@techierathore/techieflow 1.0.4 → 1.1.1

package/.tfcore/utils/tf-status-facts.py

@@ -14,7 +14,10 @@ into the template (.tfcore/templates/v4custom/app-project-status-tmpl.md):
   - the Open requirements section (counts by status, at most ten named rows)
   - the Verification log table with its new row (last five kept)
   - the Library feedback summary lines
-  - the Next command to run, in both harness forms, and why
+  - the Next command to run, in both harness forms, and why. On a project with more than one
+    phase a verify names its phase (`*verify ui <App> --phase 3`), and built rows waiting in
+    another phase's checklist are found too: `--phase N` for one, `--phase all` for several
+    (Sevak TF-005). A build of this phase still comes first.
 
 Writes nothing. The agent writes PROJECT-STATUS.md with the harness Write tool.
 Python 3 standard library only. Exit 0 printed, 2 could not run.
@@ -27,6 +30,7 @@ import re
 import sys
 
 TERMINAL = {"verified", "done (pre-existing)", "n/a"}
+NA = {"n/a"}                         # terminal, but never counted as verified (TF-018)
 PASS_THROUGH = {"blocked"}           # a library gap; counts as closed for the ladder
 BUILT = {"implemented", "needs re-verify"}
 OWNER = {"owner-uat"}                # only the owner can close it, from the UsageGuide test plan
@@ -61,6 +65,9 @@ def read(path):
 
 
 def checklist_rows(text):
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+    import tf_roadmap
+    marked = tf_roadmap.ids(text)
     rows = []
     for line in text.splitlines():
         if not re.match(r"^\s*\|\s*`?REQ-", line):
@@ -69,10 +76,34 @@ def checklist_rows(text):
         if len(cells) < 3:
             continue
         rid = cells[0].strip("`* ")
-        rows.append({"id": rid, "name": cells[1].strip("`* "), "status": norm_status(cells[2])})
+        status = norm_status(cells[2])
+        rows.append({"id": rid, "name": cells[1].strip("`* "), "status": status,
+                     "remarks": cells[4] if len(cells) > 4 else "",
+                     "roadmap": rid.upper() in marked and status.lower() not in TERMINAL})
     return rows
 
 
+def figures(rows):
+    """(verified, counted, not applicable). An N/A row is terminal but was never verified, so it is
+    left out of both numbers and named: AppManager read "89 of 89 verified" with REQ-NFR-008 at N/A
+    (TF-018). tests/regression/run.sh am_018."""
+    na = sum(1 for r in rows if r["status"].lower() in NA)
+    return sum(1 for r in rows if r["status"].lower() in TERMINAL - NA), len(rows) - na, na
+
+
+# The defect marks live in tf_defect.py. A bare ⚠ is not enough: sending "not verifiable here" to a
+# build is the TfLens loop again.
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from tf_defect import DEFECT  # noqa: E402
+
+
+def has_defect(r):
+    """A Needs re-verify row whose Remarks carry a framework defect mark holds a defect no fix has
+    cleared, and a verify of the acceptance line cannot see it. So it is fix work, as build-phase step 7
+    and tf-build-list say, never a verify (AppManager TF-019). tests/regression/run.sh am_019."""
+    return r["status"].lower() == "needs re-verify" and bool(DEFECT.search(r.get("remarks", "")))
+
+
 def ladder_rank(status):
     return LADDER.index(status) if status in LADDER else 0
 
@@ -142,24 +173,29 @@ def existing_log_rows(status_text):
     return rows
 
 
-def handoff_ran(log_rows):
-    return any("handoff" in r.lower() for r in log_rows)
+def handoff_ran(log_rows, app="", phase=1):
+    """A handoff of THIS phase: a log row naming handoff whose status-table cell names this phase's
+    checklist. Phase 2's handoff counted for phase 3, so a newly built phase read "handoff done" and
+    sent the owner to UAT with guides that did not describe it (TechieRag TF-003). A row naming no
+    checklist (an older log) counts in phase 1 only, where nothing else could be meant."""
+    own = f"{phase_prefix(app, phase)}Checklist.md" if app else ""
+    for r in log_rows:
+        if "handoff" not in r.lower():
+            continue
+        named = re.findall(r"[\w.-]+-Checklist\.md", r)
+        if (own in named) if named and own else (phase <= 1):
+            return True
+    return False
 
 
 def feedback_lines(root, app):
