@codeyam-editor/codeyam-editor 0.1.1 → 0.1.3

package/npm/scenario-interactivity.js

@@ -0,0 +1,245 @@
+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` (framework-owned controls
+// exist but no attachment signal — the dead-hydration case), or `null` (no
+// detector for this framework, OR every interactive control is delegated to a
+// terminal/canvas widget with no hydration marker → 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]';
+    // Roots of third-party terminal/canvas widgets that mount imperatively and
+    // wire their own (non-framework) event handlers — xterm's `.xterm`, any
+    // `<canvas>`, or an element a component explicitly flags terminal-backed.
+    // Interactive controls inside these (e.g. xterm's hidden helper
+    // `<textarea>`) never carry framework attachment keys even on a fully
+    // hydrated page, so judging hydration from them yields a false "not
+    // interactive" verdict. Stack assumption: `.xterm` is xterm-specific; the
+    // `<canvas>` and `[data-terminal-backed]` entries are framework-agnostic
+    // escape hatches any widget-embedding component can use.
+    const WIDGET_ROOT_SELECTOR = ".xterm, canvas, [data-terminal-backed]";
+
+    const controls = Array.from(document.querySelectorAll(SELECTOR));
+    const inWidget = (el) =>
+      !!el &&
+      typeof el.closest === "function" &&
+      el.closest(WIDGET_ROOT_SELECTOR) != null;
+    // Framework-owned controls: those NOT delegated to a terminal/canvas
+    // widget. Only these can prove or disprove that the framework hydrated.
+    const frameworkControls = controls.filter((el) => !inWidget(el));
+
+    // Per-framework attachment detectors. Each returns true when the framework
+    // has demonstrably attached its client runtime to a live 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];
+
+    // Terminal/canvas scenarios prove hydration with an explicit, framework-
+    // rendered `data-codeyam-hydrated` marker. It counts only when the
+    // framework actually attached to it — a marker that exists in static HTML
+    // but never hydrated fails the same detector and does not count.
+    const markerEl = document.querySelector("[data-codeyam-hydrated]");
+    const markerAttached = detector
+      ? detector(markerEl ? [markerEl] : [])
+      : false;
+
+    let frameworkAttached;
+    if (!detector) {
+      // No detector for this framework — cannot judge (conservative pass).
+      frameworkAttached = null;
+    } else if (detector(frameworkControls) || markerAttached) {
+      // A genuinely framework-owned control attached, or an explicit hydration
+      // marker proves the framework ran — definitively hydrated.
+      frameworkAttached = true;
+    } else if (frameworkControls.length === 0) {
+      // Controls exist but every one lives inside a terminal/canvas widget and
+      // there is no marker — we cannot prove the page is dead, so never flag.
+      frameworkAttached = null;
+    } else {
+      // Framework-owned controls rendered but none attached — the dead-island
+      // signal the gate exists to catch.
+      frameworkAttached = false;
+    }
+
+    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,
 };