@storyshelf/core 0.6.2 → 0.8.0

package/dist/models/baseline-conflict.mjs

@@ -0,0 +1,9 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/models/baseline-conflict.ts
+/** A baseline write lost a concurrency check and should be retried. */
+var BaselineWriteConflict = class extends Error {};
+export { BaselineWriteConflict };
+
+//# sourceMappingURL=baseline-conflict.mjs.map

package/dist/models/baseline-conflict.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-conflict.mjs","names":[],"sources":["../../src/models/baseline-conflict.ts"],"sourcesContent":["/** A baseline write lost a concurrency check and should be retried. */\nexport class BaselineWriteConflict extends Error {}\n"],"mappings":";;;;;AACA,IAAa,wBAAb,cAA2C,MAAM,CAAC"}

package/dist/models/baseline-export.d.mts

@@ -0,0 +1,17 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import "../adapter/storage.mjs";
+import { BaselineSkipped } from "./baseline-archive.mjs";
+/** Options for {@link exportBaselineArchive}. */
+interface BaselineExportOptions {
+  /** Export only this branch; omit (or null) for every branch. */
+  branch?: string | null;
+  /** Source project slug recorded in the manifest. */
+  project?: string | null;
+  /** Called for each baseline left out of the archive because its image is missing or too large. */
+  onSkipped?: (baseline: BaselineSkipped) => void;
+  /** Clock override for `exportedAt` (tests). */
+  now?: () => Date;
+}
+export { BaselineExportOptions };
+//# sourceMappingURL=baseline-export.d.mts.map

package/dist/models/baseline-export.mjs

