Merge dev into Feature 06 branch before integration review

iOS install hint component (#56 )
Co-authored-by: dev_agent <dev_agent@cubecraftlabs.com>
2026-10-05 08:56:59 -04:00 · 2026-10-05 08:35:35 -04:00 · 2026-10-05 08:13:50 -04:00 · 2026-10-04 16:36:43 -04:00 · 2026-10-04 16:16:41 -04:00
44 changed files with 6722 additions and 696 deletions
@@ -3,8 +3,6 @@ design/.DS_Store

 # Secrets and local environment
 .env*
-!deploy/.env.example
-deploy/.env
 deploy/secrets/

 # Build artifacts and dependencies
@@ -1,80 +0,0 @@
-# MealQuest production environment. Copy to deploy/.env (never committed)
-# and replace the placeholders. The service fails fast: a missing or invalid
-# required variable stops it at boot with the variable named.
-#
-# Secrets are never set here. They live in deploy/secrets/ (never committed),
-# one value per file, owned by the container user and readable only by it:
-#
-#   mkdir -p deploy/secrets && chmod 700 deploy/secrets
-#   head -c 32 /dev/urandom | base64 > deploy/secrets/secret_key
-#   printf '%s\n' '<Authentik client secret>' > deploy/secrets/oidc_client_secret
-#   sudo chown 10001:10001 deploy/secrets/* && sudo chmod 600 deploy/secrets/*
-#
-# deploy/compose.yaml mounts them at /run/secrets/<name> and points the
-# *_FILE variables at them.
-
-# --- Compose -----------------------------------------------------------------
-
-# Host address the service is published on, as <address>:8090. Production
-# binds the LAN address 10.60.1.14 only; 127.0.0.1 suits a dev machine.
-MEALQUEST_BIND_ADDRESS=127.0.0.1
-
-# --- Service -----------------------------------------------------------------
-
-# Public origin the household opens. Fixes the OIDC redirect URI
-# (<url>/auth/callback) and the Secure cookies. Must be https:// (plain
-# http:// is accepted only for localhost, 127.0.0.1 and [::1]).
-MEALQUEST_PUBLIC_URL=https://mealquest.cubecraftlabs.com
-
-# How long a graceful shutdown may take before in-flight requests are cut.
-MEALQUEST_SHUTDOWN_TIMEOUT=10s
-
-# Optional. Comma-separated IPs/CIDRs of reverse proxies whose
-# X-Forwarded-For/-Proto headers are honoured. Production lists Traefik;
-# unset trusts no peer.
-MEALQUEST_TRUSTED_PROXY=10.60.1.33
-
-# IANA zone the household settings are created with on first boot. Required
-# until those settings exist; ignored afterwards (change the zone in
-# household settings instead). Confirm the household's zone before the first
-# deploy.
-MEALQUEST_DEFAULT_TZ=America/New_York
-
-# --- Authentik OIDC ----------------------------------------------------------
-
-# Issuer of the Authentik application "mealquest". Discovered at boot, so it
-# must be reachable from the container. Must be https://.
-MEALQUEST_OIDC_ISSUER=https://auth.cubecraftlabs.com/application/o/mealquest/
-MEALQUEST_OIDC_CLIENT_ID=mealquest
-# Comma-separated Authentik groups whose members may sign in.
-MEALQUEST_OIDC_ALLOWED_GROUPS=mealquest-admin
-
-# Optional session lifetimes. A session ends after IDLE unused and always MAX
-# after sign-in; MAX must be at least IDLE. Defaults: 720h and 4320h.
-MEALQUEST_SESSION_IDLE=720h
-MEALQUEST_SESSION_MAX=4320h
-
-# --- Set by deploy/compose.yaml; do not set here -----------------------------
-#
-# MEALQUEST_HTTP_ADDR=:8080
-# MEALQUEST_DATA_DIR=/data
-# MEALQUEST_SECRET_KEY_FILE=/run/secrets/secret_key
-#   Base64 of 32 random bytes; encrypts secrets at rest (AES-256-GCM).
-# MEALQUEST_OIDC_CLIENT_SECRET_FILE=/run/secrets/oidc_client_secret
-#   The Authentik provider's client secret.
-
-# --- Planned; not read by the service yet -------------------------------------
-#
-# Added to deploy/compose.yaml and this file by the features that use them.
-#
-# Web Push (Feature 19). Generate the key pair with cmd/vapidgen.
-# MEALQUEST_VAPID_PUBLIC_KEY=<base64url VAPID public key>
-# MEALQUEST_VAPID_PRIVATE_KEY_FILE=/run/secrets/vapid_private_key
-# MEALQUEST_VAPID_SUBJECT=mailto:<owner address>
-#
-# Google Calendar OAuth web client (Feature 16).
-# MEALQUEST_GOOGLE_CLIENT_ID=<client id>.apps.googleusercontent.com
-# MEALQUEST_GOOGLE_CLIENT_SECRET_FILE=/run/secrets/google_client_secret
-#
-# SearXNG recipe search sidecar on the compose network (Feature 07).
-# MEALQUEST_SEARXNG_URL=http://searxng:8080
@@ -1,318 +0,0 @@
-# MealQuest deployment runbook
-
-How MealQuest is deployed on office-srvr (10.60.1.14) and how its data is
-backed up and restored. Sections marked *task 876134bc* are completed by
-that task (Feature 07 deployment runbook); this file currently records the
-reverse-proxy route, the backups and the restore procedure.
-
-Paths used below:
-
-| Name | Path |
-| --- | --- |
-| Checkout on the host | `/home/overseer/mealquest` |
-| Data volume (`mealquest-data`) on the host | `/var/lib/docker/volumes/mealquest-data/_data` |
-| Same volume inside the containers | `/data` |
-| Database | `mealquest.db` (+ `mealquest.db-wal`, `mealquest.db-shm` while open) |
-| Media | `media/` in the data volume |
-| Backup target (NAS, over SSH) | `joshua@10.60.1.50:/volume1/homes/Joshua/mealquest-backups` |
-| Same target over SFTP (Synology chroot) | `/homes/Joshua/mealquest-backups` |
-
-## Stack and first deploy
-
-*Completed by task 876134bc.* The compose stack is `deploy/compose.yaml`;
-start it with `docker compose -f deploy/compose.yaml up -d --build`.
-
-## Reverse proxy (Traefik)
-
-MealQuest is published at <https://mealquest.cubecraftlabs.com> by the
-shared Traefik instance on 10.60.1.33 (Feature 07, task 0c1dc172). The
-route is a dynamic-configuration file that lives on the Traefik host only,
-at `/home/overseer/Code/traefik/config/dynamic/mealquest-ccl.yml`. Its exact
-contents:
-
-```yaml
-# MealQuest - https://mealquest.cubecraftlabs.com
-#   Feature 07 task 0c1dc172. Single Go binary (API + embedded PWA) on
-#   office-srvr 10.60.1.14:8090. HTTP -> HTTPS is handled globally by
-#   http-conf.yml, so only a websecure router is defined here.
-#   This file lives on the Traefik host only; the repo copy is recorded in
-#   deploy/RUNBOOK.md by task 876134bc.
-http:
-  routers:
-    mealquest:
-      entryPoints:
-        - websecure
-      rule: "Host(`mealquest.cubecraftlabs.com`)"
-      priority: 100
-      middlewares:
-        - mealquest-headers
-      service: mealquest
-      tls:
-        certResolver: myresolver
-        domains:
-          - main: mealquest.cubecraftlabs.com
-
-  services:
-    mealquest:
-      loadBalancer:
-        servers:
-          - url: "http://10.60.1.14:8090"
-
-  middlewares:
-    mealquest-headers:
-      headers:
-        stsSeconds: 31536000
-        stsIncludeSubdomains: true
-        contentTypeNosniff: true
-        frameDeny: true
-```
-
-## Backups
-
-### Database — Litestream
-
-The `litestream` compose service streams every committed change to
-`mealquest.db` to the NAS over SFTP (`deploy/litestream.yml`). It takes a
-full snapshot daily (compaction level 9) and keeps a week of snapshots
-plus the incremental LTX files between them.
-
-One-time setup (already done on 10.60.1.14):
-
-1. Generate the dedicated keypair, git-ignored, owned by the container
-   user:
-
-   ```sh
-   cd /home/overseer/mealquest
-   ssh-keygen -t ed25519 -N '' -C mealquest-litestream -f deploy/secrets/litestream_key
-   # append deploy/secrets/litestream_key.pub to joshua@10.60.1.50:~/.ssh/authorized_keys
-   rm deploy/secrets/litestream_key.pub
-   sudo chown 10001:10001 deploy/secrets/litestream_key
-   sudo chmod 0600 deploy/secrets/litestream_key
-   ```
-
-2. The NAS host key is pinned in `deploy/litestream.yml` (`host-key`).
-
-Check replication — list every LTX file at every level. Level 9 holds the
-full snapshots; the default listing (`-level 0`) shows only L0 files:
-
-```sh
-docker compose -f deploy/compose.yaml exec -T litestream \
-  litestream ltx -config /etc/litestream.yml -level all /data/mealquest.db
-```
-
-### Media — nightly rsync
-
-`mealquest-media-backup.timer` runs `mealquest-media-backup.service` at
-03:30 every night. The service runs `/usr/local/sbin/mealquest-media-backup`
-(`deploy/systemd/mealquest-media-backup.sh`) as the unprivileged host user
-`mealquest` (uid/gid 10001, the app's own user) with no capabilities.
-systemd bind-mounts the data volume read-only at `/run/mealquest-data` and
-passes the Litestream key in as the credential `nas_key`; uid 10001 cannot
-otherwise reach `/var/lib/docker` or `deploy/secrets/`. The script refuses a
-`media` path that is a symlink and fails (exit 1) if `media` is missing.
-
-One-time setup (already done on 10.60.1.14):
-
-```sh
-cd /home/overseer/mealquest
-# Host user for the backup; ssh needs a passwd entry for its uid.
-sudo groupadd --system --gid 10001 mealquest
-sudo useradd --system --uid 10001 --gid 10001 --no-create-home \
-  --home-dir /nonexistent --shell /usr/sbin/nologin mealquest
-# Pinned NAS host keys, root-owned and world-readable.
-sudo install -d -o root -g root -m 0755 /etc/mealquest
-sudo install -o root -g root -m 0644 deploy/known_hosts /etc/mealquest/known_hosts
-# The media directory; the backup fails if it is ever missing.
-sudo install -d -o 10001 -g 10001 -m 0755 /var/lib/docker/volumes/mealquest-data/_data/media
-# Script and units.
-sudo install -o root -g root -m 0755 deploy/systemd/mealquest-media-backup.sh /usr/local/sbin/mealquest-media-backup
-sudo install -o root -g root -m 0644 deploy/systemd/mealquest-media-backup.service \
-  deploy/systemd/mealquest-media-backup.timer /etc/systemd/system/
-sudo systemctl daemon-reload
-sudo systemctl enable --now mealquest-media-backup.timer
-```
-
-Run it by hand and read the result:
-
-```sh
-sudo systemctl start mealquest-media-backup.service
-journalctl -u mealquest-media-backup --no-pager -n 30
-```
-
-Restore media by reversing the copy into the (empty or stale) media
-directory as uid 10001:
-
-```sh
-sudo rsync -a --chown=10001:10001 \
-  -e "ssh -i deploy/secrets/litestream_key -o IdentitiesOnly=yes -o UserKnownHostsFile=/etc/mealquest/known_hosts -o StrictHostKeyChecking=yes" \
-  joshua@10.60.1.50:/volume1/homes/Joshua/mealquest-backups/media/ \
-  /var/lib/docker/volumes/mealquest-data/_data/media/
-```
-
-## Restore the database
-
-SQLite in WAL mode keeps recent commits in `mealquest.db-wal`, indexed by
-`mealquest.db-shm`. **A restored database must never sit beside an old WAL
-or shared-memory file**: on open, SQLite would replay the old WAL's pages
-onto the restored database and corrupt it or mix in state from the
-database it replaced. So all three files are moved aside together, with
-Litestream's local state directory `.mealquest.db-litestream`, before the
-restore — and the restore runs into an empty volume.
-
-Run from `/home/overseer/mealquest`:
-
-```sh
-D=/var/lib/docker/volumes/mealquest-data/_data
-A=/var/tmp/mealquest-restore-aside-$(date +%Y%m%d%H%M)
-
-# 1. Stop the whole stack (app and Litestream). Nothing may hold the
-#    database open; a clean close checkpoints the WAL into mealquest.db.
-docker compose -f deploy/compose.yaml down
-
-# 2. Move the database, its -wal and -shm files and Litestream's state
-#    aside — all of them, every time. Keep the directory until the
-#    restored stack is verified.
-sudo mkdir "$A"
-for f in mealquest.db mealquest.db-wal mealquest.db-shm .mealquest.db-litestream; do
-  if sudo test -e "$D/$f"; then sudo mv "$D/$f" "$A/"; fi
-done
-sudo ls -la "$D"   # must list only media/
-
-# 3. Restore from the NAS. --no-deps keeps the app stopped so it cannot
-#    create a fresh, empty database first.
-docker compose -f deploy/compose.yaml run --rm --no-deps litestream \
-  restore -config /etc/litestream.yml -o /data/mealquest.db /data/mealquest.db
-sudo ls -la "$D"   # mealquest.db only: no -wal, no -shm
-
-# 4. Check the restored file before starting the app (see "Count check").
-
-# 5. Start the stack and check health.
-docker compose -f deploy/compose.yaml up -d
-docker compose -f deploy/compose.yaml ps
-curl -s -o /dev/null -w "health %{http_code}\n" http://10.60.1.14:8090/health
-```
-
-To restore to a point in time, add `-timestamp 2026-10-05T23:00:00Z` (or
-`-txid`) to the `restore` command.
-
-### Count check
-
-`/tmp/mqcount.py` prints row counts for key tables, the number of
-application tables, a SHA-256 over every application row (first 16 hex
-digits; Litestream's own `_litestream*` tables are excluded) and
-`PRAGMA integrity_check`. Run it on a **copy** of the database, never on the
-live file; copy `-wal`/`-shm` along with it when the app is running.
-
-```python
-import sqlite3, sys, hashlib
-c = sqlite3.connect(sys.argv[1])
-tabs = [r[0] for r in c.execute("select name from sqlite_master where type=\"table\" and name not like \"sqlite_%\" and name not like \"_litestream%\" order by name")]
-for t in ("dinners", "week_plans", "schema_migrations"):
-    print(t, c.execute(f"select count(*) from {t}").fetchone()[0])
-h = hashlib.sha256()
-for t in tabs:
-    for row in c.execute(f"select * from \"{t}\" order by rowid"):
-        h.update(repr(row).encode())
-print("tables", len(tabs), "content-sha256", h.hexdigest()[:16])
-print("integrity", c.execute("pragma integrity_check").fetchone()[0])
-```
-
-```sh
-rm -rf /tmp/mqcheck && mkdir /tmp/mqcheck
-sudo sh -c "cp -a $D/mealquest.db* /tmp/mqcheck/" && sudo chown -R "$USER" /tmp/mqcheck
-python3 /tmp/mqcount.py /tmp/mqcheck/mealquest.db
-```
-
-Before and after must match exactly.
-
-## Restore drill record — 2026-10-05
-
-Drill on 10.60.1.14 against the live (pre-launch, empty-household)
-database, Litestream 0.5.17. Commands as in "Restore the database";
-output trimmed only of compose progress lines.
-
-Replica before the drill (`ltx -level all`; level 9 is the full snapshot):
-
-```
-level  min_txid          max_txid          size   created
-0      0000000000000003  0000000000000003  14110  2026-10-05T23:13:30Z
-1      0000000000000001  0000000000000002  14110  2026-10-05T23:12:38Z
-1      0000000000000003  0000000000000003  14110  2026-10-05T23:13:30Z
-2      0000000000000001  0000000000000002  14110  2026-10-05T23:12:38Z
-2      0000000000000003  0000000000000003  14110  2026-10-05T23:13:30Z
-3      0000000000000001  0000000000000002  14110  2026-10-05T23:12:38Z
-9      0000000000000001  0000000000000002  14110  2026-10-05T23:12:38Z
-```
-
-1. `docker compose -f deploy/compose.yaml down` — both containers stopped
-   and removed. The volume then held `mealquest.db`,
-   `.mealquest.db-litestream/` and `media/`; the clean close had
-   checkpointed and removed `-wal` and `-shm`.
-2. Before (copy of the stopped database):
-
-   ```
-   dinners 0
-   week_plans 0
-   schema_migrations 7
-   tables 26 content-sha256 836e230e16c58dc7
-   integrity ok
-   ```
-
-3. Moved aside to `/var/tmp/mealquest-restore-aside-20261005`:
-   `mealquest.db` and `.mealquest.db-litestream` (no `-wal`/`-shm` existed
-   after the clean stop; the loop moves them whenever they do). Volume
-   afterwards: `media/` only.
-4. `docker compose -f deploy/compose.yaml run --rm --no-deps litestream restore -config /etc/litestream.yml -o /data/mealquest.db /data/mealquest.db`
-   — volume afterwards: `mealquest.db` (258048 bytes) and `media/`; no
-   `-wal`, no `-shm`.
-5. After (copy of the restored file, before the app started):
-
-   ```
-   dinners 0
-   week_plans 0
-   schema_migrations 7
-   tables 26 content-sha256 836e230e16c58dc7
-   integrity ok
-   ```
-
-6. `docker compose -f deploy/compose.yaml up -d` — `mealquest-mealquest-1`
-   healthy, `mealquest-litestream-1` up; `GET /health` → `200`. Counts on a
-   copy of the running database (`mealquest.db`, `-wal`, `-shm`) were
-   identical to the above.
-7. Litestream resumed against the restored database:
-
-   ```
-   level=INFO msg="detected database behind replica" db=mealquest.db db_txid=0000000000000000 replica_txid=0000000000000003
-   level=INFO msg="fetched latest L0 file from replica" db=mealquest.db min_txid=0000000000000003 max_txid=0000000000000003
-   level=INFO msg="compaction complete" db=mealquest.db level=1 txid.min=0000000000000004 txid.max=0000000000000004 size=14110
-   ```
-
-   Replica after the drill (`ltx -level all`):
-
-   ```
-   level  min_txid          max_txid          size   created
-   0      0000000000000004  0000000000000004  14110  2026-10-05T23:27:21Z
-   1      0000000000000001  0000000000000002  14110  2026-10-05T23:12:38Z
-   1      0000000000000003  0000000000000003  14110  2026-10-05T23:13:30Z
-   1      0000000000000004  0000000000000004  14110  2026-10-05T23:27:21Z
-   2      0000000000000001  0000000000000002  14110  2026-10-05T23:12:38Z
-   2      0000000000000003  0000000000000003  14110  2026-10-05T23:13:30Z
-   3      0000000000000001  0000000000000002  14110  2026-10-05T23:12:38Z
-   9      0000000000000001  0000000000000002  14110  2026-10-05T23:12:38Z
-   ```
-
-The first drill earlier the same day (before `-level all` was recorded)
-gave the same before/after result: checksum `836e230e16c58dc7`, 26 tables,
-integrity ok.
-
-### Media backup checks — 2026-10-05
-
-`sudo systemctl start mealquest-media-backup.service` on 10.60.1.14:
-
-| Case | Result |
-| --- | --- |
-| Normal run | `Result=success`; journal: `synced /run/mealquest-data/media to joshua@10.60.1.50:/volume1/homes/Joshua/mealquest-backups/media/ as uid 10001` |
-| A test file added | `Number of regular files transferred: 1`; removing it then gave `Number of deleted files: 1 (reg: 1)` |
-| `media` replaced by a symlink to `/etc` | `Result=exit-code`, status 1; `/run/mealquest-data/media is a symlink to /etc; refusing to back it up` |
-| `media` removed | `Result=exit-code`, status 1; `media directory /run/mealquest-data/media is missing` |
-| `sudo -u mealquest` writing into the volume via `/var/lib/docker/...` | `Permission denied` — uid 10001 cannot traverse `/var/lib/docker` (mode 0710 root) |
@@ -1,95 +0,0 @@
-# Production stack for MealQuest on 10.60.1.14 (D-018). Build and start on
-# the host with:
-#
-#   docker compose -f deploy/compose.yaml up -d --build
-#
-# Configuration comes from deploy/.env (copy deploy/.env.example) and secrets
-# from deploy/secrets/; neither is committed. Compose bind-mounts file secrets
-# with their host owner and mode, so each file in deploy/secrets/ must be
-# owned by the container user 10001:10001 with mode 0600.
-name: mealquest
-
-services:
-  mealquest:
-    build:
-      context: ..
-      dockerfile: Dockerfile
-    user: "10001:10001"
-    restart: unless-stopped
-    env_file:
-      - path: .env
-        required: true
-    # Fixed by this file's container shape (listen port, volume, secret
-    # mounts); deploy/.env must not set them.
-    environment:
-      MEALQUEST_HTTP_ADDR: ":8080"
-      MEALQUEST_DATA_DIR: /data
-      MEALQUEST_SECRET_KEY_FILE: /run/secrets/secret_key
-      MEALQUEST_OIDC_CLIENT_SECRET_FILE: /run/secrets/oidc_client_secret
-    secrets:
-      - secret_key
-      - oidc_client_secret
-    volumes:
-      - mealquest-data:/data
-    ports:
-      - "${MEALQUEST_BIND_ADDRESS:?set MEALQUEST_BIND_ADDRESS in deploy/.env}:8090:8080"
-    networks:
-      - mealquest
-    healthcheck:
-      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8080/health"]
-      interval: 30s
-      timeout: 3s
-      start_period: 10s
-      retries: 3
-    security_opt:
-      - no-new-privileges:true
-    cap_drop:
-      - ALL
-
-  # Litestream streams the database to the Synology NAS over SFTP
-  # (config: deploy/litestream.yml). The SFTP private key
-  # deploy/secrets/litestream_key is a dedicated keypair, owned by
-  # 10001:10001 with mode 0600 like the other secrets.
-  #
-  # The data volume is mounted read-write on purpose: Litestream writes its
-  # tracking tables into the database and checkpoints the WAL. It runs as
-  # the app's own user (owner of the volume) with a read-only root
-  # filesystem, no privilege escalation and no Linux capabilities.
-  #
-  # Restore: follow "Restore the database" in deploy/RUNBOOK.md (stop the
-  # stack, move the database with its -wal and -shm aside, restore, check).
-  litestream:
-    image: litestream/litestream:0.5.17
-    user: "10001:10001"
-    restart: unless-stopped
-    command: ["replicate", "-config", "/etc/litestream.yml"]
-    depends_on:
-      mealquest:
-        condition: service_healthy
-    volumes:
-      - mealquest-data:/data
-      - ./litestream.yml:/etc/litestream.yml:ro
-      - ./secrets/litestream_key:/etc/litestream/sftp_key:ro
-    networks:
-      - mealquest
-    read_only: true
-    tmpfs:
-      - /tmp
-    security_opt:
-      - no-new-privileges:true
-    cap_drop:
-      - ALL
-
-secrets:
-  secret_key:
-    file: ./secrets/secret_key
-  oidc_client_secret:
-    file: ./secrets/oidc_client_secret
-
-volumes:
-  mealquest-data:
-    name: mealquest-data
-
-networks:
-  mealquest:
-    name: mealquest
@@ -1,6 +0,0 @@
-# Host keys of the Synology NAS (10.60.1.50), the backup target. Installed
-# root-owned with mode 0644 as /etc/mealquest/known_hosts and pinned by the
-# media backup (UserKnownHostsFile, StrictHostKeyChecking=yes). The ECDSA
-# key is also pinned in deploy/litestream.yml (host-key).
-10.60.1.50 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKHxIfgjavBABMRE5GW/EFY4C4gO6mo0sKbhkUW2NcAo
-10.60.1.50 ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBNujay9nYEiXuRQf4wDRDU1gp+CDvpeMdhuhC2XypIihzKGEtB654kwrUGfA2kDWAoSPGlmojeS3OIRtHPkj6GY=
@@ -1,31 +0,0 @@
-# Litestream continuous backup of the MealQuest SQLite database (Feature
-# 07). The ``litestream`` compose service mounts the same named volume as
-# the app and streams every committed change to the Synology NAS over
-# SFTP, so the backup lives outside the Docker host.
-#
-# Nothing here is secret. The SFTP private key is a dedicated, git-ignored
-# keypair (deploy/secrets/litestream_key) mounted read-only by compose at
-# /etc/litestream/sftp_key; its public half is in
-# joshua@10.60.1.50:~/.ssh/authorized_keys. ``host-key`` pins the NAS's
-# ECDSA host key, the algorithm Litestream's SSH client negotiates with
-# this NAS.
-#
-# The Synology SFTP server is chrooted to the shared folders, so the
-# directory seen over SSH as /volume1/homes/Joshua/mealquest-backups is
-# /homes/Joshua/mealquest-backups over SFTP.
-
-# Take a full snapshot daily and keep a week of snapshots plus the
-# incremental changes between them (point-in-time restore window).
-snapshot:
-  interval: 24h
-  retention: 168h
-
-dbs:
-  - path: /data/mealquest.db
-    replicas:
-      - type: sftp
-        host: 10.60.1.50
-        user: joshua
-        path: /homes/Joshua/mealquest-backups
-        key-path: /etc/litestream/sftp_key
-        host-key: ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBNujay9nYEiXuRQf4wDRDU1gp+CDvpeMdhuhC2XypIihzKGEtB654kwrUGfA2kDWAoSPGlmojeS3OIRtHPkj6GY=
@@ -1,22 +0,0 @@
-# Applies the MealQuest DOCKER-USER rules (/usr/local/sbin/mealquest-firewall).
-#
-# PartOf= re-runs this unit whenever docker.service is stopped or restarted,
-# and WantedBy=docker.service starts it whenever docker.service starts. Both
-# are one-way: a failure here fails this unit visibly and never fails
-# docker.service.
-#
-# Start MealQuest only after this unit has succeeded:
-#   systemctl start mealquest-firewall && docker compose up -d
-[Unit]
-Description=Restrict MealQuest port 8090 to Traefik (DOCKER-USER)
-After=docker.service
-Requires=docker.service
-PartOf=docker.service
-
-[Service]
-Type=oneshot
-RemainAfterExit=yes
-ExecStart=/usr/local/sbin/mealquest-firewall
-
-[Install]
-WantedBy=multi-user.target docker.service
@@ -1,29 +0,0 @@
-#!/bin/sh
-# Restrict the MealQuest published host port (10.60.1.14:8090) to Traefik
-# (10.60.1.33) and the Docker host itself (10.60.1.14); drop every other
-# source.
-#
-# DOCKER-USER runs after Docker's DNAT, so the destination there is the
-# container address and port, not the published ones. Match the original
-# destination address and port with conntrack instead of -d/--dport.
-#
-# The rules must sit at the top of DOCKER-USER, ahead of any other project's
-# rules (an earlier RETURN or DROP would decide MealQuest traffic first).
-# Every run deletes all rules tagged with the mealquest-firewall comment and
-# re-inserts them at positions 1-3, so re-runs leave the same ordered rules
-# and no duplicates. Installed as /usr/local/sbin/mealquest-firewall.
-set -eu
-
-tag="-m comment --comment mealquest-firewall"
-match="-m conntrack --ctorigdst 10.60.1.14 --ctorigdstport 8090 --ctdir ORIGINAL"
-
-rules=$(iptables -w -S DOCKER-USER)
-printf '%s\n' "$rules" | while read -r _ chain spec; do
-	case " $spec " in
-	*" --comment mealquest-firewall "*) iptables -w -D "$chain" $spec ;;
-	esac
-done
-
-iptables -w -I DOCKER-USER 1 -s 10.60.1.33/32 $match $tag -j RETURN
-iptables -w -I DOCKER-USER 2 -s 10.60.1.14/32 $match $tag -j RETURN
-iptables -w -I DOCKER-USER 3 $match $tag -j DROP
@@ -1,29 +0,0 @@
-# Runs the nightly MealQuest media backup (/usr/local/sbin/mealquest-media-backup).
-# Triggered by mealquest-media-backup.timer; run by hand with
-#   systemctl start mealquest-media-backup
-# and read the result with
-#   journalctl -u mealquest-media-backup
-#
-# The script runs as the app's user (10001, host user "mealquest") with no
-# capabilities. systemd, as root, only bind-mounts the data volume's root
-# (a root-owned path the app cannot replace) read-only at
-# /run/mealquest-data and copies the NAS key into the credentials directory.
-[Unit]
-Description=Back up MealQuest media to the Synology NAS
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-Type=oneshot
-ExecStart=/usr/local/sbin/mealquest-media-backup
-User=mealquest
-Group=mealquest
-LoadCredential=nas_key:/home/overseer/mealquest/deploy/secrets/litestream_key
-BindReadOnlyPaths=/var/lib/docker/volumes/mealquest-data/_data:/run/mealquest-data
-ProtectSystem=strict
-ProtectHome=yes
-PrivateTmp=yes
-PrivateDevices=yes
-NoNewPrivileges=yes
-CapabilityBoundingSet=
-RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
@@ -1,44 +0,0 @@
-#!/bin/sh
-# Nightly copy of the MealQuest media directory (recipe and dinner photos)
-# to the Synology NAS. The database itself is replicated continuously by
-# Litestream; this covers the files beside it.
-#
-# Runs as the unprivileged app user (10001, host user "mealquest"), never
-# root: mealquest-media-backup.service bind-mounts the data volume
-# read-only at /run/mealquest-data and hands the NAS key in as a systemd
-# credential. Anything the app could plant in the volume is therefore read
-# with the app's own permissions only.
-#
-# The script changes into the media directory and checks that the physical
-# path is the expected one, so a media path that is a symlink is refused.
-# rsync then copies "./" — the directory the shell is already in — so
-# swapping the path afterwards cannot redirect it. Symlinks inside the
-# directory are copied as links (-a), never followed.
-#
-# The media directory is created at deploy time (deploy/RUNBOOK.md). If it
-# is missing the job fails; it is never treated as "nothing to back up".
-#
-# rsync mirrors into .../mealquest-backups/media/ only: the target ends in
-# a slash, so --delete removes files from that directory and nothing
-# outside it. Re-runs transfer only what changed. Output goes to the
-# journal via mealquest-media-backup.service.
-set -eu
-
-src=/run/mealquest-data/media
-dest=joshua@10.60.1.50:/volume1/homes/Joshua/mealquest-backups/media/
-key=$CREDENTIALS_DIRECTORY/nas_key
-known_hosts=/etc/mealquest/known_hosts
-
-if ! cd "$src"; then
-	echo "mealquest-media-backup: media directory $src is missing" >&2
-	exit 1
-fi
-if [ "$(pwd -P)" != "$src" ]; then
-	echo "mealquest-media-backup: $src is a symlink to $(pwd -P); refusing to back it up" >&2
-	exit 1
-fi
-
-rsync -a --delete --stats \
-	-e "ssh -F none -i $key -o IdentitiesOnly=yes -o BatchMode=yes -o UserKnownHostsFile=$known_hosts -o GlobalKnownHostsFile=/dev/null -o StrictHostKeyChecking=yes" \
-	./ "$dest"
-echo "mealquest-media-backup: synced $src to $dest as uid $(id -u)"
@@ -1,11 +0,0 @@
-# Nightly trigger for mealquest-media-backup.service. Persistent= runs a
-# missed backup at the next boot.
-[Unit]
-Description=Nightly MealQuest media backup
-
-[Timer]
-OnCalendar=*-*-* 03:30:00
-Persistent=true
-
-[Install]
-WantedBy=timers.target
@@ -3,6 +3,8 @@
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#5a358c" />
+    <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
    <title>MealQuest</title>
  </head>
  <body>
@@ -0,0 +1,19 @@
+{
+  "name": "MealQuest",
+  "short_name": "MealQuest",
+  "start_url": "/",
+  "scope": "/",
+  "display": "standalone",
+  "theme_color": "#5a358c",
+  "background_color": "#f9f6f1",
+  "icons": [
+    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
+    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" },
+    {
+      "src": "/icons/icon-maskable-512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "maskable"
+    }
+  ]
+}
@@ -5,9 +5,9 @@
  "type": "module",
  "scripts": {
    "dev": "vite",
-    "build": "npm run lint:colors && tsc --noEmit && vite build && npm run check:dist-fonts",
+    "build": "npm run lint:colors && npm run typecheck && vite build && npm run check:dist-fonts",
    "preview": "vite preview",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.sw.json",
    "test": "npm run lint:colors && vitest run",
    "lint:colors": "node scripts/lint-colors.mjs",
    "check:dist-fonts": "node scripts/check-dist-fonts.mjs"
@@ -29,6 +29,7 @@
    "jsdom": "^30.1.1",
    "typescript": "^7.0.2",
    "vite": "^8.3.2",
+    "vite-plugin-pwa": "^2.0.0",
    "vitest": "^5.0.3"
  }
 }
@@ -0,0 +1,59 @@
+"""Generates the PWA icons in web/public from the MealQuest logo.
+
+Run from the repository root with Pillow installed:
+
+    python3 web/scripts/generate-icons.py
+
+The logo fills the regular icons edge to edge. The maskable icon shrinks it
+onto the colour of its own parchment, so the banner stays inside
+the circular safe zone (radius 40% of the icon) that launchers may crop to.
+"""
+
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFilter, ImageStat
+
+ROOT = Path(__file__).resolve().parents[2]
+SOURCE = ROOT / "design" / "logos" / "logo_v1_2Oct2026.jpg"
+PUBLIC = ROOT / "web" / "public"
+
+MASKABLE_SCALE = 0.66
+
+
+def resized(logo: Image.Image, size: int) -> Image.Image:
+    return logo.resize((size, size), Image.Resampling.LANCZOS)
+
+
+def maskable(logo: Image.Image, size: int) -> Image.Image:
+    # The padding is the median colour of the logo's top edge, which is bare
+    # parchment; a feathered edge hides the seam.
+    top_edge = ImageStat.Stat(logo.crop((0, 0, logo.width, logo.height // 40)))
+    canvas = Image.new("RGB", (size, size), tuple(round(c) for c in top_edge.median))
+    inner = round(size * MASKABLE_SCALE)
+    offset = (size - inner) // 2
+    feather = Image.new("L", (inner, inner), 0)
+    margin = inner // 24
+    ImageDraw.Draw(feather).rectangle((margin, margin, inner - margin, inner - margin), fill=255)
+    feather = feather.filter(ImageFilter.GaussianBlur(margin / 2))
+    canvas.paste(resized(logo, inner), (offset, offset), feather)
+    return canvas
+
+
+def main() -> None:
+    logo = Image.open(SOURCE).convert("RGB")
+    if logo.width != logo.height:
+        raise SystemExit(f"{SOURCE} is {logo.width}x{logo.height}; the logo must be square")
+    outputs = {
+        PUBLIC / "icons" / "icon-192.png": resized(logo, 192),
+        PUBLIC / "icons" / "icon-512.png": resized(logo, 512),
+        PUBLIC / "icons" / "icon-maskable-512.png": maskable(logo, 512),
+        PUBLIC / "apple-touch-icon.png": resized(logo, 180),
+    }
+    for path, image in outputs.items():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        image.save(path, optimize=True)
+        print(f"wrote {path.relative_to(ROOT)} ({image.width}x{image.height})")
+
+
+if __name__ == "__main__":
+    main()
@@ -2,6 +2,7 @@ import { render, screen } from '@testing-library/react'
 import { MemoryRouter } from 'react-router'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { createApiClient } from './api/index.ts'
+import { createNetworkStatus } from './pwa/networkStatus.ts'
 import { mockViewport } from './test/matchMedia.ts'
 import { errorResponse, fakeLocation, jsonResponse, ME, request, stubFetch } from './test/fetchStub.ts'
 import App, { routes } from './App.tsx'
@@ -14,7 +15,7 @@ afterEach(() => {
 function renderAt(path: string, location = fakeLocation(path)) {
  render(
    <MemoryRouter initialEntries={[path]}>
-      <App api={createApiClient(location)} />
+      <App api={createApiClient(location, createNetworkStatus(window))} serviceWorker={undefined} />
    </MemoryRouter>,
  )
  return location
@@ -4,6 +4,8 @@ import { Route, Routes } from 'react-router'
 import { ApiProvider, createQueryClient, type ApiClient } from './api/index.ts'
 import { AuthBootstrap } from './AuthBootstrap.tsx'
 import { PlaceholderPage } from './pages/PlaceholderPage.tsx'
+import { OfflinePill } from './pwa/OfflinePill.tsx'
+import { UpdatePrompt, type UpdateContainer } from './pwa/UpdatePrompt.tsx'
 import { AppShell } from './shell/AppShell.tsx'

 // Every route the app serves, with the heading its placeholder page shows.
@@ -40,11 +42,17 @@ export function AppRoutes() {

 export type AppProps = {
  api: ApiClient
+  // navigator.serviceWorker, or undefined where there is none (and in tests).
+  serviceWorker: UpdateContainer | undefined
+}
+
+function reloadPage() {
+  window.location.reload()
 }

 // App expects to be rendered inside a router (BrowserRouter in main.tsx,
 // MemoryRouter in tests).
-export default function App({ api }: AppProps) {
+export default function App({ api, serviceWorker }: AppProps) {
  const [queryClient] = useState(createQueryClient)
  return (
    <ApiProvider client={api}>
@@ -52,6 +60,8 @@ export default function App({ api }: AppProps) {
        <AuthBootstrap>
          <AppRoutes />
        </AuthBootstrap>
+        <OfflinePill />
+        <UpdatePrompt container={serviceWorker} reload={reloadPage} />
      </QueryClientProvider>
    </ApiProvider>
  )
@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { errorResponse, fakeLocation, jsonResponse, ME, request, stubFetch } from '../test/fetchStub.ts'
 import { ApiError, createApiClient, CSRF_HEADER } from './index.ts'
+import { createNetworkStatus } from '../pwa/networkStatus.ts'

 afterEach(() => {
  vi.unstubAllGlobals()
@@ -9,7 +10,7 @@ afterEach(() => {
 describe('apiFetch', () => {
  it('sends same-origin JSON and the cached CSRF token on non-GET requests only', async () => {
    const fetchMock = stubFetch(jsonResponse(200, ME), jsonResponse(200, { ok: 1 }), jsonResponse(200, { ok: 2 }))
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window))
    await api.loadMe()

    await expect(api.apiFetch('/api/v1/settings/household')).resolves.toEqual({ ok: 1 })
@@ -29,7 +30,7 @@ describe('apiFetch', () => {

  it('refuses a non-GET request before /me has loaded', async () => {
    const fetchMock = stubFetch()
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window))
    await expect(api.apiFetch('/api/v1/jobs', { method: 'POST', body: {} })).rejects.toThrow(/no CSRF token/)
    expect(fetchMock).not.toHaveBeenCalled()
  })
@@ -47,7 +48,7 @@ describe('apiFetch', () => {
    'api/v1/me',
  ])('refuses %s without sending it or the CSRF token', async (path) => {
    const fetchMock = stubFetch(jsonResponse(200, ME))
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window))
    await api.loadMe()

    await expect(api.apiFetch(path, { method: 'POST', body: {} })).rejects.toThrow(
@@ -60,7 +61,7 @@ describe('apiFetch', () => {

  it('rejects with a typed ApiError from the error body', async () => {
    stubFetch(errorResponse(503, 'unavailable', true))
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window))
    const error = await api.apiFetch('/api/v1/jobs/j1').catch((e: unknown) => e)
    expect(error).toBeInstanceOf(ApiError)
    expect(error).toMatchObject({ status: 503, code: 'unavailable', message: 'unavailable message', retryable: true })
@@ -68,14 +69,14 @@ describe('apiFetch', () => {

  it('rejects a response without the API error body', async () => {
    stubFetch(new Response('<html>bad gateway</html>', { status: 502 }))
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window))
    await expect(api.apiFetch('/api/v1/jobs/j1')).rejects.toThrow('GET /api/v1/jobs/j1: 502 response is not JSON')
  })

  it('on 401 navigates to sign-in with the current path and search to return to', async () => {
    stubFetch(errorResponse(401, 'unauthenticated'))
    const location = fakeLocation('/plan/shopping', '?week=2026-10-05')
-    const api = createApiClient(location)
+    const api = createApiClient(location, createNetworkStatus(window))

    await expect(api.apiFetch('/api/v1/settings/household')).rejects.toMatchObject({ status: 401 })
    expect(location.assign).toHaveBeenCalledExactlyOnceWith(
@@ -90,7 +91,7 @@ describe('apiFetch', () => {
      jsonResponse(200, { ...ME, csrfToken: 'token-2' }),
      jsonResponse(201, { id: 'j1' }),
    )
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window))
    await api.loadMe()

    await expect(api.apiFetch('/api/v1/jobs', { method: 'POST', body: { kind: 'noop' } })).resolves.toEqual({
@@ -111,7 +112,7 @@ describe('apiFetch', () => {
      jsonResponse(200, { ...ME, csrfToken: 'token-2' }),
      errorResponse(403, 'csrf'),
    )
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window))
    await api.loadMe()

    await expect(api.apiFetch('/api/v1/jobs', { method: 'POST', body: {} })).rejects.toMatchObject({
@@ -124,7 +125,7 @@ describe('apiFetch', () => {

  it('marks any other 403 as not in this household and notifies subscribers', async () => {
    const fetchMock = stubFetch(errorResponse(403, 'forbidden'))
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window))
    const listener = vi.fn()
    api.subscribe(listener)

@@ -136,14 +137,14 @@ describe('apiFetch', () => {

  it('does not take a 403 without the API error body as not in this household', async () => {
    stubFetch(new Response('<html>denied by proxy</html>', { status: 403 }))
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window))
    await expect(api.apiFetch('/api/v1/me')).rejects.toThrow('GET /api/v1/me: 403 response is not JSON')
    expect(api.forbidden()).toBe(false)
  })

  it('does not refresh /me for a csrf 403 on a GET, which carries no token', async () => {
    const fetchMock = stubFetch(errorResponse(403, 'csrf'))
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window))
    await expect(api.loadMe()).rejects.toMatchObject({ status: 403, code: 'csrf' })
    expect(fetchMock).toHaveBeenCalledTimes(1)
  })
@@ -152,7 +153,7 @@ describe('apiFetch', () => {
 describe('loadMe', () => {
  it('rejects a /me response without a CSRF token', async () => {
    stubFetch(jsonResponse(200, { ...ME, csrfToken: '' }))
-    const api = createApiClient(fakeLocation())
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window))
    await expect(api.loadMe()).rejects.toThrow('response is not a member with a CSRF token')
  })
 })
@@ -1,3 +1,4 @@
+import type { NetworkStatus } from '../pwa/networkStatus.ts'
 import { ApiError, isRecord, parseApiError } from './errors.ts'

 // CSRF_HEADER carries the session's CSRF token on every non-GET request.
@@ -36,7 +37,7 @@ export type ApiLocation = Pick<Location, 'origin' | 'pathname' | 'search' | 'ass

 export type ApiRequest = {
  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
-  // Sent as JSON.
+  // Sent as JSON. A GET must not have one.
  body?: unknown
 }

@@ -51,11 +52,14 @@ export type ApiClient = {
  // account is not in this household; subscribe is notified when it changes.
  forbidden(): boolean
  subscribe(listener: () => void): () => void
+  // network learns of every request that failed with a network error and of
+  // every request that got a response.
+  network: NetworkStatus
 }

 // createApiClient builds the app's API client. location is window.location in
 // the app: a 401 sends it to /auth/login with the current path to return to.
-export function createApiClient(location: ApiLocation): ApiClient {
+export function createApiClient(location: ApiLocation, network: NetworkStatus): ApiClient {
  let csrfToken: string | null = null
  let refreshing: Promise<Me> | null = null
  let forbidden = false
@@ -70,12 +74,25 @@ export function createApiClient(location: ApiLocation): ApiClient {
      }
      headers[CSRF_HEADER] = csrfToken
    }
-    return fetch(path, {
-      method,
-      headers,
-      credentials: 'same-origin',
-      body: body === undefined ? undefined : JSON.stringify(body),
-    })
+    // Serialize before fetching so a body that cannot be sent is its own error
+    // and never counts as a network failure.
+    let json: string | undefined
+    try {
+      json = body === undefined ? undefined : JSON.stringify(body)
+    } catch (error) {
+      throw new Error(`${method} ${path}: request body is not serializable as JSON`, { cause: error })
+    }
+    let response: Response
+    try {
+      response = await fetch(path, { method, headers, credentials: 'same-origin', body: json })
+    } catch (error) {
+      // fetch rejects with a TypeError when the network fails; an abort is a
+      // DOMException and says nothing about the network.
+      if (error instanceof TypeError) network.requestFailed()
+      throw error
+    }
+    network.requestSucceeded()
+    return response
  }

  // refreshMe shares one in-flight /me request between every request that
@@ -90,6 +107,11 @@ export function createApiClient(location: ApiLocation): ApiClient {
  async function apiFetch<T>(path: string, request: ApiRequest = {}): Promise<T> {
    const method = request.method ?? 'GET'
    const url = apiURL(location.origin, method, path)
+    // fetch refuses a GET with a body by rejecting with a TypeError, the same
+    // error as a network failure, so refuse it here before anything is sent.
+    if (method === 'GET' && request.body !== undefined) {
+      throw new Error(`GET ${path}: a GET request cannot carry a body`)
+    }
    let response = await send(method, url, request.body)
    if (response.status === 403) {
      const error = await parseForbidden(method, path, response)
@@ -151,5 +173,6 @@ export function createApiClient(location: ApiLocation): ApiClient {
      listeners.add(listener)
      return () => listeners.delete(listener)
    },
+    network,
  }
 }
@@ -3,6 +3,7 @@ import type { ReactNode } from 'react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { errorResponse, fakeLocation, jsonResponse, request, stubFetch } from '../test/fetchStub.ts'
 import { ApiProvider, createApiClient, useJob } from './index.ts'
+import { createNetworkStatus } from '../pwa/networkStatus.ts'

 type Draft = { dinners: string[] }

@@ -11,7 +12,7 @@ function job(status: string, result: Draft | null, error: string | null = null)
 }

 function renderJob(jobId: string | null) {
-  const api = createApiClient(fakeLocation())
+  const api = createApiClient(fakeLocation(), createNetworkStatus(window))
  const wrapper = ({ children }: { children: ReactNode }) => <ApiProvider client={api}>{children}</ApiProvider>
  return renderHook(({ id }) => useJob<Draft>(id), { wrapper, initialProps: { id: jobId } })
 }
@@ -5,18 +5,19 @@ import './styles/tokens.css'
 import './styles/base.css'
 import App from './App.tsx'
 import { createApiClient } from './api/index.ts'
+import { createNetworkStatus } from './pwa/networkStatus.ts'

 const root = document.getElementById('root')
 if (!root) {
  throw new Error('MealQuest: #root element missing from index.html')
 }

-const api = createApiClient(window.location)
+const api = createApiClient(window.location, createNetworkStatus(window))

 createRoot(root).render(
  <StrictMode>
    <BrowserRouter>
-      <App api={api} />
+      <App api={api} serviceWorker={'serviceWorker' in navigator ? navigator.serviceWorker : undefined} />
    </BrowserRouter>
  </StrictMode>,
 )
@@ -0,0 +1,157 @@
+// @vitest-environment node
+// Builds the app with the production config and serves the result, so the
+// assertions cover what ships in dist: the web manifest, the service worker,
+// every icon, and the service worker registration that only builds include.
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { build, createServer, preview, type PreviewServer, type ViteDevServer } from 'vite'
+import tokens from './styles/tokens.css?raw'
+
+const outDir = 'node_modules/.tmp/pwa-test-dist'
+
+const icons = [
+  { path: '/icons/icon-192.png', size: 192 },
+  { path: '/icons/icon-512.png', size: 512 },
+  { path: '/icons/icon-maskable-512.png', size: 512 },
+  { path: '/apple-touch-icon.png', size: 180 },
+]
+
+function token(name: string): string {
+  const value = tokens.match(new RegExp(`^\\s*${name}:\\s*([^;\\s]+);`, 'm'))?.[1]
+  if (!value) throw new Error(`${name} is not defined in tokens.css`)
+  return value
+}
+
+// Width and height from a PNG's IHDR chunk, which follows the 8-byte
+// signature, the chunk length and the chunk type.
+// The precache list vite-plugin-pwa injects into sw.js: a JSON array of
+// { revision, url } entries.
+function precacheEntries(sw: string): Array<{ revision: string | null; url: string }> {
+  const start = sw.indexOf('[{"revision":')
+  expect(start, 'injected precache list').toBeGreaterThanOrEqual(0)
+  return JSON.parse(sw.slice(start, sw.indexOf('}]', start) + 2))
+}
+
+function pngSize(bytes: Uint8Array): { width: number; height: number } {
+  const signature = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
+  expect(Array.from(bytes.subarray(0, 8))).toEqual(signature)
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  return { width: view.getUint32(16), height: view.getUint32(20) }
+}
+
+describe('production build', () => {
+  let server: PreviewServer
+  let origin: string
+
+  async function get(path: string): Promise<Response> {
+    const response = await fetch(new URL(path, origin))
+    expect(response.status, path).toBe(200)
+    return response
+  }
+
+  beforeAll(async () => {
+    await build({ logLevel: 'error', build: { outDir, emptyOutDir: true } })
+    server = await preview({
+      logLevel: 'error',
+      build: { outDir },
+      preview: { port: 0, strictPort: false, host: '127.0.0.1' },
+    })
+    const url = server.resolvedUrls?.local[0]
+    if (!url) throw new Error('preview server did not report a URL')
+    origin = url
+  }, 60_000)
+
+  afterAll(async () => {
+    await server?.close()
+  })
+
+  it('emits manifest.webmanifest with the MealQuest identity', async () => {
+    const manifest = await (await get('/manifest.webmanifest')).json()
+    expect(manifest).toMatchObject({
+      name: 'MealQuest',
+      short_name: 'MealQuest',
+      start_url: '/',
+      scope: '/',
+      display: 'standalone',
+      // --color-accent and --color-bg hold the manifest colours; hex colours
+      // may not be written outside tokens.css.
+      theme_color: token('--color-accent'),
+      background_color: token('--color-bg'),
+    })
+    expect(manifest.icons).toEqual([
+      { src: '/icons/icon-192.png', sizes: '192x192', type: 'image/png', purpose: 'any' },
+      { src: '/icons/icon-512.png', sizes: '512x512', type: 'image/png', purpose: 'any' },
+      {
+        src: '/icons/icon-maskable-512.png',
+        sizes: '512x512',
+        type: 'image/png',
+        purpose: 'maskable',
+      },
+    ])
+  })
+
+  it.each(icons)('ships $path as a $size px square PNG', async ({ path, size }) => {
+    const bytes = new Uint8Array(await (await get(path)).arrayBuffer())
+    expect(pngSize(bytes)).toEqual({ width: size, height: size })
+  })
+
+  it('emits sw.js with the precache list injected', async () => {
+    const sw = await (await get('/sw.js')).text()
+    expect(sw).not.toContain('self.__WB_MANIFEST')
+    expect(sw).toContain('"url":"index.html"')
+    for (const { path } of icons.slice(0, 3)) {
+      expect(sw).toContain(`"url":"${path.slice(1)}"`)
+    }
+  })
+
+  it('precaches the shell, JS, CSS and every self-hosted font', async () => {
+    const entries = precacheEntries(await (await get('/sw.js')).text())
+    const urls = entries.map((entry) => entry.url)
+    // index.html keeps its URL across builds, so it carries a content
+    // revision; the other assets have content hashes in their names.
+    expect(entries.find((entry) => entry.url === 'index.html')?.revision).toMatch(/^[0-9a-f]{32}$/)
+    expect(urls.some((url) => url.endsWith('.js'))).toBe(true)
+    expect(urls.some((url) => url.endsWith('.css'))).toBe(true)
+    for (const font of [
+      'BagelFatOne-LatinExt',
+      'BagelFatOne-Latin',
+      'Figtree-Regular',
+      'Figtree-SemiBold',
+      'Figtree-Bold',
+    ]) {
+      expect(urls.some((url) => url.startsWith(`assets/${font}`) && url.endsWith('.woff2'))).toBe(true)
+    }
+  })
+
+  it('links the manifest, theme colour and apple-touch-icon from index.html', async () => {
+    const html = await (await get('/')).text()
+    expect(html.match(/<link rel="manifest" href="\/manifest\.webmanifest">/g)).toHaveLength(1)
+    expect(html).toContain(`<meta name="theme-color" content="${token('--color-accent')}" />`)
+    expect(html).toContain('<link rel="apple-touch-icon" href="/apple-touch-icon.png" />')
+  })
+
+  it('registers /sw.js at scope / from index.html', async () => {
+    const html = await (await get('/')).text()
+    expect(html).toContain('<script id="vite-plugin-pwa:register-sw" src="/registerSW.js"></script>')
+    const register = await (await get('/registerSW.js')).text()
+    expect(register).toContain("navigator.serviceWorker.register('/sw.js', { scope: '/' })")
+  })
+})
+
+describe('dev server', () => {
+  let server: ViteDevServer
+
+  beforeAll(async () => {
+    server = await createServer({ logLevel: 'error', server: { middlewareMode: true } })
+  })
+
+  afterAll(async () => {
+    await server?.close()
+  })
+
+  it('does not register a service worker', async () => {
+    const html = await server.transformIndexHtml('/', '<html><head></head><body></body></html>')
+    expect(html).not.toContain('registerSW')
+    expect(html).not.toContain('serviceWorker')
+    expect(html).not.toContain('rel="manifest"')
+  })
+})
@@ -0,0 +1,18 @@
+.hint {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+}
+
+.icon {
+  color: var(--color-accent);
+}
+
+.message {
+  flex: 1;
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 15px;
+  font-weight: 600;
+  line-height: 1.35;
+}
@@ -0,0 +1,146 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { DISMISSED_KEY, InstallHint } from './InstallHint.tsx'
+
+const IPHONE_SAFARI =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.5 Mobile/15E148 Safari/604.1'
+const IPAD_SAFARI =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.5 Safari/605.1.15'
+const MAC_SAFARI = IPAD_SAFARI
+const IPHONE_CHROME =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/138.0.7204.119 Mobile/15E148 Safari/604.1'
+const IPHONE_FIREFOX =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) FxiOS/141.0 Mobile/15E148 Safari/605.1.15'
+const IPHONE_EDGE =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 EdgiOS/138.3351.83 Mobile/15E148 Safari/605.1.15'
+const IPHONE_OPERA =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1 OPT/5.4.0'
+const IPHONE_MQQBROWSER =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 MQQBrowser/11.3.5 Mobile/15E148 Safari/604.1'
+const ANDROID_CHROME =
+  'Mozilla/5.0 (Linux; Android 15; Pixel 9) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Mobile Safari/537.36'
+const DESKTOP_CHROME =
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36'
+
+const copy = 'Tap Share, then Add to Home Screen to get notifications'
+
+type Device = {
+  userAgent: string
+  maxTouchPoints?: number
+  // display-mode: standalone
+  displayStandalone?: boolean
+  // navigator.standalone (Safari only; undefined elsewhere)
+  navigatorStandalone?: boolean
+}
+
+// mockDevice pretends to be a browser with the given user agent and
+// display mode; jsdom has no matchMedia, navigator.maxTouchPoints or
+// navigator.standalone.
+function mockDevice({ userAgent, maxTouchPoints = 0, displayStandalone = false, navigatorStandalone }: Device) {
+  vi.spyOn(navigator, 'userAgent', 'get').mockReturnValue(userAgent)
+  Object.defineProperty(navigator, 'maxTouchPoints', { configurable: true, value: maxTouchPoints })
+  Object.defineProperty(navigator, 'standalone', { configurable: true, value: navigatorStandalone })
+  vi.stubGlobal('matchMedia', (query: string) => {
+    if (query !== '(display-mode: standalone)') throw new Error(`unexpected media query ${query}`)
+    return { matches: displayStandalone, media: query } as MediaQueryList
+  })
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+  Reflect.deleteProperty(navigator, 'maxTouchPoints')
+  Reflect.deleteProperty(navigator, 'standalone')
+  localStorage.clear()
+})
+
+describe('InstallHint', () => {
+  it('shows on iPhone Safari in a browser tab', () => {
+    mockDevice({ userAgent: IPHONE_SAFARI, maxTouchPoints: 5, navigatorStandalone: false })
+    render(<InstallHint />)
+    expect(screen.getByRole('note')).toHaveTextContent(copy)
+  })
+
+  it('shows on iPadOS Safari, which reports itself as a Mac with a touch screen', () => {
+    mockDevice({ userAgent: IPAD_SAFARI, maxTouchPoints: 5, navigatorStandalone: false })
+    render(<InstallHint />)
+    expect(screen.getByRole('note')).toHaveTextContent(copy)
+  })
+
+  it('is hidden when navigator.standalone is true', () => {
+    mockDevice({ userAgent: IPHONE_SAFARI, maxTouchPoints: 5, navigatorStandalone: true })
+    render(<InstallHint />)
+    expect(screen.queryByRole('note')).toBeNull()
+  })
+
+  it('is hidden when display-mode is standalone', () => {
+    mockDevice({ userAgent: IPHONE_SAFARI, maxTouchPoints: 5, displayStandalone: true })
+    render(<InstallHint />)
+    expect(screen.queryByRole('note')).toBeNull()
+  })
+
+  it.each([
+    ['Android Chrome', { userAgent: ANDROID_CHROME, maxTouchPoints: 5 }],
+    ['desktop Chrome', { userAgent: DESKTOP_CHROME }],
+    ['desktop Safari on a Mac', { userAgent: MAC_SAFARI }],
+    ['Chrome on iPhone', { userAgent: IPHONE_CHROME, maxTouchPoints: 5 }],
+    ['Firefox on iPhone', { userAgent: IPHONE_FIREFOX, maxTouchPoints: 5 }],
+    ['Edge on iPhone', { userAgent: IPHONE_EDGE, maxTouchPoints: 5 }],
+    ['Opera on iPhone', { userAgent: IPHONE_OPERA, maxTouchPoints: 5 }],
+    ['MQQBrowser on iPhone', { userAgent: IPHONE_MQQBROWSER, maxTouchPoints: 5 }],
+  ])('is hidden on %s', (_name, device: Device) => {
+    mockDevice(device)
+    render(<InstallHint />)
+    expect(screen.queryByRole('note')).toBeNull()
+  })
+
+  it('stays dismissed on this device', () => {
+    mockDevice({ userAgent: IPHONE_SAFARI, maxTouchPoints: 5, navigatorStandalone: false })
+    const first = render(<InstallHint />)
+    fireEvent.click(screen.getByRole('button', { name: 'Dismiss' }))
+    expect(screen.queryByRole('note')).toBeNull()
+    expect(localStorage.getItem(DISMISSED_KEY)).toBe('1')
+
+    first.unmount()
+    render(<InstallHint />)
+    expect(screen.queryByRole('note')).toBeNull()
+  })
+
+  it('stays up and reports the error when the dismissal cannot be saved', () => {
+    mockDevice({ userAgent: IPHONE_SAFARI, maxTouchPoints: 5, navigatorStandalone: false })
+    const setItem = vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+      throw new DOMException('quota exceeded', 'QuotaExceededError')
+    })
+
+    render(<InstallHint />)
+    fireEvent.click(screen.getByRole('button', { name: 'Dismiss' }))
+    expect(screen.getByRole('note')).toHaveTextContent(copy)
+    expect(screen.getByRole('alert')).toHaveTextContent(
+      'Could not remember on this device that this hint was dismissed: QuotaExceededError: quota exceeded',
+    )
+
+    setItem.mockRestore()
+    fireEvent.click(screen.getByRole('button', { name: 'Retry' }))
+    expect(screen.queryByRole('note')).toBeNull()
+    expect(screen.queryByRole('alert')).toBeNull()
+    expect(localStorage.getItem(DISMISSED_KEY)).toBe('1')
+  })
+
+  it('shows and reports the error when storage cannot be read', () => {
+    mockDevice({ userAgent: IPHONE_SAFARI, maxTouchPoints: 5, navigatorStandalone: false })
+    const getItem = vi.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+      throw new DOMException('storage blocked', 'SecurityError')
+    })
+
+    render(<InstallHint />)
+    expect(screen.getByRole('note')).toHaveTextContent(copy)
+    expect(screen.getByRole('alert')).toHaveTextContent(
+      'Could not check whether this hint was dismissed on this device: SecurityError: storage blocked',
+    )
+
+    getItem.mockRestore()
+    fireEvent.click(screen.getByRole('button', { name: 'Retry' }))
+    expect(screen.getByRole('note')).toHaveTextContent(copy)
+    expect(screen.queryByRole('alert')).toBeNull()
+  })
+})
@@ -0,0 +1,97 @@
+import { useState } from 'react'
+import { Share, X } from 'lucide-react'
+import { Card } from '../ui/Card.tsx'
+import { ErrorBanner } from '../ui/ErrorBanner.tsx'
+import { Icon } from '../ui/Icon.tsx'
+import { IconButton } from '../ui/IconButton.tsx'
+import styles from './InstallHint.module.css'
+
+// DISMISSED_KEY is the localStorage key remembering, on this device, that the
+// household dismissed the hint.
+export const DISMISSED_KEY = 'mealquest.installHint.dismissed'
+
+// Safari's user agent ends "(KHTML, like Gecko) Version/<v> Mobile/<build>
+// Safari/<v>" (iPadOS leaves out Mobile/). Every other iOS browser and in-app
+// web view adds its own token (CriOS, FxiOS, EdgiOS, OPiOS, MQQBrowser, GSA,
+// ...) or drops Version/ or Safari/, so only this exact tail is Safari.
+const SAFARI_TAIL = /\(KHTML, like Gecko\) Version\/[\d.]+ (?:Mobile\/\w+ )?Safari\/[\d.]+$/
+
+// isIosSafari reports whether the page is open in Safari on iPhone, iPod or
+// iPad. iPadOS 13+ asks for the desktop site and reports itself as a Mac, so
+// a "Macintosh" with a touch screen is an iPad.
+export function isIosSafari(nav: Pick<Navigator, 'userAgent' | 'maxTouchPoints'>): boolean {
+  const ua = nav.userAgent
+  const ios = /iPhone|iPod|iPad/.test(ua) || (/Macintosh/.test(ua) && nav.maxTouchPoints > 1)
+  return ios && SAFARI_TAIL.test(ua)
+}
+
+// isStandalone reports whether the app is running from the Home Screen.
+// Safari sets navigator.standalone; other browsers answer the display-mode
+// media query.
+export function isStandalone(): boolean {
+  const legacy = (navigator as Navigator & { standalone?: boolean }).standalone
+  return legacy === true || window.matchMedia('(display-mode: standalone)').matches
+}
+
+// HintState is whether the household dismissed the hint on this device, and
+// the storage failure, if any, that stopped us reading or saving that.
+type HintState = {
+  dismissed: boolean
+  failure: { action: 'read' | 'write'; message: string } | null
+}
+
+// Storage can be unavailable (blocked by the browser or privacy settings), in
+// which case using it throws. The failure is reported, never treated as a
+// remembered dismissal.
+function readDismissed(): HintState {
+  try {
+    return { dismissed: window.localStorage.getItem(DISMISSED_KEY) === '1', failure: null }
+  } catch (err) {
+    return { dismissed: false, failure: { action: 'read', message: String(err) } }
+  }
+}
+
+function writeDismissed(): HintState {
+  try {
+    window.localStorage.setItem(DISMISSED_KEY, '1')
+    return { dismissed: true, failure: null }
+  } catch (err) {
+    return { dismissed: false, failure: { action: 'write', message: String(err) } }
+  }
+}
+
+const failureText = {
+  read: 'Could not check whether this hint was dismissed on this device',
+  write: 'Could not remember on this device that this hint was dismissed',
+}
+
+// InstallHint tells iOS and iPadOS Safari users how to install the app, which
+// iOS requires before it delivers Web Push. It shows only in a Safari browser
+// tab, never once installed, and stays dismissed on this device. If storage
+// fails, the hint stays up with an error saying so. Used by onboarding step 3
+// and the Notifications screen.
+export function InstallHint() {
+  const [eligible] = useState(() => isIosSafari(navigator) && !isStandalone())
+  const [state, setState] = useState<HintState>(() =>
+    eligible ? readDismissed() : { dismissed: false, failure: null },
+  )
+  if (!eligible || state.dismissed) return null
+
+  const { failure } = state
+  return (
+    <>
+      <Card tone="muted" role="note" className={styles.hint}>
+        <Icon icon={Share} className={styles.icon} />
+        <p className={styles.message}>Tap Share, then Add to Home Screen to get notifications</p>
+        <IconButton label="Dismiss" onClick={() => setState(writeDismissed())}>
+          <Icon icon={X} />
+        </IconButton>
+      </Card>
+      {failure && (
+        <ErrorBanner onRetry={() => setState(failure.action === 'read' ? readDismissed() : writeDismissed())}>
+          {failureText[failure.action]}: {failure.message}
+        </ErrorBanner>
+      )}
+    </>
+  )
+}
@@ -0,0 +1,22 @@
+.pill {
+  position: fixed;
+  top: calc(var(--space-3) + env(safe-area-inset-top));
+  left: 50%;
+  z-index: 20;
+  transform: translateX(-50%);
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  margin: 0;
+  padding: 6px 14px;
+  border-radius: var(--radius-pill);
+  background: var(--color-neutral-800);
+  color: var(--on-accent);
+  box-shadow: var(--shadow-md);
+  font-family: var(--font-body);
+  font-size: 13px;
+  font-weight: 700;
+  line-height: 1.2;
+  white-space: nowrap;
+  pointer-events: none;
+}
@@ -0,0 +1,134 @@
+import { act, render, screen } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { ApiProvider, createApiClient, type ApiClient } from '../api/index.ts'
+import { fakeLocation, jsonResponse, ME, stubFetch } from '../test/fetchStub.ts'
+import { createNetworkStatus } from './networkStatus.ts'
+import { OfflinePill } from './OfflinePill.tsx'
+
+const copy = 'Offline — showing saved data'
+
+let onLine: boolean
+
+beforeEach(() => {
+  onLine = true
+  vi.spyOn(navigator, 'onLine', 'get').mockImplementation(() => onLine)
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+})
+
+function goOffline() {
+  onLine = false
+  window.dispatchEvent(new Event('offline'))
+}
+
+function goOnline() {
+  onLine = true
+  window.dispatchEvent(new Event('online'))
+}
+
+function renderPill(): ApiClient {
+  const api = createApiClient(fakeLocation(), createNetworkStatus(window))
+  render(
+    <ApiProvider client={api}>
+      <OfflinePill />
+    </ApiProvider>,
+  )
+  return api
+}
+
+describe('OfflinePill', () => {
+  it('is hidden while online', () => {
+    renderPill()
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('shows while the browser is offline when it renders', () => {
+    onLine = false
+    renderPill()
+    expect(screen.getByRole('status')).toHaveTextContent(copy)
+  })
+
+  it('appears on the offline event and disappears on the online event', () => {
+    renderPill()
+    act(goOffline)
+    expect(screen.getByRole('status')).toHaveTextContent(copy)
+    act(goOnline)
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('appears when a request fails with a network error', async () => {
+    const api = renderPill()
+    vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockRejectedValue(new TypeError('Failed to fetch')))
+    await act(() => expect(api.apiFetch('/api/v1/plan')).rejects.toThrow(TypeError))
+    expect(screen.getByRole('status')).toHaveTextContent(copy)
+
+    act(goOnline)
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('disappears when a later request gets a response', async () => {
+    const api = renderPill()
+    vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockRejectedValue(new TypeError('Failed to fetch')))
+    await act(() => expect(api.apiFetch('/api/v1/plan')).rejects.toThrow(TypeError))
+    expect(screen.getByRole('status')).toBeInTheDocument()
+
+    stubFetch(jsonResponse(200, {}))
+    await act(() => api.apiFetch('/api/v1/plan'))
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('ignores a request body that cannot be serialized', async () => {
+    const api = renderPill()
+    const fetchMock = stubFetch(jsonResponse(200, ME))
+    await act(() => api.loadMe())
+    const body: Record<string, unknown> = {}
+    body.self = body
+
+    await act(() =>
+      expect(api.apiFetch('/api/v1/plan', { method: 'PUT', body })).rejects.toThrow(
+        'PUT /api/v1/plan: request body is not serializable as JSON',
+      ),
+    )
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('ignores a GET request with a body, which fetch would refuse to send', async () => {
+    const api = renderPill()
+    const fetchMock = stubFetch()
+
+    await act(() =>
+      expect(api.apiFetch('/api/v1/plan', { body: { week: 1 } })).rejects.toThrow(
+        'GET /api/v1/plan: a GET request cannot carry a body',
+      ),
+    )
+    expect(fetchMock).not.toHaveBeenCalled()
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('ignores an aborted request', async () => {
+    const api = renderPill()
+    vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockRejectedValue(new DOMException('aborted', 'AbortError')))
+    await act(() => expect(api.apiFetch('/api/v1/plan')).rejects.toThrow('aborted'))
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('removes its online and offline listeners on unmount', () => {
+    const add = vi.spyOn(window, 'addEventListener')
+    const remove = vi.spyOn(window, 'removeEventListener')
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window))
+    const { unmount } = render(
+      <ApiProvider client={api}>
+        <OfflinePill />
+      </ApiProvider>,
+    )
+    const added = add.mock.calls.filter(([type]) => type === 'online' || type === 'offline')
+    expect(added.map(([type]) => type).sort()).toEqual(['offline', 'online'])
+
+    unmount()
+    for (const [type, listener] of added) expect(remove).toHaveBeenCalledWith(type, listener)
+  })
+})
@@ -0,0 +1,19 @@
+import { useSyncExternalStore } from 'react'
+import { WifiOff } from 'lucide-react'
+import { useApi } from '../api/index.ts'
+import { Icon } from '../ui/Icon.tsx'
+import styles from './OfflinePill.module.css'
+
+// OfflinePill tells the household that what they see came from the cache
+// while the browser is offline or the server cannot be reached.
+export function OfflinePill() {
+  const { network } = useApi()
+  const offline = useSyncExternalStore(network.subscribe, network.offline)
+  if (!offline) return null
+  return (
+    <p role="status" className={styles.pill}>
+      <Icon icon={WifiOff} />
+      Offline — showing saved data
+    </p>
+  )
+}
@@ -0,0 +1,22 @@
+.toast {
+  position: fixed;
+  left: 50%;
+  bottom: calc(110px + env(safe-area-inset-bottom));
+  z-index: 20;
+  transform: translateX(-50%);
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  width: max-content;
+  max-width: calc(100vw - 2 * var(--space-4));
+  padding: var(--space-2) var(--space-2) var(--space-2) var(--space-4);
+  box-shadow: var(--shadow-lg);
+}
+
+.message {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 15px;
+  font-weight: 600;
+  line-height: 1.35;
+}
@@ -0,0 +1,165 @@
+import { act, render, screen } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import { SKIP_WAITING, UpdatePrompt, type UpdateContainer } from './UpdatePrompt.tsx'
+
+// FakeWorker is a ServiceWorker whose state the test moves along.
+class FakeWorker extends EventTarget {
+  state: ServiceWorkerState = 'installing'
+  postMessage = vi.fn()
+  setState(state: ServiceWorkerState) {
+    this.state = state
+    this.dispatchEvent(new Event('statechange'))
+  }
+}
+
+class FakeRegistration extends EventTarget {
+  installing: FakeWorker | null = null
+  waiting: FakeWorker | null = null
+  // install starts a new worker, as the browser does on finding an update.
+  install(): FakeWorker {
+    const worker = new FakeWorker()
+    this.installing = worker
+    this.dispatchEvent(new Event('updatefound'))
+    return worker
+  }
+  // finishInstall moves the installing worker to waiting.
+  finishInstall(worker: FakeWorker) {
+    this.installing = null
+    this.waiting = worker
+    worker.setState('installed')
+  }
+}
+
+class FakeContainer extends EventTarget {
+  controller: object | null = {}
+  registration = new FakeRegistration()
+  ready = Promise.resolve(this.registration)
+  // takeOver makes the waiting worker the controller.
+  takeOver() {
+    const worker = this.registration.waiting
+    this.registration.waiting = null
+    this.controller = worker
+    worker?.setState('activated')
+    this.dispatchEvent(new Event('controllerchange'))
+  }
+}
+
+async function renderPrompt(container: FakeContainer | undefined) {
+  const reload = vi.fn()
+  const view = render(<UpdatePrompt container={container as unknown as UpdateContainer} reload={reload} />)
+  await act(async () => {
+    await container?.ready
+  })
+  return { reload, ...view }
+}
+
+const copy = 'New version ready · Reload'
+
+describe('UpdatePrompt', () => {
+  it('shows nothing without a service worker', async () => {
+    await renderPrompt(undefined)
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('shows nothing while no worker is waiting', async () => {
+    const container = new FakeContainer()
+    await renderPrompt(container)
+    act(() => {
+      container.registration.install()
+    })
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('shows nothing for a waiting worker when the page has no controller', async () => {
+    const container = new FakeContainer()
+    container.controller = null
+    container.registration.waiting = new FakeWorker()
+    await renderPrompt(container)
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('shows the toast for a worker already waiting when the page loads', async () => {
+    const container = new FakeContainer()
+    container.registration.waiting = new FakeWorker()
+    await renderPrompt(container)
+    expect(screen.getByRole('status')).toHaveTextContent(copy)
+  })
+
+  it('shows the toast when an update finishes installing', async () => {
+    const container = new FakeContainer()
+    await renderPrompt(container)
+    act(() => container.registration.finishInstall(container.registration.install()))
+    expect(screen.getByRole('status')).toHaveTextContent(copy)
+  })
+
+  it('sends SKIP_WAITING on Reload and reloads once the new worker controls the page', async () => {
+    const container = new FakeContainer()
+    const { reload } = await renderPrompt(container)
+    const worker = container.registration.install()
+    act(() => container.registration.finishInstall(worker))
+
+    act(() => screen.getByRole('button', { name: 'Reload' }).click())
+    expect(worker.postMessage).toHaveBeenCalledExactlyOnceWith(SKIP_WAITING)
+    expect(screen.queryByRole('status')).toBeNull()
+    expect(reload).not.toHaveBeenCalled()
+
+    act(() => container.takeOver())
+    expect(reload).toHaveBeenCalledOnce()
+    // A later controller change (another tab's update) does not reload again.
+    act(() => container.dispatchEvent(new Event('controllerchange')))
+    expect(reload).toHaveBeenCalledOnce()
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('does not reappear for the worker the household chose to reload into', async () => {
+    const container = new FakeContainer()
+    container.registration.waiting = new FakeWorker()
+    await renderPrompt(container)
+    act(() => screen.getByRole('button', { name: 'Reload' }).click())
+    // The worker reports another state change before it takes over.
+    act(() => container.registration.waiting?.setState('installed'))
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  it('hides when dismissed until the next update is waiting', async () => {
+    const container = new FakeContainer()
+    const { reload } = await renderPrompt(container)
+    const first = container.registration.install()
+    act(() => container.registration.finishInstall(first))
+
+    act(() => screen.getByRole('button', { name: 'Dismiss' }).click())
+    expect(screen.queryByRole('status')).toBeNull()
+    expect(first.postMessage).not.toHaveBeenCalled()
+    act(() => first.setState('installed'))
+    expect(screen.queryByRole('status')).toBeNull()
+
+    act(() => container.registration.finishInstall(container.registration.install()))
+    expect(screen.getByRole('status')).toHaveTextContent(copy)
+    expect(reload).not.toHaveBeenCalled()
+  })
+
+  it('hides when another tab activates the waiting worker', async () => {
+    const container = new FakeContainer()
+    container.registration.waiting = new FakeWorker()
+    const { reload } = await renderPrompt(container)
+    act(() => container.takeOver())
+    expect(screen.queryByRole('status')).toBeNull()
+    expect(reload).not.toHaveBeenCalled()
+  })
+
+  it('removes its listeners on unmount', async () => {
+    const container = new FakeContainer()
+    const worker = new FakeWorker()
+    container.registration.waiting = worker
+    const { reload, unmount } = await renderPrompt(container)
+    const removeRegistration = vi.spyOn(container.registration, 'removeEventListener')
+    const removeWorker = vi.spyOn(worker, 'removeEventListener')
+    act(() => screen.getByRole('button', { name: 'Reload' }).click())
+
+    unmount()
+    expect(removeRegistration).toHaveBeenCalledWith('updatefound', expect.any(Function))
+    expect(removeWorker).toHaveBeenCalledWith('statechange', expect.any(Function))
+    container.takeOver()
+    expect(reload).not.toHaveBeenCalled()
+  })
+})
@@ -0,0 +1,101 @@
+import { useEffect, useRef, useState } from 'react'
+import { X } from 'lucide-react'
+import { Button } from '../ui/Button.tsx'
+import { Card } from '../ui/Card.tsx'
+import { Icon } from '../ui/Icon.tsx'
+import { IconButton } from '../ui/IconButton.tsx'
+import styles from './UpdatePrompt.module.css'
+
+// UpdateContainer is the part of navigator.serviceWorker the prompt uses.
+export type UpdateContainer = Pick<ServiceWorkerContainer, 'ready' | 'controller' | 'addEventListener' | 'removeEventListener'>
+
+export type UpdatePromptProps = {
+  // navigator.serviceWorker, or undefined where the browser has none.
+  container: UpdateContainer | undefined
+  // Reloads the page once the new worker controls it.
+  reload: () => void
+}
+
+// SKIP_WAITING is the message src/sw.ts answers by activating the waiting
+// worker.
+export const SKIP_WAITING = { type: 'SKIP_WAITING' } as const
+
+// UpdatePrompt offers to reload when a new service worker is installed and
+// waiting to replace the one controlling the page. Reload asks the waiting
+// worker to activate and reloads once it controls the page; dismissing hides
+// the prompt until a different worker is waiting.
+export function UpdatePrompt({ container, reload }: UpdatePromptProps) {
+  const [waiting, setWaiting] = useState<ServiceWorker | null>(null)
+  const [dismissed, setDismissed] = useState<ServiceWorker | null>(null)
+  const [accepted, setAccepted] = useState<ServiceWorker | null>(null)
+  const reloadListener = useRef<(() => void) | null>(null)
+
+  useEffect(() => {
+    if (container === undefined) return
+    const sw = container
+    let registration: ServiceWorkerRegistration | null = null
+    let unmounted = false
+    const watched = new Set<ServiceWorker>()
+
+    // A waiting worker only replaces something when the page has a
+    // controller; without one there is no controllerchange to reload on.
+    function check() {
+      if (registration === null) return
+      setWaiting(sw.controller === null ? null : registration.waiting)
+    }
+    function watch(worker: ServiceWorker | null) {
+      if (worker === null || watched.has(worker)) return
+      watched.add(worker)
+      worker.addEventListener('statechange', check)
+    }
+    function updateFound() {
+      watch(registration?.installing ?? null)
+    }
+
+    void sw.ready.then((ready) => {
+      if (unmounted) return
+      registration = ready
+      ready.addEventListener('updatefound', updateFound)
+      watch(ready.installing)
+      watch(ready.waiting)
+      check()
+    })
+    return () => {
+      unmounted = true
+      registration?.removeEventListener('updatefound', updateFound)
+      watched.forEach((worker) => worker.removeEventListener('statechange', check))
+      if (reloadListener.current !== null) {
+        sw.removeEventListener('controllerchange', reloadListener.current)
+        reloadListener.current = null
+      }
+    }
+  }, [container])
+
+  if (container === undefined || waiting === null || waiting === dismissed || waiting === accepted) return null
+
+  function update() {
+    if (container === undefined || waiting === null || reloadListener.current !== null) return
+    const listener = () => {
+      reloadListener.current = null
+      reload()
+    }
+    reloadListener.current = listener
+    container.addEventListener('controllerchange', listener, { once: true })
+    setAccepted(waiting)
+    waiting.postMessage(SKIP_WAITING)
+  }
+
+  return (
+    <Card role="status" className={styles.toast}>
+      <p className={styles.message}>
+        New version ready <span aria-hidden="true">·</span>
+      </p>
+      {/* The space keeps the copy "New version ready · Reload" in the text;
+          a flex container does not render it. */}{' '}
+      <Button onClick={update}>Reload</Button>
+      <IconButton label="Dismiss" onClick={() => setDismissed(waiting)}>
+        <Icon icon={X} />
+      </IconButton>
+    </Card>
+  )
+}
@@ -0,0 +1,50 @@
+// NetworkWindow is the part of window the network status reads: the browser's
+// online flag and its online/offline events.
+export type NetworkWindow = Pick<Window, 'navigator' | 'addEventListener' | 'removeEventListener'>
+
+export type NetworkStatus = {
+  // offline reports whether the browser says it is offline or the last API
+  // request failed with a network error.
+  offline(): boolean
+  // subscribe is notified when offline may have changed. It listens for the
+  // window's online/offline events until the returned function is called.
+  subscribe(listener: () => void): () => void
+  // requestFailed records a fetch that rejected with a network error.
+  requestFailed(): void
+  // requestSucceeded records a fetch that got a response.
+  requestSucceeded(): void
+}
+
+// createNetworkStatus tracks whether MealQuest can reach the server. A failed
+// request counts as offline until a later request gets a response or the
+// browser reports that it is back online.
+export function createNetworkStatus(win: NetworkWindow): NetworkStatus {
+  let failed = false
+  const listeners = new Set<() => void>()
+
+  function setFailed(value: boolean) {
+    if (failed === value) return
+    failed = value
+    listeners.forEach((listener) => listener())
+  }
+
+  return {
+    offline: () => !win.navigator.onLine || failed,
+    subscribe(listener) {
+      const online = () => {
+        failed = false
+        listener()
+      }
+      listeners.add(listener)
+      win.addEventListener('online', online)
+      win.addEventListener('offline', listener)
+      return () => {
+        listeners.delete(listener)
+        win.removeEventListener('online', online)
+        win.removeEventListener('offline', listener)
+      }
+    },
+    requestFailed: () => setFailed(true),
+    requestSucceeded: () => setFailed(false),
+  }
+}
@@ -0,0 +1,103 @@
+// MealQuest service worker. vite-plugin-pwa replaces self.__WB_MANIFEST with
+// the build's precache list (shell, JS, CSS and fonts, each with a revision).
+// Every other request goes through the route src/sw/routes.ts decides.
+// Fonts are precached too, but their route is registered ahead of the
+// precache route, so a font fetch goes through the expiring CacheFirst
+// strategy and falls back to the precached copy when the network fails.
+
+import { cacheNames as workboxCacheNames, setCacheNameDetails } from 'workbox-core'
+import type { RouteHandlerCallbackOptions } from 'workbox-core/types'
+import { ExpirationPlugin } from 'workbox-expiration'
+import { PrecacheFallbackPlugin, matchPrecache, precacheAndRoute } from 'workbox-precaching'
+import { registerRoute } from 'workbox-routing'
+import { CacheFirst, NetworkFirst, NetworkOnly, type Strategy } from 'workbox-strategies'
+import {
+  cacheNames,
+  cacheVersion,
+  networkTimeoutSeconds,
+  routeFor,
+  staleCaches,
+  type Route,
+} from './sw/routes'
+
+declare const self: ServiceWorkerGlobalScope & {
+  __WB_MANIFEST: Array<{ url: string; revision: string | null }>
+}
+
+// The precache becomes mealquest-precache-v1.
+setCacheNameDetails({ prefix: 'mealquest', precache: 'precache', suffix: cacheVersion })
+
+const day = 24 * 60 * 60
+
+const strategies = {
+  [cacheNames.api]: new NetworkFirst({ cacheName: cacheNames.api, networkTimeoutSeconds }),
+  [cacheNames.media]: new CacheFirst({
+    cacheName: cacheNames.media,
+    plugins: [
+      new ExpirationPlugin({ maxEntries: 200, maxAgeSeconds: 30 * day, purgeOnQuotaError: true }),
+    ],
+  }),
+  [cacheNames.fonts]: new CacheFirst({
+    cacheName: cacheNames.fonts,
+    plugins: [
+      new ExpirationPlugin({ maxEntries: 20, maxAgeSeconds: 365 * day, purgeOnQuotaError: true }),
+      // Offline with no runtime copy yet: the font from the precache.
+      { handlerDidError: async ({ request }) => matchPrecache(request.url) },
+    ],
+  }),
+}
+const networkOnly = new NetworkOnly()
+const navigation = new NetworkOnly({
+  plugins: [new PrecacheFallbackPlugin({ fallbackURL: 'index.html' })],
+})
+
+function strategyFor(route: Route): Strategy {
+  switch (route.strategy) {
+    case 'network-first':
+    case 'cache-first':
+      return strategies[route.cacheName]
+    case 'network-only':
+      return networkOnly
+    case 'navigation-fallback':
+      return navigation
+  }
+}
+
+function routeOf({ request, url }: { request: Request; url: URL }): Route {
+  return routeFor({ method: request.method, url, mode: request.mode }, self.location.origin)
+}
+
+function handle({ request, url, event }: RouteHandlerCallbackOptions): Promise<Response> {
+  return strategyFor(routeOf({ request, url })).handle({ request, event })
+}
+
+function isFont(options: { request: Request; url: URL }): boolean {
+  const route = routeOf(options)
+  return route.strategy === 'cache-first' && route.cacheName === cacheNames.fonts
+}
+
+// Workbox uses the first route that matches, so the font route comes before
+// the precache route, which would otherwise answer every precached font.
+registerRoute(isFont, handle, 'GET')
+precacheAndRoute(self.__WB_MANIFEST)
+
+// Workbox routes are per method; every method goes through routeFor, which
+// sends every non-GET to the network only.
+for (const method of ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'] as const) {
+  registerRoute(() => true, handle, method)
+}
+
+self.addEventListener('activate', (event) => {
+  const current = [workboxCacheNames.precache, ...Object.values(cacheNames)]
+  event.waitUntil(
+    caches
+      .keys()
+      .then((names) => Promise.all(staleCaches(names, current).map((name) => caches.delete(name)))),
+  )
+})
+
+// The update prompt (src/pwa/UpdatePrompt.tsx) asks a waiting worker to take
+// over when the household chooses Reload.
+self.addEventListener('message', (event) => {
+  if (event.data?.type === 'SKIP_WAITING') void self.skipWaiting()
+})
@@ -0,0 +1,157 @@
+import { describe, expect, it } from 'vitest'
+import { cacheNames, routeFor, staleCaches, type Route } from './routes'
+
+const origin = 'https://mealquest.test'
+
+function route(path: string, method = 'GET', mode: RequestMode = 'cors'): Route {
+  return routeFor({ method, url: new URL(path, origin), mode }, origin)
+}
+
+const apiCache: Route = { strategy: 'network-first', cacheName: cacheNames.api }
+const networkOnly: Route = { strategy: 'network-only' }
+
+describe('routeFor', () => {
+  it.each([
+    '/api/v1/plans',
+    '/api/v1/plans/2026-W40',
+    '/api/v1/shopping/current',
+    '/api/v1/dinners',
+    '/api/v1/dinners/01J9ZK?include=recipe',
+    '/api/v1/home',
+  ])('GET %s is network-first in the API cache', (path) => {
+    expect(route(path)).toEqual(apiCache)
+  })
+
+  it.each(['/media/photos/abc.jpg', '/media/thumbs/abc.webp'])(
+    'GET %s is cache-first in the media cache',
+    (path) => {
+      expect(route(path)).toEqual({ strategy: 'cache-first', cacheName: cacheNames.media })
+    },
+  )
+
+  it('GET of a font file is cache-first in the fonts cache', () => {
+    expect(route('/assets/Figtree-Bold-a1b2c3.woff2')).toEqual({
+      strategy: 'cache-first',
+      cacheName: cacheNames.fonts,
+    })
+  })
+
+  it.each([
+    '/auth/login',
+    '/auth/callback?code=x&state=y',
+    '/auth/logout',
+    '/auth/me',
+    '/api/v1/settings',
+    '/api/v1/settings/ai',
+    '/api/v1/jobs',
+    '/api/v1/jobs/01J9ZK',
+  ])('GET %s is network-only', (path) => {
+    expect(route(path)).toEqual(networkOnly)
+  })
+
+  it.each(['/auth/login', '/auth/callback?code=x&state=y', '/api/v1/settings/ai'])(
+    'a navigation to %s is network-only with no offline fallback',
+    (path) => {
+      expect(route(path, 'GET', 'navigate')).toEqual(networkOnly)
+    },
+  )
+
+  it.each([
+    '/%61uth/login',
+    '/auth%2Fcallback?code=x&state=y',
+    '/%61pi/v1/settings/household',
+    '/api/v1/%73ettings/ai',
+    '/api/v1/settings%2Fai',
+    '/%61pi/v1/jobs/01J9ZK',
+    '/api/v1/j%6Fbs',
+    '/api/v1/plans%2F..%2Fsettings',
+    '/plan%2F..%2Fauth%2Flogin',
+  ])('an encoded reserved path %s is network-only, navigated or not', (path) => {
+    expect(route(path)).toEqual(networkOnly)
+    expect(route(path, 'GET', 'navigate')).toEqual(networkOnly)
+  })
+
+  it.each(['/%E0%A4%A', '/auth%', '/plan/%zz', '/api/v1/plans/%C3'])(
+    'a malformed encoding in %s is network-only, navigated or not',
+    (path) => {
+      expect(route(path)).toEqual(networkOnly)
+      expect(route(path, 'GET', 'navigate')).toEqual(networkOnly)
+    },
+  )
+
+  it('classifies other API paths by their decoded form', () => {
+    expect(route('/%61pi/v1/plans/2026-W40')).toEqual(apiCache)
+    expect(route('/%61pi/v1/recipes', 'GET', 'navigate')).toEqual(networkOnly)
+  })
+
+  it.each(['POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'])(
+    '%s is network-only on every URL class',
+    (method) => {
+      for (const path of [
+        '/api/v1/plans/2026-W40',
+        '/api/v1/shopping/current',
+        '/api/v1/dinners/01J9ZK',
+        '/api/v1/home',
+        '/media/photos/abc.jpg',
+        '/assets/Figtree-Bold-a1b2c3.woff2',
+        '/auth/logout',
+        '/plan',
+      ]) {
+        expect(route(path, method), `${method} ${path}`).toEqual(networkOnly)
+        expect(route(path, method, 'navigate'), `${method} ${path}`).toEqual(networkOnly)
+      }
+    },
+  )
+
+  it('matches whole path segments only', () => {
+    expect(route('/api/v1/plansx')).toEqual(networkOnly)
+    expect(route('/api/v1/homepage')).toEqual(networkOnly)
+    expect(route('/mediax/a.jpg')).toEqual(networkOnly)
+    expect(route('/authors')).toEqual(networkOnly)
+    expect(route('/api/v1/settingsx')).toEqual(networkOnly)
+  })
+
+  it('leaves other API calls network-only', () => {
+    expect(route('/api/v1/recipes')).toEqual(networkOnly)
+    expect(route('/api/v1/ideas', 'GET', 'navigate')).toEqual(networkOnly)
+  })
+
+  it('leaves cross-origin requests network-only', () => {
+    for (const path of ['/api/v1/plans', '/media/a.jpg', '/assets/a.woff2']) {
+      const url = new URL(path, 'https://cdn.example')
+      expect(routeFor({ method: 'GET', url, mode: 'no-cors' }, origin)).toEqual(networkOnly)
+    }
+  })
+
+  it.each(['/', '/plan', '/supply-run', '/dinners/01J9ZK'])(
+    'a navigation to the app at %s falls back to the precached index.html',
+    (path) => {
+      expect(route(path, 'GET', 'navigate')).toEqual({ strategy: 'navigation-fallback' })
+    },
+  )
+
+  it('leaves other same-origin GETs network-only', () => {
+    expect(route('/health')).toEqual(networkOnly)
+  })
+})
+
+describe('cache names', () => {
+  it('all start with mealquest-', () => {
+    for (const name of Object.values(cacheNames)) expect(name).toMatch(/^mealquest-/)
+  })
+})
+
+describe('staleCaches', () => {
+  it('deletes only MealQuest caches that are not current', () => {
+    const current = ['mealquest-precache-v1', ...Object.values(cacheNames)]
+    const names = [
+      ...current,
+      'mealquest-precache',
+      'mealquest-api-v0',
+      'workbox-precache-v2-https://mealquest.test/',
+      'other-app-cache',
+      'my-mealquest-cache',
+    ]
+    expect(staleCaches(names, current)).toEqual(['mealquest-precache', 'mealquest-api-v0'])
+  })
+})
@@ -0,0 +1,96 @@
+// Decides how the service worker handles each request. This module is pure —
+// no Workbox, no service worker globals — so the tests can assert every URL
+// class without a worker; src/sw.ts maps each route to a Workbox strategy.
+//
+// Security rule: /auth/*, /api/v1/settings/*, /api/v1/jobs/* and every
+// non-GET request are network-only and never reach a cache. Paths are matched
+// as the server sees them — percent-decoded, before and after dot segments are
+// resolved — so /%61uth/login is /auth/login; a malformed encoding is
+// network-only.
+
+export type Route =
+  // Network with a 3 s timeout, then the last cached response.
+  | { strategy: 'network-first'; cacheName: typeof cacheNames.api }
+  // Cached response when there is one, else the network; entries expire.
+  | { strategy: 'cache-first'; cacheName: typeof cacheNames.media | typeof cacheNames.fonts }
+  // Network only, nothing cached.
+  | { strategy: 'network-only' }
+  // Network only, nothing cached; offline, the precached index.html.
+  | { strategy: 'navigation-fallback' }
+
+export interface RouteRequest {
+  method: string
+  url: URL
+  mode: RequestMode
+}
+
+// Bumping the version renames every cache; activate then deletes the old ones.
+export const cacheVersion = 'v1'
+export const cachePrefix = 'mealquest-'
+
+export const cacheNames = {
+  api: `${cachePrefix}api-${cacheVersion}`,
+  media: `${cachePrefix}media-${cacheVersion}`,
+  fonts: `${cachePrefix}fonts-${cacheVersion}`,
+} as const
+
+export const networkTimeoutSeconds = 3
+
+const neverCached = ['/auth', '/api/v1/settings', '/api/v1/jobs']
+const networkFirst = ['/api/v1/plans', '/api/v1/shopping', '/api/v1/dinners', '/api/v1/home']
+
+// True when path is prefix itself or a path below it: /api/v1/plans matches
+// /api/v1/plans and /api/v1/plans/2026-W40, never /api/v1/plansx.
+function under(path: string, prefix: string): boolean {
+  return path === prefix || path.startsWith(`${prefix}/`)
+}
+
+// The pathname percent-decoded, as the server's router sees it, or undefined
+// when the encoding is malformed.
+function decodePath(pathname: string): string | undefined {
+  try {
+    return decodeURIComponent(pathname)
+  } catch {
+    return undefined
+  }
+}
+
+// Resolves "." and ".." segments the way the server's path.Clean does, so a
+// decoded %2F cannot carry a request out of a reserved prefix:
+// /api/v1/plans/../settings cleans to /api/v1/settings.
+function cleanPath(path: string): string {
+  const segments: string[] = []
+  for (const segment of path.split('/')) {
+    if (segment === '' || segment === '.') continue
+    if (segment === '..') segments.pop()
+    else segments.push(segment)
+  }
+  return `/${segments.join('/')}`
+}
+
+const networkOnly: Route = { strategy: 'network-only' }
+
+export function routeFor(request: RouteRequest, origin: string): Route {
+  const { method, url, mode } = request
+  if (method !== 'GET') return networkOnly
+  if (url.origin !== origin) return networkOnly
+  const path = decodePath(url.pathname)
+  if (path === undefined) return networkOnly
+  const cleaned = cleanPath(path)
+  const reserved = (prefix: string) => under(path, prefix) || under(cleaned, prefix)
+  if (neverCached.some(reserved)) return networkOnly
+  if (networkFirst.some((prefix) => under(path, prefix))) {
+    return { strategy: 'network-first', cacheName: cacheNames.api }
+  }
+  if (under(path, '/media')) return { strategy: 'cache-first', cacheName: cacheNames.media }
+  if (path.endsWith('.woff2')) return { strategy: 'cache-first', cacheName: cacheNames.fonts }
+  if (reserved('/api')) return networkOnly
+  if (mode === 'navigate') return { strategy: 'navigation-fallback' }
+  return networkOnly
+}
+
+// The caches activate deletes: MealQuest caches that are no longer current.
+// Caches without the mealquest- prefix belong to someone else and are kept.
+export function staleCaches(names: readonly string[], current: readonly string[]): string[] {
+  return names.filter((name) => name.startsWith(cachePrefix) && !current.includes(name))
+}
@@ -0,0 +1,30 @@
+// The service worker itself needs worker globals, so these tests read its
+// source: they pin the parts routes.ts cannot express — the font strategy's
+// expiration and the font route's place ahead of the precache route.
+import { describe, expect, it } from 'vitest'
+import source from '../sw.ts?raw'
+
+describe('service worker source', () => {
+  it('gives the fonts cache a CacheFirst strategy with an expiration plugin', () => {
+    expect(source).toMatch(
+      /\[cacheNames\.fonts\]: new CacheFirst\(\{\s*cacheName: cacheNames\.fonts,\s*plugins: \[\s*new ExpirationPlugin\(\{ maxEntries: \d+, maxAgeSeconds: [^}]+\}\)/,
+    )
+  })
+
+  it('falls back to the precached font when the network fails', () => {
+    expect(source).toContain('handlerDidError: async ({ request }) => matchPrecache(request.url)')
+  })
+
+  it('registers the font route before the precache route', () => {
+    const fontRoute = source.indexOf("registerRoute(isFont, handle, 'GET')")
+    const precache = source.indexOf('precacheAndRoute(self.__WB_MANIFEST)')
+    expect(fontRoute).toBeGreaterThanOrEqual(0)
+    expect(precache).toBeGreaterThan(fontRoute)
+  })
+
+  it('activates a waiting worker when the update prompt sends SKIP_WAITING', () => {
+    expect(source).toMatch(
+      /self\.addEventListener\('message', \(event\) => \{\s*if \(event\.data\?\.type === 'SKIP_WAITING'\) void self\.skipWaiting\(\)/,
+    )
+  })
+})
@@ -13,9 +13,11 @@
    "noUncheckedIndexedAccess": true,
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
+    "resolveJsonModule": true,
    "allowImportingTsExtensions": true,
    "skipLibCheck": true,
    "noEmit": true
  },
-  "include": ["src", "vite.config.ts"]
+  "include": ["src", "vite.config.ts", "manifest.json"],
+  "exclude": ["src/sw.ts"]
 }
@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "WebWorker"],
+    "types": []
+  },
+  "include": ["src/sw.ts"],
+  "exclude": []
+}
@@ -1,10 +1,30 @@
 import { defineConfig } from 'vitest/config'
 import react from '@vitejs/plugin-react'
+import { VitePWA, type ManifestOptions } from 'vite-plugin-pwa'
+import manifest from './manifest.json' with { type: 'json' }

 const backend = 'http://localhost:8080'

 export default defineConfig({
-  plugins: [react()],
+  plugins: [
+    react(),
+    // The plugin writes manifest.webmanifest and sw.js, links the manifest
+    // from index.html and adds the registerSW.js script. It does both only
+    // in production builds: dev options stay off, so neither `vite` nor
+    // Vitest registers a service worker.
+    VitePWA({
+      strategies: 'injectManifest',
+      srcDir: 'src',
+      filename: 'sw.ts',
+      injectRegister: 'script',
+      // Precache the shell, JS, CSS and the self-hosted fonts.
+      injectManifest: { globPatterns: ['**/*.{html,js,css,woff2}'] },
+      // The web manifest lives in manifest.json: its theme and background
+      // colours are --color-accent and --color-bg from src/styles/tokens.css,
+      // and hex colours may not be written in TypeScript.
+      manifest: manifest as Partial<ManifestOptions>,
+    }),
+  ],
  server: {
    proxy: {
      '/api': backend,
Author	SHA1	Message	Date
dev_agent	1fa295b131	Merge dev into Feature 06 branch before integration review CI / ci (push) Successful in 1m35s Details CI / ci (pull_request) Successful in 1m34s Details	2026-10-05 08:56:59 -04:00
dev_agent	581ff217a9	iOS install hint component (#56 ) CI / ci (push) Successful in 1m33s Details CI / ci (pull_request) Successful in 1m34s Details Co-authored-by: dev_agent <dev_agent@cubecraftlabs.com>	2026-10-05 08:35:35 -04:00
dev_agent	78c33370f9	Update prompt and offline indicator (#52 ) CI / ci (push) Successful in 1m33s Details Co-authored-by: dev_agent <dev_agent@cubecraftlabs.com>	2026-10-05 08:13:50 -04:00
dev_agent	21b2672d40	Service worker caching strategy (#51 ) CI / ci (push) Successful in 1m31s Details Co-authored-by: dev_agent <dev_agent@cubecraftlabs.com> Co-committed-by: dev_agent <dev_agent@cubecraftlabs.com>	2026-10-04 16:36:43 -04:00
dev_agent	dd58865323	Web app manifest and icons (#50 ) CI / ci (push) Successful in 1m35s Details Co-authored-by: dev_agent <dev_agent@cubecraftlabs.com> Co-committed-by: dev_agent <dev_agent@cubecraftlabs.com>	2026-10-04 16:16:41 -04:00