@storyshelf/core 0.6.1 → 0.7.0

package/dist/utils/zip-read.mjs

@@ -0,0 +1,129 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import "node:buffer";
+import { crc32, inflateRawSync } from "node:zlib";
+//#region src/utils/zip-read.ts
+/** A malformed, unsafe, or over-limit archive. */
+var ZipFormatError = class extends Error {
+	name = "ZipFormatError";
+};
+/**
+* Index the file entries of `archive` by name (directories are skipped).
+*
+* @throws {ZipFormatError} On malformed, unsafe, or over-limit archives.
+*/
+function readZip(archive, limits) {
+	const end = findEndOfCentralDirectory(archive);
+	const count = archive.readUInt16LE(end + 10);
+	if (count > limits.maxEntries) throw new ZipFormatError(`Archive has more than ${limits.maxEntries} entries`);
+	const records = readCentralDirectory(archive, archive.readUInt32LE(end + 16), count);
+	if (records.reduce((sum, record) => sum + record.size, 0) > limits.maxTotalBytes) throw new ZipFormatError(`Archive expands beyond ${limits.maxTotalBytes} bytes`);
+	return indexEntries(archive, records, limits.maxEntryBytes);
+}
+const EOCD_SIGNATURE = 101010256;
+const CENTRAL_SIGNATURE = 33639248;
+const LOCAL_SIGNATURE = 67324752;
+const EOCD_SIZE = 22;
+const MAX_COMMENT = 65535;
+const STORE = 0;
+const DEFLATE = 8;
+function fail(message) {
+	throw new ZipFormatError(message);
+}
+function findEndOfCentralDirectory(archive) {
+	const floor = Math.max(0, archive.length - EOCD_SIZE - MAX_COMMENT);
+	for (let at = archive.length - EOCD_SIZE; at >= floor; at -= 1) if (archive.readUInt32LE(at) === EOCD_SIGNATURE) {
+		assertSingleDisk(archive, at);
+		return at;
+	}
+	return fail("Not a zip archive (no end of central directory)");
+}
+function assertSingleDisk(archive, end) {
+	const multiDisk = archive.readUInt16LE(end + 4) !== 0 || archive.readUInt16LE(end + 6) !== 0;
+	const entriesMismatch = archive.readUInt16LE(end + 8) !== archive.readUInt16LE(end + 10);
+	if (multiDisk || entriesMismatch || archive.readUInt32LE(end + 16) === 4294967295) fail("Multi-disk and zip64 archives are not supported");
+}
+function readCentralDirectory(archive, start, count) {
+	const records = [];
+	let at = start;
+	for (let index = 0; index < count; index += 1) {
+		const { record, next } = readCentralRecord(archive, at);
+		records.push(record);
+		at = next;
+	}
+	return records;
+}
+function readCentralRecord(archive, at) {
+	assertRange(archive, at, 46);
+	if (archive.readUInt32LE(at) !== CENTRAL_SIGNATURE) fail("Corrupt central directory");
+	const nameLength = archive.readUInt16LE(at + 28);
+	const extras = archive.readUInt16LE(at + 30) + archive.readUInt16LE(at + 32);
+	assertRange(archive, at + 46, nameLength);
+	return {
+		record: {
+			name: archive.toString("utf8", at + 46, at + 46 + nameLength),
+			method: archive.readUInt16LE(at + 10),
+			flags: archive.readUInt16LE(at + 8),
+			crc: archive.readUInt32LE(at + 16),
+			compressedSize: archive.readUInt32LE(at + 20),
+			size: archive.readUInt32LE(at + 24),
+			localOffset: archive.readUInt32LE(at + 42)
+		},
+		next: at + 46 + nameLength + extras
+	};
+}
+function assertRange(archive, start, length) {
+	if (start < 0 || start + length > archive.length) fail("Truncated zip archive");
+}
+/** Whether an entry name could escape an extraction root or confuse lookups. */
+function isUnsafeEntryName(name) {
+	return name.length === 0 || name.startsWith("/") || name.includes("\\") || name.includes("\0") || /^[a-z]:/iu.test(name) || name.split("/").some((segment) => segment === ".." || segment === ".");
+}
+function indexEntries(archive, records, maxEntryBytes) {
+	const entries = /* @__PURE__ */ new Map();
+	for (const record of records) {
+		if (record.name.endsWith("/")) continue;
+		validateRecord(record, maxEntryBytes);
+		if (entries.has(record.name)) fail(`Duplicate zip entry: ${record.name}`);
+		entries.set(record.name, {
+			name: record.name,
+			size: record.size,
+			read: () => extract(archive, record)
+		});
+	}
+	return entries;
+}
+function validateRecord(record, maxEntryBytes) {
+	if (isUnsafeEntryName(record.name)) fail(`Unsafe zip entry name: ${record.name}`);
+	if (record.flags % 2 === 1) fail(`Encrypted zip entries are not supported: ${record.name}`);
+	if (record.method !== STORE && record.method !== DEFLATE) fail(`Unsupported compression method ${record.method}: ${record.name}`);
+	if (record.size > maxEntryBytes) fail(`Zip entry exceeds ${maxEntryBytes} bytes: ${record.name}`);
+}
+function extract(archive, record) {
+	const at = record.localOffset;
+	assertRange(archive, at, 30);
+	if (archive.readUInt32LE(at) !== LOCAL_SIGNATURE) fail(`Corrupt local header: ${record.name}`);
+	const raw = entryData(archive, record);
+	const data = record.method === STORE ? raw : inflate(raw, record);
+	if (data.length !== record.size || crc32(data) !== record.crc) fail(`Zip entry failed integrity check: ${record.name}`);
+	return data;
+}
+/** Compressed bytes of an entry, located through its local header. */
+function entryData(archive, record) {
+	const at = record.localOffset;
+	const start = at + 30 + archive.readUInt16LE(at + 26) + archive.readUInt16LE(at + 28);
+	assertRange(archive, start, record.compressedSize);
+	return archive.subarray(start, start + record.compressedSize);
+}
+function inflate(raw, record) {
+	try {
+		return inflateRawSync(raw, { maxOutputLength: record.size + 1 });
+	} catch {
+		return fail(`Zip entry failed to inflate: ${record.name}`);
+	}
+}
+//#endregion
+export { ZipFormatError, isUnsafeEntryName, readZip };
+
+//# sourceMappingURL=zip-read.mjs.map