@@ -0,0 +1,135 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import "../adapters/capture-target.mjs";
+import { BASELINE_ARCHIVE_FORMAT, BASELINE_ARCHIVE_LIMITS, BASELINE_MANIFEST_NAME, BaselineArchiveError, archiveFileName } from "./baseline-archive.mjs";
+import { zipStream } from "../utils/zip-write.mjs";
+import { createHash } from "node:crypto";
+// src/models/baseline-export.ts
+/** Stream a project's baselines as a portable zip archive (format v1). */
+/**
+* Prepare a baseline archive for `rows`. Validation (the entry limit) runs
+* eagerly so callers can fail the request before streaming; images are then
+* read one at a time while the returned iterable is consumed, and the
+* manifest is written last so it can carry each image's SHA-256. Baselines
+* whose image is missing (or over the per-image limit) are listed under
+* `skipped` and reported through `onSkipped`. Storage errors on an image that
+* exists abort the stream, as does outgrowing the archive size limit, so a
+* truncated stream is never mistaken for a complete backup.
+*
+* @throws {BaselineArchiveError} When there are more baselines than an archive may hold.
+*/
+function exportBaselineArchive(storage, rows, options = {}) {
+	const branch = options.branch ?? null;
+	const selected = rows.filter((row) => branch === null || row.branch === branch).toSorted((a, b) => compareKeys(sortKey(a), sortKey(b)));
+	if (selected.length > BASELINE_ARCHIVE_LIMITS.maxBaselines) throw new BaselineArchiveError(`Too many baselines to export (${selected.length} > ${BASELINE_ARCHIVE_LIMITS.maxBaselines}); filter by branch`);
+	const manifest = {
+		format: BASELINE_ARCHIVE_FORMAT,
+		version: 1,
+		exportedAt: (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString(),
+		project: options.project ?? null,
+		branch,
+		baselines: [],
+		skipped: []
+	};
+	return zipStream(archiveSources(storage, selected, manifest, options.onSkipped));
+}
+function sortKey(row) {
+	return [
+		row.branch,
+		row.storyId,
+		row.viewportName,
+		row.browser ?? "chromium"
+	];
+}
+function compareKeys(a, b) {
+	const index = a.findIndex((part, at) => part !== b[at]);
+	if (index === -1) return 0;
+	return (a[index] ?? "") < (b[index] ?? "") ? -1 : 1;
+}
+async function* archiveSources(storage, rows, manifest, onSkipped) {
+	const state = {
+		names: /* @__PURE__ */ new Set(),
+		budget: new ArchiveBudget()
+	};
+	for (const row of rows) {
+		const source = await rowSource(storage, row, manifest, state, onSkipped);
+		if (source) yield source;
+	}
+	const json = Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`);
+	yield {
+		name: BASELINE_MANIFEST_NAME,
+		data: json
+	};
+}
+/** The zip entry for one baseline, or null (after recording it as skipped) when its image is unavailable. */
+async function rowSource(storage, row, manifest, state, onSkipped) {
+	const data = await readImage(storage, row);
+	if (!data) {
+		const identity = identityOf(row);
+		manifest.skipped?.push(identity);
+		onSkipped?.(identity);
+		return null;
+	}
+	const entry = manifestEntry(row, data, state.names);
+	state.budget.add(entry.file, data.length);
+	manifest.baselines.push(entry);
+	return {
+		name: entry.file,
+		data
+	};
+}
+/** Tracks the streamed size so an export never outgrows what an import accepts. */
+var ArchiveBudget = class ArchiveBudget {
+	/** Zip local + central header bytes per entry, excluding the (twice-stored) name. */
+	static ENTRY_OVERHEAD = 76;
+	used = BASELINE_ARCHIVE_LIMITS.maxManifestBytes;
+	add(name, bytes) {
+		this.used += ArchiveBudget.ENTRY_OVERHEAD + Buffer.byteLength(name) * 2 + bytes;
+		if (this.used > BASELINE_ARCHIVE_LIMITS.maxArchiveBytes) throw new BaselineArchiveError(`Export exceeds ${BASELINE_ARCHIVE_LIMITS.maxArchiveBytes} bytes (the import limit); export one branch at a time`);
+	}
+};
+/** Read a baseline image; null when it is missing or too large, throws on other storage errors. */
+async function readImage(storage, row) {
+	try {
+		const data = await storage.read(row.screenshotPath);
+		return data.length <= BASELINE_ARCHIVE_LIMITS.maxImageBytes ? data : null;
+	} catch (error) {
+		if (await storage.exists(row.screenshotPath).catch(() => false)) throw error;
+		return null;
+	}
+}
+function identityOf(row) {
+	return {
+		storyId: row.storyId,
+		viewport: row.viewportName,
+		browser: row.browser ?? "chromium",
+		branch: row.branch
+	};
+}
+function manifestEntry(row, data, names) {
+	const identity = identityOf(row);
+	return {
+		...identity,
+		mode: row.mode ?? null,
+		infraHash: row.infraHash,
+		fingerprint: row.fingerprint ?? null,
+		createdAt: row.createdAt,
+		updatedAt: row.updatedAt,
+		file: uniqueName(archiveFileName(identity.branch, identity.storyId, identity.viewport, identity.browser), names),
+		sha256: createHash("sha256").update(data).digest("hex")
+	};
+}
+/**
+* `modeSegment` can map two identities to one name (`a~firefox` on chromium vs
+* `a` on firefox). Names are only lookup keys, so disambiguate with a suffix.
+*/
+function uniqueName(name, names) {
+	let candidate = name;
+	for (let n = 2; names.has(candidate); n += 1) candidate = name.replace(/\.png$/u, `.${n}.png`);
+	names.add(candidate);
+	return candidate;
+}
+export { exportBaselineArchive };
+
+//# sourceMappingURL=baseline-export.mjs.map

package/dist/models/baseline-export.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-export.mjs","names":[],"sources":["../../src/models/baseline-export.ts"],"sourcesContent":["/** Stream a project's baselines as a portable zip archive (format v1). */\nimport { createHash } from \"node:crypto\";\nimport { DEFAULT_BROWSER } from \"../adapters/capture-runner.ts\";\nimport type { StorageAdapter } from \"../adapters/storage.ts\";\nimport type { Baseline } from \"../schema/baseline.ts\";\nimport { zipStream, type ZipSource } from \"../utils/zip-write.ts\";\nimport {\n  archiveFileName,\n  BASELINE_ARCHIVE_FORMAT,\n  BASELINE_ARCHIVE_LIMITS,\n  BASELINE_ARCHIVE_VERSION,\n  BASELINE_MANIFEST_NAME,\n  BaselineArchiveError,\n  type BaselineManifest,\n  type BaselineManifestEntry,\n  type BaselineSkipped,\n} from \"./baseline-archive.ts\";\n\n/** Options for {@link exportBaselineArchive}. */\nexport interface BaselineExportOptions {\n  /** Export only this branch; omit (or null) for every branch. */\n  branch?: string | null;\n  /** Source project slug recorded in the manifest. */\n  project?: string | null;\n  /** Called for each baseline left out of the archive because its image is missing or too large. */\n  onSkipped?: (baseline: BaselineSkipped) => void;\n  /** Clock override for `exportedAt` (tests). */\n  now?: () => Date;\n}\n\n/**\n * Prepare a baseline archive for `rows`. Validation (the entry limit) runs\n * eagerly so callers can fail the request before streaming; images are then\n * read one at a time while the returned iterable is consumed, and the\n * manifest is written last so it can carry each image's SHA-256. Baselines\n * whose image is missing (or over the per-image limit) are listed under\n * `skipped` and reported through `onSkipped`. Storage errors on an image that\n * exists abort the stream, as does outgrowing the archive size limit, so a\n * truncated stream is never mistaken for a complete backup.\n *\n * @throws {BaselineArchiveError} When there are more baselines than an archive may hold.\n */\nexport function exportBaselineArchive(\n  storage: StorageAdapter,\n  rows: Baseline[],\n  options: BaselineExportOptions = {},\n): AsyncIterable<Buffer> {\n  const branch = options.branch ?? null;\n  const selected = rows\n    .filter((row) => branch === null || row.branch === branch)\n    .toSorted((a, b) => compareKeys(sortKey(a), sortKey(b)));\n  if (selected.length > BASELINE_ARCHIVE_LIMITS.maxBaselines) {\n    throw new BaselineArchiveError(\n      `Too many baselines to export (${selected.length} > ${BASELINE_ARCHIVE_LIMITS.maxBaselines}); filter by branch`,\n    );\n  }\n  const manifest: BaselineManifest = {\n    format: BASELINE_ARCHIVE_FORMAT,\n    version: BASELINE_ARCHIVE_VERSION,\n    exportedAt: (options.now?.() ?? new Date()).toISOString(),\n    project: options.project ?? null,\n    branch,\n    baselines: [],\n    skipped: [],\n  };\n  return zipStream(archiveSources(storage, selected, manifest, options.onSkipped));\n}\n\nfunction sortKey(row: Baseline): string[] {\n  return [row.branch, row.storyId, row.viewportName, row.browser ?? DEFAULT_BROWSER];\n}\n\nfunction compareKeys(a: string[], b: string[]): number {\n  const index = a.findIndex((part, at) => part !== b[at]);\n  if (index === -1) {\n    return 0;\n  }\n  // Code-unit order, not locale order, so archives are reproducible across hosts.\n  return (a[index] ?? \"\") < (b[index] ?? \"\") ? -1 : 1;\n}\n\nasync function* archiveSources(\n  storage: StorageAdapter,\n  rows: Baseline[],\n  manifest: BaselineManifest,\n  onSkipped?: (baseline: BaselineSkipped) => void,\n): AsyncGenerator<ZipSource> {\n  const state = { names: new Set<string>(), budget: new ArchiveBudget() };\n  for (const row of rows) {\n    // oxlint-disable-next-line eslint/no-await-in-loop -- one image in memory at a time\n    const source = await rowSource(storage, row, manifest, state, onSkipped);\n    if (source) {\n      yield source;\n    }\n  }\n  const json = Buffer.from(`${JSON.stringify(manifest, null, 2)}\\n`);\n  yield { name: BASELINE_MANIFEST_NAME, data: json };\n}\n\n/** The zip entry for one baseline, or null (after recording it as skipped) when its image is unavailable. */\nasync function rowSource(\n  storage: StorageAdapter,\n  row: Baseline,\n  manifest: BaselineManifest,\n  state: { names: Set<string>; budget: ArchiveBudget },\n  onSkipped?: (baseline: BaselineSkipped) => void,\n): Promise<ZipSource | null> {\n  const data = await readImage(storage, row);\n  if (!data) {\n    const identity = identityOf(row);\n    manifest.skipped?.push(identity);\n    onSkipped?.(identity);\n    return null;\n  }\n  const entry = manifestEntry(row, data, state.names);\n  state.budget.add(entry.file, data.length);\n  manifest.baselines.push(entry);\n  return { name: entry.file, data };\n}\n\n/** Tracks the streamed size so an export never outgrows what an import accepts. */\nclass ArchiveBudget {\n  /** Zip local + central header bytes per entry, excluding the (twice-stored) name. */\n  private static readonly ENTRY_OVERHEAD = 76;\n  private used = BASELINE_ARCHIVE_LIMITS.maxManifestBytes;\n\n  add(name: string, bytes: number): void {\n    this.used += ArchiveBudget.ENTRY_OVERHEAD + Buffer.byteLength(name) * 2 + bytes;\n    if (this.used > BASELINE_ARCHIVE_LIMITS.maxArchiveBytes) {\n      throw new BaselineArchiveError(\n        `Export exceeds ${BASELINE_ARCHIVE_LIMITS.maxArchiveBytes} bytes (the import limit); export one branch at a time`,\n      );\n    }\n  }\n}\n\n/** Read a baseline image; null when it is missing or too large, throws on other storage errors. */\nasync function readImage(storage: StorageAdapter, row: Baseline): Promise<Buffer | null> {\n  try {\n    const data = await storage.read(row.screenshotPath);\n    return data.length <= BASELINE_ARCHIVE_LIMITS.maxImageBytes ? data : null;\n  } catch (error) {\n    if (await storage.exists(row.screenshotPath).catch(() => false)) {\n      throw error;\n    }\n    return null;\n  }\n}\n\nfunction identityOf(row: Baseline): BaselineSkipped {\n  return {\n    storyId: row.storyId,\n    viewport: row.viewportName,\n    browser: row.browser ?? DEFAULT_BROWSER,\n    branch: row.branch,\n  };\n}\n\nfunction manifestEntry(row: Baseline, data: Buffer, names: Set<string>): BaselineManifestEntry {\n  const identity = identityOf(row);\n  return {\n    ...identity,\n    mode: row.mode ?? null,\n    infraHash: row.infraHash,\n    fingerprint: row.fingerprint ?? null,\n    createdAt: row.createdAt,\n    updatedAt: row.updatedAt,\n    file: uniqueName(\n      archiveFileName(identity.branch, identity.storyId, identity.viewport, identity.browser),\n      names,\n    ),\n    sha256: createHash(\"sha256\").update(data).digest(\"hex\"),\n  };\n}\n\n/**\n * `modeSegment` can map two identities to one name (`a~firefox` on chromium vs\n * `a` on firefox). Names are only lookup keys, so disambiguate with a suffix.\n */\nfunction uniqueName(name: string, names: Set<string>): string {\n  let candidate = name;\n  for (let n = 2; names.has(candidate); n += 1) {\n    candidate = name.replace(/\\.png$/u, `.${n}.png`);\n  }\n  names.add(candidate);\n  return candidate;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AA0CA,SAAgB,sBACd,SACA,MACA,UAAiC,CAAC,GACX;CACvB,MAAM,SAAS,QAAQ,UAAU;CACjC,MAAM,WAAW,KACd,QAAQ,QAAQ,WAAW,QAAQ,IAAI,WAAW,MAAM,CAAC,CACzD,UAAU,GAAG,MAAM,YAAY,QAAQ,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;CACzD,IAAI,SAAS,SAAS,wBAAwB,cAC5C,MAAM,IAAI,qBACR,iCAAiC,SAAS,OAAO,KAAK,wBAAwB,aAAa,oBAC7F;CAEF,MAAM,WAA6B;EACjC,QAAQ;EACR,SAAA;EACA,aAAa,QAAQ,MAAM,qBAAK,IAAI,KAAK,EAAA,CAAG,YAAY;EACxD,SAAS,QAAQ,WAAW;EAC5B;EACA,WAAW,CAAC;EACZ,SAAS,CAAC;CACZ;CACA,OAAO,UAAU,eAAe,SAAS,UAAU,UAAU,QAAQ,SAAS,CAAC;AACjF;AAEA,SAAS,QAAQ,KAAyB;CACxC,OAAO;EAAC,IAAI;EAAQ,IAAI;EAAS,IAAI;EAAc,IAAI,WAAA;CAA0B;AACnF;AAEA,SAAS,YAAY,GAAa,GAAqB;CACrD,MAAM,QAAQ,EAAE,WAAW,MAAM,OAAO,SAAS,EAAE,GAAG;CACtD,IAAI,UAAU,IACZ,OAAO;CAGT,QAAQ,EAAE,UAAU,OAAO,EAAE,UAAU,MAAM,KAAK;AACpD;AAEA,gBAAgB,eACd,SACA,MACA,UACA,WAC2B;CAC3B,MAAM,QAAQ;EAAE,uBAAO,IAAI,IAAY;EAAG,QAAQ,IAAI,cAAc;CAAE;CACtE,KAAK,MAAM,OAAO,MAAM;EAEtB,MAAM,SAAS,MAAM,UAAU,SAAS,KAAK,UAAU,OAAO,SAAS;EACvE,IAAI,QACF,MAAM;CAEV;CACA,MAAM,OAAO,OAAO,KAAK,GAAG,KAAK,UAAU,UAAU,MAAM,CAAC,EAAE,GAAG;CACjE,MAAM;EAAE,MAAM;EAAwB,MAAM;CAAK;AACnD;;AAGA,eAAe,UACb,SACA,KACA,UACA,OACA,WAC2B;CAC3B,MAAM,OAAO,MAAM,UAAU,SAAS,GAAG;CACzC,IAAI,CAAC,MAAM;EACT,MAAM,WAAW,WAAW,GAAG;EAC/B,SAAS,SAAS,KAAK,QAAQ;EAC/B,YAAY,QAAQ;EACpB,OAAO;CACT;CACA,MAAM,QAAQ,cAAc,KAAK,MAAM,MAAM,KAAK;CAClD,MAAM,OAAO,IAAI,MAAM,MAAM,KAAK,MAAM;CACxC,SAAS,UAAU,KAAK,KAAK;CAC7B,OAAO;EAAE,MAAM,MAAM;EAAM;CAAK;AAClC;;AAGA,IAAM,gBAAN,MAAM,cAAc;;CAElB,OAAwB,iBAAiB;CACzC,OAAe,wBAAwB;CAEvC,IAAI,MAAc,OAAqB;EACrC,KAAK,QAAQ,cAAc,iBAAiB,OAAO,WAAW,IAAI,IAAI,IAAI;EAC1E,IAAI,KAAK,OAAO,wBAAwB,iBACtC,MAAM,IAAI,qBACR,kBAAkB,wBAAwB,gBAAgB,uDAC5D;CAEJ;AACF;;AAGA,eAAe,UAAU,SAAyB,KAAuC;CACvF,IAAI;EACF,MAAM,OAAO,MAAM,QAAQ,KAAK,IAAI,cAAc;EAClD,OAAO,KAAK,UAAU,wBAAwB,gBAAgB,OAAO;CACvE,SAAS,OAAO;EACd,IAAI,MAAM,QAAQ,OAAO,IAAI,cAAc,CAAC,CAAC,YAAY,KAAK,GAC5D,MAAM;EAER,OAAO;CACT;AACF;AAEA,SAAS,WAAW,KAAgC;CAClD,OAAO;EACL,SAAS,IAAI;EACb,UAAU,IAAI;EACd,SAAS,IAAI,WAAA;EACb,QAAQ,IAAI;CACd;AACF;AAEA,SAAS,cAAc,KAAe,MAAc,OAA2C;CAC7F,MAAM,WAAW,WAAW,GAAG;CAC/B,OAAO;EACL,GAAG;EACH,MAAM,IAAI,QAAQ;EAClB,WAAW,IAAI;EACf,aAAa,IAAI,eAAe;EAChC,WAAW,IAAI;EACf,WAAW,IAAI;EACf,MAAM,WACJ,gBAAgB,SAAS,QAAQ,SAAS,SAAS,SAAS,UAAU,SAAS,OAAO,GACtF,KACF;EACA,QAAQ,WAAW,QAAQ,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,KAAK;CACxD;AACF;;;;;AAMA,SAAS,WAAW,MAAc,OAA4B;CAC5D,IAAI,YAAY;CAChB,KAAK,IAAI,IAAI,GAAG,MAAM,IAAI,SAAS,GAAG,KAAK,GACzC,YAAY,KAAK,QAAQ,WAAW,IAAI,EAAE,KAAK;CAEjD,MAAM,IAAI,SAAS;CACnB,OAAO;AACT"}

package/dist/models/baseline-import.mjs

@@ -0,0 +1,117 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { baselinePath, contentPath } from "../paths.mjs";
+import { BASELINE_ARCHIVE_LIMITS, BASELINE_MANIFEST_NAME, BaselineArchiveError, baselineIdentity, baselineManifestSchema, isPng } from "./baseline-archive.mjs";
+import { ZipFormatError, readZip } from "../utils/zip-read.mjs";
+import { createHash } from "node:crypto";
+import { setImmediate } from "node:timers/promises";
+// src/models/baseline-import.ts
+/**
+* Validate and apply a baseline archive (format v1).
+*
+* All-or-nothing validation: the manifest, every identity (through the same
+* segment checks as {@link baselinePath}), every image's size, PNG signature
+* and SHA-256 are verified before the first write. Storage paths are always
+* derived from the manifest identity — never from zip entry names.
+*/
+/**
+* Parse and fully validate `archive` for import into `projectId`. Inflating and
+* hashing is CPU-bound, so the loop yields to the event loop between entries
+* instead of blocking the server for the whole archive.
+*
+* @throws {BaselineArchiveError} On any malformed, unsafe, or inconsistent input.
+*/
+async function planBaselineImport(archive, projectId) {
+	const entries = openArchive(archive);
+	const manifest = parseManifest(entries);
+	const seen = /* @__PURE__ */ new Set();
+	const plan = [];
+	for (const entry of manifest.baselines) {
+		claimEntry(seen, entry);
+		plan.push(planEntry(entries, projectId, entry));
+		await setImmediate();
+	}
+	return plan;
+}
+/** Reject repeated identities or files, so total work stays bounded by the archive's own size limit. */
+function claimEntry(seen, entry) {
+	const keys = [baselineIdentity(entry), `file:${entry.file}`];
+	if (keys.some((key) => seen.has(key))) fail(`Duplicate baseline or file in manifest: ${entry.file}`);
+	for (const key of keys) seen.add(key);
+}
+/** Write a planned baseline's image to storage. */
+async function writePlannedImage(storage, planned) {
+	if (!await storage.exists(planned.storagePath)) await storage.write(planned.storagePath, planned.data);
+}
+function fail(message) {
+	throw new BaselineArchiveError(message);
+}
+function openArchive(archive) {
+	try {
+		return readZip(archive, {
+			maxEntries: BASELINE_ARCHIVE_LIMITS.maxBaselines + 1,
+			maxEntryBytes: Math.max(BASELINE_ARCHIVE_LIMITS.maxImageBytes, BASELINE_ARCHIVE_LIMITS.maxManifestBytes),
+			maxTotalBytes: BASELINE_ARCHIVE_LIMITS.maxArchiveBytes
+		});
+	} catch (error) {
+		if (error instanceof ZipFormatError) fail(error.message);
+		throw error;
+	}
+}
+function parseManifest(entries) {
+	const file = entries.get(BASELINE_MANIFEST_NAME);
+	if (!file) fail(`Archive has no ${BASELINE_MANIFEST_NAME}`);
+	if (file.size > BASELINE_ARCHIVE_LIMITS.maxManifestBytes) fail(`${BASELINE_MANIFEST_NAME} exceeds ${BASELINE_ARCHIVE_LIMITS.maxManifestBytes} bytes`);
+	const parsed = baselineManifestSchema.safeParse(parseJson(file.read().toString("utf8")));
+	if (!parsed.success) {
+		const issue = parsed.error.issues[0];
+		fail(`Invalid ${BASELINE_MANIFEST_NAME}: ${issue?.path.join(".") ?? ""} ${issue?.message ?? ""}`);
+	}
+	return parsed.data;
+}
+function parseJson(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return fail(`${BASELINE_MANIFEST_NAME} is not valid JSON`);
+	}
+}
+function planEntry(entries, projectId, entry) {
+	const zipEntry = entries.get(entry.file);
+	if (!zipEntry || entry.file === "manifest.json") fail(`Archive is missing ${entry.file}`);
+	if (zipEntry.size > BASELINE_ARCHIVE_LIMITS.maxImageBytes) fail(`${entry.file} exceeds ${BASELINE_ARCHIVE_LIMITS.maxImageBytes} bytes`);
+	assertSafeIdentity(projectId, entry);
+	const data = verifiedImage(zipEntry, entry);
+	return {
+		entry,
+		storagePath: contentPath(projectId, createHash("sha256").update(data).digest("hex")),
+		zipEntry,
+		data
+	};
+}
+/** The identity only has to be safe here: the image itself is stored by content. */
+function assertSafeIdentity(projectId, entry) {
+	try {
+		baselinePath(projectId, entry.branch, entry.storyId, entry.viewport, entry.browser);
+	} catch {
+		fail(`Unsafe baseline identity for ${entry.file}`);
+	}
+}
+function verifiedImage(zipEntry, entry) {
+	const data = readEntry(zipEntry);
+	if (!isPng(data)) fail(`${entry.file} is not a PNG`);
+	if (createHash("sha256").update(data).digest("hex") !== entry.sha256) fail(`${entry.file} does not match its manifest checksum`);
+	return data;
+}
+function readEntry(zipEntry) {
+	try {
+		return zipEntry.read();
+	} catch (error) {
+		if (error instanceof ZipFormatError) return fail(error.message);
+		throw error;
+	}
+}
+export { planBaselineImport, writePlannedImage };
+
+//# sourceMappingURL=baseline-import.mjs.map

package/dist/models/baseline-import.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-import.mjs","names":[],"sources":["../../src/models/baseline-import.ts"],"sourcesContent":["/**\n * Validate and apply a baseline archive (format v1).\n *\n * All-or-nothing validation: the manifest, every identity (through the same\n * segment checks as {@link baselinePath}), every image's size, PNG signature\n * and SHA-256 are verified before the first write. Storage paths are always\n * derived from the manifest identity — never from zip entry names.\n */\nimport { createHash } from \"node:crypto\";\nimport { setImmediate } from \"node:timers/promises\";\nimport type { StorageAdapter } from \"../adapters/storage.ts\";\nimport { baselinePath, contentPath } from \"../utils/paths.ts\";\nimport { readZip, ZipFormatError, type ZipEntry } from \"../utils/zip-read.ts\";\nimport {\n  BASELINE_ARCHIVE_LIMITS,\n  BASELINE_MANIFEST_NAME,\n  BaselineArchiveError,\n  baselineIdentity,\n  baselineManifestSchema,\n  isPng,\n  type BaselineManifest,\n  type BaselineManifestEntry,\n} from \"./baseline-archive.ts\";\n\n/** A validated baseline ready to write. */\nexport interface PlannedBaseline {\n  entry: BaselineManifestEntry;\n  /** Content-addressed destination inside the importing project. */\n  storagePath: string;\n  zipEntry: ZipEntry;\n  /** The verified PNG bytes, extracted once during planning. */\n  data: Buffer;\n}\n\n/**\n * Parse and fully validate `archive` for import into `projectId`. Inflating and\n * hashing is CPU-bound, so the loop yields to the event loop between entries\n * instead of blocking the server for the whole archive.\n *\n * @throws {BaselineArchiveError} On any malformed, unsafe, or inconsistent input.\n */\nexport async function planBaselineImport(\n  archive: Buffer,\n  projectId: string,\n): Promise<PlannedBaseline[]> {\n  const entries = openArchive(archive);\n  const manifest = parseManifest(entries);\n  const seen = new Set<string>();\n  const plan: PlannedBaseline[] = [];\n  for (const entry of manifest.baselines) {\n    claimEntry(seen, entry);\n    plan.push(planEntry(entries, projectId, entry));\n    // oxlint-disable-next-line eslint/no-await-in-loop -- deliberate yield between CPU-bound entries\n    await setImmediate();\n  }\n  return plan;\n}\n\n/** Reject repeated identities or files, so total work stays bounded by the archive's own size limit. */\nfunction claimEntry(seen: Set<string>, entry: BaselineManifestEntry): void {\n  const keys = [baselineIdentity(entry), `file:${entry.file}`];\n  if (keys.some((key) => seen.has(key))) {\n    fail(`Duplicate baseline or file in manifest: ${entry.file}`);\n  }\n  for (const key of keys) {\n    seen.add(key);\n  }\n}\n\n/** Write a planned baseline's image to storage. */\nexport async function writePlannedImage(\n  storage: StorageAdapter,\n  planned: PlannedBaseline,\n): Promise<void> {\n  if (!(await storage.exists(planned.storagePath))) {\n    await storage.write(planned.storagePath, planned.data);\n  }\n}\n\nfunction fail(message: string): never {\n  throw new BaselineArchiveError(message);\n}\n\nfunction openArchive(archive: Buffer): Map<string, ZipEntry> {\n  try {\n    return readZip(archive, {\n      maxEntries: BASELINE_ARCHIVE_LIMITS.maxBaselines + 1,\n      maxEntryBytes: Math.max(\n        BASELINE_ARCHIVE_LIMITS.maxImageBytes,\n        BASELINE_ARCHIVE_LIMITS.maxManifestBytes,\n      ),\n      maxTotalBytes: BASELINE_ARCHIVE_LIMITS.maxArchiveBytes,\n    });\n  } catch (error) {\n    if (error instanceof ZipFormatError) {\n      fail(error.message);\n    }\n    throw error;\n  }\n}\n\nfunction parseManifest(entries: Map<string, ZipEntry>): BaselineManifest {\n  const file = entries.get(BASELINE_MANIFEST_NAME);\n  if (!file) {\n    fail(`Archive has no ${BASELINE_MANIFEST_NAME}`);\n  }\n  if (file.size > BASELINE_ARCHIVE_LIMITS.maxManifestBytes) {\n    fail(`${BASELINE_MANIFEST_NAME} exceeds ${BASELINE_ARCHIVE_LIMITS.maxManifestBytes} bytes`);\n  }\n  const parsed = baselineManifestSchema.safeParse(parseJson(file.read().toString(\"utf8\")));\n  if (!parsed.success) {\n    const issue = parsed.error.issues[0];\n    fail(\n      `Invalid ${BASELINE_MANIFEST_NAME}: ${issue?.path.join(\".\") ?? \"\"} ${issue?.message ?? \"\"}`,\n    );\n  }\n  return parsed.data;\n}\n\nfunction parseJson(text: string): unknown {\n  try {\n    return JSON.parse(text) as unknown;\n  } catch {\n    return fail(`${BASELINE_MANIFEST_NAME} is not valid JSON`);\n  }\n}\n\nfunction planEntry(\n  entries: Map<string, ZipEntry>,\n  projectId: string,\n  entry: BaselineManifestEntry,\n): PlannedBaseline {\n  const zipEntry = entries.get(entry.file);\n  if (!zipEntry || entry.file === BASELINE_MANIFEST_NAME) {\n    fail(`Archive is missing ${entry.file}`);\n  }\n  if (zipEntry.size > BASELINE_ARCHIVE_LIMITS.maxImageBytes) {\n    fail(`${entry.file} exceeds ${BASELINE_ARCHIVE_LIMITS.maxImageBytes} bytes`);\n  }\n  assertSafeIdentity(projectId, entry);\n  const data = verifiedImage(zipEntry, entry);\n  const storagePath = contentPath(projectId, createHash(\"sha256\").update(data).digest(\"hex\"));\n  return { entry, storagePath, zipEntry, data };\n}\n\n/** The identity only has to be safe here: the image itself is stored by content. */\nfunction assertSafeIdentity(projectId: string, entry: BaselineManifestEntry): void {\n  try {\n    baselinePath(projectId, entry.branch, entry.storyId, entry.viewport, entry.browser);\n  } catch {\n    fail(`Unsafe baseline identity for ${entry.file}`);\n  }\n}\n\nfunction verifiedImage(zipEntry: ZipEntry, entry: BaselineManifestEntry): Buffer {\n  const data = readEntry(zipEntry);\n  if (!isPng(data)) {\n    fail(`${entry.file} is not a PNG`);\n  }\n  if (createHash(\"sha256\").update(data).digest(\"hex\") !== entry.sha256) {\n    fail(`${entry.file} does not match its manifest checksum`);\n  }\n  return data;\n}\n\nfunction readEntry(zipEntry: ZipEntry): Buffer {\n  try {\n    return zipEntry.read();\n  } catch (error) {\n    if (error instanceof ZipFormatError) {\n      return fail(error.message);\n    }\n    throw error;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAyCA,eAAsB,mBACpB,SACA,WAC4B;CAC5B,MAAM,UAAU,YAAY,OAAO;CACnC,MAAM,WAAW,cAAc,OAAO;CACtC,MAAM,uBAAO,IAAI,IAAY;CAC7B,MAAM,OAA0B,CAAC;CACjC,KAAK,MAAM,SAAS,SAAS,WAAW;EACtC,WAAW,MAAM,KAAK;EACtB,KAAK,KAAK,UAAU,SAAS,WAAW,KAAK,CAAC;EAE9C,MAAM,aAAa;CACrB;CACA,OAAO;AACT;;AAGA,SAAS,WAAW,MAAmB,OAAoC;CACzE,MAAM,OAAO,CAAC,iBAAiB,KAAK,GAAG,QAAQ,MAAM,MAAM;CAC3D,IAAI,KAAK,MAAM,QAAQ,KAAK,IAAI,GAAG,CAAC,GAClC,KAAK,2CAA2C,MAAM,MAAM;CAE9D,KAAK,MAAM,OAAO,MAChB,KAAK,IAAI,GAAG;AAEhB;;AAGA,eAAsB,kBACpB,SACA,SACe;CACf,IAAI,CAAE,MAAM,QAAQ,OAAO,QAAQ,WAAW,GAC5C,MAAM,QAAQ,MAAM,QAAQ,aAAa,QAAQ,IAAI;AAEzD;AAEA,SAAS,KAAK,SAAwB;CACpC,MAAM,IAAI,qBAAqB,OAAO;AACxC;AAEA,SAAS,YAAY,SAAwC;CAC3D,IAAI;EACF,OAAO,QAAQ,SAAS;GACtB,YAAY,wBAAwB,eAAe;GACnD,eAAe,KAAK,IAClB,wBAAwB,eACxB,wBAAwB,gBAC1B;GACA,eAAe,wBAAwB;EACzC,CAAC;CACH,SAAS,OAAO;EACd,IAAI,iBAAiB,gBACnB,KAAK,MAAM,OAAO;EAEpB,MAAM;CACR;AACF;AAEA,SAAS,cAAc,SAAkD;CACvE,MAAM,OAAO,QAAQ,IAAI,sBAAsB;CAC/C,IAAI,CAAC,MACH,KAAK,kBAAkB,wBAAwB;CAEjD,IAAI,KAAK,OAAO,wBAAwB,kBACtC,KAAK,GAAG,uBAAuB,WAAW,wBAAwB,iBAAiB,OAAO;CAE5F,MAAM,SAAS,uBAAuB,UAAU,UAAU,KAAK,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,CAAC;CACvF,IAAI,CAAC,OAAO,SAAS;EACnB,MAAM,QAAQ,OAAO,MAAM,OAAO;EAClC,KACE,WAAW,uBAAuB,IAAI,OAAO,KAAK,KAAK,GAAG,KAAK,GAAG,GAAG,OAAO,WAAW,IACzF;CACF;CACA,OAAO,OAAO;AAChB;AAEA,SAAS,UAAU,MAAuB;CACxC,IAAI;EACF,OAAO,KAAK,MAAM,IAAI;CACxB,QAAQ;EACN,OAAO,KAAK,GAAG,uBAAuB,mBAAmB;CAC3D;AACF;AAEA,SAAS,UACP,SACA,WACA,OACiB;CACjB,MAAM,WAAW,QAAQ,IAAI,MAAM,IAAI;CACvC,IAAI,CAAC,YAAY,MAAM,SAAA,iBACrB,KAAK,sBAAsB,MAAM,MAAM;CAEzC,IAAI,SAAS,OAAO,wBAAwB,eAC1C,KAAK,GAAG,MAAM,KAAK,WAAW,wBAAwB,cAAc,OAAO;CAE7E,mBAAmB,WAAW,KAAK;CACnC,MAAM,OAAO,cAAc,UAAU,KAAK;CAE1C,OAAO;EAAE;EAAO,aADI,YAAY,WAAW,WAAW,QAAQ,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,KAAK,CAC/D;EAAG;EAAU;CAAK;AAC9C;;AAGA,SAAS,mBAAmB,WAAmB,OAAoC;CACjF,IAAI;EACF,aAAa,WAAW,MAAM,QAAQ,MAAM,SAAS,MAAM,UAAU,MAAM,OAAO;CACpF,QAAQ;EACN,KAAK,gCAAgC,MAAM,MAAM;CACnD;AACF;AAEA,SAAS,cAAc,UAAoB,OAAsC;CAC/E,MAAM,OAAO,UAAU,QAAQ;CAC/B,IAAI,CAAC,MAAM,IAAI,GACb,KAAK,GAAG,MAAM,KAAK,cAAc;CAEnC,IAAI,WAAW,QAAQ,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,KAAK,MAAM,MAAM,QAC5D,KAAK,GAAG,MAAM,KAAK,sCAAsC;CAE3D,OAAO;AACT;AAEA,SAAS,UAAU,UAA4B;CAC7C,IAAI;EACF,OAAO,SAAS,KAAK;CACvB,SAAS,OAAO;EACd,IAAI,iBAAiB,gBACnB,OAAO,KAAK,MAAM,OAAO;EAE3B,MAAM;CACR;AACF"}

package/dist/models/baseline-origin.d.mts

@@ -0,0 +1,16 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Build } from "../schema/build.mjs";
+import { Baseline } from "../schema/baseline.mjs";
+import { Snapshot } from "../schema/snapshot.mjs";
+import "../schema.mjs";
+/** The records needed to prove which build rendered a baseline image. */
+interface BaselineOriginReader {
+  baseline(id: string): Promise<Baseline | null>;
+  snapshot(id: string): Promise<Snapshot | null>;
+  build(id: string): Promise<Build | null>;
+}
+/** A proven source, or null when the recorded history is incomplete or has changed. */
+declare function resolveBaselineOrigin(baseline: Baseline, reader: BaselineOriginReader): Promise<Build | null>;
+export { BaselineOriginReader, resolveBaselineOrigin };
+//# sourceMappingURL=baseline-origin.d.mts.map

package/dist/models/baseline-origin.mjs

@@ -0,0 +1,35 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import "../adapters/capture-target.mjs";
+// src/models/baseline-origin.ts
+/** A proven source, or null when the recorded history is incomplete or has changed. */
+async function resolveBaselineOrigin(baseline, reader) {
+	return await traceOrigin(baseline, baseline.projectId, reader, /* @__PURE__ */ new Set());
+}
+async function traceOrigin(current, projectId, reader, seen) {
+	if (current.sourceBuildId) return await verifiedBuild(current.sourceBuildId, projectId, reader);
+	if (seen.size >= 32 || seen.has(current.id) || !current.snapshotId) return null;
+	seen.add(current.id);
+	const snapshot = await reader.snapshot(current.snapshotId);
+	if (!snapshot || !matchesImage(current, snapshot)) return null;
+	if (!snapshot.inherited) return await verifiedBuild(snapshot.buildId, projectId, reader);
+	return await traceInherited(snapshot, projectId, reader, seen);
+}
+async function traceInherited(snapshot, projectId, reader, seen) {
+	if (snapshot.sourceBuildId) return await verifiedBuild(snapshot.sourceBuildId, projectId, reader);
+	if (!snapshot.baselineId || !snapshot.baselineVersion) return null;
+	const parent = await reader.baseline(snapshot.baselineId);
+	if (!parent || parent.updatedAt !== snapshot.baselineVersion || !matchesImage(parent, snapshot)) return null;
+	return await traceOrigin(parent, projectId, reader, seen);
+}
+function matchesImage(baseline, snapshot) {
+	return baseline.projectId === snapshot.projectId && baseline.storyId === snapshot.storyId && baseline.viewportName === snapshot.viewportName && (baseline.browser ?? "chromium") === (snapshot.browser ?? "chromium") && baseline.screenshotPath === snapshot.screenshotPath;
+}
+async function verifiedBuild(buildId, projectId, reader) {
+	const build = await reader.build(buildId);
+	return build?.projectId === projectId ? build : null;
+}
+export { resolveBaselineOrigin };
+
+//# sourceMappingURL=baseline-origin.mjs.map

package/dist/models/baseline-origin.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-origin.mjs","names":[],"sources":["../../src/models/baseline-origin.ts"],"sourcesContent":["import { DEFAULT_BROWSER } from \"../adapters/capture-runner.ts\";\nimport type { Baseline, Build, Snapshot } from \"../schema/index.ts\";\n\n/** The records needed to prove which build rendered a baseline image. */\nexport interface BaselineOriginReader {\n  baseline(id: string): Promise<Baseline | null>;\n  snapshot(id: string): Promise<Snapshot | null>;\n  build(id: string): Promise<Build | null>;\n}\n\n/** A proven source, or null when the recorded history is incomplete or has changed. */\nexport async function resolveBaselineOrigin(\n  baseline: Baseline,\n  reader: BaselineOriginReader,\n): Promise<Build | null> {\n  return await traceOrigin(baseline, baseline.projectId, reader, new Set());\n}\n\nasync function traceOrigin(\n  current: Baseline,\n  projectId: string,\n  reader: BaselineOriginReader,\n  seen: Set<string>,\n): Promise<Build | null> {\n  if (current.sourceBuildId) return await verifiedBuild(current.sourceBuildId, projectId, reader);\n  if (seen.size >= 32 || seen.has(current.id) || !current.snapshotId) return null;\n  seen.add(current.id);\n  const snapshot = await reader.snapshot(current.snapshotId);\n  if (!snapshot || !matchesImage(current, snapshot)) return null;\n  if (!snapshot.inherited) return await verifiedBuild(snapshot.buildId, projectId, reader);\n  return await traceInherited(snapshot, projectId, reader, seen);\n}\n\nasync function traceInherited(\n  snapshot: Snapshot,\n  projectId: string,\n  reader: BaselineOriginReader,\n  seen: Set<string>,\n): Promise<Build | null> {\n  if (snapshot.sourceBuildId) return await verifiedBuild(snapshot.sourceBuildId, projectId, reader);\n  if (!snapshot.baselineId || !snapshot.baselineVersion) return null;\n  const parent = await reader.baseline(snapshot.baselineId);\n  if (!parent || parent.updatedAt !== snapshot.baselineVersion || !matchesImage(parent, snapshot))\n    return null;\n  return await traceOrigin(parent, projectId, reader, seen);\n}\n\nfunction matchesImage(baseline: Baseline, snapshot: Snapshot): boolean {\n  return (\n    baseline.projectId === snapshot.projectId &&\n    baseline.storyId === snapshot.storyId &&\n    baseline.viewportName === snapshot.viewportName &&\n    (baseline.browser ?? DEFAULT_BROWSER) === (snapshot.browser ?? DEFAULT_BROWSER) &&\n    baseline.screenshotPath === snapshot.screenshotPath\n  );\n}\n\nasync function verifiedBuild(\n  buildId: string,\n  projectId: string,\n  reader: BaselineOriginReader,\n): Promise<Build | null> {\n  const build = await reader.build(buildId);\n  return build?.projectId === projectId ? build : null;\n}\n"],"mappings":";;;;;;AAWA,eAAsB,sBACpB,UACA,QACuB;CACvB,OAAO,MAAM,YAAY,UAAU,SAAS,WAAW,wBAAQ,IAAI,IAAI,CAAC;AAC1E;AAEA,eAAe,YACb,SACA,WACA,QACA,MACuB;CACvB,IAAI,QAAQ,eAAe,OAAO,MAAM,cAAc,QAAQ,eAAe,WAAW,MAAM;CAC9F,IAAI,KAAK,QAAQ,MAAM,KAAK,IAAI,QAAQ,EAAE,KAAK,CAAC,QAAQ,YAAY,OAAO;CAC3E,KAAK,IAAI,QAAQ,EAAE;CACnB,MAAM,WAAW,MAAM,OAAO,SAAS,QAAQ,UAAU;CACzD,IAAI,CAAC,YAAY,CAAC,aAAa,SAAS,QAAQ,GAAG,OAAO;CAC1D,IAAI,CAAC,SAAS,WAAW,OAAO,MAAM,cAAc,SAAS,SAAS,WAAW,MAAM;CACvF,OAAO,MAAM,eAAe,UAAU,WAAW,QAAQ,IAAI;AAC/D;AAEA,eAAe,eACb,UACA,WACA,QACA,MACuB;CACvB,IAAI,SAAS,eAAe,OAAO,MAAM,cAAc,SAAS,eAAe,WAAW,MAAM;CAChG,IAAI,CAAC,SAAS,cAAc,CAAC,SAAS,iBAAiB,OAAO;CAC9D,MAAM,SAAS,MAAM,OAAO,SAAS,SAAS,UAAU;CACxD,IAAI,CAAC,UAAU,OAAO,cAAc,SAAS,mBAAmB,CAAC,aAAa,QAAQ,QAAQ,GAC5F,OAAO;CACT,OAAO,MAAM,YAAY,QAAQ,WAAW,QAAQ,IAAI;AAC1D;AAEA,SAAS,aAAa,UAAoB,UAA6B;CACrE,OACE,SAAS,cAAc,SAAS,aAChC,SAAS,YAAY,SAAS,WAC9B,SAAS,iBAAiB,SAAS,iBAClC,SAAS,WAAA,iBAAiC,SAAS,WAAA,eACpD,SAAS,mBAAmB,SAAS;AAEzC;AAEA,eAAe,cACb,SACA,WACA,QACuB;CACvB,MAAM,QAAQ,MAAM,OAAO,MAAM,OAAO;CACxC,OAAO,OAAO,cAAc,YAAY,QAAQ;AAClD"}

