@storyshelf/core 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# @storyshelf/core
+
+The heart of StoryShelf: the Hono router, adapter interfaces, models, capture pipeline, diff engine, and retention logic. Compose pluggable adapters into a complete self-hosted visual testing server.
+
+## Install
+
+```sh
+nub add @storyshelf/core
+```
+
+or
+
+```sh
+npm install @storyshelf/core
+```
+
+## Quick start
+
+```ts
+import { createShelfRouter } from "@storyshelf/core";
+
+const app = createShelfRouter({
+  database,                 // DatabaseAdapter
+  storage,                  // StorageAdapter
+  capture,                  // CaptureRunner (optional)
+  auth,                     // AuthAdapter (optional)
+  status,                   // StatusAdapter (optional)
+  logger,                   // pino Logger (optional; built internally if omitted)
+  ui: { name: "My Shelf" }, // UIConfig (optional)
+  config: { captureConcurrency: 2, purgeTtlDays: 30 }, // ShelfConfig (optional)
+});
+
+// The returned app is a Hono instance; serve it with any Hono adapter.
+serve({ fetch: app.fetch, port: 3000 });
+```
+
+## API
+
+### `createShelfRouter(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. |
+| `capture` | `CaptureRunner` | Optional. Enables the async capture queue. |
+| `auth` | `AuthAdapter` | Optional. Enables auth and the login UI. |
+| `status` | `StatusAdapter` | Optional. Reports CI status checks. |
+| `logger` | `Logger` (pino) | Optional. Shared logger. Construct a fallback via `createShelfLogger()`. |
+| `ui` | `UIConfig` | Optional. UI branding. |
+| `config` | `ShelfConfig` | Optional. Server behavior. |
+
+### `ShelfConfig`
+
+```ts
+interface ShelfConfig {
+  secret?: string;              // session signing secret
+  publishedBaseDomain?: string; // for published storybook URLs
+  captureConcurrency?: number;  // concurrent capture jobs (default 2)
+  purgeTtlDays?: number;        // purge builds older than N days
+  viewports?: Viewport[];       // capture viewports
+}
+```
+
+### `UIConfig`
+
+```ts
+interface UIConfig {
+  name?: string;
+  logo?: string;
+  favicon?: string;
+  lightTheme?: BrandTheme;
+  darkTheme?: BrandTheme;
+}
+```
+
+### Adapter interfaces
+
+All adapters are constructor-injected (no AsyncLocalStorage). See `docs/architecture.md` for the entity model and workflow.
+
+- `DatabaseAdapter` — `insert`, `update`, `get`, `remove`, `list`, `count`, `all`, `migrate`, `close`. Also exports `ListOptions`.
+- `StorageAdapter` — `read`, `write`, `delete`, `exists`, `list(prefix)`.
+- `AuthAdapter` — `check(request)`, `createSession(user)`, `destroySession(sessionId)`, optional `handleCallback(callback)`. Also exports `AuthUser`, `AuthCallback`, and the shared `SESSION_COOKIE`.
+- `CaptureRunner` — a **pure capture renderer**: `render(input) => RenderResult`, `cancel(buildId)`. Also exports `JobStatus`, `RenderedSnapshot`, `RenderResult`.
+- `StatusAdapter` — `setStatus(context, gitSha, status, url)`. Also exports `CheckStatus`.
+
+### Logging
+
+`core` uses **pino** for structured JSON logging. `createShelfLogger({ level, transports, env })` builds a logger writing to stdout by default, with optional extra pino worker transports (Sentry, PostHog, Datadog, GCP, OTEL collector, etc.). Pass the resulting `Logger` to `createShelfRouter({ logger })` (or construct it at your composition root) so request and background logs share one stream. The capture orchestrator derives a `reqId`-scoped child for background capture work, correlating each capture back to the triggering HTTP request. See ADR 0014.
+
+### Capture, diff, and retention
+
+- `executeCaptureJob({ buildId, reqId }, deps)` — 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. `createShelfRouter` wires it into a `CaptureQueue` when `capture` is supplied (and requires `ShelfConfig.scratchDir`). Also exports `CaptureJobOptions`.
+- `persistCapture(ctx: CaptureContext)` — writes screenshots, diffs against the branch baseline, creates snapshots, and finalizes a build from a pure renderer's `captures`. Also exports `CaptureContext` and the `StorySourceAdapter`/`StoryEntry`/`Viewport` types.
+- `StorybookAdapter` — reads a built Storybook's `index.json`/`stories.json`.
+- `diffImages(baseline: Buffer, current: Buffer, options: DiffOptions): DiffResult` — pixelmatch-based diff. Also exports `DiffOptions`, `DiffResult`.
+- `CaptureQueue` — the **capture queue adapter**: `enqueue({ buildId, reqId? })`, plus `status`, `active`, `recent`. `enqueue` returns once a build is queued (async, "queued"); the job runs in a worker. Default is `InMemoryCaptureQueue` (in-process, concurrency-limited, for long-lived hosts); supply a remote queue with a separate worker for serverless. Also exports `CaptureJob`, `QueueEntry`, `JobStatus`.
+- `Retention` — `new Retention(db, storage, logger?)`, with `purge(project, { ttlDays, keepLatestPerBranch })`.
+
+### Helpers
+
+- `createUrlBuilder(baseUrl, publishedBaseDomain?)` — type-safe URL builder. Also exports `UrlBuilder`.
+- `ulid`, `slugify`.
+- Path helpers: `screenshotPath`, `diffPath`, `baselinePath`, `storybookDir`, `storybookZipPath`.
+- `RenderedContent` type for the server-rendered UI.
+
+## How it fits in
+
+`core` is the framework everything else plugs into: `createShelfRouter` takes database, storage, capture, and auth adapters (from the `db-*`, `storage-*`, and `auth-*` packages) and produces a complete Hono server. The web UI is server-rendered `hono/jsx` + HTMX, and custom UIs can consume the JSON API under `/api/v1`.
+
+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 code in the stack is `@hono/node-server` in `@storyshelf/node-server`. You can assemble on any platform:
+
+| Platform | Database | Storage | Capture queue | Server entry |
+|----------|----------|---------|---------------|--------------|
+| **Vercel** | `@storyshelf/db-turso` | `@storyshelf/storage-s3` (R2/S3) | Remote `CaptureQueue` + worker | Hono + `@hono/vercel-edge` |
+| **Cloudflare Workers** | `@storyshelf/db-turso` | `@storyshelf/storage-s3` (R2) | Workers Queues `CaptureQueue` | Hono + Workers entry |
+| **Azure Functions** | `@storyshelf/db-turso` | `@storyshelf/storage-s3` (Blob) | Azure Queues `CaptureQueue` | Hono + Azure handler |
+| **AWS Lambda** | `@storyshelf/db-turso` | `@storyshelf/storage-s3` | SQS `CaptureQueue` | Hono + Lambda handler |
+| **Deno Deploy** | `@storyshelf/db-turso` | `@storyshelf/storage-s3` | Custom `CaptureQueue` (Deno KV) | Hono + Deno entry |
+| **Bun / Node (VPS, Fly, Railway, Render)** | `db-sqlite` / `db-turso` | `storage-local` / `storage-s3` | `InMemoryCaptureQueue` | `storyshelf-server serve` |
+
+All clouds are equal — pick the adapters that match your infrastructure. See the **Deployment** guide for recipes including a minimal Turso + S3 + `InMemoryCaptureQueue` example.

