@storyshelf/core 0.6.2 → 0.7.0

package/dist/capture/catalog/components.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.mjs","names":[],"sources":["../../../src/capture/catalog/components.ts"],"sourcesContent":["/** Catalog entries grouped into components, hashed, and compared between builds. */\nimport { createHash } from \"node:crypto\";\nimport type { BuildComponentInput } from \"../../models/build-component.ts\";\nimport type { CatalogComponent, CatalogEntry } from \"./types.ts\";\n\n/** Group entries by story file (entries without one by title), ordered by title then file. */\nexport function groupComponents(entries: readonly CatalogEntry[]): CatalogComponent[] {\n  const groups = Map.groupBy(entries, (entry) => entry.importPath || `title:${entry.title}`);\n  return [...groups.values()]\n    .map((group): CatalogComponent => {\n      const [first] = group;\n      return {\n        importPath: first?.importPath ?? \"\",\n        title: first?.title ?? \"\",\n        storyCount: group.filter((entry) => entry.type === \"story\").length,\n        hash: hashEntries(group),\n        entries: group,\n      };\n    })\n    .toSorted((a, b) => a.title.localeCompare(b.title) || a.importPath.localeCompare(b.importPath));\n}\n\n/** What `build_components` stores of a component. */\nexport function toBuildComponent(component: CatalogComponent): BuildComponentInput {\n  const { importPath, title, storyCount, hash } = component;\n  return { importPath, title, storyCount, hash };\n}\n\n/** SHA-256 over the entries' id, name, type and title, in id order: equal sets hash equal. */\nexport function hashEntries(entries: readonly CatalogEntry[]): string {\n  const lines = entries\n    .map((entry) => [entry.id, entry.name, entry.type, entry.title].join(\"\\t\"))\n    .toSorted();\n  return createHash(\"sha256\").update(lines.join(\"\\n\")).digest(\"hex\");\n}\n\n/** How one component's entries differ between two builds. */\nexport interface EntryChanges {\n  added: number;\n  removed: number;\n  /** Same id, new display name. */\n  renamed: number;\n}\n\n/** Entries added, removed and renamed from `before` to `after` (matched by entry id). */\nexport function diffEntries(\n  before: readonly CatalogEntry[],\n  after: readonly CatalogEntry[],\n): EntryChanges {\n  const was = new Map(before.map((entry) => [entry.id, entry] as const));\n  const now = new Map(after.map((entry) => [entry.id, entry] as const));\n  let renamed = 0;\n  for (const [id, entry] of now) {\n    if (was.has(id) && was.get(id)?.name !== entry.name) {\n      renamed += 1;\n    }\n  }\n  return {\n    added: [...now.keys()].filter((id) => !was.has(id)).length,\n    removed: [...was.keys()].filter((id) => !now.has(id)).length,\n    renamed,\n  };\n}\n"],"mappings":";;;;;;;AAMA,SAAgB,gBAAgB,SAAsD;CAEpF,OAAO,CAAC,GADO,IAAI,QAAQ,UAAU,UAAU,MAAM,cAAc,SAAS,MAAM,OAClE,CAAC,CAAC,OAAO,CAAC,CAAC,CACxB,KAAK,UAA4B;EAChC,MAAM,CAAC,SAAS;EAChB,OAAO;GACL,YAAY,OAAO,cAAc;GACjC,OAAO,OAAO,SAAS;GACvB,YAAY,MAAM,QAAQ,UAAU,MAAM,SAAS,OAAO,CAAC,CAAC;GAC5D,MAAM,YAAY,KAAK;GACvB,SAAS;EACX;CACF,CAAC,CAAC,CACD,UAAU,GAAG,MAAM,EAAE,MAAM,cAAc,EAAE,KAAK,KAAK,EAAE,WAAW,cAAc,EAAE,UAAU,CAAC;AAClG;;AAGA,SAAgB,iBAAiB,WAAkD;CACjF,MAAM,EAAE,YAAY,OAAO,YAAY,SAAS;CAChD,OAAO;EAAE;EAAY;EAAO;EAAY;CAAK;AAC/C;;AAGA,SAAgB,YAAY,SAA0C;CACpE,MAAM,QAAQ,QACX,KAAK,UAAU;EAAC,MAAM;EAAI,MAAM;EAAM,MAAM;EAAM,MAAM;CAAK,CAAC,CAAC,KAAK,GAAI,CAAC,CAAC,CAC1E,SAAS;CACZ,OAAO,WAAW,QAAQ,CAAC,CAAC,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,KAAK;AACnE;;AAWA,SAAgB,YACd,QACA,OACc;CACd,MAAM,MAAM,IAAI,IAAI,OAAO,KAAK,UAAU,CAAC,MAAM,IAAI,KAAK,CAAU,CAAC;CACrE,MAAM,MAAM,IAAI,IAAI,MAAM,KAAK,UAAU,CAAC,MAAM,IAAI,KAAK,CAAU,CAAC;CACpE,IAAI,UAAU;CACd,KAAK,MAAM,CAAC,IAAI,UAAU,KACxB,IAAI,IAAI,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,CAAC,EAAE,SAAS,MAAM,MAC7C,WAAW;CAGf,OAAO;EACL,OAAO,CAAC,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,QAAQ,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;EACpD,SAAS,CAAC,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,QAAQ,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;EACtD;CACF;AACF"}

package/dist/capture/catalog/history.d.mts

@@ -0,0 +1,30 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Build } from "../../schema/build.mjs";
+import { BuildComponent } from "../../schema/build-component.mjs";
+import { ComponentPresence } from "../../models/component.mjs";
+//#region src/capture/catalog/history.d.ts
+/** How a build's version of a component compares with the build before it on the same branch. */
+type ComponentChange = "new" | "changed" | "unchanged";
+/** One build's row of a component's history. */
+interface ComponentBuildRow {
+  build: Build;
+  component: BuildComponent;
+  change: ComponentChange;
+  /** The same component in the build before on the branch; null when this is its first. */
+  previous: BuildComponent | null;
+}
+/**
+ * Component history, newest build first. `rows` are the component's `build_components` rows;
+ * a row whose build is missing is skipped. The build before is the next older one on the same
+ * branch, so a feature branch compares with itself rather than with an unrelated default build.
+ */
+declare function componentBuildHistory(rows: readonly BuildComponent[], builds: readonly Build[]): ComponentBuildRow[];
+/**
+ * Where a component stands against the project's latest build. `latest` holds that build's
+ * component rows, or null when it has no catalog (the answer is then unknown, never "deleted").
+ */
+declare function catalogPresence(history: readonly ComponentBuildRow[], importPath: string, latest: readonly BuildComponent[] | null): ComponentPresence;
+//#endregion
+export { ComponentBuildRow, ComponentChange, catalogPresence, componentBuildHistory };
+//# sourceMappingURL=history.d.mts.map

package/dist/capture/catalog/history.mjs

