@codeyam-editor/codeyam-editor 0.1.1 → 0.1.3

package/npm/scenario-playwright.js

@@ -2,6 +2,92 @@ 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;");
@@ -62,7 +148,7 @@ async function collectContentState(target) {
       }
     }
     return {
-      bodyTextLength: document.body.innerText.trim().length,
+      bodyTextLength: document.body ? document.body.innerText.trim().length : 0,
       rootChildCount: root ? root.childElementCount : 0,
       rootTextLength: root ? (root.textContent || "").trim().length : 0,
       imageCount: imgs.length,
@@ -99,6 +185,18 @@ async function waitForImagesSettled(
   }
   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 };
 }
 
@@ -121,20 +219,122 @@ async function waitForAnimationsSettled(
   return { settled: false, elapsedMs: Date.now() - started };
 }
 
-async function waitForStablePage(page, target, timeoutMs = 10000) {
+// Track in-flight network requests on a Playwright page so a capture can wait
+// for client-side data fetches to settle before screenshotting. The
+// resource-timing API (`performance.getEntriesByType("resource")`) only records
+// COMPLETED requests, so it cannot see a fetch that is still in flight — the
+// exact window where a client-fetch page shows a loading skeleton. We count
+// request starts against finishes/failures instead. Returns a live view:
+// `inFlight()` is the current outstanding count and `lastActivityMs()` is the
+// timestamp of the most recent request start OR completion (0 when the page has
+// made no requests since the tracker attached). Attach BEFORE navigation so
+// every request is counted. Stack-agnostic — it observes raw HTTP activity, not
+// any framework's fetch wrapper.
+function createNetworkTracker(page) {
+  let inFlight = 0;
+  let lastActivityMs = 0;
+  const bump = () => {
+    lastActivityMs = Date.now();
+  };
+  if (page && typeof page.on === "function") {
+    page.on("request", () => {
+      inFlight += 1;
+      bump();
+    });
+    const settle = () => {
+      inFlight = Math.max(0, inFlight - 1);
+      bump();
+    };
+    page.on("requestfinished", settle);
+    page.on("requestfailed", settle);
+  }
+  return {
+    inFlight: () => inFlight,
+    lastActivityMs: () => lastActivityMs,
+  };
+}
+
+// Bounded network-quiet wait: after the DOM is stable a client-side data fetch
+// can still be in flight — the loading skeleton is gone but the fetched rows
+// haven't replaced it yet, so a screenshot here catches the in-between frame.
+// Wait until no request has been outstanding for `quietWindowMs`, hard-capped at
+// `overallTimeoutMs`. Two properties matter:
+//   - A page that made NO requests (lastActivityMs stays 0) is already quiet and
+//     returns on the first poll, so server-rendered captures incur no extra wait.
+//   - A streaming / long-poll endpoint that never goes idle hits the cap and the
+//     caller captures anyway — the wait can never hang the capture.
+async function waitForNetworkQuiet(
+  tracker,
+  { quietWindowMs = 500, overallTimeoutMs = 5000, pollIntervalMs = 100 } = {},
+) {
+  const started = Date.now();
+  while (Date.now() - started < overallTimeoutMs) {
+    const idleForMs = Date.now() - tracker.lastActivityMs();
+    if (tracker.inFlight() === 0 && idleForMs >= quietWindowMs) {
+      const elapsedMs = Date.now() - started;
+      logCaptureTiming("network-quiet", { outcome: "quiet", elapsedMs });
+      return { quiet: true, elapsedMs };
+    }
+    await new Promise((r) => setTimeout(r, pollIntervalMs));
+  }
+  const elapsedMs = Date.now() - started;
+  logCaptureTiming("network-quiet", {
+    outcome: "capped",
+    elapsedMs,
+    inFlight: tracker.inFlight(),
+  });
+  return { quiet: false, elapsedMs };
+}
+
+// `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,
-    }));
+    const pageState = await target.evaluate(() => {
+      const getById = document.getElementById;
+      const root =
+        typeof getById === "function" ? document.getElementById("root") : null;
+      return {
+        bodyText: document.body?.innerText ?? "",
+        html: document.body?.innerHTML ?? "",
+        // Whether the SPA mount point exists AND has painted anything. An
+        // existing-but-empty `<div id="root">` is the pre-paint window of a
+        // slow-first-paint scenario (e.g. a live-session app that spends a few
+        // seconds connecting before the gate UI mounts). `rootExists` lets us
+        // distinguish that from a mid-redirect/teardown `null` body, where
+        // there is no root to wait on and a stable-empty page is legitimately
+        // settled.
+        rootExists: !!root,
+        rootChildCount: root ? root.childElementCount : 0,
+      };
+    });
+
+    lastHadLoadingMarkers = hasLoadingMarkers(pageState.bodyText, loadingMarkers);
+    lastHtmlChanged = pageState.html !== lastHtml;
 
