incanto 0.69.0 → 0.70.0

package/skills/incanto-editor.md

@@ -18,8 +18,20 @@ bunx incanto-editor level.scene.json --output build/level.scene.json --port 5179
 
 **Project mode** (no file argument — the usual way) scans the current directory for
 `*.scene.json` (skipping node_modules/dist/hidden dirs): one scene auto-opens; several
-open the scene browser. The page can only ever address `*.scene.json` files under the
-launch directory.
+open the scene browser.
+
+**What the server will and will not touch**, since the browser lists every
+`.json` and the answer comes from the server:
+
+| | |
+| --- | --- |
+| reads | any `.json` **under the launch directory** — but only sends it if it IS a scene; anything else comes back with the reason and its contents never leave |
+| writes | a scene, over a file that is already a scene, or to a file that does not exist yet |
+| refuses | a path outside the project, a non-scene body, and **overwriting a file that is not a scene** — `?file=package.json` gets a 409 naming what it found |
+
+That last row used to be missing: the write path checked the body and never what
+it was about to land on, so one query parameter could replace a manifest with a
+scene. The GET on the same endpoint already refused it.
 
 ### The scene browser (`scenes`)
 
@@ -108,7 +120,13 @@ Opens a local page (default `http://127.0.0.1:5179/`) with three panes:
   changed. A prop is rewritten only if its type declares `nodePath: true`, so a
   text prop that merely reads "Player" is never touched. `+` adds a child of any registered
   type, `✕` deletes the selection. Selecting the ⚙ scene row edits the header
-  (dimension, gravity with real inputs, environment/input/assets/multiplayer/strings).
+  (dimension, gravity with real inputs, environment/input/assets/multiplayer),
+  including a **STRINGS table** — one row per `@t:` key, one column per
+  language. It shows the two things raw JSON cannot: an untranslated cell shows
+  the English it will silently fall back to (greyed, because that fallback is
+  the design), and a key the BASE locale is missing is marked in red, because
+  that one has nothing to fall back to and paints the raw key on screen.
+  `+ key`, `+ language`, and deleting a key that a prop still says asks first.
 - **CONNECTIONS on the selected node** — the inspector's last section shows what
   the node **emits** and what it **receives**, each row being signal → target →
   handler with a ✕ to remove and `+ connect` to add. Signals come from the node
@@ -116,8 +134,12 @@ Opens a local page (default `http://127.0.0.1:5179/`) with three panes:
   node in the scene; the handler is a dropdown of real methods when the target
   has no script, and free text when it does (those handlers live in your
   TypeScript, which the editor never loads). An end that no longer resolves is
-  marked red with the reason. For what a row cannot express — `filter`, `once`,
-  bound args — the scene header still has `connections` as raw JSON.
+  marked red with the reason. For what a row cannot express — `filter` and `once`
+  — the scene header still has `connections` as raw JSON. (It used to say "bound
+  args" as well: a connection has never had them. Its keys are exactly
+  `[signal, from, to, handler, once, filter]`, and since they became a closed
+  set an invented one is a load error rather than a key that quietly does
+  nothing.)
   **Validation now runs WITH connections**: the editor used to strip them before
   loading, so it reported green for a scene the game hard-fails to open.
 - **Viewport with DIRECT MANIPULATION** — a mode toolbar (top left) + the
@@ -167,8 +189,11 @@ Opens a local page (default `http://127.0.0.1:5179/`) with three panes:
   `invulnerableFor`/`freeOnDeath` with their defaults; a `Patrol`'s `mode` is a
   `loop`/`pingpong` menu), delta-only like every other field. A name that is NOT
   built in is your game's TypeScript: it keeps the raw-JSON props box and says
-  so, with copy-paste Behavior boilerplate in its help — and `groups` (tag
-  chips). Every one has a `?` help popover with examples. Values equal to the
+  so, with copy-paste Behavior boilerplate in its help — `groups` (name chips)
+  and `tags` (the node's free-form identity JSON: what
+  `connections[].filter.tag` matches on, and where a chart, a card or a loot
+  entry lives; a value the loader would reject is marked invalid rather than
+  written). Every one has a `?` help popover with examples. Values equal to the
   default are removed (delta-only, like the serializer).
   **A prop that holds a NODE PATH** (`Chase.target`, `Camera2D.follow`,
   `Spawner.prefab`, `Joint3D.target`, `skinPath`, `terrain`…) offers every node
@@ -358,6 +383,20 @@ editing wherever the simulation happened to be. Games hosting the editor
 themselves (`createGame3D({ editor: … })`) get a **save** button only when they
 pass `editor.save` — otherwise edits live as long as the session does.
 
