incanto 0.60.0 → 0.62.0

package/dist/{register-Da3hXh2H.js → register-D3yx8D4r.js}

@@ -1,8 +1,8 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { C as Node, N as Signal, S as InputMap, g as restoreBehaviors, h as captureBehaviors, v as createSaveStore, w as diagnose, x as resolveOrderGroups, y as ORDER_GROUP_BASE } from "./loader-D8n7TU8W.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-DEe272nY.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
-import { l as registerNode } from "./registry-WWcQcfMr.js";
+import { l as registerNode } from "./registry-CF70EArN.js";
 //#region src/core/audio/buses.ts
 const AUDIO_LOG_LIMIT = 200;
 var AudioBuses = class {
@@ -612,6 +612,16 @@ const SFX_PRESETS = {
 	}
 };
 const SFX_PRESET_NAMES = Object.keys(SFX_PRESETS);
+/**
+* How long a preset lasts, in seconds — the same `attack + sustain + decay`
+* `synthSfx` uses to size its buffer.
+*
+* `pitch` deliberately does not enter into it: it is a frequency multiplier,
+* not a playback rate, so a preset played an octave up is the same length.
+*/
+function sfxDuration(params) {
+	return params.attack + params.sustain + params.decay;
+}
 const TWO_PI = Math.PI * 2;
 /**
 * Render a preset to mono PCM in [-1, 1]. PURE: identical inputs → identical
@@ -1369,6 +1379,14 @@ var HudLayer = class extends Node {
 * widget (an icon inside a slot), so the walk upward is the point.
 */
 const widgetOf = /* @__PURE__ */ new WeakMap();
