@selvajs/visualization 1.0.0-beta.0 → 1.0.0-beta.2

package/dist/render.d.cts

@@ -1,50 +1,52 @@
-import * as THREE from 'three';
-import { L as Look, a as LookPreset, M as MaterialAppearanceOptions } from './types-CdF9R3qA.cjs';
-export { b as LOOKS } from './types-CdF9R3qA.cjs';
-import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
-
+import { i as MaterialAppearanceOptions, n as Look, r as LookPreset, t as LOOKS } from "./types-Di80Y609.cjs";
+import * as THREE from "three";
+import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+import "three/addons/renderers/CSS2DRenderer.js";
+//#region src/shared/errors.d.ts
 /**
  * Errors for the visualization package. Replaces `@selvajs/compute`'s `RhinoComputeError`, which
  * mis-named failures on paths (e.g. the plugin WebSocket) that never touch Rhino.Compute. `code`
  * values match compute's so existing catch-sites keep working.
  */
 declare const ErrorCodes: {
-    /** Structural check failed: bad magic bytes, out-of-window index, malformed metadata. */
-    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
-    readonly INVALID_STATE: "INVALID_STATE";
-    /** No `DecompressionStream`, no WebGL context, etc. */
-    readonly ENVIRONMENT_ERROR: "ENVIRONMENT_ERROR";
-    readonly INVALID_CONFIG: "INVALID_CONFIG";
-    /** Base64 input could not be decoded. */
-    readonly ENCODING_ERROR: "ENCODING_ERROR";
-    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+  /** Structural check failed: bad magic bytes, out-of-window index, malformed metadata. */
+  readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+  readonly INVALID_STATE: "INVALID_STATE";
+  /** No `DecompressionStream`, no WebGL context, etc. */
+  readonly ENVIRONMENT_ERROR: "ENVIRONMENT_ERROR";
+  readonly INVALID_CONFIG: "INVALID_CONFIG";
+  /** Base64 input could not be decoded. */
+  readonly ENCODING_ERROR: "ENCODING_ERROR";
+  readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
 };
 type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
 declare class VisualizationError extends Error {
-    readonly code: ErrorCode;
-    readonly context?: Record<string, unknown>;
-    readonly originalError?: Error;
-    constructor(message: string, code?: ErrorCode, options?: {
-        context?: Record<string, unknown>;
-        originalError?: Error;
-    });
+  readonly code: ErrorCode;
+  readonly context?: Record<string, unknown>;
+  readonly originalError?: Error;
+  constructor(message: string, code?: ErrorCode, options?: {
+    context?: Record<string, unknown>;
+    originalError?: Error;
+  });
 }
-
+//#endregion
+//#region src/shared/logger.d.ts
 /**
  * Logging facility for the visualization package. Deliberately local rather than imported from
  * `@selvajs/compute` (logging isn't a compute concern). Mirrors compute's logger shape so a host
  * wanting one sink for both can call `setLogger(computeLogger.getLogger())`.
  */
 interface Logger {
-    debug(message: string, ...args: unknown[]): void;
-    info(message: string, ...args: unknown[]): void;
-    warn(message: string, ...args: unknown[]): void;
-    error(message: string, ...args: unknown[]): void;
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
 }
 declare function getLogger(): Logger;
 declare function setLogger(logger: Logger | Console | null): void;
 declare function enableDebugLogging(): void;
-
+//#endregion
+//#region src/shared/looks.d.ts
 /** The look applied when the caller passes no `look` option. */
 declare const DEFAULT_LOOK: Look;
 /**
@@ -57,209 +59,206 @@ declare const DEFAULT_LOOK: Look;
 declare const LOOK_PRESETS: Record<Look, LookPreset>;
 /** Baked at parse time (not toggleable at runtime). */
 declare function materialAppearanceForLook(look: Look): MaterialAppearanceOptions;
