@selvajs/compute 3.1.0-beta.4 → 3.1.0-beta.6

package/dist/{types-DxPi5SEx.d.cts → types-Dtok-mVq.d.ts}

@@ -1,57 +1,44 @@
-import { C as ComputeConfig, a as RhinoModelUnit } from './types-V7G83j5m.cjs';
+import { C as ComputeConfig, a as RhinoModelUnit } from './types-BGhtYxZ-.js';
 import { RhinoModule } from 'rhino3dm';
 
-/**
- * Grasshopper types
- */
-
-/**
- * Grasshopper-style data tree branch path
- * @example "{0}", "{0;0}", "{0;1;2}"
- */
 type DataTreePath = `{${string}}`;
-/**
- * Represents a data item in a data tree
- */
 interface DataItem {
-    /** The type of the data, inferred from the Grasshopper GOO class */
     type: string;
-    /** The actual returned data as a string that may need to be parsed */
     data: string;
-    /** The grasshopper refrence id of the output */
     id: string;
 }
-/**
- * Grasshopper-style data tree for input defaults
- * @example
- * ```typescript
- * const numericTree: DataTreeDefault<number> = {
- *   "{0}": [1, 2, 3],
- *   "{0;0}": [4, 5],
- *   "{1}": [6]
- * };
- * ```
- */
 type DataTreeDefault<T = any> = {
     [K in DataTreePath]?: T[];
 };
-/**
- * Data structure for InnerTreeData matching Rhino Compute responses
- */
 type InnerTreeData = {
     [path in DataTreePath]: DataItem[];
 };
 /**
- * Tree with parameter metadata (used in compute responses)
+ * Tree with parameter metadata (used in compute requests and responses).
+ *
+ * Field casing varies by server branch: stock mcneel compute (8.x/9.x)
+ * serializes `Resthopper.IO.DataTree` in PascalCase (`ParamName`/`InnerTree`
+ * — the C# class carries no `[JsonProperty]` attributes), while
+ * camelCase-serializing forks return `paramName`/`innerTree` instead. This
+ * client always *sends* PascalCase (see `DataTree.toCompute()` in
+ * `data-tree.ts`), so the PascalCase fields remain the canonical/required
+ * shape; the optional camelCase fields exist so responses from camelCase
+ * forks are representable without casts. Code that must read trees across
+ * both server families should use `readField`/`hasField`
+ * (`@/core/utils/read-field`, case-insensitive) rather than direct property
+ * access — `warnOnEmptyInnerTrees` in `solve.ts` is the reference example.
  */
 interface DataTree {
+    /** PascalCase — stock mcneel servers, and the request shape this client sends. */
     InnerTree: InnerTreeData;
+    /** PascalCase — stock mcneel servers, and the request shape this client sends. */
     ParamName: string;
+    /** camelCase — sent instead of `InnerTree` by camelCase server forks. */
+    innerTree?: InnerTreeData;
+    /** camelCase — sent instead of `ParamName` by camelCase server forks. */
+    paramName?: string;
 }
-/**
- * Output types supported from Grasshopper/Rhino Compute
- */
-type OutputType = 'System.String' | 'System.Double' | 'System.Int32' | 'System.Boolean' | 'Rhino.Geometry.Point3d' | 'Rhino.Geometry.Line' | 'Rhino.Geometry.Circle' | 'Rhino.Geometry.Arc' | 'Rhino.Geometry.NurbsCurve' | 'Rhino.Geometry.Brep' | 'Rhino.Geometry.Mesh' | 'Rhino.Geometry.Vector3d' | 'Rhino.Geometry.Plane' | 'Rhino.Geometry.Box' | string;
+type OutputType = 'System.String' | 'System.Double' | 'System.Int32' | 'System.Boolean' | 'Rhino.Geometry.Point3d' | 'Rhino.Geometry.Line' | 'Rhino.Geometry.Circle' | 'Rhino.Geometry.Arc' | 'Rhino.Geometry.NurbsCurve' | 'Rhino.Geometry.Brep' | 'Rhino.Geometry.Mesh' | 'Rhino.Geometry.Vector3d' | 'Rhino.Geometry.Plane' | 'Rhino.Geometry.Box' | (string & {});
 /**
  * Union type for all possible default value types
  */
@@ -207,11 +194,24 @@ interface GrasshopperRequestSchema extends GrasshopperBaseSchema, GrasshopperDef
 /**
  * Response from Grasshopper compute server
  * Includes all schema fields + computed results
+ *
+ * `pointer` is deliberately excluded (`Omit`): the solve layer (`runSolve` in
+ * `solve.ts`) splits the server's echoed `pointer` off as the solve's
+ * `cacheKey` and strips it from the returned response, so client-returned
+ * responses never carry it.
+ *
+ * The schema-echo fields (`cachesolve`/`modelunits`/`dataversion`) stay
+ * optional as inherited from {@link GrasshopperBaseSchema}: the server echoes
+ * them back when set, but nothing client-side enforces their presence — don't
+ * rely on them without a fallback.
  */
