@storyshelf/core 0.7.0 → 0.8.0

package/dist/capture/build-state/publisher.mjs

@@ -4,7 +4,7 @@ import.meta.url;
 import { sanitizeErrorText } from "../../utils/redact.mjs";
 import { NotificationChannelModel } from "../../models/notification-channel.mjs";
 import { loadBuild, stateTargets, writeTo } from "./deliver.mjs";
-//#region src/capture/build-state/publisher.ts
+// src/capture/build-state/publisher.ts
 /**
 * The one entry point for "this build changed, show it" (ADR 0014, decisions 5 and 7). Every build
 * transition and the end of publishing call `request`; it hands each git channel of the project a
@@ -101,7 +101,6 @@ async function deliverInline(deps, loaded, where) {
 		}, "failed to record outcome");
 	});
 }
-//#endregion
 export { PAUSED_MESSAGE, createBuildStatePublisher };
 
 //# sourceMappingURL=publisher.mjs.map

package/dist/capture/build-state/resume.d.mts

@@ -1,9 +1,7 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { BuildStateDeps, BuildStatePublisher } from "./types.mjs";
-//#region src/capture/build-state/resume.d.ts
 /** Ask `publisher` for the state of every open recent build; resolves to how many were asked. Never rejects. */
 declare function requestOpenBuildStates(deps: Pick<BuildStateDeps, "db" | "logger">, publisher: BuildStatePublisher): Promise<number>;
-//#endregion
 export { requestOpenBuildStates };
 //# sourceMappingURL=resume.d.mts.map

package/dist/capture/build-state/resume.mjs

@@ -4,7 +4,7 @@ import.meta.url;
 import { BuildModel } from "../../models/build.mjs";
 import { ProjectModel } from "../../models/project.mjs";
 import { LOCAL_SHA_PREFIX } from "@storyshelf/affected";
