@moku-labs/game 0.8.0 → 0.10.0

package/dist/memory-CWlqhS7l.mjs

@@ -0,0 +1,136 @@
+import { t as applyTo } from "./drafts-BawpSaVp.mjs";
+//#region src/plugins/clock/system.ts
+/**
+* Tells whether a handle was produced by this source.
+*
+* @param handle - Handle given back to `clearTimer`.
+* @returns `true` when the handle carries a platform timer.
+* @example
+* ```ts
+* isSystemTimer({ timer: 7 }); // true
+* isSystemTimer(7); // false: a handle of another source is ignored
+* ```
+*/
+function isSystemTimer(handle) {
+	return typeof handle === "object" && handle !== null && "timer" in handle;
+}
+/**
+* Creates the system source: epoch milliseconds from the device clock and real timers.
+*
+* @returns A source reading `Date.now` and scheduling with `setTimeout`.
+*/
+function systemSource() {
+	return {
+		now: () => Date.now(),
+		setTimer: (callback, delayMs) => ({ timer: setTimeout(callback, delayMs) }),
+		clearTimer: (handle) => {
+			if (!isSystemTimer(handle)) return;
+			clearTimeout(handle.timer);
+		}
+	};
+}
+//#endregion
+//#region src/plugins/model/store/providers/memory.ts
+/** Seed of a save built by `saveOf` when the caller does not pin one. */
+const defaultSeed = 1;
+/** The base a patch applies to when the provider was never handed a document. */
+const noDocument = {};
+/**
+* Creates an in-memory provider that keeps what it was committed and records every call.
+* It is the default when a game configures no `playerProvider`, and the double every test uses:
+* `provider.calls` is the whole persistence protocol of one run, in order. The document lives as
+* long as the provider does, so a second app over the same instance reads what the first one
+* wrote, and nothing survives the process.
+*
+* `load()` reads the fixture, or everything committed since; without either, the player is new.
+* `commitDurable()` resolves at once: there is no disk behind it.
+*
+* @param fixture - The save `load()` starts from. Omitted: a new player.
+* @param fixture.state - The saved document.
+* @param fixture.version - Schema version of the saved document.
+* @returns A provider that keeps its document and records its calls.
+* @example
+* ```ts
+* // A new player is saved at once. One roll reaches the provider at the next rest node.
+* const provider = memory();
+* const game = await createHeadless(createGame(provider));
+*
+* await game.walk([{ at: "home", intent: "roll" }]);
+* provider.calls.map(call => call.method); // ["load", "commit", "commit"]
+* ```
+*/
+function memory(fixture) {
+	const calls = [];
+	const held = {
+		document: fixture?.state,
+		version: fixture?.version ?? 0
+	};
+	/**
+	* Applies the patches of one commit to the held document.
+	*
+	* @param patches - Doc patches since the last commit.
+	* @param version - Schema version this build writes.
+	* @throws {Error} When a patch names a path the held document does not have.
+	*/
+	const hold = (patches, version) => {
+		held.document = applyTo(held.document ?? noDocument, patches);
+		held.version = version;
+	};
+	return {
+		calls,
+		load: async () => {
+			calls.push({ method: "load" });
+			const document = held.document;
+			if (document === void 0) return null;
+			return {
+				state: document,
+				version: held.version
+			};
+		},
+		commit: (patches, version) => {
+			calls.push({
+				method: "commit",
+				patches,
+				version
+			});
+			hold(patches, version);
+		},
+		commitDurable: async (patches, txId, version) => {
+			calls.push({
+				method: "commitDurable",
+				patches,
+				txId,
+				version
+			});
+			hold(patches, version);
+		},
+		flush: async () => {
+			calls.push({ method: "flush" });
+		}
+	};
+}
+/**
+* Builds a save document from a player tree, with no rng streams drawn yet.
+* Short fixtures in tests read as `saveOf({ coins: 5 })` instead of spelling out the rng branch.
+*
+* @param player - Player tree of the save.
+* @param seed - Rng seed of the save.
+* @returns The save document.
+* @example
+* ```ts
+* // A returning player with 5 coins. The test starts from this save, not from `initialPlayer`.
+* saveOf({ coins: 5 }, 42); // { player: { coins: 5 }, rng: { seed: 42, streams: {} } }
+* const provider = memory({ state: saveOf({ coins: 5 }, 42), version: 1 });
+* ```
+*/
+function saveOf(player, seed = defaultSeed) {
+	return {
+		player,
+		rng: {
+			seed,
+			streams: {}
+		}
+	};
+}
+//#endregion
+export { saveOf as n, systemSource as r, memory as t };

