@selvajs/compute 3.1.0-beta.1 → 3.1.0-beta.11

package/dist/{handle-files-9pkEgDIp.d.cts → handle-files-BISo_wob.d.ts}

@@ -25,14 +25,16 @@ declare class ComputeServerStats {
     private disposed;
     private activeMonitors;
     private activeTimeouts;
-    /**
-     * @param serverUrl - Base URL of the Rhino Compute server with http:// or https:// scheme (e.g., 'http://localhost:6500')
-     * @param apiKey - Optional API key for authentication
-     */
     /** Timeout (ms) for the fast read/monitoring endpoints. */
     private static readonly DEFAULT_TIMEOUT_MS;
     /** Timeout (ms) for child-lifecycle POSTs — a cold Windows child can take ~30s to spawn. */
     private static readonly LIFECYCLE_TIMEOUT_MS;
+    /** Floor for `monitor()`'s `intervalMs` — anything lower hot-loops the server. */
+    private static readonly MIN_MONITOR_INTERVAL_MS;
+    /**
+     * @param serverUrl - Base URL of the Rhino Compute server with http:// or https:// scheme (e.g., 'http://localhost:6500')
+     * @param apiKey - Optional API key for authentication
+     */
     constructor(serverUrl: string, apiKey?: string);
     /**
      * Build request headers with optional API key.
@@ -273,8 +275,10 @@ declare class ComputeServerStats {
      * Continuously monitor server stats at specified interval.
      *
      * @param callback - Function called with stats on each interval
-     * @param intervalMs - Milliseconds between checks (default: 5000)
+     * @param intervalMs - Milliseconds between checks (default: 5000). Must be a
+     *   finite number of at least 100 ms — lower values would hot-loop the server.
      * @returns Function to stop monitoring
+     * @throws {RangeError} If `intervalMs` is not a finite number >= 100.
      *
      * @example
      * ```typescript
@@ -298,9 +302,6 @@ declare class ComputeServerStats {
     private ensureNotDisposed;
 }
 
-/**
- * Error types and codes for `@selvajs/compute`.
- */
 declare const ErrorCodes: {
     readonly NETWORK_ERROR: "NETWORK_ERROR";
     readonly AUTH_ERROR: "AUTH_ERROR";
@@ -308,6 +309,17 @@ declare const ErrorCodes: {
     readonly COMPUTATION_ERROR: "COMPUTATION_ERROR";
     readonly TIMEOUT_ERROR: "TIMEOUT_ERROR";
     readonly CORS_ERROR: "CORS_ERROR";
+    /** HTTP 404 — the endpoint path does not exist on the server (usually a typo'd route or wrong server). Never retried. */
+    readonly NOT_FOUND: "NOT_FOUND";
+    /** HTTP 429 — the server is rate-limiting requests. Retried by default (honors `Retry-After`); see `RetryPolicy.retryOn429`. */
+    readonly RATE_LIMIT: "RATE_LIMIT";
+    /**
+     * The server answered 2xx but the body is deterministically not JSON (the
+     * response declared a non-JSON `Content-Type`, e.g. an HTML captive-portal or
+     * proxy login page, or a misconfigured endpoint). Never retried — refetching
+     * returns the same page.
+     */
+    readonly INVALID_RESPONSE: "INVALID_RESPONSE";
     readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
     readonly INVALID_STATE: "INVALID_STATE";
     readonly INVALID_INPUT: "INVALID_INPUT";
@@ -321,6 +333,19 @@ declare const ErrorCodes: {
     readonly SUPERSEDED: "SUPERSEDED";
     /** Scheduler / caller-supplied AbortSignal: this call was aborted. */
     readonly ABORTED: "ABORTED";
+    /**
+     * Scheduler backpressure: the queue was already at `maxQueueDepth` when this
+     * call arrived, so it was shed immediately rather than queued. Retryable — the
+     * caller (or an HTTP layer, as 503 + Retry-After) should back off and retry.
+     * The error `context` carries `{ queueDepth, maxQueueDepth }`.
+     */
+    readonly QUEUE_FULL: "QUEUE_FULL";
+    /**
+     * Scheduler backpressure: this call sat queued longer than `queueWaitMs`
+     * without starting, so it was shed before wasting compute on a stale request.
+     * Retryable. The error `context` carries `{ waitedMs, queueWaitMs }`.
+     */
+    readonly QUEUE_TIMEOUT: "QUEUE_TIMEOUT";
     /**
      * A solve referenced a definition by `pointer` (server-side cache key), but the
      * server no longer holds that definition (evicted / GC'd / a different child in
@@ -357,94 +382,53 @@ declare class RhinoComputeError extends Error {
 }
 
 /**
- * Represents raw file data from Grasshopper/Rhino Compute response.
- *
- * This type encapsulates file output from compute operations, with metadata
- * for processing (decoding, naming, organization). Files are typically combined
- * with additional files and packaged into a ZIP archive for download.
- *
- * @see {@link ProcessedFile} for the normalized format after processing
+ * Raw file data from Grasshopper/Rhino Compute response, with metadata for processing.
+ * Files are typically combined with additional files and packaged into a ZIP archive.
  * @see {@link extractFilesFromComputeResponse} for extraction from compute responses
  */
 type FileData = {
     /** Base filename without extension (e.g., "model") */
     fileName: string;
-    /** File content as a base64-encoded or plain string, depending on {@link IsBase64Encoded} */
+    /** File content, base64-encoded or plain string depending on isBase64Encoded flag */
     data: string;
-    /** File extension including the dot (e.g., ".3dm", ".json"). Appended to {@link FileName} to create the full filename */
+    /** File extension including the dot (e.g., ".3dm", ".json"). Appended to fileName to create the full filename */
     fileType: string;
-    /** Whether {@link Data} is base64-encoded. If true, must be decoded to binary before use. If false, can be used as a plain text string */
+    /** Whether data is base64-encoded. If true, must be decoded to binary before use */
     isBase64Encoded: boolean;
-    /** Directory path for organizing the file in archive structures (e.g., ZIP). Typically empty string for root-level files, or a path like "subfolder/nested" */
+    /** Directory path for archive organization (e.g., "subfolder/nested"). Empty string for root-level files */
     subFolder: string;
-    /** Arbitrary user-supplied metadata (e.g. tags, indexing keys) attached in Grasshopper. Not interpreted by compute; passed through for downstream consumers. May be absent on older payloads. */
+    /** Arbitrary metadata attached in Grasshopper. Not interpreted by compute; passed through for downstream consumers. May be absent on older payloads */
     metadata?: Record<string, string>;
 };
 /**
- * Represents a normalized, processed file ready for consumption or archival.
- *
- * This is the unified intermediate format produced by processing both {@link FileData}
- * and {@link FileBaseInfo}. Files in this format are ready to be packaged into archives
- * (e.g., ZIP files) or returned to callers for programmatic use.
- *
- * @see {@link FileData} for raw compute response files
- * @see {@link FileBaseInfo} for external file references
+ * Normalized file ready for consumption or archival.
+ * Unified intermediate format from FileData or FileBaseInfo, ready to be packaged into archives or returned to callers.
  */
 type ProcessedFile = {
     /** Full filename including extension (e.g., "model.3dm") */
     fileName: string;
-    /** File content as either binary data or text. Binary format (Uint8Array) is used for decoded base64 or fetched binary files; text format is used for plain text content */
+    /** File content as binary data (Uint8Array for decoded base64 or fetched binary) or text */
     content: Uint8Array | string;
-    /** File path for archive organization (e.g., "subfolder/model.3dm"). Used when creating ZIP archives or other hierarchical structures */
+    /** File path for archive organization (e.g., "subfolder/model.3dm") */
     path: string;
 };
 /**
- * Represents a reference to an external file to be included in file operations.
- *
- * This type is used to specify additional files (beyond compute response files)
- * that should be fetched and included when processing files. The file is fetched
- * from the provided URL and processed as a {@link ProcessedFile}.
- *
- *
- * @see {@link FileData} for files from compute responses
- * @see {@link fetchRemoteFiles} for how FileBaseInfo is processed (fetched and converted)
+ * Reference to an external file to be fetched and included in file operations.
+ * Specifies additional files (beyond compute response files) to fetch and process as ProcessedFile.
+ * @see {@link fetchRemoteFiles} for how FileBaseInfo is fetched and converted
  */
 type FileBaseInfo = {
     /** Destination filename for the file in the archive or result set (e.g., "additional-data.json") */
     fileName: string;
     /** URL to fetch the file from. Must be accessible from the runtime environment */
     filePath: string;
+    /** Optional directory path for archive organization (e.g., "extras/docs"). When omitted, file lands at archive root */
+    subFolder?: string;
 };
 
-/**
- * Extracts and processes files from compute response data without downloading them.
- * Returns an array of ProcessedFile objects that can be used programmatically.
- *
- * @param downloadableFiles - An array of FileData items from the compute response.
- * @param additionalFiles - Optional additional files to include (fetched from URLs).
- * @returns A Promise resolving to an array of ProcessedFile objects.
- * @throws Will throw an error if file processing fails.
- *
- * @example
- * const files = await extractFilesFromComputeResponse(fileData);
- * files.forEach(file => {
- *   console.log(`File: ${file.fileName}, Size: ${file.content.length}`);
- * });
- */
+/** Extracts and processes files from compute response data without downloading them. */
 declare const extractFilesFromComputeResponse: (downloadableFiles: FileData[], additionalFiles?: FileBaseInfo[] | FileBaseInfo | null) => Promise<ProcessedFile[]>;
-/**
- * Downloads files from a compute response as a ZIP archive.
- * Packages multiple files into a single ZIP file and triggers a browser download.
- *
- * @param downloadableFiles - An array of FileData items from the compute response.
- * @param additionalFiles - Optional additional files to include in the ZIP (fetched from URLs).
- * @param fileFoldername - The name of the ZIP file (without extension).
- * @throws Will throw an error if the file handling or download fails.
- *
- * @example
- * await downloadDataFromComputeResponse(fileData, null, 'my-export');
- * // Downloads 'my-export.zip'
- */
+/** Downloads files from a compute response as a ZIP archive. */
 declare const downloadFileData: (downloadableFiles: FileData[], fileFoldername: string, additionalFiles?: FileBaseInfo[] | FileBaseInfo | null) => Promise<void>;
 
 export { ComputeServerStats as C, type ErrorCode as E, type FileBaseInfo as F, type ProcessedFile as P, RhinoComputeError as R, ErrorCodes as a, type FileData as b, downloadFileData as d, extractFilesFromComputeResponse as e };

package/dist/index.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkLP7LO5PRcjs = require('./chunk-LP7LO5PR.cjs');var _chunkDRG5SLIPcjs = require('./chunk-DRG5SLIP.cjs');exports.ComputeServerStats = _chunkDRG5SLIPcjs.n; exports.ErrorCodes = _chunkDRG5SLIPcjs.c; exports.GrasshopperClient = _chunkLP7LO5PRcjs.c; exports.GrasshopperResponseProcessor = _chunkLP7LO5PRcjs.d; exports.RhinoComputeError = _chunkDRG5SLIPcjs.d; exports.SolveScheduler = _chunkLP7LO5PRcjs.b; exports.TreeBuilder = _chunkLP7LO5PRcjs.i; exports.camelcaseKeys = _chunkDRG5SLIPcjs.p; exports.downloadFileData = _chunkDRG5SLIPcjs.r; exports.enableDebugLogging = _chunkDRG5SLIPcjs.g; exports.extractFilesFromComputeResponse = _chunkDRG5SLIPcjs.q; exports.fetchDefinitionIO = _chunkLP7LO5PRcjs.g; exports.fetchParsedDefinitionIO = _chunkLP7LO5PRcjs.h; exports.fetchRhinoCompute = _chunkDRG5SLIPcjs.l; exports.getLogger = _chunkDRG5SLIPcjs.e; exports.processInput = _chunkLP7LO5PRcjs.e; exports.processInputs = _chunkLP7LO5PRcjs.f; exports.setLogger = _chunkDRG5SLIPcjs.f; exports.solveGrasshopperDefinition = _chunkLP7LO5PRcjs.a; exports.toCamelCase = _chunkDRG5SLIPcjs.o;
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkQZECCPT3cjs = require('./chunk-QZECCPT3.cjs');var _chunkCUQQ3ZBVcjs = require('./chunk-CUQQ3ZBV.cjs');exports.ComputeServerStats = _chunkCUQQ3ZBVcjs.n; exports.ErrorCodes = _chunkCUQQ3ZBVcjs.c; exports.GrasshopperClient = _chunkQZECCPT3cjs.g; exports.GrasshopperResponseProcessor = _chunkQZECCPT3cjs.h; exports.RhinoComputeError = _chunkCUQQ3ZBVcjs.d; exports.SolveScheduler = _chunkQZECCPT3cjs.f; exports.TreeBuilder = _chunkQZECCPT3cjs.m; exports.camelcaseKeys = _chunkCUQQ3ZBVcjs.p; exports.downloadFileData = _chunkCUQQ3ZBVcjs.t; exports.enableDebugLogging = _chunkCUQQ3ZBVcjs.g; exports.extractFilesFromComputeResponse = _chunkCUQQ3ZBVcjs.s; exports.fetchDefinitionIO = _chunkQZECCPT3cjs.k; exports.fetchParsedDefinitionIO = _chunkQZECCPT3cjs.l; exports.fetchRhinoCompute = _chunkCUQQ3ZBVcjs.l; exports.getLogger = _chunkCUQQ3ZBVcjs.e; exports.hashDefinition = _chunkQZECCPT3cjs.e; exports.hashSolveInput = _chunkQZECCPT3cjs.d; exports.isDefinitionRef = _chunkQZECCPT3cjs.a; exports.processInput = _chunkQZECCPT3cjs.i; exports.processInputs = _chunkQZECCPT3cjs.j; exports.setLogger = _chunkCUQQ3ZBVcjs.f; exports.solveGrasshopperDefinition = _chunkQZECCPT3cjs.b; exports.stableStringify = _chunkQZECCPT3cjs.c; exports.toCamelCase = _chunkCUQQ3ZBVcjs.o;
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/selva-compute/selva-compute/dist/index.cjs"],"names":[],"mappings":"AAAA,iIAAgG,wDAAqG,y8BAA0c","file":"/home/runner/work/selva-compute/selva-compute/dist/index.cjs"}
+{"version":3,"sources":["/home/runner/work/selva/selva/packages/compute/dist/index.cjs"],"names":[],"mappings":"AAAA,iIAA4H,wDAAqG,moCAA4hB","file":"/home/runner/work/selva/selva/packages/compute/dist/index.cjs"}

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 export { Logger, camelcaseKeys, enableDebugLogging, fetchRhinoCompute, getLogger, setLogger, toCamelCase } from './core.cjs';
-export { C as ComputeServerStats, E as ErrorCode, a as ErrorCodes, F as FileBaseInfo, b as FileData, P as ProcessedFile, R as RhinoComputeError, d as downloadFileData, e as extractFilesFromComputeResponse } from './handle-files-9pkEgDIp.cjs';
-export { C as ComputeConfig, R as RetryPolicy, a as RhinoModelUnit, S as ServerTiming } from './types-ChF690kY.cjs';
-export { CacheOptions, DataTreeValue, GetValuesOptions, GetValuesResult, GrasshopperClient, GrasshopperResponseProcessor, ParsedContext, SchedulerMode, SolveContext, SolveOptions, SolveResult, SolveScheduler, SolveSchedulerOptions, TreeBuilder, fetchDefinitionIO, fetchParsedDefinitionIO, processInput, processInputs, solveGrasshopperDefinition } from './grasshopper.cjs';
-export { B as BooleanInputType, D as DataItem, a as DataTree, b as DataTreeDefault, c as DataTreePath, d as DefaultValue, F as FileInputType, G as GeometryInputType, e as GrasshopperComputeConfig, f as GrasshopperComputeResponse, g as GrasshopperParsedIO, h as GrasshopperParsedIORaw, i as GrasshopperRequestSchema, I as InnerTreeData, j as InputParam, k as InputParamSchema, N as NumericInputType, O as OutputParamSchema, l as OutputType, T as TextInputType, V as ValueListInputType } from './types-DK2-skCK.cjs';
+export { C as ComputeServerStats, E as ErrorCode, a as ErrorCodes, F as FileBaseInfo, b as FileData, P as ProcessedFile, R as RhinoComputeError, d as downloadFileData, e as extractFilesFromComputeResponse } from './handle-files-BISo_wob.cjs';
+export { C as ComputeConfig, R as RetryPolicy, a as RhinoModelUnit, S as ServerTiming } from './types-BGhtYxZ-.cjs';
+export { CacheOptions, DataTreeValue, DefinitionRef, GetValuesOptions, GetValuesResult, GrasshopperClient, GrasshopperResponseProcessor, ParsedContext, SchedulerMode, SolveContext, SolveDefinition, SolveOptions, SolveResult, SolveScheduler, SolveSchedulerOptions, TreeBuilder, fetchDefinitionIO, fetchParsedDefinitionIO, hashDefinition, hashSolveInput, isDefinitionRef, processInput, processInputs, solveGrasshopperDefinition, stableStringify } from './grasshopper.cjs';
+export { B as BooleanInputType, D as DataItem, a as DataTree, b as DataTreeDefault, c as DataTreePath, d as DefaultValue, F as FileInputType, G as GeometryInputType, e as GrasshopperComputeConfig, f as GrasshopperComputeResponse, g as GrasshopperParsedIO, h as GrasshopperParsedIORaw, i as GrasshopperRequestSchema, I as InnerTreeData, j as InputParam, k as InputParamSchema, N as NumericInputType, O as OutputParamSchema, l as OutputType, T as TextInputType, V as ValueListInputType } from './types-C8XWc4Ab.cjs';
 import 'three';
 import 'rhino3dm';

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { Logger, camelcaseKeys, enableDebugLogging, fetchRhinoCompute, getLogger, setLogger, toCamelCase } from './core.js';
-export { C as ComputeServerStats, E as ErrorCode, a as ErrorCodes, F as FileBaseInfo, b as FileData, P as ProcessedFile, R as RhinoComputeError, d as downloadFileData, e as extractFilesFromComputeResponse } from './handle-files-9pkEgDIp.js';
-export { C as ComputeConfig, R as RetryPolicy, a as RhinoModelUnit, S as ServerTiming } from './types-ChF690kY.js';
-export { CacheOptions, DataTreeValue, GetValuesOptions, GetValuesResult, GrasshopperClient, GrasshopperResponseProcessor, ParsedContext, SchedulerMode, SolveContext, SolveOptions, SolveResult, SolveScheduler, SolveSchedulerOptions, TreeBuilder, fetchDefinitionIO, fetchParsedDefinitionIO, processInput, processInputs, solveGrasshopperDefinition } from './grasshopper.js';
-export { B as BooleanInputType, D as DataItem, a as DataTree, b as DataTreeDefault, c as DataTreePath, d as DefaultValue, F as FileInputType, G as GeometryInputType, e as GrasshopperComputeConfig, f as GrasshopperComputeResponse, g as GrasshopperParsedIO, h as GrasshopperParsedIORaw, i as GrasshopperRequestSchema, I as InnerTreeData, j as InputParam, k as InputParamSchema, N as NumericInputType, O as OutputParamSchema, l as OutputType, T as TextInputType, V as ValueListInputType } from './types-jb_K_a0s.js';
+export { C as ComputeServerStats, E as ErrorCode, a as ErrorCodes, F as FileBaseInfo, b as FileData, P as ProcessedFile, R as RhinoComputeError, d as downloadFileData, e as extractFilesFromComputeResponse } from './handle-files-BISo_wob.js';
+export { C as ComputeConfig, R as RetryPolicy, a as RhinoModelUnit, S as ServerTiming } from './types-BGhtYxZ-.js';
+export { CacheOptions, DataTreeValue, DefinitionRef, GetValuesOptions, GetValuesResult, GrasshopperClient, GrasshopperResponseProcessor, ParsedContext, SchedulerMode, SolveContext, SolveDefinition, SolveOptions, SolveResult, SolveScheduler, SolveSchedulerOptions, TreeBuilder, fetchDefinitionIO, fetchParsedDefinitionIO, hashDefinition, hashSolveInput, isDefinitionRef, processInput, processInputs, solveGrasshopperDefinition, stableStringify } from './grasshopper.js';
+export { B as BooleanInputType, D as DataItem, a as DataTree, b as DataTreeDefault, c as DataTreePath, d as DefaultValue, F as FileInputType, G as GeometryInputType, e as GrasshopperComputeConfig, f as GrasshopperComputeResponse, g as GrasshopperParsedIO, h as GrasshopperParsedIORaw, i as GrasshopperRequestSchema, I as InnerTreeData, j as InputParam, k as InputParamSchema, N as NumericInputType, O as OutputParamSchema, l as OutputType, T as TextInputType, V as ValueListInputType } from './types-Dtok-mVq.js';
 import 'three';
 import 'rhino3dm';

package/dist/index.js

@@ -1,2 +1,2 @@
-import{a as d,b as g,c as h,d as i,e as j,f as k,g as l,h as n,i as q}from"./chunk-ESPPM542.js";import{c as o,d as r,e,f,g as m,l as p,n as t,o as x,p as a,q as b,r as c}from"./chunk-J3MFKB33.js";export{t as ComputeServerStats,o as ErrorCodes,h as GrasshopperClient,i as GrasshopperResponseProcessor,r as RhinoComputeError,g as SolveScheduler,q as TreeBuilder,a as camelcaseKeys,c as downloadFileData,m as enableDebugLogging,b as extractFilesFromComputeResponse,l as fetchDefinitionIO,n as fetchParsedDefinitionIO,p as fetchRhinoCompute,e as getLogger,j as processInput,k as processInputs,f as setLogger,d as solveGrasshopperDefinition,x as toCamelCase};
+import{a as d,b as g,c as h,d as i,e as j,f as k,g as l,h as n,i as q,j as s,k as u,l as v,m as w}from"./chunk-C7P43VZF.js";import{c as o,d as r,e,f,g as m,l as p,n as t,o as x,p as a,s as b,t as c}from"./chunk-WPB2LKCD.js";export{t as ComputeServerStats,o as ErrorCodes,l as GrasshopperClient,n as GrasshopperResponseProcessor,r as RhinoComputeError,k as SolveScheduler,w as TreeBuilder,a as camelcaseKeys,c as downloadFileData,m as enableDebugLogging,b as extractFilesFromComputeResponse,u as fetchDefinitionIO,v as fetchParsedDefinitionIO,p as fetchRhinoCompute,e as getLogger,j as hashDefinition,i as hashSolveInput,d as isDefinitionRef,q as processInput,s as processInputs,f as setLogger,g as solveGrasshopperDefinition,h as stableStringify,x as toCamelCase};
 //# sourceMappingURL=index.js.map

package/dist/types-BGhtYxZ-.d.cts

@@ -0,0 +1,45 @@
+type RhinoModelUnit = 'None' | 'Microns' | 'Millimeters' | 'Centimeters' | 'Meters' | 'Kilometers' | 'Microinches' | 'Mils' | 'Inches' | 'Feet' | 'Miles' | 'CustomUnits' | 'Angstroms' | 'Nanometers' | 'Decimeters' | 'Dekameters' | 'Hectometers' | 'Megameters' | 'Gigameters' | 'Yards' | 'PrinterPoints' | 'PrinterPicas' | 'NauticalMiles' | 'AstronomicalUnits' | 'LightYears' | 'Parsecs' | 'Unset';
+interface RetryPolicy {
+    /** Maximum number of retry attempts after the initial request (default: 0). */
+    attempts?: number;
+    /** Base delay in milliseconds for exponential backoff (default: 500). */
+    baseDelayMs?: number;
+    /** Upper bound for backoff delay (default: 30_000). */
+    maxDelayMs?: number;
+    /** Whether to retry on 429 responses (default: true — honors Retry-After). */
+    retryOn429?: boolean;
+}
+interface ComputeConfig {
+    serverUrl: string;
+    /** Optional API key for authenticating with the server (RhinoComputeKey) */
+    apiKey?: string;
+    /** Optional Bearer token for authentication (e.g., when behind a proxy or API gateway) */
+    authToken?: string;
+    headers?: Record<string, string>;
+    /** Enable debug logging to the console */
+    debug?: boolean;
+    /** Suppress browser security warnings in the console */
+    suppressBrowserWarning?: boolean;
+    /** @deprecated Renamed to `suppressBrowserWarning`. */
+    suppressClientSideWarning?: boolean;
+    timeoutMs?: number;
+    /**
+     * Retry policy for transient errors. Default: no retries.
+     */
+    retry?: RetryPolicy;
+    /**
+     * Optional caller-supplied AbortSignal. Composes with the internal timeout —
+     * whichever fires first wins. Lets callers cancel in-flight requests
+     * (e.g. on component unmount or when superseding a stale solve).
+     */
+    signal?: AbortSignal;
+    onServerTiming?: (timing: ServerTiming, requestId: string) => void;
+}
+interface ServerTiming {
+    decode?: number;
+    solve?: number;
+    encode?: number;
+    raw: string;
+}
+
+export type { ComputeConfig as C, RetryPolicy as R, ServerTiming as S, RhinoModelUnit as a };

package/dist/types-BGhtYxZ-.d.ts

@@ -0,0 +1,45 @@
+type RhinoModelUnit = 'None' | 'Microns' | 'Millimeters' | 'Centimeters' | 'Meters' | 'Kilometers' | 'Microinches' | 'Mils' | 'Inches' | 'Feet' | 'Miles' | 'CustomUnits' | 'Angstroms' | 'Nanometers' | 'Decimeters' | 'Dekameters' | 'Hectometers' | 'Megameters' | 'Gigameters' | 'Yards' | 'PrinterPoints' | 'PrinterPicas' | 'NauticalMiles' | 'AstronomicalUnits' | 'LightYears' | 'Parsecs' | 'Unset';
+interface RetryPolicy {
+    /** Maximum number of retry attempts after the initial request (default: 0). */
+    attempts?: number;
+    /** Base delay in milliseconds for exponential backoff (default: 500). */
+    baseDelayMs?: number;
+    /** Upper bound for backoff delay (default: 30_000). */
+    maxDelayMs?: number;
+    /** Whether to retry on 429 responses (default: true — honors Retry-After). */
+    retryOn429?: boolean;
+}
+interface ComputeConfig {
+    serverUrl: string;
+    /** Optional API key for authenticating with the server (RhinoComputeKey) */
+    apiKey?: string;
+    /** Optional Bearer token for authentication (e.g., when behind a proxy or API gateway) */
+    authToken?: string;
+    headers?: Record<string, string>;
+    /** Enable debug logging to the console */
+    debug?: boolean;
+    /** Suppress browser security warnings in the console */
+    suppressBrowserWarning?: boolean;
+    /** @deprecated Renamed to `suppressBrowserWarning`. */
+    suppressClientSideWarning?: boolean;
+    timeoutMs?: number;
+    /**
+     * Retry policy for transient errors. Default: no retries.
+     */
+    retry?: RetryPolicy;
+    /**
+     * Optional caller-supplied AbortSignal. Composes with the internal timeout —
+     * whichever fires first wins. Lets callers cancel in-flight requests
+     * (e.g. on component unmount or when superseding a stale solve).
+     */
+    signal?: AbortSignal;
+    onServerTiming?: (timing: ServerTiming, requestId: string) => void;
+}
+interface ServerTiming {
+    decode?: number;
+    solve?: number;
+    encode?: number;
+    raw: string;
+}
+
+export type { ComputeConfig as C, RetryPolicy as R, ServerTiming as S, RhinoModelUnit as a };

package/dist/{types-DK2-skCK.d.cts → types-C8XWc4Ab.d.cts}

@@ -1,57 +1,44 @@
-import { C as ComputeConfig, a as RhinoModelUnit } from './types-ChF690kY.cjs';
+import { C as ComputeConfig, a as RhinoModelUnit } from './types-BGhtYxZ-.cjs';
 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,18 +194,34 @@ 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;
-    /** Base64 encoded algorithm (always present in response) */
-    algo: string;
+    /**
+     * The server echoes the request's full base64 definition back as `algo`, but the client strips
+     * it before returning — retaining it would pin a multi-MB copy of the definition per response,
+     * multiplied by every cache that holds responses. Always `undefined` on client-returned
+     * responses (inherited optional field from {@link GrasshopperDefinitionSource}).
+     */
+    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 */
@@ -327,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`)
@@ -362,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;
@@ -385,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;
 }
 /**
@@ -416,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;
@@ -463,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. */
@@ -485,16 +489,37 @@ 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 "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 `setLook`.
+     */
+    material?: MaterialAppearanceOptions;
+}
+/**
+ * How compute meshes read visually. Bundled so a caller can pick a coherent look ('technical' vs
+ * 'rendered') by setting all three together rather than dialing each in isolation.
+ */
+interface MaterialAppearanceOptions {
+    /**
+     * Multiplier on the HDR image-based-lighting reflection strength. ~0.5 reads matte/technical,
+     * ~1.3 reads glossy/presentation. Default 1 (three.js's own default — unchanged look).
+     */
+    envMapIntensity?: number;
+    /**
+     * Cull back faces (`THREE.FrontSide`) instead of rendering both sides (`THREE.DoubleSide`).
+     * FrontSide gives cleaner interior shading, a crisper silhouette, and less overdraw on closed
+     * solids — but open surfaces (which Rhino also emits) then vanish when viewed from behind.
+     * Default false (keep DoubleSide) to stay safe for surface geometry.
+     */
+    cullBackfaces?: boolean;
 }
 /**
  * Options for extracting and processing meshes from compute responses.
@@ -515,4 +540,4 @@ interface MeshExtractionOptions {
     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, DisplayBatch as n, DisplayItem as o, DisplayCurve as p, DisplayIdentity as q, DisplayItemBase as r, DisplayPoint as s, DisplayPosition as t, MeshBatch as u };
+export type { BooleanInputType as B, DataItem as D, FileInputType as F, GeometryInputType as G, InnerTreeData as I, MaterialAppearanceOptions 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, MeshExtractionOptions as m, MeshBatchParsingOptions as n, DisplayBatch as o, DisplayItem as p, DisplayCurve as q, DisplayIdentity as r, DisplayItemBase as s, DisplayPoint as t, DisplayPosition as u, MeshBatch as v };