@techierathore/techieflow 1.0.4 → 1.1.1

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
@@ -10,6 +11,10 @@
 //           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.
+// Themes (Lekhak TF-024): every screen is graded in light mode, then in dark mode when the app has
+// one (its painted surface changes when dark is put on it; --themes light,dark|light|dark forces the
+// choice). In both, the visual check measures text contrast (3.0 : 1 against what is painted behind
+// it, disabled controls exempt) and, in dark mode, large light panels. tf-theme.mjs does both.
 // 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
@@ -22,6 +27,9 @@
 import { chromium } from 'playwright';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { parseThemes, useTheme, surface, differs, audit } from './tf-theme.mjs';
+import { mockupMenus, walkMenus, placeholdersOnPage, reachability } from './tf-menus.mjs';
 
 const argv = process.argv.slice(2);
 const arg = (n, d = null) => { const i = argv.indexOf(n); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : d; };
@@ -53,31 +61,147 @@ const ATTR = arg('--testid-attr', 'data-testid');
 // 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]'];
+// null = auto: light, and dark when the app has a dark theme (Lekhak TF-024)
+const THEMES = parseThemes(arg('--themes', 'auto'));
+const MIN_CONTRAST = parseFloat(arg('--min-contrast', '3'));
+// Chatur TF-011: the menus are opened and every item clicked (tf-menus.mjs). --placeholder-text adds to
+// the deny list, --no-click to the labels never clicked; --no-menus leaves the menus closed (said in the JSON).
+const PLACEHOLDER_EXTRA = args('--placeholder-text');
+const NO_CLICK_EXTRA = args('--no-click');
+const WALK_MENUS = !argv.includes('--no-menus');
 
 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 || {}, seed: s.seed || '' }));
 }
 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 words a mockup draws, so placeholder text the design itself shows is not held against the app
+const mockTexts = {};
+const mockTextOf = (mockup) => {
+  if (!mockup || !existsSync(mockup)) return '';
+  return mockTexts[mockup] ??= readFileSync(mockup, 'utf8').replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<(style|script)\b[\s\S]*?<\/\1\s*>/gi, '').replace(/<[^>]+>/g, ' ').replace(/&nbsp;/g, ' ').replace(/\s+/g, ' ');
+};
+
+// 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. A control on a box marked
+// data-tf-sample (a sample row a fresh app has no data for) is treated the same way (Chatur TF-002).
+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],[data-tf-sample]');
+      }), { 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|tf-sample)\\b[^>]*\\b${ATTR}\\s*=\\s*["']${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["']|<[^>]*\\b${ATTR}\\s*=\\s*["']${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["'][^>]*\\bdata-(?:tf-state|state-testid|tf-sample)\\b`).test(html));
+}
+
+// A screen whose mockup draws sample data the app has none of is compared against an empty view
+// (Chatur TF-002). Its seed, tests/verify/seed/<mockup name>.sh (tf-verify-list.py finds it), puts the
+// running app in the state the mockup draws, once, before the screen is first opened. It is given the
+// app's address as TF_BASE. A seed that fails is the screen's render finding: the screen was not in
+// the state it is graded in.
+function runSeed(seed) {
+  if (!seed) return null;
+  if (!existsSync(seed)) return { path: seed, ok: false, output: 'the seed script is not on disk at that path' };
+  const r = spawnSync('bash', [seed], { env: { ...process.env, TF_BASE: BASE || CDP }, encoding: 'utf8', timeout: 120000 });
+  const output = `${r.stdout || ''}${r.stderr || ''}`.trim().split('\n').slice(-3).join(' | ').slice(0, 300);
+  return { path: seed, ok: r.status === 0, exit: r.status, output: r.error ? String(r.error.message) : output };
+}
+
 // ---------------------------------------------------------------- browser
 let browser, cdpPage = null;
 if (CDP) {
@@ -89,13 +213,18 @@ 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,
+    themes: THEMES || (darkOffered ? ['light', 'dark'] : ['light']),
     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 +238,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 +276,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).
@@ -228,8 +354,21 @@ async function inspect(page, anchors, attr, errorSelectors) {
       if (!el) { out.anchors.push({ id, present: false }); continue; }
       const tag = el.tagName.toLowerCase();
       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;
+      const text = String(el.innerText || el.value || el.getAttribute('aria-label') || '').trim();
+      // A progress bar shows its value as a filled width, not as text (Chatur TF-009): a native
+      // progress or meter, a role="progressbar" carrying aria-valuenow, or a track holding a fill
+      // that has size and paints something (a background, an image or a border).
+      const bar = '[role="progressbar"][aria-valuenow],progress,meter';
+      const paints = (c) => {
+        const cr = c.getBoundingClientRect();
+        if (cr.width <= 0 || cr.height <= 0) return false;
+        const cs = getComputedStyle(c);
+        return !/^(transparent|rgba\(0, 0, 0, 0\))$/.test(cs.backgroundColor) || cs.backgroundImage !== 'none'
+          || ['Top', 'Right', 'Bottom', 'Left'].some((s) => parseFloat(cs[`border${s}Width`]) > 0 && cs[`border${s}Style`] !== 'none');
+      };
+      const filled = text.length > 0 || ['input', 'select', 'textarea', 'img', 'svg', 'canvas', 'video', 'iframe', 'progress', 'meter'].includes(tag)
+        || el.matches(bar) || el.querySelector(`img,svg,canvas,input,select,textarea,button,a,${bar}`) !== null
+        || [...el.children].some(paints);
       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 });
