incanto 0.77.0 → 0.78.1

package/README.md

@@ -21,9 +21,14 @@ rest declared in JSON. `bun run verify` plays the entire quest **headlessly**
 and replays recorded input bit-identically: the agent loop is author → verify →
 fix, no browser needed.
 
-`bunx incanto new --list` shows all five starters, grouped by dimension: three
-3D (island adventure, third-person shooter, quest vignette) and two 2D
-(platformer, survivors-like).
+`bunx incanto new --list` shows all six starters, grouped by dimension: three
+3D (island adventure, third-person shooter, quest vignette) and three 2D
+(platformer, survivors-like, and a whack-a-mole played with the mouse alone).
+
+Every starter is **TypeScript + Vite + React**: `src/main.tsx` mounts `<App />`
+and `src/App.tsx` owns the canvas the engine draws into. React is the shell, not
+the game — `incanto/react`'s `<IncantoCanvas>` is the other shape, for putting a
+game inside an app you already have.
 
 ## Or wire the engine yourself
 
@@ -53,7 +58,7 @@ engine.start();
 | `incanto/net` | multiplayer over a pluggable `NetworkTransport` — built-in offline Loopback + [@agent8/gameserver](https://www.npmjs.com/package/@agent8/gameserver) adapter (optional peer); custom backends implement one interface |
 
 - `schemas/scene.schema.json` — generated JSON Schema for scene files (the agent contract)
-- `templates/agent8-server.js` — the multiplayer server kernel for the agent8 platform
+- `templates/agent8-server.ts` — the multiplayer server kernel for the agent8 platform (`.js` beside it for the legacy single-file server)
 
 ## Debug mode
 

package/dist/index.js

@@ -9,5 +9,5 @@ import { t as showBootFailure } from "./boot-failure-CKYrEcGF.js";
 import { a as logText, i as logReport, o as parseDrive, r as resolveRendering, t as isWebGLAvailable } from "./webgl-unavailable-C8aDbGmR.js";
 import { t as createNoise2D } from "./noise-D3nPpmFg.js";
 import { a as PARTICLE_PRESETS, i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-SQa5gIu2.js";
-import { a as findPath, i as preloadUrls, n as assetUrls, o as gridFromRows, r as preloadSceneAssets, t as VERSION } from "./src-DygJfhOb.js";
+import { a as findPath, i as preloadUrls, n as assetUrls, o as gridFromRows, r as preloadSceneAssets, t as VERSION } from "./src-SWXe-bub.js";
 export { AudioBuses, AudioPlayer, BASE_LOCALE, Behavior, CONST_REF_KEY, EffectLog, Engine, HudLayer, IncantoError, InputMap, Localization, LogManager, MusicManager, Node, ORDER_GROUP_BASE, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, ParticleSim, ROLLOFF_MODELS, Respawn, Rng, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, SaveSlots, Scene, SceneTree, Settings, SfxEngine, Signal, T_PREFIX, Timer, TouchControls, UiBanner, UiBar, UiButton, UiDialogue, UiFrameCapSelect, UiImage, UiLanguageSelect, UiMinimap, UiMuteToggle, UiPanel, UiQualitySelect, UiRenderScaleSelect, UiSelect, UiSlider, UiText, UiToggle, UiVolumeSlider, UiWaypoint, VERSION, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, auditScene, behaviorSchema, behaviorSignals, behaviorsWithoutSave, captureBehaviors, clearBehaviors, clearRegistry, computeViewport, createNode, createNoise2D, createSaveStore, crossfadeGains, describeRefProblem, duplicateNode, effectiveOrder, fadeGain, findPath, getBehavior, getNodeSchema, getNodeSignals, getNodeType, gridFromRows, isAudioContextAvailable, isConstRef, isWebGLAvailable, joystickVector, jsonClone, jsonEquals, jsonKind, loadScene, logReport, logText, mergeStaticSignals, newUid, nodeRefWarnings, parseDrive, parseNodePath, preloadSceneAssets, preloadUrls, qualityEnvironment, readDeviceHints, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, replay, resolveAnimation, resolveConstants, resolveFrames, resolveOrderGroups, resolveRefInJson, resolveRendering, resolveViewport, restoreBehaviors, savesWithoutUid, serializeNode, sfxDuration, showBootFailure, spatialGain, spatialPan, startRecording, suggestLocale, suggestQuality, synthSfx, translationKey };

package/dist/{src-DygJfhOb.js → src-SWXe-bub.js}

@@ -199,6 +199,6 @@ async function preloadSceneAssets(assets, title) {
 //#endregion
 //#region src/index.ts
 /** Engine version. Kept in sync with package.json by the release pipeline. */
-const VERSION = "0.77.0";
+const VERSION = "0.78.1";
 //#endregion
 export { findPath as a, preloadUrls as i, assetUrls as n, gridFromRows as o, preloadSceneAssets as r, VERSION as t };

package/dist/vite.js

@@ -1,7 +1,7 @@
 import { a as parseJsonText } from "./json-CfTjpvW8.js";
 import { P as newUid } from "./pose-ByFB_J3O.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { t as VERSION } from "./src-DygJfhOb.js";
+import { t as VERSION } from "./src-SWXe-bub.js";
 import { n as diffSignatures } from "./frame-report-D-_7YF2G.js";
 import { s as validateScene } from "./test-CVbxnXlv.js";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "incanto",
-  "version": "0.77.0",
+  "version": "0.78.1",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",

package/skills/incanto-building-2d-games.md

@@ -44,6 +44,12 @@ const game = await createGame2D({
 // game.dispose() — ONE call tears everything down (SPA unmount)
 ```
 
+A scaffolded project calls this from `src/App.tsx` — React owns the page, the
+component owns the canvas, and the boot runs in an effect. `canvas` comes from a
+ref there rather than a `querySelector`. See `incanto-web-integration.md` for
+that shell and for the `<IncantoCanvas>` component you use instead when the game
+is one part of a larger site.
+
 One call does register → load → physics → input → renderer → start. Physics is
 `'auto'`: Rapier is enabled iff the tree has physics bodies (force with
 `physics: true|false`). Keyboard attaches to `window` (`keyboard: false`

package/skills/incanto-building-3d-games.md

@@ -52,6 +52,12 @@ const game = await createGame3D({
 // game.dispose() — ONE call tears everything down (SPA unmount)
 ```
 
+A scaffolded project calls this from `src/App.tsx` — React owns the page, the
+component owns the canvas, and the boot runs in an effect. `canvas` comes from a
+ref there rather than a `querySelector`. See `incanto-web-integration.md` for
+that shell and for the `<IncantoCanvas>` component you use instead when the game
+is one part of a larger site.
+
 One call does register → load → physics → input → renderer → start. Physics is
 `'auto'`: Rapier is enabled iff the tree has physics bodies (force with
 `physics: true|false`). Keyboard attaches to `window` (`keyboard: false`

package/skills/incanto-editor.md

@@ -363,7 +363,7 @@ import { incantoLibrary, incantoScenes } from 'incanto/vite';
 export default defineConfig({ plugins: [incantoScenes(), incantoLibrary()] });
 ```
 ```ts
-// main.ts
+// App.tsx
 createGame3D({
   ...,
   debug: import.meta.env.VITE_INCANTO_DEBUG === '1',
@@ -407,7 +407,7 @@ pass `editor.save` — otherwise edits live as long as the session does.
 
 **Saving keeps you in the editor.** It used to throw you out of it: the save
 writes the scene through `incantoScenes()`'s `PUT /api/scene`, vite saw its own
-watched file change, and a JSON module imported by `main.ts` cannot be
+watched file change, and a JSON module imported by `App.tsx` cannot be
 hot-swapped — so vite full-page-RELOADED, the page came back as the game, and
 the selection, the camera and the panel you were working in were gone. The
 plugin now recognises a write it just made and lets the page be. A hand edit in

package/skills/incanto-multiplayer.md

@@ -447,7 +447,7 @@ the composition:
   in the browser that offline pose went out as the client's FIRST replicated
   state, on top of the other player's car, which the kinematic copy then lifted
   off the ground. Boot with `autoStart: false` and call `game.engine.start()`
-  once the manager exists (`examples/race-mp-3d/src/main.ts`):
+  once the manager exists (`examples/race-mp-3d/src/App.tsx`):
 
   ```ts
   const game = await createGame3D({ canvas, scene, behaviors, autoStart: false });

package/skills/incanto-save-slots.md

@@ -267,7 +267,7 @@ signature of a save format change, so the hunt started in the wrong place
 entirely.
 
 **To keep the continue INSIDE the game** (where a harness can reach it —
-`runScript` boots the scene, never your `main.ts`), do it on the first frame:
+`runScript` boots the scene, never your `App.tsx`), do it on the first frame:
 
 ```ts
 class Game extends Behavior {

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

@@ -428,7 +428,7 @@ it does not load. Every CLI (`incanto-check`, `-playtest`, `-verify`, `-feel`,
 game and your harness are the two places you write it yourself:
 
 ```ts
-// main.ts — vite. Every *.scene.json beside this file, keyed by the path an
+// App.tsx — vite. Every *.scene.json beside this file, keyed by the path an
 // `instance:` names.
 const prefabs = import.meta.glob('./*.scene.json', { eager: true, import: 'default' });
 const resolveScene = (path: string): unknown => prefabs[`./${path}`] ?? null;

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

@@ -914,8 +914,8 @@ thing gating it: keep it `false` (or dev-gated) in anything you publish.
 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
+SCENE. Two of the nastiest defects this engine has had lived exactly there: a boot
+file 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

package/skills/incanto-web-integration.md

@@ -9,8 +9,46 @@ description: Embed an Incanto game in a React/Next/any web app — the IncantoCa
 > installed engine version. Sibling skills live in `node_modules/incanto/skills/`.
 
 Incanto's core is framework-free and every entry imports cleanly in Node (SSR
-safe). `incanto/react` is the official last mile — React is an OPTIONAL peer:
-`bun add react` only if you use it.
+safe). React is an OPTIONAL peer of the package — but every project
+`incanto-new` scaffolds already ships it, because the whole stack is
+**TypeScript + Vite + React**.
+
+## Two shapes, and which one you want
+
+| | `src/App.tsx` (what a scaffold gives you) | `<IncantoCanvas>` (`incanto/react`) |
+|---|---|---|
+| owns | the whole page | one box inside a bigger app |
+| canvas | yours, one `<canvas ref>` | the component's |
+| boot | your own `createGame2D/3D` call | the component's |
+| gives you | every boot option — `editor`, asset preloading with a progress bar, `showBootFailure` | scene, behaviors, and the common options |
+| HUD | `HudLayer` nodes, or DOM in `index.html` | `children`, with `useGame()` inside |
+
+**A scaffolded game keeps its own `App.tsx`.** It is ten lines and it can pass
+anything `createGame3D` takes:
+
+```tsx
+export function App() {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    // StrictMode runs this twice against the SAME element — boot once.
+    if (!canvas || (canvas as { _incanto?: true })._incanto) return;
+    (canvas as { _incanto?: true })._incanto = true;
+    void (async () => {
+      const game = await createGame3D({ canvas, scene: sceneJson, behaviors });
+      (window as unknown as { game: typeof game }).game = game;
+      document.querySelector('#loading')?.remove();
+    })();
+  }, []);
+  return <canvas ref={canvasRef} id="game" />;
+}
+```
+
+`index.html` holds `<div id="root"></div>` styled `display: contents`, so every
+CSS rule that used to target the canvas as a body child still applies.
+
+Reach for `IncantoCanvas` instead when the game is a COMPONENT of a site you
+already have — a page with a header, a route in a Next app, a card in a grid.
 
 ## React: the component
 

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

@@ -51,10 +51,15 @@ point-and-click or an RTS starts from).
 ```
 src/game.scene.json   ← the game. Nodes, props, connections. This is most of it.
 src/behaviors.ts      ← the parts JSON cannot express. Usually very little.
-src/main.ts           ← boot. You rarely touch it.
+src/App.tsx           ← boot. The React component that owns the canvas. Rarely touched.
+src/main.tsx          ← mounts <App /> into #root. Never touched.
 verify.ts             ← the harness that proves it works. You WILL touch it.
 ```
 
+Every project is **TypeScript + Vite + React**: `main.tsx` mounts the app,
+`App.tsx` renders one `<canvas>` and boots the engine into it from an effect.
+React is the shell, not the game — the game is still the JSON.
+
 The claim that "all structure is JSON" is not marketing: one of the four builds
 shipped a whole 3D world with **zero** gameplay TypeScript, and another needed
 90 lines for one melee swing. Reach for a built-in behavior before you write a

package/templates-app/beacon-isle-3d/PROJECT/Structure.md

@@ -5,7 +5,8 @@ generate-world.ts        the WORLD AUTHORING script (bun run world):
                          island terrain + sea + groves/grass/flowers +
                          quest sites on walkable ground → src/game.scene.json
 index.html               canvas + loading bar
-src/main.ts              preload → createGame3D
+src/main.tsx             React entry — mounts <App /> into #root
+src/App.tsx              preload → createGame3D
 src/game.scene.json      GENERATED — do not hand-edit; edit generate-world.ts
 src/behaviors.ts         IsleDirector (quest FSM, terrain-nav shade AI,
                          ward relighting, fireworks, respawn) + SwordStrike

package/templates-app/beacon-isle-3d/index.html

@@ -54,15 +54,18 @@
         font-size: 0.85rem;
         color: #aaa;
       }
+      #root {
+        display: contents;
+      }
     </style>
   </head>
   <body>
-    <canvas></canvas>
+    <div id="root"></div>
     <div id="loading" class="loading-container">
       <div class="loading-title">Beacon Isle</div>
       <div class="progress-track"><div id="progress"></div></div>
       <div id="progress-text">0%</div>
     </div>
-    <script type="module" src="/src/main.ts"></script>
+    <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>

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

@@ -14,12 +14,17 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.77.0",
+    "incanto": "^0.78.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "three": "^0.184.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
     "@types/three": "^0.184.1",
+    "@vitejs/plugin-react": "^6.0.3",
     "typescript": "^6.0.3",
     "vite": "^8.0.16"
   }

package/templates-app/beacon-isle-3d/src/App.tsx

@@ -0,0 +1,77 @@
+/**
+ * Beacon Isle — the incanto 3D template: a generated island (terrain, sea,
+ * groves, grass, flowers), a quest with a real NPC, shades that HUNT you
+ * across the surface via terrain navigation, melee with a bone-mounted sword,
+ * golden-hour grade + bloom, touch controls on phones — regenerate the whole
+ * world with `bun run world`, the game logic never changes.
+ */
+import { assetUrls, preloadUrls } from 'incanto';
+import { createGame3D, showBootFailure } from 'incanto/3d';
+import { useEffect, useRef } from 'react';
+import { BEHAVIORS } from './behaviors';
+import gameJson from './game.scene.json';
+
+export function App() {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    // StrictMode runs this effect twice against the SAME canvas element, and a
+    // second engine on one canvas is two renderers fighting for one context.
+    // The flag lives on the element, so it lasts exactly as long as the thing
+    // it guards — a page-level game like this one never unmounts otherwise.
+    if (!canvas || (canvas as { _incanto?: true })._incanto) return;
+    (canvas as { _incanto?: true })._incanto = true;
+
+    void (async () => {
+      const fill = document.querySelector('#progress') as HTMLElement | null;
+      const text = document.querySelector('#progress-text') as HTMLElement | null;
+      await preloadUrls(assetUrls(gameJson.assets), (done, total) => {
+        const pct = total > 0 ? Math.round((done / total) * 100) : 100;
+        if (fill) fill.style.width = `${pct}%`;
+        if (text) text.textContent = `${pct}%`;
+      });
+      /** Dev-only surfaces: the ☰ debug overlay, and the editor behind it. */
+      const DEBUG = import.meta.env.VITE_INCANTO_DEBUG === '1';
+
+      const game = await createGame3D({
+        debug: DEBUG,
+        // The editor's 📚 buttons, served by `incantoLibrary()` in vite.config.ts.
+        // BOTH halves are the opt-in, and this half was missing from every shipped
+        // template: the plugin alone left a vite config whose own comment promised
+        // "the agent8 asset catalog behind the 📚 buttons" and no button anywhere.
+        // Gated on the same flag, because `editor` DEFAULTS to `debug` and an object
+        // here would turn the editor on in a production build.
+        editor: DEBUG && { library: true },
+        canvas,
+        scene: gameJson,
+        behaviors: BEHAVIORS,
+        pointer: true,
+      }).catch((e) => {
+        // Without this the player watches the loading overlay sit at 100% forever:
+        // `#loading` is removed on the line below, so anything that rejects here (no
+        // WebGL context, a scene that will not load) leaves the bar up and the reason
+        // in a console nobody opens.
+        showBootFailure(e);
+        throw e;
+      });
+
+      // The console handle FIRST, before any wiring of your own can throw.
+      // `game.stats()`, `game.assetErrors()`, `game.frame()` and `game.engine.log`
+      // are the entire in-page diagnostic surface, and a static build has no other.
+      // Assigned after the wiring, one mistake below took all of them with it.
+      (window as unknown as { game: typeof game }).game = game;
+
+      // The overlay comes down LAST, after any wiring of your own. There is none in
+      // this template — when you add some, put it above this line and wrap it:
+      //
+      //   try { …your wiring… } catch (e) { showBootFailure(e); throw e; }
+      //
+      // A throw between the overlay coming down and the handle going up used to leave
+      // a level that renders perfectly with no player and no error of any kind.
+      document.querySelector('#loading')?.remove();
+    })();
+  }, []);
+
+  return <canvas ref={canvasRef} id="game" />;
+}

package/templates-app/beacon-isle-3d/src/main.tsx

@@ -0,0 +1,9 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+
+createRoot(document.getElementById('root') as HTMLElement).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

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

@@ -7,7 +7,8 @@
     "noEmit": true,
     "skipLibCheck": true,
     "resolveJsonModule": true,
-    "types": ["vite/client", "node"]
+    "types": ["vite/client", "node"],
+    "jsx": "react-jsx"
   },
   "include": ["src", "verify.ts", "vite.config.ts"]
 }

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

@@ -1,12 +1,15 @@
+import react from '@vitejs/plugin-react';
 import { incantoLibrary, incantoScenes } from 'incanto/vite';
 import { defineConfig } from 'vite';
 
 export default defineConfig({
   base: './',
+  // react(): the app entry is React — src/main.tsx mounts <App />, and App.tsx
+  //   owns the canvas the engine draws into.
   // 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()],
+  plugins: [react(), incantoScenes(), incantoLibrary()],
 });

package/templates-app/molehill-2d/PROJECT/Structure.md

@@ -3,7 +3,8 @@
 ```
 src/game.scene.json   the whole game's structure — holes, moles, HUD, wiring
 src/behaviors.ts      Molehill (when a mole pops) + Scoreboard (what the HUD says)
-src/main.ts           createGame2D, the pointer, the two behaviours
+src/main.tsx          React entry — mounts <App /> into #root
+src/App.tsx           createGame2D, the pointer, the two behaviours
 verify.ts             the headless proof — drives the MOUSE
 coverage.json         the gate's two questions: can it hurt you, can it be lost
 ```

package/templates-app/molehill-2d/index.html

@@ -59,6 +59,9 @@
           transform: rotate(360deg);
         }
       }
+      #root {
+        display: contents;
+      }
     </style>
   </head>
   <body>
@@ -67,7 +70,7 @@
       <div class="spinner"></div>
       <div class="hint">click the moles — twelve to win, three misses and they win</div>
     </div>
-    <canvas id="game"></canvas>
-    <script type="module" src="/src/main.ts"></script>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>

package/templates-app/molehill-2d/package.json

@@ -11,12 +11,17 @@
   },
   "dependencies": {
     "@dimforge/rapier2d-compat": "0.19.3",
-    "incanto": "^0.77.0",
+    "incanto": "^0.78.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "three": "^0.184.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
     "@types/three": "^0.184.1",
+    "@vitejs/plugin-react": "^6.0.3",
     "typescript": "^6.0.3",
     "vite": "^8.0.16"
   }

package/templates-app/molehill-2d/src/App.tsx

@@ -0,0 +1,58 @@
+/**
+ * Molehill — a whack-a-mole you play with the MOUSE and nothing else.
+ *
+ * No character body, no keyboard, no gravity. Nine holes, a mole that pops out
+ * of one of them, three misses before they win. The engine's `Clickable` turns
+ * each mole into a node that reports being clicked; the built-in `ScoreKeeper`
+ * holds the score and the misses; the wiring between them is `game.scene.json`.
+ *
+ * It is the starter for a whole family the other templates do not cover —
+ * match-3, tower defense, cards, point-and-click, RTS, board games, idle.
+ */
+import { createGame2D, showBootFailure } from 'incanto/2d';
+import { useEffect, useRef } from 'react';
+import { Molehill, Scoreboard } from './behaviors';
+import sceneJson from './game.scene.json';
+
+export function App() {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    // StrictMode runs this effect twice against the SAME canvas element, and a
+    // second engine on one canvas is two renderers fighting for one context.
+    // The flag lives on the element, so it lasts exactly as long as the thing
+    // it guards — a page-level game like this one never unmounts otherwise.
+    if (!canvas || (canvas as { _incanto?: true })._incanto) return;
+    (canvas as { _incanto?: true })._incanto = true;
+
+    void (async () => {
+      /** Dev-only surfaces: the ☰ debug overlay, and the editor behind it. */
+      const DEBUG = import.meta.env.VITE_INCANTO_DEBUG === '1';
+
+      try {
+        const game = await createGame2D({
+          canvas,
+          scene: sceneJson,
+          behaviors: { Molehill, Scoreboard },
+          // The cursor is the input. `lockOnClick` would HIDE it, which is exactly
+          // wrong for a game you play by pointing — the pointer is attached for its
+          // position, and nothing else.
+          pointer: { lockOnClick: false },
+          debug: DEBUG,
+          // Gated on the same flag: `editor` DEFAULTS to `debug`, so a bare object
+          // here turns it on in a production build — and this file also hangs the
+          // game handle off `globalThis`, so `game.openEditor()` would be one line
+          // away in a shipped build. Every other starter gates it; this one did not.
+          editor: DEBUG && { library: true },
+        });
+        document.getElementById('loading')?.remove();
+        (globalThis as { game?: unknown }).game = game;
+      } catch (error) {
+        showBootFailure(error);
+      }
+    })();
+  }, []);
+
+  return <canvas ref={canvasRef} id="game" />;
+}

package/templates-app/molehill-2d/src/main.tsx

@@ -0,0 +1,9 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+
+createRoot(document.getElementById('root') as HTMLElement).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/templates-app/molehill-2d/tsconfig.json

@@ -7,7 +7,8 @@
     "noEmit": true,
     "skipLibCheck": true,
     "resolveJsonModule": true,
-    "types": ["vite/client", "node"]
+    "types": ["vite/client", "node"],
+    "jsx": "react-jsx"
   },
   "include": ["src", "verify.ts", "vite.config.ts"]
 }

package/templates-app/molehill-2d/vite.config.ts

@@ -1,12 +1,15 @@
+import react from '@vitejs/plugin-react';
 import { incantoLibrary, incantoScenes } from 'incanto/vite';
 import { defineConfig } from 'vite';
 
 export default defineConfig({
   base: './',
+  // react(): the app entry is React — src/main.tsx mounts <App />, and App.tsx
+  //   owns the canvas the engine draws into.
   // 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()],
+  plugins: [react(), incantoScenes(), incantoLibrary()],
 });

package/templates-app/platformer-2d/PROJECT/Context.md

@@ -28,7 +28,7 @@ _Exact versions are in `package.json`._
   ScoreKeeper, …).
 - **Art**: built-in animated sheets `medieval-knight` (player) + `goblin`
   (enemy), and `coin` + `gem` item textures — all bundler-imported from the
-  package and injected into the scene asset urls in `main.ts`. Ground, platforms,
+  package and injected into the scene asset urls in `App.tsx`. Ground, platforms,
   spikes, flags and parallax castle are styled `ColorRect2D`.
 - **Audio**: zero-asset procedural SFX presets (jump/coin/hit/hurt/powerup/
   win/lose); an OPTIONAL `engine.music` hook for a looping track.

package/templates-app/platformer-2d/PROJECT/Requirements.md

@@ -31,7 +31,7 @@
 - Moving platforms: `Patrol` (horizontal ferry) / `Oscillate` (vertical lift) on
   a `StaticBody2D` in the `platform` group — the `Feet` sensor + carry logic ride
   them. Bobbing pickups: `Oscillate` on the sprite child.
-- Keep `main.ts` thin: inject the four built-in asset urls (knight/goblin/coin/
+- Keep `App.tsx` thin: inject the four built-in asset urls (knight/goblin/coin/
   gem), boot `createGame2D` with the scene + behaviors, optional music, the
   on-screen JUMP button, remove the loader, expose `window.game`. There is NO
   respawn-via-scene-reload (respawn is in-level in `PlayerController`).
@@ -56,7 +56,7 @@
   hazards/checkpoint/goal/feet-sensor = `Area2D`.
 - Sprites: `medieval-knight` (idle 0–5, move 6–11, attack 12–17; jump reuses a
   move frame) and `goblin` (idle 0–6, move 7–12). Swap a sheet by changing only
-  the asset entry + the import in `main.ts`.
+  the asset entry + the import in `App.tsx`.
 - The parallax "castle" is styled `ColorRect2D` bands + towers (no tilemap node
   in v0). Background art is the obvious next polish pass; the hero sprites carry
   the look. Music is OPTIONAL (`MUSIC_URL` empty by default; SFX presets need no

package/templates-app/platformer-2d/PROJECT/Status.md

@@ -26,7 +26,7 @@
   `Particles2D`.
 - `connections`: each coin/gem `collected → addScore` (+ SFX); root `won/lost →
   SfxWin/SfxLose`.
-- `main.ts`: inject the four asset urls, `createGame2D`, optional music, JUMP
+- `App.tsx`: inject the four asset urls, `createGame2D`, optional music, JUMP
   button, remove loader, expose `window.game`. Node uids omitted (loader-
   generated).
 

package/templates-app/platformer-2d/PROJECT/Structure.md

@@ -13,7 +13,7 @@ THE whole level (open it with `npx incanto-editor`):
 - scene header — `environment.background`, `viewport` (`design [960,540]`, `fit:
   expand`), `physics.gravity [0,1800]`, `move`/`jump` input, and the
   `knight`/`goblin` spritesheets + `coin`/`gem` texture `assets` (urls injected
-  in `main.ts`).
+  in `App.tsx`).
 - `Game` root — `ScoreKeeper` (`scoreToWin 100000`, `lives 3`).
 - Parallax castle backdrop — `Sky`/`Sun`/`Cloud1–3` (far), `CastleFar` band +
   `TowerFarA–C`, `CastleNear` band + `BattlementA/B` — `ColorRect2D` +
@@ -56,7 +56,7 @@ THE whole level (open it with `npx incanto-editor`):
 - `ParallaxLayer` — re-anchor a backdrop to `cameraX · factor` for depth.
 - `HudUpdater` — score/hearts/lives Labels + win/lose banner.
 
-## `src/main.ts`
+## `src/main.tsx` and `src/App.tsx`
 
 Boot: inject the four built-in asset urls, `createGame2D({ canvas, scene,
 behaviors })`, optional `engine.music`, the JUMP button, remove the loader,

package/templates-app/platformer-2d/docs/project-2d-rules.md

@@ -25,7 +25,7 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template
    `newUid`). NEVER hand-invent readable uid strings.
 5. 📦 ASSETS ARE DECLARED: `assets` entries need `type` + `url`; reference them as
    `"$key"`. The knight + goblin sheets and the coin + gem textures are BUILT-INS
-   (`incanto/assets/...`) imported in `main.ts` and injected into the asset url
+   (`incanto/assets/...`) imported in `App.tsx` and injected into the asset url
    placeholders before boot. Free extra key-values are preserved — use them for
    notes (frame ranges, license, source).
 6. ⬇️ Y IS DOWN: 2D space is y-down pixels, (0,0) top-left, clockwise degrees.