-interface GrasshopperComputeResponse extends GrasshopperBaseSchema, GrasshopperDefinitionSource {
-    /** Whether cache was used (always present in response) */
-    cachesolve: boolean;
-    /** Model units (always present in response) */
+interface GrasshopperComputeResponse extends GrasshopperBaseSchema, Omit<GrasshopperDefinitionSource, 'pointer'> {
+    /**
+     * Model units the definition was solved in. Every conforming server response
+     * carries this (it drives downstream scaling, e.g. the webdisplay parser),
+     * but note it is not validated client-side — a non-conforming server or
+     * hand-built mock may omit it at runtime.
+     */
     modelunits: RhinoModelUnit;
     /**
      * The server echoes the request's full base64 definition back as `algo`, but the client strips
@@ -222,8 +222,6 @@ interface GrasshopperComputeResponse extends GrasshopperBaseSchema, GrasshopperD
     algo?: string | null;
     /** Filename of the definition (always present in response) */
     filename: string | null;
-    /** Data version */
-    dataversion: 7 | 8;
     /** Recursion level used */
     recursionlevel?: number;
     /** Output values organized by parameter */
@@ -332,14 +330,9 @@ interface GrasshopperParsedIO {
 }
 
 /**
- * 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.
+ * Non-mesh display items: curves and points. Ride as JSON inside {@link DisplayBatch} alongside
+ * the binary mesh blob. The union is STRICT and discriminated on `kind`; the parser uses a
+ * `never`-exhaustiveness check, so adding a new kind is a compile error until handled.
  */
 /**
  * Identity + tagging shared by every display thing — meshes (via an adapter over `MeshMetadata`)
@@ -367,7 +360,10 @@ interface DisplayItemBase extends DisplayIdentity {
     /** 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. */
+/**
+ * A world position in Rhino's Z-up frame, in Rhino's `{X,Y,Z}` casing. Used unchanged on parse —
+ * the Three scene IS Rhino's Z-up frame, so no rotation is applied (see `../coordinate-transform.ts`).
+ */
 interface DisplayPosition {
     X: number;
     Y: number;
@@ -390,7 +386,7 @@ interface DisplayCurve extends DisplayItemBase {
 /** 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. */
+    /** World position in Rhino Z-up, used directly — the Three scene shares Rhino's Z-up frame. */
     position: DisplayPosition;
 }
 /**
@@ -421,11 +417,17 @@ interface SerializableMaterial {
  * Metadata for a single mesh within a batch.
  *
  * Offsets and counts are expressed in **vertex-count units** (not float components) and
- * **index-count units**. To address the typed-array storage:
- *   - vertex component offset = `vertexStart * 3`
- *   - vertex component count  = `vertexCount * 3`
- *   - index byte offset       = `indexStart * 4`
- *   - index count             = `indexCount`
+ * **index-count units** — i.e. element offsets into the decoded typed arrays, which is how
+ * consumers address them (`indices.subarray(indexStart, indexStart + indexCount)`). To address
+ * the typed-array storage:
+ *   - vertex component offset  = `vertexStart * 3`
+ *   - vertex component count   = `vertexCount * 3`
+ *   - index element offset     = `indexStart`
+ *   - index count              = `indexCount`
+ *
+ * If you need *byte* offsets, multiply by the element size, which depends on the blob's flags:
+ * indices are 2 bytes each for `FLAG_UINT16_INDICES` (wire v2+) blobs and 4 bytes for uint32
+ * blobs; vertex components are 2 bytes (int16 quantized) or 4 bytes (`FLAG_FLOAT32`).
  */
 interface MeshMetadata {
     name: string;
@@ -468,11 +470,8 @@ interface MaterialGroup {
  * later labels/icons) also travel — those ride as JSON alongside the mesh blob, not inside it.
  */
 interface DisplayBatch {
-    /** Array of unique materials */
     materials: SerializableMaterial[];
-    /** Groups of meshes organized by material */
     groups: MaterialGroup[];
-    /** Base64-encoded binary blob (SLVA wire format). */
     compressedData: string;
     /** InstanceGuid of the WebDisplay GH component that produced this batch.
      *  Combined with MeshMetadata.originalIndex to backtrack any mesh to its GH source. */
@@ -490,20 +489,17 @@ interface DisplayBatch {
  * This alias keeps existing imports compiling; remove it once consumers migrate.
  */
 type MeshBatch = DisplayBatch;
-/**
- * Options for parsing mesh batch data.
- */
 interface MeshBatchParsingOptions {
-    /** Merge meshes with same material into single geometry (better performance). Defaults to true. */
+    /** Merge meshes with same material into single geometry. Defaults to true. */
     mergeByMaterial?: boolean;
-    /** Apply coordinate system transformations (Rhino Z-up to Three.js Y-up). Defaults to true. */
+    /** Apply coordinate system transformations. Defaults to true. */
     applyTransforms?: boolean;
-    /** Enable performance monitoring in console. Defaults to false. */
+    /** Enable performance monitoring. Defaults to false. */
     debug?: boolean;
     /**
-     * Appearance dials applied to every material built from this batch. These drive how "rendered"
+     * Appearance dials applied to every material built from this batch. These drive how "studio"
      * vs "matte technical" the meshes look; they are set once at parse time (materials are rebuilt
-     * per solve). Runtime restyling of an already-built scene lives in the viewer's `setRenderStyle`.
+     * per solve). Runtime restyling of an already-built scene lives in the viewer's `setLook`.
      */
     material?: MaterialAppearanceOptions;
 }

package/dist/visualization-36IV2CVU.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunk727SRM4Ecjs = require('./chunk-727SRM4E.cjs');require('./chunk-CUQQ3ZBV.cjs');exports.BINARY_MESH_MAGIC = _chunk727SRM4Ecjs.w; exports.BINARY_MESH_VERSION = _chunk727SRM4Ecjs.y; exports.COMPRESSED_MESH_MAGIC = _chunk727SRM4Ecjs.x; exports.EDGE_USERDATA_KIND = _chunk727SRM4Ecjs.i; exports.FLAG_DELTA_ENCODED = _chunk727SRM4Ecjs.C; exports.FLAG_FLOAT32 = _chunk727SRM4Ecjs.A; exports.FLAG_HAS_UVS = _chunk727SRM4Ecjs.D; exports.FLAG_HAS_VERTEX_COLORS = _chunk727SRM4Ecjs.E; exports.FLAG_UINT16_INDICES = _chunk727SRM4Ecjs.B; exports.MIN_SUPPORTED_VERSION = _chunk727SRM4Ecjs.z; exports.Materials = _chunk727SRM4Ecjs.a; exports.SCALE_FACTORS = _chunk727SRM4Ecjs.L; exports.TEXTURE_CACHE_MAX_ENTRIES = _chunk727SRM4Ecjs.q; exports.UV_FORMAT_FLOAT32 = _chunk727SRM4Ecjs.G; exports.UV_FORMAT_UINT16 = _chunk727SRM4Ecjs.F; exports.addEdges = _chunk727SRM4Ecjs.j; exports.applyOffset = _chunk727SRM4Ecjs.d; exports.clearTextureCache = _chunk727SRM4Ecjs.s; exports.computeCombinedBoundingBox = _chunk727SRM4Ecjs.e; exports.createCameraController = _chunk727SRM4Ecjs.f; exports.createGrid = _chunk727SRM4Ecjs.g; exports.createLabelLayer = _chunk727SRM4Ecjs.n; exports.createMeasureTool = _chunk727SRM4Ecjs.p; exports.createRenderPipeline = _chunk727SRM4Ecjs.m; exports.createViewGizmo = _chunk727SRM4Ecjs.h; exports.getThreeMeshesFromComputeResponse = _chunk727SRM4Ecjs.M; exports.initThree = _chunk727SRM4Ecjs.u; exports.isEdgeOverlay = _chunk727SRM4Ecjs.k; exports.materialAppearanceForLook = _chunk727SRM4Ecjs.t; exports.parseBinaryMeshBatch = _chunk727SRM4Ecjs.H; exports.parseColor = _chunk727SRM4Ecjs.c; exports.parseDisplayItems = _chunk727SRM4Ecjs.v; exports.parseMeshBatch = _chunk727SRM4Ecjs.I; exports.parseMeshBatchBlob = _chunk727SRM4Ecjs.K; exports.parseMeshBatchObject = _chunk727SRM4Ecjs.J; exports.removeEdges = _chunk727SRM4Ecjs.l; exports.setTextureAnisotropy = _chunk727SRM4Ecjs.r; exports.snapToVertex = _chunk727SRM4Ecjs.o; exports.updateScene = _chunk727SRM4Ecjs.b;
+//# sourceMappingURL=visualization-36IV2CVU.cjs.map

package/dist/visualization-36IV2CVU.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/selva-compute/selva-compute/dist/visualization-36IV2CVU.cjs"],"names":[],"mappings":"AAAA,iIAA6S,gCAA6B,62DAAg4B","file":"/home/runner/work/selva-compute/selva-compute/dist/visualization-36IV2CVU.cjs"}

package/dist/visualization-QCI36RHC.js

@@ -0,0 +1,2 @@
+import{A as I,B as L,C as R,D as S,E as D,F as B,G,H as P,I as u,J as F,K as b,L as N,M as V,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 C,o as x,p as d,q as h,r as E,s as M,t as _,u as c,v as A,w as g,x as O,y as T,z as j}from"./chunk-CWODTGNH.js";import"./chunk-WPB2LKCD.js";export{g as BINARY_MESH_MAGIC,T as BINARY_MESH_VERSION,O as COMPRESSED_MESH_MAGIC,n as EDGE_USERDATA_KIND,R as FLAG_DELTA_ENCODED,I as FLAG_FLOAT32,S as FLAG_HAS_UVS,D as FLAG_HAS_VERTEX_COLORS,L as FLAG_UINT16_INDICES,j as MIN_SUPPORTED_VERSION,e as Materials,N as SCALE_FACTORS,h as TEXTURE_CACHE_MAX_ENTRIES,G as UV_FORMAT_FLOAT32,B as UV_FORMAT_UINT16,m as addEdges,t as applyOffset,M as clearTextureCache,a as computeCombinedBoundingBox,s as createCameraController,p as createGrid,C as createLabelLayer,d as createMeasureTool,y as createRenderPipeline,i as createViewGizmo,V as getThreeMeshesFromComputeResponse,c as initThree,l as isEdgeOverlay,_ as materialAppearanceForLook,P as parseBinaryMeshBatch,o as parseColor,A as parseDisplayItems,u as parseMeshBatch,b as parseMeshBatchBlob,F as parseMeshBatchObject,f as removeEdges,E as setTextureAnisotropy,x as snapToVertex,r as updateScene};
+//# sourceMappingURL=visualization-QCI36RHC.js.map

package/dist/visualization.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunk4JNRO7TXcjs = require('./chunk-4JNRO7TX.cjs');require('./chunk-D7A3YIYD.cjs');exports.EDGE_USERDATA_KIND = _chunk4JNRO7TXcjs.h; exports.Materials = _chunk4JNRO7TXcjs.t; exports.SCALE_FACTORS = _chunk4JNRO7TXcjs.F; exports.addEdges = _chunk4JNRO7TXcjs.i; exports.applyOffset = _chunk4JNRO7TXcjs.c; exports.computeCombinedBoundingBox = _chunk4JNRO7TXcjs.d; exports.createCameraController = _chunk4JNRO7TXcjs.e; exports.createGrid = _chunk4JNRO7TXcjs.f; exports.createLabelLayer = _chunk4JNRO7TXcjs.m; exports.createMeasureTool = _chunk4JNRO7TXcjs.o; exports.createRenderPipeline = _chunk4JNRO7TXcjs.l; exports.createViewGizmo = _chunk4JNRO7TXcjs.g; exports.getThreeMeshesFromComputeResponse = _chunk4JNRO7TXcjs.G; exports.initThree = _chunk4JNRO7TXcjs.s; exports.isEdgeOverlay = _chunk4JNRO7TXcjs.j; exports.parseColor = _chunk4JNRO7TXcjs.b; exports.parseDisplayItems = _chunk4JNRO7TXcjs.u; exports.parseMeshBatchBlob = _chunk4JNRO7TXcjs.E; exports.parseMeshBatchObject = _chunk4JNRO7TXcjs.D; exports.removeEdges = _chunk4JNRO7TXcjs.k; exports.snapToVertex = _chunk4JNRO7TXcjs.n; exports.updateScene = _chunk4JNRO7TXcjs.a;
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunk727SRM4Ecjs = require('./chunk-727SRM4E.cjs');require('./chunk-CUQQ3ZBV.cjs');exports.EDGE_USERDATA_KIND = _chunk727SRM4Ecjs.i; exports.Materials = _chunk727SRM4Ecjs.a; exports.SCALE_FACTORS = _chunk727SRM4Ecjs.L; exports.addEdges = _chunk727SRM4Ecjs.j; exports.applyOffset = _chunk727SRM4Ecjs.d; exports.computeCombinedBoundingBox = _chunk727SRM4Ecjs.e; exports.createCameraController = _chunk727SRM4Ecjs.f; exports.createGrid = _chunk727SRM4Ecjs.g; exports.createLabelLayer = _chunk727SRM4Ecjs.n; exports.createMeasureTool = _chunk727SRM4Ecjs.p; exports.createRenderPipeline = _chunk727SRM4Ecjs.m; exports.createViewGizmo = _chunk727SRM4Ecjs.h; exports.getThreeMeshesFromComputeResponse = _chunk727SRM4Ecjs.M; exports.initThree = _chunk727SRM4Ecjs.u; exports.isEdgeOverlay = _chunk727SRM4Ecjs.k; exports.parseColor = _chunk727SRM4Ecjs.c; exports.parseDisplayItems = _chunk727SRM4Ecjs.v; exports.parseMeshBatchBlob = _chunk727SRM4Ecjs.K; exports.parseMeshBatchObject = _chunk727SRM4Ecjs.J; exports.removeEdges = _chunk727SRM4Ecjs.l; exports.snapToVertex = _chunk727SRM4Ecjs.o; exports.updateScene = _chunk727SRM4Ecjs.b;
 //# sourceMappingURL=visualization.cjs.map

package/dist/visualization.d.cts

@@ -1,11 +1,11 @@
 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-DxPi5SEx.cjs';
-export { q as DisplayCurve, r as DisplayIdentity, s as DisplayItemBase, t as DisplayPoint, u as DisplayPosition, v as MeshBatch } from './types-DxPi5SEx.cjs';
+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 { CSS2DObject } from 'three/addons/renderers/CSS2DRenderer.js';
 import { LineSegments2 } from 'three/addons/lines/LineSegments2.js';
 import { RhinoModule } from 'rhino3dm';
-import './types-V7G83j5m.cjs';
+import './types-BGhtYxZ-.cjs';
 
 type CameraConfig = {
     position?: THREE.Vector3;
@@ -21,6 +21,20 @@ type LightingConfig = {
     ambientLightColor?: THREE.Color;
     ambientLightIntensity?: number;
     sunlightColor?: THREE.Color | number;
+    /**
+     * Add a hemisphere fill light (sky color from above, ground color from below). Unlike the flat
+     * ambient, this gives soft *direction-aware* fill, so downward- and side-facing surfaces never
+     * collapse to black when the HDR's lower hemisphere is dark. The single biggest lever for keeping
+     * results well-lit regardless of which HDR is loaded. Default false (opt-in) — enabling it shifts
+     * the look. See {@link LightingConfig.hemisphereIntensity}.
+     */
+    enableHemisphereLight?: boolean;
+    /** Hemisphere fill sky color (lights upward-facing surfaces). Default white. */
+    hemisphereSkyColor?: THREE.Color | number;
+    /** Hemisphere fill ground color (lights downward-facing surfaces). Default a mid grey. */
+    hemisphereGroundColor?: THREE.Color | number;
+    /** Hemisphere fill strength. Default 0.6. Only applies when {@link LightingConfig.enableHemisphereLight}. */
+    hemisphereIntensity?: number;
 };
 type EnvironmentConfig = {
     hdrPath?: string;
@@ -28,6 +42,13 @@ type EnvironmentConfig = {
     enableEnvironmentLighting?: boolean;
     sceneUp?: THREE.Vector3;
     showEnvironment?: boolean;
+    /**
+     * Uniform multiplier on the HDR's image-based lighting contribution (`scene.environmentIntensity`).
+     * Normalizes brightness across HDRs of differing exposure — raise it to lift a dim HDR, lower it to
+     * tame a blown-out one — so the scene doesn't render dim-or-blown purely because of the HDR chosen.
+     * Default 1 (three.js default, unchanged look).
+     */
+    environmentIntensity?: number;
 };
 type FloorConfig = {
     enabled?: boolean;
@@ -52,17 +73,29 @@ type RenderConfig = {
     ambientOcclusion?: boolean;
     /** AO strength 0–1 when {@link RenderConfig.ambientOcclusion} is on. Default 1. */
     aoIntensity?: number;
+    /**
+     * Device-pixel-ratio cap for the ambient-occlusion postprocessing buffers. AO is low-frequency, so
+     * rendering its buffers below the display DPR is nearly invisible but hugely cheaper — on a Retina
+     * display (DPR 2) full-resolution AO means 4× the pixels through GTAO's per-pixel sample loops,
+     * which can dominate frame time. Default 1 (AO buffers at 1× regardless of display DPR). Raise
+     * toward the display DPR for sharper AO at higher cost; only relevant when AO is enabled.
+     */
+    aoPixelRatio?: number;
 };
 /**
- * A coherent visual look. Seeds the initial render defaults (tone mapping, AO, edges, grid, IBL
- * strength) at construction and can be re-applied live via `setRenderStyle`.
+ * A ready-to-go visual look. A `look` is a named bundle of LIGHTING/MATERIAL defaults only — it is
+ * deliberately decoupled from the CAD overlays (edges, grid), which are driven independently by
+ * {@link EdgesConfig}/{@link GridConfig}. Pick one and the viewer looks professional with zero other
+ * config; every individual `lighting`/`environment`/`render` option still overrides the preset. Seeds
+ * construction defaults and can be re-applied live via `setLook`.
  *
- * - 'technical': matte, drawing-like — neutral tone mapping, low IBL, edges + grid on, AO on.
- *   Reads like a CAD shaded view (Rhino/Onshape).
- * - 'rendered':  presentation — ACES-filmic tone mapping, stronger IBL, edges off, AO on. Reads
- *   like a Keyshot/Fusion render.
+ * - 'technical' (default): matte, drawing-like — neutral tone mapping, low IBL, no fill. Reads like a
+ *   CAD shaded view (Rhino/Onshape).
+ * - 'studio': balanced presentation — ACES tone mapping, hemisphere fill + lifted HDR so results are
+ *   well-lit regardless of the HDR, without washing colour out. The polished "product shot" look.
+ * - 'showcase': punchier presentation — ACES, stronger IBL/fill and a touch more exposure.
  */
-type RenderStyle = 'technical' | 'rendered';
+type Look = 'studio' | 'technical' | 'showcase';
 /** Crisp boundary/crease edge overlays on meshes. See `addEdges`. */
 type EdgesConfig = {
     /** Auto-attach edge overlays to meshes as they load. Default false (opt-in). */
@@ -133,12 +166,13 @@ type MeasureConfig = {
 type ThreeInitializerOptions = {
     sceneScale?: 'mm' | 'cm' | 'm' | 'inches' | 'feet';
     /**
-     * Pick a coherent look up front — seeds sensible defaults for tone mapping, AO, edges, grid, and
-     * IBL strength (see {@link RenderStyle}). Individual `render`/`edges`/`grid` options still win
-     * when set explicitly, so this only fills in what you leave unspecified. Omit for the plain
-     * per-field defaults (no style applied). Re-apply later via the init result's `setRenderStyle`.
+     * Pick a ready-to-go visual look up front — seeds professional lighting/material defaults (tone
+     * mapping, AO, IBL strength, hemisphere fill; see {@link Look}). Individual `lighting`/
+     * `environment`/`render` options still win when set explicitly, so this only fills in what you
+     * leave unspecified. A look does NOT touch edges/grid (those are independent overlays). Defaults
+     * to 'technical'. Re-apply later via the init result's `setLook`.
      */
-    renderStyle?: RenderStyle;
+    look?: Look;
     camera?: CameraConfig;
     lighting?: LightingConfig;
     environment?: EnvironmentConfig;
@@ -210,12 +244,20 @@ interface CameraController {
      * singularity.
      */
     setViewDirection(direction: THREE.Vector3, animate?: boolean): void;
+    /**
+     * Frame an arbitrary world-space box (e.g. a double-clicked object) from the current view
+     * direction, moving the *active* camera — in 2D mode that means resizing the ortho frustum, not
+     * just translating. No-op on an empty box.
+     */
+    frameBounds(box: THREE.Box3, animate?: boolean): void;
     /** Enable/disable orbit rotation at runtime (pan/zoom unaffected). */
     setRotateEnabled(enabled: boolean): void;
     /** Whether rotation is currently enabled. */
     isRotateEnabled(): boolean;
     /** Keep the orthographic frustum aspect in sync on canvas resize. Called by the resize loop. */
     updateAspect(width: number, height: number): void;
+    /** Cancel any in-flight camera tween. Call on viewer teardown so ticks can't touch disposed controls. */
+    dispose(): void;
 }
 interface CameraControllerDeps {
     scene: THREE.Scene;
@@ -282,14 +324,24 @@ declare function createGrid(options?: GridOptions): Grid;
  *
  * 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 (no-op now; kept for API symmetry),
  *  - forward pointer clicks to {@link ViewGizmo.handleClick}.
  */
 interface ViewGizmo {
     render(renderer: THREE.WebGLRenderer): void;
+    /**
+     * @deprecated No-op, kept only for API stability. This wrapper never uses ViewHelper's
+     * click→animate path (see module comment) — view changes snap instantly through the camera
+     * controller — so there is never a gizmo animation to advance. Safe to stop calling.
+     */
     update(delta: number): void;
     /** Hit-test a click. Returns true if it hit the gizmo (and a view change started). */
     handleClick(event: MouseEvent): boolean;
+    /**
+     * @deprecated Always `false`, kept only for API stability. Gizmo clicks snap the view
+     * instantly rather than animating (deliberately — ViewHelper's built-in animation assumes a
+     * Y-up world and rolls the view in this Z-up scene), so there is no animation window to gate
+     * input on.
+     */
     readonly isAnimating: boolean;
     /** Show/hide the gizmo at runtime. Hidden = not rendered and not click-hittable. */
     setVisible(visible: boolean): void;
@@ -392,6 +444,14 @@ interface MeasureDeps {
     canvas: HTMLCanvasElement;
     scene: THREE.Scene;
     getActiveCamera: () => THREE.Camera;
+    /**
+     * The current orbit target (e.g. `controls.target`). Used to scale the line/point pick
+     * threshold with the view: the tolerance is a fraction of the camera→target distance, so it
+     * stays roughly constant on screen wherever the user has framed the model. Optional for
+     * backward compatibility — without it the perspective fallback is the camera's distance to the
+     * world origin, which misjudges the threshold for off-origin content. Thread it in when you can.
+     */
+    getViewTarget?: () => THREE.Vector3;
     labelLayer: LabelLayer;
     options?: MeasureOptions;
 }
@@ -435,13 +495,40 @@ declare const initThree: (canvas: HTMLCanvasElement, options?: ThreeInitializerO
      * edges). Retunes viewer-owned dials only; per-material parse choices are set via the batch
      * parser's `material` option. Handy for comparing the two looks in a live viewer.
      */
-    setRenderStyle: (style: "technical" | "rendered") => void;
     /**
-     * The parse-time material options (backface culling, IBL strength) matching the active render
-     * style — feed into the batch parser's `material` option so freshly-loaded meshes are built to
-     * match the look. Returns undefined when no style is active. See `setRenderStyle`.
+     * Switch the viewer to a ready-to-go look at runtime ('studio' | 'technical' | 'showcase'). Retunes
+     * lighting/material only (tone mapping, fill, IBL, AO) — never edges/grid. A straight preset apply:
+     * overwrites any granular lighting dials you set earlier.
+     */
+    setLook: (look: "studio" | "technical" | "showcase") => void;
+    /**
+     * Retune the fill lights at runtime: the direction-aware hemisphere fill (sky/ground) and the flat
+     * ambient. Raising `hemisphereIntensity` is the most effective way to lift shadowed / under-facing
+     * surfaces a dark HDR leaves black. A positive `hemisphereIntensity` lazily creates the hemisphere
+     * light if the viewer was built without one; `0` switches it off.
      */
-    getMaterialAppearance: () => MaterialAppearanceOptions | undefined;
+    setFillLights: (opts: {
+        hemisphereIntensity?: number;
+        hemisphereSkyColor?: THREE.Color | number;
+        hemisphereGroundColor?: THREE.Color | number;
+        ambientIntensity?: number;
+    }) => void;
+    /**
+     * Set the uniform multiplier on the HDR's image-based lighting (`scene.environmentIntensity`) at
+     * runtime — normalizes brightness across HDRs of differing exposure so the scene isn't at the
+     * mercy of whichever HDR is loaded. Applies immediately, even before the HDR finishes decoding.
+     */
+    setEnvironmentIntensity: (intensity: number) => void;
+    /** Set renderer tone-mapping exposure at runtime. Higher lifts shadows and overall brightness. */
+    setToneMappingExposure: (exposure: number) => void;
+    /** Set GTAO strength at runtime (0–1). No-op when ambient occlusion isn't active. */
+    setAoIntensity: (intensity: number) => void;
+    /**
+     * The parse-time material options (backface culling, IBL strength) matching the active look — feed
+     * into the batch parser's `material` option so freshly-loaded meshes are built to match it. See
+     * `setLook`.
+     */
+    getMaterialAppearance: () => MaterialAppearanceOptions;
     /**
      * Refit the sun's shadow frustum to the current scene content for crisp shadows. Call after
      * loading or replacing geometry (e.g. after `updateScene`). No-op when sunlight/shadows are off.
@@ -462,25 +549,9 @@ declare const initThree: (canvas: HTMLCanvasElement, options?: ThreeInitializerO
     clearUserGeometry: () => void;
 };
 
-/**
- * Updates the scene with the given meshes and camera settings.
- * If initialPositionSet is false, it positions the camera and sets the controls target based on the bounding boxes of the meshes.
- * @param scene - The THREE.Scene object to update.
- * @param meshes - An array of THREE.Mesh objects to add to the scene.
- * @param camera - The THREE.PerspectiveCamera object to position.
- * @param controls - The OrbitControls object to update.
- * @param initialPositionSet - A boolean indicating whether the initial position of the camera and controls have been set.
- */
+/** Updates scene with meshes and positions camera on first call. */
 declare function updateScene(scene: THREE.Scene, meshes: THREE.Object3D[], camera: THREE.PerspectiveCamera, controls: OrbitControls, initialPositionSet: boolean): void;
-/**
- * Parses a color string in multiple formats to a THREE.Color object.
- * Supported formats:
- * - Hex: "#C7A5A5", "C7A5A5"
- * - RGB: "199, 165, 165"
- * - CSS named colors: "red", "blue", etc.
- * @param colorString - The color string to parse.
- * @returns A THREE.Color object.
- */
+/** Parses color strings (hex, RGB, CSS names). */
 declare function parseColor(colorString: string): THREE.Color;
 /**
  * Shift objects along one world axis. Defaults to `z` — the up axis of the unified Z-up scene
@@ -500,6 +571,8 @@ declare const PLASTIC_MATERIAL: THREE.MeshPhysicalMaterial;
 declare const GLASS_MATERIAL: THREE.MeshPhysicalMaterial;
 declare const RUBBER_MATERIAL: THREE.MeshPhysicalMaterial;
 declare const WOOD_MATERIAL: THREE.MeshPhysicalMaterial;
+/** Shared singleton materials; must not be disposed (rebuilds shaders, frees textures). */
+declare const SHARED_MATERIALS: ReadonlySet<THREE.Material>;
 
 declare const threeMaterials_CONCRETE_MATERIAL: typeof CONCRETE_MATERIAL;
 declare const threeMaterials_EMISSIVE_MATERIAL: typeof EMISSIVE_MATERIAL;
@@ -507,9 +580,10 @@ declare const threeMaterials_GLASS_MATERIAL: typeof GLASS_MATERIAL;
 declare const threeMaterials_METAL_MATERIAL: typeof METAL_MATERIAL;
 declare const threeMaterials_PLASTIC_MATERIAL: typeof PLASTIC_MATERIAL;
 declare const threeMaterials_RUBBER_MATERIAL: typeof RUBBER_MATERIAL;
+declare const threeMaterials_SHARED_MATERIALS: typeof SHARED_MATERIALS;
 declare const threeMaterials_WOOD_MATERIAL: typeof WOOD_MATERIAL;
 declare namespace threeMaterials {
-  export { threeMaterials_CONCRETE_MATERIAL as CONCRETE_MATERIAL, threeMaterials_EMISSIVE_MATERIAL as EMISSIVE_MATERIAL, threeMaterials_GLASS_MATERIAL as GLASS_MATERIAL, threeMaterials_METAL_MATERIAL as METAL_MATERIAL, threeMaterials_PLASTIC_MATERIAL as PLASTIC_MATERIAL, threeMaterials_RUBBER_MATERIAL as RUBBER_MATERIAL, threeMaterials_WOOD_MATERIAL as WOOD_MATERIAL };
+  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 };
 }
 
 /**
@@ -585,9 +659,21 @@ interface RenderPipelineOptions {
     toneMappingExposure: number;
     /** AO strength 0–1. Default 1. */
     aoIntensity?: number;
+    /**
+     * Cap on the device-pixel-ratio used for the composer's (AO) buffers. AO is low-frequency, so
+     * rendering below the display DPR is nearly invisible but far cheaper. `setSize`'s incoming
+     * pixelRatio is clamped to this. Default 1.
+     */
+    aoPixelRatio?: number;
 }
 declare function createRenderPipeline(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera, width: number, height: number, options: RenderPipelineOptions): RenderPipeline;
 
+/**
+ * Metres per model unit, keyed by Rhino `UnitSystem` name (the `modelunits` string on the compute
+ * response). Imperial factors are the exact international definitions (1 in = 0.0254 m,
+ * 1 ft = 0.3048 m, 1 mi = 1609.344 m). Units not in this table scale 1 and log a one-time warning
+ * — see {@link getScaleFactor}.
+ */
 declare const SCALE_FACTORS: Record<string, number>;
 /**
  * Extracts and processes display meshes from a ComputePointerResponse using the Grasshopper WebDisplay component.
@@ -595,7 +681,9 @@ declare const SCALE_FACTORS: Record<string, number>;
  * This is the primary entry point for extracting mesh geometry from Grasshopper compute responses.
  * It handles all aspects of mesh processing: decompression, coordinate transformation, scaling, and positioning.
  *
- * **Note:** Mesh decompression happens asynchronously in a Web Worker to prevent UI blocking.
+ * **Note:** The entire pipeline (base64 decode, inflate, dequantization, mesh construction) runs
+ * synchronously on the calling thread — large batches will block the UI for their duration. The
+ * function is `async` only so its shape can stay stable if parsing moves off-thread later.
  *
  * @param data - The ComputePointerResponse containing Grasshopper output trees.
  * @param options - Configuration for mesh extraction and parsing behavior. All options are optional with sensible defaults.
@@ -606,7 +694,7 @@ declare const SCALE_FACTORS: Record<string, number>;
  * - Only works with the WebDisplay component of GHHeadless.
  * - Requires changes to Rhino.Compute (see https://github.com/TheVessen/compute.rhino3d).
  * - Provides a performant way to display mesh data in Three.js.
- * - Decompression is performed in a Web Worker for non-blocking UI updates.
+ * - All decoding is synchronous on the main thread; there is no Web Worker offload today.
  * - Supports mesh metadata (names, user data) if provided in the compute response.
  *
  * @internal Internal helper: high-level extraction remains public via visualization module, but this
@@ -635,11 +723,7 @@ declare const SCALE_FACTORS: Record<string, number>;
  */
 declare function getThreeMeshesFromComputeResponse(data: GrasshopperComputeResponse, options?: MeshExtractionOptions): Promise<THREE.Object3D[]>;
 
-/**
- * Internal-only telemetry threaded from an outer entry point (e.g. the JSON
- * `parseMeshBatch` measuring its own `JSON.parse` cost) into the shared build
- * step. Never part of any public options surface — callers don't supply timings.
- */
+/** Internal telemetry only (not exposed in public options). */
 interface ParseTelemetry {
     parseTime?: number;
     perfStart?: number;
@@ -651,9 +735,14 @@ interface ParseTelemetry {
  * over the blob. The function stays `async` so callers don't have to change shape if we move
  * parsing into a worker later.
  *
+ * A batch with no `compressedData` (genuinely empty/absent geometry) resolves to `[]`. A corrupt,
+ * truncated, or unsupported blob throws so callers get a signal instead of a silent empty scene —
+ * `getThreeMeshesFromComputeResponse` documents (and now delivers) exactly that rethrow.
+ *
  * @param batch - DisplayBatch object
  * @param options - Rendering options
  * @returns Promise resolving to array of Three.js mesh objects
+ * @throws {RhinoComputeError} On a corrupt/truncated/unsupported mesh blob or malformed group metadata.
  */
 declare function parseMeshBatchObject(batch: DisplayBatch, options?: MeshBatchParsingOptions, 
 /** @internal Timings threaded from an outer entry point; not a caller option. */
@@ -669,13 +758,20 @@ telemetry?: ParseTelemetry): Promise<THREE.Mesh[]>;
  * @param blob - Raw blob bytes from a binary WebSocket frame.
  * @param options - Rendering options.
  * @returns Promise resolving to array of Three.js mesh objects.
+ * @throws {RhinoComputeError} On a corrupt/truncated/unsupported mesh blob or malformed group metadata.
  */
 declare function parseMeshBatchBlob(blob: ArrayBuffer | Uint8Array, options?: MeshBatchParsingOptions): Promise<THREE.Mesh[]>;
 
 interface DisplayItemParseOptions {
     /** rhino3dm instance for decoding curve JSON. Omit to skip curves (points still render). */
     rhino?: RhinoModule;
-    /** Apply the Rhino Z-up → Three Y-up transform. Defaults to true (matches the mesh path). */
+    /**
+     * No-op. Historically toggled the Rhino Z-up → Three Y-up rotation, but the pipeline now keeps
+     * one coordinate frame end to end ({@link rhinoToThree} is the identity), so this flag no longer
+     * changes the result. Do NOT pre-rotate your own geometry to compensate — none is applied.
+     *
+     * @deprecated Retained only so existing call sites compile unchanged; has no effect.
+     */
     applyTransforms?: boolean;
 }
 /**