@moku-labs/game 0.7.1 → 0.8.0

package/dist/project.mjs

@@ -2862,10 +2862,10 @@ const DEFAULT_DEBOUNCE_MS = 75;
 *   installed: `[game] The project index needs the "typescript" package.`
 * @example
 * ```ts
-* // The editor opens the fixture game and answers where a node and a text style live.
-* const project = await openProject({ root: "tests/integration/merge-game" });
-* Object.keys(project.index.files).length; // 111
-* (await project.find("textStyle:ui.title"))[0]?.line; // 39, in "features/ui/styles.ts"
+* // The editor opens the mini game and answers where a node and a text style live.
+* const project = await openProject({ root: "tests/fixtures/mini-game" });
+* Object.keys(project.index.files).length; // 21
+* (await project.find("textStyle:ui.counter"))[0]?.line; // 16, in "features/home/styles.ts"
 * project.close();
 * ```
 */
@@ -3075,9 +3075,9 @@ async function runCommand(project, options, ui) {
 *   `--check` that found a broken file or a conflict; else `0`.
 * @example
 * ```ts
-* // An agent asks where a node of the fixture game lives.
-* await runCli(["--root", "tests/integration/merge-game", "where", "node:board/merge"]);
-* // 0, and the console printed "nodes/merge.ts:17"
+* // An agent asks where a node of the mini game lives.
+* await runCli(["--root", "tests/fixtures/mini-game", "where", "node:infoPopup/count"]);
+* // 0, and the console printed "nodes/count.ts:7"
 * ```
 */
 async function runCli(argv, ui = createBrandConsole()) {

package/dist/registry-DlpRCibU.mjs

@@ -0,0 +1,384 @@
+//#region src/plugins/flow/runner/journal.ts
+/** FNV-1a 32-bit offset basis. */
+const OFFSET_BASIS = 2166136261;
+/** FNV-1a 32-bit prime. */
+const PRIME = 16777619;
+/** Separates the parts of a hashed edge, so "a|b" and "a" + "b" never collide. */
+const SEPARATOR = "\0";
+/**
+* Hashes text with FNV-1a, 32 bit. Pure and deterministic: the same text always gives the same
+* eight hexadecimal characters, in every runtime.
+*
+* @param text - The text to hash.
+* @returns Eight lowercase hexadecimal characters.
+* @example
+* ```ts
+* hashText("board/merge"); // "53ceca70"
+* ```
+*/
+function hashText(text) {
+	let hash = OFFSET_BASIS;
+	for (const character of text) hash = Math.imul(hash ^ (character.codePointAt(0) ?? 0), PRIME);
+	return (hash >>> 0).toString(16).padStart(8, "0");
+}
+/**
+* Hashes one edge, so a replay against edited code fails loudly in dev.
+*
+* @param path - Path of the node that produced the outcome.
+* @param outcome - Outcome name.
+* @param next - Rendered edge target.
+* @returns The digest of the three parts together.
+* @example
+* ```ts
+* entryHash("board/merge", "done", "board/awaitIntent"); // "e881176b"
+* ```
+*/
+function entryHash(path, outcome, next) {
+	return hashText([
+		path,
+		outcome,
+		next
+	].join(SEPARATOR));
+}
+/**
+* Appends an entry with the next index and its hash, and drops the oldest entries above the limit.
+* The index keeps counting while entries are dropped, so two entries never share a number.
+*
+* @param state - Runner state that holds the journal.
+* @param entry - The taken edge without `index` and `hash`.
+* @param limit - Journal entries kept between checkpoints.
+* @returns The stored entry.
+*/
+function pushEntry(state, entry, limit) {
+	const stored = {
+		...entry,
+		index: state.journalIndex,
+		hash: entryHash(entry.path, entry.outcome, entry.next)
+	};
+	state.journalIndex += 1;
+	state.journal.push(stored);
+	if (state.journal.length > limit) state.journal.splice(0, state.journal.length - limit);
+	return stored;
+}
+/**
+* Clears the journal at a checkpoint. The running index is kept, and so is the array itself: a
+* reader that holds `history()` sees the compaction.
+*
+* @param state - Runner state that holds the journal.
+*/
+function compact(state) {
+	state.journal.length = 0;
+}
+//#endregion
+//#region src/plugins/flow/runner/registry.ts
+/**
+* Creates the empty flow map. It lives in its own function because the plugin's lint rule L5
+* refuses a collection built inside an exported declaration.
+*
+* @returns An empty map of flow id to flow.
+* @example
+* ```ts
+* emptyFlows().size; // 0
+* ```
+*/
+function emptyFlows() {
+	return /* @__PURE__ */ new Map();
+}
+/**
+* Adds a flow and every flow it reaches by reference to the map. The first flow under an id wins,
+* so a collision is visible to `validateGraph` instead of silently replacing a flow.
+*
+* @param flow - The flow to add.
+* @param flows - The map being filled.
+*/
+function addFlow(flow, flows) {
+	if (flows.has(flow.id)) return;
+	flows.set(flow.id, flow);
+	for (const entry of Object.values(flow.nodes)) if (entry.kind === "flow") addFlow(entry, flows);
+}
+/**
+* Collects every flow reachable from the main flow by reference, plus the registered extras.
+* The main flow is the first entry: `describeGraph` reads it as the entry point of the graph.
+*
+* @param main - The top-level flow.
+* @param extra - Flows added with `register`, not reachable by reference.
+* @returns Flow id to flow, main first.
+* @example
+* ```ts
+* [...collectFlows(mainFlow, []).keys()]; // ["main", "board"]: the main flow first
+* ```
+*/
+function collectFlows(main, extra) {
+	const flows = emptyFlows();
+	addFlow(main, flows);
+	for (const flow of extra) addFlow(flow, flows);
+	return flows;
+}
+/**
+* Renders a position as a path: the node of every frame, outermost first.
+*
+* @param stack - One frame per nesting level.
+* @returns The path, for example `"board/awaitIntent"`; empty without a position.
+* @example
+* ```ts
+* const board = { flow: "main", node: "board", input: null };
+* framePath([board, { flow: "board", node: "merge", input: null }]); // "board/merge"
+* ```
+*/
+function framePath(stack) {
+	return stack.map((frame) => frame.node).join("/");
+}
+/**
+* Picks the flow a path continues in after one entry: the sub-flow itself, or, behind a slot, the
+* first contribution in order that has the next segment as a node. A path keeps node names only,
+* so two contributions of one slot with the same node name cannot be told apart; `validateGraph`
+* warns about that.
+*
+* @param entry - The entry the path just passed.
+* @param next - The next segment of the path.
+* @param contributionsOf - Reads the contributions of a slot, in order.
+* @returns The flow to go on in, or `undefined` when the path ends here.
+*/
+function flowBehind(entry, next, contributionsOf) {
+	if (entry.kind === "flow") return entry;
+	if (entry.kind !== "slot") return void 0;
+	return contributionsOf(entry.name).find((item) => Object.hasOwn(item.flow.nodes, next))?.flow;
+}
+/**
+* Reads no contributions: the default of `findNode` for a caller that has no features API.
+*
+* @returns An empty list.
+* @example
+* ```ts
+* noContributions(); // []
+* ```
+*/
+function noContributions() {
+	return [];
+}
+/**
+* Finds the node, sub-flow or slot a path names, starting at the main flow. A path descends one
+* sub-flow per segment, and through a slot into the contribution that has the next segment; a
+* segment after a plain node finds nothing.
+*
+* @param main - The top-level flow.
+* @param path - A path as `framePath` renders it.
+* @param contributionsOf - Reads the contributions of a slot, in order. Without it a path ends at
+*   a slot.
+* @returns Where the path leads, or `undefined` when no such node exists.
+* @example
+* ```ts
+* findNode(mainFlow, "board/awaitIntent")?.trail;
+* // [{ flow: "main", node: "board" }, { flow: "board", node: "awaitIntent" }]
+* findNode(mainFlow, "afterOrder/show", () => [{ flow: rewardFlow }])?.trail;
+* // [{ flow: "main", node: "afterOrder" }, { flow: "rewardPopup", node: "show" }]
+* ```
+*/
+function findNode(main, path, contributionsOf = noContributions) {
+	const names = path.split("/").filter(Boolean);
+	const trail = [];
+	let flow = main;
+	for (const [step, name] of names.entries()) {
+		const entry = flow.nodes[name];
+		if (!entry) return void 0;
+		trail.push({
+			flow: flow.id,
+			node: name
+		});
+		if (step === names.length - 1) return {
+			flow,
+			name,
+			entry,
+			trail
+		};
+		const behind = flowBehind(entry, names[step + 1] ?? "", contributionsOf);
+		if (behind === void 0) return void 0;
+		flow = behind;
+	}
+}
+/**
+* Renders an edge target as a string: a node name, `"exit:win"` or `"map:node"`.
+*
+* @param target - The target as the edge table holds it.
+* @returns The rendered target.
+* @example
+* ```ts
+* renderTarget("home"); // "home"
+* renderTarget({ kind: "exit", outcome: "win" }); // "exit:win"
+* ```
+*/
+function renderTarget(target) {
+	if (typeof target === "string") return target;
+	return target.kind === "exit" ? `exit:${target.outcome}` : `map:${target.target}`;
+}
+/**
+* Renders the edge table of one flow.
+*
+* @param flow - The flow to render.
+* @returns Node name to outcome name to rendered target.
+* @example
+* ```ts
+* renderEdges(boardFlow).awaitIntent?.leave; // "exit:left"
+* ```
+*/
+function renderEdges(flow) {
+	const edges = {};
+	for (const [name, row] of Object.entries(flow.edges)) {
+		const rendered = {};
+		for (const [outcome, target] of Object.entries(row)) rendered[outcome] = renderTarget(target);
+		edges[name] = rendered;
+	}
+	return edges;
+}
+/**
+* Maps every node and flow a feature brought to the name of that feature.
+*
+* @param features - Features API.
+* @returns Node or flow object to feature name.
+*/
+function collectOwners(features) {
+	const owners = /* @__PURE__ */ new Map();
+	for (const { name, description } of features.all()) {
+		for (const node of description.nodes ?? []) owners.set(node, name);
+		for (const flow of description.flows ?? []) owners.set(flow, name);
+	}
+	return owners;
+}
+/**
+* Describes one entry of a flow: its flags, its scene, its outcome names, and the slot, sub-flow
+* or owning feature when it has one.
+*
+* @param flow - The flow that holds the entry.
+* @param name - Name of the entry inside that flow.
+* @param entry - The node, sub-flow or slot.
+* @param owner - Name of the feature that brought it, when a feature did.
+* @returns The entry as JSON.
+* @example
+* ```ts
+* describeNode(mainFlow, "home", home, undefined).rest; // true
+* describeNode(mainFlow, "board", boardFlow, "board").subFlow; // "board"
+* ```
+*/
+function describeNode(flow, name, entry, owner) {
+	const node = entry.kind === "node" ? entry : void 0;
+	return {
+		flow: flow.id,
+		node: name,
+		rest: node?.rest ?? false,
+		over: node?.over ?? false,
+		checkpoint: node?.checkpoint ?? false,
+		barrier: node?.barrier ?? false,
+		outcomes: Object.keys(entry.outcomes),
+		...node?.scene === void 0 ? {} : { scene: node.scene },
+		...entry.kind === "slot" ? { slot: entry.name } : {},
+		...entry.kind === "flow" ? { subFlow: entry.id } : {},
+		...owner === void 0 ? {} : { owner }
+	};
+}
+/**
+* Describes every entry of one flow.
+*
+* @param flow - The flow to describe.
+* @param owners - Node or flow object to feature name.
+* @returns Node name to description.
+* @example
+* ```ts
+* describeNodes(boardFlow, new Map()).merge?.outcomes; // ["done", "rejected"]
+* ```
+*/
+function describeNodes(flow, owners) {
+	const nodes = {};
+	for (const [name, entry] of Object.entries(flow.nodes)) nodes[name] = describeNode(flow, name, entry, owners.get(entry) ?? owners.get(flow));
+	return nodes;
+}
+/**
+* Collects the slot names of every flow of the graph. `describe()` and `validate` both read the
+* contributions of exactly these slots.
+*
+* @param flows - Every collected flow by id.
+* @returns The slot names, in the order the graph declares them, each once.
+* @example
+* ```ts
+* slotNames(collectFlows(mainFlow, [])); // ["afterOrder"]
+* ```
+*/
+function slotNames(flows) {
+	const names = [];
+	for (const flow of flows.values()) for (const entry of Object.values(flow.nodes)) if (entry.kind === "slot" && !names.includes(entry.name)) names.push(entry.name);
+	return names;
+}
+/**
+* Renders the whole graph as JSON without running the game: nodes, flags, outcomes, edges,
+* slots and who contributed. Edge targets become `"node"`, `"exit:win"`, `"map:node"`.
+*
+* @param flows - Every collected flow by id, the main flow first, as `collectFlows` returns them.
+* @param features - Features API: owners and slot contributions.
+* @returns The graph as plain JSON.
+*/
+function describeGraph(flows, features) {
+	const owners = collectOwners(features);
+	const described = {};
+	const slots = {};
+	for (const flow of flows.values()) described[flow.id] = {
+		nodes: describeNodes(flow, owners),
+		start: flow.start,
+		edges: renderEdges(flow)
+	};
+	for (const name of slotNames(flows)) slots[name] = features.contributions(name).map(({ feature, flow, order }) => ({
+		feature,
+		flow: flow.id,
+		order
+	}));
+	return {
+		main: [...flows.keys()][0] ?? "",
+		flows: described,
+		slots
+	};
+}
+/**
+* Compares two object keys without a locale, so the rendering is the same everywhere.
+*
+* @param first - First key.
+* @param second - Second key.
+* @returns A negative number, zero or a positive number.
+* @example
+* ```ts
+* compareKeys("edges", "nodes"); // -1
+* ```
+*/
+function compareKeys(first, second) {
+	if (first === second) return 0;
+	return first < second ? -1 : 1;
+}
+/**
+* Renders a JSON value with its object keys sorted, so two equal graphs written in a different
+* order hash the same.
+*
+* @param value - Any JSON value.
+* @returns The value as text.
+* @example
+* ```ts
+* stableJson({ b: 1, a: 2 }); // '{"a":2,"b":1}'
+* ```
+*/
+function stableJson(value) {
+	if (Array.isArray(value)) return `[${value.map((item) => stableJson(item)).join(",")}]`;
+	if (typeof value !== "object" || !value) return JSON.stringify(value) ?? "";
+	return `{${Object.entries(value).filter(([, item]) => item !== void 0).toSorted(([first], [second]) => compareKeys(first, second)).map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
+}
+/**
+* Hashes a graph description. A bookmark of a plain rest node is accepted only while this hash
+* is unchanged.
+*
+* @param graph - Result of `describeGraph`.
+* @returns Eight lowercase hexadecimal characters.
+* @example
+* ```ts
+* graphHash({ main: "main", flows: {}, slots: {} }); // "cfb16c03"
+* ```
+*/
+function graphHash(graph) {
+	return hashText(stableJson(graph));
+}
+//#endregion
+export { graphHash as a, pushEntry as c, framePath as i, describeGraph as n, slotNames as o, findNode as r, compact as s, collectFlows as t };

package/dist/{run-Bcyg32M5.mjs → run-CUPSFM85.mjs}

@@ -1,190 +1,7 @@
-import { a as sheetAlone, u as graphHash } from "./capture-fpd83Mi5.mjs";
+import { a as sheetAlone } from "./capture-BX5Gfoty.mjs";
 import { n as isDev, r as notInstalled, t as controlRefused } from "./dev-wKLgOw7c.mjs";
-import { a as isProjectionTarget, i as recordCheat, o as readTarget, r as isTainted, s as defineCommand, t as inputOrEmpty } from "./input-CK4nxBO1.mjs";
-//#region src/plugins/flow/headless.ts
-const noPayload = null;
-/** Seed of a repro that pins no rng state, the seed `saveOf` writes. */
-const defaultSeed = 1;
-/**
-* Turns whatever `run()` rejected with into an error that can be thrown again.
-*
-* @param value - The rejection value.
-* @returns The value itself when it is an error, a wrapped one otherwise.
-* @example
-* ```ts
-* asError("offline").message; // "[game] The headless run failed.\n  offline."
-* ```
-*/
-function asError(value) {
-	if (value instanceof Error) return value;
-	return /* @__PURE__ */ new Error(`[game] The headless run failed.\n  ${String(value)}.`);
-}
-/**
-* Starts the one loop unless the app's own `onStart` already did, and keeps a fatal error until
-* someone asks for it. `run()` rejects only on a fatal error, and nobody awaits it here.
-*
-* @param app - The started app.
-* @returns The holder of the fatal error.
-*/
-function startLoop(app) {
-	const fatal = { error: void 0 };
-	if (app.flow.state().running) return fatal;
-	app.flow.run().catch((error) => {
-		fatal.error = error;
-	});
-	return fatal;
-}
-/**
-* Waits until the loop rests for the first time, or ends. An empty route walks nowhere: it only
-* waits for the gate the loop opens at the node it enters, so a start that is a chain of transit
-* nodes is played out before anything reads the game.
-*
-* @param app - The started app whose loop is running.
-* @param fatal - Holder of the fatal error of `run()`.
-* @returns Resolves once the loop rests at its first rest node.
-* @throws {Error} When the loop failed fatally instead of reaching a rest node.
-*/
-async function settleAtFirstRest(app, fatal) {
-	await app.flow.walk([]).catch((error) => {
-		throw asError(fatal.error ?? error);
-	});
-	if (fatal.error !== void 0) throw asError(fatal.error);
-}
-/**
-* Starts an app headless: sets flow mode `"fast"`, awaits `app.start()`, starts `flow.run()`
-* unless the app's own `onStart` already did, and waits until the loop rests for the first time.
-* `game.state().path` therefore names the first rest node of the graph as soon as the call
-* resolves. A fatal error of the loop rejects this call, and a later one is re-thrown by `walk`
-* and by `stop`, so a headless test never loses it.
-*
-* @param app - An app that is not started yet.
-* @returns The game: walk it, answer it, read it, stop it.
-* @throws {Error} When the loop failed fatally before it reached its first rest node.
-* @example
-* ```ts
-* // A test starts the merge game without a screen. The call resolves at the first rest node.
-* const game = await createHeadless(app);
-*
-* game.state().path; // "home": the transit node "boot" was played out
-* game.state().mode; // "fast"
-* await game.stop();
-* ```
-*/
-async function createHeadless(app) {
-	app.flow.setMode("fast");
-	await app.start();
-	const fatal = startLoop(app);
-	await settleAtFirstRest(app, fatal);
-	return {
-		walk: async (route) => {
-			const state = await app.flow.walk(route).catch((error) => {
-				throw asError(fatal.error ?? error);
-			});
-			if (fatal.error !== void 0) throw asError(fatal.error);
-			return state;
-		},
-		answer: (answer) => app.flow.gate.answer(answer),
-		state: () => app.flow.state(),
-		history: () => app.flow.history(),
-		stop: async () => {
-			await app.stop();
-			if (fatal.error !== void 0) throw asError(fatal.error);
-		}
-	};
-}
-/**
-* Reads the rest node a repro starts at: its checkpoint, or the start of the main flow.
-*
-* @param app - The started app.
-* @param repro - Starting state, optional checkpoint and the route.
-* @returns The path of the node the repro enters.
-* @throws {Error} When the graph has no main flow to start from.
-*/
-function reproPath(app, repro) {
-	if (repro.checkpoint !== void 0) return repro.checkpoint;
-	const graph = app.flow.describe();
-	const start = graph.flows[graph.main]?.start;
-	if (start === void 0) throw new Error(`[game] runRepro() found no flow "${graph.main}" to start from.\n  Name the checkpoint the repro was taken at.`);
-	return start;
-}
-/**
-* Builds the bookmark a repro is entered with: its state, its checkpoint and the hash of the
-* graph that runs now, so a checkpoint is accepted and any other rest node is checked. The route
-* is not part of it: the caller walks it after the restore.
-*
-* @param app - The started app.
-* @param repro - Starting state, optional checkpoint and the route.
-* @returns The bookmark to restore.
-* @throws {Error} When the repro names no checkpoint and the graph has no main flow.
-* @example
-* ```ts
-* // The game.restore command loads a bug report taken at the "home" checkpoint.
-* const bookmark = reproBookmark(app, { player: { coins: 7 }, checkpoint: "home", route: [] });
-* bookmark.path; // "home"
-* bookmark.rng; // { seed: 1, streams: {} }: the repro pinned no rng
-* await app.flow.restore(bookmark);
-* ```
-*/
-function reproBookmark(app, repro) {
-	return {
-		path: reproPath(app, repro),
-		input: noPayload,
-		player: repro.player,
-		session: repro.session ?? {},
-		rng: repro.rng ?? {
-			seed: defaultSeed,
-			streams: {}
-		},
-		graph: graphHash(app.flow.describe())
-	};
-}
-/**
-* Plays a repro: starts the app headless, restores the bookmark built from its state and
-* checkpoint, then walks its route. The app keeps running, so the caller can read more than the
-* result and stops it itself.
-*
-* @param app - An app that is not started yet.
-* @param repro - Starting state, optional checkpoint and the route.
-* @returns The path the run ended at, and the committed state.
-* @example
-* ```ts
-* // A bug report on the dice game: "reset keeps my coins". Replay it from the "home" checkpoint.
-* const reset = { at: "home", intent: "reset" };
-* const result = await runRepro(app, { player: { coins: 7 }, checkpoint: "home", route: [reset] });
-*
-* result.player; // { coins: 0 }; result.path is ["home"]
-* await app.stop(); // the app keeps running after the run
-* ```
-*/
-async function runRepro(app, repro) {
-	const game = await createHeadless(app);
-	await app.flow.restore(reproBookmark(app, repro));
-	const state = await game.walk(repro.route);
-	const ended = app.flow.bookmark();
-	return {
-		path: state.stack.map((frame) => frame.node),
-		player: ended.player,
-		session: ended.session
-	};
-}
-/**
-* Steps the frame loop by hand: `count` calls of `app.time.step(deltaMs)`. A headless game has no
-* frame source, so this is the only thing that moves the frame phases.
-*
-* @param app - A started app.
-* @param count - Number of frames.
-* @param deltaMs - Milliseconds per frame.
-* @example
-* ```ts
-* // A headless game has no frame source: the test moves the six frame phases by hand.
-* stepFrames(app, 2, 16);
-* app.time.snapshot(); // frame: 2, delta: 16, elapsed: 32
-* ```
-*/
-function stepFrames(app, count, deltaMs) {
-	for (let frame = 0; frame < count; frame += 1) app.time.step(deltaMs);
-}
-//#endregion
+import { n as reproBookmark } from "./headless-CvamCUcR.mjs";
+import { a as isProjectionTarget, i as recordCheat, o as readTarget, r as isTainted, s as defineCommand, t as inputOrEmpty } from "./input-z_35Jwfn.mjs";
 //#region src/plugins/anim/control.ts
 /**
 * @file anim plugin — the anim command of the `/control` door: switch reduced motion. Dev builds
@@ -1282,4 +1099,4 @@ async function run(app, command, ...input) {
 	};
 }
 //#endregion
-export { stepFrames as a, runRepro as i, commands as n, createHeadless as r, run as t };
+export { commands as n, run as t };

package/dist/{runtime-HTlmRb81.d.mts → runtime-CvDZZg1S.d.mts}

@@ -1,4 +1,4 @@
-import { a as JsxChild, m as UiIntrinsicElements, t as DescriptionNode } from "./types-BaUUcIaN.mjs";
+import { a as JsxChild, m as UiIntrinsicElements, t as DescriptionNode } from "./types-DgdMLZnV.mjs";
 
 //#region src/plugins/ui/jsx/runtime.d.ts
 /** What the compiler passes as props: the children plus whatever the tag declared. */

package/dist/{sources-DVWJ8nfr.mjs → sources-BBUd15vQ.mjs}

@@ -1,6 +1,6 @@
 import { i as scaleByFits, w as Layer } from "./visual-DUvvPPCt.mjs";
 import { r as notInstalled } from "./dev-wKLgOw7c.mjs";
-import { c as defineSource, n as cheatsOf, o as readTarget, r as isTainted, t as inputOrEmpty } from "./input-CK4nxBO1.mjs";
+import { c as defineSource, n as cheatsOf, o as readTarget, r as isTainted, t as inputOrEmpty } from "./input-z_35Jwfn.mjs";
 //#region src/plugins/flow/doors/read.ts
 /**
 * @file flow/doors — `read` and `watch`, the `/inspect` side. Neither changes the game.