@moku-labs/game 0.7.0 → 0.8.0

package/dist/{run-Bcyg32M5.mjs → run-CUPSFM85.mjs}

@@ -1,190 +1,7 @@
-import { a as sheetAlone, u as graphHash } from "./capture-fpd83Mi5.mjs";
+import { a as sheetAlone } from "./capture-BX5Gfoty.mjs";
 import { n as isDev, r as notInstalled, t as controlRefused } from "./dev-wKLgOw7c.mjs";
-import { a as isProjectionTarget, i as recordCheat, o as readTarget, r as isTainted, s as defineCommand, t as inputOrEmpty } from "./input-CK4nxBO1.mjs";
-//#region src/plugins/flow/headless.ts
-const noPayload = null;
-/** Seed of a repro that pins no rng state, the seed `saveOf` writes. */
-const defaultSeed = 1;
-/**
-* Turns whatever `run()` rejected with into an error that can be thrown again.
-*
-* @param value - The rejection value.
-* @returns The value itself when it is an error, a wrapped one otherwise.
-* @example
-* ```ts
-* asError("offline").message; // "[game] The headless run failed.\n  offline."
-* ```
-*/
-function asError(value) {
-	if (value instanceof Error) return value;
-	return /* @__PURE__ */ new Error(`[game] The headless run failed.\n  ${String(value)}.`);
-}
-/**
-* Starts the one loop unless the app's own `onStart` already did, and keeps a fatal error until
-* someone asks for it. `run()` rejects only on a fatal error, and nobody awaits it here.
-*
-* @param app - The started app.
-* @returns The holder of the fatal error.
-*/
-function startLoop(app) {
-	const fatal = { error: void 0 };
-	if (app.flow.state().running) return fatal;
-	app.flow.run().catch((error) => {
-		fatal.error = error;
-	});
-	return fatal;
-}
-/**
-* Waits until the loop rests for the first time, or ends. An empty route walks nowhere: it only
-* waits for the gate the loop opens at the node it enters, so a start that is a chain of transit
-* nodes is played out before anything reads the game.
-*
-* @param app - The started app whose loop is running.
-* @param fatal - Holder of the fatal error of `run()`.
-* @returns Resolves once the loop rests at its first rest node.
-* @throws {Error} When the loop failed fatally instead of reaching a rest node.
-*/
-async function settleAtFirstRest(app, fatal) {
-	await app.flow.walk([]).catch((error) => {
-		throw asError(fatal.error ?? error);
-	});
-	if (fatal.error !== void 0) throw asError(fatal.error);
-}
-/**
-* Starts an app headless: sets flow mode `"fast"`, awaits `app.start()`, starts `flow.run()`
-* unless the app's own `onStart` already did, and waits until the loop rests for the first time.
-* `game.state().path` therefore names the first rest node of the graph as soon as the call
-* resolves. A fatal error of the loop rejects this call, and a later one is re-thrown by `walk`
-* and by `stop`, so a headless test never loses it.
-*
-* @param app - An app that is not started yet.
-* @returns The game: walk it, answer it, read it, stop it.
-* @throws {Error} When the loop failed fatally before it reached its first rest node.
-* @example
-* ```ts
-* // A test starts the merge game without a screen. The call resolves at the first rest node.
-* const game = await createHeadless(app);
-*
-* game.state().path; // "home": the transit node "boot" was played out
-* game.state().mode; // "fast"
-* await game.stop();
-* ```
-*/
-async function createHeadless(app) {
-	app.flow.setMode("fast");
-	await app.start();
-	const fatal = startLoop(app);
-	await settleAtFirstRest(app, fatal);
-	return {
-		walk: async (route) => {
-			const state = await app.flow.walk(route).catch((error) => {
-				throw asError(fatal.error ?? error);
-			});
-			if (fatal.error !== void 0) throw asError(fatal.error);
-			return state;
-		},
-		answer: (answer) => app.flow.gate.answer(answer),
-		state: () => app.flow.state(),
-		history: () => app.flow.history(),
-		stop: async () => {
-			await app.stop();
-			if (fatal.error !== void 0) throw asError(fatal.error);
-		}
-	};
-}
-/**
-* Reads the rest node a repro starts at: its checkpoint, or the start of the main flow.
-*
-* @param app - The started app.
-* @param repro - Starting state, optional checkpoint and the route.
-* @returns The path of the node the repro enters.
-* @throws {Error} When the graph has no main flow to start from.
-*/
-function reproPath(app, repro) {
-	if (repro.checkpoint !== void 0) return repro.checkpoint;
-	const graph = app.flow.describe();
-	const start = graph.flows[graph.main]?.start;
-	if (start === void 0) throw new Error(`[game] runRepro() found no flow "${graph.main}" to start from.\n  Name the checkpoint the repro was taken at.`);
-	return start;
-}
-/**
-* Builds the bookmark a repro is entered with: its state, its checkpoint and the hash of the
-* graph that runs now, so a checkpoint is accepted and any other rest node is checked. The route
-* is not part of it: the caller walks it after the restore.
-*
-* @param app - The started app.
-* @param repro - Starting state, optional checkpoint and the route.
-* @returns The bookmark to restore.
-* @throws {Error} When the repro names no checkpoint and the graph has no main flow.
-* @example
-* ```ts
-* // The game.restore command loads a bug report taken at the "home" checkpoint.
-* const bookmark = reproBookmark(app, { player: { coins: 7 }, checkpoint: "home", route: [] });
-* bookmark.path; // "home"
-* bookmark.rng; // { seed: 1, streams: {} }: the repro pinned no rng
-* await app.flow.restore(bookmark);
-* ```
-*/
-function reproBookmark(app, repro) {
-	return {
-		path: reproPath(app, repro),
-		input: noPayload,
-		player: repro.player,
-		session: repro.session ?? {},
-		rng: repro.rng ?? {
-			seed: defaultSeed,
-			streams: {}
-		},
-		graph: graphHash(app.flow.describe())
-	};
-}
-/**
-* Plays a repro: starts the app headless, restores the bookmark built from its state and
-* checkpoint, then walks its route. The app keeps running, so the caller can read more than the
-* result and stops it itself.
-*
-* @param app - An app that is not started yet.
-* @param repro - Starting state, optional checkpoint and the route.
-* @returns The path the run ended at, and the committed state.
-* @example
-* ```ts
-* // A bug report on the dice game: "reset keeps my coins". Replay it from the "home" checkpoint.
-* const reset = { at: "home", intent: "reset" };
-* const result = await runRepro(app, { player: { coins: 7 }, checkpoint: "home", route: [reset] });
-*
-* result.player; // { coins: 0 }; result.path is ["home"]
-* await app.stop(); // the app keeps running after the run
-* ```
-*/
-async function runRepro(app, repro) {
-	const game = await createHeadless(app);
-	await app.flow.restore(reproBookmark(app, repro));
-	const state = await game.walk(repro.route);
-	const ended = app.flow.bookmark();
-	return {
-		path: state.stack.map((frame) => frame.node),
-		player: ended.player,
-		session: ended.session
-	};
-}
-/**
-* Steps the frame loop by hand: `count` calls of `app.time.step(deltaMs)`. A headless game has no
-* frame source, so this is the only thing that moves the frame phases.
-*
-* @param app - A started app.
-* @param count - Number of frames.
-* @param deltaMs - Milliseconds per frame.
-* @example
-* ```ts
-* // A headless game has no frame source: the test moves the six frame phases by hand.
-* stepFrames(app, 2, 16);
-* app.time.snapshot(); // frame: 2, delta: 16, elapsed: 32
-* ```
-*/
-function stepFrames(app, count, deltaMs) {
-	for (let frame = 0; frame < count; frame += 1) app.time.step(deltaMs);
-}
-//#endregion
+import { n as reproBookmark } from "./headless-CvamCUcR.mjs";
+import { a as isProjectionTarget, i as recordCheat, o as readTarget, r as isTainted, s as defineCommand, t as inputOrEmpty } from "./input-z_35Jwfn.mjs";
 //#region src/plugins/anim/control.ts
 /**
 * @file anim plugin — the anim command of the `/control` door: switch reduced motion. Dev builds
@@ -1282,4 +1099,4 @@ async function run(app, command, ...input) {
 	};
 }
 //#endregion
-export { stepFrames as a, runRepro as i, commands as n, createHeadless as r, run as t };
+export { commands as n, run as t };

package/dist/{runtime-HTlmRb81.d.mts → runtime-CvDZZg1S.d.mts}

@@ -1,4 +1,4 @@
-import { a as JsxChild, m as UiIntrinsicElements, t as DescriptionNode } from "./types-BaUUcIaN.mjs";
+import { a as JsxChild, m as UiIntrinsicElements, t as DescriptionNode } from "./types-DgdMLZnV.mjs";
 
 //#region src/plugins/ui/jsx/runtime.d.ts
 /** What the compiler passes as props: the children plus whatever the tag declared. */

