@storyshelf/runner-playwright 0.6.1 → 0.7.0

package/dist/remote/index.mjs

@@ -0,0 +1,8 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { remote } from "./remote.mjs";
+import { playwrightServer } from "./playwright-server.mjs";
+import { azurePlaywright } from "./azure.mjs";
+import { browserstack } from "./browserstack.mjs";
+export { azurePlaywright, browserstack, playwrightServer, remote };

package/dist/remote/playwright-server.d.mts

@@ -0,0 +1,40 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { BrowserName, RemoteBrowser } from "@storyshelf/core/adapter/capture-runner";
+//#region src/remote/playwright-server.d.ts
+/** Options of {@link playwrightServer}. */
+interface PlaywrightServerOptions {
+  /** The target name half (`chromium@<name>`); default `grid`. */
+  name?: string;
+  /** `ws://host:3000/` or `wss://…`: the server's address and `--path`. */
+  endpoint: string;
+  /**
+   * Bearer token for a reverse proxy in front of the server: a bare `run-server` has no
+   * authentication of its own. Sent as `authorization: Bearer …`.
+   */
+  token?: string;
+  /** Further handshake headers. */
+  headers?: Record<string, string>;
+  /**
+   * Route the remote browser's requests for the loopback Storybook server back through the
+   * connection (default `"<loopback>"`). `false` when the server cannot, which makes every target
+   * need a signed Storybook URL.
+   */
+  exposeNetwork?: string | false;
+  /** Parallel pages the farm should take from this runner (default 1: set it to the farm's cap). */
+  sessions?: number;
+  /** Engines to offer (default all three; the server must have them installed). */
+  engines?: readonly BrowserName[];
+  /** OS the server runs on, reported when the page cannot tell. */
+  platform?: string;
+  /**
+   * How long one connect attempt waits in ms (default 30 000). A server started with
+   * `--max-clients` queues extra connections: raise this when renders outnumber its clients.
+   */
+  connectTimeoutMs?: number;
+}
+/** Targets on a Playwright server: `chromium@grid`, `firefox@grid`, `webkit@grid`. */
+declare function playwrightServer(options: PlaywrightServerOptions): RemoteBrowser;
+//#endregion
+export { PlaywrightServerOptions, playwrightServer };
+//# sourceMappingURL=playwright-server.d.mts.map

package/dist/remote/playwright-server.mjs

@@ -0,0 +1,34 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { remote } from "./remote.mjs";
+//#region src/remote/playwright-server.ts
+/** Targets on a Playwright server: `chromium@grid`, `firefox@grid`, `webkit@grid`. */
+function playwrightServer(options) {
+	const headers = {
+		...options.token === void 0 ? {} : { authorization: `Bearer ${options.token}` },
+		...options.headers
+	};
+	const exposeNetwork = options.exposeNetwork ?? "<loopback>";
+	return remote({
+		name: options.name ?? "grid",
+		engines: options.engines ?? [
+			"chromium",
+			"firefox",
+			"webkit"
+		],
+		connect: () => ({
+			protocol: "playwright",
+			endpoint: options.endpoint,
+			headers,
+			...exposeNetwork === false ? {} : { exposeNetwork }
+		}),
+		sessions: options.sessions ?? 1,
+		platform: options.platform,
+		connectTimeoutMs: options.connectTimeoutMs
+	});
+}
+//#endregion
+export { playwrightServer };
+
+//# sourceMappingURL=playwright-server.mjs.map

package/dist/remote/playwright-server.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-server.mjs","names":[],"sources":["../../src/remote/playwright-server.ts"],"sourcesContent":["/** A self-hosted Playwright server (`playwright run-server`), or anything speaking its protocol. */\nimport type { BrowserName, RemoteBrowser } from \"@storyshelf/core/adapter/capture-runner\";\nimport { remote } from \"./remote.ts\";\n\n/** Options of {@link playwrightServer}. */\nexport interface PlaywrightServerOptions {\n  /** The target name half (`chromium@<name>`); default `grid`. */\n  name?: string;\n  /** `ws://host:3000/` or `wss://…`: the server's address and `--path`. */\n  endpoint: string;\n  /**\n   * Bearer token for a reverse proxy in front of the server: a bare `run-server` has no\n   * authentication of its own. Sent as `authorization: Bearer …`.\n   */\n  token?: string;\n  /** Further handshake headers. */\n  headers?: Record<string, string>;\n  /**\n   * Route the remote browser's requests for the loopback Storybook server back through the\n   * connection (default `\"<loopback>\"`). `false` when the server cannot, which makes every target\n   * need a signed Storybook URL.\n   */\n  exposeNetwork?: string | false;\n  /** Parallel pages the farm should take from this runner (default 1: set it to the farm's cap). */\n  sessions?: number;\n  /** Engines to offer (default all three; the server must have them installed). */\n  engines?: readonly BrowserName[];\n  /** OS the server runs on, reported when the page cannot tell. */\n  platform?: string;\n  /**\n   * How long one connect attempt waits in ms (default 30 000). A server started with\n   * `--max-clients` queues extra connections: raise this when renders outnumber its clients.\n   */\n  connectTimeoutMs?: number;\n}\n\n/** Targets on a Playwright server: `chromium@grid`, `firefox@grid`, `webkit@grid`. */\nexport function playwrightServer(options: PlaywrightServerOptions): RemoteBrowser {\n  const headers = {\n    ...(options.token === undefined ? {} : { authorization: `Bearer ${options.token}` }),\n    ...options.headers,\n  };\n  const exposeNetwork = options.exposeNetwork ?? \"<loopback>\";\n  return remote({\n    name: options.name ?? \"grid\",\n    engines: options.engines ?? [\"chromium\", \"firefox\", \"webkit\"],\n    connect: () => ({\n      protocol: \"playwright\",\n      endpoint: options.endpoint,\n      headers,\n      ...(exposeNetwork === false ? {} : { exposeNetwork }),\n    }),\n    sessions: options.sessions ?? 1,\n    platform: options.platform,\n    connectTimeoutMs: options.connectTimeoutMs,\n  });\n}\n"],"mappings":";;;;;;AAqCA,SAAgB,iBAAiB,SAAiD;CAChF,MAAM,UAAU;EACd,GAAI,QAAQ,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,eAAe,UAAU,QAAQ,QAAQ;EAClF,GAAG,QAAQ;CACb;CACA,MAAM,gBAAgB,QAAQ,iBAAiB;CAC/C,OAAO,OAAO;EACZ,MAAM,QAAQ,QAAQ;EACtB,SAAS,QAAQ,WAAW;GAAC;GAAY;GAAW;EAAQ;EAC5D,gBAAgB;GACd,UAAU;GACV,UAAU,QAAQ;GAClB;GACA,GAAI,kBAAkB,QAAQ,CAAC,IAAI,EAAE,cAAc;EACrD;EACA,UAAU,QAAQ,YAAY;EAC9B,UAAU,QAAQ;EAClB,kBAAkB,QAAQ;CAC5B,CAAC;AACH"}

