incanto 0.68.0 → 0.70.0

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

@@ -33,14 +33,22 @@ wiring, and composition are all in the file. TS is for *behavior only* (attached
 ```
 
 - `format` MUST be `1`. `type` MUST be `"scene"`. `name` non-empty.
-- `dimension` is optional: `"2d"` or `"3d"` only.
+- `dimension` is optional: `"2d"` or `"3d"` only. Left out, it is INFERRED from
+  the node types in the tree (anything ending `3D` makes the scene 3D) — write
+  it anyway, because it is what the environment validator, the audit's
+  no-camera/no-light warnings and `physics: "auto"` all read.
 - `fragment` (optional, default `false`) says this file is a PIECE of another
   scene — a spawner's prefab, a sub-scene something instances — and is never
   rendered on its own. It changes nothing at runtime; it tells the checker to
-  stop asking a prefab where its camera and its sun are. Set it on any scene
-  you load from TypeScript and hand to a spawner. (A scene another scene
-  embeds with `instance` needs no key — `incanto-check` walks the project and
-  can see that for itself.)
+  stop asking a prefab where its camera and its sun are, and to stop answering
+  the two questions only the HOST can answer: a node path that leaves the file
+  (`/root/Bolts` is the fragment's own root only while the fragment is alone)
+  and a `DamageOnContact.targetGroup` whose victims live in the host scene.
+  Those two are still NAMED, with a reworded verdict — a typo is most likely in
+  exactly this file, written away from the scene that gives it meaning. Set it
+  on any scene you load from TypeScript and hand to a spawner. (A scene another
+  scene embeds with `instance` needs no key — `incanto-check` walks the project
+  and can see that for itself.)
 - `viewport` (optional) makes scene JSON own responsive layout: author the world
   in fixed `design` pixels (`[width, height]`, positive numbers) and the renderer
   maps them onto any canvas size. `fit`: `"expand"` (design rect always fully
@@ -96,12 +104,24 @@ Rules the engine enforces with **hard errors** (it never warns silently):
 3. Prop keys and value kinds are validated against the type's schema:
    unknown key → `UNKNOWN_PROP` (message lists valid keys); wrong JSON kind
    (e.g. string where the default is boolean) → `PROP_TYPE_MISMATCH`.
+   A few props accept TWO kinds — `Flowers3D.density` takes a preset name or
+   plants per m², `Water3D.underwater` takes `true`/`false` or a settings
+   object — and `incanto-node-reference.md` names both in its Kind column
+   (`one of: lush sparse none, or number`). The error names them too, so a
+   value the loader refuses tells you every shape it would have taken.
 4. Sibling names must be unique. Colliding names are auto-renamed by incrementing a
    trailing number (`Enemy` → `Enemy2` → `Enemy3`) — **write unique names yourself** so your
    connection paths stay valid (connections resolve after renaming).
 5. Node names must not contain `/` or `%` and must be non-empty.
 6. `groups` are string tags for queries (`getNodesInGroup`, connection filters).
    `tags` is free-form JSON for game-logic identity (`{"kind": "ITEM", "value": 10}`).
+   **`groups` is a LIST and `tags` is an OBJECT**, and the loader now says so:
+   `"groups": "player"` used to load clean and spread the string one CHARACTER
+   at a time (`["p","l","a","y","e","r"]`), so `player` was in no group and
+   every query and `filter: {group: "player"}` silently matched nothing. Every
+   node key is checked for its KIND now — `props`/`overrides` an object,
+   `children` a list, `uid` a non-empty string from `newUid()` — as are the
+   header's `constants`, `multiplayer` (objects) and `connections` (a list).
 7. `script` resolves to a registered Behavior at load (`incanto-behaviors-and-scripts.md`);
    `network` drives multiplayer replication (`incanto-multiplayer.md`). Both round-trip
    losslessly through export.
@@ -321,10 +341,21 @@ that do exist at the failing spot).
             never recovers.
   ```
 
-  `died → ScoreKeeper.addScore` is the natural way to score a kill and it sets the
-  score to `NaN` on the first one, with the win condition then permanently out of
-  reach. A handler that DEFAULTS what it is not given is correct and stays silent:
-  `won → GameFlow.win` works, because `win(text = 'YOU WIN')` needs nothing. On **both**, it is
+  `died → ScoreKeeper.addScore` is the natural way to score a kill and it used to
+  set the score to `NaN` on the first one, with the win condition then
+  permanently out of reach. The numeric handlers REFUSE a non-number now, so the
+  same wire fails loudly instead — and so does the one the arity check cannot
+  see: `clicked → addScore` hands the NODE, which is one argument into one
+  parameter, and `score + node` is a STRING that grows forever. A handler that DEFAULTS what it is not given is correct and stays silent:
+  `won → GameFlow.win` works, because `win(text = 'YOU WIN')` needs nothing.
+
+  Writing your OWN handler, the same rule applies to you: an optional parameter
+  is a **default**, not a `?`. `hurt(amount: number, from?: Node)` counts as
+  needing 2, because `?` is a TypeScript annotation that does not survive to
+  runtime — write `from: Node | undefined = undefined` and the wire is judged on
+  what it actually needs. Every engine method a wire can name has been corrected
+  to this; before that, four of five documented HUD wires were reported as
+  broken while working perfectly. On **both**, it is
   `AMBIGUOUS_HANDLER`: the node's method wins, so the script's would never run
   and nothing would say so. A core node answers to 62 public methods before any
   adapter adds more (`stop` `play` `show` `clear` `say` `start` `free` …), which
@@ -333,7 +364,11 @@ that do exist at the failing spot).
 - Unresolvable `from`/`to` → `DANGLING_CONNECTION` at load. Renaming a node breaks its
   connections **loudly** — update paths in the same edit.
 - `filter` gates firing on the first emitted argument: it must be a node in `filter.group`
