@codeyam-editor/codeyam-editor 0.1.1 → 0.1.2

package/npm/scenario-interactivity.js

@@ -0,0 +1,199 @@
+const fs = require("fs");
+const path = require("path");
+const { createIssue } = require("./scenario-issues");
+
+// Hydration / interactivity probe for the headless capture browser.
+//
+// Background: a page can return HTTP 200, render visible content, log no
+// console errors, and still be completely dead — the client framework never
+// hydrated, so every button and handler is inert. The status / render /
+// console / image gates all pass and the broken page sails through to the
+// user (the catalog whose filter buttons did nothing). This probe asserts the
+// page actually became interactive before the capture gate reports success,
+// so a non-hydrating page can no longer pass `client-errors`.
+//
+// Stack assumption: WHICH framework's hydration we look for is data-driven
+// from `.codeyam/stack.json` (or an explicit override) — never hardcoded into
+// the capture flow. Stacks with no client runtime (backend services, CLIs,
+// static HTML) are a documented no-op pass. Frameworks for which we have no
+// reliable in-page attachment signal are ALSO a conservative pass: we never
+// flag a page we cannot prove is dead, so a healthy Svelte / Solid / vanilla
+// page is never a false negative. A new framework detector is a new entry in
+// `detectors` below plus a `KNOWN_FRAMEWORKS` mapping — not an edit here.
+
+// Frameworks we have an in-page attachment detector for. Inference only
+// resolves to one of these; an unrecognised framework yields `null`, which
+// the caller treats as "cannot determine" (conservative pass).
+const KNOWN_FRAMEWORKS = ["react", "vue"];
+
+// Read `.codeyam/stack.json` relative to the capture script's cwd (the project
+// dir — `scenario_check.rs` sets `.current_dir(project_dir)`). Never throws: a
+// missing or malformed file yields `null` so the probe degrades to a no-op
+// rather than breaking a capture.
+function readStackJson() {
+  try {
+    const raw = fs.readFileSync(path.join(".codeyam", "stack.json"), "utf8");
+    return JSON.parse(raw);
+  } catch (_) {
+    return null;
+  }
+}
+
+// Scan a stack descriptor's identity fields for a framework we can probe.
+// Pure — no I/O — so the matching rules are unit-tested without a stack.json.
+function inferFramework(stack) {
+  if (!stack) return null;
+  const haystack = [
+    stack.id,
+    stack.name,
+    ...(Array.isArray(stack.technologies) ? stack.technologies : []),
+  ]
+    .filter((s) => typeof s === "string")
+    .join(" ")
+    .toLowerCase();
+  for (const fw of KNOWN_FRAMEWORKS) {
+    if (haystack.includes(fw)) return fw;
+  }
+  return null;
+}
+
+// Decide, from a stack descriptor, whether the capture should expect a
+// hydrated client runtime and which framework to probe for. Pure.
+//
+// `capture.interactivity === false` is an explicit opt-out for stacks that
+// render no client runtime. `capture.interactivity.framework` is an explicit
+// override when inference can't see the framework in the identity fields.
+// Otherwise we infer: a known client framework, or `routing.type ===
+// "client-side"`, implies a runtime that must hydrate; backend / static / CLI
+// stacks match neither and no-op.
+function resolveInteractivityExpectation(stack) {
+  const capture = (stack && stack.capture) || {};
+  if (capture.interactivity === false) {
+    return { expectInteractive: false, framework: null };
+  }
+  const explicit =
+    capture.interactivity && typeof capture.interactivity === "object"
+      ? capture.interactivity.framework
+      : null;
+  if (typeof explicit === "string" && explicit.length > 0) {
+    return { expectInteractive: true, framework: explicit.toLowerCase() };
+  }
+  const framework = inferFramework(stack);
+  const routingType =
+    stack && stack.routing && typeof stack.routing.type === "string"
+      ? stack.routing.type
+      : null;
+  const expectInteractive = framework != null || routingType === "client-side";
+  return { expectInteractive, framework };
+}
+
+// Run the in-page detection inside the loaded frame. Read-only: it inspects
+// DOM-node properties left by a framework's hydration but never clicks or
+// mutates anything, so it is safe to run before the screenshot is taken.
+//
+// Returns `{ controlCount, frameworkAttached }` where `frameworkAttached` is
+// `true` (runtime demonstrably attached), `false` (controls exist but no
+// attachment signal — the dead-hydration case), or `null` (no detector for
+// this framework → cannot judge).
+async function collectHydrationState(frame, { framework } = {}) {
+  return frame.evaluate((fw) => {
+    const SELECTOR =
+      'button, [role="button"], a[href], input:not([type="hidden"]), select, textarea, summary, [onclick]';
+    const controls = Array.from(document.querySelectorAll(SELECTOR));
+
+    // Per-framework attachment detectors. Each returns true when the framework
+    // has demonstrably attached its client runtime to a live interactive node.
+    // The presence of a detector for `fw` is itself the signal that we CAN
+    // judge this framework; the default (no detector) means "cannot determine".
+    const detectors = {
+      react: (els) =>
+        els.some(
+          (el) =>
+            !!el &&
+            Object.keys(el).some(
+              (k) =>
+                k.startsWith("__reactFiber$") ||
+                k.startsWith("__reactProps$") ||
+                k.startsWith("__reactContainer$"),
+            ),
+        ),
+      vue: (els) =>
+        els.some(
+          (el) =>
+            !!el &&
+            (el.__vue__ != null ||
+              el.__vnode != null ||
+              el.__vueParentComponent != null),
+        ) || !!document.querySelector("[data-v-app]"),
+    };
+
+    const detector = detectors[fw];
+    const frameworkAttached = detector ? detector(controls) : null;
+    return { controlCount: controls.length, frameworkAttached };
+  }, framework || null);
+}
+
+// Turn a collected state into a `hydration` issue, or `null` to pass. Pure, so
+// every branch is unit-tested without a browser.
+//
+// Pass when: no client runtime expected (no-op stacks); no interactive control
+// to probe (a static content page in a client app is legitimately inert); the
+// framework attached; OR we couldn't determine attachment (`null` — never
+// false-positive). Flag only the proven-dead case: controls exist AND the
+// framework's runtime is demonstrably not attached.
+function interpretHydration({
+  expectInteractive,
+  controlCount,
+  frameworkAttached,
+  framework,
+  url,
+}) {
+  if (!expectInteractive) return null;
+  if (!(controlCount > 0)) return null;
+  if (frameworkAttached !== false) return null;
+  const fw = framework || "the client framework";
+  const plural = controlCount === 1 ? "" : "s";
+  return createIssue(
+    "hydration",
+    `Page rendered ${controlCount} interactive control${plural} but ${fw} never attached ` +
+      `event handlers — the page is not interactive (hydration did not run). Client JS may ` +
+      `not be executing; check the preview proxy and the browser console. Run ` +
+      "`codeyam-editor editor diagnose-preview --path <route>` to pinpoint a proxy " +
+      `HTML-injection blocker.`,
+    { url: url ?? null },
+  );
+}
+
+// Orchestrator called from the capture flow: resolve the expectation (from the
+// project's stack.json unless the caller injects a `stack`), short-circuit when
+// no client runtime is expected, collect the in-page state, and interpret it.
+// Never throws — a probe failure must not break an otherwise-good capture.
+async function probeInteractivity(frame, { url, stack } = {}) {
+  const descriptor = stack !== undefined ? stack : readStackJson();
+  const { expectInteractive, framework } =
+    resolveInteractivityExpectation(descriptor);
+  if (!expectInteractive) return null;
+  let state;
+  try {
+    state = await collectHydrationState(frame, { framework });
+  } catch (_) {
+    return null;
+  }
+  return interpretHydration({
+    expectInteractive: true,
+    controlCount: state.controlCount,
+    frameworkAttached: state.frameworkAttached,
+    framework,
+    url,
+  });
+}
+
+module.exports = {
+  KNOWN_FRAMEWORKS,
+  readStackJson,
+  inferFramework,
+  resolveInteractivityExpectation,
+  collectHydrationState,
+  interpretHydration,
+  probeInteractivity,
+};

