@storyshelf/core 0.3.2 → 0.5.3

package/dist/auth.d.mts

@@ -0,0 +1,94 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { AuthUser } from "./types.mjs";
+//#region src/auth.d.ts
+/** Login widget kinds in display order (the shelf plugin contract). */
+type EngineLoginMethodKind = "password" | "oauth" | "passkey" | "sso";
+/**
+ * One login widget on the descriptor-driven login page.
+ *
+ * Plugin contract: `password` posts the credential form to
+ * `/auth/engine/login`; `oauth`/`sso` link at `/auth/engine/:id` (the app
+ * starts the provider flow server-side); `passkey` is JS-driven on the page
+ * (its `url` is an unused fallback). Method ids must be unique across all
+ * providers (checked at boot).
+ */
+interface EngineLoginMethod {
+  kind: EngineLoginMethodKind;
+  id: string;
+  label: string;
+}
+/** One device session for the profile device list. */
+interface EngineSessionInfo {
+  id: string;
+  token: string;
+  ipAddress: string | null;
+  userAgent: string | null;
+  createdAt: string;
+  expiresAt: string;
+}
+/** One registered passkey for the profile page. */
+interface EnginePasskeyInfo {
+  id: string;
+  name: string | null;
+  deviceType: string;
+  backedUp: boolean;
+  transports: string | null;
+  aaguid: string | null;
+  createdAt: string;
+}
+/** Auth singleton: the shelf authentication surface (not an adapter). */
+interface Auth {
+  /** Raw engine handler (mount at `/api/auth/*`). */
+  handler: (request: Request) => Response | Promise<Response>;
+  /** Login methods in display order (drives the login page). */
+  loginMethods: () => EngineLoginMethod[];
+  /** One-shot boot validation (secret strength); the app calls it directly. */
+  setup: () => Promise<void>;
+  /** Stage a shelf user and mint a single-use invite token. */
+  issueInvite: (input: {
+    email: string;
+    name: string;
+    role: AuthUser["role"];
+  }) => Promise<{
+    inviteId: string;
+    token: string;
+    expiresAt: string;
+  }>;
+  /** Check an invite token without consuming it (drives the accept page). */
+  verifyInvite: (input: {
+    inviteId: string;
+    token: string;
+  }) => Promise<{
+    email: string;
+    name: string;
+  }>;
+  /** Consume an invite: set the engine credential and return the shelf user. */
+  acceptInvite: (input: {
+    inviteId: string;
+    token: string;
+    password: string;
+  }) => Promise<AuthUser>;
+  /** Whether WebAuthn passkeys are enabled (drives the profile section). */
+  passkeysEnabled: () => boolean;
+  /** Active device sessions for the profile page (newest first). */
+  listSessions: (userId: string) => Promise<EngineSessionInfo[]>;
+  /** Registered passkeys for the profile page (oldest first). */
+  listPasskeys: (userId: string) => Promise<EnginePasskeyInfo[]>;
+  /** Whether the user has a local credential (shows the password form). */
+  hasPassword: (userId: string) => Promise<boolean>;
+  /**
+   * Disable or re-enable a user: flips the shelf flag and eagerly revokes
+   * every engine session (the per-request check is the backstop).
+   */
+  setDisabled: (userId: string, disabled: boolean) => Promise<void>;
+  /** Resolve the session user from a request (null when anonymous). */
+  check: (request: Request) => Promise<AuthUser | null>;
+  /** Forbidden by design: sessions mint at engine endpoints, never here. */
+  createSession: (user: AuthUser) => Promise<string>;
+  /** Revoke one session by token (accepts the signed cookie value). */
+  destroySession: (sessionToken: string) => Promise<void>;
+}
+//#endregion
+export { Auth, EngineLoginMethod, EngineLoginMethodKind, EnginePasskeyInfo, EngineSessionInfo };
+//# sourceMappingURL=auth.d.mts.map

package/dist/auth.mjs

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

package/dist/brand-packs.d.mts

@@ -0,0 +1,16 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { BrandTheme } from "./config.mjs";
+//#region src/brand-packs.d.ts
+/** One named light/dark theme pair. */
+interface BrandPack {
+  light: BrandTheme;
+  dark: BrandTheme;
+}
+/** Curated brand packs keyed by name (`storyshelf` is the default look). */
+declare const brandPacks: Record<string, BrandPack>;
+/** Look up a brand pack by name (undefined for unknown names). */
+declare function brandPack(name: string): BrandPack | undefined;
+//#endregion
+export { BrandPack, brandPack, brandPacks };
+//# sourceMappingURL=brand-packs.d.mts.map

package/dist/brand-packs.mjs

@@ -0,0 +1,130 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+/** Curated brand packs keyed by name (`storyshelf` is the default look). */
+const brandPacks = {
+	storyshelf: {
+		light: {
+			accent: "#1d5fcf",
+			accentContrast: "#ffffff",
+			ring: "#1d5fcf",
+			surface: {
+				base: "#fafafa",
+				card: "#ffffff",
+				muted: "#f4f4f5",
+				subtle: "#fafafa"
+			},
+			text: {
+				primary: "#09090b",
+				secondary: "#5b5b64",
+				muted: "#6a6a73"
+			},
+			border: "#e4e4e7",
+			borderSubtle: "#f4f4f5",
+			status: {
+				approved: "#16a34a",
+				new: "#d97706",
+				rejected: "#dc2626"
+			},
+			sidebarBg: "#ffffff",
+			topbarBg: "#1d5fcf",
+			radius: "0.5rem",
+			radiusSm: "0.375rem",
+			shadow: "0 1px 2px rgba(0,0,0,.04)"
+		},
+		dark: {
+			accent: "#4f8fff",
+			accentContrast: "#09090b",
+			ring: "#4f8fff",
+			surface: {
+				base: "#09090b",
+				card: "#111113",
+				muted: "#27272a",
+				subtle: "#18181b"
+			},
+			text: {
+				primary: "#fafafa",
+				secondary: "#a1a1aa",
+				muted: "#8a8a94"
+			},
+			border: "#27272a",
+			borderSubtle: "#1e1e22",
+			status: {
+				approved: "#22c55e",
+				new: "#f59e0b",
+				rejected: "#ef4444"
+			},
+			sidebarBg: "#111113",
+			topbarBg: "#0f172a",
+			radius: "0.5rem",
+			radiusSm: "0.375rem",
+			shadow: "0 1px 2px rgba(0,0,0,.3)"
+		}
+	},
+	ocean: {
+		light: {
+			accent: "#0e7490",
+			accentContrast: "#ffffff",
+			ring: "#0e7490",
+			surface: {
+				base: "#faf7f0",
+				card: "#ffffff",
+				muted: "#f1ece1",
+				subtle: "#faf7f0"
+			},
+			text: {
+				primary: "#1c1917",
+				secondary: "#78716c",
+				muted: "#a8a29e"
+			},
+			border: "#e7e0d2",
+			borderSubtle: "#f1ece1",
+			status: {
+				approved: "#16a34a",
+				new: "#d97706",
+				rejected: "#dc2626"
+			},
+			sidebarBg: "#ffffff",
+			topbarBg: "#0e7490",
+			radius: "0.5rem",
+			radiusSm: "0.375rem",
+			shadow: "0 1px 2px rgba(0,0,0,.04)"
+		},
+		dark: {
+			accent: "#22d3ee",
+			accentContrast: "#082f36",
+			ring: "#22d3ee",
+			surface: {
+				base: "#081014",
+				card: "#0e1a21",
+				muted: "#1d303b",
+				subtle: "#101e25"
+			},
+			text: {
+				primary: "#f0f9fa",
+				secondary: "#93a7b0",
+				muted: "#5d747e"
+			},
+			border: "#1d303b",
+			borderSubtle: "#14242c",
+			status: {
+				approved: "#22c55e",
+				new: "#f59e0b",
+				rejected: "#ef4444"
+			},
+			sidebarBg: "#0e1a21",
+			topbarBg: "#082f36",
+			radius: "0.5rem",
+			radiusSm: "0.375rem",
+			shadow: "0 1px 2px rgba(0,0,0,.3)"
+		}
+	}
+};
+/** Look up a brand pack by name (undefined for unknown names). */
+function brandPack(name) {
+	return brandPacks[name];
+}
+//#endregion
+export { brandPack, brandPacks };
+
+//# sourceMappingURL=brand-packs.mjs.map

package/dist/brand-packs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand-packs.mjs","names":[],"sources":["../src/brand-packs.ts"],"sourcesContent":["/**\n * Brand packs: curated light/dark theme pairs for `UIConfig`.\n *\n * Drop one into the server options (`ui: { ...brandPacks.ocean }`) instead\n * of hand-rolling every token. Packs carry full `BrandTheme` pairs so both\n * color schemes stay coherent; every pack validates against\n * {@link uiConfigSchema}.\n */\nimport type { BrandTheme } from \"./config.ts\";\n\n/** One named light/dark theme pair. */\nexport interface BrandPack {\n  light: BrandTheme;\n  dark: BrandTheme;\n}\n\n/** Default StoryShelf look (matches the built-in UI themes). */\nconst storyshelf: BrandPack = {\n  light: {\n    accent: \"#1d5fcf\",\n    accentContrast: \"#ffffff\",\n    ring: \"#1d5fcf\",\n    surface: { base: \"#fafafa\", card: \"#ffffff\", muted: \"#f4f4f5\", subtle: \"#fafafa\" },\n    text: { primary: \"#09090b\", secondary: \"#5b5b64\", muted: \"#6a6a73\" },\n    border: \"#e4e4e7\",\n    borderSubtle: \"#f4f4f5\",\n    status: { approved: \"#16a34a\", new: \"#d97706\", rejected: \"#dc2626\" },\n    sidebarBg: \"#ffffff\",\n    topbarBg: \"#1d5fcf\",\n    radius: \"0.5rem\",\n    radiusSm: \"0.375rem\",\n    shadow: \"0 1px 2px rgba(0,0,0,.04)\",\n  },\n  dark: {\n    accent: \"#4f8fff\",\n    accentContrast: \"#09090b\",\n    ring: \"#4f8fff\",\n    surface: { base: \"#09090b\", card: \"#111113\", muted: \"#27272a\", subtle: \"#18181b\" },\n    text: { primary: \"#fafafa\", secondary: \"#a1a1aa\", muted: \"#8a8a94\" },\n    border: \"#27272a\",\n    borderSubtle: \"#1e1e22\",\n    status: { approved: \"#22c55e\", new: \"#f59e0b\", rejected: \"#ef4444\" },\n    sidebarBg: \"#111113\",\n    topbarBg: \"#0f172a\",\n    radius: \"0.5rem\",\n    radiusSm: \"0.375rem\",\n    shadow: \"0 1px 2px rgba(0,0,0,.3)\",\n  },\n};\n\n/** Deep teal on warm paper (light) / abyss (dark). */\nconst ocean: BrandPack = {\n  light: {\n    accent: \"#0e7490\",\n    accentContrast: \"#ffffff\",\n    ring: \"#0e7490\",\n    surface: { base: \"#faf7f0\", card: \"#ffffff\", muted: \"#f1ece1\", subtle: \"#faf7f0\" },\n    text: { primary: \"#1c1917\", secondary: \"#78716c\", muted: \"#a8a29e\" },\n    border: \"#e7e0d2\",\n    borderSubtle: \"#f1ece1\",\n    status: { approved: \"#16a34a\", new: \"#d97706\", rejected: \"#dc2626\" },\n    sidebarBg: \"#ffffff\",\n    topbarBg: \"#0e7490\",\n    radius: \"0.5rem\",\n    radiusSm: \"0.375rem\",\n    shadow: \"0 1px 2px rgba(0,0,0,.04)\",\n  },\n  dark: {\n    accent: \"#22d3ee\",\n    accentContrast: \"#082f36\",\n    ring: \"#22d3ee\",\n    surface: { base: \"#081014\", card: \"#0e1a21\", muted: \"#1d303b\", subtle: \"#101e25\" },\n    text: { primary: \"#f0f9fa\", secondary: \"#93a7b0\", muted: \"#5d747e\" },\n    border: \"#1d303b\",\n    borderSubtle: \"#14242c\",\n    status: { approved: \"#22c55e\", new: \"#f59e0b\", rejected: \"#ef4444\" },\n    sidebarBg: \"#0e1a21\",\n    topbarBg: \"#082f36\",\n    radius: \"0.5rem\",\n    radiusSm: \"0.375rem\",\n    shadow: \"0 1px 2px rgba(0,0,0,.3)\",\n  },\n};\n\n/** Curated brand packs keyed by name (`storyshelf` is the default look). */\nexport const brandPacks: Record<string, BrandPack> = { storyshelf, ocean };\n\n/** Look up a brand pack by name (undefined for unknown names). */\nexport function brandPack(name: string): BrandPack | undefined {\n  return brandPacks[name];\n}\n"],"mappings":";;;;AAqFA,MAAa,aAAwC;CAAE;EAnErD,OAAO;GACL,QAAQ;GACR,gBAAgB;GAChB,MAAM;GACN,SAAS;IAAE,MAAM;IAAW,MAAM;IAAW,OAAO;IAAW,QAAQ;GAAU;GACjF,MAAM;IAAE,SAAS;IAAW,WAAW;IAAW,OAAO;GAAU;GACnE,QAAQ;GACR,cAAc;GACd,QAAQ;IAAE,UAAU;IAAW,KAAK;IAAW,UAAU;GAAU;GACnE,WAAW;GACX,UAAU;GACV,QAAQ;GACR,UAAU;GACV,QAAQ;EACV;EACA,MAAM;GACJ,QAAQ;GACR,gBAAgB;GAChB,MAAM;GACN,SAAS;IAAE,MAAM;IAAW,MAAM;IAAW,OAAO;IAAW,QAAQ;GAAU;GACjF,MAAM;IAAE,SAAS;IAAW,WAAW;IAAW,OAAO;GAAU;GACnE,QAAQ;GACR,cAAc;GACd,QAAQ;IAAE,UAAU;IAAW,KAAK;IAAW,UAAU;GAAU;GACnE,WAAW;GACX,UAAU;GACV,QAAQ;GACR,UAAU;GACV,QAAQ;EACV;CAsCqD;CAAY;EAjCjE,OAAO;GACL,QAAQ;GACR,gBAAgB;GAChB,MAAM;GACN,SAAS;IAAE,MAAM;IAAW,MAAM;IAAW,OAAO;IAAW,QAAQ;GAAU;GACjF,MAAM;IAAE,SAAS;IAAW,WAAW;IAAW,OAAO;GAAU;GACnE,QAAQ;GACR,cAAc;GACd,QAAQ;IAAE,UAAU;IAAW,KAAK;IAAW,UAAU;GAAU;GACnE,WAAW;GACX,UAAU;GACV,QAAQ;GACR,UAAU;GACV,QAAQ;EACV;EACA,MAAM;GACJ,QAAQ;GACR,gBAAgB;GAChB,MAAM;GACN,SAAS;IAAE,MAAM;IAAW,MAAM;IAAW,OAAO;IAAW,QAAQ;GAAU;GACjF,MAAM;IAAE,SAAS;IAAW,WAAW;IAAW,OAAO;GAAU;GACnE,QAAQ;GACR,cAAc;GACd,QAAQ;IAAE,UAAU;IAAW,KAAK;IAAW,UAAU;GAAU;GACnE,WAAW;GACX,UAAU;GACV,QAAQ;GACR,UAAU;GACV,QAAQ;EACV;CAIiE;AAAM;;AAGzE,SAAgB,UAAU,MAAqC;CAC7D,OAAO,WAAW;AACpB"}

package/dist/capture/adapter.d.mts

@@ -1,6 +1,20 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
+import { DepGraph } from "@storyshelf/affected";
 //#region src/capture/adapter.d.ts
+/** A custom viewport registered on a story via `parameters.viewport`. */
+interface StoryViewportDefinition {
+  name?: string;
+  styles?: {
+    width?: string | number;
+    height?: string | number;
+  };
+}
+/** Storybook `parameters.viewport` config; carried through discovery for per-story viewport capture. */
+interface StoryViewportConfig {
+  defaultViewport?: string;
+  viewports?: Record<string, StoryViewportDefinition>;
+}
 /** Per-story capture parameters from the Storybook index. */
 interface StoryParameters {
   disableSnapshot?: boolean;
@@ -8,6 +22,23 @@ interface StoryParameters {
   diffThreshold?: number;
   pauseAnimationAtEnd?: boolean;
   flakyTest?: boolean;
+  /** Force auto-crop (true) or full viewport (false) for this story; undefined uses 60% whitespace rule. */
+  autoCrop?: boolean;
+  /** Whitespace fraction (0..1) above which we crop; default 0.6. */
+  autoCropThreshold?: number;
+  /** Whether overflow should trigger fullPage; default true. */
+  fullPageOnOverflow?: boolean;
+  /** Min dimensions for the final PNG (clamp after padding). */
+  minWidth?: number;
+  minHeight?: number;
+  maxWidth?: number;
+  maxHeight?: number;
+  /** Burst count for steady capture (1 = single shot, 3 = burst 100ms); default 1. */
+  burst?: number;
+  /** Whether to wait for fonts.ready before screenshot; default true when burst >1. */
+  waitForFonts?: boolean;
+  /** Storybook viewport config; adds the story's default viewport to the project list at capture time. */
+  viewport?: StoryViewportConfig;
 }
 /** Return whether a story is marked flaky (failures stay non-blocking). */
 declare function isFlakyStory(entry: Pick<StoryEntry, "tags" | "parameters">): boolean;
@@ -23,12 +54,31 @@ interface StoryEntry {
   type: "story" | "docs";
   parameters?: StoryParameters;
 }
+/** Minimal structural page handle handed to `StorySourceAdapter.waitForReady`. */
+interface CapturePage {
+  evaluate(pageFunction: string | ((...args: unknown[]) => unknown), arg?: unknown): Promise<unknown>;
+  waitForSelector(selector: string, options?: Record<string, unknown>): Promise<unknown>;
+}
 /** 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;
+  /**
+   * Optional hook loading the module dependency graph of an extracted build,
+   * enabling affected capture (render only stories downstream of a change).
+   * Absent (or resolving `null`) means the source cannot be traced, so the
+   * orchestrator renders every story.
+   */
+  loadDependencyGraph?(sourceDir: string): Promise<DepGraph | null>;
+  /**
+   * Optional hook invoked after navigation and before the screenshot sequence,
+   * letting a custom source wait until it is ready to capture. The built-in
+   * Storybook adapter leaves this undefined (rendered via iframe). See
+   * ADR 0005.
+   */
+  waitForReady?(page: CapturePage): Promise<void>;
 }
 /** A viewport size at which stories are captured. */
 interface Viewport {
@@ -39,5 +89,5 @@ interface Viewport {
 /** Default viewport used when none is configured. */
 declare const DEFAULT_VIEWPORTS: Viewport[];
 //#endregion
-export { DEFAULT_VIEWPORTS, StoryEntry, StoryParameters, StorySourceAdapter, Viewport, isDisabledStory, isFlakyStory };
+export { CapturePage, DEFAULT_VIEWPORTS, StoryEntry, StoryParameters, StorySourceAdapter, StoryViewportConfig, StoryViewportDefinition, Viewport, isDisabledStory, isFlakyStory };
 //# sourceMappingURL=adapter.d.mts.map

package/dist/capture/adapter.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.mjs","names":[],"sources":["../../src/capture/adapter.ts"],"sourcesContent":["/** Per-story capture parameters from the Storybook index. */\nexport interface StoryParameters {\n  disableSnapshot?: boolean;\n  delay?: number;\n  diffThreshold?: number;\n  pauseAnimationAtEnd?: boolean;\n  flakyTest?: boolean;\n}\n\n/** Return whether a story is marked flaky (failures stay non-blocking). */\nexport function isFlakyStory(entry: Pick<StoryEntry, \"tags\" | \"parameters\">): boolean {\n  if (entry.parameters?.flakyTest) return true;\n  const tags = entry.tags ?? [];\n  for (const t of tags) {\n    if (t.toLowerCase() === \"flaky-test\") return true;\n  }\n  return false;\n}\n\n/** Return whether a story is excluded from snapshot capture. */\nexport function isDisabledStory(entry: Pick<StoryEntry, \"tags\" | \"parameters\">): boolean {\n  if (entry.parameters?.disableSnapshot) return true;\n  const tags = entry.tags ?? [];\n  for (const t of tags) {\n    const lower = t.toLowerCase();\n    if (lower === \"skip\" || lower === \"disable\" || lower === \"disable-snapshot\") return true;\n  }\n  return false;\n}\n\n/** 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  parameters?: StoryParameters;\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\n/** Default viewport used when none is configured. */\nexport const DEFAULT_VIEWPORTS: Viewport[] = [{ name: \"desktop\", width: 1280, height: 720 }];\n"],"mappings":";;;;;AAUA,SAAgB,aAAa,OAAyD;CACpF,IAAI,MAAM,YAAY,WAAW,OAAO;CACxC,MAAM,OAAO,MAAM,QAAQ,CAAC;CAC5B,KAAK,MAAM,KAAK,MACd,IAAI,EAAE,YAAY,MAAM,cAAc,OAAO;CAE/C,OAAO;AACT;;AAGA,SAAgB,gBAAgB,OAAyD;CACvF,IAAI,MAAM,YAAY,iBAAiB,OAAO;CAC9C,MAAM,OAAO,MAAM,QAAQ,CAAC;CAC5B,KAAK,MAAM,KAAK,MAAM;EACpB,MAAM,QAAQ,EAAE,YAAY;EAC5B,IAAI,UAAU,UAAU,UAAU,aAAa,UAAU,oBAAoB,OAAO;CACtF;CACA,OAAO;AACT;;AA6BA,MAAa,oBAAgC,CAAC;CAAE,MAAM;CAAW,OAAO;CAAM,QAAQ;AAAI,CAAC"}
+{"version":3,"file":"adapter.mjs","names":[],"sources":["../../src/capture/adapter.ts"],"sourcesContent":["import type { DepGraph } from \"@storyshelf/affected\";\n\n/** A custom viewport registered on a story via `parameters.viewport`. */\nexport interface StoryViewportDefinition {\n  name?: string;\n  styles?: {\n    width?: string | number;\n    height?: string | number;\n  };\n}\n\n/** Storybook `parameters.viewport` config; carried through discovery for per-story viewport capture. */\nexport interface StoryViewportConfig {\n  defaultViewport?: string;\n  viewports?: Record<string, StoryViewportDefinition>;\n}\n\n/** Per-story capture parameters from the Storybook index. */\nexport interface StoryParameters {\n  disableSnapshot?: boolean;\n  delay?: number;\n  diffThreshold?: number;\n  pauseAnimationAtEnd?: boolean;\n  flakyTest?: boolean;\n  /** Force auto-crop (true) or full viewport (false) for this story; undefined uses 60% whitespace rule. */\n  autoCrop?: boolean;\n  /** Whitespace fraction (0..1) above which we crop; default 0.6. */\n  autoCropThreshold?: number;\n  /** Whether overflow should trigger fullPage; default true. */\n  fullPageOnOverflow?: boolean;\n  /** Min dimensions for the final PNG (clamp after padding). */\n  minWidth?: number;\n  minHeight?: number;\n  maxWidth?: number;\n  maxHeight?: number;\n  /** Burst count for steady capture (1 = single shot, 3 = burst 100ms); default 1. */\n  burst?: number;\n  /** Whether to wait for fonts.ready before screenshot; default true when burst >1. */\n  waitForFonts?: boolean;\n  /** Storybook viewport config; adds the story's default viewport to the project list at capture time. */\n  viewport?: StoryViewportConfig;\n}\n\n/** Return whether a story is marked flaky (failures stay non-blocking). */\nexport function isFlakyStory(entry: Pick<StoryEntry, \"tags\" | \"parameters\">): boolean {\n  if (entry.parameters?.flakyTest) return true;\n  const tags = entry.tags ?? [];\n  for (const t of tags) {\n    if (t.toLowerCase() === \"flaky-test\") return true;\n  }\n  return false;\n}\n\n/** Return whether a story is excluded from snapshot capture. */\nexport function isDisabledStory(entry: Pick<StoryEntry, \"tags\" | \"parameters\">): boolean {\n  if (entry.parameters?.disableSnapshot) return true;\n  const tags = entry.tags ?? [];\n  for (const t of tags) {\n    const lower = t.toLowerCase();\n    if (lower === \"skip\" || lower === \"disable\" || lower === \"disable-snapshot\") return true;\n  }\n  return false;\n}\n\n/** 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  parameters?: StoryParameters;\n}\n\n/** Minimal structural page handle handed to `StorySourceAdapter.waitForReady`. */\nexport interface CapturePage {\n  evaluate(\n    pageFunction: string | ((...args: unknown[]) => unknown),\n    arg?: unknown,\n  ): Promise<unknown>;\n  waitForSelector(selector: string, options?: Record<string, unknown>): Promise<unknown>;\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   * Optional hook loading the module dependency graph of an extracted build,\n   * enabling affected capture (render only stories downstream of a change).\n   * Absent (or resolving `null`) means the source cannot be traced, so the\n   * orchestrator renders every story.\n   */\n  loadDependencyGraph?(sourceDir: string): Promise<DepGraph | null>;\n  /**\n   * Optional hook invoked after navigation and before the screenshot sequence,\n   * letting a custom source wait until it is ready to capture. The built-in\n   * Storybook adapter leaves this undefined (rendered via iframe). See\n   * ADR 0005.\n   */\n  waitForReady?(page: CapturePage): Promise<void>;\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\n/** Default viewport used when none is configured. */\nexport const DEFAULT_VIEWPORTS: Viewport[] = [{ name: \"desktop\", width: 1280, height: 720 }];\n"],"mappings":";;;;;AA4CA,SAAgB,aAAa,OAAyD;CACpF,IAAI,MAAM,YAAY,WAAW,OAAO;CACxC,MAAM,OAAO,MAAM,QAAQ,CAAC;CAC5B,KAAK,MAAM,KAAK,MACd,IAAI,EAAE,YAAY,MAAM,cAAc,OAAO;CAE/C,OAAO;AACT;;AAGA,SAAgB,gBAAgB,OAAyD;CACvF,IAAI,MAAM,YAAY,iBAAiB,OAAO;CAC9C,MAAM,OAAO,MAAM,QAAQ,CAAC;CAC5B,KAAK,MAAM,KAAK,MAAM;EACpB,MAAM,QAAQ,EAAE,YAAY;EAC5B,IAAI,UAAU,UAAU,UAAU,aAAa,UAAU,oBAAoB,OAAO;CACtF;CACA,OAAO;AACT;;AAoDA,MAAa,oBAAgC,CAAC;CAAE,MAAM;CAAW,OAAO;CAAM,QAAQ;AAAI,CAAC"}

package/dist/capture/affected.d.mts

@@ -0,0 +1,16 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { StoryEntry, Viewport } from "./adapter.mjs";
+import "../adapter/database.mjs";
+import { Baseline } from "../schema/baseline.mjs";
+import "../models/baseline.mjs";
+//#region src/capture/affected.d.ts
+/** An inherit candidate paired with the baseline it reuses. */
+interface InheritedStory {
+  story: StoryEntry;
+  viewport: Viewport;
+  baseline: Baseline;
+}
+//#endregion
+export { InheritedStory };
+//# sourceMappingURL=affected.d.mts.map

package/dist/capture/affected.mjs

@@ -0,0 +1,64 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { BaselineModel } from "../models/baseline.mjs";
+import { resolveStoryViewports } from "./storybook.mjs";
+import { selectAffectedStories } from "@storyshelf/affected";
+//#region src/capture/affected.ts
+/** Split one inherit candidate by per-viewport baseline availability. */
+async function splitStory(baselines, input, story) {
+	const render = [];
+	const inherited = [];
+	const viewports = resolveStoryViewports(story, input.viewports);
+	const settled = await Promise.all(viewports.map(async (viewport) => ({
+		viewport,
+		baseline: await baselines.resolve(input.projectId, story.id, viewport.name, input.branch, input.defaultBranch)
+	})));
+	for (const { viewport, baseline } of settled) if (baseline) inherited.push({
+		story,
+		viewport,
+		baseline
+	});
+	else if (!render.includes(story)) render.push(story);
+	return {
+		render,
+		inherited
+	};
+}
+/** Merge per-story partitions into a single render/inherit split. */
+function mergePartitions(partitions) {
+	const render = [];
+	const inherited = [];
+	for (const partition of partitions) {
+		render.push(...partition.render);
+		inherited.push(...partition.inherited);
+	}
+	return {
+		render,
+		inherited
+	};
+}
+/**
+* Partition discovered stories into render versus inherit sets.
+*
+* Stories outside the affected set inherit their baseline without rendering,
+* except when no baseline exists (new stories always render). A `null`
+* affected set renders everything.
+*/
+async function partitionAffectedStories(input) {
+	const selected = selectAffectedStories(input.stories, input.affectedPaths);
+	if (selected.inherit.length === 0) return {
+		render: selected.render,
+		inherited: []
+	};
+	const baselines = new BaselineModel(input.db, input.tables);
+	const merged = mergePartitions(await Promise.all(selected.inherit.map(async (story) => await splitStory(baselines, input, story))));
+	return {
+		render: [...selected.render, ...merged.render],
+		inherited: merged.inherited
+	};
+}
+//#endregion
+export { partitionAffectedStories };
+
+//# sourceMappingURL=affected.mjs.map

package/dist/capture/affected.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"affected.mjs","names":[],"sources":["../../src/capture/affected.ts"],"sourcesContent":["import { selectAffectedStories } from \"@storyshelf/affected\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport { BaselineModel, type BaselineTables } from \"../models/baseline.ts\";\nimport type { Baseline } from \"../schema/baseline.ts\";\nimport type { StoryEntry, Viewport } from \"./adapter.ts\";\nimport { resolveStoryViewports } from \"./storybook.ts\";\n\n/** An inherit candidate paired with the baseline it reuses. */\nexport interface InheritedStory {\n  story: StoryEntry;\n  viewport: Viewport;\n  baseline: Baseline;\n}\n\n/** Stories split into capture-now versus inherit-from-baseline sets. */\nexport interface AffectedPartition {\n  render: StoryEntry[];\n  inherited: InheritedStory[];\n}\n\n/** Inputs for partitioning a build's stories by affected status. */\nexport interface PartitionInput {\n  db: DatabaseAdapter;\n  tables: BaselineTables;\n  projectId: string;\n  branch: string;\n  defaultBranch: string;\n  stories: StoryEntry[];\n  viewports: Viewport[];\n  /** Affected import paths, or `null` to render everything. */\n  affectedPaths: string[] | null;\n}\n\n/** Split one inherit candidate by per-viewport baseline availability. */\nasync function splitStory(\n  baselines: BaselineModel,\n  input: PartitionInput,\n  story: StoryEntry,\n): Promise<AffectedPartition> {\n  const render: StoryEntry[] = [];\n  const inherited: InheritedStory[] = [];\n  const viewports = resolveStoryViewports(story, input.viewports);\n  const settled = await Promise.all(\n    viewports.map(async (viewport) => ({\n      viewport,\n      baseline: await baselines.resolve(\n        input.projectId,\n        story.id,\n        viewport.name,\n        input.branch,\n        input.defaultBranch,\n      ),\n    })),\n  );\n  for (const { viewport, baseline } of settled) {\n    if (baseline) {\n      inherited.push({ story, viewport, baseline });\n    } else if (!render.includes(story)) {\n      render.push(story);\n    }\n  }\n  return { render, inherited };\n}\n\n/** Merge per-story partitions into a single render/inherit split. */\nfunction mergePartitions(partitions: AffectedPartition[]): AffectedPartition {\n  const render: StoryEntry[] = [];\n  const inherited: InheritedStory[] = [];\n  for (const partition of partitions) {\n    render.push(...partition.render);\n    inherited.push(...partition.inherited);\n  }\n  return { render, inherited };\n}\n\n/**\n * Partition discovered stories into render versus inherit sets.\n *\n * Stories outside the affected set inherit their baseline without rendering,\n * except when no baseline exists (new stories always render). A `null`\n * affected set renders everything.\n */\nexport async function partitionAffectedStories(input: PartitionInput): Promise<AffectedPartition> {\n  const selected = selectAffectedStories(input.stories, input.affectedPaths);\n  if (selected.inherit.length === 0) {\n    return { render: selected.render, inherited: [] };\n  }\n  const baselines = new BaselineModel(input.db, input.tables);\n  const partitions = await Promise.all(\n    selected.inherit.map(async (story) => await splitStory(baselines, input, story)),\n  );\n  const merged = mergePartitions(partitions);\n  return { render: [...selected.render, ...merged.render], inherited: merged.inherited };\n}\n"],"mappings":";;;;;;;;AAkCA,eAAe,WACb,WACA,OACA,OAC4B;CAC5B,MAAM,SAAuB,CAAC;CAC9B,MAAM,YAA8B,CAAC;CACrC,MAAM,YAAY,sBAAsB,OAAO,MAAM,SAAS;CAC9D,MAAM,UAAU,MAAM,QAAQ,IAC5B,UAAU,IAAI,OAAO,cAAc;EACjC;EACA,UAAU,MAAM,UAAU,QACxB,MAAM,WACN,MAAM,IACN,SAAS,MACT,MAAM,QACN,MAAM,aACR;CACF,EAAE,CACJ;CACA,KAAK,MAAM,EAAE,UAAU,cAAc,SACnC,IAAI,UACF,UAAU,KAAK;EAAE;EAAO;EAAU;CAAS,CAAC;MACvC,IAAI,CAAC,OAAO,SAAS,KAAK,GAC/B,OAAO,KAAK,KAAK;CAGrB,OAAO;EAAE;EAAQ;CAAU;AAC7B;;AAGA,SAAS,gBAAgB,YAAoD;CAC3E,MAAM,SAAuB,CAAC;CAC9B,MAAM,YAA8B,CAAC;CACrC,KAAK,MAAM,aAAa,YAAY;EAClC,OAAO,KAAK,GAAG,UAAU,MAAM;EAC/B,UAAU,KAAK,GAAG,UAAU,SAAS;CACvC;CACA,OAAO;EAAE;EAAQ;CAAU;AAC7B;;;;;;;;AASA,eAAsB,yBAAyB,OAAmD;CAChG,MAAM,WAAW,sBAAsB,MAAM,SAAS,MAAM,aAAa;CACzE,IAAI,SAAS,QAAQ,WAAW,GAC9B,OAAO;EAAE,QAAQ,SAAS;EAAQ,WAAW,CAAC;CAAE;CAElD,MAAM,YAAY,IAAI,cAAc,MAAM,IAAI,MAAM,MAAM;CAI1D,MAAM,SAAS,gBAAgB,MAHN,QAAQ,IAC/B,SAAS,QAAQ,IAAI,OAAO,UAAU,MAAM,WAAW,WAAW,OAAO,KAAK,CAAC,CACjF,CACyC;CACzC,OAAO;EAAE,QAAQ,CAAC,GAAG,SAAS,QAAQ,GAAG,OAAO,MAAM;EAAG,WAAW,OAAO;CAAU;AACvF"}

package/dist/capture/diff-record.mjs

@@ -0,0 +1,30 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { diffImages } from "../diff/engine.mjs";
+import { DEFAULT_DIFF_OPTIONS } from "../diff/options.mjs";
+//#region src/capture/diff-record.ts
+/** Per-story `diffThreshold` when it is a finite number in 0..1; otherwise the project threshold. */
+function resolvePixelThreshold(projectThreshold, override) {
+	return typeof override === "number" && Number.isFinite(override) && override >= 0 && override <= 1 ? override : projectThreshold;
+}
+/** Read two stored PNGs and diff them with the project's thresholds (optionally a per-story pixel threshold). */
+async function diffStoredScreenshots(storage, project, baselinePath, currentPath, diffThreshold) {
+	const current = await storage.read(currentPath);
+	const previous = await storage.read(baselinePath);
+	return diffImages(previous, current, {
+		...DEFAULT_DIFF_OPTIONS,
+		pixelThreshold: resolvePixelThreshold(project.pixelThreshold, diffThreshold),
+		maxDiffRatio: project.maxDiffRatio
+	});
+}
+/** Write the diff overlay for a failing diff; returns the stored path, or null when none applies. */
+async function writeDiffOverlay(storage, path, result, passed) {
+	if (passed || !result.diffImage) return null;
+	await storage.write(path, result.diffImage);
+	return path;
+}
+//#endregion
+export { diffStoredScreenshots, resolvePixelThreshold, writeDiffOverlay };
+
+//# sourceMappingURL=diff-record.mjs.map

package/dist/capture/diff-record.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-record.mjs","names":[],"sources":["../../src/capture/diff-record.ts"],"sourcesContent":["/** Diff a stored screenshot against a baseline and persist the overlay; shared by capture and re-diff. */\nimport type { StorageAdapter } from \"../adapters/storage.ts\";\nimport { diffImages } from \"../diff/engine.ts\";\nimport { DEFAULT_DIFF_OPTIONS, type DiffResult } from \"../diff/options.ts\";\n\n/** Project thresholds that drive a diff. */\nexport interface DiffThresholds {\n  pixelThreshold: number;\n  maxDiffRatio: number;\n}\n\n/** Per-story `diffThreshold` when it is a finite number in 0..1; otherwise the project threshold. */\nexport function resolvePixelThreshold(projectThreshold: number, override?: number): number {\n  const valid = typeof override === \"number\" && Number.isFinite(override);\n  return valid && override >= 0 && override <= 1 ? override : projectThreshold;\n}\n\n/** Read two stored PNGs and diff them with the project's thresholds (optionally a per-story pixel threshold). */\nexport async function diffStoredScreenshots(\n  storage: StorageAdapter,\n  project: DiffThresholds,\n  baselinePath: string,\n  currentPath: string,\n  diffThreshold?: number,\n): Promise<DiffResult> {\n  const current = await storage.read(currentPath);\n  const previous = await storage.read(baselinePath);\n  return diffImages(previous, current, {\n    ...DEFAULT_DIFF_OPTIONS,\n    pixelThreshold: resolvePixelThreshold(project.pixelThreshold, diffThreshold),\n    maxDiffRatio: project.maxDiffRatio,\n  });\n}\n\n/** Write the diff overlay for a failing diff; returns the stored path, or null when none applies. */\nexport async function writeDiffOverlay(\n  storage: StorageAdapter,\n  path: string,\n  result: Pick<DiffResult, \"diffImage\">,\n  passed: boolean,\n): Promise<string | null> {\n  if (passed || !result.diffImage) {\n    return null;\n  }\n  await storage.write(path, result.diffImage);\n  return path;\n}\n"],"mappings":";;;;;;;AAYA,SAAgB,sBAAsB,kBAA0B,UAA2B;CAEzF,OADc,OAAO,aAAa,YAAY,OAAO,SAAS,QAAQ,KACtD,YAAY,KAAK,YAAY,IAAI,WAAW;AAC9D;;AAGA,eAAsB,sBACpB,SACA,SACA,cACA,aACA,eACqB;CACrB,MAAM,UAAU,MAAM,QAAQ,KAAK,WAAW;CAC9C,MAAM,WAAW,MAAM,QAAQ,KAAK,YAAY;CAChD,OAAO,WAAW,UAAU,SAAS;EACnC,GAAG;EACH,gBAAgB,sBAAsB,QAAQ,gBAAgB,aAAa;EAC3E,cAAc,QAAQ;CACxB,CAAC;AACH;;AAGA,eAAsB,iBACpB,SACA,MACA,QACA,QACwB;CACxB,IAAI,UAAU,CAAC,OAAO,WACpB,OAAO;CAET,MAAM,QAAQ,MAAM,MAAM,OAAO,SAAS;CAC1C,OAAO;AACT"}

package/dist/capture/dispatch.d.mts

@@ -0,0 +1,36 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DatabaseAdapter } from "../adapter/database.mjs";
+import { GitHostProvider } from "../adapter/git-host.mjs";
+import { Logger } from "../logger.mjs";
+import { SecretInput } from "../utils/encrypt.mjs";
+import { BuildTables } from "../models/build.mjs";
+import { CaptureAttemptTables } from "../models/capture-attempt.mjs";
+import { CaptureLogTables } from "../models/capture-log.mjs";
+import { ProjectTables } from "../models/project.mjs";
+import { CaptureJobOptions } from "./orchestrator.mjs";
+import { StatusConfigTables } from "../models/status-config.mjs";
+//#region src/capture/dispatch.d.ts
+/** Build the queue's job runner: post pending, apply skip rules, capture, report. */
+declare function createDispatchJob(deps: DispatchDeps): (job: CaptureDispatchJob) => Promise<void>;
+/** Table handles required by dispatch. */
+type DispatchTables = BuildTables & ProjectTables & StatusConfigTables & CaptureAttemptTables & CaptureLogTables;
+/** Dependencies for building the capture queue's job runner. */
+interface DispatchDeps {
+  db: DatabaseAdapter;
+  tables: DispatchTables;
+  jobOptions: CaptureJobOptions;
+  gitHosts: GitHostProvider[];
+  secret: SecretInput;
+  logger: Logger;
+}
+/** A queued capture job. */
+interface CaptureDispatchJob {
+  buildId: string;
+  reqId?: string;
+  /** W3C `traceparent` continuing the enqueueing request's trace. */
+  traceparent?: string;
+}
+//#endregion
+export { CaptureDispatchJob, DispatchDeps, DispatchTables, createDispatchJob };
+//# sourceMappingURL=dispatch.d.mts.map