@storyshelf/core 0.6.1 → 0.7.0

package/dist/urls.mjs

@@ -19,12 +19,14 @@ function createUrlBuilder(baseUrl, publishedBaseDomain) {
 		buildsList: (slug) => `${root}/projects/${slug}/builds`,
 		build: (slug, buildId) => `${root}/projects/${slug}/builds/${buildId}`,
 		buildDiff: (slug, buildId) => `${root}/projects/${slug}/builds/${buildId}/diff`,
+		snapshot: (slug, buildId, snapshotId) => `${root}/projects/${slug}/builds/${buildId}/diff?snapshot=${encodeURIComponent(snapshotId)}`,
 		library: (slug) => `${root}/projects/${slug}/library`,
 		jobs: (slug) => `${root}/projects/${slug}/jobs`,
 		labels: (slug) => `${root}/projects/${slug}/labels`,
-		label: (slug, key, value) => `${root}/projects/${slug}/labels/${encodeURIComponent(key)}/${encodeURI(value)}`,
+		label: (slug, key, value) => `${root}/projects/${slug}/labels/${encodeURIComponent(key)}/${encodePath(value)}`,
+		component: (slug, importPath) => `${root}/projects/${slug}/components/${encodePath(importPath.replace(/^(?:\.\/)+/u, ""))}`,
 		storybook: (slug) => publishedBaseDomain ? `https://${slug}.${publishedBaseDomain}` : `${root}/projects/${slug}/storybook`,
-		storybookLabel: (slug, key, value) => `${root}/projects/${slug}/storybook/${encodeURIComponent(key)}/${encodeURI(value)}`,
+		storybookLabel: (slug, key, value) => `${root}/projects/${slug}/storybook/${encodeURIComponent(key)}/${encodePath(value)}`,
 		storybookBuild: (slug, buildId) => publishedBaseDomain ? `https://${buildId}.${slug}.${publishedBaseDomain}` : `${root}/projects/${slug}/storybook/build/${buildId}`,
 		settings: (slug) => `${root}/projects/${slug}/settings`,
 		short: (id) => `${root}/_/${id}/`
@@ -43,6 +45,13 @@ function safeImageUrl(value) {
 		return null;
 	}
 }
+/**
+* Encode a value that may hold slashes (a label value, a branch, an import path) as URL path
+* segments: each segment is escaped (`?`, `#` and `%` included), the slashes stay.
+*/
+function encodePath(value) {
+	return value.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+}
 //#endregion
 export { createUrlBuilder, safeImageUrl };
 