@@ -0,0 +1,51 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/capture/catalog/history.ts
+/**
+* Component history, newest build first. `rows` are the component's `build_components` rows;
+* a row whose build is missing is skipped. The build before is the next older one on the same
+* branch, so a feature branch compares with itself rather than with an unrelated default build.
+*/
+function componentBuildHistory(rows, builds) {
+	const byId = new Map(builds.map((build) => [build.id, build]));
+	const known = rows.flatMap((component) => {
+		const build = byId.get(component.buildId);
+		return build ? [{
+			build,
+			component
+		}] : [];
+	}).toSorted((a, b) => b.build.createdAt.localeCompare(a.build.createdAt));
+	return known.map((entry, index) => {
+		const previous = known.slice(index + 1).find((older) => older.build.gitBranch === entry.build.gitBranch)?.component ?? null;
+		const change = previous ? previous.hash === entry.component.hash ? "unchanged" : "changed" : "new";
+		return {
+			build: entry.build,
+			component: entry.component,
+			change,
+			previous
+		};
+	});
+}
+/**
+* Where a component stands against the project's latest build. `latest` holds that build's
+* component rows, or null when it has no catalog (the answer is then unknown, never "deleted").
+*/
+function catalogPresence(history, importPath, latest) {
+	const newest = history[0];
+	if (!latest || !newest) return { kind: "unknown" };
+	if (latest.some((row) => row.importPath === importPath)) return { kind: "present" };
+	const moved = latest.find((row) => row.title === newest.component.title && row.importPath !== "");
+	return moved ? {
+		kind: "moved",
+		to: moved.importPath,
+		title: moved.title
+	} : {
+		kind: "deleted",
+		lastSeen: newest.build
+	};
+}
+//#endregion
+export { catalogPresence, componentBuildHistory };
+
+//# sourceMappingURL=history.mjs.map

package/dist/capture/catalog/history.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.mjs","names":[],"sources":["../../../src/capture/catalog/history.ts"],"sourcesContent":["/** A component across builds: which builds hold it, whether its stories changed, and where it went. */\nimport type { ComponentPresence } from \"../../models/component.ts\";\nimport type { BuildComponent } from \"../../schema/build-component.ts\";\nimport type { Build } from \"../../schema/build.ts\";\n\n/** How a build's version of a component compares with the build before it on the same branch. */\nexport type ComponentChange = \"new\" | \"changed\" | \"unchanged\";\n\n/** One build's row of a component's history. */\nexport interface ComponentBuildRow {\n  build: Build;\n  component: BuildComponent;\n  change: ComponentChange;\n  /** The same component in the build before on the branch; null when this is its first. */\n  previous: BuildComponent | null;\n}\n\n/**\n * Component history, newest build first. `rows` are the component's `build_components` rows;\n * a row whose build is missing is skipped. The build before is the next older one on the same\n * branch, so a feature branch compares with itself rather than with an unrelated default build.\n */\nexport function componentBuildHistory(\n  rows: readonly BuildComponent[],\n  builds: readonly Build[],\n): ComponentBuildRow[] {\n  const byId = new Map(builds.map((build) => [build.id, build] as const));\n  const known = rows\n    .flatMap((component) => {\n      const build = byId.get(component.buildId);\n      return build ? [{ build, component }] : [];\n    })\n    .toSorted((a, b) => b.build.createdAt.localeCompare(a.build.createdAt));\n  return known.map((entry, index) => {\n    const previous =\n      known.slice(index + 1).find((older) => older.build.gitBranch === entry.build.gitBranch)\n        ?.component ?? null;\n    const change: ComponentChange = previous\n      ? previous.hash === entry.component.hash\n        ? \"unchanged\"\n        : \"changed\"\n      : \"new\";\n    return { build: entry.build, component: entry.component, change, previous };\n  });\n}\n\n/**\n * Where a component stands against the project's latest build. `latest` holds that build's\n * component rows, or null when it has no catalog (the answer is then unknown, never \"deleted\").\n */\nexport function catalogPresence(\n  history: readonly ComponentBuildRow[],\n  importPath: string,\n  latest: readonly BuildComponent[] | null,\n): ComponentPresence {\n  const newest = history[0];\n  if (!latest || !newest) {\n    return { kind: \"unknown\" };\n  }\n  if (latest.some((row) => row.importPath === importPath)) {\n    return { kind: \"present\" };\n  }\n  const moved = latest.find((row) => row.title === newest.component.title && row.importPath !== \"\");\n  return moved\n    ? { kind: \"moved\", to: moved.importPath, title: moved.title }\n    : { kind: \"deleted\", lastSeen: newest.build };\n}\n"],"mappings":";;;;;;;;;AAsBA,SAAgB,sBACd,MACA,QACqB;CACrB,MAAM,OAAO,IAAI,IAAI,OAAO,KAAK,UAAU,CAAC,MAAM,IAAI,KAAK,CAAU,CAAC;CACtE,MAAM,QAAQ,KACX,SAAS,cAAc;EACtB,MAAM,QAAQ,KAAK,IAAI,UAAU,OAAO;EACxC,OAAO,QAAQ,CAAC;GAAE;GAAO;EAAU,CAAC,IAAI,CAAC;CAC3C,CAAC,CAAC,CACD,UAAU,GAAG,MAAM,EAAE,MAAM,UAAU,cAAc,EAAE,MAAM,SAAS,CAAC;CACxE,OAAO,MAAM,KAAK,OAAO,UAAU;EACjC,MAAM,WACJ,MAAM,MAAM,QAAQ,CAAC,CAAC,CAAC,MAAM,UAAU,MAAM,MAAM,cAAc,MAAM,MAAM,SAAS,CAAC,EACnF,aAAa;EACnB,MAAM,SAA0B,WAC5B,SAAS,SAAS,MAAM,UAAU,OAChC,cACA,YACF;EACJ,OAAO;GAAE,OAAO,MAAM;GAAO,WAAW,MAAM;GAAW;GAAQ;EAAS;CAC5E,CAAC;AACH;;;;;AAMA,SAAgB,gBACd,SACA,YACA,QACmB;CACnB,MAAM,SAAS,QAAQ;CACvB,IAAI,CAAC,UAAU,CAAC,QACd,OAAO,EAAE,MAAM,UAAU;CAE3B,IAAI,OAAO,MAAM,QAAQ,IAAI,eAAe,UAAU,GACpD,OAAO,EAAE,MAAM,UAAU;CAE3B,MAAM,QAAQ,OAAO,MAAM,QAAQ,IAAI,UAAU,OAAO,UAAU,SAAS,IAAI,eAAe,EAAE;CAChG,OAAO,QACH;EAAE,MAAM;EAAS,IAAI,MAAM;EAAY,OAAO,MAAM;CAAM,IAC1D;EAAE,MAAM;EAAW,UAAU,OAAO;CAAM;AAChD"}

package/dist/capture/catalog/hook.d.mts

@@ -0,0 +1,14 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { AfterPublishHook } from "../publish/complete.mjs";
+import { CatalogLoader } from "./load.mjs";
+//#region src/capture/catalog/hook.d.ts
+/**
+ * Catalogue every build that published successfully, whatever its verdict and with `testing` on or
+ * off. A failed publish writes nothing. A build with no readable index is logged and left for the
+ * lazy loader, which tries again on first view.
+ */
+declare function createCatalogHook(loader: CatalogLoader): AfterPublishHook;
+//#endregion
+export { createCatalogHook };
+//# sourceMappingURL=hook.d.mts.map

package/dist/capture/catalog/hook.mjs

@@ -0,0 +1,19 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/capture/catalog/hook.ts
+/**
+* Catalogue every build that published successfully, whatever its verdict and with `testing` on or
+* off. A failed publish writes nothing. A build with no readable index is logged and left for the
+* lazy loader, which tries again on first view.
+*/
+function createCatalogHook(loader) {
+	return async ({ build, project, outcome, logger }) => {
+		if (!outcome.ok) return;
+		if (!await loader.refresh(project.id, build.id)) logger.warn("published build has no readable Storybook index; no catalog written");
+	};
+}
+//#endregion
+export { createCatalogHook };
+
+//# sourceMappingURL=hook.mjs.map

