hyperframes 0.6.99 → 0.6.101

package/dist/commands/layout-audit.browser.js

@@ -402,6 +402,12 @@
     return !!element.closest("[data-layout-allow-overlap]");
   }
 
+  function isTransparentColor(color) {
+    return (
+      !color || color === "transparent" || color === "rgba(0, 0, 0, 0)" || color.endsWith(", 0)")
+    );
+  }
+
   function alphaFromParts(parts, index) {
     return parts.length > index ? parsePx(parts[index]) : 1;
   }
@@ -458,13 +464,16 @@
     const area = intersectionArea(a.rect, b.rect);
     if (area <= Math.min(rectArea(a.rect), rectArea(b.rect)) * 0.2) return null;
     return {
+      // Warning, not error: must not fail the exit code (ok = errorCount === 0)
+      // for compositions that intentionally layer text. Re-promote once the
+      // data-layout-allow-overlap opt-out is widely adopted.
       code: "content_overlap",
-      severity: "error",
+      severity: "warning",
       time,
       selector: selectorFor(a.element),
       containerSelector: selectorFor(b.element),
       text: textContentFor(a.element),
-      message: "Two text blocks overlap and render unreadable.",
+      message: "Two text blocks overlap and may render unreadable.",
       rect: a.rect,
       fixHint:
         "Give each block its own zone, or mark intentional layering with data-layout-allow-overlap.",
@@ -483,6 +492,79 @@
     return issues;
   }
 
+  function hasOpaqueBackground(style) {
+    if (style.backgroundImage && style.backgroundImage !== "none") return true;
+    if (isTransparentColor(style.backgroundColor)) return false;
+    return colorAlpha(style.backgroundColor) > 0.6;
+  }
+
+  const RASTER_TAGS = new Set(["IMG", "VIDEO", "CANVAS"]);
+
+  // An element hides text beneath it when it paints opaque pixels at near-full
+  // opacity: raster content (img/video/canvas), a background image, or a solid
+  // background colour. Low-opacity overlays (grain, scrims) do not occlude.
+  function isOpaqueOccluder(element) {
+    if (opacityChain(element) < 0.6) return false;
+    if (IGNORE_TAGS.has(element.tagName)) return false;
+    if (RASTER_TAGS.has(element.tagName)) return true;
+    return hasOpaqueBackground(getComputedStyle(element));
+  }
+
+  function hasAllowOcclusionFlag(element) {
+    return !!element.closest("[data-layout-allow-occlusion]");
+  }
+
+  // A foreign element is one painted independently of the text — not the text
+  // itself, its own subtree, or an ancestor it shares a background with.
+  function isForeignElement(element, hit) {
+    return !!hit && hit !== element && !element.contains(hit) && !hit.contains(element);
+  }
+
+  // The opaque element painted over (x, y), or null when the topmost element
+  // there is related to the text or non-opaque.
+  function occluderAt(element, x, y) {
+    if (typeof document.elementFromPoint !== "function") return null;
+    const hit = document.elementFromPoint(x, y);
+    if (!isForeignElement(element, hit)) return null;
+    return isOpaqueOccluder(hit) ? hit : null;
+  }
+
+  // Sweep a grid across the text box (three rows, not just the mid-line, so
+  // overlays covering only part of a multi-line block are caught) and return
+  // the first opaque element painted over any sample point.
+  function firstOccluder(element, textRect) {
+    for (const yFraction of [0.25, 0.5, 0.75]) {
+      const y = textRect.top + textRect.height * yFraction;
+      for (const xFraction of [0.03, 0.1, 0.2, 0.35, 0.5, 0.65, 0.8, 0.9, 0.97]) {
+        const occluder = occluderAt(element, textRect.left + textRect.width * xFraction, y);
+        if (occluder) return occluder;
+      }
+    }
+    return null;
+  }
+
+  // Catches the blind spot the overflow checks miss: text that fits its box
+  // perfectly but is covered by a later sibling/overlay.
+  function occludedTextIssue(element, time) {
+    if (hasAllowOcclusionFlag(element)) return null;
+    const textRect = textRectFor(element);
+    if (!textRect) return null;
+    const occluder = firstOccluder(element, textRect);
+    if (!occluder) return null;
+    return {
+      code: "text_occluded",
+      severity: "error",
+      time,
+      selector: selectorFor(element),
+      containerSelector: selectorFor(occluder),
+      text: textContentFor(element),
+      message: "Text is hidden beneath an opaque element.",
+      rect: textRect,
+      fixHint:
+        "Give the text its own zone, raise its stacking order above the covering element, or mark intentional layering with data-layout-allow-occlusion.",
+    };
+  }
+
   window.__hyperframesLayoutAudit = function auditLayout(options) {
     const time = options && typeof options.time === "number" ? options.time : 0;
     const tolerance =
@@ -500,6 +582,8 @@
       const clipped = clippedTextIssue(element, time, tolerance);
       if (clipped) issues.push(clipped);
       issues.push(...textOverflowIssues(element, root, rootRect, time, tolerance));
+      const occluded = occludedTextIssue(element, time);
+      if (occluded) issues.push(occluded);
     }
 
     issues.push(...containerOverflowIssues(root, time, tolerance));

