rnwind 0.0.1 → 0.0.3

package/src/metro/with-config.ts

@@ -0,0 +1,251 @@
+import { existsSync, mkdirSync, utimesSync, watch as watchFile } from 'node:fs'
+import path from 'node:path'
+import { writeDtsFile } from './dts'
+import { createRnwindResolver, type ResolveRequestFn } from './resolver'
+import { configureRnwindState, getRnwindState, onThemeChange } from './state'
+
+/** Default cache directory at the project root. Visible for debugging. */
+const DEFAULT_CACHE_DIR = '.rnwind'
+
+/**
+ * Active CSS watcher — replaced (and the prior one closed) when
+ * `withRnwindConfig` is called again (Metro restart, repeated init).
+ * Only one watcher per process; no stacking.
+ */
+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.
+ * @param cssPath Absolute path to the theme CSS to watch.
+ * @param projectRoot Metro's project root (for `getRnwindState`).
+ */
+function watchThemeCss(cssPath: string, projectRoot: string): void {
+  if (activeCssWatcher?.cssPath === cssPath) return
+  activeCssWatcher?.close()
+  if (!existsSync(cssPath)) return
+  let pending = false
+  const watcher = watchFile(cssPath, { persistent: false }, () => {
+    // Debounce: editors often emit 2-3 change events per save (atomic
+    // rename dance, tmp files). Coalesce to ONE rebuild per microtask.
+    if (pending) return
+    pending = true
+    queueMicrotask(async () => {
+      pending = false
+      try {
+        await onThemeChange(projectRoot)
+        touchRecordedFiles(projectRoot)
+      } catch {
+        // Invalidation is best-effort — never crash the dev server.
+      }
+    })
+  })
+  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
+ * built `lib/` output. Tries a few extensions because `require.resolve`
+ * doesn't auto-find `.cjs` / `.mjs` from a bare specifier.
+ * @returns Absolute path to the rnwind transformer module.
+ */
+function transformerPath(): string {
+  for (const candidate of ['./transformer.cjs', './transformer.mjs', './transformer.js', './transformer.ts', './transformer']) {
+    try {
+      return require.resolve(candidate)
+    } catch {
+      // try the next extension
+    }
+  }
+  throw new Error('rnwind: could not resolve the metro transformer path')
+}
+
+/**
+ * Resolve the effective cache directory, honoring a user override and
+ * falling back to `<projectRoot>/.rnwind`.
+ * @param projectRoot Anchor for relative paths.
+ * @param override User-supplied option.
+ * @returns Absolute cache directory.
+ */
+function resolveCacheDir(projectRoot: string, override: string | undefined): string {
+  if (!override || override.length === 0) return path.resolve(projectRoot, DEFAULT_CACHE_DIR)
+  return path.isAbsolute(override) ? override : path.resolve(projectRoot, override)
+}
+
+/**
+ * Read the theme CSS and extract `@variant <name>` blocks for the .d.ts
+ * generator. Forces construction of `getRnwindState`, then reads
+ * `parser.declaredSchemes` (populated synchronously at construction).
+ * @param cssEntry Absolute path to theme CSS.
+ * @param projectRoot
+ * @returns Scheme names (empty when the theme has no variants; `'base'` is filtered).
+ */
+function discoverSchemes(cssEntry: string, projectRoot: string): readonly string[] {
+  if (!existsSync(cssEntry)) return []
+  try {
+    const { parser } = getRnwindState(projectRoot)
+    return parser.declaredSchemes.filter((name) => name !== 'base')
+  } catch {
+    return []
+  }
+}
+
+/** User-facing options for `withRnwindConfig`. */
+export interface RnwindMetroOptions {
+  /** Path to the theme CSS (absolute or relative to `projectRoot`). Required. */
+  cssEntryFile: string
+  /** Where rnwind writes the `.d.ts` file. Set `false` to disable. Defaults to `<projectRoot>/rnwind-types.d.ts`. */
+  dtsFile?: string | false
+  /** Optional project-root override — defaults to `metroConfig.projectRoot` then `process.cwd()`. */
+  projectRoot?: string
+  /** Cache directory. Absolute, or relative to `projectRoot`. Default: `.rnwind` at project root. */
+  cacheDir?: string
+  /**
+   * Extra JSX prop-name prefixes that rnwind should rewrite. Each
+   * prefix `P` turns `<Tag PClassName="…">` into `<Tag
+   * PStyle={lookupCss(…)}>`. The built-in `'contentContainer'` prefix
+   * is always on (covers ScrollView / FlatList / SectionList); user
+   * entries merge on top.
+   */
+  classNamePrefixes?: readonly string[]
+  /**
+   * Extra module specifiers whose JSX exports rnwind should treat as
+   * "host components" — i.e. tags whose `className="…"` attribute is
+   * rewritten to `style={lookupCss(…)}` at build time (zero runtime
+   * cost). Merged with the built-in defaults: `react-native`,
+   * `react-native-reanimated`, `react-native-svg`,
+   * `react-native-gesture-handler`, `expo-linear-gradient`, `expo-image`.
+   *
+   * Anything NOT marked as a host has its `className` left untouched —
+   * the importing component receives the raw string and decides what
+   * to do with it. Use this option to opt your design-system / UI
+   * primitive packages into the zero-runtime path.
+   */
+  hostSources?: readonly string[]
+  /**
+   * Extra JSX tag names (verbatim — may include `.` for member access
+   * like `'Animated.View'`) rnwind should treat as host components,
+   * regardless of where they're imported from. Useful for one-off
+   * escape-hatches: `import { View as MyBox } from 'react-native'`
+   * doesn't change the local name → `'MyBox'` here picks it up.
+   */
+  hostComponents?: readonly string[]
+}
+
+/** Shape we mutate on Metro's config. Loose so we don't pin Metro's internal types. */
+export interface MetroConfigLike {
+  projectRoot?: string
+  watchFolders?: string[]
+  transformer?: {
+    babelTransformerPath?: string
+    [key: string]: unknown
+  }
+  resolver?: {
+    resolveRequest?: ResolveRequestFn | null
+    [key: string]: unknown
+  }
+  [key: string]: unknown
+}
+
+/**
+ * Wrap a Metro config with rnwind's pipeline:
+ *  - Install the rnwind babel transformer.
+ *  - Chain a `resolveRequest` hook that serves
+ *    `rnwind/__generated/schemes` from `<cacheDir>/schemes.js`.
+ *  - Write the `.d.ts` so TypeScript accepts `className=` on RN components.
+ *  - Publish the theme CSS path + cache dir via env so Metro workers
+ *    can rebuild their local state.
+ *  - Ensure the cache dir is a watched folder Metro's haste-map indexes.
+ *
+ * Theme-edit hot reload happens implicitly: every transformed file
+ * imports `rnwind/__generated/schemes`, and that module eager-imports
+ * `common.style.js`. When the theme changes, the per-scheme files
+ * regenerate with new bytes; Metro's content SHA1 dedup detects the
+ * change and invalidates every importer automatically.
+ * `getCacheKey()` on the transformer covers the per-file transform
+ * cache. No file watcher / source-padding hack needed — the dep graph
+ * carries the signal.
+ * @param metroConfig Config from `getDefaultConfig(__dirname)` or equivalent.
+ * @param options rnwind options.
+ * @returns The same config, mutated.
+ */
+export function withRnwindConfig<C extends MetroConfigLike>(metroConfig: C, options: RnwindMetroOptions): C {
+  const projectRoot = options.projectRoot ?? metroConfig.projectRoot ?? process.cwd()
+  const cacheDir = resolveCacheDir(projectRoot, options.cacheDir)
+  const cssEntry = path.isAbsolute(options.cssEntryFile) ? options.cssEntryFile : path.resolve(projectRoot, options.cssEntryFile)
+
+  mkdirSync(cacheDir, { recursive: true })
+  const watchFolders = (metroConfig.watchFolders ?? []).filter((p) => typeof p === 'string' && p.length > 0)
+  configureRnwindState(cssEntry, cacheDir, watchFolders, options.classNamePrefixes, options.hostSources, options.hostComponents)
+
+  // Warm the state eagerly (in the Metro master process) so oxide's
+  // Scanner walks every project source (and every monorepo
+  // watch-folder) ONCE and the manifest + scheme files hold the
+  // complete union before Metro's resolver tries to SHA1 them on the
+  // first transform. Each worker lazy-repeats this scan on its first
+  // transform to converge on identical state.
+  try {
+    void getRnwindState(projectRoot).builder.ensureFilesExist()
+  } catch {
+    // Any init error surfaces again at the first transform; don't crash Metro boot.
+  }
+
+  // Install transformer + resolver. Capture the existing
+  // babelTransformerPath BEFORE we override it — our worker chains to
+  // it (env-passed) so Flow / expo-router / babel-preset-expo etc. all
+  // continue to run.
+  const existingTransformerPath = metroConfig.transformer?.babelTransformerPath
+  if (typeof existingTransformerPath === 'string' && existingTransformerPath.length > 0) {
+    process.env.RNWIND_UPSTREAM_TRANSFORMER = existingTransformerPath
+  }
+  const upstream = metroConfig.resolver?.resolveRequest ?? null
+  metroConfig.transformer = { ...metroConfig.transformer, babelTransformerPath: transformerPath() }
+  metroConfig.resolver = { ...metroConfig.resolver, resolveRequest: createRnwindResolver(upstream) }
+
+  // Metro's haste-map indexes `watchFolders` at startup. Adding the
+  // cache dir guarantees scheme style files + manifest get SHA1'd
+  // without a "Failed to get the SHA-1" race when the first transform
+  // writes them.
+  const existingWatch = metroConfig.watchFolders ?? []
+  metroConfig.watchFolders = existingWatch.includes(cacheDir) ? existingWatch : [...existingWatch, cacheDir]
+
+  if (options.dtsFile !== false) {
+    const dtsPath = options.dtsFile ?? path.resolve(projectRoot, 'rnwind-types.d.ts')
+    const schemes = discoverSchemes(cssEntry, projectRoot)
+    writeDtsFile(dtsPath, schemes, options.classNamePrefixes)
+  }
+
+  // Watch the theme CSS. On edit, we rewrite scheme files AND touch
+  // mtime on every transformed source file so Metro invalidates them
+  // and re-transforms — the only reliable way to propagate theme
+  // changes to an already-running dev server.
+  watchThemeCss(cssEntry, projectRoot)
+
+  return metroConfig
+}

package/src/runtime/chain-handlers.ts

@@ -0,0 +1,47 @@
+/**
+ * Tiny helpers that compose rnwind's press / focus handlers with any
+ * user-provided ones the JSX site already has. The transformer uses
+ * these when it rewrites a `<Pressable onPressIn={user}>` into
+ * `<Pressable onPressIn={chainPress(user, _i.onPressIn)}>` so the user's
+ * callback keeps firing.
+ *
+ * Both helpers bail out when the user's handler is `null` / `undefined`,
+ * returning rnwind's handler directly — that gives the transformer a
+ * cheap uniform rewrite ("always chain") without allocating a new
+ * function per render when the user didn't opt in to the handler.
+ */
+import type { GestureResponderEvent, NativeSyntheticEvent, TargetedEvent } from 'react-native'
+
+type PressHandler = (event: GestureResponderEvent) => void
+type FocusHandler = (event: NativeSyntheticEvent<TargetedEvent>) => void
+
+/**
+ * Compose a user-supplied press handler with rnwind's internal one.
+ * User fires first (its return / side-effects happen pre-gate flip); the
+ * rnwind handler then updates the active flag.
+ * @param user User-supplied handler from the original JSX (optional).
+ * @param ours rnwind's internal active-toggling handler.
+ * @returns Combined handler, or `ours` directly when the user didn't provide one.
+ */
+export function chainPress(user: PressHandler | null | undefined, ours: PressHandler): PressHandler {
+  if (user == null) return ours
+  return (event: GestureResponderEvent): void => {
+    user(event)
+    ours(event)
+  }
+}
+
+/**
+ * Compose a user-supplied focus/blur handler with rnwind's internal one.
+ * Same ordering rule as {@link chainPress}: user first, rnwind second.
+ * @param user User-supplied handler (optional).
+ * @param ours rnwind's internal focus-toggling handler.
+ * @returns Combined handler, or `ours` directly when the user didn't provide one.
+ */
+export function chainFocus(user: FocusHandler | null | undefined, ours: FocusHandler): FocusHandler {
+  if (user == null) return ours
+  return (event: NativeSyntheticEvent<TargetedEvent>): void => {
+    user(event)
+    ours(event)
+  }
+}

package/src/runtime/components/rnwind-provider.tsx

@@ -0,0 +1,144 @@
+import { createContext, useContext, useMemo, type ReactNode } from 'react'
+import { useWindowDimensions } from 'react-native'
+import type { ThemeTables } from '../../core/types'
+import type { Scheme } from '../types'
+import type { OnHaptics } from '../../core/parser/haptics'
+import { activeBreakpointFor, BASE_BREAKPOINT, loadScheme } from '../lookup-css'
+
+/**
+ * Per-render safe-area insets snapshot. Bridge from any source
+ * (`useSafeAreaInsets()`, expo-router insets, a manually computed
+ * value) into the {@link RnwindProvider} — rnwind stays
+ * library-agnostic.
+ */
+export type Insets = Readonly<{
+  top: number
+  right: number
+  bottom: number
+  left: number
+}>
+
+/**
+ * Single value carried by the rnwind context. Every piece of runtime
+ * state rnwind needs — scheme, theme tables, insets, font scale,
+ * window width, active responsive breakpoint, optional haptic
+ * dispatcher — lives on this one bag. Consumers read it via
+ * {@link useRnwind} and either destructure or forward straight to
+ * `lookupCss` / `useCss`.
+ *
+ * `activeBreakpoint` is the highest-threshold registered breakpoint
+ * whose min-width is `<= windowWidth`, or `'base'` when below the
+ * smallest one (mobile-first tier) or when no breakpoints are
+ * registered yet (tests, bundles without rnwind-transformed sources).
+ * Always a string — never null. Reactive: it updates with
+ * `useWindowDimensions().width`, so consumers can branch on it
+ * without a separate hook.
+ */
+export type RnwindState = Readonly<{
+  scheme: Scheme
+  tables: ThemeTables
+  insets: Insets
+  onHaptics: OnHaptics | undefined
+  fontScale: number
+  windowWidth: number
+  activeBreakpoint: string
+}>
+
+/** Props accepted by {@link RnwindProvider}. */
+export type RnwindProviderProps = Readonly<{
+  scheme: Scheme
+  tables?: ThemeTables
+  insets?: Partial<Insets>
+  onHaptics?: OnHaptics
+  children?: ReactNode
+}>
+
+const EMPTY_TABLES: ThemeTables = {}
+const ZERO_INSETS: Insets = { top: 0, right: 0, bottom: 0, left: 0 }
+const DEFAULT_STATE: RnwindState = {
+  scheme: 'light' as Scheme,
+  tables: EMPTY_TABLES,
+  insets: ZERO_INSETS,
+  onHaptics: undefined,
+  fontScale: 1,
+  windowWidth: 0,
+  activeBreakpoint: BASE_BREAKPOINT,
+}
+
+/**
+ * Normalise a `Partial<Insets>` into a complete {@link Insets}, returning
+ * the shared {@link ZERO_INSETS} reference when nothing is supplied so
+ * downstream memoisation stays stable.
+ * @param partial Caller-supplied insets (or undefined).
+ * @returns Complete insets record.
+ */
+function normaliseInsets(partial: Partial<Insets> | undefined): Insets {
+  if (!partial) return ZERO_INSETS
+  const top = partial.top ?? 0
+  const right = partial.right ?? 0
+  const bottom = partial.bottom ?? 0
+  const left = partial.left ?? 0
+  if (top === 0 && right === 0 && bottom === 0 && left === 0) return ZERO_INSETS
+  return { top, right, bottom, left }
+}
+
+/** Single internal context the runtime reads from. */
+const RnwindContext = createContext<RnwindState>(DEFAULT_STATE)
+
+/**
+ * Read rnwind's full runtime state — scheme, theme tables, insets,
+ * fontScale, windowWidth, onHaptics — in one go. Pass the returned
+ * value straight to `lookupCss` / `useCss`, or destructure what you
+ * need.
+ * @returns Active rnwind state under the nearest {@link RnwindProvider}.
+ */
+export function useRnwind(): RnwindState {
+  return useContext(RnwindContext)
+}
+
+/**
+ * Internal context hook the babel transformer injects at the top of
+ * every rewritten component as `const _t = useR_()`. Same body as the
+ * public {@link useRnwind} — exposed under a `use*`-prefixed name so
+ * react-refresh's babel plugin (which only tracks call-sites whose
+ * identifier matches `^use[A-Z]`) folds it into each component's
+ * fast-refresh signature. Without that prefix the signature stayed
+ * stable across transformer changes; HMR then preserved fiber state
+ * while the rendered hook list shifted, surfacing as "change in the
+ * order of Hooks" runtime errors. Trailing underscore keeps it
+ * visually distinct from the user-facing `useRnwind`.
+ * @returns Active rnwind state.
+ */
+export function useR_(): RnwindState {
+  return useContext(RnwindContext)
+}
+
+/**
+ * Provider for rnwind's full runtime state. fontScale + windowWidth
+ * come from `useWindowDimensions()` so they react to OS-level
+ * orientation / accessibility-text-size changes automatically.
+ * @param props Provider props.
+ * @param props.scheme Active scheme name.
+ * @param props.tables Optional pre-resolved token tables.
+ * @param props.insets Optional safe-area insets.
+ * @param props.onHaptics Optional haptic dispatcher.
+ * @param props.children React subtree.
+ * @returns Provider element.
+ */
+export function RnwindProvider({ scheme, tables, insets, onHaptics, children }: RnwindProviderProps): ReactNode {
+  const normalized = normaliseInsets(insets)
+  const { fontScale, width } = useWindowDimensions()
+  const value = useMemo<RnwindState>(() => {
+    loadScheme(scheme)
+    return {
+      scheme,
+      tables: tables ?? EMPTY_TABLES,
+      insets: normalized,
+      onHaptics,
+      fontScale,
+      windowWidth: width,
+      activeBreakpoint: activeBreakpointFor(width),
+    }
+  }, [scheme, tables, normalized, onHaptics, fontScale, width])
+  return <RnwindContext.Provider value={value}>{children}</RnwindContext.Provider>
+}

package/src/runtime/gradient-types.ts

@@ -0,0 +1,60 @@
+/**
+ * Typed contract for the component rnwind's transformer calls with a
+ * gradient-class `className`. Matches `expo-linear-gradient` verbatim
+ * so users can plug any gradient library that mirrors that API.
+ *
+ * A typical wiring:
+ *
+ * ```tsx
+ * import { LinearGradient } from 'expo-linear-gradient'
+ * import type { AsLinearGradientProps } from 'rnwind'
+ *
+ * // Assert at the type level — CI catches mismatches before runtime.
+ * const _typeCheck: AsLinearGradientProps = {} as Parameters<typeof LinearGradient>[0]
+ *
+ * // Then use it in real JSX. rnwind fills in colors / start / end.
+ * <LinearGradient className="bg-gradient-to-r from-red-500 to-blue-500" />
+ * ```
+ *
+ * The rnwind transformer emits `colors` as a frozen `readonly string[]`,
+ * and `start` / `end` as frozen `{x: number, y: number}` records.
+ * Users pass the component; rnwind fills the props. Unused props
+ * (`locations`, `dither`, …) are forwarded verbatim from the JSX site.
+ */
+
+/** A unit-square point. Matches the `LinearGradientPoint` object form. */
+export interface LinearGradientPoint {
+  /** Horizontal component, 0..1. */
+  readonly x: number
+  /** Vertical component, 0..1. */
+  readonly y: number
+}
+
+/**
+ * The exact prop shape rnwind fills onto a gradient component at
+ * build time. A user-supplied `<LinearGradient>` (or any other
+ * component) must accept these props — no wrapper, no adapter.
+ */
+export interface AsLinearGradientProps {
+  /**
+   * Gradient colour stops in source order. rnwind emits a frozen
+   * `readonly string[]` with 2+ entries (at least `from` + `to`).
+   * Compatible with expo-linear-gradient's `colors: readonly [ColorValue, ColorValue, ...ColorValue[]]`.
+   */
+  readonly colors: readonly string[]
+  /**
+   * Start point, in the unit square (0,0)=top-left → (1,1)=bottom-right.
+   * rnwind emits a frozen `{x, y}` record matching the Tailwind
+   * direction utility (`to-r` → `{x: 0, y: 0.5}`).
+   */
+  readonly start: LinearGradientPoint
+  /** End point — same unit-square coordinates as `start`. */
+  readonly end: LinearGradientPoint
+  /**
+   * Optional colour-stop positions matching `colors` length. rnwind
+   * doesn't emit this today (Tailwind v4's stop-position atoms aren't
+   * wired yet); listed here so the prop surface still matches
+   * expo-linear-gradient when a consumer passes their own.
+   */
+  readonly locations?: readonly number[] | null
+}

package/src/runtime/haptics.ts

@@ -0,0 +1,120 @@
+/**
+ * Runtime helpers the transformer injects for haptic utilities.
+ *
+ * Two entry points:
+ *
+ *   useMountHaptic(requests) — fires each request on mount via
+ *     `useEffect(() => { ... }, [])`. Used by the transformer for bare
+ *     `haptic-*` atoms (no variant prefix).
+ *
+ *   triggerHaptic(onHaptics, request, trigger) — thin forwarding
+ *     helper for event-driven variants (`active:haptic-*`, `focus:...`,
+ *     `hover:...`). The transformer emits an inline arrow that calls
+ *     this from `onPressIn` / `onFocus` / etc.
+ *
+ * Both emit a one-shot dev-mode warning when `onHaptics` is missing —
+ * so developers get a clear "you forgot to wire <SchemeProvider
+ * onHaptics=...>" signal instead of silently dropping the haptic.
+ */
+
+import { useEffect } from 'react'
+import type { HapticRequest, HapticTrigger, OnHaptics } from '../core/parser/haptics'
+import { useRnwind } from './components/rnwind-provider'
+
+/**
+ * Module-scope set tracking haptic trigger strings we've already
+ * warned about. Prevents the "missing onHaptics" warning from
+ * spamming the console when the same class appears on many elements.
+ */
+const WARNED_MISSING_HAPTICS = new Set<string>()
+
+/**
+ * Render a `HapticRequest` as a short descriptive tag for log lines.
+ * @param request Haptic request.
+ * @returns `impact/Light`, `notification/Success`, or `selection`.
+ */
+function hapticTag(request: HapticRequest): string {
+  if (request.kind === 'impact') return `impact/${request.style}`
+  if (request.kind === 'notification') return `notification/${request.type}`
+  return 'selection'
+}
+
+/**
+ * Warn once per haptic trigger kind when a `haptic-*` atom tries to
+ * dispatch without an `onHaptics` provider. Dev-mode only — `__DEV__`
+ * is a Metro / Expo / RN global that compiles to `false` in release
+ * bundles, so no warn code ships to production.
+ * @param request The haptic request that had no provider.
+ * @param trigger The lifecycle trigger that tried to fire.
+ */
+function warnMissingOnHaptics(request: HapticRequest, trigger: HapticTrigger): void {
+  // `__DEV__` is a RN / Metro global — `false` in release, strips the
+  // branch entirely. Guarded in case we're evaluated outside of Metro
+  // (tests, node scripts) where the global isn't defined.
+  const isDevelopment = typeof __DEV__ === 'undefined' || __DEV__
+  if (!isDevelopment) return
+  const tag = hapticTag(request)
+  const key = `${tag}@${trigger}`
+  if (WARNED_MISSING_HAPTICS.has(key)) return
+  WARNED_MISSING_HAPTICS.add(key)
+  // eslint-disable-next-line no-console
+  console.warn(
+    `rnwind: a haptic utility fired (${tag}, trigger=${trigger}) but no onHaptics callback is wired on <SchemeProvider>. ` +
+      `Pass \`onHaptics\` on the provider to forward this to expo-haptics (or any library of your choice).`,
+  )
+}
+
+/**
+ * Test-only hook — clears the warned-haptics set so successive test
+ * runs don't silently swallow their own warnings.
+ */
+function __resetHapticWarnings(): void {
+  WARNED_MISSING_HAPTICS.clear()
+}
+
+/**
+ * Invoke every request in `requests` on mount (once per component
+ * mount), using the `onHaptics` dispatcher from the nearest
+ * `<SchemeProvider>`. Missing-provider dev warnings fire via
+ * {@link warnMissingOnHaptics}.
+ *
+ * Uses `useEffect(..., [])` — the requests array is identity-stable
+ * (hoisted at module scope by the transformer), so re-firing on
+ * re-renders isn't a concern.
+ * @param requests Hoisted request list for this component.
+ */
+function useMountHaptic(requests: readonly HapticRequest[]): void {
+  const { onHaptics } = useRnwind()
+   
+  useEffect(() => {
+    for (const request of requests) {
+      if (onHaptics) onHaptics(request, 'mount')
+      else warnMissingOnHaptics(request, 'mount')
+    }
+    // requests is a hoisted stable reference — depending on onHaptics
+    // identity keeps the effect fresh if the provider remounts with a
+    // different dispatcher, while the hoisted const prevents a remount
+    // from an inline `onHaptics={(r) => ...}`.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [onHaptics])
+}
+
+/**
+ * Fire one haptic request through the provider dispatcher. Emits the
+ * missing-provider dev warning when no dispatcher is wired. Designed
+ * for the inline arrows the transformer synthesises:
+ *
+ *   onPressIn={(e) => { triggerHaptic(_h, _HR_xxx, 'pressIn'); user?.(e) }}
+ * @param onHaptics Provider dispatcher (may be undefined).
+ * @param request Pre-hoisted request object.
+ * @param trigger Lifecycle trigger.
+ */
+function triggerHaptic(onHaptics: OnHaptics | undefined, request: HapticRequest, trigger: HapticTrigger): void {
+  if (onHaptics) {
+    onHaptics(request, trigger)
+    return
+  }
+  warnMissingOnHaptics(request, trigger)
+}
+
+export { useMountHaptic, triggerHaptic, __resetHapticWarnings }

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

@@ -0,0 +1,16 @@
+import { useRnwind } from '../components/rnwind-provider'
+import { lookupCss } from '../lookup-css'
+
+/**
+ * Convenience hook: `useRnwind()` + `lookupCss()` rolled into one. Use
+ * inside any component that wants the resolved style array without
+ * threading the rnwind context manually. JSX-heavy components should
+ * still call `useRnwind()` once and pass it to `lookupCss(...)` per
+ * element so React only does a single context read per render.
+ * @param className Raw className string or transformer-hoisted atom-name array.
+ * @param userStyle Optional caller-supplied style appended last.
+ * @returns Frozen style array for React Native's `style` prop.
+ */
+export function useCss(className?: string | readonly string[] | null, userStyle?: unknown): readonly unknown[] {
+  return lookupCss(className, useRnwind(), userStyle)
+}