-    out = []
-    for path in sorted(glob.glob(os.path.join(root, "docs", f"{app}-*-Feedback.md"))):
-        lib = re.sub(rf"^{re.escape(app)}-(.+)-Feedback\.md$", r"\1", os.path.basename(path))
-        text = read(path)
-        entries = re.split(r"(?m)^###\s+", text)[1:]
-        open_n = 0
-        for e in entries:
-            closed = re.search(r"(?im)^\s*[-*]\s*\*\*(status|resolved|fixed)[^:]*:\*\*\s*(fixed|resolved|closed|done)", e)
-            if not closed:
-                open_n += 1
-        rel = os.path.relpath(path, root).replace(os.sep, "/")
-        out.append(f"- {lib}: {open_n} open of {len(entries)} — {rel}")
-    return out or ["- None"]
+    # One reader for every script (tf_feedback.py). This function used to count every `###`
+    # heading as an entry and accept only a closing line no file used, so TfLens's status read
+    # "TechieFlow: 62 open of 62" for 27 entries, 19 of them fixed or closed, and the agent told
+    # the owner two fixed problems were open (MISS-TechieFlow-20260911-04).
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+    import tf_feedback
+    return [tf_feedback.summary_line(p, app) for p in tf_feedback.files(root, app)] or ["- None"]
 
 
 def config_phase(root):
@@ -171,6 +207,13 @@ def config_phase(root):
     return 1
 
 
+def config_library(root):
+    """metrics.project_type: library (or appKind: library): the documents ship inside the package."""
+    p = os.path.join(root, ".tfcore", "core-config.yaml")
+    t = read(p) if os.path.isfile(p) else ""
+    return bool(re.search(r"(?m)^\s+project_type:\s*['\"]?lib", t) or re.search(r"(?m)^appKind:\s*['\"]?lib", t))
+
+
 def phase_prefix(app, phase):
     return f"{app}-" if phase <= 1 else f"{app}-P{phase}-"
 
@@ -191,9 +234,48 @@ def phase_row(root, app, phase):
     return name, total
 
 
-def next_command(app, rows, log_rows, phase=1, verdicts=None):
-    """Returns (phase, qualifier, cc_line, oc_line, reason)."""
+def usage_guide(app):
+    """UsageGuide or Usage-Guide, whichever exists: tf-verify-list.py's reader (AppManager TF-022)."""
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("tf_verify_list", os.path.join(os.path.dirname(os.path.abspath(__file__)), "tf-verify-list.py"))
+    vl = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(vl)
+    return vl.usage_guide(app)
+
+
+def to_verify(rows, verdicts):
+    """(waiting, unmeasured): built rows a verify should grade, and built rows the last verify could
+    not measure (every test skipped). Roadmap rows and rows carrying a defect are neither."""
+    built = [r for r in rows if not r.get("roadmap") and r["status"].lower() in BUILT and not has_defect(r)]
+    unmeasured = [r for r in built if verdicts.get(r["id"]) == "NOT-TESTED"]
+    return [r for r in built if r not in unmeasured], unmeasured
+
+
+def scope_of(rows):
+    ui = [r for r in rows if r["id"].startswith("REQ-UI")]
+    return "ui" if len(ui) == len(rows) else ("functional" if not ui else "all")
+
+
+def other_phases(root, app, phase_n, verdicts):
+    """{phase: rows waiting for a verify} for every other phase with a checklist (Sevak TF-005: phases 1
+    and 2 held 86 rows waiting while the status read only phase 3's checklist)."""
+    found = {}
+    for f in sorted(os.listdir(os.path.join(root, "docs"))) if os.path.isdir(os.path.join(root, "docs")) else []:
+        m = re.fullmatch(re.escape(app) + r"-(?:P(\d+)-)?Checklist\.md", f)
+        p = int(m.group(1) or 1) if m else 0
+        if not p or p == phase_n:
+            continue
+        waiting, _ = to_verify(checklist_rows(read(os.path.join(root, "docs", f))), verdicts)
+        if waiting:
+            found[p] = waiting
+    return dict(sorted(found.items()))
+
+
+def next_command(app, rows, log_rows, phase=1, verdicts=None, library=False, multi=False):
+    """Returns (phase, qualifier, cc_line, oc_line, reason). multi: the project has more than one
+    phase, so a verify names the phase it grades."""
     verdicts = verdicts or {}
