@moku-labs/game 0.0.1 → 0.0.2

package/dist/runtime-DRlwxkIv.mjs

@@ -0,0 +1,182 @@
+import { n as isComponentDefinition } from "./component-DGg5DqKK.mjs";
+//#region src/plugins/ui/jsx/flatten.ts
+/** The type of the node `Fragment` builds. It never reaches a reconcile: `flatten` lifts it. */
+const FRAGMENT = "#fragment";
+/**
+* Builds the node a bare string or number child becomes.
+*
+* @param content - What stood between the tags.
+* @returns A text node carrying it.
+* @example
+* ```ts
+* textNode(5); // { type: "text", props: { content: "5" }, children: [] }
+* ```
+*/
+function textNode(content) {
+	return {
+		type: "text",
+		props: { content: String(content) },
+		children: []
+	};
+}
+/**
+* Tells a description node from the other things a child may be.
+*
+* @param child - One child of a tag.
+* @returns True when it is a node.
+* @example
+* ```ts
+* isNode({ type: "row", props: {}, children: [] }); // true
+* ```
+*/
+function isNode(child) {
+	return typeof child === "object" && child !== null && !Array.isArray(child) && "type" in child;
+}
+/**
+* Turns whatever stood between two tags into the children of that tag.
+*
+* @param child - One child, an array of children, or nothing.
+* @returns The children as nodes, fragments lifted and empty values dropped.
+* @example
+* ```ts
+* flatten(["a", undefined, 2]).map(node => node.props.content); // ["a", "2"]
+* ```
+*/
+function flatten(child) {
+	if (child === null || child === void 0 || typeof child === "boolean") return [];
+	if (typeof child === "string" || typeof child === "number") return [textNode(child)];
+	if (Array.isArray(child)) {
+		const nodes = [];
+		for (const item of child) nodes.push(...flatten(item));
+		return nodes;
+	}
+	if (!isNode(child)) return [];
+	if (child.type === "#fragment") return [...child.children];
+	return [child];
+}
+//#endregion
+//#region src/plugins/ui/jsx/runtime.ts
+/**
+* @file ui/jsx — the JSX runtime itself: the three factories a TypeScript build calls, the
+* fragment, and the `JSX` namespace `"jsxImportSource": "@moku-labs/game"` resolves to. Pure and
+* reachable only through `src/jsx-runtime.ts` and `src/jsx-dev-runtime.ts` (lint L9).
+*/
+/**
+* Splits the children out of the props the compiler built, so a node never carries them twice.
+*
+* @param props - What the compiler passed.
+* @returns The props without `children`.
+* @example
+* ```ts
+* withoutChildren({ style: {}, children: "a" }); // { style: {} }
+* ```
+*/
+function withoutChildren(props) {
+	const rest = { ...props };
+	delete rest.children;
+	return rest;
+}
+/**
+* Wraps what a plain function component returned so it can stand where one node is expected.
+*
+* @param produced - What the function returned.
+* @param key - The key the tag carried, if any.
+* @returns One node; several results are lifted by the parent's `flatten`.
+*/
+function asSingleNode(produced, key) {
+	const nodes = flatten(produced);
+	const single = nodes.length === 1 ? nodes[0] : void 0;
+	if (single === void 0) return {
+		type: FRAGMENT,
+		props: {},
+		children: nodes
+	};
+	if (key === void 0) return single;
+	return {
+		...single,
+		key
+	};
+}
+/**
+* Builds one description node. A string tag becomes an intrinsic, a component definition becomes
+* one node the reconcile expands, and a plain function runs now.
+*
+* @param type - The tag: a string, `Fragment`, a component definition or a plain function.
+* @param props - What the compiler collected, `children` included.
+* @param key - The `key` attribute, passed as the third argument, never inside `props`.
+* @returns The node.
+* @example
+* ```ts
+* jsx("row", { style: { gap: 8 } }, "tabs"); // { type: "row", key: "tabs", props: { style: { gap: 8 } }, children: [] }
+* ```
+*/
+function jsx(type, props, key) {
+	const rest = withoutChildren(props);
+	if (type === Fragment) return {
+		type: FRAGMENT,
+		props: rest,
+		children: flatten(props.children)
+	};
+	if (isComponentDefinition(type)) {
+		const node = {
+			type: type.name,
+			props,
+			children: []
+		};
+		return key === void 0 ? node : {
+			...node,
+			key
+		};
+	}
+	if (typeof type === "function") return asSingleNode(type(props), key);
+	const node = {
+		type: String(type),
+		props: rest,
+		children: flatten(props.children)
+	};
+	return key === void 0 ? node : {
+		...node,
+		key
+	};
+}
+/**
+* The factory for a tag with several static children. The same function as `jsx`.
+*/
+const jsxs = jsx;
+/**
+* The development factory. The last three arguments are debug information the runtime drops.
+*
+* @param type - The tag.
+* @param props - What the compiler collected.
+* @param key - The `key` attribute.
+* @param _isStatic - Whether the children list is static. Ignored.
+* @param _source - The file and line of the tag. Ignored.
+* @param _self - The `this` of the enclosing scope. Ignored.
+* @returns The node `jsx` builds.
+* @example
+* ```ts
+* jsxDEV("row", {}, "tabs", false, { fileName: "hud.tsx" }, undefined).key; // "tabs"
+* ```
+*/
+function jsxDEV(type, props, key, _isStatic, _source, _self) {
+	return jsx(type, props, key);
+}
+/**
+* Groups children without a tag of its own. Its children are lifted into the parent.
+*
+* @param props - The children between the two ends of the fragment.
+* @returns The fragment node, which `flatten` lifts.
+* @example
+* ```ts
+* Fragment({ children: ["a"] }).children.length; // 1
+* ```
+*/
+function Fragment(props) {
+	return {
+		type: FRAGMENT,
+		props: {},
+		children: flatten(props.children)
+	};
+}
+//#endregion
+export { jsxs as i, jsx as n, jsxDEV as r, Fragment as t };

