@codeyam-editor/codeyam-editor 0.1.8 → 0.1.10

package/npm/scenario-issues.js

@@ -7,6 +7,19 @@ function createIssue(kind, message, extra = {}) {
   };
   if (extra.matchedPattern != null) issue.matchedPattern = extra.matchedPattern;
   if (extra.contextSnippet != null) issue.contextSnippet = extra.contextSnippet;
+  // The hydration gate's cross-origin ATTRIBUTION, carried as data rather than
+  // only as prose. A consumer that must act on the verdict — escalating the
+  // preview off the subpath when the counterpart origin hydrates — would
+  // otherwise have to regex the English message, which breaks the moment the
+  // wording is improved. Same conditional shape as the two fields above so an
+  // issue that carries no attribution serializes exactly as it did before.
+  if (extra.crossOrigin != null) issue.crossOrigin = extra.crossOrigin;
+  if (extra.counterpartUrl != null) issue.counterpartUrl = extra.counterpartUrl;
+  // The dev-server-down verdict, carried as data for the same reason as the
+  // attribution fields above: a consumer that must distinguish "the app served
+  // an error" from "the app was not serving at all" should branch on a field,
+  // not on the prose of the message.
+  if (extra.devServerDown != null) issue.devServerDown = extra.devServerDown;
   return issue;
 }
 
@@ -17,6 +30,42 @@ function pushIssue(issues, issue) {
   }
 }
 
