@moku-labs/game 0.0.0

package/dist/testing.d.mts

@@ -0,0 +1,161 @@
+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";
+
+//#region src/plugins/clock/fake.d.ts
+/**
+ * Creates a fake source for tests. Timers fire synchronously inside `advance`, in due order.
+ *
+ * @param start - Starting moment in epoch milliseconds. Defaults to 0.
+ * @returns A clock source with the test-only controls `advance` and `set`.
+ * @example
+ * ```ts
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const repro: Repro = { player: { coins: 0 }, checkpoint: "home", route: [{ at: "home", intent: "play" }] };
+ * ```
+ */
+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;
+//#endregion
+//#region src/plugins/model/store/providers/memory.d.ts
+/**
+ * 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.
+ *
+ * @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 });
+ * ```
+ */
+declare function memory(fixture?: {
+  state: SaveDoc;
+  version: number;
+}): PlayerStateProvider & {
+  calls: ProviderCall[];
+};
+/**
+ * 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
+ * const provider = memory({ state: saveOf({ coins: 5 }, 42), version: 1 });
+ * ```
+ */
+declare function saveOf(player: Json, seed?: number): SaveDoc;
+//#endregion
+export { type HeadlessApp, type HeadlessGame, type Repro, type ReproResult, createHeadless, fakeClock, memory, runRepro, saveOf, stepFrames };

package/dist/testing.mjs

