@selvajs/visualization 1.0.0-beta.1 → 1.0.0-beta.3

package/dist/render.d.ts

@@ -1,50 +1,52 @@
-import * as THREE from 'three';
-import { L as Look, a as LookPreset, M as MaterialAppearanceOptions } from './types-DCuos3gI.js';
-export { b as LOOKS } from './types-DCuos3gI.js';
-import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
-
+import { i as MaterialAppearanceOptions, n as Look, r as LookPreset, t as LOOKS } from "./types-Di80Y609.js";
+import * as THREE from "three";
+import { CSS2DObject } from "three/addons/renderers/CSS2DRenderer.js";
+import { OrbitControls } from "three/addons/controls/OrbitControls.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,205 +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;
-    /**
-     * 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;
+  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. Field rationale: see `EdgeOptions` in `edges/options.ts`. */
 type EdgesConfig = {
-    /** 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;
+  /** 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 — `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;
+  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.
  *
@@ -269,40 +272,57 @@ type EventConfig = {
 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/label-layer.d.ts
+interface LabelHandle {
+  readonly object: CSS2DObject;
+  setPosition(position: THREE.Vector3): void;
+  setText(text: string): void;
+  remove(): void;
 }
-
+interface LabelLayer {
+  addLabel(text: string, position: THREE.Vector3, className?: string): LabelHandle;
+  /** Call each frame after the WebGL render, with the active camera. */
+  render(scene: THREE.Scene, camera: THREE.Camera): void;
+  setSize(width: number, height: number): 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.
@@ -316,16 +336,85 @@ interface Grid {
  * 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;
+}
+/**
+ * Raycast threshold for picking lines/points, as a fixed fraction of view size so the grab band
+ * stays constant on screen while zooming. Perspective uses camera→target distance (see
+ * `MeasureDeps.getViewTarget`); orthographic uses frustum height `(top − bottom) / zoom`, since
+ * ortho zoom changes `camera.zoom` rather than position.
+ *
+ * Shared with any tool doing its own picking, so grab bands stay consistent across tools.
+ */
+declare function pickThreshold(camera: THREE.Camera, viewTarget?: THREE.Vector3): number;
+/** Snap a raycast hit to the nearest geometry vertex within `snapPixels` on screen, else the raw hit point. */
+declare function snapToVertex(hit: THREE.Intersection, camera: THREE.Camera, screenSize: {
+  width: number;
+  height: number;
+}, snapPixels: number): THREE.Vector3;
+//#endregion
+//#region src/render/tool-registry.d.ts
+/**
+ * A tool that can claim canvas pointer input.
+ *
+ * `handleClick` returning true means the tool consumed the event and the host stops dispatching —
+ * no further tool sees it, and object selection doesn't run. `handleMove` never consumes: it runs
+ * on every move regardless of which tool is active, so previews can't block orbit or pan.
+ */
+interface PointerTool {
+  setEnabled?(enabled: boolean): void;
+  isEnabled?(): boolean;
+  /** Returns true if this tool consumed the click. */
+  handleClick(event: MouseEvent): boolean;
+  /** Preview only — must not consume. */
+  handleMove?(event: MouseEvent): void;
+  clear?(): void;
+  dispose?(): void;
+}
+interface ToolRegistration {
+  /** Unique within the registry; registering the same id twice replaces the earlier tool. */
+  id: string;
+  tool: PointerTool;
+  /**
+   * Higher runs first. The built-ins sit at 0 (measure) and -100 (gizmo); register above 0 to
+   * claim clicks before measuring, below -100 to act only as a fallback.
+   */
+  priority?: number;
 }
-
+interface ToolRegistry {
+  /** Returns an unregister function. Does not dispose the tool — the registrant still owns it. */
+  register(registration: ToolRegistration): () => void;
+  unregister(id: string): void;
+  get(id: string): PointerTool | null;
+  /**
+   * Enables one tool and disables every other registered one. Pass null to disable all.
+   * Tools without `setEnabled` are always live and unaffected.
+   */
+  setActive(id: string | null): void;
+  /** The id passed to the last `setActive`, or null. */
+  getActive(): string | null;
+  /** @internal — `initThree` forwards DOM events here. */
+  handleClick(event: MouseEvent): boolean;
+  /** @internal */
+  handleMove(event: MouseEvent): void;
+}
+/**
+ * Screen-space ray from a canvas mouse event, for tools doing their own picking. Handles the
+ * canvas's position and size, so it stays correct under CSS scaling and in fullscreen.
+ */
+declare function pointerToNdc(event: MouseEvent, canvas: HTMLCanvasElement): {
+  x: number;
+  y: number;
+};
+//#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
  * click→animate behavior: ViewHelper's snap assumes Y-up and animates straight onto the up axis,
@@ -340,83 +429,123 @@ interface MeasureTool {
  * 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`. */
-    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;
+  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;
+  /** CSS2D annotation overlay. Always present — labels render above the canvas and don't take input. */
+  labelLayer: LabelLayer;
+  /**
+   * Pointer tools competing for canvas clicks, ahead of object selection. Built-ins are already
+   * registered as `'measure'` and `'gizmo'`; register your own and drive it with `setActive`.
+   */
+  tools: ToolRegistry;
+  /**
+   * 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;
+  /**
+   * Adds host-owned geometry that survives `updateScene` solves and counts for fit-to-view.
+   * Pass `appId` to scope it to one app (`userData.source = 'app:<id>'`) so `clearUserGeometry`
+   * can clear that app alone; without one it's tagged `'user'` and only a global clear removes it.
+   *
+   * Not restyled by `setLook` — the caller owns these materials.
+   */
+  addUserGeometry: (object: THREE.Object3D, appId?: string) => void;
+  removeUserGeometry: (object: THREE.Object3D) => void;
+  /** Removes and disposes geometry added via `addUserGeometry` — one app's, or all of it. */
+  clearUserGeometry: (appId?: string) => void;
 }
-
+//#endregion
+//#region src/render/scene-setup/init-three.d.ts
 declare const initThree: (canvas: HTMLCanvasElement, options?: ThreeInitializerOptions) => ThreeViewer;
-
+//#endregion
+//#region src/render/scene-ownership.d.ts
+/** Geometry produced by a solve. Replaced wholesale on the next one. */
+declare const SOURCE_COMPUTE = "compute";
+/**
+ * Host-added geometry with no owner id. Predates scoped ownership and still honoured everywhere
+ * an `app:` scope is — new code should prefer {@link appSource}.
+ */
+declare const SOURCE_USER = "user";
+/** The `userData.source` tag for geometry owned by app `id` (`'pointcloud'` → `'app:pointcloud'`). */
+declare function appSource(id: string): string;
+/** The app id from a source tag, or null if the tag isn't app-owned. */
+declare function appIdFromSource(source: unknown): string | null;
+/**
+ * True for anything a host added rather than the solve — `'user'` or any `app:` scope. This is
+ * the predicate `clearScene` uses, so it decides what survives a solve.
+ */
+declare function isHostOwned(object: THREE.Object3D): boolean;
+/**
+ * True for objects owned by `id`. Passing no id matches every host-owned object, which is what
+ * `clearUserGeometry()` does.
+ */
+declare function isOwnedBy(object: THREE.Object3D, id?: string): boolean;
+//#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 LabelHandle, type LabelLayer, type LightingConfig, type Logger, type Look, type LookPreset, type MaterialAppearanceOptions, type MeasureConfig, type MeasureTool, type PointerTool, type RenderConfig, SOURCE_COMPUTE, SOURCE_USER, type ThreeInitializerOptions, type ThreeViewer, type ToolRegistration, type ToolRegistry, type ViewGizmo, type ViewPreset, VisualizationError, appIdFromSource, appSource, enableDebugLogging, getLogger, initThree, isHostOwned, isOwnedBy, materialAppearanceForLook, pickThreshold, pointerToNdc, setLogger, snapToVertex, updateScene };
+//# sourceMappingURL=render.d.ts.map