@storyshelf/runner-puppeteer 0.6.2 → 0.8.0

package/README.md

@@ -19,11 +19,83 @@ npm install @storyshelf/runner-puppeteer
 ```ts
 import { createPuppeteerCaptureRunner } from "@storyshelf/runner-puppeteer";
 
-const capture = createPuppeteerCaptureRunner();
+const runner = createPuppeteerCaptureRunner({
+  // defaults to the test-bundled chrome-headless-shell; point at your own Chromium when needed
+  executablePath: process.env.CHROME_PATH,
+});
 ```
 
+Hand the runner to the server:
+
+```ts
+import { createShelfApp } from "@storyshelf/app";
+import { createPuppeteerCaptureRunner } from "@storyshelf/runner-puppeteer";
+
+const app = createShelfApp({
+  database,
+  storage,
+  testing: { runner: createPuppeteerCaptureRunner() },
+});
+```
+
+## Browsers
+
+`browsers` lists the targets the runner offers, default first (ADR 0007); omitted it is `["chromium"]`.
+
+```ts
+import { createPuppeteerCaptureRunner, local } from "@storyshelf/runner-puppeteer";
+
+createPuppeteerCaptureRunner({
+  executablePath: "/usr/bin/chromium", // what the bare "chromium" entry launches
+  browsers: ["chromium", local("chrome", { executablePath: "/usr/bin/google-chrome" })],
+});
+```
+
+`puppeteer-core` ships no browser, so a target is `ready` only when it has an executable that exists (the entry's own, the runner's `executablePath` for `chromium`, or `PUPPETEER_EXECUTABLE_PATH`); otherwise it is `unavailable` with that reason on **System → Capture browsers**. Bare `"chrome"` without its own `executablePath` throws when the runner is created, and `local("firefox")` and `local("webkit")` throw too: this runner drives Chromium-family engines only. A launch that fails marks its target unavailable and fails the job at once.
+
+## Remote browsers
+
+`cdp({ name, endpoint, headers, sessions })` from `@storyshelf/runner-puppeteer/remote` is a Chrome DevTools Protocol endpoint (Browserless, Cloudflare Browser Rendering, a Chrome with remote debugging). The runner calls `puppeteer.connect` and offers `chromium@<name>` (and `chrome@<name>` with `engines`):
+
+```ts
+import { createPuppeteerCaptureRunner } from "@storyshelf/runner-puppeteer";
+import { cdp } from "@storyshelf/runner-puppeteer/remote";
+
+createPuppeteerCaptureRunner({
+  executablePath: "/usr/bin/chromium",
+  browsers: [
+    "chromium",
+    cdp({
+      name: "cloudflare",
+      endpoint: "wss://…",
+      headers: { authorization: `Bearer ${token}` },
+      sessions: 4,
+    }),
+  ],
+});
+```
+
+A service that must be woken or started first passes `connect` as a function (with `release`, `retry` and `timeouts`) instead of `endpoint`: it receives the run's `buildId`, `runId`, `shardIndex`, `purpose` and a cancel `signal` and returns `{ endpoint, headers, lease }`, and `release(lease, { outcome, error })` runs once when the render ends, fails or is cancelled. `RemoteConnectError` and `refCounted` come from the same `./remote` subpath; see "Scale to zero" in [Remote browsers](https://storyshelf.js.org/guides/remote-browsers/).
+
+A Puppeteer remote browser cannot route back to the host, so every remote target needs a signed Storybook URL (`reach: "url"`); it stays `unavailable` until a `secret` and a confirmed public origin exist, then the server hands the runner a short-lived signed URL (`<public origin>/_s/<token>/`) for every render pass, and the runner refuses to start one without it. See [Signed Storybook URLs](https://storyshelf.js.org/guides/remote-browsers/#signed-storybook-urls). The target's environment is measured inside the browser, `sessions` is the per-target page cap shared across the process, and connection failures are retried with backoff. Details in [Remote browsers](https://storyshelf.js.org/guides/remote-browsers/).
+
+## Concurrency and memory
+
+Pages render through a bounded pool instead of all at once. The default is sized from the detected CPU and memory, container limits included (one page on 0.5–1 vCPU hosts, up to 4); override with `createPuppeteerCaptureRunner({ concurrency })` or `STORYSHELF_CAPTURE_CONCURRENCY`. The per-page timeout scales with CPU (30 s, 60 s under 2 CPUs, 90 s under 1 CPU); override with `navigationTimeoutMs` or `STORYSHELF_NAVIGATION_TIMEOUT_MS`. Every 150 captures the local browser is closed and relaunched to bound its slow memory growth (`recycleBrowserEvery`, or `STORYSHELF_BROWSER_RECYCLE_EVERY`; `0` disables). A connected remote target is instead disconnected and reconnected, never sent `Browser.close`, so sibling clients and the provider machine survive; a run closes only the pages and contexts it created and releases any provider lease once with the first outcome. Each render logs a `capture sizing` line with the detected CPUs, memory and resulting settings. When the orchestrator passes `onCapture`, each screenshot is handed over as soon as it is taken instead of being collected in the result, so memory does not grow with the story count. Set `reusePages: true` (or `STORYSHELF_REUSE_PAGES=1`) to reuse a pool of reset pages (own context each; storage, cookies and IndexedDB cleared between captures; failed pages discarded). It is off by default. The default launch args add low-memory flags (`--disable-dev-shm-usage`, `--disable-extensions`, `--disable-background-networking`, `--mute-audio`); passing your own `args` replaces them. See the deployment guide's "Sizing memory for capture" section.
+
 See the [StoryShelf documentation](https://github.com/GuptaSiddhant/StoryShelf#readme) for configuration details.
 
+## Puppeteer vs Playwright
+
+| Aspect       | `runner-puppeteer`                                                                                 | `runner-playwright`                                 |
+| ------------ | -------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| Engine       | `puppeteer-core` + `chrome-headless-shell` (Chromium only)                                         | Playwright (`chromium`/`firefox`/`webkit`/`chrome`) |
+| Selected via | `browsers` runner option (Chromium family only); projects pick from what it offers                 | `browsers` runner option; projects pick from it     |
+| Image size   | Smaller — no bundled Firefox/WebKit                                                                | Larger                                              |
+| Capabilities | Same orchestrator-owned controls: `play`, `delay`, `diffThreshold`, `viewports`, a11y (axe), burst | Identical controls                                  |
+
+Both runners implement the same pure `CaptureRunner` contract. The orchestrator (`@storyshelf/core`, ADR 0015) owns build loading, archive extraction, story discovery, and persistence and delegates only the screenshotting to the runner, so switching is a one-line factory swap.
+
 ## License
 
 MIT

package/dist/a11y.mjs

@@ -1,31 +1,31 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/a11y.ts
-/** Run lightweight a11y checks inside the page context. */
-async function checkA11y(page) {
-	return await page.evaluate(inPageA11y);
-}
+import { axeInjectionScript, inPageReadA11yParameters, inPageRunAxe, loadAxeSource, mapAxeViolations, resolveA11yRun } from "@storyshelf/core/capture";
+// src/a11y.ts
+/** axe-core accessibility checks for captured pages (ADR 0004 §6). */
 /**
-* Runs inside the browser. Playwright/Puppeteer serialize only this function's source, so it must
-* not reference anything from this module (helpers, imports): split it up and the page throws
-* `ReferenceError`. `a11y.test.ts` evaluates it in a scope without module bindings to guard that.
+* Run axe over the story root and return one annotation string per violation (worst first).
+* Honours `parameters.a11y` (`disable`, `test: "off"`, `config`, `options`, `element`/`context`;
+* function values cannot be read from the page and are dropped, with one warning). Results are annotations: nothing
+* here fails a build. If axe cannot be loaded or injected the result is one visible annotation
+* (`axe unavailable: <reason>`) instead of a silent pass.
 */
-function inPageA11y() {
-	const doc = globalThis.document;
-	const violations = [];
-	const root = doc?.querySelector("#storybook-root");
-	if (!root) return violations;
-	for (const img of root.querySelectorAll("img:not([alt])")) violations.push(`img missing alt: ${img.outerHTML.slice(0, 120)}`);
-	for (const btn of root.querySelectorAll("button")) if (!(btn.hasAttribute("aria-label") || btn.hasAttribute("aria-labelledby") || (btn.textContent ?? "").trim() !== "")) violations.push(`button missing label: ${btn.outerHTML.slice(0, 120)}`);
-	for (const anchor of root.querySelectorAll("a")) if (!anchor.hasAttribute("href")) violations.push(`a missing href: ${anchor.outerHTML.slice(0, 120)}`);
-	for (const input of root.querySelectorAll("input, select, textarea")) {
-		const el = input;
-		if (!(el.type === "hidden" || el.hasAttribute("aria-label") || el.hasAttribute("aria-labelledby") || el.id === "" || Boolean(doc.querySelector(`label[for="${el.id}"]`)))) violations.push(`input missing label: ${el.outerHTML.slice(0, 120)}`);
+async function checkA11y(page, logger, storyId) {
+	try {
+		const read = await page.evaluate(inPageReadA11yParameters);
+		if (read && read.dropped > 0) logger?.warn({
+			storyId,
+			dropped: read.dropped
+		}, "parameters.a11y: function, symbol or undefined values were omitted; axe uses the remaining configuration");
+		const plan = resolveA11yRun(read?.params);
+		if (plan.skip) return [];
+		await page.evaluate(axeInjectionScript(await loadAxeSource()));
+		return mapAxeViolations(await page.evaluate(inPageRunAxe, plan));
+	} catch (error) {
+		return [`axe unavailable: ${error instanceof Error ? error.message : String(error)}`];
 	}
-	return violations.slice(0, 10);
 }
-//#endregion
-export { checkA11y, inPageA11y };
+export { checkA11y };
 
 //# sourceMappingURL=a11y.mjs.map

package/dist/a11y.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"a11y.mjs","names":[],"sources":["../src/a11y.ts"],"sourcesContent":["/** Accessibility checks for captured pages. */\n\nimport type { Page } from \"puppeteer-core\";\n\n/** Run lightweight a11y checks inside the page context. */\nexport async function checkA11y(page: Page): Promise<string[]> {\n  return await page.evaluate(inPageA11y);\n}\n\n/**\n * Runs inside the browser. Playwright/Puppeteer serialize only this function's source, so it must\n * not reference anything from this module (helpers, imports): split it up and the page throws\n * `ReferenceError`. `a11y.test.ts` evaluates it in a scope without module bindings to guard that.\n */\n// oxlint-disable-next-line eslint/max-statements, eslint/max-lines-per-function, eslint/complexity -- must stay one self-contained function (see above)\nexport function inPageA11y(): string[] {\n  const doc = globalThis.document;\n  const violations: string[] = [];\n  const root = doc?.querySelector(\"#storybook-root\");\n  if (!root) return violations;\n  for (const img of root.querySelectorAll(\"img:not([alt])\")) {\n    violations.push(`img missing alt: ${img.outerHTML.slice(0, 120)}`);\n  }\n  for (const btn of root.querySelectorAll(\"button\")) {\n    const labelled =\n      btn.hasAttribute(\"aria-label\") ||\n      btn.hasAttribute(\"aria-labelledby\") ||\n      (btn.textContent ?? \"\").trim() !== \"\";\n    if (!labelled) violations.push(`button missing label: ${btn.outerHTML.slice(0, 120)}`);\n  }\n  for (const anchor of root.querySelectorAll(\"a\")) {\n    if (!anchor.hasAttribute(\"href\"))\n      violations.push(`a missing href: ${anchor.outerHTML.slice(0, 120)}`);\n  }\n  for (const input of root.querySelectorAll(\"input, select, textarea\")) {\n    const el = input as HTMLInputElement;\n    const labelled =\n      el.type === \"hidden\" ||\n      el.hasAttribute(\"aria-label\") ||\n      el.hasAttribute(\"aria-labelledby\") ||\n      el.id === \"\" ||\n      Boolean(doc.querySelector(`label[for=\"${el.id}\"]`));\n    if (!labelled) violations.push(`input missing label: ${el.outerHTML.slice(0, 120)}`);\n  }\n  return violations.slice(0, 10);\n}\n"],"mappings":";;;;;AAKA,eAAsB,UAAU,MAA+B;CAC7D,OAAO,MAAM,KAAK,SAAS,UAAU;AACvC;;;;;;AAQA,SAAgB,aAAuB;CACrC,MAAM,MAAM,WAAW;CACvB,MAAM,aAAuB,CAAC;CAC9B,MAAM,OAAO,KAAK,cAAc,iBAAiB;CACjD,IAAI,CAAC,MAAM,OAAO;CAClB,KAAK,MAAM,OAAO,KAAK,iBAAiB,gBAAgB,GACtD,WAAW,KAAK,oBAAoB,IAAI,UAAU,MAAM,GAAG,GAAG,GAAG;CAEnE,KAAK,MAAM,OAAO,KAAK,iBAAiB,QAAQ,GAK9C,IAAI,EAHF,IAAI,aAAa,YAAY,KAC7B,IAAI,aAAa,iBAAiB,MACjC,IAAI,eAAe,GAAA,CAAI,KAAK,MAAM,KACtB,WAAW,KAAK,yBAAyB,IAAI,UAAU,MAAM,GAAG,GAAG,GAAG;CAEvF,KAAK,MAAM,UAAU,KAAK,iBAAiB,GAAG,GAC5C,IAAI,CAAC,OAAO,aAAa,MAAM,GAC7B,WAAW,KAAK,mBAAmB,OAAO,UAAU,MAAM,GAAG,GAAG,GAAG;CAEvE,KAAK,MAAM,SAAS,KAAK,iBAAiB,yBAAyB,GAAG;EACpE,MAAM,KAAK;EAOX,IAAI,EALF,GAAG,SAAS,YACZ,GAAG,aAAa,YAAY,KAC5B,GAAG,aAAa,iBAAiB,KACjC,GAAG,OAAO,MACV,QAAQ,IAAI,cAAc,cAAc,GAAG,GAAG,GAAG,CAAC,IACrC,WAAW,KAAK,wBAAwB,GAAG,UAAU,MAAM,GAAG,GAAG,GAAG;CACrF;CACA,OAAO,WAAW,MAAM,GAAG,EAAE;AAC/B"}
+{"version":3,"file":"a11y.mjs","names":[],"sources":["../src/a11y.ts"],"sourcesContent":["/** axe-core accessibility checks for captured pages (ADR 0004 §6). */\n\nimport {\n  axeInjectionScript,\n  inPageReadA11yParameters,\n  inPageRunAxe,\n  loadAxeSource,\n  mapAxeViolations,\n  resolveA11yRun,\n} from \"@storyshelf/core/capture\";\nimport type { Logger } from \"@storyshelf/core/logger\";\nimport type { Page } from \"puppeteer-core\";\n\n/**\n * Run axe over the story root and return one annotation string per violation (worst first).\n * Honours `parameters.a11y` (`disable`, `test: \"off\"`, `config`, `options`, `element`/`context`;\n * function values cannot be read from the page and are dropped, with one warning). Results are annotations: nothing\n * here fails a build. If axe cannot be loaded or injected the result is one visible annotation\n * (`axe unavailable: <reason>`) instead of a silent pass.\n */\nexport async function checkA11y(page: Page, logger?: Logger, storyId?: string): Promise<string[]> {\n  try {\n    const read = await page.evaluate(inPageReadA11yParameters);\n    if (read && read.dropped > 0)\n      logger?.warn(\n        { storyId, dropped: read.dropped },\n        \"parameters.a11y: function, symbol or undefined values were omitted; axe uses the remaining configuration\",\n      );\n    const plan = resolveA11yRun(read?.params);\n    if (plan.skip) return [];\n    // Source string over CDP `Runtime.evaluate`: not CSP-bound and works on remote browsers.\n    await page.evaluate(axeInjectionScript(await loadAxeSource()));\n    return mapAxeViolations(await page.evaluate(inPageRunAxe, plan));\n  } catch (error) {\n    return [`axe unavailable: ${error instanceof Error ? error.message : String(error)}`];\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAoBA,eAAsB,UAAU,MAAY,QAAiB,SAAqC;CAChG,IAAI;EACF,MAAM,OAAO,MAAM,KAAK,SAAS,wBAAwB;EACzD,IAAI,QAAQ,KAAK,UAAU,GACzB,QAAQ,KACN;GAAE;GAAS,SAAS,KAAK;EAAQ,GACjC,0GACF;EACF,MAAM,OAAO,eAAe,MAAM,MAAM;EACxC,IAAI,KAAK,MAAM,OAAO,CAAC;EAEvB,MAAM,KAAK,SAAS,mBAAmB,MAAM,cAAc,CAAC,CAAC;EAC7D,OAAO,iBAAiB,MAAM,KAAK,SAAS,cAAc,IAAI,CAAC;CACjE,SAAS,OAAO;EACd,OAAO,CAAC,oBAAoB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAAG;CACtF;AACF"}

package/dist/availability.mjs

@@ -0,0 +1,30 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { existsSync } from "node:fs";
+// src/availability.ts
+/**
+* Each local target as a {@link RunnerTarget}. `puppeteer-core` ships no browser, so a target is
+* `ready` only when it has an executable that exists: its own, the runner's, or the one named by
+* `PUPPETEER_EXECUTABLE_PATH`, which `puppeteer-core` itself reads.
+*/
+function verifyLocalTargets(targets, env = process.env, exists = existsSync) {
+	return targets.map((entry) => ({
+		target: entry.target,
+		reach: "loopback",
+		status: statusOf(entry, env, exists)
+	}));
+}
+function statusOf(entry, env, exists) {
+	const path = entry.executablePath ?? envPath(entry, env);
+	if (path === void 0) return { unavailable: "no executablePath (puppeteer-core ships no browser): set `executablePath`" };
+	return exists(path) ? "ready" : { unavailable: `executable not found at ${path}` };
+}
+/** `PUPPETEER_EXECUTABLE_PATH` is for the bundled engine, never for `chrome`. */
+function envPath(entry, env) {
+	const path = env["PUPPETEER_EXECUTABLE_PATH"];
+	return entry.target === "chromium" && path ? path : void 0;
+}
+export { verifyLocalTargets };
+
+//# sourceMappingURL=availability.mjs.map

package/dist/availability.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"availability.mjs","names":[],"sources":["../src/availability.ts"],"sourcesContent":["/** Telling which declared local engines can launch, without launching anything (ADR 0007, decision 7). */\nimport type { RunnerTarget } from \"@storyshelf/core/adapter/capture-runner\";\nimport { existsSync } from \"node:fs\";\nimport type { LocalTarget } from \"./targets.ts\";\n\n/** Injectable file check, so tests need no browsers installed. */\ntype Exists = (path: string) => boolean;\n\n/**\n * Each local target as a {@link RunnerTarget}. `puppeteer-core` ships no browser, so a target is\n * `ready` only when it has an executable that exists: its own, the runner's, or the one named by\n * `PUPPETEER_EXECUTABLE_PATH`, which `puppeteer-core` itself reads.\n */\nexport function verifyLocalTargets(\n  targets: readonly LocalTarget[],\n  env: Readonly<Record<string, string | undefined>> = process.env,\n  exists: Exists = existsSync,\n): RunnerTarget[] {\n  return targets.map((entry) => ({\n    target: entry.target,\n    reach: \"loopback\",\n    status: statusOf(entry, env, exists),\n  }));\n}\n\nfunction statusOf(\n  entry: LocalTarget,\n  env: Readonly<Record<string, string | undefined>>,\n  exists: Exists,\n): RunnerTarget[\"status\"] {\n  const path = entry.executablePath ?? envPath(entry, env);\n  if (path === undefined) {\n    return {\n      unavailable: \"no executablePath (puppeteer-core ships no browser): set `executablePath`\",\n    };\n  }\n  return exists(path) ? \"ready\" : { unavailable: `executable not found at ${path}` };\n}\n\n/** `PUPPETEER_EXECUTABLE_PATH` is for the bundled engine, never for `chrome`. */\nfunction envPath(\n  entry: LocalTarget,\n  env: Readonly<Record<string, string | undefined>>,\n): string | undefined {\n  const path = env[\"PUPPETEER_EXECUTABLE_PATH\"];\n  return entry.target === \"chromium\" && path ? path : undefined;\n}\n"],"mappings":";;;;;;;;;;AAaA,SAAgB,mBACd,SACA,MAAoD,QAAQ,KAC5D,SAAiB,YACD;CAChB,OAAO,QAAQ,KAAK,WAAW;EAC7B,QAAQ,MAAM;EACd,OAAO;EACP,QAAQ,SAAS,OAAO,KAAK,MAAM;CACrC,EAAE;AACJ;AAEA,SAAS,SACP,OACA,KACA,QACwB;CACxB,MAAM,OAAO,MAAM,kBAAkB,QAAQ,OAAO,GAAG;CACvD,IAAI,SAAS,KAAA,GACX,OAAO,EACL,aAAa,4EACf;CAEF,OAAO,OAAO,IAAI,IAAI,UAAU,EAAE,aAAa,2BAA2B,OAAO;AACnF;;AAGA,SAAS,QACP,OACA,KACoB;CACpB,MAAM,OAAO,IAAI;CACjB,OAAO,MAAM,WAAW,cAAc,OAAO,OAAO,KAAA;AACtD"}

package/dist/browser.mjs

@@ -1,22 +1,27 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/browser.ts
-/** Tracks in-flight renders so `cancel` can abort them. */
-const activeRuns = /* @__PURE__ */ new Map();
-/** Close a browser if present; `cancel` must never throw. */
-async function closeBrowser(browser) {
-	if (!browser) return;
-	await tryCloseBrowser(browser);
+import { RenderRuns } from "@storyshelf/core/adapter/capture-runner";
+// src/browser.ts
+/** Active-run tracking and best-effort cleanup helpers for Puppeteer. */
+/** Tracks in-flight renders, each by its own handle, so `cancel` aborts exactly the runs it names. */
+const activeRuns = new RenderRuns();
+/** The outcome a render's `finally` reports: a cancel wins over a failure, a failure over a finish. */
+function outcomeOf(active, failed) {
+	if (active.cancelled) return "cancelled";
+	return failed ? "failed" : "finished";
 }
-async function tryCloseBrowser(browser) {
+/** Run `work`, then `finish` with whether it threw, so a browser is released with how its run went. */
+async function finishing(work, finish) {
+	let failure;
 	try {
-		await browser.close();
-	} catch {}
-}
-/** Best-effort close for the render's `finally` block. */
-async function safeCloseBrowser(browser) {
-	await tryCloseBrowser(browser);
+		return await work();
+	} catch (error) {
+		failure = { error };
+		throw error;
+	} finally {
+		await finish(failure !== void 0, failure?.error);
+	}
 }
 /** Best-effort close for the static server. */
 async function safeCloseServer(server) {
@@ -24,11 +29,17 @@ async function safeCloseServer(server) {
 		await server.close();
 	} catch {}
 }
+/** Release and throw when the run was cancelled while acquiring the browser. */
+async function abortIfCancelled(active, session) {
+	if (!active.cancelled) return;
+	await session.release("cancelled");
+	if (active.session === session) active.session = null;
+	throw new Error("Capture cancelled");
+}
 /** Normalize any thrown value to a string. */
 function messageOf(error) {
 	return error instanceof Error ? error.message : String(error);
 }
-//#endregion
-export { activeRuns, closeBrowser, messageOf, safeCloseBrowser, safeCloseServer };
+export { abortIfCancelled, activeRuns, finishing, messageOf, outcomeOf, safeCloseServer };
 
 //# sourceMappingURL=browser.mjs.map

package/dist/browser.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"browser.mjs","names":[],"sources":["../src/browser.ts"],"sourcesContent":["/** Browser lifecycle and active-run tracking for Puppeteer. */\n\nimport type { Browser } from \"puppeteer-core\";\nimport type { ActiveRun } from \"./types.ts\";\n\n/** Tracks in-flight renders so `cancel` can abort them. */\nexport const activeRuns = new Map<string, ActiveRun>();\n\n/** Close a browser if present; `cancel` must never throw. */\nexport async function closeBrowser(browser: Browser | null): Promise<void> {\n  if (!browser) return;\n  await tryCloseBrowser(browser);\n}\n\nasync function tryCloseBrowser(browser: Browser): Promise<void> {\n  try {\n    await browser.close();\n  } catch {\n    // The run's own `finally` performs final cleanup; cancel must never throw.\n  }\n}\n\n/** Best-effort close for the render's `finally` block. */\nexport async function safeCloseBrowser(browser: Browser): Promise<void> {\n  await tryCloseBrowser(browser);\n}\n\n/** Best-effort close for the static server. */\nexport async function safeCloseServer(server: { close(): Promise<void> }): Promise<void> {\n  try {\n    await server.close();\n  } catch {\n    // Best-effort; teardown must never mask a render result.\n  }\n}\n\n/** Normalize any thrown value to a string. */\nexport function messageOf(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n"],"mappings":";;;;;AAMA,MAAa,6BAAa,IAAI,IAAuB;;AAGrD,eAAsB,aAAa,SAAwC;CACzE,IAAI,CAAC,SAAS;CACd,MAAM,gBAAgB,OAAO;AAC/B;AAEA,eAAe,gBAAgB,SAAiC;CAC9D,IAAI;EACF,MAAM,QAAQ,MAAM;CACtB,QAAQ,CAER;AACF;;AAGA,eAAsB,iBAAiB,SAAiC;CACtE,MAAM,gBAAgB,OAAO;AAC/B;;AAGA,eAAsB,gBAAgB,QAAmD;CACvF,IAAI;EACF,MAAM,OAAO,MAAM;CACrB,QAAQ,CAER;AACF;;AAGA,SAAgB,UAAU,OAAwB;CAChD,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAC9D"}
+{"version":3,"file":"browser.mjs","names":[],"sources":["../src/browser.ts"],"sourcesContent":["/** Active-run tracking and best-effort cleanup helpers for Puppeteer. */\n\nimport { RenderRuns, type RemoteLeaseOutcome } from \"@storyshelf/core/adapter/capture-runner\";\nimport type { ActiveRun } from \"./types.ts\";\nimport type { BrowserSession } from \"./session.ts\";\n\n/** Tracks in-flight renders, each by its own handle, so `cancel` aborts exactly the runs it names. */\nexport const activeRuns = new RenderRuns<ActiveRun>();\n\n/** The outcome a render's `finally` reports: a cancel wins over a failure, a failure over a finish. */\nexport function outcomeOf(active: { cancelled: boolean }, failed: boolean): RemoteLeaseOutcome {\n  if (active.cancelled) return \"cancelled\";\n  return failed ? \"failed\" : \"finished\";\n}\n\n/** Run `work`, then `finish` with whether it threw, so a browser is released with how its run went. */\nexport async function finishing<T>(\n  work: () => Promise<T>,\n  finish: (failed: boolean, error?: unknown) => Promise<void>,\n): Promise<T> {\n  let failure: { error: unknown } | undefined;\n  try {\n    return await work();\n  } catch (error) {\n    failure = { error };\n    throw error;\n  } finally {\n    await finish(failure !== undefined, failure?.error);\n  }\n}\n\n/** Best-effort close for the static server. */\nexport async function safeCloseServer(server: { close(): Promise<void> }): Promise<void> {\n  try {\n    await server.close();\n  } catch {\n    // Best-effort; teardown must never mask a render result.\n  }\n}\n\n/** Release and throw when the run was cancelled while acquiring the browser. */\nexport async function abortIfCancelled(\n  active: { cancelled: boolean; session: BrowserSession | null },\n  session: BrowserSession,\n): Promise<void> {\n  if (!active.cancelled) return;\n  await session.release(\"cancelled\");\n  if (active.session === session) active.session = null;\n  throw new Error(\"Capture cancelled\");\n}\n\n/** Normalize any thrown value to a string. */\nexport function messageOf(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n"],"mappings":";;;;;;;AAOA,MAAa,aAAa,IAAI,WAAsB;;AAGpD,SAAgB,UAAU,QAAgC,QAAqC;CAC7F,IAAI,OAAO,WAAW,OAAO;CAC7B,OAAO,SAAS,WAAW;AAC7B;;AAGA,eAAsB,UACpB,MACA,QACY;CACZ,IAAI;CACJ,IAAI;EACF,OAAO,MAAM,KAAK;CACpB,SAAS,OAAO;EACd,UAAU,EAAE,MAAM;EAClB,MAAM;CACR,UAAU;EACR,MAAM,OAAO,YAAY,KAAA,GAAW,SAAS,KAAK;CACpD;AACF;;AAGA,eAAsB,gBAAgB,QAAmD;CACvF,IAAI;EACF,MAAM,OAAO,MAAM;CACrB,QAAQ,CAER;AACF;;AAGA,eAAsB,iBACpB,QACA,SACe;CACf,IAAI,CAAC,OAAO,WAAW;CACvB,MAAM,QAAQ,QAAQ,WAAW;CACjC,IAAI,OAAO,YAAY,SAAS,OAAO,UAAU;CACjD,MAAM,IAAI,MAAM,mBAAmB;AACrC;;AAGA,SAAgB,UAAU,OAAwB;CAChD,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAC9D"}

package/dist/capture-runner.d.mts

@@ -1,16 +1,31 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
+import { BrowserEntry } from "./targets.mjs";
 import "./types.mjs";
 import "./runtime-params.mjs";
-import { BrowserName, CaptureRunner } from "@storyshelf/core/adapter/capture-runner";
-//#region src/capture-runner.d.ts
+import { CaptureRunner } from "@storyshelf/core/adapter/capture-runner";
 /** Create a CaptureRunner that renders Storybook stories with Puppeteer (Chromium via chrome-headless-shell). */
 declare function createPuppeteerCaptureRunner(options?: {
-  browser?: BrowserName;
-  supportedBrowsers?: readonly BrowserName[];
+  /**
+   * Every target the runner offers, default first (ADR 0007, decision 1): `"chromium"`,
+   * `local(engine, { executablePath })`, or remote CDP services from
+   * `@storyshelf/runner-puppeteer/remote` (`cdp(...)`: `<engine>@<name>` targets that need a
+   * Storybook URL they can reach). Default `["chromium"]`. Chromium-family engines only; bare
+   * `"chrome"` needs `local("chrome", { executablePath })`.
+   */
+  browsers?: readonly BrowserEntry[];
+  /** The executable bare entries launch (`puppeteer-core` ships no browser). */
   executablePath?: string;
+  /** Launch flags for local engines; replaces the default sandbox and low-memory flags. */
   args?: string[];
+  /** Pages rendered at once; falls back to `STORYSHELF_CAPTURE_CONCURRENCY`, then CPU/memory detection. */
+  concurrency?: number;
+  /** Per-page timeout in ms; falls back to `STORYSHELF_NAVIGATION_TIMEOUT_MS`, then CPU detection. */
+  navigationTimeoutMs?: number;
+  /** Captures between browser restarts (0 disables); falls back to `STORYSHELF_BROWSER_RECYCLE_EVERY`, then 150. */
+  recycleBrowserEvery?: number;
+  /** Reuse pages between captures (opt-in); falls back to `STORYSHELF_REUSE_PAGES=1`. */
+  reusePages?: boolean;
 }): CaptureRunner;
-//#endregion
 export { createPuppeteerCaptureRunner };
 //# sourceMappingURL=capture-runner.d.mts.map

package/dist/capture-runner.mjs

@@ -1,42 +1,115 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { activeRuns, closeBrowser } from "./browser.mjs";
+import { verifyLocalTargets } from "./availability.mjs";
+import { activeRuns } from "./browser.mjs";
+import { connectRemote } from "./connect.mjs";
+import { launchLocal } from "./launch.mjs";
 import "./runtime-params.mjs";
 import { renderAll } from "./pipeline.mjs";
-//#region src/capture-runner.ts
+import { flattenBrowsers } from "./targets.mjs";
+import { runTestEntries } from "./tests.mjs";
+import { createTargetOffers, shutdownRemote } from "@storyshelf/core/adapter/capture-runner";
+import { recommendedNavigationTimeoutMs } from "@storyshelf/core/utils";
+// src/capture-runner.ts
+/** Puppeteer capture runner — composition root (factory wiring). */
 /** Create a CaptureRunner that renders Storybook stories with Puppeteer (Chromium via chrome-headless-shell). */
 function createPuppeteerCaptureRunner(options = {}) {
+	const { declared, locals, remotes } = flattenBrowsers(options.browsers ?? ["chromium"], options.executablePath);
+	const offers = createTargetOffers(declared);
+	const driver = {
+		launch: offers.guard(async (target, logger, context) => {
+			const remote = remotes.find((entry) => entry.target === target);
+			return remote ? await connectRemote(remote, context, logger) : {
+				browser: await launchLocal(locals.find((entry) => entry.target === target), options.args),
+				ownership: "launched"
+			};
+		}),
+		remote: (target) => remotes.find((entry) => entry.target === target)
+	};
+	const concurrency = options.concurrency ?? envPositiveInt("STORYSHELF_CAPTURE_CONCURRENCY");
+	const navigationTimeoutMs = options.navigationTimeoutMs ?? envPositiveInt("STORYSHELF_NAVIGATION_TIMEOUT_MS") ?? recommendedNavigationTimeoutMs();
+	const recycleBrowserEvery = options.recycleBrowserEvery ?? envInt("STORYSHELF_BROWSER_RECYCLE_EVERY", 0);
+	const reusePages = options.reusePages ?? ["1", "true"].includes(process.env["STORYSHELF_REUSE_PAGES"] ?? "");
 	return {
 		metadata: {
 			name: "Puppeteer",
-			version: globalThis.__PKG_VERSION__ ?? "0.0.0",
+			version: "0.8.0",
 			description: "Puppeteer capture runner (chrome-headless-shell)",
 			kind: "puppeteer",
 			category: "capture-runner",
-			supportedBrowsers: options.supportedBrowsers ?? ["chromium", "chrome"]
+			get targets() {
+				return offers.current();
+			}
 		},
+		lifecycle: withShutdown(offers.lifecycle(async () => await Promise.resolve(verifyTargets(declared, locals)))),
 		async render(input) {
 			const active = {
 				cancelled: false,
-				browser: null
+				session: null,
+				abort: new AbortController()
 			};
-			activeRuns.set(input.buildId, active);
+			const remove = activeRuns.add(input.buildId, input.runId, active);
 			try {
-				return await renderAll(input, active, options);
+				return await renderAll({
+					concurrency,
+					navigationTimeoutMs,
+					recycleBrowserEvery,
+					reusePages,
+					...input
+				}, active, driver, offers.defaultTarget);
 			} finally {
-				activeRuns.delete(input.buildId);
+				remove();
 			}
 		},
-		async cancel(buildId) {
-			const active = activeRuns.get(buildId);
-			if (!active) return;
-			active.cancelled = true;
-			await closeBrowser(active.browser);
+		async runTests(input) {
+			const active = {
+				cancelled: false,
+				session: null,
+				abort: new AbortController()
+			};
+			const remove = activeRuns.add(input.buildId, input.runId, active);
+			try {
+				return await runTestEntries({
+					concurrency,
+					navigationTimeoutMs,
+					...input
+				}, active, driver, offers.defaultTarget);
+			} finally {
+				remove();
+			}
+		},
+		async cancel(buildId, runId) {
+			await Promise.all(activeRuns.matching(buildId, runId).map(async (active) => {
+				active.cancelled = true;
+				active.abort?.abort();
+				await active.session?.release("cancelled");
+			}));
+		}
+	};
+}
+/** Local targets are checked for an executable; a remote one is not probed (that would open a session). */
+function verifyTargets(declared, locals) {
+	const checked = new Map(verifyLocalTargets(locals).map((entry) => [entry.target, entry]));
+	return declared.map((entry) => checked.get(entry.target) ?? entry);
+}
+/** Teardown also releases every lease still held and closes every pool, so a stopped process leaves no server running. */
+function withShutdown(lifecycle) {
+	return {
+		...lifecycle,
+		teardown: async () => {
+			await shutdownRemote();
+			await lifecycle.teardown();
 		}
 	};
 }
-//#endregion
+function envPositiveInt(name) {
+	return envInt(name, 1);
+}
+function envInt(name, min) {
+	const parsed = Number.parseInt(process.env[name] ?? "", 10);
+	return parsed >= min ? parsed : void 0;
+}
 export { createPuppeteerCaptureRunner };
 
 //# sourceMappingURL=capture-runner.mjs.map

package/dist/capture-runner.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"capture-runner.mjs","names":[],"sources":["../src/capture-runner.ts"],"sourcesContent":["/** Puppeteer capture runner — composition root (factory wiring). */\n\nimport type { BrowserName, CaptureRunner } from \"@storyshelf/core/adapter/capture-runner\";\nimport { activeRuns, closeBrowser } from \"./browser.ts\";\nimport { renderAll } from \"./pipeline.ts\";\nimport type { ActiveRun, PuppeteerRenderInput } from \"./types.ts\";\n\ndeclare const __PKG_VERSION__: string | undefined;\n\n/** Create a CaptureRunner that renders Storybook stories with Puppeteer (Chromium via chrome-headless-shell). */\nexport function createPuppeteerCaptureRunner(\n  options: {\n    browser?: BrowserName;\n    supportedBrowsers?: readonly BrowserName[];\n    executablePath?: string;\n    args?: string[];\n  } = {},\n): CaptureRunner {\n  return {\n    metadata: {\n      name: \"Puppeteer\",\n      version: (globalThis as unknown as { __PKG_VERSION__?: string }).__PKG_VERSION__ ?? \"0.0.0\",\n      description: \"Puppeteer capture runner (chrome-headless-shell)\",\n      kind: \"puppeteer\",\n      category: \"capture-runner\",\n      supportedBrowsers: options.supportedBrowsers ?? [\"chromium\", \"chrome\"],\n    },\n    async render(input: PuppeteerRenderInput) {\n      const active: ActiveRun = { cancelled: false, browser: null };\n      activeRuns.set(input.buildId, active);\n      try {\n        return await renderAll(input, active, options);\n      } finally {\n        activeRuns.delete(input.buildId);\n      }\n    },\n    async cancel(buildId) {\n      const active = activeRuns.get(buildId);\n      if (!active) return;\n      active.cancelled = true;\n      await closeBrowser(active.browser);\n    },\n  };\n}\n\n// Re-exports for backward compatibility (tests import these from capture-runner).\nexport type { PuppeteerRenderInput, RuntimeParamsState } from \"./types.ts\";\nexport { createRuntimeParamsState, runtimeParametersForStory } from \"./runtime-params.ts\";\n"],"mappings":";;;;;;;;AAUA,SAAgB,6BACd,UAKI,CAAC,GACU;CACf,OAAO;EACL,UAAU;GACR,MAAM;GACN,SAAU,WAAuD,mBAAmB;GACpF,aAAa;GACb,MAAM;GACN,UAAU;GACV,mBAAmB,QAAQ,qBAAqB,CAAC,YAAY,QAAQ;EACvE;EACA,MAAM,OAAO,OAA6B;GACxC,MAAM,SAAoB;IAAE,WAAW;IAAO,SAAS;GAAK;GAC5D,WAAW,IAAI,MAAM,SAAS,MAAM;GACpC,IAAI;IACF,OAAO,MAAM,UAAU,OAAO,QAAQ,OAAO;GAC/C,UAAU;IACR,WAAW,OAAO,MAAM,OAAO;GACjC;EACF;EACA,MAAM,OAAO,SAAS;GACpB,MAAM,SAAS,WAAW,IAAI,OAAO;GACrC,IAAI,CAAC,QAAQ;GACb,OAAO,YAAY;GACnB,MAAM,aAAa,OAAO,OAAO;EACnC;CACF;AACF"}
+{"version":3,"file":"capture-runner.mjs","names":[],"sources":["../src/capture-runner.ts"],"sourcesContent":["/** Puppeteer capture runner — composition root (factory wiring). */\n\nimport {\n  createTargetOffers,\n  shutdownRemote,\n  type CaptureRunner,\n  type RunnerTarget,\n} from \"@storyshelf/core/adapter/capture-runner\";\nimport type { AdapterLifecycle } from \"@storyshelf/core/adapter/metadata\";\nimport { recommendedNavigationTimeoutMs } from \"@storyshelf/core/utils\";\nimport { verifyLocalTargets } from \"./availability.ts\";\nimport { activeRuns } from \"./browser.ts\";\nimport { connectRemote } from \"./connect.ts\";\nimport { launchLocal } from \"./launch.ts\";\nimport { renderAll } from \"./pipeline.ts\";\nimport { flattenBrowsers, type BrowserEntry, type LocalTarget } from \"./targets.ts\";\nimport { runTestEntries } from \"./tests.ts\";\nimport type {\n  ActiveRun,\n  PuppeteerRenderInput,\n  PuppeteerTestsInput,\n  TargetDriver,\n} from \"./types.ts\";\n\ndeclare const __PKG_VERSION__: string | undefined;\n\n/** Create a CaptureRunner that renders Storybook stories with Puppeteer (Chromium via chrome-headless-shell). */\nexport function createPuppeteerCaptureRunner(\n  options: {\n    /**\n     * Every target the runner offers, default first (ADR 0007, decision 1): `\"chromium\"`,\n     * `local(engine, { executablePath })`, or remote CDP services from\n     * `@storyshelf/runner-puppeteer/remote` (`cdp(...)`: `<engine>@<name>` targets that need a\n     * Storybook URL they can reach). Default `[\"chromium\"]`. Chromium-family engines only; bare\n     * `\"chrome\"` needs `local(\"chrome\", { executablePath })`.\n     */\n    browsers?: readonly BrowserEntry[];\n    /** The executable bare entries launch (`puppeteer-core` ships no browser). */\n    executablePath?: string;\n    /** Launch flags for local engines; replaces the default sandbox and low-memory flags. */\n    args?: string[];\n    /** Pages rendered at once; falls back to `STORYSHELF_CAPTURE_CONCURRENCY`, then CPU/memory detection. */\n    concurrency?: number;\n    /** Per-page timeout in ms; falls back to `STORYSHELF_NAVIGATION_TIMEOUT_MS`, then CPU detection. */\n    navigationTimeoutMs?: number;\n    /** Captures between browser restarts (0 disables); falls back to `STORYSHELF_BROWSER_RECYCLE_EVERY`, then 150. */\n    recycleBrowserEvery?: number;\n    /** Reuse pages between captures (opt-in); falls back to `STORYSHELF_REUSE_PAGES=1`. */\n    reusePages?: boolean;\n  } = {},\n): CaptureRunner {\n  const { declared, locals, remotes } = flattenBrowsers(\n    options.browsers ?? [\"chromium\"],\n    options.executablePath,\n  );\n  // Until `lifecycle.setup` verifies them, every declared target reads as ready.\n  const offers = createTargetOffers(declared);\n  const driver: TargetDriver = {\n    launch: offers.guard(async (target, logger, context) => {\n      const remote = remotes.find((entry) => entry.target === target);\n      return remote\n        ? await connectRemote(remote, context, logger)\n        : {\n            browser: await launchLocal(\n              locals.find((entry) => entry.target === target) as LocalTarget,\n              options.args,\n            ),\n            ownership: \"launched\",\n          };\n    }),\n    remote: (target) => remotes.find((entry) => entry.target === target),\n  };\n  const concurrency = options.concurrency ?? envPositiveInt(\"STORYSHELF_CAPTURE_CONCURRENCY\");\n  const navigationTimeoutMs =\n    options.navigationTimeoutMs ??\n    envPositiveInt(\"STORYSHELF_NAVIGATION_TIMEOUT_MS\") ??\n    recommendedNavigationTimeoutMs();\n  const recycleBrowserEvery =\n    options.recycleBrowserEvery ?? envInt(\"STORYSHELF_BROWSER_RECYCLE_EVERY\", 0);\n  const reusePages =\n    options.reusePages ?? [\"1\", \"true\"].includes(process.env[\"STORYSHELF_REUSE_PAGES\"] ?? \"\");\n  return {\n    metadata: {\n      name: \"Puppeteer\",\n      version: typeof __PKG_VERSION__ === \"string\" ? __PKG_VERSION__ : \"0.0.0\",\n      description: \"Puppeteer capture runner (chrome-headless-shell)\",\n      kind: \"puppeteer\",\n      category: \"capture-runner\",\n      get targets() {\n        return offers.current();\n      },\n    },\n    lifecycle: withShutdown(\n      offers.lifecycle(async () => await Promise.resolve(verifyTargets(declared, locals))),\n    ),\n    async render(input: PuppeteerRenderInput) {\n      const active: ActiveRun = { cancelled: false, session: null, abort: new AbortController() };\n      const remove = activeRuns.add(input.buildId, input.runId, active);\n      try {\n        return await renderAll(\n          { concurrency, navigationTimeoutMs, recycleBrowserEvery, reusePages, ...input },\n          active,\n          driver,\n          offers.defaultTarget,\n        );\n      } finally {\n        remove();\n      }\n    },\n    async runTests(input: PuppeteerTestsInput) {\n      const active: ActiveRun = { cancelled: false, session: null, abort: new AbortController() };\n      const remove = activeRuns.add(input.buildId, input.runId, active);\n      try {\n        return await runTestEntries(\n          { concurrency, navigationTimeoutMs, ...input },\n          active,\n          driver,\n          offers.defaultTarget,\n        );\n      } finally {\n        remove();\n      }\n    },\n    async cancel(buildId, runId) {\n      await Promise.all(\n        activeRuns.matching(buildId, runId).map(async (active) => {\n          active.cancelled = true;\n          active.abort?.abort();\n          await active.session?.release(\"cancelled\");\n        }),\n      );\n    },\n  };\n}\n\n/** Local targets are checked for an executable; a remote one is not probed (that would open a session). */\nfunction verifyTargets(\n  declared: readonly RunnerTarget[],\n  locals: readonly LocalTarget[],\n): RunnerTarget[] {\n  const checked = new Map(verifyLocalTargets(locals).map((entry) => [entry.target, entry]));\n  return declared.map((entry) => checked.get(entry.target) ?? entry);\n}\n\n/** Teardown also releases every lease still held and closes every pool, so a stopped process leaves no server running. */\nfunction withShutdown(lifecycle: AdapterLifecycle): AdapterLifecycle {\n  return {\n    ...lifecycle,\n    teardown: async () => {\n      await shutdownRemote();\n      await lifecycle.teardown();\n    },\n  };\n}\n\nfunction envPositiveInt(name: string): number | undefined {\n  return envInt(name, 1);\n}\n\nfunction envInt(name: string, min: number): number | undefined {\n  const parsed = Number.parseInt(process.env[name] ?? \"\", 10);\n  return parsed >= min ? parsed : undefined;\n}\n\n// Re-exports for backward compatibility (tests import these from capture-runner).\nexport type { PuppeteerRenderInput, RuntimeParamsState } from \"./types.ts\";\nexport { createRuntimeParamsState, runtimeParametersForStory } from \"./runtime-params.ts\";\n"],"mappings":";;;;;;;;;;;;;;;;AA2BA,SAAgB,6BACd,UAqBI,CAAC,GACU;CACf,MAAM,EAAE,UAAU,QAAQ,YAAY,gBACpC,QAAQ,YAAY,CAAC,UAAU,GAC/B,QAAQ,cACV;CAEA,MAAM,SAAS,mBAAmB,QAAQ;CAC1C,MAAM,SAAuB;EAC3B,QAAQ,OAAO,MAAM,OAAO,QAAQ,QAAQ,YAAY;GACtD,MAAM,SAAS,QAAQ,MAAM,UAAU,MAAM,WAAW,MAAM;GAC9D,OAAO,SACH,MAAM,cAAc,QAAQ,SAAS,MAAM,IAC3C;IACE,SAAS,MAAM,YACb,OAAO,MAAM,UAAU,MAAM,WAAW,MAAM,GAC9C,QAAQ,IACV;IACA,WAAW;GACb;EACN,CAAC;EACD,SAAS,WAAW,QAAQ,MAAM,UAAU,MAAM,WAAW,MAAM;CACrE;CACA,MAAM,cAAc,QAAQ,eAAe,eAAe,gCAAgC;CAC1F,MAAM,sBACJ,QAAQ,uBACR,eAAe,kCAAkC,KACjD,+BAA+B;CACjC,MAAM,sBACJ,QAAQ,uBAAuB,OAAO,oCAAoC,CAAC;CAC7E,MAAM,aACJ,QAAQ,cAAc,CAAC,KAAK,MAAM,CAAC,CAAC,SAAS,QAAQ,IAAI,6BAA6B,EAAE;CAC1F,OAAO;EACL,UAAU;GACR,MAAM;GACN,SAAA;GACA,aAAa;GACb,MAAM;GACN,UAAU;GACV,IAAI,UAAU;IACZ,OAAO,OAAO,QAAQ;GACxB;EACF;EACA,WAAW,aACT,OAAO,UAAU,YAAY,MAAM,QAAQ,QAAQ,cAAc,UAAU,MAAM,CAAC,CAAC,CACrF;EACA,MAAM,OAAO,OAA6B;GACxC,MAAM,SAAoB;IAAE,WAAW;IAAO,SAAS;IAAM,OAAO,IAAI,gBAAgB;GAAE;GAC1F,MAAM,SAAS,WAAW,IAAI,MAAM,SAAS,MAAM,OAAO,MAAM;GAChE,IAAI;IACF,OAAO,MAAM,UACX;KAAE;KAAa;KAAqB;KAAqB;KAAY,GAAG;IAAM,GAC9E,QACA,QACA,OAAO,aACT;GACF,UAAU;IACR,OAAO;GACT;EACF;EACA,MAAM,SAAS,OAA4B;GACzC,MAAM,SAAoB;IAAE,WAAW;IAAO,SAAS;IAAM,OAAO,IAAI,gBAAgB;GAAE;GAC1F,MAAM,SAAS,WAAW,IAAI,MAAM,SAAS,MAAM,OAAO,MAAM;GAChE,IAAI;IACF,OAAO,MAAM,eACX;KAAE;KAAa;KAAqB,GAAG;IAAM,GAC7C,QACA,QACA,OAAO,aACT;GACF,UAAU;IACR,OAAO;GACT;EACF;EACA,MAAM,OAAO,SAAS,OAAO;GAC3B,MAAM,QAAQ,IACZ,WAAW,SAAS,SAAS,KAAK,CAAC,CAAC,IAAI,OAAO,WAAW;IACxD,OAAO,YAAY;IACnB,OAAO,OAAO,MAAM;IACpB,MAAM,OAAO,SAAS,QAAQ,WAAW;GAC3C,CAAC,CACH;EACF;CACF;AACF;;AAGA,SAAS,cACP,UACA,QACgB;CAChB,MAAM,UAAU,IAAI,IAAI,mBAAmB,MAAM,CAAC,CAAC,KAAK,UAAU,CAAC,MAAM,QAAQ,KAAK,CAAC,CAAC;CACxF,OAAO,SAAS,KAAK,UAAU,QAAQ,IAAI,MAAM,MAAM,KAAK,KAAK;AACnE;;AAGA,SAAS,aAAa,WAA+C;CACnE,OAAO;EACL,GAAG;EACH,UAAU,YAAY;GACpB,MAAM,eAAe;GACrB,MAAM,UAAU,SAAS;EAC3B;CACF;AACF;AAEA,SAAS,eAAe,MAAkC;CACxD,OAAO,OAAO,MAAM,CAAC;AACvB;AAEA,SAAS,OAAO,MAAc,KAAiC;CAC7D,MAAM,SAAS,OAAO,SAAS,QAAQ,IAAI,SAAS,IAAI,EAAE;CAC1D,OAAO,UAAU,MAAM,SAAS,KAAA;AAClC"}

package/dist/connect.mjs

@@ -0,0 +1,45 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { connectLeased, scrubConnection } from "@storyshelf/core/adapter/capture-runner";
+import puppeteer from "puppeteer-core";
+// src/connect.ts
+/** Connecting to a remote browser: retried when the service is unreachable or full, a clear error when it is not. */
+/**
+* Connect to `entry`'s service and return the browser with its ownership: the run must disconnect
+* it, never close it, and releases the service's lease (a function `connect`'s `lease`) exactly
+* once when the session ends. Connection-level failures are retried with backoff, so a provider
+* outage or a full plan costs time and not a story crash; what is left is a `TargetLaunchError`,
+* which fails the job at once (a refused credential also marks the target unavailable, a service
+* that is merely down does not). No message carries the endpoint, its credentials or the lease.
+*/
+async function connectRemote(entry, context, logger) {
+	const { value, lease } = await connectLeased(entry, context, {
+		logger,
+		open: async (connection) => await connectOnce(connection, entry.remote.timeouts.connectMs),
+		reasonOf
+	});
+	return {
+		browser: value,
+		ownership: "connected",
+		releaseLease: async (outcome, error) => {
+			await lease.end(outcome, error);
+		}
+	};
+}
+async function connectOnce(connection, timeoutMs) {
+	const isHttp = connection.endpoint.startsWith("http");
+	return await puppeteer.connect({
+		...isHttp ? { browserURL: connection.endpoint } : { browserWSEndpoint: connection.endpoint },
+		protocolTimeout: timeoutMs,
+		...connection.headers === void 0 ? {} : { headers: connection.headers }
+	});
+}
+/** What failed, in one line, with the endpoint and credentials removed. */
+function reasonOf(error, connection) {
+	const line = (error instanceof Error ? error.message : String(error)).split("\n").find((candidate) => candidate.trim() !== "")?.trim() ?? "the connection failed";
+	return scrubConnection(line, connection);
+}
+export { connectRemote };
+
+//# sourceMappingURL=connect.mjs.map

package/dist/connect.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.mjs","names":[],"sources":["../src/connect.ts"],"sourcesContent":["/** Connecting to a remote browser: retried when the service is unreachable or full, a clear error when it is not. */\nimport {\n  connectLeased,\n  scrubConnection,\n  type ConnectLeasedContext,\n  type RemoteConnection,\n  type RemoteTarget,\n} from \"@storyshelf/core/adapter/capture-runner\";\nimport type { Logger } from \"@storyshelf/core/logger\";\nimport type { Browser } from \"puppeteer-core\";\nimport puppeteer from \"puppeteer-core\";\nimport type { BrowserAcquisition } from \"./session.ts\";\n\n/**\n * Connect to `entry`'s service and return the browser with its ownership: the run must disconnect\n * it, never close it, and releases the service's lease (a function `connect`'s `lease`) exactly\n * once when the session ends. Connection-level failures are retried with backoff, so a provider\n * outage or a full plan costs time and not a story crash; what is left is a `TargetLaunchError`,\n * which fails the job at once (a refused credential also marks the target unavailable, a service\n * that is merely down does not). No message carries the endpoint, its credentials or the lease.\n */\nexport async function connectRemote(\n  entry: RemoteTarget,\n  context: ConnectLeasedContext,\n  logger?: Logger,\n): Promise<BrowserAcquisition> {\n  const { value, lease } = await connectLeased(entry, context, {\n    logger,\n    open: async (connection) => await connectOnce(connection, entry.remote.timeouts.connectMs),\n    reasonOf,\n  });\n  return {\n    browser: value,\n    ownership: \"connected\",\n    releaseLease: async (outcome, error) => {\n      await lease.end(outcome, error);\n    },\n  };\n}\n\nasync function connectOnce(connection: RemoteConnection, timeoutMs: number): Promise<Browser> {\n  const isHttp = connection.endpoint.startsWith(\"http\");\n  return await puppeteer.connect({\n    ...(isHttp ? { browserURL: connection.endpoint } : { browserWSEndpoint: connection.endpoint }),\n    protocolTimeout: timeoutMs,\n    ...(connection.headers === undefined ? {} : { headers: connection.headers }),\n  });\n}\n\n/** What failed, in one line, with the endpoint and credentials removed. */\nfunction reasonOf(error: unknown, connection: RemoteConnection & { lease?: unknown }): string {\n  const text = error instanceof Error ? error.message : String(error);\n  const line =\n    text\n      .split(\"\\n\")\n      .find((candidate) => candidate.trim() !== \"\")\n      ?.trim() ?? \"the connection failed\";\n  return scrubConnection(line, connection);\n}\n"],"mappings":";;;;;;;;;;;;;;;AAqBA,eAAsB,cACpB,OACA,SACA,QAC6B;CAC7B,MAAM,EAAE,OAAO,UAAU,MAAM,cAAc,OAAO,SAAS;EAC3D;EACA,MAAM,OAAO,eAAe,MAAM,YAAY,YAAY,MAAM,OAAO,SAAS,SAAS;EACzF;CACF,CAAC;CACD,OAAO;EACL,SAAS;EACT,WAAW;EACX,cAAc,OAAO,SAAS,UAAU;GACtC,MAAM,MAAM,IAAI,SAAS,KAAK;EAChC;CACF;AACF;AAEA,eAAe,YAAY,YAA8B,WAAqC;CAC5F,MAAM,SAAS,WAAW,SAAS,WAAW,MAAM;CACpD,OAAO,MAAM,UAAU,QAAQ;EAC7B,GAAI,SAAS,EAAE,YAAY,WAAW,SAAS,IAAI,EAAE,mBAAmB,WAAW,SAAS;EAC5F,iBAAiB;EACjB,GAAI,WAAW,YAAY,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS,WAAW,QAAQ;CAC5E,CAAC;AACH;;AAGA,SAAS,SAAS,OAAgB,YAA4D;CAE5F,MAAM,QADO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAAA,CAG7D,MAAM,IAAI,CAAC,CACX,MAAM,cAAc,UAAU,KAAK,MAAM,EAAE,CAAC,EAC3C,KAAK,KAAK;CAChB,OAAO,gBAAgB,MAAM,UAAU;AACzC"}

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
+import { BrowserEntry, LocalBrowser, LocalOptions, local } from "./targets.mjs";
 import { createPuppeteerCaptureRunner } from "./capture-runner.mjs";
-export { createPuppeteerCaptureRunner };
+export { type BrowserEntry, type LocalBrowser, type LocalOptions, createPuppeteerCaptureRunner, local };

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import "node:path";
 import "node:url";
 import.meta.url;
+import { local } from "./targets.mjs";
 import { createPuppeteerCaptureRunner } from "./capture-runner.mjs";
-export { createPuppeteerCaptureRunner };
+export { createPuppeteerCaptureRunner, local };

package/dist/launch.mjs

@@ -0,0 +1,52 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { TargetLaunchError } from "@storyshelf/core/adapter/capture-runner";
+import puppeteer from "puppeteer-core";
+// src/launch.ts
+/** Starting a local browser, and telling one that would not start from one that crashed. */
+/**
+* Sandbox flags for containers plus low-memory flags. Rendering-affecting flags
+* (`--disable-gpu`, `--single-process`) are excluded: they can shift pixels.
+*/
+const DEFAULT_ARGS = [
+	"--no-sandbox",
+	"--disable-setuid-sandbox",
+	"--disable-dev-shm-usage",
+	"--disable-extensions",
+	"--disable-background-networking",
+	"--mute-audio"
+];
+/**
+* Puppeteer closes its browser on SIGINT/SIGTERM/SIGHUP by default, which fails a render that a
+* graceful drain is still finishing. The host owns shutdown: it drains, each render releases the
+* browser it launched (or disconnects the one it connected to), then `teardown` releases leases.
+*/
+const HOST_OWNS_SIGNALS = {
+	handleSIGINT: false,
+	handleSIGTERM: false,
+	handleSIGHUP: false
+};
+/**
+* Launch `entry`'s browser. A failure is a {@link TargetLaunchError}: the browser never started, so
+* no story is at fault and the job fails at once instead of going through crash isolation.
+*/
+async function launchLocal(entry, args) {
+	try {
+		return await puppeteer.launch({
+			...HOST_OWNS_SIGNALS,
+			headless: true,
+			executablePath: entry.executablePath,
+			args: args ?? DEFAULT_ARGS
+		});
+	} catch (error) {
+		throw new TargetLaunchError(entry.target, firstLine(error), { cause: error });
+	}
+}
+/** Launch errors carry a long log tail; the first line says what failed. */
+function firstLine(error) {
+	return (error instanceof Error ? error.message : String(error)).split("\n").find((line) => line.trim() !== "")?.trim() ?? "the browser did not start";
+}
+export { launchLocal };
+
+//# sourceMappingURL=launch.mjs.map

package/dist/launch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch.mjs","names":[],"sources":["../src/launch.ts"],"sourcesContent":["/** Starting a local browser, and telling one that would not start from one that crashed. */\nimport { TargetLaunchError } from \"@storyshelf/core/adapter/capture-runner\";\nimport type { Browser } from \"puppeteer-core\";\nimport puppeteer from \"puppeteer-core\";\nimport type { LocalTarget } from \"./targets.ts\";\n\n/**\n * Sandbox flags for containers plus low-memory flags. Rendering-affecting flags\n * (`--disable-gpu`, `--single-process`) are excluded: they can shift pixels.\n */\nconst DEFAULT_ARGS = [\n  \"--no-sandbox\",\n  \"--disable-setuid-sandbox\",\n  \"--disable-dev-shm-usage\",\n  \"--disable-extensions\",\n  \"--disable-background-networking\",\n  \"--mute-audio\",\n];\n\n/**\n * Puppeteer closes its browser on SIGINT/SIGTERM/SIGHUP by default, which fails a render that a\n * graceful drain is still finishing. The host owns shutdown: it drains, each render releases the\n * browser it launched (or disconnects the one it connected to), then `teardown` releases leases.\n */\nconst HOST_OWNS_SIGNALS = {\n  handleSIGINT: false,\n  handleSIGTERM: false,\n  handleSIGHUP: false,\n} as const;\n\n/**\n * Launch `entry`'s browser. A failure is a {@link TargetLaunchError}: the browser never started, so\n * no story is at fault and the job fails at once instead of going through crash isolation.\n */\nexport async function launchLocal(\n  entry: LocalTarget,\n  args: string[] | undefined,\n): Promise<Browser> {\n  try {\n    return await puppeteer.launch({\n      ...HOST_OWNS_SIGNALS,\n      headless: true,\n      executablePath: entry.executablePath,\n      args: args ?? DEFAULT_ARGS,\n    });\n  } catch (error) {\n    throw new TargetLaunchError(entry.target, firstLine(error), { cause: error });\n  }\n}\n\n/** Launch errors carry a long log tail; the first line says what failed. */\nfunction firstLine(error: unknown): string {\n  const text = error instanceof Error ? error.message : String(error);\n  return (\n    text\n      .split(\"\\n\")\n      .find((line) => line.trim() !== \"\")\n      ?.trim() ?? \"the browser did not start\"\n  );\n}\n"],"mappings":";;;;;;;;;;;AAUA,MAAM,eAAe;CACnB;CACA;CACA;CACA;CACA;CACA;AACF;;;;;;AAOA,MAAM,oBAAoB;CACxB,cAAc;CACd,eAAe;CACf,cAAc;AAChB;;;;;AAMA,eAAsB,YACpB,OACA,MACkB;CAClB,IAAI;EACF,OAAO,MAAM,UAAU,OAAO;GAC5B,GAAG;GACH,UAAU;GACV,gBAAgB,MAAM;GACtB,MAAM,QAAQ;EAChB,CAAC;CACH,SAAS,OAAO;EACd,MAAM,IAAI,kBAAkB,MAAM,QAAQ,UAAU,KAAK,GAAG,EAAE,OAAO,MAAM,CAAC;CAC9E;AACF;;AAGA,SAAS,UAAU,OAAwB;CAEzC,QADa,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAAA,CAG7D,MAAM,IAAI,CAAC,CACX,MAAM,SAAS,KAAK,KAAK,MAAM,EAAE,CAAC,EACjC,KAAK,KAAK;AAElB"}