+**The handle you booted with does not survive the round trip.** ▶ builds a NEW
+game, so after one ✎→▶ the `game` your app is holding refers to something that
+no longer exists. It is inert rather than destructive — a stale `dispose()` and
+a stale `openEditor()` both do nothing — but if your app keeps using the handle,
+take the live one:
+
+```ts
+let game = await createGame3D({
+  scene, canvas,
+  debug: DEBUG,
+  editor: DEBUG && { library: true, onReboot: (next) => { game = next; } },
+});
+```
+
 ## Animating a model from the inspector
 
 Select a `ModelInstance3D` and everything about what it is DOING sits in one

package/skills/incanto-environment.md

@@ -201,6 +201,24 @@ template). Options: `seed`, `size` (32 blocks), `height` (8), `water`. The
 voxel `generateIsland` (radial dome falloff, sandy shore) also remains for
 the same use case.
 
+**Digging and building** is the node's own API, and for a long time none of it
+was written down here — the whole point of a voxel world is that it changes:
+
+```ts
+const world = this.node.getNode('World') as VoxelGrid3D;
+world.tileAt(x, y, z);              // the tile there, or undefined
+world.removeBlockAt(x, y, z);       // dig — true if there was one
+world.addBlock({ x, y, z, tile: 3 });
+world.setBlocks(blocks);            // replace the lot (emits `blocksChanged`)
+world.blockCount();                 // how many are standing
+world.blocks();                     // every one of them, to save or inspect
+```
+
+Grid coordinates, not world ones — multiply by the node's `blockSize` to place
+something on a block. `TileMap2D` answers the same questions in two dimensions
+(`cellAt`/`tileAt`/`worldAt`/`setTile`), and that one takes WORLD coordinates
+because a flat world has a cursor in it.
+
 ## Library
 
 ```ts
@@ -609,7 +627,7 @@ is radians of `atan(|∇h|)`. Default textures stream from the live agent8 CDN
 | `theme` | `"island"` | see table — `custom` requires `layers` |
 | `roughness` | `0.5` | detail-octave persistence (higher = more rugged) |
 | `detail` | `4` | detail octave count |
-| `flatThreshold` | `0.95` | snap-flatten heights within ±0.6 m of `maxHeight·flatThreshold` |
+| `flatThreshold` | `0.95` | snap-flatten heights within ±0.6 m of `maxHeight·flatThreshold` — a fraction of the SCALE, not of the peak, so the default plateau lands around 18% of the realized height (measured: maxHeight 28 → band at 26.6, peak 150). Read `heightAt` before choosing one |
 | `islandEdge` | `null` | `null` = theme decides; force the rim wrap on/off with a boolean |
 | `layers` | `[]` | custom splat layers (theme `custom` only) |
 | `textureBase` | agent8 CDN | base URL: `<base>/<name>.png` + `<base>/<name>_normal.png` |

package/skills/incanto-game-feel.md

@@ -14,6 +14,7 @@ bunx incanto-feel src/game.scene.json
 ```
 feel of /Game/Player
 
+  pushed           'move' [1, 0]
   top speed        5.62 u/s
   to full speed    383 ms
   to a stop        133 ms