package/dist/capture/catalog/hook.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.mjs","names":[],"sources":["../../../src/capture/catalog/hook.ts"],"sourcesContent":["/** The `afterPublish` hook that catalogues a build the moment its publishing succeeds. */\nimport type { AfterPublishHook } from \"../publish/complete.ts\";\nimport type { CatalogLoader } from \"./load.ts\";\n\n/**\n * Catalogue every build that published successfully, whatever its verdict and with `testing` on or\n * off. A failed publish writes nothing. A build with no readable index is logged and left for the\n * lazy loader, which tries again on first view.\n */\nexport function createCatalogHook(loader: CatalogLoader): AfterPublishHook {\n  return async ({ build, project, outcome, logger }) => {\n    if (!outcome.ok) {\n      return;\n    }\n    const catalog = await loader.refresh(project.id, build.id);\n    if (!catalog) {\n      logger.warn(\"published build has no readable Storybook index; no catalog written\");\n    }\n  };\n}\n"],"mappings":";;;;;;;;;AASA,SAAgB,kBAAkB,QAAyC;CACzE,OAAO,OAAO,EAAE,OAAO,SAAS,SAAS,aAAa;EACpD,IAAI,CAAC,QAAQ,IACX;EAGF,IAAI,CAAC,MADiB,OAAO,QAAQ,QAAQ,IAAI,MAAM,EAAE,GAEvD,OAAO,KAAK,qEAAqE;CAErF;AACF"}

package/dist/capture/catalog/index.d.mts

@@ -0,0 +1,11 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Catalog, CatalogComponent, CatalogEntry } from "./types.mjs";
+import { CatalogDeps, catalogueBuild, readCatalog } from "./catalogue.mjs";
+import { CatalogLoader, CatalogLoaderOptions, DEFAULT_CATALOG_CACHE_SIZE, createCatalogLoader } from "./load.mjs";
+import { createCatalogHook } from "./hook.mjs";
+import { EntryChanges, diffEntries, groupComponents, hashEntries, toBuildComponent } from "./components.mjs";
+import { parseStorybookIndex, parseStorybookIndexText } from "./parse.mjs";
+import { readPublishedFile } from "./read.mjs";
+import { ComponentBuildRow, ComponentChange, catalogPresence, componentBuildHistory } from "./history.mjs";
+export { type Catalog, type CatalogComponent, type CatalogDeps, type CatalogEntry, type CatalogLoader, type CatalogLoaderOptions, type ComponentBuildRow, type ComponentChange, DEFAULT_CATALOG_CACHE_SIZE, type EntryChanges, catalogPresence, catalogueBuild, componentBuildHistory, createCatalogHook, createCatalogLoader, diffEntries, groupComponents, hashEntries, parseStorybookIndex, parseStorybookIndexText, readCatalog, readPublishedFile, toBuildComponent };

package/dist/capture/catalog/load.d.mts

@@ -0,0 +1,26 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Logger } from "../../logger.mjs";
+import { Catalog } from "./types.mjs";
+import { CatalogDeps } from "./catalogue.mjs";
+//#region src/capture/catalog/load.d.ts
+/** Reads catalogs; one per app, so the cache is shared by every request. */
+interface CatalogLoader {
+  /** The build's catalog, or null when it has no catalog and no readable index. */
+  load(projectId: string, buildId: string): Promise<Catalog | null>;
+  /** Catalogue the build again from its statics (a publish ended) and cache the result. */
+  refresh(projectId: string, buildId: string): Promise<Catalog | null>;
+}
+/** Catalogs kept in memory by default. */
+declare const DEFAULT_CATALOG_CACHE_SIZE = 32;
+/** What {@link createCatalogLoader} needs. */
+interface CatalogLoaderOptions extends CatalogDeps {
+  /** Catalogs kept in memory (least recently used leave first). */
+  cacheSize?: number;
+  logger?: Logger;
+}
+/** A loader over `options.db` and `options.storage`. */
+declare function createCatalogLoader(options: CatalogLoaderOptions): CatalogLoader;
+//#endregion
+export { CatalogLoader, CatalogLoaderOptions, DEFAULT_CATALOG_CACHE_SIZE, createCatalogLoader };
+//# sourceMappingURL=load.d.mts.map

package/dist/capture/catalog/load.mjs

@@ -0,0 +1,49 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { catalogueBuild, readCatalog } from "./catalogue.mjs";
+//#region src/capture/catalog/load.ts
+/** Catalogs kept in memory by default. */
+const DEFAULT_CATALOG_CACHE_SIZE = 32;
+/** A loader over `options.db` and `options.storage`. */
+function createCatalogLoader(options) {
+	const limit = Math.max(1, options.cacheSize ?? 32);
+	const cache = /* @__PURE__ */ new Map();
+	const inflight = /* @__PURE__ */ new Map();
+	const remember = (buildId, catalog) => {
+		cache.delete(buildId);
+		cache.set(buildId, catalog);
+		const oldest = cache.keys().next().value;
+		if (cache.size > limit && oldest !== void 0) cache.delete(oldest);
+		return catalog;
+	};
+	const fetchCatalog = async (projectId, buildId) => {
+		const stored = await readCatalog(options.storage, projectId, buildId);
+		if (stored) return stored;
+		options.logger?.info({ buildId }, "cataloguing a build published before the catalog");
+		return await catalogueBuild(options, projectId, buildId);
+	};
+	return {
+		load: async (projectId, buildId) => {
+			const hit = cache.get(buildId);
+			if (hit) return remember(buildId, hit);
+			const pending = inflight.get(buildId) ?? fetchCatalog(projectId, buildId);
+			inflight.set(buildId, pending);
+			try {
+				const catalog = await pending;
+				return catalog ? remember(buildId, catalog) : null;
+			} finally {
+				inflight.delete(buildId);
+			}
+		},
+		refresh: async (projectId, buildId) => {
+			cache.delete(buildId);
+			const catalog = await catalogueBuild(options, projectId, buildId);
+			return catalog ? remember(buildId, catalog) : null;
+		}
+	};
+}
+//#endregion
+export { DEFAULT_CATALOG_CACHE_SIZE, createCatalogLoader };
+
+//# sourceMappingURL=load.mjs.map

