incanto 0.42.0 → 0.44.0

package/dist/frame-report-Ct8XgsmV.d.ts

@@ -0,0 +1,80 @@
+//#region src/3d/frame-report.d.ts
+/**
+* What the frame looks like, as something worth saying.
+*
+* The pixels are not the deliverable. A 1280x720 frame is 2.8 million numbers:
+* unreadable by a person, unaffordable for a model (roughly a thousand tokens
+* as an image, roughly a million as text). The deliverable is the JUDGEMENT —
+* black screen, one flat colour, washed out — and the numbers behind it, small
+* enough to print and compare.
+*
+* Same principle as `framing`'s "lit by: NOTHING": a report is a sentence
+* before it is a number, because a number needs a reader who already knows what
+* to compare it against.
+*
+* Pure arithmetic over an RGBA buffer — no three, no DOM, no GPU. Whoever has
+* the pixels calls this; in practice that is the browser holding the canvas.
+*/
+/** Per-cell mean colour, `[r, g, b]` 0..255. */
+type GridCell = [number, number, number];
+interface FrameStats {
+  width: number;
+  height: number;
+  /** Every pixel below the black threshold — the render produced nothing. */
+  black: boolean;
+  /** One colour everywhere: a clear-colour fill, or a camera inside geometry. */
+  uniform: boolean;
+  /** 0..1 mean relative luminance. */
+  meanLuma: number;
+  /** Coarse mean colour per cell, rows top to bottom. */
+  grid: GridCell[][];
+}
+interface FrameStatsOptions {
+  /** Cells across and down. Default 16x9 — 144 cells, printable. */
+  grid?: [number, number];
+}
+declare function frameStats(pixels: Uint8Array | Uint8ClampedArray, width: number, height: number, opts?: FrameStatsOptions): FrameStats;
+/** The report a person or an agent reads. Verdict first, numbers after. */
+declare function frameText(stats: FrameStats): string;
+/**
+* Comparison resolution. Fine enough that a one-pixel line moves a cell by
+* several levels at 720p, small enough (6912 bytes) to hold and to send.
+*/
+declare const SIGNATURE_GRID: readonly [number, number];
+interface FrameSignature {
+  /** The frame this was made from — a different size is not comparable. */
+  width: number;
+  height: number;
+  cols: number;
+  rows: number;
+  /** base64 of `cols * rows * 3` bytes: cell means, rows top to bottom. */
+  data: string;
+}
+interface FrameDiff {
+  /** False when the two cannot be subtracted at all; see `reason`. */
+  comparable: boolean;
+  reason?: string;
+  /** 0..1 fraction of cells that moved past the threshold. */
+  changed: number;
+  /** Largest single-channel move, 0..255. */
+  maxDelta: number;
+  /** Mean single-channel move across the frame, 0..255. */
+  meanDelta: number;
+  /** Where the change is, in pixels of the compared frame. */
+  box: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+  } | null;
+  /** A thin full-length band is worth naming: that is what a seam looks like. */
+  shape: "vertical band" | "horizontal band" | null;
+}
+declare function frameSignature(pixels: Uint8Array | Uint8ClampedArray, width: number, height: number, grid?: readonly [number, number]): FrameSignature;
+declare function diffSignatures(before: FrameSignature, after: FrameSignature, opts?: {
+  threshold?: number;
+}): FrameDiff;
+/** The comparison a person or an agent reads. */
+declare function diffText(diff: FrameDiff): string;
+//#endregion
+export { GridCell as a, diffText as c, frameText as d, FrameStatsOptions as i, frameSignature as l, FrameSignature as n, SIGNATURE_GRID as o, FrameStats as r, diffSignatures as s, FrameDiff as t, frameStats as u };

package/dist/frame-report-Lr3VO24R.js