package/dist/adapter/auth.d.mts

@@ -0,0 +1,50 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { AdapterMetadata } from "../adapters/metadata.mjs";
+import { ProjectRole, SiteRole } from "../types.mjs";
+//#region src/adapters/auth.d.ts
+/** Shared session cookie name used by all auth adapters (ADR 0008). */
+declare const SESSION_COOKIE = "storyshelf_session";
+/** An authenticated user of the platform. */
+interface AuthUser {
+  /** User ID. */
+  id: string;
+  /** User email. */
+  email: string;
+  /** Display name. */
+  name: string;
+  /** Optional avatar URL. */
+  avatarUrl?: string;
+  /** Site-wide role. */
+  role: SiteRole;
+}
+/** Data passed to an auth adapter when an OAuth callback is received. */
+interface AuthCallback {
+  /** Provider name. */
+  provider: string;
+  /** Authorization code from the provider. */
+  code: string;
+  /** Anti-CSRF state value. */
+  state: string;
+}
+/** Access controls granted to a user for a specific project. */
+interface ProjectAccess {
+  /** Project role. */
+  role: ProjectRole;
+}
+/** Pluggable authentication abstraction (ADR 0008). */
+interface AuthAdapter {
+  /** Adapter identity. */
+  readonly metadata?: AdapterMetadata;
+  /** Resolve the current user from a request, or null if unauthenticated. */
+  check(request: Request): Promise<AuthUser | null>;
+  /** Create a session for a user and return a session token. */
+  createSession(user: AuthUser): Promise<string>;
+  /** Destroy a session by its id. */
+  destroySession(sessionId: string): Promise<void>;
+  /** Handle an OAuth callback and return the resolved user, if supported. */
+  handleCallback?(callback: AuthCallback): Promise<AuthUser | null>;
+}
+//#endregion
+export { AuthAdapter, AuthCallback, AuthUser, ProjectAccess, SESSION_COOKIE };
+//# sourceMappingURL=auth.d.mts.map

package/dist/adapter/auth.mjs

@@ -0,0 +1,10 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/adapters/auth.ts
+/** Shared session cookie name used by all auth adapters (ADR 0008). */
+const SESSION_COOKIE = "storyshelf_session";
+//#endregion
+export { SESSION_COOKIE };
+
+//# sourceMappingURL=auth.mjs.map

package/dist/adapter/auth.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.mjs","names":[],"sources":["../../src/adapters/auth.ts"],"sourcesContent":["import type { AdapterMetadata } from \"./metadata.ts\";\nimport type { ProjectRole, SiteRole } from \"../types.ts\";\n\n/** Shared session cookie name used by all auth adapters (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\n/** Data passed to an auth adapter when an OAuth callback is received. */\nexport interface AuthCallback {\n  /** Provider name. */\n  provider: string;\n  /** Authorization code from the provider. */\n  code: string;\n  /** Anti-CSRF state value. */\n  state: string;\n}\n\n/** Access controls granted to a user for a specific project. */\nexport interface ProjectAccess {\n  /** Project role. */\n  role: ProjectRole;\n}\n\n/** Pluggable authentication abstraction (ADR 0008). */\nexport interface AuthAdapter {\n  /** Adapter identity. */\n  readonly metadata?: AdapterMetadata;\n  /** Resolve the current user from a request, or null if unauthenticated. */\n  check(request: Request): Promise<AuthUser | null>;\n  /** Create a session for a user and return a session token. */\n  createSession(user: AuthUser): Promise<string>;\n  /** Destroy a session by its id. */\n  destroySession(sessionId: string): Promise<void>;\n  /** Handle an OAuth callback and return the resolved user, if supported. */\n  handleCallback?(callback: AuthCallback): Promise<AuthUser | null>;\n}\n"],"mappings":";;;;;AAIA,MAAa,iBAAiB"}

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

@@ -0,0 +1,70 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { AdapterMetadata } from "../adapters/metadata.mjs";
+import { StoryEntry, Viewport } from "../capture/adapter.mjs";
+import { JobStatus } from "../adapters/capture-queue.mjs";
+import { Logger } from "pino";
+//#region src/adapters/capture-runner.d.ts
+/** A screenshot produced by a capture renderer. */
+interface RenderedSnapshot {
+  /** The rendered story (echoed back from the render request). */
+  story: StoryEntry;
+  /** Viewport name the screenshot was captured at. */
+  viewportName: string;
+  /** PNG screenshot bytes. */
+  screenshot: Buffer;
+}
+/** A story/viewport that a renderer could not capture. */
+interface RenderFailure {
+  /** Story that failed to render. */
+  storyId: string;
+  /** Viewport that failed to render. */
+  viewportName: string;
+  /** Error message. */
+  error: string;
+}
+/** The outcome of a render request. */
+interface RenderResult {
+  /** Screenshots the renderer produced successfully. */
+  captures: RenderedSnapshot[];
+  /** Story/viewport pairs the renderer could not capture. */
+  failures: RenderFailure[];
+}
+/**
+ * A pure capture renderer.
+ *
+ * Adapters implementing `CaptureRunner` render screenshots from an
+ * already-extracted Storybook directory and return PNG buffers. They are
+ * intentionally pure: they perform **no** database, storage, or build-state
+ * management. Loading the build, extracting the uploaded archive, persisting
+ * snapshots/baselines/diffs, and advancing build status are the capture
+ * orchestrator's job (see `capture/orchestrator.ts`), keeping every adapter
+ * implementation free of server concerns.
+ */
+interface CaptureRunner {
+  /** Adapter identity. */
+  readonly metadata?: AdapterMetadata;
+  /**
+   * Render configured viewports for the given stories of an extracted
+   * Storybook and return the screenshot buffers.
+   *
+   * @param input - Render request with the extracted Storybook directory.
+   */
+  render(input: {
+    /** Build being captured, used to correlate cancels with in-flight work. */
+    buildId: string;
+    /** Root of the already-extracted Storybook build. */
+    storybookDir: string;
+    /** Stories to render. */
+    stories: StoryEntry[];
+    /** Viewports to capture. */
+    viewports: Viewport[];
+    /** Optional logger for render-time diagnostics. */
+    logger?: Logger;
+  }): Promise<RenderResult>;
+  /** Cancel a pending or in-flight render for a build. */
+  cancel(buildId: string): Promise<void>;
+}
+//#endregion
+export { CaptureRunner, type JobStatus, RenderFailure, RenderResult, RenderedSnapshot };
+//# sourceMappingURL=capture-runner.d.mts.map

