@codeyam-editor/codeyam-editor 0.1.4 → 0.1.5

package/npm/scenario-handlers.js

@@ -1,15 +1,59 @@
 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);
-    });
+// Known substrings that mean the app refused to initialize because it was loaded
+// from an *insecure context* — a bare dotted-quad IP rather than HTTPS or the
+// hostname `localhost`. This is a whole CLASS of failure (Sveltia CMS's
+// "only works with HTTPS or localhost", anything gating on `isSecureContext`,
+// `crypto.subtle`, service workers, `Secure` cookies, WebAuthn), not one app.
+// Matching reclassifies the error as an actionable `insecure-host` advisory
+// instead of a generic console/page failure that surfaces as a bare
+// `screenshot=null` with no explanation. Substrings are matched
+// case-insensitively; keep the set small and well-known.
+const INSECURE_CONTEXT_SIGNATURES = [
+  "only works with https or localhost",
+  "issecurecontext",
+  "secure context",
+  "requires https",
+];
+
+// The single actionable message the `insecure-host` advisory carries. Names the
+// class of failure and the fix (the preview origin is `localhost` by default;
+// stubborn apps can opt into HTTPS) rather than echoing one app's raw error.
+const INSECURE_HOST_ADVISORY_MESSAGE =
+  "The app refused to run because it was loaded from an insecure context " +
+  "(a bare IP). It requires a secure context — HTTPS or the hostname " +
+  "`localhost`. The preview origin is `localhost` by default; if this persists, " +
+  "the app may require HTTPS even on localhost — enable `proxy.httpsPreview` in " +
+  ".codeyam/editor.json.";
+
+// Reclassify an error string as an `insecure-host` advisory when it matches a
+// known insecure-context signature, else null. Pure; the original text is kept
+// as the `contextSnippet` so the operator can still see what the app logged.
+function insecureContextAdvisory(text) {
+  if (typeof text !== "string" || text.length === 0) return null;
+  const lower = text.toLowerCase();
+  const matched = INSECURE_CONTEXT_SIGNATURES.some((sig) => lower.includes(sig));
+  if (!matched) return null;
+  return createIssue("insecure-host", INSECURE_HOST_ADVISORY_MESSAGE, {
+    contextSnippet: text,
+  });
+}
 
