@techierathore/techieflow 1.0.3 → 1.0.4

package/.tfcore/utils/tf-selfcheck.sh

@@ -0,0 +1,323 @@
+#!/usr/bin/env bash
+# TechieFlow — the framework's own scripts, run against THIS project's real files.
+#
+#   bash .tfcore/utils/tf-selfcheck.sh [<repo>] [--report]
+#
+# WHY IT EXISTS. Nine framework defects reached TfLens in three weeks. Every one was
+# found mid-build, in the application's repository, and could only be fixed in the
+# framework's — so each cost a switch between repos, a feedback entry, a maintenance
+# sitting and a re-deploy. The defects were not exotic: a checklist with a row that
+# could never clear, a BRD carrying the anchors its own link checker demands, a metrics
+# file holding the framework's own verdicts. They were simply never run against a real
+# project's real files before the project ran them (MISS-TechieFlow-20260909-01).
+#
+# So this runs them here, first, and says which are broken ON THIS PROJECT. A FAIL is a
+# FRAMEWORK defect, never the project's: nothing here grades the application.
+#
+# Run it before a build pass, or any time. It writes nothing, boots nothing, and never
+# runs git. Python 3 standard library only.
+#
+# --report prints a ready-to-paste entry for the project's framework-feedback file, so
+# filing costs one paste instead of a page.
+#
+# EXIT: 0 every framework script works here · 1 at least one is broken · 3 cannot run.
+
+set -uo pipefail
+REPO="."; REPORT=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --report)  REPORT=1; shift ;;
+    -h|--help) sed -n '2,23p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *)         REPO="$1"; shift ;;
+  esac
+done
+[[ -d "$REPO" ]] || { echo "tf-selfcheck: not a directory: $REPO" >&2; exit 3; }
+command -v python3 >/dev/null 2>&1 || { echo "tf-selfcheck: python3 required" >&2; exit 3; }
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+TF_REPO="$REPO" TF_UTILS="$HERE" TF_REPORT="$REPORT" python3 - <<'PY'
+import json, os, re, subprocess, sys
+
+REPO = os.path.abspath(os.environ["TF_REPO"])
+UTILS = os.environ["TF_UTILS"]
+TELEM = os.path.join(os.path.dirname(UTILS), "telemetry")
+REPORT = os.environ["TF_REPORT"] == "1"
+findings = []          # (script, what is wrong, the one-line fix hint)
+lines = []
+
+
+def ok(script, msg):
+    lines.append("ok    %-20s %s" % (script, msg))
+
+
+def broken(script, msg, hint=""):
+    lines.append("FAIL  %-20s %s" % (script, msg))
+    findings.append((script, msg, hint))
+
+
+def skip(script, msg):
+    lines.append("--    %-20s %s" % (script, msg))
+
+
+def run(cmd, cwd=REPO, timeout=120):
+    try:
+        p = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True, timeout=timeout)
+        return p.returncode, (p.stdout or "") + (p.stderr or "")
+    except Exception as e:
+        return 99, str(e)
+
+
+def app_names():
+    """Every application this repo holds a checklist for. The checklist is the framework's
+    single source of truth, so its name is the app's name — no config value is trusted,
+    because core-config.yaml is rsynced between projects and is the thing most likely to
+    be stale (the same reason tf-gitignore-audit detects the stack from the tree)."""
+    d = os.path.join(REPO, "docs")
+    out = []
+    if os.path.isdir(d):
+        for f in sorted(os.listdir(d)):
+            m = re.match(r"^(.+?)(?:-P(\d+))?-Checklist\.md$", f)
+            if m and "Deployment" not in f:
+                out.append((m.group(1), int(m.group(2) or 1), os.path.join(d, f)))
+    return out
+
+
+# ---- 1. the deployed copy is intact ----------------------------------------------------
+# A framework script that will not even parse is the cheapest possible thing to catch and
+# the most expensive to meet mid-build.
+# Parsed in-process and the shells checked in ONE bash, not one subprocess per file:
+# 54 scripts meant 54 process launches and ten seconds, which is enough to make a check
+# that should run at the top of every command feel like a tax and get skipped.
+bad_parse, shells = [], []
+for folder in (UTILS, TELEM):
+    if not os.path.isdir(folder):
+        continue
+    for f in sorted(os.listdir(folder)):
+        full = os.path.join(folder, f)
+        if f.endswith(".py"):
+            try:
+                import ast
+                ast.parse(open(full, encoding="utf-8", errors="replace").read(), filename=full)
+            except SyntaxError:
+                bad_parse.append(f)
+        elif f.endswith(".sh"):
+            shells.append(full)
+if shells:
+    script = "for f in " + " ".join('"%s"' % x for x in shells) + \
+             '; do bash -n "$f" 2>/dev/null || echo "$f"; done'
+    rc, out = run(["bash", "-c", script])
+    bad_parse += [os.path.basename(x) for x in out.split() if x.strip()]
+if bad_parse:
+    broken("deployed copy", "%d script(s) do not parse: %s" % (len(bad_parse), ", ".join(bad_parse[:6])),
+           "re-run update-framework.sh; if it persists the framework shipped a broken script")
+else:
+    ok("deployed copy", "every framework script parses")
+
+# ---- 2. the working list accounts for every checklist row ------------------------------
+# TF-019: a row can sit at `Needs re-verify` forever, which pinned the mode and dropped
+# every not-started row out of the list AND out of the counts, so a build pass could report
+# a phase finished with rows at 0%. The arithmetic is the check: every row lands in exactly
+# one of open / terminal / Blocked.
+apps = app_names()
+if not apps:
+    skip("tf-build-list", "no checklist in docs/ yet")
+for app, phase, path in apps:
+    rc, out = run(["bash", os.path.join(UTILS, "tf-build-list.sh"), app] +
+                  ([] if phase <= 1 else ["--phase", str(phase)]))
+    label = "%s p%d" % (app, phase)
+    if rc not in (0, 2):
+        broken("tf-build-list", "%s: exited %d" % (label, rc), out.strip().splitlines()[0][:120] if out.strip() else "")
+        continue
+    m = re.search(r"Mode: (\w+) — (\d+) row\(s\) to build; (\d+) terminal, (\d+) Blocked, (\d+) total", out)
+    if not m:
+        if "has no REQ rows" in out:
+            skip("tf-build-list", "%s: checklist has no requirement rows yet" % label)
+        else:
+            broken("tf-build-list", "%s: no counts line to check" % label,
+                   "the output shape changed; the arithmetic can no longer be verified")
+        continue
+    mode, work, term, blocked, total = m.group(1), *(int(x) for x in m.groups()[1:])
+    if work + term + blocked != total:
+        broken("tf-build-list",
+               "%s: %d rows are in no category (%d open + %d terminal + %d blocked ≠ %d total)"
+               % (label, total - work - term - blocked, work, term, blocked, total),
+               "a build pass trusting this list would leave those rows at 0%")
+    else:
+        ok("tf-build-list", "%s: %d rows, all accounted for (%s)" % (label, total, mode))
+
+# ---- 3. the BRD this project actually wrote can be read --------------------------------
+# TF-017: the ledger regex required **BRD-N** immediately after the bullet, and a real BRD
+# carries an <a id> anchor there because §9 cross-links need one. It matched 0 of 179 items.
+sys.path.insert(0, UTILS)
+for app, phase, _cl in apps:
+    brd = os.path.join(REPO, "docs", "%s-BRD.md" % app if phase <= 1 else "%s-P%d-BRD.md" % (app, phase))
+    if not os.path.isfile(brd):
+        continue
+    text = open(brd, encoding="utf-8", errors="replace").read()
+    # A struck-through item (~~**BRD-3**~~ *(removed …)*) is deliberately not a live
+    # requirement, and the ledger is right to skip it. Counting it as unread would make
+    # this check cry wolf on every mature BRD -- and a check that cries wolf is the one
+    # that gets skimmed (TF-012 failed 8 of 10 screens identically and trained exactly that).
+    # UNIQUE ids, not occurrences: an id named again in a cross-reference is the same
+    # requirement, and counting mentions made every BRD look short by however many times
+    # it referred to itself.
+    written_ids = {m.group(1) for m in re.finditer(r"\*\*(BRD-\d+)\*\*", text)
+                   if not re.search(r"~~\s*$", text[max(0, m.start() - 3):m.start()])}
+    written = len(written_ids)
+    try:
+        import importlib.util
+        spec = importlib.util.spec_from_file_location("_sb", os.path.join(UTILS, "tf-split-brd.py"))
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        read = len({(i["id"] if isinstance(i, dict) else i[0]) for i in mod.ledger(text)})
+    except Exception as e:
+        broken("tf-split-brd", "%s: could not read the BRD at all (%s)" % (app, type(e).__name__),
+               "*amend-docs --add-missing cannot append checklist rows")
+        continue
+    if written and read < written:
+        broken("tf-split-brd", "%s: reads %d of %d BRD items" % (app, read, written),
+               "new requirements must be added to the checklist by hand until this is fixed")
+    elif written:
+        ok("tf-split-brd", "%s: reads all %d BRD items" % (app, written))
+
+# ---- 4. the streams this project's figures are built on --------------------------------
+# TF-015: a run whose `ended` precedes its `started` was stored with a negative or invented
+# duration, and the two readers of the stream then disagreed about the same record.
+runs_p = os.path.join(REPO, "docs", "metrics", "runs.jsonl")
+if not os.path.isfile(runs_p):
+    skip("runs.jsonl", "no telemetry in this project yet")
+else:
+    neg = impossible = total_r = badline = 0
+    for l in open(runs_p, encoding="utf-8", errors="replace"):
+        l = l.strip()
+        if not l:
+            continue
+        try:
+            r = json.loads(l)
+        except Exception:
+            badline += 1
+            continue
+        total_r += 1
+        d = r.get("duration_s")
+        if isinstance(d, (int, float)) and d < 0:
+            neg += 1
+        s, e = r.get("started"), r.get("ended")
+        if isinstance(s, str) and isinstance(e, str) and e < s:
+            impossible += 1
+    if badline:
+        broken("runs.jsonl", "%d line(s) are not valid JSON" % badline, "those records are invisible to every figure")
+    if impossible or neg:
+        # NOT a failure. The emitter refuses these now and the reader discards them and
+        # prints how many -- so nothing is wrong with the framework here, and nothing can
+        # be done about the records either: the stream is append-only and the true start
+        # times are gone. Reported once as history, because calling it broken on every
+        # command for the life of the project is how a check earns being skimmed.
+        skip("runs.jsonl", "%d old record(s) end before they start — discarded from every "
+                           "duration figure, and the report says so" % impossible)
+    elif total_r:
+        ok("runs.jsonl", "%d run record(s), none impossible" % total_r)
+
+# ---- 5. the framework's own verdicts are not counted as this project's -----------------
+# TF-020: an FR verdict grades a framework requirement, not a screen, and pooling it into
+# an application segment raises that segment's first-pass rate with nothing on the output
+# to show it happened. SCHEMA §3 states the rule; the rollup has to apply it.
+gates_p = os.path.join(REPO, "docs", "metrics", "gates.jsonl")
+if not os.path.isfile(gates_p):
+    skip("tf-metrics", "no gate records in this project yet")
+else:
+    has_fr = False
+    for l in open(gates_p, encoding="utf-8", errors="replace"):
+        if '"req_class"' in l and '"FR"' in l:
+            has_fr = True
+            break
+    rc, out = run(["bash", os.path.join(TELEM, "tf-metrics.sh"), "--rollup", REPO, "--json"])
+    try:
+        data = json.loads(out)
+    except Exception:
+        broken("tf-metrics", "--rollup did not return readable JSON (exit %d)" % rc,
+               "no figure this project publishes can be checked against the reference")
+        data = None
+    if data is not None:
+        segs = data.get("live") or {}
+        if has_fr and "framework-requirement" not in segs:
+            broken("tf-metrics", "framework verdicts are pooled into %s" % ", ".join(sorted(segs) or ["nothing"]),
+                   "this project's first-pass rate is overstated")
+        else:
+            ok("tf-metrics", "rollup reads; %d segment(s), framework verdicts separate" % len(segs))
+
+# ---- 6. amendments to the miss log still fold -------------------------------------------
+# TF-006 and TF-018: a field added after a record was written can only be completed by an
+# amendment, and an amendment the reader will not fold is a fact silently lost.
+miss_p = os.path.join(REPO, "docs", "metrics", "misses.jsonl")
+if not os.path.isfile(miss_p):
+    skip("misses.jsonl", "no miss records in this project yet")
+else:
+    ids, amends, orphan = set(), 0, 0
+    for l in open(miss_p, encoding="utf-8", errors="replace"):
+        l = l.strip()
+        if not l:
+            continue
+        try:
+            r = json.loads(l)
+        except Exception:
+            continue
+        if r.get("kind") == "miss":
+            ids.add(r.get("miss_id"))
+        elif r.get("kind") == "miss-amend":
+            amends += 1
+            if r.get("miss_id") not in ids:
+                orphan += 1
+    if orphan:
+        broken("misses.jsonl", "%d amendment(s) name a miss that is not on this stream" % orphan,
+               "the information in them is not reaching any figure")
+    else:
+        ok("misses.jsonl", "%d miss(es), %d amendment(s), none orphaned" % (len(ids), amends))
+
+# ---- 7. the checks that read this project's documents run at all -----------------------
+for name, cmd in (("tf-doc-check", ["bash", os.path.join(UTILS, "tf-doc-check.sh")] +
+                   (["--app", apps[0][0]] if apps else []) + ["--warn"]),
+                  ("tf-gitignore-audit", ["bash", os.path.join(UTILS, "tf-gitignore-audit.sh"), REPO, "--dry-run"])):
+    if name == "tf-doc-check" and not apps:
+        skip(name, "no application documents yet")
+        continue
+    rc, out = run(cmd)
+    if rc in (99,) or "Traceback" in out:
+        broken(name, "crashed on this project's files",
+               (out.strip().splitlines() or [""])[-1][:120])
+    else:
+        first = next((l for l in out.splitlines() if l.strip()), "")
+        ok(name, "runs (exit %d)" % rc)
+
+# ---- output -----------------------------------------------------------------------------
+proj = os.path.basename(REPO.rstrip(os.sep))
+print("# tf-selfcheck — %s — the framework's own scripts against this project's real files" % proj)
+for l in lines:
+    print(l)
+print()
+if not findings:
+    print("Every framework script works on this project. Nothing to file.")
+    raise SystemExit(0)
+
+print("%d framework defect(s) found. These are the FRAMEWORK's, not this project's —" % len(findings))
+print("nothing here graded the application. Do not work around them silently: file them,")
+print("and carry on (a framework defect blocks a row only when it stops the work).")
+if REPORT:
+    print()
+    print("--- paste into docs/%s-TechieFlow-Feedback.md ---" % proj)
+    for i, (script, msg, hint) in enumerate(findings, 1):
+        print()
+        print("## TF-xxx — %s: %s" % (script, msg))
+        print()
+        print("- **Severity:** major")
+        print("- **Blocks:** no")
+        print("- **Repro:** `bash .tfcore/utils/tf-selfcheck.sh` in this repository")
+        print("- **Expected:** the script works on this project's files")
+        print("- **Actual:** %s" % msg)
+        print("- **Encountered in:** tf-selfcheck, %s" % proj)
+        if hint:
+            print("- **Consequence:** %s" % hint)
+        print("- **Not fixable here** — `.tfcore/` is framework-owned and is replaced on the next update.")
+else:
+    print("Run again with --report for entries you can paste into the feedback file.")
+raise SystemExit(1)
+PY

