incanto 0.76.0 → 0.78.0

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

@@ -11,12 +11,17 @@
   },
   "dependencies": {
     "@dimforge/rapier2d-compat": "0.19.3",
-    "incanto": "^0.76.0",
+    "incanto": "^0.78.0",
+    "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.

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

@@ -49,6 +49,9 @@
           transform: rotate(360deg);
         }
       }
+      #root {
+        display: contents;
+      }
     </style>
   </head>
   <body>
@@ -56,7 +59,7 @@
       <h2 class="loading-title">Castle Run</h2>
       <div class="spinner"></div>
     </div>
-    <canvas id="game"></canvas>
+    <div id="root"></div>
     <script>
       // agent8 embed harness: report the game size to a hosting iframe parent.
       function postGameSize() {
@@ -71,6 +74,6 @@
         if (e.data && e.data.type === 'REQUEST_GAME_SIZE') postGameSize();
       });
     </script>
-    <script type="module" src="/src/main.ts"></script>
+    <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>

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

@@ -11,12 +11,17 @@
   },
   "dependencies": {
     "@dimforge/rapier2d-compat": "0.19.3",
-    "incanto": "^0.76.0",
+    "incanto": "^0.78.0",
+    "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/platformer-2d/src/App.tsx

@@ -0,0 +1,115 @@
+/**
+ * Castle Run — a polished 2D adventure PLATFORMER on Incanto. Run a medieval
+ * knight through a castle: A/D (or arrows) to run, Space/W to jump — tap again in
+ * the air to DOUBLE-JUMP, and the controller forgives you with coyote-time +
+ * jump-buffering. STOMP goblins from above (and chain-bounce), ride the moving
+ * platform and the lift, grab coins + gems, dodge the spikes and the pit, touch
+ * the Checkpoint flag so a fall sends you back there, and reach the gold flag to
+ * clear the castle. Three hearts per life, three lives.
+ *
+ * The level is JSON: StaticBody2D platforms, Patrol/Oscillate moving platforms +
+ * goblins, Pickup coins/gems, ScoreKeeper score/lives/win-lose, AudioPlayer SFX —
+ * all wired in `game.scene.json`. The custom TypeScript is the game FEEL the
+ * built-ins leave open: PlayerController (coyote/buffer/double-jump/variable
+ * height/stomp/knockback/checkpoint-respawn/platform-carry), GoblinSkin,
+ * FollowCam (follow + screen-shake), ParallaxLayer, HudUpdater.
+ */
+import { createGame2D, showBootFailure } from 'incanto/2d';
+import goblinUrl from 'incanto/assets/characters/goblin.png';
+import knightUrl from 'incanto/assets/characters/medieval-knight.png';
+import coinUrl from 'incanto/assets/items/coin.png';
+import gemUrl from 'incanto/assets/items/gem.png';
+import { useEffect, useRef } from 'react';
+import { FollowCam, GoblinSkin, HudUpdater, ParallaxLayer, PlayerController } 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 () => {
+      // Built-in sprite art ships in the package — import the URLs and inject them into
+      // the scene's asset placeholders before boot (the engine clones the scene).
+
+      // OPTIONAL looping music (large tracks aren't bundled). Point at any URL to loop.
+      const MUSIC_URL = '';
+
+      const behaviors = { PlayerController, GoblinSkin, FollowCam, ParallaxLayer, HudUpdater };
+
+      const scene = structuredClone(sceneJson) as typeof sceneJson & {
+        assets: {
+          knight: { url: string };
+          goblin: { url: string };
+          coin: { url: string };
+          gem: { url: string };
+        };
+      };
+      scene.assets.knight.url = knightUrl;
+      scene.assets.goblin.url = goblinUrl;
+      scene.assets.coin.url = coinUrl;
+      scene.assets.gem.url = gemUrl;
+
+      /** Dev-only surfaces: the ☰ debug overlay, and the editor behind it. */
+      const DEBUG = import.meta.env.VITE_INCANTO_DEBUG === '1';
+
+      const game = await createGame2D({
+        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,
+        behaviors,
+      }).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;
+
+      // And the loading overlay comes down LAST. Everything between here and there is
+      // your code; a throw in it used to leave a level that renders perfectly with no
+      // player, no error UI, and no way to ask the page what happened.
+      try {
+        if (MUSIC_URL) {
+          game.engine.music.play(MUSIC_URL, { loop: true, fadeIn: 1.5 });
+          game.engine.audio.music = 0.3;
+        }
+
+        // No hand-rolled touch button here: the scene declares `"touch": "button"` on
+        // `jump` and `"touch": "joystick"` on `move`, so the ENGINE draws both on a
+        // coarse pointer — safe-area aware, off the home-indicator band, and sized to
+        // its own rules. This template used to draw an 88 px disc of its own at a flat
+        // `bottom: 2rem`, which covered 78% of the engine's jump button and put its
+        // lower edge inside the band iOS reserves for the leave-the-app swipe.
+      } catch (e) {
+        showBootFailure(e);
+        throw e;
+      }
+
+      document.querySelector('#loading')?.remove();
+    })();
+  }, []);
+
+  return <canvas ref={canvasRef} id="game" />;
+}

