@joystyk/pwa 0.0.0 → 0.2.0

package/dist/client/forced.js

@@ -0,0 +1,57 @@
+import { mustUpdate } from "../control.js";
+import { readControl } from "./control.js";
+//#region src/client/forced.ts
+var DEFAULT_CHECK_MS = 9e5;
+/** The default notice: `<jy-security-update>` at the end of the body. */
+var securityNotice = () => ({ show: (update) => {
+	import("./elements.js").then(({ definePwaElements }) => {
+		definePwaElements();
+		const notice = document.createElement("jy-security-update");
+		notice.onUpdate = update;
+		document.body.append(notice);
+	});
+} });
+var watchForcedUpdates = (options) => {
+	const read = options.read ?? readControl;
+	const reload = options.reload ?? (() => location.reload());
+	const notice = options.notice ?? securityNotice();
+	const cleanups = [];
+	let forcing = false;
+	const force = () => {
+		if (forcing) return;
+		forcing = true;
+		const saved = Promise.resolve().then(() => options.saveGame?.()).catch(() => void 0);
+		notice.show(() => {
+			saved.then(() => options.prepare?.()).catch(() => void 0).then(reload);
+		});
+	};
+	const observe = (control) => {
+		if (mustUpdate(control, options.releaseTime)) force();
+	};
+	const check = async () => {
+		const control = await read();
+		observe(control);
+		return control;
+	};
+	const interval = setInterval(() => void check(), options.checkMs ?? DEFAULT_CHECK_MS);
+	cleanups.push(() => clearInterval(interval));
+	const onVisible = () => {
+		if (document.visibilityState === "visible") check();
+	};
+	document.addEventListener("visibilitychange", onVisible);
+	cleanups.push(() => document.removeEventListener("visibilitychange", onVisible));
+	return {
+		check,
+		observe,
+		get forcing() {
+			return forcing;
+		},
+		dispose: () => {
+			for (const cleanup of cleanups.splice(0)) cleanup();
+		}
+	};
+};
+//#endregion
+export { securityNotice, watchForcedUpdates };
+
+//# sourceMappingURL=forced.js.map