-//#region src/capture/build-state/resume.ts
+// src/capture/build-state/resume.ts
 /**
 * Re-requesting the state of builds still open. Requests made while no public origin was resolved
 * were dropped (ADR 0014, decision 11), so once one is, the builds that can still change are asked
@@ -41,7 +41,6 @@ async function openBuildIds(deps, projectId) {
 function hasGitCommit(gitSha) {
 	return gitSha.length > 0 && !gitSha.startsWith(LOCAL_SHA_PREFIX);
 }
-//#endregion
 export { requestOpenBuildStates };
 
 //# sourceMappingURL=resume.mjs.map

package/dist/capture/build-state/types.d.mts

@@ -1,7 +1,7 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { DatabaseAdapter } from "../../adapter/database.mjs";
 import { Logger } from "../../logger.mjs";
+import { DatabaseAdapter } from "../../adapter/database.mjs";
 import { NotificationChannel } from "../../adapters/notifier/types.mjs";
 import { NotifierProvider, StateNotifierProvider } from "../../adapters/notifier/provider.mjs";
 import { StorageAdapter } from "../../adapter/storage.mjs";
@@ -9,7 +9,6 @@ import { ShelfConfig } from "../../config.mjs";
 import { BuildStateFlags } from "../../adapters/notifier/build-state.mjs";
 import { SecretInput } from "../../utils/encrypt.mjs";
 import { Project } from "../../schema/project.mjs";
-//#region src/capture/build-state/types.d.ts
 /** What delivering a build's state needs. */
 interface BuildStateDeps {
   db: DatabaseAdapter;
@@ -44,6 +43,5 @@ type SkipReason = "no-build" | "no-channel" | "disabled" | "no-provider" | "no-o
 interface BuildStatePublisher {
   request(buildId: string): Promise<void>;
 }
-//#endregion
 export { BuildStateDeps, BuildStatePublisher, SkipReason, StateTarget };
 //# sourceMappingURL=types.d.mts.map

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

@@ -3,7 +3,6 @@ import __tsdown_shims_url from 'node:url';
 import { DatabaseAdapter } from "../../adapter/database.mjs";
 import { StorageAdapter } from "../../adapter/storage.mjs";
 import { Catalog } from "./types.mjs";
-//#region src/capture/catalog/catalogue.d.ts
 /** What cataloguing reads and writes. */
 interface CatalogDeps {
   db: DatabaseAdapter;
@@ -17,6 +16,5 @@ interface CatalogDeps {
 declare function catalogueBuild(deps: CatalogDeps, projectId: string, buildId: string): Promise<Catalog | null>;
 /** A build's persisted catalog, or null when it has none (or an unreadable one). */
 declare function readCatalog(storage: StorageAdapter, projectId: string, buildId: string): Promise<Catalog | null>;
-//#endregion
 export { CatalogDeps, catalogueBuild, readCatalog };
 //# sourceMappingURL=catalogue.d.mts.map

package/dist/capture/catalog/catalogue.mjs

@@ -6,7 +6,7 @@ import { BuildComponentModel } from "../../models/build-component.mjs";
 import { groupComponents, toBuildComponent } from "./components.mjs";
 import { parseStorybookIndexText } from "./parse.mjs";
 import { readPublishedFile } from "./read.mjs";
-//#region src/capture/catalog/catalogue.ts
+// src/capture/catalog/catalogue.ts
 /** Index files a Storybook may publish, newest format first. */
 const INDEX_FILES = ["index.json", "stories.json"];
 /**
@@ -47,7 +47,6 @@ async function readIndexEntries(storage, projectId, buildId) {
 	}
 	return null;
 }
-//#endregion
 export { catalogueBuild, readCatalog };
 
 //# sourceMappingURL=catalogue.mjs.map

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

@@ -2,7 +2,6 @@ import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { CatalogComponent, CatalogEntry } from "./types.mjs";
 import { BuildComponentInput } from "../../models/build-component.mjs";
-//#region src/capture/catalog/components.d.ts
 /** Group entries by story file (entries without one by title), ordered by title then file. */
 declare function groupComponents(entries: readonly CatalogEntry[]): CatalogComponent[];
 /** What `build_components` stores of a component. */
@@ -18,6 +17,5 @@ interface EntryChanges {
 }
 /** Entries added, removed and renamed from `before` to `after` (matched by entry id). */
 declare function diffEntries(before: readonly CatalogEntry[], after: readonly CatalogEntry[]): EntryChanges;
-//#endregion
 export { EntryChanges, diffEntries, groupComponents, hashEntries, toBuildComponent };
 //# sourceMappingURL=components.d.mts.map

package/dist/capture/catalog/components.mjs

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { createHash } from "node:crypto";
-//#region src/capture/catalog/components.ts
+// src/capture/catalog/components.ts
 /** Catalog entries grouped into components, hashed, and compared between builds. */
 /** Group entries by story file (entries without one by title), ordered by title then file. */
 function groupComponents(entries) {
@@ -49,7 +49,6 @@ function diffEntries(before, after) {
 		renamed
 	};
 }
-//#endregion
 export { diffEntries, groupComponents, hashEntries, toBuildComponent };
 
 //# sourceMappingURL=components.mjs.map

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

@@ -3,7 +3,6 @@ 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. */
@@ -25,6 +24,5 @@ declare function componentBuildHistory(rows: readonly BuildComponent[], builds:
  * 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

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/capture/catalog/history.ts
+// 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
@@ -45,7 +45,6 @@ function catalogPresence(history, importPath, latest) {
 		lastSeen: newest.build
 	};
 }
-//#endregion
 export { catalogPresence, componentBuildHistory };
 
 //# sourceMappingURL=history.mjs.map

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

@@ -2,13 +2,11 @@ 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

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/capture/catalog/hook.ts
+// 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
@@ -13,7 +13,6 @@ function createCatalogHook(loader) {
 		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/index.d.mts

@@ -6,6 +6,6 @@ import { CatalogLoader, CatalogLoaderOptions, DEFAULT_CATALOG_CACHE_SIZE, create
 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 { readPublishedFile, readPublishedFileInfo } 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 };
+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, readPublishedFileInfo, toBuildComponent };

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

@@ -3,7 +3,6 @@ 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. */
@@ -21,6 +20,5 @@ interface CatalogLoaderOptions extends CatalogDeps {
 }
 /** 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

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { catalogueBuild, readCatalog } from "./catalogue.mjs";
-//#region src/capture/catalog/load.ts
+// 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`. */
@@ -43,7 +43,6 @@ function createCatalogLoader(options) {
 		}
 	};
 }
-//#endregion
 export { DEFAULT_CATALOG_CACHE_SIZE, createCatalogLoader };
 
 //# sourceMappingURL=load.mjs.map

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

@@ -1,7 +1,6 @@
 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
@@ -10,6 +9,5 @@ import { CatalogEntry } from "./types.mjs";
 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

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { normalizeImportPath } from "../../models/design-resolve.mjs";
-//#region src/capture/catalog/parse.ts
+// 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
@@ -50,7 +50,6 @@ function toEntry(raw) {
 		tags: Array.isArray(tags) ? tags.filter((tag) => typeof tag === "string") : []
 	};
 }
