incanto 0.46.0 → 0.48.0

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.d.ts

@@ -69,6 +69,106 @@ interface DebugLineSource {
   debugLines(): Float32Array | null;
 }
 //#endregion
+//#region src/core/drive-script.d.ts
+/**
+* A little script for driving a game, in the words it already understands.
+*
+* `incanto-play` has driven scenes from bash for many releases — `press`,
+* `vector`, `step` — and cannot show you the result, because headless has no
+* pixels. `incanto-frame` has the pixels and cannot move. Between them an agent
+* could only ever look at the boot screen, and every interesting state in a
+* game is downstream of input: the boss room, the bridge, the moment after the
+* jump.
+*
+* So the same vocabulary drives the RUNNING page, and the frame comes back
+* after it. One language for both, or an agent has to learn two.
+*
+* Pure: parsing only. Who applies the steps is the page's business.
+*/
+type DriveStep = {
+  kind: "press";
+  action: string;
+} | {
+  kind: "release";
+  action: string;
+} | {
+  kind: "vector";
+  action: string;
+  x: number;
+  y: number;
+} | {
+  kind: "key";
+  code: string;
+  down: boolean;
+} | {
+  kind: "pointer";
+  dx: number;
+  dy: number;
+} | {
+  kind: "step";
+  ms: number;
+};
+interface DriveScript {
+  steps: DriveStep[];
+  /** Why nothing will run, or null. A refused script runs NONE of its steps. */
+  error: string | null;
+  /** Total simulated time the script asks for, ms. */
+  totalMs: number;
+}
+/**
+* `vector move 0 1; step 2000` → steps, or an error naming the bad command.
+*
+* Semicolons and newlines both separate, so a whole plan fits in one shell
+* argument and a longer one fits in a file. `#` starts a comment.
+*
+* A command it does not know REFUSES THE WHOLE SCRIPT. Skipping it would leave
+* an agent looking at a frame that never moved, believing it had walked
+* somewhere — the failure mode this exists to prevent.
+*/
+declare function parseDrive(text: string): DriveScript;
+//#endregion
+//#region src/core/log-report.d.ts
+interface AssetFailure {
+  ref: string;
+  url: string;
+  error: string;
+}
+interface LiveInput {
+  entries: readonly LogEntry[];
+  stats: EngineStats;
+  assetErrors: readonly AssetFailure[];
+  /**
+  * The page is one the browser has stopped drawing — hidden, or a window
+  * merely covered by another. It throttles such a tab to about a frame a
+  * second, and that number says nothing about the game.
+  */
+  hidden?: boolean;
+}
+/** One message, however many times the game said it. */
+interface GroupedLog {
+  level: LogLevel;
+  message: string;
+  count: number;
+  /** When it was last said, in the page's own clock. */
+  lastMs: number;
+}
+interface LiveReport {
+  ok: boolean;
+  /** Frame rate low enough to be felt (running, and not merely throttled). */
+  slow: boolean;
+  /** The browser is throttling this page — see {@link LiveInput.hidden}. */
+  hidden: boolean;
+  counts: Record<LogLevel, number>;
+  grouped: GroupedLog[];
+  /** The most severe thing said, or null when nothing was. */
+  worst: GroupedLog | null;
+  stats: EngineStats;
+  assetErrors: readonly AssetFailure[];
+}
+declare function logReport(input: LiveInput): LiveReport;
+/** The report as a person or an agent reads it: what is wrong, then the numbers. */
+declare function logText(r: LiveReport): string;
+//#endregion
 //#region src/core/node-path.d.ts
 /**
 * Godot-style NodePath grammar:
@@ -710,4 +810,4 @@ declare function computeViewport(canvasW: number, canvasH: number, viewport: {
 /** Engine version. Kept in sync with package.json by the release pipeline. */
 declare const VERSION: string;
 //#endregion