package/dist/client/forced.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forced.js","names":[],"sources":["../../src/client/forced.ts"],"sourcesContent":["// Forced security updates (offline-and-updates.md, Rule 2). The page reads the flag file at\n// start, every 15 minutes, whenever the tab comes back into view and on each navigation to\n// the index. When the file names a minimum release later than this page's, the page shows a\n// blocking notice and asks the launcher to save the game in play. Only when the player\n// chooses Update now, and the save has landed, does it bring in the new worker and reload: a\n// game never swaps code without that save (Rule 2). A page that can't reach the flag file\n// reads no instruction, so offline play goes on.\nimport { mustUpdate, type Control } from '../control.ts';\nimport { readControl } from './control.ts';\n\n/** How the page shows the notice. The default is `<jy-security-update>`. */\nexport interface SecurityNotice {\n  /** Shows the blocking notice; `update` runs when the player chooses Update now. */\n  show(update: () => void): void;\n}\n\nexport type ForcedUpdateOptions = {\n  /** This page's release time (`__JOYSTYK_RELEASE_TIME__`). */\n  readonly releaseTime: string;\n  /** Saves the game in play: the launcher's `requestSave`. Without it, nothing is saved. */\n  readonly saveGame?: () => Promise<void>;\n  /** Brings in the new release's worker before the reload, when there is one. */\n  readonly prepare?: () => Promise<void>;\n  /** How often to read the flag file. Default 15 minutes. */\n  readonly checkMs?: number;\n  readonly notice?: SecurityNotice;\n  /** Reads the flag file; swapped in tests. */\n  readonly read?: () => Promise<Control | null>;\n  /** Reloads the page; swapped in tests. */\n  readonly reload?: () => void;\n};\n\nexport interface ForcedUpdates {\n  /** Reads the flag file now and acts on it; resolves with what it said. */\n  check(): Promise<Control | null>;\n  /** Acts on a flag file read elsewhere. */\n  observe(control: Control | null): void;\n  /** True once the notice is up. */\n  readonly forcing: boolean;\n  dispose(): void;\n}\n\nconst DEFAULT_CHECK_MS = 15 * 60 * 1000;\n\n/** The default notice: `<jy-security-update>` at the end of the body. */\nexport const securityNotice = (): SecurityNotice => ({\n  show: (update) => {\n    void import('./elements.ts').then(({ definePwaElements }) => {\n      definePwaElements();\n      const notice = document.createElement('jy-security-update');\n      notice.onUpdate = update;\n      document.body.append(notice);\n    });\n  },\n});\n\nexport const watchForcedUpdates = (options: ForcedUpdateOptions): ForcedUpdates => {\n  const read = options.read ?? readControl;\n  const reload = options.reload ?? (() => location.reload());\n  const notice = options.notice ?? securityNotice();\n  const cleanups: (() => void)[] = [];\n  let forcing = false;\n\n  const force = (): void => {\n    if (forcing) return;\n    forcing = true;\n    // Saving starts with the notice: the notice stops input, and pausing stops a real-time\n    // game from running on unattended behind it.\n    const saved = Promise.resolve()\n      .then(() => options.saveGame?.())\n      .catch(() => undefined);\n    notice.show(() => {\n      void saved\n        .then(() => options.prepare?.())\n        .catch(() => undefined)\n        .then(reload);\n    });\n  };\n\n  const observe = (control: Control | null): void => {\n    if (mustUpdate(control, options.releaseTime)) force();\n  };\n\n  const check = async (): Promise<Control | null> => {\n    const control = await read();\n    observe(control);\n    return control;\n  };\n\n  const interval = setInterval(() => void check(), options.checkMs ?? DEFAULT_CHECK_MS);\n  cleanups.push(() => clearInterval(interval));\n  const onVisible = (): void => {\n    if (document.visibilityState === 'visible') void check();\n  };\n  document.addEventListener('visibilitychange', onVisible);\n  cleanups.push(() => document.removeEventListener('visibilitychange', onVisible));\n\n  return {\n    check,\n    observe,\n    get forcing() {\n      return forcing;\n    },\n    dispose: () => {\n      for (const cleanup of cleanups.splice(0)) cleanup();\n    },\n  };\n};\n"],"mappings":";;;AA0CA,IAAM,mBAAmB;;AAGzB,IAAa,wBAAwC,EACnD,OAAO,WAAW;CAChB,OAAY,gBAAgB,CAAC,MAAM,EAAE,wBAAwB;EAC3D,kBAAkB;EAClB,MAAM,SAAS,SAAS,cAAc,oBAAoB;EAC1D,OAAO,WAAW;EAClB,SAAS,KAAK,OAAO,MAAM;CAC7B,CAAC;AACH,EACF;AAEA,IAAa,sBAAsB,YAAgD;CACjF,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,SAAS,QAAQ,iBAAiB,SAAS,OAAO;CACxD,MAAM,SAAS,QAAQ,UAAU,eAAe;CAChD,MAAM,WAA2B,CAAC;CAClC,IAAI,UAAU;CAEd,MAAM,cAAoB;EACxB,IAAI,SAAS;EACb,UAAU;EAGV,MAAM,QAAQ,QAAQ,QAAQ,CAAC,CAC5B,WAAW,QAAQ,WAAW,CAAC,CAAC,CAChC,YAAY,KAAA,CAAS;EACxB,OAAO,WAAW;GAChB,MACG,WAAW,QAAQ,UAAU,CAAC,CAAC,CAC/B,YAAY,KAAA,CAAS,CAAC,CACtB,KAAK,MAAM;EAChB,CAAC;CACH;CAEA,MAAM,WAAW,YAAkC;EACjD,IAAI,WAAW,SAAS,QAAQ,WAAW,GAAG,MAAM;CACtD;CAEA,MAAM,QAAQ,YAAqC;EACjD,MAAM,UAAU,MAAM,KAAK;EAC3B,QAAQ,OAAO;EACf,OAAO;CACT;CAEA,MAAM,WAAW,kBAAkB,KAAK,MAAM,GAAG,QAAQ,WAAW,gBAAgB;CACpF,SAAS,WAAW,cAAc,QAAQ,CAAC;CAC3C,MAAM,kBAAwB;EAC5B,IAAI,SAAS,oBAAoB,WAAW,MAAW;CACzD;CACA,SAAS,iBAAiB,oBAAoB,SAAS;CACvD,SAAS,WAAW,SAAS,oBAAoB,oBAAoB,SAAS,CAAC;CAE/E,OAAO;EACL;EACA;EACA,IAAI,UAAU;GACZ,OAAO;EACT;EACA,eAAe;GACb,KAAK,MAAM,WAAW,SAAS,OAAO,CAAC,GAAG,QAAQ;EACpD;CACF;AACF"}

package/dist/client/index.d.ts

@@ -0,0 +1,7 @@
+export { definePwaElements, OfflineToggle, SecurityUpdate, UpdateToast } from './elements.js';
+export { browserCachePorts, pinnedGames, pinStatus, unpinGame, type CachePorts } from './pinned.js';
+export { browserPinPorts, PIN_MESSAGES, pinGame, refreshPinnedGames, type Pinned, type PinError, type PinErrorCode, type PinPorts, } from './pins.js';
+export { readControl } from './control.js';
+export { securityNotice, watchForcedUpdates, type ForcedUpdateOptions, type ForcedUpdates, type SecurityNotice, } from './forced.js';
+export { dailyToPrefetch, disablePwa, registerPwa, toastPrompt, type DailyPrefetcher, type PwaController, type PwaOptions, type UpdatePrompt, } from './register.js';
+export { watchOfflineAvailability, PIN_CHANGED, type AvailabilityPorts } from './availability.js';

