rnwind 0.0.7 → 0.0.9

package/src/core/parser/color.ts

@@ -32,7 +32,9 @@ function byteToHex(byte: number): string {
  */
 function rgbIntsToString(r: number, g: number, b: number, alpha: number): string {
   if (alpha >= 1) return `#${byteToHex(r)}${byteToHex(g)}${byteToHex(b)}`
-  return `rgba(${r}, ${g}, ${b}, ${alpha})`
+  // Round the alpha to shed f32 noise (`0.2 → 0.20000000298…`) — RN parses
+  // either, but the rounded form keeps generated StyleSheets compact.
+  return `rgba(${r}, ${g}, ${b}, ${Math.round(alpha * 10_000) / 10_000})`
 }
 
 /**
@@ -134,6 +136,35 @@ function xyzToHex(color: { type: 'xyz-d50' | 'xyz-d65'; x: number; y: number; z:
   return withAlpha(formatHex({ mode, x: color.x, y: color.y, z: color.z }) ?? null, color.alpha)
 }
 
+/**
+ * Modern CSS color functions RN's native view manager can't paint —
+ * everything else (hex, `rgb()`/`rgba()`, `hsl()`/`hsla()`, named colors,
+ * `transparent`, `currentColor`) RN reads directly and must pass through
+ * untouched. Custom `@theme` tokens reach the parser as `var(--color-x)`
+ * (only the default palette is `theme(inline)`-d), so they flow through the
+ * unparsed-string path where the typed {@link cssColorToString} never runs —
+ * this is the one place that lowers their wide-gamut values to sRGB.
+ */
+const RN_UNREADABLE_COLOR_PREFIXES: readonly string[] = ['oklch(', 'oklab(', 'lab(', 'lch(', 'color(', 'hwb(']
+
+/**
+ * Lower a wide-gamut / modern CSS color STRING (`oklch(…)`, `lab(…)`,
+ * `color(display-p3 …)`, …) to an sRGB hex/rgba string RN can paint. Returns
+ * `null` for anything RN already understands (hex, rgb, hsl, named) so the
+ * caller keeps the original text — only the unrepresentable forms convert.
+ * Mirrors {@link cssColorToString}'s culori lowering for the string path.
+ * @param text Resolved CSS color text (post theme-var substitution).
+ * @returns sRGB color string, or `null` when no conversion is needed/possible.
+ */
+export function normalizeColorString(text: string): string | null {
+  const lower = text.trim().toLowerCase()
+  if (!RN_UNREADABLE_COLOR_PREFIXES.some((prefix) => lower.startsWith(prefix))) return null
+  const parsed = culoriRgb(text)
+  if (!parsed || ![parsed.r, parsed.g, parsed.b].every((v) => typeof v === 'number' && Number.isFinite(v))) return null
+  const alpha = typeof parsed.alpha === 'number' ? parsed.alpha : 1
+  return rgbIntsToString(clampByte(parsed.r * 255), clampByte(parsed.g * 255), clampByte(parsed.b * 255), alpha)
+}
+
 /**
  * Convert a lightningcss `CssColor` to an RN-safe color string. RGB
  * passes through unchanged. LAB / LCH / OKLAB / OKLCH / `color(xyz-…)`

package/src/core/parser/declaration.ts

@@ -1,7 +1,7 @@
 /* eslint-disable sonarjs/cognitive-complexity -- the main Declaration → RN-entries dispatcher is intentionally a flat switch so each branch keeps its narrowed value type */
 import type { Declaration as LcDeclaration, TokenOrValue } from 'lightningcss'
 import { kebabToCamel } from './case-convert'
-import { cssColorToString } from './color'
+import { cssColorToString, normalizeColorString } from './color'
 import { dimensionPercentageToNumber, gapValueToValue, lengthPercentageOrAutoToValue, sizeLikeToValue } from './length'
 import {
   expandBorderColor,
@@ -38,6 +38,74 @@ const UNSUPPORTED_LOGICAL_PROPS = new Set([
   'border-block-end-style',
 ])
 
+/**
+ * Web-only CSS properties Tailwind v4 emits that have NO React Native style
+ * equivalent. Without this denylist they reach the generic `kebabToCamel`
+ * fallback and emit dead keys (`objectPosition`, `textWrap`, `willChange`,
+ * `float`, `columns`, `-webkit-line-clamp` → `WebkitLineClamp`, …) that bloat
+ * every StyleSheet and read as "supported" when they do nothing. Dropping the
+ * property name (kebab-case, pre-camel) is safe: it only excludes known
+ * web-only props — anything RN supports is handled by a typed branch above.
+ * (line-clamp's real RN behaviour comes from `numberOfLines` in text-truncate.)
+ */
+const RN_UNSUPPORTED_PROPERTIES: ReadonlySet<string> = new Set([
+  'object-position',
+  'text-wrap',
+  'will-change',
+  'columns',
+  'float',
+  'clear',
+  'table-layout',
+  'caption-side',
+  'transform-style',
+  'background-blend-mode',
+  'scroll-behavior',
+  'overscroll-behavior',
+  'overscroll-behavior-x',
+  'overscroll-behavior-y',
+  'scroll-snap-type',
+  'scroll-snap-align',
+  'scroll-snap-stop',
+  'break-after',
+  'break-before',
+  'break-inside',
+  'content',
+  'field-sizing',
+  'forced-color-adjust',
+  'text-shadow',
+  'touch-action',
+  'backdrop-filter',
+  '-webkit-backdrop-filter',
+  '-webkit-line-clamp',
+  '-webkit-box-orient',
+  '-webkit-font-smoothing',
+  '-moz-osx-font-smoothing',
+])
+
+/** CSS single-sided logical-inline property → RN writing-direction Yoga key. */
+const LOGICAL_INLINE_TO_RN: Record<string, string> = {
+  'margin-inline-start': 'marginStart',
+  'margin-inline-end': 'marginEnd',
+  'padding-inline-start': 'paddingStart',
+  'padding-inline-end': 'paddingEnd',
+}
+
+/**
+ * Logical border-COLOR property → physical RN side key(s). Custom `@theme`
+ * tokens reach the unparsed path as `border-inline-color: var(--color-x)`,
+ * which a plain `kebabToCamel` would turn into `borderInlineColor` — a key RN
+ * silently drops, so the border color never paints. Lower to the physical
+ * keys RN actually honors, matching the typed `dispatchBorderDeclaration`.
+ */
+const LOGICAL_BORDER_COLOR_SIDES: Record<string, readonly string[]> = {
+  'border-inline-color': ['borderLeftColor', 'borderRightColor'],
+  'border-block-color': ['borderTopColor', 'borderBottomColor'],
+  'border-inline-start-color': ['borderLeftColor'],
+  'border-inline-end-color': ['borderRightColor'],
+  'border-block-start-color': ['borderTopColor'],
+  'border-block-end-color': ['borderBottomColor'],
+}
+
 /**
  * Pick the closest predefined CSS easing keyword for a `cubic-bezier`
  * control-point set. Mirrors {@link snapCubicBezierToKeyword} in
@@ -80,6 +148,23 @@ function coerceCubicBezierString(value: string): string {
   return snapBezier(Number(x1), Number(y1), Number(x2), Number(y2))
 }
 
+/**
+ * Whether `text` has a whitespace char OUTSIDE any parenthesised group —
+ * the signature of a multi-token CSS value (`2px solid #000`) rather than a
+ * single color (`#000`, `rgb(1 2 3)`, `red`).
+ * @param text Resolved value text.
+ * @returns True when a top-level space is present.
+ */
+function hasTopLevelSpace(text: string): boolean {
+  let depth = 0
+  for (const ch of text.trim()) {
+    if (ch === '(') depth += 1
+    else if (ch === ')') depth = Math.max(0, depth - 1)
+    else if (depth === 0 && (ch === ' ' || ch === '\t' || ch === '\n')) return true
+  }
+  return false
+}
+
 /**
  * Fast-path check for the handful of color property names Tailwind emits.
  * @param property Kebab-case CSS property name.
@@ -89,6 +174,11 @@ function isColorProperty(property: string): boolean {
   return (
     property === 'color' ||
     property === 'background-color' ||
+    // SVG paint props (`fill-<token>` / `stroke-<token>` via react-native-svg) —
+    // they don't end in `-color`, so without this they'd skip normalization and
+    // leak a raw `oklch(…)` string for custom `@theme` tokens.
+    property === 'fill' ||
+    property === 'stroke' ||
     (property.startsWith('border-') && property.endsWith('-color')) ||
     property.endsWith('-color')
   )
@@ -110,6 +200,7 @@ function unparsedToEntries(
   themeVars: ReadonlyMap<string, string> | undefined,
 ): readonly RNEntry[] {
   if (property.length === 0) return []
+  if (RN_UNSUPPORTED_PROPERTIES.has(property)) return []
   // Safe-area detection runs BEFORE token serialization because
   // `env()` serializes to an empty string, which would strip the side
   // info we need. If the tokens encode a recognised `env(safe-area-inset-*)`
@@ -122,12 +213,15 @@ function unparsedToEntries(
   if (themeVars && themeVars.size > 0) text = substituteThemeVars(text, themeVars)
   const coerced = coerceUnparsedValue(text)
   if (coerced === null) return []
-  // Skip values that didn't resolve past their `var()` wrapper — they
-  // came from a `@property --tw-*` token without a real fallback.
-  // Tailwind v4's `border-N` emits `border-style: var(--tw-border-style)`
-  // expecting the cascade to fill it in; in RN we drop them and rely on
-  // RN's default (solid).
-  if (typeof coerced === 'string' && coerced.startsWith('var(')) return []
+  // Skip values still carrying an unresolved `var(--tw-*)` ANYWHERE in the
+  // string — they came from a `@property --tw-*` composable with no real
+  // fallback (e.g. `filter: blur(8px) var(--tw-brightness) …`,
+  // `transform: rotateX(45deg) var(--tw-rotate-y) …`, `touch-action`,
+  // `scroll-snap-type`). RN can't evaluate the cascade, so a leaked `var()`
+  // makes the whole declaration an invalid string RN rejects — drop it and
+  // rely on RN's default rather than emit garbage. `var(--color-*)` refs are
+  // already substituted above, so anything left is a genuine composable miss.
+  if (typeof coerced === 'string' && coerced.includes('var(')) return []
   // RN `fontFamily` is a single typeface, not a CSS fallback list — take
   // the first family so `--font-x: "Name", sans-serif` works out of the box.
   if (property === 'font-family' && typeof coerced === 'string') {
@@ -144,9 +238,21 @@ function unparsedToEntries(
     return [[kebabToCamel(property), coerceCubicBezierString(coerced)]]
   }
   if (isColorProperty(property) && typeof coerced === 'string') {
-    // Resolved user-theme color strings (e.g. `#ff0099`) go straight to
-    // the RN style — no further conversion needed.
-    return [[kebabToCamel(property), coerced]]
+    // A color is a single token. Tailwind compiles an arbitrary shorthand like
+    // `border-[2px_solid_#000]` to `border-color: 2px solid #000` (invalid for
+    // a color property → unparsed), which would otherwise emit
+    // `borderColor: "2px solid #000000"` — a string RN rejects. A top-level
+    // space (outside parens — `rgb(1 2 3)` keeps its inner spaces) means it's a
+    // multi-token shorthand, not a color: drop it.
+    if (hasTopLevelSpace(coerced)) return []
+    // Lower modern color spaces (`oklch(…)`, `lab(…)`, `color(p3 …)`) that
+    // RN can't paint to sRGB; hex/rgb/hsl/named pass through unchanged.
+    const color = normalizeColorString(coerced) ?? coerced
+    // Logical border-color utilities must lower to physical RN side keys —
+    // RN ignores `borderInlineColor` / `borderInlineStartColor`.
+    const sides = LOGICAL_BORDER_COLOR_SIDES[property]
+    if (sides) return sides.map((key): RNEntry => [key, color])
+    return [[kebabToCamel(property), color]]
   }
   return [[kebabToCamel(property), coerced]]
 }
@@ -333,6 +439,7 @@ export function declarationToRnEntries(decl: LcDeclaration, themeVars?: Readonly
     }
     default: {
       return (
+        dispatchLogicalInline(decl) ??
         dispatchLayoutDeclaration(decl) ??
         dispatchTypographyDeclaration(decl) ??
         dispatchColorPropertyDeclaration(decl) ??
@@ -343,3 +450,46 @@ export function declarationToRnEntries(decl: LcDeclaration, themeVars?: Readonly
     }
   }
 }
+
+/**
+ * Map single-sided CSS logical-inline props to RN's writing-direction-aware
+ * Yoga keys: `ms-2` → `marginStart`, `pe-4` → `paddingEnd`, `start-2` →
+ * `start`, `end-3` → `end`. RN resolves start/end against the layout
+ * direction, so these stay RTL-correct. Returns null for any other property
+ * (so the dispatch chain continues).
+ * @param decl One declaration from a lightningcss style rule.
+ * @returns RN entries, or null when not a logical-inline property.
+ */
+function dispatchLogicalInline(decl: LcDeclaration): readonly RNEntry[] | null {
+  switch (decl.property) {
+    case 'margin-inline-start':
+    case 'margin-inline-end':
+    case 'padding-inline-start':
+    case 'padding-inline-end': {
+      const v = lengthPercentageOrAutoToValue(decl.value)
+      return v === null ? [] : [[LOGICAL_INLINE_TO_RN[decl.property], v]]
+    }
+    case 'inset-inline-start': {
+      const v = lengthPercentageOrAutoToValue(decl.value)
+      return v === null ? [] : [['start', v]]
+    }
+    case 'inset-inline-end': {
+      const v = lengthPercentageOrAutoToValue(decl.value)
+      return v === null ? [] : [['end', v]]
+    }
+    // Logical border-radius corners (`rounded-s/e/ss/se/ee/es-*`). RN has
+    // matching keys — `kebabToCamel('border-start-start-radius')` is exactly
+    // `borderStartStartRadius`. Value is a `[x, y]` tuple like physical corners.
+    case 'border-start-start-radius':
+    case 'border-start-end-radius':
+    case 'border-end-start-radius':
+    case 'border-end-end-radius': {
+      const [xAxis] = decl.value
+      const v = dimensionPercentageToNumber(xAxis)
+      return v === null ? [] : [[kebabToCamel(decl.property), v]]
+    }
+    default: {
+      return null
+    }
+  }
+}

package/src/core/parser/gradient.ts

@@ -22,8 +22,10 @@
  * {@link GradientAtomInfo} record the transformer can read per atom.
  */
 
+import { formatHex as culoriFormatHex } from 'culori'
 import type { Declaration as LcDeclaration, TokenOrValue } from 'lightningcss'
-import { cssColorToString } from './color'
+import { cssColorToString, normalizeColorString } from './color'
+import { serializeTokens, substituteThemeVars } from './tokens'
 
 /**
  * The four roles an atom can play in a Tailwind v4 gradient. `from`,
@@ -59,32 +61,62 @@ export type GradientDirection =
  * return the atom's role + data. Returns `null` for rules that don't
  * belong to a gradient utility.
  * @param declarations Declarations from one lightningcss style rule.
+ * @param themeVars
  * @returns Gradient info, or null.
  */
-function detectGradientAtom(declarations: readonly LcDeclaration[]): GradientAtomInfo | null {
+function detectGradientAtom(
+  declarations: readonly LcDeclaration[],
+  themeVars?: ReadonlyMap<string, string>,
+): GradientAtomInfo | null {
   for (const decl of declarations) {
     if (decl.property !== 'custom') continue
     const custom = decl.value as { name: { name: string } | string; value?: readonly TokenOrValue[] }
     const name = typeof custom.name === 'string' ? custom.name : custom.name.name
     if (!name.startsWith('--tw-gradient-')) continue
-    if (name === '--tw-gradient-from') return fromColor('from', custom.value)
-    if (name === '--tw-gradient-via') return fromColor('via', custom.value)
-    if (name === '--tw-gradient-to') return fromColor('to', custom.value)
+    if (name === '--tw-gradient-from') return fromColor('from', custom.value, themeVars)
+    if (name === '--tw-gradient-via') return fromColor('via', custom.value, themeVars)
+    if (name === '--tw-gradient-to') return fromColor('to', custom.value, themeVars)
     if (name === '--tw-gradient-position') return fromDirection(custom.value)
   }
   return null
 }
 
 /**
- * Extract a single color token from a custom-property value list and
- * return the `{role, color}` record. Returns `null` when no color token
- * is present (defensive — Tailwind always emits one, but future output
- * shapes may not).
+ * Lower a resolved gradient-stop color string to one RN's `LinearGradient`
+ * `colors=` array accepts. Hex/rgb/hsl pass through; modern spaces
+ * (`oklch(…)`, `lab(…)`, `color(p3 …)`) and named colors go through culori.
+ * @param text Resolved color text (post theme-var substitution).
+ * @returns sRGB color string, or null when unparseable.
+ */
+function resolveGradientColor(text: string): string | null {
+  if (text.startsWith('#') || text.startsWith('rgb') || text.startsWith('hsl')) return text
+  const normalized = normalizeColorString(text)
+  if (normalized) return normalized
+  try {
+    const hex = culoriFormatHex(text)
+    return typeof hex === 'string' ? hex : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Extract a stop color from a `--tw-gradient-*` value list. The default
+ * Tailwind palette is inlined to a typed `color` token; CUSTOM `@theme`
+ * tokens arrive as an unresolved `var(--color-x)` token list, so when no
+ * typed color is present we serialize, substitute `themeVars`, and lower
+ * the result to sRGB — without this, `from-<token>` / `via-<token>` /
+ * `to-<token>` dropped the stop entirely.
  * @param role Target role (`from` / `via` / `to`).
  * @param tokens Value tokens from the `--tw-gradient-*` declaration.
+ * @param themeVars Per-scheme var table for resolving `var(--color-x)`.
  * @returns Gradient info, or null.
  */
-function fromColor(role: 'from' | 'via' | 'to', tokens: readonly TokenOrValue[] | undefined): GradientAtomInfo | null {
+function fromColor(
+  role: 'from' | 'via' | 'to',
+  tokens: readonly TokenOrValue[] | undefined,
+  themeVars?: ReadonlyMap<string, string>,
+): GradientAtomInfo | null {
   if (!tokens) return null
   for (const token of tokens) {
     if (token.type !== 'color') continue
@@ -92,7 +124,12 @@ function fromColor(role: 'from' | 'via' | 'to', tokens: readonly TokenOrValue[]
     if (!color) return null
     return { role, color } as GradientAtomInfo
   }
-  return null
+  // Custom @theme token: value is `var(--color-x)` — serialize + resolve.
+  let text = serializeTokens(tokens).trim()
+  if (themeVars && themeVars.size > 0) text = substituteThemeVars(text, themeVars)
+  if (text.length === 0 || text.startsWith('var(')) return null
+  const color = resolveGradientColor(text)
+  return color ? ({ role, color } as GradientAtomInfo) : null
 }
 
 /**

package/src/core/parser/keyframes.ts

@@ -45,8 +45,17 @@ export function keyframesName(raw: KeyframesName): string | null {
  */
 export function keyframeSelectorOffset(selectors: readonly KeyframeSelector[]): string | null {
   const [head] = selectors
-  if (!head) return null
-  switch (head.type) {
+  return head ? offsetForSelector(head) : null
+}
+
+/**
+ * Render ONE keyframe selector to its CSS offset text, or `null` when it's a
+ * timeline-range selector RN can't run.
+ * @param selector A single keyframe selector.
+ * @returns Offset text (`'from'` / `'to'` / `'50%'`), or `null`.
+ */
+function offsetForSelector(selector: KeyframeSelector): string | null {
+  switch (selector.type) {
     case 'from': {
       return 'from'
     }
@@ -54,7 +63,7 @@ export function keyframeSelectorOffset(selectors: readonly KeyframeSelector[]):
       return 'to'
     }
     case 'percentage': {
-      return `${head.value * 100}%`
+      return `${selector.value * 100}%`
     }
     default: {
       return null
@@ -62,6 +71,25 @@ export function keyframeSelectorOffset(selectors: readonly KeyframeSelector[]):
   }
 }
 
+/**
+ * Render EVERY representable offset in a frame's selector list. Tailwind
+ * collapses shared steps into one frame with multiple selectors — `animate-ping`
+ * emits `75%, 100% { … }`, `animate-bounce` emits `0%, 100% { … }`. Reading only
+ * the first selector (the old singular helper) dropped the terminal `100%`, so
+ * the looping animation never defined its end/return-to-start state. Returns all
+ * offsets the frame's style applies to; timeline-range selectors are skipped.
+ * @param selectors Step selectors for one frame.
+ * @returns Every representable offset (may be empty).
+ */
+export function keyframeSelectorOffsets(selectors: readonly KeyframeSelector[]): readonly string[] {
+  const offsets: string[] = []
+  for (const selector of selectors) {
+    const offset = offsetForSelector(selector)
+    if (offset !== null) offsets.push(offset)
+  }
+  return offsets
+}
+
 /**
  * Extract the referenced `@keyframes` name from a declaration whose
  * property is `animation-name` or a shorthand `animation` that names one.

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

@@ -1,6 +1,33 @@
 import type { Declaration as LcDeclaration } from 'lightningcss'
 import type { RNEntry } from './types'
 
+/**
+ * Lower a CSS `overflow` keyword to one RN's `overflow` prop accepts
+ * (`'visible' | 'hidden' | 'scroll'`). `auto` → `scroll` (auto means
+ * scroll-when-needed), `clip` → `hidden` (closest no-scroll clip). Anything
+ * else (an unexpected keyword) drops so RN never sees an invalid value.
+ * @param css CSS overflow keyword.
+ * @returns RN overflow keyword, or `null` to drop.
+ */
+function mapOverflow(css: string): string | null {
+  if (css === 'visible' || css === 'hidden' || css === 'scroll') return css
+  if (css === 'auto') return 'scroll'
+  if (css === 'clip') return 'hidden'
+  return null
+}
+
+/**
+ * Build the RN `overflow` entry for a raw axis value, mapping it to an
+ * RN-valid keyword and dropping unrepresentable shapes. Shared by the
+ * `overflow` shorthand and the `overflow-x` / `overflow-y` longhands.
+ * @param value Raw per-axis overflow value (string keyword or other).
+ * @returns Single `[overflow, …]` entry, or empty when unmappable.
+ */
+function overflowEntry(value: unknown): readonly RNEntry[] {
+  const mapped = typeof value === 'string' ? mapOverflow(value) : null
+  return mapped === null ? [] : [['overflow', mapped]]
+}
+
 /**
  * Lower CSS alignment keywords to the strings RN accepts. CSS uses
  * `start`/`end` while RN sticks with the legacy `flex-start`/`flex-end`.
@@ -87,14 +114,10 @@ export function dispatchLayoutDeclaration(decl: LcDeclaration): readonly RNEntry
     }
     case 'overflow': {
       // Lightningcss splits CSS `overflow` into `{x, y}` axes; RN only
-      // supports a single `overflow` keyword (and only `'hidden' |
-      // 'visible' | 'scroll'` on iOS, `'hidden' | 'visible'` on
-      // Android — RN ignores unsupported keywords at runtime). Take
-      // the `x` axis when the user wrote shorthand; per-axis Tailwind
-      // utilities both emit shorthand here so axis splitting is rare.
-      const value = decl.value as { x?: unknown; y?: unknown }
-      if (typeof value.x !== 'string') return []
-      return [['overflow', value.x]]
+      // supports a single `overflow` keyword. Take the `x` axis when the
+      // user wrote shorthand; per-axis Tailwind utilities both emit
+      // shorthand here so axis splitting is rare.
+      return overflowEntry((decl.value as { x?: unknown }).x)
     }
     case 'overflow-x':
     case 'overflow-y': {
@@ -102,7 +125,7 @@ export function dispatchLayoutDeclaration(decl: LcDeclaration): readonly RNEntry
       // not the `overflow` shorthand. RN has only a single `overflow`,
       // so collapse both axes onto it (last one declared wins via the
       // normal entry-merge order).
-      return typeof decl.value === 'string' ? [['overflow', decl.value]] : []
+      return overflowEntry(decl.value)
     }
     default: {
       return null

package/src/core/parser/length.ts

@@ -69,11 +69,28 @@ export function lengthToPx(length: LengthValue): number {
  * @returns Number, percent string, or `null` when unrepresentable.
  */
 export function dimensionPercentageToNumber(value: DimensionPercentage): LengthResult {
-  if (value.type === 'dimension') return lengthToPx(value.value)
+  if (value.type === 'dimension') return viewportToPercent(value.value) ?? lengthToPx(value.value)
   if (value.type === 'percentage') return `${roundFloat(value.value * 100)}%`
   return null
 }
 
+/** Viewport-relative units — can't resolve to px statically; approximate as `%`. */
+const VIEWPORT_UNITS: ReadonlySet<string> = new Set(['vw', 'vh', 'vmin', 'vmax', 'dvw', 'dvh', 'svw', 'svh', 'lvw', 'lvh'])
+
+/**
+ * Map a viewport-unit length to a percentage string — `100vw`/`100vh`
+ * (e.g. `w-screen`/`h-screen`) become `'100%'`. Viewport units can't be
+ * statically resolved to px (they need live `Dimensions`), and `'N%'` is
+ * the closest RN-renderable approximation, far better than treating `100vw`
+ * as a literal `100px` box. Returns null for non-viewport units.
+ * @param length Typed length value.
+ * @returns `'N%'` string, or null when not a viewport unit.
+ */
+function viewportToPercent(length: LengthValue): string | null {
+  if (!VIEWPORT_UNITS.has(length.unit)) return null
+  return `${roundFloat(length.value)}%`
+}
+
 /**
  * Convert `LengthPercentageOrAuto` (per-side value type for padding /
  * margin / inset) to an RN scalar. `auto` maps to the string `'auto'`,

package/src/core/parser/safe-area.ts

@@ -53,10 +53,16 @@ function detectSafeAreaMarker(tokens: readonly TokenOrValue[], themeVars?: Theme
   const nonWs = stripWhitespace(tokens)
   if (nonWs.length === 0) return null
 
-  // Shape 1: pure env(safe-area-inset-*)
+  // Shape 1: pure env(safe-area-inset-*), optionally with a CSS fallback —
+  // `env(safe-area-inset-top, 12px)`. The fallback is the author's intended
+  // floor when the inset is unavailable, so capture it as `or` (max(inset, N))
+  // instead of silently dropping it and collapsing to 0.
   if (nonWs.length === 1) {
     const side = envSide(nonWs[0]!)
-    if (side !== null) return { __safe: side }
+    if (side !== null) {
+      const or = envFallbackPx(nonWs[0]!, themeVars)
+      return or === null ? { __safe: side } : { __safe: side, or }
+    }
   }
 
   // Shape 2 / 3: max(env(...), n) or calc(env(...) + n)
@@ -194,6 +200,21 @@ function envSide(token: TokenOrValue): SafeAreaMarker['__safe'] | null {
   return SIDE_TAG[name.value] ?? null
 }
 
+/**
+ * Read an `env(side, <fallback>)` token's CSS fallback as a pixel floor.
+ * Returns null when there's no fallback or it isn't a plain length — the
+ * caller then emits the bare marker.
+ * @param token One TokenOrValue (expected to be an `env` token).
+ * @param themeVars Optional theme-vars table for resolving `var()` in the fallback.
+ * @returns Fallback length in px, or null.
+ */
+function envFallbackPx(token: TokenOrValue, themeVars: ThemeVars | undefined): number | null {
+  if (token.type !== 'env') return null
+  const { fallback } = token.value
+  if (!fallback || fallback.length === 0) return null
+  return coerceLengthPx(stripWhitespace(fallback), themeVars)
+}
+
 /**
  * Drop whitespace / comment tokens from a list so downstream branches
  * can pattern-match by index without counting spaces.