@moku-labs/game 0.1.0 → 0.2.0

package/llms.txt

@@ -0,0 +1,536 @@
+# @moku-labs/game
+
+> 2D puzzle game engine on TypeScript, built as a Layer-2 framework on @moku-labs/core. The game is a deterministic graph of business logic. State commits only on edges. Position is data. Player input and world events are answers a node waits for. The screen is a projection of committed state. V1 is the logic plugins `time`, `lifecycle`, `model`, `clock`, `flow` and a headless testing entry; V2 adds the screen plugins `world`, `renderer`, `input`, `assets`, `scenes`, a Pixi v8 renderer loaded lazily, and the `@moku-labs/game/assets` entry that generates typed asset keys. V3 adds the interface plugins `anim`, `i18n`, `text`, `ui` (`screen` lists all nine) and the opt-in `audio`: choreographies as data, strings as data, text from MSDF fonts, screens in JSX laid out by Yoga, sound as an effect a node awaits. V4 adds two doors for the editor: `@moku-labs/game/inspect` reads a running game, `@moku-labs/game/control` drives a dev build. V5 adds the opt-in plugin `effects`: particles and WGSL/GLSL filters as components. V6 adds the opt-in plugin `platform`: the Back button, haptics and keep-awake through a provider the game passes. The package is published on npm as `@moku-labs/game`, and this file ships inside it.
+
+Facts: Bun only. ESM only. `"sideEffects": false`. `pixi.js` `^8.0.0` is a peer dependency, no V1 code imports it. `playwright-core` (visual tests) and `sharp` (the asset pack) are optional peers. Node >= 24, Bun >= 1.3.14. TypeScript strict with `exactOptionalPropertyTypes` and `noUncheckedIndexedAccess`. The engine ships no genre rules: no merge, no match-3, no physics. A game brings its own pure rule functions.
+
+## Entry points
+
+- `@moku-labs/game`: everything a game imports.
+- `@moku-labs/game/testing`: headless play, repro runs, fake clock, in-memory save provider.
+- `@moku-labs/game/assets` (node and bun only): the asset key scanner, the production packer and the string compiler. The package bin `moku-game-assets` runs it.
+- `@moku-labs/game/inspect`: the read door of the editor, safe in a production build. See "Doors for the editor".
+- `@moku-labs/game/control`: the write door of the editor, dev builds only. See "Doors for the editor".
+- `@moku-labs/game/fonts/*`: the shipped MSDF body font and its licence. See "Fonts".
+- `@moku-labs/game/jsx-runtime` and `@moku-labs/game/jsx-dev-runtime`: what `"jsxImportSource": "@moku-labs/game"` resolves to. A game never imports them by hand.
+
+Root exports:
+- Functions: `createApp`, `createPlugin`, `defineGame`, `defineFeature`, `type`, `exit`, `to`, `slot`, `schedule`, `guide`, `hint`.
+- Class: `SaveUnreadableError`.
+- Plugin instances: `timePlugin`, `lifecyclePlugin`, `modelPlugin`, `clockPlugin`, `flowPlugin`, `worldPlugin`, `rendererPlugin`, `inputPlugin`, `assetsPlugin`, `scenesPlugin`, `animPlugin`, `i18nPlugin`, `textPlugin`, `uiPlugin`, `audioPlugin`, `effectsPlugin`, `platformPlugin`; the list `screen` = `world`, `renderer`, `input`, `assets`, `scenes`, `anim`, `i18n`, `text`, `ui`. `effects`, `audio` and `platform` are opt-in: `plugins: [...screen, effectsPlugin, audioPlugin, platformPlugin]`, `platform` last.
+- Screen helpers from the root: `component`, `tag`, `resource`, `mut`, `system`, `projection`, `Layer`, `Order`, `Exiting`, `Tree`, `Transform`, `Sprite`, `NineSlice`, `Shape`, `Parent`, `Display`, `sprite`, `Tappable`, `Pressable`, `Draggable`, `DropTarget`, `Swipeable`, `Touchable`, `Held`, `Hovered`, `PointerOver`, `Pressed`, `Pointer`, `defineBundles`, `load`, `defineScene`.
+- Interface helpers from the root (V3): `defineAnimation`, `sequence`, `parallel`, `stagger`, `tween`, `set`, `wait`, `mark`, `frames`, `sfx`, `haptic`, `use`, `spawn`, `spawned`, `play`, `external`, `defineMotion`, `Animation`, `Frames`; `tr`; `Text`, `label`, `defineTextStyles`; `defineComponent`, `popup`, `defineStyle`, `defineTokens`, `resolve`, `Box`, `LocalWrite`; `music`.
+- Effects helpers from the root (V5): `defineEmitter`, `Emitter`, `defineFilter`, `Glow`, `Outline`, `Blur`, `ColorMatrix`, `Noise`, `Displacement`, `Alpha`.
+- Platform from the root (V6): the types `PlatformProvider`, `BackResult`, `HapticKind` and the frozen list `HAPTIC_KINDS`.
+- `defineGame<Types>()` returns, typed by the game's `player`, `session`, `assets`, `bundles`, `scenes`, `strings` and `textStyles`: `defineNode`, `defineFlow`, `defineFeature`, `projection`, `sprite`, `Sprite`, `NineSlice`, `defineBundles`, `load`, `defineScene`, `defineAnimation`, `frames`, `sfx`, `play`, `tr`, `label`, `defineTextStyles`, `defineComponent`, `defineStyle`, `defineTokens`, `popup`, `music`, `Frames`, `defineEmitter`, `Emitter`, `Displacement`. `Types` is `{ player; session; assets: string; bundles?: string; scenes?: string; strings: Record<string, unknown>; textStyles?: string; emitters?: string }`.
+- `@moku-labs/game/assets`: `scanAssets(options)`, `emitKeys`, `emitManifest`, `compileStrings(root, out, options?)`, `checkStrings`, `packAssets(options)`, `runCli(argv, compileStrings)`. Asset key = feature + "." + path inside `assets/`. `runCli` (a game's `bun run assets:keys`) scans the assets and compiles `features/*/strings/<locale>.json` into `generated/strings.ts` (the `Strings` type for `defineGame`) and one `generated/strings.<locale>.ts` per locale; `--check` fails when any output is out of date; `--pack <dir>` writes the production build. The package bin `moku-game-assets` is this CLI: a game's script is `"assets:keys": "moku-game-assets --root src --manifest public/assets/manifest.json --keys src/generated/assets.ts"`.
+- Type namespaces: `Time`, `Lifecycle`, `Model`, `Clock`, `Flow`, `World`, `Renderer`, `Input`, `Assets`, `Scenes`, `Anim`, `I18n`, `TextTypes`, `Ui`, `Audio`, `Effects`, `Platform`. Use `import type { Flow } from "@moku-labs/game"` and then `Flow.RouteStep`, `Flow.NodeContext`, `Model.Json`, `Model.PlayerStateProvider`, `Clock.ClockSource`, `Time.Phase`, `Lifecycle.PauseReason`, `Anim.Target`, `I18n.Message`. `Text` is the component, so the text types are `TextTypes`.
+- `defineNode` and `defineFlow` are NOT root exports. They come from `defineGame<Types>()`.
+
+## Concepts
+
+- Node: a small function with a plain `await` body. It gets one context object and returns `out.<outcome>(payload)`. A bare string is not accepted.
+- Flow: an id, a `nodes` table, a `start` node and an `edges` table. One entry per outcome of every node. The compiler checks the table.
+- Exactly one node is active. The runner opens one model transaction per node run and commits it on the edge. A node that throws changes nothing.
+- Transit node: has `run`, no `rest`. Rest node: `rest: true`. The graph waits there. Without `run` it is a pure wait.
+- A pure wait ends in two ways. A gate answer whose `intent` is an outcome name: the answer payload becomes the outcome payload. Or a world event whose `type` is listed in the node's `inbox`: the event payload becomes the outcome payload.
+- Transition: rest node to rest node. It is a transaction. On an error the runner discards, rolls back to the last rest point, retries `retries` times, then enters `safeNode`. A failure inside `safeNode` rejects `run()`.
+- Entering a rest node calls `model.store.markRest()`: the save provider gets the patches. Leaving a `barrier` node calls `markBarrier(txId)`: a durable write, and rollback cannot cross it.
+- `checkpoint: true` on a rest node: the journal is compacted there. `safeNode` must be a checkpoint.
+- `over: true`: entering the node waits while a pointer is down.
+- Path: node names joined by `/` through sub-flows and slots. Examples: `"home"`, `"board/awaitIntent"`, `"afterBonus/thanks"`.
+- Edge target: a node name, `exit(...)` or `to(...)`. A payload must fit the input of the target. A node without input accepts any payload.
+- Sub-flow: a flow that declares `outcomes` is used as a node of another flow. `exit("name")` leaves it with that outcome.
+- Slot: `slot("name")` is a node with the single outcome `done`. Features contribute sub-flows to it. They run in `order`. `when(snapshot)` can skip one; it always reads the committed state, also what an earlier contribution of the same slot wrote. A contribution may hold a slot of its own. The slot ends with its own `done` edge after the last contribution.
+- Feature: `defineFeature(name, description)` makes an ordinary plugin that registers into `flow.features` in `onInit`. Pass it in `createApp({ plugins: [...] })`. `feature.logicOnly` is the same plugin with the V1 keys only, for headless tests.
+- Modes: `"live"` and `"fast"`. In fast mode effects answer instantly, hints are dropped and only `runInFast` handlers run. All node logic runs for real.
+
+## Authoring helpers, with signatures
+
+```ts
+function defineGame<Types extends Flow.GameTypes>();  // returns the helpers listed under "Root exports", typed by Types
+// GameTypes = { player: Json; session: Json; assets: string; strings: Record<string, unknown>;
+//               bundles?: string; scenes?: string; textStyles?: string; emitters?: string }
+
+function type<Payload = void>(): TypeTag<Payload>;
+
+// From the kit. Input and Tags are inferred from the spec.
+defineNode(spec: {
+  input?: TypeTag<Input>;
+  outcomes: Tags;                      // { done: type(), failed: type<{ reason: string }>() }
+  rest?: boolean;                      // run is required unless rest: true
+  over?: boolean;
+  checkpoint?: boolean;
+  barrier?: boolean;
+  inbox?: readonly (keyof Tags & string)[];
+  run?: (ctx: NodeContext) => Result | Promise<Result>;
+}): NodeDefinition;
+
+defineFlow(id: string, spec: {
+  nodes: Nodes;                        // node, sub-flow or slot per name
+  start: string;                       // a node whose input accepts the flow input
+  edges: Table;                        // edges[node][outcome] = target
+  input?: TypeTag<Input>;
+  outcomes?: FlowTags;                 // declare them to use the flow as a node
+}): FlowDefinition;
+
+function exit<const Name extends string>(outcome: Name): Exit<Name>;
+function to<const TargetName extends string, Payload, Output>(
+  target: TargetName,
+  map: (payload: Payload) => Output    // annotate the parameter type yourself
+): Mapped<TargetName, Payload, Output>;
+function slot(name: string): SlotNode;
+
+function defineFeature(name: string, description: FeatureDescription): FeaturePlugin;
+// FeatureDescription = {
+//   nodes?: readonly AnyNode[];
+//   flows?: readonly AnyFlow[];
+//   contribute?: Record<string, { flow: AnyFlow; order: number; when?: (snapshot: Snapshot) => boolean }>;
+//   projections?, systems?, components?, scenes?, assets?;   // V2 keys, read by world, scenes and assets
+//   animations?: readonly AnimationDefinition[];              // V3, read by anim
+//   ui?: readonly ComponentDefinition[];                      // V3, read by ui (defineComponent results)
+//   strings?: Record<locale, CompiledMessages | (() => Promise<unknown>)>;   // V3, read by i18n
+//   textStyles?: ReturnType<typeof defineTextStyles>;         // V3, read by text
+//   emitters?: readonly ReturnType<typeof defineEmitter>[];   // V5, read by effects
+//   filters?: readonly ReturnType<typeof defineFilter>[];     // V5, read by effects
+// }
+
+function schedule(moment: number | undefined): Descriptor;  // awaited, asks the clock for one `elapsed`
+function guide(options: GuideOptions): Descriptor;          // awaited, narrows the gate to one answer
+function hint(kind: string, payload?: Json): Hint;          // for fx.emit, cosmetic
+// GuideOptions = { allow: { intent: string; payload?: Json }; highlight?: readonly string[]; hand?: "tap" | "drag"; text?: string }
+// Descriptor   = { kind: string; payload?: Json; answers?: readonly string[]; cosmetic?: boolean }
+```
+
+## Node context
+
+```ts
+type NodeContext = {
+  input: Input;          // payload of the edge that led here
+  player: Player;        // draft of the saved player tree, mutate it
+  session: Session;      // draft of the session tree, never saved
+  rng: RngView;          // rng.stream(id) gives a deterministic stream
+  fx: NodeFx;            // await fx(descriptor), fx.emit(hint(...))
+  out: Out;              // one method per declared outcome
+  signal: AbortSignal;   // aborted on stop, restore and inbox delivery
+  now: number;           // clock.now() read once at node entry
+};
+```
+
+`RngStream` methods, integers only: `int(maxExclusive)`, `range(min, maxInclusive)`, `pick(items)`, `weighted(table)` with `{ weight: number }` entries, `chance(numerator, denominator)`.
+
+## Rules of determinism
+
+- Never call `Date.now()`, `performance.now()` or `new Date()` in a node or in rule functions. Use `now` from the node context.
+- Never call `Math.random()`. Use `rng.stream("some-id")`. Use one id per source, for example `"chest:42"`. Stream state is part of the save, so a draw commits and rolls back with its transaction.
+- Never call `setTimeout` or `setInterval` in game logic. Store the due moment in `player`, then `await fx(schedule(moment))` and wait for `elapsed` at a rest node with `inbox: ["elapsed"]`.
+- State is plain JSON only. No classes, no `Map`, no `Date`, no `undefined` values in trees.
+- Change state only through `player` and `session` of the node context. Do not keep game state in module scope or closures.
+- Keep rules as pure functions `(state, input, tables) => result`. The node calls the rule and writes the result into the draft.
+- A node never calls `app.model`, `app.clock` or `app.time`. Everything outside logic goes through `fx`.
+- A timer is a moment stored in player state. How long is left is computed from `now`.
+
+## Minimal game
+
+```ts
+// state.ts
+import { defineGame } from "@moku-labs/game";
+
+export type Player = { coins: number; lastRoll: number };
+export type Session = { rolls: number };
+
+export const { defineNode, defineFlow, defineFeature } = defineGame<{
+  player: Player;
+  session: Session;
+  assets: string;
+  strings: Record<string, unknown>;
+}>();
+```
+
+```ts
+// nodes.ts
+import { type } from "@moku-labs/game";
+import { defineNode } from "./state";
+
+export const home = defineNode({
+  outcomes: { roll: type() },
+  rest: true,
+  checkpoint: true
+});
+
+export const roll = defineNode({
+  outcomes: { done: type() },
+  run: ({ player, session, rng, out }) => {
+    const face = rng.stream("dice").range(1, 6);
+
+    player.coins += face;
+    player.lastRoll = face;
+    session.rolls += 1;
+    return out.done();
+  }
+});
+```
+
+```ts
+// flow.ts
+import { defineFlow } from "./state";
+import { home, roll } from "./nodes";
+
+export const mainFlow = defineFlow("main", {
+  nodes: { home, roll },
+  start: "home",
+  edges: {
+    home: { roll: "roll" },
+    roll: { done: "home" }
+  }
+});
+```
+
+```ts
+// game.ts
+import { createApp } from "@moku-labs/game";
+import { mainFlow } from "./flow";
+
+export const createGame = (seed: "from-save" | number = "from-save") =>
+  createApp({
+    pluginConfigs: {
+      model: { initialPlayer: { coins: 0, lastRoll: 0 }, initialSession: { rolls: 0 }, seed },
+      flow: { mainFlow, safeNode: "home" }
+    },
+    onStart: ctx => {
+      ctx.flow.run().catch((error: unknown) => {
+        ctx.log.error("game: the graph failed", { error });
+      });
+    }
+  });
+```
+
+The game calls `flow.run()` itself, once, from `onStart`. Do not await it there: it resolves only when the app stops. The screen sends answers with `app.flow.gate.answer({ intent: "roll" })`.
+
+## More patterns
+
+```ts
+import { exit, hint, schedule, slot, to, type } from "@moku-labs/game";
+import { defineFeature, defineFlow, defineNode } from "./state";
+
+// Awaited effect with answers. The gate opens for these intents. The promise resolves with the answer.
+export const confirmReset = defineNode({
+  outcomes: { yes: type(), no: type() },
+  over: true,
+  run: async ({ fx, out }) => {
+    const answer = (await fx({ kind: "popup", payload: { name: "reset" }, answers: ["yes", "no"] })) as {
+      intent: string;
+    };
+
+    return answer.intent === "yes" ? out.yes() : out.no();
+  }
+});
+
+// Timer: arm the clock, emit a cosmetic hint, then wait for `elapsed` at a rest node.
+export const arm = defineNode({
+  outcomes: { armed: type() },
+  run: async ({ now, fx, out }) => {
+    await fx(schedule(now + 60_000));
+    fx.emit(hint("sparkle", { target: "dice" }));
+    return out.armed();
+  }
+});
+
+export const waiting = defineNode({
+  outcomes: { elapsed: type<{ now: number }>(), skip: type() },
+  rest: true,
+  inbox: ["elapsed"]
+});
+
+// Sub-flow with a mapped edge and two exits.
+const pick = defineNode({ outcomes: { picked: type<{ face: number }>(), back: type() }, rest: true });
+const apply = defineNode({
+  input: type<{ value: number }>(),
+  outcomes: { done: type() },
+  run: ({ input, player, out }) => {
+    player.coins += input.value;
+    return out.done();
+  }
+});
+
+export const bonusFlow = defineFlow("bonus", {
+  nodes: { pick, apply },
+  start: "pick",
+  outcomes: { finished: type(), left: type() },
+  edges: {
+    pick: { picked: to("apply", (payload: { face: number }) => ({ value: payload.face * 2 })), back: exit("left") },
+    apply: { done: exit("finished") }
+  }
+});
+
+// Main flow with the sub-flow as a node and a slot.
+const lobby = defineNode({ outcomes: { bonus: type() }, rest: true, checkpoint: true });
+
+export const main = defineFlow("main", {
+  nodes: { lobby, bonus: bonusFlow, afterBonus: slot("afterBonus") },
+  start: "lobby",
+  edges: {
+    lobby: { bonus: "bonus" },
+    bonus: { finished: "afterBonus", left: "lobby" },
+    afterBonus: { done: "lobby" }
+  }
+});
+
+// Feature: contributes a sub-flow to the slot. A feature name must differ from every flow id.
+const thanks = defineNode({ outcomes: { ok: type() }, rest: true, over: true });
+const thanksFlow = defineFlow("thanksPopup", {
+  nodes: { thanks },
+  start: "thanks",
+  outcomes: { done: type() },
+  edges: { thanks: { ok: exit("done") } }
+});
+
+export const thanksFeature = defineFeature("thanks", {
+  flows: [thanksFlow],
+  contribute: { afterBonus: { flow: thanksFlow, order: 10 } }
+});
+```
+
+A tutorial step is `await fx(guide({ allow: { intent: "roll" }, hand: "tap", text: "Tap the dice" }))`. Only that answer passes the gate until the node exits.
+
+## Graph rules checked at `run()`
+
+- Every outcome of every node has an edge. Every edge names a node of the same flow or a declared flow outcome.
+- The start node is in `nodes`. Every node is reachable from the start node.
+- A cycle needs at least one rest node.
+- Every `inbox` type is an outcome of its node. A rest node has outcomes or a `run` body.
+- Every edge of a `barrier` node leads to a rest node of the same flow.
+- Flow ids are unique. A feature name is not a flow id. It is also not a plugin name: `time`, `lifecycle`, `model`, `clock`, `flow`, `world`, `renderer`, `input`, `assets`, `scenes`, `anim`, `i18n`, `text`, `ui`, `effects`, `audio`, `platform`, `log`, `env`.
+- Two contributions of one slot need different `order` values.
+- `safeNode` is the path of a checkpoint node.
+- A flow above 15 nodes is a warning. Split it into sub-flows of 7 to 15 nodes.
+
+## Plugins
+
+Registered in this order: `time`, `lifecycle`, `model`, `clock`, `flow`; then the list `screen` a game spreads in: `world`, `renderer`, `input`, `assets`, `scenes`, `anim`, `i18n`, `text`, `ui`; then the opt-in `effects`, `audio` and `platform` when the game adds them, `platform` last. `log` and `env` from `@moku-labs/common` are on every context as `ctx.log` and `ctx.env`. Configure with `createApp({ pluginConfigs: { <name>: { ... } } })`. Global config: `createApp({ config: { orientation, referenceSide } })`, defaults `"portrait"` and `1080`.
+
+### time (Standard, no dependencies, no events)
+
+The single `requestAnimationFrame` loop. Six phases in this order: `input`, `animate`, `layout`, `sync`, `signals`, `render`.
+- API: `onFrame(phase, callback): () => void`, `snapshot(): Readonly<Time>`, `setScale(scale)`, `pause()`, `resume()`, `isPaused()`, `isRunning()`, `step(deltaMs)`, `wake()`.
+- `Time` is `{ delta, elapsed, scale, frame, idle }` in scaled milliseconds.
+- Idle cap: after `idleAfterMs` unscaled milliseconds without a `wake()` the loop runs at `idleFps` and `snapshot().idle` is true. `wake()` lifts it at once; `input`, `anim`, `flow`, `assets`, `scenes`, `text` and `ui` call it. `step(deltaMs)` is never capped.
+- Config: `maxFps: 30 | 60 | 120` default `60`, `maxDeltaMs: number` default `50`, `idleFps: 0 | 30` default `30` (`0` turns the idle cap off), `idleAfterMs: number` default `2000`.
+- In plain Bun there is no frame source. `isRunning()` is false and tests drive frames with `step`.
+
+### lifecycle (Standard, depends on time)
+
+The stack of pause reasons. The game is paused while the stack is not empty.
+- API: `push(reason)`, `pop(reason)`, `reasons(): readonly PauseReason[]`, `isPaused()`.
+- Named reasons: `"background"`, `"devtools"`, `"system-dialog"`, `"device-lost"`. Any other string is allowed.
+- Event `lifecycle:changed`: `{ reason, action: "push" | "pop", reasons, paused, resumed }`. `resumed` is true only on the change that emptied the stack.
+- No config.
+
+### model (Very Complex, no dependencies)
+
+The `session` tree and the save document `{ player, rng }`. Modules `store` and `rng`.
+- `store`: `load()`, `snapshot(): { player, session, rng }` frozen, `begin(): Transaction`, `markRest()`, `markBarrier(txId)`, `rollback()`, `restore({ player, session?, rng? })`, `flush()`.
+- `rng`: `peek(id): number | undefined`.
+- `load()` hands the whole document to `provider.commit()` at once when it rewrote the save: a new player and a migrated save are stored before the first node runs. A save at the current version produces no commit.
+- A game reads `app.model.store.snapshot()`. The runner calls the rest. A node never calls the model.
+- Event `model:committed`: `{ roots: readonly ("player" | "session" | "rng")[]; cause: "edge" | "rollback" | "restore" | "load" }`.
+- Config: `playerProvider: PlayerStateProvider | undefined` default `undefined` which means in-memory, `initialPlayer: Json` default `{}`, `initialSession: Json` default `{}`, `seed: "from-save" | number` default `"from-save"`, `schemaVersion: number` default `1`, `migrations: readonly Migration[]` default `[]`.
+- `PlayerStateProvider`: `load(): Promise<{ state: Json; version: number } | null>`, `commit(patches, version): void`, `commitDurable(patches, txId, version): Promise<void>`, `flush(): Promise<void>`.
+- `Migration` is `{ from: number; up(state: Json): Json }`. `up` of `from: n` produces version `n + 1`. It works on the whole save document.
+- `SaveUnreadableError` has `savedVersion` and `schemaVersion`. `flow.run()` rejects with it when the save is newer, a step is missing, a step throws or the shape is wrong.
+
+### clock (Standard, no dependencies, no events)
+
+Trusted time as an input. Monotonic `now()` and one `elapsed` signal at the next due moment.
+- API: `now()`, `scheduleAt(moment | undefined)`, `onElapsed(listener): () => void`, `poke()`, `dueAt()`.
+- Config: `source: ClockSource | undefined` default `undefined` which means the system clock. `ClockSource` is `{ now(), setTimer(callback, delayMs), clearTimer(handle) }`.
+- A node never touches the clock. It awaits `fx(schedule(moment))`. `flow` posts `{ type: "elapsed", payload: { now } }` into its inbox when the moment arrives and when the game resumes.
+
+### flow (Very Complex, depends on time, lifecycle, model, clock)
+
+The graph. Modules `runner`, `gate`, `inbox`, `fx`, `features`. Runner methods sit on the plugin root.
+- Runner: `run(): Promise<void>`, `onEnter(stage: "load" | "scene", callback): () => void`, `walk(route, options?: { from?: Bookmark }): Promise<FlowState>`, `bookmark(): Bookmark`, `restore(bookmark): Promise<void>`, `describe(): FlowGraph`, `state(): FlowState`, `history(): readonly JournalEntry[]`, `setMode("live" | "fast")`.
+- `gate.answer({ intent, payload? }): boolean` is the one entry of player answers. `gate.pointer(active)`. `gate.state(): { open, allowed, narrowed }`.
+- `inbox.post({ type, payload? })` queues a world event. One entry per type. It is delivered only to a rest node whose `inbox` lists the type.
+- `fx.handle(kind, handler, options?: { runInFast?: boolean }): () => void` registers the single handler of one effect kind. `fx.dispatch(descriptor)` is fire-and-forget. An awaited effect without a handler resolves `undefined` at once.
+- `features.register(name, description)`, `features.all()`, `features.contributions(slotName)`.
+- `FlowState` is `{ running, path, stack, pending: { fx?, gate? }, mode }`.
+- `Bookmark` is `{ path, input, player, session, rng, graph }`. Serialisable. `restore` needs a running graph and the path of a rest node. A checkpoint is always accepted. Any other rest node is accepted only when the graph did not change since the bookmark.
+- Events: `flow:edge` `{ flow, node, outcome, payload, next, patches: { doc, session }, index, now }` after the commit of an edge. `flow:rest` `{ path, checkpoint }`. `flow:error` `{ path, error, rolledBackTo, retry }`.
+- Config: `mainFlow` default `undefined` and required before `run()`, `safeNode: string | undefined` default `undefined` which means the main flow's `start`, `retries` default `1`, `settleTimeoutMs` default `2000`, `journalLimit` default `500`.
+
+### Screen plugins (V2, built)
+
+`world`, `renderer`, `input`, `assets`, `scenes`. Each has a README at `src/plugins/<name>/README.md`; the root README lists their APIs, events and config. Rendering: WebGPU preferred, with Pixi's WebGL fallback.
+
+### Interface plugins (V3, built)
+
+A screen is a projection whose `view` returns JSX. The game's `tsconfig.json` sets `"jsx": "react-jsx"` and `"jsxImportSource": "@moku-labs/game"`; screens are `.tsx` files. There is no DOM and no React.
+
+- Tags: `screen`, `layer`, `row`, `column`, `stack`, `spacer`, `panel` (swallows taps), `image` (`texture`, `fit?: "contain" | "cover" | "fill"`), `icon` (`name`, `fit?`), `text` (`content: string | Message`, or `bind: { component, field }`; `style` is a text style key), `button` (`intent` + `payload`, or `local`, never both), `scroll` (`axis: "y"` only in V3), `input` (a text field; its text lives in the component's `local`, see the ui README). Common props: `key`, `style`, `state: { active?, disabled?, selected? }`, `motion`, `components` (extra component values for the element's entity, such as a filter: `components={[Glow({ strength: 2 })]}`); containers take `hosts?: string[]` (projections drawn inside the element). Style adds `nineSlice`, `tint`, `offsetX`, `offsetY`, `scale`, `origin`, `fit: "contain"`; state variants `is: { hover, pressed, disabled, active, selected, covered }`. `popup(Component, props, { over })` stacks a popup over a kept one.
+- Style vocabulary (`defineStyle`, plain data): flow `direction`, `wrap`, `justify`, `align`, `alignSelf`, `gap`, `grow`, `shrink`; box `padding`, `margin`, `width`, `height`, `minWidth`, `minHeight`, `maxWidth`, `maxHeight`, `aspect`, `overflow`; position `position`, `left`, `top`, `right`, `bottom`, `reason`; visual `fill`, `stroke`, `strokeWidth`, `radius`, `alpha`; variants `is: { pressed?, disabled?, active?, selected? }` and `when: { portrait?, landscape?, tall?, wide? }`, each a partial style merged in when the flag holds. Lengths are reference units or `"safeArea.top" | "safeArea.right" | "safeArea.bottom" | "safeArea.left"`. No font size here: it comes from the text style.
+- `defineComponent(name, { local?, outcomes?, view(props, local) })`. A component with `outcomes` is a popup: `await fx(popup(Component, props))` opens the gate for its outcomes and resolves with `{ intent, payload }` of the pressed button. A button with `local` writes into the nearest component instance; it never reaches the graph.
+- `tr(key, params?)` returns a frozen `Message` `{ key, params }`; no locale is read at the call site. Strings live in `features/<feature>/strings/<locale>.json` as ICU MessageFormat 1 (`{n, plural, one {# order} other {# orders}}`, `select`, `selectordinal`, `number`, `date`, `time`; no skeletons, no `currency`). `bun run assets:keys` compiles them. `app.i18n`: `locale()`, `setLocale(locale)` (async, emits `i18n:locale-changed`), `format(message, locale?)` returns `Part[]`, `plain(message)` returns a string, `has(key)`, `locales()`. Config: `locale: "en"`, `fallback: "en"`, `locales: {}`.
+- Text: `Text` component, `label({ text, style, at, anchor? })` for board text in a projection view, `defineTextStyles({ "hud.digits": { font, size, fill, bold?, italic?, stroke?, strokeWidth?, letterSpacing?, align?, wrap?, digits? } })` under the feature's `textStyles` key. Tags inside a string: `<b>`, `<i>`, `<color=#rrggbb>`, `<icon=key>`, `\<`, `\n`. Built-in styles `body` and `digits` from config `fonts: { body: "ui.font-body", digits: "ui.font-digits" }`. `app.text.measure(content, style)` gives the same numbers in a browser and in Bun.
+- Animation is data: `defineAnimation(id, { slots: { name: type<Anim.Target>() }, build: (slots, { at }) => Step })`. Steps: `sequence(...)`, `parallel(...)`, `stagger(items, ms, item => Step)`, `tween(target, Component, to, { ms, ease?, delayMs?, additive? })`, `set(target, Component, patch)`, `wait(ms)`, `mark(name)`, `frames(target, { keys, fps, loop? })`, `sfx(key, { bus? })`, `haptic(kind)`, `use(animation, slots, tools?)`, `spawn` (a temporary entity, flying coins, that the timeline despawns when it ends; see the anim README). `Frames({ keys, fps, loop, playing })` is a component that walks a sprite through its textures for the entity's whole life. A target is `{ projection, key }` or an entity. A node plays it with `await fx(play(animation, slots))`; in fast mode it finishes at once. `defineMotion({ states, transition?, on: { enter?, exit?, change? } })` builds the enter, exit and change hooks for a projection or the `motion` prop of a tag. Events `anim:mark` `{ animation, mark }` and `anim:finished` `{ animation }`. Config `maxTracks: 2000`.
+- Audio is opt-in: `plugins: [...screen, audioPlugin]`. `fx(sfx("orders.complete"))` resolves when the sound started. `await fx(music("board.theme"))` cross-fades; `music(null)` fades out; a scene's `music` key switches the track on `scenes:changed`. Buses `master`, `music`, `sfx`. Volumes come from the committed player: config `volumes: player => (player as Player).settings.audio`, applied on every `model:committed`. `app.audio`: `setVolume(bus, value)`, `volume(bus)`, `mute(bus, on)`, `unlocked()`, `journal()` (the last started sounds, empty unless config `journal` is above 0). Config: `buses: { master: 1, music: 0.6, sfx: 1 }`, `musicFadeMs: 600`, `volumes`, `context`, `journal: 0`. Without `audio` every `sfx` and `music` effect resolves `undefined` at once, so the same node runs in a game with no sound.
+- `app.ui`: `tree()` the live screen as plain data, `find(key)` the entity of a keyed element, `fill(key, value)` types into the text field with that `key`, `lint()` tap targets under `tapTargetPt` (default `44`), text that overflows in some locale, absolute elements without `reason`. Config: `tapTargetPt: 44`, `breakpoints: { tall: 2, wide: 1.5 }`. `ui` emits nothing.
+
+```tsx
+// features/hud/view.tsx
+import type { Anim } from "@moku-labs/game";
+import { Transform, mark, sequence, sfx, tween, type } from "@moku-labs/game";
+import { defineAnimation, defineComponent, defineFeature, defineTextStyles, projection, tr } from "../../state";
+
+export const hud = projection({
+  name: "hud",
+  layer: "ui",
+  from: player => ({ coins: player.coins }),
+  view: hud => (
+    <row key="bar" style={{ gap: 16, padding: { top: "safeArea.top", left: 24, right: 24 }, width: "100%", height: 120 }}>
+      <text key="coins" style="hud.digits" content={tr("hud.coins", { n: hud.coins })} />
+      <button key="settings" intent="openSettings" style={{ width: 96, height: 96 }}><icon name="hud.gear" /></button>
+    </row>
+  )
+});
+
+export const RewardPopup = defineComponent("RewardPopup", {
+  outcomes: { claim: type<{ orderId: string }>() },
+  view: (props: { orderId: string; gold: number }) => (
+    <panel key="reward" style={{ nineSlice: "ui.panel", direction: "column", gap: 16, padding: 32, width: 600, height: 400, fit: "contain" }}>
+      <text key="gold" style="hud.digits" content={String(props.gold)} />
+      <button key="claim" intent="claim" payload={{ orderId: props.orderId }} style={{ width: 240, height: 88 }}>
+        <text content={tr("common.claim")} />
+      </button>
+    </panel>
+  )
+});
+
+export const popCoins = defineAnimation("hud.popCoins", {
+  slots: { coins: type<Anim.Target>() },
+  build: ({ coins }) => sequence(tween(coins, Transform, { scale: 1.2 }, { ms: 120 }), tween(coins, Transform, { scale: 1 }, { ms: 200 }), sfx("hud.coins"), mark("done"))
+});
+
+export const hudFeature = defineFeature("hud", {
+  projections: [hud],
+  ui: [RewardPopup],
+  animations: [popCoins],
+  textStyles: defineTextStyles({ "hud.digits": { font: "ui.font-digits", size: 40, fill: 0xffe082, digits: true } }),
+  strings: { en: () => import("../../generated/strings.en") }
+});
+
+// features/orders/deliver.ts — the popup and the choreography are effects the node awaits
+import { play, type } from "@moku-labs/game";
+import { defineNode, popup } from "../../state";
+import { popCoins, RewardPopup } from "../hud/view";
+
+export const deliver = defineNode({
+  outcomes: { claimed: type<{ orderId: string }>() },
+  run: async ({ player, fx, out }) => {
+    const answer = (await fx(popup(RewardPopup, { orderId: "o1", gold: 5 }))) as { intent: "claim"; payload: { orderId: string } };
+
+    player.coins += 5;
+    await fx(play(popCoins, { coins: { projection: "hud", key: "coins" } }));
+    return out.claimed({ orderId: answer.payload.orderId });
+  }
+});
+```
+
+### effects (V5, Complex, opt-in)
+
+Cosmetic rendering extras as data, drawn by `effectsPlugin`: `plugins: [...screen, effectsPlugin]`. Nothing here enters `model`, the journal or a save. Headless it draws nothing. The full reference is `src/plugins/effects/README.md`.
+- Particles: `defineEmitter(id, config)` returns frozen data a feature lists under `emitters`. Required: `textures` (1 to 16 asset keys of one atlas page) and exactly one of `burst` (an integer, emitted once) and `rate` (particles per second while `active`). Optional with defaults: `lifeMs`, `speed`, `angle`, `gravity`, `drag`, `spin`, `shape` (`point`, `circle`, `rect`, `ring`), `scale`, `alpha`, `tint` (each `{ from, to }`), `space` (`"world"` or `"local"`), `prewarmMs`, `maxParticles` (`256`), `blend` (`"normal"` or `"add"`). A mistake throws at definition.
+- The `Emitter({ effect, active })` component on an entity runs an emitter: `generator: item => [Sprite({ texture: "board.generator" }), Emitter({ effect: "fx.steam" })]`. `effect: ""` draws nothing. Particles step in the `animate` phase, so they freeze while paused and a fast walk emits nothing. Their random source is seeded, never `Math.random` and never the model's rng.
+- Filters: `defineFilter(id, { wgsl, glsl, uniforms?, passes?, padding? })` returns a component type a feature lists under `filters`. Both bodies are required: `wgsl` is the WGSL `fn mainFragment` and reads a uniform as `fu.amount`; `glsl` is GLSL ES 3.0 `void main()` that sets `finalColor` and reads a uniform as `amount`. A uniform is a number (tweenable), `{ color: 0xffd700 }` or an array of 2 to 4 numbers. Every filter component also has `enabled: true` and `order: 0`. A filter covers the entity's subtree; on a ui element it goes in the `components` prop.
+- Built-in filters: `Glow`, `Outline`, `Blur`, `ColorMatrix`, `Noise`, `Displacement` (`map` is an asset key), `Alpha`. A motion hook tweens them like any component: `view.tween(Glow, { strength: 0 }, { ms: 200 })`.
+- API: `app.effects.stats()` returns `{ particles, emitters, filters, renderPasses }`; headless every number is 0.
+- Config: `maxParticles: 3000` and `maxPasses: 24`, each warns once per crossing; `phone: "auto"`; `blur: { quality: 2, phoneResolution: 0.5 }`.
+- With `emitters: "fx.starsBurst" | "fx.steam"` in the `defineGame` types, the `defineEmitter` id and `Emitter.effect` are checked by the compiler; `textures` and `Displacement.map` are checked against the asset keys. No events. Depends on `flow`, `world`, `renderer`, `assets`, `anim`.
+
+### platform (V6, Standard, opt-in)
+
+The phone as a provider, last in the array: `plugins: [...screen, effectsPlugin, audioPlugin, platformPlugin]` with `pluginConfigs: { platform: { provider, keepAwake: true } }`. The engine never imports a native package: the game builds the provider in its own layer, usually from `@moku-labs/system`. The full reference is `src/plugins/platform/README.md`.
+- `PlatformProvider` has six members: `onPause(fn)`, `onResume(fn)`, `onBack(fn)` (each returns its remover), `haptic(kind)`, `keepAwake(on)`, `exit()`. Pause and resume push and pop the `"background"` reason of `lifecycle`. A provider method that throws is logged, never thrown into the frame.
+- Back chain, `app.platform.back(): BackResult`. First an Escape press: a popup with an `escape` button closes, `"popup"`. Then `flow.gate.answer({ intent: "back" })` when the resting node lists `back`, `"intent"`. Then `provider.exit()`, `"exit"`. Without a provider `"none"`.
+- Haptics: `await fx(haptic("success"))` in a node, or `haptic("light")` as a timeline step. The kinds are `HAPTIC_KINDS`: `light`, `medium`, `heavy`, `selection`, `success`, `warning`, `error`. A fast walk is silent.
+- Config: `provider: undefined`, which leaves the plugin inert: a `haptic` effect resolves at once, so the same node runs on the web and headless. `keepAwake: false`.
+- No events. Depends on `lifecycle`, `flow`, `input`.
+
+## Game plugins and events
+
+A game plugin is `createPlugin(name, { depends: [flowPlugin], hooks: ctx => ({ "flow:edge": payload => { ... } }) })`. The root README has the full example in its Events section.
+
+A plugin that owns a resource stores it in its state and frees it in `onStop: ({ state }) => …` (core 1.6: `onStop` receives `{ global, config, state }`). A throwing `onStop` makes `app.stop()` reject. A hook that throws never stops the game: the engine writes the error entry `"game: a hook failed"` to the log (`app.log.trace()`), through the framework `onError(error, core)` of core 1.7. A game can pass its own `onError: (error, ctx) => …` to `createApp`; the kernel calls both.
+
+## Doors for the editor
+
+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`.
+- 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.
+
+## Fonts
+
+The package ships one MSDF body font: `fonts/font-body.fnt` and `fonts/font-body.png` (Pangolin Regular) with `fonts/LICENSE.txt` (SIL Open Font License 1.1). Copy it into the game; a path in `node_modules` is not an asset key, the scanner reads keys only from `features/<feature>/assets/`. The licence goes next to `assets/`, not inside it.
+
+```bash
+mkdir -p src/features/ui/assets
+cp node_modules/@moku-labs/game/fonts/font-body.* src/features/ui/assets/
+cp node_modules/@moku-labs/game/fonts/LICENSE.txt src/features/ui/LICENSE-fonts.txt
+bun run assets:keys
+```
+
+The scanner keys it `ui.font-body`, which is the `text` config default `fonts.body`, so the built-in style `body` works with no config. No `digits` font ships: a game that uses the style `digits` brings `ui.font-digits` itself.
+
+## Testing entry
+
+Exports of `@moku-labs/game/testing`: `createHeadless`, `runRepro`, `stepFrames`, `fakeClock`, `memory`, `saveOf`, and the visual tests `defineVisualTest`, `runVisualTests`, `parseVisualArgv` (see `docs/testing.md` in the engine repository).
+
+- `createHeadless(app): Promise<HeadlessGame>`. Pass an app that is not started. It sets mode `"fast"`, awaits `app.start()`, starts `flow.run()` unless the app's `onStart` already did, and resolves when the loop rests for the first time: `game.state().path` already names the first rest node. A fatal error of `run()` rejects the call.
+- `HeadlessGame`: `walk(route): Promise<FlowState>`, `answer(answer): boolean`, `state()`, `history()`, `stop()`. `walk` and `stop` throw a fatal error of the loop again when the headless runner owns `run()`.
+- `Flow.RouteStep` is `{ at: string; intent: string; payload?: Json }` or `{ at: string; result: { outcome: string; payload?: Json } }`. `at` is the path of a rest node. The `result` form substitutes the result of a sub-flow at that path.
+- `runRepro(app, { player, session?, rng?, checkpoint?, route }): Promise<{ path: string[]; player; session }>`. The app keeps running. Stop it with `app.stop()`.
+- `stepFrames(app, count, deltaMs)` calls `app.time.step(deltaMs)` `count` times.
+- `fakeClock(start = 0)`: a `ClockSource` with `advance(ms)` and `set(moment)`. `advance` fires due timers synchronously.
+- `memory(fixture?)`: in-memory `PlayerStateProvider` with `calls`, the list of every call. It applies the patches it is committed to the document it holds, so a second app over the same instance reads what the first one wrote. `saveOf(player, seed = 1)` builds a `SaveDoc`.
+
+```ts
+import type { Flow } from "@moku-labs/game";
+import { createHeadless } from "@moku-labs/game/testing";
+import { expect, it } from "vitest";
+import { createGame } from "./game";
+
+const rollOnce: Flow.RouteStep = { at: "home", intent: "roll" };
+
+it("plays two rolls without a screen", async () => {
+  const app = createGame(42);
+  const game = await createHeadless(app);
+
+  const state = await game.walk([rollOnce, rollOnce]);
+
+  expect(state.path).toBe("home");
+  expect(app.model.store.snapshot().session).toEqual({ rolls: 2 });
+
+  await game.stop();
+});
+```
+
+For timers, pass `clock: { source: fakeClock(1_000_000) }` in `pluginConfigs`, call `clock.advance(ms)`, then yield the microtask queue before reading the state. For a fixed game, pass `model: { seed: 42 }`. In tests, compose features as `plugins: [feature.logicOnly]`.
+
+## File layout of a game
+
+```
+src/
+  state.ts        Player and Session types, starting state, the defineGame call
+  tables.ts       balance data as plain objects
+  rules/          pure functions, no engine import, no clock, no random
+  nodes/          one file per node: boot.ts, home.ts, await-intent.ts
+  flows/          main.ts, one file per sub-flow, one file per feature
+  game.ts         the single createApp call
+tests/            headless scenarios with createHeadless and walk
+```
+
+This is the layout of the worked example in the engine repository: `tests/integration/merge-game/` with `kit.ts`, `state.ts`, `tables.ts`, `rules/`, `nodes/`, `flows/`, `game.ts`. It is an internal test fixture written on the public API only. It is not in the npm package. Its scenario is `tests/integration/template-merge.test.ts`. A game with a screen adds `features/<name>/view.tsx` (projections and components), `features/<name>/animations.ts`, `features/<name>/strings/<locale>.json` and the `generated/` folder `bun run assets:keys` writes. Each plugin has a README: `src/plugins/<name>/README.md` for `time`, `lifecycle`, `model`, `clock`, `flow`, `world`, `renderer`, `input`, `assets`, `scenes`, `anim`, `i18n`, `text`, `ui`, `audio`, `effects`, `platform`. Moku Core specification: https://github.com/moku-labs/core/tree/main/specification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/game",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "2D puzzle game engine on TypeScript and PixiJS, built on @moku-labs/core.",
   "type": "module",
   "sideEffects": false,
@@ -34,11 +34,18 @@
     "./jsx-dev-runtime": {
       "types": "./dist/jsx-dev-runtime.d.mts",
       "default": "./dist/jsx-dev-runtime.mjs"
-    }
+    },
+    "./fonts/*": "./fonts/*"
+  },
+  "bin": {
+    "moku-game-assets": "./bin/moku-game-assets.mjs"
   },
   "license": "MIT",
   "files": [
     "dist",
+    "bin",
+    "fonts",
+    "llms.txt",
     "LICENSE",
     "README.md"
   ],