@moku-labs/game 0.2.0 → 0.3.0

package/dist/dev-CQYJPmcD.mjs

@@ -0,0 +1,1183 @@
+//#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;
+/** Padding around the badge number, in picture pixels. */
+const BADGE_PADDING = 2;
+/** The largest sheet width the cells are scaled down to, before the gutters. */
+const SHEET_MAX_WIDTH = 2048;
+/** Gap around and between the cells of a sheet, in picture pixels. */
+const SHEET_GUTTER = 8;
+/** Background of a sheet, shown in the gutters. */
+const SHEET_BACKGROUND = "#202020";
+/** The largest channel delta that still counts as the same pixel: the visual runner's default. */
+const PIXEL_THRESHOLD = 24;
+/** How much of the way to white a matching grey pixel keeps: `255 - (255 - grey) × 0.4`. */
+const FADE_KEEP = .4;
+/** Bytes of one pixel: red, green, blue and alpha. */
+const CHANNELS = 4;
+/** The alpha of a pixel no one sees through: every pixel of the diff picture. */
+const OPAQUE = 255;
+/** The value of a channel in white, where a matching pixel fades to. */
+const WHITE = 255;
+/** A pixel that differs, on the diff picture: opaque `#ff0000`. */
+const DIFF_PIXEL = [
+	255,
+	0,
+	0,
+	OPAQUE
+];
+/** The Rec. 601 luma weights: how much red, green and blue make the grey of a pixel. */
+const LUMA = {
+	red: .299,
+	green: .587,
+	blue: .114
+};
+/** Bytes encoded per `String.fromCodePoint` call, well under the argument limit of an engine. */
+const ENCODE_CHUNK = 32768;
+/**
+* Builds the error of two pictures that cannot be compared.
+*
+* @returns The error, ready to throw.
+* @example
+* ```ts
+* differentSizes().message.startsWith("[game] game.capture: the pictures differ in size."); // true
+* ```
+*/
+function differentSizes() {
+	return /* @__PURE__ */ new Error("[game] game.capture: the pictures differ in size.\n  Capture both at the same canvas size.");
+}
+/**
+* Brings a box in reference units onto the picture: both corners through `toScreen`, the canvas
+* origin taken off, times the resolution, rounded to whole pixels.
+*
+* @param box - The box in reference units.
+* @param toScreen - The viewport map from reference units to client CSS pixels.
+* @param origin - The top-left corner of the canvas on the page, in CSS pixels.
+* @param resolution - Picture pixels per CSS pixel.
+* @returns The rect in picture pixels.
+* @example
+* ```ts
+* pictureRect({ x: 570, y: 1155, width: 283.5, height: 82 }, point => point, { x: 0, y: 0 }, 2);
+* // { x: 1140, y: 2310, w: 567, h: 164 }
+* ```
+*/
+function pictureRect(box, toScreen, origin, resolution) {
+	const topLeft = toScreen({
+		x: box.x,
+		y: box.y
+	});
+	const bottomRight = toScreen({
+		x: box.x + box.width,
+		y: box.y + box.height
+	});
+	return {
+		x: Math.round((topLeft.x - origin.x) * resolution),
+		y: Math.round((topLeft.y - origin.y) * resolution),
+		w: Math.round((bottomRight.x - topLeft.x) * resolution),
+		h: Math.round((bottomRight.y - topLeft.y) * resolution)
+	};
+}
+/**
+* Numbers the views of a legend: sorted by the top edge of their rect, then the left edge, and
+* numbered from 1 in that order.
+*
+* @param found - The views with their address and rect.
+* @returns The numbered entries, a fresh array.
+* @example
+* ```ts
+* numberLegend([{ projection: "hud", key: "claim", rect: { x: 1140, y: 2310, w: 567, h: 164 } }])[0]?.n; // 1
+* ```
+*/
+function numberLegend(found) {
+	return found.toSorted((left, right) => left.rect.y - right.rect.y || left.rect.x - right.rect.x).map((entry, index) => ({
+		n: index + 1,
+		...entry
+	}));
+}
+/**
+* Draws one badge: the label in white on a black box, its top-left corner at the point.
+*
+* @param context - The 2D context of the picture.
+* @param label - The text, a number.
+* @param at - The top-left corner, in picture pixels.
+* @param resolution - Picture pixels per CSS pixel; the label is 12 CSS pixels high.
+*/
+function drawBadge(context, label, at, resolution) {
+	const size = BADGE_FONT_PX * resolution;
+	context.font = `${String(size)}px sans-serif`;
+	context.textBaseline = "top";
+	const width = context.measureText(label).width;
+	context.fillStyle = "#000000";
+	context.fillRect(at.x, at.y, width + 4, size + 4);
+	context.fillStyle = "#ffffff";
+	context.fillText(label, at.x + BADGE_PADDING, at.y + BADGE_PADDING);
+}
+/**
+* Draws the badge of every legend entry at the top-left corner of its rect, in legend order.
+*
+* @param context - The 2D context of the picture.
+* @param legend - The numbered entries.
+* @param resolution - Picture pixels per CSS pixel.
+*/
+function drawLegend(context, legend, resolution) {
+	for (const entry of legend) drawBadge(context, String(entry.n), entry.rect, resolution);
+}
+/**
+* Lays a contact sheet out: `ceil(sqrt(frames))` columns, as many rows as needed, every cell the
+* picture scaled by `min(1, 2048 / (columns × width))` with its aspect kept, an 8 px gutter around
+* and between the cells, left to right and top to bottom.
+*
+* @param frames - How many pictures, 2 to 12.
+* @param width - Width of one picture, in pixels.
+* @param height - Height of one picture, in pixels.
+* @returns The grid, the scale, the size of the sheet and the rect of every cell.
+* @example
+* ```ts
+* sheetLayout(5, 400, 300).cells[3]; // { x: 8, y: 316, w: 400, h: 300 }
+* ```
+*/
+function sheetLayout(frames, width, height) {
+	const columns = Math.ceil(Math.sqrt(frames));
+	const rows = Math.ceil(frames / columns);
+	const scale = Math.min(1, SHEET_MAX_WIDTH / (columns * width));
+	const w = Math.max(1, Math.round(width * scale));
+	const h = Math.max(1, Math.round(height * scale));
+	const cells = Array.from({ length: frames }, (_, index) => ({
+		x: SHEET_GUTTER + index % columns * (w + SHEET_GUTTER),
+		y: SHEET_GUTTER + Math.floor(index / columns) * (h + SHEET_GUTTER),
+		w,
+		h
+	}));
+	return {
+		columns,
+		rows,
+		scale,
+		width: columns * w + (columns + 1) * SHEET_GUTTER,
+		height: rows * h + (rows + 1) * SHEET_GUTTER,
+		cells
+	};
+}
+/**
+* One byte of a picture, 0 past its end.
+*
+* @param data - The RGBA bytes.
+* @param at - The index of the byte.
+* @returns The byte.
+* @example
+* ```ts
+* byteAt(new Uint8ClampedArray([10, 20, 30, 255]), 1); // 20
+* ```
+*/
+function byteAt(data, at) {
+	return data[at] ?? 0;
+}
+/**
+* Tells whether two pixels differ: any RGBA channel by more than 24.
+*
+* @param current - The bytes of the current picture.
+* @param earlier - The bytes of the earlier picture.
+* @param at - The index of the pixel's first byte.
+* @returns True when the pixels differ.
+* @example
+* ```ts
+* pixelDiffers(new Uint8ClampedArray([125, 0, 0, 255]), new Uint8ClampedArray([100, 0, 0, 255]), 0); // true
+* ```
+*/
+function pixelDiffers(current, earlier, at) {
+	for (let channel = at; channel < at + CHANNELS; channel += 1) if (Math.abs(byteAt(current, channel) - byteAt(earlier, channel)) > PIXEL_THRESHOLD) return true;
+	return false;
+}
+/**
+* The grey of a pixel: its red, green and blue by the luma weights.
+*
+* @param data - The RGBA bytes.
+* @param at - The index of the pixel's first byte.
+* @returns The grey, 0 to 255.
+* @example
+* ```ts
+* greyOf(new Uint8ClampedArray([10, 20, 30, 255]), 0); // 18.15
+* ```
+*/
+function greyOf(data, at) {
+	return LUMA.red * byteAt(data, at) + LUMA.green * byteAt(data, at + 1) + LUMA.blue * byteAt(data, at + 2);
+}
+/**
+* Compares two pictures pixel by pixel into the diff picture: `#ff0000` where a pixel differs,
+* the current pixel faded elsewhere (its grey, then `255 - (255 - grey) × 0.4`), always opaque.
+*
+* @param current - The current picture.
+* @param earlier - The earlier picture.
+* @returns The RGBA bytes of the diff picture.
+* @throws {Error} When the two pictures differ in size.
+* @example
+* ```ts
+* const grey = { width: 1, height: 1, data: new Uint8ClampedArray([10, 20, 30, 255]) };
+* [...diffPixels(grey, grey)]; // [160, 160, 160, 255]
+* ```
+*/
+function diffPixels(current, earlier) {
+	if (current.width !== earlier.width || current.height !== earlier.height) throw differentSizes();
+	const out = new Uint8ClampedArray(current.width * current.height * CHANNELS);
+	const now = current.data;
+	for (let at = 0; at < out.length; at += CHANNELS) {
+		if (pixelDiffers(now, earlier.data, at)) {
+			out.set(DIFF_PIXEL, at);
+			continue;
+		}
+		const faded = WHITE - (WHITE - greyOf(now, at)) * FADE_KEEP;
+		out.set([
+			faded,
+			faded,
+			faded,
+			OPAQUE
+		], at);
+	}
+	return out;
+}
+/**
+* Decodes a PNG data URL into a bitmap a 2D context draws.
+*
+* @param url - The `data:image/png;base64,…` URL.
+* @returns The bitmap.
+*/
+async function decodePicture(url) {
+	const binary = atob(url.slice(url.indexOf(",") + 1));
+	const bytes = Uint8Array.from(binary, (char) => char.codePointAt(0) ?? 0);
+	return createImageBitmap(new Blob([bytes], { type: "image/png" }));
+}
+/**
+* Encodes a canvas as a PNG data URL.
+*
+* @param canvas - The canvas.
+* @returns The `data:image/png;base64,…` URL.
+*/
+async function encodePicture(canvas) {
+	const blob = await canvas.convertToBlob({ type: "image/png" });
+	const bytes = new Uint8Array(await blob.arrayBuffer());
+	let binary = "";
+	for (let start = 0; start < bytes.length; start += ENCODE_CHUNK) binary += String.fromCodePoint(...bytes.subarray(start, start + ENCODE_CHUNK));
+	return `data:image/png;base64,${btoa(binary)}`;
+}
+/**
+* Makes a canvas and its 2D context.
+*
+* @param width - Width in pixels.
+* @param height - Height in pixels.
+* @returns The canvas and the context.
+* @throws {Error} When the browser gives no 2D context.
+*/
+function canvasOf(width, height) {
+	const canvas = new OffscreenCanvas(width, height);
+	const context = canvas.getContext("2d");
+	if (context === null) throw new Error("[game] game.capture got no 2D context from OffscreenCanvas.\n  Capture in a browser that draws 2D on an OffscreenCanvas.");
+	return {
+		canvas,
+		context
+	};
+}
+/**
+* Draws the badges of a legend on a picture.
+*
+* @param png - The picture.
+* @param legend - The numbered entries, measured on the frame of the picture.
+* @param resolution - Picture pixels per CSS pixel.
+* @returns The PNG data URL of the numbered picture.
+*/
+async function legendPicture(png, legend, resolution) {
+	const bitmap = await decodePicture(png);
+	const { canvas, context } = canvasOf(bitmap.width, bitmap.height);
+	context.drawImage(bitmap, 0, 0);
+	drawLegend(context, legend, resolution);
+	return encodePicture(canvas);
+}
+/**
+* Lays several pictures of one canvas out on a contact sheet, each with its frame number. The
+* first picture gives the size of a cell.
+*
+* @param pictures - The PNG data URLs, in frame order.
+* @param resolution - Picture pixels per CSS pixel, for the badges.
+* @returns The PNG data URL of the sheet.
+*/
+async function sheetPicture(pictures, resolution) {
+	const [head, ...tail] = pictures;
+	const first = await decodePicture(head);
+	const bitmaps = [first, ...await Promise.all(tail.map((png) => decodePicture(png)))];
+	const layout = sheetLayout(bitmaps.length, first.width, first.height);
+	const { canvas, context } = canvasOf(layout.width, layout.height);
+	context.fillStyle = SHEET_BACKGROUND;
+	context.fillRect(0, 0, layout.width, layout.height);
+	for (const [index, bitmap] of bitmaps.entries()) {
+		const cell = layout.cells[index];
+		if (cell === void 0) continue;
+		context.drawImage(bitmap, cell.x, cell.y, cell.w, cell.h);
+		drawBadge(context, String(index + 1), cell, resolution);
+	}
+	return encodePicture(canvas);
+}
+/**
+* Reads the pixels of a bitmap through a canvas of its size.
+*
+* @param context - A 2D context as large as the bitmap.
+* @param bitmap - The bitmap.
+* @returns Its pixels.
+*/
+function pixelsOf(context, bitmap) {
+	context.clearRect(0, 0, bitmap.width, bitmap.height);
+	context.drawImage(bitmap, 0, 0);
+	return context.getImageData(0, 0, bitmap.width, bitmap.height);
+}
+/**
+* Draws the pixel diff of the current picture against an earlier one, and the badges of the
+* current frame's legend over it when there is one.
+*
+* @param png - The current picture.
+* @param against - The earlier picture.
+* @param legend - The legend of the current frame, or `undefined`.
+* @param resolution - Picture pixels per CSS pixel.
+* @returns The PNG data URL of the diff picture.
+* @throws {Error} When the two pictures differ in size.
+*/
+async function diffPicture(png, against, legend, resolution) {
+	const [current, earlier] = await Promise.all([decodePicture(png), decodePicture(against)]);
+	if (current.width !== earlier.width || current.height !== earlier.height) throw differentSizes();
+	const { canvas, context } = canvasOf(current.width, current.height);
+	const before = pixelsOf(context, earlier);
+	const now = pixelsOf(context, current);
+	context.putImageData(new ImageData(diffPixels(now, before), current.width, current.height), 0, 0);
+	if (legend !== void 0) drawLegend(context, legend, resolution);
+	return encodePicture(canvas);
+}
+//#endregion
+//#region src/plugins/renderer/monitor/capture.ts
+/** Drawn frames a sheet waits for game time to grow before it gives up. */
+const MAX_WAIT_FRAMES = 600;
+/** Fewest and most frames of a sheet. */
+const SHEET_FRAMES = {
+	min: 2,
+	max: 12
+};
+/** Longest spacing of two frames of a sheet, in milliseconds of game time. */
+const SHEET_MAX_MS = 5e3;
+/** The options, in the order the messages name them. */
+const OPTION_NAMES = [
+	"legend",
+	"layers",
+	"sheet",
+	"against"
+];
+/**
+* Builds the error of a sheet combined with an option that draws on one picture.
+*
+* @returns The error, ready to throw.
+* @example
+* ```ts
+* sheetAlone().message; // "[game] game.capture takes a sheet on its own.\n  Drop legend and against, or drop sheet."
+* ```
+*/
+function sheetAlone() {
+	return /* @__PURE__ */ new Error("[game] game.capture takes a sheet on its own.\n  Drop legend and against, or drop sheet.");
+}
+/**
+* Builds the error of a layer name the scene does not declare.
+*
+* @param name - The name asked for.
+* @param scene - The layer names of the scene.
+* @returns The error, ready to throw.
+* @example
+* ```ts
+* layerMissing("sky", ["board", "hud"]).message;
+* // '[game] game.capture: layer "sky" is not in the scene.\n  Use one of "board", "hud".'
+* ```
+*/
+function layerMissing(name, scene) {
+	const fix = scene.length === 0 ? "Declare the layers of the scene first" : `Use one of ${scene.map((layer) => JSON.stringify(layer)).join(", ")}`;
+	return /* @__PURE__ */ new Error(`[game] game.capture: layer "${name}" is not in the scene.\n  ${fix}.`);
+}
+/**
+* Builds the error of an option that needs a 2D canvas where there is none.
+*
+* @param option - The first option given.
+* @returns The error, ready to throw.
+* @example
+* ```ts
+* needsCanvas("legend").message.startsWith("[game] game.capture needs OffscreenCanvas for legend."); // true
+* ```
+*/
+function needsCanvas(option) {
+	return /* @__PURE__ */ new Error(`[game] game.capture needs OffscreenCanvas for ${option}.\n  Capture in a browser, or leave the option out.`);
+}
+/**
+* Builds the error of a running sheet whose game time stood still.
+*
+* @returns The error, ready to throw.
+* @example
+* ```ts
+* timeStood().message.startsWith("[game] game.capture sheet: game time did not advance."); // true
+* ```
+*/
+function timeStood() {
+	return /* @__PURE__ */ new Error("[game] game.capture sheet: game time did not advance.\n  Set game.timeScale above 0 or pause the game.");
+}
+/**
+* The options a capture was given: `legend` when true, the others when present.
+*
+* @param options - The options of `capture()`.
+* @returns Their names, in the order the messages name them.
+* @example
+* ```ts
+* givenOptions({ legend: false, layers: ["hud"] }); // ["layers"]
+* ```
+*/
+function givenOptions(options) {
+	return OPTION_NAMES.filter((name) => name === "legend" ? options.legend === true : options[name] !== void 0);
+}
+/**
+* Tells whether a sheet is in range: 2 to 12 whole frames, above 0 and at most 5000 ms apart.
+*
+* @param sheet - The sheet.
+* @returns True when it is.
+* @example
+* ```ts
+* sheetInRange({ frames: 6, everyMs: 100 }); // true
+* ```
+*/
+function sheetInRange(sheet) {
+	const { frames, everyMs } = sheet;
+	return Number.isInteger(frames) && frames >= SHEET_FRAMES.min && frames <= SHEET_FRAMES.max && Number.isFinite(everyMs) && everyMs > 0 && everyMs <= SHEET_MAX_MS;
+}
+/**
+* Refuses option values `capture()` cannot draw.
+*
+* @param options - The options of `capture()`.
+* @param scene - The layer names of the scene, `world.projection.layers()`.
+* @throws {Error} When a sheet comes with `legend` or `against`, when a layer is not in the scene
+*   or the list is empty, and when a sheet is out of range.
+*/
+function checkCaptureOptions(options, scene) {
+	const { legend, layers, sheet, against } = options;
+	if (sheet !== void 0 && (legend === true || against !== void 0)) throw sheetAlone();
+	if (layers?.length === 0) throw new Error("[game] game.capture takes at least one layer.\n  Pass the layer names to draw, or leave layers out.");
+	const missing = layers?.find((name) => !scene.includes(name));
+	if (missing !== void 0) throw layerMissing(missing, scene);
+	if (sheet !== void 0 && !sheetInRange(sheet)) throw new Error("[game] game.capture takes a sheet of 2 to 12 frames, every 1 to 5000 ms.\n  Pass { frames, everyMs } in that range.");
+}
+/**
+* Tells whether a view of a layer is drawn when only some layers are.
+*
+* @param layers - The layers drawn; every layer when `undefined`.
+* @param layer - The layer of the view, or `undefined` when it names none.
+* @returns True when the view is in the picture.
+* @example
+* ```ts
+* drawnIn(["hud"], "board"); // false
+* ```
+*/
+function drawnIn(layers, layer) {
+	return layers === void 0 || layer !== void 0 && layers.includes(layer);
+}
+/**
+* The layer names of the scene.
+*
+* @param mctx - Domain context of the capture.
+* @returns The names, in draw order.
+*/
+function sceneLayers(mctx) {
+	return mctx.ctx.deps.world.projection.layers().map((spec) => spec.name);
+}
+/**
+* The layer containers a picture of some layers leaves out.
+*
+* @param mctx - Domain context of the capture.
+* @param layers - The layers drawn; every layer when `undefined`.
+* @returns The containers of the other layers.
+*/
+function hiddenLayers(mctx, layers) {
+	const hidden = [];
+	if (layers === void 0) return hidden;
+	for (const name of sceneLayers(mctx)) {
+		const container = layers.includes(name) ? void 0 : mctx.deps.sync.layerContainer(name);
+		if (container !== void 0) hidden.push(container);
+	}
+	return hidden;
+}
+/**
+* Where the canvas is on the page, so a rect of the viewport becomes a rect of the picture.
+*
+* @param canvas - The canvas of the application.
+* @returns Its top-left corner in CSS pixels; the origin when there is no canvas.
+*/
+function canvasOrigin(canvas) {
+	const rect = canvas?.getBoundingClientRect();
+	return {
+		x: rect?.left ?? 0,
+		y: rect?.top ?? 0
+	};
+}
+/**
+* Measures the legend of the frame just drawn: every entity of the world with a projection
+* address and visible bounds, in a layer drawn, placed on the picture and numbered.
+*
+* @param mctx - Domain context of the capture.
+* @param layers - The layers drawn; every layer when `undefined`.
+* @returns The numbered entries.
+*/
+function measureLegend(mctx, layers) {
+	const world = mctx.ctx.deps.world;
+	const { host, viewport, sync } = mctx.deps;
+	const origin = canvasOrigin(host.canvas());
+	const resolution = host.resolution();
+	const found = [];
+	for (const { id } of world.ecs.snapshot().entities) {
+		const address = world.projection.keyOf(id);
+		const box = address === void 0 ? void 0 : sync.boundsOf(id);
+		if (address === void 0 || box === void 0 || !drawnIn(layers, sync.layerOf(id))) continue;
+		found.push({
+			projection: address.projection,
+			key: address.key,
+			rect: pictureRect(box, viewport.toScreen, origin, resolution)
+		});
+	}
+	return numberLegend(found);
+}
+/**
+* Takes the picture of the frame just drawn. The legend and the extract's render happen now,
+* synchronously, so both show this frame; only the encoding of the PNG comes later.
+*
+* @param mctx - Domain context of the capture.
+* @param take - The layers drawn and whether the legend is measured.
+* @returns The shot, or `undefined` when Pixi could not read the frame.
+*/
+async function takeShot(mctx, take) {
+	const legend = take.legend ? measureLegend(mctx, take.layers) : void 0;
+	const elapsed = mctx.ctx.deps.time.snapshot().elapsed;
+	const png = await mctx.deps.host.extract(hiddenLayers(mctx, take.layers));
+	return png === void 0 ? void 0 : {
+		png,
+		legend,
+		elapsed
+	};
+}
+/**
+* Queues a picture for the end of the first drawn frame `due` accepts.
+*
+* @param mctx - Domain context of the capture.
+* @param take - The layers drawn and whether the legend is measured.
+* @param due - True when the frame just drawn is the one to take.
+* @param whilePaused - Takes the shot instead when the game pauses before that frame came.
+* @returns The shot, once that frame was drawn.
+*/
+function queueShot(mctx, take, due, whilePaused) {
+	return new Promise((resolve, reject) => {
+		mctx.ctx.state.monitor.captures.push({
+			...take,
+			due,
+			whilePaused,
+			waited: 0,
+			resolve,
+			reject
+		});
+	});
+}
+/**
+* The picture of the next drawn frame; at once while the clock is paused, since no frame comes.
+*
+* @param mctx - Domain context of the capture.
+* @param take - The layers drawn and whether the legend is measured.
+* @returns The shot.
+*/
+function nextShot(mctx, take) {
+	const now = () => takeShot(mctx, take);
+	if (mctx.ctx.deps.time.isPaused()) return now();
+	return queueShot(mctx, take, () => true, now);
+}
+/**
+* Steps the clock by some game time, the way `game.step` does, and takes the frame it drew.
+* Async, so a throwing step rejects the shot instead of throwing at the caller.
+*
+* @param mctx - Domain context of the capture.
+* @param take - The layers drawn and whether the legend is measured.
+* @param stepMs - The game time to step, in milliseconds.
+* @returns The shot.
+*/
+async function steppedShot(mctx, take, stepMs) {
+	mctx.ctx.log.debug("moku:dev", {
+		command: "renderer.capture",
+		step: stepMs
+	});
+	mctx.ctx.deps.time.step(stepMs);
+	return takeShot(mctx, take);
+}
+/**
+* The next frame of a sheet, `everyMs` of game time after the last one. A paused clock is stepped
+* by `everyMs` once; a running one is waited for, and stepped by what is left of `everyMs` when
+* the game pauses first, by nothing when an earlier capture stepped the clock past it.
+*
+* @param mctx - Domain context of the capture.
+* @param layers - The layers drawn.
+* @param everyMs - The spacing of the sheet.
+* @param since - The game time of the last frame.
+* @returns The shot.
+*/
+function laterShot(mctx, layers, everyMs, since) {
+	const time = mctx.ctx.deps.time;
+	const take = {
+		layers,
+		legend: false
+	};
+	if (time.isPaused()) return steppedShot(mctx, take, everyMs);
+	return queueShot(mctx, take, () => time.snapshot().elapsed - since >= everyMs, () => steppedShot(mctx, take, Math.max(0, since + everyMs - time.snapshot().elapsed)));
+}
+/**
+* A cache for one drawn frame: the captures due on it with the same layers and legend share one
+* shot, so one frame costs one extract per kind of picture.
+*
+* @param mctx - Domain context of the capture.
+* @returns Takes the shot of a kind, or hands back the one taken already.
+*/
+function shotsOfFrame(mctx) {
+	const taken = /* @__PURE__ */ new Map();
+	return (take) => {
+		const kind = `${String(take.legend)} ${JSON.stringify(take.layers ?? [])}`;
+		const shot = taken.get(kind) ?? takeShot(mctx, take);
+		taken.set(kind, shot);
+		return shot;
+	};
+}
+/**
+* Keeps a capture waiting for a later frame, until it waited 600 drawn frames.
+*
+* @param state - The monitor branch of the plugin state.
+* @param request - The capture whose frame has not come.
+*/
+function waitOn(state, request) {
+	request.waited += 1;
+	if (request.waited >= MAX_WAIT_FRAMES) {
+		request.reject(timeStood());
+		return;
+	}
+	state.captures.push(request);
+}
+/**
+* Hands the frame just drawn to the captures waiting for it. Called at the end of every drawn
+* frame.
+*
+* @param mctx - Domain context of the capture.
+*/
+function serveCaptures(mctx) {
+	const state = mctx.ctx.state.monitor;
+	if (state.captures.length === 0) return;
+	const waiting = state.captures.splice(0);
+	const shots = shotsOfFrame(mctx);
+	for (const request of waiting) if (request.due()) shots(request).then(request.resolve, request.reject);
+	else waitOn(state, request);
+}
+/**
+* Serves the captures still waiting when the game pauses, since no frame comes to serve them: each
+* takes its paused path, a plain capture at once and a sheet with `time.step`. It runs one
+* microtask later, so a pause inside a frame lets that frame end first, as `time.step` throws
+* inside one; a clock that runs again by then leaves them waiting for its next frame.
+*
+* @param state - The monitor branch of the plugin state.
+* @param time - The time API, asked whether the clock is still paused.
+*/
+function servePaused(state, time) {
+	queueMicrotask(() => {
+		if (!time.isPaused()) return;
+		for (const request of state.captures.splice(0)) request.whilePaused().then(request.resolve, request.reject);
+	});
+}
+/**
+* Answers every capture still waiting with `undefined`. Works on the state alone, for `onStop`.
+*
+* @param state - The monitor branch of the plugin state.
+*/
+function cancelCaptures(state) {
+	for (const request of state.captures.splice(0)) request.resolve();
+}
+/**
+* Takes the frames of a contact sheet and lays them out.
+*
+* @param mctx - Domain context of the capture.
+* @param layers - The layers drawn.
+* @param sheet - How many frames, how far apart.
+* @returns `{ png }` of the sheet, or `undefined` when a frame could not be read.
+*/
+async function captureSheet(mctx, layers, sheet) {
+	const first = await nextShot(mctx, {
+		layers,
+		legend: false
+	});
+	if (first === void 0) return void 0;
+	const pictures = [first.png];
+	let since = first.elapsed;
+	while (pictures.length < sheet.frames) {
+		const shot = await laterShot(mctx, layers, sheet.everyMs, since);
+		if (shot === void 0) return void 0;
+		pictures.push(shot.png);
+		since = shot.elapsed;
+	}
+	return { png: await sheetPicture(pictures, mctx.deps.host.resolution()) };
+}
+/**
+* Draws the answer of one picture: the diff when there is an earlier picture, the badges when
+* there is a legend, the picture itself otherwise.
+*
+* @param mctx - Domain context of the capture.
+* @param shot - The picture and its legend.
+* @param against - The earlier picture, or `undefined`.
+* @returns The answer.
+*/
+async function answerOf(mctx, shot, against) {
+	const { legend } = shot;
+	const resolution = mctx.deps.host.resolution();
+	if (against !== void 0) {
+		const png = await diffPicture(shot.png, against, legend, resolution);
+		return legend === void 0 ? { png } : {
+			png,
+			legend
+		};
+	}
+	if (legend === void 0) return { png: shot.png };
+	return {
+		png: await legendPicture(shot.png, legend, resolution),
+		legend
+	};
+}
+/**
+* Captures the canvas with its options, after the dev guard of `capture()`.
+*
+* @param mctx - Domain context of the capture.
+* @param options - The options of `capture()`.
+* @returns The answer, or `undefined` while nothing draws and when Pixi could not read a frame.
+* @throws {Error} When an option is refused, or there is no `OffscreenCanvas` for one.
+*/
+async function captureFrame(mctx, options) {
+	checkCaptureOptions(options, sceneLayers(mctx));
+	if (!mctx.deps.host.ready()) return void 0;
+	const given = givenOptions(options);
+	if (given[0] !== void 0 && typeof OffscreenCanvas === "undefined") throw needsCanvas(given[0]);
+	mctx.ctx.log.debug("moku:dev", given.length === 0 ? { command: "renderer.capture" } : {
+		command: "renderer.capture",
+		options: given
+	});
+	if (options.sheet !== void 0) return captureSheet(mctx, options.layers, options.sheet);
+	const shot = await nextShot(mctx, {
+		layers: options.layers,
+		legend: options.legend === true
+	});
+	return shot === void 0 ? void 0 : answerOf(mctx, shot, options.against);
+}
+//#endregion
+//#region src/plugins/flow/doors/dev.ts
+/**
+* Reads the dev flag at call time. Undefined means off: production is the default.
+*
+* @returns True only when `__MOKU_GAME_DEV__` is exactly `true`.
+* @example
+* ```ts
+* // The dev page set the flag in web/dev.ts before the engine started.
+* globalThis.__MOKU_GAME_DEV__ = true;
+* isDev(); // true
+* ```
+*/
+function isDev() {
+	return typeof __MOKU_GAME_DEV__ !== "undefined" && __MOKU_GAME_DEV__ === true;
+}
+/**
+* Builds the error a control command throws outside a dev build.
+*
+* @returns The error, ready to throw.
+* @example
+* ```ts
+* // A production build called a /control command.
+* controlRefused().message; // "[game] Control commands run in dev builds only.\n  Define __MOKU_GAME_DEV__ as true in the dev build."
+* ```
+*/
+function controlRefused() {
+	return /* @__PURE__ */ new Error("[game] Control commands run in dev builds only.\n  Define __MOKU_GAME_DEV__ as true in the dev build.");
+}
+//#endregion
+export { serveCaptures as a, collectFlows as c, framePath as d, graphHash as f, pushEntry as h, captureFrame as i, describeGraph as l, compact as m, isDev as n, servePaused as o, slotNames as p, cancelCaptures as r, sheetAlone as s, controlRefused as t, findNode as u };