@pix3/cli 1.6.4 → 2.0.0-alpha.0

package/kit/files/.claude/skills/pix3-scene-format/reference.md

@@ -1,4 +1,4 @@
-<!-- Pix3 agent kit 1.6.4 — generated from docs/pix3-specification.md ("Scene File Format"). Do not edit: pix3 kit --update regenerates it. -->
+<!-- Pix3 agent kit 2.0.0-alpha.0 — generated from docs/pix3-specification.md ("Scene File Format"). Do not edit: pix3 kit --update regenerates it. -->
 # `.pix3scene` — the engine specification
 
 Excerpts of the engine's specification, as shipped with this CLI. `SKILL.md` beside this file
@@ -11,14 +11,14 @@ layout (`res://` is always relative to the project root). Source paths quoted he
 
 - Declarative: The file describes the composition and structure of the scene, not the process of its creation.
 - Asset Referencing: Assets (models, textures) are not embedded in the file but are referenced via relative paths with a res:// prefix (path from the project root).
-- Flat Asset Layout: a game project keeps one folder per asset type **at its root** — `scenes/`, `sprites/` (images/textures), `models/`, `audio/`, `fonts/`, `spine/` (skeleton + atlas + pages together), `scripts/`, `locales/` — with free subdivision inside (`sprites/ui/…`). There is no `assets/` wrapper folder; the project templates ship this layout and `defaultAssetFolder()` (`src/core/asset-categories.ts`) is the canonical mapping used when the editor creates an asset from a bare file name.
-- SVG textures: an `.svg` works as a `Sprite2D` / `Button2D` texture only when its root `<svg>` carries `xmlns="http://www.w3.org/2000/svg"` and px `width`/`height` (a viewBox alone has no intrinsic size), it is self-contained, and the Blob it is decoded from is typed `image/svg+xml` — every read path therefore types image/audio blobs by extension when the stored type is generic (`CloudProjectCacheService.readBlob`, `PlayableHtmlBuildService.resolveMimeType`). `pix3 validate` checks referenced SVGs (`E_SVG_INVALID`, `E_SVG_NO_SIZE`, `W_SVG_VIEWBOX_ONLY`, `W_SVG_EXTERNAL_REF`).
+- Flat Asset Layout: a game project keeps one folder per asset type **at its root** — `scenes/`, `sprites/` (images/textures), `models/`, `audio/`, `fonts/`, `spine/` (skeleton + atlas + pages together), `scripts/`, `locales/` — with free subdivision inside (`sprites/ui/…`). There is no `assets/` wrapper folder; `pix3 new` creates this layout.
+- SVG textures: an `.svg` works as a `Sprite2D` / `Button2D` texture only when its root `<svg>` carries `xmlns="http://www.w3.org/2000/svg"` and px `width`/`height` (a viewBox alone has no intrinsic size), it is self-contained, and the Blob it is decoded from is typed `image/svg+xml` — the editor types the bytes it reads by extension (`packages/editor-core/src/services/project/file-content-type.ts`) and a build embeds every asset with its type (`packages/vite-plugin/src/files/content-type.ts`). `pix3 validate` checks referenced SVGs (`E_SVG_INVALID`, `E_SVG_NO_SIZE`, `W_SVG_VIEWBOX_ONLY`, `W_SVG_EXTERNAL_REF`).
 - Composition: Complex scenes are assembled from simpler ones by instantiating other scene files.
 - Unambiguous Structure: An explicit children key is used to denote the list of child nodes, which separates the hierarchy from the properties of the node itself.
 - Unique Identification: Every node must have an id field. The value is a short, cryptographically secure unique identifier (similar to Nano ID) to provide a balance between file readability and the absolute reliability of references.
 - Versioned Schema: Each file includes a `version` field; migrations are maintained in the SceneManager and run automatically on load.
 - Conflict Resolution: Instance overrides always win over parent definitions. Duplicate IDs trigger validation errors during import.
-- Forgiving Vocabulary: a `type:` the loader does not know does **not** fail the load — the node is built as a bare `NodeBase` placeholder that does nothing, so a scene written by a newer version (or with a typo) stays openable and editable. Because such a node is otherwise indistinguishable from a working one, it is reported on three surfaces: the renderability lint (`inert-nodes` in `scene_tree` / `game_observe` / play start), the loader diagnostic (`describeUnknownNodeType`, which suggests the nearest known name), and the Scene Tree row, which carries a warn badge and states the reason in its tooltip. `isInertNode` (`packages/pix3-runtime/src/core/renderability-lint.ts`) is the one predicate behind all three.
+- Forgiving Vocabulary: a `type:` the loader does not know does **not** fail the load — the node is built as a bare `NodeBase` placeholder that does nothing, so a scene written by a newer version (or with a typo) stays openable and editable. Because such a node is otherwise indistinguishable from a working one, it is reported on three surfaces: the renderability lint (`inert-nodes`, a warning when play starts and in `pix3_game_run` observations), the loader diagnostic (`describeUnknownNodeType`, which suggests the nearest known name), and the Scene Tree row, which carries a warn badge and states the reason in its tooltip. `isInertNode` (`packages/runtime/src/core/renderability-lint.ts`) is the one predicate behind all three; `pix3 validate` reports the same node as `E_UNKNOWN_NODE_TYPE`.
 
 ## Skinned 2D UI controls
 
@@ -57,13 +57,9 @@ The four `sliceBorderLeft/Right/Top/Bottom` scalars are the same nine-slice inse
 fill; the slider thumb is drawn at its authored size and is never sliced. A fill
 that shrinks with `value` is **re-cut** at the new width, so its end caps keep
 their pixel size. All-zero (the default) is the plain stretch. A sliced skin opts
-out of the 2D quad batcher, because the batcher extracts four *unit* corners, and
+out of the 2D quad batcher, because the batcher extracts four _unit_ corners, and
 is excluded from the pre-launch texture atlas for the same reason.
 
