@storyshelf/core 0.6.2 → 0.8.0

package/dist/utils/environment.mjs

@@ -0,0 +1,58 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { sha256 } from "./hash.mjs";
+// src/utils/environment.ts
+let fonts;
+/**
+* Digest of the installed system font families (`fc-list`), or undefined where fontconfig is not
+* available. Cached for the process (fonts do not change under a running server), except a failed
+* run such as a timeout under load: that is retried next time rather than reported as "no fonts"
+* for the life of the process.
+*/
+async function systemFontsHash() {
+	fonts ??= listFonts().then((result) => {
+		if (!result.settled) fonts = void 0;
+		return result.hash;
+	});
+	return await fonts;
+}
+async function listFonts() {
+	const childProcess = process.getBuiltinModule?.call(process, "node:child_process");
+	if (!childProcess) return {
+		hash: void 0,
+		settled: true
+	};
+	return await new Promise((resolve) => {
+		childProcess.execFile("fc-list", [":", "family"], { timeout: 3e3 }, (error, stdout) => {
+			resolve(error ? {
+				hash: void 0,
+				settled: error.code === "ENOENT"
+			} : {
+				hash: digestOf(stdout),
+				settled: true
+			});
+		});
+	});
+}
+/**
+* The environment a runner captured in: browser build, host platform, device scale factor and a
+* font digest. Runners call this once per render with the version their driver reports.
+*/
+async function detectCaptureEnvironment(browserVersion, deviceScaleFactor = 1) {
+	const fontsHash = await systemFontsHash();
+	return {
+		...browserVersion ? { browserVersion } : {},
+		platform: `${process.platform}-${process.arch}`,
+		deviceScaleFactor,
+		...fontsHash ? { fontsHash } : {}
+	};
+}
+/** Digest of the distinct family names in `fc-list` output; undefined when there are none. */
+function digestOf(stdout) {
+	const families = [...new Set(stdout.split("\n").map((line) => line.trim()))].filter(Boolean);
+	return families.length > 0 ? sha256(families.toSorted().join("\n")).slice(0, 16) : void 0;
+}
+export { detectCaptureEnvironment, systemFontsHash };
+
+//# sourceMappingURL=environment.mjs.map

package/dist/utils/environment.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.mjs","names":[],"sources":["../../src/utils/environment.ts"],"sourcesContent":["/** Detects the rendering environment a capture runner reports (see `CaptureEnvironment`). */\nimport type { CaptureEnvironment } from \"../adapters/capture-runner.ts\";\nimport { sha256 } from \"./hash.ts\";\n\ntype ChildProcessModule = typeof import(\"node:child_process\");\n\nlet fonts: Promise<string | undefined> | undefined;\n\n/**\n * Digest of the installed system font families (`fc-list`), or undefined where fontconfig is not\n * available. Cached for the process (fonts do not change under a running server), except a failed\n * run such as a timeout under load: that is retried next time rather than reported as \"no fonts\"\n * for the life of the process.\n */\nexport async function systemFontsHash(): Promise<string | undefined> {\n  fonts ??= listFonts().then((result) => {\n    if (!result.settled) {\n      fonts = undefined;\n    }\n    return result.hash;\n  });\n  return await fonts;\n}\n\n/** An `fc-list` outcome; `settled` is false for a failure worth retrying. */\ninterface FontsResult {\n  hash: string | undefined;\n  settled: boolean;\n}\n\nasync function listFonts(): Promise<FontsResult> {\n  const getBuiltin = (process as { getBuiltinModule?: (id: string) => unknown }).getBuiltinModule;\n  const childProcess = getBuiltin?.call(process, \"node:child_process\") as\n    | ChildProcessModule\n    | undefined;\n  if (!childProcess) {\n    return { hash: undefined, settled: true };\n  }\n  return await new Promise<FontsResult>((resolve) => {\n    childProcess.execFile(\"fc-list\", [\":\", \"family\"], { timeout: 3000 }, (error, stdout) => {\n      resolve(\n        error\n          ? { hash: undefined, settled: (error as { code?: unknown }).code === \"ENOENT\" }\n          : { hash: digestOf(stdout), settled: true },\n      );\n    });\n  });\n}\n\n/**\n * The environment a runner captured in: browser build, host platform, device scale factor and a\n * font digest. Runners call this once per render with the version their driver reports.\n */\nexport async function detectCaptureEnvironment(\n  browserVersion?: string,\n  deviceScaleFactor = 1,\n): Promise<CaptureEnvironment> {\n  const fontsHash = await systemFontsHash();\n  return {\n    ...(browserVersion ? { browserVersion } : {}),\n    platform: `${process.platform}-${process.arch}`,\n    deviceScaleFactor,\n    ...(fontsHash ? { fontsHash } : {}),\n  };\n}\n\n/** Digest of the distinct family names in `fc-list` output; undefined when there are none. */\nfunction digestOf(stdout: string): string | undefined {\n  const families = [...new Set(stdout.split(\"\\n\").map((line) => line.trim()))].filter(Boolean);\n  return families.length > 0 ? sha256(families.toSorted().join(\"\\n\")).slice(0, 16) : undefined;\n}\n"],"mappings":";;;;;AAMA,IAAI;;;;;;;AAQJ,eAAsB,kBAA+C;CACnE,UAAU,UAAU,CAAC,CAAC,MAAM,WAAW;EACrC,IAAI,CAAC,OAAO,SACV,QAAQ,KAAA;EAEV,OAAO,OAAO;CAChB,CAAC;CACD,OAAO,MAAM;AACf;AAQA,eAAe,YAAkC;CAE/C,MAAM,eADc,QAA2D,kBAC9C,KAAK,SAAS,oBAAoB;CAGnE,IAAI,CAAC,cACH,OAAO;EAAE,MAAM,KAAA;EAAW,SAAS;CAAK;CAE1C,OAAO,MAAM,IAAI,SAAsB,YAAY;EACjD,aAAa,SAAS,WAAW,CAAC,KAAK,QAAQ,GAAG,EAAE,SAAS,IAAK,IAAI,OAAO,WAAW;GACtF,QACE,QACI;IAAE,MAAM,KAAA;IAAW,SAAU,MAA6B,SAAS;GAAS,IAC5E;IAAE,MAAM,SAAS,MAAM;IAAG,SAAS;GAAK,CAC9C;EACF,CAAC;CACH,CAAC;AACH;;;;;AAMA,eAAsB,yBACpB,gBACA,oBAAoB,GACS;CAC7B,MAAM,YAAY,MAAM,gBAAgB;CACxC,OAAO;EACL,GAAI,iBAAiB,EAAE,eAAe,IAAI,CAAC;EAC3C,UAAU,GAAG,QAAQ,SAAS,GAAG,QAAQ;EACzC;EACA,GAAI,YAAY,EAAE,UAAU,IAAI,CAAC;CACnC;AACF;;AAGA,SAAS,SAAS,QAAoC;CACpD,MAAM,WAAW,CAAC,GAAG,IAAI,IAAI,OAAO,MAAM,IAAI,CAAC,CAAC,KAAK,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,OAAO;CAC3F,OAAO,SAAS,SAAS,IAAI,OAAO,SAAS,SAAS,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,GAAG,EAAE,IAAI,KAAA;AACrF"}

package/dist/utils/hash.d.mts

@@ -1,6 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/utils/hash.d.ts
 /** Hash a value with SHA-256, returning lowercase hex. */
 declare function sha256(value: string): string;
 /** Sign a value with HMAC-SHA-256, returning lowercase hex. */
@@ -12,6 +11,5 @@ declare function randomToken(prefix: string): {
 };
 /** Compare two strings in constant time to avoid timing leaks. */
 declare function timingSafeEqualString(a: string, b: string): boolean;
-//#endregion
 export { hmacSha256, randomToken, sha256, timingSafeEqualString };
 //# sourceMappingURL=hash.d.mts.map

