@joystyk/pwa 0.0.0 → 0.2.0

package/dist/client/register.js

@@ -0,0 +1,255 @@
+import { MESSAGES, isPwaCache } from "../names.js";
+import { shouldOfferUpdate } from "../routing.js";
+import { isDisabled } from "../control.js";
+import { watchOfflineAvailability } from "./availability.js";
+import { readControl } from "./control.js";
+import { watchForcedUpdates } from "./forced.js";
+//#region src/client/register.ts
+var loadElements = async () => (await import("./elements.js")).definePwaElements();
+var DEFAULT_UPDATE_CHECK_MS = 27e5;
+/** Refresh pins and prefetch at most this often per page. */
+var IDLE_WORK_MS = 18e5;
+/** The daily games to prefetch: all of them in an installed app, otherwise the pinned ones. */
+var dailyToPrefetch = (prefetchers, context) => prefetchers.filter((p) => context.installed || context.pinned.includes(p.gameId));
+/** Unregisters every worker of this origin and deletes the PWA's caches. Saves are untouched. */
+var disablePwa = async () => {
+	for (const registration of await navigator.serviceWorker.getRegistrations()) await registration.unregister();
+	if (!("caches" in window)) return;
+	const names = (await caches.keys()).filter(isPwaCache);
+	await Promise.all(names.map((name) => caches.delete(name)));
+};
+/** The default prompt: `<jy-update-toast>` at the end of the body. */
+var toastPrompt = () => {
+	let toast = null;
+	let wanted = false;
+	return {
+		show: (choose) => {
+			wanted = true;
+			loadElements().then(() => {
+				if (!wanted) return;
+				toast ??= document.createElement("jy-update-toast");
+				toast.onChoice = choose;
+				if (!toast.isConnected) document.body.append(toast);
+			});
+		},
+		hide: () => {
+			wanted = false;
+			toast?.remove();
+		}
+	};
+};
+var isInstalled = () => matchMedia("(display-mode: standalone)").matches || navigator.standalone === true;
+/** Resolves with `promise`, or with undefined after `ms`. */
+var within = (promise, ms) => Promise.race([promise, new Promise((resolve) => setTimeout(() => resolve(void 0), ms))]);
+/** Resolves once `worker` reaches `state`, or is thrown away. */
+var reaches = (worker, state) => new Promise((resolve) => {
+	const done = () => worker.state === state || worker.state === "redundant";
+	if (done()) return resolve();
+	const listener = () => {
+		if (!done()) return;
+		worker.removeEventListener("statechange", listener);
+		resolve();
+	};
+	worker.addEventListener("statechange", listener);
+});
+/** Runs `work` once the page has loaded, so nothing competes with the page itself. */
+var afterLoad = (work) => {
+	if (document.readyState === "complete") work();
+	else addEventListener("load", work, { once: true });
+};
+var forcedUpdates = (options, prepare) => options.releaseTime === void 0 ? null : watchForcedUpdates({
+	releaseTime: options.releaseTime,
+	...options.saveGame === void 0 ? {} : { saveGame: options.saveGame },
+	...options.controlCheckMs === void 0 ? {} : { checkMs: options.controlCheckMs },
+	...options.securityNotice === void 0 ? {} : { notice: options.securityNotice },
+	...prepare === void 0 ? {} : { prepare }
+});
+/**
+* Registers /sw.js and runs the update flow. Call once per page, in production builds only.
+* A new worker installs and waits; the page shows "Update ready" only while the launcher
+* reports a safe point, then posts SKIP_WAITING and reloads once the new worker controls it.
+*/
+var registerPwa = (options) => {
+	if (!("serviceWorker" in navigator)) {
+		const forced = forcedUpdates(options);
+		if (forced !== null) afterLoad(() => void forced.check());
+		return {
+			release: options.release,
+			ready: Promise.resolve(null),
+			checkForUpdate: async () => void 0,
+			dispose: () => forced?.dispose()
+		};
+	}
+	const container = navigator.serviceWorker;
+	const prompt = options.prompt ?? toastPrompt();
+	const cleanups = [watchOfflineAvailability()];
+	let registration = null;
+	let waiting = null;
+	/** Another tab accepted an update: this page runs the old release under the new worker. */
+	let stale = false;
+	let safe = true;
+	let dismissed = false;
+	let accepted = false;
+	let lastIdleWork = -Infinity;
+	let idleWork = null;
+	/**
+	* Before a forced update's reload: install the new release's worker and hand it the page,
+	* within a few seconds. Best effort, since the reload fetches the new release's page from
+	* the network either way; a worker left waiting is offered at the next safe point.
+	*/
+	const activateNewWorker = async () => {
+		const reg = registration;
+		if (reg === null || container.controller === null) return;
+		await within(reg.update().catch(() => void 0), 5e3);
+		const installing = reg.installing;
+		if (installing !== null) await within(reaches(installing, "installed"), 1e4);
+		const next = reg.waiting;
+		if (next === null) return;
+		const handedOver = new Promise((resolve) => container.addEventListener("controllerchange", () => resolve(), { once: true }));
+		next.postMessage({ type: MESSAGES.skipWaiting });
+		await within(handedOver, 3e3);
+	};
+	const forced = forcedUpdates(options, activateNewWorker);
+	if (forced !== null) cleanups.push(() => forced.dispose());
+	const choose = (choice) => {
+		if (choice === "later") {
+			dismissed = true;
+			evaluate();
+			return;
+		}
+		accepted = true;
+		prompt.hide();
+		if (waiting !== null && !stale) waiting.postMessage({ type: MESSAGES.skipWaiting });
+		else location.reload();
+	};
+	const runIdleWork = () => {
+		if (idleWork !== null || !navigator.onLine || container.controller === null) return;
+		if (performance.now() - lastIdleWork < IDLE_WORK_MS) return;
+		lastIdleWork = performance.now();
+		idleWork = (async () => {
+			await (await import("./pins.js")).refreshPinnedGames();
+			const prefetchers = options.daily ?? [];
+			if (prefetchers.length === 0) return;
+			const pinned = (await (await import("./pinned.js")).pinnedGames()).map((record) => record.id);
+			const { today } = await import("@joystyk/daily/browser");
+			const date = today();
+			for (const client of dailyToPrefetch(prefetchers, {
+				installed: isInstalled(),
+				pinned
+			})) await client.prefetch(date);
+		})().catch(() => void 0).finally(() => {
+			idleWork = null;
+		});
+	};
+	function evaluate() {
+		if (forced?.forcing === true) {
+			prompt.hide();
+			return;
+		}
+		if (shouldOfferUpdate({
+			ready: waiting !== null || stale,
+			safe,
+			dismissed
+		})) prompt.show(choose);
+		else prompt.hide();
+		if (safe) runIdleWork();
+	}
+	const track = (reg) => {
+		if (reg.waiting !== null && container.controller !== null) waiting = reg.waiting;
+		reg.addEventListener("updatefound", () => {
+			const installing = reg.installing;
+			installing?.addEventListener("statechange", () => {
+				if (installing.state === "installed" && container.controller !== null) {
+					waiting = installing;
+					dismissed = false;
+					evaluate();
+				}
+			});
+		});
+		evaluate();
+	};
+	const checkForUpdate = async () => {
+		try {
+			await registration?.update();
+		} catch {}
+	};
+	const onControllerChange = () => {
+		if (forced?.forcing === true) return;
+		if (accepted) {
+			location.reload();
+			return;
+		}
+		if (container.controller === null) return;
+		stale = true;
+		dismissed = false;
+		evaluate();
+	};
+	container.addEventListener("controllerchange", onControllerChange);
+	cleanups.push(() => container.removeEventListener("controllerchange", onControllerChange));
+	const onMessage = (event) => {
+		if (event.data?.type === MESSAGES.disabled) {
+			waiting = null;
+			stale = false;
+			prompt.hide();
+		}
+	};
+	container.addEventListener("message", onMessage);
+	cleanups.push(() => container.removeEventListener("message", onMessage));
+	if (options.watchSafePoints !== void 0) cleanups.push(options.watchSafePoints((detail) => {
+		safe = detail.safe;
+		evaluate();
+	}));
+	const ready = new Promise((resolve) => {
+		const start = async () => {
+			if (isDisabled(forced === null ? await readControl() : await forced.check())) {
+				await disablePwa().catch(() => void 0);
+				resolve(null);
+				return;
+			}
+			try {
+				registration = await container.register("/sw.js", {
+					scope: "/",
+					updateViaCache: "none"
+				}) ?? null;
+			} catch {
+				registration = null;
+			}
+			if (registration !== null) track(registration);
+			resolve(registration);
+		};
+		afterLoad(() => {
+			loadElements();
+			start();
+		});
+	});
+	const interval = setInterval(() => void checkForUpdate(), options.updateCheckMs ?? DEFAULT_UPDATE_CHECK_MS);
+	cleanups.push(() => clearInterval(interval));
+	const onVisible = () => {
+		if (document.visibilityState === "visible") checkForUpdate();
+	};
+	document.addEventListener("visibilitychange", onVisible);
+	cleanups.push(() => document.removeEventListener("visibilitychange", onVisible));
+	const navigation = globalThis.navigation;
+	if (navigation !== void 0) {
+		const onNavigate = () => {
+			if (location.pathname !== "/") return;
+			checkForUpdate();
+			forced?.check();
+		};
+		navigation.addEventListener("navigatesuccess", onNavigate);
+		cleanups.push(() => navigation.removeEventListener("navigatesuccess", onNavigate));
+	}
+	return {
+		release: options.release,
+		ready,
+		checkForUpdate,
+		dispose: () => {
+			for (const cleanup of cleanups.splice(0)) cleanup();
+			prompt.hide();
+		}
+	};
+};
+//#endregion
+export { dailyToPrefetch, disablePwa, registerPwa, toastPrompt };
+
+//# sourceMappingURL=register.js.map

package/dist/client/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","names":[],"sources":["../../src/client/register.ts"],"sourcesContent":["// The page's side of the worker: register it, check for updates, offer an update only at a\n// safe point (Rule 2), force a security update when the flag file's minimum release says so\n// (Rule 2, ./forced.ts), honor the kill switch (Rule 5), and, while the page is idle at a safe\n// point and online, refresh pinned games and prefetch daily puzzles (offline-and-updates.md).\n// Registration waits for the page's `load` event, so it never competes with the page itself,\n// and the elements and the pinning code load after it, in a chunk of their own.\nimport { watchOfflineAvailability } from './availability.ts';\nimport { isDisabled } from '../control.ts';\nimport { isPwaCache, MESSAGES, SW_URL } from '../names.ts';\nimport { shouldOfferUpdate } from '../routing.ts';\nimport { readControl } from './control.ts';\nimport type { UpdateToast } from './elements.ts';\nimport { watchForcedUpdates, type ForcedUpdates, type SecurityNotice } from './forced.ts';\n\nconst loadElements = async (): Promise<void> => (await import('./elements.ts')).definePwaElements();\n\n/** A daily game's content client, as `@joystyk/daily/browser`'s `createDailyClient` makes it. */\nexport type DailyPrefetcher = {\n  readonly gameId: string;\n  prefetch(today: string): Promise<unknown>;\n};\n\n/** How the page shows \"Update ready\". The default is `<jy-update-toast>`. */\nexport interface UpdatePrompt {\n  show(choose: (choice: 'refresh' | 'later') => void): void;\n  hide(): void;\n}\n\nexport type PwaOptions = {\n  /** This build's release ID, for diagnostics. */\n  readonly release: string;\n  /**\n   * Subscribes to safe-point reports: pass the launcher's `watchSafePoints`\n   * (`@joystyk/launcher/browser`). Without it, every moment counts as safe.\n   */\n  readonly watchSafePoints?: (listener: (detail: { readonly safe: boolean }) => void) => () => void;\n  /** How often to look for a new worker. Default 45 minutes, as the blog does. */\n  readonly updateCheckMs?: number;\n  /**\n   * The daily games' content clients. At a safe point, an installed app prefetches every\n   * daily game, and a browser tab only the pinned ones (D-46: today and tomorrow, no further).\n   */\n  readonly daily?: readonly DailyPrefetcher[];\n  readonly prompt?: UpdatePrompt;\n  /**\n   * When this release's code was committed (`__JOYSTYK_RELEASE_TIME__`). With it, the page\n   * honors the flag file's minimum release and forces a security update when it is older.\n   */\n  readonly releaseTime?: string;\n  /** Saves the game in play before a forced update: pass the launcher's `requestSave`. */\n  readonly saveGame?: () => Promise<void>;\n  /** How often to read the flag file for a minimum release. Default 15 minutes. */\n  readonly controlCheckMs?: number;\n  readonly securityNotice?: SecurityNotice;\n};\n\nexport interface PwaController {\n  /** The release this page runs. */\n  readonly release: string;\n  /** The registration, or null without a worker (unsupported, failed, or switched off). */\n  readonly ready: Promise<ServiceWorkerRegistration | null>;\n  /** Looks for a new worker now. */\n  checkForUpdate(): Promise<void>;\n  dispose(): void;\n}\n\nconst DEFAULT_UPDATE_CHECK_MS = 45 * 60 * 1000;\n/** Refresh pins and prefetch at most this often per page. */\nconst IDLE_WORK_MS = 30 * 60 * 1000;\n\n/** The daily games to prefetch: all of them in an installed app, otherwise the pinned ones. */\nexport const dailyToPrefetch = (\n  prefetchers: readonly DailyPrefetcher[],\n  context: { readonly installed: boolean; readonly pinned: readonly string[] },\n): DailyPrefetcher[] => prefetchers.filter((p) => context.installed || context.pinned.includes(p.gameId));\n\n/** Unregisters every worker of this origin and deletes the PWA's caches. Saves are untouched. */\nexport const disablePwa = async (): Promise<void> => {\n  for (const registration of await navigator.serviceWorker.getRegistrations()) await registration.unregister();\n  if (!('caches' in window)) return;\n  const names = (await caches.keys()).filter(isPwaCache);\n  await Promise.all(names.map((name) => caches.delete(name)));\n};\n\n/** The default prompt: `<jy-update-toast>` at the end of the body. */\nexport const toastPrompt = (): UpdatePrompt => {\n  let toast: UpdateToast | null = null;\n  let wanted = false;\n  return {\n    show: (choose) => {\n      wanted = true;\n      void loadElements().then(() => {\n        if (!wanted) return;\n        toast ??= document.createElement('jy-update-toast');\n        toast.onChoice = choose;\n        if (!toast.isConnected) document.body.append(toast);\n      });\n    },\n    hide: () => {\n      wanted = false;\n      toast?.remove();\n    },\n  };\n};\n\nconst isInstalled = (): boolean =>\n  matchMedia('(display-mode: standalone)').matches ||\n  (navigator as Navigator & { standalone?: boolean }).standalone === true;\n\ntype NavigationLike = EventTarget;\n\n/** Resolves with `promise`, or with undefined after `ms`. */\nconst within = <T>(promise: Promise<T>, ms: number): Promise<T | undefined> =>\n  Promise.race([promise, new Promise<undefined>((resolve) => setTimeout(() => resolve(undefined), ms))]);\n\n/** Resolves once `worker` reaches `state`, or is thrown away. */\nconst reaches = (worker: ServiceWorker, state: ServiceWorkerState): Promise<void> =>\n  new Promise((resolve) => {\n    const done = (): boolean => worker.state === state || worker.state === 'redundant';\n    if (done()) return resolve();\n    const listener = (): void => {\n      if (!done()) return;\n      worker.removeEventListener('statechange', listener);\n      resolve();\n    };\n    worker.addEventListener('statechange', listener);\n  });\n\n/** Runs `work` once the page has loaded, so nothing competes with the page itself. */\nconst afterLoad = (work: () => void): void => {\n  if (document.readyState === 'complete') work();\n  else addEventListener('load', work, { once: true });\n};\n\nconst forcedUpdates = (options: PwaOptions, prepare?: () => Promise<void>): ForcedUpdates | null =>\n  options.releaseTime === undefined\n    ? null\n    : watchForcedUpdates({\n        releaseTime: options.releaseTime,\n        ...(options.saveGame === undefined ? {} : { saveGame: options.saveGame }),\n        ...(options.controlCheckMs === undefined ? {} : { checkMs: options.controlCheckMs }),\n        ...(options.securityNotice === undefined ? {} : { notice: options.securityNotice }),\n        ...(prepare === undefined ? {} : { prepare }),\n      });\n\n/**\n * Registers /sw.js and runs the update flow. Call once per page, in production builds only.\n * A new worker installs and waits; the page shows \"Update ready\" only while the launcher\n * reports a safe point, then posts SKIP_WAITING and reloads once the new worker controls it.\n */\nexport const registerPwa = (options: PwaOptions): PwaController => {\n  if (!('serviceWorker' in navigator)) {\n    // No worker, but a forced update still reaches the page.\n    const forced = forcedUpdates(options);\n    if (forced !== null) afterLoad(() => void forced.check());\n    return {\n      release: options.release,\n      ready: Promise.resolve(null),\n      checkForUpdate: async () => undefined,\n      dispose: () => forced?.dispose(),\n    };\n  }\n  const container = navigator.serviceWorker;\n  const prompt = options.prompt ?? toastPrompt();\n  const cleanups: (() => void)[] = [watchOfflineAvailability()];\n  let registration: ServiceWorkerRegistration | null = null;\n  let waiting: ServiceWorker | null = null;\n  /** Another tab accepted an update: this page runs the old release under the new worker. */\n  let stale = false;\n  let safe = true;\n  let dismissed = false;\n  let accepted = false;\n  let lastIdleWork = -Infinity;\n  let idleWork: Promise<void> | null = null;\n\n  /**\n   * Before a forced update's reload: install the new release's worker and hand it the page,\n   * within a few seconds. Best effort, since the reload fetches the new release's page from\n   * the network either way; a worker left waiting is offered at the next safe point.\n   */\n  const activateNewWorker = async (): Promise<void> => {\n    const reg = registration;\n    if (reg === null || container.controller === null) return;\n    await within(\n      reg.update().catch(() => undefined),\n      5_000,\n    );\n    const installing = reg.installing;\n    if (installing !== null) await within(reaches(installing, 'installed'), 10_000);\n    const next = reg.waiting;\n    if (next === null) return;\n    const handedOver = new Promise<void>((resolve) =>\n      container.addEventListener('controllerchange', () => resolve(), { once: true }),\n    );\n    next.postMessage({ type: MESSAGES.skipWaiting });\n    await within(handedOver, 3_000);\n  };\n  const forced = forcedUpdates(options, activateNewWorker);\n  if (forced !== null) cleanups.push(() => forced.dispose());\n\n  const choose = (choice: 'refresh' | 'later'): void => {\n    if (choice === 'later') {\n      dismissed = true;\n      evaluate();\n      return;\n    }\n    accepted = true;\n    prompt.hide();\n    // The reload happens on controllerchange, once the new worker is in charge; reloading\n    // now would race the handoff. A stale page has nothing to wait for.\n    if (waiting !== null && !stale) waiting.postMessage({ type: MESSAGES.skipWaiting });\n    else location.reload();\n  };\n\n  const runIdleWork = (): void => {\n    if (idleWork !== null || !navigator.onLine || container.controller === null) return;\n    if (performance.now() - lastIdleWork < IDLE_WORK_MS) return;\n    lastIdleWork = performance.now();\n    idleWork = (async () => {\n      await (await import('./pins.ts')).refreshPinnedGames();\n      const prefetchers = options.daily ?? [];\n      if (prefetchers.length === 0) return;\n      const pinned = (await (await import('./pinned.ts')).pinnedGames()).map((record) => record.id);\n      const { today } = await import('@joystyk/daily/browser');\n      const date = today();\n      for (const client of dailyToPrefetch(prefetchers, { installed: isInstalled(), pinned }))\n        await client.prefetch(date);\n    })()\n      .catch(() => undefined)\n      .finally(() => {\n        idleWork = null;\n      });\n  };\n\n  function evaluate(): void {\n    // A forced update's notice is up: no toast beside it, and no work behind it.\n    if (forced?.forcing === true) {\n      prompt.hide();\n      return;\n    }\n    if (shouldOfferUpdate({ ready: waiting !== null || stale, safe, dismissed })) prompt.show(choose);\n    else prompt.hide();\n    if (safe) runIdleWork();\n  }\n\n  const track = (reg: ServiceWorkerRegistration): void => {\n    // A worker may already be waiting from an earlier visit; `updatefound` won't fire for it.\n    if (reg.waiting !== null && container.controller !== null) waiting = reg.waiting;\n    reg.addEventListener('updatefound', () => {\n      const installing = reg.installing;\n      installing?.addEventListener('statechange', () => {\n        // The very first install has nothing to update from: no controller yet.\n        if (installing.state === 'installed' && container.controller !== null) {\n          waiting = installing;\n          dismissed = false;\n          evaluate();\n        }\n      });\n    });\n    evaluate();\n  };\n\n  const checkForUpdate = async (): Promise<void> => {\n    try {\n      await registration?.update();\n    } catch {\n      // Offline, or the server is down: try again at the next check.\n    }\n  };\n\n  const onControllerChange = (): void => {\n    // A forced update reloads by itself once the new worker is in charge.\n    if (forced?.forcing === true) return;\n    if (accepted) {\n      location.reload();\n      return;\n    }\n    if (container.controller === null) return;\n    stale = true;\n    dismissed = false;\n    evaluate();\n  };\n  container.addEventListener('controllerchange', onControllerChange);\n  cleanups.push(() => container.removeEventListener('controllerchange', onControllerChange));\n\n  const onMessage = (event: MessageEvent): void => {\n    if ((event.data as { type?: unknown } | null)?.type === MESSAGES.disabled) {\n      waiting = null;\n      stale = false;\n      prompt.hide();\n    }\n  };\n  container.addEventListener('message', onMessage);\n  cleanups.push(() => container.removeEventListener('message', onMessage));\n\n  if (options.watchSafePoints !== undefined) {\n    cleanups.push(\n      options.watchSafePoints((detail) => {\n        safe = detail.safe;\n        evaluate();\n      }),\n    );\n  }\n\n  const ready = new Promise<ServiceWorkerRegistration | null>((resolve) => {\n    const start = async (): Promise<void> => {\n      if (isDisabled(forced === null ? await readControl() : await forced.check())) {\n        await disablePwa().catch(() => undefined);\n        resolve(null);\n        return;\n      }\n      try {\n        // Some environments (automation that blocks workers) resolve without a registration.\n        registration =\n          ((await container.register(SW_URL, { scope: '/', updateViaCache: 'none' })) as\n            ServiceWorkerRegistration | undefined) ?? null;\n      } catch {\n        registration = null;\n      }\n      // Without one the site still works fully, only without offline play or update prompts.\n      if (registration !== null) track(registration);\n      resolve(registration);\n    };\n    afterLoad(() => {\n      void loadElements();\n      void start();\n    });\n  });\n\n  // Periodic checks, a check when the tab comes back, and one on each navigation to the index.\n  const interval = setInterval(() => void checkForUpdate(), options.updateCheckMs ?? DEFAULT_UPDATE_CHECK_MS);\n  cleanups.push(() => clearInterval(interval));\n  const onVisible = (): void => {\n    if (document.visibilityState === 'visible') void checkForUpdate();\n  };\n  document.addEventListener('visibilitychange', onVisible);\n  cleanups.push(() => document.removeEventListener('visibilitychange', onVisible));\n  const navigation = (globalThis as { navigation?: NavigationLike }).navigation;\n  if (navigation !== undefined) {\n    const onNavigate = (): void => {\n      if (location.pathname !== '/') return;\n      void checkForUpdate();\n      void forced?.check();\n    };\n    navigation.addEventListener('navigatesuccess', onNavigate);\n    cleanups.push(() => navigation.removeEventListener('navigatesuccess', onNavigate));\n  }\n\n  return {\n    release: options.release,\n    ready,\n    checkForUpdate,\n    dispose: () => {\n      for (const cleanup of cleanups.splice(0)) cleanup();\n      prompt.hide();\n    },\n  };\n};\n"],"mappings":"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"}

