@storyshelf/core 0.6.2 → 0.7.0

package/dist/test-helpers/queue-multi-instance.mjs

@@ -0,0 +1,206 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { CaptureJobModel, attemptRowId } from "../models/capture-job.mjs";
+import { LEASE_EXHAUSTED_ERROR } from "../capture/db-queue/claim.mjs";
+import { createDatabaseCaptureQueue } from "../capture/db-queue/index.mjs";
+import { describe, expect, it } from "vitest";
+//#region src/test-helpers/queue-multi-instance.ts
+/**
+* Multi-instance suite for the database capture queue: several queue instances (one per simulated
+* app instance) share ONE database, the way horizontally scaled app instances do. Database packages
+* run it against their own drivers (node:sqlite, PGlite, and the gated live Postgres, MySQL and
+* Turso tests):
+*
+* ```ts
+* import { databaseQueueMultiInstanceSuite } from "@storyshelf/core/test-helpers";
+* databaseQueueMultiInstanceSuite("sqlite", async () => await setUp(createSqliteDatabase(":memory:")));
+* ```
+*
+* Every instance reads one shared manual clock, so lease expiry and retry delays are exact and no
+* case sleeps. Build ids are unique per run, so a shared live database needs no cleanup between runs.
+*/
+const LEASE_MS = 6e4;
+const RETRIES = 2;
+async function fleet(makeDb, size, kinds = ["capture"]) {
+	const db = await makeDb();
+	const clock = { now: Date.now() };
+	const queues = Array.from({ length: size }, (_unused, index) => createDatabaseCaptureQueue(db, {
+		kinds,
+		leaseMs: LEASE_MS,
+		retries: RETRIES,
+		owner: `instance-${String(index)}`,
+		now: () => clock.now
+	}));
+	const advance = (ms) => {
+		clock.now += ms;
+	};
+	return {
+		db,
+		queues,
+		advance,
+		runId: `mi-${String(clock.now)}-${Math.random().toString(36).slice(2, 8)}`
+	};
+}
+/** Poll on every instance at once, as concurrent app instances would. */
+async function pollAll(queues) {
+	return (await Promise.all(queues.map(async (queue) => await queue.poll()))).filter((job) => job !== null);
+}
+/** Poll every instance until one returns the job of `buildId` (others' jobs are acked away). */
+async function claimOn(queue, buildId) {
+	for (let tries = 0; tries < 50; tries += 1) {
+		const job = await queue.poll();
+		if (job === null || job.buildId === buildId) return job;
+		await queue.ack(job);
+	}
+	return null;
+}
+/** Run the multi-instance suite against databases from `makeDb`. */
+function databaseQueueMultiInstanceSuite(label, makeDb, options = {}) {
+	const size = options.instances ?? 4;
+	const jobs = options.jobs ?? 24;
+	describe(`database queue, ${String(size)} instances on one database: ${label}`, () => {
+		exactlyOnceCase(makeDb, size, jobs, options.timeoutMs);
+		leaseCases(makeDb, size, options.timeoutMs);
+		retryCases(makeDb, size, options.timeoutMs);
+		cancelAndKindCases(makeDb, size, options.timeoutMs);
+	});
+}
+function exactlyOnceCase(makeDb, size, jobs, timeoutMs) {
+	it("runs each job exactly once across instances polling at the same time", async () => {
+		const { queues, runId } = await fleet(makeDb, size);
+		const ids = Array.from({ length: jobs }, (_unused, index) => `${runId}-${String(index)}`);
+		await Promise.all(ids.map(async (buildId, index) => await queues[index % size].enqueue({ buildId })));
+		const claims = /* @__PURE__ */ new Map();
+		const ours = new Set(ids);
+		for (let round = 0; round < jobs * 2 + 20 && claims.size < jobs; round += 1) {
+			const claimed = await pollAll(queues);
+			for (const job of claimed.filter((one) => ours.has(one.buildId))) claims.set(job.buildId, (claims.get(job.buildId) ?? 0) + 1);
+			await Promise.all(claimed.map(async (job) => await queues[0].ack(job)));
+		}
+		expect([...claims.keys()].toSorted()).toEqual(ids.toSorted());
+		expect([...claims.values()].every((count) => count === 1)).toBe(true);
+		const statuses = await Promise.all(ids.map(async (id) => (await queues[1].status(id))?.status));
+		expect(new Set(statuses)).toEqual(/* @__PURE__ */ new Set(["completed"]));
+	}, timeoutMs);
+}
+function leaseCases(makeDb, size, timeoutMs) {
+	it("redelivers an expired lease to another instance and fences the stale holder", async () => {
+		const { db, queues, advance, runId } = await fleet(makeDb, size);
+		const [first, second] = [queues[0], queues[1]];
+		const buildId = `${runId}-lease`;
+		await first.enqueue({ buildId });
+		const stale = await claimOn(first, buildId);
+		expect(stale?.attempt).toBe(1);
+		expect(await claimOn(second, buildId)).toBeNull();
+		advance(60001);
+		const winners = (await pollAll(queues)).filter((job) => job.buildId === buildId);
+		expect(winners).toHaveLength(1);
+		const fresh = winners[0];
+		expect(fresh.attempt).toBe(2);
+		const model = new CaptureJobModel(db);
+		const leaseBefore = (await model.get(attemptRowId(fresh.jobId, 2)))?.visibleAt;
+		expect(await first.extend(stale)).toBe("lost");
+		expect(await first.inspect(stale)).toBe("lost");
+		await first.nack(stale, {
+			requeue: true,
+			error: "stale"
+		});
+		const after = await model.get(fresh.jobId);
+		expect(after).toMatchObject({
+			status: "running",
+			attempt: 2
+		});
+		expect((await model.get(attemptRowId(fresh.jobId, 2)))?.visibleAt).toBe(leaseBefore);
+		expect((await model.get(attemptRowId(fresh.jobId, 1)))?.status).toBe("expired");
+		expect(await second.extend(fresh)).toBe("ok");
+		await second.ack(fresh);
+		await first.ack(stale);
+		expect((await second.status(buildId))?.status).toBe("completed");
+	}, timeoutMs);
+}
+function retryCases(makeDb, size, timeoutMs) {
+	it("fails a job on any instance once its retries are spent", async () => {
+		const { queues, advance, runId } = await fleet(makeDb, size);
+		const buildId = `${runId}-retry`;
+		await queues[0].enqueue({ buildId });
+		for (let attempt = 1; attempt <= 3; attempt += 1) {
+			const queue = queues[attempt % size];
+			const job = await claimOn(queue, buildId);
+			expect(job?.attempt).toBe(attempt);
+			await queue.nack(job, {
+				requeue: true,
+				delayMs: 1e3,
+				error: `boom ${String(attempt)}`
+			});
+			advance(1001);
+		}
+		expect(await claimOn(queues[0], buildId)).toBeNull();
+		expect(await queues[2 % size].status(buildId)).toMatchObject({
+			status: "failed",
+			error: `boom ${String(3)}`
+		});
+	}, timeoutMs);
+	it("fails a job whose every attempt lost its lease", async () => {
+		const { queues, advance, runId } = await fleet(makeDb, size);
+		const buildId = `${runId}-hung`;
+		await queues[0].enqueue({ buildId });
+		for (let attempt = 1; attempt <= 3; attempt += 1) {
+			const job = await claimOn(queues[attempt % size], buildId);
+			expect(job?.attempt).toBe(attempt);
+			advance(60001);
+		}
+		expect(await claimOn(queues[0], buildId)).toBeNull();
+		expect(await queues[1].status(buildId)).toMatchObject({
+			status: "failed",
+			error: LEASE_EXHAUSTED_ERROR
+		});
+	}, timeoutMs);
+}
+function cancelAndKindCases(makeDb, size, timeoutMs) {
+	it("lets one instance cancel a job another instance holds", async () => {
+		const { queues, runId } = await fleet(makeDb, size);
+		const [holder, other] = [queues[0], queues[1]];
+		const buildId = `${runId}-cancel`;
+		await other.enqueue({ buildId });
+		const job = await claimOn(holder, buildId);
+		expect(await holder.inspect(job)).toBe("ok");
+		expect(await other.cancel(buildId)).toBe(true);
+		expect(await holder.inspect(job)).toBe("cancelled");
+		expect(await holder.extend(job)).toBe("cancelled");
+		await holder.nack(job, {
+			requeue: false,
+			error: "cancelled"
+		});
+		expect((await other.status(buildId))?.status).toBe("cancelled");
+		expect(await claimOn(other, buildId)).toBeNull();
+	}, timeoutMs);
+	it("keeps job kinds independent", async () => {
+		const shared = await makeDb();
+		const reuse = () => shared;
+		const capture = await fleet(reuse, 2, ["capture"]);
+		const publish = await fleet(reuse, 2, ["publish"]);
+		const buildId = `${capture.runId}-kinds`;
+		await capture.queues[0].enqueue({ buildId });
+		await publish.queues[0].enqueueJob({
+			kind: "publish",
+			buildId,
+			data: { zip: "k" }
+		});
+		const published = await claimOn(publish.queues[1], buildId);
+		expect(published).toMatchObject({
+			kind: "publish",
+			data: { zip: "k" }
+		});
+		const captured = await claimOn(capture.queues[1], buildId);
+		expect(captured?.kind).toBe("capture");
+		expect(await claimOn(publish.queues[0], buildId)).toBeNull();
+		await publish.queues[1].ack(published);
+		await capture.queues[1].ack(captured);
+		expect((await capture.queues[0].status(buildId))?.status).toBe("completed");
+	}, timeoutMs);
+}
+//#endregion
+export { databaseQueueMultiInstanceSuite };
+
+//# sourceMappingURL=queue-multi-instance.mjs.map

