incanto 0.69.0 → 0.70.0

package/skills/incanto-performance.md

@@ -324,3 +324,55 @@ rendered a five-pass frame at 3.3 ms where `low` rendered one pass at 1.24 ms
 A tier is also REVERSIBLE now: it is applied against the scene FILE rather than
 against whatever the last tier left behind, so `low` → `high` restores exactly
 what you authored instead of leaving it stripped.
+
+## How big a game actually is, and the chunk named after the wrong thing
+
+Measured on all six templates, scaffolded from the packed tarball and built:
+
+```
+                    eager     on disk
+molehill-2d        967 KB      5.8 MB
+platformer-2d      981 KB      5.9 MB
+star-survivor      962 KB      5.9 MB
+beacon-isle-3d    1414 KB      5.8 MB
+tps-3d            1376 KB      5.8 MB
+village-quest-3d  1469 KB      5.8 MB
+```
+
+**`dist/` is six megabytes and a player downloads one.** The rest is lazy: the
+Rapier wasm builds (2D and 3D, ~4.5 MB together) load only when a scene has
+physics bodies, and the editor chunk only if someone opens it. Read the
+`<script>` and `<link rel=modulepreload>` tags in `dist/index.html` for what
+actually loads — `du -sh dist` answers a question nobody asked.
+
+**The vendor chunk is named after whichever module the bundler happened to pick,
+and it is not the one you think.** In every one of those builds the ~790 KB
+chunk is called `quiet-rapier-*.js` and contains **three.js** — no Rapier at
+all. A size audit that reads names concludes the physics engine is eager in a
+mouse game with no bodies in it. Read the contents:
+
+```bash
+grep -c WebGLRenderer dist/assets/quiet-rapier-*.js   # three.js lives here
+```
+
+Name them yourself if it matters to you — it changes nothing about what loads,
+only what the file is called:
+
+```ts
+export default defineConfig({
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks: (id) =>
+          id.includes('node_modules/three') ? 'three'
+          : id.includes('@dimforge/rapier') ? 'rapier'
+          : undefined,
+      },
+    },
+  },
+});
+```
+
+three is eager in a 2D game too, and that is not a bug: `Renderer2D` draws
+through the same WebGL renderer as the 3D one — shared-PlaneGeometry meshes and
+an orthographic camera. It is the price of one renderer instead of two.

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

@@ -80,14 +80,22 @@ mesh or one model and warns when the body carries more.
 - **`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).
+  read back every step; `velocity` is an alias for it). 3D also has
+  `angularVelocity`. Every one of them is LIVE — write it mid-run and the solver
+  picks it up on the next 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`, `stickToGround true`, `slopeLimitDeg 45`.
-  API: `moveAndSlide()` (call from `fixedUpdate`), `isOnFloor()`.
+  (capsule recommended), `velocity`, `stickToGround true`, `slopeLimitDeg 45`,
+  `stepHeight` (3D `0.35` m / 2D `35` px — see below).
+  API: `moveAndSlide()` (call from `fixedUpdate`), `isOnFloor()`,
+  **`isOnWall()`** and **`isOnCeiling()`**. Which wall is answered in the shape
+  each dimension has: 2D's `wallSide()` is `-1` left / `+1` right, 3D's
+  `wallNormal()` is the wall's normal pointing away from it — the direction a
+  wall jump pushes. Without them a wall jump or a wall slide is not awkward to
+  write, it is impossible: there is nothing to ask.
 
 ### `enabled` — a collider that is off for now
 
@@ -105,6 +113,13 @@ sword.enabled = true;    // the active window of the swing
 sword.enabled = false;   // …and done
 ```
 
+**A collider's keys are CLOSED**: `shape`, `size`, `radius`, `height`, `offset`
+and (2D) `oneWay` — plus `vertices`/`indices` for a 3D trimesh. Anything else is
+a load error naming the nearest one, because
+`{"shape": "circle", "radius": 8, "offest": [0, -24]}` used to load clean with
+its hitbox 24 px from where it was meant to be. `friction`, `restitution` and
+mass are props of the BODY, not of its collider.
+
 **Do not arm a hitbox by swapping `collider` in and out.** Replacing the
 collider prop tears the rigid body down and builds a new one — twice per swing —
 and a scene authored `"collider": {}` warns `has no collider — physics skips it`
@@ -169,9 +184,19 @@ 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).
+**One press is ONE edge**, in `update` and in `fixedUpdate` alike — the fixed pass has
+its own edge view, drained after its first step, so a dropped frame carrying five steps
+delivers the edge once and a 144 Hz tick that runs no fixed step at all does not lose it.
+Same for `justReleased`. (Until 0.63 this warned that the edge repeated in every fixed
+step of a slow frame; it has not since the fixed pass got its own edge sets, and nothing
+noticed for two releases.)
+
+⚠️ What IS worth knowing: **a press injected from inside the frame lands on the NEXT
+tick.** `pressAction`/`releaseAction` called from a `fixedUpdate`, an `update` or an
+`engine.updated` handler — replay drivers, AI input, touch overlays — is invisible for
+the rest of that tick and arrives at the next one, because an edge created after the
+pass that reads it would be created and destroyed without anything seeing it. The HELD
+state (`isPressed`) is immediate either way.
 
 ## Touch controls (mobile web)
 
@@ -307,11 +332,25 @@ body.velocity = [2, 0, 0];         // or set the velocity outright
 
 `applyImpulse` is what the character controller itself runs on. It is an
 IMPULSE, not a force: it changes velocity once, so a continuous push is one call
-per frame from `update(dt)` scaled by `dt`.
-
-Readable/writable body state: `velocity`, `mass`, `gravityScale`, `friction`,
-`restitution`, `fixedRotation`. There is no torque call and no `angularVelocity`
-yet — a body's spin can be neither set nor read.
+per frame from `update(dt)` scaled by `dt`. In 2D the impulse is in px·kg/s,
+y-down, exactly like `linearVelocity`.
+
+Readable/writable body state, in BOTH adapters: `velocity` (= `linearVelocity`),
+`angularVelocity`, `mass`, `gravityScale`, `friction`, `restitution`. Read the
+spin to see how fast a lever is swinging; write it to launch a spinning body.
+3D's is a 3-vector about the world axes, 2D's is the scalar rad/s about z with
+the same sign as `rotation` (clockwise, because 2D is y-down). There is no
+torque call in either. Writes land on the next step — these are live props, not
+load-time constants.
+
+`fixedRotation` is authored, not live: it locks the body's rotation when the
+body is CREATED. Changing it mid-run does nothing, and a locked body's
+`angularVelocity` is zero rather than whatever was authored.
+
+> Four of these were once false, silently: `applyImpulse` existed only in
+> 3D (a TypeError in 2D), `body.velocity = […]` wrote a stray field nothing read
+> in both, `mass`/`friction`/`restitution` were read once at creation in both,
+> and `gravityScale` was live in 3D and dead in 2D.
 
 ## What is inside this Area right now?
 
@@ -354,7 +393,12 @@ question you usually mean.
    only** — never their contact with the rest of the world. Defaulting a spring
    off drops a barrel roped to the floor straight through it, which is how this
    table was arrived at.
-3. **`anchor`/`targetAnchor` are local offsets from each body's ORIGIN**,
+3. **A joint's two ends must be two DIFFERENT bodies.** It is a child of one and
+   points at the other, so `"target": ".."` — which reads like naming the body
+   it belongs to — is now a load-time error: Rapier accepts a body jointed to
+   itself and constrains nothing, and the rope fell exactly as if it were not
+   there.
+4. **`anchor`/`targetAnchor` are local offsets from each body's ORIGIN**,
    resolved against the bodies' positions at load. If the two disagree the solver
    snaps the body into place on the first frame, and a 4 cm typo is silent. Author
    them with arithmetic (generate the scene) rather than by hand.
@@ -380,19 +424,41 @@ Both runtimes expose the same query (2D in PIXELS y-down, 3D in meters):
 
 ```ts
 const hit = physics.castRay(origin, dir, maxLen, excludeBody?, { staticOnly?: true });