package/dist/commands/motion-sample.browser.js

@@ -0,0 +1,121 @@
+// In-page motion sampler for `hyperframes inspect` motion verification (#1437).
+// Runs inside the seeked, paused page (via page.evaluate). For each asserted
+// selector it returns this frame's { rect, opacity, visible }; for each liveness
+// scope it returns a bucketed signature of all visible elements, so the Node-side
+// evaluator can detect frozen windows by comparing signatures across frames.
+(function () {
+  const IGNORE_TAGS = new Set(["SCRIPT", "STYLE", "TEMPLATE", "NOSCRIPT", "META", "LINK"]);
+
+  function round(value) {
+    return Math.round(value * 100) / 100;
+  }
+
+  function toRect(rect) {
+    return {
+      left: round(rect.left),
+      top: round(rect.top),
+      right: round(rect.right),
+      bottom: round(rect.bottom),
+      width: round(rect.width),
+      height: round(rect.height),
+    };
+  }
+
+  function opacityChain(element) {
+    let opacity = 1;
+    for (let current = element; current; current = current.parentElement) {
+      const parsed = Number.parseFloat(getComputedStyle(current).opacity || "1");
+      if (Number.isFinite(parsed)) opacity *= parsed;
+    }
+    return opacity;
+  }
+
+  // Mirrors layout-audit.browser.js isVisibleElement.
+  // fallow-ignore-next-line complexity
+  function isVisibleElement(element) {
+    if (IGNORE_TAGS.has(element.tagName)) return false;
+    const style = getComputedStyle(element);
+    if (
+      style.display === "none" ||
+      style.visibility === "hidden" ||
+      style.visibility === "collapse"
+    ) {
+      return false;
+    }
+    if (opacityChain(element) < 0.2) return false;
+    const rect = element.getBoundingClientRect();
+    return rect.width > 0.5 && rect.height > 0.5;
+  }
+
+  function sampleElement(element) {
+    const rect = element.getBoundingClientRect();
+    return {
+      rect: toRect(rect),
+      opacity: round(opacityChain(element)),
+      visible: isVisibleElement(element),
+    };
+  }
+
+  function compositionRoot() {
+    return document.querySelector("[data-composition-id]") || document.body;
+  }
+
+  // ponytail: bucket position to 2px and opacity to 0.08 so the RFC's "moves ≥2px /
+  // opacity ≥0.08" thresholds fall out of bucketing. Boundary-straddling moves are
+  // approximate — good enough for liveness; tighten only if false negatives show up.
+  function elementSignature(element) {
+    const rect = element.getBoundingClientRect();
+    const bx = Math.round(rect.left / 2);
+    const by = Math.round(rect.top / 2);
+    const bw = Math.round(rect.width / 2);
+    const bh = Math.round(rect.height / 2);
+    const bo = Math.round(opacityChain(element) / 0.08);
+    return bx + "," + by + "," + bw + "," + bh + "," + bo;
+  }
+
+  function livenessSignature(root) {
+    if (!root) return "";
+    const parts = [];
+    // ponytail: O(DOM) × MOTION_MAX_SAMPLES (300) — fine for typical compositions;
+    // narrow selector (e.g. "[id],[class]") if heavy-DOM compositions slow this down.
+    const all = root.querySelectorAll("*");
+    for (const element of all) {
+      if (!isVisibleElement(element)) continue;
+      parts.push(elementSignature(element));
+    }
+    return parts.join("|");
+  }
+
+  function safeQuery(selector) {
+    try {
+      return document.querySelector(selector);
+    } catch {
+      return null;
+    }
+  }
+
+  function sampleSelectors(selectors) {
+    const data = {};
+    for (const selector of selectors) {
+      // Multi-match selectors are rejected before this point by findAmbiguousSelectors
+      // in layout.ts; querySelector is safe here.
+      const element = safeQuery(selector);
+      data[selector] = element ? sampleElement(element) : null;
+    }
+    return data;
+  }
+
+  function sampleLiveness(scopes) {
+    const liveness = {};
+    for (const scope of scopes) {
+      const root = scope === "*" ? compositionRoot() : safeQuery(scope);
+      liveness[scope] = livenessSignature(root);
+    }
+    return liveness;
+  }
+
+  window.__hyperframesMotionSample = function motionSample(options) {
+    const { selectors = [], livenessScopes = [] } = options || {};
+    return { data: sampleSelectors(selectors), liveness: sampleLiveness(livenessScopes) };
+  };
+})();