rnwind 0.0.1 → 0.0.3

package/lib/esm/metro/transformer.mjs

@@ -0,0 +1,349 @@
+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.mjs';
+import { onThemeChange, getRnwindState, getRnwindCacheKey, getClassNamePrefixes, getHostSources, getHostComponents } from './state.mjs';
+import { THEME_SIGNATURE_MODULE, STYLE_SPECIFIERS } from './resolver.mjs';
+import { filterUnknownClassCandidates } from './warn-unknown-classes.mjs';
+
+/** 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 = null;
+const generateModule = 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) {
+    try {
+        return parse(source, {
+            sourceType: 'unambiguous',
+            allowReturnOutsideFunction: true,
+            allowImportExportEverywhere: true,
+            plugins: ['typescript', 'jsx'],
+        });
+    }
+    catch {
+        try {
+            return parse(source, {
+                sourceType: 'unambiguous',
+                allowReturnOutsideFunction: true,
+                allowImportExportEverywhere: true,
+                plugins: ['flow', 'jsx'],
+            });
+        }
+        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, candidates, atoms, filename) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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();
+    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);
+    if (changed)
+        await state.builder.writeSchemes();
+    transformAst(ast, {
+        styleSpecifiers: STYLE_SPECIFIERS,
+        gradientAtoms: parsed.gradientAtoms,
+        hapticAtoms: parsed.hapticAtoms,
+        classNamePrefixes,
+        hostSources,
+        hostComponents,
+    });
+    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) {
+    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() {
+    const upstream = loadUpstream();
+    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) {
+    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() {
+    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);
+        const upstream = required.default ?? required;
+        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.
+ *
+ * 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) {
+    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;
+    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;
+    }
+}
+/**
+ * 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) {
+    return parse(source, { sourceType: 'module', plugins: ['typescript', 'jsx'] });
+}
+/**
+ * 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.
+ */
+async function transform(args) {
+    // 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' }) };
+    }
+    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.
+ */
+function getCacheKey() {
+    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. */
+function __resetUpstreamCache() {
+    cachedUpstream = null;
+}
+
+export { __resetUpstreamCache, getCacheKey, transform };
+//# sourceMappingURL=transformer.mjs.map

package/lib/esm/metro/transformer.mjs.map

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

package/lib/esm/metro/warn-unknown-classes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 declare function filterUnknownClassCandidates(source: string, candidates: readonly string[], atoms: ReadonlySet<string>): string[];

package/lib/esm/metro/warn-unknown-classes.mjs

@@ -0,0 +1,84 @@
+/**
+ * Yield every literal-text segment found at a `className=` site.
+ * @param source Raw source text.
+ * @yields Each literal's inner text.
+ */
+function* iterateClassNameLiterals(source) {
+    // 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) {
+    const out = new Set();
+    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.
+ */
+function filterUnknownClassCandidates(source, candidates, atoms) {
+    const literalTokens = collectClassNameTokens(source);
+    const out = [];
+    for (const candidate of candidates) {
+        if (atoms.has(candidate))
+            continue;
+        if (!literalTokens.has(candidate))
+            continue;
+        out.push(candidate);
+    }
+    return out;
+}
+
+export { filterUnknownClassCandidates };
+//# sourceMappingURL=warn-unknown-classes.mjs.map

package/lib/esm/metro/warn-unknown-classes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"warn-unknown-classes.mjs","sources":["../../../../src/metro/warn-unknown-classes.ts"],"sourcesContent":["/**\n * Yield every literal-text segment found at a `className=` site.\n * @param source Raw source text.\n * @yields Each literal's inner text.\n */\nfunction* iterateClassNameLiterals(source: string): Iterable<string> {\n  // className=\"...\"  /  className='...'\n  for (const match of source.matchAll(/className\\s*=\\s*\"([^\"]*)\"/g)) yield match[1] ?? ''\n  for (const match of source.matchAll(/className\\s*=\\s*'([^']*)'/g)) yield match[1] ?? ''\n  // className={\"...\"}  /  className={'...'}\n  for (const match of source.matchAll(/className\\s*=\\s*\\{\\s*\"([^\"]*)\"\\s*\\}/g)) yield match[1] ?? ''\n  for (const match of source.matchAll(/className\\s*=\\s*\\{\\s*'([^']*)'\\s*\\}/g)) yield match[1] ?? ''\n  // className={`...`} — yield each static quasi between `${...}` substitutions.\n  for (const match of source.matchAll(/className\\s*=\\s*\\{\\s*`([^`]*)`\\s*\\}/g)) {\n    const body = match[1] ?? ''\n    for (const part of body.split(/\\$\\{[^}]*\\}/)) yield part\n  }\n}\n\n/**\n * Pull every `className=\"…\"`, `className={'…'}`, `className={\"…\"}`, and\n * `className={\\`…\\`}` literal out of the source and union their\n * whitespace-separated tokens. A regex-based scan is enough — the\n * warning is best-effort, not load-bearing, and a regex sidesteps\n * having to re-parse the file.\n *\n * Skipped on purpose:\n *  - `className={someExpression}` with no inline literal (we can't\n *    introspect the runtime value at build time).\n *  - Template literals with substitutions (`` `text-${size}` ``) — we\n *    only union the static-quasi parts, which is fine because the\n *    warning fires only on candidates that ARE in the static parts.\n * @param source Raw source text.\n * @returns Set of whitespace-separated tokens drawn from every literal.\n */\nfunction collectClassNameTokens(source: string): Set<string> {\n  const out = new Set<string>()\n  for (const literal of iterateClassNameLiterals(source)) {\n    for (const token of literal.split(/\\s+/)) {\n      if (token.length > 0) out.add(token)\n    }\n  }\n  return out\n}\n\n/**\n * Filter Tailwind candidate strings down to ones that actually appear\n * as a token inside a `className=\"…\"` literal in the source. Oxide\n * scans the entire file and surfaces anything Tailwind-shaped — that\n * includes import specifiers (`'expo-router'`), comment markers\n * (`/* @rnwind-theme=… *\\/`), JSX prop values (`keyboardType=\"email-\n * address\"`), and bare suffixes Tailwind splits out from compound\n * utilities (`bg-sky-500` also produces `sky-500`). None of those are\n * \"unknown classes\" worth nagging the user about; the genuine signal\n * is a typo in a real `className`, e.g. `bg-srface` for `bg-surface`.\n *\n * The filter walks every `className=\"…\" / {'…'} / {`…`}` literal in the\n * source, splits each on whitespace, and unions the tokens. Only\n * candidates in that token set survive. Then known-good atoms are\n * subtracted, leaving genuine typos.\n * @param source Raw source text the transformer received from Metro.\n * @param candidates Every candidate oxide picked up.\n * @param atoms Set of atom names the parser successfully resolved.\n * @returns Candidates that look like real \"unknown classes\" the user typed.\n */\nexport function filterUnknownClassCandidates(\n  source: string,\n  candidates: readonly string[],\n  atoms: ReadonlySet<string>,\n): string[] {\n  const literalTokens = collectClassNameTokens(source)\n  const out: string[] = []\n  for (const candidate of candidates) {\n    if (atoms.has(candidate)) continue\n    if (!literalTokens.has(candidate)) continue\n    out.push(candidate)\n  }\n  return out\n}\n"],"names":[],"mappings":"AAAA;;;;AAIG;AACH,UAAU,wBAAwB,CAAC,MAAc,EAAA;;IAE/C,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,QAAQ,CAAC,4BAA4B,CAAC;AAAE,QAAA,MAAM,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE;IACvF,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,QAAQ,CAAC,4BAA4B,CAAC;AAAE,QAAA,MAAM,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE;;IAEvF,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,QAAQ,CAAC,sCAAsC,CAAC;AAAE,QAAA,MAAM,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE;IACjG,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,QAAQ,CAAC,sCAAsC,CAAC;AAAE,QAAA,MAAM,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE;;IAEjG,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,QAAQ,CAAC,sCAAsC,CAAC,EAAE;QAC3E,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE;QAC3B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC;AAAE,YAAA,MAAM,IAAI;IAC1D;AACF;AAEA;;;;;;;;;;;;;;;AAeG;AACH,SAAS,sBAAsB,CAAC,MAAc,EAAA;AAC5C,IAAA,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU;IAC7B,KAAK,MAAM,OAAO,IAAI,wBAAwB,CAAC,MAAM,CAAC,EAAE;QACtD,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;AACxC,YAAA,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;AAAE,gBAAA,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC;QACtC;IACF;AACA,IAAA,OAAO,GAAG;AACZ;AAEA;;;;;;;;;;;;;;;;;;;AAmBG;SACa,4BAA4B,CAC1C,MAAc,EACd,UAA6B,EAC7B,KAA0B,EAAA;AAE1B,IAAA,MAAM,aAAa,GAAG,sBAAsB,CAAC,MAAM,CAAC;IACpD,MAAM,GAAG,GAAa,EAAE;AACxB,IAAA,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE;AAClC,QAAA,IAAI,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE;AAC1B,QAAA,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE;AACnC,QAAA,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;IACrB;AACA,IAAA,OAAO,GAAG;AACZ;;;;"}

package/lib/esm/metro/with-config.d.ts

@@ -0,0 +1,79 @@
+import { type ResolveRequestFn } from './resolver';
+/** 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[];
+    /**
+     * 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. */
+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 declare function withRnwindConfig<C extends MetroConfigLike>(metroConfig: C, options: RnwindMetroOptions): C;