package/dist/capture/catalog/load.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.mjs","names":[],"sources":["../../../src/capture/catalog/load.ts"],"sourcesContent":["/**\n * The catalog loader: a build's catalog from `catalog.json`, kept in a small in-process LRU cache\n * by build id; a build that has none (published before the catalog existed) is catalogued on first\n * view from its persisted statics (ADR 0006, decision 9).\n */\nimport type { Logger } from \"../../logger.ts\";\nimport { catalogueBuild, readCatalog, type CatalogDeps } from \"./catalogue.ts\";\nimport type { Catalog } from \"./types.ts\";\n\n/** Reads catalogs; one per app, so the cache is shared by every request. */\nexport interface CatalogLoader {\n  /** The build's catalog, or null when it has no catalog and no readable index. */\n  load(projectId: string, buildId: string): Promise<Catalog | null>;\n  /** Catalogue the build again from its statics (a publish ended) and cache the result. */\n  refresh(projectId: string, buildId: string): Promise<Catalog | null>;\n}\n\n/** Catalogs kept in memory by default. */\nexport const DEFAULT_CATALOG_CACHE_SIZE = 32;\n\n/** What {@link createCatalogLoader} needs. */\nexport interface CatalogLoaderOptions extends CatalogDeps {\n  /** Catalogs kept in memory (least recently used leave first). */\n  cacheSize?: number;\n  logger?: Logger;\n}\n\n/** A loader over `options.db` and `options.storage`. */\nexport function createCatalogLoader(options: CatalogLoaderOptions): CatalogLoader {\n  const limit = Math.max(1, options.cacheSize ?? DEFAULT_CATALOG_CACHE_SIZE);\n  const cache = new Map<string, Catalog>();\n  const inflight = new Map<string, Promise<Catalog | null>>();\n  const remember = (buildId: string, catalog: Catalog): Catalog => {\n    cache.delete(buildId);\n    cache.set(buildId, catalog);\n    const oldest = cache.keys().next().value;\n    if (cache.size > limit && oldest !== undefined) {\n      cache.delete(oldest);\n    }\n    return catalog;\n  };\n  const fetchCatalog = async (projectId: string, buildId: string): Promise<Catalog | null> => {\n    const stored = await readCatalog(options.storage, projectId, buildId);\n    if (stored) {\n      return stored;\n    }\n    options.logger?.info({ buildId }, \"cataloguing a build published before the catalog\");\n    return await catalogueBuild(options, projectId, buildId);\n  };\n  return {\n    load: async (projectId, buildId) => {\n      const hit = cache.get(buildId);\n      if (hit) {\n        return remember(buildId, hit);\n      }\n      const pending = inflight.get(buildId) ?? fetchCatalog(projectId, buildId);\n      inflight.set(buildId, pending);\n      try {\n        const catalog = await pending;\n        return catalog ? remember(buildId, catalog) : null;\n      } finally {\n        inflight.delete(buildId);\n      }\n    },\n    refresh: async (projectId, buildId) => {\n      cache.delete(buildId);\n      const catalog = await catalogueBuild(options, projectId, buildId);\n      return catalog ? remember(buildId, catalog) : null;\n    },\n  };\n}\n"],"mappings":";;;;;;AAkBA,MAAa,6BAA6B;;AAU1C,SAAgB,oBAAoB,SAA8C;CAChF,MAAM,QAAQ,KAAK,IAAI,GAAG,QAAQ,aAAA,EAAuC;CACzE,MAAM,wBAAQ,IAAI,IAAqB;CACvC,MAAM,2BAAW,IAAI,IAAqC;CAC1D,MAAM,YAAY,SAAiB,YAA8B;EAC/D,MAAM,OAAO,OAAO;EACpB,MAAM,IAAI,SAAS,OAAO;EAC1B,MAAM,SAAS,MAAM,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;EACnC,IAAI,MAAM,OAAO,SAAS,WAAW,KAAA,GACnC,MAAM,OAAO,MAAM;EAErB,OAAO;CACT;CACA,MAAM,eAAe,OAAO,WAAmB,YAA6C;EAC1F,MAAM,SAAS,MAAM,YAAY,QAAQ,SAAS,WAAW,OAAO;EACpE,IAAI,QACF,OAAO;EAET,QAAQ,QAAQ,KAAK,EAAE,QAAQ,GAAG,kDAAkD;EACpF,OAAO,MAAM,eAAe,SAAS,WAAW,OAAO;CACzD;CACA,OAAO;EACL,MAAM,OAAO,WAAW,YAAY;GAClC,MAAM,MAAM,MAAM,IAAI,OAAO;GAC7B,IAAI,KACF,OAAO,SAAS,SAAS,GAAG;GAE9B,MAAM,UAAU,SAAS,IAAI,OAAO,KAAK,aAAa,WAAW,OAAO;GACxE,SAAS,IAAI,SAAS,OAAO;GAC7B,IAAI;IACF,MAAM,UAAU,MAAM;IACtB,OAAO,UAAU,SAAS,SAAS,OAAO,IAAI;GAChD,UAAU;IACR,SAAS,OAAO,OAAO;GACzB;EACF;EACA,SAAS,OAAO,WAAW,YAAY;GACrC,MAAM,OAAO,OAAO;GACpB,MAAM,UAAU,MAAM,eAAe,SAAS,WAAW,OAAO;GAChE,OAAO,UAAU,SAAS,SAAS,OAAO,IAAI;EAChD;CACF;AACF"}

package/dist/capture/catalog/parse.d.mts

@@ -0,0 +1,15 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { CatalogEntry } from "./types.mjs";
+//#region src/capture/catalog/parse.d.ts
+/**
+ * Entries of a parsed index document, or null when it is not an index. Test entries (Storybook 10
+ * `subtype: "test"`) are left out, as capture leaves them out; entries without an id or title are
+ * skipped, never an error.
+ */
+declare function parseStorybookIndex(document: unknown): CatalogEntry[] | null;
+/** Parse the text of an index file; null when it is not JSON or not an index. */
+declare function parseStorybookIndexText(text: string): CatalogEntry[] | null;
+//#endregion
+export { parseStorybookIndex, parseStorybookIndexText };
+//# sourceMappingURL=parse.d.mts.map

package/dist/capture/catalog/parse.mjs