package/dist/urls.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"urls.mjs","names":[],"sources":["../src/urls.ts"],"sourcesContent":["/** Type-safe URL builder for project pages and published Storybooks. */\nexport interface UrlBuilder {\n  projectsList(): string;\n  projects(): string;\n  project(slug: string): string;\n  projectsNew(): string;\n  buildsList(slug: string): string;\n  build(slug: string, buildId: string): string;\n  buildDiff(slug: string, buildId: string): string;\n  library(slug: string): string;\n  jobs(slug: string): string;\n  labels(slug: string): string;\n  label(slug: string, key: string, value: string): string;\n  storybook(slug: string): string;\n  storybookLabel(slug: string, key: string, value: string): string;\n  storybookBuild(slug: string, buildId: string): string;\n  settings(slug: string): string;\n  short(id: string): string;\n}\n\n/**\n * Create a URL builder rooted at the given base URL.\n *\n * @param baseUrl - Public root URL of the shelf server.\n * @param publishedBaseDomain - Optional wildcard domain for published Storybooks.\n * @returns The URL builder.\n */\nexport function createUrlBuilder(baseUrl: string, publishedBaseDomain?: string): UrlBuilder {\n  const root = baseUrl.replace(/\\/+$/u, \"\");\n\n  return {\n    projectsList: () => root || \"/\",\n    projects: () => `${root}/projects`,\n    project: (slug) => `${root}/projects/${slug}`,\n    projectsNew: () => `${root}/projects/new`,\n    buildsList: (slug) => `${root}/projects/${slug}/builds`,\n    build: (slug, buildId) => `${root}/projects/${slug}/builds/${buildId}`,\n    buildDiff: (slug, buildId) => `${root}/projects/${slug}/builds/${buildId}/diff`,\n    library: (slug) => `${root}/projects/${slug}/library`,\n    jobs: (slug) => `${root}/projects/${slug}/jobs`,\n    labels: (slug) => `${root}/projects/${slug}/labels`,\n    label: (slug, key, value) =>\n      `${root}/projects/${slug}/labels/${encodeURIComponent(key)}/${encodeURI(value)}`,\n    storybook: (slug) =>\n      publishedBaseDomain\n        ? `https://${slug}.${publishedBaseDomain}`\n        : `${root}/projects/${slug}/storybook`,\n    storybookLabel: (slug, key, value) =>\n      `${root}/projects/${slug}/storybook/${encodeURIComponent(key)}/${encodeURI(value)}`,\n    storybookBuild: (slug, buildId) =>\n      publishedBaseDomain\n        ? `https://${buildId}.${slug}.${publishedBaseDomain}`\n        : `${root}/projects/${slug}/storybook/build/${buildId}`,\n    settings: (slug) => `${root}/projects/${slug}/settings`,\n    short: (id) => `${root}/_/${id}/`,\n  };\n}\n\n/**\n * Embeddable image URL check for IdP-supplied avatars: `https:` and\n * app-relative paths only, so `javascript:`/`data:` payloads fall back.\n */\nexport function safeImageUrl(value: string | undefined): string | null {\n  if (!value) {\n    return null;\n  }\n  if (value.startsWith(\"/\") && !value.startsWith(\"//\")) {\n    return value;\n  }\n  try {\n    const url = new URL(value);\n    return url.protocol === \"https:\" ? value : null;\n  } catch {\n    return null;\n  }\n}\n"],"mappings":";;;;;;;;;;;AA2BA,SAAgB,iBAAiB,SAAiB,qBAA0C;CAC1F,MAAM,OAAO,QAAQ,QAAQ,SAAS,EAAE;CAExC,OAAO;EACL,oBAAoB,QAAQ;EAC5B,gBAAgB,GAAG,KAAK;EACxB,UAAU,SAAS,GAAG,KAAK,YAAY;EACvC,mBAAmB,GAAG,KAAK;EAC3B,aAAa,SAAS,GAAG,KAAK,YAAY,KAAK;EAC/C,QAAQ,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,UAAU;EAC7D,YAAY,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,UAAU,QAAQ;EACzE,UAAU,SAAS,GAAG,KAAK,YAAY,KAAK;EAC5C,OAAO,SAAS,GAAG,KAAK,YAAY,KAAK;EACzC,SAAS,SAAS,GAAG,KAAK,YAAY,KAAK;EAC3C,QAAQ,MAAM,KAAK,UACjB,GAAG,KAAK,YAAY,KAAK,UAAU,mBAAmB,GAAG,EAAE,GAAG,UAAU,KAAK;EAC/E,YAAY,SACV,sBACI,WAAW,KAAK,GAAG,wBACnB,GAAG,KAAK,YAAY,KAAK;EAC/B,iBAAiB,MAAM,KAAK,UAC1B,GAAG,KAAK,YAAY,KAAK,aAAa,mBAAmB,GAAG,EAAE,GAAG,UAAU,KAAK;EAClF,iBAAiB,MAAM,YACrB,sBACI,WAAW,QAAQ,GAAG,KAAK,GAAG,wBAC9B,GAAG,KAAK,YAAY,KAAK,mBAAmB;EAClD,WAAW,SAAS,GAAG,KAAK,YAAY,KAAK;EAC7C,QAAQ,OAAO,GAAG,KAAK,KAAK,GAAG;CACjC;AACF;;;;;AAMA,SAAgB,aAAa,OAA0C;CACrE,IAAI,CAAC,OACH,OAAO;CAET,IAAI,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,WAAW,IAAI,GACjD,OAAO;CAET,IAAI;EAEF,OAAO,IADS,IAAI,KACX,CAAC,CAAC,aAAa,WAAW,QAAQ;CAC7C,QAAQ;EACN,OAAO;CACT;AACF"}
+{"version":3,"file":"urls.mjs","names":[],"sources":["../src/urls.ts"],"sourcesContent":["/** Type-safe URL builder for project pages and published Storybooks. */\nexport interface UrlBuilder {\n  projectsList(): string;\n  projects(): string;\n  project(slug: string): string;\n  projectsNew(): string;\n  buildsList(slug: string): string;\n  build(slug: string, buildId: string): string;\n  buildDiff(slug: string, buildId: string): string;\n  /** Review page of one snapshot: the build's diff page with that snapshot selected. */\n  snapshot(slug: string, buildId: string, snapshotId: string): string;\n  library(slug: string): string;\n  jobs(slug: string): string;\n  labels(slug: string): string;\n  label(slug: string, key: string, value: string): string;\n  /** Stable component page, keyed by the story file's import path. */\n  component(slug: string, importPath: string): string;\n  storybook(slug: string): string;\n  storybookLabel(slug: string, key: string, value: string): string;\n  storybookBuild(slug: string, buildId: string): string;\n  settings(slug: string): string;\n  short(id: string): string;\n}\n\n/**\n * Create a URL builder rooted at the given base URL.\n *\n * @param baseUrl - Public root URL of the shelf server.\n * @param publishedBaseDomain - Optional wildcard domain for published Storybooks.\n * @returns The URL builder.\n */\nexport function createUrlBuilder(baseUrl: string, publishedBaseDomain?: string): UrlBuilder {\n  const root = baseUrl.replace(/\\/+$/u, \"\");\n\n  return {\n    projectsList: () => root || \"/\",\n    projects: () => `${root}/projects`,\n    project: (slug) => `${root}/projects/${slug}`,\n    projectsNew: () => `${root}/projects/new`,\n    buildsList: (slug) => `${root}/projects/${slug}/builds`,\n    build: (slug, buildId) => `${root}/projects/${slug}/builds/${buildId}`,\n    buildDiff: (slug, buildId) => `${root}/projects/${slug}/builds/${buildId}/diff`,\n    snapshot: (slug, buildId, snapshotId) =>\n      `${root}/projects/${slug}/builds/${buildId}/diff?snapshot=${encodeURIComponent(snapshotId)}`,\n    library: (slug) => `${root}/projects/${slug}/library`,\n    jobs: (slug) => `${root}/projects/${slug}/jobs`,\n    labels: (slug) => `${root}/projects/${slug}/labels`,\n    label: (slug, key, value) =>\n      `${root}/projects/${slug}/labels/${encodeURIComponent(key)}/${encodePath(value)}`,\n    component: (slug, importPath) =>\n      `${root}/projects/${slug}/components/${encodePath(importPath.replace(/^(?:\\.\\/)+/u, \"\"))}`,\n    storybook: (slug) =>\n      publishedBaseDomain\n        ? `https://${slug}.${publishedBaseDomain}`\n        : `${root}/projects/${slug}/storybook`,\n    storybookLabel: (slug, key, value) =>\n      `${root}/projects/${slug}/storybook/${encodeURIComponent(key)}/${encodePath(value)}`,\n    storybookBuild: (slug, buildId) =>\n      publishedBaseDomain\n        ? `https://${buildId}.${slug}.${publishedBaseDomain}`\n        : `${root}/projects/${slug}/storybook/build/${buildId}`,\n    settings: (slug) => `${root}/projects/${slug}/settings`,\n    short: (id) => `${root}/_/${id}/`,\n  };\n}\n\n/**\n * Embeddable image URL check for IdP-supplied avatars: `https:` and\n * app-relative paths only, so `javascript:`/`data:` payloads fall back.\n */\nexport function safeImageUrl(value: string | undefined): string | null {\n  if (!value) {\n    return null;\n  }\n  if (value.startsWith(\"/\") && !value.startsWith(\"//\")) {\n    return value;\n  }\n  try {\n    const url = new URL(value);\n    return url.protocol === \"https:\" ? value : null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Encode a value that may hold slashes (a label value, a branch, an import path) as URL path\n * segments: each segment is escaped (`?`, `#` and `%` included), the slashes stay.\n */\nfunction encodePath(value: string): string {\n  return value\n    .split(\"/\")\n    .map((segment) => encodeURIComponent(segment))\n    .join(\"/\");\n}\n"],"mappings":";;;;;;;;;;;AA+BA,SAAgB,iBAAiB,SAAiB,qBAA0C;CAC1F,MAAM,OAAO,QAAQ,QAAQ,SAAS,EAAE;CAExC,OAAO;EACL,oBAAoB,QAAQ;EAC5B,gBAAgB,GAAG,KAAK;EACxB,UAAU,SAAS,GAAG,KAAK,YAAY;EACvC,mBAAmB,GAAG,KAAK;EAC3B,aAAa,SAAS,GAAG,KAAK,YAAY,KAAK;EAC/C,QAAQ,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,UAAU;EAC7D,YAAY,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,UAAU,QAAQ;EACzE,WAAW,MAAM,SAAS,eACxB,GAAG,KAAK,YAAY,KAAK,UAAU,QAAQ,iBAAiB,mBAAmB,UAAU;EAC3F,UAAU,SAAS,GAAG,KAAK,YAAY,KAAK;EAC5C,OAAO,SAAS,GAAG,KAAK,YAAY,KAAK;EACzC,SAAS,SAAS,GAAG,KAAK,YAAY,KAAK;EAC3C,QAAQ,MAAM,KAAK,UACjB,GAAG,KAAK,YAAY,KAAK,UAAU,mBAAmB,GAAG,EAAE,GAAG,WAAW,KAAK;EAChF,YAAY,MAAM,eAChB,GAAG,KAAK,YAAY,KAAK,cAAc,WAAW,WAAW,QAAQ,eAAe,EAAE,CAAC;EACzF,YAAY,SACV,sBACI,WAAW,KAAK,GAAG,wBACnB,GAAG,KAAK,YAAY,KAAK;EAC/B,iBAAiB,MAAM,KAAK,UAC1B,GAAG,KAAK,YAAY,KAAK,aAAa,mBAAmB,GAAG,EAAE,GAAG,WAAW,KAAK;EACnF,iBAAiB,MAAM,YACrB,sBACI,WAAW,QAAQ,GAAG,KAAK,GAAG,wBAC9B,GAAG,KAAK,YAAY,KAAK,mBAAmB;EAClD,WAAW,SAAS,GAAG,KAAK,YAAY,KAAK;EAC7C,QAAQ,OAAO,GAAG,KAAK,KAAK,GAAG;CACjC;AACF;;;;;AAMA,SAAgB,aAAa,OAA0C;CACrE,IAAI,CAAC,OACH,OAAO;CAET,IAAI,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,WAAW,IAAI,GACjD,OAAO;CAET,IAAI;EAEF,OAAO,IADS,IAAI,KACX,CAAC,CAAC,aAAa,WAAW,QAAQ;CAC7C,QAAQ;EACN,OAAO;CACT;AACF;;;;;AAMA,SAAS,WAAW,OAAuB;CACzC,OAAO,MACJ,MAAM,GAAG,CAAC,CACV,KAAK,YAAY,mBAAmB,OAAO,CAAC,CAAC,CAC7C,KAAK,GAAG;AACb"}

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