package/dist/control.d.ts

@@ -0,0 +1,46 @@
+export type Control = {
+    readonly schemaVersion: 1;
+    readonly serviceWorker: 'enabled' | 'disabled';
+    /**
+     * The release time of the oldest release that may keep running, as an RFC 3339 date-time
+     * such as "2026-10-09T14:03:12Z". An open page from an older release must update.
+     */
+    readonly minimumRelease?: string;
+};
+/** A release time in milliseconds since the epoch, or null when it isn't a valid date-time. */
+export declare const releaseTimeMs: (value: unknown) => number | null;
+/** A release time in its canonical form: UTC, whole seconds, e.g. "2026-10-09T14:03:12Z". */
+export declare const canonicalReleaseTime: (value: string) => string | null;
+export declare const ControlSchema: import("@joystyk/contracts").Validator<Control>;
+export declare const DEFAULT_CONTROL: Control;
+/**
+ * What the flag file says. Anything unreadable, a network failure included, reads as "no
+ * instruction": a broken flag file must not wipe every player's offline games, and a page
+ * that can't reach the server keeps playing.
+ */
+export declare const parseControl: (value: unknown) => Control | null;
+export declare const isDisabled: (control: Control | null) => boolean;
+/**
+ * True when a page running the release built at `releaseTime` must update now: the flag
+ * file names a minimum release, and this one is older. An unreadable time on either side
+ * never forces anything.
+ */
+export declare const mustUpdate: (control: Control | null, releaseTime: string) => boolean;
+/**
+ * The flag file as the server running `releaseTime` serves it: a minimum later than that
+ * release comes down to it. Raising the minimum past what the site serves would otherwise
+ * send every page into a reload that can never reach a new enough release.
+ */
+export declare const capMinimumRelease: (control: Control, releaseTime: string) => Control;
+/**
+ * The build's record of its release, written beside `sw.js` as `release.json` and never
+ * served: the site reads it to cap the minimum release it serves.
+ */
+export type ReleaseRecord = {
+    readonly release: string;
+    /** Canonical: UTC, whole seconds. */
+    readonly releaseTime: string;
+};
+export declare const RELEASE_RECORD_FILE = "release.json";
+export declare const ReleaseRecordSchema: import("@joystyk/contracts").Validator<ReleaseRecord>;
+export declare const parseReleaseRecord: (value: unknown) => ReleaseRecord | null;

