@moku-labs/game 0.15.31 → 0.15.33

package/dist/{types-BAp9HdR4.d.mts → types-DGHVGP5i.d.mts}

@@ -2502,9 +2502,12 @@ type ElementChange<Value> = (view: ViewHandle<unknown>, previous: Value, next: V
 /**
  * The motion hooks of one element: the hook triple of `world.projection`, which `defineMotion`
  * of `anim` returns. `ui` plays the `change` hooks of `Box` (the rects), of `Transform` (the rest
- * poses) and of every extra component of the `components` prop (its values before and after). A
- * hook for any other component name is accepted, so every `defineMotion` result fits, and `ui`
- * never plays it. Every hook gets the hint routed to the element's key in that frame step.
+ * poses), of the visual the element is drawn with (`Shape`, `Sprite`, `NineSlice` or `Text`: its
+ * values before and after, when a render or a restyle moves a number of it) and of every extra
+ * component of the `components` prop (its values before and after). A hook for any other
+ * component name is accepted, so every `defineMotion` result fits; `ui` never plays it, and a dev
+ * build names it once (`ui:change-never-plays`). Every hook gets the hint routed to the element's
+ * key in that frame step.
  *
  * @example
  * ```ts
@@ -2648,27 +2651,29 @@ type StyleBasis = {
 };
 /**
  * One live element: the entity, the Yoga node, the resolved style and the place in the tree.
- * `rect` is natural: under a `fit` ancestor it is the rect before that ancestor's scale. `fit`
- * is the element's own fit scale (1 without `fit: "contain"`), and `rest` the rest `Transform`
- * last written for it. `loop` is the motion of the running `loop` hook, kept apart from
- * `handles`: it never ends, so the exit sweep must not wait for it. `extras` holds the values of
- * the `components` prop added last time, by component name; `extraHandles` the motion the last
- * `change` hook of each of them returned; `warnedOwned` the names of the `components` values the
- * element owns that were already logged. A windowed scroll carries its `window` and the one-time
- * warnings of its props in `warned`; `scrolledIn` marks an element a range change of a windowed
- * scroll created: it plays no `enter` hook. A scroll carries its `scroll` motion from its enter. A text or an icon that sizes itself keeps in
- * `measuredSize` what its measure function last answered, before Yoga's clamp: a bound text whose
- * new string measures the same asks for no solve. `measuredWidth` is the width Yoga offered that
- * call when the text wrapped at it (only a `"box"` style does), `undefined` otherwise: such a text
- * is measured again at its laid-out width and gets a `Text.box`, any other gets none. `basis` is what `style` was resolved on, set
- * once the style is on the layout node and the components are written; an element without one is
- * patched in full at its next patch. `index` is its place among the element children of its parent
- * at the last diff (0 for a root element): with its `zIndex` it gives the child its `Order`.
- * `cause` is why the element appeared: `"mount"` when it came with the first build of its root and
- * the root came by a mount, `"change"` otherwise; its `enter` hook is told. `rebuilds` counts the
- * patches in a row that brought a loop of another reference that is not really another loop: a
- * dev build names the element once it reaches three. `endless` holds the motions a hook returned
- * after it started a track that repeats forever: they never end, so no exit waits for them (F42).
+ * `rect` is natural: under a `fit` ancestor it is the rect before that ancestor's scale. `fit` is
+ * the element's own fit scale (1 without `fit: "contain"`), and `rest` the rest `Transform` last
+ * written for it. `loop` is the motion of the running `loop` hook, kept apart from `handles`: it
+ * never ends, so the exit sweep must not wait for it. `extras` holds the values of the
+ * `components` prop added last time, by component name; `extraHandles` the motion the last
+ * `change` hook of each of them and of the visual returned; `warnedOwned` the names of the
+ * `components` values the element owns that were already logged. A windowed scroll carries its
+ * `window` and the one-time warnings of its props in `warned`; `scrolledIn` marks an element a
+ * range change of a windowed scroll created: it plays no `enter` hook. A scroll carries its
+ * `scroll` motion from its enter. A text or an icon that sizes itself keeps in `measuredSize` what
+ * its measure function last answered, before Yoga's clamp: a bound text whose new string measures
+ * the same asks for no solve. `measuredWidth` is the width Yoga offered that call when the text
+ * wrapped at it (only a `"box"` style does), `undefined` otherwise: such a text is measured again
+ * at its laid-out width and gets a `Text.box`, any other gets none. `basis` is what `style` was
+ * resolved on, set once the style is on the layout node and the components are written; an
+ * element without one is patched in full at its next patch. `index` is its place among the
+ * element children of its parent at the last diff (0 for a root element): with its `zIndex` it
+ * gives the child its `Order`. `cause` is why the element appeared: `"mount"` when it came with
+ * the first build of its root and the root came by a mount, `"change"` otherwise; its `enter` hook
+ * is told. `rebuilds` counts the patches in a row that brought a loop of another reference that is
+ * not really another loop: a dev build names the element once it reaches three. `endless` holds
+ * the motions a hook returned after it started a track that repeats forever: they never end, so
+ * no exit waits for them (F42).
  */
 type Element = {
   entity: Entity;
@@ -2724,7 +2729,10 @@ type Element = {
   blended?: boolean;
   basis?: StyleBasis; /** The motions of its hooks that started a `repeat: "forever"` track; made with the first one. */
   endless?: Set<MotionHandle>; /** What its enter hook did at the `Box`, until `ui.enter` keeps the play or plays it again (F49). */
-  posed?: PosedEnter | undefined;
+  posed?: PosedEnter | undefined; /** The value of its visual last written: what a `change` hook of the visual gets as the value before (F85). */
+  look?: AnyComponentValue | undefined; /** The write pass in which a `change` hook of its visual last returned a motion. */
+  lookPass?: number | undefined; /** The value of its visual before that pass: a second write in the pass plays the hook from it. */
+  lookFrom?: object | undefined;
 };
 /**
  * One `set` of an enter hook: the fields it wrote, and the values they had before. A hook may write any component of

package/dist/{visual-HGn_TF2x.d.mts → visual-C2HHHs46.d.mts}

@@ -1,9 +1,9 @@
-import { Vr as Api$3, Y as Api, nn as Api$1, wr as Api$2 } from "./types-D27I4Q7b.mjs";
-import { P as AnimApi, r as UiApi } from "./types-DHamyZq1.mjs";
-import { N as InputApi } from "./types-BAp9HdR4.mjs";
+import { Vr as Api$3, Y as Api, nn as Api$1, vr as Api$4, wr as Api$2 } from "./types-D27I4Q7b.mjs";
+import { P as AnimApi, r as UiApi } from "./types-BqfwZ_lM.mjs";
+import { N as InputApi } from "./types-DGHVGP5i.mjs";
 import { r as Repro } from "./headless-f31cEZ7f.mjs";
 import { a as InputOf, r as ControlApp } from "./types-CgE5L_7f.mjs";
-import { t as commands } from "./commands-C8N_rpwt.mjs";
+import { t as commands } from "./commands-C1gTg70a.mjs";
 
 //#region src/visual/types.d.ts
 /** The base commands of the `/control` door, keyed by their short names. */
@@ -32,7 +32,9 @@ type StepCommand = Exclude<keyof Catalogue, "bookmark" | "capture" | "debug">;
 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.
+ * typed from the catalogue, or a checkpoint by its name. A checkpoint lands every motion
+ * (`anim.finishAll()`) before its snapshot; with `finish: false` it does not, and the snapshot
+ * shows the motions where they stand after the same frames in both legs (F87).
  *
  * @example
  * ```ts
@@ -40,12 +42,15 @@ type VisualStart = Omit<Repro, "route">;
  * const steps: VisualStep[] = [
  *   { tap: { key: "play" } },
  *   { answer: { intent: "deliver", payload: { orderId: "o1" } } },
- *   { checkpoint: "open" }
+ *   { checkpoint: "open" },
+ *   // The hint that fades out at the end of its animation, caught while it still shows.
+ *   { checkpoint: "hint", finish: false }
  * ];
  * ```
  */
 type VisualStep = {
   checkpoint: string;
+  finish?: boolean;
 } | { [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
@@ -84,7 +89,8 @@ type VisualApp = ControlApp & {
   readonly world: Api$1;
   readonly model: Api$2;
   readonly input: InputApi;
-  readonly lifecycle: Api$3;
+  readonly lifecycle: Api$3; /** The clock: the pixel leg puts its moment on the page, so both legs see one `clock.now()`. */
+  readonly clock: Api$4;
 };
 /**
  * The dev page the browser leg opens: its URL, the viewport width in CSS px (390 by default), the
@@ -254,7 +260,8 @@ type VisualFlags = {
 /**
  * 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
+ * where the runner lands every motion and saves `state.json` and `describe.json` next to the test;
+ * `{ checkpoint: name, finish: false }` keeps the motions running for the snapshot. `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.

package/dist/visual.d.mts

@@ -1,2 +1,2 @@
-import { a as VisualApp, c as VisualRenderer, d as VisualStart, f as VisualStep, h as VisualTolerance, i as CheckpointResult, l as VisualReport, m as VisualTestResult, n as runVisualTests, o as VisualOptions, p as VisualTest, r as defineVisualTest, s as VisualPage, t as parseVisualArgv, u as VisualSetup } from "./visual-HGn_TF2x.mjs";
+import { a as VisualApp, c as VisualRenderer, d as VisualStart, f as VisualStep, h as VisualTolerance, i as CheckpointResult, l as VisualReport, m as VisualTestResult, n as runVisualTests, o as VisualOptions, p as VisualTest, r as defineVisualTest, s as VisualPage, t as parseVisualArgv, u as VisualSetup } from "./visual-C2HHHs46.mjs";
 export { type CheckpointResult, type VisualApp, type VisualOptions, type VisualPage, type VisualRenderer, type VisualReport, type VisualSetup, type VisualStart, type VisualStep, type VisualTest, type VisualTestResult, type VisualTolerance, defineVisualTest, parseVisualArgv, runVisualTests };

package/dist/visual.mjs

@@ -1,5 +1,6 @@
-import { n as read, t as sources } from "./sources-DM5Zcl4o.mjs";
-import { n as commands, t as run } from "./run-BnriyKUu.mjs";
+import { t as VISUAL_CLOCK } from "./fake-hnJcJeYf.mjs";
+import { n as read, t as sources } from "./sources-MfRpM8sV.mjs";
+import { n as commands, t as run } from "./run-G4m1APMv.mjs";
 import path from "node:path";
 import { createBrandConsole } from "@moku-labs/common/cli";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
@@ -62,15 +63,41 @@ function stepNames() {
 	return Object.keys(commands).filter((name) => isStepCommand(name)).join(", ");
 }
 /**
-* Takes one step apart and checks its shape: exactly one key, either `checkpoint` or a step
-* command with an input object. The checkpoint name is checked by the caller.
+* Takes a checkpoint step apart: its name, a string, and `finish`, a boolean when it is there; no
+* other key.
+*
+* @param at - The test and the step, for the message.
+* @param fields - The step.
+* @returns The checkpoint.
+* @throws {Error} When the name is not a string, `finish` not a boolean, or another key is there.
+* @example
+* ```ts
+* checkpointEntry('[game] Visual test "fade", step 2', { checkpoint: "glow", finish: false }); // { kind: "checkpoint", name: "glow", finish: false }
+* ```
+*/
+function checkpointEntry(at, fields) {
+	const { checkpoint: name, finish = true, ...others } = fields;
+	if (Object.keys(others).length > 0) throw new Error(`${at} is not one command.\n  A checkpoint takes its name and finish, like { checkpoint: "name", finish: false }.`);
+	if (typeof name !== "string") throw new TypeError(`${at}: the checkpoint name is not a string.\n  Write the checkpoint as { checkpoint: "name" }.`);
+	if (typeof finish !== "boolean") throw new TypeError(`${at}: finish of the checkpoint "${name}" is not a boolean.\n  Write finish: false to keep the motions running, or leave it out.`);
+	return {
+		kind: "checkpoint",
+		name,
+		finish
+	};
+}
+/**
+* Takes one step apart and checks its shape: a checkpoint (its name, and `finish` when it is
+* there), or exactly one step command with an input object. The checkpoint name is checked by the
+* caller.
 *
 * @param test - The test name, for the message.
 * @param step - The step.
 * @param index - Its index in the steps, from 0.
 * @returns The checkpoint or the command with its input.
 * @throws {Error} When the step holds no key or more than one, names something that is not a
-*   step, gives a command no input object, or a checkpoint no string.
+*   step, gives a command no input object, or a checkpoint no string name or a `finish` that is
+*   not a boolean.
 * @example
 * ```ts
 * stepEntry("reward-popup", { tap: { key: "play" } }, 0); // { kind: "command", name: "tap", input: { key: "play" } }
@@ -80,15 +107,9 @@ function stepEntry(test, step, index) {
 	const fields = step;
 	const [name, ...others] = Object.keys(fields);
 	const at = `[game] Visual test "${test}", step ${index + 1}`;
+	if (Object.hasOwn(fields, "checkpoint")) return checkpointEntry(at, fields);
 	if (name === void 0 || others.length > 0) throw new Error(`${at} is not one command.\n  Write one command by its short name, or { checkpoint: "name" }.`);
 	const value = fields[name];
-	if (name === "checkpoint") {
-		if (typeof value === "string") return {
-			kind: "checkpoint",
-			name: value
-		};
-		throw new Error(`${at}: the checkpoint name is not a string.\n  Write the checkpoint as { checkpoint: "name" }.`);
-	}
 	if (!isStepCommand(name)) throw new Error(`${at} names "${name}", which is not a step.\n  Use a checkpoint or one of: ${stepNames()}.`);
 	if (!isInputObject(value)) throw new Error(`${at} (${name}) has no input object.\n  Pass the input of the command, like { tap: { key: "play" } }.`);
 	return {
@@ -173,7 +194,8 @@ function checkVisualTest(name, steps) {
 /**
 * 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
+* where the runner lands every motion and saves `state.json` and `describe.json` next to the test;
+* `{ checkpoint: name, finish: false }` keeps the motions running for the snapshot. `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.
@@ -773,17 +795,19 @@ async function settleAt(play, where) {
 	if (play.loop.error !== void 0) throw play.loop.error;
 }
 /**
-* Plays a checkpoint: settle, land every track and loop, two frames, then read and compare.
+* Plays a checkpoint: settle, land every track and loop unless it says `finish: false`, two
+* frames, then read and compare.
 *
 * @param play - The test being played.
-* @param name - The checkpoint name.
+* @param entry - The checkpoint: its name, and whether it lands the motions.
 * @param where - The step, for the message.
 * @returns The outcome of the checkpoint; `pixels` is skipped in this leg.
 */
-async function checkpoint$1(play, name, where) {
+async function checkpoint$1(play, entry, where) {
 	const { app, test, run: options } = play;
+	const { name } = entry;
 	await settleAt(play, where);
-	app.anim.finishAll();
+	if (entry.finish) app.anim.finishAll();
 	await frames(app, REST_FRAMES);
 	const file = (kind) => baselineFile(options.dir, test.name, name, kind);
 	const state = await checkBaseline(file("state.json"), stableJson(stateOf(app)), options.update);
@@ -819,7 +843,7 @@ async function playSteps$1(play, checkpoints) {
 		const entry = stepEntry(test.name, step, index);
 		const where = `step ${index + 1} (${entry.kind === "checkpoint" ? "checkpoint" : entry.name})`;
 		if (entry.kind === "checkpoint") {
-			checkpoints.push(await checkpoint$1(play, entry.name, where));
+			checkpoints.push(await checkpoint$1(play, entry, where));
 			continue;
 		}
 		await failing(test.name, where, () => runStep(app, entry.name, entry.input));
@@ -1234,13 +1258,16 @@ async function pageStep(argument) {
 	}
 }
 /**
-* Plays a checkpoint in the page: settle, land every track and loop, two stepped frames, then the
+* Plays a checkpoint in the page: settle, land every track and loop unless the step says
+* `finish: false` (F87), two stepped frames, then the
 * picture of the whole canvas as lossless WebP and the state through the doors. The game is
 * paused, so the picture is the stage after the last stepped frame. With the frame check on, a
 * missed frame or mark logged in the meantime fails the checkpoint.
 *
-* @param argument - The test and the step, and the most frames to settle.
+* @param argument - The test and the step, the most frames to settle, and whether to land the
+*   motions.
 * @param argument.settleFrames - The most frames to settle.
+* @param argument.finish - True to land every motion before the picture.
 * @returns The state and the picture, or why the checkpoint failed.
 */
 async function pageCheckpoint(argument) {
@@ -1252,7 +1279,7 @@ async function pageCheckpoint(argument) {
 			ok: false,
 			error: unsettled
 		};
-		game.anim.finishAll();
+		if (argument.finish) game.anim.finishAll();
 		await pageTick(handles);
 		await pageTick(handles);
 		const captured = await game.renderer.capture();
@@ -1497,6 +1524,17 @@ function pageScript() {
 }
 //#endregion
 //#region src/visual/leg-browser.ts
+/**
+* @file visual — the browser leg: Chrome with WebGPU on a Mac, driven by Playwright. It loads
+* `playwright-core` with a dynamic import only here, opens the dev page once per test, waits until
+* the page has loaded what it asked for, turns on the renderer's check of skipped frames
+* (`debug.verifyFrames`), pauses the game and steps it to the start time, plays the
+* test inside the page through `globalThis.game` and `globalThis.doors` on stepped frames, and at
+* each checkpoint checks the page's state against `state.json` and its picture against
+* `screen.webp`. The WebGL leg opens the page with `?renderer=webgl` and keeps its pictures in
+* `screen.webgl.webp`. The pixels are compared in the page (`page-script.ts`); the files are written by
+* `files.ts`. A failure of the page itself fails the leg; a failure of a step ends its test only.
+*/
 /** The Chrome flags of `.planning/e2e/run.mjs`: WebGPU on Metal, on any GPU. */
 const WEBGPU_FLAGS = [
 	"--enable-unsafe-webgpu",
@@ -1636,6 +1674,20 @@ async function launchChrome(chromium, browser) {
 	throw new Error(`[game] No Chrome launched: ${own.reason}.\n  Install Playwright's Chromium (bunx playwright-core install chromium), set page.browser, or run with --no-pixels.`);
 }
 /**
+* The init script that puts the moment of the headless leg's clock on the page before it loads
+* (F86): a dev page then runs its app on a fake clock standing there, as the headless leg does.
+*
+* @param moment - The moment, epoch milliseconds.
+* @returns The script.
+* @example
+* ```ts
+* clockScript(1_000_000); // 'globalThis["__mokuVisualClock"] = 1000000;'
+* ```
+*/
+function clockScript(moment) {
+	return `globalThis[${JSON.stringify(VISUAL_CLOCK)}] = ${JSON.stringify(moment)};`;
+}
+/**
 * Sizes the page: `page.width` CSS px wide (390), as tall as the inert frame of the game is at
 * that width, so the reference frame of the page equals the one of the headless leg; a phone
 * with touch at `page.deviceScaleFactor` (2). Builds one app of the setup, never started, to read
@@ -1762,14 +1814,16 @@ async function startPage(page, url, run) {
 * @param context - The browser context.
 * @param url - The URL of the page the leg opens.
 * @param run - The run options, for `settleFrames` and `renderer`.
+* @param moment - The moment the headless leg's clock stands at, for the page's clock (F86).
 * @returns The open page.
 * @throws {Error} When the page does not open, never exposes `game` and `doors`, does not start,
 *   draws with another backend or never stops loading. The page is closed then.
 */
-async function openPage(context, url, run) {
+async function openPage(context, url, run, moment) {
 	const page = await context.newPage();
 	try {
 		await page.addInitScript({ content: pageScript() });
+		await page.addInitScript({ content: clockScript(moment) });
 		await page.goto(url).catch((error) => {
 			throw new Error(`[game] The page at ${url} did not open: ${firstLine(error)}.\n  Serve the dev page (moku-game dev), or run with --no-pixels.`);
 		});
@@ -1825,17 +1879,19 @@ async function checkScreen(play, file, where, screen) {
 * headless leg wrote, the picture against the baseline of the leg's backend.
 *
 * @param play - The test being played.
-* @param name - The checkpoint name.
+* @param entry - The checkpoint: its name, and whether it lands the motions.
 * @param where - The step, for the message.
 * @returns What the browser leg found there.
 * @throws {Error} When the page did not settle, gave no picture, or broke.
 */
-async function checkpoint(play, name, where) {
+async function checkpoint(play, entry, where) {
 	const { test, run } = play;
+	const { name } = entry;
 	const shot = await callPage(play.page, pageCheckpoint, {
 		test: test.name,
 		where,
-		settleFrames: run.settleFrames
+		settleFrames: run.settleFrames,
+		finish: entry.finish
 	});
 	if (shot.screen === void 0) throw new Error(`[game] Visual test "${test.name}", ${where}: the page gave no picture.\n  Serve a dev build with ${BACKEND[run.renderer]}: renderer.capture() answers only there.`);
 	const file = (kind) => baselineFile(run.dir, test.name, name, kind);
@@ -1882,7 +1938,7 @@ async function playSteps(play, found) {
 		const entry = stepEntry(test.name, step, index);
 		const where = `step ${index + 1} (${entry.kind === "checkpoint" ? "checkpoint" : entry.name})`;
 		if (entry.kind === "checkpoint") {
-			found.set(entry.name, await checkpoint(play, entry.name, where));
+			found.set(entry.name, await checkpoint(play, entry, where));
 			continue;
 		}
 		await callPage(play.page, pageStep, {
@@ -1901,13 +1957,15 @@ async function playSteps(play, found) {
 * @param play - The test and the run options; the page is opened here.
 * @param play.test - The test.
 * @param play.run - The run options.
-* @param url - The URL of the page the leg opens.
+* @param target - The page the leg opens: its URL, and the moment of the headless leg's clock.
+* @param target.url - The URL.
+* @param target.moment - The moment, epoch milliseconds.
 * @param headless - The result of the test in the headless leg.
 * @returns The result of the test with its pixel fields.
 * @throws {Error} When the page fails to open: that fails the leg.
 */
-async function browserTest(context, play, url, headless) {
-	const page = await openPage(context, url, play.run);
+async function browserTest(context, play, target, headless) {
+	const page = await openPage(context, target.url, play.run, target.moment);
 	const found = /* @__PURE__ */ new Map();
 	let failed;
 	try {
@@ -1954,7 +2012,10 @@ async function runBrowserLeg(setup, tests, run, headless, load = loadChromium) {
 	if (page === void 0) throw new Error("[game] The pixel leg needs the dev page.\n  Pass page: { url } in the setup, or run with --no-pixels.");
 	const chromium = await load();
 	const options = pageSize(setup, page);
-	const url = rendererUrl(page.url, run.renderer);
+	const target = {
+		url: rendererUrl(page.url, run.renderer),
+		moment: setup.app().clock.now()
+	};
 	const browser = await launchChrome(chromium, page.browser);
 	try {
 		const context = await browser.newContext(options);
@@ -1967,7 +2028,7 @@ async function runBrowserLeg(setup, tests, run, headless, load = loadChromium) {
 			results.push(before.error === void 0 ? await browserTest(context, {
 				test,
 				run
-			}, url, before) : before);
+			}, target, before) : before);
 		}
 		return results;
 	} finally {

package/llms.txt

@@ -12,7 +12,7 @@ Facts: Bun only. ESM only. `"sideEffects"` lists the root entry `./dist/index.mj
 - `@moku-labs/game/app/system` (the browser, the native shell): `systemShellOf`, `fromSystem`, `storeSave`, `createSystemApp`, the type `SystemModules`, over the optional peer `@moku-labs/system`. The one entry that names it, in types only: the page hands it the loaders.
 - `@moku-labs/game/cli` (node and bun only): `runCli`, the bin `moku-game`, `preparePage`, the editor's dev page, `watchKeys`, the watch that keeps `generated/` fresh next to it, and `watchEngine`, the watch that tells when the installed engine changed.
 - `@moku-labs/game/testing`: headless play, repro runs, isolated feature tests (`isolate`, `stub`), fake clock, the `fx` of a node for a unit test (`fakeFx`), in-memory save provider. No `node:` import.
-- `@moku-labs/game/visual` (node and bun only): the visual tests `defineVisualTest`, `runVisualTests`, `parseVisualArgv`. The bin runs them: `moku-game visual`.
+- `@moku-labs/game/visual` (node and bun only): the visual tests `defineVisualTest`, `runVisualTests`, `parseVisualArgv`. The bin runs them: `moku-game visual`. A step is a `/control` command or `{ checkpoint: name, finish?: boolean }`: a checkpoint lands every motion before its snapshot, `finish: false` keeps them running (same frames in both legs). Both legs run on one clock: the pixel leg's dev page runs on a fake clock at the headless app's `clock.now()` (`startMoment`), standing still like the headless one.
 - `@moku-labs/game/assets` (node and bun only): the asset key scanner, the production packer and the string compiler. The package bin `moku-game-assets` runs it.
 - `@moku-labs/game/inspect`: the read door of the editor, safe in a production build. See "Doors for the editor".
 - `@moku-labs/game/control`: the write door of the editor, dev builds only. See "Doors for the editor".
@@ -550,7 +550,7 @@ The graph. Modules `runner`, `gate`, `inbox`, `fx`, `features`. Runner methods s
 
 A screen is a projection whose `view` returns JSX. The game's `tsconfig.json` sets `"jsx": "react-jsx"` and `"jsxImportSource": "@moku-labs/game"`; screens are `.tsx` files. There is no DOM and no React.
 
-- Tags: `screen`, `layer`, `row`, `column`, `stack`, `spacer`, `panel` (swallows taps), `image` (`texture`, `fit?: "contain" | "cover" | "fill"`), `icon` (`name`, `fit?`), `text` (`content: string | Message`, or `bind={bind(Counter, "value")}` with `components={[Counter({ value })]}`; formats `int`, `mm:ss`, `h:mm:ss`, `duration`; `Countdown({ until })` with `bind(Countdown, "left", { format: "mm:ss" })` counts down to a `clock` moment; `style` is a text style key), `button` (`intent` + `payload`, or `local`, never both), `scroll` (`axis?: "x" | "y"` (`"y"`), fixed at spawn, another one later warns `ui:scroll-axis-fixed`; children for a short list, laid out as a column on `y` and a row on `x`, or the windowed form `rows`, `rowHeight`, `overscan?` (5), `row: index => node`, on `y` only: `axis: "x"` with `rows` throws `[game] A windowed scroll moves on y only.`; row state belongs in the model, a row that leaves the window loses its local state; `snap?: number[]` stops in offsets, kept inside `0..max`: a release glides to the stop nearest `offset + v × 260` (v in units a ms) on `1 − (1 − p)³` over `min(620, 260 + distance × 1.1)` ms; without `snap` a release flings, `v ×= 0.998` a ms until under 0.02, 0 when the finger rested over 50 ms; `offset?: number` (0) where it stands from the start, drawn there in its first frame, a new value glides there, the same value does nothing; hard edges, nothing passes on to a parent scroll; a press on a child that leaves the tap slop along the scroll's axis goes to the scroll and the child answers nothing, a finger on a moving scroll only stops it; every number in `time.delta` ms, so a time scale applies; the public component `ScrollState { offset, max, moving }` on its entity, whole units `0..max`, written when it changes and once with `moving: false` when it stops, read by a system and by `game.explain`; `app.ui.scroll(key, to)` and the visual step `{ scroll: { key, to } }` set it at once), `input` (a text field; its text lives in the component's `local`, see the ui README). Common props: `key`, `style`, `state: { active?, disabled?, selected? }`, `motion`, `components` (extra component values for the element's entity, such as a filter: `components={[Glow({ strength: 2 })]}`, or `DebugTrigger()`: five taps within 3000 ms of wall time on that view call `app.debug.overlay.open()` on a page with the agent flag, nothing elsewhere; put it on a `button` naming nothing); containers take `hosts?: string[]` (projections drawn inside the element: world views hang under it from the slot's first frame; a JSX projection is laid out in the slot's content box). Children draw and are hit in markup order at equal `zIndex`; the roots of a scene draw in the order of its `projections` (the `ui` layer sorts by `Order`; `ui: { sort: "none" }` keeps insertion order). `defineMotion({ when: "change" })` plays its `enter` and `exit` only for a commit or a popup, never when its screen mounts or unmounts; declare a motion at module level (`ui:motion-rebuilt` names a loop rebuilt in a view). Style adds `nineSlice`, `tint`, `offsetX`, `offsetY`, `scale`, `origin`, `fit: "contain"`; state variants `is: { hover, pressed, disabled, active, selected, covered }`. `popup(Component, props, { over })` stacks a popup over a kept one.
+- Tags: `screen`, `layer`, `row`, `column`, `stack`, `spacer`, `panel` (swallows taps), `image` (`texture`, `fit?: "contain" | "cover" | "fill"`), `icon` (`name`, `fit?`), `text` (`content: string | Message`, or `bind={bind(Counter, "value")}` with `components={[Counter({ value })]}`; formats `int`, `mm:ss`, `h:mm:ss`, `duration`; `Countdown({ until })` with `bind(Countdown, "left", { format: "mm:ss" })` counts down to a `clock` moment; `style` is a text style key), `button` (`intent` + `payload`, or `local`, never both), `scroll` (`axis?: "x" | "y"` (`"y"`), fixed at spawn, another one later warns `ui:scroll-axis-fixed`; children for a short list, laid out as a column on `y` and a row on `x`, or the windowed form `rows`, `rowHeight`, `overscan?` (5), `row: index => node`, on `y` only: `axis: "x"` with `rows` throws `[game] A windowed scroll moves on y only.`; row state belongs in the model, a row that leaves the window loses its local state; `snap?: number[]` stops in offsets, kept inside `0..max`: a release glides to the stop nearest `offset + v × 260` (v in units a ms) on `1 − (1 − p)³` over `min(620, 260 + distance × 1.1)` ms; without `snap` a release flings, `v ×= 0.998` a ms until under 0.02, 0 when the finger rested over 50 ms; `offset?: number` (0) where it stands from the start, drawn there in its first frame, a new value glides there, the same value does nothing; hard edges, nothing passes on to a parent scroll; a press on a child that leaves the tap slop along the scroll's axis goes to the scroll and the child answers nothing, a finger on a moving scroll only stops it; every number in `time.delta` ms, so a time scale applies; the public component `ScrollState { offset, max, moving }` on its entity, whole units `0..max`, written when it changes and once with `moving: false` when it stops, read by a system and by `game.explain`; `app.ui.scroll(key, to)` and the visual step `{ scroll: { key, to } }` set it at once), `input` (a text field; its text lives in the component's `local`, see the ui README). Common props: `key`, `style`, `state: { active?, disabled?, selected? }`, `motion`, `components` (extra component values for the element's entity, such as a filter: `components={[Glow({ strength: 2 })]}`, or `DebugTrigger()`: five taps within 3000 ms of wall time on that view call `app.debug.overlay.open()` on a page with the agent flag, nothing elsewhere; put it on a `button` naming nothing); containers take `hosts?: string[]` (projections drawn inside the element: world views hang under it from the slot's first frame; a JSX projection is laid out in the slot's content box). Children draw and are hit in markup order at equal `zIndex`; the roots of a scene draw in the order of its `projections` (the `ui` layer sorts by `Order`; `ui: { sort: "none" }` keeps insertion order). `defineMotion({ when: "change" })` plays its `enter` and `exit` only for a commit or a popup, never when its screen mounts or unmounts; declare a motion at module level (`ui:motion-rebuilt` names a loop rebuilt in a view). `motion.change` plays `Box` (the rects), `Transform` (the rest poses), the visual the element is drawn with (`Shape`, `Sprite`, `NineSlice`, `Text`, when a render or a restyle moves a number of it: `sweep`, `alpha`, `w`; a returned motion brings the numbers home from where they stand and the other fields land at once; the last motion of that name is cancelled first) and each extra of `components`, each as `(view, previous, next, hint)`; a dev build names any other `change` hook once, `ui:change-never-plays` `{ key, name }`. An element a render replaces (a root whose view returns another key or tag, a child of another key or tag) plays its exit with `"change"`, everything under it plays its own, and it leaves `find` at once, so the new element takes the keys they share. Style adds `nineSlice`, `tint`, `offsetX`, `offsetY`, `scale`, `origin`, `fit: "contain"`; state variants `is: { hover, pressed, disabled, active, selected, covered }`. `popup(Component, props, { over })` stacks a popup over a kept one.
 - Style vocabulary (`defineStyle`, plain data): flow `direction`, `wrap`, `justify`, `align`, `alignSelf`, `gap`, `grow`, `shrink`; box `padding`, `margin`, `width`, `height`, `minWidth`, `minHeight`, `maxWidth`, `maxHeight`, `aspect`, `overflow`; position `position`, `left`, `top`, `right`, `bottom`, `reason`; visual `fill`, `stroke`, `strokeWidth`, `radius`, `alpha`, `shape: "rect" | "triangle" | "arc"` (`"rect"`; a triangle fills the box pointing right; an arc is only a `stroke` of `strokeWidth` on the circle inscribed in the box, `min(width, height) − strokeWidth` across, from 12 o'clock clockwise over `sweep`), `dash` (dash length of the stroke, gaps of half a dash; not on an arc), `sweep` (0..1, default 1, clamped; 0 draws nothing, 1 a closed ring), `cap: "round" | "butt"` (`"round"`; the ends of an open arc); variants `is: { pressed?, disabled?, active?, selected? }` and `when: { portrait?, landscape?, tall?, wide? }`, each a partial style merged in when the flag holds. Lengths are reference units or `"safeArea.top" | "safeArea.right" | "safeArea.bottom" | "safeArea.left"`. No font size here: it comes from the text style.
 - `defineComponent(name, { local?, outcomes?, view(props, local) })`. A component with `outcomes` is a popup: `await fx(popup(Component, props))` opens the gate for its outcomes and resolves with `{ intent, payload }` of the pressed button. A button with `local` writes into the nearest component instance; it never reaches the graph.
 - `tr(key, params?)` returns a frozen `Message` `{ key, params }`; no locale is read at the call site. Strings live in `strings/<locale>.json` of any feature or sub-feature, as ICU MessageFormat 1 (`{n, plural, one {# order} other {# orders}}`, `select`, `selectordinal`, `number`, `date`, `time`; no skeletons, no `currency`). `bun run assets:keys` compiles them. The keys of the top-level features and the layers go into `generated/strings.<locale>.ts`, which one feature registers; a sub-feature's keys start with `<name>.` (`ep01.title`) and go into `generated/strings.<name>.<locale>.ts`, which the sub-feature registers lazily, `strings: { en: () => import("@generated/strings.ep01.en"), ru: () => import("@generated/strings.ep01.ru") }`. With `assets` composed those modules load and unload with the bundle named like the sub-feature: every way the bundle comes (a node entry, a scene's `bundles`, `load`, a restore, the `safeNode`) brings its strings, a locale switch brings them in the new locale, and while the bundle is not loaded a key of it gives `⟦key⟧` and `has(key)` is false. A compiled module calls the root helpers `messageArgument(value, intl)` (an element stays an element part, a list goes through `Intl.ListFormat`, a number through `Intl.NumberFormat`, else text) and `messageDuration(ms)` (`95_000` gives `{ minutes: 1, seconds: 35 }`). `app.i18n`: `locale()`, `setLocale(locale)` (async, emits `i18n:locale-changed`), `format(message, locale?)` returns `Part[]`, `plain(message)` returns a string, `has(key)`, `isKey(value)`, `locales()`, `replace(locale, messages)` (dev hot swap of a generated strings file). Config: `locale: "en"`, `fallback: "en"`, `locales: {}`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/game",
-  "version": "0.15.31",
+  "version": "0.15.33",
   "description": "2D puzzle game engine on TypeScript and PixiJS, built on @moku-labs/core.",
   "type": "module",
   "sideEffects": [