incanto 0.76.0 → 0.77.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-DygJfhOb.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-DygJfhOb.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.77.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-DygJfhOb.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.77.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",

package/skills/incanto-editor.md

@@ -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/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.76.0",
+    "incanto": "^0.77.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

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

@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@dimforge/rapier2d-compat": "0.19.3",
-    "incanto": "^0.76.0",
+    "incanto": "^0.77.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

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

@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@dimforge/rapier2d-compat": "0.19.3",
-    "incanto": "^0.76.0",
+    "incanto": "^0.77.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

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

@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@dimforge/rapier2d-compat": "0.19.3",
-    "incanto": "^0.76.0",
+    "incanto": "^0.77.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

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.76.0",
+    "incanto": "^0.77.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

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.76.0",
+    "incanto": "^0.77.0",
     "three": "^0.184.0"
   },
   "devDependencies": {