+// hit: { distance, normal, node, point } — `point` is WHERE it landed, in the
+// scene's own units. `dir` may be any length; the ray normalizes it, so
+// `origin + dir * distance` by hand is wrong unless you normalize first.
 // → { distance, normal, node } | null   (sensors never block rays)
 ```
 
+Both also answer two questions about a body that the node props cannot:
+
+```ts
+physics.velocityOf(body);  // px/s (2D, y-down) or m/s (3D) — from the SOLVER
+physics.massOf(body);      // what the solver settled on, collider-derived
+```
+
+`linearVelocity` on the node is written back once per step, AFTER the solve — so
+a behavior reading it from inside `fixedUpdate`, which is where a collision
+response belongs, sees the value from BEFORE the impact. That is exactly the
+moment a game wants to know how hard it hit something. Scale a push by `massOf`
+rather than by the authored `mass` prop, which the solver may not be using.
+
+`dir` may be ANY length — `target - eye` is the usual spelling and is metres
+long. It is normalized for you, so `distance` and `maxLen` are always plain
+metres (2D: pixels), never multiples of the vector you passed. A zero-length
+direction points nowhere and returns `null`.
+
 Exclude the shooter's own body when casting from inside it — a ray that starts
 inside its own collider hits itself at distance 0, which reads as "blocked" and
 is the reason a vision cone can come back permanently blind.
 
-3D also has a THICK ray — a sphere sweep — for probes where skimming matters
-(the camera boom, ledge feelers):
+Both also have a THICK ray — a sphere sweep in 3D, a circle sweep in 2D — for
+probes where skimming matters (the camera boom, ledge feelers, a shot that must
+not thread a one-pixel gap between two floor tiles):
 
 ```ts
 const hit = physics.castSphere(origin, dir, radius, maxLen, excludeBody?, { staticOnly?: true });
-// → { distance, node } | null   (distance = travel of the sphere CENTER)
+// → { distance, node } | null   (distance = travel of the CENTRE)
 ```
 
 ## Gamepad
@@ -440,12 +506,15 @@ the tree says, without your scene falling over while you look at it. Use it for
 any "show me the collision geometry" tool. Do NOT use it to freeze a running
 game — that is `engine.timeScale = 0`, which keeps the world coherent.
 
-## A walking body climbs a step (`stepHeight`, 3D)
+## A walking body climbs a step (`stepHeight`, 2D **and** 3D)
 
-`CharacterBody3D.stepHeight` (default `0.35` m, `0` = off) is how high a ledge
-the body walks UP without jumping. It is Rapier's autostep, and **Rapier does not
-autostep unless it is asked** — before 0.63 nothing asked, so any walking body
-was stopped dead by a curb.
+`CharacterBody3D.stepHeight` (default `0.35` m) and `CharacterBody2D.stepHeight`
+(default `35` px — the same 0.35 m at the 2D world's scale of 100 px = 1 m,
+which is why gravity defaults to 980) are how high a ledge the body walks UP
+without jumping. `0` = off. It is Rapier's autostep, and **Rapier does not
+autostep unless it is asked** — before 0.63 nothing asked in 3D, and for longer
+still nothing asked in 2D at all, where a lip ONE PIXEL high stopped a walking body
+dead.
 
 You will not see this on the player: `CharacterController3D` rides a hover spring
 rather than the character controller, so it floats over small ledges already.
@@ -522,6 +591,16 @@ game.pick(x, y);                  // the node under that pixel, or null
 A stretched canvas is handled: `pointerPosition()` scales client → canvas pixels,
 so the coordinates are the ones `pick()` wants.
 
+**The pointer has to be attached, and now attaches itself.** `createGame2D`/
+`createGame3D` turn it on when the scene contains a `Clickable` — the same
+`'auto'` shape `physics` has always had — and they ask again on every scene
+change, because a title screen you click into a level has no `Clickable` in it
+(a `UiButton` is DOM) and the level is full of them. Pass `pointer: true` explicitly when a
+behaviour of YOUR OWN reads `pointerPosition()`; the boot cannot see that. A
+`Clickable` that finds no pointer (or no picker) for two seconds says so by
+name instead of sitting there inert, which is what it used to do: no error, a
+clean `incanto-check`, a clean audit, and a board that did nothing when clicked.
+
 From scene JSON, the **`Clickable`** behavior needs no code at all:
 
 ```json