package/dist/client/index.js

@@ -0,0 +1,8 @@
+import { browserCachePorts, pinStatus, pinnedGames, unpinGame } from "./pinned.js";
+import { PIN_CHANGED, watchOfflineAvailability } from "./availability.js";
+import { readControl } from "./control.js";
+import { PIN_MESSAGES, browserPinPorts, pinGame, refreshPinnedGames } from "./pins.js";
+import { OfflineToggle, SecurityUpdate, UpdateToast, definePwaElements } from "./elements.js";
+import { securityNotice, watchForcedUpdates } from "./forced.js";
+import { dailyToPrefetch, disablePwa, registerPwa, toastPrompt } from "./register.js";
+export { OfflineToggle, PIN_CHANGED, PIN_MESSAGES, SecurityUpdate, UpdateToast, browserCachePorts, browserPinPorts, dailyToPrefetch, definePwaElements, disablePwa, pinGame, pinStatus, pinnedGames, readControl, refreshPinnedGames, registerPwa, securityNotice, toastPrompt, unpinGame, watchForcedUpdates, watchOfflineAvailability };

package/dist/client/pinned.d.ts

@@ -0,0 +1,13 @@
+import { type PinRecord } from '../pin-record.js';
+/** The Cache Storage a pin lives in, and the origin its keys belong to. Tests pass fakes. */
+export type CachePorts = {
+    readonly caches: CacheStorage;
+    readonly origin: string;
+};
+export declare const browserCachePorts: () => CachePorts;
+/** Every pinned game, read from each pin's own record, sorted by name. */
+export declare const pinnedGames: (ports?: CachePorts) => Promise<PinRecord[]>;
+/** The game's pin, or null when it isn't available offline. */
+export declare const pinStatus: (gameId: string, ports?: CachePorts) => Promise<PinRecord | null>;
+/** Removes every pinned build of the game. */
+export declare const unpinGame: (gameId: string, ports?: CachePorts) => Promise<void>;

package/dist/client/pinned.js

@@ -0,0 +1,29 @@
+import { PIN_RECORD_PATH, parsePinnedCacheName } from "../names.js";
+import { parsePinRecord } from "../pin-record.js";
+//#region src/client/pinned.ts
+var browserCachePorts = () => ({
+	caches: globalThis.caches,
+	origin: location.origin
+});
+/** Every pinned game, read from each pin's own record, sorted by name. */
+var pinnedGames = async (ports = browserCachePorts()) => {
+	const found = [];
+	for (const name of await ports.caches.keys()) {
+		const pinned = parsePinnedCacheName(name);
+		if (pinned === null) continue;
+		const response = await (await ports.caches.open(name)).match(new URL(PIN_RECORD_PATH, ports.origin).href);
+		const record = response === void 0 ? null : parsePinRecord(await response.json().catch(() => null));
+		if (record !== null && record.id === pinned.id && record.version === pinned.version) found.push(record);
+	}
+	return found.sort((a, b) => a.name.localeCompare(b.name, "en"));
+};
+/** The game's pin, or null when it isn't available offline. */
+var pinStatus = async (gameId, ports = browserCachePorts()) => (await pinnedGames(ports)).find((record) => record.id === gameId) ?? null;
+/** Removes every pinned build of the game. */
+var unpinGame = async (gameId, ports = browserCachePorts()) => {
+	for (const name of await ports.caches.keys()) if (parsePinnedCacheName(name)?.id === gameId) await ports.caches.delete(name);
+};
+//#endregion
+export { browserCachePorts, pinStatus, pinnedGames, unpinGame };
+
+//# sourceMappingURL=pinned.js.map