+// Derive which origin a capture actually loaded from, and whether that differs
+// from the origin the VIEWER's browser is served.
+//
+// The two can legitimately differ: the capture browser runs where the app is,
+// the viewer may not, and aiming them independently is what makes a capture
+// work on a cloud VM at all. A capture that renders perfectly from the app's
+// own origin while the user's pane sits on `/__codeyam_preview` is a USEFUL
+// result — but only if the difference travels with it instead of having to be
+// inferred from a URL the reader must parse themselves.
+//
+// Both unknowns resolve toward "no split", never toward a guess. A caller that
+// supplies no `viewerOrigin` (every pre-existing call site) and a `url` with no
+// parseable origin both yield `false`, so no existing consumer sees a changed
+// verdict and an unclassifiable capture is never reported as diverging.
+//
+// Deliberately not reusing `isCrossOriginRequest` from scenario-check.js: that
+// module imports THIS one, so depending on it would invert the dependency, and
+// its fail-safe answers a different question (never strip markers) than this
+// one does (never claim a split).
+function deriveOriginSplit(url, viewerOrigin) {
+  let captureOrigin = null;
+  try {
+    captureOrigin = new URL(url).origin;
+  } catch (_) {
+    /* a malformed or relative capture URL has no origin to report */
+  }
+  return {
+    captureOrigin,
+    viewerOrigin: viewerOrigin ?? null,
+    captureOriginDiffersFromViewer:
+      captureOrigin != null &&
+      viewerOrigin != null &&
+      captureOrigin !== viewerOrigin,
+  };
+}
+
 function buildResult({
   loaded,
   hasContent,
@@ -26,7 +75,13 @@ function buildResult({
   unmockedRoutes = [],
   mockUsage = { used: [], unused: [] },
   externalRequests = [],
+  viewerOrigin = null,
 }) {
+  const { captureOrigin, captureOriginDiffersFromViewer } = deriveOriginSplit(
+    url,
+    viewerOrigin,
+  );
+
   return {
     ok: loaded && hasContent && issues.length === 0,
     loaded,
@@ -48,6 +103,11 @@ function buildResult({
     // Requests grouped by origin, split mocked/unmocked and same/cross-origin.
     // The line that ends a "why is this page blank" misdiagnosis.
     externalRequests,
+    // The two hops, named. See `deriveOriginSplit` for why they can differ and
+    // why reporting the difference is not optional.
+    captureOrigin,
+    viewerOrigin,
+    captureOriginDiffersFromViewer,
   };
 }
 
@@ -55,4 +115,5 @@ module.exports = {
   createIssue,
   pushIssue,
   buildResult,
+  deriveOriginSplit,
 };

package/npm/scenario-playwright.js

@@ -345,9 +345,18 @@ async function collectVisibleTextLength(target) {
 // style id) and best-effort. Returns true when the style is present after the
 // call.
 //
-// The reveal is per-element and conditional ON THE ELEMENT BEING INVISIBLE,
-// never a blanket `opacity: 1 !important` / `transform: none !important` over
-// `*`. A blanket rule cannot tell an entrance animation's `opacity: 0` from
+// The reveal is conditional on ANIMATION EVIDENCE, not on transparency alone:
+// an element is revealed only when, before the reset lands, an animation or a
+// transition was actually holding it back. An element resting at `opacity: 0`
+// with neither is hidden BY INTENT — a closed dropdown, a hover-only action, an
+// empty toast slot, an off-screen drawer — and is left exactly as the app
+// rendered it. Elements carrying an explicit hidden-intent signal
+// (`aria-hidden="true"`, `inert`, or `pointer-events: none`), on themselves or
+// on an ancestor, are skipped even when a transition is declared — that is the
+// resting shape of a closed popover which animates on open.
+//
+// It is never a blanket `opacity: 1 !important` / `transform: none !important`
+// over `*`. A blanket rule cannot tell an entrance animation's `opacity: 0` from
 // DELIBERATE, resting state — a disabled control's dim, a muted row, a
 // collapsed chevron's rotation — so it silently flattened every one of them out
 // of every screenshot the capture pipeline produced. Two scenarios differing
@@ -385,14 +394,104 @@ async function forceFinalVisualState(target) {
       "}";
     const head = document.head || document.documentElement;
     if (!head || typeof head.appendChild !== "function") return false;
+
+    // Which elements is an animation or a transition ACTUALLY holding back?
+    // Snapshot that BEFORE the stylesheet lands, because injecting it destroys
+    // the evidence: `animation: none` / `transition: none` clears
+    // `animationName`, empties the running-animation list, and zeroes every
+    // duration. Only elements in this set are eligible for the reveal below.
+    const isAnimationHeld = (el) => {
+      let animations = null;
+      if (typeof el.getAnimations === "function") {
+        try {
+          animations = el.getAnimations();
+        } catch (_) {
+          animations = null;
+        }
+      }
+      if (animations && animations.length > 0) return true;
+      // No `getAnimations` (older engines) falls through to the computed-style
+      // evidence below — never to "reveal every invisible element".
+      let computed = null;
+      try {
+        computed = getComputedStyle(el);
+      } catch (_) {
+        return false;
+      }
+      if (!computed) return false;
+      const animationName = computed.animationName;
+      if (
+        typeof animationName === "string" &&
+        animationName !== "" &&
+        animationName !== "none"
+      ) {
+        return true;
+      }
+      const properties = computed.transitionProperty;
+      if (
+        typeof properties !== "string" ||
+        properties === "" ||
+        properties === "none"
+      ) {
+        return false;
+      }
+      const coversVisibility = properties
+        .split(",")
+        .map((property) => property.trim())
+        .some(
+          (property) =>
+            property === "opacity" ||
+            property === "transform" ||
+            property === "all",
+        );
+      if (!coversVisibility) return false;
+      const durations = computed.transitionDuration;
+      if (typeof durations !== "string") return false;
+      // A declared transition with a zero duration animates nothing, so it is
+      // not holding anything back.
+      return durations.split(",").some((duration) => parseFloat(duration) > 0);
+    };
+
+    // Explicit "this is hidden on purpose" signals, which outrank animation
+    // evidence. A closed popover carries its open-transition while resting
+    // closed, so a transition alone cannot distinguish it from an entrance the
+    // capture should finish. An ancestor counts: hiding a whole subtree is the
+    // common spelling.
+    const hasHiddenIntent = (el, computed) => {
+      if (computed && computed.pointerEvents === "none") return true;
+      if (typeof el.closest === "function") {
+        try {
+          if (el.closest('[aria-hidden="true"], [inert]')) return true;
+        } catch (_) {
+          // Fall through to the self-only checks below.
+        }
+      }
+      if (el.inert === true) return true;
+      if (
+        typeof el.getAttribute === "function" &&
+        el.getAttribute("aria-hidden") === "true"
+      ) {
+        return true;
+      }
+      return false;
+    };
+
+    const heldByAnimation = new Set();
+    if (typeof document.querySelectorAll === "function") {
+      for (const el of document.querySelectorAll("*")) {
+        if (isAnimationHeld(el)) heldByAnimation.add(el);
+      }
+    }
+
     head.appendChild(style);
 
     // With animations disabled above, an element held back by an entrance
     // animation now computes to its pre-animation resting state — typically
     // `opacity: 0`, often paired with a translate/scale that parks it offscreen.
-    // Reveal exactly those, and only those: a fully transparent element shows
-    // nothing either way, so forcing it can hide no real state, while an element
-    // at any visible opacity is left untouched.
+    // Reveal exactly those, and only those: membership in the pre-reset
+    // `heldByAnimation` snapshot is what separates them from UI the app is
+    // deliberately holding at `opacity: 0`, which stays hidden. An element at
+    // any visible opacity is left untouched either way.
     //
     // The transform half of the reveal STOPS at the SVG boundary. A CSS
     // `transform` overrides the SVG `transform` presentation attribute, so
@@ -417,6 +516,8 @@ async function forceFinalVisualState(target) {
       if (!computed) continue;
       const opacity = parseFloat(computed.opacity);
       if (!Number.isFinite(opacity) || opacity > INVISIBLE_EPSILON) continue;
+      if (!heldByAnimation.has(el)) continue;
+      if (hasHiddenIntent(el, computed)) continue;
       if (!el.style || typeof el.style.setProperty !== "function") continue;
       const inSvg =
         el.ownerSVGElement != null ||
@@ -928,6 +1029,59 @@ async function collectInteractiveLabels(frame) {
   }, INTERACTIVE_SELECTOR);
 }
 
+// How many candidate labels an error message may echo. Deliberately tighter
+// than `collectInteractiveLabels`' own 20-label read cap: the labels are the
+// USER'S page content, so every one printed is a line of their app leaked into
+// the terminal. Enough to answer "did you mean one of these?", not enough to
+// transcribe the page.
+const CANDIDATE_LABEL_CAP = 8;
+
+// Render the candidate labels for an error message, capped and counted. Shared
+// by the no-match and action-failed paths so the echo policy lives in one place.
+async function candidateLabelSummary(frame) {
+  const candidates = await collectInteractiveLabels(frame);
+  if (candidates.length === 0) return "(none found on page)";
+  const shown = candidates.slice(0, CANDIDATE_LABEL_CAP);
+  const rest = candidates.length - shown.length;
+  return rest > 0 ? `${shown.join(", ")} (+${rest} more)` : shown.join(", ");
+}
+
+// Compose the "no element matched" error, branched on the form the caller
+// ACTUALLY passed. Pure and string-returning so both branches are asserted
+// without a browser.
+//
+// The substring advice ("prefer an exact CSS selector") only applies to a text
+// label. Printing it at a caller who already passed `#id` contradicts its own
+// input and reads as misdirection — the failure mode that sent two sessions
+// hunting a selector bug when the page had simply not hydrated. The candidate
+// labels ride with the text branch for the same reason: they answer "did you
+// mean one of these?", a question only a text match can have asked, and every
+// label printed is a line of the user's own page echoed into the terminal.
+function noMatchGuidance({ targetDesc, matchedByText, candidateLabels }) {
+  const queryParamHint =
+    `Many filter/status/sort states are also reachable directly via a ` +
+    `URL query param (e.g. add "?status=active" to the path) with no ` +
+    `interaction at all.`;
+  if (matchedByText) {
+    return (
+      `preview-interact: no element matched ${targetDesc}. ` +
+      `Text is matched as a case-insensitive SUBSTRING, so a misspelled or ` +
+      `over-specific label matches nothing — prefer an exact/role/testid CSS ` +
+      `selector (e.g. {"selector":"[data-testid=\\"save\\"]"}) for a precise ` +
+      `target. ${queryParamHint} ` +
+      `Candidate interactive labels: ${candidateLabels}`
+    );
+  }
+  return (
+    `preview-interact: no element matched ${targetDesc}. ` +
+    `That is already an exact CSS selector, so nothing on the page matches ` +
+    `it as written — confirm the element is present in THIS state (it may be ` +
+    `behind a tab, dialog, or conditional render), that the id/attribute is ` +
+    `spelled as the markup emits it, and that the page rendered and hydrated ` +
+    `at all. ${queryParamHint}`
+  );
+}
+
 // Describe the elements a substring text match resolved, so an ambiguity
 // warning can name the competing controls (e.g. the preset button "Bet" vs the
 // disclosure button "…or bet on"). Reads each matched element's inner text via
@@ -1075,17 +1229,17 @@ async function performInteraction(
   }
 
   if (matchCount === 0) {
-    const candidates = await collectInteractiveLabels(frame);
-    const candidateList =
-      candidates.length > 0 ? candidates.join(", ") : "(none found on page)";
+    // Candidate labels are collected ONLY for the text branch — see
+    // `noMatchGuidance` for why a CSS-selector miss neither needs them nor
+    // should echo the user's page content back at them.
     throw new Error(
-      `preview-interact: no element matched ${targetDesc}. ` +
-        `Text is matched as a case-insensitive SUBSTRING, so a misspelled or ` +
-        `over-specific label matches nothing — prefer an exact/role/testid CSS ` +
-        `selector (e.g. {"selector":"[data-testid=\\"save\\"]"}) for a precise ` +
-        `target. Many filter/status/sort states are also reachable directly via a ` +
-        `URL query param (e.g. add "?status=active" to the path) with no ` +
-        `interaction at all. Candidate interactive labels: ${candidateList}`,
+      noMatchGuidance({
+        targetDesc,
+        matchedByText,
+        candidateLabels: matchedByText
+          ? await candidateLabelSummary(frame)
+          : null,
+      }),
     );
   }
 
@@ -1127,12 +1281,9 @@ async function performInteraction(
         );
     }
   } catch (error) {
-    const candidates = await collectInteractiveLabels(frame);
-    const candidateList =
-      candidates.length > 0 ? candidates.join(", ") : "(none found on page)";
     throw new Error(
       `preview-interact: action "${action}" failed against ${targetDesc}: ${error.message || String(error)}. ` +
-        `Candidate interactive labels: ${candidateList}`,
+        `Candidate interactive labels: ${await candidateLabelSummary(frame)}`,
     );
   }
 }
@@ -1209,6 +1360,7 @@ async function performInteractionSequence(
 
 module.exports = {
   logCaptureTiming,
+  defaultReadServerState,
   resolveTcpTarget,
   assertAppPortReachable,
   escapeHtmlAttribute,
@@ -1230,6 +1382,8 @@ module.exports = {
   loadScenarioInIframe,
   loadScenarioTopLevel,
   collectInteractiveLabels,
+  candidateLabelSummary,
+  noMatchGuidance,
   describeMatchCandidates,
   performInteraction,
   waitForPredicate,