@moku-labs/game 0.0.1 → 0.0.2

package/README.md

@@ -2,7 +2,7 @@
 
 **A 2D puzzle game engine where the game is a deterministic graph of business logic.**
 
-`@moku-labs/game` is a Layer-2 framework on [`@moku-labs/core`](https://github.com/moku-labs/core), written in TypeScript, with PixiJS v8 as a peer dependency. You write small nodes and edge tables. The engine runs them, commits state on the edges, saves at rest points and replays the same game without a screen. It is not a general-purpose engine and it ships no genre rules: no match-3, no merge, no physics. Today it is the logic half only. The screen arrives in V2.
+`@moku-labs/game` is a Layer-2 framework on [`@moku-labs/core`](https://github.com/moku-labs/core), written in TypeScript, with PixiJS v8 as a peer dependency. You write small nodes and edge tables. The engine runs them, commits state on the edges, saves at rest points and replays the same game without a screen. It is not a general-purpose engine and it ships no genre rules: no match-3, no merge, no physics. V1 is the logic half; V2 adds the screen: an own small ECS, projections from committed state, a Pixi v8 renderer loaded lazily, gestures as data components, typed asset keys and scenes as declarations. V3 adds the interface: choreographies as data, strings as data, text from MSDF fonts, screens written in JSX and laid out by Yoga, and sound as an effect a node awaits. V4 adds two doors for the editor: sources that read a running game and dev-only commands that drive it.
 
 <br/>
 
@@ -15,7 +15,7 @@
 
 <br/>
 
-[Why](#why-moku-labsgame) · [Status](#status) · [Install](#install) · [Quick start](#quick-start) · [How it works](#how-it-works) · [Plugins](#plugins) · [Events](#events) · [Configuration](#configuration) · [Development](#development) · [Requirements](#requirements) · [Docs](#docs)
+[Why](#why-moku-labsgame) · [Status](#status) · [Install](#install) · [Quick start](#quick-start) · [How it works](#how-it-works) · [Plugins](#plugins) · [Interface in JSX](#interface-in-jsx) · [Doors for the editor](#doors-for-the-editor) · [Events](#events) · [Configuration](#configuration) · [Development](#development) · [Requirements](#requirements) · [Docs](#docs)
 
 ---
 
@@ -25,23 +25,23 @@
 - **State commits only on edges.** A node works on drafts. The runner commits them when the node returns an outcome. A node that throws changes nothing.
 - **Position is data.** Node path, input and state describe the whole game. That gives checkpoints, rollback, bookmarks, fast walk and repro runs.
 - **Input and world events are answers.** A rest node waits. A player answer comes through the gate, a world event comes through the inbox. Nothing else moves the graph.
-- **The screen is a projection, not the game.** Rendering reads committed state and never owns it. The projection arrives in V2. V1 plays whole games headless.
+- **The screen is a projection, not the game.** Rendering reads committed state and never owns it. A projection is one pure `view(item)` function; the engine diffs the components and plays enter, exit, change and settle motions. The same game plays whole headless.
 - **Deterministic by construction.** Time is an input named `now`. Randomness is a persisted `rng` stream. Lint rule L3 refuses `Date.now` and `Math.random` in the logic set.
 
 ## Status
 
-Only V1 exists. Everything else in this table is a plan and may change.
+V1, V2 and V3 are built. V4 has its engine side: the two doors described in [Doors for the editor](#doors-for-the-editor). The editor that uses them is a separate package. Everything after V4 is a plan and may change.
 
 | Milestone | State | Scope | Exit criterion |
 |---|---|---|---|
 | V1 | built | `time`, `lifecycle`, `model`, `clock`, `flow`, the `@moku-labs/game/testing` entry | A fixture game is played to the end headless |
-| V2 | planned | `world`, `renderer`, `input`, `assets`, `scenes` | A board is visible and items move by drag |
-| V3 | planned | `anim`, `i18n`, `audio`, `text`, `ui` | Popup, HUD and buttons with sound |
-| V4 | planned | `/inspect` and `/control` entries | External tools can read and drive a game |
+| V2 | built | `world`, `renderer`, `input`, `assets`, `scenes`, the `@moku-labs/game/assets` entry | A board is visible and items merge by drag; the same game still plays to the end headless |
+| V3 | built | `anim`, `i18n`, `text`, `ui`, `audio`, the `@moku-labs/game/jsx-runtime` entry | Popup, HUD and buttons with sound; the same game still plays to the end headless |
+| V4 | doors built | `/inspect` and `/control` entries | External tools can read and drive a game |
 | V5 | planned | `effects`, production mode of `assets`, visual test helpers | Not defined yet |
 | V6 | planned | `platform` | A template game runs on a phone |
 
-Rendering decision for V2: WebGPU is preferred, with Pixi's WebGL fallback.
+Rendering: WebGPU is preferred, with Pixi's WebGL fallback and an honest "unsupported device" screen when neither exists.
 
 ## Install
 
@@ -53,7 +53,7 @@ bun add @moku-labs/game pixi.js
 > **Status: `0.0.0`, not published yet.** The package is not on npm. The command above is the intended install line. `pixi.js` `^8.0.0` is a peer dependency. No V1 code imports it.
 
 > [!IMPORTANT]
-> Bun only. ESM only. `"sideEffects": false`. There is no CJS build.
+> Bun only. ESM only. `"sideEffects": false`. There is no CJS build. `yoga-layout` is a dependency the `ui` plugin loads lazily; nothing imports it before `onStart`.
 
 ## Quick start
 
@@ -149,6 +149,8 @@ export const createGame = (seed: "from-save" | number = "from-save") =>
   });
 ```
 
+A hook that throws never stops the game. The engine writes it to the log as the error entry `"game: a hook failed"`; read it with `app.log.trace()`. A game can add its own `onError: (error, ctx) => …` to `createApp`; the kernel calls both.
+
 **5. Play it headless.** `createHeadless` returns a game object once the graph rests at its first
 rest node. Its `walk` method plays a route.
 
@@ -181,7 +183,7 @@ it("plays two rolls and a reset without a screen", async () => {
 In a live game the same answer comes from the screen: `app.flow.gate.answer({ intent: "roll" })`.
 
 > [!TIP]
-> Types reach a game through one namespace per plugin: `import type { Flow, Model, Clock, Lifecycle, Time } from "@moku-labs/game"`, then `Flow.RouteStep`, `Model.PlayerStateProvider`, `Time.Phase`.
+> Types reach a game through one namespace per plugin: `import type { Flow, Model, Clock, Lifecycle, Time } from "@moku-labs/game"`, then `Flow.RouteStep`, `Model.PlayerStateProvider`, `Time.Phase`. The screen and interface plugins follow the same rule: `World`, `Renderer`, `Input`, `Assets`, `Scenes`, `Anim`, `I18n`, `TextTypes`, `Ui`, `Audio`. `Text` is the component, so its type namespace is `TextTypes`.
 
 > [!TIP]
 > A larger worked example lives in [`tests/integration/merge-game/`](./tests/integration/merge-game). It is a small game written on the public API only, with sub-flows, a slot, a feature and timers. It is an internal test fixture and is not published. Its scenario is [`tests/integration/template-merge.test.ts`](./tests/integration/template-merge.test.ts).
@@ -196,7 +198,7 @@ flowchart LR
   N --> E["Edge<br/>commit, journal, flow:edge"]
   E --> R
   E --> M["model<br/>committed state and save"]
-  M --> S["Screen<br/>projection, V2"]
+  M --> S["Screen<br/>projection, JSX"]
   classDef u fill:#0b7285,stroke:#08525f,color:#fff;
   classDef m fill:#1864ab,stroke:#0d3d6e,color:#fff;
   class P,W,S u
@@ -223,7 +225,7 @@ flowchart LR
 
 ## Plugins
 
-Seven plugins are on every app today. `log` and `env` come from [`@moku-labs/common`](https://github.com/moku-labs/common) and sit on every plugin context as `ctx.log` and `ctx.env`.
+Five logic plugins are on every app; the nine screen plugins are the list `screen` a game spreads in; `audio` is opt-in, `[...screen, audioPlugin]`. `log` and `env` come from [`@moku-labs/common`](https://github.com/moku-labs/common) and sit on every plugin context as `ctx.log` and `ctx.env`.
 
 ### Built
 
@@ -233,7 +235,17 @@ Seven plugins are on every app today. `log` and `env` come from [`@moku-labs/com
 | [`lifecycle`](./src/plugins/lifecycle/README.md) | Standard | The stack of pause reasons. Pauses `time` by a direct call | `push(reason)`, `pop(reason)`, `reasons()`, `isPaused()` |
 | [`model`](./src/plugins/model/README.md) | Very Complex | The `session` tree and the save document `{ player, rng }`, transactions, rest-point rollback, rng streams | `store.load()`, `store.snapshot()`, `store.begin()`, `store.markRest()`, `store.markBarrier(txId)`, `store.rollback()`, `store.restore(input)`, `store.flush()`, `rng.peek(id)` |
 | [`clock`](./src/plugins/clock/README.md) | Standard | Trusted time as an input: monotonic `now()` and one `elapsed` signal at the next due moment | `now()`, `scheduleAt(moment)`, `onElapsed(listener)`, `poke()`, `dueAt()` |
-| [`flow`](./src/plugins/flow/README.md) | Very Complex | The graph: runner, gate, inbox, effects gateway, features registry | `run()`, `register(flow)`, `onEnter(stage, callback)`, `walk(route, options?)`, `bookmark()`, `restore(bookmark)`, `describe()`, `state()`, `history()`, `setMode(mode)`, `gate.answer(answer)`, `gate.pointer(active)`, `gate.state()`, `inbox.post(event)`, `fx.handle(kind, handler, options?)`, `fx.dispatch(descriptor)`, `features.register(name, description)`, `features.all()`, `features.contributions(slotName)` |
+| [`flow`](./src/plugins/flow/README.md) | Very Complex | The graph: runner, gate, inbox, effects gateway, features registry | `run()`, `onEnter(stage, callback)`, `walk(route, options?)`, `bookmark()`, `restore(bookmark)`, `describe()`, `state()`, `history()`, `setMode(mode)`, `gate.answer(answer)`, `gate.pointer(active)`, `gate.state()`, `inbox.post(event)`, `fx.handle(kind, handler, options?)`, `fx.dispatch(descriptor)`, `features.register(name, description)`, `features.all()`, `features.contributions(slotName)` |
+| [`world`](./src/plugins/world/README.md) | Very Complex | A zero-dependency ECS (`ecs`) and the projection from committed state to entities (`projection`): keyed reconcile of one `view(item)` function, retarget motions, a despawn queue, named layers | `ecs.spawn(owner, components)`, `ecs.query(...Components)`, `ecs.system(def)`, `ecs.set(entity, Component, patch)`, `ecs.changed(Component)`, `ecs.snapshot()`, `ecs.mode()`, `projection.mount(names, owner)`, `projection.setLayers(list)`, `projection.settle(entity)`, `projection.keyOf(entity)`, `projection.entityOf(projection, key)` |
+| [`renderer`](./src/plugins/renderer/README.md) | Very Complex | The Pixi v8 host loaded lazily (`host`), one `sync` system that owns every display object, the reference viewport fitted to `referenceSide` and `referenceLong` (`viewport`) | `host.ready()`, `host.kind()`, `host.canvas()`, `sync.hitTest(x, y, accept)`, `sync.textures.provide(fn)`, `sync.displayOf(entity)`, `viewport.toReference(x, y)`, `viewport.size()` |
+| [`input`](./src/plugins/input/README.md) | Standard | Gestures as data components: `Tappable`, `Pressable`, `Draggable`, `DropTarget`, `Swipeable`; the drop target names the intent that reaches `flow.gate` | `tap(target)`, `press(target)`, `drag(from, to)`, `swipe(target, direction)` |
+| [`assets`](./src/plugins/assets/README.md) | Complex | The manifest, five load tiers, graph-driven preload, a texture budget with LRU unload; typed keys from the `assets` entry | `load(bundle)`, `unload(bundle)`, `isLoaded(bundle)`, `texture(key)`, `usage()` |
+| [`scenes`](./src/plugins/scenes/README.md) | Standard | A scene as a declaration: bundle, layers, projections, `music`. A node names its scene; the runner switches through `flow.onEnter` | `current()` |
+| [`anim`](./src/plugins/anim/README.md) | Complex | The one tween core, installed into `world.projection` as the `TweenDriver`; timelines as frozen data built from typed slots; `defineMotion` sugar for the enter, exit and change hooks | `play(animation, slots)`, `finishAll()`, `active()`, `onMark(fn)` |
+| [`i18n`](./src/plugins/i18n/README.md) | Complex | Strings as data: `tr(key, params)` is a `Message`, ICU MessageFormat compiled to plain functions by `compileStrings` on the `assets` door, `Part[]` at run time, never a joined string | `locale()`, `setLocale(locale)`, `format(message, locale?)`, `plain(message)`, `has(key)`, `locales()` |
+| [`text`](./src/plugins/text/README.md) | Complex | The `Text` component, `label()`, `defineTextStyles()`, the tags `<b> <i> <color=#hex> <icon=key>`, measurement from the font's advance table, BitmapText from the MSDF fonts of a bundle | `measure(content, style)`, `styles()` |
+| [`ui`](./src/plugins/ui/README.md) | Very Complex | A screen is a projection whose `view` returns JSX; the tree is reconciled by identity into entities, laid out by one Yoga solve per change, `Box` is the rest pose; `defineComponent` with `local` and `outcomes`, `popup` as an effect, `defineStyle`, `defineTokens` | `tree()`, `find(key)`, `lint()` |
+| [`audio`](./src/plugins/audio/README.md) | Standard | Opt-in. Buses `master`, `music`, `sfx`; `sfx()` descriptors of `anim` and `music()` descriptors handled here; the scene's `music`; volumes read from the committed player through `volumes` | `setVolume(bus, value)`, `volume(bus)`, `mute(bus, on)`, `unlocked()` |
 
 ```mermaid
 flowchart LR
@@ -243,13 +255,47 @@ flowchart LR
   F --> M["model"]
   F --> C["clock"]
   L --> T
+  W["world"] --> T
+  W --> M
+  W --> F
+  R["renderer"] --> T
+  R --> L
+  R --> W
+  I["input"] --> F
+  I --> W
+  I --> R
+  A["assets"] --> F
+  A --> R
+  S["scenes"] --> F
+  S --> W
+  S --> A
+  AN["anim"] --> F
+  AN --> W
+  AN --> R
+  N["i18n"] --> F
+  X["text"] --> W
+  X --> R
+  X --> A
+  X --> N
+  U["ui"] --> I
+  U --> AN
+  U --> X
+  AU["audio"] --> L
+  AU --> M
+  AU --> F
+  AU --> A
+  AU --> S
   classDef u fill:#0b7285,stroke:#08525f,color:#fff;
   classDef m fill:#1864ab,stroke:#0d3d6e,color:#fff;
+  classDef s fill:#5c940d,stroke:#3d6208,color:#fff;
+  classDef v fill:#862e9c,stroke:#5f1f70,color:#fff;
   class G u
   class F,T,L,M,C m
+  class W,R,I,A,S s
+  class AN,N,X,U,AU v
 ```
 
-An arrow means "depends on". `time`, `model` and `clock` depend on nothing. The plugins are registered in this order: `time`, `lifecycle`, `model`, `clock`, `flow`.
+An arrow means "depends on"; for the V3 plugins the edges to `time` and the edges a nearer plugin already implies are left out for space, the plugin READMEs list them in full. `time`, `model` and `clock` depend on nothing. The logic plugins are registered in this order: `time`, `lifecycle`, `model`, `clock`, `flow`; the screen set `screen` follows as `world`, `renderer`, `input`, `assets`, `scenes`, `anim`, `i18n`, `text`, `ui`; a game that wants sound appends `audioPlugin`. Without a document the screen plugins are inert: the same app starts in plain Bun, Yoga included.
 
 ### Planned
 
@@ -257,16 +303,6 @@ Not built. Names are reserved: `defineFeature` refuses them as feature names. Sc
 
 | Plugin | Milestone | Tier | Depends on | Will own |
 |---|---|---|---|---|
-| `world` | V2 | Very Complex | `time`, `model`, `flow` | ECS world and the projections of the model |
-| `renderer` | V2 | Very Complex | `time`, `lifecycle`, `world` | The Pixi host, sync and viewport. Pixi is loaded lazily |
-| `input` | V2 | Standard | `time`, `flow`, `world`, `renderer` | Pointer listeners on the canvas |
-| `assets` | V2 | Complex | `flow`, `renderer` | Manifest, tiers, preload, budget |
-| `scenes` | V2 | Standard | `flow`, `world`, `assets` | Scenes as data, switched through `flow.onEnter` |
-| `anim` | V3 | Complex | `flow`, `world` | Tweens and motion |
-| `i18n` | V3 | Standard | `flow`, `world`, `assets` | String tables per locale |
-| `text` | V3 | Complex | `world`, `renderer`, `assets`, `i18n` | Text rendering and the text field |
-| `ui` | V3 | Very Complex | `flow`, `world`, `renderer`, `anim`, `i18n`, `text` | JSX components, styles, layout |
-| `audio` | V3 | Standard | `lifecycle`, `flow`, `assets`, `scenes` | Audio context and unlock |
 | `effects` | V5 | Complex | `flow`, `world`, `renderer` | Particles, filters, frames |
 | `platform` | V6 | Standard | `lifecycle`, `flow` | The native provider: background, system dialogs |
 
@@ -276,14 +312,32 @@ Not built. Names are reserved: `defineFeature` refuses them as feature names. Sc
 |---|---|---|
 | `createApp` | function | Creates a game application |
 | `createPlugin` | function | Creates a game plugin bound to the engine's config and events |
-| `defineGame` | function | Returns `{ defineNode, defineFlow, defineFeature }` typed with the game's `player` and `session` |
-| `defineFeature` | function | Turns a feature description into a plugin |
+| `defineGame` | function | Returns the authoring helpers typed with the game's `player`, `session`, `assets`, `bundles`, `strings` and `textStyles`: `defineNode`, `defineFlow`, `defineFeature`, `projection`, `sprite`, `Sprite`, `NineSlice`, `defineBundles`, `load`, `defineScene`, and from V3 `tr`, `label`, `defineTextStyles`, `defineComponent`, `defineStyle`, `defineTokens`, `popup`, `defineAnimation`, `frames`, `sfx`, `play`, `music` |
+| `defineFeature` | function | Turns a feature description into a plugin. V3 keys: `projections`, `animations`, `ui`, `strings`, `textStyles` |
 | `type`, `exit`, `to`, `slot` | functions | Type tag of a payload, and the three graph helpers for edge targets and slots |
 | `schedule`, `guide`, `hint` | functions | Effect descriptors: next due moment, tutorial narrowing of the gate, cosmetic hint |
 | `SaveUnreadableError` | class | Thrown by `model.store.load()` when the save cannot be read |
-| `teardown` | object | `teardown.register(global, key, dispose)` and `teardown.run(global, key)` for plugins that own a resource |
-| `timePlugin`, `lifecyclePlugin`, `modelPlugin`, `clockPlugin`, `flowPlugin` | plugin instances | For `depends` and `ctx.require` in game plugins |
-| `Time`, `Lifecycle`, `Model`, `Clock`, `Flow` | type namespaces | All public types of one plugin |
+| `component`, `tag`, `resource`, `mut`, `system`, `projection`, `Layer`, `Order`, `Exiting`, `Tree` | functions and components | The ECS vocabulary of `world` and the projection helper |
+| `Transform`, `Sprite`, `NineSlice`, `Shape`, `Parent`, `Display`, `sprite` | components | The display components of `renderer` |
+| `Tappable`, `Pressable`, `Draggable`, `DropTarget`, `Swipeable`, `Touchable`, `Held`, `Hovered`, `PointerOver`, `Pressed`, `Pointer` | components | Gestures as data, from `input`; `PointerOver` marks the view under an idle mouse or pen (the `hover` style state) |
+| `defineBundles`, `load`, `defineScene` | functions | Bundle and scene declarations |
+| `defineAnimation`, `sequence`, `parallel`, `stagger`, `tween`, `set`, `wait`, `mark`, `frames`, `sfx`, `haptic`, `use`, `spawn`, `spawned`, `play`, `external`, `defineMotion`, `Animation` | functions and a component | Choreography as frozen data. `play(animation, slots)` is the effect a node awaits; `spawn` makes a temporary entity (flying coins, a toast sign) that the timeline despawns when it ends; `sfx` and `haptic` are descriptors `audio` and `platform` handle; `external` throws until Spine arrives |
+| `tr` | function | `tr(key, params?)` builds a frozen `Message`; no locale is read at the call site |
+| `Text`, `label`, `defineTextStyles` | component and functions | Words on the screen and the text styles a feature registers |
+| `defineComponent`, `popup`, `defineStyle`, `defineTokens`, `resolve`, `Box`, `LocalWrite` | functions and components | Interface components, the popup effect, the style vocabulary, the rect of an element |
+| `music` | function | `music(key \| null, { fadeMs? })`, the awaited effect that switches the music track |
+| `timePlugin`, `lifecyclePlugin`, `modelPlugin`, `clockPlugin`, `flowPlugin`, `worldPlugin`, `rendererPlugin`, `inputPlugin`, `assetsPlugin`, `scenesPlugin`, `animPlugin`, `i18nPlugin`, `textPlugin`, `uiPlugin`, `audioPlugin` | plugin instances | For `depends` and `ctx.require` in game plugins; `screen` is the list of the nine screen plugins |
+| `Time`, `Lifecycle`, `Model`, `Clock`, `Flow`, `World`, `Renderer`, `Input`, `Assets`, `Scenes`, `Anim`, `I18n`, `TextTypes`, `Ui`, `Audio` | type namespaces | All public types of one plugin |
+
+### Other entries
+
+| Entry | Runs in | Exports |
+|---|---|---|
+| `@moku-labs/game/testing` | anywhere | The headless helpers, see below |
+| `@moku-labs/game/assets` | node and bun only | `scanAssets`, `emitKeys`, `emitManifest`, `compileStrings`, `checkStrings`, `runCli`. A game runs it as `bun run assets:keys`: it writes the manifest, the typed asset keys and, next to them, `generated/strings.ts` with one `strings.<locale>.ts` per locale; `--check` fails when any of them is out of date |
+| `@moku-labs/game/inspect` | anywhere, production included | `read`, `watch`, `defineSource`, the catalogue `sources` and the types `Source`, `InputSchema`, `InputOf`. See [Doors for the editor](#doors-for-the-editor) |
+| `@moku-labs/game/control` | dev builds only | `run`, `defineCommand`, `controlRefused`, the catalogue `commands` and the types `Command`, `Ran`. See [Doors for the editor](#doors-for-the-editor) |
+| `@moku-labs/game/jsx-runtime`, `@moku-labs/game/jsx-dev-runtime` | anywhere | `jsx`, `jsxs`, `jsxDEV`, `Fragment` and the `JSX` namespace that `"jsxImportSource": "@moku-labs/game"` resolves to. A game never imports them by hand |
 
 ### Testing entry
 
@@ -300,6 +354,293 @@ Not built. Names are reserved: `defineFeature` refuses them as feature names. Sc
 
 A `HeadlessGame` has `walk(route)`, `answer(answer)`, `state()`, `history()` and `stop()`.
 
+## Interface in JSX
+
+The interface is one more projection. A screen is a projection whose `view` returns JSX; `ui` reconciles the tree by identity into entities it owns and lays them out with one Yoga solve per change. There is no DOM and no React: the runtime builds plain description nodes, and `"jsxImportSource": "@moku-labs/game"` is the only setup.
+
+```jsonc
+// tsconfig.json of the game
+{ "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "@moku-labs/game" } }
+```
+
+The tags are `screen`, `layer`, `row`, `column`, `stack`, `spacer`, `panel`, `image`, `icon`, `text`, `button` and `scroll`. A `button` either names an `intent` for the gate or writes `local` state of its nearest component, never both. A `text` takes a string or a `Message` from `tr`; its size comes from a text style key, not from the layout style.
+
+```tsx
+// features/hud/view.tsx — the HUD, a reward popup and the choreography they share
+import type { Anim } from "@moku-labs/game";
+import { Transform, mark, parallel, 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="title" content={tr("orders.complete")} />
+      <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 }),
+      parallel(tween(coins, Transform, { scale: 1 }, { ms: 200, ease: "outCubic" }), 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") }
+});
+```
+
+A popup is an effect. The node awaits it, the gate opens for the outcomes of the component, and the promise resolves with the intent of the button the player pressed. The choreography is played the same way.
+
+```ts
+// features/orders/deliver.ts
+import { play, sfx, 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 }) => {
+    fx(sfx("orders.complete"));
+    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 });
+  }
+});
+```
+
+Headless the same node runs to the end: `popup` resolves through the gate, `play` finishes at once in fast mode, and `sfx` without `audio` resolves `undefined`. The strings behind `tr` come from `features/*/strings/<locale>.json`; `bun run assets:keys` compiles them next to the asset keys, and `strings: Strings` in `defineGame` makes a wrong key or a missing parameter a compile error.
+
+```ts
+// game.ts — sound is opt-in, the buses follow the committed player
+createApp({
+  plugins: [...screen, audioPlugin, hudFeature],
+  pluginConfigs: {
+    renderer: { mount: "#game" },
+    audio: { volumes: player => (player as Player).settings.audio }
+  }
+});
+```
+
+`volumes` receives the committed player as `Json`, so the game names its own type once. `player.settings.audio` is `{ master?, music?, sfx? }`, committed by a settings node like any other state and applied on every `model:committed`.
+
+> [!TIP]
+> `app.ui.tree()` answers the live screen as plain data, `app.ui.find(key)` the entity of a keyed element, and `app.ui.lint()` the tap targets under `tapTargetPt`, the text that overflows in some locale and the absolute elements without a `reason`. The example app of the `ui` tests, [`src/plugins/ui/__tests__/app.tsx`](./src/plugins/ui/__tests__/app.tsx), is a whole HUD with a settings component, a scrolling list and a popup, run in plain Bun.
+
+## Doors for the editor
+
+The editor, MCP tools and e2e scripts reach a running game through two subpaths. Neither is on the root.
+
+| Subpath | Exports | In a production build |
+|---|---|---|
+| `@moku-labs/game/inspect` | `read`, `watch`, `defineSource`, the catalogue `sources`, the types `Source`, `InputSchema`, `InputOf` | Safe. Every source only reads. The door reaches no command module, so its bundle carries no command |
+| `@moku-labs/game/control` | `run`, `defineCommand`, `controlRefused`, the catalogue `commands`, the types `Command`, `Ran` | Dev only. `run` throws unless the dev flag is `true`, and a `define` of `false` drops every command body |
+
+A source or a command is data: an id, a title, an input schema and one function. `sources` and `commands` are frozen objects keyed by a short name, so an editor registers `Object.values(sources)` and `Object.values(commands)`. Each descriptor lives in the plugin that owns its data, in that plugin's `inspect.ts` or `control.ts`; the machinery lives in `flow`, see its [README](./src/plugins/flow/README.md#doors-for-the-editor).
+
+The dice game of the [Quick start](#quick-start), driven through both doors:
+
+```ts
+// dice.test.ts
+import { commands, run } from "@moku-labs/game/control";
+import { read, sources, watch } from "@moku-labs/game/inspect";
+import { createHeadless } from "@moku-labs/game/testing";
+import { it, vi } from "vitest";
+import { createGame } from "./game";
+
+it("rolls, bookmarks and restores through the doors", async () => {
+  vi.stubGlobal("__MOKU_GAME_DEV__", true);
+  const app = createGame(42);
+  const game = await createHeadless(app);
+
+  read(app, sources.position); // { path: "home", flow: "main", node: "home", waiting: ["roll", "reset"] }
+
+  const seen: string[] = [];
+  const stop = watch(app, sources.position, undefined, position => {
+    seen.push(position.path);
+  });
+  app.time.step(16);
+  seen; // ["home"]: a headless watch reads on the frames a test steps
+
+  const walked = await run(app, commands.walk, { route: [{ at: "home", intent: "roll" }] });
+  walked.value.path; // "home"
+  walked.state; // { path: "home", frame: 1, tainted: false }: a walk goes through the graph
+  read(app, sources.model).session; // { rolls: 1 }
+
+  const { value: mark } = await run(app, commands.bookmark);
+  await run(app, commands.restore, { bookmark: mark });
+  read(app, sources.tainted); // true: a restore replaces the state outside the graph
+  read(app, sources.cheats); // [{ id: "game.restore", input: { bookmark: { path: "home", ... } }, frame: 1 }]
+
+  stop();
+  await game.stop();
+});
+```
+
+- **Input.** A schema maps field names to `"string"`, `"number"`, `"boolean"` or `"json"`. A kind with a trailing `?` is optional. The input may be left out when every field is optional. The descriptor function gets it typed.
+- **`read(app, source, input?)`** calls the source once and returns what it reads.
+- **`watch(app, source, input, fn)`** reads on the first frame, in the `signals` phase, and again when the source's change key moved: `frame` every frame, `commit` when `model.store.snapshot()` is a new object, `edge` when `flow.state()` is. It returns the stop function. It runs on the frame loop, so a headless test steps frames with `app.time.step(16)`.
+- **`run(app, command, input?)`** resolves `{ value, state }`. `value` is what the command returned. `state` is the envelope `{ path, frame, tainted }`, read after the command.
+- **Screen sources need the screen.** `Source` and `Command` name the app they need. `read(app, sources.rect, { key: "play" })` on an app without `ui` and `renderer` is a compile error.
+
+### Base sources
+
+From `@moku-labs/game/inspect`. `Changes` is when `watch` reads the source again.
+
+| Key in `sources` | id | Input | Changes | Reads |
+|---|---|---|---|---|
+| `graph` | `game.graph` | none | edge | `flow.describe()`: flows, nodes with their flags and outcomes, edges, slots |
+| `position` | `game.position` | none | edge | `{ path, flow, node, waiting }` from `flow.state()`. `waiting` lists the intents the gate waits for |
+| `history` | `game.history` | `{ last: "number?" }` | edge | `flow.history()`, the edges since the last checkpoint: all of them, or the last `last` |
+| `tainted` | `game.tainted` | none | frame | Whether a `cheat` or `raw` command ran on this app |
+| `cheats` | `game.cheats` | none | frame | The journal of `cheat` and `raw` commands, `{ id, input, frame }`, oldest first, the last 500 |
+| `model` | `game.model` | none | commit | `model.store.snapshot()`: the committed `{ player, session, rng }` |
+| `entities` | `game.entities` | `{ owner: "string?", component: "string?" }` | frame | `world.ecs.snapshot().entities`: all, the ones whose owner has that name, the ones that carry that component, or both |
+| `projections` | `game.projections` | none | commit | Projection name to key to entity, through `world.projection.keyOf` |
+| `ui` | `game.ui` | none | frame | `ui.tree()`: the live screen as plain data |
+| `rect` | `game.rect` | `{ key: "string" }` | frame | Where the element with that `key` is on the page, in CSS px; in reference units while the renderer is inert. `undefined` when it is not on screen |
+| `render` | `game.render` | none | frame | `renderer.stats()`: `{ fps, frameMs, textures, textureMb, views, pooled }` |
+| `sounds` | `game.sounds` | `{ last: "number?" }` | frame | `audio.journal()`: all, or the last `last`. Empty unless `pluginConfigs.audio.journal` is above 0 |
+| `assets` | `game.assets` | none | frame | `assets.usage()`: `{ textureMb, budgetMb, bundles }` |
+| `log` | `game.log` | `{ level: "string?" }` | frame | `log.trace()`: every entry, or the entries at `level` and above. A level other than `debug`, `info`, `warn`, `error` throws |
+
+### Base commands
+
+From `@moku-labs/game/control`. Every command runs in dev builds only and leaves a `moku:dev` debug entry in the log.
+
+| Key in `commands` | id | Input | Effect | Does |
+|---|---|---|---|---|
+| `answer` | `game.answer` | `{ intent: "string", payload: "json?" }` | route | `flow.gate.answer({ intent, payload })`. Value: whether the gate took the answer |
+| `tap` | `game.tap` | `{ key: "string?", target: "json?" }`, exactly one | route | `input.tap` on the ui element with that `key`, or on the view `target: { projection, key }`. Value: whether the gate took the answer |
+| `drag` | `game.drag` | `{ from: "json", to: "json" }` | route | `input.drag(from, to)`, both `{ projection, key }`. Value: whether the gate took the answer |
+| `key` | `game.key` | `{ key: "string", shift: "boolean?" }` | route | `input.pressKey(key, { shift })`. Value: whether a listener handled the key |
+| `walk` | `game.walk` | `{ route: "json" }` | route | `flow.walk(route)`. Value: the flow state after the walk |
+| `bookmark` | `game.bookmark` | none | read | `flow.bookmark()`. Value: the bookmark, plain JSON |
+| `restore` | `game.restore` | `{ bookmark: "json?", repro: "json?" }`, exactly one | raw | `flow.restore(bookmark)`, or a `/testing` repro: its state at its checkpoint, then `flow.walk(repro.route)`. Value: the flow state |
+| `step` | `game.step` | `{ frames: "number", deltaMs: "number?" }` | cosmetic | `time.step(deltaMs)` `frames` times, also while paused. `deltaMs` is 1000/60 by default. Value: `time.snapshot()` |
+| `pause` | `game.pause` | none | cosmetic | `lifecycle.push("devtools")`. Value: `lifecycle.isPaused()` |
+| `resume` | `game.resume` | none | cosmetic | `lifecycle.pop("devtools")`. Value: `lifecycle.isPaused()`, still true while another reason holds |
+| `capture` | `game.capture` | none | read | `renderer.capture()`: a PNG data URL of the canvas after the next drawn frame. `undefined` while the renderer is inert |
+| `debug` | `game.debug` | `{ nineSlice: "boolean" }` | cosmetic | `renderer.sync.debug.nineSlice(on)`. Value: the debug switches |
+| `reducedMotion` | `game.reducedMotion` | `{ on: "boolean" }` | cosmetic | `anim.setReducedMotion(on)`. Value: `anim.reducedMotion()` |
+
+### Effects, taint and the cheat journal
+
+| Effect | Means |
+|---|---|
+| `read` | Takes something out of the game and changes nothing |
+| `route` | Goes through the graph or the input, the way a player does. The session stays clean |
+| `cosmetic` | Changes how the game runs or looks. The session stays clean |
+| `cheat` | Changes the state outside the rules. Taints the session and is journaled |
+| `raw` | Replaces the state outside the graph. Taints the session and is journaled |
+
+`run` journals a `cheat` or `raw` command as `{ id, input, frame }` before it runs, so a failing one still counts. The session and the journal belong to one app object: two apps in one process never share them. Read them with `sources.tainted` and `sources.cheats` (`game.cheats`), and in `state.tainted` of every `run`. Of the base commands only `game.restore` is `raw`; none is `cheat`.
+
+### Turn the dev build on
+
+`__MOKU_GAME_DEV__` is a global the engine reads and never sets. Only `true` turns the dev build on; undefined means production, and `run` throws `[game] Control commands run in dev builds only.` The package ships its declaration, `var __MOKU_GAME_DEV__: boolean | undefined`. A game never re-declares it.
+
+**Preferred: a bundler `define`**, `true` in dev and `false` in production.
+
+```ts
+// build.ts of the game
+const production = Bun.argv.includes("--production");
+
+await Bun.build({
+  entrypoints: ["web/main.ts"],
+  outdir: "dist",
+  minify: true,
+  define: { __MOKU_GAME_DEV__: production ? "false" : "true" }
+});
+```
+
+**Or set the global** in a module the dev entry imports before the engine. The fixture page does this in [`tests/integration/merge-game/web/dev.ts`](./tests/integration/merge-game/web/dev.ts):
+
+```ts
+// web/dev.ts, the first import of web/main.ts
+globalThis.__MOKU_GAME_DEV__ = true;
+```
+
+A test sets it with `vi.stubGlobal("__MOKU_GAME_DEV__", true)`.
+
+**What the `define` strips.** Every command body starts with the inline guard `if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();`. A `define` of `false` folds the condition, and the minifier drops the body behind it. [`tests/integration/doors-build.test.ts`](./tests/integration/doors-build.test.ts) proves it with a minified Bun build of each door: with `false` no command body of `/control` is left, with `true` every body is there, and an `/inspect` bundle carries no command id at all. The descriptors stay, so an editor can still list the commands. Without a `define` the bodies stay in the bundle, and `run` still refuses them while the flag is undefined.
+
+### A game's own sources and commands
+
+`defineSource` and `defineCommand` take the same shape as the base catalogue. The id is camelCase words joined by dots, at least two (`dice.rolls`); any other id throws. Keep them in `.dev` modules that only the dev entry and the tests import, so a production bundle never reaches them. `defineCommand` adds no guard: a command writes the inline guard itself, because Bun does not inline a guard function across modules.
+
+```ts
+// dice.dev.ts
+import { controlRefused, defineCommand } from "@moku-labs/game/control";
+import { defineSource } from "@moku-labs/game/inspect";
+import type { createGame } from "./game";
+
+export const rolls = defineSource({
+  id: "dice.rolls",
+  title: "Rolls",
+  input: {},
+  changes: "commit",
+  read: (app: ReturnType<typeof createGame>) => app.model.store.snapshot().session
+});
+
+export const rollTwice = defineCommand({
+  id: "dice.rollTwice",
+  title: "Roll twice",
+  input: {},
+  effect: "route",
+  run: app => {
+    if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+    return app.flow.walk([{ at: "home", intent: "roll" }, { at: "home", intent: "roll" }]);
+  }
+});
+
+export const giveCoins = defineCommand({
+  id: "dice.giveCoins",
+  title: "Give coins",
+  input: { coins: "number" },
+  effect: "cheat",
+  run: (app, { coins }) => {
+    if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+    return app.flow.restore({ ...app.flow.bookmark(), player: { coins, lastRoll: 0 } });
+  }
+});
+
+// On a fresh headless game, before any frame:
+// (await run(app, rollTwice)).state; // { path: "home", frame: 0, tainted: false }
+// read(app, rolls); // { rolls: 2 }
+// (await run(app, giveCoins, { coins: 100 })).state.tainted; // true
+// read(app, sources.cheats); // [{ id: "dice.giveCoins", input: { coins: 100 }, frame: 0 }]
+```
+
 ## Events
 
 Global events are empty: every event belongs to a plugin. `time` and `clock` emit nothing.
@@ -311,6 +652,15 @@ Global events are empty: every event belongs to a plugin. `time` and `clock` emi
 | `flow:edge` | `flow` | `{ flow: string; node: string; outcome: string; payload: Json; next: string; patches: { doc: Patch[]; session: Patch[] }; index: number; now: number }` | After the commit of an edge |
 | `flow:rest` | `flow` | `{ path: string; checkpoint: boolean }` | The graph entered a rest node |
 | `flow:error` | `flow` | `{ path: string; error: unknown; rolledBackTo: string; retry: boolean }` | A node failed and the graph rolled back |
+| `world:reconciled` | `world` | counts per reconcile | Dev only, behind `reconciledEvent` |
+| `renderer:device-lost` | `renderer` | `{ kind, reason }` | The GPU device or context was lost; `lifecycle` is pushed |
+| `assets:bundle-loaded`, `assets:bundle-unloaded` | `assets` | `{ bundle, tier, mb, reason }` | A bundle entered or left memory |
+| `scenes:changed` | `scenes` | `{ from, to, music }` | The scene switched on entering a node |
+| `anim:mark` | `anim` | `{ animation, mark }` | A `mark` step was reached, or jumped by `finish()` |
+| `anim:finished` | `anim` | `{ animation }` | A timeline ended or was finished. Never on `cancel()` |
+| `i18n:locale-changed` | `i18n` | `{ locale }` | The module of the new locale is loaded; `text` re-resolves. Never at start |
+
+`text`, `ui` and `audio` emit nothing.
 
 ```ts
 import { createPlugin, flowPlugin } from "@moku-labs/game";
@@ -330,13 +680,14 @@ export const edgeLog = createPlugin("edgeLog", {
 ### Global
 
 ```ts
-createApp({ config: { orientation: "landscape", referenceSide: 1080 } });
+createApp({ config: { orientation: "landscape", referenceSide: 1080, referenceLong: 1920 } });
 ```
 
 | Key | Type | Default | Meaning |
 |---|---|---|---|
 | `orientation` | `"portrait" \| "landscape"` | `"portrait"` | Screen orientation the game is designed for |
 | `referenceSide` | `number` | `1080` | Short side of the reference resolution in pixels |
+| `referenceLong` | `number` | `1920` | The long side, in reference units, the layout needs inside the safe area. The viewport scale is `min(short / referenceSide, safeLong / referenceLong)`, so a wide screen gives the layout more width instead of shrinking it |
 
 ### Per plugin
 
@@ -346,6 +697,8 @@ Set with `createApp({ pluginConfigs: { <plugin>: { ... } } })`.
 |---|---|---|---|---|
 | `time` | `maxFps` | `30 \| 60 \| 120` | `60` | Frame rate cap |
 | `time` | `maxDeltaMs` | `number` | `50` | Upper bound of one frame's delta in milliseconds |
+| `time` | `idleFps` | `0 \| 30` | `30` | Frame rate cap of an idle screen. `0` turns the idle cap off. Any plugin lifts it with `wake()` |
+| `time` | `idleAfterMs` | `number` | `2000` | Unscaled milliseconds without a `wake()` after which the loop drops to `idleFps` |
 | `lifecycle` | none | | | The plugin has no config |
 | `model` | `playerProvider` | `PlayerStateProvider \| undefined` | `undefined` | The save seam. `undefined` means an in-memory provider: the save lives as long as the app does |
 | `model` | `initialPlayer` | `Json` | `{}` | Player state of a new player. Deep-cloned |
@@ -359,13 +712,37 @@ Set with `createApp({ pluginConfigs: { <plugin>: { ... } } })`.
 | `flow` | `retries` | `number` | `1` | Retries of a failed transition before `safeNode` |
 | `flow` | `settleTimeoutMs` | `number` | `2000` | How long `onStop` waits for the active node to settle after abort |
 | `flow` | `journalLimit` | `number` | `500` | Journal entries kept between checkpoints |
+| `world` | `settleMs` | `number` | `350` | Length of the default settle motion |
+| `world` | `reconciledEvent` | `boolean` | `false` | Emit `world:reconciled` after every reconcile (dev tools) |
+| `renderer` | `mount` | `string \| undefined` | `undefined` | Selector of the mount element. `undefined` keeps the renderer inert |
+| `renderer` | `preference` | `"webgpu" \| "webgl"` | `"webgpu"` | Preferred backend; Pixi falls back to WebGL |
+| `renderer` | `background`, `antialias`, `maxResolution`, `aspect`, `poolLimit`, `unsupportedMessage`, `loadPixi` | | see the plugin README | Host, viewport and pool settings; `loadPixi` is the lazy loader, a test passes a fake |
+| `renderer` | `debug` | `{ nineSlice: boolean }` | `{ nineSlice: false }` | Outline every nine-slice from the start; `sync.debug.nineSlice(on)` switches it live |
+| `input` | `tapSlopPx`, `longPressMs`, `dragStartPx`, `swipeMinPx`, `swipeMaxMs` | `number` | `12`, `450`, `8`, `48`, `300` | Gesture thresholds in reference px and ms |
+| `input` | `cursor` | `{ control: string; idle: string }` | `{ control: "pointer", idle: "" }` | CSS cursor over a control and elsewhere |
+| `assets` | `manifest` | `string \| Manifest \| undefined` | `undefined` | Manifest URL, or the parsed file in a test |
+| `assets` | `textureBudgetMb` | `number` | `192` | Texture memory budget for the LRU unload |
+| `assets` | `preloadDepth` | `number` | `2` | Graph edges walked for the preload at a rest node |
+| `assets` | `baseUrl`, `io` | | `undefined` | The CDN seam and the fetch/decode/texture seam a test replaces |
+| `anim` | `maxTracks` | `number` | `2000` | Dev guard: one warning each time the running track count rises past it. Durations live in the steps, never here |
+| `i18n` | `locale` | `string` | `"en"` | The locale at start |
+| `i18n` | `fallback` | `string` | `"en"` | The locale a missing key is read from before it is reported missing |
+| `i18n` | `locales` | `Record<string, module \| loader>` | `{}` | Compiled modules outside features, per locale |
+| `text` | `fonts` | `{ body, digits }` | `{ body: "ui.font-body", digits: "ui.font-digits" }` | The two boot fonts behind the built-in styles `body` and `digits` |
+| `text` | `missingGlyph` | `string` | `"□"` | Drawn for a glyph the font lacks |
+| `ui` | `tapTargetPt` | `number` | `44` | The smallest tap target `lint()` accepts |
+| `ui` | `breakpoints` | `{ tall, wide }` | `{ tall: 2, wide: 1.5 }` | Aspect thresholds of the `when` style variants |
+| `audio` | `buses` | `{ master, music, sfx }` | `{ master: 1, music: 0.6, sfx: 1 }` | Start gain of each bus, 0..1 |
+| `audio` | `musicFadeMs` | `number` | `600` | Cross-fade of a music switch, in real milliseconds |
+| `audio` | `volumes` | `(player) => Partial<Record<Bus, number>> \| undefined` | `undefined` | Reads the player's choice from the committed player on every `model:committed`. Absent: the buses stay at `buses` |
+| `audio` | `context` | `() => AudioContext \| undefined` | `undefined` | The context factory, a test seam. Absent: `new AudioContext()` where the global exists |
 
 ## Development
 
 ### Scripts
 
 ```sh
-bun run build              # build with tsdown: dist/index.mjs and dist/testing.mjs
+bun run build              # build with tsdown: dist/index.mjs, testing.mjs, assets.mjs, inspect.mjs, control.mjs, jsx-runtime.mjs, jsx-dev-runtime.mjs
 bun run typecheck          # tsc --noEmit
 bun run lint               # biome check . && eslint .
 bun run lint:fix           # biome check --write . && eslint --fix .
@@ -384,7 +761,7 @@ bun run release            # moku-release
 
 | Path | Holds |
 |---|---|
-| `tests/unit/` | Framework-level unit tests: root index, setup, teardown registry |
+| `tests/unit/` | Framework-level unit tests: root index, setup |
 | `tests/integration/` | Framework-level scenarios across plugins |
 | `tests/integration/merge-game/` | The fixture game, written on the public API only. Not published |
 | `src/plugins/<name>/__tests__/unit/` | Unit tests of one plugin |
@@ -393,7 +770,7 @@ bun run release            # moku-release
 
 Plugin tests never go into the root `tests/` folder. Coverage thresholds are 90% for lines, functions, branches and statements.
 
-### Lint rules L1 to L6
+### Lint rules L1 to L9
 
 The project rules live in [`eslint.config.ts`](./eslint.config.ts).
 
@@ -403,14 +780,18 @@ The project rules live in [`eslint.config.ts`](./eslint.config.ts).
 | L2 | No static import of `pixi.js` or `yoga-layout`. They are loaded lazily with `import()` | `src/**` |
 | L3 | Determinism: no `Date.now`, `performance.now`, `new Date`, `Math.random`, `setTimeout`, `setInterval` | `model`, `flow`, `clock` except `clock/system.ts`, and the rules of the fixture game |
 | L4 | The rules of the fixture game import only their siblings | `tests/integration/merge-game/rules/` |
-| L5 | No module-scope state: no top-level `let`, no top-level `Map`, `Set`, `WeakMap`, `WeakSet`. The only registry is `src/teardown.ts` | `src/**` |
-| L6 | Plugin wiring files need no JSDoc on small inline arrows. Every other export needs JSDoc with description, params, returns and example | `src/plugins/*/index.ts` |
+| L5 | No module-scope state: no top-level `let`, no top-level `Map`, `Set`, `WeakMap`, `WeakSet`. No allowlist | `src/**` |
+| L6 | Plugin wiring files need no JSDoc on small inline arrows. Every function declaration and every exported type needs JSDoc with description, params and returns | `src/plugins/*/index.ts` |
+| L7 | The public contract carries the docs: every member of a `…Api` type in `types.ts` has JSDoc and a scenario `@example` (when it is called, literal arguments, the result). A member another plugin calls is shown from that plugin's point of view; there is no private tier and no exemption. The implementation of an API method has no JSDoc. Elsewhere an example is allowed, never required | `src/plugins/**/types.ts` |
+| L8 | No signature echo: an `@example` whose whole body is one call with bare identifiers is an error | `src/**` |
+| L9 | The JSX runtime module is reached only through `src/jsx-runtime.ts` and `src/jsx-dev-runtime.ts`, and those two import nothing else | `src/**` outside `ui` |
 
 ## Requirements
 
 - **Node `>= 24`** and **Bun `>= 1.3.14`**. Use `bun` only, never npm, yarn or pnpm.
 - **TypeScript** in strict mode, with `exactOptionalPropertyTypes` and `noUncheckedIndexedAccess`.
-- **`pixi.js` `^8.0.0`** as a peer dependency.
+- **`pixi.js` `^8.0.0`** as a peer dependency. **`yoga-layout`** is a dependency, loaded lazily by `ui`. The string compiler on the `assets` door uses `@formatjs/icu-messageformat-parser`; no parser ships to the browser.
+- **JSX**: `"jsx": "react-jsx"` and `"jsxImportSource": "@moku-labs/game"` in the game's `tsconfig.json`. Screens are `.tsx` files.
 - **[`@moku-labs/core`](https://github.com/moku-labs/core)** is the kernel: plugins, lifecycle, events. **[`@moku-labs/common`](https://github.com/moku-labs/common)** brings `log` and `env`.
 
 ## Docs
@@ -419,7 +800,13 @@ The project rules live in [`eslint.config.ts`](./eslint.config.ts).
 - [`lifecycle`](./src/plugins/lifecycle/README.md): pause reasons
 - [`model`](./src/plugins/model/README.md): store, rng, provider seam, migrations
 - [`clock`](./src/plugins/clock/README.md): `now`, `scheduleAt`, `fakeClock`
-- [`flow`](./src/plugins/flow/README.md): runner, gate, inbox, fx, features
+- [`flow`](./src/plugins/flow/README.md): runner, gate, inbox, fx, features, the door machinery
+- [`world`](./src/plugins/world/README.md), [`renderer`](./src/plugins/renderer/README.md), [`input`](./src/plugins/input/README.md), [`assets`](./src/plugins/assets/README.md), [`scenes`](./src/plugins/scenes/README.md): the screen
+- [`anim`](./src/plugins/anim/README.md): tracks, timelines, `defineMotion`, the driver
+- [`i18n`](./src/plugins/i18n/README.md): messages, parts, the compiler, supported ICU
+- [`text`](./src/plugins/text/README.md): styles, tags, measurement, fonts
+- [`ui`](./src/plugins/ui/README.md): the JSX runtime, components, styles, layout, popups
+- [`audio`](./src/plugins/audio/README.md): buses, the unlock, pause, memory
 - [`llms.txt`](./llms.txt): overview for an LLM that writes a game on this engine
 - [Moku Core specification](https://github.com/moku-labs/core/tree/main/specification)