@@ -531,7 +610,7 @@ From scene JSON, the **`Clickable`** behavior needs no code at all:
 | prop | default | |
 | --- | --- | --- |
 | `button` | `0` | 0 left · 1 middle · 2 right |
-| `maxDistance` | `0` | ignore clicks further than this (0 = any) |
+| `maxDistance` | `0` | ignore clicks further than this **from the current camera** (0 = any) |
 | `enabled` | `true` | stop responding without detaching |
 
 Signals: **`clicked(node)`**, **`hovered(node)`**, **`unhovered(node)`** — wire
@@ -550,11 +629,31 @@ ends elsewhere is not a click, the way every button on every platform behaves),
 and a hit on a CHILD counts as a hit on the node — the raycast lands on the
 visual mesh, which is usually a child.
 
+**A finger that lifts stops hovering.** `hovered`/`unhovered` follow the cursor,
+and a mouse cursor stays where you left it — but a finger ceases to exist, so a
+touch release clears the pointer at the end of that frame (after the click has
+fired, not with it). Without that the last-tapped node stayed `hovering: true`
+for the rest of the session: a permanently highlighted tile, mole or card on
+every phone. Do not build a hover-only affordance — on touch there is no hover
+before the tap, only after it, and only for a frame.
+
+**`visible: false` is not clickable.** A pixel the frame does not draw has
+nothing under it, so hiding a node (or any ancestor of it) takes it out of the
+pick — which is how you disable a button, a dialogue choice or a mole down its
+hole without detaching anything. Before 0.71 three's raycaster reported hidden
+geometry and `pick()` handed it straight to `Clickable`.
+
 ### Testing a mouse-driven game headlessly
 
