@thunderclap-engine/host-pwa 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mandalorian007 / ThunderClap Gaming
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# @thunderclap-engine/host-pwa
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The installable web shell for a ThunderClap game: a vite plugin that turns a build into an
+installable, offline-capable app (manifest, icons, service worker), and a `Host` that surfaces the
+install prompt, the update prompt and the offline state through `host.pwa`. No dependencies, no
+workbox: the worker is written here. The engine itself stays network-free; the worker and the
+manifest are this package's and the game's.
+
+## Layout
+
+| Path | What it is |
+| --- | --- |
+| `src/index.ts` | Exports: `createPwaHost`, `inStandalone`, `pwaPlugin` and the types |
+| `src/host.ts` | `createPwaHost(opts)`: `createWebHost()` plus `host.pwa`; `inStandalone()` |
+| `src/vite.ts` | `pwaPlugin(opts)`: the build-only vite plugin (`@thunderclap-engine/host-pwa/vite`, so a vite config never loads the host) |
+| `src/manifest.ts` | The manifest, the icon file names, the tags injected into the page, the precache list and the version stamp |
+| `src/worker.ts` | The `sw.js` body with the per-build placeholders, and `workerSource(cfg)` that fills them |
+| `src/sw-logic.ts` | The worker's decisions as pure functions (`routeFor`, `trimPlan`, `staleCacheNames`, `isNewVersion`) |
+| `harness/` | A noun-free page built with the plugin, publishing `window.__pwa` |
+| `e2e/pwa.spec.ts` | The smoke on the built preview (Chromium, port 4551) |
+
+## Usage
+
+```ts
+// vite.config.ts
+import { pwaPlugin } from '@thunderclap-engine/host-pwa/vite';
+
+export default defineConfig({
+  plugins: [
+    pwaPlugin({
+      manifest: { name: 'Pairs', theme_color: '#0b0d14', background_color: '#0b0d14', svg: ICON_SVG },
+      runtimeCache: ['levels/', 'audio/'], // stale-while-revalidate, capped
+      maxRuntimeEntries: 60,
+    }),
+  ],
+});
+```
+
+```ts
+// main.ts
+import { createPwaHost } from '@thunderclap-engine/host-pwa';
+
+const host = createPwaHost(); // a web Host (kind 'web') with host.pwa
+const ctx = await createGame({ host, ... });
+
+host.pwa.onInstallable(() => showInstallButton(() => host.pwa.install())); // 'accepted' | 'dismissed' | 'unavailable'
+host.pwa.onUpdateReady(() => toast('Update ready', () => host.pwa.applyUpdate())); // skip-waiting, then reload
+host.pwa.onOffline((off) => hint(off ? 'Offline: playing from the cache' : ''));
+host.pwa.standalone; // launched from the home screen or the dock
+await host.pwa.cacheStatus(); // { precached, runtime, bytes }
+await host.pwa.clearCache(); // drops every tc-pwa-* cache; saves are untouched
+```
+
+`pwaPlugin` runs on `vite build` only; `vite dev` is unchanged. At `generateBundle` it reads the
+bundle's hashed file names, stamps the version (fnv1a of the sorted precache list, or
+`opts.version`), and emits `manifest.webmanifest`, `icon.svg`, `sw.js` and, when `OffscreenCanvas`
+exists in the build process, `icon-192.png` and `icon-512.png` (Node has none, so the package's own
+tests and harness take the SVG-only path; a game can list ready-made PNGs in `manifest.icons`
+instead). Its post `transformIndexHtml` hook then injects `<link rel="manifest">`,
+`<meta name="theme-color">` and a registration snippet that also sets `window.__tcPwa = { sw, version }`,
+which is how `createPwaHost()` finds the worker (`opts.swUrl` overrides it; `register: false` leaves
+registration to the page). `inStandalone()` reads the `display-mode` media query.
+
+`createPwaHost` is guarded: in a browser without `serviceWorker`, `caches` or
+`beforeinstallprompt`, `install()` resolves `'unavailable'`, `applyUpdate()` and `clearCache()` do
+nothing, `cacheStatus()` reports zeros, and the host is otherwise the plain web host.
+
+## Routing
+
+The worker (`sw.js`, scope = where the game is served) decides per `GET` on its own origin, in order:
+
+| Request | Route | Strategy |
+| --- | --- | --- |
+| A navigation, the scope root, or `index.html` | `index` | Network-first (`cache: 'no-cache'`); the cached copy on failure |
+| A path in the precache set (the build's hashed assets) | `precache` | Cache-first; a miss is fetched and stored |
+| A path starting with one of `runtimeCache` | `runtime` | Stale-while-revalidate into `tc-pwa-runtime`, the oldest dropped past `maxRuntimeEntries` |
+| Anything else (other origins, non-GET, unknown paths) | `network` | Untouched |
+
+Cache names: `tc-pwa-precache-<version>` and `tc-pwa-runtime`. On activate the worker deletes the
+precache caches of other versions and claims the open pages. Lookups ignore `Vary` (the caches
+are keyed by URL; a server answering `Vary: Origin` would otherwise make module scripts miss) and
+the query string on precached assets. A page posts `{ type: 'tc-pwa:skip-waiting' }` to make a
+waiting worker take over; `applyUpdate()` does that and reloads on `controllerchange`.
+
+### What is cached, and what never is
+
+- **Cached**: the bundle's emitted assets (hashed JS, CSS, images, fonts, anything vite emits,
+  minus `.map` files), `index.html`, and the `runtimeCache` prefixes a game opts into.
+- **Never cached**: the game's saves (they live in the host's `storage`, `localStorage` on the web;
+  `clearCache()` does not touch them), anything the game fetches outside the prefixes, other
+  origins, `POST`s, the worker and manifest themselves.
+
+An update is a new version stamp: the new worker installs its own precache beside the old one,
+reaches `installed`, and `host.pwa.updateReady` flips (`onUpdateReady` fires); nothing changes
+until `applyUpdate()` or the next full navigation. `index.html` is network-first, so an online
+load always gets the new page, which registers the new worker.
+
+## Commands
+
+From the repo root: `pnpm pwa:dev` (harness dev server on 5198), `pnpm pwa:build`,
+`pnpm check:host-pwa` (part of `pnpm check`). In this folder: `pnpm test` (Vitest: the routing,
+the plugin's hooks, the host with a fake worker container under happy-dom), `pnpm test:e2e`
+(builds the harness, serves it with `vite preview` on 4551 and runs `e2e/pwa.spec.ts`: manifest,
+activation, an offline reload, `offline` following the context, the precache count, the runtime
+cache filling and trimming).

package/dist/host.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `createPwaHost()`: the web host (`createWebHost`, `@thunderclap-engine/engine/host`) with a `pwa`
+ * facet: install prompt, update prompt, offline state, standalone detection and the caches the
+ * plugin's worker fills. `Host` itself gains nothing: `kind` stays `'web'` (the engine's type is
+ * not this package's), and `pwa.standalone` says the rest.
+ *
+ * Everything is guarded. In a tab without service workers, without `caches`, or on a build that
+ * never ran the plugin (no `window.__tcPwa`, no `swUrl`), the host boots and every method
+ * resolves `'unavailable'` or does nothing.
+ */
+import { type Host, type WebHostOptions } from '@thunderclap-engine/engine/host';
+export type InstallOutcome = 'accepted' | 'dismissed' | 'unavailable';
+export interface CacheStatus {
+    /** Entries in the build's precache (hashed assets and `index.html`). */
+    precached: number;
+    /** Entries in the runtime cache (the `runtimeCache` prefixes). */
+    runtime: number;
+    /** Bytes across both, summed from each cached body. */
+    bytes: number;
+}
+export interface PwaHost {
+    /** True once the browser offered an install prompt (`beforeinstallprompt`) that is still open. */
+    readonly installable: boolean;
+    /** Shows the deferred prompt. `unavailable` when there is none (already installed, or unsupported). */
+    install(): Promise<InstallOutcome>;
+    /** Calls `fn(installable)` on every change. Returns unsubscribe. */
+    onInstallable(fn: (installable: boolean) => void): () => void;
+    /** True when a new worker is installed and waiting behind the one that controls the page. */
+    readonly updateReady: boolean;
+    /**
+     * Tells the waiting worker to take over and reloads the page once it controls it. Resolves
+     * without reloading when no update is waiting.
+     */
+    applyUpdate(): Promise<void>;
+    /** Calls `fn()` when an update becomes ready. Returns unsubscribe. */
+    onUpdateReady(fn: () => void): () => void;
+    /** `!navigator.onLine`: kept current from the `online` and `offline` events. */
+    readonly offline: boolean;
+    /** Calls `fn(offline)` on every change. Returns unsubscribe. */
+    onOffline(fn: (offline: boolean) => void): () => void;
+    /** True when the page runs as an installed app (display-mode standalone, or iOS `navigator.standalone`). */
+    readonly standalone: boolean;
+    /** Counts and bytes of this package's caches. Zeros without `caches`. */
+    cacheStatus(): Promise<CacheStatus>;
+    /** Deletes this package's caches (never saves: those are `localStorage` / IndexedDB). */
+    clearCache(): Promise<void>;
+}
+export interface PwaHostOptions extends WebHostOptions {
+    /**
+     * The worker to register. Default: `window.__tcPwa.sw`, which the plugin's snippet sets in the
+     * built page. Without either the host registers nothing.
+     */
+    swUrl?: string;
+    /** Set false to leave registration to the page (the plugin's snippet already did it). Default true. */
+    register?: boolean;
+}
+/** True when the page runs as an installed app. */
+export declare function inStandalone(win?: Window): boolean;
+export declare function createPwaHost(opts?: PwaHostOptions): Host & {
+    pwa: PwaHost;
+};

package/dist/host.js

@@ -0,0 +1,188 @@
+/**
+ * `createPwaHost()`: the web host (`createWebHost`, `@thunderclap-engine/engine/host`) with a `pwa`
+ * facet: install prompt, update prompt, offline state, standalone detection and the caches the
+ * plugin's worker fills. `Host` itself gains nothing: `kind` stays `'web'` (the engine's type is
+ * not this package's), and `pwa.standalone` says the rest.
+ *
+ * Everything is guarded. In a tab without service workers, without `caches`, or on a build that
+ * never ran the plugin (no `window.__tcPwa`, no `swUrl`), the host boots and every method
+ * resolves `'unavailable'` or does nothing.
+ */
+import { createWebHost } from '@thunderclap-engine/engine/host';
+import { PAGE_GLOBAL } from './manifest.js';
+import { CACHE_PREFIX, PRECACHE_PREFIX, RUNTIME_CACHE } from './sw-logic.js';
+import { SKIP_WAITING } from './worker.js';
+/** True when the page runs as an installed app. */
+export function inStandalone(win = window) {
+    try {
+        if (win.matchMedia?.('(display-mode: standalone)').matches)
+            return true;
+        if (win.matchMedia?.('(display-mode: fullscreen)').matches)
+            return true;
+        return win.navigator.standalone === true;
+    }
+    catch {
+        return false;
+    }
+}
+function listeners() {
+    const set = new Set();
+    return {
+        add(fn) {
+            set.add(fn);
+            return () => {
+                set.delete(fn);
+            };
+        },
+        emit(v) {
+            for (const fn of set)
+                fn(v);
+        },
+    };
+}
+export function createPwaHost(opts = {}) {
+    const win = opts.win ?? window;
+    const base = createWebHost({ win });
+    const nav = win.navigator;
+    // Install prompt.
+    let deferred = null;
+    const installable = listeners();
+    win.addEventListener('beforeinstallprompt', (e) => {
+        e.preventDefault();
+        deferred = e;
+        installable.emit(true);
+    });
+    win.addEventListener('appinstalled', () => {
+        deferred = null;
+        installable.emit(false);
+    });
+    // Online state.
+    let offline = nav.onLine === false;
+    const offlineL = listeners();
+    const setOffline = (v) => {
+        if (v === offline)
+            return;
+        offline = v;
+        offlineL.emit(v);
+    };
+    win.addEventListener('online', () => setOffline(false));
+    win.addEventListener('offline', () => setOffline(true));
+    // Service worker: registration and the waiting worker.
+    const sw = 'serviceWorker' in nav ? nav.serviceWorker : null;
+    const page = win[PAGE_GLOBAL];
+    const swUrl = opts.swUrl ?? page?.sw;
+    let registration = null;
+    let updateReady = false;
+    const updateL = listeners();
+    const markReady = () => {
+        if (updateReady)
+            return;
+        updateReady = true;
+        updateL.emit();
+    };
+    const watchInstalling = (reg) => {
+        const w = reg.installing;
+        if (!w)
+            return;
+        w.addEventListener('statechange', () => {
+            // A worker that installed while another controls the page is an update waiting.
+            if (w.state === 'installed' && sw?.controller)
+                markReady();
+        });
+    };
+    const adopt = (reg) => {
+        registration = reg;
+        if (reg.waiting && sw?.controller)
+            markReady();
+        watchInstalling(reg);
+        reg.addEventListener('updatefound', () => watchInstalling(reg));
+    };
+    if (sw && swUrl) {
+        const ready = opts.register === false
+            ? sw.getRegistration(swUrl)
+            : sw.register(swUrl).then((r) => r, () => undefined);
+        ready.then((reg) => reg && adopt(reg)).catch(() => { });
+    }
+    const openCaches = async () => {
+        const store = win.caches;
+        if (!store)
+            return [];
+        try {
+            const names = (await store.keys()).filter((n) => n.startsWith(CACHE_PREFIX));
+            return Promise.all(names.map(async (name) => ({ name, cache: await store.open(name) })));
+        }
+        catch {
+            return [];
+        }
+    };
+    const pwa = {
+        get installable() {
+            return deferred !== null;
+        },
+        async install() {
+            const e = deferred;
+            if (!e)
+                return 'unavailable';
+            deferred = null;
+            installable.emit(false);
+            try {
+                await e.prompt();
+                const { outcome } = await e.userChoice;
+                return outcome;
+            }
+            catch {
+                return 'unavailable';
+            }
+        },
+        onInstallable: (fn) => installable.add(fn),
+        get updateReady() {
+            return updateReady;
+        },
+        async applyUpdate() {
+            const waiting = registration?.waiting;
+            if (!waiting || !sw)
+                return;
+            await new Promise((resolve) => {
+                const done = () => {
+                    sw.removeEventListener('controllerchange', done);
+                    resolve();
+                };
+                sw.addEventListener('controllerchange', done);
+                waiting.postMessage({ type: SKIP_WAITING });
+            });
+            win.location.reload();
+        },
+        onUpdateReady: (fn) => updateL.add(() => fn()),
+        get offline() {
+            return offline;
+        },
+        onOffline: (fn) => offlineL.add(fn),
+        get standalone() {
+            return inStandalone(win);
+        },
+        async cacheStatus() {
+            const status = { precached: 0, runtime: 0, bytes: 0 };
+            for (const { name, cache } of await openCaches()) {
+                const keys = await cache.keys();
+                if (name.startsWith(PRECACHE_PREFIX))
+                    status.precached += keys.length;
+                else if (name === RUNTIME_CACHE)
+                    status.runtime += keys.length;
+                for (const k of keys) {
+                    const res = await cache.match(k);
+                    if (res)
+                        status.bytes += (await res.arrayBuffer()).byteLength;
+                }
+            }
+            return status;
+        },
+        async clearCache() {
+            const store = win.caches;
+            if (!store)
+                return;
+            for (const { name } of await openCaches())
+                await store.delete(name);
+        },
+    };
+    return Object.assign(base, { pwa });
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@thunderclap-engine/host-pwa`: what a game imports. The page side (`createPwaHost`, `inStandalone`)
+ * and the build side (`pwaPlugin`, also at `@thunderclap-engine/host-pwa/vite`, which a `vite.config.ts`
+ * should prefer so Node never loads the host).
+ */
+export { type CacheStatus, createPwaHost, type InstallOutcome, inStandalone, type PwaHost, type PwaHostOptions, } from './host.js';
+export type { ManifestIcon, ManifestOptions, WebManifest } from './manifest.js';
+export type { Route, RouteRequest } from './sw-logic.js';
+export { type PwaPluginOptions, pwaPlugin } from './vite.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * `@thunderclap-engine/host-pwa`: what a game imports. The page side (`createPwaHost`, `inStandalone`)
+ * and the build side (`pwaPlugin`, also at `@thunderclap-engine/host-pwa/vite`, which a `vite.config.ts`
+ * should prefer so Node never loads the host).
+ */
+export { createPwaHost, inStandalone, } from './host.js';
+export { pwaPlugin } from './vite.js';

package/dist/manifest.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Build-time pieces of the plugin as pure functions: the web manifest, the `index.html`
+ * injection, the precache list from a bundle and the version stamp. vite.ts wires them into
+ * Vite's hooks; vite.test.ts exercises them on fakes.
+ */
+export interface ManifestIcon {
+    /** Path relative to the build root, e.g. `icons/icon-192.png`. */
+    src: string;
+    sizes: string;
+    type?: string;
+    purpose?: string;
+}
+export interface ManifestOptions {
+    name: string;
+    short_name?: string;
+    description?: string;
+    /** Default `#000000`. */
+    theme_color?: string;
+    /** Default `#000000`. */
+    background_color?: string;
+    /** Default `standalone`. */
+    display?: 'standalone' | 'fullscreen' | 'minimal-ui' | 'browser';
+    /** Default `landscape` (a game); `any` lets the page follow the device. */
+    orientation?: 'any' | 'landscape' | 'portrait' | 'natural';
+    /** Default `.` (the build root). */
+    start_url?: string;
+    /** Default `.`. */
+    scope?: string;
+    /** Default `games`. */
+    categories?: string[];
+    /**
+     * One SVG document. The plugin emits it as `icon.svg` (`sizes: any`) and, where
+     * `OffscreenCanvas` exists at build time, rasterises it to `icon-192.png` and `icon-512.png`.
+     * Node has no `OffscreenCanvas`, so under `vite build` the SVG goes alone unless `icons` names
+     * PNGs the game ships in `public/`.
+     */
+    svg?: string;
+    /** Icons the game provides itself (paths relative to the build root). */
+    icons?: ManifestIcon[];
+}
+export interface WebManifest {
+    name: string;
+    short_name: string;
+    description?: string;
+    start_url: string;
+    scope: string;
+    display: string;
+    orientation: string;
+    theme_color: string;
+    background_color: string;
+    categories: string[];
+    icons: ManifestIcon[];
+}
+/** Rasterised icons the plugin emits next to the manifest. */
+export declare const ICON_SIZES: readonly [192, 512];
+export declare const SVG_ICON_FILE = "icon.svg";
+export declare const pngIconFile: (size: number) => string;
+/**
+ * The manifest as written. `svg` adds the SVG icon (and the PNG names when `rasterised`); the
+ * game's own `icons` follow.
+ */
+export declare function buildManifest(opts: ManifestOptions, rasterised: boolean): WebManifest;
+/** What the page learns from the build: read by `createPwaHost` when it is given no `swUrl`. */
+export declare const PAGE_GLOBAL = "__tcPwa";
+/**
+ * The tags injected into `index.html`: the manifest link, a theme colour, and a snippet that
+ * publishes `window.__tcPwa = { sw, version }` and registers the worker, so a page that never
+ * calls `createPwaHost` still works offline. `base` is Vite's `base` (`/`, `./`, `/game/`).
+ */
+export declare function injectTags(html: string, base: string, cfg: HtmlInjection): string;
+export interface HtmlInjection {
+    manifestFile: string;
+    swFile: string;
+    version: string;
+    themeColor: string;
+}
+/** The subset of a Rollup/Rolldown output bundle the precache list reads. */
+export interface BundleLike {
+    [fileName: string]: {
+        type: 'chunk' | 'asset';
+        fileName: string;
+    };
+}
+/**
+ * Scope-relative paths to precache: every emitted chunk and asset except the worker and the
+ * manifest, plus `index.html`. Sorted so the list (and the version stamped from it) is stable.
+ */
+export declare function precacheList(bundle: BundleLike, exclude: Iterable<string>): string[];
+/** FNV-1a over a string, as 8 hex digits. */
+export declare function fnv1a(text: string): string;
+/**
+ * The build's version stamp: a hash of the precache list. Every chunk and asset carries a content
+ * hash in its name, so any changed code or asset changes the list and the stamp, while an
+ * identical rebuild keeps it (no spurious update). `index.html` is not in the stamp: it is served
+ * network-first and its cached copy is refreshed on every online load, so a page-only change
+ * needs no new worker.
+ */
+export declare function versionStamp(precache: string[]): string;

package/dist/manifest.js

@@ -0,0 +1,91 @@
+/**
+ * Build-time pieces of the plugin as pure functions: the web manifest, the `index.html`
+ * injection, the precache list from a bundle and the version stamp. vite.ts wires them into
+ * Vite's hooks; vite.test.ts exercises them on fakes.
+ */
+/** Rasterised icons the plugin emits next to the manifest. */
+export const ICON_SIZES = [192, 512];
+export const SVG_ICON_FILE = 'icon.svg';
+export const pngIconFile = (size) => `icon-${size}.png`;
+/**
+ * The manifest as written. `svg` adds the SVG icon (and the PNG names when `rasterised`); the
+ * game's own `icons` follow.
+ */
+export function buildManifest(opts, rasterised) {
+    const icons = [];
+    if (opts.svg) {
+        icons.push({ src: SVG_ICON_FILE, sizes: 'any', type: 'image/svg+xml', purpose: 'any' });
+        if (rasterised) {
+            for (const s of ICON_SIZES) {
+                icons.push({ src: pngIconFile(s), sizes: `${s}x${s}`, type: 'image/png', purpose: 'any' });
+            }
+        }
+    }
+    icons.push(...(opts.icons ?? []));
+    const m = {
+        name: opts.name,
+        short_name: opts.short_name ?? opts.name,
+        start_url: opts.start_url ?? '.',
+        scope: opts.scope ?? '.',
+        display: opts.display ?? 'standalone',
+        orientation: opts.orientation ?? 'landscape',
+        theme_color: opts.theme_color ?? '#000000',
+        background_color: opts.background_color ?? '#000000',
+        categories: opts.categories ?? ['games'],
+        icons,
+    };
+    if (opts.description)
+        m.description = opts.description;
+    return m;
+}
+/** What the page learns from the build: read by `createPwaHost` when it is given no `swUrl`. */
+export const PAGE_GLOBAL = '__tcPwa';
+/**
+ * The tags injected into `index.html`: the manifest link, a theme colour, and a snippet that
+ * publishes `window.__tcPwa = { sw, version }` and registers the worker, so a page that never
+ * calls `createPwaHost` still works offline. `base` is Vite's `base` (`/`, `./`, `/game/`).
+ */
+export function injectTags(html, base, cfg) {
+    const prefix = base.endsWith('/') ? base : `${base}/`;
+    const sw = JSON.stringify(`${prefix}${cfg.swFile}`);
+    const version = JSON.stringify(cfg.version);
+    const tags = [
+        `<link rel="manifest" href="${prefix}${cfg.manifestFile}" />`,
+        `<meta name="theme-color" content="${cfg.themeColor}" />`,
+        `<script>window.${PAGE_GLOBAL}={sw:${sw},version:${version}};if('serviceWorker' in navigator)navigator.serviceWorker.register(${sw}).catch(function(){});</script>`,
+    ].join('\n    ');
+    if (html.includes('</head>'))
+        return html.replace(/\s*<\/head>/, `\n    ${tags}\n  </head>`);
+    return `${tags}\n${html}`;
+}
+/**
+ * Scope-relative paths to precache: every emitted chunk and asset except the worker and the
+ * manifest, plus `index.html`. Sorted so the list (and the version stamped from it) is stable.
+ */
+export function precacheList(bundle, exclude) {
+    const skip = new Set(exclude);
+    const out = Object.values(bundle)
+        .map((o) => o.fileName)
+        .filter((f) => !skip.has(f) && !f.endsWith('.map') && !f.endsWith('.html'));
+    out.push('index.html');
+    return [...new Set(out)].sort();
+}
+/** FNV-1a over a string, as 8 hex digits. */
+export function fnv1a(text) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h.toString(16).padStart(8, '0');
+}
+/**
+ * The build's version stamp: a hash of the precache list. Every chunk and asset carries a content
+ * hash in its name, so any changed code or asset changes the list and the stamp, while an
+ * identical rebuild keeps it (no spurious update). `index.html` is not in the stamp: it is served
+ * network-first and its cached copy is refreshed on every online load, so a page-only change
+ * needs no new worker.
+ */
+export function versionStamp(precache) {
+    return fnv1a(precache.join('\n'));
+}

