@storyshelf/runner-playwright 0.7.0 → 0.8.0

package/dist/remote/remote.mjs

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { defineRemote } from "@storyshelf/core/adapter/capture-runner";
-//#region src/remote/remote.ts
+// src/remote/remote.ts
 /** The generic remote browser entry: every preset is sugar over it (ADR 0007, decision 1). */
 /** What the Playwright runner can drive: every engine, over its own protocol or CDP (Chromium only). */
 const SUPPORT = {
@@ -21,18 +21,35 @@ const SUPPORT = {
 * throws when the runner is created for a bad name, engine, protocol or endpoint.
 *
 * ```ts
+* // A fixed service:
 * remote({
 *   name: "mygrid",
 *   engines: ["chromium", "firefox", "webkit"],
-*   connect: () => ({ protocol: "playwright", endpoint: "wss://grid.example/", exposeNetwork: "<loopback>" }),
+*   protocol: "playwright",
+*   reach: "loopback", // its browser can route back to this host
+*   connect: { endpoint: "wss://grid.example/" },
 *   sessions: 4,
+*   maxPagesPerConnection: 2,
+* });
+*
+* // A service that must be woken first, with a lease handed back to `release`:
+* remote<{ id: string }>({
+*   name: "pool",
+*   engines: ["chromium"],
+*   protocol: "playwright",
+*   reach: "loopback",
+*   sessions: 4,
+*   connect: async ({ shardIndex, signal }) => {
+*     const server = await wake(shardIndex, signal);
+*     return { endpoint: server.endpoint, lease: { id: server.id } };
+*   },
+*   release: async (lease, { outcome }) => await suspend(lease.id, outcome),
 * });
 * ```
 */
 function remote(options) {
 	return defineRemote(options, SUPPORT);
 }
-//#endregion
 export { remote };
 
 //# sourceMappingURL=remote.mjs.map

package/dist/remote/remote.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"remote.mjs","names":[],"sources":["../../src/remote/remote.ts"],"sourcesContent":["/** The generic remote browser entry: every preset is sugar over it (ADR 0007, decision 1). */\nimport {\n  defineRemote,\n  type BrowserName,\n  type RemoteBrowser,\n  type RemoteConnection,\n  type RemoteOptions,\n  type RemoteSupport,\n} from \"@storyshelf/core/adapter/capture-runner\";\n\n/** What the Playwright runner can drive: every engine, over its own protocol or CDP (Chromium only). */\nconst SUPPORT: RemoteSupport = {\n  engines: [\"chromium\", \"firefox\", \"webkit\", \"chrome\"],\n  protocols: [\"playwright\", \"cdp\"],\n  label: \"remote()\",\n};\n\n/**\n * A browser service the runner connects to instead of launching, for `browsers`. It offers one\n * target per engine, `<engine>@<name>`, each with its own baselines (ADR 0007, decision 3), and\n * throws when the runner is created for a bad name, engine, protocol or endpoint.\n *\n * ```ts\n * remote({\n *   name: \"mygrid\",\n *   engines: [\"chromium\", \"firefox\", \"webkit\"],\n *   connect: () => ({ protocol: \"playwright\", endpoint: \"wss://grid.example/\", exposeNetwork: \"<loopback>\" }),\n *   sessions: 4,\n * });\n * ```\n */\nexport function remote(options: RemoteOptions): RemoteBrowser {\n  return defineRemote(options, SUPPORT);\n}\n\nexport type { BrowserName, RemoteBrowser, RemoteConnection, RemoteOptions };\n"],"mappings":";;;;;;;AAWA,MAAM,UAAyB;CAC7B,SAAS;EAAC;EAAY;EAAW;EAAU;CAAQ;CACnD,WAAW,CAAC,cAAc,KAAK;CAC/B,OAAO;AACT;;;;;;;;;;;;;;;AAgBA,SAAgB,OAAO,SAAuC;CAC5D,OAAO,aAAa,SAAS,OAAO;AACtC"}
+{"version":3,"file":"remote.mjs","names":[],"sources":["../../src/remote/remote.ts"],"sourcesContent":["/** The generic remote browser entry: every preset is sugar over it (ADR 0007, decision 1). */\nimport {\n  defineRemote,\n  type BrowserName,\n  type RemoteBrowser,\n  type RemoteConnection,\n  type RemoteOptions,\n  type RemoteSupport,\n} from \"@storyshelf/core/adapter/capture-runner\";\n\n/** What the Playwright runner can drive: every engine, over its own protocol or CDP (Chromium only). */\nconst SUPPORT: RemoteSupport = {\n  engines: [\"chromium\", \"firefox\", \"webkit\", \"chrome\"],\n  protocols: [\"playwright\", \"cdp\"],\n  label: \"remote()\",\n};\n\n/**\n * A browser service the runner connects to instead of launching, for `browsers`. It offers one\n * target per engine, `<engine>@<name>`, each with its own baselines (ADR 0007, decision 3), and\n * throws when the runner is created for a bad name, engine, protocol or endpoint.\n *\n * ```ts\n * // A fixed service:\n * remote({\n *   name: \"mygrid\",\n *   engines: [\"chromium\", \"firefox\", \"webkit\"],\n *   protocol: \"playwright\",\n *   reach: \"loopback\", // its browser can route back to this host\n *   connect: { endpoint: \"wss://grid.example/\" },\n *   sessions: 4,\n *   maxPagesPerConnection: 2,\n * });\n *\n * // A service that must be woken first, with a lease handed back to `release`:\n * remote<{ id: string }>({\n *   name: \"pool\",\n *   engines: [\"chromium\"],\n *   protocol: \"playwright\",\n *   reach: \"loopback\",\n *   sessions: 4,\n *   connect: async ({ shardIndex, signal }) => {\n *     const server = await wake(shardIndex, signal);\n *     return { endpoint: server.endpoint, lease: { id: server.id } };\n *   },\n *   release: async (lease, { outcome }) => await suspend(lease.id, outcome),\n * });\n * ```\n */\nexport function remote<TLease = unknown>(options: RemoteOptions<TLease>): RemoteBrowser {\n  return defineRemote(options, SUPPORT);\n}\n\nexport type { BrowserName, RemoteBrowser, RemoteConnection, RemoteOptions };\n"],"mappings":";;;;;;;AAWA,MAAM,UAAyB;CAC7B,SAAS;EAAC;EAAY;EAAW;EAAU;CAAQ;CACnD,WAAW,CAAC,cAAc,KAAK;CAC/B,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,SAAgB,OAAyB,SAA+C;CACtF,OAAO,aAAa,SAAS,OAAO;AACtC"}

package/dist/remote-environment.mjs

@@ -2,35 +2,48 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { messageOf } from "./browser.mjs";
-import { FONT_PROBE_FAMILIES, inPageProbe, remoteEnvironment } from "@storyshelf/core/utils";
-//#region src/remote-environment.ts
+import { FONT_PROBE_FAMILIES, boundedProbe, inPageProbe, remoteEnvironment } from "@storyshelf/core/utils";
+// src/remote-environment.ts
 /**
 * The fingerprint of the browser a render drove: its version, and what a blank page in it reports
 * (OS, pixel ratio, installed fonts). Never `process.platform` or `fc-list`, which describe this
-* host. A page that cannot be probed leaves those fields out, and an unknown component is not a
-* change (ADR 0005), so a service outage here cannot rewrite baselines.
+* host. The probe is bounded by `remote.timeouts.probeMs`: a page that cannot be probed, or that
+* overruns, leaves those fields out with a warning, and an unknown component is not a change
+* (ADR 0005), so a service outage here cannot rewrite baselines. A cancel is not an outage: it
+* throws `Capture cancelled` so the run stops and is never stored as an unknown environment.
 */
-async function measureRemote(browser, remote, logger) {
+async function measureRemote(browser, remote, options = {}) {
 	return remoteEnvironment({
 		browserVersion: typeof browser.version === "function" ? browser.version() : void 0,
-		probe: await probeBlankPage(browser, logger),
+		probe: await probeBlankPage(browser, remote.timeouts.probeMs, options),
 		declaredPlatform: remote.platform
 	});
 }
-async function probeBlankPage(browser, logger) {
-	try {
-		const page = await browser.newPage();
-		try {
-			return await page.evaluate(inPageProbe, [...FONT_PROBE_FAMILIES]);
-		} finally {
-			await page.close();
+/**
+* Open a blank page, read the probe and close the page, within the limit. The page is closed on
+* every path: after a result, after a failure, and after a timeout or cancel, when the work that
+* opened it may still be pending (a page it opens late is closed by the work itself).
+*/
+async function probeBlankPage(browser, timeoutMs, options) {
+	let page;
+	const outcome = await boundedProbe({
+		timeoutMs,
+		signal: options.signal,
+		run: async ({ stopped }) => {
+			const opened = await browser.newPage();
+			page = opened;
+			if (stopped()) {
+				await opened.close().catch(() => {});
+				throw new Error("the measurement stopped before its page opened");
+			}
+			return await opened.evaluate(inPageProbe, [...FONT_PROBE_FAMILIES]);
 		}
-	} catch (error) {
-		logger?.warn({ reason: messageOf(error) }, "could not measure the remote browser");
-		return;
-	}
+	});
+	await page?.close().catch(() => {});
+	if (outcome.status === "done") return outcome.value;
+	if (outcome.status === "cancelled") throw new Error("Capture cancelled");
+	options.logger?.warn(outcome.status === "timeout" ? { timeoutMs } : { reason: messageOf(outcome.error) }, outcome.status === "timeout" ? "measuring the remote browser timed out; its environment is unknown" : "could not measure the remote browser");
 }
-//#endregion
 export { measureRemote };
 
 //# sourceMappingURL=remote-environment.mjs.map

package/dist/remote-environment.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"remote-environment.mjs","names":[],"sources":["../src/remote-environment.ts"],"sourcesContent":["/** Measuring a remote browser's environment from inside it (ADR 0007, decision 2). */\nimport type { CaptureEnvironment, RemoteBrowser } from \"@storyshelf/core/adapter/capture-runner\";\nimport type { Logger } from \"@storyshelf/core/logger\";\nimport {\n  FONT_PROBE_FAMILIES,\n  inPageProbe,\n  remoteEnvironment,\n  type BrowserProbe,\n} from \"@storyshelf/core/utils\";\nimport type { Browser } from \"playwright-core\";\nimport { messageOf } from \"./browser.ts\";\n\n/**\n * The fingerprint of the browser a render drove: its version, and what a blank page in it reports\n * (OS, pixel ratio, installed fonts). Never `process.platform` or `fc-list`, which describe this\n * host. A page that cannot be probed leaves those fields out, and an unknown component is not a\n * change (ADR 0005), so a service outage here cannot rewrite baselines.\n */\nexport async function measureRemote(\n  browser: Browser,\n  remote: RemoteBrowser,\n  logger?: Logger,\n): Promise<CaptureEnvironment> {\n  return remoteEnvironment({\n    browserVersion: typeof browser.version === \"function\" ? browser.version() : undefined,\n    probe: await probeBlankPage(browser, logger),\n    declaredPlatform: remote.platform,\n  });\n}\n\nasync function probeBlankPage(\n  browser: Browser,\n  logger?: Logger,\n): Promise<BrowserProbe | undefined> {\n  try {\n    const page = await browser.newPage();\n    try {\n      return await page.evaluate(inPageProbe, [...FONT_PROBE_FAMILIES]);\n    } finally {\n      await page.close();\n    }\n  } catch (error) {\n    logger?.warn({ reason: messageOf(error) }, \"could not measure the remote browser\");\n    return undefined;\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAkBA,eAAsB,cACpB,SACA,QACA,QAC6B;CAC7B,OAAO,kBAAkB;EACvB,gBAAgB,OAAO,QAAQ,YAAY,aAAa,QAAQ,QAAQ,IAAI,KAAA;EAC5E,OAAO,MAAM,eAAe,SAAS,MAAM;EAC3C,kBAAkB,OAAO;CAC3B,CAAC;AACH;AAEA,eAAe,eACb,SACA,QACmC;CACnC,IAAI;EACF,MAAM,OAAO,MAAM,QAAQ,QAAQ;EACnC,IAAI;GACF,OAAO,MAAM,KAAK,SAAS,aAAa,CAAC,GAAG,mBAAmB,CAAC;EAClE,UAAU;GACR,MAAM,KAAK,MAAM;EACnB;CACF,SAAS,OAAO;EACd,QAAQ,KAAK,EAAE,QAAQ,UAAU,KAAK,EAAE,GAAG,sCAAsC;EACjF;CACF;AACF"}
+{"version":3,"file":"remote-environment.mjs","names":[],"sources":["../src/remote-environment.ts"],"sourcesContent":["/** Measuring a remote browser's environment from inside it (ADR 0007, decision 2). */\nimport type { CaptureEnvironment, RemoteBrowser } from \"@storyshelf/core/adapter/capture-runner\";\nimport type { Logger } from \"@storyshelf/core/logger\";\nimport {\n  FONT_PROBE_FAMILIES,\n  boundedProbe,\n  inPageProbe,\n  remoteEnvironment,\n  type BrowserProbe,\n} from \"@storyshelf/core/utils\";\nimport type { Browser, Page } from \"playwright-core\";\nimport { messageOf } from \"./browser.ts\";\n\n/** What stops a measurement: the run's cancel signal, and where warnings go. */\nexport interface MeasureOptions {\n  logger?: Logger | undefined;\n  /** Aborted when the run is cancelled; the measurement then stops the run. */\n  signal?: AbortSignal | undefined;\n}\n\n/**\n * The fingerprint of the browser a render drove: its version, and what a blank page in it reports\n * (OS, pixel ratio, installed fonts). Never `process.platform` or `fc-list`, which describe this\n * host. The probe is bounded by `remote.timeouts.probeMs`: a page that cannot be probed, or that\n * overruns, leaves those fields out with a warning, and an unknown component is not a change\n * (ADR 0005), so a service outage here cannot rewrite baselines. A cancel is not an outage: it\n * throws `Capture cancelled` so the run stops and is never stored as an unknown environment.\n */\nexport async function measureRemote(\n  browser: Browser,\n  remote: RemoteBrowser,\n  options: MeasureOptions = {},\n): Promise<CaptureEnvironment> {\n  return remoteEnvironment({\n    browserVersion: typeof browser.version === \"function\" ? browser.version() : undefined,\n    probe: await probeBlankPage(browser, remote.timeouts.probeMs, options),\n    declaredPlatform: remote.platform,\n  });\n}\n\n/**\n * Open a blank page, read the probe and close the page, within the limit. The page is closed on\n * every path: after a result, after a failure, and after a timeout or cancel, when the work that\n * opened it may still be pending (a page it opens late is closed by the work itself).\n */\nasync function probeBlankPage(\n  browser: Browser,\n  timeoutMs: number,\n  options: MeasureOptions,\n): Promise<BrowserProbe | undefined> {\n  let page: Page | undefined;\n  const outcome = await boundedProbe({\n    timeoutMs,\n    signal: options.signal,\n    run: async ({ stopped }) => {\n      const opened = await browser.newPage();\n      page = opened;\n      if (stopped()) {\n        await opened.close().catch(() => {});\n        throw new Error(\"the measurement stopped before its page opened\");\n      }\n      return await opened.evaluate(inPageProbe, [...FONT_PROBE_FAMILIES]);\n    },\n  });\n  await page?.close().catch(() => {});\n  if (outcome.status === \"done\") {\n    return outcome.value;\n  }\n  if (outcome.status === \"cancelled\") {\n    throw new Error(\"Capture cancelled\");\n  }\n  options.logger?.warn(\n    outcome.status === \"timeout\" ? { timeoutMs } : { reason: messageOf(outcome.error) },\n    outcome.status === \"timeout\"\n      ? \"measuring the remote browser timed out; its environment is unknown\"\n      : \"could not measure the remote browser\",\n  );\n  return undefined;\n}\n"],"mappings":";;;;;;;;;;;;;;AA4BA,eAAsB,cACpB,SACA,QACA,UAA0B,CAAC,GACE;CAC7B,OAAO,kBAAkB;EACvB,gBAAgB,OAAO,QAAQ,YAAY,aAAa,QAAQ,QAAQ,IAAI,KAAA;EAC5E,OAAO,MAAM,eAAe,SAAS,OAAO,SAAS,SAAS,OAAO;EACrE,kBAAkB,OAAO;CAC3B,CAAC;AACH;;;;;;AAOA,eAAe,eACb,SACA,WACA,SACmC;CACnC,IAAI;CACJ,MAAM,UAAU,MAAM,aAAa;EACjC;EACA,QAAQ,QAAQ;EAChB,KAAK,OAAO,EAAE,cAAc;GAC1B,MAAM,SAAS,MAAM,QAAQ,QAAQ;GACrC,OAAO;GACP,IAAI,QAAQ,GAAG;IACb,MAAM,OAAO,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IACnC,MAAM,IAAI,MAAM,gDAAgD;GAClE;GACA,OAAO,MAAM,OAAO,SAAS,aAAa,CAAC,GAAG,mBAAmB,CAAC;EACpE;CACF,CAAC;CACD,MAAM,MAAM,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;CAClC,IAAI,QAAQ,WAAW,QACrB,OAAO,QAAQ;CAEjB,IAAI,QAAQ,WAAW,aACrB,MAAM,IAAI,MAAM,mBAAmB;CAErC,QAAQ,QAAQ,KACd,QAAQ,WAAW,YAAY,EAAE,UAAU,IAAI,EAAE,QAAQ,UAAU,QAAQ,KAAK,EAAE,GAClF,QAAQ,WAAW,YACf,uEACA,sCACN;AAEF"}

package/dist/runtime-params.mjs

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { mergeParameters } from "@storyshelf/core/capture";
-//#region src/runtime-params.ts
+// src/runtime-params.ts
 /** Per-run runtime-parameter extraction cache (ADR 0017). */
 /** Create the per-run runtime-parameter cache shared across captures. */
 function createRuntimeParamsState() {
@@ -61,7 +61,6 @@ async function readExtractedParameters(page) {
 function hasEntries(map) {
 	return Boolean(map && Object.keys(map).length > 0);
 }
-//#endregion
 export { createRuntimeParamsState, extractAllParameters, runtimeParametersForStory };
 
 //# sourceMappingURL=runtime-params.mjs.map

package/dist/screenshot.mjs

@@ -1,32 +1,53 @@
 import "node:path";
 import "node:url";
 import.meta.url;
+import { TransientCaptureError, capturePhase } from "./capture-retry.mjs";
 import { awaitPaint, settleTimeoutOf, waitForSettled } from "./settle.mjs";
 import { acquirePage } from "./pages.mjs";
 import { runtimeParametersForStory } from "./runtime-params.mjs";
 import { checkA11y } from "./a11y.mjs";
 import { runPlay } from "./play.mjs";
-import { getScreenshotPlan } from "@storyshelf/core/capture";
-//#region src/screenshot.ts
+import { cleanIgnoreSelectors, getScreenshotPlan, ignoreStylesheet } from "@storyshelf/core/capture";
+// src/screenshot.ts
 /** Capture a screenshot for one story/viewport, returning buffer + a11y violations. */
-async function captureScreenshot(ctx, inputStory, viewport) {
-	const lease = await acquirePage(ctx, viewport);
+async function captureScreenshot(ctx, inputStory, viewport, fresh = false) {
+	return await captureLeased(ctx, inputStory, viewport, await acquirePage(fresh ? { browser: ctx.browser } : ctx, viewport));
+}
+async function captureLeased(ctx, inputStory, viewport, lease) {
 	let reusable = false;
+	const crash = watchCrash(lease.page);
 	if (ctx.navigationTimeoutMs) lease.page.setDefaultTimeout(ctx.navigationTimeoutMs);
 	try {
 		const result = await runCapture(lease.page, ctx, inputStory, viewport);
 		reusable = true;
 		return result;
+	} catch (error) {
+		throw crash.classify(error);
 	} finally {
+		crash.dispose();
 		await lease.release(reusable);
 	}
 }
+function watchCrash(page) {
+	let crashed = false;
+	const onCrash = () => {
+		crashed = true;
+	};
+	page.on?.("crash", onCrash);
+	return {
+		classify: (error) => crashed ? new TransientCaptureError("crash", error) : error,
+		dispose: () => {
+			page.off?.("crash", onCrash);
+		}
+	};
+}
 async function runCapture(page, ctx, inputStory, viewport) {
 	const story = await navigateAndEnrich(ctx, page, inputStory, viewport);
 	await waitUntilReady(ctx, page, story);
 	if (ctx.executePlay) await runPlay(page, story.id, ctx.playTimeoutMs ?? 1e4);
-	const a11yViolations = await getA11y(ctx, page);
+	const a11yViolations = await getA11y(ctx, page, story);
 	await settlePage(page, story);
+	await maskIgnoredRegions(ctx, page, story);
 	const plan = await resolvePlan(page, viewport, story);
 	if (plan.viewport.width !== viewport.width || plan.viewport.height !== viewport.height) await page.setViewportSize(plan.viewport);
 	return {
@@ -36,7 +57,7 @@ async function runCapture(page, ctx, inputStory, viewport) {
 	};
 }
 async function navigateAndEnrich(ctx, page, story, viewport) {
-	await page.goto(ctx.adapter.buildUrl(ctx.baseUrl, story.id, viewport.globals), { waitUntil: "networkidle" });
+	await capturePhase("navigation", async () => await page.goto(ctx.adapter.buildUrl(ctx.baseUrl, story.id, viewport.globals), { waitUntil: "networkidle" }));
 	await ctx.adapter.waitForReady?.(page);
 	if (story.parameters) return story;
 	const rpPage = page;
@@ -79,8 +100,8 @@ function logSettle(ctx, story, report) {
 	if (!report.settled && report.hooked) ctx.logger?.warn(detail, "story did not signal that it finished rendering; used a fixed wait");
 	else if (problem !== void 0) ctx.logger?.warn(detail, "story reported an error while rendering");
 }
-async function getA11y(ctx, page) {
-	return ctx.runA11y ? await checkA11y(page, ctx.logger) : [];
+async function getA11y(ctx, page, story) {
+	return ctx.runA11y ? await checkA11y(page, ctx.logger, story.id) : [];
 }
 async function settlePage(page, story) {
 	const burst = story.parameters?.burst ?? 1;
@@ -95,6 +116,38 @@ async function settlePage(page, story) {
 		});
 	} catch {}
 }
+/**
+* Hide the story's ignore regions (`ignoreSelectors` plus the attribute markers) so a changing
+* timestamp or avatar cannot cause a diff. A selector the browser rejects is skipped with a
+* warning on the snapshot log; it never fails the build.
+*/
+async function maskIgnoredRegions(ctx, page, story) {
+	const { selectors: declared, skipped } = cleanIgnoreSelectors(story.parameters?.ignoreSelectors);
+	try {
+		const refused = await page.evaluate((list) => {
+			const doc = globalThis.document;
+			return list.filter((selector) => {
+				try {
+					doc.querySelector(selector);
+					return false;
+				} catch {
+					return true;
+				}
+			});
+		}, declared);
+		const rejected = [...skipped, ...refused];
+		if (rejected.length > 0) ctx.logger?.warn({
+			storyId: story.id,
+			selectors: rejected
+		}, "skipped invalid ignore selectors");
+		await page.addStyleTag({ content: ignoreStylesheet(declared.filter((selector) => !rejected.includes(selector))) });
+	} catch (err) {
+		ctx.logger?.warn({
+			storyId: story.id,
+			err
+		}, "could not mask ignore regions");
+	}
+}
 async function resolvePlan(page, viewport, story) {
 	const box = await page.locator("#storybook-root").boundingBox().catch(() => null);
 	return getScreenshotPlan(viewport, box, {
@@ -116,20 +169,19 @@ async function burstShots(page, plan, story) {
 	}
 	const preferred = shots[Math.floor(shots.length / 2)] ?? shots[0];
 	if (preferred) return preferred;
-	return await page.screenshot({
+	return await capturePhase("screenshot", async () => await page.screenshot({
 		animations: story.parameters?.pauseAnimationAtEnd ? "allow" : "disabled",
 		...plan.fullPage ? { fullPage: true } : {},
 		...plan.clip ? { clip: plan.clip } : {}
-	});
+	}));
 }
 async function shotOne(page, plan, story) {
-	return await page.screenshot({
+	return await capturePhase("screenshot", async () => await page.screenshot({
 		animations: story.parameters?.pauseAnimationAtEnd ? "allow" : "disabled",
 		...plan.fullPage ? { fullPage: true } : {},
 		...plan.clip ? { clip: plan.clip } : {}
-	});
+	}));
 }
-//#endregion
 export { captureScreenshot };
 
 //# sourceMappingURL=screenshot.mjs.map

package/dist/screenshot.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"screenshot.mjs","names":[],"sources":["../src/screenshot.ts"],"sourcesContent":["/** Screenshot pipeline for a single story + viewport. */\n\nimport type { StoryEntry, Viewport } from \"@storyshelf/core/adapter/capture-runner\";\nimport { getScreenshotPlan } from \"@storyshelf/core/capture\";\nimport type { Page } from \"playwright-core\";\nimport { checkA11y } from \"./a11y.ts\";\nimport { acquirePage } from \"./pages.ts\";\nimport { runPlay } from \"./play.ts\";\nimport { runtimeParametersForStory } from \"./runtime-params.ts\";\nimport { awaitPaint, settleTimeoutOf, waitForSettled, type SettleReport } from \"./settle.ts\";\nimport type { CaptureContext, RuntimeParamsPage } from \"./types.ts\";\n\n/** Capture a screenshot for one story/viewport, returning buffer + a11y violations. */\nexport async function captureScreenshot(\n  ctx: CaptureContext,\n  inputStory: StoryEntry,\n  viewport: Viewport,\n): Promise<{ screenshot: Buffer; a11yViolations: string[]; story: StoryEntry }> {\n  const lease = await acquirePage(ctx, viewport);\n  let reusable = false;\n  if (ctx.navigationTimeoutMs) lease.page.setDefaultTimeout(ctx.navigationTimeoutMs);\n  try {\n    const result = await runCapture(lease.page, ctx, inputStory, viewport);\n    reusable = true;\n    return result;\n  } finally {\n    await lease.release(reusable);\n  }\n}\n\nasync function runCapture(\n  page: Page,\n  ctx: CaptureContext,\n  inputStory: StoryEntry,\n  viewport: Viewport,\n): Promise<{ screenshot: Buffer; a11yViolations: string[]; story: StoryEntry }> {\n  const story = await navigateAndEnrich(ctx, page, inputStory, viewport);\n  await waitUntilReady(ctx, page, story);\n  if (ctx.executePlay) await runPlay(page, story.id, ctx.playTimeoutMs ?? 10_000);\n  const a11yViolations = await getA11y(ctx, page);\n  await settlePage(page, story);\n  const plan = await resolvePlan(page, viewport, story);\n  if (plan.viewport.width !== viewport.width || plan.viewport.height !== viewport.height)\n    await page.setViewportSize(plan.viewport);\n  const screenshot = await burstShots(page, plan, story);\n  return { screenshot, a11yViolations, story };\n}\n\nasync function navigateAndEnrich(\n  ctx: CaptureContext,\n  page: Page,\n  story: StoryEntry,\n  viewport: Viewport,\n): Promise<StoryEntry> {\n  await page.goto(ctx.adapter.buildUrl(ctx.baseUrl, story.id, viewport.globals), {\n    waitUntil: \"networkidle\",\n  });\n  await ctx.adapter.waitForReady?.(page);\n  if (story.parameters) return story;\n  const rpPage = page as unknown as RuntimeParamsPage;\n  const params = await runtimeParametersForStory(ctx.runtimeParams, rpPage, story.id);\n  return params ? { ...story, parameters: params } : story;\n}\n/**\n * Wait until the story is ready to be photographed: the selector exists, then Storybook says the\n * render (and its play function) finished, then an explicit `parameters.delay` runs on top. A page\n * that never signals (no channel, or no event before the timeout) gets today's fixed wait instead:\n * `delay ?? 500` ms.\n */\nasync function waitUntilReady(ctx: CaptureContext, page: Page, story: StoryEntry): Promise<void> {\n  if (!ctx.adapter.screenshotSelector) return;\n  await page.waitForSelector(ctx.adapter.screenshotSelector, { state: \"attached\" });\n  const report = await waitForSettled(page, settleTimeoutOf(ctx));\n  if (report.settled) {\n    await awaitPaint(page);\n    if (story.parameters?.delay !== undefined) await page.waitForTimeout(story.parameters.delay);\n  } else {\n    await page.waitForTimeout(story.parameters?.delay ?? 500);\n  }\n  logSettle(ctx, story, report);\n  if (story.parameters?.pauseAnimationAtEnd) {\n    await page.evaluate(() => {\n      const doc = globalThis.document as unknown as {\n        getAnimations: () => { pause: () => void }[];\n      };\n      for (const anim of doc.getAnimations()) anim.pause();\n    });\n  }\n}\n\n/** One line per story that did not render cleanly: where it stopped, and what Storybook said. */\nfunction logSettle(ctx: CaptureContext, story: StoryEntry, report: SettleReport): void {\n  const problem = report.renderError ?? report.playError ?? report.unhandled?.[0];\n  if (report.settled && problem === undefined) return;\n  const detail = { storyId: story.id, phase: report.phase, waitedMs: report.elapsedMs, problem };\n  if (!report.settled && report.hooked) {\n    ctx.logger?.warn(detail, \"story did not signal that it finished rendering; used a fixed wait\");\n  } else if (problem !== undefined) {\n    ctx.logger?.warn(detail, \"story reported an error while rendering\");\n  }\n}\nasync function getA11y(ctx: CaptureContext, page: Page): Promise<string[]> {\n  // checkA11y reports its own failures as an annotation, so it never throws.\n  return ctx.runA11y ? await checkA11y(page, ctx.logger) : [];\n}\nasync function settlePage(page: Page, story: StoryEntry): Promise<void> {\n  const burst = story.parameters?.burst ?? 1;\n  const waitFonts = story.parameters?.waitForFonts ?? burst > 1;\n  if (waitFonts) {\n    try {\n      await page.evaluate(async () => {\n        await (globalThis as unknown as { document: { fonts: { ready: Promise<void> } } }).document\n          .fonts.ready;\n      });\n    } catch {\n      // best-effort\n    }\n  }\n  try {\n    await page.evaluate(() => {\n      for (const vid of (globalThis as unknown as { document: Document }).document.querySelectorAll(\n        \"video\",\n      ))\n        // oxlint-disable-next-line typescript/no-unnecessary-type-assertion -- narrow to HTMLVideoElement\n        (vid as unknown as HTMLVideoElement).pause();\n    });\n  } catch {\n    // best-effort\n  }\n}\nasync function resolvePlan(\n  page: Page,\n  viewport: Viewport,\n  story: StoryEntry,\n): Promise<ReturnType<typeof getScreenshotPlan>> {\n  const box = await page\n    .locator(\"#storybook-root\")\n    .boundingBox()\n    .catch(() => null);\n  return getScreenshotPlan(viewport, box, {\n    autoCrop: story.parameters?.autoCrop,\n    whitespaceThreshold: story.parameters?.autoCropThreshold,\n    fullPageOnOverflow: story.parameters?.fullPageOnOverflow,\n    minWidth: story.parameters?.minWidth,\n    minHeight: story.parameters?.minHeight,\n    maxWidth: story.parameters?.maxWidth,\n    maxHeight: story.parameters?.maxHeight,\n  });\n}\nasync function burstShots(\n  page: Page,\n  plan: ReturnType<typeof getScreenshotPlan>,\n  story: StoryEntry,\n): Promise<Buffer> {\n  const count = Math.max(1, Math.min(5, story.parameters?.burst ?? 1));\n  const shots: Buffer[] = [];\n  for (let i = 0; i < count; i += 1) {\n    if (i > 0) {\n      // oxlint-disable-next-line eslint/no-await-in-loop -- sequential burst\n      await page.waitForTimeout(100);\n    }\n    // oxlint-disable-next-line eslint/no-await-in-loop -- sequential burst\n    shots.push(await shotOne(page, plan, story));\n  }\n  const preferred = shots[Math.floor(shots.length / 2)] ?? shots[0];\n  if (preferred) return preferred;\n  const fallback: unknown = await page.screenshot({\n    animations: story.parameters?.pauseAnimationAtEnd ? \"allow\" : \"disabled\",\n    ...(plan.fullPage ? { fullPage: true } : {}),\n    ...(plan.clip ? { clip: plan.clip } : {}),\n  });\n  // oxlint-disable-next-line typescript/no-unnecessary-type-assertion -- Buffer narrowing\n  return fallback as unknown as Buffer;\n}\nasync function shotOne(\n  page: Page,\n  plan: ReturnType<typeof getScreenshotPlan>,\n  story: StoryEntry,\n): Promise<Buffer> {\n  const shot: unknown = await page.screenshot({\n    animations: story.parameters?.pauseAnimationAtEnd ? \"allow\" : \"disabled\",\n    ...(plan.fullPage ? { fullPage: true } : {}),\n    ...(plan.clip ? { clip: plan.clip } : {}),\n  });\n  // oxlint-disable-next-line typescript/no-unnecessary-type-assertion -- Buffer narrowing\n  return shot as unknown as Buffer;\n}\n"],"mappings":"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"}
+{"version":3,"file":"screenshot.mjs","names":[],"sources":["../src/screenshot.ts"],"sourcesContent":["/** Screenshot pipeline for a single story + viewport. */\n\nimport type { StoryEntry, Viewport } from \"@storyshelf/core/adapter/capture-runner\";\nimport {\n  cleanIgnoreSelectors,\n  getScreenshotPlan,\n  ignoreStylesheet,\n} from \"@storyshelf/core/capture\";\nimport type { Page } from \"playwright-core\";\nimport { checkA11y } from \"./a11y.ts\";\nimport { capturePhase, TransientCaptureError } from \"./capture-retry.ts\";\nimport { acquirePage, type PageLease } from \"./pages.ts\";\nimport { runPlay } from \"./play.ts\";\nimport { runtimeParametersForStory } from \"./runtime-params.ts\";\nimport { awaitPaint, settleTimeoutOf, waitForSettled, type SettleReport } from \"./settle.ts\";\nimport type { CaptureContext, RuntimeParamsPage } from \"./types.ts\";\n\n/** Capture a screenshot for one story/viewport, returning buffer + a11y violations. */\nexport async function captureScreenshot(\n  ctx: CaptureContext,\n  inputStory: StoryEntry,\n  viewport: Viewport,\n  fresh = false,\n): Promise<{ screenshot: Buffer; a11yViolations: string[]; story: StoryEntry }> {\n  const lease = await acquirePage(fresh ? { browser: ctx.browser } : ctx, viewport);\n  return await captureLeased(ctx, inputStory, viewport, lease);\n}\n\nasync function captureLeased(\n  ctx: CaptureContext,\n  inputStory: StoryEntry,\n  viewport: Viewport,\n  lease: PageLease,\n): Promise<{ screenshot: Buffer; a11yViolations: string[]; story: StoryEntry }> {\n  let reusable = false;\n  const crash = watchCrash(lease.page);\n  if (ctx.navigationTimeoutMs) lease.page.setDefaultTimeout(ctx.navigationTimeoutMs);\n  try {\n    const result = await runCapture(lease.page, ctx, inputStory, viewport);\n    reusable = true;\n    return result;\n  } catch (error) {\n    throw crash.classify(error);\n  } finally {\n    crash.dispose();\n    await lease.release(reusable);\n  }\n}\n\nfunction watchCrash(page: Page): { classify(error: unknown): unknown; dispose(): void } {\n  let crashed = false;\n  const onCrash = (): void => {\n    crashed = true;\n  };\n  page.on?.(\"crash\", onCrash);\n  return {\n    classify: (error) => (crashed ? new TransientCaptureError(\"crash\", error) : error),\n    dispose: () => {\n      page.off?.(\"crash\", onCrash);\n    },\n  };\n}\n\nasync function runCapture(\n  page: Page,\n  ctx: CaptureContext,\n  inputStory: StoryEntry,\n  viewport: Viewport,\n): Promise<{ screenshot: Buffer; a11yViolations: string[]; story: StoryEntry }> {\n  const story = await navigateAndEnrich(ctx, page, inputStory, viewport);\n  await waitUntilReady(ctx, page, story);\n  if (ctx.executePlay) await runPlay(page, story.id, ctx.playTimeoutMs ?? 10_000);\n  const a11yViolations = await getA11y(ctx, page, story);\n  await settlePage(page, story);\n  await maskIgnoredRegions(ctx, page, story);\n  const plan = await resolvePlan(page, viewport, story);\n  if (plan.viewport.width !== viewport.width || plan.viewport.height !== viewport.height)\n    await page.setViewportSize(plan.viewport);\n  const screenshot = await burstShots(page, plan, story);\n  return { screenshot, a11yViolations, story };\n}\n\nasync function navigateAndEnrich(\n  ctx: CaptureContext,\n  page: Page,\n  story: StoryEntry,\n  viewport: Viewport,\n): Promise<StoryEntry> {\n  await capturePhase(\n    \"navigation\",\n    async () =>\n      await page.goto(ctx.adapter.buildUrl(ctx.baseUrl, story.id, viewport.globals), {\n        waitUntil: \"networkidle\",\n      }),\n  );\n  await ctx.adapter.waitForReady?.(page);\n  if (story.parameters) return story;\n  const rpPage = page as unknown as RuntimeParamsPage;\n  const params = await runtimeParametersForStory(ctx.runtimeParams, rpPage, story.id);\n  return params ? { ...story, parameters: params } : story;\n}\n/**\n * Wait until the story is ready to be photographed: the selector exists, then Storybook says the\n * render (and its play function) finished, then an explicit `parameters.delay` runs on top. A page\n * that never signals (no channel, or no event before the timeout) gets today's fixed wait instead:\n * `delay ?? 500` ms.\n */\nasync function waitUntilReady(ctx: CaptureContext, page: Page, story: StoryEntry): Promise<void> {\n  if (!ctx.adapter.screenshotSelector) return;\n  await page.waitForSelector(ctx.adapter.screenshotSelector, { state: \"attached\" });\n  const report = await waitForSettled(page, settleTimeoutOf(ctx));\n  if (report.settled) {\n    await awaitPaint(page);\n    if (story.parameters?.delay !== undefined) await page.waitForTimeout(story.parameters.delay);\n  } else {\n    await page.waitForTimeout(story.parameters?.delay ?? 500);\n  }\n  logSettle(ctx, story, report);\n  if (story.parameters?.pauseAnimationAtEnd) {\n    await page.evaluate(() => {\n      const doc = globalThis.document as unknown as {\n        getAnimations: () => { pause: () => void }[];\n      };\n      for (const anim of doc.getAnimations()) anim.pause();\n    });\n  }\n}\n\n/** One line per story that did not render cleanly: where it stopped, and what Storybook said. */\nfunction logSettle(ctx: CaptureContext, story: StoryEntry, report: SettleReport): void {\n  const problem = report.renderError ?? report.playError ?? report.unhandled?.[0];\n  if (report.settled && problem === undefined) return;\n  const detail = { storyId: story.id, phase: report.phase, waitedMs: report.elapsedMs, problem };\n  if (!report.settled && report.hooked) {\n    ctx.logger?.warn(detail, \"story did not signal that it finished rendering; used a fixed wait\");\n  } else if (problem !== undefined) {\n    ctx.logger?.warn(detail, \"story reported an error while rendering\");\n  }\n}\nasync function getA11y(ctx: CaptureContext, page: Page, story: StoryEntry): Promise<string[]> {\n  // checkA11y reports its own failures as an annotation, so it never throws.\n  return ctx.runA11y ? await checkA11y(page, ctx.logger, story.id) : [];\n}\nasync function settlePage(page: Page, story: StoryEntry): Promise<void> {\n  const burst = story.parameters?.burst ?? 1;\n  const waitFonts = story.parameters?.waitForFonts ?? burst > 1;\n  if (waitFonts) {\n    try {\n      await page.evaluate(async () => {\n        await (globalThis as unknown as { document: { fonts: { ready: Promise<void> } } }).document\n          .fonts.ready;\n      });\n    } catch {\n      // best-effort\n    }\n  }\n  try {\n    await page.evaluate(() => {\n      for (const vid of (globalThis as unknown as { document: Document }).document.querySelectorAll(\n        \"video\",\n      ))\n        // oxlint-disable-next-line typescript/no-unnecessary-type-assertion -- narrow to HTMLVideoElement\n        (vid as unknown as HTMLVideoElement).pause();\n    });\n  } catch {\n    // best-effort\n  }\n}\n/**\n * Hide the story's ignore regions (`ignoreSelectors` plus the attribute markers) so a changing\n * timestamp or avatar cannot cause a diff. A selector the browser rejects is skipped with a\n * warning on the snapshot log; it never fails the build.\n */\nasync function maskIgnoredRegions(\n  ctx: CaptureContext,\n  page: Page,\n  story: StoryEntry,\n): Promise<void> {\n  const { selectors: declared, skipped } = cleanIgnoreSelectors(story.parameters?.ignoreSelectors);\n  try {\n    const refused = await page.evaluate((list: string[]) => {\n      const doc = (globalThis as unknown as { document: { querySelector(s: string): unknown } })\n        .document;\n      return list.filter((selector) => {\n        try {\n          doc.querySelector(selector);\n          return false;\n        } catch {\n          return true;\n        }\n      });\n    }, declared);\n    const rejected = [...skipped, ...refused];\n    if (rejected.length > 0)\n      ctx.logger?.warn(\n        { storyId: story.id, selectors: rejected },\n        \"skipped invalid ignore selectors\",\n      );\n    await page.addStyleTag({\n      content: ignoreStylesheet(declared.filter((selector) => !rejected.includes(selector))),\n    });\n  } catch (err) {\n    ctx.logger?.warn({ storyId: story.id, err }, \"could not mask ignore regions\");\n  }\n}\nasync function resolvePlan(\n  page: Page,\n  viewport: Viewport,\n  story: StoryEntry,\n): Promise<ReturnType<typeof getScreenshotPlan>> {\n  const box = await page\n    .locator(\"#storybook-root\")\n    .boundingBox()\n    .catch(() => null);\n  return getScreenshotPlan(viewport, box, {\n    autoCrop: story.parameters?.autoCrop,\n    whitespaceThreshold: story.parameters?.autoCropThreshold,\n    fullPageOnOverflow: story.parameters?.fullPageOnOverflow,\n    minWidth: story.parameters?.minWidth,\n    minHeight: story.parameters?.minHeight,\n    maxWidth: story.parameters?.maxWidth,\n    maxHeight: story.parameters?.maxHeight,\n  });\n}\nasync function burstShots(\n  page: Page,\n  plan: ReturnType<typeof getScreenshotPlan>,\n  story: StoryEntry,\n): Promise<Buffer> {\n  const count = Math.max(1, Math.min(5, story.parameters?.burst ?? 1));\n  const shots: Buffer[] = [];\n  for (let i = 0; i < count; i += 1) {\n    if (i > 0) {\n      // oxlint-disable-next-line eslint/no-await-in-loop -- sequential burst\n      await page.waitForTimeout(100);\n    }\n    // oxlint-disable-next-line eslint/no-await-in-loop -- sequential burst\n    shots.push(await shotOne(page, plan, story));\n  }\n  const preferred = shots[Math.floor(shots.length / 2)] ?? shots[0];\n  if (preferred) return preferred;\n  const fallback: unknown = await capturePhase(\n    \"screenshot\",\n    async () =>\n      await page.screenshot({\n        animations: story.parameters?.pauseAnimationAtEnd ? \"allow\" : \"disabled\",\n        ...(plan.fullPage ? { fullPage: true } : {}),\n        ...(plan.clip ? { clip: plan.clip } : {}),\n      }),\n  );\n  // oxlint-disable-next-line typescript/no-unnecessary-type-assertion -- Buffer narrowing\n  return fallback as unknown as Buffer;\n}\nasync function shotOne(\n  page: Page,\n  plan: ReturnType<typeof getScreenshotPlan>,\n  story: StoryEntry,\n): Promise<Buffer> {\n  const shot: unknown = await capturePhase(\n    \"screenshot\",\n    async () =>\n      await page.screenshot({\n        animations: story.parameters?.pauseAnimationAtEnd ? \"allow\" : \"disabled\",\n        ...(plan.fullPage ? { fullPage: true } : {}),\n        ...(plan.clip ? { clip: plan.clip } : {}),\n      }),\n  );\n  // oxlint-disable-next-line typescript/no-unnecessary-type-assertion -- Buffer narrowing\n  return shot as unknown as Buffer;\n}\n"],"mappings":"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"}

package/dist/settle.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/settle.ts
+// src/settle.ts
 /** How long to wait for the event when nothing else says (the play timeout raises it). */
 const DEFAULT_SETTLE_TIMEOUT_MS = 5e3;
 /** The wait for the event: the context's override, else the play timeout when plays run, else 5 s. */
@@ -14,9 +14,12 @@ async function installSettleRecorder(page) {
 	await page.addInitScript(inPageRecorder);
 }
 /** Wait until Storybook says the story is done (or `timeoutMs` passes); never throws. */
-async function waitForSettled(page, timeoutMs) {
+async function waitForSettled(page, timeoutMs, requireFinished = false) {
 	try {
-		const report = await page.evaluate(inPageWaitSettled, { timeoutMs });
+		const report = await page.evaluate(inPageWaitSettled, {
+			timeoutMs,
+			...requireFinished ? { requireFinished } : {}
+		});
 		return isSettleReport(report) ? report : unsettled(false);
 	} catch {
 		return unsettled(false);
@@ -48,6 +51,7 @@ function inPageRecorder() {
 	const state = {
 		hooked: false,
 		settled: false,
+		finished: false,
 		phase: null,
 		unhandled: [],
 		hook: () => false
@@ -71,7 +75,11 @@ function inPageRecorder() {
 			if (typeof phase === "string") state.phase = phase;
 		},
 		storyRendered: markSettled,
-		storyFinished: markSettled,
+		storyFinished: (payload) => {
+			if (payload?.status === "error" && state["playError"] === void 0) state["playError"] = "Storybook reported that the test failed";
+			state.finished = true;
+			markSettled();
+		},
 		storyThrewException: failRender,
 		storyErrored: failRender,
 		storyMissing: failRender,
@@ -101,7 +109,7 @@ function inPageRecorder() {
 * Runs in the browser: resolves when the recorder saw a terminal event, the page has no channel
 * to listen to, or `timeoutMs` passed. Self-contained for the same reason as the recorder.
 */
-async function inPageWaitSettled({ timeoutMs }) {
+async function inPageWaitSettled({ timeoutMs, requireFinished }) {
 	const state = globalThis["__STORYSHELF_SETTLE__"];
 	const started = performance.now();
 	const report = (settled, hooked) => ({
@@ -116,12 +124,12 @@ async function inPageWaitSettled({ timeoutMs }) {
 	if (!state) return report(false, false);
 	if (!state.hook() && globalThis.document?.readyState === "complete") return report(false, false);
 	while (performance.now() - started < timeoutMs) {
-		if (state.settled) return report(true, true);
+		if (state.settled && (!requireFinished || state.finished || state.renderError !== void 0)) return report(true, true);
 		await new Promise((resolve) => {
 			setTimeout(resolve, 10);
 		});
 	}
-	return report(state.settled, state.hook());
+	return report(state.settled && (!requireFinished || state.finished || state.renderError !== void 0), state.hook());
 }
 /** After the signal: let web fonts finish and two frames paint, so the screenshot sees the final DOM. */
 async function awaitPaint(page) {
@@ -144,7 +152,6 @@ async function inPagePaint() {
 	});
 	await Promise.race([Promise.all([scope.document.fonts?.ready, frames]), cap]);
 }
-//#endregion
 export { DEFAULT_SETTLE_TIMEOUT_MS, awaitPaint, inPagePaint, inPageRecorder, inPageWaitSettled, installSettleRecorder, settleTimeoutOf, unsettled, waitForSettled };
 
 //# sourceMappingURL=settle.mjs.map

package/dist/settle.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"settle.mjs","names":[],"sources":["../src/settle.ts"],"sourcesContent":["/** Render-settled signalling: wait for Storybook's own \"render finished\" event, not a clock. */\n\nimport type { Page } from \"playwright-core\";\n\n/** What the page knew when the wait ended (all of it from Storybook's public channel events). */\nexport interface SettleReport {\n  /** Storybook announced the story rendered, finished, errored or missing before the timeout. */\n  settled: boolean;\n  /** The preview's channel was found, so events could have arrived at all. */\n  hooked: boolean;\n  /** The last `storyRenderPhaseChanged` phase seen (`playing`, `errored`, `completed` ...). */\n  phase: string | null;\n  /** Milliseconds the wait took. */\n  elapsedMs: number;\n  /** The story failed to render (`storyThrewException`, `storyErrored`, `storyMissing`). */\n  renderError?: string;\n  /** The play function (or a `.test()` body) threw (`playFunctionThrewException`). */\n  playError?: string;\n  /** Errors Storybook reported after the play function (`unhandledErrorsWhilePlaying`). */\n  unhandled?: string[];\n}\n\n/** How long to wait for the event when nothing else says (the play timeout raises it). */\nexport const DEFAULT_SETTLE_TIMEOUT_MS = 5000;\n\n/** The wait for the event: the context's override, else the play timeout when plays run, else 5 s. */\nexport function settleTimeoutOf(ctx: {\n  settleTimeoutMs?: number | undefined;\n  executePlay?: boolean | undefined;\n  playTimeoutMs?: number | undefined;\n}): number {\n  if (ctx.settleTimeoutMs !== undefined) return ctx.settleTimeoutMs;\n  return ctx.executePlay\n    ? Math.max(DEFAULT_SETTLE_TIMEOUT_MS, ctx.playTimeoutMs ?? 0)\n    : DEFAULT_SETTLE_TIMEOUT_MS;\n}\n\n/** Register the recorder on a page, once; it runs before the page's own scripts on every load. */\nexport async function installSettleRecorder(page: Page): Promise<void> {\n  await page.addInitScript(inPageRecorder);\n}\n\n/** Wait until Storybook says the story is done (or `timeoutMs` passes); never throws. */\nexport async function waitForSettled(page: Page, timeoutMs: number): Promise<SettleReport> {\n  try {\n    const report: unknown = await page.evaluate(inPageWaitSettled, { timeoutMs });\n    return isSettleReport(report) ? report : unsettled(false);\n  } catch {\n    return unsettled(false);\n  }\n}\n\n/** A report for a wait that saw no signal. */\nexport function unsettled(hooked: boolean): SettleReport {\n  return { settled: false, hooked, phase: null, elapsedMs: 0 };\n}\n\nfunction isSettleReport(value: unknown): value is SettleReport {\n  if (typeof value !== \"object\" || value === null) return false;\n  const record = value as Record<string, unknown>;\n  return typeof record[\"settled\"] === \"boolean\" && typeof record[\"hooked\"] === \"boolean\";\n}\n\n/**\n * Runs in the browser before the page's scripts, on every document. It watches the preview's\n * channel (`__STORYBOOK_ADDONS_CHANNEL__`, the public `Channel.on` API; nothing is patched) and\n * records the events StoryShelf needs. Playwright serializes only this function's source, so it\n * must not reference anything from this module; `settle.test.ts` evaluates it without bindings.\n */\n// oxlint-disable-next-line eslint/max-statements, eslint/max-lines-per-function -- must stay one self-contained function (see above)\nexport function inPageRecorder(): void {\n  type Channel = { on: (event: string, cb: (payload: unknown) => void) => void };\n  type State = Record<string, unknown> & {\n    hooked: boolean;\n    settled: boolean;\n    phase: string | null;\n    unhandled: string[];\n    hook: () => boolean;\n  };\n  const scope = globalThis as unknown as Record<string, unknown>;\n  if (scope[\"__STORYSHELF_SETTLE__\"]) return;\n  const state: State = {\n    hooked: false,\n    settled: false,\n    phase: null,\n    unhandled: [],\n    hook: () => false,\n  };\n  const text = {\n    of(payload: unknown): string {\n      if (typeof payload === \"string\") return payload;\n      const record = (payload ?? {}) as Record<string, unknown>;\n      const found = record[\"message\"] ?? record[\"description\"] ?? record[\"title\"];\n      return typeof found === \"string\" ? found : \"unknown error\";\n    },\n  };\n  const markSettled = (): void => {\n    state.settled = true;\n  };\n  const failRender = (payload: unknown): void => {\n    state[\"renderError\"] = text.of(payload);\n    markSettled();\n  };\n  const handlers: Record<string, (payload: unknown) => void> = {\n    storyRenderPhaseChanged: (payload) => {\n      const phase = (payload as { newPhase?: unknown } | undefined)?.newPhase;\n      if (typeof phase === \"string\") state.phase = phase;\n    },\n    storyRendered: markSettled,\n    storyFinished: markSettled,\n    storyThrewException: failRender,\n    storyErrored: failRender,\n    storyMissing: failRender,\n    playFunctionThrewException: (payload) => {\n      state[\"playError\"] = text.of(payload);\n    },\n    unhandledErrorsWhilePlaying: (payload) => {\n      for (const error of Array.isArray(payload) ? payload : [payload]) {\n        state.unhandled.push(text.of(error));\n      }\n    },\n  };\n  state.hook = (): boolean => {\n    if (state.hooked) return true;\n    const found = (scope[\"__STORYBOOK_ADDONS_CHANNEL__\"] ??\n      (scope[\"__STORYBOOK_PREVIEW__\"] as { channel?: unknown } | undefined)?.channel) as\n      | Channel\n      | undefined;\n    if (!found || typeof found.on !== \"function\") return false;\n    for (const [event, handler] of Object.entries(handlers)) found.on(event, handler);\n    state.hooked = true;\n    return true;\n  };\n  scope[\"__STORYSHELF_SETTLE__\"] = state;\n  // The channel is created by iframe.html's bundle, before the first story renders: catch it\n  // within a few ms. Give up after a while (a page that is not Storybook never gets one).\n  if (state.hook()) return;\n  const started = Date.now();\n  const timer = setInterval(() => {\n    if (state.hook() || Date.now() - started > 30_000) clearInterval(timer);\n  }, 2);\n}\n\n/** Arguments serialized into the page for {@link inPageWaitSettled}. */\nexport interface SettleArgs {\n  timeoutMs: number;\n}\n\n/**\n * Runs in the browser: resolves when the recorder saw a terminal event, the page has no channel\n * to listen to, or `timeoutMs` passed. Self-contained for the same reason as the recorder.\n */\n// oxlint-disable-next-line eslint/max-statements, eslint/max-lines-per-function -- must stay one self-contained function (see above)\nexport async function inPageWaitSettled({ timeoutMs }: SettleArgs): Promise<SettleReport> {\n  type State = {\n    hooked: boolean;\n    settled: boolean;\n    phase: string | null;\n    unhandled: string[];\n    hook: () => boolean;\n    renderError?: string;\n    playError?: string;\n  };\n  const state = (globalThis as unknown as Record<string, State | undefined>)[\n    \"__STORYSHELF_SETTLE__\"\n  ];\n  const started = performance.now();\n  const report = (settled: boolean, hooked: boolean): SettleReport => ({\n    settled,\n    hooked,\n    phase: state?.phase ?? null,\n    elapsedMs: Math.round(performance.now() - started),\n    ...(state?.renderError === undefined ? {} : { renderError: state.renderError }),\n    ...(state?.playError === undefined ? {} : { playError: state.playError }),\n    ...(state && state.unhandled.length > 0 ? { unhandled: [...state.unhandled] } : {}),\n  });\n  if (!state) return report(false, false);\n  // After `load` every script has run: no channel by now means there will never be one.\n  if (!state.hook() && globalThis.document?.readyState === \"complete\") return report(false, false);\n  while (performance.now() - started < timeoutMs) {\n    if (state.settled) return report(true, true);\n    // oxlint-disable-next-line eslint/no-await-in-loop -- polling the recorded state\n    await new Promise<void>((resolve) => {\n      setTimeout(resolve, 10);\n    });\n  }\n  return report(state.settled, state.hook());\n}\n\n/** After the signal: let web fonts finish and two frames paint, so the screenshot sees the final DOM. */\nexport async function awaitPaint(page: Page): Promise<void> {\n  try {\n    await page.evaluate(inPagePaint);\n  } catch {\n    // best-effort: the screenshot still follows\n  }\n}\n\n/** Runs in the browser; bounded so a page that never paints (hidden tab) cannot hang the capture. */\nexport async function inPagePaint(): Promise<void> {\n  const scope = globalThis as unknown as {\n    document: { fonts?: { ready: Promise<unknown> } };\n    requestAnimationFrame: (cb: () => void) => void;\n  };\n  const frames = new Promise<void>((resolve) => {\n    scope.requestAnimationFrame(() => {\n      scope.requestAnimationFrame(() => {\n        resolve();\n      });\n    });\n  });\n  const cap = new Promise<void>((resolve) => {\n    setTimeout(resolve, 250);\n  });\n  await Promise.race([Promise.all([scope.document.fonts?.ready, frames]), cap]);\n}\n"],"mappings":";;;;;AAuBA,MAAa,4BAA4B;;AAGzC,SAAgB,gBAAgB,KAIrB;CACT,IAAI,IAAI,oBAAoB,KAAA,GAAW,OAAO,IAAI;CAClD,OAAO,IAAI,cACP,KAAK,IAAI,2BAA2B,IAAI,iBAAiB,CAAC,IAC1D;AACN;;AAGA,eAAsB,sBAAsB,MAA2B;CACrE,MAAM,KAAK,cAAc,cAAc;AACzC;;AAGA,eAAsB,eAAe,MAAY,WAA0C;CACzF,IAAI;EACF,MAAM,SAAkB,MAAM,KAAK,SAAS,mBAAmB,EAAE,UAAU,CAAC;EAC5E,OAAO,eAAe,MAAM,IAAI,SAAS,UAAU,KAAK;CAC1D,QAAQ;EACN,OAAO,UAAU,KAAK;CACxB;AACF;;AAGA,SAAgB,UAAU,QAA+B;CACvD,OAAO;EAAE,SAAS;EAAO;EAAQ,OAAO;EAAM,WAAW;CAAE;AAC7D;AAEA,SAAS,eAAe,OAAuC;CAC7D,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CACxD,MAAM,SAAS;CACf,OAAO,OAAO,OAAO,eAAe,aAAa,OAAO,OAAO,cAAc;AAC/E;;;;;;;AASA,SAAgB,iBAAuB;CASrC,MAAM,QAAQ;CACd,IAAI,MAAM,0BAA0B;CACpC,MAAM,QAAe;EACnB,QAAQ;EACR,SAAS;EACT,OAAO;EACP,WAAW,CAAC;EACZ,YAAY;CACd;CACA,MAAM,OAAO,EACX,GAAG,SAA0B;EAC3B,IAAI,OAAO,YAAY,UAAU,OAAO;EACxC,MAAM,SAAU,WAAW,CAAC;EAC5B,MAAM,QAAQ,OAAO,cAAc,OAAO,kBAAkB,OAAO;EACnE,OAAO,OAAO,UAAU,WAAW,QAAQ;CAC7C,EACF;CACA,MAAM,oBAA0B;EAC9B,MAAM,UAAU;CAClB;CACA,MAAM,cAAc,YAA2B;EAC7C,MAAM,iBAAiB,KAAK,GAAG,OAAO;EACtC,YAAY;CACd;CACA,MAAM,WAAuD;EAC3D,0BAA0B,YAAY;GACpC,MAAM,QAAS,SAAgD;GAC/D,IAAI,OAAO,UAAU,UAAU,MAAM,QAAQ;EAC/C;EACA,eAAe;EACf,eAAe;EACf,qBAAqB;EACrB,cAAc;EACd,cAAc;EACd,6BAA6B,YAAY;GACvC,MAAM,eAAe,KAAK,GAAG,OAAO;EACtC;EACA,8BAA8B,YAAY;GACxC,KAAK,MAAM,SAAS,MAAM,QAAQ,OAAO,IAAI,UAAU,CAAC,OAAO,GAC7D,MAAM,UAAU,KAAK,KAAK,GAAG,KAAK,CAAC;EAEvC;CACF;CACA,MAAM,aAAsB;EAC1B,IAAI,MAAM,QAAQ,OAAO;EACzB,MAAM,QAAS,MAAM,mCAClB,MAAM,wBAAwB,EAAwC;EAGzE,IAAI,CAAC,SAAS,OAAO,MAAM,OAAO,YAAY,OAAO;EACrD,KAAK,MAAM,CAAC,OAAO,YAAY,OAAO,QAAQ,QAAQ,GAAG,MAAM,GAAG,OAAO,OAAO;EAChF,MAAM,SAAS;EACf,OAAO;CACT;CACA,MAAM,2BAA2B;CAGjC,IAAI,MAAM,KAAK,GAAG;CAClB,MAAM,UAAU,KAAK,IAAI;CACzB,MAAM,QAAQ,kBAAkB;EAC9B,IAAI,MAAM,KAAK,KAAK,KAAK,IAAI,IAAI,UAAU,KAAQ,cAAc,KAAK;CACxE,GAAG,CAAC;AACN;;;;;AAYA,eAAsB,kBAAkB,EAAE,aAAgD;CAUxF,MAAM,QAAS,WACb;CAEF,MAAM,UAAU,YAAY,IAAI;CAChC,MAAM,UAAU,SAAkB,YAAmC;EACnE;EACA;EACA,OAAO,OAAO,SAAS;EACvB,WAAW,KAAK,MAAM,YAAY,IAAI,IAAI,OAAO;EACjD,GAAI,OAAO,gBAAgB,KAAA,IAAY,CAAC,IAAI,EAAE,aAAa,MAAM,YAAY;EAC7E,GAAI,OAAO,cAAc,KAAA,IAAY,CAAC,IAAI,EAAE,WAAW,MAAM,UAAU;EACvE,GAAI,SAAS,MAAM,UAAU,SAAS,IAAI,EAAE,WAAW,CAAC,GAAG,MAAM,SAAS,EAAE,IAAI,CAAC;CACnF;CACA,IAAI,CAAC,OAAO,OAAO,OAAO,OAAO,KAAK;CAEtC,IAAI,CAAC,MAAM,KAAK,KAAK,WAAW,UAAU,eAAe,YAAY,OAAO,OAAO,OAAO,KAAK;CAC/F,OAAO,YAAY,IAAI,IAAI,UAAU,WAAW;EAC9C,IAAI,MAAM,SAAS,OAAO,OAAO,MAAM,IAAI;EAE3C,MAAM,IAAI,SAAe,YAAY;GACnC,WAAW,SAAS,EAAE;EACxB,CAAC;CACH;CACA,OAAO,OAAO,MAAM,SAAS,MAAM,KAAK,CAAC;AAC3C;;AAGA,eAAsB,WAAW,MAA2B;CAC1D,IAAI;EACF,MAAM,KAAK,SAAS,WAAW;CACjC,QAAQ,CAER;AACF;;AAGA,eAAsB,cAA6B;CACjD,MAAM,QAAQ;CAId,MAAM,SAAS,IAAI,SAAe,YAAY;EAC5C,MAAM,4BAA4B;GAChC,MAAM,4BAA4B;IAChC,QAAQ;GACV,CAAC;EACH,CAAC;CACH,CAAC;CACD,MAAM,MAAM,IAAI,SAAe,YAAY;EACzC,WAAW,SAAS,GAAG;CACzB,CAAC;CACD,MAAM,QAAQ,KAAK,CAAC,QAAQ,IAAI,CAAC,MAAM,SAAS,OAAO,OAAO,MAAM,CAAC,GAAG,GAAG,CAAC;AAC9E"}
+{"version":3,"file":"settle.mjs","names":[],"sources":["../src/settle.ts"],"sourcesContent":["/** Render-settled signalling: wait for Storybook's own \"render finished\" event, not a clock. */\n\nimport type { Page } from \"playwright-core\";\n\n/** What the page knew when the wait ended (all of it from Storybook's public channel events). */\nexport interface SettleReport {\n  /** Storybook announced the story rendered, finished, errored or missing before the timeout. */\n  settled: boolean;\n  /** The preview's channel was found, so events could have arrived at all. */\n  hooked: boolean;\n  /** The last `storyRenderPhaseChanged` phase seen (`playing`, `errored`, `completed` ...). */\n  phase: string | null;\n  /** Milliseconds the wait took. */\n  elapsedMs: number;\n  /** The story failed to render (`storyThrewException`, `storyErrored`, `storyMissing`). */\n  renderError?: string;\n  /** The play function (or a `.test()` body) threw (`playFunctionThrewException`). */\n  playError?: string;\n  /** Errors Storybook reported after the play function (`unhandledErrorsWhilePlaying`). */\n  unhandled?: string[];\n}\n\n/** How long to wait for the event when nothing else says (the play timeout raises it). */\nexport const DEFAULT_SETTLE_TIMEOUT_MS = 5000;\n\n/** The wait for the event: the context's override, else the play timeout when plays run, else 5 s. */\nexport function settleTimeoutOf(ctx: {\n  settleTimeoutMs?: number | undefined;\n  executePlay?: boolean | undefined;\n  playTimeoutMs?: number | undefined;\n}): number {\n  if (ctx.settleTimeoutMs !== undefined) return ctx.settleTimeoutMs;\n  return ctx.executePlay\n    ? Math.max(DEFAULT_SETTLE_TIMEOUT_MS, ctx.playTimeoutMs ?? 0)\n    : DEFAULT_SETTLE_TIMEOUT_MS;\n}\n\n/** Register the recorder on a page, once; it runs before the page's own scripts on every load. */\nexport async function installSettleRecorder(page: Page): Promise<void> {\n  await page.addInitScript(inPageRecorder);\n}\n\n/** Wait until Storybook says the story is done (or `timeoutMs` passes); never throws. */\nexport async function waitForSettled(\n  page: Page,\n  timeoutMs: number,\n  requireFinished = false,\n): Promise<SettleReport> {\n  try {\n    const report: unknown = await page.evaluate(inPageWaitSettled, {\n      timeoutMs,\n      ...(requireFinished ? { requireFinished } : {}),\n    });\n    return isSettleReport(report) ? report : unsettled(false);\n  } catch {\n    return unsettled(false);\n  }\n}\n\n/** A report for a wait that saw no signal. */\nexport function unsettled(hooked: boolean): SettleReport {\n  return { settled: false, hooked, phase: null, elapsedMs: 0 };\n}\n\nfunction isSettleReport(value: unknown): value is SettleReport {\n  if (typeof value !== \"object\" || value === null) return false;\n  const record = value as Record<string, unknown>;\n  return typeof record[\"settled\"] === \"boolean\" && typeof record[\"hooked\"] === \"boolean\";\n}\n\n/**\n * Runs in the browser before the page's scripts, on every document. It watches the preview's\n * channel (`__STORYBOOK_ADDONS_CHANNEL__`, the public `Channel.on` API; nothing is patched) and\n * records the events StoryShelf needs. Playwright serializes only this function's source, so it\n * must not reference anything from this module; `settle.test.ts` evaluates it without bindings.\n */\n// oxlint-disable-next-line eslint/max-statements, eslint/max-lines-per-function -- must stay one self-contained function (see above)\nexport function inPageRecorder(): void {\n  type Channel = { on: (event: string, cb: (payload: unknown) => void) => void };\n  type State = Record<string, unknown> & {\n    hooked: boolean;\n    settled: boolean;\n    finished: boolean;\n    phase: string | null;\n    unhandled: string[];\n    hook: () => boolean;\n  };\n  const scope = globalThis as unknown as Record<string, unknown>;\n  if (scope[\"__STORYSHELF_SETTLE__\"]) return;\n  const state: State = {\n    hooked: false,\n    settled: false,\n    finished: false,\n    phase: null,\n    unhandled: [],\n    hook: () => false,\n  };\n  const text = {\n    of(payload: unknown): string {\n      if (typeof payload === \"string\") return payload;\n      const record = (payload ?? {}) as Record<string, unknown>;\n      const found = record[\"message\"] ?? record[\"description\"] ?? record[\"title\"];\n      return typeof found === \"string\" ? found : \"unknown error\";\n    },\n  };\n  const markSettled = (): void => {\n    state.settled = true;\n  };\n  const failRender = (payload: unknown): void => {\n    state[\"renderError\"] = text.of(payload);\n    markSettled();\n  };\n  const handlers: Record<string, (payload: unknown) => void> = {\n    storyRenderPhaseChanged: (payload) => {\n      const phase = (payload as { newPhase?: unknown } | undefined)?.newPhase;\n      if (typeof phase === \"string\") state.phase = phase;\n    },\n    storyRendered: markSettled,\n    storyFinished: (payload) => {\n      const status = (payload as { status?: unknown } | undefined)?.status;\n      if (status === \"error\" && state[\"playError\"] === undefined) {\n        state[\"playError\"] = \"Storybook reported that the test failed\";\n      }\n      state.finished = true;\n      markSettled();\n    },\n    storyThrewException: failRender,\n    storyErrored: failRender,\n    storyMissing: failRender,\n    playFunctionThrewException: (payload) => {\n      state[\"playError\"] = text.of(payload);\n    },\n    unhandledErrorsWhilePlaying: (payload) => {\n      for (const error of Array.isArray(payload) ? payload : [payload]) {\n        state.unhandled.push(text.of(error));\n      }\n    },\n  };\n  state.hook = (): boolean => {\n    if (state.hooked) return true;\n    const found = (scope[\"__STORYBOOK_ADDONS_CHANNEL__\"] ??\n      (scope[\"__STORYBOOK_PREVIEW__\"] as { channel?: unknown } | undefined)?.channel) as\n      | Channel\n      | undefined;\n    if (!found || typeof found.on !== \"function\") return false;\n    for (const [event, handler] of Object.entries(handlers)) found.on(event, handler);\n    state.hooked = true;\n    return true;\n  };\n  scope[\"__STORYSHELF_SETTLE__\"] = state;\n  // The channel is created by iframe.html's bundle, before the first story renders: catch it\n  // within a few ms. Give up after a while (a page that is not Storybook never gets one).\n  if (state.hook()) return;\n  const started = Date.now();\n  const timer = setInterval(() => {\n    if (state.hook() || Date.now() - started > 30_000) clearInterval(timer);\n  }, 2);\n}\n\n/** Arguments serialized into the page for {@link inPageWaitSettled}. */\nexport interface SettleArgs {\n  timeoutMs: number;\n  requireFinished?: boolean;\n}\n\n/**\n * Runs in the browser: resolves when the recorder saw a terminal event, the page has no channel\n * to listen to, or `timeoutMs` passed. Self-contained for the same reason as the recorder.\n */\n// oxlint-disable-next-line eslint/max-statements, eslint/max-lines-per-function -- must stay one self-contained function (see above)\nexport async function inPageWaitSettled({\n  timeoutMs,\n  requireFinished,\n}: SettleArgs): Promise<SettleReport> {\n  type State = {\n    hooked: boolean;\n    settled: boolean;\n    finished: boolean;\n    phase: string | null;\n    unhandled: string[];\n    hook: () => boolean;\n    renderError?: string;\n    playError?: string;\n  };\n  const state = (globalThis as unknown as Record<string, State | undefined>)[\n    \"__STORYSHELF_SETTLE__\"\n  ];\n  const started = performance.now();\n  const report = (settled: boolean, hooked: boolean): SettleReport => ({\n    settled,\n    hooked,\n    phase: state?.phase ?? null,\n    elapsedMs: Math.round(performance.now() - started),\n    ...(state?.renderError === undefined ? {} : { renderError: state.renderError }),\n    ...(state?.playError === undefined ? {} : { playError: state.playError }),\n    ...(state && state.unhandled.length > 0 ? { unhandled: [...state.unhandled] } : {}),\n  });\n  if (!state) return report(false, false);\n  // After `load` every script has run: no channel by now means there will never be one.\n  if (!state.hook() && globalThis.document?.readyState === \"complete\") return report(false, false);\n  while (performance.now() - started < timeoutMs) {\n    if (state.settled && (!requireFinished || state.finished || state.renderError !== undefined)) {\n      return report(true, true);\n    }\n    // oxlint-disable-next-line eslint/no-await-in-loop -- polling the recorded state\n    await new Promise<void>((resolve) => {\n      setTimeout(resolve, 10);\n    });\n  }\n  return report(\n    state.settled && (!requireFinished || state.finished || state.renderError !== undefined),\n    state.hook(),\n  );\n}\n\n/** After the signal: let web fonts finish and two frames paint, so the screenshot sees the final DOM. */\nexport async function awaitPaint(page: Page): Promise<void> {\n  try {\n    await page.evaluate(inPagePaint);\n  } catch {\n    // best-effort: the screenshot still follows\n  }\n}\n\n/** Runs in the browser; bounded so a page that never paints (hidden tab) cannot hang the capture. */\nexport async function inPagePaint(): Promise<void> {\n  const scope = globalThis as unknown as {\n    document: { fonts?: { ready: Promise<unknown> } };\n    requestAnimationFrame: (cb: () => void) => void;\n  };\n  const frames = new Promise<void>((resolve) => {\n    scope.requestAnimationFrame(() => {\n      scope.requestAnimationFrame(() => {\n        resolve();\n      });\n    });\n  });\n  const cap = new Promise<void>((resolve) => {\n    setTimeout(resolve, 250);\n  });\n  await Promise.race([Promise.all([scope.document.fonts?.ready, frames]), cap]);\n}\n"],"mappings":"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"}

package/dist/static-server.mjs

@@ -1,24 +1,30 @@
-import "node:path";
+import { join, normalize } from "node:path";
 import "node:url";
 import.meta.url;
 import { isPathSafe, mimeFor } from "@storyshelf/core/utils";
 import { createReadStream } from "node:fs";
-import { join, normalize } from "node:path";
-import { stat } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { createServer } from "node:http";
-//#region src/static-server.ts
+import { promisify } from "node:util";
+import { gzip } from "node:zlib";
+// src/static-server.ts
+const compress = promisify(gzip);
+const MAX_COMPRESS_FILE = 524288;
+const MAX_COMPRESS_CACHE = 4194304;
+const MAX_UNCOMPRESSIBLE_FILES = 128;
 /**
 * Serve a built Storybook directory over HTTP on 127.0.0.1 for capture.
 *
 * @param rootDir - Directory containing the built Storybook (`index.html` entry).
 * @returns The server URL and a `close` function to stop it.
 */
-async function createStaticServer(rootDir) {
+async function createStaticServer(rootDir, options = {}) {
 	const root = normalize(rootDir);
 	const info = await stat(root).catch(() => null);
 	if (!info || !info.isDirectory()) throw new Error(`Storybook directory not found: ${rootDir}. Upload the built Storybook before capturing.`);
+	const cache = new CompressionCache();
 	const server = createServer((req, res) => {
-		handleRequest(root, req.url ?? "/", res).catch(() => {
+		handleRequest(root, req, res, options.compression === true ? cache : void 0).catch(() => {
 			sendNotFound(res);
 		});
 	});
@@ -42,15 +48,72 @@ async function resolveFile(root, urlPath) {
 	if (info.isDirectory()) return resolveFile(root, `${clean}/index.html`);
 	return info.isFile() ? target : null;
 }
-async function handleRequest(root, url, res) {
-	const file = await resolveFile(root, url);
+async function handleRequest(root, req, res, cache) {
+	const file = await resolveFile(root, req.url ?? "/");
 	if (!file) {
 		sendNotFound(res);
 		return;
 	}
-	res.writeHead(200, { "content-type": mimeFor(file) });
+	const zipped = cache && acceptsGzip(req.headers["accept-encoding"]) && isCompressible(mimeFor(file)) ? await cache.get(file) : void 0;
+	res.writeHead(200, {
+		"content-type": mimeFor(file),
+		"cache-control": "public, max-age=3600",
+		...cache ? { vary: "Accept-Encoding" } : {},
+		...zipped ? {
+			"content-encoding": "gzip",
+			"content-length": zipped.length
+		} : {}
+	});
+	if (zipped) {
+		res.end(zipped);
+		return;
+	}
 	createReadStream(file).pipe(res);
 }
+function acceptsGzip(header) {
+	if (!header) return false;
+	const values = header.split(",").map((part) => part.trim().split(";"));
+	const entry = values.find(([name]) => name?.trim().toLowerCase() === "gzip") ?? values.find(([name]) => name?.trim() === "*");
+	if (!entry) return false;
+	const quality = entry.slice(1).find((part) => /^\s*q\s*=/iu.test(part));
+	if (quality === void 0) return true;
+	const value = Number(quality.split("=")[1]);
+	return Number.isFinite(value) && value > 0 && value <= 1;
+}
+function isCompressible(mime) {
+	return /^(?:text\/|application\/(?:javascript|json|xml|wasm)|image\/svg\+xml)/iu.test(mime);
+}
+/** Budget reservations include in-flight reads so concurrent requests stay bounded. */
+var CompressionCache = class {
+	entries = /* @__PURE__ */ new Map();
+	uncompressible = /* @__PURE__ */ new Set();
+	reserved = 0;
+	async get(file) {
+		if (this.uncompressible.has(file)) return void 0;
+		const existing = this.entries.get(file);
+		if (existing) return await existing;
+		return await this.reserve(file, (await stat(file)).size);
+	}
+	async reserve(file, size) {
+		if (this.uncompressible.has(file)) return void 0;
+		const pending = this.entries.get(file);
+		if (pending) return await pending;
+		if (size > MAX_COMPRESS_FILE || this.reserved + size > MAX_COMPRESS_CACHE) return void 0;
+		this.reserved += size;
+		const result = this.encode(file, size);
+		this.entries.set(file, result);
+		return await result;
+	}
+	async encode(file, size) {
+		try {
+			const compressed = await compress(await readFile(file));
+			if (compressed.length < size) return compressed;
+			if (this.uncompressible.size < MAX_UNCOMPRESSIBLE_FILES) this.uncompressible.add(file);
+		} catch {}
+		this.reserved -= size;
+		this.entries.delete(file);
+	}
+};
 async function listen(server) {
 	return await new Promise((resolve, reject) => {
 		server.once("error", reject);
@@ -68,7 +131,6 @@ async function closeServer(server) {
 		});
 	});
 }
-//#endregion
 export { createStaticServer };
 
 //# sourceMappingURL=static-server.mjs.map