@codeyam-editor/codeyam-editor 0.1.0-staging.01efa1a

package/npm/scenario-handlers.js

@@ -0,0 +1,82 @@
+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) {
+  const errorText = request.failure()?.errorText || "Request failed";
+
+  // Filter benign request cancellations. `net::ERR_ABORTED` is what Playwright
+  // emits when a request is in-flight at the moment the page is closed (or the
+  // iframe is destroyed). For scenarios whose pages fetch large payloads (the
+  // editor's own EditorShell mounts a 2.2MB `/api/tests` fetch), the
+  // browser.close() at the end of capture races the fetch and produces this
+  // event AFTER the screenshot has already been taken — there is no real
+  // failure to surface. Genuine network failures arrive under different
+  // codes (net::ERR_CONNECTION_REFUSED, net::ERR_NAME_NOT_RESOLVED, etc.)
+  // and continue to be reported.
+  if (errorText.includes("net::ERR_ABORTED")) {
+    return null;
+  }
+
+  return createIssue("requestfailed", errorText, { url: request.url() });
+}
+
+module.exports = {
+  getInitScript,
+  handleConsoleMessage,
+  handlePageError,
+  handleRequestFailed,
+};

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-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,108 @@
+const LOADING_MARKERS = [
+  "Loading scenario...",
+  "Loading tests...",
+  "Loading scenarios...",
+  "disconnected",
+];
+
+// `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) {
+  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,107 @@
+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;
+}
+
+// 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;
+
+  // 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";
+        }
+      }
+
+      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 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,
+      headers: { "content-type": "application/json" },
+      body: "[]",
+    });
+  });
+}
+
+module.exports = {
+  normalizeMockCandidates,
+  findHttpMock,
+  mockedTargets,
+  requestTargetsMock,
+  attachHttpMocks,
+};