-
+//#endregion
+//#region src/render/types.d.ts
 type CameraConfig = {
-    position?: THREE.Vector3;
-    fov?: number;
-    near?: number;
-    far?: number;
-    target?: THREE.Vector3;
-    /**
-     * Refit the near plane to the camera↔content gap every frame (default true) — recovers
-     * depth-buffer precision when zoomed out, preventing distant z-fighting. `near` is only ever
-     * raised, never lowered below the configured value.
-     */
-    dynamicNear?: boolean;
+  position?: THREE.Vector3;
+  fov?: number;
+  near?: number;
+  far?: number;
+  target?: THREE.Vector3;
+  /**
+   * Refit the near plane to the camera↔content gap every frame (default true) — recovers
+   * depth-buffer precision when zoomed out, preventing distant z-fighting. `near` is only ever
+   * raised, never lowered below the configured value.
+   */
+  dynamicNear?: boolean;
 };
 type LightingConfig = {
-    enableSunlight?: boolean;
-    sunlightIntensity?: number;
-    sunlightPosition?: THREE.Vector3;
-    ambientLightColor?: THREE.Color;
-    ambientLightIntensity?: number;
-    sunlightColor?: THREE.Color | number;
-    /**
-     * Direction-aware fill (sky color above, ground color below) so surfaces facing away from the
-     * sun don't collapse to black under a dark HDR. Default false — enabling it shifts the look.
-     */
-    enableHemisphereLight?: boolean;
-    /** Default white. */
-    hemisphereSkyColor?: THREE.Color | number;
-    /** Default a mid grey. */
-    hemisphereGroundColor?: THREE.Color | number;
-    /** Default 0.6. Only applies when {@link LightingConfig.enableHemisphereLight}. */
-    hemisphereIntensity?: number;
+  enableSunlight?: boolean;
+  sunlightIntensity?: number;
+  sunlightPosition?: THREE.Vector3;
+  ambientLightColor?: THREE.Color;
+  ambientLightIntensity?: number;
+  sunlightColor?: THREE.Color | number;
+  /**
+   * Direction-aware fill (sky color above, ground color below) so surfaces facing away from the
+   * sun don't collapse to black under a dark HDR. Default false — enabling it shifts the look.
+   */
+  enableHemisphereLight?: boolean;
+  /** Default white. */
+  hemisphereSkyColor?: THREE.Color | number;
+  /** Default a mid grey. */
+  hemisphereGroundColor?: THREE.Color | number;
+  /** Default 0.6. Only applies when {@link LightingConfig.enableHemisphereLight}. */
+  hemisphereIntensity?: number;
 };
 type EnvironmentConfig = {
-    hdrPath?: string;
-    backgroundColor?: THREE.Color | string;
-    enableEnvironmentLighting?: boolean;
-    /**
-     * Defaults to `(0, 0, 1)` — Rhino's Z-up, not Three's native Y-up — because geometry arrives in
-     * Rhino's frame and is never rotated on ingress. Everything orientation-dependent derives from
-     * this (view presets, default camera, sun, grid, floor, hemisphere light), but overriding it
-     * reorients the viewer only — it does NOT rotate incoming geometry.
-     */
-    sceneUp?: THREE.Vector3;
-    showEnvironment?: boolean;
-    /**
-     * Multiplier on the HDR's image-based lighting contribution — normalizes brightness across HDRs
-     * of differing exposure. Default 1 (unchanged look).
-     */
-    environmentIntensity?: number;
+  hdrPath?: string;
+  backgroundColor?: THREE.Color | string;
+  enableEnvironmentLighting?: boolean;
+  /**
+   * Default `(0, 0, 1)` — Rhino's Z-up. Every orientation default derives from this (see `up-axis.ts`);
+   * overriding it reorients the viewer only, it does not rotate incoming geometry.
+   */
+  sceneUp?: THREE.Vector3;
+  showEnvironment?: boolean;
+  /**
+   * Multiplier on the HDR's image-based lighting contribution — normalizes brightness across HDRs
+   * of differing exposure. Default 1 (unchanged look).
+   */
+  environmentIntensity?: number;
 };
 type FloorConfig = {
-    enabled?: boolean;
-    size?: number;
-    color?: THREE.Color | string;
-    roughness?: number;
-    metalness?: number;
-    receiveShadow?: boolean;
+  enabled?: boolean;
+  size?: number;
+  color?: THREE.Color | string;
+  roughness?: number;
+  metalness?: number;
+  receiveShadow?: boolean;
 };
 type RenderConfig = {
-    enableShadows?: boolean;
-    shadowMapSize?: number;
-    antialias?: boolean;
-    pixelRatio?: number;
-    toneMapping?: THREE.ToneMapping;
-    toneMappingExposure?: number;
-    preserveDrawingBuffer?: boolean;
-    /** Default false — switches rendering from `renderer.render` to an EffectComposer, which costs more. */
-    ambientOcclusion?: boolean;
-    /** AO strength 0–1 when {@link RenderConfig.ambientOcclusion} is on. Default 1. */
-    aoIntensity?: number;
-    /**
-     * DPR cap for AO buffers — AO is low-frequency, so sampling below display DPR is nearly invisible
-     * but much cheaper (a DPR-2 display would otherwise push 4× the pixels through GTAO's per-pixel
-     * sample loop). Default 1; only relevant when AO is enabled.
-     */
-    aoPixelRatio?: number;
-    /**
-     * Render only on change (camera motion, invalidate(), pointer input, resize) plus a ~500ms safety
-     * repaint, instead of every frame. Default true — cuts idle GPU/battery use. Set false to restore
-     * a continuous loop.
-     */
-    onDemand?: boolean;
+  enableShadows?: boolean;
+  shadowMapSize?: number;
+  antialias?: boolean;
+  pixelRatio?: number;
+  toneMapping?: THREE.ToneMapping;
+  toneMappingExposure?: number;
+  preserveDrawingBuffer?: boolean;
+  /** Default false — switches rendering from `renderer.render` to an EffectComposer, which costs more. */
+  ambientOcclusion?: boolean;
+  /** AO strength 0–1 when {@link RenderConfig.ambientOcclusion} is on. Default 1. */
+  aoIntensity?: number;
+  /**
+   * DPR cap for AO buffers — AO is low-frequency, so sampling below display DPR is nearly invisible
+   * but much cheaper (a DPR-2 display would otherwise push 4× the pixels through GTAO's per-pixel
+   * sample loop). Default 1; only relevant when AO is enabled.
+   */
+  aoPixelRatio?: number;
+  /**
+   * Render only on change (camera motion, invalidate(), pointer input, resize) plus a ~500ms safety
+   * repaint, instead of every frame. Default true — cuts idle GPU/battery use. Set false to restore
+   * a continuous loop.
+   */
+  onDemand?: boolean;
 };
