rnwind 0.0.2 → 0.0.3

package/src/core/parser/tokens.ts

@@ -1,4 +1,5 @@
 import type { Token, TokenOrValue } from 'lightningcss'
+import { rgb as culoriRgb } from 'culori'
 import { BARE_NUMBER_REGEX, CALC_MUL_REGEX, CALC_RATIO_REGEX, LENGTH_PX_REGEX, LENGTH_REM_REGEX, REM_TO_PX } from './constants'
 import { cssColorToString } from './color'
 import type { RNStyleValue } from './types'
@@ -244,6 +245,8 @@ export function coerceUnparsedValue(text: string): RNStyleValue | null {
   if (px) return Number(px[1])
   const rem = LENGTH_REM_REGEX.exec(trimmed)
   if (rem) return Number(rem[1]) * REM_TO_PX
+  const colorMix = evaluateColorMixWithTransparent(trimmed)
+  if (colorMix !== null) return colorMix
   const fallback = extractVariableFallback(trimmed)
   if (fallback !== null) return coerceUnparsedValue(fallback)
   const calcRatio = CALC_RATIO_REGEX.exec(trimmed)
@@ -262,7 +265,174 @@ export function coerceUnparsedValue(text: string): RNStyleValue | null {
     const base = Number(calcMul[1]) * Number(calcMul[2])
     return unit === 'rem' ? base * REM_TO_PX : base
   }
-  return trimmed
+  return unquoteCssString(trimmed)
+}
+
+/**
+ * Evaluate the specific `color-mix(in <space>, <color> <pct>%, transparent)`
+ * shape Tailwind v4 emits for opacity-suffixed themed colors (e.g.
+ * `border-text/20`, `bg-on-background/30`). The result is the original
+ * color with `alpha = originalAlpha * pct/100` — no actual color-space
+ * conversion is needed because mixing a color with `transparent` only
+ * changes its alpha, regardless of the named space (oklab / srgb /
+ * lab / …) — the chrominance is preserved.
+ *
+ * Returns null when the expression isn't this shape (handed back to
+ * the caller for the next coercion strategy).
+ * @param text Trimmed CSS value.
+ * @returns RN-compatible `rgba(...)` string, or null when unmatched.
+ */
+function evaluateColorMixWithTransparent(text: string): string | null {
+  const lower = text.toLowerCase()
+  if (!lower.startsWith('color-mix(')) return null
+  // Match the trailing `, transparent)` (allowing optional whitespace).
+  const tail = /,\s*transparent\s*\)\s*$/.exec(text)
+  if (!tail) return null
+  // Skip the `in <space>` clause (everything up to the FIRST comma after
+  // the opening paren). Walking by hand instead of regex because the
+  // color slot may itself contain `(...)` (e.g. `rgb(...)`).
+  const inComma = text.indexOf(',', 'color-mix('.length)
+  if (inComma === -1 || inComma > tail.index) return null
+  const middle = text.slice(inComma + 1, tail.index).trim()
+  // `<color> <pct>%` — the `<num>%` token is at the END of `middle`.
+  // Anchored, no backtracking — explicit `% ` then end.
+  const pctMatch = COLOR_MIX_PCT_TAIL.exec(middle)
+  if (!pctMatch) return null
+  const pct = Number(pctMatch[1]) / 100
+  if (!Number.isFinite(pct)) return null
+  const colorText = middle.slice(0, pctMatch.index).trim()
+  if (colorText.length === 0) return null
+  return applyAlphaToCssColor(colorText, pct)
+}
+
+/** End-anchored `<num>%` matcher used to slice a color-mix percentage off the right of an expression. */
+// eslint-disable-next-line sonarjs/slow-regex -- end-anchored, atomic-style group; bounded backtracking is safe.
+const COLOR_MIX_PCT_TAIL = /(-?\d+(?:\.\d+)?)%$/
+
+/**
+ * Multiply the alpha channel of a serialized CSS color by `multiplier`
+ * (0…1). Recognises `#rgb` / `#rrggbb` / `#rrggbbaa` hex, named colors
+ * (only `transparent` matters here), and `rgb(…)` / `rgba(…)` forms —
+ * which is what theme tokens resolve to after substitution.
+ * @param color CSS color text.
+ * @param multiplier Alpha multiplier (0…1).
+ * @returns `rgba(r, g, b, a)` string with the adjusted alpha.
+ */
+function applyAlphaToCssColor(color: string, multiplier: number): string | null {
+  const trimmed = color.trim()
+  if (trimmed === 'transparent') return 'rgba(0, 0, 0, 0)'
+  return alphaFromHex(trimmed, multiplier) ?? alphaFromRgbFunction(trimmed, multiplier) ?? alphaFromCulori(trimmed, multiplier)
+}
+
+/**
+ * Apply the alpha multiplier to a hex literal, expanding 3/4/6/8-digit forms.
+ * @param text
+ * @param multiplier
+ */
+function alphaFromHex(text: string, multiplier: number): string | null {
+  const hexMatch = /^#([0-9a-fA-F]{3,8})$/.exec(text)
+  if (!hexMatch) return null
+  const expanded = expandHex(hexMatch[1]!)
+  if (!expanded) return null
+  return `rgba(${expanded.r}, ${expanded.g}, ${expanded.b}, ${expanded.alpha * multiplier})`
+}
+
+/**
+ * Apply alpha to an `rgb(…)` / `rgba(…)` literal. Walks the channels by
+ * hand instead of a multi-capture regex (the linter flags the regex
+ * form as backtracking-prone).
+ * @param text
+ * @param multiplier
+ */
+function alphaFromRgbFunction(text: string, multiplier: number): string | null {
+  if (!text.startsWith('rgb(') && !text.startsWith('rgba(')) return null
+  const inner = text.slice(text.indexOf('(') + 1, -1)
+  const channels = inner.split(/\s*[\s,]\s*/).filter((part) => part.length > 0)
+  if (channels.length !== 3 && channels.length !== 4) return null
+  const r = Math.round(Number(channels[0]))
+  const g = Math.round(Number(channels[1]))
+  const b = Math.round(Number(channels[2]))
+  const baseAlpha = channels.length === 4 ? Number(channels[3]) : 1
+  if (![r, g, b, baseAlpha].every((value) => Number.isFinite(value))) return null
+  return `rgba(${r}, ${g}, ${b}, ${baseAlpha * multiplier})`
+}
+
+/**
+ * Fallback for wide-gamut color forms (`oklch`, `oklab`, `lab`, `lch`,
+ * `hsl`, …) — culori parses every CSS color shape and yields RGB. Lets
+ * `color-mix(in oklab, oklch(...) 50%, transparent)` resolve when
+ * Tailwind emits the source color in a wide-gamut space (every
+ * built-in `bg-red-500` / `shadow-red-500` does, in v4).
+ * @param text
+ * @param multiplier
+ */
+function alphaFromCulori(text: string, multiplier: number): string | null {
+  try {
+    const parsed = culoriRgb(text) as { r?: number; g?: number; b?: number; alpha?: number } | undefined
+    if (!parsed) return null
+    if (![parsed.r, parsed.g, parsed.b].every((v) => typeof v === 'number' && Number.isFinite(v))) return null
+    const r = Math.round(Math.max(0, Math.min(1, parsed.r!)) * 255)
+    const g = Math.round(Math.max(0, Math.min(1, parsed.g!)) * 255)
+    const b = Math.round(Math.max(0, Math.min(1, parsed.b!)) * 255)
+    const baseAlpha = typeof parsed.alpha === 'number' ? parsed.alpha : 1
+    return `rgba(${r}, ${g}, ${b}, ${baseAlpha * multiplier})`
+  } catch {
+    // culori threw on an unrecognised CSS form — fall through.
+    return null
+  }
+}
+
+/**
+ * Expand `#rgb` / `#rrggbb` / `#rrggbbaa` hex to its `{r, g, b, alpha}`
+ * components. Returns null when the digit count doesn't match a CSS hex
+ * shape.
+ * @param digits Hex digits without the leading `#`.
+ * @returns Decoded color or null.
+ */
+function expandHex(digits: string): { r: number; g: number; b: number; alpha: number } | null {
+  const {length} = digits
+  if (length === 3 || length === 4) {
+    const r = Number.parseInt(digits[0]! + digits[0]!, 16)
+    const g = Number.parseInt(digits[1]! + digits[1]!, 16)
+    const b = Number.parseInt(digits[2]! + digits[2]!, 16)
+    const alpha = length === 4 ? Number.parseInt(digits[3]! + digits[3]!, 16) / 255 : 1
+    return Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b) ? null : { r, g, b, alpha }
+  }
+  if (length === 6 || length === 8) {
+    const r = Number.parseInt(digits.slice(0, 2), 16)
+    const g = Number.parseInt(digits.slice(2, 4), 16)
+    const b = Number.parseInt(digits.slice(4, 6), 16)
+    const alpha = length === 8 ? Number.parseInt(digits.slice(6, 8), 16) / 255 : 1
+    return Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b) ? null : { r, g, b, alpha }
+  }
+  return null
+}
+
+/**
+ * Strip the matched outer quote characters from a CSS string literal.
+ * `--font-sans: 'Inter-Medium'` flows through `var(--font-sans)`
+ * substitution as the raw value text — quotes included. Without this
+ * step `fontFamily` lands on the RN style as `"'Inter-Medium'"` (with
+ * literal quote characters), which RN can't match against the registered
+ * native font and silently falls back to the system face.
+ *
+ * Only strips when both ends agree (`'…'` or `"…"`) and there are no
+ * other top-level quote chars — keeps multi-segment fallbacks like
+ * `'Inter', sans-serif` untouched (those get split downstream).
+ * @param text Trimmed CSS value.
+ * @returns Same text with outer matching quotes removed, or unchanged.
+ */
+function unquoteCssString(text: string): string {
+  if (text.length < 2) return text
+  const first = text.codePointAt(0)
+  const last = text.codePointAt(text.length - 1)
+  if (first === undefined || first !== last) return text
+  if (first !== 34 && first !== 39) return text // " or '
+  const inner = text.slice(1, -1)
+  // Don't unquote when the inner string itself contains an unescaped
+  // matching quote — that means we'd be merging two adjacent literals.
+  if (inner.includes(text[0]!)) return text
+  return inner
 }
 
 /**

package/src/core/parser/tw-parser.ts

@@ -8,7 +8,14 @@ import { detectHapticAtom, type HapticRequest } from './haptics'
 import { keyframeSelectorOffset, keyframesName, pickAnimationName } from './keyframes'
 import { serializeInitialValue } from './property'
 import { classNameFromSelector } from './selector'
-import { BASE_SCHEME, compileReadyTheme, extractSchemeAliases, extractThemeVars, type ThemeSchemeTable } from './theme-vars'
+import {
+  BASE_SCHEME,
+  compileReadyTheme,
+  extractCustomVariantSchemes,
+  extractSchemeAliases,
+  extractThemeVars,
+  type ThemeSchemeTable,
+} from './theme-vars'
 import { serializeTokens } from './tokens'
 import type { RNStyle } from './types'
 import type { Declaration as LcDeclaration, TokenOrValue } from 'lightningcss'
@@ -34,14 +41,18 @@ const DEFAULT_TRANSFORM_OPTIONS: Partial<TransformOptions<never>> = {
   },
   include: Features.Nesting | Features.MediaQueries,
   exclude: Features.LogicalProperties | Features.DirSelector | Features.LightDark,
-  targets: {
-    // eslint-disable-next-line sonarjs/no-identical-expressions
-    safari: (16 << 16) | (4 << 8),
-    // eslint-disable-next-line camelcase, sonarjs/no-identical-expressions
-    ios_saf: (16 << 16) | (4 << 8),
-    firefox: 128 << 16,
-    chrome: 111 << 16,
-  },
+  // NOTE: deliberately no `targets`. With targets that include
+  // color-mix-supporting browsers (Safari 16.4+, Chrome 111+, …),
+  // lightningcss EVALUATES `color-mix(in oklab, var(--theme-color)
+  // <pct>%, transparent)` at parse time using whichever value of
+  // `--theme-color` it sees first in the cascade. Tailwind v4 emits
+  // exactly this shape for `<prop>-<themed>/<N>` utilities (e.g.
+  // `border-text/20`), so the resulting RGB color is locked to ONE
+  // scheme — every variant gets the same value. By dropping targets,
+  // lightningcss leaves color-mix as an unparsed function and our
+  // per-scheme `unparsedToEntries` substitution path runs instead,
+  // producing the right rgba(...) for each scheme. Targets in this
+  // pipeline are otherwise unused — we never re-emit CSS from the AST.
 }
 /** Parser configuration — one instance per Metro session, theme CSS fixed. */
 export interface TailwindParserConfig {
@@ -164,6 +175,13 @@ export class TailwindParser {
   private compiler: TailwindCompiler | undefined
   private readonly themeSchemes: ThemeSchemeTable
   private readonly schemeAliases: ReadonlyMap<string, string>
+  /**
+   * Scheme names declared via `@custom-variant <name> …;`. A scheme
+   * listed here but absent from {@link themeSchemes} (no `@variant`
+   * override block) draws its values from the base `@theme` — the
+   * standard Tailwind v4 "light defaults + dark override" shape.
+   */
+  private readonly customVariantSchemes: readonly string[]
   /**
    * Memoise `resolveCandidates` results by candidate-list fingerprint.
    * Fast Refresh hits this on every save: oxide's scan is cheap, but
@@ -187,20 +205,41 @@ export class TailwindParser {
   constructor(private readonly config: TailwindParserConfig) {
     this.themeSchemes = extractThemeVars(config.themeCss)
     this.schemeAliases = extractSchemeAliases(config.themeCss)
+    this.customVariantSchemes = extractCustomVariantSchemes(config.themeCss)
     this.scanner = new Scanner({ sources: config.sources ? [...config.sources] : [] })
   }
 
   /**
-   * Schemes declared by the user — either every `@variant <name>` block
-   * found (in declaration order) or just `['base']` for themes without
-   * any variants. Used to decide how many per-scheme buckets the
-   * per-atom resolver fills. Exposed publicly so Metro integration can
-   * hand the names to the `.d.ts` generator without a full parse.
+   * Schemes declared by the user — the union of every `@custom-variant
+   * <name>` declaration and every `@variant <name>` block, or just
+   * `['base']` for themes without any. Used to decide how many
+   * per-scheme buckets the per-atom resolver fills. Exposed publicly so
+   * Metro integration can hand the names to the `.d.ts` generator
+   * without a full parse.
+   *
+   * Both sources matter. `@variant` blocks alone miss the common
+   * Tailwind v4 shape where the light palette sits in the base `@theme`
+   * and only `@variant dark` overrides it: there `light` exists solely
+   * as a `@custom-variant` and would otherwise be dropped, collapsing
+   * every themed atom to a single bucket that can't switch.
+   * `@custom-variant` order wins (it's where users enumerate their
+   * schemes); any `@variant`-only scheme is appended after.
    * @returns Scheme names.
    */
   public get declaredSchemes(): readonly string[] {
-    const variants = [...this.themeSchemes.keys()].filter((name) => name !== BASE_SCHEME)
-    return variants.length > 0 ? variants : [BASE_SCHEME]
+    const ordered: string[] = []
+    const seen = new Set<string>()
+    for (const name of this.customVariantSchemes) {
+      if (seen.has(name)) continue
+      seen.add(name)
+      ordered.push(name)
+    }
+    for (const name of this.themeSchemes.keys()) {
+      if (name === BASE_SCHEME || seen.has(name)) continue
+      seen.add(name)
+      ordered.push(name)
+    }
+    return ordered.length > 0 ? ordered : [BASE_SCHEME]
   }
 
   /**
@@ -291,6 +330,19 @@ export class TailwindParser {
     } catch (error) {
       throw wrapThemeError(error)
     }
+    // Tailwind v4 emits opacity-suffixed themed colors as a pre-resolved
+    // sRGB fallback PLUS a `@supports`-gated var()-based override:
+    //   border-color: color-mix(in srgb, #0A0A0A 20%, transparent);
+    //   @supports (color: color-mix(in lab, red, red)) {
+    //     border-color: color-mix(in oklab, var(--color-text) 20%, transparent);
+    //   }
+    // Lightningcss takes the OUTER fallback (locked to whichever scheme
+    // the compiler resolved first), and our per-scheme substitution
+    // never gets a chance. Unwrap the @supports so the var()-based
+    // declaration overrides the fallback in the same rule — lightningcss
+    // emits the override as `unparsed` and the parser's themeVars-aware
+    // path produces correct rgba per scheme.
+    css = unwrapColorMixSupports(css)
     // `compiler.build(candidates)` memoizes across calls — it returns CSS for
     // every candidate the compiler has EVER seen in this process. To keep
     // parser output pure per-call we restrict outputs to this call's
@@ -1068,20 +1120,24 @@ function parseFirstShadow(raw: string): ParsedShadow | null {
  * @returns Pixel lengths + the remainder text (color expression).
  */
 function extractShadowLengths(head: string): { lengths: number[]; remainder: string } {
-  const lengthRegex = /(?<![A-Za-z(])-?\d*\.?\d+(?:px|rem|em|%)?/g
+  // Take ONLY the leading run of length tokens, stopping at the first
+  // non-length token (the color). A previous global digit-regex scanned
+  // the whole string, so a <4-length shadow like `0 1px 1px rgb(0 0 0 /
+  // 0.05)` stole a digit out of the color expression — corrupting the
+  // alpha (opacity) or a digit-leading hex. Whitespace-splitting can't
+  // reach inside the color because we break as soon as a token isn't a
+  // bare/`px`/`rem`/`em`/`%` length.
+  // Unambiguous integer-or-decimal (no `\d*\.?\d+` overlap) so there's no
+  // super-linear backtracking on long digit runs.
+  const isLength = /^-?(?:\d+(?:\.\d+)?|\.\d+)(?:px|rem|em|%)?$/
+  const parts = head.split(/\s+/)
   const lengths: number[] = []
-  const matches: { text: string; index: number }[] = []
-  let next: RegExpExecArray | null = lengthRegex.exec(head)
-  while (next !== null && lengths.length < 4) {
-    matches.push({ text: next[0], index: next.index })
-    lengths.push(parseLengthToken(next[0]))
-    next = lengthRegex.exec(head)
-  }
-  let remainder = head
-  for (const { text, index } of matches.toReversed()) {
-    remainder = `${remainder.slice(0, index)}${remainder.slice(index + text.length)}`
+  let index = 0
+  while (index < parts.length && lengths.length < 4 && isLength.test(parts[index]!)) {
+    lengths.push(parseLengthToken(parts[index]!))
+    index += 1
   }
-  return { lengths, remainder }
+  return { lengths, remainder: parts.slice(index).join(' ') }
 }
 
 /**
@@ -1618,6 +1674,69 @@ function resolveAngleExpression(text: string): string | null {
  * @param css Tailwind's compiled CSS.
  * @returns Map of custom-property name → resolved value.
  */
+/**
+ * Strip `\@supports (color: color-mix(in lab, red, red)) { … }` wrappers
+ * from Tailwind v4's compiled CSS, hoisting their inner declarations up
+ * to the parent rule.
+ *
+ * Tailwind emits opacity-suffixed themed colors with both a pre-resolved
+ * sRGB fallback AND a var()-based override gated behind the color-mix
+ * `\@supports` clause. The OUTER fallback hard-codes a single scheme's
+ * value of the theme token; the inner override is var()-based and
+ * substitutes correctly per scheme. By unwrapping the gate, the inner
+ * declaration becomes a sibling of the fallback in the same rule body —
+ * lightningcss takes the LATER one (the var()-based unparsed form), and
+ * the parser's themeVars-aware path produces correct rgba per scheme.
+ * Modern RN-targeted browsers all support color-mix anyway, so dropping
+ * the gating is safe.
+ * @param css Tailwind-compiled CSS.
+ * @returns CSS with the color-mix support gates unwrapped.
+ */
+function unwrapColorMixSupports(css: string): string {
+  const guard = '@supports (color: color-mix(in lab, red, red))'
+  let out = ''
+  let cursor = 0
+  while (cursor < css.length) {
+    const head = css.indexOf(guard, cursor)
+    if (head === -1) {
+      out += css.slice(cursor)
+      break
+    }
+    out += css.slice(cursor, head)
+    const brace = css.indexOf('{', head)
+    if (brace === -1) {
+      out += css.slice(head)
+      break
+    }
+    const blockEnd = findMatchingClose(css, brace + 1)
+    if (blockEnd === -1) {
+      out += css.slice(head)
+      break
+    }
+    const inner = css.slice(brace + 1, blockEnd)
+    // Only unwrap when the gated declaration substitutes a USER theme
+    // token (`var(--color-…)`). Tailwind also gates `--tw-*` internal
+    // composers (shadow color, ring color, …) on the same supports
+    // clause; their outer fallback is the optimized hex/oklch value
+    // the parser's own composed-prop pass needs (`applyComposedShadow`
+    // reads `--tw-shadow-color` from the rule's local vars). Unwrapping
+    // them would replace the resolvable color with an unresolvable
+    // `color-mix(... var(--tw-shadow-alpha), transparent)` text and
+    // break the composed-shadow path.
+    // Keep the gate intact for non-themed colors — the outer fallback
+    // wins, which is what Tailwind intended.
+    out += inner.includes('var(--color-') ? inner : css.slice(head, blockEnd + 1)
+    cursor = blockEnd + 1
+  }
+  return out
+}
+
+/**
+ * Extract every `--name: value` declaration from the `:root` blocks in
+ * Tailwind's compiled CSS into a flat map.
+ * @param css Tailwind-compiled CSS.
+ * @returns Map of custom-property name → resolved value.
+ */
 function extractRootCustomProperties(css: string): Map<string, string> {
   const out = new Map<string, string>()
   let cursor = 0

package/src/core/parser/typography-dispatcher.ts

@@ -48,6 +48,20 @@ function letterSpacingToEntries(value: LcDeclaration['value']): readonly RNEntry
   return [['letterSpacing', unit === 'px' ? px : px * 16]]
 }
 
+/**
+ * Lower a CSS `text-align` keyword to one RN's `textAlign` accepts. RN
+ * has no logical `start`/`end`, so map them to physical sides (LTR
+ * default); every other keyword (left/right/center/justify/auto) is
+ * already valid and passes through.
+ * @param align CSS text-align keyword.
+ * @returns RN-valid textAlign keyword.
+ */
+function physicalTextAlign(align: string): string {
+  if (align === 'start') return 'left'
+  if (align === 'end') return 'right'
+  return align
+}
+
 /**
  * Dispatch typography declarations rnwind cares about (text-align,
  * text-transform, text-decoration-line, line-height, letter-spacing,
@@ -59,7 +73,7 @@ function letterSpacingToEntries(value: LcDeclaration['value']): readonly RNEntry
 export function dispatchTypographyDeclaration(decl: LcDeclaration): readonly RNEntry[] | null {
   switch (decl.property) {
     case 'text-align': {
-      return [['textAlign', decl.value]]
+      return [['textAlign', physicalTextAlign(String(decl.value))]]
     }
     case 'text-transform': {
       return [['textTransform', decl.value.case ?? 'none']]

package/src/core/style-builder/build-style.ts

@@ -309,25 +309,84 @@ export interface AtomSerializedEntry {
 export type AtomSerializedCache = Map<string, AtomSerializedEntry>
 
 /**
- * Serialize one atom's canonical + variant-diff entries, honouring
- * the per-atom cache. Returns the number of cache MISSES this atom
- * incurred (0 when canonical was cached AND every needed variant was
- * cached; 1 when anything had to be re-stringified). Split out of
- * `buildSchemeSources` to keep that function under the repo's cognitive
- * complexity budget.
+ * Pre-serialize every non-empty variant value, reusing the per-atom
+ * cache where present. Result drives both the scheme-uniform check
+ * AND the per-variant emission loop downstream.
+ * @param atom Atom name.
+ * @param schemed Parser-produced schemed bucket.
+ * @param variants Variant scheme names in deterministic order.
+ * @param keyframes Keyframes available to inline.
+ * @param cached Cached entry for this atom (when ref-stable).
+ * @returns variantName → serialized text.
+ */
+function buildVariantTexts(
+  atom: string,
+  schemed: SchemedStyle,
+  variants: readonly string[],
+  keyframes: ReadonlyMap<string, KeyframeBlock>,
+  cached: AtomSerializedEntry | undefined,
+): Map<string, string> {
+  const out = new Map<string, string>()
+  for (const variant of variants) {
+    const own = (schemed as Readonly<Record<string, RNStyle>>)[variant]
+    if (!isNonEmptyStyle(own)) continue
+    const text = cached?.variants.get(variant) ?? prepareAtomValue(atom, own, keyframes)
+    out.set(variant, text)
+  }
+  return out
+}
+
+/**
+ * Decide whether a (no-base) atom should be promoted to common because
+ * every declared variant resolves to the same value. This is the
+ * scheme-uniform case: `flex`, `p-4`, `absolute` all carry no theme
+ * variables, so Phase-1 fills every variant bucket identically and
+ * leaves `base` empty — without this collapse they'd be duplicated
+ * across every scheme file.
+ *
+ * The variant-prefix check is what keeps a real scheme-gated atom
+ * (`dark:bg-indigo-800`) out of common in a single-variant project
+ * (where its 1 bucket would otherwise look "uniform" by definition).
+ * @param atom Atom name (checked for `<variant>:` prefix).
+ * @param variants Declared variant scheme names.
+ * @param variantTexts Serialized variant values.
+ * @param canonicalText Serialized canonical (common) value.
+ * @returns Whether the atom is uniform across every declared variant.
+ */
+function isSchemeUniform(
+  atom: string,
+  variants: readonly string[],
+  variantTexts: ReadonlyMap<string, string>,
+  canonicalText: string,
+): boolean {
+  if (variants.length === 0 || variantTexts.size !== variants.length) return false
+  if (variants.some((variant) => atom.startsWith(`${variant}:`))) return false
+  for (const text of variantTexts.values()) {
+    if (text !== canonicalText) return false
+  }
+  return true
+}
+
+/**
+ * Serialize one atom's canonical + variant-diff entries, honouring the
+ * per-atom cache. Returns the number of cache MISSES this atom incurred
+ * (0 when canonical was cached AND every needed variant was cached;
+ * 1 when anything had to be re-stringified).
  *
- * Two paths gated on whether the parser produced a non-empty `base`
- * bucket:
+ * Three paths gated on whether the parser produced a non-empty `base`
+ * bucket and whether the variants converge:
  *  - **Themed atom (base present)**: canonical goes to `common`, each
  *    variant whose own value diverges from canonical writes the diff
- *    into its own scheme file. `lookupAtom` then finds the variant's
+ *    into its own scheme file. `lookupAtom` finds the variant's
  *    override or falls through to common.
- *  - **Scheme-gated atom (base empty)**: the atom only matches when a
- *    specific scheme is active (Tailwind `light:` / `dark:` / `brand:`
- *    selectors). Skipping `common` here is essential — registering it
- *    would let the lookup fall through under non-matching schemes and
- *    leak the variant style into every scheme. Each populated variant
- *    bucket writes the value into its own scheme file directly.
+ *  - **Scheme-uniform atom (base empty, every variant identical)**:
+ *    promoted to `common` once — the parser's Phase-1 fills every
+ *    variant bucket with the same value for utilities like `flex` /
+ *    `p-4` / `absolute` that don't reference theme variables.
+ *  - **Scheme-gated atom (base empty, prefixed name like `dark:foo`,
+ *    or variants diverge)**: each populated variant writes the value
+ *    into its own scheme file directly; common stays empty so the
+ *    runtime fallback can't leak the variant style into other schemes.
  * @param atom Atom name.
  * @param schemed Parser-produced schemed bucket for the atom.
  * @param canonical Canonical RN style for `common`.
@@ -351,23 +410,22 @@ function collectAtomEntries(
   const cached = cache?.get(atom)
   const hit = cached?.styleRef === schemed
   const baseEntry = (schemed as Readonly<Record<string, RNStyle>>)[BASE_SCHEME]
-  const isSchemeGated = !isNonEmptyStyle(baseEntry)
+  const hasBase = isNonEmptyStyle(baseEntry)
   const canonicalText = hit ? cached.canonical : prepareAtomValue(atom, canonical, keyframes)
-  if (!isSchemeGated) commonEntries.push([atom, canonicalText])
+  const variantTexts = buildVariantTexts(atom, schemed, variants, keyframes, hit ? cached : undefined)
+  const goesToCommon = hasBase || isSchemeUniform(atom, variants, variantTexts, canonicalText)
+
+  if (goesToCommon) commonEntries.push([atom, canonicalText])
+
   const entry: AtomSerializedEntry = hit
     ? cached
-    : { styleRef: schemed, canonical: canonicalText, variants: new Map<string, string>() }
+    : { styleRef: schemed, canonical: canonicalText, variants: new Map(variantTexts) }
   if (!hit) cache?.set(atom, entry)
 
   for (const variant of variants) {
-    const own = (schemed as Readonly<Record<string, RNStyle>>)[variant]
-    if (!isNonEmptyStyle(own)) continue
-    let ownText = entry.variants.get(variant)
-    if (ownText === undefined) {
-      ownText = prepareAtomValue(atom, own, keyframes)
-      entry.variants.set(variant, ownText)
-    }
-    if (!isSchemeGated && ownText === canonicalText) continue
+    const ownText = variantTexts.get(variant)
+    if (ownText === undefined) continue
+    if (goesToCommon && ownText === canonicalText) continue
     variantEntries[variant].push([atom, ownText])
   }
   return hit ? 0 : 1