@storyshelf/core 0.6.2 → 0.8.0

package/dist/utils/resources.mjs

@@ -0,0 +1,121 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { availableParallelism, totalmem } from "node:os";
+import { readFileSync } from "node:fs";
+// src/utils/resources.ts
+const MB = 1048576;
+/** Headroom for Node, the server and Chromium's browser process. */
+const BASE_MEMORY_MB = 512;
+/** Typical cost of one rendering page. */
+const PAGE_MEMORY_MB = 300;
+const MAX_PAGES = 4;
+/** Ceiling for the adaptive controller, in Chromium-page slots. */
+const MAX_ADAPTIVE_PAGES = 8;
+/**
+* Detect the CPU and memory budget. Container limits win over the host's: a
+* 0.5 vCPU / 1 GB container on a large machine must be sized as 0.5 / 1 GB.
+*/
+function detectResources() {
+	const cpus = Math.min(availableParallelism(), cgroupCpus() ?? Infinity);
+	const constrained = typeof process.constrainedMemory === "function" ? process.constrainedMemory() : 0;
+	return {
+		cpus,
+		memoryBytes: constrained > 0 && constrained < totalmem() ? constrained : totalmem()
+	};
+}
+/**
+* Cost of one page in Chromium-page slots. Firefox and WebKit pages cost about twice a Chromium
+* page in CPU time (ray.run cross-browser benchmarks: Firefox +71%, WebKit +60%; some Playwright
+* reports show WebKit worse), so they get half the page budget. Takes a capture target too.
+*/
+function engineWeight(browser) {
+	const engine = browser?.split("@")[0];
+	return engine === "firefox" || engine === "webkit" ? 2 : 1;
+}
+/**
+* Pages to render at once: no more than the CPUs (extra pages only slow each
+* other down and trip timeouts) and no more than memory allows. A heavier engine
+* (see {@link engineWeight}) spends the same budget on fewer pages.
+*/
+function recommendedPageConcurrency(resources = detectResources(), browser) {
+	const budget = Math.min(Math.ceil(resources.cpus), memoryPages(resources), MAX_PAGES);
+	return Math.max(1, Math.floor(budget / engineWeight(browser)));
+}
+/**
+* Most pages the adaptive controller may reach: memory is a hard limit, but CPU is only a
+* starting point (latency tells us when it is saturated), so allow up to twice the CPUs.
+*/
+function maxPageConcurrency(resources = detectResources(), browser) {
+	const budget = Math.min(Math.ceil(resources.cpus) * 2, memoryPages(resources), MAX_ADAPTIVE_PAGES);
+	return Math.max(recommendedPageConcurrency(resources, browser), Math.floor(budget / engineWeight(browser)));
+}
+function memoryPages(resources) {
+	return Math.floor((resources.memoryBytes / MB - BASE_MEMORY_MB) / PAGE_MEMORY_MB);
+}
+/** Builds to capture at once: each launches its own browser, so only on roomy hosts. */
+function recommendedBuildConcurrency(resources = detectResources()) {
+	return resources.cpus >= 2 && resources.memoryBytes >= 3072 * MB ? 2 : 1;
+}
+/** Playwright's 30 s default assumes a full CPU; starved containers parse the Storybook bundle slower. */
+function recommendedNavigationTimeoutMs(resources = detectResources()) {
+	if (resources.cpus < 1) return 9e4;
+	if (resources.cpus < 2) return 6e4;
+	return 3e4;
+}
+/** Captures between browser restarts: Chromium grows slowly over a long run, so recycle it. */
+const DEFAULT_RECYCLE_BROWSER_EVERY = 150;
+/** Loggable summary of the host budget and the capture settings derived from it. */
+function describeSizing(settings) {
+	const resources = detectResources();
+	return {
+		cpus: Math.round(resources.cpus * 100) / 100,
+		memoryMb: Math.round(resources.memoryBytes / MB),
+		pages: settings.concurrency ?? recommendedPageConcurrency(resources, settings.browser),
+		maxPages: settings.concurrency ?? maxPageConcurrency(resources, settings.browser),
+		navigationTimeoutMs: settings.navigationTimeoutMs ?? recommendedNavigationTimeoutMs(resources),
+		recycleBrowserEvery: settings.recycleBrowserEvery ?? 150
+	};
+}
+/** Summarise the host budget and effective capture concurrency, for the System page. */
+function describeCaptureHost(configuredBuilds, resources = detectResources()) {
+	return {
+		cpus: Math.round(resources.cpus * 100) / 100,
+		memoryMb: Math.round(resources.memoryBytes / MB),
+		builds: {
+			value: configuredBuilds ?? recommendedBuildConcurrency(resources),
+			auto: configuredBuilds === void 0
+		},
+		pages: {
+			start: recommendedPageConcurrency(resources),
+			max: maxPageConcurrency(resources)
+		}
+	};
+}
+function cgroupCpus() {
+	return cgroupV2Cpus() ?? cgroupV1Cpus();
+}
+function cgroupV2Cpus() {
+	const [quota, period] = readText("/sys/fs/cgroup/cpu.max")?.trim().split(/\s+/u) ?? [];
+	return quotaToCpus(quota, period);
+}
+function cgroupV1Cpus() {
+	const quota = readText("/sys/fs/cgroup/cpu/cpu.cfs_quota_us")?.trim();
+	const period = readText("/sys/fs/cgroup/cpu/cpu.cfs_period_us")?.trim();
+	return quotaToCpus(quota, period);
+}
+function quotaToCpus(quota, period) {
+	const q = Number(quota);
+	const p = Number(period);
+	return Number.isFinite(q) && q > 0 && Number.isFinite(p) && p > 0 ? q / p : null;
+}
+function readText(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return null;
+	}
+}
+export { DEFAULT_RECYCLE_BROWSER_EVERY, describeCaptureHost, describeSizing, detectResources, engineWeight, maxPageConcurrency, recommendedBuildConcurrency, recommendedNavigationTimeoutMs, recommendedPageConcurrency };
+
+//# sourceMappingURL=resources.mjs.map

package/dist/utils/resources.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.mjs","names":[],"sources":["../../src/utils/resources.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\";\nimport { availableParallelism, totalmem } from \"node:os\";\n\n/** CPU and memory actually available to this process (container limits included). */\nexport interface HostResources {\n  /** Fractional vCPUs: a cgroup quota of 0.5 CPU reports `0.5`. */\n  cpus: number;\n  memoryBytes: number;\n}\n\nconst MB = 1024 * 1024;\n/** Headroom for Node, the server and Chromium's browser process. */\nconst BASE_MEMORY_MB = 512;\n/** Typical cost of one rendering page. */\nconst PAGE_MEMORY_MB = 300;\nconst MAX_PAGES = 4;\n/** Ceiling for the adaptive controller, in Chromium-page slots. */\nconst MAX_ADAPTIVE_PAGES = 8;\n\n/**\n * Detect the CPU and memory budget. Container limits win over the host's: a\n * 0.5 vCPU / 1 GB container on a large machine must be sized as 0.5 / 1 GB.\n */\nexport function detectResources(): HostResources {\n  const cpus = Math.min(availableParallelism(), cgroupCpus() ?? Infinity);\n  const constrained =\n    typeof process.constrainedMemory === \"function\" ? process.constrainedMemory() : 0;\n  const memoryBytes = constrained > 0 && constrained < totalmem() ? constrained : totalmem();\n  return { cpus, memoryBytes };\n}\n\n/**\n * Cost of one page in Chromium-page slots. Firefox and WebKit pages cost about twice a Chromium\n * page in CPU time (ray.run cross-browser benchmarks: Firefox +71%, WebKit +60%; some Playwright\n * reports show WebKit worse), so they get half the page budget. Takes a capture target too.\n */\nexport function engineWeight(browser?: string): number {\n  // A target is `<engine>[@<name>]`; the engine decides the page cost.\n  const engine = browser?.split(\"@\")[0];\n  return engine === \"firefox\" || engine === \"webkit\" ? 2 : 1;\n}\n\n/**\n * Pages to render at once: no more than the CPUs (extra pages only slow each\n * other down and trip timeouts) and no more than memory allows. A heavier engine\n * (see {@link engineWeight}) spends the same budget on fewer pages.\n */\nexport function recommendedPageConcurrency(\n  resources: HostResources = detectResources(),\n  browser?: string,\n): number {\n  const budget = Math.min(Math.ceil(resources.cpus), memoryPages(resources), MAX_PAGES);\n  return Math.max(1, Math.floor(budget / engineWeight(browser)));\n}\n\n/**\n * Most pages the adaptive controller may reach: memory is a hard limit, but CPU is only a\n * starting point (latency tells us when it is saturated), so allow up to twice the CPUs.\n */\nexport function maxPageConcurrency(\n  resources: HostResources = detectResources(),\n  browser?: string,\n): number {\n  const budget = Math.min(\n    Math.ceil(resources.cpus) * 2,\n    memoryPages(resources),\n    MAX_ADAPTIVE_PAGES,\n  );\n  return Math.max(\n    recommendedPageConcurrency(resources, browser),\n    Math.floor(budget / engineWeight(browser)),\n  );\n}\n\nfunction memoryPages(resources: HostResources): number {\n  return Math.floor((resources.memoryBytes / MB - BASE_MEMORY_MB) / PAGE_MEMORY_MB);\n}\n\n/** Builds to capture at once: each launches its own browser, so only on roomy hosts. */\nexport function recommendedBuildConcurrency(resources: HostResources = detectResources()): number {\n  return resources.cpus >= 2 && resources.memoryBytes >= 3 * 1024 * MB ? 2 : 1;\n}\n\n/** Playwright's 30 s default assumes a full CPU; starved containers parse the Storybook bundle slower. */\nexport function recommendedNavigationTimeoutMs(\n  resources: HostResources = detectResources(),\n): number {\n  if (resources.cpus < 1) return 90_000;\n  if (resources.cpus < 2) return 60_000;\n  return 30_000;\n}\n\n/** Captures between browser restarts: Chromium grows slowly over a long run, so recycle it. */\nexport const DEFAULT_RECYCLE_BROWSER_EVERY = 150;\n\n/** Loggable summary of the host budget and the capture settings derived from it. */\nexport function describeSizing(settings: {\n  browser?: string;\n  concurrency?: number;\n  navigationTimeoutMs?: number;\n  recycleBrowserEvery?: number;\n}): Record<string, number> {\n  const resources = detectResources();\n  return {\n    cpus: Math.round(resources.cpus * 100) / 100,\n    memoryMb: Math.round(resources.memoryBytes / MB),\n    pages: settings.concurrency ?? recommendedPageConcurrency(resources, settings.browser),\n    maxPages: settings.concurrency ?? maxPageConcurrency(resources, settings.browser),\n    navigationTimeoutMs: settings.navigationTimeoutMs ?? recommendedNavigationTimeoutMs(resources),\n    recycleBrowserEvery: settings.recycleBrowserEvery ?? DEFAULT_RECYCLE_BROWSER_EVERY,\n  };\n}\n\n/** What capture will use on this host: detected resources and the effective concurrency. */\nexport interface CaptureHostSummary {\n  cpus: number;\n  memoryMb: number;\n  /** Builds captured at once, and whether that was sized from the hardware or configured. */\n  builds: { value: number; auto: boolean };\n  /** Pages per build when the runner is not pinned: where it starts and the most it may reach (Chromium). */\n  pages: { start: number; max: number };\n}\n\n/** Summarise the host budget and effective capture concurrency, for the System page. */\nexport function describeCaptureHost(\n  configuredBuilds?: number,\n  resources: HostResources = detectResources(),\n): CaptureHostSummary {\n  return {\n    cpus: Math.round(resources.cpus * 100) / 100,\n    memoryMb: Math.round(resources.memoryBytes / MB),\n    builds: {\n      value: configuredBuilds ?? recommendedBuildConcurrency(resources),\n      auto: configuredBuilds === undefined,\n    },\n    pages: { start: recommendedPageConcurrency(resources), max: maxPageConcurrency(resources) },\n  };\n}\n\nfunction cgroupCpus(): number | null {\n  return cgroupV2Cpus() ?? cgroupV1Cpus();\n}\n\nfunction cgroupV2Cpus(): number | null {\n  const [quota, period] = readText(\"/sys/fs/cgroup/cpu.max\")?.trim().split(/\\s+/u) ?? [];\n  return quotaToCpus(quota, period);\n}\n\nfunction cgroupV1Cpus(): number | null {\n  const quota = readText(\"/sys/fs/cgroup/cpu/cpu.cfs_quota_us\")?.trim();\n  const period = readText(\"/sys/fs/cgroup/cpu/cpu.cfs_period_us\")?.trim();\n  return quotaToCpus(quota, period);\n}\n\nfunction quotaToCpus(quota: string | undefined, period: string | undefined): number | null {\n  const q = Number(quota);\n  const p = Number(period);\n  return Number.isFinite(q) && q > 0 && Number.isFinite(p) && p > 0 ? q / p : null;\n}\n\nfunction readText(path: string): string | null {\n  try {\n    return readFileSync(path, \"utf8\");\n  } catch {\n    return null;\n  }\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,13 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { StorageAdapter } from "../adapter/storage.mjs";
+/**
+ * Store a screenshot under the SHA-256 of its bytes and return its path.
+ *
+ * An unchanged story renders the same bytes build after build, so the object usually exists
+ * already and nothing is uploaded. Snapshots and baselines then point at the same object, and
+ * 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>;
+export { storeScreenshot };
+//# sourceMappingURL=screenshot-store.d.mts.map

package/dist/utils/screenshot-store.mjs

@@ -0,0 +1,40 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { ulid } from "./ulid.mjs";
+import { contentDir, contentPath } from "../paths.mjs";
+import { createHash } from "node:crypto";
+// 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.
+*
+* An unchanged story renders the same bytes build after build, so the object usually exists
+* already and nothing is uploaded. Snapshots and baselines then point at the same object, and
+* identical paths mean identical pixels (the diff can be skipped without reading either image).
+*/
+async function storeScreenshot(storage, projectId, data) {
+	const path = contentPath(projectId, createHash("sha256").update(data).digest("hex"));
+	if (!await storage.exists(path)) await storage.write(path, data);
+	return path;
+}
+/** Folder inside a project's content directory holding in-flight reuse claims. */
+const CLAIMS_DIR = ".claims";
+/**
+* Run `work` under a reuse claim the screenshot sweep honours: while the claim exists (and is
+* younger than the sweep's grace period) nothing in the project's content is deleted. For work
+* outside a capture that reuses objects before writing the rows that reference them (baseline
+* import, approving a legacy snapshot); a capture is covered by its build's status instead.
+*/
+async function withContentClaim(storage, projectId, work) {
+	const path = `${contentDir(projectId)}/${CLAIMS_DIR}/${ulid()}.json`;
+	await storage.write(path, Buffer.from(JSON.stringify({ at: Date.now() })));
+	try {
+		return await work();
+	} finally {
+		await storage.delete(path).catch(() => false);
+	}
+}
+export { CLAIMS_DIR, storeScreenshot, withContentClaim };
+
+//# sourceMappingURL=screenshot-store.mjs.map