@@ -0,0 +1,56 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { normalizeImportPath } from "../../models/design-resolve.mjs";
+//#region src/capture/catalog/parse.ts
+/** Storybook index to catalog entries: `index.json` (v4/v5), `stories.json` (v3 and older). */
+/**
+* Entries of a parsed index document, or null when it is not an index. Test entries (Storybook 10
+* `subtype: "test"`) are left out, as capture leaves them out; entries without an id or title are
+* skipped, never an error.
+*/
+function parseStorybookIndex(document) {
+	if (typeof document !== "object" || document === null) return null;
+	const record = document;
+	const table = [record.entries, record.stories].find((value) => isRecord(value));
+	if (!table) return null;
+	return Object.values(table).flatMap((raw) => {
+		const entry = toEntry(raw);
+		return entry ? [entry] : [];
+	});
+}
+/** Parse the text of an index file; null when it is not JSON or not an index. */
+function parseStorybookIndexText(text) {
+	try {
+		return parseStorybookIndex(JSON.parse(text));
+	} catch {
+		return null;
+	}
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function str(value) {
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+/** One raw entry; every field is optional on old Storybooks, so each is read defensively. */
+function toEntry(raw) {
+	if (!isRecord(raw) || raw["subtype"] === "test") return null;
+	const id = str(raw["id"]);
+	const title = str(raw["title"]) ?? str(raw["kind"]);
+	if (!id || !title) return null;
+	const importPath = str(raw["importPath"]);
+	const tags = raw["tags"];
+	return {
+		id,
+		title,
+		name: str(raw["name"]) ?? str(raw["story"]) ?? id,
+		importPath: importPath ? normalizeImportPath(importPath) : "",
+		type: raw["type"] === "docs" ? "docs" : "story",
+		tags: Array.isArray(tags) ? tags.filter((tag) => typeof tag === "string") : []
+	};
+}
+//#endregion
+export { parseStorybookIndex, parseStorybookIndexText };
+
+//# sourceMappingURL=parse.mjs.map

package/dist/capture/catalog/parse.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.mjs","names":[],"sources":["../../../src/capture/catalog/parse.ts"],"sourcesContent":["/** Storybook index to catalog entries: `index.json` (v4/v5), `stories.json` (v3 and older). */\nimport { normalizeImportPath } from \"../../models/design-resolve.ts\";\nimport type { CatalogEntry } from \"./types.ts\";\n\n/**\n * Entries of a parsed index document, or null when it is not an index. Test entries (Storybook 10\n * `subtype: \"test\"`) are left out, as capture leaves them out; entries without an id or title are\n * skipped, never an error.\n */\nexport function parseStorybookIndex(document: unknown): CatalogEntry[] | null {\n  if (typeof document !== \"object\" || document === null) {\n    return null;\n  }\n  const record = document as { entries?: unknown; stories?: unknown };\n  const table = [record.entries, record.stories].find((value) => isRecord(value));\n  if (!table) {\n    return null;\n  }\n  return Object.values(table).flatMap((raw) => {\n    const entry = toEntry(raw);\n    return entry ? [entry] : [];\n  });\n}\n\n/** Parse the text of an index file; null when it is not JSON or not an index. */\nexport function parseStorybookIndexText(text: string): CatalogEntry[] | null {\n  try {\n    return parseStorybookIndex(JSON.parse(text));\n  } catch {\n    return null;\n  }\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction str(value: unknown): string | undefined {\n  return typeof value === \"string\" && value !== \"\" ? value : undefined;\n}\n\n/** One raw entry; every field is optional on old Storybooks, so each is read defensively. */\nfunction toEntry(raw: unknown): CatalogEntry | null {\n  if (!isRecord(raw) || raw[\"subtype\"] === \"test\") {\n    return null;\n  }\n  const id = str(raw[\"id\"]);\n  const title = str(raw[\"title\"]) ?? str(raw[\"kind\"]);\n  if (!id || !title) {\n    return null;\n  }\n  const importPath = str(raw[\"importPath\"]);\n  const tags = raw[\"tags\"];\n  return {\n    id,\n    title,\n    name: str(raw[\"name\"]) ?? str(raw[\"story\"]) ?? id,\n    importPath: importPath ? normalizeImportPath(importPath) : \"\",\n    type: raw[\"type\"] === \"docs\" ? \"docs\" : \"story\",\n    tags: Array.isArray(tags) ? tags.filter((tag): tag is string => typeof tag === \"string\") : [],\n  };\n}\n"],"mappings":";;;;;;;;;;;AASA,SAAgB,oBAAoB,UAA0C;CAC5E,IAAI,OAAO,aAAa,YAAY,aAAa,MAC/C,OAAO;CAET,MAAM,SAAS;CACf,MAAM,QAAQ,CAAC,OAAO,SAAS,OAAO,OAAO,CAAC,CAAC,MAAM,UAAU,SAAS,KAAK,CAAC;CAC9E,IAAI,CAAC,OACH,OAAO;CAET,OAAO,OAAO,OAAO,KAAK,CAAC,CAAC,SAAS,QAAQ;EAC3C,MAAM,QAAQ,QAAQ,GAAG;EACzB,OAAO,QAAQ,CAAC,KAAK,IAAI,CAAC;CAC5B,CAAC;AACH;;AAGA,SAAgB,wBAAwB,MAAqC;CAC3E,IAAI;EACF,OAAO,oBAAoB,KAAK,MAAM,IAAI,CAAC;CAC7C,QAAQ;EACN,OAAO;CACT;AACF;AAEA,SAAS,SAAS,OAAkD;CAClE,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAEA,SAAS,IAAI,OAAoC;CAC/C,OAAO,OAAO,UAAU,YAAY,UAAU,KAAK,QAAQ,KAAA;AAC7D;;AAGA,SAAS,QAAQ,KAAmC;CAClD,IAAI,CAAC,SAAS,GAAG,KAAK,IAAI,eAAe,QACvC,OAAO;CAET,MAAM,KAAK,IAAI,IAAI,KAAK;CACxB,MAAM,QAAQ,IAAI,IAAI,QAAQ,KAAK,IAAI,IAAI,OAAO;CAClD,IAAI,CAAC,MAAM,CAAC,OACV,OAAO;CAET,MAAM,aAAa,IAAI,IAAI,aAAa;CACxC,MAAM,OAAO,IAAI;CACjB,OAAO;EACL;EACA;EACA,MAAM,IAAI,IAAI,OAAO,KAAK,IAAI,IAAI,QAAQ,KAAK;EAC/C,YAAY,aAAa,oBAAoB,UAAU,IAAI;EAC3D,MAAM,IAAI,YAAY,SAAS,SAAS;EACxC,MAAM,MAAM,QAAQ,IAAI,IAAI,KAAK,QAAQ,QAAuB,OAAO,QAAQ,QAAQ,IAAI,CAAC;CAC9F;AACF"}

package/dist/capture/catalog/read.d.mts

@@ -0,0 +1,12 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { StorageAdapter } from "../../adapter/storage.mjs";
+//#region src/capture/catalog/read.d.ts
+/**
+ * A file of a build's published Storybook by its path inside the build, or null when it is gone.
+ * Content-addressed builds answer through their manifest; older ones from the per-build copy.
+ */
+declare function readPublishedFile(storage: StorageAdapter, projectId: string, buildId: string, rel: string): Promise<Buffer | null>;
+//#endregion
+export { readPublishedFile };
+//# sourceMappingURL=read.d.mts.map

package/dist/capture/catalog/read.mjs

@@ -0,0 +1,33 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { storybookDir } from "../../paths.mjs";
+import { posix } from "node:path";
+//#region src/capture/catalog/read.ts
+/** Reading a published build's files from storage. */
+/**
+* A file of a build's published Storybook by its path inside the build, or null when it is gone.
+* Content-addressed builds answer through their manifest; older ones from the per-build copy.
+*/
+async function readPublishedFile(storage, projectId, buildId, rel) {
+	const dir = storybookDir(projectId, buildId);
+	const viaManifest = await readViaManifest(storage, dir, rel);
+	if (viaManifest) return viaManifest;
+	const legacy = posix.join(dir, rel);
+	return await storage.exists(legacy) ? await storage.read(legacy) : null;
+}
+async function readViaManifest(storage, dir, rel) {
+	try {
+		const manifestPath = posix.join(dir, "manifest.json");
+		if (!await storage.exists(manifestPath)) return null;
+		const hash = JSON.parse((await storage.read(manifestPath)).toString("utf8"))[rel];
+		const path = hash ? `content/${hash}` : void 0;
+		return path && await storage.exists(path) ? await storage.read(path) : null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { readPublishedFile };
+
+//# sourceMappingURL=read.mjs.map

package/dist/capture/catalog/read.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.mjs","names":[],"sources":["../../../src/capture/catalog/read.ts"],"sourcesContent":["/** Reading a published build's files from storage. */\nimport { posix } from \"node:path\";\nimport type { StorageAdapter } from \"../../adapters/storage.ts\";\nimport { storybookDir } from \"../../utils/paths.ts\";\n\n/**\n * A file of a build's published Storybook by its path inside the build, or null when it is gone.\n * Content-addressed builds answer through their manifest; older ones from the per-build copy.\n */\nexport async function readPublishedFile(\n  storage: StorageAdapter,\n  projectId: string,\n  buildId: string,\n  rel: string,\n): Promise<Buffer | null> {\n  const dir = storybookDir(projectId, buildId);\n  const viaManifest = await readViaManifest(storage, dir, rel);\n  if (viaManifest) {\n    return viaManifest;\n  }\n  const legacy = posix.join(dir, rel);\n  return (await storage.exists(legacy)) ? await storage.read(legacy) : null;\n}\n\nasync function readViaManifest(\n  storage: StorageAdapter,\n  dir: string,\n  rel: string,\n): Promise<Buffer | null> {\n  try {\n    const manifestPath = posix.join(dir, \"manifest.json\");\n    if (!(await storage.exists(manifestPath))) {\n      return null;\n    }\n    const manifest = JSON.parse((await storage.read(manifestPath)).toString(\"utf8\")) as Record<\n      string,\n      string\n    >;\n    const hash = manifest[rel];\n    const path = hash ? `content/${hash}` : undefined;\n    return path && (await storage.exists(path)) ? await storage.read(path) : null;\n  } catch {\n    // an unreadable manifest falls back to the per-build copy\n    return null;\n  }\n}\n"],"mappings":";;;;;;;;;;;AASA,eAAsB,kBACpB,SACA,WACA,SACA,KACwB;CACxB,MAAM,MAAM,aAAa,WAAW,OAAO;CAC3C,MAAM,cAAc,MAAM,gBAAgB,SAAS,KAAK,GAAG;CAC3D,IAAI,aACF,OAAO;CAET,MAAM,SAAS,MAAM,KAAK,KAAK,GAAG;CAClC,OAAQ,MAAM,QAAQ,OAAO,MAAM,IAAK,MAAM,QAAQ,KAAK,MAAM,IAAI;AACvE;AAEA,eAAe,gBACb,SACA,KACA,KACwB;CACxB,IAAI;EACF,MAAM,eAAe,MAAM,KAAK,KAAK,eAAe;EACpD,IAAI,CAAE,MAAM,QAAQ,OAAO,YAAY,GACrC,OAAO;EAMT,MAAM,OAJW,KAAK,OAAO,MAAM,QAAQ,KAAK,YAAY,EAAA,CAAG,SAAS,MAAM,CAI1D,CAAC,CAAC;EACtB,MAAM,OAAO,OAAO,WAAW,SAAS,KAAA;EACxC,OAAO,QAAS,MAAM,QAAQ,OAAO,IAAI,IAAK,MAAM,QAAQ,KAAK,IAAI,IAAI;CAC3E,QAAQ;EAEN,OAAO;CACT;AACF"}