package/dist/utils/hash.mjs

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
-//#region src/utils/hash.ts
+// src/utils/hash.ts
 /** Hash a value with SHA-256, returning lowercase hex. */
 function sha256(value) {
 	return createHash("sha256").update(value).digest("hex");
@@ -25,7 +25,6 @@ function timingSafeEqualString(a, b) {
 	const bb = Buffer.from(b);
 	return ab.length === bb.length && timingSafeEqual(ab, bb);
 }
-//#endregion
 export { hmacSha256, randomToken, sha256, timingSafeEqualString };
 
 //# sourceMappingURL=hash.mjs.map

package/dist/utils/http.d.mts

@@ -1,7 +1,7 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { Logger } from "../logger.mjs";
-//#region src/utils/http.d.ts
+import { Buffer } from "node:buffer";
 /**
  * Fetch JSON with timeout, retries, and structured errors.
  *
@@ -13,6 +13,15 @@ import { Logger } from "../logger.mjs";
  * @returns The parsed JSON response body.
  */
 declare function httpJson<T>(url: string, options?: HttpRequestOptions): Promise<T>;
+/**
+ * Download a binary response (images) with the same timeout, retry, and
+ * `Retry-After` semantics as {@link httpJson}.
+ *
+ * @param url - Absolute request URL.
+ * @param options - Method, headers, timeout, retries, logger.
+ * @returns The raw response bytes.
+ */
+declare function httpBytes(url: string, options?: HttpRequestOptions): Promise<Buffer>;
 /**
  * POST/PUT plain payloads (e.g. Slack/Teams webhook cards) with the same
  * timeout, retry, and `Retry-After` semantics as {@link httpJson}.
@@ -22,6 +31,18 @@ declare function httpJson<T>(url: string, options?: HttpRequestOptions): Promise
  * @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;
@@ -35,10 +56,14 @@ interface HttpRequestOptions {
   headers?: Record<string, string>;
   /** Body serialized as JSON with a `content-type` header. */
   json?: unknown;
+  /** Body serialized as `application/x-www-form-urlencoded` (ignored when `json` is set). */
+  form?: Record<string, string>;
   /** Per-attempt timeout in milliseconds (default 30s). */
   timeoutMs?: number;
   /** Total attempts including the first (default 3). */
   retries?: number;
+  /** Aborts the request (and any further retry) when it fires. */
+  signal?: AbortSignal;
   logger?: Logger;
 }
 /** Options for {@link httpText}. */
@@ -51,8 +76,9 @@ interface HttpTextOptions {
   timeoutMs?: number;
   /** Total attempts including the first (default 3). */
   retries?: number;
+  /** Aborts the request (and any further retry) when it fires. */
+  signal?: AbortSignal;
   logger?: Logger;
 }
-//#endregion
-export { HttpError, HttpRequestOptions, HttpTextOptions, httpJson, httpText };
+export { HttpError, HttpRequestOptions, HttpTextOptions, httpBytes, httpJson, httpStatus, httpText };
 //# sourceMappingURL=http.d.mts.map

package/dist/utils/http.mjs

