@joystyk/pwa 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# @joystyk/pwa
+
+## 0.2.0
+
+### Patch Changes
+
+- Updated dependencies [bb095c7]
+- Updated dependencies [bb095c7]
+  - @joystyk/contracts@0.2.0
+  - @joystyk/storage@0.2.0
+  - @joystyk/daily@0.2.0
+
+## 0.1.0
+
+### Minor Changes
+
+- Prepare the first compiled library release: ESM and API declarations for every public entry point, runtime assets, and checks against installed npm tarballs. Games and applications remain private.
+
+### Patch Changes
+
+- Updated dependencies
+  - @joystyk/contracts@0.1.0
+  - @joystyk/storage@0.1.0
+  - @joystyk/daily@0.1.0

package/README.md

@@ -1,5 +1,218 @@
 # @joystyk/pwa
 
-The first Joystyk library release is not yet available. This placeholder reserves the package name.
+The installable, offline-capable Joystyk (host policy). A service worker built from Workbox keeps
+the site's shell, recently played games and the games a player pins; the page offers updates
+only where nothing can be lost; a flag file can switch the whole thing off. The design is
+offline-and-updates.md (Joystyk host reference); the blog's worker
+(pwa-offline.md (Joystyk host reference)) is the model.
 
-Source: https://github.com/joystyk-games/game-libraries
+## npm package
+
+The first `0.1.0` release is being prepared; it has not been published. Once available:
+
+```sh
+npm install @joystyk/pwa
+```
+
+Node consumers require Node 24.15 or later. Browser entry points require a modern
+browser and should be loaded in the browser. The build entry uses Vite 8.3.3, declared
+as a peer dependency.
+
+| Import | Format |
+| --- | --- |
+| `@joystyk/pwa` | ES module and TypeScript declarations |
+| `@joystyk/pwa/client` | ES module and TypeScript declarations |
+| `@joystyk/pwa/build` | ES module and TypeScript declarations |
+
+Only the entries listed above are public API. Installed packages contain compiled ESM,
+type declarations and runtime assets. Repository-relative links describe the Joystyk
+workspace and are not needed to use the npm package.
+
+## Entry points
+
+| Import | Runs in | Contents |
+| --- | --- | --- |
+| `@joystyk/pwa` | Anywhere | Cache names, routing decisions, the asset-manifest, pin-record and flag-file formats |
+| `@joystyk/pwa/client` | Browser page | `registerPwa`, `pinGame`, `unpinGame`, `pinnedGames`, `refreshPinnedGames`, `<jy-offline-toggle>`, `<jy-update-toast>`, `<jy-security-update>` |
+| `@joystyk/pwa/build` | Node, at build time | `joystykPwa`, the Vite plugin that writes `sw.js` and the manifests |
+
+The worker's source is `src/sw/sw.ts`. It is never imported: the build bundles it into one
+classic `sw.js`. `tsconfig.sw.json` type-checks it with the worker's globals instead of the DOM.
+
+Workbox (`workbox-core`, `-precaching`, `-routing`, `-strategies`, `-expiration`, pinned to
+one exact version in `pnpm-workspace.yaml`) is the one non-Gyral runtime dependency here,
+as host policy and the blog notes allow. It runs only inside the worker.
+
+## Use
+
+The site's client build adds the plugin, and the browser entry registers the worker in
+production builds (`apps/site/vite.config.ts` and `src/entry-client.ts` do both):
+
+```ts
+// vite.config.ts
+import { joystykPwa } from '@joystyk/pwa/build';
+
+plugins: [joystykPwa({ release, releaseTime, site: ({ outDir }) => pwaBuildInput({ clientDir: outDir }) })];
+
+// entry-client.ts
+import { requestSave, watchSafePoints } from '@joystyk/launcher/browser';
+import { registerPwa } from '@joystyk/pwa/client';
+
+registerPwa({
+  release: __JOYSTYK_RELEASE__,
+  releaseTime: __JOYSTYK_RELEASE_TIME__,
+  watchSafePoints,
+  saveGame: requestSave,
+  daily: [/* daily content clients */],
+});
+```
+
+`site` gives the build the games it ships (id, versions, the folder holding the game's code,
+its asset-manifest path and page) and a `render(path)` that answers exactly as the production
+server will. `unlisted` names games whose code is bundled but not listed (the site's test
+games outside test builds); their code never enters the precache. The site serves the files
+the build writes (see below), all `no-cache` except the hashed ones.
+
+A game page renders `<jy-offline-toggle game-id="nim" game-name="Nim" assets="/games/nim/manifest.json">`;
+the catalog does this for every playable game and reserves its box, so nothing shifts when
+the control appears.
+
+Catalog cards and lineup rows include `<jy-offline-availability game-id="nim" hidden>`.
+The client reads completed pins, updates labels after pin changes and navigation, and
+marks unpinned game links unavailable while offline. Completed pins read “Available
+offline”; unpinned games read “Unavailable offline” when the network is down.
+For a cached offline page, the worker renders those labels from completed pin records
+before first paint, keeping catalog cards and table rows stable through hydration.
+
+## What the build writes
+
+After Vite writes the client build, the plugin reads `.vite/manifest.json` and adds:
+
+| File | Served | What it is |
+| --- | --- | --- |
+| `sw.js` | `/sw.js`, no-cache | The worker, one classic script, with the precache list and the release ID injected |
+| `games/<id>/manifest.json` | the game manifest's `assets`, no-cache | Every file the game's page needs to play: the shell's and the game's own, with sizes, kinds, the game's build, rules and save versions, and the release |
+| `manifest.webmanifest` | `/manifest.webmanifest`, no-cache | Name, colors and icons for installing Joystyk |
+| `offline.html` | `/offline`, no-cache | The offline page; its script lists the games this device can play offline |
+| `assets/icon-*.svg`, `assets/icon-*.png` | `/assets/…`, immutable | The joystick icon: SVG, 192 and 512 pixel PNGs and a maskable 512, drawn by the build (no image library) |
+| `assets/offline-*.js`, `assets/offline-*.css` | `/assets/…`, immutable | The offline page's script and styles (no inline code: the site's CSP) |
+| `pwa-control.json` | `/pwa-control.json`, no-cache | The default flag file: `{ "schemaVersion": 1, "serviceWorker": "enabled" }` |
+| `sw-remove.js` | `/sw.js` while the kill switch is on | The emergency worker: it removes itself and the PWA's caches |
+| `release.json` | Never | The release ID and release time; the site reads it to cap the minimum release it serves |
+
+**Which files a game needs.** The shell is everything the site's entry reaches, including
+the launcher's lazily loaded stage, storage and identity code, but no game: a dynamic import
+whose source lies in a game's folder starts that game. A game needs the shell plus everything
+its own dynamic entries reach. Static imports are always followed, even into another game's
+chunk, because the bundler may put shared code there.
+
+A file the bundler emits for a module (a worker named with `new Worker(new URL(…))`, a font)
+is an asset of the chunk holding that module, so it belongs to whoever reaches that chunk. The
+site therefore imports a game's job worker factory lazily (`apps/site/src/games.ts`): Greed's
+4 MB physics worker is then Greed's own file, not part of the shell that every visitor
+precaches and every pin copies. The build fails if the shell reaches any worker script.
+
+**The precache list** holds the shell's files, the icons, the offline page and its files, the
+web app manifest, and the server-rendered `/` and `/favicon.svg`. Hashed files carry no
+revision; the rest carry a hash of their rendered bytes, so a revision changes exactly when
+what is served changes. The build fails if any entry is missing, because one bad entry would
+fail the worker's install for every visitor.
+
+## The cache tiers
+
+| Tier | Cache | Holds | Eviction |
+| --- | --- | --- | --- |
+| 1 | `joystyk-shell-v1-<scope>` (Workbox) | The precache list | Replaced each release; Workbox removes outdated entries on activation |
+| 2 | `recent:code:v1`, `recent:art:v1`, `recent:audio:v1`, `recent:wasm:v1` | Hashed files of games played but not pinned | Capped per kind (`RECENT_LIMITS`), least recently used first, 30 days, `purgeOnQuotaError` |
+| 3 | `game:<id>:<version>` | A pinned game's whole build, its page and catalog data, and the pin's record | Never evicted by the worker; refreshed and replaced at safe points |
+
+How the worker answers (`routeFor` in `src/routing.ts`):
+
+- **Pages** go to the network first. If it fails (or takes over 8 seconds while a copy
+  exists), a pinned copy of the page, then the precached shell, then the offline page. A
+  page answered from a cache gets `data-offline` on its `<html>` tag (`src/offline-mark.ts`),
+  so its CSS reserves no ad space at first paint.
+  Worker-controlled HTML also removes `modulepreload` links before the browser parses
+  it, avoiding duplicate fetches across the page and worker. Initial network responses
+  keep the server's preload hints. Module scripts and CSP hashes remain intact.
+  The site disables Vite's runtime JavaScript preload hints to prevent lazy imports
+  from adding them back; stylesheet dependency loading stays enabled.
+- **Catalog data** (`/api/games…`) goes to the network first, then to a pinned copy.
+- **Hashed files** come from the precache, then the pins, then their kind's Tier 2 cache
+  (stale-while-revalidate; the revalidating request is answered by the browser's HTTP cache,
+  since the files are immutable). Each strategy's background work is handed to the fetch
+  event's `waitUntil`, the blog's fix that keeps the caps holding.
+- `/sw.js`, `/pwa-control.json`, `/healthz`, other origins and other methods are never cached.
+
+## Pinning
+
+`pinGame({ gameId, assets })` reads the asset manifest, fills `game:<id>:<version>` with every
+file, then the page and its data, then the pin's record. It checks that the page names no
+hashed file the manifest lacks (a deploy mid-pin), and tries once more if so. Only after the
+new build is complete does it drop stale files and older versions. The first pin asks for
+persistent storage (`@joystyk/storage/browser`). Errors come back as a `PinError` with a
+player-facing message: offline, out of space, or not available right now.
+
+A pin is self-sufficient: it holds the shell files its page names, so a pinned game still
+plays offline after a worker update replaced the precache. `refreshPinnedGames` brings every
+pin to the server's current build; `registerPwa` runs it at safe points while online.
+
+## Updates
+
+- The worker never activates itself. `registerPwa` watches the registration; when a new
+  worker is installed and waiting, it shows "Update ready" **only while the launcher reports a
+  safe point** (`joystyk:safe-point`, through `watchSafePoints`), and hides it when play
+  starts. Refresh posts `SKIP_WAITING`; the page reloads on `controllerchange`.
+- If another tab accepted the update, this page runs the old release under the new worker
+  (safe: hashed files outlive their release). It offers a reload at its next safe point and
+  never reloads by itself.
+- Checks: every 45 minutes, when the tab becomes visible, and on each navigation to the index.
+- **Forced security updates** (`forced.ts`). Given `releaseTime`, the page reads the flag
+  file at load, every 15 minutes, when the tab becomes visible and on each navigation to the
+  index. If its `minimumRelease` is later than this release, `<jy-security-update>` opens: a
+  modal dialog with the reason and one action, Update now, which Escape can't close.
+  `saveGame` (the launcher's `requestSave`) runs at once and pauses play; Update now waits for
+  the save, brings in the new worker when it can (a few seconds at most) and reloads. A failed
+  read changes nothing, so offline play goes on. The design is
+  Forced security updates (Joystyk host reference).
+- At safe points while online, at most every 30 minutes: refresh pins, then prefetch daily
+  puzzles (today and tomorrow, host policy) for every daily client in an installed app, or for the
+  pinned ones in a browser tab. The site passes no daily clients yet; no daily game exists.
+
+## The kill switch
+
+The site serves `/pwa-control.json` from `PWA_CONTROL_FILE` (default: the build's own file).
+Setting `"serviceWorker": "disabled"`:
+
+- a page reads it before registering, unregisters every worker and deletes the PWA's caches;
+- a worker reads it on install (and refuses to install), on activation, and on navigations
+  (at most every five minutes), then unregisters itself and deletes the PWA's caches.
+- the site serves `sw-remove.js` as `/sw.js`, so the browser's own update check replaces even
+  a worker too broken to read the flag with one that removes itself and its caches.
+
+IndexedDB (saves, stats, preferences) is never touched. A missing or unreadable flag file
+changes nothing, so a broken file can't wipe every player's offline games.
+
+The same file's optional `minimumRelease` forces older pages to update (see Updates above).
+The site serves a minimum later than its own release as its own release's time.
+
+## Tests
+
+- `src/*.test.ts` and `src/build/*.test.ts` (Node): routing decisions and cache names, the
+  offline mark on cached pages, the update-prompt rule, asset-manifest decoding and pin planning, the flag file (release-time
+  comparison, the minimum release and its cap) and pin records, the shell/game split over a Vite manifest, the asset manifest, precache list and
+  injection the build writes, the web app manifest, the offline page, and the PNG encoder and
+  icon drawing.
+- `src/client/*.browser.test.ts` (Chromium): pinning against real Cache Storage with a fake
+  server (first pin, refresh in place, a version switch, a page from a newer deploy, offline
+  and bad manifests, unpinning), the elements, and the forced update's order: the notice,
+  the save, then the reload, never before the save.
+- `apps/site/src/pwa.e2e.test.ts`: two real releases on the production server. With the
+  network off, the shell loads, a pinned Nim plays to the end and an unpinned game shows the
+  offline page; the index served offline reserves no ad space and shifts nothing, and its
+  slots return with the connection; a pinned Greed throws its dice in the physics worker, which only Greed's asset
+  manifest lists; the update waits through a game of Nim and appears at the results; a raised
+  minimum release blocks a game of Nim with the notice, saves it and reloads into release B,
+  which resumes it; an old tab
+  lazily loads its own release's chunks after a deploy; the kill switch unregisters the worker
+  and empties the caches.

package/dist/asset-manifest.d.ts

@@ -0,0 +1,76 @@
+import { type Result } from '@joystyk/contracts';
+import * as z from 'zod/mini';
+export declare const ASSET_MANIFEST_VERSION = 1;
+export declare const FILE_KINDS: readonly ["code", "art", "audio", "wasm", "font"];
+export type FileKind = (typeof FILE_KINDS)[number];
+export declare const AssetFileSchema: z.ZodMiniObject<{
+    url: z.ZodMiniString<string>;
+    size: z.ZodMiniInt;
+    kind: z.ZodMiniEnum<{
+        code: "code";
+        art: "art";
+        audio: "audio";
+        wasm: "wasm";
+        font: "font";
+    }>;
+    scope: z.ZodMiniEnum<{
+        shell: "shell";
+        game: "game";
+    }>;
+}, z.core.$strip>;
+export type AssetFile = z.infer<typeof AssetFileSchema>;
+export declare const GameAssetManifestSchema: z.ZodMiniObject<{
+    schemaVersion: z.ZodMiniLiteral<1>;
+    id: z.ZodMiniString<string>;
+    name: z.ZodMiniString<string>;
+    version: z.ZodMiniString<string>;
+    rulesVersion: z.ZodMiniInt;
+    saveVersion: z.ZodMiniInt;
+    release: z.ZodMiniString<string>;
+    page: z.ZodMiniString<string>;
+    documents: z.ZodMiniArray<z.ZodMiniString<string>>;
+    files: z.ZodMiniArray<z.ZodMiniObject<{
+        url: z.ZodMiniString<string>;
+        size: z.ZodMiniInt;
+        kind: z.ZodMiniEnum<{
+            code: "code";
+            art: "art";
+            audio: "audio";
+            wasm: "wasm";
+            font: "font";
+        }>;
+        scope: z.ZodMiniEnum<{
+            shell: "shell";
+            game: "game";
+        }>;
+    }, z.core.$strip>>;
+    totalBytes: z.ZodMiniInt;
+}, z.core.$strip>;
+export type GameAssetManifest = z.infer<typeof GameAssetManifestSchema>;
+/** Decodes an asset manifest, or lists what is wrong with it. */
+export declare const parseAssetManifest: (value: unknown) => Result<GameAssetManifest, readonly string[]>;
+/** What pinning a manifest into the caches must do. */
+export type PinPlan = {
+    /** The cache this build lives in: `game:<id>:<version>`. */
+    readonly target: string;
+    /** Hashed files the target cache lacks. */
+    readonly fetch: readonly string[];
+    /** Pages and data, fetched fresh every time, after the files. */
+    readonly documents: readonly string[];
+    /** Paths in the target cache the manifest no longer lists; deleted last. */
+    readonly remove: readonly string[];
+    /** The same game's caches for other builds; deleted after the switch. */
+    readonly dropCaches: readonly string[];
+};
+/**
+ * Plans a pin or a refresh. `existing` lists this game's pinned caches with the paths each
+ * holds. Hashed files never change, so one already cached is kept; pages always refresh.
+ */
+export declare const planPin: (manifest: GameAssetManifest, assetsUrl: string, target: string, existing: readonly {
+    readonly cacheName: string;
+    readonly paths: readonly string[];
+}[], recordPath: string) => PinPlan;
+/** The hashed files a page's HTML refers to (`src` and `href`), to check a pin is complete. */
+export declare const referencedAssets: (html: string) => string[];
+/** "312 KB", for the offline control. */
+export declare const formatBytes: (bytes: number) => string;

package/dist/asset-manifest.js

@@ -0,0 +1,80 @@
+import { RECENT_KINDS } from "./names.js";
+import { ASSETS_PREFIX } from "./routing.js";
+import { err, isGameId, ok } from "@joystyk/contracts";
+import * as z from "zod/mini";
+//#region src/asset-manifest.ts
+var ASSET_MANIFEST_VERSION = 1;
+var FILE_KINDS = [...RECENT_KINDS, "font"];
+var path = z.string().check(z.refine((value) => value.startsWith("/") && !value.startsWith("//"), "Expected a same-origin path such as /assets/x.js"));
+var assetPath = z.string().check(z.refine((value) => value.startsWith("/assets/") && !value.includes(".."), `Expected a path under ${ASSETS_PREFIX}`));
+var size = z.int().check(z.nonnegative());
+var AssetFileSchema = z.object({
+	url: assetPath,
+	size,
+	kind: z.enum(FILE_KINDS),
+	/** `shell`: the page and launcher code every game shares. `game`: this game's own code and assets. */
+	scope: z.enum(["shell", "game"])
+});
+var GameAssetManifestSchema = z.object({
+	schemaVersion: z.literal(1),
+	id: z.string().check(z.refine(isGameId, "Expected a kebab-case game id")),
+	name: z.string().check(z.minLength(1)),
+	/** The game build, semver (`manifest.versions.build`). Pinned caches are named by it. */
+	version: z.string().check(z.regex(/^[0-9A-Za-z.+-]+$/)),
+	rulesVersion: z.int(),
+	saveVersion: z.int(),
+	/** The platform release that built these files. */
+	release: z.string().check(z.minLength(1)),
+	/** The game's page. */
+	page: path,
+	/** Server-rendered pages and catalog data a pin keeps; always fetched fresh when pinning. */
+	documents: z.array(path),
+	files: z.array(AssetFileSchema),
+	/** The sum of `files[].size`. */
+	totalBytes: size
+});
+/** Decodes an asset manifest, or lists what is wrong with it. */
+var parseAssetManifest = (value) => {
+	const parsed = GameAssetManifestSchema.safeParse(value);
+	if (!parsed.success) return err(parsed.error.issues.map((issue) => `${issue.path.join(".") || "manifest"}: ${issue.message}`));
+	const total = parsed.data.files.reduce((sum, file) => sum + file.size, 0);
+	if (total !== parsed.data.totalBytes) return err([`totalBytes: ${String(parsed.data.totalBytes)} is not the sum of the file sizes (${String(total)})`]);
+	return ok(parsed.data);
+};
+/**
+* Plans a pin or a refresh. `existing` lists this game's pinned caches with the paths each
+* holds. Hashed files never change, so one already cached is kept; pages always refresh.
+*/
+var planPin = (manifest, assetsUrl, target, existing, recordPath) => {
+	const held = new Set(existing.find((cache) => cache.cacheName === target)?.paths ?? []);
+	const files = [...new Set(manifest.files.map((file) => file.url))];
+	const documents = [.../* @__PURE__ */ new Set([...manifest.documents, assetsUrl])];
+	const keep = /* @__PURE__ */ new Set([
+		...files,
+		...documents,
+		recordPath
+	]);
+	return {
+		target,
+		fetch: files.filter((url) => !held.has(url)),
+		documents,
+		remove: [...held].filter((url) => !keep.has(url)).sort(),
+		dropCaches: existing.map((cache) => cache.cacheName).filter((name) => name !== target)
+	};
+};
+/** The hashed files a page's HTML refers to (`src` and `href`), to check a pin is complete. */
+var referencedAssets = (html) => {
+	const found = /* @__PURE__ */ new Set();
+	for (const match of html.matchAll(/\s(?:src|href)=["']?(\/assets\/[^"'\s>]+)/g)) if (match[1] !== void 0) found.add(match[1]);
+	return [...found].sort();
+};
+/** "312 KB", for the offline control. */
+var formatBytes = (bytes) => {
+	if (bytes < 1024) return `${String(bytes)} bytes`;
+	if (bytes < 1048576) return `${String(Math.round(bytes / 1024))} KB`;
+	return `${(bytes / 1048576).toFixed(1)} MB`;
+};
+//#endregion
+export { ASSET_MANIFEST_VERSION, AssetFileSchema, FILE_KINDS, GameAssetManifestSchema, formatBytes, parseAssetManifest, planPin, referencedAssets };
+
+//# sourceMappingURL=asset-manifest.js.map

package/dist/asset-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-manifest.js","names":[],"sources":["../src/asset-manifest.ts"],"sourcesContent":["// A game's asset manifest, `games/<id>/manifest.json` (offline-and-updates.md, Rule 1): every\n// file the game's page needs to play, with sizes and the versions that built it. The build\n// writes it; pinning reads it from the network, so it is decoded through Standard Schema\n// before use (D-18). A game is either completely available offline or not offered.\nimport { err, isGameId, ok, type Result } from '@joystyk/contracts';\nimport * as z from 'zod/mini';\nimport { RECENT_KINDS } from './names.ts';\nimport { ASSETS_PREFIX } from './routing.ts';\n\nexport const ASSET_MANIFEST_VERSION = 1;\n\nexport const FILE_KINDS = [...RECENT_KINDS, 'font'] as const;\nexport type FileKind = (typeof FILE_KINDS)[number];\n\nconst path = z\n  .string()\n  .check(\n    z.refine(\n      (value) => value.startsWith('/') && !value.startsWith('//'),\n      'Expected a same-origin path such as /assets/x.js',\n    ),\n  );\nconst assetPath = z\n  .string()\n  .check(\n    z.refine(\n      (value) => value.startsWith(ASSETS_PREFIX) && !value.includes('..'),\n      `Expected a path under ${ASSETS_PREFIX}`,\n    ),\n  );\nconst size = z.int().check(z.nonnegative());\n\nexport const AssetFileSchema = z.object({\n  url: assetPath,\n  size,\n  kind: z.enum(FILE_KINDS),\n  /** `shell`: the page and launcher code every game shares. `game`: this game's own code and assets. */\n  scope: z.enum(['shell', 'game']),\n});\nexport type AssetFile = z.infer<typeof AssetFileSchema>;\n\nexport const GameAssetManifestSchema = z.object({\n  schemaVersion: z.literal(ASSET_MANIFEST_VERSION),\n  id: z.string().check(z.refine(isGameId, 'Expected a kebab-case game id')),\n  name: z.string().check(z.minLength(1)),\n  /** The game build, semver (`manifest.versions.build`). Pinned caches are named by it. */\n  version: z.string().check(z.regex(/^[0-9A-Za-z.+-]+$/)),\n  rulesVersion: z.int(),\n  saveVersion: z.int(),\n  /** The platform release that built these files. */\n  release: z.string().check(z.minLength(1)),\n  /** The game's page. */\n  page: path,\n  /** Server-rendered pages and catalog data a pin keeps; always fetched fresh when pinning. */\n  documents: z.array(path),\n  files: z.array(AssetFileSchema),\n  /** The sum of `files[].size`. */\n  totalBytes: size,\n});\nexport type GameAssetManifest = z.infer<typeof GameAssetManifestSchema>;\n\n/** Decodes an asset manifest, or lists what is wrong with it. */\nexport const parseAssetManifest = (value: unknown): Result<GameAssetManifest, readonly string[]> => {\n  const parsed = GameAssetManifestSchema.safeParse(value);\n  if (!parsed.success)\n    return err(parsed.error.issues.map((issue) => `${issue.path.join('.') || 'manifest'}: ${issue.message}`));\n  const total = parsed.data.files.reduce((sum, file) => sum + file.size, 0);\n  if (total !== parsed.data.totalBytes)\n    return err([`totalBytes: ${String(parsed.data.totalBytes)} is not the sum of the file sizes (${String(total)})`]);\n  return ok(parsed.data);\n};\n\n/** What pinning a manifest into the caches must do. */\nexport type PinPlan = {\n  /** The cache this build lives in: `game:<id>:<version>`. */\n  readonly target: string;\n  /** Hashed files the target cache lacks. */\n  readonly fetch: readonly string[];\n  /** Pages and data, fetched fresh every time, after the files. */\n  readonly documents: readonly string[];\n  /** Paths in the target cache the manifest no longer lists; deleted last. */\n  readonly remove: readonly string[];\n  /** The same game's caches for other builds; deleted after the switch. */\n  readonly dropCaches: readonly string[];\n};\n\n/**\n * Plans a pin or a refresh. `existing` lists this game's pinned caches with the paths each\n * holds. Hashed files never change, so one already cached is kept; pages always refresh.\n */\nexport const planPin = (\n  manifest: GameAssetManifest,\n  assetsUrl: string,\n  target: string,\n  existing: readonly { readonly cacheName: string; readonly paths: readonly string[] }[],\n  recordPath: string,\n): PinPlan => {\n  const held = new Set(existing.find((cache) => cache.cacheName === target)?.paths ?? []);\n  const files = [...new Set(manifest.files.map((file) => file.url))];\n  const documents = [...new Set([...manifest.documents, assetsUrl])];\n  const keep = new Set([...files, ...documents, recordPath]);\n  return {\n    target,\n    fetch: files.filter((url) => !held.has(url)),\n    documents,\n    remove: [...held].filter((url) => !keep.has(url)).sort(),\n    dropCaches: existing.map((cache) => cache.cacheName).filter((name) => name !== target),\n  };\n};\n\n/** The hashed files a page's HTML refers to (`src` and `href`), to check a pin is complete. */\nexport const referencedAssets = (html: string): string[] => {\n  const found = new Set<string>();\n  for (const match of html.matchAll(/\\s(?:src|href)=[\"']?(\\/assets\\/[^\"'\\s>]+)/g)) {\n    if (match[1] !== undefined) found.add(match[1]);\n  }\n  return [...found].sort();\n};\n\n/** \"312 KB\", for the offline control. */\nexport const formatBytes = (bytes: number): string => {\n  if (bytes < 1024) return `${String(bytes)} bytes`;\n  if (bytes < 1024 * 1024) return `${String(Math.round(bytes / 1024))} KB`;\n  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;\n};\n"],"mappings":"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"}

package/dist/build/documents.d.ts

@@ -0,0 +1,79 @@
+import { type GameAssetManifest } from '../asset-manifest.js';
+/** A short content hash for a file name or a precache revision (base64url, like Vite's). */
+export declare const contentHash: (content: string | Uint8Array, length?: number) => string;
+export type IconFiles = {
+    readonly svg: string;
+    readonly png192: string;
+    readonly png512: string;
+    readonly maskable512: string;
+};
+/** manifest.webmanifest: what an installed Joystyk looks like. */
+export declare const webManifest: (icons: IconFiles) => {
+    id: string;
+    name: string;
+    short_name: string;
+    description: string;
+    lang: string;
+    dir: string;
+    start_url: string;
+    scope: string;
+    display: string;
+    background_color: string;
+    theme_color: string;
+    categories: string[];
+    icons: {
+        src: string;
+        sizes: string;
+        type: string;
+        purpose: string;
+    }[];
+};
+/** The offline page. Static: its script fills in the list of games this device can play. */
+export declare const offlinePage: (files: {
+    readonly css: string;
+    readonly js: string;
+    readonly icon: string;
+}) => string;
+/** A game as the site describes it to the build. */
+export type BuildGame = {
+    readonly id: string;
+    readonly name: string;
+    /** `manifest.versions.build`. */
+    readonly version: string;
+    readonly rulesVersion: number;
+    readonly saveVersion: number;
+    /** The folder holding the game's code (its entry's folder). */
+    readonly root: string;
+    /** The game manifest's `assets`: where this asset manifest is served. */
+    readonly assets: string;
+    /** The game's page, e.g. /games/nim. */
+    readonly page: string;
+    /** Catalog data the page loads on client-side navigation, e.g. /api/games/nim. */
+    readonly data: readonly string[];
+};
+/** `games/<id>/manifest.json`: the game's files plus the shell's, sizes from `sizeOf`. */
+export declare const gameAssetManifest: (game: BuildGame, release: string, shell: ReadonlySet<string>, own: ReadonlySet<string>, sizeOf: (file: string) => number) => GameAssetManifest;
+/** One Workbox precache entry. `revision: null` for a URL whose name already holds a hash. */
+export type PrecacheEntry = {
+    readonly url: string;
+    readonly revision: string | null;
+};
+/** Where a precache entry's bytes come from at build time, so each can be checked. */
+export type PrecacheSource = {
+    readonly url: string;
+    readonly hashed: true;
+    readonly file: string;
+} | {
+    readonly url: string;
+    readonly hashed: false;
+    readonly body: Uint8Array | string;
+};
+/**
+ * The precache list. A hashed file must exist on disk (`exists`); an unhashed entry gets a
+ * revision from its rendered bytes. Throws listing every missing entry, because one bad entry
+ * fails the worker's install for every visitor.
+ */
+export declare const precacheEntries: (sources: readonly PrecacheSource[], exists: (file: string) => boolean) => PrecacheEntry[];
+export declare const INJECTION_POINT = "self.__WB_MANIFEST";
+/** Puts the precache list into the bundled worker, or throws when the injection point is gone. */
+export declare const injectManifest: (code: string, entries: readonly PrecacheEntry[]) => string;

package/dist/build/documents.js

@@ -0,0 +1,135 @@
+import { fileKind } from "../routing.js";
+import "../asset-manifest.js";
+import { BRAND_BACKGROUND } from "./icons.js";
+import { createHash } from "node:crypto";
+//#region src/build/documents.ts
+/** A short content hash for a file name or a precache revision (base64url, like Vite's). */
+var contentHash = (content, length = 8) => createHash("sha256").update(content).digest("base64url").replace(/[-_]/g, "x").slice(0, length);
+/** manifest.webmanifest: what an installed Joystyk looks like. */
+var webManifest = (icons) => ({
+	id: "/",
+	name: "Joystyk",
+	short_name: "Joystyk",
+	description: "Free games for your browser, for every age. Solo, against the computer, or pass the device to a friend.",
+	lang: "en",
+	dir: "ltr",
+	start_url: "/",
+	scope: "/",
+	display: "standalone",
+	background_color: BRAND_BACKGROUND,
+	theme_color: BRAND_BACKGROUND,
+	categories: ["games", "entertainment"],
+	icons: [
+		{
+			src: icons.svg,
+			sizes: "any",
+			type: "image/svg+xml",
+			purpose: "any"
+		},
+		{
+			src: icons.png192,
+			sizes: "192x192",
+			type: "image/png",
+			purpose: "any"
+		},
+		{
+			src: icons.png512,
+			sizes: "512x512",
+			type: "image/png",
+			purpose: "any"
+		},
+		{
+			src: icons.maskable512,
+			sizes: "512x512",
+			type: "image/png",
+			purpose: "maskable"
+		}
+	]
+});
+var escapeAttr = (value) => value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+/** The offline page. Static: its script fills in the list of games this device can play. */
+var offlinePage = (files) => `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>You're offline | Joystyk</title>
+<meta name="robots" content="noindex">
+<meta name="theme-color" content="${BRAND_BACKGROUND}">
+<link rel="icon" href="${escapeAttr(files.icon)}" type="image/svg+xml">
+<link rel="stylesheet" href="${escapeAttr(files.css)}">
+<script defer src="${escapeAttr(files.js)}"><\/script>
+</head>
+<body>
+<main>
+<p class="kicker">Joystyk</p>
+<h1>You're offline</h1>
+<p id="where" class="lede">This page needs an internet connection.</p>
+<section aria-labelledby="ready-heading">
+<h2 id="ready-heading">Games you can play offline</h2>
+<ul id="games" hidden></ul>
+<p id="none">No games are saved on this device yet. Next time you're online, open a game's page and choose “Make available offline”.</p>
+</section>
+<p class="actions"><button type="button" id="retry">Try again</button> <a href="/">See all games</a></p>
+</main>
+</body>
+</html>
+`;
+/** `games/<id>/manifest.json`: the game's files plus the shell's, sizes from `sizeOf`. */
+var gameAssetManifest = (game, release, shell, own, sizeOf) => {
+	const describe = (file, scope) => {
+		const url = `/${file}`;
+		const kind = fileKind(url) ?? "code";
+		return {
+			url,
+			size: sizeOf(file),
+			kind,
+			scope
+		};
+	};
+	const files = [...[...shell].sort().map((file) => describe(file, "shell")), ...[...own].sort().map((file) => describe(file, "game"))];
+	return {
+		schemaVersion: 1,
+		id: game.id,
+		name: game.name,
+		version: game.version,
+		rulesVersion: game.rulesVersion,
+		saveVersion: game.saveVersion,
+		release,
+		page: game.page,
+		documents: [game.page, ...game.data],
+		files,
+		totalBytes: files.reduce((sum, file) => sum + file.size, 0)
+	};
+};
+/**
+* The precache list. A hashed file must exist on disk (`exists`); an unhashed entry gets a
+* revision from its rendered bytes. Throws listing every missing entry, because one bad entry
+* fails the worker's install for every visitor.
+*/
+var precacheEntries = (sources, exists) => {
+	const missing = sources.filter((source) => source.hashed ? !exists(source.file) : source.body.length === 0);
+	if (missing.length > 0) throw new Error(`[pwa] Precache entries missing from the build: ${missing.map((s) => s.url).join(", ")}. Each one would fail the service worker install for every visitor; fix the build before deploying.`);
+	const seen = /* @__PURE__ */ new Set();
+	const entries = [];
+	for (const source of sources) {
+		if (seen.has(source.url)) continue;
+		seen.add(source.url);
+		entries.push({
+			url: source.url,
+			revision: source.hashed ? null : contentHash(source.body, 16)
+		});
+	}
+	return entries.sort((a, b) => a.url.localeCompare(b.url));
+};
+var INJECTION_POINT = "self.__WB_MANIFEST";
+/** Puts the precache list into the bundled worker, or throws when the injection point is gone. */
+var injectManifest = (code, entries) => {
+	const at = code.indexOf(INJECTION_POINT);
+	if (at === -1 || code.indexOf("self.__WB_MANIFEST", at + 1) !== -1) throw new Error(`[pwa] Expected "${INJECTION_POINT}" exactly once in the bundled service worker; sw.ts must call precache(${INJECTION_POINT}).`);
+	return code.replace(INJECTION_POINT, JSON.stringify(entries));
+};
+//#endregion
+export { INJECTION_POINT, contentHash, gameAssetManifest, injectManifest, offlinePage, precacheEntries, webManifest };
+
+//# sourceMappingURL=documents.js.map