@@ -28,12 +29,58 @@ feel of /Game/Player
   jump buffer      150 ms
 ```
 
+A `✗` or `!` line above the numbers is what the ENGINE said while they were
+being taken — a script that threw and was quarantined, a camera following a node
+with no position. The measurements below it are still real (a behaviour is
+quarantined, the node is not), but a page of confident numbers taken while a
+script was dying reads as a healthy character, so read those lines first.
+
 ## Why this exists
 
+**`top speed` is what the character SUSTAINS, not its fastest frame.** The probe
+holds `move` for five seconds and takes the 90th percentile of the run, because
+the maximum belongs to whatever hit the character last. Measured on the shipped
+`platformer-2d`, whose `RUN_SPEED` is 250: it reported `top speed 300 u/s` —
+that is `KNOCK_X`, from an enemy the probe walked into — and `to full speed
+2367 ms`, which was the walk to the enemy, on a character that reaches its speed
+in ONE frame. Four numbers, all about a character being attacked. When the peak
+and the sustained speed disagree the report says so:
+
+```
+top speed        250 u/s
+to full speed    17 ms
+peak             300 u/s   ← SOMETHING ELSE moved it
+```
+
+Measure feel somewhere nothing can hit you.
+
+**A character that jumps in MID-AIR has no coyote window to measure.** The probe
+lifts the body, waits, presses, and reads "vertical velocity went up" as a jump —
+so a double jump answers yes at any delay, and so does any behaviour that pushes
+the body up while `jump` is held (a glide, a jetpack, an updraft). It used to
+print `coyote window always (no window)`, which reads as the opposite of the
+truth, on two of the six shipped starters — one of which declares
+`coyoteSeconds: 0.12` five lines from its glide. It says
+
+```
+coyote window    not measurable — this character jumps in MID-AIR
+jump buffer      33 ms   (suspect — see above)
+```
+
+and names the declared value it cannot confirm. To measure the window, probe a
+build with the air jump off.
+
 **`jumpVelocity: 4` is not a height.** It is an impulse, and what it produces
 depends on gravity, mass, drag and `fallGravity`. The apex in world units and the
 hang time in milliseconds are what you are actually choosing.
 
+**It says what it pushed.** The `pushed` line names the action AND the direction
+that produced every number under it. The probe used to hold `(1, 0)` and only
+`(1, 0)`, so a game whose movement reads the OTHER axis of the same action —
+`-v.y`, which is this engine's own documented forward, `getVector` being y-down —
+measured nothing and printed the nothing as `top speed 0 u/s` with four blank
+rows and exit 0. A racer that its own harness clocked at 41 m/s reported 0.
+
 **The windows are MEASURED, not read.** `coyoteMs` comes from probing — lift the
 character clear of its support, wait, press, see whether it launched, binary
 search the boundary. A `coyoteSeconds: 0.12` that the controller never consults
@@ -52,6 +99,29 @@ reports **0 ms**. That was a real bug in this engine's own 3D controller until
 | `coyote window` | **0 reads to players as "the controls are broken"**, not as a missing feature. |
 | `jump buffer` | 0 throws away a press made a few frames before landing. |
 
+## When it cannot move your player
+
+If the default push finds no motion, the tool SEARCHES: every declared `vector2`
+action, each pushed ±x and ±y, and it keeps whichever moved the body furthest.
+That is a fallback, never a replacement — a scene that already answered cannot
+have its numbers changed by it. Two real games it rescues: a throttle on `-v.y`,
+and a game where an unrelated `aim` happened to be declared FIRST in the input
+map (the default move action is "the first `vector2`").
+
+When nothing moves it says so instead of printing a zero:
+
+```
+  pushed           'move', 'aim' every way (±x, ±y) — the player did not move
+
+  could not move /Game/Turret: no motion in 300 frames with 'move', 'aim' pushed
+  ±x and ±y. Either the movement is not wired to a vector action, or it is
+  driven by buttons. Nothing below was measured.
+```
+
+`--move <action>` pins the action explicitly, and pinning it turns the search
+OFF — you asked about that action, so a silent answer about a different one
+would be worse than no answer.
+
 ## It reports, it does not grade
 
 There are no PASS/FAIL bands here on purpose. A twitch platformer and a survival

package/skills/incanto-gameplay-behaviors.md

@@ -71,12 +71,13 @@ warn: World/Enemy: Chase.target — '%Playerr' matches no node in this scene.
 
 — which is the one failure that used to be completely silent (a prop path
 resolves with `getNodeOrNull`, so the scene opens and the enemy just never
-chases). That is for a behaviour the ENGINE ships: `incanto-check` reads scene
-files and cannot load your TypeScript, so a `nodePath: true` prop on a
-behaviour of YOUR OWN is invisible to it. `auditScene` from `incanto/test`
-gives the identical sentence once your behaviours are registered — which is why
-every scaffolded `verify.ts` calls it before `runScript`, and why a
-hand-written harness that skips it loses this check.
+chases). It works for a behaviour of YOUR OWN too, given the file that registers it:
+`incanto-check src --behaviors src/behaviors.ts` prints the identical sentence
+for `Archer.arrowTemplate`. Without the flag the checker has no schema for your
+behaviours and their node-path props are invisible to it — which is why every
+scaffolded project's `check` script passes it, and why a hand-written one that
+does not loses the check silently. `auditScene` from `incanto/test` is the same
+audit from inside your harness, once your behaviours are registered.
 
 `Chase.target` and `FollowCamera.target` are `required`: an EMPTY one
 is a load error naming the node, not a surprise in the browser.
@@ -106,6 +107,7 @@ Hit points with regen and post-hit invulnerability (i-frames). The universal
 | `regenPerSec` | `0` | HP regained per second (0 = off) |
 | `invulnerableFor` | `0` | seconds of immunity after a hit (i-frames; 0 = off) |
 | `freeOnDeath` | `false` | `queueFree()` this node when it dies (clone-safe) |
+| `freeParent` | `false` | with `freeOnDeath`, free the PARENT — the enemy, when `Health` rides a child node |
 
 Signals: `damaged(amount, current)` · `healed(amount, current)` ·
 `healthChanged(current, max)` · `died` · `revived(current)`
@@ -150,6 +152,13 @@ still while the character heals. Use `damaged`/`healed` for reacting to the HIT
 > node-local, so it clones perfectly and frees the whole enemy with no wiring.
 > (Connections are still the right tool for NON-cloned nodes, e.g. the player's
 > `died → ScoreKeeper.loseLife`.)
+>
+> A node carries ONE script, so if the root is already taken — a `Patrol` you
+> did not give `moveParent`, an `Area2D` with a `Clickable` — put `Health` on a
+> child and add **`freeParent: true`**. Without it the child frees ITSELF and
+> the body walks on with no health at all: an immortal enemy that takes damage
+> from nothing and reports nothing. Same prop, same reason, as `Lifetime` and
+> `DamageOnContact`.
 
 ## Lifetime
 
@@ -182,7 +191,10 @@ once; reaching 0 lives emits `lost` once.
 | `lives` | `0` | starting lives (0 = lives disabled) |
 | `scoreToWin` | `0` | score that triggers `won` (0 = disabled) |
 
-Signals: `scoreChanged(score)` · `won` · `lost` · `lifeLost(lives)`
+Signals: `scoreChanged(score)` · `won` · `lost` · `lifeLost(lives)` ·
+`livesChanged(lives)` — the EVENT and the COUNT: `lifeLost` fires when a life is
+spent (flash, respawn), `livesChanged` also fires when a save is restored, so a
+lives counter belongs on that one.
 Methods: `addScore(n)` · `setScore(n)` · `loseLife()`
 
 ```json