-    if (!hasLoadingMarkers(pageState.bodyText) && pageState.html === lastHtml) {
+    // A mounted-but-unpainted root is "still loading", not "settled": the HTML
+    // can sit byte-stable for a second or two while the SPA boots, which would
+    // otherwise satisfy the stability check and capture a blank frame before
+    // first paint. Treat an existing root with zero children AND no body text
+    // as not-ready so the loop keeps polling until the app actually paints (or
+    // the overall timeout fires, by which point real content is present). A
+    // `null` body (rootExists=false) is unaffected — it stays trivially stable.
+    const rootUnpainted =
+      pageState.rootExists &&
+      pageState.rootChildCount === 0 &&
+      (pageState.bodyText ?? "").trim().length === 0;
+
+    if (!lastHadLoadingMarkers && !lastHtmlChanged && !rootUnpainted) {
       stableCount += 1;
       if (stableCount >= 2) {
         const remaining = () => Math.max(0, timeoutMs - (Date.now() - started));
@@ -142,6 +342,10 @@ async function waitForStablePage(page, target, timeoutMs = 10000) {
           timeoutMs: Math.min(2000, remaining()),
         });
         await waitForImagesSettled(target, { overallTimeoutMs: remaining() });
+        logCaptureTiming("stable-page", {
+          outcome: "stabilized",
+          elapsedMs: Date.now() - started,
+        });
         return;
       }
     } else {
@@ -150,9 +354,26 @@ async function waitForStablePage(page, target, timeoutMs = 10000) {
 
     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,
+  });
 }
 
-async function loadScenarioInIframe(page, url, { background } = {}) {
+// `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) =>
@@ -177,16 +398,137 @@ async function loadScenarioInIframe(page, url, { background } = {}) {
 
   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 };
+}
+
+// Collect up to 20 distinct visible labels of interactive elements on the
+// page — buttons, links, role=button, form controls, <summary>, and anything
+// with an onclick. Used to build an ACTIONABLE error when an interaction's
+// target matches nothing: the agent reliably knows a label it rendered, so
+// listing the real candidates turns a silent blank capture into a "did you
+// mean one of these?" hint. Pure read (no clicks); falls back to value /
+// aria-label / placeholder when an element has no text.
+async function collectInteractiveLabels(frame) {
+  return frame.evaluate(() => {
+    const selector =
+      "button, a[href], [role=button], input, select, textarea, summary, [onclick]";
+    const nodes = Array.from(document.querySelectorAll(selector));
+    const labels = nodes
+      .map((node) => {
+        const text =
+          (node.innerText || node.textContent || "").trim() ||
+          (typeof node.value === "string" ? node.value.trim() : "") ||
+          (node.getAttribute && node.getAttribute("aria-label")) ||
+          (node.getAttribute && node.getAttribute("placeholder")) ||
+          "";
+        return String(text).trim();
+      })
+      .filter((label) => label.length > 0);
+    return Array.from(new Set(labels)).slice(0, 20);
+  });
+}
+
+// Drive a single user-style interaction against the settled frame before the
+// screenshot, so an interactive state (expanded accordion, open modal, filled
+// field) can be captured without editing app source.
+//
+// The target is matched by visible `text` (preferred — the agent reliably
+// knows the label it rendered) or a CSS `selector`. `action` is click / fill /
+// press; `value` carries the text for `fill` or the key for `press` (e.g.
+// `Enter`). On a no-match target this THROWS with the list of candidate
+// interactive labels — the capture script's outer catch turns that into a
+// failed capture with an actionable message, never a silent blank screenshot.
+async function performInteraction(frame, interaction, { timeoutMs = 5000 } = {}) {
+  const { action, selector, text, value } = interaction || {};
+
+  let locator;
+  let targetDesc;
+  if (typeof text === "string" && text.length > 0) {
+    locator = frame.getByText(text, { exact: false }).first();
+    targetDesc = `text "${text}"`;
+  } else if (typeof selector === "string" && selector.length > 0) {
+    locator = frame.locator(selector).first();
+    targetDesc = `selector "${selector}"`;
+  } else {
+    throw new Error(
+      "preview-interact: interaction requires a `text` or `selector` target",
+    );
+  }
+
+  const matchCount = await locator.count();
+  if (matchCount === 0) {
+    const candidates = await collectInteractiveLabels(frame);
+    const candidateList =
+      candidates.length > 0 ? candidates.join(", ") : "(none found on page)";
+    throw new Error(
+      `preview-interact: no element matched ${targetDesc}. ` +
+        `Candidate interactive labels: ${candidateList}`,
+    );
+  }
+
+  switch (action) {
+    case "click":
+      await locator.click({ timeout: timeoutMs });
+      break;
+    case "fill":
+      await locator.fill(value ?? "", { timeout: timeoutMs });
+      break;
+    case "press":
+      await locator.press(value || "Enter", { timeout: timeoutMs });
+      break;
+    default:
+      throw new Error(
+        `preview-interact: unknown action "${action}" (expected click | fill | press)`,
+      );
+  }
+}
+
 module.exports = {
+  logCaptureTiming,
+  resolveTcpTarget,
+  assertAppPortReachable,
   escapeHtmlAttribute,
   buildIframeHarness,
   collectContentState,
   collectImageStates,
   waitForImagesSettled,
   waitForAnimationsSettled,
+  createNetworkTracker,
+  waitForNetworkQuiet,
   waitForStablePage,
   loadScenarioInIframe,
+  loadScenarioTopLevel,
+  collectInteractiveLabels,
+  performInteraction,
 };