incanto 0.28.0 → 0.30.0

package/skills/incanto-node-reference.md

@@ -49,6 +49,7 @@ Signals: `animationFinished(name)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `texture` | `""` | string |
 | `size` | `[1,1]` | array |
 | `billboard` | `"y"` | one of: `y` `full` `none` |
@@ -94,6 +95,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `collider` | `{}` | object |
 
 Signals: `triggerEnter(other)` · `triggerExit(other)`
@@ -128,6 +130,7 @@ Signals: `finished`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `mode` | `"screen"` | one of: `screen` `y` `none` |
 
 ## `BoneAttachment3D` — `incanto/3d`
@@ -141,6 +144,7 @@ Signals: `finished`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `target` | `""` | string |
 | `bone` | `""` | string |
 
@@ -155,6 +159,7 @@ Signals: `finished`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `target` | `""` | string |
 | `bone` | `"Head"` | string |
 | `lookAt` | `""` | string |
@@ -190,6 +195,7 @@ Signals: `finished`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `fov` | `60` | number |
 | `near` | `0.1` | number |
 | `far` | `1000` | number |
@@ -224,9 +230,9 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `true` | boolean |
 | `collider` | `{}` | object |
 | `velocity` | `[0,0,0]` | array |
-| `snapToGround` | `true` | boolean |
 | `slopeLimitDeg` | `45` | number |
 
 Signals: `triggerEnter(other)` · `triggerExit(other)`
@@ -252,6 +258,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `view` | `"free"` | one of: `free` `firstPerson` `quarter` `side` |
 | `camDistance` | `4` | number |
 | `eyeHeight` | `0.64` | number |
@@ -304,6 +311,7 @@ Signals: `movementStateChanged(state)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `color` | `"#ffffff"` | string |
 | `intensity` | `1` | number |
 | `castShadow` | `false` | boolean |
@@ -322,6 +330,7 @@ Signals: `movementStateChanged(state)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `density` | `"sparse"` | one of: `lush` `sparse` `none` |
 | `area` | `[20,20]` | array |
 | `seed` | `1` | number |
@@ -345,6 +354,7 @@ Signals: `movementStateChanged(state)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `2` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `kind` | `"grass"` | one of: `grass` `flowers` `reeds` |
 | `style` | `"mesh"` | one of: `blades` `simple` `mesh` `tufts` |
 | `tuftStyle` | `"grass"` | one of: `grass` `fern` |
@@ -385,12 +395,14 @@ Signals: `movementStateChanged(state)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `mesh` | `"box"` | one of: `box` `sphere` `capsule` `plane` `cylinder` `gem` |
 | `size` | `[1,1,1]` | array |
 | `material` | `{}` | object |
 | `transforms` | `[]` | array |
 | `castShadow` | `false` | boolean |
 | `receiveShadow` | `false` | boolean |
+| `collider` | `null` | null |
 
 ## `Joint2D` — `incanto/2d`
 
@@ -422,6 +434,7 @@ Signals: `movementStateChanged(state)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `type` | `"spherical"` | one of: `fixed` `spherical` `rope` `spring` |
 | `target` | `""` | string |
 | `anchor` | `[0,0,0]` | array |
@@ -458,6 +471,7 @@ Signals: `movementStateChanged(state)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `sections` | `[]` | array |
 | `slices` | `24` | number |
 | `smooth` | `4` | number |
@@ -476,6 +490,7 @@ Signals: `movementStateChanged(state)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `mesh` | `"box"` | one of: `box` `sphere` `capsule` `plane` `cylinder` `gem` |
 | `size` | `[1,1,1]` | array |
 | `material` | `{}` | object |
