incanto 0.68.0 → 0.70.0

package/editor/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Incanto Scene Editor</title>
     <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><rect width='16' height='16' rx='3' fill='%236ee7dc'/><text x='8' y='12' text-anchor='middle' font-size='11' font-family='monospace' fill='%230e1018'>i</text></svg>" />
-    <script type="module" crossorigin src="./assets/index-eVd0BToA.js"></script>
+    <script type="module" crossorigin src="./assets/index-CIu3uc3l.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/GameServer-C56iOUgF.js">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "incanto",
-  "version": "0.68.0",
+  "version": "0.70.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",
@@ -54,8 +54,10 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run --project unit --root ../.."
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.node.json",
+    "test": "vitest run --project unit --root ../..",
+    "prepack": "node scripts/strip-dev-deps.mjs",
+    "postpack": "node scripts/strip-dev-deps.mjs --restore"
   },
   "peerDependencies": {
     "@agent8/gameserver": ">=1.10.0",
@@ -70,18 +72,6 @@
       "optional": true
     }
   },
-  "devDependencies": {
-    "@agent8/gameserver": "1.10.2",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "@types/three": "catalog:",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
-    "three": "catalog:",
-    "tsdown": "0.22.2",
-    "typescript": "catalog:",
-    "vitest": "catalog:"
-  },
   "dependencies": {
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
@@ -102,6 +92,7 @@
     "incanto-new": "bin/incanto-new.mjs",
     "incanto-frame": "bin/incanto-frame.mjs",
     "incanto-verify": "./bin/incanto-verify.mjs",
-    "incanto-logs": "./bin/incanto-logs.mjs"
+    "incanto-logs": "./bin/incanto-logs.mjs",
+    "incanto-serve": "./bin/incanto-serve.mjs"
   }
 }

package/schemas/scene.schema.json

@@ -1771,6 +1771,11 @@
             "current": {
               "type": "boolean",
               "default": false
+            },
+            "lookAt": {
+              "type": "string",
+              "description": "A node path: '%UniqueName', '/Absolute/From/Root', or relative to this node ('../Skin').",
+              "default": ""
             }
           },
           "additionalProperties": false
@@ -1903,6 +1908,10 @@
             "slopeLimitDeg": {
               "type": "number",
               "default": 45
+            },
+            "stepHeight": {
+              "type": "number",
+              "default": 35
             }
           },
           "additionalProperties": false
@@ -2800,8 +2809,15 @@
               "default": null
             },
             "density": {
-              "type": "string",
-              "enum": ["lush", "sparse", "none"],
+              "anyOf": [
+                {
+                  "type": "string",
+                  "enum": ["lush", "sparse", "none"]
+                },
+                {
+                  "type": "number"
+                }
+              ],
               "default": "sparse"
             },
             "area": {
@@ -5532,6 +5548,10 @@
               "minItems": 2,
               "maxItems": 2,
               "default": [0, 0]
+            },
+            "angularVelocity": {
+              "type": "number",
+              "default": 0
             }
           },
           "additionalProperties": false
@@ -9442,7 +9462,14 @@
               "default": true
             },
             "underwater": {
-              "type": "boolean",
+              "anyOf": [
+                {
+                  "type": "boolean"
+                },
+                {
+                  "type": "object"
+                }
+              ],
               "default": true
             },
             "swell": {

package/skills/incanto-3d-character.md

@@ -252,7 +252,16 @@ That is the EXACT formula `CharacterController3D` uses for move-facing
 an enemy that idles facing you): use the direction from self TO the target —
 `dx = target.position[0] - self.position[0]`, `dz = target.position[2] - self.position[2]`,
 then `rotation[1] = atan2(dx, dz)*RAD2DEG`. Movement-facing is just this with the
