# CHUNK #11 — Packaging, Parity & Polish

**Duration:** ~3 days · **Prereqs:** CHUNK #10 (multi-user complete) · **Follows:** CHUNK #10 · **Unblocks:** — (final chunk)

**Purpose:** Package PubScript for every platform — Docker Compose for self-hosting, Tauri 2 native bundles for Linux/Windows/macOS — and prove web/desktop parity. Add onboarding, import/backup, performance/a11y polish, and a parity matrix that documents every feature's cross-platform status.

---

## Steps

### 1. Docker self-hosting (`docker/`)
1. **`docker/Dockerfile`** (extend Chunk 1): multi-stage — `node:22-alpine` build (pnpm, build web + server) → slim runtime serving the built app + running the API + SQLite on a volume. Non-root user. `HEALTHCHECK` → `/api/health`.
2. **`docker/compose.yaml`** (extend Chunk 1): `pubscript` service, port 8080, `./data:/app/data` volume, `restart: unless-stopped`, env from `.env`.
3. **`docker/languagetool/compose.yaml`**: optional LanguageTool sidecar (Chunk 7) — documented, not required.
4. **Backup scripts** (`docker/backup.sh`): `pg_dump`-style SQLite snapshot (`cp` the `.sqlite` file with WAL checkpoint) → timestamped `.sqlite.bak`; restore script.
5. **`docker/README.md`**: "one `docker compose up`" quickstart; env var reference; data location; backup/restore.

### 2. Tauri desktop bundles (`desktop/`)
1. **Tauri 2 config** (`desktop/tauri.conf.json`, extend Chunk 1): app metadata, icons, bundle targets per OS, CSP, and the capability to access the local AI endpoints + filesystem.
2. **Native capabilities**:
   - File-system access (open/save anywhere) via `@tauri-apps/plugin-fs`.
   - System print-to-PDF (Chunk 6 PDF backend default).
   - Local AI plumbing (detect Ollama/llama.cpp on LAN).
3. **Build matrix** (`.github/workflows/desktop.yml`):
   - **Linux**: AppImage + `.deb` + `.rpm`.
   - **Windows**: NSIS installer + portable `.zip`.
   - **macOS**: `.dmg` (arm64 + x86_64); notarization as explicit later polish.
4. **Icons**: generate per-platform icon sets (scripts in `desktop/icons/`).

### 3. Parity proof
1. **Parity matrix** (`docs/PARITY.md`): every feature × {web, desktop-local, desktop-server} with a ✓/—/⚠. Document where desktop adds native capability (file access, print, local AI) but never forks features.
2. **Contract suite** (Chunk 2) already runs Local vs. Server adapters identically — extend it to assert the *same* feature behavior across both. CI gate.
3. **Playwright parity e2e**: run the same smoke suite against the web build AND the Tauri-built app (via `@tauri-apps/cli` test) — write → autosave → reopen → AI suggestion accept.

### 4. Onboarding (`apps/web/src/features/onboarding/`)
1. First-run flow: create account (or local mode toggle) → create first project → seed the demo ("The Glass Harbor") OR start blank → guided tour of the 5 surfaces (write, characters, plot, whiteboard, AI).
2. **Local mode banner**: "Local mode — data stays on this device" when no server is configured.

### 5. Import & backup (UI)
1. **Import** (`apps/web/src/features/import/`): import a `.md` file into a project (Chunk 3); import an EPUB (parse → chapters) as a bonus.
2. **Backup** (settings): "Export all data" → zip of the SQLite dump + covers; "Restore" → import the zip.

### 6. Performance & a11y polish
1. Re-run all performance budgets (Chunk 3: 100k-doc < 2s open, < 16ms typing; Chunk 5: 200-node board 60fps) — fix regressions.
2. **a11y**: axe-core audit in CI; ensure contrast ≥ 4.5:1 in all themes, full keyboard nav, screen-reader labels on all surfaces.

### 7. Final docs
1. `README.md` (extend Chunk 1): full quickstart for web + desktop + self-host.
2. `docs/ROLE_PROMPTS.md`, `docs/DATA_MODEL.md`, `docs/EDITOR.md`, `docs/BOARDS.md`, `docs/PARITY.md` — all complete.

### 8. Tests
1. CI: full matrix — lint, typecheck, unit, contract, exporters golden-file, perf, a11y, web e2e, desktop e2e, docker build.
2. All performance + a11y budgets pass.

---

## Acceptance criteria (all must pass)
- [ ] `docker compose up` → app + API + SQLite running; `/api/health` green; app loads.
- [ ] Linux build produces AppImage + `.deb` + `.rpm`; Windows: NSIS + portable; macOS: `.dmg`.
- [ ] Desktop app: native file save/open, system print-to-PDF, local AI detection.
- [ ] Parity matrix documents every feature; contract suite + Playwright prove web/desktop parity.
- [ ] Onboarding flow guides a first-time user through all 5 surfaces.
- [ ] Import `.md`/`.epub`; backup/restore round-trips all data.
- [ ] All performance budgets pass (open, typing, board fps).
- [ ] a11y: axe-core clean, contrast ≥ 4.5:1, full keyboard nav.
- [ ] CI green end-to-end across the full matrix.

## Definition of done
PubScript ships as a self-hostable multi-user web app AND native desktop apps on three OSes, with proven parity, polished performance and accessibility, and complete docs. The full vision from PLAN.md is realized.

## Risks & fallbacks
- **Tauri cross-OS packaging friction** (esp. macOS notarization) → Linux-first; Windows as a CI matrix; macOS notarization is explicit later polish, not a v1 blocker.
- **Parity gaps slip through** → parity matrix + automated contract/playwright gates in CI make gaps visible.
- **Docker native-build issues** (better-sqlite3) → `node:22-alpine` with build tools; fall back to `node:22-slim` (documented in an ADR, Chunk 1).