incanto 0.47.0 → 0.49.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { $ as suggestLocale, A as SettingsValues, At as LogLevel, B as captureBehaviors, C as EngineStats, Ct as PlayMusicOptions, Dt as NodeLifecycle, E as DeviceHints, Et as Node, F as BehaviorState, G as OrderGroup, H as SaveStore, I as RestoreReport, J as resolveOrderGroups, K as OrderGroupTable, L as SaveSlot, M as readDeviceHints, Mt as Signal, N as suggestQuality, Nt as SignalListener, O as QualityTier, Ot as SceneTree, P as Scene, Q as T_PREFIX, R as SaveSlots, S as Scheduler, St as MusicTrack, T as RendererStats, Tt as BusName, U as createSaveStore, V as restoreBehaviors, W as ORDER_GROUP_BASE, X as LocaleTables, Y as BASE_LOCALE, Z as Localization, _ as mergeStaticSignals, _t as SfxWave, a as clearBehaviors, at as Voice, b as Engine, bt as MusicBackend, c as registeredBehaviors, ct as ROLLOFF_MODELS, d as PropSchema, dt as Vec3, et as translationKey, f as clearRegistry, ft as spatialGain, g as getNodeType, gt as SfxParams, h as getNodeSignals, ht as SFX_PRESET_NAMES, i as behaviorSignals, it as isAudioContextAvailable, j as qualityEnvironment, jt as LogManager, k as Settings, kt as LogEntry, l as NodeCtor, lt as RolloffModel, m as getNodeSchema, mt as SFX_PRESETS, n as BehaviorCtor, nt as SfxEngine, o as getBehavior, ot as VoicePreset, p as createNode, pt as spatialPan, q as effectiveOrder, r as behaviorSchema, rt as SfxPlayOptions, s as registerBehavior, st as Listener, t as Behavior, tt as InputMap, u as PropDef, ut as SpatialParams, v as registerNode, vt as SynthOptions, w as GameStats, wt as AudioBuses, x as EngineOptions, xt as MusicManager, y as registeredTypes, yt as synthSfx, z as behaviorsWithoutSave } from "./behavior-62q0HWBO.js";
 import { a as Rng, c as JsonValue, d as jsonKind, i as SceneJson, l as jsonClone, n as NodeJson, o as JsonKind, r as SCENE_FORMAT, s as JsonObject, t as ConnectionJson, u as jsonEquals } from "./schema-CFeioQRE.js";
 import { n as loadScene, t as LoadSceneOptions } from "./loader-CeyU_bm1.js";
+import { i as resolveFrames, n as AnimationEntry, r as resolveAnimation, t as AnimationDef } from "./sprite-animation-CMr6f1K2.js";
 import { n as ParticleSimConfig, r as ParticleView, t as ParticleSim } from "./particle-sim-BzJ1yxoE.js";
 import { a as AudioElementLike, i as gridFromRows, n as PathGrid, o as AudioPlayer, r as findPath, t as FindPathOptions } from "./pathfinding-C49JSNNq.js";
 import { a as startRecording, c as IncantoErrorDetails, i as replay, l as auditScene, n as ReplayEvent, o as IncantoError, r as ReplayJson, s as IncantoErrorCode, t as Recorder } from "./replay-CAphXMyM.js";
@@ -69,6 +70,106 @@ interface DebugLineSource {
   debugLines(): Float32Array | null;
 }
 //#endregion
