PubScript/CHUNK#11.md

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).