+    pflag = f" --phase {phase}" if multi else ""
 
     def ids(lst):
         return ", ".join(r["id"] for r in lst[:6]) + (" …" if len(lst) > 6 else "")
@@ -207,17 +289,24 @@ def next_command(app, rows, log_rows, phase=1, verdicts=None):
                 f"{CC}analyst *day1-greenfield {app}", f"{OC}flow-analyst *day1-greenfield {app}",
                 "no BRD and no checklist exist; day-1 stage 1 has not run")
 
-    unbuilt = [r for r in rows if r["status"].lower() not in TERMINAL | PASS_THROUGH | BUILT | OWNER]
-    built = [r for r in rows if r["status"].lower() in BUILT]
-    owner = [r for r in rows if r["status"].lower() in OWNER]
-    total = len(rows)
-    closed = sum(1 for r in rows if r["status"].lower() in TERMINAL)
-    q = f"{closed} of {total} verified"
-
-    if unbuilt:
-        return ("Build", f"{len(unbuilt)} not built, {q}",
-                f"{CC}flow-master *build-phase {app}", f"{OC}flow-master *build-phase {app}",
-                f"{len(unbuilt)} rows are not built yet: {ids(unbuilt)}")
+    # A roadmap row is not this phase's work, so it never decides the next command (TF-017).
+    now = [r for r in rows if not r.get("roadmap")]
+    unbuilt = [r for r in now if r["status"].lower() not in TERMINAL | PASS_THROUGH | BUILT | OWNER]
+    defects = [r for r in now if has_defect(r)]
+    waiting, unmeasured = to_verify(now, verdicts)
+    built = waiting + unmeasured
+    owner = [r for r in now if r["status"].lower() in OWNER]
+    verified, counted, na = figures(rows)
+    q = f"{verified} of {counted} verified" + (f", {na} not applicable" if na else "")
+
+    if unbuilt or defects:
+        qual = ", ".join(x for x in (f"{len(unbuilt)} not built" if unbuilt else "",
+                                     f"{len(defects)} to fix" if defects else "") if x)
+        why = "; ".join(x for x in (f"{len(unbuilt)} rows are not built yet: {ids(unbuilt)}" if unbuilt else "",
+                                    f"{len(defects)} rows carry a defect (⚠ in Remarks) that a fix must clear before "
+                                    f"a verify: {ids(defects)}" if defects else "") if x)
+        return ("Build", f"{qual}, {q}",
+                f"{CC}flow-master *build-phase {app}", f"{OC}flow-master *build-phase {app}", why)
     if built:
         # A row the last verify could not MEASURE is not a row waiting for another verify.
         # Its tests declined — the state they need does not exist in this environment — so
@@ -225,37 +314,40 @@ def next_command(app, rows, log_rows, phase=1, verdicts=None):
         # loop that looks like progress. Say what it actually needs: data, a changed
         # acceptance line, or the row marked N/A. Only the owner can choose. FR-69's sibling
         # case; the verdicts come from the ledger the verifier already writes.