-
-/** Crisp boundary/crease edge overlays on meshes. See `addEdges`. */
+/** Crisp boundary/crease edge overlays on meshes. Field rationale: see `EdgeOptions` in `edges/options.ts`. */
 type EdgesConfig = {
-    /** Default false (opt-in). */
-    enabled?: boolean;
-    /** Omit (default) to derive each mesh's edge color from its own surface material, darkened by `darken`. */
-    color?: THREE.ColorRepresentation;
-    /** 0–1, default 0.75. Ignored when `color` is set. */
-    darken?: number;
-    /** CSS px. Default 1.5. */
-    width?: number;
-    /** Crease angle in degrees: keep edges where faces differ by more than this. Default 44. */
-    thresholdAngle?: number;
-    /** Fade an overlay out as its mesh shrinks on screen. Default true. */
-    distanceFade?: boolean;
-    /** Skip overlay extraction for meshes above this triangle count. Default 4M. */
-    maxTriangles?: number;
-    /** Overlays above this segment count render opaque (no distance fade). Default 2M. */
-    maxSegments?: number;
-    /** Meshes skipped for exceeding `maxTriangles` fall back to the screen-space edge-detection pass
-     * (constant cost regardless of triangle count). Default true. */
-    screenSpaceFallback?: boolean;
+  /** Default false (opt-in). */
+  enabled?: boolean;
+  color?: THREE.ColorRepresentation;
+  /** 0–1, default 0.75. Ignored when `color` is set. */
+  darken?: number;
+  /** CSS px. Default 1.5. */
+  width?: number;
+  /** Degrees. Default 44. */
+  thresholdAngle?: number;
+  /** Default true. */
+  distanceFade?: boolean;
+  /** Default 4M. */
+  maxTriangles?: number;
+  /** Default 2M. */
+  maxSegments?: number;
+  /** Fall back to the screen-space edge-detection pass for meshes skipped by `maxTriangles`. Default true. */
+  screenSpaceFallback?: boolean;
 };
 type ControlsConfig = {
-    enableDamping?: boolean;
-    dampingFactor?: number;
-    autoRotate?: boolean;
-    autoRotateSpeed?: number;
-    enableZoom?: boolean;
-    enablePan?: boolean;
-    minDistance?: number;
-    maxDistance?: number;
+  enableDamping?: boolean;
+  dampingFactor?: number;
+  autoRotate?: boolean;
+  autoRotateSpeed?: number;
+  enableZoom?: boolean;
+  enablePan?: boolean;
+  minDistance?: number;
+  maxDistance?: number;
 };
 /** Infinite distance-fading reference grid. See `createGrid`. */
 type GridConfig = {
-    /** Default false (opt-in). */
-    enabled?: boolean;
-    /** World units (meters). Default 1. */
-    cellSize?: number;
-    /** Minor cells per major line. Default 10. */
-    majorEvery?: number;
-    cellColor?: THREE.ColorRepresentation;
-    majorColor?: THREE.ColorRepresentation;
-    /** World radius at which the grid fully fades. Default 100. */
-    fadeDistance?: number;
-    /**
-     * Axis the grid lies perpendicular to. Defaults to whichever axis `sceneUp` points along
-     * (`'z'` unless `sceneUp` is overridden); set explicitly to force an orientation that ignores it.
-     */
-    plane?: 'x' | 'y' | 'z';
+  /** Default false (opt-in). */
+  enabled?: boolean;
+  /** World units (meters). Default 1. */
+  cellSize?: number;
+  /** Minor cells per major line. Default 10. */
+  majorEvery?: number;
+  cellColor?: THREE.ColorRepresentation;
+  majorColor?: THREE.ColorRepresentation;
+  /** World radius at which the grid fully fades. Default 100. */
+  fadeDistance?: number;
+  /**
+   * Axis the grid lies perpendicular to. Defaults to whichever axis `sceneUp` points along
+   * (`'z'` unless `sceneUp` is overridden); set explicitly to force an orientation that ignores it.
+   */
+  plane?: 'x' | 'y' | 'z';
 };
 /** Corner nav-cube/axis gizmo that snaps to preset views. See `createViewGizmo`. */
 type GizmoConfig = {
-    /** Default false (opt-in). */
-    enabled?: boolean;
+  /** Default false (opt-in). */
+  enabled?: boolean;
 };
 /** Two-click distance measurement tool. See `createMeasureTool`. */
 type MeasureConfig = {
-    /** Default false. Only builds the tool; start measuring via `measureTool.setEnabled(true)` on the init result. */
-    enabled?: boolean;
-    /** Snap to a vertex within this many screen px. Default 12. */
-    snapPixels?: number;
-    /** Default yellow. */
-    color?: THREE.ColorRepresentation;
-    /** CSS class for the distance label. */
-    labelClassName?: string;
-    /** Scene is in meters; pass the response's `modelunits` to convert the label (e.g. "25.0 mm"). Default meters. Ignored if `format` is set. */
-    displayUnit?: string;
-    /** Receives the straight-line `distance` and per-axis `delta`. Default renders the total plus a Δx/Δy/Δz breakdown. */
-    format?: (distance: number, delta: THREE.Vector3) => string;
+  /** Default false. Only builds the tool; start measuring via `measureTool.setEnabled(true)` on the init result. */
+  enabled?: boolean;
+  /** Snap to a vertex within this many screen px. Default 12. */
+  snapPixels?: number;
+  /** Default yellow. */
+  color?: THREE.ColorRepresentation;
+  /** CSS class for the distance label. */
+  labelClassName?: string;
+  /** Scene is in meters; pass the response's `modelunits` to convert the label (e.g. "25.0 mm"). Default meters. Ignored if `format` is set. */
+  displayUnit?: string;
+  /** Receives the straight-line `distance` and per-axis `delta`. Default renders the total plus a Δx/Δy/Δz breakdown. */
+  format?: (distance: number, delta: THREE.Vector3) => string;
 };
 type ThreeInitializerOptions = {
-    sceneScale?: 'mm' | 'cm' | 'm' | 'inches' | 'feet';
-    /**
-     * Seeds lighting/material defaults (tone mapping, AO, IBL strength, hemisphere fill); explicit
-     * `lighting`/`environment`/`render` options still win. Does NOT touch edges/grid. Default
-     * 'technical'. Re-apply later via the init result's `setLook`.
-     */
-    look?: Look;
-    camera?: CameraConfig;
-    lighting?: LightingConfig;
-    environment?: EnvironmentConfig;
-    floor?: FloorConfig;
-    render?: RenderConfig;
-    controls?: ControlsConfig;
-    grid?: GridConfig;
-    gizmo?: GizmoConfig;
-    edges?: EdgesConfig;
-    measure?: MeasureConfig;
-    events?: EventConfig;
-    /**
-     * Called once at init with the GPU's max anisotropy. **Not needed for sharp textures** — the
-     * parse layer's texture cache subscribes to this value itself via a shared sink. This hook is
-     * only for hosts doing their own texture work on top.
-     */
-    onMaxAnisotropy?: (value: number) => void;
+  sceneScale?: 'mm' | 'cm' | 'm' | 'inches' | 'feet';
+  /**
+   * Seeds lighting/material defaults (tone mapping, AO, IBL strength, hemisphere fill); explicit
+   * `lighting`/`environment`/`render` options still win. Does NOT touch edges/grid. Default
+   * 'technical'. Re-apply later via the init result's `setLook`.
+   */
+  look?: Look;
+  camera?: CameraConfig;
+  lighting?: LightingConfig;
+  environment?: EnvironmentConfig;
+  floor?: FloorConfig;
+  render?: RenderConfig;
+  controls?: ControlsConfig;
+  grid?: GridConfig;
+  gizmo?: GizmoConfig;
+  edges?: EdgesConfig;
+  measure?: MeasureConfig;
+  events?: EventConfig;
+  /**
+   * Called once at init with the GPU's max anisotropy. Not needed for sharp textures — `parse/`'s
+   * texture cache subscribes to this value on its own (see README's render↔parse seam). Only for
+   * hosts doing their own texture work.
+   */
+  onMaxAnisotropy?: (value: number) => void;
 };
 type EventConfig = {
-    onBackgroundClicked?: (event: {
-        x: number;
-        y: number;
-    }) => void;
-    onObjectSelected?: (object: THREE.Object3D) => void;
-    /** Receives the clicked mesh's `userData`; only fires for meshes with non-empty `userData`. */
-    onMeshMetadataClicked?: (metadata: Record<string, unknown>) => void;
-    onMeshDoubleClicked?: (object: THREE.Object3D) => void;
-    /** Default red (#ff0000). */
-    selectionColor?: THREE.Color | string;
-    /** Enable all event handlers (click/selection/metadata). Default true. */
-    enableEventHandlers?: boolean;
-    enableKeyboardControls?: boolean;
-    enableClickToFocus?: boolean;
-    /** Default true. */
-    enableDoubleClickZoom?: boolean;
-    onReady?: () => void;
-    /** Fires every animation frame, after controls update and before render. */
-    onFrame?: (delta: number) => void;
+  onBackgroundClicked?: (event: {
+    x: number;
+    y: number;
+  }) => void;
+  onObjectSelected?: (object: THREE.Object3D) => void;
+  /** Receives the clicked mesh's `userData`; only fires for meshes with non-empty `userData`. */
+  onMeshMetadataClicked?: (metadata: Record<string, unknown>) => void;
+  onMeshDoubleClicked?: (object: THREE.Object3D) => void;
+  /** Default red (#ff0000). */
+  selectionColor?: THREE.Color | string;
+  /** Enable all event handlers (click/selection/metadata). Default true. */
+  enableEventHandlers?: boolean;
+  enableKeyboardControls?: boolean;
+  enableClickToFocus?: boolean;
+  /** Default true. */
+  enableDoubleClickZoom?: boolean;
+  onReady?: () => void;
+  /** Fires every animation frame, after controls update and before render. */
+  onFrame?: (delta: number) => void;
 };
-
+//#endregion
+//#region src/render/camera-controller.d.ts
 /**
  * Runtime camera control: preset views, perspective⇄orthographic toggle, rotate lock.
  *
@@ -267,164 +266,167 @@ type EventConfig = {
  * render loop renders, resize reshapes, and the raycaster picks with — {@link getActiveCamera} is
  * the one source of truth for all four call sites.
  *
- * Orthographic shadows perspective (same position/target, frustum derived from perspective FOV +
- * distance) so switching doesn't visually jump.
+ * Orthographic mirrors perspective's position/target with a frustum derived from perspective's FOV
+ * and distance, so switching projections doesn't visually jump.
  */
 type ViewPreset = 'top' | 'bottom' | 'front' | 'back' | 'left' | 'right' | 'iso';
 type CameraProjection = 'perspective' | 'orthographic';
 interface CameraController {
-    /** Swaps identity on {@link setProjection}. */
-    getActiveCamera(): THREE.Camera;
-    getProjection(): CameraProjection;
-    setProjection(projection: CameraProjection): void;
-    toggleProjection(): CameraProjection;
-    setView(preset: ViewPreset, animate?: boolean): void;
-    /**
-     * Frame current content from an explicit world-space direction (target → camera) instead of a
-     * named preset — used by the nav-cube, whose clicked axis is a world axis.
-     */
-    setViewDirection(direction: THREE.Vector3, animate?: boolean): void;
-    /** Frame a world-space box from the current view direction. No-op on an empty box. */
-    frameBounds(box: THREE.Box3, animate?: boolean): void;
-    setRotateEnabled(enabled: boolean): void;
-    isRotateEnabled(): boolean;
-    updateAspect(width: number, height: number): void;
-    /** Cancel any in-flight camera tween. Call on viewer teardown so ticks can't touch disposed controls. */
-    dispose(): void;
+  /** Swaps identity on {@link setProjection}. */
+  getActiveCamera(): THREE.Camera;
+  getProjection(): CameraProjection;
+  setProjection(projection: CameraProjection): void;
+  toggleProjection(): CameraProjection;
+  setView(preset: ViewPreset, animate?: boolean): void;
+  /**
+   * Frame current content from an explicit world-space direction (target → camera) instead of a
+   * named preset — used by the nav-cube, whose clicked axis is a world axis.
+   */
+  setViewDirection(direction: THREE.Vector3, animate?: boolean): void;
+  /** Frame a world-space box from the current view direction. No-op on an empty box. */
+  frameBounds(box: THREE.Box3, animate?: boolean): void;
+  setRotateEnabled(enabled: boolean): void;
+  isRotateEnabled(): boolean;
+  updateAspect(width: number, height: number): void;
+  /** Cancel any in-flight camera tween. Call on viewer teardown so ticks can't touch disposed controls. */
+  dispose(): void;
 }
