@storyshelf/core 0.6.1 → 0.7.0

package/dist/capture/tests.d.mts

@@ -0,0 +1,37 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import "./adapter.mjs";
+import "../adapter/capture-runner.mjs";
+import "./storybook-urls.mjs";
+import "../models/build.mjs";
+import "../models/capture-attempt.mjs";
+import { Logger } from "pino";
+//#region src/capture/tests.d.ts
+/** What a build keeps of one `.test()` entry (JSON in `builds.test_results`). */
+interface TestResult {
+  /** The test entry's id (`<story id>:<test name slug>`). */
+  id: string;
+  /** Story file title (the component path), as on its index entry. */
+  title: string;
+  /** The test's own name, as written in `story.test("...")`. */
+  name: string;
+  /** The story the test is written under. */
+  parentId: string | null;
+  status: "passed" | "failed";
+  /** The failure message of a failed test. */
+  error?: string;
+  durationMs: number;
+}
+/** Pass and fail counts of a build's tests. */
+interface TestSummary {
+  total: number;
+  passed: number;
+  failed: number;
+}
+/** The results a build holds; empty for none or an unreadable value. */
+declare function parseTestResults(json: string | null | undefined): TestResult[];
+/** Counts of a build's results. */
+declare function summarizeTests(results: readonly TestResult[]): TestSummary;
+//#endregion
+export { TestResult, TestSummary, parseTestResults, summarizeTests };
+//# sourceMappingURL=tests.d.mts.map

package/dist/capture/tests.mjs

@@ -0,0 +1,126 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { redactSecrets } from "../utils/redact.mjs";
+import { isDisabledStory } from "./adapter.mjs";
+import { emitAttemptLog } from "../models/capture-attempt.mjs";
+import { classifyFailures } from "./failure-sets.mjs";
+import { renderBudgetMs } from "./render.mjs";
+import { StorybookAdapter } from "./storybook.mjs";
+//#region src/capture/tests.ts
+/** Longest failure message kept (rows and logs stay bounded). */
+const ERROR_MAX = 1e3;
+/**
+* Run the build's `.test()` entries when the project turned tests on, and store the results on the
+* build. A failing test is a blocking failure of its own id, exactly like a `play` that throws; it
+* takes no screenshot, writes no snapshot and sets no status of its own. Without the setting (or
+* without test entries) nothing runs and nothing is written, except that results left by an
+* earlier run of the same build are cleared.
+*/
+async function runProjectTests(input) {
+	const tests = input.project.runTests ? await testsToRun(input) : [];
+	const run = input.runner.runTests?.bind(input.runner);
+	if (tests.length === 0 || !run) return await skipTests(input, tests.length);
+	const results = resultsOf(tests, await execute(input, run, tests));
+	await keepResults(input, results);
+	return await reportFailures(input, results, tests);
+}
+/** Nothing to run: warn when tests were wanted but the runner cannot, and clear stale results. */
+async function skipTests(input, wanted) {
+	if (wanted > 0) input.logger?.warn({ tests: wanted }, "project runs tests but the capture runner cannot run them; skipped");
+	await keepResults(input, null);
+	return {
+		blocking: /* @__PURE__ */ new Set(),
+		flaky: /* @__PURE__ */ new Set()
+	};
+}
+/** The test entries to run: those of stories that are not skipped. */
+async function testsToRun(input) {
+	const skipped = new Set(input.stories.filter((story) => isDisabledStory(story)).map((s) => s.id));
+	return (await new StorybookAdapter().discoverTests(input.storybookDir)).filter((entry) => !isDisabledStory(entry) && !(entry.parentId !== void 0 && skipped.has(entry.parentId)));
+}
+async function execute(input, run, tests) {
+	const storybookUrl = await input.storybookUrl?.(input.target, { budgetMs: renderBudgetMs(tests.length) });
+	await emitAttemptLog(input.recordLog, input.logger, "info", "running storybook tests", { tests: tests.length });
+	return await run({
+		buildId: input.build.id,
+		storybookDir: input.storybookDir,
+		tests,
+		playTimeoutMs: input.project.playTimeoutMs,
+		target: input.target,
+		...storybookUrl === void 0 ? {} : { storybookUrl },
+		...input.logger ? { logger: input.logger } : {}
+	});
+}
+/** One result per test entry; a test the runner reported nothing for counts as failed. */
+function resultsOf(tests, outcomes) {
+	const byId = new Map(outcomes.map((outcome) => [outcome.storyId, outcome]));
+	return tests.map((test) => {
+		const outcome = byId.get(test.id);
+		const error = outcome === void 0 ? "the runner reported no result for this test" : outcome.error;
+		const failed = outcome === void 0 || outcome.status === "failed";
+		return {
+			id: test.id,
+			title: test.title,
+			name: test.name,
+			parentId: test.parentId ?? null,
+			status: failed ? "failed" : "passed",
+			...failed ? { error: redactSecrets(error ?? "test failed").slice(0, ERROR_MAX) } : {},
+			durationMs: outcome?.durationMs ?? 0
+		};
+	});
+}
+/** Write the results; a build that has none and never had any is left untouched. */
+async function keepResults(input, results) {
+	if (results === null && !input.build.testResults) return;
+	await input.builds.setTestResults(input.build.id, results);
+}
+async function reportFailures(input, results, tests) {
+	const failed = results.filter((result) => result.status === "failed");
+	const classified = classifyFailures(tests, failed.map((result) => ({
+		storyId: result.id,
+		viewportName: "test",
+		error: result.error ?? ""
+	})));
+	const sets = {
+		blocking: classified.blocking,
+		flaky: classified.flaky
+	};
+	const fields = {
+		tests: results.length,
+		failed: failed.length,
+		flaky: sets.flaky.size
+	};
+	const level = sets.blocking.size > 0 ? "error" : "info";
+	input.logger?.[level](fields, "storybook tests finished");
+	await emitAttemptLog(input.recordLog, input.logger, level, "storybook tests finished", fields);
+	return sets;
+}
+/** The results a build holds; empty for none or an unreadable value. */
+function parseTestResults(json) {
+	if (!json) return [];
+	try {
+		const parsed = JSON.parse(json);
+		return Array.isArray(parsed) ? parsed.filter((item) => isTestResult(item)) : [];
+	} catch {
+		return [];
+	}
+}
+/** Counts of a build's results. */
+function summarizeTests(results) {
+	const failed = results.filter((result) => result.status === "failed").length;
+	return {
+		total: results.length,
+		passed: results.length - failed,
+		failed
+	};
+}
+function isTestResult(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const record = value;
+	return typeof record["id"] === "string" && typeof record["name"] === "string" && (record["status"] === "passed" || record["status"] === "failed");
+}
+//#endregion
+export { parseTestResults, runProjectTests, summarizeTests };
+
+//# sourceMappingURL=tests.mjs.map