-  and/or match every `filter.tag` entry. With `once: true`, the connection is consumed only
+  and/or match every `filter.tag` entry. **A filter's keys are `group` and `tag`, and a
+  connection's are `[signal, from, to, handler, once, filter]`** — anything else is a load
+  error, because a filter the matcher cannot read (`{"gruop": "player"}`, or the bare
+  string `"player"`) passes EVERYTHING, which is the opposite of what a filter is for, and
+  `"once": "no"` is truthy so it fires exactly once. With `once: true`, the connection is consumed only
   when the filter matches.
 
 ## Sub-scene composition
@@ -345,7 +380,20 @@ that do exist at the failing spot).
 - `instance` embeds another scene's tree; `overrides` deep-merge onto the sub-scene root's
   props. At the instancing site, `groups` and `children` COMPOSE (union/append), while
   `tags`/`script`/`network` REPLACE the sub-scene root's values when declared (omitted = kept).
-- The sub-scene's own `connections` are wired inside its subtree automatically.
+- The sub-scene's own `connections` are wired inside its subtree automatically,
+  and so are its `assets`, `input`, `strings`, `constants` and `orderGroups` —
+  **a prefab brings everything it declares**. (Its `orderGroups` used to come
+  through as NAMES only, so `"orderGroup": "loot"` validated and the band's
+  number was dropped: the sprite sorted in the default band and the scene loaded
+  clean.) A `coin.scene.json` with its own
+  spritesheet, or a `player.scene.json` with its own `move`/`jump` bindings, is
+  a complete, reusable thing.
+- The HOST wins any asset key, action name or string it declares itself, so a
+  level can re-point a prefab's art or rebind its controls without editing the
+  prefab. Two INSTANCED scenes declaring one asset key with different urls — or
+  one action name with different keys — is a hard error naming both:
+  first-writer-wins would hand the second prefab the first one's art in silence.
+  The same key with the same value is just two prefabs agreeing.
 - There is **no** scene inheritance — composition only.
 - Current limitation: exporting expands instances into full trees (the `instance` reference is
   not preserved on export yet).
@@ -373,6 +421,12 @@ that do exist at the failing spot).
 | `DUPLICATE_BEHAVIOR` | two classes registered under one behavior name | rename one, or `{ replace: true }` for hot reload |
 | `TREE_VIOLATION` | invalid name, re-parenting without detach, cycles, double root | follow the rule in the message |
 