package/dist/utils/zip-read.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip-read.mjs","names":[],"sources":["../../src/utils/zip-read.ts"],"sourcesContent":["/**\n * Defensive in-memory zip reader for untrusted archives.\n *\n * Reads the central directory of a buffered archive and inflates entries\n * lazily, enforcing entry-count, per-entry and total size limits before any\n * decompression (zip-bomb guard) and verifying each entry's CRC. Entry names\n * that could traverse paths are rejected outright. Supports STORE and\n * DEFLATE; rejects encryption, multi-disk and zip64 archives.\n */\nimport { Buffer } from \"node:buffer\";\nimport { crc32, inflateRawSync } from \"node:zlib\";\n\n/** Limits applied while reading an archive. */\nexport interface ZipReadLimits {\n  /** Maximum number of entries in the central directory. */\n  maxEntries: number;\n  /** Maximum uncompressed size of one entry, in bytes. */\n  maxEntryBytes: number;\n  /** Maximum combined uncompressed size of all entries, in bytes. */\n  maxTotalBytes: number;\n}\n\n/** One file in an archive; `read()` inflates and CRC-checks it. */\nexport interface ZipEntry {\n  name: string;\n  size: number;\n  read: () => Buffer;\n}\n\n/** A malformed, unsafe, or over-limit archive. */\nexport class ZipFormatError extends Error {\n  override readonly name = \"ZipFormatError\";\n}\n\n/**\n * Index the file entries of `archive` by name (directories are skipped).\n *\n * @throws {ZipFormatError} On malformed, unsafe, or over-limit archives.\n */\nexport function readZip(archive: Buffer, limits: ZipReadLimits): Map<string, ZipEntry> {\n  const end = findEndOfCentralDirectory(archive);\n  const count = archive.readUInt16LE(end + 10);\n  if (count > limits.maxEntries) {\n    throw new ZipFormatError(`Archive has more than ${limits.maxEntries} entries`);\n  }\n  const records = readCentralDirectory(archive, archive.readUInt32LE(end + 16), count);\n  const total = records.reduce((sum, record) => sum + record.size, 0);\n  if (total > limits.maxTotalBytes) {\n    throw new ZipFormatError(`Archive expands beyond ${limits.maxTotalBytes} bytes`);\n  }\n  return indexEntries(archive, records, limits.maxEntryBytes);\n}\n\n/** Central-directory fields needed to extract an entry. */\ninterface CentralRecord {\n  name: string;\n  method: number;\n  flags: number;\n  crc: number;\n  compressedSize: number;\n  size: number;\n  localOffset: number;\n}\n\nconst EOCD_SIGNATURE = 0x06_05_4b_50;\nconst CENTRAL_SIGNATURE = 0x02_01_4b_50;\nconst LOCAL_SIGNATURE = 0x04_03_4b_50;\nconst EOCD_SIZE = 22;\nconst MAX_COMMENT = 0xff_ff;\nconst STORE = 0;\nconst DEFLATE = 8;\n\nfunction fail(message: string): never {\n  throw new ZipFormatError(message);\n}\n\nfunction findEndOfCentralDirectory(archive: Buffer): number {\n  const floor = Math.max(0, archive.length - EOCD_SIZE - MAX_COMMENT);\n  for (let at = archive.length - EOCD_SIZE; at >= floor; at -= 1) {\n    if (archive.readUInt32LE(at) === EOCD_SIGNATURE) {\n      assertSingleDisk(archive, at);\n      return at;\n    }\n  }\n  return fail(\"Not a zip archive (no end of central directory)\");\n}\n\nfunction assertSingleDisk(archive: Buffer, end: number): void {\n  const multiDisk = archive.readUInt16LE(end + 4) !== 0 || archive.readUInt16LE(end + 6) !== 0;\n  const entriesMismatch = archive.readUInt16LE(end + 8) !== archive.readUInt16LE(end + 10);\n  if (multiDisk || entriesMismatch || archive.readUInt32LE(end + 16) === 0xff_ff_ff_ff) {\n    fail(\"Multi-disk and zip64 archives are not supported\");\n  }\n}\n\nfunction readCentralDirectory(archive: Buffer, start: number, count: number): CentralRecord[] {\n  const records: CentralRecord[] = [];\n  let at = start;\n  for (let index = 0; index < count; index += 1) {\n    const { record, next } = readCentralRecord(archive, at);\n    records.push(record);\n    at = next;\n  }\n  return records;\n}\n\nfunction readCentralRecord(archive: Buffer, at: number): { record: CentralRecord; next: number } {\n  assertRange(archive, at, 46);\n  if (archive.readUInt32LE(at) !== CENTRAL_SIGNATURE) {\n    fail(\"Corrupt central directory\");\n  }\n  const nameLength = archive.readUInt16LE(at + 28);\n  const extras = archive.readUInt16LE(at + 30) + archive.readUInt16LE(at + 32);\n  assertRange(archive, at + 46, nameLength);\n  const record: CentralRecord = {\n    name: archive.toString(\"utf8\", at + 46, at + 46 + nameLength),\n    method: archive.readUInt16LE(at + 10),\n    flags: archive.readUInt16LE(at + 8),\n    crc: archive.readUInt32LE(at + 16),\n    compressedSize: archive.readUInt32LE(at + 20),\n    size: archive.readUInt32LE(at + 24),\n    localOffset: archive.readUInt32LE(at + 42),\n  };\n  return { record, next: at + 46 + nameLength + extras };\n}\n\nfunction assertRange(archive: Buffer, start: number, length: number): void {\n  if (start < 0 || start + length > archive.length) {\n    fail(\"Truncated zip archive\");\n  }\n}\n\n/** Whether an entry name could escape an extraction root or confuse lookups. */\nexport function isUnsafeEntryName(name: string): boolean {\n  return (\n    name.length === 0 ||\n    name.startsWith(\"/\") ||\n    name.includes(\"\\\\\") ||\n    name.includes(\"\\0\") ||\n    /^[a-z]:/iu.test(name) ||\n    name.split(\"/\").some((segment) => segment === \"..\" || segment === \".\")\n  );\n}\n\nfunction indexEntries(\n  archive: Buffer,\n  records: CentralRecord[],\n  maxEntryBytes: number,\n): Map<string, ZipEntry> {\n  const entries = new Map<string, ZipEntry>();\n  for (const record of records) {\n    if (record.name.endsWith(\"/\")) {\n      continue;\n    }\n    validateRecord(record, maxEntryBytes);\n    if (entries.has(record.name)) {\n      fail(`Duplicate zip entry: ${record.name}`);\n    }\n    entries.set(record.name, {\n      name: record.name,\n      size: record.size,\n      read: () => extract(archive, record),\n    });\n  }\n  return entries;\n}\n\nfunction validateRecord(record: CentralRecord, maxEntryBytes: number): void {\n  if (isUnsafeEntryName(record.name)) {\n    fail(`Unsafe zip entry name: ${record.name}`);\n  }\n  if (record.flags % 2 === 1) {\n    fail(`Encrypted zip entries are not supported: ${record.name}`);\n  }\n  if (record.method !== STORE && record.method !== DEFLATE) {\n    fail(`Unsupported compression method ${record.method}: ${record.name}`);\n  }\n  if (record.size > maxEntryBytes) {\n    fail(`Zip entry exceeds ${maxEntryBytes} bytes: ${record.name}`);\n  }\n}\n\nfunction extract(archive: Buffer, record: CentralRecord): Buffer {\n  const at = record.localOffset;\n  assertRange(archive, at, 30);\n  if (archive.readUInt32LE(at) !== LOCAL_SIGNATURE) {\n    fail(`Corrupt local header: ${record.name}`);\n  }\n  const raw = entryData(archive, record);\n  const data = record.method === STORE ? raw : inflate(raw, record);\n  if (data.length !== record.size || crc32(data) !== record.crc) {\n    fail(`Zip entry failed integrity check: ${record.name}`);\n  }\n  return data;\n}\n\n/** Compressed bytes of an entry, located through its local header. */\nfunction entryData(archive: Buffer, record: CentralRecord): Buffer {\n  const at = record.localOffset;\n  const start = at + 30 + archive.readUInt16LE(at + 26) + archive.readUInt16LE(at + 28);\n  assertRange(archive, start, record.compressedSize);\n  return archive.subarray(start, start + record.compressedSize);\n}\n\nfunction inflate(raw: Buffer, record: CentralRecord): Buffer {\n  try {\n    // Cap output at the declared size (+1 so overruns are detectable, not truncated).\n    return inflateRawSync(raw, { maxOutputLength: record.size + 1 });\n  } catch {\n    return fail(`Zip entry failed to inflate: ${record.name}`);\n  }\n}\n"],"mappings":"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"}

package/dist/utils/zip-write.d.mts

@@ -0,0 +1,18 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Buffer } from "node:buffer";
+//#region src/utils/zip-write.d.ts
+/** One file to add to an archive; a `data` function is called lazily when the entry is written. */
+interface ZipSource {
+  name: string;
+  data: Buffer | (() => Promise<Buffer>);
+}
+/**
+ * Stream a zip archive for `sources`, yielding header/data chunks in order.
+ *
+ * @throws When the archive would need zip64 (more than 65535 entries or 4 GiB).
+ */
+declare function zipStream(sources: Iterable<ZipSource> | AsyncIterable<ZipSource>): AsyncGenerator<Buffer>;
+//#endregion
+export { ZipSource, zipStream };
+//# sourceMappingURL=zip-write.d.mts.map

package/dist/utils/zip-write.mjs

@@ -0,0 +1,188 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { Buffer } from "node:buffer";
+import { crc32 } from "node:zlib";
+//#region src/utils/zip-write.ts
+/**
+* Minimal streaming zip writer (STORE method, no zip64).
+*
+* Baseline exports are PNGs — already deflated — so entries are stored
+* uncompressed. Entries are produced one at a time, so memory stays bounded
+* by the largest single entry rather than the whole archive.
+*/
+/**
+* Stream a zip archive for `sources`, yielding header/data chunks in order.
+*
+* @throws When the archive would need zip64 (more than 65535 entries or 4 GiB).
+*/
+async function* zipStream(sources) {
+	const central = [];
+	let offset = 0;
+	for await (const source of sources) {
+		const data = typeof source.data === "function" ? await source.data() : source.data;
+		const record = entryRecord(source.name, data);
+		central.push(centralHeader(record, offset));
+		yield* [localHeader(record), data];
+		offset = checkedSize(offset + 30 + record.name.length + data.length);
+	}
+	yield* trailer(central, offset);
+}
+const MAX_U32 = 4294967295;
+const MAX_ENTRIES = 65535;
+/** General-purpose flag bit 11: file names are UTF-8. */
+const UTF8_FLAG = 2048;
+/** 1980-01-01 in DOS date format — fixed so archives are byte-reproducible. */
+const DOS_DATE = 33;
+const VERSION = 20;
+function entryRecord(name, data) {
+	return {
+		name: Buffer.from(name, "utf8"),
+		crc: crc32(data),
+		size: checkedSize(data.length)
+	};
+}
+function checkedSize(size) {
+	if (size > MAX_U32) throw new Error("Archive exceeds 4 GiB (zip64 is not supported)");
+	return size;
+}
+function header(size, fields, name) {
+	const out = Buffer.alloc(size);
+	for (const [offset, width, value] of fields) if (width === 2) out.writeUInt16LE(value, offset);
+	else out.writeUInt32LE(value, offset);
+	return name ? Buffer.concat([out, name]) : out;
+}
+function localHeader(record) {
+	return header(30, [
+		[
+			0,
+			4,
+			67324752
+		],
+		[
+			4,
+			2,
+			VERSION
+		],
+		[
+			6,
+			2,
+			UTF8_FLAG
+		],
+		[
+			12,
+			2,
+			DOS_DATE
+		],
+		[
+			14,
+			4,
+			record.crc
+		],
+		[
+			18,
+			4,
+			record.size
+		],
+		[
+			22,
+			4,
+			record.size
+		],
+		[
+			26,
+			2,
+			record.name.length
+		]
+	], record.name);
+}
+function centralHeader(record, offset) {
+	return header(46, [
+		[
+			0,
+			4,
+			33639248
+		],
+		[
+			4,
+			2,
+			VERSION
+		],
+		[
+			6,
+			2,
+			VERSION
+		],
+		[
+			8,
+			2,
+			UTF8_FLAG
+		],
+		[
+			14,
+			2,
+			DOS_DATE
+		],
+		[
+			16,
+			4,
+			record.crc
+		],
+		[
+			20,
+			4,
+			record.size
+		],
+		[
+			24,
+			4,
+			record.size
+		],
+		[
+			28,
+			2,
+			record.name.length
+		],
+		[
+			42,
+			4,
+			offset
+		]
+	], record.name);
+}
+function* trailer(central, offset) {
+	if (central.length > MAX_ENTRIES) throw new Error("Archive exceeds 65535 entries (zip64 is not supported)");
+	const directory = Buffer.concat(central);
+	yield directory;
+	yield header(22, [
+		[
+			0,
+			4,
+			101010256
+		],
+		[
+			8,
+			2,
+			central.length
+		],
+		[
+			10,
+			2,
+			central.length
+		],
+		[
+			12,
+			4,
+			directory.length
+		],
+		[
+			16,
+			4,
+			checkedSize(offset)
+		]
+	]);
+}
+//#endregion
+export { zipStream };
+
+//# sourceMappingURL=zip-write.mjs.map

