incanto 0.7.1 → 0.8.0

package/dist/gameplay.js

@@ -1,2 +1,2 @@
-import { C as Health, S as DamageOnContact, T as Chase, _ as screenFlash, a as Wander, b as restartScene, c as Projectile, d as Oscillate, f as MoveTo, g as hitStop, h as Cooldown, i as WaveSpawner, l as Pickup, m as CameraShake, n as registerGameplayBehaviors, o as Spawner, p as Lifetime, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as Patrol, v as Interactable, w as Collector, x as FollowCamera, y as GameFlow } from "./gameplay-CDFgSG6z.js";
-export { CameraShake, Chase, Collector, Cooldown, DamageOnContact, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, Health, Interactable, Lifetime, MoveTo, Oscillate, Patrol, Pickup, Projectile, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, hitStop, registerGameplayBehaviors, restartScene, screenFlash };
+import { C as FollowCamera, D as Chase, E as Collector, S as restartScene, T as Health, _ as hitStop, a as Wander, b as GameFlow, c as Projectile, d as PathFollow, f as Oscillate, g as Cooldown, h as CameraShake, i as WaveSpawner, l as Pickup, m as Lifetime, n as registerGameplayBehaviors, o as Spawner, p as MoveTo, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as Patrol, v as screenFlash, w as DamageOnContact, x as goToScene, y as Interactable } from "./gameplay-DPMgZk9W.js";
+export { CameraShake, Chase, Collector, Cooldown, DamageOnContact, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, Projectile, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, registerGameplayBehaviors, restartScene, screenFlash };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 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-CcoWb32N.js";
-import { $ as Signal, A as SfxPlayOptions, B as SFX_PRESET_NAMES, C as RendererStats, D as LogManager, E as LogLevel, F as SpatialParams, G as MusicBackend, H as SfxWave, I as Vec3, J as PlayMusicOptions, K as MusicManager, L as spatialGain, M as Listener, N as ROLLOFF_MODELS, O as InputMap, P as RolloffModel, Q as NodeLifecycle, R as spatialPan, S as GameStats, T as LogEntry, U as SynthOptions, V as SfxParams, W as synthSfx, X as BusName, Y as AudioBuses, Z as Node, _ as registeredTypes, a as registerBehavior, b as Scheduler, c as PropDef, d as createNode, et as SignalListener, f as getNodeSchema, g as registerNode, h as mergeStaticSignals, i as getBehavior, j as isAudioContextAvailable, k as SfxEngine, l as PropSchema, m as getNodeType, n as BehaviorCtor, o as registeredBehaviors, p as getNodeSignals, q as MusicTrack, r as clearBehaviors, s as NodeCtor, t as Behavior, tt as SceneTree, u as clearRegistry, v as Engine, w as Scene, x as EngineStats, y as EngineOptions, z as SFX_PRESETS } from "./behavior-q3cejJgs.js";
-import { n as loadScene, t as LoadSceneOptions } from "./loader-DnLMMRy8.js";
+import { $ as Node, A as SfxPlayOptions, B as spatialPan, C as RendererStats, D as LogManager, E as LogLevel, F as ROLLOFF_MODELS, G as SynthOptions, H as SFX_PRESET_NAMES, I as RolloffModel, J as MusicManager, K as synthSfx, L as SpatialParams, M as Voice, N as VoicePreset, O as InputMap, P as Listener, Q as BusName, R as Vec3, S as GameStats, T as LogEntry, U as SfxParams, V as SFX_PRESETS, W as SfxWave, X as PlayMusicOptions, Y as MusicTrack, Z as AudioBuses, _ as registeredTypes, a as registerBehavior, b as Scheduler, c as PropDef, d as createNode, et as NodeLifecycle, f as getNodeSchema, g as registerNode, h as mergeStaticSignals, i as getBehavior, j as isAudioContextAvailable, k as SfxEngine, l as PropSchema, m as getNodeType, n as BehaviorCtor, nt as SignalListener, o as registeredBehaviors, p as getNodeSignals, q as MusicBackend, r as clearBehaviors, rt as SceneTree, s as NodeCtor, t as Behavior, tt as Signal, u as clearRegistry, v as Engine, w as Scene, x as EngineStats, y as EngineOptions, z as spatialGain } from "./behavior-Bod1AyJS.js";
+import { n as loadScene, t as LoadSceneOptions } from "./loader-BcUDfNHn.js";
 import { n as ParticleSimConfig, r as ParticleView, t as ParticleSim } from "./particle-sim-CwJ5rI_P.js";
