@storyshelf/core 0.7.0 → 0.8.0

package/dist/utils/remote-environment.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"remote-environment.mjs","names":[],"sources":["../../src/utils/remote-environment.ts"],"sourcesContent":["/**\n * The environment of a remote browser, measured inside it (ADR 0007, decision 2). `fc-list` and\n * `process.platform` describe the machine running the runner, not the one that rendered.\n */\nimport type { CaptureEnvironment } from \"../adapters/capture-runner.ts\";\nimport { sha256 } from \"./hash.ts\";\n\n/** What the probe page reports. */\nexport interface BrowserProbe {\n  /** OS as the page sees it (`navigator.userAgentData.platform`, else `navigator.platform`). */\n  platform?: string;\n  deviceScaleFactor?: number;\n  /** Which of {@link FONT_PROBE_FAMILIES} are installed. */\n  fonts?: string[];\n}\n\n/**\n * Families probed for the fonts digest: system fonts that differ between operating systems and\n * image builds, so a provider-side change moves the hash. A fixed list; changing it re-baselines\n * every remote target's fingerprint.\n */\nexport const FONT_PROBE_FAMILIES: readonly string[] = [\n  \"Arial\",\n  \"Helvetica\",\n  \"Helvetica Neue\",\n  \"Times New Roman\",\n  \"Georgia\",\n  \"Verdana\",\n  \"Tahoma\",\n  \"Trebuchet MS\",\n  \"Courier New\",\n  \"Consolas\",\n  \"Menlo\",\n  \"Monaco\",\n  \"Segoe UI\",\n  \"Calibri\",\n  \"Cambria\",\n  \"San Francisco\",\n  \"SF Pro Text\",\n  \"Lucida Grande\",\n  \"Roboto\",\n  \"Open Sans\",\n  \"Noto Sans\",\n  \"Noto Serif\",\n  \"Noto Sans Mono\",\n  \"Noto Color Emoji\",\n  \"Apple Color Emoji\",\n  \"Segoe UI Emoji\",\n  \"DejaVu Sans\",\n  \"DejaVu Serif\",\n  \"DejaVu Sans Mono\",\n  \"Liberation Sans\",\n  \"Liberation Serif\",\n  \"Liberation Mono\",\n  \"Ubuntu\",\n  \"Cantarell\",\n  \"Droid Sans\",\n  \"Source Sans Pro\",\n  \"Fira Sans\",\n  \"Inter\",\n  \"Arial Unicode MS\",\n  \"MS Gothic\",\n  \"Hiragino Sans\",\n  \"PingFang SC\",\n  \"Microsoft YaHei\",\n  \"Malgun Gothic\",\n];\n\n/**\n * Read the OS, the device pixel ratio and the installed probe fonts. Runs inside the page, so it\n * must stay one self-contained function (no imports, no closures): the runners pass it to\n * `page.evaluate`, which sends its source. A font counts as installed when text in it measures\n * differently from the generic family it would fall back to; `document.fonts.check` answers `true`\n * for a family that does not exist, so it cannot tell.\n */\n// oxlint-disable-next-line eslint/max-statements, eslint/max-lines-per-function -- must stay one self-contained function (see above)\nexport function inPageProbe(families: string[]): BrowserProbe {\n  const win = globalThis as unknown as {\n    devicePixelRatio?: number;\n    navigator: { userAgentData?: { platform?: string }; platform?: string };\n    document: {\n      createElement: (tag: string) => {\n        getContext: (kind: string) => {\n          font: string;\n          measureText: (text: string) => { width: number };\n        } | null;\n      };\n    };\n  };\n  const probe: BrowserProbe = {};\n  const reported = win.navigator.userAgentData?.platform;\n  const platform = reported === undefined || reported === \"\" ? win.navigator.platform : reported;\n  if (platform) probe.platform = platform;\n  if (typeof win.devicePixelRatio === \"number\") probe.deviceScaleFactor = win.devicePixelRatio;\n  const context = win.document.createElement(\"canvas\").getContext(\"2d\");\n  if (!context) return probe;\n  const text = \"mmmmmmmmmmlli1WwQqÅgy 漢字\";\n  const generics = [\"monospace\", \"sans-serif\", \"serif\"];\n  const widthOf = (font: string): number => {\n    context.font = `72px ${font}`;\n    return context.measureText(text).width;\n  };\n  const baseline = generics.map((generic) => widthOf(generic));\n  probe.fonts = families.filter((family) =>\n    generics.some((generic, index) => widthOf(`\"${family}\", ${generic}`) !== baseline[index]),\n  );\n  return probe;\n}\n\n/**\n * The environment of a remote render: the driver's browser version and what the page reported. A\n * field the page could not give is left out, except the OS, which falls back to what the service\n * was configured to render on; an unknown fingerprint component is never a change (ADR 0005).\n */\nexport function remoteEnvironment(options: {\n  browserVersion?: string | undefined;\n  probe?: BrowserProbe | undefined;\n  declaredPlatform?: string | undefined;\n}): CaptureEnvironment {\n  const { probe, browserVersion } = options;\n  const platform = normalizePlatform(probe?.platform) ?? options.declaredPlatform;\n  const fonts = probe?.fonts;\n  return {\n    ...(browserVersion ? { browserVersion } : {}),\n    ...(platform ? { platform } : {}),\n    ...(probe?.deviceScaleFactor ? { deviceScaleFactor: probe.deviceScaleFactor } : {}),\n    ...(fonts && fonts.length > 0\n      ? { fontsHash: sha256(fonts.toSorted().join(\"\\n\")).slice(0, 16) }\n      : {}),\n  };\n}\n\n/** `Win32`, `Windows` and `Linux x86_64` read as the OS, in one spelling per OS. */\nfunction normalizePlatform(value: string | undefined): string | undefined {\n  const text = value?.trim().toLowerCase();\n  if (!text) {\n    return undefined;\n  }\n  if (text.startsWith(\"win\")) return \"windows\";\n  if (text.startsWith(\"mac\") || text === \"iphone\" || text === \"ipad\") return \"macos\";\n  return text.startsWith(\"linux\") ? \"linux\" : text;\n}\n"],"mappings":";;;;;;;;;;AAqBA,MAAa,sBAAyC;CACpD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;;;;;;;AAUA,SAAgB,YAAY,UAAkC;CAC5D,MAAM,MAAM;CAYZ,MAAM,QAAsB,CAAC;CAC7B,MAAM,WAAW,IAAI,UAAU,eAAe;CAC9C,MAAM,WAAW,aAAa,KAAA,KAAa,aAAa,KAAK,IAAI,UAAU,WAAW;CACtF,IAAI,UAAU,MAAM,WAAW;CAC/B,IAAI,OAAO,IAAI,qBAAqB,UAAU,MAAM,oBAAoB,IAAI;CAC5E,MAAM,UAAU,IAAI,SAAS,cAAc,QAAQ,CAAC,CAAC,WAAW,IAAI;CACpE,IAAI,CAAC,SAAS,OAAO;CACrB,MAAM,OAAO;CACb,MAAM,WAAW;EAAC;EAAa;EAAc;CAAO;CACpD,MAAM,WAAW,SAAyB;EACxC,QAAQ,OAAO,QAAQ;EACvB,OAAO,QAAQ,YAAY,IAAI,CAAC,CAAC;CACnC;CACA,MAAM,WAAW,SAAS,KAAK,YAAY,QAAQ,OAAO,CAAC;CAC3D,MAAM,QAAQ,SAAS,QAAQ,WAC7B,SAAS,MAAM,SAAS,UAAU,QAAQ,IAAI,OAAO,KAAK,SAAS,MAAM,SAAS,MAAM,CAC1F;CACA,OAAO;AACT;;;;;;AAOA,SAAgB,kBAAkB,SAIX;CACrB,MAAM,EAAE,OAAO,mBAAmB;CAClC,MAAM,WAAW,kBAAkB,OAAO,QAAQ,KAAK,QAAQ;CAC/D,MAAM,QAAQ,OAAO;CACrB,OAAO;EACL,GAAI,iBAAiB,EAAE,eAAe,IAAI,CAAC;EAC3C,GAAI,WAAW,EAAE,SAAS,IAAI,CAAC;EAC/B,GAAI,OAAO,oBAAoB,EAAE,mBAAmB,MAAM,kBAAkB,IAAI,CAAC;EACjF,GAAI,SAAS,MAAM,SAAS,IACxB,EAAE,WAAW,OAAO,MAAM,SAAS,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,GAAG,EAAE,EAAE,IAC9D,CAAC;CACP;AACF;;AAGA,SAAS,kBAAkB,OAA+C;CACxE,MAAM,OAAO,OAAO,KAAK,CAAC,CAAC,YAAY;CACvC,IAAI,CAAC,MACH;CAEF,IAAI,KAAK,WAAW,KAAK,GAAG,OAAO;CACnC,IAAI,KAAK,WAAW,KAAK,KAAK,SAAS,YAAY,SAAS,QAAQ,OAAO;CAC3E,OAAO,KAAK,WAAW,OAAO,IAAI,UAAU;AAC9C"}
+{"version":3,"file":"remote-environment.mjs","names":[],"sources":["../../src/utils/remote-environment.ts"],"sourcesContent":["/**\n * The environment of a remote browser, measured inside it (ADR 0007, decision 2). `fc-list` and\n * `process.platform` describe the machine running the runner, not the one that rendered.\n */\nimport type { CaptureEnvironment } from \"../adapters/capture-runner.ts\";\nimport { sha256 } from \"./hash.ts\";\n\n/** What the probe page reports. */\nexport interface BrowserProbe {\n  /** OS as the page sees it (`navigator.userAgentData.platform`, else `navigator.platform`). */\n  platform?: string;\n  deviceScaleFactor?: number;\n  /** Which of {@link FONT_PROBE_FAMILIES} are installed. */\n  fonts?: string[];\n}\n\n/**\n * Families probed for the fonts digest: system fonts that differ between operating systems and\n * image builds, so a provider-side change moves the hash. A fixed list; changing it re-baselines\n * every remote target's fingerprint.\n */\nexport const FONT_PROBE_FAMILIES: readonly string[] = [\n  \"Arial\",\n  \"Helvetica\",\n  \"Helvetica Neue\",\n  \"Times New Roman\",\n  \"Georgia\",\n  \"Verdana\",\n  \"Tahoma\",\n  \"Trebuchet MS\",\n  \"Courier New\",\n  \"Consolas\",\n  \"Menlo\",\n  \"Monaco\",\n  \"Segoe UI\",\n  \"Calibri\",\n  \"Cambria\",\n  \"San Francisco\",\n  \"SF Pro Text\",\n  \"Lucida Grande\",\n  \"Roboto\",\n  \"Open Sans\",\n  \"Noto Sans\",\n  \"Noto Serif\",\n  \"Noto Sans Mono\",\n  \"Noto Color Emoji\",\n  \"Apple Color Emoji\",\n  \"Segoe UI Emoji\",\n  \"DejaVu Sans\",\n  \"DejaVu Serif\",\n  \"DejaVu Sans Mono\",\n  \"Liberation Sans\",\n  \"Liberation Serif\",\n  \"Liberation Mono\",\n  \"Ubuntu\",\n  \"Cantarell\",\n  \"Droid Sans\",\n  \"Source Sans Pro\",\n  \"Fira Sans\",\n  \"Inter\",\n  \"Arial Unicode MS\",\n  \"MS Gothic\",\n  \"Hiragino Sans\",\n  \"PingFang SC\",\n  \"Microsoft YaHei\",\n  \"Malgun Gothic\",\n];\n\n/**\n * Read the OS, the device pixel ratio and the installed probe fonts. Runs inside the page, so it\n * must stay one self-contained function (no imports, no closures): the runners pass it to\n * `page.evaluate`, which sends its source. A font counts as installed when text in it measures\n * differently from the generic family it would fall back to; `document.fonts.check` answers `true`\n * for a family that does not exist, so it cannot tell.\n */\n// oxlint-disable-next-line eslint/max-statements, eslint/max-lines-per-function -- must stay one self-contained function (see above)\nexport function inPageProbe(families: string[]): BrowserProbe {\n  const win = globalThis as unknown as {\n    devicePixelRatio?: number;\n    navigator: { userAgentData?: { platform?: string }; platform?: string };\n    document: {\n      createElement: (tag: string) => {\n        getContext: (kind: string) => {\n          font: string;\n          measureText: (text: string) => { width: number };\n        } | null;\n      };\n    };\n  };\n  const probe: BrowserProbe = {};\n  const reported = win.navigator.userAgentData?.platform;\n  const platform = reported === undefined || reported === \"\" ? win.navigator.platform : reported;\n  if (platform) probe.platform = platform;\n  if (typeof win.devicePixelRatio === \"number\") probe.deviceScaleFactor = win.devicePixelRatio;\n  const context = win.document.createElement(\"canvas\").getContext(\"2d\");\n  if (!context) return probe;\n  const text = \"mmmmmmmmmmlli1WwQqÅgy 漢字\";\n  const generics = [\"monospace\", \"sans-serif\", \"serif\"];\n  const widthOf = (font: string): number => {\n    context.font = `72px ${font}`;\n    return context.measureText(text).width;\n  };\n  const baseline = generics.map((generic) => widthOf(generic));\n  probe.fonts = families.filter((family) =>\n    generics.some((generic, index) => widthOf(`\"${family}\", ${generic}`) !== baseline[index]),\n  );\n  return probe;\n}\n\n/** How a {@link boundedProbe} ended. */\nexport type ProbeOutcome<T> =\n  | { status: \"done\"; value: T }\n  /** Still running after `timeoutMs`: the environment is unknown, the run goes on. */\n  | { status: \"timeout\" }\n  /** The run was cancelled: the run stops, it is never read as \"unknown environment\". */\n  | { status: \"cancelled\" }\n  /** The probe threw (a service outage, a page that would not open): unknown, with a warning. */\n  | { status: \"failed\"; error: unknown };\n\n/** What a probe's work can ask about its own fate. */\nexport interface ProbeControl {\n  /**\n   * True once the probe timed out or was cancelled. Work that opens a page must check it after\n   * every await and release what it opened, because nothing waits for it any more.\n   */\n  stopped: () => boolean;\n}\n\n/**\n * Run probe work under a time limit and a cancel signal (ADR 0007, decision 2). A probe that hangs\n * on an unresponsive service must not hold a render, and a cancel must interrupt it instead of\n * waiting for the service. The work is never awaited past the limit and never leaves an unhandled\n * rejection; releasing the page it opened is the caller's job (`ProbeControl.stopped`, or closing\n * what it holds once this returns). A failure after the signal fired reads as cancelled, since\n * closing the browser is how a cancel interrupts it.\n */\nexport async function boundedProbe<T>(options: {\n  run: (control: ProbeControl) => Promise<T>;\n  timeoutMs: number;\n  signal?: AbortSignal | undefined;\n}): Promise<ProbeOutcome<T>> {\n  const { signal, timeoutMs } = options;\n  if (signal?.aborted) {\n    return { status: \"cancelled\" };\n  }\n  const halt = { halted: false };\n  const work = options.run({ stopped: () => halt.halted }).then(\n    (value): ProbeOutcome<T> => ({ status: \"done\", value }),\n    (error: unknown): ProbeOutcome<T> => ({ status: \"failed\", error }),\n  );\n  return await settle(work, limitOf<T>(timeoutMs, signal), signal, halt);\n}\n\n/** Wait for the work or the limit, mark the work stopped if it lost, and drop the timer and listener. */\nasync function settle<T>(\n  work: Promise<ProbeOutcome<T>>,\n  limit: { reached: Promise<ProbeOutcome<T>>; clear: () => void },\n  signal: AbortSignal | undefined,\n  halt: { halted: boolean },\n): Promise<ProbeOutcome<T>> {\n  try {\n    const outcome = await Promise.race([work, limit.reached]);\n    halt.halted = outcome.status === \"timeout\" || outcome.status === \"cancelled\";\n    return outcome.status === \"failed\" && signal?.aborted ? { status: \"cancelled\" } : outcome;\n  } finally {\n    limit.clear();\n  }\n}\n\n/** A promise that settles on the timeout or the abort, and a way to drop both. */\nfunction limitOf<T>(\n  timeoutMs: number,\n  signal: AbortSignal | undefined,\n): { reached: Promise<ProbeOutcome<T>>; clear: () => void } {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  let onAbort: (() => void) | undefined;\n  const reached = new Promise<ProbeOutcome<T>>((resolve) => {\n    timer = setTimeout(() => {\n      resolve({ status: \"timeout\" });\n    }, timeoutMs);\n    onAbort = (): void => {\n      resolve({ status: \"cancelled\" });\n    };\n    signal?.addEventListener(\"abort\", onAbort, { once: true });\n  });\n  return {\n    reached,\n    clear: (): void => {\n      clearTimeout(timer);\n      if (onAbort) signal?.removeEventListener(\"abort\", onAbort);\n    },\n  };\n}\n\n/**\n * The environment of a remote render: the driver's browser version and what the page reported. A\n * field the page could not give is left out, except the OS, which falls back to what the service\n * was configured to render on; an unknown fingerprint component is never a change (ADR 0005).\n */\nexport function remoteEnvironment(options: {\n  browserVersion?: string | undefined;\n  probe?: BrowserProbe | undefined;\n  declaredPlatform?: string | undefined;\n}): CaptureEnvironment {\n  const { probe, browserVersion } = options;\n  const platform = normalizePlatform(probe?.platform) ?? options.declaredPlatform;\n  const fonts = probe?.fonts;\n  return {\n    ...(browserVersion ? { browserVersion } : {}),\n    ...(platform ? { platform } : {}),\n    ...(probe?.deviceScaleFactor ? { deviceScaleFactor: probe.deviceScaleFactor } : {}),\n    ...(fonts && fonts.length > 0\n      ? { fontsHash: sha256(fonts.toSorted().join(\"\\n\")).slice(0, 16) }\n      : {}),\n  };\n}\n\n/** `Win32`, `Windows` and `Linux x86_64` read as the OS, in one spelling per OS. */\nfunction normalizePlatform(value: string | undefined): string | undefined {\n  const text = value?.trim().toLowerCase();\n  if (!text) {\n    return undefined;\n  }\n  if (text.startsWith(\"win\")) return \"windows\";\n  if (text.startsWith(\"mac\") || text === \"iphone\" || text === \"ipad\") return \"macos\";\n  return text.startsWith(\"linux\") ? \"linux\" : text;\n}\n"],"mappings":"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"}

package/dist/utils/resources.d.mts

@@ -1,6 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/utils/resources.d.ts
 /** CPU and memory actually available to this process (container limits included). */
 interface HostResources {
   /** Fractional vCPUs: a cgroup quota of 0.5 CPU reports `0.5`. */
@@ -59,6 +58,5 @@ interface CaptureHostSummary {
 }
 /** Summarise the host budget and effective capture concurrency, for the System page. */
 declare function describeCaptureHost(configuredBuilds?: number, resources?: HostResources): CaptureHostSummary;
-//#endregion
 export { CaptureHostSummary, DEFAULT_RECYCLE_BROWSER_EVERY, HostResources, describeCaptureHost, describeSizing, detectResources, engineWeight, maxPageConcurrency, recommendedBuildConcurrency, recommendedNavigationTimeoutMs, recommendedPageConcurrency };
 //# sourceMappingURL=resources.d.mts.map

package/dist/utils/resources.mjs

@@ -3,7 +3,7 @@ import "node:url";
 import.meta.url;
 import { availableParallelism, totalmem } from "node:os";
 import { readFileSync } from "node:fs";
-//#region src/utils/resources.ts
+// src/utils/resources.ts
 const MB = 1048576;
 /** Headroom for Node, the server and Chromium's browser process. */
 const BASE_MEMORY_MB = 512;
@@ -116,7 +116,6 @@ function readText(path) {
 		return null;
 	}
 }
