incanto 0.43.0 → 0.45.0

package/bin/incanto-frame.mjs

@@ -25,20 +25,46 @@ const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 const { listeningPorts, parseProcNetTcp } = await import(
   pathToFileURL(join(PKG, 'dist', 'vite.js')).href
 );
-const { frameText } = await import(pathToFileURL(join(PKG, 'dist', '3d.js')).href);
+const { frameText, diffText } = await import(pathToFileURL(join(PKG, 'dist', '3d.js')).href);
 
 const args = process.argv.slice(2);
 const asJson = args.includes('--json');
-const gridArg = args[args.indexOf('--grid') + 1];
+/** `--flag` with an optional value: `--remember` and `--remember shader` both. */
+const flag = (name) => {
+  const i = args.indexOf(name);
+  if (i < 0) return null;
+  const next = args[i + 1];
+  return next && !next.startsWith('-') ? next : '';
+};
+const gridArg = flag('--grid');
+const remember = flag('--remember');
+const diff = flag('--diff');
+const threshold = flag('--threshold');
 if (args.includes('--help') || args.includes('-h')) {
   console.error(`Usage: incanto-frame [options]
 
-  --json         the full report as JSON instead of prose
-  --grid WxH     cells across and down (default 16x9)
-  --port N       skip discovery and use this port
+  --json          the full report as JSON instead of prose
+  --grid WxH      cells across and down (default 16x9)
+  --port N        skip discovery and use this port
+
+  --remember [L]  keep this frame as the baseline named L (default "last")
+  --diff [L]      say what changed since baseline L
+  --threshold N   a cell has changed when it moves this far, 0..255 (default 3)
 
 Run your game's dev server and open the preview page first: the pixels live in
-the browser, not in the dev server.`);
+the browser, not in the dev server.
+
+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
+scene. Two frames of the SAME view can:
+
+  incanto-frame --remember      # before your change
+  ...edit the shader...
+  incanto-frame --diff          # "a vertical band at x 640..660"
+
+Baselines live in the dev server's memory and die with it — no file is written.
+Pause the game first (debug ☰ → Time → Pause) or you are measuring time
+passing, not your change.`);
   process.exit(0);
 }
 
@@ -110,7 +136,13 @@ if (!found) {
   process.exit(1);
 }
 
-const res = await fetch(`http://${found.host}:${found.port}/__incanto/frame`, {
+const params = new URLSearchParams();
+if (gridArg !== null) params.set('grid', gridArg);
+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),
 });
 const body = await res.json().catch(() => null);
@@ -134,11 +166,23 @@ if (report.error) {
 }
 
 if (asJson) {
-  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  process.stdout.write(`${JSON.stringify(body, null, 2)}\n`);
 } else {
-  process.stdout.write(`${frameText(report)}\n`);
+  const lines = [frameText(report)];
+  if (body.diffError === 'no-baseline') {
+    lines.push(
+      `no baseline named "${diff || 'last'}" — run \`incanto-frame --remember${diff ? ` ${diff}` : ''}\` first,\n` +
+        '  then again with --diff after your change. The baseline lives in the dev\n' +
+        '  server, so restarting it forgets.',
+    );
+  } else if (body.diffError) {
+    lines.push(`cannot compare: ${body.diffError}`);
+  }
+  if (body.diff) lines.push(diffText(body.diff));
+  if (body.remembered) lines.push(`remembered as "${body.remembered}"`);
+  process.stdout.write(`${lines.join('\n')}\n`);
 }
-process.exit(report.black ? 1 : 0);
+// A missing baseline is a usage error, not a picture: fail so a script notices.
+process.exit(report.black || body.diffError ? 1 : 0);
 
 void parseProcNetTcp; // re-exported for tests; referenced so bundlers keep it
-void gridArg;

package/dist/3d.d.ts

@@ -3,6 +3,7 @@ import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-D
 import { i as SceneJson, s as JsonObject } from "./schema-CFeioQRE.js";
 import { t as LoadSceneOptions } from "./loader-CeyU_bm1.js";
 import { t as ParticleSim } from "./particle-sim-BzJ1yxoE.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-Ct8XgsmV.js";
 import { n as PathGrid, s as SpatialPose } from "./pathfinding-C49JSNNq.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";
