@moku-labs/game 0.15.31 → 0.15.32

package/dist/app/page.mjs

@@ -1,6 +1,7 @@
 import { r as systemSource, t as memory } from "../memory-CWlqhS7l.mjs";
 import { t as applyTo } from "../drafts-BawpSaVp.mjs";
 import { i as isControl } from "../dev-BNndV-hU.mjs";
+import { n as fakeClock, t as VISUAL_CLOCK } from "../fake-hnJcJeYf.mjs";
 import { n as read, r as watch, t as sources } from "../sources-DM5Zcl4o.mjs";
 import { t as resolveConfig } from "../config-B87aFTW-.mjs";
 //#region src/app/save.ts
@@ -211,6 +212,20 @@ function toError(thrown) {
 	return thrown instanceof Error ? thrown : new Error(String(thrown));
 }
 /**
+* The clock of the page: the device clock; on a dev page a visual test's pixel leg opened, the fake
+* clock its headless leg runs on, standing at the same moment (F86). The leg puts the moment on the
+* page before it loads, so the app never sees the device time.
+*
+* @returns The clock source of the page.
+*/
+function pageClock() {
+	if (typeof __MOKU_GAME_DEV__ !== "undefined" && __MOKU_GAME_DEV__) {
+		const moment = Reflect.get(globalThis, VISUAL_CLOCK);
+		if (typeof moment === "number") return fakeClock(moment);
+	}
+	return systemSource();
+}
+/**
 * Picks the start of the page from `?player=`: the named scenario's player and session, at the
 * device time. An unknown name is reported, and the page starts from the starting player.
 *
@@ -382,7 +397,7 @@ async function startPage(game, config, options = {}) {
 	const settings = resolveConfig(config);
 	const query = new URLSearchParams(location.search);
 	const { report, attach } = lateReporter();
-	const clock = systemSource();
+	const clock = pageClock();
 	const start = scenarioStart(query.get("player"), options.scenarios ?? {}, clock.now(), report);
 	const shell = options.system === void 0 ? void 0 : await options.system(settings, report);
 	const namespace = settings.native?.identifier ?? "moku-game";

package/dist/app.mjs

@@ -1,6 +1,6 @@
 import { Ft as audioPlugin, H as platformPlugin, i as screen, m as flattenFeatures, t as createApp, wt as effectsPlugin } from "./src-5qdNjLKN.mjs";
 import { t as memory } from "./memory-CWlqhS7l.mjs";
-import { n as isFakeClock, t as fakeClock } from "./fake-6mazmHK3.mjs";
+import { n as fakeClock, r as isFakeClock } from "./fake-hnJcJeYf.mjs";
 //#region src/app/define.ts
 /**
 * The moment the default fake clock starts at, in epoch milliseconds. A test stamps times from it.

package/dist/{fake-6mazmHK3.mjs → fake-hnJcJeYf.mjs}

@@ -101,5 +101,11 @@ function fakeClock(start = 0) {
 function isFakeClock(source) {
 	return fakeClocks.has(source);
 }
+/**
+* The global a visual test's pixel leg sets on the dev page before it loads (F86): the moment of
+* the fake clock its headless leg runs on. The page of a dev build then runs on `fakeClock` at
+* that moment, so both legs see the same `clock.now()`. Not in the root.
+*/
+const VISUAL_CLOCK = "__mokuVisualClock";
 //#endregion
-export { isFakeClock as n, fakeClock as t };
+export { fakeClock as n, isFakeClock as r, VISUAL_CLOCK as t };

package/dist/testing.mjs

@@ -1,6 +1,6 @@
 import { en as refuseStart, in as type, m as flattenFeatures, t as createApp, tn as exit } from "./src-5qdNjLKN.mjs";
 import { n as saveOf, t as memory } from "./memory-CWlqhS7l.mjs";
-import { t as fakeClock } from "./fake-6mazmHK3.mjs";
+import { n as fakeClock } from "./fake-hnJcJeYf.mjs";
 import { i as stepFrames, r as runRepro, t as createHeadless } from "./headless-Bxxl_mQX.mjs";
 //#region src/testing/fake-fx.ts
 /** The node path a refused `fx.start` names when the test gives none. */

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

@@ -1,4 +1,4 @@
-import { Vr as Api$3, Y as Api, nn as Api$1, wr as Api$2 } from "./types-D27I4Q7b.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-DHamyZq1.mjs";
 import { N as InputApi } from "./types-BAp9HdR4.mjs";
 import { r as Repro } from "./headless-f31cEZ7f.mjs";
@@ -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-DEo5Hndx.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,3 +1,4 @@
+import { t as VISUAL_CLOCK } from "./fake-hnJcJeYf.mjs";
 import { n as read, t as sources } from "./sources-DM5Zcl4o.mjs";
 import { n as commands, t as run } from "./run-BnriyKUu.mjs";
 import path from "node:path";
@@ -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".

package/package.json

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