incanto 0.1.0

package/dist/loader-CGs_G-r0.js

@@ -0,0 +1,919 @@
+import { t as IncantoError } from "./errors-BpWbnbb_.js";
+import { n as jsonEquals, t as jsonClone } from "./json-BLk7H2Qa.js";
+import { c as mergeStaticSignals, i as getNodeSchema, r as createNode, s as mergeStaticProps, t as applySchemaProps } from "./registry-BVJ2HbCn.js";
+//#region src/core/signal.ts
+var Signal = class {
+	connections = [];
+	/** Connect a listener. Returns a disposer. Connecting the same fn twice is a no-op. */
+	connect(fn, opts) {
+		if (!this.connections.some((c) => c.fn === fn)) this.connections.push({
+			fn,
+			once: opts?.once ?? false
+		});
+		return () => this.disconnect(fn);
+	}
+	disconnect(fn) {
+		const i = this.connections.findIndex((c) => c.fn === fn);
+		if (i !== -1) this.connections.splice(i, 1);
+	}
+	disconnectAll() {
+		this.connections.length = 0;
+	}
+	emit(...args) {
+		const snapshot = [...this.connections];
+		for (const conn of snapshot) {
+			if (!this.connections.includes(conn)) continue;
+			if (conn.once) this.disconnect(conn.fn);
+			conn.fn(...args);
+		}
+	}
+	get connectionCount() {
+		return this.connections.length;
+	}
+};
+//#endregion
+//#region src/core/behavior.ts
+/**
+* Vibe-coded logic attached to a JSON-declared node — the ONE script a node
+* may carry (`"script": {"name": "PlayerController", "props": {...}}`).
+*
+* Lifecycle hooks run AFTER the node's own. Props follow the same
+* schema/defaults/delta model as node props.
+*/
+var Behavior = class {
+	static props;
+	/**
+	* Custom signals this behavior emits via `this.emit(...)` — declared onto
+	* its node at load. Undeclared emits are hard errors (typo safety).
+	*/
+	static signals;
+	/** The node this behavior is attached to (assigned by the loader). */
+	node;
+	/** The running engine, reached through the scene tree. */
+	get engine() {
+		const engine = this.node?.tree?.engine;
+		if (!engine) throw new IncantoError("TREE_VIOLATION", `Behavior on '${this.node?.name ?? "?"}' is not attached to a running engine (node must be in a scene set on an Engine).`);
+		return engine;
+	}
+	/** Shortcut for `this.engine.input`. */
+	get input() {
+		return this.engine.input;
+	}
+	/** Seeded engine randomness — use this, not Math.random(), for replayability. */
+	get rng() {
+		return this.engine.rng;
+	}
+	/** The engine log channel (visible in the debug overlay and test harness). */
+	get log() {
+		return this.engine.log;
+	}
+	getNode(path) {
+		return this.node.getNode(path);
+	}
+	emit(signal, ...args) {
+		this.node.emit(signal, ...args);
+	}
+	on(signal, fn, opts) {
+		return this.node.on(signal, fn, opts);
+	}
+};
+/**
+* @internal No-op stand-in attached when a scene's script names an
+* unregistered behavior under `stubMissingBehaviors` (validation/tool mode):
+* props skip validation, connection handlers resolve to nothing, emits are
+* harmless. Games never see this — the strict default still hard-fails.
+*/
+var StubBehavior = class extends Behavior {};
+const behaviors = /* @__PURE__ */ new Map();
+/** Whether a behavior name is registered (no throw). */
+function hasBehavior(name) {
+	return behaviors.has(name);
+}
+/** Explicit registration — never an import side effect (tree-shaking safety). */
+function registerBehavior(name, ctor, opts) {
+	const existing = behaviors.get(name);
+	if (existing && existing !== ctor && !opts?.replace) throw new IncantoError("DUPLICATE_BEHAVIOR", `Behavior '${name}' is already registered by a different class. Replacing an implementation (e.g. under hot reload) needs registerBehavior(name, ctor, { replace: true }).`);
+	behaviors.set(name, ctor);
+}
+function getBehavior(name) {
+	const ctor = behaviors.get(name);
+	if (!ctor) {
+		const registered = [...behaviors.keys()];
+		throw new IncantoError("UNKNOWN_BEHAVIOR", `Unknown behavior '${name}'. Registered behaviors: [${registered.join(", ")}]. Did you forget registerBehavior('${name}', ${name})?`, { validOptions: registered });
+	}
+	return ctor;
+}
+function registeredBehaviors() {
+	return [...behaviors.keys()];
+}
+/** Test isolation helper. */
+function clearBehaviors() {
+	behaviors.clear();
+}
+/** @internal Instantiate + validate props (used by the scene loader). */
+function createBehavior(name, props) {
+	const ctor = getBehavior(name);
+	const behavior = new ctor();
+	applySchemaProps(behavior, mergeStaticProps(ctor), props, `script:${name}`);
+	return behavior;
+}
+//#endregion
+//#region src/core/node-path.ts
+function parseNodePath(path) {
+	if (path === "") throw new IncantoError("BAD_NODE_PATH", "Node path must not be empty.");
+	if (path.startsWith("%")) {
+		const name = path.slice(1);
+		if (name === "" || name.includes("/") || name.includes("%")) throw new IncantoError("BAD_NODE_PATH", `Invalid unique-name path '${path}'. Expected '%NodeName'.`);
+		return {
+			kind: "unique",
+			name
+		};
+	}
+	if (path === ".") return {
+		kind: "relative",
+		segments: []
+	};
+	const absolute = path.startsWith("/");
+	const body = absolute ? path.slice(1) : path;
+	if (body === "" || body.split("/").some((s) => s === "")) throw new IncantoError("BAD_NODE_PATH", `Invalid node path '${path}'. Segments must be non-empty (no leading/trailing/double '/').`);
+	const segments = body.split("/");
+	for (const seg of segments) {
+		if (seg.includes("%")) throw new IncantoError("BAD_NODE_PATH", `Invalid node path '${path}'. '%' is only allowed as a whole-path prefix ('%Name').`);
+		if (seg === ".") throw new IncantoError("BAD_NODE_PATH", `Invalid node path '${path}'. '.' is only valid as the whole path — drop the './' prefix.`);
+	}
+	if (absolute && segments.includes("..")) throw new IncantoError("BAD_NODE_PATH", `Invalid node path '${path}'. Absolute paths must not contain '..'.`);
+	return {
+		kind: absolute ? "absolute" : "relative",
+		segments
+	};
+}
+//#endregion
+//#region src/core/node.ts
+function validateName(name) {
+	if (name === "" || name.includes("/") || name.includes("%")) throw new IncantoError("TREE_VIOLATION", `Invalid node name '${name}'. Names must be non-empty and must not contain '/' or '%'.`);
+}
+/**
+* Base class of everything in an Incanto scene (Godot's Node model).
+*
+* Pure data + tree structure: no rendering, no DOM, no three.js — renderer
+* adapters subscribe from the outside.
+*/
+var Node = class {
+	static typeName = "Node";
+	_name;
+	_parent = null;
+	_children = [];
+	_groups = /* @__PURE__ */ new Set();
+	_signals = /* @__PURE__ */ new Map();
+	_declared = null;
+	_tree = null;
+	_ready = false;
+	/**
+	* Optional STABLE identifier (scene JSON `uid`) — unlike names (unique only
+	* among siblings) a uid is unique across the whole scene, so scripts and
+	* tools can address a node no matter where it moves.
+	*/
+	uid = null;
+	/** Free-form JSON identity for game logic (e.g. `{kind: 'ITEM', value: 10}`). */
+	tags = {};
+	/** Behavior attachment blob from scene JSON (resolved by the loader). */
+	script = null;
+	/** The resolved behavior instance (set by the loader from `script`). */
+	behavior = null;
+	/** Replication config blob from scene JSON (interpreted in M6; preserved until then). */
+	network = null;
+	constructor(name) {
+		const ctor = this.constructor;
+		this._name = name ?? ctor.typeName;
+		validateName(this._name);
+	}
+	get name() {
+		return this._name;
+	}
+	set name(value) {
+		validateName(value);
+		if (this._parent) this._name = uniqueSiblingName(value, this._parent._children, this);
+		else this._name = value;
+	}
+	get parent() {
+		return this._parent;
+	}
+	get children() {
+		return this._children;
+	}
+	get groups() {
+		return this._groups;
+	}
+	/** The SceneTree this node is attached to, or null while detached. */
+	get tree() {
+		return this._tree;
+	}
+	/** Whether onReady has run (it runs at most once per instance). */
+	get isReady() {
+		return this._ready;
+	}
+	addChild(child) {
+		if (child._parent !== null) throw new IncantoError("TREE_VIOLATION", `Cannot add '${child.name}': it already has parent '${child._parent.name}'. removeChild/reparent first.`);
+		for (let n = this; n; n = n._parent) if (n === child) throw new IncantoError("TREE_VIOLATION", `Cannot add '${child.name}' to '${this.name}': it is this node or an ancestor (cycle).`);
+		child._name = uniqueSiblingName(child._name, this._children, child);
+		child._parent = this;
+		this._children.push(child);
+		if (this._tree) {
+			child._propagateEnterTree(this._tree);
+			child._propagateReady();
+		}
+		return child;
+	}
+	removeChild(child) {
+		const i = this._children.indexOf(child);
+		if (i === -1) throw new IncantoError("TREE_VIOLATION", `'${child.name}' is not a child of '${this.name}'.`);
+		if (child._tree) child._propagateExitTree();
+		this._children.splice(i, 1);
+		child._parent = null;
+	}
+	reparent(newParent) {
+		this._parent?.removeChild(this);
+		newParent.addChild(this);
+	}
+	findChild(name, recursive = true) {
+		for (const c of this._children) if (c._name === name) return c;
+		if (recursive) for (const c of this._children) {
+			const found = c.findChild(name, true);
+			if (found) return found;
+		}
+		return null;
+	}
+	/** Topmost ancestor (the node itself when detached). */
+	getRoot() {
+		let n = this;
+		while (n._parent) n = n._parent;
+		return n;
+	}
+	/** Depth-first search of THIS subtree for the node carrying `uid`. */
+	getNodeByUid(uid) {
+		if (this.uid === uid) return this;
+		for (const child of this.children) {
+			const found = child.getNodeByUid(uid);
+			if (found) return found;
+		}
+		return null;
+	}
+	/** Every node in THIS subtree named `name` — names repeat, so a list. */
+	getNodesByName(name) {
+		const out = [];
+		const walk = (node) => {
+			if (node.name === name) out.push(node);
+			for (const child of node.children) walk(child);
+		};
+		walk(this);
+		return out;
+	}
+	getPath() {
+		const parts = [];
+		for (let n = this; n; n = n._parent) parts.unshift(n._name);
+		return `/${parts.join("/")}`;
+	}
+	getNode(path) {
+		const found = this.resolve(path);
+		if (found) return found;
+		throw new IncantoError("NODE_NOT_FOUND", `No node at '${path}' from '${this.getPath()}'. Children here: [${this._children.map((c) => c._name).join(", ")}].`);
+	}
+	getNodeOrNull(path) {
+		return this.resolve(path);
+	}
+	resolve(path) {
+		const parsed = parseNodePath(path);
+		if (parsed.kind === "unique") {
+			const matches = [];
+			collectByName(this.getRoot(), parsed.name, matches);
+			if (matches.length > 1) throw new IncantoError("DUPLICATE_UNIQUE_NAME", `'%${parsed.name}' is ambiguous: ${matches.length} nodes named '${parsed.name}' (${matches.map((m) => m.getPath()).join(", ")}).`);
+			return matches[0] ?? null;
+		}
+		let current;
+		let segments = parsed.segments;
+		if (parsed.kind === "absolute") {
+			const root = this.getRoot();
+			if (segments[0] !== root._name && segments[0] !== "root") return null;
+			current = root;
+			segments = segments.slice(1);
+		} else current = this;
+		for (const seg of segments) {
+			if (!current) return null;
+			if (seg === "..") {
+				current = current._parent;
+				continue;
+			}
+			current = current._children.find((c) => c._name === seg) ?? null;
+		}
+		return current;
+	}
+	addToGroup(group) {
+		this._groups.add(group);
+	}
+	removeFromGroup(group) {
+		this._groups.delete(group);
+	}
+	isInGroup(group) {
+		return this._groups.has(group);
+	}
+	declaredSignals() {
+		if (!this._declared) {
+			this._declared = /* @__PURE__ */ new Set();
+			let ctor = this.constructor;
+			while (typeof ctor === "function") {
+				const own = ctor;
+				if (Object.hasOwn(ctor, "signals") && own.signals) for (const s of own.signals) this._declared.add(s);
+				ctor = Object.getPrototypeOf(ctor);
+			}
+		}
+		return this._declared;
+	}
+	/** Declare an ad-hoc signal on THIS instance (static `signals` covers types). */
+	declareSignal(name) {
+		this.declaredSignals().add(name);
+	}
+	/** Every signal this instance may emit (static + behavior + ad-hoc). */
+	declaredSignalNames() {
+		return [...this.declaredSignals()];
+	}
+	assertDeclared(name) {
+		if (this.declaredSignals().has(name)) return;
+		const ctor = this.constructor;
+		const declared = [...this.declaredSignals()];
+		throw new IncantoError("UNKNOWN_SIGNAL", `Unknown signal '${name}' on '${this.getPath()}' (${ctor.typeName}). Declared signals: [${declared.join(", ")}]. Declare it with "static signals = ['${name}']" on the node class or its behavior, or call node.declareSignal('${name}').`, {
+			signal: name,
+			path: this.getPath(),
+			nodeType: ctor.typeName,
+			validOptions: declared
+		});
+	}
+	/** Get the named DECLARED signal (creating its Signal object on demand). */
+	signal(name) {
+		this.assertDeclared(name);
+		let sig = this._signals.get(name);
+		if (!sig) {
+			sig = new Signal();
+			this._signals.set(name, sig);
+		}
+		return sig;
+	}
+	on(signal, fn, opts) {
+		return this.signal(signal).connect(fn, opts);
+	}
+	off(signal, fn) {
+		this._signals.get(signal)?.disconnect(fn);
+	}
+	emit(signal, ...args) {
+		this.assertDeclared(signal);
+		this._signals.get(signal)?.emit(...args);
+	}
+	/**
+	* Defer destruction to the end of the current update pass (flushed by the
+	* SceneTree). Frees immediately when detached from any tree.
+	*/
+	queueFree() {
+		if (this._tree) this._tree._queueFree(this);
+		else this.free();
+	}
+	/** Immediately detach and tear down this node and its children. */
+	free() {
+		const tree = this._tree;
+		for (const child of [...this._children]) child.free();
+		this._parent?.removeChild(this);
+		if (this._tree) this._propagateExitTree();
+		tree?._detachRoot(this);
+		for (const sig of this._signals.values()) sig.disconnectAll();
+		this._signals.clear();
+	}
+	/** @internal */
+	_propagateEnterTree(tree) {
+		this._tree = tree;
+		this.onEnterTree();
+		this.behavior?.onEnterTree?.();
+		for (const c of [...this._children]) if (c._tree !== tree) c._propagateEnterTree(tree);
+	}
+	/** @internal */
+	_propagateReady() {
+		for (const c of [...this._children]) if (c._tree) c._propagateReady();
+		if (!this._ready) {
+			this._ready = true;
+			this.onReady();
+			this.behavior?.onReady?.();
+		}
+	}
+	/** @internal */
+	_propagateExitTree() {
+		for (const c of [...this._children]) c._propagateExitTree();
+		this.onExitTree();
+		this.behavior?.onExitTree?.();
+		this._tree = null;
+	}
+	/** @internal */
+	_propagateUpdate(dt) {
+		this.update(dt);
+		this.behavior?.update?.(dt);
+		const kids = this._children;
+		for (let i = 0, n = kids.length; i < n; i++) kids[i]?._propagateUpdate(dt);
+	}
+	/** @internal */
+	_propagateFixedUpdate(dt) {
+		this.fixedUpdate(dt);
+		this.behavior?.fixedUpdate?.(dt);
+		const kids = this._children;
+		for (let i = 0, n = kids.length; i < n; i++) kids[i]?._propagateFixedUpdate(dt);
+	}
+	onEnterTree() {}
+	onReady() {}
+	onExitTree() {}
+	update(_dt) {}
+	fixedUpdate(_dt) {}
+};
+function collectByName(node, name, out) {
+	if (node.name === name) out.push(node);
+	for (const c of node.children) collectByName(c, name, out);
+}
+/**
+* Deterministic sibling auto-rename: keep the requested name when free,
+* otherwise increment its trailing number ('Enemy' → 'Enemy2', 'Enemy2' → 'Enemy3').
+*/
+function uniqueSiblingName(requested, siblings, self) {
+	const taken = new Set(siblings.filter((s) => s !== self).map((s) => s.name));
+	if (!taken.has(requested)) return requested;
+	const m = requested.match(/^(.*?)(\d+)$/);
+	const stem = m ? m[1] : requested;
+	let counter = m ? Number(m[2]) + 1 : 2;
+	while (taken.has(`${stem}${counter}`)) counter += 1;
+	return `${stem}${counter}`;
+}
+//#endregion
+//#region src/core/scene/constants.ts
+/**
+* Named scene CONSTANTS — a scene-level table of reusable typed values
+* (`scene.constants`) that node props may reference instead of hard-coding a
+* literal. A prop value of `{"@const": "NAME"}` is replaced, AT LOAD, with the
+* constant's literal value before the node is built — so nodes never see a
+* reference, only the resolved value (mirrors how assets stay simple, but
+* resolved eagerly because a prop's value must match its declared type).
+*
+* Authoring tools keep the `{"@const": …}` reference in their own JSON; only the
+* runtime resolves it. Constant values are FINAL literals — a constant must not
+* reference another constant (keep the table flat).
+*
+* Pure + three-free; lives in core so the loader and any tool can share it.
+*/
+/** The single reserved key marking a prop value as a constant reference. */
+const CONST_REF_KEY = "@const";
+/** A `{"@const": "NAME"}` reference — exactly that one string key, nothing else. */
+function isConstRef(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const keys = Object.keys(value);
+	return keys.length === 1 && keys[0] === "@const" && typeof value["@const"] === "string";
+}
+/**
+* Deep-resolve every `{"@const": "NAME"}` reference in `value` to its literal
+* from `constants` (cloned, so the table is never aliased into node state).
+* Unknown names hard-fail — agents self-correct on hard errors.
+*/
+function resolveConstants(value, constants) {
+	if (value === void 0 || value === null) return value;
+	if (isConstRef(value)) {
+		const name = value[CONST_REF_KEY];
+		if (!constants || !(name in constants)) {
+			const declared = constants ? Object.keys(constants) : [];
+			throw new IncantoError("UNKNOWN_CONSTANT", `Unknown constant '@const: ${name}'. Declared constants: ${declared.length ? declared.join(", ") : "(none — add a \"constants\" section)"}.`);
+		}
+		return jsonClone(constants[name]);
+	}
+	if (Array.isArray(value)) return value.map((item) => resolveConstants(item, constants));
+	if (typeof value === "object") {
+		const out = {};
+		for (const [k, v] of Object.entries(value)) out[k] = resolveConstants(v, constants);
+		return out;
+	}
+	return value;
+}
+//#endregion
+//#region src/core/scene-tree.ts
+/**
+* Owns a node tree and drives its lifecycle:
+*
+* - `setRoot` → onEnterTree parent-first, then onReady children-first (once per instance)
+* - `update`/`fixedUpdate` → parent-first traversal, then flush of queued frees
+* - group queries across attached nodes
+*
+* Headless by design — tests step it manually; the render loop (M2) calls it.
+*/
+var SceneTree = class {
+	_root = null;
+	_engine = null;
+	freeQueue = /* @__PURE__ */ new Set();
+	_frameId = 0;
+	/**
+	* Monotonic update-frame counter — bumped once per `update()`. Per-frame
+	* caches (e.g. the 3d grass-bender body gather) key off this so they rebuild
+	* at most once a frame regardless of node visitation order.
+	*/
+	get frameId() {
+		return this._frameId;
+	}
+	/**
+	* @internal Opaque per-frame scratch the 3d layer parks its shared moving-body
+	* snapshot on (kept here so it is per-tree-instance, never a module global —
+	* core stays three-free, the 3d resolver owns the shape).
+	*/
+	_frameScratch = null;
+	get root() {
+		return this._root;
+	}
+	/** The engine driving this tree (set by Engine.setScene), or null. */
+	get engine() {
+		return this._engine;
+	}
+	/** @internal */
+	_setEngine(engine) {
+		this._engine = engine;
+	}
+	setRoot(node) {
+		if (this._root) throw new IncantoError("TREE_VIOLATION", "SceneTree already has a root.");
+		if (node.parent) throw new IncantoError("TREE_VIOLATION", `Root must not have a parent ('${node.name}' is a child of '${node.parent.name}').`);
+		this._root = node;
+		node._propagateEnterTree(this);
+		node._propagateReady();
+	}
+	update(dt) {
+		this._frameId++;
+		this._root?._propagateUpdate(dt);
+		this.flushFreeQueue();
+	}
+	fixedUpdate(dt) {
+		this._root?._propagateFixedUpdate(dt);
+		this.flushFreeQueue();
+	}
+	getNodesInGroup(group) {
+		const out = [];
+		if (this._root) collectGroup(this._root, group, out);
+		return out;
+	}
+	/** Call `method(...args)` on every group member that implements it. */
+	callGroup(group, method, ...args) {
+		for (const node of this.getNodesInGroup(group)) {
+			const fn = node[method];
+			if (typeof fn === "function") fn.apply(node, args);
+		}
+	}
+	/** @internal */
+	_queueFree(node) {
+		this.freeQueue.add(node);
+	}
+	/** @internal Called by Node.free(): a freed root must not be re-drivable. */
+	_detachRoot(node) {
+		if (this._root === node) this._root = null;
+	}
+	flushFreeQueue() {
+		if (this.freeQueue.size === 0) return;
+		const items = [...this.freeQueue];
+		this.freeQueue.clear();
+		for (const node of items) node.free();
+	}
+};
+function collectGroup(node, group, out) {
+	if (node.isInGroup(group)) out.push(node);
+	for (const c of node.children) collectGroup(c, group, out);
+}
+//#endregion
+//#region src/core/viewport.ts
+const FITS = [
+	"expand",
+	"letterbox",
+	"integer"
+];
+/**
+* Parse + hard-validate a scene's `viewport` header. With a design resolution,
+* scene JSON owns layout again: the game is authored in fixed design pixels
+* and the renderer maps them onto whatever canvas size the page provides.
+*/
+function resolveViewport(viewport) {
+	if (viewport === void 0) return null;
+	const design = viewport.design;
+	if (!Array.isArray(design) || design.length !== 2 || typeof design[0] !== "number" || typeof design[1] !== "number" || design[0] <= 0 || design[1] <= 0) throw new IncantoError("BAD_FORMAT", `Scene "viewport.design" must be [width, height] with positive numbers, got ${JSON.stringify(design)}.`);
+	const fit = viewport.fit ?? "expand";
+	if (typeof fit !== "string" || !FITS.includes(fit)) throw new IncantoError("BAD_FORMAT", `Scene "viewport.fit" must be one of [${FITS.join(", ")}], got ${JSON.stringify(fit)}.`);
+	return {
+		design: [design[0], design[1]],
+		fit
+	};
+}
+/**
+* Pure viewport math (headless-testable):
+* - expand:    the design rect is always fully visible; extra world shows beyond it
+* - letterbox: EXACTLY the design rect, centered, bars elsewhere
+* - integer:   expand with whole-number scaling (pixel art), floored, min 1
+*/
+function computeViewport(canvasW, canvasH, viewport) {
+	const dw = viewport.design[0];
+	const dh = viewport.design[1];
+	const raw = Math.min(canvasW / dw, canvasH / dh);
+	const scale = viewport.fit === "integer" ? Math.max(1, Math.floor(raw)) : raw;
+	if (viewport.fit === "letterbox") {
+		const contentW = dw * scale;
+		const contentH = dh * scale;
+		return {
+			scale,
+			viewW: dw,
+			viewH: dh,
+			offsetX: (canvasW - contentW) / 2,
+			offsetY: (canvasH - contentH) / 2,
+			contentW,
+			contentH
+		};
+	}
+	return {
+		scale,
+		viewW: canvasW / scale,
+		viewH: canvasH / scale,
+		offsetX: 0,
+		offsetY: 0,
+		contentW: canvasW,
+		contentH: canvasH
+	};
+}
+//#endregion
+//#region src/core/scene/schema.ts
+/** Current scene file format version. Defaults are frozen per format version. */
+const SCENE_FORMAT = 1;
+//#endregion
+//#region src/core/scene/serializer.ts
+/**
+* Serialize a node subtree to scene JSON with delta-only props: values equal
+* to the type's schema defaults are omitted (Godot PackedScene behavior —
+* files stay tiny and AI-readable).
+*/
+function serializeNode(node) {
+	const ctor = node.constructor;
+	const json = {
+		name: node.name,
+		type: ctor.typeName
+	};
+	if (node.uid !== null) json.uid = node.uid;
+	if (node.groups.size > 0) json.groups = [...node.groups];
+	if (Object.keys(node.tags).length > 0) json.tags = jsonClone(node.tags);
+	const schema = getNodeSchema(ctor.typeName);
+	const props = {};
+	for (const [key, def] of Object.entries(schema)) {
+		const value = node[key];
+		if (value === void 0) continue;
+		assertJsonSafe(value, `${node.name}.${key}`);
+		if (!jsonEquals(value, def.default)) props[key] = jsonClone(value);
+	}
+	if (Object.keys(props).length > 0) json.props = props;
+	if (node.script) json.script = jsonClone(node.script);
+	if (node.network) json.network = jsonClone(node.network);
+	if (node.children.length > 0) json.children = node.children.map((c) => serializeNode(c));
+	return json;
+}
+/**
+* NaN/Infinity silently become `null` in JSON.stringify — corrupting saved
+* scenes. Fail loudly at serialize time instead.
+*/
+function assertJsonSafe(value, at) {
+	if (typeof value === "number" && !Number.isFinite(value)) throw new IncantoError("PROP_TYPE_MISMATCH", `Prop '${at}' is ${value} — scene props must be finite numbers (NaN/Infinity become null in JSON).`);
+	if (Array.isArray(value)) for (let i = 0; i < value.length; i++) assertJsonSafe(value[i], `${at}[${i}]`);
+	else if (value !== null && typeof value === "object") for (const [k, v] of Object.entries(value)) assertJsonSafe(v, `${at}.${k}`);
+}
+//#endregion
+//#region src/core/scene/scene.ts
+/**
+* A loaded, live scene: the node tree plus everything needed to round-trip
+* back to scene JSON (declared connections, asset/input/multiplayer blobs).
+*
+* JSON is the source of truth for STRUCTURE; imperative listeners added via
+* `node.on(...)` are code, not data, and intentionally do not serialize.
+*/
+var Scene = class {
+	name;
+	dimension;
+	root;
+	tree;
+	/** Scene-level rendering environment (read by renderer adapters). */
+	environment;
+	/** Asset declarations (consumed by renderer/asset layers, `$key` references). */
+	assets;
+	/** Named constant values (`{"@const": "NAME"}` prop references resolve to these). */
+	constants;
+	/** Input action declarations (loaded into `Engine.input` on setScene). */
+	input;
+	/** Physics config (gravity etc. — interpreted by the physics modules). */
+	physics;
+	/** Multiplayer config (room etc. — interpreted by incanto/net). */
+	multiplayer;
+	/** Design-resolution viewport (consumed by renderers via resolveViewport). */
+	viewport;
+	connections;
+	constructor(source, root, tree) {
+		this.name = source.name;
+		this.dimension = source.dimension;
+		this.root = root;
+		this.tree = tree;
+		this.assets = source.assets ? jsonClone(source.assets) : void 0;
+		this.constants = source.constants ? jsonClone(source.constants) : void 0;
+		this.input = source.input ? jsonClone(source.input) : void 0;
+		this.physics = source.physics ? jsonClone(source.physics) : void 0;
+		this.multiplayer = source.multiplayer ? jsonClone(source.multiplayer) : void 0;
+		this.environment = source.environment ? jsonClone(source.environment) : void 0;
+		this.viewport = source.viewport ? jsonClone(source.viewport) : void 0;
+		this.connections = source.connections ? jsonClone(source.connections) : [];
+	}
+	/** Lossless export. Note: expanded sub-scene instances serialize as full trees in M1. */
+	toJSON() {
+		return {
+			format: 1,
+			type: "scene",
+			name: this.name,
+			...this.dimension ? { dimension: this.dimension } : {},
+			...this.assets ? { assets: jsonClone(this.assets) } : {},
+			...this.constants ? { constants: jsonClone(this.constants) } : {},
+			...this.input ? { input: jsonClone(this.input) } : {},
+			...this.physics ? { physics: jsonClone(this.physics) } : {},
+			...this.multiplayer ? { multiplayer: jsonClone(this.multiplayer) } : {},
+			...this.environment ? { environment: jsonClone(this.environment) } : {},
+			...this.viewport ? { viewport: jsonClone(this.viewport) } : {},
+			root: serializeNode(this.root),
+			...this.connections.length > 0 ? { connections: jsonClone(this.connections) } : {}
+		};
+	}
+};
+//#endregion
+//#region src/core/scene/loader.ts
+/**
+* Build a live Scene from scene JSON.
+*
+* Takes `unknown` on purpose: the loader hard-validates everything at runtime,
+* so consumers can pass an imported JSON module without TypeScript casts.
+*
+* Order: validate header → instantiate nodes top-down → attach to a SceneTree
+* (enterTree/ready fire) → wire connections LAST. Every failure is a hard
+* IncantoError naming valid alternatives — agents self-correct on hard errors.
+*/
+function loadScene(json, opts) {
+	if (typeof json !== "object" || json === null) throw new IncantoError("BAD_FORMAT", `Scene JSON must be an object, got ${json === null ? "null" : typeof json}.`);
+	const sceneJson = json;
+	validateHeader(sceneJson);
+	const root = buildNode(sceneJson.root, opts, [], "", sceneJson.constants);
+	validateUniqueUids(root);
+	const tree = new SceneTree();
+	if (opts?.engine) tree._setEngine(opts.engine);
+	tree.setRoot(root);
+	wireConnections(root, sceneJson.connections ?? [], opts?.declareConnectionSignals);
+	return new Scene(sceneJson, root, tree);
+}
+/** @internal Rebuild a detached node subtree from node JSON (used by duplicateNode).
+* The source comes from a live node's serialized props, which are already resolved
+* literals — no constants table needed. */
+function buildNodeJson(json, opts) {
+	return buildNode(json, opts, [], "", void 0);
+}
+function validateHeader(json) {
+	if (json.format !== 1) throw new IncantoError("BAD_FORMAT", `Unsupported scene format ${JSON.stringify(json.format)}; this engine reads format 1.`);
+	if (json.type !== "scene") throw new IncantoError("BAD_FORMAT", `Expected "type": "scene", got ${JSON.stringify(json.type)}.`);
+	if (typeof json.name !== "string" || json.name === "") throw new IncantoError("BAD_FORMAT", "Scene \"name\" must be a non-empty string.");
+	if (json.dimension !== void 0 && json.dimension !== "2d" && json.dimension !== "3d") throw new IncantoError("BAD_FORMAT", `Scene "dimension" must be "2d" or "3d", got ${JSON.stringify(json.dimension)}.`);
+	if (typeof json.root !== "object" || json.root === null) throw new IncantoError("BAD_FORMAT", "Scene \"root\" must be a node object.");
+	resolveViewport(json.viewport);
+}
+/**
+* Re-raise a node-build error with the node's absolute scene path attached —
+* "Unknown prop 'x' on 'Sprite2D'" alone cannot locate the node among forty
+* Sprite2Ds; "(at '/Level/Enemies/Slime3')" can. Inner (deeper) contexts win.
+*/
+function withNodeContext(e, path, nj) {
+	if (e instanceof IncantoError && !e.details.path) return new IncantoError(e.code, `${e.message} (at '${path}')`, {
+		...e.details,
+		path,
+		...typeof nj.uid === "string" && nj.uid !== "" ? { uid: nj.uid } : {},
+		...e.details.nodeType === void 0 && nj.type ? { nodeType: nj.type } : {}
+	});
+	return e;
+}
+function buildNode(nj, opts, stack, parentPath, constants) {
+	const path = `${parentPath}/${nj.name}`;
+	try {
+		if (nj.instance !== void 0 && nj.type !== void 0) throw new IncantoError("BAD_FORMAT", `Node '${nj.name}' declares both "type" and "instance" — they are mutually exclusive.`);
+		if (nj.instance !== void 0) return buildInstance(nj, opts, stack, path, constants);
+		if (nj.type === void 0) throw new IncantoError("BAD_FORMAT", `Node '${nj.name}' must declare either "type" or "instance".`);
+		const node = createNode(nj.type, resolveConstants(nj.props, constants));
+		applyCommon(node, nj, opts);
+		node.constructor.validateJson?.(node);
+		for (const childJson of nj.children ?? []) node.addChild(buildNode(childJson, opts, stack, path, constants));
+		return node;
+	} catch (e) {
+		throw withNodeContext(e, path, nj);
+	}
+}
+function buildInstance(nj, opts, stack, path, constants) {
+	const instancePath = nj.instance;
+	if (!opts?.resolveScene) throw new IncantoError("UNRESOLVED_INSTANCE", `Node '${nj.name}' references instance '${instancePath}' but no resolveScene option was provided.`);
+	if (stack.includes(instancePath)) throw new IncantoError("UNRESOLVED_INSTANCE", `Instance cycle detected: ${[...stack, instancePath].join(" → ")}.`);
+	const sub = opts.resolveScene(instancePath);
+	if (!sub) throw new IncantoError("UNRESOLVED_INSTANCE", `resolveScene returned nothing for instance '${instancePath}' (node '${nj.name}').`);
+	validateHeader(sub);
+	const overrides = resolveConstants(nj.overrides ?? {}, constants);
+	const node = buildNode({
+		...sub.root,
+		name: nj.name,
+		props: deepMerge(sub.root.props ?? {}, overrides)
+	}, opts, [...stack, instancePath], parentOf(path), sub.constants);
+	applyCommon(node, {
+		...nj,
+		type: void 0,
+		props: void 0
+	}, opts);
+	for (const childJson of nj.children ?? []) node.addChild(buildNode(childJson, opts, stack, path, constants));
+	wireConnections(node, sub.connections ?? [], opts?.declareConnectionSignals);
+	return node;
+}
+function parentOf(path) {
+	const i = path.lastIndexOf("/");
+	return i <= 0 ? "" : path.slice(0, i);
+}
+function applyCommon(node, nj, opts) {
+	if (typeof nj.uid === "string" && nj.uid !== "") node.uid = nj.uid;
+	node.name = nj.name;
+	for (const g of nj.groups ?? []) node.addToGroup(g);
+	if (nj.tags) node.tags = jsonClone(nj.tags);
+	if (nj.script) {
+		node.script = jsonClone(nj.script);
+		const name = nj.script.name;
+		if (typeof name !== "string" || name === "") throw new IncantoError("BAD_FORMAT", `Node '${nj.name}': "script" needs a non-empty "name" (a registered behavior).`);
+		const behavior = opts?.stubMissingBehaviors && !hasBehavior(name) ? new class extends StubBehavior {}() : createBehavior(name, nj.script.props);
+		behavior.node = node;
+		node.behavior = behavior;
+		for (const s of mergeStaticSignals(behavior.constructor)) node.declareSignal(s);
+	}
+	if (nj.network) node.network = jsonClone(nj.network);
+}
+function deepMerge(base, override) {
+	const out = { ...base };
+	for (const [key, value] of Object.entries(override)) {
+		const prev = out[key];
+		if (prev !== null && value !== null && typeof prev === "object" && typeof value === "object" && !Array.isArray(prev) && !Array.isArray(value)) out[key] = deepMerge(prev, value);
+		else out[key] = value;
+	}
+	return out;
+}
+function wireConnections(root, connections, declareSignals = false) {
+	for (const conn of connections) {
+		const fromNode = resolveEndpoint(root, conn.from, conn, "from");
+		if (declareSignals || fromNode.behavior instanceof StubBehavior) fromNode.declareSignal(conn.signal);
+		const toNode = resolveEndpoint(root, conn.to, conn, "to");
+		const nodeFn = toNode[conn.handler];
+		const behaviorFn = toNode.behavior ? toNode.behavior[conn.handler] : void 0;
+		if (typeof nodeFn !== "function" && typeof behaviorFn !== "function" && !(toNode.behavior instanceof StubBehavior)) throw new IncantoError("UNKNOWN_HANDLER", `Connection '${conn.signal}' → '${conn.to}' names handler '${conn.handler}', but '${toNode.name}' has no such method` + (toNode.behavior ? ` (nor does its behavior '${toNode.script?.name}')` : "") + `.`);
+		const listener = (...args) => {
+			if (conn.filter && !matchesFilter(args[0], conn.filter)) return;
+			if (conn.once) fromNode.off(conn.signal, listener);
+			const fn = toNode[conn.handler];
+			if (typeof fn === "function") {
+				fn.apply(toNode, args);
+				return;
+			}
+			const bfn = toNode.behavior ? toNode.behavior[conn.handler] : void 0;
+			if (typeof bfn === "function") bfn.apply(toNode.behavior, args);
+		};
+		try {
+			fromNode.on(conn.signal, listener);
+		} catch (e) {
+			if (e instanceof IncantoError && e.code === "UNKNOWN_SIGNAL") throw new IncantoError("UNKNOWN_SIGNAL", `Connection from '${conn.from}': ${e.message}`, e.details);
+			throw e;
+		}
+	}
+}
+function resolveEndpoint(root, path, conn, side) {
+	try {
+		return root.getNode(path);
+	} catch (e) {
+		if (e instanceof IncantoError) throw new IncantoError("DANGLING_CONNECTION", `Connection '${conn.signal}' has a dangling '${side}' path '${path}': ${e.message}`);
+		throw e;
+	}
+}
+function matchesFilter(arg, filter) {
+	if (!(arg instanceof Node)) return false;
+	if (filter.group && !arg.isInGroup(filter.group)) return false;
+	if (filter.tag) {
+		for (const [key, value] of Object.entries(filter.tag)) if (JSON.stringify(arg.tags[key]) !== JSON.stringify(value)) return false;
+	}
+	return true;
+}
+function validateUniqueUids(root) {
+	const seen = /* @__PURE__ */ new Map();
+	const walk = (node) => {
+		if (node.uid !== null) {
+			const other = seen.get(node.uid);
+			if (other) throw new IncantoError("DUPLICATE_UID", `duplicate uid '${node.uid}' on ${other.getPath()} and ${node.getPath()} — uids must be unique across the scene.`);
+			seen.set(node.uid, node);
+		}
+		for (const child of node.children) walk(child);
+	};
+	walk(root);
+}
+//#endregion
+export { registerBehavior as _, SCENE_FORMAT as a, SceneTree as c, resolveConstants as d, Node as f, getBehavior as g, clearBehaviors as h, serializeNode as i, CONST_REF_KEY as l, Behavior as m, loadScene as n, computeViewport as o, parseNodePath as p, Scene as r, resolveViewport as s, buildNodeJson as t, isConstRef as u, registeredBehaviors as v, Signal as y };