@storyshelf/core 0.7.0 → 0.8.0

package/dist/capture/storybook-urls.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"storybook-urls.mjs","names":[],"sources":["../../src/capture/storybook-urls.ts"],"sourcesContent":["/**\n * The signed Storybook URL of a render (ADR 0007, decision 5): minted at the moment a pass starts,\n * only for a target whose browser cannot reach this host (`reach: \"url\"`). The URL is the build's\n * Storybook root, `<publicOrigin>/_s/<token>/`; it carries the token and is never logged. Its\n * lifetime comes from the pass's render budget unless the project sets one (`storybookUrlTtl`).\n */\nimport type { CaptureRunner, CaptureTarget } from \"../adapters/capture-runner.ts\";\nimport type { Build } from \"../schema/build.ts\";\nimport type { Project } from \"../schema/project.ts\";\nimport type { SecretInput } from \"../utils/encrypt.ts\";\nimport {\n  signStorybookToken,\n  storybookTokenPath,\n  storybookUrlTtl,\n} from \"../utils/storybook-token.ts\";\n\n/** What a pass tells the source: how long it may run, which sizes the token's lifetime. */\nexport interface StorybookUrlPass {\n  /** The render budget of the pass in ms (`renderBudgetMs`); unset when the pass has none. */\n  budgetMs?: number | undefined;\n}\n\n/** Gives the URL a target's browser opens, or `undefined` when it needs none (or none can be made). */\nexport type StorybookUrlSource = ((\n  target: CaptureTarget,\n  pass?: StorybookUrlPass,\n) => Promise<string | undefined>) & {\n  /**\n   * The lifetime in seconds a token minted for a pass of this budget gets (the project's override\n   * or the derived, capped one). A pass that outlasts it is rendered in slices, each with a fresh\n   * token (`renderInSlices`). `undefined` for a target that needs no signed URL (it is never\n   * sliced), and absent on a source that has no such limit.\n   */\n  ttlSeconds?: (target: CaptureTarget, budgetMs: number) => number | undefined;\n};\n\n/** What minting needs of a capture job. */\nexport interface StorybookUrlOptions {\n  runner: Pick<CaptureRunner, \"metadata\">;\n  secret?: SecretInput;\n  publicOrigin?: (() => Promise<string | undefined>) | undefined;\n}\n\n/**\n * A source of signed URLs for one build. Every call mints a fresh token, so a shard that waited in\n * the queue or a retried pass is never handed a token minted before it started.\n */\nexport function storybookUrlSource(\n  options: StorybookUrlOptions,\n  subject: {\n    build: Pick<Build, \"id\" | \"projectId\">;\n    project: Pick<Project, \"storybookUrlTtlSeconds\">;\n  },\n): StorybookUrlSource {\n  const source: StorybookUrlSource = async (target, pass = {}) => {\n    const origin = needsUrl(options.runner, target) ? await options.publicOrigin?.() : undefined;\n    return origin !== undefined && options.secret\n      ? `${origin}${mint(options.secret, subject, pass)}`\n      : undefined;\n  };\n  source.ttlSeconds = (target, budgetMs): number | undefined =>\n    needsUrl(options.runner, target)\n      ? storybookUrlTtl({ override: subject.project.storybookUrlTtlSeconds, budgetMs })\n      : undefined;\n  return source;\n}\n\n/** The path of a fresh token for one pass of the build. */\nfunction mint(\n  secret: SecretInput,\n  subject: Parameters<typeof storybookUrlSource>[1],\n  pass: StorybookUrlPass,\n): string {\n  const ttlSeconds = storybookUrlTtl({\n    override: subject.project.storybookUrlTtlSeconds,\n    budgetMs: pass.budgetMs ?? 0,\n  });\n  const { id: buildId, projectId } = subject.build;\n  return storybookTokenPath(signStorybookToken({ secret, projectId, buildId, ttlSeconds }));\n}\n\nfunction needsUrl(runner: Pick<CaptureRunner, \"metadata\">, target: CaptureTarget): boolean {\n  return runner.metadata.targets?.some((t) => t.target === target && t.reach === \"url\") ?? false;\n}\n"],"mappings":";;;;;;;;;AA+CA,SAAgB,mBACd,SACA,SAIoB;CACpB,MAAM,SAA6B,OAAO,QAAQ,OAAO,CAAC,MAAM;EAC9D,MAAM,SAAS,SAAS,QAAQ,QAAQ,MAAM,IAAI,MAAM,QAAQ,eAAe,IAAI,KAAA;EACnF,OAAO,WAAW,KAAA,KAAa,QAAQ,SACnC,GAAG,SAAS,KAAK,QAAQ,QAAQ,SAAS,IAAI,MAC9C,KAAA;CACN;CACA,OAAO,cAAc,QAAQ,aAC3B,SAAS,QAAQ,QAAQ,MAAM,IAC3B,gBAAgB;EAAE,UAAU,QAAQ,QAAQ;EAAwB;CAAS,CAAC,IAC9E,KAAA;CACN,OAAO;AACT;;AAGA,SAAS,KACP,QACA,SACA,MACQ;CACR,MAAM,aAAa,gBAAgB;EACjC,UAAU,QAAQ,QAAQ;EAC1B,UAAU,KAAK,YAAY;CAC7B,CAAC;CACD,MAAM,EAAE,IAAI,SAAS,cAAc,QAAQ;CAC3C,OAAO,mBAAmB,mBAAmB;EAAE;EAAQ;EAAW;EAAS;CAAW,CAAC,CAAC;AAC1F;AAEA,SAAS,SAAS,QAAyC,QAAgC;CACzF,OAAO,OAAO,SAAS,SAAS,MAAM,MAAM,EAAE,WAAW,UAAU,EAAE,UAAU,KAAK,KAAK;AAC3F"}
+{"version":3,"file":"storybook-urls.mjs","names":[],"sources":["../../src/capture/storybook-urls.ts"],"sourcesContent":["/**\n * The signed Storybook URL of a render (ADR 0007, decision 5): minted at the moment a pass starts,\n * only for a target whose browser cannot reach this host (`reach: \"url\"`). The URL is the build's\n * Storybook root, `<publicOrigin>/_s/<token>/`; it carries the token and is never logged. Its\n * lifetime comes from the pass's render budget unless the project sets one (`storybookUrlTtl`).\n * Every token minted here carries the signed `capture` purpose, the only claim that lets the\n * server opt a response into browser-private caching.\n */\nimport type { CaptureRunner, CaptureTarget } from \"../adapters/capture-runner.ts\";\nimport type { Build } from \"../schema/build.ts\";\nimport type { Project } from \"../schema/project.ts\";\nimport type { SecretInput } from \"../utils/encrypt.ts\";\nimport {\n  signStorybookToken,\n  storybookTokenPath,\n  storybookUrlTtl,\n} from \"../utils/storybook-token.ts\";\n\n/** What a pass tells the source: how long it may run, which sizes the token's lifetime. */\nexport interface StorybookUrlPass {\n  /** The render budget of the pass in ms (`renderBudgetMs`); unset when the pass has none. */\n  budgetMs?: number | undefined;\n}\n\n/** Gives the URL a target's browser opens, or `undefined` when it needs none (or none can be made). */\nexport type StorybookUrlSource = ((\n  target: CaptureTarget,\n  pass?: StorybookUrlPass,\n) => Promise<string | undefined>) & {\n  /**\n   * The lifetime in seconds a token minted for a pass of this budget gets (the project's override\n   * or the derived, capped one). A pass that outlasts it is rendered in slices, each with a fresh\n   * token (`renderInSlices`). `undefined` for a target that needs no signed URL (it is never\n   * sliced), and absent on a source that has no such limit.\n   */\n  ttlSeconds?: (target: CaptureTarget, budgetMs: number) => number | undefined;\n};\n\n/** What minting needs of a capture job. */\nexport interface StorybookUrlOptions {\n  runner: Pick<CaptureRunner, \"metadata\">;\n  secret?: SecretInput;\n  publicOrigin?: (() => Promise<string | undefined>) | undefined;\n}\n\n/**\n * A source of signed URLs for one build. Every call mints a fresh token, so a shard that waited in\n * the queue or a retried pass is never handed a token minted before it started.\n */\nexport function storybookUrlSource(\n  options: StorybookUrlOptions,\n  subject: {\n    build: Pick<Build, \"id\" | \"projectId\">;\n    project: Pick<Project, \"storybookUrlTtlSeconds\">;\n  },\n): StorybookUrlSource {\n  const source: StorybookUrlSource = async (target, pass = {}) => {\n    const origin = needsUrl(options.runner, target) ? await options.publicOrigin?.() : undefined;\n    return origin !== undefined && options.secret\n      ? `${origin}${mint(options.secret, subject, pass)}`\n      : undefined;\n  };\n  source.ttlSeconds = (target, budgetMs): number | undefined =>\n    needsUrl(options.runner, target)\n      ? storybookUrlTtl({ override: subject.project.storybookUrlTtlSeconds, budgetMs })\n      : undefined;\n  return source;\n}\n\n/** The path of a fresh token for one pass of the build. */\nfunction mint(\n  secret: SecretInput,\n  subject: Parameters<typeof storybookUrlSource>[1],\n  pass: StorybookUrlPass,\n): string {\n  const ttlSeconds = storybookUrlTtl({\n    override: subject.project.storybookUrlTtlSeconds,\n    budgetMs: pass.budgetMs ?? 0,\n  });\n  const { id: buildId, projectId } = subject.build;\n  return storybookTokenPath(\n    signStorybookToken({ secret, projectId, buildId, ttlSeconds, purpose: \"capture\" }),\n  );\n}\n\nfunction needsUrl(runner: Pick<CaptureRunner, \"metadata\">, target: CaptureTarget): boolean {\n  return runner.metadata.targets?.some((t) => t.target === target && t.reach === \"url\") ?? false;\n}\n"],"mappings":";;;;;;;;;AAiDA,SAAgB,mBACd,SACA,SAIoB;CACpB,MAAM,SAA6B,OAAO,QAAQ,OAAO,CAAC,MAAM;EAC9D,MAAM,SAAS,SAAS,QAAQ,QAAQ,MAAM,IAAI,MAAM,QAAQ,eAAe,IAAI,KAAA;EACnF,OAAO,WAAW,KAAA,KAAa,QAAQ,SACnC,GAAG,SAAS,KAAK,QAAQ,QAAQ,SAAS,IAAI,MAC9C,KAAA;CACN;CACA,OAAO,cAAc,QAAQ,aAC3B,SAAS,QAAQ,QAAQ,MAAM,IAC3B,gBAAgB;EAAE,UAAU,QAAQ,QAAQ;EAAwB;CAAS,CAAC,IAC9E,KAAA;CACN,OAAO;AACT;;AAGA,SAAS,KACP,QACA,SACA,MACQ;CACR,MAAM,aAAa,gBAAgB;EACjC,UAAU,QAAQ,QAAQ;EAC1B,UAAU,KAAK,YAAY;CAC7B,CAAC;CACD,MAAM,EAAE,IAAI,SAAS,cAAc,QAAQ;CAC3C,OAAO,mBACL,mBAAmB;EAAE;EAAQ;EAAW;EAAS;EAAY,SAAS;CAAU,CAAC,CACnF;AACF;AAEA,SAAS,SAAS,QAAyC,QAAgC;CACzF,OAAO,OAAO,SAAS,SAAS,MAAM,MAAM,EAAE,WAAW,UAAU,EAAE,UAAU,KAAK,KAAK;AAC3F"}

