incanto 0.69.0 → 0.71.0

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
@@ -167,6 +259,20 @@ widget use `UiButton`'s `pressed`.
 Setting `.value` from a behavior updates the control and does **NOT** re-emit
 `changed` — restoring a saved setting must not fire the handler that saved it.
 
+**`choose(value)` is the other half**: set it as a PERSON would, and say so.
+`UiButton` has always had `press()`; the value widgets had nothing, so a preset
+button, a "reset to defaults", a tutorial that moves a slider for you, or a
+harness checking its own options screen had no public route at all.
+
+```ts
+(hud.getNode('%Volume') as UiSlider).choose(0.25);      // clamped, emits changed
+(hud.getNode('%Invert') as UiToggle).choose(true);
+(hud.getNode('%Quality') as UiSelect).choose('high');   // an option it does not
+                                                        // offer is refused
+```
+
+Both are silent when nothing changes.
+
 **Every prop is live.** `color`, `size`, `width`, `background`, `label` and
 `anchor` are re-read each frame, so flashing the score red, growing a health bar
 or moving a widget to another corner all work from a behavior — and from the
@@ -204,12 +310,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 +363,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

package/skills/incanto-localization.md

@@ -64,7 +64,7 @@ A text prop becomes translatable by naming a key with `@t:` — the same shape a
 the `"$assetKey"` references you already write:
 
 ```json
-{ "name": "Start", "type": "UiButton", "props": { "text": "@t:menu.start" } }
+{ "name": "Start", "type": "UiButton", "props": { "text": "@t:menu.start" } },
 { "name": "Wave",  "type": "UiText",   "props": { "format": "@t:hud.wave" } }
 ```
 
@@ -101,10 +101,18 @@ param is left alone rather than blanked.
 
 ### Authoring the table
 
-The scene header's **advanced** section has a `strings` field — the same
-raw-JSON editor `input` and `multiplayer` use. Until 0.61 it was the one of
-those three the panel did not show, so a localized game could be read by the
-editor and never authored in it.
+The scene header has a **strings** table: one row per key, one column per
+language, `+ key` and `+ language`. Two things it shows that the JSON cannot:
+
+- an **untranslated cell** shows the English it will silently fall back to,
+  greyed — that fallback is the design, not an error, and this is where you see
+  it happening;
+- a key the **base locale is missing** is marked red, because that is the one
+  case that really breaks: nothing to fall back to, so the raw key paints.
+
+Deleting a key a prop still says asks first, and tells you how many props will
+start painting the key. The raw-JSON `strings` field is still in **advanced**
+for pasting a whole table in at once.
 
 ## Checking a translation without a browser
 

package/skills/incanto-multiplayer.md

@@ -34,6 +34,16 @@ Authority rules:
 - movement/cosmetics → **owner-authoritative** (the replication below)
 - score/economy/inventory → **server-function-authoritative** (extend `server.js`;
   `$sender.account` is trustworthy, args are NOT; guard with `$lock`)
+
+  > **`$lock` is NOT reentrant.** Taking one key inside another's callback —
+  > `$lock('clock')` inside `$lock('match')`, one string apart in a
+  > read-modify-write — DEADLOCKS. The preview server runs every client's calls
+  > one at a time, so one stuck call wedges the whole match: every
+  > `setMyState` stops, new players can never join, and `local.tick()` never
+  > resolves. It says so now (`a call has been running for over 5s and every
+  > other client is blocked behind it`) instead of hanging in silence, and
+  > `incanto-multiplay` prints its verdict instead of exiting 13 with nothing.
+  > Take one lock, do the whole read-modify-write inside it, and release.
 - physics/AI run client-side; one-simulator needs (NPC waves) use the host-client pattern
 
 ## Scene JSON
