@selvajs/compute 3.1.1 → 4.0.0-beta.1

package/dist/grasshopper.d.cts

@@ -1,11 +1,335 @@
-import { R as RhinoComputeError, C as ComputeServerStats, F as FileBaseInfo } from './handle-files-BISo_wob.cjs';
-export { b as FileData, P as ProcessedFile, d as downloadFileData, e as extractFilesFromComputeResponse } from './handle-files-BISo_wob.cjs';
-import { R as RetryPolicy, C as ComputeConfig } from './types-BGhtYxZ-.cjs';
-export { a as RhinoModelUnit } from './types-BGhtYxZ-.cjs';
-import { f as GrasshopperComputeResponse, a as DataTree, e as GrasshopperComputeConfig, g as GrasshopperParsedIO, h as GrasshopperParsedIORaw, m as MeshExtractionOptions, k as InputParamSchema, j as InputParam, b as DataTreeDefault, c as DataTreePath } from './types-BpOl6U02.cjs';
-export { B as BooleanInputType, D as DataItem, d as DefaultValue, F as FileInputType, G as GeometryInputType, i as GrasshopperRequestSchema, I as InnerTreeData, N as NumericInputType, O as OutputParamSchema, l as OutputType, T as TextInputType, V as ValueListInputType } from './types-BpOl6U02.cjs';
-import * as THREE from 'three';
-import 'rhino3dm';
+import { C as ComputeConfig, e as RhinoModelUnit, R as RetryPolicy, d as RhinoComputeError, a as ComputeServerStats, F as FileBaseInfo } from './handle-files-DcA24IkS.cjs';
+export { c as FileData, P as ProcessedFile, f as downloadFileData, g as extractFilesFromComputeResponse } from './handle-files-DcA24IkS.cjs';
+
+type DataTreePath = `{${string}}`;
+interface DataItem {
+    type: string;
+    data: string;
+    id: string;
+}
+type DataTreeDefault<T = any> = {
+    [K in DataTreePath]?: T[];
+};
+type InnerTreeData = {
+    [path in DataTreePath]: DataItem[];
+};
+/**
+ * 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;
+}
+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;
+
+/**
+ * Base Grasshopper schema properties shared by config, args, and response
+ */
+interface GrasshopperBaseSchema {
+    /** Absolute tolerance used in computation */
+    absolutetolerance?: number | null;
+    /** Angular tolerance used in computation */
+    angletolerance?: number | null;
+    /** Model units used */
+    modelunits?: RhinoModelUnit | null;
+    /** Data version (7 or 8) */
+    dataversion?: 7 | 8 | null;
+    /** Whether to use cached solution */
+    cachesolve?: boolean | null;
+    /**
+     * Opt-in: cache a solve even when the definition reported GH errors. Default
+     * (false/unset) means errored solves are never cached server-side. Some
+     * definitions throw GH errors by design (a guarded Python component, a
+     * filtered branch) while still producing correct geometry — set this so those
+     * still benefit from the server's solve cache. Only meaningful with
+     * `cachesolve`. Requires a server that honors it (VektorNode fork).
+     */
+    cacheerroredsolves?: boolean | null;
+}
+/**
+ * Definition source (used in args and response)
+ */
+interface GrasshopperDefinitionSource {
+    /** Base64 encoded algorithm (if embedded) */
+    algo?: string | null;
+    /** URL pointer to definition file */
+    pointer?: string | null;
+    /** Filename of the definition */
+    filename?: string | null;
+}
+/**
+ * Configuration for Grasshopper compute operations
+ * Combines server config with optional Grasshopper-specific computation settings
+ *
+ * Note: The definition source (pointer/algo) is NOT part of config.
+ * Instead, pass the definition directly to methods like solve(), getIO(), etc.
+ */
+interface GrasshopperComputeConfig extends ComputeConfig {
+    /** Absolute tolerance used in computation */
+    absolutetolerance?: number | null;
+    /** Angular tolerance used in computation */
+    angletolerance?: number | null;
+    /** Model units used */
+    modelunits?: RhinoModelUnit | null;
+    /** Data version (7 or 8) */
+    dataversion?: 7 | 8 | null;
+    /** Whether to use cached solution */
+    cachesolve?: boolean | null;
+    /**
+     * Opt-in: cache a solve even when the definition reported GH errors. See
+     * {@link GrasshopperBaseSchema.cacheerroredsolves}. Only meaningful with
+     * `cachesolve`.
+     */
+    cacheerroredsolves?: boolean | null;
+}
+/**
+ * Arguments sent to Grasshopper compute endpoint
+ * Includes config options + definition source + input values
+ */
+interface GrasshopperRequestSchema extends GrasshopperBaseSchema, GrasshopperDefinitionSource {
+    /** Input values organized by parameter */
+    values?: DataTree[];
+}
+/**
+ * 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, 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
+     * it before returning — retaining it would pin a multi-MB copy of the definition per response,
+     * multiplied by every cache that holds responses. Always `undefined` on client-returned
+     * responses (inherited optional field from {@link GrasshopperDefinitionSource}).
+     */
+    algo?: string | null;
+    /** Filename of the definition (always present in response) */
+    filename: string | null;
+    /** Recursion level used */
+    recursionlevel?: number;
+    /** Output values organized by parameter */
+    values: DataTree[];
+    /** Computation errors */
+    errors?: string[];
+    /** Computation warnings */
+    warnings?: string[];
+}
+/**
+ * Output parameter
+ */
+interface OutputParamSchema {
+    name: string;
+    nickname: string | null;
+    paramType: string;
+    /**
+     * Grasshopper parameter instance GUID
+     */
+    id: string;
+}
+/**
+ * Input parameter
+ */
+interface InputParamSchema {
+    /**
+     * Grasshopper parameter instance GUID
+     */
+    id: string;
+    name: string;
+    nickname: string | null;
+    description: string;
+    paramType: string;
+    treeAccess: boolean;
+    minimum: number | null;
+    maximum: number | null;
+    atLeast: number;
+    atMost: number;
+    stepSize?: number;
+    default: any;
+    /**
+     * Key-value pairs for dropdown options
+     */
+    values?: Record<string, string>;
+    /**
+     * Accepted file formats for File input
+     */
+    acceptedFormats?: string[];
+    groupName?: string | null;
+}
+
+/**
+ * Parsed input/output structure with raw schemas.
+ *
+ * `loadWarnings` / `loadErrors` carry the server's definition-load diagnostics
+ * (missing plugin, broken component, etc.) from the `/io` response. They are
+ * distinct from per-input parse failures (`InputParseError`): these come from
+ * the server loading the definition, those from the client typing an input.
+ */
+interface GrasshopperParsedIORaw {
+    inputs: InputParamSchema[];
+    outputs: OutputParamSchema[];
+    /** Server-side definition-load warnings, if any. */
+    loadWarnings?: string[];
+    /** Server-side definition-load errors, if any (e.g. missing plugin). */
+    loadErrors?: string[];
+}
+/**
+ * Per-input parse failure. The corresponding entry in `inputs` was filled
+ * with a safe default so the rest of the pipeline can keep going — but the
+ * caller should surface this so the user knows their definition has a
+ * misconfigured parameter.
+ */
+interface InputParseError {
+    /** The input's `name` (or `'unknown'` if the schema didn't have one). */
+    inputName: string;
+    /** The declared paramType from the raw schema. */
+    paramType: string;
+    /** Human-readable reason from the underlying RhinoComputeError. */
+    message: string;
+    /** Error code from the underlying RhinoComputeError, if available. */
+    code?: string;
+}
+/**
+ * Parsed input/output structure with processed types.
+ *
+ * `parseErrors` is populated when one or more inputs failed validation and
+ * fell back to a safe default. The result is still usable, but the UI should
+ * surface these so the user can fix their definition.
+ */
+interface GrasshopperParsedIO {
+    inputs: InputParam[];
+    outputs: OutputParamSchema[];
+    parseErrors?: InputParseError[];
+    /**
+     * Server-side definition-load warnings from the `/io` response (e.g. an
+     * obsolete component). Surface these so the user understands a degraded IO
+     * list. Distinct from `parseErrors` (client-side input typing failures).
+     */
+    loadWarnings?: string[];
+    /**
+     * Server-side definition-load errors from the `/io` response (e.g. a missing
+     * plugin that left inputs unresolved). When present, the inputs/outputs may
+     * be incomplete — the user needs to fix their server/definition.
+     */
+    loadErrors?: string[];
+}
 
 /**
  * By-reference definition form for solves.
@@ -63,19 +387,29 @@ declare function isDefinitionRef(definition: SolveDefinition): definition is Def
  */
 type SchedulerMode = 'latest-wins' | 'queue' | 'parallel';
 interface CacheOptions {
-    /** Maximum entries kept in the LRU. Default: 50. */
-    maxEntries?: number;
-    /**
-     * Total byte budget for retained responses, evicted LRU alongside
-     * `maxEntries` (both bounds apply). Responses range KB→100s of MB, so an
-     * entry count alone can't bound heap. Sizing uses the response's wire size
-     * (JSON text length, recorded at the fetch boundary — no re-serialization);
-     * a response without that hint (custom executor) is sized by a one-off
-     * `JSON.stringify`. A single response larger than the whole budget is
-     * served but never retained. `0` = no byte bound (count-only, default).
-     */
-    maxBytes?: number;
-    /** Time-to-live in ms. Set to `0` for no expiry (default). */
+    /**
+     * Total byte budget for retained responses, evicted LRU. The only size bound
+     * there is: responses range KB→100s of MB, so memory is the constraint that
+     * matters and an entry count would only obscure it.
+     *
+     * Sizing uses the response's wire size (JSON text length, recorded at the
+     * fetch boundary — no re-serialization); a response without that hint
+     * (custom executor) is sized by a one-off `JSON.stringify`. A single
+     * response larger than the whole budget is served but never retained.
+     *
+     * Required and must be > 0 — to disable caching, pass `cache: false`.
+     */
+    maxBytes: number;
+    /**
+     * Time-to-live in ms. Set to `0` for no expiry (default, and the right
+     * choice for a solve keyed by immutable definition+inputs — expiry there
+     * only buys a paid re-solve of an identical answer). Meaningful only when a
+     * definition reaches outside its inputs (external data source, clock), where
+     * a stale result is genuinely wrong rather than merely old.
+     *
+     * Expiry is evaluated lazily on read: an expired entry keeps its bytes
+     * counted against `maxBytes` until that exact key is next consulted.
+     */
     ttlMs?: number;
     /**
      * Cache responses that carry Grasshopper `errors`. Default `true`: an
@@ -109,8 +443,12 @@ interface SolveSchedulerOptions {
     queueWaitMs?: number;
     timeoutMs?: number;
     retry?: RetryPolicy;
-    /** Enable response caching keyed by hash of (definition, dataTree). */
-    cache?: boolean | CacheOptions;
+    /**
+     * Response caching keyed by hash of (definition, dataTree). Omit or pass
+     * `false` to disable; otherwise a byte budget is required, so an unbounded
+     * cache can't be enabled by accident.
+     */
+    cache?: false | CacheOptions;
     /**
      * Reuse the server's definition cache key so a large (base64/binary)
      * definition is uploaded once and subsequent solves reference it by
@@ -157,10 +495,6 @@ type SolveResult = {
 } | {
     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: SolveDefinition, dataTree: DataTree[], config: GrasshopperComputeConfig) => Promise<GrasshopperComputeResponse>;
 /**
  * Cache-key-aware executor. When `cacheKey` is provided, the executor solves by
@@ -178,6 +512,7 @@ type CacheKeyExecutor = (definition: SolveDefinition, dataTree: DataTree[], cach
     cacheKey: string | null;
     missed: boolean;
 }>;
+
 /**
  * Robust scheduler for Grasshopper solves.
  *
@@ -220,13 +555,21 @@ declare class SolveScheduler {
     private readonly timeoutMs;
     private readonly retry;
     private readonly cacheEnabled;
-    private readonly cacheMax;
     private readonly cacheMaxBytes;
     private readonly cacheTtl;
     private readonly cacheErroredSolves;
     private readonly cache;
     /** Sum of `sizeBytes` across retained cache entries. */
     private cacheBytes;
+    /**
+     * Cumulative hit/miss/eviction counters for {@link cacheStats}. Deliberately
+     * NOT reset by `clearCache()` — they measure this scheduler's whole lifetime,
+     * so a hit rate stays comparable across a session rather than restarting at
+     * every clear.
+     */
+    private cacheHits;
+    private cacheMisses;
+    private cacheEvictions;
     /** Optional cache-key-aware executor and whether server-def-cache reuse is on. */
     private readonly cacheKeyExecutor?;
     private readonly reuseServerDefinitionCache;
@@ -357,10 +700,22 @@ declare class SolveScheduler {
     /** Remove one cache entry and release its bytes from the running total. */
     private dropCacheEntry;
     clearCache(): void;
-    /** Observability snapshot of the response cache (entries + retained bytes). */
+    /**
+     * Observability snapshot of the solve cache: current size plus lifetime
+     * hit/miss/eviction counters.
+     *
+     * `hits`/`misses` count cache CONSULTATIONS, so `hits / (hits + misses)` is the
+     * hit rate. A TTL-expired entry counts as a miss (the solve runs either way).
+     * `evictions` counts only entries dropped under size/byte pressure — not
+     * replace-in-place writes or TTL expiry, which are not capacity signals.
+     * Counters are cumulative and survive `clearCache()`.
+     */
     cacheStats(): {
         entries: number;
         bytes: number;
+        hits: number;
+        misses: number;
+        evictions: number;
     };
     dispose(): void;
     private runHook;
@@ -509,9 +864,31 @@ interface GetValuesResult<T = ParsedContext> {
  * when working with Grasshopper results in client applications.
  */
 declare class GrasshopperResponseProcessor {
-    private readonly response;
-    private readonly debug;
-    constructor(response: GrasshopperComputeResponse, debug?: boolean);
+    /**
+     * The raw compute response. Public so callers can hand it to a renderer-side parser — e.g.
+     * `getThreeMeshesFromComputeResponse` in `@selvajs/visualization/parse`, which replaced this
+     * class's former `extractMeshesFromResponse()`.
+     */
+    readonly response: GrasshopperComputeResponse;
+    /**
+     * Retained for call-signature compatibility. Its only consumer was the removed
+     * `extractMeshesFromResponse()`, which merged it into the parse options; pass `debug`
+     * directly to the parser in `@selvajs/visualization/parse` instead.
+     */
+    readonly debug: boolean;
+    constructor(
+    /**
+     * The raw compute response. Public so callers can hand it to a renderer-side parser — e.g.
+     * `getThreeMeshesFromComputeResponse` in `@selvajs/visualization/parse`, which replaced this
+     * class's former `extractMeshesFromResponse()`.
+     */
+    response: GrasshopperComputeResponse, 
+    /**
+     * Retained for call-signature compatibility. Its only consumer was the removed
+     * `extractMeshesFromResponse()`, which merged it into the parse options; pass `debug`
+     * directly to the parser in `@selvajs/visualization/parse` instead.
+     */
+    debug?: boolean);
     /**
      * Extract all values in the response.
      *
@@ -549,22 +926,17 @@ declare class GrasshopperResponseProcessor {
         byId: string;
     }, options?: GetValuesOptions): any;
     /**
-     * Decode all geometry results into Three.js meshes/lines ready for rendering.
-     * The processor's `debug` flag is merged with `options` (explicit options win).
-     *
-     * Requires the **Selva Display** Grasshopper component and the VektorNode
-     * rhino.compute branch. Three.js is loaded dynamically, so install it as a
-     * peer dependency before calling this.
-     *
-     * @throws {RhinoComputeError} If the three.js visualization module can't load.
+     * REMOVED: `extractMeshesFromResponse()`. Mesh decoding lives in `@selvajs/visualization` now, so
+     * this package stays pure solve/data and carries no `three` dependency. Call the parser directly
+     * with the raw response:
      *
-     * @example
      * ```ts
-     * const meshes = await processor.extractMeshesFromResponse();
+     * import { getThreeMeshesFromComputeResponse } from '@selvajs/visualization/parse';
+     *
+     * const meshes = await getThreeMeshesFromComputeResponse(processor.response, { rhino });
      * scene.add(...meshes);
      * ```
      */
-    extractMeshesFromResponse(options?: MeshExtractionOptions): Promise<THREE.Object3D<THREE.Object3DEventMap>[]>;
     private getFileData;
     /**
      * Download all files generated by Grasshopper, optionally including
@@ -722,12 +1094,6 @@ declare function fetchParsedDefinitionIO(definition: string | Uint8Array, config
  * {@link processInputWithError} to receive them.
  */
 declare function processInput(rawInput: InputParamSchema): InputParam;
-/**
- * Parse an array of raw input schemas into typed {@link InputParam}s, each via
- * {@link processInput}. Use {@link processInputsWithErrors} to also collect the
- * inputs that failed validation.
- */
-declare function processInputs(rawInputs: InputParamSchema[]): InputParam[];
 
 /**
  * Value types that can be stored in a DataTree
@@ -1003,4 +1369,4 @@ declare class TreeBuilder {
     private static clampValue;
 }
 
-export { type CacheOptions, ComputeConfig, DataTree, DataTreeDefault, DataTreePath, type DataTreeValue, type DefinitionRef, FileBaseInfo, type GetValuesOptions, type GetValuesResult, GrasshopperClient, GrasshopperComputeConfig, GrasshopperComputeResponse, GrasshopperParsedIO, GrasshopperParsedIORaw, GrasshopperResponseProcessor, InputParam, InputParamSchema, type ParsedContext, RetryPolicy, RhinoComputeError, type SchedulerMode, type SolveContext, type SolveDefinition, type SolveOptions, type SolveResult, SolveScheduler, type SolveSchedulerOptions, TreeBuilder, fetchDefinitionIO, fetchParsedDefinitionIO, hashDefinition, hashSolveInput, isDefinitionRef, processInput, processInputs, solveGrasshopperDefinition, stableStringify };
+export { type BooleanInputType, type CacheOptions, type DataItem, type DataTree, type DataTreeDefault, type DataTreePath, type DataTreeValue, type DefaultValue, type DefinitionRef, FileBaseInfo, type FileInputType, type GeometryInputType, type GetValuesOptions, type GetValuesResult, GrasshopperClient, type GrasshopperComputeConfig, type GrasshopperComputeResponse, type GrasshopperParsedIO, type GrasshopperParsedIORaw, type GrasshopperRequestSchema, GrasshopperResponseProcessor, type InnerTreeData, type InputParam, type InputParamSchema, type NumericInputType, type OutputParamSchema, type OutputType, type ParsedContext, type SchedulerMode, type SolveContext, type SolveDefinition, type SolveOptions, type SolveResult, SolveScheduler, type SolveSchedulerOptions, type TextInputType, TreeBuilder, type ValueListInputType, fetchDefinitionIO, fetchParsedDefinitionIO, hashDefinition, hashSolveInput, isDefinitionRef, processInput, solveGrasshopperDefinition, stableStringify };