incanto 0.45.1 → 0.47.0

package/dist/{environment-presets-DUsBqvtk.js → environment-presets-D1b0ydTS.js}

@@ -6536,19 +6536,20 @@ var ModelInstance3D = class extends Node3D {
 		if (anim.status !== "ready" || !anim.scene) return null;
 		const source = (anim.clip ? anim.clips.find((c) => c.name === anim.clip) : void 0) ?? anim.clips[0];
 		if (!source) return null;
+		const cacheKey = source.uuid;
 		if (this.entry.isVrm && this.entry.vrm) {
-			const cached = this.entry.retargeted.get(ref);
+			const cached = this.entry.retargeted.get(cacheKey);
 			if (cached) return cached;
 			const result = retargetClipToVrm(source, anim.scene, this.entry.vrm);
 			if (result.skippedBones.length > 0) this.diagnose("warn", `incanto: retarget '${ref}' skipped bones: ${result.skippedBones.join(", ")}`);
-			this.entry.retargeted.set(ref, result.clip);
+			this.entry.retargeted.set(cacheKey, result.clip);
 			return result.clip;
 		}
-		const cached = this.entry.retargeted.get(ref);
+		const cached = this.entry.retargeted.get(cacheKey);
 		if (cached) return cached;
 		const rig = retargetClipToRig(source, anim.scene, this.fitGroup ?? this._ensureObject3D());
 		if (rig.passthrough) this.diagnose("warn", `incanto: animation '${ref}' — ${rig.reason}`);
-		this.entry.retargeted.set(ref, rig.clip);
+		this.entry.retargeted.set(cacheKey, rig.clip);
 		return rig.clip;
 	}
 	/** Masked upper/lower variants of a clip for two-layer playback (cached). */

package/dist/{frame-report-Ct8XgsmV.d.ts → frame-report-DZ70IY26.d.ts}

@@ -28,6 +28,31 @@ interface FrameStats {
   meanLuma: number;
   /** Coarse mean colour per cell, rows top to bottom. */
   grid: GridCell[][];
+  /** What the frame is OF, or null when it is all background. */
+  subject: Subject | null;
+}
+/**
+* The thing in the shot: everything that is not the background.
+*
+* `black` and `uniform` answer "did anything render at all". They do not answer
+* the question that actually goes wrong — "is the thing IN the shot, and can
+* you see it" — and every visual defect reported against the editor's model
+* previews walked straight past them. A white square with a faint sky gradient
+* is neither black nor uniform; a character drawn as a speck in the corner has
+* a perfectly ordinary mean luminance.
+*/
+interface Subject {
+  /** Bounding box in pixels, origin top-left. */
+  box: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+  };
+  /** Share of the frame's pixels that are subject, 0..1. */
+  coverage: number;
+  /** Touching an edge — the shot is a crop, and something is outside it. */
+  clipped: boolean;
 }
 interface FrameStatsOptions {
   /** Cells across and down. Default 16x9 — 144 cells, printable. */

package/dist/{frame-report-Lr3VO24R.js → frame-report-njybhZon.js}

@@ -44,6 +44,98 @@ function cellMeans(pixels, width, height, cols, rows) {
 	}
 	return out;
 }
