@codeyam-editor/codeyam-editor 0.1.5 → 0.1.7

package/npm/scenario-interactivity.js

@@ -19,13 +19,36 @@ const { createIssue } = require("./scenario-issues");
 // 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.
+// `detectors` below plus a `KNOWN_FRAMEWORKS` mapping — not an edit here; a
+// meta-framework that hydrates an already-detected runtime is a new row in
+// `META_FRAMEWORK_ALIASES`.
 
 // 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"];
 
+// Meta-frameworks mapped to the underlying runtime whose hydration detector
+// applies. These do not carry their runtime's name in their stack identity: a
+// Next.js app is `id: "nextjs-prisma-sqlite"`, `name: "Next.js + Prisma +
+// SQLite"` — nothing contains the literal "react". Without this map the
+// substring scan below returns `null`, the capture skips the hydration gate,
+// and a genuinely un-hydrated page is reported as an inert control rather than
+// as hydration never having run.
+//
+// Saying "Next hydrates React" is a fact about the runtime, not a framework
+// assumption, so this stays consistent with the data-driven design above: a new
+// meta-framework is a new row here, not a new branch in the capture flow.
+//
+// Matched with word boundaries rather than bare substrings so an unrelated name
+// like "NextGen CLI" or "Remixer" cannot masquerade as a meta-framework.
+const META_FRAMEWORK_ALIASES = [
+  { pattern: /\bnext(\.js|js)?\b/, framework: "react" },
+  { pattern: /\bremix\b/, framework: "react" },
+  { pattern: /\bgatsby\b/, framework: "react" },
+  { pattern: /\bnuxt(\.js|js)?\b/, framework: "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
@@ -51,6 +74,9 @@ function inferFramework(stack) {
     .filter((s) => typeof s === "string")
     .join(" ")
     .toLowerCase();
+  for (const { pattern, framework } of META_FRAMEWORK_ALIASES) {
+    if (pattern.test(haystack)) return framework;
+  }
   for (const fw of KNOWN_FRAMEWORKS) {
     if (haystack.includes(fw)) return fw;
   }
@@ -214,24 +240,136 @@ function interpretHydration({
 // 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 } = {}) {
+//
+// Returns `{ hydrated, issue }`:
+//   hydrated — `true` (runtime demonstrably attached), `false` (PROVEN dead:
+//     framework-owned controls rendered but nothing attached), or `null`
+//     ("cannot determine" — no client runtime expected, no control to probe, no
+//     detector for the framework, or the probe threw).
+//   issue — the `hydration` issue to surface, or `null` to pass.
+//
+// `hydrated` is deliberately three-valued rather than a bare boolean: the
+// capture flow branches a page to `interactionEffect: "unhydrated"` ONLY on a
+// proven `false`. A `null` must never be read as "dead" — that would turn every
+// unknown-framework page into a false hydration failure.
+async function probeHydrationState(frame, { url, stack } = {}) {
   const descriptor = stack !== undefined ? stack : readStackJson();
   const { expectInteractive, framework } =
     resolveInteractivityExpectation(descriptor);
-  if (!expectInteractive) return null;
+  if (!expectInteractive) return { hydrated: null, issue: null };
   let state;
   try {
     state = await collectHydrationState(frame, { framework });
   } catch (_) {
-    return null;
+    return { hydrated: null, issue: null };
   }
-  return interpretHydration({
+  const issue = interpretHydration({
     expectInteractive: true,
     controlCount: state.controlCount,
     frameworkAttached: state.frameworkAttached,
     framework,
     url,
   });
+  // `frameworkAttached` is already the three-valued signal `hydrated` needs —
+  // pass it through rather than re-deriving it from the presence of an issue,
+  // which would conflate "no issue" (a pass) with "hydrated" (a positive).
+  return { hydrated: state.frameworkAttached, issue };
+}
+
+// Sleep for `ms` — a promisified `setTimeout`, so the poll loop yields the
+// event loop between ticks instead of spinning.
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Bounded WAIT for hydration — the polling generalization of
+// `probeHydrationState`. Where the probe reads the attachment state once,
+// this re-polls `collectHydrationState` until the framework demonstrably
+// attaches, the state becomes unjudgeable, or a wall-clock cap elapses. It is
+// the seam the capture flow calls so that every screenshot and every driven
+// interaction happens AFTER the client runtime has attached, not on inert SSR
+// markup (the bug where a fill/click landed before React hydrated, the handler
+// never fired, yet the run reported success).
+//
+// Stack-agnostic by construction: it resolves the same expectation as the
+// probe, so a non-interactive stack (backend/static/CLI, or an explicit
+// `capture.interactivity === false`) returns immediately with `hydrated: null`
+// and never waits. An unknown framework (no detector) reads
+// `frameworkAttached === null` on the first poll and also passes instantly — we
+// never block on a page we cannot judge.
+//
+// Never fails closed: a timeout yields `hydrated: false` and lets the existing
+// `interpretHydration` path decide whether to surface the loud `hydration`
+// issue; a thrown probe (detached frame mid-nav) is caught and treated as a
+// pass. The wait can never hang a capture (hard cap) and never turns a page we
+// cannot prove dead into a failure.
+//
+// Honest limitation: the poll can only judge a page that has already rendered
+// framework-owned controls. `waitForStablePage` runs first (its `rootUnpainted`
+// guard waits for the SPA root to paint), so by the time this runs, content is
+// present for the SSR case this guards; a pure-CSR shell that renders zero
+// controls reads `null` and passes instantly, unchanged from today.
+//
+// Returns `{ hydrated, issue, timedOut, waitedMs }` where `hydrated` is the
+// same three-valued signal `probeHydrationState` returns.
+async function waitForHydration(
+  frame,
+  { url, stack, framework, timeoutMs = 10000, pollIntervalMs = 150 } = {},
+) {
+  let resolvedFramework;
+  let expectInteractive;
+  if (typeof framework === "string" && framework.length > 0) {
+    expectInteractive = true;
+    resolvedFramework = framework.toLowerCase();
+  } else {
+    const descriptor = stack !== undefined ? stack : readStackJson();
+    const resolution = resolveInteractivityExpectation(descriptor);
+    expectInteractive = resolution.expectInteractive;
+    resolvedFramework = resolution.framework;
+  }
+  if (!expectInteractive) {
+    return { hydrated: null, issue: null, timedOut: false, waitedMs: 0 };
+  }
+
+  const start = Date.now();
+  let state = { controlCount: 0, frameworkAttached: null };
+  let timedOut = false;
+  for (;;) {
+    try {
+      state = await collectHydrationState(frame, {
+        framework: resolvedFramework,
+      });
+    } catch (_) {
+      // Detached frame mid-navigation (or any probe throw): treat as "cannot
+      // determine" and pass — a probe failure must never fail a capture.
+      state = { controlCount: 0, frameworkAttached: null };
+      break;
+    }
+    // `true` (attached) and `null` (cannot judge) are both terminal — the
+    // conservative "can't prove dead" signal the probe already trusts. Only a
+    // proven `false` keeps us waiting.
+    if (state.frameworkAttached !== false) break;
+    // Stop before a sleep that would overrun the cap, so the wait stays bounded.
+    if (Date.now() - start + pollIntervalMs >= timeoutMs) {
+      timedOut = true;
+      break;
+    }
+    await sleep(pollIntervalMs);
+  }
+
+  const issue = interpretHydration({
+    expectInteractive: true,
+    controlCount: state.controlCount,
+    frameworkAttached: state.frameworkAttached,
+    framework: resolvedFramework,
+    url,
+  });
+  return {
+    hydrated: state.frameworkAttached,
+    issue,
+    timedOut,
+    waitedMs: Date.now() - start,
+  };
 }
 
 module.exports = {
@@ -241,5 +379,6 @@ module.exports = {
   resolveInteractivityExpectation,
   collectHydrationState,
   interpretHydration,
-  probeInteractivity,
+  probeHydrationState,
+  waitForHydration,
 };

package/npm/scenario-issues.js

@@ -17,7 +17,14 @@ function pushIssue(issues, issue) {
   }
 }
 
-function buildResult({ loaded, hasContent, issues, outputPath, url }) {
+function buildResult({
+  loaded,
+  hasContent,
+  issues,
+  outputPath,
+  url,
+  unmockedRoutes = [],
+}) {
   return {
     ok: loaded && hasContent && issues.length === 0,
     loaded,
@@ -25,6 +32,11 @@ function buildResult({ loaded, hasContent, issues, outputPath, url }) {
     url,
     outputPath: outputPath ?? null,
     issues,
+    // Diagnostic-only: same-origin 4xx routes with no scenario mock. Does NOT
+    // affect `ok` — the paired console error already fails the capture; this is
+    // the actionable route list the failure message and `stub-unmocked-routes`
+    // consume. Defaults to `[]` so callers that omit it are unchanged.
+    unmockedRoutes,
   };
 }
 

package/npm/scenario-mocks.js

@@ -1,45 +1,124 @@
-function normalizeMockCandidates(url) {
+// Route matcher shared, semantically, with the injected live-preview shim
+// (crates/proxy-http/src/fetch_patch.js::matchUrl / matchPath / matchQuerySpec).
+// This is a VERBATIM port of that shim's matcher — the two interception paths
+// MUST agree on which requests a mock route covers. When they drifted (the
+// shim gained `:param` + query-spec parity but this capture-harness matcher was
+// left doing exact string matching), a parameterized or query-spec'd mock
+// rendered in the Live Preview but escaped Playwright's `page.route` during
+// capture and rendered an empty list. `scenario-mocks.test.js` pins the two to
+// identical verdicts on a shared fixture table so a future divergence is a
+// test failure, not another lost build session.
+//
+// `:param` path segments match any single non-empty segment; a `?k=v` / `?k=*`
+// query-spec suffix constrains the query as a subset match (`k=*` matches any
+// value; an empty spec matches any query). Full-URL patterns (`http://…`) match
+// by prefix on the raw URL. Mirrors crates/mock-engine's server matcher.
+function matchUrl(pattern, url) {
+  // Full-URL patterns (external APIs) match by prefix on the raw URL.
+  if (pattern.startsWith("http://") || pattern.startsWith("https://")) {
+    return url.indexOf(pattern) === 0;
+  }
+
+  let reqPath = url;
+  let reqQuery = "";
   try {
-    const parsed = new URL(url);
-    return [url, `${parsed.pathname}${parsed.search}`, parsed.pathname];
+    const u = new URL(url);
+    reqPath = u.pathname;
+    reqQuery = u.search.replace(/^\?/, "");
   } catch {
-    return [url];
+    const qi = url.indexOf("?");
+    if (qi >= 0) {
+      reqPath = url.slice(0, qi);
+      reqQuery = url.slice(qi + 1);
+    }
+  }
+
+  const patParts = pattern.split("?");
+  if (!matchPath(patParts[0], reqPath)) return false;
+  return matchQuerySpec(patParts.length > 1 ? patParts[1] : "", reqQuery);
+}
+
+// Segment-wise path match with `:param` wildcards. A `:name` segment matches
+// any single non-empty segment; every other segment must be equal, and the
+// segment counts must match — no implicit prefix match, same as the server.
+function matchPath(pattern, path) {
+  const pp = pattern.split("/");
+  const rp = path.split("/");
+  if (pp.length !== rp.length) return false;
+  for (let i = 0; i < pp.length; i++) {
+    if (pp[i].charAt(0) === ":") {
+      if (rp[i] === "") return false;
+      continue;
+    }
+    if (pp[i] !== rp[i]) return false;
   }
+  return true;
+}
+
+// Query-spec match. An empty spec matches any query (a path-only route still
+// matches a request that carries query params). Otherwise every `k=v` pair in
+// the spec must be present in the request query; `k=*` matches any value.
+function matchQuerySpec(spec, query) {
+  if (!spec) return true;
+  const want = new URLSearchParams(spec);
+  const have = new URLSearchParams(query);
+  let ok = true;
+  want.forEach((v, k) => {
+    const got = have.get(k);
+    if (got === null) {
+      ok = false;
+      return;
+    }
+    if (v !== "*" && got !== v) ok = false;
+  });
+  return ok;
+}
+
+// Split a mock key (`"<METHOD> <route>"`, e.g. `"GET /api/plans"`) into its
+// method and route pattern. Returns null for a malformed key with no separator.
+function splitMockKey(key) {
+  const spaceIdx = key.indexOf(" ");
+  if (spaceIdx === -1) return null;
+  return { method: key.slice(0, spaceIdx), route: key.slice(spaceIdx + 1) };
 }
 
 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];
-    }
+  const url = request.url();
+  for (const [key, mock] of Object.entries(httpMocks)) {
+    const parsed = splitMockKey(key);
+    if (!parsed) continue;
+    // Method stays an exact check; only the route is matched by pattern.
+    if (parsed.method.toUpperCase() !== method) continue;
+    if (matchUrl(parsed.route, url)) return mock;
   }
   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
+// The set of path/URL route patterns declared by the mock keys. A key is
+// `"<METHOD> <route>"` (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));
+    const parsed = splitMockKey(key);
+    if (!parsed) continue;
+    targets.add(parsed.route);
   }
   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).
+// True when a request URL matches one of the declared mock route patterns under
+// the shared route matcher (`:param` + query-spec parity), not exact string
+// equality. 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),
-  );
+  for (const target of targets) {
+    if (matchUrl(target, href)) return true;
+  }
+  return false;
 }
 
 async function attachHttpMocks(page, httpMocks) {
@@ -106,22 +185,46 @@ async function attachHttpMocks(page, httpMocks) {
 // produces. Console errors carry no HTTP method, so any method's mock on a
 // matching target counts.
 function isDeclaredErrorMock(httpMocks, url) {
-  const candidates = normalizeMockCandidates(url);
   for (const [key, mock] of Object.entries(httpMocks || {})) {
-    const spaceIdx = key.indexOf(" ");
-    if (spaceIdx === -1) continue;
-    const target = key.slice(spaceIdx + 1);
-    if (!candidates.includes(target)) continue;
+    const parsed = splitMockKey(key);
+    if (!parsed) continue;
+    // Method-agnostic on purpose: console errors carry no HTTP method, so any
+    // method's error mock on a matching route counts. Route matching uses the
+    // shared matcher so a `:param`/query-spec error mock is recognised too.
+    if (!matchUrl(parsed.route, url)) continue;
     if ((mock.status || 200) >= 400) return true;
   }
   return false;
 }
 
+// Given a same-origin response's method/url/status and the scenario's declared
+// mocks, return the `{method, path, status}` to record as an unmocked route, or
+// `null` if it should be ignored: a sub-4xx response, or one already covered by
+// a declared error mock (status >= 400, whose 4xx is the mock's intended
+// behavior). The caller applies the same-origin and `expectedConsoleErrors`
+// gates before calling. `path` is the URL pathname — the route half of the
+// `"<METHOD> <path>"` stub-mock key; a malformed URL falls back to the raw
+// string so the key is still well-formed.
+function unmockedRouteFrom(method, url, status, httpMocks) {
+  if (status < 400) return null;
+  if (isDeclaredErrorMock(httpMocks, url)) return null;
+  let path = url;
+  try {
+    path = new URL(url).pathname;
+  } catch {
+    /* malformed URL — fall back to the raw string for the stub key */
+  }
+  return { method: String(method).toUpperCase(), path, status };
+}
+
 module.exports = {
-  normalizeMockCandidates,
+  matchUrl,
+  matchPath,
+  matchQuerySpec,
   findHttpMock,
   mockedTargets,
   requestTargetsMock,
   attachHttpMocks,
   isDeclaredErrorMock,
+  unmockedRouteFrom,
 };