rnwind 0.0.1 → 0.0.2

package/src/metro/transformer.ts

@@ -0,0 +1,347 @@
+import type { File } from '@babel/types'
+import * as t from '@babel/types'
+import { parse } from '@babel/parser'
+import generate from '@babel/generator'
+import { createHash } from 'node:crypto'
+import { transformAst } from './transform-ast'
+import { getClassNamePrefixes, getRnwindCacheKey, getRnwindState, onThemeChange } from './state'
+import { STYLE_SPECIFIERS, THEME_SIGNATURE_MODULE } from './resolver'
+import { filterUnknownClassCandidates } from './warn-unknown-classes'
+
+/** The shape of the upstream module we delegate parsing/babel work to. */
+interface UpstreamTransformer {
+  transform: (args: BabelTransformerArgs) => Promise<BabelTransformerResult> | BabelTransformerResult
+}
+
+/** Env var that points at the upstream `babelTransformerPath` we override. */
+const UPSTREAM_ENV = 'RNWIND_UPSTREAM_TRANSFORMER'
+
+/** Cached upstream module — required once, reused across every transform call. */
+let cachedUpstream: UpstreamTransformer | null = null
+
+const generateModule = (generate as unknown as { default?: typeof generate }).default ?? generate
+
+/**
+ * Parse user source with the broad plugin set (Flow + JSX + TypeScript
+ * + class properties). Permissive on purpose so we don't reject any
+ * file the upstream could have handled. Returns `null` when parse
+ * fails — caller falls back to the raw source string.
+ * @param source Source text.
+ * @returns Parsed AST, or null on parse failure.
+ */
+function parseUserSource(source: string): File | null {
+  try {
+    return parse(source, {
+      sourceType: 'unambiguous',
+      allowReturnOutsideFunction: true,
+      allowImportExportEverywhere: true,
+      plugins: ['typescript', 'jsx'],
+    }) as unknown as File
+  } catch {
+    try {
+      return parse(source, {
+        sourceType: 'unambiguous',
+        allowReturnOutsideFunction: true,
+        allowImportExportEverywhere: true,
+        plugins: ['flow', 'jsx'],
+      }) as unknown as File
+    } catch {
+      return null
+    }
+  }
+}
+
+/**
+ * Print Tailwind-shaped candidates oxide picked up but the parser
+ * could NOT compile — typo, missing custom utility, or class not in
+ * the user's theme. Filtering by candidates that ALSO appear inside a
+ * `className="…"` literal eliminates false positives from imports,
+ * comments, and JSX prop values.
+ * @param source Original source text — searched for className literals.
+ * @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.
+ */
+function warnUnknownClasses(
+  source: string,
+  candidates: readonly string[],
+  atoms: ReadonlyMap<string, unknown>,
+  filename: string,
+): void {
+  const atomNames = new Set(atoms.keys())
+  const unknown = filterUnknownClassCandidates(source, candidates, atomNames)
+  if (unknown.length === 0) return
+  // eslint-disable-next-line no-console
+  console.warn(`rnwind: unknown class${unknown.length > 1 ? 'es' : ''} in ${filename}: ${unknown.join(', ')}`)
+}
+
+/**
+ * Extract the bare extension for oxide / internal switches.
+ * @param filename Absolute path.
+ * @returns Extension without the leading dot (`tsx` / `ts` / `js` / `jsx`).
+ */
+function extensionOf(filename: string): string {
+  const index = filename.lastIndexOf('.')
+  if (index === -1) return 'tsx'
+  return filename.slice(index + 1)
+}
+
+/**
+ * Read the project root Metro hands us per-transform. Falls back to
+ * `process.cwd()` only when the upstream harness doesn't set it (unit
+ * tests, standalone). Metro's production pipeline always sets it.
+ * @param args Metro transformer args.
+ * @returns Absolute project root.
+ */
+function projectRootOf(args: BabelTransformerArgs): string {
+  const fromOptions = args.options?.projectRoot
+  if (typeof fromOptions === 'string' && fromOptions.length > 0) return fromOptions
+  return process.cwd()
+}
+
+/**
+ * Whether a `.css` filename is the user's theme entry (the file
+ * `withRnwindConfig` pointed us at via `RNWIND_CSS_ENTRY_FILE`).
+ * Only the theme CSS should trigger a scheme rebuild — unrelated CSS
+ * files in the project stay invisible to rnwind.
+ * @param filename Absolute CSS path.
+ * @returns Whether the file is the configured theme entry.
+ */
+function isThemeCssEntry(filename: string): boolean {
+  const cssEntry = process.env.RNWIND_CSS_ENTRY_FILE
+  return typeof cssEntry === 'string' && cssEntry.length > 0 && cssEntry === filename
+}
+
+/**
+ * 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.
+ * @param args Metro args; `src` is the original source text.
+ * @returns Rewritten source text (with `className=` rewrites applied).
+ */
+async function rewriteSource(args: BabelTransformerArgs): Promise<string> {
+  const ast = parseUserSource(args.src)
+  if (!ast) return 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)
+
+  const classNamePrefixes = getClassNamePrefixes()
+  if (parsed.atoms.size === 0) {
+    state.builder.dropFile(args.filename)
+    await state.builder.writeSchemes()
+    transformAst(ast, {
+      styleSpecifiers: [],
+      gradientAtoms: parsed.gradientAtoms,
+      hapticAtoms: parsed.hapticAtoms,
+      classNamePrefixes,
+    })
+    injectThemeSignatureImport(ast)
+    return generateModule(ast).code
+  }
+
+  const { changed } = await state.builder.recordFile(args.filename, parsed.atoms, parsed.keyframes)
+  if (changed) await state.builder.writeSchemes()
+
+  transformAst(ast, {
+    styleSpecifiers: STYLE_SPECIFIERS as unknown as readonly string[],
+    gradientAtoms: parsed.gradientAtoms,
+    hapticAtoms: parsed.hapticAtoms,
+    classNamePrefixes,
+  })
+  injectThemeSignatureImport(ast)
+  return generateModule(ast).code
+}
+
+/**
+ * Prepend `import 'rnwind/__generated/theme-signature'` to every
+ * rnwind-transformed file. The resolver maps that specifier to the
+ * user's theme CSS so Metro's dependency graph carries a real edge
+ * from this JS file to the CSS. When the user edits `global.css`,
+ * the CSS module's SHA1 changes, and Metro invalidates every JS file
+ * holding this import — forcing them to re-transform with the new
+ * theme. The `.css` branch in {@link transform} returns an empty
+ * `export {}` module so the runtime cost is one extra `require()`.
+ * @param ast Babel File AST to mutate in place.
+ */
+function injectThemeSignatureImport(ast: File): void {
+  const declaration = t.importDeclaration([], t.stringLiteral(THEME_SIGNATURE_MODULE))
+  ast.program.body.unshift(declaration)
+}
+
+/**
+ * Read the upstream transformer's `getCacheKey()` so our cache-key
+ * contribution composes with — rather than replaces — whatever the
+ * host framework wants to mix in.
+ * @returns Upstream cache key, or `null` when no upstream exposes one.
+ */
+function loadUpstreamCacheKey(): string | null {
+  const upstream = loadUpstream() as (UpstreamTransformer & { getCacheKey?: () => string }) | null
+  if (!upstream) return null
+  try {
+    return typeof upstream.getCacheKey === 'function' ? upstream.getCacheKey() : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Invoke the upstream `babelTransformerPath` Metro originally had
+ * configured. The path is read from `RNWIND_UPSTREAM_TRANSFORMER`,
+ * which `withRnwindConfig` sets at Metro startup. When the env var is
+ * unset (unit tests, standalone use), fall back to a typescript+jsx
+ * parse.
+ * @param args Metro's per-file args.
+ * @returns Upstream transform result containing the post-babel AST.
+ */
+async function runUpstream(args: BabelTransformerArgs): Promise<BabelTransformerResult> {
+  if (args.ast && !process.env[UPSTREAM_ENV]) return { ast: args.ast }
+  const upstream = loadUpstream()
+  if (upstream) return await Promise.resolve(upstream.transform(args))
+  if (args.ast) return { ast: args.ast }
+  return { ast: parseSource(args.src) }
+}
+
+/**
+ * Lazily require the upstream transformer module. Cached after first
+ * load so per-file overhead is one cache lookup.
+ * @returns Upstream module, or null when env is unset.
+ */
+function loadUpstream(): UpstreamTransformer | null {
+  if (cachedUpstream) return cachedUpstream
+  const upstreamPath = process.env[UPSTREAM_ENV]
+  if (!upstreamPath || upstreamPath.length === 0) return null
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const required = require(upstreamPath) as UpstreamTransformer | { default?: UpstreamTransformer }
+    const upstream = (required as { default?: UpstreamTransformer }).default ?? (required as UpstreamTransformer)
+    if (typeof upstream.transform !== 'function') return null
+    cachedUpstream = upstream
+    return upstream
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    if (process.env.RNWIND_DEBUG) console.error('rnwind: failed to load upstream transformer:', error)
+    return null
+  }
+}
+
+/**
+ * Cheap guard — the file has to look JS/TS, live outside `node_modules`,
+ * and mention `className=` before we spend AST cycles on it.
+ * @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=')
+}
+
+/**
+ * Fallback parse when no upstream is configured AND Metro didn't hand
+ * us an AST. Used by unit tests and standalone setups.
+ * @param source Source text.
+ * @returns Parsed Babel File.
+ */
+function parseSource(source: string): File {
+  return parse(source, { sourceType: 'module', plugins: ['typescript', 'jsx'] }) as unknown as File
+}
+
+/** Metro's babel transformer signature. */
+export interface BabelTransformerArgs {
+  filename: string
+  src: string
+  options: { projectRoot?: string; [key: string]: unknown }
+  ast?: File
+  plugins?: readonly unknown[]
+}
+
+/** Return shape Metro expects from a babel transformer. */
+export interface BabelTransformerResult {
+  ast: File
+  metadata?: unknown
+}
+
+/**
+ * rnwind's Metro babel transformer. Two phases per source file:
+ *
+ *  1. **Pre-process the source string before handing it to the upstream
+ *     babel pipeline.** babel-preset-expo / React's JSX transform run
+ *     inside the upstream and convert `<View className="..."/>` into
+ *     `React.createElement(View, {className})`. If we walked the AST
+ *     AFTER the upstream, there'd be no JSX attributes left to
+ *     rewrite. So we parse, run our pass, regenerate code, and feed
+ *     THAT to the upstream as `src`.
+ *  2. **Delegate to the upstream `babelTransformerPath`** (Expo's
+ *     default handles Flow stripping, expo-router macros, etc.).
+ *
+ * Skip both phases when the file isn't a JS/TS source under user
+ * code, or doesn't mention `className=` — hand straight to upstream.
+ * @param args Metro's per-file args.
+ * @returns Mutated AST + metadata.
+ */
+export async function transform(args: BabelTransformerArgs): Promise<BabelTransformerResult> {
+  // Short-circuit `.css` inputs: the theme CSS is pulled into the dep
+  // graph as a sentinel (see `THEME_SIGNATURE_MODULE` in resolver.ts)
+  // so Metro watches it and invalidates importers on edit, but the
+  // file's CSS syntax can't go through a JS babel transformer.
+  //
+  // When the CSS being transformed IS the user's theme entry, we
+  // piggyback on Metro's own file-watcher: Metro calls us here on
+  // every CSS save; we trigger `onThemeChange` to rebuild parser +
+  // rewrite scheme files with the new values. Metro's dep graph then
+  // HMRs the regenerated `common.style.js` to the running app.
+  //
+  // Emitting the CSS content hash in the fake JS output is what makes
+  // Metro propagate invalidation to downstream importers — constant
+  // `export {}` bytes would never look changed and Metro would skip
+  // the chain.
+  if (args.filename.endsWith('.css')) {
+    if (isThemeCssEntry(args.filename)) {
+      try {
+        await onThemeChange(projectRootOf(args))
+      } catch {
+        // CSS edit happened outside a configured project (e.g. tests).
+      }
+    }
+    const themeHash = createHash('sha256').update(args.src).digest('hex').slice(0, 16)
+    const stub = `export const __rnwindThemeHash = ${JSON.stringify(themeHash)};\n`
+    return { ast: parse(stub, { sourceType: 'module' }) as unknown as File }
+  }
+  if (!isRewriteCandidate(args)) {
+    if (/\.(?:tsx|ts|jsx|js)$/i.test(args.filename) && !args.filename.includes('/node_modules/')) {
+      try {
+        getRnwindState(projectRootOf(args)).builder.dropFile(args.filename)
+      } catch {
+        // State not configured (e.g. test). Nothing to drop.
+      }
+    }
+    return runUpstream(args)
+  }
+
+  const rewrittenSource = await rewriteSource(args)
+  return runUpstream({ ...args, src: rewrittenSource, ast: undefined })
+}
+
+/**
+ * Metro's babel-transformer contract: a `getCacheKey()` export is
+ * sampled per-file and mixed into the transform cache key. Returning
+ * a string that includes the theme CSS content hash invalidates every
+ * cached transform on every CSS edit — so the bundle rebuilds with
+ * the new theme automatically on the next request.
+ * @returns Cache-key segment that includes rnwind's current theme hash.
+ */
+export function getCacheKey(): string {
+  const upstreamKey = loadUpstreamCacheKey()
+  const ownKey = getRnwindCacheKey()
+  return upstreamKey ? `${upstreamKey}|${ownKey}` : ownKey
+}
+
+/** Test-only — drop the cached upstream so a new env var picks up next call. */
+export function __resetUpstreamCache(): void {
+  cachedUpstream = null
+}

package/src/metro/warn-unknown-classes.ts

@@ -0,0 +1,79 @@
+/**
+ * Yield every literal-text segment found at a `className=` site.
+ * @param source Raw source text.
+ * @yields Each literal's inner text.
+ */
+function* iterateClassNameLiterals(source: string): Iterable<string> {
+  // className="..."  /  className='...'
+  for (const match of source.matchAll(/className\s*=\s*"([^"]*)"/g)) yield match[1] ?? ''
+  for (const match of source.matchAll(/className\s*=\s*'([^']*)'/g)) yield match[1] ?? ''
+  // className={"..."}  /  className={'...'}
+  for (const match of source.matchAll(/className\s*=\s*\{\s*"([^"]*)"\s*\}/g)) yield match[1] ?? ''
+  for (const match of source.matchAll(/className\s*=\s*\{\s*'([^']*)'\s*\}/g)) yield match[1] ?? ''
+  // className={`...`} — yield each static quasi between `${...}` substitutions.
+  for (const match of source.matchAll(/className\s*=\s*\{\s*`([^`]*)`\s*\}/g)) {
+    const body = match[1] ?? ''
+    for (const part of body.split(/\$\{[^}]*\}/)) yield part
+  }
+}
+
+/**
+ * Pull every `className="…"`, `className={'…'}`, `className={"…"}`, and
+ * `className={\`…\`}` literal out of the source and union their
+ * whitespace-separated tokens. A regex-based scan is enough — the
+ * warning is best-effort, not load-bearing, and a regex sidesteps
+ * having to re-parse the file.
+ *
+ * Skipped on purpose:
+ *  - `className={someExpression}` with no inline literal (we can't
+ *    introspect the runtime value at build time).
+ *  - Template literals with substitutions (`` `text-${size}` ``) — we
+ *    only union the static-quasi parts, which is fine because the
+ *    warning fires only on candidates that ARE in the static parts.
+ * @param source Raw source text.
+ * @returns Set of whitespace-separated tokens drawn from every literal.
+ */
+function collectClassNameTokens(source: string): Set<string> {
+  const out = new Set<string>()
+  for (const literal of iterateClassNameLiterals(source)) {
+    for (const token of literal.split(/\s+/)) {
+      if (token.length > 0) out.add(token)
+    }
+  }
+  return out
+}
+
+/**
+ * Filter Tailwind candidate strings down to ones that actually appear
+ * as a token inside a `className="…"` literal in the source. Oxide
+ * scans the entire file and surfaces anything Tailwind-shaped — that
+ * includes import specifiers (`'expo-router'`), comment markers
+ * (`/* @rnwind-theme=… *\/`), JSX prop values (`keyboardType="email-
+ * address"`), and bare suffixes Tailwind splits out from compound
+ * utilities (`bg-sky-500` also produces `sky-500`). None of those are
+ * "unknown classes" worth nagging the user about; the genuine signal
+ * is a typo in a real `className`, e.g. `bg-srface` for `bg-surface`.
+ *
+ * The filter walks every `className="…" / {'…'} / {`…`}` literal in the
+ * source, splits each on whitespace, and unions the tokens. Only
+ * candidates in that token set survive. Then known-good atoms are
+ * subtracted, leaving genuine typos.
+ * @param source Raw source text the transformer received from Metro.
+ * @param candidates Every candidate oxide picked up.
+ * @param atoms Set of atom names the parser successfully resolved.
+ * @returns Candidates that look like real "unknown classes" the user typed.
+ */
+export function filterUnknownClassCandidates(
+  source: string,
+  candidates: readonly string[],
+  atoms: ReadonlySet<string>,
+): string[] {
+  const literalTokens = collectClassNameTokens(source)
+  const out: string[] = []
+  for (const candidate of candidates) {
+    if (atoms.has(candidate)) continue
+    if (!literalTokens.has(candidate)) continue
+    out.push(candidate)
+  }
+  return out
+}

package/src/metro/with-config.ts

@@ -0,0 +1,229 @@
+import { existsSync, mkdirSync, utimesSync, watch as watchFile } from 'node:fs'
+import path from 'node:path'
+import { writeDtsFile } from './dts'
+import { createRnwindResolver, type ResolveRequestFn } from './resolver'
+import { configureRnwindState, getRnwindState, onThemeChange } from './state'
+
+/** Default cache directory at the project root. Visible for debugging. */
+const DEFAULT_CACHE_DIR = '.rnwind'
+
+/**
+ * Active CSS watcher — replaced (and the prior one closed) when
+ * `withRnwindConfig` is called again (Metro restart, repeated init).
+ * Only one watcher per process; no stacking.
+ */
+let activeCssWatcher: { cssPath: string; close: () => void } | null = null
+
+/**
+ * Watch the theme CSS for edits. On change, rewrite the per-scheme
+ * files with the fresh theme AND bump `mtime` on every source file
+ * rnwind has transformed so far — Metro's own watcher sees those
+ * mtime changes, invalidates the modules, and re-transforms them
+ * against the new CSS on the next request. `getCacheKey()` alone is
+ * NOT enough: Metro samples the cache key once per worker lifetime,
+ * so edits during an already-running dev server don't propagate
+ * without this explicit nudge.
+ * @param cssPath Absolute path to the theme CSS to watch.
+ * @param projectRoot Metro's project root (for `getRnwindState`).
+ */
+function watchThemeCss(cssPath: string, projectRoot: string): void {
+  if (activeCssWatcher?.cssPath === cssPath) return
+  activeCssWatcher?.close()
+  if (!existsSync(cssPath)) return
+  let pending = false
+  const watcher = watchFile(cssPath, { persistent: false }, () => {
+    // Debounce: editors often emit 2-3 change events per save (atomic
+    // rename dance, tmp files). Coalesce to ONE rebuild per microtask.
+    if (pending) return
+    pending = true
+    queueMicrotask(async () => {
+      pending = false
+      try {
+        await onThemeChange(projectRoot)
+        touchRecordedFiles(projectRoot)
+      } catch {
+        // Invalidation is best-effort — never crash the dev server.
+      }
+    })
+  })
+  activeCssWatcher = { cssPath, close: () => watcher.close() }
+}
+
+/**
+ * Bump the mtime on every file the builder has transformed. Metro's
+ * file watcher keys on `mtime`, so this is what makes it invalidate
+ * those modules and re-transform them.
+ * @param projectRoot Metro's project root.
+ */
+function touchRecordedFiles(projectRoot: string): void {
+  const state = getRnwindState(projectRoot)
+  const files = state.builder.recordedFiles()
+  const now = new Date()
+  for (const file of files) {
+    try {
+      if (existsSync(file)) utimesSync(file, now, now)
+    } catch {
+      // One file's stat failure shouldn't stop the others.
+    }
+  }
+}
+
+/**
+ * Where the rnwind babel transformer lives — resolved relative to this
+ * module so the path works from both the `src/` tree (tests) and the
+ * built `lib/` output. Tries a few extensions because `require.resolve`
+ * doesn't auto-find `.cjs` / `.mjs` from a bare specifier.
+ * @returns Absolute path to the rnwind transformer module.
+ */
+function transformerPath(): string {
+  for (const candidate of ['./transformer.cjs', './transformer.mjs', './transformer.js', './transformer.ts', './transformer']) {
+    try {
+      return require.resolve(candidate)
+    } catch {
+      // try the next extension
+    }
+  }
+  throw new Error('rnwind: could not resolve the metro transformer path')
+}
+
+/**
+ * Resolve the effective cache directory, honoring a user override and
+ * falling back to `<projectRoot>/.rnwind`.
+ * @param projectRoot Anchor for relative paths.
+ * @param override User-supplied option.
+ * @returns Absolute cache directory.
+ */
+function resolveCacheDir(projectRoot: string, override: string | undefined): string {
+  if (!override || override.length === 0) return path.resolve(projectRoot, DEFAULT_CACHE_DIR)
+  return path.isAbsolute(override) ? override : path.resolve(projectRoot, override)
+}
+
+/**
+ * Read the theme CSS and extract `@variant <name>` blocks for the .d.ts
+ * generator. Forces construction of `getRnwindState`, then reads
+ * `parser.declaredSchemes` (populated synchronously at construction).
+ * @param cssEntry Absolute path to theme CSS.
+ * @param projectRoot
+ * @returns Scheme names (empty when the theme has no variants; `'base'` is filtered).
+ */
+function discoverSchemes(cssEntry: string, projectRoot: string): readonly string[] {
+  if (!existsSync(cssEntry)) return []
+  try {
+    const { parser } = getRnwindState(projectRoot)
+    return parser.declaredSchemes.filter((name) => name !== 'base')
+  } catch {
+    return []
+  }
+}
+
+/** User-facing options for `withRnwindConfig`. */
+export interface RnwindMetroOptions {
+  /** Path to the theme CSS (absolute or relative to `projectRoot`). Required. */
+  cssEntryFile: string
+  /** Where rnwind writes the `.d.ts` file. Set `false` to disable. Defaults to `<projectRoot>/rnwind-types.d.ts`. */
+  dtsFile?: string | false
+  /** Optional project-root override — defaults to `metroConfig.projectRoot` then `process.cwd()`. */
+  projectRoot?: string
+  /** 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[]
+}
+
+/** Shape we mutate on Metro's config. Loose so we don't pin Metro's internal types. */
+export interface MetroConfigLike {
+  projectRoot?: string
+  watchFolders?: string[]
+  transformer?: {
+    babelTransformerPath?: string
+    [key: string]: unknown
+  }
+  resolver?: {
+    resolveRequest?: ResolveRequestFn | null
+    [key: string]: unknown
+  }
+  [key: string]: unknown
+}
+
+/**
+ * Wrap a Metro config with rnwind's pipeline:
+ *  - Install the rnwind babel transformer.
+ *  - Chain a `resolveRequest` hook that serves
+ *    `rnwind/__generated/schemes` from `<cacheDir>/schemes.js`.
+ *  - Write the `.d.ts` so TypeScript accepts `className=` on RN components.
+ *  - Publish the theme CSS path + cache dir via env so Metro workers
+ *    can rebuild their local state.
+ *  - Ensure the cache dir is a watched folder Metro's haste-map indexes.
+ *
+ * Theme-edit hot reload happens implicitly: every transformed file
+ * imports `rnwind/__generated/schemes`, and that module eager-imports
+ * `common.style.js`. When the theme changes, the per-scheme files
+ * regenerate with new bytes; Metro's content SHA1 dedup detects the
+ * change and invalidates every importer automatically.
+ * `getCacheKey()` on the transformer covers the per-file transform
+ * cache. No file watcher / source-padding hack needed — the dep graph
+ * carries the signal.
+ * @param metroConfig Config from `getDefaultConfig(__dirname)` or equivalent.
+ * @param options rnwind options.
+ * @returns The same config, mutated.
+ */
+export function withRnwindConfig<C extends MetroConfigLike>(metroConfig: C, options: RnwindMetroOptions): C {
+  const projectRoot = options.projectRoot ?? metroConfig.projectRoot ?? process.cwd()
+  const cacheDir = resolveCacheDir(projectRoot, options.cacheDir)
+  const cssEntry = path.isAbsolute(options.cssEntryFile) ? options.cssEntryFile : path.resolve(projectRoot, options.cssEntryFile)
+
+  mkdirSync(cacheDir, { recursive: true })
+  const watchFolders = (metroConfig.watchFolders ?? []).filter((p) => typeof p === 'string' && p.length > 0)
+  configureRnwindState(cssEntry, cacheDir, watchFolders, options.classNamePrefixes)
+
+  // Warm the state eagerly (in the Metro master process) so oxide's
+  // Scanner walks every project source (and every monorepo
+  // watch-folder) ONCE and the manifest + scheme files hold the
+  // complete union before Metro's resolver tries to SHA1 them on the
+  // first transform. Each worker lazy-repeats this scan on its first
+  // transform to converge on identical state.
+  try {
+    void getRnwindState(projectRoot).builder.ensureFilesExist()
+  } catch {
+    // Any init error surfaces again at the first transform; don't crash Metro boot.
+  }
+
+  // Install transformer + resolver. Capture the existing
+  // babelTransformerPath BEFORE we override it — our worker chains to
+  // it (env-passed) so Flow / expo-router / babel-preset-expo etc. all
+  // continue to run.
+  const existingTransformerPath = metroConfig.transformer?.babelTransformerPath
+  if (typeof existingTransformerPath === 'string' && existingTransformerPath.length > 0) {
+    process.env.RNWIND_UPSTREAM_TRANSFORMER = existingTransformerPath
+  }
+  const upstream = metroConfig.resolver?.resolveRequest ?? null
+  metroConfig.transformer = { ...metroConfig.transformer, babelTransformerPath: transformerPath() }
+  metroConfig.resolver = { ...metroConfig.resolver, resolveRequest: createRnwindResolver(upstream) }
+
+  // Metro's haste-map indexes `watchFolders` at startup. Adding the
+  // cache dir guarantees scheme style files + manifest get SHA1'd
+  // without a "Failed to get the SHA-1" race when the first transform
+  // writes them.
+  const existingWatch = metroConfig.watchFolders ?? []
+  metroConfig.watchFolders = existingWatch.includes(cacheDir) ? existingWatch : [...existingWatch, cacheDir]
+
+  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)
+  }
+
+  // Watch the theme CSS. On edit, we rewrite scheme files AND touch
+  // mtime on every transformed source file so Metro invalidates them
+  // and re-transforms — the only reliable way to propagate theme
+  // changes to an already-running dev server.
+  watchThemeCss(cssEntry, projectRoot)
+
+  return metroConfig
+}