@selvajs/compute 3.1.0-beta.9 → 3.1.1

package/dist/visualization.d.cts

@@ -1,9 +1,10 @@
 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-C8XWc4Ab.cjs';
-export { q as DisplayCurve, r as DisplayIdentity, s as DisplayItemBase, t as DisplayPoint, u as DisplayPosition, v as MeshBatch } from './types-C8XWc4Ab.cjs';
+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';
 
@@ -13,6 +14,13 @@ type CameraConfig = {
     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;
@@ -40,6 +48,15 @@ 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;
     /**
@@ -81,6 +98,13 @@ type RenderConfig = {
      * 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
@@ -107,12 +131,31 @@ type Look = (typeof LOOKS)[number];
 type EdgesConfig = {
     /** Auto-attach edge overlays to meshes as they load. Default false (opt-in). */
     enabled?: boolean;
-    /** Edge color. Default near-black. */
+    /**
+     * 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 30. */
+    /** 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;
@@ -138,7 +181,11 @@ type GridConfig = {
     majorColor?: THREE.ColorRepresentation;
     /** World radius at which the grid fully fades. Default 100. */
     fadeDistance?: number;
-    /** Plane the grid lies on. 'y' = horizontal ground. Default 'y'. */
+    /**
+     * 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`. */
@@ -275,7 +322,8 @@ interface CameraControllerDeps {
     /**
      * 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. Defaults to Y-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;
 }
@@ -303,7 +351,13 @@ interface GridOptions {
     majorColor?: THREE.ColorRepresentation;
     /** World-space radius at which the grid has fully faded out. Default 100. */
     fadeDistance?: number;
-    /** Plane to lay the grid on. 'y' = horizontal ground (Three Y-up). Default 'y'. */
+    /**
+     * 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 {
@@ -311,6 +365,13 @@ interface Grid {
     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;
 }
@@ -491,9 +552,24 @@ declare const initThree: (canvas: HTMLCanvasElement, options?: ThreeInitializerO
     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.
+     * 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;
     /**
@@ -541,6 +617,12 @@ declare const initThree: (canvas: HTMLCanvasElement, options?: ThreeInitializerO
      * 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;
@@ -562,7 +644,8 @@ declare function updateScene(scene: THREE.Scene, meshes: THREE.Object3D[], camer
 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.
+ * 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;
 /**
@@ -593,54 +676,262 @@ 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.
  *
- * Built with `EdgesGeometry` (which keeps only edges whose adjacent faces meet above a threshold
- * angle, so flat tessellation noise is dropped) rendered as a fat `LineSegments2` using the same
- * `LineMaterial` family as curves (Phase 1) — 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.
+ * 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 {
-    /** Edge color. Default near-black. */
+    /**
+     * 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 30. Higher = fewer edges (only sharp creases); lower = more (catches gentle bends).
+     * 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[];
-/** Whether an object is an edge overlay (for pick/fit filters elsewhere). */
-declare function isEdgeOverlay(object: THREE.Object3D): boolean;
+/**
+ * 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}; together they make edges a live on/off toggle. Returns how many were removed.
+ * {@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;
 
 /**
- * Optional postprocessing pipeline for ambient occlusion. Default-OFF: the viewer only constructs
- * this when `render.ambientOcclusion` is enabled, and otherwise renders with a plain
- * `renderer.render` so the cheap path stays cheap (the chosen tradeoff — see cad-viewer-plan.md).
+ * 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.
  *
- * Pipeline: RenderPass → GTAOPass → 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,
@@ -658,12 +949,18 @@ interface RenderPipeline {
     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;
     /**
@@ -672,6 +969,11 @@ interface RenderPipelineOptions {
      * 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;
 
@@ -715,11 +1017,11 @@ declare const SCALE_FACTORS: Record<string, number>;
  * // With debugging enabled
  * const meshes = await getThreeMeshesFromComputeResponse(response, { debug: true });
  *
- * // With advanced options
+ * // 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: false,
+ *   allowAutoPosition: true,
  *   parsing: {
  *     mergeByMaterial: false,
  *     applyTransforms: true,
@@ -788,4 +1090,4 @@ interface DisplayItemParseOptions {
  */
 declare function parseDisplayItems(items: DisplayItem[] | undefined, options?: DisplayItemParseOptions): THREE.Object3D[];
 
-export { type CameraConfig, type CameraController, type CameraProjection, type ControlsConfig, DisplayBatch, DisplayItem, type DisplayItemParseOptions, EDGE_USERDATA_KIND, 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 ViewGizmo, type ViewPreset, addEdges, applyOffset, computeCombinedBoundingBox, createCameraController, createGrid, createLabelLayer, createMeasureTool, createRenderPipeline, createViewGizmo, getThreeMeshesFromComputeResponse, initThree, isEdgeOverlay, parseColor, parseDisplayItems, parseMeshBatchBlob, parseMeshBatchObject, removeEdges, snapToVertex, updateScene };
+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 };