rnwind 0.0.10 → 0.0.12

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

@@ -1,5 +1,5 @@
 import { createHash, randomBytes } from 'node:crypto'
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import type { GradientAtomInfo, HapticRequest, KeyframeBlock, SchemedStyle, TailwindParser } from '../parser'
 import type { ThemeTables } from '../types'
@@ -8,6 +8,12 @@ import { buildSchemeSources, type AtomSerializedCache } from './build-style'
 /** Manifest module basename — the file SchemeProvider imports via the resolver. */
 const MANIFEST_BASENAME = 'schemes.js'
 
+/** Suffix every per-scheme style file carries on disk. */
+const SCHEME_FILE_SUFFIX = '.style.js'
+
+/** Registry key for the always-loaded fallback scheme — never reaped. */
+const COMMON_SCHEME = 'common'
+
 /**
  * Atomic file write — stage to a `.tmp.<pid>.<nonce>` sibling, then
  * `rename()` into place. Skips the write entirely when the existing
@@ -66,7 +72,34 @@ function setsEqual(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
  * @returns Absolute path, e.g. `<cacheDir>/dark.style.js`.
  */
 function schemeFilePath(cacheDir: string, scheme: string): string {
-  return path.join(cacheDir, `${scheme}.style.js`)
+  return path.join(cacheDir, `${scheme}${SCHEME_FILE_SUFFIX}`)
+}
+
+/**
+ * List scheme names whose `<scheme>.style.js` exists on disk but is NOT in
+ * the set the current build emits — orphans left by a removed variant
+ * (e.g. user drops `@variant dark`, or a theme swap via git pull). The
+ * always-loaded `common` scheme is never an orphan. The manifest
+ * (`schemes.js`) doesn't carry the `.style.js` suffix, so it's skipped.
+ * @param cacheDir Absolute cache directory.
+ * @param liveSchemes Scheme names the current build writes.
+ * @returns Orphaned scheme names safe to delete.
+ */
+function findOrphanedSchemes(cacheDir: string, liveSchemes: ReadonlySet<string>): readonly string[] {
+  let names: readonly string[]
+  try {
+    names = readdirSync(cacheDir)
+  } catch {
+    return []
+  }
+  const orphans: string[] = []
+  for (const name of names) {
+    if (!name.endsWith(SCHEME_FILE_SUFFIX)) continue
+    const scheme = name.slice(0, -SCHEME_FILE_SUFFIX.length)
+    if (scheme === COMMON_SCHEME || liveSchemes.has(scheme)) continue
+    orphans.push(scheme)
+  }
+  return orphans
 }
 
 /**
@@ -156,6 +189,15 @@ class UnionBuilder {
     return this.serializedMissesCount
   }
 
+  /**
+   * Snapshot of the scheme keys currently tracked in `schemeSignatures` —
+   * exposed for tests to assert orphan-signature cleanup.
+   * @returns Scheme signature keys (includes the `__manifest` sentinel).
+   */
+  public schemeSignatureKeys(): readonly string[] {
+    return [...this.schemeSignatures.keys()]
+  }
+
   /**
    * Absolute path of one scheme's style file.
    * @param scheme Registry key.
@@ -285,7 +327,7 @@ class UnionBuilder {
     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 (this.canSkipWrite(scheme, signature, target, source)) continue
       if (writeIfChanged(target, source)) changed.push(scheme)
       this.schemeSignatures.set(scheme, signature)
     }
@@ -297,9 +339,47 @@ class UnionBuilder {
       this.schemeSignatures.set('__manifest', manifestSignature)
     }
 
+    this.reapOrphanedSchemes(new Set(Object.keys(schemeSources)))
     return { changedSchemes: changed }
   }
 
+  /**
+   * Whether the current write for one scheme can be skipped. A skip is
+   * safe only when the cached signature matches AND the bytes on disk
+   * still equal the expected source — an `existsSync` pass alone would
+   * keep a truncated or externally-modified file (corrupt content with a
+   * stale-but-matching signature). The byte read happens only on a
+   * signature match, so the common no-change path stays cheap.
+   * @param scheme Scheme registry key.
+   * @param signature Signature of the source about to be written.
+   * @param target Absolute path of the scheme file.
+   * @param source Expected file content.
+   * @returns Whether writing this scheme can be skipped.
+   */
+  private canSkipWrite(scheme: string, signature: string, target: string, source: string): boolean {
+    if (this.schemeSignatures.get(scheme) !== signature) return false
+    try {
+      return readFileSync(target, 'utf8') === source
+    } catch {
+      // Missing or unreadable on disk — must rewrite.
+      return false
+    }
+  }
+
+  /**
+   * Delete `<scheme>.style.js` files left behind by a scheme that's no
+   * longer part of the build (removed `@variant`, theme swap), and drop
+   * their cached signatures so a later re-introduction rewrites cleanly.
+   * The `common` file and the manifest are never touched.
+   * @param liveSchemes Scheme names the current build wrote.
+   */
+  private reapOrphanedSchemes(liveSchemes: ReadonlySet<string>): void {
+    for (const scheme of findOrphanedSchemes(this.cacheDir, liveSchemes)) {
+      rmSync(schemeFilePath(this.cacheDir, scheme), { force: true })
+      this.schemeSignatures.delete(scheme)
+    }
+  }
+
   /**
    * Ensure the manifest + common scheme files exist on disk so Metro's
    * resolver can SHA1 them at boot before the first transform runs.

package/src/metro/state.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync, statSync } from 'node:fs'
 import path from 'node:path'
 import { createHash } from 'node:crypto'
 import { UnionBuilder } from '../core/style-builder'
@@ -59,22 +59,91 @@ let libraryFingerprint: string | undefined
 /** Live state shared across one Metro transform worker. */
 let cached: RnwindState | null = null
 
