incanto 0.76.0 → 0.78.0

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-D823V07k.js";
+import { a as findPath, i as preloadUrls, n as assetUrls, o as gridFromRows, r as preloadSceneAssets, t as VERSION } from "./src-DzPtpk1t.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-D823V07k.js → src-DzPtpk1t.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.76.0";
+const VERSION = "0.78.0";
 //#endregion
 export { findPath as a, preloadUrls as i, assetUrls as n, gridFromRows as o, preloadSceneAssets as r, VERSION as t };

package/dist/vite.d.ts

@@ -151,6 +151,50 @@ interface IncantoScenesOptions {
   * Nothing outside it is readable or writable, whatever a request asks for.
   */
   root?: string;
+  /**
+  * Called after a scene is written through this server — the editor's save,
+  * and the editor's create. In-process, with the scene itself; the same
+  * event goes to stdout for anything watching the dev server from outside
+  * (see {@link SceneEvent}).
+  */
+  onSave?(event: SceneEvent): void;
+}
+/**
+* What this server announces when a scene lands, on stdout AND to `onSave`.
+*
+* ONE line per event, `[incanto] ` and a JSON object — readable by a person in
+* the terminal they are already watching, unambiguous to a machine, and
+* extensible without breaking a parser that only reads the fields it knows:
+*
+*     [incanto] {"event":"scene:saved","file":"src/game.scene.json","bytes":13284,"at":"2026-09-08T10:19:57.412Z"}
+*
+* It exists because a container had no way to hear a save that happened inside
+* it. The editor a running game hosts writes through `PUT /api/scene`, and the
+* only signals available to the process supervising that container were
+* accidents: watching the filesystem, or scraping vite's `page reload` line —
+* which existed only because saving used to reload the page, and went away
+* when that was fixed.
+*
+* `abs` and `json` are for `onSave` only; the printed line carries neither (an
+* absolute container path means nothing outside it, and a scene does not
+* belong on one log line).
+*/
+interface SceneEvent {
+  event: "scene:saved" | "scene:created";
+  /** Project-relative, forward slashes on every OS. */
+  file: string;
+  /** Bytes written. */
+  bytes: number;
+  /** ISO-8601, when it landed. */
+  at: string;
+  /** Absolute path — `onSave` only, never printed. */
+  abs?: string;
+  /** The scene as written — `onSave` only, never printed. */
+  json?: unknown;
+}
+/** Hooks the middlewares carry (exported for tests, not for vite). */
+interface SceneHooks {
+  onSave?(event: SceneEvent): void;
 }
 declare function incantoScenes(opts?: IncantoScenesOptions): {
   name: string;
@@ -241,9 +285,9 @@ declare function discoverScenes(root: string): ProjectFileEntry[];
 */
 declare function resolveSceneFile(root: string, rel: unknown): string | null;
 /** @internal Exported for tests — `GET`/`POST /api/scenes`. */
-declare function serveSceneList(req: ApiReq, res: LibraryRes, root: string): Promise<void>;
+declare function serveSceneList(req: ApiReq, res: LibraryRes, root: string, hooks?: SceneHooks): Promise<void>;
 /** @internal Exported for tests — `GET`/`PUT /api/scene?file=`. */
-declare function serveSceneFile(req: ApiReq, res: LibraryRes, root: string): Promise<void>;
+declare function serveSceneFile(req: ApiReq, res: LibraryRes, root: string, hooks?: SceneHooks): Promise<void>;
 interface DevServer {
   middlewares: {
     use(path: string, handler: (req: LibraryReq, res: LibraryRes) => void): void;
@@ -317,4 +361,4 @@ declare function serveDeviceAuth(req: LibraryReq, res: LibraryRes, opts?: Incant
 /** @internal Exported for tests — the whole request/response behaviour. */
 declare function serveLibrary(req: LibraryReq, res: LibraryRes, opts?: IncantoLibraryOptions, doFetch?: typeof fetch): Promise<void>;
 //#endregion
-export { type FrameHost, type FrameReq, type FrameRes, IncantoLibraryOptions, IncantoScenesOptions, type IncantoTrimOptions, ProjectFileEntry, type StaticInspectHost, createStaticInspectHost, discoverScenes, incantoLibrary, incantoScenes, incantoTrim, listeningPorts, maskToken, onlyKnownOptions, parseProcNetTcp, projectDimension, resolveSceneFile, sceneFacts, serveDeviceAuth, serveFrameEndpoints, serveLibrary, serveSceneFile, serveSceneList, serveTokenStatus };
+export { type FrameHost, type FrameReq, type FrameRes, IncantoLibraryOptions, IncantoScenesOptions, type IncantoTrimOptions, ProjectFileEntry, SceneEvent, SceneHooks, type StaticInspectHost, createStaticInspectHost, discoverScenes, incantoLibrary, incantoScenes, incantoTrim, listeningPorts, maskToken, onlyKnownOptions, parseProcNetTcp, projectDimension, resolveSceneFile, sceneFacts, serveDeviceAuth, serveFrameEndpoints, serveLibrary, serveSceneFile, serveSceneList, serveTokenStatus };

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-D823V07k.js";
+import { t as VERSION } from "./src-DzPtpk1t.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";
@@ -525,6 +525,29 @@ function incantoTrim(opts = {}) {
 * vite's Plugin interface.
 */
 /**
+* Announce a scene that LANDED. Never called for a refused write: the line
+* means the bytes are on disk, which is the only reading that is any use to a
+* process deciding whether to rebuild.
+*/
+function announce(kind, base, abs, raw, json, hooks) {
+	const event = {
+		event: kind,
+		file: relative(base, abs).split(sep).join("/"),
+		bytes: Buffer.byteLength(raw),
+		at: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	console.log(`[incanto] ${JSON.stringify(event)}`);
+	try {
+		hooks?.onSave?.({
+			...event,
+			abs,
+			json
+		});
+	} catch (error) {
+		console.error(`[incanto] onSave threw: ${message(error)}`);
+	}
+}
+/**
 * The BUILT-IN art, at the path the scenes already name.
 *
 * `incanto-assets` prints `incanto/assets/items/coin.png` as an asset's url and
@@ -604,7 +627,11 @@ const ASSET_MIME = {
 */
 const OWN_WRITES = /* @__PURE__ */ new Map();
 function incantoScenes(opts = {}) {
-	onlyKnownOptions("incantoScenes", opts, ["strictBehaviors", "root"]);
+	onlyKnownOptions("incantoScenes", opts, [
+		"strictBehaviors",
+		"root",
+		"onSave"
+	]);
 	return {
 		name: "incanto-scenes",
 		/**
@@ -615,11 +642,12 @@ function incantoScenes(opts = {}) {
 		configureServer(server) {
 			serveFrameEndpoints(server, VERSION);
 			const root = opts.root ?? server.config?.root ?? process.cwd();
+			const hooks = opts.onSave ? { onSave: opts.onSave } : {};
 			server.middlewares.use("/api/scenes", (req, res) => {
-				serveSceneList(req, res, root);
+				serveSceneList(req, res, root, hooks);
 			});
 			server.middlewares.use("/api/scene", (req, res) => {
-				serveSceneFile(req, res, root);
+				serveSceneFile(req, res, root, hooks);
 			});
 			serveBuiltInAssets(server);
 		},
@@ -838,7 +866,7 @@ function readBody(req) {
 	});
 }
 /** @internal Exported for tests — `GET`/`POST /api/scenes`. */
-async function serveSceneList(req, res, root) {
+async function serveSceneList(req, res, root, hooks) {
 	const base = normalize(resolve(root));
 	if (req.method === void 0 || req.method === "GET") return json(res, 200, discoverScenes(base));
 	if (req.method !== "POST") return json(res, 405, { error: "method not allowed" });
@@ -855,22 +883,25 @@ async function serveSceneList(req, res, root) {
 	if (existsSync(abs)) return json(res, 409, { error: `already exists: ${String(wanted)}` });
 	const name = basename(abs).replace(/\.scene\.json$|\.json$/, "") || "Scene";
 	const dimension = (body.dimension === "3d" || body.dimension === "2d" ? body.dimension : null) ?? projectDimension(base) ?? "2d";
+	const created = {
+		format: 1,
+		type: "scene",
+		dimension,
+		name,
+		root: {
+			name,
+			type: dimension === "3d" ? "Node3D" : "Node2D",
+			uid: newUid()
+		}
+	};
+	const raw = `${JSON.stringify(created, null, 2)}\n`;
 	try {
 		mkdirSync(dirname(abs), { recursive: true });
-		writeFileSync(abs, `${JSON.stringify({
-			format: 1,
-			type: "scene",
-			dimension,
-			name,
-			root: {
-				name,
-				type: dimension === "3d" ? "Node3D" : "Node2D",
-				uid: newUid()
-			}
-		}, null, 2)}\n`);
+		writeFileSync(abs, raw);
 	} catch (error) {
 		return json(res, 400, { error: message(error) });
 	}
+	announce("scene:created", base, abs, raw, created, hooks);
 	return json(res, 201, {
 		rel: relative(base, abs).split(sep).join("/"),
 		abs,
@@ -879,7 +910,7 @@ async function serveSceneList(req, res, root) {
 	});
 }
 /** @internal Exported for tests — `GET`/`PUT /api/scene?file=`. */
-async function serveSceneFile(req, res, root) {
+async function serveSceneFile(req, res, root, hooks) {
 	const base = normalize(resolve(root));
 	const file = new URL(req.url ?? "/", "http://localhost").searchParams.get("file");
 	const abs = resolveSceneFile(base, file);
@@ -937,6 +968,7 @@ async function serveSceneFile(req, res, root) {
 		return json(res, 400, { error: message(error) });
 	}
 	OWN_WRITES.set(normalize(abs), written);
+	announce("scene:saved", base, abs, written, parsed, hooks);
 	return json(res, 200, {
 		ok: true,
 		output: abs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "incanto",
-  "version": "0.76.0",
+  "version": "0.78.0",
   "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
@@ -493,6 +493,50 @@ embedded editor posts nothing. The page posts to its parent window:
 { type: 'incanto-editor:error',  message }                  // loader/save errors
 ```
 
+### Hearing a save from OUTSIDE the browser
+
+A preview running in a container saves into that container, and the process
+supervising it — the one that rebuilds, commits or syncs — is not in the page.
+It has two ways to hear about it, and neither needs the iframe:
+
+**1. stdout, zero configuration.** Every scene this dev server writes announces
+itself on the terminal you are already tailing, as ONE line: a fixed `[incanto] `
+prefix and a JSON object.
+
+```
+[incanto] {"event":"scene:saved","file":"src/game.scene.json","bytes":13284,"at":"2026-09-08T10:19:57.412Z"}
+[incanto] {"event":"scene:created","file":"src/levels/arena.scene.json","bytes":214,"at":"…"}
+```
+
+`file` is project-relative with forward slashes on every OS, `bytes` is what was
+written, `at` is ISO-8601. The line is printed only when the bytes LANDED — a
+refused write (not a scene, would overwrite a non-scene) says nothing, so the
+line means "there is something new on disk". Read the fields you know and ignore
+the rest: more may be added, these will not change. Nothing to configure; a
+project with `incantoScenes()` in its vite config already prints it.
+
+Do not scrape vite's own `page reload <file>` line for this. It appears for a
+HAND edit and deliberately does not for the editor's own save (that reload used
+to throw you out of the editor mid-edit).
+
+**2. `onSave`, in-process, with the scene itself.** When the host wants the JSON
+rather than the path:
+
+```ts
+incantoScenes({
+  onSave: ({ event, file, abs, json }) => {
+    // event: 'scene:saved' | 'scene:created'
+    void fetch('http://127.0.0.1:9000/scene-saved', {
+      method: 'POST',
+      body: JSON.stringify({ file, json }),
+    });
+  },
+})
+```
+
+It runs after the write, and a throw from it is reported and swallowed — a
+broken hook must not take the dev server down or silence the stdout line.
+
 The page can never choose filesystem paths — `input`/`output` are fixed at launch;
 the API only reads the input and writes the output. Saves are rejected (422, file
 untouched) unless the body is scene-shaped (`format: 1`, `type: "scene"`, `name`,

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.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/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>