incanto 0.31.0 → 0.33.0

package/dist/test-BRxLd2jH.js

@@ -0,0 +1,642 @@
+import { n as loadScene, y as registerBehavior } from "./loader-Buk8Bu1h.js";
+import { h as Engine } from "./register-CscIzJEO.js";
+import { t as IncantoError } from "./errors-BpWbnbb_.js";
+import { n as jsonEquals, t as jsonClone } from "./json-BLk7H2Qa.js";
+import { i as getNodeSchema, s as mergeStaticProps } from "./registry-CJdGpT2V.js";
+import { n as registerGameplayBehaviors } from "./gameplay-BpQCbABv.js";
+import { t as registerNodes2D } from "./register-FIJtNbub.js";
+import { n as registerNodes3D, t as resolveEnvironmentHdri } from "./environment-presets-CQtEGogB.js";
+import { t as registerNodesNet } from "./register-CtI-itec.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/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-DjXR5DMu.js").then((n) => n.r);
+		await enablePhysics2D(engine);
+	} else if (physics === "3d" || physics === "auto" && scene.dimension === "3d") {
+		const { enablePhysics3D } = await import("./physics-3d-DF8npb1O.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-DjXR5DMu.js").then((n) => n.r);
+		await enablePhysics2D(engine);
+	} else if (physics === "3d" || physics === "auto" && scene.dimension === "3d") {
+		const { enablePhysics3D } = await import("./physics-3d-DF8npb1O.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, describeFraming as c, findFloatingProps as i, framingText as l, createPlaySession as n, runScript as o, describeCapture as r, validateScene as s, captureScene as t };