@selvajs/compute 2.1.0-beta.0 → 2.1.0-beta.1

package/dist/{types-DgepKOuU.d.cts → types-BuRCHPlb.d.cts}

@@ -355,12 +355,17 @@ interface DisplayPosition {
 }
 /**
  * A curve shipped as Rhino-native JSON (`curve.ToNurbsCurve().ToJSON()`), decoded via rhino3dm and
- * tessellated to a `THREE.Line` on the web.
+ * tessellated to a fat `Line2` on the web (so {@link DisplayCurve.width} is honoured).
  */
 interface DisplayCurve extends DisplayItemBase {
     kind: 'curve';
     /** Rhino CommonObject JSON for the curve. */
     json: string;
+    /**
+     * Line thickness in CSS pixels (screen-space, constant regardless of zoom). Rendered via a fat
+     * `Line2`, so unlike `THREE.Line` this is actually honoured. Omitted → viewer default.
+     */
+    width?: number;
 }
 /** A single point, shipped raw (no rhino3dm decode), rendered as one vertex of a `THREE.Points`. */
 interface DisplayPoint extends DisplayItemBase {

package/dist/{types-B6KrSthC.d.ts → types-jPuWWtnU.d.ts}

@@ -355,12 +355,17 @@ interface DisplayPosition {
 }
 /**
  * A curve shipped as Rhino-native JSON (`curve.ToNurbsCurve().ToJSON()`), decoded via rhino3dm and
- * tessellated to a `THREE.Line` on the web.
+ * tessellated to a fat `Line2` on the web (so {@link DisplayCurve.width} is honoured).
  */
 interface DisplayCurve extends DisplayItemBase {
     kind: 'curve';
     /** Rhino CommonObject JSON for the curve. */
     json: string;
+    /**
+     * Line thickness in CSS pixels (screen-space, constant regardless of zoom). Rendered via a fat
+     * `Line2`, so unlike `THREE.Line` this is actually honoured. Omitted → viewer default.
+     */
+    width?: number;
 }
 /** A single point, shipped raw (no rhino3dm decode), rendered as one vertex of a `THREE.Points`. */
 interface DisplayPoint extends DisplayItemBase {

package/dist/visualization-R7QUUUWV.js

@@ -0,0 +1,2 @@
+import{A as u,a as e,b as r,c as o,d as t,e as a,f as s,g as p,h as i,i as n,j as m,k as l,l as f,m as y,n as d,o as h,p as x,q as C,r as g,s as M,t as c,u as B,v as j,w as E,x as D,y as O,z as b}from"./chunk-Z4TVQVMV.js";import"./chunk-GTTKNF4G.js";export{M as BINARY_MESH_MAGIC,c as BINARY_MESH_VERSION,i as EDGE_USERDATA_KIND,B as FLAG_FLOAT32,C as Materials,b as SCALE_FACTORS,n as addEdges,o as applyOffset,t as computeCombinedBoundingBox,a as createCameraController,s as createGrid,y as createLabelLayer,h as createMeasureTool,f as createRenderPipeline,p as createViewGizmo,u as getThreeMeshesFromComputeResponse,x as initThree,m as isEdgeOverlay,j as parseBinaryMeshBatch,r as parseColor,g as parseDisplayItems,E as parseMeshBatch,O as parseMeshBatchBlob,D as parseMeshBatchObject,l as removeEdges,d as snapToVertex,e as updateScene};
+//# sourceMappingURL=visualization-R7QUUUWV.js.map

package/dist/visualization-ZDXKGD2L.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkJPXUC3P5cjs = require('./chunk-JPXUC3P5.cjs');require('./chunk-MA6YB3YZ.cjs');exports.BINARY_MESH_MAGIC = _chunkJPXUC3P5cjs.s; exports.BINARY_MESH_VERSION = _chunkJPXUC3P5cjs.t; exports.EDGE_USERDATA_KIND = _chunkJPXUC3P5cjs.h; exports.FLAG_FLOAT32 = _chunkJPXUC3P5cjs.u; exports.Materials = _chunkJPXUC3P5cjs.q; exports.SCALE_FACTORS = _chunkJPXUC3P5cjs.z; exports.addEdges = _chunkJPXUC3P5cjs.i; exports.applyOffset = _chunkJPXUC3P5cjs.c; exports.computeCombinedBoundingBox = _chunkJPXUC3P5cjs.d; exports.createCameraController = _chunkJPXUC3P5cjs.e; exports.createGrid = _chunkJPXUC3P5cjs.f; exports.createLabelLayer = _chunkJPXUC3P5cjs.m; exports.createMeasureTool = _chunkJPXUC3P5cjs.o; exports.createRenderPipeline = _chunkJPXUC3P5cjs.l; exports.createViewGizmo = _chunkJPXUC3P5cjs.g; exports.getThreeMeshesFromComputeResponse = _chunkJPXUC3P5cjs.A; exports.initThree = _chunkJPXUC3P5cjs.p; exports.isEdgeOverlay = _chunkJPXUC3P5cjs.j; exports.parseBinaryMeshBatch = _chunkJPXUC3P5cjs.v; exports.parseColor = _chunkJPXUC3P5cjs.b; exports.parseDisplayItems = _chunkJPXUC3P5cjs.r; exports.parseMeshBatch = _chunkJPXUC3P5cjs.w; exports.parseMeshBatchBlob = _chunkJPXUC3P5cjs.y; exports.parseMeshBatchObject = _chunkJPXUC3P5cjs.x; exports.removeEdges = _chunkJPXUC3P5cjs.k; exports.snapToVertex = _chunkJPXUC3P5cjs.n; exports.updateScene = _chunkJPXUC3P5cjs.a;
+//# sourceMappingURL=visualization-ZDXKGD2L.cjs.map

package/dist/visualization-ZDXKGD2L.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/selva-compute/selva-compute/dist/visualization-ZDXKGD2L.cjs"],"names":[],"mappings":"AAAA,iIAA8N,gCAA6B,owCAA+kB","file":"/home/runner/work/selva-compute/selva-compute/dist/visualization-ZDXKGD2L.cjs"}

package/dist/visualization.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkKAULD2XQcjs = require('./chunk-KAULD2XQ.cjs');require('./chunk-MA6YB3YZ.cjs');exports.Materials = _chunkKAULD2XQcjs.f; exports.SCALE_FACTORS = _chunkKAULD2XQcjs.o; exports.getThreeMeshesFromComputeResponse = _chunkKAULD2XQcjs.p; exports.initThree = _chunkKAULD2XQcjs.a; exports.parseDisplayItems = _chunkKAULD2XQcjs.g; exports.parseMeshBatchBlob = _chunkKAULD2XQcjs.n; exports.parseMeshBatchObject = _chunkKAULD2XQcjs.m; exports.updateScene = _chunkKAULD2XQcjs.b;
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkJPXUC3P5cjs = require('./chunk-JPXUC3P5.cjs');require('./chunk-MA6YB3YZ.cjs');exports.Materials = _chunkJPXUC3P5cjs.q; exports.SCALE_FACTORS = _chunkJPXUC3P5cjs.z; exports.getThreeMeshesFromComputeResponse = _chunkJPXUC3P5cjs.A; exports.initThree = _chunkJPXUC3P5cjs.p; exports.parseDisplayItems = _chunkJPXUC3P5cjs.r; exports.parseMeshBatchBlob = _chunkJPXUC3P5cjs.y; exports.parseMeshBatchObject = _chunkJPXUC3P5cjs.x; exports.updateScene = _chunkJPXUC3P5cjs.a;
 //# sourceMappingURL=visualization.cjs.map

package/dist/visualization.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["c:\\Users\\felix\\coding\\selva-compute\\dist\\visualization.cjs"],"names":[],"mappings":"AAAA,iIAAoF,gCAA6B,iYAA0L","file":"C:\\Users\\felix\\coding\\selva-compute\\dist\\visualization.cjs"}
+{"version":3,"sources":["/home/runner/work/selva-compute/selva-compute/dist/visualization.cjs"],"names":[],"mappings":"AAAA,iIAAyF,gCAA6B,iYAA0L","file":"/home/runner/work/selva-compute/selva-compute/dist/visualization.cjs"}

package/dist/visualization.d.cts

@@ -1,7 +1,7 @@
 import * as THREE from 'three';
 import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
-import { f as GrasshopperComputeResponse, M as MeshExtractionOptions, m as MeshBatchParsingOptions, n as DisplayBatch, o as DisplayItem } from './types-DgepKOuU.cjs';
-export { p as DisplayCurve, q as DisplayIdentity, r as DisplayItemBase, s as DisplayPoint, t as DisplayPosition, u as MeshBatch } from './types-DgepKOuU.cjs';
+import { f as GrasshopperComputeResponse, M as MeshExtractionOptions, m as MeshBatchParsingOptions, n as DisplayBatch, o as DisplayItem } from './types-BuRCHPlb.cjs';
+export { p as DisplayCurve, q as DisplayIdentity, r as DisplayItemBase, s as DisplayPoint, t as DisplayPosition, u as MeshBatch } from './types-BuRCHPlb.cjs';
 import { RhinoModule } from 'rhino3dm';
 import './types-D1SkNje_.cjs';
 
@@ -43,6 +43,24 @@ type RenderConfig = {
     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;
+};
+/** 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;
+    /** Edge color. Default near-black. */
+    color?: THREE.ColorRepresentation;
+    /** Edge thickness in CSS px. Default 1.5. */
+    width?: number;
+    /** Crease angle (degrees): keep edges where faces differ by more than this. Default 30. */
+    thresholdAngle?: number;
 };
 type ControlsConfig = {
     enableDamping?: boolean;
@@ -54,6 +72,44 @@ type ControlsConfig = {
     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;
+    /** Plane the grid lies on. 'y' = horizontal ground. Default 'y'. */
+    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;
+    /** Format the distance number → label text. Default 3 sig-digits + " m". */
+    format?: (distance: number) => string;
+};
 type ThreeInitializerOptions = {
     sceneScale?: 'mm' | 'cm' | 'm' | 'inches' | 'feet';
     camera?: CameraConfig;
@@ -62,6 +118,10 @@ type ThreeInitializerOptions = {
     floor?: FloorConfig;
     render?: RenderConfig;
     controls?: ControlsConfig;
+    grid?: GridConfig;
+    gizmo?: GizmoConfig;
+    edges?: EdgesConfig;
+    measure?: MeasureConfig;
     events?: EventConfig;
 };
 type EventConfig = {
@@ -88,6 +148,105 @@ type EventConfig = {
     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;
+    /** 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;
+}
+
+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;
+    setVisible(visible: boolean): void;
+    dispose(): void;
+}
+
+/**
+ * The corner nav-cube/axis gizmo. Wraps three's {@link ViewHelper} (the standard, well-tested
+ * widget) and uses its built-in click → animate behavior, which we keep rather than reimplement:
+ * ViewHelper's hit-test depends on private internals (`dim`, `interactiveObjects`, viewport math),
+ * so replicating it is fragile. We let it drive the perspective camera directly.
+ *
+ * Two integration points with the viewer's dual-camera setup:
+ *  1. Before each click we point `helper.center` at the live orbit target, so the snap rotates about
+ *     what the user is looking at (not the world origin).
+ *  2. ViewHelper only drives the perspective camera. 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 — then ViewHelper animates as usual. Using the cube returns you to 3D.
+ *
+ * Caller responsibilities (mirror ViewHelper's own contract):
+ *  - call {@link ViewGizmo.render} *after* the main scene render each frame (overlay viewport),
+ *  - call {@link ViewGizmo.update} each frame with the frame delta (drives the snap animation),
+ *  - forward pointer clicks to {@link ViewGizmo.handleClick}.
+ */
+interface ViewGizmo {
+    render(renderer: THREE.WebGLRenderer): void;
+    update(delta: number): void;
+    /** Hit-test a click. Returns true if it hit the gizmo (and a view change started). */
+    handleClick(event: MouseEvent): boolean;
+    readonly isAnimating: boolean;
+    /** Show/hide the gizmo at runtime. Hidden = not rendered and not click-hittable. */
+    setVisible(visible: boolean): void;
+    isVisible(): boolean;
+    dispose(): void;
+}
+
+/**
+ * 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;
+    /** Clear the current measurement (markers, line, label). */
+    clear(): void;
+    dispose(): void;
+}
+
 /**
  * Initializes a Three.js environment with scene, camera, renderer, and event handling.
  */
@@ -96,6 +255,18 @@ declare const initThree: (canvas: HTMLCanvasElement, options?: ThreeInitializerO
     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.
+     */
+    applyEdges: (root: THREE.Object3D) => void;
+    /** Toggle ambient occlusion at runtime — builds or tears down the postprocessing pipeline. */
+    setAmbientOcclusion: (enabled: boolean) => void;
     dispose: () => void;
     fitToView: () => void;
     clearSelection: () => void;

package/dist/visualization.d.ts

@@ -1,7 +1,7 @@
 import * as THREE from 'three';
 import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
-import { f as GrasshopperComputeResponse, M as MeshExtractionOptions, m as MeshBatchParsingOptions, n as DisplayBatch, o as DisplayItem } from './types-B6KrSthC.js';
-export { p as DisplayCurve, q as DisplayIdentity, r as DisplayItemBase, s as DisplayPoint, t as DisplayPosition, u as MeshBatch } from './types-B6KrSthC.js';
+import { f as GrasshopperComputeResponse, M as MeshExtractionOptions, m as MeshBatchParsingOptions, n as DisplayBatch, o as DisplayItem } from './types-jPuWWtnU.js';
+export { p as DisplayCurve, q as DisplayIdentity, r as DisplayItemBase, s as DisplayPoint, t as DisplayPosition, u as MeshBatch } from './types-jPuWWtnU.js';
 import { RhinoModule } from 'rhino3dm';
 import './types-D1SkNje_.js';
 
@@ -43,6 +43,24 @@ type RenderConfig = {
     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;
+};
+/** 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;
+    /** Edge color. Default near-black. */
+    color?: THREE.ColorRepresentation;
+    /** Edge thickness in CSS px. Default 1.5. */
+    width?: number;
+    /** Crease angle (degrees): keep edges where faces differ by more than this. Default 30. */
+    thresholdAngle?: number;
 };
 type ControlsConfig = {
     enableDamping?: boolean;
@@ -54,6 +72,44 @@ type ControlsConfig = {
     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;
+    /** Plane the grid lies on. 'y' = horizontal ground. Default 'y'. */
+    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;
+    /** Format the distance number → label text. Default 3 sig-digits + " m". */
+    format?: (distance: number) => string;
+};
 type ThreeInitializerOptions = {
     sceneScale?: 'mm' | 'cm' | 'm' | 'inches' | 'feet';
     camera?: CameraConfig;
@@ -62,6 +118,10 @@ type ThreeInitializerOptions = {
     floor?: FloorConfig;
     render?: RenderConfig;
     controls?: ControlsConfig;
+    grid?: GridConfig;
+    gizmo?: GizmoConfig;
+    edges?: EdgesConfig;
+    measure?: MeasureConfig;
     events?: EventConfig;
 };
 type EventConfig = {
@@ -88,6 +148,105 @@ type EventConfig = {
     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;
+    /** 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;
+}
+
+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;
+    setVisible(visible: boolean): void;
+    dispose(): void;
+}
+
+/**
+ * The corner nav-cube/axis gizmo. Wraps three's {@link ViewHelper} (the standard, well-tested
+ * widget) and uses its built-in click → animate behavior, which we keep rather than reimplement:
+ * ViewHelper's hit-test depends on private internals (`dim`, `interactiveObjects`, viewport math),
+ * so replicating it is fragile. We let it drive the perspective camera directly.
+ *
+ * Two integration points with the viewer's dual-camera setup:
+ *  1. Before each click we point `helper.center` at the live orbit target, so the snap rotates about
+ *     what the user is looking at (not the world origin).
+ *  2. ViewHelper only drives the perspective camera. 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 — then ViewHelper animates as usual. Using the cube returns you to 3D.
+ *
+ * Caller responsibilities (mirror ViewHelper's own contract):
+ *  - call {@link ViewGizmo.render} *after* the main scene render each frame (overlay viewport),
+ *  - call {@link ViewGizmo.update} each frame with the frame delta (drives the snap animation),
+ *  - forward pointer clicks to {@link ViewGizmo.handleClick}.
+ */
+interface ViewGizmo {
+    render(renderer: THREE.WebGLRenderer): void;
+    update(delta: number): void;
+    /** Hit-test a click. Returns true if it hit the gizmo (and a view change started). */
+    handleClick(event: MouseEvent): boolean;
+    readonly isAnimating: boolean;
+    /** Show/hide the gizmo at runtime. Hidden = not rendered and not click-hittable. */
+    setVisible(visible: boolean): void;
+    isVisible(): boolean;
+    dispose(): void;
+}
+
+/**
+ * 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;
+    /** Clear the current measurement (markers, line, label). */
+    clear(): void;
+    dispose(): void;
+}
+
 /**
  * Initializes a Three.js environment with scene, camera, renderer, and event handling.
  */
@@ -96,6 +255,18 @@ declare const initThree: (canvas: HTMLCanvasElement, options?: ThreeInitializerO
     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.
+     */
+    applyEdges: (root: THREE.Object3D) => void;
+    /** Toggle ambient occlusion at runtime — builds or tears down the postprocessing pipeline. */
+    setAmbientOcclusion: (enabled: boolean) => void;
     dispose: () => void;
     fitToView: () => void;
     clearSelection: () => void;

package/dist/visualization.js

@@ -1,2 +1,2 @@
-import{a as e,b as t,f as i,g as s,m as o,n as a,o as r,p}from"./chunk-SP73WPYA.js";import"./chunk-GTTKNF4G.js";export{i as Materials,r as SCALE_FACTORS,p as getThreeMeshesFromComputeResponse,e as initThree,s as parseDisplayItems,a as parseMeshBatchBlob,o as parseMeshBatchObject,t as updateScene};
+import{A as p,a as e,p as t,q as i,r as s,x as o,y as a,z as r}from"./chunk-Z4TVQVMV.js";import"./chunk-GTTKNF4G.js";export{i as Materials,r as SCALE_FACTORS,p as getThreeMeshesFromComputeResponse,t as initThree,s as parseDisplayItems,a as parseMeshBatchBlob,o as parseMeshBatchObject,e as updateScene};
 //# sourceMappingURL=visualization.js.map