+Every one of these lists what WOULD have worked, and names the nearest
+candidate when there is one — `Unknown node type 'Label2D'. Did you mean
+"Label"?`, `Unknown prop 'size' on 'Label'. Did you mean "fontSize"?`. A name
+that resembles nothing gets the list alone, because a suggestion that is not the
+answer is worse than none.
+
 Scene-load and registry errors carry structured `details` (`path`, `uid`, `nodeType`,
 `prop`, `signal`, `validOptions`) mirroring the prose — prefer those over regexing the
 message (a few runtime errors still carry prose only). Scene-load
@@ -384,7 +438,10 @@ errors append the offending node's path: `… (at '/Level/Enemies/Slime3')`.
 import { loadScene, registerCoreNodes, duplicateNode } from 'incanto';
 
 registerCoreNodes();                            // explicit — never an import side effect
-const scene = loadScene(json, { resolveScene }); // throws IncantoError on any problem
+// `{ engine }` on a manual boot: `onReady` runs during the LOAD, so a behaviour
+// that reads `this.engine` or `this.rng` there throws without it. `createGame2D`
+// /`3D` and `runScript` pass it for you.
+const scene = loadScene(json, { engine, resolveScene }); // throws IncantoError on any problem
 scene.root.getNode('Player').emit('hit', 10);
 const copy = duplicateNode(scene.root.getNode('Coin'));
 const exported = scene.toJSON();                 // lossless (delta-only props)

package/skills/incanto-verifying-your-game.md

@@ -34,7 +34,7 @@ $ bunx incanto verify                       # finds your scene AND your behaviou
 ✓ loads — the scene is legal and its assets resolve
     ! /Game/Chest: script Chest — target '%Ke' matches nothing
 ? plays — 8 runs played without reaching a win (4 lost, 4 ran out the clock)
-✓ feels — 5 of 7 fired — silent: /Game/Boss/Roar, /Game/Boss/Boom
+? feels — 5 of 7 fired — silent: /Game/Boss/Roar, /Game/Boss/Boom
 · agrees — not run — this scene has no `multiplayer` header
 ? draws — the dev server is running on :5173, but no page answered
 
@@ -106,8 +106,17 @@ and a run without `--behaviors` reports that instead: neither is a broken game.
 `feels` is the sound-and-effects rung: it lists what the scene DECLARES against
 what actually fired during the playtest. A game whose feedback is wired but
 never triggered plays perfectly and feels dead, and every other rung calls it
-healthy. Nothing firing at all is a failure; some nodes staying silent is
-reported by name, because the bot may simply never have reached the boss.
+healthy. Nothing firing at all is a FAILURE. Some nodes staying silent is
+`unmeasured` (`?`) with the names listed — a silent emitter is either a broken
+wire or a moment random play never reached, and the two look identical from
+here. Reach it in a scripted run and this rung can tell you which. It ticks
+(`✓`) only when every declared emitter fired.
+
+`says` reads the running page's own log. Errors and failed assets fail it;
+WARNINGS are carried under it with a `!` and it still passes — a camera whose
+`follow` points at a node with no position, a `DayNight` with no sky to move, a
+body with no collider. Those leave a game running and wrong, and they are the
+lines worth reading before anything else on this list.
 
 Exit 1 only when a rung actually failed. `--behaviors src/behaviors.ts` matters:
 without it your game logic is stubbed and only the structure is played.
@@ -116,6 +125,16 @@ The sections below are the same rungs one at a time, for when you need the detai
 
 ## 1. After EVERY scene edit: `incanto-check`
 
+```bash
+bunx incanto-check                                  # structure, assets, semantics
+bunx incanto-check --behaviors src/behaviors.ts --strict-behaviors
+```
+
+`--strict-behaviors` makes a `script.name` that resolves nowhere a FAILURE
+instead of a stub — and it needs `--behaviors` to know what you registered.
+Without it, on any project with a behaviour of its own, it could only ever fail:
+`Unknown behavior 'Hunter' … Did you forget registerBehavior?`
+
 ```bash
 bunx incanto-check               # validates every *.scene.json under cwd
 bunx incanto-check --json        # machine-readable (code + details.path/prop)
@@ -211,6 +230,22 @@ console.log(result.describe());        // run report + final scene, one line per
 if (!result.ok) process.exit(1);       // failures carry atMs + label + message
 ```
 
