rnwind 0.0.1 → 0.0.3

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

@@ -0,0 +1,328 @@
+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 { buildSchemeSources, type AtomSerializedCache } from './build-style'
+
+/** Manifest module basename — the file SchemeProvider imports via the resolver. */
+const MANIFEST_BASENAME = 'schemes.js'
+
+/**
+ * Atomic file write — stage to a `.tmp.<pid>.<nonce>` sibling, then
+ * `rename()` into place. Skips the write entirely when the existing
+ * content matches.
+ * @param target Final destination path.
+ * @param content Bytes to write.
+ * @returns Whether the file was actually rewritten.
+ */
+function writeIfChanged(target: string, content: string): boolean {
+  if (existsSync(target)) {
+    try {
+      if (readFileSync(target, 'utf8') === content) return false
+    } catch {
+      // Unreadable — fall through to rewrite.
+    }
+  }
+  mkdirSync(path.dirname(target), { recursive: true })
+  const temporary = `${target}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`
+  try {
+    writeFileSync(temporary, content, 'utf8')
+    renameSync(temporary, target)
+    return true
+  } catch (error) {
+    rmSync(temporary, { force: true })
+    throw error
+  }
+}
+
+/**
+ * SHA-256 prefix of a string — cheap signature used to detect whether a
+ * per-scheme file's source has changed since the last write.
+ * @param text Input text.
+ * @returns 16-char hex digest.
+ */
+function signatureOf(text: string): string {
+  return createHash('sha256').update(text).digest('hex').slice(0, 16)
+}
+
+/**
+ * Compare two `Set<string>`s for equality — same size + every element
+ * of `a` present in `b`.
+ * @param a First set.
+ * @param b Second set.
+ * @returns Whether the two sets contain identical values.
+ */
+function setsEqual(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
+  if (a.size !== b.size) return false
+  for (const v of a) if (!b.has(v)) return false
+  return true
+}
+
+/**
+ * Compute the absolute path of a per-scheme style file under the cache dir.
+ * @param cacheDir Absolute cache directory.
+ * @param scheme Registry key (`'common'` or a variant name).
+ * @returns Absolute path, e.g. `<cacheDir>/dark.style.js`.
+ */
+function schemeFilePath(cacheDir: string, scheme: string): string {
+  return path.join(cacheDir, `${scheme}.style.js`)
+}
+
+/**
+ * In-memory atom union + per-scheme style-file emitter.
+ *
+ * Correctness under multi-worker Metro relies on `ensureProjectScanned`:
+ * the FIRST `recordFile` / `writeSchemes` call in every worker drives
+ * the oxide Scanner across ALL project sources and hydrates the union
+ * with the complete set of candidates. Subsequent per-file
+ * `recordFile` calls only layer in atoms the scan already knew about,
+ * so writes are idempotent — different workers can't clobber each
+ * other's scheme files with partial views.
+ *
+ * Per-file deltas (atom set unchanged → early return) skip
+ * serialization entirely. On a theme-CSS change, `getRnwindState`
+ * builds a fresh parser + builder; the next call re-runs
+ * `ensureProjectScanned` against the new parser, producing scheme
+ * files with the new theme values.
+ */
+class UnionBuilder {
+  private readonly cacheDir: string
+  private readonly parser: TailwindParser
+  private readonly unionAtoms = new Map<string, SchemedStyle>()
+  private readonly unionKeyframes = new Map<string, KeyframeBlock>()
+  /**
+   * Responsive breakpoints captured from the parser. Refreshed on every
+   * `recordFile` / `ensureProjectScanned` so user-defined
+   * `--breakpoint-*` overrides land in the manifest the next time it's
+   * written. Identical for every parser call within one parser instance
+   * (theme is fixed for the parser's lifetime), so storing the latest
+   * snapshot is sufficient.
+   */
+  private breakpoints: ReadonlyMap<string, number> = new Map()
+  /** file → set of atom names this file currently contributes. */
+  private readonly fileAtomSets = new Map<string, Set<string>>()
+  /** atom name → how many files currently contribute it (refcount). */
+  private readonly atomRefCount = new Map<string, number>()
+  /** scheme → last-written source SHA. Skips re-writing unchanged schemes. */
+  private readonly schemeSignatures = new Map<string, string>()
+  /**
+   * Per-atom serialized-value cache — identity-keyed on each atom's
+   * SchemedStyle reference. Carried across `writeSchemes` calls so the
+   * typical "user added one className" FR case re-stringifies ONE atom
+   * instead of all 175+. Cleared on `ensureProjectScanned` (full
+   * rescan replaces every reference) and individually invalidated for
+   * any atom `applyDiff` mutates.
+   */
+  private readonly serializedCache: AtomSerializedCache = new Map()
+  /** Running count of stringify passes (cache misses). Test telemetry. */
+  private serializedMissesCount = 0
+  /** Set after `ensureProjectScanned` completes. */
+  private projectScanned = false
+  /** Promise guard so concurrent first-calls await ONE scan. */
+  private pendingScan: Promise<void> | null = null
+
+  constructor(cacheDir: string, parser: TailwindParser) {
+    this.cacheDir = cacheDir
+    this.parser = parser
+    mkdirSync(this.cacheDir, { recursive: true })
+  }
+
+  /** Absolute path of the manifest module (`rnwind/__generated/schemes`). */
+  public get manifestPath(): string {
+    return path.join(this.cacheDir, MANIFEST_BASENAME)
+  }
+
+  /**
+   * Snapshot of every source file the builder has recorded atoms for
+   * this worker session. Used by `withRnwindConfig`'s CSS watcher to
+   * touch `mtime` on each and nudge Metro into re-transforming them
+   * with the new theme values.
+   * @returns Absolute source paths.
+   */
+  public recordedFiles(): readonly string[] {
+    return [...this.fileAtomSets.keys()]
+  }
+
+  /** Cumulative cache-miss count — exposed for tests to assert cache behaviour. */
+  public get serializedMisses(): number {
+    return this.serializedMissesCount
+  }
+
+  /**
+   * Absolute path of one scheme's style file.
+   * @param scheme Registry key.
+   * @returns Absolute path.
+   */
+  public schemePath(scheme: string): string {
+    return schemeFilePath(this.cacheDir, scheme)
+  }
+
+  /**
+   * One-shot oxide scan + compile across every source the parser was
+   * configured with. Idempotent — safe to call from any entry point.
+   * Concurrent callers share the same in-flight promise.
+   */
+  public async ensureProjectScanned(): Promise<void> {
+    if (this.projectScanned) return
+    if (this.pendingScan) return this.pendingScan
+    this.pendingScan = (async () => {
+      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)
+      this.breakpoints = parsed.breakpoints
+      this.projectScanned = true
+    })()
+    try {
+      await this.pendingScan
+    } finally {
+      this.pendingScan = null
+    }
+  }
+
+  /**
+   * Record one source file's resolved atoms + keyframes. Short-circuits
+   * when the file's atom name set hasn't changed — the common case on
+   * every Fast Refresh save of a file whose className literals are
+   * unchanged.
+   * @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.
+   * @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.
+   */
+  public async recordFile(
+    file: string,
+    atoms: ReadonlyMap<string, SchemedStyle>,
+    keyframes: ReadonlyMap<string, KeyframeBlock>,
+  ): Promise<{ changed: boolean }> {
+    await this.ensureProjectScanned()
+    const newAtomNames = new Set(atoms.keys())
+    const previous = this.fileAtomSets.get(file)
+    if (previous && setsEqual(previous, newAtomNames)) {
+      // Atom set unchanged — skip the unionAtoms update entirely. The
+      // project scan already populated them, and re-setting a fresh
+      // object ref here would invalidate the per-atom serialization
+      // cache on every FR save for no gain (values are identical).
+      // Theme edits go through `getRnwindState` → new builder → fresh
+      // scan, so stale cache is impossible.
+      let keyframeAdded = false
+      for (const [name, kf] of keyframes) {
+        if (!this.unionKeyframes.has(name)) keyframeAdded = true
+        this.unionKeyframes.set(name, kf)
+      }
+      return { changed: keyframeAdded }
+    }
+    this.applyDiff(file, newAtomNames, atoms, keyframes)
+    return { changed: true }
+  }
+
+  /**
+   * Forget one source file's contribution. Idempotent — repeated calls
+   * for a file that's already dropped are no-ops. Does NOT remove the
+   * atom from the union when another file (or the project scan) still
+   * references it.
+   * @param file Absolute source file path.
+   */
+  public dropFile(file: string): void {
+    const previous = this.fileAtomSets.get(file)
+    if (!previous) return
+    for (const name of previous) {
+      const count = (this.atomRefCount.get(name) ?? 0) - 1
+      if (count <= 0) this.atomRefCount.delete(name)
+      else this.atomRefCount.set(name, count)
+    }
+    this.fileAtomSets.delete(file)
+  }
+
+  /**
+   * Serialize the union into per-scheme files + manifest, writing only
+   * files whose source bytes changed. Called after every `recordFile`
+   * from the transformer — and once at Metro startup via
+   * `ensureFilesExist` to seed disk from the project scan alone.
+   * @returns List of scheme keys whose files were rewritten (empty
+   *   when the union is byte-identical to the last flush).
+   */
+  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)
+    this.serializedMissesCount += result.serializedMisses
+    const { schemeSources, manifestSource } = result
+
+    const changed: string[] = []
+    for (const [scheme, source] of Object.entries(schemeSources)) {
+      const signature = signatureOf(source)
+      const target = schemeFilePath(this.cacheDir, scheme)
+      if (this.schemeSignatures.get(scheme) === signature && existsSync(target)) continue
+      if (writeIfChanged(target, source)) changed.push(scheme)
+      this.schemeSignatures.set(scheme, signature)
+    }
+
+    const manifestSignature = signatureOf(manifestSource)
+    const manifestTarget = path.join(this.cacheDir, MANIFEST_BASENAME)
+    if (this.schemeSignatures.get('__manifest') !== manifestSignature || !existsSync(manifestTarget)) {
+      if (writeIfChanged(manifestTarget, manifestSource)) changed.push('__manifest')
+      this.schemeSignatures.set('__manifest', manifestSignature)
+    }
+
+    return { changedSchemes: changed }
+  }
+
+  /**
+   * Ensure the manifest + common scheme files exist on disk so Metro's
+   * resolver can SHA1 them at boot before the first transform runs.
+   */
+  public async ensureFilesExist(): Promise<void> {
+    if (existsSync(this.manifestPath) && existsSync(schemeFilePath(this.cacheDir, 'common'))) {
+      // Still trigger the scan so the in-memory union is complete; file
+      // bytes may already be authoritative from a prior Metro run.
+      await this.ensureProjectScanned()
+      return
+    }
+    await this.writeSchemes()
+  }
+
+  /**
+   * Apply one file's atom-name diff to the in-memory refcount + union.
+   * @param file Source file path.
+   * @param newAtoms New atom-name set for the file.
+   * @param resolvedAtoms Fresh parser output — carries the resolved
+   *   styles for every entry in `newAtoms`.
+   * @param newKeyframes Keyframes this file's atoms reference.
+   */
+  private applyDiff(
+    file: string,
+    newAtoms: ReadonlySet<string>,
+    resolvedAtoms: ReadonlyMap<string, SchemedStyle>,
+    newKeyframes: ReadonlyMap<string, KeyframeBlock>,
+  ): void {
+    const previous = this.fileAtomSets.get(file) ?? new Set<string>()
+    for (const name of previous) {
+      if (newAtoms.has(name)) continue
+      const count = (this.atomRefCount.get(name) ?? 0) - 1
+      if (count <= 0) this.atomRefCount.delete(name)
+      else this.atomRefCount.set(name, count)
+      // Do NOT remove `name` from `unionAtoms` — the project scan still
+      // references it (orphaned atoms get reaped on the next Metro
+      // cold start when the scanner re-walks disk).
+    }
+    for (const name of newAtoms) {
+      if (!previous.has(name)) this.atomRefCount.set(name, (this.atomRefCount.get(name) ?? 0) + 1)
+      // Only install the resolved style when the atom is new to the
+      // union. Replacing an existing entry with a fresh parser-
+      // produced object would swap the identity guard the per-atom
+      // serialization cache uses and force a re-stringify for every
+      // atom on every FR save. CSS edits rebuild the whole builder
+      // (via `getRnwindState`) so stale values aren't possible.
+      if (!this.unionAtoms.has(name)) {
+        const style = resolvedAtoms.get(name)
+        if (style) this.unionAtoms.set(name, style)
+      }
+    }
+    this.fileAtomSets.set(file, new Set(newAtoms))
+    for (const [name, kf] of newKeyframes) this.unionKeyframes.set(name, kf)
+  }
+}
+
+export { UnionBuilder }