package/dist/runtime-DiOTkDZz.d.mts

@@ -0,0 +1,77 @@
+import { a as JsxChild, m as UiIntrinsicElements, t as DescriptionNode } from "./types-yg_ywtT-.mjs";
+
+//#region src/plugins/ui/jsx/runtime.d.ts
+/** What the compiler passes as props: the children plus whatever the tag declared. */
+type JsxProperties = Record<string, unknown> & {
+  children?: JsxChild;
+};
+/**
+ * Builds one description node. A string tag becomes an intrinsic, a component definition becomes
+ * one node the reconcile expands, and a plain function runs now.
+ *
+ * @param type - The tag: a string, `Fragment`, a component definition or a plain function.
+ * @param props - What the compiler collected, `children` included.
+ * @param key - The `key` attribute, passed as the third argument, never inside `props`.
+ * @returns The node.
+ * @example
+ * ```ts
+ * jsx("row", { style: { gap: 8 } }, "tabs"); // { type: "row", key: "tabs", props: { style: { gap: 8 } }, children: [] }
+ * ```
+ */
+declare function jsx(type: unknown, props: JsxProperties, key?: string): DescriptionNode;
+/**
+ * The factory for a tag with several static children. The same function as `jsx`.
+ */
+declare const jsxs: typeof jsx;
+/**
+ * The development factory. The last three arguments are debug information the runtime drops.
+ *
+ * @param type - The tag.
+ * @param props - What the compiler collected.
+ * @param key - The `key` attribute.
+ * @param _isStatic - Whether the children list is static. Ignored.
+ * @param _source - The file and line of the tag. Ignored.
+ * @param _self - The `this` of the enclosing scope. Ignored.
+ * @returns The node `jsx` builds.
+ * @example
+ * ```ts
+ * jsxDEV("row", {}, "tabs", false, { fileName: "hud.tsx" }, undefined).key; // "tabs"
+ * ```
+ */
+declare function jsxDEV(type: unknown, props: JsxProperties, key?: string, _isStatic?: boolean, _source?: unknown, _self?: unknown): DescriptionNode;
+/**
+ * Groups children without a tag of its own. Its children are lifted into the parent.
+ *
+ * @param props - The children between the two ends of the fragment.
+ * @returns The fragment node, which `flatten` lifts.
+ * @example
+ * ```ts
+ * Fragment({ children: ["a"] }).children.length; // 1
+ * ```
+ */
+declare function Fragment(props: JsxProperties): DescriptionNode;
+/**
+ * The namespace TypeScript reads a `.tsx` file against. A game sets `"jsx": "react-jsx"` and
+ * `"jsxImportSource": "@moku-labs/game"`, and both entry files export this namespace.
+ */
+declare namespace JSX {
+  /** What a tag evaluates to. */
+  interface Element extends DescriptionNode {}
+  /** The thirteen tags a screen is written with. */
+  interface IntrinsicElements extends UiIntrinsicElements {}
+  /** The prop children are collected into. */
+  interface ElementChildrenAttribute {
+    children: unknown;
+  }
+  /** The attribute every tag takes next to its own props. */
+  interface IntrinsicAttributes {
+    key?: string;
+  }
+  /** The same attribute on a component tag. */
+  interface IntrinsicClassAttributes<Component> {
+    key?: string;
+    ref?: Component;
+  }
+}
+//#endregion
+export { jsxs as a, jsxDEV as i, JSX as n, jsx as r, Fragment as t };