+**An assert fails on `false`, on a non-empty STRING, or on a throw.** The
+string is used as the message, which is how a harness explains itself:
+
+```ts
+assert: (ctx) => {
+  const lives = (ctx.getNode('Score').behavior as never as { lives: number }).lives;
+  if (lives <= 0) return `the keep fell — ${lives} lives`;   // the failure, in words
+  return null;                                               // nothing to say
+}
+```
+
+`true`, `null`, `undefined` and `''` are passes. Anything else — a number, an
+object — is recorded as a failure naming the contract, because a check that
+cannot fail is not a check. (It used to read only `false` and a throw, so every
+assert in the shape above passed by not being `false`.)
+
 Run it with `bunx tsx verify.ts` (or inside a vitest test). Physics enables
 automatically from the scene's `dimension`. `result.snapshots` holds periodic
 captures; `result.logs` holds everything behaviors logged via `this.log`.
@@ -222,6 +257,84 @@ into the process-global registries (hot-replacing same names). In a test
 suite, isolate with `clearRegistry()`/`clearBehaviors()` between files if
 you register conflicting classes.
 
+### Clicking, for a game the mouse plays
+
+`press`/`release`/`vector`/`key` are all ACTIONS, and `Clickable` reads the mouse
+BUTTON — so a match-3, a tower defense, a card game, a point-and-click, an RTS or
+a flip puzzle needs one more verb:
+
+```ts
+steps: [
+  { atMs: 100, click: 'Board/Tile3' },   // by node path — the usual way
+  { atMs: 400, click: [300, 100] },      // or a raw point, in the scene's units
+]
+```
+
+A click is a press and a release on two DIFFERENT frames — `clicked` fires on
+release over the node the press started on — and that is handled for you. So is
+the picker: headless there is no renderer and therefore no raycast, so a
+**geometric** one is installed for the run, answering from the same world boxes
+`framing()` measures. A game that installs a picker of its own keeps it — its
+answer always wins.
+
+2D coordinates are world pixels (the space every 2D `position` in the file is
+already written in); 3D casts a ray from the scene's current camera. A `click`
+naming a path that resolves to nothing is a FAILURE, not a click into space.
+
+`geometricPicker(scene)` from `incanto/test` is the same thing on its own, for a
+harness that wants to ask "what is under this point" directly.
+
+**A `click` naming a HUD widget PRESSES it** — `click: 'Hud/Shop/Buy'` is the
+whole verb for a menu, a shop, a settings screen, an idle game or a card game.
+There is no cursor involved: a widget lives in the DOM overlay, not the world,
+so the click goes to what a MOUSE does to that widget — a button presses, a
+toggle flips, a select advances, and a `UiDialogue` ADVANCES THE LINE without
+answering a waiting choice, exactly as clicking the box does in a browser
+(`advance()` refuses to skip choices). To answer one, do what a player does and
+press the choice, or call `talk.choose(i)` from a `do:` step. Enter and the
+pad's A are a different verb and DO answer.
+A widget that is hidden — or that sits under a hidden `UiPanel` or a hidden
+`HudLayer` — is a FAILURE naming it, because a player could not have pressed it
+either.
+
+**A drag needs the two edges apart**, and `click` puts them at one point:
+
+```ts
+steps: [
+  { atMs: 100, at: [400, 300], mouse: 'down' },   // press, here
+  { atMs: 200, at: [300, 380] },                  // and move while held
+  { atMs: 300, mouse: 'up' },                     // let go, there
+]
+```
+
+`at` on its own is a HOVER — the state a game shows for a cursor that has not
+clicked yet. `button` picks a different one (0 left · 1 middle · 2 right) for
+`mouse` and for `click` alike. Written with `click`, a drag-and-launch game
+launches with a vector of `from - to` where both are the same point: **it fires
+every shot and every shot goes nowhere**, and the run reports fine.
+
+The aiming side is on the engine, not the renderer: a behaviour reads
+`this.engine.pointerWorld()` (and `toWorld`/`toScreen`), and a `click` or `at`
+step installs a geometric one for the run alongside the picker.
+
+### Asking the game a question
+
+An assert needs to READ something, and the readable thing is often neither a
+prop nor a method. Every node type's **`Reads:`** line in
+`incanto-node-reference.md` lists its read-only accessors — the ones that exist
+for exactly this:
+
+```ts
+(ctx.getNode('Hud/Banner') as never as { showing: string }).showing   // '' when idle
+(ctx.getNode('Talk') as never as { active: boolean }).active          // mid-dialogue?
+(ctx.getNode('Gun').behavior as never as { liveCount: number }).liveCount
+(ctx.getNode('Player').behavior as never as { isDead: boolean }).isDead
+```
+
+`banner.text` does not exist and reads as `undefined`, which an assert will
+happily compare against and pass. Look the accessor up rather than guessing a
+prop name.
+
 ## 4. Read the scene like a screenshot
 
 ```ts
@@ -290,19 +403,27 @@ from geometry alone — no renderer, no canvas, no browser:
 
 ```
 > framing