package/src/core/types.ts

@@ -0,0 +1,15 @@
+/**
+ * Resolved values for every CSS custom property in one theme scheme.
+ * Keys are the raw custom-property names (e.g. `--color-primary`) as they
+ * appear in the theme CSS. Values are the string / number primitives the
+ * parser emits after Tailwind compile + lightningcss walk.
+ */
+export type ThemeTable = Record<string, string | number>
+
+/**
+ * Map from scheme name to its resolved {@link ThemeTable}. The scheme name
+ * matches the identifier the user declared in `@variant <name> { ... }` —
+ * `'light'`, `'dark'`, `'brand'`, etc. A synthetic `'base'` key carries
+ * tokens declared outside any variant block.
+ */
+export type ThemeTables = Record<string, ThemeTable>

package/src/metro/dts.ts

@@ -0,0 +1,128 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+/**
+ * React Native component-props interfaces rnwind augments. Adding an
+ * optional `className?: string` to each lets TypeScript accept
+ * `<View className="…" />` without the user touching types by hand.
+ * The generic ones are written with a placeholder so the output type
+ * stays parameterised.
+ */
+const INTERFACES: ReadonlyArray<string | { name: string; generic: string }> = [
+  'ViewProps',
+  'TextProps',
+  'ImageProps',
+  'ImageBackgroundProps',
+  'ScrollViewProps',
+  'PressableProps',
+  'ModalProps',
+  'TextInputProps',
+  'TouchableOpacityProps',
+  'TouchableHighlightProps',
+  'TouchableNativeFeedbackProps',
+  'TouchableWithoutFeedbackProps',
+  'SafeAreaViewProps',
+  'KeyboardAvoidingViewProps',
+  'RefreshControlProps',
+  'StatusBarProps',
+  'SwitchProps',
+  'ActivityIndicatorProps',
+  'SectionListProps',
+  { name: 'FlatListProps', generic: 'ItemT' },
+  { name: 'VirtualizedListProps', generic: 'ItemT' },
+]
+
+/**
+ * Built-in prefix wired into every install. Restricted to the interfaces
+ * that natively expose `contentContainerStyle` so TypeScript doesn't
+ * start accepting `<View contentContainerClassName="…" />` — RN would
+ * silently ignore it at runtime and a typed lint is more useful than a
+ * permissive one. User prefixes don't come with this restriction; rnwind
+ * can't know which component props they target.
+ */
+const BUILTIN_PREFIX = 'contentContainer'
+
+/**
+ * Interfaces that expose `contentContainerStyle` in React Native's own
+ * types — the set the built-in prefix's `.d.ts` augmentation targets.
+ * Everything else stays `className`-only by default.
+ */
+const CONTENT_CONTAINER_INTERFACES: ReadonlySet<string> = new Set([
+  'ScrollViewProps',
+  'FlatListProps',
+  'SectionListProps',
+  'VirtualizedListProps',
+])
+
+/**
+ * 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.
+ * @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 {
+  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('; ')
+}
+
+/**
+ * Write the rnwind TypeScript declaration file. The generated `.d.ts`
+ * declares a `rnwind` module augmentation for `react-native`'s
+ * component props — every interface gets an optional `className?:
+ * string` plus `<prefix>ClassName?: string` for each active prefix.
+ * Runtime-rendered schemes (`@variant` blocks) are reflected in the
+ * `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.
+ * @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 {
+  const lines: string[] = [
+    '// Auto-generated by rnwind — do not edit by hand.',
+    '// Overwritten on Metro start / theme CSS change.',
+    '',
+    `declare module 'react-native' {`,
+  ]
+  for (const entry of INTERFACES) {
+    const name = typeof entry === 'string' ? entry : entry.name
+    const body = buildInterfaceBody(name, classNamePrefixes)
+    if (typeof entry === 'string') {
+      lines.push(`  interface ${entry} { ${body} }`)
+      continue
+    }
+    lines.push(`  interface ${entry.name}<${entry.generic}> { ${body} }`)
+  }
+  lines.push('}', '')
+  if (schemes.length > 0) {
+    lines.push(`declare module 'rnwind' {`, `  export interface RnwindConfig {`)
+    const schemeLiterals = schemes.map((s) => `'${s}'`).join(', ')
+    lines.push(`    themes: readonly [${schemeLiterals}]`, `  }`, '}', '')
+  }
+  // The `export {}` is mandatory — without at least one top-level
+  // import/export, TypeScript treats this file as a SCRIPT and the
+  // `declare module 'react-native'` block above becomes a complete
+  // *replacement* declaration (hiding the real RN exports like
+  // `Pressable`, `useColorScheme`, etc.). With `export {}` the file
+  // becomes a module and the `declare module` blocks are interpreted as
+  // *augmentations* — which is what we want.
+  lines.push('export {}', '')
+  mkdirSync(path.dirname(targetPath), { recursive: true })
+  writeFileSync(targetPath, lines.join('\n'), 'utf8')
+}

package/src/metro/index.ts

@@ -0,0 +1,9 @@
+export { withRnwindConfig } from './with-config'
+export type { RnwindMetroOptions, MetroConfigLike } from './with-config'
+export { createRnwindResolver } from './resolver'
+export type { ResolveRequestFn } from './resolver'
+export { writeDtsFile } from './dts'
+export { transform } from './transformer'
+export type { BabelTransformerArgs, BabelTransformerResult } from './transformer'
+export { getRnwindState, configureRnwindState, resetRnwindState, manifestPathFor } from './state'
+export type { RnwindState } from './state'

package/src/metro/resolver.ts

@@ -0,0 +1,42 @@
+import { manifestPathFor } from './state'
+
+/** Specifier the transformer prepends — resolves to the scheme manifest. */
+const SCHEMES_MODULE = 'rnwind/__generated/schemes'
+
+/** Metro `resolveRequest` callable shape. Loose so we don't bind to Metro's internal types. */
+export type ResolveRequestFn = (context: unknown, moduleName: string, platform: string | null) => unknown
+
+/**
+ * Sentinel module specifier the transformer prepends to every rewritten
+ * file. The resolver maps it to the user's theme CSS so Metro watches
+ * that file as a real node in the dependency graph — when the user
+ * edits `global.css`, the CSS file's SHA1 changes, and Metro
+ * invalidates every JS file that imports the sentinel. The transformer
+ * recognises `.css` filenames and returns an empty `export {}` AST so
+ * Metro can still bundle it.
+ */
+export const THEME_SIGNATURE_MODULE = 'rnwind/__generated/theme-signature'
+
+/**
+ * Build a Metro `resolveRequest` hook that maps the scheme manifest
+ * specifier (and the theme-signature sentinel) to its on-disk path.
+ * Delegates every other request to the upstream resolver.
+ * @param upstream Previously-registered `resolveRequest` (kept in the chain).
+ * @returns Metro-compatible resolver.
+ */
+export function createRnwindResolver(upstream: ResolveRequestFn | null | undefined): ResolveRequestFn {
+  return (context, moduleName, platform) => {
+    if (moduleName === SCHEMES_MODULE) return { type: 'sourceFile', filePath: manifestPathFor() }
+    if (moduleName === THEME_SIGNATURE_MODULE) {
+      const cssPath = process.env.RNWIND_CSS_ENTRY_FILE
+      if (cssPath) return { type: 'sourceFile', filePath: cssPath }
+    }
+    if (upstream) return upstream(context, moduleName, platform)
+    const { resolveRequest } = context as { resolveRequest?: ResolveRequestFn }
+    if (resolveRequest) return resolveRequest(context, moduleName, platform)
+    return null as unknown
+  }
+}
+
+/** Side-effect import specifier(s) the transformer injects on every rewritten file. */
+export const STYLE_SPECIFIERS = [SCHEMES_MODULE] as const