package/dist/utils/zip-write.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip-write.mjs","names":[],"sources":["../../src/utils/zip-write.ts"],"sourcesContent":["/**\n * Minimal streaming zip writer (STORE method, no zip64).\n *\n * Baseline exports are PNGs — already deflated — so entries are stored\n * uncompressed. Entries are produced one at a time, so memory stays bounded\n * by the largest single entry rather than the whole archive.\n */\nimport { Buffer } from \"node:buffer\";\nimport { crc32 } from \"node:zlib\";\n\n/** One file to add to an archive; a `data` function is called lazily when the entry is written. */\nexport interface ZipSource {\n  name: string;\n  data: Buffer | (() => Promise<Buffer>);\n}\n\n/**\n * Stream a zip archive for `sources`, yielding header/data chunks in order.\n *\n * @throws When the archive would need zip64 (more than 65535 entries or 4 GiB).\n */\nexport async function* zipStream(\n  sources: Iterable<ZipSource> | AsyncIterable<ZipSource>,\n): AsyncGenerator<Buffer> {\n  const central: Buffer[] = [];\n  let offset = 0;\n  for await (const source of sources) {\n    const data = typeof source.data === \"function\" ? await source.data() : source.data;\n    const record = entryRecord(source.name, data);\n    central.push(centralHeader(record, offset));\n    yield* [localHeader(record), data];\n    offset = checkedSize(offset + 30 + record.name.length + data.length);\n  }\n  yield* trailer(central, offset);\n}\n\n/** Header fields shared by the local and central records of an entry. */\ninterface EntryRecord {\n  name: Buffer;\n  crc: number;\n  size: number;\n}\n\nconst MAX_U32 = 0xff_ff_ff_ff;\nconst MAX_ENTRIES = 0xff_ff;\n/** General-purpose flag bit 11: file names are UTF-8. */\nconst UTF8_FLAG = 0x08_00;\n/** 1980-01-01 in DOS date format — fixed so archives are byte-reproducible. */\nconst DOS_DATE = 0x00_21;\nconst VERSION = 20;\n\nfunction entryRecord(name: string, data: Buffer): EntryRecord {\n  return { name: Buffer.from(name, \"utf8\"), crc: crc32(data), size: checkedSize(data.length) };\n}\n\nfunction checkedSize(size: number): number {\n  if (size > MAX_U32) {\n    throw new Error(\"Archive exceeds 4 GiB (zip64 is not supported)\");\n  }\n  return size;\n}\n\n/** `[offset, width, value]` triples for a fixed-size header. */\ntype Fields = readonly (readonly [offset: number, width: 2 | 4, value: number])[];\n\nfunction header(size: number, fields: Fields, name?: Buffer): Buffer {\n  const out = Buffer.alloc(size);\n  for (const [offset, width, value] of fields) {\n    if (width === 2) {\n      out.writeUInt16LE(value, offset);\n    } else {\n      out.writeUInt32LE(value, offset);\n    }\n  }\n  return name ? Buffer.concat([out, name]) : out;\n}\n\nfunction localHeader(record: EntryRecord): Buffer {\n  return header(\n    30,\n    [\n      [0, 4, 0x04_03_4b_50],\n      [4, 2, VERSION],\n      [6, 2, UTF8_FLAG],\n      [12, 2, DOS_DATE],\n      [14, 4, record.crc],\n      [18, 4, record.size],\n      [22, 4, record.size],\n      [26, 2, record.name.length],\n    ],\n    record.name,\n  );\n}\n\nfunction centralHeader(record: EntryRecord, offset: number): Buffer {\n  return header(\n    46,\n    [\n      [0, 4, 0x02_01_4b_50],\n      [4, 2, VERSION],\n      [6, 2, VERSION],\n      [8, 2, UTF8_FLAG],\n      [14, 2, DOS_DATE],\n      [16, 4, record.crc],\n      [20, 4, record.size],\n      [24, 4, record.size],\n      [28, 2, record.name.length],\n      [42, 4, offset],\n    ],\n    record.name,\n  );\n}\n\nfunction* trailer(central: Buffer[], offset: number): Generator<Buffer> {\n  if (central.length > MAX_ENTRIES) {\n    throw new Error(\"Archive exceeds 65535 entries (zip64 is not supported)\");\n  }\n  const directory = Buffer.concat(central);\n  yield directory;\n  yield header(22, [\n    [0, 4, 0x06_05_4b_50],\n    [8, 2, central.length],\n    [10, 2, central.length],\n    [12, 4, directory.length],\n    [16, 4, checkedSize(offset)],\n  ]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAqBA,gBAAuB,UACrB,SACwB;CACxB,MAAM,UAAoB,CAAC;CAC3B,IAAI,SAAS;CACb,WAAW,MAAM,UAAU,SAAS;EAClC,MAAM,OAAO,OAAO,OAAO,SAAS,aAAa,MAAM,OAAO,KAAK,IAAI,OAAO;EAC9E,MAAM,SAAS,YAAY,OAAO,MAAM,IAAI;EAC5C,QAAQ,KAAK,cAAc,QAAQ,MAAM,CAAC;EAC1C,OAAO,CAAC,YAAY,MAAM,GAAG,IAAI;EACjC,SAAS,YAAY,SAAS,KAAK,OAAO,KAAK,SAAS,KAAK,MAAM;CACrE;CACA,OAAO,QAAQ,SAAS,MAAM;AAChC;AASA,MAAM,UAAU;AAChB,MAAM,cAAc;;AAEpB,MAAM,YAAY;;AAElB,MAAM,WAAW;AACjB,MAAM,UAAU;AAEhB,SAAS,YAAY,MAAc,MAA2B;CAC5D,OAAO;EAAE,MAAM,OAAO,KAAK,MAAM,MAAM;EAAG,KAAK,MAAM,IAAI;EAAG,MAAM,YAAY,KAAK,MAAM;CAAE;AAC7F;AAEA,SAAS,YAAY,MAAsB;CACzC,IAAI,OAAO,SACT,MAAM,IAAI,MAAM,gDAAgD;CAElE,OAAO;AACT;AAKA,SAAS,OAAO,MAAc,QAAgB,MAAuB;CACnE,MAAM,MAAM,OAAO,MAAM,IAAI;CAC7B,KAAK,MAAM,CAAC,QAAQ,OAAO,UAAU,QACnC,IAAI,UAAU,GACZ,IAAI,cAAc,OAAO,MAAM;MAE/B,IAAI,cAAc,OAAO,MAAM;CAGnC,OAAO,OAAO,OAAO,OAAO,CAAC,KAAK,IAAI,CAAC,IAAI;AAC7C;AAEA,SAAS,YAAY,QAA6B;CAChD,OAAO,OACL,IACA;EACE;GAAC;GAAG;GAAG;EAAa;EACpB;GAAC;GAAG;GAAG;EAAO;EACd;GAAC;GAAG;GAAG;EAAS;EAChB;GAAC;GAAI;GAAG;EAAQ;EAChB;GAAC;GAAI;GAAG,OAAO;EAAG;EAClB;GAAC;GAAI;GAAG,OAAO;EAAI;EACnB;GAAC;GAAI;GAAG,OAAO;EAAI;EACnB;GAAC;GAAI;GAAG,OAAO,KAAK;EAAM;CAC5B,GACA,OAAO,IACT;AACF;AAEA,SAAS,cAAc,QAAqB,QAAwB;CAClE,OAAO,OACL,IACA;EACE;GAAC;GAAG;GAAG;EAAa;EACpB;GAAC;GAAG;GAAG;EAAO;EACd;GAAC;GAAG;GAAG;EAAO;EACd;GAAC;GAAG;GAAG;EAAS;EAChB;GAAC;GAAI;GAAG;EAAQ;EAChB;GAAC;GAAI;GAAG,OAAO;EAAG;EAClB;GAAC;GAAI;GAAG,OAAO;EAAI;EACnB;GAAC;GAAI;GAAG,OAAO;EAAI;EACnB;GAAC;GAAI;GAAG,OAAO,KAAK;EAAM;EAC1B;GAAC;GAAI;GAAG;EAAM;CAChB,GACA,OAAO,IACT;AACF;AAEA,UAAU,QAAQ,SAAmB,QAAmC;CACtE,IAAI,QAAQ,SAAS,aACnB,MAAM,IAAI,MAAM,wDAAwD;CAE1E,MAAM,YAAY,OAAO,OAAO,OAAO;CACvC,MAAM;CACN,MAAM,OAAO,IAAI;EACf;GAAC;GAAG;GAAG;EAAa;EACpB;GAAC;GAAG;GAAG,QAAQ;EAAM;EACrB;GAAC;GAAI;GAAG,QAAQ;EAAM;EACtB;GAAC;GAAI;GAAG,UAAU;EAAM;EACxB;GAAC;GAAI;GAAG,YAAY,MAAM;EAAC;CAC7B,CAAC;AACH"}

