selva-compute 1.0.0

package/dist/grasshopper.d.cts

@@ -0,0 +1,741 @@
+import { C as ComputeServerStats } from './base-DbB0Ggdq.cjs';
+export { R as RhinoComputeError } from './base-DbB0Ggdq.cjs';
+import { d as DataTreeDefault, O as OutputParamSchema, I as InputParamSchema, c as GrasshopperComputeConfig, a as DataTree, b as GrasshopperComputeResponse, C as ComputeConfig, e as DataTreePath } from './schemas-5LuPKgX2.cjs';
+export { D as DataItem, G as GrasshopperRequestSchema, R as RhinoModelUnit } from './schemas-5LuPKgX2.cjs';
+import * as THREE from 'three';
+import { a as FileBaseInfo } from './types-SwbLAMW8.cjs';
+import { M as MeshExtractionOptions } from './types-r00wVwfo.cjs';
+
+/**
+ * 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>;
+}
+/**
+ * Discriminated union of all input parameter types
+ */
+type InputParam = NumericInputType | BooleanInputType | TextInputType | ValueListInputType | GeometryInputType | FileInputType;
+
+/**
+ * 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[];
+}
+
+/**
+ * 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[]): Promise<GrasshopperComputeResponse>;
+    /**
+     * 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;
+}
+
+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.
+     *
+     * @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 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.
+     *
+     * @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.)
+ * @param options - Optional compute options (timeout, cachesolve, model units, tolerances, 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
+ * @see {@link preProcessRawInput} for default value normalization
+ */
+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;
+}
+
+export { type BooleanInputType, ComputeConfig, DataTree, DataTreeDefault, type DataTreeValue, type GeometryInputType, GrasshopperClient, GrasshopperComputeConfig, GrasshopperComputeResponse, type GrasshopperParsedIO, GrasshopperResponseProcessor, type InputParam, InputParamSchema, type NumericInputType, OutputParamSchema, type OutputType, type TextInputType, TreeBuilder, type ValueListInputType, fetchDefinitionIO, fetchParsedDefinitionIO, processInput, processInputs, solveGrasshopperDefinition };