-There is no renderer and therefore no raycast, so `engine.picker` is null and
-`Clickable` is inert. That is not a dead end: give the engine a picker of your
-own and drive the cursor.
+**Use `runScript`'s `click` step** — `{ atMs: 100, click: 'Board/Tile3' }` — which
+installs a geometric picker, points the cursor and spreads the press and release
+across the two frames `Clickable` needs. `incanto-playtest` clicks too, and its
+report says how many clicks it landed. See `incanto-verifying-your-game.md`.
+
+The raw recipe below is what that does, and is still what you want when the
+cursor has to be somewhere a node is not. There is no renderer and therefore no
+raycast, so `engine.picker` is null and `Clickable` is inert. That is not a dead
+end: give the engine a picker of your own and drive the cursor.
 
 ```ts
 // A picker that answers from the tree instead of a GPU raycast.

package/skills/incanto-playtesting.md

@@ -51,12 +51,36 @@ two.
 | `fell` | the player left the world past `--fall-below` (default: 50 m under the spawn in 3D, 1000 px under it in 2D) |
 | `error` | `stats().errors` went above zero — a behavior threw |
 | `stuck` | the clock ran out AND the player never got more than 3 m (96 px) from its spawn — it is wedged, or nothing moves it |
-| `swapped` | the game changed scene. The bot binds player, destinations and the win/lose oracle ONCE, from the tree it started in, so nothing after a `goToScene` is measured — the run stops there and says so. It is not a defect, and the destinations it never got to are reported as unmeasured rather than missed. Judge a multi-scene game with a scripted `runScript`. |
+| `swapped` | the game changed scene. The bot binds player, destinations and the win/lose oracle ONCE, from the tree it started in, so nothing after a `goToScene` is measured — the run stops there and says so. It is not a defect, and the destinations it never got to are reported as unmeasured rather than missed. Judge a multi-scene game with a scripted `runScript`. The bot's own KEYS are re-read on the swap: it used to hold the first scene's buttons into the second, and letting go of one the new scene never declared threw the whole playtest away. |
 | `unfinished` | the clock ran out on a player that was getting around. Not a defect: a win that needs a SEQUENCE (talk to the NPC, then fetch, then return) is out of reach of a random walker, forever |
 | `never reached` | destinations the bot never came within `--reach-radius` of (default 2 m in 3D, 32 px in 2D) |
 | `never fired` | signals a `connections[]` entry listens to that never happened |
+| `declared and never read` | actions in the scene's `input{}` that NOTHING asked about, in any run — a key the control list promises and no code implements. Measured as a read, not a press, so the bot pressing it does not clear it. Two shipped starters had one: `tps-3d` declared `restart` (on `KeyR`, already the reload key) and `MISSION FAILED` was a dead end you left with F5. An action polled only on a screen no run reached lands here honestly — read it, do not gate on it |
 | `danger` | how many times the player's `Health` emitted `damaged` — and when that is ZERO, WHICH zero it is: a scene with no hazard wired at all is a walkabout and worth shouting about; a scene full of them that never landed one is a report about the BOT, which a real player would outrun less easily. Hazards are counted from the scene FILE, because a `Spawner` detaches its prefab at ready and a wave game's hazards are not in the tree yet. |
 
+**The bot presses the HUD.** Every focusable widget a player can currently see —
+`UiButton`, `UiToggle`, `UiSelect`, `UiSlider` — gets pressed occasionally,
+through the same entry point Enter and the pad's A use. That is the whole
+interface of a menu, a shop, a settings screen or an idle game, and it was on
+none of the lists the bot searched: one built from the tarball reported
+`nothing here is drivable … nothing to point at` and `✗ stuck in 2/2` about a
+game that plays perfectly. A widget under a hidden panel is not pressed, because
+a player could not press it either. `report.runs[].presses` counts them.
+
+**The bot drags between SLOTS.** Every `draggable` widget gets picked up now and
+then and dropped on a `dropTarget` that is not its own parent, through
+`dropOnto` — the same entry point a harness uses, with the same rules as the
+pointer path. An inventory is the one screen the HUD skill says a click cannot
+express, and it was the one screen the bot could not touch: a potion bench whose
+every verb is a drag reported `nothing here is drivable` and `✗ stuck in 6/6`,
+and now reports `324 slot drag(s)` and which of its wires never fired.
+`report.runs[].widgetDrags` counts them.
+
+**The line names every channel it used**, not the first one that fired: a game
+played by dragging AND by keys reports both counts, because an either/or ladder
+printed the drags and said nothing about three hundred key presses on the same
+run.
+
 **The bot can use the MOUSE.** If your scene has `Clickable` nodes, it presses
 and releases over them at random — through the real `Clickable`, the real
 `mouseJustPressed` edge and your real connection, with a picker that answers
@@ -70,6 +94,12 @@ A random clicker still cannot finish a game that needs a SEQUENCE — select a
 trooper, then a tile, then end the turn — and that is reported as unmeasured,
 not failed.
 
+**A wire on a HUD widget is visible now too.** The whole screen-space subtree was
+skipped when the run collected signals — right for "never reached", which is
+about walking, and it took every `pressed`, `changed` and `dropped` wire with
+it, so the line that exists to say "this wire does nothing" could never say it
+about a HUD.
+
 **Nothing here is a guess about your design.** The scene already declares what
 winning is; this only listens.
 
@@ -102,10 +132,38 @@ geometry says you cannot. Check the jump height, the gap, the collider.
 **`never fired`** means you drew a wire that does nothing. Either the signal is
 unreachable or the connection is wrong.
 
+**`silent`** names a declared emitter — an `AudioPlayer`, a particle node — that
+never went off in any run. Emitters on a SPAWNER's prefab count: the template is
+lifted out of the tree at load, so the check reads the scene FILE as well as the
+loaded tree, and a wave of forty enemies is reported as its one authored
+emitter, not forty.
+
 **`nothing here can hurt you`** is a design report, not an error. Sometimes it
 is exactly right (a walking simulator). Usually it means the hazards are not
 wired up.
 
+**`!` lines** are what the ENGINE warned about during the runs — a camera whose
+`follow` resolves to a node with no position, a `DayNight` with no sky, a body
+with no collider. They are not failures and they do not change the exit code;
+they are the things that leave a game running and wrong, and they are usually
+the first thing to read. One line per distinct warning, however many times it
+fired.
+
+**`error`** prints the throw under it — the behavior, the node and the
+exception, in the engine's own words:
+
+```
+  ✗ error in 8/8
+      behavior 'Boom' on /Game/Player/Sword (Node2D) threw in update — THE
+      SCRIPT is now skipped … Error: the sword script is broken
+```
+
+A script that throws in `update` is quarantined (the node keeps running, its
+script does not), so everything downstream of it simply stops happening and
+every other line of the report describes the silence rather than the cause.
+Read this one first. `incanto-verify` carries the same lines under its `plays`
+rung.
+
 **`stuck` in every run** means the player is not going anywhere: wedged in
 geometry, spawned inside a collider, or missing the input map that moves it.
 That is a real bug and worth chasing.
@@ -156,6 +214,18 @@ real thing:
 bunx incanto-playtest src/game.scene.json --behaviors src/behaviors.ts
 ```
 