package/dist/capture/tests.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tests.mjs","names":[],"sources":["../../src/capture/tests.ts"],"sourcesContent":["/** Running a project's Storybook 10 `.test()` entries and keeping what they reported (ADR 0004, decision 10). */\nimport type { Logger } from \"pino\";\nimport type { CaptureRunner, CaptureTarget, TestOutcome } from \"../adapters/capture-runner.ts\";\nimport type { BuildModel } from \"../models/build.ts\";\nimport { emitAttemptLog, type AttemptLogRecorder } from \"../models/capture-attempt.ts\";\nimport type { Build } from \"../schema/build.ts\";\nimport type { Project } from \"../schema/project.ts\";\nimport { redactSecrets } from \"../utils/redact.ts\";\nimport { isDisabledStory, type StoryEntry } from \"./adapter.ts\";\nimport { classifyFailures } from \"./failure-sets.ts\";\nimport { renderBudgetMs } from \"./render.ts\";\nimport type { StorybookUrlSource } from \"./storybook-urls.ts\";\nimport { StorybookAdapter } from \"./storybook.ts\";\n\n/** What a build keeps of one `.test()` entry (JSON in `builds.test_results`). */\nexport interface TestResult {\n  /** The test entry's id (`<story id>:<test name slug>`). */\n  id: string;\n  /** Story file title (the component path), as on its index entry. */\n  title: string;\n  /** The test's own name, as written in `story.test(\"...\")`. */\n  name: string;\n  /** The story the test is written under. */\n  parentId: string | null;\n  status: \"passed\" | \"failed\";\n  /** The failure message of a failed test. */\n  error?: string;\n  durationMs: number;\n}\n\n/** Pass and fail counts of a build's tests. */\nexport interface TestSummary {\n  total: number;\n  passed: number;\n  failed: number;\n}\n\n/** Longest failure message kept (rows and logs stay bounded). */\nconst ERROR_MAX = 1000;\n\n/** Test ids by how their failure counts, as {@link runProjectTests} classifies them. */\nexport interface TestRunSets {\n  /** Fail the build, like a failing `play` function. */\n  blocking: Set<string>;\n  /** Tests of a story marked flaky: logged, never blocking. */\n  flaky: Set<string>;\n}\n\n/** Inputs for {@link runProjectTests}. */\nexport interface RunTestsInput {\n  runner: CaptureRunner;\n  builds: BuildModel;\n  build: Build;\n  project: Project;\n  storybookDir: string;\n  /** Every discovered story, so the tests of a skipped story are skipped too. */\n  stories: readonly StoryEntry[];\n  target: CaptureTarget;\n  storybookUrl?: StorybookUrlSource | undefined;\n  logger: Logger | undefined;\n  recordLog?: AttemptLogRecorder | undefined;\n}\n\n/**\n * Run the build's `.test()` entries when the project turned tests on, and store the results on the\n * build. A failing test is a blocking failure of its own id, exactly like a `play` that throws; it\n * takes no screenshot, writes no snapshot and sets no status of its own. Without the setting (or\n * without test entries) nothing runs and nothing is written, except that results left by an\n * earlier run of the same build are cleared.\n */\nexport async function runProjectTests(input: RunTestsInput): Promise<TestRunSets> {\n  const tests = input.project.runTests ? await testsToRun(input) : [];\n  const run = input.runner.runTests?.bind(input.runner);\n  if (tests.length === 0 || !run) return await skipTests(input, tests.length);\n  const results = resultsOf(tests, await execute(input, run, tests));\n  await keepResults(input, results);\n  return await reportFailures(input, results, tests);\n}\n\n/** Nothing to run: warn when tests were wanted but the runner cannot, and clear stale results. */\nasync function skipTests(input: RunTestsInput, wanted: number): Promise<TestRunSets> {\n  if (wanted > 0) {\n    input.logger?.warn(\n      { tests: wanted },\n      \"project runs tests but the capture runner cannot run them; skipped\",\n    );\n  }\n  await keepResults(input, null);\n  return { blocking: new Set(), flaky: new Set() };\n}\n\n/** The test entries to run: those of stories that are not skipped. */\nasync function testsToRun(input: RunTestsInput): Promise<StoryEntry[]> {\n  const skipped = new Set(input.stories.filter((story) => isDisabledStory(story)).map((s) => s.id));\n  const found = await new StorybookAdapter().discoverTests(input.storybookDir);\n  return found.filter(\n    (entry) =>\n      !isDisabledStory(entry) && !(entry.parentId !== undefined && skipped.has(entry.parentId)),\n  );\n}\n\nasync function execute(\n  input: RunTestsInput,\n  run: NonNullable<CaptureRunner[\"runTests\"]>,\n  tests: StoryEntry[],\n): Promise<TestOutcome[]> {\n  const storybookUrl = await input.storybookUrl?.(input.target, {\n    budgetMs: renderBudgetMs(tests.length),\n  });\n  await emitAttemptLog(input.recordLog, input.logger, \"info\", \"running storybook tests\", {\n    tests: tests.length,\n  });\n  return await run({\n    buildId: input.build.id,\n    storybookDir: input.storybookDir,\n    tests,\n    playTimeoutMs: input.project.playTimeoutMs,\n    target: input.target,\n    ...(storybookUrl === undefined ? {} : { storybookUrl }),\n    ...(input.logger ? { logger: input.logger } : {}),\n  });\n}\n\n/** One result per test entry; a test the runner reported nothing for counts as failed. */\nfunction resultsOf(tests: readonly StoryEntry[], outcomes: readonly TestOutcome[]): TestResult[] {\n  const byId = new Map(outcomes.map((outcome) => [outcome.storyId, outcome]));\n  return tests.map((test) => {\n    const outcome = byId.get(test.id);\n    const error =\n      outcome === undefined ? \"the runner reported no result for this test\" : outcome.error;\n    const failed = outcome === undefined || outcome.status === \"failed\";\n    return {\n      id: test.id,\n      title: test.title,\n      name: test.name,\n      parentId: test.parentId ?? null,\n      status: failed ? \"failed\" : \"passed\",\n      ...(failed ? { error: redactSecrets(error ?? \"test failed\").slice(0, ERROR_MAX) } : {}),\n      durationMs: outcome?.durationMs ?? 0,\n    };\n  });\n}\n\n/** Write the results; a build that has none and never had any is left untouched. */\nasync function keepResults(input: RunTestsInput, results: TestResult[] | null): Promise<void> {\n  if (results === null && !input.build.testResults) return;\n  await input.builds.setTestResults(input.build.id, results);\n}\n\nasync function reportFailures(\n  input: RunTestsInput,\n  results: readonly TestResult[],\n  tests: readonly StoryEntry[],\n): Promise<TestRunSets> {\n  const failed = results.filter((result) => result.status === \"failed\");\n  const classified = classifyFailures(\n    tests,\n    failed.map((result) => ({\n      storyId: result.id,\n      viewportName: \"test\",\n      error: result.error ?? \"\",\n    })),\n  );\n  const sets = { blocking: classified.blocking, flaky: classified.flaky };\n  const fields = { tests: results.length, failed: failed.length, flaky: sets.flaky.size };\n  const level = sets.blocking.size > 0 ? \"error\" : \"info\";\n  input.logger?.[level](fields, \"storybook tests finished\");\n  await emitAttemptLog(input.recordLog, input.logger, level, \"storybook tests finished\", fields);\n  return sets;\n}\n\n/** The results a build holds; empty for none or an unreadable value. */\nexport function parseTestResults(json: string | null | undefined): TestResult[] {\n  if (!json) return [];\n  try {\n    const parsed: unknown = JSON.parse(json);\n    return Array.isArray(parsed) ? parsed.filter((item) => isTestResult(item)) : [];\n  } catch {\n    return [];\n  }\n}\n\n/** Counts of a build's results. */\nexport function summarizeTests(results: readonly TestResult[]): TestSummary {\n  const failed = results.filter((result) => result.status === \"failed\").length;\n  return { total: results.length, passed: results.length - failed, failed };\n}\n\nfunction isTestResult(value: unknown): value is TestResult {\n  if (typeof value !== \"object\" || value === null) return false;\n  const record = value as Record<string, unknown>;\n  return (\n    typeof record[\"id\"] === \"string\" &&\n    typeof record[\"name\"] === \"string\" &&\n    (record[\"status\"] === \"passed\" || record[\"status\"] === \"failed\")\n  );\n}\n"],"mappings":"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"}

package/dist/capture/token-chunks.mjs

