@moku-labs/game 0.8.0 → 0.10.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/cli.d.mts

@@ -0,0 +1,70 @@
+//#region src/cli.d.ts
+/**
+ * What the dev page of `preparePage` is written with besides the game.
+ *
+ * @example
+ * ```ts
+ * // The editor against an engine working tree: its agent on the page, the tree's recipe in Bun.
+ * const options: PreparePageOptions = {
+ *   agents: ["@moku-labs/editor/agent/page"],
+ *   preload: ["../engine/scripts/tree/preload.ts"],
+ *   servePlugins: ["../engine/scripts/tree/bundle.ts"]
+ * };
+ * ```
+ */
+type PreparePageOptions = {
+  /** Agent modules the dev page passes to startPage, in order. Each default-exports a PageAgent. Bare specifiers or absolute paths. */agents?: readonly string[]; /** Files Bun preloads in the serving process. Relative paths resolve against the cwd. */
+  preload?: readonly string[]; /** Bun plugins the dev page bundles with, after the hot plugin. Relative paths resolve against the cwd. */
+  servePlugins?: readonly string[];
+};
+/**
+ * The written dev page: what a Bun server imports, and the config it runs under.
+ *
+ * @example
+ * ```ts
+ * // The editor re-runs itself under the page's bunfig, in the game folder.
+ * const { html, bunfig } = await preparePage("games/timber");
+ * Bun.spawn([process.execPath, `--config=${bunfig}`, Bun.main, html, "--root", "games/timber"], { cwd: "games/timber" });
+ * ```
+ */
+type PreparedPage = {
+  /** Absolute path of `<root>/.moku/index.html`: the HTML a Bun server imports. */html: string; /** Absolute path of `<root>/.moku/bunfig.toml`: pass it as `bun --config=<bunfig>`. */
+  bunfig: string;
+};
+/**
+ * Runs one `moku-game` command line in this process: `dev`, `build`, `native <verb>`, `keys`,
+ * `pack` or `help`, with `--root`, `--preload` and `--serve-plugin` before or after the command
+ * word. Every line goes through the branded console; nothing exits the process.
+ *
+ * @param argv - The arguments after the bin.
+ * @returns The exit code.
+ * @example
+ * ```ts
+ * // bin/moku-game.mjs in a game folder:
+ * await runCli(["dev", "--port", "0"]); // 0 after Ctrl+C; stdout had "http://localhost:<port>/"
+ * await runCli(["help"]); // 0
+ * ```
+ */
+declare function runCli(argv: readonly string[]): Promise<number>;
+/**
+ * Writes a game's dev page into `<root>/.moku/` for a server the caller starts: `index.html`,
+ * `dev.ts`, `main.ts` with the scenarios of `tests/scenarios/` (and, with agents, the agents and
+ * the game's `.dev` modules), and `bunfig.toml` with the engine's hot plugin. It starts no server
+ * and no watcher, and throws the `[game]` errors of `moku-game dev`.
+ *
+ * @param root - The game folder, relative to the cwd or absolute.
+ * @param options - The agents, the preloads and the extra bundler plugins.
+ * @returns The absolute paths of the HTML and the bunfig.
+ * @throws {Error} When the game has no `config.ts` or `index.ts`, a config value is refused, the
+ *   game does not resolve `@moku-labs/game/hot`, or a preload or plugin is not a file.
+ * @example
+ * ```ts
+ * // The editor bin, started with --root games/timber:
+ * const { preparePage } = await import(Bun.resolveSync("@moku-labs/game/cli", root));
+ * await preparePage("games/timber", { agents: ["@moku-labs/editor/agent/page"] });
+ * // { html: "<cwd>/games/timber/.moku/index.html", bunfig: "<cwd>/games/timber/.moku/bunfig.toml" }
+ * ```
+ */
+declare function preparePage(root: string, options?: PreparePageOptions): Promise<PreparedPage>;
+//#endregion
+export { PreparePageOptions, PreparedPage, preparePage, runCli };