@codeyam-editor/codeyam-editor 0.1.14 → 0.1.15

package/npm/scenario-check.js

@@ -352,6 +352,8 @@ const {
   frameHasVisualContent,
   buildSettleAdvisory,
   describeBlankReason,
+  stripStateSelector,
+  collectCssRuleMatches,
 } = require("./scenario-metrics");
 
 // Decode a PNG screenshot buffer to `{ width, height, data }` (RGBA) with the
@@ -710,6 +712,97 @@ function readStackReadySignal() {
   }
 }
 
+// Read the app's declared rendered-sources signal from `.codeyam/stack.json`
+// (`capture.renderedSourcesSignal`): a JS expression returning the source paths
+// of the widgets the app actually drew. A canvas app routes every scenario
+// through one entry, so static analysis cannot tell which widgets a seed
+// reaches; only the running app can. Never throws; an unreadable stack.json or
+// a missing/empty value declares no signal (null).
+function readStackRenderedSourcesSignal() {
+  try {
+    const raw = fs.readFileSync(path.join(".codeyam", "stack.json"), "utf8");
+    const stack = JSON.parse(raw);
+    return normalizeRenderedSourcesSignal(stack && stack.capture);
+  } catch (_) {
+    return null;
+  }
+}
+
+function normalizeRenderedSourcesSignal(source) {
+  return source &&
+    typeof source.renderedSourcesSignal === "string" &&
+    source.renderedSourcesSignal.trim()
+    ? source.renderedSourcesSignal.trim()
+    : null;
+}
+
+// The rendered-sources signal this capture evaluates: one injected through
+// config (unit tests) wins; otherwise stack.json's.
+function resolveRenderedSourcesSignal(config, readStack = readStackRenderedSourcesSignal) {
+  return config && typeof config.renderedSourcesSignal === "string"
+    ? normalizeRenderedSourcesSignal(config)
+    : readStack();
+}
+
+// The record beside a screenshot: `<screenshot>.rendered.json`. The editor's
+// staleness check (`rendered_sources.rs`) reads the same spelling.
+function renderedSourcesRecordPath(outputPath) {
+  return `${outputPath}.rendered.json`;
+}
+
+// Evaluate the rendered-sources signal in the captured frame and record the
+// answer beside the screenshot as `{"sources": [...]}`. Any earlier record is
+// removed first, so a recapture that yields no usable answer never leaves the
+// previous capture's report standing. An empty array means "no information"
+// (no record, no warning); a throw or a non-array / non-string value is a
+// warning — non-blocking, because the editor then simply keeps the full static
+// render set. Returns the warning string, or null.
+async function recordRenderedSources(frame, signal, outputPath, { fsImpl = fs } = {}) {
+  const recordPath = renderedSourcesRecordPath(outputPath);
+  try {
+    fsImpl.rmSync(recordPath, { force: true });
+  } catch (_) {}
+  if (!signal) return null;
+  let outcome;
+  try {
+    outcome = await frame.evaluate((expr) => {
+      try {
+        return { value: (0, eval)(expr) };
+      } catch (e) {
+        return { error: String((e && e.message) || e) };
+      }
+    }, signal);
+  } catch (e) {
+    outcome = { error: String((e && e.message) || e) };
+  }
+  const { sources, warning } = renderedSourcesFromOutcome(outcome, signal);
+  if (sources) {
+    fsImpl.writeFileSync(recordPath, `${JSON.stringify({ sources }, null, 2)}\n`);
+  }
+  return warning;
+}
+
+// Judge what the signal evaluated to: `{ sources }` (sorted, deduped, blanks
+// dropped) for a usable answer, `{ warning }` for a throw or a value that is not
+// an array of strings, and neither for an empty answer — "no information",
+// which the editor already treats as "keep the static render set".
+function renderedSourcesFromOutcome(outcome, signal) {
+  if (outcome && outcome.error != null) {
+    return {
+      warning: `rendered-sources: \`${signal}\` threw (${outcome.error}); staleness keeps this scenario's full static render set. Fix capture.renderedSourcesSignal in .codeyam/stack.json or the app code that publishes it.`,
+    };
+  }
+  const value = outcome ? outcome.value : undefined;
+  if (!Array.isArray(value) || value.some((s) => typeof s !== "string")) {
+    const shape = Array.isArray(value) ? "an array with non-string entries" : typeof value;
+    return {
+      warning: `rendered-sources: \`${signal}\` returned ${shape}, not an array of source paths; staleness keeps this scenario's full static render set.`,
+    };
+  }
+  const sources = [...new Set(value.map((s) => s.trim()).filter((s) => s.length > 0))].sort();
+  return sources.length > 0 ? { sources, warning: null } : { warning: null };
+}
+
 // The readiness this capture waits on: a `readySignal` injected through config
 // (unit tests, and any caller that knows better) wins; otherwise stack.json's.
 function resolveCaptureReadiness(config, readStack = readStackReadySignal) {
@@ -834,6 +927,36 @@ async function resolvePixelClip(frame, interaction, resolve = resolveInteraction
   }
 }
 