-target being "where I'm walking." There is ONE facing formula; only the direction differs.
+target being "where I'm walking." There is ONE facing formula for anything with a
+SKIN; only the direction differs.
+
+**NOT a camera.** A `Camera3D` looks down its own local **−Z**, and — more to the
+point — it has an UP that a rod does not. This formula aims a camera perfectly and
+rolls it: over 72 headings, dot 1.000 in all 72 and **upside down in 36**. No
+two-angle recipe can fix it (Euler XYZ makes `[pitch, yaw, 0]` = Rx·Ry, while a
+level camera is Ry·Rx, so its third angle is non-zero). Use
+`Camera3D.lookAt: "%Target"` — a node path, re-aimed every frame with world up.
+See `incanto-building-3d-games.md`.
 
 - **The 180° is NOT a facing formula.** It is only the AT-REST MOUNT — the character
   starts turned away from the behind-the-shoulder camera until it first moves. Adding
@@ -354,6 +363,10 @@ const rx = Math.atan2(-Dy, Dz);
 t.rotation = [rx*RAD2DEG, ry*RAD2DEG, 0];
 ```
 
+(This is a ROD: a stretched box has no up, so two angles are enough for it and
+`rodAxis · (target − muzzle) ≈ 1` is a complete check. A camera is not a rod —
+that same check scores 1.000 on an upside-down one. See the Camera3D note above.)
+
 The "obvious" `[-atan2(dy, hypot(dx,dz)), atan2(dx,dz), 0]` is only correct for a LEVEL
 shot — for XYZ order the yaw denominator must be `hypot(Dy,Dz)`, not the ground `hypot(dx,
 dz)`. With the wrong form the rod skews off-axis when you aim up/down, so its near end

package/skills/incanto-3d-models.md

@@ -76,6 +76,18 @@ meta (name/authors) + humanoid bone count. Decision rules:
   (a center.y of half the height usually means feet at origin: good).
 - **animation names** are exact strings for the `animation` prop.
 
+**At runtime the node itself will tell you**, which is what a harness or a
+behaviour picking a random idle needs:
+
+```ts
+model.availableAnimations();   // embedded clip names PLUS the scene's $animation assets
+model.boneNames();             // every bone, for BoneAttachment3D's `bone`
+model.findBone('RightHand');   // the Object3D, matching mixamorig prefixes too
+```
+
+`availableAnimations` is the one to check before setting `animation` from data:
+a clip name that is not in the list plays nothing and says nothing.
+
 ## Scene JSON
 
 ```json

package/skills/incanto-assets.md

@@ -21,13 +21,27 @@ playable character — model, locomotion clips, body, controller, skin and input
 ## 1. Built-in assets (in the package)
 
 ```bash
-bunx incanto-assets list                  # the full catalog (see categories below)
+bunx incanto-assets list                  # name · kind · GRID · what it is
 bunx incanto-assets info medieval-knight  # description + animation names
 bunx incanto-assets copy medieval-knight --out public/assets
 ```
 
 `list --json` prints every entry. Each entry carries a **`url`** — the drop-in
-reference you put in scene JSON so the asset LOADS (the contract, see §1b).
+reference you put in scene JSON so the asset LOADS (the contract, see §1b) —
+and, where the art has a grid, the numbers a node needs:
+
+```
+2dbasic          character  [animated] 111×83           2dbasic sprite sheet image…
+minecraft-tiles  tile                  16×16 (25 tiles) Minecraft-themed tiles…
+```
+
+`frameWidth`/`frameHeight` are what `AnimatedSprite2D.frameWidth` and
+`TileMap2D.tileSize` want; `columns` and `tiles` tell you the highest index a
+`legend` may name (25 tiles means 0–24, and asking for 99 draws clamp-streaks —
+the engine reports it, but the catalog is where you get the number). **The sizes
+live in these fields and nowhere else** — a frame size in the description was a
+second copy, and it drifted: `2dbasic` said 192×192 for art whose real grid is
+111×83.
 
 ### Categories — the whole built-in set
 