@@ -0,0 +1,74 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { PER_CAPTURE_BUDGET_MS } from "../utils/storybook-token.mjs";
+import { renderBudgetMs, renderWithTimeout } from "./render.mjs";
+//#region src/capture/token-chunks.ts
+/** Render the pass, minting a fresh signed URL for each slice; results are concatenated. */
+async function renderInSlices(input) {
+	const slices = slicesOf(input);
+	const results = [];
+	for (const slice of slices) {
+		const budgetMs = renderBudgetMs(slice.expected, input.renderTimeoutMs);
+		const storybookUrl = await input.storybookUrl?.(input.browser, { budgetMs });
+		results.push(await renderWithTimeout(input.runner, {
+			...input.request,
+			stories: slice.stories,
+			...storybookUrl === void 0 ? {} : { storybookUrl }
+		}, budgetMs));
+	}
+	return mergeResults(results);
+}
+/** One slice with every story, unless the pass outlasts the lifetime a token can have. */
+function slicesOf(input) {
+	const { stories } = input.request;
+	const counts = stories.map((story) => input.captureCount(story));
+	const expected = counts.reduce((sum, count) => sum + count, 0);
+	const whole = [{
+		stories,
+		expected
+	}];
+	const ttl = input.storybookUrl?.ttlSeconds?.(input.browser, renderBudgetMs(expected, input.renderTimeoutMs));
+	const budgetSeconds = renderBudgetMs(expected, input.renderTimeoutMs) / 1e3;
+	if (ttl === void 0 || input.renderTimeoutMs !== void 0 || budgetSeconds + 300 <= ttl) return whole;
+	return cut(stories, counts, Math.max(50, Math.floor((ttl - 300) * 1e3 / PER_CAPTURE_BUDGET_MS)));
+}
+function cut(stories, counts, limit) {
+	const slices = [];
+	let current = {
+		stories: [],
+		expected: 0
+	};
+	for (const [index, story] of stories.entries()) {
+		const count = counts[index] ?? 0;
+		if (current.stories.length > 0 && current.expected + count > limit) {
+			slices.push(current);
+			current = {
+				stories: [],
+				expected: 0
+			};
+		}
+		current.stories.push(story);
+		current.expected += count;
+	}
+	return [...slices, current];
+}
+function mergeResults(results) {
+	const [only] = results;
+	if (results.length === 1 && only) return only;
+	const environment = results.find((result) => result.environment)?.environment;
+	return {
+		captures: results.flatMap((result) => tagged(result)),
+		failures: results.flatMap((result) => result.failures),
+		...environment ? { environment } : {}
+	};
+}
+/** A slice's captures with the environment that slice reported (a reconnect may differ). */
+function tagged(result) {
+	for (const capture of result.captures) if (result.environment) capture.environment ??= result.environment;
+	return result.captures;
+}
+//#endregion
+export { renderInSlices };
+
+//# sourceMappingURL=token-chunks.mjs.map

package/dist/capture/token-chunks.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-chunks.mjs","names":[],"sources":["../../src/capture/token-chunks.ts"],"sourcesContent":["/**\n * Renders a pass in slices that each fit one signed Storybook URL (ADR 0007, decision 5). A token\n * never lives longer than `MAX_STORYBOOK_URL_TTL` (and a project may set it lower), so a pass whose\n * budget outlasts that is cut into slices of stories and every slice asks the source for a fresh\n * token just before it starts: the render never dies when its token does. A pass that fits one\n * token (the usual case, and every target without a signed URL) is one render call, as before.\n */\nimport type { CaptureTarget, CaptureRunner, RenderResult } from \"../adapters/capture-runner.ts\";\nimport {\n  MIN_CAPTURES_PER_SLICE,\n  PER_CAPTURE_BUDGET_MS,\n  STORYBOOK_URL_TTL_GRACE,\n} from \"../utils/storybook-token.ts\";\nimport type { StoryEntry } from \"./adapter.ts\";\nimport { renderBudgetMs, renderWithTimeout } from \"./render.ts\";\nimport type { RenderRequest } from \"./render.ts\";\nimport type { StorybookUrlSource } from \"./storybook-urls.ts\";\n\n/** What cutting a pass into slices needs of its caller. */\nexport interface SliceInput {\n  runner: CaptureRunner;\n  /** The render call without its `storybookUrl`; its `stories` are the whole pass. */\n  request: RenderRequest;\n  browser: CaptureTarget;\n  storybookUrl: StorybookUrlSource | undefined;\n  /** Captures one story expands to (its viewports and modes). */\n  captureCount: (story: StoryEntry) => number;\n  /** An explicit budget fixes one call's timeout; slices then are not budgeted separately. */\n  renderTimeoutMs: number | undefined;\n}\n\n/** Render the pass, minting a fresh signed URL for each slice; results are concatenated. */\nexport async function renderInSlices(input: SliceInput): Promise<RenderResult> {\n  const slices = slicesOf(input);\n  const results: RenderResult[] = [];\n  for (const slice of slices) {\n    const budgetMs = renderBudgetMs(slice.expected, input.renderTimeoutMs);\n    // oxlint-disable-next-line no-await-in-loop -- each slice needs a token minted just before it\n    const storybookUrl = await input.storybookUrl?.(input.browser, { budgetMs });\n    results.push(\n      // oxlint-disable-next-line no-await-in-loop -- slices render one after another\n      await renderWithTimeout(\n        input.runner,\n        {\n          ...input.request,\n          stories: slice.stories,\n          ...(storybookUrl === undefined ? {} : { storybookUrl }),\n        },\n        budgetMs,\n      ),\n    );\n  }\n  return mergeResults(results);\n}\n\ninterface Slice {\n  stories: StoryEntry[];\n  expected: number;\n}\n\n/** One slice with every story, unless the pass outlasts the lifetime a token can have. */\nfunction slicesOf(input: SliceInput): Slice[] {\n  const { stories } = input.request;\n  const counts = stories.map((story) => input.captureCount(story));\n  const expected = counts.reduce((sum, count) => sum + count, 0);\n  const whole: Slice[] = [{ stories, expected }];\n  const ttl = input.storybookUrl?.ttlSeconds?.(\n    input.browser,\n    renderBudgetMs(expected, input.renderTimeoutMs),\n  );\n  const budgetSeconds = renderBudgetMs(expected, input.renderTimeoutMs) / 1000;\n  if (\n    ttl === undefined ||\n    input.renderTimeoutMs !== undefined ||\n    budgetSeconds + STORYBOOK_URL_TTL_GRACE <= ttl\n  ) {\n    return whole;\n  }\n  const limit = Math.max(\n    MIN_CAPTURES_PER_SLICE,\n    Math.floor(((ttl - STORYBOOK_URL_TTL_GRACE) * 1000) / PER_CAPTURE_BUDGET_MS),\n  );\n  return cut(stories, counts, limit);\n}\n\nfunction cut(stories: StoryEntry[], counts: number[], limit: number): Slice[] {\n  const slices: Slice[] = [];\n  let current: Slice = { stories: [], expected: 0 };\n  for (const [index, story] of stories.entries()) {\n    const count = counts[index] ?? 0;\n    if (current.stories.length > 0 && current.expected + count > limit) {\n      slices.push(current);\n      current = { stories: [], expected: 0 };\n    }\n    current.stories.push(story);\n    current.expected += count;\n  }\n  return [...slices, current];\n}\n\nfunction mergeResults(results: RenderResult[]): RenderResult {\n  const [only] = results;\n  if (results.length === 1 && only) {\n    return only;\n  }\n  const environment = results.find((result) => result.environment)?.environment;\n  return {\n    captures: results.flatMap((result) => tagged(result)),\n    failures: results.flatMap((result) => result.failures),\n    ...(environment ? { environment } : {}),\n  };\n}\n\n/** A slice's captures with the environment that slice reported (a reconnect may differ). */\nfunction tagged(result: RenderResult): RenderResult[\"captures\"] {\n  for (const capture of result.captures) {\n    if (result.environment) {\n      capture.environment ??= result.environment;\n    }\n  }\n  return result.captures;\n}\n"],"mappings":";;;;;;;AAgCA,eAAsB,eAAe,OAA0C;CAC7E,MAAM,SAAS,SAAS,KAAK;CAC7B,MAAM,UAA0B,CAAC;CACjC,KAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,WAAW,eAAe,MAAM,UAAU,MAAM,eAAe;EAErE,MAAM,eAAe,MAAM,MAAM,eAAe,MAAM,SAAS,EAAE,SAAS,CAAC;EAC3E,QAAQ,KAEN,MAAM,kBACJ,MAAM,QACN;GACE,GAAG,MAAM;GACT,SAAS,MAAM;GACf,GAAI,iBAAiB,KAAA,IAAY,CAAC,IAAI,EAAE,aAAa;EACvD,GACA,QACF,CACF;CACF;CACA,OAAO,aAAa,OAAO;AAC7B;;AAQA,SAAS,SAAS,OAA4B;CAC5C,MAAM,EAAE,YAAY,MAAM;CAC1B,MAAM,SAAS,QAAQ,KAAK,UAAU,MAAM,aAAa,KAAK,CAAC;CAC/D,MAAM,WAAW,OAAO,QAAQ,KAAK,UAAU,MAAM,OAAO,CAAC;CAC7D,MAAM,QAAiB,CAAC;EAAE;EAAS;CAAS,CAAC;CAC7C,MAAM,MAAM,MAAM,cAAc,aAC9B,MAAM,SACN,eAAe,UAAU,MAAM,eAAe,CAChD;CACA,MAAM,gBAAgB,eAAe,UAAU,MAAM,eAAe,IAAI;CACxE,IACE,QAAQ,KAAA,KACR,MAAM,oBAAoB,KAAA,KAC1B,gBAAA,OAA2C,KAE3C,OAAO;CAMT,OAAO,IAAI,SAAS,QAJN,KAAK,IAAA,IAEjB,KAAK,OAAQ,MAAA,OAAiC,MAAQ,qBAAqB,CAE7C,CAAC;AACnC;AAEA,SAAS,IAAI,SAAuB,QAAkB,OAAwB;CAC5E,MAAM,SAAkB,CAAC;CACzB,IAAI,UAAiB;EAAE,SAAS,CAAC;EAAG,UAAU;CAAE;CAChD,KAAK,MAAM,CAAC,OAAO,UAAU,QAAQ,QAAQ,GAAG;EAC9C,MAAM,QAAQ,OAAO,UAAU;EAC/B,IAAI,QAAQ,QAAQ,SAAS,KAAK,QAAQ,WAAW,QAAQ,OAAO;GAClE,OAAO,KAAK,OAAO;GACnB,UAAU;IAAE,SAAS,CAAC;IAAG,UAAU;GAAE;EACvC;EACA,QAAQ,QAAQ,KAAK,KAAK;EAC1B,QAAQ,YAAY;CACtB;CACA,OAAO,CAAC,GAAG,QAAQ,OAAO;AAC5B;AAEA,SAAS,aAAa,SAAuC;CAC3D,MAAM,CAAC,QAAQ;CACf,IAAI,QAAQ,WAAW,KAAK,MAC1B,OAAO;CAET,MAAM,cAAc,QAAQ,MAAM,WAAW,OAAO,WAAW,CAAC,EAAE;CAClE,OAAO;EACL,UAAU,QAAQ,SAAS,WAAW,OAAO,MAAM,CAAC;EACpD,UAAU,QAAQ,SAAS,WAAW,OAAO,QAAQ;EACrD,GAAI,cAAc,EAAE,YAAY,IAAI,CAAC;CACvC;AACF;;AAGA,SAAS,OAAO,QAAgD;CAC9D,KAAK,MAAM,WAAW,OAAO,UAC3B,IAAI,OAAO,aACT,QAAQ,gBAAgB,OAAO;CAGnC,OAAO,OAAO;AAChB"}

package/dist/capture.d.mts

@@ -1,14 +1,67 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { DEFAULT_VIEWPORTS, StoryEntry, StoryParameters, StorySourceAdapter, StoryViewportConfig, StoryViewportDefinition, Viewport, isDisabledStory, isFlakyStory } from "./capture/adapter.mjs";
-import { PollableCaptureQueue, PollableJob } from "./adapter/capture-queue.mjs";
+import { DEFAULT_VIEWPORTS, ModeDefinition, ModeMap, ModeViewportValue, StoryEntry, StoryParameters, StorySourceAdapter, StoryViewportConfig, StoryViewportDefinition, Viewport, isDisabledStory, isFlakyStory } from "./capture/adapter.mjs";
+import { LeaseRenewal, PollableCaptureQueue, PollableJob } from "./adapter/capture-queue.mjs";
+import { MAX_BROWSERS, assertBrowserCount, assertSupportedBrowsers, listTargets, parseBrowsers, primaryTargetOf, refusalFor, resolveBrowsers } from "./capture/browsers.mjs";
+import { NO_ORIGIN_REASON, NO_SECRET_REASON, TargetPrerequisites, offeredTargets } from "./capture/targets.mjs";
+import { StorybookUrlSource, storybookUrlSource } from "./capture/storybook-urls.mjs";
+import { MAX_MODES_PER_STORY, buildGlobalsParam, filterModes, modeSlug, parseModesAllowlist } from "./capture/modes.mjs";
+import { TestResult, TestSummary, parseTestResults, summarizeTests } from "./capture/tests.mjs";
+import { JobLease, ProgressLease } from "./capture/job-lease.mjs";
 import { CaptureContext, persistCapture } from "./capture/pipeline.mjs";
+import { DEFAULT_MAX_INLINE_UNZIP_SIZE, DEFAULT_MAX_UNZIPPED_BYTES, DEFAULT_MAX_ZIP_ENTRIES, ExtractionLimits, FILE_BY_FILE_HINT, PublishLimits, ZipLimitError, extractionLimitsOf, publishRoute, resolvePublishLimits } from "./capture/publish/limits.mjs";
 import { CaptureAttemptRef, CaptureJobInput, CaptureJobOptions, executeCaptureJob } from "./capture/orchestrator.mjs";
-import { REDIFFABLE_BUILD_STATUSES, RediffDeps, RediffResult, rediffBuild } from "./capture/rediff.mjs";
+import { SCRATCH_DIRNAME, SCRATCH_MAX_AGE_MS, ScratchSweepOptions, buildScratchDir, removeBuildScratch, removeJobScratch, sweepOrphanedScratch } from "./capture/scratch.mjs";
+import { BoundingBox, SIZING_DEFAULTS, ScreenshotPlan, SizingOptions, getScreenshotPlan, resolveViewports } from "./capture/sizing.mjs";
+import { EnvironmentChange, Fingerprint, buildFingerprint, changedFields, fingerprintHash, parseFingerprint } from "./capture/fingerprint.mjs";
+import { axeInjectionScript, loadAxeSource } from "./capture/a11y/axe-source.mjs";
+import { MAX_REPORTED_VIOLATIONS, SlimViolation, mapAxeViolations } from "./capture/a11y/map.mjs";
+import { A11Y_ROOT_SELECTOR, A11yRunPlan, resolveA11yRun } from "./capture/a11y/options.mjs";
+import { inPageReadA11yParameters, inPageRunAxe } from "./capture/a11y/in-page.mjs";
+import { BuildStateDeps, BuildStatePublisher, SkipReason, StateTarget } from "./capture/build-state/types.mjs";
+import { deliverBuildState, loadBuild, stateTargets, writeTo } from "./capture/build-state/deliver.mjs";
+import { ACTIVE_POLL_MS, ACTIVE_WINDOW_MS, CANCEL_CHECK_MS, DEFAULT_CADENCE, IDLE_POLL_MS, POLL_JITTER, PollCadence, nextPollDelay } from "./capture/db-queue/cadence.mjs";
 import { CaptureDispatchJob, DispatchDeps, createDispatchJob } from "./capture/dispatch.mjs";