@@ -190,45 +191,6 @@ declare function keyboardIntensity(moving: boolean, sprinting: boolean): number;
 /** intensity → movement state (the animation driver). */
 declare function movementState(grounded: boolean, intensity: number): "idle" | "walk" | "run" | "fastRun" | "airborne";
 //#endregion
-//#region src/3d/frame-report.d.ts
-/**
-* What the frame looks like, as something worth saying.
-*
-* The pixels are not the deliverable. A 1280x720 frame is 2.8 million numbers:
-* unreadable by a person, unaffordable for a model (roughly a thousand tokens
-* as an image, roughly a million as text). The deliverable is the JUDGEMENT —
-* black screen, one flat colour, washed out — and the numbers behind it, small
-* enough to print and compare.
-*
-* Same principle as `framing`'s "lit by: NOTHING": a report is a sentence
-* before it is a number, because a number needs a reader who already knows what
-* to compare it against.
-*
-* Pure arithmetic over an RGBA buffer — no three, no DOM, no GPU. Whoever has
-* the pixels calls this; in practice that is the browser holding the canvas.
-*/
-/** Per-cell mean colour, `[r, g, b]` 0..255. */
-type GridCell = [number, number, number];
-interface FrameStats {
-  width: number;
-  height: number;
-  /** Every pixel below the black threshold — the render produced nothing. */
-  black: boolean;
-  /** One colour everywhere: a clear-colour fill, or a camera inside geometry. */
-  uniform: boolean;
-  /** 0..1 mean relative luminance. */
-  meanLuma: number;
-  /** Coarse mean colour per cell, rows top to bottom. */
-  grid: GridCell[][];
-}
-interface FrameStatsOptions {
-  /** Cells across and down. Default 16x9 — 144 cells, printable. */
-  grid?: [number, number];
-}
-declare function frameStats(pixels: Uint8Array | Uint8ClampedArray, width: number, height: number, opts?: FrameStatsOptions): FrameStats;
-/** The report a person or an agent reads. Verdict first, numbers after. */
-declare function frameText(stats: FrameStats): string;
-//#endregion
 //#region src/3d/nodes/node-3d.d.ts
 /**
 * Per-frame hand-off from `Renderer3D` to nodes that need the LIVE WebGL
@@ -1834,6 +1796,8 @@ declare class ModelInstance3D extends Node3D {
   private entry;
   private mountedRef;
   private fittedHeight;
+  /** A skinned model waiting for a posed skeleton it can be measured against. */
+  private fitPending;
   private fitGroup;
   /**
   * @internal The mounted model, or null while the asset is still loading.
@@ -1893,6 +1857,16 @@ declare class ModelInstance3D extends Node3D {
   availableAnimations(): string[];
   /** Called by the 3D sync pass with the renderer's asset store. */
   _syncModel(assets: AssetStore3D): void;
+  /**
+  * Scale the model so it stands `targetHeight` tall, measured ONCE.
+  *
+  * Once, deliberately: the measurement reflects the pose the model happens to
+  * be in, and re-running it every frame would let a walk cycle resize the
+  * character mid-stride. In practice the pose barely matters — across a whole
+  * idle clip this rig's height moves 0.5% — but "barely" is not "never", and
+  * a size that breathes is worse than one that is half a percent off.
+  */
+  private applyFit;
   /** Apply per-instance material mods — `tint` (multiplied into colour) and the
   *  `metalness`/`roughness` overrides — by cloning the captured originals
   *  (never mutates the shared source), disposing prior clones on change. */
@@ -3647,4 +3621,4 @@ declare function createNavDebugNode(nav: TerrainNav, opts?: {
   name?: string;
 }): InstancedMesh3D;
 //#endregion
