@moku-labs/game 0.14.11 → 0.14.13

package/dist/{visual-dMW8iqAE.mjs → visual-2m4wJL_z.mjs}

@@ -124,6 +124,20 @@ function system(definition) {
 	return definition;
 }
 /**
+* Binds `system` to one game's player and session, so `run` reads a typed snapshot. Type-only:
+* the same function.
+*
+* @returns `{ system }` whose `run` reads the game's state types.
+* @example
+* ```ts
+* const { system: gameSystem } = systemsFor<{ board: { cells: number[] } }, {}>();
+* gameSystem({ name: "looks", phase: "animate", query: [Transform], run: (rows, { snapshot }) => void snapshot.player.board.cells });
+* ```
+*/
+function systemsFor() {
+	return { system };
+}
+/**
 * The layer a view is drawn in. Written only by the projection; a `view` that returns it is
 * logged and the value ignored.
 */
@@ -146,13 +160,48 @@ const Tree = /*#__PURE__*/ component("Tree", { node: {
 	props: {},
 	children: []
 } });
+/**
+* The moment of the frame on the game's clock: `clock.now()`, read by `world` once at the start of
+* every frame (before the systems of `input`) and once when the world starts, headless too. It is
+* the moment a node gets as `now`, so a fake clock makes it exact in tests. A system that shows
+* time reads it and writes its component only when its picture changes; with `renderer.onDemand`
+* that is when a frame is drawn. A write by a system is overwritten at the next frame. `0` only
+* before the world started, and after `ecs.clear()` until the next frame. `"Now"` is an engine
+* resource name: a game resource of that name is refused.
+*
+* @example
+* ```ts
+* // A toast shows the seconds left of its energy timer: it is written once a second, not every frame.
+* const toastTime = system({
+*   name: "shared.toastTime",
+*   phase: "animate",
+*   query: [ToastTime],
+*   run: (rows, { world, res }) => {
+*     const { now } = res(Now); // 1_790_000_016_000: the fake clock of the test stands there
+*     for (const [entity, time] of rows) {
+*       const left = Math.max(0, time.until - now);
+*       if (Math.ceil(left / 1000) !== Math.ceil(time.left / 1000)) world.set(entity, ToastTime, { left });
+*     }
+*   }
+* });
+* app.world.ecs.resource(Now).now; // 1_790_000_016_000
+* ```
+*/
+const Now = /*#__PURE__*/ resource("Now", { now: 0 });
 //#endregion
 //#region src/plugins/renderer/components.ts
 /**
-* @file renderer plugin — the five components a game writes and the `sprite()` bundle helper.
-* Pure: no ctx, no state, no Pixi. Made with the `component()` helper of `world`, so nothing has
+* @file renderer plugin — the components a game writes (the five of a view, the overlay marker and the HUD
+* part), the engine's own overlay level, and the `sprite()` bundle helper. Pure: no ctx, no state, no Pixi. Made with the `component()` helper of `world`, so nothing has
 * to be registered.
 */
