@moku-labs/game 0.0.2 → 0.0.3

package/dist/{define-sFoO3y6X.d.mts → types-D0uYTTC3.d.mts}

@@ -1,7 +1,184 @@
-import { K as Snapshot, L as Json } from "./types-JNc_UQBo.mjs";
-import { t as HeadlessApp } from "./headless-KaSWcd0s.mjs";
+import { At as Json, Ht as RngState, St as Api, ft as FlowState, ht as RouteStep, pt as JournalEntry, q as Api$1, xt as Answer, zt as Snapshot } from "./types-Cjf3ywai.mjs";
 import { Log } from "@moku-labs/common/browser";
 
+//#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
+ * // A test of the dice game: two rolls, no screen, no waiting.
+ * const game = await createHeadless(app);
+ * const state = await game.walk([{ at: "home", intent: "roll" }, { at: "home", intent: "roll" }]);
+ *
+ * state.path; // "home"
+ * await game.stop();
+ * ```
+ */
+type HeadlessGame = {
+  /**
+   * 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
+   * // Open the board and tap the generator twice. Every node's logic runs for real.
+   * const tap = { at: "board/awaitIntent", intent: "tap", payload: { generatorId: "sawmill" } };
+   * const state = await game.walk([{ at: "home", intent: "play" }, tap, tap]);
+   *
+   * state.path; // "board/awaitIntent"
+   * ```
+   */
+  walk(route: readonly RouteStep[]): Promise<FlowState>;
+  /**
+   * 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
+   * // One tap without a route. The test then waits for the loop by itself.
+   * game.answer({ intent: "play" }); // true: "home" rests and lists "play"
+   * ```
+   */
+  answer(answer: Answer): boolean;
+  /**
+   * Reads where the graph stands.
+   *
+   * @returns Whether it runs, the path, the stack, what it waits for and the mode.
+   * @example
+   * ```ts
+   * // Right after createHeadless: the graph rests at its first rest node.
+   * game.state().path; // "home"
+   * game.state().pending; // { gate: ["play"] }
+   * ```
+   */
+  state(): FlowState;
+  /**
+   * Reads the edges taken since the last checkpoint.
+   *
+   * @returns A copy of the journal.
+   * @example
+   * ```ts
+   * // After a merge onto an empty cell: the last edge says why the move was refused.
+   * const last = game.history().at(-1);
+   * // last?.path: "board/merge", last?.outcome: "rejected", last?.payload: { reason: "empty" }
+   * ```
+   */
+  history(): readonly JournalEntry[];
+  /**
+   * Stops the app, then re-throws a fatal error of the loop.
+   *
+   * @throws {Error} When the loop failed fatally.
+   * @example
+   * ```ts
+   * // The last line of a headless test. A fatal error of the loop fails the test here.
+   * await game.stop();
+   * ```
+   */
+  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 result: ReproResult = { path: ["home"], player: { coins: 3 }, session: { visits: 1 } };
+ * ```
+ */
+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
+ * // A test starts the merge game without a screen. The call resolves at the first rest node.
+ * const game = await createHeadless(app);
+ *
+ * game.state().path; // "home": the transit node "boot" was played out
+ * game.state().mode; // "fast"
+ * 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
+ * // A bug report on the dice game: "reset keeps my coins". Replay it from the "home" checkpoint.
+ * const reset = { at: "home", intent: "reset" };
+ * const result = await runRepro(app, { player: { coins: 7 }, checkpoint: "home", route: [reset] });
+ *
+ * result.player; // { coins: 0 }; result.path is ["home"]
+ * await app.stop(); // the app keeps running after the run
+ * ```
+ */
+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
+ * // A headless game has no frame source: the test moves the six frame phases by hand.
+ * stepFrames(app, 2, 16);
+ * app.time.snapshot(); // frame: 2, delta: 16, elapsed: 32
+ * ```
+ */
+declare function stepFrames(app: HeadlessApp, count: number, deltaMs: number): void;
+//#endregion
 //#region src/plugins/flow/doors/types.d.ts
 /**
  * The kinds an input field can take. `json` is any JSON value the command checks itself.
@@ -212,52 +389,4 @@ type ControlApp = HeadlessApp & {
   readonly log: Log.LogApi;
 };
 //#endregion
-//#region src/plugins/flow/doors/define.d.ts
-/**
- * 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"
- * ```
- */
-declare function defineSource<S extends InputSchema, O, App = HeadlessApp>(source: Source<S, O, App>): Source<S, O, App>;
-/**
- * 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"
- * ```
- */
-declare function defineCommand<S extends InputSchema, O, App = HeadlessApp>(command: Command<S, O, App>): Command<S, O, App>;
-//#endregion
-export { ControlApp as a, InputSchema as c, WatchApp as d, WatchInput as f, Command as i, Ran as l, defineSource as n, InputArguments as o, CheatEntry as r, InputOf as s, defineCommand as t, Source as u };
+export { stepFrames as _, InputOf as a, Source as c, HeadlessApp as d, HeadlessGame as f, runRepro as g, createHeadless as h, InputArguments as i, WatchApp as l, ReproResult as m, Command as n, InputSchema as o, Repro as p, ControlApp as r, Ran as s, CheatEntry as t, WatchInput as u };

