@hadoku/themes 0.0.0-stage → 5.12.16

package/scripts/check-usage.mjs

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+/**
+ * Gate: theme tokens must exist, and must be paired correctly.
+ *
+ * Six checks, because each covers a blind spot the others miss:
+ *
+ *   1. `var(--color-*)` in stylesheets  — catches renamed/typo'd tokens.
+ *   2. Tailwind colour classes in markup — stylelint only lints .css and never
+ *      sees `bg-success-bg` inside a .tsx, which is how hadoku_site shipped
+ *      white buttons.
+ *   3. `var(--x, fallback)` fallbacks   — a fallback renders the hardcoded
+ *      value, so a wrong token looks correct in the default light theme and
+ *      breaks in the other 17. This is the silent-failure vector, and the
+ *      stylelint rule everyone reaches for ignores it by design.
+ *   4. Layered `style.css` imports      — putting it in a cascade layer makes
+ *      every colour resolve to nothing.
+ *   5. The tint anti-pattern            — `--color-<f>` as text on
+ *      `--color-<f>-bg`. Both tokens exist, so nothing else flags it, but the
+ *      pair fails AA in 62 of 90 theme/family combinations.
+ *   6. The accent-as-text anti-pattern  — `--color-<f>` as bare text on a page
+ *      or card surface. check-contrast validates `on-<f>` over `<f>` and never
+ *      looks at accent-over-surface, so the pair passes by being unexamined.
+ *      This is how `.app-header__title` shipped 1.92:1 in izakaya-light.
+ *
+ *   5 and 6 run on markup too, as Tailwind classes (`text-success` on a card,
+ *   `bg-success-bg text-success`) — CSS-only, hadoku_site had 49 of them while
+ *   this gate reported OK.
+ *
+ *   node themes/scripts/check-usage.mjs [paths...]   (default: cwd)
+ */
+
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, extname, relative } from 'node:path'
+import { parseThemes, allTokenNames, THEMES, FAMILIES } from './lib/parse-themes.mjs'
+
+const roots = process.argv.slice(2).filter(a => !a.startsWith('--'))
+const targets = roots.length ? roots : [process.cwd()]
+
+const themes = parseThemes()
+// Only tokens defined in EVERY theme count as usable.
+const known = new Set(allTokenNames(themes).filter(n => THEMES.every(t => themes[t][n])))
+
+// `.claude` holds git worktrees — separate checkouts that lint themselves.
+const SKIP_DIRS = new Set([
+  'node_modules',
+  'dist',
+  '.git',
+  '.claude',
+  'playwright-report',
+  'test-results',
+  '.profiler',
+  'calendar-mockups'
+])
+const STYLE_EXT = new Set(['.css'])
+const MARKUP_EXT = new Set(['.tsx', '.jsx', '.astro', '.html', '.vue', '.svelte'])
+
+function* walk(dir) {
+  let entries
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return
+  }
+  for (const entry of entries) {
+    if (SKIP_DIRS.has(entry)) continue
+    const full = join(dir, entry)
+    let st
+    try {
+      st = statSync(full)
+    } catch {
+      continue
+    }
+    if (st.isDirectory()) yield* walk(full)
+    else yield full
+  }
+}
+
+const problems = []
+/**
+ * Opt-out, one line at a time:
+ *
+ *   \/* check-usage-disable-next-line *\/
+ *   color: var(--color-warning);
+ *
+ * Deliberately per-line and comment-based, so every suppression sits next to the
+ * thing it excuses and shows up in review. The real case it exists for is
+ * DEMONSTRATING an anti-pattern — dev/gallery renders a bare accent glyph beside
+ * the tile treatments precisely so the contrast failure is visible. Without a
+ * suppression the only ways to ship that are to weaken the rule for everyone or
+ * to hide the colour somewhere the scanner cannot see, and both are worse.
+ */
+const DISABLE_NEXT = /(?:\/\*|\/\/|<!--)\s*check-usage-disable-next-line/
+
+/** Lines whose finding was explicitly waived by the preceding line. */
+const suppressed = new Map()
+
+const add = (file, line, kind, detail) => {
+  if (suppressed.get(file)?.has(line)) return
+  problems.push({ file, line, kind, detail })
+}
+
+/** Tokens a file is allowed to define locally (app-scoped, not theme tokens). */
+const localDefinitions = new Set()
+
+for (const target of targets) {
+  const base = statSync(target).isDirectory() ? target : null
+  const files = base ? [...walk(base)] : [target]
+
+  // Pass 1: collect locally-defined custom properties so app-level vars
+  // (e.g. --skeleton-shimmer) don't read as unknown theme tokens.
+  for (const file of files) {
+    if (!STYLE_EXT.has(extname(file))) continue
+    const text = readFileSync(file, 'utf8')
+    for (const m of text.matchAll(/^\s*(--[a-z0-9-]+)\s*:/gim)) localDefinitions.add(m[1])
+  }
+
+  for (const file of files) {
+    const ext = extname(file)
+    const isStyle = STYLE_EXT.has(ext)
+    const isMarkup = MARKUP_EXT.has(ext)
+    if (!isStyle && !isMarkup) continue
+    // The package's own sources define the tokens; don't lint them against themselves.
+    if (file.includes(join('themes', 'src')) || file.includes(join('themes', 'dev'))) continue
+
+    const rel = relative(process.cwd(), file)
+    const lines = readFileSync(file, 'utf8').split(/\r?\n/)
+
+    // Collect waivers before scanning, so a rule reported by offset (the
+    // block-level checks below) is covered as well as the per-line ones.
+    const waived = new Set()
+    lines.forEach((line, i) => {
+      if (DISABLE_NEXT.test(line)) waived.add(i + 2)
+    })
+    suppressed.set(rel, waived)
+
+    lines.forEach((line, i) => {
+      const n = i + 1
+
+      // (3) fallbacks — banned outright, they mask every other failure.
+      // Covers every package-owned prefix, not just colours: --hdk-* fails the
+      // same silent way (a stale --hdk-space-md renders the hardcoded px).
+      for (const m of line.matchAll(/var\(\s*(--(?:color|hdk)-[a-z0-9-]+)\s*,/gi)) {
+        add(rel, n, 'fallback', `var(${m[1]}, …) — fallbacks hide broken tokens; drop the fallback`)
+      }
+
+      // (1) unknown custom properties in var()
+      for (const m of line.matchAll(/var\(\s*(--color-[a-z0-9-]+)\s*[,)]/gi)) {
+        const name = m[1]
+        if (!known.has(name) && !localDefinitions.has(name)) {
+          add(rel, n, 'unknown-token', `var(${name}) is not defined by @wolffm/themes`)
+        }
+      }
+
+      // (2) Tailwind colour classes in markup
+      if (isMarkup) {
+        for (const m of line.matchAll(
+          /(?<![\w-])(?:bg|text|border|ring|fill|stroke|from|to|via|outline|decoration|accent|caret|divide|shadow)-((?:on-)?(?:primary|success|warning|danger|neutral|text|border|bg)(?:-[a-z0-9]+)*)(?![\w-])/g
+        )) {
+          const token = `--color-${m[1]}`
+          if (!known.has(token)) {
+            add(rel, n, 'unknown-class', `${m[0]} → ${token} is not mapped by @wolffm/themes`)
+          }
+        }
+
+        // (4)/(5) in markup: the same two anti-patterns, written as Tailwind
+        // classes. `text-success` on a card is `color: var(--color-success)` on
+        // a card, and the CSS pass below never sees a .tsx. The scope is one
+        // quoted string — the class list — so a fill added conditionally in a
+        // separate clsx() argument does not excuse the unfilled case.
+        for (const q of line.matchAll(/(["'`])((?:(?!\1).)*)\1/g)) {
+          const classes = q[2]
+          for (const m of classes.matchAll(
+            /(?<![\w-])text-(primary|success|warning|danger|neutral)(-dark)?(?![\w-])/g
+          )) {
+            const family = m[1]
+            const has = re => new RegExp(`(?<![\\w-])${re}(?![\\w-])`).test(classes)
+            if (has(`bg-${family}-bg`)) {
+              add(
+                rel,
+                n,
+                'tint-pair',
+                `${m[0]} on bg-${family}-bg fails AA in most themes; use text-on-${family}-bg`
+              )
+              continue
+            }
+            // A filled backdrop of its own family is the class list choosing
+            // its surface, like rule (5)'s paintsOwnBg. A surface class
+            // (bg-bg-card) is not: that is exactly the unvalidated pair.
+            if (has(`bg-${family}(?:-dark|-hover)?`)) continue
+            add(
+              rel,
+              n,
+              'accent-as-text',
+              `${m[0]} is a fill colour, not a text colour; on a page or card surface it ` +
+                `fails contrast in most themes. Use text-text, or bg-${family}-bg + text-on-${family}-bg.`
+            )
+          }
+        }
+      }
+    })
+
+    if (isStyle) {
+      const text = lines.join('\n')
+
+      // The cascade-layer constraint that makes the whole mapping work.
+      if (text.match(/@import\s+["'][^"']*@wolffm\/themes\/style\.css["']\s+layer\(/)) {
+        add(
+          rel,
+          1,
+          'layered-import',
+          'style.css must be imported UNLAYERED or every colour resolves to nothing'
+        )
+      }
+
+      // (4) The tint anti-pattern: `<f>` as text on the `<f>-bg` surface.
+      // This is the exact pair that failed AA in 62 of 90 theme/family
+      // combinations, and no amount of token checking catches it — both
+      // tokens exist, they just must not be used together.
+      //
+      // (5) The accent-as-text anti-pattern: `<f>` or `<f>-dark` as bare text,
+      // with no filled background of its own family in the rule. Whatever
+      // surface it lands on is then the page or a card, and THAT pair is
+      // validated by nothing: check-contrast only checks `on-<f>` over `<f>`,
+      // so every accent-over-surface combination passes by never being looked
+      // at. It is not a sanctioned pair — a fill colour is legible only under
+      // `--color-on-<f>`. `.app-header__title` shipped `--color-primary` this
+      // way and missed the 3:1 large-text floor in 6 of 18 themes, in all nine
+      // consuming apps at once. Text on a surface is `--color-text`; to carry
+      // an accent, pair `--color-<f>-bg` with `--color-on-<f>-bg`.
+      const stripped = text.replace(/\/\*[\s\S]*?\*\//g, m => m.replace(/[^\n]/g, ' '))
+      const lineAt = offset => stripped.slice(0, offset).split('\n').length
+      for (const rule of stripped.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+        const body = rule[2]
+        const bodyStart = rule.index + rule[1].length + 1
+        const bg = body.match(/background(?:-color)?\s*:\s*var\(--color-([a-z]+)-bg\)/)
+        const fg = body.match(/(?<!-)color\s*:\s*var\(--color-([a-z]+)\)\s*;/)
+        if (bg && fg && bg[1] === fg[1]) {
+          add(
+            rel,
+            lineAt(bodyStart + fg.index),
+            'tint-pair',
+            `--color-${fg[1]} on --color-${bg[1]}-bg fails AA in most themes; use --color-on-${fg[1]}-bg`
+          )
+          continue
+        }
+
+        // Only *bare* accent text is the anti-pattern. A rule that paints its
+        // own background has chosen its backdrop explicitly — whether that is
+        // `var(--color-primary)` (a filled button: check-contrast's `on-<f>`
+        // over `<f>` pair) or a hardcoded gradient (the theme-picker's fixed
+        // light/dark pill previews). Neither lands on the page surface, which
+        // is the pair this check exists to catch. `none`/`transparent` do not
+        // count: they are exactly how a button declares it has no backdrop and
+        // inherits whatever is behind it.
+        const declaredBg = body.match(/background(?:-color)?\s*:\s*([^;]+)/)
+        const paintsOwnBg =
+          declaredBg && !/^\s*(none|transparent|inherit|initial|unset)\s*$/i.test(declaredBg[1])
+        if (paintsOwnBg) continue
+        for (const m of body.matchAll(/(?<!-)color\s*:\s*var\(--color-([a-z]+)(-dark)?\)\s*;/g)) {
+          const family = m[1]
+          if (!FAMILIES.includes(family)) continue
+          add(
+            rel,
+            lineAt(bodyStart + m.index),
+            'accent-as-text',
+            `--color-${family}${m[2] ?? ''} is a fill colour, not a text colour; ` +
+              `on a page or card surface it fails contrast in most themes. ` +
+              `Use --color-text, or --color-${family}-bg + --color-on-${family}-bg.`
+          )
+        }
+      }
+    }
+  }
+}
+
+const BY_KIND = {
+  'unknown-token': 'Unknown theme tokens',
+  'unknown-class': 'Tailwind classes with no matching token',
+  fallback: 'var() fallbacks (banned — they hide broken tokens)',
+  'layered-import': 'style.css imported into a cascade layer',
+  'tint-pair': 'Family colour used as text on its own tint (fails AA in most themes)',
+  'accent-as-text': 'Fill colour used as bare text on a page/card surface (unvalidated pair)'
+}
+
+if (!problems.length) {
+  console.log(`check-usage: OK — every token reference resolves (${known.size} tokens known).`)
+  process.exit(0)
+}
+
+for (const [kind, label] of Object.entries(BY_KIND)) {
+  const rows = problems.filter(p => p.kind === kind)
+  if (!rows.length) continue
+  console.error(`\n${label} (${rows.length}):`)
+  for (const p of rows) console.error(`  ${p.file}:${p.line}  ${p.detail}`)
+}
+console.error(`\ncheck-usage: FAILED — ${problems.length} problem(s).`)
+process.exit(1)

package/scripts/codemod-icons.mjs

@@ -0,0 +1,396 @@
+#!/usr/bin/env node
+/**
+ * Apply the mechanical half of the emoji -> icon migration.
+ *
+ *   node codemod-icons.mjs <path> [--write] [--quiet]
+ *
+ * Dry-run by default. `--write` edits in place.
+ *
+ * WHAT IT WILL TOUCH, and nothing else:
+ *
+ *   1. `"icon": "✅"` in JSON, and `icon: '✅'` in object literals — a pure string
+ *      swap with no surrounding syntax to get wrong.
+ *   2. A JSX text node that is ONLY an emoji  ->  <Icon name="check" />
+ *   3. An emoji LEADING a JSX text run        ->  <Icon name="check" /> the rest
+ *
+ * WHAT IT DELIBERATELY LEAVES ALONE:
+ *
+ *   - `'🗑️ Delete Board'` — a string, not JSX. Turning it into an element changes
+ *     the call site's type, and whether that call site even accepts a ReactNode is
+ *     a question this script cannot answer. (In hadoku-task the equivalent change
+ *     required widening ContextMenu's `label` from string to ReactNode first.)
+ *   - String literals that are only an emoji, for the same reason: whether the
+ *     value is rendered, logged, or compared is not knowable from the literal.
+ *   - Any emoji with no entry in emoji-map.json.
+ *   - Any emoji listed under `$ambiguous` there — `◀`/`▶`, whose correct icon depends
+ *     on whether it is a transport control or one arm of a mirrored nav pair. Rewriting
+ *     those off the map alone writes a mismatched pair automatically, everywhere.
+ *   - Anything within a few lines of an emoji it is leaving raw, for any of the reasons
+ *     above. Refusing `▶ Play` while rewriting the `⏸ Pause` beside it still ships an
+ *     SVG next to a glyph — the refusal only helps if its neighbours wait with it.
+ *
+ * Those are reported, not guessed at. A codemod that is wrong 5% of the time
+ * across twelve repos costs more review than it saves.
+ */
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'node:fs'
+import { join, extname, relative, resolve, dirname, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { loadIconRegistry, MISSING_REGISTRY_MESSAGE } from './lib/icon-registry.mjs'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const args = process.argv.slice(2)
+const roots = args.filter(a => !a.startsWith('--'))
+const write = args.includes('--write')
+const quiet = args.includes('--quiet')
+if (!roots.length) {
+  console.error('usage: codemod-icons.mjs <path> [--write]')
+  process.exit(1)
+}
+
+// Same two-tree resolution as check-icons — an unguarded read here threw a raw
+// ENOENT stack at anyone running the codemod from a consumer install.
+const { emojiMap: MAP, ambiguous: AMBIGUOUS_RAW } = await loadIconRegistry()
+if (!MAP) {
+  console.error(`codemod-icons: ${MISSING_REGISTRY_MESSAGE}`)
+  process.exit(1)
+}
+const stripVs = s =>
+  [...s]
+    .filter(c => {
+      const p = c.codePointAt(0)
+      return p !== 0xfe0f && p !== 0xfe0e && !(p >= 0x1f3fb && p <= 0x1f3ff)
+    })
+    .join('')
+const EMOJI_TO_ICON = new Map()
+for (const [e, n] of Object.entries(MAP)) {
+  if (!e.startsWith('$') && typeof n === 'string') EMOJI_TO_ICON.set(stripVs(e), n)
+}
+/**
+ * Glyphs listed under `$ambiguous` in emoji-map.json resolve two ways depending on
+ * what sits beside them, so they are exactly the "needs judgement" case this script
+ * refuses. Rewriting `◀ Prev` / `Next ▶` off the map alone emits chevron-left beside
+ * play — a mismatched pair, written automatically, in every repo the codemod touches.
+ */
+const AMBIGUOUS = new Map(
+  Object.entries(AMBIGUOUS_RAW ?? {}).map(([e, note]) => [stripVs(e), note])
+)
+const nameFor = e => (AMBIGUOUS.has(stripVs(e)) ? undefined : EMOJI_TO_ICON.get(stripVs(e)))
+const ambiguityNote = e => AMBIGUOUS.get(stripVs(e))
+
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', 'out', '.next', '.astro', '.claude',
+  'playwright-report', 'test-results', '.profiler', '.wrangler', 'coverage',
+  'vendor', 'third_party', '__pycache__', '.venv'
+])
+const GENERATED_PATH =
+  /(^|\/)(public\/(mf|v\d+)|\.output|\.vercel|storybook-static|bundle)(\/|$)|\.(min|bundle|generated)\.[a-z]+$/
+const NON_UI_CODE_DIR =
+  /(^|\/)(workers?|services?|server|scripts?|functions|cli|bin|migrations|e2e|tests?|__tests__)(\/|$)/
+const TEST_FILE = /\.(spec|test)\.[cm]?[jt]sx?$/
+const MARKUP_EXT = new Set(['.tsx', '.jsx', '.astro', '.vue', '.svelte', '.html'])
+const SCRIPT_EXT = new Set(['.ts', '.js', '.mjs', '.cjs'])
+
+const EMOJI_RE =
+  /(?:\p{RI}\p{RI}|[#*0-9]️?⃣|\p{Extended_Pictographic}(?:️|[\u{1F3FB}-\u{1F3FF}])*(?:‍\p{Extended_Pictographic}(?:️|[\u{1F3FB}-\u{1F3FF}])*)*)/gu
+const isEmoji = s => /\p{Extended_Pictographic}|\p{RI}\p{RI}|⃣/u.test(s)
+
+function* walk(dir) {
+  let entries
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return
+  }
+  for (const e of entries) {
+    if (SKIP_DIRS.has(e.name)) continue
+    const full = join(dir, e.name)
+    if (e.isSymbolicLink()) continue
+    if (e.isDirectory()) yield* walk(full)
+    else yield full
+  }
+}
+
+const changed = []
+const skipped = []
+let filesTouched = 0
+
+for (const root of roots) {
+  const abs = resolve(root)
+  if (!existsSync(abs)) {
+    console.error(`codemod-icons: no such path: ${root}`)
+    process.exit(1)
+  }
+  for (const file of walk(abs)) {
+    const ext = extname(file)
+    const isMarkup = MARKUP_EXT.has(ext)
+    const isJson = ext === '.json'
+    const isScript = SCRIPT_EXT.has(ext)
+    if (!isMarkup && !isJson && !isScript) continue
+    const posix = file.split(sep).join('/')
+    if (GENERATED_PATH.test(posix) || TEST_FILE.test(posix)) continue
+    if (!isMarkup && NON_UI_CODE_DIR.test(posix)) continue
+
+    let st
+    try {
+      st = statSync(file)
+    } catch {
+      continue
+    }
+    if (st.size > 2 * 1024 * 1024) continue
+
+    const original = readFileSync(file, 'utf8')
+    if (!EMOJI_RE.test(original)) continue
+    EMOJI_RE.lastIndex = 0
+
+    const rel = relative(process.cwd(), file)
+    const lines = original.split('\n')
+    let jsxEdits = 0
+    let fileEdits = 0
+
+    const isNonUi = l =>
+      /^(\/\/|\/\*|\*|#|<!--)/.test(l.trim()) ||
+      /\b(console|logger|log)\s*\.\s*(log|warn|error|info|debug|table|trace|group)\b/.test(l) ||
+      /process\.stdout|\bprint\(/.test(l)
+
+    /**
+     * Where a `//` line comment starts, or the line length. Everything past it
+     * renders nothing, so no rule may rewrite there AND no emoji there can clash
+     * with an icon beside it. `isNonUi` only catches lines that BEGIN with a comment
+     * marker, and pygmalion's icons.tsx documents its whole registry in TRAILING
+     * ones — `export const WarnIcon = TriangleAlert // ⚠` would otherwise become
+     * `// <Icon name="warning" />`, rewriting prose about an icon into an icon.
+     * Quote-aware, so a `//` inside a string is not mistaken for a comment.
+     */
+    const codeEndOf = line => {
+      let quote = null
+      for (let k = 0; k < line.length; k++) {
+        const c = line[k]
+        if (quote) {
+          if (c === '\\') k++
+          else if (c === quote) quote = null
+          continue
+        }
+        if (c === "'" || c === '"' || c === '`') { quote = c; continue }
+        if (c === '/' && line[k + 1] === '/') return k
+      }
+      return line.length
+    }
+
+    /**
+     * One line's rewrite, isolated so it can be run twice: once as a PROBE that
+     * answers "does this line still hold a raw emoji afterwards", and once for
+     * real. `report` is null on the probe pass so nothing is logged twice.
+     */
+    const convertLine = (line, i, report) => {
+      let jsx = 0
+      let edits = 0
+      const say = msg => { if (report) report.push(msg) }
+
+      // (1) icon/glyph/emoji field values — pure string swap.
+      line = line.replace(
+        /((?:"(?:icon|glyph|emoji)"|(?<![\w$])(?:icon|glyph|emoji))\s*[:=]\s*)(['"])([^'"]*)\2/g,
+        (m, head, q, val) => {
+          const hits = [...val.matchAll(EMOJI_RE)].map(x => x[0]).filter(isEmoji)
+          if (!hits.length || hits.join('') !== val.trim()) return m
+          const name = nameFor(hits[0])
+          if (!name) {
+            const note = ambiguityNote(hits[0])
+            say(
+              note
+                ? `${rel}:${i + 1}  ${hits[0]} needs judgement — ${note}`
+                : `${rel}:${i + 1}  no mapping for ${val}`
+            )
+            return m
+          }
+          edits++
+          return `${head}${q}${name}${q}`
+        }
+      )
+
+      // Only JSX files get an <Icon> element. An .astro/.vue/.svelte/.html file
+      // has no such component in scope and the import block below cannot give it
+      // one — emitting <Icon> there produces markup that does not compile. Astro
+      // wants `set:html={getIconSvg('name')}` with a frontmatter import, which is
+      // a different edit in a different part of the file, so it is reported
+      // instead of guessed at.
+      const canEmitJsx = ext === '.tsx' || ext === '.jsx'
+      const codeEnd = codeEndOf(line)
+
+      /**
+       * The icon name for a token that is NOTHING BUT emoji.
+       *   undefined — not an emoji-only token, ignore it silently
+       *   null      — emoji, but this run will not convert it (reason logged)
+       */
+      const resolveToken = tok => {
+        const hits = [...tok.matchAll(EMOJI_RE)].map(x => x[0]).filter(isEmoji)
+        if (!hits.length || hits.join('') !== tok) return undefined
+        const name = nameFor(tok)
+        if (name) return name
+        const note = ambiguityNote(tok)
+        say(
+          note
+            ? `${rel}:${i + 1}  ${tok} needs judgement — ${note}`
+            : `${rel}:${i + 1}  no mapping for ${tok}`
+        )
+        return null
+      }
+
+      // An emoji OPENING a text run — `<div>👤 {value}</div>`, the commonest shape.
+      const LEADING = /(^|>|\{' '\}|\{" "\})(\s*)([^\s<>{}'"`]+)(\s*)(?=$|<|[A-Za-z({])/g
+      // An emoji CLOSING one — `<b>{disp(m.b)}</b> wins ▶`. LEADING anchors on `>` or
+      // line start, so a glyph sitting AFTER its label was invisible to it: the codemod
+      // stayed silent on pygmalion's BakeoffReview `wins ▶` and on promptsmith's
+      // `Pick B ▶` while check-icons reported both. The two tools now agree.
+      //
+      // Anchored on the whitespace before the token and a `<` or end-of-line after it,
+      // which is what keeps it out of strings and attributes: the token class excludes
+      // quotes and braces, so `'⚠ ' + err` and `className="a b"` cannot produce one.
+      const TRAILING = /(\s)([^\s<>{}'"`]+)(\s*)(?=<|$)/g
+
+      if (isMarkup && !canEmitJsx) {
+        // Report only — an .astro/.vue/.html file has no <Icon> in scope.
+        const seen = new Set()
+        for (const re of [LEADING, TRAILING]) {
+          re.lastIndex = 0
+          for (const m of line.matchAll(re)) {
+            const tok = re === LEADING ? m[3] : m[2]
+            if (m.index + m[0].indexOf(tok) >= codeEnd) continue
+            if (seen.has(tok)) continue
+            const name = resolveToken(tok)
+            if (name === undefined || name === null) continue
+            seen.add(tok)
+            say(
+              `${rel}:${i + 1}  ${tok} -> ${name} (${ext} needs getIconSvg + a frontmatter import, by hand)`
+            )
+          }
+        }
+      }
+      if (canEmitJsx) {
+        line = line.replace(LEADING, (m, pre, ws, tok, post, offset) => {
+          if (offset + pre.length + ws.length >= codeEnd) return m
+          const name = resolveToken(tok)
+          if (!name) return m
+          jsx++
+          edits++
+          return `${pre}${ws}<Icon name="${name}" />${post}`
+        })
+        line = line.replace(TRAILING, (m, pre, tok, post, offset) => {
+          if (offset + pre.length >= codeEnd) return m
+          const name = resolveToken(tok)
+          if (!name) return m
+          jsx++
+          edits++
+          return `${pre}<Icon name="${name}" />${post}`
+        })
+      }
+      return { line, jsx, edits }
+    }
+
+    /**
+     * PARTIAL PAIRS. Converting one glyph of a control group while its neighbour
+     * stays a raw emoji is the failure this guard exists for: `▶ Play` is refused
+     * as ambiguous, `⏸ Pause` on the next line is not, and --write leaves an SVG
+     * sitting beside an emoji — the very mismatch the refusal was meant to avoid.
+     *
+     * A line that STILL holds an emoji after its own rewrite is one this run is
+     * leaving raw, whatever the reason (ambiguous, unmapped, a bare string, an
+     * .html file with no <Icon> in scope). Nothing within PAIR_WINDOW lines of one
+     * is converted; it is reported instead, so the human fixes the group together.
+     *
+     * Comments are excluded — an emoji in a comment renders nothing, so it cannot
+     * clash with an icon beside it.
+     *
+     * The window is deliberately small. Sibling controls in one row sit within a
+     * few lines of each other (the promptsmith tournament row spanned five), while
+     * unrelated emoji are typically far off — pygmalion's BakeoffReview has a `▶`
+     * at line 310 and its next emoji at 31 and 471. File scope would have blocked
+     * both of those for no reason.
+     */
+    const PAIR_WINDOW = 4
+    const retainsRawEmoji = lines.map((l, i) => {
+      if (isNonUi(l)) return false
+      const { line: after } = convertLine(l, i, null)
+      const code = after.slice(0, codeEndOf(after))
+      return [...code.matchAll(EMOJI_RE)].some(m => isEmoji(m[0]))
+    })
+    const nearRetained = i => {
+      const lo = Math.max(0, i - PAIR_WINDOW)
+      const hi = Math.min(lines.length - 1, i + PAIR_WINDOW)
+      for (let j = lo; j <= hi; j++) if (retainsRawEmoji[j]) return true
+      return false
+    }
+
+    for (let i = 0; i < lines.length; i++) {
+      if (isNonUi(lines[i])) continue
+      // Run for real either way: a deferred line still owes its own reasons
+      // ("▶ needs judgement"), which are what tell the human what to do.
+      const r = convertLine(lines[i], i, skipped)
+      if (nearRetained(i)) {
+        if (r.edits) {
+          skipped.push(
+            `${rel}:${i + 1}  deferred — a raw emoji this run cannot convert sits within ` +
+              `${PAIR_WINDOW} lines; converting this one alone would leave an SVG beside a glyph`
+          )
+        }
+        continue
+      }
+      if (r.line !== lines[i]) {
+        lines[i] = r.line
+        changed.push(`${rel}:${i + 1}`)
+      }
+      jsxEdits += r.jsx
+      fileEdits += r.edits
+    }
+
+    if (!fileEdits) continue
+    let out = lines.join('\n')
+
+    // Add the import only when JSX was actually produced.
+    if (jsxEdits && (ext === '.tsx' || ext === '.jsx') && !/from '@wolffm\/themes'/.test(out)) {
+      // Insert after the line that CLOSES the last import, not after the last
+      // line that merely starts with `import`. A multi-line
+      //     import {
+      //       a, b
+      //     } from 'x'
+      // matches the naive test on its first line, and inserting there lands the
+      // new import INSIDE the braces — which is exactly what it did to
+      // pygmalion's BakeoffReview.tsx, and the build caught it.
+      const src = out.split('\n')
+      let lastImport = -1
+      let inImport = false
+      for (let idx = 0; idx < src.length; idx++) {
+        const l = src[idx]
+        if (!inImport && /^\s*import\b/.test(l)) {
+          // Single-line import, or the head of a multi-line one.
+          if (/\bfrom\s*['"][^'"]+['"]\s*;?\s*$/.test(l) || /^\s*import\s*['"]/.test(l)) lastImport = idx
+          else inImport = true
+        } else if (inImport && /\bfrom\s*['"][^'"]+['"]\s*;?\s*$/.test(l)) {
+          lastImport = idx
+          inImport = false
+        }
+      }
+      if (lastImport >= 0) {
+        src.splice(lastImport + 1, 0, "import { Icon } from '@wolffm/themes'")
+        out = src.join('\n')
+      } else {
+        skipped.push(`${rel}  produced JSX but has no import block — add Icon import by hand`)
+      }
+    }
+
+    filesTouched++
+    if (write) writeFileSync(file, out)
+  }
+}
+
+if (!quiet) {
+  for (const c of changed) console.log(`  edit  ${c}`)
+  if (skipped.length) {
+    console.log('\n  left for a human:')
+    for (const s of [...new Set(skipped)]) console.log(`    ${s}`)
+  }
+}
+console.log(
+  `\ncodemod-icons: ${changed.length} replacement(s) in ${filesTouched} file(s)` +
+    `${skipped.length ? `, ${new Set(skipped).size} left for a human` : ''}` +
+    `${write ? '' : '  [dry run — pass --write to apply]'}`
+)