@techierathore/techieflow 1.0.3 → 1.1.0

package/.tfcore/utils/tf-verify-list.py

@@ -71,13 +71,21 @@ def entries_of(text):
     out, current = {}, ""
     lines = text.splitlines()
     for i, line in enumerate(lines):
-        m = re.match(r"^##\s+(.+)$", line)
+        # a heading one level down (`### Page: …` under `## UI / Pages`) names the section too, and any
+        # other one (`### Cross-page: …`) ends the page above it
+        m = re.match(r"^#{2,3}\s+(.+)$", line)
         if m:
             current = re.sub(r"^(?:page|screen)\s*:\s*", "", m.group(1).strip(), flags=re.I)
             continue
         a = re.search(r"<a id=['\"]d-(req-[a-z]+-\d+)['\"]", line, re.I)
         if a:
             rid = a.group(1).upper()
+            # an anchor written above its own page heading belongs to that page, not the one before
+            # (AppManager's older entries: `<a id>` then `### Page:` then the row)
+            nxt = next((l for l in lines[i + 1:i + 3] if l.strip()), "")
+            h = re.match(r"^#{2,3}\s+(?:page|screen)\s*:\s*(.+)$", nxt, re.I)
+            if h:
+                current = h.group(1).strip()
             e = {"section": current, "acceptance": "", "mockup": "", "brd": "", "perf_budget": ""}
             for j in range(i, min(i + 14, len(lines))):
                 l = lines[j]
@@ -117,6 +125,28 @@ def screens_of_uidesign(path):
     return out
 
 
+def screens_of_checklist(text, ent):
+    """[{name, route, mockup}] from the checklist's own '## Page: Name (`/route`, …)' headings, at ## or
+    ###, for a project with no UIDesign: the first route that can be opened as typed (no `{id}`),
+    the mockup from the first entry under the heading. A heading with no such route names no screen.
+    Without this every UI row of such a project was graded by its test only (AppManager TF-016)."""
+    out, seen = [], set()
+    for line in text.splitlines():
+        m = re.match(r"^#{2,3}\s+(?:page|screen)\s*:\s*(.+?)\s*\((.*)\)\s*$", line, re.I)
+        if not m or norm_name(m.group(1)) in seen:
+            continue
+        inner = m.group(2)
+        cands = re.findall(r"`([^`]+)`", inner) or re.split(r"\s*,\s*", inner)
+        route = next((c.strip() for c in cands if c.strip().startswith("/") and "{" not in c and " " not in c.strip()), "")
+        if not route:
+            continue
+        section = re.sub(r"^#+\s+(?:page|screen)\s*:\s*", "", line.strip(), flags=re.I)
+        mock = next((e["mockup"] for e in ent.values() if e["section"] == section and e["mockup"]), "")
+        seen.add(norm_name(m.group(1)))
+        out.append({"name": m.group(1).strip(), "route": route, "mockup": mock, "section": section})
+    return out
+
+
 def dialogs_of_brd(path):
     """name -> parent route, from the BRD screens table rows whose Route cell reads 'on /route'."""
     out = {}
@@ -131,17 +161,47 @@ def dialogs_of_brd(path):
     return out
 
 
+def usage_guide(app):
+    """docs/{App}-UsageGuide.md, or docs/{App}-Usage-Guide.md: the two spellings tf-doc-check.py
+    accepts. Only the first was looked for, so AppManager's guide read as having no test users
+    (AppManager TF-009)."""
+    for name in (f"{app}-UsageGuide.md", f"{app}-Usage-Guide.md"):
+        p = os.path.join("docs", name)
+        if os.path.isfile(p):
+            return p
+    return os.path.join("docs", f"{app}-UsageGuide.md")
+
+
 def test_users(path):
+    """The rows of the guide's Test users table. The heading may sit at ## or ### (a guide that
+    numbers its chapters nests it one level down), and the table may be the template's
+    `| # | User | Password source | Role |` or any table whose header names a user or email column
+    and a role column, read by those names (AppManager TF-009)."""
     users = []
     if not os.path.isfile(path):
         return users