-camera /World/Player/Cam at [0, 2, 8] looking [0, -0.2, -0.97] fov 60
+camera /World/Player/Cam at [0, 2, 8] looking [0, -0.2, -0.97] up [0, 1, 0] fov 60
 lit by: /World/Sun (DirectionalLight3D), environment.sky
-3 on screen, 1 off screen, 2 behind the camera
+3 on screen, 1 off screen, 2 behind the camera, 1 hidden (visible: false)
   onScreen  /World/Island (MeshInstance3D) [0, 0, 0] screen [0.02, -0.11] 8.2m
   behind    /World/Chest (ModelInstance3D) [0, 0, 40] 32m
   offscreen /World/Gem (MeshInstance3D) [80, 0, 0] screen [4.4, 0] 80.1m
+  hidden    /World/Boss (ModelInstance3D) [0, 0, -12] 20.1m
   overlap   /World/Platform ∩ /World/Gem
 ```
 
-Read it for the three visual failures that look identical from a node list:
+Read it for the five visual failures that look identical from a node list:
 
 - **`behind`** — the thing is fine, the camera has its back to it. Indistinguishable
   from "my model did not load" until you can see this line.
+- **`hidden`** — `visible: false` on the node or on any ancestor. The renderer skips
+  the whole subtree, so it is NOT in view; a screen drawing nothing used to report
+  every one of them as in view. `NOTHING IS DRAWN` when that is all of them.
+- **`up`** — which way is up on screen. Roll changes NOTHING else, so a camera rolled
+  180° prints the same `at` and the same `looking` as an upright one; the report
+  says `is UPSIDE DOWN` when `up.y` goes negative (a top-down camera measures
+  `up.y = 0` and is left alone).
 - **`lit by: NOTHING`** — the scene renders black. No error, no log, nothing wrong
   with any node.
 - **`overlap`** — two declared colliders intersect: the gem is inside the platform.
@@ -312,6 +433,13 @@ Also `incanto-play`'s `framing` command, and `describeFraming(scene)` /
 as on screen when its `size` box (or collider) is, not only its origin — so a
 200 m island whose origin sits off to the left is correctly `onScreen`.
 
+**HUD widgets are counted separately** (`report.widgets`), because asking
+whether the camera can see one is a category error — and because leaving them
+out meant a shop screen made entirely of widgets and an empty scene file both
+read `0/0 on screen`. A scene with no drawable node AND no widget now says
+`nothing on screen`, and the gate treats it as broken: a scene that draws
+nothing looks exactly like one that failed to load.
+
 **A 2D scene gets a 2D report**, in pixels: the `viewport.design` window centred
 on the current `Camera2D` and CLAMPED by its `limits`, which is the view the
 renderer actually draws. Nothing is ever `behind` a 2D camera and nothing is
@@ -324,7 +452,7 @@ the instant a frame composites, so `canvas.toDataURL()` and every screenshot
 built on it come back BLANK without it:
 
 ```ts
-createGame3D({ ..., preserveDrawingBuffer: true });
+createGame3D({ ..., preserveDrawingBuffer: true });   // createGame2D too
 // or in the scene: "environment": { "rendering": { "preserveDrawingBuffer": true } }
 ```
 
@@ -510,6 +638,44 @@ The same words `incanto-play` takes — `press`/`release ACTION`, `vector ACTION
 newlines. `--do-file` reads a longer plan from a file. One vocabulary for the
 headless gamepad and the live one.
 