+// The canvas form of a flow `waitFor` (`{"canvas": true}`): hold until two
+// consecutive screenshots match. The shot is clipped to the page's canvas when
+// one resolves, as the other canvas settles are, so an unrelated spinner
+// elsewhere cannot keep it unsettled; with no canvas it uses the viewport.
+// THROWS naming the settle and the bound when the frame never stops changing —
+// the same fail-loud contract the DOM wait keeps, never a silent pass.
+async function waitForCanvasSettle(
+  page,
+  frame,
+  step,
+  {
+    defaultTimeoutMs = 8000,
+    resolveClip = resolvePixelClip,
+    pixelSettle = waitForPixelStable,
+  } = {},
+) {
+  const { timeoutMs } = step || {};
+  const bound =
+    typeof timeoutMs === "number" && timeoutMs > 0 ? timeoutMs : defaultTimeoutMs;
+  const { clip } = await resolveClip(frame, { action: "click", selector: "canvas" });
+  if (!(await pixelSettle(page, { clip, timeoutMs: bound }))) {
+    throw new Error(
+      `waitFor: the canvas frame did not settle (two consecutive equal ` +
+        `screenshots) within ${bound}ms — something on it is still moving ` +
+        `(a spinner or a running animation). Raise timeoutMs, or drop the ` +
+        `wait and capture.`,
+    );
+  }
+}
+
 // Which signal proved the effect: `dom` wins when both moved, because it is the
 // stronger and more specific evidence. `null` when neither moved.
 function interactionEffectSignal(beforeFingerprint, afterFingerprint, pixelsChanged) {
@@ -1869,6 +1992,28 @@ function resolveFlowDownloadDir(config) {
   );
 }
 
+// The transient record of which stylesheet rules matched the frame at
+// `outputPath`. The editor folds it into the `.png.hash` sidecar so an edit to
+// a rule that styled nothing in this frame leaves the screenshot fresh.
+function cssRuleMatchesPath(outputPath) {
+  return `${outputPath}.css-matches.json`;
+}
+
+// Walk the settled DOM and write the record for the frame just captured.
+// Stack assumption: per-rule CSS tracking needs a DOM at capture; a failed walk
+// writes nothing, and no record means whole-file stylesheet digests — so every
+// failure here is swallowed rather than failing the capture.
+async function recordCssRuleMatches(frame, outputPath) {
+  try {
+    const matches = await frame.evaluate(
+      `(${collectCssRuleMatches.toString()})(${stripStateSelector.toString()})`,
+    );
+    fs.writeFileSync(cssRuleMatchesPath(outputPath), JSON.stringify(matches));
+  } catch (_) {
+    // No record is the safe outcome.
+  }
+}
+
 // Close the capture browser, but never wait on it forever: a browser wedged in
 // teardown (a download mid-flight, a crashed renderer) used to hold the whole
 // capture past its budget with every frame already on disk. Past `boundMs` the
@@ -2056,7 +2201,11 @@ async function runFlowSteps(page, initialFrame, steps, ctx) {
           break;
         }
         case "waitFor":