package/dist/test-helpers/queue-multi-instance.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-multi-instance.mjs","names":[],"sources":["../../src/test-helpers/queue-multi-instance.ts"],"sourcesContent":["/**\n * Multi-instance suite for the database capture queue: several queue instances (one per simulated\n * app instance) share ONE database, the way horizontally scaled app instances do. Database packages\n * run it against their own drivers (node:sqlite, PGlite, and the gated live Postgres, MySQL and\n * Turso tests):\n *\n * ```ts\n * import { databaseQueueMultiInstanceSuite } from \"@storyshelf/core/test-helpers\";\n * databaseQueueMultiInstanceSuite(\"sqlite\", async () => await setUp(createSqliteDatabase(\":memory:\")));\n * ```\n *\n * Every instance reads one shared manual clock, so lease expiry and retry delays are exact and no\n * case sleeps. Build ids are unique per run, so a shared live database needs no cleanup between runs.\n */\nimport { describe, expect, it } from \"vitest\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport {\n  createDatabaseCaptureQueue,\n  LEASE_EXHAUSTED_ERROR,\n  type DatabaseCaptureQueue,\n  type DatabaseJob,\n} from \"../capture/db-queue/index.ts\";\nimport { attemptRowId, CaptureJobModel } from \"../models/capture-job.ts\";\nimport type { CaptureJobKind } from \"../schema/capture-job.ts\";\n\n/** A set-up database the instances of one case share. */\nexport type SharedDatabaseFactory = () => DatabaseAdapter | Promise<DatabaseAdapter>;\n\n/** Options of {@link databaseQueueMultiInstanceSuite}. */\nexport interface MultiInstanceOptions {\n  /** Queue instances sharing the database (default 4). */\n  instances?: number;\n  /** Jobs in the exactly-once case (default 24). */\n  jobs?: number;\n  /** Per-case timeout in ms, for slow remote databases (default vitest's). */\n  timeoutMs?: number;\n}\n\nconst LEASE_MS = 60_000;\nconst RETRIES = 2;\n\ninterface Fleet {\n  db: DatabaseAdapter;\n  queues: DatabaseCaptureQueue[];\n  advance: (ms: number) => void;\n  runId: string;\n}\n\nasync function fleet(\n  makeDb: SharedDatabaseFactory,\n  size: number,\n  kinds: readonly CaptureJobKind[] = [\"capture\"],\n): Promise<Fleet> {\n  const db = await makeDb();\n  const clock = { now: Date.now() };\n  const queues = Array.from({ length: size }, (_unused, index) =>\n    createDatabaseCaptureQueue(db, {\n      kinds,\n      leaseMs: LEASE_MS,\n      retries: RETRIES,\n      owner: `instance-${String(index)}`,\n      now: () => clock.now,\n    }),\n  );\n  const advance = (ms: number): void => {\n    clock.now += ms;\n  };\n  return {\n    db,\n    queues,\n    advance,\n    runId: `mi-${String(clock.now)}-${Math.random().toString(36).slice(2, 8)}`,\n  };\n}\n\n/** Poll on every instance at once, as concurrent app instances would. */\nasync function pollAll(queues: DatabaseCaptureQueue[]): Promise<DatabaseJob[]> {\n  const jobs = await Promise.all(queues.map(async (queue) => await queue.poll()));\n  return jobs.filter((job): job is DatabaseJob => job !== null);\n}\n\n/** Poll every instance until one returns the job of `buildId` (others' jobs are acked away). */\nasync function claimOn(queue: DatabaseCaptureQueue, buildId: string): Promise<DatabaseJob | null> {\n  for (let tries = 0; tries < 50; tries += 1) {\n    // oxlint-disable-next-line eslint/no-await-in-loop -- sequential polls are the point\n    const job = await queue.poll();\n    if (job === null || job.buildId === buildId) {\n      return job;\n    }\n    // oxlint-disable-next-line eslint/no-await-in-loop -- clear a leftover of another case\n    await queue.ack(job);\n  }\n  return null;\n}\n\n/** Run the multi-instance suite against databases from `makeDb`. */\nexport function databaseQueueMultiInstanceSuite(\n  label: string,\n  makeDb: SharedDatabaseFactory,\n  options: MultiInstanceOptions = {},\n): void {\n  const size = options.instances ?? 4;\n  const jobs = options.jobs ?? 24;\n  describe(`database queue, ${String(size)} instances on one database: ${label}`, () => {\n    exactlyOnceCase(makeDb, size, jobs, options.timeoutMs);\n    leaseCases(makeDb, size, options.timeoutMs);\n    retryCases(makeDb, size, options.timeoutMs);\n    cancelAndKindCases(makeDb, size, options.timeoutMs);\n  });\n}\n\nfunction exactlyOnceCase(\n  makeDb: SharedDatabaseFactory,\n  size: number,\n  jobs: number,\n  timeoutMs?: number,\n): void {\n  it(\n    \"runs each job exactly once across instances polling at the same time\",\n    async () => {\n      const { queues, runId } = await fleet(makeDb, size);\n      const ids = Array.from({ length: jobs }, (_unused, index) => `${runId}-${String(index)}`);\n      await Promise.all(\n        ids.map(async (buildId, index) => await queues[index % size]!.enqueue({ buildId })),\n      );\n      const claims = new Map<string, number>();\n      const ours = new Set(ids);\n      for (let round = 0; round < jobs * 2 + 20 && claims.size < jobs; round += 1) {\n        // oxlint-disable-next-line eslint/no-await-in-loop -- rounds of concurrent polls\n        const claimed = await pollAll(queues);\n        // A shared (live) database may hold other runs' jobs: settle them, count only ours.\n        for (const job of claimed.filter((one) => ours.has(one.buildId))) {\n          claims.set(job.buildId, (claims.get(job.buildId) ?? 0) + 1);\n        }\n        // oxlint-disable-next-line eslint/no-await-in-loop -- see above\n        await Promise.all(claimed.map(async (job) => await queues[0]!.ack(job)));\n      }\n      expect([...claims.keys()].toSorted()).toEqual(ids.toSorted());\n      expect([...claims.values()].every((count) => count === 1)).toBe(true);\n      const statuses = await Promise.all(\n        ids.map(async (id) => (await queues[1]!.status(id))?.status),\n      );\n      expect(new Set(statuses)).toEqual(new Set([\"completed\"]));\n    },\n    timeoutMs,\n  );\n}\n\nfunction leaseCases(makeDb: SharedDatabaseFactory, size: number, timeoutMs?: number): void {\n  it(\n    \"redelivers an expired lease to another instance and fences the stale holder\",\n    async () => {\n      const { db, queues, advance, runId } = await fleet(makeDb, size);\n      const [first, second] = [queues[0]!, queues[1]!];\n      const buildId = `${runId}-lease`;\n      await first.enqueue({ buildId });\n      const stale = await claimOn(first, buildId);\n      expect(stale?.attempt).toBe(1);\n      expect(await claimOn(second, buildId)).toBeNull();\n      advance(LEASE_MS + 1);\n      // Every instance races for the expired lease; exactly one wins.\n      const winners = (await pollAll(queues)).filter((job) => job.buildId === buildId);\n      expect(winners).toHaveLength(1);\n      const fresh = winners[0]!;\n      expect(fresh.attempt).toBe(2);\n      const model = new CaptureJobModel(db);\n      const leaseBefore = (await model.get(attemptRowId(fresh.jobId, 2)))?.visibleAt;\n      expect(await first.extend(stale!)).toBe(\"lost\");\n      expect(await first.inspect(stale!)).toBe(\"lost\");\n      await first.nack(stale!, { requeue: true, error: \"stale\" });\n      const after = await model.get(fresh.jobId);\n      expect(after).toMatchObject({ status: \"running\", attempt: 2 });\n      expect((await model.get(attemptRowId(fresh.jobId, 2)))?.visibleAt).toBe(leaseBefore);\n      expect((await model.get(attemptRowId(fresh.jobId, 1)))?.status).toBe(\"expired\");\n      expect(await second.extend(fresh)).toBe(\"ok\");\n      await second.ack(fresh);\n      // A late finish by the stale holder costs a duplicate run, never a wrong result.\n      await first.ack(stale!);\n      expect((await second.status(buildId))?.status).toBe(\"completed\");\n    },\n    timeoutMs,\n  );\n}\n\nfunction retryCases(makeDb: SharedDatabaseFactory, size: number, timeoutMs?: number): void {\n  it(\n    \"fails a job on any instance once its retries are spent\",\n    async () => {\n      const { queues, advance, runId } = await fleet(makeDb, size);\n      const buildId = `${runId}-retry`;\n      await queues[0]!.enqueue({ buildId });\n      for (let attempt = 1; attempt <= RETRIES + 1; attempt += 1) {\n        const queue = queues[attempt % size]!;\n        // oxlint-disable-next-line eslint/no-await-in-loop -- attempts are sequential\n        const job = await claimOn(queue, buildId);\n        expect(job?.attempt).toBe(attempt);\n        // oxlint-disable-next-line eslint/no-await-in-loop -- see above\n        await queue.nack(job!, { requeue: true, delayMs: 1000, error: `boom ${String(attempt)}` });\n        advance(1001);\n      }\n      expect(await claimOn(queues[0]!, buildId)).toBeNull();\n      expect(await queues[2 % size]!.status(buildId)).toMatchObject({\n        status: \"failed\",\n        error: `boom ${String(RETRIES + 1)}`,\n      });\n    },\n    timeoutMs,\n  );\n\n  it(\n    \"fails a job whose every attempt lost its lease\",\n    async () => {\n      const { queues, advance, runId } = await fleet(makeDb, size);\n      const buildId = `${runId}-hung`;\n      await queues[0]!.enqueue({ buildId });\n      for (let attempt = 1; attempt <= RETRIES + 1; attempt += 1) {\n        // oxlint-disable-next-line eslint/no-await-in-loop -- attempts are sequential\n        const job = await claimOn(queues[attempt % size]!, buildId);\n        expect(job?.attempt).toBe(attempt);\n        advance(LEASE_MS + 1);\n      }\n      expect(await claimOn(queues[0]!, buildId)).toBeNull();\n      expect(await queues[1]!.status(buildId)).toMatchObject({\n        status: \"failed\",\n        error: LEASE_EXHAUSTED_ERROR,\n      });\n    },\n    timeoutMs,\n  );\n}\n\nfunction cancelAndKindCases(makeDb: SharedDatabaseFactory, size: number, timeoutMs?: number): void {\n  it(\n    \"lets one instance cancel a job another instance holds\",\n    async () => {\n      const { queues, runId } = await fleet(makeDb, size);\n      const [holder, other] = [queues[0]!, queues[1]!];\n      const buildId = `${runId}-cancel`;\n      await other.enqueue({ buildId });\n      const job = await claimOn(holder, buildId);\n      expect(await holder.inspect(job!)).toBe(\"ok\");\n      expect(await other.cancel(buildId)).toBe(true);\n      expect(await holder.inspect(job!)).toBe(\"cancelled\");\n      expect(await holder.extend(job!)).toBe(\"cancelled\");\n      await holder.nack(job!, { requeue: false, error: \"cancelled\" });\n      expect((await other.status(buildId))?.status).toBe(\"cancelled\");\n      expect(await claimOn(other, buildId)).toBeNull();\n    },\n    timeoutMs,\n  );\n\n  it(\n    \"keeps job kinds independent\",\n    async () => {\n      const shared = await makeDb();\n      const reuse = (): DatabaseAdapter => shared;\n      const capture = await fleet(reuse, 2, [\"capture\"]);\n      const publish = await fleet(reuse, 2, [\"publish\"]);\n      const buildId = `${capture.runId}-kinds`;\n      await capture.queues[0]!.enqueue({ buildId });\n      await publish.queues[0]!.enqueueJob({ kind: \"publish\", buildId, data: { zip: \"k\" } });\n      const published = await claimOn(publish.queues[1]!, buildId);\n      expect(published).toMatchObject({ kind: \"publish\", data: { zip: \"k\" } });\n      const captured = await claimOn(capture.queues[1]!, buildId);\n      expect(captured?.kind).toBe(\"capture\");\n      expect(await claimOn(publish.queues[0]!, buildId)).toBeNull();\n      await publish.queues[1]!.ack(published!);\n      await capture.queues[1]!.ack(captured!);\n      expect((await capture.queues[0]!.status(buildId))?.status).toBe(\"completed\");\n    },\n    timeoutMs,\n  );\n}\n"],"mappings":"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"}