-    m = re.search(r"(?ms)^##\s+(?:\d+[.)]\s*)?Test users[^\n]*\n(.*?)(?=^## |\Z)", read(path))
+    m = re.search(r"(?ms)^#{2,3}\s+(?:\d+[.)]\s*)?Test users[^\n]*\n(.*?)(?=^#{1,3} |\Z)", read(path))
     if not m:
         return users
+    cols = None
     for line in m.group(1).splitlines():
+        if not line.strip().startswith("|"):
+            continue
         c = [x.strip().strip("`* ") for x in line.strip().strip("|").split("|")]
-        if len(c) >= 4 and c[0].isdigit():
-            users.append({"user": c[1], "password_source": c[2], "role": c[3]})
+        if cols is None:
+            low = [x.lower() for x in c]
+            def col(*names):
+                return next((i for i, h in enumerate(low) if any(n in h for n in names)), None)
+            cols = {"user": col("user", "email", "login", "account"), "pw": col("password", "secret"), "role": col("role")}
+            if cols["user"] is None or cols["role"] is None:
+                cols = {"user": 1, "pw": 2, "role": 3}      # the template's numbered shape
+            continue
+        if set("".join(c)) <= set("-: "):
+            continue                                        # the header rule
+        if len(c) > max(cols["user"], cols["role"]) and c[cols["user"]] and not c[cols["user"]].isdigit():
+            users.append({"user": c[cols["user"]],
+                          "password_source": c[cols["pw"]] if cols["pw"] is not None and len(c) > cols["pw"] else "",
+                          "role": c[cols["role"]]})
     return users
 
 
@@ -186,12 +246,15 @@ def main(argv):
     if not rows:
         die(f"{cl} has no REQ rows")
     ent = entries_of(text)
-    screens = screens_of_uidesign(os.path.join("docs", f"{pfx}UIDesign.md"))
+    screens, source = screens_of_uidesign(os.path.join("docs", f"{pfx}UIDesign.md")), "UIDesign"
+    if not screens:
+        screens, source = screens_of_checklist(text, ent), "checklist's Page headings"
     dialogs = dialogs_of_brd(os.path.join("docs", f"{pfx}BRD.md"))
-    users = test_users(os.path.join("docs", f"{app}-UsageGuide.md"))
+    users = test_users(usage_guide(app))
     by_name = {norm_name(s["name"]): s for s in screens}
     by_mock = {s["mockup"]: s for s in screens if s["mockup"]}
     by_route = {s["route"].lower(): s for s in screens}
+    by_section = {s["section"]: s for s in screens if s.get("section")}
 
     work, skipped, unresolved = [], 0, []
     for r in rows:
@@ -204,6 +267,10 @@ def main(argv):
         row = dict(r, acceptance=e["acceptance"], mockup=e["mockup"], brd=e["brd"], perf_budget=e["perf_budget"],
                    section=e["section"], screen="", route="", dialog="")
         cand = [screen_from_acceptance(e["acceptance"]), e["section"], r["title"]]
+        if e["section"] in by_section:     # a screen read from the checklist: the heading the row sits under
+            s = by_section[e["section"]]
+            row["screen"], row["route"] = s["name"], s["route"]
+            cand = []
         for c in cand:
             n = norm_name(c)
             if not n:
@@ -236,7 +303,7 @@ def main(argv):
     if not work:
         print("NOTHING: no row in scope. Run the status gate and stop.")
     print()
-    print(f"## Screens to drive ({len(screen_list)} of {len(screens)} in the UIDesign)")
+    print(f"## Screens to drive ({len(screen_list)} of {len(screens)} in the {source})")
     for s in screen_list:
         print(f"- {s['name']} ({s['route']}) — mockup {s['mockup'] or 'none'} — rows {', '.join(s['rows'])}")
     print()
@@ -259,7 +326,7 @@ def main(argv):
     os.makedirs(os.path.dirname(out_path) or ".", exist_ok=True)
     with open(out_path, "w", encoding="utf-8") as f:
         json.dump({"app": app, "scope": scope, "phase": phase, "kind": cfg("appKind", "app"), "checklist": cl,
-                   "rows": work, "screens": screen_list, "unresolved": unresolved, "test_users": users,
+                   "rows": work, "screens": screen_list, "screens_source": source, "unresolved": unresolved, "test_users": users,
                    "skipped_na": skipped, "total": len(rows)}, f, indent=1)
     print()
     print(f"JSON: {out_path}")

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