package/dist/utils/screenshot-store.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot-store.mjs","names":[],"sources":["../../src/utils/screenshot-store.ts"],"sourcesContent":["/** Content-addressed screenshot storage: identical bytes are stored once per project. */\nimport { createHash } from \"node:crypto\";\nimport type { StorageAdapter } from \"../adapters/storage.ts\";\nimport { contentDir, contentPath } from \"./paths.ts\";\nimport { ulid } from \"./ulid.ts\";\n\n/**\n * Store a screenshot under the SHA-256 of its bytes and return its path.\n *\n * An unchanged story renders the same bytes build after build, so the object usually exists\n * already and nothing is uploaded. Snapshots and baselines then point at the same object, and\n * identical paths mean identical pixels (the diff can be skipped without reading either image).\n */\nexport async function storeScreenshot(\n  storage: StorageAdapter,\n  projectId: string,\n  data: Buffer,\n): Promise<string> {\n  const path = contentPath(projectId, createHash(\"sha256\").update(data).digest(\"hex\"));\n  if (!(await storage.exists(path))) {\n    await storage.write(path, data);\n  }\n  return path;\n}\n\n/** Folder inside a project's content directory holding in-flight reuse claims. */\nexport const CLAIMS_DIR = \".claims\";\n\n/**\n * Run `work` under a reuse claim the screenshot sweep honours: while the claim exists (and is\n * younger than the sweep's grace period) nothing in the project's content is deleted. For work\n * outside a capture that reuses objects before writing the rows that reference them (baseline\n * import, approving a legacy snapshot); a capture is covered by its build's status instead.\n */\nexport async function withContentClaim<T>(\n  storage: StorageAdapter,\n  projectId: string,\n  work: () => Promise<T>,\n): Promise<T> {\n  const path = `${contentDir(projectId)}/${CLAIMS_DIR}/${ulid()}.json`;\n  await storage.write(path, Buffer.from(JSON.stringify({ at: Date.now() })));\n  try {\n    return await work();\n  } finally {\n    await storage.delete(path).catch(() => false);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAaA,eAAsB,gBACpB,SACA,WACA,MACiB;CACjB,MAAM,OAAO,YAAY,WAAW,WAAW,QAAQ,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC;CACnF,IAAI,CAAE,MAAM,QAAQ,OAAO,IAAI,GAC7B,MAAM,QAAQ,MAAM,MAAM,IAAI;CAEhC,OAAO;AACT;;AAGA,MAAa,aAAa;;;;;;;AAQ1B,eAAsB,iBACpB,SACA,WACA,MACY;CACZ,MAAM,OAAO,GAAG,WAAW,SAAS,EAAE,GAAG,WAAW,GAAG,KAAK,EAAE;CAC9D,MAAM,QAAQ,MAAM,MAAM,OAAO,KAAK,KAAK,UAAU,EAAE,IAAI,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;CACzE,IAAI;EACF,OAAO,MAAM,KAAK;CACpB,UAAU;EACR,MAAM,QAAQ,OAAO,IAAI,CAAC,CAAC,YAAY,KAAK;CAC9C;AACF"}

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