-//#endregion
 export { DEFAULT_RECYCLE_BROWSER_EVERY, describeCaptureHost, describeSizing, detectResources, engineWeight, maxPageConcurrency, recommendedBuildConcurrency, recommendedNavigationTimeoutMs, recommendedPageConcurrency };
 
 //# sourceMappingURL=resources.mjs.map

package/dist/utils/screenshot-store.d.mts

@@ -1,7 +1,6 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { StorageAdapter } from "../adapter/storage.mjs";
-//#region src/utils/screenshot-store.d.ts
 /**
  * Store a screenshot under the SHA-256 of its bytes and return its path.
  *
@@ -10,6 +9,5 @@ import { StorageAdapter } from "../adapter/storage.mjs";
  * identical paths mean identical pixels (the diff can be skipped without reading either image).
  */
 declare function storeScreenshot(storage: StorageAdapter, projectId: string, data: Buffer): Promise<string>;
-//#endregion
 export { storeScreenshot };
 //# sourceMappingURL=screenshot-store.d.mts.map

package/dist/utils/screenshot-store.mjs

@@ -4,7 +4,7 @@ import.meta.url;
 import { ulid } from "./ulid.mjs";
 import { contentDir, contentPath } from "../paths.mjs";
 import { createHash } from "node:crypto";