package/templates-app/platformer-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/platformer-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/platformer-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/star-survivor/PROJECT/Context.md

@@ -21,7 +21,7 @@ _Exact versions are in `package.json`._
   AnimatedSprite2D, ColorRect2D, Camera2D, AudioPlayer) + `incanto/gameplay`
   (auto-registered Spawner, Chase, Health, DamageOnContact, ScoreKeeper, …).
 - **Art**: built-in animated sheets `medieval-knight` (player), `goblin` + `ghost`
-  (enemies), bundler-imported in `main.ts` and injected into the scene asset urls.
+  (enemies), bundler-imported in `App.tsx` and injected into the scene asset urls.
   Arena/bolts/XP shards are `ColorRect2D`.
 - **Audio**: procedural SFX presets (shoot/coin/hurt/win/lose). HUD is DOM.
 - **Build/Lang**: Vite, TypeScript. **Headless verify**: `incanto/test` (`runScript`).

package/templates-app/star-survivor/PROJECT/Requirements.md

@@ -42,6 +42,6 @@
 - The clone path is internal, so spawning leans on built-in `Spawner` + `Director`
   scatter; bolts/XP are managed `ColorRect2D`s (no per-projectile behavior).
 - Sprites: `medieval-knight`/`goblin` (192px frames), `ghost` (112×128). Swap a sheet
-  by changing only its asset entry + the import in `main.ts`.
+  by changing only its asset entry + the import in `App.tsx`.
 - Difficulty ramps with elapsed time (spawn rate + enemy HP/speed); tune in `Director`
   and the `Survivor` constants. Music is OPTIONAL (`MUSIC_URL` empty; SFX need no files).

package/templates-app/star-survivor/PROJECT/Status.md

@@ -14,7 +14,7 @@
 - Custom `src/behaviors.ts`: `Survivor` (move + auto-attack managed bolts + XP magnet
   + level-up/upgrades + pause via `engine.stop/start` + DOM HUD), `Director`
   (ring-scatter spawns + time escalation), `EnemyDrop`, `EnemyFace`.
-- `main.ts` injects the three sheet urls; `vite.config.ts` aliases `incanto/assets`.
+- `App.tsx` injects the three sheet urls; `vite.config.ts` aliases `incanto/assets`.
 
 ## Works (verified)
 

package/templates-app/star-survivor/PROJECT/Structure.md

@@ -14,7 +14,7 @@ The arena + horde, mostly BUILT-INS:
 
 - header — `background`, `viewport` (`design [960,540]`, `fit: expand`),
   `physics.gravity [0,0]` (top-down), `move` input (WASD+arrows), and the
-  `knight`/`goblin`/`ghost` spritesheet `assets` (urls injected in `main.ts`).
+  `knight`/`goblin`/`ghost` spritesheet `assets` (urls injected in `App.tsx`).
 - `Game` root — `ScoreKeeper` (`scoreToWin 1`, `lives 1`).
 - `Arena`/`ArenaPad`/`ArenaRing*` — dark `ColorRect2D` floor + a centre marker.
 - `Player` — `CharacterBody2D` (group `player`) + `Survivor`; children `Skin`
@@ -42,7 +42,7 @@ The arena + horde, mostly BUILT-INS:
   group `xp` with an `_xp` value) + `Survivor.addKill()`.
 - `EnemyFace` — flip the enemy sprite toward travel + play `move`.
 
-## `src/main.ts`
+## `src/main.tsx` and `src/App.tsx`
 
 Inject the knight/goblin/ghost urls, `createGame2D({ canvas, scene, behaviors })`,
 optional music, remove the loader, expose `window.game`.

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

@@ -17,7 +17,7 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template
    escalation), `EnemyDrop` (XP shard + kill on death), `EnemyFace` (sprite facing).
 4. 🔑 UIDS ARE GENERATED: omit `uid` and the loader assigns one. Never hand-invent.
 5. 📦 ASSETS ARE DECLARED: `assets` entries need `type` + `url`; reference as `"$key"`.
-   The knight/goblin/ghost sheets are BUILT-INS imported in `main.ts` and injected
+   The knight/goblin/ghost sheets are BUILT-INS imported in `App.tsx` and injected
    into the asset url placeholders before boot. ⚠️ For `incanto/assets/*` imports to
    resolve in `bun run dev`, `vite.config.ts` needs an `'incanto/assets'` ALIAS to
    `../../packages/engine/assets` (see this template's config).

package/templates-app/star-survivor/index.html

@@ -190,6 +190,9 @@
         text-shadow: 0 2px 14px rgba(0, 0, 0, 0.9);
         transition: opacity 0.3s;
       }