package/dist/client/pinned.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned.js","names":[],"sources":["../../src/client/pinned.ts"],"sourcesContent":["// Reading and removing pins: what the offline page needs, without the code that pins.\nimport { parsePinnedCacheName, PIN_RECORD_PATH } from '../names.ts';\nimport { parsePinRecord, type PinRecord } from '../pin-record.ts';\n\n/** The Cache Storage a pin lives in, and the origin its keys belong to. Tests pass fakes. */\nexport type CachePorts = {\n  readonly caches: CacheStorage;\n  readonly origin: string;\n};\n\nexport const browserCachePorts = (): CachePorts => ({ caches: globalThis.caches, origin: location.origin });\n\n/** Every pinned game, read from each pin's own record, sorted by name. */\nexport const pinnedGames = async (ports: CachePorts = browserCachePorts()): Promise<PinRecord[]> => {\n  const found: PinRecord[] = [];\n  for (const name of await ports.caches.keys()) {\n    const pinned = parsePinnedCacheName(name);\n    if (pinned === null) continue;\n    const response = await (await ports.caches.open(name)).match(new URL(PIN_RECORD_PATH, ports.origin).href);\n    const record = response === undefined ? null : parsePinRecord(await response.json().catch(() => null));\n    if (record !== null && record.id === pinned.id && record.version === pinned.version) found.push(record);\n  }\n  return found.sort((a, b) => a.name.localeCompare(b.name, 'en'));\n};\n\n/** The game's pin, or null when it isn't available offline. */\nexport const pinStatus = async (gameId: string, ports: CachePorts = browserCachePorts()): Promise<PinRecord | null> =>\n  (await pinnedGames(ports)).find((record) => record.id === gameId) ?? null;\n\n/** Removes every pinned build of the game. */\nexport const unpinGame = async (gameId: string, ports: CachePorts = browserCachePorts()): Promise<void> => {\n  for (const name of await ports.caches.keys()) {\n    if (parsePinnedCacheName(name)?.id === gameId) await ports.caches.delete(name);\n  }\n};\n"],"mappings":";;;AAUA,IAAa,2BAAuC;CAAE,QAAQ,WAAW;CAAQ,QAAQ,SAAS;AAAO;;AAGzG,IAAa,cAAc,OAAO,QAAoB,kBAAkB,MAA4B;CAClG,MAAM,QAAqB,CAAC;CAC5B,KAAK,MAAM,QAAQ,MAAM,MAAM,OAAO,KAAK,GAAG;EAC5C,MAAM,SAAS,qBAAqB,IAAI;EACxC,IAAI,WAAW,MAAM;EACrB,MAAM,WAAW,OAAO,MAAM,MAAM,OAAO,KAAK,IAAI,EAAA,CAAG,MAAM,IAAI,IAAI,iBAAiB,MAAM,MAAM,CAAC,CAAC,IAAI;EACxG,MAAM,SAAS,aAAa,KAAA,IAAY,OAAO,eAAe,MAAM,SAAS,KAAK,CAAC,CAAC,YAAY,IAAI,CAAC;EACrG,IAAI,WAAW,QAAQ,OAAO,OAAO,OAAO,MAAM,OAAO,YAAY,OAAO,SAAS,MAAM,KAAK,MAAM;CACxG;CACA,OAAO,MAAM,MAAM,GAAG,MAAM,EAAE,KAAK,cAAc,EAAE,MAAM,IAAI,CAAC;AAChE;;AAGA,IAAa,YAAY,OAAO,QAAgB,QAAoB,kBAAkB,OACnF,MAAM,YAAY,KAAK,EAAA,CAAG,MAAM,WAAW,OAAO,OAAO,MAAM,KAAK;;AAGvE,IAAa,YAAY,OAAO,QAAgB,QAAoB,kBAAkB,MAAqB;CACzG,KAAK,MAAM,QAAQ,MAAM,MAAM,OAAO,KAAK,GACzC,IAAI,qBAAqB,IAAI,CAAC,EAAE,OAAO,QAAQ,MAAM,MAAM,OAAO,OAAO,IAAI;AAEjF"}

package/dist/client/pins.d.ts

@@ -0,0 +1,43 @@
+import { type Result } from '@joystyk/contracts';
+import type { PersistResult } from '@joystyk/storage/browser';
+import type { PinRecord } from '../pin-record.js';
+import { type CachePorts } from './pinned.js';
+/** What pinning touches; tests pass fakes. */
+export type PinPorts = CachePorts & {
+    readonly fetch: (url: string, init?: RequestInit) => Promise<Response>;
+    /** Asks the browser to keep the site's data; called on the first pin only. */
+    readonly persist: () => Promise<PersistResult>;
+};
+export declare const browserPinPorts: () => PinPorts;
+export type PinErrorCode = 'Offline' | 'Quota' | 'Invalid' | 'Incomplete' | 'Unsupported';
+export type PinError = {
+    readonly code: PinErrorCode;
+    /** For players. */
+    readonly message: string;
+    /** For developers. */
+    readonly detail: string;
+};
+export declare const PIN_MESSAGES: Readonly<Record<PinErrorCode, string>>;
+export type Pinned = {
+    readonly record: PinRecord;
+    /** Set on the first pin, when persistent storage was requested; null otherwise. */
+    readonly persisted: PersistResult | null;
+};
+/**
+ * Makes a game available offline, or brings its pin up to date: reads the asset manifest at
+ * `assets` (the game manifest's `assets`), caches every file and the game's page, then
+ * removes older builds. The first pin asks for persistent storage.
+ */
+export declare const pinGame: (input: {
+    readonly gameId: string;
+    readonly assets: string;
+}, ports?: PinPorts) => Promise<Result<Pinned, PinError>>;
+/**
+ * Brings every pin up to the build the server has now: same version, missing files added and
+ * stale ones dropped; a new version, a new cache, then the old one removed. Call it at a safe
+ * point while online (Rule 2); a pin that fails to refresh keeps its old build.
+ */
+export declare const refreshPinnedGames: (ports?: PinPorts) => Promise<{
+    refreshed: string[];
+    failed: string[];
+}>;