-import { INTERRUPTED_ERROR, RecoveryDeps, RecoveryResult, recoverStuckCaptures } from "./capture/recovery.mjs";
-import { InMemoryCaptureQueue, InMemoryCaptureQueueOptions } from "./capture/queue.mjs";
+import { CaptureHandlerOptions, captureDispatchDeps, createCaptureHandler } from "./capture/consumer/capture-handler.mjs";
+import { ConsumerMetrics, DEFAULT_SAMPLE_MS, JobFinishedEvent, JobOutcome, QueueSample, sampleQueue } from "./capture/consumer/metrics.mjs";
+import { DEFAULT_BACKOFF_MS, DEFAULT_MAX_RETRIES, DEFAULT_WAIT_TIME_SECONDS, MAX_BACKOFF_MS, RetryConfig, backoffDelayMs, isFinalAttempt } from "./capture/consumer/retry.mjs";
+import { CaptureConsumer, CaptureConsumerOptions, ConsumerConfig, ConsumerJob, JobHandlers, JobRunContext, KindHandler } from "./capture/consumer/types.mjs";
+import { DEFAULT_LEASE_MS, DEFAULT_RETRIES, DatabaseCaptureQueue, DatabaseCaptureQueueOptions, DatabaseJob, QueueJobInput } from "./capture/db-queue/types.mjs";
+import { NOTIFY_BACKOFF, NOTIFY_MAX_ATTEMPTS, NotifyFailure, NotifyHandlerOptions, NotifyJobQueue, createNotifyEnqueuer, createNotifyHandler, notifyExhausted } from "./capture/build-state/notify-job.mjs";
+import { BuildStatePublisherOptions, PAUSED_MESSAGE, createBuildStatePublisher } from "./capture/build-state/publisher.mjs";
+import { requestOpenBuildStates } from "./capture/build-state/resume.mjs";
+import "./capture/build-state/index.mjs";
+import { REDIFFABLE_BUILD_STATUSES, RediffDeps, RediffResult, rediffBuild } from "./capture/rediff.mjs";
+import { CrashFailureOutcome, failCrashedCapture } from "./capture/crash-failure.mjs";
+import { LEASE_EXHAUSTED_ERROR } from "./capture/db-queue/claim.mjs";
+import { MAX_NACK_DELAY_MS } from "./capture/db-queue/poll.mjs";
+import { DATABASE_QUEUE_METADATA, createDatabaseCaptureQueue } from "./capture/db-queue/index.mjs";
+import { JobLeaseKeeper, LeaseEnd, LeaseKeeperOptions, RENEW_THROTTLE_MS, keepJobLease } from "./capture/db-queue/keeper.mjs";
+import { PollLoop, PollLoopOptions, startPollLoop } from "./capture/db-queue/poll-loop.mjs";
+import { MIN_BLOCKING_POLL_MS, idleDelayMs, isFastEmptyPoll } from "./capture/consumer/idle.mjs";
+import { createCaptureConsumer } from "./capture/consumer/index.mjs";
+import { ChildMessage, ParentMessage } from "./capture/forked/protocol.mjs";
+import { CaptureChildOptions, ChildHost, runCaptureChild } from "./capture/forked/child.mjs";
 import { STORYBOOK_BUILTIN_VIEWPORTS, StorybookAdapter, mergeParameters, resolveStoryViewports } from "./capture/storybook.mjs";
 import { extractStorybookToScratch, persistStorybookStatics } from "./capture/statics.mjs";
-import { BoundingBox, SIZING_DEFAULTS, ScreenshotPlan, SizingOptions, getScreenshotPlan, resolveViewports } from "./capture/sizing.mjs";
-export { type BoundingBox, type CaptureAttemptRef, type CaptureContext, type CaptureDispatchJob, type CaptureJobInput, type CaptureJobOptions, DEFAULT_VIEWPORTS, type DispatchDeps, INTERRUPTED_ERROR, InMemoryCaptureQueue, type InMemoryCaptureQueueOptions, type PollableCaptureQueue, type PollableJob, REDIFFABLE_BUILD_STATUSES, type RecoveryDeps, type RecoveryResult, type RediffDeps, type RediffResult, SIZING_DEFAULTS, STORYBOOK_BUILTIN_VIEWPORTS, type ScreenshotPlan, type SizingOptions, type StoryEntry, type StoryParameters, type StorySourceAdapter, type StoryViewportConfig, type StoryViewportDefinition, StorybookAdapter, type Viewport, createDispatchJob, executeCaptureJob, extractStorybookToScratch, getScreenshotPlan, isDisabledStory, isFlakyStory, mergeParameters, persistCapture, persistStorybookStatics, recoverStuckCaptures, rediffBuild, resolveViewports as resolveCaptureViewports, resolveStoryViewports };
+import { AfterPublishContext, AfterPublishHook, PublishCompleter, PublishCompleterOptions, PublishOutcome, createPublishCompleter } from "./capture/publish/complete.mjs";
+import { PublishHandlerOptions, createPublishHandler } from "./capture/publish/handler.mjs";
+import { PublishFacts, publishVerdict } from "./capture/publish/accept.mjs";
+import { publishingOf } from "./capture/publish/published.mjs";
+import { ExtractionResult, extractZipStream } from "./capture/publish/extract.mjs";
+import { PUBLISH_SCRATCH_ID, PublishZipOptions, publishStoredZip } from "./capture/publish/run.mjs";
+import "./capture/publish/index.mjs";
+import { Catalog, CatalogComponent, CatalogEntry } from "./capture/catalog/types.mjs";
+import { CatalogDeps, catalogueBuild, readCatalog } from "./capture/catalog/catalogue.mjs";
+import { CatalogLoader, CatalogLoaderOptions, DEFAULT_CATALOG_CACHE_SIZE, createCatalogLoader } from "./capture/catalog/load.mjs";
+import { createCatalogHook } from "./capture/catalog/hook.mjs";
+import { EntryChanges, diffEntries, groupComponents, hashEntries, toBuildComponent } from "./capture/catalog/components.mjs";
+import { parseStorybookIndex, parseStorybookIndexText } from "./capture/catalog/parse.mjs";
+import { readPublishedFile } from "./capture/catalog/read.mjs";
+import { ComponentBuildRow, ComponentChange, catalogPresence, componentBuildHistory } from "./capture/catalog/history.mjs";
+import "./capture/catalog/index.mjs";
+import { ChildProcessHandle, ParentPort } from "./capture/forked/channel.mjs";
+import { ForkedCaptureHandler, ForkedCaptureOptions, createForkedCaptureHandler } from "./capture/forked/forked-capture.mjs";
+import { CAPTURE_RETRIES_ENV, CAPTURE_SHARD_SIZE_ENV, CAPTURE_WORKER_ROLE, ForkOptions, canForkCaptureChild, forkCaptureChild } from "./capture/forked/fork.mjs";
+import { FORK_MIN_CPUS, FORK_MIN_MEMORY_BYTES, ForkDecision, ForkHost, decideCaptureProcess } from "./capture/forked/decision.mjs";
+export { A11Y_ROOT_SELECTOR, type A11yRunPlan, ACTIVE_POLL_MS, ACTIVE_WINDOW_MS, type AfterPublishContext, type AfterPublishHook, type BoundingBox, type BuildStateDeps, type BuildStatePublisher, type BuildStatePublisherOptions, CANCEL_CHECK_MS, CAPTURE_RETRIES_ENV, CAPTURE_SHARD_SIZE_ENV, CAPTURE_WORKER_ROLE, type CaptureAttemptRef, type CaptureChildOptions, type CaptureConsumer, type CaptureConsumerOptions, type CaptureContext, type CaptureDispatchJob, type CaptureHandlerOptions, type CaptureJobInput, type CaptureJobOptions, type Catalog, type CatalogComponent, type CatalogDeps, type CatalogEntry, type CatalogLoader, type CatalogLoaderOptions, type ChildHost, type ChildMessage, type ChildProcessHandle, type ComponentBuildRow, type ComponentChange, type ConsumerConfig, type ConsumerJob, type ConsumerMetrics, type CrashFailureOutcome, DATABASE_QUEUE_METADATA, DEFAULT_BACKOFF_MS, DEFAULT_CADENCE, DEFAULT_CATALOG_CACHE_SIZE, DEFAULT_LEASE_MS, DEFAULT_MAX_INLINE_UNZIP_SIZE, DEFAULT_MAX_RETRIES, DEFAULT_MAX_UNZIPPED_BYTES, DEFAULT_MAX_ZIP_ENTRIES, DEFAULT_RETRIES, DEFAULT_SAMPLE_MS, DEFAULT_VIEWPORTS, DEFAULT_WAIT_TIME_SECONDS, type DatabaseCaptureQueue, type DatabaseCaptureQueueOptions, type DatabaseJob, type DispatchDeps, type EntryChanges, type EnvironmentChange, type ExtractionLimits, type ExtractionResult, FILE_BY_FILE_HINT, FORK_MIN_CPUS, FORK_MIN_MEMORY_BYTES, type Fingerprint, type ForkDecision, type ForkHost, type ForkOptions, type ForkedCaptureHandler, type ForkedCaptureOptions, IDLE_POLL_MS, type JobFinishedEvent, type JobHandlers, type JobLease, type JobLeaseKeeper, type JobOutcome, type JobRunContext, type KindHandler, LEASE_EXHAUSTED_ERROR, type LeaseEnd, type LeaseKeeperOptions, type LeaseRenewal, MAX_BACKOFF_MS, MAX_BROWSERS, MAX_MODES_PER_STORY, MAX_NACK_DELAY_MS, MAX_REPORTED_VIOLATIONS, MIN_BLOCKING_POLL_MS, type ModeDefinition, type ModeMap, type ModeViewportValue, NOTIFY_BACKOFF, NOTIFY_MAX_ATTEMPTS, NO_ORIGIN_REASON, NO_SECRET_REASON, type NotifyFailure, type NotifyHandlerOptions, type NotifyJobQueue, PAUSED_MESSAGE, POLL_JITTER, PUBLISH_SCRATCH_ID, type ParentMessage, type ParentPort, type PollCadence, type PollLoop, type PollLoopOptions, type PollableCaptureQueue, type PollableJob, ProgressLease, type PublishCompleter, type PublishCompleterOptions, type PublishFacts, type PublishHandlerOptions, type PublishLimits, type PublishOutcome, type PublishZipOptions, type QueueJobInput, type QueueSample, REDIFFABLE_BUILD_STATUSES, RENEW_THROTTLE_MS, type RediffDeps, type RediffResult, type RetryConfig, SCRATCH_DIRNAME, SCRATCH_MAX_AGE_MS, SIZING_DEFAULTS, STORYBOOK_BUILTIN_VIEWPORTS, type ScratchSweepOptions, type ScreenshotPlan, type SizingOptions, type SkipReason, type SlimViolation, type StateTarget, type StoryEntry, type StoryParameters, type StorySourceAdapter, type StoryViewportConfig, type StoryViewportDefinition, StorybookAdapter, type StorybookUrlSource, type TargetPrerequisites, type TestResult, type TestSummary, type Viewport, ZipLimitError, assertBrowserCount, assertSupportedBrowsers, axeInjectionScript, backoffDelayMs, buildFingerprint, buildGlobalsParam, buildScratchDir, canForkCaptureChild, captureDispatchDeps, catalogPresence, catalogueBuild, changedFields, componentBuildHistory, createBuildStatePublisher, createCaptureConsumer, createCaptureHandler, createCatalogHook, createCatalogLoader, createDatabaseCaptureQueue, createDispatchJob, createForkedCaptureHandler, createNotifyEnqueuer, createNotifyHandler, createPublishCompleter, createPublishHandler, decideCaptureProcess, deliverBuildState, diffEntries, executeCaptureJob, extractStorybookToScratch, extractZipStream, extractionLimitsOf, failCrashedCapture, filterModes, fingerprintHash, forkCaptureChild, getScreenshotPlan, groupComponents, hashEntries, idleDelayMs, inPageReadA11yParameters, inPageRunAxe, isDisabledStory, isFastEmptyPoll, isFinalAttempt, isFlakyStory, keepJobLease, listTargets, loadAxeSource, loadBuild, mapAxeViolations, mergeParameters, modeSlug, nextPollDelay, notifyExhausted, offeredTargets, parseBrowsers, parseFingerprint, parseModesAllowlist, parseStorybookIndex, parseStorybookIndexText, parseTestResults, persistCapture, persistStorybookStatics, primaryTargetOf, publishRoute, publishStoredZip, publishVerdict, publishingOf, readCatalog, readPublishedFile, rediffBuild, refusalFor, removeBuildScratch, removeJobScratch, requestOpenBuildStates, resolveA11yRun, resolveBrowsers, resolveViewports as resolveCaptureViewports, resolvePublishLimits, resolveStoryViewports, runCaptureChild, sampleQueue, startPollLoop, stateTargets, storybookUrlSource, summarizeTests, sweepOrphanedScratch, toBuildComponent, writeTo };