-export { AudioBuses, type AudioElementLike, AudioPlayer, BASE_LOCALE, Behavior, type BehaviorCtor, type BehaviorState, type BusName, CONST_REF_KEY, type ComputedViewport, type ConnectionJson, type CrossfadeGains, type DebugLineSource, type DeviceHints, Engine, type EngineOptions, type EngineStats, type FindPathOptions, type GameStats, type HudAnchor, HudLayer, IncantoError, type IncantoErrorCode, type IncantoErrorDetails, InputMap, type JsonKind, type JsonObject, type JsonValue, type Listener, type LoadSceneOptions, type LocaleTables, Localization, type LogEntry, type LogLevel, LogManager, type MusicBackend, MusicManager, type MusicTrack, Node, type NodeCtor, type NodeJson, type NodeLifecycle, ORDER_GROUP_BASE, type OrderGroup, type OrderGroupTable, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, type ParsedNodePath, type ParticlePresetValues, ParticleSim, type ParticleSimConfig, type ParticleView, type PathGrid, type PlayMusicOptions, type PreloadResult, type PropDef, type PropSchema, type QualityTier, ROLLOFF_MODELS, type Recorder, type RendererStats, type ReplayEvent, type ReplayJson, type ResolvedRendering, type ResolvedViewport, type RestoreReport, Rng, type RolloffModel, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, type SaveSlot, SaveSlots, type SaveStore, Scene, type SceneJson, SceneTree, type Scheduler, Settings, type SettingsValues, SfxEngine, type SfxParams, type SfxPlayOptions, type SfxWave, Signal, type SignalListener, type SpatialParams, type SynthOptions, T_PREFIX, Timer, TouchControls, type TouchControlsOptions, UiBanner, UiBar, UiButton, UiDialogue, UiImage, UiPanel, UiSelect, UiSlider, UiText, UiToggle, VERSION, type Vec3, type ViewportFit, type Voice, type VoicePreset, 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 };
+export { type AssetFailure, AudioBuses, type AudioElementLike, AudioPlayer, BASE_LOCALE, Behavior, type BehaviorCtor, type BehaviorState, type BusName, CONST_REF_KEY, type ComputedViewport, type ConnectionJson, type CrossfadeGains, type DebugLineSource, type DeviceHints, type DriveScript, type DriveStep, Engine, type EngineOptions, type EngineStats, type FindPathOptions, type GameStats, type GroupedLog, type HudAnchor, HudLayer, IncantoError, type IncantoErrorCode, type IncantoErrorDetails, InputMap, type JsonKind, type JsonObject, type JsonValue, type Listener, type LiveInput, type LiveReport, type LoadSceneOptions, type LocaleTables, Localization, type LogEntry, type LogLevel, LogManager, type MusicBackend, MusicManager, type MusicTrack, Node, type NodeCtor, type NodeJson, type NodeLifecycle, ORDER_GROUP_BASE, type OrderGroup, type OrderGroupTable, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, type ParsedNodePath, type ParticlePresetValues, ParticleSim, type ParticleSimConfig, type ParticleView, type PathGrid, type PlayMusicOptions, type PreloadResult, type PropDef, type PropSchema, type QualityTier, ROLLOFF_MODELS, type Recorder, type RendererStats, type ReplayEvent, type ReplayJson, type ResolvedRendering, type ResolvedViewport, type RestoreReport, Rng, type RolloffModel, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, type SaveSlot, SaveSlots, type SaveStore, Scene, type SceneJson, SceneTree, type Scheduler, Settings, type SettingsValues, SfxEngine, type SfxParams, type SfxPlayOptions, type SfxWave, Signal, type SignalListener, type SpatialParams, type SynthOptions, T_PREFIX, Timer, TouchControls, type TouchControlsOptions, UiBanner, UiBar, UiButton, UiDialogue, UiImage, UiPanel, UiSelect, UiSlider, UiText, UiToggle, VERSION, type Vec3, type ViewportFit, type Voice, type VoicePreset, 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, logReport, logText, mergeStaticSignals, newUid, parseDrive, 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/index.js

@@ -5,9 +5,10 @@ import { t as Rng } from "./rng-DP-SR7eg.js";
 import { n as startRecording, r as auditScene, t as replay } from "./replay-DilbZgQI.js";
 import { n as jsonEquals, r as jsonKind, t as jsonClone } from "./json-BLk7H2Qa.js";
 import { a as getNodeSignals, c as mergeStaticSignals, i as getNodeSchema, l as registerNode, n as clearRegistry, o as getNodeType, r as createNode, u as registeredTypes } from "./registry-IyWCGe4q.js";
+import { n as logText, r as parseDrive, t as logReport } from "./log-report-lxrQY9cH.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-B43b6bZo.js";
+import { a as findPath, i as preloadUrls, n as newUid, o as gridFromRows, r as assetUrls, t as VERSION } from "./src-Bl1Kire1.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 };
+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, logReport, logText, mergeStaticSignals, newUid, parseDrive, 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/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-BtCNdkjI.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-CniOiWzN.js").then((n) => n.n)).createGame2D(o)))(opts);
+			const next = await (_gameFactory ?? (mode === "3d" ? async (o) => (await import("./create-game-akjPkFv5.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-B43b6bZo.js → src-Bl1Kire1.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.46.0";
+const VERSION = "0.48.0";
 //#endregion
 export { findPath as a, preloadUrls as i, newUid as n, gridFromRows as o, assetUrls as r, VERSION as t };

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

@@ -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.
@@ -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-BboGNQr-.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: {