+**Pointing at things**, for the games that are played that way:
+
+```
+$ bunx incanto-frame --do "at %Mole; click; step 300" --out whacked.png
+```
+
+`at X Y` puts the cursor on a canvas pixel and `at <node path>` puts it wherever
+that node is ON SCREEN — the page knows, and you cannot compute it from out
+here. **A `click` before anything has aimed is refused**, because it would land
+wherever the cursor was left, and a plan whose `at` failed would otherwise
+report the aim false and the click true. Headless, `click` also answers with
+what it HIT (`"hit": "/Game/Field/Hole11/Mole"`, or `null`) — the reason to aim
+is to hit something, and from outside the process there is no way to ask. **`incanto-play` takes the same two words**, headless, installing a
+geometric picker for them (there is no renderer to raycast with):
+
+```
+$ printf 'step 700\nat Field/Hole12/Mole\nclick\ndescribe\nquit\n' \
+    | bunx incanto-play src/game.scene.json --behaviors src/behaviors.ts
+{"ok":true,"cmd":"at","at":[560,291]}
+{"ok":true,"cmd":"click","t":733}
+… /Game/Hud/Score UiText text="Moles 1 / 12"
+``` `click` (optionally `left`/`middle`/`right`) presses and releases where the
+cursor is, with a frame in between so the game gets to show that it is being
+pressed.
+
+**A drag is `mouse` — press, move, let go**, because `click` is both edges at
+one point and a slingshot, a selection box, a swipe and an item carried between
+inventory slots are all "press here, move there, let go":
+
+```
+$ bunx incanto-frame --do "at 400 300; mouse left down; at 300 380; mouse left up; step 400"
+```
+
+`mouse` takes the same three words `click` does, and the same `0|1|2` the
+`incanto-play` REPL takes. The language used to have only `pointer DX DY`, which is a delta —
+the mouse-LOOK question — so an agent driving its own match-3, tower defense,
+card game or point-and-click could reach no state at all.
+
 `step` waits on the REAL clock: this is the running game, with its own loop, its
 own physics and its own animation, and stepping it by hand would fight all three.
 
@@ -637,8 +803,9 @@ the path, then **▶ play ▸ ⤢ run as the game** and the page is the game aga
 running your edit. `game.openEditor()` is the same switch from code.
 
 It follows `debug` (so a build with the overlay has it) and loads lazily, so a
