@moku-labs/game 0.9.0 → 0.10.0

package/README.md

@@ -15,7 +15,7 @@ You write small nodes and edge tables. The engine runs them, saves on the edges
 
 <br/>
 
-[Why](#why) · [Status](#status) · [Install](#install) · [Quick start](#quick-start) · [How it works](#how-it-works) · [Plugins](#plugins) · [Docs](#docs)
+[Why](#why) · [Status](#status) · [Install](#install) · [Quick start](#quick-start) · [Game shell](#game-shell) · [How it works](#how-it-works) · [Plugins](#plugins) · [Docs](#docs)
 
 ---
 
@@ -55,9 +55,11 @@ bun add @moku-labs/game pixi.js
 > [!IMPORTANT]
 > Bun only. ESM only. There is no CJS build. `pixi.js` `^8.0.0` is a peer dependency. Screens are `.tsx`, so a game sets `"jsx": "react-jsx"` and `"jsxImportSource": "@moku-labs/game"`.
 
+A game in a native shell adds the optional peers: `bun add @moku-labs/system` for the system plugins and the store save, `bun add -d @moku-labs/native` for the native build. A web-only game installs neither.
+
 ## Quick start
 
-A dice game in three files: one rest node, one working node, one flow.
+A dice game in a folder: one rest node, one working node, one flow, then the game and its page as data.
 
 ```ts
 // state.ts: bind the helpers to the types of the game
@@ -94,30 +96,81 @@ export const mainFlow = defineFlow("main", {
 });
 ```
 
+A game in two files: `index.ts` is the game as one data object, `config.ts` the page as plain data.
+
 ```ts
-// game.test.ts: play it with no screen
-import { createApp } from "@moku-labs/game";
-import { createHeadless } from "@moku-labs/game/testing";
+// index.ts: the game as one data object
+import { defineGameApp } from "@moku-labs/game/app";
 import { mainFlow } from "./flow";
 
-const app = createApp({
-  pluginConfigs: {
-    model: { initialPlayer: { coins: 0 }, initialSession: { rolls: 0 }, seed: 42 },
-    flow: { mainFlow, safeNode: "home" }
-  },
-  onStart: ctx => {
-    ctx.flow.run().catch((error: unknown) => ctx.log.error("game: the graph failed", { error }));
-  }
+export default defineGameApp({
+  flow: mainFlow,
+  safeNode: "home",
+  player: { coins: 0 },
+  session: { rolls: 0 }
 });
+```
+
+```ts
+// config.ts: the page, as plain data
+import type { GameConfig } from "@moku-labs/game/app";
+
+export default { page: { title: "Dice" } } satisfies GameConfig;
+```
+
+Tests make the app with `game.headless()` or `game.screen()`, not started, on a fake clock and an in-memory save:
+
+```ts
+// game.test.ts: play it with no screen
+import { createHeadless } from "@moku-labs/game/testing";
+import game from "./index";
 
-const game = await createHeadless(app);
-await game.walk([{ at: "home", intent: "roll" }, { at: "home", intent: "roll" }]);
+const { app } = game.headless();
+const run = await createHeadless(app);
+
+await run.walk([{ at: "home", intent: "roll" }, { at: "home", intent: "roll" }]);
 app.model.store.snapshot().session; // { rolls: 2 }
 ```
 
-The full version, with a reset node and a vitest file, is in [docs/quick-start.md](./docs/quick-start.md). A bigger game, the merge game, lives in [moku-labs/demos](https://github.com/moku-labs/demos) with its tests.
+`bunx moku-game dev` serves it with hot reload on `http://localhost:3000/`. The full version, with a reset node and a vitest file, is in [docs/quick-start.md](./docs/quick-start.md). A bigger game, the merge game, lives in [moku-labs/demos](https://github.com/moku-labs/demos) with its tests.
+
+A game with a screen gets two more things from the package. The body font `fonts/font-body.*` (Pangolin, SIL OFL 1.1) is the default of the built-in text style `body` once copied into `features/ui/assets/`. `moku-game keys` writes the typed asset keys, the manifest and the strings. Both are in [docs/quick-start.md](./docs/quick-start.md#a-screen-the-body-font-and-the-asset-keys).
+
+## Game shell
+
+The engine bin `moku-game` serves, builds and packs a game folder. A game writes no page, no server, no bridge and no `bunfig.toml`.
+
+| Path | Holds |
+|---|---|
+| `index.ts` | `export default defineGameApp({ ... })` |
+| `config.ts` | `page`, `native`, `system`, `save`, `assets`: plain data that `satisfies GameConfig` |
+| `core/`, `shared/`, `features/`, `plugins/` | The kit, the shared layer, the features, the game's plugins |
+| `tests/` | The tests. `tests/scenarios/<name>.ts` are the saves of `?player=<name>` on the dev page |
+| `.moku/` | What `moku-game` writes. Add `.moku/` to `.gitignore` |
+
+```json
+{
+  "scripts": {
+    "dev": "moku-game dev",
+    "build": "moku-game build",
+    "native:ios-sim": "moku-game native build ios --simulator"
+  }
+}
+```
+
+| Command | Does |
+|---|---|
+| `moku-game dev [--port 3000] [--packed]` | Serves the game with hot reload. Prints the bound URL, also for `--port 0` |
+| `moku-game build [--out dist/web]` | Packs the assets and builds the production page |
+| `moku-game native build <target> [--simulator]` | Builds the native app: `ios`, `macos`, `android` |
+| `moku-game native dev <target>` | Runs the native shell on the dev server |
+| `moku-game native doctor`, `native clean` | Checks or removes the native project |
+| `moku-game keys [--check]` | Writes `generated/assets.ts`, the strings and `manifest.json` |
+| `moku-game pack [--no-cache]` | Packs the assets into `dist/assets` |
+
+Every command takes `--root <dir>`, `--preload <path>` and `--serve-plugin <path>`.
 
-A game with a screen gets two more things from the package. The body font `fonts/font-body.*` (Pangolin, SIL OFL 1.1) is the default of the built-in text style `body` once copied into `src/features/ui/assets/`. The bin `moku-game-assets` writes the typed asset keys, the manifest and the strings. It runs under bun; with node only, run `bun node_modules/@moku-labs/game/dist/assets.mjs`. Both are in [docs/quick-start.md](./docs/quick-start.md#a-screen-the-body-font-and-the-asset-keys).
+`config.ts` names the system plugins the page wires, `system: ["lifecycle", "back", "haptics", "keepAwake"]`, and the save, `save: "memory" | "local" | "store"`. A `system` list and the `"store"` save need the optional peer `@moku-labs/system`; `moku-game native` needs `@moku-labs/native`. The game imports neither. The whole shell is in [docs/shell.md](./docs/shell.md).
 
 ## How it works
 
@@ -188,12 +241,16 @@ createApp({ plugins: [...screen, effectsPlugin, audioPlugin, platformPlugin] });
 | Import | Runs in | For |
 |---|---|---|
 | `@moku-labs/game` | anywhere | The engine: plugins, helpers, components |
+| `@moku-labs/game/app` | anywhere | `defineGameApp`, `startMoment` and the types of `index.ts` and `config.ts`. See [The game shell](./docs/shell.md) |
+| `@moku-labs/game/app/page` | the browser | `startPage`, the page the generated `.moku/main.ts` calls |
+| `@moku-labs/game/app/system` | the browser, the native shell | The system shell over the optional peer `@moku-labs/system` |
+| `@moku-labs/game/cli` | Node and Bun | `runCli`, the bin `moku-game`; `preparePage`, the dev page for the editor |
 | `@moku-labs/game/testing` | anywhere | Headless and isolated games, the fake clock, the in-memory save |
 | `@moku-labs/game/visual` | Node and Bun | Visual tests: baselines of state, describe and pixels |
 | `@moku-labs/game/assets` | Node and Bun | Asset keys, the manifest, strings, the pack |
 | `@moku-labs/game/inspect` | anywhere | Read a running game |
 | `@moku-labs/game/control` | dev builds | Drive a running game |
-| `@moku-labs/game/hot` | the Bun dev server | The `bunfig.toml` plugin that hot swaps views. See [Hot swap](./docs/hot-swap.md) |
+| `@moku-labs/game/hot` | the Bun dev server | The Bun plugin that hot swaps views. `moku-game dev` lists it. See [Hot swap](./docs/hot-swap.md) |
 | `@moku-labs/game/lint` | oxlint | The game lint rules, as an oxlint JS plugin |
 | `@moku-labs/game/project` | Node and Bun | Where every engine id of a game is defined, line fresh at the call. The bin `moku-game-index`. See [Project index](./docs/project-index.md) |
 | `@moku-labs/game/jsx-runtime`, `/jsx-dev-runtime` | anywhere | The JSX runtime. A game never imports it by hand. |
@@ -228,6 +285,7 @@ Each rule takes `{ "files": [...], "ignores": [...] }`. `layer-imports`, `featur
 | Page | What is inside |
 |---|---|
 | [Quick start](./docs/quick-start.md) | The full dice game, step by step |
+| [The game shell](./docs/shell.md) | `defineGameApp`, `config.ts`, the page, the save, system and native, the `moku-game` commands |
 | [Plugins](./docs/plugins.md) | The dependency graph, the plugin table, every root export |
 | [Interface in JSX](./docs/jsx.md) | Tags, components, styles, popups |
 | [Doors for the editor](./docs/doors.md) | `/inspect` and `/control`, base sources and commands |
@@ -236,7 +294,7 @@ Each rule takes `{ "files": [...], "ignores": [...] }`. `layer-imports`, `featur
 | [Configuration](./docs/configuration.md) | Every config field and its default |
 | [Lint for games](./docs/lint.md) | The `moku-game` oxlint rules, their options and defaults |
 | [Project index](./docs/project-index.md) | `openProject`, the key scheme, `find` and `watch`, the `moku-game-index` bin |
-| [Testing](./docs/testing.md) | Headless, isolated and visual tests, all scripts, test layout, lint rules |
+| [Testing](./docs/testing.md) | `game.headless()` and `game.screen()`, headless, isolated and visual tests, all scripts, test layout, lint rules |
 | [`llms.txt`](./llms.txt) | The engine in one page, for an AI that writes a game |
 
 Each plugin has its own README, linked in the table above. The kernel is specified in the [Moku Core specification](https://github.com/moku-labs/core/tree/main/specification).
@@ -250,7 +308,8 @@ bun run lint             # biome check . && eslint .
 bun run test             # vitest, unit and integration
 bun run test:coverage    # with the 90% threshold
 bun run validate         # publint and attw
-bun run mini:pack        # pack the mini game of tests/fixtures
+bun run mini:dev         # moku-game dev of the mini game of tests/fixtures
+bun run mini:pack        # moku-game pack of the mini game
 bun run mini:visual      # visual tests of the mini game
 bun run release          # moku-release
 ```
@@ -259,7 +318,7 @@ Every script is in [docs/testing.md](./docs/testing.md#scripts).
 
 ### Hot swap
 
-A save of a view file swaps it in the running page, with the same state. One line in the game's `bunfig.toml`:
+A save of a view file swaps it in the running page, with the same state. `moku-game dev` lists the plugin in the bunfig it writes, so a game sets nothing. A game with a server of its own lists it in its `bunfig.toml`:
 
 ```toml
 [serve.static]
@@ -272,7 +331,7 @@ A save of a logic file reloads the page. What swaps and what reloads: [docs/hot-
 
 - **Node `>= 24`** and **Bun `>= 1.3.14`**. Use `bun` only.
 - **TypeScript** in strict mode, with `exactOptionalPropertyTypes` and `noUncheckedIndexedAccess`.
-- **`pixi.js` `^8.0.0`** as a peer dependency. `playwright-core` for visual tests, `sharp` for the asset pack and `typescript` for the project index are optional peers. `yoga-layout` is loaded lazily by `ui`. The string compiler uses `@formatjs/icu-messageformat-parser` at build time only.
+- **`pixi.js` `^8.0.0`** as a peer dependency. `playwright-core` for visual tests, `sharp` for the asset pack, `typescript` for the project index, `@moku-labs/system` for the system shell and `@moku-labs/native` for the native build are optional peers. `yoga-layout` is loaded lazily by `ui`. The string compiler uses `@formatjs/icu-messageformat-parser` at build time only.
 - **[`@moku-labs/core`](https://github.com/moku-labs/core)** is the kernel. **[`@moku-labs/common`](https://github.com/moku-labs/common)** brings `log` and `env`.
 
 ## License

package/bin/moku-game.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { runCli } from "../dist/cli.mjs";
+
+process.exitCode = await runCli(process.argv.slice(2));

package/dist/app/page.d.mts

@@ -0,0 +1,41 @@
+import { h as StartedPage, r as GameConfig, t as AnyGameApp, u as PageOptions } from "../types-hQgI_wrq.mjs";
+
+//#region src/app/page.d.ts
+/**
+ * Runs a game on its page: resolves `config.ts`, picks the start (a `?player=` scenario runs on a
+ * fresh memory save, never on the stored one), builds the system shell when the page has one,
+ * picks the save, makes the screen app on `#game` over the device clock and the manifest next to
+ * the page, sets `globalThis.game`, `system` and `doors`, follows reduced motion, starts the shell,
+ * then the app, and runs the graph. A graph that stops is logged, never thrown. In dev it then
+ * starts the agents. Every problem goes to the app's log.
+ *
+ * @param game - The default export of the game's `index.ts`.
+ * @param config - The default export of the game's `config.ts`.
+ * @param options - What the CLI found: scenarios, the shell factory, agents, `.dev` modules.
+ * @returns The running screen app, and the system app for `globalThis.system`.
+ * @throws {Error} When `config.ts` holds a value TypeScript would refuse, or the save is `"store"`
+ * and the page has no system shell.
+ * @example
+ * ```ts
+ * // Written by moku-game dev. Do not edit.
+ * import "./dev.ts";
+ * import { startPage } from "@moku-labs/game/app/page";
+ * import { systemShell } from "@moku-labs/game/app/system";
+ * import game from "../index.ts";
+ * import config from "../config.ts";
+ * import scenario0 from "../tests/scenarios/empty.ts";
+ * import scenario1 from "../tests/scenarios/full.ts";
+ * import * as devModule0 from "../features/board/board.dev.ts";
+ * import agent0 from "@moku-labs/editor/agent/page";
+ *
+ * await startPage(game, config, {
+ *   scenarios: { "empty": scenario0, "full": scenario1 },
+ *   system: systemShell,
+ *   agents: [agent0],
+ *   devModules: [devModule0]
+ * });
+ * ```
+ */
+declare function startPage<Game extends AnyGameApp>(game: Game, config: GameConfig, options?: PageOptions): Promise<StartedPage<Game>>;
+//#endregion
+export { startPage };

package/dist/app/page.mjs

@@ -0,0 +1,376 @@
+import { r as systemSource, t as memory } from "../memory-CWlqhS7l.mjs";
+import { t as applyTo } from "../drafts-BawpSaVp.mjs";
+import { n as read, r as watch, t as sources } from "../sources-Duzj6lhV.mjs";
+import { t as resolveConfig } from "../config-CdARrrhU.mjs";
+//#region src/app/save.ts
+/**
+* @file The saves of the page: `localSave` keeps the player in `localStorage`, `pageSave` picks
+* the save `config.save` names. The store save is the system shell's (`storeSave` of
+* `./system`): this file imports no system code, so a web-only page bundles none. Not exported
+* from any entry: the page is the one caller.
+*/
+/**
+* Tells whether a JSON value is an object, not an array or `null`.
+*
+* @param value - A JSON value.
+* @returns True for a JSON object.
+* @example
+* ```ts
+* isDocument([1, 2]); // false
+* ```
+*/
+function isDocument(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Tells whether a parsed JSON value is a save: a document under `state` and a number under
+* `version`.
+*
+* @param value - The parsed text.
+* @returns True for a save.
+* @example
+* ```ts
+* isStored({ state: {}, version: "1" }); // false
+* ```
+*/
+function isStored(value) {
+	return isDocument(value) && isDocument(value.state) && typeof value.version === "number";
+}
+/**
+* Reads the stored text as a save: the document and its schema version.
+*
+* @param text - What `localStorage` holds under the key.
+* @returns The save, or `undefined` when the text is not JSON or not a save.
+* @example
+* ```ts
+* parseStored('{ "state": {}, "version": 1 }'); // { state: {}, version: 1 }
+* ```
+*/
+function parseStored(text) {
+	try {
+		const value = JSON.parse(text);
+		return isStored(value) ? {
+			state: value.state,
+			version: value.version
+		} : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Says what a failed write threw, without a closing period: the sentence adds its own.
+*
+* @param thrown - What `setItem` threw.
+* @returns The message.
+* @example
+* ```ts
+* reasonOf(new Error("The quota has been exceeded.")); // "The quota has been exceeded"
+* ```
+*/
+function reasonOf(thrown) {
+	const message = thrown instanceof Error ? thrown.message : String(thrown);
+	return message.endsWith(".") ? message.slice(0, -1) : message;
+}
+/**
+* Tries `localStorage` once: a write and a removal of a probe key.
+*
+* @param key - The key of the save.
+* @returns The storage, or `undefined` when the page has none or it refuses.
+*/
+function probeStorage(key) {
+	try {
+		const storage = globalThis.localStorage;
+		storage.setItem(`${key}:probe`, "1");
+		storage.removeItem(`${key}:probe`);
+		return storage;
+	} catch {
+		return;
+	}
+}
+/**
+* Makes the save that keeps the player in `localStorage` under one key. Each commit applies its
+* patches to the held document and writes the whole value at once: the value is small and the
+* write is synchronous, so nothing is pending and `flush` has nothing to do. A page with no
+* `localStorage`, or one that refuses a write (private mode, site data off), gets a memory save
+* and a report.
+*
+* @param key - The key of the save, `<namespace>:save`.
+* @param report - Where a problem goes: the app's warn log once the app exists.
+* @returns The save provider.
+*/
+function localSave(key, report) {
+	const storage = probeStorage(key);
+	if (storage === void 0) {
+		report("[game] localStorage is not available, so the save lives in memory.\n  Progress is lost when the page closes.");
+		return memory();
+	}
+	const held = { document: void 0 };
+	/**
+	* Applies one commit to the held document and writes the whole value.
+	*
+	* @param patches - The patches of the commit.
+	* @param version - The schema version this build writes.
+	* @returns The sentence of a failed write, or `undefined` when the value is written.
+	*/
+	const write = (patches, version) => {
+		const document = applyTo(held.document ?? {}, patches);
+		const value = {
+			state: document,
+			version
+		};
+		held.document = document;
+		try {
+			storage.setItem(key, JSON.stringify(value));
+			return;
+		} catch (error) {
+			return `[game] The local save was not written: ${reasonOf(error)}.\n  Free browser storage; progress since the last write is lost on close.`;
+		}
+	};
+	return {
+		load: async () => {
+			const text = storage.getItem(key);
+			if (text === null) return null;
+			const stored = parseStored(text);
+			if (stored === void 0) throw new Error(`[game] The local save is not JSON.\n  Clear the site data or the key "${key}".`);
+			held.document = stored.state;
+			return stored;
+		},
+		commit: (patches, version) => {
+			const failure = write(patches, version);
+			if (failure !== void 0) report(failure);
+		},
+		commitDurable: async (patches, _txId, version) => {
+			const failure = write(patches, version);
+			if (failure !== void 0) throw new Error(failure);
+		},
+		flush: () => Promise.resolve()
+	};
+}
+/**
+* Picks the save `config.save` names: a fresh memory save, the local save under
+* `<namespace>:save`, or the system shell's store save.
+*
+* @param kind - The save kind of the resolved config.
+* @param where - The key prefix, the shell and the reporter.
+* @returns The save provider of the page.
+* @throws {Error} When the kind is `"store"` and the page has no shell with a store save.
+*/
+function pageSave(kind, where) {
+	switch (kind) {
+		case "memory": return memory();
+		case "local": return localSave(`${where.namespace}:save`, where.report);
+		case "store":
+			if (where.shell?.save === void 0) throw new Error("[game] config.save is \"store\", but the page has no system shell.\n  Run moku-game dev or build again: it passes the shell when config.ts names save \"store\".");
+			return where.shell.save;
+	}
+}
+//#endregion
+//#region src/app/page.ts
+/**
+* @file The `@moku-labs/game/app/page` entry: `startPage`, the page of a game. The generated
+* `.moku/main.ts` calls it with the game, its config and what the CLI found: scenarios, the system
+* shell, the dev agents and the `.dev` modules. It reaches the shell only through
+* `options.system`, never by an import, so a web-only page bundles no system code. Its dev parts
+* (the write door `/control`, the agents, the audio journal) sit behind the inline dev guard, so a
+* production build drops them.
+*/
+/** How many started sounds the audio journal of the dev page keeps. */
+const DEV_AUDIO_JOURNAL = 200;
+/**
+* Makes the reporter of the page: a problem found before the app exists (the scenario, the shell)
+* waits for the app's log.
+*
+* @returns The reporter.
+*/
+function lateReporter() {
+	const kept = [];
+	const sink = { log: void 0 };
+	return {
+		report: (problem) => {
+			if (sink.log === void 0) kept.push(problem);
+			else sink.log.warn(problem);
+		},
+		attach: (log) => {
+			sink.log = log;
+			for (const problem of kept.splice(0)) log.warn(problem);
+		}
+	};
+}
+/**
+* Turns anything thrown into an `Error` for the log.
+*
+* @param thrown - What was thrown or rejected.
+* @returns The error itself, or an error with its text.
+* @example
+* ```ts
+* toError("no bridge").message; // "no bridge"
+* ```
+*/
+function toError(thrown) {
+	return thrown instanceof Error ? thrown : new Error(String(thrown));
+}
+/**
+* Picks the start of the page from `?player=`: the named scenario's player and session, at the
+* device time. An unknown name is reported, and the page starts from the starting player.
+*
+* @param name - The value of `?player=`, or `null` without it.
+* @param scenarios - The scenarios of the page, by name.
+* @param now - The device time.
+* @param report - Where the unknown name goes.
+* @returns The player and session of the scenario, or `undefined`.
+*/
+function scenarioStart(name, scenarios, now, report) {
+	if (name === null) return void 0;
+	const scenario = scenarios[name];
+	if (scenario !== void 0) return scenario(now);
+	report(`[game] No scenario "${name}".\n  Known: ${Object.keys(scenarios).join(", ") || "none"}. The page starts from the starting player.`);
+}
+/**
+* Makes the screen app of the page: the canvas on `#game`, the manifest next to the page, the
+* shell's platform, the save, the device clock, and the scenario's start when one is named.
+*
+* @param game - The game.
+* @param runtime - What the app runs on.
+* @returns The app, not started.
+*/
+function screenOf(game, runtime) {
+	const { settings, query, shell, start } = runtime;
+	return game.screen({
+		manifest: new URL("manifest.json", location.href).href,
+		renderer: {
+			mount: "#game",
+			...query.get("renderer") === "webgl" ? { preference: "webgl" } : {}
+		},
+		...shell === void 0 ? {} : { platform: shell.platform },
+		keepAwake: settings.system.includes("keepAwake"),
+		provider: runtime.provider,
+		...start === void 0 ? {} : { player: start.player },
+		...start?.session === void 0 ? {} : { session: start.session },
+		clock: runtime.clock,
+		audio: typeof __MOKU_GAME_DEV__ !== "undefined" && __MOKU_GAME_DEV__ ? { journal: DEV_AUDIO_JOURNAL } : {}
+	}).app;
+}
+/**
+* Sets the three handles of the page on `globalThis`: `game` for e2e, `system` for the shell,
+* `doors` for the editor. The write door `/control` is loaded in dev only.
+*
+* @param app - The screen app.
+* @param shell - The system shell, or `undefined`.
+* @returns Resolves when the handles are set.
+*/
+async function setHandles(app, shell) {
+	Reflect.set(globalThis, "game", app);
+	Reflect.set(globalThis, "system", shell?.handle);
+	const control = typeof __MOKU_GAME_DEV__ !== "undefined" && __MOKU_GAME_DEV__ ? await import("../control.mjs") : void 0;
+	Reflect.set(globalThis, "doors", {
+		read,
+		watch,
+		sources,
+		...control === void 0 ? {} : {
+			run: control.run,
+			commands: control.commands
+		}
+	});
+}
+/**
+* Follows the system setting of reduced motion, also when the player changes it while the page
+* runs.
+*
+* @param app - The screen app.
+*/
+function followReducedMotion(app) {
+	const reducedMotion = matchMedia("(prefers-reduced-motion: reduce)");
+	app.anim.setReducedMotion(reducedMotion.matches);
+	reducedMotion.addEventListener("change", (event) => app.anim.setReducedMotion(event.matches));
+}
+/**
+* Starts the dev agents, in order, after the app: each gets the app, the page title and the
+* game's `.dev` modules. A throwing agent is logged and the page keeps running.
+*
+* @param app - The running app.
+* @param settings - The resolved config.
+* @param options - The agents and the dev modules.
+* @returns Resolves when every agent started or failed.
+*/
+async function startAgents(app, settings, options) {
+	for (const agent of options.agents ?? []) try {
+		await agent({
+			app,
+			name: settings.page.title,
+			modules: options.devModules ?? []
+		});
+	} catch (error) {
+		app.log.error("[game] A page agent failed to start.", void 0, toError(error));
+	}
+}
+/**
+* Runs a game on its page: resolves `config.ts`, picks the start (a `?player=` scenario runs on a
+* fresh memory save, never on the stored one), builds the system shell when the page has one,
+* picks the save, makes the screen app on `#game` over the device clock and the manifest next to
+* the page, sets `globalThis.game`, `system` and `doors`, follows reduced motion, starts the shell,
+* then the app, and runs the graph. A graph that stops is logged, never thrown. In dev it then
+* starts the agents. Every problem goes to the app's log.
+*
+* @param game - The default export of the game's `index.ts`.
+* @param config - The default export of the game's `config.ts`.
+* @param options - What the CLI found: scenarios, the shell factory, agents, `.dev` modules.
+* @returns The running screen app, and the system app for `globalThis.system`.
+* @throws {Error} When `config.ts` holds a value TypeScript would refuse, or the save is `"store"`
+* and the page has no system shell.
+* @example
+* ```ts
+* // Written by moku-game dev. Do not edit.
+* import "./dev.ts";
+* import { startPage } from "@moku-labs/game/app/page";
+* import { systemShell } from "@moku-labs/game/app/system";
+* import game from "../index.ts";
+* import config from "../config.ts";
+* import scenario0 from "../tests/scenarios/empty.ts";
+* import scenario1 from "../tests/scenarios/full.ts";
+* import * as devModule0 from "../features/board/board.dev.ts";
+* import agent0 from "@moku-labs/editor/agent/page";
+*
+* await startPage(game, config, {
+*   scenarios: { "empty": scenario0, "full": scenario1 },
+*   system: systemShell,
+*   agents: [agent0],
+*   devModules: [devModule0]
+* });
+* ```
+*/
+async function startPage(game, config, options = {}) {
+	const settings = resolveConfig(config);
+	const query = new URLSearchParams(location.search);
+	const { report, attach } = lateReporter();
+	const clock = systemSource();
+	const start = scenarioStart(query.get("player"), options.scenarios ?? {}, clock.now(), report);
+	const shell = options.system === void 0 ? void 0 : await options.system(settings, report);
+	const namespace = settings.native?.identifier ?? "moku-game";
+	const app = screenOf(game, {
+		settings,
+		query,
+		clock,
+		shell,
+		provider: start === void 0 ? pageSave(settings.save, {
+			namespace,
+			shell,
+			report
+		}) : memory(),
+		start
+	});
+	attach(app.log);
+	await setHandles(app, shell);
+	followReducedMotion(app);
+	await shell?.start();
+	await app.start();
+	app.flow.run().catch((error) => {
+		app.log.error("[game] The graph stopped.", void 0, toError(error));
+	});
+	if (typeof __MOKU_GAME_DEV__ !== "undefined" && __MOKU_GAME_DEV__) await startAgents(app, settings, options);
+	return {
+		app,
+		system: shell?.handle
+	};
+}
+//#endregion
+export { startPage };