package/dist/capture/catalog/types.d.mts

@@ -0,0 +1,33 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/capture/catalog/types.d.ts
+/** Shapes of the persisted catalog (ADR 0006, decision 9). */
+/** One Storybook index entry, kept compact: story and docs entries, never test entries. */
+interface CatalogEntry {
+  id: string;
+  title: string;
+  name: string;
+  /** Story file without a leading `./`; empty when the index carries none. */
+  importPath: string;
+  type: "story" | "docs";
+  tags: string[];
+}
+/** A build's catalog as stored in `catalog.json`. */
+interface Catalog {
+  /** Format version of the file. */
+  v: 1;
+  entries: CatalogEntry[];
+}
+/** The entries of one story file, with what `build_components` stores of them. */
+interface CatalogComponent {
+  importPath: string;
+  title: string;
+  /** Story entries; docs entries are not counted. */
+  storyCount: number;
+  /** SHA-256 over the component's entries, so two builds compare with one string. */
+  hash: string;
+  entries: CatalogEntry[];
+}
+//#endregion
+export { Catalog, CatalogComponent, CatalogEntry };
+//# sourceMappingURL=types.d.mts.map

package/dist/capture/consumer/capture-handler.d.mts

@@ -0,0 +1,58 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { CaptureRunner } from "../../adapter/capture-runner.mjs";
+import { DatabaseAdapter } from "../../adapter/database.mjs";
+import { Logger } from "../../logger.mjs";
+import { DesignProvider } from "../../adapter/design.mjs";
+import { NotifierProvider } from "../../adapters/notifier/provider.mjs";
+import { StorageAdapter } from "../../adapter/storage.mjs";
+import { ShelfConfig } from "../../config.mjs";
+import { SecretInput } from "../../utils/encrypt.mjs";
+import { CaptureJobOptions, ShardJob } from "../orchestrator.mjs";
+import { BuildStatePublisher } from "../build-state/types.mjs";
+import { DispatchDeps } from "../dispatch.mjs";
+import { KindHandler } from "./types.mjs";
+//#region src/capture/consumer/capture-handler.d.ts
+/** What the capture handler needs: the same adapters the server's own capture setup uses. */
+interface CaptureHandlerOptions {
+  /** Database adapter; its own `tables` are used (never a dialect's defaults). */
+  db: DatabaseAdapter;
+  storage: StorageAdapter;
+  /** Pure renderer; `cancel` is called when a job's lease is lost or the job is cancelled. */
+  runner: CaptureRunner;
+  /** Scratch directory for Storybook extraction. */
+  scratchDir: string;
+  logger: Logger;
+  /** Puts a shard job on the queue; sharding needs it. Defaults to the consumed queue's `enqueue`. */
+  enqueue: (job: ShardJob) => Promise<void>;
+  /** Notifier providers; `state` channels (git hosts) get the build statuses. */
+  notifiers?: NotifierProvider[];
+  /**
+   * Shows a build's state on its git channels at every transition. Default: deliver inline through
+   * `notifiers` (a capture always has `testing` on); the app passes its queue-backed publisher.
+   */
+  buildState?: BuildStatePublisher;
+  /** Links in statuses are absolute from `publicBaseUrl`; published Storybooks use `publishedBaseDomain`. */
+  config?: Pick<ShelfConfig, "publicBaseUrl" | "publishedBaseDomain" | "maxZipEntries" | "maxUnzippedBytes">;
+  /**
+   * The resolved public origin (ADR 0007, decision 6): status links and URL-reaching targets use it.
+   * Default: `config.publicBaseUrl`, then the platform's address, then the origin an admin stored.
+   */
+  publicOrigin?: () => Promise<string | undefined>;
+  /** Design providers validating declared design links during capture. */
+  design?: DesignProvider[];
+  /** Server secret for webhook decryption. */
+  secret?: SecretInput;
+  viewports?: CaptureJobOptions["viewports"];
+  /** Captures per shard; unset keeps every build in one job. */
+  shardSize?: number;
+  /** Retries assumed for jobs that do not state `maxAttempts` (default 2). */
+  maxRetries?: number;
+}
+/** The `capture` handler: runs `createDispatchJob`'s runner, cancels through `runner.cancel`. */
+declare function createCaptureHandler(options: CaptureHandlerOptions): KindHandler;
+/** The dispatch dependencies the handler runs captures with; the host reuses them to write failures the pipeline never got to. */
+declare function captureDispatchDeps(options: CaptureHandlerOptions, maxRetries: number): DispatchDeps;
+//#endregion
+export { CaptureHandlerOptions, captureDispatchDeps, createCaptureHandler };
+//# sourceMappingURL=capture-handler.d.mts.map

package/dist/capture/consumer/capture-handler.mjs

@@ -0,0 +1,118 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { extractionLimitsOf, resolvePublishLimits } from "../publish/limits.mjs";
+import { retriesOf } from "./retry.mjs";
+import { createBuildStatePublisher } from "../build-state/publisher.mjs";
+import { createPublicOriginResolver } from "../../models/public-origin.mjs";
+import { createDispatchJob } from "../dispatch.mjs";
+//#region src/capture/consumer/capture-handler.ts
+/** Whether a polled capture job carries the minimum shape to execute. */
+function isValidCaptureJob(job) {
+	return typeof job.buildId === "string" && job.buildId.length > 0;
+}
+/** The `capture` handler: runs `createDispatchJob`'s runner, cancels through `runner.cancel`. */
+function createCaptureHandler(options) {
+	const fallbackRetries = options.maxRetries ?? 2;
+	const dispatches = /* @__PURE__ */ new Map();
+	const dispatchFor = (retries) => {
+		const existing = dispatches.get(retries);
+		if (existing !== void 0) return existing;
+		const created = createDispatchJob(captureDispatchDeps(options, retries));
+		dispatches.set(retries, created);
+		return created;
+	};
+	dispatchFor(fallbackRetries);
+	return {
+		accepts: isValidCaptureJob,
+		run: async (job, context) => {
+			await dispatchFor(retriesOf(job, fallbackRetries))(toDispatchJob(job), { touch: () => {
+				context.touch();
+			} });
+		},
+		cancel: async (job) => {
+			await options.runner.cancel(job.buildId, job.shard);
+		}
+	};
+}
+function toDispatchJob(job) {
+	return {
+		buildId: job.buildId,
+		shard: job.shard,
+		attempts: job.attempts,
+		...job.reqId === void 0 ? {} : { reqId: job.reqId },
+		...job.traceparent === void 0 ? {} : { traceparent: job.traceparent }
+	};
+}
+/** The dispatch dependencies the handler runs captures with; the host reuses them to write failures the pipeline never got to. */
+function captureDispatchDeps(options, maxRetries) {
+	const t = options.db.tables;
+	const publicOrigin = originOf(options);
+	const jobOptions = {
+		db: options.db,
+		tables: {
+			projects: t.projects,
+			builds: t.builds,
+			buildLabels: t.buildLabels,
+			snapshots: t.snapshots,
+			baselines: t.baselines,
+			captureAttempts: t.captureAttempts,
+			captureLogs: t.captureLogs
+		},
+		storage: options.storage,
+		runner: options.runner,
+		scratchDir: options.scratchDir,
+		limits: extractionLimitsOf(resolvePublishLimits(options.config)),
+		viewports: options.viewports,
+		logger: options.logger,
+		secret: options.secret,
+		design: options.design,
+		publicOrigin,
+		shardSize: options.shardSize,
+		enqueue: options.enqueue
+	};
+	return {
+		db: options.db,
+		tables: {
+			projects: t.projects,
+			builds: t.builds,
+			buildLabels: t.buildLabels,
+			snapshots: t.snapshots,
+			captureAttempts: t.captureAttempts,
+			captureLogs: t.captureLogs
+		},
+		jobOptions,
+		buildState: options.buildState ?? inlineBuildState(options, publicOrigin),
+		logger: options.logger,
+		maxRetries
+	};
+}
+/** Inline delivery of captured builds' states through the handler's own adapters. */
+function inlineBuildState(options, publicOrigin) {
+	return createBuildStatePublisher({ deps: {
+		db: options.db,
+		storage: options.storage,
+		notifiers: options.notifiers ?? [],
+		secret: options.secret,
+		config: options.config ?? {},
+		publicOrigin,
+		flags: () => ({
+			testing: true,
+			review: false
+		}),
+		logger: options.logger
+	} });
+}
+/** The host's origin resolver, else one built from the database and `config.publicBaseUrl`. */
+function originOf(options) {
+	if (options.publicOrigin !== void 0) return options.publicOrigin;
+	const resolver = createPublicOriginResolver({
+		db: options.db,
+		config: options.config
+	});
+	return async () => await resolver.url();
+}
+//#endregion
+export { captureDispatchDeps, createCaptureHandler, originOf };
+
+//# sourceMappingURL=capture-handler.mjs.map