-game that never opens it never downloads it. `editor: false` opts out;
-`editor: { save }` adds the editor's save button, wired to your own writer:
+game that never opens it never downloads it. `editor: false` opts out at
+RUNTIME — the button is absent — and `editor: { save }` adds the editor's save
+button, wired to your own writer:
 
 ```ts
 createGame3D({
@@ -660,6 +827,89 @@ overlay is a lazily-imported chunk — it stays out of the main bundle (no size
 cost), but it still ships in the build, so that runtime `debug` flag is the only
 thing gating it: keep it `false` (or dev-gated) in anything you publish.
 
+## 9. Verify the thing you SHIP, not just the thing you run
+
+Everything above measures a dev server. The artifact a player gets is
+`bun run build` — a bundled, minified `dist/` with different asset paths and a
+different module graph — and the boot path is the only code a BUILD adds over a
+SCENE. Two of the nastiest defects this engine has had lived exactly there: a
+`main.ts` whose scene swap left the game with no physics, and a boot that threw
+behind a loading overlay that never came down.
+
+`incanto-frame` and `incanto-logs` ask a dev server, and the dev server asks the
+page over vite's HMR channel. A build has no HMR, so they used to answer:
+
+```
+? draws — no incanto dev server found.
+? says  — no incanto dev server found.
+```
+
+**`incanto-serve` closes that.** It serves your build as plain static files —
+no bundler, no transform, byte-for-byte what you deploy — and adds only the
+`/__incanto/*` endpoints the CLIs already speak, plus one inline script injected
+into `index.html` at serve time. Nothing is written to disk, so what you measure
+is what you ship.
+
+```bash
+bun run build                 # the artifact
+bunx incanto-serve            # ./dist on :4180 (or: incanto-serve build --port 5050)
+# open http://127.0.0.1:4180/ , then:
+bunx incanto-verify           # draws and says now measure the BUILT game
+bunx incanto-logs             # what the built page is complaining about
+bunx incanto-frame --out shipped.png
+```
+
+**Ship-check list**, in the order things actually break:
+
+1. **`bun run build` at all.** Dev-only code (`import.meta.env.DEV`, a plugin
+   that is `apply: 'serve'`) can compile and then do nothing.
+2. **Open the built page.** A blank screen with a console error is the common
+   failure; `incanto-logs` reads it without you opening devtools.
+3. **`incanto-verify` against `incanto-serve`.** `draws` catches an asset base
+   path that survived dev and broke under a subdirectory deploy; `says` catches
+   the 404s.
+4. **A phone-sized window.** See `incanto-web-integration.md` — a HUD that is
+   legible at 1280×800 can be 6 px tall at 390×844.
+5. **A second load.** Saves, settings and unlocks come back; a private window
+   answers `slots.persistent === false` (see `incanto-save-slots.md`).
+
+The one thing `incanto-serve` is not is a production server: it is a local tool
+for looking at a build, on `127.0.0.1` by default.
+
+### The editor is in your build, even in a 2D game
+
+`editor: false` is a runtime option and **cannot remove bytes from a bundle**.
+The editor chunk is lazy — a game that never opens it never downloads it — but
+it is in `dist/`, and it imports `incanto/3d`, which imports rapier3d. Measured
+on a pristine `platformer-2d` scaffold:
+
+```
+2236503  assets/rapier-*.js    rapier3d      ← a 2D game can never execute this
+1692278  assets/rapier-*.js    rapier2d      ← the one it uses
+ 471186  assets/3d-*.js        the 3D adapter
+─────────
+5979588  total
+```
+
+A build-time decision needs a build-time lever:
+
+```ts
+import { incantoScenes, incantoTrim } from 'incanto/vite';
+export default defineConfig({
+  plugins: [incantoScenes(), incantoTrim({ editor: false })],
+});
+```
+
+```
+5979588  →  2769972 bytes     53.7% smaller, same game
+```
+
+Build only: the dev server keeps the editor, so `☰ debug ▸ ✎ edit this scene`
+works the whole time you are making the game and is simply absent from what you
+ship. Opening it in a trimmed build says so in one sentence rather than failing
+obscurely. Reach for this when deploy size matters — a CDN, a jam upload, an
+agent8 zip — and leave it off otherwise.
+
 ## 8. Debugging signals
 
 - `this.log.info(...)` in behaviors — shows up in `runScript().logs` (and the
@@ -685,6 +935,32 @@ rows until the orange box lands on the thing you're hunting.
 inside a `static` subtree, HUD widgets outside a HudLayer. Programmatic:
 `auditScene(json)` from `incanto` or `incanto/test` returns the warnings.
 
+**Including a HUD line that names the wrong key.** `tps-3d`'s pause menu read
+`Esc to resume · R to restart` for exactly three hours after `restart` was moved
+off `KeyR` — the binding moved and the sentence about it did not, which is the
+whole failure mode of any fact written down twice. The check is narrow on
+purpose: it fires only when a line names both a key it recognises AND a word
+that is a DECLARED ACTION in the same scene, so "Esc to resume" says nothing
+(there is no `resume` action) and prose is left alone.
+
+**Including one key bound to two actions.** `tps-3d` shipped `reload` and
+`restart` both on `KeyR`: pressing R reloaded, and `restart` — which nothing
+read — looked broken. Two actions on one key are legal, sometimes deliberate,
+so this warns rather than refuses; the sibling question ("does anything read
+this action at all?") is `input.unreadActions()`, in `incanto-playtesting.md`.
+
+**Including a `Clickable` nobody listens to.** It produces `clicked`, `hovered`
+and `unhovered` and nothing else, so attaching it and wiring none of them costs
+a pick every frame and can never do anything — the likeliest mistake a mouse
+game makes, and one with no error anywhere. A board of sixteen unwired tiles
+used to print `1/1 scene(s) valid`.
+
+```
+warn: Game/A: Clickable produces nothing but 'clicked'/'hovered'/'unhovered',
+      and no connection listens to any of them — so it can never do anything.
+      Wire one, or listen in code with `node.on('clicked', …)`.
+```
+
 **Including a node path that points at nothing.** `Chase.target`,
 `Camera2D.follow`, `Spawner.prefab`, `Joint3D.target`, `skinPath`, `terrain` —
 these hold a path to another node, and a wrong one is SILENT: a connection that
@@ -699,8 +975,12 @@ warn: World/Cam: follow — '/Level/Player' starts at 'Level', but the scene
 ```
 
 An empty value is never reported — `""` is the default of most of these and
-means "not set". A behavior of YOUR OWN is not reported either: the checker
-never loads your TypeScript, so it cannot know which of its props are paths.
+means "not set" (and `getNodeOrNull("")` returns null, so the guard you would
+write for it is unnecessary). A behavior of YOUR OWN is reported too, once you
+hand the checker the file that registers it: `incanto-check src --behaviors
+src/behaviors.ts`. Without the flag it has no schema for your behaviours and
+cannot know which of their props are paths — so pass it, the way every
+scaffolded project's `check` script does.
 
 ## Deterministic replay (record once, regression-test forever)
 
@@ -717,7 +997,7 @@ save.set('replays/level1', rec.stop());
 
 // in a headless test:
 const engine = new Engine({ seed: SAME_SEED });
-engine.setScene(loadScene(sceneJson));
+engine.setScene(loadScene(sceneJson, { engine }));
 replay(engine, recording, { onTick(i) { /* mid-run asserts */ } });
 expect(player.position).toEqual(expected); // exact, not approximate
 ```

package/skills/incanto-web-integration.md

@@ -83,6 +83,34 @@ null when the ray misses (looking at the sky). `pick(sx, sy)` gives you the NODE
 under a pixel — a different question, and the only one 3D could answer before
 0.66.
 
+**Inside a Behavior there is no renderer**, so the same four questions are on
+the engine, installed by whichever renderer is running and cleared when it is
+disposed:
+
+```ts
+this.engine.pointerWorld()                 // where the cursor is → number[] | null
+this.engine.toWorld(sx, sy)                // any screen point → [x, y] | [x, y, z]
+this.engine.toScreen(node.position)        // → { x, y, behind } | null
+this.engine.screenRay(sx, sy)              // 3D only → { origin, dir } for castRay
+this.engine.pickAt(sx, sy)                 // which node (cached per frame)
+```
+
+The answer is the scene's own shape — `[x, y]` in 2D, `[x, y, z]` on the ground
+in 3D — so it goes straight back into a `position`. All are null with no
+renderer; a `runScript` `click` step (and `incanto-play`'s `at`) installs
+geometric `toWorld`/`toScreen`/`screenRay` for the run, so a game that AIMS is
+testable headless and not only one that clicks.
+
+**On uneven ground, cast the ray** — `toWorld` lands on a plane, which is the
+wrong answer under a hill or a crate:
+
+```ts
+const at = this.engine.input.pointerPosition();
+const ray = at && this.engine.screenRay?.(at.x, at.y);
+const hit = ray && this.engine.physics?.castRay(ray.origin, ray.dir, 100);
+if (hit) place(hit.point);          // WHERE it landed, not how far
+```
+
 Perf note: `useNodeProp` deep-compares per frame — subscribe to LEAF values
 (`'UI/Score', 'text'`), not big objects like a whole `animations` map.
 

package/skills/incanto-your-first-game.md

@@ -40,7 +40,9 @@ the vite config and the verify harness.
 
 Pick by shape, not by subject: `tps-3d` (third-person combat), `platformer-2d`,
 `star-survivor` (top-down survivor), `village-quest-3d` (quest/NPC),
-`beacon-isle-3d` (open world).
+`beacon-isle-3d` (open world), `molehill-2d` (**played with the MOUSE** — no
+character, no keyboard: the shape a match-3, a tower defense, a card game, a
+point-and-click or an RTS starts from).
 
 ---
 
@@ -242,7 +244,8 @@ Things that cost real time, in the order you will meet them.
 | a 3D character that feels right | `incanto-3d-character.md` |
 | terrain, water, trees, sky | `incanto-environment.md` |
 | sound | `incanto-audio.md` |
-| shake, flash, hit-stop, particles | `incanto-game-feel.md` |
+| shake, flash, hit-stop, particles | `incanto-gameplay-behaviors.md` (`CameraShake`, `screenFlash`, `hitStop`, `Particles2D/3D`) |
+| is the feel RIGHT? measure it | `incanto-game-feel.md` |
 | HUD, menus, inventory | `incanto-hud.md` |
 | proving it works | `incanto-verifying-your-game.md` |