package/.tfcore/utils/tf-split-brd.py

@@ -85,7 +85,12 @@ def ledger(text):
     lines = text.splitlines()
     i = 0
     while i < len(lines):
-        m = re.match(r"^\s*[-*]\s*\*\*(BRD-\d+)\*\*\s*[—:-]+\s*(.*)$", lines[i])
+        # The anchor is not decoration: a BRD's §9 screen inventory links to each item as
+        # [BRD-21](#brd-21), markdown generates no id for bold text inside a list item, and
+        # tf-doc-check refuses a broken link -- so a real BRD carries `<a id="brd-N"></a>`
+        # here and this regex matched NONE of TfLens's 179 items. tests/regression tf_017.
+        m = re.match(r"^\s*[-*]\s*(?:<a id=[\"\']?[^\"\'>]*[\"\']?\s*>\s*</a>\s*)?"
+                     r"\*\*(BRD-\d+)\*\*\s*[—:-]+\s*(.*)$", lines[i])
         if m and m.group(1) not in nfr_ids:
             rid, rest = m.group(1), m.group(2)
             title = re.split(r"\s*(?:\.\s+\*|\s\*Screen|\s·\s\*|\s\*Mockup)", rest, 1)[0].strip().rstrip(".")

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

@@ -77,14 +77,44 @@ def ladder_rank(status):
     return LADDER.index(status) if status in LADDER else 0
 
 
+def ledger(root):
+    """docs/.last-verify.json as a dict, or {} when there is none.
+
+    The verifier writes it with `json.dump(..., indent=1)`, so it is ONE pretty-printed
+    object spanning many lines. This reader used to take `splitlines()[-1]` — written for
+    an append-per-line ledger that no version of the verifier has ever produced — so it
+    parsed the closing brace, threw, and every project reported `last_verified_build:
+    not-run` however many verify runs it had behind it (TfLens: 69 of 73 rows Verified and
+    a full ledger, reported as never verified). Whole file first, last line second for a
+    legacy JSONL ledger. tests/regression/run.sh tf_ledger."""
+    path = os.path.join(root, "docs", ".last-verify.json")
+    if not os.path.isfile(path):
+        return {}
+    text = read(path).strip()
+    for candidate in (text, text.splitlines()[-1] if text else ""):
+        try:
+            data = json.loads(candidate)
+            if isinstance(data, dict):
+                return data
+        except Exception:
+            continue
+    return {}
+
+
+def ledger_verdicts(root):
+    """{REQ id: verdict} from the last verify run, or {} when none has run.
+
+    The verifier already writes every row's verdict into the ledger. Reading it here is
+    what lets the status line tell "built, waiting for a verify" apart from "verified as
+    far as it can be, and the rest needs a decision only the owner can make"."""
+    rows = ledger(root).get("rows")
+    return rows if isinstance(rows, dict) else {}
+
+
 def last_verify(root, app):
     """(date, build_result) from docs/.last-verify.json and gates.jsonl; ('', 'not-run') if none."""