-
+//#endregion
+//#region src/render/grid.d.ts
 interface Grid {
-    /** Tagged `userData.id = 'grid'` so pick/fit code skips it. */
-    readonly object: THREE.Mesh;
-    /** Re-centers the fade on the camera so the grid feels infinite as you move. Call per frame. */
-    update(cameraPosition: THREE.Vector3): void;
-    /**
-     * Rescales cell spacing and fade radius to the content's extent, so a 3-unit or 3000-unit part
-     * both get sensible cells. No-op for empty/degenerate bounds.
-     */
-    fitToContent(bounds: THREE.Box3): void;
-    setVisible(visible: boolean): void;
-    dispose(): void;
+  /** Tagged `userData.id = 'grid'` so pick/fit code skips it. */
+  readonly object: THREE.Mesh;
+  /** Re-centers the fade on the camera so the grid feels infinite as you move. Call per frame. */
+  update(cameraPosition: THREE.Vector3): void;
+  /**
+   * Rescales cell spacing and fade radius to the content's extent, so a 3-unit or 3000-unit part
+   * both get sensible cells. No-op for empty/degenerate bounds.
+   */
+  fitToContent(bounds: THREE.Box3): void;
+  setVisible(visible: boolean): void;
+  dispose(): void;
 }
-
+//#endregion
+//#region src/render/measure.d.ts
 /**
  * Two-click distance measurement. Click a point, click a second, read the distance off a label on
  * the connecting line; a third click starts fresh.
  *
- * Picking snaps to the nearest vertex of the struck triangle within {@link MeasureOptions.snapPixels}
- * so measurements land exactly on vertices rather than wherever the ray happened to hit — a cheap
- * local snap (three candidate vertices, no spatial index).
+ * Picking snaps to the nearest vertex within {@link MeasureOptions.snapPixels} so measurements
+ * land exactly on vertices rather than wherever the ray happened to hit — a cheap local snap
+ * against the struck primitive's own vertices, no spatial index.
  *
  * Dormant until {@link MeasureTool.setEnabled}(true). While enabled it intercepts clicks (caller
  * forwards them and swallows the event when {@link MeasureTool.handleClick} returns true) so
  * measuring doesn't also select objects.
  */
 interface MeasureTool {
-    setEnabled(enabled: boolean): void;
-    isEnabled(): boolean;
-    /** Returns true if the tool consumed the click (caller should not also select). */
-    handleClick(event: MouseEvent): boolean;
-    /** Preview the next snap point via a ghost marker. No-op when disabled; never consumes the event. */
-    handleMove(event: MouseEvent): void;
-    clear(): void;
-    dispose(): void;
+  setEnabled(enabled: boolean): void;
+  isEnabled(): boolean;
+  /** Returns true if the tool consumed the click (caller should not also select). */
+  handleClick(event: MouseEvent): boolean;
+  /** Preview the next snap point via a ghost marker. No-op when disabled; never consumes the event. */
+  handleMove(event: MouseEvent): void;
+  clear(): void;
+  dispose(): void;
 }
