@moku-labs/game 0.8.0 → 0.9.0

package/dist/{capture-BX5Gfoty.mjs → capture-fpd83Mi5.mjs}

@@ -1,3 +1,386 @@
+//#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
 //#region src/plugins/renderer/monitor/picture.ts
 /** Size of the badge number in CSS pixels; the picture draws it times the resolution. */
 const BADGE_FONT_PX = 12;
@@ -768,4 +1151,4 @@ async function captureFrame(mctx, options) {
 	return shot === void 0 ? void 0 : answerOf(mctx, shot, options.against);
 }
 //#endregion
-export { sheetAlone as a, servePaused as i, captureFrame as n, serveCaptures as r, cancelCaptures as t };
+export { sheetAlone as a, findNode as c, slotNames as d, compact as f, servePaused as i, framePath as l, captureFrame as n, collectFlows as o, pushEntry as p, serveCaptures as r, describeGraph as s, cancelCaptures as t, graphHash as u };

package/dist/{commands-C1kIfOG5.d.mts → commands-DuwCxK5t.d.mts}

@@ -1,9 +1,8 @@
-import { N as Time, Z as Api, _ as Bookmark, b as FlowState } from "./types-ERb2Y9U5.mjs";
-import { C as Captured, T as DebugSwitches, k as Api$2, m as Api$1 } from "./types-BWzCSRM2.mjs";
-import { t as HeadlessApp } from "./headless-q98SwADR.mjs";
-import { n as Command, r as ControlApp } from "./types-CDSKa0vl.mjs";
-import { H as InputApi } from "./types-DgdMLZnV.mjs";
-import { b as AnimApi, p as ScenesApi, t as AudioApi, v as UiApi } from "./types-DlgsfOmW.mjs";
+import { At as FlowState, C as Captured, Dt as Bookmark, T as DebugSwitches, Ut as Time, k as Api$2, m as Api$1, sn as Api } from "./types-B0v5VVa3.mjs";
+import { t as HeadlessApp } from "./headless-SCQXJxQf.mjs";
+import { n as Command, r as ControlApp } from "./types-DUMoYPYe.mjs";
+import { H as InputApi } from "./types-xXfyk56Q.mjs";
+import { b as AnimApi, p as ScenesApi, t as AudioApi, v as UiApi } from "./types-VZVWwqCg.mjs";
 
 //#region src/plugins/flow/doors/commands.d.ts
 /**

package/dist/control.d.mts

@@ -1,7 +1,7 @@
-import { t as HeadlessApp } from "./headless-q98SwADR.mjs";
-import { i as InputArguments, n as Command, o as InputSchema, s as Ran } from "./types-CDSKa0vl.mjs";
-import { t as commands } from "./commands-C1kIfOG5.mjs";
-import { t as defineCommand } from "./define-BPpZcpxW.mjs";
+import { t as HeadlessApp } from "./headless-SCQXJxQf.mjs";
+import { i as InputArguments, n as Command, o as InputSchema, s as Ran } from "./types-DUMoYPYe.mjs";
+import { t as commands } from "./commands-DuwCxK5t.mjs";
+import { t as defineCommand } from "./define-B6pHpdBi.mjs";
 
 //#region src/plugins/flow/doors/dev.d.ts
 /**

package/dist/control.mjs

@@ -1,4 +1,4 @@
 import { t as controlRefused } from "./dev-wKLgOw7c.mjs";
 import { s as defineCommand } from "./input-z_35Jwfn.mjs";
-import { n as commands, t as run } from "./run-CUPSFM85.mjs";
+import { n as commands, t as run } from "./run-CofJEdYx.mjs";
 export { commands, controlRefused, defineCommand, run };

package/dist/{define-BPpZcpxW.d.mts → define-B6pHpdBi.d.mts}

@@ -1,5 +1,5 @@
-import { t as HeadlessApp } from "./headless-q98SwADR.mjs";
-import { c as Source, n as Command, o as InputSchema } from "./types-CDSKa0vl.mjs";
+import { t as HeadlessApp } from "./headless-SCQXJxQf.mjs";
+import { c as Source, n as Command, o as InputSchema } from "./types-DUMoYPYe.mjs";
 
 //#region src/plugins/flow/doors/define.d.ts
 /**

package/dist/{headless-CvamCUcR.mjs → headless-BsNdJs9W.mjs}

@@ -1,4 +1,4 @@
-import { a as graphHash } from "./registry-DlpRCibU.mjs";
+import { u as graphHash } from "./capture-fpd83Mi5.mjs";
 //#region src/plugins/flow/headless.ts
 const noPayload = null;
 /** Seed of a repro that pins no rng state, the seed `saveOf` writes. */