package/dist/models/baseline-status.d.mts

@@ -2,7 +2,6 @@ import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { Baseline } from "../schema/baseline.mjs";
 import { Snapshot } from "../schema/snapshot.mjs";
-//#region src/models/baseline-status.d.ts
 /** `baselineVersion` recorded when a story had no baseline at diff time. */
 declare const NO_BASELINE = "none";
 /**
@@ -24,6 +23,5 @@ type TrackedSnapshot = Pick<Snapshot, "baselineId" | "baselineVersion">;
 declare function baselineStatus(snapshot: TrackedSnapshot, current: Baseline | null): BaselineStatus;
 /** True when approving should be refused until the diff is recomputed (or forced). */
 declare function isBaselineDrifted(status: BaselineStatus): boolean;
-//#endregion
 export { BaselineStatus, NO_BASELINE, baselineStatus, isBaselineDrifted };
 //# sourceMappingURL=baseline-status.d.mts.map

package/dist/models/baseline-status.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/models/baseline-status.ts
+// src/models/baseline-status.ts
 /** `baselineVersion` recorded when a story had no baseline at diff time. */
 const NO_BASELINE = "none";
 /**
@@ -20,7 +20,6 @@ function baselineStatus(snapshot, current) {
 function isBaselineDrifted(status) {
 	return status === "stale" || status === "removed";
 }
-//#endregion
 export { NO_BASELINE, baselineStatus, isBaselineDrifted };
 
 //# sourceMappingURL=baseline-status.mjs.map

package/dist/models/baseline-transfer.d.mts

@@ -0,0 +1,48 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DatabaseAdapter } from "../adapter/database.mjs";
+import { StorageAdapter } from "../adapter/storage.mjs";
+import { BaselineTables } from "./baseline.mjs";
+import { BaselineExportOptions } from "./baseline-export.mjs";
+/** Outcome of {@link BaselineTransferModel.import}. */
+interface BaselineImportResult {
+  /** Baselines in the archive (all applied). */
+  imported: number;
+  /** Baselines that did not exist before. */
+  created: number;
+  /** Existing baselines that were overwritten. */
+  updated: number;
+}
+/** Export/import of baselines between StoryShelf instances (or for backup). */
+declare class BaselineTransferModel {
+  private readonly tables;
+  private readonly baselines;
+  private readonly db;
+  private readonly storage;
+  constructor(db: DatabaseAdapter, storage: StorageAdapter, tables?: BaselineTables);
+  /**
+   * Stream the project's baselines (optionally one branch) as a zip archive.
+   *
+   * @throws {BaselineArchiveError} Before streaming, when over the archive entry limit.
+   */
+  export(projectId: string, options?: BaselineExportOptions): Promise<AsyncIterable<Buffer>>;
+  /**
+   * Upsert every baseline in `archive` into the project. The whole archive is
+   * validated before anything is written; images are then stored (idempotent,
+   * safe to retry) and all rows are applied in one transaction when the driver
+   * supports it, so a failure leaves the rows untouched. Imports into the same
+   * project run one at a time. Imported rows keep their original timestamps;
+   * `snapshotId` is cleared because snapshots are not portable.
+   *
+   * @throws {BaselineArchiveError} On a malformed, unsafe, or inconsistent archive.
+   */
+  import(projectId: string, archive: Buffer): Promise<BaselineImportResult>;
+  private existingByIdentity;
+  /** Apply every row, in a transaction when available; returns how many were created. */
+  private applyRows;
+  private assertUnchangedIdentities;
+  /** Write one planned row; resolves true when it was created. */
+  private applyRow;
+}
+export { BaselineImportResult, BaselineTransferModel };
+//# sourceMappingURL=baseline-transfer.d.mts.map