package/dist/session-DmAxY6Ll.mjs

@@ -0,0 +1,145 @@
+//#region src/plugins/flow/doors/define.ts
+/** Lowercase-first camelCase words joined by dots, at least two: `game.position`. */
+const idPattern = /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$/;
+/**
+* Refuses an id that is not a dotted name.
+*
+* @param kind - `"source"` or `"command"`, for the message.
+* @param id - The id to check.
+* @throws {Error} When the id is not camelCase words joined by dots.
+*/
+function checkId(kind, id) {
+	if (idPattern.test(id)) return;
+	throw new Error(`[game] The ${kind} id "${id}" is not a dotted name.\n  Name it like "game.position": camelCase words joined by dots.`);
+}
+/**
+* Declares a source: a read-only view the editor lists, reads and watches. The types flow from
+* the object: the input from `input`, the app from the `read` parameter, the output from its
+* result.
+*
+* @param source - The descriptor.
+* @returns The same descriptor, frozen.
+* @throws {Error} When the id is not a dotted name such as `"game.position"`.
+* @example
+* ```ts
+* // A game's .dev module: the orders on the board, re-read after every edge.
+* export const orders = defineSource({
+*   id: "timber.orders",
+*   title: "Orders",
+*   input: {},
+*   changes: "edge",
+*   read: app => app.flow.state().path
+* });
+* read(app, orders); // "board/awaitIntent"
+* ```
+*/
+function defineSource(source) {
+	checkId("source", source.id);
+	Object.freeze(source.input);
+	return Object.freeze(source);
+}
+/**
+* Declares a command: a dev-only action the editor lists and runs. Its body starts with the
+* inline dev guard, so a production build drops it.
+*
+* @param command - The descriptor.
+* @returns The same descriptor, frozen.
+* @throws {Error} When the id is not a dotted name such as `"game.answer"`.
+* @example
+* ```ts
+* // A game's .dev module: open the shop from anywhere, through the graph.
+* export const openShop = defineCommand({
+*   id: "timber.openShop",
+*   title: "Open the shop",
+*   input: {},
+*   effect: "route",
+*   run: app => {
+*     if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+*     return app.flow.walk([{ at: "home", intent: "shop" }]);
+*   }
+* });
+* (await run(app, openShop)).state.path; // "shop"
+* ```
+*/
+function defineCommand(command) {
+	checkId("command", command.id);
+	Object.freeze(command.input);
+	return Object.freeze(command);
+}
+//#endregion
+//#region src/plugins/flow/doors/input.ts
+/** The input of a call that passed none. */
+const noInput = Object.freeze({});
+/**
+* Hands the given input on, or an empty one. `InputArguments` and `WatchInput` let a call leave
+* the input out only when every field of the schema is optional, so `{}` is an input of that
+* schema.
+*
+* @param input - The input of the call, if any.
+* @returns The input to pass to the descriptor.
+* @example
+* ```ts
+* inputOrEmpty<{ last: "number?" }>(undefined); // {}
+* ```
+*/
+function inputOrEmpty(input) {
+	return input ?? noInput;
+}
+//#endregion
+//#region src/plugins/flow/doors/session.ts
+/** The journal of an app that ran no cheat. */
+const noCheats = Object.freeze([]);
+const sessions = /*#__PURE__*/ new WeakMap();
+/**
+* Tells whether a cheat or a raw command ran on this app.
+*
+* @param app - The app.
+* @returns True once a `cheat` or `raw` command ran.
+* @example
+* ```ts
+* // After run(app, commands.restore, { repro }): a restore is raw.
+* isTainted(app); // true
+* ```
+*/
+function isTainted(app) {
+	return sessions.get(app)?.tainted ?? false;
+}
+/**
+* Reads the journal of cheat and raw commands of this app, oldest first.
+*
+* @param app - The app.
+* @returns The frozen journal, the same list until the next cheat.
+* @example
+* ```ts
+* // After run(app, commands.restore, { bookmark }) on frame 96.
+* cheatsOf(app); // [{ id: "game.restore", input: { bookmark: { path: "home", ... } }, frame: 96 }]
+* ```
+*/
+function cheatsOf(app) {
+	return sessions.get(app)?.cheats ?? noCheats;
+}
+/**
+* Taints the session of this app and journals the command. The input is copied, so the caller
+* cannot rewrite the journal afterwards.
+*
+* @param app - The app.
+* @param id - The command id.
+* @param input - The input the command got.
+* @param frame - The frame it runs on.
+*/
+function recordCheat(app, id, input, frame) {
+	const session = sessions.get(app) ?? {
+		tainted: true,
+		cheats: noCheats
+	};
+	const entry = Object.freeze({
+		id,
+		input: structuredClone(input),
+		frame
+	});
+	session.tainted = true;
+	session.cheats = Object.freeze([...session.cheats.slice(-499), entry]);
+	sessions.set(app, session);
+}
+//#endregion
+export { defineCommand as a, inputOrEmpty as i, isTainted as n, defineSource as o, recordCheat as r, cheatsOf as t };