package/dist/capture/storybook.d.mts

@@ -2,7 +2,6 @@ import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { DiscoverOptions, StoryEntry, StoryParameters, StorySourceAdapter, StoryViewportConfig, Viewport } from "./adapter.mjs";
 import { DepGraph } from "@storyshelf/affected";
-//#region src/capture/storybook.d.ts
 /** Story parameters as serialized by the Storybook index. */
 interface StorybookParameters {
   chromatic?: StoryParameters;
@@ -47,6 +46,5 @@ declare class StorybookAdapter implements StorySourceAdapter {
   loadDependencyGraph(source: string): Promise<DepGraph | null>;
   private readIndex;
 }
-//#endregion
 export { STORYBOOK_BUILTIN_VIEWPORTS, StorybookAdapter, mergeParameters, resolveStoryViewports };
 //# sourceMappingURL=storybook.d.mts.map

package/dist/capture/storybook.mjs

@@ -1,12 +1,12 @@
-import "node:path";
+import { join } from "node:path";
 import "node:url";
 import.meta.url;
+import { declaredIgnoreSelectors } from "./ignore-regions.mjs";
 import { applyModes, buildGlobalsParam } from "./modes.mjs";
 import { extractDesignUrl } from "./design.mjs";
-import { join } from "node:path";
 import { STATS_FILENAME, loadDepGraph } from "@storyshelf/affected";
 import { readFile } from "node:fs/promises";
-//#region src/capture/storybook.ts
+// src/capture/storybook.ts
 /** Merge the `chromatic` and `storyshelf` parameter layers (`storyshelf` wins). */
 function mergeParameters(entry) {
 	const { figma: _figma, ...storyshelf } = entry.parameters?.storyshelf ?? {};
@@ -17,6 +17,11 @@ function mergeParameters(entry) {
 	const modes = mergeModes(entry.parameters?.chromatic?.modes, entry.parameters?.storyshelf?.modes);
 	if (modes) merged.modes = modes;
 	if (entry.parameters?.viewport) merged.viewport = entry.parameters.viewport;
+	if ("ignoreSelectors" in merged) {
+		const declared = declaredIgnoreSelectors(merged.ignoreSelectors);
+		if (declared) merged.ignoreSelectors = declared;
+		else delete merged.ignoreSelectors;
+	}
 	return Object.keys(merged).length > 0 ? merged : void 0;
 }
 /** Union both parameter keys' modes by name (`storyshelf` wins per mode). */
@@ -158,7 +163,6 @@ var StorybookAdapter = class {
 		throw new Error(`No Storybook index found in ${source}`);
 	}
 };
-//#endregion
 export { STORYBOOK_BUILTIN_VIEWPORTS, StorybookAdapter, mergeParameters, resolveStoryViewports };
 
 //# sourceMappingURL=storybook.mjs.map

package/dist/capture/storybook.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"storybook.mjs","names":[],"sources":["../../src/capture/storybook.ts"],"sourcesContent":["import { loadDepGraph, STATS_FILENAME, type DepGraph } from \"@storyshelf/affected\";\nimport { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport type {\n  ModeMap,\n  StoryEntry,\n  StoryParameters,\n  StorySourceAdapter,\n  StoryViewportConfig,\n  StoryViewportDefinition,\n  Viewport,\n} from \"./adapter.ts\";\nimport type { DiscoverOptions } from \"./adapter.ts\";\nimport { extractDesignUrl, type DesignUrlParser } from \"./design.ts\";\nimport { applyModes, buildGlobalsParam } from \"./modes.ts\";\n\ninterface StorybookIndex {\n  v: number;\n  entries: Record<\n    string,\n    {\n      id: string;\n      name: string;\n      title: string;\n      importPath?: string;\n      tags?: string[];\n      type: string;\n      subtype?: string;\n      /** Test entries only: the id of the story the `.test()` is written under. */\n      parent?: string;\n      parameters?: StorybookParameters;\n    }\n  >;\n}\n\n/** Story parameters as serialized by the Storybook index. */\ninterface StorybookParameters {\n  chromatic?: StoryParameters;\n  storyshelf?: StoryParameters & { figma?: unknown };\n  viewport?: StoryViewportConfig;\n  design?: unknown;\n}\n\n/** Merge the `chromatic` and `storyshelf` parameter layers (`storyshelf` wins). */\nexport function mergeParameters(entry: {\n  parameters?: StorybookParameters;\n}): StoryParameters | undefined {\n  const { figma: _figma, ...storyshelf } = entry.parameters?.storyshelf ?? {};\n  const merged: StoryParameters = { ...entry.parameters?.chromatic, ...storyshelf };\n  const modes = mergeModes(entry.parameters?.chromatic?.modes, entry.parameters?.storyshelf?.modes);\n  if (modes) merged.modes = modes;\n  if (entry.parameters?.viewport) merged.viewport = entry.parameters.viewport;\n  return Object.keys(merged).length > 0 ? merged : undefined;\n}\n\n/** Union both parameter keys' modes by name (`storyshelf` wins per mode). */\nfunction mergeModes(chromatic?: ModeMap, storyshelf?: ModeMap): ModeMap | undefined {\n  const merged = { ...chromatic, ...storyshelf };\n  return Object.keys(merged).length > 0 ? merged : undefined;\n}\n\n/**\n * The Storybook `MINIMAL_VIEWPORTS` snapshot used to resolve a story's\n * `defaultViewport` name at capture time. Dimensions are the documented\n * stable set; inline `parameters.viewport.viewports` always win over these.\n */\nexport const STORYBOOK_BUILTIN_VIEWPORTS: Readonly<Record<string, Viewport>> = {\n  mobile1: { name: \"mobile1\", width: 320, height: 568 },\n  mobile2: { name: \"mobile2\", width: 414, height: 896 },\n  tablet: { name: \"tablet\", width: 834, height: 1112 },\n  desktop: { name: \"desktop\", width: 1024, height: 1280 },\n};\n\n/**\n * Resolve the viewports a story should be captured at: the project's global\n * list plus the story's Storybook default viewport (union), deduplicated by\n * name. An unresolvable or duplicate default contributes nothing extra.\n */\nexport function resolveStoryViewports(\n  entry: Pick<StoryEntry, \"parameters\">,\n  globalViewports: Viewport[],\n): Viewport[] {\n  const resolved = storyViewport(entry);\n  const withDefault =\n    resolved && !globalViewports.some((v) => v.name === resolved.name)\n      ? [...globalViewports, resolved]\n      : [...globalViewports];\n  return applyModes(entry.parameters?.modes, withDefault, (name) => namedViewport(entry, name));\n}\n\n/** Resolve a Storybook viewport name via the story's inline config, then builtins. */\nfunction namedViewport(entry: Pick<StoryEntry, \"parameters\">, name: string): Viewport | undefined {\n  const inline = entry.parameters?.viewport?.viewports?.[name];\n  return (\n    (inline ? viewportFromInline(name, inline) : undefined) ?? STORYBOOK_BUILTIN_VIEWPORTS[name]\n  );\n}\n\nfunction storyViewport(entry: Pick<StoryEntry, \"parameters\">): Viewport | undefined {\n  const config = entry.parameters?.viewport;\n  const name = config?.defaultViewport;\n  const inline = name ? config?.viewports?.[name] : undefined;\n  const resolved =\n    name && inline\n      ? viewportFromInline(name, inline)\n      : name\n        ? STORYBOOK_BUILTIN_VIEWPORTS[name]\n        : undefined;\n  return resolved;\n}\n\nfunction viewportFromInline(\n  defaultName: string,\n  inline: StoryViewportDefinition,\n): Viewport | undefined {\n  const dims = viewportDims(inline.styles);\n  return dims ? { name: inline.name ?? defaultName, ...dims } : undefined;\n}\n\nfunction viewportDims(\n  styles: StoryViewportDefinition[\"styles\"] | undefined,\n): { width: number; height: number } | undefined {\n  const width = pxOf(styles?.width);\n  const height = pxOf(styles?.height);\n  return width !== undefined && height !== undefined ? { width, height } : undefined;\n}\n\nfunction pxOf(value: string | number | undefined): number | undefined {\n  if (typeof value === \"number\") return Math.round(value);\n  const bare = typeof value === \"string\" ? value.trim() : \"\";\n  const match = /^(\\d+(?:\\.\\d+)?)px$/u.exec(bare);\n  return match ? Number(match[1]) : undefined;\n}\n\nfunction toTestEntry(entry: StorybookIndex[\"entries\"][string]): StoryEntry {\n  const test = toStoryEntry(entry);\n  if (entry.parent !== undefined) test.parentId = entry.parent;\n  return test;\n}\n\nfunction toStoryEntry(\n  entry: StorybookIndex[\"entries\"][string],\n  parseDesignUrl?: DesignUrlParser,\n): StoryEntry {\n  const design = parseDesignUrl ? extractDesignUrl(entry.parameters, parseDesignUrl) : {};\n  const story: StoryEntry = {\n    id: entry.id,\n    title: entry.title,\n    name: entry.name,\n    importPath: entry.importPath,\n    tags: entry.tags,\n    type: entry.type === \"docs\" ? \"docs\" : \"story\",\n    parameters: mergeParameters(entry),\n  };\n  if (design.url) story.designUrl = design.url;\n  if (design.invalid) story.designInvalid = design.invalid;\n  return story;\n}\n\n/** Discovers stories from a built Storybook via its index file. */\nexport class StorybookAdapter implements StorySourceAdapter {\n  readonly name = \"storybook\";\n  readonly screenshotSelector = \"#storybook-root\";\n\n  async discover(source: string, options: DiscoverOptions = {}): Promise<StoryEntry[]> {\n    const index = await this.readIndex(source);\n    return Object.values(index.entries)\n      .filter((entry) => entry.type !== \"docs\" && entry.subtype !== \"test\")\n      .map((entry) => toStoryEntry(entry, options.parseDesignUrl));\n  }\n\n  /**\n   * The `.test()` entries of a Storybook 10 build (index `subtype: \"test\"`), which {@link discover}\n   * leaves out. Empty for older Storybooks, whose index has no such entries.\n   */\n  async discoverTests(source: string): Promise<StoryEntry[]> {\n    const index = await this.readIndex(source);\n    return Object.values(index.entries)\n      .filter((entry) => entry.subtype === \"test\" && entry.type !== \"docs\")\n      .map((entry) => toTestEntry(entry));\n  }\n\n  // eslint-disable-next-line class-methods-use-this\n  buildUrl(baseUrl: string, storyId: string, globals?: Record<string, unknown>): string {\n    const url = `${baseUrl}/iframe.html?id=${encodeURIComponent(storyId)}&viewMode=story`;\n    const param = globals ? buildGlobalsParam(globals) : \"\";\n    return param === \"\" ? url : `${url}&globals=${encodeURIComponent(param)}`;\n  }\n\n  /**\n   * Load the Vite stats dependency graph of an extracted build for affected\n   * capture. Resolves `null` when the build ships no usable stats, in which\n   * case the orchestrator renders every story.\n   */\n  // eslint-disable-next-line class-methods-use-this\n  async loadDependencyGraph(source: string): Promise<DepGraph | null> {\n    return await loadDepGraph(join(source, STATS_FILENAME));\n  }\n\n  // eslint-disable-next-line class-methods-use-this\n  private async readIndex(source: string): Promise<StorybookIndex> {\n    const candidates: string[] = [\"stories.json\", \"index.json\"];\n    const results = await Promise.all(\n      candidates.map(async (name) => {\n        try {\n          const raw = await readFile(join(source, name), \"utf8\");\n          return JSON.parse(raw) as StorybookIndex;\n        } catch {\n          return null;\n        }\n      }),\n    );\n    const found = results.find((index) => index !== null);\n    if (found) {\n      return found;\n    }\n    throw new Error(`No Storybook index found in ${source}`);\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"storybook.mjs","names":[],"sources":["../../src/capture/storybook.ts"],"sourcesContent":["import { loadDepGraph, STATS_FILENAME, type DepGraph } from \"@storyshelf/affected\";\nimport { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport type {\n  ModeMap,\n  StoryEntry,\n  StoryParameters,\n  StorySourceAdapter,\n  StoryViewportConfig,\n  StoryViewportDefinition,\n  Viewport,\n} from \"./adapter.ts\";\nimport type { DiscoverOptions } from \"./adapter.ts\";\nimport { extractDesignUrl, type DesignUrlParser } from \"./design.ts\";\nimport { declaredIgnoreSelectors } from \"./ignore-regions.ts\";\nimport { applyModes, buildGlobalsParam } from \"./modes.ts\";\n\ninterface StorybookIndex {\n  v: number;\n  entries: Record<\n    string,\n    {\n      id: string;\n      name: string;\n      title: string;\n      importPath?: string;\n      tags?: string[];\n      type: string;\n      subtype?: string;\n      /** Test entries only: the id of the story the `.test()` is written under. */\n      parent?: string;\n      parameters?: StorybookParameters;\n    }\n  >;\n}\n\n/** Story parameters as serialized by the Storybook index. */\ninterface StorybookParameters {\n  chromatic?: StoryParameters;\n  storyshelf?: StoryParameters & { figma?: unknown };\n  viewport?: StoryViewportConfig;\n  design?: unknown;\n}\n\n/** Merge the `chromatic` and `storyshelf` parameter layers (`storyshelf` wins). */\nexport function mergeParameters(entry: {\n  parameters?: StorybookParameters;\n}): StoryParameters | undefined {\n  const { figma: _figma, ...storyshelf } = entry.parameters?.storyshelf ?? {};\n  const merged: StoryParameters = { ...entry.parameters?.chromatic, ...storyshelf };\n  const modes = mergeModes(entry.parameters?.chromatic?.modes, entry.parameters?.storyshelf?.modes);\n  if (modes) merged.modes = modes;\n  if (entry.parameters?.viewport) merged.viewport = entry.parameters.viewport;\n  if (\"ignoreSelectors\" in merged) {\n    const declared = declaredIgnoreSelectors(merged.ignoreSelectors);\n    if (declared) merged.ignoreSelectors = declared;\n    else delete merged.ignoreSelectors;\n  }\n  return Object.keys(merged).length > 0 ? merged : undefined;\n}\n\n/** Union both parameter keys' modes by name (`storyshelf` wins per mode). */\nfunction mergeModes(chromatic?: ModeMap, storyshelf?: ModeMap): ModeMap | undefined {\n  const merged = { ...chromatic, ...storyshelf };\n  return Object.keys(merged).length > 0 ? merged : undefined;\n}\n\n/**\n * The Storybook `MINIMAL_VIEWPORTS` snapshot used to resolve a story's\n * `defaultViewport` name at capture time. Dimensions are the documented\n * stable set; inline `parameters.viewport.viewports` always win over these.\n */\nexport const STORYBOOK_BUILTIN_VIEWPORTS: Readonly<Record<string, Viewport>> = {\n  mobile1: { name: \"mobile1\", width: 320, height: 568 },\n  mobile2: { name: \"mobile2\", width: 414, height: 896 },\n  tablet: { name: \"tablet\", width: 834, height: 1112 },\n  desktop: { name: \"desktop\", width: 1024, height: 1280 },\n};\n\n/**\n * Resolve the viewports a story should be captured at: the project's global\n * list plus the story's Storybook default viewport (union), deduplicated by\n * name. An unresolvable or duplicate default contributes nothing extra.\n */\nexport function resolveStoryViewports(\n  entry: Pick<StoryEntry, \"parameters\">,\n  globalViewports: Viewport[],\n): Viewport[] {\n  const resolved = storyViewport(entry);\n  const withDefault =\n    resolved && !globalViewports.some((v) => v.name === resolved.name)\n      ? [...globalViewports, resolved]\n      : [...globalViewports];\n  return applyModes(entry.parameters?.modes, withDefault, (name) => namedViewport(entry, name));\n}\n\n/** Resolve a Storybook viewport name via the story's inline config, then builtins. */\nfunction namedViewport(entry: Pick<StoryEntry, \"parameters\">, name: string): Viewport | undefined {\n  const inline = entry.parameters?.viewport?.viewports?.[name];\n  return (\n    (inline ? viewportFromInline(name, inline) : undefined) ?? STORYBOOK_BUILTIN_VIEWPORTS[name]\n  );\n}\n\nfunction storyViewport(entry: Pick<StoryEntry, \"parameters\">): Viewport | undefined {\n  const config = entry.parameters?.viewport;\n  const name = config?.defaultViewport;\n  const inline = name ? config?.viewports?.[name] : undefined;\n  const resolved =\n    name && inline\n      ? viewportFromInline(name, inline)\n      : name\n        ? STORYBOOK_BUILTIN_VIEWPORTS[name]\n        : undefined;\n  return resolved;\n}\n\nfunction viewportFromInline(\n  defaultName: string,\n  inline: StoryViewportDefinition,\n): Viewport | undefined {\n  const dims = viewportDims(inline.styles);\n  return dims ? { name: inline.name ?? defaultName, ...dims } : undefined;\n}\n\nfunction viewportDims(\n  styles: StoryViewportDefinition[\"styles\"] | undefined,\n): { width: number; height: number } | undefined {\n  const width = pxOf(styles?.width);\n  const height = pxOf(styles?.height);\n  return width !== undefined && height !== undefined ? { width, height } : undefined;\n}\n\nfunction pxOf(value: string | number | undefined): number | undefined {\n  if (typeof value === \"number\") return Math.round(value);\n  const bare = typeof value === \"string\" ? value.trim() : \"\";\n  const match = /^(\\d+(?:\\.\\d+)?)px$/u.exec(bare);\n  return match ? Number(match[1]) : undefined;\n}\n\nfunction toTestEntry(entry: StorybookIndex[\"entries\"][string]): StoryEntry {\n  const test = toStoryEntry(entry);\n  if (entry.parent !== undefined) test.parentId = entry.parent;\n  return test;\n}\n\nfunction toStoryEntry(\n  entry: StorybookIndex[\"entries\"][string],\n  parseDesignUrl?: DesignUrlParser,\n): StoryEntry {\n  const design = parseDesignUrl ? extractDesignUrl(entry.parameters, parseDesignUrl) : {};\n  const story: StoryEntry = {\n    id: entry.id,\n    title: entry.title,\n    name: entry.name,\n    importPath: entry.importPath,\n    tags: entry.tags,\n    type: entry.type === \"docs\" ? \"docs\" : \"story\",\n    parameters: mergeParameters(entry),\n  };\n  if (design.url) story.designUrl = design.url;\n  if (design.invalid) story.designInvalid = design.invalid;\n  return story;\n}\n\n/** Discovers stories from a built Storybook via its index file. */\nexport class StorybookAdapter implements StorySourceAdapter {\n  readonly name = \"storybook\";\n  readonly screenshotSelector = \"#storybook-root\";\n\n  async discover(source: string, options: DiscoverOptions = {}): Promise<StoryEntry[]> {\n    const index = await this.readIndex(source);\n    return Object.values(index.entries)\n      .filter((entry) => entry.type !== \"docs\" && entry.subtype !== \"test\")\n      .map((entry) => toStoryEntry(entry, options.parseDesignUrl));\n  }\n\n  /**\n   * The `.test()` entries of a Storybook 10 build (index `subtype: \"test\"`), which {@link discover}\n   * leaves out. Empty for older Storybooks, whose index has no such entries.\n   */\n  async discoverTests(source: string): Promise<StoryEntry[]> {\n    const index = await this.readIndex(source);\n    return Object.values(index.entries)\n      .filter((entry) => entry.subtype === \"test\" && entry.type !== \"docs\")\n      .map((entry) => toTestEntry(entry));\n  }\n\n  // eslint-disable-next-line class-methods-use-this\n  buildUrl(baseUrl: string, storyId: string, globals?: Record<string, unknown>): string {\n    const url = `${baseUrl}/iframe.html?id=${encodeURIComponent(storyId)}&viewMode=story`;\n    const param = globals ? buildGlobalsParam(globals) : \"\";\n    return param === \"\" ? url : `${url}&globals=${encodeURIComponent(param)}`;\n  }\n\n  /**\n   * Load the Vite stats dependency graph of an extracted build for affected\n   * capture. Resolves `null` when the build ships no usable stats, in which\n   * case the orchestrator renders every story.\n   */\n  // eslint-disable-next-line class-methods-use-this\n  async loadDependencyGraph(source: string): Promise<DepGraph | null> {\n    return await loadDepGraph(join(source, STATS_FILENAME));\n  }\n\n  // eslint-disable-next-line class-methods-use-this\n  private async readIndex(source: string): Promise<StorybookIndex> {\n    const candidates: string[] = [\"stories.json\", \"index.json\"];\n    const results = await Promise.all(\n      candidates.map(async (name) => {\n        try {\n          const raw = await readFile(join(source, name), \"utf8\");\n          return JSON.parse(raw) as StorybookIndex;\n        } catch {\n          return null;\n        }\n      }),\n    );\n    const found = results.find((index) => index !== null);\n    if (found) {\n      return found;\n    }\n    throw new Error(`No Storybook index found in ${source}`);\n  }\n}\n"],"mappings":";;;;;;;;;;AA6CA,SAAgB,gBAAgB,OAEA;CAC9B,MAAM,EAAE,OAAO,QAAQ,GAAG,eAAe,MAAM,YAAY,cAAc,CAAC;CAC1E,MAAM,SAA0B;EAAE,GAAG,MAAM,YAAY;EAAW,GAAG;CAAW;CAChF,MAAM,QAAQ,WAAW,MAAM,YAAY,WAAW,OAAO,MAAM,YAAY,YAAY,KAAK;CAChG,IAAI,OAAO,OAAO,QAAQ;CAC1B,IAAI,MAAM,YAAY,UAAU,OAAO,WAAW,MAAM,WAAW;CACnE,IAAI,qBAAqB,QAAQ;EAC/B,MAAM,WAAW,wBAAwB,OAAO,eAAe;EAC/D,IAAI,UAAU,OAAO,kBAAkB;OAClC,OAAO,OAAO;CACrB;CACA,OAAO,OAAO,KAAK,MAAM,CAAC,CAAC,SAAS,IAAI,SAAS,KAAA;AACnD;;AAGA,SAAS,WAAW,WAAqB,YAA2C;CAClF,MAAM,SAAS;EAAE,GAAG;EAAW,GAAG;CAAW;CAC7C,OAAO,OAAO,KAAK,MAAM,CAAC,CAAC,SAAS,IAAI,SAAS,KAAA;AACnD;;;;;;AAOA,MAAa,8BAAkE;CAC7E,SAAS;EAAE,MAAM;EAAW,OAAO;EAAK,QAAQ;CAAI;CACpD,SAAS;EAAE,MAAM;EAAW,OAAO;EAAK,QAAQ;CAAI;CACpD,QAAQ;EAAE,MAAM;EAAU,OAAO;EAAK,QAAQ;CAAK;CACnD,SAAS;EAAE,MAAM;EAAW,OAAO;EAAM,QAAQ;CAAK;AACxD;;;;;;AAOA,SAAgB,sBACd,OACA,iBACY;CACZ,MAAM,WAAW,cAAc,KAAK;CACpC,MAAM,cACJ,YAAY,CAAC,gBAAgB,MAAM,MAAM,EAAE,SAAS,SAAS,IAAI,IAC7D,CAAC,GAAG,iBAAiB,QAAQ,IAC7B,CAAC,GAAG,eAAe;CACzB,OAAO,WAAW,MAAM,YAAY,OAAO,cAAc,SAAS,cAAc,OAAO,IAAI,CAAC;AAC9F;;AAGA,SAAS,cAAc,OAAuC,MAAoC;CAChG,MAAM,SAAS,MAAM,YAAY,UAAU,YAAY;CACvD,QACG,SAAS,mBAAmB,MAAM,MAAM,IAAI,KAAA,MAAc,4BAA4B;AAE3F;AAEA,SAAS,cAAc,OAA6D;CAClF,MAAM,SAAS,MAAM,YAAY;CACjC,MAAM,OAAO,QAAQ;CACrB,MAAM,SAAS,OAAO,QAAQ,YAAY,QAAQ,KAAA;CAOlD,OALE,QAAQ,SACJ,mBAAmB,MAAM,MAAM,IAC/B,OACE,4BAA4B,QAC5B,KAAA;AAEV;AAEA,SAAS,mBACP,aACA,QACsB;CACtB,MAAM,OAAO,aAAa,OAAO,MAAM;CACvC,OAAO,OAAO;EAAE,MAAM,OAAO,QAAQ;EAAa,GAAG;CAAK,IAAI,KAAA;AAChE;AAEA,SAAS,aACP,QAC+C;CAC/C,MAAM,QAAQ,KAAK,QAAQ,KAAK;CAChC,MAAM,SAAS,KAAK,QAAQ,MAAM;CAClC,OAAO,UAAU,KAAA,KAAa,WAAW,KAAA,IAAY;EAAE;EAAO;CAAO,IAAI,KAAA;AAC3E;AAEA,SAAS,KAAK,OAAwD;CACpE,IAAI,OAAO,UAAU,UAAU,OAAO,KAAK,MAAM,KAAK;CACtD,MAAM,OAAO,OAAO,UAAU,WAAW,MAAM,KAAK,IAAI;CACxD,MAAM,QAAQ,uBAAuB,KAAK,IAAI;CAC9C,OAAO,QAAQ,OAAO,MAAM,EAAE,IAAI,KAAA;AACpC;AAEA,SAAS,YAAY,OAAsD;CACzE,MAAM,OAAO,aAAa,KAAK;CAC/B,IAAI,MAAM,WAAW,KAAA,GAAW,KAAK,WAAW,MAAM;CACtD,OAAO;AACT;AAEA,SAAS,aACP,OACA,gBACY;CACZ,MAAM,SAAS,iBAAiB,iBAAiB,MAAM,YAAY,cAAc,IAAI,CAAC;CACtF,MAAM,QAAoB;EACxB,IAAI,MAAM;EACV,OAAO,MAAM;EACb,MAAM,MAAM;EACZ,YAAY,MAAM;EAClB,MAAM,MAAM;EACZ,MAAM,MAAM,SAAS,SAAS,SAAS;EACvC,YAAY,gBAAgB,KAAK;CACnC;CACA,IAAI,OAAO,KAAK,MAAM,YAAY,OAAO;CACzC,IAAI,OAAO,SAAS,MAAM,gBAAgB,OAAO;CACjD,OAAO;AACT;;AAGA,IAAa,mBAAb,MAA4D;CAC1D,OAAgB;CAChB,qBAA8B;CAE9B,MAAM,SAAS,QAAgB,UAA2B,CAAC,GAA0B;EACnF,MAAM,QAAQ,MAAM,KAAK,UAAU,MAAM;EACzC,OAAO,OAAO,OAAO,MAAM,OAAO,CAAC,CAChC,QAAQ,UAAU,MAAM,SAAS,UAAU,MAAM,YAAY,MAAM,CAAC,CACpE,KAAK,UAAU,aAAa,OAAO,QAAQ,cAAc,CAAC;CAC/D;;;;;CAMA,MAAM,cAAc,QAAuC;EACzD,MAAM,QAAQ,MAAM,KAAK,UAAU,MAAM;EACzC,OAAO,OAAO,OAAO,MAAM,OAAO,CAAC,CAChC,QAAQ,UAAU,MAAM,YAAY,UAAU,MAAM,SAAS,MAAM,CAAC,CACpE,KAAK,UAAU,YAAY,KAAK,CAAC;CACtC;CAGA,SAAS,SAAiB,SAAiB,SAA2C;EACpF,MAAM,MAAM,GAAG,QAAQ,kBAAkB,mBAAmB,OAAO,EAAE;EACrE,MAAM,QAAQ,UAAU,kBAAkB,OAAO,IAAI;EACrD,OAAO,UAAU,KAAK,MAAM,GAAG,IAAI,WAAW,mBAAmB,KAAK;CACxE;;;;;;CAQA,MAAM,oBAAoB,QAA0C;EAClE,OAAO,MAAM,aAAa,KAAK,QAAQ,cAAc,CAAC;CACxD;CAGA,MAAc,UAAU,QAAyC;EAY/D,MAAM,SAAQ,MAVQ,QAAQ,IAC5B,CAF4B,gBAAgB,YAEnC,CAAC,CAAC,IAAI,OAAO,SAAS;GAC7B,IAAI;IACF,MAAM,MAAM,MAAM,SAAS,KAAK,QAAQ,IAAI,GAAG,MAAM;IACrD,OAAO,KAAK,MAAM,GAAG;GACvB,QAAQ;IACN,OAAO;GACT;EACF,CAAC,CACH,EAAA,CACsB,MAAM,UAAU,UAAU,IAAI;EACpD,IAAI,OACF,OAAO;EAET,MAAM,IAAI,MAAM,+BAA+B,QAAQ;CACzD;AACF"}