package/dist/control.js

@@ -0,0 +1,88 @@
+import { decodeSync, isRecord, validator } from "./validate.js";
+//#region src/control.ts
+/** An RFC 3339 date-time with seconds and a zone: what `git show -s --format=%cI` prints, or UTC. */
+var RELEASE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+/** A release time in milliseconds since the epoch, or null when it isn't a valid date-time. */
+var releaseTimeMs = (value) => {
+	if (typeof value !== "string" || !RELEASE_TIME.test(value)) return null;
+	const ms = Date.parse(value);
+	return Number.isNaN(ms) ? null : ms;
+};
+/** A release time in its canonical form: UTC, whole seconds, e.g. "2026-10-09T14:03:12Z". */
+var canonicalReleaseTime = (value) => {
+	const ms = releaseTimeMs(value);
+	return ms === null ? null : `${(/* @__PURE__ */ new Date(Math.floor(ms / 1e3) * 1e3)).toISOString().slice(0, 19)}Z`;
+};
+var ControlSchema = validator((value, issues) => {
+	if (!isRecord(value)) {
+		issues.push("Expected an object");
+		return;
+	}
+	const { schemaVersion, serviceWorker, minimumRelease } = value;
+	if (schemaVersion !== 1) issues.push("schemaVersion: expected 1");
+	if (serviceWorker !== "enabled" && serviceWorker !== "disabled") issues.push("serviceWorker: expected \"enabled\" or \"disabled\"");
+	if (minimumRelease !== void 0 && releaseTimeMs(minimumRelease) === null) issues.push("minimumRelease: expected a date-time such as \"2026-10-09T14:03:12Z\"");
+	if (issues.length > 0) return void 0;
+	const control = {
+		schemaVersion: 1,
+		serviceWorker
+	};
+	return minimumRelease === void 0 ? control : {
+		...control,
+		minimumRelease
+	};
+});
+var DEFAULT_CONTROL = {
+	schemaVersion: 1,
+	serviceWorker: "enabled"
+};
+/**
+* What the flag file says. Anything unreadable, a network failure included, reads as "no
+* instruction": a broken flag file must not wipe every player's offline games, and a page
+* that can't reach the server keeps playing.
+*/
+var parseControl = (value) => decodeSync(ControlSchema, value);
+var isDisabled = (control) => control?.serviceWorker === "disabled";
+/**
+* True when a page running the release built at `releaseTime` must update now: the flag
+* file names a minimum release, and this one is older. An unreadable time on either side
+* never forces anything.
+*/
+var mustUpdate = (control, releaseTime) => {
+	const minimum = releaseTimeMs(control?.minimumRelease);
+	const own = releaseTimeMs(releaseTime);
+	return minimum !== null && own !== null && own < minimum;
+};
+/**
+* The flag file as the server running `releaseTime` serves it: a minimum later than that
+* release comes down to it. Raising the minimum past what the site serves would otherwise
+* send every page into a reload that can never reach a new enough release.
+*/
+var capMinimumRelease = (control, releaseTime) => {
+	const minimum = releaseTimeMs(control.minimumRelease);
+	const own = releaseTimeMs(releaseTime);
+	if (minimum === null || own === null || minimum <= own) return control;
+	return {
+		...control,
+		minimumRelease: releaseTime
+	};
+};
+var RELEASE_RECORD_FILE = "release.json";
+var ReleaseRecordSchema = validator((value, issues) => {
+	if (!isRecord(value)) {
+		issues.push("Expected an object");
+		return;
+	}
+	const { release, releaseTime } = value;
+	if (typeof release !== "string" || release === "") issues.push("release: expected text");
+	if (releaseTimeMs(releaseTime) === null) issues.push("releaseTime: expected a date-time");
+	return issues.length === 0 ? {
+		release,
+		releaseTime
+	} : void 0;
+});
+var parseReleaseRecord = (value) => decodeSync(ReleaseRecordSchema, value);
+//#endregion
+export { ControlSchema, DEFAULT_CONTROL, RELEASE_RECORD_FILE, ReleaseRecordSchema, canonicalReleaseTime, capMinimumRelease, isDisabled, mustUpdate, parseControl, parseReleaseRecord, releaseTimeMs };
+
+//# sourceMappingURL=control.js.map