package/dist/testing.d.mts

@@ -1,125 +1,27 @@
-import { E as Json, L as RngState, M as ProviderCall, N as SaveDoc, S as FakeClock, U as Api, h as RouteStep, j as PlayerStateProvider, m as JournalEntry, p as FlowState, t as Api$1, y as Answer } from "./types-BfsmUzLC.mjs";
+import { H as PlayerStateProvider, L as Json, U as ProviderCall, W as SaveDoc, it as FakeClock } from "./types-JNc_UQBo.mjs";
+import { a as createHeadless, i as ReproResult, n as HeadlessGame, o as runRepro, r as Repro, s as stepFrames, t as HeadlessApp } from "./headless-KaSWcd0s.mjs";
 
 //#region src/plugins/clock/fake.d.ts
 /**
- * Creates a fake source for tests. Timers fire synchronously inside `advance`, in due order.
+ * Creates a fake source for tests. Timers fire synchronously inside `advance`, in due order. A
+ * negative delay counts as zero and an unknown handle is ignored.
  *
  * @param start - Starting moment in epoch milliseconds. Defaults to 0.
  * @returns A clock source with the test-only controls `advance` and `set`.
  * @example
  * ```ts
+ * // An energy point refills 60 s after it was spent. The test moves the clock, not the minute.
  * const clock = fakeClock(1000);
- * clock.advance(5000);
- * ```
- */
-declare function fakeClock(start?: number): FakeClock;
-//#endregion
-//#region src/plugins/flow/headless.d.ts
-/**
- * The part of an app the headless helpers use. Structural on purpose: any app created with the
- * default plugins fits.
- *
- * @example
- * ```ts
- * const app: HeadlessApp = createApp({ pluginConfigs: { flow: { mainFlow } } });
- * ```
- */
-type HeadlessApp = {
-  start(): Promise<void>;
-  stop(): Promise<void>;
-  time: Api;
-  flow: Api$1;
-};
-/**
- * A game played without a screen: answers go through the gate, effects resolve instantly.
- *
- * @example
- * ```ts
- * const game: HeadlessGame = await createHeadless(app);
- * await game.walk([{ at: "home", intent: "play" }]);
- * ```
- */
-type HeadlessGame = {
-  walk(route: readonly RouteStep[]): Promise<FlowState>;
-  answer(answer: Answer): boolean;
-  state(): FlowState;
-  history(): readonly JournalEntry[];
-  stop(): Promise<void>;
-};
-/**
- * A reproducible run: a starting state, an optional checkpoint and the route played from it.
+ * const app = createApp({ pluginConfigs: { clock: { source: clock } } });
+ * const seen: number[] = [];
  *
- * @example
- * ```ts
- * const repro: Repro = { player: { coins: 0 }, checkpoint: "home", route: [{ at: "home", intent: "play" }] };
+ * app.clock.onElapsed(({ now }) => seen.push(now));
+ * app.clock.scheduleAt(61_000);
+ * clock.advance(60_000); // the timer fires inside advance, nothing waits
+ * seen; // [61000]
  * ```
  */