@@ -0,0 +1,197 @@
+//#region src/3d/frame-report.ts
+/** Rec. 709 relative luminance of an 8-bit triple, 0..1. */
+function luma(r, g, b) {
+	return (.2126 * r + .7152 * g + .0722 * b) / 255;
+}
+/**
+* A pixel this dark is indistinguishable from "nothing was drawn". Not zero:
+* a real render of a night scene still lands a few levels above black, and
+* calling that a failure would make the check useless where it matters most.
+*/
+const BLACK_LEVEL = .012;
+/** Cell-to-cell luminance range below this: the frame is one flat colour. */
+const UNIFORM_EPSILON = .004;
+/**
+* Mean colour of every cell of a `cols` x `rows` box filter, as a flat
+* `cols * rows * 3` byte array, rows top to bottom.
+*
+* The one place a frame is reduced. Both the printable report and the
+* comparison signature are this at different resolutions, so a boundary that
+* moves moves for both.
+*/
+function cellMeans(pixels, width, height, cols, rows) {
+	const out = new Uint8Array(cols * rows * 3);
+	for (let row = 0; row < rows; row++) for (let col = 0; col < cols; col++) {
+		const x0 = Math.floor(col * width / cols);
+		const x1 = Math.max(x0 + 1, Math.floor((col + 1) * width / cols));
+		const y0 = Math.floor(row * height / rows);
+		const y1 = Math.max(y0 + 1, Math.floor((row + 1) * height / rows));
+		let r = 0;
+		let g = 0;
+		let b = 0;
+		let n = 0;
+		for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) {
+			const i = (y * width + x) * 4;
+			r += pixels[i] ?? 0;
+			g += pixels[i + 1] ?? 0;
+			b += pixels[i + 2] ?? 0;
+			n += 1;
+		}
+		const o = (row * cols + col) * 3;
+		out[o] = Math.round(r / n);
+		out[o + 1] = Math.round(g / n);
+		out[o + 2] = Math.round(b / n);
+	}
+	return out;
+}
+function frameStats(pixels, width, height, opts = {}) {
+	const [cols, rows] = opts.grid ?? [16, 9];
+	const means = cellMeans(pixels, width, height, cols, rows);
+	const grid = [];
+	let total = 0;
+	let maxLuma = 0;
+	let minLuma = 1;
+	for (let row = 0; row < rows; row++) {
+		const line = [];
+		for (let col = 0; col < cols; col++) {
+			const o = (row * cols + col) * 3;
+			const cell = [
+				means[o],
+				means[o + 1],
+				means[o + 2]
+			];
+			const cellLuma = luma(cell[0], cell[1], cell[2]);
+			total += cellLuma;
+			maxLuma = Math.max(maxLuma, cellLuma);
+			minLuma = Math.min(minLuma, cellLuma);
+			line.push(cell);
+		}
+		grid.push(line);
+	}
+	const cells = cols * rows;
+	const meanLuma = total / cells;
+	return {
+		width,
+		height,
+		black: maxLuma <= BLACK_LEVEL,
+		uniform: maxLuma - minLuma < UNIFORM_EPSILON,
+		meanLuma: Math.round(meanLuma * 1e3) / 1e3,
+		grid
+	};
+}
+/** The report a person or an agent reads. Verdict first, numbers after. */
+function frameText(stats) {
+	const lines = [];
+	if (stats.black) lines.push("BLACK SCREEN — nothing was drawn (no light, no camera, or nothing in view)");
+	else if (stats.uniform) lines.push("one flat colour — the camera may be inside geometry, or only the sky is drawn");
+	lines.push(`frame ${stats.width}×${stats.height} · luminance ${stats.meanLuma.toFixed(2)}`);
+	return lines.join("\n");
+}
+/**
+* Comparison resolution. Fine enough that a one-pixel line moves a cell by
+* several levels at 720p, small enough (6912 bytes) to hold and to send.
+*/
+const SIGNATURE_GRID = [64, 36];
+/**
+* Below this, a cell has not changed. Compression, dithering and the last bit
+* of a tonemap all wander by a level or two between two captures of the same
+* still frame; calling that a change would bury the real one.
+*/
+const DIFF_THRESHOLD = 3;
+function frameSignature(pixels, width, height, grid = SIGNATURE_GRID) {
+	const [cols, rows] = grid;
+	return {
+		width,
+		height,
+		cols,
+		rows,
+		data: toBase64(cellMeans(pixels, width, height, cols, rows))
+	};
+}
+function diffSignatures(before, after, opts = {}) {
+	const none = {
+		changed: 0,
+		maxDelta: 0,
+		meanDelta: 0,
+		box: null,
+		shape: null
+	};
+	if (before.width !== after.width || before.height !== after.height) return {
+		comparable: false,
+		reason: `frame size changed: ${before.width}×${before.height} → ${after.width}×${after.height}`,
+		...none
+	};
+	if (before.cols !== after.cols || before.rows !== after.rows) return {
+		comparable: false,
+		reason: "signature grid changed",
+		...none
+	};
+	const threshold = opts.threshold ?? DIFF_THRESHOLD;
+	const a = fromBase64(before.data);
+	const b = fromBase64(after.data);
+	const { cols, rows } = after;
+	let changedCells = 0;
+	let maxDelta = 0;
+	let totalDelta = 0;
+	let minCol = cols;
+	let maxCol = -1;
+	let minRow = rows;
+	let maxRow = -1;
+	for (let row = 0; row < rows; row++) for (let col = 0; col < cols; col++) {
+		const o = (row * cols + col) * 3;
+		const delta = Math.max(Math.abs((a[o] ?? 0) - (b[o] ?? 0)), Math.abs((a[o + 1] ?? 0) - (b[o + 1] ?? 0)), Math.abs((a[o + 2] ?? 0) - (b[o + 2] ?? 0)));
+		totalDelta += delta;
+		maxDelta = Math.max(maxDelta, delta);
+		if (delta >= threshold) {
+			changedCells += 1;
+			minCol = Math.min(minCol, col);
+			maxCol = Math.max(maxCol, col);
+			minRow = Math.min(minRow, row);
+			maxRow = Math.max(maxRow, row);
+		}
+	}
+	const cells = cols * rows;
+	const box = maxCol < 0 ? null : {
+		x: Math.floor(minCol * after.width / cols),
+		y: Math.floor(minRow * after.height / rows),
+		w: Math.ceil((maxCol + 1 - minCol) * after.width / cols),
+		h: Math.ceil((maxRow + 1 - minRow) * after.height / rows)
+	};
+	const spanCols = maxCol < 0 ? 0 : maxCol + 1 - minCol;
+	const spanRows = maxRow < 0 ? 0 : maxRow + 1 - minRow;
+	return {
+		comparable: true,
+		changed: changedCells / cells,
+		maxDelta,
+		meanDelta: Math.round(totalDelta / cells * 10) / 10,
+		box,
+		shape: spanCols > 0 && spanCols <= 2 && spanRows >= rows / 2 ? "vertical band" : spanRows > 0 && spanRows <= 2 && spanCols >= cols / 2 ? "horizontal band" : null
+	};
+}
+/** The comparison a person or an agent reads. */
+function diffText(diff) {
+	if (!diff.comparable) return `cannot compare — ${diff.reason ?? "unknown reason"}`;
+	if (diff.changed === 0) return `identical — nothing moved (largest cell shift ${diff.maxDelta}/255)`;
+	const lines = [`changed ${(diff.changed * 100).toFixed(1)}% of the frame · largest shift ${diff.maxDelta}/255, mean ${diff.meanDelta}`];
+	if (diff.box) {
+		const { x, y, w, h } = diff.box;
+		lines.push(`region x ${x}..${x + w}, y ${y}..${y + h}${diff.shape ? ` — a ${diff.shape}` : ""}`);
+	}
+	if (diff.changed > .9) lines.push("the whole frame moved — if the scene is animating, pause it first (debug ☰ → Time → Pause) so the comparison is of your change, not of time passing");
+	return lines.join("\n");
+}
+/** Portable in a browser and in node; both have had `btoa`/`atob` for years. */
+function toBase64(bytes) {
+	let binary = "";
+	const CHUNK = 32768;
+	for (let i = 0; i < bytes.length; i += CHUNK) binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+	return btoa(binary);
+}
+function fromBase64(text) {
+	const binary = atob(text);
+	const out = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+	return out;
+}
+//#endregion
+export { frameStats as a, frameSignature as i, diffSignatures as n, frameText as o, diffText as r, SIGNATURE_GRID as t };

