@selvajs/compute 4.3.0-beta.1 → 5.0.0-beta.2

package/dist/grasshopper.d.ts

@@ -1,5 +1,15 @@
-import { A as RetryPolicy, N as ComputeError, O as ComputeAuth, _ as isDefinitionRef, a as extractFilesFromComputeResponse, c as ProcessedFile, g as SolveDefinition, h as DefinitionRef, k as ComputeConfig, o as FileBaseInfo, r as downloadFileData, s as FileData } from "./index-BR_XZvjj.js";
+import { A as ServerTiming, D as ComputeConfig, E as ComputeAuth, O as RetryPolicy, g as SolveDefinition, j as ComputeError, o as FileBaseInfo } from "./index-C5T6o4Fr.js";
 //#region src/grasshopper/server/compute-server-stats.d.ts
+interface ServerVersion {
+  rhino: string;
+  compute: string;
+  git_sha: string | null;
+}
+interface ServerStats {
+  isOnline: boolean;
+  version?: ServerVersion;
+  activeChildren?: number;
+}
 /**
  * ComputeServerStats provides methods to query Rhino Compute server statistics.
  *
@@ -26,7 +36,6 @@ declare class ComputeServerStats {
   private readonly headers;
   private disposed;
   private activeMonitors;
-  private activeTimeouts;
   /** Timeout (ms) for the fast read/monitoring endpoints. */
   private static readonly DEFAULT_TIMEOUT_MS;
   /** Timeout (ms) for child-lifecycle POSTs — a cold Windows child can take ~30s to spawn. */
@@ -39,11 +48,13 @@ declare class ComputeServerStats {
    *   (`apiKey`, `apiKeyHeader`, `authToken`, `headers`).
    */
   constructor(serverUrl: string, auth?: string | ComputeAuth);
+  /** Aborts after `timeoutMs` so a hung connection can't stall a probe or `monitor()`; `0` disables it. */
+  private fetchWithTimeout;
   /**
-   * `fetch` wrapper that aborts after `timeoutMs` so a hung connection can't stall
-   * a probe (or the `monitor()` loop) forever. Pass `0` to disable the timeout.
+   * The response body of `path`, or `null` (logged) on a non-2xx or a network
+   * failure. Throws only when disposed.
    */
-  private fetchWithTimeout;
+  private getText;
   /**
    * Check if the server is online.
    *
@@ -97,11 +108,7 @@ declare class ComputeServerStats {
    *
    * @returns Version object with rhino, compute, and git_sha, or null if unavailable
    */
-  getVersion(): Promise<{
-    rhino: string;
-    compute: string;
-    git_sha: string | null;
-  } | null>;
+  getVersion(): Promise<ServerVersion | null>;
   /**
    * Get the plugins installed on the server.
    *
@@ -128,15 +135,7 @@ declare class ComputeServerStats {
    *
    * @returns Object containing server status and available stats
    */
-  getServerStats(): Promise<{
-    isOnline: boolean;
-    version?: {
-      rhino: string;
-      compute: string;
-      git_sha: string | null;
-    };
-    activeChildren?: number;
-  }>;
+  getServerStats(): Promise<ServerStats>;
   /**
    * Purge the server's solve-results / URL-data cache.
    *
@@ -281,12 +280,7 @@ declare class ComputeServerStats {
     spawned: number[];
     active: number;
   } | null>;
-  /**
-   * POST a control endpoint that replies with a JSON object and return it,
-   * degrading to `null` on any non-2xx, non-JSON, or network failure. Shared by
-   * the child-lifecycle methods so their failure semantics stay identical. Uses
-   * the longer lifecycle timeout since a spawn/recycle can take ~30s.
-   */
+  /** A child-lifecycle POST: a spawn or recycle can take ~30 s. */
   private postJson;
   /**
    * Continuously monitor server stats at specified interval.
@@ -307,15 +301,12 @@ declare class ComputeServerStats {
    * stopMonitoring();
    * ```
    */
-  monitor(callback: (stats: Awaited<ReturnType<typeof this.getServerStats>>) => void, intervalMs?: number): () => void;
+  monitor(callback: (stats: ServerStats) => void, intervalMs?: number): () => void;
   /**
    * Disposes of all resources and stops all active monitors.
    * Call this when you're done using the stats instance.
    */
   dispose(): Promise<void>;
-  /**
-   * Ensures the instance hasn't been disposed.
-   */
   private ensureNotDisposed;
 }
 //#endregion
