@moku-labs/game 0.0.1 → 0.0.2

package/dist/inspect.d.mts

@@ -0,0 +1,109 @@
+import { K as Snapshot, P as Api, b as JournalEntry, o as Position, v as FlowGraph } from "./types-JNc_UQBo.mjs";
+import { P as EntitySnapshot, o as RenderStats, t as Api$2, u as Api$1 } from "./types-BxkNNYul.mjs";
+import { f as Usage, t as Api$3 } from "./types-DWILGrPn.mjs";
+import { t as HeadlessApp } from "./headless-KaSWcd0s.mjs";
+import { c as InputSchema, d as WatchApp, f as WatchInput, n as defineSource, o as InputArguments, r as CheatEntry, s as InputOf, u as Source } from "./define-sFoO3y6X.mjs";
+import { c as UiNode } from "./types-yg_ywtT-.mjs";
+import { r as UiApi } from "./types-DD-QrG_z.mjs";
+import { a as SoundEntry, t as AudioApi } from "./types-DYLnSgMI.mjs";
+
+//#region src/plugins/flow/doors/read.d.ts
+/**
+ * Reads a source once.
+ *
+ * @param app - The app the source reads.
+ * @param source - The source.
+ * @param input - Its input; left out when every field of its schema is optional.
+ * @returns What the source reads.
+ * @example
+ * ```ts
+ * // An e2e script checks where the game rests after a tap on Play.
+ * read(app, sources.position); // { path: "board/awaitIntent", flow: "board", node: "awaitIntent", waiting: ["tap", "leave"] }
+ * read(app, sources.history, { last: 1 }); // [{ path: "home", outcome: "play", next: "board/awaitIntent", ... }]
+ * ```
+ */
+declare function read<S extends InputSchema, O, App>(app: App, source: Source<S, O, App>, ...input: InputArguments<S>): O;
+/**
+ * Watches a source: reads it on the first frame, then again whenever its change key moved,
+ * in the `signals` phase of the frame loop.
+ *
+ * @param app - The app the source reads.
+ * @param source - The source.
+ * @param input - Its input, or `undefined` when every field of its schema is optional.
+ * @param fn - Called with each value read.
+ * @returns Stops watching.
+ * @example
+ * ```ts
+ * // An editor panel follows the position; it redraws only after the graph moved.
+ * const stop = watch(app, sources.position, undefined, position => panel.show(position.path));
+ * // next frame: panel shows "home"; a tap on Play: panel shows "board/awaitIntent"
+ * stop();
+ * ```
+ */
+declare function watch<S extends InputSchema, O, App extends WatchApp>(app: App, source: Source<S, O, App>, input: WatchInput<S>, fn: (value: O) => void): () => void;
+//#endregion
+//#region src/plugins/flow/doors/sources.d.ts
+/**
+ * Every source of the engine, keyed by its short name: what an editor lists as panel data and
+ * MCP tools. Frozen.
+ *
+ * @example
+ * ```ts
+ * // An e2e script checks where the game rests, and the editor registers every source.
+ * read(app, sources.position).path; // "board/awaitIntent"
+ * for (const source of Object.values(sources)) registry.add(source);
+ * ```
+ */
+declare const sources: Readonly<{
+  graph: Source<{}, FlowGraph, HeadlessApp>;
+  position: Source<{}, Position, HeadlessApp>;
+  history: Source<{
+    last: "number?";
+  }, readonly JournalEntry[], HeadlessApp>;
+  tainted: Source<{}, boolean, HeadlessApp>;
+  cheats: Source<{}, readonly CheatEntry[], HeadlessApp>;
+  model: Source<{}, Snapshot, HeadlessApp & {
+    readonly model: Api;
+  }>;
+  entities: Source<{
+    owner: "string?";
+    component: "string?";
+  }, EntitySnapshot[], HeadlessApp & {
+    readonly world: Api$1;
+  }>;
+  projections: Source<{}, Record<string, Record<string, number>>, HeadlessApp & {
+    readonly world: Api$1;
+  }>;
+  ui: Source<{}, UiNode, HeadlessApp & {
+    readonly ui: UiApi;
+  }>;
+  rect: Source<{
+    key: "string";
+  }, {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+  } | undefined, HeadlessApp & {
+    readonly ui: UiApi;
+    readonly renderer: Api$2;
+  }>;
+  render: Source<{}, RenderStats, HeadlessApp & {
+    readonly renderer: Api$2;
+  }>;
+  sounds: Source<{
+    last: "number?";
+  }, readonly SoundEntry[], HeadlessApp & {
+    readonly audio: AudioApi;
+  }>;
+  assets: Source<{}, Usage, HeadlessApp & {
+    readonly assets: Api$3;
+  }>;
+  log: Source<{
+    level: "string?";
+  }, readonly import("@moku-labs/common/browser").LogEntry[], HeadlessApp & {
+    readonly log: import("@moku-labs/common/browser").LogApi;
+  }>;
+}>;
+//#endregion
+export { type InputOf, type InputSchema, type Source, defineSource, read, sources, watch };

