@techierathore/techieflow 1.1.0 → 1.2.0

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

@@ -0,0 +1,307 @@
+// tf-verify-native.mjs — the render and visual checks on a MAUI Mac Catalyst head, over Appium mac2.
+// Run through tf-verify-screens.sh --appium <url>, not directly.
+//
+// The native twin of tf-verify-screens.mjs: the same list.json in, the same screens.json out (mode
+// "appium"), so tf-verify-verdict.sh grades a Mac screen exactly as a web one. The mockup's
+// data-testid anchors are looked for as AutomationId (the accessibility identifier the Mac shows).
+//   render  every anchored control is present and shows something (text, a value, or content
+//           inside it); an anchored list has rows; the window is not blank; no error bar.
+//   visual  no two visible controls overlap; no anchored control has zero size or sits outside
+//           the window. (A native window has no stylesheet and no sideways page scroll to check.)
+// A web view head (Blazor Hybrid; boot.json webview, or --no-names): on a Mac neither data-testid
+// nor an HTML id reaches mac2, so controls are not matched by name. Everything else runs: blank
+// window, error bar (--error-text, repeatable; the defaults are the stock Blazor messages), overlap,
+// and the screenshot. Each screen records anchors_not_measured, and the verdict says the name check
+// was not measured (owner decision A, 2026-10-07).
+// A screen is reached by clicking, inside the app, the control whose AutomationId is
+// nav-<screen name> or, failing that, the tab, button, link or list item labelled with the screen's
+// name, or by clicking in turn the labels the list read from the code for it (list.json `nav`, from
+// tf-verify-list.sh: "Images", or "Users" then "+ Add New User"). Only a screen whose route is "/" may be
+// the one the app opens on; any other screen nothing reached is UNREACHABLE and is never graded on
+// whatever was on view (Lekhak TF-027: Search results passed on BlogAdmin's Dashboard). A screen the
+// list says another project serves (a website page, when the Mac head is the desktop app) is skipped
+// as another head's. The session opens the app by its .app path (boot.json app_path, or --app-path)
+// when known, else by bundle id. Each screen is measured at every --widths (default 1280,390): the
+// window is resized through macOS, the width it really took is recorded (an app's minimum size holds),
+// and the screenshot is that window alone, taken by macOS by its window number.
+// --from-source a.xml,b.xml grades saved page sources instead of a running app (one screen per
+// file, no screenshot): how the self-tests check the grading where there is no Mac.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, normalize, resolve } from 'node:path';
+import { openSession, parseSource, descendants, appPid, resizeWindow, windowShot, macWindow } from './tf-appium.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; };
+const args = (n) => argv.flatMap((a, i) => (a === n && i + 1 < argv.length ? [argv[i + 1]] : []));
+const APPIUM = (arg('--appium') || '').replace(/\/$/, '');
+const BOOT = arg('--boot', 'tests/.artifacts/verify/boot.json');
+const boot = existsSync(BOOT) ? JSON.parse(readFileSync(BOOT, 'utf8')) : {};
+const BUNDLE = arg('--bundle') || boot.bundle_id || '';
+const APP_PATH = arg('--app-path') || boot.app_path || '';
+const LIST = arg('--list');
+const MOCKUPS = arg('--mockups', 'docs/mockups');
+const OUT = arg('--json-out', 'tests/.artifacts/verify/screens.json');
+const SHOTS = arg('--shots-dir', 'tests/.artifacts/verify/screens');
+const RENDER_WAIT = parseInt(arg('--render-wait', '5000'), 10);
+const SETTLE = parseInt(arg('--wait', '1500'), 10);   // after a click, before the first look
+const ATTR = arg('--testid-attr', 'data-testid');
+const FROM_SOURCE = (arg('--from-source') || '').split(',').filter(Boolean);
+const NO_NAMES = argv.includes('--no-names') || boot.webview === true;
+const ERROR_TEXTS = [...args('--error-text'), 'An unhandled error has occurred', 'An error has occurred. This application may no longer respond']
+  .map((t) => t.toLowerCase());
+if (!FROM_SOURCE.length && (!APPIUM || !(BUNDLE || APP_PATH))) { console.error('tf-verify-native: --appium URL and the app (boot.json from tf-verify-boot.sh, --bundle or --app-path) are required'); process.exit(3); }
+
+let screens = [];
+if (LIST && !existsSync(LIST)) { console.error(`tf-verify-native: ${LIST} does not exist; make it first with bash .tfcore/utils/tf-verify-list.sh <App> ui`); process.exit(3); }
+if (LIST) screens = (JSON.parse(readFileSync(LIST, 'utf8')).screens || []).map((s) => ({ name: s.name, route: s.route, mockup: s.mockup || '', rows: s.rows || [],
+  nav: s.nav || null, project: s.project || '' }));
+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 (FROM_SOURCE.length && !screens.length) screens = FROM_SOURCE.map((f) => ({ name: basename(f).replace(/\.xml$/, ''), route: '', mockup: '', rows: [] }));
+if (!screens.length) { console.error('tf-verify-native: no screens (--list <json> or --screen name=route)'); process.exit(3); }
+
+const WIDTHS = String(arg('--widths', '1280,390')).split(',').map((x) => parseInt(x, 10)).filter((x) => x > 0);
+// The booted project and every project it references: a screen another project serves is another head's.
+const heads = (() => {
+  const out = new Set(); const todo = boot.project ? [dirname(boot.project)] : [];
+  while (todo.length) {
+    const d = todo.pop().replace(/\/$/, '');
+    if (out.has(d)) continue; out.add(d);
+    try {
+      const proj = readdirSync(d).find((f) => f.endsWith('.csproj'));
+      for (const m of readFileSync(`${d}/${proj}`, 'utf8').matchAll(/<ProjectReference\s+Include="([^"]+)"/g))
+        todo.push(normalize(join(d, dirname(m[1].replace(/\\/g, '/')))));
+    } catch { /* not a project folder */ }
+  }
+  return out;
+})();
+const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+const anchorsOf = (mockup) => {   // as tf-verify-screens.mjs: an attribute on an element, not in a style or script
+  if (!mockup || !existsSync(mockup)) return null;
+  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];
+};
+
+const LISTS = new Set(['CollectionView', 'Table', 'Outline']);
+const CHROME = new Set(['TabBar', 'Toolbar', 'NavigationBar', 'MenuBar', 'Menu']);
+const LEAF = new Set(['Button', 'StaticText', 'TextField', 'SecureTextField', 'TextView', 'Image', 'CheckBox', 'Switch', 'Slider',
+  'PopUpButton', 'ComboBox', 'Link', 'RadioButton', 'SegmentedControl', 'Stepper', 'DatePicker', 'ProgressIndicator', 'Cell']);
+const WEB_CONTROLS = new Set(['Button', 'Link', 'TextField', 'SecureTextField', 'TextView', 'CheckBox', 'RadioButton', 'PopUpButton', 'ComboBox', 'Heading']);
+const shows = (n) => [n.label, n.value, n.title].some((t) => (t || '').trim().length > 0);
+
+function windowOf(nodes) { return nodes.find((n) => n.type === 'Window'); }
+// chrome: bars, menus, and what sits directly on the window (its title, its three buttons)
+function inChrome(nodes, n) {
+  if (n.parent >= 0 && nodes[n.parent].type === 'Window') return true;
+  for (let p = n.parent; p >= 0; p = nodes[p].parent) if (CHROME.has(nodes[p].type)) return true;
+  return CHROME.has(n.type);
+}
+
+// the app has drawn something: text or a control in its content, the window's own title not counted
+function hasContent(nodes) {
+  const win = windowOf(nodes);
+  return !!win && descendants(nodes, win.i).some((n) => !inChrome(nodes, n) && ((n.type === 'StaticText' && shows(n)) || (LEAF.has(n.type) && n.type !== 'StaticText')));
+}
+
+function grade(nodes, anchors) {
+  const findings = [];
+  const win = windowOf(nodes);
+  const inside = win ? descendants(nodes, win.i) : [];
+  const content = inside.filter((n) => !inChrome(nodes, n));
+  const out = { anchors: [] };
+  for (const id of NO_NAMES ? [] : anchors || []) {
+    const n = inside.find((x) => x.id === id);
+    if (!n) { out.anchors.push({ id, present: false }); findings.push({ check: 'render', class: 'blank-data', detail: `anchored control "${id}" is not on the screen (no AutomationId="${id}")` }); continue; }
+    const sub = descendants(nodes, n.i);
+    const lists = [n, ...sub].filter((x) => LISTS.has(x.type));
+    const cells = sub.filter((x) => x.type === 'Cell').length;
+    const filled = shows(n) || sub.some((x) => shows(x) || x.type === 'Cell' || x.type === 'Image' || x.type === 'TextField');
+    out.anchors.push({ id, present: true, type: n.type, filled, x: n.x, y: n.y, w: n.w, h: n.h, rows: lists.length ? cells : undefined });
+    if (lists.length && cells === 0) findings.push({ check: 'render', class: 'zero-rows', detail: `list "${id}" (${lists[0].type}) has no rows` });
+    else if (!filled) findings.push({ check: 'render', class: 'blank-data', detail: `anchored control "${id}" (${n.type}) is empty` });
+    if (n.w === 0 || n.h === 0) findings.push({ check: 'visual', class: 'clipped', detail: `anchored control "${id}" has zero ${n.w === 0 ? 'width' : 'height'}` });
+    else if (win && (n.x < win.x - 2 || n.y < win.y - 2 || n.x + n.w > win.x + win.w + 2 || n.y + n.h > win.y + win.h + 2)) findings.push({ check: 'visual', class: 'offscreen', detail: `anchored control "${id}" sits outside the window` });
+  }
+  // the error bar: shown text naming the app's own crash (a hidden bar is not in the tree at all)
+  const bar = content.find((n) => n.w > 0 && n.h > 0 && ERROR_TEXTS.some((t) => [n.label, n.value].some((v) => (v || '').toLowerCase().includes(t))));
+  if (bar) findings.push({ check: 'render', class: 'exception', detail: `the application's error bar is showing ("${(bar.label || bar.value).slice(0, 80)}")` });
+  if (!win) findings.push({ check: 'render', class: 'blank-data', detail: 'the app has no window open' });
+  else if (!content.some((n) => (n.type === 'StaticText' && shows(n)) || (LEAF.has(n.type) && n.type !== 'StaticText'))) findings.push({ check: 'render', class: 'blank-data', detail: 'the window is blank (no text, no control)' });
+  // overlap: visible leaf controls, never a control and one inside it; the same thresholds as the web
+  // check, on the rectangle each one PAINTS in. The tree gives a text its full size even where its box
+  // cuts it off: a table cell's comment, drawn as "Seeded approved…" in a 50 pt row, reported 170 pt
+  // and "overlapped" the button under the table (Lekhak Comments, 2026-10-07). So each rectangle is
+  // cut to every container's; the tree says nothing of overflow, so text that truly spills out of its
+  // box is not seen here.
+  const clip = (n) => {
+    let x1 = n.x, y1 = n.y, x2 = n.x + n.w, y2 = n.y + n.h;
+    for (let p = n.parent; p >= 0 && nodes[p].type !== 'Window'; p = nodes[p].parent) {
+      const a = nodes[p]; if (a.w <= 0 || a.h <= 0) continue;
+      x1 = Math.max(x1, a.x); y1 = Math.max(y1, a.y); x2 = Math.min(x2, a.x + a.w); y2 = Math.min(y2, a.y + a.h);
+    }
+    return { ...n, x: x1, y: y1, w: Math.max(0, x2 - x1), h: Math.max(0, y2 - y1) };
+  };
+  // In a web view plain text is not compared, as the web check compares controls only (links,
+  // buttons, fields, headings): the tree does not say a box scrolls, so the lines of a scrolled log
+  // report places under the next card (Lekhak AI Story Studio, 2026-10-07).
+  const kinds = NO_NAMES ? WEB_CONTROLS : LEAF;
+  const boxes = content.filter((n) => kinds.has(n.type) && n.w > 0 && n.h > 0).map(clip).filter((n) => n.w > 0 && n.h > 0);
+  const anc = (a, b) => { for (let p = b.parent; p >= 0; p = nodes[p].parent) if (p === a.i) return true; return false; };
+  let overlaps = 0;
+  for (let i = 0; i < boxes.length && overlaps < 5; i++) for (let j = i + 1; j < boxes.length && overlaps < 5; j++) {
+    const a = boxes[i], b = boxes[j];
+    if (anc(a, b) || anc(b, a)) continue;
+    const ix = Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x), iy = Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y);
+    if (ix <= 4 || iy <= 4) continue;
+    const r = (ix * iy) / Math.min(a.w * a.h, b.w * b.h);
+    if (r > 0.9 || r < 0.25) continue;
+    overlaps++;
+    const nm = (e) => e.id || `${e.type} "${(e.label || e.value || '').slice(0, 40)}"`;
+    findings.push({ check: 'visual', class: 'overlap', detail: `${nm(a)} overlaps ${nm(b)}` });
+  }
+  const render = findings.some((f) => f.class === 'exception') ? 'ERROR' : findings.some((f) => f.check === 'render') ? 'EMPTY' : 'OK';
+  const visual = findings.some((f) => f.check === 'visual') ? 'FAIL' : 'OK';
+  return { render, visual, findings, anchors_present: out.anchors.filter((a) => a.present).length, window: win ? { w: win.w, h: win.h } : null };
+}
+
+const skipped = [];
+function writeOut(results, extra = {}, width = 0) {
+  const summary = {
+    mode: 'appium', base: APPIUM, bundle_id: BUNDLE, widths: width ? [width] : [], login: null, screens: results, skipped,
+    anchors_not_measured: NO_NAMES,
+    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,
+      visual_ok: results.filter((r) => r.visual === 'OK').length,
+      visual_fail: results.filter((r) => r.visual === 'FAIL').length,
+    },
+    ...extra,
+  };
+  mkdirSync(dirname(resolve(OUT)), { recursive: true });
+  writeFileSync(OUT, JSON.stringify(summary, null, 2));
+  return summary;
+}
+
+let s = null;
+if (!FROM_SOURCE.length) {
+  try { s = await openSession(APPIUM, { bundleId: BUNDLE, appPath: APP_PATH }); }
+  catch (e) {
+    console.log(`UNREACHABLE appium ${APPIUM} (${APP_PATH || BUNDLE}): ${e.message}`);
+    console.log('  a mac2 session that cannot start is usually a permission: System Settings > Privacy & Security > Accessibility (the terminal, and WebDriverAgentRunner-Runner)');
+    writeOut(screens.map((x) => ({ ...x, anchors: anchorsOf(x.mockup), render: 'UNREACHABLE', visual: 'n/a', widths: [{ width: 0, render: 'UNREACHABLE', visual: 'n/a', findings: [{ check: 'render', class: 'other', detail: `no Appium session: ${e.message}` }] }] })), { unreachable: true, error: e.message });
+    process.exit(2);
+  }
+}
+
+const sleep = (ms) => new Promise((ok) => setTimeout(ok, ms));
+const q = (t) => t.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+// Button 9, RadioButton 10, Link 42 (a web view's menu), Cell 75: the control labelled `text`, else
+// the one whose label holds it (a menu link reads "📷 Images" for the code's "Images")
+async function control(win, text) {
+  for (const value of [`elementType IN {9, 10, 42, 75} AND (label ==[c] '${q(text)}' OR title ==[c] '${q(text)}')`,
+    `elementType IN {9, 10, 42, 75} AND label CONTAINS[c] '${q(text)}'`]) {
+    const el = await s.find('-ios predicate string', value, win).catch(() => null);
+    if (el) return el;
+  }
+  return null;
+}
+async function reach(sc, first) {
+  const name = sc.name;
+  const win = await s.find('-ios predicate string', 'elementType == 4').catch(() => null);
+  if (sc.nav && sc.nav.length) {          // the path the code gives (Lekhak TF-027)
+    for (const [i, label] of sc.nav.entries()) {
+      const el = await control(win, label);
+      if (!el) return { how: '', win, why: `the code links "${label}" to it${i ? ` (after ${sc.nav.slice(0, i).map((x) => `"${x}"`).join(', ')})` : ''}, and no such control was on view` };
+      await s.click(el); await sleep(SETTLE);
+    }
+    return { how: `clicked ${sc.nav.map((x) => `"${x}"`).join(' > ')}`, win };
+  }
+  const el = await s.find('accessibility id', `nav-${slug(name)}`, win).catch(() => null) || await control(win, name);
+  if (el) { await s.click(el); await sleep(SETTLE); return { how: `clicked the control for "${name}"`, win }; }
+  // only the start screen may be the one on view without a click; any other was never shown
+  if (first && ['', '/'].includes(String(sc.route || '').trim())) return { how: 'the screen the app opens on', win };
+  return { how: '', win };
+}
+
+mkdirSync(SHOTS, { recursive: true });
+const results = []; let width = 0;
+const PID = !FROM_SOURCE.length && APP_PATH ? appPid(APP_PATH) : 0;
+const before = PID ? macWindow(PID) : null;            // put back at the end
+let firstDrawn = false;
+for (const [i, sc] of screens.entries()) {
+  // another head's screen: the list says a project the booted one does not include serves it
+  if (sc.project && heads.size && !heads.has(normalize(sc.project))) {
+    skipped.push({ name: sc.name, route: sc.route, rows: sc.rows, reason: `it is served by ${sc.project}, not by the booted head (${boot.project})` });
+    console.log(`SKIP ${sc.name} (${sc.route}) — another head's screen: served by ${sc.project}`);
+    continue;
+  }
+  if (/\{/.test(sc.route || '') && !(sc.nav && sc.nav.length)) {
+    skipped.push({ name: sc.name, route: sc.route, rows: sc.rows, reason: `its route ${sc.route} takes a value and no link in the code reaches it` });
+    console.log(`SKIP ${sc.name} (${sc.route}) — its route takes a value and no link in the code reaches it`);
+    continue;
+  }
+  const r = { name: sc.name, route: sc.route, mockup: sc.mockup, rows: sc.rows, anchors: anchorsOf(sc.mockup), widths: [] };
+  if (NO_NAMES) r.anchors_not_measured = true;
+  results.push(r);
+  const want = NO_NAMES ? [] : r.anchors || [];
+  let nav;
+  try {
+    // the first look: opening the session starts the app again, and a web view took about eight
+    // seconds to draw its first page, menu included (2026-10-07). Wait for it before looking for the menu.
+    if (s && !firstDrawn) { const t1 = Date.now(); while (Date.now() - t1 < Math.max(RENDER_WAIT, 20000) && !hasContent(parseSource(await s.source()))) await sleep(300); firstDrawn = true; }
+    nav = FROM_SOURCE.length ? { how: `saved source ${FROM_SOURCE[i]}` } : await reach(sc, results.length === 1);
+  } catch (e) { nav = { how: '', why: `Appium: ${e.message}` }; }
+  if (!nav.how) {
+    const detail = nav.why ? `${sc.name} was not reached: ${nav.why}`
+      : `no control reaches ${sc.name}: no link to ${sc.route} was found in the code${NO_NAMES ? '' : `; give its tab, flyout item, link or button AutomationId="nav-${slug(sc.name)}"`}, or the label "${sc.name}"`;
+    r.widths.push({ width, url: '', status: 0, screenshot: '', render: 'UNREACHABLE', visual: 'n/a', findings: [{ check: 'render', class: 'other', detail }] });
+  } else {
+    for (const w of PID ? WIDTHS : [0]) {
+      const shot = `${SHOTS}/${slug(sc.name)}${w ? `-${w}` : ''}-mac.png`;
+      let entry;
+      try {
+        const size = w ? resizeWindow(PID, w, w < 700 ? 844 : 800) : null;
+        if (w) await sleep(SETTLE);
+        const t0 = Date.now();
+        const src = async () => parseSource(FROM_SOURCE.length ? readFileSync(FROM_SOURCE[i], 'utf8') : await s.source());
+        let nodes = await src();
+        while (!FROM_SOURCE.length && Date.now() - t0 < RENDER_WAIT && !(want.length ? nodes.some((n) => want.includes(n.id)) : hasContent(nodes))) {
+          await sleep(300); nodes = await src();
+        }
+        const g = grade(nodes, want);
+        if (g.window) width = g.window.w;
+        entry = { width: g.window ? g.window.w : 0, height: g.window ? g.window.h : 0, url: '', status: 200, reached: nav.how, render_wait_ms: Date.now() - t0,
+          screenshot: FROM_SOURCE.length ? '' : shot, render: g.render, visual: g.visual, findings: g.findings, anchors_present: g.anchors_present, console_errors: [] };
+        if (w) { entry.requested_width = w; if (!size || Math.abs(size.w - w) > 8) entry.width_note = size ? `the window stayed ${size.w} px wide (the app's minimum)` : 'macOS did not resize the window (Accessibility for the terminal)'; }
+        if (NO_NAMES) entry.anchors_not_measured = true;
+        if (s) {
+          if (!(PID && windowShot(PID, shot))) {
+            try { writeFileSync(shot, Buffer.from(await s.shot(nav.win), 'base64')); } catch (e) { entry.screenshot = ''; }
+          }
+        }
+      } catch (e) {
+        entry = { width, url: '', status: 0, screenshot: '', render: 'UNREACHABLE', visual: 'n/a', findings: [{ check: 'render', class: 'other', detail: `Appium: ${e.message}` }] };
+      }
+      r.widths.push(entry);
+    }
+  }
+  const worst = r.widths.find((e) => e.render !== 'OK') || r.widths[0];
+  r.render = worst.render; r.visual = r.widths.some((e) => e.visual === 'FAIL') ? 'FAIL' : worst.visual; r.anchors_n = (r.anchors || []).length;
+  const notes = [...new Set(r.widths.flatMap((e) => (e.findings || []).map((f) => f.detail + (e.requested_width ? ` @${e.width}` : ''))))].slice(0, 4);
+  const sizes = r.widths.filter((e) => e.requested_width).map((e) => `${e.width}${e.width_note ? ` (asked ${e.requested_width})` : ''}`);
+  const names = NO_NAMES ? 'names not measured (web view)' : `${r.anchors_n} anchors${r.mockup && !existsSync(r.mockup) ? ' (no mockup file)' : ''}`;
+  console.log(`${r.render === 'OK' && r.visual === 'OK' ? 'OK  ' : 'FAIL'} ${r.name} (${r.route}) — render ${r.render}, visual ${r.visual}, ${names}${sizes.length ? `, @${sizes.join('/')}` : ''}${r.widths[0].reached ? ` — ${r.widths[0].reached}` : ''}${notes.length ? ' — ' + notes.join('; ') : ''}`);
+}
+if (PID && before) resizeWindow(PID, before.w, before.h);
+if (s) await s.close();
+const out = writeOut(results, {}, width);
+console.log(`screens ${out.summary.screens}${skipped.length ? ` (+${skipped.length} skipped)` : ''}: 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${NO_NAMES ? '; control names not measured (web view)' : ''}; screenshots ${SHOTS}; JSON ${OUT}`);
+process.exit(out.summary.screens && 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.mjs

@@ -11,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
@@ -23,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; };
@@ -54,6 +61,14 @@ 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); }
 
