Summary

Adds scripts/audit-css-class-drift.mjs — a one-shot triage helper that surfaces fork-side class="..." tokens in ui/src/**/*.{ts,tsx} that have no matching rule anywhere in the ui/src/styles.css import graph.

Addresses #2502. The #2501 fix (nav-section + topbar vocabulary after v2026.3.13-1 sync) was the first visible symptom; this audit generalizes the detection so future drift surfaces in one pass instead of reactively, component by component, as users notice broken styling.

What this PR does

• Script-only change. No CSS, no TS, no runtime wiring. Per audit(ui): one-shot CSS class drift audit — surface fork-side references with no CSS definition #2502 this is the pure audit+report step; the build-time gate that depends on it is tracked in feat(ci): CSS class consistency build-time gate — fail build on undefined class references #2503.
• Script is CI-friendly: no stdin interaction, exit 0 when clean, exit 1 on findings, exit 2 on fatal error.
• Output written to .tmp/audit-css-drift.md (already gitignored via .tmp/).

Current state on this branch

Running the script against origin/main:

• 36 orphans across 3 drift clusters:
  1. 0667aa5596 (v2026.3.22 sync) — 21 orphans — full .config-sidebar* / .config-search__tag-* / .config-nav* / .config-subnav* family gone; upstream moved to .config-top-tabs
  2. 04a7853f0f (v2026.3.13-1 sync) — 5 orphans — residue after fix(ui): restore nav-section/topbar class names after v2026.3.13-1 sync — paired call-site update missed #2501: .nav (→ .sidebar), .nav--collapsed (→ .sidebar--collapsed), .theme-toggle* (→ .theme-orb*)
  3. 21ac4b9a8a (style(ui) clarity pass) — 1 orphan — .btn-sm (→ .btn--sm)
• 9 unresolved — no removing-commit found in CSS history. Mix of genuinely-never-defined BEM sub-elements (.cron-run-entry__main, .cron-run-entry__title, .nav-item--external, .nav-section--links), fork-side classes with no rule (.nostr-profile-form, .form-field, .monospace, .debug-event-log), and one dynamic-construction scope-out (.language- prefix from class="language-${lang}").

Design decisions

• Reference extraction walks Lit template strings with brace+string awareness so class="btn ${cond ? \"active\" : \"\"}" doesn't confuse the parser with the inner quote (naive class="[^"]*" regex breaks here).
• Interpolation content is scope-out per audit(ui): one-shot CSS class drift audit — surface fork-side references with no CSS definition #2502. Static tokens AROUND ${...} ARE captured; content INSIDE is not. This avoids the false-positive flood from string literals used as enum discriminants, i18n keys, or comparison values.
• CSS selector extraction handles compound selectors (.btn.primary → both btn and primary), BEM, pseudo-classes, :not(...), and nested @media blocks.
• Cluster attribution uses git log -S .className with a selector-boundary filter on per-commit diffs so .nav isn't conflated with .nav-section on substring pickaxe hits.

Known limitations

Documented in-script and in the report. The big ones:

• Dynamic class composition (${variable}, classList.add(...), classMap(...)) is out of scope.
• Cluster SHA attribution is a hint, not a guarantee — bulk search-replace renames may cluster to the rename commit rather than an earlier definition.
• Vendored UI outside the ui/src/styles.css import graph is not analyzed.

Test plan

• node scripts/audit-css-class-drift.mjs runs to completion, writes .tmp/audit-css-drift.md, exits 1 with 36 orphans
• Exit code contract verified (1 on findings; logic would exit 0 if 0 orphans; 2 on import-graph resolution failure)
• Output file is under .tmp/ (gitignored) — not accidentally committed
• pnpm format, pnpm lint, pnpm tsgo all clean
• Manually verified 3 cluster attributions against git show <sha> diffs
• Manually verified compound-selector handling (.btn.primary yields both btn and primary)
• Manually verified quote-in-interpolation parser handles class="btn ${cond ? \"active\" : \"\"}" correctly

Follow-ups

• Triage report posted as a comment on audit(ui): one-shot CSS class drift audit — surface fork-side references with no CSS definition #2502 with the full cluster breakdown
• fix(ui) issue filed per cluster with the renames table