incanto 0.47.0 → 0.48.0

package/bin/incanto-frame.mjs

@@ -26,6 +26,7 @@ const { listeningPorts, parseProcNetTcp } = await import(
   pathToFileURL(join(PKG, 'dist', 'vite.js')).href
 );
 const { frameText, diffText } = await import(pathToFileURL(join(PKG, 'dist', '3d.js')).href);
+const { parseDrive } = await import(pathToFileURL(join(PKG, 'dist', 'index.js')).href);
 
 const args = process.argv.slice(2);
 const asJson = args.includes('--json');
@@ -39,6 +40,8 @@ const flag = (name) => {
 const gridArg = flag('--grid');
 const outArg = flag('--out');
 const sizeArg = flag('--size');
+const driveArg = flag('--do');
+const driveFile = flag('--do-file');
 const remember = flag('--remember');
 const diff = flag('--diff');
 const threshold = flag('--threshold');
@@ -49,6 +52,8 @@ if (args.includes('--help') || args.includes('-h')) {
   --grid WxH      cells across and down (default 16x9)
   --out FILE      also write the frame as a PNG you can look at
   --size N        longest side of that PNG (default 512)
+  --do SCRIPT     drive the game first, THEN capture (see below)
+  --do-file FILE  the same script, from a file
   --port N        skip discovery and use this port
 
   --remember [L]  keep this frame as the baseline named L (default "last")
@@ -64,6 +69,17 @@ the frame it fills. When that is not enough, look:
 
   incanto-frame --out shot.png    # then open it, or read it
 
+Every interesting state in a game is downstream of input, so --do drives the
+running game before capturing — the same words incanto-play takes:
+
+  incanto-frame --do "vector move 0 1; step 3000; vector move 0 0" --out bridge.png
+  incanto-frame --do "press jump; step 400" --out midair.png
+
+  press/release ACTION · vector ACTION X Y · key CODE down|up
+  pointer DX DY · step MS        (semicolons or newlines separate)
+
+step waits on the real clock: this is the live game, with its own loop.
+
 
 The report of ONE frame has a floor: a one-pixel seam is a fraction of a level
 once a cell is averaged, and nothing can tell it apart from a thin rope in the
@@ -111,6 +127,24 @@ function bsdListeningPorts() {
   }
 }
 
+/** The script to run before capturing, from `--do` or `--do-file`. */
+const driveScript = driveFile ? read(driveFile) : driveArg;
+if (driveFile && driveScript === null) {
+  console.error(`cannot read ${driveFile}`);
+  process.exit(1);
+}
+if (driveScript) {
+  const parsed = parseDrive(driveScript);
+  if (parsed.error) {
+    // Refuse here rather than in the page: a bad command that ran nothing would
+    // hand back the boot screen, and nothing about that frame would say so.
+    console.error(
+      `${parsed.error}\n  commands: press/release ACTION · vector ACTION X Y · key CODE down|up · pointer DX DY · step MS`,
+    );
+    process.exit(1);
+  }
+}
+
 const explicit = args.includes('--port') ? Number(args[args.indexOf('--port') + 1]) : null;
 const discovered = explicit ? [explicit] : await listeningPorts({ read });
 const ports = explicit ? discovered : [...new Set([...bsdListeningPorts(), ...discovered])];
@@ -150,12 +184,20 @@ if (!found) {
 const params = new URLSearchParams();
 if (gridArg !== null) params.set('grid', gridArg);
 if (outArg) params.set('image', sizeArg || '512');
+if (driveScript) {
+  params.set('drive', driveScript);
+  // Tell the server how long to wait: the script runs in real time.
+  const totalMs = parseDrive(driveScript).totalMs;
+  params.set('driveMs', String(totalMs));
+}
 if (remember !== null) params.set('remember', remember);
 if (diff !== null) params.set('diff', diff);
 if (threshold) params.set('threshold', threshold);
 const q = params.toString();
 const res = await fetch(`http://${found.host}:${found.port}/__incanto/frame${q ? `?${q}` : ''}`, {
-  signal: AbortSignal.timeout(10_000),
+  // Outlast the server's own budget, or the CLI gives up on an answer that
+  // was on its way.
+  signal: AbortSignal.timeout(15_000 + (driveScript ? parseDrive(driveScript).totalMs * 2 : 0)),
 });
 const body = await res.json().catch(() => null);
 
@@ -184,6 +226,18 @@ if (!res.ok || !body?.report) {
 }
 
 const report = body.report;
+// A drive that advanced no frames moved nothing: the inputs landed on a game
+// the browser had frozen, and the frame that came back is the one from before.
+// Saying nothing here would be handing over a picture that quietly lies.
+if (driveScript && report.droveFrames === 0) {
+  console.error(
+    'the drive ran but the game never advanced — 0 frames drawn.\n' +
+      '  The page is hidden (a window covered by another counts) and the browser\n' +
+      '  stops animating it, so the inputs landed on a frozen game and this frame\n' +
+      '  is unchanged. Bring the preview to the front and try again.',
+  );
+  process.exit(1);
+}
 if (report.error) {
   console.error(`the page could not capture a frame: ${report.error}`);
   process.exit(1);
@@ -215,6 +269,9 @@ if (asJson) {
   );
 } else {
   const lines = [frameText(report)];
+  if (typeof report.droveFrames === 'number') {
+    lines.push(`drove ${report.droveFrames} frames before capturing`);
+  }
   if (wroteImage) lines.push(`wrote ${wroteImage} — open it, or read it`);
   if (body.diffError === 'no-baseline') {
     lines.push(

package/bin/incanto-logs.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * incanto-logs — what the RUNNING game is saying.
+ *
+ *   bunx incanto-logs
+ *   bunx incanto-logs --json
+ *
+ * `incanto-frame` gets the pixels out of the browser; this gets the WORDS. The
+ * engine writes diagnostics for exactly this purpose — a model whose fit came
+ * out at 934x, an asset that 404'd, a node that quarantined itself — and until
+ * now every one of them reached a human only, in the debug overlay's logs
+ * panel. An agent could see a game and not hear it.
+ *
+ * Unlike a frame this needs no render, so it answers from a tab the browser has
+ * stopped drawing.
+ *
+ * Exit 1 when the game reports something wrong: an error logged, an error
+ * swallowed to keep it alive, or an asset that never loaded.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+const { listeningPorts } = await import(pathToFileURL(join(PKG, 'dist', 'vite.js')).href);
+const { logText } = await import(pathToFileURL(join(PKG, 'dist', 'index.js')).href);
+
+const args = process.argv.slice(2);
+const asJson = args.includes('--json');
+if (args.includes('--help') || args.includes('-h')) {
+  console.error(`Usage: incanto-logs [--json] [--port N]
+
+What the running game is saying: its warnings and errors, the errors it
+swallowed to keep going, the assets that never loaded, and its frame rate.
+
+Run your game's dev server and open the page first — the log buffer is in the
+browser, not in the dev server. This needs no render, so a page the browser has
+stopped drawing still answers.
+
+Exit 1 when something is wrong.`);
+  process.exit(0);
+}
+
+const read = (path) => {
+  try {
+    return readFileSync(path, 'utf-8');
+  } catch {
+    return null;
+  }
+};
+
+/** Ports listening on a machine with no `/proc` (macOS, BSD) — see incanto-frame. */
+function bsdListeningPorts() {
+  try {
+    const { execFileSync } = createRequire(import.meta.url)('node:child_process');
+    const out = execFileSync('lsof', ['-nP', '-iTCP', '-sTCP:LISTEN'], {
+      encoding: 'utf-8',
+      timeout: 1500,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const ports = new Set();
+    for (const line of out.split('\n')) {
+      const m = line.match(/:(\d+)\s*\(LISTEN\)/);
+      if (m) ports.add(Number(m[1]));
+    }
+    return [...ports];
+  } catch {
+    return [];
+  }
+}
+
+const explicit = args.includes('--port') ? Number(args[args.indexOf('--port') + 1]) : null;
+const discovered = explicit ? [explicit] : await listeningPorts({ read });
+const ports = explicit ? discovered : [...new Set([...bsdListeningPorts(), ...discovered])];
+
+let found = null;
+outer: for (const port of ports) {
+  for (const host of ['localhost', '127.0.0.1']) {
+    try {
+      const res = await fetch(`http://${host}:${port}/__incanto/ping`, {
+        signal: AbortSignal.timeout(300),
+      });
+      if (!res.ok) continue;
+      const body = await res.json();
+      if (body?.incanto) {
+        found = { host, port };
+        break outer;
+      }
+    } catch {
+      // not listening, not ours, or not answering — next
+    }
+  }
+}
+
+if (!found) {
+  console.error(
+    'no incanto dev server found.\n' +
+      '  Start your game (the dev server) and try again — the log buffer lives in\n' +
+      '  the running page, so there has to be one.',
+  );
+  process.exit(1);
+}
+
+const res = await fetch(`http://${found.host}:${found.port}/__incanto/logs`, {
+  signal: AbortSignal.timeout(10_000),
+});
+const body = await res.json().catch(() => null);
+
+if (res.status === 504 || body?.error === 'no-page-connected') {
+  console.error(
+    `the dev server is running on :${found.port}, but no page answered.\n` +
+      '  Open the preview in a browser — the log buffer is there, not in the server.',
+  );
+  process.exit(1);
+}
+if (!res.ok || !body?.report || body.report.error) {
+  console.error(
+    `could not read the game's logs: ${body?.report?.error ?? body?.error ?? res.status}`,
+  );
+  process.exit(1);
+}
+
+console.log(asJson ? JSON.stringify(body.report, null, 2) : logText(body.report));
+// `exitCode`, never `process.exit()` — stdout to a pipe is written
+// asynchronously and exiting discards what has not flushed.
+process.exitCode = body.report.ok ? 0 : 1;

package/bin/incanto-verify.mjs

@@ -13,6 +13,7 @@
  *   loads   incanto-check     the scene is legal and every asset resolves
  *   plays   incanto-playtest  a seeded run can actually finish it
  *   draws   incanto-frame     the GPU drew something, and the subject is in shot
+ *   says    incanto-logs      what the running game is complaining about
  *
  * Exit 1 when a rung FAILED. An unmeasured rung is not a failure — it prints
  * what to arrange, and says so in the summary.
@@ -41,6 +42,7 @@ Walks the whole ladder and tells you the ONE thing to do next:
   loads   the scene is legal and every asset resolves       (incanto-check)
   plays   a seeded run can actually finish it               (incanto-playtest)
   draws   the GPU drew something and the subject is in shot (incanto-frame)
+  says    the running game logs no errors and lost no assets (incanto-logs)
 
 Without a scene it looks for one *.scene.json under the current directory.
 "draws" needs a dev server with the page open; without one it is reported as
@@ -190,6 +192,35 @@ if (rungs[0].status === 'pass') {
  * deprecation notice lands on stdout ahead of the report, and treating that as
  * "the tool could not run" is how this reported a healthy scene as broken.
  */
+// ---- says ---------------------------------------------------------------
+{
+  const r = run('logs', ['--json']);
+  const report = safeJson(r.stdout);
+  if (!report) {
+    rungs.push({
+      name: 'says',
+      status: 'unmeasured',
+      summary: firstLine(r.stderr) ?? 'no page to ask',
+      fix: 'open the preview page and run this again — the log buffer is in the browser',
+    });
+  } else if (report.ok) {
+    rungs.push({ name: 'says', status: 'pass', summary: 'no errors, no failed assets' });
+  } else {
+    const asset = report.assetErrors?.[0];
+    rungs.push({
+      name: 'says',
+      status: 'fail',
+      // A game whose grass and water are fine still fails here when its player
+      // never loaded — which is the case this rung exists for, and the one
+      // `draws` calls healthy.
+      summary: asset
+        ? `asset ${asset.ref} never loaded: ${asset.error}`
+        : (report.worst?.message ?? `${report.stats?.errors ?? 0} errors were swallowed`),
+      fix: 'read it in full: `incanto-logs`',
+    });
+  }
+}
+
 function safeJson(text) {
   const raw = text ?? '';
   const start = raw.indexOf('{');

package/dist/3d.js

@@ -1,6 +1,6 @@
 import { A as Water3D, F as PhysicsBody3D, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D, V as WATER_MAX_RIPPLES, j as WATER_CUTOUT_MAX } from "./gameplay-BQOeAid6.js";
 import { A as Terrain3D, B as keyboardIntensity, C as resolveFlowerDensity, D as BoneLookAt3D, E as Camera3D, F as InstancedMesh3D, G as acquireTexture, H as rigPose, I as MeshInstance3D, M as TERRAIN_THEMES, N as terrainThemeLayers, O as BoneAttachment3D, P as Joint3D, R as QUARTER_PITCH, S as Flowers3D, T as CharacterController3D, U as TextureCache3D, V as movementState, W as acquireOwnTexture, _ as LoftMesh3D, a as Tree3D, b as Foliage3D, c as buildRiverRings, d as riverCarveChannels, f as riverStepFor, g as ModelInstance3D, h as Particles3D, i as VoxelGrid3D, j as DEFAULT_TERRAIN_TEXTURE_BASE, k as Billboard3D, l as findRiverCoverageGaps, m as traceDownhillPath, n as registerNodes3D, o as Trail3D, p as smoothCourse, r as VOXEL_PALETTE, s as River3D, u as projectToRiver, v as DirectionalLight3D, w as FLOWER_VARIETIES, x as DENSITY_PRESETS, y as OmniLight3D, z as cameraRelative } from "./environment-presets-D1b0ydTS.js";
-import { a as Environment3D, c as parseEnvironment3D, d as AssetStore3D, i as syncTree, l as sunDirectionFromElevationAzimuth, o as setEnvironment3D, r as Renderer3D, s as horizonColorFromSky, t as createGame3D, u as sunDirectionFromSky } from "./create-game-D16MVIPO.js";
+import { a as Environment3D, c as parseEnvironment3D, d as AssetStore3D, i as syncTree, l as sunDirectionFromElevationAzimuth, o as setEnvironment3D, r as Renderer3D, s as horizonColorFromSky, t as createGame3D, u as sunDirectionFromSky } from "./create-game-akjPkFv5.js";
 import { a as frameSignature, n as diffSignatures, o as frameStats, r as diffText, s as frameText, t as SIGNATURE_GRID } from "./frame-report-njybhZon.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
 import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-CSoGjM8P.js";

package/dist/{create-game-D16MVIPO.js → create-game-akjPkFv5.js}

@@ -2,6 +2,7 @@ import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
 import { n as loadScene, v as diagnose, w as registerBehavior } from "./loader-r49nDwB4.js";
 import { _ as qualityCaps, h as Engine, m as AudioPlayer, y as qualityRendering } from "./register-BSXV8T9F.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
+import { r as parseDrive, t as logReport } from "./log-report-lxrQY9cH.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-BoNg_MnF.js";
 import { a as openBundledEditor, i as devServerLibrary, n as pauseWhenHidden, o as poseFromRenderer, r as crossFade, t as teardown } from "./teardown-BKTCzLek.js";
 import { B as createCausticsQuad, F as PhysicsBody3D, R as Node3D, n as registerGameplayBehaviors } from "./gameplay-BQOeAid6.js";
@@ -2455,17 +2456,69 @@ async function createGame3D(opts) {
 		if (!capture) throw new IncantoError("TREE_VIOLATION", "this renderer cannot capture frames");
 		return capture.call(renderer);
 	};
+	/**
+	* Run a drive script against the LIVE game, in real time.
+	*
+	* `step` waits on the wall clock rather than advancing a fixed timestep: this
+	* is the running game, with its own loop, its own physics and its own
+	* animation. Stepping it by hand would fight all three.
+	*/
+	const applyDrive = async (steps) => {
+		let frames = 0;
+		let watching = true;
+		const tick = () => {
+			if (!watching) return;
+			frames += 1;
+			requestAnimationFrame(tick);
+		};
+		requestAnimationFrame(tick);
+		for (const s of steps) switch (s.kind) {
+			case "press":
+				engine.input.pressAction(s.action);
+				break;
+			case "release":
+				engine.input.releaseAction(s.action);
+				break;
+			case "vector":
+				engine.input.setActionVector(s.action, s.x, s.y);
+				break;
+			case "key":
+				engine.input.handleKey(s.code, s.down);
+				break;
+			case "pointer":
+				engine.input.handlePointerMove(s.dx, s.dy);
+				break;
+			case "step":
+				await new Promise((r) => setTimeout(r, s.ms));
+				break;
+		}
+		watching = false;
+		return frames;
+	};
 	const hot = import.meta.hot;
 	if (hot) {
 		const onFrameRequest = (data) => {
 			const request = data;
 			const id = request?.id;
 			hot.send("incanto:frame-ack", { id });
-			captureFramePixels().then((shot) => hot.send("incanto:frame-report", {
+			const drive = request?.drive ? parseDrive(request.drive) : null;
+			if (drive?.error) {
+				hot.send("incanto:frame-report", {
+					id,
+					report: { error: drive.error }
+				});
+				return;
+			}
+			let droveFrames = null;
+			(drive ? applyDrive(drive.steps) : Promise.resolve(null)).then((frames) => {
+				droveFrames = frames;
+				return captureFramePixels();
+			}).then((shot) => hot.send("incanto:frame-report", {
 				id,
 				report: {
 					...frameStats(shot.pixels, shot.width, shot.height, { grid: request?.grid }),
 					signature: frameSignature(shot.pixels, shot.width, shot.height),
+					...droveFrames === null ? {} : { droveFrames },
 					...request?.image ? { image: frameImage(shot.pixels, shot.width, shot.height, (w, h) => Object.assign(document.createElement("canvas"), {
 						width: w,
 						height: h
@@ -2478,6 +2531,30 @@ async function createGame3D(opts) {
 		};
 		hot.on("incanto:frame-request", onFrameRequest);
 		cleanups.push(() => hot.off?.("incanto:frame-request", onFrameRequest));
+		const onLogsRequest = (data) => {
+			const id = data?.id;
+			try {
+				hot.send("incanto:logs-report", {
+					id,
+					report: logReport({
+						entries: engine.log.entries(),
+						stats: {
+							...engine.stats(),
+							...renderer.stats?.() ?? {}
+						},
+						assetErrors: renderer.assets?.errors() ?? [],
+						hidden: typeof document !== "undefined" && document.hidden
+					})
+				});
+			} catch (error) {
+				hot.send("incanto:logs-report", {
+					id,
+					report: { error: error instanceof Error ? error.message : String(error) }
+				});
+			}
+		};
+		hot.on("incanto:logs-request", onLogsRequest);
+		cleanups.push(() => hot.off?.("incanto:logs-request", onLogsRequest));
 	}
 	cleanups.push(pauseWhenHidden(engine));
 	await report(1, "ready");

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-Ca3oV1fe.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-D16MVIPO.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-Ca3oV1fe.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.47.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/vite.js

@@ -1,4 +1,4 @@
-import { t as VERSION } from "./src-Ca3oV1fe.js";
+import { t as VERSION } from "./src-Bl1Kire1.js";
 import { n as diffSignatures } from "./frame-report-njybhZon.js";
 import { s as validateScene } from "./test-E4-otKqK.js";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
@@ -60,6 +60,7 @@ function serveFrameEndpoints(host, version, opts = {}) {
 	for (const c of channels) {
 		c.on("incanto:frame-report", onReport);
 		c.on("incanto:frame-ack", onAck);
+		c.on("incanto:logs-report", onReport);
 	}
 	host.middlewares.use("/__incanto/ping", (_req, res) => {
 		json$1(res, 200, {
@@ -67,6 +68,7 @@ function serveFrameEndpoints(host, version, opts = {}) {
 			frame: Boolean(channel)
 		});
 	});
+	serveLogs(host, channels, waiting, () => nextId++, timeoutMs);
 	host.middlewares.use("/__incanto/frame", (req, res) => {
 		if (!channel) {
 			json$1(res, 503, { error: "no-hmr-channel" });
@@ -78,11 +80,13 @@ function serveFrameEndpoints(host, version, opts = {}) {
 		const threshold = Number(params.get("threshold"));
 		const grid = parseGrid(params.get("grid"));
 		const image = Math.max(0, Math.min(2048, Number(params.get("image")) || 0));
+		const drive = params.get("drive") ?? "";
+		const driveMs = Math.max(0, Math.min(12e4, Number(params.get("driveMs")) || 0));
 		const id = nextId++;
 		const timer = setTimeout(() => {
 			waiting.delete(id);
 			json$1(res, 504, { error: acked.delete(id) ? "page-not-drawing" : "no-page-connected" });
-		}, timeoutMs);
+		}, timeoutMs + (driveMs > 0 ? driveMs * 2 + 2e3 : 0));
 		waiting.set(id, (value) => {
 			clearTimeout(timer);
 			acked.delete(id);
@@ -113,11 +117,44 @@ function serveFrameEndpoints(host, version, opts = {}) {
 			data: {
 				id,
 				grid,
-				image
+				image,
+				...drive ? { drive } : {}
 			}
 		});
 	});
 }
+/**
+* `/__incanto/logs` — what the game is SAYING, not what it looks like.
+*
+* Same round trip as a frame and a different question. It needs no render, so
+* unlike a frame it answers from a tab the browser has stopped drawing.
+*/
+function serveLogs(host, channels, waiting, nextId, timeoutMs) {
+	host.middlewares.use("/__incanto/logs", (_req, res) => {
+		if (channels.length === 0) {
+			json$1(res, 503, { error: "no-hmr-channel" });
+			return;
+		}
+		const id = nextId();
+		const timer = setTimeout(() => {
+			waiting.delete(id);
+			json$1(res, 504, { error: "no-page-connected" });
+		}, timeoutMs);
+		waiting.set(id, (value) => {
+			clearTimeout(timer);
+			if (!value.ok) {
+				json$1(res, 500, { error: "report-failed" });
+				return;
+			}
+			json$1(res, 200, { report: value.report });
+		});
+		for (const c of channels) c.send({
+			type: "custom",
+			event: "incanto:logs-request",
+			data: { id }
+		});
+	});
+}
 function query(req) {
 	const url = req?.originalUrl ?? req?.url ?? "";
 	const q = url.indexOf("?");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "incanto",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",
@@ -99,6 +99,7 @@
     "incanto-feel": "bin/incanto-feel.mjs",
     "incanto-new": "bin/incanto-new.mjs",
     "incanto-frame": "bin/incanto-frame.mjs",
-    "incanto-verify": "./bin/incanto-verify.mjs"
+    "incanto-verify": "./bin/incanto-verify.mjs",
+    "incanto-logs": "./bin/incanto-logs.mjs"
   }
 }

package/skills/incanto-verifying-your-game.md

@@ -348,6 +348,32 @@ ceiling — drive `engine.timeScale`, with `0.25× 0.5× 1× 2×` presets:
 number is refused and negatives clamp to 0: the scale multiplies every dt in
 the engine, so one NaN would take physics, timers and animation with it.
 
+### `bunx incanto-logs` — what the game is SAYING
+
+`incanto-frame` gets the pixels out of the browser; this gets the words. The
+engine writes diagnostics for exactly this — and until they had a channel out,
+they reached a human only, in the debug overlay's logs panel.
+
+```
+$ bunx incanto-logs
+asset $characters/base never loaded: … responded with 404
+[error] incanto: failed to load model '…/NO-SUCH-MODEL.glb'
+82 nodes · frame rate not measurable — the page is hidden (a window covered by
+another counts), and the browser throttles it. Bring it to the front
+```
+
+That game's grass, water and trees all rendered — `incanto-frame` called it
+healthy (`subject fills 84.2%`) because they ARE there. Only the player was
+missing. **Pixels and words answer different questions; a game can pass one and
+fail the other**, which is why both are rungs.
+
+It needs no render, so it answers from a page the browser has stopped drawing.
+Exit 1 when something is wrong: an error logged, an error swallowed to keep the
+game alive, or an asset that never loaded.
+
+A repeated warning is folded into one line with a count (`×600`) — a game
+shouting the same thing every frame has one problem, not six hundred.
+
 ### `bunx incanto-frame` — what is actually on screen
 
 The rung above framing. `framing` PREDICTS what the camera should see from the
@@ -386,6 +412,33 @@ browser, not in the dev server.** You do not have to tell it where anything is
 it reads the ports that are actually listening, asks each one whether it is an
 incanto dev server, and asks that page for a frame over vite's own HMR channel.
 
+#### Drive it somewhere first
+
+Every interesting state in a game is downstream of input, and the boot screen is
+the only frame anything could capture before this:
+
+```
+$ bunx incanto-frame --do "vector move 0 1; step 3000; vector move 0 0" --out bridge.png
+frame 1280×720 · luminance 0.68
+subject fills 21.4% of frame
+drove 180 frames before capturing
+wrote bridge.png — open it, or read it
+```
+
+The same words `incanto-play` takes — `press`/`release ACTION`, `vector ACTION X Y`,
+`key CODE down|up`, `pointer DX DY`, `step MS`, separated by semicolons or
+newlines. `--do-file` reads a longer plan from a file. One vocabulary for the
+headless gamepad and the live one.
+
+`step` waits on the REAL clock: this is the running game, with its own loop, its
+own physics and its own animation, and stepping it by hand would fight all three.
+
+**`drove N frames` is the number to check.** A browser stops animating a tab it
+considers hidden — including a window merely covered by another — and the inputs
+then land on a game that never advances: the capture comes back UNCHANGED and
+looks perfectly healthy. `drove 0 frames` is refused with an error rather than
+handed over as a picture.
+
 #### Look at it
 
 ```

package/templates-app/beacon-isle-3d/package.json

@@ -14,7 +14,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.47.0",
+    "incanto": "^0.48.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/tps-3d/package.json

@@ -13,7 +13,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.47.0",
+    "incanto": "^0.48.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/village-quest-3d/package.json

@@ -13,7 +13,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.47.0",
+    "incanto": "^0.48.0",
     "three": "^0.184.0"
   },
   "devDependencies": {