@selvajs/compute 5.0.0-beta.7 → 5.0.0-beta.9

package/README.md

@@ -21,6 +21,8 @@ objects, use [`@selvajs/visualization`](https://www.npmjs.com/package/@selvajs/v
 npm install @selvajs/compute
 ```
 
+The package is ESM only, with two entrypoints: `/core` and `/grasshopper`.
+
 Two entrypoints: `@selvajs/compute/grasshopper` (client, scheduler, data trees, IO parsing) and
 `@selvajs/compute/core` (low-level fetch, errors, config). There is no root entry: import a
 subpath.
@@ -65,6 +67,10 @@ scheduler.subscribe(() => {
 });
 ```
 
+New here? [How the client works](https://selva.dev/docs/packages/build/how-it-works) explains the pieces, and [Common tasks](https://selva.dev/docs/packages/build/common-tasks) has copy-ready examples.
+
+> `client.solve` throws on solver errors; `scheduler.solve` resolves with them. See [Errors](#errors).
+
 ## Configuring the scheduler
 
 Pick the row that matches what the user is doing:
@@ -72,7 +78,7 @@ Pick the row that matches what the user is doing:
 | Workload                          | `mode`          | `timeoutMs`      | `retry`           | Notes                                                                                                                    |
 | --------------------------------- | --------------- | ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
 | **Slider scrubs / live previews** | `'latest-wins'` | `30_000`         | default           | Aborts in-flight solves when newer values arrive. Add `cache: { maxBytes: 64 * 1024 * 1024 }` for instant repeats.       |
-| **Submit / long-running jobs**    | `'queue'`       | `0` (no timeout) | `{ attempts: 1 }` | Serial queue. Pass a caller `signal` so users can hit Cancel. See [Long jobs behind a proxy](#long-jobs-behind-a-proxy). |
+| **Submit / long-running jobs**    | `'queue'`       | `0` (no timeout) | default           | Serial queue. Pass a caller `signal` so users can hit Cancel. See [Long jobs behind a proxy](#long-jobs-behind-a-proxy). |
 | **Background / batch parallel**   | `'queue'`       | `60_000`         | `{ attempts: 2 }` | Set `maxConcurrent` (e.g. 4) to run that many solves at once; queue mode defaults to 1.                                  |
 
 Create one scheduler per UI surface: their queues, cancel scopes and caches are independent.
@@ -110,6 +116,20 @@ work around that: raise the proxy's idle timeout before running long solves from
 solves longer than a couple of minutes, run this library server-side behind your own job queue
 and expose a status endpoint to the browser.
 
+On Node, undici stops waiting for response headers at 300 s, and neither `timeoutMs` nor `0` lifts
+that: the solve fails with `NETWORK_ERROR` while it is still running on the server, and a retry
+would run it a second time. Past 300 s, keep `retry` off and pass a `fetch` with a longer limit:
+
+```ts
+import { Agent, fetch as undiciFetch } from 'undici';
+
+const dispatcher = new Agent({ headersTimeout: 0, bodyTimeout: 0 });
+const client = await GrasshopperClient.create({
+	serverUrl,
+	fetch: (url, init) => undiciFetch(url, { ...init, dispatcher })
+});
+```
+
 ## Errors
 
 Every failure is a `ComputeError`. Branch on `err.code`, one of `ErrorCodes`, not on the message.
@@ -147,17 +167,16 @@ Read outputs through `GrasshopperResponseProcessor`, or a whole tree with
 `getTreeValue` is the shortcut for a one-branch param: it unwraps a single item and throws when
 the param has more than one branch.
 
-Pass a rhino3dm module as `{ rhino }` in the `getValues` / `getValue` options to decode geometry. Its objects live on the WASM
-heap, which garbage collection never frees: release them with `disposeRhinoObjects`. Install
-`rhino3dm` yourself; this package doesn't depend on it.
+Pass a rhino3dm module as `{ rhino }` in the `getValues` / `getValue` options to decode geometry.
+Its objects live on the WASM heap, which garbage collection never frees: release them with
+`disposeRhinoObjects`. Install `rhino3dm` yourself; this package doesn't depend on it.
 
 ## File outputs
 
-File outputs need the [Selva plugin](https://www.food4rhino.com/en/app/selva?lang=en) and the
-[VektorNode compute fork](https://github.com/VektorNode/compute.rhino3d); standard Rhino Compute
-drops them. Read one with `getValue` and it comes back as `FileData`.
+File outputs need the Selva plugin and the VektorNode fork (see [Requirements](#requirements));
+standard Rhino Compute drops them. Read one with `getValue` and it comes back as `FileData`.
 
-Each file component has a `Sub Folder` input, where `::` nests (as in Rhino layer names). The
+Each file component has a `Sub Folder` input, where `/` or `::` nests (as in Rhino layer names). The
 first segment is the root: `downloadFileDataByRoot` from `/core` turns each root into its own
 archive and puts files without one in the fallback archive. With `'export'` as the fallback name:
 
@@ -174,8 +193,6 @@ archive and puts files without one in the fallback archive. With `'export'` as t
 
 ## Requirements
 
-**Node.js >= 24.**
-
 The [official McNeel Rhino Compute](https://github.com/mcneel/compute.rhino3d) handles plain
 Grasshopper solving. The [VektorNode compute fork](https://github.com/VektorNode/compute.rhino3d)
 adds input grouping (`groupName`), persistent input ids keyed on Grasshopper object GUIDs, file
@@ -185,7 +202,9 @@ file-export components those features read.
 
 ## Troubleshooting
 
-**`Network error: Failed to fetch`** means the browser couldn't reach the server. Check that
+**`CORS_ERROR` (`Request failed: Failed to fetch`)** means the browser got no response, which it
+reports the same way for a CORS block and for an unreachable server. Outside a browser the same
+failure is `NETWORK_ERROR`. Check that
 `curl http://localhost:6500/` returns 200; that a server on another origin sends
 `Access-Control-Allow-Origin` (standard Rhino Compute doesn't: put a proxy in front that adds it,
 or use the [VektorNode fork](https://github.com/VektorNode/compute.rhino3d)); that an HTTPS app

package/dist/core.d.ts

@@ -1,2 +1,190 @@
-import { A as ServerErrorCodeMap, C as enableDebugLogging, D as ComputeAuth, E as fetchCompute, M as ComputeError, N as ErrorCode, O as ComputeConfig, P as ErrorCodes, S as Logger, T as setLogger, _ as SolveDefinition, a as extractFilesFromComputeResponse, b as hasField, c as FileData, d as ProbeVerdict, f as classifyProbeFailure, g as DefinitionRef, h as validateServerUrl, i as downloadFileDataByRoot, j as ServerTiming, k as RetryPolicy, l as ProcessedFile, m as ValidateServerUrlOptions, n as subFolderSegments, o as DownloadOptions, p as DEFAULT_BLOCKED_HOST, r as downloadFileData, s as FileBaseInfo, t as groupFilesByRoot, u as ProbeFailure, v as isDefinitionRef, w as getLogger, x as readField, y as decodeBase64ToBinary } from "./index-DDmprCht.js";
-export { type ComputeAuth, type ComputeConfig, ComputeError, DEFAULT_BLOCKED_HOST, type DefinitionRef, type DownloadOptions, type ErrorCode, ErrorCodes, type FileBaseInfo, type FileData, type Logger, type ProbeFailure, type ProbeVerdict, type ProcessedFile, type RetryPolicy, type ServerErrorCodeMap, type ServerTiming, type SolveDefinition, type ValidateServerUrlOptions, classifyProbeFailure, decodeBase64ToBinary, downloadFileData, downloadFileDataByRoot, enableDebugLogging, extractFilesFromComputeResponse, fetchCompute, getLogger, groupFilesByRoot, hasField, isDefinitionRef, readField, setLogger, subFolderSegments, validateServerUrl };
+import { a as DefinitionRef, c as ComputeAuth, d as ServerErrorCodeMap, f as ServerTiming, h as ErrorCodes, i as ProcessedFile, l as ComputeConfig, m as ErrorCode, n as FileBaseInfo, o as SolveDefinition, p as ComputeError, r as FileData, s as isDefinitionRef, t as DownloadOptions, u as RetryPolicy } from "./types-Dm9QFVvA.js";
+/**
+ * POST `args` as JSON to `<serverUrl>/<endpoint>` with retry, timeout and abort handling, and
+ * return the parsed response. Most callers want a higher-level API.
+ *
+ * `R` names the expected response shape; nothing checks it, so the default `unknown` forces a
+ * narrowing.
+ *
+ * @example
+ * const response = await fetchCompute('grasshopper', args, {
+ *   serverUrl: 'https://my-server.com',
+ *   timeoutMs: 30_000,
+ *   retry: { attempts: 2 },
+ *   signal: controller.signal
+ * });
+ */
+export declare function fetchCompute<R = unknown>(endpoint: string, args: Record<string, any>, config: ComputeConfig): Promise<R>;
+interface Logger {
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+export declare function getLogger(): Logger;
+/**
+ * Route the package's logs to `logger`; `null` silences them (the default).
+ *
+ * @throws {ComputeError} `INVALID_CONFIG` if the logger lacks one of the four methods, rather
+ *   than a "debug is not a function" later at an unrelated call site.
+ *
+ * @example
+ * ```typescript
+ * import { setLogger } from '@selvajs/compute/core';
+ *
+ * setLogger(console);
+ * setLogger({
+ *   debug: (msg, ...args) => myLogger.debug(msg, ...args),
+ *   info: (msg, ...args) => myLogger.info(msg, ...args),
+ *   warn: (msg, ...args) => myLogger.warn(msg, ...args),
+ *   error: (msg, ...args) => myLogger.error(msg, ...args)
+ * });
+ * setLogger(null);
+ * ```
+ */
+export declare function setLogger(logger: Logger | Console | null): void;
+/** Shorthand for `setLogger(console)`. */
+export declare function enableDebugLogging(): void;
+/**
+ * Case-insensitive field reads for wire payloads.
+ *
+ * Rhino Compute branches serialize the same field in different casings. mcneel 8.x/9.x send the IO
+ * schema PascalCase (`ParamType`, `Default`, `InnerTree`): those C# classes carry no
+ * `[JsonProperty]`. The VektorNode fork sends camelCase, except inside the `default` DataTree
+ * (`ParamName`, `InnerTree`), an external type it can't attribute. So one response can mix casings.
+ * Read the fields you need through here and leave the rest verbatim: rewriting every key corrupts
+ * user-authored ones such as value-list labels.
+ */
+/**
+ * Read `name` in any casing, preferring an exact-case match. `undefined` when no own key matches or
+ * `obj` isn't an object.
+ */
+export declare function readField<T = unknown>(obj: unknown, name: string): T | undefined;
+/** Whether `name` is present in any casing, even with a null or undefined value. */
+export declare function hasField(obj: unknown, name: string): boolean;
+/**
+ * Decode base64 to bytes, normalizing and validating the same way in Node and browsers.
+ * `packages/visualization/src/shared/encoding.ts` keeps a copy that throws its own error class;
+ * change both together.
+ *
+ * @throws {ComputeError} `ENCODING_ERROR` if invalid, or `ENVIRONMENT_ERROR` if the runtime has no decoder
+ */
+export declare function decodeBase64ToBinary(base64File: string): Uint8Array;
+/**
+ * The public McNeel endpoint, blocked by default: users must point at their own server. Its raw IP
+ * isn't blocked: it sits behind a load balancer with no stable address to pin.
+ */
+export declare const DEFAULT_BLOCKED_HOST = "compute.rhino3d.com";
+interface ValidateServerUrlOptions {
+  /**
+   * Hostnames rejected as a `serverUrl` — a backend's shared public endpoint,
+   * which callers must not point at. Defaults to `[DEFAULT_BLOCKED_HOST]`; pass
+   * `[]` to block nothing. Compared lowercased with any trailing dot stripped.
+   */
+  blockedHosts?: readonly string[];
+}
+/**
+ * Validate a compute `serverUrl` and return it trimmed, without trailing slashes.
+ *
+ * @throws {ComputeError} `INVALID_CONFIG` when the URL is empty, isn't http(s), doesn't parse,
+ *   embeds credentials, has a query or fragment, or names a blocked host.
+ */
+export declare function validateServerUrl(raw: string, options?: ValidateServerUrlOptions): string;
+/**
+ * Why a liveness probe failed, and whether waiting can change the answer.
+ *
+ * `retryable` is the whole point: a powered-off VM and a booting one both read
+ * as "offline" from a single probe, but only one of them will ever come up. A
+ * caller that can't tell them apart has to assume the optimistic case and burn
+ * its full retry window on a machine that is simply off.
+ */
+type ProbeVerdict =
+/** Nothing is listening on the port — the host answered, and said no. */
+'refused' |
+/** The hostname does not resolve. */
+'dns' |
+/** No answer within the timeout: a booting host swallows packets rather than refusing them. */
+'timeout' |
+/** The server answered, but rejected the probe's credentials (401/403). */
+'unauthorized' |
+/** The server answered with a non-2xx that isn't an auth rejection. */
+'http_error' |
+/** Connection failed in a way we can't attribute. */
+'unknown';
+interface ProbeFailure {
+  verdict: ProbeVerdict;
+  /** Whether retrying the same probe could plausibly succeed later. */
+  retryable: boolean;
+  /** Operator-facing sentence. Never includes the API key. */
+  summary: string;
+}
+/**
+ * Classify a `ComputeServerStats.probeServer` result.
+ *
+ * A DNS failure is treated as retryable even though a missing record won't fix
+ * itself: `EAI_AGAIN` is a *timeout* talking to the resolver, and the two are
+ * not distinguishable from the error alone. Retrying a genuinely-wrong hostname
+ * costs one window; giving up on a resolver hiccup breaks a server that is fine.
+ *
+ * @param probe - The `{ online, status?, error? }` a probe returned. An `online`
+ *   probe is not a failure and yields `null`.
+ */
+export declare function classifyProbeFailure(probe: {
+  online: boolean;
+  status?: number;
+  error?: string;
+}): ProbeFailure | null;
+/**
+ * Decode the files in a compute response, plus any external `additionalFiles`, without
+ * downloading them. Never throws: an unnamed or undecodable item and a failed external fetch are
+ * logged and dropped, the rest still resolve. Colliding archive paths are renamed
+ * (`model.txt` → `model-2.txt`), so a consumer keying by `path` loses nothing.
+ */
+export declare const extractFilesFromComputeResponse: (downloadableFiles: FileData[], additionalFiles?: FileBaseInfo[] | FileBaseInfo | null) => Promise<ProcessedFile[]>;
+/** Downloads files from a compute response as a ZIP archive. */
+export declare const downloadFileData: (downloadableFiles: FileData[], fileFoldername: string, additionalFiles?: FileBaseInfo[] | FileBaseInfo | null, options?: DownloadOptions) => Promise<void>;
+/**
+ * Download one archive per `Sub Folder` root (see {@link groupFilesByRoot}). Files with no root go
+ * into `fallbackName`, so a definition that never sets `Sub Folder` downloads as one archive.
+ *
+ * Archives are saved one at a time: browsers discard concurrent downloads issued in the same tick.
+ * More than one save per gesture may prompt the user for permission.
+ *
+ * @param downloadableFiles - `FileData` items from the compute response.
+ * @param fallbackName - Archive name for files with no `Sub Folder` root.
+ * @param additionalFiles - Extra files to package; they carry no root and join the fallback archive.
+ * @param options - `saveBlob` replaces the anchor download for every archive.
+ */
+export declare const downloadFileDataByRoot: (downloadableFiles: FileData[], fallbackName: string, additionalFiles?: FileBaseInfo[] | FileBaseInfo | null, options?: DownloadOptions) => Promise<void>;
+/**
+ * The `Sub Folder` convention, as authored on Selva's Grasshopper file components.
+ *
+ * `::` nests, matching Rhino's layer separator (`ROOT::Panels`), and `/` and `\` are accepted
+ * because people type them out of habit. The plugin normalizes to `/` before sending, so these
+ * helpers also cover payloads from an older plugin that still emit `::`.
+ *
+ * The first segment is the **root**, which names the archive rather than becoming a folder inside
+ * it: `ROOT::Panels` downloads as `ROOT.zip` containing `Panels/…`. Files sharing a root travel
+ * together; distinct roots produce separate archives.
+ */
+/**
+ * Split a `Sub Folder` value into folder segments; `/`, `\` and `::` all separate.
+ *
+ * Exported because anything rendering a folder tree has to agree with the archive on where the
+ * boundaries are — splitting on `/` alone leaves `Main::Panels` as one literal segment and shows
+ * a folder named after the separator.
+ */
+export declare const subFolderSegments: (subFolder: string | undefined) => string[];
+/**
+ * Group files by their `Sub Folder` root, preserving encounter order.
+ *
+ * Rootless files group under `''` — a caller naming archives supplies its own fallback for that
+ * bucket. Useful beyond downloading: a consumer writing to disk gets the same grouping without
+ * touching the DOM.
+ */
+export declare const groupFilesByRoot: <T extends Pick<FileData, "subFolder">>(files: readonly T[]) => Array<{
+  root: string;
+  files: T[];
+}>;
+export { type ComputeAuth, type ComputeConfig, ComputeError, type DefinitionRef, type DownloadOptions, type ErrorCode, ErrorCodes, type FileBaseInfo, type FileData, type Logger, type ProbeFailure, type ProbeVerdict, type ProcessedFile, type RetryPolicy, type ServerErrorCodeMap, type ServerTiming, type SolveDefinition, type ValidateServerUrlOptions, isDefinitionRef };
+//# sourceMappingURL=core.d.ts.map

package/dist/core.js

@@ -1 +1 @@
-export{D as ComputeError,b as DEFAULT_BLOCKED_HOST,O as ErrorCodes,u as classifyProbeFailure,g as decodeBase64ToBinary,t as downloadFileData,n as downloadFileDataByRoot,w as enableDebugLogging,r as extractFilesFromComputeResponse,l as fetchCompute,T as getLogger,a as groupFilesByRoot,S as hasField,s as isDefinitionRef,C as readField,E as setLogger,o as subFolderSegments,x as validateServerUrl}from"./core-BPYXUtfq.js";
+export { P as ComputeError, T as DEFAULT_BLOCKED_HOST, F as ErrorCodes, d as classifyProbeFailure, y as decodeBase64ToBinary, t as downloadFileData, n as downloadFileDataByRoot, j as enableDebugLogging, r as extractFilesFromComputeResponse, l as fetchCompute, M as getLogger, a as groupFilesByRoot, k as hasField, s as isDefinitionRef, A as readField, N as setLogger, o as subFolderSegments, E as validateServerUrl } from "./handle-files-fKtSlWT2.js";

package/dist/grasshopper.d.ts

@@ -1,4 +1,4 @@
-import { D as ComputeAuth, M as ComputeError, O as ComputeConfig, _ as SolveDefinition, j as ServerTiming, k as RetryPolicy, s as FileBaseInfo } from "./index-DDmprCht.js";
+import { c as ComputeAuth, f as ServerTiming, l as ComputeConfig, n as FileBaseInfo, o as SolveDefinition, p as ComputeError, u as RetryPolicy } from "./types-Dm9QFVvA.js";
 interface ServerVersion {
   rhino: string;
   compute: string;
@@ -10,9 +10,7 @@ interface ServerStats {
   activeChildren?: number;
 }
 /**
- * ComputeServerStats provides methods to query Rhino Compute server statistics.
- *
- * @public Use this for server health monitoring and statistics.
+ * Server health and control: liveness, version, child processes, cache purges.
  *
  * @example
  * ```typescript
@@ -83,10 +81,11 @@ declare class ComputeServerStats {
    *
    * @param timeoutMs - Abort the probe after this many ms (default: 5000).
    *   Pass `0` to disable the timeout.
+   * @param signal - Cancels the probe, which then reports the abort as its `error`.
    * @returns `online` plus either the HTTP `status` the server answered with,
    *   or the `error` the connection attempt failed with.
    */
-  probeServer(timeoutMs?: number): Promise<{
+  probeServer(timeoutMs?: number, signal?: AbortSignal): Promise<{
     online: boolean;
     status?: number;
     error?: string;
@@ -317,7 +316,8 @@ type DataTreePath = `{${string}}`;
 interface DataItem {
   type: string;
   data: string;
-  id: string;
+  /** **Requires:** the VektorNode compute fork. A stock server sends none. */
+  id?: string;
 }
 type DataTreeDefault<T = any> = { [K in DataTreePath]?: T[]; };
 type InnerTreeData = { [path in DataTreePath]: DataItem[]; };
@@ -353,12 +353,14 @@ interface BaseInputType {
   treeAccess: boolean;
   /**
    * Name of the group this parameter belongs to.
-   * @requires Custom branch of compute.rhino3d
+   *
+   * **Requires:** the VektorNode compute fork.
    */
   groupName?: string;
   /**
    * Unique identifier for the parameter.
-   * @requires Custom branch of compute.rhino3d
+   *
+   * **Requires:** the VektorNode compute fork.
    */
   id?: string;
 }
@@ -437,15 +439,6 @@ interface GrasshopperBaseSchema {
   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;
 }
 /**
  * Where a Selva-family plugin running inside the solve may POST live events, and
@@ -636,12 +629,19 @@ interface CacheOptions {
    * Cache responses that carry Grasshopper `errors`. Default `true`: an
    * errored solve is a valid, deterministic result — definitions raise GH
    * errors by design (guarded components, validation branches), so replaying
-   * one from cache is correct. Set `false` for parity with Rhino's opt-in
-   * `cacheerroredsolves` server flag, e.g. when a definition's errors are
+   * one from cache is correct. Set `false` when a definition's errors are
    * transient (external data sources) rather than functions of the inputs.
    */
   cacheErroredSolves?: boolean;
 }
+/** What {@link SolveScheduler.cacheStats} reports. */
+interface CacheStats {
+  entries: number;
+  bytes: number;
+  hits: number;
+  misses: number;
+  evictions: number;
+}
 interface SolveSchedulerOptions {
   mode?: SchedulerMode;
   maxConcurrent?: number;
@@ -706,8 +706,6 @@ type SolveResult = {
   status: 'error';
   error: ComputeError;
   durationMs: number;
-} | {
-  status: 'superseded';
 };
 /**
  * Solves by `cacheKey` when given one, otherwise uploads. Reports the server's
@@ -773,15 +771,7 @@ export declare class SolveScheduler {
   private readonly queueWaitMs;
   private readonly timeoutMs;
   private readonly retry;
-  private readonly cacheEnabled;
-  private readonly cacheMaxBytes;
-  private readonly cacheTtl;
-  private readonly cacheErroredSolves;
   private readonly cache;
-  private cacheBytes;
-  private cacheHits;
-  private cacheMisses;
-  private cacheEvictions;
   private readonly reuseServerDefinitionCache;
   /** Definition hash → the server's cache key (`pointer`) for it. */
   private readonly serverCacheKeys;
@@ -816,10 +806,10 @@ export declare class SolveScheduler {
    * Raising it drains queued work immediately. Lowering it never interrupts work
    * already in flight — those finish above the new limit, and the cap applies from
    * the next dispatch. Values below 1 are clamped, since 0 would wedge the queue.
+   *
+   * @throws {ComputeError} `INVALID_CONFIG` for `NaN`, which would wedge it too.
    */
   setMaxConcurrent(value: number): void;
-  /** Current concurrency cap — reflects any {@link setMaxConcurrent} adjustment. */
-  getMaxConcurrent(): number;
   /** Subscribe to state changes. */
   subscribe(listener: () => void): () => void;
   private notify;
@@ -880,13 +870,10 @@ export declare class SolveScheduler {
    */
   private fail;
   private settleSuccess;
-  private removeQueuedAbortHandler;
+  private claimSettle;
   private normalizeExecutionError;
   /** Cancel everything — in-flight and pending. */
   cancelAll(): void;
-  private readCache;
-  private writeCache;
-  private dropCacheEntry;
   clearCache(): void;
   /**
    * Observability snapshot of the solve cache: current size plus lifetime
@@ -898,13 +885,7 @@ export declare class SolveScheduler {
    * 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;
-  };
+  cacheStats(): CacheStats;
   dispose(): void;
   private runHook;
 }
@@ -937,13 +918,10 @@ interface CreateClientOptions {
   };
 }
 /**
- * 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.
+ * The high-level API for solving Grasshopper definitions on a Rhino Compute server.
  *
- * **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.
+ * In a browser, the server URL and API key are exposed to users: run it server-side, or proxy
+ * requests through your own backend.
  *
  * @example
  * ```typescript
@@ -963,39 +941,26 @@ interface CreateClientOptions {
 declare class GrasshopperClient {
   private readonly config;
   readonly serverStats: ComputeServerStats;
+  private readonly schedulers;
   private disposed;
   /**
-   * Per-probe timeout for the `create()` liveness gate. A healthy `GET /` on the
-   * proxy answers in milliseconds; this bound only ever applies to a server that
-   * is not answering, where every extra second is multiplied by the retry count
-   * and paid by whoever is waiting on the solve.
+   * Per-probe timeout for the `create()` liveness gate: a healthy `GET /` answers in milliseconds,
+   * so this only bounds a silent server, and every extra second is paid once per retry.
    */
   private static readonly CREATE_PROBE_TIMEOUT_MS;
   private constructor();
   /**
-   * Creates and initializes a GrasshopperClient with server validation.
+   * Creates a client once a liveness probe (`GET /`) says the server is up. A cold server can read
+   * as offline, so the probe retries with a short backoff, stopping early when
+   * {@link classifyProbeFailure} says waiting can't change the answer. `config.signal` cancels the
+   * ladder.
    *
-   * The pre-flight liveness probe (a GET on the proxy root `/`) is a
-   * single-sample boolean gate that reads a cold or briefly-busy-but-up server
-   * as offline. To avoid failing construction on that transient class, the probe
-   * is retried with a short exponential backoff before giving up.
-   *
-   * Retries stop early when {@link classifyProbeFailure} says waiting cannot
-   * change the answer — connection refused, or a 401/403. This runs in front of
-   * a user who clicked Solve, so the retry ladder must not spend its whole
-   * budget confirming that a machine is switched off.
-   *
-   * @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
+   * @throws {ComputeError} `NETWORK_ERROR` if the server stays unreachable across all attempts.
+   *   `context.probeVerdict` carries the verdict, so a caller can render a specific cause.
+   * @throws {ComputeError} `ABORTED` if `config.signal` fires first.
+   * @throws {ComputeError} `INVALID_CONFIG` if the configuration is invalid.
    */
   static create(config: GrasshopperComputeConfig, options?: CreateClientOptions): Promise<GrasshopperClient>;
-  /**
-   * Gets the client's configuration.
-   * Useful for passing to lower-level functions.
-   */
-  getConfig(): GrasshopperComputeConfig;
   /**
    * Get input/output parameters of a Grasshopper definition.
    */
@@ -1025,23 +990,31 @@ declare class GrasshopperClient {
    * @example
    * ```ts
    * const sliderScheduler = client.createScheduler({ mode: 'latest-wins' });
-   * const submitScheduler = client.createScheduler({ mode: 'queue', timeoutMs: 0, retry: { attempts: 1 } });
+   * const submitScheduler = client.createScheduler({ mode: 'queue', timeoutMs: 0 });
    * ```
    */
   createScheduler(options?: SolveSchedulerOptions): SolveScheduler;
-  /**
-   * Disposes of client resources.
-   * Call this when you're done using the client.
-   */
+  /** Disposes of client resources, including every scheduler it created. */
   dispose(): Promise<void>;
   private ensureNotDisposed;
 }
+/**
+ * The part of rhino3dm the decoders call. Structural so the public types don't name `rhino3dm`, a
+ * dev dependency here. A loaded `RhinoModule` satisfies it.
+ */
+interface RhinoRuntime {
+  Point: new (location: number[]) => unknown;
+  Line: new (from: number[], to: number[]) => unknown;
+  CommonObject: {
+    decode(jsonObject: object): unknown;
+  };
+}
 interface ParsedContext {
   [key: string]: any;
 }
 interface GetValuesOptions {
   parseValues?: boolean;
-  rhino?: any;
+  rhino?: RhinoRuntime;
   /**
    * If true, only include values of type System.String in the result.
    * Non-string types are filtered out.
@@ -1106,9 +1079,7 @@ declare class GrasshopperResponseProcessor {
    * 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 folderName - Name of the zip archive, without the extension.
    * @param additionalFiles - Extra files to package (single file, array, or null).
    *
    * @example
@@ -1118,7 +1089,7 @@ declare class GrasshopperResponseProcessor {
    *
    * @example
    * ```ts
-   * const extra = { name: 'notes.txt', data: 'Example' };
+   * const extra = { fileName: 'notes.txt', filePath: 'https://example.com/notes.txt' };
    * await processor.getAndDownloadFiles('project', extra);
    * ```
    */
@@ -1157,14 +1128,11 @@ export declare function solveGrasshopperDefinition(dataTree: DataTree[], definit
 /**
  * Fetches a definition's input/output schemas without per-type parsing.
  *
- * 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`
+ * Field KEYS are canonicalized to camelCase and missing required fields get a fallback; a missing
+ * or non-array `inputs` / `outputs` becomes `[]`. Field VALUES, notably `default` and the `values`
  * label map, pass through verbatim.
  *
  * @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>;
 /**
@@ -1287,17 +1255,14 @@ export declare class TreeBuilder {
   private innerTree;
   private paramName;
   constructor(paramName: string);
-  /** Append values to the branch at `path` (`[0, 1]` is `{0;1}`). */
+  /** Append values to the branch at `path` (`[0, 1]` is `{0;1}`). A `null` item is skipped. */
   append(path: number[], items: DataTreeValue[]): this;
   /** Replace the tree with a branch-path map like `{ '{0;1}': [1, 2] }`. */
   fromDataTreeDefault(treeData: DataTreeDefault): this;
   /** Append a value, or each value of an array, to branch `{0}`. */
   appendFlat(values: DataTreeValue | DataTreeValue[]): this;
-  /** Every value across all branches. */
-  flatten(): DataTreeValue[];
   /** The tree in the shape a solve request sends. */
   toComputeFormat(): DataTree;
-  getParamName(): string;
   /**
    * 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}.
@@ -1351,5 +1316,5 @@ export declare class TreeBuilder {
   private static hasValidValue;
   private static clampValue;
 }
-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 };
+export { type BooleanInputType, type CacheOptions, type CacheStats, 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 RhinoRuntime, 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