package/dist/control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.js","names":[],"sources":["../src/control.ts"],"sourcesContent":["// The flag file (offline-and-updates.md, Rules 2 and 5): a small `no-cache` JSON file the site\n// serves at /pwa-control.json, which operators change without a deploy. It carries two flags.\n//\n// - The kill switch. When it says the worker is disabled, pages stop registering it, and\n//   every installed worker unregisters itself and deletes the PWA's caches. Saves and other\n//   IndexedDB data are never touched.\n// - The minimum release, for forced security updates. A page whose release is older shows a\n//   blocking notice, saves the game and reloads into the current release.\n//\n// Releases are ordered by their release time: the UTC time of the commit a release is built\n// from (apps/site/vite.config.ts). Release IDs are commit hashes, which have no order.\nimport { decodeSync, isRecord, validator } from './validate.ts';\n\nexport type Control = {\n  readonly schemaVersion: 1;\n  readonly serviceWorker: 'enabled' | 'disabled';\n  /**\n   * The release time of the oldest release that may keep running, as an RFC 3339 date-time\n   * such as \"2026-10-09T14:03:12Z\". An open page from an older release must update.\n   */\n  readonly minimumRelease?: string;\n};\n\n/** An RFC 3339 date-time with seconds and a zone: what `git show -s --format=%cI` prints, or UTC. */\nconst RELEASE_TIME = /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?(?:Z|[+-]\\d{2}:\\d{2})$/;\n\n/** A release time in milliseconds since the epoch, or null when it isn't a valid date-time. */\nexport const releaseTimeMs = (value: unknown): number | null => {\n  if (typeof value !== 'string' || !RELEASE_TIME.test(value)) return null;\n  const ms = Date.parse(value);\n  return Number.isNaN(ms) ? null : ms;\n};\n\n/** A release time in its canonical form: UTC, whole seconds, e.g. \"2026-10-09T14:03:12Z\". */\nexport const canonicalReleaseTime = (value: string): string | null => {\n  const ms = releaseTimeMs(value);\n  return ms === null ? null : `${new Date(Math.floor(ms / 1000) * 1000).toISOString().slice(0, 19)}Z`;\n};\n\nexport const ControlSchema = validator<Control>((value, issues) => {\n  if (!isRecord(value)) {\n    issues.push('Expected an object');\n    return undefined;\n  }\n  const { schemaVersion, serviceWorker, minimumRelease } = value;\n  if (schemaVersion !== 1) issues.push('schemaVersion: expected 1');\n  if (serviceWorker !== 'enabled' && serviceWorker !== 'disabled')\n    issues.push('serviceWorker: expected \"enabled\" or \"disabled\"');\n  if (minimumRelease !== undefined && releaseTimeMs(minimumRelease) === null) {\n    issues.push('minimumRelease: expected a date-time such as \"2026-10-09T14:03:12Z\"');\n  }\n  if (issues.length > 0) return undefined;\n  const control: Control = { schemaVersion: 1, serviceWorker: serviceWorker as Control['serviceWorker'] };\n  return minimumRelease === undefined ? control : { ...control, minimumRelease: minimumRelease as string };\n});\n\nexport const DEFAULT_CONTROL: Control = { schemaVersion: 1, serviceWorker: 'enabled' };\n\n/**\n * What the flag file says. Anything unreadable, a network failure included, reads as \"no\n * instruction\": a broken flag file must not wipe every player's offline games, and a page\n * that can't reach the server keeps playing.\n */\nexport const parseControl = (value: unknown): Control | null => decodeSync(ControlSchema, value);\n\nexport const isDisabled = (control: Control | null): boolean => control?.serviceWorker === 'disabled';\n\n/**\n * True when a page running the release built at `releaseTime` must update now: the flag\n * file names a minimum release, and this one is older. An unreadable time on either side\n * never forces anything.\n */\nexport const mustUpdate = (control: Control | null, releaseTime: string): boolean => {\n  const minimum = releaseTimeMs(control?.minimumRelease);\n  const own = releaseTimeMs(releaseTime);\n  return minimum !== null && own !== null && own < minimum;\n};\n\n/**\n * The flag file as the server running `releaseTime` serves it: a minimum later than that\n * release comes down to it. Raising the minimum past what the site serves would otherwise\n * send every page into a reload that can never reach a new enough release.\n */\nexport const capMinimumRelease = (control: Control, releaseTime: string): Control => {\n  const minimum = releaseTimeMs(control.minimumRelease);\n  const own = releaseTimeMs(releaseTime);\n  if (minimum === null || own === null || minimum <= own) return control;\n  return { ...control, minimumRelease: releaseTime };\n};\n\n/**\n * The build's record of its release, written beside `sw.js` as `release.json` and never\n * served: the site reads it to cap the minimum release it serves.\n */\nexport type ReleaseRecord = {\n  readonly release: string;\n  /** Canonical: UTC, whole seconds. */\n  readonly releaseTime: string;\n};\n\nexport const RELEASE_RECORD_FILE = 'release.json';\n\nexport const ReleaseRecordSchema = validator<ReleaseRecord>((value, issues) => {\n  if (!isRecord(value)) {\n    issues.push('Expected an object');\n    return undefined;\n  }\n  const { release, releaseTime } = value;\n  if (typeof release !== 'string' || release === '') issues.push('release: expected text');\n  if (releaseTimeMs(releaseTime) === null) issues.push('releaseTime: expected a date-time');\n  return issues.length === 0 ? { release: release as string, releaseTime: releaseTime as string } : undefined;\n});\n\nexport const parseReleaseRecord = (value: unknown): ReleaseRecord | null => decodeSync(ReleaseRecordSchema, value);\n"],"mappings":";;;AAwBA,IAAM,eAAe;;AAGrB,IAAa,iBAAiB,UAAkC;CAC9D,IAAI,OAAO,UAAU,YAAY,CAAC,aAAa,KAAK,KAAK,GAAG,OAAO;CACnE,MAAM,KAAK,KAAK,MAAM,KAAK;CAC3B,OAAO,OAAO,MAAM,EAAE,IAAI,OAAO;AACnC;;AAGA,IAAa,wBAAwB,UAAiC;CACpE,MAAM,KAAK,cAAc,KAAK;CAC9B,OAAO,OAAO,OAAO,OAAO,oBAAG,IAAI,KAAK,KAAK,MAAM,KAAK,GAAI,IAAI,GAAI,EAAA,CAAE,YAAY,CAAC,CAAC,MAAM,GAAG,EAAE,EAAE;AACnG;AAEA,IAAa,gBAAgB,WAAoB,OAAO,WAAW;CACjE,IAAI,CAAC,SAAS,KAAK,GAAG;EACpB,OAAO,KAAK,oBAAoB;EAChC;CACF;CACA,MAAM,EAAE,eAAe,eAAe,mBAAmB;CACzD,IAAI,kBAAkB,GAAG,OAAO,KAAK,2BAA2B;CAChE,IAAI,kBAAkB,aAAa,kBAAkB,YACnD,OAAO,KAAK,qDAAiD;CAC/D,IAAI,mBAAmB,KAAA,KAAa,cAAc,cAAc,MAAM,MACpE,OAAO,KAAK,uEAAqE;CAEnF,IAAI,OAAO,SAAS,GAAG,OAAO,KAAA;CAC9B,MAAM,UAAmB;EAAE,eAAe;EAAkB;CAA0C;CACtG,OAAO,mBAAmB,KAAA,IAAY,UAAU;EAAE,GAAG;EAAyB;CAAyB;AACzG,CAAC;AAED,IAAa,kBAA2B;CAAE,eAAe;CAAG,eAAe;AAAU;;;;;;AAOrF,IAAa,gBAAgB,UAAmC,WAAW,eAAe,KAAK;AAE/F,IAAa,cAAc,YAAqC,SAAS,kBAAkB;;;;;;AAO3F,IAAa,cAAc,SAAyB,gBAAiC;CACnF,MAAM,UAAU,cAAc,SAAS,cAAc;CACrD,MAAM,MAAM,cAAc,WAAW;CACrC,OAAO,YAAY,QAAQ,QAAQ,QAAQ,MAAM;AACnD;;;;;;AAOA,IAAa,qBAAqB,SAAkB,gBAAiC;CACnF,MAAM,UAAU,cAAc,QAAQ,cAAc;CACpD,MAAM,MAAM,cAAc,WAAW;CACrC,IAAI,YAAY,QAAQ,QAAQ,QAAQ,WAAW,KAAK,OAAO;CAC/D,OAAO;EAAE,GAAG;EAAS,gBAAgB;CAAY;AACnD;AAYA,IAAa,sBAAsB;AAEnC,IAAa,sBAAsB,WAA0B,OAAO,WAAW;CAC7E,IAAI,CAAC,SAAS,KAAK,GAAG;EACpB,OAAO,KAAK,oBAAoB;EAChC;CACF;CACA,MAAM,EAAE,SAAS,gBAAgB;CACjC,IAAI,OAAO,YAAY,YAAY,YAAY,IAAI,OAAO,KAAK,wBAAwB;CACvF,IAAI,cAAc,WAAW,MAAM,MAAM,OAAO,KAAK,mCAAmC;CACxF,OAAO,OAAO,WAAW,IAAI;EAAW;EAAgC;CAAsB,IAAI,KAAA;AACpG,CAAC;AAED,IAAa,sBAAsB,UAAyC,WAAW,qBAAqB,KAAK"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { ASSET_MANIFEST_VERSION, AssetFileSchema, FILE_KINDS, formatBytes, GameAssetManifestSchema, parseAssetManifest, planPin, referencedAssets, type AssetFile, type FileKind, type GameAssetManifest, type PinPlan, } from './asset-manifest.js';
+export { markOfflineHtml, markOfflineResponse } from './offline-mark.js';
+export { parsePinRecord, PinRecordSchema, type PinRecord } from './pin-record.js';
+export { canonicalReleaseTime, capMinimumRelease, ControlSchema, DEFAULT_CONTROL, isDisabled, mustUpdate, parseControl, parseReleaseRecord, RELEASE_RECORD_FILE, ReleaseRecordSchema, releaseTimeMs, type Control, type ReleaseRecord, } from './control.js';
+export { CONTROL_URL, isPwaCache, MESSAGES, OFFLINE_ATTRIBUTE, OFFLINE_URL, parsePinnedCacheName, PIN_RECORD_PATH, pinnedCacheName, PRECACHE_NAME, PRECACHE_PREFIX, RECENT_KINDS, recentCacheName, SW_URL, WEB_MANIFEST_URL, type RecentKind, } from './names.js';
+export { ASSETS_PREFIX, fileKind, RECENT_LIMITS, routeFor, shouldOfferUpdate, type PromptInput, type Route, type RouteInput, } from './routing.js';
+export { decodeSync, validator } from './validate.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+import { CONTROL_URL, MESSAGES, OFFLINE_ATTRIBUTE, OFFLINE_URL, PIN_RECORD_PATH, PRECACHE_NAME, PRECACHE_PREFIX, RECENT_KINDS, SW_URL, WEB_MANIFEST_URL, isPwaCache, parsePinnedCacheName, pinnedCacheName, recentCacheName } from "./names.js";
+import { ASSETS_PREFIX, RECENT_LIMITS, fileKind, routeFor, shouldOfferUpdate } from "./routing.js";
+import { ASSET_MANIFEST_VERSION, AssetFileSchema, FILE_KINDS, GameAssetManifestSchema, formatBytes, parseAssetManifest, planPin, referencedAssets } from "./asset-manifest.js";
+import { decodeSync, validator } from "./validate.js";
+import { ControlSchema, DEFAULT_CONTROL, RELEASE_RECORD_FILE, ReleaseRecordSchema, canonicalReleaseTime, capMinimumRelease, isDisabled, mustUpdate, parseControl, parseReleaseRecord, releaseTimeMs } from "./control.js";
+import { PinRecordSchema, parsePinRecord } from "./pin-record.js";
+import { markOfflineHtml, markOfflineResponse } from "./offline-mark.js";
+export { ASSETS_PREFIX, ASSET_MANIFEST_VERSION, AssetFileSchema, CONTROL_URL, ControlSchema, DEFAULT_CONTROL, FILE_KINDS, GameAssetManifestSchema, MESSAGES, OFFLINE_ATTRIBUTE, OFFLINE_URL, PIN_RECORD_PATH, PRECACHE_NAME, PRECACHE_PREFIX, PinRecordSchema, RECENT_KINDS, RECENT_LIMITS, RELEASE_RECORD_FILE, ReleaseRecordSchema, SW_URL, WEB_MANIFEST_URL, canonicalReleaseTime, capMinimumRelease, decodeSync, fileKind, formatBytes, isDisabled, isPwaCache, markOfflineHtml, markOfflineResponse, mustUpdate, parseAssetManifest, parseControl, parsePinRecord, parsePinnedCacheName, parseReleaseRecord, pinnedCacheName, planPin, recentCacheName, referencedAssets, releaseTimeMs, routeFor, shouldOfferUpdate, validator };