@@ -0,0 +1,66 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Logger } from "../logger.mjs";
+//#region src/utils/adaptive-concurrency.d.ts
+/** Tuning for {@link AdaptiveConcurrency}. */
+interface AdaptiveOptions {
+  /** Starting in-flight limit. */
+  initial: number;
+  /** Lowest limit (default 1). */
+  min?: number;
+  /** Highest limit. */
+  max: number;
+  /** Event-loop lag p99 (ms) since the previous reading; defaults to a `perf_hooks` histogram. */
+  readLagMs?: () => number;
+  /** p95 latency may grow this much over the first window before the window counts as unhealthy (default 1.25). */
+  latencyTolerance?: number;
+  /** Event-loop lag p99 above this (ms) counts as unhealthy (default 100). */
+  lagLimitMs?: number;
+  /** Windows to hold after a timeout back-off before raising again (default 3). */
+  holdWindows?: number;
+  /** Scoped logger; every limit change is logged with its reason. */
+  logger?: Logger;
+}
+/** What one finished capture reports. */
+interface Observation {
+  durationMs: number;
+  /** The capture hit a navigation/action timeout. */
+  timedOut?: boolean;
+}
+/**
+ * AIMD controller over the number of pages rendering at once.
+ *
+ * Captures are grouped in windows (at least 8, or two per slot). A window with any timeout halves
+ * the limit and holds it there for a few windows; a window whose p95 latency grew more than the
+ * tolerance over the first window, or whose event-loop lag p99 is high, lowers it by one; a healthy
+ * window raises it by one. The first window without timeouts sets the latency baseline, so it only
+ * ever holds.
+ */
+declare class AdaptiveConcurrency {
+  private current;
+  private readonly min;
+  private readonly max;
+  private readonly options;
+  private window;
+  private baselineP95;
+  private hold;
+  private readonly lag;
+  constructor(options: AdaptiveOptions);
+  /** Pages allowed in flight right now. */
+  get limit(): number;
+  /** Record a finished capture; may change {@link limit} at a window boundary. */
+  observe(observation: Observation): void;
+  /** Release the lag monitor. */
+  dispose(): void;
+  private closeWindow;
+  /** Decide what a finished window means; updates the post-back-off hold. */
+  private judge;
+  /** A healthy window: set the baseline, sit out a back-off hold, or raise by one. */
+  private raiseOrHold;
+  private isSlow;
+}
+/** Whether an error is a navigation/action timeout (Playwright and Puppeteer both name it `TimeoutError`). */
+declare function isTimeoutError(error: unknown): boolean;
+//#endregion
+export { AdaptiveConcurrency, AdaptiveOptions, Observation, isTimeoutError };
+//# sourceMappingURL=adaptive-concurrency.d.mts.map