+//#region src/core/drive-script.d.ts
+/**
+* A little script for driving a game, in the words it already understands.
+*
+* `incanto-play` has driven scenes from bash for many releases — `press`,
+* `vector`, `step` — and cannot show you the result, because headless has no
+* pixels. `incanto-frame` has the pixels and cannot move. Between them an agent
+* could only ever look at the boot screen, and every interesting state in a
+* game is downstream of input: the boss room, the bridge, the moment after the
+* jump.
+*
+* So the same vocabulary drives the RUNNING page, and the frame comes back
+* after it. One language for both, or an agent has to learn two.
+*
+* Pure: parsing only. Who applies the steps is the page's business.
+*/
+type DriveStep = {
+  kind: "press";
+  action: string;
+} | {
+  kind: "release";
+  action: string;
+} | {
+  kind: "vector";
+  action: string;
+  x: number;
+  y: number;
+} | {
+  kind: "key";
+  code: string;
+  down: boolean;
+} | {
+  kind: "pointer";
+  dx: number;
+  dy: number;
+} | {
+  kind: "step";
+  ms: number;
+};
+interface DriveScript {
+  steps: DriveStep[];
+  /** Why nothing will run, or null. A refused script runs NONE of its steps. */
+  error: string | null;
+  /** Total simulated time the script asks for, ms. */
+  totalMs: number;
+}
+/**
+* `vector move 0 1; step 2000` → steps, or an error naming the bad command.
+*
+* Semicolons and newlines both separate, so a whole plan fits in one shell
+* argument and a longer one fits in a file. `#` starts a comment.
+*
+* A command it does not know REFUSES THE WHOLE SCRIPT. Skipping it would leave
+* an agent looking at a frame that never moved, believing it had walked
+* somewhere — the failure mode this exists to prevent.
+*/
+declare function parseDrive(text: string): DriveScript;
+//#endregion
+//#region src/core/log-report.d.ts
+interface AssetFailure {
+  ref: string;
+  url: string;
+  error: string;
+}
+interface LiveInput {
+  entries: readonly LogEntry[];
+  stats: EngineStats;
+  assetErrors: readonly AssetFailure[];
+  /**
+  * The page is one the browser has stopped drawing — hidden, or a window
+  * merely covered by another. It throttles such a tab to about a frame a
+  * second, and that number says nothing about the game.
+  */
+  hidden?: boolean;
+}
+/** One message, however many times the game said it. */
+interface GroupedLog {
+  level: LogLevel;
+  message: string;
+  count: number;
+  /** When it was last said, in the page's own clock. */
+  lastMs: number;
+}
+interface LiveReport {
+  ok: boolean;
+  /** Frame rate low enough to be felt (running, and not merely throttled). */
+  slow: boolean;
+  /** The browser is throttling this page — see {@link LiveInput.hidden}. */
+  hidden: boolean;
+  counts: Record<LogLevel, number>;
+  grouped: GroupedLog[];
+  /** The most severe thing said, or null when nothing was. */
+  worst: GroupedLog | null;
+  stats: EngineStats;
+  assetErrors: readonly AssetFailure[];
+}
+declare function logReport(input: LiveInput): LiveReport;
+/** The report as a person or an agent reads it: what is wrong, then the numbers. */
+declare function logText(r: LiveReport): string;
+//#endregion
 //#region src/core/node-path.d.ts
 /**
 * Godot-style NodePath grammar:
@@ -219,10 +320,37 @@ declare class UiText extends HudWidgetBase {
   static override readonly typeName: string;
   static override readonly props: PropSchema;
   text: string;
+  /**
+  * A template with a `{}` slot that `setText` fills — `"Gems {} / 8"`.
+  *
+  * Empty (the default) means `setText` replaces the whole line. Resolved at
+  * PAINT like `text`, so `"@t:hud.gems"` works and changing locale re-reads
+  * it: the value lives here, the words live in the strings table.
+  */
+  format: string;
   size: number;
   color: string;
   shadow: boolean;
   private last;
+  /** null until something has actually set a value — see `shown`. */
+  private slot;
+  /**
+  * Put a signal's value on screen — `scoreChanged → setText`.
+  *
+  * A `connections[]` handler must be a METHOD and `text` is a property, so the
+  * one wire every game needs (score to screen) could not be declared: every
+  * HUD began with a behavior whose whole job was one assignment.
+  */
+  setText(value: unknown): void;
+  /**
+  * What it actually paints, after the template and the locale.
+  *
+  * Before the first value arrives, a formatted widget shows `text` — its
+  * authored opening line. Filling the slot with nothing instead would put
+  * `"Gems  / 8"` on screen for every game's first frame, and a score line
+  * that starts blank looks broken rather than empty.
+  */
+  get shown(): string;
   protected _build(): HTMLElement;
   protected override _sync(): void;
 }
@@ -245,6 +373,16 @@ declare class UiBar extends HudWidgetBase {
   private lastRatio;
   /** Current fill ratio 0..1 (what the bar shows). */
   get ratio(): number;
+  /**
+  * Drive the bar from a signal — `healthChanged → setValue`.
+  *
+  * Takes the max as a second argument because that is the shape the signal
+  * already has, so a bar whose ceiling moves (a max-HP upgrade) needs no
+  * second wire.
+  */
+  setValue(value: number, max?: number): void;
+  /** Move the ceiling on its own, leaving the fill where it is. */
+  setMax(max: number): void;
   protected _build(): HTMLElement;
   protected override _sync(): void;
 }