@@ -1,8 +1,9 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { injectTraceContext, withSpan } from "../tracing.mjs";
-//#region src/utils/http.ts
+import { injectTraceContext, setSpanMessage, spanException, withSpan } from "../tracing.mjs";
+import { Buffer } from "node:buffer";
+// src/utils/http.ts
 /**
 * Fetch JSON with timeout, retries, and structured errors.
 *
@@ -17,6 +18,17 @@ async function httpJson(url, options = {}) {
 	return await requestWithRetry(url, options, options.retries ?? DEFAULT_RETRIES, options.timeoutMs ?? DEFAULT_TIMEOUT_MS, doFetchJson);
 }
 /**
+* Download a binary response (images) with the same timeout, retry, and
+* `Retry-After` semantics as {@link httpJson}.
+*
+* @param url - Absolute request URL.
+* @param options - Method, headers, timeout, retries, logger.
+* @returns The raw response bytes.
+*/
+async function httpBytes(url, options = {}) {
+	return await requestWithRetry(url, options, options.retries ?? DEFAULT_RETRIES, options.timeoutMs ?? DEFAULT_TIMEOUT_MS, doFetchBytes);
+}
+/**
 * POST/PUT plain payloads (e.g. Slack/Teams webhook cards) with the same
 * timeout, retry, and `Retry-After` semantics as {@link httpJson}.
 *
@@ -27,6 +39,20 @@ async function httpJson(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;
@@ -79,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));
-			if (!shouldRetry(error, attempt, maxAttempts)) throw 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");
@@ -109,6 +164,9 @@ function buildRequest(options) {
 	if (options.json !== void 0) {
 		headers["content-type"] = "application/json";
 		body = JSON.stringify(options.json);
+	} else if (options.form) {
+		headers["content-type"] = "application/x-www-form-urlencoded";
+		body = new URLSearchParams(options.form).toString();
 	}
 	return {
 		headers,
@@ -122,26 +180,49 @@ async function doFetchJson(url, options, timeoutMs) {
 async function doFetchText(url, options, timeoutMs) {
 	return await (await doFetchResponse(url, options, timeoutMs)).text();
 }
-async function doFetchResponse(url, options, timeoutMs) {
+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, 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, {
 		method: request.method,
 		headers: request.headers,
 		body: request.body,
-		signal: AbortSignal.timeout(timeoutMs)
+		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, 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 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 * 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  /** Per-attempt timeout in milliseconds (default 30s). */\n  timeoutMs?: number;\n  /** Total attempts including the first (default 3). */\n  retries?: number;\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  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 (!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  }\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 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: 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":";;;;;;;;;;;;;;;AAaA,eAAsB,SAAY,KAAa,UAA8B,CAAC,GAAe;CAC3F,OAAO,MAAM,iBACX,KACA,SACA,QAAQ,WAAW,iBACnB,QAAQ,aAAa,oBACrB,WACF;AACF;;;;;;;;;AAUA,eAAsB,SAAS,KAAa,UAA2B,CAAC,GAAoB;CAC1F,OAAO,MAAM,iBACX,KACA,SACA,QAAQ,WAAW,iBACnB,QAAQ,aAAa,oBACrB,WACF;AACF;;AAGA,IAAa,YAAb,cAA+B,MAAM;CACnC;CACA;CACA;CAEA,YAAY,QAAgB,MAAc,SAAmB;EAC3D,MAAM,QAAQ,OAAO,IAAI,MAAM;EAC/B,KAAK,OAAO;EACZ,KAAK,SAAS;EACd,KAAK,OAAO;EACZ,KAAK,UAAU,WAAW,IAAI,QAAQ;CACxC;AACF;AAeA,MAAM,qBAAqB;AAc3B,MAAM,kBAAkB;AACxB,MAAM,qBAAqB;AAC3B,MAAM,kBAAkB;AACxB,MAAM,mBAAmB;;AAGzB,SAAS,YAAY,OAAgB,SAAiB,aAA8B;CAClF,IAAI,WAAW,aACb,OAAO;CAET,IAAI,EAAE,iBAAiB,YACrB,OAAO;CAET,OAAO,MAAM,WAAW,OAAQ,MAAM,UAAU,OAAO,MAAM,UAAU;AACzE;;AAGA,SAAS,gBAAgB,OAAqC;CAC5D,IAAI,CAAC,OACH,OAAO;CAET,MAAM,UAAU,OAAO,KAAK;CAC5B,IAAI,OAAO,SAAS,OAAO,KAAK,WAAW,GACzC,OAAO,KAAK,IAAI,UAAU,KAAM,kBAAkB;CAEpD,MAAM,OAAO,KAAK,MAAM,KAAK;CAC7B,IAAI,CAAC,OAAO,MAAM,IAAI,GACpB,OAAO,KAAK,IAAI,KAAK,IAAI,OAAO,KAAK,IAAI,GAAG,CAAC,GAAG,kBAAkB;CAEpE,OAAO;AACT;;AAGA,SAAS,aAAa,OAAgB,SAAyB;CAC7D,IAAI,iBAAiB,WAAW;EAC9B,MAAM,aAAa,gBAAgB,MAAM,QAAQ,IAAI,aAAa,CAAC;EACnE,IAAI,eAAe,MACjB,OAAO;CAEX;CACA,OAAO,KAAK,IAAI,kBAAkB,MAAM,UAAU,IAAI,kBAAkB;AAC1E;;AAGA,eAAe,MAAM,IAA2B;CAC9C,MAAM,IAAI,SAAS,YAAY;EAC7B,WAAW,SAAS,EAAE;CACxB,CAAC;AACH;AAGA,eAAe,iBACb,KACA,SACA,aACA,WACA,SACY;CACZ,OAAO,MAAM,SACX,eACA,OAAO,SAAS;EACd,KAAK,IAAI,UAAU,IAAK,WAAW,GACjC,IAAI;GACF,OAAO,MAAM,QAAQ,KAAK,SAAS,SAAS;EAC9C,SAAS,OAAO;GACd,KAAK,gBAAgB,iBAAiB,QAAQ,QAAQ,OAAO,KAAK,CAAC;GACnE,IAAI,CAAC,YAAY,OAAO,SAAS,WAAW,GAC1C,MAAM;GAER,KAAK,aAAa,oBAAoB,OAAO;GAC7C,MAAM,QAAQ,OAAO,SAAS,KAAK,QAAQ,MAAM;EACnD;CAEJ,GACA;EAAE,uBAAuB,QAAQ,UAAU;EAAO,YAAY,UAAU,GAAG;CAAE,CAC/E;AACF;;AAIA,SAAS,UAAU,KAAqB;CACtC,MAAM,QAAQ,IAAI,QAAQ,GAAG;CAC7B,OAAO,UAAU,KAAK,MAAM,IAAI,MAAM,GAAG,KAAK;AAChD;AAEA,eAAe,QACb,OACA,SACA,KACA,QACe;CACf,MAAM,QAAQ,aAAa,OAAO,OAAO;CACzC,QAAQ,KAAK;EAAE;EAAK;EAAS,SAAS;CAAM,GAAG,+BAA+B;CAC9E,MAAM,MAAM,KAAK;AACnB;AAEA,SAAS,aAAa,SAIpB;CACA,MAAM,UAAkC,EAAE,GAAG,QAAQ,QAAQ;CAC7D,IAAI;CACJ,IAAI,QAAQ,SAAS,KAAA,GAAW;EAC9B,QAAQ,kBAAkB;EAC1B,OAAO,KAAK,UAAU,QAAQ,IAAI;CACpC;CACA,OAAO;EAAE;EAAS;EAAM,QAAQ,QAAQ,UAAU;CAAM;AAC1D;AAEA,eAAe,YACb,KACA,SACA,WACY;CAEZ,OAAQ,OAAM,MADS,gBAAgB,KAAK,SAAS,SAAS,EAAA,CACvC,KAAK;AAC9B;AAEA,eAAe,YACb,KACA,SACA,WACiB;CAEjB,OAAO,OAAM,MADU,gBAAgB,KAAK,SAAS,SAAS,EAAA,CACxC,KAAK;AAC7B;AAEA,eAAe,gBACb,KACA,SACA,WACmB;CACnB,MAAM,UAAU,aAAa,OAAO;CACpC,mBAAmB,QAAQ,OAAO;CAClC,QAAQ,QAAQ,MAAM;EAAE;EAAK,QAAQ,QAAQ;CAAO,GAAG,cAAc;CACrE,MAAM,WAAW,MAAM,MAAM,KAAK;EAChC,QAAQ,QAAQ;EAChB,SAAS,QAAQ;EACjB,MAAM,QAAQ;EACd,QAAQ,YAAY,QAAQ,SAAS;CACvC,CAAC;CACD,IAAI,CAAC,SAAS,IAAI;EAChB,MAAM,OAAO,MAAM,SAAS,KAAK;EACjC,MAAM,IAAI,UAAU,SAAS,QAAQ,KAAK,MAAM,GAAG,gBAAgB,GAAG,SAAS,OAAO;CACxF;CACA,OAAO;AACT"}
+{"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

@@ -0,0 +1,13 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { AdaptiveConcurrency } from "./adaptive-concurrency.mjs";
+/**
+ * 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`.
+ */
+declare function mapAdaptive<T, R>(items: readonly T[], controller: AdaptiveConcurrency, fn: (item: T, index: number) => Promise<{
+  value: R;
+  timedOut?: boolean;
+}>): Promise<R[]>;
+export { mapAdaptive };
+//# sourceMappingURL=map-adaptive.d.mts.map

package/dist/utils/map-adaptive.mjs

@@ -0,0 +1,71 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// 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`.
+*/
+async function mapAdaptive(items, controller, fn) {
+	return await new AdaptiveRun(items, controller, fn).run();
+}
+var AdaptiveRun = class {
+	results;
+	next = 0;
+	active = 0;
+	failure = null;
+	finish = null;
+	items;
+	controller;
+	fn;
+	constructor(items, controller, fn) {
+		this.items = items;
+		this.controller = controller;
+		this.fn = fn;
+		this.results = Array.from({ length: items.length });
+	}
+	async run() {
+		return await new Promise((resolve, reject) => {
+			this.finish = {
+				resolve,
+				reject
+			};
+			this.pump();
+		});
+	}
+	pump() {
+		while (this.canLaunch()) {
+			this.launch(this.next);
+			this.next += 1;
+		}
+		if (this.active === 0 && (this.failure || this.next >= this.items.length)) {
+			if (this.failure) this.finish?.reject(this.failure.error);
+			else this.finish?.resolve(this.results);
+		}
+	}
+	canLaunch() {
+		return !this.failure && this.active < this.controller.limit && this.next < this.items.length;
+	}
+	launch(index) {
+		this.active += 1;
+		const started = performance.now();
+		this.fn(this.items[index], index).then((outcome) => {
+			this.results[index] = outcome.value;
+			this.controller.observe({
+				durationMs: performance.now() - started,
+				timedOut: outcome.timedOut
+			});
+			this.settle();
+		}, (error) => {
+			this.failure ??= { error: error instanceof Error ? error : new Error(String(error)) };
+			this.settle();
+		});
+	}
+	settle() {
+		this.active -= 1;
+		this.pump();
+	}
+};
+export { mapAdaptive };
+
+//# sourceMappingURL=map-adaptive.mjs.map

package/dist/utils/map-adaptive.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-adaptive.mjs","names":[],"sources":["../../src/utils/map-adaptive.ts"],"sourcesContent":["/** `mapLimit` with a live, self-adjusting limit. */\nimport type { AdaptiveConcurrency } from \"./adaptive-concurrency.ts\";\n\n/**\n * Like `mapLimit`, but the limit is read live from `controller` and every finished item is fed\n * back to it. `fn` reports a timeout it handled itself with `timedOut: true`.\n */\nexport async function mapAdaptive<T, R>(\n  items: readonly T[],\n  controller: AdaptiveConcurrency,\n  fn: (item: T, index: number) => Promise<{ value: R; timedOut?: boolean }>,\n): Promise<R[]> {\n  return await new AdaptiveRun(items, controller, fn).run();\n}\n\nclass AdaptiveRun<T, R> {\n  private readonly results: R[];\n  private next = 0;\n  private active = 0;\n  private failure: { error: Error } | null = null;\n  private finish: { resolve: (value: R[]) => void; reject: (error: Error) => void } | null = null;\n\n  private readonly items: readonly T[];\n  private readonly controller: AdaptiveConcurrency;\n  private readonly fn: (item: T, index: number) => Promise<{ value: R; timedOut?: boolean }>;\n\n  constructor(\n    items: readonly T[],\n    controller: AdaptiveConcurrency,\n    fn: (item: T, index: number) => Promise<{ value: R; timedOut?: boolean }>,\n  ) {\n    this.items = items;\n    this.controller = controller;\n    this.fn = fn;\n    this.results = Array.from<R>({ length: items.length });\n  }\n\n  async run(): Promise<R[]> {\n    return await new Promise<R[]>((resolve, reject) => {\n      this.finish = { resolve, reject };\n      this.pump();\n    });\n  }\n\n  private pump(): void {\n    while (this.canLaunch()) {\n      this.launch(this.next);\n      this.next += 1;\n    }\n    if (this.active === 0 && (this.failure || this.next >= this.items.length)) {\n      if (this.failure) {\n        this.finish?.reject(this.failure.error);\n      } else {\n        this.finish?.resolve(this.results);\n      }\n    }\n  }\n\n  private canLaunch(): boolean {\n    return !this.failure && this.active < this.controller.limit && this.next < this.items.length;\n  }\n\n  private launch(index: number): void {\n    this.active += 1;\n    const started = performance.now();\n    this.fn(this.items[index] as T, index).then(\n      (outcome) => {\n        this.results[index] = outcome.value;\n        this.controller.observe({\n          durationMs: performance.now() - started,\n          timedOut: outcome.timedOut,\n        });\n        this.settle();\n      },\n      (error: unknown) => {\n        this.failure ??= { error: error instanceof Error ? error : new Error(String(error)) };\n        this.settle();\n      },\n    );\n  }\n\n  private settle(): void {\n    this.active -= 1;\n    this.pump();\n  }\n}\n"],"mappings":";;;;;;;;AAOA,eAAsB,YACpB,OACA,YACA,IACc;CACd,OAAO,MAAM,IAAI,YAAY,OAAO,YAAY,EAAE,CAAC,CAAC,IAAI;AAC1D;AAEA,IAAM,cAAN,MAAwB;CACtB;CACA,OAAe;CACf,SAAiB;CACjB,UAA2C;CAC3C,SAA2F;CAE3F;CACA;CACA;CAEA,YACE,OACA,YACA,IACA;EACA,KAAK,QAAQ;EACb,KAAK,aAAa;EAClB,KAAK,KAAK;EACV,KAAK,UAAU,MAAM,KAAQ,EAAE,QAAQ,MAAM,OAAO,CAAC;CACvD;CAEA,MAAM,MAAoB;EACxB,OAAO,MAAM,IAAI,SAAc,SAAS,WAAW;GACjD,KAAK,SAAS;IAAE;IAAS;GAAO;GAChC,KAAK,KAAK;EACZ,CAAC;CACH;CAEA,OAAqB;EACnB,OAAO,KAAK,UAAU,GAAG;GACvB,KAAK,OAAO,KAAK,IAAI;GACrB,KAAK,QAAQ;EACf;EACA,IAAI,KAAK,WAAW,MAAM,KAAK,WAAW,KAAK,QAAQ,KAAK,MAAM,SAAS;GACzE,IAAI,KAAK,SACP,KAAK,QAAQ,OAAO,KAAK,QAAQ,KAAK;QAEtC,KAAK,QAAQ,QAAQ,KAAK,OAAO;EAErC;CACF;CAEA,YAA6B;EAC3B,OAAO,CAAC,KAAK,WAAW,KAAK,SAAS,KAAK,WAAW,SAAS,KAAK,OAAO,KAAK,MAAM;CACxF;CAEA,OAAe,OAAqB;EAClC,KAAK,UAAU;EACf,MAAM,UAAU,YAAY,IAAI;EAChC,KAAK,GAAG,KAAK,MAAM,QAAa,KAAK,CAAC,CAAC,MACpC,YAAY;GACX,KAAK,QAAQ,SAAS,QAAQ;GAC9B,KAAK,WAAW,QAAQ;IACtB,YAAY,YAAY,IAAI,IAAI;IAChC,UAAU,QAAQ;GACpB,CAAC;GACD,KAAK,OAAO;EACd,IACC,UAAmB;GAClB,KAAK,YAAY,EAAE,OAAO,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC,EAAE;GACpF,KAAK,OAAO;EACd,CACF;CACF;CAEA,SAAuB;EACrB,KAAK,UAAU;EACf,KAAK,KAAK;CACZ;AACF"}

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

