mosaic-headless 1.7.0 → 1.9.0

package/tools/verify_browser.py

@@ -34,6 +34,14 @@ AUDIT     what only a browser knows, checked whether or not it was declared: fon
           fallback, tracking against script, text contrast, horizontal overflow,
           clipped text, and line measure.
 
+          Its scope is stated rather than implied: readings are taken with the page
+          at rest at scroll-top, so a defect that only exists part-way down a scroll
+          - a fixed element crossing a band of a different colour - is outside what
+          this pass sees. The contrast check does hit-test the ground behind a fixed
+          or sticky element rather than walking its ancestors, so it would find such
+          a case if it were looking there; it simply is not scrolling. `verify_intro`
+          samples over time; nothing here yet samples over scroll.
+
 Exit status is non-zero if any declaration is OVERRIDDEN or any audit finding is
 rated `error`.
 """
@@ -307,11 +315,31 @@ PROBE = r"""
 
   // Effective background behind a text node, for contrast. Walks up until something
   // is actually painted; a transparent parent is not a background.
+  const solid = b => {
+    const n = (b.match(/[\d.]+/g) || []).map(Number);
+    return (n.length >= 3 && (n.length < 4 || n[3] > 0.55)) ? n.slice(0, 3) : null;
+  };
   const bgOf = el => {
+    const cs0 = getComputedStyle(el);
+    // A FIXED or STICKY element does not sit on its ancestors - it sits on whatever
+    // the page has scrolled underneath it, and the ancestor chain knows nothing
+    // about that. The clause index on this page is fixed to the left margin in a
+    // faint grey; when an accent-coloured band scrolls behind it the text becomes
+    // unreadable, and walking parents reports the paper ground it was declared on
+    // and passes. Hit-testing is the only way to ask what is actually back there.
+    if (cs0.position === 'fixed' || cs0.position === 'sticky') {
+      const r = el.getBoundingClientRect();
+      const x = Math.min(Math.max(r.left + r.width / 2, 1), innerWidth - 1);
+      const y = Math.min(Math.max(r.top + r.height / 2, 1), innerHeight - 1);
+      for (const under of document.elementsFromPoint(x, y)) {
+        if (under === el || el.contains(under) || under.contains(el)) continue;
+        const c = solid(getComputedStyle(under).backgroundColor);
+        if (c) return c;
+      }
+    }
     for (let p = el; p; p = p.parentElement) {
-      const b = getComputedStyle(p).backgroundColor;
-      const n = (b.match(/[\d.]+/g) || []).map(Number);
-      if (n.length >= 3 && (n.length < 4 || n[3] > 0.55)) return n.slice(0, 3);
+      const c = solid(getComputedStyle(p).backgroundColor);
+      if (c) return c;
     }
     return [255, 255, 255];
   };
@@ -363,8 +391,22 @@ PROBE = r"""
         sample: own.slice(0, 24)});
     }
 
-    const fg = (cs.color.match(/[\d.]+/g) || []).map(Number).slice(0, 3);
-    if (fg.length === 3) {
+    // Text can be painted by something other than `color`. A headline using
+    // `background-clip:text` sets `color:transparent`, and a naive parse reads
+    // rgba(0,0,0,0) as pure black - which then scores a perfect contrast ratio
+    // against any light ground. That is a blind spot scoring itself as a pass, so
+    // it gets its own finding instead: the check cannot run here, and says so.
+    const rgba = (cs.color.match(/[\d.]+/g) || []).map(Number);
+    if (rgba.length === 4 && rgba[3] < 0.05) {
+      out.audit.push({check: 'TEXT_CLIP', level: 'warn', node: id,
+                      detail: 'color is ' + cs.color + '; painted by ' +
+                              (cs.backgroundClip === 'text' ? 'background-clip:text'
+                                                            : 'something else') +
+                              ' - contrast NOT checked here',
+                      sample: own.slice(0, 24)});
+    }
+    const fg = rgba.slice(0, 3);
+    if (fg.length === 3 && !(rgba.length === 4 && rgba[3] < 0.05)) {
       const r = ratio(fg, bgOf(el));
       const large = size >= 24 || (size >= 18.66 && px(cs.fontWeight) >= 700);
       const need = large ? 3.0 : 4.5;
@@ -577,8 +619,12 @@ def main():
                             f.get("sample", "")])
         print("wrote %s (%d findings)" % (a.audit, len(audit)))
 
-    print("\n%s" % ("PASS - every comparable declaration is what the browser "
-                    "computed, and the audit is clean"
+    # "clean" was overstating it once the audit began reporting blind spots as
+    # warnings. A run carrying two labelled unknowns is not a run carrying none, and
+    # the summary line is the part people read.
+    print("\n%s" % (("PASS - every comparable declaration is what the browser "
+                     "computed; 0 audit errors, %d warnings"
+                     % (len(audit) - len(errors)))
                     if not hard else
                     "FAIL - %d overridden declarations, %d audit errors"
                     % (counts.get("OVERRIDDEN", 0), len(errors))))

package/tools/verify_intro.py

@@ -72,7 +72,14 @@ PROBE = r"""
       pointerEvents: cs.pointerEvents,
       clipPath: cs.clipPath,
       transform: cs.transform,
