@moku-labs/game 0.0.1 → 0.0.3

package/dist/testing.d.mts

@@ -1,161 +1,375 @@
-import { E as Json, L as RngState, M as ProviderCall, N as SaveDoc, S as FakeClock, U as Api, h as RouteStep, j as PlayerStateProvider, m as JournalEntry, p as FlowState, t as Api$1, y as Answer } from "./types-BfsmUzLC.mjs";
+import { At as Json, Dt as Api$2, Ft as PlayerStateProvider, It as ProviderCall, Lt as SaveDoc, Ut as Api$3, Zt as FakeClock, h as Api$1, t as Api } from "./types-Cjf3ywai.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-D0uYTTC3.mjs";
+import { H as InputApi } from "./types-C0SLQsx0.mjs";
+import { b as UiApi, t as AnimApi } from "./types-KlE_GL1z.mjs";
+import { t as commands } from "./commands-BOxqlv7w.mjs";
 
 //#region src/plugins/clock/fake.d.ts
 /**
- * Creates a fake source for tests. Timers fire synchronously inside `advance`, in due order.
+ * Creates a fake source for tests. Timers fire synchronously inside `advance`, in due order. A
+ * negative delay counts as zero and an unknown handle is ignored.
  *
  * @param start - Starting moment in epoch milliseconds. Defaults to 0.
  * @returns A clock source with the test-only controls `advance` and `set`.
  * @example
  * ```ts
+ * // An energy point refills 60 s after it was spent. The test moves the clock, not the minute.
  * const clock = fakeClock(1000);
- * clock.advance(5000);
+ * const app = createApp({ pluginConfigs: { clock: { source: clock } } });
+ * const seen: number[] = [];
+ *
+ * app.clock.onElapsed(({ now }) => seen.push(now));
+ * app.clock.scheduleAt(61_000);
+ * clock.advance(60_000); // the timer fires inside advance, nothing waits
+ * seen; // [61000]
  * ```
  */
 declare function fakeClock(start?: number): FakeClock;
 //#endregion
-//#region src/plugins/flow/headless.d.ts
+//#region src/plugins/model/store/providers/memory.d.ts
 /**
- * The part of an app the headless helpers use. Structural on purpose: any app created with the
- * default plugins fits.
+ * Creates an in-memory provider that keeps what it was committed and records every call.
+ * It is the default when a game configures no `playerProvider`, and the double every test uses:
+ * `provider.calls` is the whole persistence protocol of one run, in order. The document lives as
+ * long as the provider does, so a second app over the same instance reads what the first one
+ * wrote, and nothing survives the process.
  *
+ * `load()` reads the fixture, or everything committed since; without either, the player is new.
+ * `commitDurable()` resolves at once: there is no disk behind it.
+ *
+ * @param fixture - The save `load()` starts from. Omitted: a new player.
+ * @param fixture.state - The saved document.
+ * @param fixture.version - Schema version of the saved document.
+ * @returns A provider that keeps its document and records its calls.
  * @example
  * ```ts
- * const app: HeadlessApp = createApp({ pluginConfigs: { flow: { mainFlow } } });
+ * // A new player is saved at once. One roll reaches the provider at the next rest node.
+ * const provider = memory();
+ * const game = await createHeadless(createGame(provider));
+ *
+ * await game.walk([{ at: "home", intent: "roll" }]);
+ * provider.calls.map(call => call.method); // ["load", "commit", "commit"]
  * ```
  */