-Sprites for every one of these slots — and the matching insets — can be generated
-and applied without leaving the editor; the files and their manifest are specified
-in **§6.23 UI Kit Assets**.
-
 ```yaml
 - id: 'q7Bd-1mZ_kTn0-Vx4pA'
   type: 'Button2D'
@@ -114,7 +110,7 @@ in **§6.23 UI Kit Assets**.
 A `SpineSkeleton2D` references its Spine export by two `res://` paths — the
 skeleton (`.json` or `.skel`) and the atlas (`.atlas`). The atlas' page images are
 NOT listed: they are named inside the atlas text and resolved relative to it (the
-export asset collector parses `.atlas` files for the same reason). `texture` is an
+build's asset scan, `packages/vite-plugin/src/build/scan.ts`, parses `.atlas` files for the same reason). `texture` is an
 optional single-page override.
 
 ```yaml
@@ -151,14 +147,30 @@ Groups provide runtime categorization for nodes (for example, `enemies`, `ui`, `
 - `removeFromGroup(group)`
 - `isInGroup(group)`
 
-#### 6.19.2 Scene API
-
-`SceneManager` provides group-based queries and invocation:
+A node's groups are its own `groups` set (names trimmed); it is the only membership record —
+nothing indexes it, so a change is seen by the next query.
 
-- `getNodesInGroup(group)` - returns matching nodes in the active scene.
-- `callGroup(group, method, ...args)` - calls matching component methods across grouped nodes.
+#### 6.19.2 Scene API
 
-`callGroup` performs runtime method checks and warns if no callable method is found.
+A script queries and calls groups through `this.scene` (`SceneService`), during play and in the
+exported player alike:
+
+- `getNodesInGroup(group)` - the running scene's nodes in `group`, in tree order (depth-first,
+  a parent before its children, roots in order); empty outside a running game. Read at call
+  time from the nodes' `groups`, so `addToGroup` / `removeFromGroup`, a spawned prefab, a freed
+  node and `changeScene` all show in the next call. Like `findNode`, it walks the running scene
+  only — not the autoloads' hidden root, and not the editor's authored graph (play runs on a
+  clone).
+- `callGroup(group, method, ...args)` - Godot's `call_group`: calls `method(...args)` on every
+  component of every node in the group that has a function of that name, and returns how many
+  calls it made. The node list is taken before the first call. A component without the method
+  is skipped; when the group has nodes but no component has the method, one warning names the
+  group and the method (no throw). An empty group calls nothing, silently.
+
+```ts
+for (const enemy of this.scene.getNodesInGroup('enemies')) enemy.visible = false;
+this.scene.callGroup('enemies', 'onAlarm', 3);
+```
 
 #### 6.19.3 Serialization
 

package/kit/files/.claude/skills/pix3-scripts/SKILL.md

