incanto 0.55.0 → 0.57.0

package/bin/incanto-verify.mjs

@@ -109,14 +109,21 @@ const rungs = [];
 {
   const r = run('check', [scene, '--json']);
   const out = safeJson(r.stdout);
-  const problems = out?.files?.flatMap((f) => f.problems ?? []) ?? [];
+  // `incanto-check --json` emits { ok, results: [{ file, ok, code, message }] }.
+  // This read `out.files[].problems[].why` — three keys that have never existed —
+  // so the summary always fell through to the first line of the pretty-printed
+  // JSON, which is `{`. Every scene-validation failure, the top rung of the
+  // ladder, rendered as `✗ loads — {` with the sentence naming the node path and
+  // the legal values sitting one key away in the same object.
+  const broke = out?.results?.find((entry) => entry && entry.ok === false);
+  const detail = broke && (broke.message || broke.code) ? `[${broke.code}] ${broke.message}` : null;
   rungs.push(
     r.status === 0
       ? { name: 'loads', status: 'pass', summary: 'the scene is legal and its assets resolve' }
       : {
           name: 'loads',
           status: 'fail',
-          summary: problems[0]?.why ?? firstLine(r.stdout || r.stderr) ?? 'incanto-check failed',
+          summary: detail ?? firstLine(r.stderr) ?? 'incanto-check failed',
           fix: `fix that, then run again — nothing above this rung means anything until it is green (\`incanto-check ${scene}\` for the detail)`,
         },
   );

package/dist/2d.d.ts

@@ -1,7 +1,8 @@
-import { At as Node, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, n as BehaviorCtor, w as GameStats } from "./behavior-CyQoSu4n.js";
+import { At as Node, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, n as BehaviorCtor, w as GameStats } from "./behavior-l08AEbq9.js";
 import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-DAvWQeld.js";
 import { i as SceneJson, s as JsonObject } from "./schema-CFeioQRE.js";
-import { t as LoadSceneOptions } from "./loader-DhI1jFW_.js";
+import { r as FrameStats } from "./frame-report-DCnHFmto.js";
+import { t as LoadSceneOptions } from "./loader-BbEMTuWg.js";
 import { n as AnimationEntry } from "./sprite-animation-CMr6f1K2.js";
 import { r as ParticleView, t as ParticleSim } from "./particle-sim-C5OfBbmU.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
@@ -388,6 +389,16 @@ interface Game2D {
   engine: Engine;
   scene: Scene$1;
   /**
+  * What the last drawn frame actually looks like, as numbers.
+  *
+  * The 3D game has answered this since 0.47 and a 2D game could not, so
+  * `incanto-frame` and `incanto-verify`'s `draws` rung were permanently
+  * unmeasured for half the engine's games.
+  */
+  frame(opts?: {
+    grid?: [number, number];
+  }): Promise<FrameStats>;
+  /**
   * The AUTHORED scene this game booted from — the JSON, not the live tree.
   * A running tree has moved; the editor gets what was written down.
   */
@@ -691,6 +702,14 @@ declare class Label extends Node2D {
   _quad(): Mesh;
   override _syncObject2D(assets: AssetStore2D | null): void;
   private rasterize;
+  /**
+  * Hand the canvas and its texture back.
+  *
+  * LABEL_PLANE is shared by every Label in the process and stays; the material
+  * and the CanvasTexture are this node's, and a scene that spawns floating
+  * text left one of each behind per freed node.
+  */
+  override free(): void;
 }
 //#endregion
 //#region src/2d/nodes/particles-2d.d.ts
@@ -768,6 +787,15 @@ declare class Particles2D extends Node2D {
   * (dust under a player) as well as the node's own position.
   */
   private holdWorldSpace;
+  /** What the current mesh was built FOR — capacity and blend, the two things
+  *  baked into it. Not the draw count, which changes every frame. */
+  private meshKey;
+  /**
+  * Hand the GPU back. UNIT_PLANE is shared by every 2D particle system in the
+  * process, so the geometry stays; the per-node material and the instance
+  * buffers inside the InstancedMesh do not.
+  */
+  override free(): void;
   /** Tell the engine an effect fired — the visual half of the audio record. */
   private report;
   /** Restart a one-shot (re-burst + allow finished to fire again). */
@@ -815,6 +843,8 @@ declare class TileMap2D extends Node2D {
   private _solid;
   /** Rebuild flags — raised when the map-shaping props are REPLACED. */
   private geometryDirty;
+  /** Reported once per atlas, so a bad grid says so on the first build only. */
+  private gridChecked;
   private collidersDirty;
   /** Replace the whole array to change the map (mutations are not watched). */
   get cells(): (string | number[])[];
@@ -909,11 +939,6 @@ interface Renderer2DOptions {
   /** MSAA on the canvas. Defaults to TRUE (Phaser parity). */
   antialias?: boolean;
 }
-/**
-* 2D presentation layer: world pass through the active Camera2D
-* (center/zoom/limits), then a screen-space UI pass for UILayer subtrees.
-* 1 unit = 1 px, (0,0) top-left, +y down.
-*/
 declare class Renderer2D {
   /**
   * When set, the world pass frames THIS view instead of the scene's active
@@ -926,6 +951,33 @@ declare class Renderer2D {
     zoom: number;
   } | null;
   private readonly webgl;
+  /**
+  * The pixels of the next drawn frame — how `incanto-frame` sees a 2D game.
+  *
+  * Mirrors Renderer3D exactly: read inside the render, so
+  * `preserveDrawingBuffer` can stay off, and nudge a frame ourselves after a
+  * moment because a browser stops handing rAF to a tab it thinks is hidden —
+  * including a window merely covered by another one. Without the nudge the
+  * promise never settles and the CLI reports "no page connected" about a page
+  * that is right there.
+  */
+  captureFrame(): Promise<{
+    pixels: Uint8Array;
+    width: number;
+    height: number;
+  }>;
+  private pendingCaptures;
+  /** Hand the waiting captures this frame's pixels. Called at the end of render. */
+  private drainFrameCapture;
+  /** The pixel ratio the scene asked for, before any render-scale setting. */
+  private basePixelRatio;
+  /**
+  * Fewer pixels for the same world — the cheapest frames on a weak device.
+  *
+  * `settings.renderScale` persisted and was applied by the 3D boot only, so a
+  * 2D game's resolution slider saved a number and changed nothing, forever.
+  */
+  setRenderScale(scale: number): void;
   private readonly worldScene;
   private readonly syncScratch;
   /** Editors set this: keep syncing `static: true` subtrees every frame. */

package/dist/2d.js

@@ -1,7 +1,7 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-BRt6XKmP.js";
-import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-en63AEZO.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-CfWAggJ1.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-DpbUrMOQ.js";
+import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-C6ZBFRjd.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-BLcvEFDR.js";
 //#region src/2d/library-sprite.ts
 /**
 * What a `CharacterController2D`/`3D` will ask a skin to play, and the clip in

package/dist/3d.d.ts

@@ -1,10 +1,10 @@
-import { At as Node, D as QualityCaps, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, n as BehaviorCtor, w as GameStats } from "./behavior-CyQoSu4n.js";
+import { At as Node, D as QualityCaps, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, n as BehaviorCtor, w as GameStats } from "./behavior-l08AEbq9.js";
 import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-DAvWQeld.js";
 import { i as SceneJson$1, s as JsonObject } from "./schema-CFeioQRE.js";
-import { t as LoadSceneOptions } from "./loader-DhI1jFW_.js";
+import { a as GridCell, c as diffText, d as frameText, i as FrameStatsOptions, l as frameSignature, n as FrameSignature, o as SIGNATURE_GRID, r as FrameStats, s as diffSignatures, t as FrameDiff, u as frameStats } from "./frame-report-DCnHFmto.js";
+import { t as LoadSceneOptions } from "./loader-BbEMTuWg.js";
 import { r as ParticleView, t as ParticleSim } from "./particle-sim-C5OfBbmU.js";
-import { a as GridCell, c as diffText, d as frameText, i as FrameStatsOptions, l as frameSignature, n as FrameSignature, o as SIGNATURE_GRID, r as FrameStats, s as diffSignatures, t as FrameDiff, u as frameStats } from "./frame-report-DZ70IY26.js";
-import { n as PathGrid, s as SpatialPose } from "./pathfinding-CXGCpRQe.js";
+import { n as PathGrid, s as SpatialPose } from "./pathfinding-mEN4V1CU.js";
 import { AnimationClip, AnimationMixer, BufferGeometry, Color, DirectionalLight, Group, InstancedMesh, Mesh, MeshPhysicalMaterial, Object3D, PerspectiveCamera, Scene, ShaderMaterial, Texture, Vector3, WebGLRenderer } from "three";
 import { VRM } from "@pixiv/three-vrm";
 import { Sky } from "three/examples/jsm/objects/Sky.js";
@@ -902,6 +902,9 @@ declare class Environment3D {
   /** Underwater fog/tint, created lazily the first time the camera submerges. */
   private underwaterFog;
   private readonly underwaterBg;
+  /** Told when the scene's HDRI/preset lighting fails to arrive. Set by the
+  *  renderer, which is the piece that knows the engine and the asset store. */
+  onHdriError: ((url: string, error: unknown) => void) | null;
   constructor(scene: Scene);
   /** The sky's unit sun direction, or null when no sky is declared. */
   get sunDirection(): [number, number, number] | null;
@@ -1141,6 +1144,21 @@ declare class BoneAttachment3D extends Node3D {
   get attachedBone(): Object3D | null;
   _onRender3D(_ctx: RenderContext3D): void;
   override free(): void;
+  /** The model this attachment last looked in. */
+  private source;
+  private reportedBone;
+  /**
+  * Say when the bone NAME is wrong, without accusing a model that is still
+  * loading.
+  *
+  * The lookup retries every frame on purpose — a GLB mounts async — so the
+  * node can never conclude on its own that the name is bad. But once the model
+  * HAS bones and this one is not among them, it is a typo, and the list that
+  * would fix it is sitting in `boneNames()` right next to `findBone`. Until
+  * now a misspelled bone left the sword at the mount node's authored position
+  * while the character animated away from it, forever, in silence.
+  */
+  private reportMissingBone;
 }
 //#endregion
 //#region src/3d/nodes/bone-look-at-3d.d.ts
@@ -1262,6 +1280,18 @@ declare class CharacterController3D extends Node3D {
   private get body();
   override onEnterTree(): void;
   override fixedUpdate(dt: number): void;
+  /** Actions already reported missing, so a per-frame read says it once. */
+  private readonly reportedActions;
+  /**
+  * Read an input action this controller is allowed to be missing.
+  *
+  * Tolerated because a game may declare no sprint key and no jump; reported
+  * because otherwise a TYPO looks exactly like a deliberate omission, and the
+  * engine has already thrown the sentence that fixes it.
+  */
+  private readAction;
+  /** Report a throw the caller already caught (the move read has its own try). */
+  private reportMissingAction;
   override update(dt: number): void;
   private pivot;
   private cameraCache;

package/dist/3d.js

@@ -1,9 +1,9 @@
-import { F as CharacterBody3D, H as WATER_MAX_RIPPLES, I as PhysicsBody3D, L as RigidBody3D, M as WATER_CUTOUT_MAX, N as WaterCutout3D, P as Area3D, R as StaticBody3D, j as Water3D, z as Node3D } from "./gameplay-CZ2yq37J.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-DAbEdEwh.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-CzK9_pzg.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 { a as frameSignature, n as diffSignatures, o as frameStats, r as diffText, s as frameText, t as SIGNATURE_GRID } from "./frame-report-BSMny7oe.js";
+import { B as StaticBody3D, F as WaterCutout3D, I as Area3D, L as CharacterBody3D, N as Water3D, P as WATER_CUTOUT_MAX, R as PhysicsBody3D, V as Node3D, W as WATER_MAX_RIPPLES, z as RigidBody3D } from "./gameplay-BVphcxmE.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-CvvQr_bJ.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-C5jQYPah.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-C_ZJ6f_d.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-QBrfIT2Y.js";
 //#region src/3d/model-verdict.ts
 /** Mixamo exports every bone as `mixamorigX`; the retargeter binds by that name. */
 const MIXAMO = /^mixamorig[:_]?/i;

package/dist/{behavior-CyQoSu4n.d.ts → behavior-l08AEbq9.d.ts}

@@ -465,6 +465,11 @@ declare class MusicManager {
   * With an inert backend the state machine runs identically and nothing plays.
   */
   private ensure;
+  /**
+  * Where a track that will never play gets reported. The engine sets this; a
+  * bare MusicManager (tests) stays quiet.
+  */
+  onTrackError: ((src: string, reason: string) => void) | null;
   /** Resume a gesture-suspended context + (re)start any pending track. */
   unlock(): void;
   /** Play a single track (replacing any current one immediately, no fade). */

package/dist/{create-game-CzK9_pzg.js → create-game-C5jQYPah.js}

@@ -1,15 +1,14 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { A as registerBehavior, C as diagnose, n as loadScene } from "./loader-BTkHYrQn.js";
-import { C as qualityCaps, T as qualityRendering, b as AudioPlayer, x as Engine } from "./register-p48lHE2o.js";
+import { A as registerBehavior, C as diagnose, n as loadScene } from "./loader-BcrRSjxB.js";
+import { _ as Engine, g as AudioPlayer, x as qualityRendering, y as qualityCaps } from "./register-Ch70uByv.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { r as parseDrive, t as logReport } from "./log-report-CPFm4OXf.js";
-import { i as resolveRendering, n as attachTouchControls } from "./touch-BnMyy9tr.js";
-import { a as openBundledEditor, c as audioErrors, i as devServerLibrary, n as pauseWhenHidden, o as poseFromRenderer, r as crossFade, s as claimCanvasGestures, t as teardown } from "./teardown-C7uVSJvx.js";
-import { I as PhysicsBody3D, V as createCausticsQuad, n as registerGameplayBehaviors, z as Node3D } from "./gameplay-CZ2yq37J.js";
+import { i as resolveRendering, n as attachTouchControls } from "./touch-DESwnpOc.js";
+import { a as openBundledEditor, c as claimCanvasGestures, i as devServerLibrary, l as audioErrors, n as pauseWhenHidden, o as poseFromRenderer, r as crossFade, s as wireDevChannel, t as teardown } from "./teardown-Cs113S9F.js";
+import { o as frameStats } from "./frame-report-BSMny7oe.js";
+import { R as PhysicsBody3D, U as createCausticsQuad, V as Node3D, n as registerGameplayBehaviors } from "./gameplay-BVphcxmE.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { E as Camera3D, U as TextureCache3D, g as ModelInstance3D, n as registerNodes3D, t as resolveEnvironmentHdri, v as DirectionalLight3D } from "./environment-presets-DAbEdEwh.js";
-import { a as frameSignature, i as frameImage, o as frameStats } from "./frame-report-njybhZon.js";
-import { n as enablePhysics3D } from "./physics-3d-C_ZJ6f_d.js";
+import { E as Camera3D, U as TextureCache3D, g as ModelInstance3D, n as registerNodes3D, t as resolveEnvironmentHdri, v as DirectionalLight3D } from "./environment-presets-CvvQr_bJ.js";
+import { n as enablePhysics3D } from "./physics-3d-QBrfIT2Y.js";
 import { ACESFilmicToneMapping, AmbientLight, Box3, BufferAttribute, BufferGeometry, Color, DepthTexture, EquirectangularReflectionMapping, FloatType, Fog, HalfFloatType, LineBasicMaterial, LineSegments, Matrix4, Mesh, PCFShadowMap, PMREMGenerator, PerspectiveCamera, PlaneGeometry, Quaternion, Raycaster, Scene, ShaderMaterial, Vector2, Vector3, WebGLRenderTarget, WebGLRenderer } from "three";
 import { VRMLoaderPlugin, VRMUtils } from "@pixiv/three-vrm";
 import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
@@ -1014,6 +1013,9 @@ var Environment3D = class {
 	/** Underwater fog/tint, created lazily the first time the camera submerges. */
 	underwaterFog = null;
 	underwaterBg = new Color();
+	/** Told when the scene's HDRI/preset lighting fails to arrive. Set by the
+	*  renderer, which is the piece that knows the engine and the asset store. */
+	onHdriError = null;
 	constructor(scene) {
 		this.scene = scene;
 		this.scene.add(this.ambient);
@@ -1161,6 +1163,8 @@ var Environment3D = class {
 			}
 			texture.mapping = EquirectangularReflectionMapping;
 			this.hdriTexture = texture;
+		}, void 0, (error) => {
+			this.onHdriError?.(url, error);
 		});
 	}
 	applySky(sky, gl) {
@@ -1575,7 +1579,14 @@ var Renderer3D = class {
 	};
 	webgl;
 	threeScene = new Scene();
-	environment = new Environment3D(this.threeScene);
+	environment = (() => {
+		const env = new Environment3D(this.threeScene);
+		env.onHdriError = (url, error) => {
+			this.assets.textures.noteError(url, error);
+			diagnose(this.engine, "error", `[incanto] the scene's lighting (${url}) could not be loaded — nothing else lights it.`);
+		};
+		return env;
+	})();
 	engine;
 	disconnect;
 	canvas;
@@ -2500,67 +2511,13 @@ async function createGame3D(opts) {
 		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 });
-			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
-					}), request.image) } : {}
-				}
-			})).catch((error) => hot.send("incanto:frame-report", {
-				id,
-				report: { error: error instanceof Error ? error.message : String(error) }
-			}));
-		};
-		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(...wireDevChannel({
+		engine,
+		applyDrive,
+		captureFramePixels,
+		rendererStats: () => renderer.stats?.(),
+		assetErrors: () => renderer.assets?.errors() ?? []
+	}));
 	cleanups.push(pauseWhenHidden(engine));
 	await report(1, "ready");
 	function disposeGame() {

package/dist/{create-game-BRt6XKmP.js → create-game-DpbUrMOQ.js}

@@ -1,13 +1,14 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { A as registerBehavior, C as diagnose, n as loadScene, o as computeViewport, s as resolveViewport } from "./loader-BTkHYrQn.js";
-import { b as AudioPlayer, x as Engine } from "./register-p48lHE2o.js";
+import { A as registerBehavior, C as diagnose, n as loadScene, o as computeViewport, s as resolveViewport } from "./loader-BcrRSjxB.js";
+import { _ as Engine, g as AudioPlayer } from "./register-Ch70uByv.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { i as resolveRendering, n as attachTouchControls } from "./touch-BnMyy9tr.js";
-import { a as openBundledEditor, c as audioErrors, i as devServerLibrary, n as pauseWhenHidden, r as crossFade, s as claimCanvasGestures, t as teardown } from "./teardown-C7uVSJvx.js";
-import { n as registerGameplayBehaviors } from "./gameplay-CZ2yq37J.js";
-import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-en63AEZO.js";
+import { i as resolveRendering, n as attachTouchControls } from "./touch-DESwnpOc.js";
+import { a as openBundledEditor, c as claimCanvasGestures, i as devServerLibrary, l as audioErrors, n as pauseWhenHidden, r as crossFade, s as wireDevChannel, t as teardown } from "./teardown-Cs113S9F.js";
+import { o as frameStats } from "./frame-report-BSMny7oe.js";
+import { n as registerGameplayBehaviors } from "./gameplay-BVphcxmE.js";
+import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-C6ZBFRjd.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { n as enablePhysics2D } from "./physics-2d-CfWAggJ1.js";
+import { n as enablePhysics2D } from "./physics-2d-BLcvEFDR.js";
 import { Box3, BufferAttribute, BufferGeometry, Color, LineBasicMaterial, LineSegments, LinearFilter, NearestFilter, OrthographicCamera, Raycaster, SRGBColorSpace, Scene, TextureLoader, Vector2, Vector3, WebGLRenderer } from "three";
 //#region src/2d/assets.ts
 /**
@@ -276,6 +277,8 @@ function prune(obj, visited) {
 * (center/zoom/limits), then a screen-space UI pass for UILayer subtrees.
 * 1 unit = 1 px, (0,0) top-left, +y down.
 */
+/** How long to wait for the game's own loop before drawing a frame ourselves. */
+const CAPTURE_NUDGE_MS = 120;
 var Renderer2D = class {
 	/**
 	* When set, the world pass frames THIS view instead of the scene's active
@@ -284,6 +287,76 @@ var Renderer2D = class {
 	*/
 	viewOverride = null;
 	webgl;
+	/**
+	* The pixels of the next drawn frame — how `incanto-frame` sees a 2D game.
+	*
+	* Mirrors Renderer3D exactly: read inside the render, so
+	* `preserveDrawingBuffer` can stay off, and nudge a frame ourselves after a
+	* moment because a browser stops handing rAF to a tab it thinks is hidden —
+	* including a window merely covered by another one. Without the nudge the
+	* promise never settles and the CLI reports "no page connected" about a page
+	* that is right there.
+	*/
+	captureFrame() {
+		return new Promise((resolve, reject) => {
+			this.pendingCaptures.push({
+				resolve,
+				reject
+			});
+			setTimeout(() => {
+				if (this.pendingCaptures.length > 0) try {
+					this.render();
+				} catch (error) {
+					const e = error instanceof Error ? error : new Error(String(error));
+					for (const w of this.pendingCaptures.splice(0)) w.reject(e);
+				}
+			}, CAPTURE_NUDGE_MS);
+		});
+	}
+	pendingCaptures = [];
+	/** Hand the waiting captures this frame's pixels. Called at the end of render. */
+	drainFrameCapture() {
+		if (this.pendingCaptures.length === 0) return;
+		const waiting = this.pendingCaptures;
+		this.pendingCaptures = [];
+		try {
+			const gl = this.webgl.getContext();
+			const width = this.webgl.domElement.width;
+			const height = this.webgl.domElement.height;
+			const pixels = new Uint8Array(width * height * 4);
+			this.webgl.setRenderTarget(null);
+			gl.readPixels(0, 0, width, height, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
+			for (let y = 0; y < Math.floor(height / 2); y++) {
+				const top = y * width * 4;
+				const bottom = (height - 1 - y) * width * 4;
+				for (let i = 0; i < width * 4; i++) {
+					const t = pixels[top + i];
+					pixels[top + i] = pixels[bottom + i];
+					pixels[bottom + i] = t;
+				}
+			}
+			for (const w of waiting) w.resolve({
+				pixels,
+				width,
+				height
+			});
+		} catch (error) {
+			const e = error instanceof Error ? error : new Error(String(error));
+			for (const w of waiting) w.reject(e);
+		}
+	}
+	/** The pixel ratio the scene asked for, before any render-scale setting. */
+	basePixelRatio = 1;
+	/**
+	* Fewer pixels for the same world — the cheapest frames on a weak device.
+	*
+	* `settings.renderScale` persisted and was applied by the 3D boot only, so a
+	* 2D game's resolution slider saved a number and changed nothing, forever.
+	*/
+	setRenderScale(scale) {
+		const clamped = Number.isFinite(scale) && scale > 0 ? Math.min(2, Math.max(.25, scale)) : 1;
+		this.webgl.setPixelRatio(this.basePixelRatio * clamped);
+	}
 	worldScene = new Scene();
 	syncScratch = createSync2DScratch();
 	/** Editors set this: keep syncing `static: true` subtrees every frame. */
@@ -313,6 +386,7 @@ var Renderer2D = class {
 		});
 		this.webgl.info.autoReset = false;
 		this.engine.picker = (x, y) => this.pick(x, y);
+		this.basePixelRatio = rendering.pixelRatio;
 		this.webgl.setPixelRatio(rendering.pixelRatio);
 		this.webgl.info.autoReset = false;
 		this.debugLines = new LineSegments(new BufferGeometry(), new LineBasicMaterial({
@@ -447,6 +521,7 @@ var Renderer2D = class {
 		this.webgl.autoClear = false;
 		this.webgl.render(this.uiScene, this.uiCam);
 		this.webgl.autoClear = true;
+		this.drainFrameCapture();
 	}
 	/** UI-pass extent from the last render — the space HUD nodes are posed in. */
 	lastUi = {
@@ -663,6 +738,64 @@ async function createGame2D(opts) {
 		...opts.pixelRatio !== void 0 ? { pixelRatio: opts.pixelRatio } : {},
 		...opts.antialias !== void 0 ? { antialias: opts.antialias } : {}
 	});
+	cleanups.push(engine.settings.bindFrameCap((fps) => {
+		engine.maxFps = fps;
+	}));
+	cleanups.push(engine.settings.bindRenderScale((scale) => {
+		renderer.setRenderScale?.(scale);
+	}));
+	/**
+	* Feed the running game a drive script and count the frames it drew.
+	*
+	* Same as the 3D boot: the count travels with the report because a browser
+	* stops handing rAF to a hidden tab, and inputs landing on a game that never
+	* advances produce an UNCHANGED capture that says nothing about why.
+	*/
+	const applyDrive = async (steps) => {
+		let frames = 0;
+		let watching = true;
+		const tick = () => {
+			if (!watching) return;
+			frames += 1;
+			requestAnimationFrame(tick);
+		};
+		if (typeof requestAnimationFrame === "function") requestAnimationFrame(tick);
+		for (const step of steps) switch (step.kind) {
+			case "press":
+				engine.input.pressAction(step.action);
+				break;
+			case "release":
+				engine.input.releaseAction(step.action);
+				break;
+			case "vector":
+				engine.input.setActionVector(step.action, step.x, step.y);
+				break;
+			case "key":
+				engine.input.handleKey(step.code, step.down);
+				break;
+			case "pointer":
+				engine.input.handlePointerMove(step.dx, step.dy);
+				break;
+			case "step":
+				await new Promise((r) => setTimeout(r, step.ms));
+				break;
+		}
+		watching = false;
+		return frames;
+	};
+	cleanups.push(...wireDevChannel({
+		engine,
+		applyDrive,
+		captureFramePixels: () => {
+			const capture = renderer.captureFrame;
+			if (!capture) return Promise.reject(new IncantoError("TREE_VIOLATION", "this renderer cannot capture frames"));
+			return capture.call(renderer);
+		},
+		rendererStats: () => renderer.stats?.(),
+		assetErrors: () => {
+			return [...renderer.assets?.errors() ?? [], ...audioErrors(engine.scene?.tree.root)];
+		}
+	}));
 	const wantDebug = opts.debug ?? false;
 	const wantEditor = opts.editor ?? wantDebug;
 	const editorSwitch = wantEditor === true ? {} : wantEditor ? wantEditor : null;
@@ -727,6 +860,12 @@ async function createGame2D(opts) {
 		pick(x, y) {
 			return engine.picker?.(x, y) ?? null;
 		},
+		async frame(frameOpts) {
+			const capture = renderer.captureFrame;
+			if (!capture) throw new IncantoError("TREE_VIOLATION", "this renderer cannot capture frames");
+			const shot = await capture.call(renderer);
+			return frameStats(shot.pixels, shot.width, shot.height, frameOpts);
+		},
 		assetErrors() {
 			return [...renderer.assets?.errors() ?? [], ...audioErrors(engine.scene?.tree.root)];
 		},

package/dist/debug.d.ts

@@ -1,4 +1,4 @@
-import { Pt as LogLevel, T as RendererStats, b as Engine } from "./behavior-CyQoSu4n.js";
+import { Pt as LogLevel, T as RendererStats, b as Engine } from "./behavior-l08AEbq9.js";
 
 //#region src/debug/panel.d.ts
 /** Minimal document surface the overlay needs (injectable for tests). */

package/dist/{duplicate-MNLMAcbz.js → duplicate-BPLZDZpd.js}

@@ -1,4 +1,4 @@
-import { i as serializeNode, t as buildNodeJson } from "./loader-BTkHYrQn.js";
+import { i as serializeNode, t as buildNodeJson } from "./loader-BcrRSjxB.js";
 //#region src/core/scene/duplicate.ts
 function stripUids(json) {
 	const { uid: _uid, ...rest } = json;