package/npm/scenario-metrics.js

@@ -5,8 +5,22 @@ const LOADING_MARKERS = [
   "disconnected",
 ];
 
-function hasLoadingMarkers(text) {
-  return LOADING_MARKERS.some((marker) => text.includes(marker));
+// `extraMarkers` are project-supplied (from stack.json `capture.loadingMarkers`)
+// because an app's own loading copy ("Loading…", "Please wait") is
+// app-specific and must NOT be hardcoded into the shared harness — only the
+// four codeyam-harness markers above are universal. Matching is
+// case-insensitive so "Loading…" and "loading…" both count; without the
+// project markers a stable app loading screen looks "ready" to
+// waitForStablePage and gets captured mid-hydration.
+function hasLoadingMarkers(text, extraMarkers = []) {
+  if (!text) return false;
+  const lower = text.toLowerCase();
+  const markers = LOADING_MARKERS.concat(
+    Array.isArray(extraMarkers) ? extraMarkers : [],
+  );
+  return markers.some(
+    (marker) => marker && lower.includes(String(marker).toLowerCase()),
+  );
 }
 
 function hasRenderableContent(state) {

package/npm/scenario-mocks.js

@@ -19,41 +19,76 @@ function findHttpMock(httpMocks, request) {
   return null;
 }
 
+// The set of path/URL targets declared by the mock keys. A key is
+// `"<METHOD> <target>"` (e.g. `"GET /api/plans"`); we strip the method so the
+// route matcher can decide whether a request *could* match any mock without
+// knowing the method (the handler re-checks method via findHttpMock).
+function mockedTargets(httpMocks) {
+  const targets = new Set();
+  for (const key of Object.keys(httpMocks)) {
+    const spaceIdx = key.indexOf(" ");
+    if (spaceIdx === -1) continue;
+    targets.add(key.slice(spaceIdx + 1));
+  }
+  return targets;
+}
+
+// True when a request URL matches one of the declared mock targets. Accepts
+// either a string or a WHATWG URL (Playwright's URL-matcher passes a URL).
+function requestTargetsMock(targets, url) {
+  const href = typeof url === "string" ? url : url.href;
+  return normalizeMockCandidates(href).some((candidate) =>
+    targets.has(candidate),
+  );
+}
+
 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;
-    }
+  // Intercept ONLY requests whose path matches a declared mock — not every
+  // request. A blanket `page.route("**/*")` intercepts the dev server's ESM
+  // module/script/style requests too, and routing them through
+  // `route.continue()` breaks Vite dev-mode module loading: the lazy app
+  // chunks never resolve and the SPA renders blank. Scoping the matcher to
+  // mocked targets lets those requests load natively while still mocking the API.
+  const targets = mockedTargets(httpMocks);
+  await page.route(
+    (url) => requestTargetsMock(targets, url),
+    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";
+      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,
-    });
-  });
+      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).
+  // interception. This route is registered AFTER the mock matcher so it takes
+  // priority for that path (Playwright uses LIFO ordering for route handlers).
   await page.route("**/active-mocks.json", async (route) => {
     await route.fulfill({
       status: 200,
@@ -66,5 +101,7 @@ async function attachHttpMocks(page, httpMocks) {
 module.exports = {
   normalizeMockCandidates,
   findHttpMock,
+  mockedTargets,
+  requestTargetsMock,
   attachHttpMocks,
 };

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,29 @@ async function waitForAnimationsSettled(
   return { settled: false, elapsedMs: Date.now() - started };
 }
 
-async function waitForStablePage(page, target, timeoutMs = 10000) {
+// `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,
+      bodyText: document.body?.innerText ?? "",
+      html: document.body?.innerHTML ?? "",
     }));
 
-    if (!hasLoadingMarkers(pageState.bodyText) && pageState.html === lastHtml) {
+    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));
@@ -142,6 +249,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 +261,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,10 +305,44 @@ 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 };
+}
+
 module.exports = {
+  logCaptureTiming,
+  resolveTcpTarget,
+  assertAppPortReachable,
   escapeHtmlAttribute,
   buildIframeHarness,
   collectContentState,
@@ -189,4 +351,5 @@ module.exports = {
   waitForAnimationsSettled,
   waitForStablePage,
   loadScenarioInIframe,
+  loadScenarioTopLevel,
 };