package/dist/utils.d.mts

@@ -1,12 +1,26 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { KeyUsed, SecretInput, SecretKeys, UndecryptableCredentialError, decrypt, decryptCredential, decryptWithKey, encrypt } from "./utils/encrypt.mjs";
+import { Env, detectPublicBaseUrl, normalizeOrigin } from "./utils/public-origin.mjs";
 import { hmacSha256, randomToken, sha256, timingSafeEqualString } from "./utils/hash.mjs";
-import { HttpError, HttpRequestOptions, HttpTextOptions, httpJson, httpText } from "./utils/http.mjs";
-import { baselinePath, diffPath, screenshotPath, storybookDir, storybookZipPath } from "./paths.mjs";
+import { HttpError, HttpRequestOptions, HttpTextOptions, httpBytes, httpJson, httpText } from "./utils/http.mjs";
+import { baselinePath, catalogPath, contentDir, contentPath, designRenderPath, diffPath, isContentPath, modeSegment, screenshotPath, storybookDir, storybookZipPath } from "./paths.mjs";
+import { AdaptiveConcurrency, AdaptiveOptions, Observation, isTimeoutError } from "./utils/adaptive-concurrency.mjs";
+import { detectCaptureEnvironment, systemFontsHash } from "./utils/environment.mjs";
+import { RetryConnectOptions, isRetryableConnectError, retryConnect } from "./utils/connect-retry.mjs";
+import { BrowserProbe, FONT_PROBE_FAMILIES, inPageProbe, remoteEnvironment } from "./utils/remote-environment.mjs";
+import { storybookBase } from "./utils/storybook-url.mjs";
+import { DEFAULT_STORYBOOK_URL_TTL, MAX_STORYBOOK_URL_TTL, MIN_CAPTURES_PER_SLICE, MIN_STORYBOOK_URL_TTL, MIN_STORYBOOK_URL_TTL_OVERRIDE, PER_CAPTURE_BUDGET_MS, STORYBOOK_TOKEN_PREFIX, STORYBOOK_TOKEN_SOURCE, STORYBOOK_URL_TTL_GRACE, SignStorybookTokenInput, StorybookTokenClaims, StorybookTokenFailure, StorybookTokenResult, assertStorybookUrlTtl, signStorybookToken, storybookTokenPath, storybookUrlTtl, storybookUrlTtlOverrideError, verifyStorybookToken } from "./utils/storybook-token.mjs";
+import { SessionGate, createSessionGate, sessionGateFor } from "./utils/session-gate.mjs";
+import { storeScreenshot } from "./utils/screenshot-store.mjs";
+import { PageLimiter, PageLimiterOptions, createPageLimiter } from "./utils/page-limiter.mjs";
+import { mapAdaptive } from "./utils/map-adaptive.mjs";
+import { chunk, mapLimit } from "./utils/map-limit.mjs";
+import { CaptureHostSummary, DEFAULT_RECYCLE_BROWSER_EVERY, HostResources, describeCaptureHost, describeSizing, detectResources, engineWeight, maxPageConcurrency, recommendedBuildConcurrency, recommendedNavigationTimeoutMs, recommendedPageConcurrency } from "./utils/resources.mjs";
 import { MIME_TYPES, mimeFor } from "./utils/mime.mjs";
 import { isBlockedTarget, isPathSafe, isSafeSegment } from "./utils/path-security.mjs";
 import { redactSecrets, sanitizeErrorText } from "./utils/redact.mjs";
 import { TimingMap, addTiming, roundedTimings, runWithTimings, timed } from "./utils/timing.mjs";
 import { slugify, ulid } from "./utils/ulid.mjs";