-
+//#endregion
+//#region src/render/view-gizmo.d.ts
 /**
- * Corner nav-cube/axis gizmo. Uses three's {@link ViewHelper} only as the rendered widget, NOT its
+ * Corner nav-cube/axis gizmo. Uses three's {@link ViewHelper} only as the rendered widget, not its
  * click→animate behavior: ViewHelper's snap assumes Y-up and animates straight onto the up axis,
- * which rolls the view and jitters the gizmo at the pole in our Z-up scene. Instead we hit-test the
- * axis sprites ourselves and drive the viewer's up-aware camera controller, which snaps instantly
- * with a pole nudge so the orbit basis never degenerates.
+ * which rolls the view and jitters the gizmo at the pole in a Z-up scene. Instead this hit-tests
+ * the axis sprites directly and drives the viewer's up-aware camera controller, which snaps
+ * instantly with a pole nudge so the orbit basis never degenerates.
  *
- * A click frames the current orbit target (not the world origin), and flips the viewer back to
- * perspective first if it's in orthographic mode (the cube is inherently a 3D-orientation tool).
+ * A click frames the current orbit target (not the world origin) and switches back to perspective
+ * first if orthographic — the cube is a 3D-orientation tool.
  *
- * Caller contract (mirrors ViewHelper's own): call {@link ViewGizmo.render} *after* the main scene
+ * Caller contract (mirrors ViewHelper's own): call {@link ViewGizmo.render} after the main scene
  * render each frame, and forward pointer clicks to {@link ViewGizmo.handleClick}.
  */
 interface ViewGizmo {
-    render(renderer: THREE.WebGLRenderer): void;
-    /** Returns true if it hit the gizmo (and a view change started). */
-    handleClick(event: MouseEvent): boolean;
-    setVisible(visible: boolean): void;
-    isVisible(): boolean;
-    dispose(): void;
+  render(renderer: THREE.WebGLRenderer): void;
+  /** Returns true if it hit the gizmo (and a view change started). */
+  handleClick(event: MouseEvent): boolean;
+  setVisible(visible: boolean): void;
+  isVisible(): boolean;
+  dispose(): void;
 }