package/dist/capture.mjs

@@ -1,14 +1,59 @@
 import "node:path";
 import "node:url";
 import.meta.url;
+import { MAX_BROWSERS, assertBrowserCount, assertSupportedBrowsers, listTargets, parseBrowsers, primaryTargetOf, refusalFor, resolveBrowsers } from "./capture/browsers.mjs";
+import { NO_ORIGIN_REASON, NO_SECRET_REASON, offeredTargets } from "./capture/targets.mjs";
+import { storybookUrlSource } from "./capture/storybook-urls.mjs";
+import { MAX_MODES_PER_STORY, buildGlobalsParam, filterModes, modeSlug, parseModesAllowlist } from "./capture/modes.mjs";
 import { DEFAULT_VIEWPORTS, isDisabledStory, isFlakyStory } from "./capture/adapter.mjs";
 import { STORYBOOK_BUILTIN_VIEWPORTS, StorybookAdapter, mergeParameters, resolveStoryViewports } from "./capture/storybook.mjs";
+import { parseTestResults, summarizeTests } from "./capture/tests.mjs";
 import { SIZING_DEFAULTS, getScreenshotPlan, resolveViewports } from "./capture/sizing.mjs";
+import { buildFingerprint, changedFields, fingerprintHash, parseFingerprint } from "./capture/fingerprint.mjs";
 import { persistCapture } from "./capture/pipeline.mjs";
+import { SCRATCH_DIRNAME, SCRATCH_MAX_AGE_MS, buildScratchDir, removeBuildScratch, removeJobScratch, sweepOrphanedScratch } from "./capture/scratch.mjs";
+import { DEFAULT_MAX_INLINE_UNZIP_SIZE, DEFAULT_MAX_UNZIPPED_BYTES, DEFAULT_MAX_ZIP_ENTRIES, FILE_BY_FILE_HINT, ZipLimitError, extractionLimitsOf, publishRoute, resolvePublishLimits } from "./capture/publish/limits.mjs";
+import { extractZipStream } from "./capture/publish/extract.mjs";
 import { extractStorybookToScratch, persistStorybookStatics } from "./capture/statics.mjs";
 import { executeCaptureJob } from "./capture/orchestrator.mjs";
+import { axeInjectionScript, loadAxeSource } from "./capture/a11y/axe-source.mjs";
+import { inPageReadA11yParameters, inPageRunAxe } from "./capture/a11y/in-page.mjs";
+import { MAX_REPORTED_VIOLATIONS, mapAxeViolations } from "./capture/a11y/map.mjs";
+import { A11Y_ROOT_SELECTOR, resolveA11yRun } from "./capture/a11y/options.mjs";
+import { publishingOf } from "./capture/publish/published.mjs";
+import { deliverBuildState, loadBuild, stateTargets, writeTo } from "./capture/build-state/deliver.mjs";
+import { DEFAULT_BACKOFF_MS, DEFAULT_MAX_RETRIES, DEFAULT_WAIT_TIME_SECONDS, MAX_BACKOFF_MS, backoffDelayMs, isFinalAttempt } from "./capture/consumer/retry.mjs";
+import { NOTIFY_BACKOFF, NOTIFY_MAX_ATTEMPTS, createNotifyEnqueuer, createNotifyHandler, notifyExhausted } from "./capture/build-state/notify-job.mjs";
+import { PAUSED_MESSAGE, createBuildStatePublisher } from "./capture/build-state/publisher.mjs";
+import { requestOpenBuildStates } from "./capture/build-state/resume.mjs";
 import { REDIFFABLE_BUILD_STATUSES, rediffBuild } from "./capture/rediff.mjs";
-import { INTERRUPTED_ERROR, recoverStuckCaptures } from "./capture/recovery.mjs";
-import { InMemoryCaptureQueue } from "./capture/queue.mjs";
+import { failCrashedCapture } from "./capture/crash-failure.mjs";
+import { ProgressLease } from "./capture/job-lease.mjs";
+import { LEASE_EXHAUSTED_ERROR } from "./capture/db-queue/claim.mjs";
+import { MAX_NACK_DELAY_MS } from "./capture/db-queue/poll.mjs";
+import { DEFAULT_LEASE_MS, DEFAULT_RETRIES } from "./capture/db-queue/types.mjs";
+import { DATABASE_QUEUE_METADATA, createDatabaseCaptureQueue } from "./capture/db-queue/index.mjs";
+import { ACTIVE_POLL_MS, ACTIVE_WINDOW_MS, CANCEL_CHECK_MS, DEFAULT_CADENCE, IDLE_POLL_MS, POLL_JITTER, nextPollDelay } from "./capture/db-queue/cadence.mjs";
+import { RENEW_THROTTLE_MS, keepJobLease } from "./capture/db-queue/keeper.mjs";
+import { startPollLoop } from "./capture/db-queue/poll-loop.mjs";
 import { createDispatchJob } from "./capture/dispatch.mjs";