package/dist/sw-logic.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The service worker's decisions as pure functions. They run in two places: in Vitest, as
+ * ordinary imports, and inside the emitted `sw.js`, where worker.ts pastes their
+ * `Function.prototype.toString()` ahead of the worker body. That is why every function here is
+ * self-contained: no imports, no closures over module state, no TS-only syntax that leaves a
+ * runtime trace (enums, parameter properties). Types are erased and leave plain JavaScript.
+ */
+/** Cache names. The precache cache carries the build version; the runtime cache is shared. */
+export declare const CACHE_PREFIX = "tc-pwa-";
+export declare const PRECACHE_PREFIX = "tc-pwa-precache-";
+export declare const RUNTIME_CACHE = "tc-pwa-runtime";
+/** What the worker does with a fetch. */
+export type Route = 'precache' | 'index' | 'runtime' | 'network';
+/** The parts of a `Request` the routing reads, so a test can pass a plain object. */
+export interface RouteRequest {
+    url: string;
+    method: string;
+    /** `'navigate'` for a page load. */
+    mode?: string;
+}
+/**
+ * Which cache strategy a request takes.
+ *
+ * - `precache`: a GET for a path in the precache set (the build's hashed assets): cache-first.
+ * - `index`: a navigation, or a GET for the scope root or `index.html`: network-first with the
+ *   cached copy as the fallback.
+ * - `runtime`: a GET whose path starts with one of `runtimePrefixes`: stale-while-revalidate
+ *   into the runtime cache.
+ * - `network`: everything else (other origins, non-GET, unknown paths): straight through.
+ *
+ * `scope` is the worker's scope URL (`self.registration.scope`), so paths are matched relative
+ * to where the game is served, not to the origin root.
+ */
+export declare function routeFor(request: RouteRequest, precache: Set<string>, runtimePrefixes: string[], scope: string): Route;
+/**
+ * Which runtime-cache entries to evict so that at most `max` remain, oldest first. `keys` is the
+ * cache's key list in insertion order (what `cache.keys()` returns).
+ */
+export declare function trimPlan(keys: string[], max: number): string[];
+/**
+ * Which caches an activating worker of `version` deletes: every cache of this package whose
+ * name is a precache of another version. The runtime cache and caches of other software stay.
+ */
+export declare function staleCacheNames(names: string[], version: string): string[];
+/** True when `incoming` is a build other than `current`; empty stamps never count as new. */
+export declare function isNewVersion(current: string, incoming: string): boolean;