package/dist/{sources-DVWJ8nfr.mjs → sources-BBUd15vQ.mjs}

@@ -1,6 +1,6 @@
 import { i as scaleByFits, w as Layer } from "./visual-DUvvPPCt.mjs";
 import { r as notInstalled } from "./dev-wKLgOw7c.mjs";
-import { c as defineSource, n as cheatsOf, o as readTarget, r as isTainted, t as inputOrEmpty } from "./input-CK4nxBO1.mjs";
+import { c as defineSource, n as cheatsOf, o as readTarget, r as isTainted, t as inputOrEmpty } from "./input-z_35Jwfn.mjs";
 //#region src/plugins/flow/doors/read.ts
 /**
 * @file flow/doors — `read` and `watch`, the `/inspect` side. Neither changes the game.

package/dist/testing.d.mts

@@ -1,8 +1,5 @@
-import { $t as SaveDoc, Kt as Json, Qt as ProviderCall, Ut as Api$2, Zt as PlayerStateProvider, an as Api$3, k as Api$1, m as Api, pn as FakeClock } from "./types-BMEn0tSC.mjs";
-import { _ as stepFrames, a as InputOf, d as HeadlessApp, f as HeadlessGame, g as runRepro, h as createHeadless, m as ReproResult, p as Repro, r as ControlApp } from "./types-CYYKjvLn.mjs";
-import { H as InputApi } from "./types-BaUUcIaN.mjs";
-import { b as AnimApi, v as UiApi } from "./types-CXyipKhE.mjs";
-import { t as commands } from "./commands-mzE9PX0H.mjs";
+import { G as SaveDoc, R as Json, U as PlayerStateProvider, W as ProviderCall, at as FakeClock } from "./types-ERb2Y9U5.mjs";
+import { a as createHeadless, i as ReproResult, n as HeadlessGame, o as runRepro, r as Repro, s as stepFrames, t as HeadlessApp } from "./headless-q98SwADR.mjs";
 
 //#region src/plugins/clock/fake.d.ts
 /**
@@ -73,326 +70,4 @@ declare function memory(fixture?: {
  */
 declare function saveOf(player: Json, seed?: number): SaveDoc;
 //#endregion