@@ -493,11 +508,14 @@ Signals: `movementStateChanged(state)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `model` | `""` | string |
 | `animation` | `""` | string |
 | `targetHeight` | `0` | number |
 | `castShadow` | `false` | boolean |
 | `animationLoop` | `true` | boolean |
+| `animationSpeed` | `1` | number |
+| `animationOffset` | `0` | number |
 | `animationUpper` | `""` | string |
 | `animationUpperLoop` | `false` | boolean |
 | `upperBodyRoot` | `"Spine"` | string |
@@ -545,6 +563,7 @@ _No props (structural fields only)._
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 
 ## `OmniLight3D` — `incanto/3d`
 
@@ -557,6 +576,7 @@ _No props (structural fields only)._
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `color` | `"#ffffff"` | string |
 | `intensity` | `1` | number |
 | `range` | `0` | number |
@@ -606,6 +626,7 @@ Signals: `finished`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"effects"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `preset` | `"custom"` | one of: `custom` `fire` `smoke` `sparks` `fireworks` `explosion` `flash` `lightning` `rain` `snow` `magic` |
 | `emitting` | `true` | boolean |
 | `rate` | `40` | number |
@@ -662,6 +683,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `collider` | `{}` | object |
 | `mass` | `1` | number |
 | `gravityScale` | `1` | number |
@@ -683,6 +705,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `path` | `[]` | array |
 | `width` | `6` | number |
 | `widths` | `[]` | array |
@@ -730,6 +753,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `texture` | `""` | string |
 | `size` | `[1,1]` | array |
 | `billboard` | `"y"` | one of: `y` `full` `none` |
@@ -768,6 +792,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `collider` | `{}` | object |
 
 Signals: `triggerEnter(other)` · `triggerExit(other)`
@@ -783,6 +808,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"terrain"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `size` | `[200,200]` | array |
 | `maxHeight` | `28` | number |
 | `seed` | `1` | number |
@@ -838,6 +864,7 @@ Signals: `timeout`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `width` | `0.3` | number |
 | `color` | `"#ffffff"` | string |
 | `opacity` | `0.8` | number |
@@ -857,6 +884,7 @@ Signals: `timeout`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `tier` | `"medium"` | one of: `simple` `medium` `high` |
 | `type` | `"conifer"` | one of: `conifer` `broadleaf` `dead` `bush` |
 | `seed` | `1` | number |
@@ -952,6 +980,7 @@ Signals: `lineShown` · `choiceMade` · `dialogueFinished`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `voxels` | `[]` | array |
 
 Signals: `blocksChanged`
@@ -967,6 +996,7 @@ Signals: `blocksChanged`
 | `visible` | `true` | boolean |
 | `renderOrder` | `1` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `size` | `[40,40]` | array |
 | `color` | `"#2a6fbe"` | string |
 | `opacity` | `0.8` | number |
@@ -980,6 +1010,7 @@ Signals: `blocksChanged`
 | `mirrorInterval` | `33` | number |
 | `swellSteepness` | `0.35` | number |
 | `foam` | `true` | boolean |
+| `reflectivity` | `null` | null |
 | `interaction` | `true` | boolean |
 | `splash` | `true` | boolean |
 | `sunDirection` | `[0.5,0.8,0.3]` | array |
@@ -1010,6 +1041,7 @@ Signals: `entered(body)` · `exited(body)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `size` | `[2,1,1]` | array |
 | `enabled` | `true` | boolean |
 

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

@@ -30,11 +30,43 @@ independent; enable the one matching your scene.
 
 2D collider shapes: `{"shape":"rect","size":[w,h]}` · `{"shape":"circle","radius":r}` ·
 `{"shape":"capsule","radius":r,"height":h}`.
-3D: `{"shape":"box","size":[x,y,z]}` · `{"shape":"sphere","radius":r}` · `{"shape":"capsule",...}` ·
-`{"shape":"trimesh","vertices":[...],"indices":[...]}` · `{"shape":"heightfield"}` (STATIC-only;
-reads the grid from a `Terrain3D` child — see the incanto-environment skill).
+3D: `{"shape":"auto"}` · `{"shape":"box","size":[x,y,z]}` · `{"shape":"sphere","radius":r}` ·
+`{"shape":"capsule",...}` · `{"shape":"trimesh","vertices":[...],"indices":[...]}` ·
+`{"shape":"heightfield"}` (STATIC-only; reads the grid from a `Terrain3D` child — see the
+incanto-environment skill).
 Malformed colliders are hard `BAD_FORMAT` errors at enable time.
 