-export { DEFAULT_VIEWPORTS, INTERRUPTED_ERROR, InMemoryCaptureQueue, REDIFFABLE_BUILD_STATUSES, SIZING_DEFAULTS, STORYBOOK_BUILTIN_VIEWPORTS, StorybookAdapter, createDispatchJob, executeCaptureJob, extractStorybookToScratch, getScreenshotPlan, isDisabledStory, isFlakyStory, mergeParameters, persistCapture, persistStorybookStatics, recoverStuckCaptures, rediffBuild, resolveViewports as resolveCaptureViewports, resolveStoryViewports };
+import { captureDispatchDeps, createCaptureHandler } from "./capture/consumer/capture-handler.mjs";
+import { MIN_BLOCKING_POLL_MS, idleDelayMs, isFastEmptyPoll } from "./capture/consumer/idle.mjs";
+import { DEFAULT_SAMPLE_MS, sampleQueue } from "./capture/consumer/metrics.mjs";
+import { createCaptureConsumer } from "./capture/consumer/index.mjs";
+import { CAPTURE_RETRIES_ENV, CAPTURE_SHARD_SIZE_ENV, CAPTURE_WORKER_ROLE, canForkCaptureChild, forkCaptureChild } from "./capture/forked/fork.mjs";
+import { runCaptureChild } from "./capture/forked/child.mjs";
+import { PUBLISH_SCRATCH_ID, publishStoredZip } from "./capture/publish/run.mjs";
+import { createPublishHandler } from "./capture/publish/handler.mjs";
+import { publishVerdict } from "./capture/publish/accept.mjs";
+import { createPublishCompleter } from "./capture/publish/complete.mjs";
+import { createCatalogHook } from "./capture/catalog/hook.mjs";
+import { diffEntries, groupComponents, hashEntries, toBuildComponent } from "./capture/catalog/components.mjs";
+import { parseStorybookIndex, parseStorybookIndexText } from "./capture/catalog/parse.mjs";
+import { readPublishedFile } from "./capture/catalog/read.mjs";
+import { catalogueBuild, readCatalog } from "./capture/catalog/catalogue.mjs";
+import { DEFAULT_CATALOG_CACHE_SIZE, createCatalogLoader } from "./capture/catalog/load.mjs";
+import { catalogPresence, componentBuildHistory } from "./capture/catalog/history.mjs";
+import { createForkedCaptureHandler } from "./capture/forked/forked-capture.mjs";
+import { FORK_MIN_CPUS, FORK_MIN_MEMORY_BYTES, decideCaptureProcess } from "./capture/forked/decision.mjs";
+export { A11Y_ROOT_SELECTOR, ACTIVE_POLL_MS, ACTIVE_WINDOW_MS, CANCEL_CHECK_MS, CAPTURE_RETRIES_ENV, CAPTURE_SHARD_SIZE_ENV, CAPTURE_WORKER_ROLE, DATABASE_QUEUE_METADATA, DEFAULT_BACKOFF_MS, DEFAULT_CADENCE, DEFAULT_CATALOG_CACHE_SIZE, DEFAULT_LEASE_MS, DEFAULT_MAX_INLINE_UNZIP_SIZE, DEFAULT_MAX_RETRIES, DEFAULT_MAX_UNZIPPED_BYTES, DEFAULT_MAX_ZIP_ENTRIES, DEFAULT_RETRIES, DEFAULT_SAMPLE_MS, DEFAULT_VIEWPORTS, DEFAULT_WAIT_TIME_SECONDS, FILE_BY_FILE_HINT, FORK_MIN_CPUS, FORK_MIN_MEMORY_BYTES, IDLE_POLL_MS, LEASE_EXHAUSTED_ERROR, MAX_BACKOFF_MS, MAX_BROWSERS, MAX_MODES_PER_STORY, MAX_NACK_DELAY_MS, MAX_REPORTED_VIOLATIONS, MIN_BLOCKING_POLL_MS, NOTIFY_BACKOFF, NOTIFY_MAX_ATTEMPTS, NO_ORIGIN_REASON, NO_SECRET_REASON, PAUSED_MESSAGE, POLL_JITTER, PUBLISH_SCRATCH_ID, ProgressLease, REDIFFABLE_BUILD_STATUSES, RENEW_THROTTLE_MS, SCRATCH_DIRNAME, SCRATCH_MAX_AGE_MS, SIZING_DEFAULTS, STORYBOOK_BUILTIN_VIEWPORTS, StorybookAdapter, ZipLimitError, assertBrowserCount, assertSupportedBrowsers, axeInjectionScript, backoffDelayMs, buildFingerprint, buildGlobalsParam, buildScratchDir, canForkCaptureChild, captureDispatchDeps, catalogPresence, catalogueBuild, changedFields, componentBuildHistory, createBuildStatePublisher, createCaptureConsumer, createCaptureHandler, createCatalogHook, createCatalogLoader, createDatabaseCaptureQueue, createDispatchJob, createForkedCaptureHandler, createNotifyEnqueuer, createNotifyHandler, createPublishCompleter, createPublishHandler, decideCaptureProcess, deliverBuildState, diffEntries, executeCaptureJob, extractStorybookToScratch, extractZipStream, extractionLimitsOf, failCrashedCapture, filterModes, fingerprintHash, forkCaptureChild, getScreenshotPlan, groupComponents, hashEntries, idleDelayMs, inPageReadA11yParameters, inPageRunAxe, isDisabledStory, isFastEmptyPoll, isFinalAttempt, isFlakyStory, keepJobLease, listTargets, loadAxeSource, loadBuild, mapAxeViolations, mergeParameters, modeSlug, nextPollDelay, notifyExhausted, offeredTargets, parseBrowsers, parseFingerprint, parseModesAllowlist, parseStorybookIndex, parseStorybookIndexText, parseTestResults, persistCapture, persistStorybookStatics, primaryTargetOf, publishRoute, publishStoredZip, publishVerdict, publishingOf, readCatalog, readPublishedFile, rediffBuild, refusalFor, removeBuildScratch, removeJobScratch, requestOpenBuildStates, resolveA11yRun, resolveBrowsers, resolveViewports as resolveCaptureViewports, resolvePublishLimits, resolveStoryViewports, runCaptureChild, sampleQueue, startPollLoop, stateTargets, storybookUrlSource, summarizeTests, sweepOrphanedScratch, toBuildComponent, writeTo };

package/dist/config.d.mts

@@ -2,13 +2,15 @@ import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { CaptureRunner } from "./adapter/capture-runner.mjs";
 import { DatabaseAdapter } from "./adapter/database.mjs";
+import { DesignProvider } from "./adapter/design.mjs";
 import { EmailSender } from "./adapter/email-sender.mjs";
-import { GitHostProvider } from "./adapter/git-host.mjs";
 import { NotifierProvider } from "./adapters/notifier/provider.mjs";
 import { StorageAdapter } from "./adapter/storage.mjs";
+import { Ai } from "./ai.mjs";
 import { Auth } from "./auth.mjs";
+import { DEFAULT_SCRATCH_DIR, resolveShelfOptions } from "./options.mjs";
+import { ALLOW_SERVERLESS_ENV, assertServerless, isServerlessHost } from "./serverless.mjs";
 import { AdapterCategory } from "./adapter/metadata.mjs";
-import { CaptureQueue } from "./adapter/capture-queue.mjs";
 import { z } from "zod";
 import { Logger } from "pino";
 //#region src/config.d.ts