-//#endregion
 export { parseStorybookIndex, parseStorybookIndexText };
 
 //# sourceMappingURL=parse.mjs.map

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

@@ -1,12 +1,15 @@
 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 };
+/** Published bytes and, for content-addressed files, their manifest identity. */
+declare function readPublishedFileInfo(storage: StorageAdapter, projectId: string, buildId: string, rel: string): Promise<{
+  bytes: Buffer;
+  contentHash?: string;
+} | null>;
+export { readPublishedFile, readPublishedFileInfo };
 //# sourceMappingURL=read.d.mts.map

package/dist/capture/catalog/read.mjs

@@ -1,33 +1,39 @@
-import "node:path";
+import { posix } from "node:path";
 import "node:url";
 import.meta.url;
 import { storybookDir } from "../../paths.mjs";
-import { posix } from "node:path";
-//#region src/capture/catalog/read.ts
+// 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) {
+	return (await readPublishedFileInfo(storage, projectId, buildId, rel))?.bytes ?? null;
+}
+/** Published bytes and, for content-addressed files, their manifest identity. */
+async function readPublishedFileInfo(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;
+	return await storage.exists(legacy) ? { bytes: 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;
+		if (!hash) return null;
+		const path = `content/${hash}`;
+		return await storage.exists(path) ? {
+			bytes: await storage.read(path),
+			contentHash: hash
+		} : null;
 	} catch {
 		return null;
 	}
 }
-//#endregion
-export { readPublishedFile };
+export { readPublishedFile, readPublishedFileInfo };
 
 //# sourceMappingURL=read.mjs.map

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

@@ -1 +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"}
+{"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  return (await readPublishedFileInfo(storage, projectId, buildId, rel))?.bytes ?? null;\n}\n\n/** Published bytes and, for content-addressed files, their manifest identity. */\nexport async function readPublishedFileInfo(\n  storage: StorageAdapter,\n  projectId: string,\n  buildId: string,\n  rel: string,\n): Promise<{ bytes: Buffer; contentHash?: string } | 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)) ? { bytes: await storage.read(legacy) } : null;\n}\n\nasync function readViaManifest(\n  storage: StorageAdapter,\n  dir: string,\n  rel: string,\n): Promise<{ bytes: Buffer; contentHash: string } | 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    if (!hash) return null;\n    const path = `content/${hash}`;\n    return (await storage.exists(path))\n      ? { bytes: await storage.read(path), contentHash: hash }\n      : 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,QAAQ,MAAM,sBAAsB,SAAS,WAAW,SAAS,GAAG,EAAA,EAAI,SAAS;AACnF;;AAGA,eAAsB,sBACpB,SACA,WACA,SACA,KACyD;CACzD,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,EAAE,OAAO,MAAM,QAAQ,KAAK,MAAM,EAAE,IAAI;AAClF;AAEA,eAAe,gBACb,SACA,KACA,KACwD;CACxD,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,IAAI,CAAC,MAAM,OAAO;EAClB,MAAM,OAAO,WAAW;EACxB,OAAQ,MAAM,QAAQ,OAAO,IAAI,IAC7B;GAAE,OAAO,MAAM,QAAQ,KAAK,IAAI;GAAG,aAAa;EAAK,IACrD;CACN,QAAQ;EAEN,OAAO;CACT;AACF"}

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

