Complete PWA offline access and notifications

[mathemage]

Source

Milestone 1 item: PWA access

Gap

v1.0.0 / PR #12 added minimal manifest metadata, but the milestone's PWA access requirement is not complete: there is no verified iPhone home-screen support beyond the basic manifest, no offline-capable app shell/data cache, and no push notification flow.

Current evidence:

• sleepops/src/app/manifest.ts defines basic manifest fields and a favicon icon.
• There is no service worker, offline route/app-shell cache, IndexedDB/local cache integration, or notification subscription flow in the repository.
• Repository search found no offline, service worker, push notification, or notification-permission implementation.

Scope

Finish the MVP PWA access slice without adding auth or remote database work.

Acceptance criteria

• The app has the manifest metadata and icon assets needed for installability on laptop Chrome and iPhone home screen.
• Core sleep contract state needed for the MVP is available after reload and while offline.
• The app serves an offline-capable shell for the main experience.
• Push notifications are implemented where the platform supports them and gracefully unavailable where it does not.
• Notification permission/subscription is initiated only by an explicit user action.
• Unit tests cover persistence/cache helpers where applicable.
• Playwright covers the install/offline-critical path as far as browser automation reasonably allows.

Original prompt

Implement issue #16 in mathemage/SleepOps: complete Milestone 1 PWA offline access and supported notifications.

Context:

• Read README.md, root AGENTS.md, sleepops/AGENTS.md, and the current SleepOps app before editing.
• This should be implemented after Add evening shutdown assistant #15 is merged. Wrap the stabilized sleep contract, profiler, compressor, and shutdown assistant flows instead of changing their core behavior.
• PR feat(mvp): Add SleepOps MVP sleep contract #12 added only basic manifest metadata in sleepops/src/app/manifest.ts; there is currently no service worker, offline app shell/data cache, or notification subscription flow.
• Because sleepops/AGENTS.md says this Next.js version may differ from older APIs, read the relevant docs under sleepops/node_modules/next/dist/docs/ before changing Next.js code.

Goal:
Finish the MVP PWA access slice so SleepOps is installable enough for laptop Chrome and iPhone home-screen use, keeps the core MVP available offline, and supports shutdown notifications where the platform allows them.

Requirements:

1. Do not add auth, Supabase, Prisma, or remote sync. Keep data local for this MVP milestone.
2. Add the manifest metadata and icon assets needed for practical installability on Chrome and iPhone home screen.
3. Add an offline-capable app shell for the main SleepOps experience.
4. Persist the core MVP state needed for offline use: sleep contract inputs, profiler data, compressed routine data, and shutdown assistant state where appropriate.
5. Add a small notification setup flow for shutdown reminders where supported by the browser/platform.
6. Request notification permission only from an explicit user action.
7. Gracefully explain or disable notification setup when the current browser does not support the needed APIs.
8. Keep the UI restrained and operational. Do not add a marketing-style install page.

Validation:

• Add unit tests for persistence/cache helper logic where applicable.
• Add Playwright coverage for the offline-critical path as far as browser automation reasonably allows: state survives reload, main route still renders after simulated offline/cache conditions, and notification controls behave correctly with supported/unsupported APIs mocked as needed.
• Run npm run lint, npm test, npm run build, and npm --prefix sleepops run test:e2e.

Git/GitHub:

• Create a branch from latest main after Add evening shutdown assistant #15 is merged.
• Use a commit message matching the repo convention, for example feat(pwa): Complete offline access and notifications #16.
• Open a pull request that closes Complete PWA offline access and notifications #16.
• Keep the README minimal unless a command or behavior must be documented.

[mathemage]

Executor recommendation

Use Codex with gpt-5.5 xhigh reasoning for this issue.

Reasoning

This is the highest-risk issue in the Milestone 1 remainder. It touches browser platform behavior, Next.js app behavior, service worker/offline mechanics, local persistence, and notification support differences across desktop Chrome and iPhone home-screen PWAs.

The main risks are:

• implementing offline access without destabilizing the completed sleep/profiler/compressor/shutdown flows,
• choosing the right service-worker and caching approach for the current Next.js version,
• keeping installability practical for both laptop Chrome and iPhone home screen,
• handling notification permission and unsupported-platform behavior correctly,
• testing offline and notification-critical paths in Playwright without brittle browser assumptions,
• avoiding scope creep into auth, remote sync, or database work.

Codex with gpt-5.5 xhigh is the better fit because this task needs deeper platform reasoning and careful validation. The implementation is not just code generation; it requires deciding what can be reliably supported in the MVP, what must degrade gracefully, and how to prove that with tests.

GitHub Copilot with GPT-5.4 High may be useful for smaller follow-up patches, but I would not use it as the primary executor for this issue.