incanto 0.28.0 → 0.30.0

package/dist/{register-CvpSUU3O.js → register-DWcWq4QG.js}

@@ -1,5 +1,5 @@
 import { f as Node } from "./loader-BZqOKfI2.js";
-import { t as registerCoreNodes } from "./register-nObreUQR.js";
+import { t as registerCoreNodes } from "./register-BTg0EM7s.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
 import { i as getNodeSchema, l as registerNode } from "./registry-BVJ2HbCn.js";
@@ -115,7 +115,27 @@ var Node2D = class extends Node {
 * `{shape:'capsule', radius, height}` — never child shape nodes.
 */
 var PhysicsBody2D = class extends Node2D {
-	static props = { collider: { default: {} } };
+	static props = { collider: {
+		default: {},
+		variants: {
+			tag: "shape",
+			byTag: {
+				rect: {
+					shape: "rect",
+					size: [32, 32]
+				},
+				circle: {
+					shape: "circle",
+					radius: 16
+				},
+				capsule: {
+					shape: "capsule",
+					radius: 12,
+					height: 32
+				}
+			}
+		}
+	} };
 	/** The unified collision model: every collider participant can emit these. */
 	static signals = ["triggerEnter", "triggerExit"];
 	_collider = {};

package/dist/{register-BFFE1Mh1.js → register-MelqEdza.js}

@@ -1,5 +1,5 @@
 import { f as Node, t as buildNodeJson, y as Signal } from "./loader-BZqOKfI2.js";
-import { t as registerCoreNodes } from "./register-nObreUQR.js";
+import { t as registerCoreNodes } from "./register-BTg0EM7s.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { n as jsonEquals, t as jsonClone } from "./json-BLk7H2Qa.js";
 import { l as registerNode } from "./registry-BVJ2HbCn.js";

package/dist/teardown-ByzfDPyu.js

@@ -0,0 +1,240 @@
+//#region src/core/editor-switch.ts
+/**
+* Cover the page while it changes what it is.
+*
+* A mode switch tears down a whole game and builds a whole IDE in its place;
+* between those two the window shows a dead canvas, a flash of white body, and
+* then a fully-formed editor. Every one of those frames is honest and none of
+* them is pleasant. A veil makes the crossing read as one movement: fade to the
+* editor's own background, do the work behind it, fade back.
+*
+* Deliberately CSS-only and dependency-free — it has to work in a game page
+* whose styles we know nothing about, so it sits at the top of the stacking
+* order, eats pointer events (nobody clicks a UI that is being replaced), and
+* removes itself completely. In a headless boot there is no document and this
+* is a pair of no-ops.
+*/
+const VEIL_MS = 160;
+function raiseVeil(label = "", background = "#0b0d14") {
+	if (typeof document === "undefined") return { lift: () => {} };
+	const el = document.createElement("div");
+	el.dataset.incantoSwitch = "";
+	el.style.cssText = `position:fixed;inset:0;z-index:2147483646;background:${background};display:flex;align-items:center;justify-content:center;opacity:0;transition:opacity ${VEIL_MS}ms ease;pointer-events:auto;`;
+	if (label) {
+		const text = document.createElement("div");
+		text.textContent = label;
+		text.style.cssText = "font:13px/1 ui-monospace,SFMono-Regular,Menlo,monospace;color:#5d6680;letter-spacing:0.04em;";
+		el.appendChild(text);
+	}
+	document.body.appendChild(el);
+	requestAnimationFrame(() => {
+		el.style.opacity = "1";
+	});
+	let lifted = false;
+	return { lift() {
+		if (lifted) return;
+		lifted = true;
+		requestAnimationFrame(() => {
+			el.style.opacity = "0";
+			setTimeout(() => el.remove(), 200);
+		});
+	} };
+}
+/** Hold the veil up for at least one paint so the fade is visible at all. */
+async function settle(ms = VEIL_MS) {
+	if (typeof requestAnimationFrame !== "function") return;
+	await new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* The `/api/library` route `incanto/vite`'s `incantoLibrary()` (and the
+* `incanto-editor` server) serve. Used when a game passes `library: true`.
+*/
+function devServerLibrary(token) {
+	return async (query) => {
+		const params = new URLSearchParams({
+			tags: query.tags.join(","),
+			page: String(query.page ?? 1),
+			limit: String(query.limit ?? 24)
+		});
+		if (query.keyword?.trim()) params.set("keyword", query.keyword.trim());
+		const res = await fetch(`/api/library?${params}`, { headers: token ? { "x-incanto-v8-token": token } : {} });
+		if (res.status === 401) {
+			const body = await res.json().catch(() => ({}));
+			const error = new Error(body.error ?? "the asset library needs a Verse8 access token");
+			error.needsToken = true;
+			throw error;
+		}
+		if (!res.ok) throw new Error(`asset library: HTTP ${res.status}`);
+		return await res.json();
+	};
+}
+/**
+* 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
+* production bundle. A build that cannot resolve it fails HERE, with the two
+* ways to fix it, rather than silently offering a menu item that does nothing.
+*/
+async function openBundledEditor(opts) {
+	let mod;
+	try {
+		mod = await import("incanto/editor");
+	} catch (error) {
+		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: "project",
+				root: "",
+				input: null,
+				output: null
+			}),
+			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) => {
+			if (choice !== "debug") return void 0;
+			const camera = handle?.camera();
+			return crossFade(async () => {
+				handle?.dispose();
+				handle = null;
+				await opts.play(working, camera);
+			}, "starting the game…");
+		},
+		...opts.exit ? { onExit: () => crossFade(async () => {
+			handle?.dispose();
+			handle = null;
+			await opts.exit?.();
+		}, "back to the game…") } : {}
+	});
+}
+/**
+* Run a mode change behind the veil: cover, swap, reveal.
+*
+* The reveal waits for the new page to have PAINTED (two frames — one for the
+* layout the swap just produced, one for it to reach the screen), otherwise the
+* fade-out races the boot and shows the very flash it exists to hide.
+*/
+async function crossFade(swap, label = "") {
+	const veil = raiseVeil(label);
+	await settle();
+	try {
+		await swap();
+	} finally {
+		await settle(0);
+		veil.lift();
+	}
+}
+/**
+* The camera the player is actually looking through, as a pose.
+*
+* Reads the renderer's LAST rendered camera rather than the scene's Camera3D:
+* a third-person rig, a cutscene camera and a debug free-fly all end up in the
+* same place, and it is the view on screen — the thing continuity is about.
+*/
+function poseFromRenderer(renderer, fallbackDistance = 8) {
+	const basis = renderer.cameraBasis;
+	const posOf = renderer.lastCameraPosition;
+	if (typeof basis !== "function" || typeof posOf !== "function") return void 0;
+	const eye = posOf.call(renderer);
+	if (!eye) return void 0;
+	const { forward } = basis.call(renderer);
+	return {
+		position: [
+			eye.x,
+			eye.y,
+			eye.z
+		],
+		target: [
+			eye.x + forward.x * fallbackDistance,
+			eye.y + forward.y * fallbackDistance,
+			eye.z + forward.z * fallbackDistance
+		]
+	};
+}
+//#endregion
+//#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.d.ts