package/dist/models/baseline-transfer.mjs

@@ -0,0 +1,149 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import "../adapters/capture-target.mjs";
+import { ulid } from "../utils/ulid.mjs";
+import { withContentClaim } from "../utils/screenshot-store.mjs";
+import { BaselineWriteConflict } from "./baseline-conflict.mjs";
+import { BaselineModel } from "./baseline.mjs";
+import { baselineIdentity } from "./baseline-archive.mjs";
+import { exportBaselineArchive } from "./baseline-export.mjs";
+import { planBaselineImport, writePlannedImage } from "./baseline-import.mjs";
+// src/models/baseline-transfer.ts
+/**
+* Baseline portability: export a project's baselines as a zip archive and
+* import (upsert) them from the same format. Format and limits live in
+* `baseline-archive.ts`; see the portability guide in the docs site.
+*/
+/** Export/import of baselines between StoryShelf instances (or for backup). */
+var BaselineTransferModel = class {
+	tables;
+	baselines;
+	db;
+	storage;
+	constructor(db, storage, tables) {
+		this.db = db;
+		this.storage = storage;
+		this.tables = tables ?? { baselines: db.tables.baselines };
+		this.baselines = new BaselineModel(db, this.tables, storage);
+	}
+	/**
+	* Stream the project's baselines (optionally one branch) as a zip archive.
+	*
+	* @throws {BaselineArchiveError} Before streaming, when over the archive entry limit.
+	*/
+	async export(projectId, options = {}) {
+		return exportBaselineArchive(this.storage, await this.baselines.list(projectId), options);
+	}
+	/**
+	* Upsert every baseline in `archive` into the project. The whole archive is
+	* validated before anything is written; images are then stored (idempotent,
+	* safe to retry) and all rows are applied in one transaction when the driver
+	* supports it, so a failure leaves the rows untouched. Imports into the same
+	* project run one at a time. Imported rows keep their original timestamps;
+	* `snapshotId` is cleared because snapshots are not portable.
+	*
+	* @throws {BaselineArchiveError} On a malformed, unsafe, or inconsistent archive.
+	*/
+	async import(projectId, archive) {
+		const plan = await planBaselineImport(archive, projectId);
+		return await serialized(projectId, async () => await withContentClaim(this.storage, projectId, async () => {
+			for (const planned of plan) await writePlannedImage(this.storage, planned);
+			const existing = await this.existingByIdentity(projectId);
+			const created = await this.applyRows(projectId, plan, existing);
+			return {
+				imported: plan.length,
+				created,
+				updated: plan.length - created
+			};
+		}));
+	}
+	async existingByIdentity(projectId) {
+		const rows = await this.baselines.list(projectId);
+		return new Map(rows.map((row) => [baselineIdentity({
+			storyId: row.storyId,
+			viewport: row.viewportName,
+			browser: row.browser ?? "chromium",
+			branch: row.branch
+		}), row]));
+	}
+	/** Apply every row, in a transaction when available; returns how many were created. */
+	async applyRows(projectId, plan, existing) {
+		const run = async (store) => {
+			let created = 0;
+			for (const planned of plan) created += await this.applyRow(store, projectId, planned, existing) ? 1 : 0;
+			return created;
+		};
+		const lifecycle = this.db.buildReferenceLifecycle;
+		if (lifecycle) {
+			const touched = plan.map((planned) => existing.get(baselineIdentity(planned.entry))).filter((row) => row !== void 0);
+			const changes = await Promise.all(touched.map(async (row) => {
+				const owner = {
+					type: "baseline",
+					id: row.id,
+					projectId
+				};
+				return {
+					owner,
+					expectedGeneration: await lifecycle.referenceGeneration(owner),
+					buildIds: []
+				};
+			}));
+			return (await lifecycle.replaceManyFencedReferences(changes, async (store) => {
+				await this.assertUnchangedIdentities(store, touched);
+				return await run(store);
+			})).result;
+		}
+		return this.db.transact ? await this.db.transact(run) : await run(this.db);
+	}
+	async assertUnchangedIdentities(store, rows) {
+		const current = await Promise.all(rows.map(async (row) => await store.get(this.tables.baselines, row.id)));
+		for (const [index, row] of rows.entries()) {
+			const found = current[index];
+			if (!found || found.projectId !== row.projectId || found.storyId !== row.storyId || found.viewportName !== row.viewportName || found.branch !== row.branch || found.updatedAt !== row.updatedAt || found.snapshotId !== row.snapshotId || found.sourceBuildId !== row.sourceBuildId || found.screenshotPath !== row.screenshotPath || (found.browser ?? "chromium") !== (row.browser ?? "chromium")) throw new BaselineWriteConflict("Baseline changed during import; retry");
+		}
+	}
+	/** Write one planned row; resolves true when it was created. */
+	async applyRow(store, projectId, planned, existing) {
+		const { entry, storagePath } = planned;
+		const fields = {
+			snapshotId: null,
+			sourceBuildId: null,
+			screenshotPath: storagePath,
+			infraHash: entry.infraHash,
+			fingerprint: entry.fingerprint ?? null,
+			mode: entry.mode,
+			createdAt: entry.createdAt,
+			updatedAt: entry.updatedAt
+		};
+		const current = existing.get(baselineIdentity(entry));
+		if (current) {
+			await store.update(this.tables.baselines, current.id, fields);
+			return false;
+		}
+		await store.insert(this.tables.baselines, {
+			...fields,
+			id: ulid(),
+			projectId,
+			storyId: entry.storyId,
+			viewportName: entry.viewport,
+			branch: entry.branch,
+			browser: entry.browser
+		});
+		return true;
+	}
+};
+const importQueues = /* @__PURE__ */ new Map();
+/** Run `task` after earlier work for the same key settles (in-process serialization). */
+async function serialized(key, task) {
+	const run = (importQueues.get(key) ?? Promise.resolve()).then(task, task);
+	importQueues.set(key, run);
+	try {
+		return await run;
+	} finally {
+		if (importQueues.get(key) === run) importQueues.delete(key);
+	}
+}
+export { BaselineTransferModel };
+
+//# sourceMappingURL=baseline-transfer.mjs.map

