@storyshelf/core 0.6.2 → 0.7.0

package/dist/adapter/design.d.mts

@@ -0,0 +1,85 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Logger } from "../logger.mjs";
+import { OAuthClient } from "./oauth.mjs";
+import { Adapter, AdapterMetadata } from "./metadata.mjs";
+import { Buffer } from "node:buffer";
+//#region src/adapters/design.d.ts
+/** Design-provider metadata: identity plus the copy the settings UI shows for its credential. */
+interface DesignAdapterMetadata extends AdapterMetadata {
+  readonly category: "design";
+  /** Credential field label, e.g. "Figma access token". */
+  readonly credentialLabel: string;
+  /** Help text under the credential field (scopes needed, expiry). */
+  readonly credentialHelp: string;
+  /** Placeholder for the credential input, e.g. "figd_…". */
+  readonly credentialPlaceholder?: string;
+  /** Example of a link this provider accepts, shown on rejection. */
+  readonly urlHint: string;
+  /** Longest lifetime of a credential, so the UI can count down to rotation. */
+  readonly credentialMaxAgeDays?: number;
+}
+/** A parsed design link. */
+interface DesignRef {
+  /** Provider file identifier. */
+  fileKey: string;
+  /** Node id inside the file, or null when the link targets the whole file. */
+  nodeId: string | null;
+  /** URL to open: the pasted link without credentials or fragment. */
+  url: string;
+}
+/** Outcome of a metadata fetch. `error` is transient (outage/rate limit) and never persisted. */
+type DesignState = "ok" | "deleted" | "unauthorized" | "forbidden" | "error";
+/** Metadata of a design file or node. */
+interface DesignMeta {
+  state: DesignState;
+  name: string | null;
+  version: string | null;
+  lastModified: string | null;
+}
+/** Per-call options: a signal cancelling the whole call (page-render budget) plus a logger. */
+interface DesignCallOptions {
+  logger?: Logger;
+  signal?: AbortSignal;
+}
+/** How a stored credential authenticates: a pasted personal token or a user's OAuth access token. */
+type DesignAuthType = "token" | "oauth";
+/** Descriptor — registered at startup, parses links and binds a credential. */
+interface DesignProvider extends Adapter<DesignAdapterMetadata> {
+  /** Parse a pasted link; null when it is not one of this provider's links. */
+  parseUrl(raw: string): DesignRef | null;
+  /** Create a client bound to a decrypted credential (`authType` defaults to a personal token). */
+  create(opts: {
+    credential: string;
+    authType?: DesignAuthType;
+    logger?: Logger;
+  }): DesignClient;
+  /** Present only when the operator configured OAuth for this provider. */
+  readonly oauth?: OAuthClient;
+}
+/** Runtime — bound to a credential, talks to the vendor API. */
+interface DesignClient {
+  /**
+   * Metadata for several refs of one file, keyed by node id (`""` = whole file).
+   * API failures map to a {@link DesignState} per ref rather than throwing.
+   */
+  fetchMetas(fileKey: string, refs: readonly DesignRef[], options?: DesignCallOptions): Promise<Map<string, DesignMeta>>;
+  /**
+   * PNG renders of several nodes of one file, keyed by node id. Nodes the vendor
+   * cannot render are omitted; throws when the render API call itself fails.
+   */
+  fetchRenders(fileKey: string, nodeIds: readonly string[], options?: DesignCallOptions): Promise<Map<string, Buffer>>;
+}
+/** Thrown when a design link is not accepted by any configured provider. */
+declare class InvalidDesignUrlError extends Error {
+  readonly value: string;
+  constructor(value: string, hint?: string);
+}
+/** First provider that accepts the link, with its parsed ref. */
+declare function parseDesignUrl(providers: readonly DesignProvider[], raw: string): {
+  provider: DesignProvider;
+  ref: DesignRef;
+} | null;
+//#endregion
+export { DesignAdapterMetadata, DesignAuthType, DesignCallOptions, DesignClient, DesignMeta, DesignProvider, DesignRef, DesignState, InvalidDesignUrlError, parseDesignUrl };
+//# sourceMappingURL=design.d.mts.map

package/dist/adapter/design.mjs

@@ -0,0 +1,28 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/adapters/design.ts
+/** Thrown when a design link is not accepted by any configured provider. */
+var InvalidDesignUrlError = class extends Error {
+	value;
+	constructor(value, hint) {
+		super(hint ? `Enter a supported design link, e.g. ${hint}` : "No design provider is configured");
+		this.value = value;
+		this.name = "InvalidDesignUrlError";
+	}
+};
+/** First provider that accepts the link, with its parsed ref. */
+function parseDesignUrl(providers, raw) {
+	for (const provider of providers) {
+		const ref = provider.parseUrl(raw);
+		if (ref) return {
+			provider,
+			ref
+		};
+	}
+	return null;
+}
+//#endregion
+export { InvalidDesignUrlError, parseDesignUrl };
+
+//# sourceMappingURL=design.mjs.map

