incanto 0.40.1 → 0.42.0

package/bin/incanto-frame.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+/**
+ * incanto-frame — what is actually on screen, as numbers.
+ *
+ *   bunx incanto-frame
+ *
+ * The rung above `incanto-check`. That one says the scene loads; `framing` says
+ * what the camera SHOULD see; this says what the GPU actually drew — the only
+ * one that can catch a black screen, a material that failed, or a shader
+ * drawing where it should not.
+ *
+ * It writes no files. An image is only worth producing when a human is going to
+ * look at one, and a report is what an agent can act on.
+ *
+ * Finding the dev server is this program's job, never the caller's: it reads
+ * the ports that are actually listening and asks each one whether it is an
+ * incanto dev server. You run one command; it works out the rest.
+ */
+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, parseProcNetTcp } = await import(
+  pathToFileURL(join(PKG, 'dist', 'vite.js')).href
+);
+const { frameText } = 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];
+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
+
+Run your game's dev server and open the preview page first: the pixels live in
+the browser, not in the dev server.`);
+  process.exit(0);
+}
+
+const read = (path) => {
+  try {
+    return readFileSync(path, 'utf-8');
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Ports that are listening, on a machine with no `/proc` (macOS, BSD).
+ * The container this is built for is Linux, but a developer's laptop is not,
+ * and a tool that only works in CI teaches nobody anything.
+ */
+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;
+// BOTH hosts, deliberately: vite binds to ::1 on some machines and 127.0.0.1 on
+// others, and a probe of the wrong one reports "no dev server" while the page
+// is plainly on screen.
+const HOSTS = ['localhost', '127.0.0.1'];
+outer: for (const port of ports) {
+  for (const host of HOSTS) {
+    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, ...body };
+        break outer;
+      }
+    } catch {
+      // not listening, not ours, or not answering — either way, next
+    }
+  }
+}
+
+if (!found) {
+  console.error(
+    'no incanto dev server found.\n' +
+      '  Start your game (the dev server) and try again — this reads the frame\n' +
+      '  from the running preview, so there has to be one.',
+  );
+  process.exit(1);
+}
+
+const res = await fetch(`http://${found.host}:${found.port}/__incanto/frame`, {
+  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 is connected.\n` +
+      '  Open the preview in a browser — the pixels are there, not in the server.',
+  );
+  process.exit(1);
+}
+if (!res.ok || !body?.report) {
+  console.error(`could not capture a frame: ${body?.error ?? res.status}`);
+  process.exit(1);
+}
+
+const report = body.report;
+if (report.error) {
+  console.error(`the page could not capture a frame: ${report.error}`);
+  process.exit(1);
+}
+
+if (asJson) {
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+} else {
+  process.stdout.write(`${frameText(report)}\n`);
+}
+process.exit(report.black ? 1 : 0);
+
+void parseProcNetTcp; // re-exported for tests; referenced so bundlers keep it
+void gridArg;

package/dist/2d.d.ts

@@ -1,7 +1,7 @@
-import { Et 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-TA8nySqb.js";
+import { Et 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-62q0HWBO.js";
 import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-DVwIGZdK.js";
 import { i as SceneJson, s as JsonObject } from "./schema-CFeioQRE.js";
-import { t as LoadSceneOptions } from "./loader-CvSDKC3v.js";
+import { t as LoadSceneOptions } from "./loader-CeyU_bm1.js";
 import { t as ParticleSim } from "./particle-sim-BzJ1yxoE.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
 import * as RapierNs from "@dimforge/rapier2d-compat";

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-B7c5icho.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-CgMO5JBY.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-CxIqR1cW.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-9KPppR0L.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-R2JTnIMw.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-BmgXBNDB.js";
 //#region src/2d/library-sprite.ts
 /**
 * Turn a library sprite-animation JSON into a scene-ready spritesheet asset

package/dist/3d.d.ts

@@ -1,9 +1,9 @@
-import { D as QualityCaps, Et 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-TA8nySqb.js";
+import { D as QualityCaps, Et 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-62q0HWBO.js";
 import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-DVwIGZdK.js";
 import { i as SceneJson, s as JsonObject } from "./schema-CFeioQRE.js";
-import { t as LoadSceneOptions } from "./loader-CvSDKC3v.js";
+import { t as LoadSceneOptions } from "./loader-CeyU_bm1.js";
 import { t as ParticleSim } from "./particle-sim-BzJ1yxoE.js";
-import { n as PathGrid, s as SpatialPose } from "./pathfinding-_UlKUoox.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";
 import { Sky } from "three/examples/jsm/objects/Sky.js";
@@ -190,6 +190,45 @@ 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
@@ -643,6 +682,20 @@ interface Game3D {
   /** Engine + renderer perf counters in one read (fps/nodes/triangles/…). */
   stats(): GameStats;
   /**
+  * What is actually on screen, as numbers.
+  *
+  * The rung above `framing()`: that one PREDICTS what the camera should see
+  * from the scene graph, this one measures what the GPU drew. The difference
+  * between the two is the whole class of bug a scene graph cannot express — a
+  * black screen, a material that failed, a shader drawing where it should not.
+  *
+  * Returns the report, never a file. An image is only worth writing when a
+  * human is going to look at it.
+  */
+  frame(opts?: {
+    grid?: [number, number];
+  }): Promise<FrameStats>;
+  /**
   * Assets that failed to load, with the reason.
   *
   * "The model just never appeared" used to be unanswerable from outside: the
@@ -3351,6 +3404,25 @@ declare class Renderer3D {
   warmUp(onProgress?: (fraction: number) => void): Promise<void>;
   private render;
   /**
+  * A frame's pixels, read on the NEXT frame that draws.
+  *
+  * `preserveDrawingBuffer` is false by default — with good reason, it costs
+  * bandwidth on every frame — so `canvas.toDataURL()` comes back blank, which
+  * is the trap this repo has fallen into before. Reading with `gl.readPixels`
+  * at the END of a render, in the same frame, needs no such flag and no
+  * per-frame cost: nothing happens at all until somebody asks.
+  *
+  * That is why this lives in the engine rather than in a generic screenshot
+  * tool. An outside tool cannot get inside the frame.
+  */
+  captureFrame(): Promise<{
+    pixels: Uint8Array;
+    width: number;
+    height: number;
+  }>;
+  private pendingCaptures;
+  private drainFrameCapture;
+  /**
   * Bloom post pass (only when `environment.bloom` is declared). LDR and safe:
   *   1. scene → full-res offscreen (tone-mapped exactly like direct output)
   *   2. bright-pass at HALF res (keep pixels above threshold)
@@ -3575,4 +3647,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 Game3D, 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, 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 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 };

package/dist/3d.js

@@ -1,8 +1,8 @@
-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-By8mslMc.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-CIZXGKnS.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-p-O66Y_U.js";
+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-DRi9524r.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-Vl5xBsXp.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-DItIRyXH.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-CgIHivyL.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-C2G604O1.js";
 //#region src/3d/terrain-nav.ts
 function buildTerrainNav(terrain, opts) {
 	const cellSize = opts?.cellSize ?? 2;
@@ -114,4 +114,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, 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, 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 };

package/dist/{behavior-TA8nySqb.d.ts → behavior-62q0HWBO.d.ts}

@@ -390,7 +390,9 @@ interface PlayMusicOptions {
 * frame to advance fades (the engine wires this to `updated`).
 *
 * ```ts