+/**
+ * Cached wrap-module map. The env var feeding it only changes on a Metro
+ * (re)configure, so rebuilding the 11-entry Map per file transform is pure
+ * waste — `configureRnwindState` / `resetRnwindState` clear this so the next
+ * call rebuilds from the current env.
+ */
+let cachedWrapModules: ReturnType<typeof buildWrapModules> | null = null
+
+/** A memoised theme read: the resolved CSS, its content hash, and its mtime. */
+interface ThemeMemoEntry {
+  mtimeMs: number
+  hash: string
+  css: string
+}
+
+/**
+ * Process-scoped memo of resolved theme CSS keyed by entry path. Every file
+ * transform reads the theme hash (via `getRnwindState` + `getRnwindCacheKey`)
+ * and the rebuild path reads the full CSS again — without this memo each is a
+ * full disk read + `@import` inline + SHA-256. Keyed on `statSync` mtime so a
+ * real edit busts it while unchanged files reuse the cached result. This is
+ * NOT a competing persistent cache: it's in-memory, process-scoped, and only
+ * defers the redundant re-reads Metro's own caching can't see.
+ */
+const themeMemo = new Map<string, ThemeMemoEntry>()
+
+/** Test-only counter — increments on each actual disk read (memo miss). */
+let themeReadCount = 0
+
+/**
+ * Load (or reuse) the resolved theme CSS + hash for `cssPath`. Re-reads from
+ * disk only when the file's mtime changed since the last read; otherwise the
+ * cached entry is returned untouched.
+ * @param cssPath Absolute CSS entry path.
+ * @returns The memo entry, or `null` when the entry can't be read.
+ */
+function loadThemeMemo(cssPath: string): ThemeMemoEntry | null {
+  let stat: ReturnType<typeof statSync>
+  try {
+    stat = statSync(cssPath)
+  } catch {
+    themeMemo.delete(cssPath)
+    return null
+  }
+  const { mtimeMs } = stat
+  const cachedEntry = themeMemo.get(cssPath)
+  if (cachedEntry?.mtimeMs === mtimeMs) return cachedEntry
+  const css = resolveThemeCss(cssPath)
+  themeReadCount += 1
+  const entry: ThemeMemoEntry = { mtimeMs, hash: createHash('sha256').update(css).digest('hex').slice(0, 16), css }
+  themeMemo.set(cssPath, entry)
+  return entry
+}
+
 /**
  * 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.
+ * read so the cache key stays deterministic. Memoised by mtime.
  * @param cssPath Absolute CSS path.
  * @returns 16-char hex content hash.
  */
 function readThemeHashFor(cssPath: string): string {
-  if (!existsSync(cssPath)) return 'missing'
-  try {
-    return createHash('sha256').update(resolveThemeCss(cssPath)).digest('hex').slice(0, 16)
-  } catch {
-    return 'missing'
-  }
+  return loadThemeMemo(cssPath)?.hash ?? 'missing'
+}
+
+/**
+ * Resolved theme CSS for the entry, served from the same mtime memo so the
+ * rebuild path doesn't re-read the file the hash readout already loaded.
+ * @param cssPath Absolute CSS path.
+ * @returns Fully-inlined theme CSS, or `''` when unreadable.
+ */
+function readThemeCssFor(cssPath: string): string {
+  return loadThemeMemo(cssPath)?.css ?? ''
+}
+
+/** Test-only — count of actual disk reads of the theme CSS (memo misses). */
+export function __getThemeReadCount(): number {
+  return themeReadCount
+}
+
+/** Test-only — clear the theme memo so the next read hits disk. */
+export function __resetThemeMemo(): void {
+  themeMemo.clear()
 }
 
 /**
@@ -127,6 +196,17 @@ function getLibraryFingerprint(): string {
   return libraryFingerprint
 }
 
+/**
+ * Test-only override for the memoised library fingerprint. Production reads
+ * the value once from disk; tests use this to simulate a library upgrade
+ * (fingerprint rotation) without rebuilding the lib. Passing `undefined`
+ * clears the override so the next call re-derives from disk.
+ * @param value Forced fingerprint, or omit/`undefined` to clear the override.
+ */
+export function __setLibraryFingerprintForTest(value?: string): void {
+  libraryFingerprint = value
+}
+
 /**
  * Worker-local state. Lazy-initialised on first access so files that
  * bypass the transform don't pay for construction.
@@ -136,6 +216,12 @@ export interface RnwindState {
   builder: UnionBuilder
   themeCss: string
   themeHash: string
+  /**
+   * Library fingerprint captured when this state was built. Folded into the
+   * rebuild guard so an in-place rnwind upgrade (unchanged CSS, rotated
+   * fingerprint) drops the stale builder + on-disk scheme format.
+   */
+  libraryFingerprint: string
   projectRoot: string
 }
 