package/dist/test-helpers/runner-contract.mjs

@@ -1,6 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
+import { isCaptureTarget } from "../adapters/capture-target.mjs";
 import { describe, expect, it } from "vitest";
 //#region src/test-helpers/runner-contract.ts
 /**
@@ -19,6 +20,16 @@ function runnerContractSuite(label, make) {
 			expect(runner.metadata.category).toBe("capture-runner");
 			expect(runner.metadata.kind.length).toBeGreaterThan(0);
 		});
+		it("lists its targets as unique, valid capture targets, default first", async () => {
+			const targets = (await make()).metadata.targets;
+			if (targets === void 0) return;
+			expect(targets.length).toBeGreaterThan(0);
+			for (const entry of targets) {
+				expect(isCaptureTarget(entry.target), entry.target).toBe(true);
+				expect(["loopback", "url"]).toContain(entry.reach);
+			}
+			expect(new Set(targets.map((entry) => entry.target)).size).toBe(targets.length);
+		});
 		it("exposes render and cancel", async () => {
 			const runner = await make();
 			expect(typeof runner.render).toBe("function");

package/dist/test-helpers/runner-contract.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"runner-contract.mjs","names":[],"sources":["../../src/test-helpers/runner-contract.ts"],"sourcesContent":["/**\n * Published runner contract suite for first- and third-party adapters.\n *\n * Structural conformance (identity, render/cancel presence). Behavioral\n * rendering stays per-package behind real or mocked browsers — the\n * orchestrator owns timeouts, byte guards, and failure caps, so runners\n * only promise to return PNG buffers and honor `cancel`.\n */\nimport { describe, expect, it } from \"vitest\";\nimport type { CaptureRunner } from \"../adapters/capture-runner.ts\";\n\n/** Build the adapter under test (sync or async factories both work). */\nexport type RunnerFactory = () => CaptureRunner | Promise<CaptureRunner>;\n\n/** Run the runner contract against a factory. */\nexport function runnerContractSuite(label: string, make: RunnerFactory): void {\n  describe(`runner contract: ${label}`, () => {\n    it(\"exposes capture-runner metadata\", async () => {\n      const runner = await make();\n      expect(runner.metadata.category).toBe(\"capture-runner\");\n      expect(runner.metadata.kind.length).toBeGreaterThan(0);\n    });\n\n    it(\"exposes render and cancel\", async () => {\n      const runner = await make();\n      expect(typeof runner.render).toBe(\"function\");\n      expect(typeof runner.cancel).toBe(\"function\");\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;AAeA,SAAgB,oBAAoB,OAAe,MAA2B;CAC5E,SAAS,oBAAoB,eAAe;EAC1C,GAAG,mCAAmC,YAAY;GAChD,MAAM,SAAS,MAAM,KAAK;GAC1B,OAAO,OAAO,SAAS,QAAQ,CAAC,CAAC,KAAK,gBAAgB;GACtD,OAAO,OAAO,SAAS,KAAK,MAAM,CAAC,CAAC,gBAAgB,CAAC;EACvD,CAAC;EAED,GAAG,6BAA6B,YAAY;GAC1C,MAAM,SAAS,MAAM,KAAK;GAC1B,OAAO,OAAO,OAAO,MAAM,CAAC,CAAC,KAAK,UAAU;GAC5C,OAAO,OAAO,OAAO,MAAM,CAAC,CAAC,KAAK,UAAU;EAC9C,CAAC;CACH,CAAC;AACH"}
+{"version":3,"file":"runner-contract.mjs","names":[],"sources":["../../src/test-helpers/runner-contract.ts"],"sourcesContent":["/**\n * Published runner contract suite for first- and third-party adapters.\n *\n * Structural conformance (identity, render/cancel presence). Behavioral\n * rendering stays per-package behind real or mocked browsers — the\n * orchestrator owns timeouts, byte guards, and failure caps, so runners\n * only promise to return PNG buffers and honor `cancel`.\n */\nimport { describe, expect, it } from \"vitest\";\nimport type { CaptureRunner } from \"../adapters/capture-runner.ts\";\nimport { isCaptureTarget } from \"../adapters/capture-target.ts\";\n\n/** Build the adapter under test (sync or async factories both work). */\nexport type RunnerFactory = () => CaptureRunner | Promise<CaptureRunner>;\n\n/** Run the runner contract against a factory. */\nexport function runnerContractSuite(label: string, make: RunnerFactory): void {\n  describe(`runner contract: ${label}`, () => {\n    it(\"exposes capture-runner metadata\", async () => {\n      const runner = await make();\n      expect(runner.metadata.category).toBe(\"capture-runner\");\n      expect(runner.metadata.kind.length).toBeGreaterThan(0);\n    });\n\n    it(\"lists its targets as unique, valid capture targets, default first\", async () => {\n      const targets = (await make()).metadata.targets;\n      if (targets === undefined) {\n        return;\n      }\n      expect(targets.length).toBeGreaterThan(0);\n      for (const entry of targets) {\n        expect(isCaptureTarget(entry.target), entry.target).toBe(true);\n        expect([\"loopback\", \"url\"]).toContain(entry.reach);\n      }\n      expect(new Set(targets.map((entry) => entry.target)).size).toBe(targets.length);\n    });\n\n    it(\"exposes render and cancel\", async () => {\n      const runner = await make();\n      expect(typeof runner.render).toBe(\"function\");\n      expect(typeof runner.cancel).toBe(\"function\");\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;AAgBA,SAAgB,oBAAoB,OAAe,MAA2B;CAC5E,SAAS,oBAAoB,eAAe;EAC1C,GAAG,mCAAmC,YAAY;GAChD,MAAM,SAAS,MAAM,KAAK;GAC1B,OAAO,OAAO,SAAS,QAAQ,CAAC,CAAC,KAAK,gBAAgB;GACtD,OAAO,OAAO,SAAS,KAAK,MAAM,CAAC,CAAC,gBAAgB,CAAC;EACvD,CAAC;EAED,GAAG,qEAAqE,YAAY;GAClF,MAAM,WAAW,MAAM,KAAK,EAAA,CAAG,SAAS;GACxC,IAAI,YAAY,KAAA,GACd;GAEF,OAAO,QAAQ,MAAM,CAAC,CAAC,gBAAgB,CAAC;GACxC,KAAK,MAAM,SAAS,SAAS;IAC3B,OAAO,gBAAgB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,CAAC,KAAK,IAAI;IAC7D,OAAO,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,UAAU,MAAM,KAAK;GACnD;GACA,OAAO,IAAI,IAAI,QAAQ,KAAK,UAAU,MAAM,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,QAAQ,MAAM;EAChF,CAAC;EAED,GAAG,6BAA6B,YAAY;GAC1C,MAAM,SAAS,MAAM,KAAK;GAC1B,OAAO,OAAO,OAAO,MAAM,CAAC,CAAC,KAAK,UAAU;GAC5C,OAAO,OAAO,OAAO,MAAM,CAAC,CAAC,KAAK,UAAU;EAC9C,CAAC;CACH,CAAC;AACH"}

package/dist/test-helpers/sql-chunks.mjs

@@ -24,7 +24,10 @@ function matchChunk(chunks, row, table) {
 	const text = chunks.map((c) => textOf(c) ?? "").join("");
 	if (/is not null/iu.test(text)) return isNullMatches(chunks, row, table, true);
 	if (/is null/iu.test(text)) return isNullMatches(chunks, row, table, false);
+	if (text.includes(" like ")) return likeMatches(chunks, row, table);
 	if (text.includes(" in ")) return inArrayMatches(chunks, row, table);
+	if (text.includes(" >= ")) return !ltMatches(chunks, row, table);
+	if (text.includes(" <= ")) return lteMatches(chunks, row, table);
 	if (text.includes(" < ")) return ltMatches(chunks, row, table);
 	return eqMatches(chunks, row, table);
 }
@@ -45,6 +48,21 @@ function eqMatches(chunks, row, table) {
 	if (columnName === void 0) return false;
 	return row[columnKey(table, columnName)] === argument;
 }
+/** Match `column like 'pattern'`: `%` is any run of characters, `_` any one; everything else literal. */
+function likeMatches(chunks, row, table) {
+	let columnName;
+	let pattern;
+	for (const chunk of chunks) if (typeof chunk === "string") pattern = chunk;
+	else if (chunk !== null && typeof chunk === "object") {
+		const node = chunk;
+		if (typeof node.name === "string" && node.table !== void 0) columnName = node.name;
+		else if ("brand" in node) pattern = node.value;
+	}
+	const cell = columnName === void 0 ? void 0 : row[columnKey(table, columnName)];
+	if (typeof cell !== "string" || typeof pattern !== "string") return false;
+	const source = pattern.replaceAll(/[.*+?^${}()|[\]\\]/gu, String.raw`\$&`);
+	return new RegExp(`^${source.replaceAll("%", ".*").replaceAll("_", ".")}$`, "su").test(cell);
+}
 function inArrayMatches(chunks, row, table) {
 	let columnName;
 	const values = [];
@@ -78,6 +96,11 @@ function inArrayMatches(chunks, row, table) {
 	const key = columnKey(table, columnName);
 	return values.includes(row[key]);
 }
+/** `column <= value`: the cell is present and not greater than the argument. */
+function lteMatches(chunks, row, table) {
+	if (ltMatches(chunks, row, table)) return true;
+	return eqMatches(chunks, row, table);
+}
 function ltMatches(chunks, row, table) {
 	let columnName;
 	let argument;

package/dist/test-helpers/sql-chunks.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"sql-chunks.mjs","names":[],"sources":["../../src/test-helpers/sql-chunks.ts"],"sourcesContent":["import { getTableColumns, type SQL, type Table } from \"drizzle-orm\";\n\n/* eslint-disable require-await, no-unnecessary-type-assertion, no-unnecessary-type-parameters, non-nullable-type-assertion-style */\n\n/** A drizzle SQL chunk inspected for matching and ordering. */\nexport interface SqlChunk {\n  value?: unknown;\n  name?: string;\n  table?: unknown;\n  brand?: unknown;\n  queryChunks?: SqlChunk[];\n}\n\n/** Flatten the string parts of a drizzle SQL chunk into a single string. */\nfunction textOf(chunk: SqlChunk | undefined): string | undefined {\n  if (\n    chunk === undefined ||\n    !Array.isArray(chunk.value) ||\n    !chunk.value.every((part) => typeof part === \"string\")\n  ) {\n    return undefined;\n  }\n  return chunk.value.join(\"\");\n}\n\n/** Test whether an in-memory row satisfies a drizzle where-clause. */\nexport function whereMatches(where: SQL, row: Record<string, unknown>, table: Table): boolean {\n  let current = where.queryChunks as unknown as SqlChunk[];\n  let wrapped = current[1]?.queryChunks;\n  while (wrapped !== undefined && textOf(current[0]) === \"(\" && textOf(current.at(-1)) === \")\") {\n    current = wrapped;\n    wrapped = current[1]?.queryChunks;\n  }\n  // Drizzle's `and(singleCondition)` emits the condition directly, without\n  // the enclosing parens produced for two or more clauses, so unwrap it.\n  if (current.length === 1 && current[0]?.queryChunks !== undefined) {\n    current = current[0].queryChunks as unknown as SqlChunk[];\n  }\n  if (current.some((chunk) => textOf(chunk)?.trim() === \"and\")) {\n    return current\n      .filter((chunk) => textOf(chunk) === undefined)\n      .every((chunk) => matchChunk(chunk.queryChunks ?? [], row, table));\n  }\n  return matchChunk(current, row, table);\n}\n\nfunction matchChunk(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  const text = chunks.map((c) => textOf(c) ?? \"\").join(\"\");\n  if (/is not null/iu.test(text)) {\n    return isNullMatches(chunks, row, table, true);\n  }\n  if (/is null/iu.test(text)) {\n    return isNullMatches(chunks, row, table, false);\n  }\n  if (text.includes(\" in \")) {\n    return inArrayMatches(chunks, row, table);\n  }\n  if (text.includes(\" < \")) {\n    return ltMatches(chunks, row, table);\n  }\n  return eqMatches(chunks, row, table);\n}\n\n/** Match `is null` / `is not null` predicates (no value argument). */\nfunction isNullMatches(\n  chunks: SqlChunk[],\n  row: Record<string, unknown>,\n  table: Table,\n  negated: boolean,\n): boolean {\n  let columnName: string | undefined;\n  for (const chunk of chunks) {\n    if (typeof chunk.name === \"string\" && chunk.table !== undefined) {\n      columnName = chunk.name;\n    }\n  }\n  if (columnName === undefined) {\n    return false;\n  }\n  const cell = row[columnKey(table, columnName)];\n  const missing = cell === null || cell === undefined;\n  return negated ? !missing : missing;\n}\n\nfunction eqMatches(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  let columnName: string | undefined;\n  let argument: unknown;\n  for (const chunk of chunks) {\n    if (typeof chunk.name === \"string\" && chunk.table !== undefined) {\n      columnName = chunk.name;\n    } else if (\"brand\" in chunk) {\n      argument = chunk.value;\n    }\n  }\n  if (columnName === undefined) {\n    return false;\n  }\n  return row[columnKey(table, columnName)] === argument;\n}\n\n/* eslint-disable complexity, max-depth -- handles drizzle's varied chunk shapes */\nfunction inArrayMatches(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  let columnName: string | undefined;\n  const values: unknown[] = [];\n  const collect = (nodes: unknown[]): void => {\n    for (const raw of nodes as SqlChunk[]) {\n      const chunk = raw as SqlChunk & Record<string, unknown>;\n      // Handle array-like chunk (inArray values stored as array of chunks)\n      if (\n        Array.isArray(chunk) ||\n        (chunk && typeof chunk === \"object\" && Object.keys(chunk).every((k) => /^\\d+$/u.test(k)))\n      ) {\n        collect(Object.values(chunk as unknown as Record<string, unknown>) as unknown[]);\n        continue;\n      }\n      if (typeof chunk.name === \"string\" && chunk.table !== undefined) {\n        columnName = chunk.name as string;\n      }\n      if (\"brand\" in chunk && (chunk as Record<string, unknown>)[\"value\"] !== undefined) {\n        const val = (chunk as Record<string, unknown>)[\"value\"];\n        if (Array.isArray(val)) {\n          values.push(...(val as unknown[]));\n        } else {\n          values.push(val);\n        }\n      }\n      if (chunk.queryChunks) {\n        collect(chunk.queryChunks as unknown[]);\n      }\n      const val = (chunk as Record<string, unknown>)[\"value\"];\n      if (Array.isArray(val)) {\n        for (const item of val as unknown[]) {\n          if (\n            item &&\n            typeof item === \"object\" &&\n            \"queryChunks\" in (item as Record<string, unknown>)\n          ) {\n            collect(((item as Record<string, unknown>)[\"queryChunks\"] as unknown[]) ?? []);\n          }\n          if (item && typeof item === \"object\" && \"value\" in (item as Record<string, unknown>)) {\n            const iv = (item as Record<string, unknown>)[\"value\"];\n            if (iv !== undefined) {\n              values.push(iv);\n            }\n          }\n          if (typeof item === \"string\") {\n            values.push(item);\n          }\n        }\n      }\n    }\n  };\n  collect(chunks as unknown[]);\n  if (columnName === undefined) {\n    return false;\n  }\n  const key = columnKey(table, columnName);\n  return values.includes(row[key]);\n}\n/* eslint-enable complexity, max-depth */\n\nfunction ltMatches(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  let columnName: string | undefined;\n  let argument: unknown;\n  for (const chunk of chunks) {\n    if (typeof chunk.name === \"string\" && chunk.table !== undefined) {\n      columnName = chunk.name;\n    } else if (\"brand\" in chunk) {\n      argument = chunk.value;\n    }\n  }\n  if (columnName === undefined) {\n    return false;\n  }\n  const key = columnKey(table, columnName);\n  const cell = row[key];\n  if (typeof cell === \"string\" && typeof argument === \"string\") {\n    return cell < argument;\n  }\n  if (typeof cell === \"number\" && typeof argument === \"number\") {\n    return cell < argument;\n  }\n  return String(cell) < String(argument);\n}\n\nfunction compareCells(left: unknown, right: unknown): number {\n  if (typeof left === \"string\" && typeof right === \"string\") {\n    if (left === right) {\n      return 0;\n    }\n    return left < right ? -1 : 1;\n  }\n  if (typeof left === \"number\" && typeof right === \"number\") {\n    return left - right;\n  }\n  const leftText = String(left);\n  const rightText = String(right);\n  if (leftText === rightText) {\n    return 0;\n  }\n  return leftText < rightText ? -1 : 1;\n}\n\n/** Collect every raw string part of a drizzle SQL chunk tree. */\nfunction sqlText(nodes: SqlChunk[]): string {\n  return nodes\n    .map((node) => {\n      const own = textOf(node) ?? \"\";\n      const nested = node.queryChunks ? sqlText(node.queryChunks as unknown as SqlChunk[]) : \"\";\n      return own + nested;\n    })\n    .join(\"\");\n}\n\n/** Find the ordered column reference in a drizzle order-by expression. */\nfunction findOrderColumn(nodes: SqlChunk[]): string | undefined {\n  for (const node of nodes) {\n    if (typeof node.name === \"string\" && node.table !== undefined) {\n      return node.name;\n    }\n    if (node.queryChunks) {\n      const nested = findOrderColumn(node.queryChunks as unknown as SqlChunk[]);\n      if (nested !== undefined) {\n        return nested;\n      }\n    }\n  }\n  return undefined;\n}\n\n/** Sort rows per a drizzle order-by expression (single-column asc/desc). */\nexport function orderRows(rows: unknown[], orderBy: SQL, table: Table): unknown[] {\n  const chunks = orderBy.queryChunks as unknown as SqlChunk[];\n  const columnName = findOrderColumn(chunks);\n  if (columnName === undefined) {\n    return rows;\n  }\n  const key = columnKey(table, columnName);\n  const descending = /desc/iu.test(sqlText(chunks));\n  return rows.toSorted((left, right) => {\n    const order = compareCells(\n      (left as Record<string, unknown>)[key],\n      (right as Record<string, unknown>)[key],\n    );\n    return descending ? -order : order;\n  });\n}\n\nfunction columnKey(table: Table, dbName: string): string {\n  for (const [property, column] of Object.entries(getTableColumns(table))) {\n    if (column.name === dbName) {\n      return property;\n    }\n  }\n  return dbName;\n}\n/* eslint-enable require-await, no-unnecessary-type-assertion, no-unnecessary-type-parameters, non-nullable-type-assertion-style */\n"],"mappings":"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"}
+{"version":3,"file":"sql-chunks.mjs","names":[],"sources":["../../src/test-helpers/sql-chunks.ts"],"sourcesContent":["import { getTableColumns, type SQL, type Table } from \"drizzle-orm\";\n\n/* eslint-disable require-await, no-unnecessary-type-assertion, no-unnecessary-type-parameters, non-nullable-type-assertion-style */\n\n/** A drizzle SQL chunk inspected for matching and ordering. */\nexport interface SqlChunk {\n  value?: unknown;\n  name?: string;\n  table?: unknown;\n  brand?: unknown;\n  queryChunks?: SqlChunk[];\n}\n\n/** Flatten the string parts of a drizzle SQL chunk into a single string. */\nfunction textOf(chunk: SqlChunk | undefined): string | undefined {\n  if (\n    chunk === undefined ||\n    !Array.isArray(chunk.value) ||\n    !chunk.value.every((part) => typeof part === \"string\")\n  ) {\n    return undefined;\n  }\n  return chunk.value.join(\"\");\n}\n\n/** Test whether an in-memory row satisfies a drizzle where-clause. */\nexport function whereMatches(where: SQL, row: Record<string, unknown>, table: Table): boolean {\n  let current = where.queryChunks as unknown as SqlChunk[];\n  let wrapped = current[1]?.queryChunks;\n  while (wrapped !== undefined && textOf(current[0]) === \"(\" && textOf(current.at(-1)) === \")\") {\n    current = wrapped;\n    wrapped = current[1]?.queryChunks;\n  }\n  // Drizzle's `and(singleCondition)` emits the condition directly, without\n  // the enclosing parens produced for two or more clauses, so unwrap it.\n  if (current.length === 1 && current[0]?.queryChunks !== undefined) {\n    current = current[0].queryChunks as unknown as SqlChunk[];\n  }\n  if (current.some((chunk) => textOf(chunk)?.trim() === \"and\")) {\n    return current\n      .filter((chunk) => textOf(chunk) === undefined)\n      .every((chunk) => matchChunk(chunk.queryChunks ?? [], row, table));\n  }\n  return matchChunk(current, row, table);\n}\n\nfunction matchChunk(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  const text = chunks.map((c) => textOf(c) ?? \"\").join(\"\");\n  if (/is not null/iu.test(text)) {\n    return isNullMatches(chunks, row, table, true);\n  }\n  if (/is null/iu.test(text)) {\n    return isNullMatches(chunks, row, table, false);\n  }\n  if (text.includes(\" like \")) {\n    return likeMatches(chunks, row, table);\n  }\n  if (text.includes(\" in \")) {\n    return inArrayMatches(chunks, row, table);\n  }\n  if (text.includes(\" >= \")) {\n    return !ltMatches(chunks, row, table);\n  }\n  if (text.includes(\" <= \")) {\n    return lteMatches(chunks, row, table);\n  }\n  if (text.includes(\" < \")) {\n    return ltMatches(chunks, row, table);\n  }\n  return eqMatches(chunks, row, table);\n}\n\n/** Match `is null` / `is not null` predicates (no value argument). */\nfunction isNullMatches(\n  chunks: SqlChunk[],\n  row: Record<string, unknown>,\n  table: Table,\n  negated: boolean,\n): boolean {\n  let columnName: string | undefined;\n  for (const chunk of chunks) {\n    if (typeof chunk.name === \"string\" && chunk.table !== undefined) {\n      columnName = chunk.name;\n    }\n  }\n  if (columnName === undefined) {\n    return false;\n  }\n  const cell = row[columnKey(table, columnName)];\n  const missing = cell === null || cell === undefined;\n  return negated ? !missing : missing;\n}\n\nfunction eqMatches(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  let columnName: string | undefined;\n  let argument: unknown;\n  for (const chunk of chunks) {\n    if (typeof chunk.name === \"string\" && chunk.table !== undefined) {\n      columnName = chunk.name;\n    } else if (\"brand\" in chunk) {\n      argument = chunk.value;\n    }\n  }\n  if (columnName === undefined) {\n    return false;\n  }\n  return row[columnKey(table, columnName)] === argument;\n}\n\n/** Match `column like 'pattern'`: `%` is any run of characters, `_` any one; everything else literal. */\nfunction likeMatches(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  let columnName: string | undefined;\n  let pattern: unknown;\n  for (const chunk of chunks as unknown[]) {\n    if (typeof chunk === \"string\") {\n      pattern = chunk;\n    } else if (chunk !== null && typeof chunk === \"object\") {\n      const node = chunk as SqlChunk;\n      if (typeof node.name === \"string\" && node.table !== undefined) {\n        columnName = node.name;\n      } else if (\"brand\" in node) {\n        pattern = node.value;\n      }\n    }\n  }\n  const cell = columnName === undefined ? undefined : row[columnKey(table, columnName)];\n  if (typeof cell !== \"string\" || typeof pattern !== \"string\") {\n    return false;\n  }\n  const source = pattern.replaceAll(/[.*+?^${}()|[\\]\\\\]/gu, String.raw`\\$&`);\n  return new RegExp(`^${source.replaceAll(\"%\", \".*\").replaceAll(\"_\", \".\")}$`, \"su\").test(cell);\n}\n\n/* eslint-disable complexity, max-depth -- handles drizzle's varied chunk shapes */\nfunction inArrayMatches(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  let columnName: string | undefined;\n  const values: unknown[] = [];\n  const collect = (nodes: unknown[]): void => {\n    for (const raw of nodes as SqlChunk[]) {\n      const chunk = raw as SqlChunk & Record<string, unknown>;\n      // Handle array-like chunk (inArray values stored as array of chunks)\n      if (\n        Array.isArray(chunk) ||\n        (chunk && typeof chunk === \"object\" && Object.keys(chunk).every((k) => /^\\d+$/u.test(k)))\n      ) {\n        collect(Object.values(chunk as unknown as Record<string, unknown>) as unknown[]);\n        continue;\n      }\n      if (typeof chunk.name === \"string\" && chunk.table !== undefined) {\n        columnName = chunk.name as string;\n      }\n      if (\"brand\" in chunk && (chunk as Record<string, unknown>)[\"value\"] !== undefined) {\n        const val = (chunk as Record<string, unknown>)[\"value\"];\n        if (Array.isArray(val)) {\n          values.push(...(val as unknown[]));\n        } else {\n          values.push(val);\n        }\n      }\n      if (chunk.queryChunks) {\n        collect(chunk.queryChunks as unknown[]);\n      }\n      const val = (chunk as Record<string, unknown>)[\"value\"];\n      if (Array.isArray(val)) {\n        for (const item of val as unknown[]) {\n          if (\n            item &&\n            typeof item === \"object\" &&\n            \"queryChunks\" in (item as Record<string, unknown>)\n          ) {\n            collect(((item as Record<string, unknown>)[\"queryChunks\"] as unknown[]) ?? []);\n          }\n          if (item && typeof item === \"object\" && \"value\" in (item as Record<string, unknown>)) {\n            const iv = (item as Record<string, unknown>)[\"value\"];\n            if (iv !== undefined) {\n              values.push(iv);\n            }\n          }\n          if (typeof item === \"string\") {\n            values.push(item);\n          }\n        }\n      }\n    }\n  };\n  collect(chunks as unknown[]);\n  if (columnName === undefined) {\n    return false;\n  }\n  const key = columnKey(table, columnName);\n  return values.includes(row[key]);\n}\n/* eslint-enable complexity, max-depth */\n\n/** `column <= value`: the cell is present and not greater than the argument. */\nfunction lteMatches(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  if (ltMatches(chunks, row, table)) {\n    return true;\n  }\n  return eqMatches(chunks, row, table);\n}\n\nfunction ltMatches(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  let columnName: string | undefined;\n  let argument: unknown;\n  for (const chunk of chunks) {\n    if (typeof chunk.name === \"string\" && chunk.table !== undefined) {\n      columnName = chunk.name;\n    } else if (\"brand\" in chunk) {\n      argument = chunk.value;\n    }\n  }\n  if (columnName === undefined) {\n    return false;\n  }\n  const key = columnKey(table, columnName);\n  const cell = row[key];\n  if (typeof cell === \"string\" && typeof argument === \"string\") {\n    return cell < argument;\n  }\n  if (typeof cell === \"number\" && typeof argument === \"number\") {\n    return cell < argument;\n  }\n  return String(cell) < String(argument);\n}\n\nfunction compareCells(left: unknown, right: unknown): number {\n  if (typeof left === \"string\" && typeof right === \"string\") {\n    if (left === right) {\n      return 0;\n    }\n    return left < right ? -1 : 1;\n  }\n  if (typeof left === \"number\" && typeof right === \"number\") {\n    return left - right;\n  }\n  const leftText = String(left);\n  const rightText = String(right);\n  if (leftText === rightText) {\n    return 0;\n  }\n  return leftText < rightText ? -1 : 1;\n}\n\n/** Collect every raw string part of a drizzle SQL chunk tree. */\nfunction sqlText(nodes: SqlChunk[]): string {\n  return nodes\n    .map((node) => {\n      const own = textOf(node) ?? \"\";\n      const nested = node.queryChunks ? sqlText(node.queryChunks as unknown as SqlChunk[]) : \"\";\n      return own + nested;\n    })\n    .join(\"\");\n}\n\n/** Find the ordered column reference in a drizzle order-by expression. */\nfunction findOrderColumn(nodes: SqlChunk[]): string | undefined {\n  for (const node of nodes) {\n    if (typeof node.name === \"string\" && node.table !== undefined) {\n      return node.name;\n    }\n    if (node.queryChunks) {\n      const nested = findOrderColumn(node.queryChunks as unknown as SqlChunk[]);\n      if (nested !== undefined) {\n        return nested;\n      }\n    }\n  }\n  return undefined;\n}\n\n/** Sort rows per a drizzle order-by expression (single-column asc/desc). */\nexport function orderRows(rows: unknown[], orderBy: SQL, table: Table): unknown[] {\n  const chunks = orderBy.queryChunks as unknown as SqlChunk[];\n  const columnName = findOrderColumn(chunks);\n  if (columnName === undefined) {\n    return rows;\n  }\n  const key = columnKey(table, columnName);\n  const descending = /desc/iu.test(sqlText(chunks));\n  return rows.toSorted((left, right) => {\n    const order = compareCells(\n      (left as Record<string, unknown>)[key],\n      (right as Record<string, unknown>)[key],\n    );\n    return descending ? -order : order;\n  });\n}\n\nfunction columnKey(table: Table, dbName: string): string {\n  for (const [property, column] of Object.entries(getTableColumns(table))) {\n    if (column.name === dbName) {\n      return property;\n    }\n  }\n  return dbName;\n}\n/* eslint-enable require-await, no-unnecessary-type-assertion, no-unnecessary-type-parameters, non-nullable-type-assertion-style */\n"],"mappings":"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"}

package/dist/test-helpers/storage-contract.mjs

@@ -1,8 +1,8 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { describe, expect, it } from "vitest";
 import { Readable } from "node:stream";
+import { describe, expect, it } from "vitest";
 //#region src/test-helpers/storage-contract.ts
 /**
 * Published storage contract suite for first- and third-party adapters.

package/dist/test-helpers.d.mts

@@ -1,13 +1,18 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
+import { Deferred, Latch, ReleaseQueue, createLatch, createReleaseQueue, deferred } from "./test-helpers/deferred.mjs";
+import { DesignContractSamples, designContractSuite } from "./test-helpers/design-contract.mjs";
 import { createTestBuild, createTestProject } from "./test-helpers/create-project.mjs";
 import { REQUIRED_TABLES, databaseContractSuite } from "./test-helpers/database-contract.mjs";
-import { gitContractSuite } from "./test-helpers/git-contract.mjs";
+import { FAKE_PNG, FakeDesign, fakeUrl, makeFakeDesign } from "./test-helpers/fake-design.mjs";
 import { makeDatabase } from "./test-helpers/fake-database.mjs";
 import { FakeStorage, makeStorage } from "./test-helpers/fake-storage.mjs";
 import { stubTables } from "./test-helpers/fake-adapters.mjs";
-import { notifierContractSuite } from "./test-helpers/notifier-contract.mjs";
-import { queueContractSuite } from "./test-helpers/queue-contract.mjs";
+import { notifierContractSuite, stateNotifierContractSuite } from "./test-helpers/notifier-contract.mjs";
+import { PollableContractOptions, QueueContractOptions, QueueFactory, queueContractSuite } from "./test-helpers/queue-contract.mjs";
+import { MultiInstanceOptions, SharedDatabaseFactory, databaseQueueMultiInstanceSuite } from "./test-helpers/queue-multi-instance.mjs";
+import { ManualClock, createManualClock } from "./test-helpers/manual-clock.mjs";
 import { runnerContractSuite } from "./test-helpers/runner-contract.mjs";
 import { storageContractSuite } from "./test-helpers/storage-contract.mjs";
-export { type FakeStorage, REQUIRED_TABLES, createTestBuild, createTestProject, databaseContractSuite, gitContractSuite, makeDatabase, makeStorage, notifierContractSuite, queueContractSuite, runnerContractSuite, storageContractSuite, stubTables };
+import { FakeStateNotifier, makeFakeStateNotifier } from "./test-helpers/fake-notifier.mjs";
+export { type Deferred, type DesignContractSamples, FAKE_PNG, type FakeDesign, type FakeStateNotifier, type FakeStorage, type Latch, type ManualClock, type MultiInstanceOptions, type PollableContractOptions, type QueueContractOptions, type QueueFactory, REQUIRED_TABLES, type ReleaseQueue, type SharedDatabaseFactory, createLatch, createManualClock, createReleaseQueue, createTestBuild, createTestProject, databaseContractSuite, databaseQueueMultiInstanceSuite, deferred, designContractSuite, fakeUrl, makeDatabase, makeFakeDesign, makeFakeStateNotifier, makeStorage, notifierContractSuite, queueContractSuite, runnerContractSuite, stateNotifierContractSuite, storageContractSuite, stubTables };

package/dist/test-helpers.mjs

@@ -1,14 +1,19 @@
 import "node:path";
 import "node:url";
 import.meta.url;
+import { createLatch, createReleaseQueue, deferred } from "./test-helpers/deferred.mjs";
+import { designContractSuite } from "./test-helpers/design-contract.mjs";
 import { createTestBuild, createTestProject } from "./test-helpers/create-project.mjs";
 import { REQUIRED_TABLES, databaseContractSuite } from "./test-helpers/database-contract.mjs";
-import { gitContractSuite } from "./test-helpers/git-contract.mjs";
+import { FAKE_PNG, fakeUrl, makeFakeDesign } from "./test-helpers/fake-design.mjs";
 import { makeDatabase } from "./test-helpers/fake-database.mjs";
 import { makeStorage } from "./test-helpers/fake-storage.mjs";
 import { stubTables } from "./test-helpers/fake-adapters.mjs";
-import { notifierContractSuite } from "./test-helpers/notifier-contract.mjs";
+import { notifierContractSuite, stateNotifierContractSuite } from "./test-helpers/notifier-contract.mjs";
 import { queueContractSuite } from "./test-helpers/queue-contract.mjs";
+import { databaseQueueMultiInstanceSuite } from "./test-helpers/queue-multi-instance.mjs";
+import { createManualClock } from "./test-helpers/manual-clock.mjs";
 import { runnerContractSuite } from "./test-helpers/runner-contract.mjs";
 import { storageContractSuite } from "./test-helpers/storage-contract.mjs";
-export { REQUIRED_TABLES, createTestBuild, createTestProject, databaseContractSuite, gitContractSuite, makeDatabase, makeStorage, notifierContractSuite, queueContractSuite, runnerContractSuite, storageContractSuite, stubTables };
+import { makeFakeStateNotifier } from "./test-helpers/fake-notifier.mjs";
+export { FAKE_PNG, REQUIRED_TABLES, createLatch, createManualClock, createReleaseQueue, createTestBuild, createTestProject, databaseContractSuite, databaseQueueMultiInstanceSuite, deferred, designContractSuite, fakeUrl, makeDatabase, makeFakeDesign, makeFakeStateNotifier, makeStorage, notifierContractSuite, queueContractSuite, runnerContractSuite, stateNotifierContractSuite, storageContractSuite, stubTables };

package/dist/types.d.mts

@@ -2,7 +2,7 @@ import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 //#region src/types.d.ts
 /** All lifecycle statuses a build can carry. */
-declare const BUILD_STATUSES: readonly ["pending", "capturing", "comparing", "reviewing", "approved", "rejected", "failed"];
+declare const BUILD_STATUSES: readonly ["pending", "capturing", "comparing", "reviewing", "approved", "rejected", "failed", "cancelled"];
 /** Lifecycle status of a build. */
 type BuildStatus = (typeof BUILD_STATUSES)[number];
 /** All review statuses a snapshot can carry. */
@@ -11,10 +11,15 @@ declare const SNAPSHOT_STATUSES: readonly ["pending", "new", "unchanged", "chang
 type SnapshotStatus = (typeof SNAPSHOT_STATUSES)[number];
 /**
  * Build statuses considered terminal for retention purging.
- * Only builds that have finished review (`approved`, `rejected`, `failed`)
+ * Only builds that have finished review (`approved`, `rejected`, `failed`, `cancelled`)
  * are eligible for TTL-based cleanup; `pending`/`reviewing` builds are kept.
  */
 declare const TERMINAL_BUILD_STATUSES: readonly BuildStatus[];
+/**
+ * Statuses of a build whose capture or compare work may still run: a user may cancel it (the build
+ * then ends `cancelled`, a terminal status no capture write moves it out of again).
+ */
+declare const CANCELLABLE_BUILD_STATUSES: readonly BuildStatus[];
 /** All site-wide user roles. */
 declare const SITE_ROLES: readonly ["admin", "member", "viewer"];
 /** Site-wide role of a user. */
@@ -45,10 +50,16 @@ interface AuthUser {
    */
   providerId?: string;
 }
+/** Build-level review verdicts (ADR 0013, decision 3). */
+declare const REVIEW_VERDICTS: readonly ["approved", "rejected"];
+/** A reviewer's verdict on a build. */
+type ReviewVerdict = (typeof REVIEW_VERDICTS)[number];
 /** All per-project membership roles. */
 declare const PROJECT_ROLES: readonly ["admin", "approver", "developer", "viewer"];
 /** Per-project role of a member. */
 type ProjectRole = (typeof PROJECT_ROLES)[number];
+/** Narrow an untrusted string to a {@link ProjectRole}. */
+declare function isProjectRole(value: unknown): value is ProjectRole;
 /** Label type keys seeded for every new project. */
 declare const SEEDED_LABEL_KEYS: readonly ["branch", "persistent", "pr", "mr", "jira", "linear", "figma", "custom"];
 /** Label type keys reserved for internal bookkeeping (cannot be created by users). */
@@ -59,5 +70,5 @@ declare const RESERVED_LABEL_KEYS: readonly ["build"];
  */
 declare const PERSISTENT_LABEL_KEY = "persistent";
 //#endregion
-export { AuthUser, BUILD_STATUSES, BuildStatus, PERSISTENT_LABEL_KEY, PROJECT_ROLES, ProjectRole, RESERVED_LABEL_KEYS, SEEDED_LABEL_KEYS, SESSION_COOKIE, SITE_ROLES, SNAPSHOT_STATUSES, SiteRole, SnapshotStatus, TERMINAL_BUILD_STATUSES };
+export { AuthUser, BUILD_STATUSES, BuildStatus, CANCELLABLE_BUILD_STATUSES, PERSISTENT_LABEL_KEY, PROJECT_ROLES, ProjectRole, RESERVED_LABEL_KEYS, REVIEW_VERDICTS, ReviewVerdict, SEEDED_LABEL_KEYS, SESSION_COOKIE, SITE_ROLES, SNAPSHOT_STATUSES, SiteRole, SnapshotStatus, TERMINAL_BUILD_STATUSES, isProjectRole };
 //# sourceMappingURL=types.d.mts.map

package/dist/types.mjs

@@ -10,7 +10,8 @@ const BUILD_STATUSES = [
 	"reviewing",
 	"approved",
 	"rejected",
-	"failed"
+	"failed",
+	"cancelled"
 ];
 /** All review statuses a snapshot can carry. */
 const SNAPSHOT_STATUSES = [
@@ -23,13 +24,23 @@ const SNAPSHOT_STATUSES = [
 ];
 /**
 * Build statuses considered terminal for retention purging.
-* Only builds that have finished review (`approved`, `rejected`, `failed`)
+* Only builds that have finished review (`approved`, `rejected`, `failed`, `cancelled`)
 * are eligible for TTL-based cleanup; `pending`/`reviewing` builds are kept.
 */
 const TERMINAL_BUILD_STATUSES = [
 	"approved",
 	"rejected",
-	"failed"
+	"failed",
+	"cancelled"
+];
+/**
+* Statuses of a build whose capture or compare work may still run: a user may cancel it (the build
+* then ends `cancelled`, a terminal status no capture write moves it out of again).
+*/
+const CANCELLABLE_BUILD_STATUSES = [
+	"pending",
+	"capturing",
+	"comparing"
 ];
 /** All site-wide user roles. */
 const SITE_ROLES = [
@@ -39,6 +50,8 @@ const SITE_ROLES = [
 ];
 /** Shared session cookie name used by auth (ADR 0008). */
 const SESSION_COOKIE = "storyshelf_session";
+/** Build-level review verdicts (ADR 0013, decision 3). */
+const REVIEW_VERDICTS = ["approved", "rejected"];
 /** All per-project membership roles. */
 const PROJECT_ROLES = [
 	"admin",
@@ -46,6 +59,10 @@ const PROJECT_ROLES = [
 	"developer",
 	"viewer"
 ];
+/** Narrow an untrusted string to a {@link ProjectRole}. */
+function isProjectRole(value) {
+	return typeof value === "string" && PROJECT_ROLES.includes(value);
+}
 /** Label type keys seeded for every new project. */
 const SEEDED_LABEL_KEYS = [
 	"branch",
@@ -65,6 +82,6 @@ const RESERVED_LABEL_KEYS = ["build"];
 */
 const PERSISTENT_LABEL_KEY = "persistent";
 //#endregion
-export { BUILD_STATUSES, PERSISTENT_LABEL_KEY, PROJECT_ROLES, RESERVED_LABEL_KEYS, SEEDED_LABEL_KEYS, SESSION_COOKIE, SITE_ROLES, SNAPSHOT_STATUSES, TERMINAL_BUILD_STATUSES };
+export { BUILD_STATUSES, CANCELLABLE_BUILD_STATUSES, PERSISTENT_LABEL_KEY, PROJECT_ROLES, RESERVED_LABEL_KEYS, REVIEW_VERDICTS, SEEDED_LABEL_KEYS, SESSION_COOKIE, SITE_ROLES, SNAPSHOT_STATUSES, TERMINAL_BUILD_STATUSES, isProjectRole };
 
 //# sourceMappingURL=types.mjs.map

package/dist/types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.mjs","names":[],"sources":["../src/types.ts"],"sourcesContent":["/** All lifecycle statuses a build can carry. */\nexport const BUILD_STATUSES = [\n  \"pending\",\n  \"capturing\",\n  \"comparing\",\n  \"reviewing\",\n  \"approved\",\n  \"rejected\",\n  \"failed\",\n] as const;\n\n/** Lifecycle status of a build. */\nexport type BuildStatus = (typeof BUILD_STATUSES)[number];\n\n/** All review statuses a snapshot can carry. */\nexport const SNAPSHOT_STATUSES = [\n  \"pending\",\n  \"new\",\n  \"unchanged\",\n  \"changed\",\n  \"approved\",\n  \"rejected\",\n] as const;\n\n/** Review status of a snapshot. */\nexport type SnapshotStatus = (typeof SNAPSHOT_STATUSES)[number];\n\n/**\n * Build statuses considered terminal for retention purging.\n * Only builds that have finished review (`approved`, `rejected`, `failed`)\n * are eligible for TTL-based cleanup; `pending`/`reviewing` builds are kept.\n */\nexport const TERMINAL_BUILD_STATUSES: readonly BuildStatus[] = [\"approved\", \"rejected\", \"failed\"];\n\n/** All site-wide user roles. */\nexport const SITE_ROLES = [\"admin\", \"member\", \"viewer\"] as const;\n\n/** Site-wide role of a user. */\nexport type SiteRole = (typeof SITE_ROLES)[number];\n\n/** Shared session cookie name used by auth (ADR 0008). */\nexport const SESSION_COOKIE = \"storyshelf_session\";\n\n/** An authenticated user of the platform. */\nexport interface AuthUser {\n  /** User ID. */\n  id: string;\n  /** User email. */\n  email: string;\n  /** Display name. */\n  name: string;\n  /** Optional avatar URL. */\n  avatarUrl?: string;\n  /** Site-wide role. */\n  role: SiteRole;\n  /**\n   * Identity-provider group memberships (names or IDs, provider-dependent).\n   * Populated when the provider exposes group claims; absent otherwise.\n   * Drives group-to-role mapping at login.\n   */\n  groups?: string[];\n  /**\n   * Login method that minted this identity.\n   * Matches an engine login method id; absent for single-method deployments.\n   */\n  providerId?: string;\n}\n\n/** All per-project membership roles. */\nexport const PROJECT_ROLES = [\"admin\", \"approver\", \"developer\", \"viewer\"] as const;\n\n/** Per-project role of a member. */\nexport type ProjectRole = (typeof PROJECT_ROLES)[number];\n\n/** Label type keys seeded for every new project. */\nexport const SEEDED_LABEL_KEYS = [\n  \"branch\",\n  \"persistent\",\n  \"pr\",\n  \"mr\",\n  \"jira\",\n  \"linear\",\n  \"figma\",\n  \"custom\",\n] as const;\n\n/** Label type keys reserved for internal bookkeeping (cannot be created by users). */\nexport const RESERVED_LABEL_KEYS = [\"build\"] as const;\n\n/**\n * Label key that marks a build as exempt from retention purging.\n * Attach `persistent=true` to keep a build indefinitely, even after its TTL expires.\n */\nexport const PERSISTENT_LABEL_KEY = \"persistent\";\n"],"mappings":";;;;;AACA,MAAa,iBAAiB;CAC5B;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAMA,MAAa,oBAAoB;CAC/B;CACA;CACA;CACA;CACA;CACA;AACF;;;;;;AAUA,MAAa,0BAAkD;CAAC;CAAY;CAAY;AAAQ;;AAGhG,MAAa,aAAa;CAAC;CAAS;CAAU;AAAQ;;AAMtD,MAAa,iBAAiB;;AA4B9B,MAAa,gBAAgB;CAAC;CAAS;CAAY;CAAa;AAAQ;;AAMxE,MAAa,oBAAoB;CAC/B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAGA,MAAa,sBAAsB,CAAC,OAAO;;;;;AAM3C,MAAa,uBAAuB"}
+{"version":3,"file":"types.mjs","names":[],"sources":["../src/types.ts"],"sourcesContent":["/** All lifecycle statuses a build can carry. */\nexport const BUILD_STATUSES = [\n  \"pending\",\n  \"capturing\",\n  \"comparing\",\n  \"reviewing\",\n  \"approved\",\n  \"rejected\",\n  \"failed\",\n  \"cancelled\",\n] as const;\n\n/** Lifecycle status of a build. */\nexport type BuildStatus = (typeof BUILD_STATUSES)[number];\n\n/** All review statuses a snapshot can carry. */\nexport const SNAPSHOT_STATUSES = [\n  \"pending\",\n  \"new\",\n  \"unchanged\",\n  \"changed\",\n  \"approved\",\n  \"rejected\",\n] as const;\n\n/** Review status of a snapshot. */\nexport type SnapshotStatus = (typeof SNAPSHOT_STATUSES)[number];\n\n/**\n * Build statuses considered terminal for retention purging.\n * Only builds that have finished review (`approved`, `rejected`, `failed`, `cancelled`)\n * are eligible for TTL-based cleanup; `pending`/`reviewing` builds are kept.\n */\nexport const TERMINAL_BUILD_STATUSES: readonly BuildStatus[] = [\n  \"approved\",\n  \"rejected\",\n  \"failed\",\n  \"cancelled\",\n];\n\n/**\n * Statuses of a build whose capture or compare work may still run: a user may cancel it (the build\n * then ends `cancelled`, a terminal status no capture write moves it out of again).\n */\nexport const CANCELLABLE_BUILD_STATUSES: readonly BuildStatus[] = [\n  \"pending\",\n  \"capturing\",\n  \"comparing\",\n];\n\n/** All site-wide user roles. */\nexport const SITE_ROLES = [\"admin\", \"member\", \"viewer\"] as const;\n\n/** Site-wide role of a user. */\nexport type SiteRole = (typeof SITE_ROLES)[number];\n\n/** Shared session cookie name used by auth (ADR 0008). */\nexport const SESSION_COOKIE = \"storyshelf_session\";\n\n/** An authenticated user of the platform. */\nexport interface AuthUser {\n  /** User ID. */\n  id: string;\n  /** User email. */\n  email: string;\n  /** Display name. */\n  name: string;\n  /** Optional avatar URL. */\n  avatarUrl?: string;\n  /** Site-wide role. */\n  role: SiteRole;\n  /**\n   * Identity-provider group memberships (names or IDs, provider-dependent).\n   * Populated when the provider exposes group claims; absent otherwise.\n   * Drives group-to-role mapping at login.\n   */\n  groups?: string[];\n  /**\n   * Login method that minted this identity.\n   * Matches an engine login method id; absent for single-method deployments.\n   */\n  providerId?: string;\n}\n\n/** Build-level review verdicts (ADR 0013, decision 3). */\nexport const REVIEW_VERDICTS = [\"approved\", \"rejected\"] as const;\n\n/** A reviewer's verdict on a build. */\nexport type ReviewVerdict = (typeof REVIEW_VERDICTS)[number];\n\n/** All per-project membership roles. */\nexport const PROJECT_ROLES = [\"admin\", \"approver\", \"developer\", \"viewer\"] as const;\n\n/** Per-project role of a member. */\nexport type ProjectRole = (typeof PROJECT_ROLES)[number];\n\n/** Narrow an untrusted string to a {@link ProjectRole}. */\nexport function isProjectRole(value: unknown): value is ProjectRole {\n  return typeof value === \"string\" && (PROJECT_ROLES as readonly string[]).includes(value);\n}\n\n/** Label type keys seeded for every new project. */\nexport const SEEDED_LABEL_KEYS = [\n  \"branch\",\n  \"persistent\",\n  \"pr\",\n  \"mr\",\n  \"jira\",\n  \"linear\",\n  \"figma\",\n  \"custom\",\n] as const;\n\n/** Label type keys reserved for internal bookkeeping (cannot be created by users). */\nexport const RESERVED_LABEL_KEYS = [\"build\"] as const;\n\n/**\n * Label key that marks a build as exempt from retention purging.\n * Attach `persistent=true` to keep a build indefinitely, even after its TTL expires.\n */\nexport const PERSISTENT_LABEL_KEY = \"persistent\";\n"],"mappings":";;;;;AACA,MAAa,iBAAiB;CAC5B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAMA,MAAa,oBAAoB;CAC/B;CACA;CACA;CACA;CACA;CACA;AACF;;;;;;AAUA,MAAa,0BAAkD;CAC7D;CACA;CACA;CACA;AACF;;;;;AAMA,MAAa,6BAAqD;CAChE;CACA;CACA;AACF;;AAGA,MAAa,aAAa;CAAC;CAAS;CAAU;AAAQ;;AAMtD,MAAa,iBAAiB;;AA4B9B,MAAa,kBAAkB,CAAC,YAAY,UAAU;;AAMtD,MAAa,gBAAgB;CAAC;CAAS;CAAY;CAAa;AAAQ;;AAMxE,SAAgB,cAAc,OAAsC;CAClE,OAAO,OAAO,UAAU,YAAa,cAAoC,SAAS,KAAK;AACzF;;AAGA,MAAa,oBAAoB;CAC/B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAGA,MAAa,sBAAsB,CAAC,OAAO;;;;;AAM3C,MAAa,uBAAuB"}

package/dist/urls.d.mts

@@ -10,10 +10,14 @@ interface UrlBuilder {
   buildsList(slug: string): string;
   build(slug: string, buildId: string): string;
   buildDiff(slug: string, buildId: string): string;
+  /** Review page of one snapshot: the build's diff page with that snapshot selected. */
+  snapshot(slug: string, buildId: string, snapshotId: string): string;
   library(slug: string): string;
   jobs(slug: string): string;
   labels(slug: string): string;
   label(slug: string, key: string, value: string): string;
+  /** Stable component page, keyed by the story file's import path. */
+  component(slug: string, importPath: string): string;
   storybook(slug: string): string;
   storybookLabel(slug: string, key: string, value: string): string;
   storybookBuild(slug: string, buildId: string): string;