@techierathore/techieflow 1.0.4 → 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,7 +2,8 @@
 // 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
+//   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. Overlap and off-screen are measured
@@ -58,26 +59,112 @@ if (!BASE && !CDP) { console.error('tf-verify-screens: --base URL or --cdp URL i
 
 // ---------------------------------------------------------------- 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) {
@@ -89,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,
@@ -109,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) {
@@ -157,6 +238,13 @@ 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).
@@ -246,8 +334,20 @@ async function inspect(page, anchors, attr, errorSelectors) {
     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: 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) });
+        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 = [];
@@ -258,15 +358,18 @@ async function inspect(page, anchors, attr, errorSelectors) {
   }, { anchors, attr, errorSelectors });
 }
 
-function grade(info, consoleErrors, width) {
+function grade(info, consoleErrors, width, excused = [], stateOnly = []) {
   const findings = [];
+  // 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) {
@@ -291,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++;
@@ -317,20 +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 {
-      entry.render_wait_ms = await waitForRender(page, r.anchors || [], ATTR);
+      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);
+      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;
@@ -350,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);

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

@@ -7,6 +7,10 @@
 #   bash .tfcore/utils/tf-verify-screens.sh --list … --cdp http://172.18.144.1:9223               # an embedded-browser desktop head
 #   … --error-selector '.my-crash-banner'   # the banner THIS stack shows when its client side falls over
 #                                           # (repeatable; defaults cover one framework's id and [data-error-ui])
+#   … --route-value ProviderId=21           # a sample for /x/{ProviderId:long} (repeatable; or "route_values"
+#                                           # in the list); a screen whose route still needs one is SKIPped
+#   A mockup control marked data-tf-state="<state>" (on it or a box around it) belongs to another state
+#   of the screen: it is not owed on the first view.
 #
 # For every screen, at 1280 and 390 px: every control the mockup anchors is present and shows
 # something, no header-only table, no blank page, no Blazor or console error (render); nothing
@@ -22,10 +26,11 @@ HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # `--help` is a request and exits 0; no argument at all is a mistake and exits 3. (The one-line
 # form this replaces computed "0--help" as its exit code and printed a bash error under the help.)
 case "${1:-}" in
-  -h|--help) sed -n '2,19p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
-  "")        sed -n '2,19p' "$0" | sed 's/^# \{0,1\}//'; exit 3 ;;
+  -h|--help) sed -n '2,23p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+  "")        sed -n '2,23p' "$0" | sed 's/^# \{0,1\}//'; exit 3 ;;
 esac
 command -v node >/dev/null 2>&1 || { echo "tf-verify-screens: node is required (bash .tfcore/utils/tf-verify-env.sh)" >&2; exit 4; }
 node -e "import('playwright').then(()=>process.exit(0)).catch(()=>process.exit(1))" 2>/dev/null || {
   echo "tf-verify-screens: the 'playwright' package is not resolvable from this folder; run bash .tfcore/utils/tf-verify-env.sh" >&2; exit 4; }
-exec node "$HERE/tf-verify-screens.mjs" "$@"
+source "$HERE/tf-lock.sh"; tf_take_lock verify-screens   # one browser check at a time (TF-048)
+node "$HERE/tf-verify-screens.mjs" "$@"