package/dist/{types-DWILGrPn.d.mts → types-DgwbzDLP.d.mts}

@@ -1,11 +1,10 @@
-import { T as Descriptor, k as Api$2, lt as Require, t as Api$1, x as NodeInfo } from "./types-JNc_UQBo.mjs";
-import { r as PixiTexture, t as Api$3 } from "./types-BxkNNYul.mjs";
+import { St as Api$3, f as SliceFrame, mt as NodeInfo, nn as Require, o as PixiTexture, q as Api$1, t as Api$2, vt as Descriptor } from "./types-Cjf3ywai.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 
 //#region src/plugins/assets/types.d.ts
 declare namespace types_d_exports {
-  export { Api, AssetKind, AssetsCtx, AssetsIo, AtlasFrame, BundleMap, BundleRecord, BundleSpec, BundleUsage, Config, CreateTextureOptions, DecodedImage, DefineBundles, Deps, Events, FetchResponse, FlowRest, FontAsset, FontPage, Inflight, KernelSlice, LoadBundles, LoadReason, LoadResult, LoadedAssets, LoadedFont, Manifest, ManifestBundle, ManifestFile, NineBorders, NineSlice, PreloadQueue, State, Texture, Tier, Usage };
+  export { Api, AssetKind, AssetsCtx, AssetsIo, AtlasFrame, AtlasPage, BundleMap, BundleRecord, BundleSpec, BundleUsage, Config, CreateTextureOptions, DecodedImage, DefineBundles, Deps, Events, FetchResponse, FlowRest, FontAsset, FontPage, Inflight, KernelSlice, LoadBundles, LoadReason, LoadResult, LoadedAssets, LoadedFont, Manifest, ManifestBundle, ManifestFile, NineBorders, NineSlice, PreloadQueue, State, Texture, Tier, Usage };
 }
 /**
  * When a bundle is loaded. `boot` and `core` stay for the whole session, `scene` and `feature`
@@ -88,6 +87,7 @@ type FetchResponse = {
  *   }),
  *   decode: async () => bitmap,
  *   createTexture: () => ({ id: "t1" }) as unknown as Texture,
+ *   sliceTexture: (page, frame) => ({ id: "s1", page, frame }) as unknown as Texture,
  *   destroyTexture: texture => destroyed.push(texture)
  * };
  *
@@ -122,7 +122,19 @@ type AssetsIo = {
    */
   createTexture(image: DecodedImage, options?: CreateTextureOptions): Texture;
   /**
-   * Frees one texture and its source.
+   * Cuts the texture of one packed file out of its atlas page. The slice shares the page's
+   * source: no pixel is copied. Same shape as `renderer.sync.textures.slice`; the manifest's
+   * `atlas` frame is passed as it is.
+   *
+   * @param page - The page texture, made by `createTexture`.
+   * @param frame - Where the file lies on the page, in page pixels.
+   * @param options - `nine` becomes the default nine-slice borders of the slice.
+   * @returns The new texture over the page's source.
+   */
+  sliceTexture(page: Texture, frame: SliceFrame, options?: CreateTextureOptions): Texture;
+  /**
+   * Frees one texture. A page frees its source too; a slice frees only itself, so the slices of
+   * a bundle go first and its pages after them.
    *
    * @param texture - The texture to free.
    */
@@ -144,11 +156,13 @@ type NineSlice = {
   bottom: number;
 };
 /**
- * Reserved atlas placement. V2 never writes it and refuses to load a file that carries it.
+ * Where a packed file lies: `page` is the id of a page of the same bundle, never a file name, and
+ * the frame is in page pixels. `width` and `height` equal the file's own, so its `nine` stays
+ * valid as it is. The packer writes it; the loader cuts the file out of the page.
  *
  * @example
  * ```ts
- * const frame: AtlasFrame = { page: "ui-0.png", x: 0, y: 0, width: 128, height: 128 };
+ * const frame: AtlasFrame = { page: "ui/main-0", x: 583, y: 595, width: 256, height: 128 };
  * ```
  */
 type AtlasFrame = {
@@ -158,6 +172,29 @@ type AtlasFrame = {
   width: number;
   height: number;
 };
+/**
+ * One atlas page of a packed bundle. `id` is `<bundle>/<group>-<index>`, the name an `atlas`
+ * frame uses; `path` is the hashed WebP file, read like the `path` of a file. `mb` is
+ * `width × height × 4 / 1 048 576`: the page carries the cost of every file packed on it.
+ *
+ * @example
+ * ```ts
+ * const page: AtlasPage = {
+ *   id: "ui/main-0",
+ *   path: "ui/main-0-3b1d55a0c9.webp",
+ *   width: 966,
+ *   height: 1365,
+ *   mb: 5.03
+ * };
+ * ```
+ */
+type AtlasPage = {
+  id: string;
+  path: string;
+  width: number;
+  height: number;
+  mb: number;
+};
 /**
  * One page image of a font. A page has no key of its own: it belongs to the `.fnt` file that
  * names it, and is loaded and freed with it.
@@ -180,12 +217,15 @@ type FontPage = {
 };
 /**
  * One file of a bundle. `mb` is what it costs: `width × height × 4` bytes for a texture, the sum
- * of the pages for a font, the size of the file for audio. `kind` is absent for a texture, which
- * is what every manifest written before fonts and audio carries.
+ * of the pages for a font, the size of the file for audio, and `0` for a texture packed in an
+ * atlas, whose page carries the cost. `kind` is absent for a texture, which is what every
+ * manifest written before fonts and audio carries. A loose file has `path`; a packed texture has
+ * `atlas` and no `path`.
  *
  * @example
  * ```ts
- * const file: ManifestFile = {
+ * // The dev manifest of the scanner: a loose file.
+ * const loose: ManifestFile = {
  *   key: "ui.panel",
  *   path: "features/ui/assets/panel{nine=48}.png",
  *   width: 256,
@@ -193,11 +233,21 @@ type FontPage = {
  *   mb: 0.125,
  *   nine: { left: 48, top: 48, right: 48, bottom: 48 }
  * };
+ *
+ * // The packed manifest: the same key, cut out of the page "ui/main-0".
+ * const packed: ManifestFile = {
+ *   key: "ui.panel",
+ *   width: 256,
+ *   height: 128,
+ *   mb: 0,
+ *   nine: { left: 48, top: 48, right: 48, bottom: 48 },
+ *   atlas: { page: "ui/main-0", x: 583, y: 595, width: 256, height: 128 }
+ * };
  * ```
  */
 type ManifestFile = {
   key: string;
-  path: string;
+  path?: string;
   kind?: AssetKind;
   width: number;
   height: number;
@@ -207,7 +257,9 @@ type ManifestFile = {
   atlas?: AtlasFrame;
 };
 /**
- * One bundle of the manifest: which feature owns it, when it loads and what it costs.
+ * One bundle of the manifest: which feature owns it, when it loads and what it costs. `pages` is
+ * written by the packer only, sorted by id; `mb` is then its pages, its loose textures, its font
+ * pages and its audio bytes together.
  *
  * @example
  * ```ts
@@ -218,24 +270,37 @@ type ManifestBundle = {
   feature: string;
   tier: Tier;
   mb: number;
+  pages?: readonly AtlasPage[];
   files: readonly ManifestFile[];
 };
 /**
- * The manifest: the contract between the scanner, this plugin and the editor later. Bundles are
- * sorted by name and files by key, so two scans of the same tree give the same bytes.
+ * The manifest: the contract between the scanner, the packer, this plugin and the editor. Version
+ * `1` is the dev manifest of `bun run assets:keys`, version `2` the packed one of
+ * `bun run assets:pack`; the plugin reads both. Bundles are sorted by name, pages by id and files
+ * by key, so two runs on the same tree give the same bytes.
  *
  * @example
  * ```ts
+ * // A dev build: loose files, straight from the features.
  * const manifest: Manifest = {
  *   version: 1,
  *   bundles: { ui: { feature: "ui", tier: "core", mb: 0, files: [] } }
  * };
  *
  * createApp({ plugins: [...screen], pluginConfigs: { assets: { manifest } } });
+ *
+ * // The packed manifest of the same game: the panel is cut out of the page "ui/main-0".
+ * const page = { id: "ui/main-0", path: "ui/main-0-3b1d55a0c9.webp", width: 966, height: 1365, mb: 5.03 };
+ * const atlas = { page: "ui/main-0", x: 583, y: 595, width: 256, height: 128 };
+ * const panel = { key: "ui.panel", width: 256, height: 128, mb: 0, atlas };
+ * const packed: Manifest = {
+ *   version: 2,
+ *   bundles: { ui: { feature: "ui", tier: "core", mb: 5.03, pages: [page], files: [panel] } }
+ * };
  * ```
  */
 type Manifest = {
-  version: 1;
+  version: 1 | 2;
   bundles: Readonly<Record<string, ManifestBundle>>;
 };
 /**
@@ -339,13 +404,15 @@ type LoadedFont = FontAsset & {
   pages: readonly Texture[];
 };
 /**
- * What one bundle brought, by asset key: textures, fonts with their pages, and the undecoded
- * bytes of the audio files. A running load fills the same three maps before they are published.
+ * What one bundle brought: textures by asset key (a packed file's is a slice of its page), fonts
+ * with their pages, the undecoded bytes of the audio files, and the atlas pages by page id. A
+ * running load fills the same four maps before they are published.
  */
 type LoadedAssets = {
   textures: Map<string, Texture>;
   fonts: Map<string, LoadedFont>;
   audio: Map<string, ArrayBuffer>;
+  pages: Map<string, Texture>;
 };
 /**
  * What the plugin knows about one bundle. `lastUsed` is the value of `useCounter` at the last
@@ -530,7 +597,8 @@ type Api = {
   /**
    * The texture of a loaded asset key. It touches the use counter of the bundle, which is what
    * the LRU reads. A key of a bundle that is not loaded warns once, starts a background load and
-   * answers `undefined`; the sprites waiting for it are textured when that load lands.
+   * answers `undefined`; the sprites waiting for it are textured when that load lands. A key packed
+   * in an atlas answers its slice of the page, so a game never sees the difference.
    *
    * @param key - Asset key, as `generated/assets.ts` types it.
    * @returns The texture, or `undefined` while the bundle is not loaded.
@@ -590,8 +658,8 @@ type Api = {
  */
 type Deps = {
   flow: Api$1;
-  renderer: Api$3;
-  time: Api$2;
+  renderer: Api$2;
+  time: Api$3;
 };
 /**
  * What the kernel context offers before the deps are attached.