@storyshelf/runner-playwright 0.6.2 → 0.8.0

package/dist/screenshot.mjs

@@ -1,29 +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 page = await ctx.browser.newPage({ viewport: {
-		width: viewport.width,
-		height: viewport.height
-	} });
+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 {
-		return await runCapture(page, ctx, inputStory, viewport);
+		const result = await runCapture(lease.page, ctx, inputStory, viewport);
+		reusable = true;
+		return result;
+	} catch (error) {
+		throw crash.classify(error);
 	} finally {
-		await page.close();
+		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);
-	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);
+	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 {
@@ -32,8 +56,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 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;
@@ -43,22 +67,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();
 	});
 }
-async function getA11y(ctx, page) {
-	if (!ctx.runA11y) return [];
-	try {
-		return await checkA11y(page);
-	} catch {
-		return [];
-	}
+/** 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, story) {
+	return ctx.runA11y ? await checkA11y(page, ctx.logger, story.id) : [];
 }
 async function settlePage(page, story) {
 	const burst = story.parameters?.burst ?? 1;
@@ -73,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, {
@@ -94,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 { 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 {\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

@@ -0,0 +1,157 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// 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, requireFinished = false) {
+	try {
+		const report = await page.evaluate(inPageWaitSettled, {
+			timeoutMs,
+			...requireFinished ? { requireFinished } : {}
+		});
+		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,
+		finished: 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: (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,
+		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, requireFinished }) {
+	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 && (!requireFinished || state.finished || state.renderError !== void 0)) return report(true, true);
+		await new Promise((resolve) => {
+			setTimeout(resolve, 10);
+		});
+	}
+	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) {
+	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]);
+}
+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(\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":";;;;;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,eACpB,MACA,WACA,kBAAkB,OACK;CACvB,IAAI;EACF,MAAM,SAAkB,MAAM,KAAK,SAAS,mBAAmB;GAC7D;GACA,GAAI,kBAAkB,EAAE,gBAAgB,IAAI,CAAC;EAC/C,CAAC;EACD,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;CAUrC,MAAM,QAAQ;CACd,IAAI,MAAM,0BAA0B;CACpC,MAAM,QAAe;EACnB,QAAQ;EACR,SAAS;EACT,UAAU;EACV,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,gBAAgB,YAAY;GAE1B,IADgB,SAA8C,WAC/C,WAAW,MAAM,iBAAiB,KAAA,GAC/C,MAAM,eAAe;GAEvB,MAAM,WAAW;GACjB,YAAY;EACd;EACA,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;;;;;AAaA,eAAsB,kBAAkB,EACtC,WACA,mBACoC;CAWpC,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,YAAY,CAAC,mBAAmB,MAAM,YAAY,MAAM,gBAAgB,KAAA,IAChF,OAAO,OAAO,MAAM,IAAI;EAG1B,MAAM,IAAI,SAAe,YAAY;GACnC,WAAW,SAAS,EAAE;EACxB,CAAC;CACH;CACA,OAAO,OACL,MAAM,YAAY,CAAC,mBAAmB,MAAM,YAAY,MAAM,gBAAgB,KAAA,IAC9E,MAAM,KAAK,CACb;AACF;;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"}

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 { stat } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { createServer } from "node:http";
-import { join, normalize } from "node:path";
-//#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

package/dist/static-server.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"static-server.mjs","names":[],"sources":["../src/static-server.ts"],"sourcesContent":["import { isPathSafe, mimeFor } from \"@storyshelf/core/utils\";\nimport { createReadStream } from \"node:fs\";\nimport { stat } from \"node:fs/promises\";\nimport { createServer, type Server, type ServerResponse } from \"node:http\";\nimport { join, normalize } from \"node:path\";\n\n/** A local HTTP server serving a built Storybook directory for capture. */\nexport interface StaticServer {\n  url: string;\n  close(): Promise<void>;\n}\n\n/**\n * Serve a built Storybook directory over HTTP on 127.0.0.1 for capture.\n *\n * @param rootDir - Directory containing the built Storybook (`index.html` entry).\n * @returns The server URL and a `close` function to stop it.\n */\nexport async function createStaticServer(rootDir: string): Promise<StaticServer> {\n  const root = normalize(rootDir);\n  const info = await stat(root).catch(() => null);\n  if (!info || !info.isDirectory()) {\n    throw new Error(\n      `Storybook directory not found: ${rootDir}. Upload the built Storybook before capturing.`,\n    );\n  }\n\n  const server = createServer((req, res) => {\n    handleRequest(root, req.url ?? \"/\", res).catch(() => {\n      sendNotFound(res);\n    });\n  });\n\n  const port = await listen(server);\n\n  return {\n    url: `http://127.0.0.1:${port}`,\n    close: async () => {\n      await closeServer(server);\n    },\n  };\n}\n\nfunction sendNotFound(res: ServerResponse): void {\n  res.writeHead(404, { \"content-type\": \"text/plain\" });\n  res.end(\"Not found\");\n}\n\nasync function resolveFile(root: string, urlPath: string): Promise<string | null> {\n  const clean = (urlPath.split(\"?\")[0] ?? \"/\").replace(/^\\/+/u, \"\");\n  const target = normalize(join(root, clean === \"\" ? \"index.html\" : clean));\n  if (!isPathSafe(root, target)) {\n    return null;\n  }\n  const info = await stat(target).catch(() => null);\n  if (!info) {\n    return null;\n  }\n  if (info.isDirectory()) {\n    return resolveFile(root, `${clean}/index.html`);\n  }\n  return info.isFile() ? target : null;\n}\n\nasync function handleRequest(root: string, url: string, res: ServerResponse): Promise<void> {\n  const file = await resolveFile(root, url);\n  if (!file) {\n    sendNotFound(res);\n    return;\n  }\n  res.writeHead(200, { \"content-type\": mimeFor(file) });\n  createReadStream(file).pipe(res);\n}\n\nasync function listen(server: Server): Promise<number> {\n  return await new Promise((resolve, reject) => {\n    server.once(\"error\", reject);\n    server.listen(0, \"127.0.0.1\", () => {\n      const address = server.address();\n      resolve(typeof address === \"object\" && address !== null ? address.port : 0);\n    });\n  });\n}\n\nasync function closeServer(server: Server): Promise<void> {\n  await new Promise<void>((resolve, reject) => {\n    server.close((error) => {\n      if (error) {\n        reject(error);\n      } else {\n        resolve();\n      }\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;AAkBA,eAAsB,mBAAmB,SAAwC;CAC/E,MAAM,OAAO,UAAU,OAAO;CAC9B,MAAM,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,YAAY,IAAI;CAC9C,IAAI,CAAC,QAAQ,CAAC,KAAK,YAAY,GAC7B,MAAM,IAAI,MACR,kCAAkC,QAAQ,+CAC5C;CAGF,MAAM,SAAS,cAAc,KAAK,QAAQ;EACxC,cAAc,MAAM,IAAI,OAAO,KAAK,GAAG,CAAC,CAAC,YAAY;GACnD,aAAa,GAAG;EAClB,CAAC;CACH,CAAC;CAID,OAAO;EACL,KAAK,oBAAoB,MAHR,OAAO,MAAM;EAI9B,OAAO,YAAY;GACjB,MAAM,YAAY,MAAM;EAC1B;CACF;AACF;AAEA,SAAS,aAAa,KAA2B;CAC/C,IAAI,UAAU,KAAK,EAAE,gBAAgB,aAAa,CAAC;CACnD,IAAI,IAAI,WAAW;AACrB;AAEA,eAAe,YAAY,MAAc,SAAyC;CAChF,MAAM,SAAS,QAAQ,MAAM,GAAG,CAAC,CAAC,MAAM,IAAA,CAAK,QAAQ,SAAS,EAAE;CAChE,MAAM,SAAS,UAAU,KAAK,MAAM,UAAU,KAAK,eAAe,KAAK,CAAC;CACxE,IAAI,CAAC,WAAW,MAAM,MAAM,GAC1B,OAAO;CAET,MAAM,OAAO,MAAM,KAAK,MAAM,CAAC,CAAC,YAAY,IAAI;CAChD,IAAI,CAAC,MACH,OAAO;CAET,IAAI,KAAK,YAAY,GACnB,OAAO,YAAY,MAAM,GAAG,MAAM,YAAY;CAEhD,OAAO,KAAK,OAAO,IAAI,SAAS;AAClC;AAEA,eAAe,cAAc,MAAc,KAAa,KAAoC;CAC1F,MAAM,OAAO,MAAM,YAAY,MAAM,GAAG;CACxC,IAAI,CAAC,MAAM;EACT,aAAa,GAAG;EAChB;CACF;CACA,IAAI,UAAU,KAAK,EAAE,gBAAgB,QAAQ,IAAI,EAAE,CAAC;CACpD,iBAAiB,IAAI,CAAC,CAAC,KAAK,GAAG;AACjC;AAEA,eAAe,OAAO,QAAiC;CACrD,OAAO,MAAM,IAAI,SAAS,SAAS,WAAW;EAC5C,OAAO,KAAK,SAAS,MAAM;EAC3B,OAAO,OAAO,GAAG,mBAAmB;GAClC,MAAM,UAAU,OAAO,QAAQ;GAC/B,QAAQ,OAAO,YAAY,YAAY,YAAY,OAAO,QAAQ,OAAO,CAAC;EAC5E,CAAC;CACH,CAAC;AACH;AAEA,eAAe,YAAY,QAA+B;CACxD,MAAM,IAAI,SAAe,SAAS,WAAW;EAC3C,OAAO,OAAO,UAAU;GACtB,IAAI,OACF,OAAO,KAAK;QAEZ,QAAQ;EAEZ,CAAC;CACH,CAAC;AACH"}
+{"version":3,"file":"static-server.mjs","names":[],"sources":["../src/static-server.ts"],"sourcesContent":["import { isPathSafe, mimeFor } from \"@storyshelf/core/utils\";\nimport { createReadStream } from \"node:fs\";\nimport { readFile, stat } from \"node:fs/promises\";\nimport { createServer, type IncomingMessage, type Server, type ServerResponse } from \"node:http\";\nimport { join, normalize } from \"node:path\";\nimport { promisify } from \"node:util\";\nimport { gzip } from \"node:zlib\";\n\nconst compress = promisify(gzip);\nconst MAX_COMPRESS_FILE = 512 * 1024;\nconst MAX_COMPRESS_CACHE = 4 * 1024 * 1024;\nconst MAX_UNCOMPRESSIBLE_FILES = 128;\n\n/** Optional settings for the capture-only server. */\nexport interface StaticServerOptions {\n  /** Precompress small text assets with gzip when accepted; disabled by default. */\n  compression?: boolean | undefined;\n}\n\n/** A local HTTP server serving a built Storybook directory for capture. */\nexport interface StaticServer {\n  url: string;\n  close(): Promise<void>;\n}\n\n/**\n * Serve a built Storybook directory over HTTP on 127.0.0.1 for capture.\n *\n * @param rootDir - Directory containing the built Storybook (`index.html` entry).\n * @returns The server URL and a `close` function to stop it.\n */\nexport async function createStaticServer(\n  rootDir: string,\n  options: StaticServerOptions = {},\n): Promise<StaticServer> {\n  const root = normalize(rootDir);\n  const info = await stat(root).catch(() => null);\n  if (!info || !info.isDirectory()) {\n    throw new Error(\n      `Storybook directory not found: ${rootDir}. Upload the built Storybook before capturing.`,\n    );\n  }\n\n  const cache = new CompressionCache();\n  const server = createServer((req, res) => {\n    handleRequest(root, req, res, options.compression === true ? cache : undefined).catch(() => {\n      sendNotFound(res);\n    });\n  });\n\n  const port = await listen(server);\n\n  return {\n    url: `http://127.0.0.1:${port}`,\n    close: async () => {\n      await closeServer(server);\n    },\n  };\n}\n\nfunction sendNotFound(res: ServerResponse): void {\n  res.writeHead(404, { \"content-type\": \"text/plain\" });\n  res.end(\"Not found\");\n}\n\nasync function resolveFile(root: string, urlPath: string): Promise<string | null> {\n  const clean = (urlPath.split(\"?\")[0] ?? \"/\").replace(/^\\/+/u, \"\");\n  const target = normalize(join(root, clean === \"\" ? \"index.html\" : clean));\n  if (!isPathSafe(root, target)) {\n    return null;\n  }\n  const info = await stat(target).catch(() => null);\n  if (!info) {\n    return null;\n  }\n  if (info.isDirectory()) {\n    return resolveFile(root, `${clean}/index.html`);\n  }\n  return info.isFile() ? target : null;\n}\n\nasync function handleRequest(\n  root: string,\n  req: IncomingMessage,\n  res: ServerResponse,\n  cache: CompressionCache | undefined,\n): Promise<void> {\n  const file = await resolveFile(root, req.url ?? \"/\");\n  if (!file) {\n    sendNotFound(res);\n    return;\n  }\n  // This origin is private to a single capture run and its Storybook directory\n  // is immutable for that run. Reused browser contexts can therefore cache all\n  // successful responses without keeping a cache across builds.\n  const zipped =\n    cache && acceptsGzip(req.headers[\"accept-encoding\"]) && isCompressible(mimeFor(file))\n      ? await cache.get(file)\n      : undefined;\n  res.writeHead(200, {\n    \"content-type\": mimeFor(file),\n    \"cache-control\": \"public, max-age=3600\",\n    ...(cache ? { vary: \"Accept-Encoding\" } : {}),\n    ...(zipped ? { \"content-encoding\": \"gzip\", \"content-length\": zipped.length } : {}),\n  });\n  if (zipped) {\n    res.end(zipped);\n    return;\n  }\n  createReadStream(file).pipe(res);\n}\n\nfunction acceptsGzip(header: string | undefined): boolean {\n  if (!header) return false;\n  const values = header.split(\",\").map((part) => part.trim().split(\";\"));\n  const gzipEntry = values.find(([name]) => name?.trim().toLowerCase() === \"gzip\");\n  const entry = gzipEntry ?? values.find(([name]) => name?.trim() === \"*\");\n  if (!entry) return false;\n  const quality = entry.slice(1).find((part) => /^\\s*q\\s*=/iu.test(part));\n  if (quality === undefined) return true;\n  const value = Number(quality.split(\"=\")[1]);\n  return Number.isFinite(value) && value > 0 && value <= 1;\n}\n\nfunction isCompressible(mime: string): boolean {\n  return /^(?:text\\/|application\\/(?:javascript|json|xml|wasm)|image\\/svg\\+xml)/iu.test(mime);\n}\n\n/** Budget reservations include in-flight reads so concurrent requests stay bounded. */\nclass CompressionCache {\n  private readonly entries = new Map<string, Promise<Buffer | undefined>>();\n  private readonly uncompressible = new Set<string>();\n  private reserved = 0;\n\n  async get(file: string): Promise<Buffer | undefined> {\n    if (this.uncompressible.has(file)) return undefined;\n    const existing = this.entries.get(file);\n    if (existing) return await existing;\n    return await this.reserve(file, (await stat(file)).size);\n  }\n\n  private async reserve(file: string, size: number): Promise<Buffer | undefined> {\n    // Another request can populate the cache while stat is pending.\n    if (this.uncompressible.has(file)) return undefined;\n    const pending = this.entries.get(file);\n    if (pending) return await pending;\n    if (size > MAX_COMPRESS_FILE || this.reserved + size > MAX_COMPRESS_CACHE) return undefined;\n    this.reserved += size;\n    const result = this.encode(file, size);\n    this.entries.set(file, result);\n    return await result;\n  }\n\n  private async encode(file: string, size: number): Promise<Buffer | undefined> {\n    try {\n      const compressed = await compress(await readFile(file));\n      if (compressed.length < size) return compressed;\n      if (this.uncompressible.size < MAX_UNCOMPRESSIBLE_FILES) this.uncompressible.add(file);\n    } catch {\n      // Fall back to the original file if compression fails.\n    }\n    this.reserved -= size;\n    this.entries.delete(file);\n    return undefined;\n  }\n}\n\nasync function listen(server: Server): Promise<number> {\n  return await new Promise((resolve, reject) => {\n    server.once(\"error\", reject);\n    server.listen(0, \"127.0.0.1\", () => {\n      const address = server.address();\n      resolve(typeof address === \"object\" && address !== null ? address.port : 0);\n    });\n  });\n}\n\nasync function closeServer(server: Server): Promise<void> {\n  await new Promise<void>((resolve, reject) => {\n    server.close((error) => {\n      if (error) {\n        reject(error);\n      } else {\n        resolve();\n      }\n    });\n  });\n}\n"],"mappings":"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"}

package/dist/targets.d.mts

@@ -0,0 +1,24 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { BrowserName, RemoteBrowser } from "@storyshelf/core/adapter/capture-runner";
+/** 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;
+export { BrowserEntry, LocalBrowser, LocalOptions, local };
+//# sourceMappingURL=targets.d.mts.map