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

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 _chunk33753HSVcjs = require('./chunk-33753HSV.cjs');var _chunkD7A3YIYDcjs = require('./chunk-D7A3YIYD.cjs');exports.ComputeServerStats = _chunkD7A3YIYDcjs.n; exports.ErrorCodes = _chunkD7A3YIYDcjs.c; exports.GrasshopperClient = _chunk33753HSVcjs.c; exports.GrasshopperResponseProcessor = _chunk33753HSVcjs.d; exports.RhinoComputeError = _chunkD7A3YIYDcjs.d; exports.SolveScheduler = _chunk33753HSVcjs.b; exports.TreeBuilder = _chunk33753HSVcjs.i; exports.camelcaseKeys = _chunkD7A3YIYDcjs.p; exports.downloadFileData = _chunkD7A3YIYDcjs.r; exports.enableDebugLogging = _chunkD7A3YIYDcjs.g; exports.extractFilesFromComputeResponse = _chunkD7A3YIYDcjs.q; exports.fetchDefinitionIO = _chunk33753HSVcjs.g; exports.fetchParsedDefinitionIO = _chunk33753HSVcjs.h; exports.fetchRhinoCompute = _chunkD7A3YIYDcjs.l; exports.getLogger = _chunkD7A3YIYDcjs.e; exports.processInput = _chunk33753HSVcjs.e; exports.processInputs = _chunk33753HSVcjs.f; exports.setLogger = _chunkD7A3YIYDcjs.f; exports.solveGrasshopperDefinition = _chunk33753HSVcjs.a; exports.toCamelCase = _chunkD7A3YIYDcjs.o;
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkY5E6RIEHcjs = require('./chunk-Y5E6RIEH.cjs');var _chunkCUQQ3ZBVcjs = require('./chunk-CUQQ3ZBV.cjs');exports.ComputeServerStats = _chunkCUQQ3ZBVcjs.n; exports.ErrorCodes = _chunkCUQQ3ZBVcjs.c; exports.GrasshopperClient = _chunkY5E6RIEHcjs.g; exports.GrasshopperResponseProcessor = _chunkY5E6RIEHcjs.h; exports.RhinoComputeError = _chunkCUQQ3ZBVcjs.d; exports.SolveScheduler = _chunkY5E6RIEHcjs.f; exports.TreeBuilder = _chunkY5E6RIEHcjs.m; exports.camelcaseKeys = _chunkCUQQ3ZBVcjs.p; exports.downloadFileData = _chunkCUQQ3ZBVcjs.t; exports.enableDebugLogging = _chunkCUQQ3ZBVcjs.g; exports.extractFilesFromComputeResponse = _chunkCUQQ3ZBVcjs.s; exports.fetchDefinitionIO = _chunkY5E6RIEHcjs.k; exports.fetchParsedDefinitionIO = _chunkY5E6RIEHcjs.l; exports.fetchRhinoCompute = _chunkCUQQ3ZBVcjs.l; exports.getLogger = _chunkCUQQ3ZBVcjs.e; exports.hashDefinition = _chunkY5E6RIEHcjs.e; exports.hashSolveInput = _chunkY5E6RIEHcjs.d; exports.isDefinitionRef = _chunkY5E6RIEHcjs.a; exports.processInput = _chunkY5E6RIEHcjs.i; exports.processInputs = _chunkY5E6RIEHcjs.j; exports.setLogger = _chunkCUQQ3ZBVcjs.f; exports.solveGrasshopperDefinition = _chunkY5E6RIEHcjs.b; exports.stableStringify = _chunkY5E6RIEHcjs.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-compute/selva-compute/dist/index.cjs"],"names":[],"mappings":"AAAA,iIAA4H,wDAAqG,moCAA4hB","file":"/home/runner/work/selva-compute/selva-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-V7G83j5m.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-DxPi5SEx.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-V7G83j5m.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-BBSF_ISX.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-MDFVHHH6.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-EMXDP7KY.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-JNFNLKFO.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-BBSF_ISX.d.ts → types-C8XWc4Ab.d.cts}

@@ -1,57 +1,44 @@
-import { C as ComputeConfig, a as RhinoModelUnit } from './types-V7G83j5m.js';
+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,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;
 }