@@ -246,8 +385,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
-      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) });
+      // 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: String(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), frags });
     });
     // ancestry so a button inside its card is never an "overlap"
     out.rel = [];
@@ -258,15 +409,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,13 +445,32 @@ 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++;
     const nm = (e) => e.id || `${e.tag} "${e.text || ''}"`;
     findings.push({ check: 'visual', class: 'overlap', detail: `${nm(a)} overlaps ${nm(b)} at ${width}px` });
   }
+  // Lekhak TF-024: text a reader cannot read, and a white panel left in a dark shell
+  const c = info.contrast;
+  if (c) {
+    for (const x of c.low) findings.push({ check: 'visual', class: 'low-contrast',
+      detail: `text "${x.text}" in ${x.where} is ${x.ratio} : 1 against its background (${x.fg} on ${x.bg}; ${MIN_CONTRAST} : 1 is the minimum)${c.low_n > c.low.length ? `, one of ${c.low_n}` : ''}` });
+    for (const x of c.light) findings.push({ check: 'visual', class: 'light-surface',
+      detail: `${x.where} paints a light panel (${x.bg}, ${x.share}% of the window) in dark mode${x.text ? ` ("${x.text}")` : ''}${c.light_n > c.light.length ? `, one of ${c.light_n}` : ''}` });
+  }
   const render = findings.some((f) => f.check === 'render' && f.class === 'exception') ? 'ERROR'
     : findings.some((f) => f.check === 'render') ? 'EMPTY' : 'OK';
   const visual = findings.some((f) => f.check === 'visual') ? 'FAIL' : 'OK';
@@ -309,6 +482,7 @@ mkdirSync(SHOTS, { recursive: true });
 const results = [];
 let loginResult = null;
 let firstUnreachable = false;