package/dist/memory-DwDhfFWK.d.mts

@@ -0,0 +1,50 @@
+import { Xt as Json, nn as ProviderCall, rn as SaveDoc, tn as PlayerStateProvider } from "./types-ZQLYXo5X.mjs";
+
+//#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.
+ *
+ * `load()` reads the fixture, or everything committed since; without either, the player is new.
+ * `commitDurable()` resolves at once: there is no disk behind it.
+ *
+ * @param fixture - The save `load()` starts from. Omitted: a new player.
+ * @param fixture.state - The saved document.
+ * @param fixture.version - Schema version of the saved document.
+ * @returns A provider that keeps its document and records its calls.
+ * @example
+ * ```ts
+ * // A new player is saved at once. One roll reaches the provider at the next rest node.
+ * const provider = memory();
+ * const game = await createHeadless(createGame(provider));
+ *
+ * await game.walk([{ at: "home", intent: "roll" }]);
+ * provider.calls.map(call => call.method); // ["load", "commit", "commit"]
+ * ```
+ */
+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
+ * // 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 });
+ * ```
+ */
+declare function saveOf(player: Json, seed?: number): SaveDoc;
+//#endregion
+export { saveOf as n, memory as t };

package/dist/project.d.mts

@@ -4,8 +4,9 @@
  * it holds, the anchors of a key, the fresh lines `find` answers and the handle itself. The index
  * maps every engine id of a game (flows, nodes, features, scenes, projections, emitters, text
  * styles, styles, components and JSX keys) to anchors: a path plus a binding, a key or a component. It never
- * holds a line number; `find` reads the line from the file as it is on disk at the call. No type
- * here names a `typescript` type, so the shipped declarations need no TypeScript.
+ * holds a line number; `find` reads the line from the file as it is on disk at the call. Names are
+ * followed through relative imports and the tsconfig `paths` of the game. No type here names a
+ * `typescript` type, so the shipped declarations need no TypeScript.
  */
 /**
  * What `openProject` reads. Paths are root-relative POSIX; the root itself is resolved against the
@@ -15,11 +16,18 @@
  * ```ts
  * // The editor opens the mini game with the default manifest and a slower debounce.
  * const options: ProjectOptions = { root: "tests/fixtures/mini-game", debounceMs: 120 };
+ * // A v15 game whose aliases live in a second tsconfig.
+ * const game: ProjectOptions = { root: "games/orders", tsconfig: "tsconfig.game.json" };
  * ```
  */
 type ProjectOptions = {
   /** The folder of the game. A path that is not a directory rejects `openProject`. */root: string; /** The asset manifest, root-relative. Default `manifest.json`, the scanner's default. */
-  manifest?: string; /** The quiet period, in milliseconds, that closes a batch of file events. Default 75. */
+  manifest?: string;
+  /**
+   * The tsconfig whose `paths` the index follows, root-relative. Default `tsconfig.json`. A path
+   * that leaves the root or a file that does not parse rejects `openProject`.
+   */
+  tsconfig?: string; /** The quiet period, in milliseconds, that closes a batch of file events. Default 75. */
   debounceMs?: number;
 };
 /**
@@ -68,12 +76,15 @@ type Anchor = {
  * ```ts
  * index.symbols["flow:infoPopup"]; // { def: [{ path: "flows/info.ts", binding: "infoFlow" }] }
  * index.files["nodes/count.ts"]?.state; // "ok"