-    ledger = os.path.join(root, "docs", ".last-verify.json")
-    if not os.path.isfile(ledger):
-        return "", "not-run"
-    try:
-        data = json.loads(read(ledger).strip().splitlines()[-1])
-    except Exception:
+    data = ledger(root)
+    if not data:
         return "", "not-run"
     date = str(data.get("date", ""))[:10]
     result = "PASS"
@@ -161,8 +191,10 @@ def phase_row(root, app, phase):
     return name, total
 
 
-def next_command(app, rows, log_rows, phase=1):
+def next_command(app, rows, log_rows, phase=1, verdicts=None):
     """Returns (phase, qualifier, cc_line, oc_line, reason)."""
+    verdicts = verdicts or {}
+
     def ids(lst):
         return ", ".join(r["id"] for r in lst[:6]) + (" …" if len(lst) > 6 else "")
 
@@ -187,11 +219,28 @@ def next_command(app, rows, log_rows, phase=1):
                 f"{CC}flow-master *build-phase {app}", f"{OC}flow-master *build-phase {app}",
                 f"{len(unbuilt)} rows are not built yet: {ids(unbuilt)}")
     if built:
-        ui = [r for r in built if r["id"].startswith("REQ-UI")]
-        scope = "ui" if len(ui) == len(built) else ("functional" if not ui else "all")
-        return ("Verify", f"{len(built)} to verify, {q}",
+        # 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
+        # running the verifier again produces the same NOT-TESTED and the project sits in a
+        # 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")
+        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"{len(built)} rows are built and not verified: {ids(built)}")
+                reason)
     if owner:
         if handoff_ran(log_rows):
             line = f"(owner-run) docs/{app}-UsageGuide.md — {ids(owner)}"