+let darkOffered = false;  // auto mode: has any screen shown a dark theme yet? (Lekhak TF-024)
 for (const width of WIDTHS) {
   const { page, close } = await contextFor(width);
   const consoleErrors = [];
@@ -317,39 +491,162 @@ 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;
+      if (s.seed) r.seed = runSeed(s.seed);
+    }
+    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);
-      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);
-      entry.anchors_present = (info.anchors || []).filter((a) => a.present).length;
+      try { await page.screenshot({ path: shot, fullPage: !CDP }); } catch (e) { entry.screenshot = ''; }
+      r.widths.push(entry);
+      continue;
+    }
+    entry.render_wait_ms = await waitForRender(page, (r.anchors || []).filter((id) => !excused.includes(id) && !stateOnly.includes(id)), ATTR);
+    // one pass per theme on the same opened screen; each pass puts the page back as it found it, so an
+    // attached desktop head is left in the viewer's theme (Lekhak TF-024)
+    let lightSurface = null;
+    for (const theme of THEMES || ['light', 'dark']) {
+      const restore = await useTheme(page, theme);
+      try {
+        if (theme === 'light') lightSurface = await surface(page);
+        if (theme === 'dark' && !THEMES && !darkOffered) {
+          // auto: the app has a dark theme when dark changes what it paints. Asked screen by screen until
+          // one answers yes; from then on every screen is graded in dark, so a screen that ignores the
+          // dark theme altogether is graded in it too, and fails.
+          darkOffered = differs(lightSurface, await surface(page));
+          if (!darkOffered) { r.dark = 'not offered'; continue; }
+        }
+        const te = theme === 'light' ? entry : { ...entry, screenshot: `${SHOTS}/${slug(s.name)}-${width}-${theme}.png` };
+        te.theme = theme;
+        const info = await inspect(page, r.anchors || [], ATTR, ERROR_SELECTORS);
+        info.contrast = await audit(page, theme === 'dark', MIN_CONTRAST);
+        const g = grade(info, theme === 'light' ? consoleErrors : [], width, excused, stateOnly);
+        // a screen still showing placeholder text its mockup does not draw is not built (Chatur TF-011)
+        if (theme === (THEMES || ['light'])[0]) {
+          for (const p of await placeholdersOnPage(page, mockTextOf(s.mockup), PLACEHOLDER_EXTRA)) g.findings.push({ check: 'render', class: 'placeholder', detail: `the screen shows placeholder text "${p}"` });
+          if (g.render === 'OK' && g.findings.some((f) => f.class === 'placeholder')) g.render = 'EMPTY';
+        }
+        if (r.seed && !r.seed.ok) {
+          g.findings.unshift({ check: 'render', class: 'other', detail: `seed ${r.seed.path} failed (exit ${r.seed.exit ?? '?'}): ${r.seed.output}` });
+          if (g.render === 'OK') g.render = 'EMPTY';
+        }
+        if (theme === 'dark') for (const f of g.findings) { f.theme = 'dark'; f.detail += ' in dark mode'; }
+        if (excused.length) te.hidden_in_mockup = excused;
+        if (stateOnly.length) te.state_only = stateOnly;
+        Object.assign(te, g);
+        te.console_errors = theme === 'light' ? consoleErrors.slice(0, 5) : [];
+        te.anchors_present = (info.anchors || []).filter((a) => a.present).length;
+        try { await page.screenshot({ path: te.screenshot, fullPage: !CDP }); } catch (e) { te.screenshot = ''; }
+        r.widths.push(te);
+        if (theme === 'dark') r.dark = 'graded';
+      } finally { await restore(); }
     }
-    try { await page.screenshot({ path: shot, fullPage: !CDP }); } catch (e) { entry.screenshot = ''; }
-    r.widths.push(entry);
   }
   await close();
 }