package/dist/adapter/design.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"design.mjs","names":[],"sources":["../../src/adapters/design.ts"],"sourcesContent":["/**\n * Design-provider adapter interface: link validation, file/node metadata and\n * rendered previews from a design tool (Figma, …). Core owns link resolution,\n * the metadata/render cache and credential storage; a provider owns only the\n * vendor specifics below.\n */\nimport type { Buffer } from \"node:buffer\";\nimport type { Logger } from \"../logger.ts\";\nimport type { Adapter, AdapterMetadata } from \"./metadata.ts\";\nimport type { OAuthClient } from \"./oauth.ts\";\n\n/** Design-provider metadata: identity plus the copy the settings UI shows for its credential. */\nexport interface DesignAdapterMetadata extends AdapterMetadata {\n  readonly category: \"design\";\n  /** Credential field label, e.g. \"Figma access token\". */\n  readonly credentialLabel: string;\n  /** Help text under the credential field (scopes needed, expiry). */\n  readonly credentialHelp: string;\n  /** Placeholder for the credential input, e.g. \"figd_…\". */\n  readonly credentialPlaceholder?: string;\n  /** Example of a link this provider accepts, shown on rejection. */\n  readonly urlHint: string;\n  /** Longest lifetime of a credential, so the UI can count down to rotation. */\n  readonly credentialMaxAgeDays?: number;\n}\n\n/** A parsed design link. */\nexport interface DesignRef {\n  /** Provider file identifier. */\n  fileKey: string;\n  /** Node id inside the file, or null when the link targets the whole file. */\n  nodeId: string | null;\n  /** URL to open: the pasted link without credentials or fragment. */\n  url: string;\n}\n\n/** Outcome of a metadata fetch. `error` is transient (outage/rate limit) and never persisted. */\nexport type DesignState = \"ok\" | \"deleted\" | \"unauthorized\" | \"forbidden\" | \"error\";\n\n/** Metadata of a design file or node. */\nexport interface DesignMeta {\n  state: DesignState;\n  name: string | null;\n  version: string | null;\n  lastModified: string | null;\n}\n\n/** Per-call options: a signal cancelling the whole call (page-render budget) plus a logger. */\nexport interface DesignCallOptions {\n  logger?: Logger;\n  signal?: AbortSignal;\n}\n\n/** How a stored credential authenticates: a pasted personal token or a user's OAuth access token. */\nexport type DesignAuthType = \"token\" | \"oauth\";\n\n/** Descriptor — registered at startup, parses links and binds a credential. */\nexport interface DesignProvider extends Adapter<DesignAdapterMetadata> {\n  /** Parse a pasted link; null when it is not one of this provider's links. */\n  parseUrl(raw: string): DesignRef | null;\n  /** Create a client bound to a decrypted credential (`authType` defaults to a personal token). */\n  create(opts: { credential: string; authType?: DesignAuthType; logger?: Logger }): DesignClient;\n  /** Present only when the operator configured OAuth for this provider. */\n  readonly oauth?: OAuthClient;\n}\n\n/** Runtime — bound to a credential, talks to the vendor API. */\nexport interface DesignClient {\n  /**\n   * Metadata for several refs of one file, keyed by node id (`\"\"` = whole file).\n   * API failures map to a {@link DesignState} per ref rather than throwing.\n   */\n  fetchMetas(\n    fileKey: string,\n    refs: readonly DesignRef[],\n    options?: DesignCallOptions,\n  ): Promise<Map<string, DesignMeta>>;\n  /**\n   * PNG renders of several nodes of one file, keyed by node id. Nodes the vendor\n   * cannot render are omitted; throws when the render API call itself fails.\n   */\n  fetchRenders(\n    fileKey: string,\n    nodeIds: readonly string[],\n    options?: DesignCallOptions,\n  ): Promise<Map<string, Buffer>>;\n}\n\n/** Thrown when a design link is not accepted by any configured provider. */\nexport class InvalidDesignUrlError extends Error {\n  readonly value: string;\n\n  constructor(value: string, hint?: string) {\n    super(\n      hint ? `Enter a supported design link, e.g. ${hint}` : \"No design provider is configured\",\n    );\n    this.value = value;\n    this.name = \"InvalidDesignUrlError\";\n  }\n}\n\n/** First provider that accepts the link, with its parsed ref. */\nexport function parseDesignUrl(\n  providers: readonly DesignProvider[],\n  raw: string,\n): { provider: DesignProvider; ref: DesignRef } | null {\n  for (const provider of providers) {\n    const ref = provider.parseUrl(raw);\n    if (ref) return { provider, ref };\n  }\n  return null;\n}\n"],"mappings":";;;;;AAyFA,IAAa,wBAAb,cAA2C,MAAM;CAC/C;CAEA,YAAY,OAAe,MAAe;EACxC,MACE,OAAO,uCAAuC,SAAS,kCACzD;EACA,KAAK,QAAQ;EACb,KAAK,OAAO;CACd;AACF;;AAGA,SAAgB,eACd,WACA,KACqD;CACrD,KAAK,MAAM,YAAY,WAAW;EAChC,MAAM,MAAM,SAAS,SAAS,GAAG;EACjC,IAAI,KAAK,OAAO;GAAE;GAAU;EAAI;CAClC;CACA,OAAO;AACT"}

package/dist/adapter/metadata.d.mts

@@ -1,8 +1,7 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { ShelfConfig } from "../config.mjs";
 import { Logger } from "../logger.mjs";
-import { z } from "zod";
+import { ShelfConfig } from "../config.mjs";
 //#region src/adapters/metadata.d.ts
 /**
  * Adapter family — which concern an adapter supplies.
@@ -11,7 +10,7 @@ import { z } from "zod";
  * `category` tells a reader which slot the adapter fills without knowing
  * which adapter instance supplied the metadata.
  */
-type AdapterCategory = "database" | "storage" | "capture-runner" | "capture-queue" | "git-host" | "notifier";
+type AdapterCategory = "database" | "storage" | "capture-runner" | "capture-queue" | "design" | "notifier";
 /** Common adapter identity — every adapter instance exposes this. */
 interface AdapterMetadata {
   /** Human label for UI/logs. */
@@ -25,12 +24,6 @@ interface AdapterMetadata {
   /** Adapter family — which concern this adapter supplies. */
   readonly category: AdapterCategory;
 }
-/** Git-specific metadata extension (adds logo + validation schema). */
-interface GitAdapterMetadata extends AdapterMetadata {
-  readonly category: "git-host";
-  readonly logo?: string;
-  readonly schema: z.ZodType;
-}
 /** Context passed to an adapter's `setup` on server startup. */
 interface AdapterSetupContext {
   /** Resolved shelf configuration (scratchDir, secret, …). Never log the secret. */
@@ -85,5 +78,5 @@ interface Adapter<Extra extends object = Record<string, unknown>> {
   setLogger?(logger: Logger): void;
 }
 //#endregion
-export { Adapter, AdapterCategory, AdapterHealth, AdapterLifecycle, AdapterMetadata, AdapterSetupContext, GitAdapterMetadata };
+export { Adapter, AdapterCategory, AdapterHealth, AdapterLifecycle, AdapterMetadata, AdapterSetupContext };
 //# sourceMappingURL=metadata.d.mts.map

package/dist/adapter/notifier.d.mts

@@ -1,7 +1,10 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { ChannelToggles, FormattedNotification, NotificationBrand, NotificationChannel, NotificationEvent, SystemEventName, SystemNotification } from "../adapters/notifier/types.mjs";
-import { NotifierAdapter, NotifierMetadata, NotifierProvider } from "../adapters/notifier/provider.mjs";
+import { ChannelOutcome, ChannelToggles, FormattedNotification, NotificationBrand, NotificationChannel, NotificationEvent, NotifierState, NotifierStateTarget, StateAnnotation, SystemEventName, SystemNotification } from "../adapters/notifier/types.mjs";
+import { MessageNotifierAdapter, MessageNotifierMetadata, MessageNotifierProvider, NotifierAdapter, NotifierDelivery, NotifierMetadata, NotifierProvider, SetStateInput, StateNotifierAdapter, StateNotifierMetadata, StateNotifierProvider, isStateProvider } from "../adapters/notifier/provider.mjs";
 import { emitNotifications, emitSystemNotification } from "../adapters/notifier/events.mjs";
+import { BuildStateBuild, BuildStateChange, BuildStateFlags, BuildStateInput, BuildStateSet, DesiredComment, DesiredStatus, MAX_ANNOTATIONS, PublishingState, StatusName, statusesForBuild } from "../adapters/notifier/build-state.mjs";
+import { buildCommentMarkdown } from "../adapters/notifier/build-comment.mjs";
+import { DEFAULT_STATUS_PREFIX, channelPrefix, writeBuildState } from "../adapters/notifier/state.mjs";
 import { formatNotification, formatSystemNotification } from "../adapters/notifier/format.mjs";
-export { type ChannelToggles, type FormattedNotification, type NotificationBrand, type NotificationChannel, type NotificationEvent, type NotifierAdapter, type NotifierMetadata, type NotifierProvider, type SystemEventName, type SystemNotification, emitNotifications, emitSystemNotification, formatNotification, formatSystemNotification };
+export { type BuildStateBuild, type BuildStateChange, type BuildStateFlags, type BuildStateInput, type BuildStateSet, type ChannelOutcome, type ChannelToggles, DEFAULT_STATUS_PREFIX, type DesiredComment, type DesiredStatus, type FormattedNotification, MAX_ANNOTATIONS, type MessageNotifierAdapter, type MessageNotifierMetadata, type MessageNotifierProvider, type NotificationBrand, type NotificationChannel, type NotificationEvent, type NotifierAdapter, type NotifierDelivery, type NotifierMetadata, type NotifierProvider, type NotifierState, type NotifierStateTarget, type PublishingState, type SetStateInput, type StateAnnotation, type StateNotifierAdapter, type StateNotifierMetadata, type StateNotifierProvider, type StatusName, type SystemEventName, type SystemNotification, buildCommentMarkdown, channelPrefix, emitNotifications, emitSystemNotification, formatNotification, formatSystemNotification, isStateProvider, statusesForBuild, writeBuildState };

package/dist/adapter/notifier.mjs

@@ -2,5 +2,9 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { formatNotification, formatSystemNotification } from "../adapters/notifier/format.mjs";
+import { isStateProvider } from "../adapters/notifier/provider.mjs";
 import { emitNotifications, emitSystemNotification } from "../adapters/notifier/events.mjs";
-export { emitNotifications, emitSystemNotification, formatNotification, formatSystemNotification };
+import { buildCommentMarkdown } from "../adapters/notifier/build-comment.mjs";
+import { MAX_ANNOTATIONS, statusesForBuild } from "../adapters/notifier/build-state.mjs";
+import { DEFAULT_STATUS_PREFIX, channelPrefix, writeBuildState } from "../adapters/notifier/state.mjs";
+export { DEFAULT_STATUS_PREFIX, MAX_ANNOTATIONS, buildCommentMarkdown, channelPrefix, emitNotifications, emitSystemNotification, formatNotification, formatSystemNotification, isStateProvider, statusesForBuild, writeBuildState };

package/dist/adapter/oauth.d.mts

@@ -0,0 +1,52 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/adapters/oauth.d.ts
+/**
+ * Service-neutral OAuth 2 contract for "connect your own account" flows. Any
+ * adapter that talks to a third party on behalf of a user (design tools,
+ * issue trackers, …) can expose an {@link OAuthClient}; the app owns the
+ * redirect/callback routes and core owns token storage and refresh.
+ */
+/** Tokens returned by an authorization-code exchange or a refresh. */
+interface OAuthTokens {
+  accessToken: string;
+  /** Absent when the service keeps the previous refresh token valid. */
+  refreshToken?: string | null;
+  /** ISO time the access token stops working, or null when it never expires. */
+  expiresAt: string | null;
+}
+/** Authorization-code grant against one service, with the operator's client credentials held inside. */
+interface OAuthClient {
+  /** Consent-screen URL to send the user to. */
+  authorizeUrl(opts: {
+    state: string;
+    redirectUri: string;
+  }): string;
+  /** Exchange the callback `code` for tokens. */
+  exchangeCode(opts: {
+    code: string;
+    redirectUri: string;
+    signal?: AbortSignal;
+  }): Promise<OAuthTokens>;
+  /** Mint a new access token from a refresh token. */
+  refresh(opts: {
+    refreshToken: string;
+    signal?: AbortSignal;
+  }): Promise<OAuthTokens>;
+}
+/**
+ * Anything a user can connect an account to. Structurally satisfied by adapters
+ * (`metadata.kind` identifies the service), so registering one is just
+ * listing its adapter.
+ */
+interface OAuthConnectable {
+  readonly metadata: {
+    readonly kind: string;
+    readonly name: string;
+  };
+  /** Present only when the operator configured OAuth for the service. */
+  readonly oauth?: OAuthClient;
+}
+//#endregion
+export { OAuthClient, OAuthConnectable, OAuthTokens };
+//# sourceMappingURL=oauth.d.mts.map

package/dist/adapter/setup.d.mts

@@ -2,22 +2,21 @@ import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { CaptureRunner } from "./capture-runner.mjs";
 import { DatabaseAdapter } from "./database.mjs";
+import { DesignProvider } from "./design.mjs";
 import { EmailSender } from "./email-sender.mjs";
-import { GitHostProvider } from "./git-host.mjs";
 import { NotifierProvider } from "../adapters/notifier/provider.mjs";
 import { StorageAdapter } from "./storage.mjs";
 import { AdapterSetupContext } from "./metadata.mjs";
-import { CaptureQueue } from "./capture-queue.mjs";
 import { bindAdapterLoggers, collectSetups, collectTeardowns, runAdapterSetups, runAdapterTeardowns } from "../adapters/setup-runner.mjs";
 import { validateAdapter, validateAdapterSources, validateAuth, validateBootAssembly } from "../adapters/validate.mjs";
+import { adapterSourcesOf } from "../adapters/sources.mjs";
 //#region src/adapters/setup.d.ts
 /** Adapters that can take part in lifecycle runs. */
 interface AdapterSetupSources {
   database: DatabaseAdapter;
   storage: StorageAdapter;
   captureRunner?: CaptureRunner;
-  captureQueue?: CaptureQueue;
-  gitHosts?: GitHostProvider[];
+  design?: DesignProvider[];
   notifiers?: NotifierProvider[];
   emailSender?: EmailSender;
 }
@@ -57,5 +56,5 @@ declare class AdapterLifecycleError extends Error {
   constructor(phase: LifecyclePhase, failures: AdapterSetupFailure[]);
 }
 //#endregion
-export { AdapterLifecycleError, AdapterSetupFailure, AdapterSetupResult, AdapterSetupSources, HookEntry, LifecyclePhase, bindAdapterLoggers, collectSetups, collectTeardowns, runAdapterSetups, runAdapterTeardowns, validateAdapter, validateAdapterSources, validateAuth, validateBootAssembly };
+export { AdapterLifecycleError, AdapterSetupFailure, AdapterSetupResult, AdapterSetupSources, HookEntry, LifecyclePhase, adapterSourcesOf, bindAdapterLoggers, collectSetups, collectTeardowns, runAdapterSetups, runAdapterTeardowns, validateAdapter, validateAdapterSources, validateAuth, validateBootAssembly };
 //# sourceMappingURL=setup.d.mts.map

package/dist/adapter/setup.mjs

@@ -3,6 +3,7 @@ import "node:url";
 import.meta.url;
 import { bindAdapterLoggers, collectSetups, collectTeardowns, runAdapterSetups, runAdapterTeardowns } from "../adapters/setup-runner.mjs";
 import { validateAdapter, validateAdapterSources, validateAuth, validateBootAssembly } from "../adapters/validate.mjs";
+import { adapterSourcesOf } from "../adapters/sources.mjs";
 //#region src/adapters/setup.ts
 /**
 * Thrown when an `app.lifecycle.setup()` or `teardown()` run finishes with failures.
@@ -24,6 +25,6 @@ var AdapterLifecycleError = class extends Error {
 	}
 };
 //#endregion
-export { AdapterLifecycleError, bindAdapterLoggers, collectSetups, collectTeardowns, runAdapterSetups, runAdapterTeardowns, validateAdapter, validateAdapterSources, validateAuth, validateBootAssembly };
+export { AdapterLifecycleError, adapterSourcesOf, bindAdapterLoggers, collectSetups, collectTeardowns, runAdapterSetups, runAdapterTeardowns, validateAdapter, validateAdapterSources, validateAuth, validateBootAssembly };
 
 //# sourceMappingURL=setup.mjs.map

package/dist/adapter/setup.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"setup.mjs","names":[],"sources":["../../src/adapters/setup.ts"],"sourcesContent":["/**\n * Adapter lifecycle contract: hooks every adapter can expose, plus the\n * settled-result and error types. The runner (`setup-runner.ts`) collects\n * and executes the hooks; `createShelfApp` kicks `setup` eagerly and\n * gates the first request on the shared result. All hooks must be\n * idempotent.\n */\nimport type { CaptureQueue } from \"./capture-queue.ts\";\nimport type { CaptureRunner } from \"./capture-runner.ts\";\nimport type { DatabaseAdapter } from \"./database.ts\";\nimport type { EmailSender } from \"./email-sender.ts\";\nimport type { GitHostProvider } from \"./git-host/index.ts\";\nimport type { AdapterSetupContext } from \"./metadata.ts\";\nimport type { NotifierProvider } from \"./notifier/provider.ts\";\nimport type { StorageAdapter } from \"./storage.ts\";\n\n/** Adapters that can take part in lifecycle runs. */\nexport interface AdapterSetupSources {\n  database: DatabaseAdapter;\n  storage: StorageAdapter;\n  captureRunner?: CaptureRunner;\n  captureQueue?: CaptureQueue;\n  gitHosts?: GitHostProvider[];\n  notifiers?: NotifierProvider[];\n  emailSender?: EmailSender;\n}\n\n/** One collected hook bound to its adapter identity. */\nexport interface HookEntry {\n  readonly category: string;\n  readonly kind: string;\n  readonly name: string;\n  readonly run: (ctx: AdapterSetupContext) => Promise<void>;\n}\n\n/** One failed hook, with its adapter identity attached. */\nexport interface AdapterSetupFailure {\n  readonly category: string;\n  readonly kind: string;\n  readonly name: string;\n  readonly error: string;\n}\n\n/** Settled outcome of a lifecycle run (never rejects — use `ok`). */\nexport interface AdapterSetupResult {\n  readonly ok: boolean;\n  readonly failures: AdapterSetupFailure[];\n}\n\n/** Lifecycle phase a run covers. */\nexport type LifecyclePhase = \"setup\" | \"teardown\";\n\n/**\n * Thrown when an `app.lifecycle.setup()` or `teardown()` run finishes with failures.\n *\n * Inspect `phase` to know which hook failed and `failures` for per-adapter\n * diagnostics. The router converts this into a 500 with structured details\n * during health checks.\n */\nexport class AdapterLifecycleError extends Error {\n  /** Which lifecycle phase failed (`setup` or `teardown`). */\n  readonly phase: LifecyclePhase;\n  /** One entry per adapter hook that failed. */\n  readonly failures: AdapterSetupFailure[];\n  constructor(phase: LifecyclePhase, failures: AdapterSetupFailure[]) {\n    super(`Adapter ${phase} failed: ${failures.map((f) => `${f.category}/${f.kind}`).join(\", \")}`);\n    this.name = \"AdapterLifecycleError\";\n    this.phase = phase;\n    this.failures = failures;\n  }\n}\n\n/** Collect every `setup` hook from the configured adapters. */\nexport {\n  bindAdapterLoggers,\n  collectSetups,\n  collectTeardowns,\n  runAdapterSetups,\n  runAdapterTeardowns,\n} from \"./setup-runner.ts\";\n\n/** Boot-time shape validation for third-party adapters. */\nexport {\n  validateAdapter,\n  validateAdapterSources,\n  validateAuth,\n  validateBootAssembly,\n} from \"./validate.ts\";\n"],"mappings":";;;;;;;;;;;;;AA2DA,IAAa,wBAAb,cAA2C,MAAM;;CAE/C;;CAEA;CACA,YAAY,OAAuB,UAAiC;EAClE,MAAM,WAAW,MAAM,WAAW,SAAS,KAAK,MAAM,GAAG,EAAE,SAAS,GAAG,EAAE,MAAM,CAAC,CAAC,KAAK,IAAI,GAAG;EAC7F,KAAK,OAAO;EACZ,KAAK,QAAQ;EACb,KAAK,WAAW;CAClB;AACF"}
+{"version":3,"file":"setup.mjs","names":[],"sources":["../../src/adapters/setup.ts"],"sourcesContent":["/**\n * Adapter lifecycle contract: hooks every adapter can expose, plus the\n * settled-result and error types. The runner (`setup-runner.ts`) collects\n * and executes the hooks; `createShelfApp` kicks `setup` eagerly and\n * gates the first request on the shared result. All hooks must be\n * idempotent.\n */\nimport type { CaptureRunner } from \"./capture-runner.ts\";\nimport type { DatabaseAdapter } from \"./database.ts\";\nimport type { DesignProvider } from \"./design.ts\";\nimport type { EmailSender } from \"./email-sender.ts\";\nimport type { AdapterSetupContext } from \"./metadata.ts\";\nimport type { NotifierProvider } from \"./notifier/provider.ts\";\nimport type { StorageAdapter } from \"./storage.ts\";\n\n/** Adapters that can take part in lifecycle runs. */\nexport interface AdapterSetupSources {\n  database: DatabaseAdapter;\n  storage: StorageAdapter;\n  captureRunner?: CaptureRunner;\n  design?: DesignProvider[];\n  notifiers?: NotifierProvider[];\n  emailSender?: EmailSender;\n}\n\n/** One collected hook bound to its adapter identity. */\nexport interface HookEntry {\n  readonly category: string;\n  readonly kind: string;\n  readonly name: string;\n  readonly run: (ctx: AdapterSetupContext) => Promise<void>;\n}\n\n/** One failed hook, with its adapter identity attached. */\nexport interface AdapterSetupFailure {\n  readonly category: string;\n  readonly kind: string;\n  readonly name: string;\n  readonly error: string;\n}\n\n/** Settled outcome of a lifecycle run (never rejects — use `ok`). */\nexport interface AdapterSetupResult {\n  readonly ok: boolean;\n  readonly failures: AdapterSetupFailure[];\n}\n\n/** Lifecycle phase a run covers. */\nexport type LifecyclePhase = \"setup\" | \"teardown\";\n\n/**\n * Thrown when an `app.lifecycle.setup()` or `teardown()` run finishes with failures.\n *\n * Inspect `phase` to know which hook failed and `failures` for per-adapter\n * diagnostics. The router converts this into a 500 with structured details\n * during health checks.\n */\nexport class AdapterLifecycleError extends Error {\n  /** Which lifecycle phase failed (`setup` or `teardown`). */\n  readonly phase: LifecyclePhase;\n  /** One entry per adapter hook that failed. */\n  readonly failures: AdapterSetupFailure[];\n  constructor(phase: LifecyclePhase, failures: AdapterSetupFailure[]) {\n    super(`Adapter ${phase} failed: ${failures.map((f) => `${f.category}/${f.kind}`).join(\", \")}`);\n    this.name = \"AdapterLifecycleError\";\n    this.phase = phase;\n    this.failures = failures;\n  }\n}\n\n/** Collect every `setup` hook from the configured adapters. */\nexport {\n  bindAdapterLoggers,\n  collectSetups,\n  collectTeardowns,\n  runAdapterSetups,\n  runAdapterTeardowns,\n} from \"./setup-runner.ts\";\n\n/** Boot-time shape validation for third-party adapters. */\nexport {\n  validateAdapter,\n  validateAdapterSources,\n  validateAuth,\n  validateBootAssembly,\n} from \"./validate.ts\";\nexport { adapterSourcesOf } from \"./sources.ts\";\n"],"mappings":";;;;;;;;;;;;;;AAyDA,IAAa,wBAAb,cAA2C,MAAM;;CAE/C;;CAEA;CACA,YAAY,OAAuB,UAAiC;EAClE,MAAM,WAAW,MAAM,WAAW,SAAS,KAAK,MAAM,GAAG,EAAE,SAAS,GAAG,EAAE,MAAM,CAAC,CAAC,KAAK,IAAI,GAAG;EAC7F,KAAK,OAAO;EACZ,KAAK,QAAQ;EACb,KAAK,WAAW;CAClB;AACF"}

package/dist/adapter/webhook-events.mjs

@@ -1,8 +1,8 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { WebhookModel } from "../models/webhook.mjs";
 import { hmacSha256 } from "../utils/hash.mjs";
+import { WebhookModel } from "../models/webhook.mjs";
 //#region src/adapters/webhook-events.ts
 /** Per-delivery budget: single attempt, no retries (events already fan out). */
 const WEBHOOK_TIMEOUT_MS = 1e4;

package/dist/adapters/capture-target-offers.d.mts

@@ -0,0 +1,28 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { CaptureTarget, RunnerTarget } from "./capture-target.mjs";
+import { AdapterLifecycle } from "../adapter/metadata.mjs";
+//#region src/adapters/capture-target-offers.d.ts
+/** A runner's live target list. */
+interface TargetOffers {
+  /** First declared target: what a project with no `browsers` setting resolves to. */
+  readonly defaultTarget: CaptureTarget;
+  /** The targets with their current status; reads `metadata.targets`. */
+  current(): readonly RunnerTarget[];
+  /**
+   * Wrap `launch` so a target the runner does not offer fails with a {@link TargetLaunchError}, and
+   * a launch that fails marks its target unavailable with the launch error as the reason (not a
+   * transient one: a remote service that is down stays offered).
+   */
+  guard<T, Rest extends unknown[]>(launch: (target: CaptureTarget, ...rest: Rest) => Promise<T>): (target: CaptureTarget, ...rest: Rest) => Promise<T>;
+  /** Lifecycle whose `setup` replaces the statuses with what `verify` finds, and `health` reports them. */
+  lifecycle(verify: () => Promise<readonly RunnerTarget[]>): AdapterLifecycle;
+}
+/**
+ * Offer `declared`, default first. Until verified every target reads as ready, so a runner used
+ * without `lifecycle.setup` behaves as before and a failed launch still marks its target.
+ */
+declare function createTargetOffers(declared: readonly RunnerTarget[]): TargetOffers;
+//#endregion
+export { TargetOffers, createTargetOffers };
+//# sourceMappingURL=capture-target-offers.d.mts.map

package/dist/adapters/capture-target-offers.mjs

@@ -0,0 +1,58 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { TargetLaunchError } from "./capture-target.mjs";
+//#region src/adapters/capture-target-offers.ts
+/**
+* What a runner offers right now, shared by the runners (ADR 0007): the targets it declared, whether
+* each can render, and the lifecycle that keeps that honest. A launch failure marks its target
+* unavailable from then on.
+*/
+/**
+* Offer `declared`, default first. Until verified every target reads as ready, so a runner used
+* without `lifecycle.setup` behaves as before and a failed launch still marks its target.
+*/
+function createTargetOffers(declared) {
+	let targets = declared;
+	const first = declared[0];
+	if (first === void 0) throw new Error("A runner must offer at least one target");
+	const fail = (target, reason) => {
+		targets = targets.map((entry) => entry.target === target ? {
+			...entry,
+			status: { unavailable: reason }
+		} : entry);
+	};
+	return {
+		defaultTarget: first.target,
+		current: () => targets,
+		guard: (launch) => async (target, ...rest) => {
+			if (!targets.some((entry) => entry.target === target)) throw new TargetLaunchError(target, "not offered by this runner");
+			try {
+				return await launch(target, ...rest);
+			} catch (error) {
+				if (error instanceof TargetLaunchError && !error.transient) fail(target, error.reason);
+				throw error;
+			}
+		},
+		lifecycle: (verify) => ({
+			setup: async () => {
+				targets = await verify();
+			},
+			teardown: async () => {
+				await Promise.resolve();
+			},
+			health: async () => {
+				await Promise.resolve();
+				const down = targets.flatMap((entry) => entry.status === "ready" ? [] : [`${entry.target}: ${entry.status.unavailable}`]);
+				return {
+					ok: down.length < targets.length,
+					...down.length > 0 ? { detail: down.join("; ") } : {}
+				};
+			}
+		})
+	};
+}
+//#endregion
+export { createTargetOffers };
+
+//# sourceMappingURL=capture-target-offers.mjs.map

package/dist/adapters/capture-target-offers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-target-offers.mjs","names":[],"sources":["../../src/adapters/capture-target-offers.ts"],"sourcesContent":["/**\n * What a runner offers right now, shared by the runners (ADR 0007): the targets it declared, whether\n * each can render, and the lifecycle that keeps that honest. A launch failure marks its target\n * unavailable from then on.\n */\nimport { TargetLaunchError, type CaptureTarget, type RunnerTarget } from \"./capture-target.ts\";\nimport type { AdapterLifecycle } from \"./metadata.ts\";\n\n/** A runner's live target list. */\nexport interface TargetOffers {\n  /** First declared target: what a project with no `browsers` setting resolves to. */\n  readonly defaultTarget: CaptureTarget;\n  /** The targets with their current status; reads `metadata.targets`. */\n  current(): readonly RunnerTarget[];\n  /**\n   * Wrap `launch` so a target the runner does not offer fails with a {@link TargetLaunchError}, and\n   * a launch that fails marks its target unavailable with the launch error as the reason (not a\n   * transient one: a remote service that is down stays offered).\n   */\n  guard<T, Rest extends unknown[]>(\n    launch: (target: CaptureTarget, ...rest: Rest) => Promise<T>,\n  ): (target: CaptureTarget, ...rest: Rest) => Promise<T>;\n  /** Lifecycle whose `setup` replaces the statuses with what `verify` finds, and `health` reports them. */\n  lifecycle(verify: () => Promise<readonly RunnerTarget[]>): AdapterLifecycle;\n}\n\n/**\n * Offer `declared`, default first. Until verified every target reads as ready, so a runner used\n * without `lifecycle.setup` behaves as before and a failed launch still marks its target.\n */\nexport function createTargetOffers(declared: readonly RunnerTarget[]): TargetOffers {\n  let targets: readonly RunnerTarget[] = declared;\n  const first = declared[0];\n  if (first === undefined) {\n    throw new Error(\"A runner must offer at least one target\");\n  }\n  const fail = (target: CaptureTarget, reason: string): void => {\n    targets = targets.map((entry) =>\n      entry.target === target ? { ...entry, status: { unavailable: reason } } : entry,\n    );\n  };\n  return {\n    defaultTarget: first.target,\n    current: () => targets,\n    guard:\n      (launch) =>\n      async (target, ...rest) => {\n        if (!targets.some((entry) => entry.target === target)) {\n          throw new TargetLaunchError(target, \"not offered by this runner\");\n        }\n        try {\n          return await launch(target, ...rest);\n        } catch (error) {\n          if (error instanceof TargetLaunchError && !error.transient) {\n            fail(target, error.reason);\n          }\n          throw error;\n        }\n      },\n    lifecycle: (verify) => ({\n      setup: async () => {\n        targets = await verify();\n      },\n      teardown: async () => {\n        await Promise.resolve();\n      },\n      health: async () => {\n        await Promise.resolve();\n        const down = targets.flatMap((entry) =>\n          entry.status === \"ready\" ? [] : [`${entry.target}: ${entry.status.unavailable}`],\n        );\n        return {\n          ok: down.length < targets.length,\n          ...(down.length > 0 ? { detail: down.join(\"; \") } : {}),\n        };\n      },\n    }),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;AA8BA,SAAgB,mBAAmB,UAAiD;CAClF,IAAI,UAAmC;CACvC,MAAM,QAAQ,SAAS;CACvB,IAAI,UAAU,KAAA,GACZ,MAAM,IAAI,MAAM,yCAAyC;CAE3D,MAAM,QAAQ,QAAuB,WAAyB;EAC5D,UAAU,QAAQ,KAAK,UACrB,MAAM,WAAW,SAAS;GAAE,GAAG;GAAO,QAAQ,EAAE,aAAa,OAAO;EAAE,IAAI,KAC5E;CACF;CACA,OAAO;EACL,eAAe,MAAM;EACrB,eAAe;EACf,QACG,WACD,OAAO,QAAQ,GAAG,SAAS;GACzB,IAAI,CAAC,QAAQ,MAAM,UAAU,MAAM,WAAW,MAAM,GAClD,MAAM,IAAI,kBAAkB,QAAQ,4BAA4B;GAElE,IAAI;IACF,OAAO,MAAM,OAAO,QAAQ,GAAG,IAAI;GACrC,SAAS,OAAO;IACd,IAAI,iBAAiB,qBAAqB,CAAC,MAAM,WAC/C,KAAK,QAAQ,MAAM,MAAM;IAE3B,MAAM;GACR;EACF;EACF,YAAY,YAAY;GACtB,OAAO,YAAY;IACjB,UAAU,MAAM,OAAO;GACzB;GACA,UAAU,YAAY;IACpB,MAAM,QAAQ,QAAQ;GACxB;GACA,QAAQ,YAAY;IAClB,MAAM,QAAQ,QAAQ;IACtB,MAAM,OAAO,QAAQ,SAAS,UAC5B,MAAM,WAAW,UAAU,CAAC,IAAI,CAAC,GAAG,MAAM,OAAO,IAAI,MAAM,OAAO,aAAa,CACjF;IACA,OAAO;KACL,IAAI,KAAK,SAAS,QAAQ;KAC1B,GAAI,KAAK,SAAS,IAAI,EAAE,QAAQ,KAAK,KAAK,IAAI,EAAE,IAAI,CAAC;IACvD;GACF;EACF;CACF;AACF"}

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

@@ -0,0 +1,71 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/adapters/capture-target.d.ts
+/**
+ * Capture targets (ADR 0007, decision 3): what a project names to render on. A target is a rendering
+ * engine (`chromium`) or a remote one, `<engine>@<name>` (`chromium@grid`), which has its own
+ * baselines and fingerprint.
+ */
+/** A rendering engine. */
+type BrowserName = "chromium" | "firefox" | "webkit" | "chrome";
+/** Engine names accepted for capture rendering (Chromium default). */
+declare const BROWSER_NAMES: readonly ["chromium", "firefox", "webkit", "chrome"];
+/** Engine that legacy rows and single-browser projects belong to. */
+declare const DEFAULT_BROWSER: BrowserName;
+/** What a project's `browsers` setting, a snapshot's `browser` and a baseline key hold. */
+type CaptureTarget = BrowserName | `${BrowserName}@${string}`;
+/** Remote target names: they become part of a storage key and a unique index. */
+declare const TARGET_NAME_PATTERN: RegExp;
+/** How a runner's browser reaches the Storybook (ADR 0007, decision 5). */
+type TargetReach = "loopback" | "url";
+/** Whether a target can render now; `unavailable` carries the reason shown to operators. */
+type TargetStatus = "ready" | {
+  readonly unavailable: string;
+};
+/** One target a runner offers, in its metadata. */
+interface RunnerTarget {
+  target: CaptureTarget;
+  reach: TargetReach;
+  status: TargetStatus;
+}
+/** A target split into its engine and, for a remote one, its name. */
+interface ParsedTarget {
+  engine: BrowserName;
+  /** Set for `<engine>@<name>`; absent for a local engine. */
+  name?: string;
+}
+/** Whether `value` is an engine name. */
+declare function isBrowserName(value: unknown): value is BrowserName;
+/** Split a target into engine and name; `null` when it is not a valid target. */
+declare function tryParseTarget(value: unknown): ParsedTarget | null;
+/** Split a target into engine and name; throws on anything that is not a target. */
+declare function parseTarget(value: string): ParsedTarget;
+/** Whether `value` is a capture target. */
+declare function isCaptureTarget(value: unknown): value is CaptureTarget;
+/** The engine half of a target. */
+declare function engineOf(target: CaptureTarget): BrowserName;
+/** The reason a status is unavailable, or `null` when it is ready. */
+declare function unavailableReason(status: TargetStatus): string | null;
+/**
+ * A launch or connect failure: the browser never started, so the job fails at once with this
+ * reason. Crash isolation (`capture/isolate.ts`) must not see it, since no story is at fault
+ * (ADR 0007, decision 7).
+ */
+declare class TargetLaunchError extends Error {
+  readonly name = "TargetLaunchError";
+  readonly target: CaptureTarget;
+  /** Why it did not start, without the target's name. */
+  readonly reason: string;
+  /**
+   * The failure may pass (a remote browser service that is down or full): the target is not marked
+   * unavailable for it, though the job still fails at once. A wrong version or credentials do not.
+   */
+  readonly transient: boolean;
+  constructor(target: CaptureTarget, reason: string, options?: {
+    cause?: unknown;
+    transient?: boolean;
+  });
+}
+//#endregion
+export { BROWSER_NAMES, BrowserName, CaptureTarget, DEFAULT_BROWSER, ParsedTarget, RunnerTarget, TARGET_NAME_PATTERN, TargetLaunchError, TargetReach, TargetStatus, engineOf, isBrowserName, isCaptureTarget, parseTarget, tryParseTarget, unavailableReason };
+//# sourceMappingURL=capture-target.d.mts.map

package/dist/adapters/capture-target.mjs

@@ -0,0 +1,76 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/adapters/capture-target.ts
+/** Engine names accepted for capture rendering (Chromium default). */
+const BROWSER_NAMES = [
+	"chromium",
+	"firefox",
+	"webkit",
+	"chrome"
+];
+/** Engine that legacy rows and single-browser projects belong to. */
+const DEFAULT_BROWSER = "chromium";
+/** Remote target names: they become part of a storage key and a unique index. */
+const TARGET_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/u;
+/** Whether `value` is an engine name. */
+function isBrowserName(value) {
+	return typeof value === "string" && BROWSER_NAMES.includes(value);
+}
+/** Split a target into engine and name; `null` when it is not a valid target. */
+function tryParseTarget(value) {
+	if (typeof value !== "string") return null;
+	const at = value.indexOf("@");
+	const engine = at === -1 ? value : value.slice(0, at);
+	if (!isBrowserName(engine)) return null;
+	if (at === -1) return { engine };
+	const name = value.slice(at + 1);
+	return TARGET_NAME_PATTERN.test(name) ? {
+		engine,
+		name
+	} : null;
+}
+/** Split a target into engine and name; throws on anything that is not a target. */
+function parseTarget(value) {
+	const parsed = tryParseTarget(value);
+	if (parsed === null) throw new Error(`Invalid capture target "${value}": expected one of ${BROWSER_NAMES.join(", ")}, or <engine>@<name> with a lowercase name of at most 32 letters, digits and hyphens`);
+	return parsed;
+}
+/** Whether `value` is a capture target. */
+function isCaptureTarget(value) {
+	return tryParseTarget(value) !== null;
+}
+/** The engine half of a target. */
+function engineOf(target) {
+	return parseTarget(target).engine;
+}
+/** The reason a status is unavailable, or `null` when it is ready. */
+function unavailableReason(status) {
+	return status === "ready" ? null : status.unavailable;
+}
+/**
+* A launch or connect failure: the browser never started, so the job fails at once with this
+* reason. Crash isolation (`capture/isolate.ts`) must not see it, since no story is at fault
+* (ADR 0007, decision 7).
+*/
+var TargetLaunchError = class extends Error {
+	name = "TargetLaunchError";
+	target;
+	/** Why it did not start, without the target's name. */
+	reason;
+	/**
+	* The failure may pass (a remote browser service that is down or full): the target is not marked
+	* unavailable for it, though the job still fails at once. A wrong version or credentials do not.
+	*/
+	transient;
+	constructor(target, reason, options) {
+		super(`Cannot launch ${target}: ${reason}`, options);
+		this.target = target;
+		this.reason = reason;
+		this.transient = options?.transient ?? false;
+	}
+};
+//#endregion
+export { BROWSER_NAMES, DEFAULT_BROWSER, TARGET_NAME_PATTERN, TargetLaunchError, engineOf, isBrowserName, isCaptureTarget, parseTarget, tryParseTarget, unavailableReason };
+
+//# sourceMappingURL=capture-target.mjs.map

package/dist/adapters/capture-target.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-target.mjs","names":[],"sources":["../../src/adapters/capture-target.ts"],"sourcesContent":["/**\n * Capture targets (ADR 0007, decision 3): what a project names to render on. A target is a rendering\n * engine (`chromium`) or a remote one, `<engine>@<name>` (`chromium@grid`), which has its own\n * baselines and fingerprint.\n */\n\n/** A rendering engine. */\nexport type BrowserName = \"chromium\" | \"firefox\" | \"webkit\" | \"chrome\";\n\n/** Engine names accepted for capture rendering (Chromium default). */\nexport const BROWSER_NAMES = [\"chromium\", \"firefox\", \"webkit\", \"chrome\"] as const;\n\n/** Engine that legacy rows and single-browser projects belong to. */\nexport const DEFAULT_BROWSER: BrowserName = \"chromium\";\n\n/** What a project's `browsers` setting, a snapshot's `browser` and a baseline key hold. */\nexport type CaptureTarget = BrowserName | `${BrowserName}@${string}`;\n\n/** Remote target names: they become part of a storage key and a unique index. */\nexport const TARGET_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/u;\n\n/** How a runner's browser reaches the Storybook (ADR 0007, decision 5). */\nexport type TargetReach = \"loopback\" | \"url\";\n\n/** Whether a target can render now; `unavailable` carries the reason shown to operators. */\nexport type TargetStatus = \"ready\" | { readonly unavailable: string };\n\n/** One target a runner offers, in its metadata. */\nexport interface RunnerTarget {\n  target: CaptureTarget;\n  reach: TargetReach;\n  status: TargetStatus;\n}\n\n/** A target split into its engine and, for a remote one, its name. */\nexport interface ParsedTarget {\n  engine: BrowserName;\n  /** Set for `<engine>@<name>`; absent for a local engine. */\n  name?: string;\n}\n\n/** Whether `value` is an engine name. */\nexport function isBrowserName(value: unknown): value is BrowserName {\n  return typeof value === \"string\" && (BROWSER_NAMES as readonly string[]).includes(value);\n}\n\n/** Split a target into engine and name; `null` when it is not a valid target. */\nexport function tryParseTarget(value: unknown): ParsedTarget | null {\n  if (typeof value !== \"string\") {\n    return null;\n  }\n  const at = value.indexOf(\"@\");\n  const engine = at === -1 ? value : value.slice(0, at);\n  if (!isBrowserName(engine)) {\n    return null;\n  }\n  if (at === -1) {\n    return { engine };\n  }\n  const name = value.slice(at + 1);\n  return TARGET_NAME_PATTERN.test(name) ? { engine, name } : null;\n}\n\n/** Split a target into engine and name; throws on anything that is not a target. */\nexport function parseTarget(value: string): ParsedTarget {\n  const parsed = tryParseTarget(value);\n  if (parsed === null) {\n    throw new Error(\n      `Invalid capture target \"${value}\": expected one of ${BROWSER_NAMES.join(\", \")}, or <engine>@<name> with a lowercase name of at most 32 letters, digits and hyphens`,\n    );\n  }\n  return parsed;\n}\n\n/** Whether `value` is a capture target. */\nexport function isCaptureTarget(value: unknown): value is CaptureTarget {\n  return tryParseTarget(value) !== null;\n}\n\n/** The engine half of a target. */\nexport function engineOf(target: CaptureTarget): BrowserName {\n  return parseTarget(target).engine;\n}\n\n/** The reason a status is unavailable, or `null` when it is ready. */\nexport function unavailableReason(status: TargetStatus): string | null {\n  return status === \"ready\" ? null : status.unavailable;\n}\n\n/**\n * A launch or connect failure: the browser never started, so the job fails at once with this\n * reason. Crash isolation (`capture/isolate.ts`) must not see it, since no story is at fault\n * (ADR 0007, decision 7).\n */\nexport class TargetLaunchError extends Error {\n  override readonly name = \"TargetLaunchError\";\n  readonly target: CaptureTarget;\n  /** Why it did not start, without the target's name. */\n  readonly reason: string;\n  /**\n   * The failure may pass (a remote browser service that is down or full): the target is not marked\n   * unavailable for it, though the job still fails at once. A wrong version or credentials do not.\n   */\n  readonly transient: boolean;\n\n  constructor(\n    target: CaptureTarget,\n    reason: string,\n    options?: { cause?: unknown; transient?: boolean },\n  ) {\n    super(`Cannot launch ${target}: ${reason}`, options);\n    this.target = target;\n    this.reason = reason;\n    this.transient = options?.transient ?? false;\n  }\n}\n"],"mappings":";;;;;AAUA,MAAa,gBAAgB;CAAC;CAAY;CAAW;CAAU;AAAQ;;AAGvE,MAAa,kBAA+B;;AAM5C,MAAa,sBAAsB;;AAuBnC,SAAgB,cAAc,OAAsC;CAClE,OAAO,OAAO,UAAU,YAAa,cAAoC,SAAS,KAAK;AACzF;;AAGA,SAAgB,eAAe,OAAqC;CAClE,IAAI,OAAO,UAAU,UACnB,OAAO;CAET,MAAM,KAAK,MAAM,QAAQ,GAAG;CAC5B,MAAM,SAAS,OAAO,KAAK,QAAQ,MAAM,MAAM,GAAG,EAAE;CACpD,IAAI,CAAC,cAAc,MAAM,GACvB,OAAO;CAET,IAAI,OAAO,IACT,OAAO,EAAE,OAAO;CAElB,MAAM,OAAO,MAAM,MAAM,KAAK,CAAC;CAC/B,OAAO,oBAAoB,KAAK,IAAI,IAAI;EAAE;EAAQ;CAAK,IAAI;AAC7D;;AAGA,SAAgB,YAAY,OAA6B;CACvD,MAAM,SAAS,eAAe,KAAK;CACnC,IAAI,WAAW,MACb,MAAM,IAAI,MACR,2BAA2B,MAAM,qBAAqB,cAAc,KAAK,IAAI,EAAE,qFACjF;CAEF,OAAO;AACT;;AAGA,SAAgB,gBAAgB,OAAwC;CACtE,OAAO,eAAe,KAAK,MAAM;AACnC;;AAGA,SAAgB,SAAS,QAAoC;CAC3D,OAAO,YAAY,MAAM,CAAC,CAAC;AAC7B;;AAGA,SAAgB,kBAAkB,QAAqC;CACrE,OAAO,WAAW,UAAU,OAAO,OAAO;AAC5C;;;;;;AAOA,IAAa,oBAAb,cAAuC,MAAM;CAC3C,OAAyB;CACzB;;CAEA;;;;;CAKA;CAEA,YACE,QACA,QACA,SACA;EACA,MAAM,iBAAiB,OAAO,IAAI,UAAU,OAAO;EACnD,KAAK,SAAS;EACd,KAAK,SAAS;EACd,KAAK,YAAY,SAAS,aAAa;CACzC;AACF"}

package/dist/adapters/notifier/build-comment.d.mts

@@ -0,0 +1,24 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DesiredStatus } from "./build-state.mjs";
+//#region src/adapters/notifier/build-comment.d.ts
+/** Inputs of {@link buildCommentMarkdown}. */
+interface BuildCommentInput {
+  buildUrl: string;
+  /** Present once the Storybook is published. */
+  storybookUrl?: string | undefined;
+  /** The gating statuses (`testing` or `review`), in display order. */
+  gates: readonly DesiredStatus[];
+  /** Present when `testing` or review is on: the snapshot totals to summarize. */
+  counts?: {
+    snapshotCount: number;
+    changedCount: number;
+    approvedCount: number;
+    rejectedCount: number;
+  } | undefined;
+}
+/** Comment body (below the idempotency marker): links to the build, the Storybook and a summary. */
+declare function buildCommentMarkdown(input: BuildCommentInput): string;
+//#endregion
+export { BuildCommentInput, buildCommentMarkdown };
+//# sourceMappingURL=build-comment.d.mts.map