rnwind 0.0.3 → 0.0.5

package/src/core/style-builder/union-builder.ts

@@ -1,7 +1,7 @@
 import { createHash, randomBytes } from 'node:crypto'
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
-import type { KeyframeBlock, SchemedStyle, TailwindParser } from '../parser'
+import type { GradientAtomInfo, HapticRequest, KeyframeBlock, SchemedStyle, TailwindParser } from '../parser'
 import { buildSchemeSources, type AtomSerializedCache } from './build-style'
 
 /** Manifest module basename — the file SchemeProvider imports via the resolver. */
@@ -90,6 +90,17 @@ class UnionBuilder {
   private readonly parser: TailwindParser
   private readonly unionAtoms = new Map<string, SchemedStyle>()
   private readonly unionKeyframes = new Map<string, KeyframeBlock>()
+  /** atom name → gradient role/colour, surfaced into the manifest's `registerGradients`. */
+  private readonly unionGradients = new Map<string, GradientAtomInfo>()
+  /** atom name → haptic request, surfaced into the manifest's `registerHaptics`. */
+  private readonly unionHaptics = new Map<string, HapticRequest>()
+  /**
+   * Distinct literal className strings seen across all files, pre-merged
+   * into per-scheme molecules at write time. Accumulate-only (like
+   * `unionAtoms`): orphaned literals just yield unused molecules and get
+   * reaped on the next cold start, so no refcount is needed.
+   */
+  private readonly unionLiterals = new Set<string>()
   /**
    * Responsive breakpoints captured from the parser. Refreshed on every
    * `recordFile` / `ensureProjectScanned` so user-defined
@@ -169,6 +180,8 @@ class UnionBuilder {
       const parsed = await this.parser.parseProject()
       for (const [name, style] of parsed.atoms) this.unionAtoms.set(name, style)
       for (const [name, kf] of parsed.keyframes) this.unionKeyframes.set(name, kf)
+      for (const [name, gradient] of parsed.gradientAtoms) this.unionGradients.set(name, gradient)
+      for (const [name, haptic] of parsed.hapticAtoms) this.unionHaptics.set(name, haptic)
       this.breakpoints = parsed.breakpoints
       this.projectScanned = true
     })()
@@ -187,6 +200,7 @@ class UnionBuilder {
    * @param file Absolute source file path.
    * @param atoms Per-atom resolved schemed styles from this transform.
    * @param keyframes Keyframe blocks referenced by this file's atoms.
+   * @param literals
    * @returns `{ changed: true }` when the union shifted (new atom name,
    *   removed atom name, or new keyframe) — the transformer uses this
    *   to skip the serializer + `writeSchemes` when nothing changed.
@@ -195,8 +209,10 @@ class UnionBuilder {
     file: string,
     atoms: ReadonlyMap<string, SchemedStyle>,
     keyframes: ReadonlyMap<string, KeyframeBlock>,
+    literals: readonly string[] = [],
   ): Promise<{ changed: boolean }> {
     await this.ensureProjectScanned()
+    const literalAdded = this.recordLiterals(literals)
     const newAtomNames = new Set(atoms.keys())
     const previous = this.fileAtomSets.get(file)
     if (previous && setsEqual(previous, newAtomNames)) {
@@ -211,12 +227,29 @@ class UnionBuilder {
         if (!this.unionKeyframes.has(name)) keyframeAdded = true
         this.unionKeyframes.set(name, kf)
       }
-      return { changed: keyframeAdded }
+      return { changed: keyframeAdded || literalAdded }
     }
     this.applyDiff(file, newAtomNames, atoms, keyframes)
     return { changed: true }
   }
 
+  /**
+   * Merge a file's literal classNames into the union. A literal the
+   * union hasn't seen flips `changed` so `writeSchemes` re-emits the
+   * scheme files with the new molecule.
+   * @param literals Distinct literal className strings.
+   * @returns Whether any literal was new to the union.
+   */
+  private recordLiterals(literals: readonly string[]): boolean {
+    let added = false
+    for (const literal of literals) {
+      if (this.unionLiterals.has(literal)) continue
+      this.unionLiterals.add(literal)
+      added = true
+    }
+    return added
+  }
+
   /**
    * Forget one source file's contribution. Idempotent — repeated calls
    * for a file that's already dropped are no-ops. Does NOT remove the
@@ -246,7 +279,7 @@ class UnionBuilder {
   public async writeSchemes(): Promise<{ changedSchemes: readonly string[] }> {
     await this.ensureProjectScanned()
     const sortedAtomNames = [...this.unionAtoms.keys()].toSorted((a, b) => a.localeCompare(b))
-    const result = buildSchemeSources(sortedAtomNames, this.unionAtoms, this.unionKeyframes, this.serializedCache, this.breakpoints)
+    const result = buildSchemeSources(sortedAtomNames, this.unionAtoms, this.unionKeyframes, this.serializedCache, this.breakpoints, this.unionGradients, this.unionHaptics, [...this.unionLiterals])
     this.serializedMissesCount += result.serializedMisses
     const { schemeSources, manifestSource } = result
 

package/src/metro/css-imports.ts

@@ -0,0 +1,75 @@
+import { createRequire } from 'node:module'
+import { existsSync, readFileSync } from 'node:fs'
+
+/**
+ * Inline `@import` resolution for the theme entry CSS.
+ *
+ * rnwind's scheme extractors (`extractThemeVars`, `extractSchemeAliases`,
+ * `extractCustomVariantSchemes`) are plain text passes over the entry
+ * CSS — they don't follow `@import`. Tailwind's own compiler DOES follow
+ * imports, so utilities still compile, but a user who keeps their theme
+ * in a separate file and points the entry at it:
+ *
+ * ```css
+ * @import "@acme/ui/theme.css";  // global.css — the cssEntryFile
+ * ```
+ *
+ * would hand the extractors a file with no `@theme` / `@variant` /
+ * `@custom-variant` in sight → every scheme collapses to base and theme
+ * switching dies. This module flattens those user imports first so the
+ * extractors (and the compiler) see the real declarations.
+ */
+
+/** Matches a bare `@import "spec";` / `@import 'spec';` (no media/layer suffix). */
+const CSS_IMPORT = /@import\s+(["'])([^"']+)\1\s*;/g
+
+/**
+ * Specs left untouched for the Tailwind compiler to resolve itself.
+ * `tailwindcss` resolves to JS (not inlinable) and `rnwind/css` is the
+ * framework preset — both are the compiler's job, not user theme files.
+ */
+const FRAMEWORK_SPECS = new Set(['tailwindcss', 'rnwind/css', 'rnwind'])
+
+/**
+ * Read `filePath` and replace each user `@import "<spec>";` whose spec
+ * resolves (Node resolution, honouring `exports` maps and workspace
+ * symlinks) to a readable `.css` file with that file's inlined +
+ * recursively-resolved contents. Unresolvable specs, non-CSS targets,
+ * and {@link FRAMEWORK_SPECS} are left as-is for the compiler.
+ * @param filePath Absolute path of the CSS file being inlined.
+ * @param seen Visited set guarding against import cycles.
+ * @returns CSS text with user imports flattened in place.
+ */
+function inlineImports(filePath: string, seen: Set<string>): string {
+  if (seen.has(filePath)) return ''
+  seen.add(filePath)
+  let css: string
+  try {
+    css = readFileSync(filePath, 'utf8')
+  } catch {
+    return ''
+  }
+  const request = createRequire(filePath)
+  return css.replaceAll(CSS_IMPORT, (full: string, _quote: string, spec: string): string => {
+    if (FRAMEWORK_SPECS.has(spec)) return full
+    let resolved: string
+    try {
+      resolved = request.resolve(spec)
+    } catch {
+      return full
+    }
+    if (!resolved.endsWith('.css') || !existsSync(resolved)) return full
+    return inlineImports(resolved, seen)
+  })
+}
+
+/**
+ * Flatten user `@import`s in a theme entry CSS file so rnwind's text-based
+ * scheme extractors see the real `@theme` / `@variant` / `@custom-variant`
+ * declarations even when the entry only re-exports them via `@import`.
+ * @param entryFilePath Absolute path to the theme entry CSS (the cssEntryFile).
+ * @returns Inlined CSS, or `''` when the entry can't be read.
+ */
+export function resolveThemeCss(entryFilePath: string): string {
+  return inlineImports(entryFilePath, new Set<string>())
+}

package/src/metro/dts.ts

@@ -56,21 +56,15 @@ const CONTENT_CONTAINER_INTERFACES: ReadonlySet<string> = new Set([
 
 /**
  * Build the body of one interface augmentation: `className?: string`
- * plus `<prefix>ClassName?: string` for every prefix that applies to
- * THIS interface. Emits a single-line body so the file stays easy to
- * scan and diff.
+ * plus `contentContainerClassName?: string` for the scroll interfaces
+ * that natively expose `contentContainerStyle`. Emits a single-line
+ * body so the file stays easy to scan and diff.
  * @param interfaceName Bare interface name (generic parameters stripped).
- * @param userPrefixes Extra prefixes from the Metro config — applied to
- *   every interface the same way `className` is.
  * @returns Space-separated property declarations.
  */
-function buildInterfaceBody(interfaceName: string, userPrefixes: readonly string[]): string {
+function buildInterfaceBody(interfaceName: string): string {
   const props = ['className?: string']
   if (CONTENT_CONTAINER_INTERFACES.has(interfaceName)) props.push(`${BUILTIN_PREFIX}ClassName?: string`)
-  for (const prefix of userPrefixes) {
-    if (prefix === BUILTIN_PREFIX) continue
-    props.push(`${prefix}ClassName?: string`)
-  }
   return props.join('; ')
 }
 
@@ -83,17 +77,11 @@ function buildInterfaceBody(interfaceName: string, userPrefixes: readonly string
  * `Scheme` union so `useScheme()` returns the actual names.
  *
  * Called once at Metro-config time — overwrite-on-rewrite so the file
- * stays in sync with the user's current theme CSS + prefix config.
+ * stays in sync with the user's current theme CSS.
  * @param targetPath Absolute path to write (typically `rnwind-types.d.ts` at project root).
  * @param schemes Scheme names from the user's `@variant` blocks (empty when none declared).
- * @param classNamePrefixes Extra prefixes from the Metro config — merged
- *   on top of the built-in `'contentContainer'`. Defaults to empty.
  */
-export function writeDtsFile(
-  targetPath: string,
-  schemes: readonly string[],
-  classNamePrefixes: readonly string[] = [],
-): void {
+export function writeDtsFile(targetPath: string, schemes: readonly string[]): void {
   const lines: string[] = [
     '// Auto-generated by rnwind — do not edit by hand.',
     '// Overwritten on Metro start / theme CSS change.',
@@ -102,7 +90,7 @@ export function writeDtsFile(
   ]
   for (const entry of INTERFACES) {
     const name = typeof entry === 'string' ? entry : entry.name
-    const body = buildInterfaceBody(name, classNamePrefixes)
+    const body = buildInterfaceBody(name)
     if (typeof entry === 'string') {
       lines.push(`  interface ${entry} { ${body} }`)
       continue

package/src/metro/state.ts

@@ -1,8 +1,10 @@
-import { existsSync, readFileSync, statSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { createHash } from 'node:crypto'
 import { UnionBuilder } from '../core/style-builder'
 import { TailwindParser, type SourceEntry } from '../core/parser'
+import { resolveThemeCss } from './css-imports'
+import { buildWrapModules } from './wrap-imports'
 
 /**
  * Default oxide Scanner globs — walk every JS/TS source under the
@@ -48,12 +50,8 @@ const CSS_ENTRY_ENV = 'RNWIND_CSS_ENTRY_FILE'
 const CACHE_DIR_ENV = 'RNWIND_CACHE_DIR'
 /** Env var carrying `watchFolders` from Metro config (NUL-separated). */
 const WATCH_FOLDERS_ENV = 'RNWIND_WATCH_FOLDERS'
-/** Env var carrying extra className prefixes the Metro config supplied. */
-const CLASSNAME_PREFIXES_ENV = 'RNWIND_CLASSNAME_PREFIXES'
-/** Env var carrying extra import sources whose JSX exports get className→style rewrites. Comma-separated. */
-const HOST_SOURCES_ENV = 'RNWIND_HOST_SOURCES'
-/** Env var carrying extra JSX tag names (verbatim, may contain `.`) treated as hosts. Comma-separated. */
-const HOST_COMPONENTS_ENV = 'RNWIND_HOST_COMPONENTS'
+/** Env var carrying extra modules whose component exports get `wrap()`-ed. Comma-separated. */
+const WRAP_MODULES_ENV = 'RNWIND_WRAP_MODULES'
 
 /** Memoised library fingerprint — read once per worker process. */
 let libraryFingerprint: string | undefined
@@ -62,19 +60,18 @@ let libraryFingerprint: string | undefined
 let cached: RnwindState | null = null
 
 /**
- * Cheap content-hash readout. SHA-256 prefix of the CSS bytes plus the
- * file's mtime nanoseconds (so identical content with different mtime
- * — atomic rewrites — still picks up the change). Returns `'missing'`
- * when the file can't be read so the cache key is still deterministic.
+ * Cheap content-hash readout. SHA-256 prefix of the FULLY-RESOLVED theme
+ * CSS — `@import`s flattened — so an edit to a theme file the entry only
+ * re-exports (`@import "@acme/ui/theme.css"`) still rotates the hash and
+ * invalidates Metro's cache. Returns `'missing'` when the entry can't be
+ * read so the cache key stays deterministic.
  * @param cssPath Absolute CSS path.
  * @returns 16-char hex content hash.
  */
 function readThemeHashFor(cssPath: string): string {
   if (!existsSync(cssPath)) return 'missing'
   try {
-    const bytes = readFileSync(cssPath)
-    const mtime = statSync(cssPath).mtimeMs.toString()
-    return createHash('sha256').update(bytes).update(mtime).digest('hex').slice(0, 16)
+    return createHash('sha256').update(resolveThemeCss(cssPath)).digest('hex').slice(0, 16)
   } catch {
     return 'missing'
   }
@@ -86,10 +83,10 @@ function readThemeHashFor(cssPath: string): string {
  * dev OR npm install of a new version) the file bytes change, the
  * fingerprint rotates, and Metro's transform cache invalidates.
  *
- * Includes the JSX rewriter (`transform-ast`) alongside the parser /
- * style-builder so a change to the transformer — e.g. renaming the
- * injected context hook — invalidates every stale per-file cache entry
- * on the next dev run. Without this, a user upgrading rnwind in-place
+ * Includes the import-rewriter (`wrap-imports`) and runtime resolver
+ * alongside the parser / style-builder so a change to the transformer —
+ * e.g. renaming the injected wrap helper — invalidates every stale
+ * per-file cache entry on the next dev run. Without this, a user upgrading rnwind in-place
  * would keep loading the old transformed bytes; React-refresh would
  * then preserve fiber state across the version bump and the rendered
  * hook list could shift, surfacing as "change in the order of Hooks"
@@ -105,14 +102,14 @@ function getLibraryFingerprint(): string {
     path.resolve(here, '..', 'core', 'style-builder', 'build-style.cjs'),
     path.resolve(here, '..', 'core', 'parser', 'tw-parser.mjs'),
     path.resolve(here, '..', 'core', 'parser', 'tw-parser.cjs'),
-    path.resolve(here, 'transform-ast.mjs'),
-    path.resolve(here, 'transform-ast.cjs'),
+    path.resolve(here, 'wrap-imports.mjs'),
+    path.resolve(here, 'wrap-imports.cjs'),
     path.resolve(here, 'transformer.mjs'),
     path.resolve(here, 'transformer.cjs'),
     // Source-tree fallback for tests + workspace dev (no built lib yet).
     path.resolve(here, '..', '..', 'src', 'core', 'style-builder', 'build-style.ts'),
     path.resolve(here, '..', '..', 'src', 'core', 'parser', 'tw-parser.ts'),
-    path.resolve(here, '..', '..', 'src', 'metro', 'transform-ast.ts'),
+    path.resolve(here, '..', '..', 'src', 'metro', 'wrap-imports.ts'),
     path.resolve(here, '..', '..', 'src', 'metro', 'transformer.ts'),
   ]
   const hash = createHash('sha256')
@@ -148,18 +145,14 @@ export interface RnwindState {
  * can rebuild the same state without re-reading the Metro config.
  * @param cssEntryFile Absolute path to the user's theme CSS.
  * @param cacheDir Absolute path to the cache dir (`.rnwind`).
- * @param watchFolders
- * @param classNamePrefixes Extra JSX prop-name prefixes to rewrite.
- * @param hostSources
- * @param hostComponents
+ * @param watchFolders Monorepo watch folders to scan for atoms.
+ * @param wrapModules Extra modules whose component exports get `wrap()`-ed.
  */
 export function configureRnwindState(
   cssEntryFile: string,
   cacheDir: string,
   watchFolders: readonly string[] = [],
-  classNamePrefixes?: readonly string[],
-  hostSources?: readonly string[],
-  hostComponents?: readonly string[],
+  wrapModules?: readonly string[],
 ): void {
   process.env[CSS_ENTRY_ENV] = cssEntryFile
   process.env[CACHE_DIR_ENV] = cacheDir
@@ -168,59 +161,23 @@ export function configureRnwindState(
   } else {
     process.env[WATCH_FOLDERS_ENV] = watchFolders.join('\0')
   }
-  if (!classNamePrefixes || classNamePrefixes.length === 0) {
-    delete process.env[CLASSNAME_PREFIXES_ENV]
+  if (!wrapModules || wrapModules.length === 0) {
+    delete process.env[WRAP_MODULES_ENV]
   } else {
-    process.env[CLASSNAME_PREFIXES_ENV] = classNamePrefixes.join(',')
-  }
-  if (!hostSources || hostSources.length === 0) {
-    delete process.env[HOST_SOURCES_ENV]
-  } else {
-    process.env[HOST_SOURCES_ENV] = hostSources.join(',')
-  }
-  if (!hostComponents || hostComponents.length === 0) {
-    delete process.env[HOST_COMPONENTS_ENV]
-  } else {
-    process.env[HOST_COMPONENTS_ENV] = hostComponents.join(',')
+    process.env[WRAP_MODULES_ENV] = wrapModules.join(',')
   }
   cached = null
 }
 
 /**
- * Read the caller-configured extra className prefixes out of the
- * worker environment. Returns an empty array when unset — the
- * transformer applies the built-in `contentContainer` default on top
- * either way.
- * @returns User-supplied extra prefixes.
+ * Effective module → wrap-policy map: the built-in defaults merged with
+ * any extra modules the Metro config supplied.
+ * @returns Module → policy map the import-rewrite consults.
  */
-export function getClassNamePrefixes(): readonly string[] {
-  const raw = process.env[CLASSNAME_PREFIXES_ENV]
-  if (!raw || raw.length === 0) return []
-  return raw.split(',').filter((entry) => entry.length > 0)
-}
-
-/**
- * Read the caller-configured extra host module sources out of the
- * worker environment. Empty array when unset — the transformer applies
- * its built-in default list on top either way.
- * @returns User-supplied extra host sources.
- */
-export function getHostSources(): readonly string[] {
-  const raw = process.env[HOST_SOURCES_ENV]
-  if (!raw || raw.length === 0) return []
-  return raw.split(',').filter((entry) => entry.length > 0)
-}
-
-/**
- * Read the caller-configured extra host JSX tag names out of the worker
- * environment. Verbatim names — may include `.` for member expressions
- * like `'Animated.View'`.
- * @returns User-supplied extra host component names.
- */
-export function getHostComponents(): readonly string[] {
-  const raw = process.env[HOST_COMPONENTS_ENV]
-  if (!raw || raw.length === 0) return []
-  return raw.split(',').filter((entry) => entry.length > 0)
+export function getWrapModules(): ReturnType<typeof buildWrapModules> {
+  const raw = process.env[WRAP_MODULES_ENV]
+  const extra = raw && raw.length > 0 ? raw.split(',').filter((entry) => entry.length > 0) : undefined
+  return buildWrapModules(extra)
 }
 
 /**
@@ -240,7 +197,7 @@ export function getRnwindState(projectRoot: string): RnwindState {
   if (!cacheDir) throw new Error('rnwind: RNWIND_CACHE_DIR is not set — did `withRnwindConfig` run?')
   const currentHash = readThemeHashFor(cssEntry)
   if (cached?.themeHash === currentHash && cached.projectRoot === projectRoot) return cached
-  const themeCss = readFileSync(cssEntry, 'utf8')
+  const themeCss = resolveThemeCss(cssEntry)
   const parser = new TailwindParser({
     themeCss,
     sources: defaultSources(projectRoot, cacheDir, readWatchFolders()),
@@ -261,14 +218,12 @@ export function getRnwindState(projectRoot: string): RnwindState {
  */
 export function getRnwindCacheKey(): string {
   const cssEntry = process.env[CSS_ENTRY_ENV] ?? ''
-  const prefixes = process.env[CLASSNAME_PREFIXES_ENV] ?? ''
-  // Host source / component config changes which JSX tags get rewritten,
-  // so it MUST flip the cache key — otherwise Metro replays stale
-  // transforms (a newly-opted-in host keeps its raw className, a removed
-  // one keeps the rewrite).
-  const hostSources = process.env[HOST_SOURCES_ENV] ?? ''
-  const hostComponents = process.env[HOST_COMPONENTS_ENV] ?? ''
-  return `rnwind:${cssEntry}:${readThemeHashFor(cssEntry)}|lib:${getLibraryFingerprint()}|pfx:${prefixes}|hs:${hostSources}|hc:${hostComponents}`
+  // Wrap-module config changes which import sites get `wrap()`-ed, so it
+  // MUST flip the cache key — otherwise Metro replays stale transforms
+  // (a newly-opted-in module keeps its raw import, a removed one keeps
+  // the wrap).
+  const wrapModules = process.env[WRAP_MODULES_ENV] ?? ''
+  return `rnwind:${cssEntry}:${readThemeHashFor(cssEntry)}|lib:${getLibraryFingerprint()}|wm:${wrapModules}`
 }
 
 /** Drop the cached state — call after editing the theme CSS. */