@@ -234,7 +283,7 @@ 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)
+    phase, qual, cc, oc, reason = next_command(app, rows, log_rows, phase_n, ledger_verdicts(root))
     pname, ptotal = phase_row(root, app, phase_n)
     if ptotal or phase_n > 1:
         tag = f"Phase {phase_n} of {ptotal or '?'}" + (f" ({pname})" if pname else "")

package/.tfcore/utils/tf-verify-screens.mjs

@@ -3,16 +3,21 @@
 //
 // Two of the seven verify checks, over one browser session:
 //   render  every control the mockup anchors (data-testid) is present and shows something; no
-//           table with a header and no rows; no blank page; no Blazor error; no console error.
+//           table with a header and no rows; no blank page; no error banner; no console error.
 //   visual  no two visible controls overlap; no anchored control has zero size or sits off-screen;
-//           no horizontal overflow; the page has a stylesheet.
+//           no horizontal overflow; the page has a stylesheet. Overlap and off-screen are measured
+//           on the rectangle an element PAINTS in — its box clipped by every scrolling ancestor —
+//           so a wide table inside a horizontal scroller is not read as covering its neighbour.
+// Measurement waits for the screen's first render (--render-wait, default 5000 ms) before reading
+// the page: it waits for content to appear, knowing nothing about how the page is built.
 // At every width it saves a full-page screenshot. Verdicts: render OK | EMPTY | ERROR | UNREACHABLE,
 // visual OK | FAIL, each with its findings. Findings use the telemetry classes (blank-data,
 // zero-rows, exception, overlap, clipped, offscreen, other). It writes a JSON file the verdict
 // script reads and prints one line per screen. It never decides a row's status.
 //