package/dist/utils/adaptive-concurrency.mjs

@@ -0,0 +1,149 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { monitorEventLoopDelay } from "node:perf_hooks";
+//#region src/utils/adaptive-concurrency.ts
+/** Adaptive page concurrency: raise while capture stays healthy, back off when it does not. */
+const MIN_WINDOW = 8;
+/**
+* AIMD controller over the number of pages rendering at once.
+*
+* Captures are grouped in windows (at least 8, or two per slot). A window with any timeout halves
+* the limit and holds it there for a few windows; a window whose p95 latency grew more than the
+* tolerance over the first window, or whose event-loop lag p99 is high, lowers it by one; a healthy
+* window raises it by one. The first window without timeouts sets the latency baseline, so it only
+* ever holds.
+*/
+var AdaptiveConcurrency = class {
+	current;
+	min;
+	max;
+	options;
+	window = [];
+	baselineP95 = null;
+	hold = 0;
+	lag;
+	constructor(options) {
+		this.options = options;
+		this.min = Math.max(1, Math.floor(options.min ?? 1));
+		this.max = Math.max(this.min, Math.floor(options.max));
+		this.current = clamp(Math.floor(options.initial), this.min, this.max);
+		this.lag = options.readLagMs ? {
+			read: options.readLagMs,
+			stop: noop
+		} : eventLoopLagReader();
+	}
+	/** Pages allowed in flight right now. */
+	get limit() {
+		return this.current;
+	}
+	/** Record a finished capture; may change {@link limit} at a window boundary. */
+	observe(observation) {
+		this.window.push(observation);
+		if (this.window.length >= Math.max(MIN_WINDOW, this.current * 2)) this.closeWindow();
+	}
+	/** Release the lag monitor. */
+	dispose() {
+		this.lag.stop();
+	}
+	closeWindow() {
+		const samples = this.window;
+		this.window = [];
+		const stats = {
+			p95: percentile(samples.map((sample) => sample.durationMs), .95),
+			timeouts: samples.filter((sample) => sample.timedOut).length,
+			lagP99: this.lag.read()
+		};
+		const from = this.current;
+		const verdict = this.judge(stats);
+		if (stats.timeouts === 0) this.baselineP95 ??= stats.p95;
+		this.current = verdict.halve ? Math.max(this.min, Math.floor(from / 2)) : clamp(from + verdict.delta, this.min, this.max);
+		if (this.current !== from) this.options.logger?.info({
+			from,
+			to: this.current,
+			reason: verdict.reason,
+			...roundedStats(stats)
+		}, "capture concurrency adjusted");
+	}
+	/** Decide what a finished window means; updates the post-back-off hold. */
+	judge(window) {
+		if (window.timeouts > 0) {
+			this.hold = this.options.holdWindows ?? 3;
+			return {
+				delta: 0,
+				halve: true,
+				reason: "timeouts"
+			};
+		}
+		const slow = this.isSlow(window.p95);
+		if (slow || window.lagP99 > (this.options.lagLimitMs ?? 100)) return {
+			delta: -1,
+			halve: false,
+			reason: slow ? "latency" : "event-loop lag"
+		};
+		return this.raiseOrHold();
+	}
+	/** A healthy window: set the baseline, sit out a back-off hold, or raise by one. */
+	raiseOrHold() {
+		if (this.baselineP95 === null) return {
+			delta: 0,
+			halve: false,
+			reason: "baseline"
+		};
+		if (this.hold > 0) {
+			this.hold -= 1;
+			return {
+				delta: 0,
+				halve: false,
+				reason: "holding after back-off"
+			};
+		}
+		return {
+			delta: 1,
+			halve: false,
+			reason: "healthy"
+		};
+	}
+	isSlow(p95) {
+		return this.baselineP95 !== null && p95 > this.baselineP95 * (this.options.latencyTolerance ?? 1.25);
+	}
+};
+function roundedStats(stats) {
+	return {
+		p95Ms: Math.round(stats.p95),
+		lagP99Ms: Math.round(stats.lagP99),
+		timeouts: stats.timeouts
+	};
+}
+/** Whether an error is a navigation/action timeout (Playwright and Puppeteer both name it `TimeoutError`). */
+function isTimeoutError(error) {
+	if (!(error instanceof Error)) return false;
+	return error.name === "TimeoutError" || /\btimed? ?out\b/iu.test(error.message);
+}
+function noop() {}
+function clamp(value, min, max) {
+	return Math.min(max, Math.max(min, value));
+}
+function percentile(values, fraction) {
+	const sorted = values.toSorted((left, right) => left - right);
+	return sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * fraction))] ?? 0;
+}
+/** p99 event-loop delay (ms) since the previous read, from a `perf_hooks` histogram. */
+function eventLoopLagReader() {
+	const histogram = monitorEventLoopDelay({ resolution: 10 });
+	histogram.enable();
+	return {
+		read: () => {
+			const lag = histogram.percentile(99) / 1e6;
+			histogram.reset();
+			return lag;
+		},
+		stop: () => {
+			histogram.disable();
+		}
+	};
+}
+//#endregion
+export { AdaptiveConcurrency, isTimeoutError };
+
+//# sourceMappingURL=adaptive-concurrency.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive-concurrency.mjs","names":[],"sources":["../../src/utils/adaptive-concurrency.ts"],"sourcesContent":["/** Adaptive page concurrency: raise while capture stays healthy, back off when it does not. */\nimport { monitorEventLoopDelay } from \"node:perf_hooks\";\nimport type { Logger } from \"../logger.ts\";\n\n/** Tuning for {@link AdaptiveConcurrency}. */\nexport interface AdaptiveOptions {\n  /** Starting in-flight limit. */\n  initial: number;\n  /** Lowest limit (default 1). */\n  min?: number;\n  /** Highest limit. */\n  max: number;\n  /** Event-loop lag p99 (ms) since the previous reading; defaults to a `perf_hooks` histogram. */\n  readLagMs?: () => number;\n  /** p95 latency may grow this much over the first window before the window counts as unhealthy (default 1.25). */\n  latencyTolerance?: number;\n  /** Event-loop lag p99 above this (ms) counts as unhealthy (default 100). */\n  lagLimitMs?: number;\n  /** Windows to hold after a timeout back-off before raising again (default 3). */\n  holdWindows?: number;\n  /** Scoped logger; every limit change is logged with its reason. */\n  logger?: Logger;\n}\n\n/** What one finished capture reports. */\nexport interface Observation {\n  durationMs: number;\n  /** The capture hit a navigation/action timeout. */\n  timedOut?: boolean;\n}\n\nconst MIN_WINDOW = 8;\n\n/**\n * AIMD controller over the number of pages rendering at once.\n *\n * Captures are grouped in windows (at least 8, or two per slot). A window with any timeout halves\n * the limit and holds it there for a few windows; a window whose p95 latency grew more than the\n * tolerance over the first window, or whose event-loop lag p99 is high, lowers it by one; a healthy\n * window raises it by one. The first window without timeouts sets the latency baseline, so it only\n * ever holds.\n */\nexport class AdaptiveConcurrency {\n  private current: number;\n  private readonly min: number;\n  private readonly max: number;\n  private readonly options: AdaptiveOptions;\n  private window: Observation[] = [];\n  private baselineP95: number | null = null;\n  private hold = 0;\n  private readonly lag: { read: () => number; stop: () => void };\n\n  constructor(options: AdaptiveOptions) {\n    this.options = options;\n    this.min = Math.max(1, Math.floor(options.min ?? 1));\n    this.max = Math.max(this.min, Math.floor(options.max));\n    this.current = clamp(Math.floor(options.initial), this.min, this.max);\n    this.lag = options.readLagMs ? { read: options.readLagMs, stop: noop } : eventLoopLagReader();\n  }\n\n  /** Pages allowed in flight right now. */\n  get limit(): number {\n    return this.current;\n  }\n\n  /** Record a finished capture; may change {@link limit} at a window boundary. */\n  observe(observation: Observation): void {\n    this.window.push(observation);\n    if (this.window.length >= Math.max(MIN_WINDOW, this.current * 2)) {\n      this.closeWindow();\n    }\n  }\n\n  /** Release the lag monitor. */\n  dispose(): void {\n    this.lag.stop();\n  }\n\n  private closeWindow(): void {\n    const samples = this.window;\n    this.window = [];\n    const stats = {\n      p95: percentile(\n        samples.map((sample) => sample.durationMs),\n        0.95,\n      ),\n      timeouts: samples.filter((sample) => sample.timedOut).length,\n      lagP99: this.lag.read(),\n    };\n    const from = this.current;\n    const verdict = this.judge(stats);\n    // A window with a timeout carries the timeout's duration in its p95: never a baseline.\n    if (stats.timeouts === 0) {\n      this.baselineP95 ??= stats.p95;\n    }\n    this.current = verdict.halve\n      ? Math.max(this.min, Math.floor(from / 2))\n      : clamp(from + verdict.delta, this.min, this.max);\n    if (this.current !== from) {\n      this.options.logger?.info(\n        { from, to: this.current, reason: verdict.reason, ...roundedStats(stats) },\n        \"capture concurrency adjusted\",\n      );\n    }\n  }\n\n  /** Decide what a finished window means; updates the post-back-off hold. */\n  private judge(window: WindowStats): Verdict {\n    if (window.timeouts > 0) {\n      this.hold = this.options.holdWindows ?? 3;\n      return { delta: 0, halve: true, reason: \"timeouts\" };\n    }\n    const slow = this.isSlow(window.p95);\n    if (slow || window.lagP99 > (this.options.lagLimitMs ?? 100)) {\n      return { delta: -1, halve: false, reason: slow ? \"latency\" : \"event-loop lag\" };\n    }\n    return this.raiseOrHold();\n  }\n\n  /** A healthy window: set the baseline, sit out a back-off hold, or raise by one. */\n  private raiseOrHold(): Verdict {\n    if (this.baselineP95 === null) {\n      return { delta: 0, halve: false, reason: \"baseline\" };\n    }\n    if (this.hold > 0) {\n      this.hold -= 1;\n      return { delta: 0, halve: false, reason: \"holding after back-off\" };\n    }\n    return { delta: 1, halve: false, reason: \"healthy\" };\n  }\n\n  private isSlow(p95: number): boolean {\n    return (\n      this.baselineP95 !== null && p95 > this.baselineP95 * (this.options.latencyTolerance ?? 1.25)\n    );\n  }\n}\n\ninterface WindowStats {\n  p95: number;\n  timeouts: number;\n  lagP99: number;\n}\n\nfunction roundedStats(stats: WindowStats): Record<string, number> {\n  return {\n    p95Ms: Math.round(stats.p95),\n    lagP99Ms: Math.round(stats.lagP99),\n    timeouts: stats.timeouts,\n  };\n}\n\ninterface Verdict {\n  delta: number;\n  halve: boolean;\n  reason: string;\n}\n\n/** Whether an error is a navigation/action timeout (Playwright and Puppeteer both name it `TimeoutError`). */\nexport function isTimeoutError(error: unknown): boolean {\n  if (!(error instanceof Error)) {\n    return false;\n  }\n  return error.name === \"TimeoutError\" || /\\btimed? ?out\\b/iu.test(error.message);\n}\n\nfunction noop(): void {}\n\nfunction clamp(value: number, min: number, max: number): number {\n  return Math.min(max, Math.max(min, value));\n}\n\nfunction percentile(values: number[], fraction: number): number {\n  const sorted = values.toSorted((left, right) => left - right);\n  return sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * fraction))] ?? 0;\n}\n\n/** p99 event-loop delay (ms) since the previous read, from a `perf_hooks` histogram. */\nfunction eventLoopLagReader(): { read: () => number; stop: () => void } {\n  const histogram = monitorEventLoopDelay({ resolution: 10 });\n  histogram.enable();\n  return {\n    read: () => {\n      const lag = histogram.percentile(99) / 1e6;\n      histogram.reset();\n      return lag;\n    },\n    stop: () => {\n      histogram.disable();\n    },\n  };\n}\n"],"mappings":";;;;;;AA+BA,MAAM,aAAa;;;;;;;;;;AAWnB,IAAa,sBAAb,MAAiC;CAC/B;CACA;CACA;CACA;CACA,SAAgC,CAAC;CACjC,cAAqC;CACrC,OAAe;CACf;CAEA,YAAY,SAA0B;EACpC,KAAK,UAAU;EACf,KAAK,MAAM,KAAK,IAAI,GAAG,KAAK,MAAM,QAAQ,OAAO,CAAC,CAAC;EACnD,KAAK,MAAM,KAAK,IAAI,KAAK,KAAK,KAAK,MAAM,QAAQ,GAAG,CAAC;EACrD,KAAK,UAAU,MAAM,KAAK,MAAM,QAAQ,OAAO,GAAG,KAAK,KAAK,KAAK,GAAG;EACpE,KAAK,MAAM,QAAQ,YAAY;GAAE,MAAM,QAAQ;GAAW,MAAM;EAAK,IAAI,mBAAmB;CAC9F;;CAGA,IAAI,QAAgB;EAClB,OAAO,KAAK;CACd;;CAGA,QAAQ,aAAgC;EACtC,KAAK,OAAO,KAAK,WAAW;EAC5B,IAAI,KAAK,OAAO,UAAU,KAAK,IAAI,YAAY,KAAK,UAAU,CAAC,GAC7D,KAAK,YAAY;CAErB;;CAGA,UAAgB;EACd,KAAK,IAAI,KAAK;CAChB;CAEA,cAA4B;EAC1B,MAAM,UAAU,KAAK;EACrB,KAAK,SAAS,CAAC;EACf,MAAM,QAAQ;GACZ,KAAK,WACH,QAAQ,KAAK,WAAW,OAAO,UAAU,GACzC,GACF;GACA,UAAU,QAAQ,QAAQ,WAAW,OAAO,QAAQ,CAAC,CAAC;GACtD,QAAQ,KAAK,IAAI,KAAK;EACxB;EACA,MAAM,OAAO,KAAK;EAClB,MAAM,UAAU,KAAK,MAAM,KAAK;EAEhC,IAAI,MAAM,aAAa,GACrB,KAAK,gBAAgB,MAAM;EAE7B,KAAK,UAAU,QAAQ,QACnB,KAAK,IAAI,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC,CAAC,IACvC,MAAM,OAAO,QAAQ,OAAO,KAAK,KAAK,KAAK,GAAG;EAClD,IAAI,KAAK,YAAY,MACnB,KAAK,QAAQ,QAAQ,KACnB;GAAE;GAAM,IAAI,KAAK;GAAS,QAAQ,QAAQ;GAAQ,GAAG,aAAa,KAAK;EAAE,GACzE,8BACF;CAEJ;;CAGA,MAAc,QAA8B;EAC1C,IAAI,OAAO,WAAW,GAAG;GACvB,KAAK,OAAO,KAAK,QAAQ,eAAe;GACxC,OAAO;IAAE,OAAO;IAAG,OAAO;IAAM,QAAQ;GAAW;EACrD;EACA,MAAM,OAAO,KAAK,OAAO,OAAO,GAAG;EACnC,IAAI,QAAQ,OAAO,UAAU,KAAK,QAAQ,cAAc,MACtD,OAAO;GAAE,OAAO;GAAI,OAAO;GAAO,QAAQ,OAAO,YAAY;EAAiB;EAEhF,OAAO,KAAK,YAAY;CAC1B;;CAGA,cAA+B;EAC7B,IAAI,KAAK,gBAAgB,MACvB,OAAO;GAAE,OAAO;GAAG,OAAO;GAAO,QAAQ;EAAW;EAEtD,IAAI,KAAK,OAAO,GAAG;GACjB,KAAK,QAAQ;GACb,OAAO;IAAE,OAAO;IAAG,OAAO;IAAO,QAAQ;GAAyB;EACpE;EACA,OAAO;GAAE,OAAO;GAAG,OAAO;GAAO,QAAQ;EAAU;CACrD;CAEA,OAAe,KAAsB;EACnC,OACE,KAAK,gBAAgB,QAAQ,MAAM,KAAK,eAAe,KAAK,QAAQ,oBAAoB;CAE5F;AACF;AAQA,SAAS,aAAa,OAA4C;CAChE,OAAO;EACL,OAAO,KAAK,MAAM,MAAM,GAAG;EAC3B,UAAU,KAAK,MAAM,MAAM,MAAM;EACjC,UAAU,MAAM;CAClB;AACF;;AASA,SAAgB,eAAe,OAAyB;CACtD,IAAI,EAAE,iBAAiB,QACrB,OAAO;CAET,OAAO,MAAM,SAAS,kBAAkB,oBAAoB,KAAK,MAAM,OAAO;AAChF;AAEA,SAAS,OAAa,CAAC;AAEvB,SAAS,MAAM,OAAe,KAAa,KAAqB;CAC9D,OAAO,KAAK,IAAI,KAAK,KAAK,IAAI,KAAK,KAAK,CAAC;AAC3C;AAEA,SAAS,WAAW,QAAkB,UAA0B;CAC9D,MAAM,SAAS,OAAO,UAAU,MAAM,UAAU,OAAO,KAAK;CAC5D,OAAO,OAAO,KAAK,IAAI,OAAO,SAAS,GAAG,KAAK,MAAM,OAAO,SAAS,QAAQ,CAAC,MAAM;AACtF;;AAGA,SAAS,qBAA+D;CACtE,MAAM,YAAY,sBAAsB,EAAE,YAAY,GAAG,CAAC;CAC1D,UAAU,OAAO;CACjB,OAAO;EACL,YAAY;GACV,MAAM,MAAM,UAAU,WAAW,EAAE,IAAI;GACvC,UAAU,MAAM;GAChB,OAAO;EACT;EACA,YAAY;GACV,UAAU,QAAQ;EACpB;CACF;AACF"}

