@techierathore/techieflow 1.0.3 → 1.1.0

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

@@ -43,6 +43,7 @@ import { chromium } from 'playwright';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { signIn, reach } from './tf-login.mjs';
 
 // ---------------------------------------------------------------- arguments
 const argv = process.argv.slice(2);
@@ -53,10 +54,19 @@ const arg = (name, dflt = null) => {
 const flag = (name) => argv.includes(name);
 
 const BASE = (arg('--base') || '').replace(/\/$/, '');
+// An embedded-browser desktop head, attached over its DevTools port as tf-verify-screens does; its
+// screens are opened the way its router does, by pushState (Lekhak TF-006).
+const CDP = arg('--cdp') || '';
 const MOCKUPS = arg('--mockups', 'docs/mockups');
 const WIDTHS = (arg('--widths', '1280,390') || '').split(',').map((w) => parseInt(w.trim(), 10)).filter(Boolean);
 const JSON_OUT = arg('--json-out');
 const COOKIE = arg('--cookie');
+// A sign-in the page keeps for itself sets no cookie, so --cookie could not reach AppManager's screens
+// at all: "app returned HTTP 401" at both widths (AppManager TF-011). The same --login-path, --user,
+// --password and --storage-state tf-verify-screens takes, through the shared recipe in tf-login.mjs.
+const LOGIN_PATH = arg('--login-path'); const USER = arg('--user'); const PASS = arg('--password');
+const STORAGE = arg('--storage-state');
+const LOGIN_OPTS = { base: BASE, loginPath: LOGIN_PATH, user: USER, password: PASS, settle: 1500, renderWait: 5000 };
 const HEADERS = [];
 for (let i = 0; i < argv.length; i++) if (argv[i] === '--header' && argv[i + 1]) HEADERS.push(argv[i + 1]);
 const SCREENS = [];
@@ -67,10 +77,56 @@ for (let i = 0; i < argv.length; i++) {
   }
 }
 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');
+// 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
+// such as Tailwind's `dark` uses (Lekhak TF-013). A utility class such as bg-light does not count.
+// Nothing about any one stack. The class tokens are kept under `<where>|class`, '' when there are none.
+const READ_THEME = () => {
+  const MODE = /^(?:(?:theme|mode|scheme|color)[-_])?(?:dark|light)(?:[-_](?:theme|mode|scheme))?$/i;
+  const out = {};
+  for (const [where, el] of [['html', document.documentElement], ['body', document.body]]) {
+    if (!el) continue;
+    for (const a of el.attributes) if (/^data-.*(theme|mode|scheme)/i.test(a.name)) out[`${where}|${a.name}`] = a.value;
+    out[`${where}|class`] = [...el.classList].filter((c) => MODE.test(c)).join(' ');
+  }
+  return out;
+};
+// A page declares a theme when it has such an attribute or mode class. A mockup that declares none
+// leaves the app as it is.
+const DECLARES_THEME = (t) => !!t && Object.entries(t).some(([k, v]) => !k.endsWith('|class') || v);
+// Sets those attributes and mode classes on this page; returns what it had, so the same call puts it
+// back. An attribute the page lacked is removed again on the way back (value null). For `|class` the
+// page's own mode tokens are replaced by the given ones; every other class is left alone.
+const APPLY_THEME = (t) => {
+  const MODE = /^(?:(?:theme|mode|scheme|color)[-_])?(?:dark|light)(?:[-_](?:theme|mode|scheme))?$/i;
+  const before = {}; let changed = false;
+  for (const [k, v] of Object.entries(t || {})) {
+    const [where, name] = k.split('|');
+    const el = where === 'body' ? document.body : document.documentElement;
+    if (!el) continue;
+    if (name === 'class') {
+      const had = [...el.classList].filter((c) => MODE.test(c));
+      const want = String(v || '').split(/\s+/).filter(Boolean);
+      before[k] = had.join(' ');
+      if (had.slice().sort().join(' ') !== want.slice().sort().join(' ')) changed = true;
+      for (const c of had) el.classList.remove(c);
+      for (const c of want) el.classList.add(c);
+      continue;
+    }
+    const had = el.getAttribute(name);
+    before[k] = had;
+    if (had !== v) changed = true;
+    if (v === null) el.removeAttribute(name); else el.setAttribute(name, v);
+  }
+  return { before, changed };
+};
 const MAX_FINDINGS_PER_SCREEN = parseInt(arg('--max-findings', '40'), 10);
 
