@storyshelf/core 0.6.2 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
 # @storyshelf/core
 
-The domain layer of StoryShelf: adapter interfaces, models, capture pipeline, diff engine, and retention logic — with no HTTP dependency, so workers import it without pulling a server. The Hono router lives in `@storyshelf/app`. Compose pluggable adapters into a complete self-hosted visual testing server.
+The domain layer of StoryShelf: adapter interfaces, models, capture pipeline, diff engine, and retention logic — with no HTTP dependency, so the capture consumer imports it without pulling a server. The Hono router lives in `@storyshelf/app`. Compose pluggable adapters into a complete self-hosted visual testing server.
 
 ## Install
 
@@ -22,13 +22,12 @@ import { createShelfApp } from "@storyshelf/app";
 const app = createShelfApp({
   database, // DatabaseAdapter
   storage, // StorageAdapter
-  captureRunner, // CaptureRunner (optional)
+  testing: { runner: captureRunner, concurrency: 2, compare: { threads: 2 } }, // capture pipeline + screenshot comparison (optional; absent = Storybook hosting only)
   auth, // Auth from @storyshelf/auth (optional)
-  gitHosts, // GitHostProvider[] (optional)
+  notifications: { notifiers: [...chatNotifiers, ...gitNotifiers] }, // NotifierProvider[]: chat, email and git (optional)
   logger, // pino Logger (optional; built internally if omitted)
   ui: { name: "My Shelf" }, // UIConfig (optional)
   config: {
-    captureConcurrency: 2,
     purgeTtlDays: 30,
     branchTtlDays: 30,
     branchGcIntervalMs: 86_400_000,
@@ -39,23 +38,37 @@ const app = createShelfApp({
 serve({ fetch: app.fetch, port: 3000 });
 ```
 
+Adapter `setup` hooks kick off in the background when the router is created. Await them before serving for fail-fast startup (or let the first request gate on settlement), and tear down adapters on shutdown:
+
+```ts
+await app.lifecycle.setup();
+
+const server = serve({ fetch: app.fetch, port: 3000 });
+process.on("SIGTERM", () => {
+  app.lifecycle
+    .teardown()
+    .then(() => server.close())
+    .catch(() => {});
+});
+```
+
 ## API
 
 ### `createShelfApp(options: ShelfOptions): Hono`
 
 Assembles the router from the provided adapters. `ShelfOptions`:
 
-| Option          | Type                        | Description                                                                              |
-| --------------- | --------------------------- | ---------------------------------------------------------------------------------------- |
-| `database`      | `DatabaseAdapter`           | **Required.** Data access.                                                               |
-| `storage`       | `StorageAdapter`            | **Required.** Blob storage for screenshots, diffs, storybook archives.                   |
-| `captureRunner` | `CaptureRunner`             | Optional. Enables the async capture pipeline (pure renderer).                            |
-| `captureQueue`  | `CaptureQueue`              | Optional. Queue adapter; defaults to `InMemoryCaptureQueue`.                             |
-| `auth`          | `Auth` (`@storyshelf/auth`) | Optional. Enables auth and the login UI.                                                 |
-| `gitHosts`      | `GitHostProvider[]`         | Optional. Git-host adapters (GitHub/GitLab) for status checks, merge gates, PR comments. |
-| `logger`        | `Logger` (pino)             | Optional. Shared logger. Construct a fallback via `createShelfLogger()`.                 |
-| `ui`            | `UIConfig`                  | Optional. UI branding.                                                                   |
-| `config`        | `ShelfConfig`               | Optional. Server behavior.                                                               |
+| Option            | Type                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ----------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `database`        | `DatabaseAdapter`                             | **Required.** Data access.                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `storage`         | `StorageAdapter`                              | **Required.** Blob storage for screenshots, diffs, storybook archives.                                                                                                                                                                                                                                                                                                                                                                    |
+| `testing`         | `{ runner, concurrency?, compare?, images? }` | Optional. Enables the async capture pipeline: `runner` (pure renderer; required, `testing: {}` throws; captures queue on the database), `concurrency` (jobs at once; default 2 on hosts with ≥ 2 CPUs and ≥ 3 GB, otherwise 1), `retries` (default 2). Absent means Storybook hosting only. `workerEntry` runs captures in a forked child the app pushes jobs to (`runCaptureChild`); `mode` is `auto` (default), `in-process` or `fork`. |
+| `testing.compare` | `{ threads? }`                                | Optional. Worker threads for pixel diffs (default CPU count − 1; `0` = main thread). Also serves the re-diff endpoint. Overrides `STORYSHELF_DIFF_WORKERS`.                                                                                                                                                                                                                                                                               |
+| `notifications`   | `{ notifiers?, emailSender?, config? }`       | Optional. `notifiers` (Slack/Teams/email providers and the GitHub/GitLab git providers of `@storyshelf/notify-git`), `emailSender` (transport whose lifecycle hooks run with the app's), `config` (`fromEmail`, `fromName`, `footerText`, `slackUsername`).                                                                                                                                                                               |
+| `auth`            | `Auth` (`@storyshelf/auth`)                   | Optional. Enables auth and the login UI.                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `logger`          | `Logger` (pino)                               | Optional. Shared logger. Construct a fallback via `createShelfLogger()`.                                                                                                                                                                                                                                                                                                                                                                  |
+| `ui`              | `UIConfig`                                    | Optional. UI branding.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `config`          | `ShelfConfig`                                 | Optional. Server behavior.                                                                                                                                                                                                                                                                                                                                                                                                                |
 
 ### `ShelfConfig`
 
@@ -63,13 +76,14 @@ Assembles the router from the provided adapters. `ShelfOptions`:
 interface ShelfConfig {
   secret?: string; // session signing secret
   publishedBaseDomain?: string; // for published storybook URLs
-  captureConcurrency?: number; // concurrent capture jobs (default 2)
-  scratchDir?: string; // capture working directory (required with captureRunner)
+  scratchDir?: string; // working directory for publishing and capture (default: <os.tmpdir()>/storyshelf)
   purgeTtlDays?: number; // purge builds older than N days
   branchTtlDays?: number | null; // branch baseline TTL, days; null disables GC (default 30)
   branchGcIntervalMs?: number; // branch GC interval, ms; daily via interval clock (default 86_400_000)
   maxUploadBytes?: number; // single-zip upload cap (default 1 GiB)
-  maxInlineUnzipSize?: number; // inline statics extraction cap; unset = capture-only
+  maxInlineUnzipSize?: number; // largest zip extracted inline at upload (default 50 MB; 0 = always a publish job)
+  maxZipEntries?: number; // most entries a zip may hold (default 50 000)
+  maxUnzippedBytes?: number; // most uncompressed bytes a zip may expand to (default 2 GiB)
   viewports?: Viewport[]; // capture viewports
 }
 ```
@@ -95,7 +109,8 @@ All adapters are constructor-injected (no AsyncLocalStorage). See `docs/architec
 - `Auth` (`@storyshelf/auth`) — the shelf authentication singleton: `check(request)`, `handler` (mount at `/api/auth/*`), `loginMethods()`, invites, sessions, passkeys. `AuthUser` and the shared `SESSION_COOKIE` live in `core/types`.
 - `CaptureRunner` (`core/adapter/capture-runner`) — a **pure capture renderer**: `render(input) => RenderResult`, `cancel(buildId)`. Also exports `RenderedSnapshot`, `RenderResult`, `StoryEntry`, `StorySourceAdapter`, `Viewport`.
 - `CaptureQueue` (`core/adapter/capture-queue`) — `enqueue({ buildId, reqId? })`, plus `status`, `active`, `recent`. Also exports `CaptureJob`, `QueueEntry`, `JobStatus`.
-- `GitHostProvider` / `GitHostAdapter` (`core/adapter/git-host`) — set commit status checks, detect merges, and upsert PR comments. Real providers ship in `@storyshelf/git-github` and `@storyshelf/git-gitlab`. Also exports `CheckStatus`.
+- `DesignProvider` / `DesignClient` (`core/adapter/design`) — validate design links and fetch file metadata and rendered previews from a design tool. The Figma provider ships in `@storyshelf/design-figma`; also exports `parseDesignUrl` and `InvalidDesignUrlError`.
+- `NotifierProvider` / `NotifierAdapter` (`core/adapter/notifier`) — one family with two delivery kinds: `message` providers (`@storyshelf/notify-chat`, `@storyshelf/notify-email`) `send` a formatted message; `state` providers (`@storyshelf/notify-git`: GitHub, GitLab) `setState` a commit status or pull-request comment, idempotently. Also exports `emitNotifications`, `statusesForBuild` (the pure build-to-statuses function), `writeBuildState`, `isStateProvider`, `NotifierState` and `NotifierStateTarget`; `core/capture` exports the `notify` job (`createBuildStatePublisher`, `createNotifyHandler`, `createNotifyEnqueuer`).
 
 ### Logging
 
@@ -105,11 +120,15 @@ All adapters are constructor-injected (no AsyncLocalStorage). See `docs/architec
 
 Import from `core/capture`, `core/diff`, and the model entries — never from the barrel:
 
-- `executeCaptureJob({ buildId, reqId }, deps)` (`core/capture`) — the capture **orchestrator**: loads the build, marks it `capturing`, extracts the uploaded archive into `scratchDir`, discovers stories, delegates rendering to a pure `CaptureRunner`, and persists. `createShelfApp` wires it into a `CaptureQueue` when `capture` is supplied (and requires `ShelfConfig.scratchDir`). Also exports `CaptureJobOptions`.
+- `executeCaptureJob({ buildId, reqId }, deps)` (`core/capture`) — the capture **orchestrator**: loads the build, marks it `capturing`, extracts the uploaded archive into `scratchDir`, discovers stories, delegates rendering to a pure `CaptureRunner`, and persists. `createShelfApp` wires it into a `CaptureQueue` when `testing` is supplied (and requires `ShelfConfig.scratchDir`). Also exports `CaptureJobOptions`.
 - `persistCapture(ctx: CaptureContext)` (`core/capture`) — writes screenshots, diffs against the branch baseline, creates snapshots, and finalizes a build from a pure renderer's `captures`. Also exports `CaptureContext`.
 - `StorybookAdapter` (`core/capture`) — reads a built Storybook's `index.json`/`stories.json`.
-- `InMemoryCaptureQueue` (`core/capture`) — in-process, concurrency-limited queue for long-lived hosts; supply a remote queue with a separate worker for serverless.
-- `diffImages(baseline: Buffer, current: Buffer, options: DiffOptions): DiffResult` (`core/diff`) — pixelmatch-based diff. Also exports `DiffOptions`, `DiffResult`.
+- `createCatalogLoader({ db, storage })`, `createCatalogHook(loader)`, `catalogueBuild`, `parseStorybookIndex`, `groupComponents`, `componentBuildHistory` (`core/capture`) — the Storybook catalog of a published build (ADR 0006, decision 9): `catalog.json` plus one `build_components` row per component, written by the `afterPublish` hook, loaded through an in-process LRU and catalogued lazily for older builds. `BuildComponentModel` (`core/models`) reads and replaces the rows.
+- `BuildReviewModel`, `deriveReviewStatus`, `latestVerdicts` (`core/models`) — build-level review (ADR 0013, decision 3): `build_reviews` rows (a reviewer's newest row is their verdict) and the pure rule that turns them into `approved`, `rejected` or `pending` when `testing` is off and review is on. `publishVerdict` (`core/capture`) takes the project's review switch: a published non-default build is accepted when review is off.
+- `computeChangeset`, `changesetOf`, `findChangesetBaseline`, `acceptPendingWithoutWork` (`core/models`) — the catalog changeset of a build (components added, removed and changed against its baseline build, ADR 0013 decision 8) and the pass that accepts a project's idle pending builds when review is turned off. `Retention.purge` (`core/retention`) also removes `pending` builds idle past the retention window.
+- `createDatabaseCaptureQueue(db, options)` (`core/capture`) — a `PollableCaptureQueue` on the app's own database (`capture_jobs`; ADR 0006): per-attempt claim rows fence concurrent instances, leases follow progress, retries back off, `cancel(jobId | buildId)` reaches the holder within 5 s. Not wired into the app yet. `startPollLoop` and `keepJobLease` are the consumer-side helpers.
+- `createCaptureConsumer({ queue, capture, handlers, config })` (`core/capture`) — the consumer loop over any `PollableCaptureQueue`: a handler per job kind (`capture` runs the core dispatch), a slot before each poll, retries with exponential backoff and the final-attempt rule, lease kept by progress, cancel and lease loss stop the run, `stop()` drains. `runCaptureChild` (forked capture) runs it over IPC.
+- `diffImages(baseline: Buffer, current: Buffer, options: DiffOptions): Promise<DiffResult>` (`core/diff`) — pixelmatch-based diff (async since 0.7: the optional `sharp` codec is async). An optional fourth `codec` argument selects the PNG codec and defaults to `pngjs`. Re-exported from `@storyshelf/image`, which owns the image engines; also exports `diffImagesAsync` (worker pool), `configureImages({ engine, threads })`, `DiffOptions`, `DiffResult`. `configureDiffPool` remains as a deprecated alias.
 - Models, schema, and row types back every entity; retention runs inside the router (`Retention.purge` for builds + `Retention.purgeStaleBranches` for branch GC via `retention-timer.ts` daily sweep). (Models are private implementation details with no public entry — reach row types via `core/schema`.)
 
 ### Helpers
@@ -125,15 +144,13 @@ See `docs/architecture.md` and the ADRs in `docs/adr/`.
 
 ## Deployment targets
 
-The core router is runtime-agnostic (Web `Request`/`Response`, `fetch`, `crypto`, `URL`). The only Node-specific piece is the in-process `InMemoryCaptureQueue`, which suits long-lived Node servers; serverless runtimes swap in a remote `CaptureQueue` (e.g. `@storyshelf/queue-sqs`) plus a separate worker. You assemble a server for any platform — `storyshelf server init` generates a scaffold with the adapters you choose:
+The core router is runtime-agnostic (Web `Request`/`Response`, `fetch`, `crypto`, `URL`). The Node-specific piece is the capture consumer and its optional forked child, which need a long-lived Node server: that is what the `testing` option turns on, and the database is the queue (ADR 0006). Without `testing` an instance only hosts Storybooks and runs on serverless platforms too. You assemble a server for any platform — `storyshelf server init` generates a scaffold with the adapters you choose:
 
-| Platform                                   | Database                              | Storage                          | Capture queue                   | Server entry               |
-| ------------------------------------------ | ------------------------------------- | -------------------------------- | ------------------------------- | -------------------------- |
-| **Vercel**                                 | `@storyshelf/db-sqlite/turso`         | `@storyshelf/storage-s3` (R2/S3) | Remote `CaptureQueue` + worker  | Hono + `@hono/vercel-edge` |
-| **Cloudflare Workers**                     | `@storyshelf/db-sqlite/turso`         | `@storyshelf/storage-s3` (R2)    | Workers Queues `CaptureQueue`   | Hono + Workers entry       |
-| **Azure Functions**                        | `@storyshelf/db-sqlite/turso`         | `@storyshelf/storage-s3` (Blob)  | Azure Queues `CaptureQueue`     | Hono + Azure handler       |
-| **AWS Lambda**                             | `@storyshelf/db-sqlite/turso`         | `@storyshelf/storage-s3`         | SQS `CaptureQueue`              | Hono + Lambda handler      |
-| **Deno Deploy**                            | `@storyshelf/db-sqlite/turso`         | `@storyshelf/storage-s3`         | Custom `CaptureQueue` (Deno KV) | Hono + Deno entry          |
-| **Bun / Node (VPS, Fly, Railway, Render)** | `db-sqlite` (+ `./bun-sqlite` on Bun) | `storage-local` / `storage-s3`   | `InMemoryCaptureQueue`          | `storyshelf-server serve`  |
+| Platform                                                             | Database                              | Storage                                        | `testing` (capture) | Server entry                      |
+| -------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------- | ------------------- | --------------------------------- |
+| **Vercel, AWS Lambda, Azure Functions**                              | `@storyshelf/db-sqlite/turso`         | `@storyshelf/storage-s3`                       | No (hosting only)   | Hono + platform handler           |
+| **Cloudflare Workers**                                               | `@storyshelf/db-sqlite/d1` or turso   | `@storyshelf/storage-s3` (R2)                  | No (hosting only)   | Hono + Workers entry              |
+| **Bun / Node (VPS, Fly, Railway, Render)**                           | `db-sqlite` (+ `./bun-sqlite` on Bun) | `storage-local` / `storage-s3`                 | Yes, database queue | `storyshelf-server serve`         |
+| **Container platforms (ECS, Cloud Run, Container Apps, Kubernetes)** | `db-postgres` / `db-mysql`            | `storage-s3` / `storage-gcs` / `storage-azure` | Yes, database queue | `storyshelf server init` scaffold |
 
-All clouds are equal — pick the adapters that match your infrastructure. See the **Deployment** guide for recipes including a minimal Turso + S3 + `InMemoryCaptureQueue` example.
+All clouds are equal — pick the adapters that match your infrastructure. See the **Deployment** guide for recipes including a minimal Turso + S3 example.

package/dist/adapter/capture-queue.d.mts

@@ -1,12 +1,13 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { Adapter } from "./metadata.mjs";
-//#region src/adapters/capture-queue.d.ts
 /** Lifecycle status of a queued capture job. */
 type JobStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
 /** Observable state of a single capture queue entry. */
 interface QueueEntry {
   buildId: string;
+  /** Set on the entry of a shard job; the build's own entry has none. */
+  shard?: string;
   status: JobStatus;
   queuedAt: string;
   startedAt?: string;
@@ -23,6 +24,11 @@ interface CaptureJob {
    * instead of starting a root span; absent means start a new trace.
    */
   traceparent?: string;
+  /**
+   * `capture_shards` row to render. Absent on a build job, which plans the build (and, when it is
+   * big, hands out shard jobs) or captures it whole; every transport carries it through unchanged.
+   */
+  shard?: string;
 }
 /** A job polled from a queue with transport metadata. */
 interface PollableJob extends CaptureJob {
@@ -30,9 +36,21 @@ interface PollableJob extends CaptureJob {
   receipt?: string;
   /** Number of delivery attempts already made (0 = first delivery). */
   attempts?: number;
+  /**
+   * Lease (visibility timeout / ack deadline / lock) in ms granted at poll
+   * time. The worker renews at a fraction of this while a capture runs;
+   * absent means the transport has no renewable lease.
+   */
+  leaseMs?: number;
   /** Raw transport message for debugging. */
   raw?: unknown;
 }
+/**
+ * Outcome of renewing (or inspecting) a polled job's lease: `lost` means another consumer owns it
+ * now or the job already ended; `cancelled` means someone asked for the job to stop, and the holder
+ * should cancel its run and settle the job (queues without cancel never report it).
+ */
+type LeaseRenewal = "ok" | "lost" | "cancelled";
 /**
  * A capture job queue, decoupled from the runtime.
  *
@@ -59,6 +77,12 @@ interface CaptureQueue extends Adapter<{
   active(): Promise<QueueEntry[]>;
   /** The most recent queue entries, newest first. */
   recent(limit: number): Promise<QueueEntry[]>;
+  /**
+   * Cancel by job id, or every unfinished job of a build by build id (every job kind of the build on the database queue). Optional. A job that has not
+   * started ends `cancelled` at once; a running one is flagged, and its holder sees `"cancelled"`
+   * from `extend`/`inspect`. Resolves true when anything matched.
+   */
+  cancel?(id: string): Promise<boolean>;
 }
 /** Extension for queues that support worker-side polling. */
 interface PollableCaptureQueue extends CaptureQueue {
@@ -68,12 +92,28 @@ interface PollableCaptureQueue extends CaptureQueue {
   }): Promise<PollableJob | null>;
   /** Acknowledge successful processing of a polled job. */
   ack(job: PollableJob): Promise<void>;
-  /** Negatively acknowledge; requeue with optional delay when possible. */
+  /**
+   * Negatively acknowledge; requeue with optional delay when possible. `requeue: false` is a final
+   * failure: the job is dropped, and `error` says why for queues that keep a record of it.
+   */
   nack(job: PollableJob, options?: {
     requeue?: boolean;
     delayMs?: number;
+    error?: string;
   }): Promise<void>;
+  /**
+   * Extend the lease on an in-flight job by another `job.leaseMs`. Optional:
+   * queues without a renewable lease (e.g. Redis) omit it. May update
+   * `job.receipt` in place when the transport rotates it. Resolves `"lost"`
+   * only when the transport conclusively reports the message is no longer
+   * owned by this consumer; transient failures must reject.
+   */
+  extend?(job: PollableJob): Promise<LeaseRenewal>;
+  /**
+   * Read the job's state without renewing its lease: the holder's periodic cancel check.
+   * Optional; same outcomes as `extend`.
+   */
+  inspect?(job: PollableJob): Promise<LeaseRenewal>;
 }
-//#endregion
-export { CaptureJob, CaptureQueue, JobStatus, PollableCaptureQueue, PollableJob, QueueEntry };
+export { CaptureJob, CaptureQueue, JobStatus, LeaseRenewal, PollableCaptureQueue, PollableJob, QueueEntry };
 //# sourceMappingURL=capture-queue.d.mts.map

package/dist/adapter/capture-runner.d.mts

@@ -1,10 +1,36 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { StoryEntry, StorySourceAdapter, Viewport } from "../capture/adapter.mjs";
+import { StoryEntry, StoryParameters, StorySourceAdapter, Viewport } from "../capture/adapter.mjs";
+import { BROWSER_NAMES, BrowserName, CaptureTarget, DEFAULT_BROWSER, ParsedTarget, RunnerTarget, TARGET_NAME_PATTERN, TargetLaunchError, TargetReach, TargetStatus, engineOf, isBrowserName, isCaptureTarget, parseTarget, tryParseTarget, unavailableReason } from "../adapters/capture-target.mjs";
+import { TargetOffers, createTargetOffers } from "../adapters/capture-target-offers.mjs";
+import { RemoteBrowser, RemoteConnectContext, RemoteConnection, RemoteLeaseOutcome, RemoteLeasedConnection, RemoteOptions, RemoteProtocol, RemotePurpose, RemoteReleaseInfo, RemoteSupport, RemoteTarget, defineRemote, hasSchemeFor, isRemoteBrowser, remoteTargetsOf, scrubConnection } from "../adapters/remote-browser.mjs";
+import { HeldConnection } from "../adapters/remote-lease-held.mjs";
+import { RemoteConnectError, RemoteConnectErrorOptions } from "../adapters/remote-lease-error.mjs";
+import { onRemoteShutdown, shutdownRemote } from "../adapters/remote-lease-shutdown.mjs";
+import { ConnectLeasedContext, ConnectLeasedOptions, connectLeased } from "../adapters/remote-lease.mjs";
+import { PoolLease, RefCounted, RefCountedOptions, refCounted } from "../adapters/remote-pool.mjs";
+import { RenderRuns } from "../adapters/render-runs.mjs";
 import { Adapter } from "./metadata.mjs";
 import { JobStatus } from "./capture-queue.mjs";
 import { Logger } from "pino";
-//#region src/adapters/capture-runner.d.ts
+/**
+ * The rendering environment a runner captured in. Two captures with the same environment (and
+ * engine and viewport) should produce identical pixels; a different one explains a visual diff
+ * that no code change caused. Every field is optional: runners report what they can.
+ */
+interface CaptureEnvironment {
+  /** Browser build, as the driver reports it (for example `124.0.6367.29`). */
+  browserVersion?: string;
+  /**
+   * OS and CPU text rendering depends on: the host's `process.platform-arch` for a local browser;
+   * for a remote one what the browser reported (`linux`, `windows`), never the host's.
+   */
+  platform?: string;
+  /** Device pixel ratio the pages were rendered at. */
+  deviceScaleFactor?: number;
+  /** Digest of the installed system fonts, when they could be listed. */
+  fontsHash?: string;
+}
 /** A screenshot produced by a capture renderer. */
 interface RenderedSnapshot {
   /** The rendered story (echoed back from the render request). */
@@ -15,6 +41,25 @@ interface RenderedSnapshot {
   viewport?: Viewport;
   /** PNG screenshot bytes. */
   screenshot: Buffer;
+  /** Target that produced the screenshot (the request's `target`); chromium when absent. */
+  browser?: CaptureTarget;
+  /**
+   * Wall-clock milliseconds the renderer spent on this capture, when it measured it. Recorded per
+   * snapshot and read back as the per-story cost a shard plan orders its work by (ADR 0005).
+   */
+  durationMs?: number;
+  /** Axe violation texts found on this capture (empty or absent: none, or not checked). */
+  a11y?: string[];
+  /**
+   * Set by the orchestrator when it already wrote the screenshot to storage
+   * (via `onCapture`); `screenshot` is then empty and must not be written again.
+   * Runners never set this.
+   */
+  stored?: boolean;
+  /** Where the orchestrator stored it (content-addressed); set together with `stored`. */
+  storedPath?: string;
+  /** Environment of the render pass that produced it; filled in by the orchestrator from {@link RenderResult.environment}. */
+  environment?: CaptureEnvironment;
 }
 /** A story/viewport that a renderer could not capture. */
 interface RenderFailure {
@@ -24,6 +69,8 @@ interface RenderFailure {
   viewportName: string;
   /** Error message. */
   error: string;
+  /** Target the failure happened on; chromium when absent. */
+  browser?: CaptureTarget;
 }
 /** The outcome of a render request. */
 interface RenderResult {
@@ -31,6 +78,17 @@ interface RenderResult {
   captures: RenderedSnapshot[];
   /** Story/viewport pairs the renderer could not capture. */
   failures: RenderFailure[];
+  /** What this render ran on; optional so third-party runners keep working. */
+  environment?: CaptureEnvironment;
+}
+/** What a runner reports for one Storybook `.test()` entry it ran in the iframe. */
+interface TestOutcome {
+  /** The test entry's id (`<story id>:<test name slug>`). */
+  storyId: string;
+  status: "passed" | "failed";
+  /** Why it failed: the assertion, render error or timeout message. */
+  error?: string;
+  durationMs: number;
 }
 /**
  * A pure capture renderer.
@@ -43,12 +101,13 @@ interface RenderResult {
  * orchestrator's job (see `capture/orchestrator.ts`), keeping every adapter
  * implementation free of server concerns.
  */
-type BrowserName = "chromium" | "firefox" | "webkit" | "chrome";
-/** Browser names accepted for capture rendering (Chromium default). */
-declare const BROWSER_NAMES: readonly ["chromium", "firefox", "webkit", "chrome"];
 interface CaptureRunner extends Adapter<{
   readonly category: "capture-runner";
-  readonly supportedBrowsers?: readonly BrowserName[];
+  /**
+   * Every target the runner offers, default first (ADR 0007, decision 1), with whether each can
+   * render now. A runner that omits it offers any target.
+   */
+  readonly targets?: readonly RunnerTarget[];
 }> {
   /**
    * Render configured viewports for the given stories of an extracted
@@ -59,6 +118,13 @@ interface CaptureRunner extends Adapter<{
   render(input: {
     /** Build being captured, used to correlate cancels with in-flight work. */
     buildId: string;
+    /**
+     * This call's handle within the build, for `cancel(buildId, runId)`: several renders of one
+     * build (its shards) can be in flight in one process. Absent, the build id is used.
+     */
+    runId?: string | undefined;
+    /** The shard's 1-based position in the build's plan, for a remote service that routes per shard. */
+    shardIndex?: number | undefined;
     /** Root of the already-extracted Storybook build. */
     storybookDir: string;
     /** Stories to render. */
@@ -73,8 +139,22 @@ interface CaptureRunner extends Adapter<{
     playTimeoutMs?: number;
     /** Whether to run a11y checks (axe) before screenshot; annotated as non-blocking. */
     runA11y?: boolean;
-    /** Browser to use for rendering (chromium default). */
-    browser?: BrowserName;
+    /** Target to render on (chromium when absent). */
+    target?: CaptureTarget;
+    /**
+     * An absolute URL to the build's Storybook that the target's browser can reach, set for a
+     * `reach: "url"` target (ADR 0007, decision 5). The runner navigates there instead of to its
+     * loopback server; a `reach: "url"` target given none fails to start. Never logged.
+     */
+    storybookUrl?: string;
+    /**
+     * Optional streaming hand-off. When provided, the runner awaits it with each
+     * capture as soon as it is taken, then drops the buffer instead of adding the
+     * capture to `RenderResult.captures`, so a large build never holds every
+     * screenshot in memory. A rejection is reported as a render failure for that
+     * story/viewport. Runners that do not support it return captures as usual.
+     */
+    onCapture?: (capture: RenderedSnapshot) => Promise<void>;
     /**
      * Test/extension seam: override the story source adapter (defaults to
      * `StorybookAdapter`). Only the renderer uses it; discovery stays the
@@ -82,9 +162,51 @@ interface CaptureRunner extends Adapter<{
      */
     adapter?: StorySourceAdapter;
   }): Promise<RenderResult>;
-  /** Cancel a pending or in-flight render for a build. */
-  cancel(buildId: string): Promise<void>;
+  /**
+   * Optional pre-pass reading each story's fully resolved parameters (project,
+   * component and story levels stacked) from the running preview. Storybook's
+   * index rarely carries parameters, so this is how the orchestrator learns
+   * which modes a story declares before it builds the capture matrix.
+   * Absent or failing, the orchestrator falls back to index parameters.
+   */
+  extractParameters?(input: {
+    buildId: string;
+    storybookDir: string;
+    stories: StoryEntry[];
+    logger?: Logger;
+    /** Target to read the parameters on: the project's primary (chromium when absent). */
+    target?: CaptureTarget;
+    /** As on `render`: the URL a `reach: "url"` target's browser opens. */
+    storybookUrl?: string;
+    adapter?: StorySourceAdapter;
+  }): Promise<Record<string, StoryParameters>>;
+  /**
+   * Optional: run Storybook 10 `.test()` entries (index `subtype: "test"`) as interaction tests.
+   * Each entry's iframe URL renders the story it is written under and runs the test body as the
+   * play function; the runner reports pass or fail per entry from Storybook's own events, and
+   * takes no screenshot. A runner without it leaves projects that turn tests on with a warning.
+   * Cancellable with `cancel`, like `render`.
+   */
+  runTests?(input: {
+    buildId: string;
+    runId?: string | undefined;
+    storybookDir: string;
+    /** The test entries to run (`StoryEntry.parentId` is set). */
+    tests: StoryEntry[];
+    logger?: Logger;
+    /** Timeout for one test (render plus body) in ms. */
+    playTimeoutMs?: number;
+    /** Target to run on: the project's primary (chromium when absent). */
+    target?: CaptureTarget;
+    /** As on `render`: the URL a `reach: "url"` target's browser opens. */
+    storybookUrl?: string;
+    adapter?: StorySourceAdapter;
+  }): Promise<TestOutcome[]>;
+  /**
+   * Cancel in-flight renders of a build: the ones started with `runId`, or every one of the build
+   * when it is absent. Runners can track their calls with {@link RenderRuns}.
+   */
+  cancel(buildId: string, runId?: string): Promise<void>;
 }
-//#endregion
-export { BROWSER_NAMES, BrowserName, CaptureRunner, type JobStatus, RenderFailure, RenderResult, RenderedSnapshot, type StoryEntry, type StorySourceAdapter, type Viewport };
+export { BROWSER_NAMES, type BrowserName, CaptureEnvironment, CaptureRunner, type CaptureTarget, type ConnectLeasedContext, type ConnectLeasedOptions, DEFAULT_BROWSER, type HeldConnection, type JobStatus, type ParsedTarget, type PoolLease, type RefCounted, type RefCountedOptions, type RemoteBrowser, type RemoteConnectContext, RemoteConnectError, type RemoteConnectErrorOptions, type RemoteConnection, type RemoteLeaseOutcome, type RemoteLeasedConnection, type RemoteOptions, type RemoteProtocol, type RemotePurpose, type RemoteReleaseInfo, type RemoteSupport, type RemoteTarget, RenderFailure, RenderResult, RenderRuns, RenderedSnapshot, type RunnerTarget, type StoryEntry, type StorySourceAdapter, TARGET_NAME_PATTERN, TargetLaunchError, type TargetOffers, type TargetReach, type TargetStatus, TestOutcome, type Viewport, connectLeased, createTargetOffers, defineRemote, engineOf, hasSchemeFor, isBrowserName, isCaptureTarget, isRemoteBrowser, onRemoteShutdown, parseTarget, refCounted, remoteTargetsOf, scrubConnection, shutdownRemote, tryParseTarget, unavailableReason };
 //# sourceMappingURL=capture-runner.d.mts.map

package/dist/adapter/capture-runner.mjs

@@ -1,15 +1,12 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/adapters/capture-runner.ts
-/** Browser names accepted for capture rendering (Chromium default). */
-const BROWSER_NAMES = [
-	"chromium",
-	"firefox",
-	"webkit",
-	"chrome"
-];
-//#endregion
-export { BROWSER_NAMES };
-
-//# sourceMappingURL=capture-runner.mjs.map
+import { BROWSER_NAMES, DEFAULT_BROWSER, TARGET_NAME_PATTERN, TargetLaunchError, engineOf, isBrowserName, isCaptureTarget, parseTarget, tryParseTarget, unavailableReason } from "../adapters/capture-target.mjs";
+import { createTargetOffers } from "../adapters/capture-target-offers.mjs";
+import { defineRemote, hasSchemeFor, isRemoteBrowser, remoteTargetsOf, scrubConnection } from "../adapters/remote-browser.mjs";
+import { RemoteConnectError } from "../adapters/remote-lease-error.mjs";
+import { onRemoteShutdown, shutdownRemote } from "../adapters/remote-lease-shutdown.mjs";
+import { connectLeased } from "../adapters/remote-lease.mjs";
+import { refCounted } from "../adapters/remote-pool.mjs";
+import { RenderRuns } from "../adapters/render-runs.mjs";
+export { BROWSER_NAMES, DEFAULT_BROWSER, RemoteConnectError, RenderRuns, TARGET_NAME_PATTERN, TargetLaunchError, connectLeased, createTargetOffers, defineRemote, engineOf, hasSchemeFor, isBrowserName, isCaptureTarget, isRemoteBrowser, onRemoteShutdown, parseTarget, refCounted, remoteTargetsOf, scrubConnection, shutdownRemote, tryParseTarget, unavailableReason };

package/dist/adapter/database.d.mts

@@ -2,21 +2,35 @@ import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { Adapter, AdapterMetadata } from "./metadata.mjs";
 import { SQL, Table } from "drizzle-orm";
-//#region src/adapters/database.d.ts
+/** A fenced reference write lost its generation race and should be retried. */
+declare class ReferenceGenerationConflict extends Error {}
 /** Type-safe table map enforced on every DatabaseAdapter. */
 interface Tables {
   projects: Table;
-  projectStatusConfigs: Table;
   builds: Table;
   captureAttempts: Table;
   captureLogs: Table;
+  captureShards: Table;
+  captureJobs: Table;
+  buildComponents: Table;
+  buildReviews: Table;
+  siteSettings: Table;
   snapshots: Table;
   baselines: Table;
   comments: Table;
   labelTypes: Table;
   buildLabels: Table;
+  projectLinks: Table;
+  designLinks: Table;
+  designCredentials: Table;
+  userConnections: Table;
+  designNodes: Table;
+  buildPackageUsage: Table;
   tokens: Table;
   webhooks: Table;
+  insights: Table;
+  aiUsage: Table;
+  aiBudgetAlerts: Table;
   notificationChannels: Table;
   notificationSubscriptions: Table;
   users: Table;
@@ -61,16 +75,84 @@ interface TxStore {
   /** Count rows matching an optional where condition. */
   count(table: Table, where?: SQL): Promise<number>;
 }
-/** Database abstraction over Drizzle tables, agnostic of dialect and driver. */
-interface DatabaseAdapter extends Adapter<{
+/** An owner of durable protection for a build. Historical comparisons are not build owners. */
+interface BuildReferenceOwner {
+  type: "baseline" | "investigation";
+  id: string;
+  projectId: string;
+}
+/** One owner's complete new reference set for an atomic multi-owner mutation. */
+interface BuildReferenceChange {
+  owner: BuildReferenceOwner;
+  buildIds: readonly string[];
+}
+/** A complete owner reference replacement guarded by its last observed generation. */
+interface FencedBuildReferenceChange extends BuildReferenceChange {
+  expectedGeneration: number;
+}
+/**
+ * An explicit database capability; an ordinary transaction does not establish this contract.
+ * Implementations serialize admissions, reference changes, and deletion claims across processes.
+ * Their tests must use independent connections, including promotion/purge and pin/purge races.
+ */
+interface BuildReferenceLifecycle {
+  /** Return the durable generation for an owner, or zero before its first reference mutation.
+   * This is a snapshot: callers must pass it to a fenced mutation, which rechecks atomically. */
+  referenceGeneration(owner: BuildReferenceOwner): Promise<number>;
+  /** Atomically fence and replace multiple owners, or roll back all owners and domain writes. */
+  replaceManyFencedReferences<T>(changes: readonly FencedBuildReferenceChange[], writeDomain: (tx: TxStore) => Promise<T>): Promise<{
+    result: T;
+    generations: number[];
+  }>;
+  /** Compare and advance an owner's durable generation with its reference and domain writes.
+   * Generation zero denotes an owner with no earlier mutations. A stale generation rejects the
+   * whole transaction. Generations survive release so an old worker cannot release a newer pin. */
+  replaceFencedReferences<T>(owner: BuildReferenceOwner, expectedGeneration: number, buildIds: readonly string[], writeDomain: (tx: TxStore) => Promise<T>): Promise<{
+    result: T;
+    generation: number;
+  }>;
+  /**
+   * Atomically replace one owner's complete reference set and make its domain writes. Both old and
+   * new builds must be locked in stable order, checked for project ownership and availability,
+   * and committed with the domain mutation. Unknown or tombstoned builds reject admission.
+   */
+  replaceReferences<T>(owner: BuildReferenceOwner, buildIds: readonly string[], writeDomain: (tx: TxStore) => Promise<T>): Promise<T>;
+  /** Atomically replace several owners' reference sets and the shared domain writes. */
+  replaceManyReferences<T>(changes: readonly BuildReferenceChange[], writeDomain: (tx: TxStore) => Promise<T>): Promise<T>;
+  /**
+   * In the same concurrency domain as admissions, irreversibly tombstone a build only if no
+   * protecting reference remains. Existing tombstones are resumable and never become available.
+   * Storage deletion must happen after this operation commits, outside database locks.
+   */
+  claimDeletion(projectId: string, buildId: string): Promise<"claimed" | "protected" | "deleting" | "missing">;
+}
+/** Database-specific metadata: the family plus what the backing platform can carry. */
+interface DatabaseAdapterMetadata {
   readonly category: "database";
-}> {
+  /**
+   * `false` when the database cannot back a deployment with `testing` (ADR 0006, decision 3): it
+   * is reachable only from a platform that ends the process after each request (Cloudflare D1).
+   * Unset means it can.
+   */
+  readonly supportsTesting?: boolean;
+}
+/** Database abstraction over Drizzle tables, agnostic of dialect and driver. */
+interface DatabaseAdapter extends Adapter<DatabaseAdapterMetadata> {
+  /**
+   * Present only when the adapter implements the cross-process retention safety contract.
+   * `transact` by itself is not evidence of this capability.
+   */
+  readonly buildReferenceLifecycle?: BuildReferenceLifecycle;
   /** Table handles for this adapter's dialect, enforced with type safety. */
   readonly tables: Tables;
   /** Insert a row and return the inserted record. */
   insert<T extends Table>(table: T, values: T["$inferInsert"]): Promise<T["$inferSelect"]>;
   /** Update a row by id and return the updated record. */
   update<T extends Table>(table: T, id: string, values: Partial<T["$inferInsert"]>): Promise<T["$inferSelect"]>;
+  /** Atomically update a row only while `where` matches; return the current row, or null if absent.
+   * Custom adapters must implement the condition in the same database statement as the update.
+   */
+  updateWhere<T extends Table>(table: T, id: string, values: Partial<T["$inferInsert"]>, where: SQL): Promise<T["$inferSelect"] | null>;
   /** Fetch a single row by id, or null if not found. */
   get<T extends Table>(table: T, id: string): Promise<T["$inferSelect"] | null>;
   /** Delete a row by id. */
@@ -90,15 +172,12 @@ interface DatabaseAdapter extends Adapter<{
 }
 /** Driver-supplied identity plus lifecycle hooks. */
 interface DrizzleAdapterOptions {
-  metadata: AdapterMetadata & {
-    readonly category: "database";
-  };
+  metadata: AdapterMetadata & DatabaseAdapterMetadata;
   tables: Tables;
   migrate: () => Promise<void> | void;
   close: () => Promise<void> | void;
   /** Cheap liveness probe (e.g. `SELECT 1`); omitted when the driver has none. */
   ping?: () => Promise<void> | void;
 }
-//#endregion
-export { DatabaseAdapter, DrizzleAdapterOptions, ListOptions, MAX_LIST_LIMIT, REQUIRED_TABLE_KEYS, Tables, TxStore, clampListLimit };
+export { BuildReferenceChange, BuildReferenceLifecycle, BuildReferenceOwner, DatabaseAdapter, DatabaseAdapterMetadata, DrizzleAdapterOptions, FencedBuildReferenceChange, ListOptions, MAX_LIST_LIMIT, REQUIRED_TABLE_KEYS, ReferenceGenerationConflict, Tables, TxStore, clampListLimit };
 //# sourceMappingURL=database.d.mts.map