AI Nutrition Coach as an installable, offline-capable web app (PWA)¶
AI Nutrition Coach's web build is a Progressive Web App: you open one URL on your phone, add it to the home screen, and from then on it has its own icon, opens without a connection and tells you calmly when a new version is ready. For a family trial this is the way to use AI Nutrition Coach: the web app is what you deploy and hand around.
This page is the whole story: what changed and why, how it works, how to build, run and deploy it (including behind Traefik), how to install it on a phone, how updates work, backup and limits, and what to do when something looks wrong. Design record: ADR-0003.
- What changed and why
- How it works
- Build
- Run locally
- Deploy behind Traefik
- Install on phones
- Updating
- Backup and restore
- Limitations
- Browser smoke (WebKit and Chromium)
- Troubleshooting
What changed and why¶
| Before | Now |
|---|---|
| Needed a connection to start; no icon | Own service worker precaches the app: opens offline, installable (manifest with maskable icons, iOS tags) |
| No update story | A new image shows a calm "A new version is ready — Reload" line; one tap activates it |
| The browser could evict the data silently | The app asks the browser to protect it (navigator.storage.persist()), says what the browser answered, tracks the last export and suggests one now and then |
| BYOK key and AI settings lived in memory, re-entered after every lock | They are stored inside the encrypted web store and read after you unlock |
Barcode scanning only where the browser has BarcodeDetector (not Safari) |
A SHA-256-verified zxing-wasm decoder is served from your own origin: Safari/iOS and Firefox scan too |
| Deploy: loopback or the Caddy profile | Also: behind your existing Traefik (Docker or host), no published port |
Nothing about the trust model changed: the server is still a static file server
that holds no data, makes no outbound request and never sees your passphrase or
your history (ADR-0005). The CSP is strict
(script-src 'self' 'wasm-unsafe-eval', style-src 'self', no inline script or style, no CDN).
How it works¶
Service worker: caches, offline, updates¶
The app is a Vite build (apps/web). Vite names its JS and CSS by content hash
(assets/index-<hash>.js), so the build id is a hash of the file list and their SHA-256s:
any change to a shipped file changes the bytes of sw.js, which is exactly what makes a browser
run its update check. After vite build, tools/generate_precache_manifest.mjs writes two files into apps/web/dist:
precache-manifest.json—{ buildId, files: [ { url, sha256, size } ] }for every file in the bundle except source maps and dotfiles:index.html,boot-guard.js, the hashed JS/CSS chunks (includingstore.worker-<hash>.js), the web manifest, icons, fonts, licence texts, the versionedsqlite3mc/<ver>/engine (sqlite3.mjs+sqlite3.wasm) and the self-hostedzxing/<ver>/decoder and theargon2/<ver>/argon2.umd.min.jsbuild (encrypted backups work offline). The generator refuses a bundle that cannot boot offline: it must contain the document, the web manifest, the boot guard, every local script/stylesheet/module the document references, the store worker chunk and the sqlite3mc, zxing and Argon2id files.sw.js—tools/pwa/sw.template.jswith the build id baked in. (AI_NUTRITION_COACH_BUILD_ID=...or--build-idforces an id, e.g. to test the banner.)
The worker is hand-written and hardened (tools/pwa/sw.template.js); its
manifest is generated for Vite's output, and vite-plugin-pwa/Workbox is not used (the plugin's
generateSW could not express the SHA-256 verification, the always-refetched index.html, the
header-preserving cache entries or the waiting-only update; the generator and the template are
~350 lines and are covered by tools/pwa/*.test.mjs, which executes the worker against a fake
CacheStorage).
What the worker does:
| Event | Behaviour |
|---|---|
| install | Precache the manifest into the cache ai-nutrition-coach-precache-<buildId>: cache-busting fetches, each body checked against its SHA-256, files unchanged since the previous build reused from its cache. Any failure aborts the install and the running version is untouched. |
| waiting | The new worker waits. It never takes over by itself. |
SKIP_WAITING message |
Sent when you tap Reload → skipWaiting(). |
| activate | Deletes every other ai-nutrition-coach-precache-* cache and claims open pages. |
| fetch | GET + same-origin only. A page navigation (a path without a file extension) gets the cached index.html, online or offline, so a page load is always one consistent build. A precached file is served cache-first. Anything else goes to the network untouched. Cross-origin requests (Open Food Facts, your AI endpoint) and all non-GET requests are never intercepted, and the worker never writes a cache at run time, so no API response can be cached. |
Registration is done by the app itself (apps/web/src/pwa/app-update.ts, a same-origin module —
hence no inline script and no CSP change), only on a secure context and only in a release build
(pnpm dev never registers it, so development is never served from a stale cache). The app checks
for a new version on every load and whenever it comes back to the foreground. The web manifest
(apps/web/public/manifest.webmanifest) is a static file linked from index.html.
The manifest is one file with "lang": "en": browsers read it once, at install, and do not
localise it per person, so the install name ("AI Nutrition Coach"), short name and description stay
English whatever language the app is set to. (The brand name is not translated.) The language the
person picked applies inside the app; <html lang> is set before the app bundle runs by
boot-guard.js (no inline script is allowed by the CSP) and kept up to date by the app.
The update flow in the UI: the new worker finishes installing → the app shows one
dismissible line ("A new version is ready. Reloading locks your data, so you will enter your
passphrase again." — Reload / Later) → Reload posts SKIP_WAITING → the page reloads
once, when the browser reports the new worker in control. "Later" hides the line for the
visit; there is no badge, no counter, no repeat.
The sw.js and precache-manifest.json your server sends are rendered when the container starts
(infra/nginx/docker-entrypoint.d/30-render-sw.sh): the build id is <bundle id>-<12 hex of a hash of the rendered
security headers>. The headers matter because the worker serves the cached index.html with the headers it was
fetched with (the stored responses keep the network response's headers, minus Content-Encoding/Content-Length/
Transfer-Encoding/Set-Cookie, and the document is always re-fetched on an update). So changing
AI_NUTRITION_COACH_CONNECT_SRC_EXTRA and restarting the container is a new service-worker version: installed apps show the
"new version is ready" line and pick up the new CSP when the user taps Reload. nginx serves sw.js, precache-manifest.json, manifest.webmanifest, index.html and boot-guard.js
with Cache-Control: no-cache; Vite's hashed assets/* and the versioned sqlite3mc/<ver>/,
zxing/<ver>/ and argon2/<ver>/ files are public, max-age=31536000, immutable; the worker is served from /, so its
scope is / and no Service-Worker-Allowed header is needed. CSP worker-src 'self' blob: already
allows it.
Storage and persistence¶
Your data is the encrypted SQLite database in the browser's origin-private file system (OPFS), opened by a
worker (ADR-0005; your-data.md). Browsers may clear a site's storage when space runs low unless
the site is persistent, so after every create/unlock (once, and only if not already protected)
the app calls navigator.storage.persist(). Your data then shows one plain line:
- "Storage: protected from automatic clean-up." or
- "Storage: the browser may clear this data if space runs low — export regularly."
Whether the request is granted is the browser's decision (Chromium usually grants it to an installed app; Firefox asks you; Safari grants it for apps added to the Home Screen). The app does not nag in either case.
The time of the last export is stored in the encrypted store (not in localStorage). Your data
shows "Last export:
Encryption recap and where the BYOK key lives¶
ChaCha20-Poly1305 pages (SQLite3 Multiple Ciphers, WebAssembly) in a worker on OPFS; the key is derived from your passphrase and held in memory only while unlocked; the page locks after idle / hidden time; one tab at a time (Web Locks). The parameters are in ADR-0005.
Your BYOK key (bound to the host it was entered for) and your AI settings and per-host consents live
inside the encrypted database, readable only after the passphrase unlock, and deleted by Erase all local
data. They are never in localStorage. See ai-tiers.md.
Barcode decoder¶
The scanner uses the browser's native BarcodeDetector where it exists (Chrome, Edge) and otherwise
zxing-wasm. By default that library loads its wasm from a CDN, which the CSP blocks. The build therefore
self-hosts it: scripts/fetch_web_zxing_pwa.sh downloads the exact npm tarball (zxing-wasm 3.1.1, MIT,
bundling zxing-cpp, Apache-2.0), verifies its SHA-256, rewrites the one CDN wasm URL to a path next to the
reader, verifies the result against a second SHA-256, and writes apps/web/public/zxing/3.1.1/ (git-ignored;
the version is in the path so nginx caches it as immutable). The decoder runs entirely on the device; the
camera never leaves it. If the decoder cannot start, the scanner shows the calm "scanning isn't available in
this browser — type it instead" and manual entry still works.
Argon2id for the encrypted backup¶
The encrypted backup file (docs/adr/0007-encrypted-vault.md, phase S1) derives its key from a
passphrase with Argon2id, which WebCrypto does not have. scripts/fetch_web_argon2.sh downloads the
exact npm tarball (hash-wasm 4.12.0, MIT, Dani Biro), verifies its SHA-256, removes the one package
URL from the licence banner (the host scan flags any URL), verifies the result against a second
SHA-256 and writes apps/web/public/argon2/4.12.0/argon2.umd.min.js (git-ignored; versioned path, so
immutable; precached). It is the same single file the unit tests run, loaded by a module worker
(src/sync/vault/argon2.worker.ts) so the 64 MiB, three-pass derivation never blocks the page; the
worker is terminated as soon as it answers. CSP needs nothing new ('wasm-unsafe-eval' and
worker-src 'self' blob: are already there) and nothing is requested from another host.
Content-Security-Policy¶
Strict, and set by the server (infra/nginx/templates/ai-nutrition-coach-headers.inc.template):
default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; style-src 'self'; img-src 'self' data: blob:;
font-src 'self'; media-src 'self' blob:; worker-src 'self' blob:;
connect-src 'self' https://world.openfoodfacts.org <AI_NUTRITION_COACH_CONNECT_SRC_EXTRA>;
manifest-src 'self'; object-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'
- No
'unsafe-inline', not even for styles. The build ships its CSS as a file, and React'sstyle={}props are applied through the CSSOM (element.style), whichstyle-srcdoes not govern; onlystyle=""attributes in markup and<style>elements are. The e2e suite and the browser smoke fail on any Content-Security-Policy violation, so an inline style added later is a red build. (vite devadds'unsafe-inline'for its HMR style injection; the release never has it.) index.htmlalso carries a<meta>CSP with onlyscript-src,worker-src,object-src,base-uriandform-action: a meta and a header CSP are both enforced, so a metaconnect-srccould never be widened by the knob below.connect-srctherefore exists only in the header.- The one knob is
AI_NUTRITION_COACH_CONNECT_SRC_EXTRA: this is where you add the origin of your own AI endpoint (BYOK), e.g.https://api.openai.com. Without it the browser blocks the call. Details inself-host.md.
Build¶
Needs Node 24 and pnpm (corepack enable; the version is pinned in package.json), or just Docker for the image.
pnpm install
# The whole gate (format, lint, typecheck, unit tests incl. the service-worker tests, build, scans):
pnpm verify
# Just the release web bundle (fetches + verifies sqlite3mc, zxing and Argon2id, tsc, vite build, then writes
# sw.js + precache-manifest.json and refuses a bundle that cannot boot offline):
pnpm --filter @anc/web build # -> apps/web/dist
# Re-generate only sw.js + precache-manifest.json for an existing bundle
# (AI_NUTRITION_COACH_BUILD_ID forces a new build id, e.g. to test the update banner):
AI_NUTRITION_COACH_BUILD_ID=test-2 pnpm --filter @anc/web precache
# The production image (node build stage, then nginx-unprivileged; the scans fail the build):
docker build -f infra/Dockerfile -t ai-nutrition-coach:dev .
Icons: the SVG sources are in tools/icons/; the PNGs in apps/web/public/icons/ are committed (the
192 px maskable icon is the 512 px one scaled down). The generator that drew them was removed with
the earlier client; to change the icon, edit the SVGs and re-render the PNGs with any SVG rasteriser.
Run locally¶
bin/ai-nutrition-coach up # builds the image, serves http://localhost:8080/ (loopback only)
bin/ai-nutrition-coach down
scripts/run_local_web.sh # the Vite dev server on 127.0.0.1 (no service worker), open Chrome
http://localhost counts as a secure context, so the service worker, the encrypted store and the camera
all work there; http://192.168.x.y:8080 does not. To try it on a phone you need HTTPS: use the Caddy
profile or Traefik below (or scripts/run_local_web.sh --tunnel, which serves the release bundle through
an ngrok URL, with throwaway data).
Deploy behind Traefik¶
Your Traefik terminates HTTPS and proxies to the app container, which stays local-only: no published port. Two variants.
Variant A — Traefik in Docker on the same host (most likely)¶
Assumptions: Traefik v3 with the Docker provider (providers.docker, exposedByDefault=false), already
attached to a Docker network (conventionally called traefik), an HTTPS entrypoint (conventionally
websecure), and a DNS record for your domain pointing at the host.
- Create the network if you do not have one, and attach Traefik to it:
docker network create traefik. - Build and start:
AI_NUTRITION_COACH_DOMAIN=plate.example.com \
AI_NUTRITION_COACH_TRAEFIK_CERTRESOLVER=letsencrypt \
AI_NUTRITION_COACH_CONNECT_SRC_EXTRA="https://api.openai.com" \
bin/ai-nutrition-coach up --traefik
(bin/ai-nutrition-coach down stops it. The network is external and is never removed.) The equivalent compose
command, which bin/ai-nutrition-coach up --traefik runs after building the image:
AI_NUTRITION_COACH_DOMAIN=plate.example.com AI_NUTRITION_COACH_TRAEFIK_CERTRESOLVER=letsencrypt \
docker compose -f infra/docker-compose.traefik.yml \
-f infra/docker-compose.traefik-certresolver.yml up -d
https://plate.example.com/.
What infra/docker-compose.traefik.yml does: the same hardened container as the base file (read-only, no
capabilities, no-new-privileges) with no ports:, joined to the external network; labels
traefik.enable=true, router ai-nutrition-coach with Host(`$AI_NUTRITION_COACH_DOMAIN`) on $AI_NUTRITION_COACH_TRAEFIK_ENTRYPOINT,
tls=true, service port 8080, and a middleware ai-nutrition-coach-hsts (Strict-Transport-Security, one year, no
preload, subdomains only if you ask). That middleware sets only HSTS: Traefik's headers middleware changes
nothing it is not told to, so the app's CSP, COOP, Permissions-Policy and the rest pass through untouched.
It is a standalone file (not an override of docker-compose.yml) because compose cannot remove a published
port inherited from another file without !reset; here the absence of ports: is structural.
| Variable | Default | Meaning |
|---|---|---|
AI_NUTRITION_COACH_DOMAIN |
required | Public host name (bin/ai-nutrition-coach checks it is a plain hostname). |
AI_NUTRITION_COACH_TRAEFIK_NETWORK |
traefik |
The existing Docker network shared with Traefik (must exist). |
AI_NUTRITION_COACH_TRAEFIK_ENTRYPOINT |
websecure |
Name of Traefik's HTTPS entrypoint. |
AI_NUTRITION_COACH_TRAEFIK_CERTRESOLVER |
unset | Your ACME resolver name. When set, up --traefik adds the overlay docker-compose.traefik-certresolver.yml; when unset no certresolver label exists at all (use this if Traefik serves a wildcard/default certificate). |
AI_NUTRITION_COACH_TRAEFIK_ALLOWLIST |
unset | Comma-separated CIDRs allowed to connect, e.g. 192.168.1.0/24,100.64.0.0/10. Adds the overlay docker-compose.traefik-allowlist.yml (Traefik v3 ipAllowList). |
AI_NUTRITION_COACH_TRAEFIK_HSTS_SUBDOMAINS |
false |
true adds includeSubdomains to HSTS. |
AI_NUTRITION_COACH_CONNECT_SRC_EXTRA |
empty | Extra CSP connect-src origins — the BYOK AI endpoint goes here (validated: space-separated https://host[:port] only). |
AI_NUTRITION_COACH_IMAGE_TAG |
ai-nutrition-coach:dev |
Image to build/run. |
bin/ai-nutrition-coach up --traefik validates every value with a strict pattern before it reaches a label (a
domain, network, entrypoint or resolver can never add a label or alter the router rule), and exits with 41
(no domain), 42 (invalid value) or 43 (the network does not exist).
Variant B — Traefik on the host¶
Run the app container loopback-only (the default), and route to it with the file provider:
bin/ai-nutrition-coach up --compose # 127.0.0.1:8080 only
cp infra/traefik/ai-nutrition-coach-dynamic.yml /etc/traefik/dynamic/ai-nutrition-coach.yml # your providers.file directory
# edit the domain, entrypoint and resolver marked EDIT; add `ai-nutrition-coach-allow` to the router for family-only access
infra/traefik/ai-nutrition-coach-dynamic.yml routes Host(`plate.example.com`) to http://127.0.0.1:8080 with the
same HSTS-only middleware and an optional ipAllowList.
DNS and certificates¶
Point an A/AAAA record at the host (the same name as AI_NUTRITION_COACH_DOMAIN). For Let's Encrypt, ports 80 and 443
must reach Traefik and your resolver must be configured in Traefik's static configuration. If you prefer
no public exposure, use a DNS-01 resolver or a wildcard certificate and keep the host reachable only over your
VPN. Browsers need a valid certificate for the service worker and the encrypted store; a self-signed
certificate you clicked through is not enough for a service worker.
Logs behind Traefik¶
AI Nutrition Coach's own container logs nothing per request by default
(AI_NUTRITION_COACH_ACCESS_LOG=off, docs/self-host.md). Traefik is the
one that sees the real client addresses, and its access log is off unless you turned it on.
Recommendations:
- Leave Traefik's access log disabled. If you need it, keep it short-lived and
minimal:
--accesslog.fields.defaultmode=dropwith--accesslog.fields.names.RequestPath=keep,DownstreamStatus=keep,StartUTC=keep, and noClientAddr/ClientHost; or let Traefik anonymise it with--accesslog.fields.names.ClientAddr=drop. Never keep therequest_User-Agent/request_Refererheaders (--accesslog.fields.headers.defaultmode=drop). - Set a retention: rotate (or let Docker rotate:
json-filewithmax-size/max-file) and delete after days, not months. Address + time + path is personal data about when the family uses the app. - Do not forward AI Nutrition Coach's or Traefik's logs to a third-party log service.
Family-only access¶
Pick one, in this order of preference:
- Don't expose it publicly: a VPN (WireGuard, Tailscale) and a name that only resolves inside it.
- IP allow-list in Traefik (
AI_NUTRITION_COACH_TRAEFIK_ALLOWLIST). It judges the address Traefik sees: behind Docker NAT or another proxy that may be the proxy's address, so test from outside the list. - A forward-auth sign-in you already run (Authentik, Authelia): the
traefik-auth(+traefik-authentik) overlays, seedocs/self-host.md. The manifest is requested with the session cookie, so the app stays installable. - Nothing: the app itself is protected by the passphrase (data is encrypted in each browser, the server holds none). Open access to the app shell exposes only static files.
Prefer these to Traefik basic auth in front of this app: the browser fetches the web manifest without credentials, so installability checks can fail behind basic auth (not tested here). A VPN or an IP allow-list avoids the question; the passphrase still protects the data.
Install on phones¶
Open your HTTPS address in the phone's browser first (add it to the home screen before you start logging — see limitations).
- iPhone / iPad (Safari): tap Share → Add to Home Screen → Add. (Other iOS browsers can also add to the Home Screen from their share menu on recent iOS versions.) There is no install prompt on iOS; Settings → Install on your phone in the app repeats these steps.
- Android (Chrome): menu (⋮) → Install app (or Add to Home screen). Settings → Install on your phone also shows an Install button when Chrome offers installation.
- Desktop (Chrome / Edge): the install icon at the right of the address bar, or the browser menu → Install AI Nutrition Coach.
What installing changes: it opens without a connection once it has loaded once; it has its own icon and no browser bars; on iPhone, Safari may clear a website's data after a while without a visit, but an app added to the Home Screen is not subject to that. It does not move data: see below.
Updating¶
Deploy a new image (bin/ai-nutrition-coach up --traefik again, or docker compose ... up -d with a new
AI_NUTRITION_COACH_IMAGE_TAG). Installed apps check for a new version when they open and when they return to the
foreground. When the new version has finished installing in the background they show the calm line "A new
version is ready" — tap Reload (the page reloads once and asks for your passphrase again) or Later.
Old caches are deleted when the new version activates. Nothing else is needed on the phones; data is untouched.
Store migrations run automatically the first time the new version opens the store.
If an update goes wrong: the escape hatches¶
- A build that crashes at start-up can keep serving itself from the worker's cache, and it never reaches the
code that shows the banner.
boot-guard.js(a separate classic script, loaded byindex.htmlindependently of the app bundle and served by the worker like everything else) therefore checks, 20 s after it ran, whether the app painted anything into#root; if not, and a newer worker is waiting, it activates it once (asessionStorageflag prevents reload loops) and the page reloads into the fix. Deploy the fixed image; open the app; wait ~30 s. - Kill switch — when that is not enough (the bootstrap itself is broken, or no newer worker will install):
restart the container with
AI_NUTRITION_COACH_SW_KILL=1, e.g.
AI_NUTRITION_COACH_SW_KILL=1 docker compose -f infra/docker-compose.traefik.yml up -d # or: docker run -e AI_NUTRITION_COACH_SW_KILL=1 ...
The container then serves tools/pwa/sw.kill.js as /sw.js (an empty precache manifest). Browsers fetch it on
their next visit/foreground; it takes over immediately (no banner, no tap), deletes every cache (they hold
only app files — never your history, which is the encrypted store in OPFS), and reloads each open window once
from the network. It has no fetch handler, so everything then loads straight from the server. It deliberately does
not unregister itself (the app registers /sw.js on every load; an unregistered kill switch would be
re-installed and reload the page forever). Once users are healthy, redeploy normally (without the variable):
the normal worker replaces the kill switch through the usual banner flow.
3. Data written by a newer version (for example another tab still ran a newer build): the unlock screen says
"This data was opened by a newer version of AI Nutrition Coach… reload the page to update". Nothing is lost or changed;
reloading gets the current build.
Also: every tab reloads once when a new worker takes control (not only the tab where you tapped Reload), and Reload never dead-ends: if no worker is waiting it reloads directly, and if the browser never reports the takeover it reloads after 10 s.
Backup and restore¶
There is no server-side data unless the person who runs the server turned on the optional encrypted-backup relay
(self-host.md); then a person can choose to keep an encrypted
copy there, which the server cannot read. Otherwise the server cannot back anything up. Every browser/device is an independent
store: your phone, your partner's phone and the laptop each have their own history, protected by their own
passphrase. Use Your data → Save an encrypted backup as the backup (a .ancvault file, restorable on the
create-passphrase screen or in Your data; your-data.md); the app records
the date and suggests a new one every few weeks. A CSV or JSON export is a readable copy of your history, not a
restore path. A forgotten passphrase cannot be recovered by anyone.
Limitations¶
- iOS keeps an installed app's data separate from Safari's. What you logged in a Safari tab is not in the Home Screen app (and vice versa). Install first, then log; use exports to carry anything across.
- iOS storage rules. Safari may evict a tab's site data after a period without visiting; Home Screen apps are
exempt. Chromium and Firefox decide
persist()differently (see above). Keep exports regardless. - Passphrase every time the app opens, and again after the idle lock (15 minutes by default) or 5 minutes hidden. This is by design (ADR-0002); there is no "stay unlocked".
- One tab at a time. A second tab/window says AI Nutrition Coach is open elsewhere.
- No live sync. Devices do not talk to each other; the optional relay keeps an encrypted copy (restore, join, automatic upload), and pulling another device's changes on unlock is a later phase.
- Camera needs HTTPS (or localhost) and your permission; the scanner decodes on the device.
- Fonts: Barlow is self-hosted; a character outside it falls back to the system font (no CDN, by design).
Browser smoke (WebKit and Chromium)¶
scripts/webkit_smoke.sh runs the production image (hardened like the compose file) and drives it with
Playwright (the official image, pinned by digest, sharing the server's network namespace so the page is
http://localhost:8080, a secure context) in WebKit — Safari's engine — and Chromium, with real selectors
(tools/webkit_smoke/smoke.spec.mjs):
- the web manifest and icons are valid, the service worker registers and precaches exactly the files of
precache-manifest.json, with no CSP violation; - first run: create a passphrase, log a plate by Type it, see it on Today and the durable-storage line; reload → unlock → the plate is there;
- offline reload served by the worker; unlock; the plate is there;
- update: the build id changes → the new worker waits (both caches exist) → the banner appears → Reload reloads exactly once → the old cache is deleted → unlock → the data is intact;
- in Chromium only (Playwright's WebKit has no fake camera): a barcode step: a fake camera shows an
EAN-13, the one-time Open Food Facts notice appears before anything is sent, and after OK exactly one
request leaves —
GET /api/v2/product/<code>?fields=…, no Referer / Cookie / Authorization (the host is answered by the test; nothing real is contacted); - export downloads a plain CSV;
- in every test, no request to any other origin (each is aborted and recorded) and no uncaught page error.
It is opt-in (needs Docker and the network; the Playwright image is ~3 GB), runs in CI as the image job
of .github/workflows/ci.yml and is in the release checklist. The same
offline-reload and update flows also run on every PR in pnpm e2e (apps/web/e2e/pwa.spec.ts, Chromium and
WebKit) against a small static server that plays "a new version was deployed".
scripts/webkit_smoke.sh # both browsers (builds the image)
BROWSERS=webkit scripts/webkit_smoke.sh --no-build
Known gaps, stated plainly: Firefox is not tested, and neither is a real iPhone Safari (Playwright's WebKit is
the same engine, not the same browser: it has no navigator.storage.persist() grant, for one).
Troubleshooting¶
| Symptom | Likely cause and fix |
|---|---|
| Stuck on an old version | Close every AI Nutrition Coach tab/app window and reopen (the update applies on next open), or tap Reload on the banner. To force it from a desktop browser: DevTools → Application → Service Workers → Unregister, and Cache Storage → delete the ai-nutrition-coach-precache-* entries, then reload. Do not use "Clear site data" / "Clear storage": that also erases your encrypted history (OPFS) — export first if you must. On a phone: removing the Home Screen app and re-adding it also fixes it (on iOS this discards that app's data — export first). |
| "Web storage unavailable" / store unavailable | The page is not a secure context: you opened http://<ip> instead of https://… or http://localhost, or the certificate is not trusted. Fix the URL/certificate. Private browsing modes can also block OPFS (an ephemeral WebKit context has none). |
| The app never becomes installable / no install icon | Needs HTTPS with a valid certificate, the manifest and the service worker. Check https://<host>/manifest.webmanifest and /sw.js load without credentials (basic auth breaks this) and DevTools → Application → Manifest shows no errors. |
| The AI call is blocked / "Test connection" fails | CSP connect-src: add the endpoint origin to AI_NUTRITION_COACH_CONNECT_SRC_EXTRA and restart the container (browser console shows a CSP violation). |
| Camera / scanner does nothing | Allow the camera for the site in the browser settings; needs HTTPS. If the decoder fails to start the screen says so and manual entry still works. |
| White page / the app never starts after an update | Wait ~30 s (the bootstrap activates a waiting fix once). Still broken: use the kill switch (see Updating → If an update goes wrong). |
| The banner never appears after a deploy | The browser checks on open/foreground; reopen the app once. Check that sw.js is served no-cache (curl -I https://<host>/sw.js) and that its BUILD_ID differs from the old one (it changes with the bundle and with any change to the security headers, e.g. AI_NUTRITION_COACH_CONNECT_SRC_EXTRA). |
| "Open in another tab" | Another tab/window holds the store; lock or close it, then retry. |
| Blank page after an update on iOS | Remove the Home Screen app and re-add it (export first if it had data). |