@@ -1,6 +1,5 @@
 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 {
@@ -28,6 +27,5 @@ interface CatalogComponent {
   hash: string;
   entries: CatalogEntry[];
 }
-//#endregion
 export { Catalog, CatalogComponent, CatalogEntry };
 //# sourceMappingURL=types.d.mts.map

package/dist/capture/comparison-reference.d.mts

@@ -0,0 +1,27 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import "../adapter/database.mjs";
+import "../adapter/storage.mjs";
+import { z } from "zod";
+declare const referenceSchema: z.ZodObject<{
+  version: z.ZodLiteral<1>;
+  baselineId: z.ZodString;
+  baselineVersion: z.ZodString;
+  branch: z.ZodString;
+  defaultBranch: z.ZodBoolean;
+  sourceBuildId: z.ZodNullable<z.ZodString>;
+  sourceSnapshotId: z.ZodNullable<z.ZodString>;
+  imageSha256: z.ZodString;
+  baselineFingerprint: z.ZodNullable<z.ZodString>;
+  captureFingerprint: z.ZodNullable<z.ZodString>;
+  mode: z.ZodNullable<z.ZodString>;
+  target: z.ZodString;
+  width: z.ZodNullable<z.ZodNumber>;
+  height: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+type ComparisonReference = z.infer<typeof referenceSchema>;
+declare function parseComparisonReference(raw: string | null | undefined): ComparisonReference | null;
+/** Reject paths outside the consuming build's dedicated comparison directory. */
+declare function isComparisonImagePath(path: string, projectId: string, buildId: string): boolean;
+export { ComparisonReference, isComparisonImagePath, parseComparisonReference };
+//# sourceMappingURL=comparison-reference.d.mts.map

package/dist/capture/comparison-reference.mjs

@@ -0,0 +1,75 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import "../adapters/capture-target.mjs";
+import { ulid } from "../utils/ulid.mjs";
+import { SnapshotModel } from "../models/snapshot.mjs";
+import { z } from "zod";
+import { createHash } from "node:crypto";
+// src/capture/comparison-reference.ts
+/** Freeze a baseline image under the consuming build so it survives baseline movement. */
+const referenceSchema = z.object({
+	version: z.literal(1),
+	baselineId: z.string(),
+	baselineVersion: z.string(),
+	branch: z.string(),
+	defaultBranch: z.boolean(),
+	sourceBuildId: z.string().nullable(),
+	sourceSnapshotId: z.string().nullable(),
+	imageSha256: z.string().regex(/^[a-f0-9]{64}$/u),
+	baselineFingerprint: z.string().nullable(),
+	captureFingerprint: z.string().nullable(),
+	mode: z.string().nullable(),
+	target: z.string(),
+	width: z.number().int().positive().nullable(),
+	height: z.number().int().positive().nullable()
+});
+async function freezeComparison(storage, projectId, buildId, baseline, settings) {
+	const image = await storage.read(baseline.screenshotPath);
+	const comparisonImagePath = `${projectId}/builds/${buildId}/comparisons/${ulid()}.png`;
+	const reference = {
+		version: 1,
+		baselineId: baseline.id,
+		baselineVersion: baseline.updatedAt,
+		branch: baseline.branch,
+		defaultBranch: baseline.branch === settings.defaultBranch,
+		sourceBuildId: baseline.sourceBuildId ?? null,
+		sourceSnapshotId: settings.sourceSnapshotId,
+		imageSha256: createHash("sha256").update(image).digest("hex"),
+		baselineFingerprint: baseline.fingerprint ?? null,
+		captureFingerprint: settings.captureFingerprint ?? null,
+		mode: settings.mode,
+		target: settings.target,
+		width: settings.width,
+		height: settings.height
+	};
+	await storage.write(comparisonImagePath, image);
+	return {
+		comparisonImagePath,
+		comparisonMetadata: JSON.stringify(reference)
+	};
+}
+function parseComparisonReference(raw) {
+	if (!raw) return null;
+	try {
+		const parsed = referenceSchema.safeParse(JSON.parse(raw));
+		return parsed.success ? parsed.data : null;
+	} catch {
+		return null;
+	}
+}
+/** Reject paths outside the consuming build's dedicated comparison directory. */
+function isComparisonImagePath(path, projectId, buildId) {
+	const prefix = `${projectId}/builds/${buildId}/comparisons/`;
+	return path.startsWith(prefix) && /^[0-9A-HJKMNP-TV-Z]{26}\.png$/u.test(path.slice(prefix.length));
+}
+/** Identify a rendering snapshot only when its stored identity and image are provable. */
+async function sourceSnapshotId(db, baseline) {
+	if (!baseline.sourceBuildId || !baseline.snapshotId) return null;
+	const snapshot = await new SnapshotModel(db).get(baseline.snapshotId);
+	if (!snapshot || snapshot.inherited || snapshot.buildId !== baseline.sourceBuildId || snapshot.projectId !== baseline.projectId || snapshot.storyId !== baseline.storyId || snapshot.viewportName !== baseline.viewportName || (snapshot.browser ?? "chromium") !== (baseline.browser ?? "chromium") || snapshot.screenshotPath !== baseline.screenshotPath) return null;
+	return snapshot.id;
+}
+export { freezeComparison, isComparisonImagePath, parseComparisonReference, sourceSnapshotId };
+
+//# sourceMappingURL=comparison-reference.mjs.map

package/dist/capture/comparison-reference.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"comparison-reference.mjs","names":[],"sources":["../../src/capture/comparison-reference.ts"],"sourcesContent":["/** Freeze a baseline image under the consuming build so it survives baseline movement. */\nimport { createHash } from \"node:crypto\";\nimport { z } from \"zod\";\nimport { DEFAULT_BROWSER } from \"../adapters/capture-runner.ts\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { StorageAdapter } from \"../adapters/storage.ts\";\nimport { SnapshotModel } from \"../models/snapshot.ts\";\nimport type { Baseline } from \"../schema/baseline.ts\";\nimport { ulid } from \"../utils/ulid.ts\";\n\nconst referenceSchema = z.object({\n  version: z.literal(1),\n  baselineId: z.string(),\n  baselineVersion: z.string(),\n  branch: z.string(),\n  defaultBranch: z.boolean(),\n  sourceBuildId: z.string().nullable(),\n  sourceSnapshotId: z.string().nullable(),\n  imageSha256: z.string().regex(/^[a-f0-9]{64}$/u),\n  baselineFingerprint: z.string().nullable(),\n  captureFingerprint: z.string().nullable(),\n  mode: z.string().nullable(),\n  target: z.string(),\n  width: z.number().int().positive().nullable(),\n  height: z.number().int().positive().nullable(),\n});\nexport type ComparisonReference = z.infer<typeof referenceSchema>;\nexport interface ComparisonSettings {\n  defaultBranch: string;\n  mode: string | null;\n  target: string;\n  width: number | null;\n  height: number | null;\n  captureFingerprint: string | null;\n  sourceSnapshotId: string | null;\n}\n\nexport async function freezeComparison(\n  storage: StorageAdapter,\n  projectId: string,\n  buildId: string,\n  baseline: Baseline,\n  settings: ComparisonSettings,\n): Promise<{ comparisonImagePath: string; comparisonMetadata: string }> {\n  const image = await storage.read(baseline.screenshotPath);\n  const comparisonImagePath = `${projectId}/builds/${buildId}/comparisons/${ulid()}.png`;\n  const reference: ComparisonReference = {\n    version: 1,\n    baselineId: baseline.id,\n    baselineVersion: baseline.updatedAt,\n    branch: baseline.branch,\n    defaultBranch: baseline.branch === settings.defaultBranch,\n    sourceBuildId: baseline.sourceBuildId ?? null,\n    sourceSnapshotId: settings.sourceSnapshotId,\n    imageSha256: createHash(\"sha256\").update(image).digest(\"hex\"),\n    baselineFingerprint: baseline.fingerprint ?? null,\n    captureFingerprint: settings.captureFingerprint ?? null,\n    mode: settings.mode,\n    target: settings.target,\n    width: settings.width,\n    height: settings.height,\n  };\n  await storage.write(comparisonImagePath, image);\n  return { comparisonImagePath, comparisonMetadata: JSON.stringify(reference) };\n}\n\nexport function parseComparisonReference(\n  raw: string | null | undefined,\n): ComparisonReference | null {\n  if (!raw) return null;\n  try {\n    const parsed = referenceSchema.safeParse(JSON.parse(raw));\n    return parsed.success ? parsed.data : null;\n  } catch {\n    return null;\n  }\n}\n\n/** Reject paths outside the consuming build's dedicated comparison directory. */\nexport function isComparisonImagePath(path: string, projectId: string, buildId: string): boolean {\n  const prefix = `${projectId}/builds/${buildId}/comparisons/`;\n  return (\n    path.startsWith(prefix) && /^[0-9A-HJKMNP-TV-Z]{26}\\.png$/u.test(path.slice(prefix.length))\n  );\n}\n\n/** Identify a rendering snapshot only when its stored identity and image are provable. */\nexport async function sourceSnapshotId(\n  db: DatabaseAdapter,\n  baseline: Baseline,\n): Promise<string | null> {\n  if (!baseline.sourceBuildId || !baseline.snapshotId) return null;\n  const snapshot = await new SnapshotModel(db).get(baseline.snapshotId);\n  if (\n    !snapshot ||\n    snapshot.inherited ||\n    snapshot.buildId !== baseline.sourceBuildId ||\n    snapshot.projectId !== baseline.projectId ||\n    snapshot.storyId !== baseline.storyId ||\n    snapshot.viewportName !== baseline.viewportName ||\n    (snapshot.browser ?? DEFAULT_BROWSER) !== (baseline.browser ?? DEFAULT_BROWSER) ||\n    snapshot.screenshotPath !== baseline.screenshotPath\n  )\n    return null;\n  return snapshot.id;\n}\n"],"mappings":";;;;;;;;;;AAUA,MAAM,kBAAkB,EAAE,OAAO;CAC/B,SAAS,EAAE,QAAQ,CAAC;CACpB,YAAY,EAAE,OAAO;CACrB,iBAAiB,EAAE,OAAO;CAC1B,QAAQ,EAAE,OAAO;CACjB,eAAe,EAAE,QAAQ;CACzB,eAAe,EAAE,OAAO,CAAC,CAAC,SAAS;CACnC,kBAAkB,EAAE,OAAO,CAAC,CAAC,SAAS;CACtC,aAAa,EAAE,OAAO,CAAC,CAAC,MAAM,iBAAiB;CAC/C,qBAAqB,EAAE,OAAO,CAAC,CAAC,SAAS;CACzC,oBAAoB,EAAE,OAAO,CAAC,CAAC,SAAS;CACxC,MAAM,EAAE,OAAO,CAAC,CAAC,SAAS;CAC1B,QAAQ,EAAE,OAAO;CACjB,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS;CAC5C,QAAQ,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS;AAC/C,CAAC;AAYD,eAAsB,iBACpB,SACA,WACA,SACA,UACA,UACsE;CACtE,MAAM,QAAQ,MAAM,QAAQ,KAAK,SAAS,cAAc;CACxD,MAAM,sBAAsB,GAAG,UAAU,UAAU,QAAQ,eAAe,KAAK,EAAE;CACjF,MAAM,YAAiC;EACrC,SAAS;EACT,YAAY,SAAS;EACrB,iBAAiB,SAAS;EAC1B,QAAQ,SAAS;EACjB,eAAe,SAAS,WAAW,SAAS;EAC5C,eAAe,SAAS,iBAAiB;EACzC,kBAAkB,SAAS;EAC3B,aAAa,WAAW,QAAQ,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,KAAK;EAC5D,qBAAqB,SAAS,eAAe;EAC7C,oBAAoB,SAAS,sBAAsB;EACnD,MAAM,SAAS;EACf,QAAQ,SAAS;EACjB,OAAO,SAAS;EAChB,QAAQ,SAAS;CACnB;CACA,MAAM,QAAQ,MAAM,qBAAqB,KAAK;CAC9C,OAAO;EAAE;EAAqB,oBAAoB,KAAK,UAAU,SAAS;CAAE;AAC9E;AAEA,SAAgB,yBACd,KAC4B;CAC5B,IAAI,CAAC,KAAK,OAAO;CACjB,IAAI;EACF,MAAM,SAAS,gBAAgB,UAAU,KAAK,MAAM,GAAG,CAAC;EACxD,OAAO,OAAO,UAAU,OAAO,OAAO;CACxC,QAAQ;EACN,OAAO;CACT;AACF;;AAGA,SAAgB,sBAAsB,MAAc,WAAmB,SAA0B;CAC/F,MAAM,SAAS,GAAG,UAAU,UAAU,QAAQ;CAC9C,OACE,KAAK,WAAW,MAAM,KAAK,iCAAiC,KAAK,KAAK,MAAM,OAAO,MAAM,CAAC;AAE9F;;AAGA,eAAsB,iBACpB,IACA,UACwB;CACxB,IAAI,CAAC,SAAS,iBAAiB,CAAC,SAAS,YAAY,OAAO;CAC5D,MAAM,WAAW,MAAM,IAAI,cAAc,EAAE,CAAC,CAAC,IAAI,SAAS,UAAU;CACpE,IACE,CAAC,YACD,SAAS,aACT,SAAS,YAAY,SAAS,iBAC9B,SAAS,cAAc,SAAS,aAChC,SAAS,YAAY,SAAS,WAC9B,SAAS,iBAAiB,SAAS,iBAClC,SAAS,WAAA,iBAAiC,SAAS,WAAA,eACpD,SAAS,mBAAmB,SAAS,gBAErC,OAAO;CACT,OAAO,SAAS;AAClB"}

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

@@ -1,8 +1,8 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
+import { Logger } from "../../logger.mjs";
 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";
@@ -12,7 +12,6 @@ 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). */
@@ -53,6 +52,5 @@ interface CaptureHandlerOptions {
 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

@@ -6,7 +6,7 @@ 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
+// 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;
@@ -112,7 +112,6 @@ function originOf(options) {
 	});
 	return async () => await resolver.url();
 }