+      #root {
+        display: contents;
+      }
     </style>
   </head>
   <body>
@@ -197,7 +200,7 @@
       <h2 class="loading-title">Hollow Horde</h2>
       <div class="spinner"></div>
     </div>
-    <canvas id="game"></canvas>
+    <div id="root"></div>
     <div id="hud">
       <div class="bar-track" id="hp-track"><div class="bar-fill" id="hp-fill"></div></div>
       <div id="hp-text">100</div>
@@ -227,6 +230,6 @@
         if (e.data && e.data.type === 'REQUEST_GAME_SIZE') postGameSize();
       });
     </script>
-    <script type="module" src="/src/main.ts"></script>
+    <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>

package/templates-app/star-survivor/package.json

@@ -11,12 +11,17 @@
   },
   "dependencies": {
     "@dimforge/rapier2d-compat": "0.19.3",
-    "incanto": "^0.76.0",
+    "incanto": "^0.78.0",
+    "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/star-survivor/src/App.tsx

@@ -0,0 +1,94 @@
+/**
+ * Hollow Horde — a top-down SURVIVORS-LIKE (Vampire Survivors genre) on Incanto.
+ * Move with WASD / arrows; your knight AUTO-ATTACKS the nearest enemy. Goblins and
+ * faster ghosts pour in from every side and grow tougher over time. Cut them down,
+ * vacuum up the XP shards they drop, and on each LEVEL-UP pick one of three
+ * upgrades. Survive 90 seconds to win — let the horde drain your HP and you fall.
+ *
+ * The horde is BUILT-IN gameplay wired in `game.scene.json`: two `Spawner`s clone
+ * goblin/ghost templates, each enemy `Chase`s the player, and a `DamageOnContact`
+ * hitbox drains `Health`. The custom TypeScript is the survivor FEEL the library
+ * leaves open: `Survivor` (move + auto-attack + XP/level-up/upgrades + HUD),
+ * `Director` (ring-spawn around the player + escalation), `EnemyDrop`, `EnemyFace`.
+ */
+import { createGame2D, showBootFailure } from 'incanto/2d';
+import ghostUrl from 'incanto/assets/characters/ghost.png';
+import goblinUrl from 'incanto/assets/characters/goblin.png';
+import knightUrl from 'incanto/assets/characters/medieval-knight.png';
+import { useEffect, useRef } from 'react';
+import { Director, EnemyDrop, EnemyFace, GridFloor, Survivor } 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 () => {
+      const MUSIC_URL = '';
+
+      const behaviors = { Survivor, Director, EnemyDrop, EnemyFace, GridFloor };
+
+      const scene = structuredClone(sceneJson) as typeof sceneJson & {
+        assets: { knight: { url: string }; goblin: { url: string }; ghost: { url: string } };
+      };
+      scene.assets.knight.url = knightUrl;
+      scene.assets.goblin.url = goblinUrl;
+      scene.assets.ghost.url = ghostUrl;
+
+      /** Dev-only surfaces: the ☰ debug overlay, and the editor behind it. */
+      const DEBUG = import.meta.env.VITE_INCANTO_DEBUG === '1';
+
+      const game = await createGame2D({
+        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,
+        behaviors,
+      }).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;
+
+      // And the loading overlay comes down LAST. Everything between here and there is
+      // your code; a throw in it used to leave a level that renders perfectly with no
+      // player, no error UI, and no way to ask the page what happened.
+      try {
+        if (MUSIC_URL) {
+          game.engine.music.play(MUSIC_URL, { loop: true, fadeIn: 1.5 });
+          game.engine.audio.music = 0.3;
+        }
+      } catch (e) {
+        showBootFailure(e);
+        throw e;
+      }
+
+      document.querySelector('#loading')?.remove();
+    })();
+  }, []);
+
+  return <canvas ref={canvasRef} id="game" />;
+}

package/templates-app/star-survivor/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/star-survivor/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/star-survivor/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/tps-3d/PROJECT/Status.md

@@ -24,7 +24,7 @@
 - `src/behaviors.ts`: `Shoot` (18-round clip, hitscan within a ~9° crosshair cone
   to 70 m, tracer + muzzle flash, face-aim on fire, reload) and `HudUpdater`
   (HP/Kills/Wave/Ammo + health bar + SECURE/FAILED banner).
-- `src/main.ts`: preloads the GLB + animation assets with a progress bar
+- `src/App.tsx`: preloads the GLB + animation assets with a progress bar
   (`preloadUrls(assetUrls(scene.assets))`), then `createGame3D` with
   `pointer: true`, looping music, on-screen FIRE/JUMP buttons, `window.game`.
 - `index.html`: canvas + center crosshair + HUD overlay + banner + mobile buttons.