package/dist/{headless-q98SwADR.d.mts → headless-SCQXJxQf.d.mts}

@@ -1,4 +1,4 @@
-import { A as Api, C as RouteStep, R as Json, X as RngState, b as FlowState, k as Answer, t as Api$1, x as JournalEntry } from "./types-ERb2Y9U5.mjs";
+import { At as FlowState, Bt as Api, Jt as Json, Nt as RouteStep, jt as JournalEntry, on as RngState, ut as Api$1, zt as Answer } from "./types-B0v5VVa3.mjs";
 
 //#region src/plugins/flow/headless.d.ts
 /**

package/dist/hot.d.mts

@@ -14,8 +14,10 @@
 type HotOptions = {
   /**
    * The files that get the footer. Default: `.tsx` files, `styles.ts`, `view.ts`,
-   * `animations.ts`, `effects.ts` and `generated/strings.<locale>.ts`. Bun runs it as the load
-   * filter on the absolute path, so it should not anchor at the start.
+   * `animations.ts`, `effects.ts`, any `.ts` directly in a `styles/`, `motion/`, `effects/` or
+   * `views/` folder, and in `world/projections/` or `world/layout/`, and
+   * `generated/strings.<locale>.ts`. Bun runs it as the load filter on the absolute path, so it
+   * should not anchor at the start.
    */
   include?: RegExp;
   /**

package/dist/hot.mjs

@@ -7,16 +7,18 @@ import path from "node:path";
 * update and hands the new exports to the running game through `globalThis.__moku_hot`. The `ui`
 * plugin installs that handler in dev builds only. What swaps: styles, components, projections,
 * animations, text styles, emitters and generated strings. A view module is a `.tsx` file, a
-* `styles.ts`, a `view.ts`, an `animations.ts`, an `effects.ts` or a generated
-* `generated/strings.<locale>.ts`; a logic module never gets the footer, so its save reaches the
-* root and the page reloads and restores its state. The plugin lives in `[serve.static]` of
+* `styles.ts`, a `view.ts`, an `animations.ts`, an `effects.ts`, any `.ts` directly in a
+* `styles/`, `motion/`, `effects/` or `views/` folder, any `.ts` directly in `world/projections/`
+* or `world/layout/`, or a generated `generated/strings.<locale>.ts`; a logic module never gets
+* the footer (`world/components/` and `world/systems/` included: they are registered at start), so
+* its save reaches the root and the page reloads and restores its state. The plugin lives in `[serve.static]` of
 * `bunfig.toml`, the dev server only: `Bun.build` of a production build never loads it.
 */
 /**
-* The default view modules: `.tsx` files, `styles.ts`, `view.ts`, `animations.ts`, `effects.ts`
-* and the generated strings of a locale.
+* The default view modules: the view files by name or by kind folder. Two literals joined, so
+* each stays readable.
 */
-const DEFAULT_INCLUDE = /(\.tsx|\/styles\.ts|\/view\.ts|\/animations\.ts|\/effects\.ts|\/generated\/strings\.[\w-]+\.ts)$/;
+const DEFAULT_INCLUDE = new RegExp(`(${/\.tsx|\/styles\.ts|\/view\.ts|\/animations\.ts|\/effects\.ts|\/generated\/strings\.[\w-]+\.ts/.source}|${/\/(?:styles|motion|effects|views)\/[^/]+\.ts|\/world\/(?:projections|layout)\/[^/]+\.ts/.source})$`);
 /** The generated strings of one locale, the one file under `generated/` that swaps. */
 const STRINGS = /\/generated\/strings\.[\w-]+\.ts$/;
 /** The default folders and test files that never hot swap. The outer group only scopes the `$`. */