@selvajs/compute 3.1.0 → 4.0.0-beta.0

package/dist/visualization.d.cts

@@ -1,1093 +0,0 @@
-import * as THREE from 'three';
-import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
-import { M as MaterialAppearanceOptions, f as GrasshopperComputeResponse, m as MeshExtractionOptions, n as MeshBatchParsingOptions, o as DisplayBatch, p as DisplayItem } from './types-BpOl6U02.cjs';
-export { q as DisplayCurve, r as DisplayIdentity, s as DisplayItemBase, t as DisplayPoint, u as DisplayPosition, v as MeshBatch } from './types-BpOl6U02.cjs';
-import { CSS2DObject } from 'three/addons/renderers/CSS2DRenderer.js';
-import { LineSegments2 } from 'three/addons/lines/LineSegments2.js';
-import { Pass } from 'three/addons/postprocessing/Pass.js';
-import { RhinoModule } from 'rhino3dm';
-import './types-BGhtYxZ-.cjs';
-
-type CameraConfig = {
-    position?: THREE.Vector3;
-    fov?: number;
-    near?: number;
-    far?: number;
-    target?: THREE.Vector3;
-    /**
-     * Refit the perspective camera's near plane to the camera↔content gap every frame (default true).
-     * Recovers depth-buffer precision when zoomed out (precision ∝ near/z²), which is what stops
-     * distant surfaces z-fighting. `near` stays the lower bound — the plane is only raised, never
-     * lowered below it.
-     */
-    dynamicNear?: boolean;
-};
-type LightingConfig = {
-    enableSunlight?: boolean;
-    sunlightIntensity?: number;
-    sunlightPosition?: THREE.Vector3;
-    ambientLightColor?: THREE.Color;
-    ambientLightIntensity?: number;
-    sunlightColor?: THREE.Color | number;
-    /**
-     * Add a hemisphere fill light (sky color from above, ground color from below). Unlike the flat
-     * ambient, this gives soft *direction-aware* fill, so downward- and side-facing surfaces never
-     * collapse to black when the HDR's lower hemisphere is dark. The single biggest lever for keeping
-     * results well-lit regardless of which HDR is loaded. Default false (opt-in) — enabling it shifts
-     * the look. See {@link LightingConfig.hemisphereIntensity}.
-     */
-    enableHemisphereLight?: boolean;
-    /** Hemisphere fill sky color (lights upward-facing surfaces). Default white. */
-    hemisphereSkyColor?: THREE.Color | number;
-    /** Hemisphere fill ground color (lights downward-facing surfaces). Default a mid grey. */
-    hemisphereGroundColor?: THREE.Color | number;
-    /** Hemisphere fill strength. Default 0.6. Only applies when {@link LightingConfig.enableHemisphereLight}. */
-    hemisphereIntensity?: number;
-};
-type EnvironmentConfig = {
-    hdrPath?: string;
-    backgroundColor?: THREE.Color | string;
-    enableEnvironmentLighting?: boolean;
-    /**
-     * The scene's up axis. **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 (see
-     * `coordinate-transform.ts`). Everything orientation-dependent derives from this: view presets,
-     * the default iso camera, sun position, grid plane, floor normal, and the hemisphere light.
-     *
-     * Overriding it reorients the viewer but does NOT rotate incoming geometry, so a Y-up value only
-     * makes sense if the host also feeds Y-up geometry.
-     */
-    sceneUp?: THREE.Vector3;
-    showEnvironment?: boolean;
-    /**
-     * Uniform multiplier on the HDR's image-based lighting contribution (`scene.environmentIntensity`).
-     * Normalizes brightness across HDRs of differing exposure — raise it to lift a dim HDR, lower it to
-     * tame a blown-out one — so the scene doesn't render dim-or-blown purely because of the HDR chosen.
-     * Default 1 (three.js default, unchanged look).
-     */
-    environmentIntensity?: number;
-};
-type FloorConfig = {
-    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;
-    /**
-     * Enable ground-truth ambient occlusion (GTAO) via a postprocessing pipeline. Default false —
-     * turning it on 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;
-    /**
-     * Device-pixel-ratio cap for the ambient-occlusion postprocessing buffers. AO is low-frequency, so
-     * rendering its buffers below the display DPR is nearly invisible but hugely cheaper — on a Retina
-     * display (DPR 2) full-resolution AO means 4× the pixels through GTAO's per-pixel sample loops,
-     * which can dominate frame time. Default 1 (AO buffers at 1× regardless of display DPR). Raise
-     * toward the display DPR for sharper AO at higher cost; only relevant when AO is enabled.
-     */
-    aoPixelRatio?: number;
-    /**
-     * Render only when something changed (camera motion, invalidate(), pointer input, resize), with
-     * a ~500 ms safety repaint, instead of every animation frame. Default true — cuts idle GPU/battery
-     * to ~2 fps worth of work, which matters especially with ambient occlusion on. Set false to
-     * restore the legacy continuous loop.
-     */
-    onDemand?: boolean;
-};
-/**
- * A ready-to-go visual look. A `look` is a named bundle of LIGHTING/MATERIAL defaults only — it is
- * deliberately decoupled from the CAD overlays (edges, grid), which are driven independently by
- * {@link EdgesConfig}/{@link GridConfig}. Pick one and the viewer looks professional with zero other
- * config; every individual `lighting`/`environment`/`render` option still overrides the preset. Seeds
- * construction defaults and can be re-applied live via `setLook`.
- *
- * - 'technical' (default): matte, drawing-like — neutral tone mapping, low IBL, no fill. Reads like a
- *   CAD shaded view (Rhino/Onshape).
- * - 'studio': balanced presentation — ACES tone mapping, hemisphere fill + lifted HDR so results are
- *   well-lit regardless of the HDR, without washing colour out. The polished "product shot" look.
- * - 'showcase': punchier presentation — ACES, stronger IBL/fill and a touch more exposure.
- */
-/**
- * The look values as a runtime array — the single source of truth. {@link Look} is derived from it, so
- * the type and the enumerable list can never drift. Consumers (e.g. a viewer's style picker) iterate
- * this instead of hardcoding the names, so adding or renaming a look here updates them automatically.
- * 'technical' is first because it's the default.
- */
-declare const LOOKS: readonly ["technical", "studio", "showcase"];
-type Look = (typeof LOOKS)[number];
-/** Crisp boundary/crease edge overlays on meshes. See `addEdges`. */
-type EdgesConfig = {
-    /** Auto-attach edge overlays to meshes as they load. Default false (opt-in). */
-    enabled?: boolean;
-    /**
-     * Force a single edge color for all meshes. Omit (the default) to derive each mesh's edge color
-     * from its own surface material, darkened by `darken` — so edges read as the object's own outline.
-     */
-    color?: THREE.ColorRepresentation;
-    /**
-     * How far derived edge colors are darkened toward black, 0–1 (default 0.75). Ignored when `color`
-     * is set.
-     */
-    darken?: number;
-    /** Edge thickness in CSS px. Default 1.5. */
-    width?: number;
-    /** Crease angle (degrees): keep edges where faces differ by more than this. Default 44. */
-    thresholdAngle?: number;
-    /** Fade an overlay out as its mesh shrinks on screen, so far zoom-outs stay clean. Default true. */
-    distanceFade?: boolean;
-    /** Skip overlay extraction for meshes above this triangle count. Default 4M. See `EdgeOptions`. */
-    maxTriangles?: number;
-    /** Overlays above this segment count render opaque (no distance fade). Default 2M. */
-    maxSegments?: number;
-    /**
-     * When a mesh is skipped for exceeding `maxTriangles`, approximate its edges with the
-     * screen-space edge-detection pass (constant cost in triangle count). Default true.
-     */
-    screenSpaceFallback?: boolean;
-};
-type ControlsConfig = {
-    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 = {
-    /** Show the grid. Default false (opt-in). */
-    enabled?: boolean;
-    /** Minor cell size in world units (meters). Default 1. */
-    cellSize?: number;
-    /** Minor cells per major line. Default 10. */
-    majorEvery?: number;
-    /** Minor line color. */
-    cellColor?: THREE.ColorRepresentation;
-    /** Major line color. */
-    majorColor?: THREE.ColorRepresentation;
-    /** World radius at which the grid fully fades. Default 100. */
-    fadeDistance?: number;
-    /**
-     * Axis the grid lies perpendicular to — the scene's up axis. Defaults to whichever axis
-     * `sceneUp` points along, so it is `'z'` (Rhino's horizontal ground) unless you override
-     * `sceneUp`. Set explicitly only to force a grid orientation that ignores the scene up.
-     */
-    plane?: 'x' | 'y' | 'z';
-};
-/** Corner nav-cube/axis gizmo that snaps to preset views. See `createViewGizmo`. */
-type GizmoConfig = {
-    /** Show the gizmo. Default false (opt-in). */
-    enabled?: boolean;
-};
-/** Two-click distance measurement tool. See `createMeasureTool`. */
-type MeasureConfig = {
-    /**
-     * Create the measurement tool. Default false. Note: this only *builds* the tool (and its label
-     * overlay); start measuring by calling `measureTool.setEnabled(true)` on the init result.
-     */
-    enabled?: boolean;
-    /** Snap to a vertex within this many screen px. Default 12. */
-    snapPixels?: number;
-    /** Marker + line color. Default yellow. */
-    color?: THREE.ColorRepresentation;
-    /** CSS class for the distance label. */
-    labelClassName?: string;
-    /**
-     * Model unit (pass the response's `modelunits`). The scene is in meters, so the default label is
-     * converted to this unit — a mm model reads "25.0 mm". Defaults to meters. Ignored if `format` is set.
-     */
-    displayUnit?: string;
-    /**
-     * Format the measurement → label text. 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';
-    /**
-     * Pick a ready-to-go visual look up front — seeds professional lighting/material defaults (tone
-     * mapping, AO, IBL strength, hemisphere fill; see {@link Look}). Individual `lighting`/
-     * `environment`/`render` options still win when set explicitly, so this only fills in what you
-     * leave unspecified. A look does NOT touch edges/grid (those are independent overlays). Defaults
-     * to '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;
-};
-type EventConfig = {
-    onBackgroundClicked?: (event: {
-        x: number;
-        y: number;
-    }) => void;
-    onObjectSelected?: (object: THREE.Object3D) => void;
-    /** Called when a mesh with metadata is clicked. Receives the mesh's metadata object. */
-    onMeshMetadataClicked?: (metadata: Record<string, string>) => void;
-    /** Called when a mesh is double-clicked. Receives the mesh object. */
-    onMeshDoubleClicked?: (object: THREE.Object3D) => void;
-    /** Color to use for highlighting selected meshes. Defaults to red (#ff0000). */
-    selectionColor?: THREE.Color | string;
-    /** Enable all event handlers (click/selection/metadata). Defaults to true. */
-    enableEventHandlers?: boolean;
-    enableKeyboardControls?: boolean;
-    enableClickToFocus?: boolean;
-    /** Zoom into a mesh on double-click. Defaults to true. */
-    enableDoubleClickZoom?: boolean;
-    /** Called once the HDR environment map has finished loading and been applied to the scene. */
-    onReady?: () => void;
-    /** Called every animation frame, after controls update and before render. Use for custom per-frame logic. */
-    onFrame?: (delta: number) => void;
-};
-
-/**
- * Runtime camera control for the viewer: preset views (top/front/…), a true 2D/3D toggle
- * (orthographic ⇄ perspective), and a rotate lock.
- *
- * Why a controller and not just loose methods: all three features have to agree on *which* camera
- * is active. Switching projection swaps the camera object OrbitControls drives, the animation loop
- * renders, the resize handler reshapes, and the raycaster picks with. Centralizing that here keeps
- * those four call sites reading one source of truth ({@link getActiveCamera}) instead of each
- * branching on a `mode` flag.
- *
- * The perspective camera stays the primary (it's what {@link updateScene} and existing consumers
- * size). The orthographic camera shadows it: same position/target, frustum derived from the
- * perspective FOV + current distance so the 3D→2D switch doesn't visually jump.
- */
-/** The six axis-aligned presets plus the default 3/4 iso. Named in Three's Y-up frame. */
-type ViewPreset = 'top' | 'bottom' | 'front' | 'back' | 'left' | 'right' | 'iso';
-type CameraProjection = 'perspective' | 'orthographic';
-interface CameraController {
-    /** The camera currently being rendered/picked with. Swaps identity on {@link setProjection}. */
-    getActiveCamera(): THREE.Camera;
-    /** Current projection mode. */
-    getProjection(): CameraProjection;
-    /** Switch between perspective (3D) and orthographic (2D). No-op if already in that mode. */
-    setProjection(projection: CameraProjection): void;
-    /** Convenience toggle for a 2D/3D button. */
-    toggleProjection(): CameraProjection;
-    /** Move the camera to a preset orientation, framing current scene content. Animated. */
-    setView(preset: ViewPreset, animate?: boolean): void;
-    /**
-     * Frame current content viewed from `direction` (a world-space vector from target toward camera).
-     * Like {@link setView} but takes an explicit direction — used by the nav-cube, whose clicked axis
-     * is a world axis, not a named preset. Pole directions are nudged off-axis to avoid the orbit
-     * singularity.
-     */
-    setViewDirection(direction: THREE.Vector3, animate?: boolean): void;
-    /**
-     * Frame an arbitrary world-space box (e.g. a double-clicked object) from the current view
-     * direction, moving the *active* camera — in 2D mode that means resizing the ortho frustum, not
-     * just translating. No-op on an empty box.
-     */
-    frameBounds(box: THREE.Box3, animate?: boolean): void;
-    /** Enable/disable orbit rotation at runtime (pan/zoom unaffected). */
-    setRotateEnabled(enabled: boolean): void;
-    /** Whether rotation is currently enabled. */
-    isRotateEnabled(): boolean;
-    /** Keep the orthographic frustum aspect in sync on canvas resize. Called by the resize loop. */
-    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;
-}
-interface CameraControllerDeps {
-    scene: THREE.Scene;
-    perspective: THREE.PerspectiveCamera;
-    controls: OrbitControls;
-    /** Called whenever the active camera identity changes, so callers can re-point the renderer/raycaster. */
-    onActiveCameraChange: (camera: THREE.Camera) => void;
-    /**
-     * The scene's up axis. Presets, the orthographic camera's up, and the iso direction are all derived
-     * from this so the controller is correct in any up convention (Three's native Y-up, Rhino's Z-up, …)
-     * without hardcoding an axis. Falls back to `perspective.up` when omitted; `initThree` always
-     * passes the configured `sceneUp`, which itself defaults to Rhino's Z-up.
-     */
-    up?: THREE.Vector3;
-}
-declare function createCameraController(deps: CameraControllerDeps): CameraController;
-
-/**
- * An "infinite", distance-fading reference grid — the single strongest visual cue that reads as CAD.
- *
- * Why not `GridHelper`: it's a fixed-size square of line segments that visibly ends and looks wrong
- * once you pan or zoom past it. Instead we draw one large screen-facing plane and compute the grid
- * in the fragment shader from world coordinates, fading lines out with distance so the edge is never
- * a hard cutoff. The plane is big enough to cover any reasonable view; the fade hides its bounds.
- *
- * Two line frequencies (minor + major every 10th) give the usual graph-paper depth read. Spacing is
- * in world units (meters — the scene's normalized unit), so a `cellSize` of 1 = 1m minor cells.
- */
-interface GridOptions {
-    /** Minor cell size in world units (meters). Default 1. */
-    cellSize?: number;
-    /** How many minor cells per major line. Default 10. */
-    majorEvery?: number;
-    /** Minor line color. */
-    cellColor?: THREE.ColorRepresentation;
-    /** Major line color. */
-    majorColor?: THREE.ColorRepresentation;
-    /** World-space radius at which the grid has fully faded out. Default 100. */
-    fadeDistance?: number;
-    /**
-     * Axis the grid is laid perpendicular to — i.e. the scene's up axis. `'z'` is the horizontal
-     * ground in the Rhino Z-up frame the viewer uses; `'y'` is Three's native Y-up.
-     *
-     * This standalone default is `'y'`, but `initThree` always passes a plane derived from the
-     * configured `sceneUp`, so a viewer-created grid defaults to `'z'`.
-     */
-    plane?: 'x' | 'y' | 'z';
-}
-interface Grid {
-    /** The grid mesh; add to the scene. Tagged `userData.id = 'grid'` so pick/fit code skips it. */
-    readonly object: THREE.Mesh;
-    /** Keep the fade centered on the camera so the grid feels infinite as you move. Call per frame. */
-    update(cameraPosition: THREE.Vector3): void;
-    /**
-     * Rescale the grid's cell spacing and fade radius to the loaded content's extent. Call after a
-     * geometry change (e.g. right after `updateScene`) so a part that is 3 units or 3000 units wide
-     * both get sensibly-sized cells and a fade that reaches past the model. No-op for empty/degenerate
-     * bounds — the grid keeps its last (or default) scale. See {@link Grid.fitToContent}'s impl notes.
-     */
-    fitToContent(bounds: THREE.Box3): void;
-    setVisible(visible: boolean): void;
-    dispose(): void;
-}
-declare function createGrid(options?: GridOptions): Grid;
-
-/**
- * The corner nav-cube/axis gizmo. Uses three's {@link ViewHelper} purely as the rendered widget, but
- * NOT its click→animate behavior: ViewHelper's built-in snap assumes a Y-up world and animates the
- * camera straight onto the up axis, which in our Z-up scene rolls the view and makes the gizmo jitter
- * at the pole. Instead we hit-test the axis sprites ourselves and drive the viewer's up-aware camera
- * controller, which snaps (no animation) with a pole nudge so the orbit basis never degenerates.
- *
- * Integration points with the viewer's dual-camera setup:
- *  1. The snap frames the current orbit target via the controller, so it rotates about what the user
- *     is looking at (not the world origin).
- *  2. The nav cube is inherently a 3D-orientation tool, so if the viewer is in orthographic (2D) mode
- *     when the gizmo is clicked, we first flip back to perspective.
- *
- * Caller responsibilities (mirror ViewHelper's own contract):
- *  - call {@link ViewGizmo.render} *after* the main scene render each frame (overlay viewport),
- *  - forward pointer clicks to {@link ViewGizmo.handleClick}.
- */
-interface ViewGizmo {
-    render(renderer: THREE.WebGLRenderer): void;
-    /**
-     * @deprecated No-op, kept only for API stability. This wrapper never uses ViewHelper's
-     * click→animate path (see module comment) — view changes snap instantly through the camera
-     * controller — so there is never a gizmo animation to advance. Safe to stop calling.
-     */
-    update(delta: number): void;
-    /** Hit-test a click. Returns true if it hit the gizmo (and a view change started). */
-    handleClick(event: MouseEvent): boolean;
-    /**
-     * @deprecated Always `false`, kept only for API stability. Gizmo clicks snap the view
-     * instantly rather than animating (deliberately — ViewHelper's built-in animation assumes a
-     * Y-up world and rolls the view in this Z-up scene), so there is no animation window to gate
-     * input on.
-     */
-    readonly isAnimating: boolean;
-    /** Show/hide the gizmo at runtime. Hidden = not rendered and not click-hittable. */
-    setVisible(visible: boolean): void;
-    isVisible(): boolean;
-    dispose(): void;
-}
-interface ViewGizmoDeps {
-    /** The perspective (primary) camera the gizmo visualizes and re-orients. */
-    camera: THREE.PerspectiveCamera;
-    domElement: HTMLElement;
-    controller: CameraController;
-}
-declare function createViewGizmo(deps: ViewGizmoDeps): ViewGizmo;
-
-/**
- * An HTML label layer that tracks 3D positions, via three's {@link CSS2DRenderer}. Labels are real
- * DOM nodes (crisp text, CSS-stylable) positioned each frame to follow points in the scene — the
- * foundation for measurement readouts, dimension annotations, and point tags.
- *
- * The CSS2D renderer draws into its own absolutely-positioned DOM overlay stacked on top of the
- * WebGL canvas (pointer-events disabled so it never steals clicks from the viewer). The viewer owns
- * one of these; features like the measure tool add/remove labels through it.
- */
-interface LabelHandle {
-    /** The CSS2DObject in the scene graph. */
-    readonly object: CSS2DObject;
-    /** Move the label to a new world position. */
-    setPosition(position: THREE.Vector3): void;
-    /** Replace the label's text/HTML. */
-    setText(text: string): void;
-    /** Remove the label from the scene and the DOM. */
-    remove(): void;
-}
-interface LabelLayer {
-    /** Create a label at a world position. `className` lets callers theme groups of labels. */
-    addLabel(text: string, position: THREE.Vector3, className?: string): LabelHandle;
-    /** Render the DOM overlay. 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;
-}
-/**
- * @param container element to overlay labels onto — normally the canvas's parent, so the overlay and
- * canvas share a positioning context. The overlay is appended here and absolutely positioned.
- * @param scene labels are parented to a group added to this scene, so they render and follow the
- * camera without the caller wiring scene-graph parenting.
- */
-declare function createLabelLayer(container: HTMLElement, scene: THREE.Scene): LabelLayer;
-
-/**
- * A two-click distance measurement tool — the CAD verb users expect. Click a point, click a second,
- * read the distance off a label on the connecting line; a third click starts a new measurement.
- *
- * Picking snaps to geometry so measurements are exact, not "wherever the ray happened to land":
- * on a mesh hit we snap to the nearest vertex of the struck triangle if it's within
- * {@link MeasureOptions.snapPixels} on screen, else use the raw hit point. This is a cheap local
- * snap (three candidate vertices), no spatial index — enough for clean vertex-to-vertex measurement
- * without the cost/complexity of full edge/midpoint snapping (a later refinement).
- *
- * The tool is dormant until {@link MeasureTool.setEnabled}(true). While enabled it intercepts clicks
- * (the 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;
-    /** Process a click. Returns true if the tool consumed it (caller should not also select). */
-    handleClick(event: MouseEvent): boolean;
-    /**
-     * Process pointer movement to preview the next snap point — a ghost marker tracks the cursor and
-     * jumps to the vertex a click would snap to, so users can aim before committing. No-op when the
-     * tool is disabled. The caller forwards mousemove; nothing is consumed.
-     */
-    handleMove(event: MouseEvent): void;
-    /** Clear the current measurement (markers, line, label). */
-    clear(): void;
-    dispose(): void;
-}
-interface MeasureOptions {
-    /** Snap to a vertex when the cursor is within this many screen pixels of it. Default 12. */
-    snapPixels?: number;
-    /** Marker + line color. Default yellow. */
-    color?: THREE.ColorRepresentation;
-    /** CSS class applied to the distance label, for styling. */
-    labelClassName?: string;
-    /**
-     * The model's unit (pass `data.modelunits`). The scene is in meters, so the default formatter
-     * converts and labels in this unit — e.g. a mm model reads "25.0 mm", not "0.025 m". Defaults
-     * to meters. Ignored when a custom `format` is supplied.
-     */
-    displayUnit?: string;
-    /**
-     * Format the measurement → label text. Receives the straight-line `distance` and the per-axis
-     * `delta` (|b − a| on each axis), both in **meters**. May return multi-line text or HTML; the
-     * default renders the total plus a Δx/Δy/Δz breakdown in `displayUnit`. Overrides `displayUnit`.
-     */
-    format?: (distance: number, delta: THREE.Vector3) => string;
-}
-interface MeasureDeps {
-    canvas: HTMLCanvasElement;
-    scene: THREE.Scene;
-    getActiveCamera: () => THREE.Camera;
-    /**
-     * The current orbit target (e.g. `controls.target`). Used to scale the line/point pick
-     * threshold with the view: the tolerance is a fraction of the camera→target distance, so it
-     * stays roughly constant on screen wherever the user has framed the model. Optional for
-     * backward compatibility — without it the perspective fallback is the camera's distance to the
-     * world origin, which misjudges the threshold for off-origin content. Thread it in when you can.
-     */
-    getViewTarget?: () => THREE.Vector3;
-    labelLayer: LabelLayer;
-    options?: MeasureOptions;
-}
-/**
- * Snap a raycast hit to the nearest geometry vertex within `snapPixels` on screen; otherwise return
- * the raw hit point. Works for meshes (triangle vertices), lines (segment endpoints), and points
- * (the vertex itself). Pure (no DOM) so it's unit-testable: it takes the screen size explicitly
- * rather than reading the canvas. Exported for that reason.
- *
- * Falls back to the raw point for hits without usable vertex indices or positions.
- */
-declare function snapToVertex(hit: THREE.Intersection, camera: THREE.Camera, screenSize: {
-    width: number;
-    height: number;
-}, snapPixels: number): THREE.Vector3;
-declare function createMeasureTool(deps: MeasureDeps): MeasureTool;
-
-/**
- * Initializes a Three.js environment with scene, camera, renderer, and event handling.
- */
-declare const initThree: (canvas: HTMLCanvasElement, options?: ThreeInitializerOptions) => {
-    scene: THREE.Scene;
-    camera: THREE.PerspectiveCamera;
-    controls: OrbitControls;
-    renderer: THREE.WebGLRenderer;
-    cameraController: CameraController;
-    grid: Grid | null;
-    gizmo: ViewGizmo | null;
-    /** Two-click distance measurement tool. Null unless `measure.enabled`; `setEnabled(true)` to use. */
-    measureTool: MeasureTool | null;
-    /**
-     * Attach edge overlays to the meshes under `root` (no-op unless `edges.enabled`). Call after
-     * loading meshes via `updateScene`, since meshes arrive after init. Extraction for large meshes
-     * runs off-thread — their overlays attach a beat later; meshes over `edges.maxTriangles` are
-     * skipped and (by default) covered by the screen-space edge fallback instead.
-     */
-    applyEdges: (root: THREE.Object3D) => void;
-    /**
-     * Remove edge overlays under `root` — the toggle-off counterpart of `applyEdges`. Prefer this
-     * over calling `removeEdges` directly: it also cancels in-flight async attaches' fallout and
-     * stands down the screen-space edge fallback if it was active.
-     */
-    clearEdges: (root: THREE.Object3D) => void;
-    /**
-     * Request a repaint from the on-demand render loop. Camera motion, resizes, pointer input, and
-     * the built-in setters invalidate automatically; call this after mutating the scene externally
-     * (e.g. `updateScene`, adding user geometry) so the change shows immediately rather than on the
-     * next safety repaint. No-op (harmless) when `render.onDemand` is false.
-     */
-    invalidate: () => void;
-    /** Toggle ambient occlusion at runtime — builds or tears down the postprocessing pipeline. */
-    setAmbientOcclusion: (enabled: boolean) => void;
-    /**
-     * Apply a coherent look to the already-loaded scene: 'technical' (matte/CAD — edges, grid, low
-     * IBL, neutral tone mapping) or 'rendered' (presentation — stronger IBL, ACES tone mapping, no
-     * edges). Retunes viewer-owned dials only; per-material parse choices are set via the batch
-     * parser's `material` option. Handy for comparing the two looks in a live viewer.
-     */
-    /**
-     * Switch the viewer to a ready-to-go look at runtime ('studio' | 'technical' | 'showcase'). Retunes
-     * lighting/material only (tone mapping, fill, IBL, AO) — never edges/grid. A straight preset apply:
-     * overwrites any granular lighting dials you set earlier.
-     */
-    setLook: (look: "studio" | "technical" | "showcase") => void;
-    /**
-     * Retune the fill lights at runtime: the direction-aware hemisphere fill (sky/ground) and the flat
-     * ambient. Raising `hemisphereIntensity` is the most effective way to lift shadowed / under-facing
-     * surfaces a dark HDR leaves black. A positive `hemisphereIntensity` 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;
-    /**
-     * Set the uniform multiplier on the HDR's image-based lighting (`scene.environmentIntensity`) at
-     * runtime — normalizes brightness across HDRs of differing exposure so the scene isn't at the
-     * mercy of whichever HDR is loaded. Applies immediately, even before the HDR finishes decoding.
-     */
-    setEnvironmentIntensity: (intensity: number) => void;
-    /** Set renderer tone-mapping exposure at runtime. Higher lifts shadows and overall brightness. */
-    setToneMappingExposure: (exposure: number) => void;
-    /** Set GTAO strength at runtime (0–1). No-op when ambient occlusion isn't active. */
-    setAoIntensity: (intensity: number) => void;
-    /**
-     * The parse-time material options (backface culling, IBL strength) matching the active look — feed
-     * into the batch parser's `material` option so freshly-loaded meshes are built to match it. See
-     * `setLook`.
-     */
-    getMaterialAppearance: () => MaterialAppearanceOptions;
-    /**
-     * Refit the sun's shadow frustum to the current scene content for crisp shadows. Call after
-     * loading or replacing geometry (e.g. after `updateScene`). No-op when sunlight/shadows are off.
-     */
-    updateShadowBounds: () => void;
-    /**
-     * Rescale the grid's cell spacing and fade radius to the current scene content, so parts of any
-     * size get readable cells and a fade that reaches past the model. Call after loading or replacing
-     * geometry (e.g. after `updateScene`). No-op when the grid is off or there's no content.
-     */
-    updateGridScale: () => void;
-    dispose: () => void;
-    fitToView: () => void;
-    clearSelection: () => void;
-    /**
-     * Add caller-owned geometry (lines, annotations, construction aids) to the scene. The object is
-     * tagged `userData.source = 'user'` so it persists across `updateScene` solves instead of being
-     * cleared with compute content. It is treated as normal content for fit-to-view framing.
-     */
-    addUserGeometry: (object: THREE.Object3D) => void;
-    /** Remove a single user-added object and dispose its geometry/materials. */
-    removeUserGeometry: (object: THREE.Object3D) => void;
-    /** Remove and dispose all user-added geometry (every object tagged `source === 'user'`). */
-    clearUserGeometry: () => void;
-};
-
-/** Updates scene with meshes and positions camera on first call. */
-declare function updateScene(scene: THREE.Scene, meshes: THREE.Object3D[], camera: THREE.PerspectiveCamera, controls: OrbitControls, initialPositionSet: boolean): void;
-/** Parses color strings (hex, RGB, CSS names). */
-declare function parseColor(colorString: string): THREE.Color;
-/**
- * Shift objects along one world axis. Defaults to `z` — the up axis of the unified Z-up scene
- * frame (see `../coordinate-transform.ts`), so grounding subtracts the content's lowest z. Pass an
- * explicit axis when the scene is configured with a different `sceneUp`.
- */
-declare function applyOffset(meshes: THREE.Object3D[], offset: number, axis?: 'x' | 'y' | 'z'): void;
-/**
- * Computes the combined world-axis-aligned bounding box of a set of objects (meshes, lines, points).
- * Correctly accounts for transformations (rotation, position, scale).
- */
-declare function computeCombinedBoundingBox(meshes: THREE.Object3D[]): THREE.Box3;
-
-declare const EMISSIVE_MATERIAL: THREE.MeshPhysicalMaterial;
-declare const METAL_MATERIAL: THREE.MeshPhysicalMaterial;
-declare const CONCRETE_MATERIAL: THREE.MeshPhysicalMaterial;
-declare const PLASTIC_MATERIAL: THREE.MeshPhysicalMaterial;
-declare const GLASS_MATERIAL: THREE.MeshPhysicalMaterial;
-declare const RUBBER_MATERIAL: THREE.MeshPhysicalMaterial;
-declare const WOOD_MATERIAL: THREE.MeshPhysicalMaterial;
-/** Shared singleton materials; must not be disposed (rebuilds shaders, frees textures). */
-declare const SHARED_MATERIALS: ReadonlySet<THREE.Material>;
-
-declare const threeMaterials_CONCRETE_MATERIAL: typeof CONCRETE_MATERIAL;
-declare const threeMaterials_EMISSIVE_MATERIAL: typeof EMISSIVE_MATERIAL;
-declare const threeMaterials_GLASS_MATERIAL: typeof GLASS_MATERIAL;
-declare const threeMaterials_METAL_MATERIAL: typeof METAL_MATERIAL;
-declare const threeMaterials_PLASTIC_MATERIAL: typeof PLASTIC_MATERIAL;
-declare const threeMaterials_RUBBER_MATERIAL: typeof RUBBER_MATERIAL;
-declare const threeMaterials_SHARED_MATERIALS: typeof SHARED_MATERIALS;
-declare const threeMaterials_WOOD_MATERIAL: typeof WOOD_MATERIAL;
-declare namespace threeMaterials {
-  export { threeMaterials_CONCRETE_MATERIAL as CONCRETE_MATERIAL, threeMaterials_EMISSIVE_MATERIAL as EMISSIVE_MATERIAL, threeMaterials_GLASS_MATERIAL as GLASS_MATERIAL, threeMaterials_METAL_MATERIAL as METAL_MATERIAL, threeMaterials_PLASTIC_MATERIAL as PLASTIC_MATERIAL, threeMaterials_RUBBER_MATERIAL as RUBBER_MATERIAL, threeMaterials_SHARED_MATERIALS as SHARED_MATERIALS, threeMaterials_WOOD_MATERIAL as WOOD_MATERIAL };
-}
-
-/**
- * The single source of truth for "which way is up, and what do front/right mean" in the viewer.
- *
- * Every up-dependent default (camera framing, sun position, ground offset, view presets) derives
- * from {@link buildUpBasis} instead of hardcoding an axis. Before this module those defaults each
- * spelled out a Z-up vector inline, so a scene configured Y-up got a below-horizon camera and a
- * near-horizontal sun while the presets and floor correctly followed `sceneUp`.
- *
- * ## Why front is -forward
- *
- * The basis returns `forward` = the direction the camera LOOKS (from camera toward model), and the
- * preset positions are the opposite (from target toward camera). Rhino's convention fixes the signs:
- * its Front view looks along +Y, so the camera sits at -Y; its Right view looks along -X, so the
- * camera sits at +X. Deriving `right` as `seed x up` (rather than `up x seed`) is what makes the
- * handedness come out matching Rhino rather than mirrored.
- */
-/** An orthonormal frame derived from a scene up axis. All vectors are unit length. */
-interface UpBasis {
-    /** The scene up axis, normalized. */
-    up: THREE.Vector3;
-    /** The direction a "front" view looks along (from camera toward the model). */
-    forward: THREE.Vector3;
-    /** Completes a right-handed frame with `up` and `forward`. */
-    right: THREE.Vector3;
-}
-/**
- * Derive the ground-plane axes for a given up vector.
- *
- * The seed picks whichever world axis is least parallel to `up`, so the cross products stay
- * well-conditioned in any up convention. For Rhino's Z-up this yields forward = +Y and right = +X,
- * matching Rhino's own Front/Right views; for Three's native Y-up it yields forward = -Z and
- * right = +X, matching Three's convention that the default camera looks down -Z.
- */
-declare function buildUpBasis(up: THREE.Vector3): UpBasis;
-/**
- * The default 3/4 iso camera OFFSET from the target, scaled to `distance`.
- *
- * Placed behind-left and above the model (the conventional architectural 3/4), expressed in the
- * scene's own basis so it reads the same in any up convention. Callers add this to the framing
- * target to get a camera position.
- */
-declare function isoOffset(up: THREE.Vector3, distance: number): THREE.Vector3;
-/**
- * A default sun position: high above the model, offset to one side so surfaces get a directional
- * gradient instead of flat top-down light. Expressed in the scene basis rather than a literal
- * Z-up vector, so a Y-up scene still gets an overhead sun rather than a horizontal one.
- */
-declare function sunOffset(up: THREE.Vector3, sideDistance: number, height: number): THREE.Vector3;
-/**
- * The rotation that puts an equirectangular environment map's horizon on the scene's ground plane.
- *
- * Three's equirect mapping is hardcoded to Y-up: it assumes the HDR's horizon lies in the XZ plane
- * and its zenith points along +Y. In a Z-up scene that leaves the environment on its side — the
- * horizon runs vertically and image-based lighting arrives from +Y rather than from overhead. The
- * result is a subtly wrong key direction that a neutral studio HDR hides but any sky/ground HDR
- * makes obvious.
- *
- * Returns the Euler that rotates the map's native +Y zenith onto `up`. Identity for a Y-up scene.
- * Apply to BOTH `scene.environmentRotation` and `scene.backgroundRotation` — they are independent
- * properties, and setting only one makes the visible background disagree with the lighting.
- */
-declare function environmentRotationFor(up: THREE.Vector3): THREE.Euler;
-/**
- * Which world axis (`'x' | 'y' | 'z'`) the up vector most closely aligns with.
- *
- * Used for the grid plane and for the ground-offset axis — both need a single component index
- * rather than a full vector. An off-axis up vector resolves to its dominant component.
- */
-declare function upToAxis(up: THREE.Vector3): 'x' | 'y' | 'z';
-
-/**
- * Crisp boundary/crease edges overlaid on meshes — the defining "technical drawing" look that makes
- * shaded geometry read as discrete objects rather than blobs.
- *
- * Edge segments are extracted by `extractEdgeSegments` (see edge-extract.ts — an
- * `EdgesGeometry`-equivalent that is ~an order of magnitude faster and worker-portable) and
- * rendered as fat `LineSegments2` using the same `LineMaterial` family as curves — so edges get
- * controllable thickness, not the 1px cap of `THREE.LineSegments`. The overlay is added as a
- * *child* of each mesh, so it inherits the mesh's transform and is disposed when the mesh subtree
- * is cleared.
- *
- * Performance model (docs/plans/4.edge-overlay-performance.md):
- * - Extraction results are cached at two levels: per source `BufferGeometry` (object identity,
- *   helps instanced parts within one solve) and by *content fingerprint* in an LRU — the viewer
- *   rebuilds all geometry objects every solve, so only a content key survives re-solves.
- * - {@link addEdgesAsync} runs extraction for large meshes in a Worker built from a blob URL
- *   (bundler-agnostic; falls back to inline extraction when Workers are unavailable), keeping the
- *   main thread free of the multi-second stalls extraction causes at millions of triangles.
- * - Caps bound the pathological cases: meshes above `maxTriangles` are skipped outright (tagged
- *   `userData.edgesSkipped = 'triangle-cap'`), overlays above `maxSegments` lose the distance
- *   fade so they render in the cheaper opaque pass.
- *
- * Depth strategy: surfaces render at TRUE depth, untouched; the LINES carry a small units-only
- * polygonOffset toward the camera (see EDGE_OFFSET_FACTOR/UNITS).
- *
- * This reverses an earlier strategy that instead pushed each mesh's *surface* back with a
- * slope-scaled offset (factor 1, units 2). That version bled badly: the slope term scales with
- * dZ/dpixel, which is enormous on a surface viewed near edge-on, so grazing faces receded by much
- * more than the millimetre gaps between stacked parts — geometry behind a wall then beat the wall's
- * own receded surface and drew through it. It also clobbered the polygonOffset that look presets
- * configure on their materials, and its "restore" path reset those to 0 rather than to the preset's
- * values.
- *
- * A units-only bias on the lines is bounded by construction: a fixed number of depth quantization
- * steps, independent of viewing angle, so it lifts an edge off its own coplanar surface without ever
- * reaching across to a neighbouring part.
- *
- * The caveat the old strategy correctly identified: a depth ULP grows ~quadratically with viewing
- * distance, so a constant bias is only safe while ULPs stay small. That is what the dynamic
- * near-plane fitter (near-plane.ts) buys — it keeps `camera.near` proportional to the camera↔content
- * gap, holding ULPs at micron scale even zoomed well out. The two mechanisms are load-bearing
- * together; weakening the near fit will make this bias start to bleed.
- */
-interface EdgeOptions {
-    /**
-     * Force a single edge color for every overlay. When omitted (the default), each overlay derives
-     * its color from its own mesh's material — a darkened tint of the surface — so edges read as the
-     * object's own outline rather than a uniform black frame. Meshes with no readable material color
-     * fall back to {@link DEFAULT_EDGE_COLOR}.
-     */
-    color?: THREE.ColorRepresentation;
-    /**
-     * How far to darken the derived edge color toward black, 0–1 (default 0.75). Only applies when
-     * `color` is omitted. Higher = darker edges; 0 leaves edges the surface color, 1 makes them black.
-     */
-    darken?: number;
-    /** Edge thickness in CSS px. Default 1.5. */
-    width?: number;
-    /**
-     * Crease angle in degrees: an edge is kept only where its two faces differ by more than this.
-     * Default 44. Higher = fewer edges (only sharp creases); lower = more (catches gentle bends).
-     */
-    thresholdAngle?: number;
-    /**
-     * Fade an overlay out as its own edges crowd together on screen (default true). Edges draw at a
-     * constant pixel width, so once neighbouring lines sit less than a pixel or two apart they stop
-     * resolving and merge into a dark smear — worst on layered sheet goods, whose millimetre-pitch
-     * laminations are sub-pixel at any normal zoom on a metre-scale part. Fading by edge density
-     * (not by how large the mesh is) returns those parts to a clean shaded read while leaving
-     * sparsely-edged geometry fully drawn at the same distance.
-     */
-    distanceFade?: boolean;
-    /**
-     * Skip meshes above this triangle count entirely (default 4M) — extraction time is linear in
-     * triangles, and past this bound even the worker path burns seconds for a look the screen-space
-     * fallback approximates at constant cost. Skipped meshes are tagged
-     * `userData.edgesSkipped = 'triangle-cap'` so hosts can react (e.g. enable the render-pipeline
-     * edge pass).
-     */
-    maxTriangles?: number;
-    /**
-     * Above this many extracted segments (default 2M), an overlay drops the distance fade so it
-     * renders opaque — millions of blended fat-line quads are a fill-rate cliff; opaque ones aren't.
-     */
-    maxSegments?: number;
-}
-/** Tag on edge overlays so pick/fit/clear logic can recognize and skip or dispose them. */
-declare const EDGE_USERDATA_KIND = "edge-overlay";
-/** `userData.edgesSkipped` value on meshes whose triangle count exceeded {@link EdgeOptions.maxTriangles}. */
-declare const EDGES_SKIPPED_TRIANGLE_CAP = "triangle-cap";
-/** Whether an object is an edge overlay (for pick/fit filters elsewhere). */
-declare function isEdgeOverlay(object: THREE.Object3D): boolean;
-/**
- * Walk an object subtree and attach an edge overlay to every `Mesh` found, returning the created
- * overlays (so callers can dispose them explicitly if they don't clear the whole subtree). Meshes
- * that already carry an overlay are skipped, so this is safe to call more than once.
- *
- * Skips the floor and the grid (they're aids, not content) and anything already tagged as an edge.
- *
- * Fully synchronous — extraction for every mesh runs on the calling thread. Interactive hosts with
- * potentially-large meshes should prefer {@link addEdgesAsync}, which offloads big extractions to
- * a worker.
- */
-declare function addEdges(root: THREE.Object3D, options?: EdgeOptions): LineSegments2[];
-/**
- * Like {@link addEdges}, but extraction for large meshes runs in a Worker so the main thread never
- * stalls. Small meshes (< ~25k triangles) still attach synchronously before this returns — only
- * heavy extractions arrive a beat later. Resolves with every overlay actually attached.
- *
- * Late results are dropped (never attached) when the mesh has left the root's subtree (scene was
- * cleared by a newer solve), the root's edges were removed via {@link removeEdges}, or another
- * apply already attached an overlay to that mesh.
- */
-declare function addEdgesAsync(root: THREE.Object3D, options?: EdgeOptions): Promise<LineSegments2[]>;
-/**
- * Remove every edge overlay under `root`, disposing its geometry and material. The inverse of
- * {@link addEdges}/{@link addEdgesAsync}; together they make edges a live on/off toggle — this
- * also cancels any in-flight async attaches for `root`. Returns how many were removed.
- */
-declare function removeEdges(root: THREE.Object3D): number;
-
-/**
- * Screen-space edge detection: draws crease/silhouette lines by finding depth and normal
- * discontinuities, as a fullscreen pass — cost is O(pixels), independent of triangle count.
- *
- * This is the fallback look for scenes too heavy for geometry edge overlays (see
- * docs/plans/4.edge-overlay-performance.md Phase 3): meshes over `EdgeOptions.maxTriangles` skip
- * extraction, and this pass approximates the technical-drawing read at constant cost. Trade-offs
- * vs geometry edges: uniform pixel width, one global color (no per-object tinting), view-dependent
- * response, and gentle creases below the normal threshold don't register.
- *
- * Works like GTAOPass internally: the scene is re-rendered with a `MeshNormalMaterial` override
- * into a normal target carrying a depth texture (a pattern this scene already tolerates for AO),
- * then a fullscreen shader Roberts-crosses depth (relative view-Z difference, so far scenes don't
- * dissolve into noise) and normals, and blends the edge color over the composed image.
- *
- * The render target is allocated lazily on first enabled render, so constructing the pass
- * disabled costs nothing but the material.
- */
-interface EdgeDetectionOptions {
-    /** Edge line color. Default 0x222222 — matches the geometry overlays' default. */
-    color?: THREE.ColorRepresentation;
-    /** Edge blend strength 0–1. Default 1. */
-    opacity?: number;
-    /**
-     * Normal discontinuity threshold, in summed `1 - dot(n₁, n₂)` across the two diagonal pairs.
-     * Lower catches gentler creases. Default 0.4 (≈ the 44° crease default of geometry edges).
-     */
-    normalThreshold?: number;
-    /** Relative view-depth discontinuity threshold. Default 0.02 (2% of the center depth). */
-    depthThreshold?: number;
-    /** Sample offset in device px — line thickness. Default 1. */
-    thickness?: number;
-}
-declare class EdgeDetectionPass extends Pass {
-    camera: THREE.Camera;
-    private readonly scene;
-    private readonly normalMaterial;
-    private readonly edgeMaterial;
-    private readonly fsQuad;
-    private normalTarget;
-    private width;
-    private height;
-    constructor(scene: THREE.Scene, camera: THREE.Camera, width: number, height: number, options?: EdgeDetectionOptions);
-    private acquireNormalTarget;
-    setSize(width: number, height: number): void;
-    render(renderer: THREE.WebGLRenderer, writeBuffer: THREE.WebGLRenderTarget, readBuffer: THREE.WebGLRenderTarget): void;
-    dispose(): void;
-}
-
-/**
- * Optional postprocessing pipeline. Default-OFF: the viewer only constructs this when a
- * postprocessed feature (ambient occlusion, screen-space edges) is enabled, and otherwise renders
- * with a plain `renderer.render` so the cheap path stays cheap (the chosen tradeoff — see
- * cad-viewer-plan.md).
- *
- * Pipeline: RenderPass → GTAOPass? → EdgeDetectionPass? → SMAAPass → OutputPass. GTAO
- * (ground-truth AO) is the modern replacement for SSAO/SAO — better contact shadows in crevices,
- * the "engineered" depth cue. `screenSpaceRadius` is on so the AO radius is in screen space, which
- * keeps it scale-robust across the viewer's mm→m scenes without per-scene tuning.
- *
- * EdgeDetectionPass draws crease/silhouette lines in screen space at O(pixels) — the fallback for
- * scenes too triangle-heavy for geometry edge overlays (docs/plans/4.edge-overlay-performance.md).
- * It sits before SMAA so its 1px lines get antialiased. Always constructed (its render target is
- * lazy), so it can be toggled at runtime via {@link RenderPipeline.setEdgeDetection} without a
- * pipeline rebuild.
- *
- * SMAA restores antialiasing on this path. The EffectComposer renders into an offscreen target, so
- * the WebGLRenderer's own MSAA (`antialias: true`) does nothing here — without a dedicated AA pass,
- * enabling AO would visibly *worsen* edge quality. SMAA is chosen over TAA because TAA's temporal
- * jitter smears during OrbitControls drags; SMAA is single-frame, cheap, and stable while orbiting.
- *
- * OutputPass applies tone mapping + color space last (taking over the roles the renderer did
- * directly in the non-composer path), so SMAA operates on the pre-tonemapped image as intended.
- *
- * Camera swaps: the active camera can flip perspective↔ortho. Rather than rebuild the composer, we
- * retarget the passes' `camera` each render via {@link setCamera}.
- */
-interface RenderPipeline {
-    render(deltaTime: number): void;
-    setSize(width: number, height: number, pixelRatio: number): void;
-    /** Point the passes at the currently active camera (call when projection changes). */
-    setCamera(camera: THREE.Camera): void;
-    /** Toggle the screen-space edge pass at runtime (no pipeline rebuild). */
-    setEdgeDetection(enabled: boolean): void;
-    /** Whether the screen-space edge pass currently runs. */
-    edgeDetectionEnabled(): boolean;
-    dispose(): void;
-}
-interface RenderPipelineOptions {
-    /** Tone mapping to apply in OutputPass (mirror the renderer's). */
-    toneMapping: THREE.ToneMapping;
-    toneMappingExposure: number;
-    /** Build the pipeline with the GTAO ambient-occlusion pass. Default true. */
-    ambientOcclusion?: boolean;
-    /** AO strength 0–1. Default 1. */
-    aoIntensity?: number;
-    /**
-     * Cap on the device-pixel-ratio used for the composer's (AO) buffers. AO is low-frequency, so
-     * rendering below the display DPR is nearly invisible but far cheaper. `setSize`'s incoming
-     * pixelRatio is clamped to this. Default 1.
-     */
-    aoPixelRatio?: number;
-    /**
-     * Start with the screen-space edge pass enabled; pass an object to tune it. The pass itself is
-     * always constructed (cheap while disabled) so it can be toggled later via `setEdgeDetection`.
-     */
-    edgeDetection?: boolean | EdgeDetectionOptions;
-}
-declare function createRenderPipeline(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera, width: number, height: number, options: RenderPipelineOptions): RenderPipeline;
-
-/**
- * Metres per model unit, keyed by Rhino `UnitSystem` name (the `modelunits` string on the compute
- * response). Imperial factors are the exact international definitions (1 in = 0.0254 m,
- * 1 ft = 0.3048 m, 1 mi = 1609.344 m). Units not in this table scale 1 and log a one-time warning
- * — see {@link getScaleFactor}.
- */
-declare const SCALE_FACTORS: Record<string, number>;
-/**
- * Extracts and processes display meshes from a ComputePointerResponse using the Grasshopper WebDisplay component.
- *
- * This is the primary entry point for extracting mesh geometry from Grasshopper compute responses.
- * It handles all aspects of mesh processing: decompression, coordinate transformation, scaling, and positioning.
- *
- * **Note:** The entire pipeline (base64 decode, inflate, dequantization, mesh construction) runs
- * synchronously on the calling thread — large batches will block the UI for their duration. The
- * function is `async` only so its shape can stay stable if parsing moves off-thread later.
- *
- * @param data - The ComputePointerResponse containing Grasshopper output trees.
- * @param options - Configuration for mesh extraction and parsing behavior. All options are optional with sensible defaults.
- * @returns Promise resolving to array of THREE.Mesh objects (may be empty).
- * @throws Rethrows unexpected errors after attempting to dispose any created meshes.
- *
- * @remarks
- * - Only works with the WebDisplay component of GHHeadless.
- * - Requires changes to Rhino.Compute (see https://github.com/TheVessen/compute.rhino3d).
- * - Provides a performant way to display mesh data in Three.js.
- * - All decoding is synchronous on the main thread; there is no Web Worker offload today.
- * - Supports mesh metadata (names, user data) if provided in the compute response.
- *
- * @internal Internal helper: high-level extraction remains public via visualization module, but this
- * function is considered internal implementation detail for mesh extraction.
- *
- * @example
- * ```ts
- * // Simple usage with defaults (all processing enabled)
- * const meshes = await getThreeMeshesFromComputeResponse(response);
- *
- * // With debugging enabled
- * const meshes = await getThreeMeshesFromComputeResponse(response, { debug: true });
- *
- * // Opt in to seating the model on the grid instead of using its Rhino coordinates
- * const meshes = await getThreeMeshesFromComputeResponse(response, {
- *   debug: true,
- *   allowScaling: true,
- *   allowAutoPosition: true,
- *   parsing: {
- *     mergeByMaterial: false,
- *     applyTransforms: true,
- *     debug: true,
- *   },
- * });
- * ```
- */
-declare function getThreeMeshesFromComputeResponse(data: GrasshopperComputeResponse, options?: MeshExtractionOptions): Promise<THREE.Object3D[]>;
-
-/** Internal telemetry only (not exposed in public options). */
-interface ParseTelemetry {
-    parseTime?: number;
-    perfStart?: number;
-}
-/**
- * Parses a DisplayBatch object and creates Three.js meshes from its mesh blob.
- *
- * The path is synchronous internally — `parseBinaryMeshBatch` does no IO, just typed-array views
- * over the blob. The function stays `async` so callers don't have to change shape if we move
- * parsing into a worker later.
- *
- * A batch with no `compressedData` (genuinely empty/absent geometry) resolves to `[]`. A corrupt,
- * truncated, or unsupported blob throws so callers get a signal instead of a silent empty scene —
- * `getThreeMeshesFromComputeResponse` documents (and now delivers) exactly that rethrow.
- *
- * @param batch - DisplayBatch object
- * @param options - Rendering options
- * @returns Promise resolving to array of Three.js mesh objects
- * @throws {RhinoComputeError} On a corrupt/truncated/unsupported mesh blob or malformed group metadata.
- */
-declare function parseMeshBatchObject(batch: DisplayBatch, options?: MeshBatchParsingOptions, 
-/** @internal Timings threaded from an outer entry point; not a caller option. */
-telemetry?: ParseTelemetry): Promise<THREE.Mesh[]>;
-/**
- * Parses a raw binary mesh batch blob (SLVA wire format) and creates Three.js meshes.
- *
- * Use this entry point when the blob arrives as a binary WebSocket frame (Phase 1b transport):
- * the JSON envelope no longer carries `displayData`, so there's nothing to `JSON.parse`. The blob
- * is self-describing — materials, groups, and `sourceComponentId` come from its embedded metadata
- * header.
- *
- * @param blob - Raw blob bytes from a binary WebSocket frame.
- * @param options - Rendering options.
- * @returns Promise resolving to array of Three.js mesh objects.
- * @throws {RhinoComputeError} On a corrupt/truncated/unsupported mesh blob or malformed group metadata.
- */
-declare function parseMeshBatchBlob(blob: ArrayBuffer | Uint8Array, options?: MeshBatchParsingOptions): Promise<THREE.Mesh[]>;
-
-interface DisplayItemParseOptions {
-    /** rhino3dm instance for decoding curve JSON. Omit to skip curves (points still render). */
-    rhino?: RhinoModule;
-    /**
-     * No-op. Historically toggled the Rhino Z-up → Three Y-up rotation, but the pipeline now keeps
-     * one coordinate frame end to end ({@link rhinoToThree} is the identity), so this flag no longer
-     * changes the result. Do NOT pre-rotate your own geometry to compensate — none is applied.
-     *
-     * @deprecated Retained only so existing call sites compile unchanged; has no effect.
-     */
-    applyTransforms?: boolean;
-}
-/**
- * Parse a batch's `items` into renderable THREE objects. Returns an empty array when there are no
- * items. Unknown kinds are skipped with a warning (forward-compatible with future label/icon kinds
- * a viewer hasn't taught itself to render yet).
- */
-declare function parseDisplayItems(items: DisplayItem[] | undefined, options?: DisplayItemParseOptions): THREE.Object3D[];
-
-export { type CameraConfig, type CameraController, type CameraProjection, type ControlsConfig, DisplayBatch, DisplayItem, type DisplayItemParseOptions, EDGES_SKIPPED_TRIANGLE_CAP, EDGE_USERDATA_KIND, type EdgeDetectionOptions, EdgeDetectionPass, type EdgeOptions, type EdgesConfig, type EnvironmentConfig, type EventConfig, type FloorConfig, type GizmoConfig, type Grid, type GridConfig, type GridOptions, LOOKS, type LabelHandle, type LabelLayer, type LightingConfig, type Look, threeMaterials as Materials, type MeasureConfig, type MeasureOptions, type MeasureTool, MeshExtractionOptions, type RenderConfig, type RenderPipeline, type RenderPipelineOptions, SCALE_FACTORS, type ThreeInitializerOptions, type UpBasis, type ViewGizmo, type ViewPreset, addEdges, addEdgesAsync, applyOffset, buildUpBasis, computeCombinedBoundingBox, createCameraController, createGrid, createLabelLayer, createMeasureTool, createRenderPipeline, createViewGizmo, environmentRotationFor, getThreeMeshesFromComputeResponse, initThree, isEdgeOverlay, isoOffset, parseColor, parseDisplayItems, parseMeshBatchBlob, parseMeshBatchObject, removeEdges, snapToVertex, sunOffset, upToAxis, updateScene };