+/**
+* How far a pixel must sit from the background colour to count as subject.
+* Chosen above the banding in a sky gradient and well below any real material.
+*/
+const SUBJECT_DELTA = 24;
+/** Subject smaller than this is present but not visible — say so differently. */
+const TINY_COVERAGE = .01;
+/**
+* The background colour, read off the BORDER rather than voted for.
+*
+* A subject filling most of the shot would win a popularity contest and the
+* report would invert — the sky would become "the thing", and a well-framed
+* character would read as an empty frame. The edge of a frame is background in
+* every shot this is asked about; where it is not, the subject is clipped, and
+* that gets reported too.
+*/
+function borderColour(pixels, width, height) {
+	let r = 0;
+	let g = 0;
+	let b = 0;
+	let n = 0;
+	const take = (x, y) => {
+		const o = (y * width + x) * 4;
+		r += pixels[o];
+		g += pixels[o + 1];
+		b += pixels[o + 2];
+		n += 1;
+	};
+	for (let x = 0; x < width; x++) {
+		take(x, 0);
+		take(x, height - 1);
+	}
+	for (let y = 1; y < height - 1; y++) {
+		take(0, y);
+		take(width - 1, y);
+	}
+	return n === 0 ? [
+		0,
+		0,
+		0
+	] : [
+		r / n,
+		g / n,
+		b / n
+	];
+}
+/** Where the non-background pixels are, or null when there are none worth it. */
+function findSubject(pixels, width, height) {
+	const global = borderColour(pixels, width, height);
+	const at = (x, y) => {
+		const o = (y * width + x) * 4;
+		return [
+			pixels[o],
+			pixels[o + 1],
+			pixels[o + 2]
+		];
+	};
+	const dist = (a, b) => Math.abs(a[0] - b[0]) + Math.abs(a[1] - b[1]) + Math.abs(a[2] - b[2]);
+	let minX = width;
+	let minY = height;
+	let maxX = -1;
+	let maxY = -1;
+	let count = 0;
+	for (let y = 0; y < height; y++) {
+		const left = at(0, y);
+		const right = at(width - 1, y);
+		const row = dist(left, right) > SUBJECT_DELTA ? dist(left, global) <= dist(right, global) ? left : right : [
+			(left[0] + right[0]) / 2,
+			(left[1] + right[1]) / 2,
+			(left[2] + right[2]) / 2
+		];
+		for (let x = 0; x < width; x++) {
+			if (dist(at(x, y), row) < SUBJECT_DELTA) continue;
+			count += 1;
+			if (x < minX) minX = x;
+			if (x > maxX) maxX = x;
+			if (y < minY) minY = y;
+			if (y > maxY) maxY = y;
+		}
+	}
+	if (maxX < 0) return null;
+	return {
+		box: {
+			x: minX,
+			y: minY,
+			w: maxX - minX + 1,
+			h: maxY - minY + 1
+		},
+		coverage: count / (width * height),
+		clipped: minX === 0 || minY === 0 || maxX === width - 1 || maxY === height - 1
+	};
+}
 function frameStats(pixels, width, height, opts = {}) {
 	const [cols, rows] = opts.grid ?? [16, 9];
 	const means = cellMeans(pixels, width, height, cols, rows);
@@ -70,21 +162,30 @@ function frameStats(pixels, width, height, opts = {}) {
 	}
 	const cells = cols * rows;
 	const meanLuma = total / cells;
+	const black = maxLuma <= BLACK_LEVEL;
 	return {
 		width,
 		height,
-		black: maxLuma <= BLACK_LEVEL,
+		black,
 		uniform: maxLuma - minLuma < UNIFORM_EPSILON,
 		meanLuma: Math.round(meanLuma * 1e3) / 1e3,
-		grid
+		grid,
+		subject: black ? null : findSubject(pixels, width, height)
 	};
 }
+const pct = (v) => `${(v * 100).toFixed(1)}%`;
 /** 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");
+	else if (!stats.subject) lines.push("nothing but background — the camera is pointed away from everything in the scene");
+	else if (stats.subject.coverage < TINY_COVERAGE) lines.push(`the subject fills almost nothing (${pct(stats.subject.coverage)}) — the camera is too far back, or what you meant to see is not what got drawn`);
 	lines.push(`frame ${stats.width}×${stats.height} · luminance ${stats.meanLuma.toFixed(2)}`);
+	if (stats.subject) {
+		const { box, coverage, clipped } = stats.subject;
+		lines.push(`subject ${box.w}×${box.h} at ${box.x},${box.y} · fills ${pct(coverage)} of frame` + (clipped ? " · CLIPPED by the frame edge" : ""));
+	}
 	return lines.join("\n");
 }
 /**
@@ -193,5 +294,31 @@ function fromBase64(text) {
 	for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
 	return out;
 }
+/**
+* A `data:` PNG of the frame, scaled to fit `maxSide`.
+*
+* Rows are taken as they come, TOP-DOWN. `gl.readPixels` is bottom-up, which
+* is why this wants flipping — but `Renderer3D.captureFrame` already flipped
+* once, "rather than in each of" its consumers, and this is one of them.
+* Flipping again shipped an upside-down picture that the unit test happily
+* confirmed, because the test asserted the belief instead of the boundary.
+*/
+function frameImage(pixels, width, height, makeCanvas, maxSide = 512) {
+	const full = makeCanvas(width, height);
+	const ctx = full.getContext("2d");
+	if (!ctx) return null;
+	const image = ctx.createImageData(width, height);
+	image.data.set(pixels.subarray(0, width * height * 4));
+	ctx.putImageData(image, 0, 0);
+	const scale = Math.min(1, maxSide / Math.max(width, height));
+	if (scale >= 1) return full.toDataURL("image/png");
+	const w = Math.max(1, Math.round(width * scale));
+	const h = Math.max(1, Math.round(height * scale));
+	const small = makeCanvas(w, h);
+	const sctx = small.getContext("2d");
+	if (!sctx) return full.toDataURL("image/png");
+	sctx.drawImage(full, 0, 0, w, h);
+	return small.toDataURL("image/png");
+}
 //#endregion