@@ -0,0 +1,23 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+/** 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 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>;
+}
+/**
+ * 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.
+ */
+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

@@ -0,0 +1,69 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// 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, onInvalid) {
+	let gate = gates.get(target);
+	if (gate === void 0) {
+		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. 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 = () => {
+		active -= 1;
+		while (active < limitNow() && waiting.length > 0) {
+			active += 1;
+			waiting.shift()?.();
+		}
+	};
+	const acquire = async () => {
+		if (active < limitNow()) {
+			active += 1;
+			return;
+		}
+		await new Promise((resolve) => {
+			waiting.push(resolve);
+		});
+	};
+	return {
+		get size() {
+			return limitNow();
+		},
+		run: async (fn) => {
+			await acquire();
+			try {
+				return await fn();
+			} finally {
+				release();
+			}
+		}
+	};
+}
+export { createSessionGate, sessionGateFor };
+
+//# sourceMappingURL=session-gate.mjs.map

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

@@ -0,0 +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 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

@@ -0,0 +1,89 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { SecretInput } from "./encrypt.mjs";
+/** 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. */
+declare const STORYBOOK_TOKEN_SOURCE = "[A-Za-z0-9_-]{8,200}\\.[A-Za-z0-9_-]{43}";
+/** Floor of a derived lifetime, in seconds (2 hours). */
+declare const DEFAULT_STORYBOOK_URL_TTL = 7200;
+/** Shortest lifetime a token may be minted with (a render needs at least this). */
+declare const MIN_STORYBOOK_URL_TTL = 60;
+/** Ceiling of a derived lifetime and the longest accepted: a token claiming more is refused, whoever signed it. */
+declare const MAX_STORYBOOK_URL_TTL = 86400;
+/** Slack added to a render budget when deriving a lifetime (queue wait, retries, clock skew). */
+declare const STORYBOOK_URL_TTL_GRACE = 300;
+/** Extra time granted per capture of a render pass, in ms; sizes a pass's budget and its slices. */
+declare const PER_CAPTURE_BUDGET_MS = 15000;
+/** Smallest slice (captures), so a very short project override never renders a page per call. */
+declare const MIN_CAPTURES_PER_SLICE = 50;
+/**
+ * Shortest lifetime a project may set as its override (seconds): one minimum slice's budget plus
+ * the grace, so a slice never outlives its token. Single owner of the rule; every parser of the
+ * 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 {
+  /** The server secret (a rotation pair signs with its current key); throws when empty. */
+  secret: SecretInput;
+  projectId: string;
+  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;
+}
+/** Why a token was refused (kept apart from the response, which is the same for all). */
+type StorybookTokenFailure = "malformed" | "signature" | "expired" | "scope";
+/** The outcome of {@link verifyStorybookToken}. */
+type StorybookTokenResult = {
+  ok: true;
+  claims: StorybookTokenClaims;
+} | {
+  ok: false;
+  reason: StorybookTokenFailure;
+};
+/** Sign a token for one build. Throws on an empty secret, bad ids or a lifetime out of range. */
+declare function signStorybookToken(input: SignStorybookTokenInput): string;
+/**
+ * Check a token against the current secret and, during a rotation, the previous one. The signature
+ * is checked (in constant time) before the payload is read, and every failure looks the same to
+ * the caller except for `reason`, which is for the server's own log.
+ */
+declare function verifyStorybookToken(token: unknown, secret: SecretInput, now?: number): StorybookTokenResult;
+/** The path of a token's root: `/_s/<token>/`. */
+declare function storybookTokenPath(token: string): string;
+/**
+ * The lifetime of a render's tokens: the project's override when it has one, otherwise the render
+ * budget (seconds) plus {@link STORYBOOK_URL_TTL_GRACE}, never below {@link DEFAULT_STORYBOOK_URL_TTL}
+ * and never above {@link MAX_STORYBOOK_URL_TTL}. A pass cannot outlive its budget, so a token
+ * derived from it lasts as long as the pass that carries it.
+ */
+declare function storybookUrlTtl(input: {
+  override?: number | null | undefined;
+  budgetMs: number;
+}): number;
+/** The reason a project's lifetime override is refused, or `undefined` when it is acceptable. */
+declare function storybookUrlTtlOverrideError(seconds: number): string | undefined;
+/** Throws unless `seconds` is an integer within the allowed lifetime range. */
+declare function assertStorybookUrlTtl(seconds: number): void;
+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

