@broberg/lens-daemon 0.0.0-stage → 0.1.0

package/src/manifest.ts

@@ -0,0 +1,741 @@
+// F074.6 — lens.manifest.json loader + capture-catalogue + data-testid inventory.
+//
+// A project commits a `lens.manifest.json` at its root describing the surfaces
+// Lens should photograph + verify: name, path, capture mode, the [data-testid]
+// selector, an optional assert, and a baseline_key. `lens_capture_catalogue`
+// (F074.5) runs the whole catalogue in one call — "photograph + verify the
+// whole surface" as a one-liner.
+//
+// inventoryTestIds() is the auto-discovery half: scan a repo's source for
+// data-testid attributes so a project can see what anchors exist (and the
+// cardmem audit / F073 gate can flag interactive elements that lack one).
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, extname, isAbsolute } from 'node:path';
+import { resolveSandboxedPath } from './sandbox.ts';
+import type { CaptureMode } from './capture.ts';
+import type { AuthConfig } from './auth/index.ts';
+import type { CatalogueInput, CatalogueSurface } from './service.ts';
+import { parseFlow, type Flow } from './flow.ts';
+
+export const MANIFEST_FILENAME = 'lens.manifest.json';
+
+export interface LensManifestSurface {
+  name: string;
+  path: string;
+  mode?: CaptureMode;
+  /** Preferred: a [data-testid="…"] selector for element mode. */
+  selector?: string;
+  /** F098.6 — navigation settle strategy. Default 'domcontentloaded' (won't hang
+   *  on live-data/streaming/canvas SPAs where 'load' never fires). Override with
+   *  'load' for a static page that genuinely needs full sub-resource load. */
+  waitUntil?: 'load' | 'domcontentloaded' | 'commit';
+  waitFor?: string | number;
+  assert?: string;
+  baseline_key?: string;
+  /** F089.2 — smoke-only: verify on render + anchor + assert, NEVER pixel-diff
+   *  (even if a baseline exists). The right mode for live-data dashboards whose
+   *  changing counts/timestamps make a pixel baseline drift to a false red. */
+  no_diff?: boolean;
+  /** F092.9 — capture this surface at a non-default viewport (e.g. 390x844 for
+   *  a mobile baseline). Omit for the 1280x800 desktop default. */
+  viewport?: { width: number; height: number };
+  /** Per-surface auth override: omit to inherit the manifest-level auth,
+   *  `null` to force NO auth (public pages that redirect logged-in visitors). */
+  auth?: AuthConfig | null;
+}
+
+export interface LensManifest {
+  /** Project slug — scopes runs/baselines. */
+  project: string;
+  /** Base URL for relative surface paths, e.g. "http://localhost:3019".
+   *  Overridable at call time (a deployed preview URL). */
+  base_url: string;
+  /** Optional auth pre-step applied to every surface (secret from daemon env). */
+  auth?: AuthConfig;
+  diff_threshold?: number;
+  /** F074.57 — BCP-47 locale for every capture/flow in this project, e.g.
+   *  "da-DK". A call-time value wins. Absent means absent: nothing is passed to
+   *  Playwright, so every existing baseline in the fleet stays valid. */
+  locale?: string;
+  /** F074.57 — IANA timezone, e.g. "Europe/Copenhagen". Absent means the context
+   *  inherits the HOST machine's zone, which is why the same page renders
+   *  different dates on the Mac and on Cloud Lens. Declare it to make a project's
+   *  captures machine-independent. */
+  timezone?: string;
+  surfaces: LensManifestSurface[];
+  /** F082 — E2E manuscript flows. Optional; the flow-gate runs each one and
+   *  anchor-checks every [data-testid] the steps reference against the repo. */
+  flows?: Flow[];
+}
+
+function validate(m: unknown): LensManifest {
+  if (!m || typeof m !== 'object') throw new Error('manifest is not an object');
+  const obj = m as Record<string, unknown>;
+  if (typeof obj.project !== 'string' || !obj.project.trim()) {
+    throw new Error('manifest.project (slug) is required');
+  }
+  if (typeof obj.base_url !== 'string' || !obj.base_url.trim()) {
+    throw new Error('manifest.base_url is required');
+  }
+  if (!Array.isArray(obj.surfaces) || obj.surfaces.length === 0) {
+    throw new Error('manifest.surfaces[] is required and non-empty');
+  }
+  for (const [i, s] of (obj.surfaces as unknown[]).entries()) {
+    const sf = s as Record<string, unknown>;
+    if (typeof sf.name !== 'string' || typeof sf.path !== 'string') {
+      throw new Error(`manifest.surfaces[${i}] needs string name + path`);
+    }
+    if (sf.mode === 'element' && typeof sf.selector !== 'string') {
+      throw new Error(`manifest.surfaces[${i}] (${String(sf.name)}) mode=element requires a selector`);
+    }
+  }
+  if (obj.flows !== undefined) {
+    if (!Array.isArray(obj.flows)) throw new Error('manifest.flows must be an array');
+    // parseFlow throws on the first structural problem in any flow.
+    (obj.flows as unknown[]).forEach((f, i) => {
+      try {
+        parseFlow(f);
+      } catch (err) {
+        throw new Error(`manifest.flows[${i}]: ${err instanceof Error ? err.message : err}`);
+      }
+    });
+  }
+  return m as LensManifest;
+}
+
+/** Read + validate a project's lens.manifest.json. */
+export function loadManifest(localPathInput: string, sandboxRoots: string[]): LensManifest {
+  const root = resolveSandboxedPath(localPathInput, sandboxRoots);
+  const file = join(root, MANIFEST_FILENAME);
+  let raw: string;
+  try {
+    raw = readFileSync(file, 'utf-8');
+  } catch {
+    throw new Error(`no ${MANIFEST_FILENAME} at ${root}`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`${MANIFEST_FILENAME} is not valid JSON: ${err instanceof Error ? err.message : err}`);
+  }
+  const manifest = validate(parsed);
+  const fixAuth = (a: AuthConfig | null | undefined) => resolveAuthPaths(a, root);
+  if (manifest.auth) manifest.auth = fixAuth(manifest.auth) as AuthConfig | undefined;
+  for (const s of manifest.surfaces) {
+    if (s.auth !== undefined) s.auth = fixAuth(s.auth);
+  }
+  // F082 — resolve the same portable-relative auth path on each flow.
+  if (manifest.flows) {
+    for (const f of manifest.flows) {
+      if (f.auth !== undefined) f.auth = fixAuth(f.auth) as AuthConfig | undefined;
+    }
+  }
+  return manifest;
+}
+
+// F074.12/.13 + F082.6 — resolve a relative storageState `statePath` (or
+// mintEndpoint `secretPath`) against the repo root so a COMMITTED manifest /
+// flow can point portably at a gitignored credential file (".lens/state.json")
+// without an absolute machine path or an env var. Shared by the manifest loader
+// AND standalone flow/manuscript runs (so auth reaches those paths too).
+export function resolveAuthPaths(
+  a: AuthConfig | null | undefined,
+  root: string,
+): AuthConfig | null | undefined {
+  if (a && a.adapter === 'storageState' && a.statePath && !isAbsolute(a.statePath)) {
+    return { ...a, statePath: join(root, a.statePath) };
+  }
+  if (a && a.adapter === 'mintEndpoint' && a.secretPath && !isAbsolute(a.secretPath)) {
+    return { ...a, secretPath: join(root, a.secretPath) };
+  }
+  return a;
+}
+
+/** Where a run's credential came from. `none` ALWAYS carries a note saying why. */
+export type AuthSource = 'explicit' | 'manifest' | 'none';
+
+export interface AuthProvenance {
+  auth: AuthConfig | undefined;
+  source: AuthSource;
+  /** The adapter that will be applied, for the report. Null when source='none'. */
+  adapter: string | null;
+  /** Why there is no credential. Always present when source==='none'. */
+  note?: string;
+}
+
+/**
+ * F074.36 — the effective auth for a standalone flow/manuscript run, AND the
+ * reason when there is none.
+ *
+ * The old version returned `undefined` for five different situations — no
+ * local_path, an unsandboxed path, no manifest, an invalid manifest, a manifest
+ * with no `auth` — and its comment called that "best-effort". It is not
+ * best-effort, it is silent: the run then drives an unauthenticated browser,
+ * lands on the login wall, and reports a confident verdict about a page nobody
+ * asked for (reproduced on cardmem prod, flow run 0938570e — `goto /board`
+ * returned PASS on the sign-in screen). A comment promising the failure is
+ * benign is worse than no comment; it manufactures confidence in the next
+ * reader. Same defect the F074.32 scan exists to find: take the data, drop the
+ * error.
+ *
+ * So every branch now names itself. The caller decides what to do with a `none`;
+ * what it can no longer do is not know.
+ */
+export function authProvenance(
+  flowAuth: AuthConfig | undefined,
+  localPath: string | undefined,
+  sandboxRoots: string[],
+): AuthProvenance {
+  const ok = (auth: AuthConfig, source: AuthSource): AuthProvenance => ({
+    auth,
+    source,
+    adapter: auth.adapter ?? null,
+  });
+  if (!localPath) {
+    return flowAuth
+      ? ok(flowAuth, 'explicit')
+      : { auth: undefined, source: 'none', adapter: null, note: 'no auth given and no local_path to inherit a manifest from' };
+  }
+  let root: string;
+  try {
+    root = resolveSandboxedPath(localPath, sandboxRoots);
+  } catch (err) {
+    // An unsandboxed local_path used to silently disable auth. It is a caller
+    // error and must read as one.
+    return flowAuth
+      ? ok(flowAuth, 'explicit')
+      : {
+          auth: undefined,
+          source: 'none',
+          adapter: null,
+          note: `local_path is outside the daemon sandbox: ${err instanceof Error ? err.message : String(err)}`,
+        };
+  }
+  // An explicit auth wins and never consults the manifest — the caller said
+  // exactly what to use.
+  if (flowAuth) return ok(resolveAuthPaths(flowAuth, root) as AuthConfig, 'explicit');
+  try {
+    const inherited = loadManifest(localPath, sandboxRoots).auth;
+    return inherited
+      ? ok(inherited, 'manifest')
+      : {
+          auth: undefined,
+          source: 'none',
+          adapter: null,
+          note: `lens.manifest.json at ${root} has no global "auth" — an authed route will land on the login page`,
+        };
+  } catch (err) {
+    return {
+      auth: undefined,
+      source: 'none',
+      adapter: null,
+      note: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/** F074.57 — where the locale/timezone for a run came from. Reported, not
+ *  inferred: same reasoning as auth's provenance — a caller that gets English
+ *  when it declared Danish must be able to see WHICH layer answered. */
+export interface LocaleResolution {
+  locale?: string;
+  timezone?: string;
+  /** Per field, because the two resolve independently: a project may declare a
+   *  timezone in the manifest and override only the locale at call time. */
+  localeSource: 'call' | 'manifest' | 'none';
+  timezoneSource: 'call' | 'manifest' | 'none';
+}
+
+/**
+ * Precedence: call time > manifest > unset. Resolved PER FIELD.
+ *
+ * The unset case is the one with teeth. It must yield `undefined`, never a
+ * default — `locale: undefined` is still a key on an object literal, and the
+ * whole promise of this feature to everyone who did not ask for it is that
+ * Playwright receives nothing and their baselines cannot move.
+ */
+export function resolveLocale(
+  call: { locale?: string; timezone?: string } | undefined,
+  manifest: { locale?: string; timezone?: string } | null | undefined,
+): LocaleResolution {
+  const pick = (c: string | undefined, m: string | undefined) =>
+    c ? ({ value: c, source: 'call' as const })
+      : m ? ({ value: m, source: 'manifest' as const })
+      : ({ value: undefined, source: 'none' as const });
+  const l = pick(call?.locale, manifest?.locale);
+  const t = pick(call?.timezone, manifest?.timezone);
+  return {
+    ...(l.value ? { locale: l.value } : {}),
+    ...(t.value ? { timezone: t.value } : {}),
+    localeSource: l.source,
+    timezoneSource: t.source,
+  };
+}
+
+/** F074.57 — the manifest half of {@link resolveLocale}, read the same way auth
+ *  is: best-effort, and a missing/unreadable manifest is simply "no project
+ *  value" rather than an error. A locale is a preference, not a credential. */
+export function manifestLocale(
+  localPath: string | undefined,
+  sandboxRoots: string[],
+): { locale?: string; timezone?: string } | null {
+  if (!localPath) return null;
+  try {
+    const m = loadManifest(localPath, sandboxRoots);
+    return { ...(m.locale ? { locale: m.locale } : {}), ...(m.timezone ? { timezone: m.timezone } : {}) };
+  } catch {
+    return null;
+  }
+}
+
+/** F082.6 — the credential only. Kept for callers that don't report provenance
+ *  (the /lens/gate path); everything user-facing should use authProvenance. */
+export function effectiveFlowAuth(
+  flowAuth: AuthConfig | undefined,
+  localPath: string | undefined,
+  sandboxRoots: string[],
+): AuthConfig | undefined {
+  return authProvenance(flowAuth, localPath, sandboxRoots).auth;
+}
+
+/** F082 — flows from a manifest, with base_url overridable (deployed preview
+ *  instead of the manifest's localhost). */
+export function manifestFlows(manifest: LensManifest, baseUrlOverride?: string): Flow[] {
+  return (manifest.flows ?? []).map((f) => ({
+    ...f,
+    base_url: baseUrlOverride ?? f.base_url ?? manifest.base_url,
+  }));
+}
+
+/** Map a manifest into a CatalogueInput for lensCaptureCatalogue. base_url can
+ *  be overridden (e.g. a deployed preview instead of localhost). */
+export function manifestToCatalogue(manifest: LensManifest, baseUrlOverride?: string): CatalogueInput {
+  const surfaces: CatalogueSurface[] = manifest.surfaces.map((s) => ({
+    name: s.name,
+    path: s.path,
+    mode: s.mode,
+    selector: s.selector,
+    waitUntil: s.waitUntil,
+    waitFor: s.waitFor,
+    assert: s.assert,
+    baseline_key: s.baseline_key,
+    no_diff: s.no_diff,
+    viewport: s.viewport,
+    ...(s.auth !== undefined ? { auth: s.auth } : {}),
+  }));
+  return {
+    project: manifest.project,
+    base_url: baseUrlOverride ?? manifest.base_url,
+    auth: manifest.auth,
+    diff_threshold: manifest.diff_threshold,
+    surfaces,
+  };
+}
+
+export interface TestIdHit {
+  testid: string;
+  count: number;
+  files: string[];
+}
+
+const SOURCE_EXTS = new Set(['.tsx', '.jsx', '.ts', '.js', '.vue', '.svelte', '.html', '.astro']);
+// `worktrees` holds throwaway copies of the WHOLE repo (the Agent tool's
+// isolation:"worktree" mode leaves them under .claude/worktrees). They are real
+// source files, so the walk happily read them — and 63% of the gaps this gate
+// reported for cardmem came from two abandoned ones, at whatever commit they
+// were cut from. Measured 2026-08-06: 548 reported, 346 from worktrees, 202
+// real. A gate whose number is mostly noise teaches people to ignore it, and it
+// nearly sent me to add testids to code that ships nowhere.
+//
+// Same family as the other false-greens today, inverted: a guard reading a real
+// source that is not the one the system runs. There it hid a failure; here it
+// manufactures phantom ones. Both make the number untrustworthy.
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.turbo', 'coverage', '.cache', 'worktrees']);
+const TESTID_RE = /data-testid\s*=\s*["'`]([^"'`]+)["'`]/g;
+
+function walkSource(dir: string, hits: Map<string, TestIdHit>, rootLen: number, budget: { left: number }): void {
+  if (budget.left <= 0) return;
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (budget.left <= 0) return;
+    if (SKIP_DIRS.has(name)) continue;
+    const full = join(dir, name);
+    let st;
+    try {
+      st = statSync(full);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) {
+      walkSource(full, hits, rootLen, budget);
+    } else if (SOURCE_EXTS.has(extname(name))) {
+      budget.left -= 1;
+      let content: string;
+      try {
+        content = readFileSync(full, 'utf-8');
+      } catch {
+        continue;
+      }
+      const rel = full.slice(rootLen + 1);
+      for (const m of content.matchAll(TESTID_RE)) {
+        const id = m[1]!;
+        const hit = hits.get(id) ?? { testid: id, count: 0, files: [] };
+        hit.count += 1;
+        if (!hit.files.includes(rel)) hit.files.push(rel);
+        hits.set(id, hit);
+      }
+    }
+  }
+}
+
+/** Scan a repo's source for data-testid attributes. Auto-discovery for the
+ *  manifest + the strict-gate audit. Bounded file budget so a huge monorepo
+ *  scan can't run away. */
+export function inventoryTestIds(
+  localPathInput: string,
+  sandboxRoots: string[],
+  maxFiles = 5000,
+): { total: number; unique: number; testids: TestIdHit[] } {
+  const root = resolveSandboxedPath(localPathInput, sandboxRoots);
+  const hits = new Map<string, TestIdHit>();
+  walkSource(root, hits, root.length, { left: maxFiles });
+  const testids = [...hits.values()].sort((a, b) => a.testid.localeCompare(b.testid));
+  return {
+    total: testids.reduce((n, h) => n + h.count, 0),
+    unique: testids.length,
+    testids,
+  };
+}
+
+// F082.6 / upmetrics #4 — find INTERACTIVE elements that LACK a data-testid, so
+// step-2 instrumentation ("add anchors before writing a flow") is actionable.
+// Heuristic, like inventoryTestIds: an opening tag for a native control
+// (button/input/select/textarea) or any tag carrying an onClick is a gap if the
+// tag's own attributes don't include data-testid. Per-file, per-line.
+export interface TestIdGap {
+  file: string;
+  line: number;
+  element: string;
+  snippet: string;
+}
+
+const TAG_START_RE = /<([A-Za-z][\w.]*)\b/g;
+const NATIVE_INTERACTIVE = new Set(['button', 'input', 'select', 'textarea', 'a']);
+// F074.58 — ONE definition of "an interactive handler", used by BOTH the gap
+// matcher and the blind-spot probe below, so the probe that reports what we could
+// not see can never fall behind the matcher it reports for. The `[=:]` form is
+// deliberate: `onClick={fn}` is JSX and `onClick: fn` is the SAME handler in
+// hyperscript (`h('button', { onClick: fn })`), createElement, or a Vue props
+// object — the syntaxes this probe exists to notice.
+const HANDLER_NAMES = 'Click|Change|Input|Submit';
+const HANDLER_ATTR_RE = new RegExp(`\\bon(?:${HANDLER_NAMES})\\s*=`);
+const HANDLER_ANY_RE = new RegExp(`\\bon(?:${HANDLER_NAMES})\\s*[=:]`, 'g');
+
+// F074.22b — the real end of a JSX opening tag is the first '>' that is NOT
+// inside a {…} expression or a string/template literal. The old /<tag[^>]*>/
+// stopped at the '>' in an arrow handler (`onChange={e => …}`), truncating the
+// attribute scan BEFORE a data-testid that followed the handler — so every
+// interactive element with an arrow handler before its testid was a
+// false-positive gap (fleet-wide; it broke the F086 self-check). Brace + quote
+// aware finds the true tag end. Returns the index of the closing '>' or -1.
+function openingTagEnd(content: string, from: number): number {
+  let depth = 0;
+  for (let i = from; i < content.length; i++) {
+    const ch = content[i];
+    if (ch === '{') depth++;
+    else if (ch === '}') {
+      if (depth > 0) depth--;
+    } else if (ch === '"' || ch === "'" || ch === '`') {
+      const quote = ch;
+      i++;
+      while (i < content.length && content[i] !== quote) {
+        if (content[i] === '\\') i++;
+        i++;
+      }
+    } else if (ch === '>' && depth === 0) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+// upmetrics (F074.11 closeout) — a comment line that MENTIONS a native control
+// ("// Custom date picker — never a native <input type='date'>") must not count
+// as a gap. Blank /* */ blocks + start-of-line // comments to spaces (keeping
+// newlines, so reported line numbers stay correct) before matching.
+function stripComments(src: string): string {
+  return src
+    .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '))
+    .replace(/^[ \t]*\/\/.*$/gm, (m) => m.replace(/[^\n]/g, ' '));
+}
+
+// F074.58 (second cut) — "does this file contain markup?" cannot be answered by
+// "does it contain a '<' followed by a letter". trail measured the escape on their
+// REAL popup (#21962) after the first cut shipped:
+//
+//   line   3:  // F086 + house rule: no native <select>.   ← a COMMENT
+//   line 161:  useState<Config | null>(null)               ← TS GENERICS
+//
+// Either one alone was enough to call the file examined, so its nine hyperscript
+// handlers stayed invisible. Generics appear in nearly every TypeScript file, which
+// makes the first probe close to a no-op: measured on cardmem, 310 files it called
+// examined contain no markup at all. The old probe answered "this file contains a
+// pair of angle brackets", not "this file contains markup".
+//
+// A generic's '<' always follows an identifier, ')' or ']' (`useState<`, `Array<`,
+// `foo()<`). A JSX element's '<' never does — it follows whitespace, '(', '{', ','
+// or '>'. That one character is the whole discriminator, and it is syntax-agnostic:
+// hyperscript, createElement and Vue render functions all score 0 without needing a
+// parser for any of them. Measured on the real file: 7 generic-shaped, 0 element-shaped.
+export function elementLikeCount(rawContent: string): number {
+  const content = stripComments(rawContent);
+  let n = 0;
+  for (const m of content.matchAll(TAG_START_RE)) {
+    const i = m.index ?? 0;
+    if (i > 0 && /[A-Za-z0-9_$)\]]/.test(content[i - 1]!)) continue;
+    n++;
+  }
+  return n;
+}
+
+// F074.58 — the evidence that separates "element-less and inert" (cardmem's
+// idle-cue-watcher, a genuinely markup-free effect component) from "interactive and
+// UNSEEN" (trail's popup: nine handlers the matcher never met). Without it the third
+// state is unreadable: on cardmem it names 491 files, nearly all of them .ts modules
+// that were never expected to hold markup.
+//
+// The handler names are the matcher's OWN — deliberately narrow, and measured rather
+// than chosen: a wider `on[A-Z]\w+` scored 140 "signals" on packages/db/src/schema.ts,
+// which are Drizzle's onDelete/onUpdate, and `data-testid` as evidence added nine Lens
+// tooling files that merely mention the string inside their own regexes. Narrow scores
+// 0 on all of cardmem and exactly 1 on trail's web-clipper — the reported file.
+export function interactiveHandlerCount(rawContent: string): number {
+  return stripComments(rawContent).match(HANDLER_ANY_RE)?.length ?? 0;
+}
+
+export function gapsInFile(rawContent: string, rel: string, out: TestIdGap[]): void {
+  const content = stripComments(rawContent);
+  for (const m of content.matchAll(TAG_START_RE)) {
+    const tag = m[1]!;
+    const start = m.index ?? 0;
+    // Attributes span from just after the tag name to the tag's TRUE '>' (skipping
+    // '>' inside {…}/strings — an arrow handler's '>' must not truncate this).
+    const end = openingTagEnd(content, start + m[0].length);
+    if (end < 0) continue;
+    const attrs = content.slice(start + m[0].length, end);
+    const isNative = NATIVE_INTERACTIVE.has(tag.toLowerCase());
+    const hasOnClick = HANDLER_ATTR_RE.test(attrs);
+    // PascalCase / dotted tags (`<Select>`, `<FieldEditor>`, `<SelectPrimitive.Root>`)
+    // are React COMPONENTS, not DOM elements. Their on*-handlers are PROPS passed
+    // down — the real Lens anchor is the DOM the component renders (e.g. Select →
+    // SelectTrigger), which is tagged in that component's own file. Radix
+    // SelectPrimitive.Root renders no DOM and rejects data-testid, so flagging the
+    // component itself produced an UNCLOSEABLE gap (no file with a <Select> could
+    // ever reach 0). Only native DOM controls + lowercase tags with a handler count.
+    // (Surfaced independently by the sa + fysiodk Lens sweeps, 2026-06-02.)
+    const isComponent = /^[A-Z]/.test(tag) || tag.includes('.');
+    if (isComponent) continue;
+    // `<a>` only counts when it's clickable (href or onClick).
+    if (tag.toLowerCase() === 'a' && !hasOnClick && !/\bhref\s*=/.test(attrs)) continue;
+    if (!isNative && !hasOnClick) continue;
+    if (/\bdata-testid\s*=/.test(attrs)) continue;
+    const line = content.slice(0, start).split('\n').length;
+    out.push({
+      file: rel,
+      line,
+      element: tag,
+      snippet: content.slice(start, end + 1).replace(/\s+/g, ' ').slice(0, 100),
+    });
+  }
+}
+
+export function inventoryInteractiveGaps(
+  localPathInput: string,
+  sandboxRoots: string[],
+  maxFiles = 5000,
+): {
+  total_gaps: number;
+  files_with_gaps: number;
+  gaps: TestIdGap[];
+  not_examined: string[];
+  unseen_interactive: string[];
+} {
+  const root = resolveSandboxedPath(localPathInput, sandboxRoots);
+  const gaps: TestIdGap[] = [];
+  // F074.58 — a file we could not READ and a file we found no elements in are
+  // both reported here, and neither is a gap. Reported by trail (#21959) with
+  // the mutation that proves it: their hyperscript popup (`h('button', …)`,
+  // Preact without JSX) answered 0 gaps, and still answered 0 with a
+  // data-testid REMOVED. TAG_START_RE matches JSX tag-starts, so the file was
+  // never examined — and "never examined" was indistinguishable from "clean".
+  //
+  // This repo already wrote the rule during the NUL-byte sweep: scan everything,
+  // classify afterwards, and let the check prove its own coverage. A structured
+  // "no problems" about a file nobody could read is the false green this closes.
+  const notExamined: string[] = [];
+  // The ACTIONABLE subset of not_examined: no elements visible, yet the file carries
+  // handlers. "I could not read this, and there is something here to read."
+  const unseenInteractive: string[] = [];
+  const budget = { left: maxFiles };
+  const walk = (dir: string): void => {
+    if (budget.left <= 0) return;
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      if (budget.left <= 0) return;
+      if (SKIP_DIRS.has(name)) continue;
+      const full = join(dir, name);
+      let st;
+      try {
+        st = statSync(full);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) {
+        walk(full);
+      } else if (SOURCE_EXTS.has(extname(name))) {
+        budget.left -= 1;
+        const rel = full.slice(root.length + 1);
+        try {
+          const text = readFileSync(full, 'utf-8');
+          // Count elements BEFORE judging gaps: zero elements in a source file is
+          // not a clean file, it is a file this matcher cannot see. It is NOT a
+          // gap either — cardmem's own idle-cue-watcher.tsx is genuinely
+          // element-less — so it is reported separately and a reader decides.
+          // elementLikeCount is its own pass with its own non-global matching, so
+          // the shared global TAG_START_RE's lastIndex is never advanced by the
+          // coverage probe. The first cut called .test() on the global one, and
+          // matchAll() inherits that index — gapsInFile then started mid-file and
+          // missed the first element. My own negative control caught it: a file
+          // with a real gap reported 0. The same class this card is about,
+          // introduced by the fix for it.
+          if (elementLikeCount(text) === 0) {
+            notExamined.push(rel);
+            if (interactiveHandlerCount(text) > 0) unseenInteractive.push(rel);
+          }
+          gapsInFile(text, rel, gaps);
+        } catch {
+          // Unreadable is the same class: say so instead of skipping silently.
+          notExamined.push(rel);
+        }
+      }
+    }
+  };
+  walk(root);
+  const files = new Set(gaps.map((g) => g.file));
+  return {
+    total_gaps: gaps.length,
+    files_with_gaps: files.size,
+    gaps,
+    not_examined: notExamined,
+    unseen_interactive: unseenInteractive,
+  };
+}
+
+// F123.4 — design-consistency structural check (the cheap, deterministic 80%
+// catcher; the F086-twin for layout). A "route surface" hand-rolls its own
+// header/frame chrome instead of rendering the project's shared layout
+// component — exactly the drift Christian has seen 300+ times. No browser: pure
+// static analysis. The Lens shell-diff (F123.5) catches what static can't.
+//
+// Heuristic (tuned to keep false-positives near zero): a file is a ROUTE
+// SURFACE if it renders the shared page shell (a `page-shell` class) AND carries
+// a `<x>-root` data-testid (the route-root convention). It DRIFTS if it does not
+// render the shared layout component (default `<PageHeader`). Drift is suppressed
+// by a per-file opt-out marker so a deliberate brand-variation page is declared
+// once and the check (and any auto-remediation loop) leaves it alone.
+//
+//   Opt-out marker (anywhere in the file):  design: intentional-divergence
+export interface ChromeDriftHit {
+  file: string;
+  root_testid: string;
+  reason: string;
+}
+
+// The route-surface markers + the opt-out are configurable so other repos can
+// point at their own shell class / layout component / convention.
+export interface ChromeDriftOpts {
+  /** Shared layout/header component every route must render. Default 'PageHeader'. */
+  layoutComponent?: string;
+  /** Class marking the shared page frame. Default 'page-shell'. */
+  shellMarker?: string;
+}
+const DIVERGENCE_RE = /design:\s*intentional-divergence/;
+const ROOT_TESTID_RE = /data-testid\s*=\s*["'`]([A-Za-z0-9_-]+-root)["'`]/;
+
+export function inventoryChromeDrift(
+  localPathInput: string,
+  sandboxRoots: string[],
+  opts: ChromeDriftOpts = {},
+  maxFiles = 5000,
+): {
+  layout_component: string;
+  surfaces: number;
+  drift_count: number;
+  drift: ChromeDriftHit[];
+} {
+  const layout = opts.layoutComponent ?? 'PageHeader';
+  const shellMarker = opts.shellMarker ?? 'page-shell';
+  const layoutRe = new RegExp(`<${layout}\\b|\\b${layout}\\s*(?:,|\\}|from)`); // JSX use OR import
+  const root = resolveSandboxedPath(localPathInput, sandboxRoots);
+  const drift: ChromeDriftHit[] = [];
+  let surfaces = 0;
+  const budget = { left: maxFiles };
+  const walk = (dir: string): void => {
+    if (budget.left <= 0) return;
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      if (budget.left <= 0) return;
+      if (SKIP_DIRS.has(name)) continue;
+      const full = join(dir, name);
+      let st;
+      try {
+        st = statSync(full);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (extname(name) !== '.tsx' && extname(name) !== '.jsx') continue;
+      budget.left -= 1;
+      let content: string;
+      try {
+        content = readFileSync(full, 'utf-8');
+      } catch {
+        continue;
+      }
+      // Is this a top-level route surface? (renders the shared shell + a *-root)
+      if (!content.includes(shellMarker)) continue;
+      const m = content.match(ROOT_TESTID_RE);
+      if (!m) continue;
+      surfaces += 1;
+      if (DIVERGENCE_RE.test(content)) continue; // deliberate divergence — leave it alone
+      if (layoutRe.test(content)) continue; // renders the shared layout — OK
+      drift.push({
+        file: full.slice(root.length + 1),
+        root_testid: m[1]!,
+        reason: `route surface renders the shared shell ("${shellMarker}") but hand-rolls its header — it does not use <${layout}>. Mirror a sibling route's <${layout}> (or declare "design: intentional-divergence" if this page is deliberately different).`,
+      });
+    }
+  };
+  walk(root);
+  return { layout_component: layout, surfaces, drift_count: drift.length, drift };
+}