package/dist/adapter/capture-runner.mjs

@@ -0,0 +1,4 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+export {};

package/dist/adapter/database.d.mts

@@ -0,0 +1,43 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { AdapterMetadata } from "../adapters/metadata.mjs";
+import { SQL } from "drizzle-orm";
+import { AnySQLiteTable } from "drizzle-orm/sqlite-core";
+//#region src/adapters/database.d.ts
+/** Options that narrow and page a list query. */
+interface ListOptions {
+  /** SQL WHERE condition. */
+  where?: SQL;
+  /** SQL ORDER BY condition. */
+  orderBy?: SQL;
+  /** Maximum number of rows to return. */
+  limit?: number;
+  /** Number of rows to skip. */
+  offset?: number;
+}
+/** Database abstraction over Drizzle tables, agnostic of the underlying driver. */
+interface DatabaseAdapter {
+  /** Adapter identity. */
+  readonly metadata?: AdapterMetadata;
+  /** Insert a row and return the inserted record. */
+  insert<T extends AnySQLiteTable>(table: T, values: T["$inferInsert"]): Promise<T["$inferSelect"]>;
+  /** Update a row by id and return the updated record. */
+  update<T extends AnySQLiteTable>(table: T, id: string, values: Partial<T["$inferInsert"]>): Promise<T["$inferSelect"]>;
+  /** Fetch a single row by id, or null if not found. */
+  get<T extends AnySQLiteTable>(table: T, id: string): Promise<T["$inferSelect"] | null>;
+  /** Delete a row by id. */
+  remove(table: AnySQLiteTable, id: string): Promise<void>;
+  /** List rows matching the given options. */
+  list<T extends AnySQLiteTable>(table: T, opts?: ListOptions): Promise<T["$inferSelect"][]>;
+  /** Count rows matching an optional where condition. */
+  count(table: AnySQLiteTable, where?: SQL): Promise<number>;
+  /** Run an arbitrary SQL query and return typed rows. */
+  all<T>(query: SQL): Promise<T[]>;
+  /** Apply any pending schema migrations. */
+  migrate(): Promise<void>;
+  /** Close the underlying database connection. */
+  close(): Promise<void>;
+}
+//#endregion
+export { DatabaseAdapter, ListOptions };
+//# sourceMappingURL=database.d.mts.map

package/dist/adapter/database.mjs

@@ -0,0 +1,4 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+export {};

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

@@ -0,0 +1,12 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { CheckStatus } from "../git-host.mjs";
+//#region src/adapters/git-host/helpers.d.ts
+/** Human description for a check status — shared across GitHub/GitLab. */
+declare function describeStatus(status: CheckStatus): string;
+/** Markdown comment body helpers — single comment per build, idempotent via marker. */
+declare function commentMarker(url: string): string;
+declare function buildCommentMarkdown(status: CheckStatus, url: string, context: string): string;
+//#endregion
+export { buildCommentMarkdown, commentMarker, describeStatus };
+//# sourceMappingURL=helpers.d.mts.map

package/dist/adapter/git-host/helpers.mjs