@@ -710,4 +848,4 @@ declare function computeViewport(canvasW: number, canvasH: number, viewport: {
 /** Engine version. Kept in sync with package.json by the release pipeline. */
 declare const VERSION: string;
 //#endregion
-export { AudioBuses, type AudioElementLike, AudioPlayer, BASE_LOCALE, Behavior, type BehaviorCtor, type BehaviorState, type BusName, CONST_REF_KEY, type ComputedViewport, type ConnectionJson, type CrossfadeGains, type DebugLineSource, type DeviceHints, Engine, type EngineOptions, type EngineStats, type FindPathOptions, type GameStats, type HudAnchor, HudLayer, IncantoError, type IncantoErrorCode, type IncantoErrorDetails, InputMap, type JsonKind, type JsonObject, type JsonValue, type Listener, type LoadSceneOptions, type LocaleTables, Localization, type LogEntry, type LogLevel, LogManager, type MusicBackend, MusicManager, type MusicTrack, Node, type NodeCtor, type NodeJson, type NodeLifecycle, ORDER_GROUP_BASE, type OrderGroup, type OrderGroupTable, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, type ParsedNodePath, type ParticlePresetValues, ParticleSim, type ParticleSimConfig, type ParticleView, type PathGrid, type PlayMusicOptions, type PreloadResult, type PropDef, type PropSchema, type QualityTier, ROLLOFF_MODELS, type Recorder, type RendererStats, type ReplayEvent, type ReplayJson, type ResolvedRendering, type ResolvedViewport, type RestoreReport, Rng, type RolloffModel, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, type SaveSlot, SaveSlots, type SaveStore, Scene, type SceneJson, SceneTree, type Scheduler, Settings, type SettingsValues, SfxEngine, type SfxParams, type SfxPlayOptions, type SfxWave, Signal, type SignalListener, type SpatialParams, type SynthOptions, T_PREFIX, Timer, TouchControls, type TouchControlsOptions, UiBanner, UiBar, UiButton, UiDialogue, UiImage, UiPanel, UiSelect, UiSlider, UiText, UiToggle, VERSION, type Vec3, type ViewportFit, type Voice, type VoicePreset, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, auditScene, behaviorSchema, behaviorSignals, behaviorsWithoutSave, captureBehaviors, clearBehaviors, clearRegistry, computeViewport, createNode, createNoise2D, createSaveStore, crossfadeGains, duplicateNode, effectiveOrder, fadeGain, findPath, getBehavior, getNodeSchema, getNodeSignals, getNodeType, gridFromRows, isAudioContextAvailable, isConstRef, joystickVector, jsonClone, jsonEquals, jsonKind, loadScene, mergeStaticSignals, newUid, parseNodePath, preloadUrls, qualityEnvironment, readDeviceHints, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, replay, resolveConstants, resolveOrderGroups, resolveRendering, resolveViewport, restoreBehaviors, serializeNode, spatialGain, spatialPan, startRecording, suggestLocale, suggestQuality, synthSfx, translationKey };
+export { type AnimationDef, type AnimationEntry, type AssetFailure, AudioBuses, type AudioElementLike, AudioPlayer, BASE_LOCALE, Behavior, type BehaviorCtor, type BehaviorState, type BusName, CONST_REF_KEY, type ComputedViewport, type ConnectionJson, type CrossfadeGains, type DebugLineSource, type DeviceHints, type DriveScript, type DriveStep, Engine, type EngineOptions, type EngineStats, type FindPathOptions, type GameStats, type GroupedLog, type HudAnchor, HudLayer, IncantoError, type IncantoErrorCode, type IncantoErrorDetails, InputMap, type JsonKind, type JsonObject, type JsonValue, type Listener, type LiveInput, type LiveReport, type LoadSceneOptions, type LocaleTables, Localization, type LogEntry, type LogLevel, LogManager, type MusicBackend, MusicManager, type MusicTrack, Node, type NodeCtor, type NodeJson, type NodeLifecycle, ORDER_GROUP_BASE, type OrderGroup, type OrderGroupTable, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, type ParsedNodePath, type ParticlePresetValues, ParticleSim, type ParticleSimConfig, type ParticleView, type PathGrid, type PlayMusicOptions, type PreloadResult, type PropDef, type PropSchema, type QualityTier, ROLLOFF_MODELS, type Recorder, type RendererStats, type ReplayEvent, type ReplayJson, type ResolvedRendering, type ResolvedViewport, type RestoreReport, Rng, type RolloffModel, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, type SaveSlot, SaveSlots, type SaveStore, Scene, type SceneJson, SceneTree, type Scheduler, Settings, type SettingsValues, SfxEngine, type SfxParams, type SfxPlayOptions, type SfxWave, Signal, type SignalListener, type SpatialParams, type SynthOptions, T_PREFIX, Timer, TouchControls, type TouchControlsOptions, UiBanner, UiBar, UiButton, UiDialogue, UiImage, UiPanel, UiSelect, UiSlider, UiText, UiToggle, VERSION, type Vec3, type ViewportFit, type Voice, type VoicePreset, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, auditScene, behaviorSchema, behaviorSignals, behaviorsWithoutSave, captureBehaviors, clearBehaviors, clearRegistry, computeViewport, createNode, createNoise2D, createSaveStore, crossfadeGains, duplicateNode, effectiveOrder, fadeGain, findPath, getBehavior, getNodeSchema, getNodeSignals, getNodeType, gridFromRows, isAudioContextAvailable, isConstRef, joystickVector, jsonClone, jsonEquals, jsonKind, loadScene, logReport, logText, mergeStaticSignals, newUid, parseDrive, parseNodePath, preloadUrls, qualityEnvironment, readDeviceHints, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, replay, resolveAnimation, resolveConstants, resolveFrames, resolveOrderGroups, resolveRendering, resolveViewport, restoreBehaviors, serializeNode, spatialGain, spatialPan, startRecording, suggestLocale, suggestQuality, synthSfx, translationKey };

package/dist/index.js

@@ -1,13 +1,14 @@
-import { C as getBehavior, E as Signal, S as clearBehaviors, T as registeredBehaviors, _ as InputMap, a as SCENE_FORMAT, b as behaviorSchema, c as SceneTree, d as resolveConstants, f as Node, g as resolveOrderGroups, h as effectiveOrder, i as serializeNode, l as CONST_REF_KEY, m as ORDER_GROUP_BASE, n as loadScene, o as computeViewport, p as parseNodePath, r as Scene, s as resolveViewport, u as isConstRef, w as registerBehavior, x as behaviorSignals, y as Behavior } from "./loader-r49nDwB4.js";
-import { A as T_PREFIX, B as synthSfx, C as behaviorsWithoutSave, D as LogManager, E as createSaveStore, F as ROLLOFF_MODELS, G as AudioBuses, H as WebAudioMusicBackend, I as spatialGain, L as spatialPan, M as translationKey, N as SfxEngine, O as BASE_LOCALE, P as isAudioContextAvailable, R as SFX_PRESETS, S as SaveSlots, T as restoreBehaviors, U as crossfadeGains, V as MusicManager, W as fadeGain, a as UiSlider, b as readDeviceHints, c as UiButton, d as UiBanner, f as UiBar, g as Settings, h as Engine, i as UiSelect, j as suggestLocale, k as Localization, l as UiDialogue, m as AudioPlayer, n as UiImage, o as UiToggle, p as UiText, r as UiPanel, s as Timer, t as registerCoreNodes, u as HudLayer, v as qualityEnvironment, w as captureBehaviors, x as suggestQuality, z as SFX_PRESET_NAMES } from "./register-BSXV8T9F.js";
+import { C as getBehavior, E as Signal, S as clearBehaviors, T as registeredBehaviors, _ as InputMap, a as SCENE_FORMAT, b as behaviorSchema, c as SceneTree, d as resolveConstants, f as Node, g as resolveOrderGroups, h as effectiveOrder, i as serializeNode, l as CONST_REF_KEY, m as ORDER_GROUP_BASE, n as loadScene, o as computeViewport, p as parseNodePath, r as Scene, s as resolveViewport, u as isConstRef, w as registerBehavior, x as behaviorSignals, y as Behavior } from "./loader-DwazzlQb.js";
+import { A as T_PREFIX, B as synthSfx, C as behaviorsWithoutSave, D as LogManager, E as createSaveStore, F as ROLLOFF_MODELS, G as AudioBuses, H as WebAudioMusicBackend, I as spatialGain, L as spatialPan, M as translationKey, N as SfxEngine, O as BASE_LOCALE, P as isAudioContextAvailable, R as SFX_PRESETS, S as SaveSlots, T as restoreBehaviors, U as crossfadeGains, V as MusicManager, W as fadeGain, a as UiSlider, b as readDeviceHints, c as UiButton, d as UiBanner, f as UiBar, g as Settings, h as Engine, i as UiSelect, j as suggestLocale, k as Localization, l as UiDialogue, m as AudioPlayer, n as UiImage, o as UiToggle, p as UiText, r as UiPanel, s as Timer, t as registerCoreNodes, u as HudLayer, v as qualityEnvironment, w as captureBehaviors, x as suggestQuality, z as SFX_PRESET_NAMES } from "./register-uvaZj1KX.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
-import { n as startRecording, r as auditScene, t as replay } from "./replay-DilbZgQI.js";
+import { n as startRecording, r as auditScene, t as replay } from "./replay-C0XJIsO7.js";
 import { n as jsonEquals, r as jsonKind, t as jsonClone } from "./json-BLk7H2Qa.js";
 import { a as getNodeSignals, c as mergeStaticSignals, i as getNodeSchema, l as registerNode, n as clearRegistry, o as getNodeType, r as createNode, u as registeredTypes } from "./registry-IyWCGe4q.js";
+import { n as logText, r as parseDrive, t as logReport } from "./log-report-lxrQY9cH.js";
 import { t as createNoise2D } from "./noise-CGUMx44x.js";
-import { i as applyParticlePreset, n as PARTICLE_PRESETS, r as PARTICLE_PRESET_NAMES, t as ParticleSim } from "./particle-sim-Bw7hB93B.js";
-import { a as findPath, i as preloadUrls, n as newUid, o as gridFromRows, r as assetUrls, t as VERSION } from "./src-Ca3oV1fe.js";
+import { a as PARTICLE_PRESETS, i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-D_p28jwU.js";
+import { a as findPath, i as preloadUrls, n as newUid, o as gridFromRows, r as assetUrls, t as VERSION } from "./src-DF4gCsqO.js";
 import { i as resolveRendering, n as attachTouchControls, r as joystickVector, t as TouchControls } from "./touch-BoNg_MnF.js";
-import { t as duplicateNode } from "./duplicate-CRtihGmC.js";
-export { AudioBuses, AudioPlayer, BASE_LOCALE, Behavior, CONST_REF_KEY, Engine, HudLayer, IncantoError, InputMap, Localization, LogManager, MusicManager, Node, ORDER_GROUP_BASE, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, ParticleSim, ROLLOFF_MODELS, Rng, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, SaveSlots, Scene, SceneTree, Settings, SfxEngine, Signal, T_PREFIX, Timer, TouchControls, UiBanner, UiBar, UiButton, UiDialogue, UiImage, UiPanel, UiSelect, UiSlider, UiText, UiToggle, VERSION, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, auditScene, behaviorSchema, behaviorSignals, behaviorsWithoutSave, captureBehaviors, clearBehaviors, clearRegistry, computeViewport, createNode, createNoise2D, createSaveStore, crossfadeGains, duplicateNode, effectiveOrder, fadeGain, findPath, getBehavior, getNodeSchema, getNodeSignals, getNodeType, gridFromRows, isAudioContextAvailable, isConstRef, joystickVector, jsonClone, jsonEquals, jsonKind, loadScene, mergeStaticSignals, newUid, parseNodePath, preloadUrls, qualityEnvironment, readDeviceHints, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, replay, resolveConstants, resolveOrderGroups, resolveRendering, resolveViewport, restoreBehaviors, serializeNode, spatialGain, spatialPan, startRecording, suggestLocale, suggestQuality, synthSfx, translationKey };
+import { t as duplicateNode } from "./duplicate-CI9WF_bg.js";
+export { AudioBuses, AudioPlayer, BASE_LOCALE, Behavior, CONST_REF_KEY, Engine, HudLayer, IncantoError, InputMap, Localization, LogManager, MusicManager, Node, ORDER_GROUP_BASE, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, ParticleSim, ROLLOFF_MODELS, Rng, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, SaveSlots, Scene, SceneTree, Settings, SfxEngine, Signal, T_PREFIX, Timer, TouchControls, UiBanner, UiBar, UiButton, UiDialogue, UiImage, UiPanel, UiSelect, UiSlider, UiText, UiToggle, VERSION, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, auditScene, behaviorSchema, behaviorSignals, behaviorsWithoutSave, captureBehaviors, clearBehaviors, clearRegistry, computeViewport, createNode, createNoise2D, createSaveStore, crossfadeGains, duplicateNode, effectiveOrder, fadeGain, findPath, getBehavior, getNodeSchema, getNodeSignals, getNodeType, gridFromRows, isAudioContextAvailable, isConstRef, joystickVector, jsonClone, jsonEquals, jsonKind, loadScene, logReport, logText, mergeStaticSignals, newUid, parseDrive, parseNodePath, preloadUrls, qualityEnvironment, readDeviceHints, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, replay, resolveAnimation, resolveConstants, resolveFrames, resolveOrderGroups, resolveRendering, resolveViewport, restoreBehaviors, serializeNode, spatialGain, spatialPan, startRecording, suggestLocale, suggestQuality, synthSfx, translationKey };

package/dist/{loader-r49nDwB4.js → loader-DwazzlQb.js}

@@ -1606,13 +1606,17 @@ function wireConnections(root, connections, declareSignals = false) {
 		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;
+			try {
+				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);
+			} catch (error) {
+				quarantineWire(fromNode, toNode, conn, listener, error);
 			}
-			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);
@@ -1622,6 +1626,32 @@ function wireConnections(root, connections, declareSignals = false) {
 		}
 	}
 }