package/dist/models/baseline-transfer.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-transfer.mjs","names":[],"sources":["../../src/models/baseline-transfer.ts"],"sourcesContent":["/**\n * Baseline portability: export a project's baselines as a zip archive and\n * import (upsert) them from the same format. Format and limits live in\n * `baseline-archive.ts`; see the portability guide in the docs site.\n */\nimport { DEFAULT_BROWSER } from \"../adapters/capture-runner.ts\";\nimport type { DatabaseAdapter, TxStore } from \"../adapters/database.ts\";\nimport type { StorageAdapter } from \"../adapters/storage.ts\";\nimport type { Baseline } from \"../schema/baseline.ts\";\nimport { withContentClaim } from \"../utils/screenshot-store.ts\";\nimport { ulid } from \"../utils/ulid.ts\";\nimport { baselineIdentity } from \"./baseline-archive.ts\";\nimport { BaselineWriteConflict } from \"./baseline-conflict.ts\";\nimport { exportBaselineArchive, type BaselineExportOptions } from \"./baseline-export.ts\";\nimport { planBaselineImport, writePlannedImage, type PlannedBaseline } from \"./baseline-import.ts\";\nimport { BaselineModel, type BaselineTables } from \"./baseline.ts\";\n\n/** Outcome of {@link BaselineTransferModel.import}. */\nexport interface BaselineImportResult {\n  /** Baselines in the archive (all applied). */\n  imported: number;\n  /** Baselines that did not exist before. */\n  created: number;\n  /** Existing baselines that were overwritten. */\n  updated: number;\n}\n\n/** Export/import of baselines between StoryShelf instances (or for backup). */\nexport class BaselineTransferModel {\n  private readonly tables: BaselineTables;\n  private readonly baselines: BaselineModel;\n  private readonly db: DatabaseAdapter;\n  private readonly storage: StorageAdapter;\n\n  constructor(db: DatabaseAdapter, storage: StorageAdapter, tables?: BaselineTables) {\n    this.db = db;\n    this.storage = storage;\n    this.tables = tables ?? { baselines: db.tables.baselines };\n    this.baselines = new BaselineModel(db, this.tables, storage);\n  }\n\n  /**\n   * Stream the project's baselines (optionally one branch) as a zip archive.\n   *\n   * @throws {BaselineArchiveError} Before streaming, when over the archive entry limit.\n   */\n  async export(\n    projectId: string,\n    options: BaselineExportOptions = {},\n  ): Promise<AsyncIterable<Buffer>> {\n    return exportBaselineArchive(this.storage, await this.baselines.list(projectId), options);\n  }\n\n  /**\n   * Upsert every baseline in `archive` into the project. The whole archive is\n   * validated before anything is written; images are then stored (idempotent,\n   * safe to retry) and all rows are applied in one transaction when the driver\n   * supports it, so a failure leaves the rows untouched. Imports into the same\n   * project run one at a time. Imported rows keep their original timestamps;\n   * `snapshotId` is cleared because snapshots are not portable.\n   *\n   * @throws {BaselineArchiveError} On a malformed, unsafe, or inconsistent archive.\n   */\n  async import(projectId: string, archive: Buffer): Promise<BaselineImportResult> {\n    const plan = await planBaselineImport(archive, projectId);\n    // Images that already exist are reused, not written: claim the project's content so the\n    // screenshot sweep cannot delete one before the rows pointing at it are committed.\n    return await serialized(\n      projectId,\n      async () =>\n        await withContentClaim(this.storage, projectId, async () => {\n          for (const planned of plan) {\n            // oxlint-disable-next-line eslint/no-await-in-loop -- sequential writes bound storage load\n            await writePlannedImage(this.storage, planned);\n          }\n          const existing = await this.existingByIdentity(projectId);\n          const created = await this.applyRows(projectId, plan, existing);\n          return { imported: plan.length, created, updated: plan.length - created };\n        }),\n    );\n  }\n\n  private async existingByIdentity(projectId: string): Promise<Map<string, Baseline>> {\n    const rows = await this.baselines.list(projectId);\n    return new Map(\n      rows.map((row) => [\n        baselineIdentity({\n          storyId: row.storyId,\n          viewport: row.viewportName,\n          browser: row.browser ?? DEFAULT_BROWSER,\n          branch: row.branch,\n        }),\n        row,\n      ]),\n    );\n  }\n\n  /** Apply every row, in a transaction when available; returns how many were created. */\n  private async applyRows(\n    projectId: string,\n    plan: PlannedBaseline[],\n    existing: Map<string, Baseline>,\n  ): Promise<number> {\n    const run = async (store: TxStore): Promise<number> => {\n      let created = 0;\n      for (const planned of plan) {\n        // oxlint-disable-next-line eslint/no-await-in-loop -- rows are applied in order within one transaction\n        created += (await this.applyRow(store, projectId, planned, existing)) ? 1 : 0;\n      }\n      return created;\n    };\n    const lifecycle = this.db.buildReferenceLifecycle;\n    if (lifecycle) {\n      const touched = plan\n        .map((planned) => existing.get(baselineIdentity(planned.entry)))\n        .filter((row): row is Baseline => row !== undefined);\n      const changes = await Promise.all(\n        touched.map(async (row) => {\n          const owner = { type: \"baseline\" as const, id: row.id, projectId };\n          return {\n            owner,\n            expectedGeneration: await lifecycle.referenceGeneration(owner),\n            buildIds: [],\n          };\n        }),\n      );\n      const updated = await lifecycle.replaceManyFencedReferences(changes, async (store) => {\n        await this.assertUnchangedIdentities(store, touched);\n        return await run(store);\n      });\n      return updated.result;\n    }\n    return this.db.transact ? await this.db.transact(run) : await run(this.db);\n  }\n\n  private async assertUnchangedIdentities(store: TxStore, rows: Baseline[]): Promise<void> {\n    const current = await Promise.all(\n      rows.map(\n        async (row) =>\n          (await store.get(this.tables.baselines, row.id)) as unknown as Baseline | null,\n      ),\n    );\n    for (const [index, row] of rows.entries()) {\n      const found = current[index];\n      if (\n        !found ||\n        found.projectId !== row.projectId ||\n        found.storyId !== row.storyId ||\n        found.viewportName !== row.viewportName ||\n        found.branch !== row.branch ||\n        found.updatedAt !== row.updatedAt ||\n        found.snapshotId !== row.snapshotId ||\n        found.sourceBuildId !== row.sourceBuildId ||\n        found.screenshotPath !== row.screenshotPath ||\n        (found.browser ?? DEFAULT_BROWSER) !== (row.browser ?? DEFAULT_BROWSER)\n      ) {\n        throw new BaselineWriteConflict(\"Baseline changed during import; retry\");\n      }\n    }\n  }\n\n  /** Write one planned row; resolves true when it was created. */\n  private async applyRow(\n    store: TxStore,\n    projectId: string,\n    planned: PlannedBaseline,\n    existing: Map<string, Baseline>,\n  ): Promise<boolean> {\n    const { entry, storagePath } = planned;\n    const fields = {\n      snapshotId: null,\n      sourceBuildId: null,\n      screenshotPath: storagePath,\n      infraHash: entry.infraHash,\n      fingerprint: entry.fingerprint ?? null,\n      mode: entry.mode,\n      createdAt: entry.createdAt,\n      updatedAt: entry.updatedAt,\n    } satisfies Partial<Baseline>;\n    const current = existing.get(baselineIdentity(entry));\n    if (current) {\n      await store.update(this.tables.baselines, current.id, fields);\n      return false;\n    }\n    await store.insert(this.tables.baselines, {\n      ...fields,\n      id: ulid(),\n      projectId,\n      storyId: entry.storyId,\n      viewportName: entry.viewport,\n      branch: entry.branch,\n      browser: entry.browser,\n    });\n    return true;\n  }\n}\n\nconst importQueues = new Map<string, Promise<unknown>>();\n\n/** Run `task` after earlier work for the same key settles (in-process serialization). */\nasync function serialized<T>(key: string, task: () => Promise<T>): Promise<T> {\n  const run = (importQueues.get(key) ?? Promise.resolve()).then(task, task);\n  importQueues.set(key, run);\n  try {\n    return await run;\n  } finally {\n    if (importQueues.get(key) === run) {\n      importQueues.delete(key);\n    }\n  }\n}\n"],"mappings":"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"}