package/dist/utils/connect-retry.d.mts

@@ -0,0 +1,26 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/utils/connect-retry.d.ts
+/** Retrying a connection to a remote browser service (ADR 0007, decision 4). */
+/** Options of {@link retryConnect}. */
+interface RetryConnectOptions {
+  /** Retries after the first attempt. */
+  retries: number;
+  /** Delay before the first retry in ms; doubles each time, with jitter, capped at 10 s. */
+  backoffMs: number;
+  /** Called before each retry with the error, the retry's number (from 1) and its delay. */
+  onRetry?: (error: unknown, retry: number, delayMs: number) => void;
+  /** Injectable for tests. */
+  sleep?: (ms: number) => Promise<void>;
+}
+/** Whether a connect error is worth retrying: connection-level, not a configuration mistake. */
+declare function isRetryableConnectError(error: unknown): boolean;
+/**
+ * Run `connect`, retrying a connection-level failure with exponential backoff, so a provider
+ * outage or a full plan is absorbed here and crash isolation only ever sees a browser that died
+ * while rendering. The last error is thrown once the retries are spent.
+ */
+declare function retryConnect<T>(connect: () => Promise<T>, options: RetryConnectOptions): Promise<T>;
+//#endregion
+export { RetryConnectOptions, isRetryableConnectError, retryConnect };
+//# sourceMappingURL=connect-retry.d.mts.map

