incanto 0.60.0 → 0.61.0

package/dist/{loader-D8n7TU8W.js → loader-D7jTvDQv.js}

@@ -1,7 +1,7 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { n as jsonEquals, t as jsonClone } from "./json-CwwhxQgb.js";
-import { c as mergeStaticSignals, i as getNodeSchema, r as createNode, s as mergeStaticProps, t as applySchemaProps } from "./registry-WWcQcfMr.js";
+import { c as mergeStaticSignals, i as getNodeSchema, o as getNodeType, r as createNode, s as mergeStaticProps, t as applySchemaProps } from "./registry-CF70EArN.js";
 //#region src/core/signal.ts
 var Signal = class {
 	connections = [];
@@ -166,6 +166,196 @@ function parseNodePath(path) {
 	};
 }
 //#endregion
+//#region src/core/node-refs.ts
+/**
+* Node-path PROPS, resolved against scene JSON.
+*
+* `Chase.target`, `Camera2D.follow`, `Spawner.prefab`, `Joint3D.target`,
+* `CharacterController3D.skinPath`, `Foliage3D.terrain` … each holds a path to
+* another node, and nothing checked any of them. A connection whose end does not
+* resolve is a hard `DANGLING_CONNECTION` at load; a PROP that does not resolve
+* is nothing at all — `getNodeOrNull` returns null, the scene loads, the enemy
+* never chases, and no error is ever printed.
+*
+* That makes it exactly the class `auditScene` exists for: loads fine, plays
+* wrong. The editor uses the same resolver so the two cannot drift.
+*
+* The grammar comes from `parseNodePath` — the loader's own parser — so a path
+* this module accepts is one the engine accepts.
+*/
+function nodeAt(root, path) {
+	let node = root;
+	for (const index of path) {
+		node = node?.children?.[index];
+		if (!node) return null;
+	}
+	return node ?? null;
+}
+function byName(root, name) {
+	const found = [];
+	const walk = (node, at) => {
+		if (node.name === name) found.push(at);
+		(node.children ?? []).forEach((child, i) => {
+			walk(child, [...at, i]);
+		});
+	};
+	walk(root, []);
+	return found;
+}
+/**
+* Resolve `value` from the node at `owner`, the way the engine would.
+*
+* Note the asymmetry with connections, whose paths resolve from the SCENE ROOT:
+* a prop's path resolves from the node holding it, which is why `'../Skin'` is
+* the documented default of `CharacterController3D.skinPath` and would mean
+* nothing in a connection.
+*/
+function resolveRefInJson(root, owner, value) {
+	if (!root) return {
+		ok: false,
+		problem: {
+			kind: "noMatch",
+			name: value
+		}
+	};
+	let parsed;
+	try {
+		parsed = parseNodePath(value);
+	} catch (error) {
+		return {
+			ok: false,
+			problem: {
+				kind: "grammar",
+				message: error instanceof Error ? error.message : String(error)
+			}
+		};
+	}
+	if (parsed.kind === "unique") {
+		const found = byName(root, parsed.name);
+		if (found.length === 1) return {
+			ok: true,
+			path: found[0]
+		};
+		if (found.length === 0) return {
+			ok: false,
+			problem: {
+				kind: "noMatch",
+				name: parsed.name
+			}
+		};
+		return {
+			ok: false,
+			problem: {
+				kind: "ambiguous",
+				name: parsed.name,
+				count: found.length
+			}
+		};
+	}
+	let at;
+	let segments = parsed.segments;
+	if (parsed.kind === "absolute") {
+		const first = segments[0] ?? "";
+		if (first !== root.name && first !== "root") return {
+			ok: false,
+			problem: {
+				kind: "wrongRoot",
+				first,
+				root: String(root.name ?? "")
+			}
+		};
+		at = [];
+		segments = segments.slice(1);
+	} else at = [...owner];
+	for (const segment of segments) {
+		if (segment === "..") {
+			if (at.length === 0) return {
+				ok: false,
+				problem: { kind: "aboveRoot" }
+			};
+			at.pop();
+			continue;
+		}
+		const here = nodeAt(root, at);
+		const index = (here?.children ?? []).findIndex((child) => child.name === segment);
+		if (index < 0) return {
+			ok: false,
+			problem: {
+				kind: "noChild",
+				parent: String(here?.name ?? "?"),
+				segment
+			}
+		};
+		at.push(index);
+	}
+	return {
+		ok: true,
+		path: at
+	};
+}
+/** The problem in English, for `incanto-check` and as the editor's base text. */
+function describeRefProblem(problem, value) {
+	switch (problem.kind) {
+		case "grammar": return problem.message;
+		case "noMatch": return `'%${problem.name}' matches no node in this scene.`;
+		case "ambiguous": return `'%${problem.name}' matches ${problem.count} nodes — a %name must be unique.`;
+		case "wrongRoot": return `'${value}' starts at '${problem.first}', but the scene root is '${problem.root}' (or write '/root/…').`;
+		case "noChild": return `'${value}' leads nowhere — '${problem.parent}' has no child named '${problem.segment}'.`;
+		case "aboveRoot": return `'${value}' walks above the scene root.`;
+	}
+}
+/** Every prop on this node declared `nodePath: true`, per bag. */
+function refProps(node) {
+	const collect = (schema) => Object.entries(schema).filter(([, def]) => def?.nodePath).map(([key]) => key);
+	let props = [];
+	if (node.type) try {
+		props = collect(getNodeSchema(node.type));
+	} catch {}
+	const name = node.script?.name;
+	return {
+		props,
+		script: name ? collect(behaviorSchema(name)) : []
+	};
+}
+/**
+* Scene lints for node-path props that point at nothing.
+*
+* An EMPTY value is not reported: `''` is the default of most of these props and
+* means "not set", which is a choice rather than a typo.
+*/
+function nodeRefWarnings(scene) {
+	const root = scene.root;
+	if (!root) return [];
+	const warnings = [];
+	const walk = (node, at, path) => {
+		const keys = refProps(node);
+		const bags = [[
+			node.props,
+			keys.props,
+			""
+		], [
+			node.script?.props,
+			keys.script,
+			`${node.script?.name ?? "script"}.`
+		]];
+		for (const [bag, propKeys, prefix] of bags) {
+			if (!bag) continue;
+			for (const key of propKeys) {
+				const value = bag[key];
+				if (typeof value !== "string" || value === "") continue;
+				const result = resolveRefInJson(root, at, value);
+				if (result.ok) continue;
+				warnings.push(`${path}: ${prefix}${key} — ${describeRefProblem(result.problem, value)} The scene loads and the prop does nothing.`);
+			}
+		}
+		(node.children ?? []).forEach((child, i) => {
+			walk(child, [...at, i], `${path}/${child.name ?? "?"}`);
+		});
+	};
+	walk(root, [], String(root.name ?? "root"));
+	return warnings;
+}
+//#endregion
 //#region src/core/diagnostics.ts
 function diagnose(engine, level, ...parts) {
 	engine?.log[level](...parts);
@@ -559,6 +749,112 @@ function uniqueSiblingName(requested, siblings, self) {
 	return `${stem}${counter}`;
 }
 //#endregion
+//#region src/core/scene/handler-collision.ts
+/**
+* A handler name that means two different things, resolved silently.
+*
+* `wireConnections` looks the handler up on the node FIRST and on the behavior
+* second — "Node methods win", which is right when only one of them has it and
+* a coin flip when both do. A node carries 62 public methods before any adapter
+* registers more (`stop`, `play`, `show`, `clear`, `say`, `advance`, `focus`,
+* `next`, `resolve`, `start`, `free`…), and every one of those is a name an
+* author would give a handler.
+*
+* Measured — an `Enemy` script on an `AnimatedSprite2D` with a `stop()` that
+* means "stop chasing", wired from a trigger:
+*
+* ```
+* loaded with NO error
+* behavior.chasing after the signal = true
+* ```
+*
+* `AnimatedSprite2D.stop()` ran instead: the enemy froze mid-animation and kept
+* coming. The wire fired, the handler existed, and the wrong one was called.
+*
+* Only methods the author WROTE count. Every behavior inherits `update`,
+* `onReady` and friends from the base class, and those collide with the node's
+* by construction — flagging them would be a false alarm on a name nobody would
+* wire a signal to anyway.
+*/
+function ambiguousHandler(node, handler) {
+	const behavior = node.behavior;
+	if (!behavior) return false;
+	if (typeof node[handler] !== "function") return false;
+	return declaredOnSubclass(behavior, handler);
+}
+/** Is `name` a method this behavior's own class defines, not one it inherits? */
+function declaredOnSubclass(behavior, name) {
+	let proto = Object.getPrototypeOf(behavior);
+	while (proto && proto !== Behavior.prototype) {
+		const own = Object.getOwnPropertyDescriptor(proto, name);
+		if (own && typeof own.value === "function") return true;
+		proto = Object.getPrototypeOf(proto);
+	}
+	return false;
+}
+/** The error `wireConnections` throws when a handler names both. */
+function ambiguousHandlerError(node, handler, script, to) {
+	return new IncantoError("AMBIGUOUS_HANDLER", `Connection → '${to}' names handler '${handler}', which is BOTH a method of '${node.constructor.typeName}' and one your behavior '${typeof script === "string" ? script : "?"}' defines. The node's wins, so the behavior's '${handler}' would never run and nothing would say so. Rename the behavior's method (or drop it, if the node's is the one you meant).`, {
+		path: node.getPath(),
+		nodeType: node.constructor.typeName,
+		uid: node.uid ?? void 0
+	});
+}
+/**
+* The same collision, as far as a scene FILE can see it.
+*
+* The load-time error needs the real behavior class, which only the game has —
+* `incanto check` loads scripts as stubs and cannot know what methods they
+* declare. But it CAN see that the handler is a method of the node's own type
+* and that the node carries a script, and that pair is the whole hazard: if the
+* script also defines that name, the node's wins and the script's never runs.
+*
+* Deliberately conditional on the script. `"handler": "play"` on a scriptless
+* `AudioPlayer` is the intended wiring and appears 53 times in the shipped
+* corpus; the pair this warns about appears zero times.
+*/
+function handlerShadowWarnings(scene) {
+	const root = scene.root;
+	if (!root) return [];
+	const out = [];
+	for (const raw of scene.connections ?? []) {
+		const conn = raw;
+		if (!conn || typeof conn.to !== "string" || typeof conn.handler !== "string") continue;
+		const found = resolveRefInJson(root, [], conn.to);
+		if (!found.ok) continue;
+		let node = root;
+		for (const i of found.path) node = node?.children?.[i];
+		const script = node?.script?.name;
+		if (!node?.type || !script) continue;
+		if (!nodeTypeMethods(node.type).has(conn.handler)) continue;
+		out.push(`${conn.to}: handler '${conn.handler}' is a method of ${node.type} itself, and this node also runs the script '${script}'. The node's method WINS — if '${script}' defines '${conn.handler}' too, that one never runs and nothing says so.`);
+	}
+	return out;
+}
+/** Every public method a registered node type answers to, including inherited. */
+function nodeTypeMethods(type) {
+	const cached = methodCache.get(type);
+	if (cached) return cached;
+	const out = /* @__PURE__ */ new Set();
+	let proto;
+	try {
+		proto = getNodeType(type).prototype;
+	} catch {
+		methodCache.set(type, out);
+		return out;
+	}
+	while (proto && proto !== Object.prototype) {
+		for (const key of Object.getOwnPropertyNames(proto)) {
+			if (key.startsWith("_") || key === "constructor") continue;
+			if (typeof Object.getOwnPropertyDescriptor(proto, key)?.value === "function") out.add(key);
+		}
+		proto = Object.getPrototypeOf(proto);
+	}
+	methodCache.set(type, out);
+	return out;
+}
+const methodCache = /* @__PURE__ */ new Map();
+//#endregion
 //#region src/core/input.ts
 /** Keys typed into editable elements belong to the page UI, not the game. */
 function isEditableTarget(target) {
@@ -1729,6 +2025,484 @@ function computeViewport(canvasW, canvasH, viewport) {
 	};
 }
 //#endregion
+//#region src/core/scene/asset-refs.ts
+/**
+* Hard-check every `$assetKey` a scene names, at LOAD.
+*
+* The check already existed and nothing routed to it at author time:
+* `AssetStore2D.resolve` throws `UNKNOWN_ASSET` for an undeclared key AND for a
+* value that is not a `$ref`, and it runs inside the renderer, in a browser,
+* when the texture is first needed. Headless the scene loaded clean.
+*
+* Measured before this existed, on a scene with four sprites — one good, one
+* with a typo'd key, one with a raw URL, one with a bare word:
+*
+* ```
+* ok  g.scene.json
+*     warn: $hero → /hero.png is not in the project …
+* 1/1 scene(s) valid
+* ```
+*
+* The only one it mentioned is the one that IS declared. The other three draw
+* nothing, and `incanto-assets.md` promises that a raw URL here "hard-fails".
+*/
+/** The `assets{}` entry types a prop may point at, and what to call them. */
+const KIND_LABEL = {
+	texture: "an image",
+	spritesheet: "a spritesheet (with frameWidth/frameHeight)",
+	model: "a GLB/glTF/VRM model",
+	animation: "a GLB's animation clips"
+};
+/**
+* Throws `UNKNOWN_ASSET` for any asset prop this node cannot resolve.
+*
+* @param props the node's own prop values
+* @param schema the merged prop schema for its type
+* @param assets the scene's `assets{}` block
+* @param nodeName for the message — a scene has many nodes
+*/
+function validateAssetRefs(props, schema, assets, nodeName) {
+	for (const [key, def] of Object.entries(schema)) {
+		const spec = def.asset;
+		if (!spec) continue;
+		const value = props[key];
+		if (typeof value !== "string" || value === "") continue;
+		if (!value.startsWith("$")) {
+			if (!spec.refOnly) continue;
+			throw new IncantoError("UNKNOWN_ASSET", `'${nodeName}.${key}' takes a "$assetKey" reference, not ${/^[a-z][a-z0-9+.-]*:/i.test(value) || value.startsWith("//") ? "a URL" : `'${value}'`}. Declare the asset — "assets": { "${suggestKey(value)}": { "type": "${spec.kind}", "url": "…" } } — and point the prop at "$${suggestKey(value)}".`, { prop: key });
+		}
+		const name = value.slice(1);
+		const entry = assets?.[name];
+		if (!entry) {
+			const declared = Object.keys(assets ?? {});
+			throw new IncantoError("UNKNOWN_ASSET", `'${nodeName}.${key}' names asset '${value}', which the scene does not declare. ` + (declared.length > 0 ? `Declared: [${declared.join(", ")}].` : "The scene has no \"assets\" block."), {
+				prop: key,
+				validOptions: declared
+			});
+		}
+		if (entry.type !== spec.kind) throw new IncantoError("UNKNOWN_ASSET", `'${nodeName}.${key}' needs ${KIND_LABEL[spec.kind] ?? spec.kind} — asset '${name}' is declared as "${String(entry.type)}". Change the entry's "type" to "${spec.kind}".`, {
+			prop: key,
+			validOptions: [spec.kind]
+		});
+	}
+}
+/** A plausible asset key for the message, from whatever they wrote. */
+function suggestKey(value) {
+	const last = value.split(/[/\\]/).pop() ?? value;
+	const stem = last.split("?")[0]?.replace(/\.[a-z0-9]+$/i, "") ?? last;
+	return stem !== "" ? stem : "myAsset";
+}
+//#endregion
+//#region src/core/scene/environment.ts
+const SKY_KEYS = [
+	"type",
+	"sunPosition",
+	"elevationDeg",
+	"azimuthDeg",
+	"turbidity",
+	"rayleigh"
+];
+const FOG_KEYS = [
+	"color",
+	"near",
+	"far"
+];
+const CLOUD_KEYS = [
+	"coverage",
+	"density",
+	"base",
+	"top",
+	"color",
+	"shadeColor",
+	"speed",
+	"scale"
+];
+const BLOOM_KEYS = ["threshold", "strength"];
+const POST_KEYS = [
+	"vignette",
+	"saturation",
+	"contrast"
+];
+const SHADOW_KEYS = [
+	"mapSize",
+	"radius",
+	"static"
+];
+const SHADOW_MAP_SIZES = [1024, 2048];
+const DEFAULT_TURBIDITY = 2;
+const DEFAULT_RAYLEIGH = 1;
+const DEFAULT_FOG_NEAR = 50;
+const DEFAULT_FOG_FAR = 800;
+/** Fallback haze when fog is declared without a sky to derive a horizon from. */
+const DEFAULT_FOG_COLOR = "#cfd8e0";
+const DEG2RAD = Math.PI / 180;
+/** Parse + hard-validate the 3D slice of a scene's `environment` header. */
+function parseEnvironment3D(env) {
+	return {
+		exposure: parseExposure(env?.exposure),
+		sky: parseSky(env?.sky),
+		fog: parseFog(env?.fog, env?.sky !== void 0),
+		clouds: parseClouds(env?.clouds),
+		bloom: parseBloom(env?.bloom),
+		post: parsePost(env?.post),
+		shadows: parseShadows(env?.shadows)
+	};
+}
+/**
+* elevation/azimuth (degrees) → unit direction. Matches three's Sky example
+* (`Vector3.setFromSphericalCoords`): azimuth 0 = +Z, 90 = +X; elevation 90 =
+* straight up.
+*/
+function sunDirectionFromElevationAzimuth(elevationDeg, azimuthDeg) {
+	const phi = (90 - elevationDeg) * DEG2RAD;
+	const theta = azimuthDeg * DEG2RAD;
+	return [
+		Math.sin(phi) * Math.sin(theta),
+		Math.cos(phi),
+		Math.sin(phi) * Math.cos(theta)
+	];
+}
+/** The sky's sun as a UNIT vector — what Water3D/Foliage3D uniforms consume. */
+function sunDirectionFromSky(sky) {
+	const [x, y, z] = sky.sunPosition;
+	const len = Math.hypot(x, y, z) || 1;
+	return [
+		x / len,
+		y / len,
+		z / len
+	];
+}
+/**
+* A horizon-ish haze color derived from the sky config — the default fog
+* color. Cheap model, judged by eye: clear skies haze blue-grey, turbid skies
+* whiten, and a low sun warms the band toward amber.
+*/
+function horizonColorFromSky(sky) {
+	const clear = [
+		191,
+		213,
+		232
+	];
+	const hazy = [
+		233,
+		228,
+		217
+	];
+	const warm = [
+		242,
+		201,
+		150
+	];
+	const t = clamp01((sky.turbidity - DEFAULT_TURBIDITY) / 8);
+	const dir = sunDirectionFromSky(sky);
+	const w = clamp01((18 - Math.asin(clamp(dir[1], -1, 1)) / DEG2RAD) / 18) * .8;
+	const mix = (i) => Math.round(lerp(lerp(clear[i], hazy[i], t), warm[i], w));
+	return `#${[
+		mix(0),
+		mix(1),
+		mix(2)
+	].map((c) => c.toString(16).padStart(2, "0")).join("")}`;
+}
+function parseExposure(value) {
+	if (value === void 0) return 1;
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) throw new IncantoError("BAD_FORMAT", `environment.exposure must be a finite number > 0 (tone-mapping exposure, default 1), got ${JSON.stringify(value)}.`, { prop: "exposure" });
+	return value;
+}
+function parseSky(value) {
+	if (value === void 0) return null;
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new IncantoError("BAD_FORMAT", `environment.sky must be an object ({ type?: "atmosphere", sunPosition? | elevationDeg?+azimuthDeg?, turbidity?, rayleigh? }), got ${JSON.stringify(value)}.`, { prop: "sky" });
+	const sky = value;
+	for (const key of Object.keys(sky)) if (!SKY_KEYS.includes(key)) throw new IncantoError("BAD_FORMAT", `environment.sky has unknown key '${key}'. Valid keys: [${SKY_KEYS.join(", ")}].`, {
+		prop: "sky",
+		validOptions: SKY_KEYS
+	});
+	if (sky.type !== void 0 && sky.type !== "atmosphere") throw new IncantoError("BAD_FORMAT", `environment.sky.type must be 'atmosphere' (the only sky type so far), got ${JSON.stringify(sky.type)}.`, {
+		prop: "sky",
+		validOptions: ["atmosphere"]
+	});
+	const hasAngles = sky.elevationDeg !== void 0 || sky.azimuthDeg !== void 0;
+	if (sky.sunPosition !== void 0 && hasAngles) throw new IncantoError("BAD_FORMAT", `environment.sky takes sunPosition OR elevationDeg/azimuthDeg, not both.`, {
+		prop: "sky",
+		validOptions: ["sunPosition", "elevationDeg+azimuthDeg"]
+	});
+	let sunPosition;
+	if (sky.sunPosition !== void 0) {
+		const sp = sky.sunPosition;
+		if (!Array.isArray(sp) || sp.length !== 3 || !sp.every((v) => typeof v === "number" && Number.isFinite(v)) || Math.hypot(sp[0], sp[1], sp[2]) === 0) throw new IncantoError("BAD_FORMAT", `environment.sky.sunPosition must be a non-zero [x, y, z] vector, got ${JSON.stringify(sp)}.`, { prop: "sky" });
+		sunPosition = [
+			sp[0],
+			sp[1],
+			sp[2]
+		];
+	} else {
+		const elevation = numberOr(sky.elevationDeg, 32, "sky.elevationDeg");
+		const azimuth = numberOr(sky.azimuthDeg, 135, "sky.azimuthDeg");
+		if (elevation < -90 || elevation > 90) throw new IncantoError("BAD_FORMAT", `environment.sky.elevationDeg must be in [-90, 90] (degrees above the horizon), got ${elevation}.`, { prop: "sky" });
+		sunPosition = sunDirectionFromElevationAzimuth(elevation, azimuth);
+	}
+	const turbidity = numberOr(sky.turbidity, DEFAULT_TURBIDITY, "sky.turbidity");
+	if (turbidity <= 0) throw new IncantoError("BAD_FORMAT", `environment.sky.turbidity must be > 0 (atmospheric haze; 2 ≈ clear day), got ${turbidity}.`, { prop: "sky" });
+	const rayleigh = numberOr(sky.rayleigh, DEFAULT_RAYLEIGH, "sky.rayleigh");
+	if (rayleigh < 0) throw new IncantoError("BAD_FORMAT", `environment.sky.rayleigh must be >= 0 (Rayleigh scattering; 1 ≈ earth-like), got ${rayleigh}.`, { prop: "sky" });
+	return {
+		sunPosition,
+		turbidity,
+		rayleigh
+	};
+}
+function parseFog(value, hasSky) {
+	if (value === void 0) return null;
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new IncantoError("BAD_FORMAT", `environment.fog must be an object ({ color?, near?, far? }), got ${JSON.stringify(value)}.`, { prop: "fog" });
+	const fog = value;
+	for (const key of Object.keys(fog)) if (!FOG_KEYS.includes(key)) throw new IncantoError("BAD_FORMAT", `environment.fog has unknown key '${key}'. Valid keys: [${FOG_KEYS.join(", ")}].`, {
+		prop: "fog",
+		validOptions: FOG_KEYS
+	});
+	if (fog.color !== void 0 && typeof fog.color !== "string") throw new IncantoError("BAD_FORMAT", `environment.fog.color must be a hex color string, got ${JSON.stringify(fog.color)}.`, { prop: "fog" });
+	const near = numberOr(fog.near, DEFAULT_FOG_NEAR, "fog.near");
+	const far = numberOr(fog.far, DEFAULT_FOG_FAR, "fog.far");
+	if (near < 0) throw new IncantoError("BAD_FORMAT", `environment.fog.near must be >= 0 meters, got ${near}.`, { prop: "fog" });
+	if (far <= near) throw new IncantoError("BAD_FORMAT", `environment.fog.far must be > near (got near ${near}, far ${far}).`, { prop: "fog" });
+	return {
+		color: fog.color ?? (hasSky ? "" : DEFAULT_FOG_COLOR),
+		near,
+		far
+	};
+}
+function parseClouds(value) {
+	if (value === void 0) return null;
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new IncantoError("BAD_FORMAT", `environment.clouds must be an object ({ coverage?, density?, base?, top?, color?, shadeColor?, speed?, scale? }), got ${JSON.stringify(value)}.`, { prop: "clouds" });
+	const c = value;
+	for (const key of Object.keys(c)) if (!CLOUD_KEYS.includes(key)) throw new IncantoError("BAD_FORMAT", `environment.clouds has unknown key '${key}'. Valid keys: [${CLOUD_KEYS.join(", ")}].`, {
+		prop: "clouds",
+		validOptions: CLOUD_KEYS
+	});
+	for (const k of ["color", "shadeColor"]) if (c[k] !== void 0 && typeof c[k] !== "string") throw new IncantoError("BAD_FORMAT", `environment.clouds.${k} must be a hex color string, got ${JSON.stringify(c[k])}.`, { prop: "clouds" });
+	const coverage = numberOr(c.coverage, .5, "clouds.coverage");
+	if (coverage < 0 || coverage > 1) throw new IncantoError("BAD_FORMAT", `environment.clouds.coverage must be in [0, 1] (how much sky is cloudy), got ${coverage}.`, { prop: "clouds" });
+	const density = numberOr(c.density, 1, "clouds.density");
+	if (density < 0) throw new IncantoError("BAD_FORMAT", `environment.clouds.density must be >= 0 (optical thickness), got ${density}.`, { prop: "clouds" });
+	const base = numberOr(c.base, 120, "clouds.base");
+	const top = numberOr(c.top, 320, "clouds.top");
+	if (top <= base) throw new IncantoError("BAD_FORMAT", `environment.clouds.top must be > base (got base ${base}, top ${top}).`, { prop: "clouds" });
+	const speed = numberOr(c.speed, 1, "clouds.speed");
+	const scale = numberOr(c.scale, 240, "clouds.scale");
+	if (scale <= 0) throw new IncantoError("BAD_FORMAT", `environment.clouds.scale must be > 0 (feature size in world units), got ${scale}.`, { prop: "clouds" });
+	return {
+		coverage,
+		density,
+		base,
+		top,
+		color: c.color ?? "#ffffff",
+		shadeColor: c.shadeColor ?? "#9fb0c8",
+		speed,
+		scale
+	};
+}
+function parseBloom(value) {
+	if (value === void 0) return null;
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new IncantoError("BAD_FORMAT", `environment.bloom must be an object ({ threshold?, strength? }), got ${JSON.stringify(value)}.`, { prop: "bloom" });
+	const b = value;
+	for (const key of Object.keys(b)) if (!BLOOM_KEYS.includes(key)) throw new IncantoError("BAD_FORMAT", `environment.bloom has unknown key '${key}'. Valid keys: [${BLOOM_KEYS.join(", ")}].`, {
+		prop: "bloom",
+		validOptions: BLOOM_KEYS
+	});
+	const threshold = numberOr(b.threshold, 1, "bloom.threshold");
+	if (threshold < 0 || threshold > 8) throw new IncantoError("BAD_FORMAT", `environment.bloom.threshold must be in [0, 8] (linear-HDR luminance; 1 = white), got ${threshold}.`, { prop: "bloom" });
+	const strength = numberOr(b.strength, .8, "bloom.strength");
+	if (strength < 0) throw new IncantoError("BAD_FORMAT", `environment.bloom.strength must be >= 0, got ${strength}.`, { prop: "bloom" });
+	return {
+		threshold,
+		strength
+	};
+}
+function parsePost(value) {
+	if (value === void 0) return null;
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new IncantoError("BAD_FORMAT", `environment.post must be an object ({ vignette?, saturation?, contrast? }), got ${JSON.stringify(value)}.`, { prop: "post" });
+	const p = value;
+	for (const key of Object.keys(p)) if (!POST_KEYS.includes(key)) throw new IncantoError("BAD_FORMAT", `environment.post has unknown key '${key}'. Valid keys: [${POST_KEYS.join(", ")}].`, {
+		prop: "post",
+		validOptions: POST_KEYS
+	});
+	const vignette = numberOr(p.vignette, 0, "post.vignette");
+	if (vignette < 0 || vignette > 1) throw new IncantoError("BAD_FORMAT", `environment.post.vignette must be in [0, 1], got ${vignette}.`, { prop: "post" });
+	const saturation = numberOr(p.saturation, 1, "post.saturation");
+	if (saturation < 0 || saturation > 4) throw new IncantoError("BAD_FORMAT", `environment.post.saturation must be in [0, 4] (1 = neutral), got ${saturation}.`, { prop: "post" });
+	const contrast = numberOr(p.contrast, 1, "post.contrast");
+	if (contrast < .2 || contrast > 3) throw new IncantoError("BAD_FORMAT", `environment.post.contrast must be in [0.2, 3] (1 = neutral), got ${contrast}.`, { prop: "post" });
+	return {
+		vignette,
+		saturation,
+		contrast
+	};
+}
+function parseShadows(value) {
+	if (value === void 0) return null;
+	if (value === false) return false;
+	if (value === true) return {
+		mapSize: 2048,
+		radius: 1,
+		static: false
+	};
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new IncantoError("BAD_FORMAT", `environment.shadows must be true, false or an object ({ mapSize?, radius? }), got ${JSON.stringify(value)}.`, { prop: "shadows" });
+	const shadows = value;
+	for (const key of Object.keys(shadows)) if (!SHADOW_KEYS.includes(key)) throw new IncantoError("BAD_FORMAT", `environment.shadows has unknown key '${key}'. Valid keys: [${SHADOW_KEYS.join(", ")}].`, {
+		prop: "shadows",
+		validOptions: SHADOW_KEYS
+	});
+	const mapSize = shadows.mapSize === void 0 ? 2048 : shadows.mapSize;
+	if (!SHADOW_MAP_SIZES.includes(mapSize)) throw new IncantoError("BAD_FORMAT", `environment.shadows.mapSize must be one of [${SHADOW_MAP_SIZES.join(", ")}], got ${JSON.stringify(shadows.mapSize)}.`, {
+		prop: "shadows",
+		validOptions: SHADOW_MAP_SIZES.map(String)
+	});
+	const radius = numberOr(shadows.radius, 1, "shadows.radius");
+	if (radius < 0) throw new IncantoError("BAD_FORMAT", `environment.shadows.radius must be >= 0, got ${radius}.`, { prop: "shadows" });
+	const staticShadows = shadows.static === void 0 ? false : shadows.static;
+	if (typeof staticShadows !== "boolean") throw new IncantoError("BAD_FORMAT", `environment.shadows.static must be a boolean, got ${JSON.stringify(shadows.static)}.`, { prop: "shadows" });
+	return {
+		mapSize,
+		radius,
+		static: staticShadows
+	};
+}
+function numberOr(value, fallback, at) {
+	if (value === void 0) return fallback;
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new IncantoError("BAD_FORMAT", `environment.${at} must be a finite number, got ${JSON.stringify(value)}.`, { prop: at });
+	return value;
+}
+function clamp(v, min, max) {
+	return Math.min(Math.max(v, min), max);
+}
+function clamp01(v) {
+	return clamp(v, 0, 1);
+}
+function lerp(a, b, t) {
+	return a + (b - a) * t;
+}
+//#endregion
+//#region src/core/scene/environment-validate.ts
+/**
+* Check a scene's `environment` header at LOAD.
+*
+* `parseEnvironment3D` has always thrown good errors — and its only caller was
+* `Environment3D.apply()`, inside a live renderer, in a browser. So the scene
+* header's biggest block was the one thing `loadScene` and `incanto-check`
+* could not check. Measured, every one of these loading clean and reported as
+* `1/1 scene(s) valid`:
+*
+* ```
+* sky.type = "gradient" (only atmosphere exists)   NO ERROR
+* shadows = "soft"                                 NO ERROR
+* exposure = "bright"                              NO ERROR
+* rendering.pixelRatio = "auto"                    NO ERROR
+* a typo'd top-level key: skye                     NO ERROR
+* ```
+*
+* The last two are the ones that cost a whole session. A typo'd top-level key
+* means the sky you thought you declared does not exist — no backdrop, no
+* image-based light, no sun, no message. And `pixelRatio: "auto"` (the
+* plausible typo for `"device"`) reaches `setPixelRatio("auto")`, three
+* computes `Math.floor(width * NaN)`, and the canvas becomes 0×0: the game
+* renders nothing at all.
+*
+* Same shape as the asset refs and as `nodePath`/`required` before them — the
+* rule existed and nothing routed to it at author time.
+*/
+/**
+* Top-level blocks the renderer reads.
+*
+* Kept in step with the consumers by a test, not by discipline: the first cut
+* of this list was written by hand and left out `iblIntensity` and `preset`,
+* which 17 shipped scenes use — so the check rejected the engine's own
+* examples. A whitelist nobody can verify is a new way to be wrong.
+*/
+const ENVIRONMENT_KEYS = [
+	"ambient",
+	"background",
+	"bloom",
+	"clouds",
+	"exposure",
+	"fog",
+	"hdri",
+	"iblIntensity",
+	"post",
+	"preset",
+	"rendering",
+	"shadows",
+	"sky",
+	"skybox"
+];
+/** Closest declared key by a cheap edit distance, for "did you mean". */
+function nearest(key) {
+	const lower = key.toLowerCase();
+	let best = null;
+	let bestScore = 3;
+	for (const known of ENVIRONMENT_KEYS) {
+		const d = distance(lower, known);
+		if (d < bestScore) {
+			bestScore = d;
+			best = known;
+		}
+	}
+	return best;
+}
+function distance(a, b) {
+	const rows = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+	for (let j = 0; j <= b.length; j++) rows[0][j] = j;
+	for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) {
+		const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+		rows[i][j] = Math.min(rows[i - 1][j] + 1, rows[i][j - 1] + 1, rows[i - 1][j - 1] + cost);
+	}
+	return rows[a.length][b.length];
+}
+/** `rendering` is read by the renderer, not by `parseEnvironment3D`. */
+function validateRendering(rendering) {
+	if (rendering === void 0) return;
+	if (typeof rendering !== "object" || rendering === null || Array.isArray(rendering)) throw new IncantoError("BAD_FORMAT", `environment.rendering must be an object ({ antialias?, pixelRatio? }), got ${JSON.stringify(rendering)}.`);
+	const r = rendering;
+	for (const key of Object.keys(r)) {
+		if (key === "antialias" || key === "pixelRatio" || key === "preserveDrawingBuffer") continue;
+		throw new IncantoError("BAD_FORMAT", `environment.rendering has unknown key '${key}'. Valid keys: [antialias, pixelRatio, preserveDrawingBuffer].`, {
+			prop: key,
+			validOptions: [
+				"antialias",
+				"pixelRatio",
+				"preserveDrawingBuffer"
+			]
+		});
+	}
+	const ratio = r.pixelRatio;
+	if (ratio !== void 0 && ratio !== "device" && typeof ratio !== "number") throw new IncantoError("BAD_FORMAT", `environment.rendering.pixelRatio must be a number or "device", got ${JSON.stringify(ratio)}. Anything else reaches setPixelRatio() as-is and gives the game a 0×0 canvas.`, {
+		prop: "pixelRatio",
+		validOptions: ["device"]
+	});
+	if (typeof ratio === "number" && !(ratio > 0 && Number.isFinite(ratio))) throw new IncantoError("BAD_FORMAT", `environment.rendering.pixelRatio must be greater than 0, got ${JSON.stringify(ratio)}.`, { prop: "pixelRatio" });
+	if (r.antialias !== void 0 && typeof r.antialias !== "boolean") throw new IncantoError("BAD_FORMAT", `environment.rendering.antialias must be true or false, got ${JSON.stringify(r.antialias)}.`, { prop: "antialias" });
+}
+/**
+* Throws `BAD_FORMAT` for anything in `environment` the renderer would reject
+* or silently drop.
+*
+* @param environment the scene's `environment` block
+* @param dimension only a 3D scene has this contract
+*/
+function validateEnvironment(environment, dimension) {
+	if (environment === void 0 || environment === null) return;
+	if (typeof environment !== "object" || Array.isArray(environment)) throw new IncantoError("BAD_FORMAT", `Scene "environment" must be an object, got ${JSON.stringify(environment)}.`);
+	const env = environment;
+	validateRendering(env.rendering);
+	if (dimension !== "3d") return;
+	for (const key of Object.keys(env)) {
+		if (ENVIRONMENT_KEYS.includes(key)) continue;
+		const guess = nearest(key);
+		throw new IncantoError("BAD_FORMAT", `environment has unknown key '${key}'${guess ? ` — did you mean "${guess}"?` : ""}. Valid keys: [${ENVIRONMENT_KEYS.join(", ")}].`, {
+			prop: key,
+			validOptions: [...ENVIRONMENT_KEYS]
+		});
+	}
+	parseEnvironment3D(env);
+}
+//#endregion
 //#region src/core/scene/network-validate.ts
 /**
 * Hard-check a node's `network` block at LOAD.
@@ -1958,7 +2732,12 @@ function loadScene(json, opts) {
 	const sceneJson = json;
 	validateHeader(sceneJson);
 	validateStrings(sceneJson.strings);
+	validateEnvironment(sceneJson.environment, sceneJson.dimension);
 	inheritedStrings = {};
+	loadingAssets = {
+		...opts?.declaredAssets ?? {},
+		...sceneJson.assets ?? {}
+	};
 	const root = buildNode(sceneJson.root, opts, [], "", sceneJson.constants, Object.keys(sceneJson.orderGroups ?? {}));
 	validateUniqueUids(root);
 	const tree = new SceneTree();
@@ -1967,6 +2746,7 @@ function loadScene(json, opts) {
 	wireConnections(root, sceneJson.connections ?? [], opts?.declareConnectionSignals);
 	const collected = inheritedStrings;
 	inheritedStrings = null;
+	loadingAssets = null;
 	return new Scene(withInheritedStrings(sceneJson, collected), root, tree);
 }
 /**
@@ -1978,6 +2758,15 @@ function loadScene(json, opts) {
 * constants table is passed the way it is.
 */
 let inheritedStrings = null;
