rnwind 0.0.8 → 0.0.10

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

@@ -1,4 +1,5 @@
 import type { KeyframeBlock, RNStyle, SchemedStyle } from '../parser'
+import type { ThemeTables } from '../types'
 import { normalizeClassName } from '../normalize-classname'
 
 /** Match atom names like `border-hairline`, `h-hairline`, `border-t-hairline`, etc. */
@@ -300,6 +301,7 @@ function serializeBreakpoints(breakpoints: ReadonlyMap<string, number>): string
  * @param breakpoints Responsive breakpoint name → px-threshold map.
  * @param gradients Atom → gradient info for `registerGradients`.
  * @param haptics Atom → haptic request for `registerHaptics`.
+ * @param themeTokens
  * @returns JS source text.
  */
 function renderManifest(
@@ -307,15 +309,19 @@ function renderManifest(
   breakpoints: ReadonlyMap<string, number>,
   gradients: ReadonlyMap<string, unknown>,
   haptics: ReadonlyMap<string, unknown>,
+  themeTokens: ThemeTables,
 ): string {
+  const hasTokens = Object.keys(themeTokens).length > 0
   const imports = ['registerSchemeLoader', 'registerBreakpoints']
   if (gradients.size > 0) imports.push('registerGradients')
   if (haptics.size > 0) imports.push('registerHaptics')
+  if (hasTokens) imports.push('registerThemeTokens')
   const lines: string[] = [`import { ${imports.join(', ')} } from 'rnwind'`, `import './common.style'`]
   for (const variant of variants) lines.push(`import ${JSON.stringify(`./${variant}.style`)}`)
   lines.push(``, `registerBreakpoints(${serializeBreakpoints(breakpoints)})`)
   if (gradients.size > 0) lines.push(`registerGradients(${serializeFeatureMap(gradients)})`)
   if (haptics.size > 0) lines.push(`registerHaptics(${serializeFeatureMap(haptics)})`)
+  if (hasTokens) lines.push(`registerThemeTokens(${JSON.stringify(themeTokens)})`)
   lines.push(
     ``,
     `function ensureSchemeLoaded(_name) {}`,
@@ -679,6 +685,7 @@ const EMPTY_BREAKPOINTS: ReadonlyMap<string, number> = new Map()
  * @param literals Distinct literal className strings — pre-merged into
  *   per-scheme molecules so the runtime resolver's O(1) molecule-first
  *   path is populated. Empty for legacy/test callers (atom path only).
+ * @param themeTokens
  * @returns Per-scheme sources, manifest source, variant list.
  */
 export function buildSchemeSources(
@@ -690,6 +697,7 @@ export function buildSchemeSources(
   gradients: ReadonlyMap<string, unknown> = EMPTY_FEATURE_MAP,
   haptics: ReadonlyMap<string, unknown> = EMPTY_FEATURE_MAP,
   literals: readonly string[] = EMPTY_LITERALS,
+  themeTokens: ThemeTables = EMPTY_THEME_TOKENS,
 ): BuildSchemeSourcesOutput {
   const variants = collectVariantSchemes(resolved)
   const commonEntries: (readonly [string, string])[] = []
@@ -715,7 +723,7 @@ export function buildSchemeSources(
 
   return {
     schemeSources,
-    manifestSource: renderManifest(variants, breakpoints, gradients, haptics),
+    manifestSource: renderManifest(variants, breakpoints, gradients, haptics, themeTokens),
     variants,
     serializedMisses: misses,
   }
@@ -727,5 +735,8 @@ const EMPTY_FEATURE_MAP: ReadonlyMap<string, unknown> = new Map()
 /** Shared empty literal-list default (atom-only callers). */
 const EMPTY_LITERALS: readonly string[] = []
 
+/** Shared empty theme-token default (callers without theme tokens). */
+const EMPTY_THEME_TOKENS: ThemeTables = {}
+
 /** Registry key the runtime uses for the always-loaded fallback. */
 export const COMMON_SCHEME_NAME: string = COMMON_SCHEME

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

@@ -2,6 +2,7 @@ import { createHash, randomBytes } from 'node:crypto'
 import { existsSync, mkdirSync, 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'
 import { buildSchemeSources, type AtomSerializedCache } from './build-style'
 
 /** Manifest module basename — the file SchemeProvider imports via the resolver. */
@@ -110,6 +111,13 @@ class UnionBuilder {
    * snapshot is sufficient.
    */
   private breakpoints: ReadonlyMap<string, number> = new Map()
+  /**
+   * Per-scheme theme token tables captured from the parser. Refreshed on
+   * every `recordFile` / `ensureProjectScanned` so theme-token edits land in
+   * the manifest's `registerThemeTokens({...})` — the data source for
+   * `useColor` / `useToken` / `useSize`.
+   */
+  private themeTokens: ThemeTables = {}
   /** 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). */
@@ -143,17 +151,6 @@ class UnionBuilder {
     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
@@ -183,6 +180,7 @@ class UnionBuilder {
       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.themeTokens = parsed.themeTokens
       this.projectScanned = true
     })()
     try {
@@ -279,7 +277,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, this.unionGradients, this.unionHaptics, [...this.unionLiterals])
+    const result = buildSchemeSources(sortedAtomNames, this.unionAtoms, this.unionKeyframes, this.serializedCache, this.breakpoints, this.unionGradients, this.unionHaptics, [...this.unionLiterals], this.themeTokens)
     this.serializedMissesCount += result.serializedMisses
     const { schemeSources, manifestSource } = result
 

package/src/metro/dts.ts

@@ -100,7 +100,12 @@ export function writeDtsFile(targetPath: string, schemes: readonly string[]): vo
   lines.push('}', '')
   if (schemes.length > 0) {
     lines.push(`declare module 'rnwind' {`, `  export interface RnwindConfig {`)
-    const schemeLiterals = schemes.map((s) => `'${s}'`).join(', ')
+    // Escape backslash / single-quote so a scheme name with a quote (only
+    // reachable via the public `writeDtsFile`, since CSS idents can't contain
+    // one) can't emit invalid TS that breaks the whole file and drops the
+    // `className` augmentation project-wide. Single-quoted to match the rest
+    // of the generated declaration.
+    const schemeLiterals = schemes.map((s) => `'${s.replaceAll('\\', '\\\\').replaceAll("'", String.raw`\'`)}'`).join(', ')
     lines.push(`    themes: readonly [${schemeLiterals}]`, `  }`, '}', '')
   }
   // The `export {}` is mandatory — without at least one top-level

package/src/metro/transformer.ts

@@ -17,14 +17,6 @@ interface UpstreamTransformer {
 /** Env var that points at the upstream `babelTransformerPath` we override. */
 const UPSTREAM_ENV = 'RNWIND_UPSTREAM_TRANSFORMER'
 
-/**
- * Matches a `useCss(` call. Files that resolve classes via the `useCss`
- * hook (no JSX `className=`) must still be scanned so the classes inside
- * `useCss("…")` get registered — common for theme/accent hooks living in a
- * shared package the project scan may not reach.
- */
-const USE_CSS_CALL = /\buseCss\s*\(/
-
 /** Cached upstream module — required once, reused across every transform call. */
 let cachedUpstream: UpstreamTransformer | null = null
 
@@ -145,44 +137,53 @@ function isThemeCssEntry(filename: string): boolean {
  * @returns Rewritten source text.
  */
 async function rewriteSource(args: BabelTransformerArgs): Promise<string> {
-  const ast = parseUserSource(args.src)
-  if (!ast) return args.src
+  // SCAN FIRST — exactly like Tailwind: oxide extracts class candidates from
+  // the WHOLE file content (className, cva/clsx, plain strings, anywhere),
+  // and the compiler is the only filter. No babel parse needed to scan, so
+  // the common "file with no classes" case stays cheap and the source is
+  // returned untouched. This is what makes adding a class ANYWHERE register
+  // on hot-reload, not just inside a `className=` or a known helper call.
+  const state = getRnwindState(projectRootOf(args))
+  const extension = extensionOf(args.filename)
+  const parsed = await state.parser.parseAtoms({ content: args.src, extension })
+  const hasAtoms = parsed.atoms.size > 0
 
   const hasClassName = /classname=/i.test(args.src)
-  const hasUseCss = USE_CSS_CALL.test(args.src)
   const hasSpread = /\{\s*\.\.\./.test(args.src)
 
-  // Wrap host component imports ONLY when className arrives through a
-  // component — written (`hasClassName`) or forwarded (`hasSpread`). A
-  // `useCss("…")`-only file resolves manually, so we must NOT wrap its
-  // imports: a non-RN drawing lib (e.g. skia's `LinearGradient` nested in
-  // `SkiaText`) breaks if its primitives are replaced by a wrapper.
-  const wrapped = hasClassName || hasSpread ? rewriteWrapImports(ast, getWrapModules()) : false
-
-  if (!hasClassName && !hasUseCss) {
-    // Import-only file: nothing to compile. Drop any stale atom
-    // contribution (className may have just been removed) and emit the
-    // wrapped imports — or the untouched source when nothing wrapped.
-    dropFileSafely(args.filename, projectRootOf(args))
-    return wrapped ? generateModule(ast).code : args.src
+  // Nothing for rnwind to do: no Tailwind class compiled AND no host
+  // wrapping needed. Drop any stale contribution and emit the file as-is.
+  if (!hasAtoms && !hasClassName && !hasSpread) {
+    state.builder.dropFile(args.filename)
+    return args.src
   }
 
-  // Scan path — runs for `className=` literals AND/OR `useCss("…")` strings.
-  // oxide reads class candidates from the whole file content, so classes
-  // that only ever appear inside a `useCss("…")` call still register.
-  const state = getRnwindState(projectRootOf(args))
-  const extension = extensionOf(args.filename)
-  const parsed = await state.parser.parseAtoms({ content: args.src, extension })
+  const ast = parseUserSource(args.src)
+  if (!ast) {
+    // Can't parse to wrap/inject, but we DID scan — still record the atoms so
+    // they register (a malformed-but-recoverable file shouldn't lose styles).
+    if (hasAtoms) {
+      await state.builder.recordFile(args.filename, parsed.atoms, parsed.keyframes, [])
+      await state.builder.writeSchemes()
+    } else {
+      state.builder.dropFile(args.filename)
+    }
+    return args.src
+  }
 
-  warnUnknownClasses(args.src, parsed.candidates, parsed.atoms, args.filename, [parsed.gradientAtoms, parsed.hapticAtoms])
+  // 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
 
-  if (parsed.atoms.size === 0) {
+  if (!hasAtoms) {
+    // Wrap-only forwarder — no classes to record/register.
     state.builder.dropFile(args.filename)
-    await state.builder.writeSchemes()
-    injectThemeSignatureImport(ast)
-    return generateModule(ast).code
+    return wrapped ? generateModule(ast).code : args.src
   }
 
+  warnUnknownClasses(args.src, parsed.candidates, parsed.atoms, args.filename, [parsed.gradientAtoms, parsed.hapticAtoms])
   const literals = collectClassNameLiterals(ast)
   const { changed } = await state.builder.recordFile(args.filename, parsed.atoms, parsed.keyframes, literals)
   if (changed) await state.builder.writeSchemes()
@@ -192,21 +193,6 @@ async function rewriteSource(args: BabelTransformerArgs): Promise<string> {
   return generateModule(ast).code
 }
 
-/**
- * Drop a file's union contribution, swallowing the "state not configured"
- * error unit tests hit when they call the transformer without
- * `configureRnwindState`.
- * @param filename Absolute source path.
- * @param projectRoot Project root for state lookup.
- */
-function dropFileSafely(filename: string, projectRoot: string): void {
-  try {
-    getRnwindState(projectRoot).builder.dropFile(filename)
-  } catch {
-    // State not configured (standalone/unit test). Nothing to drop.
-  }
-}
-
 /**
  * Whether a JSX attribute names a className-style prop (`className` or
  * any `<prefix>ClassName`).
@@ -404,19 +390,12 @@ function loadUpstream(): UpstreamTransformer | null {
  */
 function isRewriteCandidate(args: BabelTransformerArgs): boolean {
   if (!/\.(?:tsx|ts|jsx|js)$/i.test(args.filename)) return false
-  // Process the file when it either:
-  //  - carries a `className=` / `<prefix>ClassName=` literal (case-
-  //    insensitive — `contentContainerClassName=` has a capital C), or
-  //  - calls `useCss("…")` (classes that only ever appear in the hook must
-  //    still be scanned + registered — common for theme/accent hooks), or
-  //  - spreads props (`{...rest}`) onto a host from a wrap-module, where a
-  //    forwarded className must still get its import wrapped (no literal
-  //    appears in this file). A style-less `<View/>` with none is left
-  //    alone so it never pays for an unused wrapper.
-  const hasClassName = /classname=/i.test(args.src)
-  const hasUseCss = USE_CSS_CALL.test(args.src)
-  const isForwarder = /\{\s*\.\.\./.test(args.src) && mentionsWrapModule(args.src)
-  if (!hasClassName && !hasUseCss && !isForwarder) return false
+  // EVERY user source file is scanned — exactly like Tailwind walks its
+  // whole content set. The compiler is the only filter (see rewriteSource);
+  // no className/helper pre-filter, because that "filter magic" missed
+  // classes living in cva/clsx/plain-string files and broke their hot-reload.
+  // (Cheap when the file has no classes: oxide finds nothing, no babel parse,
+  // source returned untouched.)
   if (!args.filename.includes('/node_modules/')) return true
   // node_modules in path → could be a workspace symlink; resolve it.
   try {
@@ -427,21 +406,6 @@ function isRewriteCandidate(args: BabelTransformerArgs): boolean {
   }
 }
 
-/**
- * Cheap pre-parse check: does the source import from any configured
- * wrap-module? A quoted specifier match is enough — `rewriteWrapImports`
- * re-verifies precisely on the AST, so a false positive only costs a
- * no-op parse.
- * @param source Source text.
- * @returns True when a wrap-module specifier appears in the source.
- */
-function mentionsWrapModule(source: string): boolean {
-  for (const moduleName of getWrapModules().keys()) {
-    if (source.includes(`'${moduleName}'`) || source.includes(`"${moduleName}"`)) return true
-  }
-  return false
-}
-
 /**
  * Fallback parse when no upstream is configured AND Metro didn't hand
  * us an AST. Used by unit tests and standalone setups.

package/src/metro/with-config.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, utimesSync, watch as watchFile } from 'node:fs'
+import { existsSync, mkdirSync, watch as watchFile } from 'node:fs'
 import path from 'node:path'
 import { writeDtsFile } from './dts'
 import { createRnwindResolver, type ResolveRequestFn } from './resolver'
@@ -15,14 +15,15 @@ const DEFAULT_CACHE_DIR = '.rnwind'
 let activeCssWatcher: { cssPath: string; close: () => void } | null = null
 
 /**
- * Watch the theme CSS for edits. On change, rewrite the per-scheme
- * files with the fresh theme AND bump `mtime` on every source file
- * rnwind has transformed so far — Metro's own watcher sees those
- * mtime changes, invalidates the modules, and re-transforms them
- * against the new CSS on the next request. `getCacheKey()` alone is
- * NOT enough: Metro samples the cache key once per worker lifetime,
- * so edits during an already-running dev server don't propagate
- * without this explicit nudge.
+ * Watch the theme CSS for edits. On change, rebuild state against the fresh
+ * CSS and rewrite the per-scheme files (`onThemeChange` → full rescan →
+ * `writeSchemes`). That's the entire HMR signal: every transformed source
+ * imports `rnwind/__generated/schemes`, which eager-imports
+ * `common.style.js`; the rewrite changes its bytes, Metro's content-SHA1
+ * dedup notices, and every importer is invalidated + re-bundled with the new
+ * style values. The rewritten JSX references atoms by NAME (theme-independent),
+ * so no source-file re-transform / mtime nudge is needed — the dep graph
+ * carries the signal.
  * @param cssPath Absolute path to the theme CSS to watch.
  * @param projectRoot Metro's project root (for `getRnwindState`).
  */
@@ -40,7 +41,6 @@ function watchThemeCss(cssPath: string, projectRoot: string): void {
       pending = false
       try {
         await onThemeChange(projectRoot)
-        touchRecordedFiles(projectRoot)
       } catch {
         // Invalidation is best-effort — never crash the dev server.
       }
@@ -49,25 +49,6 @@ function watchThemeCss(cssPath: string, projectRoot: string): void {
   activeCssWatcher = { cssPath, close: () => watcher.close() }
 }
 
-/**
- * Bump the mtime on every file the builder has transformed. Metro's
- * file watcher keys on `mtime`, so this is what makes it invalidate
- * those modules and re-transform them.
- * @param projectRoot Metro's project root.
- */
-function touchRecordedFiles(projectRoot: string): void {
-  const state = getRnwindState(projectRoot)
-  const files = state.builder.recordedFiles()
-  const now = new Date()
-  for (const file of files) {
-    try {
-      if (existsSync(file)) utimesSync(file, now, now)
-    } catch {
-      // One file's stat failure shouldn't stop the others.
-    }
-  }
-}
-
 /**
  * Where the rnwind babel transformer lives — resolved relative to this
  * module so the path works from both the `src/` tree (tests) and the

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

@@ -1,5 +1,6 @@
 import type { ThemeTable } from '../../core/types'
 import { useRnwind } from '../components/rnwind-provider'
+import { getThemeTokens } from '../lookup-css'
 
 /**
  * Synthetic scheme name applied when tokens aren't declared under any
@@ -20,10 +21,13 @@ const BASE_SCHEME = 'base'
  */
 export function useTheme(): ThemeTable {
   const { scheme, tables } = useRnwind()
-  const base = tables[BASE_SCHEME] ?? {}
-  const schemeTable = tables[scheme]
-  if (!schemeTable) return base
-  // Fast path: nothing to merge when the scheme table is empty.
+  // 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).
+  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 }
 }
@@ -42,22 +46,25 @@ export function useToken(cssVariable: string): string | number | undefined {
 
 /**
  * Read a color token by shorthand name — `useColor('primary')` resolves
- * `--color-primary` for the active scheme.
- * @param name Token suffix after `--color-`.
+ * `--color-primary` for the active scheme. A fully-qualified name
+ * (`--color-primary`) is accepted as-is, so the call doesn't silently miss by
+ * double-prefixing into `--color---color-primary`.
+ * @param name Token suffix after `--color-`, or the full `--color-*` name.
  * @returns Resolved color string, or undefined when the token is missing
  *   or its value isn't a string.
  */
 export function useColor(name: string): string | undefined {
-  const value = useToken(`--color-${name}`)
+  const value = useToken(name.startsWith('--') ? name : `--color-${name}`)
   return typeof value === 'string' ? value : undefined
 }
 
 /**
  * Read a spacing token by shorthand name — `useSize('4')` resolves
- * `--spacing-4` for the active scheme.
- * @param name Token suffix after `--spacing-`.
+ * `--spacing-4` for the active scheme. A fully-qualified `--spacing-*` name is
+ * accepted as-is (no double-prefix miss).
+ * @param name Token suffix after `--spacing-`, or the full `--spacing-*` name.
  * @returns Resolved spacing value, or undefined when the token is missing.
  */
 export function useSize(name: string): number | string | undefined {
-  return useToken(`--spacing-${name}`)
+  return useToken(name.startsWith('--') ? name : `--spacing-${name}`)
 }

package/src/runtime/index.ts

@@ -2,6 +2,7 @@ export {
   lookupCss,
   registerAtoms,
   registerBreakpoints,
+  registerThemeTokens,
   registerSchemeLoader,
   setWindowHeightProvider,
   getBreakpoints,
@@ -28,4 +29,4 @@ export type { Scheme, RnwindConfig } from './types'
  * string when integrating with build tooling that may see multiple rnwind
  * copies (e.g. workspace overrides).
  */
-export const VERSION = '0.0.1' as const
+export const VERSION = '0.0.8' as const

package/src/runtime/lookup-css.ts

@@ -16,6 +16,7 @@
  */
 
 import type { RnwindState } from './components/rnwind-provider'
+import type { ThemeTables } from '../core/types'
 
 /** Empty sentinel returned when the input is null / undefined / empty. */
 const EMPTY_STYLES: readonly unknown[] = []
@@ -62,6 +63,8 @@ const cache = {
   atoms: Object.create(null) as Partial<Record<string, SchemeAtomsRecord>>,
   breakpoints: Object.create(null) as Partial<Record<string, number>>,
   breakpointList: [] as readonly BreakpointEntry[],
+  /** Per-scheme theme token tables (`--color-*`, `--spacing-*`, …) the manifest registers for `useColor` / `useToken` / `useSize`. */
+  themeTokens: {} as ThemeTables,
 }
 
 /**
@@ -280,6 +283,20 @@ function tierFor(windowWidth: number): number {
   return tier
 }
 
+/**
+ * Public breakpoint-tier for a width — the count of registered breakpoints
+ * whose threshold is reached. Used by the runtime resolver as its width
+ * cache dimension: the numeric tier is bounded AND exact, unlike the
+ * clamped `activeBreakpoint` NAME (which collapses tier-0 into the smallest
+ * breakpoint, so widths straddling that threshold would share a cache key
+ * and serve a stale style).
+ * @param windowWidth Live window width in px.
+ * @returns Tier 0..N.
+ */
+export function breakpointTier(windowWidth: number): number {
+  return tierFor(windowWidth)
+}
+
 /**
  * Build the style array for a (hoist, scheme, state, width) tuple.
  * Walks the atom list, applies the interact-state and breakpoint
@@ -539,6 +556,30 @@ export function getBreakpoints(): readonly BreakpointEntry[] {
   return cache.breakpointList
 }
 
+/**
+ * Register the per-scheme theme token tables the manifest module emits at
+ * load time — the data source for `useColor` / `useToken` / `useSize`. The
+ * build lowers `--color-*` tokens to sRGB before registering them, so these
+ * are RN-safe. Replaces the prior tables; bumps `atomVersion` so a theme HMR
+ * cycle re-resolves. The build registers tokens here so the hooks work out of
+ * the box, without the user manually threading a `tables` prop on the provider.
+ * @param tables Scheme name → (token name → value) map.
+ */
+export function registerThemeTokens(tables: ThemeTables): void {
+  cache.themeTokens = tables
+  atomVersion += 1
+}
+
+/**
+ * The manifest-registered theme token tables. The provider merges these under
+ * any explicit `tables` prop (the prop wins), so `useColor` resolves from the
+ * build by default.
+ * @returns Registered per-scheme token tables.
+ */
+export function getThemeTokens(): ThemeTables {
+  return cache.themeTokens
+}
+
 /**
  * Sentinel name returned by {@link activeBreakpointFor} ONLY when no
  * breakpoints are registered at all (bundle without rnwind-transformed
@@ -621,6 +662,7 @@ export function __resetLookupCssState(): void {
   for (const key of Object.keys(cache.atoms)) delete cache.atoms[key]
   for (const key of Object.keys(cache.breakpoints)) delete cache.breakpoints[key]
   cache.breakpointList = []
+  cache.themeTokens = {}
   windowHeightProvider = null
   schemeLoader = null
   WARNED_MISSING_INSETS = false

package/src/runtime/resolve.ts

@@ -1,4 +1,4 @@
-import { getStyleVersion, lookupCss, type InteractState } from './lookup-css'
+import { breakpointTier, getStyleVersion, lookupCss, type InteractState } from './lookup-css'
 import type { RnwindState } from './components/rnwind-provider'
 import { normalizeClassName } from '../core/normalize-classname'
 import type { GradientAtomInfo, GradientDirection } from '../core/parser/gradient'
@@ -148,17 +148,19 @@ const stateSignatureCache = new WeakMap<RnwindState, string>()
 
 /**
  * Cache key dimension for the reactive context — everything that can
- * change a resolved style. Uses the breakpoint TIER (`activeBreakpoint`),
- * NOT the raw `windowWidth`: two widths in the same tier gate `md:*` atoms
- * identically, so they resolve the same. This collapses the window axis
- * from "every pixel" to ~6 values, bounding the cache on resizable
- * surfaces (web / desktop) without changing any result.
+ * change a resolved style. Uses the numeric breakpoint TIER (count of
+ * thresholds reached) from `breakpointTier(windowWidth)`, NOT the
+ * `activeBreakpoint` NAME: the name clamps tier-0 into the smallest
+ * breakpoint, so widths straddling that threshold (e.g. 320 vs 700 with
+ * `sm=640`) would collide on one cache key and serve a stale style. The
+ * tier is exact AND bounded — two widths in the same tier gate every
+ * `sm:`/`md:`/… atom identically, so they resolve the same.
  * @param state Rnwind context.
  * @returns Compact signature string.
  */
 function stateSignature(state: RnwindState): string {
   const { insets } = state
-  return `${state.scheme}|${insets.top},${insets.right},${insets.bottom},${insets.left}|${state.fontScale}|${state.activeBreakpoint}`
+  return `${state.scheme}|${insets.top},${insets.right},${insets.bottom},${insets.left}|${state.fontScale}|${breakpointTier(state.windowWidth)}`
 }
 
 /**