+ * // A game whose tsconfig.json holds paths, such as tests/fixtures/layout-game.
+ * index.tsconfig; // "tsconfig.json"
  * ```
  */
 type ProjectIndex = {
   /** The shape of this object. A change of shape bumps it. */schemaVersion: 1; /** sha1 hex over the sorted lines `${path}\0${hash}\n` of every indexed file. */
   revision: string; /** The asset manifest, root-relative, when that file exists. */
-  manifest?: string;
+  manifest?: string; /** The tsconfig, root-relative, when that file exists and holds `paths` the index follows. */
+  tsconfig?: string;
   /**
    * Every key: where it is defined (`def`), where its binding is used (`uses`, nodes, styles and
    * components, one level), and `conflict` when a key other than `jsx:` is defined twice.
@@ -150,12 +161,13 @@ type ProjectApi = {
    */
   readonly index: ProjectIndex;
   /**
-   * Answers where a key is defined, with lines read from the file on disk now. A file whose bytes
-   * changed since the index was built is parsed again for the answer; the index itself stays as
-   * it is until the next watch batch. A JSX key the game reports at run time also finds the
-   * patterns it was built from: exact keys first, then `{id}` and `{amountKey}` patterns filled
-   * with a literal prop of the same name on their component (both the pattern and the prop come
-   * back), then `*` patterns. An unknown key answers `[]`.
+   * Answers where a key is defined, with lines read from the file on disk now. A name is followed
+   * through relative imports and the tsconfig aliases, so `@features/home` reaches the file that
+   * declares the node. A file whose bytes changed since the index was built is parsed again for
+   * the answer; the index itself stays as it is until the next watch batch. A JSX key the game
+   * reports at run time also finds the patterns it was built from: exact keys first, then `{id}`
+   * and `{amountKey}` patterns filled with a literal prop of the same name on their component
+   * (both the pattern and the prop come back), then `*` patterns. An unknown key answers `[]`.
    *
    * @param key - An engine id: `node:infoPopup/count`, `flow:main`, `textStyle:ui.counter`, `jsx:infoPanelSpark`.
    * @returns One entry per place, in the order above; `broken` when the file does not parse now.
@@ -190,8 +202,9 @@ type ProjectApi = {
   watch(onIndex: (index: ProjectIndex, change: ProjectChange) => void): () => void;
   /**
    * Re-indexes one root-relative path now, for a caller that watches files itself. A deleted
-   * file drops its entries; a path that is not a `.ts` or `.tsx` source of the index changes
-   * nothing. The watch callers are not called.
+   * file drops its entries. The tsconfig, or a file it extends, reads the aliases again, and the
+   * index is rebuilt when names now follow them elsewhere. Any other path that is not a `.ts` or
+   * `.tsx` source of the index changes nothing. The watch callers are not called.
    *
    * @param path - The root-relative POSIX path of the file.
    * @returns The index after the file was read.
@@ -201,6 +214,8 @@ type ProjectApi = {
    * // The editor saved nodes/count.ts through its own file layer.
    * const index = await project.changed("nodes/count.ts");
    * index.files["nodes/count.ts"]?.state; // "ok"
+   * // It added a paths block to tsconfig.json: the keys behind the aliases join the index.
+   * (await project.changed("tsconfig.json")).tsconfig; // "tsconfig.json"
    * ```
    */
   changed(path: string): Promise<ProjectIndex>;
@@ -260,7 +275,8 @@ declare function runCli(argv: readonly string[], ui?: IndexUi): Promise<number>;
  * path), loads TypeScript, parses every source file and builds the index. Nothing is written to
  * disk and nothing is inferred from the working directory but the root itself.
  *
- * @param options - The game root, the manifest path and the quiet period of `watch`.
+ * @param options - The game root, the manifest path, the tsconfig whose `paths` the index follows
+ *   (`tsconfig`, root-relative, `tsconfig.json` by default) and the quiet period of `watch`.
  * @returns The handle; close it when the game closes.
  * @throws {Error} When the root is missing or not a directory, or the `typescript` package is not
  *   installed: `[game] The project index needs the "typescript" package.`