package/dist/names.d.ts

@@ -0,0 +1,47 @@
+/** Tier 1: Workbox's precache, one per release; Workbox tracks revisions inside it. */
+export declare const PRECACHE_PREFIX = "joystyk";
+export declare const PRECACHE_NAME = "shell";
+/** Tier 2 kinds: each has its own capped cache. */
+export declare const RECENT_KINDS: readonly ["code", "art", "audio", "wasm"];
+export type RecentKind = (typeof RECENT_KINDS)[number];
+/** Bump the suffix when a Tier 2 cache's contents change shape; old ones are then deleted. */
+export declare const recentCacheName: (kind: RecentKind) => string;
+/** Tier 3: one cache per pinned game build, `game:<id>:<version>` (offline-and-updates.md). */
+export declare const pinnedCacheName: (id: string, version: string) => string;
+/** The game and version a pinned cache holds, or null for any other cache. */
+export declare const parsePinnedCacheName: (name: string) => {
+    readonly id: string;
+    readonly version: string;
+} | null;
+/** Every cache this site's PWA may create; the kill switch deletes them all. */
+export declare const isPwaCache: (name: string) => boolean;
+/** The service worker's own URL. Always served `no-cache`. */
+export declare const SW_URL = "/sw.js";
+/** The kill-switch flag file. Always served `no-cache`. */
+export declare const CONTROL_URL = "/pwa-control.json";
+/** The offline fallback page. */
+export declare const OFFLINE_URL = "/offline";
+/**
+ * The attribute the worker adds to the <html> tag of a page it answers from a cache because
+ * the network failed (offline-mark.ts). @joystyk/ui's tokens.css reads it to keep ad slots
+ * collapsed from the first paint.
+ */
+export declare const OFFLINE_ATTRIBUTE = "data-offline";
+/** The web app manifest. */
+export declare const WEB_MANIFEST_URL = "/manifest.webmanifest";
+/**
+ * Inside each pinned cache, the pin's own record (game name, version, asset list URL) lives
+ * at this path. No request ever asks for it, so routing never serves it.
+ */
+export declare const PIN_RECORD_PATH = "/.joystyk-pin.json";
+/** Messages between the page and the worker. */
+export declare const MESSAGES: {
+    /** Page → waiting worker: the player accepted the update. */
+    readonly skipWaiting: "SKIP_WAITING";
+    /** Page → worker: read the flag file now. */
+    readonly checkControl: "CHECK_CONTROL";
+    /** Page → worker, with a MessagePort: which release are you? */
+    readonly release: "GET_RELEASE";
+    /** Worker → pages: the kill switch fired; the worker unregistered and cleared its caches. */
+    readonly disabled: "PWA_DISABLED";
+};