-      counter: cs.getPropertyValue('--mk-n').trim(),
+      // Every registered custom property this element carries, not one name
+      // picked in advance. The counters are drawn by `::after` through
+      // `counter()`, so `textContent` is empty and computed `content` comes back
+      // as the literal `counter(s, decimal-leading-zero)` rather than the digits -
+      // the animated integer underneath is the only readable trace they leave.
+      // Hard-coding `--mk-n` meant a running clock counted as motionless.
+      counter: Array.from(cs).filter(p => p.startsWith('--'))
+                    .map(p => p + '=' + cs.getPropertyValue(p).trim()).join(';'),
       text: (el.textContent || '').trim().slice(0, 24),
       w: Math.round(r.width), h: Math.round(r.height),
     };
@@ -115,7 +122,12 @@ PROBE = r"""
 
 
 def read_ids(spec, slug):
-    """Every attrID on the page, split into veil and content."""
+    """Every attrID the visitor will see - the page tree AND the shell.
+
+    Walking only `page["tree"]` misses the header and footer entirely, because in
+    Mosaic those live on the master rather than on the template. The running clock
+    is in the header, so a check for "is anything still moving" could not see the
+    one element built specifically to always be moving."""
     ids = []
 
     def walk(node):
@@ -129,6 +141,9 @@ def read_ids(spec, slug):
             for v in node:
                 walk(v)
 
+    shell = spec.get("shell") or {}
+    walk(shell.get("header"))
+    walk(shell.get("footer"))
     for page in spec["pages"]:
         if page["slug"] == slug:
             walk(page.get("tree"))
@@ -206,6 +221,8 @@ def main():
     ap.add_argument("--page")
     ap.add_argument("--veil-prefix", default="mk-boot",
                     help="ids under this prefix are the intro, not the content")
+    ap.add_argument("--min-ambient", type=int, default=3,
+                    help="how many elements must still be moving once settled")
     ap.add_argument("--deadline-ms", type=int, default=4200,
                     help="by this point the intro must be over")
     ap.add_argument("--csv")
@@ -248,9 +265,13 @@ def main():
                    "%d of %d intro elements changed state" % (len(veil_moved),
                                                               len(veil))))
     # the counter is an animated integer, so it can be read rather than admired
-    counters = [(r["t_ms"], (r["nodes"].get(a.veil_prefix + "-num") or {})
-                 .get("counter", "")) for r in readings]
-    nums = [int(c) for _t, c in counters if c.isdigit()]
+    import re as _re
+    nums = []
+    for r in readings:
+        sig = (r["nodes"].get(a.veil_prefix + "-num") or {}).get("counter", "")
+        hit = _re.search(r"--mk-n=(-?\d+)", sig)
+        if hit:
+            nums.append(int(hit.group(1)))
     checks.append(("COUNTS", bool(nums) and max(nums) >= 99,
                    "--mk-n reached %s" % (max(nums) if nums else "nothing")))
 
@@ -271,6 +292,29 @@ def main():
     cleared = bool(clicked) and not str(clicked).startswith(a.veil_prefix)
     checks.append(("CLEARS", cleared, "a real click landed on %r" % clicked))
 
+    # AMBIENT - does anything still move once the page has settled?
+    #
+    # Every other motion check here fires on an event: the document loading, an
+    # element entering the viewport. A page can pass all of them and still be
+    # completely static the moment you stop scrolling, which is a real quality a
+    # reader notices and nothing was measuring. So: take the last two readings,
+    # both well past the intro, and count how many elements differ between them.
+    settled = [r for r in readings if r["t_ms"] >= a.deadline_ms]
+    moving = set()
+    if len(settled) >= 2:
+        first, last_ = settled[-2], settled[-1]
+        for i in ids:
+            x, y = first["nodes"].get(i), last_["nodes"].get(i)
+            if not x or not y:
+                continue
+            if (x["transform"], x["opacity"], x["counter"], x["text"]) !=                (y["transform"], y["opacity"], y["counter"], y["text"]):
+                moving.add(i)
+    checks.append(("AMBIENT", len(moving) >= a.min_ambient,
+                   "%d elements still moving between %dms and %dms with no input: %s"
+                   % (len(moving), settled[-2]["t_ms"] if len(settled) >= 2 else 0,
+                      settled[-1]["t_ms"] if settled else 0,
+                      ", ".join(sorted(moving)[:6]) or "nothing")))
+
     # DEGRADES
     red, red_click, _ = run(url, ids, True, None)
     first = red[0]