@@ -384,7 +396,7 @@ author markers). Emits `reachedPoint(index)` on arrival.
 
 | Prop | Default | Meaning |
 |---|---|---|
-| `points` | `[]` | waypoints: position arrays or node-path strings (required) |
+| `points` | `[]` | waypoints: position arrays (LOCAL to the moved node) or node-path strings (that marker's WORLD position) — required |
 | `speed` | `60` | units per second along the path |
 | `loop` | `true` | wrap to the first point after the last (loop mode) |
 | `mode` | `"loop"` | `'loop'` wraps · `'pingpong'` reverses at the ends |
@@ -395,6 +407,18 @@ author markers). Emits `reachedPoint(index)` on arrival.
 
 Signals: `reachedPoint(index)`
 
+**The two waypoint forms are in different frames, on purpose.** An array is a
+LOCAL offset — the only thing numbers typed into a prop can mean. A node path
+means *where that marker actually is*, so markers under `/root/Path` and
+walkers under a spawn container work, which is how a lane is organised. Before
+0.71 a node path was read as a local offset too, so a walker whose parent was
+not at the markers' origin walked a shifted copy of the path in silence.
+
+Need to CHANGE the route at runtime rather than author it? That is
+`PathFollow` and its `setPath()` (see *Pathfinding*, below) — `Patrol.points` is read live
+but the index and direction are not re-derived, so writing points mid-route
+moves the corners under a walker that is still heading for the old one.
+
 ```json
 { "name": "Guard", "type": "Node2D",
   "script": { "name": "Patrol", "props": { "points": [[100, 0], [300, 0]], "speed": 80, "mode": "pingpong" } } }
@@ -576,6 +600,13 @@ placeTower(pad);
 "you cannot afford that" is one wire to a banner. It saves through `serialize()`
 like `Health` and `ScoreKeeper`.
 
+A NON-POSITIVE amount is ignored, the way `Health.damage`/`heal` have always
+ignored one — and a negative is reported, because it is a sign flip in the
+caller rather than an offer. `spend(-5)` used to PAY you five (any negative
+passes the affordability test, and the subtraction then added) and `earn(-5)`
+to take five, going round `canAfford` and `refused` entirely. `spend(0)` returns
+`true`: you can always afford nothing.
+
 ## Wander
 
 Seeded random roaming inside a circle around the spawn point — idle critters,
@@ -665,6 +696,15 @@ are NOT cloned):
 - **(B) scene `connection`** (fine for a single authored entity, NOT for clones):
   `{ "signal": "movementStateChanged", "from": "Enemy/AI", "to": "Enemy/Skin", "handler": "setClip" }`.
 
+**Subscribing in `onReady` is safe to do to anything, including a node that
+outlives you.** A connection made there is owned by the node making it, so
+`free()` takes it with the node — you do not have to keep the returned
+disconnect and call it yourself. That matters most for the shape this pattern
+invites: every enemy subscribing to the score keeper or the player, where the
+emitter outlives thousands of listeners. (Wiring a signal from a `update()` or
+from outside a lifecycle method still hands ownership to you — keep the
+disconnect, or pass `{ owner: someNode }`.)
+
 Same `ZombieSkin` is the place to also FACE the heading and GROUND the body each frame
 (see incanto-3d-character.md "+Z-FORWARD rule" and incanto-3d-models.md "Grounding").
 
@@ -722,7 +762,7 @@ all a raft, a buoy, a crate or a body needs to bob, settle and ride the swell.
 
 | Prop | Default | Meaning |
 |---|---|---|
-| `water` | `""` | Water3D node path; empty = the first Water3D in the tree (a wrong path fails hard) |
+| `water` | `""` | Water3D node path; empty = the first Water3D in the tree (a wrong path fails hard; NO water in the scene is an `incanto-check` warning) |
 | `draft` | `0.35` | where the resting WATERLINE sits below the body origin, in meters — the hull floats with its origin that far above the water |
 | `stiffness` | `3` | how stiffly it returns to that waterline (extra g of lift per draft of submersion): 1 wallows, 3 is a firm dinghy, 8 is a cork |
 | `damping` | `3.5` | vertical damping (1/s) — how fast the bobbing settles |
@@ -782,7 +822,7 @@ later clones get `EnemyTemplate2`, `EnemyTemplate3`, …)
 | Prop | Default | Meaning |
 |---|---|---|
 | `prefab` | `""` | node path of the template to clone (required) |
-| `interval` | `1` | seconds between spawns |
+| `interval` | `1` | seconds between spawns — `0` is one clone per FRAME and is refused unless `max` or `total` caps it |
 | `max` | `0` | max LIVE instances (0 = unlimited) |
 | `at` | `[]` | where the clone appears, as an offset from the spawner ([x,y(,z)]) |
 | `autoStart` | `true` | begin ticking at ready |
@@ -862,19 +902,55 @@ union-typed prop so its default is `null` (= `'forward'`).
 
 In 3D, `'forward'` is the engine's ONE facing convention — **+Z**, the same
 `atan2(dx, dz)` basis `CharacterController3D` uses and `incanto-3d-character.md`
-spells out under "the +Z-FORWARD rule". So aim the bullet (or its shooter) with
-that formula and it flies at what you aimed at; do not add 180°. (Before 0.62
-this returned three.js's −Z instead, so every `'forward'` shot left the muzzle
-pointing at the shooter's back — at the right speed, with no error, which reads
-as a gun that simply never hits anything.) In 2D `rotation` is a scalar and
-`'forward'` is +x turned clockwise by it, unchanged.
+spells out under "the +Z-FORWARD rule". So aim the BULLET with that formula and
+it flies at what you aimed at; do not add 180°. (Before 0.62 this returned
+three.js's −Z instead, so every `'forward'` shot left the muzzle pointing at the
+shooter's back — at the right speed, with no error, which reads as a gun that
+simply never hits anything.) In 2D `rotation` is a scalar and `'forward'` is +x
+turned clockwise by it, unchanged.
+
+**Aim the bullet, not the shooter.** Turning a turret does not turn a bullet
+parented under it: world position is composed TRANSLATION-ONLY, so a bolt under
+a turret at `rotation: 90` still lands at world `[100, 0]`, not `[0, 100]`. Set
+the heading on the projectile itself.
 
 | Prop | Default | Meaning |
 |---|---|---|
-| `speed` | `300` | units per second along `direction` |
-| `direction` | `null` | a vector `[x,y(,z)]` OR `'forward'` (`null` = forward) |
+| `speed` | `300` | units per second along `direction` — **live**, rescales in flight |
+| `direction` | `null` | a vector `[x,y(,z)]` OR `'forward'` (`null` = forward) — **live** |
 | `gravity` | `0` | constant +y (downward, 2D y-down) pull for arcing shots |
 
+### Aiming a bullet you just spawned
+
+Every prop above is LIVE, and the heading is resolved on the projectile's FIRST
+STEP — which is after `spawned(node)` fires. That window is the whole point:
+`SpawnSource.spawn` ends with `addChild(clone)` and `Spawner` emits `spawned`
+afterwards, so a handler is by definition "too late" for anything baked at
+`onReady`.
+
+```ts
+spawner.on('spawned', (bolt) => {
+  // either spelling works — set the node's rotation…
+  (bolt as { rotation: number }).rotation = (Math.atan2(dy, dx) * 180) / Math.PI;
+  // …or hand the behavior a vector
+  (bolt.behavior as Projectile).direction = [dx / len, dy / len];
+});
+```
+
+Mid-flight, writing `direction` or `speed` re-bakes immediately (the fall
+`gravity` has accumulated is kept — it is a fact about the world, not about the
+shot). What is deliberately NOT live is `rotation` after that first step: a
+projectile that spins for looks must not have its spin become its trajectory.
+Call **`aim()`** to re-derive from the current rotation on purpose:
+
+```ts
+bolt.rotation = newHeadingDeg;
+(bolt.behavior as Projectile).aim();        // or aim([dx, dy]) to pass a vector
+```
+
+Before 0.70 all of this was dead: `direction` accepted the write, READ BACK the
+new value, and the bolt kept flying the old way.
+
 ```json
 { "name": "Bullet", "type": "Area2D", "props": { "rotation": 0 },
   "script": { "name": "Projectile", "props": { "speed": 600, "direction": "forward" } } }