+/** The nearest ancestor widget that actually accepts a drop. */
+function dropTargetFromElement(el) {
+	for (let n = el; n; n = n.parentElement) {
+		const found = widgetOf.get(n);
+		if (found?.dropTarget) return found;
+	}
+	return null;
+}
 function widgetFromElement(el) {
 	for (let n = el; n; n = n.parentElement) {
 		const found = widgetOf.get(n);
@@ -1378,6 +1396,8 @@ function widgetFromElement(el) {
 }
 /** The drag in flight, if any. One pointer, one drag. */
 let dragging = null;
+/** The drop target the dragged widget came OUT of — putting it back is a no-op. */
+let draggingFrom = null;
 /** Shared plumbing: mount into the parent HudLayer's anchor slot. */
 var HudWidgetBase = class extends Node {
 	/**
@@ -1495,6 +1515,7 @@ var HudWidgetBase = class extends Node {
 				event.preventDefault();
 				el.setPointerCapture?.(event.pointerId);
 				dragging = this;
+				draggingFrom = dropTargetFromElement(el.parentElement);
 				el.style.opacity = "0.6";
 				this.emit("dragStarted", this);
 			});
@@ -1502,9 +1523,12 @@ var HudWidgetBase = class extends Node {
 				if (dragging !== this) return;
 				el.style.opacity = "";
 				el.releasePointerCapture?.(event.pointerId);
-				const target = widgetFromElement(document.elementFromPoint?.(event.clientX, event.clientY) ?? null);
+				const under = document.elementFromPoint?.(event.clientX, event.clientY) ?? null;
+				const target = dropTargetFromElement(under) ?? widgetFromElement(under);
+				const origin = draggingFrom;
 				dragging = null;
-				if (target && target !== this && target.dropTarget) {
+				draggingFrom = null;
+				if (target && target !== this && target !== origin && target.dropTarget) {
 					this.emit("droppedOn", target);
 					target.emit("dropped", this);
 				} else this.emit("dragCancelled", this);
@@ -2463,6 +2487,7 @@ var Engine = class {
 		this.input.clear();
 		this._time = 0;
 		this._unscaledTime = 0;
+		this.timeScale = 1;
 		if (scene.input) this.input.declare(scene.input);
 		if (scene.strings) this.locale.load(scene.strings);
 		this.orderGroups = resolveOrderGroups(scene.orderGroups);
@@ -2744,7 +2769,7 @@ function createElement() {
 }
 /**
 * One sound. `play()` (or `autoplay: true`) starts it; `finished` fires when
-* it ends. Browsers block audio before the first user gesture — a blocked
+* it ends — for a procedural preset as well as a `src` clip. Browsers block audio before the first user gesture — a blocked
 * play marks `pendingGesture`; `createGame` retries pending players on the
 * first pointer/key gesture automatically.
 *
@@ -2801,10 +2826,12 @@ var AudioPlayer = class extends Node {
 	/** Start on the first frame in the tree (subject to the gesture policy). */
 	autoplay = false;
 	/**
-	* 3D positional audio: in a 3D scene the sound pans + attenuates by the
-	* emitter's world position relative to the active Camera3D (the listener).
-	* Default false → identical non-spatial behavior (back-compat). In a 2D scene
-	* spatial is currently ignored (the adapter feeds no pose) — see incanto-audio.
+	* Positional audio: the sound pans + attenuates by the emitter's world
+	* position relative to the active camera (the listener). Default false →
+	* identical non-spatial behavior.
+	*
+	* Both dimensions. A 2D scene measures in PIXELS, so the distances below —
+	* metre-shaped defaults — need setting there; `auditScene` says so.
 	*/
 	spatial = false;
 	/** Distance at which spatial gain is full; closer never gets louder. */
@@ -2838,6 +2865,21 @@ var AudioPlayer = class extends Node {
 	loadError = null;
 	element = null;
 	_playing = false;
+	/**
+	* `engine.unscaledTime` at which the preset currently sounding ends.
+	*
+	* A preset used to be fire-and-forget: `playing` stayed false through a sound
+	* that was audibly playing, and `finished` — a signal this node DECLARES, so
+	* a connection to it loads clean — never fired at all. Wiring "when the coin
+	* chime ends, free the pickup" to a preset player produced a wire that is
+	* dead for the life of the game and says nothing.
+	*
+	* The end is known exactly: `attack + sustain + decay` is the length
+	* `synthSfx` sizes its buffer to. Measured on the UNSCALED clock because a
+	* sound does not slow down when the game does, and a paused game still hears
+	* the tail of the hit that paused it.
+	*/
+	presetEndsAt = null;
 	autoplayed = false;
 	/** Last spatial pose pushed by the 3D adapter (null until/unless spatial). */
 	_spatialPose = null;
@@ -2940,15 +2982,18 @@ var AudioPlayer = class extends Node {
 	}
 	/**
 	* Procedural-SFX path: synthesize the preset and fire it through WebAudio
-	* (low-latency, overlap-friendly). Fire-and-forget — no `finished`/`playing`
-	* tracking (these are short one-shots, not the element-driven `src` clip).
-	* Headless (no AudioContext) → silent no-op. WebAudio also needs a gesture;
-	* a suspended context is resumed by the same unlock listener as `src` players.
+	* (low-latency, overlap-friendly). Headless (no AudioContext) plays nothing —
+	* but still reports `playing` and still emits `finished` on schedule, because
+	* 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() {
 		const params = SFX_PRESETS[this.preset];
 		if (!params) return;
-		const sfx = this.tree?.engine?.sfx;
+		const engine = this.tree?.engine;
+		this._playing = true;
+		this.presetEndsAt = (engine?.unscaledTime ?? 0) + sfxDuration(params);
+		const sfx = engine?.sfx;
 		if (!sfx) return;
 		sfx.play(params, this.gain(), {
 			pitch: this.pitch,
@@ -2974,6 +3019,7 @@ var AudioPlayer = class extends Node {
 			this.element.pause();
 			this.element.currentTime = 0;
 		}
+		this.presetEndsAt = null;
 		this._playing = false;
 		this.pendingGesture = false;
 	}
@@ -2986,6 +3032,13 @@ var AudioPlayer = class extends Node {
 			this.autoplayed = true;
 			this.play();
 		}
+		if (this.presetEndsAt !== null) {
+			if ((this.tree?.engine?.unscaledTime ?? 0) >= this.presetEndsAt) {
+				this.presetEndsAt = null;
+				this._playing = false;
+				this.emit("finished");
+			}
+		}
 		if (this.element && this._playing) {
 			this.element.volume = this.gain() * this.spatialElementGain();
 			this.element.loop = this.loop;
@@ -3241,6 +3294,161 @@ var UiDialogue = class extends HudWidgetBase {
 	}
 };
 //#endregion
+//#region src/core/nodes/respawn.ts
+/** Out of the world, from the spawn: metres in 3D, pixels in 2D. */
+const AUTO_DROP_3D_M = 50;
+const AUTO_DROP_2D_PX = 1e3;
+/**
+* Catch whatever this node hangs off when it leaves the world, and put it back.
+*
+* Nothing in the engine did this. Not a node, not a behavior, not a scene
+* header — and the shipped examples prove what that costs: with the `plays`
+* rung finally counting defects, `basic-3d-sideview` fails 8 seeded runs out of
+* 8, `water-lake-3d` 7, `water-ocean-3d` 5, `water-pool-3d` 4,
+* `water-river-3d` 1. Every one of them the same way — the player walks off the
+* edge of the terrain and falls forever, and the only fix available was a
+* per-frame `y` check hand-written in TypeScript, which is exactly the kind of
+* thing this engine exists to keep out of TypeScript.
+*
+* A CHILD NODE rather than a Behavior, deliberately: a node holds one behavior
+* and the player's is already spoken for (`PlayerControl`, `Health`, the game's
+* own script). Children stack, the way `CharacterController3D` already hangs
+* off its body.
+*
+* ```jsonc
+* { "name": "Player", "type": "RigidBody3D", "props": { … },
+*   "children": [
+*     { "name": "Ctl", "type": "CharacterController3D" },
+*     { "name": "Catch", "type": "Respawn" }            // that is the whole thing
+*   ] }
+* ```
+*
+* With no props it guards its parent, uses the same line the playtest's fall
+* detector uses (50 m under the spawn in 3D, 1000 px in 2D), and puts the node
+* back where it started. `respawned` fires each time, so a life can be taken
+* off a `ScoreKeeper` or a `Health` with an ordinary connection — this node
+* does not decide what falling COSTS, which is a game-design question and not
+* a physics one.
+*/
+var Respawn = class extends Node {
+	static typeName = "Respawn";
+	static signals = ["respawned"];
+	static props = {
+		target: {
+			default: "..",
+			nodePath: true
+		},
+		below: { default: null },
+		to: { default: [] },
+		resetVelocity: { default: true }
+	};
+	/**
+	* Who is being caught. Defaults to the parent, which is the whole point of
+	* hanging this off the thing it guards.
+	*/
+	target = "..";
+	/**
+	* The line past which the target has left the world, in the scene's own
+	* down: 3D counts down (−y), 2D counts down the screen (+y).
+	*
+	* `null` is AUTO — the spawn position offset by the same distance the
+	* playtest's own fall detector uses, so "the level says it fell" and "the
+	* ladder says it fell" cannot disagree. Author a number when the level has a
+	* real floor to name; leave it alone otherwise.
+	*/
+	below = null;
+	/** Where to put it back. Empty = wherever it started. */
+	to = [];
+	/**
+	* Zero the body's velocity on the way back.
+	*
+	* On by default because the alternative is invisible: a body respawned with
+	* 40 m/s of accumulated fall still in it drops straight back through the
+	* line on the next frame, and the level flickers instead of resuming.
+	*/
+	resetVelocity = true;
+	/** How many times this has caught the target — for HUDs and tests. */
+	falls = 0;
+	home = [];
+	line = null;
+	/** +1 when "out" means y greater (2D screen-down), −1 when smaller (3D). */
+	down = -1;
+	onReady() {
+		const target = this.guarded();
+		this.home = this.to.length > 0 ? [...this.to] : [...positionOf(target)];
+		this.spawnY = worldY(target);
+	}
+	spawnY = 0;
+	/**
+	* Which way is out, and where the line is.
+	*
+	* Resolved on the first `update` rather than in `onReady`, because
+	* `onReady` runs inside `loadScene` — BEFORE `setScene` attaches the engine —
+	* so the scene's `dimension` is not readable there yet. Reading it there
+	* silently gives every 2D scene the 3D answer, and a line above a falling
+	* player fires on frame one, forever.
+	*
+	* Not called `resolve`: `Node` has a private method by that name and
+	* `getNodeOrNull` calls it, so a subclass method with the same name
+	* overrides it on the prototype — `private` is a TypeScript fiction that
+	* costs nothing at runtime — and every path lookup this node made returned a
+	* number. `node-method-shadowing.test.ts` refuses the whole family now.
+	*/
+	fallLine() {
+		if (this.line !== null) return this.line;
+		this.down = this.tree?.engine?.scene?.dimension === "2d" ? 1 : -1;
+		const drop = this.down > 0 ? AUTO_DROP_2D_PX : AUTO_DROP_3D_M;
+		this.line = this.below ?? this.spawnY + this.down * drop;
+		return this.line;
+	}
+	/** The node this guards, or itself if the path no longer resolves. */
+	guarded() {
+		return this.getNodeOrNull(this.target) ?? this;
+	}
+	update(_dt) {
+		const line = this.fallLine();
+		const target = this.guarded();
+		if (target === this) return;
+		const y = worldY(target);
+		if ((y - line) * this.down <= 0) return;
+		this.falls += 1;
+		setPosition(target, this.home);
+		if (this.resetVelocity) zeroVelocity(target);
+		this.emit("respawned", target, y);
+	}
+};
+function positionOf(node) {
+	const p = node.position;
+	return Array.isArray(p) ? p : [];
+}
+/** Sum of the `position[1]` of the node and every spatial ancestor. */
+function worldY(node) {
+	let y = 0;
+	let at = node;
+	while (at) {
+		y += positionOf(at)[1] ?? 0;
+		at = at.parent;
+	}
+	return y;
+}
+function setPosition(node, to) {
+	const slot = node;
+	if (!Array.isArray(slot.position)) return;
+	slot.position = slot.position.map((v, i) => to[i] ?? v);
+}
+/**
+* Stop whatever the fall built up.
+*
+* Both names are real: `RigidBody` calls it `linearVelocity` and
+* `CharacterBody` calls it `velocity`, and a respawn has to reach whichever
+* one this body has.
+*/
+function zeroVelocity(node) {
+	const body = node;
+	if (Array.isArray(body.linearVelocity)) body.linearVelocity = body.linearVelocity.map(() => 0);
+	if (Array.isArray(body.velocity)) body.velocity = body.velocity.map(() => 0);
+}
+//#endregion
 //#region src/core/nodes/timer.ts
 /**
 * The canonical serializable game clock — never `setTimeout` in game logic.
@@ -3372,7 +3580,10 @@ var UiImage = class extends HudWidgetBase {
 	static typeName = "UiImage";
 	static props = {
 		...HudWidgetBase.props,
-		src: { default: "" },
+		src: {
+			default: "",
+			asset: { kind: "texture" }
+		},
 		width: { default: 48 },
 		height: { default: 48 },
 		/** How the picture fills its box — `contain` never crops. */
@@ -3965,6 +4176,7 @@ var UiMuteToggle = class extends UiToggle {
 function registerCoreNodes() {
 	registerNode(Node);
 	registerNode(Timer);
+	registerNode(Respawn);
 	registerNode(AudioPlayer);
 	registerNode(HudLayer);
 	registerNode(UiText);
@@ -3985,4 +4197,4 @@ function registerCoreNodes() {
 	registerNode(UiMuteToggle);
 }
 //#endregion
-export { UiBar as A, ROLLOFF_MODELS as B, readDeviceHints as C, HudLayer as D, EffectLog as E, suggestLocale as F, synthSfx as G, spatialPan as H, translateOn as I, crossfadeGains as J, MusicManager as K, translationKey as L, BASE_LOCALE as M, Localization as N, HudWidgetBase as O, T_PREFIX as P, SfxEngine as R, qualityRendering as S, LogManager as T, SFX_PRESETS as U, spatialGain as V, SFX_PRESET_NAMES as W, AudioBuses as X, fadeGain as Y, Engine as _, UiMuteToggle as a, qualityCaps as b, UiRenderScaleSelect as c, UiToggle as d, UiVolumeSlider as f, AudioPlayer as g, UiDialogue as h, UiLanguageSelect as i, UiText as j, UiBanner as k, UiSelect as l, UiButton as m, UiFrameCapSelect as n, UiPanel as o, Timer as p, WebAudioMusicBackend as q, UiImage as r, UiQualitySelect as s, registerCoreNodes as t, UiSlider as u, engine_exports as v, suggestQuality as w, qualityEnvironment as x, Settings as y, isAudioContextAvailable as z };
+export { UiBanner as A, isAudioContextAvailable as B, qualityRendering as C, EffectLog as D, LogManager as E, T_PREFIX as F, SFX_PRESET_NAMES as G, spatialGain as H, suggestLocale as I, MusicManager as J, sfxDuration as K, translateOn as L, UiText as M, BASE_LOCALE as N, HudLayer as O, Localization as P, AudioBuses as Q, translationKey as R, qualityEnvironment as S, suggestQuality as T, spatialPan as U, ROLLOFF_MODELS as V, SFX_PRESETS as W, crossfadeGains as X, WebAudioMusicBackend as Y, fadeGain as Z, AudioPlayer as _, UiMuteToggle as a, Settings as b, UiRenderScaleSelect as c, UiToggle as d, UiVolumeSlider as f, UiDialogue as g, UiButton as h, UiLanguageSelect as i, UiBar as j, HudWidgetBase as k, UiSelect as l, Respawn as m, UiFrameCapSelect as n, UiPanel as o, Timer as p, synthSfx as q, UiImage as r, UiQualitySelect as s, registerCoreNodes as t, UiSlider as u, Engine as v, readDeviceHints as w, qualityCaps as x, engine_exports as y, SfxEngine as z };

package/dist/{registry-WWcQcfMr.js → registry-CF70EArN.js}

@@ -1,5 +1,35 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { r as jsonKind, t as jsonClone } from "./json-CwwhxQgb.js";
+//#region src/core/prop-range.ts
+function describe(range) {
+	const { min, max, exclusiveMin, allow } = range;
+	let body;
+	if (min !== void 0 && max !== void 0) body = `${min}..${max}`;
+	else if (min !== void 0) body = exclusiveMin ? `greater than ${min}` : `at least ${min}`;
+	else if (max !== void 0) body = `at most ${max}`;
+	else body = "a finite number";
+	return allow && allow.length > 0 ? `${body} (or ${allow.join(", ")})` : body;
+}
+/**
+* Throws `PROP_TYPE_MISMATCH` when a number falls outside its documented range.
+*
+* A non-number is ignored: the kind check has already run and reporting the
+* same value twice, under two codes, tells its reader nothing new.
+*
+* @param value the authored value
+* @param label `Type.prop`, for the message
+* @param range what the prop documents
+*/
+function validatePropRange(value, label, range) {
+	if (typeof value !== "number") return;
+	if (range.allow?.includes(value)) return;
+	if (!Number.isFinite(value)) throw new IncantoError("PROP_TYPE_MISMATCH", `Prop '${label}' must be a finite number, got ${value}.`, { prop: label });
+	const belowMin = range.min !== void 0 && (range.exclusiveMin ? value <= range.min : value < range.min);
+	const aboveMax = range.max !== void 0 && value > range.max;
+	if (!belowMin && !aboveMax) return;
+	throw new IncantoError("PROP_TYPE_MISMATCH", `Prop '${label}' must be ${describe(range)}, got ${value}.`, { prop: label });
+}
+//#endregion
 //#region src/core/registry.ts
 /**
 * Validate a prop value against its schema default:
@@ -120,7 +150,10 @@ function mergeStaticAliases(ctor) {
 */
 function applySchemaProps(target, schema, props, label, aliases = {}, extraOptions = {}) {
 	for (const [key, def] of Object.entries(schema)) target[key] = jsonClone(def.default);
-	if (!props) return;
+	if (props) applyGivenProps(target, schema, props, label, aliases, extraOptions);
+	requireNonEmpty(target, schema, label);
+}
+function applyGivenProps(target, schema, props, label, aliases, extraOptions) {
 	for (const [rawKey, value] of Object.entries(props)) {
 		const key = schema[rawKey] ? rawKey : aliases[rawKey] ?? rawKey;
 		const def = schema[key];
@@ -135,18 +168,37 @@ function applySchemaProps(target, schema, props, label, aliases = {}, extraOptio
 		const extra = extraOptions[key];
 		const options = def.options && extra && extra.length > 0 ? [...def.options, ...extra] : def.options;
 		validatePropValue(value, def.default, `${label}.${key}`, options);
+		if (def.range) validatePropRange(value, `${label}.${key}`, def.range);
 		target[key] = jsonClone(value);
 	}
+}
+function requireNonEmpty(target, schema, label) {
 	for (const [key, def] of Object.entries(schema)) {
 		if (!def.required) continue;
-		const value = target[key];
-		if (value === "" || value === void 0 || value === null) throw new IncantoError("PROP_TYPE_MISMATCH", `'${label}' needs a "${key}" — it is empty.`, {
+		if (!isEmptyValue(target[key])) continue;
+		throw new IncantoError("PROP_TYPE_MISMATCH", `'${label}' needs a "${key}" — it is empty.`, {
 			prop: key,
 			nodeType: label
 		});
 	}
 }
 /**
+* "Not a configuration" — what `required` refuses.
+*
+* The first cut only knew about `''`, which is what the two props that
+* introduced the flag hold. Three of the ones declared since default to an
+* ARRAY — `MoveTo.to`, `Patrol.points`, `WaveSpawner.waves` — and for those the
+* flag was inert: a `MoveTo` with no `to` loaded clean and moved nowhere, which
+* is exactly the failure the flag was added to stop. Found by running the
+* shipped package as a consumer instead of trusting the declaration.
+*/
+function isEmptyValue(value) {
+	if (value === "" || value === void 0 || value === null) return true;
+	if (Array.isArray(value)) return value.length === 0;
+	if (typeof value === "object") return Object.keys(value).length === 0;
+	return false;
+}
+/**
 * Instantiate a registered type, assign schema defaults (cloned), then the
 * given props — validating every key and its JSON kind against the default.
 */

package/dist/{replay-BCMK_VRP.d.ts → replay-C5x2vPF5.d.ts}

@@ -1,4 +1,4 @@
-import { b as Engine } from "./behavior-DWKTUzKI.js";
+import { b as Engine } from "./behavior-DsgayMsH.js";
 import { s as JsonObject } from "./schema-CFeioQRE.js";
 
 //#region src/core/audit.d.ts
@@ -25,7 +25,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 = "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";
 /**
 * Structured context mirrored from the prose message — tools and agents parse
 * THESE instead of regexing the message (which is for humans and may reword).