@@ -2,17 +2,23 @@
 // Run through tf-verify-screens.sh, not directly. Sitting 4c, 2026-09-06.
 //
 // 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.
+//   render  every control the mockup anchors (data-testid) and shows at that width is present and
+//           shows something (one the mockup hides at that width only is not owed there); no
+//           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,32 +39,132 @@ 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); }
 
 // ---------------------------------------------------------------- screens
 let screens = [];
+// Sample values for route parameters (Lekhak TF-005): `/admin/llm-signin/{ProviderId:long}` opened as
+// written answers 404. --route-value ProviderId=21 (repeatable), or "route_values" in the list, at its
+// top or on one screen. A screen whose route still needs a value is not driven, and says which.
+const ROUTE_VALUES = {};
+for (const kv of args('--route-value')) { const m = kv.match(/^([^=]+)=(.*)$/); if (m) ROUTE_VALUES[m[1].trim().toLowerCase()] = m[2]; }
+let listValues = {};
 if (LIST) {
   const l = JSON.parse(readFileSync(LIST, 'utf8'));
-  screens = (l.screens || []).map((s) => ({ name: s.name, route: s.route, mockup: s.mockup || '', rows: s.rows || [] }));
+  listValues = l.route_values || {};
+  screens = (l.screens || []).map((s) => ({ name: s.name, route: s.route, mockup: s.mockup || '', rows: s.rows || [], route_values: s.route_values || {} }));
 }
 for (const s of args('--screen')) {
   const m = s.match(/^([^=]+)=(.+)$/);
   if (m) screens.push({ name: m[1], route: m[2], mockup: `${MOCKUPS}/${m[1].toLowerCase().replace(/[^a-z0-9]+/g, '-')}.html`, rows: [] });
 }
 if (!screens.length) { console.error('tf-verify-screens: no screens (--list <json> or --screen name=/route)'); process.exit(3); }
+const fillRoute = (s) => {
+  const vals = {};
+  for (const src of [listValues, s.route_values || {}]) for (const [k, v] of Object.entries(src)) vals[k.toLowerCase()] = String(v);
+  Object.assign(vals, ROUTE_VALUES);
+  const need = [];
+  const route = s.route.replace(/\/?\{\*{0,2}([A-Za-z_][\w]*)(?::[^}=?]*)?(?:=([^}?]*))?(\?)?\}/g, (whole, name, dflt, opt) => {
+    const lead = whole.startsWith('/') ? '/' : '';
+    const v = vals[name.toLowerCase()] ?? dflt;
+    if (v !== undefined && v !== '') return lead + encodeURIComponent(v);
+    if (opt) return '';
+    need.push(name); return whole;
+  });
+  return { route, need };
+};
+const skipped = [];
+screens = screens.filter((s) => {
+  const f = fillRoute(s);
+  if (f.need.length) { skipped.push({ name: s.name, route: s.route, rows: s.rows, needs: f.need }); return false; }
+  if (f.route !== s.route) s.route_pattern = s.route;
+  s.route = f.route;
+  return true;
+});
+for (const k of skipped) console.log(`SKIP ${k.name} (${k.route}) — not driven: the route needs a value; pass ${k.needs.map((n) => `--route-value ${n}=<a real ${n}>`).join(' ')}`);
 
 const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
 const anchorsOf = (mockup) => {
   if (!mockup || !existsSync(mockup)) return null;
-  const html = readFileSync(mockup, 'utf8');
-  const re = new RegExp(`${ATTR}\\s*=\\s*["']([^"']+)["']`, 'g');
+  // Only an attribute ON AN ELEMENT is a control the page must carry. A stylesheet rule such as
+  // [data-testid="source-mode"] .tab{…}, a script string or a comment naming one is not: TfLens's
+  // shared mockup stylesheet made every screen owe a dialog it never draws (TF-026).
+  const html = readFileSync(mockup, 'utf8')
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<(style|script)\b[\s\S]*?<\/\1\s*>/gi, '');
+  const re = new RegExp(`<[^>]*?\\b${ATTR}\\s*=\\s*["']([^"']+)["']`, 'g');
   const out = new Set(); let m;
   while ((m = re.exec(html))) out.add(m[1]);
   return [...out];
 };
 