-        unmeasured = [r for r in built if verdicts.get(r["id"]) == "NOT-TESTED"]
-        waiting = [r for r in built if r not in unmeasured]
         if unmeasured and not waiting:
             line = (f"(owner) {len(unmeasured)} row(s) cannot be measured here — create the data, "
                     f"change the acceptance line, or mark the row N/A: {ids(unmeasured)}")
             return ("Verify", f"{len(unmeasured)} not measurable, {q}", line, line,
                     f"every test carrying these ids was skipped, so another verify run changes nothing: {ids(unmeasured)}")
-        ui = [r for r in waiting if r["id"].startswith("REQ-UI")]
-        scope = "ui" if len(ui) == len(waiting) else ("functional" if not ui else "all")
+        scope = scope_of(waiting)
         reason = f"{len(waiting)} rows are built and not verified: {ids(waiting)}"
         if unmeasured:
             reason += (f"; {len(unmeasured)} more could not be measured (every test skipped) "
                        f"and need the owner: {ids(unmeasured)}")
         return ("Verify", f"{len(waiting)} to verify, {q}",
-                f"{CC}verifier *verify {scope} {app}", f"{OC}flow-verifier *verify {scope} {app}",
+                f"{CC}verifier *verify {scope} {app}{pflag}", f"{OC}flow-verifier *verify {scope} {app}{pflag}",
                 reason)
     if owner:
-        if handoff_ran(log_rows):
-            line = f"(owner-run) docs/{app}-UsageGuide.md — {ids(owner)}"
+        if handoff_ran(log_rows, app, phase):
+            line = f"(owner-run) {usage_guide(app)} — {ids(owner)}"
             return ("UAT", f"{len(owner)} owner-run, {q}", line, line,
                     f"{len(owner)} rows are Owner-UAT and handoff has run; the owner closes them")
         return ("Handoff", f"{len(owner)} owner-run, {q}",
                 f"{CC}flow-master *handoff-phase {app}", f"{OC}flow-master *handoff-phase {app}",
                 f"{len(owner)} rows are Owner-UAT and handoff has not run yet")
-    if handoff_ran(log_rows):
+    if handoff_ran(log_rows, app, phase):
+        if library:
+            # a library's fix runs the handoff steps itself, before the gate, so the package ships with
+            # its documents; *handoff-phase after the release was the wrong order (TrBlazeUI TF-005)
+            line = "(owner) commit, then build and publish the package — its shipped documents are current; no agent command"
+            return ("Release", f"handoff done, {q}", line, line,
+                    "every row in this phase's scope is terminal and the shipped documents were brought up to date")
         line = "(owner) set current_phase to Released after UAT — no agent command"
         return ("UAT", f"handoff done, {q}", line, line,
-                "every row is terminal and handoff has run; waiting on the owner")
+                "every row in this phase's scope is terminal and handoff has run; waiting on the owner")
     return ("Handoff", q,
             f"{CC}flow-master *handoff-phase {app}", f"{OC}flow-master *handoff-phase {app}",
-            "every row is terminal and handoff has not run yet")
+            "every row in this phase's scope is terminal and handoff has not run yet")
 
 
 def main(argv):
@@ -283,15 +375,38 @@ def main(argv):
     st_text = read(st_path) if os.path.isfile(st_path) else ""
     log_rows = existing_log_rows(st_text)
     vdate, vresult = last_verify(root, app)
-    phase, qual, cc, oc, reason = next_command(app, rows, log_rows, phase_n, ledger_verdicts(root))
+    verdicts = ledger_verdicts(root)
+    others = other_phases(root, app, phase_n, verdicts)
     pname, ptotal = phase_row(root, app, phase_n)
