rnwind 0.0.2 → 0.0.4

package/src/metro/state.ts

@@ -1,8 +1,9 @@
-import { existsSync, readFileSync, statSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { createHash } from 'node:crypto'
 import { UnionBuilder } from '../core/style-builder'
 import { TailwindParser, type SourceEntry } from '../core/parser'
+import { resolveThemeCss } from './css-imports'
 
 /**
  * Default oxide Scanner globs — walk every JS/TS source under the
@@ -50,6 +51,10 @@ const CACHE_DIR_ENV = 'RNWIND_CACHE_DIR'
 const WATCH_FOLDERS_ENV = 'RNWIND_WATCH_FOLDERS'
 /** Env var carrying extra className prefixes the Metro config supplied. */
 const CLASSNAME_PREFIXES_ENV = 'RNWIND_CLASSNAME_PREFIXES'
+/** Env var carrying extra import sources whose JSX exports get className→style rewrites. Comma-separated. */
+const HOST_SOURCES_ENV = 'RNWIND_HOST_SOURCES'
+/** Env var carrying extra JSX tag names (verbatim, may contain `.`) treated as hosts. Comma-separated. */
+const HOST_COMPONENTS_ENV = 'RNWIND_HOST_COMPONENTS'
 
 /** Memoised library fingerprint — read once per worker process. */
 let libraryFingerprint: string | undefined
@@ -58,19 +63,18 @@ let libraryFingerprint: string | undefined
 let cached: RnwindState | null = null
 
 /**
- * Cheap content-hash readout. SHA-256 prefix of the CSS bytes plus the
- * file's mtime nanoseconds (so identical content with different mtime
- * — atomic rewrites — still picks up the change). Returns `'missing'`
- * when the file can't be read so the cache key is still deterministic.
+ * Cheap content-hash readout. SHA-256 prefix of the FULLY-RESOLVED theme
+ * CSS — `@import`s flattened — so an edit to a theme file the entry only
+ * re-exports (`@import "@acme/ui/theme.css"`) still rotates the hash and
+ * invalidates Metro's cache. Returns `'missing'` when the entry can't be
+ * read so the cache key stays deterministic.
  * @param cssPath Absolute CSS path.
  * @returns 16-char hex content hash.
  */
 function readThemeHashFor(cssPath: string): string {
   if (!existsSync(cssPath)) return 'missing'
   try {
-    const bytes = readFileSync(cssPath)
-    const mtime = statSync(cssPath).mtimeMs.toString()
-    return createHash('sha256').update(bytes).update(mtime).digest('hex').slice(0, 16)
+    return createHash('sha256').update(resolveThemeCss(cssPath)).digest('hex').slice(0, 16)
   } catch {
     return 'missing'
   }
@@ -146,12 +150,16 @@ export interface RnwindState {
  * @param cacheDir Absolute path to the cache dir (`.rnwind`).
  * @param watchFolders
  * @param classNamePrefixes Extra JSX prop-name prefixes to rewrite.
+ * @param hostSources
+ * @param hostComponents
  */
 export function configureRnwindState(
   cssEntryFile: string,
   cacheDir: string,
   watchFolders: readonly string[] = [],
   classNamePrefixes?: readonly string[],
+  hostSources?: readonly string[],
+  hostComponents?: readonly string[],
 ): void {
   process.env[CSS_ENTRY_ENV] = cssEntryFile
   process.env[CACHE_DIR_ENV] = cacheDir
@@ -165,6 +173,16 @@ export function configureRnwindState(
   } else {
     process.env[CLASSNAME_PREFIXES_ENV] = classNamePrefixes.join(',')
   }
+  if (!hostSources || hostSources.length === 0) {
+    delete process.env[HOST_SOURCES_ENV]
+  } else {
+    process.env[HOST_SOURCES_ENV] = hostSources.join(',')
+  }
+  if (!hostComponents || hostComponents.length === 0) {
+    delete process.env[HOST_COMPONENTS_ENV]
+  } else {
+    process.env[HOST_COMPONENTS_ENV] = hostComponents.join(',')
+  }
   cached = null
 }
 
@@ -181,6 +199,30 @@ export function getClassNamePrefixes(): readonly string[] {
   return raw.split(',').filter((entry) => entry.length > 0)
 }
 
+/**
+ * Read the caller-configured extra host module sources out of the
+ * worker environment. Empty array when unset — the transformer applies
+ * its built-in default list on top either way.
+ * @returns User-supplied extra host sources.
+ */
+export function getHostSources(): readonly string[] {
+  const raw = process.env[HOST_SOURCES_ENV]
+  if (!raw || raw.length === 0) return []
+  return raw.split(',').filter((entry) => entry.length > 0)
+}
+
+/**
+ * Read the caller-configured extra host JSX tag names out of the worker
+ * environment. Verbatim names — may include `.` for member expressions
+ * like `'Animated.View'`.
+ * @returns User-supplied extra host component names.
+ */
+export function getHostComponents(): readonly string[] {
+  const raw = process.env[HOST_COMPONENTS_ENV]
+  if (!raw || raw.length === 0) return []
+  return raw.split(',').filter((entry) => entry.length > 0)
+}
+
 /**
  * Fetch (or build) the worker-local rnwind state. Re-reads the theme
  * CSS hash on every call: if the user edited `global.css` while Metro
@@ -198,7 +240,7 @@ export function getRnwindState(projectRoot: string): RnwindState {
   if (!cacheDir) throw new Error('rnwind: RNWIND_CACHE_DIR is not set — did `withRnwindConfig` run?')
   const currentHash = readThemeHashFor(cssEntry)
   if (cached?.themeHash === currentHash && cached.projectRoot === projectRoot) return cached
-  const themeCss = readFileSync(cssEntry, 'utf8')
+  const themeCss = resolveThemeCss(cssEntry)
   const parser = new TailwindParser({
     themeCss,
     sources: defaultSources(projectRoot, cacheDir, readWatchFolders()),
@@ -220,7 +262,13 @@ export function getRnwindState(projectRoot: string): RnwindState {
 export function getRnwindCacheKey(): string {
   const cssEntry = process.env[CSS_ENTRY_ENV] ?? ''
   const prefixes = process.env[CLASSNAME_PREFIXES_ENV] ?? ''
-  return `rnwind:${cssEntry}:${readThemeHashFor(cssEntry)}|lib:${getLibraryFingerprint()}|pfx:${prefixes}`
+  // Host source / component config changes which JSX tags get rewritten,
+  // so it MUST flip the cache key — otherwise Metro replays stale
+  // transforms (a newly-opted-in host keeps its raw className, a removed
+  // one keeps the rewrite).
+  const hostSources = process.env[HOST_SOURCES_ENV] ?? ''
+  const hostComponents = process.env[HOST_COMPONENTS_ENV] ?? ''
+  return `rnwind:${cssEntry}:${readThemeHashFor(cssEntry)}|lib:${getLibraryFingerprint()}|pfx:${prefixes}|hs:${hostSources}|hc:${hostComponents}`
 }
 
 /** Drop the cached state — call after editing the theme CSS. */

package/src/metro/transform-ast.ts

@@ -135,6 +135,21 @@ export interface TransformAstOptions {
    * or dynamic.
    */
   classNamePrefixes?: readonly string[]
+  /**
+   * Extra module specifiers whose JSX exports the transformer should
+   * treat as hosts (rewrite `className` → `style` at compile time).
+   * Merged with the built-in {@link DEFAULT_HOST_SOURCES} list. Use
+   * this for design-system packages whose primitives wrap RN hosts and
+   * accept `style` directly.
+   */
+  hostSources?: readonly string[]
+  /**
+   * Extra component names (verbatim, including dotted member access
+   * like `'Animated.View'`) the transformer should treat as hosts. Use
+   * this for one-off escape-hatches that aren't matchable by source —
+   * e.g. you alias `View as MyBox` and want the compile-time path.
+   */
+  hostComponents?: readonly string[]
 }
 
 /**
@@ -145,6 +160,162 @@ export interface TransformAstOptions {
  */
 const DEFAULT_CLASSNAME_PREFIXES: readonly string[] = ['contentContainer']
 
+/**
+ * Module specifiers whose JSX exports are "host-like" — they consume
+ * `style` directly (and own no opaque component logic that depends on
+ * receiving the raw `className` string). For tags imported from these
+ * sources the transformer rewrites `className="…"` → `style={lookupCss(…)}`
+ * at build time, so the runtime cost is zero.
+ *
+ * For tags from ANY other source the transformer leaves `className`
+ * alone — the importing component receives the raw string and decides
+ * what to do with it (forward to an inner host, reshape, route a slice
+ * to `contentContainerStyle`, …). This is what makes patterns like
+ * `<MyButton className="px-4 bg-primary" />` work without rnwind
+ * stealing the prop before the component sees it.
+ *
+ * Users extend the list via `withRnwindConfig`'s `hostSources` option.
+ */
+const DEFAULT_HOST_SOURCES: readonly string[] = [
+  'react-native',
+  'react-native-reanimated',
+  'react-native-svg',
+  'react-native-gesture-handler',
+  'react-native-safe-area-context',
+  'expo-linear-gradient',
+  'expo-image',
+  'expo-blur',
+  'expo-symbols',
+  '@shopify/flash-list',
+  '@shopify/react-native-skia',
+  'lottie-react-native',
+]
+
+/**
+ * Whether a JSX tag name is lowercase. Lowercase tags don't appear in
+ * native React Native userland — but if one shows up (web target via
+ * `react-native-web`, mdx, etc.) treat it as a host so the rewrite
+ * engages instead of silently dropping the className.
+ * @param name JSX tag identifier text.
+ * @returns True for ASCII-lowercase first character.
+ */
+function isLowercaseTag(name: string): boolean {
+  const code = name.codePointAt(0)
+  return code !== undefined && code >= 97 && code <= 122
+}
+
+/**
+ * Walk a JSX opening element's tag name node into a dotted string
+ * (`Animated.View`, `Foo.Bar.Baz`). Returns `null` for namespaced names
+ * (`<svg:rect>` — invalid in RN; we skip them).
+ * @param name JSXOpeningElement name node.
+ * @returns Dotted tag text, or null.
+ */
+function jsxTagText(name: t.JSXOpeningElement['name']): string | null {
+  if (t.isJSXIdentifier(name)) return name.name
+  if (t.isJSXMemberExpression(name)) {
+    const left = jsxTagText(name.object as t.JSXOpeningElement['name'])
+    return left ? `${left}.${name.property.name}` : null
+  }
+  return null
+}
+
+/**
+ * Leftmost identifier of a (possibly dotted) tag — used to look up its import source.
+ * @param tagText
+ */
+function leftmostIdentifier(tagText: string): string {
+  const dot = tagText.indexOf('.')
+  return dot === -1 ? tagText : tagText.slice(0, dot)
+}
+
+/** Resolves a tag-text to "is this a host?" using import sources + user-extended host names. */
+type HostLookup = (tagText: string) => boolean
+
+/**
+ * Build the per-file host lookup. Walks every `import` declaration once
+ * to map every locally-bound name to its source module. A JSX tag is a
+ * host when:
+ *  1. its full text matches an entry in `extraHostComponents` (verbatim),
+ *  2. its leftmost identifier was imported from a `hostSources` module,
+ *  3. it's a lowercase tag (web targets, defensive).
+ *
+ * Anything else is custom and the transformer leaves its className alone.
+ * @param ast File AST.
+ * @param extraHostSources User-supplied additional host module specifiers.
+ * @param extraHostComponents User-supplied additional host component names.
+ * @returns Lookup callback.
+ */
+function buildHostLookup(
+  ast: File,
+  extraHostSources: readonly string[] | undefined,
+  extraHostComponents: readonly string[] | undefined,
+): HostLookup {
+  const importSourceByLocal = new Map<string, string>()
+  for (const node of ast.program.body) {
+    if (!t.isImportDeclaration(node)) continue
+    const source = node.source.value
+    for (const spec of node.specifiers) {
+      if (t.isImportDefaultSpecifier(spec) || t.isImportSpecifier(spec) || t.isImportNamespaceSpecifier(spec)) {
+        importSourceByLocal.set(spec.local.name, source)
+      }
+    }
+  }
+  // Recognise module-local host aliases — common pattern in React Native:
+  //   const AnimatedTextInput = Animated.createAnimatedComponent(TextInput)
+  //   const Animated = createAnimatedComponent(View)
+  // The local binding wraps a host underneath so its className must still
+  // be rewritten. Without this every `<AnimatedTextInput className="…" />`
+  // site looked custom and the className silently dropped.
+  const localHostAliases = collectCreateAnimatedComponentAliases(ast)
+  const hostSources = new Set<string>([...DEFAULT_HOST_SOURCES, ...(extraHostSources ?? [])])
+  const hostComponents = new Set<string>(extraHostComponents)
+  return (tagText: string): boolean => {
+    if (isLowercaseTag(tagText)) return true
+    if (hostComponents.has(tagText)) return true
+    const left = leftmostIdentifier(tagText)
+    if (localHostAliases.has(left)) return true
+    const source = importSourceByLocal.get(left)
+    return source !== undefined && hostSources.has(source)
+  }
+}
+
+/**
+ * Walk top-level `const X = createAnimatedComponent(Y)` /
+ * `Animated.createAnimatedComponent(Y)` declarations and return the set
+ * of local names so the host-lookup recognises them. Reanimated +
+ * RN-core `Animated.createAnimatedComponent` are the only creators in
+ * common use; matching by callee-name covers both shapes without
+ * needing import-source resolution.
+ * @param ast File AST.
+ * @returns Set of locally-bound names that wrap a host component.
+ */
+function collectCreateAnimatedComponentAliases(ast: File): ReadonlySet<string> {
+  const aliases = new Set<string>()
+  for (const node of ast.program.body) {
+    const declaration = t.isExportNamedDeclaration(node) ? node.declaration : node
+    if (!t.isVariableDeclaration(declaration)) continue
+    for (const decl of declaration.declarations) {
+      if (!t.isIdentifier(decl.id) || !decl.init) continue
+      if (!isCreateAnimatedComponentCall(decl.init)) continue
+      aliases.add(decl.id.name)
+    }
+  }
+  return aliases
+}
+
+/**
+ * True for `createAnimatedComponent(...)` and `<x>.createAnimatedComponent(...)` calls.
+ * @param expr
+ */
+function isCreateAnimatedComponentCall(expr: t.Expression): boolean {
+  if (!t.isCallExpression(expr)) return false
+  const { callee } = expr
+  if (t.isIdentifier(callee) && callee.name === 'createAnimatedComponent') return true
+  if (t.isMemberExpression(callee) && t.isIdentifier(callee.property) && callee.property.name === 'createAnimatedComponent') return true
+  return false
+}
+
 /**
  * Mutate an already-parsed Babel AST in place:
  *  - Rewrite every JSX `className="…"` / `className={expr}` attribute to
@@ -168,6 +339,7 @@ export function transformAst(ast: File, options: TransformAstOptions): Transform
   const literals: string[] = []
   const prefixSet = buildPrefixSet(options.classNamePrefixes)
   const hapticHoister = createHapticHoister()
+  const isHostTag = buildHostLookup(ast, options.hostSources, options.hostComponents)
   const rewriteCtx: RewriteContext = {
     needsInsets: false,
     gradientAtoms: options.gradientAtoms ?? EMPTY_GRADIENT_ATOMS,
@@ -180,6 +352,15 @@ export function transformAst(ast: File, options: TransformAstOptions): Transform
   let touched = false
   let usedLookupCss = false
   let usedInteractiveBox = false
+  // Per-element host classification, captured the first time we see each
+  // JSXOpeningElement. Necessary because the InteractiveBox wrap mutates
+  // `parent.name` in-place from the original tag → `_ib`; sibling
+  // attributes processed AFTER the swap would otherwise re-classify off
+  // the now-meaningless `_ib` name and skip rewrites they should do
+  // (e.g. `contentContainerClassName` next to an `active:` className on
+  // the same `<ScrollView>`).
+  const customElements = new WeakSet<t.JSXOpeningElement>()
+  const classifiedElements = new WeakSet<t.JSXOpeningElement>()
 
   traverse(ast, {
     JSXAttribute(attributePath: NodePath<t.JSXAttribute>) {
@@ -187,6 +368,22 @@ export function transformAst(ast: File, options: TransformAstOptions): Transform
       if (!t.isJSXIdentifier(node.name)) return
       const target = classifyAttributeName(node.name.name, prefixSet)
       if (!target) return
+      // Skip className rewrite when the parent JSX tag is a custom
+      // component (not imported from a known host source). Custom
+      // components own their `className` prop — the transformer would
+      // steal the string from under them otherwise. The literal still
+      // appears in source text, so oxide still discovers its atoms via
+      // the project scan; the inner host that ultimately consumes the
+      // forwarded className gets rewritten by ITS file's transform.
+      const { parent } = attributePath
+      if (t.isJSXOpeningElement(parent)) {
+        if (!classifiedElements.has(parent)) {
+          classifiedElements.add(parent)
+          const tagText = jsxTagText(parent.name)
+          if (tagText !== null && !isHostTag(tagText)) customElements.add(parent)
+        }
+        if (customElements.has(parent)) return
+      }
       const rewritten = rewriteClassNameAttribute(attributePath, hoister, literals, rewriteCtx, target)
       if (!rewritten) return
       touched = true
@@ -334,10 +531,17 @@ function rewriteClassNameAttribute(
   const { node } = attributePath
   const { value } = node
   if (!value) return null
-  const buildResult = buildFirstArgument(value, hoister, literals, rewriteCtx)
-  if (!buildResult) return null
   const { parent } = attributePath
   if (!t.isJSXOpeningElement(parent)) return null
+  // The rewrite emits references to `_t` (the `useR_()` binding). That
+  // binding can only live in a component body — so if this JSX site has
+  // no enclosing component (e.g. a top-level `const renderItem = (...) =>
+  // <View className=.../>` helper), bail and leave className untouched
+  // rather than emit a dangling `_t`. Checked BEFORE any mutation
+  // (hoist, sibling-style drop) so a bail leaves the AST pristine.
+  if (!hasComponentBody(attributePath)) return null
+  const buildResult = buildFirstArgument(value, hoister, literals, rewriteCtx)
+  if (!buildResult) return null
   const userStyleExpr = extractAndDropSiblingStyle(parent, target.styleProp)
   // Single context binding `_t = _r()` — carries scheme, fontScale,
   // insets together so React tracks all three as render deps via one
@@ -388,25 +592,32 @@ function applyDerivedJsxAttributes(
 }
 
 /**
- * Splice gradient JSX attributes (`colors={…}` / `start={…}` /
- * `end={…}`) into a JSXOpeningElement's attribute list, replacing
- * any already-present attribute with the same name. Users who manually
- * set `colors=` on the same element lose; rnwind's class-derived
- * values win — matching how `className`-resolved styles override
- * inline `style={…}`.
+ * Splice class-derived JSX attributes (`colors={…}` / `start={…}` /
+ * `end={…}` for gradients; `numberOfLines=` / `ellipsizeMode=` for
+ * truncate) into a JSXOpeningElement's attribute list — but only when
+ * the developer hasn't already written that attribute themselves.
+ *
+ * **User attrs always win.** If a hand-written `colors={USER}` is
+ * present, the class-derived hoist is dropped on the floor for that
+ * specific attribute. Same rule for every derived prop, applied
+ * per-attribute so the user can override one slot (e.g. `start={…}`)
+ * and let rnwind fill in the others. Documented in
+ * `docs/architecture.md`.
  * @param opening JSXOpeningElement to mutate.
- * @param gradientAttrs Freshly built JSX attributes.
- * @param gradientAttributes
+ * @param gradientAttributes Freshly built JSX attributes.
  */
 function appendGradientAttributes(opening: t.JSXOpeningElement, gradientAttributes: readonly t.JSXAttribute[]): void {
-  const names = new Set<string>()
-  for (const attribute of gradientAttributes) if (t.isJSXIdentifier(attribute.name)) names.add(attribute.name.name)
-  opening.attributes = opening.attributes.filter((attribute) => {
-    if (!t.isJSXAttribute(attribute)) return true
-    if (!t.isJSXIdentifier(attribute.name)) return true
-    return !names.has(attribute.name.name)
-  })
-  opening.attributes.push(...gradientAttributes)
+  const userAttributeNames = new Set<string>()
+  for (const attribute of opening.attributes) {
+    if (!t.isJSXAttribute(attribute)) continue
+    if (!t.isJSXIdentifier(attribute.name)) continue
+    userAttributeNames.add(attribute.name.name)
+  }
+  for (const derived of gradientAttributes) {
+    if (!t.isJSXIdentifier(derived.name)) continue
+    if (userAttributeNames.has(derived.name.name)) continue
+    opening.attributes.push(derived)
+  }
 }
 
 /**
@@ -1183,6 +1394,26 @@ function injectContextHook(path: NodePath): string {
   return CONTEXT_BINDING
 }
 
+/**
+ * Whether `path` sits inside a recognised function component — i.e.
+ * {@link injectContextHook} would find a body to host `const _t =
+ * useR_()`. Pure lookup that mirrors {@link findComponentBody}'s walk
+ * but performs NO body promotion, so a caller can bail before mutating
+ * when the answer is no.
+ * @param path Rewrite-site path.
+ * @returns True when an enclosing component function exists.
+ */
+function hasComponentBody(path: NodePath): boolean {
+  let current: NodePath | null = path
+  while (current) {
+    const fn = current.findParent((parent) => parent.isFunction())
+    if (!fn) return false
+    if (isComponentFunction(fn)) return true
+    current = fn
+  }
+  return false
+}
+
 /**
  * Walk up from `path` to the nearest recognised function component.
  * Accepts:

package/src/metro/transformer.ts

@@ -3,8 +3,9 @@ import * as t from '@babel/types'
 import { parse } from '@babel/parser'
 import generate from '@babel/generator'
 import { createHash } from 'node:crypto'
+import { realpathSync } from 'node:fs'
 import { transformAst } from './transform-ast'
-import { getClassNamePrefixes, getRnwindCacheKey, getRnwindState, onThemeChange } from './state'
+import { getClassNamePrefixes, getHostComponents, getHostSources, getRnwindCacheKey, getRnwindState, onThemeChange } from './state'
 import { STYLE_SPECIFIERS, THEME_SIGNATURE_MODULE } from './resolver'
 import { filterUnknownClassCandidates } from './warn-unknown-classes'
 
@@ -131,6 +132,8 @@ async function rewriteSource(args: BabelTransformerArgs): Promise<string> {
   warnUnknownClasses(args.src, parsed.candidates, parsed.atoms, args.filename)
 
   const classNamePrefixes = getClassNamePrefixes()
+  const hostSources = getHostSources()
+  const hostComponents = getHostComponents()
   if (parsed.atoms.size === 0) {
     state.builder.dropFile(args.filename)
     await state.builder.writeSchemes()
@@ -139,6 +142,8 @@ async function rewriteSource(args: BabelTransformerArgs): Promise<string> {
       gradientAtoms: parsed.gradientAtoms,
       hapticAtoms: parsed.hapticAtoms,
       classNamePrefixes,
+      hostSources,
+      hostComponents,
     })
     injectThemeSignatureImport(ast)
     return generateModule(ast).code
@@ -152,6 +157,8 @@ async function rewriteSource(args: BabelTransformerArgs): Promise<string> {
     gradientAtoms: parsed.gradientAtoms,
     hapticAtoms: parsed.hapticAtoms,
     classNamePrefixes,
+    hostSources,
+    hostComponents,
   })
   injectThemeSignatureImport(ast)
   return generateModule(ast).code
@@ -232,13 +239,31 @@ function loadUpstream(): UpstreamTransformer | null {
 /**
  * Cheap guard — the file has to look JS/TS, live outside `node_modules`,
  * and mention `className=` before we spend AST cycles on it.
+ *
+ * Symlink awareness: monorepo workspaces (yarn / pnpm / bun workspaces)
+ * symlink each package into the consumer's `node_modules/<name>`, so a
+ * file from `packages/ui/src/Foo.tsx` ends up reaching the transformer
+ * as `<root>/node_modules/ui/src/Foo.tsx`. The naïve `/node_modules/`
+ * check would skip every workspace UI file. We `realpath` the filename
+ * once and only bail when the resolved real path is ALSO under
+ * node_modules — true third-party installs.
  * @param args Metro args.
  * @returns Whether the file might need the rnwind pass.
  */
 function isRewriteCandidate(args: BabelTransformerArgs): boolean {
   if (!/\.(?:tsx|ts|jsx|js)$/i.test(args.filename)) return false
-  if (args.filename.includes('/node_modules/')) return false
-  return args.src.includes('className=')
+  // Case-insensitive so `<prefix>ClassName=` (e.g. `contentContainerClassName=`)
+  // — which has a capital `C` and so doesn't contain the lowercase
+  // `className=` — still routes the file through the rewrite pass.
+  if (!/classname=/i.test(args.src)) return false
+  if (!args.filename.includes('/node_modules/')) return true
+  // node_modules in path → could be a workspace symlink; resolve it.
+  try {
+    return !realpathSync(args.filename).includes('/node_modules/')
+  } catch {
+    // realpath failed (broken symlink, missing file). Fall back to skipping.
+    return false
+  }
 }
 
 /**

package/src/metro/with-config.ts

@@ -134,6 +134,28 @@ export interface RnwindMetroOptions {
    * entries merge on top.
    */
   classNamePrefixes?: readonly string[]
+  /**
+   * Extra module specifiers whose JSX exports rnwind should treat as
+   * "host components" — i.e. tags whose `className="…"` attribute is
+   * rewritten to `style={lookupCss(…)}` at build time (zero runtime
+   * cost). Merged with the built-in defaults: `react-native`,
+   * `react-native-reanimated`, `react-native-svg`,
+   * `react-native-gesture-handler`, `expo-linear-gradient`, `expo-image`.
+   *
+   * Anything NOT marked as a host has its `className` left untouched —
+   * the importing component receives the raw string and decides what
+   * to do with it. Use this option to opt your design-system / UI
+   * primitive packages into the zero-runtime path.
+   */
+  hostSources?: readonly string[]
+  /**
+   * Extra JSX tag names (verbatim — may include `.` for member access
+   * like `'Animated.View'`) rnwind should treat as host components,
+   * regardless of where they're imported from. Useful for one-off
+   * escape-hatches: `import { View as MyBox } from 'react-native'`
+   * doesn't change the local name → `'MyBox'` here picks it up.
+   */
+  hostComponents?: readonly string[]
 }
 
 /** Shape we mutate on Metro's config. Loose so we don't pin Metro's internal types. */
@@ -180,7 +202,7 @@ export function withRnwindConfig<C extends MetroConfigLike>(metroConfig: C, opti
 
   mkdirSync(cacheDir, { recursive: true })
   const watchFolders = (metroConfig.watchFolders ?? []).filter((p) => typeof p === 'string' && p.length > 0)
-  configureRnwindState(cssEntry, cacheDir, watchFolders, options.classNamePrefixes)
+  configureRnwindState(cssEntry, cacheDir, watchFolders, options.classNamePrefixes, options.hostSources, options.hostComponents)
 
   // Warm the state eagerly (in the Metro master process) so oxide's
   // Scanner walks every project source (and every monorepo