@@ -1,9 +1,41 @@
 import { c as JsonValue, i as SceneJson } from "./schema-CcoWb32N.js";
-import { $ as Node, T as LogEntry, n as BehaviorCtor, v as Engine, w as Scene } from "./behavior-CPibUfnH.js";
-import { t as LoadSceneOptions } from "./loader-DILt9PGC.js";
+import { $ as Node, T as LogEntry, n as BehaviorCtor, v as Engine, w as Scene } from "./behavior-BAc0erXF.js";
+import { t as LoadSceneOptions } from "./loader-B242FF6N.js";
 import { i as auditScene, t as IncantoError } from "./errors-1dXlIwoR.js";
 
 //#region src/test/index.d.ts
+/** One thing that is not standing where it should be. */
+interface GroundingIssue {
+  /** Scene path, e.g. `/World/Footbridge/PostL0`. */
+  path: string;
+  /** Metres between the node's underside and the ground: + floats, − buried. */
+  gap: number;
+}
+interface GroundingOptions {
+  /** How far a foot may sit off the ground before it is a bug (default 0.1 m). */
+  tolerance?: number;
+  /** Node types to check (default: the ones that read as props on a map). */
+  types?: readonly string[];
+}
+/**
+* Every prop that is floating or buried.
+*
+* THE most repeated mistake in scene authoring, by humans and agents alike, is
+* a hand-computed Y: correct when it is written and wrong the moment anything
+* reshapes the ground under it — a river carving its bed, a new seed, a
+* generator that mirrors a carve slightly differently. This is the check that
+* catches it, and `snapToGround` is the fix that stops it happening.
+*
+* Anything explicitly marked `snapToGround: false` is skipped: that is the
+* author saying "yes, this hangs in the air", which a bridge deck, a lantern
+* and a cloud all legitimately do.
+*
+* ```ts
+* const off = findFloatingProps(gameJson);
+* ok(`nothing floats (${off.length})`, off.length === 0);
+* ```
+*/
+declare function findFloatingProps(json: unknown, opts?: GroundingOptions): GroundingIssue[];
 declare function registerAllNodes(): void;
 interface NodeCapture {
   /** Absolute path ('/Root/Player') — stable, grep-able. */
@@ -149,4 +181,4 @@ interface PlaySession {
 */
 declare function createPlaySession(json: unknown, opts?: PlaySessionOptions): Promise<PlaySession>;
 //#endregion
-export { NodeCapture, PlaySession, PlaySessionOptions, RunContext, RunFailure, RunResult, RunScriptOptions, SceneCapture, ScriptStep, ValidateSceneOptions, ValidationResult, auditScene, captureScene, createPlaySession, describeCapture, registerAllNodes, runScript, validateScene };
+export { GroundingIssue, GroundingOptions, NodeCapture, PlaySession, PlaySessionOptions, RunContext, RunFailure, RunResult, RunScriptOptions, SceneCapture, ScriptStep, ValidateSceneOptions, ValidationResult, auditScene, captureScene, createPlaySession, describeCapture, findFloatingProps, registerAllNodes, runScript, validateScene };

package/dist/test.js

@@ -1,13 +1,13 @@
 import { _ as registerBehavior, n as loadScene } from "./loader-BZqOKfI2.js";
-import { u as Engine } from "./register-nObreUQR.js";
+import { u as Engine } from "./register-BTg0EM7s.js";
 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-DEG-TP7D.js";
-import { t as registerNodes2D } from "./register-CvpSUU3O.js";
-import { t as registerNodes3D } from "./register-6R75AC7-.js";
-import { t as registerNodesNet } from "./register-BFFE1Mh1.js";
+import { n as registerGameplayBehaviors } from "./gameplay-Cfr6aFZ1.js";
+import { t as registerNodes2D } from "./register-DWcWq4QG.js";
+import { t as registerNodes3D } from "./register-DJ0SByQg.js";
+import { t as registerNodesNet } from "./register-MelqEdza.js";
 //#region src/test/index.ts
 /**
 * incanto/test — the browserless verification harness.
@@ -25,6 +25,100 @@ import { t as registerNodesNet } from "./register-BFFE1Mh1.js";
 * Deterministic by construction: fixed timestep, seeded `engine.rng`,
 * no requestAnimationFrame.
 */
+/** Node types whose whole job is to sit on the ground. Characters, water,
+* clouds, birds and lights are all legitimately off it. */
+const GROUNDED_TYPES = ["MeshInstance3D", "InstancedMesh3D"];
+/** Under one of these, the BODY owns where the thing stands — a character's
+* skin hangs at whatever offset its rig wants, and is not a floating prop. */
+const BODY_OWNED = new Set([
+	"CharacterBody3D",
+	"RigidBody3D",
+	"StaticBody3D",
+	"AreaBody3D"
+]);
+/**
+* Every prop that is floating or buried.
+*
+* THE most repeated mistake in scene authoring, by humans and agents alike, is
+* a hand-computed Y: correct when it is written and wrong the moment anything
+* reshapes the ground under it — a river carving its bed, a new seed, a
+* generator that mirrors a carve slightly differently. This is the check that
+* catches it, and `snapToGround` is the fix that stops it happening.
+*
+* Anything explicitly marked `snapToGround: false` is skipped: that is the
+* author saying "yes, this hangs in the air", which a bridge deck, a lantern
+* and a cloud all legitimately do.
+*
+* ```ts
+* const off = findFloatingProps(gameJson);
+* ok(`nothing floats (${off.length})`, off.length === 0);
+* ```
+*/
+function findFloatingProps(json, opts = {}) {
+	registerAllNodes();
+	const tolerance = opts.tolerance ?? .1;
+	const types = new Set(opts.types ?? GROUNDED_TYPES);
+	let scene;
+	try {
+		scene = loadScene(json);
+	} catch {
+		return [];
+	}
+	let ground = null;
+	const findGround = (node) => {
+		if (!ground && node.constructor.typeName === "Terrain3D" && typeof node.heightAt === "function") ground = node;
+		for (const child of node.children) findGround(child);
+	};
+	findGround(scene.root);
+	if (!ground) return [];
+	const out = [];
+	const walk = (node, path, ox, oy, oz, yaw, bodyOwned) => {
+		const n = node;
+		let wx = ox;
+		let wy = oy;
+		let wz = oz;
+		let ownYaw = yaw;
+		if (Array.isArray(n.position)) {
+			const c = Math.cos(yaw);
+			const s = Math.sin(yaw);
+			const lx = n.position[0] ?? 0;
+			const lz = n.position[2] ?? 0;
+			wx = ox + lx * c + lz * s;
+			wz = oz - lx * s + lz * c;
+			wy = oy + (n.position[1] ?? 0);
+			ownYaw = yaw + (n.rotation?.[1] ?? 0) * Math.PI / 180;
+		}
+		const type = node.constructor.typeName ?? "";
+		const soil = ground;
+		if (types.has(type) && n.visible !== false && n.snapToGround !== false && !bodyOwned) {
+			const rows = node.transforms;
+			if (Array.isArray(rows) && rows.length > 0) {
+				let worst = null;
+				for (const row of rows) {
+					const scale = row[4] ?? 1;
+					const half = (n.size?.[1] ?? 0) * scale / 2;
+					const gap = wy + (row[1] ?? 0) - half - soil.heightAt(wx + (row[0] ?? 0), wz + (row[2] ?? 0));
+					if (Math.abs(gap) > tolerance && (!worst || Math.abs(gap) > Math.abs(worst.gap))) worst = {
+						path,
+						gap: Math.round(gap * 100) / 100
+					};
+				}
+				if (worst) out.push(worst);
+			} else {
+				const half = (n.size?.[1] ?? 0) / 2;
+				const gap = wy - half - soil.heightAt(wx, wz);
+				if (Math.abs(gap) > tolerance) out.push({
+					path,
+					gap: Math.round(gap * 100) / 100
+				});
+			}
+		}
+		const childBodyOwned = bodyOwned || BODY_OWNED.has(type);
+		for (const child of node.children) walk(child, `${path}/${child.name}`, wx, wy, wz, ownYaw, childBodyOwned);
+	};
+	walk(scene.root, `/${scene.root.name}`, 0, 0, 0, 0, false);
+	return out;
+}
 function registerAllNodes() {
 	registerNodes2D();
 	registerNodes3D();
@@ -124,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-DiVFFlH3.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--y5clE2j.js").then((n) => n.r);
+		const { enablePhysics3D } = await import("./physics-3d-CeRH-Ff_.js").then((n) => n.r);
 		await enablePhysics3D(engine);
 	}
 	const failures = [];
@@ -229,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-DiVFFlH3.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--y5clE2j.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);
@@ -267,4 +361,4 @@ async function createPlaySession(json, opts = {}) {
 	};
 }
 //#endregion
