@onlook/storybook-plugin 0.4.0-beta.11 → 0.4.0-beta.13

package/dist/cli/index.js

@@ -2,9 +2,9 @@
 import { createRequire } from 'node:module';
 import { command, string, boolean, run } from '@drizzle-team/brocli';
 import { execFile, spawn } from 'child_process';
-import fs, { readFileSync, existsSync } from 'fs';
 import path, { resolve, join, dirname } from 'path';
 import crypto from 'crypto';
+import fs, { existsSync, readFileSync } from 'fs';
 import { createRequire as createRequire$1 } from 'module';
 import { promisify } from 'util';
 import { chromium } from 'playwright';
@@ -143,6 +143,77 @@ async function closeBrowser() {
     console.error("Error closing browser:", error);
   }
 }
+
+// src/containment-contract/containment-contract.ts
+var ONLOOK_RENDER_STATE_ATTR = "data-onlook-render-state";
+var ONLOOK_CONTAINED_CARD_ATTR = "data-onlook-contained-card";
+
+// src/screenshot-service/utils/screenshot/screenshot.ts
+function classifyPreviewSnapshot(s) {
+  if (s.text.includes("Sorry, something went wrong")) return "errored";
+  if (s.text.includes("Couldn't find story")) return "errored";
+  if (s.hasContainedCard) return "contained";
+  if (s.renderStateAttr === "contained") return "contained";
+  if (s.renderStateAttr === "rendered") return "rendered";
+  if (s.text.length > 0) return "rendered";
+  if (s.hasSizedElement) return "rendered";
+  return "pending";
+}
+async function detectRenderState(page, opts = {}) {
+  const pollMs = opts.pollMs ?? 250;
+  const settleMs = opts.settleMs ?? 4e3;
+  const blankStablePolls = opts.blankStablePolls ?? 6;
+  const hardCapMs = opts.hardCapMs ?? 2e4;
+  const now = opts.now ?? Date.now;
+  const start = now();
+  let emptyStreak = 0;
+  const snapshot = () => page.evaluate(
+    ({ stateAttr, cardAttr }) => {
+      const root = document.getElementById("storybook-root") ?? document.body;
+      const text = (root?.textContent ?? "").trim();
+      let hasSizedElement = false;
+      if (root) {
+        const all = root.querySelectorAll("*");
+        for (let i = 0; i < all.length; i++) {
+          const rect = all[i]?.getBoundingClientRect();
+          if (rect && rect.width > 0 && rect.height > 0) {
+            hasSizedElement = true;
+            break;
+          }
+        }
+      }
+      return {
+        text,
+        hasContainedCard: Boolean(root?.querySelector(`[${cardAttr}]`)),
+        renderStateAttr: root?.getAttribute(stateAttr) ?? null,
+        hasSizedElement
+      };
+    },
+    { stateAttr: ONLOOK_RENDER_STATE_ATTR, cardAttr: ONLOOK_CONTAINED_CARD_ATTR }
+  );
+  while (true) {
+    let state;
+    let threw = false;
+    try {
+      state = classifyPreviewSnapshot(await snapshot());
+    } catch {
+      state = "pending";
+      threw = true;
+    }
+    if (state === "rendered" || state === "contained" || state === "errored") {
+      return state;
+    }
+    const elapsed = now() - start;
+    if (threw) {
+      emptyStreak = 0;
+    } else if (elapsed >= settleMs) {
+      emptyStreak += 1;
+      if (emptyStreak >= blankStablePolls) return "blank";
+    }
+    if (elapsed >= hardCapMs) return "timedOut";
+    await page.waitForTimeout(pollMs);
+  }
+}
 function getScreenshotPath(storyId, theme) {
   const storyDir = path.join(SCREENSHOTS_DIR, storyId);
   return path.join(storyDir, `${theme}.png`);
@@ -151,7 +222,7 @@ function screenshotExists(storyId, theme) {
   const screenshotPath = getScreenshotPath(storyId, theme);
   return fs.existsSync(screenshotPath);
 }
-async function captureScreenshotBuffer(storyId, theme, width = VIEWPORT_WIDTH, height = VIEWPORT_HEIGHT, storybookUrl = "http://localhost:6006", timeoutMs = 3e4) {
+async function captureScreenshotBuffer(storyId, theme, width = VIEWPORT_WIDTH, height = VIEWPORT_HEIGHT, storybookUrl = "http://localhost:6006", loadTimeoutMs = 9e4, renderTimeoutMs = 2e4) {
   const browser = await getBrowser();
   const context = await browser.newContext({
     viewport: { width, height },
@@ -160,13 +231,14 @@ async function captureScreenshotBuffer(storyId, theme, width = VIEWPORT_WIDTH, h
   const page = await context.newPage();
   try {
     const url = `${storybookUrl}/iframe.html?id=${storyId}&viewMode=story&globals=theme:${theme}`;
-    await page.goto(url, { timeout: timeoutMs });
-    await page.waitForLoadState("domcontentloaded", { timeout: timeoutMs });
-    await page.waitForLoadState("load", { timeout: timeoutMs });
+    await page.goto(url, { timeout: loadTimeoutMs });
+    await page.waitForLoadState("domcontentloaded", { timeout: loadTimeoutMs });
+    await page.waitForLoadState("load", { timeout: loadTimeoutMs });
     try {
       await page.waitForLoadState("networkidle", { timeout: 5e3 });
     } catch {
     }
+    const renderState = await detectRenderState(page, { hardCapMs: renderTimeoutMs });
     await page.evaluate(() => document.fonts.ready);
     try {
       await page.evaluate(async () => {
@@ -228,7 +300,7 @@ async function captureScreenshotBuffer(storyId, theme, width = VIEWPORT_WIDTH, h
     } else {
       screenshotBuffer = await page.screenshot({ type: "png" });
     }
-    return { buffer: screenshotBuffer, boundingBox: resultBoundingBox };
+    return { buffer: screenshotBuffer, boundingBox: resultBoundingBox, renderState };
   } finally {
     await context.close();
   }
@@ -431,36 +503,54 @@ function detectPackageManager(repoRoot) {
   }
   return "npm";
 }
+function getStorybookScript(storybookDir) {
+  const packageJsonPath = join(storybookDir, "package.json");
+  if (!existsSync(packageJsonPath)) {
+    return null;
+  }
+  try {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    return packageJson.scripts?.storybook ?? null;
+  } catch {
+    return null;
+  }
+}
 
 // src/cli/generate-screenshots/generate-screenshots.ts
+function execStorybookCommand(pm) {
+  const devFlags = ["dev", "-p", "6006", "--no-open"];
+  switch (pm) {
+    case "pnpm":
+      return { command: "pnpm", args: ["exec", "storybook", ...devFlags] };
+    case "yarn":
+      return { command: "yarn", args: ["exec", "storybook", ...devFlags] };
+    case "bun":
+      return { command: "bunx", args: ["storybook", ...devFlags] };
+    default:
+      return { command: "npx", args: ["storybook", ...devFlags] };
+  }
+}
 function getStorybookCommand(storybookDir) {
   const repoRoot = findRepoRoot(storybookDir);
   const pm = repoRoot ? detectPackageManager(repoRoot) : "npm";
   console.log(
     `\u{1F4E6} Detected package manager: ${pm}${repoRoot ? ` (from ${repoRoot})` : ""}`
   );
-  let extraArgs = [];
-  try {
-    const pkgPath = resolve(storybookDir, "package.json");
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-    const script = pkg.scripts?.storybook ?? "";
-    const hasPort = script.includes("-p ") || script.includes("--port");
-    const hasNoOpen = script.includes("--no-open");
-    if (!hasPort || !hasNoOpen) {
-      const needsSeparator = pm === "npm" || pm === "pnpm";
-      const flags = [];
-      if (!hasPort) flags.push("-p", "6006");
-      if (!hasNoOpen) flags.push("--no-open");
-      extraArgs = needsSeparator && flags.length > 0 ? ["--", ...flags] : flags;
-    }
-  } catch {
-    const separator = pm === "npm" || pm === "pnpm" ? ["--"] : [];
-    extraArgs = [...separator, "-p", "6006", "--no-open"];
+  const memberScript = getStorybookScript(storybookDir);
+  const rootScript = !memberScript && repoRoot && repoRoot !== storybookDir ? getStorybookScript(repoRoot) : null;
+  const [script, scriptDir] = memberScript ? [memberScript, storybookDir] : rootScript && repoRoot ? [rootScript, repoRoot] : [null, storybookDir];
+  if (!script) {
+    console.log("\u26A0\uFE0F  No `storybook` script found; invoking the binary directly");
+    return { ...execStorybookCommand(pm), cwd: storybookDir };
   }
-  return {
-    command: pm,
-    args: ["run", "storybook", ...extraArgs]
-  };
+  const hasPort = script.includes("-p ") || script.includes("--port");
+  const hasNoOpen = script.includes("--no-open");
+  const flags = [];
+  if (!hasPort) flags.push("-p", "6006");
+  if (!hasNoOpen) flags.push("--no-open");
+  const needsSeparator = pm === "npm" || pm === "pnpm";
+  const extraArgs = needsSeparator && flags.length > 0 ? ["--", ...flags] : flags;
+  return { command: pm, args: ["run", "storybook", ...extraArgs], cwd: scriptDir };
 }
 async function isStorybookRunning(url) {
   try {
@@ -575,8 +665,8 @@ async function generateScreenshots(options = {}) {
     if (alreadyRunning) {
       console.log("\u2705 Storybook is already running");
     } else {
-      const { command: command2, args } = getStorybookCommand(storybookDir);
-      storybookProcess = await startStorybook(command2, args, storybookDir);
+      const { command: command2, args, cwd } = getStorybookCommand(storybookDir);
+      storybookProcess = await startStorybook(command2, args, cwd);
       weStartedStorybook = true;
       console.log("\u23F3 Waiting for Storybook to finish compiling...");
       await waitForStorybookReady(url);

package/dist/index.d.ts

@@ -53,6 +53,20 @@ type OnlookContainedPayload = {
     message: string;
     /** Present when the failure is attributed to a contained module (U4). */
     module?: ContainedModuleMarker;
+    /**
+     * React component stack from `onCaughtError`'s `errorInfo` (ONL-1505,
+     * additive). Present only on the `via: 'onCaughtError'` path — the legacy
+     * boundary decorator has no component stack to offer.
+     */
+    componentStack?: string;
+    /**
+     * Which catch path emitted this (ONL-1505, additive). `'onCaughtError'` =
+     * the React root hook registered via `parameters.react.rootOptions` (catches
+     * component render-throws, incl. those caught by Storybook's own
+     * renderToCanvas ErrorBoundary); `'decorator'` = the legacy
+     * OnlookContainmentBoundary decorator. Absent ⟹ legacy decorator (pre-1505).
+     */
+    via?: 'onCaughtError' | 'decorator';
 };
 type OnlookRenderedPayload = {
     storyId: string;

package/dist/index.js

@@ -509,11 +509,76 @@ async function getBrowser() {
   }
   return browserPromise;
 }
+function classifyPreviewSnapshot(s) {
+  if (s.text.includes("Sorry, something went wrong")) return "errored";
+  if (s.text.includes("Couldn't find story")) return "errored";
+  if (s.hasContainedCard) return "contained";
+  if (s.renderStateAttr === "contained") return "contained";
+  if (s.renderStateAttr === "rendered") return "rendered";
+  if (s.text.length > 0) return "rendered";
+  if (s.hasSizedElement) return "rendered";
+  return "pending";
+}
+async function detectRenderState(page, opts = {}) {
+  const pollMs = opts.pollMs ?? 250;
+  const settleMs = opts.settleMs ?? 4e3;
+  const blankStablePolls = opts.blankStablePolls ?? 6;
+  const hardCapMs = opts.hardCapMs ?? 2e4;
+  const now = opts.now ?? Date.now;
+  const start = now();
+  let emptyStreak = 0;
+  const snapshot = () => page.evaluate(
+    ({ stateAttr, cardAttr }) => {
+      const root = document.getElementById("storybook-root") ?? document.body;
+      const text = (root?.textContent ?? "").trim();
+      let hasSizedElement = false;
+      if (root) {
+        const all = root.querySelectorAll("*");
+        for (let i = 0; i < all.length; i++) {
+          const rect = all[i]?.getBoundingClientRect();
+          if (rect && rect.width > 0 && rect.height > 0) {
+            hasSizedElement = true;
+            break;
+          }
+        }
+      }
+      return {
+        text,
+        hasContainedCard: Boolean(root?.querySelector(`[${cardAttr}]`)),
+        renderStateAttr: root?.getAttribute(stateAttr) ?? null,
+        hasSizedElement
+      };
+    },
+    { stateAttr: ONLOOK_RENDER_STATE_ATTR, cardAttr: ONLOOK_CONTAINED_CARD_ATTR }
+  );
+  while (true) {
+    let state;
+    let threw = false;
+    try {
+      state = classifyPreviewSnapshot(await snapshot());
+    } catch {
+      state = "pending";
+      threw = true;
+    }
+    if (state === "rendered" || state === "contained" || state === "errored") {
+      return state;
+    }
+    const elapsed = now() - start;
+    if (threw) {
+      emptyStreak = 0;
+    } else if (elapsed >= settleMs) {
+      emptyStreak += 1;
+      if (emptyStreak >= blankStablePolls) return "blank";
+    }
+    if (elapsed >= hardCapMs) return "timedOut";
+    await page.waitForTimeout(pollMs);
+  }
+}
 function getScreenshotPath(storyId, theme) {
   const storyDir = path7.join(SCREENSHOTS_DIR, storyId);
   return path7.join(storyDir, `${theme}.png`);
 }
-async function captureScreenshotBuffer(storyId, theme, width = VIEWPORT_WIDTH, height = VIEWPORT_HEIGHT, storybookUrl = "http://localhost:6006", timeoutMs = 3e4) {
+async function captureScreenshotBuffer(storyId, theme, width = VIEWPORT_WIDTH, height = VIEWPORT_HEIGHT, storybookUrl = "http://localhost:6006", loadTimeoutMs = 9e4, renderTimeoutMs = 2e4) {
   const browser = await getBrowser();
   const context = await browser.newContext({
     viewport: { width, height },
@@ -522,13 +587,14 @@ async function captureScreenshotBuffer(storyId, theme, width = VIEWPORT_WIDTH, h
   const page = await context.newPage();
   try {
     const url = `${storybookUrl}/iframe.html?id=${storyId}&viewMode=story&globals=theme:${theme}`;
-    await page.goto(url, { timeout: timeoutMs });
-    await page.waitForLoadState("domcontentloaded", { timeout: timeoutMs });
-    await page.waitForLoadState("load", { timeout: timeoutMs });
+    await page.goto(url, { timeout: loadTimeoutMs });
+    await page.waitForLoadState("domcontentloaded", { timeout: loadTimeoutMs });
+    await page.waitForLoadState("load", { timeout: loadTimeoutMs });
     try {
       await page.waitForLoadState("networkidle", { timeout: 5e3 });
     } catch {
     }
+    const renderState = await detectRenderState(page, { hardCapMs: renderTimeoutMs });
     await page.evaluate(() => document.fonts.ready);
     try {
       await page.evaluate(async () => {
@@ -590,7 +656,7 @@ async function captureScreenshotBuffer(storyId, theme, width = VIEWPORT_WIDTH, h
     } else {
       screenshotBuffer = await page.screenshot({ type: "png" });
     }
-    return { buffer: screenshotBuffer, boundingBox: resultBoundingBox };
+    return { buffer: screenshotBuffer, boundingBox: resultBoundingBox, renderState };
   } finally {
     await context.close();
   }
@@ -795,6 +861,7 @@ async function captureConsoleLogs(storyId, theme = "light", storybookUrl = "http
   const page = await context.newPage();
   const logs = [];
   const pageErrors = [];
+  const failedRequests = [];
   page.on("console", (msg) => {
     const level = msg.type();
     logs.push({
@@ -806,6 +873,28 @@ async function captureConsoleLogs(storyId, theme = "light", storybookUrl = "http
   page.on("pageerror", (err) => {
     pageErrors.push(err.message);
   });
+  page.on("response", (res) => {
+    const status = res.status();
+    if (status >= 400) {
+      const req = res.request();
+      failedRequests.push({
+        url: res.url(),
+        status,
+        method: req.method(),
+        resourceType: req.resourceType(),
+        failure: null
+      });
+    }
+  });
+  page.on("requestfailed", (req) => {
+    failedRequests.push({
+      url: req.url(),
+      status: null,
+      method: req.method(),
+      resourceType: req.resourceType(),
+      failure: req.failure()?.errorText ?? "request failed"
+    });
+  });
   const url = `${storybookUrl}/iframe.html?id=${storyId}&viewMode=story&globals=theme:${theme}`;
   try {
     await page.goto(url, { timeout: timeoutMs });
@@ -816,7 +905,7 @@ async function captureConsoleLogs(storyId, theme = "light", storybookUrl = "http
     } catch {
     }
     await new Promise((r) => setTimeout(r, 1e3));
-    return { logs, pageErrors, url };
+    return { logs, pageErrors, failedRequests, url };
   } finally {
     await context.close();
   }
@@ -1148,9 +1237,11 @@ var serveMetadataAndScreenshots = (req, res, next) => {
       res.end(JSON.stringify({ error: 'theme must be "light" or "dark"' }));
       return;
     }
-    captureScreenshotBuffer(storyId, theme, width, height).then(({ buffer }) => {
+    captureScreenshotBuffer(storyId, theme, width, height).then(({ buffer, renderState }) => {
       res.setHeader("Content-Type", "image/png");
       res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Expose-Headers", "x-onlook-render-state");
+      res.setHeader("x-onlook-render-state", renderState);
       res.setHeader("Cache-Control", "no-cache");
       res.end(buffer);
     }).catch((error) => {

package/dist/preset/index.d.ts

@@ -2,9 +2,13 @@ import { O as OnlookPluginOptions } from '../storybook-onlook-plugin-B9Eo_OIq.js
 import 'vite';
 
 declare function pluginOptionsFromPresetOptions(options: Record<string, unknown> | undefined): OnlookPluginOptions;
+type ChannelLike = {
+    on(eventName: string, listener: (...args: unknown[]) => void): unknown;
+};
+declare function experimental_serverChannel(channel: ChannelLike): Promise<ChannelLike>;
 type ViteConfigLike = {
     plugins?: unknown[];
 } & Record<string, unknown>;
 declare function viteFinal(config: ViteConfigLike, options?: Record<string, unknown>): Promise<ViteConfigLike>;
 
-export { pluginOptionsFromPresetOptions, viteFinal };
+export { experimental_serverChannel, pluginOptionsFromPresetOptions, viteFinal };

package/dist/preset/index.js

@@ -13,6 +13,15 @@ import { promisify } from 'util';
 import { chromium } from 'playwright';
 
 globalThis.require = createRequire(import.meta.url);
+
+// src/containment-contract/containment-contract.ts
+var ONLOOK_CONTAINED_MODULES_GLOBAL = "__ONLOOK_CONTAINED_MODULES__";
+var ONLOOK_CONTAINED_PROP = "__onlookContained";
+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_CONTAINED_CARD_ATTR = "data-onlook-contained-card";
 function componentLocPlugin(options = {}) {
   const include = options.include ?? /\.(jsx|tsx)$/;
   const traverse = traverseModule.default ?? traverseModule;
@@ -73,12 +82,6 @@ function componentLocPlugin(options = {}) {
     }
   };
 }
-
-// src/containment-contract/containment-contract.ts
-var ONLOOK_CONTAINED_MODULES_GLOBAL = "__ONLOOK_CONTAINED_MODULES__";
-var ONLOOK_CONTAINED_PROP = "__onlookContained";
-
-// src/env-containment/env-containment.ts
 var ENV_CONTAINMENT_PLUGIN_NAME = "onlook-env-containment";
 var ENV_CONTAINMENT_VIRTUAL_PREFIX = "\0onlook-env-containment:";
 var VALID_IDENT_RE = /^[A-Za-z_$][\w$]*$/;
@@ -386,11 +389,76 @@ async function getBrowser() {
   }
   return browserPromise;
 }
+function classifyPreviewSnapshot(s) {
+  if (s.text.includes("Sorry, something went wrong")) return "errored";
+  if (s.text.includes("Couldn't find story")) return "errored";
+  if (s.hasContainedCard) return "contained";
+  if (s.renderStateAttr === "contained") return "contained";
+  if (s.renderStateAttr === "rendered") return "rendered";
+  if (s.text.length > 0) return "rendered";
+  if (s.hasSizedElement) return "rendered";
+  return "pending";
+}
+async function detectRenderState(page, opts = {}) {
+  const pollMs = opts.pollMs ?? 250;
+  const settleMs = opts.settleMs ?? 4e3;
+  const blankStablePolls = opts.blankStablePolls ?? 6;
+  const hardCapMs = opts.hardCapMs ?? 2e4;
+  const now = opts.now ?? Date.now;
+  const start = now();
+  let emptyStreak = 0;
+  const snapshot = () => page.evaluate(
+    ({ stateAttr, cardAttr }) => {
+      const root = document.getElementById("storybook-root") ?? document.body;
+      const text = (root?.textContent ?? "").trim();
+      let hasSizedElement = false;
+      if (root) {
+        const all = root.querySelectorAll("*");
+        for (let i = 0; i < all.length; i++) {
+          const rect = all[i]?.getBoundingClientRect();
+          if (rect && rect.width > 0 && rect.height > 0) {
+            hasSizedElement = true;
+            break;
+          }
+        }
+      }
+      return {
+        text,
+        hasContainedCard: Boolean(root?.querySelector(`[${cardAttr}]`)),
+        renderStateAttr: root?.getAttribute(stateAttr) ?? null,
+        hasSizedElement
+      };
+    },
+    { stateAttr: ONLOOK_RENDER_STATE_ATTR, cardAttr: ONLOOK_CONTAINED_CARD_ATTR }
+  );
+  while (true) {
+    let state;
+    let threw = false;
+    try {
+      state = classifyPreviewSnapshot(await snapshot());
+    } catch {
+      state = "pending";
+      threw = true;
+    }
+    if (state === "rendered" || state === "contained" || state === "errored") {
+      return state;
+    }
+    const elapsed = now() - start;
+    if (threw) {
+      emptyStreak = 0;
+    } else if (elapsed >= settleMs) {
+      emptyStreak += 1;
+      if (emptyStreak >= blankStablePolls) return "blank";
+    }
+    if (elapsed >= hardCapMs) return "timedOut";
+    await page.waitForTimeout(pollMs);
+  }
+}
 function getScreenshotPath(storyId, theme) {
   const storyDir = path7.join(SCREENSHOTS_DIR, storyId);
   return path7.join(storyDir, `${theme}.png`);
 }
-async function captureScreenshotBuffer(storyId, theme, width = VIEWPORT_WIDTH, height = VIEWPORT_HEIGHT, storybookUrl = "http://localhost:6006", timeoutMs = 3e4) {
+async function captureScreenshotBuffer(storyId, theme, width = VIEWPORT_WIDTH, height = VIEWPORT_HEIGHT, storybookUrl = "http://localhost:6006", loadTimeoutMs = 9e4, renderTimeoutMs = 2e4) {
   const browser = await getBrowser();
   const context = await browser.newContext({
     viewport: { width, height },
@@ -399,13 +467,14 @@ async function captureScreenshotBuffer(storyId, theme, width = VIEWPORT_WIDTH, h
   const page = await context.newPage();
   try {
     const url = `${storybookUrl}/iframe.html?id=${storyId}&viewMode=story&globals=theme:${theme}`;
-    await page.goto(url, { timeout: timeoutMs });
-    await page.waitForLoadState("domcontentloaded", { timeout: timeoutMs });
-    await page.waitForLoadState("load", { timeout: timeoutMs });
+    await page.goto(url, { timeout: loadTimeoutMs });
+    await page.waitForLoadState("domcontentloaded", { timeout: loadTimeoutMs });
+    await page.waitForLoadState("load", { timeout: loadTimeoutMs });
     try {
       await page.waitForLoadState("networkidle", { timeout: 5e3 });
     } catch {
     }
+    const renderState = await detectRenderState(page, { hardCapMs: renderTimeoutMs });
     await page.evaluate(() => document.fonts.ready);
     try {
       await page.evaluate(async () => {
@@ -467,7 +536,7 @@ async function captureScreenshotBuffer(storyId, theme, width = VIEWPORT_WIDTH, h
     } else {
       screenshotBuffer = await page.screenshot({ type: "png" });
     }
-    return { buffer: screenshotBuffer, boundingBox: resultBoundingBox };
+    return { buffer: screenshotBuffer, boundingBox: resultBoundingBox, renderState };
   } finally {
     await context.close();
   }
@@ -788,6 +857,7 @@ async function captureConsoleLogs(storyId, theme = "light", storybookUrl = "http
   const page = await context.newPage();
   const logs = [];
   const pageErrors = [];
+  const failedRequests = [];
   page.on("console", (msg) => {
     const level = msg.type();
     logs.push({
@@ -799,6 +869,28 @@ async function captureConsoleLogs(storyId, theme = "light", storybookUrl = "http
   page.on("pageerror", (err) => {
     pageErrors.push(err.message);
   });
+  page.on("response", (res) => {
+    const status = res.status();
+    if (status >= 400) {
+      const req = res.request();
+      failedRequests.push({
+        url: res.url(),
+        status,
+        method: req.method(),
+        resourceType: req.resourceType(),
+        failure: null
+      });
+    }
+  });
+  page.on("requestfailed", (req) => {
+    failedRequests.push({
+      url: req.url(),
+      status: null,
+      method: req.method(),
+      resourceType: req.resourceType(),
+      failure: req.failure()?.errorText ?? "request failed"
+    });
+  });
   const url = `${storybookUrl}/iframe.html?id=${storyId}&viewMode=story&globals=theme:${theme}`;
   try {
     await page.goto(url, { timeout: timeoutMs });
@@ -809,7 +901,7 @@ async function captureConsoleLogs(storyId, theme = "light", storybookUrl = "http
     } catch {
     }
     await new Promise((r) => setTimeout(r, 1e3));
-    return { logs, pageErrors, url };
+    return { logs, pageErrors, failedRequests, url };
   } finally {
     await context.close();
   }
@@ -1141,9 +1233,11 @@ var serveMetadataAndScreenshots = (req, res, next) => {
       res.end(JSON.stringify({ error: 'theme must be "light" or "dark"' }));
       return;
     }
-    captureScreenshotBuffer(storyId, theme, width, height).then(({ buffer }) => {
+    captureScreenshotBuffer(storyId, theme, width, height).then(({ buffer, renderState }) => {
       res.setHeader("Content-Type", "image/png");
       res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Expose-Headers", "x-onlook-render-state");
+      res.setHeader("x-onlook-render-state", renderState);
       res.setHeader("Cache-Control", "no-cache");
       res.end(buffer);
     }).catch((error) => {
@@ -1338,12 +1432,12 @@ function storybookOnlookPlugin(options = {}) {
         "manifest.json"
       );
       refreshManifest(cachedManifestPath);
-      let pending2;
+      let pending3;
       const scheduleRefresh = (file) => {
         if (file !== cachedManifestPath) return;
-        if (pending2) clearTimeout(pending2);
-        pending2 = setTimeout(() => {
-          pending2 = void 0;
+        if (pending3) clearTimeout(pending3);
+        pending3 = setTimeout(() => {
+          pending3 = void 0;
           refreshManifest(cachedManifestPath);
         }, 100);
       };
@@ -1428,6 +1522,68 @@ function storybookOnlookPlugin(options = {}) {
   );
 }
 
+// src/utils/notifyStoryError/notifyStoryError.ts
+var DEBOUNCE_MS3 = 300;
+var REQUEST_TIMEOUT_MS2 = 5e3;
+var pending2 = null;
+var inFlight2 = false;
+var trailing = false;
+var latest = null;
+function notifyStoryError(payload) {
+  enqueue({ type: "STORY_ERROR", ...payload });
+}
+function notifyStoryResolved(storyId) {
+  enqueue({ type: "STORY_RESOLVED", storyId });
+}
+function enqueue(event) {
+  const proxyToken = process.env.ONBOOK_PROXY_TOKEN;
+  const broadcastUrl = process.env.ONBOOK_BROADCAST_URL;
+  if (!proxyToken || !broadcastUrl) return;
+  latest = event;
+  if (pending2) clearTimeout(pending2);
+  pending2 = setTimeout(() => {
+    pending2 = null;
+    if (inFlight2) {
+      trailing = true;
+      return;
+    }
+    void fire2(proxyToken, broadcastUrl);
+  }, DEBOUNCE_MS3);
+}
+async function fire2(proxyToken, broadcastUrl) {
+  const event = latest;
+  if (!event) return;
+  inFlight2 = true;
+  try {
+    const res = await fetch(broadcastUrl, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${proxyToken}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ event }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS2)
+    });
+    if (!res.ok) {
+      console.warn("[STORYBOOK_PLUGIN] story-event broadcast non-2xx", {
+        status: res.status,
+        statusText: res.statusText
+      });
+    }
+  } catch (err) {
+    console.warn(
+      "[STORYBOOK_PLUGIN] story-event broadcast failed",
+      err instanceof Error ? err.message : String(err)
+    );
+  } finally {
+    inFlight2 = false;
+    if (trailing) {
+      trailing = false;
+      void fire2(proxyToken, broadcastUrl);
+    }
+  }
+}
+
 // src/preset/preset.ts
 var OPTION_KEY_MAP = {
   port: true,
@@ -1449,10 +1605,56 @@ function pluginOptionsFromPresetOptions(options) {
   }
   return picked;
 }
+var erroredStories = /* @__PURE__ */ new Map();
+var RENDER_RESOLVE_SUPPRESS_MS = 1500;
+async function experimental_serverChannel(channel) {
+  try {
+    channel.on(ONLOOK_CONTAINED_EVENT, (...args) => {
+      const payload = args[0];
+      if (!payload) return;
+      console.error(`[ONBOOK_STORY_ERROR] contained story=${payload.storyId || "?"}`);
+      if (payload.storyId) erroredStories.set(payload.storyId, Date.now());
+      notifyStoryError({
+        storyId: payload.storyId ?? "",
+        message: payload.message ?? "Unknown story error",
+        source: "contained",
+        ...payload.componentStack ? { componentStack: payload.componentStack } : {}
+      });
+    });
+    channel.on(ONLOOK_UNCONTAINED_ERROR_EVENT, (...args) => {
+      const payload = args[0];
+      if (!payload) return;
+      console.error(`[ONBOOK_STORY_ERROR] uncontained story=${payload.storyId || "?"}`);
+      if (payload.storyId) erroredStories.set(payload.storyId, Date.now());
+      notifyStoryError({
+        storyId: payload.storyId ?? "",
+        message: payload.message ?? "Unknown story error",
+        source: "uncontained"
+      });
+    });
+    channel.on(ONLOOK_RENDERED_EVENT, (...args) => {
+      const payload = args[0];
+      if (!payload?.storyId) return;
+      const erroredAt = erroredStories.get(payload.storyId);
+      if (erroredAt === void 0) return;
+      if (Date.now() - erroredAt < RENDER_RESOLVE_SUPPRESS_MS) return;
+      erroredStories.delete(payload.storyId);
+      console.error(`[ONBOOK_STORY_ERROR] resolved story=${payload.storyId}`);
+      notifyStoryResolved(payload.storyId);
+    });
+    console.error("[ONBOOK_STORY_ERROR] server-channel error + recovery tap attached");
+  } catch (err) {
+    console.error(
+      "[ONBOOK_STORY_ERROR] failed to attach server-channel tap",
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+  return channel;
+}
 async function viteFinal(config, options = {}) {
   const plugins = storybookOnlookPlugin(pluginOptionsFromPresetOptions(options));
   if (plugins.length === 0) return config;
   return { ...config, plugins: [...config.plugins ?? [], ...plugins] };
 }
 
-export { pluginOptionsFromPresetOptions, viteFinal };
+export { experimental_serverChannel, pluginOptionsFromPresetOptions, viteFinal };

package/dist/preview/index.d.ts

@@ -44,6 +44,20 @@ type OnlookContainedPayload = {
     message: string;
     /** Present when the failure is attributed to a contained module (U4). */
     module?: ContainedModuleMarker;
+    /**
+     * React component stack from `onCaughtError`'s `errorInfo` (ONL-1505,
+     * additive). Present only on the `via: 'onCaughtError'` path — the legacy
+     * boundary decorator has no component stack to offer.
+     */
+    componentStack?: string;
+    /**
+     * Which catch path emitted this (ONL-1505, additive). `'onCaughtError'` =
+     * the React root hook registered via `parameters.react.rootOptions` (catches
+     * component render-throws, incl. those caught by Storybook's own
+     * renderToCanvas ErrorBoundary); `'decorator'` = the legacy
+     * OnlookContainmentBoundary decorator. Absent ⟹ legacy decorator (pre-1505).
+     */
+    via?: 'onCaughtError' | 'decorator';
 };
 type OnlookRenderedPayload = {
     storyId: string;
@@ -92,7 +106,7 @@ declare class OnlookContainmentBoundary extends React.Component<BoundaryProps, B
     private renderedSignalSent;
     constructor(props: BoundaryProps);
     static getDerivedStateFromError(error: unknown): BoundaryState;
-    componentDidCatch(error: unknown): void;
+    componentDidCatch(): void;
     componentDidMount(): void;
     componentDidUpdate(): void;
     componentWillUnmount(): void;
@@ -134,6 +148,27 @@ declare function getPreviewChannel(): ChannelLike | null;
  * stay byte-stable.
  */
 declare function isSnapshotEnvironment(): boolean;
+/** Trim a React component stack to a payload-sized summary. */
+declare function summarizeComponentStack(stack: unknown, maxLength?: number): string | undefined;
+/**
+ * React root `onCaughtError` handler (ONL-1505). Registered via the preview
+ * annotations' `parameters.react.rootOptions.onCaughtError`, which
+ * `@storybook/react`'s `renderToCanvas` threads verbatim into `createRoot`.
+ *
+ * React 19 calls this for ANY error caught by an error boundary in the story
+ * tree — crucially including Storybook's own `renderToCanvas` ErrorBoundary,
+ * which is what catches a component render-throw. This is the ONLY node-
+ * reachable signal for render-crashes: `window.onerror` fires only for
+ * UNCAUGHT errors, and the channel `storyThrewException` / `storyErrored`
+ * events don't fire for boundary-caught render-throws. We re-emit as the
+ * existing `onlook/contained` event (tagged `via: 'onCaughtError'`) so the
+ * node-side server-channel tap needs no change.
+ *
+ * Registering `onCaughtError` replaces React's default (which logs caught
+ * errors to `console.error`), so we re-log for dev parity — keeping the
+ * iframe console behavior unchanged and giving the live tap a second marker.
+ */
+declare function handleRootCaughtError(error: unknown, componentStack?: unknown): void;
 /**
  * Attribute an error to a contained module (U4's env-containment stand-ins).
  * Primary: the marker the stand-in attaches at `error.__onlookContained`.
@@ -152,5 +187,14 @@ declare function onlookBeforeAll(): void;
 
 declare const decorators: (typeof onlookContainmentDecorator)[];
 declare const beforeAll: typeof onlookBeforeAll;
+declare const parameters: {
+    react: {
+        rootOptions: {
+            onCaughtError: (error: unknown, errorInfo?: {
+                componentStack?: string;
+            }) => void;
+        };
+    };
+};
 
-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 };
+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, handleRootCaughtError, installUncontainedErrorRelay, isSnapshotEnvironment, onlookBeforeAll, onlookContainmentDecorator, parameters, summarizeComponentStack };

package/dist/preview/index.js

@@ -85,6 +85,28 @@ function emitRendered(storyId) {
     contractVersion: ONLOOK_CONTAINMENT_CONTRACT_VERSION
   });
 }
+function summarizeComponentStack(stack, maxLength = 2e3) {
+  if (typeof stack !== "string") return void 0;
+  const trimmed = stack.trim();
+  if (!trimmed) return void 0;
+  return trimmed.length > maxLength ? `${trimmed.slice(0, maxLength - 1)}\u2026` : trimmed;
+}
+function handleRootCaughtError(error, componentStack) {
+  try {
+    console.error(error);
+  } catch {
+  }
+  const storyId = currentStoryId();
+  const stack = summarizeComponentStack(componentStack);
+  const module = attributeErrorToModule(error);
+  emitContained({
+    storyId: storyId ?? "",
+    contractVersion: ONLOOK_CONTAINMENT_CONTRACT_VERSION,
+    message: summarizeError(error),
+    ...module ? { module } : {},
+    ...stack ? { componentStack: stack } : {}
+  });
+}
 function summarizeError(error, maxLength = 400) {
   const raw = error instanceof Error ? error.message : typeof error === "string" ? error : String(error);
   const oneline = raw.trim();
@@ -242,15 +264,8 @@ var OnlookContainmentBoundary = class extends React.Component {
   static getDerivedStateFromError(error) {
     return { error, hasError: true };
   }
-  componentDidCatch(error) {
-    const module = attributeErrorToModule(error);
+  componentDidCatch() {
     setRenderState("contained", this.props.storyId);
-    emitContained({
-      storyId: this.props.storyId,
-      contractVersion: ONLOOK_CONTAINMENT_CONTRACT_VERSION,
-      message: summarizeError(error),
-      ...module ? { module } : {}
-    });
   }
   componentDidMount() {
     exposeContract();
@@ -298,5 +313,12 @@ function onlookContainmentDecorator(Story, context) {
 // src/preview/index.ts
 var decorators = [onlookContainmentDecorator];
 var beforeAll = onlookBeforeAll;
+var parameters = {
+  react: {
+    rootOptions: {
+      onCaughtError: (error, errorInfo) => handleRootCaughtError(error, errorInfo?.componentStack)
+    }
+  }
+};
 
-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 };
+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, handleRootCaughtError, installUncontainedErrorRelay, isSnapshotEnvironment, onlookBeforeAll, onlookContainmentDecorator, parameters, summarizeComponentStack };

package/dist/screenshot-service/index.js

@@ -141,6 +141,77 @@ async function closeBrowser() {
     console.error("Error closing browser:", error);
   }
 }
+
+// src/containment-contract/containment-contract.ts
+var ONLOOK_RENDER_STATE_ATTR = "data-onlook-render-state";
+var ONLOOK_CONTAINED_CARD_ATTR = "data-onlook-contained-card";
+
+// src/screenshot-service/utils/screenshot/screenshot.ts
+function classifyPreviewSnapshot(s) {
+  if (s.text.includes("Sorry, something went wrong")) return "errored";
+  if (s.text.includes("Couldn't find story")) return "errored";
+  if (s.hasContainedCard) return "contained";
+  if (s.renderStateAttr === "contained") return "contained";
+  if (s.renderStateAttr === "rendered") return "rendered";
+  if (s.text.length > 0) return "rendered";
+  if (s.hasSizedElement) return "rendered";
+  return "pending";
+}
+async function detectRenderState(page, opts = {}) {
+  const pollMs = opts.pollMs ?? 250;
+  const settleMs = opts.settleMs ?? 4e3;
+  const blankStablePolls = opts.blankStablePolls ?? 6;
+  const hardCapMs = opts.hardCapMs ?? 2e4;
+  const now = opts.now ?? Date.now;
+  const start = now();
+  let emptyStreak = 0;
+  const snapshot = () => page.evaluate(
+    ({ stateAttr, cardAttr }) => {
+      const root = document.getElementById("storybook-root") ?? document.body;
+      const text = (root?.textContent ?? "").trim();
+      let hasSizedElement = false;
+      if (root) {
+        const all = root.querySelectorAll("*");
+        for (let i = 0; i < all.length; i++) {
+          const rect = all[i]?.getBoundingClientRect();
+          if (rect && rect.width > 0 && rect.height > 0) {
+            hasSizedElement = true;
+            break;
+          }
+        }
+      }
+      return {
+        text,
+        hasContainedCard: Boolean(root?.querySelector(`[${cardAttr}]`)),
+        renderStateAttr: root?.getAttribute(stateAttr) ?? null,
+        hasSizedElement
+      };
+    },
+    { stateAttr: ONLOOK_RENDER_STATE_ATTR, cardAttr: ONLOOK_CONTAINED_CARD_ATTR }
+  );
+  while (true) {
+    let state;
+    let threw = false;
+    try {
+      state = classifyPreviewSnapshot(await snapshot());
+    } catch {
+      state = "pending";
+      threw = true;
+    }
+    if (state === "rendered" || state === "contained" || state === "errored") {
+      return state;
+    }
+    const elapsed = now() - start;
+    if (threw) {
+      emptyStreak = 0;
+    } else if (elapsed >= settleMs) {
+      emptyStreak += 1;
+      if (emptyStreak >= blankStablePolls) return "blank";
+    }
+    if (elapsed >= hardCapMs) return "timedOut";
+    await page.waitForTimeout(pollMs);
+  }
+}
 function getScreenshotPath(storyId, theme) {
   const storyDir = path.join(SCREENSHOTS_DIR, storyId);
   return path.join(storyDir, `${theme}.png`);
@@ -149,7 +220,7 @@ function screenshotExists(storyId, theme) {
   const screenshotPath = getScreenshotPath(storyId, theme);
   return fs.existsSync(screenshotPath);
 }
-async function captureScreenshotBuffer(storyId, theme, width = VIEWPORT_WIDTH, height = VIEWPORT_HEIGHT, storybookUrl = "http://localhost:6006", timeoutMs = 3e4) {
+async function captureScreenshotBuffer(storyId, theme, width = VIEWPORT_WIDTH, height = VIEWPORT_HEIGHT, storybookUrl = "http://localhost:6006", loadTimeoutMs = 9e4, renderTimeoutMs = 2e4) {
   const browser = await getBrowser();
   const context = await browser.newContext({
     viewport: { width, height },
@@ -158,13 +229,14 @@ async function captureScreenshotBuffer(storyId, theme, width = VIEWPORT_WIDTH, h
   const page = await context.newPage();
   try {
     const url = `${storybookUrl}/iframe.html?id=${storyId}&viewMode=story&globals=theme:${theme}`;
-    await page.goto(url, { timeout: timeoutMs });
-    await page.waitForLoadState("domcontentloaded", { timeout: timeoutMs });
-    await page.waitForLoadState("load", { timeout: timeoutMs });
+    await page.goto(url, { timeout: loadTimeoutMs });
+    await page.waitForLoadState("domcontentloaded", { timeout: loadTimeoutMs });
+    await page.waitForLoadState("load", { timeout: loadTimeoutMs });
     try {
       await page.waitForLoadState("networkidle", { timeout: 5e3 });
     } catch {
     }
+    const renderState = await detectRenderState(page, { hardCapMs: renderTimeoutMs });
     await page.evaluate(() => document.fonts.ready);
     try {
       await page.evaluate(async () => {
@@ -226,7 +298,7 @@ async function captureScreenshotBuffer(storyId, theme, width = VIEWPORT_WIDTH, h
     } else {
       screenshotBuffer = await page.screenshot({ type: "png" });
     }
-    return { buffer: screenshotBuffer, boundingBox: resultBoundingBox };
+    return { buffer: screenshotBuffer, boundingBox: resultBoundingBox, renderState };
   } finally {
     await context.close();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlook/storybook-plugin",
-  "version": "0.4.0-beta.11",
+  "version": "0.4.0-beta.13",
   "type": "module",
   "bin": {
     "onlook-storybook": "./dist/cli/index.js"
@@ -10,6 +10,7 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./package.json": "./package.json",
     "./preset": {
       "types": "./dist/preset/index.d.ts",
       "default": "./dist/preset/index.js"