@codeyam-editor/codeyam-editor 0.1.0 → 0.1.2

package/npm/scenario-playwright.js

@@ -0,0 +1,355 @@
+const {
+  hasLoadingMarkers,
+  shouldStopWaitingForImages,
+} = require("./scenario-metrics");
+const fs = require("fs");
+
+// PROTOTYPE (improve35 capture diagnostics): append a per-phase timing line to
+// a file so we can see WHERE a slow/timed-out capture spends its budget — even
+// when the editor kills this script on timeout (stderr is lost then, but the
+// file survives because each line is flushed synchronously). The cwd is the
+// project dir (scenario_check.rs sets `.current_dir(project_dir)`), so this
+// lands at `<project>/.codeyam/logs/capture-timing.log`. Diagnostics only —
+// never throws, never affects the capture result.
+function logCaptureTiming(phase, data) {
+  try {
+    const line = `[${new Date().toISOString()}] [capture-timing] phase=${phase} ${JSON.stringify(
+      data,
+    )}\n`;
+    fs.appendFileSync(".codeyam/logs/capture-timing.log", line);
+  } catch (_) {
+    /* diagnostics must never break a capture */
+  }
+}
+
+const net = require("net");
+
+// Resolve a URL to the TCP {host, port} a pre-flight connect should target, or
+// null when there is nothing to pre-check — an unparseable URL, or a non-http(s)
+// target like `data:`/blank that the capture renders with no network origin.
+// Pure (no socket) so the parse, protocol gate, and default-port rules are
+// unit-tested without opening a connection.
+function resolveTcpTarget(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch (_) {
+    return null;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+  return {
+    host: parsed.hostname,
+    port: Number(parsed.port) || (parsed.protocol === "https:" ? 443 : 80),
+  };
+}
+
+// Fast pre-flight (improve35): is anything accepting TCP on the app port? A
+// refused connection (the editor's reverse proxy is down) fails in milliseconds;
+// without this, the iframe's `waitForLoadState("load")` hangs the FULL 30s on a
+// dead origin (the observed capture failure — capture-timing showed
+// navigate-iframe elapsedMs=30004, status=null). A connection that ACCEPTS is
+// good enough to proceed — a slow HTTP response *after* connect is a cold
+// compile, handled by the normal load wait + the editor's retry. So we only bail
+// on a hard refusal/timeout, never on slowness.
+async function assertAppPortReachable(url, { timeoutMs = 2500 } = {}) {
+  const target = resolveTcpTarget(url);
+  if (!target) return; // non-http target (data:, blank) — nothing to pre-check
+  const { host, port } = target;
+  const started = Date.now();
+  await new Promise((resolve, reject) => {
+    const socket = net.connect({ host, port });
+    const finish = (err) => {
+      socket.destroy();
+      const elapsedMs = Date.now() - started;
+      logCaptureTiming("app-port-reachable", {
+        host,
+        port,
+        reachable: !err,
+        elapsedMs,
+        error: err ? err.message : null,
+      });
+      if (err) reject(err);
+      else resolve();
+    };
+    socket.setTimeout(timeoutMs, () =>
+      finish(
+        new Error(
+          `app port unreachable: TCP connect to ${host}:${port} timed out after ${timeoutMs}ms — the editor's reverse proxy is not accepting connections (proxy down?)`,
+        ),
+      ),
+    );
+    socket.once("connect", () => finish());
+    socket.once("error", (e) =>
+      finish(
+        new Error(
+          `app port unreachable: ${host}:${port} ${e.code || e.message} — is the editor's reverse proxy up? (a capture cannot render a dead app port)`,
+        ),
+      ),
+    );
+  });
+}
+
+function escapeHtmlAttribute(value) {
+  return String(value).replaceAll("&", "&amp;").replaceAll('"', "&quot;");
+}
+
+// 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 ? document.body.innerText.trim().length : 0,
+      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);
+  const incompleteSrcs = images
+    .filter((img) => !img || img.complete !== true || !(img.naturalWidth > 0))
+    .map((img) => (img && img.src) || "")
+    .slice(0, 6);
+  logCaptureTiming("images-settled", {
+    elapsedMs,
+    settled: allComplete,
+    total: images.length,
+    incompleteCount: incompleteSrcs.length,
+    incompleteSrcs,
+    overallTimeoutMs,
+  });
+  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 };
+}
+
+// `loadingMarkers` are the project's app-specific loading strings (from
+// stack.json `capture.loadingMarkers`); they extend the codeyam-harness
+// defaults so a stable-but-still-loading app screen counts as "not ready"
+// and the loop keeps waiting instead of capturing the loading flash.
+async function waitForStablePage(page, target, timeoutMs = 10000, loadingMarkers = []) {
+  const started = Date.now();
+  let lastHtml = "";
+  let stableCount = 0;
+  let lastHadLoadingMarkers = false;
+  let lastHtmlChanged = false;
+
+  while (Date.now() - started < timeoutMs) {
+    await page.waitForTimeout(500);
+
+    const pageState = await target.evaluate(() => ({
+      bodyText: document.body?.innerText ?? "",
+      html: document.body?.innerHTML ?? "",
+    }));
+
+    lastHadLoadingMarkers = hasLoadingMarkers(pageState.bodyText, loadingMarkers);
+    lastHtmlChanged = pageState.html !== lastHtml;
+
+    if (!lastHadLoadingMarkers && !lastHtmlChanged) {
+      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() });
+        logCaptureTiming("stable-page", {
+          outcome: "stabilized",
+          elapsedMs: Date.now() - started,
+        });
+        return;
+      }
+    } else {
+      stableCount = 0;
+    }
+
+    lastHtml = pageState.html;
+  }
+  // Hit the cap without stabilizing — record WHY: a persistent loading marker
+  // (app stuck) vs HTML still mutating each poll (HMR / animation / re-render).
+  logCaptureTiming("stable-page", {
+    outcome: "timed-out",
+    elapsedMs: Date.now() - started,
+    timeoutMs,
+    lastHadLoadingMarkers,
+    lastHtmlStillChanging: lastHtmlChanged,
+  });
+}
+
+// `preflight` is injectable so unit tests that drive a mock page can stay
+// network-free; production callers use the default real reachability check.
+async function loadScenarioInIframe(
+  page,
+  url,
+  { background, preflight = assertAppPortReachable } = {},
+) {
+  await preflight(url);
+  const navStarted = Date.now();
+  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;
+  logCaptureTiming("navigate-iframe", {
+    elapsedMs: Date.now() - navStarted,
+    status: response ? response.status() : null,
+    url,
+  });
+  return { frame, response };
+}
+
+// Load the scenario as a top-level navigation instead of embedding it in
+// the iframe harness. A top-level document is a first-party context, so a
+// `SameSite=Lax` session cookie is sent on the navigation — which is what
+// auth-gated application routes need to render the authenticated page
+// rather than redirecting to /login. The returned `frame` is the page's
+// main frame so callers can treat it uniformly with the iframe path
+// (`frame.url()`, `frame.evaluate(...)`, `waitForStablePage(page, frame)`).
+async function loadScenarioTopLevel(
+  page,
+  url,
+  { preflight = assertAppPortReachable } = {},
+) {
+  await preflight(url);
+  const navStarted = Date.now();
+  const response = await page.goto(url, {
+    waitUntil: "load",
+    timeout: 30000,
+  });
+  logCaptureTiming("navigate-toplevel", {
+    elapsedMs: Date.now() - navStarted,
+    status: response ? response.status() : null,
+    url,
+  });
+  return { frame: page.mainFrame(), response };
+}
+
+module.exports = {
+  logCaptureTiming,
+  resolveTcpTarget,
+  assertAppPortReachable,
+  escapeHtmlAttribute,
+  buildIframeHarness,
+  collectContentState,
+  collectImageStates,
+  waitForImagesSettled,
+  waitForAnimationsSettled,
+  waitForStablePage,
+  loadScenarioInIframe,
+  loadScenarioTopLevel,
+};