incanto 0.36.2 → 0.38.0

package/dist/test-CoDPWx-m.js

@@ -0,0 +1,1404 @@
+import { n as loadScene, w as registerBehavior } from "./loader-r49nDwB4.js";
+import { h as Engine } from "./register-Dm7nrd-E.js";
+import { t as IncantoError } from "./errors-BpWbnbb_.js";
+import { n as startRecording } from "./replay-DH0UOuZ-.js";
+import { n as jsonEquals, t as jsonClone } from "./json-BLk7H2Qa.js";
+import { i as getNodeSchema, s as mergeStaticProps } from "./registry-IyWCGe4q.js";
+import { n as registerGameplayBehaviors } from "./gameplay-CsJDUQh_.js";
+import { t as registerNodes2D } from "./register-DnB9m7Rl.js";
+import { n as registerNodes3D, t as resolveEnvironmentHdri } from "./environment-presets-C0Axpfth.js";
+import { t as registerNodesNet } from "./register-B4RRQbyq.js";
+import { Box3, Euler, Matrix4, PerspectiveCamera, Quaternion, Vector3 } from "three";
+//#region src/test/framing.ts
+/**
+* What the camera is actually looking at — without a GPU.
+*
+* Nearly every decision in a 3D game is visual: is the camera framing the
+* island, is anything lit, is the gem buried inside the platform. An agent
+* building a game could answer none of them. `captureScene()` lists nodes and
+* their props, which tells you a gem is at `[4, 1, -2]` and nothing whatsoever
+* about whether you can SEE it — and the engine ships no pixel output at all,
+* so "look at it" was a human's job.
+*
+* This is the geometry half of the answer, and it needs no renderer, no canvas
+* and no browser: the camera's own matrices, the world transforms composed from
+* the tree, and the colliders already declared in the JSON.
+*
+* What it measures: the node's ORIGIN, widened to its declared `size` (a
+* MeshInstance3D's box, a Terrain3D's ground) or its collider when it has one.
+* A 200 m island whose origin is off to the left still counts as on screen,
+* because its box is. For a node that declares neither, read `offscreen` as
+* "its origin is off-screen" — a loaded GLB's real silhouette needs the model,
+* and the model needs a GPU.
+*/
+const DEG = Math.PI / 180;
+const CAMERA_TYPES = new Set(["Camera3D"]);
+const LIGHT_TYPES = new Set([
+	"DirectionalLight3D",
+	"OmniLight3D",
+	"SpotLight3D"
+]);
+/**
+* World transform for every node, composed from the tree.
+*
+* NOT read off `_object3D`: that is the renderer's copy, and headless there may
+* be no renderer to have written it. The props are the truth here.
+*/
+function place(scene) {
+	const out = [];
+	const walk = (node, parent) => {
+		const type = node.constructor.typeName ?? "Node";
+		const n = node;
+		const local = new Matrix4();
+		if (Array.isArray(n.position)) local.compose(new Vector3(n.position[0] ?? 0, n.position[1] ?? 0, n.position[2] ?? 0), new Quaternion().setFromEuler(new Euler((n.rotation?.[0] ?? 0) * DEG, (n.rotation?.[1] ?? 0) * DEG, (n.rotation?.[2] ?? 0) * DEG, "XYZ")), new Vector3(n.scale?.[0] ?? 1, n.scale?.[1] ?? 1, n.scale?.[2] ?? 1));
+		const matrix = new Matrix4().multiplyMatrices(parent, local);
+		out.push({
+			node,
+			type,
+			matrix,
+			position: new Vector3().setFromMatrixPosition(matrix)
+		});
+		for (const child of node.children) walk(child, matrix);
+	};
+	walk(scene.root, new Matrix4());
+	return out;
+}
+/** A node draws something if its class builds its own three object. */
+function draws(node) {
+	const proto = Object.getPrototypeOf(node);
+	let base = proto;
+	while (base && base.constructor?.typeName !== "Node3D") {
+		base = Object.getPrototypeOf(base);
+		if (!base) return false;
+	}
+	return proto._createObject3D !== base._createObject3D;
+}
+/**
+* How big the node is on screen, from whatever it declares.
+*
+* `size` first (a MeshInstance3D's box, a Terrain3D's ground), then a collider.
+* This is the FRAMING question — "does this thing fill the view" — and a mesh's
+* own size answers it better than the body wrapped around it.
+*/
+function extentOf(node) {
+	const size = node.size;
+	if (Array.isArray(size) && size.length >= 2 && typeof size[0] === "number") {
+		const x = size[0] / 2;
+		const y = typeof size[1] === "number" && size.length >= 3 ? size[1] / 2 : x;
+		const z = (size[size.length - 1] ?? size[0]) / 2;
+		return new Vector3(Math.abs(x), Math.abs(y), Math.abs(z));
+	}
+	return halfExtents(node);
+}
+/**
+* A COLLIDER's half-extents, when the node declares one.
+*
+* Colliders live on bodies, not meshes — which is exactly right for the
+* overlap report: "the gem is inside the platform" is a question about the
+* physical shapes, and two meshes touching (a floor meeting a wall) is not a
+* finding.
+*/
+function halfExtents(node) {
+	const collider = node.collider;
+	if (!collider || typeof collider !== "object") return null;
+	const shape = collider.shape;
+	if (shape === "box") {
+		const size = collider.size ?? [
+			1,
+			1,
+			1
+		];
+		return new Vector3((size[0] ?? 1) / 2, (size[1] ?? 1) / 2, (size[2] ?? 1) / 2);
+	}
+	if (shape === "sphere") {
+		const r = collider.radius ?? .5;
+		return new Vector3(r, r, r);
+	}
+	if (shape === "capsule" || shape === "cylinder") {
+		const r = collider.radius ?? .5;
+		return new Vector3(r, (collider.height ?? 1) / 2 + r, r);
+	}
+	return null;
+}
+function describeFraming(scene, opts = {}) {
+	const placed = place(scene);
+	const cameras = placed.filter((p) => CAMERA_TYPES.has(p.type));
+	const chosen = cameras.find((p) => p.node.current === true) ?? cameras[0] ?? null;
+	const lights = [];
+	for (const p of placed) if (LIGHT_TYPES.has(p.type)) lights.push(`${p.node.getPath()} (${p.type})`);
+	const env = scene.environment;
+	if (env) {
+		if (env.preset !== void 0) lights.push(`environment.preset = ${JSON.stringify(env.preset)}`);
+		if (env.sky !== void 0) lights.push("environment.sky");
+		if (env.hdri !== void 0) lights.push("environment.hdri");
+		const ambient = env.ambient;
+		if (typeof ambient?.intensity === "number" && ambient.intensity > 0) lights.push(`environment.ambient.intensity = ${ambient.intensity}`);
+	}
+	const wanted = opts.types ? new Set(opts.types) : null;
+	const subjects = placed.filter((p) => !CAMERA_TYPES.has(p.type) && !LIGHT_TYPES.has(p.type) && (wanted ? wanted.has(p.type) : draws(p.node)));
+	const entries = [];
+	let camera = null;
+	if (chosen) {
+		const node = chosen.node;
+		const cam = new PerspectiveCamera(node.fov ?? 60, opts.aspect ?? 16 / 9, node.near ?? .1, node.far ?? 1e3);
+		cam.matrixWorld.copy(chosen.matrix);
+		cam.matrixWorldInverse.copy(chosen.matrix).invert();
+		cam.updateProjectionMatrix();
+		const forward = new Vector3(0, 0, -1).applyQuaternion(new Quaternion().setFromRotationMatrix(chosen.matrix));
+		camera = {
+			path: chosen.node.getPath(),
+			at: chosen.position.toArray(),
+			forward: [
+				round(forward.x),
+				round(forward.y),
+				round(forward.z)
+			],
+			fovDeg: node.fov ?? 60
+		};
+		for (const p of subjects) {
+			const view = p.position.clone().applyMatrix4(cam.matrixWorldInverse);
+			const distance = p.position.distanceTo(chosen.position);
+			if (view.z > -(node.near ?? .1)) {
+				entries.push({
+					path: p.node.getPath(),
+					type: p.type,
+					at: p.position.toArray(),
+					where: "behind",
+					distance: round(distance)
+				});
+				continue;
+			}
+			const ndc = p.position.clone().project(cam);
+			let onScreen = Math.abs(ndc.x) <= 1 && Math.abs(ndc.y) <= 1;
+			if (!onScreen) {
+				const half = extentOf(p.node);
+				if (half) onScreen = cornersOnScreen(new Box3().setFromCenterAndSize(p.position, half.clone().multiplyScalar(2)), cam);
+			}
+			entries.push({
+				path: p.node.getPath(),
+				type: p.type,
+				at: p.position.toArray(),
+				where: onScreen ? "onScreen" : "offscreen",
+				screen: [round(ndc.x), round(ndc.y)],
+				distance: round(distance)
+			});
+		}
+	}
+	return {
+		camera,
+		entries,
+		lights,
+		overlaps: findOverlaps(placed)
+	};
+}
+function cornersOnScreen(box, cam) {
+	const min = box.min;
+	const max = box.max;
+	for (const x of [min.x, max.x]) for (const y of [min.y, max.y]) for (const z of [min.z, max.z]) {
+		const ndc = new Vector3(x, y, z).project(cam);
+		if (Math.abs(ndc.x) <= 1 && Math.abs(ndc.y) <= 1 && ndc.z <= 1) return true;
+	}
+	return false;
+}
+/**
+* Declared colliders that intersect.
+*
+* The colliders, not the meshes: they are in the JSON, so this needs no GPU and
+* no loaded model — and a prop buried inside a platform is the thing you were
+* trying to see anyway.
+*/
+function findOverlaps(placed) {
+	const boxes = [];
+	for (const p of placed) {
+		const half = halfExtents(p.node);
+		if (!half) continue;
+		boxes.push({
+			path: p.node.getPath(),
+			box: new Box3().setFromCenterAndSize(p.position, half.clone().multiplyScalar(2))
+		});
+	}
+	const out = [];
+	for (let i = 0; i < boxes.length; i++) for (let j = i + 1; j < boxes.length; j++) {
+		const a = boxes[i];
+		const b = boxes[j];
+		if (!a || !b) continue;
+		if (a.path.startsWith(`${b.path}/`) || b.path.startsWith(`${a.path}/`)) continue;
+		if (a.box.intersectsBox(b.box)) out.push({
+			a: a.path,
+			b: b.path
+		});
+	}
+	return out;
+}
+function round(n) {
+	return Math.round(n * 1e3) / 1e3;
+}
+/** The report as something to read in a terminal. */
+function framingText(report) {
+	const lines = [];
+	if (!report.camera) lines.push("camera: NONE — this scene frames nothing (no Camera3D)");
+	else {
+		const c = report.camera;
+		lines.push(`camera ${c.path} at [${c.at.map(round).join(", ")}] looking [${c.forward.join(", ")}] fov ${c.fovDeg}`);
+	}
+	lines.push(report.lights.length ? `lit by: ${report.lights.join(", ")}` : "lit by: NOTHING — this scene renders black");
+	const on = report.entries.filter((e) => e.where === "onScreen");
+	const off = report.entries.filter((e) => e.where === "offscreen");
+	const behind = report.entries.filter((e) => e.where === "behind");
+	lines.push(`${on.length} on screen, ${off.length} off screen, ${behind.length} behind the camera`);
+	for (const e of report.entries) {
+		const at = `[${e.at.map(round).join(", ")}]`;
+		const screen = e.screen ? ` screen [${e.screen.join(", ")}]` : "";
+		lines.push(`  ${e.where.padEnd(9)} ${e.path} (${e.type}) ${at}${screen} ${e.distance}m`);
+	}
+	for (const o of report.overlaps) lines.push(`  overlap  ${o.a} ∩ ${o.b}`);
+	return lines.join("\n");
+}
+//#endregion
+//#region src/test/playtest.ts
+const CONTROLLERS = new Set(["CharacterController2D", "CharacterController3D"]);
+/**
+* Who the driver is playing as.
+*
+* In order: the body carrying a character controller, then group `player`, then
+* a node literally called Player. A scene that satisfies none of them is not
+* one this can drive, and says so rather than guessing.
+*/
+function findPlayer(root) {
+	let found = null;
+	const walk = (node) => {
+		if (found) return;
+		for (const child of node.children) if (CONTROLLERS.has(child.constructor.typeName ?? "")) {
+			found = node;
+			return;
+		}
+		for (const child of node.children) walk(child);
+	};
+	walk(root);
+	if (found) return found;
+	let byGroup = null;
+	const groups = (node) => {
+		if (byGroup) return;
+		if (node.isInGroup("player")) byGroup = node;
+		for (const child of node.children) groups(child);
+	};
+	groups(root);
+	if (byGroup) return byGroup;
+	return root.getNodeOrNull("%Player");
+}
+function positionOf$1(node) {
+	const p = node.position;
+	if (!Array.isArray(p)) return [
+		0,
+		0,
+		0
+	];
+	return [
+		p[0] ?? 0,
+		p[1] ?? 0,
+		p[2] ?? 0
+	];
+}
+/** World position by walking the parent chain — no renderer, no matrices. */
+function worldOf(node) {
+	let x = 0;
+	let y = 0;
+	let z = 0;
+	for (let n = node; n; n = n.parent) {
+		const [px, py, pz] = positionOf$1(n);
+		x += px;
+		y += py;
+		z += pz;
+	}
+	return [
+		x,
+		y,
+		z
+	];
+}
+/** Trigger volumes are destinations even without a script — that IS their job. */
+const TRIGGERS = new Set(["Area2D", "Area3D"]);
+/**
+* Is this node somewhere the player is meant to GO?
+*
+* Author intent, not geometry. Keying off the tree alone reported 150 unreached
+* nodes on the village scene and 138 of them were roof beams and fence posts —
+* a report nobody would read twice. A node is a destination when the author
+* marked it as one: it runs a behavior, it carries a group, or it is a trigger
+* volume. Decoration is silent.
+*/
+function isTarget(node) {
+	const type = node.constructor.typeName ?? "";
+	if (type.startsWith("Ui")) return false;
+	if (TRIGGERS.has(type)) return true;
+	if (node.groups.size > 0) return true;
+	return node.script?.name !== void 0;
+}
+/**
+* What the SCENE says winning and losing are.
+*
+* Nothing here is a heuristic about game design — `GameFlow` already models
+* `'won'`/`'gameover'`, `ScoreKeeper` already emits `won`/`lost`, and `Health`
+* already emits `died`. The scene declared all of it; this only listens.
+*/
+function makeOracle(engine, player) {
+	let outcome = null;
+	let damage = 0;
+	const offs = [];
+	/** First verdict wins — a run ends at its first conclusion, not its last. */
+	const settle = (verdict) => {
+		if (outcome === null) outcome = verdict;
+	};
+	const walk = (node) => {
+		if (node.behavior) for (const signal of node.declaredSignalNames()) {
+			if (signal === "won") offs.push(node.on(signal, () => settle("won")));
+			if (signal === "lost") offs.push(node.on(signal, () => settle("lost")));
+			if (signal === "died" && node === player) offs.push(node.on(signal, () => settle("lost")));
+			if (signal === "damaged" && node === player) offs.push(node.on(signal, () => {
+				damage += 1;
+			}));
+			if (signal === "flowChanged") offs.push(node.on(signal, (state) => {
+				if (state === "won") settle("won");
+				if (state === "gameover") settle("lost");
+			}));
+		}
+		for (const child of node.children) walk(child);
+	};
+	const root = engine.scene?.root;
+	if (root) walk(root);
+	return {
+		outcome: () => outcome,
+		damage: () => damage,
+		dispose: () => {
+			for (const off of offs) off();
+		}
+	};
+}
+/**
+* A monkey with a memory.
+*
+* Not an attempt to play well — an attempt to play DIFFERENTLY, which is what
+* makes automated testers find what humans do not. It holds a direction for a
+* while (a per-frame coin flip goes nowhere), presses buttons at intervals, and
+* biases its next heading toward the part of the world it has visited least.
+* That last part is the whole difference between "wanders near spawn forever"
+* and "eventually finds the door".
+*/
+var Driver = class {
+	engine;
+	rand;
+	heading = 0;
+	headingLeft = 0;
+	visits = /* @__PURE__ */ new Map();
+	buttons;
+	moveAction;
+	held = /* @__PURE__ */ new Map();
+	constructor(engine, rand) {
+		this.engine = engine;
+		this.rand = rand;
+		const declared = engine.input.declaredActions();
+		this.moveAction = declared.find((a) => a.type === "vector2")?.name ?? null;
+		this.buttons = declared.filter((a) => a.type === "button").map((a) => a.name);
+	}
+	/** Grid cell key — coarse on purpose, this is novelty not navigation. */
+	cell(p) {
+		return `${Math.round(p[0] / 4)},${Math.round(p[2] / 4)}`;
+	}
+	step(dt, at) {
+		this.visits.set(this.cell(at), (this.visits.get(this.cell(at)) ?? 0) + 1);
+		this.headingLeft -= dt;
+		if (this.headingLeft <= 0) {
+			this.heading = this.pickHeading(at);
+			this.headingLeft = .4 + this.rand() * 1.2;
+		}
+		if (this.moveAction) this.engine.input.setActionVector(this.moveAction, Math.cos(this.heading), Math.sin(this.heading));
+		for (const button of this.buttons) {
+			const left = (this.held.get(button) ?? 0) - dt;
+			if (left > 0) {
+				this.held.set(button, left);
+				continue;
+			}
+			if (left > -.05 && left <= 0) {
+				this.engine.input.releaseAction(button);
+				this.held.set(button, -1);
+				continue;
+			}
+			const chance = button === "jump" ? .06 : .02;
+			if (this.rand() < chance) {
+				this.engine.input.pressAction(button);
+				this.held.set(button, .08 + this.rand() * .12);
+			}
+		}
+	}
+	/** Prefer the least-visited neighbouring cell; ties break randomly. */
+	pickHeading(at) {
+		let best = Number.POSITIVE_INFINITY;
+		let bestAngle = this.rand() * Math.PI * 2;
+		for (let i = 0; i < 8; i++) {
+			const angle = i / 8 * Math.PI * 2 + this.rand() * .3;
+			const probe = [
+				at[0] + Math.cos(angle) * 4,
+				at[1],
+				at[2] + Math.sin(angle) * 4
+			];
+			const seen = (this.visits.get(this.cell(probe)) ?? 0) + this.rand();
+			if (seen < best) {
+				best = seen;
+				bestAngle = angle;
+			}
+		}
+		return bestAngle;
+	}
+	release() {
+		for (const button of this.buttons) this.engine.input.releaseAction(button);
+		if (this.moveAction) this.engine.input.setActionVector(this.moveAction, 0, 0);
+	}
+};
+async function runOnce(json, seed, opts) {
+	const session = await createPlaySession(json, {
+		seed,
+		...opts.behaviors ? { behaviors: opts.behaviors } : {},
+		stubMissingBehaviors: opts.stubMissingBehaviors ?? true,
+		...opts.resolveScene ? { resolveScene: opts.resolveScene } : {}
+	});
+	const { engine, scene } = session;
+	const player = findPlayer(scene.root);
+	const oracle = makeOracle(engine, player);
+	const targets = [];
+	const signals = [];
+	const fired = /* @__PURE__ */ new Set();
+	const offs = [];
+	const wired = /* @__PURE__ */ new Set();
+	for (const conn of scene.source.connections ?? []) {
+		if (typeof conn.from !== "string" || typeof conn.signal !== "string") continue;
+		const node = scene.root.getNodeOrNull(conn.from);
+		if (node) wired.add(`${node.getPath()}.${conn.signal}`);
+	}
+	const walkAll = (node) => {
+		const isDestination = node !== player && isTarget(node);
+		if (isDestination) targets.push(node.getPath());
+		for (const signal of node.declaredSignalNames()) {
+			const key = `${node.getPath()}.${signal}`;
+			if (wired.has(key) || isDestination) signals.push(key);
+			offs.push(node.on(signal, () => void fired.add(key)));
+		}
+		for (const child of node.children) walkAll(child);
+	};
+	walkAll(scene.root);
+	const targetNodes = [];
+	const collect = (node) => {
+		if (node !== player && isTarget(node)) targetNodes.push([node.getPath(), node]);
+		for (const child of node.children) collect(child);
+	};
+	collect(scene.root);
+	const start = player ? worldOf(player) : [
+		0,
+		0,
+		0
+	];
+	const floor = opts.fallBelow ?? start[1] - 50;
+	const radius = opts.reachRadius ?? 2;
+	const recorder = startRecording(engine);
+	const rand = () => engine.rng.next();
+	const driver = new Driver(engine, rand);
+	const reached = /* @__PURE__ */ new Set();
+	const stepMs = 1e3 / 60;
+	const deadline = (opts.seconds ?? 60) * 1e3;
+	let outcome = "stuck";
+	let at = start;
+	while (session.timeMs < deadline) {
+		at = player ? worldOf(player) : start;
+		driver.step(stepMs / 1e3, at);
+		session.step(stepMs);
+		if (player) for (const [path, node] of targetNodes) {
+			if (reached.has(path)) continue;
+			const p = worldOf(node);
+			if (Math.hypot(at[0] - p[0], at[1] - p[1], at[2] - p[2]) <= radius) reached.add(path);
+		}
+		const verdict = oracle.outcome();
+		if (verdict) {
+			outcome = verdict;
+			break;
+		}
+		if (engine.stats().errors > 0) {
+			outcome = "error";
+			break;
+		}
+		if (player && at[1] < floor) {
+			outcome = "fell";
+			break;
+		}
+	}
+	driver.release();
+	const bad = outcome !== "won";
+	const run = {
+		seed,
+		outcome,
+		timeMs: session.timeMs,
+		reached: [...reached],
+		fired: [...fired],
+		damageTaken: oracle.damage(),
+		errors: engine.stats().errors,
+		replay: bad ? recorder.stop() : null,
+		endedAt: at
+	};
+	if (!bad) recorder.stop();
+	for (const off of offs) off();
+	oracle.dispose();
+	session.dispose();
+	return {
+		run,
+		targets,
+		signals
+	};
+}
+/** Play the scene `runs` times and report what happened. */
+async function playtest(json, opts = {}) {
+	const count = Math.max(1, opts.runs ?? 20);
+	const base = opts.seed ?? 1;
+	const runs = [];
+	let targets = [];
+	let signals = [];
+	for (let i = 0; i < count; i++) {
+		const one = await runOnce(json, base + i, opts);
+		runs.push(one.run);
+		targets = one.targets;
+		signals = one.signals;
+	}
+	const probe = await createPlaySession(json, {
+		seed: base,
+		stubMissingBehaviors: opts.stubMissingBehaviors ?? true,
+		...opts.resolveScene ? { resolveScene: opts.resolveScene } : {}
+	});
+	const actions = probe.engine.input.declaredActions().map((a) => a.name);
+	probe.dispose();
+	return {
+		runs,
+		targets,
+		signals: [...new Set(signals)],
+		actions,
+		inertActions: []
+	};
+}
+function pct(n, total) {
+	return `${n}/${total}`;
+}
+function median(values) {
+	if (values.length === 0) return 0;
+	const s = [...values].sort((a, b) => a - b);
+	return s[Math.floor(s.length / 2)];
+}
+/**
+* The report, as prose an agent reads and a person skims.
+*
+* Deliberately says what is WRONG and stays quiet about what is fine — a wall
+* of green is a wall nobody reads.
+*/
+function playtestText(report) {
+	const { runs, targets, signals } = report;
+	const total = runs.length;
+	const lines = [];
+	const secs = Math.round((runs[0]?.timeMs ?? 0) / 1e3);
+	lines.push(`${total} runs × up to ${secs}s`);
+	lines.push("");
+	const won = runs.filter((r) => r.outcome === "won");
+	if (won.length > 0) lines.push(`  ✓ reached "won" in ${pct(won.length, total)}   median ${Math.round(median(won.map((r) => r.timeMs)) / 1e3)}s`);
+	else lines.push(`  ✗ never reached "won" in ${total} runs — nothing in this scene declares a win, or it cannot be reached`);
+	for (const bad of [
+		"error",
+		"fell",
+		"lost",
+		"stuck"
+	]) {
+		const hits = runs.filter((r) => r.outcome === bad);
+		if (hits.length === 0) continue;
+		const where = bad === "fell" ? ` (last at y=${hits[0].endedAt[1].toFixed(1)})` : "";
+		lines.push(`  ✗ ${bad} in ${pct(hits.length, total)}${where}`);
+	}
+	const everReached = new Set(runs.flatMap((r) => r.reached));
+	const missed = targets.filter((path) => !everReached.has(path));
+	if (missed.length > 0) {
+		lines.push("");
+		lines.push(`  never reached (${missed.length} of ${targets.length}):`);
+		for (const path of missed.slice(0, 12)) lines.push(`    ${path}`);
+		if (missed.length > 12) lines.push(`    …and ${missed.length - 12} more`);
+	}
+	const everFired = new Set(runs.flatMap((r) => r.fired));
+	const silent = signals.filter((s) => !everFired.has(s));
+	if (silent.length > 0) {
+		lines.push("");
+		lines.push(`  never fired (${silent.length} of ${signals.length}):`);
+		for (const s of silent.slice(0, 12)) lines.push(`    ${s}`);
+		if (silent.length > 12) lines.push(`    …and ${silent.length - 12} more`);
+	}
+	const damage = runs.reduce((n, r) => n + r.damageTaken, 0);
+	lines.push("");
+	lines.push(damage === 0 ? `  danger: the player took damage 0 times in ${total} runs — nothing here can hurt you` : `  danger: ${damage} hits across ${total} runs (${(damage / total).toFixed(1)} per run)`);
+	return lines.join("\n");
+}
+/** The failing runs worth saving, newest problem first. */
+function failingReplays(report) {
+	const order = [
+		"error",
+		"fell",
+		"stuck",
+		"lost"
+	];
+	return report.runs.filter((r) => r.replay !== null).sort((a, b) => order.indexOf(a.outcome) - order.indexOf(b.outcome)).map((r) => ({
+		seed: r.seed,
+		outcome: r.outcome,
+		replay: r.replay
+	}));
+}
+//#endregion
+//#region src/test/feel.ts
+const STEP_MS = 1e3 / 60;
+/** Drop height for the buffer probe — long enough to outlast a coyote window. */
+const DROP = 12;
+function positionOf(node) {
+	const p = node.position;
+	return [
+		p?.[0] ?? 0,
+		p?.[1] ?? 0,
+		p?.[2] ?? 0
+	];
+}
+function velocityOf(node) {
+	const v = node.linearVelocity;
+	return [
+		v?.[0] ?? 0,
+		v?.[1] ?? 0,
+		v?.[2] ?? 0
+	];
+}
+async function makeProbe(json, opts) {
+	const session = await createPlaySession(json, {
+		seed: opts.seed ?? 1,
+		...opts.behaviors ? { behaviors: opts.behaviors } : {},
+		stubMissingBehaviors: opts.stubMissingBehaviors ?? true,
+		...opts.resolveScene ? { resolveScene: opts.resolveScene } : {}
+	});
+	const player = findPlayer(session.scene.root);
+	const declared = session.engine.input.declaredActions();
+	const move = opts.moveAction ?? declared.find((a) => a.type === "vector2")?.name ?? null;
+	const jump = opts.jumpAction ?? (declared.some((a) => a.name === "jump" && a.type === "button") ? "jump" : null);
+	if (!player) {
+		session.dispose();
+		return {
+			probe: null,
+			move,
+			jump
+		};
+	}
+	return {
+		probe: {
+			session,
+			engine: session.engine,
+			player,
+			step: (frames = 1) => session.step(frames * STEP_MS),
+			pos: () => positionOf(player),
+			vel: () => velocityOf(player),
+			speed: () => {
+				const v = velocityOf(player);
+				return Math.hypot(v[0], v[2]);
+			}
+		},
+		move,
+		jump
+	};
+}
+/** Let the character settle onto whatever it is standing on. */
+function settle(probe) {
+	probe.step(60);
+}
+/** Hold one direction and learn what this character's plateau actually is. */
+function measureAccel(probe, move) {
+	settle(probe);
+	const before = probe.pos();
+	probe.engine.input.setActionVector(move, 1, 0);
+	let latency = null;
+	let top = 0;
+	for (let f = 1; f <= 300; f++) {
+		probe.step();
+		if (latency === null) {
+			const p = probe.pos();
+			if (Math.hypot(p[0] - before[0], p[2] - before[2]) > .01) latency = f;
+		}
+		top = Math.max(top, probe.speed());
+	}
+	probe.engine.input.setActionVector(move, 0, 0);
+	return {
+		top,
+		latencyFrames: latency
+	};
+}
+/**
+* Time from standstill to 95% of top speed.
+*
+* Two passes on purpose: the first learns what top speed IS (it depends on the
+* scene's own props and surface), the second times the climb to 95% of it. One
+* pass would have to guess the target.
+*/
+function timeToFullSpeed(probe, move, top) {
+	settle(probe);
+	const target = top * .95;
+	probe.engine.input.setActionVector(move, 1, 0);
+	for (let f = 1; f <= 600; f++) {
+		probe.step();
+		if (probe.speed() >= target) {
+			probe.engine.input.setActionVector(move, 0, 0);
+			return Math.round(f * STEP_MS);
+		}
+	}
+	probe.engine.input.setActionVector(move, 0, 0);
+	return null;
+}
+function timeToStop(probe, move, top) {
+	settle(probe);
+	probe.engine.input.setActionVector(move, 1, 0);
+	for (let f = 0; f < 600 && probe.speed() < top * .9; f++) probe.step();
+	probe.engine.input.setActionVector(move, 0, 0);
+	for (let f = 1; f <= 600; f++) {
+		probe.step();
+		if (probe.speed() < top * .05) return Math.round(f * STEP_MS);
+	}
+	return null;
+}
+function turnaround(probe, move, top) {
+	settle(probe);
+	probe.engine.input.setActionVector(move, 1, 0);
+	for (let f = 0; f < 600 && probe.speed() < top * .9; f++) probe.step();
+	probe.engine.input.setActionVector(move, -1, 0);
+	for (let f = 1; f <= 600; f++) {
+		probe.step();
+		if (probe.vel()[0] < -top * .9) return Math.round(f * STEP_MS);
+	}
+	probe.engine.input.setActionVector(move, 0, 0);
+	return null;
+}
+function jumpShape(probe, jump) {
+	settle(probe);
+	const floor = probe.pos()[1];
+	probe.engine.input.pressAction(jump);
+	probe.step();
+	probe.engine.input.releaseAction(jump);
+	let apex = 0;
+	let toApex = 0;
+	let airtime = null;
+	for (let f = 2; f <= 600; f++) {
+		probe.step();
+		const h = probe.pos()[1] - floor;
+		if (h > apex) {
+			apex = h;
+			toApex = f;
+		}
+		if (apex > .02 && h <= .02 && airtime === null) {
+			airtime = Math.round(f * STEP_MS);
+			break;
+		}
+	}
+	if (apex <= .02) return {
+		apex: null,
+		toApexMs: null,
+		airtimeMs: null
+	};
+	return {
+		apex: Number(apex.toFixed(3)),
+		toApexMs: Math.round(toApex * STEP_MS),
+		airtimeMs: airtime
+	};
+}
+/**
+* How long after leaving the ground a jump still fires — measured, not read.
+*
+* Binary search over the delay: lift the character clear of its support (the
+* same thing walking off a ledge does), wait, press, and see whether it
+* launched. A `coyoteSeconds` the controller never consults reports 0 here,
+* which is the whole point — that was a real bug in this engine's 3D controller
+* until 0.37 and the schema looked correct the entire time.
+*/
+async function measureCoyote(json, opts, jump) {
+	const fired = async (delayFrames) => {
+		const { probe } = await makeProbe(json, opts);
+		if (!probe) return false;
+		settle(probe);
+		const p = probe.pos();
+		probe.player.position = [
+			p[0],
+			p[1] + 40,
+			p[2]
+		];
+		probe.step(delayFrames);
+		const before = probe.vel()[1];
+		probe.engine.input.pressAction(jump);
+		probe.step();
+		const after = probe.vel()[1];
+		probe.session.dispose();
+		return after - before > 1;
+	};
+	if (!await fired(1)) return 0;
+	let lo = 1;
+	let hi = 60;
+	if (await fired(hi)) return null;
+	while (hi - lo > 1) {
+		const mid = Math.floor((lo + hi) / 2);
+		if (await fired(mid)) lo = mid;
+		else hi = mid;
+	}
+	return Math.round(lo * STEP_MS);
+}
+/**
+* How long BEFORE landing a press still survives.
+*
+* Same shape: drop the character, press at T frames before it would touch down,
+* and check whether it left the ground again afterwards.
+*/
+async function measureBuffer(json, opts, jump) {
+	const survived = async (earlyFrames) => {
+		const { probe } = await makeProbe(json, opts);
+		if (!probe) return false;
+		settle(probe);
+		const floor = probe.pos()[1];
+		probe.player.position = [
+			probe.pos()[0],
+			floor + DROP,
+			probe.pos()[2]
+		];
+		let frames = 0;
+		while (probe.pos()[1] > floor + .05 && frames < 200) {
+			probe.step();
+			frames += 1;
+		}
+		const fallFrames = frames;
+		probe.session.dispose();
+		const second = await makeProbe(json, opts);
+		if (!second.probe) return false;
+		const p2 = second.probe;
+		settle(p2);
+		p2.player.position = [
+			p2.pos()[0],
+			floor + DROP,
+			p2.pos()[2]
+		];
+		p2.step(Math.max(0, fallFrames - earlyFrames));
+		p2.engine.input.pressAction(jump);
+		p2.step();
+		p2.engine.input.releaseAction(jump);
+		let rose = false;
+		for (let f = 0; f < 40; f++) {
+			p2.step();
+			if (p2.vel()[1] > 1) rose = true;
+		}
+		p2.session.dispose();
+		return rose;
+	};
+	if (!await survived(1)) return 0;
+	let lo = 1;
+	let hi = 30;
+	if (await survived(hi)) return null;
+	while (hi - lo > 1) {
+		const mid = Math.floor((lo + hi) / 2);
+		if (await survived(mid)) lo = mid;
+		else hi = mid;
+	}
+	return Math.round(lo * STEP_MS);
+}
+async function feelReport(json, opts = {}) {
+	const first = await makeProbe(json, opts);
+	const move = first.move;
+	const jump = first.jump;
+	if (!first.probe) return {
+		player: null,
+		moveAction: move,
+		jumpAction: jump,
+		topSpeed: 0,
+		timeToFullSpeedMs: null,
+		timeToStopMs: null,
+		turnaroundMs: null,
+		jumpApex: null,
+		timeToApexMs: null,
+		airtimeMs: null,
+		coyoteMs: null,
+		jumpBufferMs: null,
+		inputToMotionFrames: null
+	};
+	const playerPath = first.probe.player.getPath();
+	let topSpeed = 0;
+	let latency = null;
+	if (move) {
+		const ramp = measureAccel(first.probe, move);
+		topSpeed = Number(ramp.top.toFixed(2));
+		latency = ramp.latencyFrames;
+	}
+	first.probe.session.dispose();
+	const fresh = async () => (await makeProbe(json, opts)).probe;
+	let toFull = null;
+	let toStop = null;
+	let turn = null;
+	if (move && topSpeed > .05) {
+		const a = await fresh();
+		if (a) {
+			toFull = timeToFullSpeed(a, move, topSpeed);
+			a.session.dispose();
+		}
+		const b = await fresh();
+		if (b) {
+			toStop = timeToStop(b, move, topSpeed);
+			b.session.dispose();
+		}
+		const c = await fresh();
+		if (c) {
+			turn = turnaround(c, move, topSpeed);
+			c.session.dispose();
+		}
+	}
+	let shape = {
+		apex: null,
+		toApexMs: null,
+		airtimeMs: null
+	};
+	let coyote = null;
+	let buffer = null;
+	if (jump) {
+		const d = await fresh();
+		if (d) {
+			shape = jumpShape(d, jump);
+			d.session.dispose();
+		}
+		coyote = await measureCoyote(json, opts, jump);
+		buffer = await measureBuffer(json, opts, jump);
+	}
+	return {
+		player: playerPath,
+		moveAction: move,
+		jumpAction: jump,
+		topSpeed,
+		timeToFullSpeedMs: toFull,
+		timeToStopMs: toStop,
+		turnaroundMs: turn,
+		jumpApex: shape.apex,
+		timeToApexMs: shape.toApexMs,
+		airtimeMs: shape.airtimeMs,
+		coyoteMs: coyote,
+		jumpBufferMs: buffer,
+		inputToMotionFrames: latency
+	};
+}
+const ms = (v) => v === null ? "—" : `${v} ms`;
+/** Numbers, not grades. What "good" means here is a genre decision. */
+function feelText(report) {
+	if (!report.player) return "feel: no player found — this needs a body with a CharacterController, a node in group \"player\", or one named Player.";
+	const lines = [];
+	lines.push(`feel of ${report.player}`);
+	lines.push("");
+	lines.push(`  top speed        ${report.topSpeed} u/s`);
+	lines.push(`  to full speed    ${ms(report.timeToFullSpeedMs)}`);
+	lines.push(`  to a stop        ${ms(report.timeToStopMs)}`);
+	lines.push(`  turnaround       ${ms(report.turnaroundMs)}`);
+	lines.push(`  input → motion   ${report.inputToMotionFrames === null ? "—" : `${report.inputToMotionFrames} frame(s)`}`);
+	if (report.jumpAction) {
+		lines.push("");
+		lines.push(`  jump apex        ${report.jumpApex === null ? "— (nothing left the ground)" : `${report.jumpApex} u`}`);
+		lines.push(`  time to apex     ${ms(report.timeToApexMs)}`);
+		lines.push(`  airtime          ${ms(report.airtimeMs)}`);
+		lines.push(`  coyote window    ${report.coyoteMs === null ? "always (no window)" : ms(report.coyoteMs)}`);
+		lines.push(`  jump buffer      ${report.jumpBufferMs === null ? "always (no window)" : ms(report.jumpBufferMs)}`);
+		if (report.coyoteMs === 0) {
+			lines.push("");
+			lines.push("  note: coyote window is 0 — a jump that only fires while the ground check");
+			lines.push("        is true reads to players as unresponsive controls. Try coyoteSeconds: 0.12.");
+		}
+		if (report.jumpBufferMs === 0) {
+			lines.push("  note: jump buffer is 0 — a press a few frames before landing is thrown away.");
+			lines.push("        Try jumpBufferSeconds: 0.15.");
+		}
+	}
+	return lines.join("\n");
+}
+//#endregion
+//#region src/test/index.ts
+/**
+* incanto/test — the browserless verification harness.
+*
+* The agent loop is "author → VERIFY → fix", and production environments
+* (e.g. the agent8 VM) have no browser. This module makes the scene state
+* itself the screenshot:
+*
+* - `validateScene(json)`  — every hard load error, without a browser
+* - `runScript(json, ...)` — scripted play by ACTION intent at a fixed
+*   timestep, with inline assertions and periodic snapshots
+* - `captureScene(scene)` / `describeCapture(capture)` — a structural,
+*   grep-able "text screenshot" of the live tree
+*
+* Deterministic by construction: fixed timestep, seeded `engine.rng`,
+* no requestAnimationFrame.
+*/
+/** Node types whose whole job is to sit on the ground. Characters, water,
+* clouds, birds and lights are all legitimately off it. */
+const GROUNDED_TYPES = ["MeshInstance3D", "InstancedMesh3D"];
+/** Under one of these, the BODY owns where the thing stands — a character's
+* skin hangs at whatever offset its rig wants, and is not a floating prop. */
+const BODY_OWNED = new Set([
+	"CharacterBody3D",
+	"RigidBody3D",
+	"StaticBody3D",
+	"AreaBody3D"
+]);
+/**
+* Every prop that is floating or buried.
+*
+* THE most repeated mistake in scene authoring, by humans and agents alike, is
+* a hand-computed Y: correct when it is written and wrong the moment anything
+* reshapes the ground under it — a river carving its bed, a new seed, a
+* generator that mirrors a carve slightly differently. This is the check that
+* catches it, and `snapToGround` is the fix that stops it happening.
+*
+* Anything explicitly marked `snapToGround: false` is skipped: that is the
+* author saying "yes, this hangs in the air", which a bridge deck, a lantern
+* and a cloud all legitimately do.
+*
+* ```ts
+* const off = findFloatingProps(gameJson);
+* ok(`nothing floats (${off.length})`, off.length === 0);
+* ```
+*/
+function findFloatingProps(json, opts = {}) {
+	registerAllNodes();
+	const tolerance = opts.tolerance ?? .1;
+	const types = new Set(opts.types ?? GROUNDED_TYPES);
+	let scene;
+	try {
+		scene = loadScene(json);
+	} catch {
+		return [];
+	}
+	let ground = null;
+	const findGround = (node) => {
+		if (!ground && node.constructor.typeName === "Terrain3D" && typeof node.heightAt === "function") ground = node;
+		for (const child of node.children) findGround(child);
+	};
+	findGround(scene.root);
+	if (!ground) return [];
+	const out = [];
+	const walk = (node, path, ox, oy, oz, yaw, bodyOwned) => {
+		const n = node;
+		let wx = ox;
+		let wy = oy;
+		let wz = oz;
+		let ownYaw = yaw;
+		if (Array.isArray(n.position)) {
+			const c = Math.cos(yaw);
+			const s = Math.sin(yaw);
+			const lx = n.position[0] ?? 0;
+			const lz = n.position[2] ?? 0;
+			wx = ox + lx * c + lz * s;
+			wz = oz - lx * s + lz * c;
+			wy = oy + (n.position[1] ?? 0);
+			ownYaw = yaw + (n.rotation?.[1] ?? 0) * Math.PI / 180;
+		}
+		const type = node.constructor.typeName ?? "";
+		const soil = ground;
+		if (types.has(type) && n.visible !== false && n.snapToGround !== false && !bodyOwned) {
+			const rows = node.transforms;
+			if (Array.isArray(rows) && rows.length > 0) {
+				let worst = null;
+				for (const row of rows) {
+					const scale = row[4] ?? 1;
+					const half = (n.size?.[1] ?? 0) * scale / 2;
+					const gap = wy + (row[1] ?? 0) - half - soil.heightAt(wx + (row[0] ?? 0), wz + (row[2] ?? 0));
+					if (Math.abs(gap) > tolerance && (!worst || Math.abs(gap) > Math.abs(worst.gap))) worst = {
+						path,
+						gap: Math.round(gap * 100) / 100
+					};
+				}
+				if (worst) out.push(worst);
+			} else {
+				const half = (n.size?.[1] ?? 0) / 2;
+				const gap = wy - half - soil.heightAt(wx, wz);
+				if (Math.abs(gap) > tolerance) out.push({
+					path,
+					gap: Math.round(gap * 100) / 100
+				});
+			}
+		}
+		const childBodyOwned = bodyOwned || BODY_OWNED.has(type);
+		for (const child of node.children) walk(child, `${path}/${child.name}`, wx, wy, wz, ownYaw, childBodyOwned);
+	};
+	walk(scene.root, `/${scene.root.name}`, 0, 0, 0, 0, false);
+	return out;
+}
+function registerAllNodes() {
+	registerNodes2D();
+	registerNodes3D();
+	registerNodesNet();
+	registerGameplayBehaviors();
+}
+/** Snapshot the live tree: every node, every schema prop's current value. */
+function captureScene(scene) {
+	const nodes = [];
+	const walk = (node) => {
+		const ctor = node.constructor;
+		const schema = mergeStaticProps(ctor);
+		const props = {};
+		for (const key of Object.keys(schema)) props[key] = jsonClone(node[key]);
+		const capture = {
+			path: node.getPath(),
+			type: ctor.typeName,
+			props
+		};
+		if (node.uid) capture.uid = node.uid;
+		if (node.groups.size > 0) capture.groups = [...node.groups];
+		if (Object.keys(node.tags).length > 0) capture.tags = jsonClone(node.tags);
+		if (typeof node.script?.name === "string") capture.script = node.script.name;
+		nodes.push(capture);
+		for (const child of node.children) walk(child);
+	};
+	walk(scene.root);
+	const out = {
+		name: scene.name,
+		nodes
+	};
+	if (scene.dimension) out.dimension = scene.dimension;
+	return out;
+}
+/**
+* Render a capture as one grep-able line per node, showing only NON-DEFAULT
+* props — the same delta discipline as scene JSON, so the interesting state
+* stands out.
+*/
+function describeCapture(capture) {
+	const lines = [`scene ${capture.name}${capture.dimension ? ` (${capture.dimension})` : ""}`];
+	for (const node of capture.nodes) {
+		const schema = defaultsFor(node.type);
+		const deltas = Object.entries(node.props).filter(([key, value]) => !schema || !jsonEquals(value, schema[key]?.default ?? null)).map(([key, value]) => `${key}=${JSON.stringify(value)}`);
+		const extras = [
+			node.script ? `script=${node.script}` : "",
+			node.groups ? `groups=${node.groups.join(",")}` : "",
+			...deltas
+		].filter(Boolean);
+		lines.push(`${node.path} ${node.type}${extras.length ? ` ${extras.join(" ")}` : ""}`);
+	}
+	return lines.join("\n");
+}
+function defaultsFor(typeName) {
+	try {
+		return getNodeSchema(typeName);
+	} catch {
+		return null;
+	}
+}
+/**
+* Run every hard load-time check headlessly. Unregistered behaviors are
+* stubbed by default (structure-only validation, no TypeScript needed) —
+* pass the real classes via `behaviors` to validate script props too.
+*/
+/**
+* `environment.preset` is resolved deep inside Renderer3D, which no headless
+* tool reaches — so a typo there passed `incanto-check` and hard-failed at boot.
+* It cannot live in the core loader (core must never import 3d), but it belongs
+* exactly here: the test entry already registers the 3D nodes.
+*/
+function checkEnvironment(json) {
+	const env = json?.environment;
+	if (!env || typeof env !== "object") return;
+	if (env.preset === void 0) return;
+	if (typeof env.preset !== "string") throw new IncantoError("BAD_FORMAT", `Scene "environment.preset" must be a string, got ${JSON.stringify(env.preset)}.`);
+	try {
+		resolveEnvironmentHdri(env);
+	} catch (error) {
+		throw new IncantoError("BAD_FORMAT", error instanceof Error ? error.message : String(error));
+	}
+}
+function validateScene(json, opts = {}) {
+	registerAllNodes();
+	for (const [name, ctor] of Object.entries(opts.behaviors ?? {})) registerBehavior(name, ctor, { replace: true });
+	try {
+		checkEnvironment(json);
+		loadScene(json, {
+			resolveScene: opts.resolveScene,
+			stubMissingBehaviors: !opts.strictBehaviors
+		}).root.free();
+		return { ok: true };
+	} catch (e) {
+		if (e instanceof IncantoError) return {
+			ok: false,
+			error: e
+		};
+		throw e;
+	}
+}
+/**
+* Load a scene and play it headlessly at a fixed timestep, driving input by
+* ACTION intent. This is the e2e loop without a browser: script → simulate →
+* snapshot → assert.
+*/
+async function runScript(json, opts) {
+	registerAllNodes();
+	for (const [name, ctor] of Object.entries(opts.behaviors ?? {})) registerBehavior(name, ctor, { replace: true });
+	const engine = new Engine({
+		seed: opts.seed,
+		fixedHz: opts.fixedHz,
+		scheduler: () => () => {}
+	});
+	const scene = loadScene(structuredClone(json), { resolveScene: opts.resolveScene });
+	engine.setScene(scene);
+	const physics = opts.physics ?? "auto";
+	if (physics === "2d" || physics === "auto" && scene.dimension === "2d") {
+		const { enablePhysics2D } = await import("./physics-2d-OfKb0PV_.js").then((n) => n.r);
+		await enablePhysics2D(engine);
+	} else if (physics === "3d" || physics === "auto" && scene.dimension === "3d") {
+		const { enablePhysics3D } = await import("./physics-3d-C8242nXr.js").then((n) => n.r);
+		await enablePhysics3D(engine);
+	}
+	const failures = [];
+	const snapshots = [];
+	const ctx = {
+		engine,
+		scene,
+		timeMs: 0,
+		getNode: (path) => scene.root.getNode(path),
+		capture: () => captureScene(scene)
+	};
+	const applyStep = (step) => {
+		if (step.press) engine.input.pressAction(step.press);
+		if (step.release) engine.input.releaseAction(step.release);
+		if (step.vector) engine.input.setActionVector(...step.vector);
+		if (step.key) engine.input.handleKey(step.key[0], step.key[1]);
+		step.do?.(ctx);
+		if (step.assert) try {
+			if (step.assert(ctx) === false) failures.push({
+				atMs: step.atMs,
+				label: step.label,
+				message: "assert returned false"
+			});
+		} catch (e) {
+			failures.push({
+				atMs: step.atMs,
+				label: step.label,
+				message: e instanceof Error ? e.message : String(e)
+			});
+		}
+	};
+	const stepMs = 1e3 / (opts.fixedHz ?? 60);
+	const totalTicks = Math.round(opts.durationMs / stepMs);
+	const steps = [...opts.steps ?? []].sort((a, b) => a.atMs - b.atMs);
+	let stepIndex = 0;
+	let nextSnapshot = opts.snapshotEveryMs ?? Number.POSITIVE_INFINITY;
+	for (let i = 1; i <= totalTicks; i++) {
+		const t = i * stepMs;
+		ctx.timeMs = t;
+		while (stepIndex < steps.length && steps[stepIndex].atMs <= t) {
+			applyStep(steps[stepIndex]);
+			stepIndex += 1;
+		}
+		engine.step();
+		if (t >= nextSnapshot - 1e-6) {
+			snapshots.push({
+				atMs: Math.round(t),
+				capture: captureScene(scene)
+			});
+			nextSnapshot += opts.snapshotEveryMs;
+		}
+	}
+	for (; stepIndex < steps.length; stepIndex++) {
+		const missed = steps[stepIndex];
+		failures.push({
+			atMs: missed.atMs,
+			label: missed.label,
+			message: `step never executed — atMs ${missed.atMs} is beyond the ${opts.durationMs}ms run`
+		});
+	}
+	const finalCapture = captureScene(scene);
+	const logs = [...engine.log.entries()];
+	const swallowed = engine.stats().errors;
+	if (swallowed > 0) failures.push({
+		atMs: opts.durationMs,
+		label: "engine",
+		message: `${swallowed} error(s) were swallowed to keep the loop alive — the logs above name the node, the behavior and the phase`
+	});
+	engine.dispose();
+	const ok = failures.length === 0;
+	return {
+		ok,
+		failures,
+		snapshots,
+		logs,
+		finalCapture,
+		describe: () => {
+			const engineWarnings = logs.filter((l) => l.level === "warn" || l.level === "error");
+			const head = `run ${ok ? "OK" : "FAILED"} — ${opts.durationMs}ms simulated, ${failures.length} failure(s), ${logs.length} log(s)`;
+			const fails = failures.map((f) => `  ✗ at ${f.atMs}ms${f.label ? ` [${f.label}]` : ""}: ${f.message}`);
+			const noisy = engineWarnings.map((l) => `  ! ${l.level}: ${l.parts.map((p) => typeof p === "string" ? p : String(p)).join(" ")}`);
+			return [
+				head,
+				...fails,
+				...noisy,
+				describeCapture(finalCapture)
+			].join("\n");
+		}
+	};
+}
+/**
+* The headless play loop behind `incanto-play`: load → feed inputs by intent
+* (`session.engine.input.pressAction(...)`) → `step(ms)` → `capture()` the
+* state AS A SCENE FILE. What a screenshot is to humans, the capture is to
+* agents: complete, structured, and in the exact format they already read.
+*/
+async function createPlaySession(json, opts = {}) {
+	registerAllNodes();
+	for (const [name, ctor] of Object.entries(opts.behaviors ?? {})) registerBehavior(name, ctor, { replace: true });
+	const engine = new Engine({
+		seed: opts.seed,
+		fixedHz: opts.fixedHz,
+		scheduler: () => () => {}
+	});
+	const scene = loadScene(structuredClone(json), {
+		resolveScene: opts.resolveScene,
+		stubMissingBehaviors: opts.stubMissingBehaviors,
+		engine
+	});
+	engine.setScene(scene);
+	const physics = opts.physics ?? "auto";
+	if (physics === "2d" || physics === "auto" && scene.dimension === "2d") {
+		const { enablePhysics2D } = await import("./physics-2d-OfKb0PV_.js").then((n) => n.r);
+		await enablePhysics2D(engine);
+	} else if (physics === "3d" || physics === "auto" && scene.dimension === "3d") {
+		const { enablePhysics3D } = await import("./physics-3d-C8242nXr.js").then((n) => n.r);
+		await enablePhysics3D(engine);
+	}
+	const stepMs = 1e3 / (opts.fixedHz ?? 60);
+	let timeMs = 0;
+	let logCursor = 0;
+	return {
+		engine,
+		scene,
+		get timeMs() {
+			return timeMs;
+		},
+		step(ms) {
+			const ticks = Math.max(1, Math.round(ms / stepMs));
+			for (let i = 0; i < ticks; i++) engine.step();
+			timeMs += ticks * stepMs;
+		},
+		capture() {
+			return scene.toJSON();
+		},
+		describe() {
+			return describeCapture(captureScene(scene));
+		},
+		framing() {
+			return framingText(describeFraming(scene));
+		},
+		drainLogs() {
+			const all = engine.log.entries();
+			const fresh = all.filter((e) => e.seq > logCursor);
+			if (all.length > 0) logCursor = all[all.length - 1].seq;
+			return [...fresh];
+		},
+		dispose() {
+			engine.dispose();
+		}
+	};
+}
+//#endregion
+export { registerAllNodes as a, feelReport as c, findPlayer as d, playtest as f, framingText as h, findFloatingProps as i, feelText as l, describeFraming as m, createPlaySession as n, runScript as o, playtestText as p, describeCapture as r, validateScene as s, captureScene as t, failingReplays as u };