+**More than one file.** Behaviours split as a game grows — bosses in `boss.ts`,
+the scene table in `scenes.ts` — so comma-separate them or repeat the flag,
+rather than writing a barrel that re-exports everything for the CLI's benefit:
+
+```bash
+bunx incanto-playtest src/game.scene.json --behaviors src/behaviors.ts,src/boss.ts
+bunx incanto-verify   src/game.scene.json --behaviors src/behaviors.ts --behaviors src/boss.ts
+```
+
+Every bin that takes `--behaviors` accepts both forms: `check`, `playtest`,
+`verify`, `feel`, `play`, `multiplay`.
+
 ## From TypeScript
 
 ```ts
@@ -166,7 +236,13 @@ console.log(playtestText(report));
 ```
 
 `report.runs` carries per-run outcome, timing, reached paths, fired signals,
-damage and the replay.
+damage and the replay. `report.inertActions` is the dead-control list above.
+
+The same question, without a playtest — after any run, scripted or hand-driven:
+
+```ts
+game.engine.input.unreadActions();   // ['restart'] — declared, nothing read it
+```
 
 ## Pairs with the feel report
 

package/skills/incanto-save-slots.md

@@ -42,10 +42,17 @@ Reloading from source sidesteps all three. The structure comes from the file
 (authoritative, already validated); the save carries only what the file cannot
 know.
 
