@moku-labs/game 0.4.1 → 0.4.3

package/README.md

@@ -31,7 +31,7 @@ You write small nodes and edge tables. The engine runs them, saves on the edges
 ## Status
 
 > [!NOTE]
-> **`0.1.0`: the first working release.** It runs on our machines, two emulators and one very patient fixture game. The API may still change before `1.0`.
+> **`0.4`: working, still young.** It runs on our machines, two emulators and one very patient fixture game. The API may still change before `1.0`.
 
 | Milestone | What it added |
 |---|---|

package/bin/moku-game-assets.mjs

@@ -1,4 +1,8 @@
 #!/usr/bin/env bun
-import { compileStrings, runCli } from "../dist/assets.mjs";
+import { compileStrings, exportStrings, importStrings, runCli } from "../dist/assets.mjs";
 
-process.exitCode = await runCli(process.argv.slice(2), compileStrings);
+process.exitCode = await runCli(process.argv.slice(2), {
+  compile: compileStrings,
+  exportStrings,
+  importStrings
+});

package/dist/{dev-CQYJPmcD.mjs → capture-fpd83Mi5.mjs}

@@ -1151,33 +1151,4 @@ async function captureFrame(mctx, options) {
 	return shot === void 0 ? void 0 : answerOf(mctx, shot, options.against);
 }
 //#endregion
-//#region src/plugins/flow/doors/dev.ts
-/**
-* Reads the dev flag at call time. Undefined means off: production is the default.
-*
-* @returns True only when `__MOKU_GAME_DEV__` is exactly `true`.
-* @example
-* ```ts
-* // The dev page set the flag in web/dev.ts before the engine started.
-* globalThis.__MOKU_GAME_DEV__ = true;
-* isDev(); // true
-* ```
-*/
-function isDev() {
-	return typeof __MOKU_GAME_DEV__ !== "undefined" && __MOKU_GAME_DEV__ === true;
-}
-/**
-* Builds the error a control command throws outside a dev build.
-*
-* @returns The error, ready to throw.
-* @example
-* ```ts
-* // A production build called a /control command.
-* controlRefused().message; // "[game] Control commands run in dev builds only.\n  Define __MOKU_GAME_DEV__ as true in the dev build."
-* ```
-*/
-function controlRefused() {
-	return /* @__PURE__ */ new Error("[game] Control commands run in dev builds only.\n  Define __MOKU_GAME_DEV__ as true in the dev build.");
-}
-//#endregion
-export { serveCaptures as a, collectFlows as c, framePath as d, graphHash as f, pushEntry as h, captureFrame as i, describeGraph as l, compact as m, isDev as n, servePaused as o, slotNames as p, cancelCaptures as r, sheetAlone as s, controlRefused as t, findNode as u };
+export { sheetAlone as a, findNode as c, slotNames as d, compact as f, servePaused as i, framePath as l, captureFrame as n, collectFlows as o, pushEntry as p, serveCaptures as r, describeGraph as s, cancelCaptures as t, graphHash as u };

package/dist/control.d.mts