@@ -0,0 +1,366 @@
+import { a as graphHash, l as memory, u as saveOf } from "./registry-DWV5C0Mf.mjs";
+//#region src/plugins/clock/fake.ts
+/**
+* Removes and returns the timer that is due first, up to and including `until`.
+* Timers due at the same moment come out in the order they were scheduled.
+*
+* @param state - Innards of the fake clock.
+* @param until - Latest moment that counts as due.
+* @returns The timer to fire, or `undefined` when nothing is due.
+* @example
+* ```ts
+* const due = takeDue(state, 1500);
+* ```
+*/
+function takeDue(state, until) {
+	let earliest;
+	for (const timer of state.timers) {
+		if (timer.at > until) continue;
+		if (earliest === void 0 || timer.at < earliest.at) earliest = timer;
+	}
+	if (earliest === void 0) return void 0;
+	const due = earliest;
+	state.timers = state.timers.filter((timer) => timer !== due);
+	return due;
+}
+/**
+* Moves the clock to `until`, firing every timer that falls due on the way, in due order.
+* A timer scheduled inside a callback fires in the same run when it is due before `until`.
+*
+* @param state - Innards of the fake clock.
+* @param until - Moment to stop at.
+* @example
+* ```ts
+* runDue(state, state.now + 5000);
+* ```
+*/
+function runDue(state, until) {
+	let due = takeDue(state, until);
+	while (due !== void 0) {
+		state.now = Math.max(state.now, due.at);
+		due.callback();
+		due = takeDue(state, until);
+	}
+	state.now = Math.max(state.now, until);
+}
+/**
+* Creates a fake source for tests. Timers fire synchronously inside `advance`, in due order.
+*
+* @param start - Starting moment in epoch milliseconds. Defaults to 0.
+* @returns A clock source with the test-only controls `advance` and `set`.
+* @example
+* ```ts
+* const clock = fakeClock(1000);
+* clock.advance(5000);
+* ```
+*/
+function fakeClock(start = 0) {
+	const state = {
+		now: start,
+		nextId: 1,
+		timers: []
+	};
+	return {
+		/**
+		* Reads the fake moment.
+		*
+		* @returns The current moment in epoch milliseconds.
+		* @example
+		* ```ts
+		* const moment = clock.now();
+		* ```
+		*/
+		now: () => state.now,
+		/**
+		* Schedules one callback. A negative delay counts as zero.
+		*
+		* @param callback - Function to run when the delay has passed.
+		* @param delayMs - Delay in milliseconds.
+		* @returns The handle to give back to `clearTimer`.
+		* @example
+		* ```ts
+		* const handle = clock.setTimer(fire, 1000);
+		* ```
+		*/
+		setTimer: (callback, delayMs) => {
+			const id = state.nextId;
+			state.nextId += 1;
+			state.timers.push({
+				id,
+				at: state.now + Math.max(0, delayMs),
+				callback
+			});
+			return id;
+		},
+		/**
+		* Cancels a pending timer. An unknown handle is ignored.
+		*
+		* @param handle - Handle returned by `setTimer`.
+		* @example
+		* ```ts
+		* clock.clearTimer(handle);
+		* ```
+		*/
+		clearTimer: (handle) => {
+			if (typeof handle !== "number") return;
+			state.timers = state.timers.filter((timer) => timer.id !== handle);
+		},
+		/**
+		* Moves the clock forward and fires every timer that falls due, in due order.
+		* A negative amount moves nothing.
+		*
+		* @param ms - Milliseconds to move forward.
+		* @example
+		* ```ts
+		* clock.advance(60_000);
+		* ```
+		*/
+		advance: (ms) => {
+			runDue(state, state.now + Math.max(0, ms));
+		},
+		/**
+		* Jumps the clock to a moment without firing any timer. Moving back is allowed: that is a
+		* device clock set by hand.
+		*
+		* @param moment - Moment in epoch milliseconds.
+		* @example
+		* ```ts
+		* clock.set(400);
+		* ```
+		*/
+		set: (moment) => {
+			state.now = moment;
+		}
+	};
+}
+//#endregion
+//#region src/plugins/flow/headless.ts
+const noPayload = null;
+/** Seed of a repro that pins no rng state, the seed `saveOf` writes. */
+const defaultSeed = 1;
+/**
+* Turns whatever `run()` rejected with into an error that can be thrown again.
+*
+* @param value - The rejection value.
+* @returns The value itself when it is an error, a wrapped one otherwise.
+* @example
+* ```ts
+* throw asError(fatal.error);
+* ```
+*/
+function asError(value) {
+	if (value instanceof Error) return value;
+	return /* @__PURE__ */ new Error(`[game] The headless run failed.\n  ${String(value)}.`);
+}
+/**
+* Starts the one loop unless the app's own `onStart` already did, and keeps a fatal error until
+* someone asks for it. `run()` rejects only on a fatal error, and nobody awaits it here.
+*
+* @param app - The started app.
+* @returns The holder of the fatal error.
+* @example
+* ```ts
+* const fatal = startLoop(app);
+* ```
+*/
+function startLoop(app) {
+	const fatal = { error: void 0 };
+	if (app.flow.state().running) return fatal;
+	app.flow.run().catch((error) => {
+		fatal.error = error;
+	});
+	return fatal;
+}
+/**
+* Waits until the loop rests for the first time, or ends. An empty route walks nowhere: it only
+* waits for the gate the loop opens at the node it enters, so a start that is a chain of transit
+* nodes is played out before anything reads the game.
+*
+* @param app - The started app whose loop is running.
+* @param fatal - Holder of the fatal error of `run()`.
+* @returns Resolves once the loop rests at its first rest node.
+* @throws {Error} When the loop failed fatally instead of reaching a rest node.
+* @example
+* ```ts
+* await settleAtFirstRest(app, fatal);
+* ```
+*/
+async function settleAtFirstRest(app, fatal) {
+	await app.flow.walk([]).catch((error) => {
+		throw asError(fatal.error ?? error);
+	});
+	if (fatal.error !== void 0) throw asError(fatal.error);
+}
+/**
+* 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();
+* ```
+*/
+async function createHeadless(app) {
+	app.flow.setMode("fast");
+	await app.start();
+	const fatal = startLoop(app);
+	await settleAtFirstRest(app, fatal);
+	return {
+		/**
+		* Walks a route through the running loop.
+		*
+		* @param route - The player's answers and substituted sub-flow results, in order.
+		* @returns The state the walk ended in.
+		* @throws {Error} When a step is never reached, or the loop failed fatally.
+		* @example
+		* ```ts
+		* await game.walk([{ at: "home", intent: "play" }]);
+		* ```
+		*/
+		walk: async (route) => {
+			const state = await app.flow.walk(route).catch((error) => {
+				throw asError(fatal.error ?? error);
+			});
+			if (fatal.error !== void 0) throw asError(fatal.error);
+			return state;
+		},
+		/**
+		* Gives one answer to the gate, the way a tap does.
+		*
+		* @param answer - Intent and optional payload.
+		* @returns Whether the gate took it.
+		* @example
+		* ```ts
+		* game.answer({ intent: "play" });
+		* ```
+		*/
+		answer: (answer) => app.flow.gate.answer(answer),
+		/**
+		* Reads where the graph stands.
+		*
+		* @returns Whether it runs, the path, the stack, what it waits for and the mode.
+		* @example
+		* ```ts
+		* expect(game.state().path).toBe("home");
+		* ```
+		*/
+		state: () => app.flow.state(),
+		/**
+		* Reads the edges taken since the last checkpoint.
+		*
+		* @returns A copy of the journal.
+		* @example
+		* ```ts
+		* const [last] = game.history().slice(-1);
+		* ```
+		*/
+		history: () => app.flow.history(),
+		/**
+		* Stops the app, then re-throws a fatal error of the loop.
+		*
+		* @throws {Error} When the loop failed fatally.
+		* @example
+		* ```ts
+		* await game.stop();
+		* ```
+		*/
+		stop: async () => {
+			await app.stop();
+			if (fatal.error !== void 0) throw asError(fatal.error);
+		}
+	};
+}
+/**
+* Reads the rest node a repro starts at: its checkpoint, or the start of the main flow.
+*
+* @param app - The started app.
+* @param repro - Starting state, optional checkpoint and the route.
+* @returns The path of the node the repro enters.
+* @throws {Error} When the graph has no main flow to start from.
+* @example
+* ```ts
+* const path = reproPath(app, repro);
+* ```
+*/
+function reproPath(app, repro) {
+	if (repro.checkpoint !== void 0) return repro.checkpoint;
+	const graph = app.flow.describe();
+	const start = graph.flows[graph.main]?.start;
+	if (start === void 0) throw new Error(`[game] runRepro() found no flow "${graph.main}" to start from.\n  Name the checkpoint the repro was taken at.`);
+	return start;
+}
+/**
+* Builds the bookmark a repro is entered with: its state, its checkpoint and the hash of the
+* graph that runs now, so a checkpoint is accepted and any other rest node is checked.
+*
+* @param app - The started app.
+* @param repro - Starting state, optional checkpoint and the route.
+* @returns The bookmark to restore.
+* @example
+* ```ts
+* const bookmark = reproBookmark(app, repro);
+* ```
+*/
+function reproBookmark(app, repro) {
+	return {
+		path: reproPath(app, repro),
+		input: noPayload,
+		player: repro.player,
+		session: repro.session ?? {},
+		rng: repro.rng ?? {
+			seed: defaultSeed,
+			streams: {}
+		},
+		graph: graphHash(app.flow.describe())
+	};
+}
+/**
+* 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 });
+* ```
+*/
+async function runRepro(app, repro) {
+	const game = await createHeadless(app);
+	await app.flow.restore(reproBookmark(app, repro));
+	const state = await game.walk(repro.route);
+	const ended = app.flow.bookmark();
+	return {
+		path: state.stack.map((frame) => frame.node),
+		player: ended.player,
+		session: ended.session
+	};
+}
+/**
+* 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);
+* ```
+*/
+function stepFrames(app, count, deltaMs) {
+	for (let frame = 0; frame < count; frame += 1) app.time.step(deltaMs);
+}
+//#endregion
+export { createHeadless, fakeClock, memory, runRepro, saveOf, stepFrames };