@techierathore/techieflow 1.1.0 → 1.2.0

package/.tfcore/utils/tf-mockup-parity.mjs

@@ -40,10 +40,12 @@
 // means for a REQ.
 
 import { chromium } from 'playwright';
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { signIn, reach } from './tf-login.mjs';
+import { parseThemes, useTheme, surface, differs, looksDark } from './tf-theme.mjs';
+import { mockupMenus, walkMenus, placeholdersOnPage, reachability } from './tf-menus.mjs';
 
 // ---------------------------------------------------------------- arguments
 const argv = process.argv.slice(2);
@@ -76,9 +78,63 @@ for (let i = 0; i < argv.length; i++) {
     SCREENS.push({ name: name.trim(), route: rest.join('=').trim() || '/' + name.trim() });
   }
 }
+// Where each screen's mockup is (Lekhak TF-022). --list names the list.json tf-verify-list.sh wrote,
+// which holds the path it resolved per screen (docs/mockups/admin/prompt-manager.html); a --screen is
+// matched to a listed screen by its mockup's stem or its name, and with no --screen every listed screen
+// that has a mockup and a route without a {value} is driven. Without a list, a mockup missing at the top
+// of --mockups is looked for in its subfolders, and used when exactly one file has that name.
+const MOCK_OF = {};
+const LIST = arg('--list');
+if (LIST) {
+  const slug = (t) => String(t || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+  let listed = [];
+  try { listed = JSON.parse(readFileSync(LIST, 'utf8')).screens || []; }
+  catch (e) { console.error(`tf-mockup-parity: --list ${LIST} unreadable (${String(e.message).slice(0, 80)})`); }
+  const byKey = {};
+  for (const ls of listed) {
+    if (!ls.mockup) continue;
+    byKey[basename(ls.mockup).replace(/\.html$/, '')] ??= ls;
+    byKey[slug(ls.name)] ??= ls;
+  }
+  if (!SCREENS.length) {
+    for (const ls of listed) {
+      if (ls.mockup && ls.route && !ls.route.includes('{')) SCREENS.push({ name: basename(ls.mockup).replace(/\.html$/, ''), route: ls.route });
+    }
+  }
+  for (const s of SCREENS) {
+    const ls = byKey[s.name] || byKey[slug(s.name)];
+    if (ls) MOCK_OF[s.name] = ls.mockup;
+  }
+}
+const findMockup = (name) => {
+  if (MOCK_OF[name]) return resolve(MOCK_OF[name]);
+  const top = resolve(MOCKUPS, `${name}.html`);
+  if (existsSync(top)) return top;
+  const hits = [];
+  const walk = (dir, depth) => {
+    if (depth > 4) return;
+    let ents = [];
+    try { ents = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (e.isDirectory() && !e.name.startsWith('.')) walk(join(dir, e.name), depth + 1);
+      else if (e.isFile() && e.name === `${name}.html` && dir !== resolve(MOCKUPS)) hits.push(join(dir, e.name));
+    }
+  };
+  walk(resolve(MOCKUPS), 0);
+  return hits.length === 1 ? hits[0] : top;
+};
 const THIN_RATIO = parseFloat(arg('--thin-ratio', '0.25'));
 // --keep-app-theme compares the app in the theme it is showing, not the mockup's (Lekhak TF-010)
 const KEEP_APP_THEME = flag('--keep-app-theme');
+// Lekhak TF-024: a screen is compared in the mockup's own theme and then in the other one. --themes
+// light,dark runs both; light or dark alone runs only that one; auto (the default) runs the other one
+// once the app shows it has it (what it paints changes when that theme is put on it). In the other
+// theme the mockup is drawn in it too; when the mockup does not change under it (no dark styles in the
+// mockup), the app is compared with the mockup as drawn and colour is left out, since the mockup says
+// nothing about it; every other class is compared.
+const THEMES = parseThemes(arg('--themes', 'auto'));
+const wantTheme = (t) => !THEMES || THEMES.includes(t);
+let otherSeen = false;    // auto: has any screen shown the other theme yet?
 // The theme a page declares: data-* attributes on <html> and <body> whose name says theme, mode or
 // scheme (data-theme, data-bs-theme, data-site-theme, data-color-mode …), and the class tokens there
 // that name a light or dark mode (dark, light, theme-dark, dark-mode …), which a class-driven dark mode
@@ -124,6 +180,13 @@ const APPLY_THEME = (t) => {
   return { before, changed };
 };
 const MAX_FINDINGS_PER_SCREEN = parseInt(arg('--max-findings', '40'), 10);
+// Chatur TF-011: a closed menu bar matches its mockup, so menus drawn open (data-tf-state="popup-open") are
+// opened and every item clicked (tf-menus.mjs). --placeholder-text and --no-click are repeatable;
+// --no-menus leaves the menus closed.
+const many = (name) => argv.flatMap((a, i) => (a === name && i + 1 < argv.length ? [argv[i + 1]] : []));
+const PLACEHOLDER_EXTRA = many('--placeholder-text');
+const NO_CLICK_EXTRA = many('--no-click');
+const WALK_MENUS = !flag('--no-menus');
 
 if ((!BASE && !CDP) || SCREENS.length === 0) {
   console.error('usage: tf-mockup-parity.sh --base URL|--cdp URL --screen name=/route [--screen ...]');
@@ -212,7 +275,12 @@ const PROBE = (wanted = []) => {
   // reads every other border property but not this one keeps missing that whole
   // vocabulary. Quantised to the three values that carry meaning rather than the
   // full CSS keyword set, so the clause stays as noise-free as the colour buckets.
+  // A checkbox, switch or radio is not compared by its border (Lekhak TF-035): a native
+  // <input type="checkbox"> computes border-style none because the browser draws its box, while a
+  // library's role="checkbox" draws the same box as a CSS border. Same control, so not applicable.
+  const TOGGLE = 'input[type="checkbox"],input[type="radio"],[role="checkbox"],[role="switch"],[role="radio"]';
   const strokeOf = (el) => {
+    if (el.matches(TOGGLE)) return null;
     const cs = getComputedStyle(el);
     const q = (s) => (s === 'none' || s === 'hidden' ? 'none'
       : s === 'dashed' || s === 'dotted' ? 'dashed' : 'solid');
@@ -223,15 +291,32 @@ const PROBE = (wanted = []) => {
   };
 
   const ICON = 'svg, img, i[class*="icon"], span[class*="icon"], [class*="bi-"], [class*="fa-"]';
-  const hasIcon = (el) => !!el.querySelector(ICON);
+  // A box the mockup marks as another state of the screen is left out of the comparison (Lekhak
+  // TF-011), and so is everything inside it when a box around it is counted: the download icon in a
+  // "newer build" banner was reported on the card holding the banner (Chatur TF-001).
+  // data-tf-state="sample-data" is not another state: it is sample data, the data-tf-sample rule
+  // (Chatur TF-005). Left out here, a list the app fills with real rows read "app carries an icon the
+  // mockup does not" on every row.
+  const STATE = '[data-tf-state]:not([data-tf-state="sample-data"]),[data-state-testid]';
+  const SAMPLE = '[data-tf-sample],[data-tf-state="sample-data"]';
+  // A chart's <svg> is not an icon (TF-054): an svg larger than 48px on either side is left out.
+  const glyph = (x) => x.tagName.toLowerCase() !== 'svg' || (() => { const r = x.getBoundingClientRect(); return r.width <= 48 && r.height <= 48; })();
+  const own = (el, sel) => [...el.querySelectorAll(sel)].filter((x) => (!x.closest(STATE) || el.closest(STATE)) && (sel !== ICON || glyph(x)));
+  const ownText = (el) => {
+    if (!el.querySelector(STATE) || el.closest(STATE)) return el.textContent || '';
+    const c = el.cloneNode(true);
+    for (const x of c.querySelectorAll(STATE)) x.remove();
+    return c.textContent || '';
+  };
+  const hasIcon = (el) => own(el, ICON).length > 0;
   // how many icons the element carries at any depth: a component library that wraps an icon
   // one element deeper than the mockup moves it to another path key without removing it (TF-027)
-  const iconCount = (el) => [...el.querySelectorAll(ICON)].filter((i) => !i.parentElement || !i.parentElement.closest('svg')).length;
+  const iconCount = (el) => own(el, ICON).filter((i) => !i.parentElement || !i.parentElement.closest('svg')).length;
   // Every icon on the page by number, so the node side can tell that an anchor and the wrappers
   // above it hold the same icon as the element it sits in: the icon clause asks "any icon inside?",
   // and one Select chevron was reported at four levels of TfLens /misses (TF-046).
-  const iconNo = new Map([...document.querySelectorAll(ICON)].map((i, n) => [i, n]));
-  const iconIds = (el) => [...el.querySelectorAll(ICON)].map((i) => iconNo.get(i));
+  const iconNo = new Map([...document.querySelectorAll(ICON)].filter(glyph).map((i, n) => [i, n]));
+  const iconIds = (el) => own(el, ICON).map((i) => iconNo.get(i));
   const depthOf = (el) => { let n = 0; for (let p = el.parentElement; p; p = p.parentElement) n++; return n; };
 
   // "Chrome" = a badge / pill / chip: a small element with its own fill or ring and
@@ -369,10 +454,12 @@ const PROBE = (wanted = []) => {
       }
       overX = Math.max(0, Math.round(right - (box.left + el.clientWidth)));
     }
-    let x = overX > 2;
-    if (x && getComputedStyle(el).overflowX === 'visible') x = cutAbove(el, right);
+    const cs = getComputedStyle(el);
+    const scrolls = (v) => v === 'auto' || v === 'scroll';   // a scroller keeps its own content in reach (TF-053)
+    let x = overX > 2 && !scrolls(cs.overflowX);
+    if (x && cs.overflowX === 'visible') x = cutAbove(el, right);
     const overY = el.scrollHeight - el.clientHeight;
-    return { x, y: overY > 2, sr_excluded: hiddenKids.length };
+    return { x, y: overY > 2 && !scrolls(cs.overflowY), sr_excluded: hiddenKids.length };
   };
 
   const sigOf = (el) => {
@@ -383,18 +470,25 @@ const PROBE = (wanted = []) => {
       // the badge and the visible border one element away, for the clauses to accept (TF-047)
       near: {
         badge: near.some((n) => chromeOn(n)?.badge === true),
-        stroke: near.map(strokeOf).find((s) => s.visible) || null,
+        stroke: near.map(strokeOf).find((s) => s && s.visible) || null,
       },
       tag: el.tagName.toLowerCase(),
-      text: (el.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 60),
+      text: ownText(el).trim().replace(/\s+/g, ' ').slice(0, 60),
       badge: chrome ? chrome.badge : null,
-      full: (el.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 400),
+      full: ownText(el).trim().replace(/\s+/g, ' ').slice(0, 400),
+      // a box the mockup marks as sample data, drawn only when the app has data there (Chatur TF-002)
+      sample: el.matches(SAMPLE),
       icon: hasIcon(el),
       icons: iconCount(el),
       icon_ids: iconIds(el),   // which icons, so a finding repeated at a container can be told apart (TF-046)
+      // the anchors inside and the icons each holds, so a row graded on its own can be taken off
+      // the box around it (Chatur TF-006)
+      nested: own(el, '[data-testid]').filter((x) => !isHidden(x))
+        .map((x) => ({ id: x.getAttribute('data-testid'), ids: iconIds(x),
+          top: x.parentElement?.closest('[data-testid]') === el })).slice(0, 200),
       depth: depthOf(el),
       // badges drawn anywhere inside, so a badge one wrapper deeper still counts under its parent (TF-045)
-      badges: [...el.querySelectorAll('*')].filter((c) => !isHidden(c) && chromeOn(c)?.badge).length,
+      badges: own(el, '*').filter((c) => !isHidden(c) && chromeOn(c)?.badge).length,
       color: semanticColor(el),
       stroke: strokeOf(el),
       wrap: lineCount(el),
@@ -418,7 +512,7 @@ const PROBE = (wanted = []) => {
   // data-state-testid="<id>") is not on the first view, so it is neither walked nor counted when its
   // siblings are numbered: a database-down alert first in a card moved every row below it one place,
   // and the Host/Port row was compared with the alert (Lekhak TF-011).
-  const stateOnly = (el) => el.hasAttribute('data-tf-state') || el.hasAttribute('data-state-testid');
+  const stateOnly = (el) => el.matches(STATE);
   const keyOf = (el, parentKey) => {
     const tag = el.tagName.toLowerCase();
     let n = 0;
@@ -447,7 +541,7 @@ const PROBE = (wanted = []) => {
   for (const a of anchors) {
     const id = a.getAttribute('data-testid');
     if (!id || index[id]) continue;
-    if (isHidden(a) || a.closest('[data-tf-state],[data-state-testid]')) continue;   // TF-011
+    if (isHidden(a) || a.closest(STATE)) continue;   // TF-011
     index[id] = sigOf(a);
     let budget = MAX_PER_ANCHOR;
     const walk = (el, key, depth) => {
@@ -488,9 +582,15 @@ const PROBE = (wanted = []) => {
   // taller than the viewport (a table wrapper that grows with its rows is not one), at least 60% of
   // its width and half its height, and across the viewport's centre (a side menu, or a drawer parked
   // off screen, is not one). Without one the document is the app's scroller (AppManager TF-014).
+  // A box that only scrolls sideways is not one either: `overflow-x: auto` alone makes the browser
+  // compute overflow-y as auto too, so Bootstrap's .table-responsive looked like a shell at 390px
+  // (AppManager TF-028). Skipped: a box whose only child is a table, and a box wider inside than
+  // out whose height fits its content.
   const scroller = [...document.querySelectorAll('body *')].find((el) => {
     const o = getComputedStyle(el).overflowY;
     if (o !== 'auto' && o !== 'scroll') return false;
+    if (el.children.length === 1 && el.children[0].tagName === 'TABLE') return false;
+    if (el.scrollWidth > el.clientWidth + 1 && el.scrollHeight <= el.clientHeight + 1) return false;
     const r = el.getBoundingClientRect(), cx = de.clientWidth / 2;
     return r.height <= de.clientHeight + 2 && r.width >= de.clientWidth * 0.6 && r.height >= de.clientHeight / 2
       && r.left <= cx && r.right >= cx;
@@ -570,7 +670,107 @@ const CLAUSES = {
 // as coverage is what let a screen the gate never really looked at read as clean.
 const CONTENT_CLAUSES = new Set(['badge', 'icon', 'wrap', 'token']);
 
-function diff(mock, app, screen, width) {
+function diff(mock, app, screen, width, skip = null) {
+  // --- Chatur TF-002: sample data the app is not showing. A mockup draws a list full of sample rows
+  // and a fresh app has none, so every icon on a sample row read as missing. A box the mockup marks
+  // data-tf-sample is compared when the app draws something at its place; when it draws nothing
+  // there, the box and everything in it are "not measured", and its icons and badges are taken off
+  // the boxes around it. A seed script (tests/verify/seed/) puts the app in the drawn state instead.
+  const notMeasured = [];
+  const mockAll = mock.index;   // before anything is dropped (Chatur TF-007)
+  // the mockup's sample rows that carry their own anchor (commit-row-N), read before any is dropped
+  const fold = (id) => id.replace(/\d+/g, '#');
+  const sampleRows = new Set(Object.keys(mock.index).filter((k) => !k.includes(' > ') && mock.index[k].sample));
+  const sampleShapes = new Set([...sampleRows].map(fold));
+  const idx = { ...mock.index };
+  for (const key of Object.keys(mock.index)) {
+    const m = mock.index[key];
+    if (!m.sample || app.index[key] || notMeasured.some((k) => key.startsWith(k + ' > '))) continue;
+    notMeasured.push(key);
+    for (const k of Object.keys(idx)) if (k === key || k.startsWith(key + ' > ')) delete idx[k];
+    const gone = new Set(m.icon_ids || []);
+    for (let up = key; up.includes(' > ');) {
+      up = up.slice(0, up.lastIndexOf(' > '));
+      const a = idx[up];
+      if (!a) continue;
+      const icons = Math.max(0, (a.icons ?? 0) - (m.icons ?? 0));
+      idx[up] = { ...a, icons, icon: a.icon && icons > 0, icon_ids: (a.icon_ids || []).filter((i) => !gone.has(i)),
+        badges: Math.max(0, (a.badges ?? 0) - (m.badges ?? 0) - (m.badge === true ? 1 : 0)) };
+    }
+  }
+  mock = { ...mock, index: idx };
+  // --- Chatur TF-006: a sample row graded on its own is not the box's icon too. The mockup's table
+  // lost its sample rows' icons when their tbody was not measured, while the app's table still counted
+  // every row's: "app carries an icon the mockup does not" on a box whose rows were each compared. A
+  // row anchored as a mockup sample row, or as more of the same (commit-row-7 beside commit-row-1), is
+  // left out of every box around it on both sides; an icon of the box's own is still counted.
+  const strip = (index, goneOf) => Object.fromEntries(Object.entries(index).map(([k, s]) => {
+    const gone = goneOf(k, s);
+    const ids = (s.icon_ids || []).filter((i) => !gone.has(i));
+    const cut = (s.icon_ids || []).length - ids.length;
+    if (!cut) return [k, s];
+    const icons = Math.max(0, (s.icons ?? 0) - cut);
+    return [k, { ...s, icons, icon: icons > 0, icon_ids: ids }];
+  }));
+  const dropRows = (index, isRow) => strip(index, (k, s) => new Set((s.nested || []).filter((n) => isRow(n.id)).flatMap((n) => n.ids)));
+  if (sampleRows.size) {
+    mock = { ...mock, index: dropRows(mock.index, (id) => sampleRows.has(id)) };
+    app = { ...app, index: dropRows(app.index, (id) => sampleRows.has(id) || (!(id in mock.index) && sampleShapes.has(fold(id)))) };
+  }
+  // --- Chatur TF-007: the app's rows in the place of sample rows not measured. The mockup's list box
+  // lost the icons of sample rows the app does not draw (recent-tflens, tools-table > tbody[0]), while
+  // the app's box kept the icons of the real rows it draws there instead (recent-chatur, a wrapped
+  // tbody): "app carries an icon the mockup does not" on Start, Prerequisites, Providers, Corrections and
+  // the file tree. The app's rows in that place — the children and anchors of the box holding the sample
+  // rows that the mockup does not have — are left out of every box around them, as the sample rows are
+  // on the mockup's side, there taken off every box too, anchors around the list included.
+  // A row's icons come off the boxes AROUND it only: an element above it that holds all of them. A
+  // button inside the row keeps its own icon, or it reads as one the mockup does not carry.
+  const appAll = app.index;
+  const rowsGone = (rows, all) => (k, s) => {
+    const had = new Set(all[k]?.icon_ids || s.icon_ids || []);
+    return new Set(rows.filter((r) => (s.depth ?? 0) < r.depth && r.ids.every((i) => had.has(i))).flatMap((r) => r.ids));
+  };
+  const inPlace = [];
+  // The app's rows in that place are what the mockup does not have under the same box and of the
+  // same kind as the sample row (a tbody for a tbody, an <a> for an <a>), the outermost of them; only
+  // when there is none of that kind, every child of the box the mockup does not have. A heading or a
+  // toolbar of the box's own is not a row.
+  const takeRows = (box, tag) => {
+    const a = appAll[box];
+    if (!a) return;
+    const tagOf = (k) => k.slice(k.lastIndexOf(' > ') + 3).replace(/\[\d+\]$/, '');
+    const same = Object.keys(appAll).filter((k) => k.startsWith(box + ' > ') && !(k in mockAll) && tagOf(k) === tag);
+    const rows = same.filter((k) => !same.some((o) => o !== k && k.startsWith(o + ' > ')))
+      .map((k) => ({ ids: appAll[k].icon_ids || [], depth: appAll[k].depth ?? 0 }));
+    for (const n of a.nested || []) {
+      if (!(n.id in mockAll) && appAll[n.id]?.tag === tag) rows.push({ ids: n.ids, depth: appAll[n.id].depth ?? 0 });
+    }
+    if (!rows.length) {
+      for (const k of Object.keys(appAll)) {
+        if (k.startsWith(box + ' > ') && !k.slice(box.length + 3).includes(' > ') && !(k in mockAll)) {
+          rows.push({ ids: appAll[k].icon_ids || [], depth: appAll[k].depth ?? 0 });
+        }
+      }
+      // and the box's own anchors the mockup does not have: a scroll area holding the rows
+      for (const n of a.nested || []) {
+        if (n.top && !(n.id in mockAll) && appAll[n.id]) rows.push({ ids: n.ids, depth: appAll[n.id].depth ?? 0 });
+      }
+    }
+    inPlace.push(...rows);
+  };
+  const sampleGone = [];
+  for (const k of notMeasured) {
+    sampleGone.push({ ids: mockAll[k].icon_ids || [], depth: mockAll[k].depth ?? 0 });
+    if (k.includes(' > ')) { takeRows(k.slice(0, k.lastIndexOf(' > ')), mockAll[k].tag); continue; }
+    // an anchored sample row: the nearest mockup box holding it
+    const box = Object.keys(mockAll).filter((b) => (mockAll[b].nested || []).some((n) => n.id === k))
+      .sort((x, y) => (mockAll[y].depth ?? 0) - (mockAll[x].depth ?? 0))[0];
+    if (box) takeRows(box, mockAll[k].tag);
+  }
+  const some = (rows) => rows.filter((r) => r.ids.length);
+  if (some(sampleGone).length) mock = { ...mock, index: strip(mock.index, rowsGone(some(sampleGone), mockAll)) };
+  if (some(inPlace).length) app = { ...app, index: strip(app.index, rowsGone(some(inPlace), appAll)) };
   const findings = [];
   const clauseCoverage = Object.fromEntries(Object.keys(CLAUSES).map((k) => [k, 0]));
   clauseCoverage.missing = 0;
@@ -669,6 +869,7 @@ function diff(mock, app, screen, width) {
     }
     compared++;
     for (const [name, fn] of Object.entries(CLAUSES)) {
+      if (skip && skip.has(name)) continue;     // a clause the mockup says nothing about in this theme (TF-024)
       const r = fn(m, a);
       if (r === null) continue;
       clauseCoverage[name]++;
@@ -694,7 +895,7 @@ function diff(mock, app, screen, width) {
       .flatMap((y) => y.side.icon_ids || []));
     if (ids.length && ids.every((i) => below.has(i))) repeat.add(x.f);
   }
-  return { findings: findings.filter((f) => !repeat.has(f)), compared, contentGraded, clauseCoverage, relocated };
+  return { findings: findings.filter((f) => !repeat.has(f)), compared, contentGraded, clauseCoverage, relocated, notMeasured };
 }
 
 // ---------------------------------------------------------------------- main
@@ -753,19 +954,25 @@ for (const width of WIDTHS) {
 if (loginResult && loginResult.attempted && !loginResult.ok) console.error(`tf-mockup-parity: LOGIN failed at ${BASE}${LOGIN_PATH}: ${loginResult.error || 'still on the sign-in page'}`);
 
 for (const s of SCREENS) {
-  const mockPath = resolve(MOCKUPS, `${s.name}.html`);
+  const mockPath = findMockup(s.name);
   // TF-008 §3: a screen with no mockup is reported, never silently passed — the
   // same discipline `⚠ STATIC-ONLY` already uses. Silence is not evidence.
   if (!existsSync(mockPath)) {
     results.push({ screen: s.name, route: s.route, verdict: 'NO-MOCKUP', mockup: mockPath,
-      note: 'no docs/mockups/<screen>.html — this screen was NOT graded against a design. It must not license a Verified on design grounds.' });
+      note: `no ${s.name}.html under ${MOCKUPS} (or several in its subfolders)${LIST ? ` and none named for it in ${LIST}` : '; pass --list tests/.artifacts/verify/list.json'} — this screen was NOT graded against a design. It must not license a Verified on design grounds.` });
     continue;
   }
 
   const perWidth = [];
+  const notOffered = new Set();
   for (const width of WIDTHS) {
     const { app: page, mock: mockPage } = tabs[width];
-    let mock, app, docFindings = [], reached = '', theme = null;
+    let mock, app, docFindings = [], reached = '', theme = null, own = 'light', ownSurface = null, mockSurface = null, mockTheme = null, wanted = [];
+    // Lekhak TF-025: the mockup's site theme stays on the app through the other-theme pass too, and is
+    // taken off only after it. It used to come off after the first pass, so the dark pass compared the
+    // app in the viewer's site theme (minimal, grey primary) with the mockup in its own (blue primary).
+    let saved = null;
+    const unSite = async () => { if (saved && saved.changed) await page.evaluate(APPLY_THEME, saved.before).catch(() => {}); saved = null; };
     try {
       await mockPage.goto(pathToFileURL(mockPath).href, { waitUntil: 'load' });
       mock = await mockPage.evaluate(PROBE);
@@ -782,7 +989,7 @@ for (const s of SCREENS) {
       }
       reached = nav.reached || '';
       await page.waitForLoadState('networkidle', { timeout: 10000 }).catch(() => {});
-      const wanted = [...new Set(Object.values(mock.index).filter((x) => x.badge === true && x.text).map((x) => x.text))];
+      wanted = [...new Set(Object.values(mock.index).filter((x) => x.badge === true && x.text).map((x) => x.text))];
       // Lekhak TF-010: the app is drawn in the mockup's theme for the comparison. The app kept the
       // viewer's saved dark theme, the mockup was light, and every primary button read "mockup accent,
       // app neutral". The mockup's theme attributes on <html> and <body> are copied onto the app page
@@ -790,11 +997,19 @@ for (const s of SCREENS) {
       // Lekhak TF-013: a light/dark class on <html> or <body> is carried the same way, or a class-driven
       // dark mode (class="dark") kept its dark colours under the mockup's light data-theme.
       const mockRead = KEEP_APP_THEME ? null : await mockPage.evaluate(READ_THEME);
-      const mockTheme = DECLARES_THEME(mockRead) ? mockRead : null;
-      const saved = mockTheme ? await page.evaluate(APPLY_THEME, mockTheme).catch(() => null) : null;
+      mockTheme = DECLARES_THEME(mockRead) ? mockRead : null;
+      // The mockup's own theme: what it declares, or, declaring none, what it paints (TF-024). A mockup
+      // that declares none now has the app put in that theme too (its colour scheme as well as its
+      // attributes), so a viewer's saved dark theme no longer decides what a light mockup is compared with.
+      mockSurface = await surface(mockPage);
+      own = mockTheme ? (Object.values(mockTheme).some((v) => /dark/i.test(String(v || ''))) ? 'dark' : 'light')
+        : looksDark(mockSurface) ? 'dark' : 'light';
+      saved = mockTheme ? await page.evaluate(APPLY_THEME, mockTheme).catch(() => null) : null;
       if (saved && saved.changed) { theme = { mockup: mockTheme, app_had: saved.before }; await page.waitForTimeout(400); }
-      try { app = await page.evaluate(PROBE, wanted); }
-      finally { if (saved && saved.changed) await page.evaluate(APPLY_THEME, saved.before).catch(() => {}); }
+      const putBack = KEEP_APP_THEME ? null : await useTheme(page, own);
+      // the mockup's site theme is put back after the other-theme pass below (TF-025)
+      try { app = await page.evaluate(PROBE, wanted); ownSurface = await surface(page); }
+      finally { if (putBack) await putBack(); }
 
       // TF-008 §2. Cheap, no false positives in a shell-scrolled app, and it would
       // have caught the /routing void on its own: 2607px of document against a
@@ -811,12 +1026,50 @@ for (const s of SCREENS) {
       }
     } catch (e) {
       perWidth.push({ width, error: String(e).slice(0, 200) });
+      await unSite();
       continue;
     }
     const d = diff(mock, app, s.name, width);
     d.findings.push(...docFindings);
-    perWidth.push({ width, ...d, mockAnchors: mock.anchors, appAnchors: app.anchors,
-      appTestIds: app.testids, mockTestIds: mock.testids, ...(reached ? { reached } : {}), ...(theme ? { theme } : {}) });
+    if (wantTheme(own)) {
+      perWidth.push({ width, mode: own, ...d, mockAnchors: mock.anchors, appAnchors: app.anchors,
+        appTestIds: app.testids, mockTestIds: mock.testids, ...(reached ? { reached } : {}), ...(theme ? { theme } : {}) });
+    }
+
+    // --- Lekhak TF-024: the other theme. Both pages are drawn in it and put back after, so an
+    // attached app is left in the viewer's theme. Every finding here says which theme it is in.
+    const other = own === 'dark' ? 'light' : 'dark';
+    if (KEEP_APP_THEME || !wantTheme(other)) { await unSite(); continue; }
+    let backApp = null, backMock = null;
+    try {
+      // The app keeps the mockup's site theme, but gets its own light/dark classes back, so that the
+      // switch below flips them as the app's toggle would (a class-driven dark mode, TF-013).
+      if (saved && saved.changed) {
+        const cls = Object.fromEntries(Object.entries(saved.before).filter(([k]) => k.endsWith('|class')));
+        if (Object.keys(cls).length) await page.evaluate(APPLY_THEME, cls).catch(() => {});
+      }
+      backApp = await useTheme(page, other);
+      backMock = await useTheme(mockPage, other, 0);
+      if (!THEMES && !otherSeen && !differs(ownSurface, await surface(page))) { notOffered.add(other); continue; }
+      otherSeen = true;
+      // A mockup that does not change under the other theme does not draw it: forcing it there only
+      // strips the styles it keys on its own theme (a badge losing its fill). The app in the other theme
+      // is then compared with the mockup as drawn, colour left out.
+      const mockDraws = differs(mockSurface, await surface(mockPage));
+      if (!mockDraws) { await backMock(); backMock = null; }
+      const mockO = mockDraws ? await mockPage.evaluate(PROBE) : mock;
+      const appO = await page.evaluate(PROBE, wanted);
+      const d2 = diff(mockO, appO, s.name, width, mockDraws ? null : new Set(['color']));
+      for (const f of d2.findings) f.theme = other;
+      perWidth.push({ width, mode: other, mockup_draws_theme: mockDraws, ...d2, mockAnchors: mockO.anchors, appAnchors: appO.anchors,
+        appTestIds: appO.testids, mockTestIds: mockO.testids, ...(reached ? { reached } : {}) });
+    } catch (e) {
+      perWidth.push({ width, mode: other, error: String(e).slice(0, 200) });
+    } finally {
+      if (backMock) await backMock();
+      if (backApp) await backApp();
+      await unSite();
+    }
   }
 
   const ok = perWidth.filter((w) => !w.error);
@@ -843,9 +1096,13 @@ for (const s of SCREENS) {
   // not read as a thorough screen with one problem — `coverage.ungradeable` stays
   // true either way, so the report can say both things at once.
   const ungradeable = contentGraded === 0;
+  // A width or theme pass that threw was not compared, so it cannot be part of a PASS: a crash in the
+  // dark pass gave PASS on light alone, with nothing saying dark was missing (MISS-TechieFlow-20261009-04).
+  const failedPasses = perWidth.filter((w) => w.error);
   let verdict;
   if (ok.length === 0) verdict = 'ERROR';
   else if (findings.length) verdict = 'FAIL';
+  else if (failedPasses.length) verdict = 'ERROR';
   else if (ungradeable) verdict = 'UNGRADEABLE';
   else verdict = 'PASS';
 
@@ -862,6 +1119,8 @@ for (const s of SCREENS) {
       compared, content_graded: contentGraded, ungradeable,
       // badges found by their text at another depth than the mockup's (TF-045)
       relocated: ok.reduce((n, w) => n + (w.relocated || 0), 0),
+      // sample boxes the app drew nothing at, so not compared (Chatur TF-002)
+      not_measured: [...new Set(ok.flatMap((w) => w.notMeasured || []))],
       app_controls: appAnchors, mockup_anchors: mockAnchors,
       ratio: appAnchors ? +(compared / appAnchors).toFixed(2) : null,
       thin: appAnchors > 0 && compared / appAnchors < THIN_RATIO,
@@ -877,18 +1136,92 @@ for (const s of SCREENS) {
       // Named so the fix is a mechanical edit to the mockup, not a research task.
       add_data_testid_to_mockup: unanchored.slice(0, 30),
     },
-    widths: perWidth.map((w) => ({ width: w.width, error: w.error || null,
+    // the themes it was compared in, and one the app showed no sign of having (TF-024)
+    themes: [...new Set(ok.map((w) => w.mode).filter(Boolean))],
+    ...(notOffered.size ? { themes_not_offered: [...notOffered] } : {}),
+    ...(failedPasses.length ? { not_compared: failedPasses.map((w) => `${w.width}${w.mode ? ' ' + w.mode : ''}: ${w.error}`) } : {}),
+    widths: perWidth.map((w) => ({ width: w.width, ...(w.mode ? { mode: w.mode } : {}),
+      ...(w.mockup_draws_theme === false ? { colour_not_compared: 'the mockup draws no ' + w.mode + ' theme' } : {}), error: w.error || null,
       compared: w.compared || 0, content_graded: w.contentGraded || 0, findings: (w.findings || []).length,
+      not_measured: (w.notMeasured || []).length,
       ...(w.reached ? { reached: w.reached } : {}),       // how a 401 screen was reached signed in (TF-011)
       ...(w.theme ? { theme: w.theme } : {}) })),          // the app was drawn in the mockup's theme (Lekhak TF-010)
   });
 }
 
+// ---------------------------------------------------------------- menus (Chatur TF-011)
+// Each menu the mockups draw open is opened in the app and every item clicked, once, on the first screen
+// that draws it, at the first width. Its findings go on every screen whose mockup draws it; a screen a
+// menu item links to and no click reached gets an `unreachable` finding.
+let menuWalk = { walked: WALK_MENUS, menus: [], clicks: [] };
+if (WALK_MENUS && results.length) {
+  const width = WIDTHS[0];
+  const { app: page, mock: mockPage } = tabs[width];
+  const byScreen = {}, mockText = {}, mockIds = {};
+  for (const r of results) {
+    if (r.verdict === 'NO-MOCKUP' || r.verdict === 'ERROR') continue;
+    try {
+      await mockPage.goto(pathToFileURL(findMockup(r.screen)).href, { waitUntil: 'load' });
+      byScreen[r.screen] = await mockupMenus(mockPage, 'data-testid');
+      mockText[r.screen] = await mockPage.evaluate(() => document.body.innerText || '');
+      // the controls that say a click landed on this screen: anchors outside any other state or open menu
+      mockIds[r.screen] = await mockPage.evaluate(() => [...document.querySelectorAll('[data-testid]')]
+        .filter((e) => !e.closest('[data-tf-state],[data-state-testid],[data-tf-sample]')).map((e) => e.getAttribute('data-testid')));
+    } catch (e) { byScreen[r.screen] = []; }
+  }
+  const key = (m) => `${m.trigger}|${m.popup}`;
+  const done = new Map();
+  const anyMock = Object.values(byScreen).some((l) => l.length);
+  const allClicks = [];
+  for (const r of results) {
+    if (!(r.screen in byScreen)) continue;
+    const todo = byScreen[r.screen].filter((m) => !done.has(key(m)));
+    if (anyMock && !todo.length) continue;
+    if (!anyMock && done.size) break;
+    const back = async () => { if (CDP) await reachCdp(page, r.route); else await reach(page, LOGIN_OPTS, r.route); };
+    try {
+      if (CDP) await page.setViewportSize({ width, height: width < 700 ? 844 : 800 }).catch(() => {});
+      await back();
+      const pages = async () => CDP ? cdpBrowser.contexts().flatMap((c) => c.pages()) : ctx.pages().filter((p) => p !== mockPage && !Object.values(tabs).some((t) => t.mock === p));
+      const w = await walkMenus(page, todo, { attr: 'data-testid', settle: LOGIN_OPTS.settle, back, pages, keepWindows: !!CDP,
+        mockText: mockText[r.screen], placeholders: PLACEHOLDER_EXTRA, noClick: NO_CLICK_EXTRA });
+      menuWalk.menus.push(...w.menus.map((m) => ({ ...m, screen: r.screen })));
+      menuWalk.clicks.push(...w.clicks.map(({ ids_before, ...c }) => ({ ...c, landed: c.landed ? { url: c.landed.url, window: c.landed.window } : null, screen: r.screen })));
+      allClicks.push(...w.clicks);
+      if (!w.from_mockup) { done.set('app|', w.findings); r._menu = w.findings; }
+      for (const m of todo) done.set(key(m), w.findings.filter((f) => f.popup === m.popup));
+    } catch (e) { menuWalk.error = String(e.message || e).split('\n')[0]; }
+  }
+  // what each screen owes: its menus' findings, placeholder text on the page, and a way in that works
+  const ways = reachability(results.filter((r) => r.screen in byScreen).map((r) => ({ name: r.screen, route: r.route, mockup: findMockup(r.screen), anchors: mockIds[r.screen] || [] })), allClicks);
+  menuWalk.reach = ways;
+  for (const r of results) {
+    if (!(r.screen in byScreen)) continue;
+    const add = (byScreen[r.screen] || []).flatMap((m) => done.get(key(m)) || []).concat(r._menu || [])
+      .map((f) => ({ screen: r.screen, width, class: f.class, key: f.popup ? `menu ${f.popup}` : 'menu', detail: f.detail }));
+    try {
+      if (CDP) await reachCdp(page, r.route); else await reach(page, LOGIN_OPTS, r.route);
+      for (const p of await placeholdersOnPage(page, mockText[r.screen], PLACEHOLDER_EXTRA)) add.push({ screen: r.screen, width, class: 'placeholder', key: 'document', detail: `the screen shows placeholder text "${p}"` });
+    } catch (e) { /* the screen was compared above; a second opening that fails adds nothing */ }
+    const rv = ways[r.screen];
+    if (rv && !rv.reached) add.unshift({ screen: r.screen, width, class: 'unreachable', key: 'document', detail: `no menu click reaches ${r.route}: ${rv.tried.join('; ')}` });
+    if (rv && rv.reached) r.reached_by = rv.by;
+    delete r._menu;
+    if (!add.length) continue;
+    r.findings = [...add, ...r.findings].slice(0, MAX_FINDINGS_PER_SCREEN);
+    r.findings_n = r.findings.length;
+    if (r.verdict === 'PASS' || r.verdict === 'UNGRADEABLE') r.verdict = 'FAIL';
+    hardFail = true;
+  }
+}
+for (const r of results) delete r._menu;
+
 await browser.close();
 if (cdpBrowser) await cdpBrowser.close().catch(() => {});   // disconnects; the app keeps running
 
 const summary = {
   status: 'measured',
+  menus: menuWalk,
   base: BASE || CDP, mode: CDP ? 'cdp' : 'base',
   widths: WIDTHS,
   screens_n: results.length,

package/.tfcore/utils/tf-mockup-parity.sh

@@ -9,13 +9,24 @@
 #        --login-path /login --user <u> --password <p>   (or --storage-state <file>)
 #   and each screen is opened in a tab that signed in through the form, the way
 #   tf-verify-screens.sh does; `widths[].reached` in the JSON says how a 401 screen was reached.
+#   --list tests/.artifacts/verify/list.json takes each screen's mockup path from the list
+#   tf-verify-list.sh wrote, so a mockup in a subfolder is found (Lekhak TF-022); with no --screen
+#   it drives every listed screen. Without a list, a mockup in a subfolder is used when it is the only one.
 #   A desktop head (Lekhak TF-006): --cdp http://<host>:9223 in place of --base attaches to the
 #   running app, as tf-verify-screens.sh --cdp does, and opens each route by pushState.
 #   The app is compared in the mockup's theme: the mockup's data-*theme/mode/scheme attributes on
 #   <html> and <body>, and a light/dark mode class there (class="dark", Lekhak TF-013), are set on the
 #   app page for the comparison and put back after (Lekhak TF-010);
-#   --keep-app-theme compares the theme the app shows. A mockup box marked data-tf-state or
-#   data-state-testid (another state of the screen) is left out of the comparison (Lekhak TF-011).
+#   Then the screen is compared again in the other theme (Lekhak TF-024), the mockup drawn in it too:
+#   --themes light,dark runs both, light or dark alone only that one, and auto (the default) runs the
+#   other once the app shows it has it. Colour is not compared in a theme the mockup does not draw.
+#   Each finding of that pass carries "theme"; the result lists "themes" it was compared in.
+#   --keep-app-theme compares the theme the app shows, and only that one. A mockup box marked data-tf-state or
+#   data-state-testid (another state of the screen) is left out of the comparison (Lekhak TF-011),
+#   and so are its icons, badges and text when a box around it is compared (Chatur TF-001).
+#   A box marked data-tf-sample, or data-tf-state="sample-data" (Chatur TF-005), is sample data: compared
+#   when the app draws something in its place,
+#   otherwise listed in coverage.not_measured and taken off the boxes around it (Chatur TF-002).
 #
 # WHAT IT ASKS: "does the built screen carry the structure its approved mockup
 # draws?" — at the same viewports, comparing STRUCTURE, never pixels. Pixel diffing
@@ -58,7 +69,7 @@ set -uo pipefail
 
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
-case "${1:-}" in -h|--help) sed -n '2,48p' "$0"; exit 0 ;; esac
+case "${1:-}" in -h|--help) sed -n '2,56p' "$0"; exit 0 ;; esac
 
 command -v node >/dev/null 2>&1 || {
   echo "tf-mockup-parity: node is required (verify-phase §1 installs the verify environment)." >&2