@codeyam-editor/codeyam-editor 0.1.0-staging.46bd02f → 0.1.0-staging.c9412f0

package/npm/editor.js

@@ -24,7 +24,21 @@ const VITE_PORT = 5173;
 const VITE_INTERNAL_PORT = VITE_PORT + 1;
 const shouldRestart = process.argv.includes("--restart");
 
+function buildBinary() {
+  console.error("Building Rust binary...");
+  try {
+    execSync("cargo build", { stdio: "inherit", cwd: rootDir });
+  } catch {
+    console.error("Failed to build Rust binary. Continuing with existing build (if any)...");
+  }
+}
+
 async function main() {
+  // Rebuild the Rust binary so code changes are picked up on restart.
+  // This script is only invoked from a source checkout (via `npm run editor`),
+  // so Cargo.toml and the crates tree are always present.
+  buildBinary();
+
   // Build the UI so the backend can serve it as static files
   console.error("Building UI...");
   try {

package/npm/scenario-check.js

@@ -1,322 +1,92 @@
 #!/usr/bin/env node
 
+// Render environment (colorScheme, deviceScaleFactor, userAgent, locale,
+// timezoneId, reduceMotion, forcedColors) is read from config when present
+// and passed to browser.newContext(). This is what makes screenshots match
+// the Live Preview iframe's host browser — see docs/rendering.md.
+//
+// iframeBackground is forwarded to buildIframeHarness so the capture paints
+// the user's editor-shell background (or whatever the UI detected) behind
+// the iframe instead of a hardcoded white.
+
 const fs = require("fs");
 const path = require("path");
 const { chromium } = require("playwright");
 
-const LOADING_MARKERS = [
-  "Loading scenario...",
-  "Loading tests...",
-  "Loading scenarios...",
-  "disconnected",
-];
-
-function hasLoadingMarkers(text) {
-  return LOADING_MARKERS.some((marker) => text.includes(marker));
-}
-
-function hasRenderableContent(state) {
-  return Boolean(
-    state &&
-      (state.rootChildCount > 0 ||
-        state.rootTextLength > 0 ||
-        state.bodyTextLength > 0),
-  );
-}
-
-const ERROR_PATTERNS = [
-  "not found in registry",
-  "Component not found",
-  "Scenario Error",
-];
-
-function hasErrorPatterns(text) {
-  return ERROR_PATTERNS.some((pattern) => text.includes(pattern));
-}
-
-function createIssue(kind, message, extra = {}) {
-  return {
-    kind,
-    message,
-    url: extra.url ?? null,
-    status: extra.status ?? null,
-  };
-}
-
-function pushIssue(issues, issue) {
-  const key = JSON.stringify(issue);
-  if (!issues.some((existing) => JSON.stringify(existing) === key)) {
-    issues.push(issue);
-  }
-}
-
-function escapeHtmlAttribute(value) {
-  return String(value)
-    .replaceAll("&", "&")
-    .replaceAll('"', """);
-}
-
-function buildIframeHarness(url) {
-  const escapedUrl = escapeHtmlAttribute(url);
-  return `<!doctype html>
-<html>
-  <head>
-    <meta charset="utf-8">
-    <style>
-      html, body {
-        margin: 0;
-        width: 100%;
-        height: 100%;
-        overflow: hidden;
-        background: #fff;
-      }
-
-      iframe {
-        display: block;
-        width: 100%;
-        height: 100%;
-        border: 0;
-        background: #fff;
-      }
-    </style>
-  </head>
-  <body>
-    <iframe id="scenario-frame" title="Scenario Preview" src="${escapedUrl}"></iframe>
-  </body>
-</html>`;
-}
-
-function buildResult({ loaded, hasContent, issues, outputPath, url }) {
-  return {
-    ok: loaded && hasContent && issues.length === 0,
-    loaded,
-    hasContent,
-    url,
-    outputPath: outputPath ?? null,
-    issues,
-  };
-}
-
-function normalizeMockCandidates(url) {
-  try {
-    const parsed = new URL(url);
-    return [url, `${parsed.pathname}${parsed.search}`, parsed.pathname];
-  } catch {
-    return [url];
-  }
-}
-
-function findHttpMock(httpMocks, request) {
-  const method = request.method().toUpperCase();
-  const candidates = normalizeMockCandidates(request.url());
-  for (const candidate of candidates) {
-    const key = `${method} ${candidate}`;
-    if (httpMocks[key]) {
-      return httpMocks[key];
-    }
-  }
-  return null;
-}
-
-async function attachHttpMocks(page, httpMocks) {
-  if (!httpMocks || Object.keys(httpMocks).length === 0) return;
-
-  await page.route("**/*", async (route) => {
-    const mock = findHttpMock(httpMocks, route.request());
-    if (!mock) {
-      await route.continue();
-      return;
-    }
-
-    const headers = { ...(mock.headers || {}) };
-    let body;
-    if (mock.body !== undefined) {
-      body =
-        typeof mock.body === "string" ? mock.body : JSON.stringify(mock.body);
-      const hasContentType = Object.keys(headers).some(
-        (key) => key.toLowerCase() === "content-type",
-      );
-      if (!hasContentType) {
-        headers["content-type"] = "application/json";
-      }
-    }
-
-    await route.fulfill({
-      status: mock.status || 200,
-      headers,
-      body,
-    });
-  });
-
-  // Disable the in-page fetch mock by returning an empty active-mocks.json.
-  // The HTML injects a script that synchronously loads this file and
-  // monkey-patches window.fetch, which would bypass Playwright's route
-  // interception. This route is registered AFTER **/* so it takes priority
-  // (Playwright uses LIFO ordering for route handlers).
-  await page.route("**/active-mocks.json", async (route) => {
-    await route.fulfill({
-      status: 200,
-      headers: { "content-type": "application/json" },
-      body: "[]",
-    });
-  });
-}
-
-async function collectContentState(target) {
-  return target.evaluate(() => {
-    const root = document.getElementById("root");
-    return {
-      bodyTextLength: document.body.innerText.trim().length,
-      rootChildCount: root ? root.childElementCount : 0,
-      rootTextLength: root ? (root.textContent || "").trim().length : 0,
-    };
-  });
-}
-
-async function waitForStablePage(page, target, timeoutMs = 10000) {
-  const started = Date.now();
-  let lastHtml = "";
-  let stableCount = 0;
-
-  while (Date.now() - started < timeoutMs) {
-    await page.waitForTimeout(500);
-
-    const pageState = await target.evaluate(() => ({
-      bodyText: document.body.innerText,
-      html: document.body.innerHTML,
-    }));
-
-    if (
-      !hasLoadingMarkers(pageState.bodyText) &&
-      pageState.html === lastHtml
-    ) {
-      stableCount += 1;
-      if (stableCount >= 2) return;
-    } else {
-      stableCount = 0;
-    }
-
-    lastHtml = pageState.html;
-  }
-}
+const {
+  findErrorPattern,
+  buildErrorContextSnippet,
+  hasRenderableContent,
+  describeBlankReason,
+} = require("./scenario-metrics");
 
-async function loadScenarioInIframe(page, url) {
-  const responsePromise = page
-    .waitForResponse(
-      (response) =>
-        response.request().resourceType() === "document" &&
-        response.url() === url,
-      { timeout: 30000 },
-    )
-    .catch(() => null);
+const {
+  createIssue,
+  pushIssue,
+  buildResult,
+} = require("./scenario-issues");
 
-  await page.setContent(buildIframeHarness(url), { waitUntil: "domcontentloaded" });
+const {
+  attachHttpMocks,
+} = require("./scenario-mocks");
 
-  const frameHandle = await page.waitForSelector("#scenario-frame", {
-    state: "attached",
-    timeout: 30000,
-  });
-  const frame = await frameHandle.contentFrame();
-  if (!frame) {
-    throw new Error("Scenario iframe did not attach");
-  }
+const {
+  loadScenarioInIframe,
+  waitForStablePage,
+  collectContentState,
+} = require("./scenario-playwright");
 
-  await frame.waitForLoadState("load", { timeout: 30000 });
-  const response = await responsePromise;
-  return { frame, response };
-}
+const {
+  getInitScript,
+  handleConsoleMessage,
+  handlePageError,
+  handleRequestFailed,
+} = require("./scenario-handlers");
 
 async function runScenarioCheck(config) {
   const { url, outputPath, width, height, httpMocks = {} } = config;
   const issues = [];
   const browser = await chromium.launch();
-  const context = await browser.newContext({
+  const contextOptions = {
     viewport: { width: width || 1440, height: height || 900 },
-  });
+  };
+  if (config.colorScheme) contextOptions.colorScheme = config.colorScheme;
+  if (config.deviceScaleFactor)
+    contextOptions.deviceScaleFactor = config.deviceScaleFactor;
+  if (config.userAgent) contextOptions.userAgent = config.userAgent;
+  if (config.locale) contextOptions.locale = config.locale;
+  if (config.timezoneId) contextOptions.timezoneId = config.timezoneId;
+  if (config.reduceMotion) contextOptions.reducedMotion = config.reduceMotion;
+  if (config.forcedColors) contextOptions.forcedColors = config.forcedColors;
+  const context = await browser.newContext(contextOptions);
 
   // Context-level init script runs in ALL frames (including cross-origin iframes)
-  await context.addInitScript(() => {
-    window.__codeyamUnhandledRejections = [];
-    window.addEventListener("unhandledrejection", (event) => {
-      const reason = event.reason;
-      const message =
-        reason instanceof Error ? reason.message : String(reason);
-      window.__codeyamUnhandledRejections.push(message);
-    });
-
-    // Stub WebSocket during capture to prevent terminal reconnection spam.
-    // Returns an object that behaves like a closed WebSocket — the terminal
-    // will attempt to reconnect a few times then give up silently.
-    window.WebSocket = class StubWebSocket {
-      static CONNECTING = 0;
-      static OPEN = 1;
-      static CLOSING = 2;
-      static CLOSED = 3;
-      readyState = 3;
-      onopen = null;
-      onclose = null;
-      onerror = null;
-      onmessage = null;
-      send() {}
-      close() {}
-      addEventListener() {}
-      removeEventListener() {}
-      dispatchEvent() { return false; }
-      constructor() {
-        // Fire onerror then onclose on next tick so the terminal sees a failed connection
-        setTimeout(() => {
-          if (this.onerror) this.onerror(new Event("error"));
-          if (this.onclose) this.onclose(new CloseEvent("close"));
-        }, 0);
-      }
-    };
-  });
+  await context.addInitScript(getInitScript());
 
   const page = await context.newPage();
   await attachHttpMocks(page, httpMocks);
 
   page.on("pageerror", (error) => {
-    pushIssue(
-      issues,
-      createIssue("pageerror", error.message || String(error), {
-        url: page.url() || url,
-      }),
-    );
+    pushIssue(issues, handlePageError(error));
   });
 
   page.on("console", (message) => {
-    if (message.type() !== "error") return;
-    const text = message.text();
-    // Ignore known dev-server WebSocket/HMR errors from Vite proxy
-    if (
-      text.includes("WebSocket connection to") ||
-      text.includes("Unsupported Media Type")
-    ) {
-      return;
+    const issue = handleConsoleMessage(message);
+    if (issue) {
+      pushIssue(issues, issue);
     }
-    pushIssue(
-      issues,
-      createIssue("console", text, {
-        url: page.url() || url,
-      }),
-    );
   });
 
   page.on("requestfailed", (request) => {
-    pushIssue(
-      issues,
-      createIssue(
-        "requestfailed",
-        request.failure()?.errorText || "Request failed",
-        { url: request.url() },
-      ),
-    );
+    pushIssue(issues, handleRequestFailed(request));
   });
 
   let loaded = false;
 
   try {
-    const { frame, response } = await loadScenarioInIframe(page, url);
+    const { frame, response } = await loadScenarioInIframe(page, url, {
+      background: config.iframeBackground,
+    });
     loaded = true;
 
     if (response && response.status() >= 400) {
@@ -349,20 +119,30 @@ async function runScenarioCheck(config) {
     if (!hasContent) {
       pushIssue(
         issues,
-        createIssue("blank", "Page rendered no visible content", {
-          url: page.url() || url,
-        }),
+        createIssue(
+          "blank",
+          `Page rendered no visible content (${describeBlankReason(contentState)})`,
+          { url: page.url() || url },
+        ),
       );
     }
 
     // Check for known error states in the rendered content
     const bodyText = await frame.evaluate(() => document.body.innerText || "");
-    if (hasErrorPatterns(bodyText)) {
+    const matchedPattern = findErrorPattern(bodyText);
+    if (matchedPattern) {
+      const contextSnippet = buildErrorContextSnippet(bodyText, matchedPattern);
       pushIssue(
         issues,
-        createIssue("error-state", `Page contains error content: ${bodyText.slice(0, 200)}`, {
-          url: page.url() || url,
-        }),
+        createIssue(
+          "error-state",
+          `Page contains error content (matched "${matchedPattern}"): ${contextSnippet ?? bodyText.slice(0, 200)}`,
+          {
+            url: page.url() || url,
+            matchedPattern,
+            contextSnippet,
+          },
+        ),
       );
     }
 
@@ -411,19 +191,7 @@ async function main() {
 }
 
 module.exports = {
-  attachHttpMocks,
-  buildResult,
-  buildIframeHarness,
-  createIssue,
-  findHttpMock,
-  hasErrorPatterns,
-  hasLoadingMarkers,
-  hasRenderableContent,
-  loadScenarioInIframe,
-  normalizeMockCandidates,
-  pushIssue,
   runScenarioCheck,
-  waitForStablePage,
 };
 
 if (require.main === module) {

package/npm/scenario-handlers.js

@@ -0,0 +1,71 @@
+const { createIssue } = require("./scenario-issues");
+
+function getInitScript() {
+  return `
+    window.__codeyamUnhandledRejections = [];
+    window.addEventListener("unhandledrejection", (event) => {
+      const reason = event.reason;
+      const message =
+        reason instanceof Error ? reason.message : String(reason);
+      window.__codeyamUnhandledRejections.push(message);
+    });
+
+    // Stub WebSocket during capture to prevent terminal reconnection spam.
+    window.WebSocket = class StubWebSocket {
+      static CONNECTING = 0;
+      static OPEN = 1;
+      static CLOSING = 2;
+      static CLOSED = 3;
+      readyState = 3;
+      onopen = null;
+      onclose = null;
+      onerror = null;
+      onmessage = null;
+      send() {}
+      close() {}
+      addEventListener() {}
+      removeEventListener() {}
+      dispatchEvent() { return false; }
+      constructor() {
+        setTimeout(() => {
+          if (this.onerror) this.onerror(new Event("error"));
+          if (this.onclose) this.onclose(new CloseEvent("close"));
+        }, 0);
+      }
+    };
+  `;
+}
+
+function handleConsoleMessage(message) {
+  if (message.type() !== "error") return null;
+  const text = message.text();
+  
+  // Ignore known dev-server WebSocket/HMR errors from Vite proxy
+  if (
+    text.includes("WebSocket connection to") ||
+    text.includes("Unsupported Media Type")
+  ) {
+    return null;
+  }
+
+  return createIssue("console", text);
+}
+
+function handlePageError(error) {
+  return createIssue("pageerror", error.message || String(error));
+}
+
+function handleRequestFailed(request) {
+  return createIssue(
+    "requestfailed",
+    request.failure()?.errorText || "Request failed",
+    { url: request.url() }
+  );
+}
+
+module.exports = {
+  getInitScript,
+  handleConsoleMessage,
+  handlePageError,
+  handleRequestFailed,
+};

package/npm/scenario-issues.js

@@ -0,0 +1,35 @@
+function createIssue(kind, message, extra = {}) {
+  const issue = {
+    kind,
+    message,
+    url: extra.url ?? null,
+    status: extra.status ?? null,
+  };
+  if (extra.matchedPattern != null) issue.matchedPattern = extra.matchedPattern;
+  if (extra.contextSnippet != null) issue.contextSnippet = extra.contextSnippet;
+  return issue;
+}
+
+function pushIssue(issues, issue) {
+  const key = JSON.stringify(issue);
+  if (!issues.some((existing) => JSON.stringify(existing) === key)) {
+    issues.push(issue);
+  }
+}
+
+function buildResult({ loaded, hasContent, issues, outputPath, url }) {
+  return {
+    ok: loaded && hasContent && issues.length === 0,
+    loaded,
+    hasContent,
+    url,
+    outputPath: outputPath ?? null,
+    issues,
+  };
+}
+
+module.exports = {
+  createIssue,
+  pushIssue,
+  buildResult,
+};

package/npm/scenario-metrics.js

@@ -0,0 +1,94 @@
+const LOADING_MARKERS = [
+  "Loading scenario...",
+  "Loading tests...",
+  "Loading scenarios...",
+  "disconnected",
+];
+
+function hasLoadingMarkers(text) {
+  return LOADING_MARKERS.some((marker) => text.includes(marker));
+}
+
+function hasRenderableContent(state) {
+  if (!state) return false;
+  if (
+    state.rootChildCount > 0 ||
+    state.rootTextLength > 0 ||
+    state.bodyTextLength > 0
+  ) {
+    return true;
+  }
+  if ((state.loadedImageCount || 0) > 0) return true;
+  if ((state.mediaBboxCount || 0) > 0) return true;
+  return false;
+}
+
+function describeBlankReason(state) {
+  if (!state) return "no content state collected";
+  const parts = [];
+  if (!(state.bodyTextLength > 0)) {
+    parts.push("no text");
+  }
+  const imageCount = state.imageCount || 0;
+  const loadedImageCount = state.loadedImageCount || 0;
+  if (imageCount > 0 && loadedImageCount === 0) {
+    parts.push(`${imageCount} unloaded image${imageCount === 1 ? "" : "s"}`);
+  } else if (imageCount === 0) {
+    parts.push("no images");
+  }
+  if (!((state.mediaBboxCount || 0) > 0)) {
+    parts.push("no svg/canvas/video");
+  }
+  return parts.join(", ");
+}
+
+function shouldStopWaitingForImages(images, options = {}) {
+  const { elapsedMs = 0, overallTimeoutMs = 5000 } = options;
+  if (!Array.isArray(images) || images.length === 0) return true;
+  if (elapsedMs >= overallTimeoutMs) return true;
+  return images.every((img) => img && img.complete === true);
+}
+
+const ERROR_PATTERNS = [
+  "not found in registry",
+  "Component not found",
+  "Scenario Error",
+];
+
+function hasErrorPatterns(text) {
+  return ERROR_PATTERNS.some((pattern) => text.includes(pattern));
+}
+
+function findErrorPattern(text) {
+  if (!text) return null;
+  for (const pattern of ERROR_PATTERNS) {
+    if (text.includes(pattern)) return pattern;
+  }
+  return null;
+}
+
+const ERROR_CONTEXT_RADIUS = 60;
+
+function buildErrorContextSnippet(text, pattern) {
+  if (!text || !pattern) return null;
+  const index = text.indexOf(pattern);
+  if (index < 0) return null;
+  const start = Math.max(0, index - ERROR_CONTEXT_RADIUS);
+  const end = Math.min(text.length, index + pattern.length + ERROR_CONTEXT_RADIUS);
+  const slice = text.slice(start, end).replace(/\s+/g, " ").trim();
+  const prefix = start > 0 ? "…" : "";
+  const suffix = end < text.length ? "…" : "";
+  return `${prefix}${slice}${suffix}`;
+}
+
+module.exports = {
+  hasLoadingMarkers,
+  hasRenderableContent,
+  describeBlankReason,
+  shouldStopWaitingForImages,
+  hasErrorPatterns,
+  findErrorPattern,
+  buildErrorContextSnippet,
+  ERROR_PATTERNS,
+  ERROR_CONTEXT_RADIUS,
+};

package/npm/scenario-mocks.js

@@ -0,0 +1,70 @@
+function normalizeMockCandidates(url) {
+  try {
+    const parsed = new URL(url);
+    return [url, `${parsed.pathname}${parsed.search}`, parsed.pathname];
+  } catch {
+    return [url];
+  }
+}
+
+function findHttpMock(httpMocks, request) {
+  const method = request.method().toUpperCase();
+  const candidates = normalizeMockCandidates(request.url());
+  for (const candidate of candidates) {
+    const key = `${method} ${candidate}`;
+    if (httpMocks[key]) {
+      return httpMocks[key];
+    }
+  }
+  return null;
+}
+
+async function attachHttpMocks(page, httpMocks) {
+  if (!httpMocks || Object.keys(httpMocks).length === 0) return;
+
+  await page.route("**/*", async (route) => {
+    const mock = findHttpMock(httpMocks, route.request());
+    if (!mock) {
+      await route.continue();
+      return;
+    }
+
+    const headers = { ...(mock.headers || {}) };
+    let body;
+    if (mock.body !== undefined) {
+      body =
+        typeof mock.body === "string" ? mock.body : JSON.stringify(mock.body);
+      const hasContentType = Object.keys(headers).some(
+        (key) => key.toLowerCase() === "content-type",
+      );
+      if (!hasContentType) {
+        headers["content-type"] = "application/json";
+      }
+    }
+
+    await route.fulfill({
+      status: mock.status || 200,
+      headers,
+      body,
+    });
+  });
+
+  // Disable the in-page fetch mock by returning an empty active-mocks.json.
+  // The HTML injects a script that synchronously loads this file and
+  // monkey-patches window.fetch, which would bypass Playwright's route
+  // interception. This route is registered AFTER **/* so it takes priority
+  // (Playwright uses LIFO ordering for route handlers).
+  await page.route("**/active-mocks.json", async (route) => {
+    await route.fulfill({
+      status: 200,
+      headers: { "content-type": "application/json" },
+      body: "[]",
+    });
+  });
+}
+
+module.exports = {
+  normalizeMockCandidates,
+  findHttpMock,
+  attachHttpMocks,
+};

package/npm/scenario-playwright.js

@@ -0,0 +1,191 @@
+const {
+  hasLoadingMarkers,
+  shouldStopWaitingForImages,
+} = require("./scenario-metrics");
+
+function escapeHtmlAttribute(value) {
+  return String(value).replaceAll("&", "&").replaceAll('"', """);
+}
+
+// The harness background defaults to transparent so the iframe's own
+// <body> background paints through — matching what users see in the Live
+// Preview. Callers (via scenario-check.js) pass a concrete color when the
+// UI has detected a background it wants the capture to paint behind the
+// iframe, e.g. `var(--bg-deep)` from the editor shell.
+function buildIframeHarness(url, { background = "transparent" } = {}) {
+  const escapedUrl = escapeHtmlAttribute(url);
+  const bg = String(background);
+  return `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <style>
+      html, body {
+        margin: 0;
+        width: 100%;
+        height: 100%;
+        overflow: hidden;
+        background: ${bg};
+      }
+
+      iframe {
+        display: block;
+        width: 100%;
+        height: 100%;
+        border: 0;
+        background: ${bg};
+      }
+    </style>
+  </head>
+  <body>
+    <iframe id="scenario-frame" title="Scenario Preview" src="${escapedUrl}"></iframe>
+  </body>
+</html>`;
+}
+
+async function collectContentState(target) {
+  return target.evaluate(() => {
+    const root = document.getElementById("root");
+    const imgs = Array.from(document.images || []);
+    const loadedImageCount = imgs.filter(
+      (img) => img.complete && img.naturalWidth > 0,
+    ).length;
+    const mediaSelectors = ["svg", "canvas", "video"];
+    let mediaBboxCount = 0;
+    for (const selector of mediaSelectors) {
+      const nodes = document.querySelectorAll(selector);
+      for (const node of nodes) {
+        const rect = node.getBoundingClientRect();
+        if (rect.width > 0 && rect.height > 0) {
+          mediaBboxCount += 1;
+        }
+      }
+    }
+    return {
+      bodyTextLength: document.body.innerText.trim().length,
+      rootChildCount: root ? root.childElementCount : 0,
+      rootTextLength: root ? (root.textContent || "").trim().length : 0,
+      imageCount: imgs.length,
+      loadedImageCount,
+      mediaBboxCount,
+    };
+  });
+}
+
+async function collectImageStates(target) {
+  return target.evaluate(() =>
+    Array.from(document.images || []).map((img) => ({
+      complete: img.complete,
+      naturalWidth: img.naturalWidth,
+      src: img.currentSrc || img.src || "",
+    })),
+  );
+}
+
+async function waitForImagesSettled(
+  target,
+  { overallTimeoutMs = 5000, pollIntervalMs = 100 } = {},
+) {
+  const started = Date.now();
+  let images = await collectImageStates(target);
+  while (
+    !shouldStopWaitingForImages(images, {
+      elapsedMs: Date.now() - started,
+      overallTimeoutMs,
+    })
+  ) {
+    await new Promise((r) => setTimeout(r, pollIntervalMs));
+    images = await collectImageStates(target);
+  }
+  const elapsedMs = Date.now() - started;
+  const allComplete = images.every((img) => img && img.complete === true);
+  return { settled: allComplete, images, elapsedMs };
+}
+
+async function waitForAnimationsSettled(
+  target,
+  { timeoutMs = 2000, pollIntervalMs = 100 } = {},
+) {
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    const runningCount = await target.evaluate(() =>
+      document
+        .getAnimations()
+        .filter((a) => a.playState === "running").length,
+    );
+    if (runningCount === 0) {
+      return { settled: true, elapsedMs: Date.now() - started };
+    }
+    await new Promise((r) => setTimeout(r, pollIntervalMs));
+  }
+  return { settled: false, elapsedMs: Date.now() - started };
+}
+
+async function waitForStablePage(page, target, timeoutMs = 10000) {
+  const started = Date.now();
+  let lastHtml = "";
+  let stableCount = 0;
+
+  while (Date.now() - started < timeoutMs) {
+    await page.waitForTimeout(500);
+
+    const pageState = await target.evaluate(() => ({
+      bodyText: document.body.innerText,
+      html: document.body.innerHTML,
+    }));
+
+    if (!hasLoadingMarkers(pageState.bodyText) && pageState.html === lastHtml) {
+      stableCount += 1;
+      if (stableCount >= 2) {
+        const remaining = () => Math.max(0, timeoutMs - (Date.now() - started));
+        await waitForAnimationsSettled(target, {
+          timeoutMs: Math.min(2000, remaining()),
+        });
+        await waitForImagesSettled(target, { overallTimeoutMs: remaining() });
+        return;
+      }
+    } else {
+      stableCount = 0;
+    }
+
+    lastHtml = pageState.html;
+  }
+}
+
+async function loadScenarioInIframe(page, url, { background } = {}) {
+  const responsePromise = page
+    .waitForResponse(
+      (response) =>
+        response.request().resourceType() === "document" &&
+        response.url() === url,
+      { timeout: 30000 },
+    )
+    .catch(() => null);
+
+  await page.setContent(buildIframeHarness(url, { background }), {
+    waitUntil: "domcontentloaded",
+  });
+
+  const frameHandle = await page.waitForSelector("#scenario-frame", {
+    state: "attached",
+    timeout: 30000,
+  });
+  const frame = await frameHandle.contentFrame();
+  if (!frame) {
+    throw new Error("Scenario iframe did not attach");
+  }
+
+  await frame.waitForLoadState("load", { timeout: 30000 });
+  const response = await responsePromise;
+  return { frame, response };
+}
+
+module.exports = {
+  buildIframeHarness,
+  collectContentState,
+  collectImageStates,
+  waitForImagesSettled,
+  waitForAnimationsSettled,
+  waitForStablePage,
+  loadScenarioInIframe,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeyam-editor/codeyam-editor",
-  "version": "0.1.0-staging.46bd02f",
+  "version": "0.1.0-staging.c9412f0",
   "description": "Language-agnostic managed execution sandbox for scenario-driven development",
   "bin": {
     "codeyam-editor": "./npm/cli.js"