-export { HttpError, type HttpRequestOptions, type HttpTextOptions, type KeyUsed, MIME_TYPES, type SecretInput, type SecretKeys, type TimingMap, UndecryptableCredentialError, addTiming, baselinePath, decrypt, decryptCredential, decryptWithKey, diffPath, encrypt, hmacSha256, httpJson, httpText, isBlockedTarget, isPathSafe, isSafeSegment, mimeFor, randomToken, redactSecrets, roundedTimings, runWithTimings, sanitizeErrorText, screenshotPath, sha256, slugify, storybookDir, storybookZipPath, timed, timingSafeEqualString, ulid };
+import { ZipSource, zipStream } from "./utils/zip-write.mjs";
+export { AdaptiveConcurrency, type AdaptiveOptions, type BrowserProbe, type CaptureHostSummary, DEFAULT_RECYCLE_BROWSER_EVERY, DEFAULT_STORYBOOK_URL_TTL, type Env, FONT_PROBE_FAMILIES, type HostResources, HttpError, type HttpRequestOptions, type HttpTextOptions, type KeyUsed, MAX_STORYBOOK_URL_TTL, MIME_TYPES, MIN_CAPTURES_PER_SLICE, MIN_STORYBOOK_URL_TTL, MIN_STORYBOOK_URL_TTL_OVERRIDE, type Observation, PER_CAPTURE_BUDGET_MS, type PageLimiter, type PageLimiterOptions, type RetryConnectOptions, STORYBOOK_TOKEN_PREFIX, STORYBOOK_TOKEN_SOURCE, STORYBOOK_URL_TTL_GRACE, type SecretInput, type SecretKeys, type SessionGate, type SignStorybookTokenInput, type StorybookTokenClaims, type StorybookTokenFailure, type StorybookTokenResult, type TimingMap, UndecryptableCredentialError, type ZipSource, addTiming, assertStorybookUrlTtl, baselinePath, catalogPath, chunk, contentDir, contentPath, createPageLimiter, createSessionGate, decrypt, decryptCredential, decryptWithKey, describeCaptureHost, describeSizing, designRenderPath, detectCaptureEnvironment, detectPublicBaseUrl, detectResources, diffPath, encrypt, engineWeight, hmacSha256, httpBytes, httpJson, httpText, inPageProbe, isBlockedTarget, isContentPath, isPathSafe, isRetryableConnectError, isSafeSegment, isTimeoutError, mapAdaptive, mapLimit, maxPageConcurrency, mimeFor, modeSegment, normalizeOrigin, randomToken, recommendedBuildConcurrency, recommendedNavigationTimeoutMs, recommendedPageConcurrency, redactSecrets, remoteEnvironment, retryConnect, roundedTimings, runWithTimings, sanitizeErrorText, screenshotPath, sessionGateFor, sha256, signStorybookToken, slugify, storeScreenshot, storybookBase, storybookDir, storybookTokenPath, storybookUrlTtl, storybookUrlTtlOverrideError, storybookZipPath, systemFontsHash, timed, timingSafeEqualString, ulid, verifyStorybookToken, zipStream };

package/dist/utils.mjs

@@ -1,13 +1,27 @@
 import "node:path";
 import "node:url";
 import.meta.url;
+import { hmacSha256, randomToken, sha256, timingSafeEqualString } from "./utils/hash.mjs";
+import { DEFAULT_STORYBOOK_URL_TTL, MAX_STORYBOOK_URL_TTL, MIN_CAPTURES_PER_SLICE, MIN_STORYBOOK_URL_TTL, MIN_STORYBOOK_URL_TTL_OVERRIDE, PER_CAPTURE_BUDGET_MS, STORYBOOK_TOKEN_PREFIX, STORYBOOK_TOKEN_SOURCE, STORYBOOK_URL_TTL_GRACE, assertStorybookUrlTtl, signStorybookToken, storybookTokenPath, storybookUrlTtl, storybookUrlTtlOverrideError, verifyStorybookToken } from "./utils/storybook-token.mjs";
 import { redactSecrets, sanitizeErrorText } from "./utils/redact.mjs";
 import { UndecryptableCredentialError, decrypt, decryptCredential, decryptWithKey, encrypt } from "./utils/encrypt.mjs";
 import { slugify, ulid } from "./utils/ulid.mjs";
-import { hmacSha256, randomToken, sha256, timingSafeEqualString } from "./utils/hash.mjs";
 import { addTiming, roundedTimings, runWithTimings, timed } from "./utils/timing.mjs";
 import { isBlockedTarget, isPathSafe, isSafeSegment } from "./utils/path-security.mjs";
-import { baselinePath, diffPath, screenshotPath, storybookDir, storybookZipPath } from "./paths.mjs";
-import { HttpError, httpJson, httpText } from "./utils/http.mjs";
+import { baselinePath, catalogPath, contentDir, contentPath, designRenderPath, diffPath, isContentPath, modeSegment, screenshotPath, storybookDir, storybookZipPath } from "./paths.mjs";
+import { storeScreenshot } from "./utils/screenshot-store.mjs";
+import { chunk, mapLimit } from "./utils/map-limit.mjs";
+import { DEFAULT_RECYCLE_BROWSER_EVERY, describeCaptureHost, describeSizing, detectResources, engineWeight, maxPageConcurrency, recommendedBuildConcurrency, recommendedNavigationTimeoutMs, recommendedPageConcurrency } from "./utils/resources.mjs";
+import { detectPublicBaseUrl, normalizeOrigin } from "./utils/public-origin.mjs";
+import { zipStream } from "./utils/zip-write.mjs";
+import { HttpError, httpBytes, httpJson, httpText } from "./utils/http.mjs";
+import { AdaptiveConcurrency, isTimeoutError } from "./utils/adaptive-concurrency.mjs";
+import { detectCaptureEnvironment, systemFontsHash } from "./utils/environment.mjs";
+import { isRetryableConnectError, retryConnect } from "./utils/connect-retry.mjs";
+import { FONT_PROBE_FAMILIES, inPageProbe, remoteEnvironment } from "./utils/remote-environment.mjs";
+import { storybookBase } from "./utils/storybook-url.mjs";
+import { createSessionGate, sessionGateFor } from "./utils/session-gate.mjs";
+import { mapAdaptive } from "./utils/map-adaptive.mjs";
+import { createPageLimiter } from "./utils/page-limiter.mjs";
 import { MIME_TYPES, mimeFor } from "./utils/mime.mjs";