@@ -4,9 +4,9 @@ import { t as defineCommand } from "./define-BKWjWgyQ.mjs";
 
 //#region src/plugins/flow/doors/dev.d.ts
 /**
- * @file flow/doors — the dev flag. `__MOKU_GAME_DEV__` is a global the engine never replaces: a
- * game's dev build defines it `true` (bundler `define`) or sets `globalThis.__MOKU_GAME_DEV__`
- * before the engine runs; undefined means a production build.
+ * @file flow/doors — the dev flag and the errors a door throws. `__MOKU_GAME_DEV__` is a global
+ * the engine never replaces: a game's dev build defines it `true` (bundler `define`) or sets
+ * `globalThis.__MOKU_GAME_DEV__` before the engine runs; undefined means a production build.
  *
  * Bun does not inline `isDev()` across modules (checked on Bun 1.3.14), so a branch that must
  * vanish from a production bundle writes the guard inline:

package/dist/control.mjs

@@ -1,4 +1,4 @@
-import { t as controlRefused } from "./dev-CQYJPmcD.mjs";
-import { n as commands, t as run } from "./run-BfuMLahc.mjs";
+import { t as controlRefused } from "./dev-B5p9_3fz.mjs";
+import { n as commands, t as run } from "./run-C7O77UQR.mjs";
 import { s as defineCommand } from "./input-CK4nxBO1.mjs";
 export { commands, controlRefused, defineCommand, run };

package/dist/dev-B5p9_3fz.mjs

@@ -0,0 +1,44 @@
+//#region src/plugins/flow/doors/dev.ts
+/**
+* Reads the dev flag at call time. Undefined means off: production is the default.
+*
+* @returns True only when `__MOKU_GAME_DEV__` is exactly `true`.
+* @example
+* ```ts
+* // The dev page set the flag in web/dev.ts before the engine started.
+* globalThis.__MOKU_GAME_DEV__ = true;
+* isDev(); // true
+* ```
+*/
+function isDev() {
+	return typeof __MOKU_GAME_DEV__ !== "undefined" && __MOKU_GAME_DEV__ === true;
+}
+/**
+* Builds the error a control command throws outside a dev build.
+*
+* @returns The error, ready to throw.
+* @example
+* ```ts
+* // A production build called a /control command.
+* controlRefused().message; // "[game] Control commands run in dev builds only.\n  Define __MOKU_GAME_DEV__ as true in the dev build."
+* ```
+*/
+function controlRefused() {
+	return /* @__PURE__ */ new Error("[game] Control commands run in dev builds only.\n  Define __MOKU_GAME_DEV__ as true in the dev build.");
+}
+/**
+* Builds the error a door source throws when the opt-in plugin it reads is not installed.
+*
+* @param id - The id of the source.
+* @param plugin - The export name of the plugin it reads.
+* @returns The error, ready to throw.
+* @example
+* ```ts
+* notInstalled("game.sounds", "audioPlugin").message; // "[game] The source game.sounds needs audioPlugin.\n  Add audioPlugin to createApp({ plugins })."
+* ```
+*/
+function notInstalled(id, plugin) {
+	return /* @__PURE__ */ new Error(`[game] The source ${id} needs ${plugin}.\n  Add ${plugin} to createApp({ plugins }).`);
+}
+//#endregion
+export { isDev as n, notInstalled as r, controlRefused as t };

package/dist/index.d.mts

@@ -1396,7 +1396,7 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
     rolledBackTo: string;
     retry: boolean;
   };