package/dist/client/pins.js

@@ -0,0 +1,140 @@
+import { PIN_RECORD_PATH, parsePinnedCacheName, pinnedCacheName } from "../names.js";
+import { parseAssetManifest, planPin, referencedAssets } from "../asset-manifest.js";
+import { pinnedGames } from "./pinned.js";
+import { err, ok } from "@joystyk/contracts";
+//#region src/client/pins.ts
+var browserPinPorts = () => ({
+	caches: globalThis.caches,
+	fetch: (url, init) => fetch(url, init),
+	origin: location.origin,
+	persist: async () => (await import("@joystyk/storage/browser")).requestPersistentStorage()
+});
+var PIN_MESSAGES = {
+	Offline: "You're offline. Connect to the internet, then try again.",
+	Quota: "This device is out of storage space, so the game couldn't be saved for offline play.",
+	Invalid: "This game can't be saved for offline play right now.",
+	Incomplete: "This game couldn't be saved for offline play right now. Try again in a minute.",
+	Unsupported: "This browser can't keep games for offline play."
+};
+var pinError = (code, detail) => ({
+	code,
+	message: PIN_MESSAGES[code],
+	detail
+});
+var PinFailure = class extends Error {
+	code;
+	constructor(code, detail) {
+		super(detail);
+		this.code = code;
+	}
+};
+var toPinError = (cause) => {
+	if (cause instanceof PinFailure) return pinError(cause.code, cause.message);
+	if (cause instanceof DOMException && cause.name === "QuotaExceededError") return pinError("Quota", cause.message);
+	if (cause instanceof TypeError) return pinError("Offline", cause.message);
+	return pinError("Incomplete", String(cause));
+};
+var pathsIn = async (cache) => (await cache.keys()).map((request) => new URL(request.url).pathname);
+var fetchOk = async (ports, url, cache) => {
+	const response = await ports.fetch(url, {
+		cache,
+		credentials: "same-origin",
+		...cache === "no-cache" ? { headers: { "X-Joystyk-Pin-Refresh": "1" } } : {}
+	});
+	if (!response.ok || response.redirected) throw new PinFailure("Incomplete", `${url}: HTTP ${String(response.status)}${response.redirected ? " (redirected)" : ""}`);
+	return response;
+};
+var loadManifest = async (ports, gameId, assets) => {
+	const response = await fetchOk(ports, assets, "no-cache").catch((cause) => {
+		throw cause instanceof PinFailure ? new PinFailure("Invalid", cause.message) : cause;
+	});
+	const raw = await response.clone().json().catch(() => null);
+	const parsed = parseAssetManifest(raw);
+	if (!parsed.ok) throw new PinFailure("Invalid", `${assets}: ${parsed.error.join("; ")}`);
+	if (parsed.value.id !== gameId) throw new PinFailure("Invalid", `${assets} describes ${parsed.value.id}, not ${gameId}`);
+	return {
+		manifest: parsed.value,
+		response
+	};
+};
+var pinOnce = async (ports, gameId, assets) => {
+	const { manifest, response: manifestResponse } = await loadManifest(ports, gameId, assets);
+	const names = await ports.caches.keys();
+	const firstPin = !names.some((name) => parsePinnedCacheName(name) !== null);
+	const existing = [];
+	for (const name of names) if (parsePinnedCacheName(name)?.id === gameId) existing.push({
+		cacheName: name,
+		paths: await pathsIn(await ports.caches.open(name))
+	});
+	const target = pinnedCacheName(manifest.id, manifest.version);
+	const created = !names.includes(target);
+	const plan = planPin(manifest, assets, target, existing, PIN_RECORD_PATH);
+	const key = (path) => new URL(path, ports.origin).href;
+	const cache = await ports.caches.open(target);
+	try {
+		for (const url of plan.fetch) await cache.put(key(url), await fetchOk(ports, url, "default"));
+		const files = new Set(manifest.files.map((file) => file.url));
+		const documents = [];
+		for (const url of plan.documents) documents.push([url, url === assets ? manifestResponse : await fetchOk(ports, url, "no-cache")]);
+		const page = documents.find(([url]) => url === manifest.page)?.[1];
+		if (page !== void 0) {
+			const missing = referencedAssets(await page.clone().text()).filter((url) => !files.has(url));
+			if (missing.length > 0) throw new PinFailure("Incomplete", `${manifest.page} needs files the asset manifest doesn't list: ${missing.join(", ")}`);
+		}
+		for (const [url, response] of documents) await cache.put(key(url), response);
+		const record = {
+			id: manifest.id,
+			name: manifest.name,
+			version: manifest.version,
+			release: manifest.release,
+			page: manifest.page,
+			assets,
+			totalBytes: manifest.totalBytes
+		};
+		await cache.put(key(PIN_RECORD_PATH), new Response(JSON.stringify(record), { headers: { "content-type": "application/json" } }));
+		for (const url of plan.remove) await cache.delete(key(url));
+		for (const name of plan.dropCaches) await ports.caches.delete(name);
+		return {
+			record,
+			persisted: firstPin ? await ports.persist() : null
+		};
+	} catch (cause) {
+		if (created) await ports.caches.delete(target);
+		throw cause;
+	}
+};
+/**
+* Makes a game available offline, or brings its pin up to date: reads the asset manifest at
+* `assets` (the game manifest's `assets`), caches every file and the game's page, then
+* removes older builds. The first pin asks for persistent storage.
+*/
+var pinGame = async (input, ports = browserPinPorts()) => {
+	if (ports.caches === void 0) return err(pinError("Unsupported", "no Cache Storage"));
+	for (let attempt = 1;; attempt += 1) try {
+		return ok(await pinOnce(ports, input.gameId, input.assets));
+	} catch (cause) {
+		const error = toPinError(cause);
+		if (error.code !== "Incomplete" || attempt === 2) return err(error);
+	}
+};
+/**
+* Brings every pin up to the build the server has now: same version, missing files added and
+* stale ones dropped; a new version, a new cache, then the old one removed. Call it at a safe
+* point while online (Rule 2); a pin that fails to refresh keeps its old build.
+*/
+var refreshPinnedGames = async (ports = browserPinPorts()) => {
+	const refreshed = [];
+	const failed = [];
+	for (const record of await pinnedGames(ports)) ((await pinGame({
+		gameId: record.id,
+		assets: record.assets
+	}, ports)).ok ? refreshed : failed).push(record.id);
+	return {
+		refreshed,
+		failed
+	};
+};
+//#endregion
+export { PIN_MESSAGES, browserPinPorts, pinGame, refreshPinnedGames };
+
+//# sourceMappingURL=pins.js.map