-//#region src/utils/screenshot-store.ts
+// src/utils/screenshot-store.ts
 /** Content-addressed screenshot storage: identical bytes are stored once per project. */
 /**
 * Store a screenshot under the SHA-256 of its bytes and return its path.
@@ -35,7 +35,6 @@ async function withContentClaim(storage, projectId, work) {
 		await storage.delete(path).catch(() => false);
 	}
 }
-//#endregion
 export { CLAIMS_DIR, storeScreenshot, withContentClaim };
 
 //# sourceMappingURL=screenshot-store.mjs.map

package/dist/utils/session-gate.d.mts

@@ -1,10 +1,9 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/utils/session-gate.d.ts
 /** Per-target session caps for remote browsers, shared by every render in the process (ADR 0007, decision 4). */
 /** Runs work under a fixed number of sessions. */
 interface SessionGate {
-  /** Sessions the plan allows. */
+  /** Sessions the plan allows now (a scaling provider's cap can change between reads). */
   readonly size: number;
   /** Run `fn` once a session is free. */
   run<T>(fn: () => Promise<T>): Promise<T>;
@@ -14,9 +13,11 @@ interface SessionGate {
  * concurrent shards share the cap instead of multiplying it. A later call with another `sessions`
  * keeps the first gate: the size is the runner's configuration and does not change under it.
  */
-declare function sessionGateFor(target: string, sessions: number): SessionGate;
-/** A gate of its own (not shared through {@link sessionGateFor}); `size` below 1 counts as 1. */
-declare function createSessionGate(size: number): SessionGate;
-//#endregion
+declare function sessionGateFor(target: string, sessions: number | (() => number), onInvalid?: (value: unknown) => void): SessionGate;
+/**
+ * A gate of its own (not shared through {@link sessionGateFor}); `size` below 1 counts as 1. A
+ * function is read on every use, so a cap that grows lets waiting work in at the next release.
+ */
+declare function createSessionGate(size: number | (() => number), onInvalid?: (value: unknown) => void): SessionGate;
 export { SessionGate, createSessionGate, sessionGateFor };
 //# sourceMappingURL=session-gate.d.mts.map

package/dist/utils/session-gate.mjs

@@ -1,33 +1,48 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/utils/session-gate.ts
+// src/utils/session-gate.ts
 const gates = /* @__PURE__ */ new Map();
 /**
 * The gate of `target`, created on first use. One gate per target for the whole process, so
 * concurrent shards share the cap instead of multiplying it. A later call with another `sessions`
 * keeps the first gate: the size is the runner's configuration and does not change under it.
 */
-function sessionGateFor(target, sessions) {
+function sessionGateFor(target, sessions, onInvalid) {
 	let gate = gates.get(target);
 	if (gate === void 0) {
-		gate = createSessionGate(sessions);
+		gate = createSessionGate(sessions, onInvalid);
 		gates.set(target, gate);
 	}
 	return gate;
 }
-/** A gate of its own (not shared through {@link sessionGateFor}); `size` below 1 counts as 1. */
-function createSessionGate(size) {
-	const limit = Math.max(1, Math.floor(size));
+/**
+* A gate of its own (not shared through {@link sessionGateFor}); `size` below 1 counts as 1. A
+* function is read on every use, so a cap that grows lets waiting work in at the next release.
+*/
+function createSessionGate(size, onInvalid) {
+	let last = 1;
+	let warned = false;
+	const limitNow = () => {
+		const raw = typeof size === "function" ? size() : size;
+		if (typeof raw === "number" && Number.isFinite(raw)) last = Math.max(1, Math.floor(raw));
+		else if (!warned) {
+			warned = true;
+			onInvalid?.(raw);
+		}
+		return last;
+	};
 	let active = 0;
 	const waiting = [];
 	const release = () => {
-		const next = waiting.shift();
-		if (next === void 0) active -= 1;
-		else next();
+		active -= 1;
+		while (active < limitNow() && waiting.length > 0) {
+			active += 1;
+			waiting.shift()?.();
+		}
 	};
 	const acquire = async () => {
-		if (active < limit) {
+		if (active < limitNow()) {
 			active += 1;
 			return;
 		}
@@ -36,7 +51,9 @@ function createSessionGate(size) {
 		});
 	};
 	return {
-		size: limit,
+		get size() {
+			return limitNow();
+		},
 		run: async (fn) => {
 			await acquire();
 			try {
@@ -47,7 +64,6 @@ function createSessionGate(size) {
 		}
 	};
 }
-//#endregion
 export { createSessionGate, sessionGateFor };
 
 //# sourceMappingURL=session-gate.mjs.map

package/dist/utils/session-gate.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"session-gate.mjs","names":[],"sources":["../../src/utils/session-gate.ts"],"sourcesContent":["/** Per-target session caps for remote browsers, shared by every render in the process (ADR 0007, decision 4). */\n\n/** Runs work under a fixed number of sessions. */\nexport interface SessionGate {\n  /** Sessions the plan allows. */\n  readonly size: number;\n  /** Run `fn` once a session is free. */\n  run<T>(fn: () => Promise<T>): Promise<T>;\n}\n\nconst gates = new Map<string, SessionGate>();\n\n/**\n * The gate of `target`, created on first use. One gate per target for the whole process, so\n * concurrent shards share the cap instead of multiplying it. A later call with another `sessions`\n * keeps the first gate: the size is the runner's configuration and does not change under it.\n */\nexport function sessionGateFor(target: string, sessions: number): SessionGate {\n  let gate = gates.get(target);\n  if (gate === undefined) {\n    gate = createSessionGate(sessions);\n    gates.set(target, gate);\n  }\n  return gate;\n}\n\n/** A gate of its own (not shared through {@link sessionGateFor}); `size` below 1 counts as 1. */\nexport function createSessionGate(size: number): SessionGate {\n  const limit = Math.max(1, Math.floor(size));\n  let active = 0;\n  const waiting: (() => void)[] = [];\n  const release = (): void => {\n    const next = waiting.shift();\n    if (next === undefined) {\n      active -= 1;\n    } else {\n      next();\n    }\n  };\n  const acquire = async (): Promise<void> => {\n    if (active < limit) {\n      active += 1;\n      return;\n    }\n    await new Promise<void>((resolve) => {\n      waiting.push(resolve);\n    });\n  };\n  return {\n    size: limit,\n    run: async (fn) => {\n      await acquire();\n      try {\n        return await fn();\n      } finally {\n        release();\n      }\n    },\n  };\n}\n"],"mappings":";;;;AAUA,MAAM,wBAAQ,IAAI,IAAyB;;;;;;AAO3C,SAAgB,eAAe,QAAgB,UAA+B;CAC5E,IAAI,OAAO,MAAM,IAAI,MAAM;CAC3B,IAAI,SAAS,KAAA,GAAW;EACtB,OAAO,kBAAkB,QAAQ;EACjC,MAAM,IAAI,QAAQ,IAAI;CACxB;CACA,OAAO;AACT;;AAGA,SAAgB,kBAAkB,MAA2B;CAC3D,MAAM,QAAQ,KAAK,IAAI,GAAG,KAAK,MAAM,IAAI,CAAC;CAC1C,IAAI,SAAS;CACb,MAAM,UAA0B,CAAC;CACjC,MAAM,gBAAsB;EAC1B,MAAM,OAAO,QAAQ,MAAM;EAC3B,IAAI,SAAS,KAAA,GACX,UAAU;OAEV,KAAK;CAET;CACA,MAAM,UAAU,YAA2B;EACzC,IAAI,SAAS,OAAO;GAClB,UAAU;GACV;EACF;EACA,MAAM,IAAI,SAAe,YAAY;GACnC,QAAQ,KAAK,OAAO;EACtB,CAAC;CACH;CACA,OAAO;EACL,MAAM;EACN,KAAK,OAAO,OAAO;GACjB,MAAM,QAAQ;GACd,IAAI;IACF,OAAO,MAAM,GAAG;GAClB,UAAU;IACR,QAAQ;GACV;EACF;CACF;AACF"}
+{"version":3,"file":"session-gate.mjs","names":[],"sources":["../../src/utils/session-gate.ts"],"sourcesContent":["/** Per-target session caps for remote browsers, shared by every render in the process (ADR 0007, decision 4). */\n\n/** Runs work under a fixed number of sessions. */\nexport interface SessionGate {\n  /** Sessions the plan allows now (a scaling provider's cap can change between reads). */\n  readonly size: number;\n  /** Run `fn` once a session is free. */\n  run<T>(fn: () => Promise<T>): Promise<T>;\n}\n\nconst gates = new Map<string, SessionGate>();\n\n/**\n * The gate of `target`, created on first use. One gate per target for the whole process, so\n * concurrent shards share the cap instead of multiplying it. A later call with another `sessions`\n * keeps the first gate: the size is the runner's configuration and does not change under it.\n */\nexport function sessionGateFor(\n  target: string,\n  sessions: number | (() => number),\n  onInvalid?: (value: unknown) => void,\n): SessionGate {\n  let gate = gates.get(target);\n  if (gate === undefined) {\n    gate = createSessionGate(sessions, onInvalid);\n    gates.set(target, gate);\n  }\n  return gate;\n}\n\n/**\n * A gate of its own (not shared through {@link sessionGateFor}); `size` below 1 counts as 1. A\n * function is read on every use, so a cap that grows lets waiting work in at the next release.\n */\nexport function createSessionGate(\n  size: number | (() => number),\n  onInvalid?: (value: unknown) => void,\n): SessionGate {\n  let last = 1;\n  let warned = false;\n  // A function returning garbage (NaN, a string) keeps the last good cap instead of blocking every page.\n  const limitNow = (): number => {\n    const raw: unknown = typeof size === \"function\" ? size() : size;\n    if (typeof raw === \"number\" && Number.isFinite(raw)) {\n      last = Math.max(1, Math.floor(raw));\n    } else if (!warned) {\n      warned = true;\n      onInvalid?.(raw);\n    }\n    return last;\n  };\n  let active = 0;\n  const waiting: (() => void)[] = [];\n  // A cap that grew lets in as many waiters as it now has room for, not one per release.\n  const release = (): void => {\n    active -= 1;\n    while (active < limitNow() && waiting.length > 0) {\n      active += 1;\n      waiting.shift()?.();\n    }\n  };\n  const acquire = async (): Promise<void> => {\n    if (active < limitNow()) {\n      active += 1;\n      return;\n    }\n    await new Promise<void>((resolve) => {\n      waiting.push(resolve);\n    });\n  };\n  return {\n    get size() {\n      return limitNow();\n    },\n    run: async (fn) => {\n      await acquire();\n      try {\n        return await fn();\n      } finally {\n        release();\n      }\n    },\n  };\n}\n"],"mappings":";;;;AAUA,MAAM,wBAAQ,IAAI,IAAyB;;;;;;AAO3C,SAAgB,eACd,QACA,UACA,WACa;CACb,IAAI,OAAO,MAAM,IAAI,MAAM;CAC3B,IAAI,SAAS,KAAA,GAAW;EACtB,OAAO,kBAAkB,UAAU,SAAS;EAC5C,MAAM,IAAI,QAAQ,IAAI;CACxB;CACA,OAAO;AACT;;;;;AAMA,SAAgB,kBACd,MACA,WACa;CACb,IAAI,OAAO;CACX,IAAI,SAAS;CAEb,MAAM,iBAAyB;EAC7B,MAAM,MAAe,OAAO,SAAS,aAAa,KAAK,IAAI;EAC3D,IAAI,OAAO,QAAQ,YAAY,OAAO,SAAS,GAAG,GAChD,OAAO,KAAK,IAAI,GAAG,KAAK,MAAM,GAAG,CAAC;OAC7B,IAAI,CAAC,QAAQ;GAClB,SAAS;GACT,YAAY,GAAG;EACjB;EACA,OAAO;CACT;CACA,IAAI,SAAS;CACb,MAAM,UAA0B,CAAC;CAEjC,MAAM,gBAAsB;EAC1B,UAAU;EACV,OAAO,SAAS,SAAS,KAAK,QAAQ,SAAS,GAAG;GAChD,UAAU;GACV,QAAQ,MAAM,CAAC,GAAG;EACpB;CACF;CACA,MAAM,UAAU,YAA2B;EACzC,IAAI,SAAS,SAAS,GAAG;GACvB,UAAU;GACV;EACF;EACA,MAAM,IAAI,SAAe,YAAY;GACnC,QAAQ,KAAK,OAAO;EACtB,CAAC;CACH;CACA,OAAO;EACL,IAAI,OAAO;GACT,OAAO,SAAS;EAClB;EACA,KAAK,OAAO,OAAO;GACjB,MAAM,QAAQ;GACd,IAAI;IACF,OAAO,MAAM,GAAG;GAClB,UAAU;IACR,QAAQ;GACV;EACF;CACF;AACF"}

package/dist/utils/storybook-token.d.mts

@@ -1,7 +1,6 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { SecretInput } from "./encrypt.mjs";
-//#region src/utils/storybook-token.d.ts
 /** The path prefix every signed Storybook URL starts with; `/_/` is the unrelated short link. */
 declare const STORYBOOK_TOKEN_PREFIX = "/_s/";
 /** Regex source of a token, shared by the shape check and the log redaction. */
@@ -24,12 +23,20 @@ declare const MIN_CAPTURES_PER_SLICE = 50;
  * override (project API, settings form, page hint) reads it through {@link storybookUrlTtlOverrideError}.
  */
 declare const MIN_STORYBOOK_URL_TTL_OVERRIDE: number;
+/**
+ * What a token was minted for. `capture` marks the tokens the server mints for a render pass or
+ * slice (`storybookUrlSource`); it is the only claim that may opt into browser-private caching of
+ * the build's assets. Interactive preview grants and legacy tokens carry none.
+ */
+type StorybookTokenPurpose = "capture";
 /** What a valid token grants: read-only access to one build's static files until `expiresAt`. */
 interface StorybookTokenClaims {
   projectId: string;
   buildId: string;
   /** Unix seconds. */
   expiresAt: number;
+  /** Set only on tokens minted for a render pass; absent on previews and legacy tokens. */
+  purpose?: StorybookTokenPurpose;
 }
 /** Inputs for {@link signStorybookToken}. */
 interface SignStorybookTokenInput {
@@ -39,6 +46,8 @@ interface SignStorybookTokenInput {
   buildId: string;
   /** Lifetime in seconds; defaults to {@link DEFAULT_STORYBOOK_URL_TTL}. See {@link storybookUrlTtl}. */
   ttlSeconds?: number | undefined;
+  /** What the token is for; omit for an interactive preview. Signed into the token. */
+  purpose?: StorybookTokenPurpose | undefined;
   /** Clock override for tests (ms). */
   now?: number | undefined;
 }
@@ -76,6 +85,5 @@ declare function storybookUrlTtl(input: {
 declare function storybookUrlTtlOverrideError(seconds: number): string | undefined;
 /** Throws unless `seconds` is an integer within the allowed lifetime range. */
 declare function assertStorybookUrlTtl(seconds: number): void;
-//#endregion
-export { DEFAULT_STORYBOOK_URL_TTL, MAX_STORYBOOK_URL_TTL, MIN_CAPTURES_PER_SLICE, MIN_STORYBOOK_URL_TTL, MIN_STORYBOOK_URL_TTL_OVERRIDE, PER_CAPTURE_BUDGET_MS, STORYBOOK_TOKEN_PREFIX, STORYBOOK_TOKEN_SOURCE, STORYBOOK_URL_TTL_GRACE, SignStorybookTokenInput, StorybookTokenClaims, StorybookTokenFailure, StorybookTokenResult, assertStorybookUrlTtl, signStorybookToken, storybookTokenPath, storybookUrlTtl, storybookUrlTtlOverrideError, verifyStorybookToken };
+export { DEFAULT_STORYBOOK_URL_TTL, MAX_STORYBOOK_URL_TTL, MIN_CAPTURES_PER_SLICE, MIN_STORYBOOK_URL_TTL, MIN_STORYBOOK_URL_TTL_OVERRIDE, PER_CAPTURE_BUDGET_MS, STORYBOOK_TOKEN_PREFIX, STORYBOOK_TOKEN_SOURCE, STORYBOOK_URL_TTL_GRACE, SignStorybookTokenInput, StorybookTokenClaims, StorybookTokenFailure, StorybookTokenPurpose, StorybookTokenResult, assertStorybookUrlTtl, signStorybookToken, storybookTokenPath, storybookUrlTtl, storybookUrlTtlOverrideError, verifyStorybookToken };
 //# sourceMappingURL=storybook-token.d.mts.map

package/dist/utils/storybook-token.mjs

@@ -3,13 +3,14 @@ import "node:url";
 import.meta.url;
 import { timingSafeEqualString } from "./hash.mjs";
 import { createHmac } from "node:crypto";
-//#region src/utils/storybook-token.ts
+// src/utils/storybook-token.ts
 /**
 * Signed Storybook tokens (ADR 0007, decision 5): the single owner of everything about the path
 * prefix of the URL a remote browser opens to read one build's published Storybook, `/_s/<token>/`:
 * the prefix, the token shape, the derived signing key, signing, verification and the lifetime
-* rules. Stateless: `base64url("<projectId>:<buildId>:<exp>")`, a dot, and the base64url
-* HMAC-SHA-256 of that first part. Imported through `@storyshelf/core/utils`.
+* rules. Stateless: `base64url("<projectId>:<buildId>:<exp>[:<purpose>]")`, a dot, and the base64url
+* HMAC-SHA-256 of that first part. The optional purpose is covered by the signature; a token
+* without one is a legacy or interactive-preview grant. Imported through `@storyshelf/core/utils`.
 */
 /** The path prefix every signed Storybook URL starts with; `/_/` is the unrelated short link. */
 const STORYBOOK_TOKEN_PREFIX = "/_s/";
@@ -36,14 +37,14 @@ const MIN_STORYBOOK_URL_TTL_OVERRIDE = Math.ceil(50 * PER_CAPTURE_BUDGET_MS / 1e
 /** Domain separation: the signing key is derived from the secret with this context, nothing else uses it. */
 const KEY_CONTEXT = "storyshelf/storybook-url/v1";
 const TOKEN_SHAPE = new RegExp(`^${STORYBOOK_TOKEN_SOURCE}$`, "u");
-const CLAIMS_SHAPE = /^([A-Za-z0-9_-]{1,64}):([A-Za-z0-9_-]{1,64}):(\d{1,12})$/u;
+const CLAIMS_SHAPE = /^([A-Za-z0-9_-]{1,64}):([A-Za-z0-9_-]{1,64}):(\d{1,12})(?::(capture))?$/u;
 /** Sign a token for one build. Throws on an empty secret, bad ids or a lifetime out of range. */
 function signStorybookToken(input) {
 	const ttl = input.ttlSeconds ?? 7200;
 	assertStorybookUrlTtl(ttl);
 	const secret = currentSecret(input.secret);
 	const expiresAt = Math.floor((input.now ?? Date.now()) / 1e3) + ttl;
-	const claims = `${input.projectId}:${input.buildId}:${expiresAt}`;
+	const claims = `${input.projectId}:${input.buildId}:${expiresAt}${input.purpose === void 0 ? "" : `:${input.purpose}`}`;
 	if (!CLAIMS_SHAPE.test(claims)) throw new Error("Cannot sign a Storybook URL: unexpected project or build id");
 	const payload = Buffer.from(claims, "utf8").toString("base64url");
 	return `${payload}.${signature(secret, payload)}`;
@@ -82,7 +83,7 @@ function storybookUrlTtl(input) {
 }
 /** The reason a project's lifetime override is refused, or `undefined` when it is acceptable. */
 function storybookUrlTtlOverrideError(seconds) {
-	if (Number.isInteger(seconds) && seconds >= MIN_STORYBOOK_URL_TTL_OVERRIDE && seconds <= 86400) return;
+	if (Number.isInteger(seconds) && seconds >= 1050 && seconds <= 86400) return;
 	return `The signed URL lifetime is a whole number of seconds from ${MIN_STORYBOOK_URL_TTL_OVERRIDE} (one slice of 50 captures plus the 300 s grace) to ${MAX_STORYBOOK_URL_TTL}`;
 }
 /** Throws unless `seconds` is an integer within the allowed lifetime range. */
@@ -95,7 +96,7 @@ function claimsOf(payload, nowSeconds) {
 		ok: false,
 		reason: "malformed"
 	};
-	const [, projectId = "", buildId = "", exp = ""] = match;
+	const [, projectId = "", buildId = "", exp = "", purpose] = match;
 	const expiresAt = Number(exp);
 	if (expiresAt <= nowSeconds) return {
 		ok: false,
@@ -110,7 +111,8 @@ function claimsOf(payload, nowSeconds) {
 		claims: {
 			projectId,
 			buildId,
-			expiresAt
+			expiresAt,
+			...purpose === "capture" ? { purpose } : {}
 		}
 	};
 }
@@ -128,7 +130,6 @@ function signature(secret, payload) {
 	const key = createHmac("sha256", secret).update(KEY_CONTEXT).digest();
 	return createHmac("sha256", key).update(payload).digest("base64url");
 }
-//#endregion
 export { DEFAULT_STORYBOOK_URL_TTL, MAX_STORYBOOK_URL_TTL, MIN_CAPTURES_PER_SLICE, MIN_STORYBOOK_URL_TTL, MIN_STORYBOOK_URL_TTL_OVERRIDE, PER_CAPTURE_BUDGET_MS, STORYBOOK_TOKEN_PREFIX, STORYBOOK_TOKEN_SOURCE, STORYBOOK_URL_TTL_GRACE, assertStorybookUrlTtl, signStorybookToken, storybookTokenPath, storybookUrlTtl, storybookUrlTtlOverrideError, verifyStorybookToken };
 
 //# sourceMappingURL=storybook-token.mjs.map

package/dist/utils/storybook-token.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"storybook-token.mjs","names":[],"sources":["../../src/utils/storybook-token.ts"],"sourcesContent":["/**\n * Signed Storybook tokens (ADR 0007, decision 5): the single owner of everything about the path\n * prefix of the URL a remote browser opens to read one build's published Storybook, `/_s/<token>/`:\n * the prefix, the token shape, the derived signing key, signing, verification and the lifetime\n * rules. Stateless: `base64url(\"<projectId>:<buildId>:<exp>\")`, a dot, and the base64url\n * HMAC-SHA-256 of that first part. Imported through `@storyshelf/core/utils`.\n */\nimport { createHmac } from \"node:crypto\";\nimport type { SecretInput } from \"./encrypt.ts\";\nimport { timingSafeEqualString } from \"./hash.ts\";\n\n/** The path prefix every signed Storybook URL starts with; `/_/` is the unrelated short link. */\nexport const STORYBOOK_TOKEN_PREFIX = \"/_s/\";\n/** Regex source of a token, shared by the shape check and the log redaction. */\nexport const STORYBOOK_TOKEN_SOURCE = \"[A-Za-z0-9_-]{8,200}\\\\.[A-Za-z0-9_-]{43}\";\n\n/** Floor of a derived lifetime, in seconds (2 hours). */\nexport const DEFAULT_STORYBOOK_URL_TTL = 7200;\n/** Shortest lifetime a token may be minted with (a render needs at least this). */\nexport const MIN_STORYBOOK_URL_TTL = 60;\n/** Ceiling of a derived lifetime and the longest accepted: a token claiming more is refused, whoever signed it. */\nexport const MAX_STORYBOOK_URL_TTL = 86_400;\n/** Slack added to a render budget when deriving a lifetime (queue wait, retries, clock skew). */\nexport const STORYBOOK_URL_TTL_GRACE = 300;\n\n/** Extra time granted per capture of a render pass, in ms; sizes a pass's budget and its slices. */\nexport const PER_CAPTURE_BUDGET_MS = 15_000;\n/** Smallest slice (captures), so a very short project override never renders a page per call. */\nexport const MIN_CAPTURES_PER_SLICE = 50;\n/**\n * Shortest lifetime a project may set as its override (seconds): one minimum slice's budget plus\n * the grace, so a slice never outlives its token. Single owner of the rule; every parser of the\n * override (project API, settings form, page hint) reads it through {@link storybookUrlTtlOverrideError}.\n */\nexport const MIN_STORYBOOK_URL_TTL_OVERRIDE =\n  Math.ceil((MIN_CAPTURES_PER_SLICE * PER_CAPTURE_BUDGET_MS) / 1000) + STORYBOOK_URL_TTL_GRACE;\n\n/** Domain separation: the signing key is derived from the secret with this context, nothing else uses it. */\nconst KEY_CONTEXT = \"storyshelf/storybook-url/v1\";\nconst TOKEN_SHAPE = new RegExp(`^${STORYBOOK_TOKEN_SOURCE}$`, \"u\");\nconst CLAIMS_SHAPE = /^([A-Za-z0-9_-]{1,64}):([A-Za-z0-9_-]{1,64}):(\\d{1,12})$/u;\n\n/** What a valid token grants: read-only access to one build's static files until `expiresAt`. */\nexport interface StorybookTokenClaims {\n  projectId: string;\n  buildId: string;\n  /** Unix seconds. */\n  expiresAt: number;\n}\n\n/** Inputs for {@link signStorybookToken}. */\nexport interface SignStorybookTokenInput {\n  /** The server secret (a rotation pair signs with its current key); throws when empty. */\n  secret: SecretInput;\n  projectId: string;\n  buildId: string;\n  /** Lifetime in seconds; defaults to {@link DEFAULT_STORYBOOK_URL_TTL}. See {@link storybookUrlTtl}. */\n  ttlSeconds?: number | undefined;\n  /** Clock override for tests (ms). */\n  now?: number | undefined;\n}\n\n/** Why a token was refused (kept apart from the response, which is the same for all). */\nexport type StorybookTokenFailure = \"malformed\" | \"signature\" | \"expired\" | \"scope\";\n\n/** The outcome of {@link verifyStorybookToken}. */\nexport type StorybookTokenResult =\n  | { ok: true; claims: StorybookTokenClaims }\n  | { ok: false; reason: StorybookTokenFailure };\n\n/** Sign a token for one build. Throws on an empty secret, bad ids or a lifetime out of range. */\nexport function signStorybookToken(input: SignStorybookTokenInput): string {\n  const ttl = input.ttlSeconds ?? DEFAULT_STORYBOOK_URL_TTL;\n  assertStorybookUrlTtl(ttl);\n  const secret = currentSecret(input.secret);\n  const expiresAt = Math.floor((input.now ?? Date.now()) / 1000) + ttl;\n  const claims = `${input.projectId}:${input.buildId}:${expiresAt}`;\n  if (!CLAIMS_SHAPE.test(claims)) {\n    throw new Error(\"Cannot sign a Storybook URL: unexpected project or build id\");\n  }\n  const payload = Buffer.from(claims, \"utf8\").toString(\"base64url\");\n  return `${payload}.${signature(secret, payload)}`;\n}\n\n/**\n * Check a token against the current secret and, during a rotation, the previous one. The signature\n * is checked (in constant time) before the payload is read, and every failure looks the same to\n * the caller except for `reason`, which is for the server's own log.\n */\nexport function verifyStorybookToken(\n  token: unknown,\n  secret: SecretInput,\n  now: number = Date.now(),\n): StorybookTokenResult {\n  if (typeof token !== \"string\" || !TOKEN_SHAPE.test(token)) {\n    return { ok: false, reason: \"malformed\" };\n  }\n  const [payload = \"\", given = \"\"] = token.split(\".\");\n  const signed = secretsOf(secret).some((key) =>\n    timingSafeEqualString(signature(key, payload), given),\n  );\n  if (!signed) {\n    return { ok: false, reason: \"signature\" };\n  }\n  return claimsOf(payload, Math.floor(now / 1000));\n}\n\n/** The path of a token's root: `/_s/<token>/`. */\nexport function storybookTokenPath(token: string): string {\n  return `${STORYBOOK_TOKEN_PREFIX}${token}/`;\n}\n\n/**\n * The lifetime of a render's tokens: the project's override when it has one, otherwise the render\n * budget (seconds) plus {@link STORYBOOK_URL_TTL_GRACE}, never below {@link DEFAULT_STORYBOOK_URL_TTL}\n * and never above {@link MAX_STORYBOOK_URL_TTL}. A pass cannot outlive its budget, so a token\n * derived from it lasts as long as the pass that carries it.\n */\nexport function storybookUrlTtl(input: {\n  override?: number | null | undefined;\n  budgetMs: number;\n}): number {\n  if (input.override !== undefined && input.override !== null) {\n    return input.override;\n  }\n  const derived = Math.ceil(input.budgetMs / 1000) + STORYBOOK_URL_TTL_GRACE;\n  return Math.min(MAX_STORYBOOK_URL_TTL, Math.max(DEFAULT_STORYBOOK_URL_TTL, derived));\n}\n\n/** The reason a project's lifetime override is refused, or `undefined` when it is acceptable. */\nexport function storybookUrlTtlOverrideError(seconds: number): string | undefined {\n  if (\n    Number.isInteger(seconds) &&\n    seconds >= MIN_STORYBOOK_URL_TTL_OVERRIDE &&\n    seconds <= MAX_STORYBOOK_URL_TTL\n  ) {\n    return undefined;\n  }\n  return `The signed URL lifetime is a whole number of seconds from ${MIN_STORYBOOK_URL_TTL_OVERRIDE} (one slice of ${MIN_CAPTURES_PER_SLICE} captures plus the ${STORYBOOK_URL_TTL_GRACE} s grace) to ${MAX_STORYBOOK_URL_TTL}`;\n}\n\n/** Throws unless `seconds` is an integer within the allowed lifetime range. */\nexport function assertStorybookUrlTtl(seconds: number): void {\n  if (\n    !Number.isInteger(seconds) ||\n    seconds < MIN_STORYBOOK_URL_TTL ||\n    seconds > MAX_STORYBOOK_URL_TTL\n  ) {\n    throw new Error(\n      `A Storybook URL lifetime must be a whole number of seconds from ${MIN_STORYBOOK_URL_TTL} to ${MAX_STORYBOOK_URL_TTL}, got ${String(seconds)}`,\n    );\n  }\n}\n\nfunction claimsOf(payload: string, nowSeconds: number): StorybookTokenResult {\n  const match = CLAIMS_SHAPE.exec(Buffer.from(payload, \"base64url\").toString(\"utf8\"));\n  if (!match) {\n    return { ok: false, reason: \"malformed\" };\n  }\n  const [, projectId = \"\", buildId = \"\", exp = \"\"] = match;\n  const expiresAt = Number(exp);\n  if (expiresAt <= nowSeconds) {\n    return { ok: false, reason: \"expired\" };\n  }\n  if (expiresAt > nowSeconds + MAX_STORYBOOK_URL_TTL) {\n    return { ok: false, reason: \"scope\" };\n  }\n  return { ok: true, claims: { projectId, buildId, expiresAt } };\n}\n\n/** The key tokens are signed with; throws when none is configured. */\nfunction currentSecret(secret: SecretInput): string {\n  const current = typeof secret === \"object\" ? secret.current : secret;\n  if (!current) {\n    throw new Error(\"Cannot sign a Storybook URL: ShelfConfig.secret is not configured\");\n  }\n  return current;\n}\n\n/** Every key a token may verify with: the current secret and, during a rotation, the previous one. */\nfunction secretsOf(secret: SecretInput): string[] {\n  const keys = typeof secret === \"object\" ? [secret.current, secret.previous] : [secret];\n  return keys.filter((key): key is string => key !== undefined && key !== \"\");\n}\n\nfunction signature(secret: string, payload: string): string {\n  const key = createHmac(\"sha256\", secret).update(KEY_CONTEXT).digest();\n  return createHmac(\"sha256\", key).update(payload).digest(\"base64url\");\n}\n"],"mappings":"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"}
+{"version":3,"file":"storybook-token.mjs","names":[],"sources":["../../src/utils/storybook-token.ts"],"sourcesContent":["/**\n * Signed Storybook tokens (ADR 0007, decision 5): the single owner of everything about the path\n * prefix of the URL a remote browser opens to read one build's published Storybook, `/_s/<token>/`:\n * the prefix, the token shape, the derived signing key, signing, verification and the lifetime\n * rules. Stateless: `base64url(\"<projectId>:<buildId>:<exp>[:<purpose>]\")`, a dot, and the base64url\n * HMAC-SHA-256 of that first part. The optional purpose is covered by the signature; a token\n * without one is a legacy or interactive-preview grant. Imported through `@storyshelf/core/utils`.\n */\nimport { createHmac } from \"node:crypto\";\nimport type { SecretInput } from \"./encrypt.ts\";\nimport { timingSafeEqualString } from \"./hash.ts\";\n\n/** The path prefix every signed Storybook URL starts with; `/_/` is the unrelated short link. */\nexport const STORYBOOK_TOKEN_PREFIX = \"/_s/\";\n/** Regex source of a token, shared by the shape check and the log redaction. */\nexport const STORYBOOK_TOKEN_SOURCE = \"[A-Za-z0-9_-]{8,200}\\\\.[A-Za-z0-9_-]{43}\";\n\n/** Floor of a derived lifetime, in seconds (2 hours). */\nexport const DEFAULT_STORYBOOK_URL_TTL = 7200;\n/** Shortest lifetime a token may be minted with (a render needs at least this). */\nexport const MIN_STORYBOOK_URL_TTL = 60;\n/** Ceiling of a derived lifetime and the longest accepted: a token claiming more is refused, whoever signed it. */\nexport const MAX_STORYBOOK_URL_TTL = 86_400;\n/** Slack added to a render budget when deriving a lifetime (queue wait, retries, clock skew). */\nexport const STORYBOOK_URL_TTL_GRACE = 300;\n\n/** Extra time granted per capture of a render pass, in ms; sizes a pass's budget and its slices. */\nexport const PER_CAPTURE_BUDGET_MS = 15_000;\n/** Smallest slice (captures), so a very short project override never renders a page per call. */\nexport const MIN_CAPTURES_PER_SLICE = 50;\n/**\n * Shortest lifetime a project may set as its override (seconds): one minimum slice's budget plus\n * the grace, so a slice never outlives its token. Single owner of the rule; every parser of the\n * override (project API, settings form, page hint) reads it through {@link storybookUrlTtlOverrideError}.\n */\nexport const MIN_STORYBOOK_URL_TTL_OVERRIDE =\n  Math.ceil((MIN_CAPTURES_PER_SLICE * PER_CAPTURE_BUDGET_MS) / 1000) + STORYBOOK_URL_TTL_GRACE;\n\n/** Domain separation: the signing key is derived from the secret with this context, nothing else uses it. */\nconst KEY_CONTEXT = \"storyshelf/storybook-url/v1\";\nconst TOKEN_SHAPE = new RegExp(`^${STORYBOOK_TOKEN_SOURCE}$`, \"u\");\nconst CLAIMS_SHAPE = /^([A-Za-z0-9_-]{1,64}):([A-Za-z0-9_-]{1,64}):(\\d{1,12})(?::(capture))?$/u;\n\n/**\n * What a token was minted for. `capture` marks the tokens the server mints for a render pass or\n * slice (`storybookUrlSource`); it is the only claim that may opt into browser-private caching of\n * the build's assets. Interactive preview grants and legacy tokens carry none.\n */\nexport type StorybookTokenPurpose = \"capture\";\n\n/** What a valid token grants: read-only access to one build's static files until `expiresAt`. */\nexport interface StorybookTokenClaims {\n  projectId: string;\n  buildId: string;\n  /** Unix seconds. */\n  expiresAt: number;\n  /** Set only on tokens minted for a render pass; absent on previews and legacy tokens. */\n  purpose?: StorybookTokenPurpose;\n}\n\n/** Inputs for {@link signStorybookToken}. */\nexport interface SignStorybookTokenInput {\n  /** The server secret (a rotation pair signs with its current key); throws when empty. */\n  secret: SecretInput;\n  projectId: string;\n  buildId: string;\n  /** Lifetime in seconds; defaults to {@link DEFAULT_STORYBOOK_URL_TTL}. See {@link storybookUrlTtl}. */\n  ttlSeconds?: number | undefined;\n  /** What the token is for; omit for an interactive preview. Signed into the token. */\n  purpose?: StorybookTokenPurpose | undefined;\n  /** Clock override for tests (ms). */\n  now?: number | undefined;\n}\n\n/** Why a token was refused (kept apart from the response, which is the same for all). */\nexport type StorybookTokenFailure = \"malformed\" | \"signature\" | \"expired\" | \"scope\";\n\n/** The outcome of {@link verifyStorybookToken}. */\nexport type StorybookTokenResult =\n  | { ok: true; claims: StorybookTokenClaims }\n  | { ok: false; reason: StorybookTokenFailure };\n\n/** Sign a token for one build. Throws on an empty secret, bad ids or a lifetime out of range. */\nexport function signStorybookToken(input: SignStorybookTokenInput): string {\n  const ttl = input.ttlSeconds ?? DEFAULT_STORYBOOK_URL_TTL;\n  assertStorybookUrlTtl(ttl);\n  const secret = currentSecret(input.secret);\n  const expiresAt = Math.floor((input.now ?? Date.now()) / 1000) + ttl;\n  const claims = `${input.projectId}:${input.buildId}:${expiresAt}${\n    input.purpose === undefined ? \"\" : `:${input.purpose}`\n  }`;\n  if (!CLAIMS_SHAPE.test(claims)) {\n    throw new Error(\"Cannot sign a Storybook URL: unexpected project or build id\");\n  }\n  const payload = Buffer.from(claims, \"utf8\").toString(\"base64url\");\n  return `${payload}.${signature(secret, payload)}`;\n}\n\n/**\n * Check a token against the current secret and, during a rotation, the previous one. The signature\n * is checked (in constant time) before the payload is read, and every failure looks the same to\n * the caller except for `reason`, which is for the server's own log.\n */\nexport function verifyStorybookToken(\n  token: unknown,\n  secret: SecretInput,\n  now: number = Date.now(),\n): StorybookTokenResult {\n  if (typeof token !== \"string\" || !TOKEN_SHAPE.test(token)) {\n    return { ok: false, reason: \"malformed\" };\n  }\n  const [payload = \"\", given = \"\"] = token.split(\".\");\n  const signed = secretsOf(secret).some((key) =>\n    timingSafeEqualString(signature(key, payload), given),\n  );\n  if (!signed) {\n    return { ok: false, reason: \"signature\" };\n  }\n  return claimsOf(payload, Math.floor(now / 1000));\n}\n\n/** The path of a token's root: `/_s/<token>/`. */\nexport function storybookTokenPath(token: string): string {\n  return `${STORYBOOK_TOKEN_PREFIX}${token}/`;\n}\n\n/**\n * The lifetime of a render's tokens: the project's override when it has one, otherwise the render\n * budget (seconds) plus {@link STORYBOOK_URL_TTL_GRACE}, never below {@link DEFAULT_STORYBOOK_URL_TTL}\n * and never above {@link MAX_STORYBOOK_URL_TTL}. A pass cannot outlive its budget, so a token\n * derived from it lasts as long as the pass that carries it.\n */\nexport function storybookUrlTtl(input: {\n  override?: number | null | undefined;\n  budgetMs: number;\n}): number {\n  if (input.override !== undefined && input.override !== null) {\n    return input.override;\n  }\n  const derived = Math.ceil(input.budgetMs / 1000) + STORYBOOK_URL_TTL_GRACE;\n  return Math.min(MAX_STORYBOOK_URL_TTL, Math.max(DEFAULT_STORYBOOK_URL_TTL, derived));\n}\n\n/** The reason a project's lifetime override is refused, or `undefined` when it is acceptable. */\nexport function storybookUrlTtlOverrideError(seconds: number): string | undefined {\n  if (\n    Number.isInteger(seconds) &&\n    seconds >= MIN_STORYBOOK_URL_TTL_OVERRIDE &&\n    seconds <= MAX_STORYBOOK_URL_TTL\n  ) {\n    return undefined;\n  }\n  return `The signed URL lifetime is a whole number of seconds from ${MIN_STORYBOOK_URL_TTL_OVERRIDE} (one slice of ${MIN_CAPTURES_PER_SLICE} captures plus the ${STORYBOOK_URL_TTL_GRACE} s grace) to ${MAX_STORYBOOK_URL_TTL}`;\n}\n\n/** Throws unless `seconds` is an integer within the allowed lifetime range. */\nexport function assertStorybookUrlTtl(seconds: number): void {\n  if (\n    !Number.isInteger(seconds) ||\n    seconds < MIN_STORYBOOK_URL_TTL ||\n    seconds > MAX_STORYBOOK_URL_TTL\n  ) {\n    throw new Error(\n      `A Storybook URL lifetime must be a whole number of seconds from ${MIN_STORYBOOK_URL_TTL} to ${MAX_STORYBOOK_URL_TTL}, got ${String(seconds)}`,\n    );\n  }\n}\n\nfunction claimsOf(payload: string, nowSeconds: number): StorybookTokenResult {\n  const match = CLAIMS_SHAPE.exec(Buffer.from(payload, \"base64url\").toString(\"utf8\"));\n  if (!match) {\n    return { ok: false, reason: \"malformed\" };\n  }\n  const [, projectId = \"\", buildId = \"\", exp = \"\", purpose] = match;\n  const expiresAt = Number(exp);\n  if (expiresAt <= nowSeconds) {\n    return { ok: false, reason: \"expired\" };\n  }\n  if (expiresAt > nowSeconds + MAX_STORYBOOK_URL_TTL) {\n    return { ok: false, reason: \"scope\" };\n  }\n  return {\n    ok: true,\n    claims: { projectId, buildId, expiresAt, ...(purpose === \"capture\" ? { purpose } : {}) },\n  };\n}\n\n/** The key tokens are signed with; throws when none is configured. */\nfunction currentSecret(secret: SecretInput): string {\n  const current = typeof secret === \"object\" ? secret.current : secret;\n  if (!current) {\n    throw new Error(\"Cannot sign a Storybook URL: ShelfConfig.secret is not configured\");\n  }\n  return current;\n}\n\n/** Every key a token may verify with: the current secret and, during a rotation, the previous one. */\nfunction secretsOf(secret: SecretInput): string[] {\n  const keys = typeof secret === \"object\" ? [secret.current, secret.previous] : [secret];\n  return keys.filter((key): key is string => key !== undefined && key !== \"\");\n}\n\nfunction signature(secret: string, payload: string): string {\n  const key = createHmac(\"sha256\", secret).update(KEY_CONTEXT).digest();\n  return createHmac(\"sha256\", key).update(payload).digest(\"base64url\");\n}\n"],"mappings":"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"}

package/dist/utils/storybook-url.d.mts

@@ -1,6 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/utils/storybook-url.d.ts
 /** The Storybook URL a runner opens for a `reach: "url"` target (ADR 0007, decision 5). */
 /**
  * The root of a build's Storybook from the URL core hands a runner, without its trailing slash. The
@@ -10,6 +9,5 @@ import __tsdown_shims_url from 'node:url';
  * quoted in the error.
  */
 declare function storybookBase(storybookUrl: string): string;
-//#endregion
 export { storybookBase };
 //# sourceMappingURL=storybook-url.d.mts.map

package/dist/utils/storybook-url.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/utils/storybook-url.ts
+// src/utils/storybook-url.ts
 /** The Storybook URL a runner opens for a `reach: "url"` target (ADR 0007, decision 5). */
 /**
 * The root of a build's Storybook from the URL core hands a runner, without its trailing slash. The
@@ -15,7 +15,6 @@ function storybookBase(storybookUrl) {
 	if (url.search !== "" || url.hash !== "" || !url.pathname.endsWith("/")) throw new Error("The Storybook URL must be the build's directory root (ending in a slash, no query or fragment)");
 	return `${url.origin}${url.pathname.replace(/\/+$/u, "")}`;
 }
-//#endregion
 export { storybookBase };
 
 //# sourceMappingURL=storybook-url.mjs.map

package/dist/utils/timing.d.mts

@@ -1,6 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/utils/timing.d.ts
 /** Aggregated durations for one scope (family/phase name → total ms). */
 type TimingMap = Record<string, number>;
 /** Run `fn` with a fresh timing scope, returning its result and aggregates. */
@@ -14,6 +13,5 @@ declare function addTiming(name: string, durationMs: number): void;
 declare function timed<T>(name: string, fn: () => T | Promise<T>): Promise<T>;
 /** Copy of aggregates with whole-millisecond values for logs and headers. */
 declare function roundedTimings(timings: TimingMap): TimingMap;
-//#endregion
 export { TimingMap, addTiming, roundedTimings, runWithTimings, timed };
 //# sourceMappingURL=timing.d.mts.map

package/dist/utils/timing.mjs

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { AsyncLocalStorage } from "node:async_hooks";
-//#region src/utils/timing.ts
+// src/utils/timing.ts
 /**
 * Per-scope timing recorder: aggregate millisecond sums under shared names.
 *
@@ -40,7 +40,6 @@ async function timed(name, fn) {
 function roundedTimings(timings) {
 	return Object.fromEntries(Object.entries(timings).map(([name, ms]) => [name, Math.round(ms)]));
 }
-//#endregion
 export { addTiming, roundedTimings, runWithTimings, timed };
 
 //# sourceMappingURL=timing.mjs.map

package/dist/utils/ulid.d.mts

@@ -1,10 +1,8 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/utils/ulid.d.ts
 /** Generate a sortable, collision-resistant ULID. */
 declare function ulid(): string;
 /** Convert a name to a URL-safe slug of at most 63 characters. */
 declare function slugify(value: string): string;
-//#endregion
 export { slugify, ulid };
 //# sourceMappingURL=ulid.d.mts.map

package/dist/utils/ulid.mjs

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { randomBytes } from "node:crypto";
-//#region src/utils/ulid.ts
+// src/utils/ulid.ts
 /** Generate a sortable, collision-resistant ULID. */
 function ulid() {
 	return encodeTime(Date.now()) + encodeRandom(randomBytes(10));
@@ -37,7 +37,6 @@ function encodeRandom(bytes) {
 	if (bits > 0) out += CROCKFORD.charAt(buffer << 5 - bits & 31);
 	return out;
 }
-//#endregion
 export { slugify, ulid };
 
 //# sourceMappingURL=ulid.mjs.map

package/dist/utils/zip-read.mjs

@@ -3,7 +3,7 @@ import "node:url";
 import.meta.url;
 import "node:buffer";
 import { crc32, inflateRawSync } from "node:zlib";
-//#region src/utils/zip-read.ts
+// src/utils/zip-read.ts
 /** A malformed, unsafe, or over-limit archive. */
 var ZipFormatError = class extends Error {
 	name = "ZipFormatError";
@@ -123,7 +123,6 @@ function inflate(raw, record) {
 		return fail(`Zip entry failed to inflate: ${record.name}`);
 	}
 }
-//#endregion
 export { ZipFormatError, isUnsafeEntryName, readZip };
 
 //# sourceMappingURL=zip-read.mjs.map

package/dist/utils/zip-write.d.mts

@@ -1,7 +1,6 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { Buffer } from "node:buffer";
-//#region src/utils/zip-write.d.ts
 /** One file to add to an archive; a `data` function is called lazily when the entry is written. */
 interface ZipSource {
   name: string;
@@ -13,6 +12,5 @@ interface ZipSource {
  * @throws When the archive would need zip64 (more than 65535 entries or 4 GiB).
  */
 declare function zipStream(sources: Iterable<ZipSource> | AsyncIterable<ZipSource>): AsyncGenerator<Buffer>;
-//#endregion
 export { ZipSource, zipStream };
 //# sourceMappingURL=zip-write.d.mts.map

package/dist/utils/zip-write.mjs

@@ -3,7 +3,7 @@ import "node:url";
 import.meta.url;
 import { Buffer } from "node:buffer";
 import { crc32 } from "node:zlib";
-//#region src/utils/zip-write.ts
+// src/utils/zip-write.ts
 /**
 * Minimal streaming zip writer (STORE method, no zip64).
 *
@@ -182,7 +182,6 @@ function* trailer(central, offset) {
 		]
 	]);
 }
-//#endregion
 export { zipStream };
 
 //# sourceMappingURL=zip-write.mjs.map

package/dist/utils.d.mts

@@ -3,14 +3,14 @@ import __tsdown_shims_url from 'node:url';
 import { KeyUsed, SecretInput, SecretKeys, UndecryptableCredentialError, decrypt, decryptCredential, decryptWithKey, encrypt } from "./utils/encrypt.mjs";
 import { Env, detectPublicBaseUrl, normalizeOrigin } from "./utils/public-origin.mjs";
 import { hmacSha256, randomToken, sha256, timingSafeEqualString } from "./utils/hash.mjs";
-import { HttpError, HttpRequestOptions, HttpTextOptions, httpBytes, httpJson, httpText } from "./utils/http.mjs";
-import { baselinePath, catalogPath, contentDir, contentPath, designRenderPath, diffPath, isContentPath, modeSegment, screenshotPath, storybookDir, storybookZipPath } from "./paths.mjs";
+import { HttpError, HttpRequestOptions, HttpTextOptions, httpBytes, httpJson, httpStatus, httpText } from "./utils/http.mjs";
+import { baselinePath, catalogPath, contentDir, contentPath, designRenderPath, diffPath, isContentPath, modeSegment, publishedGzipPath, screenshotPath, storybookDir, storybookZipPath } from "./paths.mjs";
 import { AdaptiveConcurrency, AdaptiveOptions, Observation, isTimeoutError } from "./utils/adaptive-concurrency.mjs";
 import { detectCaptureEnvironment, systemFontsHash } from "./utils/environment.mjs";
 import { RetryConnectOptions, isRetryableConnectError, retryConnect } from "./utils/connect-retry.mjs";
-import { BrowserProbe, FONT_PROBE_FAMILIES, inPageProbe, remoteEnvironment } from "./utils/remote-environment.mjs";
+import { BrowserProbe, FONT_PROBE_FAMILIES, ProbeControl, ProbeOutcome, boundedProbe, inPageProbe, remoteEnvironment } from "./utils/remote-environment.mjs";
 import { storybookBase } from "./utils/storybook-url.mjs";
-import { DEFAULT_STORYBOOK_URL_TTL, MAX_STORYBOOK_URL_TTL, MIN_CAPTURES_PER_SLICE, MIN_STORYBOOK_URL_TTL, MIN_STORYBOOK_URL_TTL_OVERRIDE, PER_CAPTURE_BUDGET_MS, STORYBOOK_TOKEN_PREFIX, STORYBOOK_TOKEN_SOURCE, STORYBOOK_URL_TTL_GRACE, SignStorybookTokenInput, StorybookTokenClaims, StorybookTokenFailure, StorybookTokenResult, assertStorybookUrlTtl, signStorybookToken, storybookTokenPath, storybookUrlTtl, storybookUrlTtlOverrideError, verifyStorybookToken } from "./utils/storybook-token.mjs";
+import { DEFAULT_STORYBOOK_URL_TTL, MAX_STORYBOOK_URL_TTL, MIN_CAPTURES_PER_SLICE, MIN_STORYBOOK_URL_TTL, MIN_STORYBOOK_URL_TTL_OVERRIDE, PER_CAPTURE_BUDGET_MS, STORYBOOK_TOKEN_PREFIX, STORYBOOK_TOKEN_SOURCE, STORYBOOK_URL_TTL_GRACE, SignStorybookTokenInput, StorybookTokenClaims, StorybookTokenFailure, StorybookTokenPurpose, StorybookTokenResult, assertStorybookUrlTtl, signStorybookToken, storybookTokenPath, storybookUrlTtl, storybookUrlTtlOverrideError, verifyStorybookToken } from "./utils/storybook-token.mjs";
 import { SessionGate, createSessionGate, sessionGateFor } from "./utils/session-gate.mjs";
 import { storeScreenshot } from "./utils/screenshot-store.mjs";
 import { PageLimiter, PageLimiterOptions, createPageLimiter } from "./utils/page-limiter.mjs";
@@ -23,4 +23,4 @@ import { redactSecrets, sanitizeErrorText } from "./utils/redact.mjs";
 import { TimingMap, addTiming, roundedTimings, runWithTimings, timed } from "./utils/timing.mjs";
 import { slugify, ulid } from "./utils/ulid.mjs";
 import { ZipSource, zipStream } from "./utils/zip-write.mjs";
-export { AdaptiveConcurrency, type AdaptiveOptions, type BrowserProbe, type CaptureHostSummary, DEFAULT_RECYCLE_BROWSER_EVERY, DEFAULT_STORYBOOK_URL_TTL, type Env, FONT_PROBE_FAMILIES, type HostResources, HttpError, type HttpRequestOptions, type HttpTextOptions, type KeyUsed, MAX_STORYBOOK_URL_TTL, MIME_TYPES, MIN_CAPTURES_PER_SLICE, MIN_STORYBOOK_URL_TTL, MIN_STORYBOOK_URL_TTL_OVERRIDE, type Observation, PER_CAPTURE_BUDGET_MS, type PageLimiter, type PageLimiterOptions, type RetryConnectOptions, STORYBOOK_TOKEN_PREFIX, STORYBOOK_TOKEN_SOURCE, STORYBOOK_URL_TTL_GRACE, type SecretInput, type SecretKeys, type SessionGate, type SignStorybookTokenInput, type StorybookTokenClaims, type StorybookTokenFailure, type StorybookTokenResult, type TimingMap, UndecryptableCredentialError, type ZipSource, addTiming, assertStorybookUrlTtl, baselinePath, catalogPath, chunk, contentDir, contentPath, createPageLimiter, createSessionGate, decrypt, decryptCredential, decryptWithKey, describeCaptureHost, describeSizing, designRenderPath, detectCaptureEnvironment, detectPublicBaseUrl, detectResources, diffPath, encrypt, engineWeight, hmacSha256, httpBytes, httpJson, httpText, inPageProbe, isBlockedTarget, isContentPath, isPathSafe, isRetryableConnectError, isSafeSegment, isTimeoutError, mapAdaptive, mapLimit, maxPageConcurrency, mimeFor, modeSegment, normalizeOrigin, randomToken, recommendedBuildConcurrency, recommendedNavigationTimeoutMs, recommendedPageConcurrency, redactSecrets, remoteEnvironment, retryConnect, roundedTimings, runWithTimings, sanitizeErrorText, screenshotPath, sessionGateFor, sha256, signStorybookToken, slugify, storeScreenshot, storybookBase, storybookDir, storybookTokenPath, storybookUrlTtl, storybookUrlTtlOverrideError, storybookZipPath, systemFontsHash, timed, timingSafeEqualString, ulid, verifyStorybookToken, zipStream };
+export { AdaptiveConcurrency, type AdaptiveOptions, type BrowserProbe, type CaptureHostSummary, DEFAULT_RECYCLE_BROWSER_EVERY, DEFAULT_STORYBOOK_URL_TTL, type Env, FONT_PROBE_FAMILIES, type HostResources, HttpError, type HttpRequestOptions, type HttpTextOptions, type KeyUsed, MAX_STORYBOOK_URL_TTL, MIME_TYPES, MIN_CAPTURES_PER_SLICE, MIN_STORYBOOK_URL_TTL, MIN_STORYBOOK_URL_TTL_OVERRIDE, type Observation, PER_CAPTURE_BUDGET_MS, type PageLimiter, type PageLimiterOptions, type ProbeControl, type ProbeOutcome, type RetryConnectOptions, STORYBOOK_TOKEN_PREFIX, STORYBOOK_TOKEN_SOURCE, STORYBOOK_URL_TTL_GRACE, type SecretInput, type SecretKeys, type SessionGate, type SignStorybookTokenInput, type StorybookTokenClaims, type StorybookTokenFailure, type StorybookTokenPurpose, type StorybookTokenResult, type TimingMap, UndecryptableCredentialError, type ZipSource, addTiming, assertStorybookUrlTtl, baselinePath, boundedProbe, catalogPath, chunk, contentDir, contentPath, createPageLimiter, createSessionGate, decrypt, decryptCredential, decryptWithKey, describeCaptureHost, describeSizing, designRenderPath, detectCaptureEnvironment, detectPublicBaseUrl, detectResources, diffPath, encrypt, engineWeight, hmacSha256, httpBytes, httpJson, httpStatus, httpText, inPageProbe, isBlockedTarget, isContentPath, isPathSafe, isRetryableConnectError, isSafeSegment, isTimeoutError, mapAdaptive, mapLimit, maxPageConcurrency, mimeFor, modeSegment, normalizeOrigin, publishedGzipPath, randomToken, recommendedBuildConcurrency, recommendedNavigationTimeoutMs, recommendedPageConcurrency, redactSecrets, remoteEnvironment, retryConnect, roundedTimings, runWithTimings, sanitizeErrorText, screenshotPath, sessionGateFor, sha256, signStorybookToken, slugify, storeScreenshot, storybookBase, storybookDir, storybookTokenPath, storybookUrlTtl, storybookUrlTtlOverrideError, storybookZipPath, systemFontsHash, timed, timingSafeEqualString, ulid, verifyStorybookToken, zipStream };