+    multi = phase_n > 1 or (ptotal or 0) > 1 or bool(others)
+    phase, qual, cc, oc, reason = next_command(app, rows, log_rows, phase_n, verdicts, config_library(root), multi)
+    if others:
+        # A verify of another phase names that phase, or --phase all when several phases wait; a build
+        # of this phase still goes first.
+        n = sum(len(w) for w in others.values())
+        where = "; ".join(f"phase {p}: {len(w)} ({', '.join(r['id'] for r in w[:4])}{' …' if len(w) > 4 else ''})"
+                          for p, w in others.items())
+        mine, _ = to_verify(rows, verdicts)
+        if phase == "Build":
+            reason += f"; after this build, {n} built rows of other phases wait for a verify — {where}"
+        else:
+            pick = list(others) + ([phase_n] if mine else [])
+            flag = f"--phase {pick[0]}" if len(pick) == 1 else "--phase all"
+            scope = scope_of([r for w in others.values() for r in w] + mine)
+            cc, oc = f"{CC}verifier *verify {scope} {app} {flag}", f"{OC}flow-verifier *verify {scope} {app} {flag}"
+            reason = (f"{n} rows of other phases are built and not verified — {where}"
+                      + (f"; and in this phase: {reason}" if phase == "Verify" else f"; this phase alone would be: {qual} ({reason})"))
+            phase, qual = "Verify", f"{n + len(mine)} to verify across phases {', '.join(map(str, sorted(pick)))}, {qual}"
+    roadmap = [r["id"] for r in rows if r["roadmap"]]
+    if roadmap:
+        reason += (f"; {len(roadmap)} roadmap row(s) are not in this phase's scope and are left for the owner "
+                   f"(*amend-docs): {', '.join(roadmap)}")
     if ptotal or phase_n > 1:
         tag = f"Phase {phase_n} of {ptotal or '?'}" + (f" ({pname})" if pname else "")
         phase = f"{tag} · {phase}"
         reason = f"{reason}; working {cl_rel}"
 
-    total = len(rows)
-    closed = sum(1 for r in rows if r["status"].lower() in TERMINAL)
+    verified, counted, na = figures(rows)
     counts = {}
     for r in rows:
         counts[r["status"]] = counts.get(r["status"], 0) + 1
@@ -322,7 +437,7 @@ def main(argv):
     print()
     if open_rows:
         for r in open_rows[:10]:
-            print(f"- [ ] {r['id']} — {r['name']} ({r['status']})")
+            print(f"- [ ] {r['id']} — {r['name']} ({r['status']}{', roadmap — not in this phase' if r['roadmap'] else ''})")
         if len(open_rows) > 10:
             print(f"- ({len(open_rows) - 10} more open rows in {cl_rel})")
     else:
@@ -332,7 +447,7 @@ def main(argv):
     print("Last five passes; older passes live in `docs/metrics/gates.jsonl`.")
     print()
     print("| Date | Phase | Result | Status table |\n|---|---|---|---|")
-    new_row = f"| {today} | {label} | {closed}/{total} Verified | {cl_rel}#requirements-status |"
+    new_row = f"| {today} | {label} | {verified}/{counted} Verified{f', {na} N/A' if na else ''} | {cl_rel}#requirements-status |"
     for r in (log_rows[-4:] if len(log_rows) > 4 else log_rows):
         print(r)
     print(new_row)

package/.tfcore/utils/tf-theme.mjs

