@selvajs/compute 2.0.0 → 2.1.0-beta.1

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

@@ -1,4 +1,5 @@
 import { C as ComputeConfig, a as RhinoModelUnit } from './types-D1SkNje_.cjs';
+import { RhinoModule } from 'rhino3dm';
 
 /**
  * Grasshopper types
@@ -310,6 +311,75 @@ interface GrasshopperParsedIO {
     loadErrors?: string[];
 }
 
+/**
+ * Non-mesh display items: curves, points, and later labels/icons.
+ *
+ * These ride as JSON inside a {@link DisplayBatch} alongside the binary mesh blob — they are a
+ * separate pipeline from the SLVA mesh path in `../webdisplay`. Curves arrive as Rhino-native JSON
+ * (decoded via rhino3dm and tessellated on the web); points arrive as raw `{X,Y,Z}` positions.
+ *
+ * The union is STRICT and discriminated on `kind`. The parser narrows on it and uses a
+ * `never`-exhaustiveness check, so adding a new kind is a compile error until it is handled.
+ */
+/**
+ * Identity + tagging shared by every display thing — meshes (via an adapter over `MeshMetadata`)
+ * and items alike — so pick / filter / label code treats them uniformly. Deliberately excludes
+ * rendering concerns (color/material): those differ by kind and are not identity.
+ */
+interface DisplayIdentity {
+    /** Stable pick key. Both meshes and items synthesize it as `${sourceComponentId}:${originalIndex}`. */
+    id: string;
+    /** Human label (e.g. "North wall"). Distinct from {@link id} — renaming must not change identity. */
+    name: string;
+    /** Layer path for grouping in the scene manager (e.g. "Structure/Walls"). */
+    layer: string;
+    /** Arbitrary key-value pairs from the GH Metadata input. */
+    metadata?: Record<string, string>;
+}
+/**
+ * Style fields every visible item can honour. Lines and points have no PBR (no metalness/roughness),
+ * so only color + opacity apply here; a future kind that needs richer material adds fields to its own
+ * variant rather than bloating this base.
+ */
+interface DisplayItemBase extends DisplayIdentity {
+    /** Hex/rgb/named color string, parsed by `parseColor`. Falls back to a viewer default. */
+    color?: string;
+    /** Opacity 0–1. Omitted means fully opaque. */
+    opacity?: number;
+}
+/** A world position in Rhino's Z-up frame, in Rhino's `{X,Y,Z}` casing. Rotated to Three on parse. */
+interface DisplayPosition {
+    X: number;
+    Y: number;
+    Z: number;
+}
+/**
+ * A curve shipped as Rhino-native JSON (`curve.ToNurbsCurve().ToJSON()`), decoded via rhino3dm and
+ * 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 {
+    kind: 'point';
+    /** World position in Rhino Z-up; the shared Rhino→Three transform is applied on parse. */
+    position: DisplayPosition;
+}
+/**
+ * One non-mesh display item. Meshes do NOT appear here — they ride the binary blob in `DisplayBatch`.
+ * New kinds (`label`, `icon`) extend this union and add a parser case; the parser's `never` guard
+ * forces them to be handled.
+ */
+type DisplayItem = DisplayCurve | DisplayPoint;
+
 /**
  * Material properties for Three.js rendering.
  */
@@ -359,14 +429,18 @@ interface MaterialGroup {
     meshes: MeshMetadata[];
 }
 /**
- * Batched mesh data optimized for Three.js rendering.
+ * One Display component's payload, ready for Three.js rendering.
  *
  * `compressedData` contains the binary "SLVA" blob (header + metadata JSON + quantized int16 or
  * float32 vertices + uint32 indices), base64-encoded for transit inside the values JSON envelope.
  * The blob is opaque to the outer JSON: a future binary WebSocket frame can drop the base64 step
  * without changing this shape.
+ *
+ * Today this carries only meshes (the binary blob). It is named `DisplayBatch` rather than
+ * `MeshBatch` because it is the seam through which non-mesh display items (curves, points, and
+ * later labels/icons) also travel — those ride as JSON alongside the mesh blob, not inside it.
  */