+// The anchors a mockup HIDES at one width and shows at another: a sidebar that becomes a slide-out
+// menu on a phone is not owed at 390px, and asking for it failed every such screen there (TF-032,
+// TfLens 2026-09-11). Worked out by drawing the mockup itself at each width. An anchor the mockup
+// hides at every width -- a closed dialog -- is still owed, as before. None is excused when the
+// mockup cannot be drawn.
+async function hiddenByWidth(b, mockup, anchors) {
+  const out = {};
+  if (!b || !mockup || !existsSync(mockup) || !anchors || !anchors.length) return out;
+  const shown = {};
+  for (const width of WIDTHS) {
+    let ctx;
+    try {
+      ctx = await b.newContext({ viewport: { width, height: width < 600 ? 844 : 800 } });
+      const p = await ctx.newPage();
+      await p.goto('file://' + resolve(mockup), { waitUntil: 'load', timeout: 15000 });
+      shown[width] = await p.evaluate(({ anchors, attr }) => anchors.filter((id) => {
+        const el = document.querySelector(`[${attr}="${CSS.escape(id)}"]`);
+        if (!el) return false;
+        const r = el.getBoundingClientRect();
+        const seen = el.checkVisibility ? el.checkVisibility({ visibilityProperty: true, opacityProperty: true }) : true;
+        return seen && r.width > 0 && r.height > 0;
+      }), { anchors, attr: ATTR });
+    } catch (e) { return {}; } finally { if (ctx) await ctx.close().catch(() => {}); }
+  }
+  const everShown = new Set(Object.values(shown).flat());
+  for (const width of WIDTHS) out[width] = anchors.filter((id) => everShown.has(id) && !shown[width].includes(id));
+  return out;
+}
+
+// The anchors a mockup marks as belonging to another state of the screen (Lekhak TF-005): a reason
+// shown only while the database is down, a result shown only after "Test". The mockup says so with
+// data-tf-state="<state>" (or data-state-testid="<id>", Lekhak TF-011) on the control or on a box around it. Such a control is not owed on the
+// first view; when it is drawn and visible it is graded like any other.
+async function stateOnlyOf(b, mockup, anchors) {
+  if (!mockup || !existsSync(mockup) || !anchors || !anchors.length) return [];
+  if (b) {
+    let ctx;
+    try {
+      ctx = await b.newContext();
+      const p = await ctx.newPage();
+      await p.goto('file://' + resolve(mockup), { waitUntil: 'load', timeout: 15000 });
+      return await p.evaluate(({ anchors, attr }) => anchors.filter((id) => {
+        const el = document.querySelector(`[${attr}="${CSS.escape(id)}"]`);
+        return !!el && !!el.closest('[data-tf-state],[data-state-testid]');
+      }), { anchors, attr: ATTR });
+    } catch (e) { /* fall through to the mark on the control itself */ } finally { if (ctx) await ctx.close().catch(() => {}); }
+  }
+  const html = readFileSync(mockup, 'utf8');
+  return anchors.filter((id) => new RegExp(`<[^>]*\\bdata-(?:tf-state|state-testid)\\b[^>]*\\b${ATTR}\\s*=\\s*["']${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["']|<[^>]*\\b${ATTR}\\s*=\\s*["']${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["'][^>]*\\bdata-(?:tf-state|state-testid)\\b`).test(html));
+}
+
 // ---------------------------------------------------------------- browser
 let browser, cdpPage = null;
 if (CDP) {
@@ -70,13 +176,17 @@ if (CDP) {
 } else {
   browser = await chromium.launch();
 }
+// mockups are drawn in a browser of our own: an attached desktop head is the app's, not ours
+const mockBrowser = CDP ? await chromium.launch().catch(() => null) : browser;
 
 function writeOut(extra, results = [], login = null) {
   const summary = {
     mode: CDP ? 'cdp' : 'base', base: BASE || CDP, widths: WIDTHS, login,
     screens: results,
+    skipped,   // screens not driven because their route needs a value (TF-005)
     summary: {
       screens: results.length,
+      skipped: skipped.length,
       render_ok: results.filter((r) => r.render === 'OK').length,
       render_fail: results.filter((r) => r.render === 'EMPTY' || r.render === 'ERROR').length,
       unreachable: results.filter((r) => r.render === 'UNREACHABLE').length,
@@ -90,28 +200,18 @@ function writeOut(extra, results = [], login = null) {
   return summary;
 }
 
-async function login(page) {
-  if (!LOGIN_PATH || !USER) return { attempted: false };
-  try {
-    await page.goto(BASE + LOGIN_PATH, { waitUntil: 'domcontentloaded', timeout: 30000 });
-    const user = page.locator(`[${ATTR}*="user" i], [${ATTR}*="email" i], input[type="email"], input[name*="user" i], input[name*="email" i], input[id*="user" i], input[id*="email" i], input[type="text"]`).first();
-    const pass = page.locator(`[${ATTR}*="pass" i], input[type="password"]`).first();
-    const btn = page.locator(`[${ATTR}*="login" i], [${ATTR}*="signin" i], [${ATTR}*="submit" i], button[type="submit"], form button, input[type="submit"]`).first();
-    await user.fill(USER, { timeout: 10000 });
-    await pass.fill(PASS || '', { timeout: 10000 });
-    await Promise.all([page.waitForLoadState('networkidle', { timeout: 15000 }).catch(() => {}), btn.click({ timeout: 10000 })]);
-    await page.waitForTimeout(SETTLE);
-    const url = page.url();
-    const still = url.startsWith(BASE + LOGIN_PATH);
-    return { attempted: true, ok: !still, url };
-  } catch (e) {
-    return { attempted: true, ok: false, error: e.message.split('\n')[0] };
-  }
-}
+// The sign-in recipe (TF-033, TF-044) and the way a screen behind an in-page sign-in is reached
+// (AppManager TF-006) live in tf-login.mjs since AppManager TF-011, shared with tf-mockup-parity
+// and tf-assets so every check reaches a screen the same way.
+import { signIn, signedOut as signedOutShared, navigateInApp as navigateInAppShared } from './tf-login.mjs';
+const LOGIN_OPTS = { base: BASE, loginPath: LOGIN_PATH, user: USER, password: PASS, attr: ATTR, settle: SETTLE, renderWait: RENDER_WAIT };
+const login = (page) => signIn(page, LOGIN_OPTS);
 
 async function contextFor(width) {
   if (CDP) { await cdpPage.setViewportSize({ width, height: width < 600 ? 844 : 800 }).catch(() => {}); return { page: cdpPage, close: async () => {} }; }
-  const opts = { viewport: { width, height: width < 600 ? 844 : 800 } };
+  // a development head on HTTPS carries a certificate nothing trusts; tf-mockup-parity and tf-assets
+  // already accept it, and without it every screen was UNREACHABLE (Lekhak TF-002)
+  const opts = { viewport: { width, height: width < 600 ? 844 : 800 }, ignoreHTTPSErrors: true };
   if (STORAGE && existsSync(STORAGE)) opts.storageState = STORAGE;
   const ctx = await browser.newContext(opts);
   if (COOKIE) {
@@ -138,9 +238,36 @@ async function navigate(page, route) {
   } catch (e) { return { status: 0, error: e.message.split('\n')[0] }; }
 }
 
+// Signed out: on the sign-in address, or drawing a sign-in form — a password field WITH a sign-in
+// button. A password field alone is not the sign-in page: AppManager's signed-in "Create user" form
+// has one for the new account and was graded unreachable (AppManager TF-012). tf-login.mjs decides.
+const signedOut = (page) => signedOutShared(page, LOGIN_OPTS);
+// Open a route from inside the page, the way its own links do (tf-login.mjs).
+const navigateInApp = (page, route) => navigateInAppShared(page, LOGIN_OPTS, route);
+
+// 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 +276,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 +318,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 +333,21 @@ 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
+      // An inline element that wraps paints one fragment per line, and its bounding box is the union
+      // of them: two sentences sharing a line then "overlap" across the tile's whole width though no
+      // pixel of one is drawn over the other (TF-036, TfLens /effort 2026-09-11). Keep the fragments,
+      // each cut to the painted rectangle, and compare those.
+      let frags = null;
+      if (getComputedStyle(el).display === 'inline') {
+        const fs = [...el.getClientRects()].map((f) => {
+          const x1 = Math.max(f.left, c.x), x2 = Math.min(f.right, c.x + c.w), y1 = Math.max(f.top, c.y), y2 = Math.min(f.bottom, c.y + c.h);
+          return { x: x1, y: y1, w: Math.max(0, x2 - x1), h: Math.max(0, y2 - y1) };
+        }).filter((f) => f.w > 0 && f.h > 0);
+        if (fs.length > 1) frags = fs;
+      }
       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), frags });
     });
     // ancestry so a button inside its card is never an "overlap"
     out.rel = [];