package/dist/utils/connect-retry.mjs

@@ -0,0 +1,43 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/utils/connect-retry.ts
+const MAX_DELAY_MS = 1e4;
+/** Errors that no retry fixes: a refused credential, a missing endpoint, mismatched versions. */
+const PERMANENT = /\b(?:401|403|404|428|unauthorized|forbidden|version mismatch|invalid (?:token|credentials)|not found)\b/iu;
+/** Errors of the connection itself: refused, dropped, timed out, or a service with no free session. */
+const CONNECTION = /(?:ECONNREFUSED|ECONNRESET|EPIPE|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|EHOSTUNREACH|socket hang up|websocket error|connection (?:closed|refused|reset)|timeout|timed out|capacity|too many|queue(?:d)? full|no (?:free )?(?:session|browser)|\b(?:408|425|429|500|502|503|504)\b)/iu;
+/** Whether a connect error is worth retrying: connection-level, not a configuration mistake. */
+function isRetryableConnectError(error) {
+	const text = error instanceof Error ? error.message : String(error);
+	return !PERMANENT.test(text) && CONNECTION.test(text);
+}
+/**
+* Run `connect`, retrying a connection-level failure with exponential backoff, so a provider
+* outage or a full plan is absorbed here and crash isolation only ever sees a browser that died
+* while rendering. The last error is thrown once the retries are spent.
+*/
+async function retryConnect(connect, options) {
+	const sleep = options.sleep ?? sleepFor;
+	for (let retry = 0;; retry += 1) try {
+		return await connect();
+	} catch (error) {
+		if (retry >= options.retries || !isRetryableConnectError(error)) throw error;
+		const delayMs = Math.min(MAX_DELAY_MS, options.backoffMs * 2 ** retry) * jitter();
+		options.onRetry?.(error, retry + 1, Math.round(delayMs));
+		await sleep(delayMs);
+	}
+}
+/** 0.75 to 1.25: providers refusing for capacity should not see every shard retry in step. */
+function jitter() {
+	return .75 + Math.random() * .5;
+}
+async function sleepFor(ms) {
+	await new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+//#endregion
+export { isRetryableConnectError, retryConnect };
+
+//# sourceMappingURL=connect-retry.mjs.map

package/dist/utils/connect-retry.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-retry.mjs","names":[],"sources":["../../src/utils/connect-retry.ts"],"sourcesContent":["/** Retrying a connection to a remote browser service (ADR 0007, decision 4). */\n\n/** Options of {@link retryConnect}. */\nexport interface RetryConnectOptions {\n  /** Retries after the first attempt. */\n  retries: number;\n  /** Delay before the first retry in ms; doubles each time, with jitter, capped at 10 s. */\n  backoffMs: number;\n  /** Called before each retry with the error, the retry's number (from 1) and its delay. */\n  onRetry?: (error: unknown, retry: number, delayMs: number) => void;\n  /** Injectable for tests. */\n  sleep?: (ms: number) => Promise<void>;\n}\n\nconst MAX_DELAY_MS = 10_000;\n\n/** Errors that no retry fixes: a refused credential, a missing endpoint, mismatched versions. */\nconst PERMANENT =\n  /\\b(?:401|403|404|428|unauthorized|forbidden|version mismatch|invalid (?:token|credentials)|not found)\\b/iu;\n\n/** Errors of the connection itself: refused, dropped, timed out, or a service with no free session. */\nconst CONNECTION =\n  /(?:ECONNREFUSED|ECONNRESET|EPIPE|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|EHOSTUNREACH|socket hang up|websocket error|connection (?:closed|refused|reset)|timeout|timed out|capacity|too many|queue(?:d)? full|no (?:free )?(?:session|browser)|\\b(?:408|425|429|500|502|503|504)\\b)/iu;\n\n/** Whether a connect error is worth retrying: connection-level, not a configuration mistake. */\nexport function isRetryableConnectError(error: unknown): boolean {\n  const text = error instanceof Error ? error.message : String(error);\n  return !PERMANENT.test(text) && CONNECTION.test(text);\n}\n\n/**\n * Run `connect`, retrying a connection-level failure with exponential backoff, so a provider\n * outage or a full plan is absorbed here and crash isolation only ever sees a browser that died\n * while rendering. The last error is thrown once the retries are spent.\n */\nexport async function retryConnect<T>(\n  connect: () => Promise<T>,\n  options: RetryConnectOptions,\n): Promise<T> {\n  const sleep = options.sleep ?? sleepFor;\n  for (let retry = 0; ; retry += 1) {\n    try {\n      // oxlint-disable-next-line eslint/no-await-in-loop -- attempts are sequential by design\n      return await connect();\n    } catch (error) {\n      if (retry >= options.retries || !isRetryableConnectError(error)) {\n        throw error;\n      }\n      const delayMs = Math.min(MAX_DELAY_MS, options.backoffMs * 2 ** retry) * jitter();\n      options.onRetry?.(error, retry + 1, Math.round(delayMs));\n      // oxlint-disable-next-line eslint/no-await-in-loop -- backoff between sequential attempts\n      await sleep(delayMs);\n    }\n  }\n}\n\n/** 0.75 to 1.25: providers refusing for capacity should not see every shard retry in step. */\nfunction jitter(): number {\n  return 0.75 + Math.random() * 0.5;\n}\n\nasync function sleepFor(ms: number): Promise<void> {\n  await new Promise<void>((resolve) => {\n    setTimeout(resolve, ms);\n  });\n}\n"],"mappings":";;;;AAcA,MAAM,eAAe;;AAGrB,MAAM,YACJ;;AAGF,MAAM,aACJ;;AAGF,SAAgB,wBAAwB,OAAyB;CAC/D,MAAM,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;CAClE,OAAO,CAAC,UAAU,KAAK,IAAI,KAAK,WAAW,KAAK,IAAI;AACtD;;;;;;AAOA,eAAsB,aACpB,SACA,SACY;CACZ,MAAM,QAAQ,QAAQ,SAAS;CAC/B,KAAK,IAAI,QAAQ,IAAK,SAAS,GAC7B,IAAI;EAEF,OAAO,MAAM,QAAQ;CACvB,SAAS,OAAO;EACd,IAAI,SAAS,QAAQ,WAAW,CAAC,wBAAwB,KAAK,GAC5D,MAAM;EAER,MAAM,UAAU,KAAK,IAAI,cAAc,QAAQ,YAAY,KAAK,KAAK,IAAI,OAAO;EAChF,QAAQ,UAAU,OAAO,QAAQ,GAAG,KAAK,MAAM,OAAO,CAAC;EAEvD,MAAM,MAAM,OAAO;CACrB;AAEJ;;AAGA,SAAS,SAAiB;CACxB,OAAO,MAAO,KAAK,OAAO,IAAI;AAChC;AAEA,eAAe,SAAS,IAA2B;CACjD,MAAM,IAAI,SAAe,YAAY;EACnC,WAAW,SAAS,EAAE;CACxB,CAAC;AACH"}

package/dist/utils/environment.d.mts

@@ -0,0 +1,19 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { CaptureEnvironment } from "../adapter/capture-runner.mjs";
+//#region src/utils/environment.d.ts
+/**
+ * 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.
+ */
+declare function systemFontsHash(): Promise<string | undefined>;
+/**
+ * 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.
+ */
+declare function detectCaptureEnvironment(browserVersion?: string, deviceScaleFactor?: number): Promise<CaptureEnvironment>;
+//#endregion
+export { detectCaptureEnvironment, systemFontsHash };
+//# sourceMappingURL=environment.d.mts.map

package/dist/utils/environment.mjs

@@ -0,0 +1,59 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { sha256 } from "./hash.mjs";
+//#region 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;
+}
+//#endregion
+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/http.d.mts

@@ -1,6 +1,7 @@
 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.
@@ -13,6 +14,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}.
@@ -35,10 +45,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 +65,10 @@ 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, httpText };
 //# sourceMappingURL=http.d.mts.map

package/dist/utils/http.mjs

@@ -2,6 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { injectTraceContext, withSpan } from "../tracing.mjs";
+import { Buffer } from "node:buffer";
 //#region 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}.
 *
@@ -80,7 +92,7 @@ async function requestWithRetry(url, options, maxAttempts, timeoutMs, perform) {
 			return await perform(url, options, timeoutMs);
 		} catch (error) {
 			span.recordException(error instanceof Error ? error : String(error));
-			if (!shouldRetry(error, attempt, maxAttempts)) throw error;
+			if (options.signal?.aborted || !shouldRetry(error, attempt, maxAttempts)) throw error;
 			span.setAttribute("http.retry.count", attempt);
 			await backoff(error, attempt, url, options.logger);
 		}
@@ -109,6 +121,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,6 +137,10 @@ async function doFetchJson(url, options, timeoutMs) {
 async function doFetchText(url, options, timeoutMs) {
 	return await (await doFetchResponse(url, options, timeoutMs)).text();
 }
+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) {
 	const request = buildRequest(options);
 	injectTraceContext(request.headers);
@@ -133,7 +152,7 @@ async function doFetchResponse(url, options, timeoutMs) {
 		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();
@@ -142,6 +161,6 @@ async function doFetchResponse(url, options, timeoutMs) {
 	return response;
 }
 //#endregion
-export { HttpError, httpJson, httpText };
+export { HttpError, httpBytes, httpJson, httpText };
 
 //# 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":"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"}
+{"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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"}