rnwind 0.0.1 → 0.0.2

package/src/core/parser/theme-vars.ts

@@ -0,0 +1,412 @@
+/**
+ * Lightweight extractor for user-declared `@theme` and `@variant` blocks
+ * inside `:root` / `@layer theme`. Used by the parser to resolve
+ * `var(--x)` references that Tailwind's `theme(inline)` leaves
+ * unresolved (it only inlines its own known tokens, not user-added ones).
+ *
+ * Kept regex-free — a linear paren-balanced scan handles nesting without
+ * the backtracking risks of `{[^}]*}` patterns. CSS comment blocks are
+ * stripped before scanning so slash-star-sequences inside declaration
+ * values don't confuse the parser.
+ */
+
+/**
+ * `@custom-variant <name> ...content-up-to-semicolon...;`
+ * The `[^;]+` class is constant-width relative to its input (one char
+ * per step, no alternation backtracking), so sonarjs/slow-regex doesn't
+ * apply — the flagged pattern is a false positive.
+ */
+// eslint-disable-next-line sonarjs/slow-regex
+const CUSTOM_VARIANT_WITH_SELECTOR = /@custom-variant\s+([A-Za-z][A-Za-z0-9_-]*)\s+([^;]+);/g
+/** Bare `.classname` occurrences (one capture group per class). */
+const CLASS_IN_SELECTOR = /\.([A-Za-z_][\w-]*)/g
+
+/**
+ * One iteration step of the block walker — decides whether the next
+ * interesting token is a declaration, a nested block, or the end of
+ * scope. Kept small to keep {@link walkBlocks} below the cognitive
+ * complexity threshold.
+ */
+interface WalkStep {
+  /** Next scan index, or `-1` to terminate the outer loop. */
+  next: number
+}
+
+/**
+ * Recursively descend into `{ ... }` blocks, collecting `--x: y;`
+ * declarations under the active scheme. When we hit `@variant <name> {`,
+ * the child scope's scheme becomes `<name>` until that block closes.
+ * @param source Pre-stripped CSS source.
+ * @param start Start index of the block body (0 for top-level).
+ * @param scheme Active scheme name for declarations inside this scope.
+ * @param table Destination table, mutated in place.
+ */
+function walkBlocks(source: string, start: number, scheme: string, table: ThemeSchemeTable): void {
+  let index = start
+  while (index < source.length) {
+    const step = nextWalkStep(source, index, scheme, table)
+    if (step.next === -1) return
+    index = step.next
+  }
+}
+
+/**
+ * Decide the next action at `index`: declaration, nested block, or EOF.
+ * @param source Pre-stripped CSS.
+ * @param index Current scan index.
+ * @param scheme Active scheme name.
+ * @param table Destination table.
+ * @returns Step descriptor with the next scan index (or -1 for EOF).
+ */
+function nextWalkStep(source: string, index: number, scheme: string, table: ThemeSchemeTable): WalkStep {
+  // Find the next TOP-LEVEL `--` (outside any `( ... )`). That's the only
+  // place a custom-property declaration can start. `--foo` that appears
+  // inside `var(--foo)` or `calc(... --value(integer) ...)` is part of a
+  // value, not a new declaration — accidentally treating it as one would
+  // splice into the `@theme` block's declaration list and produce broken
+  // CSS that Tailwind rejects downstream.
+  const atIndex = findTopLevelDoubleDash(source, index)
+  const openIndex = source.indexOf('{', index)
+  const closeIndex = source.indexOf('}', index)
+  const blockClose = closeIndex === -1 ? Number.POSITIVE_INFINITY : closeIndex
+  if (isDeclarationNext(atIndex, openIndex, blockClose)) {
+    return { next: consumeDeclaration(source, atIndex, scheme, table) }
+  }
+  if (openIndex !== -1 && openIndex < blockClose) {
+    return { next: enterBlock(source, index, openIndex, scheme, table) }
+  }
+  return { next: -1 }
+}
+
+/**
+ * Find the next `--` in `source` that's not inside a `( ... )` group.
+ * Stops early if we hit an unmatched `}` (end of the containing block)
+ * — a `--` inside a nested block isn't our concern either.
+ * @param source Pre-stripped CSS source.
+ * @param from Start index to scan from.
+ * @returns Index of the next top-level `--`, or `-1` when none.
+ */
+function findTopLevelDoubleDash(source: string, from: number): number {
+  let parenDepth = 0
+  for (let index = from; index < source.length - 1; index += 1) {
+    const ch = source.codePointAt(index)
+    if (ch === 40 /* ( */) {
+      parenDepth += 1
+      continue
+    }
+    if (ch === 41 /* ) */) {
+      if (parenDepth > 0) parenDepth -= 1
+      continue
+    }
+    if (ch === 125 /* } */ && parenDepth === 0) return -1
+    if (ch === 45 /* - */ && parenDepth === 0 && source.codePointAt(index + 1) === 45) {
+      return index
+    }
+  }
+  return -1
+}
+
+/**
+ * Whether the next action at the current scan position is a declaration.
+ * @param atIndex Index of the next `--`.
+ * @param openIndex Index of the next `{`.
+ * @param blockClose Index of the next `}` (or `+Infinity` when absent).
+ * @returns True when a declaration should be consumed next.
+ */
+function isDeclarationNext(atIndex: number, openIndex: number, blockClose: number): boolean {
+  if (atIndex === -1 || atIndex >= blockClose) return false
+  return openIndex === -1 || atIndex < openIndex
+}
+
+/**
+ * Handle a nested `{ ... }` block: recurse with the right scheme, then
+ * skip past the matching closing brace.
+ * @param source Pre-stripped CSS.
+ * @param index Scan position at the start of the header.
+ * @param openIndex Index of the opening brace.
+ * @param scheme Scheme active in the parent scope.
+ * @param table Destination table.
+ * @returns Index past the matching closing brace.
+ */
+function enterBlock(source: string, index: number, openIndex: number, scheme: string, table: ThemeSchemeTable): number {
+  const header = source.slice(index, openIndex).trim()
+  // Skip blocks that define utilities / at-rules that carry declarations
+  // meant for a downstream compiler, not custom-property values for the
+  // active theme scheme. `@utility name-*` bodies contain Tailwind v4's
+  // `--value(...)` meta-syntax which would otherwise confuse the
+  // top-level declaration walker and spill into the extracted theme.
+  if (isNonThemeAtRule(header)) return skipMatchingBrace(source, openIndex + 1)
+  const childScheme = variantNameOf(header) ?? scheme
+  walkBlocks(source, openIndex + 1, childScheme, table)
+  return skipMatchingBrace(source, openIndex + 1)
+}
+
+/**
+ * Whether a block header belongs to an at-rule whose body should be
+ * ignored by the theme-var extractor. `@utility` / `@media` / `@keyframes`
+ * / `@supports` / `@container` bodies contain property declarations that
+ * are NOT custom-property definitions for the active theme.
+ * @param header Text between the outer statement and the opening brace.
+ * @returns `true` when the block body should be skipped.
+ */
+function isNonThemeAtRule(header: string): boolean {
+  const trimmed = header.trimStart()
+  if (!trimmed.startsWith('@')) return false
+  const match = /^@([A-Za-z-]+)/.exec(trimmed)
+  if (!match) return false
+  const name = match[1]!
+  return name === 'utility' || name === 'keyframes' || name === 'media' || name === 'supports' || name === 'container'
+}
+
+/**
+ * Consume one `--name: value;` declaration starting at `start`. Commits
+ * the name/value pair into the active scheme's map and returns the index
+ * just past the terminating `;`.
+ * @param source CSS source.
+ * @param start Index of the `--`.
+ * @param scheme Active scheme.
+ * @param table Destination table.
+ * @returns Next scan index.
+ */
+function consumeDeclaration(source: string, start: number, scheme: string, table: ThemeSchemeTable): number {
+  const colon = source.indexOf(':', start)
+  if (colon === -1) return source.length
+  const name = source.slice(start, colon).trim()
+  const end = source.indexOf(';', colon)
+  const stop = end === -1 ? source.indexOf('}', colon) : end
+  if (stop === -1) return source.length
+  const value = source.slice(colon + 1, stop).trim()
+  if (name.startsWith('--')) {
+    const bucket = table.get(scheme) ?? new Map()
+    bucket.set(name, value)
+    table.set(scheme, bucket)
+  }
+  return stop + 1
+}
+
+/**
+ * Walk forward through the source tracking brace depth; return the index
+ * just past the matching `}` for the opener at `start - 1`.
+ * @param source CSS source.
+ * @param start Index just past the opening brace.
+ * @returns Index past the matching closer (or source.length on imbalance).
+ */
+function skipMatchingBrace(source: string, start: number): number {
+  let depth = 1
+  for (let index = start; index < source.length; index += 1) {
+    const ch = source[index]
+    if (ch === '{') depth += 1
+    else if (ch === '}') {
+      depth -= 1
+      if (depth === 0) return index + 1
+    }
+  }
+  return source.length
+}
+
+/**
+ * If `header` text (right before an opening brace) names a variant
+ * (`@variant <name>`), return that name. Otherwise null.
+ * @param header Text between the previous statement and the next `{`.
+ * @returns Variant name, or null when this block isn't a `@variant`.
+ */
+function variantNameOf(header: string): string | null {
+  const match = /^@variant\s+([A-Za-z][A-Za-z0-9_-]*)/.exec(header)
+  if (!match) return null
+  return match[1] ?? null
+}
+
+/**
+ * Emit `@custom-variant` declarations for every scheme the user declared
+ * but hasn't manually registered. Makes Tailwind accept `light:*` /
+ * `dark:*` / etc. as valid class-name prefixes.
+ * @param css Stripped CSS source used to detect already-declared variants.
+ * @param schemes Non-base scheme names from the extracted table.
+ * @returns Zero or more `@custom-variant ... ;` lines.
+ */
+function buildCustomVariantDeclarations(css: string, schemes: readonly string[]): string[] {
+  if (schemes.length === 0) return []
+  const existing = new Set<string>()
+  for (const match of css.matchAll(CUSTOM_VARIANT_REGEX)) existing.add(match[1]!)
+  const out: string[] = []
+  for (const name of schemes) {
+    if (!existing.has(name)) out.push(`@custom-variant ${name} (&:where(.${name}, .${name} *));`)
+  }
+  return out
+}
+
+/**
+ * Re-publish variant-scoped tokens into a flat theme block so Tailwind
+ * sees every custom-property name it needs. Values come from the base
+ * scheme first, with the FIRST declared non-base scheme layering on top
+ * — Tailwind only cares about token shape (color vs length), not the
+ * exact value, since rnwind does per-scheme substitution at walk time.
+ * @param table Extracted scheme → var-name → value table.
+ * @param schemes Non-base scheme names (sorted by declaration order).
+ * @returns A single `@theme { ... }` block or `null` when there are no tokens.
+ */
+function buildUnifiedThemeBlock(table: ThemeSchemeTable, schemes: readonly string[]): string | null {
+  const unifiedVars = new Map<string, string>()
+  const baseTokens = table.get(BASE_SCHEME)
+  if (baseTokens) for (const [k, v] of baseTokens) unifiedVars.set(k, v)
+  if (schemes.length > 0) {
+    const firstTokens = table.get(schemes[0]!)
+    if (firstTokens) for (const [k, v] of firstTokens) unifiedVars.set(k, v)
+  }
+  if (unifiedVars.size === 0) return null
+  const decls = [...unifiedVars].map(([name, value]) => `  ${name}: ${value};`).join('\n')
+  return `@theme {\n${decls}\n}`
+}
+
+const CUSTOM_VARIANT_REGEX = /@custom-variant\s+([A-Za-z][A-Za-z0-9_-]*)\b/g
+const VARIANT_OPEN_REGEX = /@variant\s+[A-Za-z0-9_-]+\s*\{/g
+
+/**
+ * Strip every `@variant <name> { ... }` block (including nested braces)
+ * from a CSS source.
+ * @param css Raw CSS.
+ * @returns CSS without variant blocks.
+ */
+function stripVariantBlocks(css: string): string {
+  let out = ''
+  let cursor = 0
+  VARIANT_OPEN_REGEX.lastIndex = 0
+  let match: RegExpExecArray | null
+  while ((match = VARIANT_OPEN_REGEX.exec(css)) !== null) {
+    const openEnd = match.index + match[0].length
+    const closeIndex = findMatchingBrace(css, openEnd)
+    if (closeIndex === -1) break
+    out += css.slice(cursor, match.index)
+    cursor = closeIndex + 1
+    VARIANT_OPEN_REGEX.lastIndex = cursor
+  }
+  out += css.slice(cursor)
+  return out
+}
+
+/**
+ * Walk forward from `start` tracking brace depth; return the index of the
+ * matching `}` for the opener just before `start`.
+ * @param source Source string.
+ * @param start Index just past the opening `{`.
+ * @returns Index of matching `}`, or `-1` on imbalance.
+ */
+function findMatchingBrace(source: string, start: number): number {
+  let depth = 1
+  for (let index = start; index < source.length; index += 1) {
+    const ch = source[index]
+    if (ch === '{') depth += 1
+    else if (ch === '}') {
+      depth -= 1
+      if (depth === 0) return index
+    }
+  }
+  return -1
+}
+
+/**
+ * Drop CSS comment blocks from a source. Keeps the token-declaration
+ * scanner simple — comments can contain braces / `--` sequences that
+ * would otherwise fool it.
+ * @param css Raw CSS source.
+ * @returns Source with every comment block removed.
+ */
+function stripComments(css: string): string {
+  let out = ''
+  let index = 0
+  while (index < css.length) {
+    const open = css.indexOf('/*', index)
+    if (open === -1) {
+      out += css.slice(index)
+      break
+    }
+    out += css.slice(index, open)
+    const close = css.indexOf('*/', open + 2)
+    if (close === -1) break
+    index = close + 2
+  }
+  return out
+}
+
+/** Scheme name → (var name → value). The base scheme key is `'base'`. */
+export type ThemeSchemeTable = Map<string, Map<string, string>>
+
+/** Synthetic scheme name used for tokens declared outside any `@variant`. */
+export const BASE_SCHEME = 'base'
+
+/**
+ * Extract user-declared theme tokens from a CSS source. Scans for:
+ *  - classic v4 `@theme` blocks (`@theme { --x: y; ... }`)
+ *  - `@variant <name> { --x: y; ... }` inside any surrounding block
+ *
+ * Both flavors contribute to the returned table: vars outside any
+ * `@variant` go under `'base'`; vars inside `@variant <name>` go under
+ * `<name>`.
+ *
+ * Not a full CSS parser — just enough to recognise the token-declaration
+ * shape Tailwind v4 users actually write.
+ * @param css Theme CSS source.
+ * @returns Scheme → var-name → value map.
+ */
+export function extractThemeVars(css: string): ThemeSchemeTable {
+  const table: ThemeSchemeTable = new Map()
+  const stripped = stripComments(css)
+  walkBlocks(stripped, 0, BASE_SCHEME, table)
+  return table
+}
+
+/**
+ * Build a `<class-in-selector> → <scheme-name>` alias map from any
+ * `@custom-variant <name> (<selector>);` declarations in the theme CSS.
+ *
+ * Tailwind compiles `dark:opacity-100` to a nested rule whose selector is
+ * the user's declared variant selector. When the user writes
+ * `@custom-variant dark (&:where(.scheme-dark, .scheme-dark *));`, the
+ * generated rule references `.scheme-dark` instead of the literal `.dark`
+ * class rnwind's selector matcher defaults to. This alias map lets the
+ * parser map those custom selector classes back to their scheme name.
+ * @param css Theme CSS source.
+ * @returns Class-name → scheme-name map. Empty when no `@custom-variant`
+ *   declarations are present (rnwind's auto-generated defaults already
+ *   use the literal scheme name and don't need an alias).
+ */
+export function extractSchemeAliases(css: string): Map<string, string> {
+  const aliases = new Map<string, string>()
+  const stripped = stripComments(css)
+  for (const match of stripped.matchAll(CUSTOM_VARIANT_WITH_SELECTOR)) {
+    const schemeName = match[1]!
+    const selectorBody = match[2]!
+    for (const cls of selectorBody.matchAll(CLASS_IN_SELECTOR)) {
+      const className = cls[1]!
+      if (className === schemeName) continue
+      aliases.set(className, schemeName)
+    }
+  }
+  return aliases
+}
+
+/**
+ * Rewrite the theme CSS so Tailwind's compiler accepts it:
+ *  1. Strip every `@variant <name> { ... }` block — Tailwind rejects
+ *     them inline because `@variant` is a rnwind concept, not a Tailwind
+ *     at-rule. The scheme-scoped vars are preserved in the extracted
+ *     {@link ThemeSchemeTable} and substituted at walk time.
+ *  2. Prepend `@custom-variant <name> (&:where(.<name>, .<name> *));`
+ *     for every scheme name we saw, so Tailwind accepts `light:bg-*`,
+ *     `dark:bg-*`, etc. as valid class-name prefixes without the user
+ *     having to duplicate the variant declaration.
+ * @param css Theme CSS source.
+ * @param table Scheme → var-name → value table from {@link extractThemeVars}.
+ * @returns CSS ready to feed `@tailwindcss/node`'s compiler.
+ */
+export function compileReadyTheme(css: string, table: ThemeSchemeTable): string {
+  const schemes = [...table.keys()].filter((name) => name !== BASE_SCHEME)
+  const stripped = stripVariantBlocks(css)
+  const prelude: string[] = []
+  const customVariants = buildCustomVariantDeclarations(stripped, schemes)
+  if (customVariants.length > 0) prelude.push(...customVariants)
+  const themeBlock = buildUnifiedThemeBlock(table, schemes)
+  if (themeBlock) prelude.push(themeBlock)
+  if (prelude.length === 0) return stripped
+  return `${prelude.join('\n')}\n${stripped}`
+}

package/src/core/parser/tokens.ts

@@ -0,0 +1,286 @@
+import type { Token, TokenOrValue } from 'lightningcss'
+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'
+
+/**
+ * Extract the fallback clause of a `var(--name, fallback)` by walking the
+ * string with paren-depth tracking. Linear-time; safe on nested
+ * `var(--a, var(--b, var(--c, 1rem)))` without regex backtracking.
+ * @param text CSS value already trimmed.
+ * @returns Fallback text, or `null` when `text` is not a `var(..., ...)`
+ *   with a fallback.
+ */
+function extractVariableFallback(text: string): string | null {
+  if (!text.startsWith('var(') || !text.endsWith(')')) return null
+  const inner = text.slice(4, -1)
+  let depth = 0
+  for (let index = 0; index < inner.length; index += 1) {
+    const ch = inner[index]
+    if (ch === '(') depth += 1
+    else if (ch === ')') depth -= 1
+    else if (ch === ',' && depth === 0) return inner.slice(index + 1).trim()
+  }
+  return null
+}
+
+/**
+ * Find the matching `)` for the opening `var(` whose body starts at
+ * `start`. Returns `-1` when the parens are unbalanced.
+ * @param text Source text.
+ * @param start Index just past the opening `var(`.
+ * @returns Index of the matching `)`, or `-1`.
+ */
+function findBalancedParenEnd(text: string, start: number): number {
+  let depth = 1
+  for (let index = start; index < text.length; index += 1) {
+    const ch = text[index]
+    if (ch === '(') depth += 1
+    else if (ch === ')') {
+      depth -= 1
+      if (depth === 0) return index
+    }
+  }
+  return -1
+}
+
+/**
+ * Resolve a `var(…)` body (the bit between parentheses). Reads the
+ * variable name, then either returns the table lookup or recurses into
+ * the fallback clause. When neither resolves, re-wraps as `var(…)` so
+ * downstream coercion still sees a well-formed reference.
+ * @param body Text between the outer parentheses of a `var()` call.
+ * @param table var → value map.
+ * @returns Substituted text fragment.
+ */
+function resolveVariableBody(body: string, table: ReadonlyMap<string, string>): string {
+  let depth = 0
+  let commaIndex = -1
+  for (const [index, ch] of [...body].entries()) {
+    if (ch === '(') depth += 1
+    else if (ch === ')') depth -= 1
+    else if (ch === ',' && depth === 0) {
+      commaIndex = index
+      break
+    }
+  }
+  const rawName = (commaIndex === -1 ? body : body.slice(0, commaIndex)).trim()
+  const fallback = commaIndex === -1 ? null : body.slice(commaIndex + 1).trim()
+  const resolved = table.get(rawName)
+  if (resolved !== undefined) return resolved
+  if (fallback !== null) return substitutePass(fallback, table)
+  return `var(${body})`
+}
+
+/**
+ * One pass of left-to-right `var(...)` substitution. Separate from the
+ * fixed-point driver so the recursion depth stays bounded.
+ * @param text Value text to scan.
+ * @param table var → value map.
+ * @returns Value text after one pass.
+ */
+function substitutePass(text: string, table: ReadonlyMap<string, string>): string {
+  let out = ''
+  let index = 0
+  while (index < text.length) {
+    const head = text.indexOf('var(', index)
+    if (head === -1) {
+      out += text.slice(index)
+      break
+    }
+    out += text.slice(index, head)
+    const end = findBalancedParenEnd(text, head + 4)
+    if (end === -1) {
+      out += text.slice(head)
+      break
+    }
+    const body = text.slice(head + 4, end)
+    out += resolveVariableBody(body, table)
+    index = end + 1
+  }
+  return out
+}
+
+/**
+ * Serialize a list of `TokenOrValue` nodes into a CSS-ish value string.
+ * Preserves the CSS form closely enough for downstream numeric coercion.
+ * @param tokens Token list from an unparsed declaration or custom-property body.
+ * @returns Concatenated CSS-value fragment.
+ */
+export function serializeTokens(tokens: readonly TokenOrValue[]): string {
+  let out = ''
+  for (const token of tokens) out += serializeToken(token)
+  return out.trim()
+}
+
+/**
+ * Serialize one `TokenOrValue` node back to CSS text. Handles the shapes
+ * Tailwind v4 actually emits in utility-class bodies: raw tokens, `var()`
+ * references, and numeric functions (`calc()`).
+ * @param token One token node.
+ * @returns CSS-value fragment.
+ */
+export function serializeToken(token: TokenOrValue): string {
+  switch (token.type) {
+    case 'token': {
+      return serializeRawToken(token.value)
+    }
+    case 'var': {
+      const head = token.value.name.ident
+      const { fallback } = token.value
+      if (!fallback || fallback.length === 0) return `var(${head})`
+      return `var(${head}, ${serializeTokens(fallback)})`
+    }
+    case 'function': {
+      return `${token.value.name}(${serializeTokens(token.value.arguments)})`
+    }
+    case 'length': {
+      return `${token.value.value}${token.value.unit}`
+    }
+    case 'dashed-ident': {
+      return token.value
+    }
+    case 'angle': {
+      return `${token.value.value}${token.value.type}`
+    }
+    case 'time': {
+      const unit = token.value.type === 'milliseconds' ? 'ms' : 's'
+      return `${token.value.value}${unit}`
+    }
+    case 'resolution': {
+      return `${token.value.value}${token.value.type}`
+    }
+    case 'color': {
+      // Pre-resolved CSS color (`oklch(...)`, `rgb(...)`, etc.) — render
+      // it back to a hex/rgba string RN can read.
+      return cssColorToString(token.value)
+    }
+    case 'env':
+    case 'unresolved-color':
+    case 'url':
+    case 'animation-name': {
+      return ''
+    }
+    default: {
+      return ''
+    }
+  }
+}
+
+/**
+ * Serialize a raw `Token` back to CSS text. `TokenOrValue` with
+ * `type === 'token'` wraps one of these; the discriminated union lets
+ * TypeScript narrow per branch without casts.
+ * @param token Raw token.
+ * @returns CSS text fragment.
+ */
+export function serializeRawToken(token: Token): string {
+  switch (token.type) {
+    case 'ident':
+    case 'at-keyword':
+    case 'string':
+    case 'unquoted-url':
+    case 'function': {
+      return token.value
+    }
+    case 'hash':
+    case 'id-hash': {
+      return `#${token.value}`
+    }
+    case 'number': {
+      return String(token.value)
+    }
+    case 'percentage': {
+      return `${token.value * 100}%`
+    }
+    case 'dimension': {
+      return `${token.value}${token.unit}`
+    }
+    case 'white-space': {
+      return ' '
+    }
+    case 'delim': {
+      return token.value
+    }
+    case 'comma': {
+      return ','
+    }
+    case 'colon':
+    case 'semicolon':
+    case 'parenthesis-block':
+    case 'square-bracket-block':
+    case 'curly-bracket-block':
+    case 'cdo':
+    case 'cdc':
+    case 'include-match':
+    case 'dash-match':
+    case 'prefix-match':
+    case 'suffix-match':
+    case 'substring-match':
+    case 'comment':
+    case 'bad-url':
+    case 'bad-string': {
+      return ''
+    }
+    default: {
+      return ''
+    }
+  }
+}
+
+/**
+ * Coerce the flat serialization of an unparsed value into an RN scalar.
+ * Handles the shapes Tailwind v4 actually emits: bare numbers, pixel /
+ * rem lengths, calc ratios, and `var(--x, fallback)` where we recurse into
+ * the fallback. Anything else passes through as a string.
+ * @param text Serialized CSS value.
+ * @returns Coerced primitive, or `null` when unrepresentable.
+ */
+export function coerceUnparsedValue(text: string): RNStyleValue | null {
+  const trimmed = text.trim()
+  if (trimmed.length === 0) return null
+  if (BARE_NUMBER_REGEX.test(trimmed)) return Number(trimmed)
+  const px = LENGTH_PX_REGEX.exec(trimmed)
+  if (px) return Number(px[1])
+  const rem = LENGTH_REM_REGEX.exec(trimmed)
+  if (rem) return Number(rem[1]) * REM_TO_PX
+  const fallback = extractVariableFallback(trimmed)
+  if (fallback !== null) return coerceUnparsedValue(fallback)
+  const calcRatio = CALC_RATIO_REGEX.exec(trimmed)
+  if (calcRatio) {
+    const right = Number(calcRatio[2])
+    if (right === 0) return null
+    return Number(calcRatio[1]) / right
+  }
+  const calcMul = CALC_MUL_REGEX.exec(trimmed)
+  if (calcMul) {
+    // Unit-aware multiply: `calc(0.5rem * 2)` → 16 (rem scaled to px).
+    // Regex captures `(number)(unit?) * (number)` — the unit is implicit
+    // in the match position; rebuild via the full match text.
+    const unitMatch = /^calc\(\s*-?\d+(?:\.\d+)?(rem|px)?/.exec(trimmed)
+    const unit = unitMatch?.[1]
+    const base = Number(calcMul[1]) * Number(calcMul[2])
+    return unit === 'rem' ? base * REM_TO_PX : base
+  }
+  return trimmed
+}
+
+/**
+ * Substitute every `var(--name [, fallback])` reference in `text` with
+ * the value from `table` (or the fallback clause when the name misses).
+ * Paren-balanced so nested `var(…)` refs don't confuse the scanner.
+ * Iterates to a fixed point so multi-hop substitutions land in one call
+ * (with a safety cap so a malformed self-referential token can't loop).
+ * @param text Raw CSS value.
+ * @param table var name → resolved value map.
+ * @returns Substituted text.
+ */
+export function substituteThemeVars(text: string, table: ReadonlyMap<string, string>): string {
+  let current = text
+  for (let pass = 0; pass < 8; pass += 1) {
+    const next = substitutePass(current, table)
+    if (next === current) return next
+    current = next
+  }
+  return current
+}