-interface MeshBatch {
+interface DisplayBatch {
     /** Array of unique materials */
     materials: SerializableMaterial[];
     /** Groups of meshes organized by material */
@@ -376,7 +450,19 @@ interface MeshBatch {
     /** InstanceGuid of the WebDisplay GH component that produced this batch.
      *  Combined with MeshMetadata.originalIndex to backtrack any mesh to its GH source. */
     sourceComponentId?: string;
+    /**
+     * Non-mesh display items (curves, points; later labels/icons) — see {@link DisplayItem}.
+     * Optional: omitted when there are none, so mesh-only batches are unchanged on the wire. These
+     * ride as JSON alongside the mesh blob and are parsed by the separate `display-items` path, not
+     * the SLVA mesh parser.
+     */
+    items?: DisplayItem[];
 }
+/**
+ * @deprecated Renamed to {@link DisplayBatch} — the payload now carries more than meshes.
+ * This alias keeps existing imports compiling; remove it once consumers migrate.
+ */
+type MeshBatch = DisplayBatch;
 /**
  * Options for parsing mesh batch data.
  */
@@ -398,8 +484,13 @@ interface MeshExtractionOptions {
     allowScaling?: boolean;
     /** Apply automatic ground offset positioning (Z=0). Defaults to true. */
     allowAutoPosition?: boolean;
+    /**
+     * rhino3dm instance for decoding curve display items. selva-compute does not own the WASM
+     * instance; the host threads it in. Omit to skip curves (points still render).
+     */
+    rhino?: RhinoModule;
     /** Enable verbose logging. Defaults to false. */
     debug?: boolean;
 }
 
-export type { BooleanInputType as B, DataItem as D, FileInputType as F, GeometryInputType as G, InnerTreeData as I, MeshExtractionOptions as M, NumericInputType as N, OutputParamSchema as O, TextInputType as T, ValueListInputType as V, DataTree as a, DataTreeDefault as b, DataTreePath as c, DefaultValue as d, GrasshopperComputeConfig as e, GrasshopperComputeResponse as f, GrasshopperParsedIO as g, GrasshopperParsedIORaw as h, GrasshopperRequestSchema as i, InputParam as j, InputParamSchema as k, OutputType as l, MeshBatchParsingOptions as m, MeshBatch as n };
+export type { BooleanInputType as B, DataItem as D, FileInputType as F, GeometryInputType as G, InnerTreeData as I, MeshExtractionOptions as M, NumericInputType as N, OutputParamSchema as O, TextInputType as T, ValueListInputType as V, DataTree as a, DataTreeDefault as b, DataTreePath as c, DefaultValue as d, GrasshopperComputeConfig as e, GrasshopperComputeResponse as f, GrasshopperParsedIO as g, GrasshopperParsedIORaw as h, GrasshopperRequestSchema as i, InputParam as j, InputParamSchema as k, OutputType as l, MeshBatchParsingOptions as m, DisplayBatch as n, DisplayItem as o, DisplayCurve as p, DisplayIdentity as q, DisplayItemBase as r, DisplayPoint as s, DisplayPosition as t, MeshBatch as u };

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

@@ -1,4 +1,5 @@
 import { C as ComputeConfig, a as RhinoModelUnit } from './types-D1SkNje_.js';
+import { RhinoModule } from 'rhino3dm';
 
 /**
  * Grasshopper types
@@ -310,6 +311,75 @@ interface GrasshopperParsedIO {
     loadErrors?: string[];
 }
 
+/**
+ * Non-mesh display items: curves, points, and later labels/icons.
+ *
+ * These ride as JSON inside a {@link DisplayBatch} alongside the binary mesh blob — they are a
+ * separate pipeline from the SLVA mesh path in `../webdisplay`. Curves arrive as Rhino-native JSON
+ * (decoded via rhino3dm and tessellated on the web); points arrive as raw `{X,Y,Z}` positions.
+ *
+ * The union is STRICT and discriminated on `kind`. The parser narrows on it and uses a
+ * `never`-exhaustiveness check, so adding a new kind is a compile error until it is handled.
+ */
+/**
+ * Identity + tagging shared by every display thing — meshes (via an adapter over `MeshMetadata`)
+ * and items alike — so pick / filter / label code treats them uniformly. Deliberately excludes
+ * rendering concerns (color/material): those differ by kind and are not identity.
+ */
+interface DisplayIdentity {
+    /** Stable pick key. Both meshes and items synthesize it as `${sourceComponentId}:${originalIndex}`. */
+    id: string;
+    /** Human label (e.g. "North wall"). Distinct from {@link id} — renaming must not change identity. */
+    name: string;
+    /** Layer path for grouping in the scene manager (e.g. "Structure/Walls"). */
+    layer: string;
+    /** Arbitrary key-value pairs from the GH Metadata input. */
+    metadata?: Record<string, string>;
+}
+/**
+ * Style fields every visible item can honour. Lines and points have no PBR (no metalness/roughness),
+ * so only color + opacity apply here; a future kind that needs richer material adds fields to its own
+ * variant rather than bloating this base.
+ */
+interface DisplayItemBase extends DisplayIdentity {
+    /** Hex/rgb/named color string, parsed by `parseColor`. Falls back to a viewer default. */
+    color?: string;
+    /** Opacity 0–1. Omitted means fully opaque. */
+    opacity?: number;
+}
+/** A world position in Rhino's Z-up frame, in Rhino's `{X,Y,Z}` casing. Rotated to Three on parse. */
+interface DisplayPosition {
+    X: number;
+    Y: number;
+    Z: number;
+}
+/**
+ * A curve shipped as Rhino-native JSON (`curve.ToNurbsCurve().ToJSON()`), decoded via rhino3dm and
+ * 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 {
+    kind: 'point';
+    /** World position in Rhino Z-up; the shared Rhino→Three transform is applied on parse. */
+    position: DisplayPosition;
+}
+/**
+ * One non-mesh display item. Meshes do NOT appear here — they ride the binary blob in `DisplayBatch`.
+ * New kinds (`label`, `icon`) extend this union and add a parser case; the parser's `never` guard
+ * forces them to be handled.
+ */
+type DisplayItem = DisplayCurve | DisplayPoint;
+
 /**
  * Material properties for Three.js rendering.
  */
@@ -359,14 +429,18 @@ interface MaterialGroup {
     meshes: MeshMetadata[];
 }
 /**
- * Batched mesh data optimized for Three.js rendering.
+ * One Display component's payload, ready for Three.js rendering.
  *
  * `compressedData` contains the binary "SLVA" blob (header + metadata JSON + quantized int16 or
  * float32 vertices + uint32 indices), base64-encoded for transit inside the values JSON envelope.
  * The blob is opaque to the outer JSON: a future binary WebSocket frame can drop the base64 step
  * without changing this shape.
+ *
+ * Today this carries only meshes (the binary blob). It is named `DisplayBatch` rather than
+ * `MeshBatch` because it is the seam through which non-mesh display items (curves, points, and
+ * later labels/icons) also travel — those ride as JSON alongside the mesh blob, not inside it.
  */
-interface MeshBatch {
+interface DisplayBatch {
     /** Array of unique materials */
     materials: SerializableMaterial[];
     /** Groups of meshes organized by material */
@@ -376,7 +450,19 @@ interface MeshBatch {
     /** InstanceGuid of the WebDisplay GH component that produced this batch.
      *  Combined with MeshMetadata.originalIndex to backtrack any mesh to its GH source. */
     sourceComponentId?: string;
+    /**
+     * Non-mesh display items (curves, points; later labels/icons) — see {@link DisplayItem}.
+     * Optional: omitted when there are none, so mesh-only batches are unchanged on the wire. These
+     * ride as JSON alongside the mesh blob and are parsed by the separate `display-items` path, not
+     * the SLVA mesh parser.
+     */
+    items?: DisplayItem[];
 }
+/**
+ * @deprecated Renamed to {@link DisplayBatch} — the payload now carries more than meshes.
+ * This alias keeps existing imports compiling; remove it once consumers migrate.
+ */
+type MeshBatch = DisplayBatch;
 /**
  * Options for parsing mesh batch data.
  */
@@ -398,8 +484,13 @@ interface MeshExtractionOptions {
     allowScaling?: boolean;
     /** Apply automatic ground offset positioning (Z=0). Defaults to true. */
     allowAutoPosition?: boolean;
+    /**
+     * rhino3dm instance for decoding curve display items. selva-compute does not own the WASM
+     * instance; the host threads it in. Omit to skip curves (points still render).
+     */
+    rhino?: RhinoModule;
     /** Enable verbose logging. Defaults to false. */
     debug?: boolean;
 }
 
-export type { BooleanInputType as B, DataItem as D, FileInputType as F, GeometryInputType as G, InnerTreeData as I, MeshExtractionOptions as M, NumericInputType as N, OutputParamSchema as O, TextInputType as T, ValueListInputType as V, DataTree as a, DataTreeDefault as b, DataTreePath as c, DefaultValue as d, GrasshopperComputeConfig as e, GrasshopperComputeResponse as f, GrasshopperParsedIO as g, GrasshopperParsedIORaw as h, GrasshopperRequestSchema as i, InputParam as j, InputParamSchema as k, OutputType as l, MeshBatchParsingOptions as m, MeshBatch as n };
+export type { BooleanInputType as B, DataItem as D, FileInputType as F, GeometryInputType as G, InnerTreeData as I, MeshExtractionOptions as M, NumericInputType as N, OutputParamSchema as O, TextInputType as T, ValueListInputType as V, DataTree as a, DataTreeDefault as b, DataTreePath as c, DefaultValue as d, GrasshopperComputeConfig as e, GrasshopperComputeResponse as f, GrasshopperParsedIO as g, GrasshopperParsedIORaw as h, GrasshopperRequestSchema as i, InputParam as j, InputParamSchema as k, OutputType as l, MeshBatchParsingOptions as m, DisplayBatch as n, DisplayItem as o, DisplayCurve as p, DisplayIdentity as q, DisplayItemBase as r, DisplayPoint as s, DisplayPosition as t, MeshBatch as u };

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 _chunkJFLD2UCYcjs = require('./chunk-JFLD2UCY.cjs');require('./chunk-MA6YB3YZ.cjs');exports.Materials = _chunkJFLD2UCYcjs.f; exports.SCALE_FACTORS = _chunkJFLD2UCYcjs.n; exports.getThreeMeshesFromComputeResponse = _chunkJFLD2UCYcjs.o; exports.initThree = _chunkJFLD2UCYcjs.a; exports.parseMeshBatchBlob = _chunkJFLD2UCYcjs.m; exports.parseMeshBatchObject = _chunkJFLD2UCYcjs.l; exports.updateScene = _chunkJFLD2UCYcjs.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":["/home/runner/work/selva-compute/selva-compute/dist/visualization.cjs"],"names":[],"mappings":"AAAA,iIAA6E,gCAA6B,gVAAmK","file":"/home/runner/work/selva-compute/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,6 +1,8 @@
 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 MeshBatch } from './types-CJ092lxB.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';
 
 type CameraConfig = {
@@ -41,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;
@@ -52,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;
@@ -60,6 +118,10 @@ type ThreeInitializerOptions = {
     floor?: FloorConfig;
     render?: RenderConfig;
     controls?: ControlsConfig;
+    grid?: GridConfig;
+    gizmo?: GizmoConfig;
+    edges?: EdgesConfig;
+    measure?: MeasureConfig;
     events?: EventConfig;
 };
 type EventConfig = {
@@ -86,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.
  */
@@ -94,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;
@@ -108,7 +281,7 @@ declare const initThree: (canvas: HTMLCanvasElement, options?: ThreeInitializerO
  * @param controls - The OrbitControls object to update.
  * @param initialPositionSet - A boolean indicating whether the initial position of the camera and controls have been set.
  */
-declare function updateScene(scene: THREE.Scene, meshes: THREE.Mesh[], camera: THREE.PerspectiveCamera, controls: OrbitControls, initialPositionSet: boolean): void;
+declare function updateScene(scene: THREE.Scene, meshes: THREE.Object3D[], camera: THREE.PerspectiveCamera, controls: OrbitControls, initialPositionSet: boolean): void;
 
 declare const EMISSIVE_MATERIAL: THREE.MeshPhysicalMaterial;
 declare const METAL_MATERIAL: THREE.MeshPhysicalMaterial;
@@ -174,7 +347,7 @@ declare const SCALE_FACTORS: Record<string, number>;
  * });
  * ```
  */
-declare function getThreeMeshesFromComputeResponse(data: GrasshopperComputeResponse, options?: MeshExtractionOptions): Promise<THREE.Mesh[]>;
+declare function getThreeMeshesFromComputeResponse(data: GrasshopperComputeResponse, options?: MeshExtractionOptions): Promise<THREE.Object3D[]>;
 
 /**
  * Internal-only telemetry threaded from an outer entry point (e.g. the JSON
@@ -186,17 +359,17 @@ interface ParseTelemetry {
     perfStart?: number;
 }
 /**
- * Parses a MeshBatch object and creates Three.js meshes.
+ * 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.
  *
- * @param batch - MeshBatch object
+ * @param batch - DisplayBatch object
  * @param options - Rendering options
  * @returns Promise resolving to array of Three.js mesh objects
  */
-declare function parseMeshBatchObject(batch: MeshBatch, options?: MeshBatchParsingOptions & {
+declare function parseMeshBatchObject(batch: DisplayBatch, options?: MeshBatchParsingOptions & {
     /** Scale factor to apply to meshes (e.g., for unit conversion) */
     scaleFactor?: number;
 }, 
@@ -219,4 +392,17 @@ declare function parseMeshBatchBlob(blob: ArrayBuffer | Uint8Array, options?: Me
     scaleFactor?: number;
 }): Promise<THREE.Mesh[]>;
 
-export { type CameraConfig, type ControlsConfig, type EnvironmentConfig, type EventConfig, type FloorConfig, type LightingConfig, threeMaterials as Materials, MeshBatch, MeshExtractionOptions, type RenderConfig, SCALE_FACTORS, type ThreeInitializerOptions, getThreeMeshesFromComputeResponse, initThree, parseMeshBatchBlob, parseMeshBatchObject, updateScene };
+interface DisplayItemParseOptions {
+    /** rhino3dm instance for decoding curve JSON. Omit to skip curves (points still render). */
+    rhino?: RhinoModule;
+    /** Apply the Rhino Z-up → Three Y-up transform. Defaults to true (matches the mesh path). */
+    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 ControlsConfig, DisplayBatch, DisplayItem, type DisplayItemParseOptions, type EnvironmentConfig, type EventConfig, type FloorConfig, type LightingConfig, threeMaterials as Materials, MeshExtractionOptions, type RenderConfig, SCALE_FACTORS, type ThreeInitializerOptions, getThreeMeshesFromComputeResponse, initThree, parseDisplayItems, parseMeshBatchBlob, parseMeshBatchObject, updateScene };