package/dist/capture/consumer/capture-handler.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-handler.mjs","names":[],"sources":["../../../src/capture/consumer/capture-handler.ts"],"sourcesContent":["/** The `capture` kind's handler: builds the existing core dispatch from the host's adapters. */\nimport type { CaptureRunner } from \"../../adapters/capture-runner.ts\";\nimport type { DatabaseAdapter } from \"../../adapters/database.ts\";\nimport type { DesignProvider } from \"../../adapters/design.ts\";\nimport type { NotifierProvider } from \"../../adapters/notifier/provider.ts\";\nimport type { StorageAdapter } from \"../../adapters/storage.ts\";\nimport type { ShelfConfig } from \"../../config.ts\";\nimport type { Logger } from \"../../logger.ts\";\nimport { createPublicOriginResolver } from \"../../models/public-origin.ts\";\nimport type { SecretInput } from \"../../utils/encrypt.ts\";\nimport { createBuildStatePublisher } from \"../build-state/publisher.ts\";\nimport type { BuildStatePublisher } from \"../build-state/types.ts\";\nimport { createDispatchJob, type CaptureDispatchJob, type DispatchDeps } from \"../dispatch.ts\";\nimport type { CaptureJobOptions, ShardJob } from \"../orchestrator.ts\";\nimport { extractionLimitsOf, resolvePublishLimits } from \"../publish/limits.ts\";\nimport { DEFAULT_MAX_RETRIES, retriesOf } from \"./retry.ts\";\nimport type { ConsumerJob, KindHandler } from \"./types.ts\";\n\n/** What the capture handler needs: the same adapters the server's own capture setup uses. */\nexport interface CaptureHandlerOptions {\n  /** Database adapter; its own `tables` are used (never a dialect's defaults). */\n  db: DatabaseAdapter;\n  storage: StorageAdapter;\n  /** Pure renderer; `cancel` is called when a job's lease is lost or the job is cancelled. */\n  runner: CaptureRunner;\n  /** Scratch directory for Storybook extraction. */\n  scratchDir: string;\n  logger: Logger;\n  /** Puts a shard job on the queue; sharding needs it. Defaults to the consumed queue's `enqueue`. */\n  enqueue: (job: ShardJob) => Promise<void>;\n  /** Notifier providers; `state` channels (git hosts) get the build statuses. */\n  notifiers?: NotifierProvider[];\n  /**\n   * Shows a build's state on its git channels at every transition. Default: deliver inline through\n   * `notifiers` (a capture always has `testing` on); the app passes its queue-backed publisher.\n   */\n  buildState?: BuildStatePublisher;\n  /** Links in statuses are absolute from `publicBaseUrl`; published Storybooks use `publishedBaseDomain`. */\n  config?: Pick<\n    ShelfConfig,\n    \"publicBaseUrl\" | \"publishedBaseDomain\" | \"maxZipEntries\" | \"maxUnzippedBytes\"\n  >;\n  /**\n   * The resolved public origin (ADR 0007, decision 6): status links and URL-reaching targets use it.\n   * Default: `config.publicBaseUrl`, then the platform's address, then the origin an admin stored.\n   */\n  publicOrigin?: () => Promise<string | undefined>;\n  /** Design providers validating declared design links during capture. */\n  design?: DesignProvider[];\n  /** Server secret for webhook decryption. */\n  secret?: SecretInput;\n  viewports?: CaptureJobOptions[\"viewports\"];\n  /** Captures per shard; unset keeps every build in one job. */\n  shardSize?: number;\n  /** Retries assumed for jobs that do not state `maxAttempts` (default 2). */\n  maxRetries?: number;\n}\n\n/** Whether a polled capture job carries the minimum shape to execute. */\nfunction isValidCaptureJob(job: ConsumerJob): boolean {\n  return typeof job.buildId === \"string\" && job.buildId.length > 0;\n}\n\n/** The `capture` handler: runs `createDispatchJob`'s runner, cancels through `runner.cancel`. */\nexport function createCaptureHandler(options: CaptureHandlerOptions): KindHandler {\n  const fallbackRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;\n  // The shard rule (\"a shard's last try is its final word\") depends on the queue's retry limit,\n  // which a database job states itself, so one dispatch exists per distinct limit.\n  const dispatches = new Map<number, ReturnType<typeof createDispatchJob>>();\n  const dispatchFor = (retries: number): ReturnType<typeof createDispatchJob> => {\n    const existing = dispatches.get(retries);\n    if (existing !== undefined) {\n      return existing;\n    }\n    const created = createDispatchJob(captureDispatchDeps(options, retries));\n    dispatches.set(retries, created);\n    return created;\n  };\n  dispatchFor(fallbackRetries);\n  return {\n    accepts: isValidCaptureJob,\n    run: async (job, context) => {\n      await dispatchFor(retriesOf(job, fallbackRetries))(toDispatchJob(job), {\n        touch: () => {\n          context.touch();\n        },\n      });\n    },\n    cancel: async (job) => {\n      await options.runner.cancel(job.buildId, job.shard);\n    },\n  };\n}\n\nfunction toDispatchJob(job: ConsumerJob): CaptureDispatchJob {\n  return {\n    buildId: job.buildId,\n    shard: job.shard,\n    attempts: job.attempts,\n    ...(job.reqId === undefined ? {} : { reqId: job.reqId }),\n    ...(job.traceparent === undefined ? {} : { traceparent: job.traceparent }),\n  };\n}\n\n/** The dispatch dependencies the handler runs captures with; the host reuses them to write failures the pipeline never got to. */\nexport function captureDispatchDeps(\n  options: CaptureHandlerOptions,\n  maxRetries: number,\n): DispatchDeps {\n  const t = options.db.tables;\n  const publicOrigin = originOf(options);\n  const jobOptions: CaptureJobOptions = {\n    db: options.db,\n    tables: {\n      projects: t.projects,\n      builds: t.builds,\n      buildLabels: t.buildLabels,\n      snapshots: t.snapshots,\n      baselines: t.baselines,\n      captureAttempts: t.captureAttempts,\n      captureLogs: t.captureLogs,\n    },\n    storage: options.storage,\n    runner: options.runner,\n    scratchDir: options.scratchDir,\n    limits: extractionLimitsOf(resolvePublishLimits(options.config)),\n    viewports: options.viewports,\n    logger: options.logger,\n    secret: options.secret,\n    design: options.design,\n    publicOrigin,\n    shardSize: options.shardSize,\n    enqueue: options.enqueue,\n  };\n  return {\n    db: options.db,\n    tables: {\n      projects: t.projects,\n      builds: t.builds,\n      buildLabels: t.buildLabels,\n      snapshots: t.snapshots,\n      captureAttempts: t.captureAttempts,\n      captureLogs: t.captureLogs,\n    },\n    jobOptions,\n    buildState: options.buildState ?? inlineBuildState(options, publicOrigin),\n    logger: options.logger,\n    maxRetries,\n  };\n}\n\n/** Inline delivery of captured builds' states through the handler's own adapters. */\nfunction inlineBuildState(\n  options: CaptureHandlerOptions,\n  publicOrigin: () => Promise<string | undefined>,\n): BuildStatePublisher {\n  return createBuildStatePublisher({\n    deps: {\n      db: options.db,\n      storage: options.storage,\n      notifiers: options.notifiers ?? [],\n      secret: options.secret,\n      config: options.config ?? {},\n      publicOrigin,\n      flags: () => ({ testing: true, review: false }),\n      logger: options.logger,\n    },\n  });\n}\n\n/** The host's origin resolver, else one built from the database and `config.publicBaseUrl`. */\nexport function originOf(\n  options: Pick<CaptureHandlerOptions, \"db\" | \"config\" | \"publicOrigin\">,\n): () => Promise<string | undefined> {\n  if (options.publicOrigin !== undefined) {\n    return options.publicOrigin;\n  }\n  const resolver = createPublicOriginResolver({ db: options.db, config: options.config });\n  return async () => await resolver.url();\n}\n"],"mappings":";;;;;;;;;;AA2DA,SAAS,kBAAkB,KAA2B;CACpD,OAAO,OAAO,IAAI,YAAY,YAAY,IAAI,QAAQ,SAAS;AACjE;;AAGA,SAAgB,qBAAqB,SAA6C;CAChF,MAAM,kBAAkB,QAAQ,cAAA;CAGhC,MAAM,6BAAa,IAAI,IAAkD;CACzE,MAAM,eAAe,YAA0D;EAC7E,MAAM,WAAW,WAAW,IAAI,OAAO;EACvC,IAAI,aAAa,KAAA,GACf,OAAO;EAET,MAAM,UAAU,kBAAkB,oBAAoB,SAAS,OAAO,CAAC;EACvE,WAAW,IAAI,SAAS,OAAO;EAC/B,OAAO;CACT;CACA,YAAY,eAAe;CAC3B,OAAO;EACL,SAAS;EACT,KAAK,OAAO,KAAK,YAAY;GAC3B,MAAM,YAAY,UAAU,KAAK,eAAe,CAAC,CAAC,CAAC,cAAc,GAAG,GAAG,EACrE,aAAa;IACX,QAAQ,MAAM;GAChB,EACF,CAAC;EACH;EACA,QAAQ,OAAO,QAAQ;GACrB,MAAM,QAAQ,OAAO,OAAO,IAAI,SAAS,IAAI,KAAK;EACpD;CACF;AACF;AAEA,SAAS,cAAc,KAAsC;CAC3D,OAAO;EACL,SAAS,IAAI;EACb,OAAO,IAAI;EACX,UAAU,IAAI;EACd,GAAI,IAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO,IAAI,MAAM;EACtD,GAAI,IAAI,gBAAgB,KAAA,IAAY,CAAC,IAAI,EAAE,aAAa,IAAI,YAAY;CAC1E;AACF;;AAGA,SAAgB,oBACd,SACA,YACc;CACd,MAAM,IAAI,QAAQ,GAAG;CACrB,MAAM,eAAe,SAAS,OAAO;CACrC,MAAM,aAAgC;EACpC,IAAI,QAAQ;EACZ,QAAQ;GACN,UAAU,EAAE;GACZ,QAAQ,EAAE;GACV,aAAa,EAAE;GACf,WAAW,EAAE;GACb,WAAW,EAAE;GACb,iBAAiB,EAAE;GACnB,aAAa,EAAE;EACjB;EACA,SAAS,QAAQ;EACjB,QAAQ,QAAQ;EAChB,YAAY,QAAQ;EACpB,QAAQ,mBAAmB,qBAAqB,QAAQ,MAAM,CAAC;EAC/D,WAAW,QAAQ;EACnB,QAAQ,QAAQ;EAChB,QAAQ,QAAQ;EAChB,QAAQ,QAAQ;EAChB;EACA,WAAW,QAAQ;EACnB,SAAS,QAAQ;CACnB;CACA,OAAO;EACL,IAAI,QAAQ;EACZ,QAAQ;GACN,UAAU,EAAE;GACZ,QAAQ,EAAE;GACV,aAAa,EAAE;GACf,WAAW,EAAE;GACb,iBAAiB,EAAE;GACnB,aAAa,EAAE;EACjB;EACA;EACA,YAAY,QAAQ,cAAc,iBAAiB,SAAS,YAAY;EACxE,QAAQ,QAAQ;EAChB;CACF;AACF;;AAGA,SAAS,iBACP,SACA,cACqB;CACrB,OAAO,0BAA0B,EAC/B,MAAM;EACJ,IAAI,QAAQ;EACZ,SAAS,QAAQ;EACjB,WAAW,QAAQ,aAAa,CAAC;EACjC,QAAQ,QAAQ;EAChB,QAAQ,QAAQ,UAAU,CAAC;EAC3B;EACA,cAAc;GAAE,SAAS;GAAM,QAAQ;EAAM;EAC7C,QAAQ,QAAQ;CAClB,EACF,CAAC;AACH;;AAGA,SAAgB,SACd,SACmC;CACnC,IAAI,QAAQ,iBAAiB,KAAA,GAC3B,OAAO,QAAQ;CAEjB,MAAM,WAAW,2BAA2B;EAAE,IAAI,QAAQ;EAAI,QAAQ,QAAQ;CAAO,CAAC;CACtF,OAAO,YAAY,MAAM,SAAS,IAAI;AACxC"}

package/dist/capture/consumer/idle.d.mts

@@ -0,0 +1,17 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/capture/consumer/idle.d.ts
+/**
+ * Idle backoff for queues whose `poll()` returns immediately when empty (GCP Pub/Sub synchronous
+ * pull, Azure Storage Queues). Queues that long-poll (SQS, Redis, Service Bus, the IPC queue) block
+ * inside `poll()` and never trigger it. The database queue paces itself (`db-queue/cadence.ts`).
+ */
+/** An empty poll that returns faster than this did not long-poll. */
+declare const MIN_BLOCKING_POLL_MS = 1000;
+/** Sleep for consecutive fast empty polls: 250ms doubling up to 5s. */
+declare function idleDelayMs(emptyStreak: number): number;
+/** Whether an empty poll came back too fast to have blocked on the queue. */
+declare function isFastEmptyPoll(elapsedMs: number): boolean;
+//#endregion
+export { MIN_BLOCKING_POLL_MS, idleDelayMs, isFastEmptyPoll };
+//# sourceMappingURL=idle.d.mts.map