incanto 0.27.0 → 0.29.0

package/dist/3d.d.ts

@@ -1,9 +1,10 @@
-import { s as JsonObject } from "./schema-CcoWb32N.js";
-import { $ as Node, C as RendererStats, S as GameStats, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-CPibUfnH.js";
-import { t as LoadSceneOptions } from "./loader-DILt9PGC.js";
+import { i as SceneJson, s as JsonObject } from "./schema-CcoWb32N.js";
+import { $ as Node, C as RendererStats, S as GameStats, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-BAc0erXF.js";
+import { t as EditorSwitchOptions } from "./editor-switch-B0wB_DSr.js";
+import { t as LoadSceneOptions } from "./loader-B242FF6N.js";
 import { t as ParticleSim } from "./particle-sim-CwJ5rI_P.js";
-import { n as PathGrid, s as SpatialPose } from "./pathfinding-RWYkNKx9.js";
-import { AnimationClip, BufferGeometry, Color, DirectionalLight, InstancedMesh, Mesh, MeshPhysicalMaterial, Object3D, PerspectiveCamera, Scene, ShaderMaterial, Vector3, WebGLRenderer } from "three";
+import { n as PathGrid, s as SpatialPose } from "./pathfinding-BwD974Ss.js";
+import { AnimationClip, AnimationMixer, BufferGeometry, Color, DirectionalLight, Group, InstancedMesh, Mesh, MeshPhysicalMaterial, Object3D, PerspectiveCamera, Scene, ShaderMaterial, Vector3, WebGLRenderer } from "three";
 import { VRM } from "@pixiv/three-vrm";
 import { Sky } from "three/examples/jsm/objects/Sky.js";
 import * as RapierNs from "@dimforge/rapier3d-compat";
@@ -124,13 +125,6 @@ interface SunConsumer3D {
   /** @internal Called by syncTree when `environment.sky` declares a sun. */
   _applySunDirection(dir: readonly [number, number, number]): void;
 }
-/**
-* Base of every 3D node: a JSON-prop transform backed by a `THREE.Object3D`.
-*
-* Props stay plain JSON (registry/serializer compatible); the renderer layer
-* pushes them onto the backing object once per frame (`_syncObject3D`).
-* Rotation is in DEGREES in JSON — friendlier for agents and humans.
-*/
 declare class Node3D extends Node {
   static override readonly typeName: string;
   static readonly props: PropSchema;
@@ -154,6 +148,23 @@ declare class Node3D extends Node {
   renderOrder: number;
   /** Named draw-order band; `renderOrder` is the fine offset inside it. */
   orderGroup: string;
+  /**
+  * PUT THIS ON THE GROUND. `true` sets the node's Y from the terrain under it
+  * at load; a number does the same and lifts it by that many metres (a post
+  * whose origin sits at its middle wants half its height).
+  *
+  * Computing a Y by hand is the single most repeated mistake in scene
+  * authoring, and it is not a careless one: the number is right when it is
+  * written and wrong the moment anything reshapes the ground — a river carving
+  * its bed, a basin, a different seed, a generator that mirrors the carve
+  * slightly differently. Every "floating boulder", "buried player" and
+  * "bridge posts in mid-air" in this engine's history is that drift.
+  *
+  * With this the ground is asked at load, in the same frame the terrain is
+  * built, and there is nothing to drift from. `null` (default) leaves `y`
+  * exactly as authored — for anything that genuinely hangs in the air.
+  */
+  snapToGround: number | boolean | null;
   /** What three actually sorts by: band base + renderOrder. */
   get effectiveRenderOrder(): number;
   private _object3D;
@@ -165,6 +176,15 @@ declare class Node3D extends Node {
   */
   _interpPrev: number[] | null;
   _interpCurr: number[] | null;
+  override onReady(): void;
+  /**
+  * Resolve {@link snapToGround} against the terrain under this node.
+  *
+  * Ancestor transforms are translation-only here, the same contract heightAt
+  * and the physics heightfield already follow, so the world height converts
+  * back to a local Y by subtracting the parents' offset.
+  */
+  applyGroundSnap(): void;
   /** @internal The backing three object (lazily created). */
   _ensureObject3D(): Object3D;
   /** @internal Override point for subclasses (mesh, camera, light…). */
@@ -262,6 +282,8 @@ declare class Physics3D {
   private readonly engine;
   /** Render collider outlines in the GAME view (renderers pick this up). */
   debugDraw: boolean;
+  /** Narrow those outlines to one node's subtree (see DebugLineSource). */
+  debugScope: object | null;
   readonly dimension = "3d";
   private readonly unregisterDebug;
   private readonly warnedNoCollider;
@@ -281,13 +303,36 @@ declare class Physics3D {
   moveAndSlide(node: CharacterBody3D): void;
   /** Rapier debug segments (meters). Null while debugDraw is off. */
   debugLines(): Float32Array | null;
+  /**
+  * The Rapier bodies a selected node stands for: its own, its descendants',
+  * and — when it owns none — the nearest body ABOVE it, so clicking the visual
+  * mesh child of a StaticBody3D shows that body's collider rather than nothing.
+  */
+  private scopedBodies;
   dispose(): void;
   private lastStructure;
   private lastRoot;
   private readonly jointSet;
   private readonly joints;
+  /** One fixed body per solid scatter field, carrying a collider per row. */
+  private readonly scatterBodies;
   private readonly bodySet;
+  /**
+  * Give every row of a scatter field its own static collider.
+  *
+  * A stone field is one node with fifty transforms in it, and a player walking
+  * through all fifty is what gives a world away as scenery. All of them hang
+  * off ONE fixed body — they never move, so there is nothing to step — and the
+  * whole set is rebuilt only when the tree's shape changes.
+  */
+  private syncScatters;
   private syncBodies;
+  /**
+  * Null while a `{"shape":"auto"}` body is waiting on its model — the shape
+  * lives in the model's triangles, and there is nothing honest to guess in the
+  * meantime. syncBodies runs every step, so the body appears the moment the
+  * download lands.
+  */
   private ensureEntry;
   /** Apply a world-space impulse to a dynamic body (character controllers). */
   applyImpulse(node: PhysicsBody3D, impulse: [number, number, number]): void;
@@ -374,6 +419,20 @@ interface CreateGame3DOptions {
   _debugDoc?: {
     createElement(tag: string): HTMLElement;
   };
+  /**
+  * LIVE EDITING: the ☰ debug menu gains "edit this scene", which turns this
+  * page into the scene editor — same window, no reload — and the editor's play
+  * button turns it back into the game. The scene and the camera survive both
+  * crossings.
+  *
+  * DEFAULTS TO `debug`: a build with the debug overlay is a build someone is
+  * working on, and "the scene I am looking at, open in the editor" is what
+  * working on it means. It costs nothing until clicked — the editor is a lazy
+  * chunk. `false` opts out; `{ open }` loads it yourself (apps that alias
+  * incanto to source); `{ save }` makes the editor's save button write your
+  * file. Never reachable without `debug` — the ☰ menu is its only entrance.
+  */
+  editor?: boolean | EditorSwitchOptions;
   seed?: number;
   fixedHz?: number;
   pixelRatio?: number;
@@ -381,6 +440,19 @@ interface CreateGame3DOptions {
   * (default ON). `false` pins the resolution — screenshots, capture, tests. */
   adaptiveResolution?: boolean;
   resolveScene?: LoadSceneOptions["resolveScene"];
+  /**
+  * Boot progress, for the loading screen an app already has.
+  *
+  * Assets are only the FIRST half of a boot: building a dressed scene and
+  * compiling its GPU programs takes as long again, and a bar that hits 100%
+  * on the last downloaded byte then sits there while the world is built is
+  * worse than no bar — the player reads "done" and waits anyway.
+  *
+  * `fraction` runs 0 → 1 across everything this call does, and `label` names
+  * the phase ('scene', 'physics', 'renderer', 'shaders', 'ready'). Feed the
+  * asset preload into the first half and this into the second.
+  */
+  onProgress?: (fraction: number, label: string) => void;
   /** @internal Test seam — replaces the Renderer3D construction. */
   _rendererFactory?: (engine: Engine, canvas: HTMLCanvasElement) => GameRenderer;
   /** @internal Test seam — replaces the rAF scheduler. */
@@ -394,10 +466,32 @@ interface GameRenderer {
 interface Game3D {
   engine: Engine;
   scene: Scene$1;
+  /**
+  * The AUTHORED scene this game booted from — the JSON, not the live tree.
+  *
+  * A running tree has moved: physics has stepped it, behaviors have spawned
+  * into it, the player is somewhere else. Handing that to an editor would
+  * make "edit the scene" mean "edit wherever the simulation happens to be",
+  * so the source is kept beside the game and handed over unchanged.
+  */
+  sourceJson: SceneJson;
   renderer: GameRenderer;
   physics: Physics3D | null;
   /** Engine + renderer perf counters in one read (fps/nodes/triangles/…). */
   stats(): GameStats;
+  /**
+  * Turn this page into the scene editor, right where the player is standing —
+  * what the ☰ debug menu's "edit this scene" calls. Bind it to your own key or
+  * button if you want the switch without the overlay.
+  *
+  * Resolves once the editor has taken the page. The game is disposed on the
+  * way out and rebooted when the editor hands it back, so the `Game3D` this
+  * was called on is DEAD afterwards — take the new one from the editor's
+  * `play` path if you need a handle.
+  *
+  * `null` when the game was booted with `editor: false` — nothing to open.
+  */
+  openEditor: (() => Promise<void>) | null;
   dispose(): void;
 }
 /**
@@ -909,6 +1003,12 @@ declare class Flowers3D extends Node3D {
   * draping entirely.
   */
   drape: boolean | null;
+  /**
+  * Keep plants out of standing and running water (default true) — a meadow a
+  * stream runs through has a bank of flowers, not flowers in the current.
+  * Set false for water lilies and marsh planting.
+  */
+  avoidWater: boolean;
   /** Drape target: a node path to the Terrain3D. Empty = auto-find the first
   * Terrain3D in the tree (the zero-config default when `drape` is on). */
   terrain: string;
@@ -1051,6 +1151,14 @@ declare class Foliage3D extends Node3D implements SunConsumer3D {
   * a terrain appears), false disables draping entirely.
   */
   drape: boolean | null;
+  /**
+  * Keep blades out of standing and running water (default true). Grass does
+  * not grow in a stream: any instance whose ground sits under a `Water3D` or
+  * `River3D` surface is dropped, which is what stops a creek that cut its bed
+  * through a meadow from filling with waving blades. Set false for reeds and
+  * paddy fields, where the plant IS in the water.
+  */
+  avoidWater: boolean;
   /** Drape target: a node path to the Terrain3D. Empty = auto-find the first
   * Terrain3D in the tree (the zero-config default when `drape` is on). */
   terrain: string;
@@ -1119,6 +1227,14 @@ declare class Foliage3D extends Node3D implements SunConsumer3D {
   * fraction of instances into a SECOND InstancedMesh of 5-vertex flower
   * heads (white/yellow/violet per instance).
   */
+  /**
+  * Drop the instances standing in water. The ground each blade drapes onto is
+  * already known here, so the test is one question per candidate — and only
+  * the ones a water surface actually covers pay for it.
+  */
+  private dryOnly;
+  /** This field's own world height (the bed sampler works in local Y). */
+  private worldY;
   private buildMeshField;
   /**
   * The meadow's flower sprinkle: ONE extra InstancedMesh of 5-vertex flower
@@ -1247,6 +1363,23 @@ declare class InstancedMesh3D extends Node3D {
   material: MeshMaterialProps;
   castShadow: boolean;
   receiveShadow: boolean;
+  /**
+  * Make the scatter SOLID: `{}` gives every row a collider shaped like the
+  * mesh itself — a faceted `gem` stone collides as that stone's own hull, not
+  * as a ball tucked inside it — sized from `size` × the row's scale.
+  *
+  * A field of fifty boulders a player walks straight through is the tell that
+  * a world is a picture. One fixed body carries all the colliders, so the cost
+  * is a handful of shapes and no per-frame work — these never move.
+  *
+  * `{ shape: 'sphere' | 'box' }` (with `radius`/`size`) opts out into a
+  * cheaper approximation when a rough blocker is genuinely all you want.
+  */
+  collider: {
+    shape?: string;
+    radius?: number;
+    size?: number[];
+  } | null;
   private _transforms;
   private transformsDirty;
   get transforms(): number[][];
@@ -1401,6 +1534,23 @@ declare class ModelInstance3D extends Node3D {
   /** false = play the clip once, then emit `animationFinished`. */
   animationLoop: boolean;
   /**
+  * Playback rate of BOTH animation layers. 1 is the speed the clip was
+  * authored at; 0.5 halves it, 2 doubles it, 0 freezes on the current pose.
+  * Negative plays backwards (a closing door is an opening one reversed).
+  *
+  * Live: changing it retimes the clip already playing, no restart.
+  */
+  animationSpeed: number;
+  /**
+  * Seconds into the clip to start at.
+  *
+  * A row of identical torches all starting at 0 flickers in lockstep and the
+  * eye reads it instantly as "copies". Give each a different offset and the
+  * same clip becomes a crowd. Applied when a clip STARTS (a restart re-seeks),
+  * wrapped into the clip's duration, so any number is legal.
+  */
+  animationOffset: number;
+  /**
   * Two-layer animation: play this clip on the UPPER BODY ONLY (the
   * `upperBodyRoot` bone subtree) while `animation` keeps driving the rest —
   * attack while running, wave while walking. One-shot by default
@@ -1425,7 +1575,21 @@ declare class ModelInstance3D extends Node3D {
   private mountedRef;
   private fittedHeight;
   private fitGroup;
+  /**
+  * @internal The mounted model, or null while the asset is still loading.
+  * Physics reads this to shape a `{"shape":"auto"}` collider on the real
+  * triangles — nothing else may reach into the loaded three graph.
+  */
+  _mountedObject3D(): Group | null;
   private mixer;
+  /** The offset the playing clip was seeked to — re-seek when the prop moves. */
+  private appliedOffset;
+  /** @internal Test seam — the mixer driving this model's clips. */
+  get _mixer(): AnimationMixer | null;
+  /** @internal Test seam — which `animation` key is actually playing. */
+  get _playingClip(): string;
+  /** @internal Test seam — where the base clip currently is, in seconds. */
+  get _currentActionTime(): number;
   private playing;
   private currentAction;
   private playingUpper;
@@ -1555,29 +1719,152 @@ declare class Particles3D extends Node3D {
   private syncParticles;
 }
 //#endregion
-//#region src/3d/water/river.d.ts
+//#region src/3d/terrain/heightmap.d.ts
 /**
-* River centerline math — the CPU half of {@link River3D}.
-*
-* Everything here works in the river node's LOCAL frame (the caller hands in a
-* `bedAt(x, z)` sampler that has already been shifted into it), so this module
-* imports nothing from three and stays testable in plain node.
-*
-* The shape of a river is NOT authored: it is derived. A path of control
-* points and a width profile is all a scene declares; the ground underneath
-* decides the rest —
-*
-* - the **surface profile** follows the bed's descending envelope, so the water
-*   runs downhill and never climbs (a rising bed dams it into a still pool);
-* - the **visible width** is whatever the terrain lets the water occupy: every
-*   vertex carries its own water column (`surfaceY − bed`), the shader fades to
-*   nothing where that reaches zero, so banks, gravel bars and half-drowned
-*   boulders carve the ribbon instead of a hand-authored outline;
-* - the **current** obeys continuity (narrow = fast) and grade (steep = fast),
-*   which is what makes rapids sit where a channel pinches or tips.
+* A smooth radial depression carved into the terrain — a lake/pond bowl. x/z
+* are terrain-LOCAL centered meters (the same space `heightAt`/`slopeAt` use);
+* `radius`/`depth` are meters. The carve is a smoothstep bowl (0 slope at the
+* rim), so banks blend into the surrounding ground with no cliff.
 */
+interface BasinSpec {
+  x: number;
+  z: number;
+  radius: number;
+  /** > 0 carves a bowl; < 0 RAISES a smooth dome mound of that height. */
+  depth: number;
+}
+/**
+* A river/road trench carved along a polyline: the line version of a basin.
+* `width` is the flat bed, `taper` the bank blend beyond it (default: the bed
+* width again, which is what makes a walkable V instead of a slot).
+*/
+interface ChannelSpec {
+  path: readonly (readonly number[])[];
+  width: number;
+  depth: number;
+  taper?: number;
+}
+interface HeightmapOptions {
+  /** Terrain extent in meters along x. */
+  width: number;
+  /** Terrain extent in meters along z. */
+  depth: number;
+  /** Grid segments along x (vertices = segsX+1). */
+  segsX: number;
+  /** Grid segments along z (vertices = segsZ+1). */
+  segsZ: number;
+  /** Height scale — realized heights land at roughly 3.5–8× this value. */
+  maxHeight: number;
+  /** Integer seed — same seed, same terrain, every machine. */
+  seed: number;
+  /** Detail persistence (amplitude falloff per detail octave). */
+  roughness?: number;
+  /** Detail octave count. */
+  detail?: number;
+  /** Snap-flatten heights within ±0.6 m of maxHeight·flatThreshold. */
+  flatThreshold?: number;
+  /** Curl the border down a quarter circle and floor it at edgeBottom. */
+  islandEdge?: boolean;
+  /** Quarter-circle radius in meters (clamped to [0, 45]). */
+  edgeWrapRadius?: number;
+  /** Floor y at the outermost ring once the wrap completes. */
+  edgeBottom?: number;
+  /** 0..1 — 1 rounds island corners fully, 0 keeps them square-ish. */
+  edgeCornerSmoothness?: number;
+  /** Smooth radial lake/pond bowls carved into the surface (interior basins). */
+  basins?: BasinSpec[];
+  /** River/road trenches carved along polylines (see {@link ChannelSpec}). */
+  channels?: ChannelSpec[];
+}
+interface Heightmap {
+  readonly width: number;
+  readonly depth: number;
+  readonly segsX: number;
+  readonly segsZ: number;
+  /**
+  * Vertex heights INCLUDING edge wrap, `(segsX+1)·(segsZ+1)` long, indexed
+  * `iz·(segsX+1)+ix` with x = -width/2 + ix·cell and z = -depth/2 + iz·cell —
+  * exactly a rotateX(-π/2) PlaneGeometry's vertex order.
+  */
+  readonly heights: Float32Array;
+  /** Realized height range EXCLUDING edge wrap — normalizes splat heights. */
+  readonly minHeight: number;
+  readonly maxHeight: number;
+  /** Bilinear height lookup in terrain-local centered meters (clamps outside). */
+  heightAt(x: number, z: number): number;
+  /** Analytic pipeline height WITHOUT edge wrap (splat domain), same coords. */
+  baseHeight(x: number, z: number): number;
+  /** Splat slope at a point: atan(|∇ baseHeight|) via central differences. */
+  slopeAt(x: number, z: number): number;
+}
+/** One splat layer: a texture plus the trapezoid ranges that place it. */
+interface TerrainLayer {
+  /** Base color texture URL. */
+  texture: string;
+  /** Optional tangent-space normal map URL. */
+  normalMap?: string;
+  /** World-UV tiling factor (UV = worldXZ · repeat · 0.1). Default 2. */
+  repeat?: number;
+  /** Normalized [min, max] over the realized height span. Default [0, 1]. */
+  heightRange?: [number, number];
+  /** [min, max] slope in radians (atan of gradient). Default [0, π/2]. */
+  slopeRange?: [number, number];
+  /** Linear falloff width OUTSIDE heightRange (fraction of span). Default 0.1. */
+  heightBlendRange?: number;
+  /** Linear falloff width outside slopeRange (radians). Default 0.1. */
+  slopeBlendRange?: number;
+  /** PBR roughness scalar for this layer. Default 1. */
+  roughness?: number;
+  /** PBR metalness scalar for this layer. Default 0. */
+  metalness?: number;
+  /** Anti-tiling UV jitter strength. Default 0.15. */
+  uvNoiseIntensity?: number;
+}
+/**
+* Build the deterministic heightfield. Heavy (one noise eval per vertex) —
+* call once and keep the result.
+*/
+declare function buildHeightmap(opts: HeightmapOptions): Heightmap;
+/**
+* Per-vertex splat weights for up to 4 layers. `height01` is the vertex
+* height normalized over the heightmap's realized (no-wrap) span, `slopeRad`
+* is `atan(|∇h|)`. Weight = heightTrapezoid · slopeTrapezoid, sharpened by
+* `pow(w, 1/blendingStrength)`, then normalized to sum 1 — when nothing
+* matches, layer 0 takes everything. Always returns exactly 4 entries
+* (missing layers weigh 0).
+*/
+declare function splatWeights(height01: number, slopeRad: number, layers: readonly TerrainLayer[], blendingStrength?: number): [number, number, number, number];
+//#endregion
+//#region src/3d/water/river.d.ts
 /** Terrain height under a LOCAL-frame point, in the same frame's meters. */
 type BedSampler = (x: number, z: number) => number;
+interface RiverCarveOptions {
+  /** Centreline in the TERRAIN'S local frame (that is where channels live). */
+  path: readonly (readonly number[])[];
+  /** Width profile source→mouth (one entry = constant). */
+  widths: readonly number[];
+  /** Water column at the centreline, meters. */
+  depth: number;
+  /** Terrain cell size in meters — a cut finer than this does not exist. */
+  cell: number;
+  /** Ground height BEFORE this river cut anything. */
+  groundAt: BedSampler;
+}
+/**
+* The trench a river digs for itself, as {@link ChannelSpec}s for Terrain3D.
+*
+* Shared on purpose: `River3D` cuts this at load, and anything that has to
+* PLACE things against the result — a scene generator putting a player, a
+* bridge and a boulder field on the ground — computes the identical cut
+* instead of approximating it. A generator that guesses differently spawns the
+* player inside a hill.
+*
+* The floor only ever FALLS. Water does not climb, so a bed that climbs is a
+* river that stops and buries itself; carrying the running minimum downstream
+* digs through a rise instead, and the cap keeps that from turning a hill into
+* a canyon.
+*/
+declare function riverCarveChannels(opts: RiverCarveOptions): ChannelSpec[];
 /** One arc-length sample of the smoothed centerline. */
 interface PathSample {
   x: number;
@@ -1588,6 +1875,30 @@ interface PathSample {
   /** Meters from the source. */
   along: number;
 }
+/** One reach where the ribbon could not cover the ground its water stands on. */
+interface RiverCoverageGap {
+  /** Metres from the source. */
+  along: number;
+  /** What the terrain says is under water at this station. */
+  wettedHalfWidth: number;
+  /** What a ribbon can carry through the bend here. */
+  carriedHalfWidth: number;
+}
+/**
+* Where a river's ribbon falls short of the water it is standing in.
+*
+* A swept ribbon has a hard geometric ceiling — it cannot be wider than the
+* bend it is taking, or its inner edge folds through itself. When the ground
+* under the surface is wetter than that ceiling allows, the ribbon leaves BARE
+* CHANNEL FLOOR beside the water, and to a player the creek simply stops in
+* the middle of its own bed. No amount of shader work fixes it: the surface
+* really is missing.
+*
+* This reports those reaches so a caller can act on them instead of shipping
+* them. River3D calls it at build time and warns; `incanto/test` exposes it so
+* a game can gate on it headlessly.
+*/
+declare function findRiverCoverageGaps(rings: readonly RiverRing[], tolerance?: number): RiverCoverageGap[];
 /** A cross-section station: where the water is, how wide, how fast. */
 interface RiverRing extends PathSample {
   /** The width the author ASKED for (half of it) — nominal, drives current. */
@@ -1595,6 +1906,9 @@ interface RiverRing extends PathSample {
   /** Wetted half-width to the left of the flow: where the ground rises to the
   * surface. This, not {@link halfWidth}, is where the water actually ends. */
   halfLeft: number;
+  /** What the terrain scan asked for before the bend capped it (fit only). */
+  wettedLeft?: number;
+  wettedRight?: number;
   /** Wetted half-width to the right of the flow. */
   halfRight: number;
   /** No bank on that side: the ground never came up to the surface, so the
@@ -1609,6 +1923,26 @@ interface RiverRing extends PathSample {
   /** Surface current in m/s. */
   speed: number;
 }
+interface RiverRingOptions {
+  path: readonly (readonly number[])[];
+  /** One entry = constant width; several = a profile lerped source→mouth. */
+  widths: readonly number[];
+  /** Water column at the centerline, in meters. */
+  depth: number;
+  /** Reference current in m/s (the mean over the river). */
+  flowSpeed: number;
+  /** Centerline sampling step in meters. */
+  step: number;
+  bedAt: BedSampler;
+  /**
+  * Fit the surface to the ground across the channel — the surface may not
+  * stand above the rim that holds it, and the ribbon ends where the ground
+  * comes up to meet it. Default OFF, because it is meaningful only when
+  * `bedAt` is REAL ground: a river with no terrain under it invents a bed one
+  * `depth` below itself, and there is nothing there to contain or spill it.
+  */
+  fit?: boolean;
+}
 interface RiverHit {
   /** In the channel: inside the banks AND between source and mouth. */
   inside: boolean;
@@ -1623,11 +1957,57 @@ interface RiverHit {
   speed: number;
   halfWidth: number;
 }
+/**
+* Make a traced course fit to carry a river of a given width.
+*
+* `traceDownhillPath` follows the steepest descent, which on real terrain
+* zigzags, kinks and sometimes hooks back within a few metres of a reach it
+* already ran. A ribbon on such a course cannot be well formed at any width
+* worth looking at: tight corners fold its inner edge, and a hook stacks two
+* sheets of water on the same ground. Every symptom of that is a rendering
+* artifact with no rendering fix.
+*
+* So the course is conditioned first, in three steps that are all about the
+* WIDTH the river will be:
+*  1. Laplacian passes relax the trace toward a curve whose bends a ribbon of
+*     `halfWidth` can take.
+*  2. Points closer together than the width are dropped — they only encode
+*     noise at that scale.
+*  3. The course is CUT where it comes back within two widths of itself: a
+*     creek does not flow over its own reach, and ending is a better answer
+*     than two stacked sheets or a strangled trickle.
+*
+* Use it on anything `traceDownhillPath` produces before handing it to River3D.
+*/
+declare function smoothCourse(path: readonly (readonly number[])[], halfWidth: number, passes?: number): number[][];
+/**
+* The centerline station spacing River3D itself uses — EXPORTED so a generator
+* placing things against the water calls the same derivation. A hardcoded step
+* puts the generator's stations in different places than the node's; on a
+* smooth reach nobody notices, on a tight tail the two snap to different rings
+* and rocks grown for one water stand beside the other.
+*/
+declare function riverStepFor(widths: readonly number[], depth: number): number;
+declare function buildRiverRings(opts: RiverRingOptions): RiverRing[];
+declare function projectToRiver(rings: readonly RiverRing[], x: number, z: number): RiverHit | null;
 /** A place where the river stops flowing and starts falling. */
 interface RiverFall {
   /** Where the water LANDS (local frame) — the plunge point. */
   x: number;
   z: number;
+  /** Where it LEAVES: the lip. A falling sheet hangs from here, not from the
+  * plunge — hanging it downstream is how a curtain ends up floating in the
+  * air past the cliff it should be pouring over. */
+  lipX: number;
+  lipZ: number;
+  /** Water half-width AT THE LIP — a fall is as wide as the water going over
+  * the edge, not as wide as the pool it lands in. */
+  lipHalfWidth: number;
+  /** Downstream direction at the lip. */
+  lipDirX: number;
+  lipDirZ: number;
+  /** Current at the lip — what throws the sheet forward. */
+  lipSpeed: number;
   /** Water surface at the lip and at the base. */
   topY: number;
   baseY: number;
@@ -1746,6 +2126,8 @@ declare class River3D extends Node3D implements SunConsumer3D {
   private bedAt;
   /** Whether the last course was fitted to real ground (see buildRiverRings). */
   private fitted;
+  private bounds;
+  private boundsKey;
   /** Everything standing in the current, rescanned on a slow timer. */
   private rocks;
   private rockScanAt;
@@ -1761,6 +2143,15 @@ declare class River3D extends Node3D implements SunConsumer3D {
   /** Rocks are picked per FRAME (nearest to the eye), scanned on a timer. */
   _onRender3D(ctx: RenderContext3D): void;
   /**
+  * @internal Water surface height over a world point, or null where this
+  * river does not run — the question scattered vegetation asks before it
+  * plants a blade (see {@link WetSurface}).
+  */
+  _waterYAt(x: number, z: number): number | null;
+  /** XZ bounds of the wetted channel, padded by its widest reach. Rebuilt with
+  * the course (the key is the same one the course is derived under). */
+  private ringBounds;
+  /**
   * Where a WORLD point sits in the channel — the query gameplay scripts run
   * (steer a raft, drown a torch, decide a ford is too fast to cross). `null`
   * until the river has been built.
@@ -1802,6 +2193,18 @@ declare class River3D extends Node3D implements SunConsumer3D {
   * Pure CPU work — no three objects — so gameplay can call it any time.
   */
   private ensureCourse;
+  /**
+  * Say so when the course cannot carry the water standing in it.
+  *
+  * A swept ribbon may not be wider than the bend it takes (its inner edge
+  * would fold through itself), so where the ground is wetter than that ceiling
+  * the surface leaves BARE CHANNEL FLOOR — the creek visibly stops in the
+  * middle of its own bed. That is a course/width mismatch the author has to
+  * decide about, and it is invisible from the JSON, so it is said out loud
+  * with the three things that fix it.
+  */
+  private warnUncoveredWater;
+  private warnedCoverage;
   private rebuildIfNeeded;
   private buildMaterial;
   /**
@@ -1834,122 +2237,6 @@ declare class River3D extends Node3D implements SunConsumer3D {
   private sweepBodies;
 }
 //#endregion
-//#region src/3d/terrain/heightmap.d.ts
-/**
-* A smooth radial depression carved into the terrain — a lake/pond bowl. x/z
-* are terrain-LOCAL centered meters (the same space `heightAt`/`slopeAt` use);
-* `radius`/`depth` are meters. The carve is a smoothstep bowl (0 slope at the
-* rim), so banks blend into the surrounding ground with no cliff.
-*/
-interface BasinSpec {
-  x: number;
-  z: number;
-  radius: number;
-  /** > 0 carves a bowl; < 0 RAISES a smooth dome mound of that height. */
-  depth: number;
-}
-/**
-* A river/road trench carved along a polyline: the line version of a basin.
-* `width` is the flat bed, `taper` the bank blend beyond it (default: the bed
-* width again, which is what makes a walkable V instead of a slot).
-*/
-interface ChannelSpec {
-  path: readonly (readonly number[])[];
-  width: number;
-  depth: number;
-  taper?: number;
-}
-interface HeightmapOptions {
-  /** Terrain extent in meters along x. */
-  width: number;
-  /** Terrain extent in meters along z. */
-  depth: number;
-  /** Grid segments along x (vertices = segsX+1). */
-  segsX: number;
-  /** Grid segments along z (vertices = segsZ+1). */
-  segsZ: number;
-  /** Height scale — realized heights land at roughly 3.5–8× this value. */
-  maxHeight: number;
-  /** Integer seed — same seed, same terrain, every machine. */
-  seed: number;
-  /** Detail persistence (amplitude falloff per detail octave). */
-  roughness?: number;
-  /** Detail octave count. */
-  detail?: number;
-  /** Snap-flatten heights within ±0.6 m of maxHeight·flatThreshold. */
-  flatThreshold?: number;
-  /** Curl the border down a quarter circle and floor it at edgeBottom. */
-  islandEdge?: boolean;
-  /** Quarter-circle radius in meters (clamped to [0, 45]). */
-  edgeWrapRadius?: number;
-  /** Floor y at the outermost ring once the wrap completes. */
-  edgeBottom?: number;
-  /** 0..1 — 1 rounds island corners fully, 0 keeps them square-ish. */
-  edgeCornerSmoothness?: number;
-  /** Smooth radial lake/pond bowls carved into the surface (interior basins). */
-  basins?: BasinSpec[];
-  /** River/road trenches carved along polylines (see {@link ChannelSpec}). */
-  channels?: ChannelSpec[];
-}
-interface Heightmap {
-  readonly width: number;
-  readonly depth: number;
-  readonly segsX: number;
-  readonly segsZ: number;
-  /**
-  * Vertex heights INCLUDING edge wrap, `(segsX+1)·(segsZ+1)` long, indexed
-  * `iz·(segsX+1)+ix` with x = -width/2 + ix·cell and z = -depth/2 + iz·cell —
-  * exactly a rotateX(-π/2) PlaneGeometry's vertex order.
-  */
-  readonly heights: Float32Array;
-  /** Realized height range EXCLUDING edge wrap — normalizes splat heights. */
-  readonly minHeight: number;
-  readonly maxHeight: number;
-  /** Bilinear height lookup in terrain-local centered meters (clamps outside). */
-  heightAt(x: number, z: number): number;
-  /** Analytic pipeline height WITHOUT edge wrap (splat domain), same coords. */
-  baseHeight(x: number, z: number): number;
-  /** Splat slope at a point: atan(|∇ baseHeight|) via central differences. */
-  slopeAt(x: number, z: number): number;
-}
-/** One splat layer: a texture plus the trapezoid ranges that place it. */
-interface TerrainLayer {
-  /** Base color texture URL. */
-  texture: string;
-  /** Optional tangent-space normal map URL. */
-  normalMap?: string;
-  /** World-UV tiling factor (UV = worldXZ · repeat · 0.1). Default 2. */
-  repeat?: number;
-  /** Normalized [min, max] over the realized height span. Default [0, 1]. */
-  heightRange?: [number, number];
-  /** [min, max] slope in radians (atan of gradient). Default [0, π/2]. */
-  slopeRange?: [number, number];
-  /** Linear falloff width OUTSIDE heightRange (fraction of span). Default 0.1. */
-  heightBlendRange?: number;
-  /** Linear falloff width outside slopeRange (radians). Default 0.1. */
-  slopeBlendRange?: number;
-  /** PBR roughness scalar for this layer. Default 1. */
-  roughness?: number;
-  /** PBR metalness scalar for this layer. Default 0. */
-  metalness?: number;
-  /** Anti-tiling UV jitter strength. Default 0.15. */
-  uvNoiseIntensity?: number;
-}
-/**
-* Build the deterministic heightfield. Heavy (one noise eval per vertex) —
-* call once and keep the result.
-*/
-declare function buildHeightmap(opts: HeightmapOptions): Heightmap;
-/**
-* Per-vertex splat weights for up to 4 layers. `height01` is the vertex
-* height normalized over the heightmap's realized (no-wrap) span, `slopeRad`
-* is `atan(|∇h|)`. Weight = heightTrapezoid · slopeTrapezoid, sharpened by
-* `pow(w, 1/blendingStrength)`, then normalized to sum 1 — when nothing
-* matches, layer 0 takes everything. Always returns exactly 4 entries
-* (missing layers weigh 0).
-*/
-declare function splatWeights(height01: number, slopeRad: number, layers: readonly TerrainLayer[], blendingStrength?: number): [number, number, number, number];
-//#endregion
 //#region src/3d/terrain/themes.d.ts
 /** Valid `Terrain3D.theme` values — drives the prop options AND validateJson. */
 declare const TERRAIN_THEMES: readonly ["island", "alpine", "plains", "desert", "grassland", "forest", "savanna", "snow", "wetland", "volcanic", "custom"];
@@ -2027,6 +2314,10 @@ declare class Terrain3D extends Node3D {
   * dug", and re-loading the scene digs it again.
   */
   private readonly externalChannels;
+  /** Bumped whenever an external channel is cut or released. */
+  private externalRev;
+  /** What the cached heightmap was built from (see shapeUnchanged). */
+  private shapeStamp;
   /**
   * WET SAND band: `{ y, band? }` darkens + glosses the splat in a noisy,
   * breathing band just above height `y` (a waterline) — the trace of the
@@ -2062,6 +2353,9 @@ declare class Terrain3D extends Node3D {
   private allChannels;
   /** @internal The pure heightfield (lazily built — physics pulls this). */
   _heightmap(): Heightmap;
+  /** Cheap guard for the heightmap cache: scalars by value, arrays by identity. */
+  private shapeUnchanged;
+  private rememberShape;
   /** The splat layers in effect — theme preset, or `layers` for 'custom'. */
   resolvedLayers(): TerrainLayer[];
   override _syncObject3D(): void;
@@ -2369,6 +2663,16 @@ declare class Water3D extends Node3D implements RenderHook3D, SunConsumer3D {
   reflectionInterval: number;
   /** Depth-texture shoreline foam — rides the always-on fancy scene pass. */
   foam: boolean;
+  /**
+  * How much sky the surface throws back at grazing angles, 0..1 — `null`
+  * keeps the preset's own ceiling.
+  *
+  * Turn it DOWN when the sky is blown out: a bright overcast reflected at 0.78
+  * is a sheet of white, and a pool doing that next to a River3D (which paints
+  * an AUTHORED sky palette and so never blows out) reads as two unrelated
+  * materials meeting at a line. Turn it up for a mirror-calm lake.
+  */
+  reflectivity: number | null;
   /** Bodies crossing the surface emit signals and raise ripples. */
   interaction: boolean;
   /** Splash WHITEWATER: the shaders paint expanding surface foam where bodies
@@ -2475,6 +2779,9 @@ declare class Water3D extends Node3D implements RenderHook3D, SunConsumer3D {
   private readonly mirrorCamera;
   private readonly mirrorMatrix;
   private lastMirrorAt;
+  /** Camera pose the current mirror image was rendered from (see redraw). */
+  private readonly lastMirrorEye;
+  private readonly lastMirrorQuat;
   protected override _createObject3D(): Object3D;
   override update(dt: number): void;
   override _syncObject3D(): void;
@@ -2534,6 +2841,13 @@ declare class Water3D extends Node3D implements RenderHook3D, SunConsumer3D {
   * the still-water level, which is what a caller comparing heights wants.
   */
   heightAt(x: number, z: number): number;
+  /**
+  * @internal Water surface height over a world point, or null outside this
+  * surface's footprint — what scattered vegetation asks before it plants a
+  * blade (see {@link WetSurface}). The STILL level, not the wave: grass does
+  * not come and go with the swash.
+  */
+  _waterYAt(x: number, z: number): number | null;
   /** Base wave height at world (x, z) — the CPU twin of the active shader.
   * Ripples are excluded on purpose: a splash must not re-trigger itself. */
   private waveOffsetAt;
@@ -2649,6 +2963,11 @@ declare class Renderer3D {
   private readonly loadedAssetScenes;
   /** The scene whose GPU programs have been pre-compiled (warm-up, see render). */
   private compiledScene;
+  /** The camera the last frame drew with — what warmUp compiles against. */
+  private warmCamera;
+  /** Set while a caller intends to run {@link warmUp} instead: the first frame
+  * then compiles only what it actually draws, and the rest goes async. */
+  private deferCompile;
   /** Reused per-frame walk scratch (instance-scoped — never a module global). */
   private readonly syncScratch;
   /** Editors set this: keep syncing `static: true` subtrees every frame. */
@@ -2698,6 +3017,20 @@ declare class Renderer3D {
   * grab, the mirror and the bloom chain follow automatically.
   */
   private governResolution;
+  /**
+  * Compile the scene's GPU programs off the critical path.
+  *
+  * The compile itself is unavoidable — a dressed outdoor scene is 40+ programs
+  * and a driver takes hundreds of milliseconds each (measured: SEVEN SECONDS
+  * for this engine's creek template on macOS/Metal). What is avoidable is
+  * doing it in ONE synchronous block, which freezes the tab and leaves a
+  * loading bar with nothing to say.
+  *
+  * Called by `createGame3D` behind the app's loading screen.
+  */
+  /** @internal Tell the next frame to leave the bulk compile to {@link warmUp}. */
+  deferFirstCompile(): void;
+  warmUp(onProgress?: (fraction: number) => void): Promise<void>;
   private render;
   /**
   * Bloom post pass (only when `environment.bloom` is declared). LDR and safe:
@@ -2743,10 +3076,23 @@ declare class Renderer3D {
   */
   pick(sx: number, sy: number): Node | null;
   /**
-  * GPU counters for the LAST rendered frame, straight from three's
-  * per-frame-maintained `renderer.info` (render pass + GPU memory).
+  * GPU counters for the last rendered frame — EVERY pass of it, summed (see
+  * the `info.reset()` in `render`), plus GPU memory.
   */
   stats(): RendererStats;
+  /**
+  * Where the last rendered frame was seen FROM.
+  *
+  * Paired with {@link cameraBasis} this is the view on screen — a third-person
+  * rig, a cutscene camera and the editor's free-fly all answer here, which is
+  * what a mode switch needs to carry across so the cut does not read as a
+  * page load.
+  */
+  lastCameraPosition(): {
+    x: number;
+    y: number;
+    z: number;
+  } | null;
   /** The last rendered camera's world-space basis (for screen-plane dragging). */
   cameraBasis(): {
     right: Vector3;
@@ -2899,4 +3245,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 RiverHit, type RiverRing, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainNav, type TerrainNavOptions, type TerrainTheme, Trail3D, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, buildHeightmap, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, setEnvironment3D, 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 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, Trail3D, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, 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 };