package/dist/client/pins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pins.js","names":[],"sources":["../../src/client/pins.ts"],"sourcesContent":["// Tier 3, from the page: \"Make available offline\" writes a game's whole build into its own\n// cache, `game:<id>:<version>`, which the worker checks before anything else it doesn't\n// precache. The page and the worker share the origin's Cache Storage, so no message passes\n// between them (the blog's design). A pin holds every file in the game's asset manifest and\n// the game's page, so it is complete or it isn't kept.\nimport { err, ok, type Result } from '@joystyk/contracts';\nimport type { PersistResult } from '@joystyk/storage/browser';\nimport { parseAssetManifest, planPin, referencedAssets, type GameAssetManifest } from '../asset-manifest.ts';\nimport { parsePinnedCacheName, PIN_RECORD_PATH, pinnedCacheName } from '../names.ts';\nimport type { PinRecord } from '../pin-record.ts';\nimport { pinnedGames, type CachePorts } from './pinned.ts';\n\n/** What pinning touches; tests pass fakes. */\nexport type PinPorts = CachePorts & {\n  readonly fetch: (url: string, init?: RequestInit) => Promise<Response>;\n  /** Asks the browser to keep the site's data; called on the first pin only. */\n  readonly persist: () => Promise<PersistResult>;\n};\n\nexport const browserPinPorts = (): PinPorts => ({\n  caches: globalThis.caches,\n  fetch: (url, init) => fetch(url, init),\n  origin: location.origin,\n  // Loaded on first use: the storage package's browser code is a chunk of its own.\n  persist: async () => (await import('@joystyk/storage/browser')).requestPersistentStorage(),\n});\n\nexport type PinErrorCode = 'Offline' | 'Quota' | 'Invalid' | 'Incomplete' | 'Unsupported';\n\nexport type PinError = {\n  readonly code: PinErrorCode;\n  /** For players. */\n  readonly message: string;\n  /** For developers. */\n  readonly detail: string;\n};\n\nexport const PIN_MESSAGES: Readonly<Record<PinErrorCode, string>> = {\n  Offline: \"You're offline. Connect to the internet, then try again.\",\n  Quota: \"This device is out of storage space, so the game couldn't be saved for offline play.\",\n  Invalid: \"This game can't be saved for offline play right now.\",\n  Incomplete: \"This game couldn't be saved for offline play right now. Try again in a minute.\",\n  Unsupported: \"This browser can't keep games for offline play.\",\n};\n\nconst pinError = (code: PinErrorCode, detail: string): PinError => ({ code, message: PIN_MESSAGES[code], detail });\n\nclass PinFailure extends Error {\n  readonly code: PinErrorCode;\n  constructor(code: PinErrorCode, detail: string) {\n    super(detail);\n    this.code = code;\n  }\n}\n\nconst toPinError = (cause: unknown): PinError => {\n  if (cause instanceof PinFailure) return pinError(cause.code, cause.message);\n  if (cause instanceof DOMException && cause.name === 'QuotaExceededError') return pinError('Quota', cause.message);\n  if (cause instanceof TypeError) return pinError('Offline', cause.message);\n  return pinError('Incomplete', String(cause));\n};\n\nexport type Pinned = {\n  readonly record: PinRecord;\n  /** Set on the first pin, when persistent storage was requested; null otherwise. */\n  readonly persisted: PersistResult | null;\n};\n\nconst pathsIn = async (cache: Cache): Promise<string[]> =>\n  (await cache.keys()).map((request) => new URL(request.url).pathname);\n\nconst fetchOk = async (ports: PinPorts, url: string, cache: RequestCache): Promise<Response> => {\n  const response = await ports.fetch(url, {\n    cache,\n    credentials: 'same-origin',\n    ...(cache === 'no-cache' ? { headers: { 'X-Joystyk-Pin-Refresh': '1' } } : {}),\n  });\n  if (!response.ok || response.redirected)\n    throw new PinFailure(\n      'Incomplete',\n      `${url}: HTTP ${String(response.status)}${response.redirected ? ' (redirected)' : ''}`,\n    );\n  return response;\n};\n\nconst loadManifest = async (\n  ports: PinPorts,\n  gameId: string,\n  assets: string,\n): Promise<{ manifest: GameAssetManifest; response: Response }> => {\n  const response = await fetchOk(ports, assets, 'no-cache').catch((cause: unknown) => {\n    throw cause instanceof PinFailure ? new PinFailure('Invalid', cause.message) : cause;\n  });\n  const raw: unknown = await response\n    .clone()\n    .json()\n    .catch(() => null);\n  const parsed = parseAssetManifest(raw);\n  if (!parsed.ok) throw new PinFailure('Invalid', `${assets}: ${parsed.error.join('; ')}`);\n  if (parsed.value.id !== gameId)\n    throw new PinFailure('Invalid', `${assets} describes ${parsed.value.id}, not ${gameId}`);\n  return { manifest: parsed.value, response };\n};\n\nconst pinOnce = async (ports: PinPorts, gameId: string, assets: string): Promise<Pinned> => {\n  const { manifest, response: manifestResponse } = await loadManifest(ports, gameId, assets);\n  const names = await ports.caches.keys();\n  const firstPin = !names.some((name) => parsePinnedCacheName(name) !== null);\n  const existing: { cacheName: string; paths: string[] }[] = [];\n  for (const name of names) {\n    if (parsePinnedCacheName(name)?.id === gameId)\n      existing.push({ cacheName: name, paths: await pathsIn(await ports.caches.open(name)) });\n  }\n  const target = pinnedCacheName(manifest.id, manifest.version);\n  const created = !names.includes(target);\n  const plan = planPin(manifest, assets, target, existing, PIN_RECORD_PATH);\n  const key = (path: string): string => new URL(path, ports.origin).href;\n  const cache = await ports.caches.open(target);\n  try {\n    // Hashed files first: they never change, so the browser's HTTP cache may answer.\n    for (const url of plan.fetch) await cache.put(key(url), await fetchOk(ports, url, 'default'));\n    // Then the pages, fresh. A deploy between reading the manifest and the page would leave a\n    // page naming files the pin lacks; refuse it, and the caller tries once more.\n    const files = new Set(manifest.files.map((file) => file.url));\n    const documents: [string, Response][] = [];\n    for (const url of plan.documents) {\n      documents.push([url, url === assets ? manifestResponse : await fetchOk(ports, url, 'no-cache')]);\n    }\n    const page = documents.find(([url]) => url === manifest.page)?.[1];\n    if (page !== undefined) {\n      const missing = referencedAssets(await page.clone().text()).filter((url) => !files.has(url));\n      if (missing.length > 0)\n        throw new PinFailure(\n          'Incomplete',\n          `${manifest.page} needs files the asset manifest doesn't list: ${missing.join(', ')}`,\n        );\n    }\n    for (const [url, response] of documents) await cache.put(key(url), response);\n    const record: PinRecord = {\n      id: manifest.id,\n      name: manifest.name,\n      version: manifest.version,\n      release: manifest.release,\n      page: manifest.page,\n      assets,\n      totalBytes: manifest.totalBytes,\n    };\n    await cache.put(\n      key(PIN_RECORD_PATH),\n      new Response(JSON.stringify(record), { headers: { 'content-type': 'application/json' } }),\n    );\n    // Only now, with the new build complete, drop what it replaced.\n    for (const url of plan.remove) await cache.delete(key(url));\n    for (const name of plan.dropCaches) await ports.caches.delete(name);\n    return { record, persisted: firstPin ? await ports.persist() : null };\n  } catch (cause) {\n    if (created) await ports.caches.delete(target);\n    throw cause;\n  }\n};\n\n/**\n * Makes a game available offline, or brings its pin up to date: reads the asset manifest at\n * `assets` (the game manifest's `assets`), caches every file and the game's page, then\n * removes older builds. The first pin asks for persistent storage.\n */\nexport const pinGame = async (\n  input: { readonly gameId: string; readonly assets: string },\n  ports: PinPorts = browserPinPorts(),\n): Promise<Result<Pinned, PinError>> => {\n  if ((ports.caches as CacheStorage | undefined) === undefined) return err(pinError('Unsupported', 'no Cache Storage'));\n  for (let attempt = 1; ; attempt += 1) {\n    try {\n      return ok(await pinOnce(ports, input.gameId, input.assets));\n    } catch (cause) {\n      const error = toPinError(cause);\n      if (error.code !== 'Incomplete' || attempt === 2) return err(error);\n    }\n  }\n};\n\n/**\n * Brings every pin up to the build the server has now: same version, missing files added and\n * stale ones dropped; a new version, a new cache, then the old one removed. Call it at a safe\n * point while online (Rule 2); a pin that fails to refresh keeps its old build.\n */\nexport const refreshPinnedGames = async (\n  ports: PinPorts = browserPinPorts(),\n): Promise<{ refreshed: string[]; failed: string[] }> => {\n  const refreshed: string[] = [];\n  const failed: string[] = [];\n  for (const record of await pinnedGames(ports)) {\n    const result = await pinGame({ gameId: record.id, assets: record.assets }, ports);\n    (result.ok ? refreshed : failed).push(record.id);\n  }\n  return { refreshed, failed };\n};\n"],"mappings":"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"}