-// Modes: --base URL (a served app, a new browser) or --cdp URL (attach to a running Blazor Hybrid
-// app's WebView2 over its DevTools port; screens are reached by pushState, the way the router does).
+// Modes: --base URL (a served app, a new browser) or --cdp URL (attach to an already-running
+// embedded-browser desktop head over its DevTools port; screens are reached by pushState, the way
+// the router does).
 
 import { chromium } from 'playwright';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -33,7 +38,21 @@ const LOGIN_PATH = arg('--login-path');
 const USER = arg('--user'); const PASS = arg('--password');
 const COOKIE = arg('--cookie'); const STORAGE = arg('--storage-state');
 const SETTLE = parseInt(arg('--wait', '1500'), 10);
+// how long to keep waiting for the FIRST render after the page has settled. Plenty of stacks
+// paint after the network goes quiet — a server-held connection that renders once it is up, a
+// client router resolving its first route, a lazily loaded bundle — so measuring at
+// domcontentloaded, at networkidle or even after --wait can read an empty document and report
+// every anchored control as missing while the tool's own screenshot shows them (TF-021, TfLens
+// 2026-09-09). Nothing here knows which stack it is looking at: it waits for CONTENT.
+const RENDER_WAIT = parseInt(arg('--render-wait', '5000'), 10);
 const ATTR = arg('--testid-attr', 'data-testid');
+// The banner a stack shows when its client side has fallen over. There is no neutral way to
+// detect one -- every stack names its own -- so this is a LIST a project extends rather than a
+// selector the framework assumes: --error-selector '.my-crash-banner', repeatable. The two
+// defaults are one widely used framework's id and a plain attribute any project can put on its
+// own banner. A project on neither still gets every other render check; it simply cannot be
+// told about a banner nobody named.
+const ERROR_SELECTORS = [...args('--error-selector'), '#blazor-error-ui', '[data-error-ui]'];
 
 if (!BASE && !CDP) { console.error('tf-verify-screens: --base URL or --cdp URL is required'); process.exit(3); }
 
@@ -138,9 +157,29 @@ async function navigate(page, route) {
   } catch (e) { return { status: 0, error: e.message.split('\n')[0] }; }
 }
 
+// Wait for the screen's first render before measuring anything. Returns the milliseconds waited.
+// It never decides anything: when nothing appears within RENDER_WAIT the page is graded exactly as
+// it stands, so a control that is genuinely missing is still reported (TF-021).
+async function waitForRender(page, anchors, attr) {
+  if (RENDER_WAIT <= 0) return 0;
+  const t0 = Date.now();
+  try {
+    // The condition names nothing about how the page is built: either a control the
+    // mockup anchors has appeared, or the document has text or a form control in it.
+    // An error banner satisfies the second, so a page that failed to start is not
+    // waited on to the timeout either.
+    await page.waitForFunction(({ anchors, attr }) => {
+      if (anchors && anchors.length) return anchors.some((id) => document.querySelector(`[${attr}="${CSS.escape(id)}"]`));
+      return (document.body && (document.body.innerText || '').trim().length > 0)
+        || document.querySelectorAll('input, select, textarea, img, svg, canvas, video').length > 0;
+    }, { anchors, attr }, { timeout: RENDER_WAIT, polling: 100 });
+  } catch (e) { /* nothing appeared in time: grade what is there */ }
+  return Date.now() - t0;
+}
+
 // what the page says about itself: anchors, tables, text, boxes