+**`{"shape":"auto"}` is the one to reach for on props.** It shapes the collider like the
+`MeshInstance3D` the body CARRIES — box→cuboid, sphere→ball, cylinder/capsule→their own
+shapes, `gem`→a convex hull of its real vertices — so a blocker can never disagree with what
+the player sees. Hand-typed extents drift: a box "around" a bridge ends up wider than the
+bridge and you stop in mid-air; a sphere "for" a stone ends up inside it and you clip through
+the corners. Give the body its mesh as a CHILD and let the shape follow:
+
+```json
+{ "name": "DeckBody", "type": "StaticBody3D",
+  "props": { "position": [0, 3.2, -8], "rotation": [0, 34, 0], "collider": { "shape": "auto" } },
+  "children": [ { "name": "Deck", "type": "MeshInstance3D",
+    "props": { "mesh": "box", "size": [14, 0.22, 2.2] } } ] }
+```
+
+Bodies ignore an ANCESTOR's rotation, so a yawed structure puts each body at top level with
+its own `rotation` — the child mesh then turns with it, visual and collider together.
+
+**`auto` works on a `ModelInstance3D` (GLB/glTF/VRM) too** — the shape comes from the model's
+real triangles, baked through their own transforms, so an offset or `targetHeight`-fitted model
+collides where it is DRAWN:
+
+- on a **static** body (`StaticBody3D`, `Area3D`) → a triangle mesh: the model keeps its holes,
+  so you walk THROUGH an archway instead of into it. Level art can be dense; a collider over
+  ~20k triangles logs a note suggesting a low-poly collision model.
+- on a **moving** body (`RigidBody3D`, `CharacterBody3D`) → the convex hull. Rapier's triangle
+  meshes are hollow shells; a dynamic one falls through the world.
+
+The body simply does not exist until the model has downloaded — nothing is invented in the
+meantime — and it appears the step the asset lands. A body is ONE shape, so `auto` fits one
+mesh or one model and warns when the body carries more.
+
 - **`StaticBody2D/3D`** — immovable (ground, walls). Props: `collider`.
 - **`RigidBody2D/3D`** — simulated. Props: `collider`, `mass 1`, `gravityScale 1`,
   `fixedRotation false`, `friction 0.5`, `restitution 0`, `linearVelocity` (write to launch,
@@ -200,9 +232,31 @@ change scan was removed for performance).
 ## Debug drawing
 
 `physics.debugDraw = true` (the instance `enablePhysics2D/3D` returns) renders
