incanto 0.66.0 → 0.68.0

package/dist/{physics-3d-BkHjwJgI.js → physics-3d-bG3n70Ky.js}

@@ -1,10 +1,10 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { k as diagnose } from "./loader-lQDCwNag.js";
+import { k as diagnose } from "./loader-BC4PNtJX.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { H as CharacterBody3D, K as Node3D, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, q as validateCollider3D } from "./gameplay-D1RADWu3.js";
+import { H as CharacterBody3D, K as Node3D, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, q as validateCollider3D } from "./gameplay-DM1eu_cV.js";
 import { n as registerDebugSource } from "./debug-draw-BM3DsvtT.js";
 import { n as jointContacts, t as withoutRapierInitNoise } from "./quiet-rapier-C6fW4zcW.js";
-import { A as Terrain3D, F as InstancedMesh3D, L as buildMeshGeometry, P as Joint3D } from "./environment-presets-BlPsEmq6.js";
+import { A as Terrain3D, F as InstancedMesh3D, L as buildMeshGeometry, P as Joint3D } from "./environment-presets-CybQXNqS.js";
 import { Euler, Matrix4, Quaternion, Vector3 } from "three";
 //#region src/3d/physics/collider-lines.ts
 /**
@@ -262,6 +262,7 @@ var Physics3D = class {
 		this.unregisterDebug = registerDebugSource(this);
 		this.disconnect = engine.fixedUpdated.connect((dt) => this.step(dt));
 		this.disconnectScene = engine.sceneChanged.connect(() => {
+			this.pruneOverlaps();
 			if (engine.scene) this.syncBodies();
 		});
 		engine.physics = this;
@@ -609,6 +610,7 @@ var Physics3D = class {
 				this.byColliderHandle.delete(e.collider.handle);
 				this.world.removeRigidBody(e.body);
 				this.entries.delete(node);
+				this.forgetOverlaps(node);
 				node._physics = null;
 				node._interpPrev = node._interpCurr = null;
 			}
@@ -824,6 +826,31 @@ var Physics3D = class {
 		}
 	}
 	/**
+	* Forget every overlap whose node has left the tree.
+	*
+	* The lazy drop inside `overlapping()` only cleans the SETS of a key someone
+	* asks about, and only when they ask. This clears the KEYS, which is where the
+	* dead nodes were pinned.
+	*/
+	/** Drop one node from the overlap map, both as a key and as a member. */
+	forgetOverlaps(node) {
+		this.overlaps.delete(node);
+		for (const [self, others] of this.overlaps) {
+			others.delete(node);
+			if (others.size === 0) this.overlaps.delete(self);
+		}
+	}
+	pruneOverlaps() {
+		for (const [self, others] of this.overlaps) {
+			if (self.tree === null) {
+				this.overlaps.delete(self);
+				continue;
+			}
+			for (const other of others) if (other.tree === null) others.delete(other);
+			if (others.size === 0) this.overlaps.delete(self);
+		}
+	}
+	/**
 	* The bodies currently overlapping `node` — the standing answer behind
 	* `triggerEnter`/`triggerExit`.
 	*

package/dist/react.d.ts

@@ -1,5 +1,5 @@
-import { P as Scene, b as Engine, n as BehaviorCtor } from "./behavior-BXNLfIJk.js";
-import { c as JsonValue } from "./schema-CFeioQRE.js";
+import { P as Scene, b as Engine, n as BehaviorCtor } from "./behavior-DoFPYrgo.js";
+import { c as JsonValue } from "./schema-B6ugCV1Q.js";
 import { CSSProperties, ReactNode } from "react";
 
 //#region src/react/index.d.ts

package/dist/react.js

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

package/dist/{register-BmuqYTiY.js → register-3ta-2Xig.js}

@@ -1,8 +1,9 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { C as ORDER_GROUP_BASE, E as InputMap, O as Node, S as createSaveStore, T as resolveOrderGroups, V as Signal, b as restoreBehaviors, k as diagnose, y as captureBehaviors } from "./loader-lQDCwNag.js";
+import { C as ORDER_GROUP_BASE, E as InputMap, O as Node, S as createSaveStore, T as resolveOrderGroups, V as Signal, b as restoreBehaviors, k as diagnose, y as captureBehaviors } from "./loader-BC4PNtJX.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
 import { l as registerNode } from "./registry-CF70EArN.js";
+import { r as capturePointer } from "./touch-DEAmqGdf.js";
 //#region src/core/audio/buses.ts
 const AUDIO_LOG_LIMIT = 200;
 var AudioBuses = class {
@@ -178,6 +179,11 @@ var WebAudioTrack = class {
 	setLoop(loop) {
 		this.el.loop = loop;
 	}
+	/** The element's own playhead — the clock the sound is actually on. */
+	playhead() {
+		const at = this.el.currentTime;
+		return typeof at === "number" && Number.isFinite(at) ? at : null;
+	}
 	play() {
 		this.el.play().catch((error) => {
 			const name = error?.name ?? "";
@@ -242,7 +248,8 @@ const SILENT_BACKEND = {
 		setGain() {},
 		setLoop() {},
 		play() {},
-		stop() {}
+		stop() {},
+		playhead: () => null
 	}),
 	unlock() {}
 };
@@ -282,6 +289,24 @@ var MusicManager = class {
 	get current() {
 		return this.active?.track.src ?? null;
 	}
+	/**
+	* Seconds into the current track — the playhead of the thing you can HEAR.
+	*
+	* `null` when nothing is playing, or when the backend has no clock (headless,
+	* or a custom backend that does not implement it).
+	*
+	* A game charted to a soundtrack needs this and there was no way to get it:
+	* `current` gave the src and the backend was private, so the only option was
+	* an `engine.time` counter started next to `music.play()` — a different clock
+	* from the one the audio is on, and one that keeps counting through a
+	* gesture-block, a stall or a seek. This is the audio's own answer.
+	*
+	* It is the RAW element time, so a looping track wraps to 0 at each pass:
+	* that is a loop boundary you can chart against, not a fault.
+	*/
+	get playhead() {
+		return this.active?.track.playhead?.() ?? null;
+	}
 	/** Per-manager volume (0..1), on top of the bus gain. */
 	get volume() {
 		return this._volume;
@@ -1035,6 +1060,16 @@ var SfxEngine = class {
 		if (ctx && ctx.state === "suspended") ctx.resume();
 	}
 	/**
+	* The AUDIO clock, in seconds — the one a sound is actually scheduled
+	* against, and the only clock that does not drift relative to what you hear.
+	*
+	* `0` headless and before the first sound, since there is no context yet.
+	* Schedule with a lead: `sfx.play(params, 1, { when: sfx.now + 0.08 })`.
+	*/
+	get now() {
+		return this.ctx?.currentTime ?? 0;
+	}
+	/**
 	* Play a preset at `gain` (0..1, already bus-multiplied by the caller). Each
 	* call spawns its own source so rapid repeats overlap instead of cutting off.
 	* Headless → no-op.
@@ -1076,7 +1111,7 @@ var SfxEngine = class {
 		const source = ctx.createBufferSource();
 		source.buffer = buffer;
 		source.connect(gainNode);
-		source.start();
+		source.start(opts.when === void 0 ? 0 : Math.max(0, opts.when));
 	}
 };
 //#endregion
@@ -1339,11 +1374,29 @@ var HudLayer = class extends Node {
 			}
 		}
 	}
-	/** Focusable widgets under this layer, in tree order. */
+	/**
+	* Focusable widgets under this layer, in tree order — **on screen only**.
+	*
+	* This filtered on each widget's OWN `visible` and recursed into hidden
+	* containers anyway, so arrow-keys walked into closed panels and Enter really
+	* pressed what it found. Measured on a title screen: 23 focus stops, 21 of
+	* them under an ancestor with `visible = false`, and
+	*
+	*   gold before = 150 -> Enter on the hidden Shop/Row0/Buy -> gold 120,
+	*   screen still 'title'
+	*
+	* The layer's own visibility was not a gate either. It is now: a HUD nobody
+	* can see has no ring, and a subtree nobody can see is not walked.
+	*
+	* PUBLIC, because a game that wants to know what its ring contains could not
+	* ask — and "why is focus on that" is exactly the question this answers.
+	*/
 	focusables() {
 		const out = [];
+		if (!this.visible) return out;
 		const walk = (node) => {
-			if (node instanceof HudWidgetBase && node.focusable && node.visible) out.push(node);
+			if (node instanceof HudWidgetBase && !node.visible) return;
+			if (node instanceof HudWidgetBase && node.focusable) out.push(node);
 			for (const child of node.children) walk(child);
 		};
 		walk(this);
@@ -1513,7 +1566,7 @@ var HudWidgetBase = class extends Node {
 			el.addEventListener("pointerdown", (event) => {
 				if (!this.draggable) return;
 				event.preventDefault();
-				el.setPointerCapture?.(event.pointerId);
+				capturePointer(el, event.pointerId);
 				dragging = this;
 				draggingFrom = dropTargetFromElement(el.parentElement);
 				el.style.opacity = "0.6";
@@ -1553,10 +1606,16 @@ var HudWidgetBase = class extends Node {
 			this._mountWidget();
 			if (!this._element) return;
 		}
-		this._element.style.display = this.visible ? "" : "none";
 		this._followAnchor();
 		this._sync();
+		if (this._element.style.display !== "none") this._shownDisplay = this._element.style.display;
+		this._element.style.display = this.visible ? this._shownDisplay : "none";
 	}
+	/**
+	* The display this widget's own css asks for while shown — `grid` for a grid
+	* panel, `flex` for a row, `''` for a widget that never says.
+	*/
+	_shownDisplay = "";
 	/** Which anchor slot this widget was mounted into. */
 	mountedAnchor = null;
 	/**
@@ -2280,14 +2339,9 @@ function qualityEnvironment(tier) {
 	};
 	if (tier === "medium") return {
 		shadows: { static: true },
-		bloom: {},
 		post: null
 	};
-	return {
-		shadows: true,
-		bloom: {},
-		post: {}
-	};
+	return { shadows: true };
 }
 const QUALITY_CAPS = Object.freeze({
 	low: Object.freeze({
@@ -2436,7 +2490,7 @@ var Engine = class {
 	* reset on reload. Reading it here costs nothing (localStorage, once) and
 	* `bindAudio` makes the volumes write themselves.
 	*/
-	settings = new Settings();
+	settings;
 	/**
 	* Translations, and the locale in force. English is the base and the default;
 	* anything a locale does not declare falls back to it silently.
@@ -2510,6 +2564,7 @@ var Engine = class {
 		this.scheduler = opts.scheduler ?? rafScheduler;
 		this.rng = new Rng(opts.seed ?? Math.random() * 4294967295 >>> 0);
 		this.maxFps = opts.maxFps ?? 0;
+		this.settings = opts.settings instanceof Settings ? opts.settings : new Settings(opts.settings?.namespace ?? "settings");
 		this.sfx._setBuses(this.audio);
 		this.music.onTrackError = (src, reason) => {
 			diagnose(this, "error", `[incanto] music '${src}' will not play — ${reason}.`);
@@ -2636,8 +2691,9 @@ var Engine = class {
 	captureState() {
 		const root = this.scene?.root;
 		if (!root) return {};
-		const { state, unaddressable } = captureBehaviors(root, this.scene?.source);
+		const { state, unaddressable, unrecordable } = captureBehaviors(root, this.scene?.source);
 		for (const path of unaddressable) diagnose(this, "warn", `save: ${path} has state to save and no uid to key it under.`);
+		if (unrecordable.length > 0) diagnose(this, "error", `[incanto] save: ${unrecordable.length} authored node(s) this run consumed have no uid, so nothing records that they are gone and LOADING THIS SAVE BRINGS THEM BACK: ${unrecordable.slice(0, 8).join(", ")}${unrecordable.length > 8 ? `, +${unrecordable.length - 8} more` : ""}. Give each one a "uid" from newUid().`);
 		return state;
 	}
 	/** Give it back, after the scene is loaded and onReady has run. */
@@ -2983,10 +3039,32 @@ var AudioPlayer = class extends Node {
 			rolloff: this.rolloff
 		};
 	}
-	play() {
+	/**
+	* Start the sound. `at` schedules it on the AUDIO clock instead of now.
+	*
+	* A frame is a 16.67 ms grid at 60 Hz and 33.33 ms at 30, so a sound fired
+	* from `update()` cannot land closer than one frame to where a chart wants
+	* it — measured 0 of 64 notes scheduled on the documented path. Queue it a
+	* lead ahead of `engine.sfx.now` and the same notes land at |mean| 0.000000
+	* ms:
+	*
+	* ```ts
+	* const lead = 0.08;                        // schedule this far ahead
+	* for (const note of dueSoon(engine.sfx.now + lead)) {
+	*   hit.play(engine.sfx.now + (note.atSec - songSeconds));
+	* }
+	* ```
+	*
+	* PRESETS only — a `src` clip goes through an `<audio>` element, which has no
+	* scheduling clock, and passing `at` for one is ignored rather than silently
+	* approximated. Everything else is unchanged: the bus gain applies, the sound
+	* lands in `engine.audio.recent()`, and `muted` still silences it, none of
+	* which a hand-rolled `AudioContext` scheduler keeps.
+	*/
+	play(at) {
 		if (this.preset !== "custom") {
 			this.note("preset", this.preset);
-			this.playPreset();
+			this.playPreset(at);
 			return;
 		}
 		if (!this.src) return;
@@ -3030,7 +3108,7 @@ var AudioPlayer = class extends Node {
 	* the length is arithmetic, not a device. WebAudio needs a gesture; a
 	* suspended context is resumed by the same unlock listener as `src` players.
 	*/
-	playPreset() {
+	playPreset(at) {
 		const params = SFX_PRESETS[this.preset];
 		if (!params) return;
 		const engine = this.tree?.engine;
@@ -3041,7 +3119,8 @@ var AudioPlayer = class extends Node {
 		sfx.play(params, this.gain(), {
 			pitch: this.pitch,
 			seed: this.seed,
-			spatial: this.spatialPlay()
+			spatial: this.spatialPlay(),
+			when: at
 		});
 	}
 	/**
@@ -3077,6 +3156,10 @@ var AudioPlayer = class extends Node {
 		}
 		if (this.presetEndsAt !== null) {
 			if ((this.tree?.engine?.unscaledTime ?? 0) >= this.presetEndsAt) {
+				if (this.loop) {
+					this.playPreset();
+					return;
+				}
 				this.presetEndsAt = null;
 				this._playing = false;
 				this.emit("finished");
@@ -3187,6 +3270,7 @@ var UiDialogue = class extends HudWidgetBase {
 	];
 	static props = {
 		...HudWidgetBase.props,
+		focusable: { default: true },
 		anchor: {
 			default: "bottom",
 			options: [
@@ -3236,6 +3320,49 @@ var UiDialogue = class extends HudWidgetBase {
 		});
 	}
 	/**
+	* A dialogue takes focus while it is up.
+	*
+	* It paints a focus ring and the generated reference advertises the prop, and
+	* it was inert: choices are raw DOM buttons inside the widget, so
+	* `HudLayer.focusables()` can never see them, and this class — unlike
+	* `UiButton` a hundred lines above it — never overrode `_activate`. Eleven
+	* keys and eight pad codes did nothing to a waiting choice while the same
+	* Enter pressed a sibling button. Native Tab worked, and is closed by any
+	* game that binds Tab; a pad has no Tab at all.
+	*/
+	focusable = true;
+	/** Which choice the keyboard/pad is on. Reset by every new line. */
+	cursor = 0;
+	/**
+	* Enter / A, and left / right between the options.
+	*
+	* `dir` is 0 for "activate" and ±1 for a nudge, the same shape `UiSelect`
+	* uses — so one key layout drives a menu, a slider and a conversation.
+	*/
+	_activate(dir) {
+		if (!this.active || !this.current) return;
+		const choices = this.current.choices;
+		if (!choices || choices.length === 0) {
+			this.advance();
+			return;
+		}
+		if (dir !== 0) {
+			this.cursor = (this.cursor + dir + choices.length) % choices.length;
+			this.paintCursor();
+			return;
+		}
+		this.choose(this.cursor);
+	}
+	/** Show which option the keyboard is on — a ring nobody can see is not one. */
+	paintCursor() {
+		const buttons = this.choicesEl?.children;
+		if (!buttons) return;
+		for (let i = 0; i < buttons.length; i++) {
+			const el = buttons[i];
+			if (el) el.style.outline = i === this.cursor ? "2px solid #fff" : "none";
+		}
+	}
+	/**
 	* Player pressed "next": mid-typing reveals the whole line; a fully-typed
 	* line without choices advances (choice lines wait for `choose`).
 	*/
@@ -3318,12 +3445,11 @@ var UiDialogue = class extends HudWidgetBase {
 			this.revealed = Math.round(progress * this.current.text.length);
 			if (this.speakerEl) this.speakerEl.textContent = this.current.speaker;
 		}
-		const wasTyping = this.revealed < this.current.text.length;
-		if (wasTyping) this.revealed = Math.min(this.current.text.length, this.revealed + this.charsPerSecond * dt);
+		if (this.revealed < this.current.text.length) this.revealed = Math.min(this.current.text.length, this.revealed + this.charsPerSecond * dt);
 		const doneTyping = this.revealed >= this.current.text.length;
 		if (this.textEl) this.textEl.textContent = this.showing;
 		if (this.hintEl) this.hintEl.style.visibility = doneTyping && !this.current.choices ? "visible" : "hidden";
-		if (doneTyping && wasTyping && this.current.choices && this.choicesEl) this.current.choices.forEach((label, i) => {
+		if (doneTyping && this.current.choices && this.choicesEl && this.choicesEl.children.length === 0) this.current.choices.forEach((label, i) => {
 			const b = document.createElement("button");
 			b.type = "button";
 			b.textContent = label;

package/dist/{register-D0CxCveZ.js → register-ibCjm-wH.js}

@@ -1,10 +1,10 @@
-import { O as Node, k as diagnose, w as effectiveOrder } from "./loader-lQDCwNag.js";
-import { L as translateOn, t as registerCoreNodes } from "./register-BmuqYTiY.js";
+import { O as Node, k as diagnose, w as effectiveOrder } from "./loader-BC4PNtJX.js";
+import { L as translateOn, t as registerCoreNodes } from "./register-3ta-2Xig.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-CF70EArN.js";
 import { i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, r as validateAnimationAliases, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-CY-mrr1L.js";
-import { F as localFromWorld, I as worldPosition } from "./gameplay-D1RADWu3.js";
+import { F as localFromWorld, I as worldPosition } from "./gameplay-DM1eu_cV.js";
 import { t as checkSheetGrid } from "./sheet-grid-BT6N_Bjs.js";
 import { AdditiveBlending, BufferAttribute, BufferGeometry, CanvasTexture, Color, DynamicDrawUsage, Group, InstancedMesh, MathUtils, Matrix4, Mesh, MeshBasicMaterial, NearestFilter, NormalBlending, Object3D, PlaneGeometry, SRGBColorSpace } from "three";
 //#region src/2d/physics/collider-validate.ts

package/dist/{replay-IsZbNu6d.js → replay-CYvhVHHN.js}

@@ -1,5 +1,5 @@
-import { D as handlerShadowWarnings, j as nodeRefWarnings } from "./loader-lQDCwNag.js";
-import { R as translationKey, k as HudWidgetBase } from "./register-BmuqYTiY.js";
+import { D as handlerShadowWarnings, j as nodeRefWarnings } from "./loader-BC4PNtJX.js";
+import { R as translationKey, k as HudWidgetBase } from "./register-3ta-2Xig.js";
 import { o as getNodeType } from "./registry-CF70EArN.js";
 //#region src/core/audit.ts
 const ANIMATED_TYPES = new Set([
@@ -104,6 +104,28 @@ function transformOf(props) {
 	if (scaled) return "scale";
 	return null;
 }
+/**
+* Which files in a corpus some OTHER scene embeds with `instance`.
+*
+* A fragment cannot be recognised by looking at itself — `enemy.scene.json` and
+* a broken first level are the same file shape. It is recognised by the project
+* around it, which every tool that audits more than one scene already walks.
+*
+* `resolveRef(fromFile, ref)` turns a scene-relative `instance` path into the
+* same spelling the corpus uses for that file, so the caller owns all path
+* logic and this stays runnable in a browser.
+*/
+function instancedScenes(corpus, resolveRef) {
+	const instanced = /* @__PURE__ */ new Set();
+	const walk = (node, from) => {
+		if (!node || typeof node !== "object") return;
+		const ref = node.instance;
+		if (typeof ref === "string" && ref) instanced.add(resolveRef(from, ref));
+		for (const child of node.children ?? []) walk(child, from);
+	};
+	for (const { path, json } of corpus) walk(json.root, path);
+	return instanced;
+}
 function auditScene(scene, opts = {}) {
 	const warnings = [];
 	const root = scene.root;
@@ -166,7 +188,9 @@ function auditScene(scene, opts = {}) {
 	if (cameraDrivers.length > 0 && followedCameras.length > 0) warnings.push(`${followedCameras.join(", ")}: a FollowCamera writes this camera's position every frame, and so does the CharacterController3D at ${cameraDrivers.join(", ")} — the controller owns the camera in every view it has. Drop one of them: use the controller's own \`view\`/\`camDistance\`, or take the controller off the camera duty.`);
 	if (cameras > 0 && currentCameras === 0) warnings.push("no camera has \"current\": true — the screen renders from a default view, probably not what you framed.");
 	if (currentCameras > 1) warnings.push(`${currentCameras} cameras claim "current": true — only the first found wins.`);
-	if (scene.dimension === "3d" && lights === 0 && !isLit(scene.environment)) warnings.push("nothing lights this 3D scene — no light node, no environment sky/hdri, and no ambient intensity. It will render black. Add a DirectionalLight3D, or an \"environment\": { \"sky\": { \"type\": \"atmosphere\" } } / { \"preset\": \"...\" }.");
+	const isFragment = opts.instanced === true || scene.fragment === true;
+	if (scene.dimension === "3d" && !isFragment && cameras === 0) warnings.push("this 3D scene has no camera — the screen renders from a default view, which is almost never the shot you want. Add a Camera3D with \"current\": true, or set \"fragment\": true in the scene header if this file is a prefab another scene drops in.");
+	if (scene.dimension === "3d" && !isFragment && lights === 0 && !isLit(scene.environment)) warnings.push("nothing lights this 3D scene — no light node, no environment sky/hdri, and no ambient intensity. It will render black. Add a DirectionalLight3D, or an \"environment\": { \"sky\": { \"type\": \"atmosphere\" } } / { \"preset\": \"...\" } — or set \"fragment\": true if another scene lights this one.");
 	if (damageGroups.length > 0) {
 		const hurtable = hurtableGroups(root);
 		for (const { path, group } of damageGroups) {
@@ -358,4 +382,4 @@ function replay(engine, recording, opts) {
 	}
 }
 //#endregion
-export { startRecording as n, auditScene as r, replay as t };
+export { instancedScenes as i, startRecording as n, auditScene as r, replay as t };

package/dist/{replay-BHoB6fCU.d.ts → replay-Dvn8aeBd.d.ts}

@@ -1,5 +1,5 @@
-import { b as Engine } from "./behavior-BXNLfIJk.js";
-import { s as JsonObject } from "./schema-CFeioQRE.js";
+import { b as Engine } from "./behavior-DoFPYrgo.js";
+import { s as JsonObject } from "./schema-B6ugCV1Q.js";
 
 //#region src/core/audit.d.ts
 /** Human-readable warnings (empty = clean). Pure JSON walk, no registry. */
@@ -15,7 +15,41 @@ interface AuditOptions {
   * has one.
   */
   declaredElsewhere?: Record<string, Record<string, string>>;
+  /**
+  * Another scene in this project embeds this file with `instance`.
+  *
+  * That, and only that, makes a scene a FRAGMENT — a thing lit and framed by
+  * whatever drops it in, which must not be told it will render black.
+  *
+  * The discriminator used to be "it has no camera", which is the same shape a
+  * beginner's FIRST 3D scene has. Measured on a ground plane and a capsule
+  * with no camera and no light — a guaranteed black screen:
+  *
+  *   $ incanto-check
+  *     ok  src/game.scene.json
+  *   1/1 scene(s) valid
+  *
+  * Not the lighting warning, and not the camera one either. The checker walks
+  * the whole project already (it unions `strings` and `assets` the same way),
+  * so it can answer this by looking instead of guessing.
+  */
+  instanced?: boolean;
 }
+/**
+* Which files in a corpus some OTHER scene embeds with `instance`.
+*
+* A fragment cannot be recognised by looking at itself — `enemy.scene.json` and
+* a broken first level are the same file shape. It is recognised by the project
+* around it, which every tool that audits more than one scene already walks.
+*
+* `resolveRef(fromFile, ref)` turns a scene-relative `instance` path into the
+* same spelling the corpus uses for that file, so the caller owns all path
+* logic and this stays runnable in a browser.
+*/
+declare function instancedScenes(corpus: {
+  path: string;
+  json: JsonObject;
+}[], resolveRef: (fromFile: string, ref: string) => string): Set<string>;
 declare function auditScene(scene: JsonObject, opts?: AuditOptions): string[];
 //#endregion
 //#region src/core/errors.d.ts
@@ -25,7 +59,7 @@ declare function auditScene(scene: JsonObject, opts?: AuditOptions): string[];
 * Incanto fails loudly with machine-readable codes and messages that list valid
 * alternatives — AI agents self-correct on hard failures, not warnings.
 */
-type IncantoErrorCode = "AMBIGUOUS_HANDLER" | "BAD_FORMAT" | "BAD_NODE_PATH" | "DANGLING_CONNECTION" | "DUPLICATE_BEHAVIOR" | "DUPLICATE_NODE_TYPE" | "DUPLICATE_UNIQUE_NAME" | "DUPLICATE_UID" | "NODE_NOT_FOUND" | "PROP_TYPE_MISMATCH" | "TREE_VIOLATION" | "UNKNOWN_ANIMATION" | "UNKNOWN_ASSET" | "UNKNOWN_CONSTANT" | "UNKNOWN_BEHAVIOR" | "UNKNOWN_HANDLER" | "UNKNOWN_NODE_TYPE" | "UNKNOWN_PROP" | "UNKNOWN_SIGNAL" | "UNRESOLVED_INSTANCE";
+type IncantoErrorCode = "AMBIGUOUS_HANDLER" | "BAD_FORMAT" | "BAD_NODE_PATH" | "DANGLING_CONNECTION" | "DUPLICATE_BEHAVIOR" | "DUPLICATE_NODE_TYPE" | "DUPLICATE_UNIQUE_NAME" | "DUPLICATE_UID" | "NODE_NOT_FOUND" | "PROP_TYPE_MISMATCH" | "TREE_VIOLATION" | "UNKNOWN_ANIMATION" | "UNKNOWN_ASSET" | "UNKNOWN_CONSTANT" | "UNKNOWN_BEHAVIOR" | "UNKNOWN_HANDLER" | "UNKNOWN_NODE_TYPE" | "UNKNOWN_PROP" | "UNKNOWN_SIGNAL" | "UNRESOLVED_INSTANCE" | "WEBGL_UNAVAILABLE";
 /**
 * Structured context mirrored from the prose message — tools and agents parse
 * THESE instead of regexing the message (which is for humans and may reword).
@@ -100,4 +134,4 @@ declare function replay(engine: Engine, recording: ReplayJson, opts?: {
   onTick?: (index: number) => void;
 }): void;
 //#endregion
-export { startRecording as a, IncantoErrorDetails as c, replay as i, auditScene as l, ReplayEvent as n, IncantoError as o, ReplayJson as r, IncantoErrorCode as s, Recorder as t };
+export { startRecording as a, IncantoErrorDetails as c, replay as i, auditScene as l, ReplayEvent as n, IncantoError as o, ReplayJson as r, IncantoErrorCode as s, Recorder as t, instancedScenes as u };

package/dist/{schema-CFeioQRE.d.ts → schema-B6ugCV1Q.d.ts}

@@ -74,6 +74,17 @@ interface SceneJson {
   input?: JsonObject;
   /** Physics config — `{gravity: [x,y]}` (2D px/s²) or `{gravity: [x,y,z]}` (3D m/s²). */
   physics?: JsonObject;
+  /**
+  * This scene is a PIECE of another one — a spawner's prefab, an instanced
+  * sub-scene — and is never rendered on its own.
+  *
+  * It exists because no tool can tell a prefab from a broken first level by
+  * looking at the file: both are a small tree with no camera and no light. The
+  * audit used to guess ("no camera means fragment") and so went silent on the
+  * commonest beginner mistake there is. One key, written by the author who
+  * knows, is the honest version. It changes nothing at runtime.
+  */
+  fragment?: boolean;
   /** Multiplayer config (interpreted in M6; preserved verbatim until then). */
   multiplayer?: JsonObject;
   /** Scene-level rendering environment (ambient light, background — interpreted by renderers). */

package/dist/{split-screen-D_i7GRcY.js → split-screen-CYwDkbLF.js}

@@ -1,5 +1,5 @@
-import { O as Node, V as Signal, k as diagnose, n as loadScene, t as buildNodeJson } from "./loader-lQDCwNag.js";
-import { t as registerCoreNodes, v as Engine } from "./register-BmuqYTiY.js";
+import { O as Node, V as Signal, k as diagnose, n as loadScene, t as buildNodeJson } from "./loader-BC4PNtJX.js";
+import { t as registerCoreNodes, v as Engine } from "./register-3ta-2Xig.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { n as jsonEquals, t as jsonClone } from "./json-CwwhxQgb.js";
 import { l as registerNode } from "./registry-CF70EArN.js";

package/dist/{split-screen-eJUFjhi1.d.ts → split-screen-DhrSzZIB.d.ts}

@@ -1,6 +1,6 @@
-import { Lt as Signal, b as Engine, jt as Node } from "./behavior-BXNLfIJk.js";
-import { c as JsonValue, i as SceneJson, s as JsonObject } from "./schema-CFeioQRE.js";
-import { t as LoadSceneOptions } from "./loader-Cga7FVP4.js";
+import { Lt as Signal, b as Engine, jt as Node } from "./behavior-DoFPYrgo.js";
+import { c as JsonValue, i as SceneJson, s as JsonObject } from "./schema-B6ugCV1Q.js";
+import { t as LoadSceneOptions } from "./loader-CcB533FR.js";
 
 //#region src/net/types.d.ts
 type Unsubscribe = () => void;

package/dist/{src-BTLbXFPZ.js → src-D7RIqXYF.js}

@@ -214,6 +214,6 @@ function newUid() {
 //#endregion
 //#region src/index.ts
 /** Engine version. Kept in sync with package.json by the release pipeline. */
-const VERSION = "0.66.0";
+const VERSION = "0.68.0";
 //#endregion
 export { preloadUrls as a, preloadSceneAssets as i, newUid as n, findPath as o, assetUrls as r, gridFromRows as s, VERSION as t };

package/dist/{teardown-byR9USax.js → teardown-D2NEmxPB.js}

@@ -1,5 +1,5 @@
-import { _ as AudioPlayer } from "./register-BmuqYTiY.js";
-import { a as logReport, s as parseDrive } from "./touch-DESwnpOc.js";
+import { _ as AudioPlayer } from "./register-3ta-2Xig.js";
+import { i as logReport, o as parseDrive } from "./webgl-unavailable-N9nQqesw.js";
 import { a as frameSignature, i as frameImage, o as frameStats } from "./frame-report-BSMny7oe.js";
 //#region src/core/audio-errors.ts
 /** Every AudioPlayer under `root` whose source could not be played. */