@storyshelf/core 0.7.0 → 0.8.0

package/dist/utils/http.d.mts

@@ -2,7 +2,6 @@ import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { Logger } from "../logger.mjs";
 import { Buffer } from "node:buffer";
-//#region src/utils/http.d.ts
 /**
  * Fetch JSON with timeout, retries, and structured errors.
  *
@@ -32,6 +31,18 @@ declare function httpBytes(url: string, options?: HttpRequestOptions): Promise<B
  * @returns The raw response body text.
  */
 declare function httpText(url: string, options?: HttpTextOptions): Promise<string>;
+/**
+ * Send a request and resolve with the response status, without ever reading the response body (it
+ * is cancelled on every response). Use it when the answer is only "did it succeed", such as webhook
+ * delivery, so a receiver cannot make the process buffer an arbitrarily large body. Retries,
+ * timeouts, redaction and tracing are those of {@link httpText}. A non-2xx response throws
+ * {@link HttpError} with an empty `body`.
+ *
+ * @param url - Absolute request URL.
+ * @param options - Method, headers, JSON body, timeout, retries, logger.
+ * @returns The 2xx response status.
+ */
+declare function httpStatus(url: string, options?: HttpTextOptions): Promise<number>;
 /** Failed HTTP response: status code plus a snippet of the response body. */
 declare class HttpError extends Error {
   readonly status: number;
@@ -69,6 +80,5 @@ interface HttpTextOptions {
   signal?: AbortSignal;
   logger?: Logger;
 }
-//#endregion
-export { HttpError, HttpRequestOptions, HttpTextOptions, httpBytes, httpJson, httpText };
+export { HttpError, HttpRequestOptions, HttpTextOptions, httpBytes, httpJson, httpStatus, httpText };
 //# sourceMappingURL=http.d.mts.map

package/dist/utils/http.mjs

@@ -1,9 +1,9 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { injectTraceContext, withSpan } from "../tracing.mjs";
+import { injectTraceContext, setSpanMessage, spanException, withSpan } from "../tracing.mjs";
 import { Buffer } from "node:buffer";
-//#region src/utils/http.ts
+// src/utils/http.ts
 /**
 * Fetch JSON with timeout, retries, and structured errors.
 *
@@ -39,6 +39,20 @@ async function httpBytes(url, options = {}) {
 async function httpText(url, options = {}) {
 	return await requestWithRetry(url, options, options.retries ?? DEFAULT_RETRIES, options.timeoutMs ?? DEFAULT_TIMEOUT_MS, doFetchText);
 }
+/**
+* Send a request and resolve with the response status, without ever reading the response body (it
+* is cancelled on every response). Use it when the answer is only "did it succeed", such as webhook
+* delivery, so a receiver cannot make the process buffer an arbitrarily large body. Retries,
+* timeouts, redaction and tracing are those of {@link httpText}. A non-2xx response throws
+* {@link HttpError} with an empty `body`.
+*
+* @param url - Absolute request URL.
+* @param options - Method, headers, JSON body, timeout, retries, logger.
+* @returns The 2xx response status.
+*/
+async function httpStatus(url, options = {}) {
+	return await requestWithRetry(url, options, options.retries ?? DEFAULT_RETRIES, options.timeoutMs ?? DEFAULT_TIMEOUT_MS, doFetchStatus);
+}
 /** Failed HTTP response: status code plus a snippet of the response body. */
 var HttpError = class extends Error {
 	status;
@@ -91,25 +105,54 @@ async function requestWithRetry(url, options, maxAttempts, timeoutMs, perform) {
 		for (let attempt = 1;; attempt += 1) try {
 			return await perform(url, options, timeoutMs);
 		} catch (error) {
-			span.recordException(error instanceof Error ? error : String(error));
+			describeFailure(span, error, url);
 			if (options.signal?.aborted || !shouldRetry(error, attempt, maxAttempts)) throw error;
+			span.recordException(spanException(error));
 			span.setAttribute("http.retry.count", attempt);
 			await backoff(error, attempt, url, options.logger);
 		}
 	}, {
 		"http.request.method": options.method ?? "GET",
-		"url.full": redactUrl(url)
+		"url.full": redactUrlForLog(url)
 	});
 }
