@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/template/AGENTS.md

@@ -0,0 +1,1110 @@
+# AGENTS.md — VGAI Game Project
+
+## The acceptance bar: feature-complete, bot-proven, great-looking
+
+This project is not done at a vertical slice. It is done when the **whole
+game** — every feature in the game's maximal spec/ROADMAP, enumerated up
+front — ships, and every one of those features has a **bot-played
+acceptance criterion** proving it works on the real client (see "Autoplay
+bots" below). Two bars, non-negotiable:
+
+- **Completeness.** Write the maximal spec/ROADMAP before or alongside the
+  first line of code — every feature the game needs, not just the ones
+  that are easy or exciting. **No descopes, no "for now," no
+  vertical-slice-and-ship.** A core-only build with the rest deferred to
+  "later" is not done; it's a partial delivery wearing a done label. If
+  scope turns out to be wrong, revise the spec explicitly and say so — do
+  not quietly narrow it by shipping less.
+- **Visual quality.** "Great-looking" is a claim you DEMONSTRATE, never one
+  you assert. Every visual milestone ships a real, inspectable artifact —
+  screenshots and a gameplay video captured from the actual running client
+  (`npm run game`, not a mockup) — judged against this game's own
+  reference/style bar. "It renders" or "looks good" in prose is not proof;
+  if you can't point at the recording, it isn't shown.
+
+Both bars are proven the same way the autoplay-bot doctrine below proves
+everything else: **the bot plays the real game and the run is the
+evidence.** A skill/feature isn't complete until a bot has played it
+end-to-end and the logs/recording show it working — that's what turns
+"I built X" and "X looks great" from a claim into a demonstrated fact on
+the real product surface.
+
+## Before Writing Any Code
+
+0. **Use this project's matching CLI, then launch the editor and keep it running.**
+   In a source-linked scaffold, invoke CLI commands as `npm run vgai -- <command>`
+   (for example, `npm run vgai -- edit .` or `npm run vgai -- screenshot`).
+   That npm script runs the CLI from the same checkout as `@vgai/engine`;
+   a plain global `vgai` may belong to another worktree and must not be trusted.
+   The other npm scripts already delegate through it, so `npm run dev` / `npm run
+   test:acceptance` are safe. `npm run vgai -- edit .` (run it in the
+   background) — the editor is the authoring surface AND the verification
+   loop: `npm run vgai -- status` / `npm run vgai -- play` /
+   `npm run vgai -- select` / `npm run vgai -- apply-diff` and
+   the `/editor` skill all drive it. Let it auto-open the browser — do NOT
+   pass `--no-open` unless you're certain no human may be watching (that flag
+   is for CI/no-human contexts). On WSL, auto-open already reaches the
+   WINDOWS browser (it hands the URL to `powershell.exe Start-Process`), so
+   running headless in WSL is not by itself a reason to suppress it. ALSO
+   tell the user the URL `vgai edit` prints (the scaffold-generated preferred
+   port is stored in `vgai.game.json`) so they can watch the game
+   take shape — but "telling the user" only counts through a channel they
+   actually see (the user-facing chat/terminal, or the opened browser
+   itself); a note left in a subagent transcript or internal log the user
+   never reads does NOT satisfy this. The editor is ALSO the surface
+   you SHOW the user: when they ask to run/see/open the game, that means
+   the editor's Play mode — present `npm run game` (the standalone
+   player-view page) only when they explicitly ask for the game by
+   itself, or for bot/acceptance runs. Recent conversation topic never
+   changes this default. This step applies to agents
+   too, headless or not: the editor still runs and auto-open still fires (or
+   you explicitly report — through a user-visible channel — that the URL was
+   only printed, not opened, if it genuinely can't be); if part of the
+   editor loop genuinely doesn't fit your game (e.g. fully procedural world,
+   no scene to author), say so explicitly instead of silently skipping the
+   editor. Hand-editing project files (scenes, manifest) is equally
+   legitimate authoring now that the dev server validates every save
+   immediately and surfaces failures loudly — terminal, editor console, and
+   `vgai status` (#103) — so treat the editor's essential agent role here as
+   observation/verification (play, status, screenshot), not the only
+   legitimate way to write files. If a `.vscn.json` you hand-edit is the
+   editor's currently-open scene, it live-reloads automatically PROVIDED the
+   editor has no unsaved changes; if it does, the edit is held back (never
+   silently clobbered or silently dropped) and a loud notice appears in the
+   editor console telling you to save or discard first — watch for that
+   notice rather than assuming a hand edit always shows up immediately.
+
+   **Port identity:** every scaffold gets a random, persisted
+   `vgai.game.json.editorPort`, so projects normally reopen at distinct, stable
+   URLs. `vgai edit` will not silently retarget another project's running
+   editor; if the preferred port is occupied, it falls forward to a free port
+   and prints THAT URL. If you (or the user) already have
+   another vgai project's editor tab open in the browser, don't assume it's
+   this project — read the printed URL/port, or pass `vgai edit --port <n>`
+   to pin a specific port for this project, so an old tab left open from a
+   different project doesn't get mistaken for this session (see the
+   `/editor` skill's CLI Reference for `--port` and `vgai sessions`).
+1. **Choose explicit adapter roots before authoring.** Every v2 manifest has
+   a non-empty `roots` array. Each root declares its adapter directly:
+   `"adapter": "react"` for DOM/layout UI and board/card/menu games,
+   `"adapter": "pixijs"` for sprite/canvas gameplay, and
+   `"adapter": "threejs"` for spatial 3D. There is no game-level or root-level
+   `kind` field. The default template already declares Three.js + React because
+   every game needs UI; use `vgai create --template 2d` for PixiJS + React or
+   `--template react` for React-only. JSX is always a declared React root—never
+   mount a second React tree from Three.js setup code. The chosen roots must
+   appear honestly in the editor hierarchy. Root discovery is manifest-driven;
+   source location is only supporting evidence for validation. Do not call
+   `createRoot`, `hydrateRoot`, or legacy `ReactDOM.render` in project source—the
+   generated host owns React mounting for every declared React root. A React-
+   only game also does **not** add a Three.js/PixiJS root merely to obtain an
+   `InputManager`: its real input path is the DOM, driven in playtests through
+   `game.page(async (page) => page.keyboard.press(...))` or locator clicks.
+2. **Read an example.** A plain scaffold ships only a minimal default scene — no example content. The worked implementations (FPS, vehicle, third-person, RTS, multiplayer arena, IK, one-concept tutorials — see the Examples Catalog below) are standalone projects in the vgai monorepo's `examples/<id>/`. Scaffold one directly to read/copy its code: `npx create-vgai-project <name> --example <id>` (e.g. `--example third-person`) makes a correctly-rewritten standalone copy of that example, `vgai.game.json` and all. You can also open any of them live in the hosted editor at `https://vgai-editor.pages.dev/?project=<id>` (read-only — scaffold to keep edits). Otherwise, build gameplay from the Components section below.
+3. **Read the schema.** Scene format is defined by the engine's Zod schemas; the generated JSON Schema is `schemas/vscn.schema.json` inside the engine package (your tsconfig `paths` / vite alias points at the engine — the schema sits next to its `src/`). Read it before writing or editing any `.vscn.json` file. Wrong field names (e.g. `type` instead of `bodyType` in physics) silently break things. Do **not** author fields the runtime doesn't read: `gamepad_axis_pair`/`mouse_move` input bindings — these (like dead `.vscn` fields) **throw at parse** — the engine ships Zod schemas for every fetched asset format (`inputmap.schema.json` sits beside `vscn.schema.json` in the engine package). Discrete character animation (idle/walk/run/jump) is an XState machine + `bindXStateAnimation` in your own component code, not a `.vscn` field — see the engine's `packages/engine/src/animation/xstate-animation-binding.ts` and a scaffolded `--example third-person`'s `src/components.ts`.
+4. **Read `src/scripts/registry.ts`.** Every component used in a scene must be registered here. Unregistered components fail with "Component not found in registry".
+
+### Procedural humanoids and character animation
+
+The source-linked engine includes a procedural, skinned humanoid capability at
+`@engine/humanoid`: `generateHumanoid`, `createHumanoidClipLibrary`,
+`skinToHumanoid`, `attachToBone`, and `restJointPosition`. It generates the
+visible body; animation inputs remain ordinary `THREE.AnimationClip`s. This is
+a capability boundary, not a character recipe: body shape, visual identity,
+movement model, camera, controls, state names, and clip set all belong to the
+game.
+
+**The default humanoid is not a styled game character.** Its multicolored
+capsule/part material is an engineering reference visualization for checking
+the skeleton, proportions, skinning, and animation. Do not ship that default
+look unchanged for a prominent player character unless the brief deliberately
+calls for it. Changing proportion parameters creates a different body type but
+does not, by itself, create visual identity. Make an explicit project-owned
+styling choice before treating the character as finished: at minimum a
+coherent material treatment, or ordinary Three.js clothing/accessories built
+with `skinToHumanoid` and `attachToBone`. The engine intentionally does not
+prescribe what that style should be.
+
+Before choosing runtime generation for a persistent player/NPC, inspect the
+project command catalog with `npm run vgai -- run --list --json`. Installed
+libraries may advertise ordinary author-time commands through their own
+`package.json`; the engine's humanoid package contributes a bake command that
+can produce a normal GLB + `.prefab.json` + provenance, with optional
+retargeted clips. Prefer that authored prefab when the character should exist
+in the scene before Play. Runtime `generateHumanoid()` remains correct for
+genuinely dynamic/spawned characters and previews. Commands are capabilities,
+not game-design prescriptions—the baked asset still uses the reference body's
+unstyled default material until the game deliberately restyles/composes it,
+and the body, controls, camera, and behavior remain the game's own decisions.
+
+For gameplay animation, preserve these contracts:
+
+- A `prePhysics` controller owns movement and exposes corrected speed,
+  grounded state, and latched actions. A separate `animation`-phase
+  `GameComponent` reads that state, drives an ordinary XState actor, and ticks
+  `bindXStateAnimation`. Never advance `rig.update`, `AnimationMixer.update`,
+  or a binding's `tick` from the controller.
+- Rapier's kinematic character-controller query treats sensors as movement
+  hits by default. Pass `ctx.rapier.QueryFilterFlags.EXCLUDE_SENSORS` as the
+  third argument to `computeColliderMovement`; the character then crosses the
+  sensor and the normal physics step delivers `onTriggerEnter/Exit`. Do not
+  replace that event contract with per-frame distance polling.
+- Resolve every required gameplay clip during an awaited `async init()` and
+  let a missing clip reject initialization. `GameComponent.init()` supports
+  promises; do not bypass that readiness guarantee with `void this.loadClips()`.
+  Do not catch a missing locomotion/action clip and silently substitute or
+  downgrade it.
+- Direct `rig.playClip` + `rig.update` is the small path for an isolated
+  preview, cinematic, or simple one-shot—not a second gameplay transition
+  system.
+- `rig.dispose()` cleans the generated hierarchy, clothing, and attached props.
+  A material passed into `generateHumanoid(..., { material })` remains
+  caller-owned and must also be disposed by the caller.
+- Acceptance evidence samples the animation state while honest input is held
+  and captures representative moving poses; a screenshot taken after release
+  proves only the return-to-idle frame.
+- Keep provenance beside any copied clip asset: source, author/license where
+  applicable, exact upstream path or catalog ID, and a content hash.
+
+The full API and retargeting policy are in the engine checkout's
+`docs/PROCEDURAL-HUMANOID.md`. The rules above intentionally do not prescribe
+a particular humanoid design or game concept.
+
+## Commands
+
+```bash
+npm run vgai -- edit .   # Launch the editor for this project (opens browser)
+npm run vgai -- play     # Enter play mode
+                         # Play-mode (and ingest-mode) edit policy:
+                         # - LIVE-BUT-DISCARDED: gizmo transforms, rename,
+                         #   visibility, environment tuning — applied to the
+                         #   running scene, thrown away on stop.
+                         # - BLOCKED (console warning): saving (Cmd/Ctrl+S),
+                         #   structural ops (add/delete/cut/copy/paste/reparent),
+                         #   inspector edits that rebuild the object (mesh,
+                         #   material, physics, ...), undo/redo, opening files.
+                         # Nothing you change during play can leak into your
+                         # .vscn. Stop play mode to persist edits.
+npm run vgai -- restart  # Remount every game root without reloading the editor page.
+                         # Component HMR swaps prototypes and preserves live instances;
+                         # it does NOT rerun init(). Restart after changing init-time
+                         # registrations, listeners, generated resources, or ownership.
+npm run vgai -- screenshot # LOOK AT THE GAME — PNG of the RUNNING game (canvas + HUD,
+         [--out <path>]  # composited), written to .vgai/screenshots/ and its path printed.
+                         # Needs play mode running; fails loudly rather than writing a
+                         # blank/editor-only image. Game STATE can report a healthy
+                         # "playing" phase while the canvas is blank or double-rendered —
+                         # only the pixels catch that. See "Autoplay bots" below.
+npm run vgai -- status   # Check editor state
+npm run vgai -- apply-diff <scene.vscn.json> <patch.json> [--report]
+                         # The canonical programmatic edit op: apply a
+                         # JSON SceneDiff patch (add/remove/update/move ops +
+                         # environment/name) to a scene file. Validates the
+                         # scene, the patch, AND the result through the engine's
+                         # Zod schemas, and dereferences every asset reference
+                         # the diff introduces (existence for all; schema parse
+                         # for .mat/.prefab refs) — nothing is
+                         # written on any failure.
+                         # --report: validate + summarize only, never write.
+                         # Prefer this over hand-editing .vscn JSON in scripts.
+npm run dev              # Open the EDITOR on this project (delegates to `vgai edit .`) —
+                         # the authoring surface; press Play (or `vgai play`) to run the game
+npm run game             # Vite dev server for the STANDALONE game page (no editor) — the
+                         # ship-shaped form, for player-view testing/bots/CI, not authoring
+                         # (show it to the user only on their explicit request — "see the
+                         # game" means the EDITOR's Play mode)
+npm test                 # Logic tests (vitest, tests/logic/) — headless, seconds per run
+npm run playtest         # Inner-loop autoplay: a plain @vgai/live script (npx tsx) driving
+                         # the live `vgai edit` session/tab you already have open — no
+                         # second browser, no committed spec. See "Autoplay bots" below.
+npm run vgai -- probe    # Committed acceptance suite (tests/acceptance/*.spec.ts) — the ONE
+                         # way to bot-PROVE a feature for the record; see "Autoplay bots"
+                         # below. (`npm run test:acceptance` is the same.) Plays inside a
+                         # live `vgai edit` session's tab by default when one exists, else
+                         # against the standalone game page (`--standalone` forces the
+                         # latter, `--in-editor` requires the former).
+                         # doctor vs probe: `vgai doctor` asks "does this project mount in
+                         # the editor?"; `vgai probe` asks "do this game's acceptance specs
+                         # pass?"
+npm run build            # tsc + vite build
+npm run typecheck        # Type-check (includes tests/tsconfig.json)
+```
+
+## Project Structure
+
+```
+public/
+  scenes/          .vscn.json scene files (entities, transforms, components)
+  audio/           Audio assets
+src/
+  main.ts          Entry point — creates game runtime
+  runtime/         Scaffold-owned standalone host wiring; game roots do not edit this
+  data/            Data assets: <name>.schema.ts + emitted .schema.json + .data.json
+                   (tuning.* ships as the worked example; see src/data/README.md)
+  operations/      Project automation: <name>.operation.ts thin wrappers around ordinary
+                   functions — Node-discovered, schema-validated, never auto-bundled
+  tools/           Project tools: <name>.tool.tsx editor panels (center document or
+                   inspector section) — editor-only, never bundled
+                   (example.tool.tsx + spin.tool.tsx ship; see src/tools/README.md)
+  scripts/
+    registry.ts    Component registry (GameComponent classes)
+    components/    Custom GameComponent classes
+  ui/              React UI kit, pages, live connectors, and colocated CSF stories
+server/
+  rooms/           Colyseus multiplayer rooms
+vgai.game.json     Sole project manifest: identity, roots, editor port, build + authoring config
+```
+
+## Key Concepts
+
+The project has a small set of fundamental concepts, each with one home:
+
+- **Roots** — explicit runtime adapter mounts in
+  `vgai.game.json.roots[]`. Every root has an `id` and an `adapter`
+  (`threejs`, `react`, `pixijs`, or a module/ingest adapter object carrying
+  its `surface`). Roots are required and are never inferred or synthesized.
+  The editor projects them as `Game → Three.js / React / PixiJS`, introducing
+  named instances when one surface has multiple roots.
+- **Hierarchy projection** — optional editor-only organization in
+  `vgai.game.json.authoring.hierarchy`; it labels roots and can group references
+  across surfaces (for example an `Overworld` group containing a Three.js scene
+  root and a React menu root). It never loads, owns, copies, pauses, or disposes
+  runtime roots. Example:
+  ```json
+  {
+    "authoring": {
+      "hierarchy": {
+        "rootLabels": { "main": "World Scene", "ui": "Menu Page" },
+        "groups": [{ "id": "overworld", "label": "Overworld", "roots": ["main", "ui"] }]
+      }
+    }
+  }
+  ```
+  The visible tree is semantic and adapter-declared: a root owns its active
+  document, a React CSF document owns its stories, and the active story owns
+  the live component/DOM subtree. Keep primary names source-owned (scene file,
+  CSF title/story, component boundary, entity); do not encode state or infer
+  behavior from magic words in ids/labels.
+- **Scenes** — optional content assets owned by a scene-capable world adapter,
+  not peer game roots. `.vscn.json` files define Three.js entity hierarchies;
+  the default Three adapter loads the selected asset. **Prefabs**
+  (`.prefab.json`) are reusable entity templates.
+- **GameComponents** — *how things behave*: per-entity classes with
+  `init`/`update`/`dispose` and a `static schema` (Zod) for per-entity config
+  (see Components below).
+- **Loop hooks** — *when things run*: per-frame system phases `input` →
+  `prePhysics` → `physics` → `postPhysics` → `gameLogic` → `animation` →
+  `preRender` → `render`, via `GameComponent.phase` or `ctx.systems.add`.
+  **Every `setup()` must return a `dispose()`** that cleans up all objects,
+  bodies, listeners, and UI.
+- **Data** — *what things are*: schema'd JSON in `src/data/`, the layer the
+  inspector (and designers, and VS Code) edit — shared/global definitions and
+  tuning, as opposed to per-entity component config. See "Tunable values → a
+  data asset" under One Canonical Way.
+- **Tools** — *how you tune it*: project-authored React panels
+  (`src/tools/*.tool.tsx`) the editor discovers automatically. Placements:
+  `placement: 'document'` (a center workspace document, opened from the
+  command palette — `'dock'` is a deprecated alias — project-global
+  dashboards), `placement: 'utility'` (a bottom utility tab for transient
+  output), and `placement: 'inspector'` with a
+  `match: (node, adapter) => boolean` predicate (a ⚙ section in the Inspector
+  for matching selections). Each tool file exports `tool = defineTool({...})`
+  (from `@engine/tools/define-tool`) plus a default React component; build
+  the panel from `@editor/widgets` (the editor's own widget kit + THEME
+  tokens) so it looks native. `src/tools/example.tool.tsx` (document) and
+  `spin.tool.tsx` (inspector) ship as worked examples — both live-tune
+  `src/data/tuning.data.json` through `useData`/`writeData`
+  (`@engine/react/use-data`) and the running game follows via HMR. An
+  inspector tool can also read the selected entity's OWN component config —
+  `useSelection()` (`@engine/react/use-selection`) returns the selected node,
+  its attached components, and each component's authored config, live.
+  Tools are editor-only dev surfaces, stripped from shipped games by
+  construction: `npm run build` bundles only what `index.html` →
+  `src/main.ts` imports, and nothing in game code imports `src/tools/`.
+- **Operations** — *how reusable project automation becomes discoverable*:
+  ordinary JS/TS functions remain the implementation and may be imported
+  directly by game code. A thin `src/operations/*.operation.ts` module exports
+  `operation = defineOperation({...})` from `@vgai/sdk/registry`, declaring
+  Zod input/result schemas, host, mutation, and permission metadata. No manual
+  registry or manifest entry exists: the editor scans the folder and exposes a
+  Project Commands catalog plus a default JSON/schema runner. Agents use `npm run vgai -- run --list --json`
+  to discover capabilities and `npm run vgai -- run <name>` to invoke one
+  (add `--input <file>` and `--yes` when needed). Keep the wrapper free of
+  React/editor imports; a custom interface is an optional
+  `src/tools/*.tool.tsx` that calls it through `@vgai/editor-sdk`. Files it
+  persists under `public/` are ordinary project assets and refresh the Assets
+  navigator after a successful mutation; the tool itself is not an asset. A
+  generator is simply an operation whose native function generates content,
+  not a new engine kind. See `src/operations/README.md`.
+
+## Components
+
+All per-entity behavior is a **GameComponent class** — an OOP class with an `init`/`update`/`dispose` lifecycle. The Object3D *is* the entity (there is no ECS / no `eid`): inside a component, `this.object3D`, `this.rigidBody`, and `this.collider` are wired up for you. **Every component referenced by a scene must be registered in `src/scripts/registry.ts`** — unregistered components cause "Component not found in registry" at play time. `update` is mandatory (not optional like `init`/`dispose`) by deliberate design — components are for *behavior*: if you find yourself writing an empty `update(_dt, _ctx) {}` body, that's a signal the class may not need to be a GameComponent at all (a pure state-holder with only `init`/event methods usually belongs as a plain object instead).
+
+| | GameComponent Class |
+|---|---|
+| **What** | OOP class extending `GameComponent` with lifecycle (`init`/`update`/`dispose`, optional `onTriggerEnter`/`onTriggerExit`) |
+| **Use for** | All gameplay behavior — controllers, cameras, AI, pickups, tags |
+| **Access** | `this.object3D` / `this.rigidBody` / `this.collider`; config fields from `static schema` (Zod) |
+| **Editable fields** | Declare a `static schema = z.object({...})` with `.describe()` + `.default()` — these become typed, documented widgets in the editor inspector and are validated on load |
+| **HMR** | Yes (prototype swap preserves instance state on live edit) |
+| **Reference** | `src/scripts/components/scene-camera.ts` (`SceneCamera` — declares `static phase` + `static schema`) in this project; for richer patterns, scaffold a worked example (`npx create-vgai-project <name> --example fps`, `--example vehicle`, `--example third-person`, ...) and read its `src/components.ts`; base class at `packages/engine/src/ecs/game-component.ts` |
+
+**Before creating a component:** read the reference above (or a scaffolded example's, per the "Read an example" step) and copy the pattern (`static phase`, `static schema`, `init`/`update`). Don't author ad-hoc `ctx.systems.add` closures for gameplay — they're neither editable nor hot-reloadable; reserve `systems.add` for non-gameplay infra (audio mixers, network send, etc.).
+
+**Procedural games (no scene file):** components also attach at runtime to
+code-created objects — construct the instance yourself and call
+`ctx.components.attach(object3D, instance)`; the component manager runs `init`
+and the per-frame lifecycle exactly as for scene-authored components. A fully
+procedural world (voxel terrain, roguelike floors, …) legitimately has a
+manifest world with an `entry` and **no `scene`**, and skips `.vscn` authoring
+entirely — registry registration is only *required* for components referenced
+by scene files. The editor still works on such games: play mode adopts the
+live scene graph into the hierarchy/inspector.
+
+Declaring an `entry` module on a manifest world needs **no edit to
+`src/main.ts`**: the scaffold registers the engine's stock threejs adapter-surface
+factory, so an entry module exporting `setup` (or `adapter`) just mounts. One
+rule to know: an `entry` world's `setup()` **owns scene loading** — if the
+world also declares `scene`, call `loadScene()` on it yourself inside
+`setup()` (the automatic scene mount applies only to roots with no `entry`).
+
+**Registration:** `src/scripts/registry.ts` exports two maps:
+- `componentRegistry` — **all** GameComponent classes referenced by scene files (used by the loader + scene validator)
+- `gameComponents` — the same classes, for HMR
+
+**In scene JSON**, components are an object keyed by name: `"components": { "Checkpoint": {}, "MarbleController": { "forceStrength": 12 } }`. Names must match `componentRegistry` keys; field names must match the component's `static schema`. Empty `{}` for tag components (no schema).
+
+**System phases** (for `ctx.systems.add` and `GameComponent.phase`): `input` → `prePhysics` → `physics` → `postPhysics` → `gameLogic` (default) → `animation` → `preRender` → `render`
+
+## One Canonical Way Per Task
+
+For each common job there is exactly ONE recommended approach. Use it — competing paths cause ambiguity and non-determinism.
+
+- **Camera → a camera GameComponent.** Attach a component that positions/aims `ctx.camera` (the shipped patterns to copy: `FPSCamera` in a `--example fps` scaffold's `src/components.ts`, `ChaseCamera` in `--example vehicle`, `CameraTarget` in `--example third-person` — all schema-declared and driven in `preRender`). This project also registers a minimal `SceneCamera` (`src/scripts/components/scene-camera.ts` — schema-declared position + look-at target). Precedence is fixed and intentional:
+
+  `editor viewport camera < scene-defined camera < camera GameComponent`
+
+  The editor's viewport transform is only the *initial* viewpoint, so a scene-defined or component-driven camera always wins (this is why play mode uses your scene's camera, not the editor's orbit camera). Do **not** also write an ad-hoc `ctx.systems.add('preRender', ...)` camera closure — put the camera logic in the component.
+
+- **Gameplay behavior → a GameComponent.** Never an ad-hoc `ctx.systems.add` closure (those are neither editable nor hot-reloadable). Reserve `systems.add` for non-gameplay infra only (audio mixers, network send, debug overlays). See the Components section above.
+
+- **Tunable values → a data asset, never a constant.** If a designer (or you,
+  while tuning) should be able to change a value without editing game code, it
+  lives in `src/data/` as JSON governed by a Zod schema — not as a constant in
+  a component or `setup()`. Per-entity config stays in the component's
+  `static schema` (see Components); data assets are the shared/global layer:
+  feel tuning, economy numbers, tables of game definitions.
+
+  Two blessed shapes, and only these (they're what the editor's DATA tab can
+  render as real widgets): a **singleton** — one `z.object` config whose
+  fields are scalars (number/string/boolean/enum), optionally grouped one or
+  two levels deep in nested `z.object`s (the tab renders groups as sub-forms)
+  — or a **table** — `z.record(z.string(), rowSchema)` with a flat row schema,
+  rendered as a grid (this Zod version's `z.record` takes a key schema AND a
+  value schema — the single-arg `z.record(rowSchema)` shorthand from Zod 3
+  throws here). Anything the tab can't type (arrays, deep nesting, unions)
+  degrades to a raw-JSON cell that refuses invalid commits — prefer
+  flattening, or a table, when a designer should tune it. Tables also get a
+  spreadsheet-friendly bulk-edit path: the DATA tab's **Export CSV** /
+  **Import CSV** buttons round-trip the whole table (header `key,<row
+  fields>`). Import is a WHOLE-TABLE REPLACE (a row the sheet doesn't mention
+  is deleted) and ATOMIC (any cell that fails to coerce to its field's kind —
+  e.g. non-numeric text in a `number` column — writes NOTHING; fix the sheet
+  and re-import). `"$schema"` is never a CSV column; it's carried over from
+  the file automatically.
+
+  ```ts
+  // src/data/tuning.schema.ts — engineer-owned: the contract
+  import { z } from 'zod'
+  export const tuningSchema = z.object({
+    gravity: z.number().min(0).max(50).default(9.8).describe('m/s², downward'),
+  })
+  ```
+  ```jsonc
+  // src/data/tuning.data.json — designer-owned: the values
+  { "$schema": "./tuning.schema.json", "gravity": 9.8 }
+  ```
+  ```ts
+  // src/data/tuning.ts — the live handle (engine defineData, W1)
+  import { defineData } from '@engine/data/data-asset'
+  import raw from './tuning.data.json'
+  import { tuningSchema } from './tuning.schema'
+  export const tuning = defineData(tuningSchema, raw, 'src/data/tuning.data.json')
+  // ['default'] not .default: the template tsconfig's
+  // noPropertyAccessFromIndexSignature applies to Vite's ModuleNamespace
+  import.meta.hot?.accept('./tuning.data.json', (m) => tuning.hotSwap(m?.['default']))
+  ```
+  Read `tuning.get()` live where the value is used (e.g. each frame) — don't
+  copy fields out at init, or HMR edits won't reach them. `subscribe(fn)` fires
+  on every hot edit. **This project ships the pattern working**: the trio in
+  `src/data/` (`tuning.schema.ts` / emitted `tuning.schema.json` /
+  `tuning.data.json`), the handle (`src/data/tuning.ts`), and a consumer
+  (`DataSpinner` on the default scene's Box — press ▶, edit the JSON, watch it
+  change live). Add a data asset by copying that trio AND registering it in
+  `src/data/assets.ts` (the one shared list); after every schema change run
+  `npm run emit-schemas` (commits the emitted `.schema.json` so VS Code
+  validates the data file with no dev server). Rows in table-shaped assets
+  are referenced as `"file#key"` strings — declare a cross-asset field with
+  `dataRef('items')` (`import { dataRef } from './data-ref'` — see
+  `src/data/data-ref.ts`, never `@engine/data/data-ref` or
+  `@vgai/engine/data/data-ref` directly: a schema file loads through
+  `vite.config.ts` at Vite config-load time, which only bundles relative
+  imports) instead of a bare `z.string()`: the emitted schema gets a real
+  `pattern` AND the editor's Data tab renders it as a `stem#key` PICKER (a
+  plain string still works, but has no picker and doesn't survive a
+  target-file rename in `vgai doctor`'s checks). Read the referenced row
+  with `getRef(itemsHandle, enemy.drop)` (also from `./data-ref`) — pass the
+  TARGET's own handle, not a stem string; it resolves live off `.get()`, same
+  HMR doctrine as everything else in this file. Data assets are immutable at
+  runtime — runtime state lives in your game's own state, never written back
+  into data files. Enforcement is automatic: `npm run build` fails loud on a
+  data file that no longer matches its schema, a dangling `"file#key"` ref (or,
+  for a declared `dataRef` field, a target file that no longer exists at all),
+  or tool code reaching the shipped bundle, and `vgai doctor <folder>` runs
+  the same data checks terminal-side.
+  (The editor edits these files in place — each data asset opens as its own
+  center document — and project
+  tools (`src/tools/`, see Key Concepts) tune them live through the same
+  file-write path. WSL note: if this project lives on `/mnt/c` (drvfs — no
+  inotify), polling is turned on AUTOMATICALLY — both the editor dev server
+  and this project's standalone `npm run game` detect the drvfs mount and
+  poll for changes with no setup needed, so external edits to `.data.json`
+  hot-reload into the running game either way. `VGAI_WATCH_POLL` is only an
+  explicit override, for the cases auto-detection doesn't cover: `=1`/`=<ms>`
+  forces polling on (e.g. a non-drvfs path that still needs it), `=0` forces
+  it off. Both servers honor the same variable the same way.)
+
+- **Material → inline `material` OR `materialRef`, never both.** An entity uses one or the other: inline `material` for a one-off look, or `materialRef` pointing at a shared `.mat.json` when several entities share a material. Setting both is a hard load-time validation error (enforced by a Zod refine in the engine schema) — there is no silent precedence to memorize.
+
+## Rules
+
+- **The engine is source-linked, not copied.** `@vgai/engine` resolves as a
+  symlink back into the vgai checkout you scaffolded from (a `file:`
+  dependency plus `@engine/*` aliases into `<checkout>/packages/engine/src`).
+  The engine source is yours to read — but **editing it edits the shared
+  checkout**, instantly affecting every project scaffolded from it. A game
+  that truly needs a divergent engine forks the checkout. Your manifest's
+  `engine.version` records which engine version this project was scaffolded
+  or last upgraded against; after updating the checkout, run `vgai upgrade`
+  (report first; `--report` for report-only) to re-sync untouched template
+  files and re-pin — your own edits are never overwritten.
+  **drvfs caveat (WSL, project on /mnt/c):** npm materializes the `file:`
+  dependency as a COPY there, not a symlink — after engine changes, code that
+  resolves through `node_modules/@vgai/engine` (root scripts like
+  `emit-schemas.ts`/`validate-scenes.ts`) sees a STALE engine until you
+  refresh it: `rm -rf node_modules/@vgai/engine && npm install`. The
+  `@engine/*` tsc/vite aliases always see the live checkout and are
+  unaffected.
+- **Use engine/library APIs directly.** No wrappers around Three.js or Rapier.
+- **GameComponents are for gameplay entities only.** Static scenery, lights, and UI are plain Three.js objects.
+- **React UI is always a manifest adapter root with `"adapter": "react"` + an
+  `entry` that default-exports a component.** JSX is truth; React roots have no
+  scene file, and GameComponents cannot attach to React nodes. Position UI
+  against its contained root layer and do not portal to `document.body`, which
+  escapes host composition. The default template already includes a React root. Never
+  call `createRoot`, `hydrateRoot`, or `ReactDOM.render` in project source—the
+  host owns the one React lifecycle for every declared root.
+
+  **A first-party React root always uses the ecosystem-native three-file
+  split:**
+  ```text
+  game-page.tsx               pure page: props + callbacks, no Game dependency
+  game-page-world.tsx         thin live Game/useGameState connector; default export
+  game-page-world.stories.tsx portable CSF3 fixtures for stopped-mode design states
+  ```
+  Add the connector path as the React root's `entry` in `vgai.game.json`.
+  That is the complete host wiring: the scaffold's Vite config generates
+  static imports directly from the manifest's declared `entry` paths, and
+  the engine's optional React adapter entry point owns the standard
+  `createRoot` + `GameProvider` lifecycle. Do not add an import table or
+  duplicate a React adapter in game code.
+  Associate the CSF module with the manifest root through Storybook's standard
+  parameter extension point:
+  ```tsx
+  const meta = {
+    component: GamePage,
+    parameters: { vgai: { root: 'ui', defaultStory: 'Playing' } },
+  } satisfies Meta<typeof GamePage>;
+  ```
+  Use ordinary CSF `args`, decorators, loaders, and `play()` functions; the
+  editor composes the story with Storybook itself. Edit mode mounts the
+  selected/default story in the main viewport. Play replaces it with the live
+  connector; Stop restores the story. Do not create `src/ui/registry.ts`, a
+  fake `Game`, or a VGAI-specific story object. `vgai validate`/`vgai doctor`
+  warns when a first-party React root has no associated CSF module.
+
+  React is ordinary React—normal props/hooks/context/`useState`, normal inline
+  styling—with no second UI data language.
+
+  **Input/pointer:** each React root's DOM layer is `pointer-events: none` by default so
+  clicks fall through to the canvas underneath; an interactive element opts
+  in with `pointer-events: auto` (only that element — and its subtree —
+  becomes clickable, everything else stays click-through):
+  ```tsx
+  <button style={{ pointerEvents: 'auto' }} onClick={onFire}>Fire</button>
+  ```
+  **No emoji glyphs in HUD text** (meteor-dodge dry-run): the headless
+  Chromium `vgai probe` runs under has NO color-emoji font, so `❤️`-style
+  glyphs render as empty tofu boxes in every probe screenshot (and on any
+  machine without an emoji font). Use inline SVG icons for hearts/stars/etc.
+  — a vector shape renders identically in probe, the editor, and any
+  browser.
+
+  The host calls `root.unmount()` when the adapter root is disposed; project
+  code does not implement or duplicate this cleanup.
+
+  To bridge live game state (a singleton gameplay component's score/lives/wave)
+  into the UI, don't poll—the host already wraps the root in `GameProvider`.
+  Import `useGameState` directly from `@engine/react/game-state` and select,
+  for example, `g.queryByComponent(MyComponent)[0]?.field`. The selector
+  re-runs at most once per frame. Worked reference: `hp-hud/src/hud.tsx`. (This project's
+  `vite.config.ts` ships `resolve.dedupe: ['react', 'react-dom']` so the
+  source-linked engine's react bridge resolves the SAME physical `react` as
+  this project — without it, `<GameProvider>` crashes with `Invalid hook
+  call` from two react copies; don't remove that `dedupe` entry.)
+- **Multiplayer → Colyseus directly.** vgai deliberately has no engine-level networking wrapper. Typed `joinOrCreate<T>` + the v0.17 Callbacks API (`onAdd`/`onChange`/`onRemove`; per-field `listen` — but see the P2P caveat below before using it); dynamic-import `@colyseus/sdk` so single-player bundles stay clean. Read live schema properties inside `onChange`; never destructure schema fields into local copies. The worked reference is `network.ts` in a `--example third-person-arena` scaffold (raw Callbacks + an ambient type mirror of the server schema; the engine's old `net/` wrapper is deleted).
+- **P2P mode (browser-hosted rooms) → write dual-target code.** Your room can
+  also run browser-hosted over WebRTC via `@vgai/p2p-colyseus`: build/serve
+  with `VGAI_P2P=1` (this project's `vite.config.ts` aliases the Colyseus
+  packages onto browser-safe compat shims only then) and launch with
+  `?net=p2p-host` / `?net=p2p-join&roomId=…`. The same room class still runs
+  on a real server (`npm run server`), so keep room + client code inside the
+  two runtimes' intersection — full rules with rationale in the engine
+  checkout's `docs/P2P-COLYSEUS-MIGRATION.md` ("Dual-Target Portability
+  Rules"); the short list:
+  - No `$.listen` in the compat layer — read root-state fields inside
+    `room.onStateChange` (use `.once(...)`, not its return value: the real
+    SDK returns an EventEmitter, the compat an unsubscribe function).
+  - No `this.clock` on the compat `Room` — drive all timing from
+    `setSimulationInterval` (tick counters for delays).
+  - Never send messages from `onJoin` (dropped under P2P) — catch-up is
+    client-initiated: register handlers, then send a `sync_req`; reply in
+    bounded batches.
+  - Keep bulky world data OUT of room state (the P2P runtime diffs the whole
+    state per client per tick) — state carries players/actors + small
+    scalars; the world is a seed + an event log sent as messages.
+  - Relay budget ~30 messages/peer/sec, 16 KB max envelope — throttle moves
+    (~10 Hz) and batch bulk sync under the cap.
+
+## Editor Control
+
+Use the `/editor` skill to control the visual editor (select entities, focus camera, play/stop, toggle display modes). The skill documents the `vgai` CLI and `@vgai/editor-sdk`.
+
+### Quick examples:
+```bash
+# Select and focus an entity after editing its scene file
+npm run vgai -- select <entity-id> && npm run vgai -- focus <entity-id>
+
+# Test gameplay
+npm run vgai -- play
+
+# Re-run init() and remount all roots after init-time code changes
+npm run vgai -- restart
+
+# LOOK at what you just changed (state can lie; pixels can't)
+npm run vgai -- screenshot
+
+# Check editor state
+npm run vgai -- status
+```
+
+## Autoplay bots — testing your game in cycles
+
+The highest-leverage test harness for a vgai game is a **synthetic player**:
+a bot that plays the game the way a human does. The full doctrine and the
+evidence behind it live in the engine checkout's
+`docs/SYNTHETIC-PLAYER-SPEC.md` and `docs/ACCEPTANCE-DRIVER-SPEC.md`; this
+section is the practical playbook.
+
+**The principle: synthesized input in, observable state out, no backdoors.**
+For canvas roots the bot presses the same virtual actions; for React-only DOM
+games it drives the same keyboard and interactive elements through
+`game.page(...)`. It reads the same game state a player sees. It never
+teleports the player, calls gameplay methods directly,
+or writes inventory outside a declared test fixture. To the extent the bot
+cannot cheat, every *gameplay* failure it hits is a real player-facing
+defect — a physics gap, a missing line-of-sight check, a UI-sequencing bug.
+
+**Three levels, one vocabulary.** `game.state`/`game.input.*`/`game.page`/`game.waitFor`/
+`game.events.expect`/`game.command`/`game.screenshot` (the `GameClient`
+surface, `@vgai/probe`) mean the same thing everywhere — what changes across
+the three levels below is HOST (where the bot plays) and PERMANENCE (does
+this run live in a file you keep). Be honest with yourself about which one
+you actually need:
+
+1. **Logic** — pure functions, `tests/logic/`, run with `npm test` (vitest,
+   no browser). Seconds per run. Most bugs belong here — see "Test in
+   layers" below.
+2. **Inner-loop autoplay** — a plain script using `@vgai/live`, run with
+   `npx tsx`. No test runner, no Playwright config, no fixture, no second
+   browser: it drives the SAME live `vgai edit` session/tab you (or the
+   human watching) already have open. This is what you reach for to answer
+   "does my game work right now" — which is most of the time you're
+   iterating. Nothing here is committed or re-run later; it's scratch.
+3. **Committed acceptance** ("Acceptance tests", below) — `tests/acceptance/*.spec.ts`,
+   run by `vgai probe`. Same vocabulary as level 2, but a FILE you keep, that runs again
+   on every future change and reports a verdict. This is what proves a
+   feature is actually done.
+
+The tradeoff is real, not sales copy: level 2 is disposable and fast to
+write but proves nothing to anyone who isn't watching; level 3 is what you
+commit, and what CI (or a future you) re-runs. Use level 2 constantly while
+building a feature, then graduate the interaction that proves it works into
+a level-3 spec before calling the feature done.
+
+### Level 2 — inner-loop autoplay with `@vgai/live`
+
+`@vgai/live` is `{ editor, game, page }` over the SAME session wire `vgai
+probe --in-editor` uses (and, since probe now defaults to that transport
+whenever a session is open, the same wire `vgai probe` uses by default too)
+— a plain node/tsx script, not a test file, not a fixture, no config. It
+never starts a session; it only ATTACHES to one already running (`vgai edit`
+— you likely have this open already), and every method rejects with a
+"run `vgai edit` first" error if none exists.
+
+```ts
+// scripts/playtest.ts (see the worked copy already in this project)
+import { editor, game } from '@vgai/live';
+
+await editor.play();                                       // enters play mode; waits for the game's full async setup
+await game.command('spinner.reset');                        // fixture (declared cheat) — jump to a known state
+await game.input.whileHeld('attack', async () => {           // proof + evidence while input is active
+  await game.waitFor((s) => (s('spinner') as { speed: number }).speed > 2,
+    { simSeconds: 10 });
+  await game.screenshot('during-boosted-spin');
+});
+```
+
+Run it with `npx tsx scripts/playtest.ts`. No browser of its own boots, no
+Vite cold start, no watchdog racing a fresh game boot — it rides the tab
+that's already open, so whoever is watching that tab sees the bot play live.
+This is the loop: edit source, `npx tsx scripts/playtest.ts`, read the
+output, repeat — seconds per cycle, not the minutes a fresh standalone boot
+costs.
+
+Everything the "Acceptance tests" (level 3) section below says about `game.command` never being a substitute
+for honest `game.input.*` or React-native `game.page(...)` interaction (D16), sim-time-only budgets, and the
+one-registry/three-doors seam applies here unchanged — `@vgai/live`'s `game`
+is a `GameClient`, the identical type `vgai probe` specs use. What it is
+NOT: a substitute for a committed spec. Nothing written against `game` here
+is re-run later, checked into `tests/acceptance/`, or seen by CI — it is the
+scratch space you iterate in before writing the level-3 spec that actually
+proves the feature.
+
+**React-only DOM games:** do not invent a canvas root for testing. Use the
+cross-host page door; it is real Playwright on the standalone host and a
+relay-safe DOM shim in the already-open editor tab:
+
+```ts
+await game.page(async (page) => {
+  await page.keyboard.press('ArrowLeft');
+  await page.getByRole('button', { name: 'Restart' }).click();
+});
+await game.waitFor(
+  (s) => (s('board') as { moves: number }).moves >= 1,
+  { simSeconds: 5 },
+);
+```
+
+The `game.page` callback is a serialization boundary in the live-editor
+relay. Do not close over imported `expect`, helpers, or outer variables inside
+it. Inline interaction values, return observations from the callback, and
+assert outside it:
+
+```ts
+const boardText = await game.page((page) => page.getByTestId('board').textContent());
+expect(boardText).toContain('2048');
+```
+
+The relay-safe common subset is `keyboard`, `locator`, `getByRole`,
+`getByText`, `getByTestId`, `click`, `fill`, `evaluate`, and locator
+`click`/`fill`/`textContent`/`count`/`waitFor`/`first`/`nth`/`ariaSnapshot`.
+Unsupported Playwright members fail immediately with the supported list;
+they never silently no-op.
+
+Pair this with `useDebugProvider` in the React root. `game.input.*` remains
+the right door for action-map input owned by Three.js/PixiJS adapters;
+`game.page(...)` is the honest path when the game itself is DOM-native.
+
+### After you change something, LOOK at it — `vgai screenshot`
+
+```bash
+npm run vgai -- play          # the game must be RUNNING to have pixels to capture
+npm run vgai -- screenshot    # writes .vgai/screenshots/<timestamp>.png, prints the path
+npm run vgai -- screenshot --out shots/after-hazard-fix.png
+```
+
+**Game state can lie. Pixels can't.** This is not a style preference — it is
+a defect class that has already bitten, twice, in one session:
+
+- A `vgai play` on an ALREADY-playing session left a **ghost runtime** alive:
+  the old game's components kept ticking and rendering alongside the new
+  one's. Three hazards rendered as six. Debug commands reached only one of
+  the two instances while the ghost kept killing the player.
+- A re-entered play mode once came up **stalled at tick 0 with a completely
+  blank canvas** — while `game.state` cheerfully reported `phase: "playing",
+  lives: 3`. Every state read said healthy. The game was dead.
+
+In both cases the state seam reported a healthy, plausible game, and only a
+screenshot showed the truth. So: after any change you believe is visible —
+LOOK. It's one command.
+
+`vgai screenshot` captures the RUNNING GAME through the same
+`bridge-screenshot` seam `game.screenshot()` uses: the full stack — canvas(es)
+PLUS the HUD/react DOM layers, composited — not the editor viewport (a
+viewport grab would happily hand you a HUD-less, possibly not-even-playing
+image). If play mode isn't running it fails loudly and writes **nothing**,
+rather than saving a blank frame you might later mistake for evidence. From a
+`@vgai/live` script, `await game.screenshot('label')` is the same capture,
+and returns the path it wrote.
+
+### Acceptance tests — level 3, the one canonical way to bot-PROVE a feature
+
+<!-- Keep the literal "### Acceptance tests" in this heading. It is not
+     decorative: @vgai/probe's GAME_SEAM_NEVER_APPEARED error tells a stranded
+     user "see 'Acceptance tests' in AGENTS.md" (packages/vgai-probe/src/errors.ts,
+     pinned by errors.test.ts), run-probe.ts cites it, and so do
+     docs/ACCEPTANCE-DRIVER-SPEC.md and -BUILD-PLAN.md. Renaming it orphans a
+     real error message. packages/editor/test/template-agent-doctrine.test.ts
+     guards this. -->
+
+
+**This is the ONE way to bot-prove a feature for the record: acceptance
+specs in `tests/acceptance/*.spec.ts`, driven through `@vgai/probe`'s `game`
+fixture, run by `vgai probe`. Do not hand-roll window globals, `?bot=` query
+params, or your own Playwright boot scripts.** The runner owns Playwright,
+the browser binary, and the config — never run `npx playwright test`
+directly (the fixture refuses to run outside `vgai probe`, and this project
+never needs `playwright install`). Your project contains spec files, plus
+two devDependencies you should never need to touch: `@vgai/probe` (ships
+compiled output — a real dependency, not raw TypeScript) and
+`@playwright/test` (a real, versioned devDependency of YOUR project — `vgai
+probe` resolves and spawns it directly, never `npx`'s registry fallback).
+The project's own `.npmrc` pins `install-links=true`: this keeps exactly one
+physical `@playwright/test` install reachable no matter how the project was
+installed (docs/PROBE-EXTERNAL-INSTALL-DESIGN.md) — don't remove it, and
+don't hand-edit either dependency's version without re-running `npm
+install`.
+
+**`vgai probe` picks its HOST automatically, and always narrates which one it
+picked.** If a live `vgai edit` session already covers this project, `vgai
+probe` plays the spec INSIDE that session's own tab — the same relay
+transport `@vgai/live` (level 2, above) uses, so there's no second browser,
+no fresh Vite/game boot, and it's visible in the tab you're already
+watching; the first line printed always names the host and, for the
+in-editor case, the URL to watch. Only when no session exists does it fall
+back to the standalone host: its own Chromium against `npm run game` (the
+ship-shaped artifact) with the debug bridge enabled (`?vgai-debug=1`
+installs `window.__vgai` in dev builds; production builds keep it off unless
+`vgai.game.json` sets `debug.allowInProduction`). `--standalone` forces the
+standalone host even with a session open; `--in-editor` forces the relay and
+fails loudly if there's no session to use — see `vgai probe --help`.
+Disambiguation: `vgai doctor` asks "does this project mount in the editor?";
+`vgai probe` asks "do this game's acceptance specs pass?"
+
+**The loop (4 steps):**
+
+1. **Register the seam in the owning component** —
+   `ctx.debug.registerStateProvider(name, fn)` / `ctx.debug.registerCommand(name, spec, fn)`
+   / `ctx.debug.emit(event, detail)`: the component that owns the state
+   exposes it, right where it lives (`ctx.debug` is optional-chained because
+   a bare test `Game` may not carry a registry; a real runtime always does):
+   ```ts
+   init(ctx: GameContext) {
+     ctx.debug?.registerStateProvider('spinner', () => ({ laps: this.laps }));
+     // Fixture, never a proof (D16) — a declared cheat for test setup:
+     ctx.debug?.registerCommand('spinner.reset', { description: 'Reset laps.', locus: 'client' },
+       () => { this.laps = 0; });
+   }
+   update(dt: number, ctx: GameContext) {
+     if (lapJustCompleted) ctx.debug?.emit('spin-lap', { laps: this.laps });
+   }
+   ```
+   Worked example: `src/scripts/components/data-spinner.ts`. Two built-in
+   providers exist with zero game code: `time` (`{ simSeconds, tick }`) and
+   `input.actions`. Once the project declares a Colyseus room, every command
+   must declare `locus: 'client' | 'server'` — server-locus commands run on
+   the authoritative copy, not client prediction. In a react world or HUD
+   component, use the hooks instead: `useDebugProvider(name, fn)` /
+   `useDebugCommand(name, spec, fn)` / `const emit = useDebugEmit()` directly
+   from `@engine/react/game-state` — the same game-scoped registry, with
+   providers/commands auto-unregistered on unmount. Emit events with
+   `emit('spin-lap', { laps })`; never import or reach through the internal
+   debug registry from game code.
+2. **Copy `tests/acceptance/example.spec.ts`** and swap in your own
+   provider/command/action names. (If it's missing, `vgai probe --init`
+   scaffolds it plus `tests/tsconfig.json` — idempotent, never overwrites.)
+3. **Run `vgai probe`** — or, to run just one spec while iterating,
+   `vgai probe tests/acceptance/foo.spec.ts` / `vgai probe -g "<title>"`
+   (both pass through to Playwright). The game server is kept warm between
+   runs (`--fresh` boots a new one; `vgai close` tears it down; probe runs
+   show up in `vgai sessions`). `--junit` emits a JUnit XML report for CI.
+   Host selection (in-editor vs. standalone) is covered above; the
+   `--headed`/`--headless` flags below are a SEPARATE, standalone-only axis
+   — they're meaningless (and warned as ignored) once probe is playing
+   inside a live editor tab, since that mode has no browser of its own to
+   launch headed or headless. `--headed` runs the standalone host's browser
+   visibly so a human can watch the synthetic player live (needs a real
+   display — an X server or desktop session on WSL). **Mode selection is
+   automatic and loud, not silent**: on the standalone host, with no
+   `--headed`/`--headless` flag, `vgai probe` runs HEADED by default
+   whenever a live `vgai edit` session is already open for this project
+   (there's a human plausibly watching) and `CI` is unset — otherwise it
+   runs headless (CI-identical). Either way the very first line printed
+   names the mode and why (e.g. `probe: headed (live editor session on
+   :5173) — watch the synthetic player; --headless to opt out`, or `probe:
+   headless (no live editor session for this project) — run \`vgai edit\`
+   and re-run with --headed to watch`) — never guess which mode a run used,
+   read that line. An explicit `--headed` or `--headless` always wins over
+   the default, verbatim.
+4. **Read the failure block.** Every driver-originated failure carries:
+   sim-elapsed vs wall-elapsed with the ratio, the tick at failure, the
+   predicate source text, the last state snapshot the predicate saw, the
+   last tick-stamped events, an absolute screenshot path, and captured
+   console/page errors. A probe failure with NO state evidence attached is a
+   harness bug, not your game's. `vgai probe --last-failure` re-prints the
+   last run's failure blocks with zero boots; artifacts (screenshots,
+   videos, `last-run.json`) land in `.vgai/probe/last-run/` — which the NEXT
+   run wipes (Playwright's own `outputDir` behavior). Before that wipe, the
+   PREVIOUS run's `last-run/` is archived to `.vgai/probe/prev-run/` (one
+   generation back, plain rename, no accumulation) — so a green run's
+   screenshots survive at least one more `vgai probe` before disappearing;
+   check `prev-run/` if you needed evidence from two runs ago.
+
+**Budget wall-clock for long sim waits:** under headless probe (SwiftShader
+software rendering, no GPU) the sim often runs at ~0.3× real time — a spec
+that waits `simSeconds: 30` can take ~100s of wall clock. That is not a hang:
+give outer timeouts headroom (a full suite with one long survival spec can
+legitimately run 3+ minutes), and where possible prove long-duration rules
+with a declared fixture command (jump the clock/state) plus ONE honest
+end-to-end spec, rather than many real-time waits.
+
+Exit codes: 0 all pass · 1 spec failure (including a `tests/` type error) ·
+2 usage (including ZERO specs — an empty suite never reports green) · 3 the
+page loaded but no debug bridge appeared · 5 the harness itself wedged (the
+wedge watchdog treats a throttled bridge-call heartbeat — printed while
+calls keep flowing, e.g. across many back-to-back `hold()`s in a long
+honest-navigation spec — as liveness, so real progress with sparse stdout
+never false-positives as a wedge).
+
+A spec is plain Playwright with one import:
+
+```ts
+import { test, expect } from '@vgai/probe';
+
+test('boosting the spinner completes a lap', async ({ game }) => {
+  await game.command('spinner.reset');                     // fixture (declared cheat)
+  await game.input.hold('attack', { simSeconds: 4 });      // proof: the honest input path
+  await game.waitFor((s) => (s('spinner') as { laps: number }).laps >= 1,
+    { simSeconds: 10 });
+  await game.events.expect(['spin-lap']);                  // ordered subsequence since test start
+  await game.screenshot('after-boosted-spin');
+});
+```
+
+For a helper function taking the `game` fixture as a parameter, type it with
+the `GameClient` type, exported from `@vgai/probe` for exactly that purpose.
+
+**Fixtures are never proofs (D16).** `game.command(...)` invokes a declared
+cheat — use it to jump to a known starting state, never to demonstrate that
+a feature works. The proof is always the honest path: `game.input.*` drives
+adapter action bindings, while a React-only game uses `game.page(...)` for its
+native DOM keyboard/controls. Assert either through `game.waitFor`
+(durable state) and `game.events.expect` (transient facts). `vgai probe`'s
+pre-boot lint FAILS a spec whose only interactions are commands.
+
+In a long honest-input spec (many `hold()` calls wandering toward several
+targets), assert final/aggregate counters with at-least bounds (`>=`)
+rather than exact equality — honest wandering can legitimately brush a
+background pickup or trigger an incidental event on the way, and an exact
+`toBe` turns that legitimate variance into a flaky failure.
+
+**Budgets are sim-time, never wall-clock.** `waitFor`/`hold` budgets are
+`{ simSeconds }` (or `{ simTicks }`) only; passing `timeout` is a TypeScript
+error AND a runtime throw. Why: probe runs headless Chromium under
+SwiftShader (software rasterization, no GPU), where a frame costs several
+times its real-hardware wall-clock and varies machine to machine — a
+wall-clock budget flakes on slow CI while sim-time measures the game's OWN
+clock, so a slow renderer never fails a correct game. The failure block
+prints sim vs wall elapsed with the ratio so you can tell game-bug /
+budget-too-small-under-SwiftShader / stalled-loop apart at a glance.
+`game.input.hold(action, { simSeconds })` — extra hold time is extra
+distance traveled, not slack; steer with closed-loop `waitFor` checks
+rather than padded holds. Spec files must not call `test.setTimeout(...)` (or
+`test.slow()`) either — `vgai probe`'s pre-boot lint rejects it: the runner
+already disables Playwright's own wall-clock timeout (`timeout: 0`), and a
+per-test wall budget fights the sim clock the same way a raw `timeout` would.
+
+`hold()` resolves after it releases the action. When the evidence must observe
+a transient active-input state or moving pose, use
+`game.input.whileHeld(action, async () => { ... })`; it presses through the
+real input map, runs the callback while still held, and releases in `finally`
+even if an assertion or screenshot throws.
+
+**One registry, three doors.** Whatever a component registers through
+`ctx.debug` (or the react hooks) is visible — same names, same JSON — on
+three surfaces:
+
+| Door | Surface | Talks to |
+| --- | --- | --- |
+| Acceptance specs / `@vgai/live` scripts | `@vgai/probe`'s `game` fixture, or the identical `GameClient` bound by `@vgai/live` (`state`/`command`/`input`/`page`/`waitFor`/`events`) | the EDITOR session's live play mode when one exists (the default — same tab a human is watching), else (specs only, no session) its own probe-booted standalone game page (`window.__vgai`) |
+| CLI / agents | the `vgai play …` op family | the EDITOR session's live play mode |
+| Editor panels | play-mode data/debug panels | the in-process registry directly |
+
+The one remaining asymmetry: only when NO live session exists do committed
+specs fall back to their own probe-booted standalone page — with a session
+open (the common case), specs, `@vgai/live` scripts, and the CLI all talk to
+the SAME editor session's live play mode. (This table enumerates USER
+surfaces; at the transport level the seam's doors are the in-page
+`window.__vgai` bridge and the editor relay — the panels ride the in-process
+path, not a transport.)
+
+**Test in layers — never debug a pure-logic bug through the browser:**
+1. **L1 — logic.** Extract pure models (movement/physics stepping, lap math,
+   world rules) into plain functions and test them headlessly in
+   `tests/logic/` (`npm test`, vitest — no browser, no renderer). Seconds
+   per run; this is where most bugs should be found and fixed. Worked
+   example: `tests/logic/example.test.ts`. Footnote: a clamp/lerp/damping
+   helper can legitimately return `-0` (e.g. `clamp(0, ...)` after a
+   negative overshoot); vitest's `toBe` asserts with `Object.is`, which
+   treats `-0` and `0` as UNEQUAL — assert numeric results with
+   `toBeCloseTo`, or add `+0` to the actual value, rather than chasing a
+   "flaky" failing assertion that is actually a `-0`/`Object.is` mismatch.
+2. **L2 — acceptance.** One focused browser spec per feature, from a known
+   fixture, through `vgai probe`. A feature isn't done until its spec is
+   green — this is the acceptance bar's "bot-proven" evidence.
+3. **L3 — mission.** Long full-run specs (start-to-goal). Only run these
+   when the isolated layers underneath are green — otherwise every failure
+   is ambiguous.
+
+**Events are the flight recorder.** `ctx.debug.emit(name, detail)` is
+tick-stamped and ring-buffered; `game.events.expect([...])` asserts an
+ordered subsequence of events since test start, and the failure block
+replays the actual event window with the first unmatched expectation marked.
+Emit gameplay milestones (`wave-cleared`, `tree-felled`, `goal-passed`) from
+day one — the iteration cycle is: red run → read the failure block →
+reproduce at the LOWEST layer that exhibits it → fix → re-run the one spec
+(`vgai probe -g …`) → re-run the suite. Without the evidence, step two is
+guesswork.
+
+**Two hard-won invariants** (each cost a debugging session to learn):
+- If your bot is a generator/coroutine stepped once per frame, every loop
+  iteration must `yield`. A loop that can re-enter without yielding (e.g.
+  "plan failed → retry") is a synchronous freeze that pins the renderer.
+- Never edit source files watched by a running dev server mid-probe — the
+  hot reload kills the run and the result is garbage either way.
+- If you drive either dev server (`vgai edit`/`npm run dev`, or `npm run
+  game`) with Playwright, use `page.goto(url, { waitUntil: 'load' })`, never
+  `'networkidle'` — the dev server keeps a live SSE/websocket/HMR
+  connection open, so the network never goes idle and `'networkidle'`
+  hangs forever.
+
+**Multiplayer without multiplayer**: N synthetic players in N headless pages
+against your Colyseus room is a real multiplayer session — same input paths,
+same netcode, no humans needed. This is the cheapest way to soak-test rooms.
+For the headless L1 equivalent, `tests/logic/room.test.ts` drives your room
+in-process through `server/loopback.ts` — no ports, no browser, no editor.
+
+### Idioms checklist
+
+The engine-usage doctrine above (GameComponents, HUD/state-bridge, `ctx.debug`
+observability, the `vgai probe`-is-the-one-harness rule, dynamic-import
+Colyseus, cleanup) is collected as a one-page checklist in `IDIOMS.md`, each
+item marked machine-checked or review-only. Run `npm run check-idioms`
+(`--strict` to also fail on the warn-level heuristics) to catch drift —
+e.g. a hand-rolled Playwright boot, a `window.__vgai` reach-in, or a
+`setInterval` polling pump next to `useGameState` — without waiting for a
+human review pass. It's a static scanner, not a substitute for `vgai probe`
+itself.
+
+## Examples Catalog
+
+Nothing example-shaped ships inside this project — every example is a
+standalone project in the vgai monorepo's `examples/<id>/`, with its own
+`src/`, scenes, `vgai.game.json`, and (where multiplayer) `server/`. Get one's
+code by scaffolding it: `npx create-vgai-project <name> --example <id>` (e.g.
+`--example third-person`) — a correctly-rewritten standalone copy. Or open it
+live in the hosted editor at `https://vgai-editor.pages.dev/?project=<id>`
+(read-only; scaffold to keep edits).
+
+**Gameplay examples:**
+- `third-person` — orbit camera, WASD movement, XState animation machine, AI chase
+- `fps` — pointer lock, throwable projectiles, dynamic physics
+- `vehicle` — Rapier raycast-vehicle suspension, steering, chase camera
+- `rts` — top-down camera, box selection, navmesh crowd pathfinding
+- `third-person-arena` — multiplayer tag with AI bots: client-authoritative movement, server-authoritative game state (tag/phases); ships its own `server/`
+- `starfighter` — flight controller with schema-declared tuning fields
+- `ik` — skeletal IK (CCDIKSolver) on a code-built rig
+
+**Scene & technique showcases:**
+- `editor-tutorial` — feature-showcase scene: meshes, materials, lights, physics, particles, audio, bloom
+- `feature-scenes` — six technique scenes in one project: instancing, terrain, ocean, particles, custom water shader, HDR skybox
+- `littlest-tokyo` — GLTF model scene (Draco-compressed; ships its decoder assets)
+- `learn-joints`, `learn-matfiles`, `learn-triggers`, `learn-splines` — one-concept tutorials (physics joints, shared `.mat.json` materials, sensor triggers, spline motion)
+- `theatre-clock-demo` — Theatre.js `getProject`/`.sheet()`/`.object()` driven by the canonical `AnimationClock` (continuous camera/object animation; no renamed Theatre vocabulary)
+- `audio-showcase` — spatial audio (`THREE.PositionalAudio`) and procedural Tone.js music sharing one audio clock/bus
+- `input-showcase` — scalar/Vector2 input actions plus a live rebind panel
+
+Cinematic authoring (Theatre + GSAP + XState + Tone + React HUD/letterbox,
+composed and rendered deterministically) has no standalone `--example` yet —
+see `docs/RECIPES.md` recipe 9 and `packages/engine/e2e/reference-cinematic/`
+for the reference composition, and `vgai render-cinematic --help` for the
+render CLI.
+
+**UI / multi-world examples:**
+- `hp-hud` — a declared React root reading live state with `useGameState`
+- `tri-world` — one manifest, three adapter roots side by side (threejs + pixijs + react)
+
+**Multiplayer note:** this project already ships a generic `server/` (a
+`GameRoom` in `server/rooms/`, registered in `server/rooms.ts`), but the
+Colyseus server is **not** started by `npm run dev`/`npm run game`. Run `npm run server` to
+boot it standalone — it starts `server/main.ts` on `ws://localhost:2567` and
+shuts down cleanly on Ctrl-C. Start it before connecting, or the client will
+fail to connect. (The script runs tsx against `server/tsconfig.json`, not the
+app tsconfig — `@colyseus/schema`'s legacy `@type` decorators need
+`experimentalDecorators`, which only the server tsconfig sets.) The
+`third-person-arena` example (`--example third-person-arena`) ships its own
+richer `server/` (an `ArenaRoom` with tag/phase state) in place of this
+generic one.
+
+## Scene File Format
+
+Entities in `.vscn.json` have these optional fields:
+- `id` — UUID. The **editor** generates one when it creates an entity, and the
+  runtime loader auto-generates a random one for id-less entities at load (so
+  every loaded object carries an entity descriptor and appears in the play-mode
+  hierarchy). But a random id can't be *referenced*: anything targeted from
+  elsewhere (joints, god-rays, etc.) still needs an AUTHORED id.
+- `name` — display name
+- `transform` — `{ position: [x,y,z], rotation: [x,y,z,w], scale: [x,y,z] }`
+- `mesh` — `{ type: 'box'|'sphere'|'plane'|'cylinder'|... }`
+- `material` — `{ type: 'standard'|'physical', color, metalness, roughness, ... }` (inline material)
+- `materialRef` — path to a shared `.mat.json` asset. **Mutually exclusive with `material`** — set one or the other, never both (load-time error).
+- `light` — `{ type: 'directional'|'point'|'spot'|'hemisphere'|'area', ... }`.
+  Light values are native Three.js values, not engine-normalized multipliers:
+  point/spot `intensity` is candela with inverse-square `decay: 2` by default
+  (a value near `1` is candle-scale), while area-light intensity is nit.
+  `distance` limits point/spot range but does not make a low-candela light
+  brighter. An emissive material only makes that mesh appear bright; add a
+  real light when it must illuminate nearby objects. Inspect Play pixels under
+  the authored tone mapping/exposure—visible bulbs are not lighting proof.
+- `camera` — `{ type: 'perspective'|'orthographic', ... }`
+- `physics` — `{ bodyType: 'dynamic'|'fixed'|'kinematic', collider: { type: 'cuboid'|'ball'|'capsule', halfExtents?, radius?, friction?, restitution?, density? }, mass? }`
+
+  **Physics contracts (current):**
+  - Physics entities may be nested under transformed parents: the loader
+    composes the full parent chain and spawns the body at the WORLD
+    transform. One exception, enforced loudly: a `dynamic` body under an
+    ancestor that itself has a `dynamic`/`kinematic` body is a load error
+    (Rapier has no parent/child body relationship).
+  - Collider dimensions (`halfExtents`, `radius`) are authored in local units
+    and **scale with the entity's composed world scale** (per-axis for
+    cuboids; round colliders require uniform scale on their round axes —
+    non-uniform is a loud load error). The editor's collider gizmo renders
+    the same computed dimensions the runtime uses.
+  - Collision events fire for all scene-loaded colliders: solid-solid
+    contacts reach `ctx.collisions.onCollision`; **sensor** colliders
+    additionally dispatch `onTriggerEnter/Exit` on components.
+- `components` — `{ "ComponentName": { prop: value, ... }, ... }` (see Components section above)
+- `children` — nested entity array