@@ -55,7 +69,7 @@ Every catalog entry has a `url` that is directly usable; there are two classes:
   // Tree3D — a bare node already loads oak leaves from the agent8 CDN; override
   // leafTexture only to swap in a different built-in cutout (e.g. ash)
   { "type": "Tree3D", "props": { "type": "broadleaf",
-      "leafTexture": "https://agent8-games.verse8.io/assets/3D/default/textures/vegetation/ash_color.png" } }
+      "leafTexture": "https://agent8-games.verse8.io/assets/3D/default/textures/vegetation/ash_color.png" } },
 
   // MeshInstance3D material — built-in ground/bark color as a map (+ a normal map)
   { "type": "MeshInstance3D", "props": { "material": {
@@ -224,3 +238,11 @@ node keeps its own texture cache. In **2D** the same question is `renderer.asset
 (`$ref`, url and reason per failed entry), and the scene EDITOR reads it: a
 failed asset is red in the explorer with the url in its tooltip and the
 consequence in its inspector.
+
+**And a texture INSIDE a model.** A `.gltf` + `.bin` + a missing `textures/`
+folder — the ordinary shape of a Blender "glTF Separate" export or a Sketchfab
+download — used to be the one silent case: GLTFLoader swallows a sub-resource
+failure, so the model resolved as a SUCCESS (`status: 'ready'`, `error: null`,
+empty `assetErrors()`, `stats().errors` 0) and the character simply rendered
+flat white. A half-loaded model was indistinguishable from a whole one. Now the
+missing texture is in `assetErrors()` by its URL, like every other one.

package/skills/incanto-audio.md

@@ -414,17 +414,26 @@ let cursor = 0;                    // next un-queued note
 engine.updated.connect(() => {
   const horizon = engine.sfx.now + LEAD;
   while (cursor < chart.length && startedAt + chart[cursor].atSec <= horizon) {
-    hit.play(startedAt + chart[cursor].atSec);   // AudioPlayer.play(at)
+    hit.playAt(startedAt + chart[cursor].atSec);   // NOT play() — see below
     cursor++;
   }
 });
 ```
 
 - **`engine.sfx.now`** — seconds on the audio clock, the one the sound is
-  actually placed on. `0` headless and before the first sound.
-- **`AudioPlayer.play(at)`** and **`engine.sfx.play(params, gain, { when })`** —
+  actually placed on. With no AudioContext — headless, and before the first
+  sound — it is the engine's own elapsed real time, so the loop above queues the
+  whole chart in the verify VM exactly as it does in a browser. (It was a frozen
+  `0`, which made that loop queue the first 80 ms of notes and then nothing ever
+  again: 1 of 21 beats, with no error anywhere.)
+- **`AudioPlayer.playAt(when)`** and **`engine.sfx.play(params, gain, { when })`** —
   PRESETS only. A `src` clip goes through an `<audio>` element, which has no
-  scheduling clock; `at` is ignored for one rather than approximated.
+  scheduling clock, so `playAt` on one plays immediately.
+- **`play()` takes no arguments, deliberately.** It is the method scenes wire
+  signals to, and a signal hands its handler whatever it carries — `collected`
+  leads with a number, so `collected → play` would have become `play(10)` and
+  scheduled the pickup sound at absolute audio-clock second 10. Scheduling has
+  its own name.
 - A time already past plays immediately (Web Audio's own rule), so a scheduler
   that ran late is late, not silent.
 - Everything else still applies: the bus gain, `engine.audio.recent()`, and
@@ -443,7 +452,9 @@ const songSeconds = engine.music.playhead;   // null = nothing playing, or no cl
 ```
 
 It is the raw element time, so a looping track wraps to 0 each pass — a loop
-boundary to chart against, not a fault.
+boundary to chart against, not a fault. Headless there is no element and no
+duration to wrap at, so it counts up from 0 for as long as the track plays —
+enough for a harness to prove the chart advanced.
 
 ## Decision guide
 
@@ -479,6 +490,17 @@ session.engine.audio.recent();
 its volume comes from. `countOf(name)` is the assertion you usually want;
 `clearLog()` resets between steps.
 
+**A LOOPING sound is recorded once, and its entry carries `loop: true`.**
+Re-recording every pass would evict the rest of the log within seconds for a
+0.2 s preset, so the count stays 1 — which used to make "the alarm loops"
+indistinguishable from "the alarm fired once and stopped". Assert the flag when
+that is the difference you care about:
+
+```ts
+const alarm = session.engine.audio.recent().find((e) => e.name === 'alarm');
+expect(alarm?.loop).toBe(true);
+```
+
 This covers every path: `AudioPlayer.play()` on both the procedural and the
 `src` route, `engine.music.play`/`crossfadeTo`, and `engine.sfx.startVoice`. It
 records the INTENT to play — that the wiring fired — not that a speaker moved;

package/skills/incanto-behaviors-and-scripts.md

@@ -50,10 +50,21 @@ silently breaks the link (`getNodeOrNull` returns null, nothing throws).
 ```ts
 static readonly props = {
   target: { default: '', nodePath: true },   // fed to getNode/getNodeOrNull
+  home: { default: '', nodePath: true, required: true },   // and you MUST set it
   damage: { default: 10 },
 };
 ```
 
+`""` is the "not set" value of a node-path prop, and `getNodeOrNull('')` returns
+`null` for it — so `const t = this.node.getNodeOrNull(this.target)` is safe to
+write without a guard.
+
+**`required: true` when the prop is not optional.** It turns "left empty" into a
+LOAD error naming the prop and the node (`'script:Archer' needs a "home" — it is
+empty. (at '/Level/Enemies/Slime3')`) instead of a behavior that silently does
+nothing all game. It costs one word and it is the best message the engine has
+for an unset prop.
+
 ## The three-artifact contract (keep them in sync!)
 
 1. scene JSON `"script": {"name": "CoinCounter"}`
@@ -75,10 +86,47 @@ under an existing name (re-registering a different class without it → `DUPLICA
   `createGame2D/3D` — they pass `{ engine }` to `loadScene`, attaching it BEFORE
   `onReady` fires. Under a manual boot it throws `TREE_VIOLATION` until
   `engine.setScene(scene)`: prefer `createGame` (or `loadScene(json, { engine })`),
-  or defer engine-dependent work to the first `update`. Two onReady caveats even
-  with the engine attached: `engine.scene` is still null (setScene runs after),
-  and the scene's `input` actions are not declared yet — query input from
-  `update`/`fixedUpdate`, never `onReady`.
+  or defer engine-dependent work to the first `update`. Caveats even with the
+  engine attached: `engine.scene` is still null (setScene runs after), and the
+  scene's `input` actions are not declared yet — query input from
+  `update`/`fixedUpdate`, never `onReady`. The scene's `strings` and its
+  `connections[]` ARE both in place by then, so `engine.t(...)` resolves and a
+  signal you emit from `onReady` reaches its JSON handler.
+
+## When your script throws
+
+A throw is CONTAINED, not fatal — but only after the scene has loaded, and the
+two halves are different on purpose:
+
+- **at load** (`loadScene`, including every `onReady` in the initial pass) a
+  throw is a hard failure. That is where an authoring mistake belongs: you want
+  to hear about it before the game runs, not to play a game with a piece
+  missing.
+- **at runtime** — a spawned prefab, a clone, a node a behaviour adds — a throw
+  from `onEnterTree`, `onReady`, `onExitTree`, `update` or `fixedUpdate`
+  quarantines THAT script and nothing else. The node keeps its state, the rest
+  of the scene keeps running, and `engine.log` names the node, the script and
+  the hook.
+
+The runtime half used to cover only `update`/`fixedUpdate`, so a spawned
+prefab's `onReady` bug unwound into the `update()` of whatever spawned it: the
+innocent Spawner was quarantined, spawning stopped permanently, and the log
+named the wrong node.
+
+**A signal listener is quarantined the same way** — the one that throws is
+disconnected, everything else keeps running, and the log names the node that
+OWNS the listener rather than the one that emitted:
+
+```
+[incanto] a 'scoreChanged' listener owned by behavior 'Hud' on /World/Hud threw
+— THIS LISTENER is now off; /World/Score, which emitted it, and the rest of the
+scene keep running.
+```
+
+Both spellings, `node.on(...)` and a JSON `connections` wire. Only the JSON
+half used to be covered, so a cosmetic HUD handler with a typo in it disabled
+the SCRIPT OF THE NODE THAT EMITTED — on the five shipped examples that do
+`controller.on('movementStateChanged', …)`, that stops the player moving.
 - `this.rng` — seeded engine randomness: `next()` [0,1), `range(min,max)`,
   `int(min,max)` (inclusive), `pick(arr)`. **Never `Math.random()` in game logic** —
   with `new Engine({ seed: 42 })` a run replays identically (scripted verification).
@@ -115,19 +163,46 @@ What behavior code actually calls at runtime — all instance methods, no global
 | `parent.addChild(node)` | attach a DETACHED node (already-parented → `TREE_VIOLATION`); sibling name collisions auto-rename (`Enemy` → `Enemy2`) |
 | `duplicateNode(node)` | deep-clone via serialize→rebuild — returns a **detached** node; attach it explicitly with `addChild` |
 | `node.queueFree()` | deferred destruction — flushed at the END of the current update pass (queued during a flush = freed next pass) |
-| `node.free()` | immediate detach + teardown (children first, signals disconnected) |
+| `node.free()` | immediate detach + teardown (children first; the signals it owns AND the ones it subscribed to elsewhere are both disconnected — see below) |
 | `root.getNodesByName('Enemy')` | EVERY node with that name in the subtree, document order |
 | `node.getNodeOrNull(path)` | like `getNode` but `null` instead of `NODE_NOT_FOUND` |
 | `node.getNode('%Player')` | unique-name lookup across the whole tree (≥2 matches → `DUPLICATE_UNIQUE_NAME`) |
+| `node.findChild('Skin')` | the first descendant with that name, or `null` — `findChild(name, false)` searches direct children only |
+| `parent.removeChild(node)` | DETACH without tearing down: the node keeps its children and its props, and is yours to `addChild` somewhere else. Nothing frees it — a detached node nobody re-attaches is a leak |
+| `node.reparent(newParent)` | detach-and-attach in one call, which is the safe order (`addChild` on a still-parented node is a `TREE_VIOLATION`) |
+| `node.getPath()` | its absolute path, `/Level/Enemies/Slime3` — what every error message and report prints, and what to log when a lookup surprises you |
+| `other.isInGroup('enemy')` | **the question a trigger asks** — the first line of nearly every `triggerEnter` handler. `node.groups` is a SET, not the array the JSON writes it as, so `groups.includes(…)` is a TypeError |
+| `node.addToGroup('enemies')` / `node.removeFromGroup('enemies')` | tag at RUNTIME; `groups` in the JSON is the same set, declared |
 | `this.node.tree?.getNodesInGroup('enemies')` | group query (also `tree.callGroup(group, method, ...args)`) |
 | `engine.stop()` / `engine.start()` | pause / resume the loop — stop resets the clock and accumulator, so no banked sim time leaks into the resume |
 | `engine.step()` | advance exactly ONE fixed step + one update (both dt = the fixed step) — the unit of time for headless tests |
 | `engine.tick(timestampMs)` | manual frame advance — takes an **absolute** ms timestamp (rAF-style), NOT a dt; the first call after (re)start only primes the clock |
 | `engine.setScene(scene)` | swap scenes: the previous root is freed, the input map is cleared and redeclared from the new scene's `input{}`, the clock resets (`time`, `unscaledTime`, and **`timeScale` back to 1** — a level restarted out of a frozen game-over must not boot frozen), then `sceneChanged` fires |
+| `node.off(signal, fn)` | disconnect ONE listener you connected with `on` — pass the same function reference. (`free()` disconnects everything a node owns, so this is for a listener that must stop while the node lives on) |
+| `node.signal('died')` | the `Signal` object itself, for `connect`/`disconnect` by hand; undeclared names throw, like `emit` |
+| `node.listenerCount('died')` | how many are listening — a test's way to prove a wire was made, or dropped |
 | `engine.stats()` | live perf counters `{ fps, frameMs, nodes, running }` — fps/frameMs average the last ~60 REAL `tick` frames (headless `step()` runs report 0), nodes is the current tree size. GPU counters (triangles/draw calls) live on `renderer.stats()` / the merged `game.stats()` |
 
 The recurring traps: `duplicateNode` does NOT insert the clone anywhere — a
-"spawner that does nothing" usually forgot `addChild`. `engine.tick(16)` does
+"spawner that does nothing" usually forgot `addChild`.
+
+**The template you clone FROM is a live node.** Its behaviors run, its timers
+tick, its turret shoots — `visible: false` hides a node, it does not switch it
+off. `Spawner` and `WaveSpawner` sidestep this by DETACHING their `prefab` at
+ready; a shelf of templates you clone yourself is still in the tree, so author
+their scripts `"enabled": false` and wake the clone:
+
+```ts
+const tower = duplicateNode(this.node.getNode('/Game/Prefabs/Tower'));
+tower.behavior?.enable();          // the template stays asleep, this one works
+this.node.getNode('/Game/Towers').addChild(tower);
+```
+
+Without it an invisible tower at the origin defends your map, and the game looks
+fine. **And look the template up by PATH, not `%Name`**: a clone keeps its
+template's name, so `%Tower` is unambiguous exactly until the first one is
+placed, and then it throws `DUPLICATE_UNIQUE_NAME` from inside your build
+handler — a game that works once. `engine.tick(16)` does
 not mean "advance 16ms": tick wants wall-clock timestamps, so scripted loops
 should call `engine.step()` instead. And `queueFree` inside `update` is always
 safe — the node keeps existing until the pass ends.
@@ -209,6 +284,8 @@ no TypeScript, and all five are clean.
 { "name": "Spawner", "type": "Timer", "props": { "waitTime": 2, "autostart": true } }
 ```
 Emits `timeout` every `waitTime` s (`oneShot` for once). API: `start(time?)`, `stop()`, `running`.
+A `waitTime` of 0 is a load error: the update guard stops a timer with no period
+on its first frame, so it would never fire and never say so.
 
 ## CharacterController2D (JSON-only playable characters)
 

package/skills/incanto-building-2d-games.md

@@ -15,6 +15,7 @@ Prerequisite: `incanto-scene-json-authoring.md` (this directory) for the file fo
 ```bash
 bunx incanto new my-game --template platformer-2d    # tilemap, jump feel, follow cam, coins
 bunx incanto new my-game --template star-survivor    # endless waves, auto-attack, upgrades
+bunx incanto new my-game --template molehill-2d      # played with the MOUSE — no character at all
 bunx incanto new --list                              # every starter, 3D and 2D
 ```
 
@@ -95,6 +96,10 @@ stop hand-placing dozens of ColorRect walls:
 - `.` / space = empty; digits `0-9` = atlas tile index directly; any OTHER char
   must be in `legend` — unknown chars **hard-fail at load** (fix the map, not
   the runtime).
+- **A legend value is an INDEX, not a description.** Every other tilemap format
+  puts solidity in the tile definition, so `"legend": { "#": { "solid": true } }`
+  is the natural guess — and it used to load clean and produce a level with no
+  floor. It is a hard error now, naming the `solid` prop that was meant.
 - `solid` tiles are merged into a handful of `StaticBody2D` rect colliders
   (greedy rectangles), so a 100×50 level costs a few bodies, not thousands.
 - Cell (0,0) hangs its TOP-LEFT on the node's origin; position the node to
@@ -103,7 +108,25 @@ stop hand-placing dozens of ColorRect walls:
 - No texture yet? Colliders still work — pair with ColorRect2D placeholders or
   just leave it invisible while you block out the level.
 - Change the map at runtime by REPLACING `cells` (mutations are not watched):
-  `map.cells = [...rows]` — geometry and colliders rebuild next frame.
+  `map.cells = [...rows]` — geometry and colliders rebuild next frame. For ONE
+  cell use `setTile` below, which does that correctly.
+
+**Pointing at tiles** — the whole input of a tile game, and four calls:
+
+```ts
+const cell = map.cellAt(...this.engine.pointerWorld() ?? []);  // [cx, cy] | null
+if (cell && map.tileAt(...cell) === 1) {
+  map.setTile(cell[0], cell[1], '.');          // dig it out (a CHARACTER)
+  marker.position = map.worldAt(...cell);      // the cell's CENTRE
+}
+```
+
+`cellAt` is null off the grid, `tileAt` is `-1` for an empty cell or one that is
+not there, and `worldAt` gives the cell's **centre** — the half-tile a
+hand-rolled version forgets. All four measure from the node's WORLD position
+(ancestors composed), which is the other thing hand-rolling gets wrong. An
+ancestor that SCALES or rotates the map moves the picture and not the answer,
+and `incanto-check` says so.
 
 ### `Sprite2D`
 | Prop | Default | Notes |
@@ -212,6 +235,42 @@ offsets that survive any canvas size: a `Label` at `[-16, 16]` under a
 `top-right` layer hugs the corner everywhere. Misspelled anchors fail at load
 listing the valid set. With a viewport design, UI coordinates are design px.
 
+**Two spellings, and the engine means it.** `UILayer` writes them with hyphens
+(`top-left`); the `HudLayer` widgets write them in camel case (`topLeft`). Nine
+of the same anchors, two vocabularies, and neither accepts the other's — a
+`UiText` with `"anchor": "top-left"` is a load error, and so is a `UILayer` with
+`"topLeft"`. Both errors print their own valid set, so you are one edit from
+right; this note is so you know why.
+
+### A `UILayer` still SCALES. On a phone, use `HudLayer`
+
+`UILayer` ignores the camera; it does not ignore the viewport. Its contents are
+design pixels multiplied by the same scale as the world, and on a portrait phone
+that scale is small:
+
+```
+1280×800   scale 1.333   a fontSize 15 Label paints at 20 device px
+390×844    scale 0.406   the same Label paints at  6.1 device px
+```
+
+Six device pixels is an unreadable smear, and it is the flagship 2D template's
+control hint before this was fixed. The vertical framing goes the same way:
+`design: [960, 540]` under `fit: "expand"` shows a portrait phone **2077 world
+px** of height, so the play surface is a band with acres of empty sky.
+
+**`HudLayer` and the `Ui*` widgets are DOM at their declared CSS pixels** and are
+immune — which is why the engine's own volume sliders and touch controls stayed
+legible in the same capture that reduced the template's HUD to a grey line. Use
+them for anything a player has to READ:
+
+| | |
+| --- | --- |
+| `Label` under `UILayer` | part of the picture — damage numbers, world-anchored callouts, art |
+| `UiText` under `HudLayer` | part of the interface — score, hearts, hints, menus |
+
+See `incanto-hud.md`. It costs nothing on desktop and it is the difference
+between a readable and an unusable phone build.
+
 ## Patterns
 
 - Group pickups/enemies (`"groups": ["coins"]`) and query `scene.tree.getNodesInGroup('coins')`.
@@ -245,13 +304,33 @@ listing the valid set. With a viewport design, UI coordinates are design px.
   touched. Its inverse, `renderer.screenFromWorld(wx, wy)`, pins DOM to the
   world (see incanto-web-integration).
 
+  **From a Behavior, ask the ENGINE** — `this.engine` is all a behavior has, and
+  the renderer is not on it:
+
+  ```ts
+  const at = this.engine.pointerWorld();          // world px, or null
+  if (at) this.node.position = at;                // it IS a position array
+  this.engine.toWorld(sx, sy);                    // any screen point
+  this.engine.toScreen(this.node.position);       // → { x, y, behind }
+  ```
+
+  The renderer installs these, exactly as it installs `engine.picker`: `pickAt`
+  answers WHICH NODE the cursor is on, `pointerWorld` answers WHERE it is, and a
+  drag-and-launch needs the second one. Both are null with no renderer, and a
+  `runScript` `click` step (or `incanto-play`'s `at`) installs a geometric
+  version for the run — so aiming is testable headless, not only clicking.
+
 ## Game flow recipes
 
 - **Scene transition** (level 2, title → game):
   ```ts
   import { loadScene } from 'incanto';
-  game.engine.setScene(loadScene(level2Json));
+  game.engine.setScene(loadScene(level2Json, { engine: game.engine }));
   ```
+  Pass `{ engine }`: `onReady` runs during the LOAD, so a behaviour that reads
+  `this.engine` or `this.rng` there — `Wander` draws its first heading in it —
+  throws `TREE_VIOLATION` without it.
+
   `setScene` frees the old root, clears + redeclares the input map from the new
   scene's `input{}`, and emits `sceneChanged` — `createGame2D`'s touch overlay
   rebuilds itself on that signal, the PHYSICS world registers the new scene's
@@ -266,7 +345,7 @@ listing the valid set. With a viewport design, UI coordinates are design px.
   last one is why the game-over recipe below is safe — a swap out of a frozen
   screen boots the next level running, not frozen.
 - **Game over / restart**: swap to a fresh load of the SAME JSON —
-  `engine.setScene(loadScene(levelJson))`. `loadScene` treats the JSON as
+  `engine.setScene(loadScene(levelJson, { engine }))`. `loadScene` treats the JSON as
   read-only (everything it keeps is cloned), so reloading the same imported
   object yields a clean run; only clone (`structuredClone(levelJson)`) first if
   your own code mutated that object. (`createGame`'s `scene` option already
@@ -294,7 +373,7 @@ constructor).
 ## Particles (effects in one node)
 
 ```json
-{ "name": "Torch", "type": "Particles2D", "props": { "preset": "fire" } }
+{ "name": "Torch", "type": "Particles2D", "props": { "preset": "fire" } },
 { "name": "Boom", "type": "Particles2D",
   "props": { "preset": "explosion", "rate": 0, "burst": 60 } }
 ```
@@ -394,7 +473,7 @@ anything a 540 px window can show.
 
 ```
 camera /Game/Camera centred [480, 274] showing 960×540px
-11 in view, 2 outside it
+11 in view, 2 outside it, 1 hidden (visible: false)
   onScreen  /Game/Level (TileMap2D) [0, 0] screen [0.333, -0.007] 160px
   onScreen  /Game/Gems/Gem1/Icon (Sprite2D) [512, 428] screen [0.067, 0.57] 157px
   offscreen /Game/Goblins/Goblin2/Skin (AnimatedSprite2D) [1002, 512] … 574px
@@ -405,14 +484,26 @@ camera /Game/Camera centred [480, 274] showing 960×540px
 edge". A node counts as in view when its BOX is — a `ColorRect2D`'s `size`, a
 `TileMap2D`'s whole grid (which hangs from its TOP-LEFT, not its centre), or a
 collider. A bare `Sprite2D` declares no size, so read `offscreen` there as "its
-ORIGIN is outside the view". Nothing is ever "behind" a 2D camera and nothing is
-lit, so neither is reported; `overlap` is real interpenetration, not resting on
-a platform. HUD widgets are screen-space and are left out entirely.
+ORIGIN is outside the view". `hidden` is `visible: false` on the node or on any
+ancestor — counted apart from `offscreen` because the fix differs, and printed as
+`NOTHING IS DRAWN` when it is every drawable in the scene. Nothing is ever
+"behind" a 2D camera and nothing is lit, so neither is reported; `overlap` is
+real interpenetration, not resting on a platform. HUD widgets are screen-space
+and are left out entirely.
 
 Then read `stats().errors` (something threw and got skipped) and `assetErrors()`
 (a texture 404'd). All of these are silent failures otherwise — the screen just
 looks wrong, or empty, and nothing throws.
 
+**A game with no jump key is fine.** `jumpAction`, `dashAction` and even
+`moveAction` may name an action the scene never declares — a top-down RPG has
+nothing to jump over — and the character simply never does that thing. Until
+this was fixed the controller THREW every frame, the node was quarantined, and
+the character could not move either: a top-down game that declared only `move`
+reported `✗ error in 1/1` and stood still, with the reason in a log nobody
+prints. An action you TYPED that does not exist is still reported, once, because
+that is a typo and not an omission.
+
 ## Platformer game feel (CharacterController2D)
 
 A jump that only fires while `isOnFloor()` is true feels BROKEN, and players do
@@ -462,6 +553,13 @@ entry, which is what the states you have no artwork for should be:
 }
 ```
 
+**The whole map is checked when the scene loads**, not when a clip first plays:
+a clip is `{frames, fps, loop}` and nothing else, so `frame`, `frameRate`,
+`speed` and `repeat` — all real fields in the sheet formats people convert from
+— are load errors naming the field you meant. Only the aliases used to be
+checked, so a misspelled `frames` was a hard error the first time the character
+walked, twenty minutes in.
+
 `incanto-assets copy` and `spriteFromLibraryMeta` already print these aliases,
 so pasting their output next to the wiring above works as-is; point any of them
 somewhere better when you have the art. Aliases may chain (`fall` → `jump` →