hyperframes 0.7.49 → 0.7.50

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

@@ -158,6 +158,22 @@ window.__contrastAuditPrepare = function () {
     }
     if (!hasText) continue;
 
+    // Same decorative opt-out the layout audit honors: text marked (or inside)
+    // data-layout-ignore is set dressing, not copy a viewer must read —
+    // deliberately dim rail labels, ghost typography, texture text.
+    if (el.closest && el.closest("[data-layout-ignore]")) continue;
+
+    // Text that has (nearly) left the canvas — a cursor exiting the frame, an
+    // element parked off-screen — is not readable content, and sampling its
+    // clamped edge reads whatever pixels happen to sit at the border (the
+    // classic false "white-on-white"). Require a minimally-visible on-canvas
+    // intersection before judging contrast; the layout audit separately owns
+    // off-canvas detection as its own finding class.
+    var vis = el.getBoundingClientRect();
+    var onX = Math.min(vis.right, window.innerWidth) - Math.max(vis.left, 0);
+    var onY = Math.min(vis.bottom, window.innerHeight) - Math.max(vis.top, 0);
+    if (onX < 8 || onY < 8) continue;
+
     var cs = getComputedStyle(el);
     if (cs.visibility === "hidden" || cs.display === "none") continue;
     if (parseFloat(cs.opacity) <= 0.01) continue;

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

@@ -81,6 +81,22 @@
     return `${selectorFor(parent)} > ${element.tagName.toLowerCase()}:nth-of-type(${index})`;
   }
 
+  function uniqueSelectorFor(element) {
+    const preferred = selectorFor(element);
+    try {
+      if (document.querySelectorAll(preferred).length === 1) return preferred;
+    } catch {
+      // Fall through to a structural selector.
+    }
+    const parent = element.parentElement;
+    if (!parent) return preferred;
+    const siblings = Array.from(parent.children).filter(
+      (child) => child.tagName === element.tagName,
+    );
+    const index = siblings.indexOf(element) + 1;
+    return `${uniqueSelectorFor(parent)} > ${element.tagName.toLowerCase()}:nth-of-type(${index})`;
+  }
+
   function hasIgnoreFlag(element) {
     return !!element.closest("[data-layout-ignore], [data-layout-check='ignore']");
   }
@@ -98,6 +114,14 @@
     return opacity;
   }
 
+  function hasOpacityBelow(element, floor) {
+    for (let current = element; current; current = current.parentElement) {
+      const parsed = Number.parseFloat(getComputedStyle(current).opacity || "1");
+      if (Number.isFinite(parsed) && parsed < floor) return true;
+    }
+    return false;
+  }
+
   // A clip-path can shrink an element's painted region to nothing (e.g. a
   // typewriter span pre-reveal at `inset(0 100% 0 0)`, or `circle(0px)`) while
   // its layout box, opacity, visibility and display all still read as present.
@@ -142,9 +166,20 @@
     return !paintsAnyProbePoint(element, rect);
   }
 
