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

package/README.md

@@ -4,7 +4,6 @@
 [![npm version](https://img.shields.io/npm/v/@selvajs/compute.svg)](https://www.npmjs.com/package/@selvajs/compute)
 [![npm downloads](https://img.shields.io/npm/dm/@selvajs/compute.svg)](https://www.npmjs.com/package/@selvajs/compute)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue.svg)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-24+-green.svg)](https://nodejs.org/)
 [![GitHub Repository](https://img.shields.io/badge/GitHub-VektorNode/selva-blue?logo=github)](https://github.com/VektorNode/selva)
 
@@ -15,28 +14,27 @@
 A TypeScript client for Rhino Compute and Grasshopper definitions: typed definition IO, data trees,
 and a scheduler that handles cancellation, retries and caching.
 
-Pure solve/data — no rendering layer, no `three` dependency. To turn a solve response into Three.js
+Pure solve/data: no rendering layer, no `three` dependency. To turn a solve response into Three.js
 objects, use [`@selvajs/visualization`](https://www.npmjs.com/package/@selvajs/visualization).
 
 ```bash
 npm install @selvajs/compute
 ```
 
-Three entrypoints: `@selvajs/compute/grasshopper` (client, data trees, IO parsing),
-`@selvajs/compute/core` (low-level fetch, errors, config). The root is empty on purpose — import a
-subpath.
+The package is ESM only, with two entrypoints: `/core` and `/grasshopper`.
 
-> **This is not a job queue.** For solves longer than a couple of minutes, run this library
-> server-side behind your own queue (BullMQ / SQS / Cloud Tasks) and expose a status endpoint to
-> the browser.
+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.
 
 ## Quickstart
 
-Every solve in `@selvajs/compute` goes through a **scheduler**. The scheduler
-handles cancellation, retries, loading state, and (optionally) a response cache
-— things every real app needs and shouldn't have to rebuild.
+`client.solve` sends one request. A scheduler adds cancellation, retries, loading state and an
+optional response cache on top; use one for any UI that fires solves.
 
 ```ts
+import { readFile } from 'node:fs/promises';
+import { ErrorCodes } from '@selvajs/compute/core';
 import {
 	GrasshopperClient,
 	TreeBuilder,
@@ -48,15 +46,15 @@ const client = await GrasshopperClient.create({
 	apiKey: 'your-api-key'
 });
 
-// Configure the scheduler for your workload (see "Configuring the scheduler" below).
 const scheduler = client.createScheduler({ mode: 'latest-wins', timeoutMs: 30_000 });
 
-// Inspect the definition's inputs once, build a data tree.
-const io = await client.getIO('my-definition.gh');
+// A URL, or the .gh bytes: a bare file name would be sent as the definition text.
+const definition = new Uint8Array(await readFile('my-definition.gh'));
+
+const io = await client.getIO(definition);
 const inputTree = TreeBuilder.fromInputParams(io.inputs);
 
-// Solve. Returns a Promise — call it as often as you like.
-const result = await scheduler.solve('my-definition.gh', inputTree);
+const result = await scheduler.solve(definition, inputTree);
 const { values } = new GrasshopperResponseProcessor(result).getValues();
 ```
 
@@ -69,128 +67,156 @@ scheduler.subscribe(() => {
 });
 ```
 
-And handle expected cancellations gracefully — when newer values supersede an
-in-flight solve, or when the user aborts:
+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.
 
-```ts
-scheduler.solve(definition, inputTree).catch((err) => {
-	if (/superseded|aborted/i.test(err.message)) return; // expected, not an error
-	showError(err);
-});
-```
+> `client.solve` throws on solver errors; `scheduler.solve` resolves with them. See [Errors](#errors).
 
 ## Configuring the scheduler
 
-The scheduler is one API with two knobs that matter — `mode` and `timeoutMs` —
-plus a couple of optional ones. Pick the row that matches what the user is
-doing in your UI:
+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: { ttlMs: 60_000 }` for instant repeats. |
-| **Submit / long-running jobs**    | `'queue'`       | `0` (no timeout) | `{ attempts: 1 }` | Serial queue. Pass a caller `signal` so users can hit Cancel. Bump proxy idle timeouts (see below).   |
-| **Background / batch parallel**   | `'parallel'`    | `60_000`         | `{ attempts: 2 }` | Fires solves concurrently up to `maxConcurrent` (default 4).                                          |
+| 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) | 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.                                  |
 
-You can create multiple schedulers from one client — typically one per UI
-surface. They share the connection pool but their queues, cancel scopes, and
-caches are independent:
+Create one scheduler per UI surface: their queues, cancel scopes and caches are independent.
 
-```ts
-const previewScheduler = client.createScheduler({ mode: 'latest-wins', timeoutMs: 30_000 });
-const submitScheduler = client.createScheduler({
-	mode: 'queue',
-	timeoutMs: 0,
-	retry: { attempts: 1 }
-});
-```
+`config.retry` covers solves. The liveness probe `GrasshopperClient.create` runs has its own
+ladder: pass `{ probe: { attempts, baseDelayMs, maxDelayMs } }` as its second argument.
+
+`scheduler.solveDetailed()` resolves `{ response, fromCache, definitionReuploaded, durationMs }`
+for that one call, and takes a per-call `onServerTiming`. Use it to record how each solve went;
+`onSettle` fires for every solve on the scheduler.
+
+Don't mutate a `Uint8Array` definition after solving it. The scheduler hashes a buffer once and
+remembers the hash by identity, so a changed buffer is served the old content's cached responses.
 
 ### Cancellation
 
-Pass a per-call `signal` to cancel just that solve, or call `cancelAll()` to
-cancel everything (e.g. on route change or component unmount):
+A superseded or cancelled solve rejects. Filter those by code:
 
 ```ts
 const ctrl = new AbortController();
-scheduler.solve(definition, tree, { signal: ctrl.signal });
+scheduler.solve(definition, inputTree, { signal: ctrl.signal }).catch((err) => {
+	if (err.code === ErrorCodes.SUPERSEDED || err.code === ErrorCodes.ABORTED) return;
+	showError(err);
+});
 
-// Later:
-ctrl.abort(); // cancel just this call
-scheduler.cancelAll(); // cancel everything in flight + pending
-scheduler.dispose(); // cancel everything and tear down the scheduler
+ctrl.abort(); // cancel this call
+scheduler.cancelAll(); // cancel everything in flight and pending, e.g. on unmount
+scheduler.dispose(); // cancel everything and tear the scheduler down
 ```
 
 ### Long jobs behind a proxy
 
-Cloudflare's default idle timeout is 100s; AWS ALB's is 60s; nginx is 60s.
-If your Compute server is behind any of them, those values must be bumped
-before you can run long solves through the browser — the library cannot work
-around proxy timeouts.
-
-For solves longer than ~2 minutes, the safer architecture is to run this
-library **server-side** behind your own job queue (BullMQ / SQS / Cloud Tasks)
+A proxy in front of Compute closes idle connections after its own timeout, and the library can't
+work around that: raise the proxy's idle timeout before running long solves from a browser. For
+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.
 
-## Requirements
+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:
 
-**Node.js >= 24.**
+```ts
+import { Agent, fetch as undiciFetch } from 'undici';
 
-The [official McNeel Rhino Compute](https://github.com/mcneel/compute.rhino3d) handles plain
-Grasshopper solving. Some features need more:
+const dispatcher = new Agent({ headersTimeout: 0, bodyTimeout: 0 });
+const client = await GrasshopperClient.create({
+	serverUrl,
+	fetch: (url, init) => undiciFetch(url, { ...init, dispatcher })
+});
+```
 
-- The [VektorNode compute fork](https://github.com/VektorNode/compute.rhino3d) adds input grouping
-  (`groupName`), persistent input ids keyed on Grasshopper object GUIDs, file export, and block
-  instance support.
-- The [Selva Rhino plugin](https://www.food4rhino.com/en/app/selva?lang=en) supplies the Display
-  and file-export components those features read.
+## Errors
 
-Anything requiring either is marked where it's documented.
+Every failure is a `ComputeError`. Branch on `err.code`, one of `ErrorCodes`, not on the message.
 
-## Troubleshooting
+`client.solve` and `scheduler.solve` differ on a response that carries Grasshopper `errors`.
+`client.solve` throws `COMPUTATION_ERROR`, with the outputs that did compute in
+`err.context.values`. `scheduler.solve` resolves with the response, so check it yourself:
 
-### `Network error: Failed to fetch`
+```ts
+import { readField } from '@selvajs/compute/core';
 
-The browser couldn't reach the server. Check, in order:
+const response = await scheduler.solve(definition, inputTree);
+// Read case-insensitively: stock Rhino Compute sends `Errors`.
+const solveErrors = readField<string[]>(response, 'errors');
+if (solveErrors?.length) showError(solveErrors.join('\n'));
+```
 
-1. **Server is running** — `curl http://localhost:6500/healthcheck` should return
-   a 200.
-2. **CORS** — if your Compute server is on a different origin than your app,
-   the server must send `Access-Control-Allow-Origin`. Standard Rhino Compute
-   does **not** ship with CORS enabled; you'll need to put it behind a proxy
-   that adds the headers, or use the [VektorNode custom branch](https://github.com/VektorNode/compute.rhino3d).
-3. **Mixed content** — an HTTPS app can't fetch from an HTTP server. Either
-   serve Compute over HTTPS or develop locally on HTTP.
-4. **API key** — you'll see the same error if your `apiKey` is missing for a
-   server that requires one (the server typically returns 401 with no CORS
-   headers, which the browser surfaces as a network error).
+## Data trees
 
-### Solves timing out before the server finishes (502 / 504 / aborted)
+`TreeBuilder.fromInputParams` builds one tree per input from its default, keyed by the input's
+**nickname**. `TreeBuilder.fromValues` builds them from your own values instead: it coerces
+Number, Integer and Boolean items, clamps numbers to `minimum`/`maximum`, and drops what it can't
+coerce, so Grasshopper keeps its own value for that input. `replaceTreeValue` is copy-on-write: it
+returns a new array and leaves yours untouched, so assign the result or the solve sends the
+defaults.
 
-A proxy in front of Compute, not the library — see [Long jobs behind a
-proxy](#long-jobs-behind-a-proxy).
+```ts
+let inputTree = TreeBuilder.fromInputParams(io.inputs);
+inputTree = TreeBuilder.replaceTreeValue(inputTree, 'Radius', 10);
+inputTree = TreeBuilder.replaceTreeValue(inputTree, 'Counts', { '{0}': [1, 2], '{0;1}': [3] });
+```
 
-### `Definition URL/content is required`
+Read outputs through `GrasshopperResponseProcessor`, or a whole tree with
+`TreeBuilder.getTree(response.values, 'Points')`: a `Map` from branch path (`'{0;1}'`) to items.
+`getTreeValue` is the shortcut for a one-branch param: it unwraps a single item and throws when
+the param has more than one branch.
 
-You called `client.solve('', tree)` or passed a `Uint8Array` of length 0.
-Validate your input before calling.
+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.
 
-### 401 vs 403
+## File outputs
 
-- **401 Unauthorized** — `apiKey` (`RhinoComputeKey` header) is missing or
-  invalid. Standard Rhino Compute uses this scheme.
-- **403 Forbidden** — your `authToken` (Bearer) was rejected by an upstream
-  proxy/API gateway. The Compute server itself almost never returns 403.
+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`.
 
-The error message includes the response body excerpt so you usually get a hint
-from the server itself.
+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:
 
-### "Superseded by newer solve" errors flooding my console
+| `Sub Folder`          | Archive      | Path in the archive      |
+| --------------------- | ------------ | ------------------------ |
+| _(empty)_             | `export.zip` | `model.3dm`              |
+| `Panels`              | `Panels.zip` | `model.3dm`              |
+| `ROOT::Panels`        | `ROOT.zip`   | `Panels/model.3dm`       |
+| `ROOT::First::Second` | `ROOT.zip`   | `First/Second/model.3dm` |
 
-The scheduler doing its job in `latest-wins` mode — every aborted slider solve rejects with this
-message. Filter it as shown in the [Quickstart](#quickstart).
+`groupFilesByRoot` returns the same grouping without the DOM, for writing files in Node.
+`processor.getAndDownloadFiles(name)` skips the split: one `name.zip`, each file at its full
+`Sub Folder` path.
 
-## Acknowledgement
+## Requirements
+
+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
+export, and block instance support. The
+[Selva Rhino plugin](https://www.food4rhino.com/en/app/selva?lang=en) supplies the Display and
+file-export components those features read.
+
+## Troubleshooting
+
+**`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
+isn't calling an HTTP server; and that the API key is set, since a 401 without CORS headers reads
+as a network error too.
 
-Where code is adapted from McNeel's repositories, it is marked in the relevant files.
+**401** means `apiKey` (the `RhinoComputeKey` header) is missing or wrong. **403** usually comes
+from a proxy or API gateway rejecting `authToken`, which is sent verbatim as the `Authorization`
+header, so include the scheme (`Bearer …`). The error message carries an excerpt of the response
+body.
+
+## Acknowledgement
 
 **Key references:**
 

package/dist/core.d.ts

@@ -1,2 +1,190 @@
-import { A as RetryPolicy, C as getLogger, D as fetchCompute, E as setResponseWireSize, F as ErrorCodes, M as ServerTiming, N as ComputeError, O as ComputeAuth, P as ErrorCode, S as enableDebugLogging, T as getResponseWireSize, _ as isDefinitionRef, a as extractFilesFromComputeResponse, b as readField, c as ProcessedFile, d as classifyProbeFailure, f as DEFAULT_BLOCKED_HOST, g as SolveDefinition, h as DefinitionRef, i as downloadFileDataByRoot, j as ServerErrorCodeMap, k as ComputeConfig, l as ProbeFailure, m as validateServerUrl, n as subFolderSegments, o as FileBaseInfo, p as ValidateServerUrlOptions, r as downloadFileData, s as FileData, t as groupFilesByRoot, u as ProbeVerdict, v as decodeBase64ToBinary, w as setLogger, x as Logger, y as hasField } from "./index-BR_XZvjj.js";
-export { type ComputeAuth, type ComputeConfig, ComputeError, DEFAULT_BLOCKED_HOST, type DefinitionRef, 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, getResponseWireSize, groupFilesByRoot, hasField, isDefinitionRef, readField, setLogger, setResponseWireSize, 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 @@
-import{C as e,S as t,_ as n,a as r,b as i,c as a,d as o,g as s,i as c,l,m as u,n as d,o as f,r as p,s as m,t as h,v as g,w as _,x as v,y}from"./core-rp3fyoca.js";export{e as ComputeError,s as DEFAULT_BLOCKED_HOST,_ as ErrorCodes,u as classifyProbeFailure,o as decodeBase64ToBinary,h as downloadFileData,d as downloadFileDataByRoot,i as enableDebugLogging,p as extractFilesFromComputeResponse,m as fetchCompute,v as getLogger,a as getResponseWireSize,c as groupFilesByRoot,g as hasField,f as isDefinitionRef,y as readField,t as setLogger,l as setResponseWireSize,r as subFolderSegments,n as validateServerUrl};
+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-D-4X4Uh_.js";