@@ -1175,6 +1251,14 @@ The panel is hidden while playing and shown while paused — `GameFlow` owns its
 `visible`, so do not set it yourself. `pauseAction` and `pausePanelPath` rename
 either half; `pausePanelPath: ""` turns it off.
 
+While the panel is up its `HudLayer` gets `focusNavigation` — arrow keys, d-pad
+and A — and the ring starts on the first widget. The layer's own value is put
+back on resume, so a game that navigates by pad all the time keeps doing so —
+unless the game CHANGED it during the pause, in which case the game had the last
+word and keeps it.
+That is the one thing every pause menu needs and nobody remembers: a menu you
+can only click is not playable on a controller.
+
 The pause key is polled in `update()`, which still runs at `timeScale 0` — a
 menu that cannot be closed by the key that opened it is worse than no menu.
 
@@ -1188,7 +1272,7 @@ physics, input. Listen to the `flowChanged(state)` signal for custom UI.
 `restartScene(engine)` is exported standalone.
 
 **Any scene swap thaws.** The freeze lives on the engine, not on the flow, so
-leaving a game-over screen by your own route — `engine.setScene(loadScene(next))`
+leaving a game-over screen by your own route — `engine.setScene(loadScene(next, { engine }))`
 from a menu button — puts `timeScale` back to 1 as surely as `flow.restart()`
 does. You cannot restart into a frozen level.
 