@@ -331,17 +322,9 @@ 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.
+ * This client sends PascalCase (`TreeBuilder.toComputeFormat()`), so those
+ * fields are required; a response's casing varies by server branch, so read
+ * one with `readField` rather than by property.
  */
 interface DataTree {
   /** PascalCase — stock mcneel servers, and the request shape this client sends. */
@@ -353,7 +336,6 @@ interface DataTree {
   /** 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
  */
@@ -428,7 +410,7 @@ interface FileInputType extends BaseInputType {
   default: DefaultValue<object | string>;
 }
 /**
- * Color input type (stored as hex string)
+ * Color input type. Values are `"R, G, B"` strings (`"255, 0, 0"`), not hex.
  */
 interface ColorInputType extends BaseInputType {
   paramType: 'Color';
@@ -487,55 +469,19 @@ interface GrasshopperDefinitionSource {
   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;
-  /** Per-solve live-event callback; see {@link SelvaEventTarget}. */
-  selvaevents?: SelvaEventTarget | null;
-}
-/**
- * Arguments sent to Grasshopper compute endpoint
- * Includes config options + definition source + input values
+ * Server config plus the Grasshopper solve settings. The definition is not part
+ * of it: pass that to `solve()` and friends.
  */
-interface GrasshopperRequestSchema extends GrasshopperBaseSchema, GrasshopperDefinitionSource {
-  /** Input values organized by parameter */
-  values?: DataTree[];
+interface GrasshopperComputeConfig extends ComputeConfig, GrasshopperBaseSchema {
   /** Per-solve live-event callback; see {@link SelvaEventTarget}. */
   selvaevents?: SelvaEventTarget | null;
 }
 /**
- * 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.
+ * Response from Grasshopper compute server.
  *
- * 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.
+ * No `pointer`: the solve returns the server's echoed pointer as its `cacheKey`
+ * instead. The echoed settings (`cachesolve`, `dataversion`) stay optional:
+ * nothing client-side enforces them.
  */
 interface GrasshopperComputeResponse extends GrasshopperBaseSchema, Omit<GrasshopperDefinitionSource, 'pointer'> {
   /**
@@ -545,12 +491,7 @@ interface GrasshopperComputeResponse extends GrasshopperBaseSchema, Omit<Grassho
    * 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}).
-   */
+  /** Always `undefined` on a client-returned response: the solve strips it. */
   algo?: string | null;
   /** Filename of the definition (always present in response) */
   filename: string | null;
@@ -617,20 +558,19 @@ interface InputParamSchema {
 }
 //#endregion
 //#region src/grasshopper/types/outputs.d.ts
-/**
- * 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.
- */
+/** Input/output schemas as the `/io` endpoint reports them, keys canonicalized. */
 interface GrasshopperParsedIORaw {
   inputs: InputParamSchema[];
   outputs: OutputParamSchema[];
-  /** Server-side definition-load warnings, if any. */
+  /**
+   * Warnings the server raised loading the definition (e.g. an obsolete
+   * component). Distinct from `parseErrors`, the client failing to type an input.
+   */
   loadWarnings?: string[];
-  /** Server-side definition-load errors, if any (e.g. missing plugin). */
+  /**
+   * Errors the server raised loading the definition (e.g. a missing plugin).
+   * When present, `inputs`/`outputs` may be incomplete.
+   */
   loadErrors?: string[];
 }
 /**
@@ -649,43 +589,26 @@ interface InputParseError {
   /** Error code from the underlying ComputeError, 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 {
+/** {@link GrasshopperParsedIORaw} with each input parsed into its typed {@link InputParam}. */
+interface GrasshopperParsedIO extends Omit<GrasshopperParsedIORaw, 'inputs'> {
   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).
+   * Inputs that failed validation and got a safe default. The result is still
+   * usable, but surface these so the user can fix their definition.
    */
-  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[];
+  parseErrors?: InputParseError[];
 }
 //#endregion
 //#region src/grasshopper/scheduler/types.d.ts
 /**
- * Scheduling mode — controls how concurrent `solve()` calls interact.
+ * 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.
+ * - `latest-wins`: one in flight at a time. A new call supersedes the pending
+ *   one and aborts the one in flight. For slider scrubs and live UIs.
+ * - `queue`: FIFO, every call runs to completion, up to `maxConcurrent` at
+ *   once (default 1). For "submit job" flows where every request matters.
  */
-type SchedulerMode = 'latest-wins' | 'queue' | 'parallel';
+type SchedulerMode = 'latest-wins' | 'queue';
 interface CacheOptions {
   /**
    * Total byte budget for retained responses, evicted LRU. The only size bound
@@ -729,7 +652,7 @@ interface SolveSchedulerOptions {
    * excluding the ones already in flight). When the queue is full, a new
    * `solve()` is rejected immediately with `code: QUEUE_FULL` (retryable, meant to
    * map to HTTP 503 + Retry-After) instead of piling up unbounded. Bounds the
-   * miss path under load. Only applies to `queue` / `parallel` modes —
+   * miss path under load. Only applies to `queue` mode —
    * `latest-wins` has an intrinsic depth of 1. Default: unbounded.
    */
   maxQueueDepth?: number;
@@ -737,8 +660,7 @@ interface SolveSchedulerOptions {
    * Backpressure — max time (ms) a call may sit queued before it starts
    * executing. If it's still waiting after this long it's rejected with
    * `code: QUEUE_TIMEOUT` rather than burning compute on a stale request.
-   * Bounds tail latency. Only applies to `queue` / `parallel` modes. Default:
-   * no deadline.
+   * Bounds tail latency. Only applies to `queue` mode. Default: no deadline.
    */
   queueWaitMs?: number;
   timeoutMs?: number;
@@ -750,15 +672,11 @@ interface SolveSchedulerOptions {
    */
   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
-   * `pointer` instead of re-sending the full payload. Hugely cheaper for
-   * multi-MB definitions on a live UI (slider scrubs, etc.).
-   *
-   * Requires a `cacheKeyExecutor` to be supplied (the client wires one). Has no
-   * effect for URL-pointer definitions (already a reference). On a server-side
-   * cache miss the executor transparently falls back to a full upload, so this
-   * is safe to leave on. Default: `true` when a `cacheKeyExecutor` is present.
+   * Upload a definition once, then solve it by the server's cache key (`pointer`)
+   * instead of re-sending the bytes; a `DefinitionRef` also skips its `load()`.
+   * When the server has evicted the key, the solve falls back to a full upload,
+   * so this is safe to leave on. No effect for URL definitions, which are
+   * already a reference. Default `true`.
    */
   reuseServerDefinitionCache?: boolean;
   /** Lifecycle hooks — fired in order. Errors thrown by hooks are logged, not rethrown. */
@@ -780,12 +698,10 @@ type SolveResult = {
   durationMs: number;
   fromCache: boolean;
   /**
-   * Definition-cache telemetry for a real compute call (not a Selva-cache
-   * `fromCache` hit). `false` → the server reused its cached definition via
-   * the pointer (no upload); `true` → the pointer was cold/stale so the full
-   * definition was re-uploaded. `undefined` when the server-definition-cache
-   * fast path didn't run (reuse disabled, or a non-reusable definition such
-   * as a remote URL).
+   * Whether this solve uploaded the full definition: `true` on its first
+   * solve or after the server evicted the cache key, `false` when the server
+   * reused its cached copy via the pointer. `undefined` for a `fromCache`
+   * hit, or when reuse is off or the definition is a URL.
    */
   definitionReuploaded?: boolean;
 } | {
@@ -795,39 +711,45 @@ type SolveResult = {
 } | {
   status: 'superseded';
 };
-type SolveExecutor = (definition: SolveDefinition, dataTree: DataTree[], config: GrasshopperComputeConfig) => Promise<GrasshopperComputeResponse>;
 /**
- * Cache-key-aware executor. When `cacheKey` is provided, the executor solves by
- * reference (`pointer: cacheKey`) and falls back to a full upload on a server
- * cache miss. Always reports the (possibly refreshed) `cacheKey` so the
- * scheduler can update its definition→key map, plus whether the fast path
- * `missed` (for telemetry). When `cacheKey` is null it's a first solve — upload
- * fully and capture the key the server assigns.
- *
- * Supplied by the client (which owns the solve primitives); the scheduler stays
- * decoupled from the transport.
+ * Solves by `cacheKey` when given one, otherwise uploads. Reports the server's
+ * (possibly new) key and whether the full definition was uploaded (`missed`).
+ * The scheduler passes `null` whenever server-definition reuse is off.
  */
-type CacheKeyExecutor = (definition: SolveDefinition, dataTree: DataTree[], cacheKey: string | null, config: GrasshopperComputeConfig) => Promise<{
+type SolveExecutor = (definition: SolveDefinition, dataTree: DataTree[], cacheKey: string | null, config: GrasshopperComputeConfig) => Promise<{
   response: GrasshopperComputeResponse;
   cacheKey: string | null;
   missed: boolean;
 }>;
+interface SchedulerSolveOptions {
+  signal?: AbortSignal;
+  /** Per-solve live-event callback. Not part of the cache key: it names where events go, not what is solved. */
+  selvaevents?: SelvaEventTarget;
+  /**
+   * This call's `Server-Timing` breakdown, after the client config's own `onServerTiming`.
+   * Never fires for a `fromCache` hit, which sends no request.
+   */
+  onServerTiming?: (timing: ServerTiming, requestId: string) => void;
+}
+/** What `solveDetailed()` resolves with: the response plus how this call got it. */
+interface SolveDetail {
+  response: GrasshopperComputeResponse;
+  /** Served from the scheduler's response cache without a request. */
+  fromCache: boolean;
+  /** Same meaning as on {@link SolveResult}. */
+  definitionReuploaded?: boolean;
+  /** Executor wall time; `0` for a `fromCache` hit. */
+  durationMs: number;
+}
 //#endregion
 //#region src/grasshopper/scheduler/solve-scheduler.d.ts
 /**
- * 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)
- * - Backpressure (bounded queue depth + queue-wait deadline) for the miss path
- * - In-flight cancellation (per-call signal + cancelAll)
+ * Adds to a plain solve call:
+ * - Scheduling (latest-wins for sliders, queue for jobs)
+ * - Backpressure (bounded queue depth + queue-wait deadline)
+ * - 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).
+ * - Lifecycle hooks (start / settle / superseded) and state via subscribe()
  *
  * @example
  * ```ts
@@ -850,11 +772,6 @@ export declare class SolveScheduler {
   private readonly executor;
   private readonly baseConfig;
   private readonly mode;
-  /**
-   * Mutable via {@link setMaxConcurrent}: the compute server's worker pool can grow
-   * or shrink while this scheduler is alive, and the dispatch loops re-read this on
-   * every pass rather than capturing it.
-   */
   private maxConcurrent;
   private readonly maxQueueDepth;
   private readonly queueWaitMs;
@@ -865,21 +782,12 @@ export declare class SolveScheduler {
   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;
-  /** definition identity → server cache key (`pointer`) learned from past solves. */
+  /** Definition hash → the server's cache key (`pointer`) for it. */
   private readonly serverCacheKeys;
   private readonly onStart?;
   private readonly onSettle?;
@@ -891,12 +799,11 @@ export declare class SolveScheduler {
   private _lastResult;
   private _lastError;
   private _lastDurationMs;
-  /** Ordinal handed to each solve() call. */
   private solveSeq;
-  /** seq of the solve that last wrote _lastResult/_lastError — see writeLastState. */
+  /** seq of the solve that last wrote `_lastResult`/`_lastError`. */
   private lastStateSeq;
   private disposed;
-  constructor(executor: SolveExecutor, baseConfig: GrasshopperComputeConfig, options?: SolveSchedulerOptions, cacheKeyExecutor?: CacheKeyExecutor);
+  constructor(executor: SolveExecutor, baseConfig: GrasshopperComputeConfig, options?: SolveSchedulerOptions);
   get isSolving(): boolean;
   get hasPending(): boolean;
   get inFlightCount(): number;
@@ -925,23 +832,16 @@ export declare class SolveScheduler {
    * - Rejects with `code: ErrorCodes.SUPERSEDED` when the call was canceled because
    *   newer values arrived (latest-wins mode).
    * - Rejects with `code: ErrorCodes.ABORTED` when the call was canceled via
-   *   caller-supplied signal or `cancelAll()`.
+   *   its own `signal` (queued or running) or `cancelAll()`.
    * - Rejects with `code: ErrorCodes.QUEUE_FULL` when `maxQueueDepth` is set and
    *   the queue was already full (backpressure; `statusCode: 503`).
    * - Rejects with `code: ErrorCodes.QUEUE_TIMEOUT` when `queueWaitMs` is set and
    *   the call sat queued longer than that before starting (`statusCode: 503`).
    *
-   * Caller-supplied `signal` cancels just this call (rejects with `ABORTED`) —
-   * including while the call is still queued, before execution starts.
-   *
-   * A {@link DefinitionRef} definition is keyed by its `key` (result cache and
-   * server-pointer map alike) without materializing bytes — `load()` runs only
-   * when an upload is unavoidable. Its immutability contract is trusted here:
-   * a reused key serves the other content's cached solve.
-   *
-   * Responses served from the cache (and via `lastResult`) are shared objects,
-   * not copies — treat them as immutable. Mutating one poisons every later
-   * cache hit for that key.
+   * Don't mutate a `Uint8Array` definition after solving it. Responses served
+   * from the cache (and via `lastResult`) are shared objects, not copies —
+   * treat them as immutable. Mutating one poisons every later cache hit for
+   * that key.
    *
    * Partial-success contract: unlike `GrasshopperClient.solve()`, which throws
    * `COMPUTATION_ERROR` when the response carries solver errors, this RESOLVES
@@ -949,79 +849,44 @@ export declare class SolveScheduler {
    * success must not be treated as a result (see `cacheErroredSolves` for the
    * caching side of the same distinction).
    */
-  solve(definition: SolveDefinition, dataTree: DataTree[], options?: {
-    signal?: AbortSignal;
-    selvaevents?: SelvaEventTarget;
-  }): Promise<GrasshopperComputeResponse>;
-  /**
-   * Record last-result state, but only if no newer solve has written since —
-   * a slow solve settling late must not overwrite the state a newer solve
-   * (or cache hit) already published.
-   */
+  solve(definition: SolveDefinition, dataTree: DataTree[], options?: SchedulerSolveOptions): Promise<GrasshopperComputeResponse>;
+  /** {@link solve}, also resolving with whether this call hit the cache and how long it took. */
+  solveDetailed(definition: SolveDefinition, dataTree: DataTree[], options?: SchedulerSolveOptions): Promise<SolveDetail>;
+  /** A slow solve settling late must not overwrite state a newer solve or cache hit published. */
   private writeLastState;
   /** latest-wins: supersede the pending item and abort everything in flight. */
   private supersedeCurrent;
-  /** Settle a still-queued item as ABORTED and remove it from its queue. */
+  private dequeue;
   private abortQueuedItem;
-  /**
-   * Backpressure: settle an incoming item as QUEUE_FULL without ever enqueuing
-   * it. The structured context lets an HTTP layer map it to 503 + Retry-After.
-   */
+  /** The structured context lets an HTTP layer map QUEUE_FULL to 503 + Retry-After. */
   private shedAsQueueFull;
-  /**
-   * Arm the queue-wait deadline for an item about to be queued. If the item is
-   * still waiting when it fires, it's rejected as QUEUE_TIMEOUT and removed from
-   * the queue. Cleared on execute/settle via {@link clearQueueWaitTimer}.
-   */
   private armQueueWaitTimer;
-  /** Clear a queued item's wait-deadline timer, if one is pending. */
   private clearQueueWaitTimer;
   private enqueue;
   private execute;
-  /**
-   * Run the solve, using the server-definition-cache fast path when it's
-   * enabled and the definition is reusable. Learns/updates the definition's
-   * server cache key from the result so later solves can reference it.
-   *
-   * `definitionHash` is the {@link hashDefinition} result already computed at
-   * `solve()` entry — threaded through rather than recomputed, so each solve
-   * pays exactly one linear pass over the definition (issue 57).
-   */
   private runExecutor;
   private drainNext;
   private supersede;
   private makeAbortError;
   /**
-   * Settle a pending/in-flight item exactly once with an error.
-   *
-   * A solve promise can be settled from four concurrent sources — the executor
-   * resolving, the executor rejecting, `supersede`, and `cancelAll` — and a JS
-   * promise silently ignores a second settle. This guard is the single place the
-   * settle-once invariant lives: it makes the *first* settle win and reports
-   * whether this call was that winner, so callers fire their own hook only when
-   * they actually settled. Any new settle path must go through here (or
-   * {@link settleSuccess}) so the guard can't be forgotten.
-   *
-   * @returns `true` if this call settled the item; `false` if it was already settled.
+   * The executor, `supersede`, `cancelAll`, abort and the queue limits can all race to settle one
+   * item, and a promise ignores a second settle silently. The first settle wins; the return value
+   * says whether this call won, so only the winner fires its hook. Every settle path goes through
+   * here or {@link settleSuccess}.
    */
   private settleError;
   /**
-   * Settle a pending/in-flight item exactly once with a successful response.
-   * The success counterpart to {@link settleError}; see it for the invariant.
-   *
-   * @returns `true` if this call settled the item; `false` if it was already settled.
+   * Fires `onSettle` for queued items too, so a consumer counting solves in progress doesn't
+   * leak one. A supersede settles through {@link settleError} and fires `onSuperseded` instead.
    */
+  private fail;
   private settleSuccess;
-  /** Detach the queued-phase abort listener, if one is still attached. */
   private removeQueuedAbortHandler;
-  private isAbortLikeError;
   private normalizeExecutionError;
   /** Cancel everything — in-flight and pending. */
   cancelAll(): void;
-  private rejectAsAborted;
   private readCache;
   private writeCache;
-  /** Remove one cache entry and release its bytes from the running total. */
   private dropCacheEntry;
   clearCache(): void;
   /**
@@ -1061,6 +926,19 @@ interface SolveOptions {
   /** Per-solve live-event callback, forwarded onto the request body. */
   selvaevents?: SelvaEventTarget;
 }
+/** Options for {@link GrasshopperClient.create} that shape construction, not the solves. */
+interface CreateClientOptions {
+  /**
+   * Retry ladder for the liveness probe: `attempts` retries after the first probe (default 2),
+   * with exponential backoff from `baseDelayMs` (default 250) capped at `maxDelayMs` (default 1000).
+   * Independent of `config.retry`, which governs solves only.
+   */
+  probe?: {
+    attempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+  };
+}
 /**
  * GrasshopperClient provides a simple API for interacting with a Rhino Compute server and grasshopper.
  *
@@ -1078,7 +956,8 @@ interface SolveOptions {
  * });
  *
  * try {
- *   const result = await client.solve(definitionUrl, { x: 1, y: 2 });
+ *   const io = await client.getIO(definitionUrl);
+ *   const result = await client.solve(definitionUrl, TreeBuilder.fromInputParams(io.inputs));
  * } finally {
  *   await client.dispose(); // Clean up resources
  * }
@@ -1109,16 +988,12 @@ declare class GrasshopperClient {
    * a user who clicked Solve, so the retry ladder must not spend its whole
    * budget confirming that a machine is switched off.
    *
-   * Each probe is bounded by {@link CREATE_PROBE_TIMEOUT_MS} rather than the
-   * stats default: a healthy `GET /` answers in milliseconds, so a longer
-   * per-probe timeout only multiplies the wait when the server is unreachable.
-   *
    * @throws {ComputeError} with code NETWORK_ERROR if the server stays
    *   unreachable across all attempts. `context.probeVerdict` carries the
    *   {@link ProbeVerdict} so callers can render a specific cause.
    * @throws {ComputeError} with code INVALID_CONFIG if configuration is invalid
    */
-  static create(config: GrasshopperComputeConfig): Promise<GrasshopperClient>;
+  static create(config: GrasshopperComputeConfig, options?: CreateClientOptions): Promise<GrasshopperClient>;
   /**
    * Gets the client's configuration.
    * Useful for passing to lower-level functions.
@@ -1162,16 +1037,7 @@ declare class GrasshopperClient {
    * 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 {ComputeError} with code INVALID_CONFIG if configuration is invalid
-   */
-  private normalizeComputeConfig;
 }
 //#endregion
 //#region src/grasshopper/io/output/response-processors.d.ts
@@ -1200,39 +1066,13 @@ interface GetValuesResult<T = ParsedContext> {
 }
 //#endregion
 //#region src/grasshopper/client/grasshopper-response-processor.d.ts
-/**
- * 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.
- */
+/** Reads parsed values and produced files out of one compute response. */
 declare class GrasshopperResponseProcessor {
-  /**
-   * 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()`.
-   */
+  /** Hand it to a mesh parser such as `@selvajs/visualization/parse`. */
   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);
+  /** Hand it to a mesh parser such as `@selvajs/visualization/parse`. */
+  response: GrasshopperComputeResponse);
   /**
    * Extract all values in the response.
    *
@@ -1269,19 +1109,6 @@ declare class GrasshopperResponseProcessor {
   } | {
     byId: string;
   }, options?: GetValuesOptions): any;
-  /**
-   * 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:
-   *
-   * ```ts
-   * import { getThreeMeshesFromComputeResponse } from '@selvajs/visualization/parse';
-   *
-   * const meshes = await getThreeMeshesFromComputeResponse(processor.response, { rhino });
-   * scene.add(...meshes);
-   * ```
-   */
-  private getFileData;
   /**
    * Download all files generated by Grasshopper, optionally including
    * additional user-provided files.
@@ -1315,100 +1142,54 @@ declare class GrasshopperResponseProcessor {
  * (false misses are harmless; false hits serve the wrong cached solve).
  */
 export declare function stableStringify(value: unknown): string;
-/**
- * Hash definition and data tree into a stable cache key.
- *
- * The definition is the *identity* of what we solve, so a binary definition is
- * hashed over its full content (`fnv1aBytes`) — a length-only or sampled key
- * would let two different `.gh` files collide and serve one's cached solve for
- * the other. `.gh` files are small enough that a single linear pass is
- * negligible. A {@link DefinitionRef} is keyed by its `key` alone — the
- * caller-declared identity of immutable bytes — so no bytes are materialized
- * or hashed at all.
- *
- * The key keeps the definition and tree hashes as separate parts rather than
- * collapsing them into one 32-bit hash: a single FNV pass over the pair would
- * birthday-collide quadratically in cache size, while requiring both 32-bit
- * parts (plus lengths) to collide at once makes that negligible.
- */
+/** The scheduler's solve-cache key for a definition and its input tree. */
 export declare function hashSolveInput(definition: SolveDefinition, dataTree: unknown): string;
 /**
- * Stable identity of a definition alone (no inputs) — used to key the
- * server-cache-key map so the same definition reuses its `pointer` across solves
- * with different inputs. Same full-content hashing as {@link hashSolveInput}: a
- * binary definition is hashed over all its bytes so two distinct `.gh` files of
- * equal length can't share a cache key. A {@link DefinitionRef} is keyed by its
- * `key` verbatim (refs are short identities like UUIDs, safe as Map keys) —
- * its immutability contract makes the key equivalent to a content hash.
+ * A definition's identity, without its inputs. Strings and bytes are hashed over their full
+ * content, so two files of equal length never share a key; a `DefinitionRef` uses its `key`.
  */
 export declare function hashDefinition(definition: SolveDefinition): string;
 //#endregion
 //#region src/grasshopper/solve.d.ts
 /**
- * Runs a Rhino Compute job using the provided tree prototypes and Grasshopper definition.
+ * Run one solve. `GrasshopperClient.solve()` adds input validation and throws on solver errors.
  *
- * @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)
- *   - A `DefinitionRef` (bytes are loaded via `ref.load()` for the upload)
- * @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.
+ * @param definition - A URL (sent as a pointer), base64 `.gh` content, raw `.gh` bytes, or a
+ *   `DefinitionRef` (loaded for the upload). Any other string is encoded as the definition text.
+ * @returns The compute response, without the server's `pointer` and echoed `algo`.
  *
  * @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);
+ * await solveGrasshopperDefinition(trees, new Uint8Array(await readFile('model.gh')), config);
  */
 export declare function solveGrasshopperDefinition(dataTree: DataTree[], definition: SolveDefinition, config: GrasshopperComputeConfig): Promise<GrasshopperComputeResponse>;
 //#endregion
 //#region src/grasshopper/io/definition-io.d.ts
 /**
- * Fetches raw input/output schemas from a Grasshopper definition.
+ * Fetches a definition's input/output schemas without per-type parsing.
  *
- * "Raw" means no per-type parsing (no default coercion, no discriminated-union
- * typing) — but NOT byte-for-byte wire data. The response IS normalized:
- * per-param field KEYS are canonicalized to camelCase across server branches
- * ({@link normalizeInputSchema} / {@link normalizeOutputSchema}, with honest
- * fallbacks for missing required fields), missing/non-array `inputs`/`outputs`
- * coerce to `[]`, and server load diagnostics surface as
- * `loadWarnings`/`loadErrors` (coerced to strings). Field VALUES — notably
- * `default` and the `values` dropdown-label map — pass through verbatim.
+ * Field KEYS are canonicalized to camelCase and missing required fields get a
+ * fallback ({@link normalizeInputSchema}); a missing or non-array `inputs` /
+ * `outputs` becomes `[]`. Field VALUES, notably `default` and the `values`
+ * label map, pass through verbatim.
  *
- * @param definition - The Grasshopper definition (URL, base64 string, or Uint8Array)
- * @param config - Compute configuration (server URL, API key, etc.)
- * @returns Key-normalized inputs and outputs with no per-type processing
  * @throws {ComputeError} If fetch fails or response is invalid
  *
  * @public Use `fetchParsedDefinitionIO()` for processed, type-safe inputs
  */
 export 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.
+ * Fetches a definition's input/output schemas and parses each input into its
+ * typed `InputParam`. An input that fails to parse gets a safe default
+ * and an entry in `parseErrors`.
  *
- * @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 {ComputeError} 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' }
+ *   { serverUrl: 'http://localhost:6500', apiKey: 'YOUR_KEY' }
  * );
  *
  * // Inputs are now strongly typed
@@ -1433,101 +1214,87 @@ interface SchemaEndpointResult<TSchema = unknown> {
  * Read compute's `/grasshopper/schema` body: `[{ FileName, Schemas }]` per
  * uploaded file, or a bare object for a single file.
  *
- * Use this rather than unwrapping the body by hand. The wrapper's casing varies
- * by server branch — mcneel serializes `FileName`/`Schemas`, the VektorNode fork
- * `fileName`/`schemas` — so a fixed-key read silently yields `undefined` against
- * half the servers, and the endpoint answers 200 either way. The failure looks
- * like "this definition has no schemas", which sends you debugging the wrong
- * thing entirely.
- *
- * A blanket key-rewrite (the old `camelcaseKeys` approach) is NOT the fix: it
- * reaches inside the schemas and mangles user-authored names — `"Display3d"` →
- * `"display3d"`, value-list labels like `"Option A"` → `"optionA"`. Only the two
- * wrapper keys are read here; schema CONTENTS pass through untouched, which is
- * why `TSchema` is a pass-through type parameter this module never inspects.
+ * Use this rather than unwrapping the body by hand: the wrapper keys' casing
+ * varies by server branch, and a fixed-key read yields "no schemas" with a 200.
+ * Only the two wrapper keys are read; schema contents pass through untouched.
  *
  * @typeParam TSchema - Your schema type (e.g. `UISchema`). Not inspected.
- * @param raw - The parsed JSON body.
  */
 export declare function readSchemaResults<TSchema = unknown>(raw: unknown): SchemaEndpointResult<TSchema>[];
 //#endregion
 //#region src/grasshopper/io/normalize-ui-schema.d.ts
 /**
- * Canonicalize a `/grasshopper/schema` body's key CASING.
- *
- * ## Why this exists
- *
- * Compute serializes the plugin's `UISchema` POCO, whose camelCase wire names
- * live in Newtonsoft `[JsonProperty]` attributes. `Selva.gha` ILRepack-merges
- * Newtonsoft into itself, so those attributes have type
- * `Selva!Newtonsoft.Json.JsonPropertyAttribute`. When the serializer that runs is
- * compute's OWN Newtonsoft assembly, it does not recognize that type as its own
- * attribute, reads no attributes at all, and falls back to raw CLR member names —
- * emitting `Inputs`/`Layout`/`SchemaVersion`.
- *
- * Nothing throws on the wire. Every consumer reads `schema.inputs` as
- * `undefined`, so the definition renders with no inputs, and `schemaVersion`
- * reads `undefined` — which also silently disables the newer-plugin version gate.
- *
- * This is the schema-body counterpart to {@link normalizeInputSchema}, which
- * solves the same split for the `/io` endpoint's param records.
- *
- * ## Why a casing rule, and not a key allowlist
- *
- * The wire names are the CLR names run through Newtonsoft's camelCase strategy,
- * so reproducing that strategy covers every key. An allowlist would have to
- * enumerate every structural key in `UISchema` and drift out of date each time
- * the schema gains a field, failing silently and in exactly this way again.
- *
- * ## What it does NOT touch
+ * Canonicalize a `/grasshopper/schema` body's key casing.
  *
- * `options`, `defaultOptions` and `values` hold USER-AUTHORED keys — dropdown
- * labels like `"Standart Beschichtung"`, `"Use 10 Elements instead"`, `"True"`.
- * Those maps are copied verbatim; only the key naming them is canonicalized.
- * Rewriting their contents is the exact regression that motivated deleting the
- * old global `camelcaseKeys` pass (see `read-field.ts`), which mangled
- * `"Option A"` into `"optionA"` and silently changed what a definition solved
- * with.
+ * Compute serializes the plugin's `UISchema`, whose camelCase wire names live in
+ * Newtonsoft `[JsonProperty]` attributes. `Selva.gha` ILRepack-merges Newtonsoft,
+ * so those attributes are `Selva!Newtonsoft.Json.JsonPropertyAttribute`. When
+ * compute's OWN Newtonsoft serializes, it doesn't recognize them, reads no
+ * attributes, and emits raw CLR names (`Inputs`, `SchemaVersion`). Nothing throws:
+ * `schema.inputs` reads `undefined`, and so does the `schemaVersion` gate.
  *
- * Values are never inspected — only object keys are rewritten.
+ * A casing rule, not a key allowlist: the wire names are the CLR names run
+ * through Newtonsoft's camelCase strategy, so reproducing it covers every key
+ * without drifting each time `UISchema` gains a field.
  */
 /**
- * Returns a schema whose structural keys are camelCase, regardless of which
- * Newtonsoft serialized it. A body that is already camelCase passes through
- * unchanged in shape (it is still rebuilt, so the result is always a fresh
- * object the caller may mutate).
- *
- * Safe to call on any parsed JSON value; non-objects are returned as-is.
+ * Returns a schema whose structural keys are camelCase, whichever Newtonsoft
+ * serialized it. Always a fresh object the caller may mutate; non-objects are
+ * returned as-is.
  */
 export declare function normalizeUISchemaCasing<T>(raw: T): T;
 //#endregion
 //#region src/grasshopper/io/input/input-processors.d.ts
 /**
  * Parse one raw Grasshopper input schema into a typed {@link InputParam}.
- * Validation failures are swallowed and replaced with a safe default; use
- * {@link processInputWithError} to receive them.
+ * A validation failure is swallowed and replaced with a safe default.
  */
 export declare function processInput(rawInput: InputParamSchema): InputParam;
 //#endregion
-//#region src/grasshopper/data-tree/data-tree.d.ts
+//#region src/grasshopper/io/output/rhino-objects.d.ts
 /**
- * Value types that can be stored in a DataTree
+ * Sentinel a Rhino geometry decode returns when a decode was attempted
+ * and failed hard (a registered decoder or `CommonObject.decode` threw). Carries
+ * the original payload so callers can log or retry. Use
+ * {@link isRhinoDecodeError} to detect it.
  */
-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;
+interface RhinoDecodeError {
+  __decodeError: true;
+  /** The Rhino type name the failed decode was attempted for. */
+  type: string;
+  /** The original (undecoded) payload. */
+  raw: unknown;
 }
+/** Type guard for the {@link RhinoDecodeError} sentinel. */
+export declare function isRhinoDecodeError(value: unknown): value is RhinoDecodeError;
 /**
- * InnerTree data structure for compute requests.
+ * Free every rhino3dm WASM object reachable from `value`.
+ *
+ * rhino3dm objects are emscripten bindings — JS GC never reclaims their WASM
+ * heap allocation, so everything decoded from a solve response (`getValues`,
+ * `getValue`) must be deleted explicitly or the heap
+ * grows monotonically across solves (e.g. a UI decoding per slider tick).
+ *
+ * Walks arrays and plain objects recursively; anything exposing a `delete()`
+ * method is treated as a WASM binding and freed (skipped if already deleted).
+ * Safe to call more than once and on values containing no WASM objects.
  */
-type ComputeInnerTreeData = { [path in DataTreePath]: ComputeDataItem[]; };
+export declare function disposeRhinoObjects(value: unknown): void;
+//#endregion
+//#region src/grasshopper/data-tree/data-tree.d.ts
+type DataTreeValue = string | number | boolean | object | null;
+/** One input's value for {@link TreeBuilder.fromValues}. */
+interface TreeValueEntry {
+  paramName: string;
+  /** Matched case-insensitively. */
+  paramType: string;
+  /** A scalar, an array (branch `{0}`), or a branch-path map like `{ '{0;1}': [1, 2] }`. */
+  value: unknown;
+  minimum?: number | null;
+  maximum?: number | null;
+}
 /**
- * Standalone TreeBuilder class for constructing Grasshopper TreeBuilder structures.
- * Does not depend on RhinoCompute library.
+ * Builds the Grasshopper data trees a solve takes as input.
  *
  * @example
  * ```ts
@@ -1541,247 +1308,70 @@ export 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 values to the branch at `path` (`[0, 1]` is `{0;1}`). */
   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
-   */
+  /** Replace the tree with a branch-path map like `{ '{0;1}': [1, 2] }`. */
   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
-   */
+  /** Append a value, or each value of an array, to branch `{0}`. */
   appendFlat(values: DataTreeValue | DataTreeValue[]): this;
-  /**
-   * Get the flattened list of all values in the tree.
-   *
-   * @returns Array of all values across all branches
-   */
+  /** Every value 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
-   */
+  /** The tree in the shape a solve request sends. */
   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);
-   * ```
+   * One tree per input that has a default, keyed by its nickname. Defaults are coerced and
+   * clamped by the same rules as {@link TreeBuilder.fromValues}.
    */
   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
+   * One tree per entry, coercing UI values the way Grasshopper reads them. Number and Integer
+   * items go through the numeric coercion (Integer rounds) and are clamped to
+   * `minimum`/`maximum`; Boolean items also accept `'true'`/`'false'`; every other type passes
+   * through. An item that fails coercion is dropped with a warning. An entry left with no items
+   * is omitted, so Grasshopper uses its own value; `''` is an item, not an empty value.
    */
-  static fromInputParam(input: InputParam): DataTree | undefined;
+  static fromValues(entries: TreeValueEntry[]): DataTree[];
+  private static branchesOf;
+  /** `null` means the item was rejected. */
+  private static itemCoercer;
   /**
-   * 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
-   *
-   * Copy-on-write: returns a new array; the caller's array is never mutated.
-   *
-   * @overload For TreeBuilder instances (high-level builder)
-   * @param trees - Array of TreeBuilder instances to read from (not mutated)
-   * @param paramName - The parameter name to set or replace
-   * @param newValue - The new value (scalar, array, or TreeBuilder structure)
-   * @returns A new TreeBuilder array with the updated parameter
-   *
-   * @overload For compiled InnerTree (low-level API format)
-   * @param trees - The compiled InnerTree array (typically from `client.solve()`; not mutated)
-   * @param paramName - The parameter name to set or replace
-   * @param newValue - The new value (scalar, array, or TreeBuilder structure)
-   * @returns A new 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]);
-   * ```
+   * Set or add `paramName`'s tree to `newValue`: a scalar, an array (branch `{0}`), or a
+   * branch-path map. Copy-on-write: returns a new array and leaves the caller's untouched, so
+   * assign the result.
    */
-  static replaceTreeValue(trees: TreeBuilder[], paramName: string, newValue: DataTreeValue): TreeBuilder[];
   static replaceTreeValue(trees: DataTree[], paramName: string, newValue: DataTreeValue): DataTree[];
+  private static buildFromValue;
   /**
-   * Build a TreeBuilder from a single value, dispatching on shape:
-   * DataTreeDefault structure, array, or scalar.
+   * `paramName`'s whole tree from a solve result's `values`, keyed by branch path (`'{0;1}'`).
+   * `null` when no tree has that param, an empty `Map` when it has no branches. An item without
+   * `data` reads as `null` in place, so indices don't shift.
    */
-  private static buildFromValue;
+  static getTree(trees: DataTree[], paramName: string): Map<DataTreePath, DataTreeValue[]> | null;
   /**
-   * 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
+   * `paramName`'s value when its tree has a single branch: one item unwrapped (`5`, not `[5]`),
+   * several as an array. `null` for a missing param or an empty tree.
    *
-   * @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, ...]
-   * ```
+   * @throws {ComputeError} `INVALID_INPUT` when the tree has more than one branch; read those
+   *   with {@link TreeBuilder.getTree}.
    */
-  static getTreeValue(trees: TreeBuilder[], paramName: string): DataTreeValue | null;
   static getTreeValue(trees: DataTree[], paramName: string): DataTreeValue | null;
+  private static paramNameOf;
   /**
-   * Read all values for `paramName` across every branch of the matching builder.
-   * Returns null when the builder isn't found.
-   */
-  private static readFromBuilders;
-  /**
-   * Read values from the first branch of the matching compiled InnerTree
-   * (multi-branch responses are not flattened — current semantics, pinned by
-   * the "reads from the first branch path only" test).
-   */
-  private static readFromDataTrees;
-  /**
-   * Parse a TreeBuilder path string like "{0;1;2}" into [0, 1, 2].
-   * Negative indices ("{-1;2}") and the root path "{}" are valid.
+   * Parse a branch path like `"{0;1;2}"` into `[0, 1, 2]`.
    *
-   * @param pathStr - Path string
-   * @returns Array of path indices
-   * @throws {ComputeError} `INVALID_INPUT` when the path string is not a valid
-   *   Grasshopper branch path. Malformed keys must never silently collapse to a
-   *   default branch — two distinct unparseable keys would merge their items
-   *   into one branch.
+   * @throws {ComputeError} `INVALID_INPUT` for a malformed path, rather than
+   *   collapsing it to a default branch where two bad keys would merge.
    */
   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}"
-   */
+  /** `[0, 1, 2]` → `"{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.
-   */
+  /** Booleans and numbers stay primitives: Grasshopper reads them typed. */
   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 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;
 }
 //#endregion
-export { type BooleanInputType, type CacheOptions, ComputeServerStats, type DataItem, type DataTree, type DataTreeDefault, type DataTreePath, type DataTreeValue, type DefaultValue, type DefinitionRef, type FileBaseInfo, type FileData, 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 ProcessedFile, type RhinoModelUnit, type SchedulerMode, type SchemaEndpointResult, type SelvaEventTarget, type SelvaResponseBlock, type SolveContext, type SolveDefinition, type SolveOptions, type SolveResult, type SolveSchedulerOptions, type TextInputType, type ValueListInputType, downloadFileData, extractFilesFromComputeResponse, isDefinitionRef };
+export { type BooleanInputType, type CacheOptions, type ColorInputType, ComputeServerStats, type CreateClientOptions, type DataItem, type DataTree, type DataTreeDefault, type DataTreePath, type DataTreeValue, type DefaultValue, type FileInputType, type GeometryInputType, type GetValuesOptions, type GetValuesResult, GrasshopperClient, type GrasshopperComputeConfig, type GrasshopperComputeResponse, type GrasshopperParsedIO, type GrasshopperParsedIORaw, GrasshopperResponseProcessor, type InnerTreeData, type InputParam, type InputParamSchema, type InputParseError, type NumericInputType, type OutputParamSchema, type ParsedContext, type RhinoDecodeError, type RhinoModelUnit, type SchedulerMode, type SchedulerSolveOptions, type SchemaEndpointResult, type SelvaEventTarget, type SelvaResponseBlock, type ServerStats, type ServerVersion, type SolveContext, type SolveDetail, type SolveExecutor, type SolveOptions, type SolveResult, type SolveSchedulerOptions, type TextInputType, type TreeValueEntry, type ValueListInputType };
 //# sourceMappingURL=grasshopper.d.ts.map