@@ -61,7 +71,9 @@ working game's. All three are hard `BAD_FORMAT` errors now, and
              — write ["position"] (on 'Player')
 ```
 
-Valid keys: `mode` (`owner` | `observer`), `sync` (array of prop names),
+Valid keys: `mode` (`owner` — the only one the engine reads; `observer` was a
+sketch that shipped in the validator's list and was never implemented, so it is
+now refused by name), `sync` (array of prop names),
 `throttleMs` (number). An `owner` with an empty `sync` is an error too — it is
 a half-finished edit that behaves exactly like a broken one.
 
@@ -76,7 +88,11 @@ a half-finished edit that behaves exactly like a broken one.
   keyframe (`keyframeMs`, default 2 s) comes round, which is also what heals a
   send that never reached the wire. Spawned entities (bullets,
   pickups) go through **collections**, never extra owner nodes.
-- **`NetworkSpawner`** (register with `registerNodesNet()`): `source: "users"` spawns one
+- **`NetworkSpawner`** (register with `registerNodesNet()`): **`scene` is REQUIRED** —
+  the key you registered the remote's scene under. Without one the spawner used to
+  return from every frame and no remote ever appeared, on a scene that loaded,
+  audited and played clean. A spawner in a game with no multiplayer at all says so
+  after two seconds, by name. `source: "users"` spawns one
   instance of the registered scene per OTHER account (self skipped); the flat `sync` patch
   applies onto the spawned scene's root; `position` lerps when `interpolate: true`
   (remote entities render slightly in the past — that's correct). Emits
@@ -98,7 +114,10 @@ import { NetworkManager, registerNodesNet, LoopbackHub } from 'incanto/net';
 // node (`Unknown node type 'Node2D'`).
 registerNodes2D();
 registerNodesNet();
-const scene = loadScene(json);
+// `{ engine }` on a MANUAL boot, always: `onReady` runs during the load, and a
+// behaviour that reads `this.engine`/`this.rng` there (Wander draws its first
+// heading in it) throws TREE_VIOLATION without it.
+const scene = loadScene(json, { engine });
 engine.setScene(scene);
 
 // DEV / offline / split-screen: zero infrastructure, built-in protocol only
@@ -142,6 +161,31 @@ delta-merged ARRAY `[{...state, account, __updated}]` → an account-keyed Recor
 `subscribeRoomCollection` arrives as `{items:[{__id,…}], changes}` → a `__id`-keyed
 Record. It also re-issues every subscription after a reconnect.
 
+**When the socket drops it keeps trying** — 0.5s, 1, 2, 4, then 8 up to eight
+attempts — and SAYS so on the first failure and again if it gives up:
+
+```
+[incanto] the multiplayer connection dropped and the server would not take it
+back (ECONNREFUSED). Retrying — other players cannot see this one until it
+comes back.
+```
+
+There used to be one attempt and no catch, so a server that was still
+restarting rejected it, the rejection escaped an unawaited `void reconnect()`,
+the re-issue loop never ran and nothing scheduled a second try: **the session
+never came back, and nothing said a word.** A `connect()` that resolved `false`
+was taken for success and re-issued every subscription onto a dead socket.
+
+**A replication send that fails now reaches `stats().errors`.** It was
+`void this.setMyState(…)`, so the rejection went to the host's
+unhandled-rejection channel — not `engine.log`, not the error count. A client
+whose socket died kept playing perfectly on its own screen while everyone else
+watched it frozen, and the run reported `errors: 0`.
+
+**A transport that REFUSES the connection now throws** `NETWORK_UNAVAILABLE`
+out of `NetworkManager.create`, instead of returning a fully-formed manager
+with `connected === false` that had joined nothing.
+
 ## Writing a custom transport (any backend)
 
 Implement `NetworkTransport` (exported from `incanto/net`): `connect`/`disconnect`,
@@ -354,6 +398,22 @@ Kernel constraints (agent8 platform facts — don't fight them):
 - room data is ephemeral — persist to `$global` before rooms empty
 - never expose unthrottled per-frame remoteFunction (rapid calls are rejected); guard score/economy with `$lock`
 
+## Changing scene in a multiplayer game
+
+A manager is bound to the ROOM the scene it was created for declares.
+
+- **Same room, new scene** (level 2 of one match, a map vote): nothing to do.
+  The manager rebinds to the incoming tree and keeps broadcasting; the new
+  owner node re-sends its full state.
+- **Different room** (lobby → match, leaving for another arena): create a NEW
+  manager for the new room. Broadcasting stops on purpose — leaking one room's
+  state into another is exactly what the binding prevents — and the engine logs
+  an error saying which room it is bound to and which the scene asked for.
+
+Dispose the old handle whenever you like, before or after creating the new one:
+disposing a handle that a later `create()` already superseded leaves the live
+manager alone.
+
 ## State rules
 
 - JSON-safe by construction: vectors as arrays, no `undefined`/`NaN`/typed arrays
@@ -392,3 +452,23 @@ changed nothing — a ✓ that could not have been a ✗.
 
 If your server cannot be loaded the run REFUSES rather than quietly measuring a
 game without its own rules.
+
+**Pass `--behaviors src/behaviors.ts` too.** A sync key is very often written by
+game TypeScript (`player.firing = input.isPressed('fire')`), and without the
+behaviors the harness cannot tell a DEAD sync key from one whose writer was
+never loaded — so it says nothing about them at all. With the behaviors there,
+a key the owner cannot read is reported as what it is:
+
+```
+✗ p1 declares `firing` in its `network.sync` and cannot READ it — it is never
+  sent, so no client will ever see it change.
+```
+
+That is the most complete failure of replication there is, and the rung used to
+grade it PASS: an unreadable key was dropped from the comparison, so
+every client agreed perfectly about a value nobody ever sent.
+
+**`collection:` spawners are compared too.** The account-keyed half of the check
+cannot see them — a bullet has no account — so a spawner that took a hundred
+entities off the wire and materialised none of them used to be entirely silent.
+Now it says which spawner, and how many entities it dropped.