-export { Area3D, AssetStore3D, type BedSampler, Billboard3D, type BillboardGroupMode, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, type CreateGame3DOptions, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, type DownhillTraceOptions, Environment3D, type Environment3DConfig, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, type FlowerVariety, Flowers3D, type FogEnvironment, Foliage3D, type FoliageKind, type FoliageStyle, type FrameStats, type FrameStatsOptions, type Game3D, type GridCell, type HeightSampler, type Heightmap, type HeightmapOptions, InstancedMesh3D, Joint3D, type JointType3D, LoftMesh3D, type LoftSection, MeshInstance3D, type MeshKind, type MeshMaterialProps, type ModelEntry, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, type Physics3DOptions, PhysicsBody3D, QUARTER_PITCH, type RenderContext3D, type RenderHook3D, Renderer3D, type Renderer3DOptions, type RigView, RigidBody3D, type Ripple, River3D, type RiverCarveOptions, type RiverCoverageGap, type RiverHit, type RiverRing, type RiverRingOptions, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainNav, type TerrainNavOptions, type TerrainTheme, TextureCache3D, type TextureSpec, Trail3D, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, acquireOwnTexture, acquireTexture, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, enablePhysics3D, findRiverCoverageGaps, frameStats, frameText, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath };
+export { Area3D, AssetStore3D, type BedSampler, Billboard3D, type BillboardGroupMode, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, type CreateGame3DOptions, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, type DownhillTraceOptions, Environment3D, type Environment3DConfig, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, type FlowerVariety, Flowers3D, type FogEnvironment, Foliage3D, type FoliageKind, type FoliageStyle, type FrameDiff, type FrameSignature, type FrameStats, type FrameStatsOptions, type Game3D, type GridCell, type HeightSampler, type Heightmap, type HeightmapOptions, InstancedMesh3D, Joint3D, type JointType3D, LoftMesh3D, type LoftSection, MeshInstance3D, type MeshKind, type MeshMaterialProps, type ModelEntry, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, type Physics3DOptions, PhysicsBody3D, QUARTER_PITCH, type RenderContext3D, type RenderHook3D, Renderer3D, type Renderer3DOptions, type RigView, RigidBody3D, type Ripple, River3D, type RiverCarveOptions, type RiverCoverageGap, type RiverHit, type RiverRing, type RiverRingOptions, SIGNATURE_GRID, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainNav, type TerrainNavOptions, type TerrainTheme, TextureCache3D, type TextureSpec, Trail3D, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, acquireOwnTexture, acquireTexture, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, diffSignatures, diffText, enablePhysics3D, findRiverCoverageGaps, frameSignature, frameStats, frameText, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath };

package/dist/3d.js

@@ -1,8 +1,9 @@
 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-Ds5kXLoF.js";
-import { a as Environment3D, c as setEnvironment3D, d as sunDirectionFromElevationAzimuth, f as sunDirectionFromSky, i as syncTree, l as horizonColorFromSky, o as frameStats, p as AssetStore3D, r as Renderer3D, s as frameText, t as createGame3D, u as parseEnvironment3D } from "./create-game-B3vBWgVD.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-2GgTlPt1.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-CCFUOWfb.js";
+import { a as frameStats, i as frameSignature, n as diffSignatures, o as frameText, r as diffText, t as SIGNATURE_GRID } from "./frame-report-Lr3VO24R.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-CLPFv99o.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-nLI_8bUR.js";
 //#region src/3d/terrain-nav.ts
 function buildTerrainNav(terrain, opts) {
 	const cellSize = opts?.cellSize ?? 2;
@@ -114,4 +115,4 @@ function createNavDebugNode(nav, opts) {
 	return node;
 }
 //#endregion
-export { Area3D, AssetStore3D, Billboard3D, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, Flowers3D, Foliage3D, InstancedMesh3D, Joint3D, LoftMesh3D, MeshInstance3D, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, PhysicsBody3D, QUARTER_PITCH, Renderer3D, RigidBody3D, River3D, StaticBody3D, TERRAIN_THEMES, Terrain3D, TextureCache3D, Trail3D, Tree3D, VOXEL_PALETTE, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, acquireOwnTexture, acquireTexture, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, enablePhysics3D, findRiverCoverageGaps, frameStats, frameText, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath };
+export { Area3D, AssetStore3D, Billboard3D, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, Flowers3D, Foliage3D, InstancedMesh3D, Joint3D, LoftMesh3D, MeshInstance3D, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, PhysicsBody3D, QUARTER_PITCH, Renderer3D, RigidBody3D, River3D, SIGNATURE_GRID, StaticBody3D, TERRAIN_THEMES, Terrain3D, TextureCache3D, Trail3D, Tree3D, VOXEL_PALETTE, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, acquireOwnTexture, acquireTexture, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, diffSignatures, diffText, enablePhysics3D, findRiverCoverageGaps, frameSignature, frameStats, frameText, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath };

package/dist/{create-game-B3vBWgVD.js → create-game-CCFUOWfb.js}

@@ -6,8 +6,9 @@ import { i as resolveRendering, n as attachTouchControls } from "./touch-BoNg_Mn
 import { a as openBundledEditor, i as devServerLibrary, n as pauseWhenHidden, o as poseFromRenderer, r as crossFade, t as teardown } from "./teardown-yePMOE1K.js";
 import { B as createCausticsQuad, F as PhysicsBody3D, R as Node3D, n as registerGameplayBehaviors } from "./gameplay-BQOeAid6.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-Ds5kXLoF.js";
-import { n as enablePhysics3D } from "./physics-3d-CLPFv99o.js";
+import { E as Camera3D, U as TextureCache3D, g as ModelInstance3D, n as registerNodes3D, t as resolveEnvironmentHdri, v as DirectionalLight3D } from "./environment-presets-2GgTlPt1.js";
+import { a as frameStats, i as frameSignature } from "./frame-report-Lr3VO24R.js";
+import { n as enablePhysics3D } from "./physics-3d-nLI_8bUR.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";
@@ -486,76 +487,6 @@ function setEnvironment3D(engine, patch) {
 	scene.environment = merged;
 }
 //#endregion
-//#region src/3d/frame-report.ts
-/** Rec. 709 relative luminance of an 8-bit triple, 0..1. */
-function luma(r, g, b) {
-	return (.2126 * r + .7152 * g + .0722 * b) / 255;
-}
-/**
-* A pixel this dark is indistinguishable from "nothing was drawn". Not zero:
-* a real render of a night scene still lands a few levels above black, and
-* calling that a failure would make the check useless where it matters most.
-*/
-const BLACK_LEVEL = .012;
-/** Cell-to-cell luminance range below this: the frame is one flat colour. */
-const UNIFORM_EPSILON = .004;
-function frameStats(pixels, width, height, opts = {}) {
-	const [cols, rows] = opts.grid ?? [16, 9];
-	const grid = [];
-	let total = 0;
-	let maxLuma = 0;
-	let minLuma = 1;
-	for (let row = 0; row < rows; row++) {
-		const line = [];
-		for (let col = 0; col < cols; col++) {
-			const x0 = Math.floor(col * width / cols);
-			const x1 = Math.max(x0 + 1, Math.floor((col + 1) * width / cols));
-			const y0 = Math.floor(row * height / rows);
-			const y1 = Math.max(y0 + 1, Math.floor((row + 1) * height / rows));
-			let r = 0;
-			let g = 0;
-			let b = 0;
-			let n = 0;
-			for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) {
-				const i = (y * width + x) * 4;
-				r += pixels[i] ?? 0;
-				g += pixels[i + 1] ?? 0;
-				b += pixels[i + 2] ?? 0;
-				n += 1;
-			}
-			const cell = [
-				Math.round(r / n),
-				Math.round(g / n),
-				Math.round(b / n)
-			];
-			const cellLuma = luma(cell[0], cell[1], cell[2]);
-			total += cellLuma;
-			maxLuma = Math.max(maxLuma, cellLuma);
-			minLuma = Math.min(minLuma, cellLuma);
-			line.push(cell);
-		}
-		grid.push(line);
-	}
-	const cells = cols * rows;
-	const meanLuma = total / cells;
-	return {
-		width,
-		height,
-		black: maxLuma <= BLACK_LEVEL,
-		uniform: maxLuma - minLuma < UNIFORM_EPSILON,
-		meanLuma: Math.round(meanLuma * 1e3) / 1e3,
-		grid
-	};
-}
-/** The report a person or an agent reads. Verdict first, numbers after. */
-function frameText(stats) {
-	const lines = [];
-	if (stats.black) lines.push("BLACK SCREEN — nothing was drawn (no light, no camera, or nothing in view)");
-	else if (stats.uniform) lines.push("one flat colour — the camera may be inside geometry, or only the sky is drawn");
-	lines.push(`frame ${stats.width}×${stats.height} · luminance ${stats.meanLuma.toFixed(2)}`);
-	return lines.join("\n");
-}
-//#endregion
 //#region src/3d/adaptive-resolution.ts
 const DEFAULTS = {
 	slowMs: 20,
@@ -2475,6 +2406,7 @@ async function createGame3D(opts) {
 			const overlay = attachDebugOverlay(engine, {
 				container: host,
 				statsSource: () => renderer.stats?.() ?? {},
+				...renderer.captureFrame ? { frameSource: () => captureFramePixels() } : {},
 				...editorSwitch ? { actions: [editorAction] } : {},
 				...opts._debugDoc ? { doc: opts._debugDoc } : {}
 			});
@@ -2504,19 +2436,22 @@ async function createGame3D(opts) {
 	cleanups.push(engine.settings.bindRenderScale((scale) => {
 		renderer.setRenderScale?.(scale);
 	}));
-	const captureReport = async (frameOpts) => {
+	const captureFramePixels = () => {
 		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);
+		return capture.call(renderer);
 	};
 	const hot = import.meta.hot;
 	if (hot) {
 		const onFrameRequest = (data) => {
-			const id = data?.id;
-			captureReport().then((frameReport) => hot.send("incanto:frame-report", {
+			const request = data;
+			const id = request?.id;
+			captureFramePixels().then((shot) => hot.send("incanto:frame-report", {
 				id,
-				report: frameReport
+				report: {
+					...frameStats(shot.pixels, shot.width, shot.height, { grid: request?.grid }),
+					signature: frameSignature(shot.pixels, shot.width, shot.height)
+				}
 			})).catch((error) => hot.send("incanto:frame-report", {
 				id,
 				report: { error: error instanceof Error ? error.message : String(error) }
@@ -2618,4 +2553,4 @@ function wireAudioUnlock(engine, root, canvas) {
 	return detachAll;
 }
 //#endregion
-export { Environment3D as a, setEnvironment3D as c, sunDirectionFromElevationAzimuth as d, sunDirectionFromSky as f, syncTree as i, horizonColorFromSky as l, create_game_exports as n, frameStats as o, AssetStore3D as p, Renderer3D as r, frameText as s, createGame3D as t, parseEnvironment3D as u };
+export { Environment3D as a, parseEnvironment3D as c, AssetStore3D as d, syncTree as i, sunDirectionFromElevationAzimuth as l, create_game_exports as n, setEnvironment3D as o, Renderer3D as r, horizonColorFromSky as s, createGame3D as t, sunDirectionFromSky as u };

package/dist/debug.d.ts

@@ -3,16 +3,21 @@ import { At as LogLevel, T as RendererStats, b as Engine } from "./behavior-62q0
 //#region src/debug/panel.d.ts
 /** Minimal document surface the overlay needs (injectable for tests). */
 interface DocumentLike {
+  /** Optional: present on a real document, absent in the test double. */
+  addEventListener?(type: string, cb: (event: unknown) => void): void;
+  removeEventListener?(type: string, cb: (event: unknown) => void): void;
   createElement(tag: string): HTMLElement;
 }
 //#endregion
 //#region src/debug/index.d.ts
 type DebugPanelId = "explorer" | "inspector" | "logs" | "stats" | "time";
+/** Menu entries that DO something once rather than opening a panel. */
+type DebugCommandId = "copyScene" | "captureRegion";
 /** Menu entries that are switches rather than panels. */
 type DebugSwitchId = "colliders";
 /** `all` is every collider in the world; `selected` follows the Explorer. */
 type ColliderMode = "off" | "all" | "selected";
-type DebugMenuId = DebugPanelId | DebugSwitchId;
+type DebugMenuId = DebugPanelId | DebugSwitchId | DebugCommandId;
 /** An extra ☰ menu entry the host app supplies (e.g. "edit this scene"). */
 interface DebugAction {
   /** Menu label. Keep it a verb — the menu is a list of things you can do. */
@@ -37,6 +42,19 @@ interface DebugOverlayOptions {
   * renderers): the chip shows engine stats only.
   */
   statsSource?: () => Partial<RendererStats>;
+  /**
+  * The renderer's pixels, for the region capture. Wired by createGame like
+  * `statsSource`, because the overlay holds the engine and not the renderer.
+  *
+  * It must be `captureFrame()` and not `canvas.toDataURL()`: the drawing
+  * buffer is gone by the time anything outside a render can read it, and the
+  * image comes back black. That trap has been hit here before.
+  */
+  frameSource?: () => Promise<{
+    pixels: Uint8Array;
+    width: number;
+    height: number;
+  }>;
   /** @internal Test seam — replaces `document`. */
   doc?: DocumentLike;
 }
@@ -48,10 +66,14 @@ declare class DebugOverlay {
   private readonly doc;
   private readonly statsSource?;
   private readonly actions;
+  private readonly frameSource?;
   private readonly panels;
   private readonly cleanups;
   private readonly menuButton;
   private dropdown;
+  private dismissDropdown;
+  /** Where the ☰ button sits, in container CSS px. Drag moves it; see bindMenuDrag. */
+  private menuPos;
   private selected;
   /** Explorer subtrees the user collapsed (nodes keep identity across frames). */
   private readonly collapsedFlags;
@@ -75,7 +97,7 @@ declare class DebugOverlay {
   private timeEls;
   /** Pointer inside the inspector — it stops refreshing under your hand. */
   private hovering;
-  constructor(engine: Engine, container: HTMLElement, doc: DocumentLike, statsSource?: (() => Partial<RendererStats>) | undefined, actions?: DebugAction[]);
+  constructor(engine: Engine, container: HTMLElement, doc: DocumentLike, statsSource?: (() => Partial<RendererStats>) | undefined, actions?: DebugAction[], frameSource?: DebugOverlayOptions["frameSource"] | undefined);
   isOpen(id: DebugMenuId): boolean;
   /** How much of the physics world the wireframes show. */
   colliderMode: ColliderMode;
@@ -102,6 +124,18 @@ declare class DebugOverlay {
   dispose(): void;
   /** `✓ Colliders · selected` — check for on, suffix for the collider mode. */
   private menuLabel;
+  /**
+  * The ☰ button is draggable, because top-left is exactly where a game puts
+  * its own menu and a debug chip pinned on top of it is a debug chip you
+  * cannot use.
+  *
+  * Drag and click share one pointer, so they are told apart by distance: under
+  * the threshold the press was a click and the menu opens, over it the press
+  * was a grab and the menu must NOT open under the finger that just let go.
+  */
+  private bindMenuDrag;
+  private moveMenuButton;
+  private closeDropdown;
   private toggleDropdown;
   private openStatsChip;
   private renderStats;
@@ -117,6 +151,28 @@ declare class DebugOverlay {
   private trackEditing;
   private pushLog;
   /**
+  * The scene, on the clipboard, ready to paste into a conversation.
+  *
+  * This is half of "here is what I am looking at" — the half a screenshot
+  * cannot carry. The other half is the region capture below.
+  */
+  copyScene(): Promise<boolean>;
+  /**
+  * Drag a rectangle over the game; the selection copies as an image.
+  *
+  * The pixels come from `frameSource` — the renderer's own end-of-frame read —
+  * and never from `canvas.toDataURL()`, which returns black once the frame has
+  * composited unless `preserveDrawingBuffer` is on (it is not, because it costs
+  * bandwidth on every frame).
+  */
+  captureRegion(): void;
+  private capture;
+  private captureScale;
+  /** Crop the last frame to `drag` and put the image on the clipboard. */
+  private copyRegion;
+  /** A line that says what happened and gets out of the way. */
+  private toast;
+  /**
   * Set game time, defensively. `timeScale` multiplies every dt in the engine,
   * so a NaN from a text field would poison physics, timers and animation in
   * one frame, and a negative would run the simulation backwards through code
@@ -144,4 +200,4 @@ declare class DebugOverlay {
   private renderLogs;
 }
 //#endregion
-export { ColliderMode, DebugAction, DebugMenuId, DebugOverlay, DebugOverlayOptions, DebugPanelId, DebugSwitchId, attachDebugOverlay };
+export { ColliderMode, DebugAction, DebugCommandId, DebugMenuId, DebugOverlay, DebugOverlayOptions, DebugPanelId, DebugSwitchId, attachDebugOverlay };