+
+// ---------------------------------------------------------------- menus (Chatur TF-011)
+// Every menu the mockups draw open is opened in the app and every item clicked, once per menu, on the
+// first screen that draws it, at the first width. What a menu lacks or does wrong is a render finding
+// on every screen whose mockup draws that menu. A screen a menu item links to, which no click reached,
+// is UNREACHABLE.
+let menuWalk = { walked: WALK_MENUS, menus: [], clicks: [] };
+if (WALK_MENUS && mockBrowser) {
+  const byScreen = {};
+  { const ctx = await mockBrowser.newContext(); const mp = await ctx.newPage();
+    for (const s of screens) {
+      if (!s.mockup || !existsSync(s.mockup)) continue;
+      try { await mp.goto('file://' + resolve(s.mockup), { waitUntil: 'load', timeout: 15000 }); byScreen[s.name] = await mockupMenus(mp, ATTR); } catch (e) { byScreen[s.name] = []; }
+    }
+    await ctx.close().catch(() => {}); }
+  const key = (m) => `${m.trigger}|${m.popup}`;
+  const done = new Map();          // menu key -> its findings
+  const width = WIDTHS[0];
+  const anyMockMenus = Object.values(byScreen).some((l) => l.length);
+  for (const s of screens) {
+    const r = results.find((x) => x.name === s.name);
+    if (!r || r.render === 'UNREACHABLE' || r.widths.every((w) => w.render === 'UNREACHABLE')) continue;
+    const todo = (byScreen[s.name] || []).filter((m) => !done.has(key(m)));
+    if (anyMockMenus && !todo.length) continue;
+    if (!anyMockMenus && done.size) break;      // the app's own menus: walked once, on the first screen
+    const { page, close } = await contextFor(width);
+    try {
+      if (!CDP) await login(page);
+      const back = async () => { await navigate(page, s.route); await waitForRender(page, (r.anchors || []).slice(0, 20), ATTR); };
+      await back();
+      const pages = async () => CDP ? browser.contexts().flatMap((c) => c.pages()) : page.context().pages();
+      const w = await walkMenus(page, todo, { attr: ATTR, settle: SETTLE, back, pages, keepWindows: !!CDP, mockText: mockTextOf(s.mockup), placeholders: PLACEHOLDER_EXTRA, noClick: NO_CLICK_EXTRA });
+      menuWalk.menus.push(...w.menus.map((m) => ({ ...m, screen: s.name })));
+      menuWalk.clicks.push(...w.clicks.map(({ ids_before, ...c }) => ({ ...c, landed: c.landed ? { url: c.landed.url, window: c.landed.window } : null, screen: s.name })));
+      menuWalk._clicks = (menuWalk._clicks || []).concat(w.clicks);
+      if (!w.from_mockup) done.set('app|', w.findings);
+      for (const m of todo) done.set(key(m), w.findings.filter((f) => f.popup === m.popup));
+      if (!w.from_mockup) { r.menu_findings = w.findings; }
+    } catch (e) { menuWalk.error = String(e.message || e).split('\n')[0]; }
+    finally { await close(); }
+  }
+  for (const r of results) {
+    const mine = (byScreen[r.name] || []).flatMap((m) => done.get(key(m)) || []).concat(r.menu_findings || []);
+    delete r.menu_findings;
+    if (!mine.length || !r.widths.length) continue;
+    const w0 = r.widths.find((w) => w.render !== 'UNREACHABLE') || r.widths[0];
+    w0.findings = [...(w0.findings || []), ...mine.map((f) => ({ check: 'render', class: f.class, detail: f.detail }))];
+    if (w0.render === 'OK') w0.render = 'EMPTY';
+  }
+  const reach = reachability(screens.map((s) => { const r = results.find((x) => x.name === s.name) || {}; return { ...s, anchors: r.anchors, state_only: r.state_only }; }), menuWalk._clicks || []);
+  delete menuWalk._clicks;
+  menuWalk.reach = reach;
+  for (const [name, v] of Object.entries(reach)) {
+    const r = results.find((x) => x.name === name);
+    if (!r || v.reached) { if (r) r.reached_by = v.by; continue; }
+    r.unreachable_by_menu = `no menu click reaches ${r.route}: ${v.tried.join('; ')}`;
+  }
+}
+
 for (const r of results) {
   const rs = r.widths.map((w) => w.render);
   r.render = rs.includes('UNREACHABLE') ? 'UNREACHABLE' : rs.includes('ERROR') ? 'ERROR' : rs.includes('EMPTY') ? 'EMPTY' : 'OK';
+  if (r.unreachable_by_menu) {
+    // the verdict reads the first finding of an UNREACHABLE screen as its reason
+    r.render = 'UNREACHABLE';
+    r.widths[0].findings = [{ check: 'render', class: 'unreachable', detail: r.unreachable_by_menu }, ...(r.widths[0].findings || [])];
+  }
   r.visual = r.widths.some((w) => w.visual === 'FAIL') ? 'FAIL' : r.render === 'UNREACHABLE' ? 'n/a' : 'OK';
   r.anchors_n = (r.anchors || []).length;
   const notes = r.widths.flatMap((w) => (w.findings || []).map((f) => `${f.detail}`)).slice(0, 4);
-  console.log(`${r.render === 'OK' && r.visual === 'OK' ? 'OK  ' : 'FAIL'} ${r.name} (${r.route}) — render ${r.render}, visual ${r.visual}, ${r.anchors_n} anchors${r.mockup && !existsSync(r.mockup) ? ' (no mockup file)' : ''}${notes.length ? ' — ' + notes.join('; ') : ''}`);
+  r.themes = [...new Set(r.widths.map((w) => w.theme).filter(Boolean))];
+  console.log(`${r.render === 'OK' && r.visual === 'OK' ? 'OK  ' : 'FAIL'} ${r.name} (${r.route}) — render ${r.render}, visual ${r.visual}, ${r.anchors_n} anchors${r.mockup && !existsSync(r.mockup) ? ' (no mockup file)' : ''}, ${r.themes.join(' + ') || 'no'} theme${r.themes.length === 1 ? '' : 's'}${r.dark === 'not offered' ? ' (the app has no dark theme)' : ''}${notes.length ? ' — ' + notes.join('; ') : ''}`);
 }
