@moku-labs/game 0.7.1 → 0.9.0

package/dist/testing.d.mts

@@ -1,8 +1,7 @@
-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 { $t as PlayerStateProvider, Et as AnyFlow, Jt as Json, Mt as NodeTable, en as ProviderCall, gn as FakeClock, mn as ClockSource, mt as FeaturePlugin, tn as SaveDoc } from "./types-B0v5VVa3.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-SCQXJxQf.mjs";
+import { t as createApp } from "./index-BO9kZzY3.mjs";
+import { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/plugins/clock/fake.d.ts
 /**
@@ -73,326 +72,129 @@ 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;
+//#region src/testing/isolate.d.ts
 /**
- * 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.
+ * A stub for one node or sub-flow of the isolated flow: the outcome it ends with, and its payload.
  *
  * @example
  * ```ts
- * const name: StepCommand = "tap"; // also "answer", "walk", "step", "reducedMotion", ...
+ * const closed: Stub<"closed"> = stub("closed"); // { kind: "stub", outcome: "closed" }
  * ```
  */
-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[];
+type Stub<Name extends string = string> = {
+  readonly kind: "stub";
+  readonly outcome: Name;
+  readonly payload?: Json;
 };
 /**
- * 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
- * ```
+ * The outcome names of one entry of a node table. Distributes over a union: for a flow widened
+ * to `Flow.AnyFlow` an entry is a node, a sub-flow or a slot, and every outcome name is allowed,
+ * not only the slot's `done`.
  */
-type Outcome = "same" | "different" | "written";
+type OutcomeNameOf<Entry> = Entry extends {
+  readonly outcomes: infer Tags;
+} ? keyof Tags & string : never;
 /**
- * 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.
+ * One optional stub per node of the flow. The outcome must be one the replaced entry declares:
+ * a wrong one and an unknown key are compile errors, and `isolate()` refuses them at run time too.
+ * A flow widened to `Flow.AnyFlow` takes every key and every outcome.
  *
  * @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"
- * };
+ * // boardFlow holds settings: settingsFlow (outcome closed) and energy (outcomes watch, later).
+ * const stubs: StubsOf<typeof boardFlow.nodes> = { settings: stub("closed"), energy: stub("later") };
  * ```
  */
-type CheckpointResult = {
-  name: string;
-  state: Outcome;
-  describe: Outcome;
-  pixels: Outcome | "skipped";
-  pixelRatio?: number;
-  first?: string;
-  verdict?: "rendering" | "behaviour";
-};
+type StubsOf<Nodes extends NodeTable> = { readonly [Name in keyof Nodes & string]?: Stub<OutcomeNameOf<Nodes[Name]>> };
 /**
- * The outcome of one visual test: every checkpoint it reached, and the error that ended it early.
+ * What `isolate` composes around one feature.
  *
  * @example
  * ```ts
- * const result: VisualTestResult = {
- *   name: "reward-popup",
- *   checkpoints: [{ name: "open", state: "same", describe: "same", pixels: "skipped" }]
+ * const options: IsolateOptions<typeof boardFlow.nodes> = {
+ *   flow: boardFlow, shared: sharedLayer, stubs: { settings: stub("closed") }, player: fresh
  * };
  * ```
  */
-type VisualTestResult = {
-  name: string;
-  checkpoints: readonly CheckpointResult[];
-  error?: string;
+type IsolateOptions<Nodes extends NodeTable> = {
+  /** The feature's flow. It becomes the one node of the harness main flow, named by `as`. */flow: AnyFlow & {
+    readonly nodes: Nodes;
+  };
+  /**
+   * The key the game's main flow holds the flow under. `flow.id` by default.
+   *
+   * @example
+   * ```ts
+   * // The mini game's main flow holds info: infoFlow, whose id is "infoPopup".
+   * isolate(infoFeature, { flow: infoFlow, as: "info", player: { count: 0 } });
+   * // paths read "info/show", as in the game
+   * ```
+   */
+  as?: string; /** The shared layer, composed as `logicOnly` before the feature. */
+  shared?: FeaturePlugin; /** Node name of `flow` to the stub that replaces it. A node not listed runs for real. */
+  stubs?: StubsOf<Nodes>; /** More plugins the feature needs headless, for example a feature-own plugin. */
+  plugins?: readonly AnyPluginInstance[]; /** The player a new save starts from. */
+  player: Json; /** The session at start. `{}` by default. */
+  session?: Json; /** The rng seed. `1` by default. */
+  seed?: number;
 };
 /**
- * What `runVisualTests` answers: `ok` is true when no test failed and no outcome is
- * `"different"`.
+ * What one app of an isolated feature may pin over the options.
  *
  * @example
  * ```ts
- * const report: VisualReport = await runVisualTests(setup, [rewardPopup], { argv: [] });
- * process.exitCode = report.ok ? 0 : 1;
+ * const game = await createHeadless(boardOnly({ player: { ...fresh, coins: 7 }, clock: fakeClock(1_000_000) }));
  * ```
  */
-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[];
+type IsolateSeams = {
+  /** The player this app starts from, instead of `options.player`. */player?: Json; /** The session this app starts with, instead of `options.session`. */
+  session?: Json; /** The rng seed of this app, instead of `options.seed`. */
+  seed?: number; /** The clock source of this app, `fakeClock()` in a test. The system clock by default. */
+  clock?: ClockSource;
 };
-//#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
- * ```
+ * An app of an isolated feature, as `createApp` returns it: not started, the engine's logic
+ * plugins on it.
  */
-declare function defineVisualTest(name: string, test: {
-  start: VisualStart;
-  steps: readonly VisualStep[];
-  webgl?: boolean;
-}): VisualTest;
-//#endregion
-//#region src/visual/run.d.ts
+type IsolatedApp = ReturnType<typeof createApp>;
 /**
- * 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.
+ * A stub: the replaced node or sub-flow ends at once with this outcome. Written as a sub-flow of
+ * one transit node, so a route can still substitute it for one visit:
+ * `{ at: "board/energy", result: { outcome: "watch" } }`.
  *
- * @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.
+ * @param outcome - An outcome the replaced entry declares.
+ * @param payload - The payload it carries, for an outcome with data.
+ * @returns The stub as plain data.
  * @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" }
+ * stub("closed"); // { kind: "stub", outcome: "closed" }
+ * stub("orderComplete", { rewardId: "r1" }); // { kind: "stub", outcome: "orderComplete", payload: { rewardId: "r1" } }
  * ```
  */
-declare function parseVisualArgv(argv: readonly string[]): VisualFlags;
+declare function stub<const Name extends string>(outcome: Name, payload?: Json): Stub<Name>;
 /**
- * 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`.
+ * Composes one feature without the rest of the game: the shared layer and the feature as
+ * `logicOnly`, the feature's flow inside a harness main flow `isolated`, and every stubbed node
+ * replaced by a sub-flow that ends with the stub's outcome. Every exit of the flow lands on the
+ * rest node `exited`, whose intent `again` enters the flow once more. Paths read as in the game:
+ * the harness holds the flow under `options.as`, its id by default. A node that is not stubbed
+ * runs for real, even when it belongs to a feature that is not composed.
  *
- * @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`.
+ * @param feature - The feature under test.
+ * @param options - Its flow, the shared layer, the stubs, the starting state.
+ * @returns A factory of apps, not started; pass one to `createHeadless`.
+ * @throws {Error} For a stub key that is not a node of the flow, or an outcome the node does not declare.
  * @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" }
+ * // tests/fixtures/mini-game: Home alone; its info popup is stubbed to end with ok at once.
+ * const homeOnly = isolate(homeFeature, {
+ *   flow: mainFlow, stubs: { info: stub("ok") }, player: startingPlayer, session: startingSession
+ * });
+ * const game = await createHeadless(homeOnly());
+ * const state = await game.walk([{ at: "main/home", intent: "info" }]);
+ * state.path; // "main/home"
  * ```
  */
-declare function runVisualTests(setup: VisualSetup, tests: readonly VisualTest[], options?: VisualOptions): Promise<VisualReport>;
+declare function isolate<Nodes extends NodeTable>(feature: FeaturePlugin, options: IsolateOptions<Nodes>): (seams?: IsolateSeams) => IsolatedApp;
 //#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 IsolateOptions, type IsolateSeams, type Repro, type ReproResult, type Stub, type StubsOf, createHeadless, fakeClock, isolate, memory, runRepro, saveOf, stepFrames, stub };