-export { HttpError, MIME_TYPES, UndecryptableCredentialError, addTiming, baselinePath, decrypt, decryptCredential, decryptWithKey, diffPath, encrypt, hmacSha256, httpJson, httpText, isBlockedTarget, isPathSafe, isSafeSegment, mimeFor, randomToken, redactSecrets, roundedTimings, runWithTimings, sanitizeErrorText, screenshotPath, sha256, slugify, storybookDir, storybookZipPath, timed, timingSafeEqualString, ulid };
+export { AdaptiveConcurrency, DEFAULT_RECYCLE_BROWSER_EVERY, DEFAULT_STORYBOOK_URL_TTL, FONT_PROBE_FAMILIES, HttpError, MAX_STORYBOOK_URL_TTL, MIME_TYPES, MIN_CAPTURES_PER_SLICE, MIN_STORYBOOK_URL_TTL, MIN_STORYBOOK_URL_TTL_OVERRIDE, PER_CAPTURE_BUDGET_MS, STORYBOOK_TOKEN_PREFIX, STORYBOOK_TOKEN_SOURCE, STORYBOOK_URL_TTL_GRACE, UndecryptableCredentialError, addTiming, assertStorybookUrlTtl, baselinePath, catalogPath, chunk, contentDir, contentPath, createPageLimiter, createSessionGate, decrypt, decryptCredential, decryptWithKey, describeCaptureHost, describeSizing, designRenderPath, detectCaptureEnvironment, detectPublicBaseUrl, detectResources, diffPath, encrypt, engineWeight, hmacSha256, httpBytes, httpJson, httpText, inPageProbe, isBlockedTarget, isContentPath, isPathSafe, isRetryableConnectError, isSafeSegment, isTimeoutError, mapAdaptive, mapLimit, maxPageConcurrency, mimeFor, modeSegment, normalizeOrigin, randomToken, recommendedBuildConcurrency, recommendedNavigationTimeoutMs, recommendedPageConcurrency, redactSecrets, remoteEnvironment, retryConnect, roundedTimings, runWithTimings, sanitizeErrorText, screenshotPath, sessionGateFor, sha256, signStorybookToken, slugify, storeScreenshot, storybookBase, storybookDir, storybookTokenPath, storybookUrlTtl, storybookUrlTtlOverrideError, storybookZipPath, systemFontsHash, timed, timingSafeEqualString, ulid, verifyStorybookToken, zipStream };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storyshelf/core",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "StoryShelf core: adapter interfaces, models, capture pipeline, diff, and retention (no HTTP).",
   "keywords": [
     "chromatic-alternative",
@@ -46,22 +46,14 @@
       "source": "./src/adapters/database.ts",
       "default": "./dist/adapter/database.mjs"
     },
+    "./adapter/design": {
+      "source": "./src/adapters/design.ts",
+      "default": "./dist/adapter/design.mjs"
+    },
     "./adapter/email-sender": {
       "source": "./src/adapters/email-sender.ts",
       "default": "./dist/adapter/email-sender.mjs"
     },
-    "./adapter/git-host": {
-      "source": "./src/adapters/git-host/index.ts",
-      "default": "./dist/adapter/git-host.mjs"
-    },
-    "./adapter/git-host/comments": {
-      "source": "./src/adapters/git-host/comments.ts",
-      "default": "./dist/adapter/git-host/comments.mjs"
-    },
-    "./adapter/git-host/helpers": {
-      "source": "./src/adapters/git-host/helpers.ts",
-      "default": "./dist/adapter/git-host/helpers.mjs"
-    },
     "./adapter/metadata": {
       "source": "./src/adapters/metadata.ts",
       "default": "./dist/adapter/metadata.mjs"
@@ -70,6 +62,10 @@
       "source": "./src/adapters/notifier/index.ts",
       "default": "./dist/adapter/notifier.mjs"
     },
+    "./adapter/oauth": {
+      "source": "./src/adapters/oauth.ts",
+      "default": "./dist/adapter/oauth.mjs"
+    },
     "./adapter/setup": {
       "source": "./src/adapters/setup.ts",
       "default": "./dist/adapter/setup.mjs"
@@ -82,6 +78,10 @@
       "source": "./src/adapters/webhook-events.ts",
       "default": "./dist/adapter/webhook-events.mjs"
     },
+    "./ai": {
+      "source": "./src/ai.ts",
+      "default": "./dist/ai.mjs"
+    },
     "./auth": {
       "source": "./src/auth.ts",
       "default": "./dist/auth.mjs"
@@ -98,6 +98,10 @@
       "source": "./src/diff/index.ts",
       "default": "./dist/diff.mjs"
     },
+    "./insights": {
+      "source": "./src/insights/index.ts",
+      "default": "./dist/insights.mjs"
+    },
     "./logger": {
       "source": "./src/logger.ts",
       "default": "./dist/logger.mjs"
@@ -154,19 +158,20 @@
       "./adapter/capture-queue": "./dist/adapter/capture-queue.mjs",
       "./adapter/capture-runner": "./dist/adapter/capture-runner.mjs",
       "./adapter/database": "./dist/adapter/database.mjs",
+      "./adapter/design": "./dist/adapter/design.mjs",
       "./adapter/email-sender": "./dist/adapter/email-sender.mjs",
-      "./adapter/git-host": "./dist/adapter/git-host.mjs",
-      "./adapter/git-host/comments": "./dist/adapter/git-host/comments.mjs",
-      "./adapter/git-host/helpers": "./dist/adapter/git-host/helpers.mjs",
       "./adapter/metadata": "./dist/adapter/metadata.mjs",
       "./adapter/notifier": "./dist/adapter/notifier.mjs",
+      "./adapter/oauth": "./dist/adapter/oauth.mjs",
       "./adapter/setup": "./dist/adapter/setup.mjs",
       "./adapter/storage": "./dist/adapter/storage.mjs",
       "./adapter/webhook-events": "./dist/adapter/webhook-events.mjs",
+      "./ai": "./dist/ai.mjs",
       "./auth": "./dist/auth.mjs",
       "./capture": "./dist/capture.mjs",
       "./config": "./dist/config.mjs",
       "./diff": "./dist/diff.mjs",
+      "./insights": "./dist/insights.mjs",
       "./logger": "./dist/logger.mjs",
       "./models": "./dist/models.mjs",
       "./orm": "./dist/orm.mjs",
@@ -192,31 +197,38 @@
     "prepublishOnly": "nub run build",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "test:flake": "vitest run --repeats=20 --maxWorkers=1 --no-file-parallelism src/utils/map-limit.test.ts src/utils/session-gate.test.ts src/utils/page-limiter.test.ts src/utils/adaptive-concurrency.test.ts src/capture/rediff.test.ts src/models/build.test.ts src/models/design-credentials.test.ts"
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@storyshelf/affected": "0.6.1",
+    "@storyshelf/affected": "0.7.0",
+    "@storyshelf/image": "0.7.0",
+    "axe-core": "4.13.0",
     "drizzle-orm": "^0.44.0",
     "pino": "^10.3.1",
-    "pixelmatch": "^7.1.0",
-    "pngjs": "^7.0.0",
     "unzipper": "0.12.5",
     "zod": "^4.2.0"
   },
   "devDependencies": {
+    "@types/jsdom": "^30.0.0",
     "@types/node": "^26.0.0",
     "@types/pngjs": "^6.0.5",
     "@types/unzipper": "0.10.11",
     "@vitest/coverage-v8": "^4.0.0",
     "adm-zip": "^0.6.1",
+    "jsdom": "^30.0.1",
     "oxfmt": "^0.65.0",
     "oxlint": "^1.80.0",
     "oxlint-tsgolint": "^7.0.2001",
+    "pngjs": "^7.0.0",
     "tsdown": "^0.22.14",
     "typescript": "^7.0.2",
     "vitest": "^5.0.0"
   },