-/** Strip the query string (tokens, signatures) from a URL for span attributes. */
-function redactUrl(url) {
-	const query = url.indexOf("?");
-	return query === -1 ? url : url.slice(0, query);
+/**
+* The form of a request URL that may appear in logs and span attributes: its origin
+* (`protocol//host`) and nothing else. The path of an incoming webhook (Slack, Teams) is the secret,
+* a bot token can be the first segment (Telegram), and other URLs carry credentials in the userinfo
+* or the query, so the path, query, fragment and userinfo are dropped by construction. There is no
+* opt-out.
+*/
+function redactUrlForLog(url) {
+	try {
+		const { protocol, host } = new URL(url);
+		return `${protocol}//${host}`;
+	} catch {
+		return "[invalid url]";
+	}
+}
+/**
+* What a span may say about a failed request. An HTTP failure carries its status and never the
+* response body, which can echo the request URL in any encoding. Any other failure keeps its
+* message with the request URL replaced by its origin, because native `fetch` repeats the whole
+* URL, userinfo included, when it refuses one. The error a caller catches is not changed.
+*/
+function describeFailure(span, error, url) {
+	if (error instanceof HttpError) {
+		span.setAttribute("http.response.status_code", error.status);
+		setSpanMessage(error, `HTTP ${String(error.status)}`);
+	} else if (error instanceof Error) setSpanMessage(error, scrubUrl(error.message, url));
+}
+/** `text` with the request URL, as given and as normalized, replaced by its origin. */
+function scrubUrl(text, url) {
+	const origin = redactUrlForLog(url);
+	const normalized = URL.canParse(url) ? new URL(url).href : url;
+	return text.replaceAll(url, origin).replaceAll(normalized, origin);
 }
 async function backoff(error, attempt, url, logger) {
 	const delay = retryDelayMs(error, attempt);
 	logger?.warn({
-		url,
+		url: redactUrlForLog(url),
 		attempt,
 		delayMs: delay
 	}, "http request failed, retrying");
@@ -137,15 +180,20 @@ async function doFetchJson(url, options, timeoutMs) {
 async function doFetchText(url, options, timeoutMs) {
 	return await (await doFetchResponse(url, options, timeoutMs)).text();
 }
+async function doFetchStatus(url, options, timeoutMs) {
+	const response = await doFetchResponse(url, options, timeoutMs, false);
+	await discardBody(response);
+	return response.status;
+}
 async function doFetchBytes(url, options, timeoutMs) {
 	const response = await doFetchResponse(url, options, timeoutMs);
 	return Buffer.from(await response.arrayBuffer());
 }
-async function doFetchResponse(url, options, timeoutMs) {
+async function doFetchResponse(url, options, timeoutMs, readErrorBody = true) {
 	const request = buildRequest(options);
 	injectTraceContext(request.headers);
 	options.logger?.debug({
-		url,
+		url: redactUrlForLog(url),
 		method: request.method
 	}, "http request");
 	const response = await fetch(url, {
@@ -154,13 +202,27 @@ async function doFetchResponse(url, options, timeoutMs) {
 		body: request.body,
 		signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs)
 	});
-	if (!response.ok) {
-		const text = await response.text();
-		throw new HttpError(response.status, text.slice(0, MAX_BODY_SNIPPET), response.headers);
-	}
+	if (!response.ok) throw await failureOf(response, readErrorBody);
 	return response;
 }
-//#endregion
-export { HttpError, httpBytes, httpJson, httpText };
+/**
+* Cancel an unread body. Cleanup only: a rejected cancel must never replace the request's outcome,
+* or a delivered request would look failed and be retried.
+*/
+async function discardBody(response) {
+	try {
+		await response.body?.cancel();
+	} catch {}
+}
+/** The {@link HttpError} for a non-2xx response; the body is read (and capped) only on request. */
+async function failureOf(response, readBody) {
+	if (!readBody) {
+		await discardBody(response);
+		return new HttpError(response.status, "", response.headers);
+	}
+	const text = await response.text();
+	return new HttpError(response.status, text.slice(0, MAX_BODY_SNIPPET), response.headers);
+}
+export { HttpError, httpBytes, httpJson, httpStatus, httpText, redactUrlForLog };
 
 //# sourceMappingURL=http.mjs.map

package/dist/utils/http.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"http.mjs","names":[],"sources":["../../src/utils/http.ts"],"sourcesContent":["import { Buffer } from \"node:buffer\";\nimport type { Logger } from \"../logger.ts\";\nimport { injectTraceContext, withSpan } from \"../tracing.ts\";\n\n/**\n * Fetch JSON with timeout, retries, and structured errors.\n *\n * Retries network failures, 429, and 502/503/504 (honoring `Retry-After`);\n * every other status throws {@link HttpError} immediately.\n *\n * @param url - Absolute request URL.\n * @param options - Method, headers, JSON body, timeout, retries, logger.\n * @returns The parsed JSON response body.\n */\nexport async function httpJson<T>(url: string, options: HttpRequestOptions = {}): Promise<T> {\n  return await requestWithRetry<T>(\n    url,\n    options,\n    options.retries ?? DEFAULT_RETRIES,\n    options.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n    doFetchJson,\n  );\n}\n\n/**\n * Download a binary response (images) with the same timeout, retry, and\n * `Retry-After` semantics as {@link httpJson}.\n *\n * @param url - Absolute request URL.\n * @param options - Method, headers, timeout, retries, logger.\n * @returns The raw response bytes.\n */\nexport async function httpBytes(url: string, options: HttpRequestOptions = {}): Promise<Buffer> {\n  return await requestWithRetry<Buffer>(\n    url,\n    options,\n    options.retries ?? DEFAULT_RETRIES,\n    options.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n    doFetchBytes,\n  );\n}\n\n/**\n * POST/PUT plain payloads (e.g. Slack/Teams webhook cards) with the same\n * timeout, retry, and `Retry-After` semantics as {@link httpJson}.\n *\n * @param url - Absolute request URL.\n * @param options - Method, headers, text body, timeout, retries, logger.\n * @returns The raw response body text.\n */\nexport async function httpText(url: string, options: HttpTextOptions = {}): Promise<string> {\n  return await requestWithRetry<string>(\n    url,\n    options,\n    options.retries ?? DEFAULT_RETRIES,\n    options.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n    doFetchText,\n  );\n}\n\n/** Failed HTTP response: status code plus a snippet of the response body. */\nexport class HttpError extends Error {\n  readonly status: number;\n  readonly body: string;\n  readonly headers: Headers;\n\n  constructor(status: number, body: string, headers?: Headers) {\n    super(`HTTP ${status}: ${body}`);\n    this.name = \"HttpError\";\n    this.status = status;\n    this.body = body;\n    this.headers = headers ?? new Headers();\n  }\n}\n\n/** Options for {@link httpJson}. */\nexport interface HttpRequestOptions {\n  method?: string;\n  headers?: Record<string, string>;\n  /** Body serialized as JSON with a `content-type` header. */\n  json?: unknown;\n  /** Body serialized as `application/x-www-form-urlencoded` (ignored when `json` is set). */\n  form?: Record<string, string>;\n  /** Per-attempt timeout in milliseconds (default 30s). */\n  timeoutMs?: number;\n  /** Total attempts including the first (default 3). */\n  retries?: number;\n  /** Aborts the request (and any further retry) when it fires. */\n  signal?: AbortSignal;\n  logger?: Logger;\n}\n\nconst DEFAULT_TIMEOUT_MS = 30_000;\n\n/** Options for {@link httpText}. */\nexport interface HttpTextOptions {\n  method?: string;\n  headers?: Record<string, string>;\n  /** Body serialized as JSON with a `content-type` header. */\n  json?: unknown;\n  /** Per-attempt timeout in milliseconds (default 30s). */\n  timeoutMs?: number;\n  /** Total attempts including the first (default 3). */\n  retries?: number;\n  /** Aborts the request (and any further retry) when it fires. */\n  signal?: AbortSignal;\n  logger?: Logger;\n}\nconst DEFAULT_RETRIES = 3;\nconst MAX_RETRY_AFTER_MS = 30_000;\nconst BACKOFF_BASE_MS = 1000;\nconst MAX_BODY_SNIPPET = 500;\n\n/** Whether a failure is worth retrying: network errors, 429, and 502/503/504. */\nfunction shouldRetry(error: unknown, attempt: number, maxAttempts: number): boolean {\n  if (attempt >= maxAttempts) {\n    return false;\n  }\n  if (!(error instanceof HttpError)) {\n    return true;\n  }\n  return error.status === 429 || (error.status >= 502 && error.status <= 504);\n}\n\n/** Parse a Retry-After value (seconds or HTTP-date) into milliseconds. */\nfunction parseRetryAfter(value: string | null): number | null {\n  if (!value) {\n    return null;\n  }\n  const seconds = Number(value);\n  if (Number.isFinite(seconds) && seconds >= 0) {\n    return Math.min(seconds * 1000, MAX_RETRY_AFTER_MS);\n  }\n  const date = Date.parse(value);\n  if (!Number.isNaN(date)) {\n    return Math.min(Math.max(date - Date.now(), 0), MAX_RETRY_AFTER_MS);\n  }\n  return null;\n}\n\n/** Delay before the next attempt: Retry-After when present, else 1s/2s/4s. */\nfunction retryDelayMs(error: unknown, attempt: number): number {\n  if (error instanceof HttpError) {\n    const retryAfter = parseRetryAfter(error.headers.get(\"retry-after\"));\n    if (retryAfter !== null) {\n      return retryAfter;\n    }\n  }\n  return Math.min(BACKOFF_BASE_MS * 2 ** (attempt - 1), MAX_RETRY_AFTER_MS);\n}\n\n/** Sleep helper for retry backoff. */\nasync function sleep(ms: number): Promise<void> {\n  await new Promise((resolve) => {\n    setTimeout(resolve, ms);\n  });\n}\n\n/* oxlint-disable eslint/no-await-in-loop -- retry attempts run sequentially by design */\nasync function requestWithRetry<T>(\n  url: string,\n  options: HttpRequestOptions,\n  maxAttempts: number,\n  timeoutMs: number,\n  perform: (url: string, options: HttpRequestOptions, timeoutMs: number) => Promise<T>,\n): Promise<T> {\n  return await withSpan(\n    \"http.client\",\n    async (span) => {\n      for (let attempt = 1; ; attempt += 1) {\n        try {\n          return await perform(url, options, timeoutMs);\n        } catch (error) {\n          span.recordException(error instanceof Error ? error : String(error));\n          if (options.signal?.aborted || !shouldRetry(error, attempt, maxAttempts)) {\n            throw error;\n          }\n          span.setAttribute(\"http.retry.count\", attempt);\n          await backoff(error, attempt, url, options.logger);\n        }\n      }\n    },\n    { \"http.request.method\": options.method ?? \"GET\", \"url.full\": redactUrl(url) },\n  );\n}\n/* oxlint-enable eslint/no-await-in-loop */\n\n/** Strip the query string (tokens, signatures) from a URL for span attributes. */\nfunction redactUrl(url: string): string {\n  const query = url.indexOf(\"?\");\n  return query === -1 ? url : url.slice(0, query);\n}\n\nasync function backoff(\n  error: unknown,\n  attempt: number,\n  url: string,\n  logger?: Logger,\n): Promise<void> {\n  const delay = retryDelayMs(error, attempt);\n  logger?.warn({ url, attempt, delayMs: delay }, \"http request failed, retrying\");\n  await sleep(delay);\n}\n\nfunction buildRequest(options: HttpRequestOptions): {\n  headers: Record<string, string>;\n  body: string | undefined;\n  method: string;\n} {\n  const headers: Record<string, string> = { ...options.headers };\n  let body: string | undefined;\n  if (options.json !== undefined) {\n    headers[\"content-type\"] = \"application/json\";\n    body = JSON.stringify(options.json);\n  } else if (options.form) {\n    headers[\"content-type\"] = \"application/x-www-form-urlencoded\";\n    body = new URLSearchParams(options.form).toString();\n  }\n  return { headers, body, method: options.method ?? \"GET\" };\n}\n\nasync function doFetchJson<T>(\n  url: string,\n  options: HttpRequestOptions,\n  timeoutMs: number,\n): Promise<T> {\n  const response = await doFetchResponse(url, options, timeoutMs);\n  return (await response.json()) as T;\n}\n\nasync function doFetchText(\n  url: string,\n  options: HttpRequestOptions,\n  timeoutMs: number,\n): Promise<string> {\n  const response = await doFetchResponse(url, options, timeoutMs);\n  return await response.text();\n}\n\nasync function doFetchBytes(\n  url: string,\n  options: HttpRequestOptions,\n  timeoutMs: number,\n): Promise<Buffer> {\n  const response = await doFetchResponse(url, options, timeoutMs);\n  return Buffer.from(await response.arrayBuffer());\n}\n\nasync function doFetchResponse(\n  url: string,\n  options: HttpRequestOptions,\n  timeoutMs: number,\n): Promise<Response> {\n  const request = buildRequest(options);\n  injectTraceContext(request.headers);\n  options.logger?.debug({ url, method: request.method }, \"http request\");\n  const response = await fetch(url, {\n    method: request.method,\n    headers: request.headers,\n    body: request.body,\n    signal: options.signal\n      ? AbortSignal.any([options.signal, AbortSignal.timeout(timeoutMs)])\n      : AbortSignal.timeout(timeoutMs),\n  });\n  if (!response.ok) {\n    const text = await response.text();\n    throw new HttpError(response.status, text.slice(0, MAX_BODY_SNIPPET), response.headers);\n  }\n  return response;\n}\n"],"mappings":"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"}
+{"version":3,"file":"http.mjs","names":[],"sources":["../../src/utils/http.ts"],"sourcesContent":["import type { Span } from \"@opentelemetry/api\";\nimport { Buffer } from \"node:buffer\";\nimport type { Logger } from \"../logger.ts\";\nimport { injectTraceContext, setSpanMessage, spanException, withSpan } from \"../tracing.ts\";\n\n/**\n * Fetch JSON with timeout, retries, and structured errors.\n *\n * Retries network failures, 429, and 502/503/504 (honoring `Retry-After`);\n * every other status throws {@link HttpError} immediately.\n *\n * @param url - Absolute request URL.\n * @param options - Method, headers, JSON body, timeout, retries, logger.\n * @returns The parsed JSON response body.\n */\nexport async function httpJson<T>(url: string, options: HttpRequestOptions = {}): Promise<T> {\n  return await requestWithRetry<T>(\n    url,\n    options,\n    options.retries ?? DEFAULT_RETRIES,\n    options.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n    doFetchJson,\n  );\n}\n\n/**\n * Download a binary response (images) with the same timeout, retry, and\n * `Retry-After` semantics as {@link httpJson}.\n *\n * @param url - Absolute request URL.\n * @param options - Method, headers, timeout, retries, logger.\n * @returns The raw response bytes.\n */\nexport async function httpBytes(url: string, options: HttpRequestOptions = {}): Promise<Buffer> {\n  return await requestWithRetry<Buffer>(\n    url,\n    options,\n    options.retries ?? DEFAULT_RETRIES,\n    options.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n    doFetchBytes,\n  );\n}\n\n/**\n * POST/PUT plain payloads (e.g. Slack/Teams webhook cards) with the same\n * timeout, retry, and `Retry-After` semantics as {@link httpJson}.\n *\n * @param url - Absolute request URL.\n * @param options - Method, headers, text body, timeout, retries, logger.\n * @returns The raw response body text.\n */\nexport async function httpText(url: string, options: HttpTextOptions = {}): Promise<string> {\n  return await requestWithRetry<string>(\n    url,\n    options,\n    options.retries ?? DEFAULT_RETRIES,\n    options.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n    doFetchText,\n  );\n}\n\n/**\n * Send a request and resolve with the response status, without ever reading the response body (it\n * is cancelled on every response). Use it when the answer is only \"did it succeed\", such as webhook\n * delivery, so a receiver cannot make the process buffer an arbitrarily large body. Retries,\n * timeouts, redaction and tracing are those of {@link httpText}. A non-2xx response throws\n * {@link HttpError} with an empty `body`.\n *\n * @param url - Absolute request URL.\n * @param options - Method, headers, JSON body, timeout, retries, logger.\n * @returns The 2xx response status.\n */\nexport async function httpStatus(url: string, options: HttpTextOptions = {}): Promise<number> {\n  return await requestWithRetry<number>(\n    url,\n    options,\n    options.retries ?? DEFAULT_RETRIES,\n    options.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n    doFetchStatus,\n  );\n}\n\n/** Failed HTTP response: status code plus a snippet of the response body. */\nexport class HttpError extends Error {\n  readonly status: number;\n  readonly body: string;\n  readonly headers: Headers;\n\n  constructor(status: number, body: string, headers?: Headers) {\n    super(`HTTP ${status}: ${body}`);\n    this.name = \"HttpError\";\n    this.status = status;\n    this.body = body;\n    this.headers = headers ?? new Headers();\n  }\n}\n\n/** Options for {@link httpJson}. */\nexport interface HttpRequestOptions {\n  method?: string;\n  headers?: Record<string, string>;\n  /** Body serialized as JSON with a `content-type` header. */\n  json?: unknown;\n  /** Body serialized as `application/x-www-form-urlencoded` (ignored when `json` is set). */\n  form?: Record<string, string>;\n  /** Per-attempt timeout in milliseconds (default 30s). */\n  timeoutMs?: number;\n  /** Total attempts including the first (default 3). */\n  retries?: number;\n  /** Aborts the request (and any further retry) when it fires. */\n  signal?: AbortSignal;\n  logger?: Logger;\n}\n\nconst DEFAULT_TIMEOUT_MS = 30_000;\n\n/** Options for {@link httpText}. */\nexport interface HttpTextOptions {\n  method?: string;\n  headers?: Record<string, string>;\n  /** Body serialized as JSON with a `content-type` header. */\n  json?: unknown;\n  /** Per-attempt timeout in milliseconds (default 30s). */\n  timeoutMs?: number;\n  /** Total attempts including the first (default 3). */\n  retries?: number;\n  /** Aborts the request (and any further retry) when it fires. */\n  signal?: AbortSignal;\n  logger?: Logger;\n}\nconst DEFAULT_RETRIES = 3;\nconst MAX_RETRY_AFTER_MS = 30_000;\nconst BACKOFF_BASE_MS = 1000;\nconst MAX_BODY_SNIPPET = 500;\n\n/** Whether a failure is worth retrying: network errors, 429, and 502/503/504. */\nfunction shouldRetry(error: unknown, attempt: number, maxAttempts: number): boolean {\n  if (attempt >= maxAttempts) {\n    return false;\n  }\n  if (!(error instanceof HttpError)) {\n    return true;\n  }\n  return error.status === 429 || (error.status >= 502 && error.status <= 504);\n}\n\n/** Parse a Retry-After value (seconds or HTTP-date) into milliseconds. */\nfunction parseRetryAfter(value: string | null): number | null {\n  if (!value) {\n    return null;\n  }\n  const seconds = Number(value);\n  if (Number.isFinite(seconds) && seconds >= 0) {\n    return Math.min(seconds * 1000, MAX_RETRY_AFTER_MS);\n  }\n  const date = Date.parse(value);\n  if (!Number.isNaN(date)) {\n    return Math.min(Math.max(date - Date.now(), 0), MAX_RETRY_AFTER_MS);\n  }\n  return null;\n}\n\n/** Delay before the next attempt: Retry-After when present, else 1s/2s/4s. */\nfunction retryDelayMs(error: unknown, attempt: number): number {\n  if (error instanceof HttpError) {\n    const retryAfter = parseRetryAfter(error.headers.get(\"retry-after\"));\n    if (retryAfter !== null) {\n      return retryAfter;\n    }\n  }\n  return Math.min(BACKOFF_BASE_MS * 2 ** (attempt - 1), MAX_RETRY_AFTER_MS);\n}\n\n/** Sleep helper for retry backoff. */\nasync function sleep(ms: number): Promise<void> {\n  await new Promise((resolve) => {\n    setTimeout(resolve, ms);\n  });\n}\n\n/* oxlint-disable eslint/no-await-in-loop -- retry attempts run sequentially by design */\nasync function requestWithRetry<T>(\n  url: string,\n  options: HttpRequestOptions,\n  maxAttempts: number,\n  timeoutMs: number,\n  perform: (url: string, options: HttpRequestOptions, timeoutMs: number) => Promise<T>,\n): Promise<T> {\n  return await withSpan(\n    \"http.client\",\n    async (span) => {\n      for (let attempt = 1; ; attempt += 1) {\n        try {\n          return await perform(url, options, timeoutMs);\n        } catch (error) {\n          describeFailure(span, error, url);\n          if (options.signal?.aborted || !shouldRetry(error, attempt, maxAttempts)) {\n            // The final failure is recorded once, by `withSpan`, in the same redacted form.\n            throw error;\n          }\n          span.recordException(spanException(error));\n          span.setAttribute(\"http.retry.count\", attempt);\n          await backoff(error, attempt, url, options.logger);\n        }\n      }\n    },\n    { \"http.request.method\": options.method ?? \"GET\", \"url.full\": redactUrlForLog(url) },\n  );\n}\n/* oxlint-enable eslint/no-await-in-loop */\n\n/**\n * The form of a request URL that may appear in logs and span attributes: its origin\n * (`protocol//host`) and nothing else. The path of an incoming webhook (Slack, Teams) is the secret,\n * a bot token can be the first segment (Telegram), and other URLs carry credentials in the userinfo\n * or the query, so the path, query, fragment and userinfo are dropped by construction. There is no\n * opt-out.\n */\nexport function redactUrlForLog(url: string): string {\n  try {\n    const { protocol, host } = new URL(url);\n    return `${protocol}//${host}`;\n  } catch {\n    return \"[invalid url]\";\n  }\n}\n\n/**\n * What a span may say about a failed request. An HTTP failure carries its status and never the\n * response body, which can echo the request URL in any encoding. Any other failure keeps its\n * message with the request URL replaced by its origin, because native `fetch` repeats the whole\n * URL, userinfo included, when it refuses one. The error a caller catches is not changed.\n */\nfunction describeFailure(span: Span, error: unknown, url: string): void {\n  if (error instanceof HttpError) {\n    span.setAttribute(\"http.response.status_code\", error.status);\n    setSpanMessage(error, `HTTP ${String(error.status)}`);\n  } else if (error instanceof Error) {\n    setSpanMessage(error, scrubUrl(error.message, url));\n  }\n}\n\n/** `text` with the request URL, as given and as normalized, replaced by its origin. */\nfunction scrubUrl(text: string, url: string): string {\n  const origin = redactUrlForLog(url);\n  const normalized = URL.canParse(url) ? new URL(url).href : url;\n  return text.replaceAll(url, origin).replaceAll(normalized, origin);\n}\n\nasync function backoff(\n  error: unknown,\n  attempt: number,\n  url: string,\n  logger?: Logger,\n): Promise<void> {\n  const delay = retryDelayMs(error, attempt);\n  logger?.warn(\n    { url: redactUrlForLog(url), attempt, delayMs: delay },\n    \"http request failed, retrying\",\n  );\n  await sleep(delay);\n}\n\nfunction buildRequest(options: HttpRequestOptions): {\n  headers: Record<string, string>;\n  body: string | undefined;\n  method: string;\n} {\n  const headers: Record<string, string> = { ...options.headers };\n  let body: string | undefined;\n  if (options.json !== undefined) {\n    headers[\"content-type\"] = \"application/json\";\n    body = JSON.stringify(options.json);\n  } else if (options.form) {\n    headers[\"content-type\"] = \"application/x-www-form-urlencoded\";\n    body = new URLSearchParams(options.form).toString();\n  }\n  return { headers, body, method: options.method ?? \"GET\" };\n}\n\nasync function doFetchJson<T>(\n  url: string,\n  options: HttpRequestOptions,\n  timeoutMs: number,\n): Promise<T> {\n  const response = await doFetchResponse(url, options, timeoutMs);\n  return (await response.json()) as T;\n}\n\nasync function doFetchText(\n  url: string,\n  options: HttpRequestOptions,\n  timeoutMs: number,\n): Promise<string> {\n  const response = await doFetchResponse(url, options, timeoutMs);\n  return await response.text();\n}\n\nasync function doFetchStatus(\n  url: string,\n  options: HttpRequestOptions,\n  timeoutMs: number,\n): Promise<number> {\n  const response = await doFetchResponse(url, options, timeoutMs, false);\n  await discardBody(response);\n  return response.status;\n}\n\nasync function doFetchBytes(\n  url: string,\n  options: HttpRequestOptions,\n  timeoutMs: number,\n): Promise<Buffer> {\n  const response = await doFetchResponse(url, options, timeoutMs);\n  return Buffer.from(await response.arrayBuffer());\n}\n\nasync function doFetchResponse(\n  url: string,\n  options: HttpRequestOptions,\n  timeoutMs: number,\n  readErrorBody = true,\n): Promise<Response> {\n  const request = buildRequest(options);\n  injectTraceContext(request.headers);\n  options.logger?.debug({ url: redactUrlForLog(url), method: request.method }, \"http request\");\n  const response = await fetch(url, {\n    method: request.method,\n    headers: request.headers,\n    body: request.body,\n    signal: options.signal\n      ? AbortSignal.any([options.signal, AbortSignal.timeout(timeoutMs)])\n      : AbortSignal.timeout(timeoutMs),\n  });\n  if (!response.ok) {\n    throw await failureOf(response, readErrorBody);\n  }\n  return response;\n}\n\n/**\n * Cancel an unread body. Cleanup only: a rejected cancel must never replace the request's outcome,\n * or a delivered request would look failed and be retried.\n */\nasync function discardBody(response: Response): Promise<void> {\n  try {\n    await response.body?.cancel();\n  } catch {\n    // The status is already known; there is nothing left to do with the body.\n  }\n}\n\n/** The {@link HttpError} for a non-2xx response; the body is read (and capped) only on request. */\nasync function failureOf(response: Response, readBody: boolean): Promise<HttpError> {\n  if (!readBody) {\n    await discardBody(response);\n    return new HttpError(response.status, \"\", response.headers);\n  }\n  const text = await response.text();\n  return new HttpError(response.status, text.slice(0, MAX_BODY_SNIPPET), response.headers);\n}\n"],"mappings":"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"}

package/dist/utils/map-adaptive.d.mts

@@ -1,7 +1,6 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { AdaptiveConcurrency } from "./adaptive-concurrency.mjs";
-//#region src/utils/map-adaptive.d.ts
 /**
  * Like `mapLimit`, but the limit is read live from `controller` and every finished item is fed
  * back to it. `fn` reports a timeout it handled itself with `timedOut: true`.
@@ -10,6 +9,5 @@ declare function mapAdaptive<T, R>(items: readonly T[], controller: AdaptiveConc
   value: R;
   timedOut?: boolean;
 }>): Promise<R[]>;
-//#endregion
 export { mapAdaptive };
 //# sourceMappingURL=map-adaptive.d.mts.map

package/dist/utils/map-adaptive.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/utils/map-adaptive.ts
+// src/utils/map-adaptive.ts
 /**
 * Like `mapLimit`, but the limit is read live from `controller` and every finished item is fed
 * back to it. `fn` reports a timeout it handled itself with `timedOut: true`.
@@ -66,7 +66,6 @@ var AdaptiveRun = class {
 		this.pump();
 	}
 };
-//#endregion
 export { mapAdaptive };
 
 //# sourceMappingURL=map-adaptive.mjs.map

package/dist/utils/map-limit.d.mts

@@ -1,10 +1,8 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/utils/map-limit.d.ts
 /** Split `items` into consecutive batches of at most `size` (a non-positive size means one batch). */
 declare function chunk<T>(items: readonly T[], size: number): T[][];
 /** Run `fn` over `items` with at most `limit` in flight; results keep input order. */
 declare function mapLimit<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
-//#endregion
 export { chunk, mapLimit };
 //# sourceMappingURL=map-limit.d.mts.map

package/dist/utils/map-limit.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/utils/map-limit.ts
+// src/utils/map-limit.ts
 /** Split `items` into consecutive batches of at most `size` (a non-positive size means one batch). */
 function chunk(items, size) {
 	const step = size > 0 ? Math.max(1, Math.floor(size)) : items.length || 1;
@@ -26,7 +26,6 @@ async function mapLimit(items, limit, fn) {
 	}));
 	return results;
 }
-//#endregion
 export { chunk, mapLimit };
 
 //# sourceMappingURL=map-limit.mjs.map

package/dist/utils/mime.d.mts

@@ -1,9 +1,7 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/utils/mime.d.ts
 /** Shared MIME types for storybook static serving. */
 declare const MIME_TYPES: Record<string, string>;
 declare function mimeFor(filePath: string): string;
-//#endregion
 export { MIME_TYPES, mimeFor };
 //# sourceMappingURL=mime.d.mts.map

package/dist/utils/mime.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/utils/mime.ts
+// src/utils/mime.ts
 /** Shared MIME types for storybook static serving. */
 const MIME_TYPES = {
 	".css": "text/css; charset=utf-8",
@@ -27,7 +27,6 @@ function mimeFor(filePath) {
 	const ext = filePath.slice(filePath.lastIndexOf(".")).toLowerCase();
 	return MIME_TYPES[ext] ?? "application/octet-stream";
 }
-//#endregion
 export { MIME_TYPES, mimeFor };
 
 //# sourceMappingURL=mime.mjs.map

package/dist/utils/page-limiter.d.mts

@@ -2,7 +2,6 @@ import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { Logger } from "../logger.mjs";
 import { SessionGate } from "./session-gate.mjs";
-//#region src/utils/page-limiter.d.ts
 /** Options for {@link createPageLimiter}. */
 interface PageLimiterOptions {
   /** Explicit page count (config or run input). Fixed: the adaptive controller stays off. */
@@ -32,6 +31,5 @@ interface PageLimiter {
  * recommendation and let latency, event-loop lag and timeouts move it up to the adaptive ceiling.
  */
 declare function createPageLimiter(options: PageLimiterOptions): PageLimiter;
-//#endregion
 export { PageLimiter, PageLimiterOptions, createPageLimiter };
 //# sourceMappingURL=page-limiter.d.mts.map

package/dist/utils/page-limiter.mjs

@@ -5,7 +5,7 @@ import { mapLimit } from "./map-limit.mjs";
 import { detectResources, maxPageConcurrency, recommendedPageConcurrency } from "./resources.mjs";
 import { AdaptiveConcurrency } from "./adaptive-concurrency.mjs";
 import { mapAdaptive } from "./map-adaptive.mjs";
-//#region src/utils/page-limiter.ts
+// src/utils/page-limiter.ts
 /**
 * The session gate's size for a remote target; a fixed limit when `concurrency` is given; otherwise start at the CPU/memory/engine-sized
 * recommendation and let latency, event-loop lag and timeouts move it up to the adaptive ceiling.
@@ -50,7 +50,6 @@ function createPageLimiter(options) {
 	};
 }
 function noop() {}
-//#endregion
 export { createPageLimiter };
 
 //# sourceMappingURL=page-limiter.mjs.map

package/dist/utils/path-security.d.mts

@@ -1,12 +1,10 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/utils/path-security.d.ts
 /** Whether a path segment is safe (no traversal). */
 declare function isSafeSegment(segment: string): boolean;
 /** Whether joining root with candidate stays inside root (no traversal). */
 declare function isPathSafe(root: string, candidate: string): boolean;
 /** Check if a path built from root + entry would escape root (for zip extraction). */
 declare function isBlockedTarget(root: string, entryPath: string): boolean;
-//#endregion
 export { isBlockedTarget, isPathSafe, isSafeSegment };
 //# sourceMappingURL=path-security.d.mts.map

package/dist/utils/path-security.mjs

@@ -1,8 +1,7 @@
-import "node:path";
+import { join, normalize, sep } from "node:path";
 import "node:url";
 import.meta.url;
-import { join, normalize, sep } from "node:path";
-//#region src/utils/path-security.ts
+// src/utils/path-security.ts
 /** Whether a path segment is safe (no traversal). */
 function isSafeSegment(segment) {
 	return segment !== ".." && !segment.startsWith("/") && !segment.includes("\\") && !segment.includes("..");
@@ -18,7 +17,6 @@ function isBlockedTarget(root, entryPath) {
 	const target = normalize(join(root, entryPath));
 	return target !== root && !target.startsWith(normalize(root) + sep);
 }
-//#endregion
 export { isBlockedTarget, isPathSafe, isSafeSegment };
 
 //# sourceMappingURL=path-security.mjs.map

package/dist/utils/path-security.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"path-security.mjs","names":[],"sources":["../../src/utils/path-security.ts"],"sourcesContent":["import { join, normalize, sep } from \"node:path\";\n\n/** Whether a path segment is safe (no traversal). */\nexport function isSafeSegment(segment: string): boolean {\n  return (\n    segment !== \"..\" &&\n    !segment.startsWith(\"/\") &&\n    !segment.includes(\"\\\\\") &&\n    !segment.includes(\"..\")\n  );\n}\n\n/** Whether joining root with candidate stays inside root (no traversal). */\nexport function isPathSafe(root: string, candidate: string): boolean {\n  const normalizedRoot = normalize(root);\n  const normalizedCandidate = normalize(candidate);\n  return (\n    normalizedCandidate === normalizedRoot ||\n    normalizedCandidate.startsWith(normalizedRoot + sep) ||\n    normalizedCandidate.startsWith(`${normalizedRoot}/`)\n  );\n}\n\n/** Check if a path built from root + entry would escape root (for zip extraction). */\nexport function isBlockedTarget(root: string, entryPath: string): boolean {\n  const target = normalize(join(root, entryPath));\n  return target !== root && !target.startsWith(normalize(root) + sep);\n}\n"],"mappings":";;;;;;AAGA,SAAgB,cAAc,SAA0B;CACtD,OACE,YAAY,QACZ,CAAC,QAAQ,WAAW,GAAG,KACvB,CAAC,QAAQ,SAAS,IAAI,KACtB,CAAC,QAAQ,SAAS,IAAI;AAE1B;;AAGA,SAAgB,WAAW,MAAc,WAA4B;CACnE,MAAM,iBAAiB,UAAU,IAAI;CACrC,MAAM,sBAAsB,UAAU,SAAS;CAC/C,OACE,wBAAwB,kBACxB,oBAAoB,WAAW,iBAAiB,GAAG,KACnD,oBAAoB,WAAW,GAAG,eAAe,EAAE;AAEvD;;AAGA,SAAgB,gBAAgB,MAAc,WAA4B;CACxE,MAAM,SAAS,UAAU,KAAK,MAAM,SAAS,CAAC;CAC9C,OAAO,WAAW,QAAQ,CAAC,OAAO,WAAW,UAAU,IAAI,IAAI,GAAG;AACpE"}
+{"version":3,"file":"path-security.mjs","names":[],"sources":["../../src/utils/path-security.ts"],"sourcesContent":["import { join, normalize, sep } from \"node:path\";\n\n/** Whether a path segment is safe (no traversal). */\nexport function isSafeSegment(segment: string): boolean {\n  return (\n    segment !== \"..\" &&\n    !segment.startsWith(\"/\") &&\n    !segment.includes(\"\\\\\") &&\n    !segment.includes(\"..\")\n  );\n}\n\n/** Whether joining root with candidate stays inside root (no traversal). */\nexport function isPathSafe(root: string, candidate: string): boolean {\n  const normalizedRoot = normalize(root);\n  const normalizedCandidate = normalize(candidate);\n  return (\n    normalizedCandidate === normalizedRoot ||\n    normalizedCandidate.startsWith(normalizedRoot + sep) ||\n    normalizedCandidate.startsWith(`${normalizedRoot}/`)\n  );\n}\n\n/** Check if a path built from root + entry would escape root (for zip extraction). */\nexport function isBlockedTarget(root: string, entryPath: string): boolean {\n  const target = normalize(join(root, entryPath));\n  return target !== root && !target.startsWith(normalize(root) + sep);\n}\n"],"mappings":";;;;;AAGA,SAAgB,cAAc,SAA0B;CACtD,OACE,YAAY,QACZ,CAAC,QAAQ,WAAW,GAAG,KACvB,CAAC,QAAQ,SAAS,IAAI,KACtB,CAAC,QAAQ,SAAS,IAAI;AAE1B;;AAGA,SAAgB,WAAW,MAAc,WAA4B;CACnE,MAAM,iBAAiB,UAAU,IAAI;CACrC,MAAM,sBAAsB,UAAU,SAAS;CAC/C,OACE,wBAAwB,kBACxB,oBAAoB,WAAW,iBAAiB,GAAG,KACnD,oBAAoB,WAAW,GAAG,eAAe,EAAE;AAEvD;;AAGA,SAAgB,gBAAgB,MAAc,WAA4B;CACxE,MAAM,SAAS,UAAU,KAAK,MAAM,SAAS,CAAC;CAC9C,OAAO,WAAW,QAAQ,CAAC,OAAO,WAAW,UAAU,IAAI,IAAI,GAAG;AACpE"}

package/dist/utils/public-origin.d.mts

@@ -1,6 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/utils/public-origin.d.ts
 /** Finding the address a deployment is reached at without being told (ADR 0007, decision 6). */
 /** Environment variables, as `process.env` has them. */
 type Env = Readonly<Record<string, string | undefined>>;
@@ -15,6 +14,5 @@ declare function normalizeOrigin(value?: string): string | undefined;
  * domain. Cloud Run, AWS App Runner, Lambda function URLs and Cloudflare Workers publish nothing.
  */
 declare function detectPublicBaseUrl(env: Env): string | undefined;
-//#endregion
 export { Env, detectPublicBaseUrl, normalizeOrigin };
 //# sourceMappingURL=public-origin.d.mts.map

package/dist/utils/public-origin.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/utils/public-origin.ts
+// src/utils/public-origin.ts
 /**
 * The origin (`scheme://host[:port]`) of `value`, or `undefined` when it is not an http(s) URL
 * without credentials. A bare host (`app.example.com`), as platforms often publish, reads as https.
@@ -69,7 +69,6 @@ function fromContainerApps(env) {
 	const suffix = env["CONTAINER_APP_ENV_DNS_SUFFIX"];
 	return app && suffix ? normalizeOrigin(`${app}.${suffix}`) : void 0;
 }
-//#endregion
 export { detectPublicBaseUrl, normalizeOrigin };
 
 //# sourceMappingURL=public-origin.mjs.map

package/dist/utils/redact.d.mts

@@ -1,6 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/utils/redact.d.ts
 /**
  * Secret redaction for adapter errors, health details, and logs.
  *
@@ -12,6 +11,5 @@ import __tsdown_shims_url from 'node:url';
 declare function redactSecrets(text: string): string;
 /** Redact secrets, then truncate to `maxLength`. */
 declare function sanitizeErrorText(text: string, maxLength: number): string;
-//#endregion
 export { redactSecrets, sanitizeErrorText };
 //# sourceMappingURL=redact.d.mts.map

package/dist/utils/redact.mjs

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { STORYBOOK_TOKEN_PREFIX, STORYBOOK_TOKEN_SOURCE } from "./storybook-token.mjs";
-//#region src/utils/redact.ts
+// src/utils/redact.ts
 /**
 * Secret redaction for adapter errors, health details, and logs.
 *
@@ -39,7 +39,6 @@ function sanitizeErrorText(text, maxLength) {
 	const redacted = redactSecrets(text);
 	return redacted.length > maxLength ? redacted.slice(0, maxLength) : redacted;
 }
-//#endregion
 export { redactSecrets, sanitizeErrorText };
 
 //# sourceMappingURL=redact.mjs.map

package/dist/utils/remote-environment.d.mts

@@ -1,7 +1,6 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { CaptureEnvironment } from "../adapter/capture-runner.mjs";
-//#region src/utils/remote-environment.d.ts
 /** What the probe page reports. */
 interface BrowserProbe {
   /** OS as the page sees it (`navigator.userAgentData.platform`, else `navigator.platform`). */
@@ -24,6 +23,45 @@ declare const FONT_PROBE_FAMILIES: readonly string[];
  * for a family that does not exist, so it cannot tell.
  */
 declare function inPageProbe(families: string[]): BrowserProbe;
+/** How a {@link boundedProbe} ended. */
+type ProbeOutcome<T> = {
+  status: "done";
+  value: T;
+} |
+/** Still running after `timeoutMs`: the environment is unknown, the run goes on. */
+{
+  status: "timeout";
+} |
+/** The run was cancelled: the run stops, it is never read as "unknown environment". */
+{
+  status: "cancelled";
+} |
+/** The probe threw (a service outage, a page that would not open): unknown, with a warning. */
+{
+  status: "failed";
+  error: unknown;
+};
+/** What a probe's work can ask about its own fate. */
+interface ProbeControl {
+  /**
+   * True once the probe timed out or was cancelled. Work that opens a page must check it after
+   * every await and release what it opened, because nothing waits for it any more.
+   */
+  stopped: () => boolean;
+}
+/**
+ * Run probe work under a time limit and a cancel signal (ADR 0007, decision 2). A probe that hangs
+ * on an unresponsive service must not hold a render, and a cancel must interrupt it instead of
+ * waiting for the service. The work is never awaited past the limit and never leaves an unhandled
+ * rejection; releasing the page it opened is the caller's job (`ProbeControl.stopped`, or closing
+ * what it holds once this returns). A failure after the signal fired reads as cancelled, since
+ * closing the browser is how a cancel interrupts it.
+ */
+declare function boundedProbe<T>(options: {
+  run: (control: ProbeControl) => Promise<T>;
+  timeoutMs: number;
+  signal?: AbortSignal | undefined;
+}): Promise<ProbeOutcome<T>>;
 /**
  * The environment of a remote render: the driver's browser version and what the page reported. A
  * field the page could not give is left out, except the OS, which falls back to what the service
@@ -34,6 +72,5 @@ declare function remoteEnvironment(options: {
   probe?: BrowserProbe | undefined;
   declaredPlatform?: string | undefined;
 }): CaptureEnvironment;
-//#endregion
-export { BrowserProbe, FONT_PROBE_FAMILIES, inPageProbe, remoteEnvironment };
+export { BrowserProbe, FONT_PROBE_FAMILIES, ProbeControl, ProbeOutcome, boundedProbe, inPageProbe, remoteEnvironment };
 //# sourceMappingURL=remote-environment.d.mts.map

package/dist/utils/remote-environment.mjs

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { sha256 } from "./hash.mjs";
-//#region src/utils/remote-environment.ts
+// src/utils/remote-environment.ts
 /**
 * Families probed for the fonts digest: system fonts that differ between operating systems and
 * image builds, so a provider-side change moves the hash. A fixed list; changing it re-baselines
@@ -85,6 +85,56 @@ function inPageProbe(families) {
 	return probe;
 }
 /**
+* Run probe work under a time limit and a cancel signal (ADR 0007, decision 2). A probe that hangs
+* on an unresponsive service must not hold a render, and a cancel must interrupt it instead of
+* waiting for the service. The work is never awaited past the limit and never leaves an unhandled
+* rejection; releasing the page it opened is the caller's job (`ProbeControl.stopped`, or closing
+* what it holds once this returns). A failure after the signal fired reads as cancelled, since
+* closing the browser is how a cancel interrupts it.
+*/
+async function boundedProbe(options) {
+	const { signal, timeoutMs } = options;
+	if (signal?.aborted) return { status: "cancelled" };
+	const halt = { halted: false };
+	return await settle(options.run({ stopped: () => halt.halted }).then((value) => ({
+		status: "done",
+		value
+	}), (error) => ({
+		status: "failed",
+		error
+	})), limitOf(timeoutMs, signal), signal, halt);
+}
+/** Wait for the work or the limit, mark the work stopped if it lost, and drop the timer and listener. */
+async function settle(work, limit, signal, halt) {
+	try {
+		const outcome = await Promise.race([work, limit.reached]);
+		halt.halted = outcome.status === "timeout" || outcome.status === "cancelled";
+		return outcome.status === "failed" && signal?.aborted ? { status: "cancelled" } : outcome;
+	} finally {
+		limit.clear();
+	}
+}
+/** A promise that settles on the timeout or the abort, and a way to drop both. */
+function limitOf(timeoutMs, signal) {
+	let timer;
+	let onAbort;
+	return {
+		reached: new Promise((resolve) => {
+			timer = setTimeout(() => {
+				resolve({ status: "timeout" });
+			}, timeoutMs);
+			onAbort = () => {
+				resolve({ status: "cancelled" });
+			};
+			signal?.addEventListener("abort", onAbort, { once: true });
+		}),
+		clear: () => {
+			clearTimeout(timer);
+			if (onAbort) signal?.removeEventListener("abort", onAbort);
+		}
+	};
+}
+/**
 * The environment of a remote render: the driver's browser version and what the page reported. A
 * field the page could not give is left out, except the OS, which falls back to what the service
 * was configured to render on; an unknown fingerprint component is never a change (ADR 0005).
@@ -108,7 +158,6 @@ function normalizePlatform(value) {
 	if (text.startsWith("mac") || text === "iphone" || text === "ipad") return "macos";
 	return text.startsWith("linux") ? "linux" : text;
 }
-//#endregion
-export { FONT_PROBE_FAMILIES, inPageProbe, remoteEnvironment };
+export { FONT_PROBE_FAMILIES, boundedProbe, inPageProbe, remoteEnvironment };
 
 //# sourceMappingURL=remote-environment.mjs.map