-//#region src/visual/types.d.ts
-/** The base commands of the `/control` door, keyed by their short names. */
-type Catalogue = typeof commands;
-/**
- * The commands a step may name: the catalogue of `/control` minus `bookmark` (it only reads),
- * `capture` (the runner captures by itself) and `debug` (debug drawing would enter a baseline). A
- * command the catalogue gains is a step with no change to the runner.
- *
- * @example
- * ```ts
- * const name: StepCommand = "tap"; // also "answer", "walk", "step", "reducedMotion", ...
- * ```
- */
-type StepCommand = Exclude<keyof Catalogue, "bookmark" | "capture" | "debug">;
-/**
- * Where a visual test starts: what `game.restore` loads, a repro without its route. The player
- * is required; the session, the rng and the checkpoint are optional, as in a repro.
- *
- * @example
- * ```ts
- * // A save with a plank ready for the first order, entered at Home.
- * const start: VisualStart = { player: { coins: 40, orders: [] }, checkpoint: "home" };
- * ```
- */
-type VisualStart = Omit<Repro, "route">;
-/**
- * One step of a visual test: a `/control` command by its short name with that command's input,
- * typed from the catalogue, or a checkpoint by its name.
- *
- * @example
- * ```ts
- * // Tap Play, answer the order on the board, then compare the screen with its baseline.
- * const steps: VisualStep[] = [
- *   { tap: { key: "play" } },
- *   { answer: { intent: "deliver", payload: { orderId: "o1" } } },
- *   { checkpoint: "open" }
- * ];
- * ```
- */
-type VisualStep = {
-  checkpoint: string;
-} | { [K in StepCommand]: { [P in K]: InputOf<Catalogue[K]["input"]> } }[StepCommand];
-/**
- * A visual test as `defineVisualTest` answers it: its name, where it starts, its steps, and
- * `webgl`, true when it also runs in the WebGL leg. Frozen data; nothing runs at definition.
- *
- * @example
- * ```ts
- * const test: VisualTest = defineVisualTest("reward-popup", {
- *   start: { player: { coins: 40 }, checkpoint: "home" },
- *   steps: [{ tap: { key: "play" } }, { checkpoint: "board" }]
- * });
- * test.name; // "reward-popup"
- * test.webgl; // false
- * Object.isFrozen(test.steps); // true
- * ```
- */
-type VisualTest = {
-  readonly name: string;
-  readonly start: Readonly<VisualStart>;
-  readonly steps: readonly VisualStep[];
-  readonly webgl: boolean;
-};
-/**
- * What the runner needs of an app: the control app, the plugins the base commands act on and
- * the plugins the readers read. Every app composed with the screen set fits.
- *
- * @example
- * ```ts
- * const app: VisualApp = createApp({ plugins: [...screen, boardFeature], pluginConfigs });
- * ```
- */
-type VisualApp = ControlApp & {
-  readonly anim: AnimApi;
-  readonly ui: UiApi;
-  readonly renderer: Api;
-  readonly world: Api$1;
-  readonly model: Api$2;
-  readonly input: InputApi;
-  readonly lifecycle: Api$3;
-};
-/**
- * The dev page the browser leg opens: its URL, the viewport width in CSS px (390 by default), the
- * device scale (2 by default) and which Chrome to launch. The page height follows the inert frame
- * of the renderer: 520 for a 390 wide portrait game at the default 4:3. Without `browser` the leg
- * launches Playwright's own Chromium, and the system Chrome when that one is not installed.
- *
- * @example
- * ```ts
- * // The fixture's dev server, a 390 px wide phone at 2x, the system Chrome.
- * const page: VisualPage = { url: "http://localhost:3000/", browser: { channel: "chrome" } };
- * ```
- */
-type VisualPage = {
-  url: string;
-  width?: number;
-  deviceScaleFactor?: number;
-  browser?: {
-    channel?: string;
-    executablePath?: string;
-  };
-};
-/**
- * How the runner builds a game: a fresh app per test, not started, with the screen set
- * composed; the renderer stays inert in Bun. `page` is the dev page of the pixel leg.
- *
- * @example
- * ```ts
- * // tests/visual/run.ts of a game.
- * const setup: VisualSetup = { app: () => createScreenGame().app, page: { url: "http://localhost:3000/" } };
- * ```
- */
-type VisualSetup = {
-  app: () => VisualApp;
-  page?: VisualPage;
-};
-/**
- * How far a pixel may differ: `threshold` is the largest channel delta that still counts as the
- * same pixel, `ratio` the share of differing pixels a checkpoint tolerates.
- *
- * @example
- * ```ts
- * const tolerance: VisualTolerance = { ratio: 0.001, threshold: 24 }; // the defaults
- * ```
- */
-type VisualTolerance = {
-  ratio: number;
-  threshold: number;
-};
-/**
- * The backend the browser leg draws with: `"webgpu"`, or `"webgl"` for the WebGL leg.
- *
- * @example
- * ```ts
- * const renderer: VisualRenderer = "webgl"; // what --webgl asks for
- * ```
- */
-type VisualRenderer = "webgpu" | "webgl";
-/**
- * The options of a run. Each one left out comes from the command line (`argv`), then from its
- * default: `dir` `"tests/visual"`, `update` false, `pixels` true with a `page` on a Mac,
- * `renderer` `"webgpu"`, `settleFrames` 600, `tolerance` `{ ratio: 0.001, threshold: 24 }`,
- * `argv` `process.argv.slice(2)`. An option given here wins over a flag. `renderer: "webgl"`
- * runs only the tests with `webgl: true`, on the page with `?renderer=webgl`, and compares their
- * pictures with `screen.webgl.webp`.
- *
- * @example
- * ```ts
- * // The same as `bun tests/visual/run.ts --only reward-popup --no-pixels`.
- * const options: VisualOptions = { only: ["reward-popup"], pixels: false };
- * // The same as `bun tests/visual/run.ts --webgl`.
- * const webgl: VisualOptions = { renderer: "webgl" };
- * ```
- */
-type VisualOptions = {
-  dir?: string;
-  update?: boolean;
-  pixels?: boolean;
-  renderer?: VisualRenderer;
-  only?: readonly string[];
-  settleFrames?: number;
-  tolerance?: VisualTolerance;
-  argv?: readonly string[];
-};
-/**
- * What a comparison with a baseline file found: the same content, a different one, or no
- * baseline (or `--update`), so the file was written.
- *
- * @example
- * ```ts
- * const outcome: Outcome = "written"; // the first run of a new checkpoint
- * ```
- */
-type Outcome = "same" | "different" | "written";
-/**
- * The outcome of one checkpoint. `first` is the JSON path of the first difference, the state's
- * before the describe's. `pixels` is `"skipped"` when the pixel leg did not run; `pixelRatio`
- * and `verdict` come with a pixel difference.
- *
- * @example
- * ```ts
- * // The player's coins differ from the baseline; the layout is the same.
- * const result: CheckpointResult = {
- *   name: "claimed", state: "different", describe: "same", pixels: "skipped", first: "player.coins"
- * };
- * ```
- */
-type CheckpointResult = {
-  name: string;
-  state: Outcome;
-  describe: Outcome;
-  pixels: Outcome | "skipped";
-  pixelRatio?: number;
-  first?: string;
-  verdict?: "rendering" | "behaviour";
-};
-/**
- * The outcome of one visual test: every checkpoint it reached, and the error that ended it early.
- *
- * @example
- * ```ts
- * const result: VisualTestResult = {
- *   name: "reward-popup",
- *   checkpoints: [{ name: "open", state: "same", describe: "same", pixels: "skipped" }]
- * };
- * ```
- */
-type VisualTestResult = {
-  name: string;
-  checkpoints: readonly CheckpointResult[];
-  error?: string;
-};
-/**
- * What `runVisualTests` answers: `ok` is true when no test failed and no outcome is
- * `"different"`.
- *
- * @example
- * ```ts
- * const report: VisualReport = await runVisualTests(setup, [rewardPopup], { argv: [] });
- * process.exitCode = report.ok ? 0 : 1;
- * ```
- */
-type VisualReport = {
-  ok: boolean;
-  tests: readonly VisualTestResult[];
-};
-/** What the command line asked for: the flags it carried, nothing else. */
-type VisualFlags = {
-  dir?: string;
-  update?: boolean;
-  pixels?: boolean;
-  renderer?: VisualRenderer;
-  only?: readonly string[];
-};
-//#endregion
-//#region src/visual/define.d.ts
-/**
- * Defines a visual test: where it starts, what `game.restore` loads, and its steps. A step is a
- * `/control` command by its short name with that command's input, or `{ checkpoint: name }`,
- * where the runner saves `state.json` and `describe.json` next to the test. `walk` runs fast: a
- * popup its last node opens never mounts, so the step before a checkpoint that shows a node's
- * result is `answer` or `tap`. With `webgl: true` the test also runs in the WebGL leg
- * (`--webgl`), whose pictures go to `screen.webgl.webp`: set it on a screen with a custom filter.
- * The answer is a frozen copy; nothing runs here.
- *
- * @param name - The test name, also its folder: lowercase letters, digits and dashes.
- * @param test - Where it starts, its steps and its WebGL leg.
- * @param test.start - The player, and optionally the session, the rng and the checkpoint.
- * @param test.steps - The commands and the checkpoints, in order.
- * @param test.webgl - True to run the test in the WebGL leg too; false by default.
- * @returns The test, frozen.
- * @throws {Error} When the name or a checkpoint name is not a file name, a checkpoint name is
- *   used twice, or a step is not one step command.
- * @example
- * ```ts
- * // tests/visual/home.visual.ts: Home with the glowing Play plank, in both legs.
- * const home = defineVisualTest("home", { start: atHome, steps: [{ checkpoint: "rest" }], webgl: true });
- * home.webgl; // true
- * ```
- */
-declare function defineVisualTest(name: string, test: {
-  start: VisualStart;
-  steps: readonly VisualStep[];
-  webgl?: boolean;
-}): VisualTest;
-//#endregion
-//#region src/visual/run.d.ts
-/**
- * Reads the flags of the visual tests from a command line: `--update`, `--no-pixels`, `--webgl`,
- * `--only <name>` (repeatable) and `--dir <path>`. An argument it does not know is left to the
- * script that got it, so a test runner's own arguments pass through.
- *
- * @param argv - The arguments after the script name.
- * @returns The flags that were given, and nothing else.
- * @throws {Error} When `--only` or `--dir` has no value.
- * @example
- * ```ts
- * // `bun tests/visual/run.ts --update --only reward-popup`
- * parseVisualArgv(["--update", "--only", "reward-popup"]); // { update: true, only: ["reward-popup"] }
- * parseVisualArgv(["--no-pixels", "--dir", "shots"]); // { pixels: false, dir: "shots" }
- * parseVisualArgv(["--webgl"]); // { renderer: "webgl" }
- * ```
- */
-declare function parseVisualArgv(argv: readonly string[]): VisualFlags;
-/**
- * Runs visual tests: the headless leg over every selected test, then the browser leg over the
- * same tests when `pixels` is on (by default only with a `page` on a Mac). With `renderer:
- * "webgl"` (`--webgl`) only the tests with `webgl: true` run, the page opens with
- * `?renderer=webgl` and its pictures go to `screen.webgl.webp`; `state.json` and `describe.json`
- * are shared with the WebGPU leg and compared as always. A checkpoint saves
- * `state.json` and `describe.json` in `<dir>/<test>/<checkpoint>/`, and the browser leg
- * `screen.webp`, lossless: a missing file is written, `--update` rewrites every file of the tests
- * run, a JSON file is compared exactly. The browser leg opens the dev page in Chrome with WebGPU
- * through `playwright-core`, pauses its game, plays each test there on stepped frames of 1000/60
- * ms, so two runs see the same game time, checks the page's state against `state.json` and
- * compares the picture in the page: a pixel differs above `tolerance.threshold`, and the screen
- * differs when more than `tolerance.ratio` of its pixels do; `screen.actual.webp` and
- * `screen.diff.webp` are written beside the baseline then. A pixel difference over the same state
- * and describe is a rendering regression (`verdict: "rendering"`). One line per checkpoint goes
- * to the branded console; the script sets the exit code from `ok`.
- *
- * @param setup - How to build a game: a fresh, unstarted app per test, and the dev page.
- * @param tests - Every visual test of the game.
- * @param options - Overrides of the flags of `argv` and of the defaults.
- * @returns The report: `ok` when no test failed and nothing is `"different"`.
- * @throws {Error} When a test is not well formed, two tests share a name, `only` names no test,
- *   a flag misses its value, or the browser leg fails as a whole: no `page`, no
- *   `playwright-core`, no Chrome, or a page that does not open, expose `game` and `doors`, start,
- *   draw with the requested backend or stop loading. In the WebGL leg, also when `only` names a
- *   test without `webgl: true`.
- * @example
- * ```ts
- * // tests/visual/run.ts of a game, `bun tests/visual/run.ts --update` on a Mac
- * const report = await runVisualTests(
- *   { app: () => createScreenGame().app, page: { url: "http://localhost:3000/" } },
- *   [rewardPopup]
- * );
- * report.tests[0]?.checkpoints[0]; // { name: "open", state: "written", describe: "written", pixels: "written" }
- * ```
- */
-declare function runVisualTests(setup: VisualSetup, tests: readonly VisualTest[], options?: VisualOptions): Promise<VisualReport>;
-//#endregion
-export { type CheckpointResult, type HeadlessApp, type HeadlessGame, type Repro, type ReproResult, type VisualApp, type VisualOptions, type VisualPage, type VisualRenderer, type VisualReport, type VisualSetup, type VisualStart, type VisualStep, type VisualTest, type VisualTestResult, type VisualTolerance, createHeadless, defineVisualTest, fakeClock, memory, parseVisualArgv, runRepro, runVisualTests, saveOf, stepFrames };
+export { type HeadlessApp, type HeadlessGame, type Repro, type ReproResult, createHeadless, fakeClock, memory, runRepro, saveOf, stepFrames };