-//#endregion
 export { captureDispatchDeps, createCaptureHandler, originOf };
 
 //# sourceMappingURL=capture-handler.mjs.map

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

@@ -1,6 +1,5 @@
 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
@@ -12,6 +11,5 @@ declare const MIN_BLOCKING_POLL_MS = 1000;
 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

package/dist/capture/consumer/idle.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/capture/consumer/idle.ts
+// src/capture/consumer/idle.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
@@ -19,7 +19,6 @@ function idleDelayMs(emptyStreak) {
 function isFastEmptyPoll(elapsedMs) {
 	return elapsedMs < MIN_BLOCKING_POLL_MS;
 }
-//#endregion
 export { MIN_BLOCKING_POLL_MS, idleDelayMs, isFastEmptyPoll };
 
 //# sourceMappingURL=idle.mjs.map

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

@@ -5,9 +5,7 @@ import { ConsumerMetrics, DEFAULT_SAMPLE_MS, JobFinishedEvent, JobOutcome, Queue
 import { DEFAULT_BACKOFF_MS, DEFAULT_MAX_RETRIES, DEFAULT_WAIT_TIME_SECONDS, MAX_BACKOFF_MS, RetryConfig, backoffDelayMs, isFinalAttempt } from "./retry.mjs";
 import { CaptureConsumer, CaptureConsumerOptions, ConsumerConfig, ConsumerJob, JobHandlers, JobRunContext, KindHandler } from "./types.mjs";
 import { MIN_BLOCKING_POLL_MS, idleDelayMs, isFastEmptyPoll } from "./idle.mjs";
-//#region src/capture/consumer/index.d.ts
 /** Create a consumer of `options.queue`; nothing runs until `start()`. */
 declare function createCaptureConsumer(options: CaptureConsumerOptions): CaptureConsumer;
-//#endregion
 export { type CaptureConsumer, type CaptureConsumerOptions, type CaptureHandlerOptions, type ConsumerConfig, type ConsumerJob, type ConsumerMetrics, DEFAULT_BACKOFF_MS, DEFAULT_MAX_RETRIES, DEFAULT_SAMPLE_MS, DEFAULT_WAIT_TIME_SECONDS, type JobFinishedEvent, type JobHandlers, type JobOutcome, type JobRunContext, type KindHandler, MAX_BACKOFF_MS, MIN_BLOCKING_POLL_MS, type QueueSample, type RetryConfig, backoffDelayMs, captureDispatchDeps, createCaptureConsumer, createCaptureHandler, idleDelayMs, isFastEmptyPoll, isFinalAttempt, sampleQueue };
 //# sourceMappingURL=index.d.mts.map

package/dist/capture/consumer/index.mjs

@@ -12,7 +12,7 @@ import { startSlotLoop } from "./loop.mjs";
 import { DEFAULT_SAMPLE_MS, sampleQueue, startQueueSampling } from "./metrics.mjs";
 import { runJob } from "./run-job.mjs";
 import { applyImageSettings, ensureImageEngine, sweepScratch } from "./startup.mjs";
-//#region src/capture/consumer/index.ts
+// src/capture/consumer/index.ts
 /** Create a consumer of `options.queue`; nothing runs until `start()`. */
 function createCaptureConsumer(options) {
 	applyImageSettings(options.images, options.compare);
@@ -133,7 +133,6 @@ function registry(options, logger) {
 	for (const [kind, handler] of Object.entries(all)) if (handler !== void 0) map.set(kind, typeof handler === "function" ? { run: handler } : handler);
 	return map;
 }
-//#endregion
 export { DEFAULT_BACKOFF_MS, DEFAULT_MAX_RETRIES, DEFAULT_SAMPLE_MS, DEFAULT_WAIT_TIME_SECONDS, MAX_BACKOFF_MS, MIN_BLOCKING_POLL_MS, backoffDelayMs, captureDispatchDeps, createCaptureConsumer, createCaptureHandler, idleDelayMs, isFastEmptyPoll, isFinalAttempt, sampleQueue };
 
 //# sourceMappingURL=index.mjs.map

package/dist/capture/consumer/loop.mjs

@@ -3,7 +3,7 @@ import "node:url";
 import.meta.url;
 import { REAL_TIMERS } from "../db-queue/timers.mjs";
 import { idleDelayMs, isFastEmptyPoll } from "./idle.mjs";
-//#region src/capture/consumer/loop.ts
+// src/capture/consumer/loop.ts
 /** Pause after a failed poll. */
 const POLL_ERROR_DELAY_MS = 1e3;
 /** Start consuming `queue` with `slots` concurrent jobs. */
@@ -104,7 +104,6 @@ async function sleep(state, timers, ms) {
 	await promise;
 	if (handle !== null) clock.clearTimeout(handle);
 }
-//#endregion
 export { POLL_ERROR_DELAY_MS, startSlotLoop };
 
 //# sourceMappingURL=loop.mjs.map