package/dist/capture/target.mjs

@@ -3,7 +3,7 @@ import "node:url";
 import.meta.url;
 import { BuildModel } from "../models/build.mjs";
 import { ProjectModel } from "../models/project.mjs";
-//#region src/capture/target.ts
+// src/capture/target.ts
 /** Load a build and its project, throwing when either is gone. */
 async function loadTarget(options, buildId) {
 	const build = await new BuildModel(options.db, options.tables).get(buildId);
@@ -15,7 +15,6 @@ async function loadTarget(options, buildId) {
 		project
 	};
 }
-//#endregion
 export { loadTarget };
 
 //# sourceMappingURL=target.mjs.map

package/dist/capture/targets.d.mts

@@ -2,7 +2,6 @@ import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { RunnerTarget } from "../adapters/capture-target.mjs";
 import { CaptureRunner } from "../adapter/capture-runner.mjs";
-//#region src/capture/targets.d.ts
 /** Why a `reach: "url"` target is unavailable without a secret (the first words are matched by tests and docs). */
 declare const NO_SECRET_REASON = "no secret: set the server secret, it signs the Storybook URL the remote browser opens";
 /** Why it is unavailable without a confirmed public origin. */
@@ -20,6 +19,5 @@ interface TargetPrerequisites {
  * reason. `undefined` when the runner publishes no list (it offers any target).
  */
 declare function offeredTargets(runner: Pick<CaptureRunner, "metadata">, prerequisites: TargetPrerequisites): readonly RunnerTarget[] | undefined;
-//#endregion
 export { NO_ORIGIN_REASON, NO_SECRET_REASON, TargetPrerequisites, offeredTargets };
 //# sourceMappingURL=targets.d.mts.map

package/dist/capture/targets.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/capture/targets.ts
+// src/capture/targets.ts
 /** Why a `reach: "url"` target is unavailable without a secret (the first words are matched by tests and docs). */
 const NO_SECRET_REASON = "no secret: set the server secret, it signs the Storybook URL the remote browser opens";
 /** Why it is unavailable without a confirmed public origin. */
@@ -26,7 +26,6 @@ function withPrerequisites(entry, prerequisites) {
 	};
 	return entry;
 }