-async function inspect(page, anchors, attr) {
-  return page.evaluate(({ anchors, attr }) => {
+async function inspect(page, anchors, attr, errorSelectors) {
+  return page.evaluate(({ anchors, attr, errorSelectors }) => {
     const vis = (el) => {
       const cs = getComputedStyle(el);
       if (cs.display === 'none' || cs.visibility === 'hidden' || cs.opacity === '0') return false;
@@ -149,13 +188,39 @@ async function inspect(page, anchors, attr) {
       if (r.width <= 1 && r.height <= 1 && cs.position === 'absolute') return false; // sr-only
       return true;
     };
+    // The rectangle an element actually PAINTS in: its own box intersected with the clip
+    // rectangle of every ancestor that clips (any overflow other than `visible`). A table row
+    // inside a horizontal scroller measures 1167px wide in a container 492px wide, so the
+    // unclipped box reaches x=1480 while the pixels stop at x=805 — and the card beside it, at
+    // x=846, was reported as being overlapped by something nothing draws (TF-021, TfLens
+    // 2026-09-09). Overlap and off-screen are judged on this rectangle; zero-size still uses the
+    // element's own box, since a control scrolled out of view is not a collapsed one.
+    const clipRect = (el) => {
+      const r = el.getBoundingClientRect();
+      let x1 = r.left, y1 = r.top, x2 = r.right, y2 = r.bottom, clipped = false;
+      for (let p = el.parentElement; p; p = p.parentElement) {
+        const cs = getComputedStyle(p);
+        const cx = cs.overflowX !== 'visible', cy = cs.overflowY !== 'visible';
+        if (!cx && !cy) continue;
+        const pr = p.getBoundingClientRect();
+        const nx1 = cx ? Math.max(x1, pr.left) : x1, nx2 = cx ? Math.min(x2, pr.right) : x2;
+        const ny1 = cy ? Math.max(y1, pr.top) : y1, ny2 = cy ? Math.min(y2, pr.bottom) : y2;
+        if (nx1 !== x1 || nx2 !== x2 || ny1 !== y1 || ny2 !== y2) clipped = true;
+        x1 = nx1; x2 = nx2; y1 = ny1; y2 = ny2;
+      }
+      return { x: x1, y: y1, w: Math.max(0, x2 - x1), h: Math.max(0, y2 - y1), clipped };
+    };
     const sheetOk = (l) => { try { return !!l.sheet && l.sheet.cssRules.length > 0; } catch (e) { return !!l.sheet; } };
     const styled = [...document.querySelectorAll('link[rel~="stylesheet"]')].some(sheetOk)
       || [...document.querySelectorAll('style')].some(sheetOk);
     const failedSheets = [...document.querySelectorAll('link[rel~="stylesheet"]')].filter((l) => !l.sheet).map((l) => l.getAttribute('href'));
     const out = { anchors: [], tables: [], text_len: (document.body.innerText || '').trim().length, boxes: [],
       controls: document.querySelectorAll('input, select, textarea, img, svg, canvas, video').length,
-      blazor_error: !!document.querySelector('#blazor-error-ui') && vis(document.querySelector('#blazor-error-ui')),
+      error_banner: (errorSelectors || []).find((sel) => {
+        let el = null;
+        try { el = document.querySelector(sel); } catch (e) { return false; }   // a bad selector is not a finding
+        return !!el && vis(el);
+      }) || '',
       overflow_x: document.documentElement.scrollWidth > document.documentElement.clientWidth + 2,
       styled, failed_sheets: failedSheets, vw: window.innerWidth, vh: window.innerHeight };
     for (const id of anchors || []) {
@@ -165,7 +230,9 @@ async function inspect(page, anchors, attr) {
       const r = el.getBoundingClientRect();
       const text = (el.innerText || el.value || el.getAttribute('aria-label') || '').trim();
       const filled = text.length > 0 || ['input', 'select', 'textarea', 'img', 'svg', 'canvas', 'video', 'iframe'].includes(tag) || el.querySelector('img,svg,canvas,input,select,textarea,button,a') !== null;
-      out.anchors.push({ id, present: true, visible: vis(el), filled, tag, w: Math.round(r.width), h: Math.round(r.height), x: Math.round(r.left), y: Math.round(r.top) });
+      const c = clipRect(el);
+      out.anchors.push({ id, present: true, visible: vis(el), filled, tag, w: Math.round(r.width), h: Math.round(r.height), x: Math.round(r.left), y: Math.round(r.top),
+        cx: Math.round(c.x), cy: Math.round(c.y), cw: Math.round(c.w), ch: Math.round(c.h), clipped: c.clipped });
     }
     for (const t of document.querySelectorAll('table')) {
       if (!vis(t)) continue;
@@ -178,8 +245,9 @@ async function inspect(page, anchors, attr) {
     const els = [...document.querySelectorAll(sel)].filter(vis);
     els.forEach((el, i) => {
       const r = el.getBoundingClientRect();
+      const c = clipRect(el);            // what is painted, not what is laid out
       out.boxes.push({ i, id: el.getAttribute(attr) || '', tag: el.tagName.toLowerCase(), text: (el.innerText || el.value || '').trim().slice(0, 40),
-        x: r.left, y: r.top, w: r.width, h: r.height, anchored: el.hasAttribute(attr) });
+        x: c.x, y: c.y, w: c.w, h: c.h, raw_w: r.width, raw_h: r.height, clipped: c.clipped, anchored: el.hasAttribute(attr) });
     });
     // ancestry so a button inside its card is never an "overlap"
     out.rel = [];
@@ -187,12 +255,12 @@ async function inspect(page, anchors, attr) {
       if (els[a].contains(els[b]) || els[b].contains(els[a])) out.rel.push([a, b]);
     }
     return out;
-  }, { anchors, attr });
+  }, { anchors, attr, errorSelectors });
 }
 
 function grade(info, consoleErrors, width) {
   const findings = [];
-  if (info.blazor_error) findings.push({ check: 'render', class: 'exception', detail: 'the Blazor error bar is showing' });
+  if (info.error_banner) findings.push({ check: 'render', class: 'exception', detail: `the application's error banner is showing (${info.error_banner})` });
   // a failed fetch ("Failed to load resource … 404") is the assets check's finding, not a page error
   const pageErrors = consoleErrors.filter((e) => !/^Failed to load resource/i.test(e));
   for (const e of pageErrors.slice(0, 3)) findings.push({ check: 'render', class: 'exception', detail: `console error: ${e.slice(0, 120)}` });
@@ -209,7 +277,10 @@ function grade(info, consoleErrors, width) {
   if (info.overflow_x) findings.push({ check: 'visual', class: 'offscreen', detail: `the page scrolls sideways at ${width}px` });
   for (const a of info.anchors) {
     if (a.present && a.visible && (a.w === 0 || a.h === 0)) findings.push({ check: 'visual', class: 'clipped', detail: `anchored control "${a.id}" has zero ${a.w === 0 ? 'width' : 'height'}` });
-    if (a.present && a.visible && a.w > 0 && (a.x + a.w > info.vw + 2 || a.x < -2)) findings.push({ check: 'visual', class: 'offscreen', detail: `anchored control "${a.id}" sits outside the viewport at ${width}px` });
+    // judged on the painted rectangle: a control inside a scroller is reachable by scrolling
+    // that container, which is a layout decision, not a control that has fallen off the page
+    const ax = a.cx === undefined ? a.x : a.cx, aw = a.cw === undefined ? a.w : a.cw;
+    if (a.present && a.visible && a.w > 0 && aw > 0 && (ax + aw > info.vw + 2 || ax < -2)) findings.push({ check: 'visual', class: 'offscreen', detail: `anchored control "${a.id}" sits outside the viewport at ${width}px` });
   }
   const rel = new Set(info.rel.map(([a, b]) => `${a}-${b}`));
   const boxes = info.boxes.filter((b) => b.w > 0 && b.h > 0);
@@ -257,7 +328,8 @@ for (const width of WIDTHS) {
       entry.findings = [{ check: 'render', class: 'other', detail: nav.status === 0 ? `could not open ${s.route}: ${nav.error || 'no response'}` : redirectedToLogin ? `${s.route} redirected to the sign-in page (not signed in)` : `${s.route} answered HTTP ${nav.status}` }];
       if (nav.status === 0 && results.length === 1 && width === WIDTHS[0]) firstUnreachable = true;
     } else {
-      const info = await inspect(page, r.anchors || [], ATTR);
+      entry.render_wait_ms = await waitForRender(page, r.anchors || [], ATTR);
+      const info = await inspect(page, r.anchors || [], ATTR, ERROR_SELECTORS);
       const g = grade(info, consoleErrors, width);
       Object.assign(entry, g);
       entry.console_errors = consoleErrors.slice(0, 5);