-type HeadlessApp = {
-  start(): Promise<void>;
-  stop(): Promise<void>;
-  time: Api;
-  flow: Api$1;
+declare function memory(fixture?: {
+  state: SaveDoc;
+  version: number;
+}): PlayerStateProvider & {
+  calls: ProviderCall[];
 };
 /**
- * A game played without a screen: answers go through the gate, effects resolve instantly.
+ * Builds a save document from a player tree, with no rng streams drawn yet.
+ * Short fixtures in tests read as `saveOf({ coins: 5 })` instead of spelling out the rng branch.
+ *
+ * @param player - Player tree of the save.
+ * @param seed - Rng seed of the save.
+ * @returns The save document.
+ * @example
+ * ```ts
+ * // A returning player with 5 coins. The test starts from this save, not from `initialPlayer`.
+ * saveOf({ coins: 5 }, 42); // { player: { coins: 5 }, rng: { seed: 42, streams: {} } }
+ * const provider = memory({ state: saveOf({ coins: 5 }, 42), version: 1 });
+ * ```
+ */
+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 and its steps.
+ * Frozen data; nothing runs at definition.
  *
  * @example
  * ```ts
- * const game: HeadlessGame = await createHeadless(app);
- * await game.walk([{ at: "home", intent: "play" }]);
+ * const test: VisualTest = defineVisualTest("reward-popup", {
+ *   start: { player: { coins: 40 }, checkpoint: "home" },
+ *   steps: [{ tap: { key: "play" } }, { checkpoint: "board" }]
+ * });
+ * test.name; // "reward-popup"
+ * Object.isFrozen(test.steps); // true
  * ```
  */
-type HeadlessGame = {
-  walk(route: readonly RouteStep[]): Promise<FlowState>;
-  answer(answer: Answer): boolean;
-  state(): FlowState;
-  history(): readonly JournalEntry[];
-  stop(): Promise<void>;
+type VisualTest = {
+  readonly name: string;
+  readonly start: Readonly<VisualStart>;
+  readonly steps: readonly VisualStep[];
 };
 /**
- * A reproducible run: a starting state, an optional checkpoint and the route played from it.
+ * 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 repro: Repro = { player: { coins: 0 }, checkpoint: "home", route: [{ at: "home", intent: "play" }] };
+ * const app: VisualApp = createApp({ plugins: [...screen, boardFeature], pluginConfigs });
  * ```
  */
-type Repro = {
-  player: Json;
-  session?: Json;
-  rng?: RngState;
-  checkpoint?: string;
-  route: RouteStep[];
+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;
 };
 /**
- * What a repro run ends with: the path where the loop rests and the committed state.
+ * 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
- * const { path, player }: ReproResult = await runRepro(app, repro);
+ * // 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 ReproResult = {
-  path: string[];
-  player: Json;
-  session: Json;
+type VisualPage = {
+  url: string;
+  width?: number;
+  deviceScaleFactor?: number;
+  browser?: {
+    channel?: string;
+    executablePath?: string;
+  };
 };
 /**
- * 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.
+ * 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.
  *
- * @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
- * const game = await createHeadless(app);
- * expect(game.state().path).toBe("home");
- * await game.walk([{ at: "board/awaitIntent", intent: "merge", payload: { from: "c2", to: "c3" } }]);
- * await game.stop();
+ * // tests/visual/run.ts of a game.
+ * const setup: VisualSetup = { app: () => createScreenGame().app, page: { url: "http://localhost:3000/" } };
  * ```
  */
-declare function createHeadless(app: HeadlessApp): Promise<HeadlessGame>;
+type VisualSetup = {
+  app: () => VisualApp;
+  page?: VisualPage;
+};
 /**
- * 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.
+ * 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.
  *
- * @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
- * const result = await runRepro(app, { player: saved, checkpoint: "home", route });
+ * const tolerance: VisualTolerance = { ratio: 0.001, threshold: 24 }; // the defaults
  * ```
  */
-declare function runRepro(app: HeadlessApp, repro: Repro): Promise<ReproResult>;
+type VisualTolerance = {
+  ratio: number;
+  threshold: number;
+};
 /**
- * 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.
+ * 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,
+ * `settleFrames` 600, `tolerance` `{ ratio: 0.001, threshold: 24 }`, `argv`
+ * `process.argv.slice(2)`. An option given here wins over a flag.
  *
- * @param app - A started app.
- * @param count - Number of frames.
- * @param deltaMs - Milliseconds per frame.
  * @example
  * ```ts
- * stepFrames(app, 60, 16);
+ * // The same as `bun tests/visual/run.ts --only reward-popup --no-pixels`.
+ * const options: VisualOptions = { only: ["reward-popup"], pixels: false };
  * ```
  */
-declare function stepFrames(app: HeadlessApp, count: number, deltaMs: number): void;
-//#endregion
-//#region src/plugins/model/store/providers/memory.d.ts
+type VisualOptions = {
+  dir?: string;
+  update?: boolean;
+  pixels?: boolean;
+  only?: readonly string[];
+  settleFrames?: number;
+  tolerance?: VisualTolerance;
+  argv?: readonly string[];
+};
 /**
- * Creates an in-memory provider that keeps what it was committed and records every call.
- * It is the default when a game configures no `playerProvider`, and the double every test uses:
- * `provider.calls` is the whole persistence protocol of one run, in order. The document lives as
- * long as the provider does, so a second app over the same instance reads what the first one
- * wrote, and nothing survives the process.
+ * What a comparison with a baseline file found: the same content, a different one, or no
+ * baseline (or `--update`), so the file was written.
  *
- * @param fixture - The save `load()` starts from. Omitted: a new player.
- * @param fixture.state - The saved document.
- * @param fixture.version - Schema version of the saved document.
- * @returns A provider that keeps its document and records its calls.
  * @example
  * ```ts
- * const provider = memory({ state: saveOf({ coins: 5 }, 42), version: 1 });
+ * const outcome: Outcome = "written"; // the first run of a new checkpoint
  * ```
  */
-declare function memory(fixture?: {
-  state: SaveDoc;
-  version: number;
-}): PlayerStateProvider & {
-  calls: ProviderCall[];
+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";
 };
 /**
- * Builds a save document from a player tree, with no rng streams drawn yet.
- * Short fixtures in tests read as `saveOf({ coins: 5 })` instead of spelling out the rng branch.
+ * The outcome of one visual test: every checkpoint it reached, and the error that ended it early.
  *
- * @param player - Player tree of the save.
- * @param seed - Rng seed of the save.
- * @returns The save document.
  * @example
  * ```ts
- * const provider = memory({ state: saveOf({ coins: 5 }, 42), version: 1 });
+ * const result: VisualTestResult = {
+ *   name: "reward-popup",
+ *   checkpoints: [{ name: "open", state: "same", describe: "same", pixels: "skipped" }]
+ * };
  * ```
  */
-declare function saveOf(player: Json, seed?: number): SaveDoc;
+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;
+  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`. 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 and its steps.
+ * @param test.start - The player, and optionally the session, the rng and the checkpoint.
+ * @param test.steps - The commands and the checkpoints, in order.
+ * @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/reward-popup.visual.ts: Play, deliver the first order, claim the reward.
+ * export const rewardPopup = defineVisualTest("reward-popup", {
+ *   start: { player: fixtures.ready, checkpoint: "home" },
+ *   steps: [{ tap: { key: "play" } }, { answer: { intent: "deliver", payload: { orderId: "o1" } } },
+ *     { checkpoint: "open" }, { tap: { key: "claim" } }, { checkpoint: "claimed" }]
+ * });
+ * ```
+ */
+declare function defineVisualTest(name: string, test: {
+  start: VisualStart;
+  steps: readonly VisualStep[];
+}): VisualTest;
+//#endregion
+//#region src/visual/run.d.ts
+/**
+ * Reads the flags of the visual tests from a command line: `--update`, `--no-pixels`,
+ * `--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" }
+ * ```
+ */
+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). 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 WebGPU or stop loading.
+ * @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 HeadlessApp, type HeadlessGame, type Repro, type ReproResult, createHeadless, fakeClock, memory, runRepro, saveOf, stepFrames };
+export { type CheckpointResult, type HeadlessApp, type HeadlessGame, type Repro, type ReproResult, type VisualApp, type VisualOptions, type VisualPage, type VisualReport, type VisualSetup, type VisualStart, type VisualStep, type VisualTest, type VisualTestResult, type VisualTolerance, createHeadless, defineVisualTest, fakeClock, memory, parseVisualArgv, runRepro, runVisualTests, saveOf, stepFrames };