package/dist/names.js

@@ -0,0 +1,64 @@
+//#region src/names.ts
+/** Tier 1: Workbox's precache, one per release; Workbox tracks revisions inside it. */
+var PRECACHE_PREFIX = "joystyk";
+var PRECACHE_NAME = "shell";
+/** Tier 2 kinds: each has its own capped cache. */
+var RECENT_KINDS = [
+	"code",
+	"art",
+	"audio",
+	"wasm"
+];
+/** Bump the suffix when a Tier 2 cache's contents change shape; old ones are then deleted. */
+var recentCacheName = (kind) => `recent:${kind}:v1`;
+var PINNED = /^game:([a-z0-9]+(?:-[a-z0-9]+)*):([0-9A-Za-z.+-]+)$/;
+/** Tier 3: one cache per pinned game build, `game:<id>:<version>` (offline-and-updates.md). */
+var pinnedCacheName = (id, version) => {
+	const name = `game:${id}:${version}`;
+	if (!PINNED.test(name)) throw new RangeError(`Can't name a pinned cache for game ${JSON.stringify(id)} at version ${JSON.stringify(version)}.`);
+	return name;
+};
+/** The game and version a pinned cache holds, or null for any other cache. */
+var parsePinnedCacheName = (name) => {
+	const match = PINNED.exec(name);
+	return match === null ? null : {
+		id: match[1] ?? "",
+		version: match[2] ?? ""
+	};
+};
+/** Every cache this site's PWA may create; the kill switch deletes them all. */
+var isPwaCache = (name) => name.startsWith(`joystyk-`) || name.startsWith("recent:") || name.startsWith("game:") || name.startsWith("workbox-");
+/** The service worker's own URL. Always served `no-cache`. */
+var SW_URL = "/sw.js";
+/** The kill-switch flag file. Always served `no-cache`. */
+var CONTROL_URL = "/pwa-control.json";
+/** The offline fallback page. */
+var OFFLINE_URL = "/offline";
+/**
+* The attribute the worker adds to the <html> tag of a page it answers from a cache because
+* the network failed (offline-mark.ts). @joystyk/ui's tokens.css reads it to keep ad slots
+* collapsed from the first paint.
+*/
+var OFFLINE_ATTRIBUTE = "data-offline";
+/** The web app manifest. */
+var WEB_MANIFEST_URL = "/manifest.webmanifest";
+/**
+* Inside each pinned cache, the pin's own record (game name, version, asset list URL) lives
+* at this path. No request ever asks for it, so routing never serves it.
+*/
+var PIN_RECORD_PATH = "/.joystyk-pin.json";
+/** Messages between the page and the worker. */
+var MESSAGES = {
+	/** Page → waiting worker: the player accepted the update. */
+	skipWaiting: "SKIP_WAITING",
+	/** Page → worker: read the flag file now. */
+	checkControl: "CHECK_CONTROL",
+	/** Page → worker, with a MessagePort: which release are you? */
+	release: "GET_RELEASE",
+	/** Worker → pages: the kill switch fired; the worker unregistered and cleared its caches. */
+	disabled: "PWA_DISABLED"
+};
+//#endregion
+export { CONTROL_URL, MESSAGES, OFFLINE_ATTRIBUTE, OFFLINE_URL, PIN_RECORD_PATH, PRECACHE_NAME, PRECACHE_PREFIX, RECENT_KINDS, SW_URL, WEB_MANIFEST_URL, isPwaCache, parsePinnedCacheName, pinnedCacheName, recentCacheName };
+
+//# sourceMappingURL=names.js.map