-* engine.music.play('incanto/assets/audio/theme.mp3');     // loop, full
+* // NOTE: the bundle ships SFX only — no music track. A background track is
+* // your game's own file under public/, or a URL.
+* engine.music.play('/audio/theme.mp3');                     // loop, full
 * engine.music.crossfadeTo('boss.mp3', 3);                  // 3s equal-power swap
 * engine.music.stop(2);                                     // fade out over 2s
 * engine.music.setVolume(0.5);                              // per-manager volume

package/dist/{create-game-B7c5icho.js → create-game-9KPppR0L.js}

@@ -1,13 +1,13 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
 import { n as loadScene, o as computeViewport, s as resolveViewport, v as diagnose, w as registerBehavior } from "./loader-r49nDwB4.js";
-import { h as Engine, m as AudioPlayer } from "./register-DMFJI-c_.js";
+import { h as Engine, m as AudioPlayer } from "./register-BSXV8T9F.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-BoNg_MnF.js";
 import { i as openBundledEditor, n as crossFade, r as devServerLibrary, t as teardown } from "./teardown-CCtAMDLB.js";
-import { n as registerGameplayBehaviors } from "./gameplay-By8mslMc.js";
-import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-CgMO5JBY.js";
+import { n as registerGameplayBehaviors } from "./gameplay-DRi9524r.js";
+import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-R2JTnIMw.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { n as enablePhysics2D } from "./physics-2d-CxIqR1cW.js";
+import { n as enablePhysics2D } from "./physics-2d-BmgXBNDB.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
 /**

package/dist/{create-game-p-O66Y_U.js → create-game-DItIRyXH.js}

@@ -1,13 +1,13 @@
 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-DMFJI-c_.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 { i as resolveRendering, n as attachTouchControls } from "./touch-BoNg_MnF.js";
 import { a as poseFromRenderer, i as openBundledEditor, n as crossFade, r as devServerLibrary, t as teardown } from "./teardown-CCtAMDLB.js";
-import { B as createCausticsQuad, F as PhysicsBody3D, R as Node3D, n as registerGameplayBehaviors } from "./gameplay-By8mslMc.js";
+import { B as createCausticsQuad, F as PhysicsBody3D, R as Node3D, n as registerGameplayBehaviors } from "./gameplay-DRi9524r.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-CIZXGKnS.js";
-import { n as enablePhysics3D } from "./physics-3d-CgIHivyL.js";
+import { E as Camera3D, U as TextureCache3D, g as ModelInstance3D, n as registerNodes3D, t as resolveEnvironmentHdri, v as DirectionalLight3D } from "./environment-presets-Vl5xBsXp.js";
+import { n as enablePhysics3D } from "./physics-3d-C2G604O1.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,6 +486,76 @@ 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,
@@ -1869,6 +1939,50 @@ var Renderer3D = class {
 		else if (clouds && !underwater) this.renderWithClouds(activeCamera, clouds, threeLight);
 		else if ((bloom || post) && !underwater) this.renderWithBloom(activeCamera, bloom, post);
 		else this.webgl.render(this.threeScene, activeCamera);
+		this.drainFrameCapture();
+	}
+	/**
+	* A frame's pixels, read on the NEXT frame that draws.
+	*
+	* `preserveDrawingBuffer` is false by default — with good reason, it costs
+	* bandwidth on every frame — so `canvas.toDataURL()` comes back blank, which
+	* is the trap this repo has fallen into before. Reading with `gl.readPixels`
+	* at the END of a render, in the same frame, needs no such flag and no
+	* per-frame cost: nothing happens at all until somebody asks.
+	*
+	* That is why this lives in the engine rather than in a generic screenshot
+	* tool. An outside tool cannot get inside the frame.
+	*/
+	captureFrame() {
+		return new Promise((resolve, reject) => {
+			this.pendingCaptures.push({
+				resolve,
+				reject
+			});
+		});
+	}
+	pendingCaptures = [];
+	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);
+			flipRows(pixels, width, height);
+			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);
+		}
 	}
 	/**
 	* Bloom post pass (only when `environment.bloom` is declared). LDR and safe:
@@ -2235,6 +2349,18 @@ const camPosScratch = new Vector3();
 /** Reused click-pick scratches (no per-pick allocation). */
 const pickRaycaster = new Raycaster();
 const pickNdc = new Vector2();
