@selvajs/compute 1.5.0

package/dist/grasshopper.d.ts

@@ -0,0 +1,1014 @@
+import { R as RhinoComputeError, C as ComputeServerStats } from './base-dtik4Dlu.js';
+import { b as DataTreeDefault, O as OutputParamSchema, f as InputParamSchema, R as RetryPolicy, d as GrasshopperComputeResponse, a as DataTree, G as GrasshopperComputeConfig, C as ComputeConfig, c as DataTreePath } from './schemas-Ct7lU-IH.js';
+export { D as DataItem, e as GrasshopperRequestSchema, I as InnerTreeData, g as RhinoModelUnit } from './schemas-Ct7lU-IH.js';
+import * as THREE from 'three';
+import { M as MeshExtractionOptions } from './types-B24K2LG4.js';
+
+/**
+ * Input and output parameter types
+ */
+
+/**
+ * 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;
+/**
+ * Union type for all possible default value types
+ */
+type DefaultValue<T> = T | T[] | DataTreeDefault<T> | undefined | null;
+/**
+ * Base properties common to all processed input types.
+ * Note: `groupName` and `id` require the custom Rhino Compute branch.
+ */
+interface BaseInputType {
+    description: string;
+    name: string;
+    nickname: string | null;
+    treeAccess: boolean;
+    /**
+     * Name of the group this parameter belongs to.
+     * @requires Custom branch of compute.rhino3d
+     */
+    groupName?: string;
+    /**
+     * Unique identifier for the parameter.
+     * @requires Custom branch of compute.rhino3d
+     */
+    id?: string;
+}
+/**
+ * Numeric input type (Number or Integer)
+ */
+interface NumericInputType extends BaseInputType {
+    paramType: 'Number' | 'Integer';
+    minimum?: number | null;
+    maximum?: number | null;
+    atLeast?: number | null;
+    atMost?: number | null;
+    stepSize?: number | null;
+    default: DefaultValue<number>;
+}
+/**
+ * Text input type
+ */
+interface TextInputType extends BaseInputType {
+    paramType: 'Text';
+    default: DefaultValue<string>;
+}
+/**
+ * Boolean input type
+ */
+interface BooleanInputType extends BaseInputType {
+    paramType: 'Boolean';
+    default: DefaultValue<boolean>;
+}
+/**
+ * Geometry input type (generic geometry)
+ */
+interface GeometryInputType extends BaseInputType {
+    paramType: 'Geometry';
+    default: DefaultValue<object | string>;
+}
+/**
+ * ValueList input type (dropdown/select)
+ */
+interface ValueListInputType extends BaseInputType {
+    paramType: 'ValueList';
+    values: Record<string, string>;
+    default?: string;
+}
+/**
+ * File input type
+ */
+interface FileInputType extends BaseInputType {
+    paramType: 'File';
+    acceptedFormats?: string[];
+    default: DefaultValue<object | string>;
+}
+/**
+ * Color input type (stored as hex string)
+ */
+interface ColorInputType extends BaseInputType {
+    paramType: 'Color';
+    default: DefaultValue<string>;
+}
+/**
+ * Discriminated union of all input parameter types
+ */
+type InputParam = NumericInputType | BooleanInputType | TextInputType | ValueListInputType | GeometryInputType | FileInputType | ColorInputType;
+
+/**
+ * Parsed data structures for processed Grasshopper input/output
+ */
+
+/**
+ * Parsed input/output structure with raw schemas
+ */
+interface GrasshopperParsedIORaw {
+    inputs: InputParamSchema[];
+    outputs: OutputParamSchema[];
+}
+/**
+ * Parsed input/output structure with processed types
+ */
+interface GrasshopperParsedIO {
+    inputs: InputParam[];
+    outputs: OutputParamSchema[];
+}
+
+/**
+ * Scheduling mode — controls how concurrent `solve()` calls interact.
+ *
+ * - `latest-wins`: One in flight at a time. New calls supersede any pending
+ *   call (in-flight one is aborted). Optimal for slider scrubs / live UIs.
+ * - `queue`: FIFO queue. Each solve runs to completion. Concurrency capped
+ *   by `maxConcurrent`. Use for "submit job" flows where every request matters.
+ * - `parallel`: No scheduling — calls run concurrently up to `maxConcurrent`.
+ *   Closest to plain `client.solve()` but with shared cancel/state.
+ */
+type SchedulerMode = 'latest-wins' | 'queue' | 'parallel';
+interface CacheOptions {
+    /** Maximum entries kept in the LRU. Default: 50. */
+    maxEntries?: number;
+    /** Time-to-live in ms. Set to `0` for no expiry (default). */
+    ttlMs?: number;
+}
+interface SolveSchedulerOptions {
+    mode?: SchedulerMode;
+    maxConcurrent?: number;
+    timeoutMs?: number;
+    retry?: RetryPolicy;
+    /** Enable response caching keyed by hash of (definition, dataTree). */
+    cache?: boolean | CacheOptions;
+    /** Lifecycle hooks — fired in order. Errors thrown by hooks are logged, not rethrown. */
+    onStart?: (ctx: SolveContext) => void;
+    onSettle?: (ctx: SolveContext, result: SolveResult) => void;
+    onSuperseded?: (ctx: SolveContext) => void;
+}
+interface SolveContext {
+    /** Stable hash of (definition, dataTree). */
+    key: string;
+    /** Wall-clock timestamp when scheduler.solve() was called. */
+    enqueuedAt: number;
+    /** Wall-clock timestamp when execution actually started (after queueing). */
+    startedAt: number | null;
+}
+type SolveResult = {
+    status: 'success';
+    response: GrasshopperComputeResponse;
+    durationMs: number;
+    fromCache: boolean;
+} | {
+    status: 'error';
+    error: RhinoComputeError;
+    durationMs: number;
+} | {
+    status: 'superseded';
+};
+/**
+ * Adapter for the underlying solve function. Lets the scheduler be tested
+ * without a real Compute server, and decouples it from the client class.
+ */
+type SolveExecutor = (definition: string | Uint8Array, dataTree: DataTree[], config: GrasshopperComputeConfig) => Promise<GrasshopperComputeResponse>;
+/**
+ * Robust scheduler for Grasshopper solves.
+ *
+ * Sits between your application code and the underlying compute call,
+ * adding:
+ * - Configurable scheduling (latest-wins for sliders, queue for jobs)
+ * - In-flight cancellation (per-call signal + cancelAll)
+ * - Optional response caching for repeated inputs
+ * - Lifecycle hooks for UI indicators (start / settle / superseded)
+ * - State observability via subscribe()
+ *
+ * Multiple schedulers can share a single GrasshopperClient — typically one
+ * per UI surface (e.g. one for slider scrubs, one for long-running submits).
+ *
+ * @example
+ * ```ts
+ * const scheduler = client.createScheduler({ mode: 'latest-wins', timeoutMs: 30_000 });
+ *
+ * // From a slider handler:
+ * scheduler.solve(definition, tree).then((result) => {
+ *   updateMeshes(result);
+ * }).catch((err) => {
+ *   if (err.code !== 'SUPERSEDED') showError(err);
+ * });
+ *
+ * // From a UI binding:
+ * scheduler.subscribe(() => {
+ *   showSpinner = scheduler.isSolving;
+ * });
+ * ```
+ */
+declare class SolveScheduler {
+    private readonly executor;
+    private readonly baseConfig;
+    private readonly mode;
+    private readonly maxConcurrent;
+    private readonly timeoutMs;
+    private readonly retry;
+    private readonly cacheEnabled;
+    private readonly cacheMax;
+    private readonly cacheTtl;
+    private readonly cache;
+    private readonly onStart?;
+    private readonly onSettle?;
+    private readonly onSuperseded?;
+    private readonly subscribers;
+    private readonly inFlight;
+    private pendingForLatestWins;
+    private readonly fifoQueue;
+    private _lastResult;
+    private _lastError;
+    private _lastDurationMs;
+    private disposed;
+    constructor(executor: SolveExecutor, baseConfig: GrasshopperComputeConfig, options?: SolveSchedulerOptions);
+    get isSolving(): boolean;
+    get hasPending(): boolean;
+    get inFlightCount(): number;
+    get queueDepth(): number;
+    get lastResult(): GrasshopperComputeResponse | null;
+    get lastError(): RhinoComputeError | null;
+    get lastDurationMs(): number | null;
+    subscribe(listener: () => void): () => void;
+    private notify;
+    /**
+     * Schedule a solve. Returns a promise that:
+     * - Resolves with the compute response on success.
+     * - Rejects with `RhinoComputeError` on failure.
+     * - Rejects with `code: ErrorCodes.UNKNOWN_ERROR` and `message: 'Superseded'`
+     *   when the call was canceled because newer values arrived (latest-wins mode).
+     *
+     * Caller-supplied `signal` cancels just this call (rejects with abort error).
+     */
+    solve(definition: string | Uint8Array, dataTree: DataTree[], options?: {
+        signal?: AbortSignal;
+    }): Promise<GrasshopperComputeResponse>;
+    private enqueue;
+    private execute;
+    private drainNext;
+    private supersede;
+    private makeAbortError;
+    /** Cancel everything — in-flight and pending. */
+    cancelAll(): void;
+    private readCache;
+    private writeCache;
+    clearCache(): void;
+    dispose(): void;
+    private runHook;
+}
+
+/**
+ * Hash a (definition, dataTree) pair into a short stable key.
+ * For Uint8Array definitions we use length + endpoint bytes rather than the
+ * full content to keep hashing cheap.
+ */
+declare function hashSolveInput(definition: string | Uint8Array, dataTree: unknown): string;
+
+/**
+ * Per-call options that override the client's default ComputeConfig values.
+ *
+ * Use these for per-request control without mutating the client config:
+ * - `signal` — cancel a specific solve (e.g. when a slider value is superseded)
+ * - `timeoutMs` — extend timeout for a long-running solve, or pass `0` to disable
+ * - `retry` — override retry policy for this call only
+ */
+interface SolveOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    retry?: RetryPolicy;
+}
+/**
+ * GrasshopperClient provides a simple API for interacting with a Rhino Compute server and grasshopper.
+ *
+ * @public This is the recommended high-level API for Rhino Compute operations.
+ *
+ * **Security Warning:**
+ * Using this client in a browser environment exposes your server URL and API key to users.
+ * For production, use this library server-side or proxy requests through your own backend.
+ *
+ * @example
+ * ```typescript
+ * const client = await GrasshopperClient.create({
+ *   serverUrl: 'http://localhost:6500',
+ *   apiKey: 'your-api-key'
+ * });
+ *
+ * try {
+ *   const result = await client.solve(definitionUrl, { x: 1, y: 2 });
+ * } finally {
+ *   await client.dispose(); // Clean up resources
+ * }
+ * ```
+ */
+declare class GrasshopperClient {
+    private readonly config;
+    readonly serverStats: ComputeServerStats;
+    private disposed;
+    private constructor();
+    /**
+     * Creates and initializes a GrasshopperClient with server validation.
+     *
+     * @throws {RhinoComputeError} with code NETWORK_ERROR if server is offline
+     * @throws {RhinoComputeError} with code INVALID_CONFIG if configuration is invalid
+     */
+    static create(config: GrasshopperComputeConfig): Promise<GrasshopperClient>;
+    /**
+     * Gets the client's configuration.
+     * Useful for passing to lower-level functions.
+     */
+    getConfig(): GrasshopperComputeConfig;
+    /**
+     * Get input/output parameters of a Grasshopper definition.
+     */
+    getIO(definition: string | Uint8Array): Promise<GrasshopperParsedIO>;
+    getRawIO(definition: string | Uint8Array): Promise<GrasshopperParsedIORaw>;
+    /**
+     * Run a compute job with a Grasshopper definition.
+     *
+     * @throws {RhinoComputeError} with code INVALID_INPUT if definition is empty
+     * @throws {RhinoComputeError} with code NETWORK_ERROR if server is offline
+     * @throws {RhinoComputeError} with code COMPUTATION_ERROR if computation fails
+     */
+    solve(definition: string | Uint8Array, dataTree: DataTree[], options?: SolveOptions): Promise<GrasshopperComputeResponse>;
+    /**
+     * Create a scheduler bound to this client. Use a scheduler for any UI surface
+     * that fires solves frequently (sliders, live editors) or that needs cancel
+     * semantics, response caching, or state observability.
+     *
+     * Multiple schedulers can be created from a single client — typically one per
+     * UI surface so their queues stay independent.
+     *
+     * @example
+     * ```ts
+     * const sliderScheduler = client.createScheduler({ mode: 'latest-wins' });
+     * const submitScheduler = client.createScheduler({ mode: 'queue', timeoutMs: 0, retry: { attempts: 1 } });
+     * ```
+     */
+    createScheduler(options?: SolveSchedulerOptions): SolveScheduler;
+    /**
+     * Disposes of client resources.
+     * Call this when you're done using the client.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Ensures the client hasn't been disposed.
+     */
+    private ensureNotDisposed;
+    /**
+     * Validates and normalizes a compute configuration.
+     *
+     * @throws {RhinoComputeError} with code INVALID_CONFIG if configuration is invalid
+     */
+    private normalizeComputeConfig;
+}
+
+/**
+ * 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
+ * @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} */
+    data: string;
+    /** File extension including the dot (e.g., ".3dm", ".json"). Appended to {@link 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 */
+    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" */
+    subFolder: 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
+ */
+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 */
+    content: Uint8Array | string;
+    /** File path for archive organization (e.g., "subfolder/model.3dm"). Used when creating ZIP archives or other hierarchical structures */
+    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 processFiles} for how FileBaseInfo is processed (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;
+};
+
+interface ParsedContext {
+    [key: string]: any;
+}
+interface GetValuesOptions {
+    parseValues?: boolean;
+    rhino?: any;
+    /**
+     * If true, only include values of type System.String in the result.
+     * Non-string types are filtered out.
+     */
+    stringOnly?: boolean;
+}
+interface GetValuesResult<T = ParsedContext> {
+    values: T;
+}
+
+/**
+ * High-level wrapper for interacting with Grasshopper Compute responses.
+ *
+ * This class exposes a clean, consistent API for accessing parsed values,
+ * geometry, and produced files. It is designed to be the primary interface
+ * when working with Grasshopper results in client applications.
+ */
+declare class GrasshopperResponseProcessor {
+    private readonly response;
+    private readonly debug;
+    /**
+     * Store the compute response for reuse.
+     */
+    constructor(response: GrasshopperComputeResponse, debug?: boolean);
+    /**
+     * Extract all values in the response.
+     *
+     * @typeParam T - Expected structure of the return value. Defaults to a simple key/value map. (later cast as needed)
+     * @param byId - If true, keys are parameter IDs; if false, keys are parameter names.
+     * @param options - Controls parsing behavior such as Rhino geometry decoding.
+     * @returns Parsed Grasshopper output values.
+     *
+     * **Note:** Using `byId` only works with the custom VektorNode rhino.compute branch.
+     *
+     * @example
+     * ```ts
+     * const processor = new GrasshopperResponseProcessor(response);
+     * const { values } = processor.getValues();
+     * ```
+     *
+     * @example
+     * ```ts
+     * const { values } = processor.getValues(true); // keyed by param ID
+     * ```
+     */
+    getValues<T = ParsedContext>(byId?: boolean, options?: GetValuesOptions): GetValuesResult<T>;
+    /**
+     * Retrieve a specific value using the parameter name.
+     *
+     * @param paramName - Human-readable parameter name from the Grasshopper definition.
+     * @param options - Parsing configuration (e.g. disable parsing or enable Rhino).
+     * @returns Single parsed value, array of values, or undefined if the parameter is absent.
+     *
+     * @example
+     * ```ts
+     * const schema = processor.getValueByParamName('Schema');
+     * ```
+     */
+    getValueByParamName(paramName: string, options?: GetValuesOptions): any;
+    /**
+     * Retrieve a specific value using the parameter ID.
+     *
+     * @param paramId - Parameter GUID from the Grasshopper definition.
+     * @param options - Parsing configuration (e.g. disable parsing or enable Rhino).
+     * @returns Parsed value, array of values, or undefined if not present.
+     *
+     * @example
+     * ```ts
+     * const output = processor.getValueByParamId('a4be1c1e-23f9-4c27-b942-7f3bb2c45c6f');
+     * ```
+     */
+    getValueByParamId(paramId: string, options?: GetValuesOptions): any;
+    /**
+     * Convert all geometry results into Three.js mesh objects.
+     *
+     * This uses internal helpers to decode Rhino geometry into Three.js
+     * primitives such as meshes and lines, making them ready for rendering.
+     *
+     * All processing options (scaling, positioning, compression, etc.) can be customized.
+     * The processor's debug flag is merged with options - explicit options take precedence.
+     *
+     * **Note:** This only works when using the **Selva Display** component in Grasshopper, and requires the custom branch of rhino.compute from VektorNode. This method dynamically imports three.js visualization modules. Ensure three.js is installed as a peer dependency if you use this feature.
+     *
+     * @param options - Configuration for mesh extraction and parsing. Overrides processor's debug flag if provided.
+     * @returns Promise resolving to an array of Three.js mesh objects.
+     * @throws {RhinoComputeError} If three.js visualization module cannot be loaded.
+     *
+     * @example
+     * ```ts
+     * const meshes = await processor.extractMeshesFromResponse();
+     * scene.add(...meshes);
+     * ```
+     *
+     * @example
+     * ```ts
+     * const meshes = await processor.extractMeshesFromResponse({
+     *   debug: true,
+     *   allowScaling: true,
+     *   allowAutoPosition: false,
+     *   parsing: {
+     *     mergeByMaterial: false,
+     *     applyTransforms: true,
+     *     debug: true,
+     *   },
+     * });
+     * ```
+     */
+    extractMeshesFromResponse(options?: MeshExtractionOptions): Promise<THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>[]>;
+    /**
+     * Extract internal file data structures from the response.
+     * This includes Grasshopper-generated textures, JSON exports,
+     * CAD formats, or any file structure packaged in the response.
+     *
+     * **Note:** This only works when using the **Block to File** and **Geometry To File** components from the Selva plugin in Grasshopper, and requires the custom branch of rhino.compute from VektorNode.
+     *
+     * @returns Raw file data entries.
+     */
+    private getFileData;
+    /**
+     * Download all files generated by Grasshopper, optionally including
+     * additional user-provided files.
+     *
+     * Files are grouped under the specified folder name when downloaded.
+     *
+     * @param folderName - Name for the download directory.
+     * @param additionalFiles - Extra files to package (single file, array, or null).
+     *
+     * @example
+     * ```ts
+     * processor.getAndDownloadFiles('gh-output');
+     * ```
+     *
+     * @example
+     * ```ts
+     * const extra = { name: 'notes.txt', data: 'Example' };
+     * processor.getAndDownloadFiles('project', extra);
+     * ```
+     */
+    getAndDownloadFiles(folderName: string, additionalFiles?: FileBaseInfo[] | FileBaseInfo | null): void;
+}
+
+/**
+ * Runs a Rhino Compute job using the provided tree prototypes and Grasshopper definition.
+ *
+ * @public Use this for direct compute control. For high-level API, use `GrasshopperClient.solve()`.
+ *
+ * @param dataTree - An array of `DataTree` objects representing the input data for the compute job.
+ * @param definition - The Grasshopper definition, which can be:
+ *   - A URL string (e.g., 'https://example.com/definition.gh')
+ *   - A base64-encoded string of the .gh file
+ *   - A plain string (will be base64-encoded)
+ *   - A Uint8Array of the .gh file (will be base64-encoded)
+ * @param config - Compute configuration (server URL, API key, etc. along with optional timeout, units, etc.)
+ * @returns An object containing the compute result and extracted file data.
+ *
+ * @example
+ * // Using a URL
+ * await solveGrasshopperDefinition(trees, 'https://example.com/definition.gh', config);
+ *
+ * // Using a base64 string
+ * await solveGrasshopperDefinition(trees, 'UEsDBBQAAAAIAL...', config);
+ *
+ * // Using binary data
+ * const fileData = new Uint8Array([...]);
+ * await solveGrasshopperDefinition(trees, fileData, config);
+ */
+declare function solveGrasshopperDefinition(dataTree: DataTree[], definition: string | Uint8Array, config: GrasshopperComputeConfig): Promise<GrasshopperComputeResponse>;
+
+/**
+ * Fetches raw input/output schemas from a Grasshopper definition.
+ * Returns unprocessed data exactly as received from the Rhino Compute API (camelCased).
+ *
+ * @param definition - The Grasshopper definition (URL, base64 string, or Uint8Array)
+ * @param config - Compute configuration (server URL, API key, etc.)
+ * @returns Raw inputs and outputs with no type processing
+ * @throws {RhinoComputeError} If fetch fails or response is invalid
+ *
+ * @public Use `fetchParsedDefinitionIO()` for processed, type-safe inputs
+ */
+declare function fetchDefinitionIO(definition: string | Uint8Array, config: ComputeConfig): Promise<GrasshopperParsedIORaw>;
+/**
+ * Fetches and processes input/output schemas from a Grasshopper definition.
+ * Returns strongly-typed, validated input parameters ready for use.
+ *
+ * @public This is the recommended way to fetch definition I/O schemas.
+ *
+ * @param definition - The Grasshopper definition (URL, base64 string, or Uint8Array)
+ * @param config - Compute configuration (server URL, API key, etc.)
+ * @returns Processed inputs with discriminated union types and outputs
+ * @throws {RhinoComputeError} If fetch fails or response is invalid
+ *
+ * @example
+ * ```typescript
+ * const { inputs, outputs } = await fetchParsedDefinitionIO(
+ *   'https://example.com/definition.gh',
+ *   { serverUrl: 'https://compute.rhino3d.com', apiKey: 'YOUR_KEY' }
+ * );
+ *
+ * // Inputs are now strongly typed
+ * inputs.forEach(input => {
+ *   if (input.paramType === 'Number') {
+ *     console.log(input.minimum, input.maximum); // TypeScript knows these exist
+ *   }
+ * });
+ * ```
+ */
+declare function fetchParsedDefinitionIO(definition: string | Uint8Array, config: ComputeConfig): Promise<GrasshopperParsedIO>;
+
+/**
+ * Processes a raw input parameter schema and converts it into a typed InputParam object.
+ *
+ * @internal This is an internal processor. Use `fetchParsedDefinitionIO()` to get processed inputs instead.
+ *
+ * This function handles the transformation of raw input parameter data from Grasshopper into
+ * a structured, type-safe format. It performs validation, type-specific processing, and error
+ * handling for various parameter types including numeric, boolean, text, geometry, point, and line inputs.
+ *
+ * @param rawInput - The raw input parameter schema to process
+ * @returns A fully processed and typed InputParam object with appropriate type-specific properties
+ *
+ * @throws {RhinoComputeError} When an unknown paramType is encountered
+ * @throws {Error} Re-throws any non-RhinoComputeError exceptions
+ *
+ * @remarks
+ * The function performs the following operations:
+ * - Extracts base properties common to all input types
+ * - Preprocesses the raw input data
+ * - Applies type-specific validation and transformation
+ * - Handles errors gracefully by creating safe default values for validation errors
+ *
+ * Supported parameter types:
+ * - `Number` and `Integer`: Numeric inputs with optional min/max constraints
+ * - `Boolean`: Boolean flag inputs
+ * - `Text`: String inputs
+ * - `Geometry`: Generic geometry objects
+ * - `Point`: 3D point objects
+ * - `Line`: Line objects
+ *
+ * @example
+ * ```typescript
+ * const rawInput = {
+ *   name: 'Length',
+ *   paramType: 'Number',
+ *   minimum: 0,
+ *   maximum: 100,
+ *   default: 50
+ * };
+ * const processedInput = processInput(rawInput);
+ * ```
+ */
+declare function processInput(rawInput: InputParamSchema): InputParam;
+/**
+ * Processes raw Grasshopper input schemas into strongly-typed TypeScript interfaces.
+ *
+ * @internal This is an internal batch processor. Use `fetchParsedDefinitionIO()` to get processed inputs instead.
+ *
+ * Transforms each raw input parameter by:
+ * - Normalizing default values (flattening data trees, parsing primitives)
+ * - Applying type-specific parsing (Number, Text, Boolean, Geometry, etc.)
+ * - Validating constraints (min/max, required fields)
+ * - Converting to discriminated union types for type safety
+ *
+ * @param rawInputs - Array of raw input schemas from Rhino Compute API
+ * @returns Array of processed, strongly-typed input parameters
+ *
+ * @remarks
+ * - Empty data trees are converted to `undefined`
+ * - Single values are extracted from arrays when appropriate
+ * - Tree structures are preserved for list/tree access parameters
+ * - Invalid inputs fall back to safe defaults with console warnings
+ *
+ * @example
+ * ```typescript
+ * const rawInputs = [
+ *   { paramType: 'Number', name: 'radius', minimum: 0, default: 10 },
+ *   { paramType: 'Text', name: 'label', default: 'Hello' }
+ * ];
+ *
+ * const processed = processInputs(rawInputs);
+ * // Result: [
+ * //   { paramType: 'Number', name: 'radius', minimum: 0, default: 10, ... },
+ * //   { paramType: 'Text', name: 'label', default: 'Hello', ... }
+ * // ]
+ *
+ * // Now type-safe:
+ * if (processed[0].paramType === 'Number') {
+ *   console.log(processed[0].minimum); // TypeScript knows this exists
+ * }
+ * ```
+ *
+ * @see {@link processInput} for individual input processing logic
+ */
+declare function processInputs(rawInputs: InputParamSchema[]): InputParam[];
+
+/**
+ * Value types that can be stored in a DataTree
+ */
+type DataTreeValue = string | number | boolean | object | null;
+/**
+ * Simple data item for compute requests (not to be confused with DataItem interface for responses).
+ * Note: While TypeScript defines this as string, Rhino Compute accepts boolean/number primitives in JSON.
+ */
+interface ComputeDataItem {
+    data: string | boolean | number;
+}
+/**
+ * InnerTree data structure for compute requests.
+ */
+type ComputeInnerTreeData = {
+    [path in DataTreePath]: ComputeDataItem[];
+};
+/**
+ * Standalone TreeBuilder class for constructing Grasshopper TreeBuilder structures.
+ * Does not depend on RhinoCompute library.
+ *
+ * @example
+ * ```ts
+ * const tree = new TreeBuilder('MyParam')
+ *   .append([0], [1, 2, 3])
+ *   .append([1], [4, 5])
+ *   .toComputeFormat();
+ * ```
+ */
+declare class TreeBuilder {
+    private innerTree;
+    private paramName;
+    constructor(paramName: string);
+    /**
+     * Append values to a specific path in the tree.
+     *
+     * @param path - Array of integers representing the branch path (e.g., [0], [0, 1])
+     * @param items - Values to append at this path
+     * @returns this for method chaining
+     */
+    append(path: number[], items: DataTreeValue[]): this;
+    /**
+     * Append a single value to a path.
+     *
+     * @param path - Branch path
+     * @param item - Single value to append
+     * @returns this for method chaining
+     */
+    appendSingle(path: number[], item: DataTreeValue): this;
+    /**
+     * Set values from a DataTreeDefault structure.
+     * Replaces any existing tree data.
+     *
+     * @param treeData - TreeBuilder structure with path keys like "{0;1}"
+     * @returns this for method chaining
+     */
+    fromDataTreeDefault(treeData: DataTreeDefault): this;
+    /**
+     * Append flattened values to path [0].
+     * Useful for simple flat inputs.
+     *
+     * @param values - Single value or array of values
+     * @returns this for method chaining
+     */
+    appendFlat(values: DataTreeValue | DataTreeValue[]): this;
+    /**
+     * Get the flattened list of all values in the tree.
+     *
+     * @returns Array of all values across all branches
+     */
+    flatten(): DataTreeValue[];
+    /**
+     * Get all paths in the tree.
+     *
+     * @returns Array of path strings
+     */
+    getPaths(): DataTreePath[];
+    /**
+     * Get values at a specific path.
+     *
+     * @param path - Path to retrieve values from
+     * @returns Array of values or undefined if path doesn't exist
+     */
+    getPath(path: number[]): DataTreeValue[] | undefined;
+    /**
+     * Convert to format compatible with Grasshopper Compute API.
+     *
+     * @returns InnerTree object ready for compute
+     */
+    toComputeFormat(): DataTree;
+    /**
+     * Get the raw InnerTree data structure.
+     *
+     * @returns InnerTree data
+     */
+    getInnerTree(): ComputeInnerTreeData;
+    /**
+     * Get the parameter name.
+     *
+     * @returns Parameter name
+     */
+    getParamName(): string;
+    /**
+     * Create DataTrees from an array of InputParam definitions.
+     * Handles tree access, numeric constraints, and value parsing.
+     *
+     * @param inputs - Array of input parameter definitions
+     * @returns Array of InnerTree instances ready for compute
+     *
+     * @example
+     * ```ts
+     * const trees = TreeBuilder.fromInputParams(inputs);
+     * ```
+     */
+    static fromInputParams(inputs: InputParam[]): DataTree[];
+    /**
+     * Create a TreeBuilder from a single InputParam.
+     *
+     * @param input - Input parameter definition
+     * @returns InnerTree ready for compute or undefined if value is invalid
+     */
+    static fromInputParam(input: InputParam): DataTree | undefined;
+    /**
+     * Set or replace a parameter value within a TreeBuilder or InnerTree array.
+     *
+     * Supports both high-level `DataTree[]` instances and low-level `InnerTree[]` format.
+     *
+     * **Architecture Note:**
+     * - Use with `DataTree[]` when building/modifying before computation
+     * - Use with `InnerTree[]` when modifying compute API results
+     * - `DataTree` is the high-level builder; `InnerTree` is the Rhino Compute format
+     *
+     * @overload For TreeBuilder instances (high-level builder)
+     * @param trees - Array of TreeBuilder instances to modify
+     * @param paramName - The parameter name to set or replace
+     * @param newValue - The new value (scalar, array, or TreeBuilder structure)
+     * @returns A new/modified TreeBuilder array with the updated parameter
+     *
+     * @overload For compiled InnerTree (low-level API format)
+     * @param trees - The compiled InnerTree array (typically from `client.solve()`)
+     * @param paramName - The parameter name to set or replace
+     * @param newValue - The new value (scalar, array, or TreeBuilder structure)
+     * @returns A new/modified InnerTree array with the updated parameter
+     *
+     * @example
+     * ```ts
+     * // With TreeBuilder instances (high-level)
+     * let trees = [new TreeBuilder('X'), new TreeBuilder('Y')];
+     * trees = TreeBuilder.replaceTreeValue(trees, 'X', 42);
+     * const result = await client.solve(definitionUrl,
+     *   trees.map(t => t.toComputeFormat())
+     * );
+     * ```
+     *
+     * @example
+     * ```ts
+     * // With InnerTree format (low-level, from API)
+     * let trees = await client.solve(definitionUrl, initialInputs);
+     * trees = TreeBuilder.replaceTreeValue(trees, 'X', 42);
+     * trees = TreeBuilder.replaceTreeValue(trees, 'Y', [1, 2, 3]);
+     * ```
+     */
+    static replaceTreeValue(trees: TreeBuilder[], paramName: string, newValue: DataTreeValue): TreeBuilder[];
+    static replaceTreeValue(trees: DataTree[], paramName: string, newValue: DataTreeValue): DataTree[];
+    /**
+     * Extract a value from a TreeBuilder or InnerTree array by parameter name.
+     *
+     * Automatically unwraps single values for convenience.
+     * Works with both high-level `DataTree[]` instances and low-level `InnerTree[]` format.
+     *
+     * **Architecture Note:**
+     * - Use with `DataTree[]` to read builder instances
+     * - Use with `InnerTree[]` to read compute API responses
+     * - Return behavior is consistent across both formats
+     *
+     * **Return Value Behavior:**
+     * - Single value → unwrapped (returns `5` not `[5]`)
+     * - Multiple values → array of values
+     * - Not found → `null`
+     *
+     * @overload For TreeBuilder instances
+     * @param trees - Array of TreeBuilder instances to read from
+     * @param paramName - The parameter name to retrieve
+     * @returns The unwrapped value, array of values, or null if parameter not found
+     *
+     * @overload For compiled InnerTree
+     * @param trees - The compiled InnerTree array (typically from `client.solve()`)
+     * @param paramName - The parameter name to retrieve
+     * @returns The unwrapped value, array of values, or null if parameter not found
+     *
+     * @example
+     * ```ts
+     * // With TreeBuilder instances
+     * const trees = [new TreeBuilder('X'), new TreeBuilder('Y')];
+     * trees[0].appendFlat(42);
+     * const x = TreeBuilder.getTreeValue(trees, 'X'); // Returns 42
+     * ```
+     *
+     * @example
+     * ```ts
+     * // With InnerTree from compute results
+     * const result = await client.solve(definitionUrl, inputs);
+     * const x = TreeBuilder.getTreeValue(result, 'X'); // Returns 42 (not [42])
+     * const points = TreeBuilder.getTreeValue(result, 'Points'); // Returns [point1, point2, ...]
+     * ```
+     */
+    static getTreeValue(trees: TreeBuilder[], paramName: string): DataTreeValue | null;
+    static getTreeValue(trees: DataTree[], paramName: string): DataTreeValue | null;
+    /**
+     * Parse a TreeBuilder path string like "{0;1;2}" into [0, 1, 2].
+     *
+     * @param pathStr - Path string
+     * @returns Array of path indices
+     */
+    static parsePathString(pathStr: string): number[];
+    /**
+     * Format a path array into TreeBuilder path string format.
+     *
+     * @param path - Path as number array
+     * @returns Formatted path string like "{0;1;2}"
+     */
+    static formatPathString(path: number[]): DataTreePath;
+    /**
+     * Apply numeric constraints to all tree values.
+     */
+    private applyNumericConstraints;
+    /**
+     * Serialize a value for compute requests.
+     * Preserves booleans and numbers as primitives for proper Grasshopper parameter handling.
+     */
+    private static serializeValue;
+    /**
+     * Deserialize a value back to its original type.
+     * Handles both string-encoded values and primitive values.
+     */
+    private static deserializeValue;
+    /**
+     * Check if a value is valid for inclusion in a DataTree.
+     */
+    private static hasValidValue;
+    /**
+     * Check if value is a TreeBuilder structure.
+     */
+    private static isDataTreeStructure;
+    /**
+     * Check if input is numeric type.
+     */
+    private static isNumericInput;
+    /**
+     * Process array of values based on input type.
+     */
+    private static processValues;
+    /**
+     * Clamp numeric value to constraints.
+     */
+    private static clampValue;
+}
+
+/**
+ * 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}`);
+ * });
+ */
+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'
+ */
+declare const downloadFileData: (downloadableFiles: FileData[], fileFoldername: string, additionalFiles?: FileBaseInfo[] | FileBaseInfo | null) => Promise<void>;
+
+export { type BooleanInputType, type CacheOptions, ComputeConfig, DataTree, DataTreeDefault, DataTreePath, type DataTreeValue, type DefaultValue, type FileBaseInfo, type FileData, type FileInputType, type GeometryInputType, type GetValuesOptions, type GetValuesResult, GrasshopperClient, GrasshopperComputeConfig, GrasshopperComputeResponse, type GrasshopperParsedIO, type GrasshopperParsedIORaw, GrasshopperResponseProcessor, type InputParam, InputParamSchema, type NumericInputType, OutputParamSchema, type OutputType, type ParsedContext, type ProcessedFile, RetryPolicy, RhinoComputeError, type SchedulerMode, type SolveContext, type SolveExecutor, type SolveOptions, type SolveResult, SolveScheduler, type SolveSchedulerOptions, type TextInputType, TreeBuilder, type ValueListInputType, downloadFileData, extractFilesFromComputeResponse, fetchDefinitionIO, fetchParsedDefinitionIO, hashSolveInput, processInput, processInputs, solveGrasshopperDefinition };