@moku-labs/game 0.0.1 → 0.0.2

package/dist/memory-CvgdnsQO.mjs

@@ -0,0 +1,259 @@
+import { applyPatches, createDraft, enablePatches, finishDraft } from "immer";
+//#region src/plugins/model/store/drafts.ts
+/** Root order of a commit result, so two commits never report the same roots in another order. */
+const rootOrder = Object.freeze([
+	"player",
+	"session",
+	"rng"
+]);
+/**
+* Turns on Immer's patch recording. Idempotent, and called from the state factory rather than at
+* module scope: a module-scope call would run on import, even when no app is created.
+*
+*/
+function enableDraftPatches() {
+	enablePatches();
+}
+/**
+* Freezes a tree and every branch of it. Immer freezes what it produces; this covers the trees
+* that never went through a draft — the initial trees and the ones handed to `restore()`.
+*
+* @param tree - The tree to freeze, in place.
+* @returns The same reference, now frozen.
+* @example
+* ```ts
+* const tree = deepFreeze({ player: { bag: ["key"] } });
+* Object.isFrozen(tree.player.bag); // true
+* ```
+*/
+function deepFreeze(tree) {
+	if (!tree || typeof tree !== "object") return tree;
+	for (const branch of Object.values(tree)) deepFreeze(branch);
+	return Object.freeze(tree);
+}
+/**
+* Maps one Immer patch to our own structural patch, so no Immer type reaches a public type.
+* A removal carries no value, and `exactOptionalPropertyTypes` forbids an explicit `undefined`.
+*
+* @param patch - The Immer patch.
+* @param path - Path of the patch inside its own tree, without the container segment.
+* @returns The structural patch.
+* @example
+* ```ts
+* toPatch({ op: "remove", path: ["doc", "player", "key"] }, ["player", "key"]);
+* // { op: "remove", path: ["player", "key"] }
+* ```
+*/
+function toPatch(patch, path) {
+	if (patch.op === "remove") return {
+		op: patch.op,
+		path
+	};
+	return {
+		op: patch.op,
+		path,
+		value: patch.value
+	};
+}
+/**
+* Derives the touched roots from the patches of one commit, in a fixed order.
+*
+* @param docPatches - Patches of the save document.
+* @param sessionPatches - Patches of the session tree.
+* @returns The roots a listener has to reconcile.
+* @example
+* ```ts
+* rootsOf([{ op: "add", path: ["rng", "streams", "dice"], value: 7 }], []); // ["rng"]
+* rootsOf([], [{ op: "replace", path: ["rolls"], value: 1 }]); // ["session"]
+* ```
+*/
+function rootsOf(docPatches, sessionPatches) {
+	const touched = /* @__PURE__ */ new Set();
+	for (const patch of docPatches) {
+		const [head] = patch.path;
+		if (head === "player" || head === "rng") touched.add(head);
+	}
+	if (sessionPatches.length > 0) touched.add("session");
+	return rootOrder.filter((root) => touched.has(root));
+}
+/**
+* Opens mutable drafts of the frozen save document and session tree.
+* Both live in one draft container, so one `finishDraft` closes the transaction and the patches
+* arrive in one list, tagged by their container key.
+*
+* @param doc - Frozen save document.
+* @param session - Frozen session tree.
+* @returns The open drafts of one transaction.
+* @example
+* ```ts
+* const pair = openDrafts({ player: { coins: 1 }, rng: { seed: 7, streams: {} } }, { rolls: 0 });
+* pair.session; // a mutable draft of { rolls: 0 }: a write never reaches the frozen input
+* ```
+*/
+function openDrafts(doc, session) {
+	return createDraft({
+		doc,
+		session
+	});
+}
+/**
+* Finishes the drafts: the new frozen trees, the patches per tree and the touched roots.
+* The drafts are revoked, so a draft that leaked into a view throws on the next touch instead of
+* corrupting the committed tree in silence.
+*
+* @param pair - Open drafts of one transaction.
+* @returns The frozen trees, the patches split by tree, and the touched roots.
+*/
+function finishDrafts(pair) {
+	const collected = [];
+	const finished = finishDraft(pair, (patches) => {
+		collected.push(...patches);
+	});
+	const docPatches = [];
+	const sessionPatches = [];
+	for (const patch of collected) {
+		const [container, ...path] = patch.path;
+		(container === "doc" ? docPatches : sessionPatches).push(toPatch(patch, path));
+	}
+	return {
+		doc: finished.doc,
+		session: finished.session,
+		patches: {
+			doc: docPatches,
+			session: sessionPatches
+		},
+		roots: rootsOf(docPatches, sessionPatches)
+	};
+}
+/**
+* Applies the patches of one commit to a document, the way a save seam stores what it was handed.
+* A whole-document patch carries the path `[]` and replaces the document. The input is left as it
+* is: the result is a new frozen document.
+*
+* @param document - The document the patches apply to.
+* @param patches - The patches of one commit, in order.
+* @returns The document after the patches.
+* @throws {Error} When a patch names a path the document does not have.
+* @example
+* ```ts
+* applyTo({ player: { coins: 0 } }, [{ op: "replace", path: ["player", "coins"], value: 4 }]);
+* // { player: { coins: 4 } }
+* ```
+*/
+function applyTo(document, patches) {
+	enablePatches();
+	return applyPatches(document, patches);
+}
+/**
+* Drops the drafts without a result: the base trees stay as they are and the drafts are revoked.
+*
+* @param pair - Open drafts of one transaction.
+*/
+function dropDrafts(pair) {
+	finishDraft(pair);
+}
+//#endregion
+//#region src/plugins/model/store/providers/memory.ts
+/** Seed of a save built by `saveOf` when the caller does not pin one. */
+const defaultSeed = 1;
+/** The base a patch applies to when the provider was never handed a document. */
+const noDocument = {};
+/**
+* Creates an in-memory provider that keeps what it was committed and records every call.
+* It is the default when a game configures no `playerProvider`, and the double every test uses:
+* `provider.calls` is the whole persistence protocol of one run, in order. The document lives as
+* long as the provider does, so a second app over the same instance reads what the first one
+* wrote, and nothing survives the process.
+*
+* `load()` reads the fixture, or everything committed since; without either, the player is new.
+* `commitDurable()` resolves at once: there is no disk behind it.
+*
+* @param fixture - The save `load()` starts from. Omitted: a new player.
+* @param fixture.state - The saved document.
+* @param fixture.version - Schema version of the saved document.
+* @returns A provider that keeps its document and records its calls.
+* @example
+* ```ts
+* // A new player is saved at once. One roll reaches the provider at the next rest node.
+* const provider = memory();
+* const game = await createHeadless(createGame(provider));
+*
+* await game.walk([{ at: "home", intent: "roll" }]);
+* provider.calls.map(call => call.method); // ["load", "commit", "commit"]
+* ```
+*/
+function memory(fixture) {
+	const calls = [];
+	const held = {
+		document: fixture?.state,
+		version: fixture?.version ?? 0
+	};
+	/**
+	* Applies the patches of one commit to the held document.
+	*
+	* @param patches - Doc patches since the last commit.
+	* @param version - Schema version this build writes.
+	* @throws {Error} When a patch names a path the held document does not have.
+	*/
+	const hold = (patches, version) => {
+		held.document = applyTo(held.document ?? noDocument, patches);
+		held.version = version;
+	};
+	return {
+		calls,
+		load: async () => {
+			calls.push({ method: "load" });
+			const document = held.document;
+			if (document === void 0) return null;
+			return {
+				state: document,
+				version: held.version
+			};
+		},
+		commit: (patches, version) => {
+			calls.push({
+				method: "commit",
+				patches,
+				version
+			});
+			hold(patches, version);
+		},
+		commitDurable: async (patches, txId, version) => {
+			calls.push({
+				method: "commitDurable",
+				patches,
+				txId,
+				version
+			});
+			hold(patches, version);
+		},
+		flush: async () => {
+			calls.push({ method: "flush" });
+		}
+	};
+}
+/**
+* Builds a save document from a player tree, with no rng streams drawn yet.
+* Short fixtures in tests read as `saveOf({ coins: 5 })` instead of spelling out the rng branch.
+*
+* @param player - Player tree of the save.
+* @param seed - Rng seed of the save.
+* @returns The save document.
+* @example
+* ```ts
+* // A returning player with 5 coins. The test starts from this save, not from `initialPlayer`.
+* saveOf({ coins: 5 }, 42); // { player: { coins: 5 }, rng: { seed: 42, streams: {} } }
+* const provider = memory({ state: saveOf({ coins: 5 }, 42), version: 1 });
+* ```
+*/
+function saveOf(player, seed = defaultSeed) {
+	return {
+		player,
+		rng: {
+			seed,
+			streams: {}
+		}
+	};
+}
+//#endregion
+export { enableDraftPatches as a, dropDrafts as i, saveOf as n, finishDrafts as o, deepFreeze as r, openDrafts as s, memory as t };

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