+// `allowWebSocket` keeps the real `WebSocket` for scenarios that script a
+// `/ws/terminal` transcript (or a WS stream): those captures NEED the socket to
+// connect so the server replays the scripted agent state into the frame. The
+// stub below exists to silence the live terminal's reconnect loop on EVERY
+// OTHER capture (a component that opens `/ws/terminal` with no scripted
+// playback would otherwise screenshot the "Reconnecting…" overlay); for a
+// scripted scenario the server holds the socket open after replay, so there is
+// no reconnect spam to silence and stubbing only hides the very state we are
+// trying to capture. The flag is computed by the capture orchestrator from the
+// scenario's `mocks.transcripts` / `mocks.streams` — see
+// `scenarioScriptsLiveSocket` in scenario-check.js.
+function getInitScript(allowWebSocket = false) {
+  const webSocketStub = allowWebSocket
+    ? ""
+    : `
     // Stub WebSocket during capture to prevent terminal reconnection spam.
     window.WebSocket = class StubWebSocket {
       static CONNECTING = 0;
@@ -32,14 +76,28 @@ function getInitScript() {
           if (this.onclose) this.onclose(new CloseEvent("close"));
         }, 0);
       }
-    };
+    };`;
+  return `
+    window.__codeyamUnhandledRejections = [];
+    window.addEventListener("unhandledrejection", (event) => {
+      const reason = event.reason;
+      const message =
+        reason instanceof Error ? reason.message : String(reason);
+      window.__codeyamUnhandledRejections.push(message);
+    });
+${webSocketStub}
   `;
 }
 
 function handleConsoleMessage(message) {
   if (message.type() !== "error") return null;
   const text = message.text();
-  
+
+  // An insecure-context refusal wins over the generic `console` classification:
+  // it is the targeted, actionable signal for the secure-context app class.
+  const advisory = insecureContextAdvisory(text);
+  if (advisory) return advisory;
+
   // Ignore known dev-server WebSocket/HMR errors from Vite proxy
   if (
     text.includes("WebSocket connection to") ||
@@ -68,7 +126,12 @@ function handleConsoleMessage(message) {
 }
 
 function handlePageError(error) {
-  return createIssue("pageerror", error.message || String(error));
+  const text = error.message || String(error);
+  // A secure-context guard often throws at boot rather than logging — surface
+  // the same actionable advisory for the pageerror path.
+  const advisory = insecureContextAdvisory(text);
+  if (advisory) return advisory;
+  return createIssue("pageerror", text);
 }
 
 function handleRequestFailed(request) {
@@ -95,4 +158,7 @@ module.exports = {
   handleConsoleMessage,
   handlePageError,
   handleRequestFailed,
+  insecureContextAdvisory,
+  INSECURE_CONTEXT_SIGNATURES,
+  INSECURE_HOST_ADVISORY_MESSAGE,
 };

package/npm/scenario-metrics.js

@@ -25,6 +25,34 @@ function hasLoadingMarkers(text, extraMarkers = []) {
 
 function hasRenderableContent(state) {
   if (!state) return false;
+
+  // Reveal-suppression guard. A scroll-gated entrance animation starts its
+  // content at `opacity:0` and reveals it via an IntersectionObserver wired
+  // from the app shell. Captured in isolation (no shell), the observer never
+  // fires, so the text renders into the DOM — `bodyTextLength`/`rootTextLength`
+  // are non-zero — yet stays visually invisible and the screenshot is blank.
+  // `visibleTextLength` is the length of text actually PAINTED to the frame
+  // (computed-style opacity/visibility aware). When the DOM carries text but
+  // none of it is visible AND there is no visible media, the frame is
+  // near-blank: report no content so the blank gate rejects it instead of
+  // waving through an empty shell. `visibleTextLength` is optional — older
+  // capture configs (and stubbed test targets) omit it, in which case the
+  // original DOM-presence behavior below is preserved byte-for-byte.
+  const domTextLength = Math.max(
+    state.bodyTextLength || 0,
+    state.rootTextLength || 0,
+  );
+  const hasVisibleMedia =
+    (state.loadedImageCount || 0) > 0 || (state.mediaBboxCount || 0) > 0;
+  if (
+    typeof state.visibleTextLength === "number" &&
+    domTextLength > 0 &&
+    state.visibleTextLength === 0 &&
+    !hasVisibleMedia
+  ) {
+    return false;
+  }
+
   if (
     state.rootChildCount > 0 ||
     state.rootTextLength > 0 ||
@@ -40,7 +68,17 @@ function hasRenderableContent(state) {
 function describeBlankReason(state) {
   if (!state) return "no content state collected";
   const parts = [];
-  if (!(state.bodyTextLength > 0)) {
+  // Distinguish "no text in the DOM at all" from "text rendered but nothing is
+  // visible" — the latter is the reveal-suppression symptom (opacity:0
+  // entrance content whose observer never fired in isolation), which points
+  // the author at a different fix than a genuinely empty page.
+  if (
+    typeof state.visibleTextLength === "number" &&
+    state.bodyTextLength > 0 &&
+    state.visibleTextLength === 0
+  ) {
+    parts.push("text rendered but not visible (reveal-suppressed?)");
+  } else if (!(state.bodyTextLength > 0)) {
     parts.push("no text");
   }
   const imageCount = state.imageCount || 0;
@@ -69,6 +107,16 @@ const ERROR_PATTERNS = [
   "Scenario Error",
 ];
 
+// The DOM attribute codeyam's own ScenarioRenderer stamps on its error and
+// seed-error fallback frames. Error detection anchors on this marker rather
+// than scanning the whole page body for ERROR_PATTERNS: a legitimately-mocked
+// scenario whose *content* quotes one of those harness phrases (a journal entry
+// describing the error component, say) must not be flagged as a failed capture.
+// Arbitrary client apps that never render a codeyam ScenarioRenderer never emit
+// the marker, so their pages are treated as healthy regardless of body text —
+// these patterns were always codeyam-harness-specific, never generic.
+const SCENARIO_ERROR_MARKER = "data-codeyam-scenario-error";
+
 function hasErrorPatterns(text) {
   return ERROR_PATTERNS.some((pattern) => text.includes(pattern));
 }
@@ -95,14 +143,81 @@ function buildErrorContextSnippet(text, pattern) {
   return `${prefix}${slice}${suffix}`;
 }
 
+// Classify a scenario-error fallback into a `{ matchedPattern, contextSnippet }`
+// from the marker info collected off the page. `marker` is the
+// `{ reason, text }` read from the `[data-codeyam-scenario-error]` element, or
+// null when no such element is present. Returns null when there is no marked
+// fallback — the page is healthy and no error-content failure is raised.
+//
+// When the marked fallback text contains a known ERROR_PATTERN (the render-error
+// path renders `Component "X" not found in registry`), that pattern is named so
+// the downstream Rust classifier can still extract the component; otherwise the
+// marker's `reason` attribute classifies it (the seed-error fallback, whose
+// "Seed Error" copy is intentionally not an ERROR_PATTERN). Because the text is
+// scoped to the fallback element — not the whole body — content elsewhere on the
+// page can quote these phrases freely without tripping detection.
+function findScenarioError(marker) {
+  // The capture passes the `frame.evaluate` result of querying the marker
+  // element: either null (no fallback rendered) or a `{reason, text}` object.
+  // Anything else (a bare string, a primitive) is not a marked error — guard
+  // so a non-object never reads as a present marker and false-flags the page.
+  if (!marker || typeof marker !== "object") return null;
+  const text = marker.text || "";
+  const reason = marker.reason || "";
+  const matchedPattern = findErrorPattern(text) || reason || "scenario error";
+  const contextSnippet =
+    buildErrorContextSnippet(text, matchedPattern) ||
+    (text ? text.replace(/\s+/g, " ").trim().slice(0, 200) : null);
+  return { matchedPattern, contextSnippet };
+}
+
+// Build the non-blocking "this page looks client-fetched" advisory from the two
+// settle signals the capture already computes: `stableOutcome` from
+// waitForStablePage (did the page settle, and was a loading marker still up at
+// the cap?) and `networkOutcome` from waitForNetworkQuiet (did in-flight network
+// go quiet, or did the bounded wait cap out?). Captures settle within a bounded
+// window so a never-idle stream can't hang them — which means a slower
+// client-side fetch lands AFTER the window and the screenshot catches the
+// loading/initial state instead of the populated one. When either signal fires,
+// name the cause and the two reliable fixes (server-render the data, or drive a
+// props-driven isolated component scenario) so the agent reaches for those up
+// front instead of rediscovering the constraint by trial and error. Returns the
+// advisory string, or null when the page settled cleanly (the SSR / props-driven
+// happy path — no advisory, so a healthy capture stays noise-free).
+function buildSettleAdvisory(stableOutcome, networkOutcome) {
+  const causes = [];
+  if (
+    stableOutcome &&
+    stableOutcome.stabilized === false &&
+    stableOutcome.hadLoadingMarkers === true
+  ) {
+    causes.push("a loading marker was still on the page");
+  }
+  if (networkOutcome && networkOutcome.quiet === false) {
+    causes.push("network requests were still in flight");
+  }
+  if (causes.length === 0) return null;
+  return (
+    `When this page was captured, ${causes.join(" and ")} — it likely fetches ` +
+    `its data on the client. Captures settle within a bounded window, so data ` +
+    `that arrives via a client-side fetch after that window renders as the ` +
+    `loading/initial state, not the populated state. To capture a populated ` +
+    `state, server-render the data (SSR/RSC) or drive a props-driven isolated ` +
+    `component scenario.`
+  );
+}
+
 module.exports = {
   hasLoadingMarkers,
   hasRenderableContent,
+  buildSettleAdvisory,
   describeBlankReason,
   shouldStopWaitingForImages,
   hasErrorPatterns,
   findErrorPattern,
+  findScenarioError,
   buildErrorContextSnippet,
   ERROR_PATTERNS,
+  SCENARIO_ERROR_MARKER,
   ERROR_CONTEXT_RADIUS,
 };

package/npm/scenario-mocks.js

@@ -98,10 +98,30 @@ async function attachHttpMocks(page, httpMocks) {
   });
 }
 
+
+// True when a console "Failed to load resource" error at `url` corresponds to
+// a mock this scenario DECLARED with an error status (>= 400). An intentional
+// error-state scenario (e.g. a History tab mocking `GET /api/history` -> 500)
+// must not fail its own capture on the console noise its mock deliberately
+// 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;
+    if ((mock.status || 200) >= 400) return true;
+  }
+  return false;
+}
+
 module.exports = {
   normalizeMockCandidates,
   findHttpMock,
   mockedTargets,
   requestTargetsMock,
   attachHttpMocks,
+  isDeclaredErrorMock,
 };