package/dist/{gameplay-DRi9524r.js → gameplay-BQOeAid6.js}

@@ -4973,10 +4973,15 @@ var GameFlow = class extends Behavior {
 	static signals = ["flowChanged"];
 	static props = {
 		restartAction: { default: "restart" },
+		pauseAction: { default: "pause" },
 		freezeOnEnd: { default: true },
 		bannerPath: {
 			default: "%Banner",
 			nodePath: true
+		},
+		pausePanelPath: {
+			default: "%PauseMenu",
+			nodePath: true
 		}
 	};
 	/** Input action that restarts from gameover/won (declare it in `input{}`). */
@@ -4985,8 +4990,31 @@ var GameFlow = class extends Behavior {
 	freezeOnEnd = true;
 	/** Where the flow looks for a UiBanner ('' = never). */
 	bannerPath = "%Banner";
+	/**
+	* Input action that toggles pause (declare it in `input{}`; undeclared is
+	* fine and means pause is API-only).
+	*/
+	pauseAction = "pause";
+	/**
+	* A node shown while paused and hidden otherwise — a `UiPanel` of buttons in
+	* practice. '' turns the whole thing off.
+	*
+	* This lives here rather than in each game because it is identical in all of
+	* them, and a pause menu that costs a script is a pause menu no generated
+	* game will have. `UiPanel` appeared in zero template scenes before this.
+	*/
+	pausePanelPath = "%PauseMenu";
 	state = "playing";
 	frozeScale = false;
+	onReady() {
+		this.syncPausePanel();
+	}
+	/** The panel follows the state; nothing else may own its visibility. */
+	syncPausePanel() {
+		if (this.pausePanelPath === "") return;
+		const panel = this.node.getNodeOrNull(this.pausePanelPath);
+		if (panel && "visible" in panel) panel.visible = this.state === "paused";
+	}
 	gameOver(text = "GAME OVER", color = "#ef4444") {
 		this.transition("gameover", text, color);
 	}
@@ -4997,12 +5025,14 @@ var GameFlow = class extends Behavior {
 		if (this.state !== "playing") return;
 		this.state = "paused";
 		this.freeze();
+		this.syncPausePanel();
 		this.node.emit("flowChanged", this.state);
 	}
 	resume() {
 		if (this.state !== "paused") return;
 		this.state = "playing";
 		this.thaw();
+		this.syncPausePanel();
 		this.node.emit("flowChanged", this.state);
 	}
 	restart() {
@@ -5035,6 +5065,13 @@ var GameFlow = class extends Behavior {
 		this.engine.timeScale = 1;
 	}
 	update() {
+		if (this.state === "playing" || this.state === "paused") {
+			try {
+				if (this.engine.input.justPressed(this.pauseAction)) if (this.state === "playing") this.pause();
+				else this.resume();
+			} catch {}
+			return;
+		}
 		if (this.state !== "gameover" && this.state !== "won") return;
 		try {
 			if (this.engine.input.justPressed(this.restartAction)) this.restart();

package/dist/gameplay.d.ts

@@ -622,8 +622,25 @@ declare class GameFlow extends Behavior {
   freezeOnEnd: boolean;
   /** Where the flow looks for a UiBanner ('' = never). */
   bannerPath: string;
+  /**
+  * Input action that toggles pause (declare it in `input{}`; undeclared is
+  * fine and means pause is API-only).
+  */
+  pauseAction: string;
+  /**
+  * A node shown while paused and hidden otherwise — a `UiPanel` of buttons in
+  * practice. '' turns the whole thing off.
+  *
+  * This lives here rather than in each game because it is identical in all of
+  * them, and a pause menu that costs a script is a pause menu no generated
+  * game will have. `UiPanel` appeared in zero template scenes before this.
+  */
+  pausePanelPath: string;
   state: GameFlowState;
   private frozeScale;
+  override onReady(): void;
+  /** The panel follows the state; nothing else may own its visibility. */
+  private syncPausePanel;
   gameOver(text?: string, color?: string): void;
   win(text?: string, color?: string): void;
   pause(): void;

package/dist/gameplay.js

@@ -1,2 +1,2 @@
-import { C as FollowCamera, D as Health, E as DamageOnContact, O as Collector, S as restartScene, T as phaseOf, _ 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, k as Chase, 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 DayNight, x as goToScene, y as Interactable } from "./gameplay-DRi9524r.js";
+import { C as FollowCamera, D as Health, E as DamageOnContact, O as Collector, S as restartScene, T as phaseOf, _ 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, k as Chase, 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 DayNight, x as goToScene, y as Interactable } from "./gameplay-BQOeAid6.js";
 export { CameraShake, Chase, Collector, Cooldown, DamageOnContact, DayNight, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, Projectile, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, phaseOf, registerGameplayBehaviors, restartScene, screenFlash };

package/dist/index.js

@@ -7,7 +7,7 @@ import { n as jsonEquals, r as jsonKind, t as jsonClone } from "./json-BLk7H2Qa.
 import { a as getNodeSignals, c as mergeStaticSignals, i as getNodeSchema, l as registerNode, n as clearRegistry, o as getNodeType, r as createNode, u as registeredTypes } from "./registry-IyWCGe4q.js";
 import { t as createNoise2D } from "./noise-CGUMx44x.js";
 import { i as applyParticlePreset, n as PARTICLE_PRESETS, r as PARTICLE_PRESET_NAMES, t as ParticleSim } from "./particle-sim-Bw7hB93B.js";
-import { a as findPath, i as preloadUrls, n as newUid, o as gridFromRows, r as assetUrls, t as VERSION } from "./src-cU57Uwdw.js";
+import { a as findPath, i as preloadUrls, n as newUid, o as gridFromRows, r as assetUrls, t as VERSION } from "./src-B3n06SsL.js";
 import { i as resolveRendering, n as attachTouchControls, r as joystickVector, t as TouchControls } from "./touch-BoNg_MnF.js";
 import { t as duplicateNode } from "./duplicate-CRtihGmC.js";
 export { AudioBuses, AudioPlayer, BASE_LOCALE, Behavior, CONST_REF_KEY, Engine, HudLayer, IncantoError, InputMap, Localization, LogManager, MusicManager, Node, ORDER_GROUP_BASE, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, ParticleSim, ROLLOFF_MODELS, Rng, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, SaveSlots, Scene, SceneTree, Settings, SfxEngine, Signal, T_PREFIX, Timer, TouchControls, UiBanner, UiBar, UiButton, UiDialogue, UiImage, UiPanel, UiSelect, UiSlider, UiText, UiToggle, VERSION, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, auditScene, behaviorSchema, behaviorSignals, behaviorsWithoutSave, captureBehaviors, clearBehaviors, clearRegistry, computeViewport, createNode, createNoise2D, createSaveStore, crossfadeGains, duplicateNode, effectiveOrder, fadeGain, findPath, getBehavior, getNodeSchema, getNodeSignals, getNodeType, gridFromRows, isAudioContextAvailable, isConstRef, joystickVector, jsonClone, jsonEquals, jsonKind, loadScene, mergeStaticSignals, newUid, parseNodePath, preloadUrls, qualityEnvironment, readDeviceHints, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, replay, resolveConstants, resolveOrderGroups, resolveRendering, resolveViewport, restoreBehaviors, serializeNode, spatialGain, spatialPan, startRecording, suggestLocale, suggestQuality, synthSfx, translationKey };

package/dist/{physics-3d-C2G604O1.js → physics-3d-CLPFv99o.js}

@@ -1,9 +1,9 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
 import { v as diagnose } from "./loader-r49nDwB4.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { F as PhysicsBody3D, I as RigidBody3D, N as Area3D, P as CharacterBody3D, R as Node3D, z as validateCollider3D } from "./gameplay-DRi9524r.js";
+import { F as PhysicsBody3D, I as RigidBody3D, N as Area3D, P as CharacterBody3D, R as Node3D, z as validateCollider3D } from "./gameplay-BQOeAid6.js";
 import { n as registerDebugSource } from "./debug-draw-BM3DsvtT.js";
-import { A as Terrain3D, F as InstancedMesh3D, L as buildMeshGeometry, P as Joint3D } from "./environment-presets-Vl5xBsXp.js";
+import { A as Terrain3D, F as InstancedMesh3D, L as buildMeshGeometry, P as Joint3D } from "./environment-presets-Ds5kXLoF.js";
 import { Euler, Matrix4, Quaternion, Vector3 } from "three";
 //#region src/3d/physics/collider-lines.ts
 /**

package/dist/react.js

@@ -156,7 +156,7 @@ function IncantoCanvas(props) {
 				pointer: latest.pointer,
 				...keyboard !== void 0 ? { keyboard } : {}
 			};
-			const next = await (_gameFactory ?? (mode === "3d" ? async (o) => (await import("./create-game-DItIRyXH.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-9KPppR0L.js").then((n) => n.n)).createGame2D(o)))(opts);
+			const next = await (_gameFactory ?? (mode === "3d" ? async (o) => (await import("./create-game-D90pyPMx.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-DFRbG0Bj.js").then((n) => n.n)).createGame2D(o)))(opts);
 			if (disposed) {
 				next.dispose();
 				return;

package/dist/{src-cU57Uwdw.js → src-B3n06SsL.js}

@@ -161,6 +161,6 @@ function newUid() {
 //#endregion
 //#region src/index.ts
 /** Engine version. Kept in sync with package.json by the release pipeline. */
-const VERSION = "0.42.0";
+const VERSION = "0.44.0";
 //#endregion
 export { findPath as a, preloadUrls as i, newUid as n, gridFromRows as o, assetUrls as r, VERSION as t };

package/dist/{teardown-CCtAMDLB.js → teardown-yePMOE1K.js}

@@ -238,6 +238,37 @@ function poseFromRenderer(renderer, fallbackDistance = 8) {
 	};
 }
 //#endregion
+//#region src/core/pause-when-hidden.ts
+function pauseWhenHidden(engine, doc = typeof document === "undefined" ? null : document) {
+	if (!doc) return () => {};
+	/** The scale to come back to — null when we did not pause anything. */
+	let heldScale = null;
+	let mutedByUs = false;
+	const onChange = () => {
+		if (doc.hidden) {
+			if (heldScale === null && engine.timeScale > 0) {
+				heldScale = engine.timeScale;
+				engine.timeScale = 0;
+			}
+			if (!engine.audio.muted) {
+				engine.audio.muted = true;
+				mutedByUs = true;
+			}
+			return;
+		}
+		if (heldScale !== null) {
+			if (engine.timeScale === 0) engine.timeScale = heldScale;
+			heldScale = null;
+		}
+		if (mutedByUs) {
+			engine.audio.muted = false;
+			mutedByUs = false;
+		}
+	};
+	doc.addEventListener("visibilitychange", onChange);
+	return () => doc.removeEventListener("visibilitychange", onChange);
+}
+//#endregion
 //#region src/core/teardown.ts
 function teardown(steps, onError = defaultReport) {
 	const failures = [];
@@ -262,4 +293,4 @@ function defaultReport(what, error) {
 	console.error(`[incanto] teardown: ${what} failed (continuing)`, error);
 }
 //#endregion
-export { poseFromRenderer as a, openBundledEditor as i, crossFade as n, devServerLibrary as r, teardown as t };
+export { openBundledEditor as a, devServerLibrary as i, pauseWhenHidden as n, poseFromRenderer as o, crossFade as r, teardown as t };

package/dist/{test-DuOD1DO8.js → test-BMgiiD5i.js}

@@ -4,9 +4,9 @@ import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { n as startRecording } from "./replay-DilbZgQI.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-DRi9524r.js";
+import { n as registerGameplayBehaviors } from "./gameplay-BQOeAid6.js";
 import { t as registerNodes2D } from "./register-R2JTnIMw.js";
-import { n as registerNodes3D, t as resolveEnvironmentHdri } from "./environment-presets-Vl5xBsXp.js";
+import { n as registerNodes3D, t as resolveEnvironmentHdri } from "./environment-presets-Ds5kXLoF.js";
 import { t as registerNodesNet } from "./register-D651it1J.js";
 import { Box3, Euler, Matrix4, PerspectiveCamera, Quaternion, Vector3 } from "three";
 //#region src/test/framing.ts
@@ -651,6 +651,118 @@ function failingReplays(report) {
 	}));
 }
 //#endregion
+//#region src/test/facing.ts
+const DEG2RAD = Math.PI / 180;
+/** The forward vector of a yaw (degrees) for a given art convention. */
+function forwardOf(yawDeg, axis) {
+	const yaw = yawDeg * DEG2RAD;
+	const base = [Math.sin(yaw), Math.cos(yaw)];
+	switch (axis) {
+		case "-z": return [-base[0], -base[1]];
+		case "+x": return [base[1], -base[0]];
+		case "-x": return [-base[1], base[0]];
+		default: return base;
+	}
+}
+/**
+* The skin, and the yaw the art is DECLARED to be rotated by.
+*
+* `skinYawOffset` is how a model that does not face +Z says so, and it is the
+* supported fix rather than a bug. Subtracting it is what stops this check
+* crying wolf on every correctly-configured non-+Z model.
+*/
+function findSkin(player, explicit) {
+	if (explicit) return {
+		skin: player.getNodeOrNull(explicit) ?? null,
+		declaredOffset: 0
+	};
+	for (const child of player.children) {
+		const ctl = child;
+		if (typeof ctl.skinPath === "string" && ctl.skinPath !== "") {
+			const skin = child.getNodeOrNull(ctl.skinPath);
+			if (skin) return {
+				skin,
+				declaredOffset: ctl.skinYawOffset ?? 0
+			};
+		}
+	}
+	return {
+		skin: player.getNodeOrNull("%Skin") ?? null,
+		declaredOffset: 0
+	};
+}
+/**
+* Drive the player forward and compare where the skin points with where it went.
+*
+* The travel direction is measured, not assumed: whatever the input map means by
+* "up", the character ends up going somewhere, and that somewhere is the truth
+* the art has to agree with.
+*/
+async function facingReport(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);
+	if (!player) {
+		session.dispose();
+		return {
+			player: null,
+			skin: null,
+			dot: null,
+			backwards: false,
+			travelled: 0
+		};
+	}
+	const declared = session.engine.input.declaredActions();
+	const move = opts.moveAction ?? declared.find((a) => a.type === "vector2")?.name ?? null;
+	const posOf = () => {
+		const p = player.position;
+		return [p[0] ?? 0, p[2] ?? 0];
+	};
+	session.step(500);
+	const from = posOf();
+	if (move) session.engine.input.setActionVector(move, 1, 0);
+	session.step(700);
+	const to = posOf();
+	if (move) session.engine.input.setActionVector(move, 0, 0);
+	const dx = to[0] - from[0];
+	const dz = to[1] - from[1];
+	const travelled = Math.hypot(dx, dz);
+	const { skin, declaredOffset } = findSkin(player, opts.skinPath);
+	const skinPath = skin ? skin.getPath() : null;
+	if (!skin || travelled < .05) {
+		session.dispose();
+		return {
+			player: player.getPath(),
+			skin: skinPath,
+			dot: null,
+			backwards: false,
+			travelled
+		};
+	}
+	const [fx, fz] = forwardOf((skin.rotation?.[1] ?? 0) - declaredOffset, opts.forwardAxis ?? "+z");
+	const dot = (fx * dx + fz * dz) / travelled;
+	session.dispose();
+	return {
+		player: player.getPath(),
+		skin: skinPath,
+		dot: Math.round(dot * 1e3) / 1e3,
+		backwards: dot < -.5,
+		travelled: Math.round(travelled * 1e3) / 1e3
+	};
+}
+/** One line for a report, or the failure spelled out. */
+function facingText(report) {
+	if (!report.player) return "facing: no player to drive";
+	if (report.skin === null) return `facing: ${report.player} has no skin to check`;
+	if (report.dot === null) return `facing: ${report.player} did not move — nothing to compare`;
+	if (report.backwards) return `facing: ${report.skin} RUNS BACKWARDS (dot ${report.dot.toFixed(2)}) — the skin points away from the direction of travel. The rule is +Z forward, yaw = atan2(dx, dz), with NO +180; for art that faces another way set skinYawOffset rather than adding to the yaw.`;
+	return `facing: ${report.skin} faces its travel (dot ${report.dot.toFixed(2)})`;
+}
+//#endregion
 //#region src/test/feel.ts
 const STEP_MS = 1e3 / 60;
 /** Drop height for the buffer probe — long enough to outlast a coyote window. */
@@ -1258,7 +1370,7 @@ async function runScript(json, opts) {
 		const { enablePhysics2D } = await import("./physics-2d-BmgXBNDB.js").then((n) => n.r);
 		await enablePhysics2D(engine);
 	} else if (physics === "3d" || physics === "auto" && scene.dimension === "3d") {
-		const { enablePhysics3D } = await import("./physics-3d-C2G604O1.js").then((n) => n.r);
+		const { enablePhysics3D } = await import("./physics-3d-CLPFv99o.js").then((n) => n.r);
 		await enablePhysics3D(engine);
 	}
 	const failures = [];
@@ -1374,7 +1486,7 @@ async function createPlaySession(json, opts = {}) {
 		const { enablePhysics2D } = await import("./physics-2d-BmgXBNDB.js").then((n) => n.r);
 		await enablePhysics2D(engine);
 	} else if (physics === "3d" || physics === "auto" && scene.dimension === "3d") {
-		const { enablePhysics3D } = await import("./physics-3d-C2G604O1.js").then((n) => n.r);
+		const { enablePhysics3D } = await import("./physics-3d-CLPFv99o.js").then((n) => n.r);
 		await enablePhysics3D(engine);
 	}
 	const stepMs = 1e3 / (opts.fixedHz ?? 60);
@@ -1412,4 +1524,4 @@ async function createPlaySession(json, opts = {}) {
 	};
 }
 //#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 };
+export { framingText as _, registerAllNodes as a, feelReport as c, facingText as d, failingReplays as f, describeFraming as g, playtestText as h, findFloatingProps as i, feelText as l, playtest as m, createPlaySession as n, runScript as o, findPlayer as p, describeCapture as r, validateScene as s, captureScene as t, facingReport as u };