-const out = writeOut({}, results, loginResult);
+const out = writeOut({ menus: menuWalk }, 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,12 +7,25 @@
 #   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
+#   bash .tfcore/utils/tf-verify-screens.sh --list … --appium http://localhost:4723   # a MAUI Mac Catalyst head
+#        (tf-verify-native.mjs: AutomationId for data-testid, the app's window for the screenshot; the
+#        bundle id comes from boot.json or --bundle; no Playwright needed)
+#   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.
+#   … --themes light,dark | light | dark   # default auto: light, then dark once the app shows it has a
+#                                           # dark theme (what it paints changes when dark is put on it)
+#   … --min-contrast 3                      # the text contrast floor, ratio : 1 (Lekhak TF-024)
 #
 # 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
 # overlaps, nothing has zero size or sits off-screen, no sideways scroll, a stylesheet is loaded
-# (visual). Overlap and off-screen are measured on the rectangle an element paints in, clipped by
-# every scrolling ancestor, and the page is read only after its first render (--render-wait,
+# (visual); every text run reaches 3.0 : 1 against the colour painted behind it (disabled controls
+# exempt) and, in dark mode, no box over 2% of the window paints a light panel (visual). Each theme is
+# put on the page through prefers-color-scheme and the light/dark value of its data-*theme attributes
+# and mode classes, and taken off again after. Overlap and off-screen are measured on the rectangle an
+# element paints in, clipped by every scrolling ancestor, and the page is read only after its first render (--render-wait,
 # default 5000 ms). Saves a screenshot per screen and width under tests/.artifacts/verify/screens/ and
 # writes tests/.artifacts/verify/screens.json; that JSON is the evidence a smoke names before a
 # row is written Implemented, and what the verdict script reads. It decides no row's status.
@@ -22,10 +35,15 @@ 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,32p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+  "")        sed -n '2,32p' "$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; }
+case " $* " in *" --appium "*)
+  source "$HERE/tf-lock.sh"; tf_take_lock verify-screens
+  node "$HERE/tf-verify-native.mjs" "$@"; exit $? ;;
+esac
 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" "$@"