@@ -0,0 +1,135 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { timingSafeEqualString } from "./hash.mjs";
+import { createHmac } from "node:crypto";
+// 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>[:<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/";
+/** Regex source of a token, shared by the shape check and the log redaction. */
+const STORYBOOK_TOKEN_SOURCE = "[A-Za-z0-9_-]{8,200}\\.[A-Za-z0-9_-]{43}";
+/** Floor of a derived lifetime, in seconds (2 hours). */
+const DEFAULT_STORYBOOK_URL_TTL = 7200;
+/** Shortest lifetime a token may be minted with (a render needs at least this). */
+const MIN_STORYBOOK_URL_TTL = 60;
+/** Ceiling of a derived lifetime and the longest accepted: a token claiming more is refused, whoever signed it. */
+const MAX_STORYBOOK_URL_TTL = 86400;
+/** Slack added to a render budget when deriving a lifetime (queue wait, retries, clock skew). */
+const STORYBOOK_URL_TTL_GRACE = 300;
+/** Extra time granted per capture of a render pass, in ms; sizes a pass's budget and its slices. */
+const PER_CAPTURE_BUDGET_MS = 15e3;
+/** Smallest slice (captures), so a very short project override never renders a page per call. */
+const MIN_CAPTURES_PER_SLICE = 50;
+/**
+* Shortest lifetime a project may set as its override (seconds): one minimum slice's budget plus
+* the grace, so a slice never outlives its token. Single owner of the rule; every parser of the
+* override (project API, settings form, page hint) reads it through {@link storybookUrlTtlOverrideError}.
+*/
+const MIN_STORYBOOK_URL_TTL_OVERRIDE = Math.ceil(50 * PER_CAPTURE_BUDGET_MS / 1e3) + 300;
+/** 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})(?::(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}${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)}`;
+}
+/**
+* Check a token against the current secret and, during a rotation, the previous one. The signature
+* is checked (in constant time) before the payload is read, and every failure looks the same to
+* the caller except for `reason`, which is for the server's own log.
+*/
+function verifyStorybookToken(token, secret, now = Date.now()) {
+	if (typeof token !== "string" || !TOKEN_SHAPE.test(token)) return {
+		ok: false,
+		reason: "malformed"
+	};
+	const [payload = "", given = ""] = token.split(".");
+	if (!secretsOf(secret).some((key) => timingSafeEqualString(signature(key, payload), given))) return {
+		ok: false,
+		reason: "signature"
+	};
+	return claimsOf(payload, Math.floor(now / 1e3));
+}
+/** The path of a token's root: `/_s/<token>/`. */
+function storybookTokenPath(token) {
+	return `${STORYBOOK_TOKEN_PREFIX}${token}/`;
+}
+/**
+* The lifetime of a render's tokens: the project's override when it has one, otherwise the render
+* budget (seconds) plus {@link STORYBOOK_URL_TTL_GRACE}, never below {@link DEFAULT_STORYBOOK_URL_TTL}
+* and never above {@link MAX_STORYBOOK_URL_TTL}. A pass cannot outlive its budget, so a token
+* derived from it lasts as long as the pass that carries it.
+*/
+function storybookUrlTtl(input) {
+	if (input.override !== void 0 && input.override !== null) return input.override;
+	const derived = Math.ceil(input.budgetMs / 1e3) + 300;
+	return Math.min(MAX_STORYBOOK_URL_TTL, Math.max(DEFAULT_STORYBOOK_URL_TTL, derived));
+}
+/** The reason a project's lifetime override is refused, or `undefined` when it is acceptable. */
+function storybookUrlTtlOverrideError(seconds) {
+	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. */
+function assertStorybookUrlTtl(seconds) {
+	if (!Number.isInteger(seconds) || seconds < 60 || seconds > 86400) throw new Error(`A Storybook URL lifetime must be a whole number of seconds from 60 to ${MAX_STORYBOOK_URL_TTL}, got ${String(seconds)}`);
+}
+function claimsOf(payload, nowSeconds) {
+	const match = CLAIMS_SHAPE.exec(Buffer.from(payload, "base64url").toString("utf8"));
+	if (!match) return {
+		ok: false,
+		reason: "malformed"
+	};
+	const [, projectId = "", buildId = "", exp = "", purpose] = match;
+	const expiresAt = Number(exp);
+	if (expiresAt <= nowSeconds) return {
+		ok: false,
+		reason: "expired"
+	};
+	if (expiresAt > nowSeconds + 86400) return {
+		ok: false,
+		reason: "scope"
+	};
+	return {
+		ok: true,
+		claims: {
+			projectId,
+			buildId,
+			expiresAt,
+			...purpose === "capture" ? { purpose } : {}
+		}
+	};
+}
+/** The key tokens are signed with; throws when none is configured. */
+function currentSecret(secret) {
+	const current = typeof secret === "object" ? secret.current : secret;
+	if (!current) throw new Error("Cannot sign a Storybook URL: ShelfConfig.secret is not configured");
+	return current;
+}
+/** Every key a token may verify with: the current secret and, during a rotation, the previous one. */
+function secretsOf(secret) {
+	return (typeof secret === "object" ? [secret.current, secret.previous] : [secret]).filter((key) => key !== void 0 && key !== "");
+}
+function signature(secret, payload) {
+	const key = createHmac("sha256", secret).update(KEY_CONTEXT).digest();
+	return createHmac("sha256", key).update(payload).digest("base64url");
+}
+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

@@ -0,0 +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>[:<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

@@ -0,0 +1,13 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+/** 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
+ * URL is the directory root `<origin>/_s/<token>/` and nothing else: no `iframe.html`, no query, no
+ * fragment, and a path ending in a slash. Anything else throws, so a runner never silently opens a
+ * different page than the one core signed. The URL carries a token and is never logged, nor is it
+ * quoted in the error.
+ */
+declare function storybookBase(storybookUrl: string): string;
+export { storybookBase };
+//# sourceMappingURL=storybook-url.d.mts.map

package/dist/utils/storybook-url.mjs

@@ -0,0 +1,20 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// 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
+* URL is the directory root `<origin>/_s/<token>/` and nothing else: no `iframe.html`, no query, no
+* fragment, and a path ending in a slash. Anything else throws, so a runner never silently opens a
+* different page than the one core signed. The URL carries a token and is never logged, nor is it
+* quoted in the error.
+*/
+function storybookBase(storybookUrl) {
+	const url = new URL(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, "")}`;
+}
+export { storybookBase };
+
+//# sourceMappingURL=storybook-url.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storybook-url.mjs","names":[],"sources":["../../src/utils/storybook-url.ts"],"sourcesContent":["/** The Storybook URL a runner opens for a `reach: \"url\"` target (ADR 0007, decision 5). */\n\n/**\n * The root of a build's Storybook from the URL core hands a runner, without its trailing slash. The\n * URL is the directory root `<origin>/_s/<token>/` and nothing else: no `iframe.html`, no query, no\n * fragment, and a path ending in a slash. Anything else throws, so a runner never silently opens a\n * different page than the one core signed. The URL carries a token and is never logged, nor is it\n * quoted in the error.\n */\nexport function storybookBase(storybookUrl: string): string {\n  const url = new URL(storybookUrl);\n  if (url.search !== \"\" || url.hash !== \"\" || !url.pathname.endsWith(\"/\")) {\n    throw new Error(\n      \"The Storybook URL must be the build's directory root (ending in a slash, no query or fragment)\",\n    );\n  }\n  return `${url.origin}${url.pathname.replace(/\\/+$/u, \"\")}`;\n}\n"],"mappings":";;;;;;;;;;;;AASA,SAAgB,cAAc,cAA8B;CAC1D,MAAM,MAAM,IAAI,IAAI,YAAY;CAChC,IAAI,IAAI,WAAW,MAAM,IAAI,SAAS,MAAM,CAAC,IAAI,SAAS,SAAS,GAAG,GACpE,MAAM,IAAI,MACR,gGACF;CAEF,OAAO,GAAG,IAAI,SAAS,IAAI,SAAS,QAAQ,SAAS,EAAE;AACzD"}

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