@@ -167,6 +253,7 @@ export function configureRnwindState(
     process.env[WRAP_MODULES_ENV] = wrapModules.join(',')
   }
   cached = null
+  cachedWrapModules = null
 }
 
 /**
@@ -175,9 +262,11 @@ export function configureRnwindState(
  * @returns Module → policy map the import-rewrite consults.
  */
 export function getWrapModules(): ReturnType<typeof buildWrapModules> {
+  if (cachedWrapModules) return cachedWrapModules
   const raw = process.env[WRAP_MODULES_ENV]
   const extra = raw && raw.length > 0 ? raw.split(',').filter((entry) => entry.length > 0) : undefined
-  return buildWrapModules(extra)
+  cachedWrapModules = buildWrapModules(extra)
+  return cachedWrapModules
 }
 
 /**
@@ -196,14 +285,26 @@ export function getRnwindState(projectRoot: string): RnwindState {
   if (!cssEntry) throw new Error('rnwind: RNWIND_CSS_ENTRY_FILE is not set — did `withRnwindConfig` run?')
   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 = resolveThemeCss(cssEntry)
+  const currentFingerprint = getLibraryFingerprint()
+  // Reuse only when the CSS hash, the project root, AND the library
+  // fingerprint all match — an in-place rnwind upgrade rotates the
+  // fingerprint while the CSS hash is unchanged, and that must still rebuild.
+  if (
+    cached?.themeHash === currentHash &&
+    cached.libraryFingerprint === currentFingerprint &&
+    cached.projectRoot === projectRoot
+  ) {
+    return cached
+  }
+  // Served from the same mtime memo `readThemeHashFor` just populated — no
+  // second disk read on the rebuild path.
+  const themeCss = readThemeCssFor(cssEntry)
   const parser = new TailwindParser({
     themeCss,
     sources: defaultSources(projectRoot, cacheDir, readWatchFolders()),
   })
   const builder = new UnionBuilder(cacheDir, parser)
-  cached = { parser, builder, themeCss, themeHash: currentHash, projectRoot }
+  cached = { parser, builder, themeCss, themeHash: currentHash, libraryFingerprint: currentFingerprint, projectRoot }
   return cached
 }
 
@@ -229,6 +330,7 @@ export function getRnwindCacheKey(): string {
 /** Drop the cached state — call after editing the theme CSS. */
 export function resetRnwindState(): void {
   cached = null
+  cachedWrapModules = null
 }
 
 /**
@@ -241,6 +343,9 @@ export function resetRnwindState(): void {
  * @param projectRoot Absolute project root (from `metroConfig.projectRoot`).
  */
 export async function onThemeChange(projectRoot: string): Promise<void> {
+  // The watcher already told us the CSS changed; an atomic save can reuse the
+  // same mtime, so bust the memo unconditionally rather than trusting stat.
+  themeMemo.clear()
   resetRnwindState()
   const state = getRnwindState(projectRoot)
   await state.builder.writeSchemes()

package/src/metro/transformer.ts

@@ -174,13 +174,18 @@ async function rewriteSource(args: BabelTransformerArgs): Promise<string> {
   // Wrap host imports ONLY when className flows through a component — written
   // (`hasClassName`) or forwarded (`{...rest}`). A `useCss`/`cva`-only file
   // resolves manually, so its imports (e.g. skia drawing primitives) are
-  // left untouched.
-  const wrapped = hasClassName || hasSpread ? rewriteWrapImports(ast, getWrapModules()) : false
+  // left untouched. Mutates the AST in place; both branches below regenerate.
+  if (hasClassName || hasSpread) rewriteWrapImports(ast, getWrapModules())
 
   if (!hasAtoms) {
-    // Wrap-only forwarder — no classes to record/register.
+    // Wrap-only forwarder — no classes to record/register, but className
+    // still flows through it (`hasClassName || hasSpread`). It MUST hold a
+    // dep-graph edge to the theme CSS so a theme edit re-transforms it and
+    // its forwarded className resolves against the new scheme — otherwise it
+    // renders stale. Inject the theme-signature import even with no atoms.
     state.builder.dropFile(args.filename)
-    return wrapped ? generateModule(ast).code : args.src
+    injectThemeSignatureImport(ast)
+    return generateModule(ast).code
   }
 
   warnUnknownClasses(args.src, parsed.candidates, parsed.atoms, args.filename, [parsed.gradientAtoms, parsed.hapticAtoms])

package/src/metro/with-config.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, watch as watchFile } from 'node:fs'
+import { existsSync, mkdirSync, rmSync, watch as watchFile } from 'node:fs'
 import path from 'node:path'
 import { writeDtsFile } from './dts'
 import { createRnwindResolver, type ResolveRequestFn } from './resolver'
@@ -79,6 +79,58 @@ function resolveCacheDir(projectRoot: string, override: string | undefined): str
   return path.isAbsolute(override) ? override : path.resolve(projectRoot, override)
 }
 