@@ -0,0 +1,29 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/adapters/git-host/helpers.ts
+/** Human description for a check status — shared across GitHub/GitLab. */
+function describeStatus(status) {
+	switch (status) {
+		case "pending": return "Visual tests pending";
+		case "success": return "Visual tests passed";
+		case "failure": return "Visual changes detected or tests failed";
+		default: return "Visual changes detected or tests failed";
+	}
+}
+/** Markdown comment body helpers — single comment per build, idempotent via marker. */
+function commentMarker(url) {
+	return `<!-- storyshelf:${url} -->`;
+}
+function buildCommentMarkdown(status, url, context) {
+	switch (status) {
+		case "pending": return `Visual tests pending for \`${context}\` — [View build](${url})`;
+		case "success": return `Visual tests passed for \`${context}\` — [View build](${url})`;
+		case "failure": return `Visual changes detected for \`${context}\` — [View build](${url})`;
+		default: return `Visual tests \`${status}\` for \`${context}\` — [View build](${url})`;
+	}
+}
+//#endregion
+export { buildCommentMarkdown, commentMarker, describeStatus };
+
+//# sourceMappingURL=helpers.mjs.map

package/dist/adapter/git-host/helpers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.mjs","names":[],"sources":["../../../src/adapters/git-host/helpers.ts"],"sourcesContent":["import type { CheckStatus } from \"./index.ts\";\n\n/** Human description for a check status — shared across GitHub/GitLab. */\nexport function describeStatus(status: CheckStatus): string {\n  switch (status) {\n    case \"pending\": {\n      return \"Visual tests pending\";\n    }\n    case \"success\": {\n      return \"Visual tests passed\";\n    }\n    case \"failure\": {\n      return \"Visual changes detected or tests failed\";\n    }\n    default: {\n      return \"Visual changes detected or tests failed\";\n    }\n  }\n}\n\n/** Markdown comment body helpers — single comment per build, idempotent via marker. */\nexport function commentMarker(url: string): string {\n  return `<!-- storyshelf:${url} -->`;\n}\n\nexport function buildCommentMarkdown(status: CheckStatus, url: string, context: string): string {\n  switch (status) {\n    case \"pending\": {\n      return `Visual tests pending for \\`${context}\\` — [View build](${url})`;\n    }\n    case \"success\": {\n      return `Visual tests passed for \\`${context}\\` — [View build](${url})`;\n    }\n    case \"failure\": {\n      return `Visual changes detected for \\`${context}\\` — [View build](${url})`;\n    }\n    default: {\n      // eslint-disable-next-line restrict-template-expressions -- status is never in default case\n      return `Visual tests \\`${status}\\` for \\`${context}\\` — [View build](${url})`;\n    }\n  }\n}\n"],"mappings":";;;;;AAGA,SAAgB,eAAe,QAA6B;CAC1D,QAAQ,QAAR;EACE,KAAK,WACH,OAAO;EAET,KAAK,WACH,OAAO;EAET,KAAK,WACH,OAAO;EAET,SACE,OAAO;CAEX;AACF;;AAGA,SAAgB,cAAc,KAAqB;CACjD,OAAO,mBAAmB,IAAI;AAChC;AAEA,SAAgB,qBAAqB,QAAqB,KAAa,SAAyB;CAC9F,QAAQ,QAAR;EACE,KAAK,WACH,OAAO,8BAA8B,QAAQ,oBAAoB,IAAI;EAEvE,KAAK,WACH,OAAO,6BAA6B,QAAQ,oBAAoB,IAAI;EAEtE,KAAK,WACH,OAAO,iCAAiC,QAAQ,oBAAoB,IAAI;EAE1E,SAEE,OAAO,kBAAkB,OAAO,WAAW,QAAQ,oBAAoB,IAAI;CAE/E;AACF"}

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

@@ -0,0 +1,46 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { GitAdapterMetadata } from "../adapters/metadata.mjs";
+import { Logger } from "pino";
+//#region src/adapters/git-host/index.d.ts
+/** Status of a git-host provider check. */
+type CheckStatus = "pending" | "success" | "failure";
+/** Descriptor — registered at startup, validates per-project config. */
+interface GitHostProvider {
+  /** Adapter identity (name, version, description, kind="github", logo, schema). */
+  readonly metadata: GitAdapterMetadata;
+  /** Create a configured instance bound to a project config + decrypted token. */
+  create(opts: {
+    config: unknown;
+    token: string;
+    logger?: Logger;
+  }): GitHostAdapter;
+}
+/** Runtime — bound to a project config + token, posts statuses/comments. */
+interface GitHostAdapter {
+  /** Adapter identity. */
+  readonly metadata: GitAdapterMetadata;
+  /** Set the status of a commit. */
+  setStatus(opts: {
+    context: string;
+    gitSha: string;
+    status: CheckStatus;
+    url: string;
+  }): Promise<void>;
+  /** Whether the branch/sha is already merged — gate to skip capture. */
+  isMerged?(opts: {
+    sha: string;
+    branch: string;
+  }): Promise<boolean>;
+  /** Create or update a single PR comment per build (idempotent via url marker). */
+  upsertComment?(opts: {
+    prNumber?: number;
+    sha: string;
+    url: string;
+    status: CheckStatus;
+    markdown: string;
+  }): Promise<string>;
+}
+//#endregion
+export { CheckStatus, GitHostAdapter, GitHostProvider };
+//# sourceMappingURL=git-host.d.mts.map

package/dist/adapter/git-host.mjs

@@ -0,0 +1,4 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+export {};

package/dist/adapter/storage.d.mts

@@ -0,0 +1,22 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { AdapterMetadata } from "../adapters/metadata.mjs";
+//#region src/adapters/storage.d.ts
+/** Blob storage abstraction for screenshots, diffs and Storybook archives. */
+interface StorageAdapter {
+  /** Adapter identity. */
+  readonly metadata?: AdapterMetadata;
+  /** Read the bytes stored at `path`. */
+  read(path: string): Promise<Buffer>;
+  /** Write `data` to `path`, creating parent directories as needed. */
+  write(path: string, data: Buffer): Promise<void>;
+  /** Delete the object at `path` if it exists. */
+  delete(path: string): Promise<void>;
+  /** Return whether an object exists at `path`. */
+  exists(path: string): Promise<boolean>;
+  /** List object paths under the given key prefix. */
+  list(prefix: string): Promise<string[]>;
+}
+//#endregion
+export { StorageAdapter };
+//# sourceMappingURL=storage.d.mts.map

package/dist/adapter/storage.mjs

@@ -0,0 +1,4 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+export {};

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

@@ -0,0 +1,49 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { AdapterMetadata } from "./metadata.mjs";
+//#region src/adapters/capture-queue.d.ts
+type JobStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+interface QueueEntry {
+  buildId: string;
+  status: JobStatus;
+  queuedAt: string;
+  startedAt?: string;
+  finishedAt?: string;
+  error?: string;
+}
+/** A build submitted for capture. */
+interface CaptureJob {
+  buildId: string;
+  /** Request id used to correlate the background job with the request that queued it. */
+  reqId?: string;
+}
+/**
+ * A capture job queue, decoupled from the runtime.
+ *
+ * `enqueue` submits a build for capture and returns quickly; the build is
+ * tracked as "queued". The capture itself runs in a worker:
+ *
+ * - the in-memory implementation (`InMemoryCaptureQueue`, in
+ *   `capture/capture-queue.ts`) runs the job in-process on a long-lived
+ *   Node server;
+ * - a remote implementation (e.g. SQS, Cloudflare Queues, Azure Storage
+ *   Queues) pushes the job and leaves execution to a separately-assembled
+ *   worker that polls the queue and runs `executeCaptureJob`.
+ *
+ * `status`/`active`/`recent` back the live queue view regardless of transport.
+ */
+interface CaptureQueue {
+  /** Adapter identity. */
+  readonly metadata?: AdapterMetadata;
+  /** Submit a build for capture. Resolves once the build is queued. */
+  enqueue(job: CaptureJob): Promise<void>;
+  /** Return the current status entry for a build, or null if untracked. */
+  status(buildId: string): Promise<QueueEntry | null>;
+  /** Queue entries that are queued or running. */
+  active(): Promise<QueueEntry[]>;
+  /** The most recent queue entries, newest first. */
+  recent(limit: number): Promise<QueueEntry[]>;
+}
+//#endregion
+export { CaptureJob, CaptureQueue, JobStatus, QueueEntry };
+//# sourceMappingURL=capture-queue.d.mts.map

package/dist/adapters/metadata.d.mts

@@ -0,0 +1,24 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { z } from "zod";
+//#region src/adapters/metadata.d.ts
+/** Common adapter identity — every adapter instance exposes this. */
+interface AdapterMetadata {
+  /** Human label for UI/logs. */
+  readonly name: string;
+  /** Package version injected at build via __PKG_VERSION__. */
+  readonly version: string;
+  /** Optional short description. */
+  readonly description?: string;
+  /** Machine key (e.g. "github", "sqlite", "local", "s3", "password", "oauth", "playwright", "sqs", "memory"). */
+  readonly kind: string;
+}
+/** Git-specific metadata extension (adds logo + validation schema). */
+interface GitAdapterMetadata extends AdapterMetadata {
+  readonly kind: string;
+  readonly logo?: string;
+  readonly schema: z.ZodType;
+}
+//#endregion
+export { AdapterMetadata, GitAdapterMetadata };
+//# sourceMappingURL=metadata.d.mts.map

package/dist/adapters/webhook-events.mjs

@@ -0,0 +1,39 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { hmacSha256 } from "../utils/hash.mjs";
+import { WebhookModel } from "../models/webhook.mjs";
+//#region src/adapters/webhook-events.ts
+async function sendWebhook(url, secret, event) {
+	const body = JSON.stringify(event);
+	const signature = hmacSha256(secret, body);
+	await fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"X-StoryShelf-Event": event.event,
+			"X-StoryShelf-Signature": signature
+		},
+		body
+	});
+}
+async function emitWebhookEvent(db, projectId, event, data) {
+	const webhooks = await new WebhookModel(db).list(projectId);
+	const eventPayload = {
+		event,
+		projectId,
+		data,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	await Promise.allSettled(webhooks.map(async (webhook) => {
+		const events = WebhookModel.eventsOf(webhook);
+		if (events.length > 0 && !events.includes(event)) return;
+		try {
+			await sendWebhook(webhook.url, webhook.secret, eventPayload);
+		} catch {}
+	}));
+}
+//#endregion
+export { emitWebhookEvent };
+
+//# sourceMappingURL=webhook-events.mjs.map

package/dist/adapters/webhook-events.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-events.mjs","names":[],"sources":["../../src/adapters/webhook-events.ts"],"sourcesContent":["import type { DatabaseAdapter } from \"./database.ts\";\nimport { WebhookModel } from \"../models/webhook.ts\";\nimport { hmacSha256 } from \"../utils/hash.ts\";\n\nexport interface WebhookEvent {\n  event: string;\n  projectId: string;\n  data: Record<string, unknown>;\n  timestamp: string;\n}\n\nasync function sendWebhook(url: string, secret: string, event: WebhookEvent): Promise<void> {\n  const body = JSON.stringify(event);\n  const signature = hmacSha256(secret, body);\n  await fetch(url, {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application/json\",\n      \"X-StoryShelf-Event\": event.event,\n      \"X-StoryShelf-Signature\": signature,\n    },\n    body,\n  });\n}\n\nexport async function emitWebhookEvent(\n  db: DatabaseAdapter,\n  projectId: string,\n  event: string,\n  data: Record<string, unknown>,\n): Promise<void> {\n  const webhookModel = new WebhookModel(db);\n  const webhooks = await webhookModel.list(projectId);\n  const eventPayload: WebhookEvent = {\n    event,\n    projectId,\n    data,\n    timestamp: new Date().toISOString(),\n  };\n\n  await Promise.allSettled(\n    webhooks.map(async (webhook) => {\n      const events = WebhookModel.eventsOf(webhook);\n      if (events.length > 0 && !events.includes(event)) {\n        return;\n      }\n      try {\n        await sendWebhook(webhook.url, webhook.secret, eventPayload);\n      } catch {\n        // webhook delivery failures are non-fatal\n      }\n    }),\n  );\n}\n"],"mappings":";;;;;;AAWA,eAAe,YAAY,KAAa,QAAgB,OAAoC;CAC1F,MAAM,OAAO,KAAK,UAAU,KAAK;CACjC,MAAM,YAAY,WAAW,QAAQ,IAAI;CACzC,MAAM,MAAM,KAAK;EACf,QAAQ;EACR,SAAS;GACP,gBAAgB;GAChB,sBAAsB,MAAM;GAC5B,0BAA0B;EAC5B;EACA;CACF,CAAC;AACH;AAEA,eAAsB,iBACpB,IACA,WACA,OACA,MACe;CAEf,MAAM,WAAW,MAAM,IADE,aAAa,EACJ,CAAC,CAAC,KAAK,SAAS;CAClD,MAAM,eAA6B;EACjC;EACA;EACA;EACA,4BAAW,IAAI,KAAK,EAAA,CAAE,YAAY;CACpC;CAEA,MAAM,QAAQ,WACZ,SAAS,IAAI,OAAO,YAAY;EAC9B,MAAM,SAAS,aAAa,SAAS,OAAO;EAC5C,IAAI,OAAO,SAAS,KAAK,CAAC,OAAO,SAAS,KAAK,GAC7C;EAEF,IAAI;GACF,MAAM,YAAY,QAAQ,KAAK,QAAQ,QAAQ,YAAY;EAC7D,QAAQ,CAER;CACF,CAAC,CACH;AACF"}

package/dist/capture/adapter.d.mts

@@ -0,0 +1,29 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/capture/adapter.d.ts
+/** A single discoverable story or docs entry within a Storybook. */
+interface StoryEntry {
+  id: string;
+  title: string;
+  name: string;
+  importPath?: string;
+  tags?: string[];
+  type: "story" | "docs";
+}
+/** Adapter that discovers and renders stories from a Storybook build. */
+interface StorySourceAdapter {
+  name: string;
+  discover(source: string): Promise<StoryEntry[]>;
+  buildUrl(baseUrl: string, storyId: string): string;
+  screenshotSelector?: string;
+}
+/** A viewport size at which stories are captured. */
+interface Viewport {
+  name: string;
+  width: number;
+  height: number;
+}
+declare const DEFAULT_VIEWPORTS: Viewport[];
+//#endregion
+export { DEFAULT_VIEWPORTS, StoryEntry, StorySourceAdapter, Viewport };
+//# sourceMappingURL=adapter.d.mts.map

package/dist/capture/adapter.mjs

@@ -0,0 +1,13 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/capture/adapter.ts
+const DEFAULT_VIEWPORTS = [{
+	name: "desktop",
+	width: 1280,
+	height: 720
+}];
+//#endregion
+export { DEFAULT_VIEWPORTS };
+
+//# sourceMappingURL=adapter.mjs.map

package/dist/capture/adapter.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.mjs","names":[],"sources":["../../src/capture/adapter.ts"],"sourcesContent":["/** A single discoverable story or docs entry within a Storybook. */\nexport interface StoryEntry {\n  id: string;\n  title: string;\n  name: string;\n  importPath?: string;\n  tags?: string[];\n  type: \"story\" | \"docs\";\n}\n\n/** Adapter that discovers and renders stories from a Storybook build. */\nexport interface StorySourceAdapter {\n  name: string;\n  discover(source: string): Promise<StoryEntry[]>;\n  buildUrl(baseUrl: string, storyId: string): string;\n  screenshotSelector?: string;\n}\n\n/** A viewport size at which stories are captured. */\nexport interface Viewport {\n  name: string;\n  width: number;\n  height: number;\n}\n\nexport const DEFAULT_VIEWPORTS: Viewport[] = [{ name: \"desktop\", width: 1280, height: 720 }];\n"],"mappings":";;;;AAyBA,MAAa,oBAAgC,CAAC;CAAE,MAAM;CAAW,OAAO;CAAM,QAAQ;AAAI,CAAC"}

package/dist/capture/orchestrator.d.mts

@@ -0,0 +1,23 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Viewport } from "./adapter.mjs";
+import { CaptureRunner } from "../adapter/capture-runner.mjs";
+import { DatabaseAdapter } from "../adapter/database.mjs";
+import { StorageAdapter } from "../adapter/storage.mjs";
+import { Logger } from "pino";
+//#region src/capture/orchestrator.d.ts
+interface CaptureJobOptions {
+  db: DatabaseAdapter;
+  storage: StorageAdapter;
+  runner: CaptureRunner;
+  scratchDir: string;
+  viewports?: Viewport[];
+  logger?: Logger;
+}
+declare function executeCaptureJob(input: {
+  buildId: string;
+  reqId?: string;
+}, options: CaptureJobOptions): Promise<void>;
+//#endregion
+export { CaptureJobOptions, executeCaptureJob };
+//# sourceMappingURL=orchestrator.d.mts.map