@@ -127,7 +129,10 @@ interface ShelfConfig {
    * helper document; falls back to the request origin when unset.
    */
   publicBaseUrl?: string;
-  captureConcurrency?: number;
+  /**
+   * Working directory for capture and inline statics extraction. Defaults to
+   * `<os.tmpdir()>/storyshelf`; publishing and capture extract there.
+   */
   scratchDir?: string;
   purgeTtlDays?: number;
   /** Branch baseline TTL, days; null disables branch GC (default 30). */
@@ -141,14 +146,24 @@ interface ShelfConfig {
    */
   serverTiming?: boolean;
   /**
-   * Max zip size (bytes) eligible for inline statics extraction at upload.
-   * Unset (or 0) disables inline extraction — statics land via capture.
+   * Largest zip (bytes) extracted inline in the upload request; a larger zip is published by a
+   * `publish` job (or refused with 413 on a host that runs no consumer). The count is taken
+   * while the upload streams, never from `Content-Length`. Default 50 MB; `0` sends every zip to
+   * a `publish` job.
    */
   maxInlineUnzipSize?: number;
+  /** Most entries an uploaded Storybook zip may hold (default 50 000); more fails the publish. */
+  maxZipEntries?: number;
+  /**
+   * Most uncompressed bytes an uploaded Storybook zip may expand to (default 2 GiB), counted while
+   * extracting; more fails the publish. The compressed size is no bound on its own.
+   */
+  maxUnzippedBytes?: number;
   viewports?: ShelfViewport[];
   adapters?: Record<string, AdapterSnapshot>;
-  notifications?: NotificationsConfig;
 }
+/** Zod schema validating `notifications.config`. */
+declare const notificationsConfigSchema: z.ZodType<NotificationsConfig>;
 /** Zod schema validating the shelf-level configuration. */
 declare const shelfConfigSchema: z.ZodType<ShelfConfig>;
 /** Zod schema validating the UI branding configuration. */
@@ -167,16 +182,110 @@ declare function validateConfig(config: Record<string, unknown>): ShelfConfig;
  * @returns The validated UI configuration.
  */
 declare function validateUiConfig(config: Record<string, unknown>): UIConfig;
+/** Testing options: what renders, how many run at once, and how screenshots are compared. */
+interface ShelfTestingOptions {
+  /** Pure renderer. Required: `testing` without a `runner` throws. */
+  runner: CaptureRunner;
+  /** Jobs this instance runs at once; auto-sized from CPU and memory when unset. */
+  concurrency?: number;
+  /**
+   * Retries after a first failed attempt before a capture job fails for good (default 2: three
+   * attempts). One limit covers failed attempts, lost leases and forked-child crashes.
+   */
+  retries?: number;
+  /**
+   * Lease of a job of the database queue, in seconds (default 300: 5 minutes). A running job
+   * renews it on a heartbeat (every `min(30 s, lease / 3)`) and on progress, so a stage that prints
+   * nothing is not redelivered while its process lives; a crashed holder's job is claimed by
+   * another instance once the lease runs out, so a shorter lease recovers crashes sooner.
+   */
+  leaseSeconds?: number;
+  /**
+   * Module run in a forked capture child (it calls `runCaptureChild` from `@storyshelf/core/capture`).
+   * The app consumes the queue and pushes each job to the child over IPC. Needs `runner`, which
+   * serves as the in-process fallback.
+   */
+  workerEntry?: string;
+  /**
+   * Split a big build across the queue: captures (story x viewport x engine) per shard. A build of
+   * up to twice this size still renders in one piece. Unset keeps every build in one job. Needs
+   * `runner`. With `workerEntry` the forked child plans and renders shards and puts them on the
+   * database queue itself.
+   */
+  shardSize?: number;
+  /**
+   * Requests per minute one client IP may make to the signed Storybook URL route, `/_s/<token>/*`
+   * (ADR 0007, decision 5). Default 6000, enough for a render fetching thousands of assets from one
+   * farm IP; a larger farm behind one address raises it. Over the limit the route answers `429`
+   * before it looks at the token, so the answer says nothing about a token's validity.
+   */
+  storybookUrlRateLimit?: number;
+  /**
+   * Where captures run. `auto` (default) forks when `workerEntry` is set and the host can afford
+   * a second process; `in-process` never forks; `fork` forks regardless of the host and fails at
+   * boot if it cannot.
+   */
+  mode?: "auto" | "in-process" | "fork";
+  /** Screenshot comparison, shared by capture and the re-diff endpoint. */
+  compare?: ShelfCompareOptions;
+  /** Image library selection; see {@link ShelfImagesOptions}. */
+  images?: ShelfImagesOptions;
+  /**
+   * Clock and timers of the database job queue. Tests inject a manual clock so lease and poll
+   * transitions do not depend on wall time; production leaves it unset (`Date.now` and the global
+   * timers).
+   */
+  queueClock?: {
+    now: () => number;
+    timers: {
+      setTimeout(callback: () => void, ms: number): unknown;
+      clearTimeout(handle: unknown): void;
+    };
+  };
+}
+/** Notification options: who can deliver, over which transport, with what branding. */
+interface ShelfNotificationsOptions {
+  /** Provider adapters (Slack, Teams, email, ...); a channel's `provider` must name one of these. */
+  notifiers?: NotifierProvider[];
+  /** Email transport. Listed here so its setup/teardown/validation hooks run with the app's. */
+  emailSender?: EmailSender;
+  /** Site-wide brand and sender settings for outgoing notifications. */
+  config?: NotificationsConfig;
+}
+/** Comparison options. */
+interface ShelfCompareOptions {
+  /**
+   * Worker threads for pixel diffs: default CPU count minus one (min 1), `0` diffs on the main
+   * thread. Takes precedence over `STORYSHELF_DIFF_WORKERS`.
+   */
+  threads?: number;
+}
+/** Image-handling options: which library decodes, encodes and resizes the PNGs. */
+interface ShelfImagesOptions {
+  /**
+   * Image library for diffs, diff overlays and AI thumbnails: `"pngjs"` (default, pure JavaScript,
+   * runs anywhere) or `"sharp"` (native, several times faster on large PNGs; needs the optional
+   * `sharp` package installed). Falls back to `STORYSHELF_IMAGE_ENGINE`. The pixel comparison is
+   * pixelmatch either way, so verdicts match.
+   */
+  engine?: "pngjs" | "sharp";
+}
 /** Adapter and configuration options for creating the shelf router. */
 interface ShelfOptions {
   database: DatabaseAdapter;
   storage: StorageAdapter;
-  captureRunner?: CaptureRunner;
-  captureQueue?: CaptureQueue;
+  /**
+   * Testing (render + diff in the background). Absent means Storybook hosting only: no renderer,
+   * no queue, and the tuning below is unreachable rather than silently ignored.
+   */
+  testing?: ShelfTestingOptions;
   auth?: Auth;
-  gitHosts?: GitHostProvider[];
-  notifiers?: NotifierProvider[];
-  emailSender?: EmailSender;
+  /** AI insights surface (ADR 0016). Set ⇒ AI on site-wide; absent ⇒ off. */
+  ai?: Ai;
+  /** Design-tool providers (Figma, …) that resolve links, metadata and previews. */
+  design?: DesignProvider[];
+  /** Notification subsystem: providers, the email transport, and shared brand/sender settings. */
+  notifications?: ShelfNotificationsOptions;
   logger?: Logger;
   ui?: UIConfig;
   config?: ShelfConfig;
@@ -196,5 +305,5 @@ interface ObservabilityHandle {
   shutdown(): Promise<void>;
 }
 //#endregion
-export { AdapterSnapshot, AuthUiConfig, BrandTheme, DEFAULT_MAX_UPLOAD_BYTES, NotificationsConfig, ObservabilityHandle, ShelfConfig, ShelfOptions, ShelfViewport, UIConfig, shelfConfigSchema, uiConfigSchema, validateConfig, validateUiConfig };
+export { ALLOW_SERVERLESS_ENV, AdapterSnapshot, AuthUiConfig, BrandTheme, DEFAULT_MAX_UPLOAD_BYTES, DEFAULT_SCRATCH_DIR, NotificationsConfig, ObservabilityHandle, ShelfCompareOptions, ShelfConfig, ShelfImagesOptions, ShelfNotificationsOptions, ShelfOptions, ShelfTestingOptions, ShelfViewport, UIConfig, assertServerless, isServerlessHost, notificationsConfigSchema, resolveShelfOptions, shelfConfigSchema, uiConfigSchema, validateConfig, validateUiConfig };
 //# sourceMappingURL=config.d.mts.map