@@ -187,18 +355,21 @@ 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) {
+function grade(info, consoleErrors, width, excused = [], stateOnly = []) {
   const findings = [];
-  if (info.blazor_error) findings.push({ check: 'render', class: 'exception', detail: 'the Blazor error bar is showing' });
+  // a control of another state is graded only when this view draws it, visible and filled (TF-005)
+  const soft = new Set(stateOnly);
+  info = { ...info, anchors: info.anchors.filter((a) => !soft.has(a.id) || (a.present && a.visible && a.filled && a.w > 0 && a.h > 0)) };
+  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)}` });
   if (info.text_len < 15 && info.controls === 0 && !info.anchors.some((a) => a.present)) findings.push({ check: 'render', class: 'blank-data', detail: `the page is blank (${info.text_len} characters of text, no control)` });
   for (const a of info.anchors) {
-    if (!a.present) findings.push({ check: 'render', class: 'blank-data', detail: `anchored control "${a.id}" is not on the page` });
+    if (!a.present && !excused.includes(a.id)) findings.push({ check: 'render', class: 'blank-data', detail: `anchored control "${a.id}" is not on the page` });
     else if (a.visible && !a.filled) findings.push({ check: 'render', class: 'blank-data', detail: `anchored control "${a.id}" (${a.tag}) is empty` });
   }
   for (const t of info.tables) {
@@ -209,7 +380,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);
@@ -220,7 +394,18 @@ function grade(info, consoleErrors, width) {
     const ix = Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x);
     const iy = Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y);
     if (ix <= 4 || iy <= 4) continue;
-    const inter = ix * iy, small = Math.min(a.w * a.h, b.w * b.h);
+    let inter = ix * iy, small = Math.min(a.w * a.h, b.w * b.h);
+    if (a.frags || b.frags) {            // a wrapped inline element: what its fragments share (TF-036)
+      const fa = a.frags || [a], fb = b.frags || [b];
+      const area = (fs) => fs.reduce((s, f) => s + f.w * f.h, 0);
+      inter = 0;
+      for (const p of fa) for (const q of fb) {
+        const px = Math.min(p.x + p.w, q.x + q.w) - Math.max(p.x, q.x), py = Math.min(p.y + p.h, q.y + q.h) - Math.max(p.y, q.y);
+        if (px > 4 && py > 4) inter += px * py;
+      }
+      if (inter === 0) continue;
+      small = Math.min(area(fa), area(fb));
+    }
     if (inter / small > 0.9) continue;       // one lies inside the other by design (a badge on a card)
     if (inter / small < 0.25) continue;      // a touch, not an overlap
     overlaps++;
@@ -246,19 +431,44 @@ for (const width of WIDTHS) {
   if (!CDP) { const l = await login(page); if (loginResult === null) loginResult = l; }
   for (const s of screens) {
     let r = results.find((x) => x.name === s.name);
-    if (!r) { r = { name: s.name, route: s.route, mockup: s.mockup, rows: s.rows, anchors: anchorsOf(s.mockup), widths: [] }; results.push(r); }
+    if (!r) {
+      r = { name: s.name, route: s.route, mockup: s.mockup, rows: s.rows, anchors: anchorsOf(s.mockup), widths: [] }; results.push(r);
+      r.hidden_by_width = await hiddenByWidth(mockBrowser, s.mockup, r.anchors);
+      r.state_only = await stateOnlyOf(mockBrowser, s.mockup, r.anchors);
+      if (s.route_pattern) r.route_pattern = s.route_pattern;
+    }
+    const excused = (r.hidden_by_width || {})[width] || [];
+    const stateOnly = r.state_only || [];
     consoleErrors.length = 0;
-    const nav = await navigate(page, s.route);
+    let nav = await navigate(page, s.route);
     const shot = `${SHOTS}/${slug(s.name)}-${width}.png`;
     const entry = { width, url: nav.url || '', status: nav.status, screenshot: shot, console_errors: [] };
+    // --- AppManager TF-006: a sign-in the page keeps for itself, not in a cookie. The document for a
+    // signed-in screen answers 401 because the server cannot see the sign-in; the page then draws the
+    // screen once its live connection reads the session in the tab, or never, when the sign-in lives
+    // only in that connection. So a 401 or 403 is judged by what the page draws: signed in, the screen
+    // is graded; still signed out, the tool signs in again and opens the screen from inside the page.
+    if (!CDP && LOGIN_PATH && USER && (nav.status === 401 || nav.status === 403)) {
+      await waitForRender(page, [], ATTR);
+      let how = `answered HTTP ${nav.status}, then drew the screen signed in`;
+      if (await signedOut(page)) {
+        how = '';
+        const again = await login(page);
+        if (again.ok && await navigateInApp(page, s.route) && !(await signedOut(page))) how = `answered HTTP ${nav.status}; opened from inside the page after signing in`;
+      }
+      if (how) { entry.reached = how; nav = { status: 200, url: page.url() }; entry.url = nav.url; }
+    }
     const redirectedToLogin = LOGIN_PATH && nav.url && new URL(nav.url).pathname.startsWith(LOGIN_PATH) && !s.route.startsWith(LOGIN_PATH);
     if (nav.status === 0 || nav.status >= 400 || redirectedToLogin) {
       entry.render = 'UNREACHABLE'; entry.visual = 'n/a';
       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);
-      const g = grade(info, consoleErrors, width);
+      entry.render_wait_ms = await waitForRender(page, (r.anchors || []).filter((id) => !excused.includes(id) && !stateOnly.includes(id)), ATTR);
+      const info = await inspect(page, r.anchors || [], ATTR, ERROR_SELECTORS);
+      const g = grade(info, consoleErrors, width, excused, stateOnly);
+      if (excused.length) entry.hidden_in_mockup = excused;
+      if (stateOnly.length) entry.state_only = stateOnly;
       Object.assign(entry, g);
       entry.console_errors = consoleErrors.slice(0, 5);
       entry.anchors_present = (info.anchors || []).filter((a) => a.present).length;
@@ -278,6 +488,7 @@ for (const r of results) {
 }
 const out = writeOut({}, results, loginResult);
 if (loginResult && loginResult.attempted && !loginResult.ok) console.log(`LOGIN failed at ${BASE}${LOGIN_PATH}: ${loginResult.error || 'still on the sign-in page'}`);
-console.log(`screens ${out.summary.screens}: render ${out.summary.render_ok} OK / ${out.summary.render_fail} failed / ${out.summary.unreachable} unreachable; visual ${out.summary.visual_ok} OK / ${out.summary.visual_fail} failed; screenshots ${SHOTS}; JSON ${OUT}`);
+console.log(`screens ${out.summary.screens}${skipped.length ? ` (+${skipped.length} not driven: route needs a value)` : ''}: render ${out.summary.render_ok} OK / ${out.summary.render_fail} failed / ${out.summary.unreachable} unreachable; visual ${out.summary.visual_ok} OK / ${out.summary.visual_fail} failed; screenshots ${SHOTS}; JSON ${OUT}`);
+if (CDP && mockBrowser) await mockBrowser.close().catch(() => {});
 if (!CDP) await browser.close(); else await browser.close().catch(() => {});
 process.exit(firstUnreachable && out.summary.unreachable === out.summary.screens ? 2 : (out.summary.render_fail + out.summary.visual_fail + out.summary.unreachable) ? 5 : 0);