+/** Turn a bottom-left GL buffer into top-left screen order, in place. */
+function flipRows(pixels, width, height) {
+	const stride = width * 4;
+	const row = new Uint8Array(stride);
+	for (let y = 0; y < Math.floor(height / 2); y++) {
+		const top = y * stride;
+		const bottom = (height - 1 - y) * stride;
+		row.set(pixels.subarray(top, top + stride));
+		pixels.copyWithin(top, bottom, bottom + stride);
+		pixels.set(row, bottom);
+	}
+}
 //#endregion
 //#region src/3d/create-game.ts
 var create_game_exports = /* @__PURE__ */ __exportAll({ createGame3D: () => createGame3D });
@@ -2378,6 +2504,27 @@ async function createGame3D(opts) {
 	cleanups.push(engine.settings.bindRenderScale((scale) => {
 		renderer.setRenderScale?.(scale);
 	}));
+	const captureReport = async (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);
+	};
+	const hot = import.meta.hot;
+	if (hot) {
+		const onFrameRequest = (data) => {
+			const id = data?.id;
+			captureReport().then((frameReport) => hot.send("incanto:frame-report", {
+				id,
+				report: frameReport
+			})).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));
+	}
 	await report(1, "ready");
 	function disposeGame() {
 		teardown([
@@ -2398,6 +2545,12 @@ async function createGame3D(opts) {
 		assetErrors() {
 			return renderer.assets?.errors() ?? [];
 		},
+		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);
+		},
 		pick(x, y) {
 			return engine.picker?.(x, y) ?? null;
 		},
@@ -2464,4 +2617,4 @@ function wireAudioUnlock(engine, root, canvas) {
 	return detachAll;
 }
 //#endregion
-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 };
+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 };

