rnwind 0.0.3 → 0.0.5

package/src/metro/transformer.ts

@@ -4,8 +4,8 @@ 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, getHostComponents, getHostSources, getRnwindCacheKey, getRnwindState, onThemeChange } from './state'
+import { getRnwindCacheKey, getRnwindState, getWrapModules, onThemeChange } from './state'
+import { rewriteWrapImports } from './wrap-imports'
 import { STYLE_SPECIFIERS, THEME_SIGNATURE_MODULE } from './resolver'
 import { filterUnknownClassCandidates } from './warn-unknown-classes'
 
@@ -62,15 +62,23 @@ function parseUserSource(source: string): File | null {
  * @param candidates Every candidate oxide surfaced from the source.
  * @param atoms Successfully resolved atoms (keys are class names).
  * @param filename Source path, prefixed onto the warning.
+ * @param features Feature-atom maps (gradient / haptic) — their names are
+ *   known classes even though they carry no RN style, so they're excluded
+ *   from the unknown-class warning.
  */
 function warnUnknownClasses(
   source: string,
   candidates: readonly string[],
   atoms: ReadonlyMap<string, unknown>,
   filename: string,
+  features: ReadonlyArray<ReadonlyMap<string, unknown>> = [],
 ): void {
-  const atomNames = new Set(atoms.keys())
-  const unknown = filterUnknownClassCandidates(source, candidates, atomNames)
+  // Feature atoms (gradient / haptic) resolve to no RN style, so they're
+  // absent from `atoms` — but they're NOT unknown. Fold their names into
+  // the known set so `active:haptic-rigid` etc. don't warn at build time.
+  const known = new Set(atoms.keys())
+  for (const map of features) for (const name of map.keys()) known.add(name)
+  const unknown = filterUnknownClassCandidates(source, candidates, known)
   if (unknown.length === 0) return
   // eslint-disable-next-line no-console
   console.warn(`rnwind: unknown class${unknown.length > 1 ? 'es' : ''} in ${filename}: ${unknown.join(', ')}`)
@@ -114,56 +122,183 @@ function isThemeCssEntry(filename: string): boolean {
 }
 
 /**
- * Parse + run rnwind's JSX rewrite + regenerate source code. When
- * parsing or transformation fails, fall back to the original source —
- * we don't want a transient parse error to crash Metro for a file the
- * upstream might handle fine.
+ * Wrap host imports + compile any className literals, then regenerate
+ * source. Two paths:
+ *  - **className present**: oxide-scan the file, record its atoms into
+ *    the union, and inject the generated-style + theme-signature
+ *    side-effect imports so the runtime registries populate.
+ *  - **import-only** (a `{...rest}` forwarder or a leaf with no literal
+ *    `className=`): just wrap the host imports so a forwarded className
+ *    still resolves at render — no oxide scan, no injected imports.
+ *
+ * On parse failure, fall back to the original source — a transient parse
+ * error shouldn't crash Metro for a file the upstream might handle fine.
  * @param args Metro args; `src` is the original source text.
- * @returns Rewritten source text (with `className=` rewrites applied).
+ * @returns Rewritten source text.
  */
 async function rewriteSource(args: BabelTransformerArgs): Promise<string> {
   const ast = parseUserSource(args.src)
   if (!ast) return args.src
 
+  // Wrap host component imports so `<View className=…>` resolves at render
+  // through the runtime `wrap` (works for literal, spread, and forwarded
+  // classNames alike). No JSX is rewritten here.
+  const wrapped = rewriteWrapImports(ast, getWrapModules())
+
+  if (!/classname=/i.test(args.src)) {
+    // Import-only file: nothing to compile. Drop any stale atom
+    // contribution (className may have just been removed) and emit the
+    // wrapped imports — or the untouched source when nothing wrapped.
+    dropFileSafely(args.filename, projectRootOf(args))
+    return wrapped ? generateModule(ast).code : args.src
+  }
+
   const state = getRnwindState(projectRootOf(args))
   const extension = extensionOf(args.filename)
   const parsed = await state.parser.parseAtoms({ content: args.src, extension })
 
-  warnUnknownClasses(args.src, parsed.candidates, parsed.atoms, args.filename)
+  warnUnknownClasses(args.src, parsed.candidates, parsed.atoms, args.filename, [parsed.gradientAtoms, parsed.hapticAtoms])
 
-  const classNamePrefixes = getClassNamePrefixes()
-  const hostSources = getHostSources()
-  const hostComponents = getHostComponents()
   if (parsed.atoms.size === 0) {
     state.builder.dropFile(args.filename)
     await state.builder.writeSchemes()
-    transformAst(ast, {
-      styleSpecifiers: [],
-      gradientAtoms: parsed.gradientAtoms,
-      hapticAtoms: parsed.hapticAtoms,
-      classNamePrefixes,
-      hostSources,
-      hostComponents,
-    })
     injectThemeSignatureImport(ast)
     return generateModule(ast).code
   }
 
-  const { changed } = await state.builder.recordFile(args.filename, parsed.atoms, parsed.keyframes)
+  const literals = collectClassNameLiterals(ast)
+  const { changed } = await state.builder.recordFile(args.filename, parsed.atoms, parsed.keyframes, literals)
   if (changed) await state.builder.writeSchemes()
 
-  transformAst(ast, {
-    styleSpecifiers: STYLE_SPECIFIERS as unknown as readonly string[],
-    gradientAtoms: parsed.gradientAtoms,
-    hapticAtoms: parsed.hapticAtoms,
-    classNamePrefixes,
-    hostSources,
-    hostComponents,
-  })
+  injectSideEffectImports(ast, STYLE_SPECIFIERS)
   injectThemeSignatureImport(ast)
   return generateModule(ast).code
 }
 
+/**
+ * Drop a file's union contribution, swallowing the "state not configured"
+ * error unit tests hit when they call the transformer without
+ * `configureRnwindState`.
+ * @param filename Absolute source path.
+ * @param projectRoot Project root for state lookup.
+ */
+function dropFileSafely(filename: string, projectRoot: string): void {
+  try {
+    getRnwindState(projectRoot).builder.dropFile(filename)
+  } catch {
+    // State not configured (standalone/unit test). Nothing to drop.
+  }
+}
+
+/**
+ * Whether a JSX attribute names a className-style prop (`className` or
+ * any `<prefix>ClassName`).
+ * @param node JSX attribute node.
+ * @returns True when the attribute is a className prop.
+ */
+function isClassNameAttribute(node: t.JSXAttribute): boolean {
+  if (!t.isJSXIdentifier(node.name)) return false
+  const {name} = node.name
+  return name === 'className' || name.endsWith('ClassName')
+}
+
+/**
+ * Pull static string literals out of a className expression. Handles a
+ * bare string, a no-substitution template, and the branches of a
+ * ternary / `&&` (so `cond ? 'a' : 'b'` and `flag && 'x'` both register
+ * their literals). Dynamic interpolations are skipped — they resolve via
+ * the runtime atom path.
+ * @param expr Expression inside a `className={...}` container.
+ * @param out Accumulator for discovered literals.
+ */
+function collectLiteralsFromExpression(expr: t.Expression | t.JSXEmptyExpression | null | undefined, out: string[]): void {
+  if (!expr) return
+  if (t.isStringLiteral(expr)) {
+    out.push(expr.value)
+    return
+  }
+  if (t.isTemplateLiteral(expr) && expr.expressions.length === 0 && expr.quasis.length === 1) {
+    const cooked = expr.quasis[0]?.value.cooked
+    if (typeof cooked === 'string') out.push(cooked)
+    return
+  }
+  if (t.isConditionalExpression(expr)) {
+    collectLiteralsFromExpression(expr.consequent, out)
+    collectLiteralsFromExpression(expr.alternate, out)
+    return
+  }
+  if (t.isLogicalExpression(expr)) {
+    collectLiteralsFromExpression(expr.right as t.Expression, out)
+  }
+}
+
+/** AST node keys the literal walk skips — position / comment metadata. */
+const SKIP_WALK_KEYS = new Set(['type', 'loc', 'start', 'end', 'range', 'leadingComments', 'trailingComments', 'innerComments'])
+
+/**
+ * Collect the static literals from one className JSX attribute into the
+ * dedup accumulator.
+ * @param attribute The (already className-matched) JSX attribute.
+ * @param seen Dedup set of literals already collected.
+ * @param out Ordered accumulator.
+ */
+function collectAttributeLiterals(attribute: t.JSXAttribute, seen: Set<string>, out: string[]): void {
+  const { value } = attribute
+  const found: string[] = []
+  if (t.isStringLiteral(value)) found.push(value.value)
+  else if (t.isJSXExpressionContainer(value)) collectLiteralsFromExpression(value.expression, found)
+  for (const literal of found) {
+    if (seen.has(literal)) continue
+    seen.add(literal)
+    out.push(literal)
+  }
+}
+
+/**
+ * Walk the AST for every `className=` / `<prefix>ClassName=` literal so
+ * the builder can pre-merge each into a per-scheme molecule. A generic
+ * node walk (no scope build) keeps it cheap; only JSX attribute nodes do
+ * any work.
+ * @param ast Parsed Babel file.
+ * @returns Distinct literal className strings, in first-seen order.
+ */
+function collectClassNameLiterals(ast: File): readonly string[] {
+  const out: string[] = []
+  const seen = new Set<string>()
+  const visit = (node: unknown): void => {
+    if (!node || typeof node !== 'object') return
+    if (Array.isArray(node)) {
+      for (const child of node) visit(child)
+      return
+    }
+    const typed = node as { type?: string; [key: string]: unknown }
+    if (typeof typed.type !== 'string') return
+    if (typed.type === 'JSXAttribute' && isClassNameAttribute(node as t.JSXAttribute)) {
+      collectAttributeLiterals(node as t.JSXAttribute, seen, out)
+    }
+    for (const key in typed) {
+      if (SKIP_WALK_KEYS.has(key)) continue
+      visit(typed[key])
+    }
+  }
+  visit(ast.program)
+  return out
+}
+
+/**
+ * Prepend side-effect imports (`import '<spec>'`) so the generated
+ * per-scheme style + manifest modules load — registering this file's
+ * atoms / molecules / features into the runtime registries the wrapper's
+ * `resolve` reads.
+ * @param ast Babel File AST to mutate in place.
+ * @param specifiers Module specifiers to side-effect-import.
+ */
+function injectSideEffectImports(ast: File, specifiers: readonly string[]): void {
+  for (const specifier of specifiers) {
+    ast.program.body.unshift(t.importDeclaration([], t.stringLiteral(specifier)))
+  }
+}
+
 /**
  * Prepend `import 'rnwind/__generated/theme-signature'` to every
  * rnwind-transformed file. The resolver maps that specifier to the
@@ -252,10 +387,16 @@ function loadUpstream(): UpstreamTransformer | null {
  */
 function isRewriteCandidate(args: BabelTransformerArgs): boolean {
   if (!/\.(?:tsx|ts|jsx|js)$/i.test(args.filename)) return false
-  // 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
+  // Process the file when it either:
+  //  - carries a `className=` / `<prefix>ClassName=` literal (case-
+  //    insensitive — `contentContainerClassName=` has a capital C), or
+  //  - spreads props (`{...rest}`) onto a host from a wrap-module, where a
+  //    forwarded className must still get its import wrapped (no literal
+  //    appears in this file). A style-less `<View/>` with neither is left
+  //    alone so it never pays for an unused wrapper.
+  const hasClassName = /classname=/i.test(args.src)
+  const isForwarder = /\{\s*\.\.\./.test(args.src) && mentionsWrapModule(args.src)
+  if (!hasClassName && !isForwarder) return false
   if (!args.filename.includes('/node_modules/')) return true
   // node_modules in path → could be a workspace symlink; resolve it.
   try {
@@ -266,6 +407,21 @@ function isRewriteCandidate(args: BabelTransformerArgs): boolean {
   }
 }
 
+/**
+ * Cheap pre-parse check: does the source import from any configured
+ * wrap-module? A quoted specifier match is enough — `rewriteWrapImports`
+ * re-verifies precisely on the AST, so a false positive only costs a
+ * no-op parse.
+ * @param source Source text.
+ * @returns True when a wrap-module specifier appears in the source.
+ */
+function mentionsWrapModule(source: string): boolean {
+  for (const moduleName of getWrapModules().keys()) {
+    if (source.includes(`'${moduleName}'`) || source.includes(`"${moduleName}"`)) return true
+  }
+  return false
+}
+
 /**
  * Fallback parse when no upstream is configured AND Metro didn't hand
  * us an AST. Used by unit tests and standalone setups.

package/src/metro/with-config.ts

@@ -127,35 +127,20 @@ export interface RnwindMetroOptions {
   /** Cache directory. Absolute, or relative to `projectRoot`. Default: `.rnwind` at project root. */
   cacheDir?: string
   /**
-   * Extra JSX prop-name prefixes that rnwind should rewrite. Each
-   * prefix `P` turns `<Tag PClassName="…">` into `<Tag
-   * PStyle={lookupCss(…)}>`. The built-in `'contentContainer'` prefix
-   * is always on (covers ScrollView / FlatList / SectionList); user
-   * 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`,
+   * Extra module specifiers whose component exports rnwind should
+   * auto-wrap at import sites — `import { View } from 'react-native'`
+   * becomes `const View = wrap(_rnw0)` so `<View className="…">` resolves
+   * styles at runtime. Merged with the built-in defaults: `react-native`,
    * `react-native-reanimated`, `react-native-svg`,
-   * `react-native-gesture-handler`, `expo-linear-gradient`, `expo-image`.
+   * `react-native-gesture-handler`, `react-native-safe-area-context`,
+   * `expo-linear-gradient`, `expo-image`, and more.
    *
-   * 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.
+   * A module NOT in this list keeps its raw imports — the importing
+   * component receives `className` as a plain prop and can resolve it
+   * via `useCss` / `wrap` itself. Use this to opt your design-system /
+   * UI primitive packages into the auto-wrap path.
    */
-  hostComponents?: readonly string[]
+  wrapModules?: readonly string[]
 }
 
 /** Shape we mutate on Metro's config. Loose so we don't pin Metro's internal types. */
@@ -202,7 +187,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, options.hostSources, options.hostComponents)
+  configureRnwindState(cssEntry, cacheDir, watchFolders, options.wrapModules)
 
   // Warm the state eagerly (in the Metro master process) so oxide's
   // Scanner walks every project source (and every monorepo
@@ -238,7 +223,7 @@ export function withRnwindConfig<C extends MetroConfigLike>(metroConfig: C, opti
   if (options.dtsFile !== false) {
     const dtsPath = options.dtsFile ?? path.resolve(projectRoot, 'rnwind-types.d.ts')
     const schemes = discoverSchemes(cssEntry, projectRoot)
-    writeDtsFile(dtsPath, schemes, options.classNamePrefixes)
+    writeDtsFile(dtsPath, schemes)
   }
 
   // Watch the theme CSS. On edit, we rewrite scheme files AND touch

package/src/metro/wrap-imports.ts

@@ -0,0 +1,260 @@
+import * as t from '@babel/types'
+import type { File } from '@babel/types'
+
+/**
+ * Build-time import rewrite. For every `import { View } from
+ * 'react-native'` (and the other configured modules) it aliases the
+ * original export and binds a `wrap()`-ed component in its place:
+ *
+ * ```
+ * import { View, StyleSheet } from 'react-native'
+ * ⇩
+ * import { View as _rnw0, StyleSheet } from 'react-native'
+ * import { wrap as _rnwWrap } from 'rnwind'
+ * const View = _rnwWrap(_rnw0)
+ * ```
+ *
+ * Now `<View className="…">` resolves className → style at render via the
+ * wrapper — no matter how className arrived (literal, `{...rest}` spread,
+ * forwarded through custom layers). Non-component exports (`StyleSheet`)
+ * are left untouched.
+ */
+
+/** Local binding the injected `wrap` import is aliased to. */
+const WRAP_LOCAL = '_rnwWrap'
+/** Local binding the injected `wrapNamespace` import is aliased to. */
+const WRAP_NS_LOCAL = '_rnwWrapNs'
+/** Module the wrapper is imported from. */
+const RUNTIME_MODULE = 'rnwind'
+
+/**
+ * Wrap-modules whose DEFAULT export is a component NAMESPACE accessed via
+ * member expressions (`Animated.View`), not a single component. Their
+ * default import is bound through `wrapNamespace` (a Proxy that wraps each
+ * accessed component member) instead of `wrap`. Every other default import
+ * is treated as a plain component.
+ */
+const NAMESPACE_DEFAULT_MODULES: ReadonlySet<string> = new Set(['react-native-reanimated'])
+
+/**
+ * react-native mixes styleable components with utilities (`StyleSheet`,
+ * `Platform`, …). Only these named exports are wrapped; everything else
+ * passes through. Other ecosystem modules export components only and use
+ * the `'all'` policy instead.
+ */
+const REACT_NATIVE_COMPONENTS: ReadonlySet<string> = new Set([
+  'View',
+  'Text',
+  'TextInput',
+  'Pressable',
+  'ScrollView',
+  'Image',
+  'ImageBackground',
+  'FlatList',
+  'SectionList',
+  'VirtualizedList',
+  'KeyboardAvoidingView',
+  'SafeAreaView',
+  'Modal',
+  'Switch',
+  'RefreshControl',
+  'ActivityIndicator',
+  'TouchableOpacity',
+  'TouchableHighlight',
+  'TouchableWithoutFeedback',
+  'TouchableNativeFeedback',
+  'Button',
+  'StatusBar',
+])
+
+/**
+ * Named exports that LOOK like components (PascalCase) under an `'all'`
+ * policy but aren't — React contexts, gesture-handler enums/namespaces,
+ * etc. Wrapping these would turn `Gesture.Pan()` / `State.ACTIVE` /
+ * `<XContext.Provider>` into a `wrap()`-ed component and break them.
+ * Names ending in `Context` are excluded separately.
+ */
+const NON_COMPONENT_EXPORTS: ReadonlySet<string> = new Set([
+  'Gesture',
+  'GestureObjects',
+  'State',
+  'Directions',
+  'Extrapolation',
+  'Extrapolate',
+  'Easing',
+  'ReduceMotion',
+  'KeyframeRegistry',
+])
+
+/** Per-module policy: an explicit allow-list, or `'all'` named exports. */
+export type WrapPolicy = 'all' | ReadonlySet<string>
+
+/**
+ * Default module → wrap policy. react-native is allow-listed (mixed
+ * exports); the rest are component-only packages → `'all'`. Only modules
+ * the project has installed are ever hit (you can't import from a missing
+ * package), so listing optional peers is free.
+ */
+export const DEFAULT_WRAP_MODULES: ReadonlyMap<string, WrapPolicy> = new Map<string, WrapPolicy>([
+  ['react-native', REACT_NATIVE_COMPONENTS],
+  ['react-native-reanimated', 'all'],
+  ['react-native-svg', 'all'],
+  ['react-native-gesture-handler', 'all'],
+  ['react-native-safe-area-context', 'all'],
+  ['expo-linear-gradient', 'all'],
+  ['expo-image', 'all'],
+  ['expo-blur', 'all'],
+  ['expo-symbols', 'all'],
+  ['@shopify/flash-list', 'all'],
+  ['@shopify/react-native-skia', 'all'],
+  ['lottie-react-native', 'all'],
+])
+
+/**
+ * Whether a named import from a wrap-module should be wrapped.
+ *
+ * Explicit allow-lists (react-native) match by exact name. The `'all'`
+ * policy wraps only component-style names — PascalCase, not a React
+ * context (`*Context`), and not a known non-component export. This is
+ * what stops `useSafeAreaInsets` (a hook) from being wrapped into a
+ * component and crashing when called.
+ * @param policy The module's wrap policy.
+ * @param importedName The exported name being imported.
+ * @returns True when the name is a component to wrap.
+ */
+function shouldWrap(policy: WrapPolicy, importedName: string): boolean {
+  if (policy !== 'all') return policy.has(importedName)
+  if (!/^[A-Z]/.test(importedName)) return false
+  if (importedName.endsWith('Context')) return false
+  return !NON_COMPONENT_EXPORTS.has(importedName)
+}
+
+/**
+ * Merge user-supplied wrap modules onto the defaults — a bare module name
+ * adopts the `'all'` policy.
+ * @param extra User module specifiers (or undefined).
+ * @returns Effective module → policy map.
+ */
+export function buildWrapModules(extra?: readonly string[]): ReadonlyMap<string, WrapPolicy> {
+  if (!extra || extra.length === 0) return DEFAULT_WRAP_MODULES
+  const merged = new Map<string, WrapPolicy>(DEFAULT_WRAP_MODULES)
+  for (const moduleName of extra) if (!merged.has(moduleName)) merged.set(moduleName, 'all')
+  return merged
+}
+
+/**
+ * The `imported` name of an import specifier (`import { a as b }` → `'a'`).
+ * @param specifier Named import specifier.
+ * @returns The exported name.
+ */
+function importedNameOf(specifier: t.ImportSpecifier): string {
+  return t.isIdentifier(specifier.imported) ? specifier.imported.name : specifier.imported.value
+}
+
+/**
+ * Build `const Local = <wrapper>(alias)` and rebind the specifier's local
+ * to `alias` in place.
+ * @param specifier The import specifier to rebind.
+ * @param alias The `_rnwN` alias to bind the original import to.
+ * @param wrapper The runtime helper local (`_rnwWrap` / `_rnwWrapNs`).
+ * @returns The wrap declaration.
+ */
+function makeWrapDecl(
+  specifier: t.ImportSpecifier | t.ImportDefaultSpecifier | t.ImportNamespaceSpecifier,
+  alias: string,
+  wrapper: string,
+): t.VariableDeclaration {
+  const { name: localName } = specifier.local
+  specifier.local = t.identifier(alias)
+  return t.variableDeclaration('const', [
+    t.variableDeclarator(t.identifier(localName), t.callExpression(t.identifier(wrapper), [t.identifier(alias)])),
+  ])
+}
+
+/**
+ * Rewrite one import declaration's wrappable specifiers, aliasing each to
+ * `_rnw<N>` in place:
+ *  - named (`{ View }`) → `const View = wrap(_rnwN)` (per policy),
+ *  - namespace (`* as Animated`) → `const Animated = wrapNamespace(_rnwN)`,
+ *  - default → `wrapNamespace` for {@link NAMESPACE_DEFAULT_MODULES}
+ *    (reanimated's `Animated`), else `wrap` (a plain default component).
+ * @param node Import declaration to inspect.
+ * @param policy The module's wrap policy.
+ * @param counter Next alias index (caller-threaded for uniqueness).
+ * @returns New wrap declarations, advanced counter, and whether any
+ *   binding used `wrapNamespace`.
+ */
+function wrapSpecifiers(
+  node: t.ImportDeclaration,
+  policy: WrapPolicy,
+  counter: number,
+): { decls: t.VariableDeclaration[]; counter: number; usesNamespace: boolean } {
+  const decls: t.VariableDeclaration[] = []
+  const moduleName = node.source.value
+  let next = counter
+  let usesNamespace = false
+  for (const specifier of node.specifiers) {
+    if (t.isImportSpecifier(specifier)) {
+      if (!shouldWrap(policy, importedNameOf(specifier))) continue
+      decls.push(makeWrapDecl(specifier, `_rnw${next}`, WRAP_LOCAL))
+      next += 1
+      continue
+    }
+    const isNamespace = t.isImportNamespaceSpecifier(specifier) || NAMESPACE_DEFAULT_MODULES.has(moduleName)
+    const wrapper = isNamespace ? WRAP_NS_LOCAL : WRAP_LOCAL
+    decls.push(makeWrapDecl(specifier, `_rnw${next}`, wrapper))
+    next += 1
+    if (isNamespace) usesNamespace = true
+  }
+  return { decls, counter: next, usesNamespace }
+}
+
+/**
+ * Insert the `wrap` import at the top and the `const X = wrap(_rnwN)`
+ * declarations AFTER every import. The consts reference the aliased
+ * binding `_rnwN`, and in Metro's real transform (CommonJS interop + the
+ * reanimated worklets plugin) a const placed above its source import
+ * evaluates before the binding initialises → `ReferenceError: _rnw0
+ * doesn't exist`. ESM-only hoisting would mask this; the bundle does not.
+ * @param ast Parsed Babel file (mutated).
+ * @param wrapDecls The wrap declarations to place.
+ * @param usesNamespace Whether any binding used `wrapNamespace`.
+ */
+function placeWrapDecls(ast: File, wrapDecls: readonly t.VariableDeclaration[], usesNamespace: boolean): void {
+  const specifiers = [t.importSpecifier(t.identifier(WRAP_LOCAL), t.identifier('wrap'))]
+  if (usesNamespace) specifiers.push(t.importSpecifier(t.identifier(WRAP_NS_LOCAL), t.identifier('wrapNamespace')))
+  ast.program.body.unshift(t.importDeclaration(specifiers, t.stringLiteral(RUNTIME_MODULE)))
+  let afterImports = 0
+  for (let index = 0; index < ast.program.body.length; index += 1) {
+    if (t.isImportDeclaration(ast.program.body[index])) afterImports = index + 1
+  }
+  ast.program.body.splice(afterImports, 0, ...wrapDecls)
+}
+
+/**
+ * Rewrite component imports from the configured wrap-modules into
+ * `wrap()`-ed bindings, in place. Injects the `wrap` import once when any
+ * binding was rewritten.
+ * @param ast Parsed Babel file (mutated).
+ * @param modules Effective module → policy map.
+ * @returns True when at least one import was wrapped.
+ */
+export function rewriteWrapImports(ast: File, modules: ReadonlyMap<string, WrapPolicy>): boolean {
+  const wrapDecls: t.VariableDeclaration[] = []
+  let counter = 0
+  let usesNamespace = false
+
+  for (const node of ast.program.body) {
+    if (!t.isImportDeclaration(node)) continue
+    const policy = modules.get(node.source.value)
+    if (!policy) continue
+    const { decls, counter: nextCounter, usesNamespace: ns } = wrapSpecifiers(node, policy, counter)
+    counter = nextCounter
+    usesNamespace = usesNamespace || ns
+    wrapDecls.push(...decls)
+  }
+
+  if (wrapDecls.length === 0) return false
+  placeWrapDecls(ast, wrapDecls, usesNamespace)
+  return true
+}

package/src/runtime/components/rnwind-provider.tsx

@@ -96,23 +96,6 @@ export function useRnwind(): RnwindState {
   return useContext(RnwindContext)
 }
 
-/**
- * Internal context hook the babel transformer injects at the top of
- * every rewritten component as `const _t = useR_()`. Same body as the
- * public {@link useRnwind} — exposed under a `use*`-prefixed name so
- * react-refresh's babel plugin (which only tracks call-sites whose
- * identifier matches `^use[A-Z]`) folds it into each component's
- * fast-refresh signature. Without that prefix the signature stayed
- * stable across transformer changes; HMR then preserved fiber state
- * while the rendered hook list shifted, surfacing as "change in the
- * order of Hooks" runtime errors. Trailing underscore keeps it
- * visually distinct from the user-facing `useRnwind`.
- * @returns Active rnwind state.
- */
-export function useR_(): RnwindState {
-  return useContext(RnwindContext)
-}
-
 /**
  * Provider for rnwind's full runtime state. fontScale + windowWidth
  * come from `useWindowDimensions()` so they react to OS-level

package/src/runtime/hooks/use-css.ts

@@ -1,16 +1,22 @@
 import { useRnwind } from '../components/rnwind-provider'
-import { lookupCss } from '../lookup-css'
+import { resolve } from '../resolve'
 
 /**
- * Convenience hook: `useRnwind()` + `lookupCss()` rolled into one. Use
- * inside any component that wants the resolved style array without
- * threading the rnwind context manually. JSX-heavy components should
- * still call `useRnwind()` once and pass it to `lookupCss(...)` per
- * element so React only does a single context read per render.
- * @param className Raw className string or transformer-hoisted atom-name array.
- * @param userStyle Optional caller-supplied style appended last.
- * @returns Frozen style array for React Native's `style` prop.
+ * Resolve a className to a React Native `style` value against the active
+ * rnwind context (scheme, insets, fontScale, breakpoint). Molecule-fast:
+ * a literal className the scanner saw returns a pre-merged object by
+ * reference; anything else falls back to per-atom resolution. The escape
+ * hatch for custom components that hold a `className` prop:
+ *
+ * ```tsx
+ * function Card({ className, style, ...rest }) {
+ *   return <RNView style={useCss(className, style)} {...rest} />
+ * }
+ * ```
+ * @param className Raw className string.
+ * @param userStyle Optional caller-supplied style appended last (wins).
+ * @returns RN `style` value (a single object or an array).
  */
-export function useCss(className?: string | readonly string[] | null, userStyle?: unknown): readonly unknown[] {
-  return lookupCss(className, useRnwind(), userStyle)
+export function useCss(className?: string | null, userStyle?: unknown): unknown {
+  return resolve(className, useRnwind(), userStyle).style
 }