-
+//#endregion
+//#region src/render/scene-setup/viewer.d.ts
 interface ThreeViewer {
-    scene: THREE.Scene;
-    camera: THREE.PerspectiveCamera;
-    controls: OrbitControls;
-    renderer: THREE.WebGLRenderer;
-    cameraController: CameraController;
-    grid: Grid | null;
-    gizmo: ViewGizmo | null;
-    /** Null unless `measure.enabled`; `setEnabled(true)` to use. */
-    measureTool: MeasureTool | null;
-    /**
-     * Attach edge overlays to meshes under `root` (no-op unless `edges.enabled`). Large-mesh
-     * extraction runs off-thread, so overlays may attach a beat later; meshes over
-     * `edges.maxTriangles` are skipped and (by default) covered by the screen-space edge fallback.
-     */
-    applyEdges: (root: THREE.Object3D) => void;
-    /**
-     * Prefer over calling `removeEdges` directly — also cancels in-flight async attaches and stands
-     * down the screen-space fallback if active.
-     */
-    clearEdges: (root: THREE.Object3D) => void;
-    /**
-     * Request a repaint from the on-demand render loop. Built-in setters and input invalidate
-     * automatically; call this after mutating the scene externally. No-op when `render.onDemand` is false.
-     */
-    invalidate: () => void;
-    setAmbientOcclusion: (enabled: boolean) => void;
-    /**
-     * Retunes lighting/material only (tone mapping, fill, IBL, AO) — never edges/grid. Overwrites
-     * any granular lighting dials set earlier.
-     */
-    setLook: (look: 'studio' | 'technical' | 'showcase') => void;
-    /**
-     * Raising `hemisphereIntensity` is the most effective way to lift shadowed/under-facing surfaces
-     * a dark HDR leaves black; a positive value lazily creates the hemisphere light if the viewer was
-     * built without one, `0` switches it off.
-     */
-    setFillLights: (opts: {
-        hemisphereIntensity?: number;
-        hemisphereSkyColor?: THREE.Color | number;
-        hemisphereGroundColor?: THREE.Color | number;
-        ambientIntensity?: number;
-    }) => void;
-    /**
-     * Normalizes IBL brightness across HDRs of differing exposure. Applies even before the HDR
-     * finishes decoding.
-     */
-    setEnvironmentIntensity: (intensity: number) => void;
-    setToneMappingExposure: (exposure: number) => void;
-    /** GTAO strength (0-1). No-op when ambient occlusion isn't active. */
-    setAoIntensity: (intensity: number) => void;
-    /** Feed into the batch parser's `material` option so freshly-loaded meshes match the active look. */
-    getMaterialAppearance: () => MaterialAppearanceOptions;
-    /** Call after loading or replacing geometry. No-op when sunlight/shadows are off. */
-    updateShadowBounds: () => void;
-    /** Call after loading or replacing geometry. No-op when the grid is off or empty. */
-    updateGridScale: () => void;
-    dispose: () => void;
-    fitToView: () => void;
-    clearSelection: () => void;
-    /**
-     * Tagged `userData.source = 'user'` so it survives `updateScene` solves instead of being cleared
-     * with compute content, and counts as normal content for fit-to-view framing.
-     */
-    addUserGeometry: (object: THREE.Object3D) => void;
-    removeUserGeometry: (object: THREE.Object3D) => void;
-    /** Removes and disposes everything added via `addUserGeometry`. */
-    clearUserGeometry: () => void;
+  scene: THREE.Scene;
+  camera: THREE.PerspectiveCamera;
+  controls: OrbitControls;
+  renderer: THREE.WebGLRenderer;
+  cameraController: CameraController;
+  grid: Grid | null;
+  gizmo: ViewGizmo | null;
+  /** Null unless `measure.enabled`. */
+  measureTool: MeasureTool | null;
+  /**
+   * No-op unless `edges.enabled`. Extraction runs off-thread for large meshes, so overlays can
+   * attach a beat later; meshes over `edges.maxTriangles` fall back to the screen-space edge shader.
+   */
+  applyEdges: (root: THREE.Object3D) => void;
+  /**
+   * Prefer over `removeEdges` directly — also cancels in-flight async attaches and stands down the
+   * screen-space edge fallback if active.
+   */
+  clearEdges: (root: THREE.Object3D) => void;
+  /**
+   * Request a repaint from the on-demand render loop. Built-in setters and input invalidate
+   * automatically; call this after mutating the scene externally. No-op when `render.onDemand` is false.
+   */
+  invalidate: () => void;
+  setAmbientOcclusion: (enabled: boolean) => void;
+  /**
+   * Retunes lighting/material (tone mapping, fill, IBL, AO) only — never edges/grid. Overwrites
+   * any granular lighting dials set earlier with the preset's values.
+   */
+  setLook: (look: 'studio' | 'technical' | 'showcase') => void;
+  /**
+   * Raising `hemisphereIntensity` is the most effective way to lift shadowed surfaces a dark HDR
+   * leaves black. Lazily creates the hemisphere light if the viewer was built without one; `0` turns
+   * it back off.
+   */
+  setFillLights: (opts: {
+    hemisphereIntensity?: number;
+    hemisphereSkyColor?: THREE.Color | number;
+    hemisphereGroundColor?: THREE.Color | number;
+    ambientIntensity?: number;
+  }) => void;
+  /**
+   * Normalizes IBL brightness across HDRs of differing exposure. Applies even before the HDR
+   * finishes decoding.
+   */
+  setEnvironmentIntensity: (intensity: number) => void;
+  setToneMappingExposure: (exposure: number) => void;
+  /** GTAO strength (0-1). No-op when ambient occlusion isn't active. */
+  setAoIntensity: (intensity: number) => void;
+  /** Feed into the batch parser's `material` option so freshly-loaded meshes match the active look. */
+  getMaterialAppearance: () => MaterialAppearanceOptions;
+  /** Call after loading or replacing geometry. No-op when sunlight/shadows are off. */
+  updateShadowBounds: () => void;
+  /** Call after loading or replacing geometry. No-op when the grid is off or empty. */
+  updateGridScale: () => void;
+  dispose: () => void;
+  fitToView: () => void;
+  clearSelection: () => void;
+  /** Tagged `userData.source = 'user'` so it survives `updateScene` solves and counts for fit-to-view. */
+  addUserGeometry: (object: THREE.Object3D) => void;
+  removeUserGeometry: (object: THREE.Object3D) => void;
+  /** Removes and disposes everything added via `addUserGeometry`. */
+  clearUserGeometry: () => void;
 }