package/dist/debug.d.ts

@@ -1,4 +1,4 @@
-import { At as LogLevel, T as RendererStats, b as Engine } from "./behavior-TA8nySqb.js";
+import { At as LogLevel, T as RendererStats, b as Engine } from "./behavior-62q0HWBO.js";
 
 //#region src/debug/panel.d.ts
 /** Minimal document surface the overlay needs (injectable for tests). */
@@ -7,7 +7,7 @@ interface DocumentLike {
 }
 //#endregion
 //#region src/debug/index.d.ts
-type DebugPanelId = "explorer" | "inspector" | "logs" | "stats";
+type DebugPanelId = "explorer" | "inspector" | "logs" | "stats" | "time";
 /** Menu entries that are switches rather than panels. */
 type DebugSwitchId = "colliders";
 /** `all` is every collider in the world; `selected` follows the Explorer. */
@@ -64,6 +64,15 @@ declare class DebugOverlay {
   private editing;
   /** Which bulky values are unfolded, per node ('transforms', 'collider.vertices'). */
   private readonly detailOpen;
+  /**
+  * The scale to come back to when a pause is lifted.
+  *
+  * Captured only from a RUNNING scale: pausing an already-frozen game (a
+  * hit-stop, a previous pause) must not record 0 as the thing to restore, or
+  * Resume does nothing and the game looks hung.
+  */
+  private resumeScale;
+  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[]);
@@ -107,6 +116,31 @@ declare class DebugOverlay {
   private renderValueRow;
   private trackEditing;
   private pushLog;
+  /**
+  * 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
+  * that has never been asked to.
+  */
+  setTimeScale(next: number): void;
+  /** Freeze or unfreeze game time. Rendering keeps running — this is a pause,
+  *  not a stop: the camera still moves and the overlay stays interactive. */
+  setPaused(paused: boolean): void;
+  get paused(): boolean;
+  /**
+  * Advance exactly one frame, pausing first.
+  *
+  * Stepping a RUNNING game is meaningless — the next real frame lands a
+  * millisecond later and swamps the step — so this pauses and then steps,
+  * which is also the only way the button is useful twice in a row.
+  */
+  nextFrame(): void;
+  /** Push the engine's current time state into the panel, without rebuilding it. */
+  private syncTime;
+  private renderTime;
+  /** After a committed edit the field must show what the ENGINE took — a
+  *  rejected 'abc' or a clamped -2 has to be visible, not left on screen. */
+  private syncTimeAfterEdit;
   private renderLogs;
 }
 //#endregion