-if (!BASE || SCREENS.length === 0) {
-  console.error('usage: tf-mockup-parity.sh --base URL --screen name=/route [--screen ...]');
+if ((!BASE && !CDP) || SCREENS.length === 0) {
+  console.error('usage: tf-mockup-parity.sh --base URL|--cdp URL --screen name=/route [--screen ...]');
   process.exit(3);
 }
 
@@ -78,7 +134,9 @@ if (!BASE || SCREENS.length === 0) {
 // Everything below runs INSIDE the browser, on both the mockup and the app, and
 // returns one flat index keyed by a stable path key. It is deliberately one
 // evaluate() call: two passes over the same DOM can disagree after a re-layout.
-const PROBE = () => {
+// `wanted` names the texts of the mockup's badges, so the app's side can find each one at whatever
+// depth the app drew it (TF-045); the mockup's own probe is called without it.
+const PROBE = (wanted = []) => {
   const MAX_DEPTH = 4;        // descend this far below an anchor
   const MAX_PER_ANCHOR = 60;  // and no further; a huge subtree is noise, not signal
 
@@ -100,11 +158,23 @@ const PROBE = () => {
     return false;
   };
 
+  // --- TF-027: the browser converts the colour, never a regex. getComputedStyle returns a
+  // colour in the syntax it was written in, and a component library themed in oklch() came
+  // back as "oklch(0.971 0.013 17.38)": read as r/g/b those three numbers are near-black, so
+  // every tinted tile, pill and icon in the app bucketed as neutral against a mockup written
+  // in hex — "semantic colour differs — mockup negative, app neutral" on tiles plainly red.
+  // Painting one pixel and reading it back gives sRGB for any syntax the browser accepts.
+  const px = document.createElement('canvas');
+  px.width = px.height = 1;
+  const pctx = px.getContext('2d', { willReadFrequently: true });
   const RGB = (v) => {
-    const m = (v || '').match(/-?[\d.]+/g);
-    if (!m || m.length < 3) return null;
-    const a = m.length > 3 ? parseFloat(m[3]) : 1;
-    return a < 0.05 ? null : { r: +m[0], g: +m[1], b: +m[2] };
+    if (!v || v === 'transparent' || !pctx) return null;
+    pctx.clearRect(0, 0, 1, 1);
+    pctx.fillStyle = 'rgba(0,0,0,0)';
+    pctx.fillStyle = v;                    // an unparseable value leaves it transparent
+    pctx.fillRect(0, 0, 1, 1);
+    const [r, g, b, a] = pctx.getImageData(0, 0, 1, 1).data;
+    return a / 255 < 0.05 ? null : { r, g, b };
   };
 
   // Semantic BUCKET, never the literal colour: two designs may legitimately differ
@@ -114,15 +184,26 @@ const PROBE = () => {
     const { r, g, b } = c;
     const mx = Math.max(r, g, b), mn = Math.min(r, g, b);
     if (mx - mn < 28) return 'neutral';
-    if (r > g && r > b) return g > 120 ? 'warning' : 'negative';
-    if (g > r && g > b) return 'positive';
-    if (b > r && b > g) return 'accent';
-    return 'neutral';
+    // By hue, never by one channel. "Red is highest, so green above 120 is a warning" put a deep
+    // amber (180, 83, 9) in `negative` beside a light amber in `warning` — one warning tone on two
+    // sides of the line, reported as a colour difference on TfLens /misses (TF-045).
+    const d = mx - mn;
+    const h = ((mx === r ? ((g - b) / d) % 6 : mx === g ? (b - r) / d + 2 : (r - g) / d + 4) * 60 + 360) % 360;
+    if (h < 15 || h >= 330) return 'negative';
+    if (h < 70) return 'warning';
+    if (h < 185) return 'positive';
+    return 'accent';
   };
 
+  // A border nobody draws carries no colour. `border: 1px solid transparent` is how a mockup
+  // reserves space, and a page reset that sets border-color everywhere leaves the property set on
+  // elements with no border at all: reading it gave a borderless icon the reset's grey and called
+  // it a colour difference (TF-038).
+  const drawnBorder = (cs) => (parseFloat(cs.borderTopWidth) || 0) > 0 && !!RGB(cs.borderTopColor);
+
   const semanticColor = (el) => {
     const cs = getComputedStyle(el);
-    return bucket(RGB(cs.backgroundColor)) || bucket(RGB(cs.borderTopColor)) || bucket(RGB(cs.color));
+    return bucket(RGB(cs.backgroundColor)) || (drawnBorder(cs) ? bucket(RGB(cs.borderTopColor)) : null) || bucket(RGB(cs.color));
   };
 
   // --- TF-009: the seventh class. A mockup says "provisional / estimated /
@@ -136,12 +217,22 @@ const PROBE = () => {
     const q = (s) => (s === 'none' || s === 'hidden' ? 'none'
       : s === 'dashed' || s === 'dotted' ? 'dashed' : 'solid');
     const sides = ['borderTopStyle', 'borderRightStyle', 'borderBottomStyle', 'borderLeftStyle'].map((k) => q(cs[k]));
-    const w = parseFloat(cs.borderTopWidth) || 0;
-    const style = w === 0 ? 'none' : sides[0];
-    return { style, uniform: new Set(sides).size === 1, visible: w > 0 };
+    const drawn = drawnBorder(cs);       // width AND a colour: transparent draws nothing (TF-038)
+    const style = drawn ? sides[0] : 'none';
+    return { style, uniform: new Set(sides).size === 1, visible: drawn };
   };
 
-  const hasIcon = (el) => !!el.querySelector('svg, img, i[class*="icon"], span[class*="icon"], [class*="bi-"], [class*="fa-"]');
+  const ICON = 'svg, img, i[class*="icon"], span[class*="icon"], [class*="bi-"], [class*="fa-"]';
+  const hasIcon = (el) => !!el.querySelector(ICON);
+  // 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;
+  // 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 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
   // a rounded edge. The mockup drawing one and the app rendering bare text is the
@@ -153,10 +244,30 @@ const PROBE = () => {
     const cs = getComputedStyle(el);
     const radius = parseFloat(cs.borderTopLeftRadius) || 0;
     const filled = !!RGB(cs.backgroundColor);
-    const ringed = (parseFloat(cs.borderTopWidth) || 0) > 0;
+    const ringed = drawnBorder(cs);      // a transparent ring is not a ring (TF-038)
     return { badge: (filled || ringed) && radius >= 6, filled, ringed, radius: Math.round(radius) };
   };
 
+  // --- TF-047: the treatment one element away. A component library draws the ring and the radius on
+  // the box AROUND the control the mockup styles (an InputGroup around a filter input, a nav <li>
+  // around the active link), and a mockup does the reverse. Keys pair by position, so the badge and
+  // stroke clauses compared the control with the plain box beside the one that carries the treatment:
+  // "badge on nav > a[4], app plain" on TfLens's sidebar, on every screen. The element's neighbours
+  // one step away are kept here — the parent when it is the same row (same height, its other
+  // children carrying no text: an icon, or the box a library wraps one in) and the only child when
+  // it is — so a clause can accept the treatment there.
+  const nearOf = (el) => {
+    const out = [];
+    const h = el.getBoundingClientRect().height;
+    const sameRow = (x) => Math.abs(x.getBoundingClientRect().height - h) <= 8;
+    const p = el.parentElement;
+    if (p && p !== document.body && sameRow(p)
+        && [...p.children].every((s) => s === el || isHidden(s) || !(s.textContent || '').trim())) out.push(p);
+    const kids = [...el.children].filter((c) => !isHidden(c));
+    if (kids.length === 1 && sameRow(kids[0])) out.push(kids[0]);
+    return out;
+  };
+
   // Only text that is genuinely a single inline run can be graded for wrapping or
   // token fit. A container with block children has no meaningful line count, and
   // pretending otherwise is how a card-shaped anchor buys nothing (TF-011).
@@ -173,8 +284,11 @@ const PROBE = () => {
     const cs = getComputedStyle(el);
     let lh = parseFloat(cs.lineHeight);
     if (!lh || Number.isNaN(lh)) lh = (parseFloat(cs.fontSize) || 16) * 1.2;
-    const h = el.getBoundingClientRect().height;
-    if (!h || !lh) return null;
+    // the text's height only: padding and borders are not rows. A badge with 4px padding and
+    // `line-height: 1` read 18 / 9.756 = 1.85, rounded to 2 rows (AppManager TF-015).
+    const h = el.getBoundingClientRect().height
+      - ['paddingTop', 'paddingBottom', 'borderTopWidth', 'borderBottomWidth'].reduce((s, k) => s + (parseFloat(cs[k]) || 0), 0);
+    if (!(h > 0) || !lh) return null;
     return Math.max(1, Math.round(h / lh));
   };
 
@@ -206,33 +320,81 @@ const PROBE = () => {
   // --- TF-012 again, on the measuring side. scrollWidth includes the phantom
   // extent of an sr-only descendant, so the ancestor is measured from the right
   // edge of its VISIBLE descendants instead whenever a hidden one is present.
+  // A descendant inside a scroller is painted only as far as that scroller's edge, so its own box
+  // must be cut by every ancestor that clips before it can count as the card overflowing. Without
+  // that, a table scrolling inside its wrapper — the layout the BRD asks for — read as a card cut
+  // off at 390px (TF-039). The same rectangle tf-verify-screens measures since TF-021.
+  // The cut stops BELOW `stop`: the element being measured must not cut its own content, or a card
+  // that really clips would read as holding everything (it did, from TF-039 until TF-042).
+  const paintedRight = (c, stop) => {
+    const r = c.getBoundingClientRect();
+    let x1 = r.left, x2 = r.right;
+    for (let a = c.parentElement; a && a !== stop; a = a.parentElement) {
+      if (getComputedStyle(a).overflowX !== 'visible') {
+        const ar = a.getBoundingClientRect();
+        x1 = Math.max(x1, ar.left); x2 = Math.min(x2, ar.right);
+      }
+    }
+    return x2 > x1 ? x2 : null;
+  };
+
+  // --- TF-042: overflow is not clipping. An element whose overflow-x is `visible` draws what spills
+  // past its edge in full, so it is cut off only where an ancestor that clips ends first. Reading
+  // scrollWidth alone called a sidebar "cut off" because its rail handle straddles its edge by 8px,
+  // on every TfLens screen, with nothing clipped anywhere up to <html> (2026-09-12).
+  const cutAbove = (el, right) => {
+    for (let a = el.parentElement; a; a = a.parentElement) {
+      if (getComputedStyle(a).overflowX === 'visible') continue;
+      if (right > a.getBoundingClientRect().left + a.clientLeft + a.clientWidth + 2) return true;
+    }
+    return false;
+  };
+
   const clipOf = (el) => {
     const hiddenKids = [...el.querySelectorAll('*')].filter(isHidden);
-    let overX;
+    const box = el.getBoundingClientRect();
+    let overX, right;
     if (hiddenKids.length === 0) {
       overX = el.scrollWidth - el.clientWidth;
+      right = box.left + el.clientLeft + el.scrollWidth;
     } else {
-      const box = el.getBoundingClientRect();
-      let right = box.left;
+      right = box.left;
       for (const c of el.querySelectorAll('*')) {
         if (isHidden(c)) continue;
         const r = c.getBoundingClientRect();
-        if (r.width > 0) right = Math.max(right, r.right);
+        if (r.width > 0) {
+          const painted = paintedRight(c, el);
+          if (painted !== null) right = Math.max(right, painted);
+        }
       }
       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 overY = el.scrollHeight - el.clientHeight;
-    return { x: overX > 2, y: overY > 2, sr_excluded: hiddenKids.length };
+    return { x, y: overY > 2, sr_excluded: hiddenKids.length };
   };
 
   const sigOf = (el) => {
     const r = el.getBoundingClientRect();
     const chrome = chromeOn(el);
+    const near = nearOf(el);
     return {
+      // 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,
+      },
       tag: el.tagName.toLowerCase(),
       text: (el.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 60),
       badge: chrome ? chrome.badge : null,
+      full: (el.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 400),
       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)
+      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,
       color: semanticColor(el),
       stroke: strokeOf(el),
       wrap: lineCount(el),
@@ -252,16 +414,32 @@ const PROBE = () => {
   // table already was. Keys pair only when both sides produce them, so extra depth
   // costs precision nothing — it only ever adds comparisons that were impossible
   // before.
+  // A box the mockup marks as another state of the screen (data-tf-state="<state>", or
+  // 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 keyOf = (el, parentKey) => {
     const tag = el.tagName.toLowerCase();
     let n = 0;
     for (const s of el.parentElement ? el.parentElement.children : []) {
       if (s === el) break;
-      if (s.tagName === el.tagName) n++;
+      if (s.tagName === el.tagName && !stateOnly(s)) n++;
     }
     return `${parentKey} > ${tag}[${n}]`;
   };
 
+  // --- TF-045: the same badge, one wrapper deeper. Keys are positional, so a component library that
+  // wraps a card header's contents in one more <div> moves every badge in it to a key the mockup
+  // never has: 32 "missing" findings on three TfLens screens, each drawn on the page with the right
+  // text. For every text a mockup badge carries, the elements under the same anchor that carry it
+  // are kept here at any depth, so the node side can find the badge where the app put it. Digits
+  // are folded, because live data is not the mockup's sample: "87 of 91" is "39 of 41". Case is
+  // kept: a card titled "Draft" is not its badge "draft".
+  const norm = (t) => (t || '').replace(/\d[\d,.]*/g, '#').replace(/\s+/g, ' ').trim();
+  const want = new Set((wanted || []).map(norm).filter(Boolean));
+  const pool = {};
+
   const index = {};
   const anchors = [...document.querySelectorAll('[data-testid]')];
   const allTestIds = anchors.map((a) => a.getAttribute('data-testid'));
@@ -269,7 +447,7 @@ const PROBE = () => {
   for (const a of anchors) {
     const id = a.getAttribute('data-testid');
     if (!id || index[id]) continue;
-    if (isHidden(a)) continue;
+    if (isHidden(a) || a.closest('[data-tf-state],[data-state-testid]')) continue;   // TF-011
     index[id] = sigOf(a);
     let budget = MAX_PER_ANCHOR;
     const walk = (el, key, depth) => {
@@ -278,6 +456,7 @@ const PROBE = () => {
         if (budget <= 0) return;
         if (c.hasAttribute('data-testid')) continue;   // it gets its own top-level entry
         if (isHidden(c)) continue;                     // TF-012
+        if (stateOnly(c)) continue;                    // another state of the screen (TF-011)
         const k = keyOf(c, key);
         index[k] = sigOf(c);
         budget--;
@@ -285,11 +464,40 @@ const PROBE = () => {
       }
     };
     walk(a, id, 1);
+    if (want.size) {
+      const found = [];
+      const queue = [[a, id, 0]];
+      let seen = 0;
+      while (queue.length && seen < 800 && found.length < 30) {
+        const [el, key, depth] = queue.shift();
+        if (depth >= 12) continue;
+        for (const c of el.children) {
+          if (c.hasAttribute('data-testid') || isHidden(c) || stateOnly(c)) continue;
+          seen++;
+          const k = keyOf(c, key);
+          if (want.has(norm((c.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 60)))) found.push({ key: k, ...sigOf(c) });
+          queue.push([c, k, depth + 1]);
+        }
+      }
+      pool[id] = found;
+    }
   }
 
   const de = document.documentElement;
+  // the shell's content scroll container, when it has one: a box that scrolls inside itself, no
+  // 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).
+  const scroller = [...document.querySelectorAll('body *')].find((el) => {
+    const o = getComputedStyle(el).overflowY;
+    if (o !== 'auto' && o !== 'scroll') 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;
+  });
   return {
     index,
+    pool,
     anchors: anchors.length,
     testids: allTestIds,
     doc: {
@@ -297,6 +505,7 @@ const PROBE = () => {
       clientHeight: de.clientHeight,
       scrollWidth: de.scrollWidth,
       clientWidth: de.clientWidth,
+      scroller: scroller ? `${scroller.tagName.toLowerCase()}${scroller.id ? '#' + scroller.id : ''}${scroller.className ? '.' + String(scroller.className).trim().split(/\s+/)[0] : ''}` : null,
     },
   };
 };
@@ -305,11 +514,18 @@ const PROBE = () => {
 // A clause returns a finding, `null` (not applicable — do NOT count it as graded),
 // or `false` (applicable and agreeing). The three are kept distinct because
 // conflating "agreed" with "not asked" is precisely how TF-011 happened.
+// The same folding the page-side probe uses: spacing and digits (TF-045).
+const norm = (t) => (t || '').replace(/\d[\d,.]*/g, '#').replace(/\s+/g, ' ').trim();
+
 const CLAUSES = {
-  badge: (m, a) => (m.badge === null || a.badge === null ? null
-    : m.badge !== a.badge
-      ? `mockup renders this as a ${m.badge ? 'badge/pill' : 'plain element'}, app renders it as a ${a.badge ? 'badge/pill' : 'plain element'}`
-      : false),
+  badge: (m, a) => {
+    if (m.badge === null || a.badge === null) return null;
+    if (m.badge === a.badge) return false;
+    // TF-047: the side without the treatment carries it one element away — the same control, drawn
+    // by a library on the box around it or the box inside it. That is agreement, not drift.
+    if ((m.badge ? a : m).near?.badge) return false;
+    return `mockup renders this as a ${m.badge ? 'badge/pill' : 'plain element'}, app renders it as a ${a.badge ? 'badge/pill' : 'plain element'}`;
+  },
   icon: (m, a) => (m.icon === a.icon ? false
     : m.icon && !a.icon ? 'mockup carries an icon here; the app does not'
       : 'app carries an icon the mockup does not'),
@@ -318,16 +534,26 @@ const CLAUSES = {
   // TF-009
   stroke: (m, a) => {
     if (!m.stroke || !a.stroke) return null;
-    if (m.stroke.style !== a.stroke.style) {
-      return `border style differs — mockup ${m.stroke.style}, app ${a.stroke.style}`
-        + (m.stroke.style === 'dashed' ? ' (a dashed rule is how a mockup says "estimate / provisional"; losing it makes an estimate look measured)' : '');
+    let ms = m.stroke, as = a.stroke;
+    // TF-047: a side that draws no border of its own is read at the border one element away, and
+    // only when the sides disagree — two plain elements inside a ringed box still agree as before.
+    if (ms.style !== as.style || ms.visible !== as.visible) {
+      if (!ms.visible && m.near?.stroke) ms = m.near.stroke;
+      if (!as.visible && a.near?.stroke) as = a.near.stroke;
+    }
+    if (ms.style !== as.style) {
+      return `border style differs — mockup ${ms.style}, app ${as.style}`
+        + (ms.style === 'dashed' ? ' (a dashed rule is how a mockup says "estimate / provisional"; losing it makes an estimate look measured)' : '');
     }
-    if (m.stroke.visible !== a.stroke.visible) {
-      return `border presence differs — mockup ${m.stroke.visible ? 'has a visible rule' : 'has none'}, app ${a.stroke.visible ? 'has one' : 'has none'}`;
+    if (ms.visible !== as.visible) {
+      return `border presence differs — mockup ${ms.visible ? 'has a visible rule' : 'has none'}, app ${as.visible ? 'has one' : 'has none'}`;
     }
     return false;
   },
-  wrap: (m, a) => (m.wrap === null || a.wrap === null ? null
+  // TF-047: a row count says something only about the same text. Live data that reads differently
+  // from the mockup's sample wraps differently for that reason alone, so the clause is not applicable
+  // (null, never counted as graded) unless the digit-folded texts match.
+  wrap: (m, a) => (m.wrap === null || a.wrap === null || norm(m.full) !== norm(a.full) ? null
     : a.wrap > m.wrap ? `wraps to ${a.wrap} rows where the mockup keeps it on ${m.wrap}` : false),
   clip: (m, a) => (!m.clip || !a.clip ? null
     : (a.clip.x && !m.clip.x) ? 'content is cut off horizontally; the mockup is not clipped'
@@ -348,11 +574,49 @@ function diff(mock, app, screen, width) {
   const findings = [];
   const clauseCoverage = Object.fromEntries(Object.keys(CLAUSES).map((k) => [k, 0]));
   clauseCoverage.missing = 0;
-  let compared = 0, contentGraded = 0;
+  let compared = 0, contentGraded = 0, relocated = 0;
+  const iconsShort = {};   // parent key -> icons the app still owes under it (TF-027)
+  const badgesShort = {};  // parent key -> badges the app still owes under it (TF-045)
+  const usedApp = new Set();
+  const iconSeen = [];     // icon findings with the side that holds the icons (TF-046)
+
+  // --- TF-047: the same icon in another child. Pairing is by position, so a card header that a
+  // library wraps in one more <div> pairs the mockup's description with the app's toolbar, and the
+  // toolbar's icon reads as one "the mockup does not" carry — while the header holds exactly one
+  // icon on both sides. The rule the `missing` clause has followed since TF-027, one wrapper further:
+  // an icon finding is dropped when the parent or the grandparent is paired and carries the same
+  // number of icons on both sides. Bounded to a few icons, so a coincidence across a whole page
+  // (one lost, one added) stays reported.
+  const iconMoved = (key) => {
+    let k = key;
+    for (let up = 0; up < 2; up++) {
+      if (!k.includes(' > ')) return false;
+      k = k.slice(0, k.lastIndexOf(' > '));
+      const pm = mock.index[k], pa = app.index[k];
+      if (!pm || !pa) return false;
+      const n = pm.icons ?? 0;
+      if (n > 0 && n <= 4 && n === (pa.icons ?? 0)) return true;
+    }
+    return false;
+  };
 
   for (const key of Object.keys(mock.index)) {
     const m = mock.index[key];
-    const a = app.index[key];
+    let a = app.index[key];
+    let appKey = key;
+
+    // --- TF-045: a badge the app draws at another depth is the same badge. Found by its text under
+    // the same anchor, it is compared like any paired element, so a badge whose colour or ring really
+    // differs is still reported, and so is one the app turned into plain text.
+    if (!a && m.badge === true && m.text) {
+      const root = key.split(' > ')[0];
+      const cands = ((app.pool || {})[root] || []).filter((c) => !usedApp.has(c.key) && norm(c.text) === norm(m.text));
+      // a badge first, then the same kind of element, then one no mockup key already pairs with;
+      // among equals the shallowest, which is the order the probe found them in
+      const score = (c) => (c.badge === true ? 4 : 0) + (c.tag === m.tag ? 2 : 0) + (c.key in mock.index ? 0 : 1);
+      const pick = cands.reduce((best, c) => (!best || score(c) > score(best) ? c : best), null);
+      if (pick) { a = pick; appKey = pick.key; usedApp.add(pick.key); relocated++; }
+    }
 
     // --- the `missing` clause. Key-pairing alone cannot see an element that is
     // NOT THERE, and "a control the mockup draws as a badge rendered as plain text"
@@ -367,14 +631,37 @@ function diff(mock, app, screen, width) {
     if (!a) {
       const parentKey = key.includes(' > ') ? key.slice(0, key.lastIndexOf(' > ')) : null;
       const parentPaired = parentKey ? !!app.index[parentKey] : false;
-      if (parentPaired && (m.badge === true || m.icon === true)) {
+      // an icon is missing only when the paired parent carries fewer icons than the mockup's
+      // does. Pairing is by position, so an icon the app draws one wrapper deeper sits under
+      // another key and was reported missing on every sidebar group and tile (TF-027).
+      // and no more reports under one parent than it is icons short
+      if (m.icon === true && parentPaired && mock.index[parentKey] && !(parentKey in iconsShort)) {
+        iconsShort[parentKey] = Math.max(0, (mock.index[parentKey].icons ?? 0) - (app.index[parentKey].icons ?? 0));
+      }
+      const iconGone = m.icon === true && parentPaired && (iconsShort[parentKey] || 0) > 0;
+      if (iconGone && m.badge !== true) iconsShort[parentKey]--;
+      // A badge not found by its text (live data reads otherwise) is missing only while the paired
+      // parent draws fewer badges than the mockup's does, the rule icons follow since TF-027 (TF-045).
+      if (m.badge === true && parentPaired && mock.index[parentKey] && !(parentKey in badgesShort)) {
+        badgesShort[parentKey] = Math.max(0, (mock.index[parentKey].badges ?? 0) - (app.index[parentKey].badges ?? 0));
+      }
+      const badgeGone = m.badge === true && parentPaired && (badgesShort[parentKey] || 0) > 0;
+      if (badgeGone) badgesShort[parentKey]--;
+      if (parentPaired && (m.badge === true || iconGone)) {
         clauseCoverage.missing++;
         contentGraded++;
+      }
+      if (parentPaired && (m.badge === true ? badgeGone : iconGone)) {
+        // Say what was seen. "Flattened into plain text" is true only when the app shows the text;
+        // said of a badge the tool had merely failed to find, it sent a reader after a wrong cause.
+        const shown = m.text && norm(app.index[parentKey].full).includes(norm(m.text));
         findings.push({
           screen, width, class: 'missing', key,
-          detail: m.badge
-            ? `the mockup draws a badge/pill here ("${m.text}") and the app renders no such element — the value is flattened into plain text`
-            : `the mockup carries an icon here and the app renders no such element`,
+          detail: m.badge !== true
+            ? `the mockup carries an icon here and the app renders no such element`
+            : shown
+              ? `the mockup draws a badge/pill here ("${m.text}"); the app shows that text with no badge/pill around it — the value is flattened into plain text`
+              : `the mockup draws a badge/pill here ("${m.text}"); it could not be located in the app — no element under this parent carries that text, and the app draws ${app.index[parentKey].badges ?? 0} badge(s) there where the mockup draws ${mock.index[parentKey].badges ?? 0}`,
           mockup_text: m.text, app_text: null,
         });
       }
@@ -386,10 +673,28 @@ function diff(mock, app, screen, width) {
       if (r === null) continue;
       clauseCoverage[name]++;
       if (CONTENT_CLAUSES.has(name)) contentGraded++;
-      if (r) findings.push({ screen, width, class: name, key, detail: r, mockup_text: m.text, app_text: a.text });
+      if (r) {
+        if (name === 'icon' && iconMoved(key)) continue;   // the same icon, another child (TF-047)
+        const f = { screen, width, class: name, key, ...(appKey !== key ? { app_key: appKey } : {}), detail: r, mockup_text: m.text, app_text: a.text };
+        findings.push(f);
+        if (name === 'icon') iconSeen.push({ f, side: m.icon ? m : a });
+      }
     }
   }
-  return { findings, compared, contentGraded, clauseCoverage };
+
+  // --- TF-046: one icon, one finding. "Is there an icon inside?" is true of the element that carries
+  // the icon and of every element above it, so each container repeated the finding. A finding is
+  // dropped when every icon it holds is already reported on a deeper element, on the side that has
+  // the icons; a container holding an extra icon of its own is still reported.
+  const repeat = new Set();
+  for (const x of iconSeen) {
+    const ids = x.side.icon_ids || [];
+    const below = new Set(iconSeen
+      .filter((y) => y !== x && y.f.detail === x.f.detail && (y.side.depth ?? 0) > (x.side.depth ?? 0))
+      .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 };
 }
 
 // ---------------------------------------------------------------------- main
@@ -397,8 +702,30 @@ const results = [];
 let hardFail = false;
 
 const browser = await chromium.launch();
-const ctx = await browser.newContext({ ignoreHTTPSErrors: true });
-if (COOKIE) {
+const ctxOpts = { ignoreHTTPSErrors: true };
+if (STORAGE && existsSync(STORAGE)) ctxOpts.storageState = STORAGE;
+const ctx = await browser.newContext(ctxOpts);
+let cdpBrowser = null, cdpPage = null;
+if (CDP) {
+  try {
+    cdpBrowser = await chromium.connectOverCDP(CDP, { timeout: 15000 });
+    const c = cdpBrowser.contexts()[0];
+    cdpPage = c && c.pages()[0];
+  } catch (e) { console.error(`tf-mockup-parity: UNREACHABLE cdp ${CDP}: ${e.message.split('\n')[0]}`); }
+  if (!cdpPage) {
+    console.error(`tf-mockup-parity: UNREACHABLE cdp ${CDP}: no page in the attached app`);
+    await browser.close(); process.exit(2);
+  }
+}
+// the attached app's router, not a document load: a desktop head has no server to answer a goto
+async function reachCdp(page, route) {
+  try {
+    await page.evaluate((r) => { history.pushState({}, '', r); window.dispatchEvent(new PopStateEvent('popstate', { state: {} })); }, route);
+    await page.waitForTimeout(LOGIN_OPTS.settle);
+    return { status: 200, url: page.url() };
+  } catch (e) { return { status: 0, error: e.message.split('\n')[0] }; }
+}
+if (COOKIE && !CDP) {
   const u = new URL(BASE);
   for (const pair of COOKIE.split(';')) {
     const [name, ...v] = pair.trim().split('=');
@@ -411,6 +738,20 @@ if (HEADERS.length) {
   await ctx.setExtraHTTPHeaders(h);
 }
 
+// One app tab per width, signed in once and kept on the app, and one tab for the mockups. A sign-in
+// the page keeps for itself lives in that tab: a fresh tab per screen would be signed out every time
+// (AppManager TF-011). The mockup tab never touches the app, so the app tab never leaves it.
+const tabs = {};
+let loginResult = null;
+for (const width of WIDTHS) {
+  const size = { width, height: width < 700 ? 844 : 800 };
+  const app = CDP ? cdpPage : await ctx.newPage(); if (!CDP) await app.setViewportSize(size);
+  const mock = await ctx.newPage(); await mock.setViewportSize(size);
+  if (!CDP && LOGIN_PATH && USER) { const l = await signIn(app, LOGIN_OPTS); if (loginResult === null) loginResult = l; }
+  tabs[width] = { app, mock };
+}
+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`);
   // TF-008 §3: a screen with no mockup is reported, never silently passed — the
@@ -423,41 +764,59 @@ for (const s of SCREENS) {
 
   const perWidth = [];
   for (const width of WIDTHS) {
-    const page = await ctx.newPage();
-    await page.setViewportSize({ width, height: width < 700 ? 844 : 800 });
-    let mock, app, docFindings = [];
+    const { app: page, mock: mockPage } = tabs[width];
+    let mock, app, docFindings = [], reached = '', theme = null;
     try {
-      await page.goto(pathToFileURL(mockPath).href, { waitUntil: 'load' });
-      mock = await page.evaluate(PROBE);
-      const resp = await page.goto(BASE + s.route, { waitUntil: 'networkidle' });
-      if (resp && resp.status() >= 400) {
-        perWidth.push({ width, error: `app returned HTTP ${resp.status()}` });
-        await page.close();
+      await mockPage.goto(pathToFileURL(mockPath).href, { waitUntil: 'load' });
+      mock = await mockPage.evaluate(PROBE);
+      // The document may answer 401 and still draw the screen signed in (AppManager TF-006/TF-011):
+      // reach() judges by what the page draws, signs in again from inside the page when it must, and
+      // returns 200 only when the screen was really drawn signed in.
+      if (CDP) await page.setViewportSize({ width, height: width < 700 ? 844 : 800 }).catch(() => {});
+      const nav = CDP ? await reachCdp(page, s.route) : await reach(page, LOGIN_OPTS, s.route);
+      if (nav.status === 0 || nav.status >= 400 || nav.signedOut) {
+        perWidth.push({ width, error: nav.status === 0 ? `could not open ${s.route}: ${nav.error || 'no response'}`
+          : nav.signedOut ? `app returned HTTP ${nav.document_status ?? nav.status} and stayed signed out (sign-in ${LOGIN_PATH && USER ? 'did not hold' : 'not given: --login-path/--user/--password or --cookie'})`
+          : `app returned HTTP ${nav.status}` });
         continue;
       }
-      app = await page.evaluate(PROBE);
+      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))];
+      // 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
+      // and the app's own are put back afterwards, so an attached app is left as the viewer had it.
+      // 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;
+      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(() => {}); }
 
       // 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
       // 900px viewport, ~1700px of it blank, with the app shell repainted at the
       // bottom because the page had escaped the shell's scroll container. No gate
       // looked at document height, so that passed too.
-      if (app.doc.scrollHeight > app.doc.clientHeight + 2) {
+      // Only when the shell has a content scroll container: an app whose document is its only
+      // scroller (a long report page) has escaped nothing (AppManager TF-014).
+      if (app.doc.scroller && app.doc.scrollHeight > app.doc.clientHeight + 2) {
         docFindings.push({
           screen: s.name, width, class: 'document-scroll', key: 'document',
-          detail: `document.scrollHeight ${app.doc.scrollHeight} exceeds clientHeight ${app.doc.clientHeight} — the page has escaped the app shell's scroll container`,
+          detail: `document.scrollHeight ${app.doc.scrollHeight} exceeds clientHeight ${app.doc.clientHeight} — the page has escaped the app shell's scroll container (${app.doc.scroller})`,
         });
       }
     } catch (e) {
       perWidth.push({ width, error: String(e).slice(0, 200) });
-      await page.close();
       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 });
-    await page.close();
+      appTestIds: app.testids, mockTestIds: mock.testids, ...(reached ? { reached } : {}), ...(theme ? { theme } : {}) });
   }
 
   const ok = perWidth.filter((w) => !w.error);
@@ -501,6 +860,8 @@ for (const s of SCREENS) {
     screen: s.name, route: s.route, verdict,
     coverage: {
       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),
       app_controls: appAnchors, mockup_anchors: mockAnchors,
       ratio: appAnchors ? +(compared / appAnchors).toFixed(2) : null,
       thin: appAnchors > 0 && compared / appAnchors < THIN_RATIO,
@@ -517,15 +878,18 @@ for (const s of SCREENS) {
       add_data_testid_to_mockup: unanchored.slice(0, 30),
     },
     widths: perWidth.map((w) => ({ width: w.width, error: w.error || null,
-      compared: w.compared || 0, content_graded: w.contentGraded || 0, findings: (w.findings || []).length })),
+      compared: w.compared || 0, content_graded: w.contentGraded || 0, findings: (w.findings || []).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)
   });
 }
 
 await browser.close();
+if (cdpBrowser) await cdpBrowser.close().catch(() => {});   // disconnects; the app keeps running
 
 const summary = {
   status: 'measured',
-  base: BASE,
+  base: BASE || CDP, mode: CDP ? 'cdp' : 'base',
   widths: WIDTHS,
   screens_n: results.length,
   pass: results.filter((r) => r.verdict === 'PASS').length,