package/dist/sw-logic.js

@@ -0,0 +1,73 @@
+/**
+ * The service worker's decisions as pure functions. They run in two places: in Vitest, as
+ * ordinary imports, and inside the emitted `sw.js`, where worker.ts pastes their
+ * `Function.prototype.toString()` ahead of the worker body. That is why every function here is
+ * self-contained: no imports, no closures over module state, no TS-only syntax that leaves a
+ * runtime trace (enums, parameter properties). Types are erased and leave plain JavaScript.
+ */
+/** Cache names. The precache cache carries the build version; the runtime cache is shared. */
+export const CACHE_PREFIX = 'tc-pwa-';
+export const PRECACHE_PREFIX = 'tc-pwa-precache-';
+export const RUNTIME_CACHE = 'tc-pwa-runtime';
+/**
+ * Which cache strategy a request takes.
+ *
+ * - `precache`: a GET for a path in the precache set (the build's hashed assets): cache-first.
+ * - `index`: a navigation, or a GET for the scope root or `index.html`: network-first with the
+ *   cached copy as the fallback.
+ * - `runtime`: a GET whose path starts with one of `runtimePrefixes`: stale-while-revalidate
+ *   into the runtime cache.
+ * - `network`: everything else (other origins, non-GET, unknown paths): straight through.
+ *
+ * `scope` is the worker's scope URL (`self.registration.scope`), so paths are matched relative
+ * to where the game is served, not to the origin root.
+ */
+export function routeFor(request, precache, runtimePrefixes, scope) {
+    if (request.method !== 'GET')
+        return 'network';
+    let url;
+    let scopeUrl;
+    try {
+        url = new URL(request.url);
+        scopeUrl = new URL(scope);
+    }
+    catch {
+        return 'network';
+    }
+    if (url.origin !== scopeUrl.origin)
+        return 'network';
+    const scopePath = scopeUrl.pathname.endsWith('/') ? scopeUrl.pathname : `${scopeUrl.pathname}/`;
+    if (!url.pathname.startsWith(scopePath))
+        return 'network';
+    const rel = url.pathname.slice(scopePath.length);
+    if (request.mode === 'navigate' || rel === '' || rel === 'index.html')
+        return 'index';
+    if (precache.has(rel))
+        return 'precache';
+    for (const p of runtimePrefixes) {
+        if (rel.startsWith(p))
+            return 'runtime';
+    }
+    return 'network';
+}
+/**
+ * Which runtime-cache entries to evict so that at most `max` remain, oldest first. `keys` is the
+ * cache's key list in insertion order (what `cache.keys()` returns).
+ */
+export function trimPlan(keys, max) {
+    if (max < 0 || keys.length <= max)
+        return [];
+    return keys.slice(0, keys.length - max);
+}
+/**
+ * Which caches an activating worker of `version` deletes: every cache of this package whose
+ * name is a precache of another version. The runtime cache and caches of other software stay.
+ */
+export function staleCacheNames(names, version) {
+    const keep = `tc-pwa-precache-${version}`;
+    return names.filter((n) => n.startsWith('tc-pwa-precache-') && n !== keep);
+}
+/** True when `incoming` is a build other than `current`; empty stamps never count as new. */
+export function isNewVersion(current, incoming) {
+    return incoming !== '' && incoming !== current;
+}