package/dist/client/register.d.ts

@@ -0,0 +1,64 @@
+import { type SecurityNotice } from './forced.js';
+/** A daily game's content client, as `@joystyk/daily/browser`'s `createDailyClient` makes it. */
+export type DailyPrefetcher = {
+    readonly gameId: string;
+    prefetch(today: string): Promise<unknown>;
+};
+/** How the page shows "Update ready". The default is `<jy-update-toast>`. */
+export interface UpdatePrompt {
+    show(choose: (choice: 'refresh' | 'later') => void): void;
+    hide(): void;
+}
+export type PwaOptions = {
+    /** This build's release ID, for diagnostics. */
+    readonly release: string;
+    /**
+     * Subscribes to safe-point reports: pass the launcher's `watchSafePoints`
+     * (`@joystyk/launcher/browser`). Without it, every moment counts as safe.
+     */
+    readonly watchSafePoints?: (listener: (detail: {
+        readonly safe: boolean;
+    }) => void) => () => void;
+    /** How often to look for a new worker. Default 45 minutes, as the blog does. */
+    readonly updateCheckMs?: number;
+    /**
+     * The daily games' content clients. At a safe point, an installed app prefetches every
+     * daily game, and a browser tab only the pinned ones (D-46: today and tomorrow, no further).
+     */
+    readonly daily?: readonly DailyPrefetcher[];
+    readonly prompt?: UpdatePrompt;
+    /**
+     * When this release's code was committed (`__JOYSTYK_RELEASE_TIME__`). With it, the page
+     * honors the flag file's minimum release and forces a security update when it is older.
+     */
+    readonly releaseTime?: string;
+    /** Saves the game in play before a forced update: pass the launcher's `requestSave`. */
+    readonly saveGame?: () => Promise<void>;
+    /** How often to read the flag file for a minimum release. Default 15 minutes. */
+    readonly controlCheckMs?: number;
+    readonly securityNotice?: SecurityNotice;
+};
+export interface PwaController {
+    /** The release this page runs. */
+    readonly release: string;
+    /** The registration, or null without a worker (unsupported, failed, or switched off). */
+    readonly ready: Promise<ServiceWorkerRegistration | null>;
+    /** Looks for a new worker now. */
+    checkForUpdate(): Promise<void>;
+    dispose(): void;
+}
+/** The daily games to prefetch: all of them in an installed app, otherwise the pinned ones. */
+export declare const dailyToPrefetch: (prefetchers: readonly DailyPrefetcher[], context: {
+    readonly installed: boolean;
+    readonly pinned: readonly string[];
+}) => DailyPrefetcher[];
+/** Unregisters every worker of this origin and deletes the PWA's caches. Saves are untouched. */
+export declare const disablePwa: () => Promise<void>;
+/** The default prompt: `<jy-update-toast>` at the end of the body. */
+export declare const toastPrompt: () => UpdatePrompt;
+/**
+ * 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.
+ */
+export declare const registerPwa: (options: PwaOptions) => PwaController;