@@ -3,7 +3,7 @@ name: pix3-scripts
 description: How to write a Pix3 game script (scripts/*.ts, `export class X extends Script`, attached as `user:X`) — lifecycle, the required getPropertySchema, config, node lookup, signals, transforms, spawning, input, juice/tweens/audio, 2D physics, scene changes, the built-in core:* components and their config keys (reference.md), and the traps that compile clean and break at runtime. Use BEFORE writing or editing any file in scripts/ or attaching a core: component.
 ---
 
-<!-- Pix3 agent kit 1.6.4 -->
+<!-- Pix3 agent kit 2.0.0-alpha.0 -->
 
 # Writing a script
 
@@ -13,7 +13,8 @@ it. Import only from `@pix3/runtime`, `three`, and other files under the scripts
 against the runtime's declarations (`.pix3/types/`, or your `node_modules` when the project
 has its own `tsconfig.json`); your editor sees the same types through the root `tsconfig.json`.
 
-`reference.md` beside this file has the engine's own API map, the capability catalog and
+`reference.md` beside this file has the rest of the API (wheel and multi-touch input, the full 2D
+physics surface, `registerGameDebug`, cutscenes, multiplayer), the capability catalog and
 **every `core:` component with its config keys and defaults** — reach for a built-in before
 writing a script for the same effect.
 
@@ -130,7 +131,8 @@ before children's.
   `node.position = …` throws at runtime.
 - 2D space: design pixels, origin centre, X right, **Y up**. YAML rotation is degrees;
   `rotation.z` is radians.
-- `visible`, `name`, `id`, `children`, `parentNode`, `findById(id)`, `findByName(name)`,
+- `visible`, `name`, `nodeId` (the scene id; `id` is three.js's number), `children`,
+  `parentNode`, `findById(nodeId)`, `findByName(name)`,
   `adoptChild(child)`, `queueFree()` (safe inside `onUpdate`), `getComponent(Class)`,
   `addComponent(c)`, `removeComponent(c)`.
 - 2D node props as fields: `width`, `height`, `opacity`, `zIndex`, `blendMode`. Assigning
@@ -155,16 +157,17 @@ before children's.
   `node.disconnect('name', this, handler)`. Every handler connected with `this` as the target
   is **auto-disconnected on detach, like own-node signals** — including ones on another node
   (`gameRoot.connect('score', this, this.onScore)`). Window listeners, store subscriptions and
-  timers are still yours to clean up in `onDetach` (see "Hosting an existing game"). Keep the
+  timers are still yours to clean up in `onDetach` ("Hosting an existing game", below). Keep the
   handler in a field (no `.bind(this)`) so an early manual `disconnect` gets the same function.
 - UI controls (`Button2D`, `Slider2D`, `Checkbox2D`, `Joystick2D`, …) emit `pressed` (touch
   went down inside), `released`, `click` (down and up inside — a completed tap),
   `pointerdown`, `pointerup`; `Checkbox2D` also `toggled`; `Label2D` emits
-  `typewriter-complete`. The recipes wire buttons to `pressed` (instant); `click` can be
-  cancelled by sliding off — use it for menus and anything costly.
-- Recipe scripts talk through signals on `game-root` (`touch-scored`, `touch-damaged`,
-  `score-changed`, `lives-changed`, `time-changed`, `game-won`, `game-lost`). Listen to
-  them; add new signal names for new mechanics; never rename existing ones.
+  `typewriter-complete`. Wire game buttons to `pressed` (instant); `click` can be
+  cancelled by sliding off — use it for menus and anything costly (purchases):
+  `button.connect('click', this, this.onBuy)`.
+- Scripts talk through signals on a shared node such as `game-root` (`score-changed`,
+  `lives-changed`, `game-won`, `game-lost`, …). Listen to the ones that exist; add new signal
+  names for new mechanics; never rename existing ones.
 
 ## `this.scene`
 
@@ -175,7 +178,8 @@ before children's.
 - Spawn: `const n = await scene.instantiate('res://scenes/prefabs/x.pix3scene', { parent, instanceId })`
   (`parent` = node | query; prefab = a scene file with one root). Despawn: `n.queueFree()`.
 - Scene change: `await scene.changeScene('res://scenes/menu.pix3scene', { transition: 'fade' | 'none', durationSec: 0.3, onLoaded })`
-  (`durationSec` is each of fade-out and fade-in).
+  (`durationSec` is each of fade-out and fade-in). State that must survive it is an autoload:
+  `scene.getAutoload(GameState)` (recipe: `pix3-scene-format/project-files.md` → "An autoload").
 - Time: `scene.time.hitstop(ms)` — no options; only on a contact START, never per frame.
   `scene.time.slowMotion(scale, { durationMs, blendMs })` — both real-time ms; no `durationMs`
   = until `scene.time.reset()`.
@@ -201,18 +205,18 @@ before children's.
   Sound without the editor: `pix3 sfx coin` writes `audio/coin.wav` (presets `coin`, `jump`,
   `hit`, `explosion`, `powerup`, `click`, or words: `pix3 sfx "short high coin pickup" --out audio/pickup.wav`;
   `--seed <n>` for a variation) — offline, no key; `.wav` plays everywhere `.ogg`/`.mp3` do.
-  Sound cannot be proven audible from the live channel: the browser only starts Web Audio after
-  a real user gesture, and `game_input`'s synthetic taps/keys are not one. Report a sound as
+  Sound cannot be proven audible from the bridge: the browser only starts Web Audio after
+  a real user gesture, and a synthetic click from chrome-devtools-mcp is not one. Report a sound as
   "code path verified, audibility not" and ask the human to listen.
 - Overlap queries without physics response: `scene.collision2d.overlapPoint(x, y, group?)`,
   `overlapCircle(x, y, r, group?)`, `overlapRect(cx, cy, w, h, group?)`, `raycast(…)` over
-  nodes carrying `core:Hitbox2D` (the tapper/arena recipes use this).
+  nodes carrying `core:Hitbox2D` (tappers, collectors, dodgers).
 - 2D physics with response: `core:PhysicsBody2D` + `core:Collider2D` on the same node;
   `scene.physics2d.getBody(node)` → `setVelocity`, `applyImpulse`, `teleport`. Never
-  hand-write a 2D solver, never import rapier for 2D. (The bouncer recipe runs its own
-  swept solver in `BallBody.ts` — do not add engine physics to its ball.)
+  hand-write a 2D solver, never import rapier for 2D. (A game that already runs its own
+  solver keeps it — do not add engine physics on top of it.)
 - Intents: `scene.commands.register('name', handler, { description })`, `dispatch(name)`.
-  The recipes register theirs and publish state with `registerGameDebug` in `GameRules` —
+  Register one per game and publish state with `registerGameDebug` from one rules script —
   when you add a mechanic, add its field to that snapshot instead of registering a second one.
 
 ## `this.input`
@@ -223,10 +227,10 @@ before children's.
   `scene.getPointer2DWorldPosition()` for world), `input.isPointerOverUI(pointerId)`,
   `input.getButton(name)`, `input.getAxis(name)`.
 - Keys held: `input.getButton('Key_ArrowLeft')`, `getButton('Key_D')` — `Key_` + the
-  `KeyboardEvent.code` (this is what the recipes' controllers use). In `input.keyEvents`
+  `KeyboardEvent.code` (the form player controllers use). In `input.keyEvents`
   compare `event.code` (`'KeyW'`, `'ArrowUp'`, `'Space'`) — case-sensitive.
 
-## Hosting an existing game (not a recipe)
+## Hosting an existing game
 
 - **Use the game's own channel.** Before wiring a script, find how the game talks:
   `grep -rn "CustomEvent\|dispatchEvent\|addEventListener\|subscribe(\|EventTarget\|emit(" src scripts`.
@@ -259,23 +263,29 @@ before children's.
   (or on any node the game positions itself) is overwritten every frame and never shows. Use the
   game's own shake (`grep -rn "shake" src scripts`) when it has one; the same goes for its own
   sound and tween helpers.
-- The project's own `AGENTS.md` wins on process (planning first, where config goes); this kit
-  wins on Pix3 facts (YAML, runtime API, `pix3 check`).
 
 ## Traps (compile clean, break at runtime)
 
 - Assigning `position` / `rotation` / `scale` throws. Mutate them.
 - A component that throws in `onStart` / `onUpdate` is **auto-disabled** and the game keeps
   running — the thing just freezes. Guard lookups (`if (!node) { console.warn(...); return; }`).
-  With the live channel, `read_errors` after a run shows it; without, tell the human to look
-  at the editor's console.
+  `pix3_errors` right after starting play (or `pix3 smoke`'s `E_SMOKE_SCRIPT`) shows the throw —
+  read it before judging anything else.
 - `as any` on `this.node` hides exactly the error above, and from `pix3 check`. Use
   `instanceof` narrowing.
 - Hitstop every frame of an overlap freezes the game — edge-trigger it.
 - A hidden `UIControl2D` takes no input; `onUpdate` still runs on hidden nodes.
 - `getComponent('user:X')` is wrong — pass the class.
-- Ending a run belongs to the recipe's `GameRules`: call its `finish(won)`; do not show the
-  result overlay yourself (RETRY would stay disabled).
+- `event.key` depends on the layout and on Shift — match `event.code`.
+- **Moves the wrong way** (sideways, backwards) is a math bug, and flipping signs does not
+  converge. With world +Y up, `rotation.z` turns the node's local +Y (its nose) to
+  `(-sin θ, cos θ)`: forward is `vx = -Math.sin(rot) * speed`, `vy = Math.cos(rot) * speed`, and
+  aiming the nose along `(dx, dy)` is `rotation.z = Math.atan2(-dx, dy)`.
+- **A button does nothing**: something must `connect` to its signal (`pressed` / `click`) on the
+  node id the scene really has — check the id in `pix3 tree`, then that the script carrying the
+  handler is attached and `enabled`.
+- Ending a run belongs to the one script that owns the rules: call it; do not show the result
+  overlay from a second place.
 
 ## Known gaps
 

package/kit/files/.claude/skills/pix3-scripts/reference.md

@@ -1,22 +1,21 @@
-<!-- Pix3 agent kit 1.6.4 — generated from docs/nodes-and-systems.md, src/services/agent/agent-skills/engine-api-map.md and the runtime's component registry. Do not edit: pix3 kit --update regenerates it. -->
+<!-- Pix3 agent kit 2.0.0-alpha.0 — generated from docs/nodes-and-systems.md, packages/cli/kit-includes/engine-api-map.md and the runtime's component registry. Do not edit: pix3 kit --update regenerates it. -->
 # Script API reference
 
-Generated from the engine's own documentation and code. Grep a heading instead of reading it
-whole. Tool names the in-editor agent uses appear in places: `add_component` /
-`set_component_property` = edit the scene YAML's `components:`; `list_component_types` = the
-"`core:` components" section at the end of this file; `engine_search` / `engine_read` do not
-exist for you — the runtime's declarations are in `.pix3/types/@pix3/runtime/` (or in
-`node_modules/@pix3/runtime` when the project has its own `tsconfig.json`). Source paths quoted here (`src/…`, `packages/…`) are files of the Pix3 engine repository, not of this project.
+Generated from the engine's own documentation and code; `SKILL.md` beside it is the practical
+part. Grep a heading instead of reading it whole. The runtime's declarations are in
+`.pix3/types/@pix3/runtime/` (or `node_modules/@pix3/runtime` when the project has its own
+`tsconfig.json`). Source paths quoted here (`src/…`, `packages/…`) are files of the Pix3 engine
+repository, not of this project.
 
 ## The surface a `Script` sees
 
 Inside any `Script` subclass:
 
-- `this.node` — the owning `NodeBase` (transform, `visible`, `getComponent`, `addComponent`, `connect`/`emit`, `findById`/`findByName`/`findByPath`, `children`, `parentNode`). `getComponent<T>(type: new (...args) => T): T | null` takes the component **class**, not a string ID — `node.getComponent(CarController)`, importing the class by relative path (`./CarController`). There is no string-based lookup (`getComponent('user:CarController')` fails); `user:*` IDs are for `add_component`/scene YAML only. To fetch by hand: `node.components.find(c => c instanceof CarController)`.
-- `this.scene` — the `SceneService` (all of §4's `scene.*` APIs, plus `getActiveCamera()`, `getActiveCamera2D()`, `findNode(query)`, `getRootNodes()`, `getViewportInfo()`/`onViewportChanged()`/`isPortrait()`, `raycastViewport(nx,ny)`, `getAudioService`/`getAssetLoader`/`getResourceManager`/`getECSService`, plus `network` and `netNodes` for multiplayer, and `commands` for named game intents). May be `undefined` in some editor previews — guard it.
+- `this.node` — the owning `NodeBase` (transform, `visible`, `getComponent`, `addComponent`, `connect`/`emit`, `findById`/`findByName`/`findByPath`, `children`, `parentNode`). `getComponent<T>(type: new (...args) => T): T | null` takes the component **class**, not a string ID — `node.getComponent(CarController)`, importing the class by relative path (`./CarController`). There is no string-based lookup (`getComponent('user:CarController')` fails); `user:*` IDs are for scene YAML only. To fetch by hand: `node.components.find(c => c instanceof CarController)`.
+- `this.scene` — the `SceneService` (all of §4's `scene.*` APIs, plus `getActiveCamera()`, `getActiveCamera2D()`, `findNode(query)`, `getRootNodes()`, `getNodesInGroup(group)` / `callGroup(group, method, ...args)` for node groups (spec §6.19), `getViewportInfo()`/`onViewportChanged()`/`isPortrait()`, `raycastViewport(nx,ny)`, `getAudioService`/`getAssetLoader`/`getResourceManager`/`getECSService`, plus `network` and `netNodes` for multiplayer, `commands` for named game intents, and `getAutoload(nameOrClass)` for the project's autoload singletons, §6.17 of the spec). May be `undefined` in some editor previews — guard it.
 - `this.input` — the `InputService` (§4 Input).
 - `this.findNode(query)` — resolve another node by id / name / slash-path, or `null` if absent (`get_node_or_null`).
-- `this.getNode(query)` — same lookup but **throws** if the node is missing (`get_node`). In the in-editor code editor the argument autocompletes to the node names/paths of the open scenes and the return type is the exact node type (`this.getNode('Hero')` → `Sprite2D`), à la Godot's `$Node` / WPF `x:Name`. Any other string resolves to `NodeBase`, so a script reused in a scene that lacks the name still type-checks — the names are hints, never constraints. (Typed names come from the editor augmenting `SceneNodeNames`; it's empty in exported games, where only `getNode<T>(query)` applies.)
+- `this.getNode(query)` — same lookup but **throws** if the node is missing (`get_node`); `getNode<T>(query)` types the result.
 
 **Lifecycle:** `onAttach(node)` → `onStart()` (first frame) → `onUpdate(dt)` (every
 frame, `dt` is scaled game time) → `onDetach()`. Define `static getPropertySchema()`
@@ -51,154 +50,82 @@ you never clone textures yourself. Author the region once and drive it from
 throwing `tickEditorPreview` disables the component and surfaces the error like a
 play-mode hook, so the editor keeps running.
 
-## Engine API map
-
-### A `Script`
-
-- Lifecycle: `onAttach(node)` → `onStart()` (first frame) → `onUpdate(dt)` (scaled seconds;
-  frozen by hitstop) → `onDetach()`. Defaults in the constructor's `this.config = {…}`;
-  `static getPropertySchema()` exposes them to the inspector / `set_component_property`.
-- `this.node` (owner `NodeBase`), `this.scene` (`SceneService`, guard for `undefined` in
-  editor previews), `this.input` (`InputService`), `this.findNode(q)` (id / name / path →
-  node or null), `this.getNode(q)` (throws when missing).
-- Reach another script: `import { Other } from './Other'; this.node.getComponent(Other)` —
-  the class, never the `user:Other` string.
+## Engine API map — beyond `SKILL.md`
 
 ### Nodes
 
-- Transform is three.js and **read-only by reference**: `node.position.set(x, y, 0)`,
-  `node.position.x += dx`, `node.rotation.z = radians`, `node.scale.set(s, s, 1)`. Never
-  assign `node.position = …`.
-- `visible`, `name`, `id`, `children`, `parentNode`, `findById(id)`, `findByName(name)`,
-  `adoptChild(child)` (runtime parenting), `queueFree()` (safe inside `onUpdate`; use
-  `dispose()` only outside the tick), `getComponent(Class)`, `addComponent(c)`,
-  `removeComponent(c)`.
-- Signals: `node.emit(name, ...args)`, `node.connect(name, target, fn)`,
-  `node.disconnect(name, target, fn)`. A script's handlers (`target === this`) are
-  auto-disconnected on detach — on its own node and on any other node it connected to.
-  Window listeners, store subscriptions and timers are still yours to clean up.
-  **UI controls emit:** every `UIControl2D` (`Button2D`, `Slider2D`, `Checkbox2D`, `Joystick2D`,
-  `InventorySlot2D`, `ScrollContainer2D`) → `'pressed'`, `'released'`, `'click'` (a completed
-  tap — wire buttons to THIS), `'pointerdown'`, `'pointerup'`; `Checkbox2D` / `InventorySlot2D`
-  also `'toggled'`; `Label2D` → `'typewriter-complete'`. Read a control's value from its
-  properties (`Slider2D.value`, `Checkbox2D.checked`) inside the handler.
-- **Node2D** adds design-pixel space (origin centre, X right, **Y up**): `width`, `height`,
-  `opacity` (0..1), `zIndex` (higher draws on top; ties = tree order, later sibling on top),
-  `blendMode` (`normal | additive | multiply | subtract` — `additive` for glow/VFX), anchored
-  `layout`. Construct at runtime with the same props the scene YAML uses:
-  `new ColorRect2D({ id, width, height, color })`, `new Sprite2D({ id, texturePath:
-  'res://sprites/ph-circle.png', width, height })`, `new Label2D({ id, label, labelFontSize,
-  labelColor })`, `new Group2D({ id, width, height })`, then `parent.adoptChild(node)`.
+- `queueFree()` is safe inside `onUpdate`; `dispose()` only outside the tick.
+- Every `UIControl2D` (`Button2D`, `Slider2D`, `Checkbox2D`, `Joystick2D`, `InventorySlot2D`,
+  `ScrollContainer2D`) emits `'pressed'`, `'released'`, `'click'`, `'pointerdown'`,
+  `'pointerup'`; `Checkbox2D` / `InventorySlot2D` also `'toggled'`. Read a control's value from
+  its properties (`Slider2D.value`, `Checkbox2D.checked`) inside the handler.
+- Constructed at runtime with the scene YAML's property names, a `Sprite2D` too:
+  `new Sprite2D({ id, texturePath: 'res://sprites/ph-circle.png', width, height })`.
 - 2D node types: `ColorRect2D`, `Sprite2D`, `TiledSprite2D`, `AnimatedSprite2D`, `Group2D`,
-  `Label2D` (`label`, `labelFontSize`, `labelColor`, `glowColor`/`glowStrength`,
-  `outlineColor`/`outlineWidth`), `Button2D`, `Slider2D`, `Checkbox2D`, `Bar2D`, `Joystick2D`,
-  `InventorySlot2D`, `ScrollContainer2D`, `Camera2D`, `CanvasLayer2D` (HUD layer, drawn after
-  post-fx, never blooms), `SpineSkeleton2D`, `Layout2D`.
+  `Label2D`, `Button2D`, `Slider2D`, `Checkbox2D`, `Bar2D`, `Joystick2D`, `InventorySlot2D`,
+  `ScrollContainer2D`, `Camera2D`, `CanvasLayer2D` (HUD layer, drawn after post-fx, never
+  blooms), `SpineSkeleton2D`.
 - 3D node types: `Node3D`, `Camera3D`, `VirtualCamera3D`, `GeometryMesh`, `MeshInstance`,
   `InstancedMesh3D`, `Sprite3D`, `AnimatedSprite3D`, `Particles3D`, lights (`Ambient`,
   `Hemisphere`, `Directional`, `Point`, `Spot`), `PostProcess` (bloom / vignette /
   chromatic aberration; `affect2D: true` for 2D scenes), `AudioPlayer`.
-- Shader effects on a 2D node: `effects: [{ type: 'core:tint', params: { color, amount } }]`
-  (also `core:adjust`, `core:grayscale`) — the way a near-white placeholder takes a colour.
 
 ### `this.scene`
 
-- Lookup: `findNode(q)`, `findNodeById`, `findNodeByName`, `findNodeByPath`, `getRootNodes()`,
-  `getActiveCamera()`, `getActiveCamera2D()`, `getViewportInfo()`, `isPortrait()`.
-- **Pointer in 2D world space:** `scene.getPointer2DWorldPosition()` → `Vector2 | null`
-  (design pixels, Y up; the primary finger), `getPointer2DWorldPosition(pointerId)` for one
-  finger (null once it is up). Godot's `get_global_mouse_position()`.
-- Spawning: `await scene.instantiate('res://prefabs/x.pix3scene', { parent: 'container' })`
-  → the new node (prefab = a `.pix3scene` with one root). Despawn with `node.queueFree()`.
-- Scenes & transitions: `await scene.changeScene('res://scenes/menu.pix3scene', {
-  transition: 'fade' | 'none', durationSec: 0.3 })`; `scene.fadeToBlack(sec, onDone?)`,
+- Cameras: `getActiveCamera()`, `getActiveCamera2D()`. `getPointer2DWorldPosition(pointerId)`
+  is null once that finger is up (Godot's `get_global_mouse_position()` for the primary one).
+- Autoloads by name too: `scene.getAutoload<GameState>('GameState')`.
+- Groups (a node's `groups: [enemies]` in the scene, `node.addToGroup('enemies')` at run time):
+  `scene.getNodesInGroup('enemies')` lists the running scene's members in tree order;
+  `scene.callGroup('enemies', 'onAlarm', 3)` calls that method on every component that has it
+  (returns the count, warns once when none has it).
+- Real-time overlays that survive hitstop: `scene.fadeToBlack(sec, onDone?)`,
   `scene.fadeFromBlack(sec, onDone?)`, `scene.switchCameraWithFade(cameraId, outSec, inSec,
-  onDone?)`; `scene.flash({ color, intensity, durationSec })`. Real-time overlays — they
-  survive hitstop.
-- Time: `scene.time.hitstop(ms)` (edge-triggered — on a contact START, never per frame),
-  `scene.time.slowMotion(scale, { durationMs, blendMs })`, `setScale`, `reset`, `scale`,
-  `isFrozen`.
-- **Juice (`scene.juice`)** — one-liners, call them WITH the mechanic: `shake(target, {
-  amplitude: 8, frequency: 24, duration: 0.35, decay: 1.5 })`, `punchScale(target, { amount: 0.3,
-  duration: 0.35, vibrato: 3 })`, `popIn(target, { from: 0, duration: 0.4, easing: 'backOut' })`
-  (these three take `duration`, not `durationSec`), `flash({ color: '#ffffff', intensity: 1,
-  durationSec: 0.2 })`, `burst(anchor, { count: 14,
-  speed: 260, spread: 2π, direction, lifeSec: 0.5, color | colors: [], sizePx: 10, gravityY:
-  -600, fadeOut: true, additive: true, zIndex })`, `floatText('+25', { at, color,
-  fontSizePx: 28, driftPx: 60, durationSec: 0.8, glow })`. `target` = node | node query |
-  `'camera'` / `'camera2d'`; `anchor` = node | query | `{ x, y }` 2D world point. Presets as
-  components: `core:BurstOnSignal`, `core:SfxOnSignal`, `core:Shake`, `core:PunchScale`,
-  `core:PopIn`, `core:Fade`.
-- **Tweens (`scene.tween`)** — Godot-style, on scaled time: `scene.tween.to(target, props, {
-  durationSec: 0.3, ease: 'cubicOut', delaySec, yoyo, repeat (-1 = forever), onUpdate,
-  onComplete })` → `{ cancel(), finished: Promise<'completed' | 'cancelled'>, isRunning }`.
-  `props` for a node: `x`, `y`, `position: {x, y}`, `scale` (number = uniform, or `{x, y}`),
-  `rotation` (radians), `opacity`, `width`, `height`, or any numeric dotted path; for a plain
-  object every key is a dotted path. `fadeIn(node, sec)`, `fadeOut(node, sec, { hide: true })`,
-  `crossFade(from, to, sec)` (state/panel switches — the in-scene counterpart of
-  `changeScene`'s fade), `killAll(target?)`. Use these instead of hand-lerping in `onUpdate`.
-- **Trail (`scene.juice.trail`)**: `scene.juice.trail(node, { lifeSec: 0.35, widthPx: 14,
-  color | colors: [], additive: true, zIndex, maxPoints: 48 })` → a fading ribbon that follows
-  the node (a ball, a projectile); `trail.stop()` lets it fade out; freeing the node frees it.
-- **Audio (`scene.audio`)**: `sfx(preset, { volume, pitch })` — procedural, no asset; presets
-  `tap | score | bounce | explosion | powerup | win | lose | laser | tick`;
-  `await play('res://sfx/hit.ogg', { bus: 'sfx', pitchVariation: 0.1, volumeVariation: 0.1 })`
-  for an authored clip; `setBusVolume(bus, v, fadeSec)`, `applySnapshot(name)`, `stopAll()`.
-- **2D physics (`scene.physics2d`)** — the built-in rigid-body solver; never hand-write one,
-  never import rapier for 2D. Author Unity-style: `core:PhysicsBody2D` (`static | kinematic |
-  dynamic`, `mass`, `restitution`, `friction`, `linearDamping`, `fixedRotation`, `bullet`,
-  `emitContacts`) **and** `core:Collider2D` (`rect | circle | polygon | capsule`, `isSensor`,
-  `group`) on the same node; a `core:Collider2D` alone is static geometry. Gravity is
-  negative Y (`core:PhysicsWorld2D` on the root or `scene.physics2d.setGravity(0, -1800)`;
-  top-down = `(0, 0)`). From a script: `const body = scene.physics2d.getBody(node)` →
-  `setVelocity(vx, vy)`, `applyImpulse(ix, iy)`, `applyForce`, `teleport(x, y, rot?)`, `wake()`,
-  `velocityX/Y`, `isSleeping`; queries `raycast(...)`, `overlapCircle(...)`,
-  `overlapRect(...)`, `moveAndSlide(...)`; signals on the node: `body-entered` /
-  `body-exited` (sensors), `contact-started` / `contact-ended` (with `emitContacts`).
-  Joints: `core:RevoluteJoint2D`.
-- 2D overlap-only queries (no response): `scene.collision2d.overlapPoint(x, y, group?)`,
-  `overlapCircle(x, y, r, group?)`, `overlapRect(cx, cy, w, h, group?)`, `raycast(x1, y1, x2,
-  y2, group?)` over nodes carrying `core:Hitbox2D`.
-- Game intents: `scene.commands.register(name, handler, { description })`,
-  `dispatch(name, args)`, `list()`, `log` — how tests and the menu drive the game without
-  clicking.
-- Debug surface for `game_observe` / `game_run`: `import { registerGameDebug } from
-  '@pix3/runtime'`; in `onStart`: `this.disposeDebug = registerGameDebug({ name, version: 1,
-  snapshot: () => ({ …JSON-safe state… }), inspect: (query, args) => …, action: (name, args)
-  => … })`, call the returned disposer in `onDetach`. Global and last-wins — only the running
-  scene's flow/rules script registers one; recipes already do (extend theirs, do not add a
-  second).
-- Cutscenes: `scene.cutscene.playCinematic(id, {…})`; camera blends via `core:CameraBrain`
-  + `VirtualCamera3D`.
+  onDone?)`, `scene.flash({ color, intensity, durationSec })`.
+- Time: `scene.time.setScale`, `reset`, `scale`, `isFrozen` beside `hitstop` / `slowMotion`.
+- Juice presets as components: `core:BurstOnSignal`, `core:SfxOnSignal`, `core:Shake`,
+  `core:PunchScale`, `core:PopIn`, `core:Fade`.
+- Tweens: `finished` is a `Promise<'completed' | 'cancelled'>`; `props` may also be `scale` as a
+  number (uniform) or `{x, y}`, or any numeric dotted path; on a plain object every key is a
+  dotted path. `crossFade` is the in-scene counterpart of `changeScene`'s fade (state and panel
+  switches). A trail is freed with its node.
+- Audio: `setBusVolume(bus, v, fadeSec)`, `applySnapshot(name)`, `stopAll()`.
+- **2D physics (`scene.physics2d`)**: `core:PhysicsBody2D` (`static | kinematic | dynamic`,
+  `mass`, `restitution`, `friction`, `linearDamping`, `fixedRotation`, `bullet`, `emitContacts`)
+  **and** `core:Collider2D` (`rect | circle | polygon | capsule`, `isSensor`, `group`) on the
+  same node; a `core:Collider2D` alone is static geometry. Gravity is negative Y
+  (`core:PhysicsWorld2D` on the root or `scene.physics2d.setGravity(0, -1800)`; top-down =
+  `(0, 0)`). A body: `applyForce`, `wake()`, `velocityX/Y`, `isSleeping` beside `setVelocity`,
+  `applyImpulse`, `teleport(x, y, rot?)`; queries `raycast(...)`, `overlapCircle(...)`,
+  `overlapRect(...)`, `moveAndSlide(...)`; signals on the node: `body-entered` / `body-exited`
+  (sensors), `contact-started` / `contact-ended` (with `emitContacts`). Joints:
+  `core:RevoluteJoint2D`.
+- Game intents: `scene.commands` also has `list()` and `log` — how tests and the menu drive the
+  game without clicking.
+- The debug surface `pix3_game_run`'s `gameState` predicates read: `import { registerGameDebug }
+  from '@pix3/runtime'`; in `onStart`: `this.disposeDebug = registerGameDebug({ name, version: 1,
+  snapshot: () => ({ …JSON-safe state… }), inspect: (query, args) => …, action: (name, args) =>
+  … })`, call the returned disposer in `onDetach`. Global and last-wins — only the running
+  scene's flow/rules script registers one (extend it, do not add a second).
+- Cutscenes: `scene.cutscene.playCinematic(id, {…})`; camera blends via `core:CameraBrain` +
+  `VirtualCamera3D`.
 - Multiplayer: `scene.network`, `scene.netNodes`, `core:NetworkedNode`,
   `core:ReplicatedTransform` (only when the brief says multiplayer).
 
 ### `this.input`
 
-- Per frame: `input.pointerEvents` → `{ type: 'down' | 'move' | 'up' | 'cancel', pointerId,
-  x, y }[]` (`cancel` is never a completed tap); `input.keyEvents`; `input.wheelDelta` (plain
-  scroll wheel only); `input.wheelZoomDelta` (Ctrl/⌘ + wheel and trackpad pinch — use it for
-  camera zoom, it is excluded from `wheelDelta`); `input.wheelModifiers` (`{ ctrl, meta, shift,
-  alt }`). The canvas already `preventDefault()`s every wheel event, so ctrl-wheel never zooms the page.
-- Polled: `input.isPointerDown` (any finger), `input.pointerPosition` (primary finger,
-  canvas space — convert with `scene.getPointer2DWorldPosition()`), `input.getActivePointers()`,
-  `input.getPointer(id)`, `input.pointerDownCount`, `input.isPointerOverUI(pointerId)` (gate
-  gestures on THIS, not on `isHoveringUI`), `input.getButton(name)` / `getAxis(name)`
-  (`Action_Primary`, arrows / WASD axes), `lock()` / `unlock()`.
-- Keyboard: compare `event.code` (`'KeyW'`, `'ArrowUp'`), case-sensitive.
-- A tap-to-place mechanic is: on a `'down'` event, `scene.getPointer2DWorldPosition(ev.pointerId)`,
+- Wheel: `input.wheelDelta` (plain scroll wheel only); `input.wheelZoomDelta` (Ctrl/⌘ + wheel
+  and trackpad pinch — use it for camera zoom, it is excluded from `wheelDelta`);
+  `input.wheelModifiers` (`{ ctrl, meta, shift, alt }`). The canvas already `preventDefault()`s
+  every wheel event, so ctrl-wheel never zooms the page.
+- Fingers: `input.getActivePointers()`, `input.getPointer(id)`, `input.pointerDownCount`. Gate
+  gestures on `input.isPointerOverUI(pointerId)`, not on `isHoveringUI`.
+- Actions: `getButton('Action_Primary')`, the arrows / WASD axes of `getAxis(name)`;
+  `lock()` / `unlock()`.
+- A tap-to-place mechanic: on a `'down'` event, `scene.getPointer2DWorldPosition(ev.pointerId)`,
   convert to the board's local space (`board.worldToLocal` or subtract the board's world
   position), place the node, `scene.juice.burst({ x, y })`, `scene.audio.sfx('tap')`.
 
-### Traps
-
-- Assigning `position` / `rotation` / `scale` throws — mutate them.
-- A component that throws in `onStart` / `onUpdate` is auto-disabled and the game keeps
-  running — `read_errors` after `play_start` is the only way to see it.
-- `this.node as any` disables exactly the check that would have caught the above.
-- Hitstop every frame while an overlap lasts freezes the contact forever — edge-trigger it.
-- A hidden `UIControl2D` takes no input; `tick` still runs on hidden nodes.
-
 ## Capability catalog — nodes
 
 Add via the editor **Create** menu / `Create*Command`, or author in `.pix3scene`
@@ -241,7 +168,7 @@ tables: node-types-reference.md.
 }
 ```
 
-**Character with variants/states (weapon skins, outfits)** — one `.pix3anim` whose clips are named `<variant>.<state>` (`sword.idle`, `sword.attack`, `bow.idle`, …; a clip without the separator is a variant-less state such as `die`), an `AnimatedSprite2D` as the prefab root (`sizeMode: native` — every frame carries `sourceSize`; the frame `anchor` at the feet, so the node's position is where the character stands) and **`core:CharacterVisual2D`** on that same node (`variant`, `state`, `separator`, optional `spriteNodeId`; empty = the host itself, else its first `AnimatedSprite2D` child). Keep the sprite as the root: selecting the character then selects the drawn quad, and the viewport frames the visible art and marks the pivot at the node position — a `Group2D` wrapper frames a centred box that the frame anchor pushes off the art. Game code says `character.playState('attack', { restart: true })` and `character.setVariant('bow')` (keeps the state, restarts its clip) and never spells a clip name; both return `false` for a pair the resource lacks, no hidden fallback. A finished one-shot holds its last frame and the root emits **`state-finished`** `(state, variant)` — the component adds no movement, physics, AI or automatic transitions. `getVariants()` / `getStates(variant?)` read the vocabulary off the clip names. This is Unity's Sprite Library categories/labels + Sprite Resolver, not an AnimationTree. `compileCharacter` (`src/services/library/character-compiler.ts`) emits exactly this shape from grouped frame files — the Store's `character2d` asset kind — as a managed sprite folder (`sprites/<slug>/<slug>.pix3anim` + `<variant>_<state>_<nnnn>.png`) plus `prefabs/<Name>.pix3scene`; pass `anchor` (y from the top) at the feet row so the node's position is where the character stands — the default is the canvas centre.
+**Character with variants/states (weapon skins, outfits)** — one `.pix3anim` whose clips are named `<variant>.<state>` (`sword.idle`, `sword.attack`, `bow.idle`, …; a clip without the separator is a variant-less state such as `die`), an `AnimatedSprite2D` as the prefab root (`sizeMode: native` — every frame carries `sourceSize`; the frame `anchor` at the feet, so the node's position is where the character stands) and **`core:CharacterVisual2D`** on that same node (`variant`, `state`, `separator`, optional `spriteNodeId`; empty = the host itself, else its first `AnimatedSprite2D` child). Keep the sprite as the root: selecting the character then selects the drawn quad, and the viewport frames the visible art and marks the pivot at the node position — a `Group2D` wrapper frames a centred box that the frame anchor pushes off the art. Game code says `character.playState('attack', { restart: true })` and `character.setVariant('bow')` (keeps the state, restarts its clip) and never spells a clip name; both return `false` for a pair the resource lacks, no hidden fallback. A finished one-shot holds its last frame and the root emits **`state-finished`** `(state, variant)` — the component adds no movement, physics, AI or automatic transitions. `getVariants()` / `getStates(variant?)` read the vocabulary off the clip names. This is Unity's Sprite Library categories/labels + Sprite Resolver, not an AnimationTree. **`pix3 character-compile <spec.yaml>`** (`packages/cli/src/character/`) emits exactly this shape from frame PNGs named in a small spec (`clips: [{ variant, state, frames | sequence, fps?, loop? }]`) — a managed sprite folder (`sprites/<slug>/<slug>.pix3anim` + `<variant>_<state>_<nnnn>.png`, the frames copied in) plus `scenes/prefabs/<Name>.pix3scene`; pass `anchor` (y from the top) at the feet row so the node's position is where the character stands — the default is the canvas centre. It never overwrites a file with other content without `--force`, and `--dry-run` shows the plan.
 
 **Spritesheet mode** instead: set top-level `texturePath` and give each frame a UV rect `offset:{x,y}` + `repeat:{x,y}` (these default to 0 → sample nothing, so they're required here). Frames may carry `durationMultiplier` and `events:[{signal,args}]` (fired on play-driven frame entry). Node wiring: `type: AnimatedSprite2D`, properties `animationResourcePath`, `currentClip`, `isPlaying`, `freeOnFinish` (one-shot self-destruct), `width`/`height`, `anchor`, `sizeMode`. First spawn of a runtime-instantiated clip warms its texture cache; if the first play must be pixel-perfect, spawn one invisible warm-up at level start. Authoring GUI: the editor's **Sprite Editor** produces the same file — one shell (canvas + clips rail + frame timeline) that edits both a bare image and a `.pix3anim`; selecting a frame binds the canvas to that frame's texture, and crop / rotate / flip / background-removal / generation write straight back into the frame.
 
@@ -302,7 +229,7 @@ cost is per skeleton per frame, so budget dozens, not hundreds. Full property ta
 Attach in the inspector or in YAML `components:`. These are the pre-built,
 designer-facing behaviors — prefer them over writing a script for the same
 effect. Registered in
-packages/pix3-runtime/src/behaviors/register-behaviors.ts.
+packages/runtime/src/behaviors/register-behaviors.ts.
 
 | Component id               | Does                                                                                                                                        |
 | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -341,7 +268,7 @@ so a keyframe **event track** or a script `emit()` can fire them.
 (3D-only), `core:uv-scroll`, `core:flash`, `core:adjust`
 (brightness/contrast/saturation), `core:grayscale`, `core:tint`. Params are
 keyframe-animatable. See
-packages/pix3-runtime/src/shader-effects/.
+packages/runtime/src/shader-effects/.
 
 ## `core:` components — every config key