package/dist/remote/remote.d.mts

@@ -0,0 +1,22 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { BrowserName as BrowserName$1, RemoteBrowser as RemoteBrowser$1, RemoteConnection, RemoteOptions } from "@storyshelf/core/adapter/capture-runner";
+//#region src/remote/remote.d.ts
+/**
+ * A browser service the runner connects to instead of launching, for `browsers`. It offers one
+ * target per engine, `<engine>@<name>`, each with its own baselines (ADR 0007, decision 3), and
+ * throws when the runner is created for a bad name, engine, protocol or endpoint.
+ *
+ * ```ts
+ * remote({
+ *   name: "mygrid",
+ *   engines: ["chromium", "firefox", "webkit"],
+ *   connect: () => ({ protocol: "playwright", endpoint: "wss://grid.example/", exposeNetwork: "<loopback>" }),
+ *   sessions: 4,
+ * });
+ * ```
+ */
+declare function remote(options: RemoteOptions): RemoteBrowser$1;
+//#endregion
+export { type BrowserName$1 as BrowserName, type RemoteBrowser$1 as RemoteBrowser, type RemoteConnection, type RemoteOptions, remote };
+//# sourceMappingURL=remote.d.mts.map

package/dist/remote/remote.mjs

@@ -0,0 +1,38 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { defineRemote } from "@storyshelf/core/adapter/capture-runner";
+//#region 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 = {
+	engines: [
+		"chromium",
+		"firefox",
+		"webkit",
+		"chrome"
+	],
+	protocols: ["playwright", "cdp"],
+	label: "remote()"
+};
+/**
+* A browser service the runner connects to instead of launching, for `browsers`. It offers one
+* target per engine, `<engine>@<name>`, each with its own baselines (ADR 0007, decision 3), and
+* throws when the runner is created for a bad name, engine, protocol or endpoint.
+*
+* ```ts
+* remote({
+*   name: "mygrid",
+*   engines: ["chromium", "firefox", "webkit"],
+*   connect: () => ({ protocol: "playwright", endpoint: "wss://grid.example/", exposeNetwork: "<loopback>" }),
+*   sessions: 4,
+* });
+* ```
+*/
+function remote(options) {
+	return defineRemote(options, SUPPORT);
+}
+//#endregion
+export { remote };
+
+//# sourceMappingURL=remote.mjs.map

package/dist/remote/remote.mjs.map

@@ -0,0 +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"}

package/dist/remote-environment.mjs

@@ -0,0 +1,36 @@
+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
+/**
+* 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.
+*/
+async function measureRemote(browser, remote, logger) {
+	return remoteEnvironment({
+		browserVersion: typeof browser.version === "function" ? browser.version() : void 0,
+		probe: await probeBlankPage(browser, logger),
+		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();
+		}
+	} catch (error) {
+		logger?.warn({ reason: messageOf(error) }, "could not measure the remote browser");
+		return;
+	}
+}
+//#endregion
+export { measureRemote };
+
+//# sourceMappingURL=remote-environment.mjs.map

package/dist/remote-environment.mjs.map

@@ -0,0 +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"}

package/dist/runtime-params.mjs

@@ -15,6 +15,13 @@ function createRuntimeParamsState() {
 async function runtimeParametersForStory(state, page, storyId) {
 	return (state.extractFailed ? void 0 : await extractedParametersMap(state, page))?.get(storyId);
 }
+/** Read every story's resolved parameters from a loaded preview page in one call. */
+async function extractAllParameters(page) {
+	const raw = await readExtractedParameters(page);
+	const out = /* @__PURE__ */ new Map();
+	if (raw) fillParamsMap(out, raw);
+	return Object.fromEntries(out);
+}
 async function extractedParametersMap(state, page) {
 	state.extractPromise ??= loadExtractedParametersMap(state, page);
 	return await state.extractPromise;
@@ -55,6 +62,6 @@ function hasEntries(map) {
 	return Boolean(map && Object.keys(map).length > 0);
 }
 //#endregion
-export { createRuntimeParamsState, runtimeParametersForStory };
+export { createRuntimeParamsState, extractAllParameters, runtimeParametersForStory };
 
 //# sourceMappingURL=runtime-params.mjs.map

package/dist/runtime-params.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-params.mjs","names":["win"],"sources":["../src/runtime-params.ts"],"sourcesContent":["/** Per-run runtime-parameter extraction cache (ADR 0017). */\n\nimport { mergeParameters } from \"@storyshelf/core/capture\";\nimport type { StoryParameters } from \"@storyshelf/core/capture\";\nimport type { ExtractedEntry, RuntimeParamsPage, RuntimeParamsState } from \"./types.ts\";\n\n/** Create the per-run runtime-parameter cache shared across captures. */\nexport function createRuntimeParamsState(): RuntimeParamsState {\n  return {};\n}\n\n/**\n * Read story parameters from the running preview via\n * `__STORYBOOK_PREVIEW__.extract()`, once per run and lazily.\n */\nexport async function runtimeParametersForStory(\n  state: RuntimeParamsState,\n  page: RuntimeParamsPage,\n  storyId: string,\n): Promise<StoryParameters | undefined> {\n  const map = state.extractFailed ? undefined : await extractedParametersMap(state, page);\n  return map?.get(storyId);\n}\n\nasync function extractedParametersMap(\n  state: RuntimeParamsState,\n  page: RuntimeParamsPage,\n): Promise<Map<string, StoryParameters>> {\n  state.extractPromise ??= loadExtractedParametersMap(state, page);\n  return await state.extractPromise;\n}\n\nasync function loadExtractedParametersMap(\n  state: RuntimeParamsState,\n  page: RuntimeParamsPage,\n): Promise<Map<string, StoryParameters>> {\n  const raw = await safeReadExtracted(state, page);\n  return buildParamsMap(state, raw);\n}\n\nasync function safeReadExtracted(\n  state: RuntimeParamsState,\n  page: RuntimeParamsPage,\n): Promise<Record<string, ExtractedEntry> | null> {\n  try {\n    return await readExtractedParameters(page);\n  } catch {\n    state.extractFailed = true;\n    return null;\n  }\n}\n\nfunction buildParamsMap(\n  state: RuntimeParamsState,\n  raw: Record<string, ExtractedEntry> | null,\n): Map<string, StoryParameters> {\n  const out = new Map<string, StoryParameters>();\n  if (raw) fillParamsMap(out, raw);\n  if (out.size === 0) state.extractFailed = true;\n  return out;\n}\n\nfunction fillParamsMap(\n  out: Map<string, StoryParameters>,\n  raw: Record<string, ExtractedEntry>,\n): void {\n  for (const [id, entry] of Object.entries(raw)) {\n    const merged = mergeParameters(entry);\n    if (merged) out.set(id, merged);\n  }\n}\n\nasync function readExtractedParameters(\n  page: RuntimeParamsPage,\n): Promise<Record<string, ExtractedEntry> | null> {\n  const map = (await page.evaluate(() => {\n    const win = globalThis as unknown as {\n      __STORYBOOK_PREVIEW__?: { extract?: () => unknown };\n    };\n    // oxlint-disable-next-line typescript/dot-notation -- __STORYBOOK_PREVIEW__ is a Storybook global\n    const preview = win[\"__STORYBOOK_PREVIEW__\"];\n    if (!preview || typeof preview.extract !== \"function\") return null;\n    const extracted = preview.extract();\n    return extracted && typeof extracted === \"object\"\n      ? (extracted as Record<string, ExtractedEntry>)\n      : null;\n  })) as Record<string, ExtractedEntry> | null;\n  return hasEntries(map) ? map : null;\n}\n\nfunction hasEntries(map: Record<string, ExtractedEntry> | null): boolean {\n  return Boolean(map && Object.keys(map).length > 0);\n}\n"],"mappings":";;;;;;;AAOA,SAAgB,2BAA+C;CAC7D,OAAO,CAAC;AACV;;;;;AAMA,eAAsB,0BACpB,OACA,MACA,SACsC;CAEtC,QADY,MAAM,gBAAgB,KAAA,IAAY,MAAM,uBAAuB,OAAO,IAAI,EAAA,EAC1E,IAAI,OAAO;AACzB;AAEA,eAAe,uBACb,OACA,MACuC;CACvC,MAAM,mBAAmB,2BAA2B,OAAO,IAAI;CAC/D,OAAO,MAAM,MAAM;AACrB;AAEA,eAAe,2BACb,OACA,MACuC;CAEvC,OAAO,eAAe,OAAO,MADX,kBAAkB,OAAO,IAAI,CACf;AAClC;AAEA,eAAe,kBACb,OACA,MACgD;CAChD,IAAI;EACF,OAAO,MAAM,wBAAwB,IAAI;CAC3C,QAAQ;EACN,MAAM,gBAAgB;EACtB,OAAO;CACT;AACF;AAEA,SAAS,eACP,OACA,KAC8B;CAC9B,MAAM,sBAAM,IAAI,IAA6B;CAC7C,IAAI,KAAK,cAAc,KAAK,GAAG;CAC/B,IAAI,IAAI,SAAS,GAAG,MAAM,gBAAgB;CAC1C,OAAO;AACT;AAEA,SAAS,cACP,KACA,KACM;CACN,KAAK,MAAM,CAAC,IAAI,UAAU,OAAO,QAAQ,GAAG,GAAG;EAC7C,MAAM,SAAS,gBAAgB,KAAK;EACpC,IAAI,QAAQ,IAAI,IAAI,IAAI,MAAM;CAChC;AACF;AAEA,eAAe,wBACb,MACgD;CAChD,MAAM,MAAO,MAAM,KAAK,eAAe;EAKrC,MAAM,UAAUA,WAAI;EACpB,IAAI,CAAC,WAAW,OAAO,QAAQ,YAAY,YAAY,OAAO;EAC9D,MAAM,YAAY,QAAQ,QAAQ;EAClC,OAAO,aAAa,OAAO,cAAc,WACpC,YACD;CACN,CAAC;CACD,OAAO,WAAW,GAAG,IAAI,MAAM;AACjC;AAEA,SAAS,WAAW,KAAqD;CACvE,OAAO,QAAQ,OAAO,OAAO,KAAK,GAAG,CAAC,CAAC,SAAS,CAAC;AACnD"}
+{"version":3,"file":"runtime-params.mjs","names":["win"],"sources":["../src/runtime-params.ts"],"sourcesContent":["/** Per-run runtime-parameter extraction cache (ADR 0017). */\n\nimport { mergeParameters } from \"@storyshelf/core/capture\";\nimport type { StoryParameters } from \"@storyshelf/core/capture\";\nimport type { ExtractedEntry, RuntimeParamsPage, RuntimeParamsState } from \"./types.ts\";\n\n/** Create the per-run runtime-parameter cache shared across captures. */\nexport function createRuntimeParamsState(): RuntimeParamsState {\n  return {};\n}\n\n/**\n * Read story parameters from the running preview via\n * `__STORYBOOK_PREVIEW__.extract()`, once per run and lazily.\n */\nexport async function runtimeParametersForStory(\n  state: RuntimeParamsState,\n  page: RuntimeParamsPage,\n  storyId: string,\n): Promise<StoryParameters | undefined> {\n  const map = state.extractFailed ? undefined : await extractedParametersMap(state, page);\n  return map?.get(storyId);\n}\n\n/** Read every story's resolved parameters from a loaded preview page in one call. */\nexport async function extractAllParameters(\n  page: RuntimeParamsPage,\n): Promise<Record<string, StoryParameters>> {\n  const raw = await readExtractedParameters(page);\n  const out = new Map<string, StoryParameters>();\n  if (raw) fillParamsMap(out, raw);\n  return Object.fromEntries(out);\n}\n\nasync function extractedParametersMap(\n  state: RuntimeParamsState,\n  page: RuntimeParamsPage,\n): Promise<Map<string, StoryParameters>> {\n  state.extractPromise ??= loadExtractedParametersMap(state, page);\n  return await state.extractPromise;\n}\n\nasync function loadExtractedParametersMap(\n  state: RuntimeParamsState,\n  page: RuntimeParamsPage,\n): Promise<Map<string, StoryParameters>> {\n  const raw = await safeReadExtracted(state, page);\n  return buildParamsMap(state, raw);\n}\n\nasync function safeReadExtracted(\n  state: RuntimeParamsState,\n  page: RuntimeParamsPage,\n): Promise<Record<string, ExtractedEntry> | null> {\n  try {\n    return await readExtractedParameters(page);\n  } catch {\n    state.extractFailed = true;\n    return null;\n  }\n}\n\nfunction buildParamsMap(\n  state: RuntimeParamsState,\n  raw: Record<string, ExtractedEntry> | null,\n): Map<string, StoryParameters> {\n  const out = new Map<string, StoryParameters>();\n  if (raw) fillParamsMap(out, raw);\n  if (out.size === 0) state.extractFailed = true;\n  return out;\n}\n\nfunction fillParamsMap(\n  out: Map<string, StoryParameters>,\n  raw: Record<string, ExtractedEntry>,\n): void {\n  for (const [id, entry] of Object.entries(raw)) {\n    const merged = mergeParameters(entry);\n    if (merged) out.set(id, merged);\n  }\n}\n\nasync function readExtractedParameters(\n  page: RuntimeParamsPage,\n): Promise<Record<string, ExtractedEntry> | null> {\n  const map = (await page.evaluate(() => {\n    const win = globalThis as unknown as {\n      __STORYBOOK_PREVIEW__?: { extract?: () => unknown };\n    };\n    // oxlint-disable-next-line typescript/dot-notation -- __STORYBOOK_PREVIEW__ is a Storybook global\n    const preview = win[\"__STORYBOOK_PREVIEW__\"];\n    if (!preview || typeof preview.extract !== \"function\") return null;\n    const extracted = preview.extract();\n    return extracted && typeof extracted === \"object\"\n      ? (extracted as Record<string, ExtractedEntry>)\n      : null;\n  })) as Record<string, ExtractedEntry> | null;\n  return hasEntries(map) ? map : null;\n}\n\nfunction hasEntries(map: Record<string, ExtractedEntry> | null): boolean {\n  return Boolean(map && Object.keys(map).length > 0);\n}\n"],"mappings":";;;;;;;AAOA,SAAgB,2BAA+C;CAC7D,OAAO,CAAC;AACV;;;;;AAMA,eAAsB,0BACpB,OACA,MACA,SACsC;CAEtC,QADY,MAAM,gBAAgB,KAAA,IAAY,MAAM,uBAAuB,OAAO,IAAI,EAAA,EAC1E,IAAI,OAAO;AACzB;;AAGA,eAAsB,qBACpB,MAC0C;CAC1C,MAAM,MAAM,MAAM,wBAAwB,IAAI;CAC9C,MAAM,sBAAM,IAAI,IAA6B;CAC7C,IAAI,KAAK,cAAc,KAAK,GAAG;CAC/B,OAAO,OAAO,YAAY,GAAG;AAC/B;AAEA,eAAe,uBACb,OACA,MACuC;CACvC,MAAM,mBAAmB,2BAA2B,OAAO,IAAI;CAC/D,OAAO,MAAM,MAAM;AACrB;AAEA,eAAe,2BACb,OACA,MACuC;CAEvC,OAAO,eAAe,OAAO,MADX,kBAAkB,OAAO,IAAI,CACf;AAClC;AAEA,eAAe,kBACb,OACA,MACgD;CAChD,IAAI;EACF,OAAO,MAAM,wBAAwB,IAAI;CAC3C,QAAQ;EACN,MAAM,gBAAgB;EACtB,OAAO;CACT;AACF;AAEA,SAAS,eACP,OACA,KAC8B;CAC9B,MAAM,sBAAM,IAAI,IAA6B;CAC7C,IAAI,KAAK,cAAc,KAAK,GAAG;CAC/B,IAAI,IAAI,SAAS,GAAG,MAAM,gBAAgB;CAC1C,OAAO;AACT;AAEA,SAAS,cACP,KACA,KACM;CACN,KAAK,MAAM,CAAC,IAAI,UAAU,OAAO,QAAQ,GAAG,GAAG;EAC7C,MAAM,SAAS,gBAAgB,KAAK;EACpC,IAAI,QAAQ,IAAI,IAAI,IAAI,MAAM;CAChC;AACF;AAEA,eAAe,wBACb,MACgD;CAChD,MAAM,MAAO,MAAM,KAAK,eAAe;EAKrC,MAAM,UAAUA,WAAI;EACpB,IAAI,CAAC,WAAW,OAAO,QAAQ,YAAY,YAAY,OAAO;EAC9D,MAAM,YAAY,QAAQ,QAAQ;EAClC,OAAO,aAAa,OAAO,cAAc,WACpC,YACD;CACN,CAAC;CACD,OAAO,WAAW,GAAG,IAAI,MAAM;AACjC;AAEA,SAAS,WAAW,KAAqD;CACvE,OAAO,QAAQ,OAAO,OAAO,KAAK,GAAG,CAAC,CAAC,SAAS,CAAC;AACnD"}

package/dist/screenshot.mjs

@@ -1,6 +1,8 @@
 import "node:path";
 import "node:url";
 import.meta.url;
+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";
@@ -8,19 +10,20 @@ import { getScreenshotPlan } from "@storyshelf/core/capture";
 //#region src/screenshot.ts
 /** Capture a screenshot for one story/viewport, returning buffer + a11y violations. */
 async function captureScreenshot(ctx, inputStory, viewport) {
-	const page = await ctx.browser.newPage({ viewport: {
-		width: viewport.width,
-		height: viewport.height
-	} });
+	const lease = await acquirePage(ctx, viewport);
+	let reusable = false;
+	if (ctx.navigationTimeoutMs) lease.page.setDefaultTimeout(ctx.navigationTimeoutMs);
 	try {
-		return await runCapture(page, ctx, inputStory, viewport);
+		const result = await runCapture(lease.page, ctx, inputStory, viewport);
+		reusable = true;
+		return result;
 	} finally {
-		await page.close();
+		await lease.release(reusable);
 	}
 }
 async function runCapture(page, ctx, inputStory, viewport) {
-	const story = await navigateAndEnrich(ctx, page, inputStory);
-	await maybeWaitForSelector(ctx, page, story);
+	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);
 	await settlePage(page, story);
@@ -32,8 +35,8 @@ async function runCapture(page, ctx, inputStory, viewport) {
 		story
 	};
 }
-async function navigateAndEnrich(ctx, page, story) {
-	await page.goto(ctx.adapter.buildUrl(ctx.baseUrl, story.id), { waitUntil: "networkidle" });
+async function navigateAndEnrich(ctx, page, story, viewport) {
+	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;
@@ -43,22 +46,41 @@ async function navigateAndEnrich(ctx, page, story) {
 		parameters: params
 	} : story;
 }
-async function maybeWaitForSelector(ctx, page, story) {
+/**
+* Wait until the story is ready to be photographed: the selector exists, then Storybook says the
+* render (and its play function) finished, then an explicit `parameters.delay` runs on top. A page
+* that never signals (no channel, or no event before the timeout) gets today's fixed wait instead:
+* `delay ?? 500` ms.
+*/
+async function waitUntilReady(ctx, page, story) {
 	if (!ctx.adapter.screenshotSelector) return;
 	await page.waitForSelector(ctx.adapter.screenshotSelector, { state: "attached" });
-	await page.waitForTimeout(story.parameters?.delay ?? 500);
+	const report = await waitForSettled(page, settleTimeoutOf(ctx));
+	if (report.settled) {
+		await awaitPaint(page);
+		if (story.parameters?.delay !== void 0) await page.waitForTimeout(story.parameters.delay);
+	} else await page.waitForTimeout(story.parameters?.delay ?? 500);
+	logSettle(ctx, story, report);
 	if (story.parameters?.pauseAnimationAtEnd) await page.evaluate(() => {
 		const doc = globalThis.document;
 		for (const anim of doc.getAnimations()) anim.pause();
 	});
 }
+/** One line per story that did not render cleanly: where it stopped, and what Storybook said. */
+function logSettle(ctx, story, report) {
+	const problem = report.renderError ?? report.playError ?? report.unhandled?.[0];
+	if (report.settled && problem === void 0) return;
+	const detail = {
+		storyId: story.id,
+		phase: report.phase,
+		waitedMs: report.elapsedMs,
+		problem
+	};
+	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) {
-	if (!ctx.runA11y) return [];
-	try {
-		return await checkA11y(page);
-	} catch {
-		return [];
-	}
+	return ctx.runA11y ? await checkA11y(page, ctx.logger) : [];
 }
 async function settlePage(page, story) {
 	const burst = story.parameters?.burst ?? 1;

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 { runPlay } from \"./play.ts\";\nimport { runtimeParametersForStory } from \"./runtime-params.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 page = await ctx.browser.newPage({\n    viewport: { width: viewport.width, height: viewport.height },\n  });\n  try {\n    return await runCapture(page, ctx, inputStory, viewport);\n  } finally {\n    await page.close();\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);\n  await maybeWaitForSelector(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): Promise<StoryEntry> {\n  await page.goto(ctx.adapter.buildUrl(ctx.baseUrl, story.id), { waitUntil: \"networkidle\" });\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}\nasync function maybeWaitForSelector(\n  ctx: CaptureContext,\n  page: Page,\n  story: StoryEntry,\n): Promise<void> {\n  if (!ctx.adapter.screenshotSelector) return;\n  await page.waitForSelector(ctx.adapter.screenshotSelector, { state: \"attached\" });\n  await page.waitForTimeout(story.parameters?.delay ?? 500);\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}\nasync function getA11y(ctx: CaptureContext, page: Page): Promise<string[]> {\n  if (!ctx.runA11y) return [];\n  try {\n    return await checkA11y(page);\n  } catch {\n    return [];\n  }\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":";;;;;;;;;AAWA,eAAsB,kBACpB,KACA,YACA,UAC8E;CAC9E,MAAM,OAAO,MAAM,IAAI,QAAQ,QAAQ,EACrC,UAAU;EAAE,OAAO,SAAS;EAAO,QAAQ,SAAS;CAAO,EAC7D,CAAC;CACD,IAAI;EACF,OAAO,MAAM,WAAW,MAAM,KAAK,YAAY,QAAQ;CACzD,UAAU;EACR,MAAM,KAAK,MAAM;CACnB;AACF;AAEA,eAAe,WACb,MACA,KACA,YACA,UAC8E;CAC9E,MAAM,QAAQ,MAAM,kBAAkB,KAAK,MAAM,UAAU;CAC3D,MAAM,qBAAqB,KAAK,MAAM,KAAK;CAC3C,IAAI,IAAI,aAAa,MAAM,QAAQ,MAAM,MAAM,IAAI,IAAI,iBAAiB,GAAM;CAC9E,MAAM,iBAAiB,MAAM,QAAQ,KAAK,IAAI;CAC9C,MAAM,WAAW,MAAM,KAAK;CAC5B,MAAM,OAAO,MAAM,YAAY,MAAM,UAAU,KAAK;CACpD,IAAI,KAAK,SAAS,UAAU,SAAS,SAAS,KAAK,SAAS,WAAW,SAAS,QAC9E,MAAM,KAAK,gBAAgB,KAAK,QAAQ;CAE1C,OAAO;EAAE,YAAA,MADgB,WAAW,MAAM,MAAM,KAAK;EAChC;EAAgB;CAAM;AAC7C;AAEA,eAAe,kBACb,KACA,MACA,OACqB;CACrB,MAAM,KAAK,KAAK,IAAI,QAAQ,SAAS,IAAI,SAAS,MAAM,EAAE,GAAG,EAAE,WAAW,cAAc,CAAC;CACzF,MAAM,IAAI,QAAQ,eAAe,IAAI;CACrC,IAAI,MAAM,YAAY,OAAO;CAC7B,MAAM,SAAS;CACf,MAAM,SAAS,MAAM,0BAA0B,IAAI,eAAe,QAAQ,MAAM,EAAE;CAClF,OAAO,SAAS;EAAE,GAAG;EAAO,YAAY;CAAO,IAAI;AACrD;AACA,eAAe,qBACb,KACA,MACA,OACe;CACf,IAAI,CAAC,IAAI,QAAQ,oBAAoB;CACrC,MAAM,KAAK,gBAAgB,IAAI,QAAQ,oBAAoB,EAAE,OAAO,WAAW,CAAC;CAChF,MAAM,KAAK,eAAe,MAAM,YAAY,SAAS,GAAG;CACxD,IAAI,MAAM,YAAY,qBACpB,MAAM,KAAK,eAAe;EACxB,MAAM,MAAM,WAAW;EAGvB,KAAK,MAAM,QAAQ,IAAI,cAAc,GAAG,KAAK,MAAM;CACrD,CAAC;AAEL;AACA,eAAe,QAAQ,KAAqB,MAA+B;CACzE,IAAI,CAAC,IAAI,SAAS,OAAO,CAAC;CAC1B,IAAI;EACF,OAAO,MAAM,UAAU,IAAI;CAC7B,QAAQ;EACN,OAAO,CAAC;CACV;AACF;AACA,eAAe,WAAW,MAAY,OAAkC;CACtE,MAAM,QAAQ,MAAM,YAAY,SAAS;CAEzC,IADkB,MAAM,YAAY,gBAAgB,QAAQ,GAE1D,IAAI;EACF,MAAM,KAAK,SAAS,YAAY;GAC9B,MAAO,WAA4E,SAChF,MAAM;EACX,CAAC;CACH,QAAQ,CAER;CAEF,IAAI;EACF,MAAM,KAAK,eAAe;GACxB,KAAK,MAAM,OAAQ,WAAiD,SAAS,iBAC3E,OACF,GAEE,IAAqC,MAAM;EAC/C,CAAC;CACH,QAAQ,CAER;AACF;AACA,eAAe,YACb,MACA,UACA,OAC+C;CAC/C,MAAM,MAAM,MAAM,KACf,QAAQ,iBAAiB,CAAC,CAC1B,YAAY,CAAC,CACb,YAAY,IAAI;CACnB,OAAO,kBAAkB,UAAU,KAAK;EACtC,UAAU,MAAM,YAAY;EAC5B,qBAAqB,MAAM,YAAY;EACvC,oBAAoB,MAAM,YAAY;EACtC,UAAU,MAAM,YAAY;EAC5B,WAAW,MAAM,YAAY;EAC7B,UAAU,MAAM,YAAY;EAC5B,WAAW,MAAM,YAAY;CAC/B,CAAC;AACH;AACA,eAAe,WACb,MACA,MACA,OACiB;CACjB,MAAM,QAAQ,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,MAAM,YAAY,SAAS,CAAC,CAAC;CACnE,MAAM,QAAkB,CAAC;CACzB,KAAK,IAAI,IAAI,GAAG,IAAI,OAAO,KAAK,GAAG;EACjC,IAAI,IAAI,GAEN,MAAM,KAAK,eAAe,GAAG;EAG/B,MAAM,KAAK,MAAM,QAAQ,MAAM,MAAM,KAAK,CAAC;CAC7C;CACA,MAAM,YAAY,MAAM,KAAK,MAAM,MAAM,SAAS,CAAC,MAAM,MAAM;CAC/D,IAAI,WAAW,OAAO;CAOtB,OAAO,MANyB,KAAK,WAAW;EAC9C,YAAY,MAAM,YAAY,sBAAsB,UAAU;EAC9D,GAAI,KAAK,WAAW,EAAE,UAAU,KAAK,IAAI,CAAC;EAC1C,GAAI,KAAK,OAAO,EAAE,MAAM,KAAK,KAAK,IAAI,CAAC;CACzC,CAAC;AAGH;AACA,eAAe,QACb,MACA,MACA,OACiB;CAOjB,OAAO,MANqB,KAAK,WAAW;EAC1C,YAAY,MAAM,YAAY,sBAAsB,UAAU;EAC9D,GAAI,KAAK,WAAW,EAAE,UAAU,KAAK,IAAI,CAAC;EAC1C,GAAI,KAAK,OAAO,EAAE,MAAM,KAAK,KAAK,IAAI,CAAC;CACzC,CAAC;AAGH"}
+{"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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"}

package/dist/settle.mjs

@@ -0,0 +1,150 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region 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. */
+function settleTimeoutOf(ctx) {
+	if (ctx.settleTimeoutMs !== void 0) return ctx.settleTimeoutMs;
+	return ctx.executePlay ? Math.max(DEFAULT_SETTLE_TIMEOUT_MS, ctx.playTimeoutMs ?? 0) : DEFAULT_SETTLE_TIMEOUT_MS;
+}
+/** Register the recorder on a page, once; it runs before the page's own scripts on every load. */
+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) {
+	try {
+		const report = await page.evaluate(inPageWaitSettled, { timeoutMs });
+		return isSettleReport(report) ? report : unsettled(false);
+	} catch {
+		return unsettled(false);
+	}
+}
+/** A report for a wait that saw no signal. */
+function unsettled(hooked) {
+	return {
+		settled: false,
+		hooked,
+		phase: null,
+		elapsedMs: 0
+	};
+}
+function isSettleReport(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const record = value;
+	return typeof record["settled"] === "boolean" && typeof record["hooked"] === "boolean";
+}
+/**
+* Runs in the browser before the page's scripts, on every document. It watches the preview's
+* channel (`__STORYBOOK_ADDONS_CHANNEL__`, the public `Channel.on` API; nothing is patched) and
+* records the events StoryShelf needs. Playwright serializes only this function's source, so it
+* must not reference anything from this module; `settle.test.ts` evaluates it without bindings.
+*/
+function inPageRecorder() {
+	const scope = globalThis;
+	if (scope["__STORYSHELF_SETTLE__"]) return;
+	const state = {
+		hooked: false,
+		settled: false,
+		phase: null,
+		unhandled: [],
+		hook: () => false
+	};
+	const text = { of(payload) {
+		if (typeof payload === "string") return payload;
+		const record = payload ?? {};
+		const found = record["message"] ?? record["description"] ?? record["title"];
+		return typeof found === "string" ? found : "unknown error";
+	} };
+	const markSettled = () => {
+		state.settled = true;
+	};
+	const failRender = (payload) => {
+		state["renderError"] = text.of(payload);
+		markSettled();
+	};
+	const handlers = {
+		storyRenderPhaseChanged: (payload) => {
+			const phase = payload?.newPhase;
+			if (typeof phase === "string") state.phase = phase;
+		},
+		storyRendered: markSettled,
+		storyFinished: markSettled,
+		storyThrewException: failRender,
+		storyErrored: failRender,
+		storyMissing: failRender,
+		playFunctionThrewException: (payload) => {
+			state["playError"] = text.of(payload);
+		},
+		unhandledErrorsWhilePlaying: (payload) => {
+			for (const error of Array.isArray(payload) ? payload : [payload]) state.unhandled.push(text.of(error));
+		}
+	};
+	state.hook = () => {
+		if (state.hooked) return true;
+		const found = scope["__STORYBOOK_ADDONS_CHANNEL__"] ?? scope["__STORYBOOK_PREVIEW__"]?.channel;
+		if (!found || typeof found.on !== "function") return false;
+		for (const [event, handler] of Object.entries(handlers)) found.on(event, handler);
+		state.hooked = true;
+		return true;
+	};
+	scope["__STORYSHELF_SETTLE__"] = state;
+	if (state.hook()) return;
+	const started = Date.now();
+	const timer = setInterval(() => {
+		if (state.hook() || Date.now() - started > 3e4) clearInterval(timer);
+	}, 2);
+}
+/**
+* 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 }) {
+	const state = globalThis["__STORYSHELF_SETTLE__"];
+	const started = performance.now();
+	const report = (settled, hooked) => ({
+		settled,
+		hooked,
+		phase: state?.phase ?? null,
+		elapsedMs: Math.round(performance.now() - started),
+		...state?.renderError === void 0 ? {} : { renderError: state.renderError },
+		...state?.playError === void 0 ? {} : { playError: state.playError },
+		...state && state.unhandled.length > 0 ? { unhandled: [...state.unhandled] } : {}
+	});
+	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);
+		await new Promise((resolve) => {
+			setTimeout(resolve, 10);
+		});
+	}
+	return report(state.settled, state.hook());
+}
+/** After the signal: let web fonts finish and two frames paint, so the screenshot sees the final DOM. */
+async function awaitPaint(page) {
+	try {
+		await page.evaluate(inPagePaint);
+	} catch {}
+}
+/** Runs in the browser; bounded so a page that never paints (hidden tab) cannot hang the capture. */
+async function inPagePaint() {
+	const scope = globalThis;
+	const frames = new Promise((resolve) => {
+		scope.requestAnimationFrame(() => {
+			scope.requestAnimationFrame(() => {
+				resolve();
+			});
+		});
+	});
+	const cap = new Promise((resolve) => {
+		setTimeout(resolve, 250);
+	});
+	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

@@ -0,0 +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":"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"}

package/dist/static-server.mjs

@@ -3,9 +3,9 @@ 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 { createServer } from "node:http";
-import { join, normalize } from "node:path";
 //#region src/static-server.ts
 /**
 * Serve a built Storybook directory over HTTP on 127.0.0.1 for capture.

package/dist/targets.d.mts

@@ -0,0 +1,26 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { BrowserName, RemoteBrowser } from "@storyshelf/core/adapter/capture-runner";
+//#region src/targets.d.ts
+/** Options of {@link local}. */
+interface LocalOptions {
+  /** Playwright channel (`chrome`, `chrome-beta`, `msedge`, …); only for `chromium` and `chrome`. */
+  channel?: string;
+}
+/** A local engine with options (ADR 0007, decision 1). */
+interface LocalBrowser {
+  readonly kind: "local";
+  readonly engine: BrowserName;
+  readonly options: LocalOptions;
+}
+/**
+ * One entry of `browsers`: a bare engine name, {@link local}, or a remote service from
+ * `@storyshelf/runner-playwright/remote` (`playwrightServer(...)`, `remote(...)`, ...), which
+ * stands for one target per engine.
+ */
+type BrowserEntry = BrowserName | LocalBrowser | RemoteBrowser;
+/** A local engine with options, for `browsers`: `local("chrome", { channel: "chrome-beta" })`. */
+declare function local(engine: BrowserName, options?: LocalOptions): LocalBrowser;
+//#endregion
+export { BrowserEntry, LocalBrowser, LocalOptions, local };
+//# sourceMappingURL=targets.d.mts.map