+  "engines": {
+    "node": ">=24"
+  },
   "jsr": {
     "runtimeCompat": {
       "node": true,

package/dist/adapter/capture-runner.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"capture-runner.mjs","names":[],"sources":["../../src/adapters/capture-runner.ts"],"sourcesContent":["/**\n * Capture-runner adapter interface: render story screenshots for a build.\n */\nimport type { Logger } from \"pino\";\nimport type { StoryEntry, StorySourceAdapter, Viewport } from \"../capture/adapter.ts\";\nimport type { Adapter } from \"./metadata.ts\";\n\nexport type { JobStatus } from \"./capture-queue.ts\";\nexport type { StoryEntry, StorySourceAdapter, Viewport } from \"../capture/adapter.ts\";\n\n/** A screenshot produced by a capture renderer. */\nexport interface RenderedSnapshot {\n  /** The rendered story (echoed back from the render request). */\n  story: StoryEntry;\n  /** Viewport name the screenshot was captured at. */\n  viewportName: string;\n  /** Exact viewport dimensions captured at; falls back to the project list lookup in the pipeline. */\n  viewport?: Viewport;\n  /** PNG screenshot bytes. */\n  screenshot: Buffer;\n}\n\n/** A story/viewport that a renderer could not capture. */\nexport interface RenderFailure {\n  /** Story that failed to render. */\n  storyId: string;\n  /** Viewport that failed to render. */\n  viewportName: string;\n  /** Error message. */\n  error: string;\n}\n\n/** The outcome of a render request. */\nexport interface RenderResult {\n  /** Screenshots the renderer produced successfully. */\n  captures: RenderedSnapshot[];\n  /** Story/viewport pairs the renderer could not capture. */\n  failures: RenderFailure[];\n}\n\n/**\n * A pure capture renderer.\n *\n * Adapters implementing `CaptureRunner` render screenshots from an\n * already-extracted Storybook directory and return PNG buffers. They are\n * intentionally pure: they perform **no** database, storage, or build-state\n * management. Loading the build, extracting the uploaded archive, persisting\n * snapshots/baselines/diffs, and advancing build status are the capture\n * orchestrator's job (see `capture/orchestrator.ts`), keeping every adapter\n * implementation free of server concerns.\n */\nexport type BrowserName = \"chromium\" | \"firefox\" | \"webkit\" | \"chrome\";\n\n/** Browser names accepted for capture rendering (Chromium default). */\nexport const BROWSER_NAMES = [\"chromium\", \"firefox\", \"webkit\", \"chrome\"] as const;\n\nexport interface CaptureRunner extends Adapter<{\n  readonly category: \"capture-runner\";\n  readonly supportedBrowsers?: readonly BrowserName[];\n}> {\n  /**\n   * Render configured viewports for the given stories of an extracted\n   * Storybook and return the screenshot buffers.\n   *\n   * @param input - Render request with the extracted Storybook directory.\n   */\n  render(input: {\n    /** Build being captured, used to correlate cancels with in-flight work. */\n    buildId: string;\n    /** Root of the already-extracted Storybook build. */\n    storybookDir: string;\n    /** Stories to render. */\n    stories: StoryEntry[];\n    /** Viewports to capture. */\n    viewports: Viewport[];\n    /** Optional logger for render-time diagnostics. */\n    logger?: Logger;\n    /** Whether to execute Storybook play functions before screenshot. */\n    executePlay?: boolean;\n    /** Timeout for play function execution in ms. */\n    playTimeoutMs?: number;\n    /** Whether to run a11y checks (axe) before screenshot; annotated as non-blocking. */\n    runA11y?: boolean;\n    /** Browser to use for rendering (chromium default). */\n    browser?: BrowserName;\n    /**\n     * Test/extension seam: override the story source adapter (defaults to\n     * `StorybookAdapter`). Only the renderer uses it; discovery stays the\n     * orchestrator's job.\n     */\n    adapter?: StorySourceAdapter;\n  }): Promise<RenderResult>;\n\n  /** Cancel a pending or in-flight render for a build. */\n  cancel(buildId: string): Promise<void>;\n}\n"],"mappings":";;;;;AAsDA,MAAa,gBAAgB;CAAC;CAAY;CAAW;CAAU;AAAQ"}

package/dist/adapter/git-host/comments.d.mts

@@ -1,41 +0,0 @@
-import __tsdown_shims_path from 'node:path';
-import __tsdown_shims_url from 'node:url';
-import { Logger } from "pino";
-//#region src/adapters/git-host/comments.d.ts
-/** A review thread (PR or MR) hosting a single StoryShelf comment. */
-interface ReviewThread {
-  /** List existing comments as id/body pairs. */
-  list(): Promise<{
-    id: string | number;
-    body: string;
-  }[]>;
-  /** Replace the body of an existing comment, returning its id. */
-  update(id: string | number, body: string): Promise<string>;
-  /** Create a comment, returning its id. */
-  create(body: string): Promise<string>;
-}
-/** Dependencies for an idempotent review-comment upsert. */
-interface UpsertReviewCommentOptions {
-  /** Canonical build/review URL — anchors the idempotency marker. */
-  url: string;
-  /** Markdown body appended below the marker. */
-  markdown: string;
-  /** Known thread number, skipping the lookup when provided. */
-  prNumber?: number;
-  /** Commit SHA used for the thread lookup and log context. */
-  sha: string;
-  logger?: Logger;
-  /** Resolve the thread number for the commit (PR number or MR iid). */
-  resolveNumber: () => Promise<number | undefined>;
-  /** Open the thread's comment store once the number is known. */
-  thread: (number: number) => ReviewThread;
-}
-/**
- * Create or update the single StoryShelf review comment for a build,
- * idempotent via the url marker. Returns the comment id, or `""` when no
- * review thread exists for the commit.
- */
-declare function upsertReviewComment(opts: UpsertReviewCommentOptions): Promise<string>;
-//#endregion
-export { ReviewThread, UpsertReviewCommentOptions, upsertReviewComment };
-//# sourceMappingURL=comments.d.mts.map