+/**
+* A handler threw. Turn THAT WIRE off, and leave the game running.
+*
+* The engine already draws this line for scripts: "a behavior is your code; the
+* node is the engine's. A typo in the first must not switch off the second, or
+* breaking a sword script stops the character from walking." A connection is
+* the same category — authored wiring, not the emitting node's own logic — and
+* it behaved the opposite way, because the handler runs inside `Signal.emit`
+* and its exception surfaces in whoever EMITTED. The node quarantine then blames
+* and skips that node, so a `movementStateChanged → play` wire naming a clip the
+* sheet does not have switched off the character controller: no animation, and
+* no movement either.
+*
+* Reported ONCE and disconnected, on the same reasoning as the node quarantine:
+* a handler that throws throws every frame, and sixty identical traces a second
+* bury the one line that matters.
+*/
+function quarantineWire(fromNode, toNode, conn, listener, error) {
+	fromNode.off(conn.signal, listener);
+	const target = toNode.behavior ? `'${conn.handler}' on behavior '${toNode.script?.name}' (${toNode.getPath()})` : `'${conn.handler}' on ${toNode.getPath()}`;
+	const message = `[incanto] connection '${conn.signal}' from ${fromNode.getPath()} → handler ${target} threw — THIS WIRE is now off; the node that emitted the signal, and the rest of the scene, keep running.`;
+	const engine = toNode.tree?.engine ?? fromNode.tree?.engine;
+	engine?.log.error(message, error);
+	engine?._nodeErrored(toNode);
+	console.error(message, error);
+}
 function resolveEndpoint(root, path, conn, side) {
 	try {
 		return root.getNode(path);

package/dist/net.js

@@ -1,9 +1,9 @@
-import { n as loadScene } from "./loader-r49nDwB4.js";
-import { h as Engine } from "./register-BSXV8T9F.js";
+import { n as loadScene } from "./loader-DwazzlQb.js";
+import { h as Engine } from "./register-uvaZj1KX.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as jsonClone } from "./json-BLk7H2Qa.js";
 import { n as createAgent8Server } from "./agent8-CvsfVskX.js";
-import { i as applySyncPatch, n as NetworkSpawner, r as NetworkManager, t as registerNodesNet } from "./register-D651it1J.js";
+import { i as applySyncPatch, n as NetworkSpawner, r as NetworkManager, t as registerNodesNet } from "./register-CB11yp21.js";
 //#region src/net/loopback.ts
 /**
 * In-memory multiplayer hub implementing the SAME kernel contract as

package/dist/{physics-2d-BmgXBNDB.js → physics-2d-vyCBfACH.js}

@@ -1,7 +1,7 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { v as diagnose } from "./loader-r49nDwB4.js";
+import { v as diagnose } from "./loader-DwazzlQb.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { _ as RigidBody2D, b as validateCollider2D, g as PhysicsBody2D, h as CharacterBody2D, m as Area2D, p as Joint2D, y as Node2D } from "./register-R2JTnIMw.js";
+import { _ as RigidBody2D, b as validateCollider2D, g as PhysicsBody2D, h as CharacterBody2D, m as Area2D, p as Joint2D, y as Node2D } from "./register-BNPZYJmd.js";
 import { n as registerDebugSource } from "./debug-draw-BM3DsvtT.js";
 //#region src/2d/physics/physics-2d.ts
 var physics_2d_exports = /* @__PURE__ */ __exportAll({
@@ -122,7 +122,7 @@ var Physics2D = class {
 	moveAndSlide(node) {
 		const e = this.ensureEntry(node);
 		const vy = node.velocity[1] ?? 0;
-		if (node.snapToGround && vy >= 0) this.kcc.enableSnapToGround(.05);
+		if (node.stickToGround && vy >= 0) this.kcc.enableSnapToGround(.05);
 		else this.kcc.disableSnapToGround();
 		this.kcc.setMaxSlopeClimbAngle(node.slopeLimitDeg * DEG);
 		let carryX = 0;

package/dist/{physics-3d-CSoGjM8P.js → physics-3d-DpRqw8Mz.js}

@@ -1,9 +1,9 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { v as diagnose } from "./loader-r49nDwB4.js";
+import { v as diagnose } from "./loader-DwazzlQb.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { F as PhysicsBody3D, I as RigidBody3D, N as Area3D, P as CharacterBody3D, R as Node3D, z as validateCollider3D } from "./gameplay-BQOeAid6.js";
+import { F as PhysicsBody3D, I as RigidBody3D, N as Area3D, P as CharacterBody3D, R as Node3D, z as validateCollider3D } from "./gameplay-02Btmmjn.js";
 import { n as registerDebugSource } from "./debug-draw-BM3DsvtT.js";
-import { A as Terrain3D, F as InstancedMesh3D, L as buildMeshGeometry, P as Joint3D } from "./environment-presets-D1b0ydTS.js";
+import { A as Terrain3D, F as InstancedMesh3D, L as buildMeshGeometry, P as Joint3D } from "./environment-presets-CZOH5TY5.js";
 import { Euler, Matrix4, Quaternion, Vector3 } from "three";
 //#region src/3d/physics/collider-lines.ts
 /**
@@ -373,7 +373,7 @@ var Physics3D = class {
 		const e = this.ensureEntry(node);
 		if (!e) return;
 		const vy = node.velocity[1] ?? 0;
-		if (node.snapToGround && vy <= 0) this.kcc.enableSnapToGround(.1);
+		if (node.stickToGround && vy <= 0) this.kcc.enableSnapToGround(.1);
 		else this.kcc.disableSnapToGround();
 		this.kcc.setMaxSlopeClimbAngle(node.slopeLimitDeg * DEG);
 		let carryX = 0;

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-D16MVIPO.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-CniOiWzN.js").then((n) => n.n)).createGame2D(o)))(opts);
+			const next = await (_gameFactory ?? (mode === "3d" ? async (o) => (await import("./create-game-DFBjMetZ.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-BgV6UbVA.js").then((n) => n.n)).createGame2D(o)))(opts);
 			if (disposed) {
 				next.dispose();
 				return;

package/dist/{register-R2JTnIMw.js → register-BNPZYJmd.js}

@@ -1,9 +1,9 @@
-import { f as Node, h as effectiveOrder } from "./loader-r49nDwB4.js";
-import { t as registerCoreNodes } from "./register-BSXV8T9F.js";
+import { f as Node, h as effectiveOrder } from "./loader-DwazzlQb.js";
+import { t as registerCoreNodes } from "./register-uvaZj1KX.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-IyWCGe4q.js";
-import { i as applyParticlePreset, r as PARTICLE_PRESET_NAMES, t as ParticleSim } from "./particle-sim-Bw7hB93B.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-D_p28jwU.js";
 import { AdditiveBlending, BufferAttribute, BufferGeometry, CanvasTexture, Color, DynamicDrawUsage, Group, InstancedMesh, MathUtils, Matrix4, Mesh, MeshBasicMaterial, NearestFilter, NormalBlending, Object3D, PlaneGeometry } from "three";
 //#region src/2d/physics/collider-validate.ts
 /**
@@ -198,13 +198,19 @@ var CharacterBody2D = class extends PhysicsBody2D {
 	static typeName = "CharacterBody2D";
 	static props = {
 		velocity: { default: [0, 0] },
-		snapToGround: { default: true },
+		stickToGround: { default: true },
 		slopeLimitDeg: { default: 45 }
 	};
+	/**
+	* Renamed to match the 3D body, where `snapToGround` had to give the name
+	* back to `Node3D`'s PLACEMENT prop. 2D has no placement prop, so nothing is
+	* ambiguous here and old scenes keep loading unchanged.
+	*/
+	static propAliases = { snapToGround: "stickToGround" };
 	/** px/s, y-down (up = -y). */
 	velocity = [0, 0];
 	/** Keep contact on slopes/steps while not moving upward. */
-	snapToGround = true;
+	stickToGround = true;
 	/** Max climbable slope angle. */
 	slopeLimitDeg = 45;
 	/** @internal Updated by Physics2D.moveAndSlide. */
@@ -402,13 +408,19 @@ var AnimatedSprite2D = class extends Sprite2D {
 	frameList = [];
 	frameIndex = 0;
 	frameTime = 0;
+	currentDef = null;
 	ownTexture = null;
 	loadedSheetRef = "";
+	/**
+	* `currentAnimation` reports the clip that is RUNNING, not the name asked
+	* for: an alias is a rename, and a state machine that reads back `fall` while
+	* the idle frames play is describing something that is not happening.
+	*/
 	play(name) {
-		const def = this.animations[name];
-		if (!def) throw new IncantoError("UNKNOWN_ANIMATION", `No animation '${name}' on '${this.name}'. Available: [${Object.keys(this.animations).join(", ")}].`);
-		this.currentAnimation = name;
-		this.frameList = resolveFrames(def.frames, name);
+		const { name: resolved, def } = resolveAnimation(this.animations, name, this.name);
+		this.currentAnimation = resolved;
+		this.currentDef = def;
+		this.frameList = resolveFrames(def.frames, resolved);
 		this.frameIndex = 0;
 		this.currentFrame = this.frameList[0] ?? 0;
 		this.frameTime = 0;
@@ -418,11 +430,12 @@ var AnimatedSprite2D = class extends Sprite2D {
 		this.playing = false;
 	}
 	onReady() {
+		validateAnimationAliases(this.animations, this.name);
 		if (this.autoplay) this.play(this.autoplay);
 	}
 	update(dt) {
 		if (!this.playing || this.currentAnimation === "") return;
-		const def = this.animations[this.currentAnimation];
+		const def = this.currentDef;
 		if (!def || !Number.isFinite(def.fps) || def.fps <= 0) return;
 		const perFrame = 1 / def.fps;
 		this.frameTime += dt;
@@ -462,18 +475,6 @@ var AnimatedSprite2D = class extends Sprite2D {
 		};
 	}
 };
-function resolveFrames(frames, name) {
-	if (!Array.isArray(frames) || frames.length === 0) throw new IncantoError("BAD_FORMAT", `Animation '${name}': "frames" must be a non-empty array.`);
-	if (frames.length === 2) {
-		const [start, end] = frames;
-		if (end >= start) {
-			const out = [];
-			for (let f = start; f <= end; f++) out.push(f);
-			return out;
-		}
-	}
-	return [...frames];
-}
 //#endregion
 //#region src/2d/nodes/camera-2d.ts
 /**

package/dist/{register-D651it1J.js → register-CB11yp21.js}

@@ -1,5 +1,5 @@
-import { E as Signal, f as Node, t as buildNodeJson } from "./loader-r49nDwB4.js";
-import { t as registerCoreNodes } from "./register-BSXV8T9F.js";
+import { E as Signal, f as Node, t as buildNodeJson } from "./loader-DwazzlQb.js";
+import { t as registerCoreNodes } from "./register-uvaZj1KX.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { n as jsonEquals, t as jsonClone } from "./json-BLk7H2Qa.js";
 import { l as registerNode } from "./registry-IyWCGe4q.js";

package/dist/{register-BSXV8T9F.js → register-uvaZj1KX.js}

@@ -1,4 +1,4 @@
-import { E as Signal, _ as InputMap, b as behaviorSchema, f as Node, g as resolveOrderGroups, m as ORDER_GROUP_BASE, v as diagnose } from "./loader-r49nDwB4.js";
+import { E as Signal, _ as InputMap, b as behaviorSchema, f as Node, g as resolveOrderGroups, m as ORDER_GROUP_BASE, v as diagnose } from "./loader-DwazzlQb.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
 import { l as registerNode } from "./registry-IyWCGe4q.js";
@@ -2558,28 +2558,73 @@ var UiText = class extends HudWidgetBase {
 	static props = {
 		...HudWidgetBase.props,
 		text: { default: "" },
+		format: { default: "" },
 		size: { default: 16 },
 		color: { default: "#ffffff" },
 		shadow: { default: true }
 	};
 	text = "";
+	/**
+	* A template with a `{}` slot that `setText` fills — `"Gems {} / 8"`.
+	*
+	* Empty (the default) means `setText` replaces the whole line. Resolved at
+	* PAINT like `text`, so `"@t:hud.gems"` works and changing locale re-reads
+	* it: the value lives here, the words live in the strings table.
+	*/
+	format = "";
 	size = 16;
 	color = "#ffffff";
 	shadow = true;
 	last = "\0";
+	/** null until something has actually set a value — see `shown`. */
+	slot = null;
+	/**
+	* Put a signal's value on screen — `scoreChanged → setText`.
+	*
+	* A `connections[]` handler must be a METHOD and `text` is a property, so the
+	* one wire every game needs (score to screen) could not be declared: every
+	* HUD began with a behavior whose whole job was one assignment.
+	*/
+	setText(value) {
+		this.slot = String(value ?? "");
+		if (!this.format) this.text = this.slot;
+	}
+	/**
+	* What it actually paints, after the template and the locale.
+	*
+	* Before the first value arrives, a formatted widget shows `text` — its
+	* authored opening line. Filling the slot with nothing instead would put
+	* `"Gems  / 8"` on screen for every game's first frame, and a score line
+	* that starts blank looks broken rather than empty.
+	*/
+	get shown() {
+		if (this.format && this.slot !== null) return this._t(this.format).replace("{}", this.slot);
+		return this._t(this.text);
+	}
 	_build() {
 		const el = document.createElement("div");
 		el.style.cssText = `font-size:${this.size}px;color:${this.color};${this.shadow ? "text-shadow:0 1px 3px rgba(0,0,0,.7);" : ""}white-space:pre;`;
 		return el;
 	}
 	_sync() {
-		const shown = this._t(this.text);
+		const shown = this.shown;
 		if (shown !== this.last && this._element) {
 			this.last = shown;
 			this._element.textContent = shown;
 		}
 	}
 };
+/**
+* A bar fed the wrong argument shows a plausible wrong number forever.
+*
+* The trap is one signal away: `Health.damaged` is `(amount, current)`, so
+* wiring it to `setValue` paints the DAMAGE as the health and looks like a
+* working health bar. Say which signal has the shape a bar wants.
+*/
+function requireNumber(value, node, method) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	throw new IncantoError("PROP_TYPE_MISMATCH", `UiBar '${node.getPath()}'.${method} needs a number, got ${JSON.stringify(value)}. Check what the wired signal passes FIRST — 'damaged' is (amount, current), 'healthChanged' is (current, max), which is the shape a bar wants.`);
+}
 /** A labeled progress bar (health, stamina, reload, boss HP). */
 var UiBar = class extends HudWidgetBase {
 	static typeName = "UiBar";
@@ -2612,6 +2657,21 @@ var UiBar = class extends HudWidgetBase {
 	get ratio() {
 		return this.max > 0 ? Math.min(1, Math.max(0, this.value / this.max)) : 0;
 	}
+	/**
+	* Drive the bar from a signal — `healthChanged → setValue`.
+	*
+	* Takes the max as a second argument because that is the shape the signal
+	* already has, so a bar whose ceiling moves (a max-HP upgrade) needs no
+	* second wire.
+	*/
+	setValue(value, max) {
+		this.value = requireNumber(value, this, "setValue");
+		if (max !== void 0) this.max = requireNumber(max, this, "setValue");
+	}
+	/** Move the ceiling on its own, leaving the fill where it is. */
+	setMax(max) {
+		this.max = requireNumber(max, this, "setMax");
+	}
 	_build() {
 		const wrap = document.createElement("div");
 		wrap.style.cssText = "display:flex;align-items:center;gap:6px;";

package/dist/{replay-DilbZgQI.js → replay-C0XJIsO7.js}

@@ -1,4 +1,4 @@
-import { M as translationKey } from "./register-BSXV8T9F.js";
+import { M as translationKey } from "./register-uvaZj1KX.js";
 //#region src/core/audit.ts
 const ANIMATED_TYPES = new Set([
 	"Particles2D",

package/dist/sprite-animation-CMr6f1K2.d.ts

@@ -0,0 +1,44 @@
+//#region src/core/sprite-animation.d.ts
+interface AnimationDef {
+  /**
+  * Two numbers = inclusive [start, end] frame RANGE.
+  * Any other length = explicit frame list.
+  */
+  frames: number[];
+  fps: number;
+  loop?: boolean;
+}
+/**
+* A clip, or the NAME of another clip in the same map.
+*
+* The alias exists because the character a game is built from and the character
+* a controller describes are not the same vocabulary.
+* `CharacterController2D`/`3D` emit `idle`/`run`/`jump`/`fall`/`wallSlide`/
+* `dash`; the sheets in the engine's own catalog carry `idle`/`move`/`attack`,
+* and no sheet anywhere ships a `fall`. So the documented one-line wiring —
+* `movementStateChanged → play` — asked for clips that do not exist, and the
+* hard error was correct and useless: there is nothing to rename it TO.
+*
+* An alias is the missing half. `"fall": "idle"` says what to show while
+* falling, in the scene, next to everything else about that character.
+*/
+type AnimationEntry = AnimationDef | string;
+/**
+* Follow aliases to the clip that actually plays.
+*
+* Chains are allowed (`fall → jump → idle`) because they are how a fallback
+* ladder reads, and a cycle is a hard error rather than a hang.
+*/
+declare function resolveAnimation(animations: Record<string, AnimationEntry>, name: string, owner: string): {
+  name: string;
+  def: AnimationDef;
+};
+/**
+* `[start, end]` is a RANGE; anything else is an explicit list.
+*
+* Two ascending numbers are overwhelmingly a range in every sheet format, and
+* a two-frame flip-book is spelled `[3, 3, 4, 4]` or a descending pair.
+*/
+declare function resolveFrames(frames: number[], name: string): number[];
+//#endregion
+export { resolveFrames as i, AnimationEntry as n, resolveAnimation as r, AnimationDef as t };