incanto 0.29.0 → 0.30.0

package/dist/{gameplay-L05WgWd1.js → gameplay-Cfr6aFZ1.js}

@@ -2367,6 +2367,15 @@ var Node3D = class Node3D extends Node {
 			this.position[2] ?? 0
 		];
 	}
+	/**
+	* @internal The backing object IF it has been built — never builds one.
+	*
+	* `_ensureObject3D()` is the wrong call during teardown: it allocates a mesh
+	* for a node that never rendered, purely so the next line can dispose it.
+	*/
+	get _builtObject3D() {
+		return this._object3D;
+	}
 	/** @internal The backing three object (lazily created). */
 	_ensureObject3D() {
 		if (!this._object3D) {
@@ -3341,9 +3350,9 @@ var Water3D = class Water3D extends Node3D {
 		} : null;
 	}
 	free() {
-		const mesh = this._ensureObject3D();
-		mesh.geometry?.dispose();
-		mesh.material?.dispose?.();
+		const mesh = this._builtObject3D;
+		mesh?.geometry?.dispose();
+		(mesh?.material)?.dispose?.();
 		this.cubeTarget?.dispose();
 		this.cubeTarget = null;
 		this.cubeCamera = null;

package/dist/gameplay.js

@@ -1,2 +1,2 @@
-import { C as FollowCamera, D as Health, E as DamageOnContact, O as Collector, S as restartScene, T as phaseOf, _ as hitStop, a as Wander, b as GameFlow, c as Projectile, d as PathFollow, f as Oscillate, g as Cooldown, h as CameraShake, i as WaveSpawner, k as Chase, l as Pickup, m as Lifetime, n as registerGameplayBehaviors, o as Spawner, p as MoveTo, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as Patrol, v as screenFlash, w as DayNight, x as goToScene, y as Interactable } from "./gameplay-L05WgWd1.js";
+import { C as FollowCamera, D as Health, E as DamageOnContact, O as Collector, S as restartScene, T as phaseOf, _ as hitStop, a as Wander, b as GameFlow, c as Projectile, d as PathFollow, f as Oscillate, g as Cooldown, h as CameraShake, i as WaveSpawner, k as Chase, l as Pickup, m as Lifetime, n as registerGameplayBehaviors, o as Spawner, p as MoveTo, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as Patrol, v as screenFlash, w as DayNight, x as goToScene, y as Interactable } from "./gameplay-Cfr6aFZ1.js";
 export { CameraShake, Chase, Collector, Cooldown, DamageOnContact, DayNight, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, Projectile, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, phaseOf, registerGameplayBehaviors, restartScene, screenFlash };

package/dist/index.d.ts

@@ -47,6 +47,15 @@ declare class WebAudioMusicBackend implements MusicBackend {
 */
 interface DebugLineSource {
   readonly dimension: "2d" | "3d";
+  /**
+  * The engine whose world these lines describe.
+  *
+  * A page can hold more than one at a time — the editor runs its edit engine
+  * and a preview engine side by side — and a renderer must draw ITS world, not
+  * whichever source happens to be first in a module-level Set. Without this,
+  * one leaked physics instance paints its frozen colliders over everybody.
+  */
+  readonly engine: object;
   /** Toggle at runtime: `physics.debugDraw = true`. */
   debugDraw: boolean;
   /**

package/dist/index.js

@@ -295,6 +295,6 @@ function newUid() {
 //#endregion
 //#region src/index.ts
 /** Engine version. Kept in sync with package.json by the release pipeline. */
-const VERSION = "0.29.0";
+const VERSION = "0.30.0";
 //#endregion
 export { AudioBuses, AudioPlayer, Behavior, CONST_REF_KEY, Engine, HudLayer, IncantoError, InputMap, LogManager, MusicManager, Node, ORDER_GROUP_BASE, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, ParticleSim, ROLLOFF_MODELS, Rng, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, Scene, SceneTree, SfxEngine, Signal, Timer, TouchControls, UiBanner, UiBar, UiButton, UiDialogue, UiText, VERSION, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, auditScene, clearBehaviors, clearRegistry, computeViewport, createNode, createNoise2D, createSaveStore, crossfadeGains, duplicateNode, effectiveOrder, fadeGain, findPath, getBehavior, getNodeSchema, getNodeSignals, getNodeType, gridFromRows, isAudioContextAvailable, isConstRef, joystickVector, jsonClone, jsonEquals, jsonKind, loadScene, mergeStaticSignals, newUid, parseNodePath, preloadUrls, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, replay, resolveConstants, resolveRendering, resolveViewport, serializeNode, spatialGain, spatialPan, startRecording, synthSfx };

package/dist/{physics-2d-CCVTrKOd.js → physics-2d-3kOQCtgd.js}

@@ -1,7 +1,7 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { _ as RigidBody2D, b as validateCollider2D, g as PhysicsBody2D, h as CharacterBody2D, m as Area2D, p as Joint2D, y as Node2D } from "./register-DWcWq4QG.js";
-import { n as registerDebugSource } from "./debug-draw-CZmOYjL2.js";
+import { n as registerDebugSource } from "./debug-draw-BM3DsvtT.js";
 //#region src/2d/physics/physics-2d.ts
 var physics_2d_exports = /* @__PURE__ */ __exportAll({
 	Physics2D: () => Physics2D,
@@ -46,6 +46,7 @@ var Physics2D = class {
 		this.R = R;
 		this.engine = engine;
 		this.optsGravity = opts?.gravity;
+		this.simulate = opts?.simulate ?? true;
 		this.lastScene = engine.scene;
 		const declared = engine.scene?.physics?.gravity;
 		const g = opts?.gravity ?? declared ?? [0, 980];
@@ -64,8 +65,15 @@ var Physics2D = class {
 		this.syncBodies();
 	}
 	/** @internal Driven by engine.fixedUpdated. */
+	/** Whether the solver runs at all. False = collider outlines only. */
+	simulate;
 	step(dt) {
 		this.lastDt = dt;
+		if (!this.simulate) {
+			this.syncBodies();
+			this.poseFromTree();
+			return;
+		}
 		if (this.engine.scene !== this.lastScene) {
 			this.lastScene = this.engine.scene;
 			if (!this.optsGravity) {
@@ -294,6 +302,23 @@ var Physics2D = class {
 	jointSet = /* @__PURE__ */ new Set();
 	joints = /* @__PURE__ */ new Map();
 	bodySet = /* @__PURE__ */ new Set();
+	/**
+	* Move every body to its node's current transform — outline mode only.
+	*
+	* Computed exactly as `ensureEntry` computes a body's first pose, so an
+	* outline drawn in the editor is the outline the running game draws.
+	*/
+	poseFromTree() {
+		for (const [node, e] of this.entries) {
+			const [wx, wy] = worldPosition2D(node);
+			e.body.setTranslation({
+				x: wx / SCALE,
+				y: wy / SCALE
+			}, false);
+			e.body.setRotation(node.rotation * DEG, false);
+		}
+		this.world.propagateModifiedBodyPositionsToColliders();
+	}
 	syncBodies() {
 		const scene = this.engine.scene;
 		if (!scene) return;

package/dist/{physics-3d-BZZLtwJu.js → physics-3d-CeRH-Ff_.js}

@@ -1,8 +1,8 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { F as PhysicsBody3D, I as RigidBody3D, N as Area3D, P as CharacterBody3D, R as Node3D, z as validateCollider3D } from "./gameplay-L05WgWd1.js";
-import { n as registerDebugSource } from "./debug-draw-CZmOYjL2.js";
-import { I as buildMeshGeometry, N as Joint3D, P as InstancedMesh3D, k as Terrain3D } from "./register-C44aSduO.js";
+import { F as PhysicsBody3D, I as RigidBody3D, N as Area3D, P as CharacterBody3D, R as Node3D, z as validateCollider3D } from "./gameplay-Cfr6aFZ1.js";
+import { n as registerDebugSource } from "./debug-draw-BM3DsvtT.js";
+import { I as buildMeshGeometry, N as Joint3D, P as InstancedMesh3D, k as Terrain3D } from "./register-DJ0SByQg.js";
 import { Euler, Matrix4, Quaternion, Vector3 } from "three";
 //#region src/3d/physics/collider-lines.ts
 /**
@@ -241,6 +241,7 @@ var Physics3D = class {
 		this.R = R;
 		this.engine = engine;
 		this.optsGravity = opts?.gravity;
+		this.simulate = opts?.simulate ?? true;
 		this.lastScene = engine.scene;
 		const declared = engine.scene?.physics?.gravity;
 		const g = opts?.gravity ?? declared ?? [
@@ -259,9 +260,16 @@ var Physics3D = class {
 		this.disconnect = engine.fixedUpdated.connect((dt) => this.step(dt));
 		this.syncBodies();
 	}
+	/** Whether the solver runs at all. False = collider outlines only. */
+	simulate;
 	/** @internal Driven by engine.fixedUpdated. */
 	step(dt) {
 		this.lastDt = dt;
+		if (!this.simulate) {
+			this.syncBodies();
+			this.poseFromTree();
+			return;
+		}
 		if (this.engine.scene !== this.lastScene) {
 			this.lastScene = this.engine.scene;
 			if (!this.optsGravity) {
@@ -332,6 +340,33 @@ var Physics3D = class {
 			}
 		});
 	}
+	/**
+	* Move every body to its node's current transform.
+	*
+	* Only used in outline mode: normally physics owns the pose and writes it
+	* INTO the node, so nothing re-reads the tree. Deliberately computed the same
+	* way `ensureEntry` computes a body's initial pose — world position, node-local
+	* euler — so an outline in the editor is the outline the game will draw, right
+	* down to the places where that pair disagrees with a rotated parent.
+	*/
+	poseFromTree() {
+		for (const [node, e] of this.entries) {
+			const [wx, wy, wz] = worldPosition3D(node);
+			e.body.setTranslation({
+				x: wx,
+				y: wy,
+				z: wz
+			}, false);
+			quatScratch.setFromEuler(eulerScratch.set((node.rotation[0] ?? 0) * DEG, (node.rotation[1] ?? 0) * DEG, (node.rotation[2] ?? 0) * DEG, "XYZ"));
+			e.body.setRotation({
+				x: quatScratch.x,
+				y: quatScratch.y,
+				z: quatScratch.z,
+				w: quatScratch.w
+			}, false);
+		}
+		this.world.propagateModifiedBodyPositionsToColliders();
+	}
 	/** @internal Called by CharacterBody3D.moveAndSlide (during tree fixedUpdate). */
 	moveAndSlide(node) {
 		const e = this.ensureEntry(node);

package/dist/react.js

@@ -156,7 +156,7 @@ function IncantoCanvas(props) {
 				pointer: latest.pointer,
 				...keyboard !== void 0 ? { keyboard } : {}
 			};
-			const next = await (_gameFactory ?? (mode === "3d" ? async (o) => (await import("./create-game-CNKXGfpr.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-CbuLWorm.js").then((n) => n.n)).createGame2D(o)))(opts);
+			const next = await (_gameFactory ?? (mode === "3d" ? async (o) => (await import("./create-game-DuBTv2zI.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-5z_QVtLx.js").then((n) => n.n)).createGame2D(o)))(opts);
 			if (disposed) {
 				next.dispose();
 				return;

package/dist/{register-C44aSduO.js → register-DJ0SByQg.js}

@@ -4,7 +4,7 @@ import { t as Rng } from "./rng-DP-SR7eg.js";
 import { i as getNodeSchema, l as registerNode } from "./registry-BVJ2HbCn.js";
 import { t as createNoise2D } from "./noise-CGUMx44x.js";
 import { i as applyParticlePreset, r as PARTICLE_PRESET_NAMES, t as ParticleSim } from "./particle-sim-Bw7hB93B.js";
-import { A as Water3D, F as PhysicsBody3D, H as colliderFootDrop, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D } from "./gameplay-L05WgWd1.js";
+import { A as Water3D, F as PhysicsBody3D, H as colliderFootDrop, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D } from "./gameplay-Cfr6aFZ1.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
 import { AdditiveBlending, AnimationClip, AnimationMixer, Box3, BoxGeometry, BufferAttribute, BufferGeometry, CanvasTexture, CapsuleGeometry, Color, ConeGeometry, CylinderGeometry, DataTexture, DirectionalLight, DoubleSide, DynamicDrawUsage, Euler, Group, IcosahedronGeometry, ImageBitmapLoader, InstancedBufferAttribute, InstancedMesh, LinearFilter, LoopOnce, LoopRepeat, Matrix4, Mesh, MeshBasicMaterial, MeshDepthMaterial, MeshPhysicalMaterial, MeshStandardMaterial, NearestFilter, NoBlending, NormalBlending, PerspectiveCamera, PlaneGeometry, PointLight, Points, PointsMaterial, Quaternion, QuaternionKeyframeTrack, RGBADepthPacking, RGBAFormat, RepeatWrapping, SRGBColorSpace, ShaderChunk, ShaderMaterial, SphereGeometry, Texture, TextureLoader, UniformsLib, UniformsUtils, Vector3, Vector4, VectorKeyframeTrack } from "three";
 import { clone } from "three/addons/utils/SkeletonUtils.js";

package/dist/{editor-switch-CAKlJMIY.js → teardown-ByzfDPyu.js}

@@ -69,6 +69,35 @@ function devServerLibrary(token) {
 	};
 }
 /**
+* Does the page's own dev server serve the project's scenes?
+*
+* `incantoScenes()` from `incanto/vite` (the plugin that already validates
+* scenes on save; `incanto-new` puts it in every scaffolded project) answers
+* `GET /api/scenes`. When it does, the
+* editor a game switches into is a PROJECT editor: it can list, open, create
+* and save every scene in the project, and play whichever one you loaded.
+* When it does not (a built game, someone else's server), the editor still
+* edits the scene the game is running, exactly as before.
+*/
+async function projectScenes() {
+	try {
+		const res = await fetch("/api/scenes");
+		if (!res.ok) return null;
+		const body = await res.json();
+		return Array.isArray(body) ? body : null;
+	} catch {
+		return null;
+	}
+}
+/** What to say when the dev server has no idea what scenes this project has. */
+const NO_SCENE_ROUTES = "this dev server does not serve the project's scenes yet. Add incantoScenes() to vite.config.ts and restart:\n\n  import { incantoScenes } from 'incanto/vite';\n  export default defineConfig({ plugins: [incantoScenes()] });\n\nIt also validates every scene you save, before the page reloads into a broken one.";
+async function readProjectScene(file) {
+	const res = await fetch(`/api/scene?file=${encodeURIComponent(file)}`);
+	if (res.ok) return await res.json();
+	const body = await res.json().catch(() => null);
+	throw new Error(body?.error ?? `could not open ${file}: HTTP ${res.status}`);
+}
+/**
 * The default opener: pull `incanto/editor` in on demand and mount it.
 *
 * It is a dynamic import so the editor — an IDE's worth of UI — never enters a
@@ -83,18 +112,44 @@ async function openBundledEditor(opts) {
 		throw new Error(`createGame3D editor: could not load 'incanto/editor'. If this app aliases incanto to the engine SOURCE (the examples and playground do), add an alias for 'incanto/editor' → packages/editor/src/main.ts — or pass editor: { open } and load it yourself. (${error instanceof Error ? error.message : String(error)})`);
 	}
 	let handle = null;
+	const project = await projectScenes();
+	const format = mod.formatSceneJson ?? ((json) => JSON.stringify(json, null, 2));
+	const writeProjectScene = async (file, json) => {
+		const res = await fetch(`/api/scene?file=${encodeURIComponent(file)}`, {
+			method: "PUT",
+			body: format(json)
+		});
+		if (!res.ok) throw new Error(`could not save ${file}: HTTP ${res.status} ${await res.text()}`);
+	};
 	handle = await mod.mountEditor({
 		...opts.camera ? { camera: opts.camera } : {},
 		api: {
 			meta: async () => ({
 				version: "live",
-				mode: "single",
+				mode: "project",
 				root: "",
 				input: null,
 				output: null
 			}),
-			loadScene: async () => opts.scene,
-			...opts.save ? { saveScene: async (json) => void opts.save?.(json) } : {},
+			loadScene: async (file) => file ? await readProjectScene(file) : opts.scene,
+			...opts.save || project ? { saveScene: async (json, file) => {
+				if (file) return writeProjectScene(file, json);
+				await opts.save?.(json);
+			} } : {},
+			scenes: async () => {
+				const found = await projectScenes();
+				if (!found) throw new Error(NO_SCENE_ROUTES);
+				return found;
+			},
+			createScene: async (path) => {
+				const res = await fetch("/api/scenes", {
+					method: "POST",
+					body: JSON.stringify({ path })
+				});
+				if (res.status === 404) throw new Error(NO_SCENE_ROUTES);
+				if (!res.ok) throw new Error(`could not create ${path}: ${await res.text()}`);
+				return await res.json();
+			},
 			...opts.library ? { library: opts.library } : {}
 		},
 		onPlay: (choice, working) => {
@@ -158,4 +213,28 @@ function poseFromRenderer(renderer, fallbackDistance = 8) {
 	};
 }
 //#endregion
-export { poseFromRenderer as i, devServerLibrary as n, openBundledEditor as r, crossFade as t };
+//#region src/core/teardown.ts
+function teardown(steps, onError = defaultReport) {
+	const failures = [];
+	for (const step of steps) {
+		if (!step) continue;
+		const [what, run] = step;
+		try {
+			run();
+		} catch (error) {
+			failures.push({
+				what,
+				error
+			});
+			try {
+				onError(what, error);
+			} catch {}
+		}
+	}
+	return { failures };
+}
+function defaultReport(what, error) {
+	console.error(`[incanto] teardown: ${what} failed (continuing)`, error);
+}
+//#endregion
+export { poseFromRenderer as a, openBundledEditor as i, crossFade as n, devServerLibrary as r, teardown as t };

package/dist/test.js

@@ -4,9 +4,9 @@ import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as auditScene } from "./audit-C6rMyict.js";
 import { n as jsonEquals, t as jsonClone } from "./json-BLk7H2Qa.js";
 import { i as getNodeSchema, s as mergeStaticProps } from "./registry-BVJ2HbCn.js";
-import { n as registerGameplayBehaviors } from "./gameplay-L05WgWd1.js";
+import { n as registerGameplayBehaviors } from "./gameplay-Cfr6aFZ1.js";
 import { t as registerNodes2D } from "./register-DWcWq4QG.js";
-import { t as registerNodes3D } from "./register-C44aSduO.js";
+import { t as registerNodes3D } from "./register-DJ0SByQg.js";
 import { t as registerNodesNet } from "./register-MelqEdza.js";
 //#region src/test/index.ts
 /**
@@ -218,10 +218,10 @@ async function runScript(json, opts) {
 	engine.setScene(scene);
 	const physics = opts.physics ?? "auto";
 	if (physics === "2d" || physics === "auto" && scene.dimension === "2d") {
-		const { enablePhysics2D } = await import("./physics-2d-CCVTrKOd.js").then((n) => n.r);
+		const { enablePhysics2D } = await import("./physics-2d-3kOQCtgd.js").then((n) => n.r);
 		await enablePhysics2D(engine);
 	} else if (physics === "3d" || physics === "auto" && scene.dimension === "3d") {
-		const { enablePhysics3D } = await import("./physics-3d-BZZLtwJu.js").then((n) => n.r);
+		const { enablePhysics3D } = await import("./physics-3d-CeRH-Ff_.js").then((n) => n.r);
 		await enablePhysics3D(engine);
 	}
 	const failures = [];
@@ -323,10 +323,10 @@ async function createPlaySession(json, opts = {}) {
 	engine.setScene(scene);
 	const physics = opts.physics ?? "auto";
 	if (physics === "2d" || physics === "auto" && scene.dimension === "2d") {
-		const { enablePhysics2D } = await import("./physics-2d-CCVTrKOd.js").then((n) => n.r);
+		const { enablePhysics2D } = await import("./physics-2d-3kOQCtgd.js").then((n) => n.r);
 		await enablePhysics2D(engine);
 	} else if (physics === "3d" || physics === "auto" && scene.dimension === "3d") {
-		const { enablePhysics3D } = await import("./physics-3d-BZZLtwJu.js").then((n) => n.r);
+		const { enablePhysics3D } = await import("./physics-3d-CeRH-Ff_.js").then((n) => n.r);
 		await enablePhysics3D(engine);
 	}
 	const stepMs = 1e3 / (opts.fixedHz ?? 60);

package/dist/vite.d.ts

@@ -17,11 +17,97 @@ interface HotUpdateContext {
 interface IncantoScenesOptions {
   /** Hard-fail on unregistered behaviors too (default: structure-only). */
   strictBehaviors?: boolean;
+  /**
+  * Where scenes are found and written. Default: vite's `root` (your project).
+  * Nothing outside it is readable or writable, whatever a request asks for.
+  */
+  root?: string;
 }
 declare function incantoScenes(opts?: IncantoScenesOptions): {
   name: string;
   handleHotUpdate(ctx: HotUpdateContext): Promise<undefined | never[]>;
+  configureServer(server: SceneDevServer): void;
+};
+/**
+* `GET /api/scenes` → every `*.scene.json` under the project root
+* `POST /api/scenes` `{path}` → create a minimal scene there
+* `GET /api/scene?file=<rel>` → that scene's JSON
+* `PUT /api/scene?file=<rel>` → write it back (bytes verbatim)
+*
+* These are the routes `incanto-editor` serves, on YOUR dev server, so the
+* editor a game switches into is a project editor rather than a single-file
+* one: it can list, open, create and save any scene in the project, and play
+* whichever one you loaded.
+*
+* Everything is bounded to the root and to `*.scene.json`. A dev server is
+* still a server: `?file=../../.ssh/id_rsa` has to be a 400, not a read.
+*/
+interface SceneDevServer {
+  config?: {
+    root?: string;
+  };
+  middlewares: {
+    use(path: string, handler: (req: ApiReq, res: LibraryRes) => void): void;
+  };
+}
+interface ApiReq extends LibraryReq {
+  on(event: "data" | "end" | "error", cb: (chunk?: unknown) => void): void;
+}
+/**
+* One JSON file in the project, and whether it is a scene.
+*
+* A file browser that only shows `*.scene.json` cannot show you the scene you
+* saved as `level.json` — and, worse, gives no reason for its absence. So the
+* list is every `.json` under the project (a scene is JSON by definition, so
+* nothing else can be one), and `scene` says which of them actually are.
+*/
+interface ProjectFileEntry {
+  rel: string;
+  abs: string;
+  size: number;
+  modified: number;
+  /** Present only when the file IS a scene — read from the file, not the name. */
+  scene?: {
+    name: string;
+    dimension?: "2d" | "3d";
+    nodes: number;
+  };
+  /** Why it is not one, in a form a person can act on. */
+  notScene?: string;
+}
+/**
+* Is this JSON an incanto scene? The file itself answers.
+*
+* A scene declares what it is — `{"format": 1, "type": "scene", "name", "root"}`
+* — and those are exactly the four keys the loader demands before it will build
+* anything (`validateHeader`). So "is this a scene" is not a guess from the file
+* name; it is a fact readable from the first object in the file. That is what
+* lets the browser mark a row ✓ instead of hoping.
+*/
+declare function sceneFacts(json: unknown): {
+  ok: true;
+  name: string;
+  dimension?: "2d" | "3d";
+  nodes: number;
+} | {
+  ok: false;
+  why: string;
 };
+/** @internal Exported for tests. Root-bounded walk, deepest 6 levels. */
+declare function discoverScenes(root: string): ProjectFileEntry[];
+/**
+* @internal The one place a request's path becomes a file path.
+*
+* `.json` under the project, nothing else — the file browser offers every JSON
+* and the loader decides, but a dev server still must not be a way to read
+* `.env` or somebody's key file. Content is gated separately: a JSON that is
+* not a scene is never sent to the page, only the reason it is not one.
+*/
+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>;
+/** @internal Exported for tests — `GET`/`PUT /api/scene?file=`. */
+declare function serveSceneFile(req: ApiReq, res: LibraryRes, root: string): Promise<void>;
 interface DevServer {
   middlewares: {
     use(path: string, handler: (req: LibraryReq, res: LibraryRes) => void): void;
@@ -75,4 +161,4 @@ declare function incantoLibrary(opts?: IncantoLibraryOptions): {
 /** @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 { IncantoLibraryOptions, IncantoScenesOptions, incantoLibrary, incantoScenes, serveLibrary };
+export { IncantoLibraryOptions, IncantoScenesOptions, ProjectFileEntry, discoverScenes, incantoLibrary, incantoScenes, resolveSceneFile, sceneFacts, serveLibrary, serveSceneFile, serveSceneList };