incanto 0.1.0

package/skills/incanto-physics-and-input.md

@@ -0,0 +1,164 @@
+---
+name: incanto-physics-and-input
+description: Incanto physics bodies (2D/3D Rapier), colliders-as-props, trigger signals, and the declarative InputMap. Use when adding movement, collisions, pickups, gravity, or keyboard controls.
+---
+
+# Physics & Input in Incanto
+
+> Shipped inside the `incanto` npm package — this document always matches the
+> installed engine version. Sibling skills live in `node_modules/incanto/skills/`.
+
+## Enabling physics (async — Rapier wasm loads on demand)
+
+```ts
+import { enablePhysics2D } from 'incanto/2d'; // or enablePhysics3D from 'incanto/3d'
+await enablePhysics2D(engine); // AFTER engine.setScene(scene)
+engine.start();
+```
+Games that never call this never download Rapier (~600KB gz). 2D and 3D worlds are
+independent; enable the one matching your scene.
+
+## Units & gravity
+
+| | 2D | 3D |
+|---|---|---|
+| Units | pixels, y-DOWN | meters, y-UP |
+| Default gravity | `[0, 980]` | `[0, -9.81, 0]` |
+| Scene header | `"physics": { "gravity": [0, 1400] }` | `"physics": { "gravity": [0, -9.81, 0] }` |
+
+## Body nodes (colliders are PROPS, never child nodes)
+
+2D collider shapes: `{"shape":"rect","size":[w,h]}` · `{"shape":"circle","radius":r}` ·
+`{"shape":"capsule","radius":r,"height":h}`.
+3D: `{"shape":"box","size":[x,y,z]}` · `{"shape":"sphere","radius":r}` · `{"shape":"capsule",...}` ·
+`{"shape":"trimesh","vertices":[...],"indices":[...]}` · `{"shape":"heightfield"}` (STATIC-only;
+reads the grid from a `Terrain3D` child — see the incanto-environment skill).
+Malformed colliders are hard `BAD_FORMAT` errors at enable time.
+
+- **`StaticBody2D/3D`** — immovable (ground, walls). Props: `collider`.
+- **`RigidBody2D/3D`** — simulated. Props: `collider`, `mass 1`, `gravityScale 1`,
+  `fixedRotation false`, `friction 0.5`, `restitution 0`, `linearVelocity` (write to launch,
+  read back every step).
+- **`Area2D/3D`** — sensor. Emits `triggerEnter(other)` / `triggerExit(other)`. Never blocks
+  movement. Solid bodies emit the same signals on real contact (one mental model).
+  Areas overlapping OTHER Areas fire too (e.g. a weapon-hitbox Area over an
+  enemy-hitbox Area) — neither side needs to be a Body.
+- **`CharacterBody2D/3D`** — kinematic character (Rapier KCC). Props: `collider`
+  (capsule recommended), `velocity`, `snapToGround true`, `slopeLimitDeg 45`.
+  API: `moveAndSlide()` (call from `fixedUpdate`), `isOnFloor()`.
+
+Physics simulates WORLD positions: bodies under offset parents work (offsets compose),
+but ancestor ROTATION/SCALE are not supported for physics bodies — keep body ancestors
+untransformed or translation-only.
+
+**Gravity is NOT auto-applied to CharacterBody** (Godot semantics) — integrate it yourself:
+
+```ts
+class Player extends CharacterBody2D {
+  static override readonly typeName = 'Player';
+  override fixedUpdate(dt: number): void {
+    const dir = input.getVector('move');
+    this.velocity[0] = dir.x * 260;
+    if (this.isOnFloor()) {
+      this.velocity[1] = input.justPressed('jump') ? -640 : 20; // small bias keeps ground snap
+    } else {
+      this.velocity[1] += 1400 * dt;
+    }
+    this.moveAndSlide();
+  }
+}
+registerNode(Player); // then use "type": "Player" in scene JSON
+```
+
+## Declarative input (scene JSON `input{}` → `engine.input`)
+
+```json
+"input": {
+  "move": { "type": "vector2", "keys": { "up": ["KeyW","ArrowUp"], "down": ["KeyS","ArrowDown"], "left": ["KeyA","ArrowLeft"], "right": ["KeyD","ArrowRight"] }, "touch": "joystick" },
+  "jump": { "type": "button", "keys": ["Space"], "touch": "button" }
+}
+```
+
+```ts
+engine.input.attachKeyboard(window); // explicit DOM wiring (browser only)
+engine.input.isPressed('jump');      // held
+engine.input.justPressed('jump');    // one-frame edge (settled per tick)
+engine.input.getVector('move');      // normalized {x, y}, y-down (up = -y)
+```
+Keys are `KeyboardEvent.code` strings (`KeyW`, `Space`, `ArrowLeft`). Unknown actions and
+wrong-kind queries (getVector on a button) are hard errors listing valid names.
+Action declarations RESET on every `setScene` (no keybind bleed between scenes).
+
+`attachKeyboard` calls `preventDefault()` ONLY for keys bound to a declared action
+(default `{ preventDefault: 'bound' }` — embedded games no longer scroll the host page on
+Space/arrows; pass `'none'` to opt out). Keys typed into INPUT/TEXTAREA/SELECT/
+contenteditable are ignored entirely, so DOM UI overlays keep working.
+`engine.input.dispose()` detaches every attached source (keyboard and pointer).
+
+⚠️ `justPressed` edges settle once per RENDER tick: on a dropped frame with multiple fixed
+steps, the edge is visible in every fixed step of that tick. Gate one-shot actions on a
+state change too (the jump example works because `isOnFloor()` flips after the first step).
+
+## Touch controls (mobile web)
+
+Declare `"touch": "joystick"` on a vector2 action and/or `"touch": "button"` on button
+actions (as above) and the game grows on-screen controls: a left-side virtual stick
+feeding `setActionVector`, right-side buttons feeding `pressAction`/`releaseAction` —
+the game logic never distinguishes touch from keyboard. `createGame2D/3D` shows them
+automatically on coarse-pointer devices (`touch: 'auto'` default; `true` forces, `false`
+disables; they overlay `touchContainer` — default the canvas's parent, give it
+`position: relative`). Manual boots call `attachTouchControls(engine, container,
+{ force? })` from `incanto`. Wrong touch kinds (`"joystick"` on a button) fail at load.
+
+Collision layers/masks are not in v0 — everything collides with everything; use groups +
+`triggerEnter` filtering for game logic.
+
+## Action-level injection (scripted tests, touch overlays)
+
+Drive the game BY INTENT — no key codes to reverse-engineer:
+
+```ts
+engine.input.pressAction('jump');           // one justPressed frame, held until…
+engine.input.releaseAction('jump');         // …released (one justReleased frame)
+engine.input.setActionVector('move', 1, 0); // analog vector2; (0, 0) clears
+```
+Injected state combines with key state (vectors clamped to unit length).
+
+## Patterns
+
+- Pickups: `Area2D` in a group + `triggerEnter` → check `other.isInGroup('player')` →
+  `queueFree()` — wire it via JSON `connections` to a behavior method (the `Pickup`
+  pattern in `incanto-behaviors-and-scripts.md`), or imperatively with `node.on(...)`.
+- Teleport: just write `node.position` — the body follows. Launch: write `linearVelocity`.
+- Reference: [examples/2d-phaser-sprite-character-gravity](https://github.com/rareboe/Incanto/tree/main/examples/2d-phaser-sprite-character-gravity) — gravity, jump, attack lockout, custom
+  `Player` node type. Verified in Chromium end-to-end.
+
+## Debug drawing
+
+`physics.debugDraw = true` (the instance `enablePhysics2D/3D` returns) renders
+every collider as light-green wireframe lines IN THE GAME VIEW — Rapier's own
+debug geometry, so what you see is exactly what the solver sees. Default OFF;
+toggle it live whenever physics feels wrong.
+
+## Placement rules
+
+`CharacterController2D` MUST be a direct child of a `CharacterBody2D` — the
+loader hard-fails otherwise (it steers its parent body; nothing else has a
+`moveAndSlide`). Bodies themselves can sit anywhere in the tree.
+
+## Validation
+
+Collider shapes are validated at LOAD TIME: a wrong shape (`box` on a 2D body,
+`circle` on a 3D body) or missing dimensions is a hard `loadScene` error — you
+find out when you author the JSON, not when physics starts. A body with NO
+collider loads fine and physics skips it with a console warning;
+`moveAndSlide()` on it throws a "has no collider" error.
+
+
+## Pointer input (mouse look, buttons, wheel)
+
+`engine.input.attachPointer(canvas, { lockOnClick: true })` wires the mouse:
+buttons become codes `Mouse0/1/2` usable in any input-map action, look
+movement accumulates into `input.pointerDelta()` (drain once per frame —
+movementX/Y, so pointer lock just works), and `input.wheelDelta()` drains the
+wheel. `lockOnClick` requests pointer lock on click — the FPS pattern.

package/skills/incanto-scene-json-authoring.md

@@ -0,0 +1,325 @@
+---
+name: incanto-scene-json-authoring
+description: Read and write Incanto *.scene.json files — the JSON source of truth for every Incanto game. Use when creating, inspecting, or modifying scenes, nodes, signal wiring, or sub-scene instances.
+---
+
+# Authoring Incanto Scene JSON
+
+> Shipped inside the `incanto` npm package — this document always matches the
+> installed engine version. Sibling skills live in `node_modules/incanto/skills/`.
+
+An Incanto game's structure lives entirely in scene JSON. You can understand and modify a
+game without reading any TypeScript: nodes, their properties, group/tag identity, signal
+wiring, and composition are all in the file. TS is for *behavior only* (attached via
+`script` — see `incanto-behaviors-and-scripts.md`).
+
+## File shape
+
+```json
+{
+  "format": 1,
+  "type": "scene",
+  "name": "Level1",
+  "dimension": "2d",
+  "viewport": { "design": [960, 540], "fit": "expand" },
+  "assets": { "<key>": { "type": "...", "url": "..." } },
+  "constants": { "UI": 1000, "Background": -100 },
+  "input": { "<action>": { "...": "...", "touch": "joystick|button (optional — mobile on-screen controls)" } },
+  "multiplayer": { "room": "auto" },
+  "root": { "name": "Level1", "type": "Node", "children": [] },
+  "connections": []
+}
+```
+
+- `format` MUST be `1`. `type` MUST be `"scene"`. `name` non-empty.
+- `dimension` is optional: `"2d"` or `"3d"` only.
+- `viewport` (optional) makes scene JSON own responsive layout: author the world
+  in fixed `design` pixels (`[width, height]`, positive numbers) and the renderer
+  maps them onto any canvas size. `fit`: `"expand"` (design rect always fully
+  visible, extra world beyond — default) · `"letterbox"` (exactly the design
+  rect, centered bars) · `"integer"` (whole-number pixel-art scaling). Bad
+  values are hard `BAD_FORMAT` errors at load. Place world geometry in design px
+  in the JSON — not `window.innerWidth` math in TS. 2D HUDs pair this with
+  `UILayer`'s `anchor` prop, which pins the layer origin to a screen
+  corner/edge/center (see `incanto-building-2d-games.md`).
+- `assets` keys are stable human-readable handles; node props reference them as `"$key"`.
+- `constants` are named, reusable TYPED values; a node prop references one as
+  `{ "@const": "NAME" }` and the loader replaces it with the literal AT LOAD (see
+  "Named constants" below). Distinct from `$key` assets (which stay references).
+- `environment.rendering` carries renderer settings IN the scene:
+  `{ "antialias": false, "pixelRatio": "device" }` (pixelRatio: a number or
+  `"device"`; defaults antialias true / 2D pixelRatio 1 (Phaser parity) /
+  3D device-capped-2). Explicit `Renderer2D/3D` constructor options outrank it.
+- 3D `environment` also carries the whole atmosphere — `sky` (physical
+  atmosphere: `type: "atmosphere"`, sun via `elevationDeg`/`azimuthDeg` or
+  `sunPosition`, `turbidity`, `rayleigh`), `fog` (`{color?, near?, far?}`
+  linear fog), `clouds` (volumetric raymarched cloud deck —
+  `{coverage?, density?, base?, top?, color?, shadeColor?, speed?, scale?}`;
+  see `incanto-building-3d-games.md`), `shadows`
+  (`true`/`false`/`{mapSize: 1024|2048, radius}`), `exposure` (ACES
+  tone-mapping dial, default 1). All renderer-interpreted, hard-validated with
+  errors listing valid keys/options; scenes without them render unchanged.
+  Full recipe: `incanto-building-3d-games.md`.
+- `assets` / `input` / `multiplayer` / `environment` / `viewport` are preserved verbatim by load → export
+  round-trips (`environment` carries renderer settings — see `incanto-building-3d-games.md`).
+- Fixed-length numeric array props (`position`, `rotation`, `scale`, `size`…) are validated
+  element-wise: wrong length, non-number elements, or NaN/Infinity → `PROP_TYPE_MISMATCH`.
+
+## Nodes
+
+```json
+{
+  "name": "Player",
+  "type": "Node",
+  "groups": ["player"],
+  "tags": { "kind": "LOCAL_PLAYER" },
+  "props": { },
+  "script": { "name": "PlayerController", "props": { "maxSpeed": 220 } },
+  "network": { "mode": "owner", "sync": ["position"] },
+  "children": []
+}
+```
+
+Rules the engine enforces with **hard errors** (it never warns silently):
+
+1. Every node needs `type` (a registered node type) **or** `instance` — never both, never neither.
+2. `props` are **delta-only**: write a prop only when it differs from the type's default.
+   On export, default-equal values are omitted automatically.
+3. Prop keys and value kinds are validated against the type's schema:
+   unknown key → `UNKNOWN_PROP` (message lists valid keys); wrong JSON kind
+   (e.g. string where the default is boolean) → `PROP_TYPE_MISMATCH`.
+4. Sibling names must be unique. Colliding names are auto-renamed by incrementing a
+   trailing number (`Enemy` → `Enemy2` → `Enemy3`) — **write unique names yourself** so your
+   connection paths stay valid (connections resolve after renaming).
+5. Node names must not contain `/` or `%` and must be non-empty.
+6. `groups` are string tags for queries (`getNodesInGroup`, connection filters).
+   `tags` is free-form JSON for game-logic identity (`{"kind": "ITEM", "value": 10}`).
+7. `script` resolves to a registered Behavior at load (`incanto-behaviors-and-scripts.md`);
+   `network` drives multiplayer replication (`incanto-multiplayer.md`). Both round-trip
+   losslessly through export.
+
+## Why a NESTED tree (not flat nodes+parent)
+
+The file you are editing is the primary surface agents read: nesting makes
+orphans/cycles/dangling-parent errors UNREPRESENTABLE, keeps a node's context
+physically adjacent, and makes subtree copy/move one-object operations. Flat
+addressing needs are covered by uid (`getNodeByUid`). Full reasoning:
+docs/adr/0001 in the repo.
+
+## Parents and children
+
+EVERY node type can hold children — `children` is universal, so any node works
+as a grouping container. The inverse is not true: some types demand a SPECIFIC
+parent and are therefore also invalid as the root. Today's rule:
+
+- `CharacterController2D` must be a direct child of a `CharacterBody2D` —
+  anywhere else (including root) is a hard `loadScene` error naming both nodes.
+
+These constraints are loader-enforced, so you discover them at authoring time;
+the editor's add-node list greys out types its engine probe rejects at the
+current position.
+
+## Stable identity: `uid`
+
+Sibling names must be unique, but the SAME name may repeat across the tree — so name
+lookups return lists. For a stable, scene-wide-unique handle give a node a `uid`:
+
+```json
+{ "name": "Player", "type": "CharacterBody2D", "uid": "n_sqb84lj9q8pvemmx", … }
+```
+
+- **NEVER hand-write a uid.** Generate every uid with the engine's `newUid()`
+  (crypto-strength `n_` + 16 base36 chars) — hand-made readable strings break
+  the collision contract and stand out as fakes:
+  - in game/tool code: `import { newUid } from 'incanto'` (e.g. when spawning
+    nodes at runtime that you'll serialize)
+  - while authoring JSON by hand:
+    `node -e "import('incanto').then(m => console.log(m.newUid()))"`
+  - the editor assigns uids automatically to everything it creates
+- `root.getNodeByUid("n_p1gakz144ktj7eta")` → the node (or null) — survives moves and renames
+- `root.getNodesByName("Enemy")` → EVERY node named Enemy, in document order
+- Duplicate uids are a hard load error (`DUPLICATE_UID`)
+- The editor treats uid as IDENTITY: every node gets one at creation (legacy scenes
+  are backfilled on open), it is shown read-only, and deleting a node whose uid is
+  still referenced anywhere opens an unlink-or-cancel confirmation
+
+## Assets
+
+Every entry needs **`type` and `url` — both required**. Everything else on an
+entry is FREE METADATA: arbitrary key-values the engine ignores but preserves,
+readable from `scene.assets` — use it to carry information for yourself or
+other agents (license, palette, source prompt, frame counts…).
+
+```json
+"assets": {
+  "characters/knight": {
+    "type": "texture", "url": "/sprites/knight.png",
+    "filter": "nearest", "license": "CC0", "palette": ["#2d3250", "#ff6b6b"]
+  },
+  "avatar": { "type": "model", "url": "/models/hero.vrm" },
+  "run":    { "type": "animation", "url": "/anims/run.glb" }
+}
+```
+
+Supported `type` values:
+
+| type | what it loads | consumed by |
+|---|---|---|
+| `texture` | an image | `Sprite2D.texture` |
+| `spritesheet` | a spritesheet image (needs numeric `frameWidth`/`frameHeight`) | `AnimatedSprite2D.sheet` |
+| `model` | a **GLB / glTF / VRM** 3D model | `ModelInstance3D.model` |
+| `animation` | a GLB's animation clips (memory only — drawn nowhere) | `ModelInstance3D.animation` |
+
+Nodes reference entries as `"$key"` (`"$characters/knight"`). `model`/`animation`
+details — sizing, VRM retargeting, the `incanto-model` CLI — live in
+`incanto-3d-models.md`.
+
+## Asset groups
+
+Asset keys may carry a `group/` prefix — pure naming convention, zero engine
+machinery: `"characters/knight"` is one flat key, referenced as
+`"$characters/knight"`. The editor renders groups as collapsible folders in
+its ASSETS explorer section. Group related assets (`characters/`, `ui/`,
+`fx/`) so scenes stay navigable as they grow.
+
+## Named constants
+
+A scene-level table of reusable TYPED values. Define once, reference from any
+node prop — change the value in one place and every reference updates.
+
+```json
+{
+  "constants": { "UI": 1000, "Background": -100, "Brand": "#ff3366", "Spawn": [0, 0, 0] },
+  "root": { "name": "World", "type": "Node3D", "children": [
+    { "name": "Hud",  "type": "Sprite2D",   "props": { "renderOrder": { "@const": "UI" } } },
+    { "name": "Pond", "type": "Water3D",    "props": { "renderOrder": { "@const": "Background" } } },
+    { "name": "Logo", "type": "MeshInstance3D", "props": { "material": { "color": { "@const": "Brand" } } } }
+  ] }
+}
+```
+
+- A prop value of `{ "@const": "NAME" }` is replaced with the constant's literal
+  value AT LOAD — the node only ever sees the resolved value, so the constant's
+  type MUST match the prop's type (a number constant for a number prop, etc.) or
+  you get a `PROP_TYPE_MISMATCH`. Works at any depth (inside `material`, arrays…).
+- Unknown name → `UNKNOWN_CONSTANT` (lists the declared names). Constants are
+  per-scene and FLAT — a constant's value is a final literal, never another `@const`.
+- The editor manages these in a CONSTANTS panel (like ASSETS); the Inspector lets
+  you pick a matching-typed constant or type a raw value for any prop.
+- THE use case: render-order / sorting tiers. Define `Background`/`World`/`UI`
+  once, then point every node's `renderOrder` at them.
+
+## Render order (draw priority)
+
+ONE prop name across 2D and 3D: **`renderOrder`** (default 0, higher = drawn
+later / on top), on every `Node2D` and `Node3D`. (Legacy 2D scenes that used
+`zIndex` still load — it's accepted as an alias — but author new scenes with
+`renderOrder`.)
+
+- **2D**: every drawable (Sprite2D/ColorRect2D/Label/Particles2D) honors it —
+  see `incanto-building-2d-games.md`.
+- **3D**: only affects TRANSPARENT materials (three sorts the transparent pass
+  by `renderOrder`, then depth; opaque meshes always sort by depth). Built-ins set
+  sensible defaults — `Water3D` 1, `Foliage3D` blades 2 — which you can override.
+- Name the tiers with constants (above) instead of scattering magic numbers.
+
+## Node paths
+
+Used by `connections[].from/to` and APIs like `getNode`:
+
+| Path | Meaning |
+|---|---|
+| `"Child/Grand"` | descend from the current node |
+| `"."` | the current node (in connections: the scene root) |
+| `".."`, `"../Sibling"` | parent hops (relative paths only) |
+| `"/Level1/Player"` | absolute — first segment must equal the root node's name |
+| `"/root/Player"` | `/root/` is an alias for the tree root regardless of its actual name |
+| `"%Player"` | unique-name lookup across the whole tree (error if 0 or ≥2 matches) |
+
+Bad grammar → `BAD_NODE_PATH`. Unresolvable → `NODE_NOT_FOUND` (message lists the children
+that do exist at the failing spot).
+
+## Connections (serialized signal wiring)
+
+```json
+{ "signal": "triggerEnter", "from": "Coin", "to": ".", "handler": "onCoinCollected",
+  "once": true, "filter": { "group": "player" } }
+```
+
+- `from`/`to` are node paths **relative to the scene root** (`"."` = the root).
+- `signal` must be DECLARED on the from node (the class's or its behavior's
+  `static signals`) — validated at load → `UNKNOWN_SIGNAL` otherwise.
+- `handler` must be a method on the target node OR its behavior (script) — both are
+  validated hard at load. Otherwise → `UNKNOWN_HANDLER`. Script names themselves must be
+  registered (`registerBehavior`) before `loadScene` → `UNKNOWN_BEHAVIOR` otherwise.
+- Unresolvable `from`/`to` → `DANGLING_CONNECTION` at load. Renaming a node breaks its
+  connections **loudly** — update paths in the same edit.
+- `filter` gates firing on the first emitted argument: it must be a node in `filter.group`
+  and/or match every `filter.tag` entry. With `once: true`, the connection is consumed only
+  when the filter matches.
+
+## Sub-scene composition
+
+```json
+{ "name": "Ruby", "instance": "scenes/item.scene.json", "overrides": { "value": 99 } }
+```
+
+- `instance` embeds another scene's tree; `overrides` deep-merge onto the sub-scene root's
+  props. At the instancing site, `groups` and `children` COMPOSE (union/append), while
+  `tags`/`script`/`network` REPLACE the sub-scene root's values when declared (omitted = kept).
+- The sub-scene's own `connections` are wired inside its subtree automatically.
+- There is **no** scene inheritance — composition only.
+- Current limitation: exporting expands instances into full trees (the `instance` reference is
+  not preserved on export yet).
+- Cycles (`a` instances `b` instances `a`) and missing resolvers → `UNRESOLVED_INSTANCE`.
+
+## Error codes you will see (all hard failures at load)
+
+| Code | Cause | Fix |
+|---|---|---|
+| `BAD_FORMAT` | wrong `format`/`type`/`name`/`dimension`, node without `type`/`instance`, or both | match the file shape above |
+| `UNKNOWN_NODE_TYPE` | `type` not registered | use a type from the message's registered list |
+| `UNKNOWN_PROP` | prop key not in the type schema | use a key from the message's list |
+| `PROP_TYPE_MISMATCH` | prop JSON kind differs from the default's kind (incl. a `@const` whose value is the wrong type) | match the default's kind |
+| `UNKNOWN_CONSTANT` | `{"@const":"X"}` names a constant not in the scene's `constants` | declare it, or use a listed name |
+| `BAD_NODE_PATH` | malformed path grammar | see path table |
+| `NODE_NOT_FOUND` | path resolves nowhere | message lists existing children |
+| `DUPLICATE_UNIQUE_NAME` | `%Name` matches ≥2 nodes | rename one, or use an explicit path |
+| `DANGLING_CONNECTION` | connection `from`/`to` unresolvable | fix the path after renames |
+| `UNKNOWN_HANDLER` | handler missing on the node AND its behavior | fix the method name |
+| `UNKNOWN_SIGNAL` | connection (or emit/on) names a signal the from node never declares | use a declared signal, or declare it (`static signals` / `declareSignal`) |
+| `UNKNOWN_BEHAVIOR` | `script.name` not registered | `registerBehavior(name, Class)` before `loadScene` |
+| `UNRESOLVED_INSTANCE` | no resolver, unknown path, or instance cycle | provide/fix `resolveScene`, break the cycle |
+| `DUPLICATE_NODE_TYPE` | two classes registered under one type name | rename one type, or `{ replace: true }` for hot reload |
+| `DUPLICATE_BEHAVIOR` | two classes registered under one behavior name | rename one, or `{ replace: true }` for hot reload |
+| `TREE_VIOLATION` | invalid name, re-parenting without detach, cycles, double root | follow the rule in the message |
+
+Scene-load and registry errors carry structured `details` (`path`, `uid`, `nodeType`,
+`prop`, `signal`, `validOptions`) mirroring the prose — prefer those over regexing the
+message (a few runtime errors still carry prose only). Scene-load
+errors append the offending node's path: `… (at '/Level/Enemies/Slime3')`.
+
+## Programmatic API (current milestone)
+
+```ts
+import { loadScene, registerCoreNodes, duplicateNode } from 'incanto';
+
+registerCoreNodes();                            // explicit — never an import side effect
+const scene = loadScene(json, { resolveScene }); // throws IncantoError on any problem
+scene.root.getNode('Player').emit('hit', 10);
+const copy = duplicateNode(scene.root.getNode('Coin'));
+const exported = scene.toJSON();                 // lossless (delta-only props)
+```
+
+Registration semantics: `registerNodes2D()` / `registerNodes3D()` (from
+`incanto/2d` / `incanto/3d`) and `registerNodesNet()` (from `incanto/net`)
+each INCLUDE `registerCoreNodes()` — you never call it separately alongside
+them, and calling several registrars together (e.g. 2D + Net for a
+multiplayer game) is safe: re-registering the SAME class under a name is
+idempotent (only a DIFFERENT class under an existing name is a
+`DUPLICATE_NODE_TYPE` error, or needs `{ replace: true }` for hot reload).
+`createGame2D`/`createGame3D` call the right registrar for you.
+
+Lifecycle once loaded: `onEnterTree` parent-first → `onReady` children-first (once per
+instance) → per-frame `update(dt)` / fixed-rate `fixedUpdate(dt)` parent-first →
+`queueFree()` defers destruction to end of the update pass.