package/dist/inspect.mjs

@@ -0,0 +1,519 @@
+import { i as scaleByFits } from "./visual-BDUHSRvf.mjs";
+import { i as inputOrEmpty, n as isTainted, o as defineSource, t as cheatsOf } from "./session-DmAxY6Ll.mjs";
+//#region src/plugins/flow/doors/read.ts
+/**
+* @file flow/doors — `read` and `watch`, the `/inspect` side. Neither changes the game.
+*/
+/**
+* Reads a source once.
+*
+* @param app - The app the source reads.
+* @param source - The source.
+* @param input - Its input; left out when every field of its schema is optional.
+* @returns What the source reads.
+* @example
+* ```ts
+* // An e2e script checks where the game rests after a tap on Play.
+* read(app, sources.position); // { path: "board/awaitIntent", flow: "board", node: "awaitIntent", waiting: ["tap", "leave"] }
+* read(app, sources.history, { last: 1 }); // [{ path: "home", outcome: "play", next: "board/awaitIntent", ... }]
+* ```
+*/
+function read(app, source, ...input) {
+	const [given] = input;
+	return source.read(app, inputOrEmpty(given));
+}
+/**
+* The change test of a `frame` source: it is read on every frame.
+*
+* @returns Always true.
+*/
+const everyFrame = () => true;
+/**
+* Builds the per-frame test of a change key. `commit` and `edge` compare the identity of the
+* memoised `store.snapshot()` and `flow.state()`, so an unchanged frame allocates nothing.
+*
+* @param app - The watched app.
+* @param changes - The source's change key.
+* @returns A test that is true on the first frame and whenever the key moved.
+*/
+function changeTest(app, changes) {
+	if (changes === "frame") return everyFrame;
+	const identity = changes === "commit" ? () => app.model.store.snapshot() : () => app.flow.state();
+	let last;
+	return () => {
+		const current = identity();
+		if (current === last) return false;
+		last = current;
+		return true;
+	};
+}
+/**
+* Watches a source: reads it on the first frame, then again whenever its change key moved,
+* in the `signals` phase of the frame loop.
+*
+* @param app - The app the source reads.
+* @param source - The source.
+* @param input - Its input, or `undefined` when every field of its schema is optional.
+* @param fn - Called with each value read.
+* @returns Stops watching.
+* @example
+* ```ts
+* // An editor panel follows the position; it redraws only after the graph moved.
+* const stop = watch(app, sources.position, undefined, position => panel.show(position.path));
+* // next frame: panel shows "home"; a tap on Play: panel shows "board/awaitIntent"
+* stop();
+* ```
+*/
+function watch(app, source, input, fn) {
+	const given = inputOrEmpty(input);
+	const changed = changeTest(app, source.changes);
+	return app.time.onFrame("signals", () => {
+		if (changed()) fn(source.read(app, given));
+	});
+}
+//#endregion
+//#region src/plugins/assets/inspect.ts
+/**
+* @file assets plugin — the assets source of the `/inspect` door: what the loaded bundles cost.
+* Production-safe: it only reads.
+*/
+/**
+* The texture memory in use, the budget and one entry per loaded bundle, sorted by name. Read
+* every frame: a bundle loads asynchronously, without a model commit.
+*
+* @example
+* ```ts
+* // The editor's memory bar after the board scene loaded.
+* read(app, sources.assets);
+* // { textureMb: 3.5, budgetMb: 192, bundles: [{ name: "board", tier: "scene", mb: 3.5, lastUsed: 12 }] }
+* ```
+*/
+const assetsSource = defineSource({
+	id: "game.assets",
+	title: "Assets",
+	input: {},
+	changes: "frame",
+	read: (app) => app.assets.usage()
+});
+//#endregion
+//#region src/plugins/audio/inspect.ts
+/**
+* @file audio plugin — the audio source of the `/inspect` door: the journal of started sounds.
+* Production-safe: it only reads.
+*/
+/**
+* The sounds that started, oldest first: every sfx played and every music track begun, all of
+* them or the last few. Empty unless `pluginConfigs.audio.journal` is above 0.
+*
+* @example
+* ```ts
+* // After a tap on Deliver, on the dev page that sets `journal: 200`.
+* read(app, sources.sounds, { last: 2 });
+* // [{ key: "ui.click", bus: "sfx", kind: "sfx", at: 1584 }, { key: "orders.complete", bus: "sfx", kind: "sfx", at: 1600 }]
+* ```
+*/
+const soundsSource = defineSource({
+	id: "game.sounds",
+	title: "Sounds",
+	input: { last: "number?" },
+	changes: "frame",
+	read: (app, { last }) => {
+		const entries = app.audio.journal();
+		return last === void 0 ? entries : entries.slice(Math.max(0, entries.length - last));
+	}
+});
+//#endregion
+//#region src/plugins/model/inspect.ts
+/**
+* @file model plugin — the model source of the `/inspect` door: the committed player and
+* session. Production-safe: it only reads.
+*/
+/**
+* The committed player, session and rng trees, the same frozen object until the next commit.
+*
+* @example
+* ```ts
+* // An editor panel shows the coins after a delivery.
+* read(app, sources.model).player; // { coins: 140, orders: [] }
+* ```
+*/
+const modelSource = defineSource({
+	id: "game.model",
+	title: "Model",
+	input: {},
+	changes: "commit",
+	read: (app) => app.model.store.snapshot()
+});
+//#endregion
+//#region src/plugins/renderer/inspect.ts
+/**
+* @file renderer plugin — the renderer source of the `/inspect` door: the frame counters.
+* Production-safe: it only reads.
+*/
+/**
+* The counters of the renderer: frames per second, frame work, GPU textures and their memory,
+* views and pooled display objects.
+*
+* @example
+* ```ts
+* // The editor's stats panel on the board of Timber Town.
+* read(app, sources.render); // { fps: 60, frameMs: 3.4, textures: 12, textureMb: 41.25, views: 180, pooled: 24 }
+* ```
+*/
+const renderSource = defineSource({
+	id: "game.render",
+	title: "Render stats",
+	input: {},
+	changes: "frame",
+	read: (app) => app.renderer.stats()
+});
+//#endregion
+//#region src/plugins/ui/inspect.ts
+/**
+* @file ui plugin — the ui sources of the `/inspect` door: the live screen as data and the rect
+* of one element on the page. Production-safe: both only read.
+*/
+/**
+* Finds a keyed node and the nodes above it.
+*
+* @param node - Where the search starts.
+* @param key - The key of the element.
+* @returns The node and its ancestors, nearest first, or `undefined` when no node has the key.
+*/
+function chainTo(node, key) {
+	if (node.key === key) return [node];
+	for (const child of node.children) {
+		const chain = chainTo(child, key);
+		if (chain !== void 0) {
+			chain.push(node);
+			return chain;
+		}
+	}
+}
+/**
+* Where an element is drawn at rest, in root coordinates. Its rect in the snapshot is natural,
+* so every fitted node on the way up, the element itself included, scales it about its centre,
+* the way ui draws a `fit: "contain"`.
+*
+* @param chain - The element and its ancestors, nearest first.
+* @returns The drawn rect.
+*/
+function drawnRect(chain) {
+	return scaleByFits(chain[0].rect, chain.map((node) => ({
+		rect: node.rect,
+		fit: node.fitScale ?? 1
+	})));
+}
+/**
+* Maps a rect in reference units to CSS px of the page through both of its corners.
+*
+* @param renderer - The renderer, for its viewport.
+* @param rect - The rect in reference units.
+* @returns The rect in CSS px; the same numbers while the renderer is inert.
+*/
+function onPage(renderer, rect) {
+	const topLeft = renderer.viewport.toScreen({
+		x: rect.x,
+		y: rect.y
+	});
+	const bottomRight = renderer.viewport.toScreen({
+		x: rect.x + rect.w,
+		y: rect.y + rect.h
+	});
+	return {
+		x: topLeft.x,
+		y: topLeft.y,
+		w: bottomRight.x - topLeft.x,
+		h: bottomRight.y - topLeft.y
+	};
+}
+/**
+* The live screen as plain data: every root, every element with its natural rect, its style,
+* its state flags and the fit scale of a fitted one.
+*
+* @example
+* ```ts
+* // The editor's tree panel lists the HUD.
+* read(app, sources.ui).children.map(child => child.key); // ["coins", "settings", "order"]
+* ```
+*/
+const uiSource = defineSource({
+	id: "game.ui",
+	title: "UI tree",
+	input: {},
+	changes: "frame",
+	read: (app) => app.ui.tree()
+});
+/**
+* Where an element is on the page, in CSS px: its layout box, so a bare button with no fill has
+* one, scaled by every fitted element above it, through the viewport. In reference units while
+* the renderer is inert.
+*
+* @example
+* ```ts
+* // An e2e script clicks Home's Play plank on a 390 px wide phone.
+* read(app, sources.rect, { key: "play" }); // { x: 101.9, y: 469.2, w: 189.2, h: 54.6 }
+* read(app, sources.rect, { key: "nothing" }); // undefined: not on screen
+* ```
+*/
+const rectSource = defineSource({
+	id: "game.rect",
+	title: "Element rect",
+	input: { key: "string" },
+	changes: "frame",
+	read: (app, { key }) => {
+		const chain = app.ui.find(key) !== void 0 ? chainTo(app.ui.tree(), key) : void 0;
+		return chain === void 0 ? void 0 : onPage(app.renderer, drawnRect(chain));
+	}
+});
+//#endregion
+//#region src/plugins/world/inspect.ts
+/**
+* @file world plugin — the world sources of the `/inspect` door: the entities, filtered by owner
+* and component, and the projection keys. Production-safe: every source only reads.
+*/
+/**
+* Tells whether an entity carries a component, as a JSON value or as a skipped one.
+*
+* @param entity - The entity snapshot.
+* @param component - The component name.
+* @returns True when the entity carries it.
+*/
+function carries(entity, component) {
+	return Object.hasOwn(entity.components, component) || entity.skipped.includes(component);
+}
+/**
+* Every entity of the world as plain JSON, sorted by index: all of them, the ones of one owner,
+* the ones that carry a component, or both.
+*
+* @example
+* ```ts
+* // Which board items are on screen right now?
+* read(app, sources.entities, { owner: "board.items" });
+* // [{ id: 1048576, index: 0, generation: 1, owner: { kind: "projection", name: "board.items" },
+* //   components: { Layer: { name: "items" } }, skipped: ["Display"] }]
+* ```
+*/
+const entitiesSource = defineSource({
+	id: "game.entities",
+	title: "Entities",
+	input: {
+		owner: "string?",
+		component: "string?"
+	},
+	changes: "frame",
+	read: (app, { owner, component }) => app.world.ecs.snapshot().entities.filter((entity) => (owner === void 0 || entity.owner.name === owner) && (component === void 0 || carries(entity, component)))
+});
+/**
+* The projection keys of the world: projection name to key to the entity of its live view.
+*
+* @example
+* ```ts
+* // An agent finds the item it is about to drag.
+* read(app, sources.projections)["board.items"]; // { i5: 1048580, i7: 1048581 }
+* ```
+*/
+const projectionsSource = defineSource({
+	id: "game.projections",
+	title: "Projections",
+	input: {},
+	changes: "commit",
+	read: (app) => {
+		const keys = {};
+		for (const { id } of app.world.ecs.snapshot().entities) {
+			const address = app.world.projection.keyOf(id);
+			if (address === void 0) continue;
+			keys[address.projection] = {
+				...keys[address.projection],
+				[address.key]: id
+			};
+		}
+		return keys;
+	}
+});
+//#endregion
+//#region src/plugins/flow/inspect.ts
+/** The levels of `Log.LogLevel`, least severe first, as the names a caller passes. */
+const LOG_LEVELS = [
+	"debug",
+	"info",
+	"warn",
+	"error"
+];
+/**
+* The rank of a log level: 0 for `debug` up to 3 for `error`.
+*
+* @param level - The level the caller named.
+* @returns Its rank.
+* @throws {Error} When the log has no such level.
+* @example
+* ```ts
+* rankOf("warn"); // 2
+* ```
+*/
+function rankOf(level) {
+	const rank = LOG_LEVELS.indexOf(level);
+	if (rank !== -1) return rank;
+	throw new Error("[game] game.log takes the level \"debug\", \"info\", \"warn\" or \"error\".\n  Leave the level out to read every entry.");
+}
+/**
+* Turns the flow state into the position a panel shows.
+*
+* @param state - The flow state.
+* @returns The path, the top flow and node, and what the gate waits for.
+* @example
+* ```ts
+* positionOf(app.flow.state()).node; // "awaitIntent"
+* ```
+*/
+function positionOf(state) {
+	const top = state.stack.at(-1);
+	return {
+		path: state.path,
+		flow: top?.flow,
+		node: top?.node,
+		waiting: state.pending.gate ?? []
+	};
+}
+/**
+* The flow graph: flows, nodes with their flags and outcomes, edges and slots.
+*
+* @example
+* ```ts
+* // The editor draws the graph of Timber Town.
+* read(app, sources.graph).flows.main?.edges.home; // { play: "board" }
+* ```
+*/
+const graphSource = defineSource({
+	id: "game.graph",
+	title: "Graph",
+	input: {},
+	changes: "edge",
+	read: (app) => app.flow.describe()
+});
+/**
+* Where the graph rests: the path, the node and the intents the gate waits for.
+*
+* @example
+* ```ts
+* // After a tap on Play on the home screen.
+* read(app, sources.position); // { path: "board/awaitIntent", flow: "board", node: "awaitIntent", waiting: ["tap", "leave"] }
+* ```
+*/
+const positionSource = defineSource({
+	id: "game.position",
+	title: "Position",
+	input: {},
+	changes: "edge",
+	read: (app) => positionOf(app.flow.state())
+});
+/**
+* The edges taken since the last checkpoint, all of them or the last few.
+*
+* @example
+* ```ts
+* // Why was the last move refused?
+* read(app, sources.history, { last: 1 }); // [{ path: "board/merge", outcome: "rejected", payload: { reason: "empty" }, ... }]
+* ```
+*/
+const historySource = defineSource({
+	id: "game.history",
+	title: "History",
+	input: { last: "number?" },
+	changes: "edge",
+	read: (app, { last }) => {
+		const entries = app.flow.history();
+		return last === void 0 ? entries : entries.slice(Math.max(0, entries.length - last));
+	}
+});
+/**
+* Whether a cheat or a raw command changed this session: a tainted session is no played one.
+*
+* @example
+* ```ts
+* // After run(app, commands.restore, { repro }).
+* read(app, sources.tainted); // true
+* ```
+*/
+const taintedSource = defineSource({
+	id: "game.tainted",
+	title: "Tainted",
+	input: {},
+	changes: "frame",
+	read: (app) => isTainted(app)
+});
+/**
+* The cheat and raw commands run on this app, oldest first, the last 500.
+*
+* @example
+* ```ts
+* // After run(app, commands.restore, { bookmark }) on frame 96.
+* read(app, sources.cheats); // [{ id: "game.restore", input: { bookmark: { path: "home", ... } }, frame: 96 }]
+* ```
+*/
+const cheatsSource = defineSource({
+	id: "game.cheats",
+	title: "Cheats",
+	input: {},
+	changes: "frame",
+	read: (app) => cheatsOf(app)
+});
+/**
+* The log trace, oldest first: every entry, or the entries at a level and above.
+*
+* @example
+* ```ts
+* // What went wrong on the last tap?
+* read(app, sources.log, { level: "warn" });
+* // [{ level: "warn", event: "assets: missing texture", data: { key: "ui.gear" }, ts: 1758620000000 }]
+* ```
+*/
+const logSource = defineSource({
+	id: "game.log",
+	title: "Log",
+	input: { level: "string?" },
+	changes: "frame",
+	read: (app, { level }) => {
+		const entries = app.log.trace();
+		if (level === void 0) return entries;
+		const lowest = rankOf(level);
+		return entries.filter((entry) => LOG_LEVELS.indexOf(entry.level) >= lowest);
+	}
+});
+//#endregion
+//#region src/plugins/flow/doors/sources.ts
+/**
+* @file flow/doors — the base sources: every source of the engine, keyed by a short name. Each
+* descriptor lives with the plugin that owns its data; this module only gathers them. Imported
+* by the door `src/inspect.ts` only, so no plugin reaches it, no import cycle forms and an
+* `/inspect` bundle carries no command.
+*/
+/**
+* Every source of the engine, keyed by its short name: what an editor lists as panel data and
+* MCP tools. Frozen.
+*
+* @example
+* ```ts
+* // An e2e script checks where the game rests, and the editor registers every source.
+* read(app, sources.position).path; // "board/awaitIntent"
+* for (const source of Object.values(sources)) registry.add(source);
+* ```
+*/
+const sources = Object.freeze({
+	graph: graphSource,
+	position: positionSource,
+	history: historySource,
+	tainted: taintedSource,
+	cheats: cheatsSource,
+	model: modelSource,
+	entities: entitiesSource,
+	projections: projectionsSource,
+	ui: uiSource,
+	rect: rectSource,
+	render: renderSource,
+	sounds: soundsSource,
+	assets: assetsSource,
+	log: logSource
+});
+//#endregion
+export { defineSource, read, sources, watch };

package/dist/jsx-dev-runtime.d.mts

@@ -0,0 +1,2 @@
+import { a as jsxs, i as jsxDEV, n as JSX, r as jsx, t as Fragment } from "./runtime-DiOTkDZz.mjs";
+export { Fragment, type JSX, jsx, jsxDEV, jsxs };

package/dist/jsx-dev-runtime.mjs

@@ -0,0 +1,2 @@
+import { i as jsxs, n as jsx, r as jsxDEV, t as Fragment } from "./runtime-DRlwxkIv.mjs";
+export { Fragment, jsx, jsxDEV, jsxs };

package/dist/jsx-runtime.d.mts

@@ -0,0 +1,2 @@
+import { a as jsxs, n as JSX, r as jsx, t as Fragment } from "./runtime-DiOTkDZz.mjs";
+export { Fragment, type JSX, jsx, jsxs };

package/dist/jsx-runtime.mjs

@@ -0,0 +1,2 @@
+import { i as jsxs, n as jsx, t as Fragment } from "./runtime-DRlwxkIv.mjs";
+export { Fragment, jsx, jsxs };