+/**
+* The `assets{}` table to validate `$ref`s against, or null outside a load.
+*
+* NULL, not empty: `buildNodeJson` rebuilds a detached subtree for
+* `duplicateNode` and for `NetworkSpawner`, and there is no scene header in
+* either — checking against "no assets" there would reject every sprite in a
+* duplicated node.
+*/
+let loadingAssets = null;
 /** Fold one sub-scene's table into the accumulator. */
 function inheritStrings(strings) {
 	if (!inheritedStrings || strings === void 0) return;
@@ -2089,6 +2878,10 @@ function parentOf(path) {
 	const i = path.lastIndexOf("/");
 	return i <= 0 ? "" : path.slice(0, i);
 }
+/** The merged prop schema of whatever type this node is. */
+function propsFor(node) {
+	return mergeStaticProps(node.constructor);
+}
 function applyCommon(node, nj, opts) {
 	if (typeof nj.uid === "string" && nj.uid !== "") node.uid = nj.uid;
 	node.name = nj.name;
@@ -2103,6 +2896,7 @@ function applyCommon(node, nj, opts) {
 		node.behavior = behavior;
 		for (const s of mergeStaticSignals(behavior.constructor)) node.declareSignal(s);
 	}
+	if (loadingAssets) validateAssetRefs(nj.props ?? {}, propsFor(node), loadingAssets, node.name);
 	if (nj.network) {
 		validateNetworkBlock(nj.network, node.name);
 		node.network = jsonClone(nj.network);
@@ -2125,6 +2919,7 @@ function wireConnections(root, connections, declareSignals = false) {
 		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}')` : "") + `.`);
+		if (ambiguousHandler(toNode, conn.handler)) throw ambiguousHandlerError(toNode, conn.handler, toNode.script?.name, conn.to);
 		const listener = (...args) => {
 			if (conn.filter && !matchesFilter(args[0], conn.filter)) return;
 			if (conn.once) fromNode.off(conn.signal, listener);
@@ -2203,4 +2998,4 @@ function validateUniqueUids(root) {
 	walk(root);
 }
 //#endregion
-export { getBehavior as A, Node as C, behaviorSchema as D, Behavior as E, registeredBehaviors as M, Signal as N, behaviorSignals as O, InputMap as S, parseNodePath as T, savesWithoutUid as _, serializeNode as a, effectiveOrder as b, resolveViewport as c, isConstRef as d, resolveConstants as f, restoreBehaviors as g, captureBehaviors as h, Scene as i, registerBehavior as j, clearBehaviors as k, SceneTree as l, behaviorsWithoutSave as m, loadScene as n, SCENE_FORMAT as o, SaveSlots as p, loader_exports as r, computeViewport as s, buildNodeJson as t, CONST_REF_KEY as u, createSaveStore as v, diagnose as w, resolveOrderGroups as x, ORDER_GROUP_BASE as y };
+export { describeRefProblem as A, registeredBehaviors as B, ORDER_GROUP_BASE as C, handlerShadowWarnings as D, InputMap as E, behaviorSchema as F, behaviorSignals as I, clearBehaviors as L, resolveRefInJson as M, parseNodePath as N, Node as O, Behavior as P, getBehavior as R, createSaveStore as S, resolveOrderGroups as T, Signal as V, SaveSlots as _, serializeNode as a, restoreBehaviors as b, parseEnvironment3D as c, computeViewport as d, resolveViewport as f, resolveConstants as g, isConstRef as h, Scene as i, nodeRefWarnings as j, diagnose as k, sunDirectionFromElevationAzimuth as l, CONST_REF_KEY as m, loadScene as n, SCENE_FORMAT as o, SceneTree as p, loader_exports as r, horizonColorFromSky as s, buildNodeJson as t, sunDirectionFromSky as u, behaviorsWithoutSave as v, effectiveOrder as w, savesWithoutUid as x, captureBehaviors as y, registerBehavior as z };