-export { auditScene, captureScene, createPlaySession, describeCapture, registerAllNodes, runScript, validateScene };
+export { auditScene, captureScene, createPlaySession, describeCapture, findFloatingProps, registerAllNodes, runScript, validateScene };

package/dist/vite.d.ts

@@ -17,10 +17,148 @@ 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;
+  };
+}
+interface LibraryReq {
+  url?: string | undefined;
+  method?: string | undefined;
+  headers: Record<string, string | string[] | undefined>;
+}
+interface LibraryRes {
+  statusCode: number;
+  setHeader(name: string, value: string): void;
+  end(body?: string): void;
+}
+interface IncantoLibraryOptions {
+  /**
+  * Verse8 access token. Defaults to INCANTO_V8_TOKEN / V8_ACCESS_TOKEN.
+  * Read at request time so a token exported after the server started works.
+  */
+  token?: string;
+  /** Upstream catalog (default: the agent8 backend). */
+  url?: string;
+}
+/**
+* Serve the agent8 asset catalog at `/api/library` on the dev server.
+*
+* The catalog wants a bearer token and does not CORS-allow localhost, so a page
+* cannot call it — but the dev server can, and it is already running. This is
+* the same proxy `incanto-editor` ships, so the editor's 📚 works identically
+* whether it opened as a page or over a running game.
+*
+* DEV ONLY (vite `configureServer`): nothing about it reaches a build, and the
+* token stays in the terminal that started the server.
+*
+* ```ts
+* // vite.config.ts
+* import { incantoLibrary, incantoScenes } from 'incanto/vite';
+* export default defineConfig({ plugins: [incantoScenes(), incantoLibrary()] });
+* ```
+* ```ts
+* // main.ts — the editor then offers the library
+* createGame3D({ ..., debug: DEV, editor: { library: true } });
+* ```
+*/
+declare function incantoLibrary(opts?: IncantoLibraryOptions): {
+  name: string;
+  apply: "serve";
+  configureServer(server: DevServer): void;
+};
+/** @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 { IncantoScenesOptions, incantoScenes };
+export { IncantoLibraryOptions, IncantoScenesOptions, ProjectFileEntry, discoverScenes, incantoLibrary, incantoScenes, resolveSceneFile, sceneFacts, serveLibrary, serveSceneFile, serveSceneList };