-          await waitForPredicate(frame, step);
+          if (step.canvas === true) {
+            await waitForCanvasSettle(page, frame, step);
+          } else {
+            await waitForPredicate(frame, step);
+          }
           break;
         case "capture":
           if (step.outputPath) {
@@ -2772,7 +2921,22 @@ async function runScenarioCheck(
     // recoverable rather than destructive.
     if (outputPath && loaded && !devServerPlaceholder) {
       fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+      // A record left by an earlier capture describes an earlier frame, so it
+      // goes before this shot; the one written after always describes THIS one.
+      fs.rmSync(cssRuleMatchesPath(outputPath), { force: true });
       const shot = await page.screenshot({ path: outputPath, fullPage: false });
+      await recordCssRuleMatches(frame, outputPath);
+      // Ask the app which widget sources it drew in THIS frame, and record the
+      // answer beside the screenshot it describes. Only when the app signalled
+      // ready — a frame that never finished painting reports nothing useful.
+      if (readyOutcome.ready) {
+        const renderedWarning = await recordRenderedSources(
+          frame,
+          resolveRenderedSourcesSignal(config),
+          outputPath,
+        );
+        if (renderedWarning) interactionWarnings.push(renderedWarning);
+      }
       // A canvas-dominated page passed the DOM blank gate on its canvas's
       // bounding box alone, so check the pixels it actually painted. A frame
       // that is one flat color is an unpainted (or cleared-to-black) canvas.
@@ -2922,12 +3086,14 @@ async function main() {
 
 module.exports = {
   runScenarioCheck,
+  recordCssRuleMatches,
   classifyInteractionEffect,
   interactionEffectSignal,
   buildStepEffect,
   classifyKeyTarget,
   fingerprintHtml,
   resolvePixelClip,
+  waitForCanvasSettle,
   mergeVisibleTextLength,
   runFlowSteps,
   saveFlowDownload,
@@ -2975,6 +3141,11 @@ module.exports = {
   resolveReadySignal,
   readStackReadySignal,
   resolveCaptureReadiness,
+  readStackRenderedSourcesSignal,
+  resolveRenderedSourcesSignal,
+  renderedSourcesRecordPath,
+  recordRenderedSources,
+  renderedSourcesFromOutcome,
   readySignalTimeoutIssue,
   canvasBlankIssue,
   decodeScreenshotPng,

package/npm/scenario-metrics.js

@@ -267,7 +267,108 @@ function frameHasVisualContent(image) {
   return Math.round(max) - Math.round(min) >= MIN_CONTENT_LUMA_SPREAD;
 }
 
+// Reduce a selector to the part a settled DOM can answer. Pseudo-elements
+// (`::before`, `::placeholder`, legacy `:after`) and interaction-state
+// pseudo-classes (`:hover`, `:focus-visible`, …) are dropped, so
+// `.btn:hover::after` asks whether a `.btn` exists. Deliberately
+// over-inclusive: the staleness check ignores edits only to rules that
+// matched NOTHING, so counting a rule as matched can cost a recapture but
+// never hides one. An emptied compound (`:hover` alone) becomes `*`.
+function stripStateSelector(selector) {
+  const stripped = String(selector)
+    .replace(/::[\w-]+(\([^)]*\))?/g, "")
+    .replace(/:(before|after|first-line|first-letter)(?![\w-])/gi, "")
+    .replace(
+      /:(hover|focus-visible|focus-within|focus|active|visited|target|link|any-link)(?![\w-])/gi,
+      "",
+    );
+  return stripped
+    .split(",")
+    .map((part) => {
+      const trimmed = part.trim();
+      if (trimmed === "") return "*";
+      return /[>+~]$/.test(trimmed) ? `${trimmed} *` : trimmed;
+    })
+    .join(", ");
+}
+
+// Runs IN THE PAGE (via `frame.evaluate`), so it is self-contained and takes
+// the selector stripper as an argument rather than closing over it. Records,
+// per stylesheet, which style rules matched an element in the captured DOM.
+// Rules inside `@media` / `@supports` / `@container` / `@layer` are tested
+// whatever their condition, so a viewport difference never under-counts.
+//
+// A sheet is named by Vite's `data-vite-dev-id` (an absolute source path) or
+// its href's pathname; an unnamed inline `<style>` is skipped, since no
+// project file can be resolved from it. Cross-origin sheets whose `cssRules`
+// throw are skipped too — they are not project source. Shadow roots with their
+// own styles and `adoptedStyleSheets` are invisible to this walk, so either
+// marks the whole record `unsupported` and the editor falls back to digesting
+// whole files. A nested style rule marks its sheet `unsupported` the same way.
+function collectCssRuleMatches(strip) {
+  const out = { unsupported: false, sheets: [] };
+  if (document.adoptedStyleSheets && document.adoptedStyleSheets.length > 0) {
+    out.unsupported = true;
+  }
+  for (const el of Array.from(document.querySelectorAll("*"))) {
+    const root = el.shadowRoot;
+    if (
+      root &&
+      ((root.adoptedStyleSheets && root.adoptedStyleSheets.length > 0) ||
+        root.querySelector("style, link[rel~='stylesheet']"))
+    ) {
+      out.unsupported = true;
+      break;
+    }
+  }
+  const matches = (selectorText) => {
+    try {
+      return document.querySelector(strip(selectorText)) !== null;
+    } catch (_) {
+      return true;
+    }
+  };
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules;
+    try {
+      rules = sheet.cssRules;
+    } catch (_) {
+      continue;
+    }
+    const owner = sheet.ownerNode;
+    const viteId =
+      owner && owner.getAttribute ? owner.getAttribute("data-vite-dev-id") : null;
+    let id = viteId;
+    if (!id && sheet.href) {
+      try {
+        id = new URL(sheet.href).pathname;
+      } catch (_) {
+        id = null;
+      }
+    }
+    if (!id) continue;
+    const entry = { id, matched: [], unmatched: [], unsupported: false };
+    const walk = (list) => {
+      for (const rule of Array.from(list)) {
+        if (typeof CSSStyleRule !== "undefined" && rule instanceof CSSStyleRule) {
+          (matches(rule.selectorText) ? entry.matched : entry.unmatched).push(
+            rule.selectorText,
+          );
+          if (rule.cssRules && rule.cssRules.length > 0) entry.unsupported = true;
+        } else if (rule.cssRules) {
+          walk(rule.cssRules);
+        }
+      }
+    };
+    walk(rules);
+    out.sheets.push(entry);
+  }
+  return out;
+}
+
 module.exports = {
+  stripStateSelector,
+  collectCssRuleMatches,
   hasLoadingMarkers,
   hasRenderableContent,
   isCanvasDominated,

package/npm/scenario-playwright.js

@@ -1,5 +1,6 @@
 const {
   hasLoadingMarkers,
+  isCanvasDominated,
   shouldStopWaitingForImages,
 } = require("./scenario-metrics");
 const fs = require("fs");
@@ -1099,11 +1100,27 @@ async function candidateLabelSummary(frame) {
 // 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 }) {
+//
+// A text miss on a canvas-dominated page is not a spelling problem: the label
+// is painted into the canvas and is not page text at all, so an empty
+// candidate list would only send the author hunting a typo. That branch names
+// the canvas and the position form instead.
+function noMatchGuidance({ targetDesc, matchedByText, candidateLabels, canvasDominated = false }) {
   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 && canvasDominated) {
+    return (
+      `preview-interact: no element matched ${targetDesc}, and this page is ` +
+      `canvas-dominated (it paints into a canvas with no visible page text), ` +
+      `so the label is painted on the canvas and cannot be matched as text. ` +
+      `Target the canvas by position instead: ` +
+      `{"selector":"canvas","position":{"x":120,"y":40}} — a point in CSS ` +
+      `pixels from the canvas's top-left corner, read off the frame captured ` +
+      `just before this step.`
+    );
+  }
   if (matchedByText) {
     return (
       `preview-interact: no element matched ${targetDesc}. ` +
@@ -1381,7 +1398,11 @@ async function performKeyboardInteraction(frame, { action, value }) {
 // Resolve a step's target to the single element to act on. Shared by
 // `performInteraction` and by callers that need the target's box BEFORE
 // acting (the pixel-effect signal clips its before/after shots to it).
-async function resolveInteractionTarget(frame, interaction, { warnings } = {}) {
+async function resolveInteractionTarget(
+  frame,
+  interaction,
+  { warnings, canvasProbe = probeCanvasDominated } = {},
+) {
   const { action, selector, text } = interaction || {};
 
   let baseLocator;
@@ -1415,6 +1436,7 @@ async function resolveInteractionTarget(frame, interaction, { warnings } = {}) {
         candidateLabels: matchedByText
           ? await candidateLabelSummary(frame)
           : null,
+        canvasDominated: matchedByText ? await canvasProbe(frame) : false,
       }),
     );
   }
@@ -1591,14 +1613,31 @@ async function waitForPixelStable(
 // turns a never-appearing predicate into an actionable failure rather than an
 // infinite hang. `text` is matched case-insensitively as a substring (the
 // agent reliably knows the copy it rendered); `selector` is a CSS selector.
-async function waitForPredicate(frame, predicate, { defaultTimeoutMs = 8000 } = {}) {
+//
+// A text predicate on a canvas-dominated page is refused at once rather than
+// after the full bound: canvas-painted words are never DOM text, so the wait
+// could only time out. A hybrid page (DOM text beside a canvas) is not
+// canvas-dominated and keeps the ordinary wait; a canvas that mounts late is
+// caught on the timeout path, which re-checks and appends the same guidance.
+// A selector predicate is never refused — naming the canvas element itself is
+// a legitimate wait for that element. `canvasProbe` is injectable so unit
+// tests classify the page without a browser.
+async function waitForPredicate(
+  frame,
+  predicate,
+  { defaultTimeoutMs = 8000, canvasProbe = probeCanvasDominated } = {},
+) {
   const { text, selector, timeoutMs } = predicate || {};
   const bound =
     typeof timeoutMs === "number" && timeoutMs > 0 ? timeoutMs : defaultTimeoutMs;
 
   let locator;
   let desc;
-  if (typeof text === "string" && text.length > 0) {
+  const byText = typeof text === "string" && text.length > 0;
+  if (byText) {
+    if (await canvasProbe(frame)) {
+      throw new Error(`waitFor: predicate text "${text}" ${canvasTextWaitGuidance()}`);
+    }
     locator = frame.getByText(text, { exact: false }).first();
     desc = `text "${text}"`;
   } else if (typeof selector === "string" && selector.length > 0) {
@@ -1611,12 +1650,44 @@ async function waitForPredicate(frame, predicate, { defaultTimeoutMs = 8000 } =
   try {
     await locator.waitFor({ state: "visible", timeout: bound });
   } catch (_) {
+    const lateCanvas = byText && (await canvasProbe(frame));
     throw new Error(
-      `waitFor: predicate ${desc} did not become visible within ${bound}ms`,
+      `waitFor: predicate ${desc} did not become visible within ${bound}ms` +
+        (lateCanvas ? `. The page is now canvas-dominated: ${canvasTextWaitGuidance()}` : ""),
     );
   }
 }
 
+// Is the frame canvas-dominated right now — visible canvas/svg/video and no
+// visible text? Reads the same content state the blank gate classifies on.
+// Best-effort: a frame that cannot be measured reads as NOT canvas, so the
+// caller keeps its ordinary DOM behavior instead of refusing on a guess.
+async function probeCanvasDominated(frame) {
+  try {
+    const state = await collectContentState(frame);
+    const visible = await collectVisibleTextLength(frame);
+    if (typeof visible === "number") state.visibleTextLength = visible;
+    return isCanvasDominated(state);
+  } catch (_) {
+    return false;
+  }
+}
+
+// The redirect a text wait on a canvas page gets: why it cannot work, and the
+// three forms that do.
+function canvasTextWaitGuidance() {
+  return (
+    `cannot be awaited: this page is canvas-dominated (it paints into a ` +
+    `canvas with no visible page text), and canvas-painted words are never ` +
+    `in the DOM, so a text wait could only time out. Instead: wait for the ` +
+    `painted frame to stop changing with {"waitFor":{"canvas":true,"timeoutMs":8000}}; ` +
+    `click by position on the canvas ` +
+    `({"click":{"selector":"canvas","position":{"x":120,"y":40}}}, CSS pixels ` +
+    `from its top-left, read off the frame captured just before the step); or ` +
+    `drop the wait and capture — the capture already settles on pixels.`
+  );
+}
+
 // Drive an ordered sequence of interactions against the settled frame, settling
 // the page between each so a later step sees the DOM the earlier one produced.
 // This is the persisted-scenario path (`scenario.interactions`): unlike the
@@ -1693,5 +1764,6 @@ module.exports = {
   samePixels,
   waitForPixelStable,
   waitForPredicate,
+  probeCanvasDominated,
   performInteractionSequence,
 };