-type Repro = {
-  player: Json;
-  session?: Json;
-  rng?: RngState;
-  checkpoint?: string;
-  route: RouteStep[];
-};
-/**
- * What a repro run ends with: the path where the loop rests and the committed state.
- *
- * @example
- * ```ts
- * const { path, player }: ReproResult = await runRepro(app, repro);
- * ```
- */
-type ReproResult = {
-  path: string[];
-  player: Json;
-  session: Json;
-};
-/**
- * Starts an app headless: sets flow mode `"fast"`, awaits `app.start()`, starts `flow.run()`
- * unless the app's own `onStart` already did, and waits until the loop rests for the first time.
- * `game.state().path` therefore names the first rest node of the graph as soon as the call
- * resolves. A fatal error of the loop rejects this call, and a later one is re-thrown by `walk`
- * and by `stop`, so a headless test never loses it.
- *
- * @param app - An app that is not started yet.
- * @returns The game: walk it, answer it, read it, stop it.
- * @throws {Error} When the loop failed fatally before it reached its first rest node.
- * @example
- * ```ts
- * const game = await createHeadless(app);
- * expect(game.state().path).toBe("home");
- * await game.walk([{ at: "board/awaitIntent", intent: "merge", payload: { from: "c2", to: "c3" } }]);
- * await game.stop();
- * ```
- */
-declare function createHeadless(app: HeadlessApp): Promise<HeadlessGame>;
-/**
- * Plays a repro: starts the app headless, restores the bookmark built from its state and
- * checkpoint, then walks its route. The app keeps running, so the caller can read more than the
- * result and stops it itself.
- *
- * @param app - An app that is not started yet.
- * @param repro - Starting state, optional checkpoint and the route.
- * @returns The path the run ended at, and the committed state.
- * @example
- * ```ts
- * const result = await runRepro(app, { player: saved, checkpoint: "home", route });
- * ```
- */
-declare function runRepro(app: HeadlessApp, repro: Repro): Promise<ReproResult>;
-/**
- * Steps the frame loop by hand: `count` calls of `app.time.step(deltaMs)`. A headless game has no
- * frame source, so this is the only thing that moves the frame phases.
- *
- * @param app - A started app.
- * @param count - Number of frames.
- * @param deltaMs - Milliseconds per frame.
- * @example
- * ```ts
- * stepFrames(app, 60, 16);
- * ```
- */
-declare function stepFrames(app: HeadlessApp, count: number, deltaMs: number): void;
+declare function fakeClock(start?: number): FakeClock;
 //#endregion
 //#region src/plugins/model/store/providers/memory.d.ts
 /**
@@ -129,13 +31,21 @@ declare function stepFrames(app: HeadlessApp, count: number, deltaMs: number): v
  * 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
- * const provider = memory({ state: saveOf({ coins: 5 }, 42), version: 1 });
+ * // 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"]
  * ```
  */
 declare function memory(fixture?: {
@@ -153,6 +63,8 @@ declare function memory(fixture?: {
  * @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 });
  * ```
  */