@@ -1211,6 +1295,12 @@ scene with no bodies still pays for nothing.
 Drives the scene `environment` (needs an atmosphere sky): sun elevation/
 azimuth arc, ambient + exposure ramps with a moonlight floor.
 
+**No `sky` in the scene environment = nothing to drive.** The clock still runs
+and `dayPhaseChanged` still fires, so the signals look right and the screen
+never changes; the behaviour says so once, in the engine log. Add
+`"sky": { "type": "atmosphere" }` to the scene's `environment` — or set it at
+runtime, which it keeps looking for.
+
 ```jsonc
 { "script": { "name": "DayNight", "props": { "daySeconds": 240, "startHour": 9 } } }
 ```

package/skills/incanto-hud.md

@@ -25,6 +25,11 @@ Declare your HUD in the scene JSON — no `index.html` markup, no CSS, no
 works identically over the 2D and 3D renderers and is a silent no-op in
 headless tests (core nodes, no three.js). Widgets pick one of 9 anchors:
 `topLeft top topRight left center right bottomLeft bottom bottomRight`.
+
+**Camel case here, hyphens in `UILayer`.** The 2D world-space layer spells the
+same nine `top-left`/`bottom-right`, and neither prop accepts the other's
+spelling — both fail at load listing their own set, so you are one edit from
+right. Worth knowing before you spend the edit.
 Widgets stacked on the same anchor form a column.
 
 ## Driving widgets from the scene JSON (no TypeScript)
@@ -36,10 +41,15 @@ are `connections[]` entries — not a behavior whose whole job is one assignment
 "connections": [
   { "signal": "scoreChanged",  "from": ".",      "to": "HUD/Score", "handler": "setText" },
   { "signal": "healthChanged", "from": "Player", "to": "HUD/Hp",    "handler": "setValue" },
-  { "signal": "lifeLost",      "from": ".",      "to": "HUD/Lives", "handler": "setText" }
+  { "signal": "livesChanged",  "from": ".",      "to": "HUD/Lives", "handler": "setText" }
 ]
 ```
 
+**`livesChanged`, not `lifeLost`, for the counter.** `lifeLost` is the EVENT — a
+life was just spent, flash the screen, respawn — and it does not fire when a
+SAVE is loaded, so a counter wired to it still read `3` after a Continue at one
+life left. `livesChanged` is the COUNT, and fires on both.
+
 ```json
 { "name": "Score", "type": "UiText",
   "props": { "anchor": "topRight", "text": "Gems 0 / 8", "format": "Gems {} / 8" } }