-every collider as light-green wireframe lines IN THE GAME VIEW — Rapier's own
-debug geometry, so what you see is exactly what the solver sees. Default OFF;
-toggle it live whenever physics feels wrong.
+every collider as light-green wireframe lines IN THE GAME VIEW — the shape data
+the solver holds, so what you see is what it collides with. Default OFF; toggle
+it live whenever physics feels wrong.
+
+`physics.debugScope = node` narrows those lines to ONE node: its own colliders,
+its descendants', or the nearest body above it when it owns none (so a visual
+mesh child shows the body it belongs to). Null again for the whole world. Without
+it, a map with terrain is a wall of grid lines and the shape you came to check is
+somewhere inside it. The debug overlay's **Colliders** menu item cycles
+off → all → selected over exactly these two fields.
+
+### Colliders without a simulation
+
+`enablePhysics3D(engine, { simulate: false })` (and the 2D twin) builds the world
+and never advances it: the body set is kept in step with the tree, every body is
+posed FROM the tree each tick and propagated to its colliders, and then it stops
+— no solver, no collision events, no write-back into node props. `debugDraw`
+works exactly as above.
+
+This is how the scene editor shows colliders while you edit: the real shapes,
+including the ones that are not in the scene JSON at all (a mesh-fitted body, an
+InstancedMesh3D scatter's hulls, a terrain, a character capsule), sitting where
+the tree says, without your scene falling over while you look at it. Use it for
+any "show me the collision geometry" tool. Do NOT use it to freeze a running
+game — that is `engine.timeScale = 0`, which keeps the world coherent.
 
 ## Placement rules
 

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

@@ -155,6 +155,12 @@ export default { plugins: [incantoScenes()] };
 Invalid `*.scene.json` saves keep the last good scene running and surface the
 IncantoError in the terminal AND as a browser overlay.
 
+The same plugin serves this project's scenes to the editor, so the one you switch
+into from the running game (`☰ debug ▸ ✎ edit this scene`) can open, create and save
+ANY scene in the project — not just the one the game booted with. `incantoScenes({
+root })` bounds that to a directory other than vite's; nothing outside it is readable
+or writable, and none of it exists in a build (`configureServer`).
+
 ## 7. See inside the RUNNING game (debug overlay)
 
 ```ts
@@ -168,12 +174,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.30.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/beacon-isle-3d/vite.config.ts

@@ -1,5 +1,12 @@
+import { incantoLibrary, incantoScenes } from 'incanto/vite';
 import { defineConfig } from 'vite';
 
 export default defineConfig({
   base: './',
+  // Dev-server only, and both are why the editor is useful here:
+  // - incantoScenes(): validates every *.scene.json the moment you save it,
+  //   AND serves this project's scenes, so the editor (☰ debug ▸ edit this
+  //   scene ▸ scenes) can open, create and save any scene in the project.
+  // - incantoLibrary(): the agent8 asset catalog behind the 📚 buttons.
+  plugins: [incantoScenes(), incantoLibrary()],
 });

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.30.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/tps-3d/vite.config.ts

@@ -1,5 +1,12 @@
+import { incantoLibrary, incantoScenes } from 'incanto/vite';
 import { defineConfig } from 'vite';
 
 export default defineConfig({
   base: './',
+  // Dev-server only, and both are why the editor is useful here:
+  // - incantoScenes(): validates every *.scene.json the moment you save it,
+  //   AND serves this project's scenes, so the editor (☰ debug ▸ edit this
+  //   scene ▸ scenes) can open, create and save any scene in the project.
+  // - incantoLibrary(): the agent8 asset catalog behind the 📚 buttons.
+  plugins: [incantoScenes(), incantoLibrary()],
 });

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.30.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/village-quest-3d/vite.config.ts

@@ -1,5 +1,12 @@
+import { incantoLibrary, incantoScenes } from 'incanto/vite';
 import { defineConfig } from 'vite';
 
 export default defineConfig({
   base: './',
+  // Dev-server only, and both are why the editor is useful here:
+  // - incantoScenes(): validates every *.scene.json the moment you save it,
+  //   AND serves this project's scenes, so the editor (☰ debug ▸ edit this
+  //   scene ▸ scenes) can open, create and save any scene in the project.
+  // - incantoLibrary(): the agent8 asset catalog behind the 📚 buttons.
+  plugins: [incantoScenes(), incantoLibrary()],
 });

package/dist/debug-draw-CZmOYjL2.js

@@ -1,13 +0,0 @@
-//#region src/core/debug-draw.ts
-const sources = /* @__PURE__ */ new Set();
-/** @internal physics runtimes self-register on enable. */
-function registerDebugSource(source) {
-	sources.add(source);
-	return () => sources.delete(source);
-}
-/** @internal renderers pull their dimension's sources. */
-function debugSources(dimension) {
-	return [...sources].filter((s) => s.dimension === dimension);
-}
-//#endregion
-export { registerDebugSource as n, debugSources as t };