+/** Cache dirs already wiped this process — guards the reset so it fires once per dir, not on every worker (re)configure. */
+const wipedCacheDirs = new Set<string>()
+
+/**
+ * CLI flags that mean "reset the cache". `metro.config.js` (→ this function)
+ * is evaluated BEFORE Metro/Expo merge the flag onto the config object
+ * (`overrideConfigWithArguments` / Expo's `instantiateMetro` both set
+ * `resetCache` AFTER loading the config), so `config.resetCache` is still its
+ * `false` default here. The reliable signal at config-eval time is the CLI
+ * argv of the same process: `react-native start --reset-cache`, Metro
+ * `--reset-cache`, and Expo `start -c` / `--clear`.
+ */
+const RESET_CACHE_ARGS: ReadonlySet<string> = new Set(['--reset-cache', '--resetCache', '--clear', '-c'])
+
+/**
+ * Whether the dev asked for a cache reset — true if the (post-merge) config
+ * flag is set OR the CLI argv carries a reset flag. Wiping on a false positive
+ * is harmless (the cache just regenerates), so argv detection errs toward
+ * honoring the request.
+ * @param resetCache Metro's `config.resetCache` (usually still false at config-eval time).
+ * @param argv Process argv (injectable for tests).
+ * @returns True when the cache dir should be wiped.
+ */
+export function isResetCacheRequested(resetCache: boolean | undefined, argv: readonly string[] = process.argv): boolean {
+  if (resetCache === true) return true
+  return argv.some((argument) => RESET_CACHE_ARGS.has(argument))
+}
+
+/**
+ * On a Metro `--reset-cache` run (Expo `start -c` / `--clear`) the dev
+ * explicitly asked for a clean slate, so rnwind's generated cache dir
+ * (`*.style.js` scheme chunks + `schemes.js` manifest) is stale and must be
+ * wiped before `ensureFilesExist` regenerates it — otherwise old chunks
+ * survive a reset and Metro's haste-map indexes dead bytes. Only ever removes
+ * the resolved cache dir rnwind owns, never the project root, and never throws
+ * when the dir is already absent. Idempotent per dir within one process.
+ * @param cacheDir Absolute path to rnwind's cache dir.
+ * @param resetCache Metro's resolved `config.resetCache` flag.
+ * @param projectRoot Absolute project root — guards against ever wiping it.
+ */
+function resetCacheDirIfRequested(cacheDir: string, resetCache: boolean | undefined, projectRoot: string): void {
+  if (!isResetCacheRequested(resetCache)) return
+  if (wipedCacheDirs.has(cacheDir)) return
+  // Hard safety: never rm the project root (or an ancestor of it) even if a
+  // mis-configured cacheDir resolves there.
+  const resolvedCache = path.resolve(cacheDir)
+  const resolvedRoot = path.resolve(projectRoot)
+  if (resolvedCache === resolvedRoot || resolvedRoot.startsWith(resolvedCache + path.sep)) return
+  wipedCacheDirs.add(cacheDir)
+  rmSync(resolvedCache, { recursive: true, force: true })
+}
+
 /**
  * Read the theme CSS and extract `@variant <name>` blocks for the .d.ts
  * generator. Forces construction of `getRnwindState`, then reads
@@ -128,6 +180,8 @@ export interface RnwindMetroOptions {
 export interface MetroConfigLike {
   projectRoot?: string
   watchFolders?: string[]
+  /** Set by Metro when the dev runs `--reset-cache` (Expo `start -c`). Wipes rnwind's cache dir. */
+  resetCache?: boolean
   transformer?: {
     babelTransformerPath?: string
     [key: string]: unknown
@@ -166,6 +220,10 @@ export function withRnwindConfig<C extends MetroConfigLike>(metroConfig: C, opti
   const cacheDir = resolveCacheDir(projectRoot, options.cacheDir)
   const cssEntry = path.isAbsolute(options.cssEntryFile) ? options.cssEntryFile : path.resolve(projectRoot, options.cssEntryFile)
 
+  // Honor Metro's `--reset-cache`: wipe rnwind's stale generated dir BEFORE we
+  // recreate it + before `ensureFilesExist` regenerates and the haste-map
+  // indexes it. Synchronous so the dir is clean by the time this returns.
+  resetCacheDirIfRequested(cacheDir, metroConfig.resetCache, projectRoot)
   mkdirSync(cacheDir, { recursive: true })
   const watchFolders = (metroConfig.watchFolders ?? []).filter((p) => typeof p === 'string' && p.length > 0)
   configureRnwindState(cssEntry, cacheDir, watchFolders, options.wrapModules)

package/src/metro/wrap-imports.ts

@@ -84,8 +84,26 @@ const NON_COMPONENT_EXPORTS: ReadonlySet<string> = new Set([
   'Easing',
   'ReduceMotion',
   'KeyframeRegistry',
+  // gesture-handler enums (PascalCase, but value objects accessed as
+  // `PointerType.TOUCH` / `MouseButton.LEFT`) — wrapping breaks the access.
+  'PointerType',
+  'MouseButton',
+  'HoverEffect',
 ])
 
+/**
+ * react-native-reanimated's NAMED exports are hooks, worklets, animation
+ * builders (`FadeIn`, `ZoomIn`, `Keyframe`, `Layout`…), easing helpers and
+ * enums (`SensorType`…) — NOT className-styleable components. Its only
+ * styleable surface is the DEFAULT `Animated` namespace, wrapped separately
+ * via {@link NAMESPACE_DEFAULT_MODULES}. Under the `'all'` policy the
+ * PascalCase heuristic wrongly wrapped builders/enums into `wrap()`-ed
+ * functions, so `FadeIn.duration()` / `new Keyframe()` / `SensorType.X` threw
+ * "is not a function" / "is not a constructor" / read `undefined`. An empty
+ * allow-list wraps none of them while leaving the default namespace intact.
+ */
+const REANIMATED_NAMED_COMPONENTS: ReadonlySet<string> = new Set()
+
 /** Per-module policy: an explicit allow-list, or `'all'` named exports. */
 export type WrapPolicy = 'all' | ReadonlySet<string>
 
@@ -97,7 +115,7 @@ export type WrapPolicy = 'all' | ReadonlySet<string>
  */
 export const DEFAULT_WRAP_MODULES: ReadonlyMap<string, WrapPolicy> = new Map<string, WrapPolicy>([
   ['react-native', REACT_NATIVE_COMPONENTS],
-  ['react-native-reanimated', 'all'],
+  ['react-native-reanimated', REANIMATED_NAMED_COMPONENTS],
   ['react-native-svg', 'all'],
   ['react-native-gesture-handler', 'all'],
   ['react-native-safe-area-context', 'all'],
@@ -151,6 +169,19 @@ function importedNameOf(specifier: t.ImportSpecifier): string {
   return t.isIdentifier(specifier.imported) ? specifier.imported.name : specifier.imported.value
 }
 
+/**
+ * Whether an import kind is type-only (`import type …` / `import { type … }`,
+ * and the Flow `typeof` variants). Type-only bindings carry no runtime value —
+ * preset-typescript strips them from the bundle — so wrapping one emits a
+ * `const X = wrap(_rnwN)` referencing a binding that no longer exists at
+ * runtime → Hermes "Property '_rnwN' doesn't exist". They must never be wrapped.
+ * @param kind The `importKind` of a declaration or specifier.
+ * @returns True when the import is type-only.
+ */
+function isTypeOnly(kind: t.ImportDeclaration['importKind'] | t.ImportSpecifier['importKind']): boolean {
+  return kind === 'type' || kind === 'typeof'
+}
+
 /**
  * Build `const Local = <wrapper>(alias)` and rebind the specifier's local
  * to `alias` in place.
@@ -193,8 +224,12 @@ function wrapSpecifiers(
   const moduleName = node.source.value
   let next = counter
   let usesNamespace = false
+  // `import type { … }` — whole declaration is type-only; nothing to wrap.
+  if (isTypeOnly(node.importKind)) return { decls, counter: next, usesNamespace }
   for (const specifier of node.specifiers) {
     if (t.isImportSpecifier(specifier)) {
+      // `import { type X }` — inline type-only specifier; skip it.
+      if (isTypeOnly(specifier.importKind)) continue
       if (!shouldWrap(policy, importedNameOf(specifier))) continue
       decls.push(makeWrapDecl(specifier, `_rnw${next}`, WRAP_LOCAL))
       next += 1

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

@@ -1,3 +1,4 @@
+import { useMemo } from 'react'
 import type { ThemeTable } from '../../core/types'
 import { useRnwind } from '../components/rnwind-provider'
 import { getThemeTokens } from '../lookup-css'
@@ -23,13 +24,19 @@ export function useTheme(): ThemeTable {
   const { scheme, tables } = useRnwind()
   // The build registers token tables on the manifest so `useColor` works out
   // of the box; an explicit `tables` prop layers on top (the prop wins).
+  // `getThemeTokens()` REPLACES its map on registration, so its identity is
+  // stable between (HMR) registers — a sound memo dep. Memoizing keeps the
+  // merged table a STABLE reference across renders, so every `useColor` /
+  // `useToken` / `useSize` call avoids re-allocating 2–3 objects per render.
   const registered = getThemeTokens()
-  const base = { ...registered[BASE_SCHEME], ...tables[BASE_SCHEME] }
-  const schemeTable = { ...registered[scheme], ...tables[scheme] }
-  // Base tokens apply everywhere (CSS `:root` cascade); the active scheme's
-  // own entries override on overlap.
-  if (Object.keys(schemeTable).length === 0) return base
-  return { ...base, ...schemeTable }
+  return useMemo(() => {
+    const base = { ...registered[BASE_SCHEME], ...tables[BASE_SCHEME] }
+    const schemeTable = { ...registered[scheme], ...tables[scheme] }
+    // Base tokens apply everywhere (CSS `:root` cascade); the active scheme's
+    // own entries override on overlap.
+    if (Object.keys(schemeTable).length === 0) return base
+    return { ...base, ...schemeTable }
+  }, [scheme, tables, registered])
 }
 
 /**

package/src/runtime/resolve.ts

@@ -109,12 +109,16 @@ const DIRECTION_POINTS: Record<GradientDirection, { start: GradientPoint; end: G
 
 /**
  * Register one scheme's pre-merged molecules (atom-merged literal
- * classNames). Merges onto any existing entries for the scheme.
+ * classNames). REPLACES the scheme's map — each generated scheme file emits a
+ * single `registerMolecules(scheme, …)` carrying the complete molecule set
+ * (mirrors `registerAtoms`). Merging instead would leak molecules removed in a
+ * Fast Refresh edit, so a deleted/renamed className would keep resolving to its
+ * stale pre-edit style.
  * @param scheme Scheme name (or `'common'`).
  * @param entries Normalized className → merged style object.
  */
 export function registerMolecules(scheme: string, entries: Record<string, unknown>): void {
-  molecules[scheme] = { ...molecules[scheme], ...entries }
+  molecules[scheme] = entries
   registryVersion += 1
 }