@selvajs/compute 4.2.2-beta.0 → 5.0.0-beta.10

package/dist/handle-files-D-4X4Uh_.js

@@ -0,0 +1,1379 @@
+// src/core/compute-fetch/retry.ts
+const DEFAULT_RETRY = {
+	attempts: 0,
+	baseDelayMs: 500,
+	maxDelayMs: 3e4,
+	retryOn429: true
+};
+const RETRYABLE_STATUS = /* @__PURE__ */ new Set([
+	502,
+	503,
+	504
+]);
+/**
+* Ceiling on a server-sent `Retry-After` wait. The server's window outranks
+* `RetryPolicy.maxDelayMs` (retrying sooner all but guarantees another 429), but a bad or hostile
+* header must not park the client for minutes. A `maxDelayMs` above this cap raises it.
+*/
+const RETRY_AFTER_CAP_MS = 6e4;
+function resolveRetryPolicy(policy) {
+	if (!policy) return DEFAULT_RETRY;
+	return {
+		attempts: policy.attempts ?? DEFAULT_RETRY.attempts,
+		baseDelayMs: policy.baseDelayMs ?? DEFAULT_RETRY.baseDelayMs,
+		maxDelayMs: policy.maxDelayMs ?? DEFAULT_RETRY.maxDelayMs,
+		retryOn429: policy.retryOn429 ?? DEFAULT_RETRY.retryOn429
+	};
+}
+function isRetryableStatus(status, policy) {
+	return RETRYABLE_STATUS.has(status) || policy.retryOn429 && status === 429;
+}
+/** Delay before the next attempt: the server's `Retry-After` when it sent one, else backoff. */
+function retryDelay(retryAfter, attempt, policy) {
+	const retryAfterMs = parseRetryAfter(retryAfter);
+	return retryAfterMs === null ? backoffDelay(attempt, policy) : Math.min(retryAfterMs, Math.max(policy.maxDelayMs, RETRY_AFTER_CAP_MS));
+}
+/** A `Retry-After` value (seconds or HTTP-date) in ms; null when missing or unparseable. */
+function parseRetryAfter(headerValue) {
+	if (!headerValue) return null;
+	const seconds = Number(headerValue);
+	if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+	const dateMs = Date.parse(headerValue);
+	if (Number.isFinite(dateMs)) {
+		const delta = dateMs - Date.now();
+		return delta > 0 ? delta : 0;
+	}
+	return null;
+}
+function backoffDelay(attempt, policy) {
+	const exponential = policy.baseDelayMs * Math.pow(2, attempt);
+	const jitter = Math.random() * policy.baseDelayMs;
+	return Math.min(exponential + jitter, policy.maxDelayMs);
+}
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new DOMException("Aborted", "AbortError"));
+			return;
+		}
+		const id = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(id);
+			reject(new DOMException("Aborted", "AbortError"));
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+// src/core/errors.ts
+const ErrorCodes = {
+	/** Connection failure, a gateway status (502/503/504), or a 2xx body cut off mid-stream. */
+	NETWORK_ERROR: "NETWORK_ERROR",
+	/** HTTP 401 or 403: the server rejected the credentials. */
+	AUTH_ERROR: "AUTH_ERROR",
+	/** The server rejected the request (HTTP 400, 413), or an input failed a client-side check. */
+	VALIDATION_ERROR: "VALIDATION_ERROR",
+	/** The server failed the solve (HTTP 500), or the solve reported errors. */
+	COMPUTATION_ERROR: "COMPUTATION_ERROR",
+	/** No response within `ComputeConfig.timeoutMs`. */
+	TIMEOUT_ERROR: "TIMEOUT_ERROR",
+	/** A browser fetch failed with no response: most often CORS, which the browser hides. */
+	CORS_ERROR: "CORS_ERROR",
+	/** HTTP 404: the endpoint doesn't exist on this server. Never retried. */
+	NOT_FOUND: "NOT_FOUND",
+	/** HTTP 429. Retried, honouring `Retry-After`, when the policy allows (`RetryPolicy.retryOn429`). */
+	RATE_LIMIT: "RATE_LIMIT",
+	/**
+	* A 2xx with a body the client can't use: declared non-JSON (a captive portal, a proxy login page)
+	* or JSON that isn't an object. Never retried.
+	*/
+	INVALID_RESPONSE: "INVALID_RESPONSE",
+	/**
+	* The response body passed `ComputeConfig.maxResponseBytes`; the download was cancelled there.
+	* Never retried. `context` carries `{ maxResponseBytes }`.
+	*/
+	RESPONSE_TOO_LARGE: "RESPONSE_TOO_LARGE",
+	/** Any failure not classified by another code. */
+	UNKNOWN_ERROR: "UNKNOWN_ERROR",
+	/** An object was used after `dispose()`, or a file download failed part-way. */
+	INVALID_STATE: "INVALID_STATE",
+	/** A caller-supplied argument is unusable: an empty definition, an unserializable body. */
+	INVALID_INPUT: "INVALID_INPUT",
+	/**
+	* Bad configuration: an invalid `serverUrl`, an unsendable header, an unusable number, a server
+	* that answers with a redirect, an incomplete logger, an interval out of range.
+	*/
+	INVALID_CONFIG: "INVALID_CONFIG",
+	/** A browser-only API (file download) was called outside a browser. */
+	BROWSER_ONLY: "BROWSER_ONLY",
+	/** The runtime has no base64 codec: neither `Buffer` nor `atob`/`btoa`. */
+	ENVIRONMENT_ERROR: "ENVIRONMENT_ERROR",
+	/** A string that should be base64 isn't. */
+	ENCODING_ERROR: "ENCODING_ERROR",
+	/** An input's `default` had a shape the normalizer didn't recognize. */
+	MALFORMED_DEFAULT: "MALFORMED_DEFAULT",
+	/** Latest-wins scheduling: a newer call replaced this one. */
+	SUPERSEDED: "SUPERSEDED",
+	/** The scheduler or a caller-supplied `AbortSignal` aborted this call. */
+	ABORTED: "ABORTED",
+	/**
+	* The queue was at `maxQueueDepth`, so the call was rejected without queueing. Retryable after a
+	* back-off. `context` carries `{ queueDepth, maxQueueDepth }`.
+	*/
+	QUEUE_FULL: "QUEUE_FULL",
+	/**
+	* The call waited longer than `queueWaitMs` without starting, and was rejected rather than run
+	* stale. Retryable. `context` carries `{ waitedMs, queueWaitMs }`.
+	*/
+	QUEUE_TIMEOUT: "QUEUE_TIMEOUT",
+	/**
+	* The server no longer holds the definition a `pointer` named (evicted, restarted, another
+	* child). Retry with the full definition. Read from the error body's
+	* `code: "definition_not_cached"`.
+	*/
+	DEFINITION_NOT_CACHED: "DEFINITION_NOT_CACHED"
+};
+/** Error with a typed `code`: switch on it rather than on the message. */
+var ComputeError = class extends Error {
+	code;
+	statusCode;
+	context;
+	originalError;
+	constructor(message, code = ErrorCodes.UNKNOWN_ERROR, options) {
+		const original = options?.originalError;
+		const cause = original === void 0 || original instanceof Error ? original : new Error(String(original));
+		super(message, cause && { cause });
+		this.name = "ComputeError";
+		this.code = code;
+		this.statusCode = options?.statusCode;
+		this.context = options?.context;
+		this.originalError = cause;
+	}
+};
+/** A caller's signal cancelled the work. */
+function abortedByCaller(context, originalError) {
+	return new ComputeError("Request aborted by caller", ErrorCodes.ABORTED, {
+		context,
+		originalError
+	});
+}
+// src/core/utils/logger.ts
+const silent = {
+	debug() {},
+	info() {},
+	warn() {},
+	error() {}
+};
+let internalLogger = silent;
+function getLogger() {
+	return internalLogger;
+}
+/**
+* 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);
+* ```
+*/
+function setLogger(logger) {
+	if (logger === null) {
+		internalLogger = silent;
+		return;
+	}
+	const missing = [
+		"debug",
+		"info",
+		"warn",
+		"error"
+	].filter((method) => typeof logger[method] !== "function");
+	if (missing.length > 0) throw new ComputeError(`Logger is missing required method(s): ${missing.join(", ")}. A logger must implement debug, info, warn and error.`, ErrorCodes.INVALID_CONFIG, { context: { missingMethods: missing } });
+	internalLogger = logger;
+}
+/** Shorthand for `setLogger(console)`. */
+function enableDebugLogging() {
+	setLogger(console);
+}
+// src/core/utils/read-field.ts
+/**
+* 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.
+*/
+/** Own keys only: a payload probed for `constructor` must not find `Object.prototype`'s. */
+function findOwnKey(obj, name) {
+	if (!obj || typeof obj !== "object") return void 0;
+	if (Object.hasOwn(obj, name)) return name;
+	const lower = name.toLowerCase();
+	return Object.keys(obj).find((key) => key.toLowerCase() === lower);
+}
+/**
+* Read `name` in any casing, preferring an exact-case match. `undefined` when no own key matches or
+* `obj` isn't an object.
+*/
+function readField(obj, name) {
+	const key = findOwnKey(obj, name);
+	return key === void 0 ? void 0 : obj[key];
+}
+/** Whether `name` is present in any casing, even with a null or undefined value. */
+function hasField(obj, name) {
+	return findOwnKey(obj, name) !== void 0;
+}
+// src/core/utils/redact-url.ts
+const UNREADABLE = "<unreadable URL>";
+/**
+* Only a URL with a real host can be cut safely. Anything else could hold a secret at any position:
+* `https://admin:p/ss@host` splits into a bad port and a path.
+*/
+function parseWithHost(url) {
+	try {
+		const parsed = new URL(url);
+		return parsed.host ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+/** `url` without credentials, query or fragment, for errors and logs. */
+function redactUrl(url) {
+	const parsed = parseWithHost(url);
+	if (!parsed) return UNREADABLE;
+	parsed.username = "";
+	parsed.password = "";
+	parsed.search = "";
+	parsed.hash = "";
+	return parsed.href;
+}
+/** Scheme and host alone. For a URL that was rejected, whose path can't be trusted either. */
+function redactToOrigin(url) {
+	const parsed = parseWithHost(url);
+	return parsed ? `${parsed.protocol}//${parsed.host}` : UNREADABLE;
+}
+// src/core/utils/try-parse-json.ts
+/** The parsed value, or `undefined` when `text` isn't JSON. */
+function tryParseJson(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+// src/core/server/validate-server-url.ts
+/**
+* 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.
+*/
+const DEFAULT_BLOCKED_HOST = "compute.rhino3d.com";
+/**
+* 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.
+*/
+function validateServerUrl(raw, options) {
+	const trimmed = raw?.trim() ?? "";
+	if (!trimmed) throw new ComputeError("serverUrl is required", ErrorCodes.INVALID_CONFIG, { context: { receivedServerUrl: raw } });
+	const redacted = redactToOrigin(trimmed);
+	const invalid = (reason) => new ComputeError(`Invalid serverUrl: "${redacted}". ${reason}`, ErrorCodes.INVALID_CONFIG, { context: { receivedServerUrl: redacted } });
+	if (!/^https?:\/\//i.test(trimmed)) throw invalid("Must start with \"http://\" or \"https://\". For example: \"http://localhost:6500\" or \"https://example.com\"");
+	let parsed;
+	try {
+		parsed = new URL(trimmed);
+	} catch {
+		throw invalid("Must be a valid URL.");
+	}
+	if (parsed.username !== "" || parsed.password !== "") throw invalid("Must not embed credentials (user:pass@host) — fetch rejects credentialed URLs at request time. Pass the API key separately.");
+	if (trimmed.includes("?") || trimmed.includes("#")) throw invalid("Must not contain a query string or fragment — endpoint paths are appended to this URL (e.g. \"${serverUrl}/version\"), and a \"?\" or \"#\" suffix would corrupt every request path.");
+	const hostname = trimTrailing(parsed.hostname.toLowerCase(), ".");
+	if ((options?.blockedHosts ?? ["compute.rhino3d.com"]).map((h) => trimTrailing(h.toLowerCase(), ".")).includes(hostname)) throw new ComputeError("serverUrl must be set to your Compute server URL. The shared public endpoint is not allowed.", ErrorCodes.INVALID_CONFIG, { context: { receivedServerUrl: redacted } });
+	return trimTrailing(trimmed, "/");
+}
+/** A loop, not `/x+$/`: that regex retries from every position of a long run and goes quadratic. */
+function trimTrailing(value, char) {
+	let end = value.length;
+	while (end > 0 && value[end - 1] === char) end--;
+	return value.slice(0, end);
+}
+// src/core/utils/warnings.ts
+const warned = /* @__PURE__ */ new Set();
+/** Log `message` the first time `key` is seen: what it reports doesn't change per call. */
+function warnOnce(key, message) {
+	if (warned.has(key)) return;
+	warned.add(key);
+	getLogger().warn(message);
+}
+/**
+* True only in a real browser, where an API key in the config is exposed to users. jsdom defines
+* `window` too, so Node is ruled out by `process.versions.node`, and by jsdom's user-agent marker
+* for setups that hide `process`.
+*/
+function isRealBrowser() {
+	if (typeof window === "undefined") return false;
+	if (globalThis.process?.versions?.node != null) return false;
+	const nav = globalThis.navigator;
+	const userAgent = typeof nav?.userAgent === "string" ? nav.userAgent : "";
+	if (/jsdom/i.test(userAgent)) return false;
+	return true;
+}
+function warnIfClientSide(functionName, suppress) {
+	if (suppress || !isRealBrowser()) return;
+	warnOnce(`client-side:${functionName}`, `Warning: ${functionName} is running on the client side. For better performance and security, consider running this on the server side.`);
+}
+// src/core/compute-fetch/request.ts
+/** `serverUrl` as `validateServerUrl` returns it: no trailing slash. */
+function buildUrl(endpoint, serverUrl) {
+	return `${serverUrl}/${endpoint.replace(/^\/+/, "")}`;
+}
+function isLocalhost(serverUrl) {
+	const hostname = new URL(serverUrl).hostname.toLowerCase();
+	return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+const DEFAULT_API_KEY_HEADER = "RhinoComputeKey";
+/**
+* Caller headers plus credentials. Every request to the server builds its headers here,
+* so a liveness probe authenticates exactly like the solve it gates.
+*/
+function buildAuthHeaders(auth) {
+	return assertSendable(mergeUnder(auth.headers, credentialHeaders(auth)));
+}
+function buildHeaders(requestId, config) {
+	const headers = assertSendable(mergeUnder(config.headers, {
+		...credentialHeaders(config),
+		"X-Request-ID": requestId,
+		"Content-Type": "application/json"
+	}));
+	if (!config.apiKey && !config.authToken && !isLocalhost(config.serverUrl)) warnOnce(`no-auth:${config.serverUrl}`, `[Compute] Request [${requestId}] targets remote server (${config.serverUrl}) but no API key or auth token is configured. Requests may fail or be rate-limited. (warned once per server)`);
+	return headers;
+}
+/** `headers` with a JSON `Content-Type` that replaces one of any casing already there. */
+function withJsonContentType(headers) {
+	return mergeUnder(headers, { "Content-Type": "application/json" });
+}
+function credentialHeaders(auth) {
+	return {
+		...auth.authToken && { Authorization: auth.authToken },
+		...auth.apiKey && { [auth.apiKeyHeader ?? DEFAULT_API_KEY_HEADER]: auth.apiKey }
+	};
+}
+/**
+* Header names are case-insensitive and fetch joins duplicates, so a caller key
+* matching a transport key in any case is dropped rather than sent alongside it.
+*/
+function mergeUnder(caller, transport) {
+	const taken = new Set(Object.keys(transport).map((name) => name.toLowerCase()));
+	const kept = Object.entries(caller ?? {}).filter(([name]) => !taken.has(name.toLowerCase()));
+	return {
+		...Object.fromEntries(kept),
+		...transport
+	};
+}
+/**
+* Left to fetch, a bad value becomes a retried TypeError that quotes it, and the value may be the
+* API key. `Headers` throws the same message, so its error is not kept as the cause.
+*/
+function assertSendable(headers) {
+	const check = new Headers();
+	for (const [name, value] of Object.entries(headers)) try {
+		check.set(name, value);
+	} catch {
+		throw new ComputeError(`Header "${name}" has an invalid name or value`, ErrorCodes.INVALID_CONFIG, { context: { header: name } });
+	}
+	return headers;
+}
+function generateRequestId() {
+	return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+}
+// src/core/utils/encoding.ts
+function getNodeBuffer() {
+	const buf = globalThis.Buffer;
+	return typeof buf === "function" ? buf : void 0;
+}
+function encodeStringToBase64(str) {
+	const Buffer = getNodeBuffer();
+	if (Buffer) return Buffer.from(str, "utf-8").toString("base64");
+	return base64ByteArray(new TextEncoder().encode(str));
+}
+/**
+* WHATWG forgiving-base64 normalization: strip ASCII whitespace, then drop trailing padding where
+* the spec allows it (total length a multiple of 4). `null` when the length can't be base64. Leaves
+* the alphabet check to the decoders, which make it faster than a regex over a multi-MB payload.
+*/
+function stripBase64(str) {
+	let data = str.replace(/[\t\n\f\r ]/g, "");
+	if (data.length % 4 === 0) data = data.replace(/={1,2}$/, "");
+	return data.length % 4 === 1 ? null : data;
+}
+const B64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/**
+* Whether an untyped string is base64 content: the canonical padded form when confident, else
+* `null` (treat it as plain text). A heuristic; pass a `Uint8Array` when it must be exact.
+*/
+function detectBase64Payload(str) {
+	const data = stripBase64(str);
+	if (data === null || data.length < 64) return null;
+	if (/[^A-Za-z0-9+/]/.test(data)) return null;
+	const rem = data.length % 4;
+	const lastValue = B64_ALPHABET.indexOf(data.charAt(data.length - 1));
+	if (rem === 2 && (lastValue & 15) !== 0) return null;
+	if (rem === 3 && (lastValue & 3) !== 0) return null;
+	return rem === 0 ? data : data + "==".slice(0, 4 - rem);
+}
+/**
+* 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
+*/
+function decodeBase64ToBinary(base64File) {
+	const data = stripBase64(base64File);
+	const bytes = data === null ? null : decodeStripped(data);
+	if (bytes === null) throw new ComputeError("Invalid base64 input.", ErrorCodes.ENCODING_ERROR, { context: { inputLength: base64File.length } });
+	return bytes;
+}
+/** Decode {@link stripBase64} output; `null` when a character is outside the alphabet. */
+function decodeStripped(data) {
+	const Buffer = getNodeBuffer();
+	if (Buffer) {
+		if (Buffer.byteLength(data, "utf8") !== data.length) return null;
+		if (data.includes("-") || data.includes("_")) return null;
+		const decoded = Buffer.from(data, "base64");
+		if (decoded.length !== Math.floor(data.length * 3 / 4)) return null;
+		return decoded.byteOffset === 0 && decoded.buffer.byteLength === decoded.length ? new Uint8Array(decoded.buffer, 0, decoded.length) : new Uint8Array(decoded);
+	}
+	if (typeof globalThis.atob === "function") {
+		let binary;
+		try {
+			binary = globalThis.atob(data);
+		} catch {
+			return null;
+		}
+		const bytes = new Uint8Array(binary.length);
+		for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i) & 255;
+		return bytes;
+	}
+	throw new ComputeError("Base64 decoding not supported in this environment.", ErrorCodes.ENVIRONMENT_ERROR, { context: { environmentInfo: "atob or Buffer not available" } });
+}
+/** UTF-8 byte length. Sizes every request body: `Buffer` counts without allocating the copy. */
+function utf8ByteLength(str) {
+	const Buffer = getNodeBuffer();
+	return Buffer ? Buffer.byteLength(str, "utf-8") : new TextEncoder().encode(str).length;
+}
+function base64ByteArray(bytes) {
+	const Buffer = getNodeBuffer();
+	if (Buffer) return Buffer.from(bytes).toString("base64");
+	if (typeof globalThis.btoa === "function") {
+		const CHUNK = 32766;
+		const parts = [];
+		for (let i = 0; i < bytes.length; i += CHUNK) parts.push(globalThis.btoa(String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK))));
+		return parts.join("");
+	}
+	throw new ComputeError("Base64 encoding not supported in this environment.", ErrorCodes.ENVIRONMENT_ERROR, { context: { environmentInfo: "btoa or Buffer not available" } });
+}
+// src/core/compute-fetch/read-body.ts
+/**
+* Cap on an error body: it is read for its `code` and message only. A 500 is read in full instead,
+* since a partial success carries the computed values.
+*/
+const ERROR_BODY_MAX_BYTES = 1 << 20;
+/** Read a body as text, cancelling the download once it passes `limit` UTF-8 bytes. */
+async function readBodyText(response, limit = Infinity) {
+	if (limit === Infinity) return {
+		text: await response.text(),
+		truncated: false
+	};
+	if (!response.body) {
+		const text = await response.text();
+		return {
+			text,
+			truncated: utf8ByteLength(text) > limit
+		};
+	}
+	const declared = Number(response.headers.get("Content-Length"));
+	if (!response.headers.has("Content-Encoding") && declared > limit) {
+		await response.body.cancel().catch(() => {});
+		return {
+			text: "",
+			truncated: true
+		};
+	}
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	const parts = [];
+	let received = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		received += value.byteLength;
+		parts.push(decoder.decode(value, { stream: true }));
+		if (received > limit) {
+			await reader.cancel().catch(() => {});
+			return {
+				text: parts.join(""),
+				truncated: true
+			};
+		}
+	}
+	parts.push(decoder.decode());
+	return {
+		text: parts.join(""),
+		truncated: false
+	};
+}
+// src/core/compute-fetch/server-timing.ts
+/**
+* Parse a W3C Server Timing header, as the solve endpoint emits it:
+* `decode;dur=3, solve;dur=120, gh;dur=110, encode;dur=8, recomputed;desc="4/97"`, or
+* `cache;desc="hit"` when the server answered from its result cache. Null when it carries no
+* recognised metric.
+*/
+function parseServerTiming(headerValue) {
+	if (!headerValue) return null;
+	const timing = { raw: headerValue };
+	let sawMetric = false;
+	for (const part of headerValue.split(",")) {
+		const [rawName, ...params] = part.trim().split(";");
+		const name = rawName.trim().toLowerCase();
+		if (name === "decode" || name === "solve" || name === "encode" || name === "gh") {
+			const dur = Number(param(params, "dur"));
+			if (!Number.isFinite(dur)) continue;
+			timing[name] = dur;
+			sawMetric = true;
+		} else if (name === "recomputed") {
+			const [ran, total] = (param(params, "desc") ?? "").split("/").map(Number);
+			if (!Number.isInteger(ran) || !Number.isInteger(total)) continue;
+			timing.recomputed = {
+				ran,
+				total
+			};
+			sawMetric = true;
+		} else if (name === "cache" && param(params, "desc") === "hit") {
+			timing.cacheHit = true;
+			sawMetric = true;
+		}
+	}
+	return sawMetric ? timing : null;
+}
+function param(params, key) {
+	for (const p of params) {
+		const [k, ...v] = p.split("=");
+		if (k.trim().toLowerCase() !== key) continue;
+		return v.join("=").trim().replace(/^"(.*)"$/, "$1");
+	}
+}
+function fireServerTiming(response, requestId, onServerTiming) {
+	if (!onServerTiming) return;
+	const timing = parseServerTiming(response.headers.get("Server-Timing"));
+	if (!timing) return;
+	try {
+		onServerTiming(timing, requestId);
+	} catch (err) {
+		getLogger().debug(`onServerTiming callback threw ${err instanceof Error ? err.name : typeof err}`);
+	}
+}
+// src/core/compute-fetch/signal.ts
+/** What fetch, or a body read, rejects with when its signal fires: a caller abort or a timeout. */
+function isAbortError(error) {
+	return error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
+}
+/** The most `AbortSignal.timeout` takes on Node, which wants a whole uint32. */
+const MAX_TIMEOUT_MS = 2 ** 32 - 1;
+/** `promise`'s outcome, or a rejection with `signal`'s reason if that fires first. */
+function raceSignal(promise, signal) {
+	if (!signal) return promise;
+	return new Promise((resolve, reject) => {
+		const onAbort = () => reject(signal.reason);
+		if (signal.aborted) onAbort();
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+	});
+}
+/**
+* Compose a caller-supplied AbortSignal with an optional timeout; `undefined` when neither was
+* given. `AbortSignal.timeout` rather than `setTimeout`: its timer isn't throttled in a hidden tab.
+*/
+function composeSignal(callerSignal, timeoutMs) {
+	const noCleanup = () => {};
+	if (typeof timeoutMs !== "number" || timeoutMs <= 0) return {
+		signal: callerSignal,
+		cleanup: noCleanup
+	};
+	const timeoutSignal = AbortSignal.timeout(Math.floor(timeoutMs));
+	if (!callerSignal) return {
+		signal: timeoutSignal,
+		cleanup: noCleanup
+	};
+	const ctrl = new AbortController();
+	const sources = [callerSignal, timeoutSignal];
+	const onAbort = function() {
+		ctrl.abort(this.reason);
+	};
+	for (const s of sources) {
+		if (s.aborted) {
+			ctrl.abort(s.reason);
+			break;
+		}
+		s.addEventListener("abort", onAbort, { once: true });
+	}
+	return {
+		signal: ctrl.signal,
+		cleanup: () => {
+			for (const s of sources) s.removeEventListener("abort", onAbort);
+		}
+	};
+}
+// src/core/compute-fetch/wire-size.ts
+/**
+* A response's JSON text length, so byte-budgeted caches never re-serialize a huge tree. A WeakMap
+* rather than a field keeps `JSON.stringify(response)` clean; it is keyed by identity, so a derived
+* copy must re-register. `.length` stands in for UTF-8 bytes: the JSON is near-pure ASCII.
+*/
+const wireSizes = /* @__PURE__ */ new WeakMap();
+/** Record `response`'s wire size. No-op for non-object/null values. */
+function setResponseWireSize(response, size) {
+	if (typeof response !== "object" || response === null) return;
+	wireSizes.set(response, size);
+}
+/** The wire size recorded for `response`, or undefined when never registered. */
+function getResponseWireSize(response) {
+	if (typeof response !== "object" || response === null) return void 0;
+	return wireSizes.get(response);
+}
+// src/core/compute-fetch/response.ts
+/** Upper bound for the raw server body stored on error `context.responseBody`. */
+const MAX_CONTEXT_BODY_CHARS = 4096;
+/** An allowlist: errors reach logs and telemetry, and `Set-Cookie` or a proxy's token must not. */
+const CONTEXT_HEADERS = [
+	"content-length",
+	"content-type",
+	"retry-after",
+	"server-timing",
+	"www-authenticate",
+	"x-request-id"
+];
+function truncateBody(body) {
+	if (body.length <= MAX_CONTEXT_BODY_CHARS) return body;
+	return `${body.slice(0, MAX_CONTEXT_BODY_CHARS)}… [truncated ${body.length - MAX_CONTEXT_BODY_CHARS} chars]`;
+}
+function contextHeaders(headers) {
+	const kept = {};
+	for (const name of CONTEXT_HEADERS) {
+		const value = headers.get(name);
+		if (value !== null) kept[name] = value;
+	}
+	return kept;
+}
+const plainMessage = ({ status, statusText, bodyHint }) => `HTTP ${status}: ${statusText}${bodyHint}`;
+const labelled = (label) => ({ statusText, bodyHint }) => `${label}: ${statusText}${bodyHint}`;
+const STATUS_RULES = {
+	400: {
+		code: ErrorCodes.VALIDATION_ERROR,
+		message: labelled("Bad request")
+	},
+	401: { code: ErrorCodes.AUTH_ERROR },
+	403: { code: ErrorCodes.AUTH_ERROR },
+	404: {
+		code: ErrorCodes.NOT_FOUND,
+		message: ({ fullUrl }) => `Endpoint not found: ${fullUrl}`
+	},
+	413: {
+		code: ErrorCodes.VALIDATION_ERROR,
+		message: ({ requestSize }) => `Request too large: ${(requestSize / 1024).toFixed(2)}KB`
+	},
+	429: {
+		code: ErrorCodes.RATE_LIMIT,
+		message: ({ bodyHint }) => `Rate limit exceeded${bodyHint}`
+	},
+	500: {
+		code: ErrorCodes.COMPUTATION_ERROR,
+		message: labelled("Server error")
+	},
+	502: {
+		code: ErrorCodes.NETWORK_ERROR,
+		message: labelled("Bad gateway")
+	},
+	503: {
+		code: ErrorCodes.NETWORK_ERROR,
+		message: labelled("Service unavailable")
+	},
+	504: {
+		code: ErrorCodes.NETWORK_ERROR,
+		message: labelled("Gateway timeout")
+	}
+};
+/**
+* `rawBody` is what came over the wire and goes on `context.responseBody`; `detail` may be a
+* message rewritten from it and only feeds the error message.
+*/
+function throwHttpError(response, ctx, rawBody, detail, serverCode) {
+	const { status, statusText } = response;
+	const { fullUrl, requestId, requestSize, config } = ctx;
+	const trimmed = detail.trim();
+	const bodyHint = trimmed ? ` — ${trimmed.slice(0, 200)}${trimmed.length > 200 ? "…" : ""}` : "";
+	const rule = STATUS_RULES[status] ?? { code: ErrorCodes.UNKNOWN_ERROR };
+	const message = (rule.message ?? plainMessage)({
+		status,
+		statusText,
+		bodyHint,
+		fullUrl,
+		requestSize
+	});
+	const codes = config.serverErrorCodes;
+	throw new ComputeError(message, (serverCode && codes && Object.hasOwn(codes, serverCode) ? codes[serverCode] : void 0) ?? rule.code, {
+		statusCode: status,
+		context: {
+			url: fullUrl,
+			requestId,
+			method: "POST",
+			requestSize,
+			serverUrl: config.serverUrl,
+			responseBody: rawBody ? truncateBody(rawBody) : void 0,
+			responseHeaders: contextHeaders(response.headers)
+		}
+	});
+}
+/** A 3xx, or a browser's `redirect: 'manual'` stand-in for one, which hides the status. */
+function isRedirect(response) {
+	return response.type === "opaqueredirect" || response.status >= 300 && response.status < 400;
+}
+/** Following a redirect would send the API key header, which fetch keeps cross-origin, to the target. */
+function redirectError(response, ctx) {
+	const header = response.headers.get("Location");
+	const location = header ? redactUrl(header) : void 0;
+	return new ComputeError(`Server redirected the request${location ? ` to ${location}` : ""}. Redirects are not followed, so credentials never leave serverUrl: set serverUrl to the address it redirects to.`, ErrorCodes.INVALID_CONFIG, {
+		...response.status > 0 && { statusCode: response.status },
+		context: {
+			url: ctx.fullUrl,
+			requestId: ctx.requestId,
+			location
+		}
+	});
+}
+function tooLargeError(response, ctx) {
+	const { maxResponseBytes } = ctx.config;
+	return new ComputeError(`Response body exceeded maxResponseBytes (${maxResponseBytes} bytes)`, ErrorCodes.RESPONSE_TOO_LARGE, {
+		statusCode: response.status,
+		context: {
+			url: ctx.fullUrl,
+			requestId: ctx.requestId,
+			maxResponseBytes
+		}
+	});
+}
+/** Sizes and identifiers only: bodies and solver messages can hold user data. */
+function logDebug(ctx, message) {
+	if (ctx.config.debug) getLogger().debug(`Request [${ctx.requestId}] ${message}`);
+}
+/** Values plus errors or warnings: the solve ran, so this 500 is a partial success. */
+function partialSuccessCounts(parsed) {
+	const solveErrors = readField(parsed, "errors");
+	const solveWarnings = readField(parsed, "warnings");
+	if (!readField(parsed, "values") || !(solveErrors || solveWarnings)) return null;
+	return {
+		errors: solveErrors?.length ?? 0,
+		warnings: solveWarnings?.length ?? 0
+	};
+}
+/**
+* Compute8's exception handler sends `{ error, message: "<category>: <detail>", stackTrace? }`;
+* older servers sent PascalCase `Message`/`ExceptionType`/`StackTrace`.
+*/
+function serverErrorDetail(parsed) {
+	const serverMessage = typeof parsed?.message === "string" && parsed.message || typeof parsed?.Message === "string" && parsed.Message || "";
+	if (serverMessage) {
+		const exceptionType = typeof parsed?.ExceptionType === "string" && parsed.ExceptionType || "";
+		const prefix = exceptionType ? `${exceptionType}: ` : "";
+		const stack = parsed?.stackTrace ?? parsed?.StackTrace;
+		const stackStr = Array.isArray(stack) ? stack.join("\n") : stack || "";
+		return `${prefix}${serverMessage}${stackStr ? `\n${stackStr}` : ""}`;
+	}
+	if (parsed?.error) return typeof parsed.error === "string" ? parsed.error : JSON.stringify(parsed.error, null, 2);
+}
+async function handleErrorStatus(response, ctx, responseTime) {
+	const { maxResponseBytes = Infinity, onServerTiming } = ctx.config;
+	const isServerError = response.status === 500;
+	const { text: rawBody, truncated } = await readBodyText(response, isServerError ? maxResponseBytes : Math.min(ERROR_BODY_MAX_BYTES, maxResponseBytes));
+	if (truncated && isServerError) throw tooLargeError(response, ctx);
+	logDebug(ctx, `failed with HTTP ${response.status} in ${responseTime}ms (${rawBody.length} chars)`);
+	const parsed = truncated ? void 0 : tryParseJson(rawBody);
+	let detail = rawBody;
+	if (parsed !== void 0) {
+		const partial = isServerError ? partialSuccessCounts(parsed) : null;
+		if (partial) {
+			setResponseWireSize(parsed, rawBody.length);
+			logDebug(ctx, `completed in ${responseTime}ms with ${partial.errors} solver error(s), ${partial.warnings} warning(s)`);
+			fireServerTiming(response, ctx.requestId, onServerTiming);
+			return {
+				ok: true,
+				value: parsed
+			};
+		}
+		detail = serverErrorDetail(parsed) ?? rawBody;
+	}
+	const code = parsed?.code;
+	throwHttpError(response, ctx, rawBody, detail, typeof code === "string" ? code : void 0);
+}
+async function parseSuccessBody(response, ctx) {
+	const { maxResponseBytes = Infinity, signal } = ctx.config;
+	try {
+		const { text: rawBody, truncated } = await readBodyText(response, maxResponseBytes);
+		if (truncated) throw tooLargeError(response, ctx);
+		const parsed = JSON.parse(rawBody);
+		setResponseWireSize(parsed, rawBody.length);
+		return {
+			ok: true,
+			value: parsed
+		};
+	} catch (error) {
+		if (signal?.aborted || isAbortError(error) || error instanceof ComputeError) throw error;
+		const contentType = (response.headers.get("Content-Type") ?? "").toLowerCase();
+		if (contentType !== "" && !contentType.includes("json")) throw new ComputeError(`Server returned a non-JSON response (Content-Type: ${contentType}) — check the server URL / proxy configuration`, ErrorCodes.INVALID_RESPONSE, {
+			statusCode: response.status,
+			context: {
+				url: ctx.fullUrl,
+				requestId: ctx.requestId,
+				contentType
+			},
+			originalError: error
+		});
+		return {
+			ok: false,
+			retryable: true,
+			cause: new ComputeError("Failed to parse JSON response", ErrorCodes.NETWORK_ERROR, {
+				statusCode: response.status,
+				context: {
+					url: ctx.fullUrl,
+					requestId: ctx.requestId
+				},
+				originalError: error
+			})
+		};
+	}
+}
+/** Throws a {@link ComputeError} for anything a retry can't fix. */
+async function handleResponse(response, ctx, startTime) {
+	const responseTime = Math.round(performance.now() - startTime);
+	if (isRedirect(response)) {
+		await response.body?.cancel().catch(() => {});
+		throw redirectError(response, ctx);
+	}
+	if (!response.ok) return handleErrorStatus(response, ctx, responseTime);
+	logDebug(ctx, `completed in ${responseTime}ms`);
+	fireServerTiming(response, ctx.requestId, ctx.config.onServerTiming);
+	return parseSuccessBody(response, ctx);
+}
+// src/core/server/classify-probe-failure.ts
+/**
+* Matched against the probe's error string, which `probeServer` builds with undici's `cause` in
+* it. A browser collapses every failure into an opaque "Failed to fetch", which reads as unknown.
+*/
+const REFUSED_PATTERN = /ECONNREFUSED|ERR_CONNECTION_REFUSED|connection refused/i;
+const DNS_PATTERN = /ENOTFOUND|EAI_AGAIN|getaddrinfo|ERR_NAME_NOT_RESOLVED|dns/i;
+const TIMEOUT_PATTERN = /TimeoutError|ETIMEDOUT|ECONNRESET|EHOSTUNREACH|ENETUNREACH|abort|timed? ?out/i;
+/**
+* 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`.
+*/
+function classifyProbeFailure(probe) {
+	if (probe.online) return null;
+	if (probe.status !== void 0) {
+		if (probe.status === 401 || probe.status === 403) return {
+			verdict: "unauthorized",
+			retryable: false,
+			summary: `The server rejected the liveness probe with HTTP ${probe.status} — check the API key.`
+		};
+		const retryable = probe.status >= 500;
+		return {
+			verdict: "http_error",
+			retryable,
+			summary: retryable ? `The server answered HTTP ${probe.status} — it may still be starting up.` : `The server answered HTTP ${probe.status}, which will not change on retry.`
+		};
+	}
+	const error = probe.error ?? "";
+	if (REFUSED_PATTERN.test(error)) return {
+		verdict: "refused",
+		retryable: false,
+		summary: "Connection refused — the host is reachable but nothing is listening on that port. Rhino.Compute is not running, or the URL names the wrong port."
+	};
+	if (DNS_PATTERN.test(error)) return {
+		verdict: "dns",
+		retryable: true,
+		summary: "The server hostname could not be resolved — check the URL and DNS."
+	};
+	if (TIMEOUT_PATTERN.test(error)) return {
+		verdict: "timeout",
+		retryable: true,
+		summary: "No response before the timeout — the machine may be powered off, blocked by a firewall, or still booting."
+	};
+	return {
+		verdict: "unknown",
+		retryable: true,
+		summary: error ? `The connection failed: ${error}` : "The connection failed."
+	};
+}
+// src/core/compute-fetch/request-compression.ts
+/**
+* Gzip request bodies, but only for a server that advertised it: its last response carried
+* `Accept-Encoding: gzip` (RFC 7694), as Rhino.Compute does with `RHINO_COMPUTE_COMPRESSION` on.
+* An older server reads a gzipped body as malformed JSON. A response without the header forgets
+* the server, so one failed request recovers from compression being turned off. Browsers only
+* learn it same-origin: CORS hides the header otherwise.
+*/
+const gzipServers = /* @__PURE__ */ new Set();
+function noteRequestEncodings(serverUrl, response) {
+	const accepted = response.headers?.get("Accept-Encoding");
+	if (accepted && /(^|[\s,])gzip($|[\s,;])/i.test(accepted)) gzipServers.add(serverUrl);
+	else gzipServers.delete(serverUrl);
+}
+/** Synchronous, so an uncompressed request reaches fetch in the same tick as before. */
+function shouldGzipRequest(serverUrl, byteLength) {
+	return byteLength >= 1024 && gzipServers.has(serverUrl) && typeof CompressionStream !== "undefined";
+}
+async function gzip(body) {
+	const stream = new Blob([body]).stream().pipeThrough(new CompressionStream("gzip"));
+	return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+// src/core/compute-fetch/compute-fetch.ts
+async function attemptFetch(ctx, policy, attempt, isFinal) {
+	const { signal, cleanup } = composeSignal(ctx.config.signal, ctx.config.timeoutMs);
+	const startTime = performance.now();
+	const send = ctx.config.fetch ?? fetch;
+	try {
+		const gzipped = shouldGzipRequest(ctx.serverUrl, ctx.requestSize) ? await gzip(ctx.body) : null;
+		const response = await send(ctx.fullUrl, {
+			method: "POST",
+			body: gzipped ?? ctx.body,
+			headers: gzipped ? {
+				...ctx.headers,
+				"Content-Encoding": "gzip"
+			} : ctx.headers,
+			signal,
+			redirect: "manual"
+		});
+		noteRequestEncodings(ctx.serverUrl, response);
+		if (!isFinal && isRetryableStatus(response.status, policy)) {
+			await readBodyText(response, ERROR_BODY_MAX_BYTES).catch(() => {});
+			return {
+				ok: false,
+				retryable: true,
+				delayMs: retryDelay(response.headers.get("Retry-After"), attempt, policy),
+				cause: new ComputeError(`HTTP ${response.status} ${response.statusText} (will retry)`, response.status === 429 ? ErrorCodes.RATE_LIMIT : ErrorCodes.NETWORK_ERROR, {
+					statusCode: response.status,
+					context: ctx.errorContext
+				})
+			};
+		}
+		return await handleResponse(response, ctx, startTime);
+	} catch (error) {
+		return classifyFetchError(error, ctx);
+	} finally {
+		cleanup();
+	}
+}
+function classifyFetchError(error, ctx) {
+	if (error instanceof ComputeError) return {
+		ok: false,
+		retryable: false,
+		cause: error
+	};
+	if (ctx.config.signal?.aborted) return {
+		ok: false,
+		retryable: false,
+		cause: abortedByCaller(ctx.errorContext, error)
+	};
+	if (isAbortError(error)) {
+		const { timeoutMs } = ctx.config;
+		return {
+			ok: false,
+			retryable: true,
+			cause: typeof timeoutMs === "number" && timeoutMs > 0 ? new ComputeError(`Request timed out after ${timeoutMs}ms`, ErrorCodes.TIMEOUT_ERROR, {
+				context: {
+					...ctx.errorContext,
+					timeoutMs
+				},
+				originalError: error
+			}) : new ComputeError(`Request aborted by the runtime (${error.name}): ${error.message}`, ErrorCodes.NETWORK_ERROR, {
+				context: ctx.errorContext,
+				originalError: error
+			})
+		};
+	}
+	if (error instanceof TypeError) return {
+		ok: false,
+		retryable: true,
+		cause: typeof window !== "undefined" && typeof window.document !== "undefined" ? new ComputeError(`Request failed: ${error.message} — in a browser this usually means a CORS misconfiguration on the server (or a network failure; the browser does not distinguish them)`, ErrorCodes.CORS_ERROR, {
+			context: ctx.errorContext,
+			originalError: error
+		}) : new ComputeError(`Network error: ${error.message}`, ErrorCodes.NETWORK_ERROR, {
+			context: ctx.errorContext,
+			originalError: error
+		})
+	};
+	return {
+		ok: false,
+		retryable: false,
+		cause: new ComputeError(error instanceof Error ? error.message : String(error), ErrorCodes.UNKNOWN_ERROR, {
+			context: ctx.errorContext,
+			originalError: error
+		})
+	};
+}
+function requireNumber(name, value, isValid) {
+	if (value !== void 0 && !isValid(value)) throw new ComputeError(`${name} is not usable: ${value}`, ErrorCodes.INVALID_CONFIG, { context: { [name]: value } });
+}
+/** `NaN` fails every comparison, so unchecked it disables a loop's exit or a limit. */
+function validateNumbers({ timeoutMs, maxResponseBytes, retry }) {
+	const notNegative = (n) => n >= 0;
+	requireNumber("timeoutMs", timeoutMs, (n) => n <= MAX_TIMEOUT_MS);
+	requireNumber("maxResponseBytes", maxResponseBytes, notNegative);
+	requireNumber("retry.attempts", retry?.attempts, (n) => notNegative(n) && Number.isFinite(n));
+	requireNumber("retry.baseDelayMs", retry?.baseDelayMs, notNegative);
+	requireNumber("retry.maxDelayMs", retry?.maxDelayMs, notNegative);
+}
+/**
+* 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
+* });
+*/
+async function fetchCompute(endpoint, args, config) {
+	const requestId = generateRequestId();
+	let body;
+	try {
+		body = JSON.stringify(args);
+	} catch (error) {
+		throw new ComputeError(`Request body is not JSON-serializable: ${error instanceof Error ? error.message : String(error)}`, ErrorCodes.INVALID_INPUT, {
+			context: {
+				endpoint,
+				requestId
+			},
+			originalError: error
+		});
+	}
+	const requestSize = utf8ByteLength(body);
+	const serverUrl = validateServerUrl(config.serverUrl, { blockedHosts: [] });
+	validateNumbers(config);
+	const fullUrl = buildUrl(endpoint, serverUrl);
+	const headers = buildHeaders(requestId, config);
+	const retryPolicy = resolveRetryPolicy(config.retry);
+	const totalAttempts = retryPolicy.attempts + 1;
+	if (config.debug) {
+		const sizeKb = (requestSize / 1024).toFixed(2);
+		getLogger().debug(`Starting compute request [${requestId}]: ${endpoint} (${sizeKb}KB)`);
+	}
+	const ctx = {
+		endpoint,
+		serverUrl,
+		body,
+		requestSize,
+		fullUrl,
+		requestId,
+		headers,
+		config,
+		errorContext: {
+			serverUrl,
+			url: fullUrl,
+			endpoint,
+			requestId,
+			requestSize
+		}
+	};
+	for (let attempt = 0;; attempt++) {
+		const isFinal = attempt >= retryPolicy.attempts;
+		const result = await attemptFetch(ctx, retryPolicy, attempt, isFinal);
+		if (result.ok) return result.value;
+		if (isFinal || !result.retryable) throw result.cause;
+		const delayMs = result.delayMs ?? backoffDelay(attempt, retryPolicy);
+		if (config.debug) getLogger().debug(`Request [${requestId}] retrying after ${delayMs}ms (attempt ${attempt + 2}/${totalAttempts}): ${result.cause.code}`);
+		try {
+			await sleep(delayMs, config.signal);
+		} catch {
+			throw abortedByCaller(ctx.errorContext, result.cause);
+		}
+	}
+}
+// src/core/definition-ref.ts
+function isDefinitionRef(definition) {
+	return typeof definition === "object" && !(definition instanceof Uint8Array) && typeof definition.key === "string" && typeof definition.load === "function";
+}
+/** A URL is already a server-side reference: it is never uploaded or keyed by server cache key. */
+function isDefinitionUrl(definition) {
+	return typeof definition === "string" && /^https?:\/\//i.test(definition);
+}
+// src/core/files/sub-folder.ts
+/**
+* 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.
+*/
+const subFolderSegments = (subFolder) => (subFolder ?? "").replace(/::/g, "/").replace(/\\/g, "/").split("/").map((segment) => segment.trim()).filter((segment) => segment !== "");
+/** First `Sub Folder` segment, or `''` when the file sits at the top level. */
+const rootOf = (file) => subFolderSegments(file.subFolder)[0] ?? "";
+/**
+* Everything below the root, as a `/`-joined path. The root names the archive, so repeating it
+* inside would nest it twice.
+*/
+const pathBelowRoot = (file) => subFolderSegments(file.subFolder).slice(1).join("/");
+/**
+* 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.
+*/
+const groupFilesByRoot = (files) => {
+	const groups = /* @__PURE__ */ new Map();
+	for (const file of files) {
+		const root = rootOf(file);
+		const bucket = groups.get(root);
+		if (bucket) bucket.push(file);
+		else groups.set(root, [file]);
+	}
+	return Array.from(groups, ([root, grouped]) => ({
+		root,
+		files: grouped
+	}));
+};
+/**
+* Make a root usable as a download filename: path separators and the characters Windows forbids
+* would otherwise reach the download attribute verbatim and produce a broken or misdirected save.
+*/
+const toArchiveName = (root) => {
+	const safe = root.replace(/[/\\:*?"<>|]/g, "_").replace(/\s+/g, " ").trim().replace(/^\.+/, "");
+	return safe === "" ? "files" : safe;
+};
+// src/core/files/handle-files.ts
+/**
+* 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.
+*/
+const extractFilesFromComputeResponse = async (downloadableFiles, additionalFiles = null) => {
+	const processedFiles = decodeResponseFiles(downloadableFiles);
+	if (additionalFiles) {
+		const filesArray = Array.isArray(additionalFiles) ? additionalFiles : [additionalFiles];
+		processedFiles.push(...await fetchRemoteFiles(filesArray));
+	}
+	const taken = /* @__PURE__ */ new Set();
+	return processedFiles.map((file) => {
+		const path = uniqueArchivePath(file.path, taken);
+		taken.add(path);
+		if (path === file.path) return file;
+		getLogger().warn(`Duplicate archive path "${file.path}" — storing as "${path}".`);
+		return {
+			...file,
+			path,
+			fileName: path.slice(path.lastIndexOf("/") + 1)
+		};
+	});
+};
+/** Downloads files from a compute response as a ZIP archive. */
+const downloadFileData = async (downloadableFiles, fileFoldername, additionalFiles = null, options = {}) => {
+	if (typeof document === "undefined" || typeof Blob === "undefined") throw new ComputeError("File download functionality is only available in browser environments. This function requires the DOM API (document, Blob).", ErrorCodes.BROWSER_ONLY, { context: {
+		environment: typeof window !== "undefined" ? "browser (SSR)" : "Node.js",
+		documentAvailable: typeof document !== "undefined",
+		blobAvailable: typeof Blob !== "undefined"
+	} });
+	try {
+		await createAndDownloadZip(await extractFilesFromComputeResponse(downloadableFiles, additionalFiles), fileFoldername, options.saveBlob ?? saveFile);
+	} catch (err) {
+		if (err instanceof ComputeError) throw err;
+		throw new ComputeError("Failed to download files from compute response", ErrorCodes.INVALID_STATE, {
+			context: {
+				fileCount: downloadableFiles.length,
+				zipName: fileFoldername
+			},
+			originalError: err
+		});
+	}
+};
+/**
+* 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.
+*/
+const downloadFileDataByRoot = async (downloadableFiles, fallbackName, additionalFiles = null, options = {}) => {
+	const groups = groupFilesByRoot(downloadableFiles);
+	if (groups.length === 0) {
+		await downloadFileData([], fallbackName, additionalFiles, options);
+		return;
+	}
+	const extrasRoot = (groups.find((group) => group.root === "") ?? groups[0]).root;
+	for (const { root, files } of groups) await downloadFileData(root === "" ? files : files.map((file) => ({
+		...file,
+		subFolder: pathBelowRoot(file)
+	})), root === "" ? fallbackName : toArchiveName(root), root === extrasRoot ? additionalFiles : null, options);
+};
+/**
+* Zip-slip defense for a server-controlled path: drop `.`, `..` and drive-prefixed segments
+* (`C:`, and `C:evil`, which is relative to that drive's working directory) so no entry escapes
+* the extraction directory. `''` when nothing safe remains.
+*/
+const sanitizeArchivePath = (raw) => subFolderSegments(raw).filter((segment) => segment !== "." && segment !== ".." && !/^[a-zA-Z]:/.test(segment)).join("/");
+/** The `isBase64Encoded` wire flag. Some server branches send booleans as strings (`"True"`). */
+const isBase64Flag = (flag) => flag === true || typeof flag === "string" && flag.trim().toLowerCase() === "true";
+const joinArchivePath = (subFolder, name) => subFolder !== "" ? `${subFolder}/${name}` : name;
+const decodeResponseFiles = (dataItems) => {
+	const processedFiles = [];
+	dataItems.forEach((item) => {
+		const rawName = readField(item, "fileName") ?? "";
+		const rawType = readField(item, "fileType") ?? "";
+		const fileName = sanitizeArchivePath(`${rawName}${rawType}`);
+		if (fileName === "") {
+			getLogger().warn(`Skipping file with unusable name "${rawName}${rawType}": no safe archive path remains after sanitization.`);
+			return;
+		}
+		const rawSubFolder = readField(item, "subFolder");
+		const subFolder = rawSubFolder ? sanitizeArchivePath(rawSubFolder) : "";
+		const filePath = joinArchivePath(subFolder, fileName);
+		const data = readField(item, "data");
+		if (typeof data !== "string" || data === "") {
+			getLogger().warn(`Skipping file "${filePath}": item carries no usable data.`);
+			return;
+		}
+		let content = data;
+		if (isBase64Flag(readField(item, "isBase64Encoded"))) try {
+			content = decodeBase64ToBinary(data);
+		} catch (err) {
+			getLogger().warn(`Skipping file "${filePath}": base64 decode failed.`, err);
+			return;
+		}
+		const metadata = readField(item, "metadata");
+		processedFiles.push({
+			fileName,
+			content,
+			path: filePath,
+			subFolder,
+			...metadata ? { metadata } : {}
+		});
+	});
+	return processedFiles;
+};
+/** One dead URL must degrade the batch, not stall it forever. */
+const REMOTE_FILE_TIMEOUT_MS = 3e4;
+const fetchRemoteFiles = async (refs) => {
+	return (await Promise.all(refs.map(async (file) => {
+		try {
+			const response = await fetch(file.filePath, { signal: AbortSignal.timeout(REMOTE_FILE_TIMEOUT_MS) });
+			if (!response.ok) {
+				getLogger().warn(`Failed to fetch additional file: ${redactUrl(file.filePath)}`);
+				return null;
+			}
+			const arrayBuffer = await response.arrayBuffer();
+			const safeName = sanitizeArchivePath(file.fileName);
+			if (safeName === "") {
+				getLogger().warn(`Skipping fetched file with unusable name: ${file.fileName}`);
+				return null;
+			}
+			const subFolder = file.subFolder ? sanitizeArchivePath(file.subFolder) : "";
+			return {
+				fileName: safeName,
+				content: new Uint8Array(arrayBuffer),
+				path: joinArchivePath(subFolder, safeName),
+				subFolder
+			};
+		} catch (error) {
+			const reason = error instanceof Error ? error.name : "unknown error";
+			getLogger().error(`Error fetching additional file ${redactUrl(file.filePath)}: ${reason}`);
+			return null;
+		}
+	}))).filter((f) => f !== null);
+};
+async function createAndDownloadZip(files, zipName, save) {
+	const { zip, strToU8 } = await import("fflate");
+	const taken = new Set(files.map((file) => file.path));
+	const zipData = {};
+	for (const file of files) {
+		const path = file.path === "__proto__" ? uniqueArchivePath(file.path, taken) : file.path;
+		taken.add(path);
+		zipData[path] = typeof file.content === "string" ? strToU8(file.content) : file.content;
+	}
+	const zipped = await new Promise((resolve, reject) => {
+		zip(zipData, { level: 6 }, (err, data) => err ? reject(err) : resolve(data));
+	});
+	await save(new Blob([zipped], { type: "application/zip" }), `${zipName}.zip`);
+}
+/**
+* First archive path not already taken in `taken`, disambiguating with a
+* numeric suffix before the extension: `dir/model.txt` → `dir/model-2.txt`.
+*/
+function uniqueArchivePath(path, taken) {
+	if (!taken.has(path)) return path;
+	const slash = path.lastIndexOf("/");
+	const dot = path.lastIndexOf(".");
+	const stemEnd = dot > slash ? dot : path.length;
+	const stem = path.slice(0, stemEnd);
+	const ext = path.slice(stemEnd);
+	for (let i = 2;; i++) {
+		const candidate = `${stem}-${i}${ext}`;
+		if (!taken.has(candidate)) return candidate;
+	}
+}
+function saveFile(blob, filename) {
+	const url = URL.createObjectURL(blob);
+	const a = document.createElement("a");
+	a.href = url;
+	a.download = filename;
+	document.body.appendChild(a);
+	a.click();
+	a.remove();
+	setTimeout(() => URL.revokeObjectURL(url), 1e4);
+}
+export { readField as A, withJsonContentType as C, tryParseJson as D, validateServerUrl as E, ErrorCodes as F, abortedByCaller as I, sleep as L, getLogger as M, setLogger as N, redactUrl as O, ComputeError as P, buildAuthHeaders as S, DEFAULT_BLOCKED_HOST as T, readBodyText as _, groupFilesByRoot as a, detectBase64Payload as b, isDefinitionUrl as c, classifyProbeFailure as d, isRedirect as f, raceSignal as g, composeSignal as h, isBase64Flag as i, enableDebugLogging as j, hasField as k, fetchCompute as l, setResponseWireSize as m, downloadFileDataByRoot as n, subFolderSegments as o, getResponseWireSize as p, extractFilesFromComputeResponse as r, isDefinitionRef as s, downloadFileData as t, validateNumbers as u, base64ByteArray as v, warnIfClientSide as w, encodeStringToBase64 as x, decodeBase64ToBinary as y };
+
+//# sourceMappingURL=handle-files-D-4X4Uh_.js.map