package/dist/names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.js","names":[],"sources":["../src/names.ts"],"sourcesContent":["// Cache names and fixed URLs, shared by the service worker, the page and the build. Every\n// cache the PWA owns says what it holds and, where it can go stale, which version\n// (offline-and-updates.md, \"Cache tiers\"), so cleanup after an update is exact.\n\n/** Tier 1: Workbox's precache, one per release; Workbox tracks revisions inside it. */\nexport const PRECACHE_PREFIX = 'joystyk';\nexport const PRECACHE_NAME = 'shell';\n\n/** Tier 2 kinds: each has its own capped cache. */\nexport const RECENT_KINDS = ['code', 'art', 'audio', 'wasm'] as const;\nexport type RecentKind = (typeof RECENT_KINDS)[number];\n\n/** Bump the suffix when a Tier 2 cache's contents change shape; old ones are then deleted. */\nexport const recentCacheName = (kind: RecentKind): string => `recent:${kind}:v1`;\n\nconst PINNED = /^game:([a-z0-9]+(?:-[a-z0-9]+)*):([0-9A-Za-z.+-]+)$/;\n\n/** Tier 3: one cache per pinned game build, `game:<id>:<version>` (offline-and-updates.md). */\nexport const pinnedCacheName = (id: string, version: string): string => {\n  const name = `game:${id}:${version}`;\n  if (!PINNED.test(name))\n    throw new RangeError(\n      `Can't name a pinned cache for game ${JSON.stringify(id)} at version ${JSON.stringify(version)}.`,\n    );\n  return name;\n};\n\n/** The game and version a pinned cache holds, or null for any other cache. */\nexport const parsePinnedCacheName = (name: string): { readonly id: string; readonly version: string } | null => {\n  const match = PINNED.exec(name);\n  return match === null ? null : { id: match[1] ?? '', version: match[2] ?? '' };\n};\n\n/** Every cache this site's PWA may create; the kill switch deletes them all. */\nexport const isPwaCache = (name: string): boolean =>\n  name.startsWith(`${PRECACHE_PREFIX}-`) ||\n  name.startsWith('recent:') ||\n  name.startsWith('game:') ||\n  name.startsWith('workbox-');\n\n/** The service worker's own URL. Always served `no-cache`. */\nexport const SW_URL = '/sw.js';\n/** The kill-switch flag file. Always served `no-cache`. */\nexport const CONTROL_URL = '/pwa-control.json';\n/** The offline fallback page. */\nexport const OFFLINE_URL = '/offline';\n/**\n * The attribute the worker adds to the <html> tag of a page it answers from a cache because\n * the network failed (offline-mark.ts). @joystyk/ui's tokens.css reads it to keep ad slots\n * collapsed from the first paint.\n */\nexport const OFFLINE_ATTRIBUTE = 'data-offline';\n/** The web app manifest. */\nexport const WEB_MANIFEST_URL = '/manifest.webmanifest';\n/**\n * Inside each pinned cache, the pin's own record (game name, version, asset list URL) lives\n * at this path. No request ever asks for it, so routing never serves it.\n */\nexport const PIN_RECORD_PATH = '/.joystyk-pin.json';\n\n/** Messages between the page and the worker. */\nexport const MESSAGES = {\n  /** Page → waiting worker: the player accepted the update. */\n  skipWaiting: 'SKIP_WAITING',\n  /** Page → worker: read the flag file now. */\n  checkControl: 'CHECK_CONTROL',\n  /** Page → worker, with a MessagePort: which release are you? */\n  release: 'GET_RELEASE',\n  /** Worker → pages: the kill switch fired; the worker unregistered and cleared its caches. */\n  disabled: 'PWA_DISABLED',\n} as const;\n"],"mappings":";;AAKA,IAAa,kBAAkB;AAC/B,IAAa,gBAAgB;;AAG7B,IAAa,eAAe;CAAC;CAAQ;CAAO;CAAS;AAAM;;AAI3D,IAAa,mBAAmB,SAA6B,UAAU,KAAK;AAE5E,IAAM,SAAS;;AAGf,IAAa,mBAAmB,IAAY,YAA4B;CACtE,MAAM,OAAO,QAAQ,GAAG,GAAG;CAC3B,IAAI,CAAC,OAAO,KAAK,IAAI,GACnB,MAAM,IAAI,WACR,sCAAsC,KAAK,UAAU,EAAE,EAAE,cAAc,KAAK,UAAU,OAAO,EAAE,EACjG;CACF,OAAO;AACT;;AAGA,IAAa,wBAAwB,SAA2E;CAC9G,MAAM,QAAQ,OAAO,KAAK,IAAI;CAC9B,OAAO,UAAU,OAAO,OAAO;EAAE,IAAI,MAAM,MAAM;EAAI,SAAS,MAAM,MAAM;CAAG;AAC/E;;AAGA,IAAa,cAAc,SACzB,KAAK,WAAW,UAAqB,KACrC,KAAK,WAAW,SAAS,KACzB,KAAK,WAAW,OAAO,KACvB,KAAK,WAAW,UAAU;;AAG5B,IAAa,SAAS;;AAEtB,IAAa,cAAc;;AAE3B,IAAa,cAAc;;;;;;AAM3B,IAAa,oBAAoB;;AAEjC,IAAa,mBAAmB;;;;;AAKhC,IAAa,kBAAkB;;AAG/B,IAAa,WAAW;;CAEtB,aAAa;;CAEb,cAAc;;CAEd,SAAS;;CAET,UAAU;AACZ"}