@hadoku/themes 0.0.0-stage → 5.12.15

package/scripts/lib/derive.mjs

@@ -0,0 +1,324 @@
+/**
+ * Derives the canonical token set for a theme from its existing values.
+ *
+ * Every derived value is produced in OKLCH (THEME_SYSTEM_RULES §8 — an HSL
+ * lightness shift that is safe for blue is catastrophic for yellow) and then
+ * verified against the WCAG contracts in §1/§2 rather than trusted.
+ */
+
+import {
+  parseColor,
+  flatten,
+  contrast,
+  toHex,
+  rgbToOklch,
+  oklchToRgb,
+  shiftLightness
+} from './color.mjs'
+import { FAMILIES } from './tokens.mjs'
+
+/** Minimum WCAG ratio for text (§1, §2). Derived values aim slightly above. */
+export const AA_TEXT = 4.5
+const TARGET = 4.6 // headroom so rounding can't drop a value under the bar
+
+/**
+ * Median OKLCH ΔL between the existing `<f>` and `<f>-dark` values across all
+ * themes is ≈ -0.07 (measured over primary/success/danger, n=54). New `-dark`
+ * values use that so they sit in the same visual family as the hand-authored ones.
+ */
+const DARK_SHIFT = -0.07
+
+/**
+ * `-dark` is overwhelmingly consumed as the bottom stop of a filled button's
+ * gradient (`linear-gradient(180deg, var(--color-f), var(--color-f-dark))`),
+ * not as a separate hover swap. So `on-<f>` sits on the whole ramp and has to
+ * clear 4.5:1 at BOTH ends. These bound how far the ramp may travel: far
+ * enough to read as a gradient, never far enough to break the text.
+ */
+const MIN_DARK_SHIFT = 0.03
+const MAX_DARK_SHIFT = 0.12
+
+const fmt = (rgb, alpha) =>
+  alpha >= 1
+    ? toHex(rgb)
+    : `rgba(${rgb
+        .slice(0, 3)
+        .map(v => Math.round(v))
+        .join(', ')}, ${Math.round(alpha * 100) / 100})`
+
+/**
+ * Text/icon color ON a filled `<f>` surface.
+ *
+ * §7 warns that the usual luminance-threshold heuristic flips near its 0.179
+ * cutoff, so this picks by measured WCAG ratio instead: whichever of black or
+ * white scores higher.
+ */
+function deriveOn(base) {
+  return contrast('black', base) >= contrast('white', base) ? 'black' : 'white'
+}
+
+/**
+ * Pull a base colour out of the luminance dead zone.
+ *
+ * §7: "If neither white nor black achieves 4.5:1, the base color is unsuitable
+ * for a filled button." Three of the 90 family bases sit just inside that band
+ * — they clear 4.5:1 on their own but leave no room for the gradient's bottom
+ * stop. Darkening is the safe direction: it monotonically *increases* white's
+ * contrast, so the ramp can only improve from there. The nudge preserves hue
+ * and chroma and is 0.015–0.045 L, below the just-noticeable threshold.
+ */
+function ensureFillable(base) {
+  const headroom = c => Math.max(contrast('black', c), contrast('white', c))
+  if (headroom(base) >= TARGET + 0.2) return { color: base, nudged: false }
+
+  for (let s = 0.005; s <= 0.25; s += 0.005) {
+    const candidate = toHex(shiftLightness(base, -s).rgb)
+    if (contrast('white', candidate) >= 4.8) {
+      return { color: candidate, nudged: true, shift: s }
+    }
+  }
+  return { color: base, nudged: false }
+}
+
+/**
+ * The gradient's bottom stop: as deep as possible without dropping `on` below
+ * the AA floor, bounded so the ramp stays visible but never runaway.
+ */
+function deriveDark(base, on = deriveOn(base)) {
+  let shift = 0
+  for (let s = MIN_DARK_SHIFT; s <= MAX_DARK_SHIFT; s += 0.005) {
+    if (contrast(on, toHex(shiftLightness(base, -s).rgb)) >= TARGET) shift = s
+    else break
+  }
+  const { rgb, alpha } = shiftLightness(base, -(shift || MIN_DARK_SHIFT))
+  return fmt(rgb, alpha)
+}
+
+/**
+ * Text color ON the faint `<f>-bg` tint (Material's on-container role).
+ *
+ * Keeps the family's hue and chroma so a badge still reads as that family,
+ * but walks OKLCH lightness away from the tint until the pair clears 4.5:1.
+ *
+ * The tint is usually translucent, so what it composites over changes the
+ * result. A badge can sit on any app surface, so this solves for the WORST of
+ * them — deriving against `bg-card` alone left 19 pairs under the bar once the
+ * same badge was placed on `bg-alt`.
+ */
+function deriveOnBg(base, tint, surfaces) {
+  const list = Array.isArray(surfaces) ? surfaces : [surfaces]
+  const solidTints = list.map(s => flatten(tint, s))
+  const holds = color => solidTints.every(t => contrast(color, toHex(t)) >= TARGET)
+
+  const { L, C, H } = rgbToOklch(parseColor(base))
+  // Move away from the tint's lightness: darker text on a light tint, lighter
+  // on a dark one. Use the lightest composite to choose the direction.
+  const tintL = Math.max(...solidTints.map(t => rgbToOklch(t).L))
+  const direction = tintL > 0.5 ? -1 : 1
+
+  for (let step = 0; step <= 100; step += 1) {
+    const target = L + direction * step * 0.01
+    if (target < 0 || target > 1) break
+    const candidate = toHex(oklchToRgb({ L: target, C, H }))
+    if (holds(candidate)) return candidate
+  }
+
+  // Hue-preserving text can't reach the bar (near-black or near-white tint) —
+  // fall back to whichever neutral holds across every surface.
+  for (const neutral of ['black', 'white']) {
+    if (holds(neutral)) return neutral
+  }
+  const worst = toHex(solidTints[0])
+  return contrast('black', worst) >= contrast('white', worst) ? 'black' : 'white'
+}
+
+/**
+ * Minimum OKLCH ΔL between the surfaces a boundary has to be seen across.
+ *
+ * Measured, not picked: every dark theme steps page → card by 0.052–0.098 and
+ * reads fine, while the light themes had drifted to 0.008–0.025 — white cards
+ * on a near-white page, with the 1px border left to carry the whole edge
+ * alone. Two of them (strawberry, lavender) even had the card DARKER than the
+ * page. Nothing gated it, because these tokens used to pass through untouched.
+ */
+export const SURFACE_STEP = 0.05 // page (`bg`) → raised (`bg-card`), both modes
+/**
+ * `border` / `border-light` against `bg-card`. The dark floor sits where the
+ * dark themes already were (0.104–0.215); only ocean-dark (0.007) and
+ * lavender-dark fell under it. The light floor is set above where the light
+ * themes were, because at those values the edges were reported unreadable.
+ */
+export const BORDER_STEP = { light: 0.13, dark: 0.1 }
+export const BORDER_LIGHT_STEP = { light: 0.075, dark: 0.05 }
+
+/** Aim this far past a floor so hex rounding can't land a value back under it. */
+const STEP_HEADROOM = 0.004
+
+/**
+ * A page pulled down off white has to carry the theme's hue, or it reads as
+ * dirty grey. Measured: the moved pages that looked right (ocean, coffee,
+ * nature) all sat at C ≥ 0.012; the ones that went dingy (strawberry,
+ * lavender, pink, cyberpunk) were at ≤ 0.005. Below this, a hue is noise.
+ */
+const PAGE_MIN_CHROMA = 0.012
+const ACHROMATIC = 0.002
+
+const L = c => rgbToOklch(parseColor(c)).L
+const withL = (color, target) => {
+  const { rgb, alpha } = shiftLightness(color, target - L(color))
+  return fmt(rgb, alpha)
+}
+
+/**
+ * Pull the surface ladder apart until each step clears its floor.
+ *
+ * Moves as little as possible and only the values that fail, keeping hue and
+ * chroma, so a theme that already holds is left alone: every dark theme but
+ * two borders, and izakaya-light but for a one-hex-step border nudge. A card
+ * is the lighter surface in both modes (§5: higher = lighter), unless an
+ * inverted ladder already clears the step. In a light theme the PAGE moves
+ * down rather than the card up — the card is already at or near white, and
+ * "too bright" was the complaint. `bg-alt` and `bg-hover` ride along with the
+ * page so their offsets from it are preserved, and all three are lifted to
+ * PAGE_MIN_CHROMA, in their own hue or, where they have none, the primary's.
+ *
+ * A darker page lowers the contrast of whatever text sits on it, so the body
+ * text tokens are then walked away from the surfaces until they clear AA again.
+ */
+function separateSurfaces(tokens, notes) {
+  const out = { ...tokens }
+  const set = (name, value) => {
+    if (value === out[name]) return
+    notes.push({ token: name, from: out[name], to: value, reason: 'separation' })
+    out[name] = value
+  }
+
+  const light = L(out['--color-bg']) > 0.5
+  const step = L(out['--color-bg-card']) - L(out['--color-bg'])
+  // An inverted ladder that still clears the step is a deliberate choice —
+  // izakaya-light's pink paper card on a cream page — and stays as authored.
+  if (Math.abs(step) < SURFACE_STEP) {
+    if (light) {
+      // Inverted (card darker than page): lift the card to the page first, so
+      // the step is measured down from a real top.
+      if (step < 0) set('--color-bg-card', withL(out['--color-bg-card'], L(out['--color-bg'])))
+      const shift = L(out['--color-bg-card']) - SURFACE_STEP - STEP_HEADROOM - L(out['--color-bg'])
+      const hueOf = c => rgbToOklch(parseColor(c))
+      const pageHue = [out['--color-bg'], out['--color-primary']]
+        .map(hueOf)
+        .find(o => o.C > ACHROMATIC).H
+      for (const n of ['--color-bg', '--color-bg-alt', '--color-bg-hover']) {
+        const own = hueOf(out[n])
+        const H = own.C > ACHROMATIC ? own.H : pageHue
+        const C = Math.max(own.C, PAGE_MIN_CHROMA)
+        set(n, toHex(oklchToRgb({ L: own.L + shift, C, H })))
+      }
+    } else {
+      const target = L(out['--color-bg']) + SURFACE_STEP + STEP_HEADROOM
+      set('--color-bg-card', withL(out['--color-bg-card'], target))
+    }
+  }
+
+  // Borders step away from the card toward the text: darker in a light
+  // theme, lighter in a dark one.
+  const card = out['--color-bg-card']
+  const away = light ? -1 : 1
+  const mode = light ? 'light' : 'dark'
+  for (const [name, floor] of [
+    ['--color-border', BORDER_STEP[mode]],
+    ['--color-border-light', BORDER_LIGHT_STEP[mode]]
+  ]) {
+    if (Math.abs(rgbToOklch(flatten(out[name], card)).L - L(card)) < floor) {
+      set(name, withL(out[name], L(card) + away * (floor + STEP_HEADROOM)))
+    }
+  }
+
+  const surfaces = ['--color-bg', '--color-bg-card', '--color-bg-alt'].map(n => out[n])
+  for (const name of ['--color-text', '--color-text-secondary']) {
+    for (let s = 0; s <= 0.3; s += 0.005) {
+      const candidate = s ? withL(out[name], L(out[name]) + away * s) : out[name]
+      if (surfaces.every(bg => contrast(candidate, bg, card) >= TARGET)) {
+        set(name, candidate)
+        break
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * Build the full canonical color token map for one theme from its current one.
+ *
+ * Renames carry values over verbatim (no visual change); only genuinely new
+ * tokens are computed.
+ */
+export function deriveTheme(input, notes = []) {
+  const out = {}
+  // Separate first: every surface-relative value below is solved against these.
+  const tokens = separateSurfaces(input, notes)
+  // Every surface a translucent tint might composite over.
+  const surfaces = ['--color-bg-card', '--color-bg', '--color-bg-alt']
+    .map(n => tokens[n])
+    .filter(Boolean)
+  if (!surfaces.length) surfaces.push('#ffffff')
+
+  // Renames — the value already exists under a legacy name.
+  const RENAMED_BG = {
+    danger: '--color-danger-light', // danger had no -bg; its tint was -light
+    neutral: '--color-muted-bg' // orphan name that broke the <family>-bg pattern
+  }
+
+  for (const f of FAMILIES) {
+    const { color: base, nudged, shift } = ensureFillable(tokens[`--color-${f}`])
+    if (nudged) {
+      notes.push({ token: `--color-${f}`, from: tokens[`--color-${f}`], to: base, shift })
+    }
+    const on = deriveOn(base)
+
+    // Keep a hand-authored `-dark` when it already holds the contract — those
+    // are deliberate design choices, and the goal here is structural symmetry,
+    // not homogenising every value. Re-derive only the ones that break it.
+    const authored = tokens[`--color-${f}-dark`]
+    const dark = authored && contrast(on, authored) >= AA_TEXT ? authored : deriveDark(base, on)
+    if (authored && dark !== authored) {
+      notes.push({ token: `--color-${f}-dark`, from: authored, to: dark, reason: 'contrast' })
+    }
+
+    const tint = tokens[`--color-${f}-bg`] || tokens[RENAMED_BG[f]]
+    out[`--color-${f}`] = base
+    out[`--color-${f}-dark`] = dark
+    out[`--color-${f}-bg`] = tint
+    out[`--color-${f}-hover`] = tokens[`--color-${f}-hover`]
+    out[`--color-on-${f}`] = on
+    out[`--color-on-${f}-bg`] = deriveOnBg(base, tint, surfaces)
+  }
+
+  // Structural tokens pass through untouched.
+  for (const name of [
+    '--color-text',
+    '--color-text-secondary',
+    '--color-text-tertiary',
+    '--color-text-muted',
+    '--color-border',
+    '--color-border-light',
+    '--color-bg',
+    '--color-bg-card',
+    '--color-bg-alt',
+    '--color-bg-hover',
+    '--color-bg-overlay'
+  ]) {
+    out[name] = tokens[name]
+  }
+
+  return out
+}
+
+/** Tokens removed by the consolidation, with what replaces them. */
+export const REMOVED_TOKENS = {
+  '--color-primary-light': '--color-primary-bg',
+  '--color-danger-light': '--color-danger-bg',
+  '--color-danger-darker': '--color-danger-dark',
+  '--color-neutral-light': '--color-neutral-bg',
+  '--color-neutral-lighter': '--color-neutral-bg',
+  '--color-muted-bg': '--color-neutral-bg'
+}

package/scripts/lib/icon-registry.mjs

@@ -0,0 +1,92 @@
+/**
+ * Locate the icon registry, from either of the two trees it can live in.
+ *
+ * The scripts that need it run in two very different places:
+ *
+ *   - In this workspace, where `themes/src` is authored but `themes/dist` only
+ *     exists after a build. Parsing the .ts source is what lets `check:icons`
+ *     run on a clean checkout with no build step.
+ *   - From a consumer's node_modules, where the shape of the tarball decides
+ *     what is there at all.
+ *
+ * Reading only `src/icons/registry.generated.ts` made the second case depend on
+ * `src/icons` being listed in package.json `files`. It was not, up to and
+ * including 5.6.2, so every consumer that ran the documented command got
+ * `registry.generated.ts is missing — run pnpm run generate:icons` — advice that
+ * cannot work in a consumer repo, for a file npm had simply not shipped. 5.7.1
+ * ships `src/icons` and fixes that, but the gate should not be one `files` edit
+ * away from breaking again for every downstream repo at once. So: prefer src,
+ * fall back to the built registry, and only fail when neither is present.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const SRC_REGISTRY = resolve(here, '../../src/icons/registry.generated.ts')
+const SRC_EMOJI_MAP = resolve(here, '../../src/icons/emoji-map.json')
+const DIST_REGISTRY = resolve(here, '../../dist/icons/registry.generated.js')
+
+/**
+ * Icon names out of the generated .ts, without needing it compiled.
+ *
+ * Tolerates any indent — the emitted source is 2-space and the built .js is
+ * 4-space, and a check that silently parses zero icons out of the wrong one is
+ * worse than no check. `export type IconName` terminates the object in the .ts
+ * and is absent from the .js, so its absence means "read to the end".
+ */
+function parseRegistrySource(src) {
+  const start = src.indexOf('export const ICON_MARKUP')
+  if (start === -1) return null
+  const end = src.indexOf('export type IconName')
+  const body = src.slice(start, end === -1 ? undefined : end)
+  const names = [...body.matchAll(/^\s+'?([a-z0-9-]+)'?:/gm)].map(m => m[1])
+  return names.length ? new Set(names) : null
+}
+
+/**
+ * @returns {Promise<{iconNames: Set<string>, emojiMap: Record<string,string>|null, ambiguous: Record<string,string>|null, source: string}>}
+ *   `emojiMap` is null only when neither tree carries one; `$`-prefixed comment
+ *   keys are passed through untouched for the caller to skip. `ambiguous` maps an
+ *   emoji to the reason its single mapping needs a human — see `$ambiguous` in
+ *   emoji-map.json.
+ */
+export async function loadIconRegistry() {
+  if (existsSync(SRC_REGISTRY)) {
+    const iconNames = parseRegistrySource(readFileSync(SRC_REGISTRY, 'utf8'))
+    if (iconNames) {
+      const emojiMap = existsSync(SRC_EMOJI_MAP)
+        ? JSON.parse(readFileSync(SRC_EMOJI_MAP, 'utf8'))
+        : null
+      return {
+        iconNames,
+        emojiMap,
+        ambiguous: emojiMap?.$ambiguous ?? null,
+        source: 'src/icons/registry.generated.ts',
+      }
+    }
+  }
+
+  if (existsSync(DIST_REGISTRY)) {
+    const mod = await import(pathToFileURL(DIST_REGISTRY).href)
+    if (mod.ICON_MARKUP) {
+      return {
+        iconNames: new Set(Object.keys(mod.ICON_MARKUP)),
+        emojiMap: mod.EMOJI_TO_ICON ?? null,
+        // Only the generated registry carries these in a consumer install —
+        // there is no emoji-map.json outside the source tree to fall back on.
+        ambiguous: mod.AMBIGUOUS_EMOJI ?? null,
+        source: 'dist/icons/registry.generated.js',
+      }
+    }
+  }
+
+  return { iconNames: new Set(), emojiMap: null, ambiguous: null, source: null }
+}
+
+/** The message every caller should print when {@link loadIconRegistry} comes back empty. */
+export const MISSING_REGISTRY_MESSAGE =
+  'icon registry not found — looked for themes/src/icons/registry.generated.ts and ' +
+  'themes/dist/icons/registry.generated.js.\n' +
+  'In this workspace, run `pnpm run generate:icons`. From a consumer repo, this means the ' +
+  'installed @wolffm/themes shipped neither tree — upgrade to >= 5.7.1.'

package/scripts/lib/parse-themes.mjs

@@ -0,0 +1,19 @@
+/**
+ * Node wrapper over tokens.mjs: the same parser, defaulting to the package's
+ * own style.css on disk. Scripts import from here; anything that must also run
+ * in a browser or a worker imports tokens.mjs / contract.mjs instead.
+ */
+
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import { parseThemes as parseThemeCss } from './tokens.mjs'
+
+export * from './tokens.mjs'
+
+const here = dirname(fileURLToPath(import.meta.url))
+export const STYLE_PATH = resolve(here, '../../src/style.css')
+
+export function parseThemes(css = readFileSync(STYLE_PATH, 'utf8')) {
+  return parseThemeCss(css)
+}

package/scripts/lib/tokens.mjs

@@ -0,0 +1,188 @@
+/**
+ * Parses themes/src/style.css text into a per-theme token map.
+ *
+ * Pure — no node imports — so the hosted theme editor and the task worker can
+ * run the same parser the CLI gates do. parse-themes.mjs is the node wrapper
+ * that reads the file from disk.
+ *
+ * The file is a flat sequence of `[data-theme='x'] { ... }` blocks (plus the
+ * `:root, [data-theme='light']` opener). A theme can appear in more than one
+ * block — the advanced-gradient contract is declared separately — so tokens
+ * are merged in source order, last write winning, which mirrors the cascade.
+ */
+
+/** Every theme shipped by the package, in source order. */
+export const THEMES = [
+  'light',
+  'dark',
+  'strawberry-light',
+  'strawberry-dark',
+  'ocean-light',
+  'ocean-dark',
+  'cyberpunk-light',
+  'cyberpunk-dark',
+  'coffee-light',
+  'coffee-dark',
+  'lavender-light',
+  'lavender-dark',
+  'pink-light',
+  'pink-dark',
+  'nature-light',
+  'nature-dark',
+  'izakaya-light',
+  'izakaya-dark'
+]
+
+export const isDarkTheme = name => name.endsWith('dark')
+
+/** The five semantic color families that must share an identical token set. */
+export const FAMILIES = ['primary', 'success', 'warning', 'danger', 'neutral']
+
+/** Structural (non-family) color tokens. */
+export const STRUCTURAL = [
+  'text',
+  'text-secondary',
+  'text-tertiary',
+  'text-muted',
+  'border',
+  'border-light',
+  'bg',
+  'bg-card',
+  'bg-alt',
+  'bg-hover',
+  'bg-overlay'
+]
+
+/**
+ * Replace every comment with same-length spaces. Blanking rather than
+ * deleting keeps all offsets valid, so callers can splice the original file
+ * using the ranges this module reports.
+ */
+export function blankComments(css) {
+  return css.replace(/\/\*[\s\S]*?\*\//g, m => m.replace(/[^\n\r]/g, ' '))
+}
+
+/**
+ * Split the stylesheet into `{ selector, body, start, end }` records.
+ * Depth counting keeps nested at-rules (none today, but @media is likely
+ * later) from terminating a block early.
+ *
+ * Offsets index into the ORIGINAL `css` string, not the blanked copy.
+ *
+ * A selector is the text between a `}` (or the start of the file) and the
+ * next `{`, and may not contain `@` — so an at-rule's own `{` opens no block,
+ * while blocks nested inside it after the first still do.
+ *
+ * Hand-scanned, in one linear pass. This was the regex
+ * `(^|\})\s*([^{}@]+?)\s*\{`, which backtracks polynomially over runs of
+ * whitespace — and blankComments turns every comment into exactly that. On the
+ * 1,400-line style.css it cost 6–12 s of CPU per parse (2026-10-23), paid by
+ * every lint:css gate, and it would have frozen the theme editor on each
+ * slider tick and blown the worker's CPU budget on save.
+ */
+export function readBlocks(css) {
+  const blocks = []
+  const scan = blankComments(css)
+  // Index of the last `{`, `}` or `@` seen; -1 is the start of the file.
+  let delim = -1
+  let i = 0
+
+  while (i < scan.length) {
+    const c = scan[i]
+    if (c === '}' || c === '@') {
+      delim = i
+      i += 1
+      continue
+    }
+    if (c !== '{') {
+      i += 1
+      continue
+    }
+
+    const opensBlock = delim === -1 || scan[delim] === '}'
+    const selector = opensBlock ? scan.slice(delim + 1, i).trim() : ''
+    if (!selector) {
+      delim = i
+      i += 1
+      continue
+    }
+
+    const bodyStart = i + 1
+    let depth = 1
+    let j = bodyStart
+    while (j < scan.length && depth > 0) {
+      if (scan[j] === '{') depth += 1
+      else if (scan[j] === '}') depth -= 1
+      j += 1
+    }
+    blocks.push({ selector, body: css.slice(bodyStart, j - 1), start: bodyStart, end: j - 1 })
+    // Resume AT the closing brace, so it can begin the next selector.
+    i = j - 1
+  }
+  return blocks
+}
+
+/** Which theme names a selector applies to. */
+export function themesForSelector(selector) {
+  const names = []
+  for (const part of selector.split(',')) {
+    const s = part.trim()
+    if (s === ':root') names.push('light')
+    const m = s.match(/^\[data-theme=['"]([^'"]+)['"]\]$/)
+    if (m) names.push(m[1])
+  }
+  return [...new Set(names)]
+}
+
+/** Declarations in a block body, in source order, comments stripped. */
+export function readDeclarations(body) {
+  const clean = body.replace(/\/\*[\s\S]*?\*\//g, '')
+  const decls = []
+  // Custom-property values can contain commas/parens, so scan to the
+  // top-level semicolon rather than splitting naively.
+  const re = /(--[a-z0-9-]+)\s*:/gi
+  let m
+  while ((m = re.exec(clean)) !== null) {
+    let i = re.lastIndex
+    let depth = 0
+    while (i < clean.length) {
+      const c = clean[i]
+      if (c === '(') depth += 1
+      else if (c === ')') depth -= 1
+      else if (c === ';' && depth === 0) break
+      i += 1
+    }
+    decls.push({ name: m[1], value: clean.slice(re.lastIndex, i).trim() })
+    re.lastIndex = i
+  }
+  return decls
+}
+
+/**
+ * Build `{ [theme]: { [tokenName]: value } }` for every color token.
+ * Only `--color-*` is returned; spacing/shadow/advanced tokens are ignored.
+ */
+export function parseThemes(css) {
+  const out = Object.fromEntries(THEMES.map(t => [t, {}]))
+
+  for (const block of readBlocks(css)) {
+    const names = themesForSelector(block.selector)
+    if (!names.length) continue
+    for (const { name, value } of readDeclarations(block.body)) {
+      if (!name.startsWith('--color-')) continue
+      for (const theme of names) {
+        if (out[theme]) out[theme][name] = value
+      }
+    }
+  }
+  return out
+}
+
+/** All distinct `--color-*` names across all themes, sorted. */
+export function allTokenNames(themes) {
+  const set = new Set()
+  for (const tokens of Object.values(themes)) {
+    for (const name of Object.keys(tokens)) set.add(name)
+  }
+  return [...set].sort()
+}