-  function isVisibleElement(element) {
+  function isVisibleElement(element, opacityFloor, probeClipPath) {
     if (IGNORE_TAGS.has(element.tagName)) return false;
     if (hasIgnoreFlag(element)) return false;
+    if (
+      opacityFloor != null &&
+      typeof element.checkVisibility === "function" &&
+      !element.checkVisibility({
+        opacityProperty: true,
+        visibilityProperty: true,
+        contentVisibilityAuto: true,
+      })
+    ) {
+      return false;
+    }
     const style = getComputedStyle(element);
     if (
       style.display === "none" ||
@@ -153,32 +188,57 @@
     ) {
       return false;
     }
-    if (opacityChain(element) < 0.2) return false;
+    if (
+      opacityFloor == null ? opacityChain(element) < 0.2 : hasOpacityBelow(element, opacityFloor)
+    ) {
+      return false;
+    }
     const rect = element.getBoundingClientRect();
     if (rect.width <= 0.5 || rect.height <= 0.5) return false;
-    return !isClippedAway(element);
+    return probeClipPath === false || !isClippedAway(element);
   }
 
-  function textContentFor(element) {
-    return (element.innerText || element.textContent || "").replace(/\s+/g, " ").trim();
+  function directTextNodes(element) {
+    return Array.from(element.childNodes).filter((node) => node.nodeType === 3);
   }
 
-  function hasOwnTextCandidate(element) {
-    const text = textContentFor(element);
+  function textContentFor(element, ownTextOnly) {
+    const content = ownTextOnly
+      ? directTextNodes(element)
+          .map((node) => node.textContent || "")
+          .join("")
+      : element.innerText || element.textContent || "";
+    return content.replace(/\s+/g, " ").trim();
+  }
+
+  function hasOwnTextCandidate(element, directOnly) {
+    const text = textContentFor(element, directOnly);
     if (!text) return false;
+    if (directOnly) return true;
     for (const child of Array.from(element.children)) {
       if (isVisibleElement(child) && textContentFor(child)) return false;
     }
     return true;
   }
 
-  function textRectFor(element) {
-    const range = document.createRange();
-    range.selectNodeContents(element);
-    const rects = Array.from(range.getClientRects()).filter(
-      (rect) => rect.width > 0.5 && rect.height > 0.5,
-    );
-    range.detach();
+  function textClientRects(element, directOnly) {
+    const subjects = directOnly ? directTextNodes(element) : [element];
+    const rects = [];
+    for (const subject of subjects) {
+      const range = document.createRange();
+      range.selectNodeContents(subject);
+      rects.push(
+        ...Array.from(range.getClientRects()).filter(
+          (rect) => rect.width > 0.5 && rect.height > 0.5,
+        ),
+      );
+      range.detach();
+    }
+    return rects;
+  }
+
+  function textRectFor(element, directOnly) {
+    const rects = textClientRects(element, directOnly);
     if (rects.length === 0) return null;
 
     const union = rects.reduce(
@@ -567,9 +627,12 @@
     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.
+      // Warning at the per-sample level: a single-sample overlap is usually an
+      // entrance/exit transient (two blocks crossing mid-animation), not a real
+      // collision. `collapseStaticLayoutIssues` (utils/layoutAudit.ts) re-promotes
+      // this to error once the SAME overlap is held across >= 2 adjacent samples
+      // (or ~500ms of timeline) — a persistence-tiered replacement for the old
+      // "re-promote once data-layout-allow-overlap is widely adopted" plan (#U10).
       code: "content_overlap",
       severity: "warning",
       time,
@@ -602,6 +665,7 @@
   }
 
   const RASTER_TAGS = new Set(["IMG", "VIDEO", "CANVAS"]);
+  const FRAME_MEDIA_TAGS = new Set([...RASTER_TAGS, "SVG"]);
 
   // 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
@@ -667,42 +731,135 @@
     return hit;
   }
 
+  const OCCLUSION_PROBE_Y_FRACTIONS = [0.25, 0.5, 0.75];
+  const OCCLUSION_PROBE_X_FRACTIONS = [0.03, 0.1, 0.2, 0.35, 0.5, 0.65, 0.8, 0.9, 0.97];
+  const OCCLUSION_GRID_POINTS =
+    OCCLUSION_PROBE_Y_FRACTIONS.length * OCCLUSION_PROBE_X_FRACTIONS.length;
+
+  // Short, atomic text (a label/button/word, no whitespace) reads as a single
+  // unit — ANY covered probe point changes what it says, so flag at any hit
+  // (the pre-#U10 behaviour). Longer prose survives a nibbled edge; only flag
+  // once a real share of it is covered — see `occludedTextIssue`.
+  const ATOMIC_LABEL_MAX_CHARS = 16;
+  const PROSE_COVERAGE_FLOOR = 0.15;
+
+  function isAtomicLabel(text) {
+    return text.length > 0 && text.length <= ATOMIC_LABEL_MAX_CHARS && !/\s/.test(text);
+  }
+
   // 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]) {
+  // overlays covering only part of a multi-line block are caught). Unlike a
+  // first-hit scan, this keeps sampling every point so it can report what
+  // fraction of the box is actually covered — a corner nibble on a paragraph
+  // reads very differently from a label buried under an overlay. Still
+  // returns the first opaque element found, for `containerSelector`.
+  function occlusionCoverage(element, textRect) {
+    let occluder = null;
+    let hits = 0;
+    for (const yFraction of OCCLUSION_PROBE_Y_FRACTIONS) {
       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;
+      for (const xFraction of OCCLUSION_PROBE_X_FRACTIONS) {
+        const hit = occluderAt(element, textRect.left + textRect.width * xFraction, y);
+        if (!hit) continue;
+        hits += 1;
+        if (!occluder) occluder = hit;
       }
     }
-    return null;
+    return { occluder, coveredFraction: round(hits / OCCLUSION_GRID_POINTS) };
   }
 
   // Catches the blind spot the overflow checks miss: text that fits its box
-  // perfectly but is covered by a later sibling/overlay.
+  // perfectly but is covered by a later sibling/overlay. An atomic label
+  // (short, no whitespace) flags at any coverage; ordinary prose only flags
+  // once coveredFraction clears PROSE_COVERAGE_FLOOR, since a sliver of edge
+  // cover on a paragraph is usually a styling artifact, not a reading defect.
   function occludedTextIssue(element, time) {
     if (hasAllowOcclusionFlag(element)) return null;
     const textRect = textRectFor(element);
     if (!textRect) return null;
-    const occluder = firstOccluder(element, textRect);
+    const text = textContentFor(element);
+    const { occluder, coveredFraction } = occlusionCoverage(element, textRect);
     if (!occluder) return null;
+    if (!isAtomicLabel(text) && coveredFraction < PROSE_COVERAGE_FLOOR) return null;
     return {
       code: "text_occluded",
       severity: "error",
       time,
       selector: selectorFor(element),
       containerSelector: selectorFor(occluder),
-      text: textContentFor(element),
+      text,
       message: "Text is hidden beneath an opaque element.",
       rect: textRect,
+      coveredFraction,
       fixHint:
         "Give the text its own zone, raise its stacking order above the covering element, or mark intentional layering with data-layout-allow-occlusion.",
     };
   }
 
+  function candidateAnchor(element) {
+    const dataAttributes = {};
+    for (const attribute of Array.from(element.attributes)) {
+      if (attribute.name.startsWith("data-")) dataAttributes[attribute.name] = attribute.value;
+    }
+    const source = element
+      .closest("[data-composition-file]")
+      ?.getAttribute("data-composition-file");
+    return {
+      selector: uniqueSelectorFor(element),
+      dataAttributes,
+      sourceFile: source || "index.html",
+    };
+  }
+
+  function geometryCandidate(element, kind, rect, elementRect, rootRect, tolerance) {
+    const tag = element.tagName.toLowerCase();
+    const text = kind === "text" ? textContentFor(element, true) : tag;
+    const overflow = kind === "media" ? overflowFor(elementRect, rootRect, tolerance) : null;
+    return {
+      kind,
+      tag,
+      text,
+      rect,
+      elementRect,
+      ...candidateAnchor(element),
+      ...(overflow ? { overflow } : {}),
+    };
+  }
+
+  window.__hyperframesGeometryCandidates = function collectGeometryCandidates(options) {
+    const includeText = options?.text === true;
+    const includeMedia = options?.media === true;
+    if (!includeText && !includeMedia) return [];
+    const tolerance = typeof options?.tolerance === "number" ? options.tolerance : 2;
+    const root =
+      document.querySelector("[data-composition-id][data-width][data-height]") ||
+      document.querySelector("[data-composition-id]") ||
+      document.body;
+    const rootRect = rootRectFor(root);
+    const candidates = [];
+    for (const element of Array.from(document.querySelectorAll("body *"))) {
+      if (element.closest('[data-composition-id="captions"], .caption-layer, #caption-stage')) {
+        continue;
+      }
+      if (!isVisibleElement(element, 0.05, false)) continue;
+      const elementRect = toRect(element.getBoundingClientRect());
+      if (includeText && hasOwnTextCandidate(element, true)) {
+        const rect = textRectFor(element, true);
+        if (rect) {
+          candidates.push(
+            geometryCandidate(element, "text", rect, elementRect, rootRect, tolerance),
+          );
+        }
+      }
+      if (includeMedia && FRAME_MEDIA_TAGS.has(element.tagName.toUpperCase())) {
+        candidates.push(
+          geometryCandidate(element, "media", elementRect, elementRect, rootRect, tolerance),
+        );
+      }
+    }
+    return candidates;
+  };
+
   window.__hyperframesLayoutAudit = function auditLayout(options) {
     const time = options && typeof options.time === "number" ? options.time : 0;
     const tolerance =
@@ -712,7 +869,9 @@
       document.querySelector("[data-composition-id]") ||
       document.body;
     const rootRect = rootRectFor(root);
-    const elements = Array.from(root.querySelectorAll("*")).filter(isVisibleElement);
+    const elements = Array.from(root.querySelectorAll("*")).filter((element) =>
+      isVisibleElement(element),
+    );
     const issues = [];
 
     for (const element of elements) {
@@ -728,4 +887,28 @@
     issues.push(...contentOverlapIssues(root, time));
     return issues;
   };
+
+  // Frozen-sweep guard (#U10, checkPipeline.ts): a compact per-sample
+  // fingerprint of every visible element's box + opacity, in DOM order. Node
+  // calls this once per seeked grid point and compares the strings across the
+  // whole run — if every sample produces the identical string, the seek never
+  // actually moved anything and the whole audit run is unreliable. Deliberately
+  // a single opaque string (not a structured array) since Node only ever needs
+  // equality, not per-element diffing.
+  window.__hyperframesLayoutGeometry = function collectLayoutGeometry() {
+    const root =
+      document.querySelector("[data-composition-id][data-width][data-height]") ||
+      document.querySelector("[data-composition-id]") ||
+      document.body;
+    const elements = Array.from(root.querySelectorAll("*")).filter((element) =>
+      isVisibleElement(element),
+    );
+    return elements
+      .map((element) => {
+        const rect = toRect(element.getBoundingClientRect());
+        const opacity = round(opacityChain(element));
+        return `${rect.left},${rect.top},${rect.width},${rect.height},${opacity}`;
+      })
+      .join("|");
+  };
 })();