@moku-labs/game 0.7.0 → 0.8.0

package/dist/project.d.mts

@@ -13,8 +13,8 @@
  *
  * @example
  * ```ts
- * // The editor opens the fixture game with the default manifest and a slower debounce.
- * const options: ProjectOptions = { root: "tests/integration/merge-game", debounceMs: 120 };
+ * // The editor opens the mini game with the default manifest and a slower debounce.
+ * const options: ProjectOptions = { root: "tests/fixtures/mini-game", debounceMs: 120 };
  * ```
  */
 type ProjectOptions = {
@@ -29,7 +29,7 @@ type ProjectOptions = {
  *
  * @example
  * ```ts
- * const kind: JsxKind = "idProp"; // id="settingsBoard" on <Signboard>
+ * const kind: JsxKind = "idProp"; // id="infoPanel" on <Panel>
  * ```
  */
 type JsxKind = "literal" | "template" | "idProp" | "ident";
@@ -39,8 +39,8 @@ type JsxKind = "literal" | "template" | "idProp" | "ident";
  *
  * @example
  * ```ts
- * // node:board/merge, defined by the const `merge` of nodes/merge.ts.
- * const anchor: Anchor = { path: "nodes/merge.ts", binding: "merge" };
+ * // node:infoPopup/count, defined by the const `count` of nodes/count.ts.
+ * const anchor: Anchor = { path: "nodes/count.ts", binding: "count" };
  * ```
  */
 type Anchor = {
@@ -66,8 +66,8 @@ type Anchor = {
  *
  * @example
  * ```ts
- * index.symbols["flow:board"]; // { def: [{ path: "flows/board.ts", binding: "boardFlow" }] }
- * index.files["nodes/merge.ts"]?.state; // "ok"
+ * index.symbols["flow:infoPopup"]; // { def: [{ path: "flows/info.ts", binding: "infoFlow" }] }
+ * index.files["nodes/count.ts"]?.state; // "ok"
  * ```
  */
 type ProjectIndex = {
@@ -99,9 +99,9 @@ type ProjectIndex = {
  *
  * @example
  * ```ts
- * // An agent moved nodes/toast.ts to nodes/board/toast.ts and fixed the import of the board flow.
- * change.files; // ["flows/board.ts", "nodes/board/toast.ts", "nodes/toast.ts"]
- * change.moved; // [{ key: "node:board/toast", from: "nodes/toast.ts", to: "nodes/board/toast.ts" }]
+ * // An agent moved nodes/count.ts to nodes/info/count.ts and fixed the import of the info flow.
+ * change.files; // ["flows/info.ts", "nodes/count.ts", "nodes/info/count.ts"]
+ * change.moved; // [{ key: "node:infoPopup/count", from: "nodes/count.ts", to: "nodes/info/count.ts" }]
  * change.removed; // []
  * ```
  */
@@ -123,9 +123,9 @@ type ProjectChange = {
  *
  * @example
  * ```ts
- * // The editor opens the Home scene of the fixture game.
+ * // The editor opens the Home scene of the mini game.
  * const [found] = await project.find("scene:home");
- * [found?.path, found?.line, found?.range]; // ["features/home/scene.ts", 8, [8, 1, 13, 4]]
+ * [found?.path, found?.line, found?.range]; // ["features/home/scene.ts", 8, [8, 1, 12, 4]]
  * ```
  */
 type Found = Anchor & {
@@ -145,7 +145,7 @@ type ProjectApi = {
    * @example
    * ```ts
    * // The editor checks a node file before it opens it.
-   * project.index.files["nodes/merge.ts"]?.state; // "ok"
+   * project.index.files["nodes/count.ts"]?.state; // "ok"
    * ```
    */
   readonly index: ProjectIndex;
@@ -157,14 +157,14 @@ type ProjectApi = {
    * with a literal prop of the same name on their component (both the pattern and the prop come
    * back), then `*` patterns. An unknown key answers `[]`.
    *
-   * @param key - An engine id: `node:board/merge`, `flow:board`, `textStyle:ui.title`, `jsx:card2Picture`.
+   * @param key - An engine id: `node:infoPopup/count`, `flow:main`, `textStyle:ui.counter`, `jsx:infoPanelSpark`.
    * @returns One entry per place, in the order above; `broken` when the file does not parse now.
    * @example
    * ```ts
-   * // The editor jumps to the node the flow view clicked, and to the X of the settings board.
-   * (await project.find("node:board/merge"))[0]?.line; // 17, in "nodes/merge.ts"
-   * (await project.find("jsx:settingsBoardClose")).map(found => `${found.path}:${found.line}`);
-   * // ["features/ui/kit.tsx:844", "features/settings/settings.tsx:290"]
+   * // The editor jumps to the node the flow view clicked, and to the spark of the info panel.
+   * (await project.find("node:infoPopup/count"))[0]?.line; // 7, in "nodes/count.ts"
+   * (await project.find("jsx:infoPanelSpark")).map(found => `${found.path}:${found.line}`);
+   * // ["features/info/popup.tsx:65", "features/info/popup.tsx:79"]
    * ```
    */
   find(key: string): Promise<Found[]>;
@@ -198,9 +198,9 @@ type ProjectApi = {
    * @throws {Error} When the path leaves the root, by `..` or by a symlink.
    * @example
    * ```ts
-   * // The editor saved nodes/merge.ts through its own file layer.
-   * const index = await project.changed("nodes/merge.ts");
-   * index.files["nodes/merge.ts"]?.state; // "ok"
+   * // The editor saved nodes/count.ts through its own file layer.
+   * const index = await project.changed("nodes/count.ts");
+   * index.files["nodes/count.ts"]?.state; // "ok"
    * ```
    */
   changed(path: string): Promise<ProjectIndex>;
@@ -247,9 +247,9 @@ type IndexUi = {
  *   `--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"
  * ```
  */
 declare function runCli(argv: readonly string[], ui?: IndexUi): Promise<number>;
@@ -266,10 +266,10 @@ declare function runCli(argv: readonly string[], ui?: IndexUi): Promise<number>;
  *   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();
  * ```
  */

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 };