package/dist/vite.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `pwaPlugin(opts)`: the Vite plugin that turns a game's build into an installable app. It
+ * imports nothing from the engine or the browser side of this package, so a `vite.config.ts` can
+ * load it from `@thunderclap-engine/host-pwa/vite` in Node without pulling the host in.
+ *
+ * Build only (`apply: 'build'`). Hooks, in the order Vite runs them:
+ *
+ * 1. `buildStart`: rasterises the SVG icon where the environment can (see `rasterise`).
+ * 2. `generateBundle`: reads the emitted chunks and assets into the precache list, stamps the
+ *    version from it, and emits `manifest.webmanifest`, the icon(s) and `sw.js` (worker.ts).
+ * 3. `transformIndexHtml` (post: Vite's own html plugin runs the post hooks in its
+ *    `generateBundle`, which comes after this plugin's): injects the manifest link, the theme
+ *    colour and the registration snippet with that version (manifest.ts `injectTags`).
+ *
+ * Imports carry `.ts` extensions because a `vite.config.ts` may load this file through Vite's
+ * native config loader, which requires them.
+ */
+import type { Plugin } from 'vite';
+import { type ManifestOptions } from './manifest.js';
+export interface PwaPluginOptions {
+    manifest: ManifestOptions;
+    /**
+     * Scope-relative path prefixes (`data/`, `levels/`) served stale-while-revalidate from the
+     * runtime cache: things the game fetches at play time that are not in the bundle. Default none.
+     */
+    runtimeCache?: string[];
+    /** Most entries the runtime cache keeps; the oldest are evicted first. Default 60. */
+    maxRuntimeEntries?: number;
+    /**
+     * The version stamp. Default: a hash of the precache list and the page, so an identical
+     * rebuild is not an update and any changed asset is.
+     */
+    version?: string;
+    /** Default `sw.js`. */
+    swFile?: string;
+    /** Default `manifest.webmanifest`. */
+    manifestFile?: string;
+}
+export declare function pwaPlugin(opts: PwaPluginOptions): Plugin;

package/dist/vite.js

@@ -0,0 +1,93 @@
+import { buildManifest, ICON_SIZES, injectTags, pngIconFile, precacheList, SVG_ICON_FILE, versionStamp, } from './manifest.js';
+import { workerSource } from './worker.js';
+/**
+ * Rasterises an SVG to PNG bytes at `size`, or returns null where the build environment has no
+ * `OffscreenCanvas` (Node). Guarded so the plugin never fails a build over an icon.
+ */
+async function rasterise(svg, size) {
+    const g = globalThis;
+    if (!g.OffscreenCanvas || !g.createImageBitmap)
+        return null;
+    try {
+        const bitmap = await g.createImageBitmap(new Blob([svg], { type: 'image/svg+xml' }));
+        const canvas = new g.OffscreenCanvas(size, size);
+        canvas.getContext('2d').drawImage(bitmap, 0, 0, size, size);
+        const blob = await canvas.convertToBlob({ type: 'image/png' });
+        return new Uint8Array(await blob.arrayBuffer());
+    }
+    catch {
+        return null;
+    }
+}
+export function pwaPlugin(opts) {
+    const swFile = opts.swFile ?? 'sw.js';
+    const manifestFile = opts.manifestFile ?? 'manifest.webmanifest';
+    const runtimePrefixes = opts.runtimeCache ?? [];
+    const maxRuntimeEntries = opts.maxRuntimeEntries ?? 60;
+    let base = '/';
+    let precache = [];
+    let version = opts.version ?? '';
+    let rasterised = false;
+    const svg = opts.manifest.svg;
+    let pngs = [];
+    const iconFiles = () => [
+        ...(svg ? [SVG_ICON_FILE] : []),
+        ...pngs.map((p) => pngIconFile(p.size)),
+    ];
+    return {
+        name: 'thunderclap:pwa',
+        apply: 'build',
+        configResolved(config) {
+            base = config.base;
+        },
+        async buildStart() {
+            pngs = [];
+            if (!svg)
+                return;
+            for (const size of ICON_SIZES) {
+                const bytes = await rasterise(svg, size);
+                if (bytes)
+                    pngs.push({ size, bytes });
+            }
+            rasterised = pngs.length === ICON_SIZES.length;
+            if (!rasterised)
+                pngs = [];
+        },
+        transformIndexHtml: {
+            order: 'post',
+            handler(html) {
+                return injectTags(html, base, {
+                    manifestFile,
+                    swFile,
+                    version,
+                    themeColor: opts.manifest.theme_color ?? '#000000',
+                });
+            },
+        },
+        generateBundle(_options, bundle) {
+            precache = precacheList(bundle, [
+                swFile,
+                manifestFile,
+                ...iconFiles(),
+            ]);
+            if (!opts.version)
+                version = versionStamp(precache);
+            const manifest = buildManifest(opts.manifest, rasterised);
+            this.emitFile({
+                type: 'asset',
+                fileName: manifestFile,
+                source: `${JSON.stringify(manifest, null, 2)}\n`,
+            });
+            if (svg)
+                this.emitFile({ type: 'asset', fileName: SVG_ICON_FILE, source: svg });
+            for (const p of pngs) {
+                this.emitFile({ type: 'asset', fileName: pngIconFile(p.size), source: p.bytes });
+            }
+            this.emitFile({
+                type: 'asset',
+                fileName: swFile,
+                source: workerSource({ version, precache, runtimePrefixes, maxRuntimeEntries }),
+            });
+        },
+    };
+}

package/dist/worker.d.ts

@@ -0,0 +1,14 @@
+export interface WorkerConfig {
+    /** The build's version stamp. */
+    version: string;
+    /** Scope-relative paths to precache (hashed assets, plus `index.html`). */
+    precache: string[];
+    /** Scope-relative path prefixes served stale-while-revalidate from the runtime cache. */
+    runtimePrefixes: string[];
+    /** Most entries the runtime cache keeps; the oldest go first. */
+    maxRuntimeEntries: number;
+}
+/** The message a page posts to make a waiting worker take over. */
+export declare const SKIP_WAITING = "tc-pwa:skip-waiting";
+/** The complete `sw.js` for one build. */
+export declare function workerSource(cfg: WorkerConfig): string;

package/dist/worker.js

@@ -0,0 +1,118 @@
+/**
+ * The service worker source. It is assembled, not compiled: the pure functions of sw-logic.ts are
+ * pasted in through `Function.prototype.toString()` (one source of truth, unit-tested as
+ * imports), followed by a body with four placeholders the plugin fills per build. The package
+ * ships TypeScript source through its exports map, like host-electron, so a worker kept as a
+ * separate TS file would need its own build step or a second copy of the routing; this needs
+ * neither. Every function pasted here must stay self-contained (see sw-logic.ts).
+ *
+ * Every cache lookup passes `ignoreVary`: the caches are keyed by URL, and a server that answers
+ * with `Vary: Origin` (vite preview, most CDNs) would otherwise make a module-script request
+ * (mode `cors`) miss the copy the worker stored from its own plain fetch.
+ */
+import { routeFor, staleCacheNames, trimPlan } from './sw-logic.js';
+/** The message a page posts to make a waiting worker take over. */
+export const SKIP_WAITING = 'tc-pwa:skip-waiting';
+const BODY = `
+const VERSION = __VERSION__;
+const PRECACHE = new Set(__PRECACHE__);
+const RUNTIME_PREFIXES = __RUNTIME_PREFIXES__;
+const MAX_RUNTIME = __MAX_RUNTIME__;
+const PRECACHE_NAME = 'tc-pwa-precache-' + VERSION;
+const RUNTIME_NAME = 'tc-pwa-runtime';
+const scope = self.registration.scope;
+
+self.addEventListener('install', (event) => {
+  event.waitUntil(
+    caches.open(PRECACHE_NAME).then((cache) =>
+      Promise.all(
+        [...PRECACHE].map((rel) =>
+          fetch(new Request(scope + rel, { cache: 'reload' })).then((res) => {
+            if (res.ok) return cache.put(scope + rel, res);
+          }),
+        ),
+      ),
+    ),
+  );
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(
+    caches
+      .keys()
+      .then((names) => Promise.all(staleCacheNames(names, VERSION).map((n) => caches.delete(n))))
+      .then(() => self.clients.claim()),
+  );
+});
+
+self.addEventListener('message', (event) => {
+  if (event.data && event.data.type === ${JSON.stringify(SKIP_WAITING)}) self.skipWaiting();
+});
+
+async function trimRuntime(cache) {
+  const keys = await cache.keys();
+  const drop = trimPlan(keys.map((k) => k.url), MAX_RUNTIME);
+  await Promise.all(drop.map((url) => cache.delete(url)));
+}
+
+async function fromPrecache(request) {
+  const cache = await caches.open(PRECACHE_NAME);
+  const hit = await cache.match(request, { ignoreSearch: true, ignoreVary: true });
+  if (hit) return hit;
+  const res = await fetch(request);
+  if (res.ok) cache.put(request, res.clone());
+  return res;
+}
+
+async function indexNetworkFirst() {
+  const key = scope + 'index.html';
+  const cache = await caches.open(PRECACHE_NAME);
+  try {
+    const res = await fetch(new Request(key, { cache: 'no-cache' }));
+    if (res.ok) {
+      cache.put(key, res.clone());
+      return res;
+    }
+    const hit = await cache.match(key, { ignoreVary: true });
+    return hit || res;
+  } catch (err) {
+    const hit = await cache.match(key, { ignoreVary: true });
+    if (hit) return hit;
+    throw err;
+  }
+}
+
+async function staleWhileRevalidate(request) {
+  const cache = await caches.open(RUNTIME_NAME);
+  const hit = await cache.match(request, { ignoreVary: true });
+  const refresh = fetch(request)
+    .then(async (res) => {
+      if (res.ok) {
+        await cache.put(request, res.clone());
+        await trimRuntime(cache);
+      }
+      return res;
+    })
+    .catch((err) => {
+      if (hit) return hit;
+      throw err;
+    });
+  return hit || refresh;
+}
+
+self.addEventListener('fetch', (event) => {
+  const route = routeFor(event.request, PRECACHE, RUNTIME_PREFIXES, scope);
+  if (route === 'precache') event.respondWith(fromPrecache(event.request));
+  else if (route === 'index') event.respondWith(indexNetworkFirst());
+  else if (route === 'runtime') event.respondWith(staleWhileRevalidate(event.request));
+});
+`;
+/** The complete `sw.js` for one build. */
+export function workerSource(cfg) {
+    const fns = [routeFor, trimPlan, staleCacheNames].map((f) => f.toString());
+    const body = BODY.replace('__VERSION__', JSON.stringify(cfg.version))
+        .replace('__PRECACHE__', JSON.stringify(cfg.precache))
+        .replace('__RUNTIME_PREFIXES__', JSON.stringify(cfg.runtimePrefixes))
+        .replace('__MAX_RUNTIME__', String(Math.max(0, Math.floor(cfg.maxRuntimeEntries))));
+    return `/* @thunderclap-engine/host-pwa service worker, build ${cfg.version} */\n'use strict';\n${fns.join('\n')}\n${body}`;
+}

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@thunderclap-engine/host-pwa",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "type": "module",
+  "description": "ThunderClap's installable web shell: a Vite plugin that emits a game's web manifest and service worker at build time, and createPwaHost(), the web Host plus install, update, offline and cache state. It knows nothing about any game and has no runtime dependencies.",
+  "license": "MIT",
+  "author": "ThunderClap",
+  "homepage": "https://github.com/Mandalorian007/thunderclap-engine/tree/main/packages/host-pwa#readme",
+  "bugs": {
+    "url": "https://github.com/Mandalorian007/thunderclap-engine/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mandalorian007/thunderclap-engine.git",
+    "directory": "packages/host-pwa"
+  },
+  "keywords": [
+    "thunderclap",
+    "pwa",
+    "service-worker",
+    "vite-plugin",
+    "webgpu",
+    "game-engine"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "@thunderclap-engine/engine": "^1.0.0",
+    "vite": ">=7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.4",
+    "@playwright/test": "^1.64.1",
+    "@types/node": "^26.6.6",
+    "@webgpu/types": "^0.1.74",
+    "happy-dom": "^21.0.4",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5",
+    "@thunderclap-engine/engine": "1.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.node.json",
+    "lint": "biome check .",
+    "test": "vitest run",
+    "check": "pnpm typecheck && pnpm lint && pnpm test",
+    "build": "vite build harness",
+    "dev": "vite harness --host 127.0.0.1 --port 5198",
+    "preview": "vite preview harness --host 127.0.0.1 --port 4551 --strictPort",
+    "test:e2e": "vite build harness && playwright test"
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js"
 }