-import { n as AudioPlayer, t as AudioElementLike } from "./audio-player-C3bH_eZ5.js";
-import { n as IncantoErrorCode, r as IncantoErrorDetails, t as IncantoError } from "./errors-BMFaY68Q.js";
+import { n as AudioPlayer, t as AudioElementLike } from "./audio-player-Dyjg5k92.js";
+import { i as auditScene, n as IncantoErrorCode, r as IncantoErrorDetails, t as IncantoError } from "./errors-1dXlIwoR.js";
 
 //#region src/core/audio/crossfade.d.ts
 /**
@@ -114,7 +114,7 @@ declare class HudLayer extends Node {
   _slot(anchor: HudAnchor): HTMLElement | null;
 }
 /** Shared plumbing: mount into the parent HudLayer's anchor slot. */
-declare abstract class HudWidget extends Node {
+declare abstract class HudWidgetBase extends Node {
   static readonly props: PropSchema;
   anchor: HudAnchor;
   visible: boolean;
@@ -128,7 +128,7 @@ declare abstract class HudWidget extends Node {
   protected _sync(): void;
 }
 /** A text line (score, timer, hints). Set `.text` from behaviors. */
-declare class UiText extends HudWidget {
+declare class UiText extends HudWidgetBase {
   static override readonly typeName: string;
   static override readonly props: PropSchema;
   text: string;
@@ -140,7 +140,7 @@ declare class UiText extends HudWidget {
   protected override _sync(): void;
 }
 /** A labeled progress bar (health, stamina, reload, boss HP). */
-declare class UiBar extends HudWidget {
+declare class UiBar extends HudWidgetBase {
   static override readonly typeName: string;
   static override readonly props: PropSchema;
   value: number;
@@ -164,7 +164,7 @@ declare class UiBar extends HudWidget {
 * in/out and a queue — call `.show(text, { color, seconds })`; `sticky:true`
 * (seconds: 0) keeps it until the next show(). Emits `bannerShown(text)`.
 */
-declare class UiBanner extends HudWidget {
+declare class UiBanner extends HudWidgetBase {
   static override readonly typeName: string;
   static readonly signals: string[];
   static override readonly props: PropSchema;
@@ -187,6 +187,75 @@ declare class UiBanner extends HudWidget {
   override update(dt: number): void;
 }
 //#endregion
+//#region src/core/nodes/dialogue.d.ts
+/**
+* Interactive HUD: clickable buttons and a typewriter dialogue box — the
+* storytelling layer RPG/adventure games kept hand-rolling in DOM.
+* Same family as the other HUD widgets: children of a HudLayer, DOM-backed,
+* silent no-ops headless.
+*/
+/** A clickable button (menus, "START", dialog choices). Emits `pressed`. */
+declare class UiButton extends HudWidgetBase {
+  static override readonly typeName: string;
+  static readonly signals: readonly string[];
+  static override readonly props: PropSchema;
+  text: string;
+  size: number;
+  color: string;
+  background: string;
+  disabled: boolean;
+  private lastText;
+  /** Programmatic press — same path as a click (tests, gamepad menus). */
+  press(): void;
+  protected _build(): HTMLElement;
+  protected override _sync(): void;
+}
+/**
+* A typewriter dialogue box with a queue and choices:
+*
+*   const talk = node.getNode('%Dialogue') as UiDialogue;
+*   talk.say('Elder', 'Welcome to Lumina Village...');
+*   talk.say('Elder', 'Will you help us?', ['Yes', 'No']);
+*   talk.on('choiceMade', (index) => { ... });
+*
+* Click / `advance()` reveals the full line, then advances. Emits
+* `lineShown(text)`, `choiceMade(index)`, `dialogueFinished()`.
+*/
+declare class UiDialogue extends HudWidgetBase {
+  static override readonly typeName: string;
+  static readonly signals: readonly string[];
+  static override readonly props: PropSchema;
+  override anchor: HudAnchor;
+  /** Typewriter speed; 0 = instant lines. */
+  charsPerSecond: number;
+  width: number;
+  private queue;
+  private current;
+  private revealed;
+  private speakerEl;
+  private textEl;
+  private choicesEl;
+  private hintEl;
+  /** True while a conversation is on screen (pause player input on this). */
+  get active(): boolean;
+  /** What the box currently shows (grows while typing) — test-friendly. */
+  get showing(): string;
+  /** Queue a line; optional `choices` renders buttons after the line types out. */
+  say(speaker: string, text: string, choices?: string[]): void;
+  /**
+  * Player pressed "next": mid-typing reveals the whole line; a fully-typed
+  * line without choices advances (choice lines wait for `choose`).
+  */
+  advance(): void;
+  /** Pick a choice on the current line (buttons call this). */
+  choose(index: number): void;
+  /** Drop the conversation (cutscene interrupts). */
+  clear(): void;
+  private next;
+  protected _build(): HTMLElement;
+  override update(dt: number): void;
+}
+//#endregion
 //#region src/core/nodes/timer.d.ts
 /**
 * The canonical serializable game clock — never `setTimeout` in game logic.
@@ -267,6 +336,33 @@ declare const PARTICLE_PRESET_NAMES: readonly string[];
 */
 declare function applyParticlePreset(target: Record<string, unknown>, presetName: string, schema: PropSchema): void;
 //#endregion
+//#region src/core/pathfinding.d.ts
+/**
+* Grid A* — the pathfinding every top-down/RPG/tower-defense asks for and
+* agents keep re-inventing badly. Pure and dimension-free: cells in, cells
+* out; the caller maps cells to world units (px, meters, tiles).
+*/
+interface PathGrid {
+  width: number;
+  height: number;
+  /** True = impassable. Out-of-bounds is always solid. */
+  solid(x: number, y: number): boolean;
+}
+interface FindPathOptions {
+  /** Allow diagonal steps (blocked from cutting corners). Default true. */
+  diagonal?: boolean;
+  /** Abort guard for huge/impossible searches. Default 20000 nodes. */
+  maxExpansions?: number;
+}
+/**
+* A* from `from` to `to` (inclusive cell coords). Returns the cell path
+* INCLUDING both endpoints, or null when unreachable. Straight steps cost
+* 1, diagonals √2; the heuristic is octile (admissible for both modes).
+*/
+declare function findPath(grid: PathGrid, from: [number, number], to: [number, number], opts?: FindPathOptions): [number, number][] | null;
+/** Build a PathGrid from row-strings ('#' = solid) — tests and tile games. */
+declare function gridFromRows(rows: readonly string[]): PathGrid;
+//#endregion
 //#region src/core/preload.d.ts
 interface PreloadResult {
   /** Urls whose fetch failed — show an error UI instead of pretending success. */
@@ -310,6 +406,52 @@ declare function resolveRendering(environment: JsonObject | undefined, fallback:
   pixelRatio?: number;
 }): ResolvedRendering;
 //#endregion
+//#region src/core/replay.d.ts
+/**
+* Deterministic input replay — the engine already runs on a seeded RNG and
+* an injectable clock, so a recording of (tick timestamps + input events)
+* replays BIT-IDENTICALLY into a fresh engine with the same seed and scene.
+* That turns "does my game still work?" into an assertion an agent can run
+* headlessly: record once while playing, replay forever as a regression.
+*
+*   const rec = startRecording(engine);            // play the game...
+*   const replayJson = rec.stop();                 // ...save this JSON
+*
+*   const fresh = new Engine({ seed: SAME_SEED }); // same seed + scene JSON
+*   fresh.setScene(loadScene(sceneJson));
+*   replay(fresh, replayJson);                     // now assert game state
+*
+* Caveats (documented, by design): game code must use `engine.rng` (not
+* Math.random) and dt/engine.time (not Date.now) — the engine's own rules.
+* Gamepad polling is not recorded (bind pads to actions; actions replay).
+*/
+/** [tickIndex, methodName, ...primitive args] */
+type ReplayEvent = [number, string, ...(string | number | boolean)[]];
+interface ReplayJson {
+  /** File-format marker for forward compatibility. */
+  replay: 1;
+  /** Tick timestamps (ms) exactly as the loop delivered them. */
+  ticks: number[];
+  events: ReplayEvent[];
+}
+interface Recorder {
+  /** Detach the taps and return the recording. */
+  stop(): ReplayJson;
+}
+/**
+* Tap the engine's input entry points and tick clock. Recording starts at
+* the CURRENT moment — start it before the first tick for full-run replays.
+*/
+declare function startRecording(engine: Engine): Recorder;
+/**
+* Drive a fresh engine through a recording: for each recorded tick, feed
+* that tick's input events first, then tick with the recorded timestamp.
+* `onTick(index)` lets tests assert mid-run state.
+*/
+declare function replay(engine: Engine, recording: ReplayJson, opts?: {
+  onTick?: (index: number) => void;
+}): void;
+//#endregion
 //#region src/core/save.d.ts
 /**
 * Namespaced game persistence — high scores, unlocks, settings. localStorage
@@ -453,4 +595,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, Behavior, type BehaviorCtor, type BusName, CONST_REF_KEY, type ComputedViewport, type ConnectionJson, type CrossfadeGains, type DebugLineSource, Engine, type EngineOptions, type EngineStats, type GameStats, type HudAnchor, HudLayer, IncantoError, type IncantoErrorCode, type IncantoErrorDetails, InputMap, type JsonKind, type JsonObject, type JsonValue, type Listener, type LoadSceneOptions, type LogEntry, type LogLevel, LogManager, type MusicBackend, MusicManager, type MusicTrack, Node, type NodeCtor, type NodeJson, type NodeLifecycle, ORDER_GROUP_BASE, type OrderGroup, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, type ParsedNodePath, type ParticlePresetValues, ParticleSim, type ParticleSimConfig, type ParticleView, type PlayMusicOptions, type PreloadResult, type PropDef, type PropSchema, ROLLOFF_MODELS, type RendererStats, type ResolvedRendering, type ResolvedViewport, Rng, type RolloffModel, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, type SaveStore, Scene, type SceneJson, SceneTree, type Scheduler, SfxEngine, type SfxParams, type SfxPlayOptions, type SfxWave, Signal, type SignalListener, type SpatialParams, type SynthOptions, Timer, TouchControls, type TouchControlsOptions, UiBanner, UiBar, UiText, VERSION, type Vec3, type ViewportFit, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, clearBehaviors, clearRegistry, computeViewport, createNode, createNoise2D, createSaveStore, crossfadeGains, duplicateNode, effectiveOrder, fadeGain, getBehavior, getNodeSchema, getNodeSignals, getNodeType, isAudioContextAvailable, isConstRef, joystickVector, jsonClone, jsonEquals, jsonKind, loadScene, mergeStaticSignals, newUid, parseNodePath, preloadUrls, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, resolveConstants, resolveRendering, resolveViewport, serializeNode, spatialGain, spatialPan, synthSfx };
+export { AudioBuses, type AudioElementLike, AudioPlayer, Behavior, type BehaviorCtor, type BusName, CONST_REF_KEY, type ComputedViewport, type ConnectionJson, type CrossfadeGains, type DebugLineSource, 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 LogEntry, type LogLevel, LogManager, type MusicBackend, MusicManager, type MusicTrack, Node, type NodeCtor, type NodeJson, type NodeLifecycle, ORDER_GROUP_BASE, type OrderGroup, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, type ParsedNodePath, type ParticlePresetValues, ParticleSim, type ParticleSimConfig, type ParticleView, type PathGrid, type PlayMusicOptions, type PreloadResult, type PropDef, type PropSchema, ROLLOFF_MODELS, type Recorder, type RendererStats, type ReplayEvent, type ReplayJson, type ResolvedRendering, type ResolvedViewport, Rng, type RolloffModel, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, type SaveStore, Scene, type SceneJson, SceneTree, type Scheduler, SfxEngine, type SfxParams, type SfxPlayOptions, type SfxWave, Signal, type SignalListener, type SpatialParams, type SynthOptions, Timer, TouchControls, type TouchControlsOptions, UiBanner, UiBar, UiButton, UiDialogue, UiText, VERSION, type Vec3, type ViewportFit, type Voice, type VoicePreset, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, auditScene, 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, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, replay, resolveConstants, resolveRendering, resolveViewport, serializeNode, spatialGain, spatialPan, startRecording, synthSfx };

package/dist/index.js

@@ -1,13 +1,128 @@
 import { _ as registerBehavior, a as SCENE_FORMAT, c as SceneTree, d as resolveConstants, f as Node, g as getBehavior, h as clearBehaviors, i as serializeNode, l as CONST_REF_KEY, m as Behavior, n as loadScene, o as computeViewport, p as parseNodePath, r as Scene, s as resolveViewport, u as isConstRef, v as registeredBehaviors, y as Signal } from "./loader-B4OEXDZ8.js";
-import { a as ORDER_GROUP_BASE, c as LogManager, d as isAudioContextAvailable, f as MusicManager, g as AudioBuses, h as fadeGain, i as applyParticlePreset, l as InputMap, m as crossfadeGains, n as PARTICLE_PRESETS, o as effectiveOrder, p as WebAudioMusicBackend, r as PARTICLE_PRESET_NAMES, s as Engine, t as ParticleSim, u as SfxEngine } from "./particle-sim-m3CdTGSl.js";
+import { C as crossfadeGains, S as WebAudioMusicBackend, T as AudioBuses, _ as spatialPan, a as HudLayer, b as synthSfx, c as UiText, d as LogManager, f as InputMap, g as spatialGain, h as ROLLOFF_MODELS, i as UiDialogue, l as AudioPlayer, m as isAudioContextAvailable, n as Timer, o as UiBanner, p as SfxEngine, r as UiButton, s as UiBar, t as registerCoreNodes, u as Engine, v as SFX_PRESETS, w as fadeGain, x as MusicManager, y as SFX_PRESET_NAMES } from "./register-DRPIjrKG.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
-import { a as UiBar, c as ROLLOFF_MODELS, d as SFX_PRESETS, f as SFX_PRESET_NAMES, i as UiBanner, l as spatialGain, n as Timer, o as UiText, p as synthSfx, r as HudLayer, s as AudioPlayer, t as registerCoreNodes, u as spatialPan } from "./register-Dl_ixIJe.js";
+import { t as auditScene } from "./audit-C6rMyict.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-BVJ2HbCn.js";
 import { t as createNoise2D } from "./noise-CGUMx44x.js";
+import { a as ORDER_GROUP_BASE, i as applyParticlePreset, n as PARTICLE_PRESETS, o as effectiveOrder, r as PARTICLE_PRESET_NAMES, t as ParticleSim } from "./particle-sim-CyUU7HVU.js";
 import { i as resolveRendering, n as attachTouchControls, r as joystickVector, t as TouchControls } from "./touch-031PxtCR.js";
 import { t as duplicateNode } from "./duplicate-BEvGBtb_.js";
+//#region src/core/pathfinding.ts
+/**
+* A* from `from` to `to` (inclusive cell coords). Returns the cell path
+* INCLUDING both endpoints, or null when unreachable. Straight steps cost
+* 1, diagonals √2; the heuristic is octile (admissible for both modes).
+*/
+function findPath(grid, from, to, opts) {
+	const [sx, sy] = from;
+	const [tx, ty] = to;
+	const { width, height } = grid;
+	const inBounds = (x, y) => x >= 0 && y >= 0 && x < width && y < height;
+	if (!inBounds(sx, sy) || !inBounds(tx, ty)) return null;
+	if (grid.solid(sx, sy) || grid.solid(tx, ty)) return null;
+	if (sx === tx && sy === ty) return [[sx, sy]];
+	const diagonal = opts?.diagonal ?? true;
+	const maxExpansions = opts?.maxExpansions ?? 2e4;
+	const idx = (x, y) => y * width + x;
+	const gScore = new Float64Array(width * height).fill(Number.POSITIVE_INFINITY);
+	const cameFrom = new Int32Array(width * height).fill(-1);
+	const closed = new Uint8Array(width * height);
+	const heap = [];
+	const fScore = new Float64Array(width * height).fill(Number.POSITIVE_INFINITY);
+	const push = (n) => {
+		heap.push(n);
+		let i = heap.length - 1;
+		while (i > 0) {
+			const p = i - 1 >> 1;
+			if (fScore[heap[p]] <= fScore[heap[i]]) break;
+			const t = heap[p];
+			heap[p] = heap[i];
+			heap[i] = t;
+			i = p;
+		}
+	};
+	const pop = () => {
+		const top = heap[0];
+		const last = heap.pop();
+		if (heap.length > 0) {
+			heap[0] = last;
+			let i = 0;
+			for (;;) {
+				const l = i * 2 + 1;
+				const r = l + 1;
+				let m = i;
+				if (l < heap.length && fScore[heap[l]] < fScore[heap[m]]) m = l;
+				if (r < heap.length && fScore[heap[r]] < fScore[heap[m]]) m = r;
+				if (m === i) break;
+				const t = heap[m];
+				heap[m] = heap[i];
+				heap[i] = t;
+				i = m;
+			}
+		}
+		return top;
+	};
+	const SQRT2 = Math.SQRT2;
+	const octile = (x, y) => {
+		const dx = Math.abs(x - tx);
+		const dy = Math.abs(y - ty);
+		return dx > dy ? dx - dy + SQRT2 * dy : dy - dx + SQRT2 * dx;
+	};
+	const start = idx(sx, sy);
+	gScore[start] = 0;
+	fScore[start] = octile(sx, sy);
+	push(start);
+	let expansions = 0;
+	while (heap.length > 0) {
+		if (++expansions > maxExpansions) return null;
+		const current = pop();
+		if (closed[current]) continue;
+		closed[current] = 1;
+		const cx = current % width;
+		const cy = current / width | 0;
+		if (cx === tx && cy === ty) {
+			const path = [];
+			let n = current;
+			while (n !== -1) {
+				path.push([n % width, n / width | 0]);
+				n = cameFrom[n];
+			}
+			path.reverse();
+			return path;
+		}
+		for (let dy = -1; dy <= 1; dy++) for (let dx = -1; dx <= 1; dx++) {
+			if (dx === 0 && dy === 0) continue;
+			const isDiag = dx !== 0 && dy !== 0;
+			if (isDiag && !diagonal) continue;
+			const nx = cx + dx;
+			const ny = cy + dy;
+			if (!inBounds(nx, ny) || grid.solid(nx, ny)) continue;
+			if (isDiag && (grid.solid(cx + dx, cy) || grid.solid(cx, cy + dy))) continue;
+			const n = idx(nx, ny);
+			if (closed[n]) continue;
+			const tentative = gScore[current] + (isDiag ? SQRT2 : 1);
+			if (tentative < gScore[n]) {
+				gScore[n] = tentative;
+				fScore[n] = tentative + octile(nx, ny);
+				cameFrom[n] = current;
+				push(n);
+			}
+		}
+	}
+	return null;
+}
+/** Build a PathGrid from row-strings ('#' = solid) — tests and tile games. */
+function gridFromRows(rows) {
+	const height = rows.length;
+	return {
+		width: rows[0]?.length ?? 0,
+		height,
+		solid: (x, y) => (rows[y]?.[x] ?? "#") === "#"
+	};
+}
+//#endregion
 //#region src/core/preload.ts
 /**
 * Warm the HTTP cache for a list of asset urls with a progress callback —
@@ -40,6 +155,76 @@ function assetUrls(assets) {
 	return Object.values(assets ?? {}).map((a) => a.url).filter((u) => typeof u === "string" && !u.startsWith("data:"));
 }
 //#endregion
+//#region src/core/replay.ts
+const RECORDED_METHODS = [
+	"handleKey",
+	"handleMouseButton",
+	"handlePointerMove",
+	"handleWheel",
+	"pressAction",
+	"releaseAction"
+];
+/**
+* Tap the engine's input entry points and tick clock. Recording starts at
+* the CURRENT moment — start it before the first tick for full-run replays.
+*/
+function startRecording(engine) {
+	const ticks = [];
+	const events = [];
+	const input = engine.input;
+	const originals = /* @__PURE__ */ new Map();
+	for (const name of RECORDED_METHODS) {
+		const original = input[name];
+		originals.set(name, original);
+		input[name] = (...args) => {
+			events.push([
+				ticks.length,
+				name,
+				...args
+			]);
+			return original.apply(engine.input, args);
+		};
+	}
+	const originalTick = engine.tick.bind(engine);
+	const engineAny = engine;
+	engineAny.tick = (nowMs) => {
+		ticks.push(nowMs);
+		originalTick(nowMs);
+	};
+	let stopped = false;
+	return { stop() {
+		if (!stopped) {
+			stopped = true;
+			for (const [name, fn] of originals) input[name] = fn;
+			engineAny.tick = originalTick;
+		}
+		return {
+			replay: 1,
+			ticks,
+			events
+		};
+	} };
+}
+/**
+* Drive a fresh engine through a recording: for each recorded tick, feed
+* that tick's input events first, then tick with the recorded timestamp.
+* `onTick(index)` lets tests assert mid-run state.
+*/
+function replay(engine, recording, opts) {
+	const input = engine.input;
+	let cursor = 0;
+	for (let i = 0; i < recording.ticks.length; i++) {
+		while (cursor < recording.events.length && recording.events[cursor][0] === i) {
+			const [, method, ...args] = recording.events[cursor];
+			const fn = input[method];
+			if (typeof fn === "function") fn.apply(engine.input, args);
+			cursor += 1;
+		}
+		engine.tick(recording.ticks[i]);
+		opts?.onTick?.(i);
+	}
+}
+//#endregion
 //#region src/core/save.ts
 const memoryStores = /* @__PURE__ */ new Map();
 function createSaveStore(namespace) {
@@ -110,6 +295,6 @@ function newUid() {
 //#endregion
 //#region src/index.ts
 /** Engine version. Kept in sync with package.json by the release pipeline. */
-const VERSION = "0.7.1";
+const VERSION = "0.8.0";
 //#endregion
-export { AudioBuses, AudioPlayer, Behavior, CONST_REF_KEY, Engine, HudLayer, IncantoError, InputMap, LogManager, MusicManager, Node, ORDER_GROUP_BASE, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, ParticleSim, ROLLOFF_MODELS, Rng, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, Scene, SceneTree, SfxEngine, Signal, Timer, TouchControls, UiBanner, UiBar, UiText, VERSION, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, clearBehaviors, clearRegistry, computeViewport, createNode, createNoise2D, createSaveStore, crossfadeGains, duplicateNode, effectiveOrder, fadeGain, getBehavior, getNodeSchema, getNodeSignals, getNodeType, isAudioContextAvailable, isConstRef, joystickVector, jsonClone, jsonEquals, jsonKind, loadScene, mergeStaticSignals, newUid, parseNodePath, preloadUrls, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, resolveConstants, resolveRendering, resolveViewport, serializeNode, spatialGain, spatialPan, synthSfx };
+export { AudioBuses, AudioPlayer, Behavior, CONST_REF_KEY, Engine, HudLayer, IncantoError, InputMap, LogManager, MusicManager, Node, ORDER_GROUP_BASE, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, ParticleSim, ROLLOFF_MODELS, Rng, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, Scene, SceneTree, SfxEngine, Signal, Timer, TouchControls, UiBanner, UiBar, UiButton, UiDialogue, UiText, VERSION, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, auditScene, 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, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, replay, resolveConstants, resolveRendering, resolveViewport, serializeNode, spatialGain, spatialPan, startRecording, synthSfx };

package/dist/{loader-DnLMMRy8.d.ts → loader-BcUDfNHn.d.ts}

@@ -1,5 +1,5 @@
 import { i as SceneJson } from "./schema-CcoWb32N.js";
-import { v as Engine, w as Scene } from "./behavior-q3cejJgs.js";
+import { v as Engine, w as Scene } from "./behavior-Bod1AyJS.js";
 
 //#region src/core/scene/loader.d.ts
 interface LoadSceneOptions {

package/dist/net.d.ts

@@ -1,5 +1,5 @@
 import { c as JsonValue, i as SceneJson, s as JsonObject } from "./schema-CcoWb32N.js";
-import { $ as Signal, Z as Node, l as PropSchema, v as Engine } from "./behavior-q3cejJgs.js";
+import { $ as Node, l as PropSchema, tt as Signal, v as Engine } from "./behavior-Bod1AyJS.js";
 
 //#region src/net/types.d.ts
 type Unsubscribe = () => void;
@@ -424,4 +424,48 @@ declare class NetworkSpawner extends Node {
 */
 declare function registerNodesNet(): void;
 //#endregion
-export { type CollectionOptions, LocalGameServer, type LocalGameServerOptions, LocalGameServerTransport, LoopbackHub, LoopbackTransport, NetworkManager, type NetworkManagerOptions, NetworkSpawner, type NetworkTransport, type ServerClass, type Unsubscribe, applySyncPatch, createAgent8Server, createLocalGameServer, registerNodesNet };
+//#region src/net/split-screen.d.ts
+interface SplitScreenPlayer {
+  account: string;
+  engine: Engine;
+  manager: NetworkManager;
+}
+interface SplitScreenOptions extends LocalGameServerOptions {
+  /** The shared scene JSON every panel loads. */
+  scene: SceneJson;
+  /** Player accounts, one panel each (default ['p1', 'p2']). */
+  accounts?: string[];
+  /** Called per player to finish wiring (renderer, input, HUD). */
+  setup: (player: SplitScreenPlayer, index: number) => void | Promise<void>;
+  /** name → scene JSON registered on every panel's NetworkManager. */
+  scenes?: Record<string, SceneJson>;
+  /** Engine seed base (each panel gets seed + index). */
+  seed?: number;
+}
+/**
+* N local clients on ONE page sharing ONE in-memory game server — the
+* split-screen preview harness three examples were hand-wiring (~40 lines
+* each). Wires: LocalGameServer + per-player Engine/scene/NetworkManager +
+* the server tick driven from the first panel's clock.
+*
+*   const { players, server } = await createSplitScreen({
+*     scene: gameJson,
+*     server: MyServerClass,
+*     scenes: { 'remote-player': remoteJson },
+*     setup: ({ engine }, i) => {
+*       new Renderer2D({ canvas: canvases[i], engine });
+*       engine.input.attachKeyboard(window);
+*       engine.start();
+*     },
+*   });
+*
+* Going live stays the one-line story: replace the transport with
+* `createAgent8Server()` and boot ONE client per browser.
+*/
+declare function createSplitScreen(opts: SplitScreenOptions): Promise<{
+  server: ReturnType<typeof createLocalGameServer>;
+  players: SplitScreenPlayer[];
+  dispose(): void;
+}>;
+//#endregion
+export { type CollectionOptions, LocalGameServer, type LocalGameServerOptions, LocalGameServerTransport, LoopbackHub, LoopbackTransport, NetworkManager, type NetworkManagerOptions, NetworkSpawner, type NetworkTransport, type ServerClass, type SplitScreenOptions, type SplitScreenPlayer, type Unsubscribe, applySyncPatch, createAgent8Server, createLocalGameServer, createSplitScreen, registerNodesNet };

package/dist/net.js

@@ -1,7 +1,9 @@
+import { n as loadScene } from "./loader-B4OEXDZ8.js";
+import { u as Engine } from "./register-DRPIjrKG.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-C35HDZpm.js";
+import { i as applySyncPatch, n as NetworkSpawner, r as NetworkManager, t as registerNodesNet } from "./register-CxmuI9FL.js";
 //#region src/net/loopback.ts
 /**
 * In-memory multiplayer hub implementing the SAME kernel contract as
@@ -769,4 +771,54 @@ var LocalGameServerTransport = class {
 	}
 };
 //#endregion
-export { LocalGameServer, LocalGameServerTransport, LoopbackHub, LoopbackTransport, NetworkManager, NetworkSpawner, applySyncPatch, createAgent8Server, createLocalGameServer, registerNodesNet };
+//#region src/net/split-screen.ts
+/**
+* N local clients on ONE page sharing ONE in-memory game server — the
+* split-screen preview harness three examples were hand-wiring (~40 lines
+* each). Wires: LocalGameServer + per-player Engine/scene/NetworkManager +
+* the server tick driven from the first panel's clock.
+*
+*   const { players, server } = await createSplitScreen({
+*     scene: gameJson,
+*     server: MyServerClass,
+*     scenes: { 'remote-player': remoteJson },
+*     setup: ({ engine }, i) => {
+*       new Renderer2D({ canvas: canvases[i], engine });
+*       engine.input.attachKeyboard(window);
+*       engine.start();
+*     },
+*   });
+*
+* Going live stays the one-line story: replace the transport with
+* `createAgent8Server()` and boot ONE client per browser.
+*/
+async function createSplitScreen(opts) {
+	const server = createLocalGameServer(opts);
+	const accounts = opts.accounts ?? ["p1", "p2"];
+	const players = [];
+	for (let i = 0; i < accounts.length; i++) {
+		const account = accounts[i];
+		const engine = new Engine(opts.seed !== void 0 ? { seed: opts.seed + i } : {});
+		engine.setScene(loadScene(jsonClone(opts.scene)));
+		const manager = await NetworkManager.create(engine, { transport: server.createClient(account) });
+		for (const [name, json] of Object.entries(opts.scenes ?? {})) manager.registerScene(name, json);
+		const player = {
+			account,
+			engine,
+			manager
+		};
+		players.push(player);
+		await opts.setup(player, i);
+	}
+	const disconnect = (players[0]?.engine)?.updated.connect((dt) => void server.tick(Math.min(dt, .05) * 1e3));
+	return {
+		server,
+		players,
+		dispose() {
+			disconnect?.();
+			for (const p of players) p.engine.dispose?.();
+		}
+	};
+}
+//#endregion
+export { LocalGameServer, LocalGameServerTransport, LoopbackHub, LoopbackTransport, NetworkManager, NetworkSpawner, applySyncPatch, createAgent8Server, createLocalGameServer, createSplitScreen, registerNodesNet };