@storyshelf/runner-puppeteer 0.7.0 → 0.8.0

package/README.md

@@ -75,11 +75,13 @@ createPuppeteerCaptureRunner({
 });
 ```
 
+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`. The browser is restarted every 150 captures to bound its slow memory growth (`recycleBrowserEvery`, or `STORYSHELF_BROWSER_RECYCLE_EVERY`; `0` disables), and 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.
+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.
 

package/dist/a11y.mjs

@@ -2,19 +2,22 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { axeInjectionScript, inPageReadA11yParameters, inPageRunAxe, loadAxeSource, mapAxeViolations, resolveA11yRun } from "@storyshelf/core/capture";
-//#region src/a11y.ts
+// src/a11y.ts
 /** axe-core accessibility checks for captured pages (ADR 0004 §6). */
 /**
 * 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 debug line). Results are annotations: nothing
+* 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.
 */
-async function checkA11y(page, logger) {
+async function checkA11y(page, logger, storyId) {
 	try {
 		const read = await page.evaluate(inPageReadA11yParameters);
-		if (read && read.dropped > 0) logger?.debug({ dropped: read.dropped }, "parameters.a11y: function values left out");
+		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()));
@@ -23,7 +26,6 @@ async function checkA11y(page, logger) {
 		return [`axe unavailable: ${error instanceof Error ? error.message : String(error)}`];
 	}
 }
-//#endregion
 export { checkA11y };
 
 //# sourceMappingURL=a11y.mjs.map

package/dist/a11y.mjs.map

@@ -1 +1 @@
-{"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 debug line). 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): Promise<string[]> {\n  try {\n    const read = await page.evaluate(inPageReadA11yParameters);\n    if (read && read.dropped > 0)\n      logger?.debug({ dropped: read.dropped }, \"parameters.a11y: function values left out\");\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,QAAoC;CAC9E,IAAI;EACF,MAAM,OAAO,MAAM,KAAK,SAAS,wBAAwB;EACzD,IAAI,QAAQ,KAAK,UAAU,GACzB,QAAQ,MAAM,EAAE,SAAS,KAAK,QAAQ,GAAG,2CAA2C;EACtF,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"}
+{"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

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { existsSync } from "node:fs";
-//#region src/availability.ts
+// 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
@@ -25,7 +25,6 @@ function envPath(entry, env) {
 	const path = env["PUPPETEER_EXECUTABLE_PATH"];
 	return entry.target === "chromium" && path ? path : void 0;
 }
-//#endregion
 export { verifyLocalTargets };
 
 //# sourceMappingURL=availability.mjs.map

package/dist/browser.mjs

@@ -2,23 +2,26 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { RenderRuns } from "@storyshelf/core/adapter/capture-runner";
-//#region src/browser.ts
-/** Browser lifecycle and active-run tracking for Puppeteer. */
+// 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();
-/** Close a browser if present; `cancel` must never throw. */
-async function closeBrowser(browser) {
-	if (!browser) return;
-	await tryCloseBrowser(browser);
+/** 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) {
@@ -26,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 { RenderRuns } from \"@storyshelf/core/adapter/capture-runner\";\nimport type { Browser } from \"puppeteer-core\";\nimport type { ActiveRun } from \"./types.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/** 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":";;;;;;;AAOA,MAAa,aAAa,IAAI,WAAsB;;AAGpD,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

@@ -4,7 +4,6 @@ import { BrowserEntry } from "./targets.mjs";
 import "./types.mjs";
 import "./runtime-params.mjs";
 import { CaptureRunner } from "@storyshelf/core/adapter/capture-runner";
-//#region src/capture-runner.d.ts
 /** Create a CaptureRunner that renders Storybook stories with Puppeteer (Chromium via chrome-headless-shell). */
 declare function createPuppeteerCaptureRunner(options?: {
   /**
@@ -28,6 +27,5 @@ declare function createPuppeteerCaptureRunner(options?: {
   /** 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

@@ -2,25 +2,28 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { verifyLocalTargets } from "./availability.mjs";
-import { activeRuns, closeBrowser } from "./browser.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";
 import { flattenBrowsers } from "./targets.mjs";
 import { runTestEntries } from "./tests.mjs";
-import { createTargetOffers } from "@storyshelf/core/adapter/capture-runner";
+import { createTargetOffers, shutdownRemote } from "@storyshelf/core/adapter/capture-runner";
 import { recommendedNavigationTimeoutMs } from "@storyshelf/core/utils";
-//#region src/capture-runner.ts
+// 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) => {
+		launch: offers.guard(async (target, logger, context) => {
 			const remote = remotes.find((entry) => entry.target === target);
-			return remote ? await connectRemote(remote, logger) : await launchLocal(locals.find((entry) => entry.target === target), options.args);
+			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)
 	};
@@ -31,7 +34,7 @@ function createPuppeteerCaptureRunner(options = {}) {
 	return {
 		metadata: {
 			name: "Puppeteer",
-			version: "0.7.0",
+			version: "0.8.0",
 			description: "Puppeteer capture runner (chrome-headless-shell)",
 			kind: "puppeteer",
 			category: "capture-runner",
@@ -39,11 +42,12 @@ function createPuppeteerCaptureRunner(options = {}) {
 				return offers.current();
 			}
 		},
-		lifecycle: offers.lifecycle(async () => await Promise.resolve(verifyTargets(declared, locals))),
+		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()
 			};
 			const remove = activeRuns.add(input.buildId, input.runId, active);
 			try {
@@ -61,7 +65,8 @@ function createPuppeteerCaptureRunner(options = {}) {
 		async runTests(input) {
 			const active = {
 				cancelled: false,
-				browser: null
+				session: null,
+				abort: new AbortController()
 			};
 			const remove = activeRuns.add(input.buildId, input.runId, active);
 			try {
@@ -77,7 +82,8 @@ function createPuppeteerCaptureRunner(options = {}) {
 		async cancel(buildId, runId) {
 			await Promise.all(activeRuns.matching(buildId, runId).map(async (active) => {
 				active.cancelled = true;
-				await closeBrowser(active.browser);
+				active.abort?.abort();
+				await active.session?.release("cancelled");
 			}));
 		}
 	};
@@ -87,6 +93,16 @@ 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();
+		}
+	};
+}
 function envPositiveInt(name) {
 	return envInt(name, 1);
 }
@@ -94,7 +110,6 @@ function envInt(name, min) {
 	const parsed = Number.parseInt(process.env[name] ?? "", 10);
 	return parsed >= min ? parsed : void 0;
 }
-//#endregion
 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 {\n  createTargetOffers,\n  type CaptureRunner,\n  type RunnerTarget,\n} from \"@storyshelf/core/adapter/capture-runner\";\nimport { recommendedNavigationTimeoutMs } from \"@storyshelf/core/utils\";\nimport { verifyLocalTargets } from \"./availability.ts\";\nimport { activeRuns, closeBrowser } 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) => {\n      const remote = remotes.find((entry) => entry.target === target);\n      return remote\n        ? await connectRemote(remote, logger)\n        : await launchLocal(\n            locals.find((entry) => entry.target === target) as LocalTarget,\n            options.args,\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: offers.lifecycle(async () => await Promise.resolve(verifyTargets(declared, locals))),\n    async render(input: PuppeteerRenderInput) {\n      const active: ActiveRun = { cancelled: false, browser: null };\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, browser: null };\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          await closeBrowser(active.browser);\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\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":";;;;;;;;;;;;;;;;AAyBA,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,WAAW;GAC7C,MAAM,SAAS,QAAQ,MAAM,UAAU,MAAM,WAAW,MAAM;GAC9D,OAAO,SACH,MAAM,cAAc,QAAQ,MAAM,IAClC,MAAM,YACJ,OAAO,MAAM,UAAU,MAAM,WAAW,MAAM,GAC9C,QAAQ,IACV;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,OAAO,UAAU,YAAY,MAAM,QAAQ,QAAQ,cAAc,UAAU,MAAM,CAAC,CAAC;EAC9F,MAAM,OAAO,OAA6B;GACxC,MAAM,SAAoB;IAAE,WAAW;IAAO,SAAS;GAAK;GAC5D,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;GAAK;GAC5D,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,MAAM,aAAa,OAAO,OAAO;GACnC,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;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"}
+{"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

@@ -1,40 +1,31 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { TargetLaunchError, scrubConnection } from "@storyshelf/core/adapter/capture-runner";
-import { isRetryableConnectError, retryConnect } from "@storyshelf/core/utils";
+import { connectLeased, scrubConnection } from "@storyshelf/core/adapter/capture-runner";
 import puppeteer from "puppeteer-core";
-//#region src/connect.ts
+// 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 its browser. 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 {@link 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
-* or its credentials.
+* 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, logger) {
-	const { remote, target } = entry;
-	const connection = remote.connect(entry.engine);
-	try {
-		return await retryConnect(async () => await connectOnce(connection, remote.connectTimeoutMs), {
-			retries: remote.connectRetries,
-			backoffMs: remote.connectBackoffMs,
-			onRetry: (error, retry, delayMs) => {
-				logger?.warn({
-					target,
-					retry,
-					delayMs,
-					reason: reasonOf(error, connection)
-				}, "remote browser connect failed, retrying");
-			}
-		});
-	} catch (error) {
-		throw new TargetLaunchError(target, reasonOf(error, connection), {
-			cause: new Error(reasonOf(error, connection)),
-			transient: isRetryableConnectError(error)
-		});
-	}
+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");
@@ -49,7 +40,6 @@ 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);
 }
-//#endregion
 export { connectRemote };
 
 //# sourceMappingURL=connect.mjs.map

package/dist/connect.mjs.map

@@ -1 +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  TargetLaunchError,\n  scrubConnection,\n  type RemoteConnection,\n  type RemoteTarget,\n} from \"@storyshelf/core/adapter/capture-runner\";\nimport type { Logger } from \"@storyshelf/core/logger\";\nimport { isRetryableConnectError, retryConnect } from \"@storyshelf/core/utils\";\nimport type { Browser } from \"puppeteer-core\";\nimport puppeteer from \"puppeteer-core\";\n\n/**\n * Connect to `entry`'s service and return its browser. Connection-level failures are retried with\n * backoff, so a provider outage or a full plan costs time and not a story crash; what is left is\n * a {@link TargetLaunchError}, which fails the job at once (a refused credential also marks the\n * target unavailable, a service that is merely down does not). No message carries the endpoint\n * or its credentials.\n */\nexport async function connectRemote(entry: RemoteTarget, logger?: Logger): Promise<Browser> {\n  const { remote, target } = entry;\n  const connection = remote.connect(entry.engine);\n  try {\n    return await retryConnect(async () => await connectOnce(connection, remote.connectTimeoutMs), {\n      retries: remote.connectRetries,\n      backoffMs: remote.connectBackoffMs,\n      onRetry: (error, retry, delayMs) => {\n        logger?.warn(\n          { target, retry, delayMs, reason: reasonOf(error, connection) },\n          \"remote browser connect failed, retrying\",\n        );\n      },\n    });\n  } catch (error) {\n    throw new TargetLaunchError(target, reasonOf(error, connection), {\n      cause: new Error(reasonOf(error, connection)),\n      transient: isRetryableConnectError(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): 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":";;;;;;;;;;;;;;;AAmBA,eAAsB,cAAc,OAAqB,QAAmC;CAC1F,MAAM,EAAE,QAAQ,WAAW;CAC3B,MAAM,aAAa,OAAO,QAAQ,MAAM,MAAM;CAC9C,IAAI;EACF,OAAO,MAAM,aAAa,YAAY,MAAM,YAAY,YAAY,OAAO,gBAAgB,GAAG;GAC5F,SAAS,OAAO;GAChB,WAAW,OAAO;GAClB,UAAU,OAAO,OAAO,YAAY;IAClC,QAAQ,KACN;KAAE;KAAQ;KAAO;KAAS,QAAQ,SAAS,OAAO,UAAU;IAAE,GAC9D,yCACF;GACF;EACF,CAAC;CACH,SAAS,OAAO;EACd,MAAM,IAAI,kBAAkB,QAAQ,SAAS,OAAO,UAAU,GAAG;GAC/D,OAAO,IAAI,MAAM,SAAS,OAAO,UAAU,CAAC;GAC5C,WAAW,wBAAwB,KAAK;EAC1C,CAAC;CACH;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,YAAsC;CAEtE,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"}
+{"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/launch.mjs

@@ -3,7 +3,7 @@ import "node:url";
 import.meta.url;
 import { TargetLaunchError } from "@storyshelf/core/adapter/capture-runner";
 import puppeteer from "puppeteer-core";
-//#region src/launch.ts
+// 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
@@ -19,8 +19,8 @@ const DEFAULT_ARGS = [
 ];
 /**
 * 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, then closes every browser
-* through `teardown`.
+* 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,
@@ -47,7 +47,6 @@ async function launchLocal(entry, args) {
 function firstLine(error) {
 	return (error instanceof Error ? error.message : String(error)).split("\n").find((line) => line.trim() !== "")?.trim() ?? "the browser did not start";
 }
-//#endregion
 export { launchLocal };
 
 //# sourceMappingURL=launch.mjs.map

package/dist/launch.mjs.map

@@ -1 +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, then closes every browser\n * through `teardown`.\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"}
+{"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"}

package/dist/pages.d.mts

@@ -1,4 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
+import "./session.mjs";
 import "@storyshelf/core/adapter/capture-runner";
 import "puppeteer-core";

package/dist/pages.mjs

@@ -2,11 +2,11 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { installSettleRecorder } from "./settle.mjs";
-//#region src/pages.ts
+// src/pages.ts
 /** Lease a page for `viewport`: pooled when the context has a pool, otherwise a throwaway. */
 async function acquirePage(ctx, viewport) {
 	if (ctx.pagePool) return await ctx.pagePool.acquire(viewport);
-	const page = await ctx.browser.newPage();
+	const page = await ctx.session.newPage();
 	await page.setViewport({
 		width: viewport.width,
 		height: viewport.height
@@ -15,7 +15,8 @@ async function acquirePage(ctx, viewport) {
 	return {
 		page,
 		release: async () => {
-			await page.close();
+			await page.close().catch(() => {});
+			ctx.session.forgetPage(page);
 		}
 	};
 }
@@ -27,9 +28,9 @@ async function acquirePage(ctx, viewport) {
 */
 var PagePool = class {
 	free = [];
-	browser;
-	constructor(browser) {
-		this.browser = browser;
+	session;
+	constructor(session) {
+		this.session = session;
 	}
 	async acquire(viewport) {
 		const entry = this.free.pop() ?? await this.open();
@@ -41,18 +42,18 @@ var PagePool = class {
 			page: entry.page,
 			release: async (reusable) => {
 				if (reusable && await reset(entry)) this.free.push(entry);
-				else await closeEntry(entry);
+				else await this.close(entry);
 			}
 		};
 	}
 	/** Close every idle page; call before the browser is replaced or closed. */
 	async dispose() {
 		await Promise.all(this.free.splice(0).map(async (entry) => {
-			await closeEntry(entry);
+			await this.close(entry);
 		}));
 	}
 	async open() {
-		const context = await this.browser.createBrowserContext();
+		const context = await this.session.createBrowserContext();
 		const page = await context.newPage();
 		await installSettleRecorder(page);
 		return {
@@ -60,6 +61,10 @@ var PagePool = class {
 			page
 		};
 	}
+	async close(entry) {
+		await entry.context.close().catch(() => {});
+		this.session.forgetContext(entry.context);
+	}
 };
 /** Wipe everything a story could leave behind; false when the page can't be trusted again. */
 async function reset(entry) {
@@ -72,9 +77,6 @@ async function reset(entry) {
 		return false;
 	}
 }
-async function closeEntry(entry) {
-	await entry.context.close().catch(() => {});
-}
 /** Runs in the page: clears web storage and IndexedDB for the current origin. */
 async function clearBrowserState() {
 	const scope = globalThis;
@@ -83,7 +85,6 @@ async function clearBrowserState() {
 	const databases = await scope.indexedDB?.databases?.() ?? [];
 	for (const database of databases) if (database.name) scope.indexedDB?.deleteDatabase(database.name);
 }
-//#endregion
 export { PagePool, acquirePage };
 
 //# sourceMappingURL=pages.mjs.map

package/dist/pages.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"pages.mjs","names":[],"sources":["../src/pages.ts"],"sourcesContent":["/** Page leasing for captures: a fresh page each time, or a small reusable pool (opt-in). */\n\nimport type { Viewport } from \"@storyshelf/core/adapter/capture-runner\";\nimport type { Browser, BrowserContext, Page } from \"puppeteer-core\";\nimport { installSettleRecorder } from \"./settle.ts\";\n\n/** A page on loan for one capture; `release(false)` discards it instead of reusing it. */\nexport interface PageLease {\n  page: Page;\n  release(reusable: boolean): Promise<void>;\n}\n\n/** Lease a page for `viewport`: pooled when the context has a pool, otherwise a throwaway. */\nexport async function acquirePage(\n  ctx: { browser: Browser; pagePool?: PagePool },\n  viewport: Viewport,\n): Promise<PageLease> {\n  if (ctx.pagePool) return await ctx.pagePool.acquire(viewport);\n  const page = await ctx.browser.newPage();\n  await page.setViewport({ width: viewport.width, height: viewport.height });\n  await installSettleRecorder(page);\n  return {\n    page,\n    release: async () => {\n      await page.close();\n    },\n  };\n}\n\ninterface Entry {\n  context: BrowserContext;\n  page: Page;\n}\n\n/**\n * Reuses pages (each in its own browser context) across captures to skip\n * per-capture startup and keep Storybook's JS in the HTTP cache. A page is\n * reset between captures (storage and cookies cleared, blank document) and\n * discarded, never reused, after a failed capture.\n */\nexport class PagePool {\n  private readonly free: Entry[] = [];\n\n  private readonly browser: Browser;\n\n  constructor(browser: Browser) {\n    this.browser = browser;\n  }\n\n  async acquire(viewport: Viewport): Promise<PageLease> {\n    const entry = this.free.pop() ?? (await this.open());\n    await entry.page.setViewport({ width: viewport.width, height: viewport.height });\n    return {\n      page: entry.page,\n      release: async (reusable) => {\n        if (reusable && (await reset(entry))) this.free.push(entry);\n        else await closeEntry(entry);\n      },\n    };\n  }\n\n  /** Close every idle page; call before the browser is replaced or closed. */\n  async dispose(): Promise<void> {\n    await Promise.all(\n      this.free.splice(0).map(async (entry) => {\n        await closeEntry(entry);\n      }),\n    );\n  }\n\n  private async open(): Promise<Entry> {\n    const context = await this.browser.createBrowserContext();\n    const page = await context.newPage();\n    await installSettleRecorder(page);\n    return { context, page };\n  }\n}\n\n/** Wipe everything a story could leave behind; false when the page can't be trusted again. */\nasync function reset(entry: Entry): Promise<boolean> {\n  try {\n    await entry.page.evaluate(clearBrowserState);\n    await entry.context.deleteCookie(...(await entry.context.cookies()));\n    await entry.page.goto(\"about:blank\");\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nasync function closeEntry(entry: Entry): Promise<void> {\n  await entry.context.close().catch(() => {});\n}\n\n/** Runs in the page: clears web storage and IndexedDB for the current origin. */\nasync function clearBrowserState(): Promise<void> {\n  const scope = globalThis as unknown as {\n    localStorage: { clear(): void };\n    sessionStorage: { clear(): void };\n    indexedDB?: {\n      databases?: () => Promise<{ name?: string }[]>;\n      deleteDatabase(name: string): unknown;\n    };\n  };\n  scope.localStorage.clear();\n  scope.sessionStorage.clear();\n  const databases = (await scope.indexedDB?.databases?.()) ?? [];\n  for (const database of databases) {\n    if (database.name) scope.indexedDB?.deleteDatabase(database.name);\n  }\n}\n"],"mappings":";;;;;;AAaA,eAAsB,YACpB,KACA,UACoB;CACpB,IAAI,IAAI,UAAU,OAAO,MAAM,IAAI,SAAS,QAAQ,QAAQ;CAC5D,MAAM,OAAO,MAAM,IAAI,QAAQ,QAAQ;CACvC,MAAM,KAAK,YAAY;EAAE,OAAO,SAAS;EAAO,QAAQ,SAAS;CAAO,CAAC;CACzE,MAAM,sBAAsB,IAAI;CAChC,OAAO;EACL;EACA,SAAS,YAAY;GACnB,MAAM,KAAK,MAAM;EACnB;CACF;AACF;;;;;;;AAaA,IAAa,WAAb,MAAsB;CACpB,OAAiC,CAAC;CAElC;CAEA,YAAY,SAAkB;EAC5B,KAAK,UAAU;CACjB;CAEA,MAAM,QAAQ,UAAwC;EACpD,MAAM,QAAQ,KAAK,KAAK,IAAI,KAAM,MAAM,KAAK,KAAK;EAClD,MAAM,MAAM,KAAK,YAAY;GAAE,OAAO,SAAS;GAAO,QAAQ,SAAS;EAAO,CAAC;EAC/E,OAAO;GACL,MAAM,MAAM;GACZ,SAAS,OAAO,aAAa;IAC3B,IAAI,YAAa,MAAM,MAAM,KAAK,GAAI,KAAK,KAAK,KAAK,KAAK;SACrD,MAAM,WAAW,KAAK;GAC7B;EACF;CACF;;CAGA,MAAM,UAAyB;EAC7B,MAAM,QAAQ,IACZ,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,UAAU;GACvC,MAAM,WAAW,KAAK;EACxB,CAAC,CACH;CACF;CAEA,MAAc,OAAuB;EACnC,MAAM,UAAU,MAAM,KAAK,QAAQ,qBAAqB;EACxD,MAAM,OAAO,MAAM,QAAQ,QAAQ;EACnC,MAAM,sBAAsB,IAAI;EAChC,OAAO;GAAE;GAAS;EAAK;CACzB;AACF;;AAGA,eAAe,MAAM,OAAgC;CACnD,IAAI;EACF,MAAM,MAAM,KAAK,SAAS,iBAAiB;EAC3C,MAAM,MAAM,QAAQ,aAAa,GAAI,MAAM,MAAM,QAAQ,QAAQ,CAAE;EACnE,MAAM,MAAM,KAAK,KAAK,aAAa;EACnC,OAAO;CACT,QAAQ;EACN,OAAO;CACT;AACF;AAEA,eAAe,WAAW,OAA6B;CACrD,MAAM,MAAM,QAAQ,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;AAC5C;;AAGA,eAAe,oBAAmC;CAChD,MAAM,QAAQ;CAQd,MAAM,aAAa,MAAM;CACzB,MAAM,eAAe,MAAM;CAC3B,MAAM,YAAa,MAAM,MAAM,WAAW,YAAY,KAAM,CAAC;CAC7D,KAAK,MAAM,YAAY,WACrB,IAAI,SAAS,MAAM,MAAM,WAAW,eAAe,SAAS,IAAI;AAEpE"}
+{"version":3,"file":"pages.mjs","names":[],"sources":["../src/pages.ts"],"sourcesContent":["/** Page leasing for captures: a fresh page each time, or a small reusable pool (opt-in). */\n\nimport type { Viewport } from \"@storyshelf/core/adapter/capture-runner\";\nimport type { BrowserContext, Page } from \"puppeteer-core\";\nimport type { BrowserSession } from \"./session.ts\";\nimport { installSettleRecorder } from \"./settle.ts\";\n\n/** A page on loan for one capture; `release(false)` discards it instead of reusing it. */\nexport interface PageLease {\n  page: Page;\n  release(reusable: boolean): Promise<void>;\n}\n\n/** Lease a page for `viewport`: pooled when the context has a pool, otherwise a throwaway. */\nexport async function acquirePage(\n  ctx: { session: BrowserSession; pagePool?: PagePool },\n  viewport: Viewport,\n): Promise<PageLease> {\n  if (ctx.pagePool) return await ctx.pagePool.acquire(viewport);\n  const page = await ctx.session.newPage();\n  await page.setViewport({ width: viewport.width, height: viewport.height });\n  await installSettleRecorder(page);\n  return {\n    page,\n    release: async () => {\n      await page.close().catch(() => {});\n      ctx.session.forgetPage(page);\n    },\n  };\n}\n\ninterface Entry {\n  context: BrowserContext;\n  page: Page;\n}\n\n/**\n * Reuses pages (each in its own browser context) across captures to skip\n * per-capture startup and keep Storybook's JS in the HTTP cache. A page is\n * reset between captures (storage and cookies cleared, blank document) and\n * discarded, never reused, after a failed capture.\n */\nexport class PagePool {\n  private readonly free: Entry[] = [];\n\n  private readonly session: BrowserSession;\n\n  constructor(session: BrowserSession) {\n    this.session = session;\n  }\n\n  async acquire(viewport: Viewport): Promise<PageLease> {\n    const entry = this.free.pop() ?? (await this.open());\n    await entry.page.setViewport({ width: viewport.width, height: viewport.height });\n    return {\n      page: entry.page,\n      release: async (reusable) => {\n        if (reusable && (await reset(entry))) this.free.push(entry);\n        else await this.close(entry);\n      },\n    };\n  }\n\n  /** Close every idle page; call before the browser is replaced or closed. */\n  async dispose(): Promise<void> {\n    await Promise.all(\n      this.free.splice(0).map(async (entry) => {\n        await this.close(entry);\n      }),\n    );\n  }\n\n  private async open(): Promise<Entry> {\n    const context = await this.session.createBrowserContext();\n    const page = await context.newPage();\n    await installSettleRecorder(page);\n    return { context, page };\n  }\n\n  private async close(entry: Entry): Promise<void> {\n    await entry.context.close().catch(() => {});\n    this.session.forgetContext(entry.context);\n  }\n}\n\n/** Wipe everything a story could leave behind; false when the page can't be trusted again. */\nasync function reset(entry: Entry): Promise<boolean> {\n  try {\n    await entry.page.evaluate(clearBrowserState);\n    await entry.context.deleteCookie(...(await entry.context.cookies()));\n    await entry.page.goto(\"about:blank\");\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/** Runs in the page: clears web storage and IndexedDB for the current origin. */\nasync function clearBrowserState(): Promise<void> {\n  const scope = globalThis as unknown as {\n    localStorage: { clear(): void };\n    sessionStorage: { clear(): void };\n    indexedDB?: {\n      databases?: () => Promise<{ name?: string }[]>;\n      deleteDatabase(name: string): unknown;\n    };\n  };\n  scope.localStorage.clear();\n  scope.sessionStorage.clear();\n  const databases = (await scope.indexedDB?.databases?.()) ?? [];\n  for (const database of databases) {\n    if (database.name) scope.indexedDB?.deleteDatabase(database.name);\n  }\n}\n"],"mappings":";;;;;;AAcA,eAAsB,YACpB,KACA,UACoB;CACpB,IAAI,IAAI,UAAU,OAAO,MAAM,IAAI,SAAS,QAAQ,QAAQ;CAC5D,MAAM,OAAO,MAAM,IAAI,QAAQ,QAAQ;CACvC,MAAM,KAAK,YAAY;EAAE,OAAO,SAAS;EAAO,QAAQ,SAAS;CAAO,CAAC;CACzE,MAAM,sBAAsB,IAAI;CAChC,OAAO;EACL;EACA,SAAS,YAAY;GACnB,MAAM,KAAK,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;GACjC,IAAI,QAAQ,WAAW,IAAI;EAC7B;CACF;AACF;;;;;;;AAaA,IAAa,WAAb,MAAsB;CACpB,OAAiC,CAAC;CAElC;CAEA,YAAY,SAAyB;EACnC,KAAK,UAAU;CACjB;CAEA,MAAM,QAAQ,UAAwC;EACpD,MAAM,QAAQ,KAAK,KAAK,IAAI,KAAM,MAAM,KAAK,KAAK;EAClD,MAAM,MAAM,KAAK,YAAY;GAAE,OAAO,SAAS;GAAO,QAAQ,SAAS;EAAO,CAAC;EAC/E,OAAO;GACL,MAAM,MAAM;GACZ,SAAS,OAAO,aAAa;IAC3B,IAAI,YAAa,MAAM,MAAM,KAAK,GAAI,KAAK,KAAK,KAAK,KAAK;SACrD,MAAM,KAAK,MAAM,KAAK;GAC7B;EACF;CACF;;CAGA,MAAM,UAAyB;EAC7B,MAAM,QAAQ,IACZ,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,UAAU;GACvC,MAAM,KAAK,MAAM,KAAK;EACxB,CAAC,CACH;CACF;CAEA,MAAc,OAAuB;EACnC,MAAM,UAAU,MAAM,KAAK,QAAQ,qBAAqB;EACxD,MAAM,OAAO,MAAM,QAAQ,QAAQ;EACnC,MAAM,sBAAsB,IAAI;EAChC,OAAO;GAAE;GAAS;EAAK;CACzB;CAEA,MAAc,MAAM,OAA6B;EAC/C,MAAM,MAAM,QAAQ,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;EAC1C,KAAK,QAAQ,cAAc,MAAM,OAAO;CAC1C;AACF;;AAGA,eAAe,MAAM,OAAgC;CACnD,IAAI;EACF,MAAM,MAAM,KAAK,SAAS,iBAAiB;EAC3C,MAAM,MAAM,QAAQ,aAAa,GAAI,MAAM,MAAM,QAAQ,QAAQ,CAAE;EACnE,MAAM,MAAM,KAAK,KAAK,aAAa;EACnC,OAAO;CACT,QAAQ;EACN,OAAO;CACT;AACF;;AAGA,eAAe,oBAAmC;CAChD,MAAM,QAAQ;CAQd,MAAM,aAAa,MAAM;CACzB,MAAM,eAAe,MAAM;CAC3B,MAAM,YAAa,MAAM,MAAM,WAAW,YAAY,KAAM,CAAC;CAC7D,KAAK,MAAM,YAAY,WACrB,IAAI,SAAS,MAAM,MAAM,WAAW,eAAe,SAAS,IAAI;AAEpE"}