@onlook/storybook-plugin 0.4.0-beta.7 → 0.4.0-beta.9

package/dist/preview/index.d.ts

@@ -0,0 +1,156 @@
+import * as React from 'react';
+
+/** Advertised + embedded in every event payload. Mirrored CLI-side (U8). */
+declare const ONLOOK_CONTAINMENT_CONTRACT_VERSION = 1;
+/** Marker attached to every contained export, thrown error, and the global registry. */
+type ContainedModuleMarker = {
+    modulePath: string;
+    reason: 'env-validation';
+    envKeys: string[];
+    schemaKind?: string;
+};
+/**
+ * Handshake global, set by the preview annotations (in `beforeAll` and again
+ * defensively when the decorator first runs):
+ * `globalThis.__ONLOOK_CONTAINMENT_CONTRACT__ = { version: 1 }`.
+ */
+declare const ONLOOK_CONTAINMENT_CONTRACT_GLOBAL = "__ONLOOK_CONTAINMENT_CONTRACT__";
+type OnlookContainmentContract = {
+    version: number;
+};
+/**
+ * Emitted when the error-boundary decorator catches a render-time throw and
+ * renders the "needs setup" card in place of the story.
+ */
+declare const ONLOOK_CONTAINED_EVENT = "onlook/contained";
+/**
+ * Emitted once per story mount, after the boundary's children committed
+ * without throwing. The verifier must key `rendered` on THIS (plus absence of
+ * Storybook error events) — never on `STORY_RENDERED` alone, which Storybook
+ * fires even after its own boundary catches.
+ */
+declare const ONLOOK_RENDERED_EVENT = "onlook/rendered";
+/**
+ * Tag-for-verifier re-emit of errors the boundary cannot catch (loader /
+ * `beforeEach` / module-load throws surface as Storybook's
+ * `storyThrewException` / `storyErrored` channel events, outside the React
+ * render). These remain overlay-not-card; no DOM repaint is attempted.
+ */
+declare const ONLOOK_UNCONTAINED_ERROR_EVENT = "onlook/uncontained-error";
+type OnlookContainedPayload = {
+    storyId: string;
+    contractVersion: number;
+    /** Trimmed failure summary (error message). */
+    message: string;
+    /** Present when the failure is attributed to a contained module (U4). */
+    module?: ContainedModuleMarker;
+};
+type OnlookRenderedPayload = {
+    storyId: string;
+    contractVersion: number;
+};
+type OnlookUncontainedErrorPayload = {
+    /** Best-effort (read from the preview iframe URL); absent when unknown. */
+    storyId?: string;
+    contractVersion: number;
+    message: string;
+    /** Which Storybook channel event this re-emits. */
+    source: 'storyThrewException' | 'storyErrored';
+};
+/**
+ * Render-state attribute, value `'rendered' | 'contained'`. Set on
+ * `#storybook-root` (falling back to `document.body` when absent) after each
+ * boundary commit, and ALSO carried on the card's own wrapper element when
+ * contained. Cleared on boundary unmount (story switch), so a stale value
+ * never leaks into the next story's mount — verifiers should match it
+ * together with `data-onlook-story-id`.
+ */
+declare const ONLOOK_RENDER_STATE_ATTR = "data-onlook-render-state";
+/** Companion attribute carrying the story id the render state belongs to. */
+declare const ONLOOK_RENDER_STORY_ATTR = "data-onlook-story-id";
+/** Present (empty value) on the "needs setup" card's wrapper element. */
+declare const ONLOOK_CONTAINED_CARD_ATTR = "data-onlook-contained-card";
+type OnlookRenderState = 'rendered' | 'contained';
+
+type ContainmentCardProps = {
+    storyId: string;
+    storyLabel: string;
+    message: string;
+    module?: ContainedModuleMarker;
+};
+declare function ContainmentCard(props: ContainmentCardProps): React.ReactElement;
+type BoundaryProps = {
+    storyId: string;
+    storyLabel: string;
+    children?: React.ReactNode;
+};
+type BoundaryState = {
+    error: unknown;
+    hasError: boolean;
+};
+declare class OnlookContainmentBoundary extends React.Component<BoundaryProps, BoundaryState> {
+    private renderedSignalSent;
+    constructor(props: BoundaryProps);
+    static getDerivedStateFromError(error: unknown): BoundaryState;
+    componentDidCatch(error: unknown): void;
+    componentDidMount(): void;
+    componentDidUpdate(): void;
+    componentWillUnmount(): void;
+    private signalRenderedIfClean;
+    render(): React.ReactNode;
+}
+type StoryContextLike = {
+    id?: string;
+    title?: string;
+    name?: string;
+};
+/**
+ * The project-level decorator delivered through the addon `./preview` entry.
+ * Keyed by story id so switching stories remounts the boundary (resetting
+ * caught-error state and re-arming the once-per-mount rendered signal).
+ */
+declare function onlookContainmentDecorator(Story: unknown, context?: StoryContextLike): React.ReactElement;
+
+type ChannelLike = {
+    emit: (event: string, payload?: unknown) => void;
+    on?: (event: string, listener: (payload?: unknown) => void) => void;
+};
+/**
+ * The preview channel. Prefers `window.__STORYBOOK_ADDONS_CHANNEL__` (set by
+ * builder-vite's setup code before any addon preview annotation loads), then
+ * the global-backed preview addon store — but only when it already HAS a
+ * channel (calling `getChannel()` earlier would install a mock and clobber
+ * Storybook's own setup). `null` when Storybook hasn't wired one (e.g. tests,
+ * portable stories).
+ */
+declare function getPreviewChannel(): ChannelLike | null;
+/**
+ * Snapshot tooling detection (Chromatic's documented `isChromatic()` check).
+ * The vite-plugin half of this package self-disables under `process.env.CI ||
+ * CHROMATIC`; the preview half can't see those env vars in the browser, so it
+ * keys on Chromatic's user agent / URL marker. When true we keep the boundary
+ * behavior (the card still renders deterministically) but skip the dynamic
+ * signals — channel events and root-element attribute writes — so snapshots
+ * stay byte-stable.
+ */
+declare function isSnapshotEnvironment(): boolean;
+/**
+ * Attribute an error to a contained module (U4's env-containment stand-ins).
+ * Primary: the marker the stand-in attaches at `error.__onlookContained`.
+ * Fallback: scan the `globalThis.__ONLOOK_CONTAINED_MODULES__` registry for a
+ * marker whose modulePath appears in the error message (covers errors
+ * re-wrapped by customer code that drops custom properties).
+ */
+declare function attributeErrorToModule(error: unknown): ContainedModuleMarker | undefined;
+declare function installUncontainedErrorRelay(channel?: ChannelLike | null): void;
+/**
+ * The preview annotations' `beforeAll` — runs once when the preview boots,
+ * before any story (and before any loader can throw). Advertises the
+ * handshake global and installs the uncontained-error relay.
+ */
+declare function onlookBeforeAll(): void;
+
+declare const decorators: (typeof onlookContainmentDecorator)[];
+declare const beforeAll: typeof onlookBeforeAll;
+
+export { ContainmentCard, ONLOOK_CONTAINED_CARD_ATTR, ONLOOK_CONTAINED_EVENT, ONLOOK_CONTAINMENT_CONTRACT_GLOBAL, ONLOOK_CONTAINMENT_CONTRACT_VERSION, ONLOOK_RENDERED_EVENT, ONLOOK_RENDER_STATE_ATTR, ONLOOK_RENDER_STORY_ATTR, ONLOOK_UNCONTAINED_ERROR_EVENT, type OnlookContainedPayload, OnlookContainmentBoundary, type OnlookContainmentContract, type OnlookRenderState, type OnlookRenderedPayload, type OnlookUncontainedErrorPayload, attributeErrorToModule, beforeAll, decorators, getPreviewChannel, installUncontainedErrorRelay, isSnapshotEnvironment, onlookBeforeAll, onlookContainmentDecorator };

package/dist/preview/index.js

@@ -0,0 +1,302 @@
+import * as React from 'react';
+
+// src/preview/containment-boundary.ts
+
+// src/containment-contract/containment-contract.ts
+var ONLOOK_CONTAINMENT_CONTRACT_VERSION = 1;
+var ONLOOK_CONTAINED_MODULES_GLOBAL = "__ONLOOK_CONTAINED_MODULES__";
+var ONLOOK_CONTAINED_PROP = "__onlookContained";
+var ONLOOK_CONTAINMENT_CONTRACT_GLOBAL = "__ONLOOK_CONTAINMENT_CONTRACT__";
+var ONLOOK_CONTAINED_EVENT = "onlook/contained";
+var ONLOOK_RENDERED_EVENT = "onlook/rendered";
+var ONLOOK_UNCONTAINED_ERROR_EVENT = "onlook/uncontained-error";
+var ONLOOK_RENDER_STATE_ATTR = "data-onlook-render-state";
+var ONLOOK_RENDER_STORY_ATTR = "data-onlook-story-id";
+var ONLOOK_CONTAINED_CARD_ATTR = "data-onlook-contained-card";
+
+// src/preview/signals.ts
+var STORYBOOK_STORY_THREW_EXCEPTION = "storyThrewException";
+var STORYBOOK_STORY_ERRORED = "storyErrored";
+function globalScope() {
+  return globalThis;
+}
+function getPreviewChannel() {
+  const g = globalScope();
+  const direct = g.__STORYBOOK_ADDONS_CHANNEL__;
+  if (direct && typeof direct.emit === "function") return direct;
+  const store = g.__STORYBOOK_ADDONS_PREVIEW;
+  if (store && typeof store.hasChannel === "function" && store.hasChannel() && typeof store.getChannel === "function") {
+    return store.getChannel();
+  }
+  return null;
+}
+function isSnapshotEnvironment() {
+  try {
+    const w = globalScope().window;
+    if (!w) return false;
+    if (/Chromatic/.test(w.navigator?.userAgent ?? "")) return true;
+    if (/chromatic=true/.test(w.location?.href ?? "")) return true;
+  } catch {
+  }
+  return false;
+}
+function exposeContract() {
+  globalScope()[ONLOOK_CONTAINMENT_CONTRACT_GLOBAL] = {
+    version: ONLOOK_CONTAINMENT_CONTRACT_VERSION
+  };
+}
+function signalElement() {
+  if (typeof document === "undefined") return null;
+  return document.getElementById("storybook-root") ?? document.body ?? null;
+}
+function setRenderState(state, storyId) {
+  if (isSnapshotEnvironment()) return;
+  try {
+    const el = signalElement();
+    if (!el) return;
+    el.setAttribute(ONLOOK_RENDER_STATE_ATTR, state);
+    el.setAttribute(ONLOOK_RENDER_STORY_ATTR, storyId);
+  } catch {
+  }
+}
+function clearRenderState(storyId) {
+  try {
+    const el = signalElement();
+    if (!el) return;
+    if (el.getAttribute(ONLOOK_RENDER_STORY_ATTR) !== storyId) return;
+    el.removeAttribute(ONLOOK_RENDER_STATE_ATTR);
+    el.removeAttribute(ONLOOK_RENDER_STORY_ATTR);
+  } catch {
+  }
+}
+function emit(event, payload) {
+  if (isSnapshotEnvironment()) return;
+  try {
+    getPreviewChannel()?.emit(event, payload);
+  } catch {
+  }
+}
+function emitContained(payload) {
+  emit(ONLOOK_CONTAINED_EVENT, payload);
+}
+function emitRendered(storyId) {
+  emit(ONLOOK_RENDERED_EVENT, {
+    storyId,
+    contractVersion: ONLOOK_CONTAINMENT_CONTRACT_VERSION
+  });
+}
+function summarizeError(error, maxLength = 400) {
+  const raw = error instanceof Error ? error.message : typeof error === "string" ? error : String(error);
+  const oneline = raw.trim();
+  return oneline.length > maxLength ? `${oneline.slice(0, maxLength - 1)}\u2026` : oneline;
+}
+function attributeErrorToModule(error) {
+  if (error && typeof error === "object") {
+    const direct = error[ONLOOK_CONTAINED_PROP];
+    if (isMarker(direct)) return direct;
+  }
+  const registry = globalScope()[ONLOOK_CONTAINED_MODULES_GLOBAL];
+  if (!registry) return void 0;
+  const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+  if (!message) return void 0;
+  for (const candidate of Object.values(registry)) {
+    if (isMarker(candidate) && message.includes(candidate.modulePath)) {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+function isMarker(value) {
+  return value !== null && typeof value === "object" && typeof value.modulePath === "string" && value.reason === "env-validation";
+}
+var INSTALLED_CHANNELS = /* @__PURE__ */ new WeakSet();
+function currentStoryId() {
+  try {
+    const w = globalScope().window;
+    const search = w?.location?.search;
+    if (!search) return void 0;
+    return new URLSearchParams(search).get("id") ?? void 0;
+  } catch {
+    return void 0;
+  }
+}
+function relayPayload(source, raw) {
+  const obj = raw ?? {};
+  const message = typeof obj.message === "string" ? obj.message : typeof obj.description === "string" ? obj.description : typeof obj.title === "string" ? obj.title : summarizeError(raw);
+  const storyId = currentStoryId();
+  return {
+    ...storyId ? { storyId } : {},
+    contractVersion: ONLOOK_CONTAINMENT_CONTRACT_VERSION,
+    message: summarizeError(message),
+    source
+  };
+}
+function installUncontainedErrorRelay(channel = getPreviewChannel()) {
+  if (!channel || typeof channel.on !== "function") return;
+  if (INSTALLED_CHANNELS.has(channel)) return;
+  INSTALLED_CHANNELS.add(channel);
+  channel.on(STORYBOOK_STORY_THREW_EXCEPTION, (payload) => {
+    emit(ONLOOK_UNCONTAINED_ERROR_EVENT, relayPayload("storyThrewException", payload));
+  });
+  channel.on(STORYBOOK_STORY_ERRORED, (payload) => {
+    emit(ONLOOK_UNCONTAINED_ERROR_EVENT, relayPayload("storyErrored", payload));
+  });
+}
+function onlookBeforeAll() {
+  exposeContract();
+  installUncontainedErrorRelay();
+}
+
+// src/preview/containment-boundary.ts
+var cardStyles = {
+  wrapper: {
+    boxSizing: "border-box",
+    fontFamily: "ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif",
+    color: "#1f2937",
+    background: "#fafaf9",
+    border: "1px solid #e7e5e4",
+    borderRadius: "12px",
+    padding: "20px 24px",
+    margin: "16px",
+    maxWidth: "560px",
+    lineHeight: 1.5
+  },
+  badge: {
+    display: "inline-block",
+    fontSize: "11px",
+    fontWeight: 600,
+    letterSpacing: "0.04em",
+    textTransform: "uppercase",
+    color: "#92400e",
+    background: "#fef3c7",
+    borderRadius: "999px",
+    padding: "2px 10px",
+    marginBottom: "10px"
+  },
+  title: {
+    fontSize: "15px",
+    fontWeight: 600,
+    margin: "0 0 6px"
+  },
+  detail: {
+    fontSize: "13px",
+    margin: "0 0 10px",
+    color: "#44403c"
+  },
+  message: {
+    fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+    fontSize: "12px",
+    whiteSpace: "pre-wrap",
+    wordBreak: "break-word",
+    color: "#7f1d1d",
+    background: "#fef2f2",
+    border: "1px solid #fee2e2",
+    borderRadius: "8px",
+    padding: "10px 12px",
+    margin: "0 0 10px"
+  },
+  footer: {
+    fontSize: "12px",
+    margin: 0,
+    color: "#78716c"
+  }
+};
+var h = React.createElement;
+function ContainmentCard(props) {
+  const { storyId, storyLabel, message, module } = props;
+  const moduleDetail = module ? h(
+    "p",
+    { style: cardStyles.detail, key: "module" },
+    `This story imports `,
+    h("code", null, module.modulePath),
+    module.envKeys.length > 0 ? `, which validates environment variables at load time. Missing: ${module.envKeys.join(", ")}.` : ", which could not load in this environment."
+  ) : null;
+  return h(
+    "div",
+    {
+      [ONLOOK_CONTAINED_CARD_ATTR]: "",
+      [ONLOOK_RENDER_STATE_ATTR]: "contained",
+      [ONLOOK_RENDER_STORY_ATTR]: storyId,
+      role: "alert",
+      style: cardStyles.wrapper
+    },
+    h("span", { style: cardStyles.badge, key: "badge" }, "Needs setup"),
+    h("h2", { style: cardStyles.title, key: "title" }, `${storyLabel} can't render yet`),
+    moduleDetail,
+    message ? h("pre", { style: cardStyles.message, key: "message" }, message) : null,
+    h(
+      "p",
+      { style: cardStyles.footer, key: "footer" },
+      "Onlook contained this error so the rest of Storybook keeps working."
+    )
+  );
+}
+var OnlookContainmentBoundary = class extends React.Component {
+  // `onlook/rendered` fires once per story mount — re-renders of a healthy
+  // story (arg updates) don't re-emit.
+  renderedSignalSent = false;
+  constructor(props) {
+    super(props);
+    this.state = { error: null, hasError: false };
+  }
+  static getDerivedStateFromError(error) {
+    return { error, hasError: true };
+  }
+  componentDidCatch(error) {
+    const module = attributeErrorToModule(error);
+    setRenderState("contained", this.props.storyId);
+    emitContained({
+      storyId: this.props.storyId,
+      contractVersion: ONLOOK_CONTAINMENT_CONTRACT_VERSION,
+      message: summarizeError(error),
+      ...module ? { module } : {}
+    });
+  }
+  componentDidMount() {
+    exposeContract();
+    this.signalRenderedIfClean();
+  }
+  componentDidUpdate() {
+    this.signalRenderedIfClean();
+  }
+  componentWillUnmount() {
+    clearRenderState(this.props.storyId);
+  }
+  signalRenderedIfClean() {
+    if (this.state.hasError || this.renderedSignalSent) return;
+    this.renderedSignalSent = true;
+    setRenderState("rendered", this.props.storyId);
+    emitRendered(this.props.storyId);
+  }
+  render() {
+    if (this.state.hasError) {
+      return h(ContainmentCard, {
+        storyId: this.props.storyId,
+        storyLabel: this.props.storyLabel,
+        message: summarizeError(this.state.error),
+        module: attributeErrorToModule(this.state.error)
+      });
+    }
+    return this.props.children;
+  }
+};
+function storyLabelFrom(context) {
+  const title = context.title?.split("/").pop();
+  if (title && context.name) return `${title} \xB7 ${context.name}`;
+  return title ?? context.name ?? context.id ?? "This story";
+}
+function onlookContainmentDecorator(Story, context) {
+  const ctx = context ?? {};
+  const storyId = ctx.id ?? "unknown";
+  return h(
+    OnlookContainmentBoundary,
+    { key: storyId, storyId, storyLabel: storyLabelFrom(ctx) },
+    h(Story)
+  );
+}
+
+// src/preview/index.ts
+var decorators = [onlookContainmentDecorator];
+var beforeAll = onlookBeforeAll;
+
+export { ContainmentCard, ONLOOK_CONTAINED_CARD_ATTR, ONLOOK_CONTAINED_EVENT, ONLOOK_CONTAINMENT_CONTRACT_GLOBAL, ONLOOK_CONTAINMENT_CONTRACT_VERSION, ONLOOK_RENDERED_EVENT, ONLOOK_RENDER_STATE_ATTR, ONLOOK_RENDER_STORY_ATTR, ONLOOK_UNCONTAINED_ERROR_EVENT, OnlookContainmentBoundary, attributeErrorToModule, beforeAll, decorators, getPreviewChannel, installUncontainedErrorRelay, isSnapshotEnvironment, onlookBeforeAll, onlookContainmentDecorator };

package/dist/screenshot-service/index.js

@@ -2,6 +2,9 @@ import { createRequire } from 'node:module';
 import crypto from 'crypto';
 import fs from 'fs';
 import path from 'path';
+import { execFile } from 'child_process';
+import { createRequire as createRequire$1 } from 'module';
+import { promisify } from 'util';
 import { chromium } from 'playwright';
 
 globalThis.require = createRequire(import.meta.url);
@@ -54,24 +57,84 @@ function updateManifest(storyId, sourcePath, fileHash, boundingBox) {
   };
   saveManifest(manifest);
 }
-var browser = null;
+var execFileAsync = promisify(execFile);
+var require2 = createRequire$1(import.meta.url);
+var browserPromise = null;
+var installPromise = null;
+var isMissingExecutableError = (err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  return msg.includes("Executable doesn't exist") || msg.includes("Please run the following command to download new browsers") || // Older playwright revisions phrase the version-mismatch case differently.
+  /chromium-\d+\/chrome-linux\/chrome/i.test(msg);
+};
+async function installChromium() {
+  if (!installPromise) {
+    installPromise = (async () => {
+      const cliPath = require2.resolve("playwright-core/cli.js");
+      console.log(
+        `[STORYBOOK_PLUGIN] chromium binary missing \u2014 installing via ${cliPath}`
+      );
+      try {
+        const { stdout, stderr } = await execFileAsync(
+          process.execPath,
+          [cliPath, "install", "--force", "chromium"],
+          { timeout: 5 * 60 * 1e3, maxBuffer: 32 * 1024 * 1024 }
+        );
+        if (stdout)
+          console.log(`[STORYBOOK_PLUGIN] playwright install: ${stdout.slice(-1e3)}`);
+        if (stderr)
+          console.log(
+            `[STORYBOOK_PLUGIN] playwright install stderr: ${stderr.slice(-1e3)}`
+          );
+        console.log("[STORYBOOK_PLUGIN] chromium installed");
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        console.error(`[STORYBOOK_PLUGIN] chromium install FAILED: ${detail}`);
+        throw new Error(`Playwright chromium install failed: ${detail}`);
+      } finally {
+        installPromise = null;
+      }
+    })();
+  }
+  return installPromise;
+}
+async function launchWithSelfHeal() {
+  try {
+    return await chromium.launch({ headless: true });
+  } catch (err) {
+    if (!isMissingExecutableError(err)) throw err;
+    console.log("[STORYBOOK_PLUGIN] launch failed, attempting self-heal install");
+    await installChromium();
+    try {
+      return await chromium.launch({ headless: true });
+    } catch (postInstallErr) {
+      const detail = postInstallErr instanceof Error ? postInstallErr.message : String(postInstallErr);
+      console.error(
+        `[STORYBOOK_PLUGIN] launch still failing after install \u2014 likely path or libs issue: ${detail}`
+      );
+      throw new Error(
+        `Playwright chromium is unavailable in this sandbox (install ran but launch still failed): ${detail}`
+      );
+    }
+  }
+}
 async function getBrowser() {
-  if (!browser) {
-    browser = await chromium.launch({
-      headless: true
+  if (!browserPromise) {
+    browserPromise = launchWithSelfHeal().catch((err) => {
+      browserPromise = null;
+      throw err;
     });
   }
-  return browser;
+  return browserPromise;
 }
 async function closeBrowser() {
-  if (browser) {
-    try {
-      await browser.close();
-    } catch (error) {
-      console.error("Error closing browser:", error);
-    } finally {
-      browser = null;
-    }
+  const pending = browserPromise;
+  if (!pending) return;
+  browserPromise = null;
+  try {
+    const b = await pending;
+    await b.close();
+  } catch (error) {
+    console.error("Error closing browser:", error);
   }
 }
 function getScreenshotPath(storyId, theme) {
@@ -83,8 +146,8 @@ function screenshotExists(storyId, theme) {
   return fs.existsSync(screenshotPath);
 }
 async function captureScreenshotBuffer(storyId, theme, width = VIEWPORT_WIDTH, height = VIEWPORT_HEIGHT, storybookUrl = "http://localhost:6006", timeoutMs = 3e4) {
-  const browser2 = await getBrowser();
-  const context = await browser2.newContext({
+  const browser = await getBrowser();
+  const context = await browser.newContext({
     viewport: { width, height },
     deviceScaleFactor: 2
   });
@@ -189,6 +252,34 @@ async function generateScreenshot(storyId, theme, storybookUrl = "http://localho
 }
 
 // src/screenshot-service/screenshot-service.ts
+var ONBOOK_PROXY_TOKEN = process.env.ONBOOK_PROXY_TOKEN ?? null;
+var ONBOOK_BROADCAST_URL = process.env.ONBOOK_BROADCAST_URL ?? null;
+var PROGRESS_TIMEOUT_MS = 3e3;
+async function broadcastScreenshotProgress(completed, total) {
+  if (!ONBOOK_PROXY_TOKEN || !ONBOOK_BROADCAST_URL) return;
+  const percent = total > 0 ? Math.min(100, Math.floor(completed / total * 100)) : null;
+  try {
+    await fetch(ONBOOK_BROADCAST_URL, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${ONBOOK_PROXY_TOKEN}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        event: {
+          type: "SANDBOX_PHASE_PROGRESS",
+          phase: "generating_screenshots",
+          completed,
+          total,
+          percent,
+          label: "Capturing stories"
+        }
+      }),
+      signal: AbortSignal.timeout(PROGRESS_TIMEOUT_MS)
+    });
+  } catch {
+  }
+}
 var StoryTimeoutError = class extends Error {
   constructor(storyId, timeoutMs) {
     super(`Story ${storyId} timed out after ${timeoutMs / 1e3}s`);
@@ -228,6 +319,7 @@ async function generateAllScreenshots(stories, storybookUrl = "http://localhost:
   }
   const storyTimeout = timeoutMs * 2 + 1e4;
   let completed = 0;
+  void broadcastScreenshotProgress(0, displayTotal);
   for (const batch of batches) {
     await Promise.all(
       batch.map(async (story) => {
@@ -297,8 +389,10 @@ async function generateAllScreenshots(stories, storybookUrl = "http://localhost:
         }
       })
     );
+    void broadcastScreenshotProgress(offset + completed, displayTotal);
   }
   await closeBrowser();
+  void broadcastScreenshotProgress(displayTotal, displayTotal);
   console.log("Screenshot generation complete!");
 }
 

package/dist/screenshot-service/utils/browser/index.d.ts

@@ -1,12 +1,6 @@
 import { Browser } from 'playwright';
 
-/**
- * Initialize browser instance
- */
 declare function getBrowser(): Promise<Browser>;
-/**
- * Close browser instance
- */
 declare function closeBrowser(): Promise<void>;
 
 export { closeBrowser, getBrowser };