@@ -93,9 +103,58 @@ banner.show('YOU DIED', { color: '#ef4444', seconds: 0 }); // sticky until next
   the queue; signal `bannerShown(text)`. Props: `size` (font px), `seconds`
   (default duration).
 
+**Showing and hiding a widget is `visible`, not a method.** There is no
+`hide()`/`show()` pair on a widget: `UiBanner.show(text)` announces a LINE, and
+every widget's own visibility is the ordinary `visible` prop it inherits from
+every other node —
+
+```ts
+(this.node.getNode('%Pause') as UiPanel).visible = false;   // a whole menu, and
+                                                            // everything under it
+```
+
+A panel hides its children with it, so one write takes a whole screen away.
+(HUD widgets are screen-space, so `framing()` leaves them out entirely — asking
+whether the camera can see one is a category error.)
+
 Pair with the `Health` / `ScoreKeeper` gameplay behaviors: listen to their
 signals and write the widget props — that is the whole HUD wiring.
 
+## On a phone
+
+The nine anchors keep out of the device's own furniture: each is 16 px from its
+edge **plus** that edge's `env(safe-area-inset-*)`. Every scaffolded
+`index.html` carries `viewport-fit=cover` — which is what makes a game fill a
+phone edge to edge, and what would otherwise put `anchor: "bottom"` under the
+home indicator, where iOS takes the gesture and your button never hears the tap.
+`topRight` behind the notch and `left`/`right` under the rounded corners are the
+same story in landscape, which is how a phone is held for a game.
+
+The insets are ADDED, and every desktop browser reports 0 for all four, so
+nothing moves where there is nothing to avoid. (The touch-control overlay has
+done this since 0.42; the HUD, which is the overlay with the buttons you
+actually tap, joined it much later.)
+
+**A widget authored in pixels still fits the screen.** `UiPanel`, `UiBar`,
+`UiImage`, `UiSlider` and `UiDialogue` all cap at `calc(100vw - 32px)` — a pause
+panel at `width: 520` on a 390 px phone would otherwise hang 130 px off the
+edge, taking its buttons with it, and a panel too TALL scrolls rather than
+hiding the row that says Resume.
+
+**Every tappable widget is at least 44x44.** Measured in Chrome, a `UiButton`
+used to come out 131x37 and a dialogue choice ~50x29, while the engine's own
+touch buttons have been 64x64 and its stick 120x120 for years — the surface a
+finger actually lands on was the one nobody had sized for a finger. Apple asks
+44, Material 48, WCAG 2.5.5 44. It is a MINIMUM: a button with more text stays
+as wide as its text, and an authored `width` still wins.
+
+The layer also takes the GESTURES over itself: every widget that receives taps
+sets `touch-action: none`, and the layer turns off text selection, the iOS
+long-press callout and the tap flash. `claimCanvasGestures` has done that for
+the canvas for a while — but the HUD is a separate overlay ABOVE it, and a
+swipe that starts on the score at the top of the screen never reaches the
+canvas at all. It used to scroll the page or pull-to-refresh.
+
 ## Interactive widgets: UiButton & UiDialogue
 
 ```json
@@ -120,6 +179,18 @@ reveals the line then advances; choice lines render buttons and wait for
 `choose(i)`. Buttons opt into pointer events — the rest of the HUD stays
 click-through.
 
+**Driving them with no screen** — a HUD widget is DOM, so a headless harness
+cannot click one. Both take the gesture directly:
+
+```ts
+(hud.getNode('Start') as UiButton).press();   // emits `pressed`, as a click would
+(hud.getNode('Talk') as UiDialogue).advance(); // reveal the rest, then next line
+```
+
+That is how a title screen, a pause menu or a conversation gets tested in
+`runScript` — `click` reaches world nodes through the picker, and a widget is
+not one of those.
+
 ## Menus, options and inventories (UiPanel + the value widgets)
 
 The HUD widgets can SAY things. These arrange them and take a value back — which
@@ -151,13 +222,34 @@ so structure in the tree becomes structure on screen. Panels nest.
 | `UiSlider` | `label`, `value`, `min`, `max`, `step`, `width`, `color` | `changed(value)` |
 | `UiToggle` | `label`, `value` | `changed(bool)` |
 | `UiSelect` | `label`, `options` (`"low,medium,high"`), `value` | `changed(value)` |
-| `UiVolumeSlider` | `bus` (`master`/`sfx`/`music`), plus every `UiSlider` prop | `changed(value)` |
-| `UiMuteToggle` | `label` | `changed(bool)` |
 
-The last two are **already wired**: they read and write `engine.audio`, which
-persists itself. An audio menu is three nodes and no TypeScript — see
-`incanto-audio.md`. The graphics ones (`UiQualitySelect`, `UiFrameCapSelect`,
-`UiRenderScaleSelect`) and `UiLanguageSelect` work the same way.
+`UiSelect.value` must be one of its `options` — a value the list cannot show is
+a hard load error naming them, because the browser would show the FIRST option
+while the node went on answering with the value it was given, and `changed`
+only fires when a person moves it. (Writing one at runtime is reported rather
+than refused: a behaviour may widen `options` a frame later, and it goes quiet
+when it does.) `""` is "nothing chosen yet", which is a choice.
+### The ones that need no TypeScript at all
+
+| node | props | follows |
+| --- | --- | --- |
+| `UiVolumeSlider` | `bus` (`master`/`sfx`/`music`), plus every `UiSlider` prop | `engine.audio[bus]` |
+| `UiMuteToggle` | `label` | `engine.audio.muted` |
+| `UiQualitySelect` | — | `engine.settings` `quality` |
+| `UiFrameCapSelect` | — | `engine.settings` `maxFps` |
+| `UiRenderScaleSelect` | — | `engine.settings` `renderScale` |
+| `UiLanguageSelect` | — | `engine.locale` (options are the scene's own locales) |
+
+These are **already wired** in both directions: they show what the game is set
+to, and setting one changes the game. A whole settings screen is those six nodes
+and no TypeScript.
+
+**They follow the engine HEADLESS too**, so a harness can drive one: set
+`slider.value`, step, and assert `engine.audio.master` moved. These used to live
+on the painting side of the widget, below `update`'s early
+return for "no DOM element" — so every one of them was inert in `runScript`,
+`incanto-playtest` and `incanto-verify`, showing a `UiSlider`'s 0.5 default next
+to a master volume of 1.
 
 **An inventory is a grid panel**: `"layout": "grid", "columns": 5`, one child per
 slot, each a small `UiPanel` holding a `UiImage` (`tint` greys out what you
@@ -204,12 +296,25 @@ What activation MEANS is per widget: a button presses, a toggle flips (left/righ
 sets it explicitly, which reads better on a pad), a select walks its list, a
 slider nudges by one `step`.
 
+**A `GameFlow` pause panel arms it for you** — that screen IS a menu, it knows
+exactly when it opens and closes, and it puts the layer's own value back on
+resume. Every game with a pause menu was otherwise writing the same two lines,
+or shipping a menu that answered only to a mouse.
+
 **It is OFF by default**, deliberately: a game whose HUD happens to contain a
 button must not lose its arrow keys the moment one exists. Turn it on for the
 screens that ARE menus and off again when play resumes —
 `hud.focusNavigation = false`. `hud.focus(widget)` sets the starting item, since
 opening a menu should land somewhere rather than nowhere.
 
+**With two layers, the TOPMOST armed one takes the key** — last in the tree,
+which is the one drawn on top, and the one a modal is. Keyboard focus is
+singular by nature (a browser has one focused element); when both a HUD and a
+modal were armed, a single Enter activated the focused widget in EACH, so the
+pause menu's RESUME and whatever the screen underneath had focused both fired.
+A HIDDEN layer is not armed at all, so a closed menu never eats the key from the
+HUD it covers.
+
 The gamepad codes are the ones the engine already produces from a pad
 (`Pad12`–`Pad15` d-pad, `Pad0` = A), so nothing extra is declared.
 
@@ -244,6 +349,22 @@ A drop on nothing cancels, and so does putting a thing back into the slot it
 came from: that is not a move, and firing `dropped` for it would make every
 mis-grab look like a transfer.
 
+**A harness can make the gesture.** This is the one screen the paragraph above
+says a click cannot express, and for a long time it was also the one screen no
+headless check could reach at all — every one of the four signals lived on a
+DOM listener, so `runScript`, `incanto-playtest` and every rung of the ladder
+were blind to an inventory.
+
+```ts
+{ atMs: 200, do: (ctx) => (ctx.getNode('%Potion') as UiImage)
+    .dropOnto(ctx.getNode('%SlotB') as UiPanel) }
+```
+
+`dropOnto(target)` is to a drag what `press()` is to a click: the same rules as
+the pointer path — a non-`draggable` source does nothing, a target that is not a
+`dropTarget` cancels, and putting a thing back where it came from is not a move
+— and it returns whether the drop was taken.
+
 
 
 ## More than one language