suaveplan/openspec/changes/enterprise-browser-pwa/tasks.md

Tasks: enterprise-browser-pwa

Change ID: enterprise-browser-pwa Package: @suaveplan/pwa Target path: browser/platform/pwa Prerequisite packages on Verdaccio: @suaveplan/cache-browser, @suaveplan/error, @suaveplan/logger, @suaveplan/schema-registry

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create directory tree per proposal.md.
• package.json v0.0.0, "sideEffects": false.
  • dependencies: @suaveplan/cache-browser workspace:^, @suaveplan/error workspace:^, @suaveplan/types workspace:^, @suaveplan/logger workspace:^, @suaveplan/schema-registry workspace:^, zod catalog:forms, @opentelemetry/api catalog:observability, tslib catalog:build
  • devDependencies: vitest catalog:testing, @vitest/coverage-istanbul catalog:testing, happy-dom catalog:testing, @playwright/test catalog:testing, @suaveplan/testing workspace:^
  • Subpath exports: ".", "./core/service-worker/service-worker", "./core/sync-queue/sync-queue", "./core/push-notifications/push-notifications", "./core/install-prompt/install-prompt", "./core/routing/routing"
• tsconfig.json, vitest.config.ts (pool: forks, happy-dom environment, fileParallelism: false).

---

2. Error codes

• SW_REGISTRATION_FAILED, SW_UPDATE_FAILED, PUSH_PERMISSION_DENIED, PUSH_UNSUPPORTED, SYNC_QUEUE_EXCEEDED.
• registerPwaErrorCodes() — call eagerly.

---

3. Types (src/types/common.ts)

• SwState, SwRegistrationOptions, SwRegistrationResult, PushPermission, PushSubscriptionResult, PushNotificationOptions, SyncQueueConfig, SyncQueueEntry, InstallPromptState, InstallPromptListener.
• Write common.md.

---

4. SyncQueueEntry schema (src/schema/sync-queue-schema/)

• sync-queue-schema.ts — SyncQueueEntrySchema (method, URL, headers, body, metadata); registerSyncQueueSchema().
• Write sync-queue-schema.md.

---

5. SyncQueue storage backends (src/core/sync-queue/storage/)

• storage.ts — StorageBackend interface: enqueue, dequeue, getAll, clear, getDepth.
• IndexedDBSyncStorage via @suaveplan/cache-browser; LocalStorageSyncStorage fallback; MemorySyncStorage for tests.
• Write storage.test.ts. Write storage.md.

---

6. SyncQueue (src/core/sync-queue/)

• sync-queue.ts — composing StorageBackend; enqueue() validates via SyncQueueEntrySchema; throws SYNC_QUEUE_EXCEEDED over max.
• flush() with exponential backoff; background-sync hook via SyncManager where supported.
• Wire OTel metrics.
• Write sync-queue.test.ts (enqueue, flush, backoff, clear, storage-backend swap). Write sync-queue.md.

---

7. ServiceWorkerManager (src/core/service-worker/)

• service-worker.ts — register, unregister, update, skipWaiting, update-interval polling.
• Throw SW_REGISTRATION_FAILED / SW_UPDATE_FAILED on failure.
• Split tests into four files ≤ 500 lines: registration, update, lifecycle, events.
• Write service-worker.md.

---

8. PushNotificationManager (src/core/push-notifications/)

• push-notifications.ts — permission query, subscribe/unsubscribe, notify.
• Throw PUSH_PERMISSION_DENIED / PUSH_UNSUPPORTED on failure.
• Tests use real PushManager fixture via injectable adapter (no vi.stubGlobal).
• Write push-notifications.test.ts, push-notifications.md.

---

9. InstallPromptManager (src/core/install-prompt/)

• install-prompt.ts — capture beforeinstallprompt, expose prompt(), state listeners.
• Wire OTel histogram pwa.install_prompt_latency_ms.
• Write install-prompt.test.ts, install-prompt.md.

---

10. Routing DSL (src/core/routing/)

• routing.ts — swRoute(pattern, strategy), networkFirst, cacheFirst, staleWhileRevalidate.
• Strategies accept ttl, cacheName, fallback options.
• Write routing.test.ts (pattern matching, strategy selection). Write routing.md.

---

11. Integration test (tests/integration.test.ts)

• SyncQueue with MemorySyncStorage — enqueue, flush, backend swap.
• ServiceWorkerManager registration + update cycle.
• Routing DSL: register routes, simulate fetch, assert strategy applied.

---

12. Playwright E2E (e2e/pwa.spec.ts)

• Chromium, WebKit, Firefox.
• SW install → page reload → SW active.
• SW update → skipWaiting → new SW takes over.
• SyncQueue survives page reload via IndexedDB backend.
• Push subscribe/unsubscribe (no real push server needed — test the subscribe call).

---

13. Docs + verify

• Write .md per module (≥200 words, API reference, examples).
• Write README.md with IndexedDB migration guide, routing DSL reference.
• bunx turbo lint typecheck test --filter=@suaveplan/pwa — green.
• bunx turbo test:coverage — 100%.
• No @ts-expect-error in src/ or tests. No vi.stubGlobal.
• Playwright E2E green on Chromium, WebKit, Firefox.
• bun scripts/publish.ts --package @suaveplan/pwa.
• Archive to openspec/archive/2026-04-24-enterprise-browser-pwa/.