-
+//#endregion
+//#region src/render/scene-setup/init-three.d.ts
 declare const initThree: (canvas: HTMLCanvasElement, options?: ThreeInitializerOptions) => ThreeViewer;
-
+//#endregion
+//#region src/render/three-helpers.d.ts
 /** Replaces scene content with `meshes`, rescales the camera frustum to fit, and (first call only) positions the camera/controls. */
 declare function updateScene(scene: THREE.Scene, meshes: THREE.Object3D[], camera: THREE.PerspectiveCamera, controls: OrbitControls, initialPositionSet: boolean): void;
-
-export { type CameraConfig, type CameraController, type CameraProjection, type ControlsConfig, DEFAULT_LOOK, type EdgesConfig, type EnvironmentConfig, type ErrorCode, ErrorCodes, type EventConfig, type FloorConfig, type GizmoConfig, type Grid, type GridConfig, LOOK_PRESETS, type LightingConfig, type Logger, Look, LookPreset, MaterialAppearanceOptions, type MeasureConfig, type MeasureTool, type RenderConfig, type ThreeInitializerOptions, type ThreeViewer, type ViewGizmo, type ViewPreset, VisualizationError, enableDebugLogging, getLogger, initThree, materialAppearanceForLook, setLogger, updateScene };
+//#endregion
+export { type CameraConfig, type CameraController, type CameraProjection, type ControlsConfig, DEFAULT_LOOK, type EdgesConfig, type EnvironmentConfig, type ErrorCode, ErrorCodes, type EventConfig, type FloorConfig, type GizmoConfig, type Grid, type GridConfig, LOOKS, LOOK_PRESETS, type LightingConfig, type Logger, type Look, type LookPreset, type MaterialAppearanceOptions, type MeasureConfig, type MeasureTool, type RenderConfig, type ThreeInitializerOptions, type ThreeViewer, type ViewGizmo, type ViewPreset, VisualizationError, enableDebugLogging, getLogger, initThree, materialAppearanceForLook, setLogger, updateScene };
+//# sourceMappingURL=render.d.cts.map