-}> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common/browser").LogConfig, import("@moku-labs/common/browser").LogState, import("@moku-labs/common/browser").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common/browser").EnvConfig, import("@moku-labs/common/browser").EnvState, import("@moku-labs/common/browser").EnvApi>]>> | undefined) => import("@moku-labs/core").App<Config$9, Events$1, (import("@moku-labs/core").PluginInstance<"time", Config$7, State$7, Api$5, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"lifecycle", Config$4, State$4, Api$3, {
+}> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common/browser").LogConfig, import("@moku-labs/common/browser").LogState, import("@moku-labs/common/browser").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common/browser").EnvConfig, import("@moku-labs/common/browser").EnvState, import("@moku-labs/common/browser").EnvApi>]>, import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common/browser").LogConfig, import("@moku-labs/common/browser").LogState, import("@moku-labs/common/browser").LogApi> | import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common/browser").EnvConfig, import("@moku-labs/common/browser").EnvState, import("@moku-labs/common/browser").EnvApi>> | undefined) => import("@moku-labs/core").App<Config$9, Events$1, (import("@moku-labs/core").PluginInstance<"time", Config$7, State$7, Api$5, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"lifecycle", Config$4, State$4, Api$3, {
   "lifecycle:changed": {
     reason: PauseReason;
     action: "push" | "pop";

package/dist/index.mjs

@@ -1,7 +1,8 @@
 import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
 import { a as enableDraftPatches, i as dropDrafts, o as finishDrafts, r as deepFreeze, s as openDrafts, t as memory } from "./memory-CvgdnsQO.mjs";
-import { a as serveCaptures, c as collectFlows, d as framePath, f as graphHash, h as pushEntry, i as captureFrame, l as describeGraph, m as compact, n as isDev, o as servePaused, p as slotNames, r as cancelCaptures, u as findNode } from "./dev-CQYJPmcD.mjs";
+import { c as findNode, d as slotNames, f as compact, i as servePaused, l as framePath, n as captureFrame, o as collectFlows, p as pushEntry, r as serveCaptures, s as describeGraph, t as cancelCaptures, u as graphHash } from "./capture-fpd83Mi5.mjs";
 import { A as system, C as Exiting, D as component, E as Tree, O as mut, S as sprite, T as Order, _ as Parent, a as visualOf$1, b as Transform, c as Text, d as defineTextStyles, f as label, g as NineSlice, h as Display, j as tag, k as resource, l as bind, m as textFor, n as fitScaleOf, o as visualRectOf, p as readStyle, r as samePose, s as Countdown, t as CONTENT, u as builtInStyles, v as Shape, w as Layer, x as componentsFor, y as Sprite } from "./visual-DUvvPPCt.mjs";
+import { n as isDev } from "./dev-B5p9_3fz.mjs";
 import { n as flatten, r as defineComponent } from "./flatten-BkXuscAV.mjs";
 import { envPlugin, logPlugin } from "@moku-labs/common/browser";
 import { createCoreConfig } from "@moku-labs/core";

package/dist/inspect.d.mts

@@ -95,10 +95,10 @@ declare const sources: Readonly<{
   sounds: Source<{
     last: "number?";
   }, readonly SoundEntry[], HeadlessApp & {
-    readonly audio: AudioApi;
+    readonly audio?: AudioApi;
   }>;
   effects: Source<{}, EffectsStats, HeadlessApp & {
-    readonly effects: EffectsApi;
+    readonly effects?: EffectsApi;
   }>;
   assets: Source<{}, Usage, HeadlessApp & {
     readonly assets: Api$3;

package/dist/inspect.mjs

@@ -1,3 +1,3 @@
 import { c as defineSource } from "./input-CK4nxBO1.mjs";
-import { n as read, r as watch, t as sources } from "./sources-C1uGjz4l.mjs";
+import { n as read, r as watch, t as sources } from "./sources-CTGuY3Fe.mjs";
 export { defineSource, read, sources, watch };

package/dist/{run-BfuMLahc.mjs → run-C7O77UQR.mjs}

@@ -1,4 +1,5 @@
-import { f as graphHash, n as isDev, s as sheetAlone, t as controlRefused } from "./dev-CQYJPmcD.mjs";
+import { a as sheetAlone, u as graphHash } from "./capture-fpd83Mi5.mjs";
+import { n as isDev, t as controlRefused } from "./dev-B5p9_3fz.mjs";
 import { a as isProjectionTarget, i as recordCheat, o as readTarget, r as isTainted, s as defineCommand, t as inputOrEmpty } from "./input-CK4nxBO1.mjs";
 //#region src/plugins/flow/headless.ts
 const noPayload = null;

package/dist/{sources-C1uGjz4l.mjs → sources-CTGuY3Fe.mjs}

@@ -1,4 +1,5 @@
 import { i as scaleByFits, w as Layer } from "./visual-DUvvPPCt.mjs";
+import { r as notInstalled } from "./dev-B5p9_3fz.mjs";
 import { c as defineSource, n as cheatsOf, o as readTarget, r as isTainted, t as inputOrEmpty } from "./input-CK4nxBO1.mjs";
 //#region src/plugins/flow/doors/read.ts
 /**
@@ -105,6 +106,7 @@ const assetsSource = defineSource({
 * 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.
 *
+* @throws {Error} `[game] The source game.sounds needs audioPlugin.` when the app has no `audioPlugin`.
 * @example
 * ```ts
 * // After a tap on Deliver, on the dev page that sets `journal: 200`.
@@ -118,6 +120,7 @@ const soundsSource = defineSource({
 	input: { last: "number?" },
 	changes: "frame",
 	read: (app, { last }) => {
+		if (app.audio === void 0) throw notInstalled("game.sounds", "audioPlugin");
 		const entries = app.audio.journal();
 		return last === void 0 ? entries : entries.slice(Math.max(0, entries.length - last));
 	}
@@ -132,6 +135,7 @@ const soundsSource = defineSource({
 * What the effects draw now: live particles, emitter instances with orphans, filter instances
 * and the render passes of the frame.
 *
+* @throws {Error} `[game] The source game.effects needs effectsPlugin.` when the app has no `effectsPlugin`.
 * @example
 * ```ts
 * // The editor's stats panel while the board rests: one steam stream and the glows of 24 cards.
@@ -144,7 +148,10 @@ const effectsSource = defineSource({
 	title: "Effects",
 	input: {},
 	changes: "frame",
-	read: (app) => app.effects.stats()
+	read: (app) => {
+		if (app.effects === void 0) throw notInstalled("game.effects", "effectsPlugin");
+		return app.effects.stats();
+	}
 });
 //#endregion
 //#region src/plugins/model/inspect.ts

package/dist/testing.mjs

@@ -1,6 +1,6 @@
 import { n as saveOf, t as memory } from "./memory-CvgdnsQO.mjs";
-import { a as stepFrames, i as runRepro, n as commands, r as createHeadless, t as run } from "./run-BfuMLahc.mjs";
-import { n as read, t as sources } from "./sources-C1uGjz4l.mjs";
+import { a as stepFrames, i as runRepro, n as commands, r as createHeadless, t as run } from "./run-C7O77UQR.mjs";
+import { n as read, t as sources } from "./sources-CTGuY3Fe.mjs";
 import { createBrandConsole } from "@moku-labs/common/cli";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";

package/llms.txt

@@ -466,8 +466,8 @@ A plugin that owns a resource stores it in its state and frees it in `onStop: ({
 
 Two subpaths, neither on the root (V4). An editor, MCP tools and e2e scripts reach a running game through them; `docs/doors.md` in the engine repository has the full catalogue.
 
-- `@moku-labs/game/inspect`: `read(app, source, input?)` reads once; `watch(app, source, input, fn)` reads on the `signals` phase when the source changes and returns the stop function; `defineSource`; the frozen catalogue `sources`; the types `Source`, `InputSchema`, `InputOf`. Every source only reads, so the door is safe in a production build. Keys of `sources`: `graph`, `position`, `history`, `tainted`, `cheats`, `model`, `entities`, `projections`, `ui`, `rect`, `render`, `effects`, `sounds`, `assets`, `log`; their ids are `game.<key>`.
-- `@moku-labs/game/control`: `run(app, command, input?)` resolves `{ value, state }`, `state` being `{ path, frame, tainted }`; `defineCommand`; `controlRefused`; the frozen catalogue `commands`; the types `Command`, `Ran`. Keys of `commands`: `answer`, `tap`, `drag`, `key`, `fill`, `walk`, `bookmark`, `restore`, `step`, `pause`, `resume`, `capture`, `debug`, `reducedMotion`.
+- `@moku-labs/game/inspect`: `read(app, source, input?)` reads once; `watch(app, source, input, fn)` reads on the `signals` phase when the source changes and returns the stop function; `defineSource`; the frozen catalogue `sources`; the types `Source`, `InputSchema`, `InputOf`. Every source only reads, so the door is safe in a production build. Keys of `sources`: `graph`, `position`, `history`, `tainted`, `cheats`, `model`, `entities`, `projections`, `ui`, `locate`, `render`, `sounds`, `effects`, `assets`, `log`, `explain`, `diff`, `schema`, `at`; their ids are `game.<key>`. `locate` takes `{ key }` (a ui element) or `{ target }` (a view by projection key) and answers its box in CSS px, the numbers Playwright clicks. `at` takes `{ x, y }` in CSS px and lists the views under that point, topmost first. `explain` takes `{ entity }` and answers that entity in full, `undefined` for a stale id. `diff` takes `{ from, to }` frames and answers what changed per entity; it throws in a production build and for a frame outside the last 120. `schema` lists every component and tag type the world met, with the JSON kind of each field. `sounds` throws `[game] The source game.sounds needs audioPlugin.` and `effects` throws `[game] The source game.effects needs effectsPlugin.` when that plugin is not installed; the editor lists such a source as not installed.
+- `@moku-labs/game/control`: `run(app, command, input?)` resolves `{ value, state }`, `state` being `{ path, frame, tainted }`; `defineCommand`; `controlRefused`; the frozen catalogue `commands`; the types `Command`, `Ran`. Keys of `commands`: `answer`, `tap`, `drag`, `key`, `fill`, `walk`, `bookmark`, `restore`, `step`, `pause`, `resume`, `capture`, `debug`, `reducedMotion`, `timeScale`, `trace`. `capture` resolves `{ png }`, and `{ png, legend }` with `legend: true`; `undefined` while the renderer is inert. `timeScale` takes `{ scale }`; 0 freezes game time while the frames keep running. `trace` takes `{ path }`, a list of views by projection key, and answers whether the gate took the answer.
 - Commands run in dev builds only. Only `__MOKU_GAME_DEV__ === true` turns the dev build on: a bundler `define` (`true` in dev, `false` in production), `globalThis.__MOKU_GAME_DEV__ = true` in the dev entry, or `vi.stubGlobal("__MOKU_GAME_DEV__", true)` in a test. Otherwise `run` throws `[game] Control commands run in dev builds only.`
 - A command's effect is `read`, `route`, `cosmetic`, `cheat` or `raw`. A `cheat` or `raw` command taints the session and is journaled; read it with `sources.tainted` and `sources.cheats`. Of the base commands only `restore` is `raw`.
 - A game's own: `defineSource({ id, title, input, changes, read })` with `changes` `"frame"`, `"commit"` or `"edge"`, and `defineCommand({ id, title, input, effect, run })`. The id is camelCase words joined by dots, at least two: `dice.rolls`. An input schema maps field names to `"string"`, `"number"`, `"boolean"` or `"json"`; a trailing `?` makes one optional. A command body starts with `if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();`. Keep them in `.dev` modules that only the dev entry and the tests import.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/game",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "2D puzzle game engine on TypeScript and PixiJS, built on @moku-labs/core.",
   "type": "module",
   "sideEffects": false,
@@ -79,11 +79,21 @@
     "release:doctor": "moku-release doctor",
     "release": "moku-release"
   },
+  "dependencies": {
+    "immer": "11.1.18",
+    "maxrects-packer": "2.7.3",
+    "yoga-layout": "3.2.1"
+  },
   "peerDependencies": {
+    "@moku-labs/common": "^0.3.4",
+    "@moku-labs/core": "^1.7.1",
     "pixi.js": "^8.0.0",
     "playwright-core": ">=1.50.0",
     "sharp": "^0.34.0"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "peerDependenciesMeta": {
     "playwright-core": {
       "optional": true
@@ -98,6 +108,8 @@
     "@biomejs/biome": "2.4.16",
     "@formatjs/icu-messageformat-parser": "3.5.20",
     "@moku-labs/ci": "1.2.6",
+    "@moku-labs/common": "0.3.4",
+    "@moku-labs/core": "1.7.1",
     "@moku-labs/native": "0.3.0",
     "@moku-labs/system": "0.3.0",
     "@tauri-apps/api": "2.12.1",
@@ -120,15 +132,5 @@
     "typescript": "6.0.3",
     "typescript-eslint": "8.58.0",
     "vitest": "4.0.18"
-  },
-  "dependencies": {
-    "@moku-labs/common": "0.3.3",
-    "@moku-labs/core": "1.7.0",
-    "immer": "11.1.18",
-    "maxrects-packer": "2.7.3",
-    "yoga-layout": "3.2.1"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }