@storyshelf/core 0.6.2 → 0.8.0

package/dist/types.d.mts

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

package/dist/types.mjs

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

package/dist/types.mjs.map

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

package/dist/urls.d.mts

@@ -1,6 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/urls.d.ts
 /** Type-safe URL builder for project pages and published Storybooks. */
 interface UrlBuilder {
   projectsList(): string;
@@ -10,10 +9,14 @@ interface UrlBuilder {
   buildsList(slug: string): string;
   build(slug: string, buildId: string): string;
   buildDiff(slug: string, buildId: string): string;
+  /** Review page of one snapshot: the build's diff page with that snapshot selected. */
+  snapshot(slug: string, buildId: string, snapshotId: string): string;
   library(slug: string): string;
   jobs(slug: string): string;
   labels(slug: string): string;
   label(slug: string, key: string, value: string): string;
+  /** Stable component page, keyed by the story file's import path. */
+  component(slug: string, importPath: string): string;
   storybook(slug: string): string;
   storybookLabel(slug: string, key: string, value: string): string;
   storybookBuild(slug: string, buildId: string): string;
@@ -33,6 +36,5 @@ declare function createUrlBuilder(baseUrl: string, publishedBaseDomain?: string)
  * app-relative paths only, so `javascript:`/`data:` payloads fall back.
  */
 declare function safeImageUrl(value: string | undefined): string | null;
-//#endregion
 export { UrlBuilder, createUrlBuilder, safeImageUrl };
 //# sourceMappingURL=urls.d.mts.map

package/dist/urls.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/urls.ts
+// src/urls.ts
 /**
 * Create a URL builder rooted at the given base URL.
 *
@@ -19,12 +19,14 @@ function createUrlBuilder(baseUrl, publishedBaseDomain) {
 		buildsList: (slug) => `${root}/projects/${slug}/builds`,
 		build: (slug, buildId) => `${root}/projects/${slug}/builds/${buildId}`,
 		buildDiff: (slug, buildId) => `${root}/projects/${slug}/builds/${buildId}/diff`,
+		snapshot: (slug, buildId, snapshotId) => `${root}/projects/${slug}/builds/${buildId}/diff?snapshot=${encodeURIComponent(snapshotId)}`,
 		library: (slug) => `${root}/projects/${slug}/library`,
 		jobs: (slug) => `${root}/projects/${slug}/jobs`,
 		labels: (slug) => `${root}/projects/${slug}/labels`,
-		label: (slug, key, value) => `${root}/projects/${slug}/labels/${encodeURIComponent(key)}/${encodeURI(value)}`,
+		label: (slug, key, value) => `${root}/projects/${slug}/labels/${encodeURIComponent(key)}/${encodePath(value)}`,
+		component: (slug, importPath) => `${root}/projects/${slug}/components/${encodePath(importPath.replace(/^(?:\.\/)+/u, ""))}`,
 		storybook: (slug) => publishedBaseDomain ? `https://${slug}.${publishedBaseDomain}` : `${root}/projects/${slug}/storybook`,
-		storybookLabel: (slug, key, value) => `${root}/projects/${slug}/storybook/${encodeURIComponent(key)}/${encodeURI(value)}`,
+		storybookLabel: (slug, key, value) => `${root}/projects/${slug}/storybook/${encodeURIComponent(key)}/${encodePath(value)}`,
 		storybookBuild: (slug, buildId) => publishedBaseDomain ? `https://${buildId}.${slug}.${publishedBaseDomain}` : `${root}/projects/${slug}/storybook/build/${buildId}`,
 		settings: (slug) => `${root}/projects/${slug}/settings`,
 		short: (id) => `${root}/_/${id}/`
@@ -43,7 +45,13 @@ function safeImageUrl(value) {
 		return null;
 	}
 }
-//#endregion
+/**
+* Encode a value that may hold slashes (a label value, a branch, an import path) as URL path
+* segments: each segment is escaped (`?`, `#` and `%` included), the slashes stay.
+*/
+function encodePath(value) {
+	return value.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+}
 export { createUrlBuilder, safeImageUrl };
 
 //# sourceMappingURL=urls.mjs.map

package/dist/urls.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"urls.mjs","names":[],"sources":["../src/urls.ts"],"sourcesContent":["/** Type-safe URL builder for project pages and published Storybooks. */\nexport interface UrlBuilder {\n  projectsList(): string;\n  projects(): string;\n  project(slug: string): string;\n  projectsNew(): string;\n  buildsList(slug: string): string;\n  build(slug: string, buildId: string): string;\n  buildDiff(slug: string, buildId: string): string;\n  library(slug: string): string;\n  jobs(slug: string): string;\n  labels(slug: string): string;\n  label(slug: string, key: string, value: string): string;\n  storybook(slug: string): string;\n  storybookLabel(slug: string, key: string, value: string): string;\n  storybookBuild(slug: string, buildId: string): string;\n  settings(slug: string): string;\n  short(id: string): string;\n}\n\n/**\n * Create a URL builder rooted at the given base URL.\n *\n * @param baseUrl - Public root URL of the shelf server.\n * @param publishedBaseDomain - Optional wildcard domain for published Storybooks.\n * @returns The URL builder.\n */\nexport function createUrlBuilder(baseUrl: string, publishedBaseDomain?: string): UrlBuilder {\n  const root = baseUrl.replace(/\\/+$/u, \"\");\n\n  return {\n    projectsList: () => root || \"/\",\n    projects: () => `${root}/projects`,\n    project: (slug) => `${root}/projects/${slug}`,\n    projectsNew: () => `${root}/projects/new`,\n    buildsList: (slug) => `${root}/projects/${slug}/builds`,\n    build: (slug, buildId) => `${root}/projects/${slug}/builds/${buildId}`,\n    buildDiff: (slug, buildId) => `${root}/projects/${slug}/builds/${buildId}/diff`,\n    library: (slug) => `${root}/projects/${slug}/library`,\n    jobs: (slug) => `${root}/projects/${slug}/jobs`,\n    labels: (slug) => `${root}/projects/${slug}/labels`,\n    label: (slug, key, value) =>\n      `${root}/projects/${slug}/labels/${encodeURIComponent(key)}/${encodeURI(value)}`,\n    storybook: (slug) =>\n      publishedBaseDomain\n        ? `https://${slug}.${publishedBaseDomain}`\n        : `${root}/projects/${slug}/storybook`,\n    storybookLabel: (slug, key, value) =>\n      `${root}/projects/${slug}/storybook/${encodeURIComponent(key)}/${encodeURI(value)}`,\n    storybookBuild: (slug, buildId) =>\n      publishedBaseDomain\n        ? `https://${buildId}.${slug}.${publishedBaseDomain}`\n        : `${root}/projects/${slug}/storybook/build/${buildId}`,\n    settings: (slug) => `${root}/projects/${slug}/settings`,\n    short: (id) => `${root}/_/${id}/`,\n  };\n}\n\n/**\n * Embeddable image URL check for IdP-supplied avatars: `https:` and\n * app-relative paths only, so `javascript:`/`data:` payloads fall back.\n */\nexport function safeImageUrl(value: string | undefined): string | null {\n  if (!value) {\n    return null;\n  }\n  if (value.startsWith(\"/\") && !value.startsWith(\"//\")) {\n    return value;\n  }\n  try {\n    const url = new URL(value);\n    return url.protocol === \"https:\" ? value : null;\n  } catch {\n    return null;\n  }\n}\n"],"mappings":";;;;;;;;;;;AA2BA,SAAgB,iBAAiB,SAAiB,qBAA0C;CAC1F,MAAM,OAAO,QAAQ,QAAQ,SAAS,EAAE;CAExC,OAAO;EACL,oBAAoB,QAAQ;EAC5B,gBAAgB,GAAG,KAAK;EACxB,UAAU,SAAS,GAAG,KAAK,YAAY;EACvC,mBAAmB,GAAG,KAAK;EAC3B,aAAa,SAAS,GAAG,KAAK,YAAY,KAAK;EAC/C,QAAQ,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,UAAU;EAC7D,YAAY,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,UAAU,QAAQ;EACzE,UAAU,SAAS,GAAG,KAAK,YAAY,KAAK;EAC5C,OAAO,SAAS,GAAG,KAAK,YAAY,KAAK;EACzC,SAAS,SAAS,GAAG,KAAK,YAAY,KAAK;EAC3C,QAAQ,MAAM,KAAK,UACjB,GAAG,KAAK,YAAY,KAAK,UAAU,mBAAmB,GAAG,EAAE,GAAG,UAAU,KAAK;EAC/E,YAAY,SACV,sBACI,WAAW,KAAK,GAAG,wBACnB,GAAG,KAAK,YAAY,KAAK;EAC/B,iBAAiB,MAAM,KAAK,UAC1B,GAAG,KAAK,YAAY,KAAK,aAAa,mBAAmB,GAAG,EAAE,GAAG,UAAU,KAAK;EAClF,iBAAiB,MAAM,YACrB,sBACI,WAAW,QAAQ,GAAG,KAAK,GAAG,wBAC9B,GAAG,KAAK,YAAY,KAAK,mBAAmB;EAClD,WAAW,SAAS,GAAG,KAAK,YAAY,KAAK;EAC7C,QAAQ,OAAO,GAAG,KAAK,KAAK,GAAG;CACjC;AACF;;;;;AAMA,SAAgB,aAAa,OAA0C;CACrE,IAAI,CAAC,OACH,OAAO;CAET,IAAI,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,WAAW,IAAI,GACjD,OAAO;CAET,IAAI;EAEF,OAAO,IADS,IAAI,KACX,CAAC,CAAC,aAAa,WAAW,QAAQ;CAC7C,QAAQ;EACN,OAAO;CACT;AACF"}
+{"version":3,"file":"urls.mjs","names":[],"sources":["../src/urls.ts"],"sourcesContent":["/** Type-safe URL builder for project pages and published Storybooks. */\nexport interface UrlBuilder {\n  projectsList(): string;\n  projects(): string;\n  project(slug: string): string;\n  projectsNew(): string;\n  buildsList(slug: string): string;\n  build(slug: string, buildId: string): string;\n  buildDiff(slug: string, buildId: string): string;\n  /** Review page of one snapshot: the build's diff page with that snapshot selected. */\n  snapshot(slug: string, buildId: string, snapshotId: string): string;\n  library(slug: string): string;\n  jobs(slug: string): string;\n  labels(slug: string): string;\n  label(slug: string, key: string, value: string): string;\n  /** Stable component page, keyed by the story file's import path. */\n  component(slug: string, importPath: string): string;\n  storybook(slug: string): string;\n  storybookLabel(slug: string, key: string, value: string): string;\n  storybookBuild(slug: string, buildId: string): string;\n  settings(slug: string): string;\n  short(id: string): string;\n}\n\n/**\n * Create a URL builder rooted at the given base URL.\n *\n * @param baseUrl - Public root URL of the shelf server.\n * @param publishedBaseDomain - Optional wildcard domain for published Storybooks.\n * @returns The URL builder.\n */\nexport function createUrlBuilder(baseUrl: string, publishedBaseDomain?: string): UrlBuilder {\n  const root = baseUrl.replace(/\\/+$/u, \"\");\n\n  return {\n    projectsList: () => root || \"/\",\n    projects: () => `${root}/projects`,\n    project: (slug) => `${root}/projects/${slug}`,\n    projectsNew: () => `${root}/projects/new`,\n    buildsList: (slug) => `${root}/projects/${slug}/builds`,\n    build: (slug, buildId) => `${root}/projects/${slug}/builds/${buildId}`,\n    buildDiff: (slug, buildId) => `${root}/projects/${slug}/builds/${buildId}/diff`,\n    snapshot: (slug, buildId, snapshotId) =>\n      `${root}/projects/${slug}/builds/${buildId}/diff?snapshot=${encodeURIComponent(snapshotId)}`,\n    library: (slug) => `${root}/projects/${slug}/library`,\n    jobs: (slug) => `${root}/projects/${slug}/jobs`,\n    labels: (slug) => `${root}/projects/${slug}/labels`,\n    label: (slug, key, value) =>\n      `${root}/projects/${slug}/labels/${encodeURIComponent(key)}/${encodePath(value)}`,\n    component: (slug, importPath) =>\n      `${root}/projects/${slug}/components/${encodePath(importPath.replace(/^(?:\\.\\/)+/u, \"\"))}`,\n    storybook: (slug) =>\n      publishedBaseDomain\n        ? `https://${slug}.${publishedBaseDomain}`\n        : `${root}/projects/${slug}/storybook`,\n    storybookLabel: (slug, key, value) =>\n      `${root}/projects/${slug}/storybook/${encodeURIComponent(key)}/${encodePath(value)}`,\n    storybookBuild: (slug, buildId) =>\n      publishedBaseDomain\n        ? `https://${buildId}.${slug}.${publishedBaseDomain}`\n        : `${root}/projects/${slug}/storybook/build/${buildId}`,\n    settings: (slug) => `${root}/projects/${slug}/settings`,\n    short: (id) => `${root}/_/${id}/`,\n  };\n}\n\n/**\n * Embeddable image URL check for IdP-supplied avatars: `https:` and\n * app-relative paths only, so `javascript:`/`data:` payloads fall back.\n */\nexport function safeImageUrl(value: string | undefined): string | null {\n  if (!value) {\n    return null;\n  }\n  if (value.startsWith(\"/\") && !value.startsWith(\"//\")) {\n    return value;\n  }\n  try {\n    const url = new URL(value);\n    return url.protocol === \"https:\" ? value : null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Encode a value that may hold slashes (a label value, a branch, an import path) as URL path\n * segments: each segment is escaped (`?`, `#` and `%` included), the slashes stay.\n */\nfunction encodePath(value: string): string {\n  return value\n    .split(\"/\")\n    .map((segment) => encodeURIComponent(segment))\n    .join(\"/\");\n}\n"],"mappings":";;;;;;;;;;;AA+BA,SAAgB,iBAAiB,SAAiB,qBAA0C;CAC1F,MAAM,OAAO,QAAQ,QAAQ,SAAS,EAAE;CAExC,OAAO;EACL,oBAAoB,QAAQ;EAC5B,gBAAgB,GAAG,KAAK;EACxB,UAAU,SAAS,GAAG,KAAK,YAAY;EACvC,mBAAmB,GAAG,KAAK;EAC3B,aAAa,SAAS,GAAG,KAAK,YAAY,KAAK;EAC/C,QAAQ,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,UAAU;EAC7D,YAAY,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,UAAU,QAAQ;EACzE,WAAW,MAAM,SAAS,eACxB,GAAG,KAAK,YAAY,KAAK,UAAU,QAAQ,iBAAiB,mBAAmB,UAAU;EAC3F,UAAU,SAAS,GAAG,KAAK,YAAY,KAAK;EAC5C,OAAO,SAAS,GAAG,KAAK,YAAY,KAAK;EACzC,SAAS,SAAS,GAAG,KAAK,YAAY,KAAK;EAC3C,QAAQ,MAAM,KAAK,UACjB,GAAG,KAAK,YAAY,KAAK,UAAU,mBAAmB,GAAG,EAAE,GAAG,WAAW,KAAK;EAChF,YAAY,MAAM,eAChB,GAAG,KAAK,YAAY,KAAK,cAAc,WAAW,WAAW,QAAQ,eAAe,EAAE,CAAC;EACzF,YAAY,SACV,sBACI,WAAW,KAAK,GAAG,wBACnB,GAAG,KAAK,YAAY,KAAK;EAC/B,iBAAiB,MAAM,KAAK,UAC1B,GAAG,KAAK,YAAY,KAAK,aAAa,mBAAmB,GAAG,EAAE,GAAG,WAAW,KAAK;EACnF,iBAAiB,MAAM,YACrB,sBACI,WAAW,QAAQ,GAAG,KAAK,GAAG,wBAC9B,GAAG,KAAK,YAAY,KAAK,mBAAmB;EAClD,WAAW,SAAS,GAAG,KAAK,YAAY,KAAK;EAC7C,QAAQ,OAAO,GAAG,KAAK,KAAK,GAAG;CACjC;AACF;;;;;AAMA,SAAgB,aAAa,OAA0C;CACrE,IAAI,CAAC,OACH,OAAO;CAET,IAAI,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,WAAW,IAAI,GACjD,OAAO;CAET,IAAI;EAEF,OAAO,IADS,IAAI,KACX,CAAC,CAAC,aAAa,WAAW,QAAQ;CAC7C,QAAQ;EACN,OAAO;CACT;AACF;;;;;AAMA,SAAS,WAAW,OAAuB;CACzC,OAAO,MACJ,MAAM,GAAG,CAAC,CACV,KAAK,YAAY,mBAAmB,OAAO,CAAC,CAAC,CAC7C,KAAK,GAAG;AACb"}

package/dist/utils/adaptive-concurrency.d.mts

@@ -0,0 +1,64 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Logger } from "../logger.mjs";
+/** Tuning for {@link AdaptiveConcurrency}. */
+interface AdaptiveOptions {
+  /** Starting in-flight limit. */
+  initial: number;
+  /** Lowest limit (default 1). */
+  min?: number;
+  /** Highest limit. */
+  max: number;
+  /** Event-loop lag p99 (ms) since the previous reading; defaults to a `perf_hooks` histogram. */
+  readLagMs?: () => number;
+  /** p95 latency may grow this much over the first window before the window counts as unhealthy (default 1.25). */
+  latencyTolerance?: number;
+  /** Event-loop lag p99 above this (ms) counts as unhealthy (default 100). */
+  lagLimitMs?: number;
+  /** Windows to hold after a timeout back-off before raising again (default 3). */
+  holdWindows?: number;
+  /** Scoped logger; every limit change is logged with its reason. */
+  logger?: Logger;
+}
+/** What one finished capture reports. */
+interface Observation {
+  durationMs: number;
+  /** The capture hit a navigation/action timeout. */
+  timedOut?: boolean;
+}
+/**
+ * AIMD controller over the number of pages rendering at once.
+ *
+ * Captures are grouped in windows (at least 8, or two per slot). A window with any timeout halves
+ * the limit and holds it there for a few windows; a window whose p95 latency grew more than the
+ * tolerance over the first window, or whose event-loop lag p99 is high, lowers it by one; a healthy
+ * window raises it by one. The first window without timeouts sets the latency baseline, so it only
+ * ever holds.
+ */
+declare class AdaptiveConcurrency {
+  private current;
+  private readonly min;
+  private readonly max;
+  private readonly options;
+  private window;
+  private baselineP95;
+  private hold;
+  private readonly lag;
+  constructor(options: AdaptiveOptions);
+  /** Pages allowed in flight right now. */
+  get limit(): number;
+  /** Record a finished capture; may change {@link limit} at a window boundary. */
+  observe(observation: Observation): void;
+  /** Release the lag monitor. */
+  dispose(): void;
+  private closeWindow;
+  /** Decide what a finished window means; updates the post-back-off hold. */
+  private judge;
+  /** A healthy window: set the baseline, sit out a back-off hold, or raise by one. */
+  private raiseOrHold;
+  private isSlow;
+}
+/** Whether an error is a navigation/action timeout (Playwright and Puppeteer both name it `TimeoutError`). */
+declare function isTimeoutError(error: unknown): boolean;
+export { AdaptiveConcurrency, AdaptiveOptions, Observation, isTimeoutError };
+//# sourceMappingURL=adaptive-concurrency.d.mts.map

package/dist/utils/adaptive-concurrency.mjs

@@ -0,0 +1,148 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { monitorEventLoopDelay } from "node:perf_hooks";
+// src/utils/adaptive-concurrency.ts
+/** Adaptive page concurrency: raise while capture stays healthy, back off when it does not. */
+const MIN_WINDOW = 8;
+/**
+* AIMD controller over the number of pages rendering at once.
+*
+* Captures are grouped in windows (at least 8, or two per slot). A window with any timeout halves
+* the limit and holds it there for a few windows; a window whose p95 latency grew more than the
+* tolerance over the first window, or whose event-loop lag p99 is high, lowers it by one; a healthy
+* window raises it by one. The first window without timeouts sets the latency baseline, so it only
+* ever holds.
+*/
+var AdaptiveConcurrency = class {
+	current;
+	min;
+	max;
+	options;
+	window = [];
+	baselineP95 = null;
+	hold = 0;
+	lag;
+	constructor(options) {
+		this.options = options;
+		this.min = Math.max(1, Math.floor(options.min ?? 1));
+		this.max = Math.max(this.min, Math.floor(options.max));
+		this.current = clamp(Math.floor(options.initial), this.min, this.max);
+		this.lag = options.readLagMs ? {
+			read: options.readLagMs,
+			stop: noop
+		} : eventLoopLagReader();
+	}
+	/** Pages allowed in flight right now. */
+	get limit() {
+		return this.current;
+	}
+	/** Record a finished capture; may change {@link limit} at a window boundary. */
+	observe(observation) {
+		this.window.push(observation);
+		if (this.window.length >= Math.max(MIN_WINDOW, this.current * 2)) this.closeWindow();
+	}
+	/** Release the lag monitor. */
+	dispose() {
+		this.lag.stop();
+	}
+	closeWindow() {
+		const samples = this.window;
+		this.window = [];
+		const stats = {
+			p95: percentile(samples.map((sample) => sample.durationMs), .95),
+			timeouts: samples.filter((sample) => sample.timedOut).length,
+			lagP99: this.lag.read()
+		};
+		const from = this.current;
+		const verdict = this.judge(stats);
+		if (stats.timeouts === 0) this.baselineP95 ??= stats.p95;
+		this.current = verdict.halve ? Math.max(this.min, Math.floor(from / 2)) : clamp(from + verdict.delta, this.min, this.max);
+		if (this.current !== from) this.options.logger?.info({
+			from,
+			to: this.current,
+			reason: verdict.reason,
+			...roundedStats(stats)
+		}, "capture concurrency adjusted");
+	}
+	/** Decide what a finished window means; updates the post-back-off hold. */
+	judge(window) {
+		if (window.timeouts > 0) {
+			this.hold = this.options.holdWindows ?? 3;
+			return {
+				delta: 0,
+				halve: true,
+				reason: "timeouts"
+			};
+		}
+		const slow = this.isSlow(window.p95);
+		if (slow || window.lagP99 > (this.options.lagLimitMs ?? 100)) return {
+			delta: -1,
+			halve: false,
+			reason: slow ? "latency" : "event-loop lag"
+		};
+		return this.raiseOrHold();
+	}
+	/** A healthy window: set the baseline, sit out a back-off hold, or raise by one. */
+	raiseOrHold() {
+		if (this.baselineP95 === null) return {
+			delta: 0,
+			halve: false,
+			reason: "baseline"
+		};
+		if (this.hold > 0) {
+			this.hold -= 1;
+			return {
+				delta: 0,
+				halve: false,
+				reason: "holding after back-off"
+			};
+		}
+		return {
+			delta: 1,
+			halve: false,
+			reason: "healthy"
+		};
+	}
+	isSlow(p95) {
+		return this.baselineP95 !== null && p95 > this.baselineP95 * (this.options.latencyTolerance ?? 1.25);
+	}
+};
+function roundedStats(stats) {
+	return {
+		p95Ms: Math.round(stats.p95),
+		lagP99Ms: Math.round(stats.lagP99),
+		timeouts: stats.timeouts
+	};
+}
+/** Whether an error is a navigation/action timeout (Playwright and Puppeteer both name it `TimeoutError`). */
+function isTimeoutError(error) {
+	if (!(error instanceof Error)) return false;
+	return error.name === "TimeoutError" || /\btimed? ?out\b/iu.test(error.message);
+}
+function noop() {}
+function clamp(value, min, max) {
+	return Math.min(max, Math.max(min, value));
+}
+function percentile(values, fraction) {
+	const sorted = values.toSorted((left, right) => left - right);
+	return sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * fraction))] ?? 0;
+}
+/** p99 event-loop delay (ms) since the previous read, from a `perf_hooks` histogram. */
+function eventLoopLagReader() {
+	const histogram = monitorEventLoopDelay({ resolution: 10 });
+	histogram.enable();
+	return {
+		read: () => {
+			const lag = histogram.percentile(99) / 1e6;
+			histogram.reset();
+			return lag;
+		},
+		stop: () => {
+			histogram.disable();
+		}
+	};
+}
+export { AdaptiveConcurrency, isTimeoutError };
+
+//# sourceMappingURL=adaptive-concurrency.mjs.map

package/dist/utils/adaptive-concurrency.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive-concurrency.mjs","names":[],"sources":["../../src/utils/adaptive-concurrency.ts"],"sourcesContent":["/** Adaptive page concurrency: raise while capture stays healthy, back off when it does not. */\nimport { monitorEventLoopDelay } from \"node:perf_hooks\";\nimport type { Logger } from \"../logger.ts\";\n\n/** Tuning for {@link AdaptiveConcurrency}. */\nexport interface AdaptiveOptions {\n  /** Starting in-flight limit. */\n  initial: number;\n  /** Lowest limit (default 1). */\n  min?: number;\n  /** Highest limit. */\n  max: number;\n  /** Event-loop lag p99 (ms) since the previous reading; defaults to a `perf_hooks` histogram. */\n  readLagMs?: () => number;\n  /** p95 latency may grow this much over the first window before the window counts as unhealthy (default 1.25). */\n  latencyTolerance?: number;\n  /** Event-loop lag p99 above this (ms) counts as unhealthy (default 100). */\n  lagLimitMs?: number;\n  /** Windows to hold after a timeout back-off before raising again (default 3). */\n  holdWindows?: number;\n  /** Scoped logger; every limit change is logged with its reason. */\n  logger?: Logger;\n}\n\n/** What one finished capture reports. */\nexport interface Observation {\n  durationMs: number;\n  /** The capture hit a navigation/action timeout. */\n  timedOut?: boolean;\n}\n\nconst MIN_WINDOW = 8;\n\n/**\n * AIMD controller over the number of pages rendering at once.\n *\n * Captures are grouped in windows (at least 8, or two per slot). A window with any timeout halves\n * the limit and holds it there for a few windows; a window whose p95 latency grew more than the\n * tolerance over the first window, or whose event-loop lag p99 is high, lowers it by one; a healthy\n * window raises it by one. The first window without timeouts sets the latency baseline, so it only\n * ever holds.\n */\nexport class AdaptiveConcurrency {\n  private current: number;\n  private readonly min: number;\n  private readonly max: number;\n  private readonly options: AdaptiveOptions;\n  private window: Observation[] = [];\n  private baselineP95: number | null = null;\n  private hold = 0;\n  private readonly lag: { read: () => number; stop: () => void };\n\n  constructor(options: AdaptiveOptions) {\n    this.options = options;\n    this.min = Math.max(1, Math.floor(options.min ?? 1));\n    this.max = Math.max(this.min, Math.floor(options.max));\n    this.current = clamp(Math.floor(options.initial), this.min, this.max);\n    this.lag = options.readLagMs ? { read: options.readLagMs, stop: noop } : eventLoopLagReader();\n  }\n\n  /** Pages allowed in flight right now. */\n  get limit(): number {\n    return this.current;\n  }\n\n  /** Record a finished capture; may change {@link limit} at a window boundary. */\n  observe(observation: Observation): void {\n    this.window.push(observation);\n    if (this.window.length >= Math.max(MIN_WINDOW, this.current * 2)) {\n      this.closeWindow();\n    }\n  }\n\n  /** Release the lag monitor. */\n  dispose(): void {\n    this.lag.stop();\n  }\n\n  private closeWindow(): void {\n    const samples = this.window;\n    this.window = [];\n    const stats = {\n      p95: percentile(\n        samples.map((sample) => sample.durationMs),\n        0.95,\n      ),\n      timeouts: samples.filter((sample) => sample.timedOut).length,\n      lagP99: this.lag.read(),\n    };\n    const from = this.current;\n    const verdict = this.judge(stats);\n    // A window with a timeout carries the timeout's duration in its p95: never a baseline.\n    if (stats.timeouts === 0) {\n      this.baselineP95 ??= stats.p95;\n    }\n    this.current = verdict.halve\n      ? Math.max(this.min, Math.floor(from / 2))\n      : clamp(from + verdict.delta, this.min, this.max);\n    if (this.current !== from) {\n      this.options.logger?.info(\n        { from, to: this.current, reason: verdict.reason, ...roundedStats(stats) },\n        \"capture concurrency adjusted\",\n      );\n    }\n  }\n\n  /** Decide what a finished window means; updates the post-back-off hold. */\n  private judge(window: WindowStats): Verdict {\n    if (window.timeouts > 0) {\n      this.hold = this.options.holdWindows ?? 3;\n      return { delta: 0, halve: true, reason: \"timeouts\" };\n    }\n    const slow = this.isSlow(window.p95);\n    if (slow || window.lagP99 > (this.options.lagLimitMs ?? 100)) {\n      return { delta: -1, halve: false, reason: slow ? \"latency\" : \"event-loop lag\" };\n    }\n    return this.raiseOrHold();\n  }\n\n  /** A healthy window: set the baseline, sit out a back-off hold, or raise by one. */\n  private raiseOrHold(): Verdict {\n    if (this.baselineP95 === null) {\n      return { delta: 0, halve: false, reason: \"baseline\" };\n    }\n    if (this.hold > 0) {\n      this.hold -= 1;\n      return { delta: 0, halve: false, reason: \"holding after back-off\" };\n    }\n    return { delta: 1, halve: false, reason: \"healthy\" };\n  }\n\n  private isSlow(p95: number): boolean {\n    return (\n      this.baselineP95 !== null && p95 > this.baselineP95 * (this.options.latencyTolerance ?? 1.25)\n    );\n  }\n}\n\ninterface WindowStats {\n  p95: number;\n  timeouts: number;\n  lagP99: number;\n}\n\nfunction roundedStats(stats: WindowStats): Record<string, number> {\n  return {\n    p95Ms: Math.round(stats.p95),\n    lagP99Ms: Math.round(stats.lagP99),\n    timeouts: stats.timeouts,\n  };\n}\n\ninterface Verdict {\n  delta: number;\n  halve: boolean;\n  reason: string;\n}\n\n/** Whether an error is a navigation/action timeout (Playwright and Puppeteer both name it `TimeoutError`). */\nexport function isTimeoutError(error: unknown): boolean {\n  if (!(error instanceof Error)) {\n    return false;\n  }\n  return error.name === \"TimeoutError\" || /\\btimed? ?out\\b/iu.test(error.message);\n}\n\nfunction noop(): void {}\n\nfunction clamp(value: number, min: number, max: number): number {\n  return Math.min(max, Math.max(min, value));\n}\n\nfunction percentile(values: number[], fraction: number): number {\n  const sorted = values.toSorted((left, right) => left - right);\n  return sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * fraction))] ?? 0;\n}\n\n/** p99 event-loop delay (ms) since the previous read, from a `perf_hooks` histogram. */\nfunction eventLoopLagReader(): { read: () => number; stop: () => void } {\n  const histogram = monitorEventLoopDelay({ resolution: 10 });\n  histogram.enable();\n  return {\n    read: () => {\n      const lag = histogram.percentile(99) / 1e6;\n      histogram.reset();\n      return lag;\n    },\n    stop: () => {\n      histogram.disable();\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/utils/connect-retry.d.mts

@@ -0,0 +1,26 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+/** Retrying a connection to a remote browser service (ADR 0007, decision 4). */
+/** Options of {@link retryConnect}. */
+interface RetryConnectOptions {
+  /** Retries after the first attempt. */
+  retries: number;
+  /** Delay before the first retry in ms; doubles each time, with jitter, capped at 10 s. */
+  backoffMs: number;
+  /** Whether an error is worth another attempt; defaults to {@link isRetryableConnectError}. */
+  retryable?: (error: unknown) => boolean;
+  /** Called before each retry with the error, the retry's number (from 1) and its delay. */
+  onRetry?: (error: unknown, retry: number, delayMs: number) => void;
+  /** Injectable for tests. */
+  sleep?: (ms: number) => Promise<void>;
+}
+/** Whether a connect error is worth retrying: connection-level, not a configuration mistake. */
+declare function isRetryableConnectError(error: unknown): boolean;
+/**
+ * Run `connect`, retrying a connection-level failure with exponential backoff, so a provider
+ * outage or a full plan is absorbed here and crash isolation only ever sees a browser that died
+ * while rendering. The last error is thrown once the retries are spent.
+ */
+declare function retryConnect<T>(connect: () => Promise<T>, options: RetryConnectOptions): Promise<T>;
+export { RetryConnectOptions, isRetryableConnectError, retryConnect };
+//# sourceMappingURL=connect-retry.d.mts.map

package/dist/utils/connect-retry.mjs

@@ -0,0 +1,42 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/utils/connect-retry.ts
+const MAX_DELAY_MS = 1e4;
+/** Errors that no retry fixes: a refused credential, a missing endpoint, mismatched versions. */
+const PERMANENT = /\b(?:401|403|404|428|unauthorized|forbidden|version mismatch|invalid (?:token|credentials)|not found)\b/iu;
+/** Errors of the connection itself: refused, dropped, timed out, or a service with no free session. */
+const CONNECTION = /(?:ECONNREFUSED|ECONNRESET|EPIPE|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|EHOSTUNREACH|socket hang up|websocket error|connection (?:closed|refused|reset)|timeout|timed out|capacity|too many|queue(?:d)? full|no (?:free )?(?:session|browser)|\b(?:408|425|429|500|502|503|504)\b)/iu;
+/** Whether a connect error is worth retrying: connection-level, not a configuration mistake. */
+function isRetryableConnectError(error) {
+	const text = error instanceof Error ? error.message : String(error);
+	return !PERMANENT.test(text) && CONNECTION.test(text);
+}
+/**
+* Run `connect`, retrying a connection-level failure with exponential backoff, so a provider
+* outage or a full plan is absorbed here and crash isolation only ever sees a browser that died
+* while rendering. The last error is thrown once the retries are spent.
+*/
+async function retryConnect(connect, options) {
+	const sleep = options.sleep ?? sleepFor;
+	for (let retry = 0;; retry += 1) try {
+		return await connect();
+	} catch (error) {
+		if (retry >= options.retries || !(options.retryable ?? isRetryableConnectError)(error)) throw error;
+		const delayMs = Math.min(MAX_DELAY_MS, options.backoffMs * 2 ** retry) * jitter();
+		options.onRetry?.(error, retry + 1, Math.round(delayMs));
+		await sleep(delayMs);
+	}
+}
+/** 0.75 to 1.25: providers refusing for capacity should not see every shard retry in step. */
+function jitter() {
+	return .75 + Math.random() * .5;
+}
+async function sleepFor(ms) {
+	await new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+export { isRetryableConnectError, retryConnect };
+
+//# sourceMappingURL=connect-retry.mjs.map

package/dist/utils/connect-retry.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-retry.mjs","names":[],"sources":["../../src/utils/connect-retry.ts"],"sourcesContent":["/** Retrying a connection to a remote browser service (ADR 0007, decision 4). */\n\n/** Options of {@link retryConnect}. */\nexport interface RetryConnectOptions {\n  /** Retries after the first attempt. */\n  retries: number;\n  /** Delay before the first retry in ms; doubles each time, with jitter, capped at 10 s. */\n  backoffMs: number;\n  /** Whether an error is worth another attempt; defaults to {@link isRetryableConnectError}. */\n  retryable?: (error: unknown) => boolean;\n  /** Called before each retry with the error, the retry's number (from 1) and its delay. */\n  onRetry?: (error: unknown, retry: number, delayMs: number) => void;\n  /** Injectable for tests. */\n  sleep?: (ms: number) => Promise<void>;\n}\n\nconst MAX_DELAY_MS = 10_000;\n\n/** Errors that no retry fixes: a refused credential, a missing endpoint, mismatched versions. */\nconst PERMANENT =\n  /\\b(?:401|403|404|428|unauthorized|forbidden|version mismatch|invalid (?:token|credentials)|not found)\\b/iu;\n\n/** Errors of the connection itself: refused, dropped, timed out, or a service with no free session. */\nconst CONNECTION =\n  /(?:ECONNREFUSED|ECONNRESET|EPIPE|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|EHOSTUNREACH|socket hang up|websocket error|connection (?:closed|refused|reset)|timeout|timed out|capacity|too many|queue(?:d)? full|no (?:free )?(?:session|browser)|\\b(?:408|425|429|500|502|503|504)\\b)/iu;\n\n/** Whether a connect error is worth retrying: connection-level, not a configuration mistake. */\nexport function isRetryableConnectError(error: unknown): boolean {\n  const text = error instanceof Error ? error.message : String(error);\n  return !PERMANENT.test(text) && CONNECTION.test(text);\n}\n\n/**\n * Run `connect`, retrying a connection-level failure with exponential backoff, so a provider\n * outage or a full plan is absorbed here and crash isolation only ever sees a browser that died\n * while rendering. The last error is thrown once the retries are spent.\n */\nexport async function retryConnect<T>(\n  connect: () => Promise<T>,\n  options: RetryConnectOptions,\n): Promise<T> {\n  const sleep = options.sleep ?? sleepFor;\n  for (let retry = 0; ; retry += 1) {\n    try {\n      // oxlint-disable-next-line eslint/no-await-in-loop -- attempts are sequential by design\n      return await connect();\n    } catch (error) {\n      if (retry >= options.retries || !(options.retryable ?? isRetryableConnectError)(error)) {\n        throw error;\n      }\n      const delayMs = Math.min(MAX_DELAY_MS, options.backoffMs * 2 ** retry) * jitter();\n      options.onRetry?.(error, retry + 1, Math.round(delayMs));\n      // oxlint-disable-next-line eslint/no-await-in-loop -- backoff between sequential attempts\n      await sleep(delayMs);\n    }\n  }\n}\n\n/** 0.75 to 1.25: providers refusing for capacity should not see every shard retry in step. */\nfunction jitter(): number {\n  return 0.75 + Math.random() * 0.5;\n}\n\nasync function sleepFor(ms: number): Promise<void> {\n  await new Promise<void>((resolve) => {\n    setTimeout(resolve, ms);\n  });\n}\n"],"mappings":";;;;AAgBA,MAAM,eAAe;;AAGrB,MAAM,YACJ;;AAGF,MAAM,aACJ;;AAGF,SAAgB,wBAAwB,OAAyB;CAC/D,MAAM,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;CAClE,OAAO,CAAC,UAAU,KAAK,IAAI,KAAK,WAAW,KAAK,IAAI;AACtD;;;;;;AAOA,eAAsB,aACpB,SACA,SACY;CACZ,MAAM,QAAQ,QAAQ,SAAS;CAC/B,KAAK,IAAI,QAAQ,IAAK,SAAS,GAC7B,IAAI;EAEF,OAAO,MAAM,QAAQ;CACvB,SAAS,OAAO;EACd,IAAI,SAAS,QAAQ,WAAW,EAAE,QAAQ,aAAa,wBAAA,CAAyB,KAAK,GACnF,MAAM;EAER,MAAM,UAAU,KAAK,IAAI,cAAc,QAAQ,YAAY,KAAK,KAAK,IAAI,OAAO;EAChF,QAAQ,UAAU,OAAO,QAAQ,GAAG,KAAK,MAAM,OAAO,CAAC;EAEvD,MAAM,MAAM,OAAO;CACrB;AAEJ;;AAGA,SAAS,SAAiB;CACxB,OAAO,MAAO,KAAK,OAAO,IAAI;AAChC;AAEA,eAAe,SAAS,IAA2B;CACjD,MAAM,IAAI,SAAe,YAAY;EACnC,WAAW,SAAS,EAAE;CACxB,CAAC;AACH"}

package/dist/utils/encrypt.d.mts

@@ -1,6 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/utils/encrypt.d.ts
 /** Current server secret plus the one it replaced, kept only to decrypt older rows. */
 interface SecretKeys {
   current: string;
@@ -43,6 +42,5 @@ declare function decryptWithKey(input: SecretInput, ciphertext: string): {
  * rotation hint. A missing secret keeps its own configuration error.
  */
 declare function decryptCredential(input: SecretInput, ciphertext: string): string;
-//#endregion
 export { KeyUsed, SecretInput, SecretKeys, UndecryptableCredentialError, decrypt, decryptCredential, decryptWithKey, encrypt };
 //# sourceMappingURL=encrypt.d.mts.map

package/dist/utils/encrypt.mjs

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
-//#region src/utils/encrypt.ts
+// src/utils/encrypt.ts
 /** Thrown when a stored credential cannot be decrypted with any configured key. */
 var UndecryptableCredentialError = class extends Error {
 	constructor(cause) {
@@ -97,7 +97,6 @@ function decryptWith(secret, ciphertext) {
 function deriveKey(secret) {
 	return createHash("sha256").update(secret).digest();
 }
-//#endregion
 export { UndecryptableCredentialError, decrypt, decryptCredential, decryptWithKey, encrypt };
 
 //# sourceMappingURL=encrypt.mjs.map

package/dist/utils/environment.d.mts

@@ -0,0 +1,17 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { CaptureEnvironment } from "../adapter/capture-runner.mjs";
+/**
+ * Digest of the installed system font families (`fc-list`), or undefined where fontconfig is not
+ * available. Cached for the process (fonts do not change under a running server), except a failed
+ * run such as a timeout under load: that is retried next time rather than reported as "no fonts"
+ * for the life of the process.
+ */
+declare function systemFontsHash(): Promise<string | undefined>;
+/**
+ * The environment a runner captured in: browser build, host platform, device scale factor and a
+ * font digest. Runners call this once per render with the version their driver reports.
+ */
+declare function detectCaptureEnvironment(browserVersion?: string, deviceScaleFactor?: number): Promise<CaptureEnvironment>;
+export { detectCaptureEnvironment, systemFontsHash };
+//# sourceMappingURL=environment.d.mts.map