-**The cost, stated plainly: spawned enemies and mid-level positions are not
-restored.** You resume at the scene's start with stats, inventory, unlocks and
-quest flags intact — a checkpoint save. If your game needs a position, save it:
-`serialize()` returns anything.
+**The cost, stated plainly: spawned enemies, mid-level positions and anything
+else that lives in the TREE are not restored.** You resume at the scene's start
+with stats, inventory, unlocks and quest flags intact — a checkpoint save. If
+your game needs a position, save it: `serialize()` returns anything.
+
+"Inventory" there means a behavior's DATA — a list of item ids, a wallet, a
+quest flag. An inventory made of WIDGETS MOVED BETWEEN SLOTS
+(`incanto-hud.md`'s drag recipe) is structure, so it reloads exactly as the
+file has it: measured on a bench with one item dragged across, the save
+mentions no slot and the reload puts the item back on its shelf. That skill
+prints the `serialize` that keeps the slot map as data.
 
 **What the run CONSUMED is remembered.** Reloading from the file brings back
 every gem you already picked up, which would let a collect-five-to-win run
@@ -83,11 +90,59 @@ class QuestLog extends Behavior {
 `maxHealth` no — that comes back from the scene JSON, and duplicating it makes
 old saves fight your balance patches.
 
+**Randomness is carried for you.** `captureState()` records where
+`engine.rng` has got to and `restoreState()` puts it back, because without that
+a load replays the seeded sequence from the top — the first "random" event after
+a save is the one the RUN opened with, and every loot roll, wander and spawn
+wobble repeats the opening of the game. Nothing to do; `engine.rng.position` is
+readable if you want it for something else.
+
 `deserialize` is defensive on purpose: that data may come from a build of your
 game that shipped six weeks ago. Check what you read.
 
-Built-ins that already save: `Health` (current, dead), `ScoreKeeper` (score,
-lives, won/lost), `Collector` (total).
+Built-ins that already save: `Collector` (total), `Currency` (amount),
+`DayNight` (hour, paused), `Health` (current, dead), `SavePoint` (playtime),
+`ScoreKeeper` (score, lives, won/lost), `WaveSpawner` (which wave).
+
+`WaveSpawner` RESTARTS the wave you were on rather than resuming mid-spawn —
+spawned entities are never restored, so resuming "four enemies into wave 3"
+would resume a wave whose enemies do not exist. `waveStarted` fires again, so a
+HUD wired to it catches up on its own.
+
+Every one of them needs a `uid` on its node, and `incanto-check` says so if it
+has none — that check reads the same list.
+
+## Tell the screen: `announce()`
+
+`deserialize` writes fields. Your HUD is wired to **signals** — that is what
+`incanto-hud.md` teaches and the only thing the editor can wire — so a restore
+that only writes fields leaves the screen showing a fresh start:
+
+```
+HUD    score="0"    hp=100/100  gems="0"
+TRUTH  score=1400   hp=38       gems=7
+```
+
+with no error anywhere and a restore report of `{missing: [], restored: 3}`.
+
+So there is a third hook, called once after the whole restore pass:
+
+```ts
+override announce() {
+  this.emit('questChanged', this.stage);   // what the screen SHOWS
+}
+```
+
+**Emit only what displays.** Not `died`, not `won`, not `levelUp` — a save is
+being read, nothing just happened, and re-firing an outcome signal on load is
+how a Continue lands straight on the game-over screen it was loaded to escape.
+It runs after every `deserialize` in the pass, so a handler that reads a sibling
+sees restored values there too.
+
+`Health`, `ScoreKeeper`, `Collector` and `Currency` implement it. `ScoreKeeper`
+gained **`livesChanged`** for this: `lifeLost` is the EVENT (flash, sound,
+respawn) and fires only on a real loss, while `livesChanged` is the COUNT and
+fires on both. Wire a lives counter to `livesChanged`.
 
 ## Every node you save — and every node that VANISHES — needs a uid
 
@@ -109,6 +164,20 @@ it just wrote is already wrong. It does not guess a replacement: a uid survives
 a rename and a reparent, and a saved PATH would point at whatever node moved
 into that slot after your next edit.
 
+**Put the uid on the node that OWNS the state, not on its art.** A collectible
+is normally one node with the script and a plain child for the sprite:
+
+```jsonc
+{ "name": "Sword", "type": "Area2D", "uid": "n_sr9scvhygy01mgxr",
+  "script": { "name": "ItemPickup" },
+  "children": [ { "name": "Icon", "type": "Sprite2D" } ] }   // no uid needed
+```
+
+Freeing the sword takes the icon with it, so the parent's uid in `#freed`
+records both — the audit says nothing about the child, and adding a uid to it
+changes nothing. What the audit still catches is the child that goes while its
+parent LIVES: that one really does come back.
+
 
 
 The uid is the join key, because it is the one identifier that survives a rename
@@ -156,6 +225,35 @@ if (slot) {
 `onReady` is where a behavior sets its starting values, so restoring first would
 be overwritten.
 
+**Not from `onReady` itself, either**, which is the tempting place to put
+"continue my run" and the one that cannot work: the ready pass runs while the
+scene is still loading, and `engine.scene` — which both halves of this API read
+— is not assigned until `setScene`. Both say so now rather than answering
+quietly:
+
+```
+[incanto] restoreState() ran before the engine had a scene, and restored NOTHING.
+```
+
+Before that it reported every uid in the save as `missing`, which is the
+signature of a save format change, so the hunt started in the wrong place
+entirely.
+
+**To keep the continue INSIDE the game** (where a harness can reach it —
+`runScript` boots the scene, never your `main.ts`), do it on the first frame:
+
+```ts
+class Game extends Behavior {
+  private continued = false;
+  override update(): void {
+    if (this.continued) return;
+    this.continued = true;
+    const slot = this.slots.read('1');
+    if (slot) this.engine.restoreState(slot.state);
+  }
+}
+```
+
 It never throws. A save naming a uid this build deleted reports it in
 `report.missing` and restores everything else; refusing to load would mean a
 patch that moves one node deletes everyone's progress.
@@ -235,6 +333,63 @@ slots.clear();                            // "delete all data"
 One `SavePoint` per slot is the declarative version: three nodes with
 `slot: "1" | "2" | "3"`, each probing into its own row of the menu.
 
+### Restore into a scene that has been PLAYED
+
+A save is restored INTO a freshly loaded scene. The structure comes from the
+file; `#freed` then takes away the nodes that run had consumed — and nothing
+puts any back. So a pause-menu Load, a slot menu, or death wired straight to
+`SavePoint.restore()` leaves THIS run's collectibles deleted:
+
+```
+CONTROL restart the scene from source, then restore → gems [Gem2,Gem3], won
+death wired straight to restore (no reload)         → gems [Gem3],       lost
+```
+
+…and the next autosave writes that hybrid back to the slot, so the unwinnable
+run survives a page reload. Reload first — `GameFlow.restart` with
+`restoreOnReady`, or `restartScene(engine)` and then restore. After a restart
+the SavePoint node is a NEW one, so a held behavior reference is stale.
+
+`report.stale` names the authored nodes this tree consumed that the save does
+not account for, and the engine warns when it is non-empty. It is a warning
+rather than an error because a node that freed ITSELF on a timer lands in the
+same set, and only your game knows which of its nodes are transient.
+
+### A save hook that throws
+
+`serialize()`, `deserialize()` and `announce()` are your code, and your code
+throws. All three are caught now, and each says something different:
+
+- a **`serialize()`** that throws leaves a HOLE in the save — that behavior's
+  whole run is missing — so `SavePoint.save()` **refuses to write** and emits
+  `saveFailed` instead of `saved`. Overwriting the previous slot with a holed
+  save destroys the progress the player actually had. `engine.lastCaptureFailures`
+  names them if you call `captureState()` yourself.
+- a **`deserialize()`** that throws is in `report.skipped` as before, and now
+  also in **`report.refused`** with the reason — a save this build cannot read
+  and a node with no `deserialize` at all are different problems.
+- an **`announce()`** that throws means the state IS restored and the SCREEN was
+  not told: **`report.unannounced`**. It reported `restored: 2, expected: 2`
+  over a HUD showing zeros, and it does not take an override to reach — a
+  `getNode('HUD/ScoreLabel')` on a renamed node lands there.
+
+### A save that cannot be read
+
+A truncated write (a power cut, a tab closed mid-save) or a slot from a build
+that predates this one is not offered by `all()` — but it is not *gone* either,
+and a load menu that quietly shows one fewer row than the player remembers is
+the worst thing a save system can do:
+
+```ts
+for (const { id, why } of slots.problems()) {
+  render(`slot ${id}: ${why === 'corrupt' ? 'damaged' : 'from an older version'}`);
+}
+```
+
+The slot INDEX is rebuilt from storage when it cannot be read, so one corrupt
+byte in a derived list no longer hides every save on the machine — nor lets the
+next `write()` orphan them. It says so on the console when it does.
+
 ## Checking your coverage
 
 ```ts