+const overlayDefaults = {
+	dim: 0,
+	dimColor: 0,
+	cover: "none",
+	hud: "all",
+	fade: 250
+};
 const displayDefaults = { object: void 0 };
 const shapeDefaults = {
 	kind: "rect",
@@ -227,6 +276,36 @@ const Display = /*#__PURE__*/ component("Display", displayDefaults);
 */
 const Shape = /*#__PURE__*/ component("Shape", shapeDefaults);
 /**
+* Marks the view an overlay is drawn from. Everything drawn before the root of that view is kept as one picture while
+* the overlay is there, and drawn again in the same frame anything in it changes; `cover: "opaque"` draws nothing
+* under it while it is fully shown. The engine draws its dim and fades the HUD parts it does not keep, with the root's
+* own enter and exit motion (`fade` when it has none).
+*
+* @example
+* ```tsx
+* // The case file: opaque once it has faded in, the ward under it is not drawn until it starts to leave.
+* <panel key="caseSheet" motion={sheetFade} components={[Overlay({ cover: "opaque" })]} />
+* ```
+*/
+const Overlay = /*#__PURE__*/ component("Overlay", overlayDefaults);
+/**
+* Tags a view of the HUD layer as a part an overlay may keep or let fade, by `key`.
+*
+* @example
+* ```tsx
+* <stack key="resEnergy" components={[HudPart({ key: "energy" })]} />
+* ```
+*/
+const HudPart = /*#__PURE__*/ component("HudPart", { key: "" });
+/**
+* The level and the landing of an overlay, on the entity that carries `Overlay`. Engine state: `ui` writes it, the
+* renderer reads it; a game never writes it.
+*/
+const OverlayLevel = /*#__PURE__*/ component("OverlayLevel", {
+	level: 0,
+	landed: false
+});
+/**
 * Bundles the two components every visual needs, so a projection `view` reads as one line.
 *
 * @param options - Texture key, position, and the four values that have defaults.
@@ -253,20 +332,24 @@ function sprite(options) {
 	})];
 }
 /**
-* Binds `sprite`, `Sprite` and `NineSlice` to one game's asset keys. Type-only: the same objects.
+* Binds `sprite`, `Sprite` and `NineSlice` to one game's asset keys, and `Overlay` and `HudPart` to its HUD part keys.
+* Type-only: the same objects.
 *
-* @returns The three helpers with `texture` narrowed to `Asset`.
+* @returns The five helpers with `texture` narrowed to `Asset` and the HUD keys to `HudKey`.
 * @example
 * ```ts
-* const { Sprite } = componentsFor<"board.cell" | "board.item-wood-1">();
+* const { Sprite, HudPart } = componentsFor<"board.cell" | "board.item-wood-1", "energy">();
 * Sprite({ texture: "board.cell" }).value.texture; // "board.cell"
+* HudPart({ key: "energy" }).value.key; // "energy"
 * ```
 */
 function componentsFor() {
 	return {
 		sprite,
 		Sprite,
-		NineSlice
+		NineSlice,
+		Overlay,
+		HudPart
 	};
 }
 /**
@@ -790,5 +873,26 @@ function visualRectOf(element, lookup) {
 function samePose(first, second) {
 	return first.x === second.x && first.y === second.y && first.rotation === second.rotation && first.scale === second.scale && first.pivot.x === second.pivot.x && first.pivot.y === second.pivot.y;
 }
+/**
+* Where a local box of a view lands in root space: moved by the pose, scaled around its pivot.
+* A guide hole is axis-aligned, so the rotation is left out.
+*
+* @param pose - The root pose of the view, `rootPoseOf` of `renderer`.
+* @param local - The box in the view's local units.
+* @returns The rect in root coordinates.
+* @example
+* ```ts
+* drawnRect({ x: 200, y: 200, rotation: 0, scale: 0.8, pivot: { x: 250, y: 250 } },
+*   { x: 50, y: 50, w: 100, h: 100 }); // { x: 40, y: 40, w: 80, h: 80 }
+* ```
+*/
+function drawnRect(pose, local) {
+	return {
+		x: pose.x + pose.scale * (local.x - pose.pivot.x),
+		y: pose.y + pose.scale * (local.y - pose.pivot.y),
+		w: local.w * pose.scale,
+		h: local.h * pose.scale
+	};
+}
 //#endregion
-export { system as A, Exiting as C, component as D, Tree as E, mut as O, sprite as S, Order as T, Parent as _, visualOf as a, Transform as b, Text as c, defineTextStyles as d, label as f, NineSlice as g, Display as h, scaleByFits as i, tag as j, resource as k, bind as l, textFor as m, fitScaleOf as n, visualRectOf as o, readStyle as p, samePose as r, Countdown as s, CONTENT as t, builtInStyles as u, Shape as v, Layer as w, componentsFor as x, Sprite as y };
+export { Order as A, Sprite as C, Exiting as D, sprite as E, system as F, systemsFor as I, tag as L, component as M, mut as N, Layer as O, resource as P, Shape as S, componentsFor as T, HudPart as _, scaleByFits as a, OverlayLevel as b, Countdown as c, builtInStyles as d, defineTextStyles as f, Display as g, textFor as h, samePose as i, Tree as j, Now as k, Text as l, readStyle as m, drawnRect as n, visualOf as o, label as p, fitScaleOf as r, visualRectOf as s, CONTENT as t, bind as u, NineSlice as v, Transform as w, Parent as x, Overlay as y };

package/dist/visual-_XhoGeIC.d.mts

@@ -0,0 +1,345 @@
+import { T as Api, sr as Api$2, wr as Api$3, zt as Api$1 } from "./types-BGcda5Le.mjs";
+import { P as AnimApi, r as UiApi } from "./types-GHE4J5Uf.mjs";
+import { j as InputApi } from "./types-7GXcXxxv.mjs";
+import { r as Repro } from "./headless-cFveciuY.mjs";
+import { a as InputOf, r as ControlApp } from "./types-DngFQJro.mjs";
+import { t as commands } from "./commands-DAETmK86.mjs";
+
+//#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" };
+ * // The same as `bun tests/visual/run.ts --no-verify-frames`: skipped frames are not checked.
+ * const unchecked: VisualOptions = { verifyFrames: false };
+ * ```
+ */
+type VisualOptions = {
+  dir?: string;
+  update?: boolean;
+  pixels?: boolean;
+  /**
+   * The browser leg turns on `debug.verifyFrames` and fails a test on the first
+   * `renderer:missed-frame`, `renderer:missed-mark` or `renderer:stale-picture` of the page, and on
+   * the first `effects:broken`, `renderer:warm-failed` or `renderer: pixel read failed`, also one
+   * logged while the page loaded; `true` by default, `false` with `--no-verify-frames`.
+   */
+  verifyFrames?: 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;
+  verifyFrames?: 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`, `--pixels`,
+ * `--webgl`, `--no-verify-frames`, `--only <name>` (repeatable) and `--dir <path>`. `--pixels`
+ * forces the pixel leg on off a Mac; the last of `--pixels` and `--no-pixels` wins.
+ * `--no-verify-frames` keeps the browser leg from checking the frames the renderer skips. An argument it does not know is left
+ * to the script that got it, so a test runner's own arguments pass through. `moku-game visual`
+ * reads its flags with it.
+ *
+ * @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" }
+ * parseVisualArgv(["--pixels"]); // { pixels: true }
+ * parseVisualArgv(["--no-verify-frames"]); // { verifyFrames: false }
+ * ```
+ */
+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 { VisualApp as a, VisualRenderer as c, VisualStart as d, VisualStep as f, VisualTolerance as h, CheckpointResult as i, VisualReport as l, VisualTestResult as m, runVisualTests as n, VisualOptions as o, VisualTest as p, defineVisualTest as r, VisualPage as s, parseVisualArgv as t, VisualSetup as u };