@@ -0,0 +1,8 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+/** 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[]>;
+export { chunk, mapLimit };
+//# sourceMappingURL=map-limit.d.mts.map

package/dist/utils/map-limit.mjs

@@ -0,0 +1,31 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// 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;
+	const batches = [];
+	for (let start = 0; start < items.length; start += step) batches.push(items.slice(start, start + step));
+	return batches;
+}
+/** Run `fn` over `items` with at most `limit` in flight; results keep input order. */
+async function mapLimit(items, limit, fn) {
+	const results = Array.from({ length: items.length });
+	let next = 0;
+	const worker = async () => {
+		while (next < items.length) {
+			const index = next;
+			next += 1;
+			results[index] = await fn(items[index], index);
+		}
+	};
+	const workers = Math.max(1, Math.min(Math.floor(limit) || 1, items.length));
+	await Promise.all(Array.from({ length: workers }, async () => {
+		await worker();
+	}));
+	return results;
+}
+export { chunk, mapLimit };
+
+//# sourceMappingURL=map-limit.mjs.map

package/dist/utils/map-limit.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-limit.mjs","names":[],"sources":["../../src/utils/map-limit.ts"],"sourcesContent":["/** Split `items` into consecutive batches of at most `size` (a non-positive size means one batch). */\nexport function chunk<T>(items: readonly T[], size: number): T[][] {\n  const step = size > 0 ? Math.max(1, Math.floor(size)) : items.length || 1;\n  const batches: T[][] = [];\n  for (let start = 0; start < items.length; start += step) {\n    batches.push(items.slice(start, start + step));\n  }\n  return batches;\n}\n\n/** Run `fn` over `items` with at most `limit` in flight; results keep input order. */\nexport async function mapLimit<T, R>(\n  items: readonly T[],\n  limit: number,\n  fn: (item: T, index: number) => Promise<R>,\n): Promise<R[]> {\n  const results = Array.from<R>({ length: items.length });\n  let next = 0;\n  const worker = async (): Promise<void> => {\n    while (next < items.length) {\n      const index = next;\n      next += 1;\n      // oxlint-disable-next-line eslint/no-await-in-loop -- bounded worker pulls sequentially\n      results[index] = await fn(items[index] as T, index);\n    }\n  };\n  const workers = Math.max(1, Math.min(Math.floor(limit) || 1, items.length));\n  await Promise.all(\n    Array.from({ length: workers }, async () => {\n      await worker();\n    }),\n  );\n  return results;\n}\n"],"mappings":";;;;;AACA,SAAgB,MAAS,OAAqB,MAAqB;CACjE,MAAM,OAAO,OAAO,IAAI,KAAK,IAAI,GAAG,KAAK,MAAM,IAAI,CAAC,IAAI,MAAM,UAAU;CACxE,MAAM,UAAiB,CAAC;CACxB,KAAK,IAAI,QAAQ,GAAG,QAAQ,MAAM,QAAQ,SAAS,MACjD,QAAQ,KAAK,MAAM,MAAM,OAAO,QAAQ,IAAI,CAAC;CAE/C,OAAO;AACT;;AAGA,eAAsB,SACpB,OACA,OACA,IACc;CACd,MAAM,UAAU,MAAM,KAAQ,EAAE,QAAQ,MAAM,OAAO,CAAC;CACtD,IAAI,OAAO;CACX,MAAM,SAAS,YAA2B;EACxC,OAAO,OAAO,MAAM,QAAQ;GAC1B,MAAM,QAAQ;GACd,QAAQ;GAER,QAAQ,SAAS,MAAM,GAAG,MAAM,QAAa,KAAK;EACpD;CACF;CACA,MAAM,UAAU,KAAK,IAAI,GAAG,KAAK,IAAI,KAAK,MAAM,KAAK,KAAK,GAAG,MAAM,MAAM,CAAC;CAC1E,MAAM,QAAQ,IACZ,MAAM,KAAK,EAAE,QAAQ,QAAQ,GAAG,YAAY;EAC1C,MAAM,OAAO;CACf,CAAC,CACH;CACA,OAAO;AACT"}

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

@@ -0,0 +1,35 @@
+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";
+/** Options for {@link createPageLimiter}. */
+interface PageLimiterOptions {
+  /** Explicit page count (config or run input). Fixed: the adaptive controller stays off. */
+  concurrency?: number;
+  /**
+   * A remote target's session cap, shared by every render of that target in the process. It
+   * replaces CPU and memory sizing: the plan's parallel-session limit is the budget, not this host.
+   * An explicit `concurrency` can lower a run's share of it, never raise it.
+   */
+  gate?: SessionGate;
+  /** Engine being rendered; heavier engines get a smaller budget. */
+  browser?: string;
+  logger?: Logger;
+}
+/** Runs capture jobs under a page limit. One limiter spans a whole run so what it learns carries across batches. */
+interface PageLimiter {
+  /**
+   * Run `fn` over `items`. `fn` resolves to whether the capture timed out (it handles its own
+   * failures, so the limiter cannot see them otherwise).
+   */
+  each<T>(items: readonly T[], fn: (item: T) => Promise<boolean>): Promise<void>;
+  /** Release the event-loop monitor. */
+  dispose(): void;
+}
+/**
+ * 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.
+ */
+declare function createPageLimiter(options: PageLimiterOptions): PageLimiter;
+export { PageLimiter, PageLimiterOptions, createPageLimiter };
+//# sourceMappingURL=page-limiter.d.mts.map