Run the app-key pre-check and rotation with the stack stopped

A raw copy of mealquest.db and its WAL taken while the stack runs is not a
consistent snapshot: a checkpoint between the two copies can drop committed
rows, so the _ct pre-check could report a false zero. Stop the app and
Litestream before the pre-check and keep them stopped until the new key is
in place.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.gitignore

@@ -3,6 +3,8 @@ design/.DS_Store
 
 # Secrets and local environment
 .env*
+!deploy/.env.example
+deploy/.env
 deploy/secrets/
 
 # Build artifacts and dependencies

deploy/.env.example

@@ -0,0 +1,80 @@
+# 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

deploy/RUNBOOK.md

@@ -0,0 +1,841 @@
+# MealQuest deployment runbook
+
+How MealQuest is deployed on office-srvr (10.60.1.14), how it is reached
+through Authentik, Traefik and DNS, how it is updated and rolled back, how
+its data is backed up and restored, and how its secrets are rotated. Values
+are the ones in use on 2026-10-05. Secrets themselves are never written
+here.
+
+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` |
+
+## Prerequisites
+
+On office-srvr (10.60.1.14), as recorded on 2026-10-05:
+
+| Item | Value |
+| --- | --- |
+| OS | Ubuntu 26.04.1 LTS |
+| Docker Engine / Compose plugin | 29.8.2 / 5.6.0 |
+| git, rsync, iptables | 2.53.0, 3.4.1, 1.8.11 (nf_tables) |
+| Account | `overseer`, with sudo |
+| Network | LAN reachability to Traefik (10.60.1.33), Authentik (`auth.cubecraftlabs.com`) and the NAS (10.60.1.50, SSH) |
+
+Elsewhere:
+
+- Admin access to Authentik at <https://auth.cubecraftlabs.com>.
+- SSH access to the Traefik host 10.60.1.33.
+- Cloudflare access for the `cubecraftlabs.com` zone, and admin access to
+  both Pi-holes (10.60.1.101 `dns.ccl`, 10.60.1.85 `dns2.ccl`).
+- A NAS account `joshua` on 10.60.1.50 with the backup directory
+  `/volume1/homes/Joshua/mealquest-backups` (see "Backups").
+- A Gitea token able to read `Maniacs_Mansion/MealQuest`, for the clone.
+
+## Stack and first deploy
+
+The compose stack is `deploy/compose.yaml`: the `mealquest` service (built
+from the repository `Dockerfile`, runs as uid/gid 10001, listens on 8080 in
+the container) and the `litestream` service. Data lives in the named volume
+`mealquest-data`.
+
+### 1. Choose and check the port
+
+The container's 8080 is published on `10.60.1.14:8090`. Ports 8080 and 8081
+on this host belong to NestQuest, so 8090 was chosen. Before the first
+deploy it was checked free with:
+
+```sh
+ss -ltnp | grep 8090   # printed nothing
+```
+
+After the deploy the same host shows NestQuest on 8080/8081 and MealQuest
+on 8090:
+
+```
+LISTEN 0 4096 10.60.1.14:8080 0.0.0.0:*
+LISTEN 0 4096 10.60.1.14:8081 0.0.0.0:*
+LISTEN 0 4096 10.60.1.14:8090 0.0.0.0:*
+```
+
+The published host port is fixed in `deploy/compose.yaml`, in
+`deploy/systemd/mealquest-firewall.sh` and in the Traefik route; change all
+three together.
+
+### 2. Clone
+
+The checkout lives at `/home/overseer/mealquest`, next to NestQuest's
+`~/nestquest` (not `/opt/mealquest`). Clone over HTTPS with a Gitea token,
+then reset the remote to the clean URL so the token is not stored in
+`.git/config`:
+
+```sh
+cd /home/overseer
+git clone https://<user>:<token>@code.cubecraftlabs.com/Maniacs_Mansion/MealQuest.git mealquest
+cd mealquest
+git remote set-url origin https://code.cubecraftlabs.com/Maniacs_Mansion/MealQuest.git
+git remote -v   # must show no token
+git checkout main
+```
+
+### 3. Environment file
+
+`deploy/.env` (git-ignored) is copied from `deploy/.env.example` and is
+mode 0600, owned by `overseer`:
+
+```sh
+cp deploy/.env.example deploy/.env
+chmod 600 deploy/.env
+```
+
+Then edit `deploy/.env` to the values below. In particular
+**`MEALQUEST_BIND_ADDRESS` must be changed**: `.env.example` ships
+`127.0.0.1` (a dev machine), and left as is the service listens only on
+the host's loopback, which Traefik cannot reach. Set it to the LAN address
+and check:
+
+```sh
+sed -i 's/^MEALQUEST_BIND_ADDRESS=.*/MEALQUEST_BIND_ADDRESS=10.60.1.14/' deploy/.env
+grep '^MEALQUEST_BIND_ADDRESS=' deploy/.env      # MEALQUEST_BIND_ADDRESS=10.60.1.14
+docker compose -f deploy/compose.yaml config | grep -A4 'ports:'
+#   host_ip: 10.60.1.14, target: 8080, published: "8090"
+```
+
+After step 5 the listener is `10.60.1.14:8090` (container port 8080):
+
+```sh
+docker compose -f deploy/compose.yaml port mealquest 8080   # 10.60.1.14:8090
+sudo ss -ltnp 'sport = :8090'                               # 10.60.1.14:8090 only, no 0.0.0.0 or 127.0.0.1
+```
+
+Values in use:
+
+| Variable | Value |
+| --- | --- |
+| `MEALQUEST_BIND_ADDRESS` | `10.60.1.14` |
+| `MEALQUEST_PUBLIC_URL` | `https://mealquest.cubecraftlabs.com` |
+| `MEALQUEST_SHUTDOWN_TIMEOUT` | `10s` |
+| `MEALQUEST_TRUSTED_PROXY` | `10.60.1.33` |
+| `MEALQUEST_DEFAULT_TZ` | `America/New_York` |
+| `MEALQUEST_OIDC_ISSUER` | `https://auth.cubecraftlabs.com/application/o/mealquest/` |
+| `MEALQUEST_OIDC_CLIENT_ID` | `i6zraqmWsF552b8nmte070LXz0SI5pRdArBxFxeq` (not a secret) |
+| `MEALQUEST_OIDC_ALLOWED_GROUPS` | `mealquest-admin` |
+| `MEALQUEST_SESSION_IDLE` / `MEALQUEST_SESSION_MAX` | `720h` / `4320h` |
+
+`MEALQUEST_HTTP_ADDR`, `MEALQUEST_DATA_DIR` and the `*_FILE` variables are
+set by `deploy/compose.yaml` and must not appear in `deploy/.env`.
+
+### 4. Secrets
+
+`deploy/secrets/` (git-ignored) is mode 0700, owned by `overseer`. Each
+file holds one value, is owned by `10001:10001` (host user `mealquest`) and
+is mode 0600. Compose bind-mounts file secrets with their host owner and
+mode, so any other owner or mode stops the container reading them and the
+service refuses to start.
+
+| File | Content | Mounted at |
+| --- | --- | --- |
+| `secret_key` | base64 of 32 random bytes; encrypts stored secrets (AES-256-GCM) | `/run/secrets/secret_key` |
+| `oidc_client_secret` | Client Secret of the Authentik provider `mealquest` | `/run/secrets/oidc_client_secret` |
+| `litestream_key` | dedicated SSH private key for the NAS (see "Backups") | `/etc/litestream/sftp_key` |
+
+```sh
+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
+# litestream_key: see "Backups" > "Database — Litestream"
+sudo chown 10001:10001 deploy/secrets/*
+sudo chmod 600 deploy/secrets/*
+sudo ls -la deploy/secrets   # three files, mealquest mealquest, -rw-------
+```
+
+The `mealquest` host user (uid/gid 10001) is created in "Media — nightly
+rsync"; until it exists `ls` shows the numeric ids.
+
+### 5. Firewall, then the stack
+
+Install the firewall unit first (see "Host firewall"), so port 8090 is
+never open to the LAN. Create the media directory (see "Media — nightly
+rsync"), then build and start:
+
+```sh
+sudo systemctl start mealquest-firewall
+docker compose -f deploy/compose.yaml up -d --build
+docker compose -f deploy/compose.yaml ps   # mealquest healthy, litestream up
+curl -fsS http://10.60.1.14:8090/health
+curl -s -o /dev/null -w "%{http_code}\n" https://mealquest.cubecraftlabs.com/health   # 200
+```
+
+### Host checkout state on 2026-10-05
+
+The first deploy ran before Feature 07 reached `main`. The checkout is at
+`main` `9cddbbb` and the Feature 07 files under `deploy/` were copied in
+from the feature branch: `deploy/compose.yaml` and `deploy/.env.example`
+are listed in `.git/info/exclude`, the rest show as untracked. Before the
+first routine deploy of a `main` that contains `deploy/`, remove those
+`.git/info/exclude` lines and the copied files (keep `deploy/.env` and
+`deploy/secrets/`), or `git checkout` refuses to overwrite them:
+
+```sh
+cd /home/overseer/mealquest
+git status --porcelain --untracked-files=all deploy   # the copied files
+sed -i '/^deploy\/\(compose.yaml\|.env.example\)$/d' .git/info/exclude
+git clean -n deploy      # dry run: must not list .env or secrets/ (both git-ignored)
+git clean -f deploy
+```
+
+Then follow "Routine deploy"; the checkout brings the tracked copies back.
+
+## Authentik
+
+Sign-in is OpenID Connect against Authentik at
+<https://auth.cubecraftlabs.com>.
+
+| Object | Setting |
+| --- | --- |
+| Provider | OAuth2/OpenID provider `mealquest`, client type **Confidential** |
+| Redirect URI | `https://mealquest.cubecraftlabs.com/auth/callback` (strict) |
+| Signing | RS256, with the instance's signing key |
+| Scopes | MealQuest requests `openid profile email groups offline_access`; the provider's scope mappings include openid, profile, email and offline_access, and the `groups` claim is delivered by a property mapping (the default profile mapping carries `groups`) |
+| Application | name MealQuest, slug `mealquest`, provider `mealquest` |
+| Group | `mealquest-admin`, bound to the application; household members are added to it |
+| Client ID | `i6zraqmWsF552b8nmte070LXz0SI5pRdArBxFxeq` (not a secret; in `deploy/.env` as `MEALQUEST_OIDC_CLIENT_ID`) |
+| Client Secret | in `deploy/secrets/oidc_client_secret` only |
+
+MealQuest refuses a sign-in unless the user's `groups` claim (from the ID
+token, or from userinfo when the token has none) contains a group in
+`MEALQUEST_OIDC_ALLOWED_GROUPS`.
+
+Check discovery from the Docker host — the service discovers the issuer
+at boot and will not start if it cannot:
+
+```sh
+curl -s -o /dev/null -w "%{http_code}\n" \
+  https://auth.cubecraftlabs.com/application/o/mealquest/.well-known/openid-configuration   # 200
+```
+
+On 2026-10-05 discovery returned 200 with issuer
+`https://auth.cubecraftlabs.com/application/o/mealquest/` and
+`id_token_signing_alg_values_supported: ["RS256"]`.
+
+## 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
+```
+
+Traefik watches the dynamic directory, so saving the file loads the route;
+the certificate comes from `certResolver: myresolver` (Let's Encrypt,
+DNS-01 through Cloudflare). Check from the LAN:
+
+```sh
+curl -s -o /dev/null -w "%{http_code}\n" https://mealquest.cubecraftlabs.com/health   # 200
+```
+
+## DNS
+
+| Where | Record |
+| --- | --- |
+| Cloudflare, zone `cubecraftlabs.com` | `CNAME mealquest.cubecraftlabs.com` → `cubecraftlabs.com`, **proxied = true** (orange cloud). Because it is proxied, public resolvers answer with Cloudflare's anycast addresses, A and AAAA (AAAA on 2026-10-05: `2606:4700:3032::6815:34ed`, `2606:4700:3035::ac43:cd75`), never the origin |
+| Pi-hole primary 10.60.1.101 (`dns.ccl`), Local DNS records | `A mealquest.cubecraftlabs.com` → `10.60.1.33` (Traefik) |
+| Pi-hole secondary 10.60.1.85 (`dns2.ccl`), Local DNS records | `A mealquest.cubecraftlabs.com` → `10.60.1.33` (Traefik) |
+
+The local record must be on **both** Pi-holes, or clients using the
+secondary go out through Cloudflare. Check:
+
+```sh
+for s in 10.60.1.101 10.60.1.85; do dig +short @$s mealquest.cubecraftlabs.com A; done
+# 10.60.1.33 from each
+```
+
+**AAAA caveat.** The Pi-hole local record is A only, so both Pi-holes still
+forward AAAA queries and return Cloudflare's IPv6 addresses
+(`2606:4700:3032::6815:34ed`, `2606:4700:3035::ac43:cd75` on 2026-10-05). An
+IPv6-capable LAN client may prefer those and reach MealQuest through
+Cloudflare instead of directly through Traefik. It still works (Cloudflare
+proxies to the public route), but it is not the LAN path. If that matters,
+add a local AAAA override or block AAAA for this name on both Pi-holes.
+
+## Host firewall
+
+Docker publishes `10.60.1.14:8090` past the host's INPUT rules, so the
+port is restricted in the `DOCKER-USER` chain instead: only Traefik
+(10.60.1.33) and the host itself (10.60.1.14) may connect; every other
+source is dropped.
+
+Docker DNATs the published port to the container address and port 8080
+**before** `DOCKER-USER`, so a plain `-p tcp --dport 8090` rule never
+matches. The rules match the original destination `10.60.1.14:8090` with
+conntrack (`--ctorigdst 10.60.1.14 --ctorigdstport 8090 --ctdir ORIGINAL`)
+and are tagged with the comment `mealquest-firewall`. The script deletes
+its own tagged rules and re-inserts them at positions 1–3, so re-runs are
+idempotent. NestQuest's 8080/8081 rules below them are left untouched.
+
+| Repository file | Installed as |
+| --- | --- |
+| `deploy/systemd/mealquest-firewall.sh` | `/usr/local/sbin/mealquest-firewall` (root, 0755) |
+| `deploy/systemd/mealquest-firewall.service` | `/etc/systemd/system/mealquest-firewall.service` (root, 0644) |
+
+The unit is `Type=oneshot`, `RemainAfterExit=yes`, `Requires=` and
+`PartOf=docker.service`, and `WantedBy=multi-user.target docker.service`:
+it re-applies the rules whenever Docker starts or restarts (Docker
+recreates `DOCKER-USER` empty), and a failure fails this unit only.
+
+Install (done on 10.60.1.14 on 2026-10-05):
+
+```sh
+cd /home/overseer/mealquest
+sudo install -o root -g root -m 0755 deploy/systemd/mealquest-firewall.sh /usr/local/sbin/mealquest-firewall
+sudo install -o root -g root -m 0644 deploy/systemd/mealquest-firewall.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now mealquest-firewall
+```
+
+Check:
+
+```sh
+systemctl is-enabled mealquest-firewall; systemctl is-active mealquest-firewall   # enabled, active
+sudo iptables -S DOCKER-USER
+```
+
+Expected head of the chain (recorded 2026-10-05; NestQuest's rules follow):
+
+```
+-A DOCKER-USER -s 10.60.1.33/32 -m conntrack --ctorigdst 10.60.1.14 --ctorigdstport 8090 --ctdir ORIGINAL -m comment --comment mealquest-firewall -j RETURN
+-A DOCKER-USER -s 10.60.1.14/32 -m conntrack --ctorigdst 10.60.1.14 --ctorigdstport 8090 --ctdir ORIGINAL -m comment --comment mealquest-firewall -j RETURN
+-A DOCKER-USER -m conntrack --ctorigdst 10.60.1.14 --ctorigdstport 8090 --ctdir ORIGINAL -m comment --comment mealquest-firewall -j DROP
+```
+
+From any other LAN machine, `curl -m 5 http://10.60.1.14:8090/health` must
+time out; from 10.60.1.33 and 10.60.1.14 it returns 200.
+
+## Routine deploy and rollback
+
+Production runs `main` (a release); only `overseer` merges `dev` → `main`.
+Every deploy builds the image on the host from the checked-out commit.
+
+### Deploy
+
+```sh
+cd /home/overseer/mealquest
+git fetch origin
+git rev-parse --short HEAD          # the SHA being replaced: note it for rollback
+git checkout --detach origin/main   # or a release tag
+docker compose -f deploy/compose.yaml up -d --build
+docker compose -f deploy/compose.yaml ps   # mealquest healthy, litestream up
+curl -fsS http://10.60.1.14:8090/health
+curl -s -o /dev/null -w "%{http_code}\n" https://mealquest.cubecraftlabs.com/health   # 200
+git rev-parse HEAD                  # the deployed SHA
+```
+
+Record the deployed SHA, the previous SHA and the date in the Maestro task
+for the release. Migrations run at start-up; the service refuses to start
+if the database has an applied migration it does not know.
+
+If `deploy/.env.example` gained a variable, add it to `deploy/.env` before
+`up`; the service fails fast at boot naming any missing required variable.
+
+### Rollback to a previous SHA
+
+```sh
+cd /home/overseer/mealquest
+git checkout --detach <previous SHA>
+docker compose -f deploy/compose.yaml up -d --build
+docker compose -f deploy/compose.yaml ps
+curl -fsS http://10.60.1.14:8090/health
+```
+
+A rollback across a release that added a migration fails at start-up
+(the older binary refuses the newer schema). In that case restore the
+database to a point before the upgrade — "Restore the database" with
+`-timestamp` set just before the deploy — then start the older SHA.
+Changes made since that point are lost; say so to the household.
+
+## 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
+```
+
+To restore media, follow "Restore photos (media)" — never copy back while
+the timer or the service can still run.
+
+## 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 photos (media)
+
+Recipe and dinner photos live in `media/` in the data volume and are
+backed up nightly to `joshua@10.60.1.50:/volume1/homes/Joshua/mealquest-backups/media/`
+(see "Media — nightly rsync"). The backup service mirrors with
+`rsync --delete`. **An `rsync --delete` run must never see an empty or
+partial `media/`**: it would delete the NAS copy you are about to restore
+from. Stopping the timer is not enough — it does not stop a run that is
+already in flight, and the service can still be started by hand. So stop
+**both** the timer and the service, confirm no rsync is running, and do
+not start the service until the restore is verified.
+
+Run from `/home/overseer/mealquest`:
+
+```sh
+M=/var/lib/docker/volumes/mealquest-data/_data/media
+NAS=/volume1/homes/Joshua/mealquest-backups/media
+SSH="ssh -i deploy/secrets/litestream_key -o IdentitiesOnly=yes -o UserKnownHostsFile=/etc/mealquest/known_hosts -o StrictHostKeyChecking=yes"
+
+# 1. Stop the nightly mirror: the timer AND any run in flight.
+sudo systemctl stop mealquest-media-backup.timer mealquest-media-backup.service
+
+# 2. Pre-check — all three must hold before media/ is touched. If any
+#    fails, stop here and find out why.
+systemctl is-active mealquest-media-backup.timer     # inactive
+systemctl is-active mealquest-media-backup.service   # inactive (or failed)
+pgrep -a -u mealquest rsync || echo "no rsync"       # no rsync
+sudo $SSH joshua@10.60.1.50 "find $NAS -type f | wc -l"
+#    ^ note this NAS file count; it must be non-zero and is the target below.
+
+# 3. Stop the app (no writes into media/ meanwhile).
+docker compose -f deploy/compose.yaml stop mealquest
+
+# 4. Recreate the directory if it is gone, owned by the app user.
+sudo install -d -o 10001 -g 10001 -m 0755 "$M"
+
+# 5. Copy back from the NAS as uid 10001's files. No --delete in this
+#    direction: the NAS copy is the source and is only read.
+sudo rsync -a --stats --chown=10001:10001 -e "$SSH" "joshua@10.60.1.50:$NAS/" "$M/"
+
+# 6. Post-condition — before anything can mirror again:
+sudo find "$M" -type f | wc -l                            # >= the NAS count from step 2
+sudo $SSH joshua@10.60.1.50 "find $NAS -type f | wc -l"   # unchanged from step 2
+
+# 7. Start the app, then the timer again. Only now may the service run.
+docker compose -f deploy/compose.yaml up -d
+curl -fsS http://10.60.1.14:8090/health
+sudo systemctl start mealquest-media-backup.timer
+systemctl is-active mealquest-media-backup.timer          # active
+```
+
+The local count may exceed the NAS count only if `media/` still held
+files the NAS never received (photos added since the last nightly run);
+the next nightly run then copies them up. If the local count is lower,
+the copy did not complete: leave the timer stopped and re-run step 5.
+
+When the database is restored too, restore it first ("Restore the
+database"), then the media, so every photo the database refers to is
+present. This media restore has not been run against production yet; the
+backup direction was checked on 2026-10-05 (see "Media backup checks").
+
+## 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) |
+
+## Secret rotation
+
+Rotate a secret when it may have leaked, when someone with access leaves,
+or on the owner's schedule. Never paste a secret into a ticket, chat or
+this file.
+
+### App key (`deploy/secrets/secret_key`)
+
+The app key encrypts every stored secret: the `_ct` columns
+`ai_settings.api_key_ct` (LLM API key), `recipe_search_settings.api_key_ct`
+(recipe-search API key), `integrations_google.refresh_token_ct` (Google
+Calendar refresh token) and `chat_settings.webhook_url_ct` (Google Chat
+webhook URL). **Rotating it re-encrypts nothing**: a value encrypted with
+the old key can no longer be read. A `mealquest rotate-key` helper that
+re-encrypts in place is planned but does not exist yet.
+
+**What is recoverable today.** The service currently exposes only
+household settings; no shipped flow writes or re-enters any of these four
+secrets. The re-entry flows are planned: the LLM key in Settings → AI
+assistant (the AI settings feature), the recipe-search key (Feature 10),
+Google Calendar reconnect (Feature 16) and the Google Chat webhook
+(Feature 19). So today the rotation is safe **only if no `_ct` value is
+stored**, which the pre-check below proves. If the pre-check finds a
+stored value, do not rotate: it could not be re-entered afterwards. Keep
+the current key and wait for the matching flow (or the `rotate-key`
+helper).
+
+**The pre-check and the key replacement run with the whole stack
+stopped**, from the pre-check until the new key is in place. A raw copy of
+`mealquest.db` and `mealquest.db-wal` taken while the stack runs is **not**
+a consistent snapshot: the two files are copied one after the other, and a
+checkpoint (by the app or by Litestream) between the two copies can move
+committed pages out of the WAL into `mealquest.db` after `mealquest.db` was
+already copied, then reset the WAL before it is copied. The copy then
+lacks those commits — possibly a stored `_ct` value — and the pre-check
+reports a false 0. A running app could also store a `_ct` value after a
+correct pre-check and before the key is replaced. Stopping both containers
+removes every writer (Litestream also writes and checkpoints), and the
+clean close checkpoints the WAL into `mealquest.db`, so the file alone is
+complete.
+
+Run from `/home/overseer/mealquest`:
+
+```sh
+D=/var/lib/docker/volumes/mealquest-data/_data
+
+# 1. Stop the whole stack (app and Litestream) and leave it stopped until
+#    step 4. Nothing may hold the database open.
+docker compose -f deploy/compose.yaml down
+sudo ls -la "$D"   # mealquest.db and media/ only: no -wal, no -shm; if
+                   # either exists, the close was not clean — stop here
+
+# 2. Pre-check, on a copy of the now-quiescent database.
+rm -rf /tmp/mqcheck && mkdir /tmp/mqcheck
+sudo cp -a "$D/mealquest.db" /tmp/mqcheck/ && sudo chown -R "$USER" /tmp/mqcheck
+python3 - /tmp/mqcheck/mealquest.db <<'PY'
+import sqlite3, sys
+c = sqlite3.connect(sys.argv[1])
+for t, col in (("ai_settings", "api_key_ct"), ("recipe_search_settings", "api_key_ct"),
+               ("integrations_google", "refresh_token_ct"), ("chat_settings", "webhook_url_ct")):
+    print(t, col, c.execute(f"select count(*) from {t} where {col} is not null").fetchone()[0])
+PY
+rm -rf /tmp/mqcheck
+# every count must be 0; otherwise start the stack again on the current
+# key (docker compose -f deploy/compose.yaml up -d) and stop here
+
+# 3. Replace the key, still with the stack stopped.
+sudo cp -a deploy/secrets/secret_key /var/tmp/secret_key.old   # keep until verified, then shred
+head -c 32 /dev/urandom | base64 | sudo tee deploy/secrets/secret_key >/dev/null
+sudo chown 10001:10001 deploy/secrets/secret_key
+sudo chmod 600 deploy/secrets/secret_key
+
+# 4. Start the stack on the new key and check health.
+docker compose -f deploy/compose.yaml up -d
+docker compose -f deploy/compose.yaml ps
+curl -fsS http://10.60.1.14:8090/health
+```
+
+Then sign in and open household settings to confirm the service runs on
+the new key. Finally `sudo shred -u /var/tmp/secret_key.old`. Once the
+planned flows ship, this section gains a step per secret to re-enter it
+and confirm it works.
+
+### OIDC client secret (`deploy/secrets/oidc_client_secret`)
+
+In Authentik, open the provider `mealquest` and regenerate the Client
+Secret. Write it to the file (same owner and mode as above) and recreate
+the service:
+
+```sh
+printf '%s\n' '<new Authentik client secret>' | sudo tee deploy/secrets/oidc_client_secret >/dev/null
+sudo chown 10001:10001 deploy/secrets/oidc_client_secret
+sudo chmod 600 deploy/secrets/oidc_client_secret
+docker compose -f deploy/compose.yaml up -d --force-recreate mealquest
+```
+
+Sign in at <https://mealquest.cubecraftlabs.com> to confirm; sign-ins
+fail between regenerating the secret in Authentik and recreating the
+service.
+
+### LLM API key
+
+Stored encrypted in the database, not in `deploy/`. In the app, open
+**Settings → AI assistant**, choose **Replace**, paste the new key and
+**Verify**, and check the verified state is shown. Then revoke the
+old key in the provider's console. (The AI assistant settings page is
+delivered by its own feature; until it ships there is no stored LLM key
+to rotate.)
+
+### VAPID keys (Web Push)
+
+Planned with Web Push (Feature 19): the public key goes in
+`deploy/.env` as `MEALQUEST_VAPID_PUBLIC_KEY`, the private key in
+`deploy/secrets/vapid_private_key` (owner `10001:10001`, mode 0600), and
+the pair is generated with `cmd/vapidgen`. **Changing the VAPID pair
+invalidates every push subscription**: each device must turn
+notifications on again (`/settings/notifications`) before it receives
+pushes. Rotate only when the private key may have leaked, write both
+halves, recreate the service with `--force-recreate mealquest`, and tell
+the household to re-enable notifications on each device.
+
+### Litestream / NAS key (`deploy/secrets/litestream_key`)
+
+Generate a new keypair as in "Database — Litestream", add the new public
+key to `joshua@10.60.1.50:~/.ssh/authorized_keys`, replace the file
+(owner `10001:10001`, mode 0600), run
+`docker compose -f deploy/compose.yaml up -d --force-recreate litestream`
+and `sudo systemctl start mealquest-media-backup.service`, check both
+(`litestream ltx` and the journal), then remove the old public key from
+the NAS.
+
+## Context records
+
+The confirmed values in this runbook (port 8090, checkout path, Authentik
+group `mealquest-admin`, DNS, firewall, backup target) are also recorded in
+the CTXD project `mealquest`: `RUNBOOKS.MD` (deployment procedure) and the
+open questions in `CONTEXT.MD`, updated for Feature 07 task 876134bc.

deploy/compose.yaml

@@ -0,0 +1,95 @@
+# 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

deploy/known_hosts

@@ -0,0 +1,6 @@
+# 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=

deploy/litestream.yml

@@ -0,0 +1,31 @@
+# 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=

deploy/systemd/mealquest-firewall.service

@@ -0,0 +1,22 @@
+# 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

deploy/systemd/mealquest-firewall.sh

@@ -0,0 +1,29 @@
+#!/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

deploy/systemd/mealquest-media-backup.service

@@ -0,0 +1,29 @@
+# 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

deploy/systemd/mealquest-media-backup.sh

@@ -0,0 +1,44 @@
+#!/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)"

deploy/systemd/mealquest-media-backup.timer

@@ -0,0 +1,11 @@
+# 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

internal/ai/llm/anthropic/anthropic.go

@@ -381,7 +381,7 @@ func (p *Provider) statusError(resp *http.Response, body []byte) error {
 	case http.StatusTooManyRequests, statusOverloaded:
 		return llm.NewRateLimitedError(retryAfter(resp.Header.Get("Retry-After"), time.Now()), p.apiKey)
 	case http.StatusRequestTimeout:
-		return fmt.Errorf("HTTP %d: %w", resp.StatusCode, llm.ErrTimeout)
+		return llm.NewTimeoutStatusError(resp.StatusCode, p.apiKey)
 	default:
 		return llm.NewProviderError(resp.StatusCode, body, p.apiKey)
 	}

internal/ai/llm/errors.go

@@ -137,3 +137,32 @@ func (e *ProviderError) GoString() string { return e.text }
 
 // Is reports whether target is ErrProvider.
 func (e *ProviderError) Is(target error) bool { return target == ErrProvider }
+
+// TimeoutStatusError is an HTTP status, such as 408, by which the vendor
+// said the request timed out. It matches ErrTimeout, and Status keeps it
+// apart from a transport timeout, so a caller can tell the vendor answered.
+// Build it with NewTimeoutStatusError, which redacts its text.
+type TimeoutStatusError struct {
+	status int
+	text   string
+}
+
+// NewTimeoutStatusError returns the error for a timeout HTTP status.
+// secret is the credential sent with the request, or "" when the request
+// sent none; every occurrence of a non-empty secret is removed from the
+// error text, and the secret itself is not kept.
+func NewTimeoutStatusError(status int, secret string) *TimeoutStatusError {
+	text := fmt.Sprintf("HTTP %d: %s", status, ErrTimeout)
+	return &TimeoutStatusError{status: status, text: Redact(text, secret)}
+}
+
+// Status returns the HTTP status code.
+func (e *TimeoutStatusError) Status() int { return e.status }
+
+func (e *TimeoutStatusError) Error() string { return e.text }
+
+// GoString keeps %#v to the redacted Error text instead of the fields.
+func (e *TimeoutStatusError) GoString() string { return e.text }
+
+// Unwrap returns ErrTimeout.
+func (e *TimeoutStatusError) Unwrap() error { return ErrTimeout }

internal/ai/llm/errors_test.go

@@ -196,3 +196,17 @@ func TestTypedErrorsDoNotKeepSecret(t *testing.T) {
 		}
 	}
 }
+
+func TestTimeoutStatusError(t *testing.T) {
+	err := fmt.Errorf("openai: %w", NewTimeoutStatusError(408, "HTTP"))
+	if !errors.Is(err, ErrTimeout) || errors.Is(err, ErrProvider) {
+		t.Fatalf("%v: want ErrTimeout only", err)
+	}
+	var ts *TimeoutStatusError
+	if !errors.As(err, &ts) || ts.Status() != 408 {
+		t.Fatalf("TimeoutStatusError from %v", err)
+	}
+	if s := ts.Error() + fmt.Sprintf("%#v", ts); strings.Contains(s, "HTTP") {
+		t.Fatalf("text holds the secret: %s", s)
+	}
+}

internal/ai/llm/openai/openai.go

@@ -453,7 +453,7 @@ func (p *Provider) statusError(resp *http.Response, body []byte) error {
 	case http.StatusTooManyRequests:
 		return llm.NewRateLimitedError(retryAfter(resp.Header.Get("Retry-After"), time.Now()), p.apiKey)
 	case http.StatusRequestTimeout:
-		return fmt.Errorf("HTTP %d: %w", resp.StatusCode, llm.ErrTimeout)
+		return llm.NewTimeoutStatusError(resp.StatusCode, p.apiKey)
 	default:
 		return llm.NewProviderError(resp.StatusCode, body, p.apiKey)
 	}

internal/ai/llm/presets/presets.go

@@ -178,13 +178,14 @@ var all = map[string]Preset{
 //
 // The Provider sends s.Temperature with every request whose Temperature is
 // nil; a request that sets one keeps it. Neither is sent to a model the
-// preset's OmitTemperature matches.
+// preset's OmitTemperature matches. It is wrapped in llm.NewRetrying, so
+// Generate retries transient vendor failures and has the default timeout.
 func FromSettings(s llm.Settings, key string) (llm.Provider, error) {
 	cp, err := fromSettings(s, key)
 	if err != nil {
 		return nil, redact(err, key)
 	}
-	return cp, nil
+	return llm.NewRetrying(cp), nil
 }
 
 func fromSettings(s llm.Settings, key string) (*configured, error) {

internal/ai/llm/presets/presets_test.go

@@ -22,10 +22,8 @@ type captured struct {
 	body   map[string]json.RawMessage
 }
 
-var errStop = errors.New("recorded")
-
-// recordingTransport records each request and fails it, so no request
-// leaves the process.
+// recordingTransport records each request and answers it 400, so no
+// request leaves the process and the Provider never retries it.
 type recordingTransport struct{ reqs []captured }
 
 func (rt *recordingTransport) RoundTrip(r *http.Request) (*http.Response, error) {
@@ -40,7 +38,12 @@ func (rt *recordingTransport) RoundTrip(r *http.Request) (*http.Response, error)
 		}
 	}
 	rt.reqs = append(rt.reqs, c)
-	return nil, errStop
+	return &http.Response{
+		StatusCode: http.StatusBadRequest,
+		Header:     http.Header{"Content-Type": {"application/json"}},
+		Body:       io.NopCloser(strings.NewReader(`{}`)),
+		Request:    r,
+	}, nil
 }
 
 // generate builds the provider s describes and returns the request its
@@ -327,7 +330,7 @@ func TestNegativeTemperatureRejectedForRejectingModels(t *testing.T) {
 		}
 		req := plainRequest()
 		req.Temperature = ptr(-0.5)
-		if _, err := p.Generate(context.Background(), req); err == nil || errors.Is(err, errStop) || !strings.Contains(err.Error(), "temperature") {
+		if _, err := p.Generate(context.Background(), req); err == nil || errors.Is(err, llm.ErrProvider) || !strings.Contains(err.Error(), "temperature") {
 			t.Errorf("%s: Generate = %v, want a temperature validation error", s.Model, err)
 		}
 	}
@@ -465,7 +468,7 @@ func TestGenerateValidationErrorsNeverLeakKey(t *testing.T) {
 		req := plainRequest()
 		req.Temperature = ptr(-0.5)
 		_, err = p.Generate(context.Background(), req)
-		if err == nil || errors.Is(err, errStop) {
+		if err == nil || errors.Is(err, llm.ErrProvider) {
 			t.Fatalf("%s: Generate = %v, want a validation error", key, err)
 		}
 		for e := error(err); e != nil; e = errors.Unwrap(e) {
@@ -518,3 +521,142 @@ func TestConfigErrorsNeverLeakKey(t *testing.T) {
 		})
 	}
 }
+
+// scriptedTransport answers each request with the next scripted status and
+// body, echoing the key in every failure body, and counts the requests. A
+// scripted status of 0 is a transport timeout instead of a response.
+type scriptedTransport struct {
+	statuses []int
+	key      string
+	sent     int
+}
+
+func (st *scriptedTransport) RoundTrip(r *http.Request) (*http.Response, error) {
+	if st.sent == len(st.statuses) {
+		return nil, fmt.Errorf("unscripted request %d", st.sent+1)
+	}
+	status := st.statuses[st.sent]
+	st.sent++
+	if status == 0 {
+		return nil, transportTimeout{}
+	}
+	header := http.Header{"Content-Type": {"application/json"}}
+	body := `{"error":{"message":"bad key ` + st.key + `"}}`
+	switch status {
+	case http.StatusOK:
+		body = `{"model":"m","choices":[{"message":{"content":"tacos"},"finish_reason":"stop"}]}`
+	case http.StatusTooManyRequests:
+		header.Set("Retry-After", "1")
+	}
+	return &http.Response{
+		StatusCode: status,
+		Header:     header,
+		Body:       io.NopCloser(strings.NewReader(body)),
+		Request:    r,
+	}, nil
+}
+
+// transportTimeout is a net.Error that timed out.
+type transportTimeout struct{}
+
+func (transportTimeout) Error() string   { return "i/o timeout" }
+func (transportTimeout) Timeout() bool   { return true }
+func (transportTimeout) Temporary() bool { return true }
+
+// useTransport makes the adapters send through rt for the rest of the test.
+func useTransport(t *testing.T, rt http.RoundTripper) {
+	t.Helper()
+	orig := http.DefaultTransport
+	http.DefaultTransport = rt
+	t.Cleanup(func() { http.DefaultTransport = orig })
+}
+
+// The Provider FromSettings returns retries a rate-limited Generate.
+func TestFromSettingsRetriesRateLimited(t *testing.T) {
+	st := &scriptedTransport{statuses: []int{http.StatusTooManyRequests, http.StatusOK}, key: testKey}
+	useTransport(t, st)
+
+	p, err := FromSettings(llm.Settings{Provider: "openai", Model: "m"}, testKey)
+	if err != nil {
+		t.Fatalf("FromSettings: %v", err)
+	}
+	resp, err := p.Generate(context.Background(), plainRequest())
+	if err != nil {
+		t.Fatalf("Generate: %v", err)
+	}
+	if resp.Text != "tacos" {
+		t.Errorf("Text = %q, want %q", resp.Text, "tacos")
+	}
+	if st.sent != 2 {
+		t.Errorf("sent %d requests, want 2", st.sent)
+	}
+}
+
+// When every retry fails, the error FromSettings's Provider returns keeps
+// its sentinel and never holds the key the vendor echoed.
+func TestFromSettingsRetryErrorNeverLeaksKey(t *testing.T) {
+	st := &scriptedTransport{statuses: []int{http.StatusTooManyRequests, http.StatusTooManyRequests, http.StatusServiceUnavailable}, key: testKey}
+	useTransport(t, st)
+
+	p, err := FromSettings(llm.Settings{Provider: "openai", Model: "m"}, testKey)
+	if err != nil {
+		t.Fatalf("FromSettings: %v", err)
+	}
+	_, err = p.Generate(context.Background(), plainRequest())
+	if !errors.Is(err, llm.ErrProvider) {
+		t.Fatalf("Generate = %v, want %v", err, llm.ErrProvider)
+	}
+	if st.sent != llm.MaxRetries+1 {
+		t.Errorf("sent %d requests, want %d", st.sent, llm.MaxRetries+1)
+	}
+	for e := error(err); e != nil; e = errors.Unwrap(e) {
+		if s := e.Error() + fmt.Sprintf("%#v", e); strings.Contains(s, testKey) {
+			t.Fatalf("error leaks the key: %s", s)
+		}
+	}
+}
+
+// An HTTP 408 from the vendor is a 4xx answer and is not retried, though it
+// matches llm.ErrTimeout.
+func TestFromSettingsDoesNotRetryHTTP408(t *testing.T) {
+	for _, provider := range []string{"openai", "anthropic"} {
+		t.Run(provider, func(t *testing.T) {
+			st := &scriptedTransport{statuses: []int{http.StatusRequestTimeout}, key: testKey}
+			useTransport(t, st)
+
+			p, err := FromSettings(llm.Settings{Provider: provider, Model: "m"}, testKey)
+			if err != nil {
+				t.Fatalf("FromSettings: %v", err)
+			}
+			_, err = p.Generate(context.Background(), plainRequest())
+			var ts *llm.TimeoutStatusError
+			if !errors.Is(err, llm.ErrTimeout) || !errors.As(err, &ts) || ts.Status() != http.StatusRequestTimeout {
+				t.Fatalf("Generate = %v, want an HTTP 408 ErrTimeout", err)
+			}
+			if st.sent != 1 {
+				t.Errorf("sent %d requests, want 1", st.sent)
+			}
+		})
+	}
+}
+
+// A transport timeout carries no status and is retried.
+func TestFromSettingsRetriesTransportTimeout(t *testing.T) {
+	st := &scriptedTransport{statuses: []int{0, http.StatusOK}, key: testKey}
+	useTransport(t, st)
+
+	p, err := FromSettings(llm.Settings{Provider: "openai", Model: "m"}, testKey)
+	if err != nil {
+		t.Fatalf("FromSettings: %v", err)
+	}
+	resp, err := p.Generate(context.Background(), plainRequest())
+	if err != nil {
+		t.Fatalf("Generate: %v", err)
+	}
+	if resp.Text != "tacos" {
+		t.Errorf("Text = %q, want %q", resp.Text, "tacos")
+	}
+	if st.sent != 2 {
+		t.Errorf("sent %d requests, want 2", st.sent)
+	}
+}

internal/ai/llm/retry.go

@@ -0,0 +1,124 @@
+package llm
+
+import (
+	"context"
+	"errors"
+	"math/rand/v2"
+	"time"
+)
+
+const (
+	// DefaultTimeout bounds a whole Generate call, retries and waits
+	// included, whose Request sets no Timeout.
+	DefaultTimeout = 60 * time.Second
+	// MaxRetries is how many times a failed Generate is retried, so a call
+	// makes at most MaxRetries+1 attempts.
+	MaxRetries = 2
+	// MaxRetryAfter caps the wait a rate-limited vendor may ask for.
+	MaxRetryAfter = 20 * time.Second
+	// backoffBase is the first retry's backoff before jitter; each later
+	// retry doubles it.
+	backoffBase = time.Second
+)
+
+// Retrying is a Provider that retries transient Generate failures of the
+// Provider it wraps. It retries ErrRateLimited, a transport ErrTimeout and
+// a 5xx ErrProvider at most MaxRetries times, and nothing else: an error
+// carrying a 4xx HTTP status other than a rate limit, such as an HTTP 408
+// TimeoutStatusError, is not retried. A rate-limited retry waits for the
+// vendor's RetryAfter, capped at MaxRetryAfter; every other retry, and a
+// rate limit that names no wait, waits a jittered exponential backoff. The Request's Timeout, or DefaultTimeout, is one
+// deadline for the whole call, retries and waits included; a caller's
+// earlier context deadline wins. A retry whose wait would not end before
+// that deadline is not made: the last error is returned at once.
+// ListModels and Verify pass straight through.
+type Retrying struct {
+	Provider
+	// now is the clock; tests replace it.
+	now func() time.Time
+	// sleep waits d or until ctx is done; tests replace it.
+	sleep func(ctx context.Context, d time.Duration) error
+	// jitter returns a random duration in [0, n) for n > 0; tests replace
+	// it.
+	jitter func(n time.Duration) time.Duration
+}
+
+// NewRetrying returns inner wrapped with retries and the default Generate
+// timeout.
+func NewRetrying(inner Provider) *Retrying {
+	return &Retrying{
+		Provider: inner,
+		now:      time.Now,
+		sleep:    sleep,
+		jitter:   rand.N[time.Duration],
+	}
+}
+
+// Generate sends req to the wrapped Provider, retrying transient failures.
+// req.Timeout, or DefaultTimeout when it is 0, sets one deadline for the
+// whole call, carried by the context each attempt receives; attempts get
+// req with Timeout 0 so none restarts the clock.
+func (r *Retrying) Generate(ctx context.Context, req Request) (Response, error) {
+	timeout := req.Timeout
+	if timeout == 0 {
+		timeout = DefaultTimeout
+	}
+	if timeout > 0 {
+		// A negative Timeout stays on req for the wrapped Provider's
+		// Validate to reject, with its key redaction.
+		req.Timeout = 0
+	}
+	ctx, cancel := context.WithDeadline(ctx, r.now().Add(timeout))
+	defer cancel()
+	deadline, _ := ctx.Deadline()
+	for retry := 0; ; retry++ {
+		resp, err := r.Provider.Generate(ctx, req)
+		if err == nil || retry == MaxRetries || ctx.Err() != nil {
+			return resp, err
+		}
+		wait, ok := r.wait(err, retry)
+		if !ok {
+			return resp, err
+		}
+		if !r.now().Add(wait).Before(deadline) {
+			return resp, err
+		}
+		if serr := r.sleep(ctx, wait); serr != nil {
+			return resp, err
+		}
+	}
+}
+
+// wait returns how long to wait before retrying after err, the retry-th
+// retry counting from 0, and false when err is not retried.
+func (r *Retrying) wait(err error, retry int) (time.Duration, bool) {
+	var st interface{ Status() int }
+	if errors.As(err, &st) && st.Status() >= 400 && st.Status() <= 499 {
+		return 0, false
+	}
+	var rl *RateLimitedError
+	if errors.As(err, &rl) && rl.RetryAfter > 0 {
+		return min(rl.RetryAfter, MaxRetryAfter), true
+	}
+	var pe *ProviderError
+	switch {
+	case errors.Is(err, ErrRateLimited), errors.Is(err, ErrTimeout):
+	case errors.As(err, &pe) && pe.Status() >= 500 && pe.Status() <= 599:
+	default:
+		return 0, false
+	}
+	half := (backoffBase << retry) / 2
+	return half + r.jitter(half), true
+}
+
+// sleep waits d or until ctx is done, returning ctx's error in that case.
+func sleep(ctx context.Context, d time.Duration) error {
+	t := time.NewTimer(d)
+	defer t.Stop()
+	select {
+	case <-t.C:
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}

internal/ai/llm/retry_test.go

@@ -0,0 +1,359 @@
+package llm
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"slices"
+	"testing"
+	"time"
+)
+
+// fakeClock is a clock whose sleeps return at once, advance it and are
+// recorded.
+type fakeClock struct {
+	t      time.Time
+	sleeps []time.Duration
+}
+
+func (c *fakeClock) now() time.Time { return c.t }
+
+func (c *fakeClock) sleep(ctx context.Context, d time.Duration) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	c.sleeps = append(c.sleeps, d)
+	c.t = c.t.Add(d)
+	return nil
+}
+
+// newTestRetrying returns a Retrying over a fresh Fake with a fake clock
+// at the real current time, so real context deadlines compare sensibly,
+// and jitter that always returns its maximum.
+func newTestRetrying() (*Retrying, *Fake, *fakeClock) {
+	f := &Fake{}
+	c := &fakeClock{t: time.Now()}
+	r := NewRetrying(f)
+	r.now = c.now
+	r.sleep = c.sleep
+	r.jitter = func(n time.Duration) time.Duration { return n - 1 }
+	return r, f, c
+}
+
+var retryReq = Request{Messages: []Message{{Role: RoleUser, Content: "plan dinners"}}}
+
+func ok(text string) GenerateResult { return GenerateResult{Response: Response{Text: text}} }
+
+func fail(err error) GenerateResult { return GenerateResult{Err: err} }
+
+func assertConsumed(t *testing.T, f *Fake, attempts int) {
+	t.Helper()
+	if g, _, _ := f.Remaining(); g != 0 {
+		t.Errorf("%d scripted Generate results unused", g)
+	}
+	if n := len(f.Requests()); n != attempts {
+		t.Errorf("made %d attempts, want %d", n, attempts)
+	}
+}
+
+func TestRetryingRateLimitedThenSuccess(t *testing.T) {
+	r, f, c := newTestRetrying()
+	f.QueueGenerate(fail(NewRateLimitedError(3*time.Second, "")), ok("dinner"))
+
+	resp, err := r.Generate(context.Background(), retryReq)
+	if err != nil || resp.Text != "dinner" {
+		t.Fatalf("Generate = %+v, %v", resp, err)
+	}
+	if want := []time.Duration{3 * time.Second}; !slices.Equal(c.sleeps, want) {
+		t.Errorf("sleeps = %v, want %v", c.sleeps, want)
+	}
+	assertConsumed(t, f, 2)
+}
+
+func TestRetryingRateLimitedWaitIsCapped(t *testing.T) {
+	r, f, c := newTestRetrying()
+	f.QueueGenerate(fail(NewRateLimitedError(time.Hour, "")), ok("dinner"))
+
+	if _, err := r.Generate(context.Background(), retryReq); err != nil {
+		t.Fatal(err)
+	}
+	if want := []time.Duration{20 * time.Second}; !slices.Equal(c.sleeps, want) {
+		t.Errorf("sleeps = %v, want %v", c.sleeps, want)
+	}
+	assertConsumed(t, f, 2)
+}
+
+func TestRetryingRateLimitedWithoutRetryAfterBacksOff(t *testing.T) {
+	r, f, c := newTestRetrying()
+	f.QueueGenerate(fail(NewRateLimitedError(0, "")), ok("dinner"))
+
+	if _, err := r.Generate(context.Background(), retryReq); err != nil {
+		t.Fatal(err)
+	}
+	if want := []time.Duration{time.Second - 1}; !slices.Equal(c.sleeps, want) {
+		t.Errorf("sleeps = %v, want %v", c.sleeps, want)
+	}
+}
+
+func TestRetrying5xxTwiceThenSuccess(t *testing.T) {
+	r, f, c := newTestRetrying()
+	f.QueueGenerate(
+		fail(NewProviderError(503, []byte("busy"), "")),
+		// Adapters wrap the error they return.
+		fail(fmt.Errorf("openai: generate: %w", NewProviderError(503, []byte("busy"), ""))),
+		ok("dinner"),
+	)
+
+	resp, err := r.Generate(context.Background(), retryReq)
+	if err != nil || resp.Text != "dinner" {
+		t.Fatalf("Generate = %+v, %v", resp, err)
+	}
+	// Max jitter: [0.5 s, 1 s) then [1 s, 2 s).
+	if want := []time.Duration{time.Second - 1, 2*time.Second - 1}; !slices.Equal(c.sleeps, want) {
+		t.Errorf("sleeps = %v, want %v", c.sleeps, want)
+	}
+	assertConsumed(t, f, 3)
+}
+
+func TestRetryingBackoffJitterLowerBound(t *testing.T) {
+	r, f, c := newTestRetrying()
+	r.jitter = func(time.Duration) time.Duration { return 0 }
+	f.QueueGenerate(fail(ErrTimeout), fail(ErrTimeout), ok("dinner"))
+
+	if _, err := r.Generate(context.Background(), retryReq); err != nil {
+		t.Fatal(err)
+	}
+	if want := []time.Duration{500 * time.Millisecond, time.Second}; !slices.Equal(c.sleeps, want) {
+		t.Errorf("sleeps = %v, want %v", c.sleeps, want)
+	}
+}
+
+func TestRetrying5xxThreeTimesFails(t *testing.T) {
+	r, f, c := newTestRetrying()
+	last := NewProviderError(503, []byte("third"), "")
+	f.QueueGenerate(
+		fail(NewProviderError(503, []byte("first"), "")),
+		fail(NewProviderError(503, []byte("second"), "")),
+		fail(last),
+	)
+
+	_, err := r.Generate(context.Background(), retryReq)
+	if err != last {
+		t.Fatalf("err = %v, want the last attempt's error", err)
+	}
+	if len(c.sleeps) != MaxRetries {
+		t.Errorf("slept %d times, want %d", len(c.sleeps), MaxRetries)
+	}
+	assertConsumed(t, f, 3)
+}
+
+func TestRetryingDoesNotRetryPermanentErrors(t *testing.T) {
+	for name, err := range map[string]error{
+		"401 auth":    ErrAuth,
+		"400":         NewProviderError(400, []byte("bad request"), ""),
+		"404":         NewProviderError(404, []byte("no such model"), ""),
+		"408":         NewTimeoutStatusError(408, ""),
+		"wrapped 408": fmt.Errorf("openai: generate: %w", NewTimeoutStatusError(408, "")),
+		"bad output":  ErrBadOutput,
+		"other":       errors.New("llm: request has no messages"),
+	} {
+		t.Run(name, func(t *testing.T) {
+			r, f, c := newTestRetrying()
+			f.QueueGenerate(fail(err))
+
+			if _, got := r.Generate(context.Background(), retryReq); got != err {
+				t.Fatalf("err = %v, want %v", got, err)
+			}
+			if len(c.sleeps) != 0 {
+				t.Errorf("slept %v", c.sleeps)
+			}
+			assertConsumed(t, f, 1)
+		})
+	}
+}
+
+// A transport timeout matches ErrTimeout like an HTTP 408, but carries no
+// status, so it is retried.
+func TestRetryingTransportTimeoutRetried(t *testing.T) {
+	r, f, _ := newTestRetrying()
+	f.QueueGenerate(fail(fmt.Errorf("openai: generate: %w", ErrTimeout)), ok("dinner"))
+
+	if _, err := r.Generate(context.Background(), retryReq); err != nil {
+		t.Fatal(err)
+	}
+	assertConsumed(t, f, 2)
+}
+
+func TestRetryingDeadlineShorterThanRetryAfter(t *testing.T) {
+	r, f, c := newTestRetrying()
+	rl := NewRateLimitedError(10*time.Second, "")
+	f.QueueGenerate(fail(rl))
+	ctx, cancel := context.WithDeadline(context.Background(), c.t.Add(5*time.Second))
+	defer cancel()
+
+	if _, err := r.Generate(ctx, retryReq); err != rl {
+		t.Fatalf("err = %v, want the rate-limited error", err)
+	}
+	if len(c.sleeps) != 0 {
+		t.Errorf("slept %v", c.sleeps)
+	}
+	assertConsumed(t, f, 1)
+}
+
+func TestRetryingDeadlineShorterThanBackoff(t *testing.T) {
+	r, f, c := newTestRetrying()
+	f.QueueGenerate(fail(ErrTimeout))
+	// The first backoff with maximum jitter is just under 1 s.
+	ctx, cancel := context.WithDeadline(context.Background(), c.t.Add(time.Second-1))
+	defer cancel()
+
+	if _, err := r.Generate(ctx, retryReq); !errors.Is(err, ErrTimeout) {
+		t.Fatalf("err = %v, want ErrTimeout", err)
+	}
+	if len(c.sleeps) != 0 {
+		t.Errorf("slept %v", c.sleeps)
+	}
+	assertConsumed(t, f, 1)
+}
+
+func TestRetryingRetriesWithinDeadline(t *testing.T) {
+	r, f, c := newTestRetrying()
+	f.QueueGenerate(fail(NewRateLimitedError(3*time.Second, "")), ok("dinner"))
+	ctx, cancel := context.WithDeadline(context.Background(), c.t.Add(time.Minute))
+	defer cancel()
+
+	if _, err := r.Generate(ctx, retryReq); err != nil {
+		t.Fatal(err)
+	}
+	assertConsumed(t, f, 2)
+}
+
+func TestRetryingStopsWhenContextDone(t *testing.T) {
+	r, f, _ := newTestRetrying()
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	f.QueueGenerate(fail(ErrTimeout))
+
+	if _, err := r.Generate(ctx, retryReq); !errors.Is(err, ErrTimeout) {
+		t.Fatalf("err = %v, want ErrTimeout", err)
+	}
+	assertConsumed(t, f, 1)
+}
+
+// slowProvider is a Provider whose every attempt takes d on clock c,
+// records the deadline of the context it received, and times out.
+type slowProvider struct {
+	Provider
+	c         *fakeClock
+	d         time.Duration
+	reqs      []Request
+	deadlines []time.Time
+}
+
+func (p *slowProvider) Generate(ctx context.Context, req Request) (Response, error) {
+	p.reqs = append(p.reqs, req)
+	deadline, _ := ctx.Deadline()
+	p.deadlines = append(p.deadlines, deadline)
+	p.c.t = p.c.t.Add(p.d)
+	return Response{}, ErrTimeout
+}
+
+func TestRetryingTimeoutBoundsWholeCall(t *testing.T) {
+	for _, tc := range []struct {
+		name    string
+		timeout time.Duration
+		want    time.Duration
+	}{
+		{"default", 0, 60 * time.Second},
+		{"custom", 10 * time.Second, 10 * time.Second},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			r, _, c := newTestRetrying()
+			// Each attempt uses most of the one deadline, so a fresh full
+			// timeout per attempt would allow every retry; one deadline
+			// leaves room for exactly one.
+			p := &slowProvider{c: c, d: tc.want * 5 / 6}
+			r.Provider = p
+			start := c.t
+			req := retryReq
+			req.Timeout = tc.timeout
+
+			if _, err := r.Generate(context.Background(), req); !errors.Is(err, ErrTimeout) {
+				t.Fatalf("err = %v, want ErrTimeout", err)
+			}
+			if len(p.deadlines) != 2 {
+				t.Fatalf("made %d attempts, want 2", len(p.deadlines))
+			}
+			for i, d := range p.deadlines {
+				if !d.Equal(start.Add(tc.want)) {
+					t.Errorf("attempt %d deadline = start+%v, want start+%v", i, d.Sub(start), tc.want)
+				}
+				if p.reqs[i].Timeout != 0 {
+					t.Errorf("attempt %d Timeout = %v, want 0", i, p.reqs[i].Timeout)
+				}
+			}
+			if want := []time.Duration{time.Second - 1}; !slices.Equal(c.sleeps, want) {
+				t.Errorf("sleeps = %v, want %v", c.sleeps, want)
+			}
+		})
+	}
+}
+
+func TestRetryingCallerDeadlineShorterThanTimeout(t *testing.T) {
+	r, _, c := newTestRetrying()
+	p := &slowProvider{c: c, d: time.Second}
+	r.Provider = p
+	ctx, cancel := context.WithDeadline(context.Background(), c.t.Add(5*time.Second))
+	defer cancel()
+
+	if _, err := r.Generate(ctx, retryReq); !errors.Is(err, ErrTimeout) {
+		t.Fatalf("err = %v, want ErrTimeout", err)
+	}
+	for i, d := range p.deadlines {
+		if want, _ := ctx.Deadline(); !d.Equal(want) {
+			t.Errorf("attempt %d deadline = %v, want caller's %v", i, d, want)
+		}
+	}
+}
+
+func TestRetryingRejectsNegativeTimeout(t *testing.T) {
+	r, f, _ := newTestRetrying()
+	f.QueueGenerate(fail(errors.New("llm: timeout is negative")))
+	req := retryReq
+	req.Timeout = -time.Second
+
+	if _, err := r.Generate(context.Background(), req); err == nil {
+		t.Fatal("Generate accepted a negative timeout")
+	}
+	assertConsumed(t, f, 1)
+	if got := f.Requests()[0].Timeout; got != -time.Second {
+		t.Errorf("wrapped Provider got Timeout %v, want -1s to reject", got)
+	}
+}
+
+func TestRetryingPassesThroughListModelsAndVerify(t *testing.T) {
+	r, f, _ := newTestRetrying()
+	f.QueueListModels(ListModelsResult{Err: ErrTimeout})
+	f.QueueVerify(ErrTimeout)
+
+	if _, err := r.ListModels(context.Background()); !errors.Is(err, ErrTimeout) {
+		t.Fatalf("ListModels err = %v", err)
+	}
+	if err := r.Verify(context.Background()); !errors.Is(err, ErrTimeout) {
+		t.Fatalf("Verify err = %v", err)
+	}
+	if _, l, v := f.Remaining(); l != 0 || v != 0 {
+		t.Fatalf("Remaining = %d, %d", l, v)
+	}
+}
+
+func TestSleepStopsWhenContextDone(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	if err := sleep(ctx, time.Hour); !errors.Is(err, context.Canceled) {
+		t.Fatalf("sleep err = %v", err)
+	}
+	if err := sleep(context.Background(), time.Millisecond); err != nil {
+		t.Fatalf("sleep err = %v", err)
+	}
+}

web/package-lock.json

@@ -9,6 +9,7 @@
       "version": "0.0.0",
       "dependencies": {
         "@tanstack/react-query": "^5.104.1",
+        "lucide-react": "^1.51.0",
         "react": "^19.3.0",
         "react-dom": "^19.3.0",
         "react-router": "^7.18.4"
@@ -736,7 +737,7 @@
       "version": "19.3.0",
       "resolved": "https://registry.npmjs.org/@types/react/-/react-19.3.0.tgz",
       "integrity": "sha512-N0rFCuH9YoxG9/m61l9MfpJKfmLOVU0em7ipIz6TRgSSkvReLB9vL85GB+yr8Bs5leqpvg96JSwF4ZS1s4viQg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "csstype": "^3.2.2"
@@ -1261,7 +1262,7 @@
       "version": "3.2.3",
       "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
       "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT"
     },
     "node_modules/data-urls": {
@@ -1760,6 +1761,21 @@
         "node": "20 || >=22"
       }
     },
+    "node_modules/lucide-react": {
+      "version": "1.51.0",
+      "resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-1.51.0.tgz",
+      "integrity": "sha512-9929jimol5y7VbXUlVKcgURMSeIxFJB7dtWCkRAaNnF7KiCRkSkhmqWPUmAmUFYPezNawFk6qvz3Mu0gEnfI4g==",
+      "license": "ISC",
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/lz-string": {
       "version": "1.5.0",
       "resolved": "https://registry.npmjs.org/lz-string/-/lz-string-1.5.0.tgz",

web/package.json

@@ -5,13 +5,16 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "tsc --noEmit && vite build",
+    "build": "npm run lint:colors && tsc --noEmit && vite build && npm run check:dist-fonts",
     "preview": "vite preview",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "npm run lint:colors && vitest run",
+    "lint:colors": "node scripts/lint-colors.mjs",
+    "check:dist-fonts": "node scripts/check-dist-fonts.mjs"
   },
   "dependencies": {
     "@tanstack/react-query": "^5.104.1",
+    "lucide-react": "^1.51.0",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
     "react-router": "^7.18.4"

web/scripts/check-dist-fonts.mjs

@@ -0,0 +1,32 @@
+// Fails when the production build references Google Fonts: fonts are
+// self-hosted, so dist must never point at fonts.googleapis.com or
+// fonts.gstatic.com.
+import { readFileSync, readdirSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const distDir = fileURLToPath(new URL('../dist', import.meta.url))
+const hosts = ['fonts.googleapis.com', 'fonts.gstatic.com']
+
+function* files(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) yield* files(path)
+    else yield path
+  }
+}
+
+const violations = []
+for (const path of files(distDir)) {
+  const content = readFileSync(path, 'latin1')
+  for (const host of hosts) {
+    if (content.includes(host)) violations.push(`${relative(distDir, path)}: ${host}`)
+  }
+}
+
+if (violations.length > 0) {
+  console.error('Production build references Google Fonts; fonts must be self-hosted:')
+  for (const v of violations) console.error(`  ${v}`)
+  process.exit(1)
+}
+console.log('check:dist-fonts: dist makes no Google Fonts requests')

web/scripts/lint-colors.mjs

@@ -0,0 +1,42 @@
+// Fails when a hex colour literal appears in any CSS or TypeScript file under
+// web/ outside the design tokens: every colour must come from a custom
+// property in tokens.css. Dependencies, build output and hidden directories
+// (tool caches) are not source and are skipped.
+import { readFileSync, readdirSync } from 'node:fs'
+import { extname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const webRoot = fileURLToPath(new URL('..', import.meta.url))
+const allowed = new Set(['src/styles/tokens.css'])
+const skippedDirs = new Set([join(webRoot, 'node_modules'), join(webRoot, 'dist')])
+const extensions = new Set(['.css', '.ts', '.tsx'])
+const hexColour = /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b/g
+
+function* sourceFiles(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (!skippedDirs.has(path) && !entry.name.startsWith('.')) yield* sourceFiles(path)
+    } else if (extensions.has(extname(entry.name))) yield path
+  }
+}
+
+const violations = []
+for (const path of sourceFiles(webRoot)) {
+  const name = relative(webRoot, path).split('\\').join('/')
+  if (allowed.has(name)) continue
+  readFileSync(path, 'utf8')
+    .split('\n')
+    .forEach((line, i) => {
+      for (const match of line.matchAll(hexColour)) {
+        violations.push(`${name}:${i + 1}: ${match[0]}`)
+      }
+    })
+}
+
+if (violations.length > 0) {
+  console.error('Hex colour literals found; use a token from src/styles/tokens.css:')
+  for (const v of violations) console.error(`  ${v}`)
+  process.exit(1)
+}
+console.log('lint:colors: no hex colour literals outside src/styles/tokens.css')

web/src/App.test.tsx

@@ -1,15 +1,101 @@
 import { render, screen } from '@testing-library/react'
 import { MemoryRouter } from 'react-router'
-import { describe, expect, it } from 'vitest'
-import App from './App.tsx'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createApiClient } from './api/index.ts'
+import { mockViewport } from './test/matchMedia.ts'
+import { errorResponse, fakeLocation, jsonResponse, ME, request, stubFetch } from './test/fetchStub.ts'
+import App, { routes } from './App.tsx'
 
-describe('App', () => {
-  it('renders the MealQuest shell', () => {
-    render(
-      <MemoryRouter>
-        <App />
-      </MemoryRouter>,
-    )
-    expect(screen.getByRole('heading', { name: 'MealQuest' })).toBeInTheDocument()
+afterEach(() => {
+  Reflect.deleteProperty(window, 'matchMedia')
+  vi.unstubAllGlobals()
+})
+
+function renderAt(path: string, location = fakeLocation(path)) {
+  render(
+    <MemoryRouter initialEntries={[path]}>
+      <App api={createApiClient(location)} />
+    </MemoryRouter>,
+  )
+  return location
+}
+
+describe('App routes', () => {
+  it('registers every handoff route plus the extra settings pages', () => {
+    expect(routes.map((route) => route.path)).toEqual([
+      '/',
+      '/onboarding',
+      '/plan',
+      '/plan/shopping',
+      '/plan/shopping/archive',
+      '/discover',
+      '/quick',
+      '/cook-from-pantry',
+      '/dinner/:id',
+      '/settings',
+      '/settings/notifications',
+      '/settings/ai',
+      '/settings/household',
+      '/settings/regulars',
+      '/settings/calendar',
+    ])
+  })
+
+  it.each(routes.map(({ path, title }) => [path.replace(':id', 'abc123'), title]))(
+    '%s renders its placeholder page inside the shell',
+    async (path, title) => {
+      mockViewport(390)
+      stubFetch(jsonResponse(200, ME))
+      renderAt(path)
+      const heading = await screen.findByRole('heading', { level: 1, name: title })
+      expect(screen.getByRole('main')).toContainElement(heading)
+      expect(screen.getByRole('navigation', { name: 'Primary' })).toBeInTheDocument()
+    },
+  )
+})
+
+describe('App bootstrap', () => {
+  it('shows the skeleton until /me loads, then the routes', async () => {
+    mockViewport(390)
+    const fetchMock = stubFetch(jsonResponse(200, ME))
+    renderAt('/plan')
+
+    expect(screen.getByRole('main', { name: 'Loading MealQuest' })).toHaveAttribute('aria-busy', 'true')
+    expect(screen.queryByRole('navigation', { name: 'Primary' })).not.toBeInTheDocument()
+
+    expect(await screen.findByRole('heading', { level: 1, name: 'Plan' })).toBeInTheDocument()
+    expect(screen.queryByRole('main', { name: 'Loading MealQuest' })).not.toBeInTheDocument()
+    expect(request(fetchMock, 0)).toMatchObject({ path: '/api/v1/me', method: 'GET', credentials: 'same-origin' })
+  })
+
+  it('sends a signed-out visitor to sign-in and never renders the routes', async () => {
+    const fetchMock = stubFetch(errorResponse(401, 'unauthenticated'))
+    const location = renderAt('/discover', fakeLocation('/discover', '?swipe=1'))
+
+    await vi.waitFor(() => expect(location.assign).toHaveBeenCalledWith('/auth/login?return=%2Fdiscover%3Fswipe%3D1'))
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(screen.getByRole('main', { name: 'Loading MealQuest' })).toBeInTheDocument()
+    expect(screen.queryByRole('navigation', { name: 'Primary' })).not.toBeInTheDocument()
+  })
+
+  it('shows the not-in-this-household screen on a 403', async () => {
+    const fetchMock = stubFetch(errorResponse(403, 'forbidden'))
+    const location = renderAt('/')
+
+    expect(await screen.findByText(/not in this household/)).toBeInTheDocument()
+    expect(screen.getByRole('heading', { name: 'Not in this household' })).toBeInTheDocument()
+    expect(screen.queryByRole('navigation', { name: 'Primary' })).not.toBeInTheDocument()
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(location.assign).not.toHaveBeenCalled()
+  })
+
+  it('reports a /me failure with a retry instead of rendering the routes', async () => {
+    mockViewport(390)
+    stubFetch(errorResponse(500, 'internal'), jsonResponse(200, ME))
+    renderAt('/')
+
+    expect(await screen.findByRole('alert')).toHaveTextContent('MealQuest could not load: internal message')
+    screen.getByRole('button', { name: 'Retry' }).click()
+    expect(await screen.findByRole('heading', { level: 1, name: 'Home' })).toBeInTheDocument()
   })
 })

web/src/App.tsx

@@ -1,25 +1,58 @@
 import { useState } from 'react'
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { QueryClientProvider } from '@tanstack/react-query'
 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 { AppShell } from './shell/AppShell.tsx'
 
-// Placeholder shell only: no product UI, auth or API calls yet.
-function Shell() {
+// Every route the app serves, with the heading its placeholder page shows.
+export const routes = [
+  { path: '/', title: 'Home' },
+  { path: '/onboarding', title: 'Onboarding' },
+  { path: '/plan', title: 'Plan' },
+  { path: '/plan/shopping', title: 'Supply run' },
+  { path: '/plan/shopping/archive', title: 'Supply archive' },
+  { path: '/discover', title: 'Discover' },
+  { path: '/quick', title: 'Quick dinners' },
+  { path: '/cook-from-pantry', title: 'Cook from what I have' },
+  { path: '/dinner/:id', title: 'Dinner' },
+  { path: '/settings', title: 'Settings' },
+  { path: '/settings/notifications', title: 'Notifications' },
+  { path: '/settings/ai', title: 'AI assistant' },
+  { path: '/settings/household', title: 'Household' },
+  { path: '/settings/regulars', title: 'Regulars' },
+  { path: '/settings/calendar', title: 'Calendar' },
+] as const
+
+// AppRoutes is the shell and its pages, shown once /api/v1/me has loaded.
+export function AppRoutes() {
   return (
-    <main>
-      <h1>MealQuest</h1>
-    </main>
+    <Routes>
+      <Route element={<AppShell />}>
+        {routes.map(({ path, title }) => (
+          <Route key={path} path={path} element={<PlaceholderPage title={title} />} />
+        ))}
+      </Route>
+    </Routes>
   )
 }
 
+export type AppProps = {
+  api: ApiClient
+}
+
 // App expects to be rendered inside a router (BrowserRouter in main.tsx,
 // MemoryRouter in tests).
-export default function App() {
-  const [queryClient] = useState(() => new QueryClient())
+export default function App({ api }: AppProps) {
+  const [queryClient] = useState(createQueryClient)
   return (
-    <QueryClientProvider client={queryClient}>
-      <Routes>
-        <Route path="*" element={<Shell />} />
-      </Routes>
-    </QueryClientProvider>
+    <ApiProvider client={api}>
+      <QueryClientProvider client={queryClient}>
+        <AuthBootstrap>
+          <AppRoutes />
+        </AuthBootstrap>
+      </QueryClientProvider>
+    </ApiProvider>
   )
 }

web/src/AuthBootstrap.tsx

@@ -0,0 +1,38 @@
+import { useSyncExternalStore, type ReactNode } from 'react'
+import { useQuery } from '@tanstack/react-query'
+import { ApiError, ME_PATH, useApi } from './api/index.ts'
+import { NotInHouseholdPage } from './pages/NotInHouseholdPage.tsx'
+import { ErrorBanner } from './ui/ErrorBanner.tsx'
+import { Skeleton } from './ui/Skeleton.tsx'
+import styles from './pages/FullScreen.module.css'
+
+export const meQueryKey = [ME_PATH] as const
+
+// AuthBootstrap loads GET /api/v1/me before rendering children. A 401 is
+// already navigating to sign-in, so the skeleton stays up; an account outside
+// the household sees only the "not in this household" screen.
+export function AuthBootstrap({ children }: { children: ReactNode }) {
+  const api = useApi()
+  const forbidden = useSyncExternalStore(api.subscribe, api.forbidden)
+  const me = useQuery({ queryKey: meQueryKey, queryFn: api.loadMe, staleTime: Infinity })
+
+  if (forbidden) return <NotInHouseholdPage />
+  if (me.isSuccess) return children
+  if (me.isError && !(me.error instanceof ApiError && me.error.status === 401)) {
+    return (
+      <main className={styles.screen}>
+        <ErrorBanner onRetry={() => void me.refetch()}>MealQuest could not load: {me.error.message}</ErrorBanner>
+      </main>
+    )
+  }
+  return (
+    <main className={styles.screen} aria-busy="true" aria-label="Loading MealQuest">
+      <div className={styles.loading}>
+        <Skeleton className={styles.title} />
+        <Skeleton />
+        <Skeleton />
+        <Skeleton />
+      </div>
+    </main>
+  )
+}

web/src/api/ApiContext.tsx

@@ -0,0 +1,15 @@
+import { createContext, useContext, type ReactNode } from 'react'
+import type { ApiClient } from './client.ts'
+
+const ApiContext = createContext<ApiClient | null>(null)
+
+export function ApiProvider({ client, children }: { client: ApiClient; children: ReactNode }) {
+  return <ApiContext.Provider value={client}>{children}</ApiContext.Provider>
+}
+
+// useApi returns the app's API client. It must be rendered inside ApiProvider.
+export function useApi(): ApiClient {
+  const client = useContext(ApiContext)
+  if (client === null) throw new Error('useApi: no ApiProvider above this component')
+  return client
+}

web/src/api/client.test.ts

@@ -0,0 +1,158 @@
+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'
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+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())
+    await api.loadMe()
+
+    await expect(api.apiFetch('/api/v1/settings/household')).resolves.toEqual({ ok: 1 })
+    await expect(
+      api.apiFetch('/api/v1/settings/household', { method: 'PATCH', body: { dinnerTime: '18:00' } }),
+    ).resolves.toEqual({ ok: 2 })
+
+    const get = request(fetchMock, 1)
+    expect(get).toMatchObject({ path: '/api/v1/settings/household', method: 'GET', credentials: 'same-origin' })
+    expect(get.headers.has(CSRF_HEADER)).toBe(false)
+
+    const patch = request(fetchMock, 2)
+    expect(patch).toMatchObject({ method: 'PATCH', credentials: 'same-origin', body: '{"dinnerTime":"18:00"}' })
+    expect(patch.headers.get(CSRF_HEADER)).toBe('token-1')
+    expect(patch.headers.get('Content-Type')).toBe('application/json')
+  })
+
+  it('refuses a non-GET request before /me has loaded', async () => {
+    const fetchMock = stubFetch()
+    const api = createApiClient(fakeLocation())
+    await expect(api.apiFetch('/api/v1/jobs', { method: 'POST', body: {} })).rejects.toThrow(/no CSRF token/)
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it.each([
+    'https://evil.example/api/v1/me',
+    '//evil.example/api/v1/me',
+    // The placeholder origin an earlier guard compared against.
+    '//same-origin.invalid/api/v1/me',
+    'https://same-origin.invalid/api/v1/me',
+    '/\\evil.example/api/v1/me',
+    '/auth/logout',
+    '/api/v1/../auth/logout',
+    '/api/v1/%2e%2e/auth/logout',
+    'api/v1/me',
+  ])('refuses %s without sending it or the CSRF token', async (path) => {
+    const fetchMock = stubFetch(jsonResponse(200, ME))
+    const api = createApiClient(fakeLocation())
+    await api.loadMe()
+
+    await expect(api.apiFetch(path, { method: 'POST', body: {} })).rejects.toThrow(
+      `POST ${path}: not a same-origin /api/v1/ path`,
+    )
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(request(fetchMock, 0)).toMatchObject({ path: '/api/v1/me', method: 'GET' })
+    expect(request(fetchMock, 0).headers.has(CSRF_HEADER)).toBe(false)
+  })
+
+  it('rejects with a typed ApiError from the error body', async () => {
+    stubFetch(errorResponse(503, 'unavailable', true))
+    const api = createApiClient(fakeLocation())
+    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 })
+  })
+
+  it('rejects a response without the API error body', async () => {
+    stubFetch(new Response('<html>bad gateway</html>', { status: 502 }))
+    const api = createApiClient(fakeLocation())
+    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)
+
+    await expect(api.apiFetch('/api/v1/settings/household')).rejects.toMatchObject({ status: 401 })
+    expect(location.assign).toHaveBeenCalledExactlyOnceWith(
+      '/auth/login?return=%2Fplan%2Fshopping%3Fweek%3D2026-10-05',
+    )
+  })
+
+  it('on a csrf 403 refreshes /me once and retries with the new token', async () => {
+    const fetchMock = stubFetch(
+      jsonResponse(200, ME),
+      errorResponse(403, 'csrf'),
+      jsonResponse(200, { ...ME, csrfToken: 'token-2' }),
+      jsonResponse(201, { id: 'j1' }),
+    )
+    const api = createApiClient(fakeLocation())
+    await api.loadMe()
+
+    await expect(api.apiFetch('/api/v1/jobs', { method: 'POST', body: { kind: 'noop' } })).resolves.toEqual({
+      id: 'j1',
+    })
+    expect(fetchMock).toHaveBeenCalledTimes(4)
+    expect(request(fetchMock, 1).headers.get(CSRF_HEADER)).toBe('token-1')
+    expect(request(fetchMock, 2)).toMatchObject({ path: '/api/v1/me', method: 'GET' })
+    expect(request(fetchMock, 3)).toMatchObject({ path: '/api/v1/jobs', method: 'POST', body: '{"kind":"noop"}' })
+    expect(request(fetchMock, 3).headers.get(CSRF_HEADER)).toBe('token-2')
+    expect(api.forbidden()).toBe(false)
+  })
+
+  it('does not loop when the retry gets a csrf 403 too', async () => {
+    const fetchMock = stubFetch(
+      jsonResponse(200, ME),
+      errorResponse(403, 'csrf'),
+      jsonResponse(200, { ...ME, csrfToken: 'token-2' }),
+      errorResponse(403, 'csrf'),
+    )
+    const api = createApiClient(fakeLocation())
+    await api.loadMe()
+
+    await expect(api.apiFetch('/api/v1/jobs', { method: 'POST', body: {} })).rejects.toMatchObject({
+      status: 403,
+      code: 'csrf',
+    })
+    expect(fetchMock).toHaveBeenCalledTimes(4)
+    expect(api.forbidden()).toBe(false)
+  })
+
+  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 listener = vi.fn()
+    api.subscribe(listener)
+
+    await expect(api.apiFetch('/api/v1/me')).rejects.toMatchObject({ status: 403, code: 'forbidden' })
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(api.forbidden()).toBe(true)
+    expect(listener).toHaveBeenCalledTimes(1)
+  })
+
+  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())
+    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())
+    await expect(api.loadMe()).rejects.toMatchObject({ status: 403, code: 'csrf' })
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('loadMe', () => {
+  it('rejects a /me response without a CSRF token', async () => {
+    stubFetch(jsonResponse(200, { ...ME, csrfToken: '' }))
+    const api = createApiClient(fakeLocation())
+    await expect(api.loadMe()).rejects.toThrow('response is not a member with a CSRF token')
+  })
+})

web/src/api/client.ts

@@ -0,0 +1,155 @@
+import { ApiError, isRecord, parseApiError } from './errors.ts'
+
+// CSRF_HEADER carries the session's CSRF token on every non-GET request.
+export const CSRF_HEADER = 'X-MealQuest-CSRF'
+
+export const ME_PATH = '/api/v1/me'
+
+// API_PREFIX is the only path apiFetch sends to.
+const API_PREFIX = '/api/v1/'
+
+// apiURL resolves path against the page origin and returns it as the
+// path-absolute URL to fetch. It refuses any path that would not resolve to a
+// same-origin URL under /api/v1/, so the CSRF token is never sent anywhere
+// else: absolute and protocol-relative URLs on another origin, and dot
+// segments that climb out of /api/v1/.
+function apiURL(origin: string, method: string, path: string): string {
+  const url = new URL(path, origin)
+  if (!path.startsWith('/') || url.origin !== origin || !url.pathname.startsWith(API_PREFIX)) {
+    throw new Error(`${method} ${path}: not a same-origin ${API_PREFIX} path`)
+  }
+  return url.pathname + url.search
+}
+
+// Me is the GET /api/v1/me response: the signed-in member, the household and
+// the session's CSRF token.
+export type Me = {
+  name: string
+  email: string
+  household: { label: string }
+  csrfToken: string
+}
+
+// ApiLocation is the part of window.location the client reads and navigates.
+// origin is the page origin every request must stay on.
+export type ApiLocation = Pick<Location, 'origin' | 'pathname' | 'search' | 'assign'>
+
+export type ApiRequest = {
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+  // Sent as JSON.
+  body?: unknown
+}
+
+export type ApiClient = {
+  // apiFetch sends a same-origin JSON request to path, which must be under
+  // /api/v1/, and resolves with the decoded response body, or rejects with an
+  // ApiError.
+  apiFetch<T>(path: string, request?: ApiRequest): Promise<T>
+  // loadMe fetches GET /api/v1/me and caches its CSRF token.
+  loadMe(): Promise<Me>
+  // forbidden reports whether a request was refused because the signed-in
+  // account is not in this household; subscribe is notified when it changes.
+  forbidden(): boolean
+  subscribe(listener: () => void): () => void
+}
+
+// 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 {
+  let csrfToken: string | null = null
+  let refreshing: Promise<Me> | null = null
+  let forbidden = false
+  const listeners = new Set<() => void>()
+
+  async function send(method: string, path: string, body: unknown): Promise<Response> {
+    const headers: Record<string, string> = { Accept: 'application/json' }
+    if (body !== undefined) headers['Content-Type'] = 'application/json'
+    if (method !== 'GET') {
+      if (csrfToken === null) {
+        throw new Error(`${method} ${path}: no CSRF token; ${ME_PATH} has not loaded`)
+      }
+      headers[CSRF_HEADER] = csrfToken
+    }
+    return fetch(path, {
+      method,
+      headers,
+      credentials: 'same-origin',
+      body: body === undefined ? undefined : JSON.stringify(body),
+    })
+  }
+
+  // refreshMe shares one in-flight /me request between every request that
+  // got a csrf 403 at the same time.
+  function refreshMe(): Promise<Me> {
+    refreshing ??= loadMe().finally(() => {
+      refreshing = null
+    })
+    return refreshing
+  }
+
+  async function apiFetch<T>(path: string, request: ApiRequest = {}): Promise<T> {
+    const method = request.method ?? 'GET'
+    const url = apiURL(location.origin, method, path)
+    let response = await send(method, url, request.body)
+    if (response.status === 403) {
+      const error = await parseForbidden(method, path, response)
+      // Only a non-GET carries the token, so only it can be refused for it.
+      if (error.code !== 'csrf' || method === 'GET') throw error
+      // The session's token changed: refresh it once and retry once.
+      await refreshMe()
+      response = await send(method, url, request.body)
+      if (response.status === 403) throw await parseForbidden(method, path, response)
+    }
+    return decode<T>(method, path, response)
+  }
+
+  // parseForbidden reads a 403. Any API error other than csrf means the
+  // account is not in this household.
+  async function parseForbidden(method: string, path: string, response: Response): Promise<ApiError> {
+    const error = await parseApiError(method, path, response)
+    if (error.code !== 'csrf') markForbidden()
+    return error
+  }
+
+  function markForbidden() {
+    if (forbidden) return
+    forbidden = true
+    listeners.forEach((listener) => listener())
+  }
+
+  async function decode<T>(method: string, path: string, response: Response): Promise<T> {
+    if (response.status === 401) {
+      location.assign(`/auth/login?return=${encodeURIComponent(location.pathname + location.search)}`)
+    }
+    if (!response.ok) throw await parseApiError(method, path, response)
+    if (response.status === 204) return undefined as T
+    return (await response.json()) as T
+  }
+
+  async function loadMe(): Promise<Me> {
+    const me = await apiFetch<unknown>(ME_PATH)
+    if (
+      !isRecord(me) ||
+      typeof me.name !== 'string' ||
+      typeof me.email !== 'string' ||
+      !isRecord(me.household) ||
+      typeof me.household.label !== 'string' ||
+      typeof me.csrfToken !== 'string' ||
+      me.csrfToken === ''
+    ) {
+      throw new Error(`GET ${ME_PATH}: response is not a member with a CSRF token`)
+    }
+    csrfToken = me.csrfToken
+    return me as Me
+  }
+
+  return {
+    apiFetch,
+    loadMe,
+    forbidden: () => forbidden,
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+  }
+}

web/src/api/errors.ts

@@ -0,0 +1,41 @@
+// ApiError is a failed API response carrying the server's
+// {"error":{"code","message","retryable"}} body.
+export class ApiError extends Error {
+  readonly status: number
+  readonly code: string
+  readonly retryable: boolean
+
+  constructor(status: number, code: string, message: string, retryable: boolean) {
+    super(message)
+    this.name = 'ApiError'
+    this.status = status
+    this.code = code
+    this.retryable = retryable
+  }
+}
+
+// parseApiError reads an error response body. A body that is not the API
+// error shape is itself an error: the server always sends one.
+export async function parseApiError(method: string, path: string, response: Response): Promise<ApiError> {
+  const text = await response.text()
+  let body: unknown
+  try {
+    body = JSON.parse(text)
+  } catch {
+    throw new Error(`${method} ${path}: ${response.status} response is not JSON: ${text.slice(0, 200)}`)
+  }
+  const error = isRecord(body) ? body.error : undefined
+  if (
+    !isRecord(error) ||
+    typeof error.code !== 'string' ||
+    typeof error.message !== 'string' ||
+    typeof error.retryable !== 'boolean'
+  ) {
+    throw new Error(`${method} ${path}: ${response.status} response has no API error body`)
+  }
+  return new ApiError(response.status, error.code, error.message, error.retryable)
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

web/src/api/index.ts

@@ -0,0 +1,5 @@
+export { ApiProvider, useApi } from './ApiContext.tsx'
+export { createApiClient, CSRF_HEADER, ME_PATH, type ApiClient, type ApiLocation, type ApiRequest, type Me } from './client.ts'
+export { ApiError } from './errors.ts'
+export { createQueryClient, shouldRetry } from './queryClient.ts'
+export { useJob, type Job, type JobState, type JobStatus } from './useJob.ts'

web/src/api/queryClient.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest'
+import { ApiError, createQueryClient, shouldRetry } from './index.ts'
+
+describe('query retries', () => {
+  it('retry only an ApiError the server marked retryable, a bounded number of times', () => {
+    expect(shouldRetry(0, new ApiError(503, 'unavailable', 'try later', true))).toBe(true)
+    expect(shouldRetry(3, new ApiError(503, 'unavailable', 'try later', true))).toBe(false)
+    expect(shouldRetry(0, new ApiError(401, 'unauthenticated', 'sign in required', false))).toBe(false)
+    expect(shouldRetry(0, new ApiError(403, 'csrf', 'bad token', false))).toBe(false)
+    expect(shouldRetry(0, new Error('network down'))).toBe(false)
+  })
+
+  it('are the QueryClient default for queries and mutations', () => {
+    const options = createQueryClient().getDefaultOptions()
+    expect(options.queries?.retry).toBe(shouldRetry)
+    expect(options.mutations?.retry).toBe(shouldRetry)
+  })
+})

web/src/api/queryClient.ts

@@ -0,0 +1,20 @@
+import { QueryClient } from '@tanstack/react-query'
+import { ApiError } from './errors.ts'
+
+// MAX_RETRIES bounds retries of a failure the server marked retryable.
+export const MAX_RETRIES = 3
+
+// shouldRetry retries only an ApiError the server marked retryable — never a
+// 401, a 403 or a malformed response.
+export function shouldRetry(failureCount: number, error: unknown): boolean {
+  return error instanceof ApiError && error.retryable && failureCount < MAX_RETRIES
+}
+
+export function createQueryClient(): QueryClient {
+  return new QueryClient({
+    defaultOptions: {
+      queries: { retry: shouldRetry, staleTime: 30_000 },
+      mutations: { retry: shouldRetry },
+    },
+  })
+}

web/src/api/useJob.test.tsx

@@ -0,0 +1,169 @@
+import { act, renderHook } from '@testing-library/react'
+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'
+
+type Draft = { dinners: string[] }
+
+function job(status: string, result: Draft | null, error: string | null = null) {
+  return jsonResponse(200, { id: 'j1', kind: 'plan.draft', status, result, error })
+}
+
+function renderJob(jobId: string | null) {
+  const api = createApiClient(fakeLocation())
+  const wrapper = ({ children }: { children: ReactNode }) => <ApiProvider client={api}>{children}</ApiProvider>
+  return renderHook(({ id }) => useJob<Draft>(id), { wrapper, initialProps: { id: jobId } })
+}
+
+// advance runs the timers due in ms and lets the polls they start answer.
+async function advance(ms: number) {
+  await act(() => vi.advanceTimersByTimeAsync(ms))
+}
+
+beforeEach(() => {
+  vi.useFakeTimers()
+})
+
+afterEach(() => {
+  vi.clearAllTimers()
+  vi.useRealTimers()
+  vi.unstubAllGlobals()
+})
+
+describe('useJob', () => {
+  it('exposes the partial result while running, then the terminal result, backing off 500 ms to 2 s', async () => {
+    const fetchMock = stubFetch(
+      job('queued', null),
+      job('running', { dinners: ['Tacos'] }),
+      job('running', { dinners: ['Tacos', 'Chili'] }),
+      job('running', { dinners: ['Tacos', 'Chili'] }),
+      job('succeeded', { dinners: ['Tacos', 'Chili', 'Soup'] }),
+    )
+    const { result } = renderJob('j1')
+    expect(result.current).toEqual({ status: undefined, result: null, error: null })
+
+    await advance(0)
+    expect(result.current.status).toBe('queued')
+    expect(request(fetchMock, 0)).toMatchObject({ path: '/api/v1/jobs/j1', method: 'GET' })
+
+    await advance(499)
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    await advance(1)
+    expect(result.current).toEqual({ status: 'running', result: { dinners: ['Tacos'] }, error: null })
+
+    await advance(999)
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+    await advance(1)
+    expect(result.current.result).toEqual({ dinners: ['Tacos', 'Chili'] })
+
+    await advance(2000)
+    expect(fetchMock).toHaveBeenCalledTimes(4)
+    await advance(2000)
+    expect(fetchMock).toHaveBeenCalledTimes(5)
+    expect(result.current).toEqual({
+      status: 'succeeded',
+      result: { dinners: ['Tacos', 'Chili', 'Soup'] },
+      error: null,
+    })
+
+    // Terminal: no timer left, no further polls.
+    expect(vi.getTimerCount()).toBe(0)
+    await advance(10_000)
+    expect(fetchMock).toHaveBeenCalledTimes(5)
+  })
+
+  it('exposes a failed job as its error and stops', async () => {
+    const fetchMock = stubFetch(job('running', { dinners: ['Tacos'] }), job('failed', null, 'model refused'))
+    const { result } = renderJob('j1')
+
+    await advance(0)
+    await advance(500)
+    expect(result.current.status).toBe('failed')
+    expect(result.current.error?.message).toBe('model refused')
+    expect(vi.getTimerCount()).toBe(0)
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('exposes a failed poll as the error and keeps polling to the terminal status', async () => {
+    const fetchMock = stubFetch(
+      job('running', { dinners: ['Tacos'] }),
+      errorResponse(503, 'unavailable', true),
+      job('succeeded', { dinners: ['Tacos', 'Chili'] }),
+    )
+    const { result } = renderJob('j1')
+
+    await advance(0)
+    await advance(500)
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+    expect(result.current).toMatchObject({ status: 'running', result: { dinners: ['Tacos'] } })
+    expect(result.current.error).toMatchObject({ status: 503, code: 'unavailable' })
+    expect(vi.getTimerCount()).toBe(1)
+
+    // The backoff carries on from the failed poll: the next one is 1 s later.
+    await advance(999)
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+    await advance(1)
+    expect(fetchMock).toHaveBeenCalledTimes(3)
+    expect(result.current).toEqual({ status: 'succeeded', result: { dinners: ['Tacos', 'Chili'] }, error: null })
+    expect(vi.getTimerCount()).toBe(0)
+  })
+
+  it('stops polling on unmount after a failed poll', async () => {
+    const fetchMock = stubFetch(errorResponse(503, 'unavailable', true))
+    const { result, unmount } = renderJob('j1')
+
+    await advance(0)
+    expect(result.current).toMatchObject({ status: undefined, result: null })
+    expect(result.current.error).toMatchObject({ status: 503 })
+    expect(vi.getTimerCount()).toBe(1)
+    unmount()
+    expect(vi.getTimerCount()).toBe(0)
+    await advance(10_000)
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('stops polling the old job when the job id changes', async () => {
+    const fetchMock = stubFetch(job('running', null), job('running', null))
+    const { result, rerender } = renderJob('j1')
+
+    await advance(0)
+    rerender({ id: 'j2' })
+    expect(result.current).toEqual({ status: undefined, result: null, error: null })
+    await advance(0)
+    expect(request(fetchMock, 1).path).toBe('/api/v1/jobs/j2')
+    expect(vi.getTimerCount()).toBe(1)
+  })
+
+  it('stops polling on unmount', async () => {
+    const fetchMock = stubFetch(job('running', null))
+    const { unmount } = renderJob('j1')
+
+    await advance(0)
+    expect(vi.getTimerCount()).toBe(1)
+    unmount()
+    expect(vi.getTimerCount()).toBe(0)
+    await advance(10_000)
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('ignores a poll that answers after unmount', async () => {
+    let answer!: (response: Response) => void
+    const fetchMock = stubFetch()
+    fetchMock.mockImplementationOnce(() => new Promise((resolve) => (answer = resolve)))
+    const { result, unmount } = renderJob('j1')
+
+    unmount()
+    await act(async () => answer(await Promise.resolve(job('running', null))))
+    expect(vi.getTimerCount()).toBe(0)
+    expect(result.current.status).toBeUndefined()
+  })
+
+  it('polls nothing without a job id', async () => {
+    const fetchMock = stubFetch()
+    const { result } = renderJob(null)
+    await advance(5000)
+    expect(fetchMock).not.toHaveBeenCalled()
+    expect(result.current).toEqual({ status: undefined, result: null, error: null })
+  })
+})

web/src/api/useJob.ts

@@ -0,0 +1,83 @@
+import { useEffect, useState } from 'react'
+import { useApi } from './ApiContext.tsx'
+
+export type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed'
+
+// Job is the GET /api/v1/jobs/{id} response. result may be set while the job
+// is running (a partial result); error is set only when it failed.
+export type Job<R> = {
+  id: string
+  kind: string
+  status: JobStatus
+  result: R | null
+  error: string | null
+}
+
+export type JobState<R> = {
+  // undefined until the first poll answers.
+  status: JobStatus | undefined
+  // The latest result, partial while the job runs.
+  result: R | null
+  // The job's failure, or the latest polling request's own failure (cleared
+  // by the next poll that answers).
+  error: Error | null
+}
+
+// Polling starts at FIRST_DELAY_MS and doubles up to MAX_DELAY_MS.
+export const FIRST_DELAY_MS = 500
+export const MAX_DELAY_MS = 2000
+
+const idle = { status: undefined, result: null, error: null }
+
+function isTerminal(status: JobStatus): boolean {
+  return status === 'succeeded' || status === 'failed'
+}
+
+// useJob polls GET /api/v1/jobs/{jobId} until the job succeeds or fails,
+// backing off from 500 ms to 2 s. A failed poll is exposed as the error and
+// polling continues. Polling stops only at a terminal status, when jobId
+// changes and on unmount. A null jobId polls nothing.
+export function useJob<R>(jobId: string | null): JobState<R> {
+  const { apiFetch } = useApi()
+  const [state, setState] = useState<{ jobId: string | null; job: JobState<R> }>({ jobId, job: idle })
+
+  useEffect(() => {
+    if (jobId === null) return
+    let active = true
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let delay = FIRST_DELAY_MS
+
+    function next() {
+      timer = setTimeout(poll, delay)
+      delay = Math.min(delay * 2, MAX_DELAY_MS)
+    }
+
+    async function poll() {
+      try {
+        const job = await apiFetch<Job<R>>(`/api/v1/jobs/${encodeURIComponent(jobId!)}`)
+        if (!active) return
+        const error = job.status === 'failed' ? new Error(job.error ?? `job ${job.id} failed without an error message`) : null
+        setState({ jobId, job: { status: job.status, result: job.result, error } })
+        if (isTerminal(job.status)) return
+      } catch (error) {
+        if (!active) return
+        // A failed poll is not the job's end: keep the last known status and
+        // result, expose the request's error, and poll again.
+        setState((prev) => ({
+          jobId,
+          job: { ...(prev.jobId === jobId ? prev.job : idle), error: error instanceof Error ? error : new Error(String(error)) },
+        }))
+      }
+      next()
+    }
+
+    void poll()
+    return () => {
+      active = false
+      clearTimeout(timer)
+    }
+  }, [apiFetch, jobId])
+
+  // State left from a previous jobId is not this job's.
+  return state.jobId === jobId ? state.job : idle
+}

web/src/assets/fonts/BagelFatOne-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2022 The Bagel Fat Project Authors (https://github.com/JAMO-TYPEFACE/BagelFat)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

web/src/assets/fonts/Figtree-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2022 The Figtree Project Authors (https://github.com/erikdkennedy/figtree)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

web/src/main.tsx

@@ -1,17 +1,22 @@
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
 import { BrowserRouter } from 'react-router'
+import './styles/tokens.css'
+import './styles/base.css'
 import App from './App.tsx'
+import { createApiClient } from './api/index.ts'
 
 const root = document.getElementById('root')
 if (!root) {
   throw new Error('MealQuest: #root element missing from index.html')
 }
 
+const api = createApiClient(window.location)
+
 createRoot(root).render(
   <StrictMode>
     <BrowserRouter>
-      <App />
+      <App api={api} />
     </BrowserRouter>
   </StrictMode>,
 )

web/src/pages/FullScreen.module.css

@@ -0,0 +1,23 @@
+/* A full-viewport screen shown instead of the app shell. */
+.screen {
+  min-height: 100dvh;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  gap: var(--space-3);
+  padding: var(--space-8) var(--space-4);
+  background: var(--color-bg);
+}
+
+.loading {
+  width: min(100%, 480px);
+  margin: 0 auto;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+}
+
+.title {
+  height: 32px;
+  width: 60%;
+}

web/src/pages/NotInHouseholdPage.tsx

@@ -0,0 +1,14 @@
+import { EmptyState } from '../ui/EmptyState.tsx'
+import styles from './FullScreen.module.css'
+
+// Shown when the server refuses a signed-in account that is not in this
+// household. Nothing else renders: the account can do nothing here.
+export function NotInHouseholdPage() {
+  return (
+    <main className={styles.screen}>
+      <EmptyState title="Not in this household">
+        You are signed in, but this account is not in this household. Ask someone in Our kitchen to add it.
+      </EmptyState>
+    </main>
+  )
+}

web/src/pages/PlaceholderPage.tsx

@@ -0,0 +1,9 @@
+export type PlaceholderPageProps = {
+  // The route's screen name, shown as the page heading.
+  title: string
+}
+
+// Stands in for a screen until its feature is built.
+export function PlaceholderPage({ title }: PlaceholderPageProps) {
+  return <h1>{title}</h1>
+}

web/src/shell/AppShell.module.css

@@ -0,0 +1,24 @@
+.shell {
+  position: relative;
+  height: 100dvh;
+  display: flex;
+  background: var(--color-bg);
+}
+
+.main {
+  flex: 1;
+  min-width: 0;
+  overflow-y: auto;
+}
+
+/* The bottom bar overlays the last 94 px of the screen (plus the safe area),
+   so the scroll area reserves at least 100 px beneath its content. */
+.mobile .main {
+  padding: 0 20px;
+  padding-bottom: calc(100px + env(safe-area-inset-bottom));
+}
+
+.tablet .main,
+.desktop .main {
+  padding: 32px 36px;
+}

web/src/shell/AppShell.test.tsx

@@ -0,0 +1,211 @@
+import { render, screen, within } from '@testing-library/react'
+import { MemoryRouter } from 'react-router'
+import { afterEach, describe, expect, it } from 'vitest'
+import { AppRoutes } from '../App.tsx'
+import { declaredStyle, outerSize } from '../test/cssRules.ts'
+import { expectMinHitArea } from '../test/hitArea.ts'
+import { mockViewport } from '../test/matchMedia.ts'
+import bottomBarStyles from './BottomBar.module.css'
+import railStyles from './Rail.module.css'
+import sidebarStyles from './Sidebar.module.css'
+
+const ORDER = ['Home', 'Plan', 'Discover', 'Quick', 'Settings']
+const MOBILE = 390
+const TABLET = 1180
+const DESKTOP = 1440
+
+afterEach(() => {
+  Reflect.deleteProperty(window, 'matchMedia')
+})
+
+function renderAt(path: string, width: number) {
+  const resize = mockViewport(width)
+  render(
+    <MemoryRouter initialEntries={[path]}>
+      <AppRoutes />
+    </MemoryRouter>,
+  )
+  return resize
+}
+
+function nav() {
+  return screen.getByRole('navigation', { name: 'Primary' })
+}
+
+function navLinks() {
+  return within(nav()).getAllByRole('link')
+}
+
+function current() {
+  return navLinks()
+    .filter((link) => link.getAttribute('aria-current') === 'page')
+    .map((link) => link.textContent)
+}
+
+describe('AppShell', () => {
+  it.each([MOBILE, TABLET, DESKTOP])('orders the nav Home · Plan · Discover · Quick · Settings at %i px', (width) => {
+    renderAt('/', width)
+    expect(navLinks().map((link) => link.textContent)).toEqual(ORDER)
+    expect(navLinks().map((link) => link.getAttribute('href'))).toEqual([
+      '/',
+      '/plan',
+      '/discover',
+      '/quick',
+      '/settings',
+    ])
+  })
+
+  it('shows only the mobile bottom bar below 768 px', () => {
+    renderAt('/', 767)
+    expect(screen.getAllByRole('navigation')).toHaveLength(1)
+    expect(nav()).toHaveClass(bottomBarStyles.bar!)
+    expect(screen.queryByText('M')).not.toBeInTheDocument()
+    expect(screen.queryByText('MealQuest')).not.toBeInTheDocument()
+    expect(screen.queryByText('Our kitchen')).not.toBeInTheDocument()
+
+    const bar = declaredStyle(nav())
+    expect(bar.position).toBe('absolute')
+    expect(bar.left).toBe('12px')
+    expect(bar.right).toBe('12px')
+    expect(bar.bottom).toBe('calc(16px + env(safe-area-inset-bottom))')
+    expect(bar.height).toBe('62px')
+    expect(outerSize(nav(), 'height')).toBe(62)
+    expect(bar.background).toBe('var(--color-text)')
+    expect(bar.borderRadius).toBe('var(--radius-pill)')
+  })
+
+  it('shows the active mobile item as icon and label over the one grape pill, inactive items as neutral icons', () => {
+    renderAt('/discover', MOBILE)
+    const pills = nav().querySelectorAll(`.${bottomBarStyles.pill}`)
+    expect(pills).toHaveLength(1)
+    const pill = declaredStyle(pills[0]!)
+    expect(pill.position).toBe('absolute')
+    expect(pill.top).toBe('10px')
+    expect(pill.height).toBe('42px')
+    expect(pill.background).toBe('var(--color-accent)')
+    expect(Number(pill.zIndex)).toBeLessThan(Number(declaredStyle(navLinks()[0]!).zIndex))
+
+    const active = screen.getByRole('link', { name: 'Discover' })
+    expect(declaredStyle(active).color).toBe('var(--on-accent)')
+    expect(within(active).getByText('Discover')).toHaveClass(bottomBarStyles.label!)
+    expect(declaredStyle(within(active).getByText('Discover')).fontSize).toBe('13px')
+
+    const inactive = screen.getByRole('link', { name: 'Plan' })
+    expect(declaredStyle(inactive).color).toBe('var(--color-neutral-400)')
+    expect(within(inactive).getByText('Plan')).toHaveClass(bottomBarStyles.hiddenLabel!)
+  })
+
+  it('makes the full 62 px bar height the mobile tap target', () => {
+    renderAt('/', MOBILE)
+    for (const link of navLinks()) {
+      expect(declaredStyle(link).height).toBe('62px')
+      expectMinHitArea(link)
+    }
+  })
+
+  it('reserves at least 100 px below the mobile scroll area', () => {
+    renderAt('/', MOBILE)
+    const padding = declaredStyle(screen.getByRole('main')).paddingBottom
+    const reserved = /^calc\((\d+)px \+ env\(safe-area-inset-bottom\)\)$/.exec(padding)
+    expect(reserved, `padding-bottom ${JSON.stringify(padding)}`).not.toBeNull()
+    expect(Number(reserved![1])).toBeGreaterThanOrEqual(100)
+  })
+
+  it.each([768, TABLET, 1199])('shows only the tablet rail with the "M" mark at %i px', (width) => {
+    renderAt('/plan', width)
+    expect(screen.getAllByRole('navigation')).toHaveLength(1)
+    expect(nav()).toHaveClass(railStyles.rail!)
+    expect(declaredStyle(nav()).width).toBe('96px')
+    expect(outerSize(nav(), 'width')).toBe(96)
+    expect(declaredStyle(nav()).background).toBe('var(--color-surface)')
+    const mark = within(nav()).getByText('M')
+    expect(declaredStyle(mark).width).toBe('48px')
+    expect(outerSize(mark, 'width')).toBe(48)
+    expect(outerSize(mark, 'height')).toBe(48)
+    expect(declaredStyle(mark).background).toBe('var(--color-accent)')
+    expect(screen.queryByText('MealQuest')).not.toBeInTheDocument()
+    expect(screen.queryByText('Our kitchen')).not.toBeInTheDocument()
+
+    for (const link of navLinks()) {
+      const pill = link.firstElementChild!
+      expect(declaredStyle(pill).width).toBe('56px')
+      expect(declaredStyle(pill).height).toBe('36px')
+      expect(outerSize(pill, 'width')).toBe(56)
+      expect(outerSize(pill, 'height')).toBe(36)
+      expect(declaredStyle(link).fontSize).toBe('11px')
+      expect(declaredStyle(link).fontWeight).toBe('700')
+      expectMinHitArea(link)
+    }
+    expect(screen.getByRole('link', { name: 'Plan' }).firstElementChild).toHaveClass(railStyles.active!)
+    expect(screen.getByRole('link', { name: 'Home' }).firstElementChild).not.toHaveClass(railStyles.active!)
+  })
+
+  it.each([1200, DESKTOP])('shows only the desktop sidebar with wordmark and household card at %i px', (width) => {
+    renderAt('/quick', width)
+    expect(screen.getAllByRole('navigation')).toHaveLength(1)
+    const sidebar = nav().closest('aside')!
+    expect(sidebar).toHaveClass(sidebarStyles.sidebar!)
+    expect(declaredStyle(sidebar).width).toBe('208px')
+    expect(declaredStyle(sidebar).background).toBe('var(--color-surface)')
+    expect(declaredStyle(sidebar).padding).toBe('28px 16px')
+    // The 16 px side padding sits inside the 208 px, not outside it.
+    expect(outerSize(sidebar, 'width')).toBe(208)
+
+    const wordmark = within(sidebar).getByText('MealQuest')
+    expect(declaredStyle(wordmark).fontFamily).toBe('var(--font-heading)')
+    expect(declaredStyle(wordmark).fontSize).toBe('28px')
+    expect(declaredStyle(wordmark).color).toBe('var(--color-accent)')
+
+    expect(within(sidebar).getByText('Our kitchen')).toBeInTheDocument()
+    expect(within(sidebar).getByText('Shared household')).toBeInTheDocument()
+    expect(screen.queryByText('M')).not.toBeInTheDocument()
+
+    const active = screen.getByRole('link', { name: 'Quick' })
+    expect(active).toHaveClass(sidebarStyles.active!)
+    expect(declaredStyle(active).background).toBe('var(--color-accent)')
+    expect(declaredStyle(active).color).toBe('var(--on-accent)')
+    expect(declaredStyle(active).fontSize).toBe('15px')
+    expect(screen.getByRole('link', { name: 'Home' })).not.toHaveClass(sidebarStyles.active!)
+    // Rows stretch across the sidebar, so only their height needs declaring.
+    for (const link of navLinks()) expect(declaredStyle(link).minHeight).toBe('44px')
+  })
+
+  it('switches layout when the viewport crosses a breakpoint', () => {
+    const resize = renderAt('/', MOBILE)
+    expect(nav()).toHaveClass(bottomBarStyles.bar!)
+    resize(TABLET)
+    expect(nav()).toHaveClass(railStyles.rail!)
+    resize(DESKTOP)
+    expect(nav().closest('aside')).toHaveClass(sidebarStyles.sidebar!)
+    resize(MOBILE)
+    expect(nav()).toHaveClass(bottomBarStyles.bar!)
+    expect(screen.getAllByRole('navigation')).toHaveLength(1)
+  })
+
+  describe.each([
+    ['mobile', MOBILE],
+    ['tablet', TABLET],
+    ['desktop', DESKTOP],
+  ])('aria-current (%s)', (_layout, width) => {
+    it.each([
+      ['/', ['Home']],
+      ['/plan', ['Plan']],
+      ['/plan/shopping', ['Plan']],
+      ['/plan/shopping/archive', ['Plan']],
+      ['/discover', ['Discover']],
+      ['/quick', ['Quick']],
+      ['/settings', ['Settings']],
+      ['/settings/notifications', ['Settings']],
+      ['/settings/ai', ['Settings']],
+      ['/settings/household', ['Settings']],
+      ['/settings/regulars', ['Settings']],
+      ['/settings/calendar', ['Settings']],
+      ['/onboarding', []],
+      ['/cook-from-pantry', []],
+      ['/dinner/abc123', []],
+    ])('%s marks %j current', (path, expected) => {
+      renderAt(path, width)
+      expect(current()).toEqual(expected)
+    })
+  })
+})

web/src/shell/AppShell.tsx

@@ -0,0 +1,22 @@
+import { Outlet } from 'react-router'
+import { BottomBar } from './BottomBar.tsx'
+import { Rail } from './Rail.tsx'
+import { Sidebar } from './Sidebar.tsx'
+import { useBreakpoint } from './useBreakpoint.ts'
+import styles from './AppShell.module.css'
+
+// The responsive frame around every page: one nav layout per breakpoint and a
+// scrolling main area for the routed page.
+export function AppShell() {
+  const breakpoint = useBreakpoint()
+  return (
+    <div className={`${styles.shell} ${styles[breakpoint]}`}>
+      {breakpoint === 'mobile' && <BottomBar />}
+      {breakpoint === 'tablet' && <Rail />}
+      {breakpoint === 'desktop' && <Sidebar />}
+      <main className={styles.main}>
+        <Outlet />
+      </main>
+    </div>
+  )
+}

web/src/shell/BottomBar.module.css

@@ -0,0 +1,65 @@
+.bar {
+  position: absolute;
+  left: 12px;
+  right: 12px;
+  bottom: calc(16px + env(safe-area-inset-bottom));
+  height: 62px;
+  padding: 0 6px;
+  box-sizing: border-box;
+  display: flex;
+  justify-content: space-around;
+  align-items: center;
+  border-radius: var(--radius-pill);
+  background: var(--color-text);
+}
+
+/* The one grape pill, shared by every item: BottomBar sets its left and width
+   to the active item's and slides it between items. */
+.pill {
+  position: absolute;
+  top: 10px;
+  height: 42px;
+  z-index: 0;
+  border-radius: var(--radius-pill);
+  background: var(--color-accent);
+  pointer-events: none;
+}
+
+/* The whole bar height is the tap target; the 42 px pill sits behind it.
+   Items stay above the pill. */
+.item {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  height: 62px;
+  min-width: 44px;
+  padding: 0 13px;
+  box-sizing: border-box;
+  color: var(--color-neutral-400);
+  text-decoration: none;
+  white-space: nowrap;
+  transition: color .2s;
+}
+
+.item[aria-current='page'] {
+  color: var(--on-accent);
+}
+
+.label {
+  font-family: var(--font-body);
+  font-size: 13px;
+  font-weight: 700;
+}
+
+/* Inactive items are icon-only on screen but keep their name for assistive tech. */
+.hiddenLabel {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}

web/src/shell/BottomBar.test.tsx

@@ -0,0 +1,282 @@
+import { fireEvent, render, screen, within } from '@testing-library/react'
+import { MemoryRouter } from 'react-router'
+import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from 'vitest'
+import { AppRoutes } from '../App.tsx'
+import { declaredStyle } from '../test/cssRules.ts'
+import { mockViewport } from '../test/matchMedia.ts'
+import styles from './BottomBar.module.css'
+
+const MOBILE = 390
+const SPRING = 'cubic-bezier(.34, 1.4, .64, 1)'
+
+// jsdom does no layout, so lay the bar out here: items sit side by side from
+// 6 px in, inactive items 48 px wide and the active one (icon + label) 110 px.
+function layOut(element: HTMLElement): { left: number; width: number } {
+  const bar = element.parentElement!
+  const items = Array.from(bar.querySelectorAll<HTMLElement>(`.${styles.item}`))
+  let left = 6
+  for (const item of items) {
+    const width = item.getAttribute('aria-current') === 'page' ? 110 : 48
+    if (item === element) return { left, width }
+    left += width
+  }
+  return { left: 0, width: 0 }
+}
+
+// jsdom paints nothing either, so bounding boxes come from the laid-out
+// offsets with the bar at the viewport's left edge. A test mid-slide sets
+// where the pill is drawn and how far each item is still translated.
+let drawnPill: { left: number; width: number } | null
+let translated: Map<Element, number>
+
+function box(left: number, width: number): DOMRect {
+  return { left, width, x: left, right: left + width, top: 0, y: 0, bottom: 0, height: 0 } as DOMRect
+}
+
+let animate: Mock<Element['animate']>
+
+beforeEach(() => {
+  drawnPill = null
+  translated = new Map()
+  // jsdom has no Web Animations API.
+  animate = vi.fn<Element['animate']>(() => ({ cancel: vi.fn() }) as unknown as Animation)
+  Element.prototype.animate = animate
+  vi.spyOn(Element.prototype, 'getBoundingClientRect').mockImplementation(function (this: Element) {
+    if (!(this instanceof HTMLElement)) return box(0, 0)
+    if (this.classList.contains(styles.pill!)) {
+      return drawnPill
+        ? box(drawnPill.left, drawnPill.width)
+        : box(parseFloat(this.style.left), parseFloat(this.style.width))
+    }
+    if (this.classList.contains(styles.item!)) {
+      return box(this.offsetLeft + (translated.get(this) ?? 0), this.offsetWidth)
+    }
+    return box(0, 0)
+  })
+  vi.spyOn(HTMLElement.prototype, 'offsetLeft', 'get').mockImplementation(function (this: HTMLElement) {
+    return layOut(this).left
+  })
+  vi.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockImplementation(function (this: HTMLElement) {
+    return layOut(this).width
+  })
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  Reflect.deleteProperty(Element.prototype, 'animate')
+  Reflect.deleteProperty(window, 'matchMedia')
+})
+
+function renderAt(path: string, reducedMotion = false) {
+  mockViewport(MOBILE, { reducedMotion })
+  render(
+    <MemoryRouter initialEntries={[path]}>
+      <AppRoutes />
+    </MemoryRouter>,
+  )
+}
+
+function nav() {
+  return screen.getByRole('navigation', { name: 'Primary' })
+}
+
+function pill(): HTMLElement {
+  return nav().querySelector<HTMLElement>(`.${styles.pill}`)!
+}
+
+function link(name: string): HTMLElement {
+  return within(nav()).getByRole('link', { name })
+}
+
+function runningOn(element: Element): Animation[] {
+  return animate.mock.contexts
+    .map((target, i) => ({ target, animation: animate.mock.results[i]!.value as Animation }))
+    .filter(({ target }) => target === element)
+    .map(({ animation }) => animation)
+}
+
+function animationsOf(element: Element) {
+  return animate.mock.contexts
+    .map((target, i) => ({ target, args: animate.mock.calls[i]! }))
+    .filter(({ target }) => target === element)
+    .map(({ args }) => ({ keyframes: args[0], options: args[1] as KeyframeAnimationOptions }))
+}
+
+describe('BottomBar', () => {
+  it('places the pill on the active item without animating on first render', () => {
+    renderAt('/plan')
+    expect(pill().style.left).toBe('54px')
+    expect(pill().style.width).toBe('110px')
+    expect(pill()).toBeVisible()
+    expect(animate).not.toHaveBeenCalled()
+  })
+
+  it('hides the pill when no item is active', () => {
+    renderAt('/onboarding')
+    expect(pill()).not.toBeVisible()
+  })
+
+  it('slides the pill from the old item to the new one over 420 ms on the spring curve', () => {
+    renderAt('/')
+    fireEvent.click(link('Quick'))
+
+    expect(animationsOf(pill())).toEqual([
+      {
+        keyframes: [
+          { left: '6px', width: '110px' },
+          { left: '150px', width: '110px' },
+        ],
+        options: { duration: 420, easing: SPRING },
+      },
+    ])
+    expect(pill().style.left).toBe('150px')
+    expect(pill().style.width).toBe('110px')
+  })
+
+  it('FLIPs every item that moved from its old left to its new one with the same timing', () => {
+    renderAt('/')
+    fireEvent.click(link('Quick'))
+
+    // Home shrinks from 110 to 48 px, so Plan and Discover shift 62 px left
+    // and Quick grows in place; Settings ends where it started.
+    for (const name of ['Plan', 'Discover']) {
+      expect(animationsOf(link(name))).toEqual([
+        {
+          keyframes: [{ transform: 'translateX(62px)' }, { transform: 'translateX(0)' }],
+          options: { duration: 420, easing: SPRING },
+        },
+      ])
+    }
+    expect(animationsOf(link('Quick'))).toEqual([
+      {
+        keyframes: [{ transform: 'translateX(62px)' }, { transform: 'translateX(0)' }],
+        options: { duration: 420, easing: SPRING },
+      },
+    ])
+    expect(animationsOf(link('Home'))).toEqual([])
+    expect(animationsOf(link('Settings'))).toEqual([])
+  })
+
+  it('fades the new label in over 220 ms ease-out after 120 ms', () => {
+    renderAt('/')
+    fireEvent.click(link('Discover'))
+
+    const label = within(link('Discover')).getByText('Discover')
+    expect(label).toHaveClass(styles.label!)
+    expect(animationsOf(label)).toEqual([
+      {
+        keyframes: [
+          { opacity: 0, transform: 'translateX(-4px)' },
+          { opacity: 1, transform: 'none' },
+        ],
+        options: { duration: 220, delay: 120, easing: 'ease-out', fill: 'backwards' },
+      },
+    ])
+  })
+
+  it('does not animate when the active item stays the same', () => {
+    renderAt('/plan')
+    fireEvent.click(link('Plan'))
+    expect(animate).not.toHaveBeenCalled()
+  })
+
+  it('jumps the pill to the new item with no animation under reduced motion', () => {
+    renderAt('/', true)
+    fireEvent.click(link('Settings'))
+
+    expect(link('Settings')).toHaveAttribute('aria-current', 'page')
+    expect(animate).not.toHaveBeenCalled()
+    expect(pill().style.left).toBe('198px')
+    expect(pill().style.width).toBe('110px')
+  })
+
+  it('re-places the pill when the viewport resizes', () => {
+    renderAt('/discover')
+    expect(pill().style.left).toBe('102px')
+    vi.spyOn(HTMLElement.prototype, 'offsetLeft', 'get').mockReturnValue(120)
+    vi.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockReturnValue(96)
+    fireEvent(window, new Event('resize'))
+    expect(pill().style.left).toBe('120px')
+    expect(pill().style.width).toBe('96px')
+    expect(animate).not.toHaveBeenCalled()
+  })
+
+  it('starts a second slide from where the first one is on screen, not from its destination', () => {
+    renderAt('/')
+    fireEvent.click(link('Quick'))
+    const [firstPill] = runningOn(pill())
+    const firstPlan = runningOn(link('Plan'))[0]!
+
+    // Midway: the pill is drawn at 78 px on its way from 6 to 150, and Plan
+    // still carries 31 of its 62 px FLIP translation.
+    drawnPill = { left: 78, width: 110 }
+    translated.set(link('Plan'), 31)
+    animate.mockClear()
+    fireEvent.click(link('Settings'))
+
+    expect(firstPill!.cancel).toHaveBeenCalled()
+    expect(firstPlan.cancel).toHaveBeenCalled()
+    expect(animationsOf(pill())).toEqual([
+      {
+        keyframes: [
+          { left: '78px', width: '110px' },
+          { left: '198px', width: '110px' },
+        ],
+        options: { duration: 420, easing: SPRING },
+      },
+    ])
+    // Plan's layout does not move between Quick and Settings, so it only
+    // finishes the 31 px it had left. Settings moves 62 px left.
+    expect(animationsOf(link('Plan'))).toEqual([
+      {
+        keyframes: [{ transform: 'translateX(31px)' }, { transform: 'translateX(0)' }],
+        options: { duration: 420, easing: SPRING },
+      },
+    ])
+    expect(animationsOf(link('Settings'))).toEqual([
+      {
+        keyframes: [{ transform: 'translateX(62px)' }, { transform: 'translateX(0)' }],
+        options: { duration: 420, easing: SPRING },
+      },
+    ])
+  })
+
+  it('stops a running slide and places the pill on the active item when the viewport resizes', () => {
+    renderAt('/')
+    fireEvent.click(link('Quick'))
+    const slide = [pill(), link('Plan'), link('Discover'), link('Quick')].flatMap(runningOn)
+    expect(slide).toHaveLength(4)
+
+    animate.mockClear()
+    vi.spyOn(HTMLElement.prototype, 'offsetLeft', 'get').mockReturnValue(140)
+    vi.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockReturnValue(96)
+    fireEvent(window, new Event('resize'))
+
+    for (const animation of slide) expect(animation.cancel).toHaveBeenCalled()
+    expect(animate).not.toHaveBeenCalled()
+    expect(pill().style.left).toBe('140px')
+    expect(pill().style.width).toBe('96px')
+  })
+
+  it('re-places the pill once the web fonts are ready', async () => {
+    let fontsReady!: () => void
+    const ready = new Promise<void>((resolve) => (fontsReady = resolve))
+    Object.defineProperty(document, 'fonts', { configurable: true, value: { ready } })
+    try {
+      renderAt('/discover')
+      vi.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockReturnValue(124)
+      fontsReady()
+      await ready
+      expect(pill().style.width).toBe('124px')
+    } finally {
+      Reflect.deleteProperty(document, 'fonts')
+    }
+  })
+
+  it('crossfades the icon colour with a .2s colour transition', () => {
+    renderAt('/')
+    for (const item of within(nav()).getAllByRole('link')) {
+      expect(declaredStyle(item).transition).toBe('color .2s')
+    }
+  })
+})

web/src/shell/BottomBar.tsx

@@ -0,0 +1,152 @@
+import { useLayoutEffect, useRef } from 'react'
+import { NavLink, useLocation } from 'react-router'
+import { Icon } from '../ui/Icon.tsx'
+import { navItems } from './navItems.ts'
+import styles from './BottomBar.module.css'
+
+// The handoff's Motion §1 timing. SPRING is the --ease-spring token's value.
+const SLIDE_MS = 420
+const SPRING = 'cubic-bezier(.34, 1.4, .64, 1)'
+const LABEL_MS = 220
+const LABEL_DELAY_MS = 120
+const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)'
+
+// The active item and every item's layout offset within the bar when the pill
+// was last placed (offsets ignore transforms, so a running FLIP does not skew
+// them).
+type Geometry = {
+  active: HTMLElement | null
+  itemLefts: number[]
+}
+
+// Mobile nav: a dark pill bar floating over the bottom of the screen. Inactive
+// items show only their icon; the active item adds its label. One shared
+// grape pill sits behind the items and slides to the active one.
+export function BottomBar() {
+  const barRef = useRef<HTMLElement>(null)
+  const pillRef = useRef<HTMLSpanElement>(null)
+  const placed = useRef<Geometry | null>(null)
+  // The pill slide and item FLIPs currently running.
+  const sliding = useRef<Animation[]>([])
+  const stopSlide = () => {
+    sliding.current.forEach((animation) => animation.cancel())
+    sliding.current = []
+  }
+  const { pathname } = useLocation()
+
+  // After each navigation: if the active item changed, move the pill to it and,
+  // motion allowed, slide the pill, FLIP the items and fade the label in. A
+  // slide still running is measured where it is on screen, then stopped, so
+  // the next one starts from there instead of from its destination.
+  useLayoutEffect(() => {
+    const bar = barRef.current!
+    const pill = pillRef.current!
+    const active = activeItem(bar)
+    const before = placed.current
+    if (before && before.active === active) return
+    const from = before && onScreen(bar, pill, before)
+    stopSlide()
+    placed.current = place(bar, pill, active)
+    if (!before || !from || !active || window.matchMedia(REDUCED_MOTION_QUERY).matches) return
+
+    const after = placed.current
+    if (before.active) {
+      sliding.current.push(
+        pill.animate(
+          [
+            { left: `${from.pill.left}px`, width: `${from.pill.width}px` },
+            { left: `${active.offsetLeft}px`, width: `${active.offsetWidth}px` },
+          ],
+          { duration: SLIDE_MS, easing: SPRING },
+        ),
+      )
+    }
+    items(bar).forEach((item, i) => {
+      const dx = from.itemLefts[i]! - after.itemLefts[i]!
+      if (dx === 0) return
+      sliding.current.push(
+        item.animate([{ transform: `translateX(${dx}px)` }, { transform: 'translateX(0)' }], {
+          duration: SLIDE_MS,
+          easing: SPRING,
+        }),
+      )
+    })
+    active.querySelector(`.${styles.label}`)!.animate(
+      [
+        { opacity: 0, transform: 'translateX(-4px)' },
+        { opacity: 1, transform: 'none' },
+      ],
+      { duration: LABEL_MS, delay: LABEL_DELAY_MS, easing: 'ease-out', fill: 'backwards' },
+    )
+  }, [pathname])
+
+  // Item widths change with the viewport and once the web fonts arrive, so
+  // stop any running slide and re-place the pill (without animating) on both. A failed font load
+  // rejects fonts.ready and is left to surface as an unhandled rejection.
+  useLayoutEffect(() => {
+    const bar = barRef.current!
+    const pill = pillRef.current!
+    let mounted = true
+    const replace = () => {
+      if (!mounted) return
+      stopSlide()
+      placed.current = place(bar, pill, activeItem(bar))
+    }
+    window.addEventListener('resize', replace)
+    // jsdom has no document.fonts; every browser the app targets does.
+    if (document.fonts) void document.fonts.ready.then(replace)
+    return () => {
+      mounted = false
+      window.removeEventListener('resize', replace)
+    }
+  }, [])
+
+  return (
+    <nav ref={barRef} aria-label="Primary" className={styles.bar}>
+      <span ref={pillRef} className={styles.pill} aria-hidden="true" />
+      {navItems.map((item) => (
+        <NavLink key={item.to} to={item.to} end={item.end} className={styles.item}>
+          {({ isActive }) => (
+            <>
+              <Icon icon={item.icon} size="nav" />
+              <span className={isActive ? styles.label : styles.hiddenLabel}>{item.label}</span>
+            </>
+          )}
+        </NavLink>
+      ))}
+    </nav>
+  )
+}
+
+function items(bar: HTMLElement): HTMLElement[] {
+  return Array.from(bar.querySelectorAll<HTMLElement>(`.${styles.item}`))
+}
+
+// NavLink's aria-current is the one record of which item is active.
+function activeItem(bar: HTMLElement): HTMLElement | null {
+  return bar.querySelector<HTMLElement>(`.${styles.item}[aria-current="page"]`)
+}
+
+// Where the pill and items are on screen right now, as offsets within the
+// bar. Bounding boxes include a running slide: the pill's box is its animated
+// left and width, and an item's box is its current layout plus whatever FLIP
+// translation remains, which applies to the layout it had when last placed.
+function onScreen(bar: HTMLElement, pill: HTMLElement, before: Geometry) {
+  const origin = bar.getBoundingClientRect().left + bar.clientLeft
+  const pillBox = pill.getBoundingClientRect()
+  return {
+    pill: { left: pillBox.left - origin, width: pillBox.width },
+    itemLefts: items(bar).map(
+      (item, i) => before.itemLefts[i]! + item.getBoundingClientRect().left - origin - item.offsetLeft,
+    ),
+  }
+}
+
+// Puts the pill on the active item (hidden when no item is active) and
+// returns the resulting geometry.
+function place(bar: HTMLElement, pill: HTMLElement, active: HTMLElement | null): Geometry {
+  pill.hidden = !active
+  pill.style.left = `${active?.offsetLeft ?? 0}px`
+  pill.style.width = `${active?.offsetWidth ?? 0}px`
+  return { active, itemLefts: items(bar).map((item) => item.offsetLeft) }
+}

web/src/shell/Rail.module.css

@@ -0,0 +1,51 @@
+.rail {
+  width: 96px;
+  padding: 24px 0;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 18px;
+  background: var(--color-surface);
+}
+
+.mark {
+  width: 48px;
+  height: 48px;
+  margin-bottom: 12px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  background: var(--color-accent);
+  color: var(--on-accent);
+  font-family: var(--font-heading);
+  font-size: 22px;
+}
+
+.item {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 5px;
+  min-width: 56px;
+  min-height: 44px;
+  color: var(--color-neutral-700);
+  font-size: 11px;
+  font-weight: 700;
+  text-decoration: none;
+}
+
+.pill {
+  width: 56px;
+  height: 36px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--radius-pill);
+}
+
+.active {
+  background: var(--color-accent);
+  color: var(--on-accent);
+}

web/src/shell/Rail.tsx

@@ -0,0 +1,27 @@
+import { NavLink } from 'react-router'
+import { Icon } from '../ui/Icon.tsx'
+import { navItems } from './navItems.ts'
+import styles from './Rail.module.css'
+
+// Tablet nav: a narrow icon rail with the "M" mark on top.
+export function Rail() {
+  return (
+    <nav aria-label="Primary" className={styles.rail}>
+      <div className={styles.mark} aria-hidden="true">
+        M
+      </div>
+      {navItems.map((item) => (
+        <NavLink key={item.to} to={item.to} end={item.end} className={styles.item}>
+          {({ isActive }) => (
+            <>
+              <span className={isActive ? `${styles.pill} ${styles.active}` : styles.pill}>
+                <Icon icon={item.icon} size="nav" />
+              </span>
+              {item.label}
+            </>
+          )}
+        </NavLink>
+      ))}
+    </nav>
+  )
+}

web/src/shell/Sidebar.module.css

@@ -0,0 +1,78 @@
+.sidebar {
+  width: 208px;
+  padding: 28px 16px;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  background: var(--color-surface);
+}
+
+.wordmark {
+  margin: 0;
+  padding: 0 12px 22px;
+  font-family: var(--font-heading);
+  font-size: 28px;
+  font-weight: 400;
+  color: var(--color-accent);
+}
+
+.nav {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.item {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  min-height: 44px;
+  padding: 12px 16px;
+  box-sizing: border-box;
+  border-radius: var(--radius-pill);
+  color: var(--color-neutral-800);
+  font-size: 15px;
+  font-weight: 700;
+  text-decoration: none;
+}
+
+.active {
+  background: var(--color-accent);
+  color: var(--on-accent);
+}
+
+.household {
+  margin-top: auto;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 12px;
+  border-radius: 22px;
+  background: var(--color-bg);
+}
+
+.avatar {
+  width: 36px;
+  height: 36px;
+  flex: none;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  background: var(--color-accent-2-300);
+  color: var(--color-accent-2-900);
+  font-family: var(--font-heading);
+  font-size: 15px;
+}
+
+.householdText {
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  font-size: 13px;
+  line-height: 1.3;
+}
+
+.householdNote {
+  color: var(--color-neutral-700);
+}

web/src/shell/Sidebar.tsx

@@ -0,0 +1,36 @@
+import { NavLink } from 'react-router'
+import { Icon } from '../ui/Icon.tsx'
+import { navItems } from './navItems.ts'
+import styles from './Sidebar.module.css'
+
+// Desktop nav: the MealQuest wordmark, labelled pill rows and the shared
+// household card at the foot.
+export function Sidebar() {
+  return (
+    <aside className={styles.sidebar}>
+      <p className={styles.wordmark}>MealQuest</p>
+      <nav aria-label="Primary" className={styles.nav}>
+        {navItems.map((item) => (
+          <NavLink
+            key={item.to}
+            to={item.to}
+            end={item.end}
+            className={({ isActive }) => (isActive ? `${styles.item} ${styles.active}` : styles.item)}
+          >
+            <Icon icon={item.icon} size="nav" />
+            {item.label}
+          </NavLink>
+        ))}
+      </nav>
+      <div className={styles.household}>
+        <span className={styles.avatar} aria-hidden="true">
+          K
+        </span>
+        <p className={styles.householdText}>
+          <strong>Our kitchen</strong>
+          <span className={styles.householdNote}>Shared household</span>
+        </p>
+      </div>
+    </aside>
+  )
+}

web/src/shell/navItems.ts

@@ -0,0 +1,20 @@
+import type { LucideIcon } from 'lucide-react'
+import { Calendar, Compass, House, SlidersHorizontal, Zap } from 'lucide-react'
+
+export type NavItem = {
+  to: string
+  label: string
+  icon: LucideIcon
+  // Match the path exactly; otherwise nested paths (/plan/shopping,
+  // /settings/ai) also mark the item current.
+  end: boolean
+}
+
+// The primary nav, in the same order in every layout.
+export const navItems: readonly NavItem[] = [
+  { to: '/', label: 'Home', icon: House, end: true },
+  { to: '/plan', label: 'Plan', icon: Calendar, end: false },
+  { to: '/discover', label: 'Discover', icon: Compass, end: false },
+  { to: '/quick', label: 'Quick', icon: Zap, end: false },
+  { to: '/settings', label: 'Settings', icon: SlidersHorizontal, end: false },
+]

web/src/shell/useBreakpoint.ts

@@ -0,0 +1,31 @@
+import { useCallback, useState, useSyncExternalStore } from 'react'
+
+export type Breakpoint = 'mobile' | 'tablet' | 'desktop'
+
+// The handoff's three layouts: mobile < 768 px, tablet 768–1199 px,
+// desktop ≥ 1200 px.
+export const TABLET_QUERY = '(min-width: 768px)'
+export const DESKTOP_QUERY = '(min-width: 1200px)'
+
+// The layout the current viewport calls for, updated as the viewport crosses
+// a breakpoint.
+export function useBreakpoint(): Breakpoint {
+  const [lists] = useState(() => ({
+    tablet: window.matchMedia(TABLET_QUERY),
+    desktop: window.matchMedia(DESKTOP_QUERY),
+  }))
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      lists.tablet.addEventListener('change', onChange)
+      lists.desktop.addEventListener('change', onChange)
+      return () => {
+        lists.tablet.removeEventListener('change', onChange)
+        lists.desktop.removeEventListener('change', onChange)
+      }
+    },
+    [lists],
+  )
+  return useSyncExternalStore(subscribe, () =>
+    lists.desktop.matches ? 'desktop' : lists.tablet.matches ? 'tablet' : 'mobile',
+  )
+}

web/src/styles/base.css

@@ -0,0 +1,12 @@
+/* App-wide base styles. Values come only from tokens.css. */
+body {
+  margin: 0;
+  background: var(--color-bg);
+  color: var(--color-text);
+  font-family: var(--font-body);
+}
+
+:focus-visible {
+  outline: 2px solid var(--color-accent);
+  outline-offset: 2px;
+}

web/src/styles/tokens.css

@@ -0,0 +1,116 @@
+/* MealQuest design tokens — final palette "B4: Grape + teal blue on off-white".
+   Built on the Organic design system (styles.css in this bundle); these values OVERRIDE its defaults. */
+/* Fonts are self-hosted from web/src/assets/fonts (OFL; licence texts alongside)
+   in place of the handoff's Google Fonts @import, so the app never calls Google.
+   Bagel Fat One: Google Fonts latin and latin-ext woff2 subsets.
+   Figtree: upstream static woff2 (github.com/erikdkennedy/figtree). */
+@font-face {
+  font-family: "Bagel Fat One";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url("../assets/fonts/BagelFatOne-LatinExt.woff2") format("woff2");
+  unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
+}
+@font-face {
+  font-family: "Bagel Fat One";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url("../assets/fonts/BagelFatOne-Latin.woff2") format("woff2");
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+@font-face {
+  font-family: "Figtree";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url("../assets/fonts/Figtree-Regular.woff2") format("woff2");
+}
+@font-face {
+  font-family: "Figtree";
+  font-style: normal;
+  font-weight: 600;
+  font-display: swap;
+  src: url("../assets/fonts/Figtree-SemiBold.woff2") format("woff2");
+}
+@font-face {
+  font-family: "Figtree";
+  font-style: normal;
+  font-weight: 700;
+  font-display: swap;
+  src: url("../assets/fonts/Figtree-Bold.woff2") format("woff2");
+}
+
+:root {
+  /* Ground + ink */
+  --color-bg: #f9f6f1;          /* oklch(0.975 0.008 85) — page / phone background */
+  --color-surface: #eee9de;     /* oklch(0.935 0.016 85) — cards, rows, inputs */
+  --color-text: #201e1d;
+  --color-divider: color-mix(in srgb, #201e1d 16%, transparent);
+  --on-accent: #f9f6f1;         /* text/icons on --color-accent fills (never dark text on grape) */
+
+  /* Primary accent — Grape (hue 300) */
+  --color-accent: #5a358c;      /* oklch(0.42 0.14 300) */
+  --color-accent-100: #f8f1ff;
+  --color-accent-200: #eedfff;
+  --color-accent-300: #dac3ff;
+  --color-accent-400: #c1a1f9;
+  --color-accent-500: #a47ee1;
+  --color-accent-600: #865fc0;
+  --color-accent-700: #68449b;  /* accent-colored small text on light grounds */
+  --color-accent-800: #4a2d73;
+  --color-accent-900: #2d1a49;
+
+  /* Second accent — Teal blue (hue 215) */
+  --color-accent-2: #29889c;    /* oklch(0.58 0.09 215) */
+  --color-accent-2-100: #e0fbff;
+  --color-accent-2-200: #bbf3ff;
+  --color-accent-2-300: #88e0f6;
+  --color-accent-2-400: #3fc7e4;
+  --color-accent-2-500: #00a9ca;
+  --color-accent-2-600: #008aaa; /* toggles ON, "Try it" button, + buttons */
+  --color-accent-2-700: #006b88;
+  --color-accent-2-800: #004c63; /* teal text on teal-100/200 fills */
+  --color-accent-2-900: #002f3e;
+
+  /* Neutrals (unchanged from Organic) */
+  --color-neutral-100: #f9f4ed;
+  --color-neutral-200: #eee7db;
+  --color-neutral-300: #dcd3c4;
+  --color-neutral-400: #c0b6a5;
+  --color-neutral-500: #a19786;
+  --color-neutral-600: #82796a;
+  --color-neutral-700: #645c50;
+  --color-neutral-800: #474238;
+  --color-neutral-900: #2e2b25;
+
+  /* Type */
+  --font-heading: "Bagel Fat One", system-ui, sans-serif; /* weight 400 only */
+  --font-body: "Figtree", system-ui, sans-serif;          /* 400 / 600 / 700 */
+  --font-mono: ui-monospace, Menlo, monospace;
+
+  /* Radii */
+  --radius-sm: 8px;
+  --radius-md: 16px;
+  --radius-lg: 28px;
+  --radius-card: 32px;   /* mobile hero cards */
+  --radius-pill: 999px;  /* buttons, inputs, tags, nav */
+
+  /* Spacing (Organic, density 1.1) */
+  --space-1: 4.4px; --space-2: 8.8px; --space-3: 13.2px; --space-4: 17.6px; --space-6: 26.4px; --space-8: 35.2px;
+
+  /* Elevation */
+  --shadow-sm: 0 1px 2px color-mix(in srgb, #2e2b25 14%, transparent);
+  --shadow-md: 0 3px 10px color-mix(in srgb, #2e2b25 16%, transparent);
+  --shadow-lg: 0 12px 32px color-mix(in srgb, #2e2b25 22%, transparent);
+
+  /* Motion */
+  --ease-spring: cubic-bezier(.34, 1.4, .64, 1);   /* nav pill, snap-back, bumps */
+  --ease-out-soft: cubic-bezier(.2, .8, .2, 1);    /* card promotion */
+  --ease-throw: cubic-bezier(.55, 0, .8, .4);      /* fly-off right */
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :root { --motion-scale: 0; }
+}

web/src/test/cssRules.ts

@@ -0,0 +1,75 @@
+// Reads the CSS Modules' rules straight from the stylesheets Vitest injects
+// (css: true). jsdom's getComputedStyle cannot answer two things these
+// primitives need checked: it resolves var() colours to transparent, and it
+// evaluates only "all" and "screen" media queries, so styles inside
+// @media (prefers-reduced-motion: reduce) never apply.
+
+function cssRules(): CSSRule[] {
+  return Array.from(document.styleSheets).flatMap((sheet) => Array.from(sheet.cssRules))
+}
+
+function collect(element: Element, rules: CSSRule[], style: CSSStyleDeclaration) {
+  for (const rule of rules) {
+    if (!(rule instanceof CSSStyleRule) || !element.matches(rule.selectorText)) continue
+    for (const property of Array.from(rule.style)) {
+      style.setProperty(property, rule.style.getPropertyValue(property))
+    }
+  }
+}
+
+// The declarations the stylesheets give the element, as written. Read the
+// shorthands the CSS uses (background, animation): jsdom does not expand
+// animation, nor any shorthand holding a var(). Later rules win; specificity
+// is not considered.
+export function declaredStyle(element: Element): CSSStyleDeclaration {
+  const style = document.createElement('div').style
+  collect(element, cssRules(), style)
+  return style
+}
+
+// Only the declarations @media (prefers-reduced-motion: reduce) gives the element.
+export function reducedMotionStyle(element: Element): CSSStyleDeclaration {
+  const style = document.createElement('div').style
+  for (const rule of cssRules()) {
+    if (rule instanceof CSSMediaRule && rule.conditionText.includes('prefers-reduced-motion: reduce')) {
+      collect(element, Array.from(rule.cssRules), style)
+    }
+  }
+  return style
+}
+
+// The @keyframes the element's animation runs. CSS Modules hash keyframe
+// names, so this follows the element's own animation-name.
+export function animationKeyframes(element: Element): CSSKeyframesRule {
+  const [name] = declaredStyle(element).animation.split(' ')
+  const keyframes = cssRules().find(
+    (rule): rule is CSSKeyframesRule => rule instanceof CSSKeyframesRule && rule.name === name,
+  )
+  if (!keyframes) throw new Error(`no @keyframes named ${JSON.stringify(name)}`)
+  return keyframes
+}
+
+function px(value: string, what: string): number {
+  if (value === '') return 0
+  const match = /^(\d+(?:\.\d+)?)px$/.exec(value)
+  if (!match) throw new Error(`${what} ${JSON.stringify(value)} is not a px length`)
+  return Number(match[1])
+}
+
+// The border-box size the element's declared rules give it on one axis:
+// width or height, plus padding and border unless box-sizing is border-box.
+// jsdom does no layout (getBoundingClientRect is all zeros), so this is the
+// way to catch padding that would push a fixed box past its specified size.
+export function outerSize(element: Element, axis: 'width' | 'height'): number {
+  const style = declaredStyle(element)
+  const size = px(style.getPropertyValue(axis), axis)
+  if (style.boxSizing === 'border-box') return size
+  const sides = axis === 'width' ? ['left', 'right'] : ['top', 'bottom']
+  return sides.reduce(
+    (total, side) =>
+      total +
+      px(style.getPropertyValue(`padding-${side}`), `padding-${side}`) +
+      px(style.getPropertyValue(`border-${side}-width`), `border-${side}-width`),
+    size,
+  )
+}

web/src/test/fetchStub.ts

@@ -0,0 +1,49 @@
+import { vi, type Mock } from 'vitest'
+import type { ApiLocation, Me } from '../api/index.ts'
+
+export const ME: Me = {
+  name: 'Sam',
+  email: 'sam@example.com',
+  household: { label: 'Our kitchen' },
+  csrfToken: 'token-1',
+}
+
+export function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } })
+}
+
+export function errorResponse(status: number, code: string, retryable = false): Response {
+  return jsonResponse(status, { error: { code, message: `${code} message`, retryable } })
+}
+
+// stubFetch replaces the global fetch with a mock answered from responses in
+// order; a request beyond them fails the test. Undo with vi.unstubAllGlobals.
+export function stubFetch(...responses: Response[]): Mock<typeof fetch> {
+  const fetchMock = vi.fn<typeof fetch>()
+  for (const response of responses) fetchMock.mockResolvedValueOnce(response)
+  fetchMock.mockImplementation((input, init) => {
+    throw new Error(`unexpected fetch: ${init?.method ?? 'GET'} ${String(input)}`)
+  })
+  vi.stubGlobal('fetch', fetchMock)
+  return fetchMock
+}
+
+// request returns the method, path and headers of the fetch mock's nth call.
+export function request(fetchMock: Mock<typeof fetch>, n: number) {
+  const call = fetchMock.mock.calls[n]
+  if (call === undefined) throw new Error(`fetch was called ${fetchMock.mock.calls.length} times, not ${n + 1}`)
+  const [input, init] = call
+  return {
+    path: String(input),
+    method: init?.method,
+    credentials: init?.credentials,
+    headers: new Headers(init?.headers),
+    body: init?.body,
+  }
+}
+
+// fakeLocation stands in for window.location on https://mealquest.test,
+// recording navigations.
+export function fakeLocation(pathname = '/', search = ''): ApiLocation & { assign: Mock<(url: string | URL) => void> } {
+  return { origin: 'https://mealquest.test', pathname, search, assign: vi.fn<(url: string | URL) => void>() }
+}

web/src/test/hitArea.ts

@@ -0,0 +1,26 @@
+import { expect } from 'vitest'
+
+// Minimum tap target from the handoff's accessibility rules.
+export const MIN_HIT_AREA = 44
+
+function px(value: string): number {
+  return value.endsWith('px') ? Number.parseFloat(value) : 0
+}
+
+// The tap target an element's stylesheet guarantees: the larger of its
+// declared size and declared minimum size, per axis. jsdom does no layout, so
+// this reads the CSS Modules' computed values (Vitest runs with css: true).
+// A dimension the CSS leaves unsized counts as 0 and fails the check.
+export function hitArea(element: Element): { width: number; height: number } {
+  const style = getComputedStyle(element)
+  return {
+    width: Math.max(px(style.width), px(style.minWidth)),
+    height: Math.max(px(style.height), px(style.minHeight)),
+  }
+}
+
+export function expectMinHitArea(element: Element) {
+  const { width, height } = hitArea(element)
+  expect(width, 'hit area width').toBeGreaterThanOrEqual(MIN_HIT_AREA)
+  expect(height, 'hit area height').toBeGreaterThanOrEqual(MIN_HIT_AREA)
+}

web/src/test/matchMedia.ts

@@ -0,0 +1,51 @@
+import { act } from '@testing-library/react'
+
+type Listener = (event: MediaQueryListEvent) => void
+
+// Replaces window.matchMedia with one that answers min-width / max-width
+// queries for a pretend viewport width, and prefers-reduced-motion: reduce
+// with reducedMotion (jsdom has no matchMedia and no layout). Returns a
+// function that resizes the pretend viewport and notifies every query whose
+// answer changed.
+export function mockViewport(initialWidth: number, { reducedMotion = false } = {}): (width: number) => void {
+  let width = initialWidth
+  const lists: { list: MediaQueryList; listeners: Set<Listener> }[] = []
+
+  function evaluate(query: string): boolean {
+    if (query === '(prefers-reduced-motion: reduce)') return reducedMotion
+    const min = /\(min-width:\s*(\d+)px\)/.exec(query)
+    const max = /\(max-width:\s*(\d+)px\)/.exec(query)
+    if (!min && !max) throw new Error(`mockViewport cannot evaluate ${JSON.stringify(query)}`)
+    return (!min || width >= Number(min[1])) && (!max || width <= Number(max[1]))
+  }
+
+  window.matchMedia = (query: string) => {
+    const listeners = new Set<Listener>()
+    const list = {
+      media: query,
+      get matches() {
+        return evaluate(query)
+      },
+      onchange: null,
+      addEventListener: (_type: string, listener: Listener) => listeners.add(listener),
+      removeEventListener: (_type: string, listener: Listener) => listeners.delete(listener),
+      addListener: (listener: Listener) => listeners.add(listener),
+      removeListener: (listener: Listener) => listeners.delete(listener),
+      dispatchEvent: () => true,
+    } as unknown as MediaQueryList
+    lists.push({ list, listeners })
+    return list
+  }
+
+  return (next: number) => {
+    const before = lists.map(({ list }) => list.matches)
+    width = next
+    act(() => {
+      lists.forEach(({ list, listeners }, i) => {
+        if (list.matches === before[i]) return
+        const event = { matches: list.matches, media: list.media } as MediaQueryListEvent
+        listeners.forEach((listener) => listener(event))
+      })
+    })
+  }
+}

web/src/ui/Button.module.css

@@ -0,0 +1,63 @@
+.button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-2);
+  min-width: 44px;
+  min-height: 48px;
+  padding: 0 22px;
+  border: 1.5px solid transparent;
+  border-radius: var(--radius-pill);
+  font-family: var(--font-heading);
+  font-size: 15px;
+  font-weight: 400;
+  line-height: 1;
+  cursor: pointer;
+  transition: transform 100ms var(--ease-out-soft), background-color 100ms var(--ease-out-soft);
+}
+
+.button:active:not(:disabled) {
+  transform: scale(0.97);
+}
+
+.button:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.primary {
+  background: var(--color-accent);
+  color: var(--on-accent);
+}
+
+.primary:hover:not(:disabled),
+.primary:active:not(:disabled) {
+  background: var(--color-accent-800);
+}
+
+.outline {
+  background: transparent;
+  border-color: var(--color-neutral-300);
+  color: var(--color-text);
+}
+
+.outline:hover:not(:disabled),
+.outline:active:not(:disabled) {
+  background: var(--color-neutral-200);
+}
+
+.dark {
+  background: var(--color-text);
+  color: var(--color-bg);
+}
+
+.dark:hover:not(:disabled),
+.dark:active:not(:disabled) {
+  background: var(--color-neutral-800);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .button {
+    transition: none;
+  }
+}

web/src/ui/Button.test.tsx

@@ -0,0 +1,53 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { createRef } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+import { expectMinHitArea } from '../test/hitArea.ts'
+import { Button } from './Button.tsx'
+import styles from './Button.module.css'
+
+describe('Button', () => {
+  it('is a button that defaults to type="button" and the primary variant', () => {
+    render(<Button>Save changes</Button>)
+    const button = screen.getByRole('button', { name: 'Save changes' })
+    expect(button).toHaveAttribute('type', 'button')
+    expect(button).toHaveClass(styles.button!, styles.primary!)
+  })
+
+  it.each(['primary', 'outline', 'dark'] as const)('renders the %s variant with a ≥ 44 px hit area', (variant) => {
+    render(<Button variant={variant}>Go</Button>)
+    const button = screen.getByRole('button', { name: 'Go' })
+    expect(button).toHaveClass(styles[variant]!)
+    expectMinHitArea(button)
+  })
+
+  it('declares the 100 ms pressed scale transition', () => {
+    render(<Button>Go</Button>)
+    expect(getComputedStyle(screen.getByRole('button')).transition).toContain('transform 100ms')
+  })
+
+  it('does not fire onClick when disabled', () => {
+    const onClick = vi.fn()
+    render(
+      <Button disabled onClick={onClick}>
+        Go
+      </Button>,
+    )
+    const button = screen.getByRole('button', { name: 'Go' })
+    expect(button).toBeDisabled()
+    fireEvent.click(button)
+    expect(onClick).not.toHaveBeenCalled()
+  })
+
+  it('forwards the ref, rest props and an explicit type', () => {
+    const ref = createRef<HTMLButtonElement>()
+    render(
+      <Button ref={ref} type="submit" aria-describedby="hint">
+        Send
+      </Button>,
+    )
+    const button = screen.getByRole('button', { name: 'Send' })
+    expect(ref.current).toBe(button)
+    expect(button).toHaveAttribute('type', 'submit')
+    expect(button).toHaveAttribute('aria-describedby', 'hint')
+  })
+})

web/src/ui/Button.tsx

@@ -0,0 +1,16 @@
+import type { ComponentPropsWithRef } from 'react'
+import styles from './Button.module.css'
+
+export type ButtonVariant = 'primary' | 'outline' | 'dark'
+
+export type ButtonProps = ComponentPropsWithRef<'button'> & {
+  variant?: ButtonVariant
+}
+
+// Pill button. Primary is grape with --on-accent text; outline and dark are the
+// secondary treatments from the handoff. `type` defaults to "button" so a
+// Button inside a form never submits by accident.
+export function Button({ variant = 'primary', type = 'button', className, ...rest }: ButtonProps) {
+  const classes = [styles.button, styles[variant], className].filter(Boolean).join(' ')
+  return <button type={type} className={classes} {...rest} />
+}

web/src/ui/Card.module.css

@@ -0,0 +1,13 @@
+.card {
+  padding: var(--space-4);
+  border-radius: var(--radius-lg);
+  color: var(--color-text);
+}
+
+.surface {
+  background: var(--color-surface);
+}
+
+.muted {
+  background: var(--color-neutral-100);
+}

web/src/ui/Card.test.tsx

@@ -0,0 +1,18 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { Card } from './Card.tsx'
+import styles from './Card.module.css'
+
+describe('Card', () => {
+  it('renders its children on the surface fill by default', () => {
+    render(<Card aria-label="Tonight">Tacos</Card>)
+    const card = screen.getByLabelText('Tonight')
+    expect(card).toHaveTextContent('Tacos')
+    expect(card).toHaveClass(styles.card!, styles.surface!)
+  })
+
+  it('supports the muted tone', () => {
+    render(<Card data-testid="card" tone="muted" />)
+    expect(screen.getByTestId('card')).toHaveClass(styles.muted!)
+  })
+})

web/src/ui/Card.tsx

@@ -0,0 +1,14 @@
+import type { ComponentPropsWithRef } from 'react'
+import styles from './Card.module.css'
+
+export type CardTone = 'surface' | 'muted'
+
+export type CardProps = ComponentPropsWithRef<'div'> & {
+  // surface = --color-surface; muted = the secondary neutral-100 fill.
+  tone?: CardTone
+}
+
+export function Card({ tone = 'surface', className, ...rest }: CardProps) {
+  const classes = [styles.card, styles[tone], className].filter(Boolean).join(' ')
+  return <div className={classes} {...rest} />
+}

web/src/ui/Checkbox.module.css

@@ -0,0 +1,63 @@
+.root {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-3);
+  min-width: 44px;
+  min-height: 44px;
+  cursor: pointer;
+}
+
+.input {
+  appearance: none;
+  display: grid;
+  place-content: center;
+  flex: none;
+  width: 22px;
+  height: 22px;
+  margin: 0;
+  border: 2px solid var(--color-neutral-400);
+  border-radius: var(--radius-sm);
+  background: transparent;
+  cursor: pointer;
+}
+
+/* The check mark. */
+.input::before {
+  content: "";
+  width: 12px;
+  height: 12px;
+  background: var(--on-accent);
+  clip-path: polygon(14% 44%, 0 59%, 40% 100%, 100% 21%, 85% 7%, 39% 69%);
+  opacity: 0;
+  transform: scale(0.8);
+  transition: transform 160ms var(--ease-spring), opacity 160ms var(--ease-out-soft);
+}
+
+.input:checked {
+  border-color: var(--color-accent);
+  background: var(--color-accent);
+}
+
+.input:checked::before {
+  opacity: 1;
+  transform: scale(1);
+}
+
+.input:disabled,
+.input:disabled + .label {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.label {
+  font-family: var(--font-body);
+  font-size: 15px;
+  font-weight: 600;
+  color: var(--color-text);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .input::before {
+    transition: none;
+  }
+}

web/src/ui/Checkbox.test.tsx

@@ -0,0 +1,36 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { expectMinHitArea } from '../test/hitArea.ts'
+import { Checkbox } from './Checkbox.tsx'
+
+describe('Checkbox', () => {
+  it('is a native checkbox named by its label', () => {
+    render(<Checkbox label="Chicken thighs" />)
+    const box = screen.getByRole('checkbox', { name: 'Chicken thighs' })
+    expect(box.tagName).toBe('INPUT')
+    expect(box).toHaveAttribute('type', 'checkbox')
+    expect(box).not.toBeChecked()
+  })
+
+  it('toggles when the input or its label text is clicked', () => {
+    render(<Checkbox label="Limes" />)
+    const box = screen.getByRole('checkbox', { name: 'Limes' })
+    fireEvent.click(box)
+    expect(box).toBeChecked()
+    fireEvent.click(screen.getByText('Limes'))
+    expect(box).not.toBeChecked()
+  })
+
+  it('reflects a controlled checked state and disabled', () => {
+    render(<Checkbox label="Rice" checked disabled readOnly />)
+    const box = screen.getByRole('checkbox', { name: 'Rice' })
+    expect(box).toBeChecked()
+    expect(box).toBeDisabled()
+  })
+
+  it('has a ≥ 44 px hit area (the wrapping label)', () => {
+    render(<Checkbox label="Rice" />)
+    const hit = screen.getByRole('checkbox', { name: 'Rice' }).closest('label')!
+    expectMinHitArea(hit)
+  })
+})

web/src/ui/Checkbox.tsx

@@ -0,0 +1,17 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react'
+import styles from './Checkbox.module.css'
+
+export type CheckboxProps = Omit<ComponentPropsWithRef<'input'>, 'type'> & {
+  label: ReactNode
+}
+
+// Native checkbox, styled. The wrapping label is the hit area (at least
+// 44×44), so tapping the text toggles it too.
+export function Checkbox({ label, className, ...rest }: CheckboxProps) {
+  return (
+    <label className={[styles.root, className].filter(Boolean).join(' ')}>
+      <input type="checkbox" className={styles.input} {...rest} />
+      <span className={styles.label}>{label}</span>
+    </label>
+  )
+}

web/src/ui/Chip.module.css

@@ -0,0 +1,35 @@
+.chip {
+  display: inline-flex;
+  align-items: center;
+  min-height: 36px;
+  padding: 0 14px;
+  border-radius: var(--radius-pill);
+  background: var(--color-accent-2-200);
+  color: var(--color-accent-2-900);
+  font-family: var(--font-body);
+  font-size: 14px;
+  font-weight: 700;
+  white-space: nowrap;
+}
+
+.removable {
+  padding-right: 0;
+}
+
+/* 44 px hit box around a small cross; negative margins keep the chip 36 px
+   tall and the cross close to the label. */
+.remove {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: 44px;
+  height: 44px;
+  margin: -4px 0 -4px -14px;
+  padding: 0;
+  border: 0;
+  border-radius: var(--radius-pill);
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+}

web/src/ui/Chip.test.tsx

@@ -0,0 +1,26 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import { expectMinHitArea } from '../test/hitArea.ts'
+import { Chip } from './Chip.tsx'
+
+describe('Chip', () => {
+  it('has no remove button unless onRemove is given', () => {
+    render(<Chip label="Beef tacos" />)
+    expect(screen.getByText('Beef tacos')).toBeInTheDocument()
+    expect(screen.queryByRole('button')).not.toBeInTheDocument()
+  })
+
+  it('exposes an accessible "Remove {label}" button that calls onRemove', () => {
+    const onRemove = vi.fn()
+    render(<Chip label="Beef tacos" onRemove={onRemove} />)
+    const remove = screen.getByRole('button', { name: 'Remove Beef tacos' })
+    expect(remove).toHaveAttribute('type', 'button')
+    fireEvent.click(remove)
+    expect(onRemove).toHaveBeenCalledOnce()
+  })
+
+  it('gives the remove button a ≥ 44 px hit area', () => {
+    render(<Chip label="Pizza night" onRemove={() => {}} />)
+    expectMinHitArea(screen.getByRole('button', { name: 'Remove Pizza night' }))
+  })
+})

web/src/ui/Chip.tsx

@@ -0,0 +1,24 @@
+import type { ComponentPropsWithRef } from 'react'
+import styles from './Chip.module.css'
+
+export type ChipProps = Omit<ComponentPropsWithRef<'span'>, 'children'> & {
+  label: string
+  // When set, the chip shows a "Remove {label}" button that calls it.
+  onRemove?: () => void
+}
+
+export function Chip({ label, onRemove, className, ...rest }: ChipProps) {
+  const classes = [styles.chip, onRemove && styles.removable, className].filter(Boolean).join(' ')
+  return (
+    <span className={classes} {...rest}>
+      {label}
+      {onRemove && (
+        <button type="button" className={styles.remove} aria-label={`Remove ${label}`} onClick={onRemove}>
+          <svg viewBox="0 0 12 12" width="10" height="10" aria-hidden="true">
+            <path d="M2 2l8 8M10 2l-8 8" stroke="currentColor" strokeWidth="2.75" strokeLinecap="round" />
+          </svg>
+        </button>
+      )}
+    </span>
+  )
+}

web/src/ui/EmptyState.module.css

@@ -0,0 +1,30 @@
+.empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--space-3);
+  padding: var(--space-8) var(--space-4);
+  color: var(--color-text);
+  text-align: center;
+}
+
+.title {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 24px;
+  font-weight: 400;
+  line-height: 1.15;
+}
+
+.body {
+  margin: 0;
+  max-width: 32ch;
+  font-family: var(--font-body);
+  font-size: 15px;
+  line-height: 1.45;
+  color: var(--color-neutral-700);
+}
+
+.action {
+  margin-top: var(--space-2);
+}

web/src/ui/EmptyState.test.tsx

@@ -0,0 +1,27 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import { expectMinHitArea } from '../test/hitArea.ts'
+import { EmptyState } from './EmptyState.tsx'
+
+describe('EmptyState', () => {
+  it('shows a Bagel title and body without an action by default', () => {
+    render(<EmptyState title="Quest log is empty">Swipe Try it on a Side quest to save it here.</EmptyState>)
+    const title = screen.getByRole('heading', { name: 'Quest log is empty' })
+    expect(getComputedStyle(title).fontFamily).toBe('var(--font-heading)')
+    expect(screen.getByText('Swipe Try it on a Side quest to save it here.')).toBeInTheDocument()
+    expect(screen.queryByRole('button')).not.toBeInTheDocument()
+  })
+
+  it('renders the optional primary action and calls its handler', () => {
+    const onClick = vi.fn()
+    render(
+      <EmptyState title="No Regulars yet" action={{ label: 'Add a dinner', onClick }}>
+        Add the dinners you make most.
+      </EmptyState>,
+    )
+    const action = screen.getByRole('button', { name: 'Add a dinner' })
+    expectMinHitArea(action)
+    fireEvent.click(action)
+    expect(onClick).toHaveBeenCalledTimes(1)
+  })
+})

web/src/ui/EmptyState.tsx

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react'
+import { Button } from './Button.tsx'
+import styles from './EmptyState.module.css'
+
+export type EmptyStateAction = {
+  label: string
+  onClick: () => void
+}
+
+export type EmptyStateProps = {
+  title: string
+  children: ReactNode
+  // Optional primary action, rendered as a primary Button.
+  action?: EmptyStateAction
+}
+
+// Bagel title, body text and an optional primary action.
+export function EmptyState({ title, children, action }: EmptyStateProps) {
+  return (
+    <section className={styles.empty}>
+      <h2 className={styles.title}>{title}</h2>
+      <p className={styles.body}>{children}</p>
+      {action && (
+        <Button className={styles.action} onClick={action.onClick}>
+          {action.label}
+        </Button>
+      )}
+    </section>
+  )
+}

web/src/ui/ErrorBanner.module.css

@@ -0,0 +1,16 @@
+.banner {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  background: var(--color-neutral-100);
+}
+
+.message {
+  flex: 1;
+  margin: 0;
+  color: var(--color-accent-700);
+  font-family: var(--font-body);
+  font-size: 15px;
+  font-weight: 600;
+  line-height: 1.35;
+}

web/src/ui/ErrorBanner.test.tsx

@@ -0,0 +1,32 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import { declaredStyle } from '../test/cssRules.ts'
+import { expectMinHitArea } from '../test/hitArea.ts'
+import { ErrorBanner } from './ErrorBanner.tsx'
+
+describe('ErrorBanner', () => {
+  it('announces the message and calls onRetry from the Retry button', () => {
+    const onRetry = vi.fn()
+    render(<ErrorBanner onRetry={onRetry}>Couldn't load the Supply run.</ErrorBanner>)
+    expect(screen.getByRole('alert')).toHaveTextContent("Couldn't load the Supply run.")
+    const retry = screen.getByRole('button', { name: 'Retry' })
+    expectMinHitArea(retry)
+    fireEvent.click(retry)
+    expect(onRetry).toHaveBeenCalledTimes(1)
+  })
+
+  it('uses a caller-supplied retry label', () => {
+    render(
+      <ErrorBanner onRetry={() => {}} retryLabel="Rebuild week">
+        The plan didn't save.
+      </ErrorBanner>,
+    )
+    expect(screen.getByRole('button', { name: 'Rebuild week' })).toBeInTheDocument()
+  })
+
+  it('is a neutral-100 card with grape-700 text', () => {
+    render(<ErrorBanner onRetry={() => {}}>Offline</ErrorBanner>)
+    expect(declaredStyle(screen.getByRole('alert')).background).toBe('var(--color-neutral-100)')
+    expect(declaredStyle(screen.getByText('Offline')).color).toBe('var(--color-accent-700)')
+  })
+})

web/src/ui/ErrorBanner.tsx

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react'
+import { Button } from './Button.tsx'
+import { Card } from './Card.tsx'
+import styles from './ErrorBanner.module.css'
+
+export type ErrorBannerProps = {
+  // What went wrong, in the caller's words.
+  children: ReactNode
+  onRetry: () => void
+  retryLabel?: string
+}
+
+// Muted neutral-100 card with grape-700 text and a Retry button.
+export function ErrorBanner({ children, onRetry, retryLabel = 'Retry' }: ErrorBannerProps) {
+  return (
+    <Card tone="muted" role="alert" className={styles.banner}>
+      <p className={styles.message}>{children}</p>
+      <Button onClick={onRetry}>{retryLabel}</Button>
+    </Card>
+  )
+}

web/src/ui/Icon.module.css

@@ -0,0 +1,15 @@
+.icon {
+  display: inline-block;
+  flex: none;
+  vertical-align: middle;
+}
+
+.nav {
+  width: 22px;
+  height: 22px;
+}
+
+.inline {
+  width: 16px;
+  height: 16px;
+}

web/src/ui/Icon.test.tsx

@@ -0,0 +1,45 @@
+import { render, screen } from '@testing-library/react'
+import { House } from 'lucide-react'
+import { describe, expect, it } from 'vitest'
+import { Icon } from './Icon.tsx'
+
+function svg(container: HTMLElement) {
+  return container.querySelector('svg')!
+}
+
+describe('Icon', () => {
+  it('is hidden and unnamed without a label', () => {
+    const { container } = render(<Icon icon={House} />)
+    expect(svg(container)).toHaveAttribute('aria-hidden', 'true')
+    expect(svg(container)).not.toHaveAttribute('aria-label')
+    expect(screen.queryByRole('img')).toBeNull()
+  })
+
+  it('is a named image when given a label', () => {
+    const { container } = render(<Icon icon={House} label="Home" />)
+    expect(svg(container)).not.toHaveAttribute('aria-hidden')
+    expect(screen.getByRole('img', { name: 'Home' })).toBe(svg(container))
+  })
+
+  it('draws at stroke width 2.75', () => {
+    const { container } = render(<Icon icon={House} />)
+    expect(svg(container)).toHaveAttribute('stroke-width', '2.75')
+  })
+
+  it('is 22 px at the nav size', () => {
+    const { container } = render(<Icon icon={House} size="nav" />)
+    const style = getComputedStyle(svg(container))
+    expect([style.width, style.height]).toEqual(['22px', '22px'])
+  })
+
+  it('is 16 px inline by default', () => {
+    const { container } = render(<Icon icon={House} />)
+    const style = getComputedStyle(svg(container))
+    expect([style.width, style.height]).toEqual(['16px', '16px'])
+  })
+
+  it('merges a caller className', () => {
+    const { container } = render(<Icon icon={House} className="extra" />)
+    expect(svg(container)).toHaveClass('extra')
+  })
+})

web/src/ui/Icon.tsx

@@ -0,0 +1,21 @@
+import type { LucideIcon } from 'lucide-react'
+import styles from './Icon.module.css'
+
+export type IconSize = 'nav' | 'inline'
+
+export type IconProps = {
+  // A lucide-react icon component, e.g. `import { House } from 'lucide-react'`.
+  icon: LucideIcon
+  // nav = 22 px (bottom bar, sidebar); inline = 16 px (beside text).
+  size?: IconSize
+  // Accessible name. Without one the icon is decorative and hidden.
+  label?: string
+  className?: string
+}
+
+// Lucide icon at the handoff's stroke width 2.75, sized by the stylesheet.
+export function Icon({ icon: LucideGlyph, size = 'inline', label, className }: IconProps) {
+  const classes = [styles.icon, styles[size], className].filter(Boolean).join(' ')
+  const a11y = label === undefined ? { 'aria-hidden': true } : { role: 'img', 'aria-label': label }
+  return <LucideGlyph strokeWidth={2.75} className={classes} {...a11y} />
+}

web/src/ui/IconButton.module.css

@@ -0,0 +1,74 @@
+/* The button is the hit box; .face is the visible circle. A 40 px face sits in
+   a 44 px hit box whose negative margin keeps the 40 px layout footprint. */
+.button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  padding: 0;
+  border: 0;
+  border-radius: var(--radius-pill);
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+}
+
+.button:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.size40 {
+  width: 44px;
+  height: 44px;
+  margin: -2px;
+}
+
+.size62 {
+  width: 62px;
+  height: 62px;
+}
+
+.face {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--radius-pill);
+  transition: transform 100ms var(--ease-out-soft);
+}
+
+.size40 .face {
+  width: 40px;
+  height: 40px;
+}
+
+.size62 .face {
+  width: 62px;
+  height: 62px;
+  box-shadow: var(--shadow-md);
+}
+
+.button:active:not(:disabled) .face {
+  transform: scale(0.97);
+}
+
+.surface {
+  background: var(--color-surface);
+  color: var(--color-text);
+}
+
+.accent {
+  background: var(--color-accent);
+  color: var(--on-accent);
+}
+
+.teal {
+  background: var(--color-accent-2-600);
+  color: var(--on-accent);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .face {
+    transition: none;
+  }
+}

web/src/ui/IconButton.test.tsx

@@ -0,0 +1,34 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import { hitArea, expectMinHitArea } from '../test/hitArea.ts'
+import { IconButton } from './IconButton.tsx'
+
+describe('IconButton', () => {
+  it('is named by its label, not its icon', () => {
+    const onClick = vi.fn()
+    render(
+      <IconButton label="Notifications" onClick={onClick}>
+        <svg />
+      </IconButton>,
+    )
+    const button = screen.getByRole('button', { name: 'Notifications' })
+    expect(button).toHaveAttribute('type', 'button')
+    fireEvent.click(button)
+    expect(onClick).toHaveBeenCalledOnce()
+  })
+
+  it('keeps a 44 px hit area around the 40 px circle', () => {
+    render(<IconButton label="Back" size={40} />)
+    const button = screen.getByRole('button', { name: 'Back' })
+    expectMinHitArea(button)
+    const face = button.firstElementChild!
+    expect(hitArea(face)).toEqual({ width: 40, height: 40 })
+  })
+
+  it('is 62 px at the large size', () => {
+    render(<IconButton label="Try it" size={62} tone="teal" />)
+    const button = screen.getByRole('button', { name: 'Try it' })
+    expectMinHitArea(button)
+    expect(hitArea(button)).toEqual({ width: 62, height: 62 })
+  })
+})

web/src/ui/IconButton.tsx

@@ -0,0 +1,33 @@
+import type { ComponentPropsWithRef } from 'react'
+import styles from './IconButton.module.css'
+
+export type IconButtonSize = 40 | 62
+export type IconButtonTone = 'surface' | 'accent' | 'teal'
+
+export type IconButtonProps = Omit<ComponentPropsWithRef<'button'>, 'aria-label'> & {
+  // Accessible name; an icon alone never names a button.
+  label: string
+  size?: IconButtonSize
+  tone?: IconButtonTone
+}
+
+// Round icon-only button. The 40 px size keeps a 44 px hit box (see the CSS);
+// the 62 px size is the round action button with --shadow-md.
+export function IconButton({
+  label,
+  size = 40,
+  tone = 'surface',
+  type = 'button',
+  className,
+  children,
+  ...rest
+}: IconButtonProps) {
+  const classes = [styles.button, styles[`size${size}`], className].filter(Boolean).join(' ')
+  return (
+    <button type={type} aria-label={label} className={classes} {...rest}>
+      <span className={[styles.face, styles[tone]].join(' ')} aria-hidden="true">
+        {children}
+      </span>
+    </button>
+  )
+}

web/src/ui/ListRow.module.css

@@ -0,0 +1,69 @@
+.row {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  width: 100%;
+  min-height: 44px;
+  padding: 14px 16px;
+  color: var(--color-text);
+  text-align: left;
+}
+
+.interactive {
+  padding: 0;
+  border-radius: var(--radius-md);
+}
+
+.interactive:hover {
+  background: var(--color-neutral-200);
+}
+
+.main {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  flex: 1 1 auto;
+  min-width: 44px;
+  min-height: 44px;
+  padding: 14px 16px;
+  border: 0;
+  border-radius: var(--radius-md);
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+
+.interactive > .trailing {
+  padding-right: 16px;
+}
+
+.leading,
+.trailing {
+  display: inline-flex;
+  align-items: center;
+  flex: none;
+}
+
+.body {
+  display: flex;
+  flex-direction: column;
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.title {
+  font-family: var(--font-body);
+  font-size: 15px;
+  font-weight: 700;
+}
+
+.meta {
+  font-family: var(--font-body);
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--color-neutral-700);
+}

web/src/ui/ListRow.test.tsx

@@ -0,0 +1,57 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import { expectMinHitArea } from '../test/hitArea.ts'
+import { ListRow } from './ListRow.tsx'
+import { Toggle } from './Toggle.tsx'
+
+describe('ListRow', () => {
+  it('renders leading, title, meta and trailing slots without being interactive', () => {
+    render(
+      <ListRow
+        leading={<span>icon</span>}
+        title="Notifications"
+        meta="Push and Google Chat"
+        trailing={<span>chevron</span>}
+      />,
+    )
+    for (const text of ['icon', 'Notifications', 'Push and Google Chat', 'chevron']) {
+      expect(screen.getByText(text)).toBeInTheDocument()
+    }
+    expect(screen.queryByRole('button')).not.toBeInTheDocument()
+  })
+
+  it('is a single button with a ≥ 44 px hit area when it has onClick', () => {
+    const onClick = vi.fn()
+    render(<ListRow title="10 new side quests to swipe" onClick={onClick} />)
+    const row = screen.getByRole('button', { name: '10 new side quests to swipe' })
+    expect(row).toHaveAttribute('type', 'button')
+    expectMinHitArea(row)
+    fireEvent.click(row)
+    expect(onClick).toHaveBeenCalledOnce()
+  })
+
+  it('keeps a trailing toggle outside the row button so each control fires only its own action', () => {
+    const onClick = vi.fn()
+    const onCheckedChange = vi.fn()
+    render(
+      <ListRow
+        title="Dinner reminders"
+        meta="Push at 4 pm"
+        trailing={<Toggle aria-label="Dinner reminders" checked={false} onCheckedChange={onCheckedChange} />}
+        onClick={onClick}
+      />,
+    )
+    const row = screen.getByRole('button', { name: /^Dinner reminders/ })
+    const toggle = screen.getByRole('switch', { name: 'Dinner reminders' })
+    expect(row).not.toContainElement(toggle)
+    expect(row.querySelector('button')).toBeNull()
+
+    fireEvent.click(toggle)
+    expect(onCheckedChange).toHaveBeenCalledExactlyOnceWith(true)
+    expect(onClick).not.toHaveBeenCalled()
+
+    fireEvent.click(row)
+    expect(onClick).toHaveBeenCalledOnce()
+    expect(onCheckedChange).toHaveBeenCalledOnce()
+  })
+})

web/src/ui/ListRow.tsx

@@ -0,0 +1,45 @@
+import type { ReactNode } from 'react'
+import styles from './ListRow.module.css'
+
+export type ListRowProps = {
+  title: ReactNode
+  meta?: ReactNode
+  // Leading slot: icon, photo or avatar.
+  leading?: ReactNode
+  // Trailing slot: chevron, toggle, count or action.
+  trailing?: ReactNode
+  // When set, the leading slot, title and meta form one button. The trailing
+  // slot stays a sibling outside it, so a trailing toggle or action is never
+  // nested in the row's button and never triggers the row's action.
+  onClick?: () => void
+  className?: string
+}
+
+export function ListRow({ title, meta, leading, trailing, onClick, className }: ListRowProps) {
+  const main = (
+    <>
+      {leading && <span className={styles.leading}>{leading}</span>}
+      <span className={styles.body}>
+        <span className={styles.title}>{title}</span>
+        {meta && <span className={styles.meta}>{meta}</span>}
+      </span>
+    </>
+  )
+  const trailingSlot = trailing && <span className={styles.trailing}>{trailing}</span>
+  if (onClick) {
+    return (
+      <div className={[styles.row, styles.interactive, className].filter(Boolean).join(' ')}>
+        <button type="button" className={styles.main} onClick={onClick}>
+          {main}
+        </button>
+        {trailingSlot}
+      </div>
+    )
+  }
+  return (
+    <div className={[styles.row, className].filter(Boolean).join(' ')}>
+      {main}
+      {trailingSlot}
+    </div>
+  )
+}

web/src/ui/Photo.module.css

@@ -0,0 +1,26 @@
+/* Radius and inset come from the --photo-radius and --photo-inset custom
+   properties the component sets from its props. Size it with className. */
+.frame {
+  display: block;
+  margin: var(--photo-inset);
+  border-radius: var(--photo-radius);
+  overflow: hidden;
+}
+
+.photo {
+  object-fit: cover;
+  filter: saturate(0.6) contrast(0.85) brightness(1.1) opacity(0.94);
+}
+
+.placeholder {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: repeating-linear-gradient(
+    135deg,
+    var(--color-neutral-300) 0 8px,
+    var(--color-neutral-200) 8px 16px
+  );
+  color: var(--color-neutral-700);
+  font: 11px var(--font-mono);
+}

web/src/ui/Photo.test.tsx

@@ -0,0 +1,66 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { declaredStyle } from '../test/cssRules.ts'
+import { Photo } from './Photo.tsx'
+
+const id = '01JABCDEFGHJKMNPQRSTVWXYZ0'
+
+describe('Photo', () => {
+  it('offers the 400 and 1200 renditions as a srcset', () => {
+    render(<Photo id={id} name="Korean beef bowls" />)
+    const img = screen.getByRole('img', { name: 'Korean beef bowls' })
+    expect(img).toHaveAttribute('src', `/media/photos/${id}-400.jpg`)
+    expect(img.getAttribute('srcset')!.split(', ')).toEqual([
+      `/media/photos/${id}-400.jpg 400w`,
+      `/media/photos/${id}-1200.jpg 1200w`,
+    ])
+  })
+
+  it('loads lazily with the dinner name as alt text', () => {
+    render(<Photo id={id} name="Pizza night" />)
+    const img = screen.getByRole('img')
+    expect(img).toHaveAttribute('loading', 'lazy')
+    expect(img).toHaveAttribute('alt', 'Pizza night')
+  })
+
+  it('applies the washed filter', () => {
+    render(<Photo id={id} name="Pizza night" />)
+    expect(declaredStyle(screen.getByRole('img')).filter).toBe(
+      'saturate(0.6) contrast(0.85) brightness(1.1) opacity(0.94)',
+    )
+  })
+
+  it('takes its radius and inset from props', () => {
+    render(<Photo id={id} name="Pizza night" radius="var(--radius-lg)" inset="10px" />)
+    const img = screen.getByRole('img')
+    const style = declaredStyle(img)
+    expect(style.borderRadius).toBe('var(--photo-radius)')
+    expect(style.margin).toBe('var(--photo-inset)')
+    expect(img.style.getPropertyValue('--photo-radius')).toBe('var(--radius-lg)')
+    expect(img.style.getPropertyValue('--photo-inset')).toBe('10px')
+  })
+
+  it('shows the striped placeholder when there is no photo', () => {
+    const { container } = render(<Photo name="Beef tacos" />)
+    expect(container.querySelector('img')).toBeNull()
+    const placeholder = screen.getByRole('img', { name: 'Beef tacos' })
+    expect(placeholder).toHaveTextContent('dish photo')
+    expect(declaredStyle(placeholder).background.replace(/\s+/g, ' ')).toBe(
+      'repeating-linear-gradient( 135deg, var(--color-neutral-300) 0 8px, var(--color-neutral-200) 8px 16px )',
+    )
+  })
+
+  it('falls back to the placeholder when the image fails to load', () => {
+    const { container } = render(<Photo id={id} name="Beef tacos" />)
+    fireEvent.error(container.querySelector('img')!)
+    expect(container.querySelector('img')).toBeNull()
+    expect(screen.getByRole('img', { name: 'Beef tacos' })).toHaveTextContent('dish photo')
+  })
+
+  it('tries again when given a new id after a failure', () => {
+    const { container, rerender } = render(<Photo id={id} name="Beef tacos" />)
+    fireEvent.error(container.querySelector('img')!)
+    rerender(<Photo id="01JZZZZZZZZZZZZZZZZZZZZZZZ" name="Beef tacos" />)
+    expect(container.querySelector('img')).toHaveAttribute('src', '/media/photos/01JZZZZZZZZZZZZZZZZZZZZZZZ-400.jpg')
+  })
+})

web/src/ui/Photo.tsx

@@ -0,0 +1,49 @@
+import { useState, type CSSProperties } from 'react'
+import styles from './Photo.module.css'
+
+export type PhotoProps = {
+  // Photo id; the server stores /media/photos/{id}-400.jpg and -1200.jpg.
+  // Without one the striped "dish photo" placeholder is shown.
+  id?: string
+  // The dinner name, used as the alt text.
+  name: string
+  // Corner radius and the margin from the containing card edge, as CSS lengths.
+  radius?: string
+  inset?: string
+  // The rendered width hint for srcset selection.
+  sizes?: string
+  className?: string
+  style?: CSSProperties
+}
+
+// Dinner photo through the Organic "washed" filter. Falls back to the
+// striped placeholder when there is no photo or it fails to load.
+export function Photo({ id, name, radius = '24px', inset = '0', sizes = '100vw', className, style }: PhotoProps) {
+  // The id whose image failed, so a new id gets a fresh attempt.
+  const [failedId, setFailedId] = useState<string>()
+  const frame = { '--photo-radius': radius, '--photo-inset': inset, ...style } as CSSProperties
+
+  if (id === undefined || failedId === id) {
+    const classes = [styles.frame, styles.placeholder, className].filter(Boolean).join(' ')
+    return (
+      <div role="img" aria-label={name} className={classes} style={frame}>
+        <span aria-hidden="true">dish photo</span>
+      </div>
+    )
+  }
+
+  const base = `/media/photos/${encodeURIComponent(id)}`
+  const classes = [styles.frame, styles.photo, className].filter(Boolean).join(' ')
+  return (
+    <img
+      src={`${base}-400.jpg`}
+      srcSet={`${base}-400.jpg 400w, ${base}-1200.jpg 1200w`}
+      sizes={sizes}
+      loading="lazy"
+      alt={name}
+      className={classes}
+      style={frame}
+      onError={() => setFailedId(id)}
+    />
+  )
+}

web/src/ui/Segmented.module.css

@@ -0,0 +1,35 @@
+.track {
+  display: flex;
+  gap: 4px;
+  padding: 4px;
+  border-radius: var(--radius-pill);
+  background: var(--color-surface);
+}
+
+.option {
+  flex: 1 1 0;
+  min-width: 44px;
+  min-height: 44px;
+  padding: 0 var(--space-4);
+  border: 0;
+  border-radius: var(--radius-pill);
+  background: transparent;
+  color: var(--color-neutral-700);
+  font-family: var(--font-body);
+  font-size: 14px;
+  font-weight: 700;
+  cursor: pointer;
+  transition: background-color 150ms var(--ease-out-soft), box-shadow 150ms var(--ease-out-soft);
+}
+
+.selected {
+  background: var(--color-bg);
+  color: var(--color-text);
+  box-shadow: var(--shadow-sm);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .option {
+    transition: none;
+  }
+}

web/src/ui/Segmented.test.tsx

@@ -0,0 +1,91 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { useState } from 'react'
+import { describe, expect, it } from 'vitest'
+import { expectMinHitArea } from '../test/hitArea.ts'
+import { Segmented } from './Segmented.tsx'
+import styles from './Segmented.module.css'
+
+const options = [
+  { value: 'week', label: 'Week' },
+  { value: 'month', label: 'Month' },
+  { value: 'year', label: 'Year' },
+] as const
+
+type Period = (typeof options)[number]['value']
+
+function Harness({ initial = 'week' }: { initial?: Period }) {
+  const [value, setValue] = useState<Period>(initial)
+  return <Segmented label="Archive period" options={options} value={value} onValueChange={setValue} />
+}
+
+function radio(name: string) {
+  return screen.getByRole('radio', { name })
+}
+
+describe('Segmented', () => {
+  it('is a named radiogroup of radios with one checked', () => {
+    render(<Harness />)
+    expect(screen.getByRole('radiogroup', { name: 'Archive period' })).toBeInTheDocument()
+    expect(screen.getAllByRole('radio')).toHaveLength(3)
+    expect(radio('Week')).toHaveAttribute('aria-checked', 'true')
+    expect(radio('Month')).toHaveAttribute('aria-checked', 'false')
+    expect(radio('Week')).toHaveClass(styles.selected!)
+  })
+
+  it('has a single tab stop on the selected option', () => {
+    render(<Harness initial="month" />)
+    expect(radio('Month')).toHaveAttribute('tabindex', '0')
+    expect(radio('Week')).toHaveAttribute('tabindex', '-1')
+    expect(radio('Year')).toHaveAttribute('tabindex', '-1')
+  })
+
+  it('moves selection and focus with the arrow keys, wrapping at the ends', () => {
+    render(<Harness />)
+    radio('Week').focus()
+
+    fireEvent.keyDown(radio('Week'), { key: 'ArrowRight' })
+    expect(radio('Month')).toHaveAttribute('aria-checked', 'true')
+    expect(radio('Month')).toHaveFocus()
+
+    fireEvent.keyDown(radio('Month'), { key: 'ArrowDown' })
+    expect(radio('Year')).toHaveAttribute('aria-checked', 'true')
+
+    fireEvent.keyDown(radio('Year'), { key: 'ArrowRight' })
+    expect(radio('Week')).toHaveAttribute('aria-checked', 'true')
+    expect(radio('Week')).toHaveFocus()
+
+    fireEvent.keyDown(radio('Week'), { key: 'ArrowLeft' })
+    expect(radio('Year')).toHaveAttribute('aria-checked', 'true')
+
+    fireEvent.keyDown(radio('Year'), { key: 'ArrowUp' })
+    expect(radio('Month')).toHaveAttribute('aria-checked', 'true')
+    expect(radio('Month')).toHaveFocus()
+    expect(radio('Year')).toHaveAttribute('aria-checked', 'false')
+  })
+
+  it('jumps to the first and last option with Home and End', () => {
+    render(<Harness initial="month" />)
+    fireEvent.keyDown(radio('Month'), { key: 'End' })
+    expect(radio('Year')).toHaveAttribute('aria-checked', 'true')
+    fireEvent.keyDown(radio('Year'), { key: 'Home' })
+    expect(radio('Week')).toHaveAttribute('aria-checked', 'true')
+  })
+
+  it('selects an option on click', () => {
+    render(<Harness />)
+    fireEvent.click(radio('Year'))
+    expect(radio('Year')).toHaveAttribute('aria-checked', 'true')
+    expect(radio('Week')).toHaveAttribute('aria-checked', 'false')
+  })
+
+  it('gives every option a ≥ 44 px hit area', () => {
+    render(<Harness />)
+    for (const option of screen.getAllByRole('radio')) expectMinHitArea(option)
+  })
+
+  it('fails fast when the value is not one of the options', () => {
+    expect(() =>
+      render(<Segmented label="Archive period" options={options} value={'decade' as Period} onValueChange={() => {}} />),
+    ).toThrow('value "decade" is not one of its options')
+  })
+})

web/src/ui/Segmented.tsx

@@ -0,0 +1,76 @@
+import { useRef, type KeyboardEvent } from 'react'
+import styles from './Segmented.module.css'
+
+export type SegmentedOption<T extends string> = {
+  value: T
+  label: string
+}
+
+export type SegmentedProps<T extends string> = {
+  // Accessible name of the radiogroup.
+  label: string
+  options: readonly SegmentedOption<T>[]
+  value: T
+  onValueChange: (value: T) => void
+  className?: string
+}
+
+const step: Record<string, number> = { ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1 }
+
+// Segmented control with radiogroup semantics: one tab stop (the selected
+// option); arrow keys move the selection and focus, wrapping at the ends;
+// Home and End jump to the first and last option.
+export function Segmented<T extends string>({ label, options, value, onValueChange, className }: SegmentedProps<T>) {
+  const refs = useRef<(HTMLButtonElement | null)[]>([])
+  const selected = options.findIndex((option) => option.value === value)
+  if (selected === -1) {
+    throw new Error(`Segmented "${label}": value "${value}" is not one of its options`)
+  }
+
+  function select(index: number) {
+    const option = options[index]
+    if (!option) throw new Error(`Segmented "${label}": no option at index ${index}`)
+    onValueChange(option.value)
+    refs.current[index]?.focus()
+  }
+
+  function onKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+    const delta = step[event.key]
+    let next: number
+    if (delta !== undefined) next = (selected + delta + options.length) % options.length
+    else if (event.key === 'Home') next = 0
+    else if (event.key === 'End') next = options.length - 1
+    else return
+    event.preventDefault()
+    select(next)
+  }
+
+  return (
+    <div
+      role="radiogroup"
+      aria-label={label}
+      className={[styles.track, className].filter(Boolean).join(' ')}
+      onKeyDown={onKeyDown}
+    >
+      {options.map((option, index) => {
+        const checked = index === selected
+        return (
+          <button
+            key={option.value}
+            ref={(el) => {
+              refs.current[index] = el
+            }}
+            type="button"
+            role="radio"
+            aria-checked={checked}
+            tabIndex={checked ? 0 : -1}
+            className={checked ? `${styles.option} ${styles.selected}` : styles.option}
+            onClick={() => select(index)}
+          >
+            {option.label}
+          </button>
+        )
+      })}
+    </div>
+  )
+}

web/src/ui/Sheet.module.css

@@ -0,0 +1,57 @@
+.root {
+  position: fixed;
+  inset: 0;
+  z-index: 100;
+}
+
+.scrim {
+  position: absolute;
+  inset: 0;
+  background: color-mix(in srgb, var(--color-neutral-900) 50%, transparent);
+  animation: fade 320ms var(--ease-out-soft);
+}
+
+.panel {
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  max-height: 90dvh;
+  overflow-y: auto;
+  padding: var(--space-6) var(--space-4) calc(var(--space-6) + env(safe-area-inset-bottom));
+  border-radius: var(--radius-lg) var(--radius-lg) 0 0;
+  background: var(--color-bg);
+  color: var(--color-text);
+  box-shadow: var(--shadow-lg);
+  transform: translateY(0);
+  animation: rise 320ms var(--ease-out-soft);
+}
+
+.panel:focus {
+  outline: none;
+}
+
+@keyframes rise {
+  from {
+    transform: translateY(100%);
+  }
+  to {
+    transform: translateY(0);
+  }
+}
+
+@keyframes fade {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .scrim,
+  .panel {
+    animation: none;
+  }
+}

web/src/ui/Sheet.test.tsx

@@ -0,0 +1,267 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { useState } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+import '../styles/tokens.css'
+import { animationKeyframes, declaredStyle, reducedMotionStyle } from '../test/cssRules.ts'
+import { Sheet } from './Sheet.tsx'
+import styles from './Sheet.module.css'
+
+function Harness({ withControls = true }: { withControls?: boolean }) {
+  const [open, setOpen] = useState(false)
+  return (
+    <>
+      <button type="button" onClick={() => setOpen(true)}>
+        Open Supply run
+      </button>
+      <Sheet aria-label="Supply run" open={open} onClose={() => setOpen(false)}>
+        <p>Grouped by dinner</p>
+        {withControls && (
+          <>
+            <button type="button">Try it</button>
+            <button type="button">Pass</button>
+          </>
+        )}
+      </Sheet>
+    </>
+  )
+}
+
+function openSheet() {
+  const opener = screen.getByRole('button', { name: 'Open Supply run' })
+  opener.focus()
+  fireEvent.click(opener)
+  return { opener, dialog: screen.getByRole('dialog', { name: 'Supply run' }) }
+}
+
+function scrim() {
+  const element = document.querySelector(`.${styles.scrim}`)
+  if (!element) throw new Error('scrim not rendered')
+  return element
+}
+
+describe('Sheet', () => {
+  it('renders nothing while closed', () => {
+    render(<Harness />)
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+  })
+
+  it('is a labelled modal dialog', () => {
+    render(<Harness />)
+    const { dialog } = openSheet()
+    expect(dialog).toHaveAttribute('aria-modal', 'true')
+  })
+
+  it('accepts aria-labelledby as its accessible name', () => {
+    render(
+      <>
+        <h2 id="sheet-title">Quest log</h2>
+        <Sheet aria-labelledby="sheet-title" open onClose={() => {}}>
+          <p>Nothing yet</p>
+        </Sheet>
+      </>,
+    )
+    expect(screen.getByRole('dialog', { name: 'Quest log' })).toBeInTheDocument()
+  })
+
+  it('moves focus to the first control and restores it to the opener on close', () => {
+    render(<Harness />)
+    const { opener } = openSheet()
+    expect(screen.getByRole('button', { name: 'Try it' })).toHaveFocus()
+    fireEvent.keyDown(document.activeElement!, { key: 'Escape' })
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+    expect(opener).toHaveFocus()
+  })
+
+  it('focuses the dialog itself when it has no focusable control', () => {
+    render(<Harness withControls={false} />)
+    const { dialog } = openSheet()
+    expect(dialog).toHaveFocus()
+  })
+
+  it('skips controls that cannot take keyboard focus when moving focus in', () => {
+    render(
+      <Sheet aria-label="Quest log" open onClose={() => {}}>
+        <button type="button" hidden>
+          Hidden
+        </button>
+        <button type="button" style={{ display: 'none' }}>
+          Not displayed
+        </button>
+        <button type="button" style={{ visibility: 'hidden' }}>
+          Invisible
+        </button>
+        <button type="button" tabIndex={-1}>
+          Not tabbable
+        </button>
+        <div aria-hidden="true">
+          <button type="button">Aria hidden</button>
+        </div>
+        <button type="button">Try it</button>
+      </Sheet>,
+    )
+    expect(screen.getByRole('button', { name: 'Try it' })).toHaveFocus()
+  })
+
+  it('focuses the dialog itself when every control is hidden', () => {
+    render(
+      <Sheet aria-label="Quest log" open onClose={() => {}}>
+        <button type="button" hidden>
+          Hidden
+        </button>
+      </Sheet>,
+    )
+    expect(screen.getByRole('dialog', { name: 'Quest log' })).toHaveFocus()
+  })
+
+  it('does not stop the Tab trap on a hidden control', () => {
+    render(
+      <Sheet aria-label="Quest log" open onClose={() => {}}>
+        <button type="button" hidden>
+          Hidden first
+        </button>
+        <button type="button">Try it</button>
+        <button type="button">Pass</button>
+        <button type="button" hidden>
+          Hidden last
+        </button>
+      </Sheet>,
+    )
+    const first = screen.getByRole('button', { name: 'Try it' })
+    const last = screen.getByRole('button', { name: 'Pass' })
+
+    last.focus()
+    fireEvent.keyDown(last, { key: 'Tab' })
+    expect(first).toHaveFocus()
+
+    fireEvent.keyDown(first, { key: 'Tab', shiftKey: true })
+    expect(last).toHaveFocus()
+  })
+
+  it('does not stop the Tab trap on a control disabled by its fieldset', () => {
+    render(
+      <Sheet aria-label="Quest log" open onClose={() => {}}>
+        <fieldset disabled>
+          <button type="button">Disabled first</button>
+        </fieldset>
+        <button type="button">Try it</button>
+        <button type="button">Pass</button>
+        <fieldset disabled>
+          <button type="button">Disabled last</button>
+        </fieldset>
+      </Sheet>,
+    )
+    const first = screen.getByRole('button', { name: 'Try it' })
+    const last = screen.getByRole('button', { name: 'Pass' })
+    expect(first).toHaveFocus()
+
+    last.focus()
+    fireEvent.keyDown(last, { key: 'Tab' })
+    expect(first).toHaveFocus()
+
+    fireEvent.keyDown(first, { key: 'Tab', shiftKey: true })
+    expect(last).toHaveFocus()
+  })
+
+  it('wraps Tab and Shift+Tab inside the sheet', () => {
+    render(<Harness />)
+    openSheet()
+    const first = screen.getByRole('button', { name: 'Try it' })
+    const last = screen.getByRole('button', { name: 'Pass' })
+
+    last.focus()
+    fireEvent.keyDown(last, { key: 'Tab' })
+    expect(first).toHaveFocus()
+
+    fireEvent.keyDown(first, { key: 'Tab', shiftKey: true })
+    expect(last).toHaveFocus()
+  })
+
+  it('keeps focus on the dialog when Tab has nowhere to go', () => {
+    render(<Harness withControls={false} />)
+    const { dialog } = openSheet()
+    const tab = fireEvent.keyDown(dialog, { key: 'Tab' })
+    expect(tab).toBe(false) // default prevented
+    expect(dialog).toHaveFocus()
+  })
+
+  it('closes on Escape', () => {
+    const onClose = vi.fn()
+    render(
+      <Sheet aria-label="Supply run" open onClose={onClose}>
+        <button type="button">Try it</button>
+      </Sheet>,
+    )
+    fireEvent.keyDown(screen.getByRole('button', { name: 'Try it' }), { key: 'Escape' })
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('closes on a scrim click but not on a panel click', () => {
+    const onClose = vi.fn()
+    render(
+      <Sheet aria-label="Supply run" open onClose={onClose}>
+        <p>Grouped by dinner</p>
+      </Sheet>,
+    )
+    fireEvent.click(screen.getByRole('dialog'))
+    fireEvent.click(screen.getByText('Grouped by dinner'))
+    expect(onClose).not.toHaveBeenCalled()
+    fireEvent.click(scrim())
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('makes the background inert while open and restores it on close', () => {
+    const { container } = render(<Harness />)
+    openSheet()
+    const root = screen.getByRole('dialog').parentElement!
+    expect(root.parentElement).toBe(document.body)
+    expect(container).toHaveAttribute('inert')
+    expect(root).not.toHaveAttribute('inert')
+
+    fireEvent.click(scrim())
+    expect(container).not.toHaveAttribute('inert')
+  })
+
+  it('leaves an already-inert background element inert after close', () => {
+    const other = document.createElement('div')
+    other.setAttribute('inert', '')
+    document.body.append(other)
+    try {
+      render(<Harness />)
+      openSheet()
+      fireEvent.click(scrim())
+      expect(other).toHaveAttribute('inert')
+    } finally {
+      other.remove()
+    }
+  })
+
+  it('rises from 100% to 0 over 320 ms with the soft ease-out', () => {
+    render(<Harness />)
+    const { dialog } = openSheet()
+    expect(declaredStyle(dialog).animation.split(' ').slice(1)).toEqual(['320ms', 'var(--ease-out-soft)'])
+    const easing = getComputedStyle(document.documentElement).getPropertyValue('--ease-out-soft')
+    expect(easing.replace(/\s/g, '')).toBe('cubic-bezier(.2,.8,.2,1)')
+    const rise = animationKeyframes(dialog)
+    expect(rise.findRule('from')?.style.transform).toBe('translateY(100%)')
+    expect(rise.findRule('to')?.style.transform).toBe('translateY(0)')
+  })
+
+  it('fades the scrim in to 50% neutral-900', () => {
+    render(<Harness />)
+    openSheet()
+    const style = declaredStyle(scrim())
+    expect(style.background).toBe('color-mix(in srgb, var(--color-neutral-900) 50%, transparent)')
+    expect(style.animation.split(' ').slice(1)).toEqual(['320ms', 'var(--ease-out-soft)'])
+    const fade = animationKeyframes(scrim())
+    expect(fade.findRule('from')?.style.opacity).toBe('0')
+    expect(fade.findRule('to')?.style.opacity).toBe('1')
+  })
+
+  it('opens in place with no rise or fade under reduced motion', () => {
+    render(<Harness />)
+    const { dialog } = openSheet()
+    expect(reducedMotionStyle(dialog).animation).toBe('none')
+    expect(reducedMotionStyle(scrim()).animation).toBe('none')
+    expect(declaredStyle(dialog).transform).toBe('translateY(0)')
+  })
+})

web/src/ui/Sheet.tsx

@@ -0,0 +1,123 @@
+import { useEffect, useRef, type KeyboardEvent, type ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import styles from './Sheet.module.css'
+
+// The dialog's accessible name: exactly one of a label or a labelling element.
+type SheetName =
+  | { 'aria-label': string; 'aria-labelledby'?: never }
+  | { 'aria-labelledby': string; 'aria-label'?: never }
+
+export type SheetProps = SheetName & {
+  open: boolean
+  onClose: () => void
+  children: ReactNode
+}
+
+const focusableSelector = [
+  'a[href]',
+  'button',
+  'input',
+  'select',
+  'textarea',
+  '[tabindex]',
+].join(',')
+
+// Whether an element can take keyboard focus: being disabled (by its own
+// attribute or a disabled fieldset), a negative tabIndex, a hidden, aria-hidden
+// or inert ancestor (or self), display: none on the way up to the panel, or
+// visibility: hidden all rule it out.
+function isKeyboardFocusable(element: HTMLElement, panel: HTMLElement): boolean {
+  if (element.matches(':disabled')) return false
+  if (element.tabIndex < 0) return false
+  if (element.closest('[hidden], [aria-hidden="true"], [inert]')) return false
+  if (getComputedStyle(element).visibility === 'hidden') return false
+  for (let node: HTMLElement | null = element; node && node !== panel; node = node.parentElement) {
+    if (getComputedStyle(node).display === 'none') return false
+  }
+  return true
+}
+
+function focusables(panel: HTMLElement): HTMLElement[] {
+  return Array.from(panel.querySelectorAll<HTMLElement>(focusableSelector)).filter((element) =>
+    isKeyboardFocusable(element, panel),
+  )
+}
+
+// Focuses the first control that actually takes focus, or the panel if none does.
+function focusFirst(panel: HTMLElement) {
+  for (const element of focusables(panel)) {
+    element.focus()
+    if (document.activeElement === element) return
+  }
+  panel.focus()
+}
+
+// Modal bottom sheet. Portalled to <body> so everything else there can be made
+// inert while it is open. Focus moves in on open, Tab is trapped inside, and
+// focus returns to the opener on close. Escape and a scrim click call onClose.
+export function Sheet({ open, onClose, children, ...name }: SheetProps) {
+  const rootRef = useRef<HTMLDivElement>(null)
+  const panelRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const root = rootRef.current
+    const panel = panelRef.current
+    if (!open || !root || !panel) return
+
+    const opener = document.activeElement instanceof HTMLElement ? document.activeElement : null
+    const background = Array.from(document.body.children).filter(
+      (element) => element !== root && !element.hasAttribute('inert'),
+    )
+    for (const element of background) element.setAttribute('inert', '')
+    focusFirst(panel)
+
+    return () => {
+      for (const element of background) element.removeAttribute('inert')
+      opener?.focus()
+    }
+  }, [open])
+
+  if (!open) return null
+
+  function onKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+    if (event.key === 'Escape') {
+      event.stopPropagation()
+      onClose()
+      return
+    }
+    if (event.key !== 'Tab' || !panelRef.current) return
+    const items = focusables(panelRef.current)
+    const first = items[0]
+    const last = items[items.length - 1]
+    if (!first || !last) {
+      event.preventDefault()
+      return
+    }
+    const active = document.activeElement
+    if (event.shiftKey && (active === first || active === panelRef.current)) {
+      event.preventDefault()
+      last.focus()
+    } else if (!event.shiftKey && active === last) {
+      event.preventDefault()
+      first.focus()
+    }
+  }
+
+  return createPortal(
+    <div ref={rootRef} className={styles.root}>
+      <div className={styles.scrim} aria-hidden="true" onClick={onClose} />
+      <div
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        tabIndex={-1}
+        className={styles.panel}
+        onKeyDown={onKeyDown}
+        {...name}
+      >
+        {children}
+      </div>
+    </div>,
+    document.body,
+  )
+}