incanto 0.28.0 → 0.29.0

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

@@ -168,12 +168,61 @@ VITE_INCANTO_DEBUG=1 bun run dev   # overlay on; plain `bun run dev` / prod buil
 A ☰ debug menu (top-left) toggles three draggable/resizable panels over the
 live game: **Explorer** (the scene tree — click any node), **Inspector** (the
 selected node's current state; numbers/strings/booleans/vectors editable
-in-place), **Logs** (an `engine.log` tail with level filters and an optional
+in-place, and an OBJECT prop like `collider` opens into a row per key with the
+`shape` as a dropdown — picking a shape writes a complete valid collider, never
+a box's `size` under a sphere's tag; bulky values like a 54-row `transforms`
+fold behind `▸ Array(54)` and expand on click, one row per element), **Logs** (an `engine.log` tail with level filters and an optional
 browser-console capture toggle) — plus **Stats**, an always-on-top chip pinned
 top-right (`60 fps · 12.1 ms` / `nodes 34 · tris 18.2k · calls 21`, refreshed
-~2×/s; the same numbers any code can read via `game.stats()`). Manual boots:
+~2×/s; the same numbers any code can read via `game.stats()`) — and
+**Colliders**, a switch that draws every physics shape as light-green wireframe
+in the game view. Manual boots:
 `(await import('incanto/debug')).attachDebugOverlay(engine)`.
 
+The Inspector HOLDS STILL while you use it: it stops refreshing whenever an
+input has focus or the pointer is inside the panel, and it keeps your scroll
+position across refreshes. Live values resume the moment you move away.
+
+**Colliders is the answer to "why did I stop in mid-air / fall through the
+floor".** What you see is the shape data the solver holds — put it next to the
+art and a collider that disagrees with its mesh is obvious in one glance.
+
+One click cycles **off → all → selected** (the menu stays open while you cycle —
+the item's label shows the state you landed on):
+
+- `all` is every collider in the world. On a real map that means a terrain
+  heightfield's grid over everything, which is why the third state exists.
+- `selected` draws only what the Explorer has picked: that node's colliders, its
+  descendants', or — if it owns none — the nearest BODY above it, so clicking a
+  visual `MeshInstance3D` shows the collider it hangs under rather than nothing.
+  A scatter field gives you all of its rows.
+
+From code: `physics.debugDraw = true` and `physics.debugScope = node` (null for
+everything).
+
+**✎ edit this scene** is the last item in that menu, and it is the fastest loop
+in the engine: the page you are playing in BECOMES the scene editor, from the
+camera you were standing at — no reload, no second tab. Drag a boulder out of
+the path, then **▶ play ▸ ⤢ run as the game** and the page is the game again,
+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:
+
+```ts
+createGame3D({
+  ...,
+  debug: import.meta.env.VITE_INCANTO_DEBUG === '1',
+  editor: { save: (json) => fetch('/api/scene', { method: 'PUT', body: JSON.stringify(json) }) },
+});
+```
+
+What crosses the switch is the AUTHORED scene JSON, not the live tree — physics
+has moved the live one, and "edit this scene" must not mean "edit wherever the
+simulation happened to be". Unsaved edits survive the round trip both ways; a
+page reload is what drops them.
+
 **Security — `debug` defaults to `false` and there is NO URL/query toggle**, so
 a DEPLOYED build can never be switched on by an end user (no more `?incanto_debug=1`).
 Enable it only from your own dev environment via the env-var gate above. The

package/templates-app/beacon-isle-3d/docs/project-3d-rules.md

@@ -35,4 +35,9 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template:
 11. ✅ VERIFY LIKE A USER: `bun run check` validates the scene, `bun run verify`
     proves the loop headlessly, then `bun run dev` and actually PLAY what you
     changed (move, shoot, clear a wave) before declaring it done.
+12. 🔍 X-RAY WHEN IT LOOKS WRONG: `VITE_INCANTO_DEBUG=1 bun run dev` adds a ☰
+    debug menu — Explorer/Inspector (click a node, see and edit its live props),
+    Logs, Stats (fps · tris · draw calls) and Colliders (every physics shape as
+    wireframe). Blocked in mid-air or falling through the floor is a Colliders
+    question; a mystery frame-rate is a Stats question. Never ship the flag on.
 </userRequest>

package/templates-app/beacon-isle-3d/package.json

@@ -14,7 +14,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.28.0",
+    "incanto": "^0.29.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/tps-3d/docs/project-3d-rules.md

@@ -35,4 +35,9 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template:
 11. ✅ VERIFY LIKE A USER: `bun run check` validates the scene, `bun run verify`
     proves the loop headlessly, then `bun run dev` and actually PLAY what you
     changed (move, shoot, clear a wave) before declaring it done.
+12. 🔍 X-RAY WHEN IT LOOKS WRONG: `VITE_INCANTO_DEBUG=1 bun run dev` adds a ☰
+    debug menu — Explorer/Inspector (click a node, see and edit its live props),
+    Logs, Stats (fps · tris · draw calls) and Colliders (every physics shape as
+    wireframe). Blocked in mid-air or falling through the floor is a Colliders
+    question; a mystery frame-rate is a Stats question. Never ship the flag on.
 </userRequest>

package/templates-app/tps-3d/package.json

@@ -13,7 +13,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.28.0",
+    "incanto": "^0.29.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/village-quest-3d/docs/project-3d-rules.md

@@ -35,4 +35,9 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template:
 11. ✅ VERIFY LIKE A USER: `bun run check` validates the scene, `bun run verify`
     proves the loop headlessly, then `bun run dev` and actually PLAY what you
     changed (move, shoot, clear a wave) before declaring it done.
+12. 🔍 X-RAY WHEN IT LOOKS WRONG: `VITE_INCANTO_DEBUG=1 bun run dev` adds a ☰
+    debug menu — Explorer/Inspector (click a node, see and edit its live props),
+    Logs, Stats (fps · tris · draw calls) and Colliders (every physics shape as
+    wireframe). Blocked in mid-air or falling through the floor is a Colliders
+    question; a mystery frame-rate is a Stats question. Never ship the flag on.
 </userRequest>

package/templates-app/village-quest-3d/package.json

@@ -13,7 +13,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.28.0",
+    "incanto": "^0.29.0",
     "three": "^0.184.0"
   },
   "devDependencies": {