@@ -68,7 +83,7 @@ let listValues = {};
 if (LIST) {
   const l = JSON.parse(readFileSync(LIST, 'utf8'));
   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 || {} }));
+  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(/^([^=]+)=(.+)$/);
@@ -114,6 +129,14 @@ const anchorsOf = (mockup) => {
   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
@@ -146,7 +169,8 @@ async function hiddenByWidth(b, mockup, anchors) {
 // 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.
+// 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) {
@@ -157,12 +181,25 @@ async function stateOnlyOf(b, mockup, anchors) {
       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]');
+        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)\\b[^>]*\\b${ATTR}\\s*=\\s*["']${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["']|<[^>]*\\b${ATTR}\\s*=\\s*["']${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["'][^>]*\\bdata-(?:tf-state|state-testid)\\b`).test(html));
+  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
@@ -182,6 +219,7 @@ 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: {
@@ -316,8 +354,27 @@ 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');
+      };
+      // A checkbox, switch or radio drawn by a library (TrBlazeUI: <button role="checkbox"
+      // aria-checked="false">, no text, no child while unticked) paints its own box, the way a native
+      // <input type="checkbox"> does (Lekhak TF-035). Counted filled when it paints; an unpainted one
+      // with no size is still empty.
+      const toggle = '[role="checkbox"],[role="switch"],[role="radio"],[aria-checked]';
+      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.matches(toggle) && paints(el)) || [...el.querySelectorAll(toggle)].some(paints)
+        || [...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 });
@@ -346,7 +403,7 @@ async function inspect(page, anchors, attr, errorSelectors) {
         }).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),
+      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"
@@ -412,6 +469,14 @@ function grade(info, consoleErrors, width, excused = [], stateOnly = []) {
     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';
@@ -423,6 +488,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 = [];
@@ -436,6 +502,7 @@ for (const width of WIDTHS) {
       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 || [];
@@ -463,30 +530,127 @@ for (const width of WIDTHS) {
       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 || []).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;
+      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}${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(() => {});