incanto 0.1.0

package/dist/3d.d.ts

@@ -0,0 +1,1860 @@
+import { s as JsonObject } from "./schema-CcoWb32N.js";
+import { C as RendererStats, S as GameStats, T as Node, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-BAQq7HGM.js";
+import { t as LoadSceneOptions } from "./loader-Mo0KghCv.js";
+import { t as ParticleSim } from "./particle-sim-CbN4YUuH.js";
+import { r as SpatialPose } from "./audio-player-DqUR3XFs.js";
+import { AnimationClip, BufferGeometry, Color, DirectionalLight, InstancedMesh, Object3D, PerspectiveCamera, Scene, 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";
+
+//#region src/3d/assets.d.ts
+interface ModelEntry {
+  status: "loading" | "ready" | "error";
+  /** Source scene — GLB instances are CLONED from this; VRM mounts it directly. */
+  scene: Object3D | null;
+  animations: AnimationClip[];
+  isVrm: boolean;
+  /** The live three-vrm runtime (normalized rig, springbones) — VRM only. */
+  vrm: VRM | null;
+  /** VRM scenes mount directly: the node currently displaying this avatar. */
+  claimedBy: object | null;
+  /** Retargeted clips cached per animation-asset reference. */
+  retargeted: Map<string, AnimationClip>;
+  error?: string;
+}
+interface AnimationEntry {
+  status: "loading" | "ready" | "error";
+  clips: AnimationClip[];
+  /** The animation file's own scene — its rest pose drives VRM retargeting. */
+  scene: Object3D | null;
+  /** Optional clip selector from the asset declaration. */
+  clip?: string;
+  error?: string;
+}
+/**
+* GLB/glTF/VRM store for the 3D adapter. Scene `assets` entries:
+*
+*   {type:"model",     url}            → ModelInstance3D `model: "$key"`
+*   {type:"animation", url, clip?}     → ModelInstance3D `animation: "$key"`
+*                                        (clips live in memory, never drawn)
+*
+* Raw URLs also work anywhere a `$key` does. VRM files load through
+* @pixiv/three-vrm (VRM 0.x facing fixed via rotateVRM0).
+*/
+declare class AssetStore3D {
+  private readonly models;
+  private readonly animations;
+  private readonly modelKeys;
+  private readonly animationKeys;
+  private readonly loader;
+  constructor();
+  /** Map a scene's `assets` header. */
+  load(assets: JsonObject): void;
+  /** Animation `$key`s declared by the scene (editor dropdowns). */
+  animationRefs(): string[];
+  modelRefs(): string[];
+  /** Resolve `$key` or URL; kicks off the load on first sight. */
+  getModel(ref: string): ModelEntry;
+  /** Resolve an animation `$key` or URL; clips load into memory only. */
+  getAnimation(ref: string): AnimationEntry;
+  dispose(): void;
+}
+//#endregion
+//#region src/3d/camera-rig.d.ts
+/**
+* Camera rig math for the four classic character views — pure functions so
+* every magic number stays testable. All values mirror vibe-starter-3d's
+* controllers exactly (the agent8 template stack):
+*
+*  free        third-person orbit: pivot = player + eye, cam at -distance
+*              along the yaw/pitch direction, lookAt pivot
+*  firstPerson cam AT the eye pivot, looking along yaw/pitch
+*  quarter     fixed isometric pitch atan(1/√2) ≈ 35.264°, offset
+*              (0, d·sinX, d·cosX), rotation hard-set (no lookAt)
+*  side        cam at (player.x, eye.y, player.z + distance), facing -z
+*/
+type RigView = "free" | "firstPerson" | "quarter" | "side";
+interface RigPose {
+  position: [number, number, number];
+  /** Euler XYZ in RADIANS (Camera3D's rotation prop is degrees — convert). */
+  rotation: [number, number, number];
+}
+declare const QUARTER_PITCH: number;
+declare function rigPose(view: RigView, player: [number, number, number], eyeHeight: number, yaw: number, pitch: number, distance: number): RigPose;
+/** Camera-relative movement: input (x right, y forward) rotated by camera yaw. */
+declare function cameraRelative(x: number, y: number, yaw: number): [number, number, number];
+/** Keyboard intensity model: any direction = 0.6, sprint adds 0.4 (cap 1). */
+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/nodes/node-3d.d.ts
+/**
+* Per-frame hand-off from `Renderer3D` to nodes that need the LIVE WebGL
+* context (cube-camera reflections, depth pre-passes…). `syncTree` collects
+* `_onRender3D` hooks while it walks the tree; the renderer invokes them just
+* before the main render. Headless runs (no Renderer3D) never invoke them —
+* GPU-only features must stay dormant, not crash.
+*/
+interface RenderContext3D {
+  gl: WebGLRenderer;
+  scene: Scene;
+  camera: PerspectiveCamera;
+}
+/**
+* Implement on a Node3D subclass to receive {@link RenderContext3D} once per
+* rendered frame — `syncTree` detects `_onRender3D` structurally, so plain
+* headless trees pay nothing and never invoke it.
+*/
+interface RenderHook3D {
+  /** @internal Called by Renderer3D right before the main render. */
+  _onRender3D(ctx: RenderContext3D): void;
+}
+/**
+* Implement on a Node3D subclass to receive the environment sky's UNIT sun
+* direction once per sync (after the node's own `_syncObject3D`). Contract:
+* apply it ONLY while the node's own sun prop is at its schema default — an
+* explicitly authored prop always wins over the sky.
+*/
+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;
+  position: number[];
+  /** Euler XYZ in degrees. */
+  rotation: number[];
+  scale: number[];
+  visible: boolean;
+  /** Draw-order priority (higher = drawn later / on top). Only affects TRANSPARENT
+  * materials — three sorts the transparent pass by renderOrder, then depth.
+  * Pairs with named scene constants (e.g. `{"@const": "UI"}`) for sorting tiers. */
+  renderOrder: number;
+  private _object3D;
+  /**
+  * @internal Fixed-step render interpolation. A physics body fills these with
+  * its previous and current fixed-step LOCAL positions; `_syncObject3D(alpha)`
+  * lerps the rendered transform between them so motion is smooth between fixed
+  * steps. `null` means "not physics-driven" — render `position` directly.
+  */
+  _interpPrev: number[] | null;
+  _interpCurr: number[] | null;
+  /** @internal The backing three object (lazily created). */
+  _ensureObject3D(): Object3D;
+  /** @internal Override point for subclasses (mesh, camera, light…). */
+  protected _createObject3D(): Object3D;
+  /** @internal Push JSON props onto the backing object. Called every frame.
+  *  `alpha` (0..1) interpolates a physics body between its last two fixed-step
+  *  positions; non-physics nodes ignore it and render `position` directly. */
+  _syncObject3D(alpha?: number): void;
+  override free(): void;
+}
+//#endregion
+//#region src/3d/nodes/bodies-3d.d.ts
+/**
+* Shared base for physics-backed 3D nodes. Colliders are NODE PROPS:
+* `{shape:'box', size:[x,y,z]}` · `{shape:'sphere', radius}` ·
+* `{shape:'capsule', radius, height}` (meters, y-up).
+*/
+declare class PhysicsBody3D extends Node3D {
+  static override readonly props: PropSchema;
+  /** The unified collision model: every collider participant can emit these. */
+  static override readonly signals: readonly string[];
+  collider: JsonObject;
+  /** Loader hook: bad collider shapes fail at LOAD, not at physics start. */
+  static validateJson(node: Node): void;
+  /** @internal Set by Physics3D when the body is created. */
+  _physics: Physics3D | null;
+}
+/** Immovable collider (ground, walls, platforms). */
+declare class StaticBody3D extends PhysicsBody3D {
+  static override readonly typeName: string;
+}
+/** Sensor volume emitting `triggerEnter(other)` / `triggerExit(other)`. */
+declare class Area3D extends PhysicsBody3D {
+  static override readonly typeName: string;
+}
+/** Dynamic simulated body. */
+declare class RigidBody3D extends PhysicsBody3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  mass: number;
+  gravityScale: number;
+  fixedRotation: boolean;
+  friction: number;
+  restitution: number;
+  /** m/s, y-up. Read back every step; write to launch. */
+  linearVelocity: number[];
+  /** @internal set by Physics3D */
+  _physics3d: Physics3D | null;
+  /** World-space impulse (kg·m/s) — the floating-capsule controller's verb. */
+  applyImpulse(impulse: [number, number, number]): void;
+}
+/**
+* Kinematic capsule on Rapier's character controller. Gravity is NOT applied
+* automatically — integrate `velocity` yourself, then `moveAndSlide()` from
+* `fixedUpdate`.
+*/
+declare class CharacterBody3D extends PhysicsBody3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  /** m/s, y-up (up = +y). */
+  velocity: number[];
+  snapToGround: boolean;
+  /** Max climbable slope angle. */
+  slopeLimitDeg: number;
+  /** @internal Updated by Physics3D.moveAndSlide. */
+  _grounded: boolean;
+  moveAndSlide(): void;
+  isOnFloor(): boolean;
+}
+//#endregion
+//#region src/3d/physics/physics-3d.d.ts
+type Rapier = typeof RapierNs;
+interface Physics3DOptions {
+  /** m/s², y-up. Default: scene `physics.gravity`, else [0, -9.81, 0]. */
+  gravity?: [number, number, number];
+}
+/**
+* Enable 3D physics for an engine. Dynamically imports Rapier (compat build)
+* so games without physics never pay its bundle cost. 1 unit = 1 meter, y-up —
+* three's native space, no conversion.
+*/
+declare function enablePhysics3D(engine: Engine, opts?: Physics3DOptions): Promise<Physics3D>;
+/** Per-engine 3D physics world. Same contract as Physics2D. */
+declare class Physics3D {
+  private readonly R;
+  private readonly engine;
+  /** Render collider outlines in the GAME view (renderers pick this up). */
+  debugDraw: boolean;
+  readonly dimension = "3d";
+  private readonly unregisterDebug;
+  private readonly warnedNoCollider;
+  private readonly entries;
+  private readonly byColliderHandle;
+  private readonly world;
+  private readonly events;
+  private readonly kcc;
+  private readonly disconnect;
+  private lastDt;
+  private readonly optsGravity;
+  private lastScene;
+  constructor(R: Rapier, engine: Engine, opts?: Physics3DOptions);
+  /** @internal Driven by engine.fixedUpdated. */
+  step(dt: number): void;
+  /** @internal Called by CharacterBody3D.moveAndSlide (during tree fixedUpdate). */
+  moveAndSlide(node: CharacterBody3D): void;
+  /** Rapier debug segments (meters). Null while debugDraw is off. */
+  debugLines(): Float32Array | null;
+  dispose(): void;
+  private syncBodies;
+  private ensureEntry;
+  /** Apply a world-space impulse to a dynamic body (character controllers). */
+  applyImpulse(node: PhysicsBody3D, impulse: [number, number, number]): void;
+  /** Mass the solver actually uses (collider-derived unless overridden). */
+  massOf(node: PhysicsBody3D): number;
+  /** Current solver velocity (fresher than the node prop mid-step). */
+  velocityOf(node: PhysicsBody3D): [number, number, number];
+  /**
+  * World-space raycast (meters). `exclude` skips that body's collider —
+  * ground probes from inside a capsule need it. `opts.staticOnly` hits ONLY the
+  * fixed/static world (excludes both dynamic AND kinematic bodies): the camera
+  * spring arm uses it so neither a dynamic projectile nor a KINEMATIC enemy
+  * (CharacterBody3D) passing behind the player yanks the camera in.
+  */
+  castRay(origin: [number, number, number], dir: [number, number, number], maxLen: number, exclude?: PhysicsBody3D, opts?: {
+    staticOnly?: boolean;
+  }): {
+    distance: number;
+    normal: [number, number, number];
+    node: PhysicsBody3D | null;
+  } | null;
+}
+//#endregion
+//#region src/3d/create-game.d.ts
+interface KeyboardTarget {
+  addEventListener: (t: string, cb: (e: KeyboardEvent) => void) => void;
+  removeEventListener: (t: string, cb: (e: KeyboardEvent) => void) => void;
+}
+interface CreateGame3DOptions {
+  canvas: HTMLCanvasElement;
+  /** Scene JSON (cloned internally — the same object can boot many games). */
+  scene: unknown;
+  behaviors?: Record<string, BehaviorCtor>;
+  /**
+  * Auto-register the built-in `incanto/gameplay` behaviors (Health, Pickup,
+  * ScoreKeeper, …) — default true. They register BEFORE `behaviors`, so a
+  * same-named user behavior always wins. Set false to ship none of them.
+  */
+  gameplay?: boolean;
+  /** Keyboard source (default: window when available). `false` disables. */
+  keyboard?: KeyboardTarget | false;
+  /** Pointer-look on the canvas (FPS pattern). Default false. */
+  pointer?: boolean | {
+    lockOnClick?: boolean;
+  };
+  /** 'auto' (default): enable Rapier iff the tree has physics bodies. */
+  physics?: "auto" | boolean;
+  /**
+  * On-screen touch controls for the scene's `"touch"` input declarations:
+  * 'auto' (default) shows them on coarse-pointer devices, true forces them,
+  * false disables. They overlay `touchContainer` (default: the canvas's
+  * parent element — give it position: relative).
+  */
+  touch?: "auto" | boolean;
+  touchContainer?: HTMLElement;
+  /** @internal Test seam — replaces `document` for the touch overlay. */
+  _touchDoc?: {
+    createElement(tag: string): HTMLElement;
+  };
+  /**
+  * Mount the runtime debug overlay (`incanto/debug` — explorer/inspector/
+  * logs). Default: false (off), and there is NO URL/query toggle — a deployed
+  * build must never be switchable on by end users. Opt in via `debug`, gated
+  * to development, e.g. `debug: import.meta.env.VITE_INCANTO_DEBUG === '1'`.
+  */
+  debug?: boolean;
+  /** @internal Test seam — replaces `document` for the debug overlay. */
+  _debugDoc?: {
+    createElement(tag: string): HTMLElement;
+  };
+  seed?: number;
+  fixedHz?: number;
+  pixelRatio?: number;
+  resolveScene?: LoadSceneOptions["resolveScene"];
+  /** @internal Test seam — replaces the Renderer3D construction. */
+  _rendererFactory?: (engine: Engine, canvas: HTMLCanvasElement) => GameRenderer;
+  /** @internal Test seam — replaces the rAF scheduler. */
+  _scheduler?: Scheduler;
+}
+/** What createGame needs from a renderer (stats is optional for test stubs). */
+interface GameRenderer {
+  dispose(): void;
+  stats?(): RendererStats;
+}
+interface Game3D {
+  engine: Engine;
+  scene: Scene$1;
+  renderer: GameRenderer;
+  physics: Physics3D | null;
+  /** Engine + renderer perf counters in one read (fps/nodes/triangles/…). */
+  stats(): GameStats;
+  dispose(): void;
+}
+/**
+* One-call 3D boot/teardown — the 3D twin of createGame2D: register → load
+* (engine attached for onReady) → physics (auto) → input → renderer → start.
+*/
+declare function createGame3D(opts: CreateGame3DOptions): Promise<Game3D>;
+//#endregion
+//#region src/3d/environment.d.ts
+/**
+* The 3D `environment` header, parsed and validated — the renderer's
+* "rendering stage". Pure data in, plain data out (NO three imports), so the
+* whole contract tests headlessly:
+*
+* - `sky`: a physical atmosphere (three Sky shader) that also feeds
+*   image-based lighting and the unified sun direction
+* - `fog`: linear distance fog (color defaults to the sky's horizon haze)
+* - `shadows`: shadow-map master switch + quality knobs
+* - `exposure`: ACES tone-mapping exposure dial
+*
+* Everything is renderer-interpreted: scenes without these keys parse to the
+* exact pre-atmosphere defaults (no sky, no fog, exposure 1).
+*/
+interface SkyEnvironment {
+  /** Sun direction (not necessarily unit length — see {@link sunDirectionFromSky}). */
+  sunPosition: [number, number, number];
+  /** Atmospheric haze 0.1–20 (three Sky semantics; 2 ≈ clear day). */
+  turbidity: number;
+  /** Rayleigh scattering ≥ 0 (1 ≈ earth-like blue). */
+  rayleigh: number;
+}
+interface FogEnvironment {
+  /** Hex fog color. */
+  color: string;
+  /** Distance where fog starts, meters. */
+  near: number;
+  /** Distance of full fog, meters. */
+  far: number;
+}
+interface ShadowsEnvironment {
+  /** Shadow map resolution per side. */
+  mapSize: 1024 | 2048;
+  /** Shadow edge softening radius (PCF blur, default 1). */
+  radius: number;
+}
+interface CloudsEnvironment {
+  /** How much of the sky is cloudy, 0..1. */
+  coverage: number;
+  /** Optical thickness multiplier (higher = more opaque/dramatic). */
+  density: number;
+  /** Cloud-base altitude, world Y. */
+  base: number;
+  /** Cloud-top altitude, world Y (> base). */
+  top: number;
+  /** Sunlit cloud color (hex). */
+  color: string;
+  /** Shaded underside color (hex). */
+  shadeColor: string;
+  /** Wind drift speed. */
+  speed: number;
+  /** Feature size in world units (bigger = larger, softer cloud masses). */
+  scale: number;
+}
+interface Environment3DConfig {
+  /** Tone-mapping exposure (ACES), default 1. */
+  exposure: number;
+  /** Physical sky, or null when the scene keeps a flat `background`. */
+  sky: SkyEnvironment | null;
+  /** Linear fog, or null for none. */
+  fog: FogEnvironment | null;
+  /** Volumetric cloud layer (renderer raymarch composite), or null for none. */
+  clouds: CloudsEnvironment | null;
+  /**
+  * `null` = not declared (shadow maps stay available, free until a light
+  * casts), `false` = force-disabled, object = declared ON with quality knobs
+  * (the renderer then makes the scene's main DirectionalLight cast).
+  */
+  shadows: ShadowsEnvironment | false | null;
+}
+/** Parse + hard-validate the 3D slice of a scene's `environment` header. */
+declare function parseEnvironment3D(env: JsonObject | undefined): Environment3DConfig;
+/**
+* elevation/azimuth (degrees) → unit direction. Matches three's Sky example
+* (`Vector3.setFromSphericalCoords`): azimuth 0 = +Z, 90 = +X; elevation 90 =
+* straight up.
+*/
+declare function sunDirectionFromElevationAzimuth(elevationDeg: number, azimuthDeg: number): [number, number, number];
+/** The sky's sun as a UNIT vector — what Water3D/Foliage3D uniforms consume. */
+declare function sunDirectionFromSky(sky: SkyEnvironment): [number, number, number];
+/**
+* A horizon-ish haze color derived from the sky config — the default fog
+* color. Cheap model, judged by eye: clear skies haze blue-grey, turbid skies
+* whiten, and a low sun warms the band toward amber.
+*/
+declare function horizonColorFromSky(sky: SkyEnvironment): string;
+//#endregion
+//#region src/3d/water/underwater.d.ts
+/** Animated caustics — the dancing refracted-light pattern on submerged surfaces. */
+interface CausticsConfig {
+  enabled: boolean;
+  /** Hex tint of the caustic highlights (a bright pale aqua by default). */
+  color: string;
+  /** Brightness of the additive caustic light. */
+  intensity: number;
+  /** World-space frequency: bigger = smaller, busier cells. */
+  scale: number;
+  /** Animation speed multiplier. */
+  speed: number;
+}
+/** Resolved underwater look: fog color, view distance, and the caustics layer. */
+interface UnderwaterConfig {
+  enabled: boolean;
+  /** Hex color of the underwater fog + background (the murk you're submerged in). */
+  color: string;
+  /** Visibility in meters — the fog's far plane (near is fixed tiny). */
+  visibility: number;
+  /** Caustics projected onto submerged surfaces (the floor especially). */
+  caustics: CausticsConfig;
+}
+//#endregion
+//#region src/3d/environment-3d.d.ts
+/**
+* Applies the scene `environment` header to a three scene — the rendering
+* stage Renderer3D delegates to. One instance per renderer; `apply` runs once
+* per frame but re-parses/rebuilds only when the env JSON actually changed.
+*
+* Headless-safe: `gl` is nullable, and everything GPU-bound (PMREM
+* image-based lighting, exposure, shadow-map switches) is skipped without it
+* while the scene-graph side (Sky object, fog, background, ambient) still
+* applies — that's what the node-environment tests assert against.
+*/
+declare class Environment3D {
+  private readonly scene;
+  private readonly ambient;
+  private envKey;
+  private config;
+  private hdriUrl;
+  private hdriTexture;
+  /** @internal The Sky backdrop object (tests reach in). */
+  _sky: Sky | null;
+  private skyKey;
+  private skyEnvKey;
+  private skyEnvTarget;
+  private readonly fog;
+  /** Underwater fog/tint, created lazily the first time the camera submerges. */
+  private underwaterFog;
+  private readonly underwaterBg;
+  constructor(scene: Scene);
+  /** The sky's unit sun direction, or null when no sky is declared. */
+  get sunDirection(): [number, number, number] | null;
+  /** Parsed volumetric-cloud config, or null when no cloud layer is declared. */
+  get clouds(): CloudsEnvironment | null;
+  /** The live scene fog (color/near/far) the cloud composite fades into, or null. */
+  get sceneFog(): {
+    color: Color;
+    near: number;
+    far: number;
+  } | null;
+  /** Apply the env header. Cheap when unchanged; hard-validates on change. */
+  apply(env: JsonObject | undefined, gl: WebGLRenderer | null): void;
+  /**
+  * Per-frame hand-off for the scene's MAIN DirectionalLight (the renderer
+  * passes the brightest one after the sync pass — never auto-created):
+  *
+  * - sky declared → the light's backing object is re-aimed along the sun
+  *   direction (its distance from origin is kept, so the node's `position`
+  *   keeps meaning "how far out the sun sits")
+  * - `shadows` declared truthy → the light casts; env mapSize/radius win,
+  *   and lights that configured nothing themselves get the default ortho box
+  */
+  applySunLight(light: DirectionalLight | null, focus?: {
+    x: number;
+    y: number;
+    z: number;
+  } | null): void;
+  /**
+  * Underwater override (the renderer passes the resolved config from whichever
+  * water the camera is submerged in, or null). When submerged, the scene
+  * switches to a short-range underwater fog + matching background AND the sky
+  * dome is hidden — without that you'd see the bright sky through the surface
+  * and the murk would never read. `null` is a no-op: the per-frame `apply`
+  * already (re)established the normal fog/background/sky, so surfacing restores
+  * the look for free.
+  */
+  applyUnderwater(config: UnderwaterConfig | null): void;
+  private applyHdri;
+  private applySky;
+  private applyFog;
+  dispose(): void;
+}
+//#endregion
+//#region src/3d/nodes/camera-3d.d.ts
+/**
+* A perspective camera. Mark exactly one camera `current: true`; with none
+* marked, the renderer falls back to the first camera in tree order.
+* Aspect ratio is managed by the renderer on resize.
+*/
+declare class Camera3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  fov: number;
+  near: number;
+  far: number;
+  current: boolean;
+  protected override _createObject3D(): Object3D;
+  override _syncObject3D(): void;
+}
+//#endregion
+//#region src/3d/nodes/character-controller-3d.d.ts
+/**
+* The floating-capsule character controller behind every agent8 3D template
+* (vibe-starter-3d parity, same numbers): put it UNDER a dynamic RigidBody3D
+* with a capsule collider and it gives you impulse-based movement with
+* sprint, jump, snappy falls, hover-float ground suspension, an
+* intensity-driven movement state (drives animations), and a camera rig for
+* the four classic views — free orbit, first person, quarter, side.
+*/
+declare class CharacterController3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly signals: readonly string[];
+  static override readonly props: PropSchema;
+  view: RigView;
+  camDistance: number;
+  eyeHeight: number;
+  maxSpeed: number;
+  sprintMultiplier: number;
+  jumpVelocity: number;
+  sprintJumpMultiplier: number;
+  floatHeight: number;
+  mouseLook: boolean;
+  zoomMin: number;
+  zoomMax: number;
+  pitchMin: number;
+  pitchMax: number;
+  /** Spring-arm: pull the orbit camera in front of walls/ground instead of clipping. */
+  cameraCollision: boolean;
+  turnSpeed: number;
+  /** Camera smoothing rate (1-exp(-rate·dt)); side view uses 5. */
+  camLerp: number;
+  moveAction: string;
+  jumpAction: string;
+  sprintAction: string;
+  skinPath: string;
+  /**
+  * Extra yaw added to the move-facing target (degrees) for models whose
+  * native forward is not +z. agent8's base-model IS +z-forward, so the
+  * default is 0; the skin merely STARTS at 180° (vibe-starter mounts the
+  * character facing away from the camera until it first moves).
+  */
+  skinYawOffset: number;
+  /** Camera yaw/pitch in radians (mouse look mutates these). */
+  yaw: number;
+  pitch: number;
+  /** idle | walk | run | fastRun | airborne — drive animations from this. */
+  state: "idle" | "walk" | "run" | "fastRun" | "airborne";
+  grounded: boolean;
+  private get body();
+  override onEnterTree(): void;
+  override fixedUpdate(dt: number): void;
+  override update(dt: number): void;
+  private pivot;
+  private cameraCache;
+  private findCamera;
+}
+//#endregion
+//#region src/3d/vegetation/flower-geometry.d.ts
+/**
+* Procedural flower PLANTS for Flowers3D — real plants like the reference
+* meadow flowers, not confetti quads: a curved stem strip, 2-3 leaf blades
+* low on the stem, and a multi-petal head (5-8 rounded-diamond petals in a
+* shallow cup around a contrasting center disc), with 1-3 blooms clustered
+* per plant at staggered heights.
+*
+* Per VARIETY the geometry is built ONCE (deterministic — no rng; topology
+* and positions are pure functions of the spec) and split into TWO buffers:
+*
+* - `structure`: stems + leaves + center discs, vertex-colored (greens + the
+*   variety's center color) — instanced with a light per-plant jitter tint
+* - `petals`: the petal fans only, white — the per-plant `instanceColor`
+*   carries the palette pick, so one variety renders patches of different
+*   head colors without splitting draw calls
+*
+* The template is ~unit height: the instance matrix's uniform scale supplies
+* the plant height in meters (petal/leaf sizes stay proportionate).
+*/
+declare const FLOWER_VARIETIES: readonly ["daisy", "cosmos", "bellflower"];
+type FlowerVariety = (typeof FLOWER_VARIETIES)[number];
+//#endregion
+//#region src/3d/nodes/flowers-3d.d.ts
+/** Named density presets, plants per m² — the vibe-coding dial (풍성하게 /
+* 듬성듬성 / 없게). Numbers are accepted too. */
+declare const DENSITY_PRESETS: Record<string, number>;
+/** Map a density prop value to plants/m² — presets by name, numbers as-is. */
+declare function resolveFlowerDensity(density: string | number): number;
+/**
+* A first-class flower field: instanced procedural flower PLANTS — curved
+* stems, leaf blades, multi-petal heads with contrasting centers, 1-3 blooms
+* per plant (see vegetation/flower-geometry.ts) — scattered over an XZ
+* `area`, deterministic from the `seed` PROP. Placement is cluster-gathered:
+* whole Voronoi patches bloom together (`clustering`), each patch coherent
+* in variety AND head color, like real meadow flowers.
+*
+* `density` is the vibe dial: `'lush'` (풍성하게), `'sparse'` (듬성듬성,
+* default), `'none'` (없게) or a number in plants/m². Up to 3 `varieties`
+* render as TWO InstancedMeshes each (green structure + palette-tinted
+* petals) — ≤6 draw calls per node. `sway` bobs the heads in a gentle wind
+* via a vertex-shader time uniform; roots never move.
+*
+* Like Foliage3D, the bed lies flat on the node's local XZ plane by default —
+* on rolling terrain either set `drape: true` (each plant roots on a Terrain3D's
+* surface per-instance) or place small patches at flat spots (the meadow theme
+* does the latter for you).
+*/
+declare class Flowers3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  /** 'lush' | 'sparse' | 'none' | plants per m² (load-time check + budget). */
+  density: string | number;
+  /** [x, z] extent in meters, centered on the node. */
+  area: number[];
+  /** Placement seed — the field is identical across runs and machines. */
+  seed: number;
+  /** Unique subset of ['daisy', 'cosmos', 'bellflower'] — ≤6 draw calls
+  * total. `[]` (default) = all three varieties. */
+  varieties: string[];
+  /** Head colors (hex) — patches pick one each. `[]` (default) = the
+  * reference white/yellow/violet trio. */
+  palette: string[];
+  /** Plant height in meters (±25% per-plant jitter; petals scale along). */
+  height: number;
+  /** 0 = uniform scatter … 1 = tight Voronoi patches (default 0.6). */
+  clustering: number;
+  /** Gentle head-bob wind strength — 0 holds still. */
+  sway: number;
+  /** Drape each plant onto a Terrain3D's surface so flowers root on the ground
+  * instead of a flat plane (lets ONE bed cover rolling terrain). */
+  drape: 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;
+  /** Resolved drape target + the bed's world position, set per rebuild. */
+  private drapeTerrain;
+  private drapeWorld;
+  /** Loader hook: bad densities/varieties/palettes fail at LOAD, not render. */
+  static validateJson(node: Node): void;
+  private time;
+  private field;
+  private varietyMeshes;
+  private fieldKey;
+  /** Shared by every material — update(dt) writes, the vertex sway reads. */
+  private readonly timeUniform;
+  private readonly swayUniform;
+  protected override _createObject3D(): Object3D;
+  /** @internal Every variety's mesh pair (tests and tools reach in here). */
+  _varietyMeshes(): {
+    variety: FlowerVariety;
+    structure: InstancedMesh;
+    petals: InstancedMesh;
+  }[];
+  override update(dt: number): void;
+  override _syncObject3D(): void;
+  /** Re-scatter only when a field-shaping prop changed (the JSON IS the field). */
+  private rebuildIfNeeded;
+  /** Resolve the drape target + cache the bed's world position for `bedY`. */
+  private resolveDrape;
+  /** Bed-local Y that roots a plant on the draped terrain (0 = flat). */
+  private bedY;
+  private buildField;
+  private disposeMeshes;
+  override free(): void;
+}
+//#endregion
+//#region src/3d/nodes/foliage-3d.d.ts
+type FoliageKind = "grass" | "flowers" | "reeds";
+type FoliageStyle = "mesh" | "tufts" | "blades" | "simple";
+/**
+* An instanced vegetation field — grass (잔디밭), flowers or reeds — scattered
+* over an XZ `area`, deterministic from the `seed` PROP (never the engine
+* rng) so the same scene JSON grows the identical field on every machine.
+*
+* Four looks, picked by `style`:
+*
+* - `'tufts'` (kind 'grass' only): the ez-tree-demo mechanism — ONE
+*   InstancedMesh of 3-crossed-quad cards (12 vertices each) carrying a
+*   baked multi-blade alpha-cutout texture, per-instance green tints
+*   (`colorA`→`colorB`, clump-coherent, dry patches) and the ported sin·cos
+*   tuft sway. Dozens of overlapping textured fans read as a DENSE meadow
+*   (잔디밭) at a fraction of the instances — the look that per-blade
+*   geometry never reaches at sane budgets.
+*
+* - `'mesh'` (default, kind 'grass' only): the per-blade path — ONE
+*   InstancedMesh where every instance is a REAL tapered blade (7-vertex
+*   strip) curved along a vertex-shader quadratic bezier. 8× the instances
+*   of the other styles (one blade each, still capped at `maxInstances`),
+*   Voronoi-clump shared lean/hue, soil-`groundColor` roots, Blinn-Phong tip
+*   sheen vs `sunDirection`, 2-octave rolling wind gusts, and a
+*   camera-distance LOD (`fadeStart`/`fadeEnd`). Fully opaque — no alpha
+*   sorting. Best up close; pairs with tufts (sparse mesh over a tuft body).
+*
+* - `'blades'` (kind 'grass' only): the ported shader look — TWO
+*   InstancedMeshes of crossed bottom-anchored quads (same instances, second
+*   rotated 90°) whose fragment shader draws 8 procedural SDF blades per
+*   quad with per-blade wind phases, plus a vertex wind ride.
+*
+* - `'simple'`: the legacy look (and the ONLY look for flowers/reeds) — one
+*   InstancedMesh of crossed quads with per-instance colorA→colorB lerp and a
+*   whole-field shear sway (one matrix write per frame).
+*
+* mesh + blades share placement (cluster-noise passes) and the character
+* bend: with `interaction: true` the nearest ≤4 moving bodies
+* (CharacterBody3D / RigidBody3D) push blade tops radially aside. Tufts
+* skip the bend (a card fan has no per-blade tops to push).
+*/
+declare class Foliage3D extends Node3D implements SunConsumer3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  /** Transparent blades draw after water (1) + opaque ground (overrides Node3D's 0). */
+  override renderOrder: number;
+  /** 'grass' | 'flowers' | 'reeds' — picks the blade silhouette. */
+  kind: string;
+  /** 'mesh' (real curved blades) | 'tufts' (ez-tree textured cards) |
+  * 'blades' (SDF quads) | 'simple' — mesh/tufts/blades are grass only. */
+  style: string;
+  /** Tufts style only: which silhouette the card texture bakes — 'grass'
+  * (the dense blade fan, default) or 'fern' (fewer, wider, arching fronds
+  * with leaflet notches — forest undergrowth). */
+  tuftStyle: string;
+  /** [x, z] extent in meters, centered on the node. */
+  area: number[];
+  /** Instances per square meter (mesh style plants 8× — capped at `maxInstances`). */
+  density: number;
+  /** Instance cap (hard ceiling 200_000). */
+  maxInstances: number;
+  /** Base blade height in meters — mesh style additionally scales it 0.55–1.7×
+  * regionally (low-frequency noise: tall patches and short worn patches). */
+  height: number;
+  /** colorA = bottom/lerp-start, colorB = top/lerp-end. Refinement pass 3:
+  * lifted toward the reference's warm sunlit green (the old olives read
+  * dusky under the brighter meadow stage). */
+  colorA: string;
+  colorB: string;
+  /** Mesh style: soil tint at the blade ROOT — pair with the terrain/ground color. */
+  groundColor: string;
+  /** Mesh style: fixed sun for the specular sheen — match the scene's key light. */
+  sunDirection: number[];
+  /** Mesh style LOD: blades start shrinking at this camera distance (meters)… */
+  fadeStart: number;
+  /** …and are gone by this one. */
+  fadeEnd: number;
+  /** Wind strength — 0 disables wind entirely. */
+  sway: number;
+  /** mesh/blades styles: let nearby moving bodies bend the grass. */
+  interaction: boolean;
+  /** Mesh style: carpet fill in (0, 1] — below 1, low-frequency noise carves
+  * dirt patches into the field (default 0.85 ≈ a real meadow's break-up;
+  * 1 = the old wall-to-wall carpet). */
+  coverage: number;
+  /** Mesh style: fraction of instances rendered as small flower heads
+  * (white/yellow/violet), 0–0.2. Default 0.
+  * @deprecated The 5-vertex heads read as confetti — use a `Flowers3D`
+  * node for real flower plants (stems, leaves, multi-petal heads, density
+  * presets). Kept working for existing scenes; generators emit Flowers3D. */
+  flowers: number;
+  /** Placement seed — the field is identical across runs and machines. */
+  seed: number;
+  /** Drape each instance onto a Terrain3D's surface so blades root on the
+  * ground instead of a flat plane (lets ONE field cover rolling terrain). */
+  drape: 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;
+  /** Resolved drape target + the field's world position, set per rebuild. */
+  private drapeTerrain;
+  private drapeWorld;
+  /** Loader hook: bad kinds/styles and degenerate areas fail at LOAD, not at render. */
+  static validateJson(node: Node): void;
+  private time;
+  private pivot;
+  private meshes;
+  private bladesMaterial;
+  private benderSlots;
+  private pickedBenders;
+  private fieldKey;
+  /** Tufts style: the wind uniforms + the baked card texture (disposed here). */
+  private tuftTime;
+  private tuftStrength;
+  private tuftTexture;
+  protected override _createObject3D(): Object3D;
+  /** Whether this field renders the ported procedural-blades shader. */
+  private get isBlades();
+  /** Whether this field renders real bezier-curved blade meshes (the default). */
+  private get isMesh();
+  /** Whether this field renders the ez-tree-demo textured tuft cards. */
+  private get isTufts();
+  /** Mesh/blades share the shader-driven path (uniform wind + benders). */
+  private get isShaderField();
+  /** @internal The primary InstancedMesh (lazily built — tests reach in here). */
+  _field(): InstancedMesh;
+  /** @internal Every InstancedMesh of the field: [quads] or [quads, quads90°]. */
+  _fields(): InstancedMesh[];
+  override update(dt: number): void;
+  override _syncObject3D(): void;
+  /**
+  * @internal Environment-sky sun hand-off (see {@link SunConsumer3D}): the
+  * sky drives the blade sheen ONLY while the `sunDirection` prop sits at its
+  * schema default — an explicit prop wins. Mesh style only (the other
+  * styles have no sun uniform).
+  */
+  _applySunDirection(dir: readonly [number, number, number]): void;
+  /**
+  * Character bend: collect moving bodies in the tree, keep the nearest ≤4
+  * whose reach touches this field. `_syncObject3D` writes them into the
+  * shader's vec4 slots (xyz = world position, w = radius; w 0 = inactive).
+  */
+  private computeBenders;
+  /** Re-scatter only when a field-shaping prop changed (the JSON IS the field). */
+  private rebuildIfNeeded;
+  /** Resolve the drape target + cache the field's world position for `bedY`. */
+  private resolveDrape;
+  /** Field-local Y that roots an instance on the draped terrain (0 = flat). */
+  private bedY;
+  /**
+  * The mesh-style field: ONE InstancedMesh of real tapered blade strips,
+  * cluster-noise placement, clump-coherent per-instance attributes —
+  * `aBlade` (leanX, leanZ, curve, rand), `aClumpHue` and `aDry` — feeding
+  * the bezier vertex shader. Fully opaque: no sorting, no alpha test.
+  *
+  * Refinement pass: `coverage` < 1 drops blades in noise-carved patches
+  * (dirt breaks the carpet), a low-frequency height field scales blades
+  * 0.55–1.7× regionally (tall blades lean/curve harder — droop), `aDry`
+  * mixes dry yellow-green hues in noise patches, and `flowers` > 0 splits a
+  * fraction of instances into a SECOND InstancedMesh of 5-vertex flower
+  * heads (white/yellow/violet per instance).
+  */
+  private buildMeshField;
+  /**
+  * The meadow's flower sprinkle: ONE extra InstancedMesh of 5-vertex flower
+  * heads riding the grass canopy (the matrix y-scale is the stem height; the
+  * head's local y ≈ 1). A standard material keeps fog/shadows/tonemapping
+  * for free, instance colors pick white/yellow/violet deterministically.
+  */
+  private buildFlowerMesh;
+  /**
+  * The tufts field — the ez-tree demo's grass verbatim in spirit: ONE
+  * InstancedMesh of 3-crossed-quad cards, a baked multi-blade alpha-cutout
+  * texture (see tuft-texture.ts for the recon), per-instance green tints
+  * (clump-coherent + dry patches) and the ported sin·cos tuft sway.
+  * MeshStandardMaterial keeps fog/shadows/tonemapping for free.
+  */
+  private buildTuftField;
+  /**
+  * The ported procedural grass: cluster-noise placement, then the SAME
+  * placements into two InstancedMeshes — the second yawed 90° so every slot
+  * renders as a crossed pair — sharing ONE ShaderMaterial (one uniform set).
+  */
+  private buildBladesField;
+  /** The legacy field: uniform scatter, instance colors, one draw call. */
+  private buildSimpleField;
+  private disposeMeshes;
+  override free(): void;
+}
+//#endregion
+//#region src/3d/nodes/lights-3d.d.ts
+/** Sun-style light. Direction comes from the node's rotation. */
+declare class DirectionalLight3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  color: string;
+  intensity: number;
+  castShadow: boolean;
+  /** Half-extent of the directional shadow frustum (template default ±75). */
+  shadowArea: number;
+  shadowMapSize: number;
+  /**
+  * Re-center the shadow frustum on the camera every frame. A directional sun's
+  * shadow map covers a fixed ortho box; in a big roaming world that box must be
+  * huge (and so low-resolution that the player's own shadow nearly vanishes).
+  * With this on, a SMALL `shadowArea` tracks the camera, so contact shadows stay
+  * crisp wherever you go. The renderer supplies the camera position.
+  */
+  shadowFollowsCamera: boolean;
+  protected override _createObject3D(): Object3D;
+  override _syncObject3D(): void;
+}
+/** Point light with a range (Godot's OmniLight3D). */
+declare class OmniLight3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  color: string;
+  intensity: number;
+  /** 0 = unlimited (three `distance` semantics). */
+  range: number;
+  protected override _createObject3D(): Object3D;
+  override _syncObject3D(): void;
+}
+//#endregion
+//#region src/3d/nodes/mesh-instance-3d.d.ts
+type MeshKind = "box" | "sphere" | "capsule" | "plane" | "cylinder" | "gem";
+interface MeshMaterialProps {
+  color?: string;
+  metalness?: number;
+  roughness?: number;
+  emissive?: string;
+  emissiveIntensity?: number;
+  wireframe?: boolean;
+  /** Flat per-face shading — gives faceted meshes (gem!) crisp glints that
+  * sparkle as the mesh turns, instead of a smoothed surface. */
+  flatShading?: boolean;
+  /** 0..1 surface opacity; below 1 turns on transparency (glassy gems, etc.). */
+  opacity?: number;
+  /** Color texture URL (sampled sRGB, tinted by `color`). */
+  map?: string;
+  /** Tangent-space normal map URL (sampled linear). */
+  normalMap?: string;
+  /** Texture tiling [u, v] across the mesh's UVs (both maps; default [1,1]).
+  * Box/plane UVs span 0–1 per face — scale repeat by the face's world size
+  * for worldspace-ish texel density (e.g. a 6×2.5 m wall at one tile per
+  * meter wants `repeat: [6, 2.5]`). */
+  repeat?: [number, number];
+}
+/**
+* A primitive mesh. Intent-level props only:
+* - `mesh`: box | sphere | capsule | plane | cylinder | gem
+* - `size [x,y,z]`: box extents; sphere/gem radius = x; capsule radius = x,
+*   height = y; plane = x·z ground plane (laid flat); cylinder radius = x, height = y
+* - `material`: `{color, metalness, roughness, wireframe, flatShading, opacity,
+*   emissive, emissiveIntensity, map, normalMap, repeat}` — `map`/`normalMap` are
+*   texture URLs loaded lazily (headless-safe: geometry and physics never
+*   wait on them), tiled by `repeat: [u, v]`. `gem` + `flatShading: true` + a low
+*   `roughness` reads as a sparkling faceted jewel (spin it for the sparkle).
+*/
+declare class MeshInstance3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  mesh: string;
+  size: number[];
+  material: MeshMaterialProps;
+  castShadow: boolean;
+  receiveShadow: boolean;
+  /** Loader hook: malformed materials fail at LOAD time, not at render. */
+  static validateJson(node: Node): void;
+  private geometryKey;
+  private textureKey;
+  private loadedTextures;
+  protected override _createObject3D(): Object3D;
+  override _syncObject3D(): void;
+  /** Lazy texture dressing — same headless guard as Tree3D bark: without a
+  * DOM there is no Image decode, so geometry/colors apply and the maps are
+  * skipped. Re-loads only when a texture-shaping key changes. */
+  private syncTextures;
+  private loadTexture;
+  override free(): void;
+}
+//#endregion
+//#region src/3d/nodes/model-instance-3d.d.ts
+/**
+* A GLB/glTF/VRM model. `model` is a `$key` into the scene's assets header
+* ({type:"model", url}) or a direct URL. `targetHeight` (>0) uniformly scales
+* the model to stand that many units tall (`npx incanto-model` reports the raw
+* size). `animation` plays either an EMBEDDED clip name or an animation-asset
+* reference (`"$run"` → {type:"animation"} entry); Mixamo-rigged assets are
+* retargeted automatically onto VRM humanoids (vibe-starter rigmap).
+*
+* GLB instances are skeleton-aware clones (one asset → many nodes). A VRM
+* mounts its SOURCE scene so the humanoid rig and springbones stay live —
+* one node per VRM asset (additional nodes warn and stay empty).
+*/
+declare class ModelInstance3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly signals: readonly string[];
+  static override props: PropSchema;
+  model: string;
+  animation: string;
+  targetHeight: number;
+  castShadow: boolean;
+  /** false = play the clip once, then emit `animationFinished`. */
+  animationLoop: boolean;
+  receiveShadow: boolean;
+  /** Hex colour multiplied into every material — RESKIN one shared GLB into many
+  *  variants (e.g. a sickly-green zombie from the base human). '' = untinted. */
+  tint: string;
+  private store;
+  private entry;
+  private mountedRef;
+  private fittedHeight;
+  private fitGroup;
+  private mixer;
+  private playing;
+  private currentAction;
+  /** action → the `animation` key that played it, so `animationFinished` reports
+  *  the clip that ACTUALLY finished (a crossfaded-away one-shot can finish a few
+  *  frames after `this.animation` already moved on). */
+  private actionKeys;
+  private warnedClaim;
+  /** Per-mesh original (shared) materials, captured at mount so `tint` can always
+  *  re-derive from the source. Our clones are tracked for disposal. */
+  private tintTargets;
+  private tintedClones;
+  private appliedTint;
+  protected override _createObject3D(): Object3D;
+  /** Embedded clip names + the scene's animation `$key`s (editor dropdown). */
+  availableAnimations(): string[];
+  /** Called by the 3D sync pass with the renderer's asset store. */
+  _syncModel(assets: AssetStore3D): void;
+  /** Multiply `tint` into every material — a per-instance reskin of one shared
+  *  GLB (e.g. base human → green zombie). Clones the captured originals (never
+  *  mutates the shared source), disposing prior clones on change. */
+  private applyTint;
+  private syncAnimation;
+  override update(dt: number): void;
+  override onExitTree(): void;
+  private unmount;
+}
+//#endregion
+//#region src/3d/nodes/particles-3d.d.ts
+/**
+* Point-sprite particle emitter — same presets and deterministic sim as
+* Particles2D, in meters (preset distances auto-scale ÷100). `rate: 0` +
+* `burst` one-shots emit `finished`. Spread covers a sphere (`spreadDeg`
+* tilts emission out of the plane too).
+*/
+declare class Particles3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly signals: readonly string[];
+  static override readonly props: PropSchema;
+  preset: string;
+  emitting: boolean;
+  rate: number;
+  burst: number;
+  lifetime: number[];
+  speed: number[];
+  directionDeg: number;
+  spreadDeg: number;
+  gravity: number[];
+  drag: number;
+  sizeStart: number;
+  sizeEnd: number;
+  colorStart: string;
+  colorEnd: string;
+  /** Per-particle base colours sampled by the particle's stable seed (multi-
+  * colour confetti). Empty → the colorStart→colorEnd ramp is used unchanged. */
+  paletteColors: string[];
+  alphaStart: number;
+  alphaEnd: number;
+  /** Per-particle alpha twinkle frequency in Hz (0 = off) — a seed-phased sine
+  * over the particle's age, so each sparkle glitters on its own rhythm. */
+  shimmer: number;
+  blend: string;
+  /** Depth-test against scene geometry (default true). Set false so the effect
+  * isn't depth-occluded by the scene — pair with a high `renderOrder` to also
+  * win the TRANSPARENT draw-order against alpha scenery (e.g. grass blades,
+  * which write depth AND draw after a default-order particle, hiding it). */
+  depthTest: boolean;
+  maxParticles: number;
+  static validateJson(node: Node): void;
+  private sim;
+  private bursted;
+  private finishedEmitted;
+  /** @internal */
+  _ensureSim(): ParticleSim;
+  override update(dt: number): void;
+  /** Restart a one-shot (re-burst + allow finished to fire again). */
+  replay(): void;
+  private points;
+  private positions;
+  private colors;
+  /** Parsed `paletteColors`, reused; rebuilt only when the hex list changes. */
+  private paletteCache;
+  private paletteCacheKey;
+  override _syncObject3D(): void;
+  /** Parse `paletteColors` into a reused `Color[]`, rebuilt only when the hex
+  * list changes (zero per-frame allocation); null when empty so the caller
+  * uses the colorStart→colorEnd ramp. */
+  private refreshPalette;
+  private syncParticles;
+}
+//#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;
+  depth: 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[];
+}
+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"];
+type TerrainTheme = (typeof TERRAIN_THEMES)[number];
+/** Live CDN the agent8 starter terrains splat from — works without any setup.
+* (Lives here so themes can detect it; re-exported by Terrain3D.) */
+declare const DEFAULT_TERRAIN_TEXTURE_BASE = "https://agent8-games.verse8.io/assets/3D/default/textures/terrain";
+/**
+* Resolve a theme to its 3–4 splat layers against a texture CDN base
+* (`<base>/<name>.png` + `<base>/<name>_normal.png`). Height ranges are
+* NORMALIZED 0..1 over the terrain's realized (no-edge-wrap) height span,
+* slope ranges are radians of `atan(|∇h|)`. 'custom' has no preset — the
+* node hard-fails before ever calling this with it.
+*/
+declare function terrainThemeLayers(theme: TerrainTheme, textureBase: string): TerrainLayer[];
+//#endregion
+//#region src/3d/nodes/terrain-3d.d.ts
+/**
+* Procedural heightfield terrain with biome texture splatting — seeded
+* simplex octaves displace a PlaneGeometry once on the CPU, per-vertex
+* height/slope trapezoids pick between 4 biome textures (vertex-color
+* weights, world-UV anti-tiled sampling in a patched MeshStandardMaterial).
+* Ported from the agent8 `vibe-starter-3d-environment` terrain stack.
+*
+* - `theme` presets the splat layers (and the island edge wrap); 'custom'
+*   takes your own `layers`.
+* - `heightAt(x, z)` answers the surface height at WORLD coords — placement,
+*   spawning, AI all read it, headless included (no renderer needed).
+* - Physics: put the terrain UNDER a `StaticBody3D` with
+*   `collider: { shape: 'heightfield' }` — the body pulls this node's grid.
+*
+* Heights realize at roughly 3.5–8× `maxHeight` (the ported pipeline sums
+* noise octaves above zero) — treat `maxHeight` as a scale knob, read the
+* real numbers off `heightAt`.
+*/
+declare class Terrain3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  /** [width, depth] extent in meters, centered on the node. */
+  size: number[];
+  /** Height scale (realized heights land at ~3.5–8× this — see class docs). */
+  maxHeight: number;
+  /** Integer seed — the same seed grows the identical terrain everywhere. */
+  seed: number;
+  /** Grid segments per side (2–128). 128 ≈ 16k vertices, built once. */
+  resolution: number;
+  /** 'island' | 'alpine' | 'plains' | 'desert' | 'custom'. */
+  theme: string;
+  /** Detail-octave persistence — higher = more rugged. */
+  roughness: number;
+  /** Detail octave count. */
+  detail: number;
+  /** Snap-flatten a plateau within ±0.6 m of maxHeight·flatThreshold. */
+  flatThreshold: number;
+  /** Wrap edges down into an island rim. null = theme decides (island: on). */
+  islandEdge: boolean | null;
+  /** Custom splat layers (theme 'custom' only, 1–4 entries). */
+  layers: TerrainLayer[];
+  /** CDN base for theme textures: `<base>/<name>.png` (+`_normal`). */
+  textureBase: string;
+  /** Lake/pond bowls carved into the surface — smooth radial depressions the
+  * collider + heightAt + dressing all see (place a Water3D in each). */
+  basins: BasinSpec[];
+  /** Loader hook: bad themes/layers/grids fail at LOAD, not at render. */
+  static validateJson(node: Node): void;
+  private heightmap;
+  private heightmapKey;
+  private builtKey;
+  private loadedTextures;
+  protected override _createObject3D(): Object3D;
+  /**
+  * Terrain surface height (world y) at WORLD x/z — works headless, before
+  * any render. Ancestor transforms are translation-only (the same contract
+  * physics bodies follow).
+  */
+  heightAt(x: number, z: number): number;
+  /** @internal The pure heightfield (lazily built — physics pulls this). */
+  _heightmap(): Heightmap;
+  /** The splat layers in effect — theme preset, or `layers` for 'custom'. */
+  resolvedLayers(): TerrainLayer[];
+  override _syncObject3D(): void;
+  private effectiveIslandEdge;
+  private segments;
+  /** Rebuild geometry+material only when a terrain-shaping prop changed. */
+  private rebuildIfNeeded;
+  private buildGeometry;
+  private buildMaterial;
+  private disposeTextures;
+  override free(): void;
+}
+//#endregion
+//#region src/3d/vegetation/tree-blueprint.d.ts
+/**
+* Tree3D construction recipes — the pure half of the procedural trees.
+* A (tier, type) pair maps to exact segment/layer/branch counts; the
+* geometry builder consumes these so tests can pin the numbers without
+* touching three.
+*/
+type TreeTier = "simple" | "medium" | "high";
+type TreeType = "conifer" | "broadleaf" | "dead" | "bush";
+//#endregion
+//#region src/3d/nodes/tree-3d.d.ts
+interface TreeVariant {
+  branches: InstancedMesh;
+  /** null for dead trees (leafless recipes). */
+  leaves: InstancedMesh | null;
+}
+/**
+* Procedural trees grown by the ported ez-tree generator (recursive gnarled
+* branches + textured leaf billboards) — one node is a whole grove in ≤6
+* draw calls: up to 3 seed VARIANTS, each one branches-InstancedMesh plus
+* one leaves-InstancedMesh, with `count` instances scattered over an XZ
+* `area` and distributed among the variants.
+*
+* `type` picks the recipe family: 'conifer' → pine whorls, 'broadleaf' →
+* oak/ash/aspen rotation, 'dead' → bare branches, no leaves, 'bush' → the
+* ported bush_1 shrub (undergrowth — pair with height 2–4). `tier` picks
+* the cost: 'simple' keeps the original primitive low-poly trees (cheapest,
+* unchanged), 'medium' grows the light `*-forest` presets (≤3k tris/tree —
+* forests), 'high' the full presets (8–20k tris/tree — hero trees).
+* validateJson enforces count × tris/tree ≤ 1.5M at LOAD time.
+*
+* Everything is deterministic from the `seed` PROP (never the engine rng):
+* the same scene JSON grows the identical grove on every machine. Leaves are
+* alpha-cutout quads (MeshStandardMaterial) sampling the packaged ez-tree
+* textures, riding a ported simplex-wind vertex sway on medium+.
+*/
+declare class Tree3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  /** 'simple' (primitive low-poly) | 'medium' (light ez-trees) | 'high' (full). */
+  tier: string;
+  /** 'conifer' | 'broadleaf' | 'dead' | 'bush' — the recipe family. */
+  type: string;
+  /** Construction seed — identical grove across runs and machines. */
+  seed: number;
+  /** Tree height in meters (each instance jitters ±20%). */
+  height: number;
+  /** Instances — count > 1 turns the node into a forest patch. */
+  count: number;
+  /** [x, z] scatter extent in meters when count > 1, centered on the node. */
+  area: number[];
+  trunkColor: string;
+  /** Leaf/canopy tint — hue is kept, value is normalized over leaf textures. */
+  canopyColor: string;
+  /** Override the leaf texture URL ('' = packaged per-type ez-tree texture). */
+  leafTexture: string;
+  /** Leaf LOD: leaf cards begin collapsing toward their branch at this camera
+  * distance (m). 0 (with leafFadeEnd 0) disables LOD — full leaves at any range. */
+  leafFadeStart: number;
+  /** Leaf LOD: cards are fully collapsed (zero overdraw) by here — tune near the
+  * scene fog far so the thinning hides in fog. leafFadeEnd > leafFadeStart to enable. */
+  leafFadeEnd: number;
+  /** Let leaves cast shadows. false keeps trunk/branch shadows but drops the
+  * expensive alpha-cutout leaf shadow pass (the dappled floor) for big FPS. */
+  leafShadows: boolean;
+  /** Drape the grove over a Terrain3D: each scattered instance roots at the
+  * ground height under it (not the node's single Y), so a patch on rolling or
+  * carved terrain never floats/buries. No effect on a count:1 tree placed by
+  * hand unless it sits off the ground. */
+  drape: boolean;
+  /** Node path to the Terrain3D to drape onto ('' = auto-find the first one). */
+  terrain: string;
+  /** Resolved drape target + the grove's world position, set per rebuild. */
+  private drapeTerrain;
+  private drapeWorld;
+  /** Loader hook: bad tiers/types/counts/budgets fail at LOAD, not at render. */
+  static validateJson(node: Node): void;
+  private time;
+  private grove;
+  private variants;
+  private simpleTrunk;
+  private simpleCanopy;
+  private swayUniform;
+  private leafFadeUniform;
+  private loadedTextures;
+  private groveKey;
+  protected override _createObject3D(): Object3D;
+  /** @internal First branches/trunk InstancedMesh (tests reach in here). */
+  _trunk(): InstancedMesh;
+  /** @internal First canopy/leaves InstancedMesh — null for dead trees. */
+  _canopy(): InstancedMesh | null;
+  /** @internal Every grown variant (medium/high tiers; empty for 'simple'). */
+  _variantMeshes(): TreeVariant[];
+  override update(dt: number): void;
+  override _syncObject3D(): void;
+  /** Re-grow only when a grove-shaping prop changed (the JSON IS the grove). */
+  private rebuildIfNeeded;
+  /** Resolve the drape target + cache the grove's world position for `bedY`. */
+  private resolveDrape;
+  /** Grove-local Y that roots an instance on the draped terrain (0 = flat). */
+  private bedY;
+  /** The original primitive trees — the cheap path, byte-for-byte unchanged. */
+  private buildSimpleGrove;
+  /** The ported ez-tree grove: K seed variants, instances dealt round-robin. */
+  private buildEzGrove;
+  /**
+  * Trunk/branch dressing. Dead trees stay barkless weathered gray (flat
+  * `trunkColor` — bark long gone from a snag); live medium/high trees
+  * sample the packaged ez-tree bark set (color + normal + roughness, 1k)
+  * tiled by the upstream per-preset repeat over the generator's ring UVs —
+  * ridged bark up close instead of smooth plastic. The default `trunkColor`
+  * hands the tint to the upstream preset (the maps carry the color); a
+  * customized prop keeps its hue max-channel-normalized so it TINTS the map
+  * instead of multiplying brown×brown into mud.
+  */
+  private buildBarkMaterial;
+  private loadBarkTexture;
+  /** Per-instance placement + jitter — ONE rng draw order for both paths. */
+  private scatter;
+  private disposeMeshes;
+  override free(): void;
+}
+//#endregion
+//#region src/3d/nodes/voxel-grid-3d.d.ts
+/**
+* Face colors per tile (front,right,back,left,top,bottom) — the agent8
+* minecraft template's exact 26-entry palette (tile 1 = grass, 2 = dirt,
+* 5 = bedrock, …). Override per-scene via the `palette` prop.
+*/
+declare const VOXEL_PALETTE: number[][][];
+interface VoxelBlock {
+  x: number;
+  y: number;
+  z: number;
+  tile: number;
+}
+/**
+* A whole voxel terrain in ONE draw call: an InstancedMesh of unit cubes
+* with per-face instanced colors, simple directional shading and darkened
+* edges — the minecraft-template look. Blocks are runtime data
+* (`setBlocks`/`addBlock`) or baked scene JSON via the `voxels` prop
+* (`[[x,y,z,tile], …]` — what `incanto-env terrain` emits), applied on the
+* next update; runtime edits take over from there. Colliders are the
+* GAME's job (chunked trimeshes near the player — see the minecraft
+* template's Terrain behavior).
+*/
+declare class VoxelGrid3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly signals: readonly string[];
+  static override readonly props: PropSchema;
+  /** JSON-authored blocks as [x, y, z, tile] tuples (generated terrains bake these). */
+  voxels: number[][];
+  private appliedVoxels;
+  private readonly map;
+  private mesh;
+  private dirty;
+  blockCount(): number;
+  tileAt(x: number, y: number, z: number): number | undefined;
+  setBlocks(blocks: VoxelBlock[]): void;
+  addBlock(b: VoxelBlock): void;
+  removeBlockAt(x: number, y: number, z: number): boolean;
+  /** All blocks (for chunk collider builders). */
+  blocks(): VoxelBlock[];
+  protected override _createObject3D(): Object3D;
+  override update(): void;
+}
+//#endregion
+//#region src/3d/water/interaction.d.ts
+/**
+* Water3D character interaction — pure functions, no three, node-env testable.
+*
+* The node samples physics bodies each update, detects waterline crossings
+* (`detectCrossings`), and converts them into ripple impulses in a FIXED-SIZE
+* ring buffer that mirrors the shader's `uRipples[8]` uniform array
+* (`pushRipple` / `ageRipples`). `rippleHeight` is the exact ring-wave shape
+* the vertex shader evaluates — `quality: 'simple'` runs it on the CPU.
+*/
+/** Ring-buffer capacity — MUST match `uRipples[8]` in the water shaders. */
+declare const WATER_MAX_RIPPLES = 8;
+/** One expanding ring wave, in world XZ. */
+interface Ripple {
+  x: number;
+  z: number;
+  /** Seconds since impact (real time — waveSpeed does not stretch ripples). */
+  age: number;
+  /** Impulse amplitude in meters. */
+  amp: number;
+  /** Splash-foam strength 0..1 the shaders paint as surface froth (omitted = 0). */
+  foam?: number;
+}
+//#endregion
+//#region src/3d/nodes/water-3d.d.ts
+/**
+* A water surface on XZ. `quality: 'fancy'` (default) is a commercial-grade
+* water shader — 9-iteration simplex FBM displacement with analytic normals,
+* two animated procedural detail-normal layers (`detailStrength`), a sun
+* specular glint+sheen (`sunDirection`/`sunColor`/`sunIntensity`), Beer's-law
+* depth `absorption` (clear shallows → dark depths), screen-space
+* `refraction` of the submerged scene, depth-texture shoreline `foam` (on by
+* default), a trough/surface/peak color ramp and fresnel-mixed CubeCamera
+* reflections (re-rendered every `reflectionInterval` ms). `quality:
+* 'simple'` is the cheap CPU sine-wave material (low-end fallback; also the
+* deterministic headless path).
+*
+* Per-frame GPU budget for fancy (beyond drawing the surface): ONE half-res
+* scene pre-pass that feeds depth (absorption/foam/soft intersections) AND
+* the refraction color grab; the cube reflection stays on its `1000 ms`
+* throttle.
+*
+* Character interaction (`interaction: true`): each update the node scans the
+* tree for CharacterBody3D/RigidBody3D, compares their world y against the
+* waterline at their xz (wave offset included, CPU twin of the shader), emits
+* `entered`/`exited` with the body node, and pushes ripple impulses into a
+* fixed 8-slot ring buffer both shaders turn into expanding ring waves. The
+* surface has no bottom — anything below the waterline inside the XZ
+* footprint counts as in-water (pair with `Area3D` for volumetric gameplay).
+*
+* GPU-only features (reflection/foam) run through the renderer's
+* `_onRender3D` hand-off — headless runs simply never invoke it.
+*/
+declare class Water3D extends Node3D implements RenderHook3D, SunConsumer3D {
+  static override readonly typeName: string;
+  static override readonly signals: readonly string[];
+  static override readonly props: PropSchema;
+  /** [width, depth] in meters (the surface lies on XZ). */
+  size: number[];
+  /** Legacy single hue: simple-quality color; tints the fancy ramp when set. */
+  color: string;
+  opacity: number;
+  /** Draw after opaque geometry (overrides Node3D's 0 default). */
+  override renderOrder: number;
+  /** Wave intensity dial, meters-ish. 0 = mirror-flat; 0.04 (default) reads
+  * as a calm sea; 0.08 = the noisier ported-source look. */
+  waveHeight: number;
+  waveSpeed: number;
+  /** 'fancy' shader water (default) | 'simple' cheap CPU sine material. */
+  quality: string;
+  /** Fancy ramp overrides: `{trough?, surface?, peak?}` hex strings. */
+  colors: JsonObject;
+  /** CubeCamera reflections (fancy only; needs a live renderer). */
+  reflection: boolean;
+  /** ms between reflection (and foam depth) re-renders. */
+  reflectionInterval: number;
+  /** Depth-texture shoreline foam — rides the always-on fancy scene pass. */
+  foam: boolean;
+  /** Bodies crossing the surface emit signals and raise ripples. */
+  interaction: boolean;
+  /** Splash WHITEWATER: the shaders paint expanding surface foam where bodies
+  * interact — a "풍덩" froth bloom on entry (scaled by fall speed) and a foam
+  * trail ("물살") behind a body wading/running through. Needs `interaction`. */
+  splash: boolean;
+  /** Fixed sun for the specular glint — match the scene's key light. */
+  sunDirection: number[];
+  /** Sun glint/sheen tint. */
+  sunColor: string;
+  /** Sun glint/sheen strength — 0 disables the specular entirely. */
+  sunIntensity: number;
+  /** Animated detail-normal strength — the close-up liquid feel (0 = off). */
+  detailStrength: number;
+  /** Beer's-law absorption per meter of water depth (0 = no depth tinting).
+  * Per-channel under the hood: red dies ~3× faster than blue, so shallows
+  * over a bright bottom read turquoise before fading to deep blue. */
+  absorption: number;
+  /** Screen-space refraction of the submerged scene (fancy only). */
+  refraction: boolean;
+  /**
+  * Submerged-camera look: when the camera dips below this surface (inside its
+  * XZ footprint) the scene switches to an underwater fog + tint for that frame
+  * — the murky, limited-visibility feel of being underwater. `true` (default)
+  * derives the murk from `color`; `false` disables it; an object
+  * `{ color?, visibility? }` overrides the fog hue / view distance (meters).
+  */
+  underwater: boolean | JsonObject;
+  /** Loader hook: degenerate planes and bad enums fail at LOAD, not at render. */
+  static validateJson(node: Node): void;
+  private time;
+  private surfaceKey;
+  /** @internal Live ripple ring buffer (≤8) — tests and tools read this. */
+  readonly _ripples: Ripple[];
+  private inWater;
+  private readonly bobTimers;
+  /** Last position a wake ripple was dropped, per in-water body (for the trail). */
+  private readonly wadeAnchors;
+  private readonly _scratchA;
+  private readonly _scratchB;
+  private readonly _bodies;
+  private cubeTarget;
+  private cubeCamera;
+  /** Reflection near plane (max half extent) — recreate the camera on resize. */
+  private reflectionNear;
+  private lastReflectionAt;
+  /** Per-frame scene pre-pass: depth (absorption/foam) + color grab (refraction). */
+  private scenePassTarget;
+  protected override _createObject3D(): Object3D;
+  override update(dt: number): void;
+  override _syncObject3D(): void;
+  /**
+  * @internal Renderer hand-off (see {@link RenderContext3D}): re-render the
+  * CubeCamera reflection every `reflectionInterval` ms, plus ONE per-frame
+  * half-res scene pre-pass whose depth texture drives Beer's-law absorption,
+  * shoreline foam and soft intersections, and whose color texture is the
+  * refraction grab — one extra render feeds all three.
+  */
+  _onRender3D(ctx: RenderContext3D): void;
+  /**
+  * Camera-submersion query (the renderer asks every water node each frame): the
+  * resolved underwater look + this surface's Y when the camera EYE is below
+  * THIS surface inside its XZ footprint, else null. Deliberately gated to the
+  * eye being underwater (not merely near the surface) so wading with the camera
+  * above the water never tints the view. Cheap above water (geometric test first).
+  */
+  underwaterAt(camX: number, camY: number, camZ: number): (UnderwaterConfig & {
+    surfaceY: number;
+  }) | null;
+  override free(): void;
+  /** Swap geometry+material only when a surface-shaping prop changed. */
+  private rebuildSurfaceIfNeeded;
+  private buildFancyMaterial;
+  /** The cheap lake ShaderMaterial — fresnel sky tint + ripple normals + sun
+  * glint + edge fade, NO scene re-renders (see lake.ts). */
+  private buildLakeMaterial;
+  private syncFancy;
+  /**
+  * @internal Environment-sky sun hand-off (see {@link SunConsumer3D}): the
+  * sky's sun drives the glint ONLY while the `sunDirection` prop sits at its
+  * schema default — an explicitly authored prop always wins. Runs right
+  * after `_syncObject3D` (which wrote the prop value), overwriting the
+  * uniform for this frame.
+  */
+  _applySunDirection(dir: readonly [number, number, number]): void;
+  /** The fancy three-color ramp; a customized legacy `color` tints it. */
+  private resolvePalette;
+  private syncSimple;
+  private stepInteraction;
+  /** 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;
+}
+//#endregion
+//#region src/3d/register.d.ts
+/**
+* Register the 3D node taxonomy (and the core nodes). Call once in your game
+* entry before loading a 3D scene. Explicit — never an import side effect.
+*/
+declare function registerNodes3D(): void;
+//#endregion
+//#region src/3d/renderer.d.ts
+interface Renderer3DOptions {
+  canvas: HTMLCanvasElement;
+  engine: Engine;
+  /** Bring your own model store (custom loader) — defaults to a GLTF+VRM one. */
+  assets?: AssetStore3D;
+  /** Defaults to `window.devicePixelRatio` capped at 2. */
+  pixelRatio?: number;
+}
+/**
+* WebGL presentation layer: subscribes to `engine.updated`, mirrors the active
+* scene's node tree onto a three.js scene, applies the scene `environment`
+* header (ambient/background/sky/fog/shadows/exposure — see Environment3D),
+* and renders with the current Camera3D under ACES filmic tone mapping.
+*
+* Keep this class thin — everything testable lives in `syncTree`, the node
+* classes and `Environment3D`; this file is the only place that touches WebGL.
+*/
+declare class Renderer3D {
+  /**
+  * When set, the render uses THIS free camera instead of the scene's active
+  * Camera3D — tooling (the scene editor) orbits/pans without touching scene
+  * data. `null` restores normal camera behavior.
+  */
+  viewOverride: {
+    position: [number, number, number];
+    target: [number, number, number];
+  } | null;
+  private readonly overrideCam;
+  private lastCamera;
+  private lastSize;
+  private readonly webgl;
+  private readonly threeScene;
+  private readonly environment;
+  private readonly engine;
+  private readonly disconnect;
+  private readonly canvas;
+  private readonly assets;
+  private readonly ownsAssets;
+  private readonly loadedAssetScenes;
+  /** The scene whose GPU programs have been pre-compiled (warm-up, see render). */
+  private compiledScene;
+  /** Reused per-frame walk scratch (instance-scoped — never a module global). */
+  private readonly syncScratch;
+  /** Reused render-hook context — gl/scene are stable, camera reassigned/frame. */
+  private renderCtx;
+  /** Underwater caustics pass (lazy — only created the first time submerged). */
+  private causticsTarget;
+  private causticsScene;
+  private causticsUniforms;
+  /** Volumetric cloud pass (lazy — only created when environment.clouds is set).
+  * The raymarch runs at HALF resolution into `cloudsHalfTarget`, then a cheap
+  * full-res composite blends it over the scene — keeps the heavy fullscreen
+  * raymarch off the critical path so it holds 60fps at retina. */
+  private cloudsTarget;
+  private cloudsHalfTarget;
+  private cloudsBlurTarget;
+  private cloudsScene;
+  private cloudsUniforms;
+  private cloudsBlurScene;
+  private cloudsBlurUniforms;
+  private cloudsCompositeScene;
+  private cloudsCompositeUniforms;
+  constructor(opts: Renderer3DOptions);
+  private readonly debugLines;
+  private syncDebugLines;
+  private render;
+  /**
+  * Volumetric cloud pass (only when `environment.clouds` is declared — scenes
+  * without it render exactly as before, zero cost). Three steps:
+  *   1. scene → full-res offscreen target (color + depth)
+  *   2. raymarch the cloud slab → HALF-res target (the heavy fullscreen work,
+  *      run at ¼ the pixels so it holds 60fps even at retina)
+  *   3. composite the half-res cloud buffer over the full-res scene → screen
+  */
+  private renderWithClouds;
+  /**
+  * Underwater caustics pass (only while submerged — normal rendering never
+  * touches this). Render the scene to an offscreen color+depth target, then a
+  * fullscreen composite that reconstructs each pixel's WORLD position from depth
+  * and adds an animated caustic highlight below the water line. World-keyed, so
+  * the pattern sticks to the floor/props instead of being a flat screen overlay.
+  */
+  private renderWithCaustics;
+  /**
+  * Project a world point through the LAST rendered camera to canvas CSS px.
+  * `behind` is true when the point sits behind the camera (don't draw it).
+  */
+  screenFromWorld(wx: number, wy: number, wz: number): {
+    x: number;
+    y: number;
+    behind: boolean;
+  };
+  /**
+  * The node rendered under canvas pixel (sx, sy), or null — raycasts the last
+  * rendered camera into the scene and resolves the hit up to its `incantoNode`
+  * (every Node3D stamps that in `_ensureObject3D`). 3D depth-sorts, so the
+  * nearest hit wins. Mirrors `Renderer2D.pick` for click-to-select in the editor.
+  */
+  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).
+  */
+  stats(): RendererStats;
+  /** The last rendered camera's world-space basis (for screen-plane dragging). */
+  cameraBasis(): {
+    right: Vector3;
+    up: Vector3;
+    forward: Vector3;
+  };
+  dispose(): void;
+}
+//#endregion
+//#region src/3d/sync.d.ts
+/** A node that accepts a per-frame spatial pose (AudioPlayer with spatial on). */
+interface SpatialConsumer {
+  spatial: boolean;
+  _setSpatialPose(pose: SpatialPose): void;
+}
+interface SyncResult {
+  activeCamera: PerspectiveCamera | null;
+  /**
+  * Nodes that declared `_onRender3D`, in tree order — Renderer3D invokes
+  * `node._onRender3D(ctx)` with the live WebGL context right before the main
+  * render. Node refs (not bound closures) so the per-frame walk allocates
+  * nothing; the renderer owns and reuses the context object.
+  */
+  renderHooks: RenderHook3D[];
+  /**
+  * The scene's MAIN directional light (highest intensity, tree order breaks
+  * ties) — the environment sky aims it and `environment.shadows` makes it
+  * cast. null when the scene declares none (never auto-created).
+  */
+  sunLight: DirectionalLight3D | null;
+}
+/**
+* Per-frame walk scratch — the caller (Renderer3D) owns ONE and reuses it every
+* frame so `syncTree` allocates nothing for its containers. Instance-scoped (a
+* field on the renderer), never a module global. Omit it and `syncTree` makes a
+* throwaway one (the test path).
+*/
+interface SyncScratch {
+  visited: Set<Object3D>;
+  cameras: Camera3D[];
+  renderHooks: RenderHook3D[];
+  emitters: Array<{
+    node: Node & SpatialConsumer;
+    parent: Object3D;
+  }>;
+  state: WalkState;
+}
+interface SyncOptions {
+  assets?: AssetStore3D;
+  /**
+  * The environment sky's unit sun direction. Pushed to every
+  * `_applySunDirection` node (Water3D, Foliage3D) right after its own sync —
+  * a per-frame cheap setter, chosen over sceneChanged-time wiring because the
+  * walk already touches every node and uniforms are overwritten by node sync
+  * each frame anyway. Nodes ignore it when their own prop was customized.
+  */
+  sunDirection?: readonly [number, number, number] | null;
+  /** Render interpolation factor (0..1) for fixed-step physics bodies; see
+  *  Engine.interpolationAlpha. Defaults to 1 (render the current transform). */
+  alpha?: number;
+}
+/**
+* Mirror an Incanto node tree onto a three.js scene (dirty-push, once per frame):
+*
+* - every Node3D's backing Object3D is parented under its nearest Node3D
+*   ancestor's object (plain Nodes are transparent), falling back to the scene
+* - transforms/props are pushed via `_syncObject3D`
+* - backing objects whose nodes left the tree are pruned
+* - returns the active camera (`current: true` wins, else first in tree order)
+*
+* Pure scene-graph math — no WebGL — so it tests headlessly with real three.
+*/
+declare function syncTree(root: Node, threeScene: Scene, assets?: AssetStore3D, opts?: SyncOptions, scratch?: SyncScratch): SyncResult;
+interface WalkState {
+  visited: Set<Object3D>;
+  cameras: Camera3D[];
+  renderHooks: RenderHook3D[];
+  emitters: Array<{
+    node: Node & SpatialConsumer;
+    parent: Object3D;
+  }>;
+  assets: AssetStore3D | undefined;
+  sunDirection: readonly [number, number, number] | null;
+  sunLight: DirectionalLight3D | null;
+  alpha: number;
+}
+//#endregion
+export { Area3D, AssetStore3D, Camera3D, CharacterBody3D, CharacterController3D, type CreateGame3DOptions, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, type Environment3DConfig, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, type FlowerVariety, Flowers3D, type FogEnvironment, Foliage3D, type FoliageKind, type FoliageStyle, type Game3D, type Heightmap, type HeightmapOptions, 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, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainTheme, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_MAX_RIPPLES, Water3D, buildHeightmap, cameraRelative, createGame3D, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers };