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

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.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.js

@@ -77,6 +77,8 @@ function componentLocPlugin(options = {}) {
 // src/containment-contract/containment-contract.ts
 var ONLOOK_CONTAINED_MODULES_GLOBAL = "__ONLOOK_CONTAINED_MODULES__";
 var ONLOOK_CONTAINED_PROP = "__onlookContained";
+var ONLOOK_RENDER_STATE_ATTR = "data-onlook-render-state";
+var ONLOOK_CONTAINED_CARD_ATTR = "data-onlook-contained-card";
 
 // src/env-containment/env-containment.ts
 var ENV_CONTAINMENT_PLUGIN_NAME = "onlook-env-containment";
@@ -386,11 +388,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 +466,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 +535,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 +856,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 +868,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 +900,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 +1232,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/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.12",
   "type": "module",
   "bin": {
     "onlook-storybook": "./dist/cli/index.js"