@@ -0,0 +1,189 @@
+// tf-theme.mjs — draw a page in its light or its dark theme, and measure what a reader sees in it.
+// Shared by tf-verify-screens and tf-mockup-parity, as tf-login.mjs is (Lekhak TF-024).
+//
+// Why: every screen was graded in light mode only. Lekhak's owner then found 20 of 20 desktop admin
+// screens unreadable in dark mode (text at 1.03 : 1, white panels inside a dark shell), all Verified.
+//
+// A theme is put on a page the two ways a stack listens for one, knowing nothing about the stack:
+//   - the browser's colour scheme (prefers-color-scheme), emulated;
+//   - the light/dark value of every data-*theme/mode/scheme attribute on <html> and <body>, and the
+//     light/dark mode classes there (dark, theme-dark …). A page that declares none is given
+//     data-theme and data-bs-theme; a page with no such class is given, for dark, the class `dark`
+//     (Tailwind's switch, and the one an app setting data-theme and the class together also reads).
+// Each call returns a function that puts the page back the way it was: an attached desktop head is
+// the viewer's app. A page whose painted surface does not change between the two has no dark theme;
+// `surface` and `differs` tell. `audit` is the contrast rule the visual check applies.
+
+export const THEMES = ['light', 'dark'];
+
+// --themes light,dark | light | dark | auto (the default: light, and dark when the app has one)
+export function parseThemes(v) {
+  const s = String(v || 'auto').toLowerCase().trim();
+  if (s === 'auto') return null;
+  const t = [...new Set(s.split(',').map((x) => x.trim()).filter((x) => THEMES.includes(x)))];
+  return t.length ? t : null;
+}
+
+const FORCE = (want) => {
+  const MODE = /^(?:(?:theme|mode|scheme|color)[-_])?(?:dark|light)(?:[-_](?:theme|mode|scheme))?$/i;
+  const other = want === 'dark' ? /light/ig : /dark/ig;
+  const before = [];
+  let declared = false, classed = false;
+  for (const [where, el] of [['html', document.documentElement], ['body', document.body]]) {
+    if (!el) continue;
+    for (const a of [...el.attributes]) {
+      if (!/^data-.*(theme|mode|scheme)/i.test(a.name) || !/(dark|light)/i.test(a.value)) continue;
+      declared = true;
+      before.push({ where, attr: a.name, value: a.value });
+      el.setAttribute(a.name, a.value.replace(other, want));
+    }
+    const toks = [...el.classList].filter((c) => MODE.test(c));
+    if (toks.length) {
+      declared = classed = true;
+      before.push({ where, cls: toks });
+      for (const c of toks) { el.classList.remove(c); el.classList.add(c.replace(other, want)); }
+    }
+  }
+  if (!declared) {
+    const h = document.documentElement;
+    for (const name of ['data-theme', 'data-bs-theme']) {
+      if (h.hasAttribute(name)) continue;            // a theme by name (data-theme="corporate") is left alone
+      before.push({ where: 'html', attr: name, value: null });
+      h.setAttribute(name, want);
+    }
+  }
+  // a page with no light/dark class gets `dark` for the dark pass even when it declared data-theme:
+  // an app whose switch sets both (Lekhak) was otherwise drawn half dark, a state it never shows (Lekhak TF-033)
+  const h = document.documentElement;
+  if (want === 'dark' && !classed && !h.classList.contains('dark')) { before.push({ where: 'html', added: 'dark' }); h.classList.add('dark'); }
+  return before;
+};
+
+const RESTORE = (before) => {
+  for (const b of [...before].reverse()) {
+    const el = b.where === 'body' ? document.body : document.documentElement;
+    if (!el) continue;
+    if (b.added) el.classList.remove(b.added);
+    else if (b.cls) {
+      for (const c of [...el.classList]) if (/^(?:(?:theme|mode|scheme|color)[-_])?(?:dark|light)(?:[-_](?:theme|mode|scheme))?$/i.test(c)) el.classList.remove(c);
+      for (const c of b.cls) el.classList.add(c);
+    } else if (b.value === null) el.removeAttribute(b.attr);
+    else el.setAttribute(b.attr, b.value);
+  }
+};
+
+// Draws the page in `want` and returns the function that puts it back.
+export async function useTheme(page, want, settle = 350) {
+  await page.emulateMedia({ colorScheme: want }).catch(() => {});
+  const before = await page.evaluate(FORCE, want).catch(() => null);
+  if (settle) await page.waitForTimeout(settle);
+  return async () => {
+    if (before) await page.evaluate(RESTORE, before).catch(() => {});
+    await page.emulateMedia({ colorScheme: null }).catch(() => {});
+  };
+}
+
+// The luminance painted at five points of the window (and behind <body>), 0 = black, 1 = white.
+const SURFACE = () => {
+  // the browser converts the colour, never a regex: a page themed in oklch() reads back as "oklch(…)",
+  // which an rgb() pattern skipped, so every surface counted as white and no dark theme was seen (Sevak TF-005)
+  const cv = document.createElement('canvas'); cv.width = cv.height = 1;
+  const cx = cv.getContext('2d', { willReadFrequently: true });
+  const parse = (c) => { if (!c || c === 'transparent' || !cx) return null; cx.clearRect(0, 0, 1, 1); cx.fillStyle = 'rgba(0,0,0,0)'; cx.fillStyle = String(c); cx.fillRect(0, 0, 1, 1); const d = cx.getImageData(0, 0, 1, 1).data; return [d[0], d[1], d[2], d[3] / 255]; };
+  const lum = (c) => { const f = (v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); }; return 0.2126 * f(c[0]) + 0.7152 * f(c[1]) + 0.0722 * f(c[2]); };
+  const behind = (el) => {
+    const layers = [];
+    for (let e = el; e; e = e.parentElement) { const c = parse(getComputedStyle(e).backgroundColor); if (c && c[3] > 0) { layers.push(c); if (c[3] >= 0.99) break; } }
+    let out = layers.length && layers[layers.length - 1][3] >= 0.99 ? layers.pop() : [255, 255, 255, 1];
+    while (layers.length) { const t = layers.pop(), a = t[3]; out = [t[0] * a + out[0] * (1 - a), t[1] * a + out[1] * (1 - a), t[2] * a + out[2] * (1 - a), 1]; }
+    return out;
+  };
+  const w = window.innerWidth, h = window.innerHeight;
+  const pts = [[0.5, 0.5], [0.2, 0.3], [0.8, 0.3], [0.2, 0.8], [0.8, 0.8]];
+  return [document.body, ...pts.map(([x, y]) => document.elementFromPoint(x * w, y * h))].map((el) => (el ? +lum(behind(el)).toFixed(3) : null));
+};
+export const surface = (page) => page.evaluate(SURFACE).catch(() => null);
+// two surface readings differ when any point's luminance moved by more than 0.15
+export const differs = (a, b) => !!a && !!b && a.some((x, i) => x !== null && b[i] !== null && Math.abs(x - b[i]) > 0.15);
+// a reading that is mostly dark: the theme a mockup that declares none is drawn in
+export const looksDark = (s) => !!s && s.filter((x) => x !== null && x < 0.2).length > s.filter((x) => x !== null).length / 2;
+
+// The contrast rule (Lekhak TF-024), measured on what is painted:
+//   - every visible text run and form-field value reaches `min` : 1 (3.0, WCAG AA for large text)
+//     against the first opaque background behind it; disabled controls are exempt, as WCAG exempts
+//     them, and text over an image or a gradient is not measured (the colour behind it is not one);
+//   - in dark mode, no box larger than 2% of the window paints a background lighter than 0.8
+//     relative luminance (a white card or panel left in a dark shell).
+// Returns { low: [...], light: [...], low_n, light_n }, each list cut to `cap`.
+const AUDIT = ({ dark, min, cap }) => {
+  const cv = document.createElement('canvas'); cv.width = cv.height = 1;   // oklch() and every other syntax, as SURFACE
+  const cx = cv.getContext('2d', { willReadFrequently: true });
+  const parse = (c) => { if (!c || c === 'transparent' || !cx) return null; cx.clearRect(0, 0, 1, 1); cx.fillStyle = 'rgba(0,0,0,0)'; cx.fillStyle = String(c); cx.fillRect(0, 0, 1, 1); const d = cx.getImageData(0, 0, 1, 1).data; return [d[0], d[1], d[2], d[3] / 255]; };
+  const lum = (c) => { const f = (v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); }; return 0.2126 * f(c[0]) + 0.7152 * f(c[1]) + 0.0722 * f(c[2]); };
+  const ratio = (a, b) => { const x = lum(a), y = lum(b); return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05); };
+  const blend = (t, u) => { const a = t[3]; return [t[0] * a + u[0] * (1 - a), t[1] * a + u[1] * (1 - a), t[2] * a + u[2] * (1 - a), 1]; };
+  const behind = (el) => {
+    const layers = [];
+    for (let e = el; e; e = e.parentElement) {
+      const cs = getComputedStyle(e);
+      if (cs.backgroundImage && cs.backgroundImage !== 'none') return null;   // an image or a gradient
+      const c = parse(cs.backgroundColor);
+      if (c && c[3] > 0) { layers.push(c); if (c[3] >= 0.99) break; }
+    }
+    let out = layers.length && layers[layers.length - 1][3] >= 0.99 ? layers.pop() : [255, 255, 255, 1];
+    while (layers.length) out = blend(layers.pop(), out);
+    return out;
+  };
+  const visible = (el) => {
+    const r = el.getBoundingClientRect();
+    if (r.width < 2 || r.height < 2) return false;
+    for (let e = el; e; e = e.parentElement) {
+      const s = getComputedStyle(e);
+      if (s.display === 'none' || s.visibility === 'hidden' || Number(s.opacity) < 0.1) return false;
+    }
+    return r.bottom > 0 && r.right > 0;
+  };
+  const where = (el) => {
+    const id = el.getAttribute('data-testid');
+    const cls = String(el.getAttribute('class') || '').split(/\s+/).filter(Boolean).slice(0, 2).join('.');
+    return `${el.tagName.toLowerCase()}${id ? `[data-testid=${id}]` : ''}${cls ? '.' + cls : ''}`;
+  };
+  const rgb = (c) => `rgb(${c.slice(0, 3).map(Math.round).join(',')})`;
+  const EXEMPT = '[disabled],[aria-disabled="true"],svg,script,style,noscript,template';
+  const low = [], light = [], seen = new Set();
+  const measure = (el, text) => {
+    const fg = parse(getComputedStyle(el).color);
+    if (!fg || fg[3] < 0.05) return;
+    const bg = behind(el);
+    if (!bg) return;
+    const r = ratio(blend(fg, bg), bg);
+    const key = where(el) + '|' + text.slice(0, 30);
+    if (r < min && !seen.has(key)) { seen.add(key); low.push({ text: text.slice(0, 40), fg: rgb(fg), bg: rgb(bg), ratio: Math.round(r * 100) / 100, where: where(el) }); }
+  };
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+  for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+    const text = (n.textContent || '').trim();
+    const el = n.parentElement;
+    if (!text || !el || !/[\p{L}\p{N}]/u.test(text) || el.closest(EXEMPT) || !visible(el)) continue;   // icon glyphs are not text a reader reads
+    measure(el, text);
+  }
+  for (const el of document.querySelectorAll('input:not([type=checkbox]):not([type=radio]):not([type=range]):not([type=hidden]):not([type=color]),textarea,select')) {
+    if (el.disabled || el.closest(EXEMPT) || !visible(el)) continue;
+    const text = String(el.value || '').trim();
+    if (text) measure(el, text);
+  }
+  if (dark) {
+    const area = window.innerWidth * window.innerHeight, flagged = [];
+    for (const el of document.querySelectorAll('body *')) {
+      if (el.closest('img,svg,video,canvas,picture,iframe') || flagged.some((f) => f.contains(el)) || !visible(el)) continue;
+      const c = parse(getComputedStyle(el).backgroundColor);
+      if (!c || c[3] < 0.5) continue;
+      const r = el.getBoundingClientRect();
+      const shown = Math.max(0, Math.min(r.right, window.innerWidth) - Math.max(r.left, 0)) * Math.max(0, Math.min(r.bottom, window.innerHeight) - Math.max(r.top, 0));
+      if (shown / area > 0.02 && lum(c) > 0.8) { flagged.push(el); light.push({ bg: rgb(c), share: Math.round(shown / area * 100), where: where(el), text: (el.innerText || '').trim().replace(/\s+/g, ' ').slice(0, 40) }); }
+    }
+  }
+  low.sort((a, b) => a.ratio - b.ratio);
+  return { low: low.slice(0, cap), light: light.slice(0, cap), low_n: low.length, light_n: light.length };
+};
+export const audit = (page, dark, min = 3.0, cap = 5) => page.evaluate(AUDIT, { dark, min, cap }).catch(() => null);