-export { frameStats as a, frameSignature as i, diffSignatures as n, frameText as o, diffText as r, SIGNATURE_GRID as t };
+export { frameSignature as a, frameImage as i, diffSignatures as n, frameStats as o, diffText as r, frameText as s, SIGNATURE_GRID as t };

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-DUxGnvq3.js";
+import { a as findPath, i as preloadUrls, n as newUid, o as gridFromRows, r as assetUrls, t as VERSION } from "./src-Ca3oV1fe.js";
 import { 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-DFqMtBUD.js → physics-3d-CSoGjM8P.js}

@@ -3,7 +3,7 @@ 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-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-DUsBqvtk.js";
+import { A as Terrain3D, F as InstancedMesh3D, L as buildMeshGeometry, P as Joint3D } from "./environment-presets-D1b0ydTS.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-Gifrjhnz.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-DFRbG0Bj.js").then((n) => n.n)).createGame2D(o)))(opts);
+			const next = await (_gameFactory ?? (mode === "3d" ? async (o) => (await import("./create-game-D16MVIPO.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-CniOiWzN.js").then((n) => n.n)).createGame2D(o)))(opts);
 			if (disposed) {
 				next.dispose();
 				return;

package/dist/{src-DUxGnvq3.js → src-Ca3oV1fe.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.45.1";
+const VERSION = "0.47.0";
 //#endregion
 export { findPath as a, preloadUrls as i, newUid as n, gridFromRows as o, assetUrls as r, VERSION as t };

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

@@ -50,14 +50,15 @@ async function settle(ms = VEIL_MS) {
 * `incanto-editor` server) serve. Used when a game passes `library: true`.
 */
 function devServerLibrary(token) {
-	return async (query) => {
+	return async (query, callToken) => {
+		const bearer = callToken || token;
 		const params = new URLSearchParams({
 			tags: query.tags.join(","),
 			page: String(query.page ?? 1),
 			limit: String(query.limit ?? 24)
 		});
 		if (query.keyword?.trim()) params.set("keyword", query.keyword.trim());
-		const res = await fetch(`/api/library?${params}`, { headers: token ? { "x-incanto-v8-token": token } : {} });
+		const res = await fetch(`/api/library?${params}`, { headers: bearer ? { "x-incanto-v8-token": bearer } : {} });
 		if (res.status === 401) {
 			const body = await res.json().catch(() => ({}));
 			const error = new Error(body.error ?? "the asset library needs a Verse8 access token");

package/dist/{test-DD5scWfm.js → test-E4-otKqK.js}

@@ -6,7 +6,7 @@ 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-BQOeAid6.js";
 import { t as registerNodes2D } from "./register-R2JTnIMw.js";
-import { n as registerNodes3D, t as resolveEnvironmentHdri } from "./environment-presets-DUsBqvtk.js";
+import { n as registerNodes3D, t as resolveEnvironmentHdri } from "./environment-presets-D1b0ydTS.js";
 import { t as registerNodesNet } from "./register-D651it1J.js";
 import { Box3, Euler, Matrix4, PerspectiveCamera, Quaternion, Vector3 } from "three";
 //#region src/test/framing.ts
@@ -345,12 +345,14 @@ function makeOracle(engine, player) {
 	let outcome = null;
 	let damage = 0;
 	const offs = [];
+	let declaresEnd = false;
 	/** 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" || signal === "lost" || signal === "flowChanged") declaresEnd = true;
 			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")));
@@ -368,6 +370,7 @@ function makeOracle(engine, player) {
 	if (root) walk(root);
 	return {
 		outcome: () => outcome,
+		declaresEnd: () => declaresEnd,
 		damage: () => damage,
 		dispose: () => {
 			for (const off of offs) off();
@@ -549,7 +552,8 @@ async function runOnce(json, seed, opts) {
 	return {
 		run,
 		targets,
-		signals
+		signals,
+		declaresEnd: oracle.declaresEnd()
 	};
 }
 /** Play the scene `runs` times and report what happened. */
@@ -559,11 +563,13 @@ async function playtest(json, opts = {}) {
 	const runs = [];
 	let targets = [];
 	let signals = [];
+	let declaresWin = false;
 	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;
+		declaresWin = declaresWin || one.declaresEnd;
 	}
 	const probe = await createPlaySession(json, {
 		seed: base,
@@ -577,7 +583,8 @@ async function playtest(json, opts = {}) {
 		targets,
 		signals: [...new Set(signals)],
 		actions,
-		inertActions: []
+		inertActions: [],
+		declaresWin
 	};
 }
 function pct(n, total) {
@@ -603,7 +610,7 @@ function playtestText(report) {
 	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`);
+	else lines.push(report.declaresWin ? `  ✗ never reached "won" in ${total} runs — a win IS declared, and no run got to it` : `  · no win declared in this scene — nothing emits won/lost, so there is nothing to reach`);
 	for (const bad of [
 		"error",
 		"fell",
@@ -1139,6 +1146,46 @@ function feelText(report) {
 	return lines.join("\n");
 }
 //#endregion
+//#region src/test/verify-ladder.ts
+const MARK = {
+	pass: "✓",
+	fail: "✗",
+	unmeasured: "?",
+	skipped: "·"
+};
+function ladderVerdict(rungs, ctx = {}) {
+	const failed = rungs.find((r) => r.status === "fail");
+	const unmeasured = rungs.filter((r) => r.status === "unmeasured");
+	const next = failed ? failed.fix ?? failed.summary : unmeasured[0]?.fix ?? unmeasured[0]?.summary ?? null;
+	const ambiguous = rungs.length === 0 && (ctx.candidates?.length ?? 0) > 1;
+	return {
+		ok: !failed,
+		rungs,
+		unmeasured: unmeasured.map((r) => r.name),
+		next: ambiguous ? "name the one you mean: `incanto-verify <scene.json>`" : next ?? null,
+		candidates: ctx.candidates ?? []
+	};
+}
+/** The ladder as a person or an agent reads it: every rung, then the one action. */
+function ladderText(v) {
+	if (v.rungs.length === 0) {
+		if (v.candidates.length > 1) return [
+			`${v.candidates.length} scenes here, and guessing between them would verify the wrong one:`,
+			...v.candidates.map((c) => `  ${c}`),
+			"",
+			`next: ${v.next}`
+		].join("\n");
+		return "nothing to verify — no scene was given and none was found";
+	}
+	const lines = v.rungs.map((r) => `${MARK[r.status]} ${r.name} — ${r.summary}`);
+	lines.push("");
+	if (!v.ok) lines.push("NOT verified.");
+	else if (v.unmeasured.length > 0) lines.push(`passes what was measured — ${v.unmeasured.join(", ")} not measured.`);
+	else lines.push("verified: it loads, it plays, and it draws.");
+	if (v.next) lines.push(`next: ${v.next}`);
+	return lines.join("\n");
+}
+//#endregion
 //#region src/test/index.ts
 /**
 * incanto/test — the browserless verification harness.
@@ -1370,7 +1417,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-DFqMtBUD.js").then((n) => n.r);
+		const { enablePhysics3D } = await import("./physics-3d-CSoGjM8P.js").then((n) => n.r);
 		await enablePhysics3D(engine);
 	}
 	const failures = [];
@@ -1486,7 +1533,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-DFqMtBUD.js").then((n) => n.r);
+		const { enablePhysics3D } = await import("./physics-3d-CSoGjM8P.js").then((n) => n.r);
 		await enablePhysics3D(engine);
 	}
 	const stepMs = 1e3 / (opts.fixedHz ?? 60);
@@ -1524,4 +1571,4 @@ async function createPlaySession(json, opts = {}) {
 	};
 }
 //#endregion
-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 };
+export { playtestText as _, registerAllNodes as a, ladderText as c, feelText as d, facingReport as f, playtest as g, findPlayer as h, findFloatingProps as i, ladderVerdict as l, failingReplays as m, createPlaySession as n, runScript as o, facingText as p, describeCapture as r, validateScene as s, captureScene as t, feelReport as u, describeFraming as v, framingText as y };

package/dist/test.d.ts

@@ -165,6 +165,15 @@ interface PlaytestReport {
   actions: string[];
   /** Actions that never changed the world in any run. */
   inertActions: string[];
+  /**
+  * Does anything in this scene declare an END?
+  *
+  * "No run reached a win" has two causes that need opposite fixes: a goal
+  * that cannot be reached, and a scene with no goal in it. A walkabout
+  * template is not a broken game, and reporting one as a failure sends its
+  * author looking for a bug that was never there.
+  */
+  declaresWin: boolean;
 }
 /**
 * Who the driver is playing as.
@@ -190,6 +199,51 @@ declare function failingReplays(report: PlaytestReport): Array<{
   replay: JsonValue;
 }>;
 //#endregion
+//#region src/test/verify-ladder.d.ts
+/**
+* The verification ladder, as one answer.
+*
+* The rungs already exist — `incanto-check` says the scene loads,
+* `incanto-playtest` says it can be finished, `incanto-frame` says something
+* was drawn. They are documented together and used apart, because using them
+* together means knowing three things nobody writes down:
+*
+*   the ORDER (a scene that does not load cannot be played or drawn, so the
+*     first red rung is the only one worth reading)
+*   that an unmeasured rung is not a failing one — "no dev server" means the
+*     question was never asked, and answering it "fail" sends an agent editing
+*     a scene that is fine
+*   what to do NEXT, which is one sentence and never the whole report
+*
+* Pure: the rungs are run by the CLI, this decides what they add up to.
+*/
+type RungStatus = "pass" | "fail" | "unmeasured" | "skipped";
+interface RungResult {
+  name: string;
+  status: RungStatus;
+  /** One line: what this rung found. */
+  summary: string;
+  /** What to do about it, when there is something to do. */
+  fix?: string;
+}
+interface LadderVerdict {
+  ok: boolean;
+  rungs: RungResult[];
+  /** Rungs that could not be measured — questions unasked, not answers. */
+  unmeasured: string[];
+  /** The single next action, or null when there is nothing to do. */
+  next: string | null;
+  /** Scenes found when none was named (empty once one is being verified). */
+  candidates: string[];
+}
+interface LadderContext {
+  /** Scenes found when none was named — none, or more than one to choose from. */
+  candidates?: string[];
+}
+declare function ladderVerdict(rungs: RungResult[], ctx?: LadderContext): LadderVerdict;
+/** The ladder as a person or an agent reads it: every rung, then the one action. */
+declare function ladderText(v: LadderVerdict): string;
+//#endregion
 //#region src/test/index.d.ts
 /** One thing that is not standing where it should be. */
 interface GroundingIssue {
@@ -371,4 +425,4 @@ interface PlaySession {
 */
 declare function createPlaySession(json: unknown, opts?: PlaySessionOptions): Promise<PlaySession>;
 //#endregion
-export { type FacingOptions, type FacingReport, type FeelOptions, type FeelReport, type FramingEntry, type FramingOptions, type FramingReport, GroundingIssue, GroundingOptions, NodeCapture, type Outcome, PlaySession, PlaySessionOptions, type PlaytestOptions, type PlaytestReport, type PlaytestRun, RunContext, RunFailure, RunResult, RunScriptOptions, SceneCapture, ScriptStep, ValidateSceneOptions, ValidationResult, type Where, auditScene, captureScene, createPlaySession, describeCapture, describeFraming, facingReport, facingText, failingReplays, feelReport, feelText, findFloatingProps, findPlayer, framingText, playtest, playtestText, registerAllNodes, runScript, validateScene };
+export { type FacingOptions, type FacingReport, type FeelOptions, type FeelReport, type FramingEntry, type FramingOptions, type FramingReport, GroundingIssue, GroundingOptions, type LadderVerdict, NodeCapture, type Outcome, PlaySession, PlaySessionOptions, type PlaytestOptions, type PlaytestReport, type PlaytestRun, RunContext, RunFailure, RunResult, RunScriptOptions, type RungResult, type RungStatus, SceneCapture, ScriptStep, ValidateSceneOptions, ValidationResult, type Where, auditScene, captureScene, createPlaySession, describeCapture, describeFraming, facingReport, facingText, failingReplays, feelReport, feelText, findFloatingProps, findPlayer, framingText, ladderText, ladderVerdict, playtest, playtestText, registerAllNodes, runScript, validateScene };

package/dist/test.js

@@ -1,3 +1,3 @@
 import { r as auditScene } from "./replay-DilbZgQI.js";
-import { _ as framingText, a as registerAllNodes, c as feelReport, d as facingText, f as failingReplays, g as describeFraming, h as playtestText, i as findFloatingProps, l as feelText, m as playtest, n as createPlaySession, o as runScript, p as findPlayer, r as describeCapture, s as validateScene, t as captureScene, u as facingReport } from "./test-DD5scWfm.js";
-export { auditScene, captureScene, createPlaySession, describeCapture, describeFraming, facingReport, facingText, failingReplays, feelReport, feelText, findFloatingProps, findPlayer, framingText, playtest, playtestText, registerAllNodes, runScript, validateScene };
+import { _ as playtestText, a as registerAllNodes, c as ladderText, d as feelText, f as facingReport, g as playtest, h as findPlayer, i as findFloatingProps, l as ladderVerdict, m as failingReplays, n as createPlaySession, o as runScript, p as facingText, r as describeCapture, s as validateScene, t as captureScene, u as feelReport, v as describeFraming, y as framingText } from "./test-E4-otKqK.js";
+export { auditScene, captureScene, createPlaySession, describeCapture, describeFraming, facingReport, facingText, failingReplays, feelReport, feelText, findFloatingProps, findPlayer, framingText, ladderText, ladderVerdict, playtest, playtestText, registerAllNodes, runScript, validateScene };

package/dist/vite.d.ts

@@ -1,4 +1,4 @@
-import { n as FrameSignature } from "./frame-report-Ct8XgsmV.js";
+import { n as FrameSignature } from "./frame-report-DZ70IY26.js";
 
 //#region src/vite/discover.d.ts
 /**
@@ -29,9 +29,20 @@ interface FrameHost {
   middlewares: {
     use(path: string, handler: (req: FrameReq, res: FrameRes) => void): void;
   };
-  /** Vite's HMR channel. `ws` on v5, `hot` on v6+ — both are accepted. */
+  /**
+  * Vite's HMR channel, which has moved twice. `ws` on v5, `hot` on v6+, and
+  * since the Environment API the one that actually reaches the BROWSER is
+  * `environments.client.hot` — on v8 the top-level `hot` still exists and
+  * still accepts `send()` without error, it simply arrives nowhere. Every
+  * candidate is used, because a silent no-op is the worst of the three.
+  */
   ws?: FrameChannel;
   hot?: FrameChannel;
+  environments?: {
+    client?: {
+      hot?: FrameChannel;
+    };
+  };
 }
 interface FrameChannel {
   send(payload: {
@@ -205,6 +216,8 @@ interface IncantoLibraryOptions {
   token?: string;
   /** Upstream catalog (default: the agent8 backend). */
   url?: string;
+  /** Verse8 API root for the sign-in flow (default: the public one). */
+  authUrl?: string;
 }
 /**
 * Serve the agent8 asset catalog at `/api/library` on the dev server.
@@ -232,7 +245,25 @@ declare function incantoLibrary(opts?: IncantoLibraryOptions): {
   apply: "serve";
   configureServer(server: DevServer): void;
 };
+/**
+* A token, shown the way a wallet address is: enough to recognise WHICH token
+* is in use, never enough to use it. Anything short enough that six and four
+* characters would give most of it away is hidden entirely.
+*/
+declare function maskToken(token: string): string;
+/** Where the server's token came from, and what it looks like. Never the token. */
+declare function serveTokenStatus(req: LibraryReq, res: LibraryRes, opts?: IncantoLibraryOptions): Promise<void>;
+/**
+* The Verse8 device-authorization flow (RFC 8628), proxied.
+*
+* The same two calls agent8's own local-dev login makes: `authorize` returns a
+* code and a page for the human to approve, `token` is polled until they have.
+* It goes through the dev server for the same reason the catalog does — the
+* page cannot reach that host itself — and it means a developer never has to
+* find, copy or paste a token at all.
+*/
+declare function serveDeviceAuth(req: LibraryReq, res: LibraryRes, opts?: IncantoLibraryOptions, doFetch?: typeof fetch): Promise<void>;
 /** @internal Exported for tests — the whole request/response behaviour. */
 declare function serveLibrary(req: LibraryReq, res: LibraryRes, opts?: IncantoLibraryOptions, doFetch?: typeof fetch): Promise<void>;
 //#endregion
-export { type FrameHost, IncantoLibraryOptions, IncantoScenesOptions, ProjectFileEntry, discoverScenes, incantoLibrary, incantoScenes, listeningPorts, parseProcNetTcp, resolveSceneFile, sceneFacts, serveFrameEndpoints, serveLibrary, serveSceneFile, serveSceneList };
+export { type FrameHost, IncantoLibraryOptions, IncantoScenesOptions, ProjectFileEntry, discoverScenes, incantoLibrary, incantoScenes, listeningPorts, maskToken, parseProcNetTcp, resolveSceneFile, sceneFacts, serveDeviceAuth, serveFrameEndpoints, serveLibrary, serveSceneFile, serveSceneList, serveTokenStatus };