-//#endregion
 export { NO_ORIGIN_REASON, NO_SECRET_REASON, offeredTargets };
 
 //# sourceMappingURL=targets.mjs.map

package/dist/capture/tests.d.mts

@@ -6,7 +6,6 @@ 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>`). */
@@ -32,6 +31,5 @@ interface TestSummary {
 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

@@ -7,7 +7,7 @@ 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
+// src/capture/tests.ts
 /** Longest failure message kept (rows and logs stay bounded). */
 const ERROR_MAX = 1e3;
 /**
@@ -20,7 +20,8 @@ const ERROR_MAX = 1e3;
 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);
+	if (tests.length === 0) return await skipTests(input, tests.length);
+	if (!run) return await unsupportedTests(input, tests);
 	const results = resultsOf(tests, await execute(input, run, tests));
 	await keepResults(input, results);
 	return await reportFailures(input, results, tests);
@@ -34,6 +35,16 @@ async function skipTests(input, wanted) {
 		flaky: /* @__PURE__ */ new Set()
 	};
 }
+/** Tests were wanted and exist, but the runner cannot run them: fail loudly rather than silently. */
+async function unsupportedTests(input, tests) {
+	input.logger?.error({ tests: tests.length }, "project runs tests but the capture runner cannot run them; unsupported capability");
+	await emitAttemptLog(input.recordLog, input.logger, "error", "storybook tests unsupported", { tests: tests.length });
+	await keepResults(input, null);
+	return {
+		blocking: new Set(tests.map((test) => test.id)),
+		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));
@@ -120,7 +131,6 @@ function isTestResult(value) {
 	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

@@ -1 +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":";;;;;;;;;;;AAsCA,MAAM,YAAY;;;;;;;;AAgClB,eAAsB,gBAAgB,OAA4C;CAChF,MAAM,QAAQ,MAAM,QAAQ,WAAW,MAAM,WAAW,KAAK,IAAI,CAAC;CAClE,MAAM,MAAM,MAAM,OAAO,UAAU,KAAK,MAAM,MAAM;CACpD,IAAI,MAAM,WAAW,KAAK,CAAC,KAAK,OAAO,MAAM,UAAU,OAAO,MAAM,MAAM;CAC1E,MAAM,UAAU,UAAU,OAAO,MAAM,QAAQ,OAAO,KAAK,KAAK,CAAC;CACjE,MAAM,YAAY,OAAO,OAAO;CAChC,OAAO,MAAM,eAAe,OAAO,SAAS,KAAK;AACnD;;AAGA,eAAe,UAAU,OAAsB,QAAsC;CACnF,IAAI,SAAS,GACX,MAAM,QAAQ,KACZ,EAAE,OAAO,OAAO,GAChB,oEACF;CAEF,MAAM,YAAY,OAAO,IAAI;CAC7B,OAAO;EAAE,0BAAU,IAAI,IAAI;EAAG,uBAAO,IAAI,IAAI;CAAE;AACjD;;AAGA,eAAe,WAAW,OAA6C;CACrE,MAAM,UAAU,IAAI,IAAI,MAAM,QAAQ,QAAQ,UAAU,gBAAgB,KAAK,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,EAAE,CAAC;CAEhG,QAAO,MADa,IAAI,iBAAiB,CAAC,CAAC,cAAc,MAAM,YAAY,EAAA,CAC9D,QACV,UACC,CAAC,gBAAgB,KAAK,KAAK,EAAE,MAAM,aAAa,KAAA,KAAa,QAAQ,IAAI,MAAM,QAAQ,EAC3F;AACF;AAEA,eAAe,QACb,OACA,KACA,OACwB;CACxB,MAAM,eAAe,MAAM,MAAM,eAAe,MAAM,QAAQ,EAC5D,UAAU,eAAe,MAAM,MAAM,EACvC,CAAC;CACD,MAAM,eAAe,MAAM,WAAW,MAAM,QAAQ,QAAQ,2BAA2B,EACrF,OAAO,MAAM,OACf,CAAC;CACD,OAAO,MAAM,IAAI;EACf,SAAS,MAAM,MAAM;EACrB,cAAc,MAAM;EACpB;EACA,eAAe,MAAM,QAAQ;EAC7B,QAAQ,MAAM;EACd,GAAI,iBAAiB,KAAA,IAAY,CAAC,IAAI,EAAE,aAAa;EACrD,GAAI,MAAM,SAAS,EAAE,QAAQ,MAAM,OAAO,IAAI,CAAC;CACjD,CAAC;AACH;;AAGA,SAAS,UAAU,OAA8B,UAAgD;CAC/F,MAAM,OAAO,IAAI,IAAI,SAAS,KAAK,YAAY,CAAC,QAAQ,SAAS,OAAO,CAAC,CAAC;CAC1E,OAAO,MAAM,KAAK,SAAS;EACzB,MAAM,UAAU,KAAK,IAAI,KAAK,EAAE;EAChC,MAAM,QACJ,YAAY,KAAA,IAAY,gDAAgD,QAAQ;EAClF,MAAM,SAAS,YAAY,KAAA,KAAa,QAAQ,WAAW;EAC3D,OAAO;GACL,IAAI,KAAK;GACT,OAAO,KAAK;GACZ,MAAM,KAAK;GACX,UAAU,KAAK,YAAY;GAC3B,QAAQ,SAAS,WAAW;GAC5B,GAAI,SAAS,EAAE,OAAO,cAAc,SAAS,aAAa,CAAC,CAAC,MAAM,GAAG,SAAS,EAAE,IAAI,CAAC;GACrF,YAAY,SAAS,cAAc;EACrC;CACF,CAAC;AACH;;AAGA,eAAe,YAAY,OAAsB,SAA6C;CAC5F,IAAI,YAAY,QAAQ,CAAC,MAAM,MAAM,aAAa;CAClD,MAAM,MAAM,OAAO,eAAe,MAAM,MAAM,IAAI,OAAO;AAC3D;AAEA,eAAe,eACb,OACA,SACA,OACsB;CACtB,MAAM,SAAS,QAAQ,QAAQ,WAAW,OAAO,WAAW,QAAQ;CACpE,MAAM,aAAa,iBACjB,OACA,OAAO,KAAK,YAAY;EACtB,SAAS,OAAO;EAChB,cAAc;EACd,OAAO,OAAO,SAAS;CACzB,EAAE,CACJ;CACA,MAAM,OAAO;EAAE,UAAU,WAAW;EAAU,OAAO,WAAW;CAAM;CACtE,MAAM,SAAS;EAAE,OAAO,QAAQ;EAAQ,QAAQ,OAAO;EAAQ,OAAO,KAAK,MAAM;CAAK;CACtF,MAAM,QAAQ,KAAK,SAAS,OAAO,IAAI,UAAU;CACjD,MAAM,SAAS,MAAM,CAAC,QAAQ,0BAA0B;CACxD,MAAM,eAAe,MAAM,WAAW,MAAM,QAAQ,OAAO,4BAA4B,MAAM;CAC7F,OAAO;AACT;;AAGA,SAAgB,iBAAiB,MAA+C;CAC9E,IAAI,CAAC,MAAM,OAAO,CAAC;CACnB,IAAI;EACF,MAAM,SAAkB,KAAK,MAAM,IAAI;EACvC,OAAO,MAAM,QAAQ,MAAM,IAAI,OAAO,QAAQ,SAAS,aAAa,IAAI,CAAC,IAAI,CAAC;CAChF,QAAQ;EACN,OAAO,CAAC;CACV;AACF;;AAGA,SAAgB,eAAe,SAA6C;CAC1E,MAAM,SAAS,QAAQ,QAAQ,WAAW,OAAO,WAAW,QAAQ,CAAC,CAAC;CACtE,OAAO;EAAE,OAAO,QAAQ;EAAQ,QAAQ,QAAQ,SAAS;EAAQ;CAAO;AAC1E;AAEA,SAAS,aAAa,OAAqC;CACzD,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CACxD,MAAM,SAAS;CACf,OACE,OAAO,OAAO,UAAU,YACxB,OAAO,OAAO,YAAY,aACzB,OAAO,cAAc,YAAY,OAAO,cAAc;AAE3D"}
+{"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) return await skipTests(input, tests.length);\n  if (!run) return await unsupportedTests(input, tests);\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/** Tests were wanted and exist, but the runner cannot run them: fail loudly rather than silently. */\nasync function unsupportedTests(\n  input: RunTestsInput,\n  tests: readonly StoryEntry[],\n): Promise<TestRunSets> {\n  input.logger?.error(\n    { tests: tests.length },\n    \"project runs tests but the capture runner cannot run them; unsupported capability\",\n  );\n  await emitAttemptLog(input.recordLog, input.logger, \"error\", \"storybook tests unsupported\", {\n    tests: tests.length,\n  });\n  await keepResults(input, null);\n  return { blocking: new Set(tests.map((test) => test.id)), 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

@@ -3,13 +3,22 @@ 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
+// src/capture/token-chunks.ts
+/**
+* The project's signed URL lifetime cannot hold what the pass must capture (a configuration
+* problem): retrying or isolating stories cannot help, so the job fails once with this message.
+*/
+var SignedUrlLifetimeError = class extends Error {
+	name = "SignedUrlLifetimeError";
+};
 /** 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 requestedBudgetMs = renderBudgetMs(slice.expected, input.renderTimeoutMs);
+		const ttl = input.storybookUrl?.ttlSeconds?.(input.browser, requestedBudgetMs);
+		const budgetMs = ttl === void 0 ? requestedBudgetMs : Math.min(requestedBudgetMs, (ttl - 300) * 1e3);
 		const storybookUrl = await input.storybookUrl?.(input.browser, { budgetMs });
 		results.push(await renderWithTimeout(input.runner, {
 			...input.request,
@@ -30,8 +39,17 @@ function slicesOf(input) {
 	}];
 	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)));
+	if (ttl === void 0 || budgetSeconds + 300 <= ttl) return whole;
+	return cut(stories, counts, sliceLimit(ttl));
+}
+function sliceLimit(ttl) {
+	const limit = Math.floor((ttl - 300) * 1e3 / PER_CAPTURE_BUDGET_MS);
+	if (limit < 1) throw new SignedUrlLifetimeError("Signed Storybook URL lifetime is too short for one capture and its grace period; increase or clear the project lifetime override.");
+	return limit;
+}
+function checkedCount(count, limit) {
+	if (count > limit) throw new SignedUrlLifetimeError(`A story expands to ${count} captures, exceeding the signed URL slice limit of ${limit}; increase or clear the project lifetime override.`);
+	return count;
 }
 function cut(stories, counts, limit) {
 	const slices = [];
@@ -40,7 +58,7 @@ function cut(stories, counts, limit) {
 		expected: 0
 	};
 	for (const [index, story] of stories.entries()) {
-		const count = counts[index] ?? 0;
+		const count = checkedCount(counts[index] ?? 0, limit);
 		if (current.stories.length > 0 && current.expected + count > limit) {
 			slices.push(current);
 			current = {
@@ -68,7 +86,6 @@ function tagged(result) {
 	for (const capture of result.captures) if (result.environment) capture.environment ??= result.environment;
 	return result.captures;
 }
-//#endregion
-export { renderInSlices };
+export { SignedUrlLifetimeError, renderInSlices };
 
 //# sourceMappingURL=token-chunks.mjs.map

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

@@ -1 +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"}
+{"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 { PER_CAPTURE_BUDGET_MS, STORYBOOK_URL_TTL_GRACE } 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 limits each call; a signed URL may require a shorter timeout. */\n  renderTimeoutMs: number | undefined;\n}\n\n/**\n * The project's signed URL lifetime cannot hold what the pass must capture (a configuration\n * problem): retrying or isolating stories cannot help, so the job fails once with this message.\n */\nexport class SignedUrlLifetimeError extends Error {\n  override readonly name = \"SignedUrlLifetimeError\";\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 requestedBudgetMs = renderBudgetMs(slice.expected, input.renderTimeoutMs);\n    const ttl = input.storybookUrl?.ttlSeconds?.(input.browser, requestedBudgetMs);\n    const budgetMs =\n      ttl === undefined\n        ? requestedBudgetMs\n        : Math.min(requestedBudgetMs, (ttl - STORYBOOK_URL_TTL_GRACE) * 1000);\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 (ttl === undefined || budgetSeconds + STORYBOOK_URL_TTL_GRACE <= ttl) {\n    return whole;\n  }\n  return cut(stories, counts, sliceLimit(ttl));\n}\n\nfunction sliceLimit(ttl: number): number {\n  const limit = Math.floor(((ttl - STORYBOOK_URL_TTL_GRACE) * 1000) / PER_CAPTURE_BUDGET_MS);\n  if (limit < 1) {\n    throw new SignedUrlLifetimeError(\n      \"Signed Storybook URL lifetime is too short for one capture and its grace period; increase or clear the project lifetime override.\",\n    );\n  }\n  return limit;\n}\n\nfunction checkedCount(count: number, limit: number): number {\n  if (count > limit) {\n    throw new SignedUrlLifetimeError(\n      `A story expands to ${count} captures, exceeding the signed URL slice limit of ${limit}; increase or clear the project lifetime override.`,\n    );\n  }\n  return count;\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 = checkedCount(counts[index] ?? 0, limit);\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":";;;;;;;;;;AA+BA,IAAa,yBAAb,cAA4C,MAAM;CAChD,OAAyB;AAC3B;;AAGA,eAAsB,eAAe,OAA0C;CAC7E,MAAM,SAAS,SAAS,KAAK;CAC7B,MAAM,UAA0B,CAAC;CACjC,KAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,oBAAoB,eAAe,MAAM,UAAU,MAAM,eAAe;EAC9E,MAAM,MAAM,MAAM,cAAc,aAAa,MAAM,SAAS,iBAAiB;EAC7E,MAAM,WACJ,QAAQ,KAAA,IACJ,oBACA,KAAK,IAAI,oBAAoB,MAAA,OAAiC,GAAI;EAExE,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,IAAI,QAAQ,KAAA,KAAa,gBAAA,OAA2C,KAClE,OAAO;CAET,OAAO,IAAI,SAAS,QAAQ,WAAW,GAAG,CAAC;AAC7C;AAEA,SAAS,WAAW,KAAqB;CACvC,MAAM,QAAQ,KAAK,OAAQ,MAAA,OAAiC,MAAQ,qBAAqB;CACzF,IAAI,QAAQ,GACV,MAAM,IAAI,uBACR,mIACF;CAEF,OAAO;AACT;AAEA,SAAS,aAAa,OAAe,OAAuB;CAC1D,IAAI,QAAQ,OACV,MAAM,IAAI,uBACR,sBAAsB,MAAM,qDAAqD,MAAM,mDACzF;CAEF,OAAO;AACT;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,aAAa,OAAO,UAAU,GAAG,KAAK;EACpD,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

@@ -5,6 +5,7 @@ import { LeaseRenewal, PollableCaptureQueue, PollableJob } from "./adapter/captu
 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 { DEFAULT_IGNORE_SELECTORS, IgnoreSelectorList, MAX_IGNORE_SELECTORS, cleanIgnoreSelectors, declaredIgnoreSelectors, ignoreStylesheet, isSafeIgnoreSelector } from "./capture/ignore-regions.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";
@@ -50,6 +51,7 @@ 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 { ZipInvalidError } from "./capture/publish/invalid-zip.mjs";
 import "./capture/publish/index.mjs";
 import { Catalog, CatalogComponent, CatalogEntry } from "./capture/catalog/types.mjs";
 import { CatalogDeps, catalogueBuild, readCatalog } from "./capture/catalog/catalogue.mjs";
@@ -57,11 +59,12 @@ import { CatalogLoader, CatalogLoaderOptions, DEFAULT_CATALOG_CACHE_SIZE, create
 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 { readPublishedFile, readPublishedFileInfo } 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 };
+import { ComparisonReference, isComparisonImagePath, parseComparisonReference } from "./capture/comparison-reference.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 ComparisonReference, 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_IGNORE_SELECTORS, 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 IgnoreSelectorList, 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_IGNORE_SELECTORS, 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, ZipInvalidError, ZipLimitError, assertBrowserCount, assertSupportedBrowsers, axeInjectionScript, backoffDelayMs, buildFingerprint, buildGlobalsParam, buildScratchDir, canForkCaptureChild, captureDispatchDeps, catalogPresence, catalogueBuild, changedFields, cleanIgnoreSelectors, componentBuildHistory, createBuildStatePublisher, createCaptureConsumer, createCaptureHandler, createCatalogHook, createCatalogLoader, createDatabaseCaptureQueue, createDispatchJob, createForkedCaptureHandler, createNotifyEnqueuer, createNotifyHandler, createPublishCompleter, createPublishHandler, decideCaptureProcess, declaredIgnoreSelectors, deliverBuildState, diffEntries, executeCaptureJob, extractStorybookToScratch, extractZipStream, extractionLimitsOf, failCrashedCapture, filterModes, fingerprintHash, forkCaptureChild, getScreenshotPlan, groupComponents, hashEntries, idleDelayMs, ignoreStylesheet, inPageReadA11yParameters, inPageRunAxe, isComparisonImagePath, isDisabledStory, isFastEmptyPoll, isFinalAttempt, isFlakyStory, isSafeIgnoreSelector, keepJobLease, listTargets, loadAxeSource, loadBuild, mapAxeViolations, mergeParameters, modeSlug, nextPollDelay, notifyExhausted, offeredTargets, parseBrowsers, parseComparisonReference, parseFingerprint, parseModesAllowlist, parseStorybookIndex, parseStorybookIndexText, parseTestResults, persistCapture, persistStorybookStatics, primaryTargetOf, publishRoute, publishStoredZip, publishVerdict, publishingOf, readCatalog, readPublishedFile, readPublishedFileInfo, 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

@@ -4,14 +4,17 @@ 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 { DEFAULT_IGNORE_SELECTORS, MAX_IGNORE_SELECTORS, cleanIgnoreSelectors, declaredIgnoreSelectors, ignoreStylesheet, isSafeIgnoreSelector } from "./capture/ignore-regions.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 { isComparisonImagePath, parseComparisonReference } from "./capture/comparison-reference.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 { ZipInvalidError } from "./capture/publish/invalid-zip.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";
@@ -50,10 +53,10 @@ 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 { readPublishedFile, readPublishedFileInfo } 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 };
+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_IGNORE_SELECTORS, 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_IGNORE_SELECTORS, 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, ZipInvalidError, ZipLimitError, assertBrowserCount, assertSupportedBrowsers, axeInjectionScript, backoffDelayMs, buildFingerprint, buildGlobalsParam, buildScratchDir, canForkCaptureChild, captureDispatchDeps, catalogPresence, catalogueBuild, changedFields, cleanIgnoreSelectors, componentBuildHistory, createBuildStatePublisher, createCaptureConsumer, createCaptureHandler, createCatalogHook, createCatalogLoader, createDatabaseCaptureQueue, createDispatchJob, createForkedCaptureHandler, createNotifyEnqueuer, createNotifyHandler, createPublishCompleter, createPublishHandler, decideCaptureProcess, declaredIgnoreSelectors, deliverBuildState, diffEntries, executeCaptureJob, extractStorybookToScratch, extractZipStream, extractionLimitsOf, failCrashedCapture, filterModes, fingerprintHash, forkCaptureChild, getScreenshotPlan, groupComponents, hashEntries, idleDelayMs, ignoreStylesheet, inPageReadA11yParameters, inPageRunAxe, isComparisonImagePath, isDisabledStory, isFastEmptyPoll, isFinalAttempt, isFlakyStory, isSafeIgnoreSelector, keepJobLease, listTargets, loadAxeSource, loadBuild, mapAxeViolations, mergeParameters, modeSlug, nextPollDelay, notifyExhausted, offeredTargets, parseBrowsers, parseComparisonReference, parseFingerprint, parseModesAllowlist, parseStorybookIndex, parseStorybookIndexText, parseTestResults, persistCapture, persistStorybookStatics, primaryTargetOf, publishRoute, publishStoredZip, publishVerdict, publishingOf, readCatalog, readPublishedFile, readPublishedFileInfo, 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

@@ -13,7 +13,6 @@ import { ALLOW_SERVERLESS_ENV, assertServerless, isServerlessHost } from "./serv
 import { AdapterCategory } from "./adapter/metadata.mjs";
 import { z } from "zod";
 import { Logger } from "pino";
-//#region src/config.d.ts
 /** Brand color theme for the server-rendered UI. */
 interface BrandTheme {
   accent: string;
@@ -101,6 +100,17 @@ interface NotificationsConfig {
   footerText?: string;
   slackUsername?: string;
 }
+/** Longest browser-private freshness a signed capture asset may be given, in seconds (1 hour). */
+declare const MAX_CAPTURE_ASSET_CACHE_SECONDS = 3600;
+/** Signed Storybook asset serving for remote capture browsers (ADR 0007, decision 5). */
+interface CaptureAssetsConfig {
+  /**
+   * Opt-in browser-private freshness of capture-scoped signed assets, in whole seconds from 0 to
+   * {@link MAX_CAPTURE_ASSET_CACHE_SECONDS}. 0 (default) keeps every signed answer `no-store`. A
+   * positive value is a cap: the answer's `max-age` never exceeds the grant's remaining lifetime.
+   */
+  cacheMaxAgeSeconds?: number;
+}
 /** Shelf-level configuration (validated by {@link shelfConfigSchema}). */
 interface ShelfConfig {
   secret?: string;
@@ -145,6 +155,10 @@ interface ShelfConfig {
    * Opt-in, off by default — some deployments prefer no timing headers.
    */
   serverTiming?: boolean;
+  /** Persist gzip variants for published Storybook files (default off). */
+  publishedCompression?: boolean;
+  /** Signed Storybook asset serving for remote capture browsers; see {@link CaptureAssetsConfig}. */
+  captureAssets?: CaptureAssetsConfig;
   /**
    * 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
@@ -304,6 +318,5 @@ interface ObservabilityHandle {
   /** Flush exporters and release SDK resources. Must be idempotent. */
   shutdown(): Promise<void>;
 }
-//#endregion
-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 };
+export { ALLOW_SERVERLESS_ENV, AdapterSnapshot, AuthUiConfig, BrandTheme, CaptureAssetsConfig, DEFAULT_MAX_UPLOAD_BYTES, DEFAULT_SCRATCH_DIR, MAX_CAPTURE_ASSET_CACHE_SECONDS, NotificationsConfig, ObservabilityHandle, ShelfCompareOptions, ShelfConfig, ShelfImagesOptions, ShelfNotificationsOptions, ShelfOptions, ShelfTestingOptions, ShelfViewport, UIConfig, assertServerless, isServerlessHost, notificationsConfigSchema, resolveShelfOptions, shelfConfigSchema, uiConfigSchema, validateConfig, validateUiConfig };
 //# sourceMappingURL=config.d.mts.map

package/dist/config.mjs

@@ -4,9 +4,11 @@ import.meta.url;
 import { DEFAULT_SCRATCH_DIR, resolveShelfOptions } from "./options.mjs";
 import { ALLOW_SERVERLESS_ENV, assertServerless, isServerlessHost } from "./serverless.mjs";
 import { z } from "zod";
-//#region src/config.ts
+// src/config.ts
 /** Default cap for a single Storybook zip upload (1 GiB). */
 const DEFAULT_MAX_UPLOAD_BYTES = 1073741824;
+/** Longest browser-private freshness a signed capture asset may be given, in seconds (1 hour). */
+const MAX_CAPTURE_ASSET_CACHE_SECONDS = 3600;
 const viewportSchema = z.object({
 	name: z.string().min(1),
 	width: z.number().int().positive(),
@@ -85,6 +87,8 @@ const shelfConfigSchema = z.object({
 	branchGcIntervalMs: z.number().int().positive().optional(),
 	maxUploadBytes: z.number().int().positive().optional(),
 	serverTiming: z.boolean().optional(),
+	publishedCompression: z.boolean().optional(),
+	captureAssets: z.object({ cacheMaxAgeSeconds: z.number().int().min(0).max(MAX_CAPTURE_ASSET_CACHE_SECONDS).optional() }).strict().optional(),
 	maxInlineUnzipSize: z.number().int().min(0).optional(),
 	maxZipEntries: z.number().int().positive().optional(),
 	maxUnzippedBytes: z.number().int().positive().optional(),
@@ -139,7 +143,6 @@ function validateUiConfig(config) {
 	}
 	return result.data;
 }
-//#endregion
-export { ALLOW_SERVERLESS_ENV, DEFAULT_MAX_UPLOAD_BYTES, DEFAULT_SCRATCH_DIR, assertServerless, isServerlessHost, notificationsConfigSchema, resolveShelfOptions, shelfConfigSchema, uiConfigSchema, validateConfig, validateUiConfig };
+export { ALLOW_SERVERLESS_ENV, DEFAULT_MAX_UPLOAD_BYTES, DEFAULT_SCRATCH_DIR, MAX_CAPTURE_ASSET_CACHE_SECONDS, assertServerless, isServerlessHost, notificationsConfigSchema, resolveShelfOptions, shelfConfigSchema, uiConfigSchema, validateConfig, validateUiConfig };
 
 //# sourceMappingURL=config.mjs.map