feat(ui): installable offline PWA — service worker, manifest, icons (F5)
Tests · UI / test (push) Failing after 7m31s

Native SvelteKit service worker (src/service-worker.ts): a version-keyed
cache precaches the app shell + build artefacts (incl. core.wasm) +
static files; activate purges old caches; the gateway is never
intercepted; navigations fall back to the cached shell offline. Adds
static/manifest.webmanifest, a generated placeholder icon set
(scripts/gen-pwa-icons.mjs — dependency-free pure-Node PNG encoder), and
manifest / theme-color / apple-touch tags in app.html.

Gated by Playwright against a production preview (playwright.pwa.config.ts
+ tests/pwa/pwa.spec.ts via `pnpm test:pwa`, wired into ui-test):
manifest + installable icons, SW registration + a single version-keyed
cache, and offline shell load. Lighthouse is not used — its PWA category
was removed in v12.

Docs: ui/docs/pwa-strategy.md (+ index); F5 marked done.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ilia Denisov
2026-05-22 15:46:42 +02:00
parent c066a8958e
commit 04c7f6e68a
15 changed files with 396 additions and 2 deletions
+2
View File
@@ -31,6 +31,8 @@ lives in [`../PLAN.md`](../PLAN.md), the active web finalization in
bridge, with the live function surface and parity rules.
- [wasm-toolchain.md](wasm-toolchain.md) — building `ui/core` to
`core.wasm` with TinyGo.
- [pwa-strategy.md](pwa-strategy.md) — the installable/offline PWA: the
native service worker, manifest, icons, and the Playwright PWA gate.
- [testing.md](testing.md) — the UI test layers (Vitest + Playwright).
## Auth & lobby
+46
View File
@@ -0,0 +1,46 @@
# PWA strategy
The web client is an installable, offline-tolerant PWA. It uses
SvelteKit's native service worker (no Workbox) so there is no extra
build dependency and the cache logic stays explicit.
## Pieces
- [`src/service-worker.ts`](../frontend/src/service-worker.ts) — the
worker. SvelteKit registers it automatically in the production build.
It precaches the app shell (`/`), the build artefacts (JS/CSS +
`core.wasm`), and the static files under a **version-keyed** cache
(`galaxy-cache-<version>`, `version` from `$service-worker`). On
`activate` it deletes every other cache, so a new deploy never serves
stale code. Strategy: cache-first for the version-keyed build/files;
network-first with cache fallback for everything else; the cached
shell answers navigations when fully offline. The gateway (cross-
origin) is never intercepted — it is always live network.
- [`static/manifest.webmanifest`](../frontend/static/manifest.webmanifest)
— name, `standalone` display, `start_url`/`scope` `/`, dark
`theme_color`/`background_color`, and the icon set.
- [`static/icons/`](../frontend/static/icons/) — `192`/`512` (`any`),
a `512` `maskable`, and a `180` apple-touch icon. They are placeholder
artwork generated from `static/favicon.svg` by
[`scripts/gen-pwa-icons.mjs`](../frontend/scripts/gen-pwa-icons.mjs)
(a dependency-free pure-Node PNG encoder); swap in real artwork at the
same paths and the manifest is unchanged.
- [`src/app.html`](../frontend/src/app.html) — the manifest link, the
apple-touch-icon link, and light/dark `theme-color` metas matching the
design tokens.
## Testing
PWA behaviour is gated by Playwright against a **production preview**
build ([`playwright.pwa.config.ts`](../frontend/playwright.pwa.config.ts)
+ [`tests/pwa/pwa.spec.ts`](../frontend/tests/pwa/pwa.spec.ts), run by
`pnpm test:pwa` in CI): the manifest is linked with installable icons,
the service worker registers and controls the page under exactly one
version-keyed cache, and the app shell loads offline from that cache.
The spec needs a real build because `$service-worker`'s `build` list is
empty under `vite dev`.
Lighthouse is intentionally **not** used: its PWA category was removed
in Lighthouse 12 (the current line is 13.x), so "Lighthouse PWA ≥ 90" is
no longer a meaningful gate. The Playwright checks above verify the same
install/offline behaviour directly.