rnwind 0.0.4 → 0.0.5

package/src/runtime/resolve.ts

@@ -0,0 +1,381 @@
+import { 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'
+import type { HapticRequest, HapticTrigger } from '../core/parser/haptics'
+
+/**
+ * Rich className resolver — the runtime heart of the wrap / `useCss`.
+ *
+ * Resolution order, per className string:
+ *  1. **Molecule** — a build-time PRE-MERGED single style object for the
+ *     whole literal className (per scheme). One map lookup returns it by
+ *     reference: no array, no merge, no per-atom loop. The common case.
+ *  2. **Atom fallback** — for a className the scanner never saw (a
+ *     runtime-built string like `` `${className} px-2` ``) OR one that
+ *     carries context-dependent atoms (`pt-safe`, `text-base`, `md:*`),
+ *     fall back to per-atom resolution via `lookupCss`, which folds in
+ *     insets / fontScale / breakpoint / scheme.
+ *
+ * Results are cached by `(normalized className, scheme, insets, fontScale,
+ * breakpoint)` so repeated renders return the SAME reference until the
+ * reactive context changes. Atoms / molecules / features all live in
+ * build-time registries the generated `.rnwind/*.js` modules populate.
+ */
+
+/** Always-loaded fallback scheme key. */
+const COMMON_SCHEME = 'common'
+
+/** Empty style sentinel. */
+const EMPTY: readonly unknown[] = []
+
+/** scheme → normalized className → pre-merged style object. */
+let molecules: Record<string, Record<string, unknown>> = Object.create(null)
+/** atom name → gradient role + resolved colour. */
+let gradients: Record<string, GradientAtomInfo> = Object.create(null)
+/** atom name (incl. `active:`/`focus:` prefix) → haptic request. */
+let haptics: Record<string, HapticRequest> = Object.create(null)
+/** Bumps on any molecule/gradient/haptic registration. */
+let registryVersion = 0
+
+/** Per-(className·state) resolved cache — strong references between context changes. */
+const resolvedCache = new Map<string, ResolvedCss>()
+/** Version the cache was last valid for (`getStyleVersion()` + {@link registryVersion}). */
+let cachedFor = -1
+
+/** A unit-square gradient endpoint. */
+interface GradientPoint {
+  readonly x: number
+  readonly y: number
+}
+
+/** Rich resolution: the RN `style` plus any className-derived props. */
+export interface ResolvedCss {
+  /** RN `style` value — a single molecule object (by ref) or an atom array. */
+  readonly style: unknown
+  /** Gradient stop colours (when the className is a complete gradient). */
+  readonly colors?: readonly string[]
+  /** Gradient start point. */
+  readonly start?: GradientPoint
+  /** Gradient end point. */
+  readonly end?: GradientPoint
+  /** Text truncation line count. */
+  readonly numberOfLines?: number
+  /** Text ellipsize mode. */
+  readonly ellipsizeMode?: 'tail' | 'clip'
+  /** Haptic requests present on the className, for the wrap to dispatch. */
+  readonly haptics?: readonly { readonly request: HapticRequest; readonly trigger: HapticTrigger }[]
+}
+
+/** `GradientDirection` → expo-linear-gradient start/end points. */
+const DIRECTION_POINTS: Record<GradientDirection, { start: GradientPoint; end: GradientPoint }> = {
+  'to-t': { start: { x: 0.5, y: 1 }, end: { x: 0.5, y: 0 } },
+  'to-b': { start: { x: 0.5, y: 0 }, end: { x: 0.5, y: 1 } },
+  'to-l': { start: { x: 1, y: 0.5 }, end: { x: 0, y: 0.5 } },
+  'to-r': { start: { x: 0, y: 0.5 }, end: { x: 1, y: 0.5 } },
+  'to-tl': { start: { x: 1, y: 1 }, end: { x: 0, y: 0 } },
+  'to-tr': { start: { x: 0, y: 1 }, end: { x: 1, y: 0 } },
+  'to-bl': { start: { x: 1, y: 0 }, end: { x: 0, y: 1 } },
+  'to-br': { start: { x: 0, y: 0 }, end: { x: 1, y: 1 } },
+  unknown: { start: { x: 0, y: 0.5 }, end: { x: 1, y: 0.5 } },
+}
+
+/**
+ * Register one scheme's pre-merged molecules (atom-merged literal
+ * classNames). Merges onto any existing entries for the scheme.
+ * @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 }
+  registryVersion += 1
+}
+
+/**
+ * Register the gradient atom map (atom name → role + resolved colour).
+ * @param map Atom name → gradient info.
+ */
+export function registerGradients(map: Record<string, GradientAtomInfo>): void {
+  gradients = map
+  registryVersion += 1
+}
+
+/**
+ * Register the haptic atom map (atom name → request).
+ * @param map Atom name → haptic request.
+ */
+export function registerHaptics(map: Record<string, HapticRequest>): void {
+  haptics = map
+  registryVersion += 1
+}
+
+
+
+/**
+ * Per-state-object signature memo. `RnwindState` is created fresh (via the
+ * provider's `useMemo`) whenever any field changes, so its identity is a
+ * sound key — a new object means a new signature. Keyed weakly so states
+ * GC with their provider.
+ */
+const stateSignatureCache = new WeakMap<RnwindState, string>()
+
+/**
+ * Cache key dimension for the reactive context — everything that can
+ * change a resolved style.
+ * @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.windowWidth}`
+}
+
+/**
+ * Memoised {@link stateSignature} — one `WeakMap.get` on the hot path
+ * instead of rebuilding the template string every resolve.
+ * @param state Rnwind context.
+ * @returns Cached compact signature.
+ */
+function stateSignatureCached(state: RnwindState): string {
+  let signature = stateSignatureCache.get(state)
+  if (signature === undefined) {
+    signature = stateSignature(state)
+    stateSignatureCache.set(state, signature)
+  }
+  return signature
+}
+
+/**
+ * Compact signature of the live interactive state for the cache key.
+ * @param interactState Active/focus flags, or undefined for the plain path.
+ * @returns Two-bit signature (`''` when no interactive state).
+ */
+function interactSignature(interactState?: InteractState): string {
+  if (!interactState) return ''
+  const active = interactState.active ? 1 : 0
+  const focus = interactState.focus ? 1 : 0
+  return `${active}${focus}`
+}
+
+/**
+ * Whether a token is a feature-ONLY utility (gradient stop/direction,
+ * haptic request, or text-truncate) that contributes NO RN `style`. These
+ * are folded in via {@link attachFeatures}, so they must be kept OUT of
+ * the `lookupCss` input — otherwise the atom resolver treats them as
+ * unknown style atoms and emits a spurious "unknown class" dev warning
+ * (e.g. for `active:haptic-rigid`).
+ * @param token Atom name.
+ * @returns True when the token carries no style.
+ */
+function isFeatureOnlyToken(token: string): boolean {
+  return Boolean(gradients[token]) || Boolean(haptics[token]) || truncateForToken(token) !== null
+}
+
+/**
+ * Lifecycle trigger for a haptic atom from its variant prefix.
+ * @param token Atom name (maybe `active:`/`focus:`/`hover:` prefixed).
+ * @returns The trigger.
+ */
+function hapticTriggerForToken(token: string): HapticTrigger {
+  const colon = token.indexOf(':')
+  if (colon === -1) return 'mount'
+  const prefix = token.slice(0, colon)
+  if (prefix === 'active') return 'pressIn'
+  if (prefix === 'focus') return 'focus'
+  if (prefix === 'hover') return 'hover'
+  return 'mount'
+}
+
+/**
+ * Syntactic text-truncate directive for one atom.
+ * @param token Atom name.
+ * @returns Partial truncate props, or null.
+ */
+function truncateForToken(token: string): { numberOfLines?: number; ellipsizeMode?: 'tail' | 'clip' } | null {
+  if (token === 'truncate') return { numberOfLines: 1, ellipsizeMode: 'tail' }
+  if (token === 'text-ellipsis') return { ellipsizeMode: 'tail' }
+  if (token === 'text-clip') return { ellipsizeMode: 'clip' }
+  if (token === 'line-clamp-none') return { numberOfLines: 0 }
+  if (token.startsWith('line-clamp-')) {
+    const count = Number(token.slice('line-clamp-'.length))
+    if (Number.isInteger(count) && count >= 0) return { numberOfLines: count }
+  }
+  return null
+}
+
+/**
+ * Assemble gradient props from gradient roles present in the atom list.
+ * @param tokens Atom names.
+ * @returns `{colors, start, end}` or null when not a complete gradient.
+ */
+function assembleGradient(tokens: readonly string[]): { colors: string[]; start: GradientPoint; end: GradientPoint } | null {
+  let from: string | undefined
+  let via: string | undefined
+  let to: string | undefined
+  let dir: GradientDirection | undefined
+  for (const token of tokens) {
+    const info = gradients[token]
+    if (!info) continue
+    switch (info.role) {
+      case 'from': {
+        from = info.color
+        break
+      }
+      case 'via': {
+        via = info.color
+        break
+      }
+      case 'to': {
+        to = info.color
+        break
+      }
+      default: {
+        ;({ dir } = info)
+      }
+    }
+  }
+  if (dir === undefined) return null
+  const colors = [from, via, to].filter((color): color is string => color !== undefined)
+  if (colors.length < 2) return null
+  const points = DIRECTION_POINTS[dir]
+  return { colors, start: points.start, end: points.end }
+}
+
+/**
+ * Fold every truncate directive across the atom list into one result —
+ * last token wins per prop (matches Tailwind last-wins).
+ * @param tokens Atom names.
+ * @returns Merged truncate props (empty when none apply).
+ */
+function collectTruncate(tokens: readonly string[]): { numberOfLines?: number; ellipsizeMode?: 'tail' | 'clip' } {
+  const out: { numberOfLines?: number; ellipsizeMode?: 'tail' | 'clip' } = {}
+  for (const token of tokens) {
+    const truncate = truncateForToken(token)
+    if (!truncate) continue
+    if (truncate.numberOfLines !== undefined) out.numberOfLines = truncate.numberOfLines
+    if (truncate.ellipsizeMode !== undefined) out.ellipsizeMode = truncate.ellipsizeMode
+  }
+  return out
+}
+
+/**
+ * Collect every haptic request present in the atom list, tagged with the
+ * lifecycle trigger its variant prefix implies.
+ * @param tokens Atom names.
+ * @returns Haptic request list, or undefined when none apply.
+ */
+function collectHaptics(tokens: readonly string[]): { request: HapticRequest; trigger: HapticTrigger }[] | undefined {
+  let collected: { request: HapticRequest; trigger: HapticTrigger }[] | undefined
+  for (const token of tokens) {
+    const request = haptics[token]
+    if (!request) continue
+    collected ??= []
+    collected.push({ request, trigger: hapticTriggerForToken(token) })
+  }
+  return collected
+}
+
+/**
+ * Scan tokens for the className-derived feature props (gradient,
+ * truncate, haptics) and fold them onto the base result.
+ * @param base Result carrying the resolved `style`.
+ * @param tokens Atom names.
+ * @returns The result with any feature props attached.
+ */
+function attachFeatures(base: ResolvedCss, tokens: readonly string[]): ResolvedCss {
+  const { numberOfLines, ellipsizeMode } = collectTruncate(tokens)
+  const collected = collectHaptics(tokens)
+  const gradient = assembleGradient(tokens)
+  const result: Mutable<ResolvedCss> = { style: base.style }
+  if (gradient) {
+    result.colors = gradient.colors
+    result.start = gradient.start
+    result.end = gradient.end
+  }
+  // `numberOfLines: 0` is kept (RN reads it as "unlimited"): `line-clamp-none`
+  // must be able to explicitly reset an earlier `line-clamp-N` on the same
+  // element — dropping the 0 would silently leave the prior limit in place.
+  if (numberOfLines !== undefined) {
+    result.numberOfLines = numberOfLines
+    if (ellipsizeMode !== undefined) result.ellipsizeMode = ellipsizeMode
+  }
+  if (collected) result.haptics = collected
+  return result
+}
+
+/**
+ * Compose a resolved style with a caller-supplied inline style (user wins).
+ * @param style
+ * @param userStyle
+ */
+function withUserStyle(style: unknown, userStyle: unknown): unknown {
+  return Array.isArray(style) ? [...style, userStyle] : [style, userStyle]
+}
+
+/**
+ * Resolve a className against the reactive context into a style plus any
+ * className-derived props. Molecule-first (one lookup, by reference),
+ * atom-fallback for unseen / context-dependent strings, cached per
+ * `(className, state)`.
+ * @param className Raw className string.
+ * @param state Rnwind context from `useRnwind()`.
+ * @param userStyle Optional inline style appended last (wins).
+ * @param interactState Live active/focus flags (for `active:`/`focus:` atoms).
+ * @returns The resolved style + feature props.
+ */
+export function resolve(
+  className: string | null | undefined,
+  state: RnwindState,
+  userStyle?: unknown,
+  interactState?: InteractState,
+): ResolvedCss {
+  const version = getStyleVersion() + registryVersion
+  if (version !== cachedFor) {
+    resolvedCache.clear()
+    cachedFor = version
+  }
+  if (className == null) {
+    return { style: userStyle === undefined || userStyle === null ? EMPTY : [userStyle] }
+  }
+  // Key on the RAW className so the hot (cache-hit) path skips normalize
+  // entirely — normalization only runs on a miss. The state signature is
+  // memoised per state object, so the hit path is one WeakMap.get + one
+  // string concat + one Map.get.
+  const key = `${className}@${stateSignatureCached(state)}@${interactSignature(interactState)}`
+  const cached = resolvedCache.get(key)
+  if (cached !== undefined) {
+    return userStyle === undefined || userStyle === null ? cached : { ...cached, style: withUserStyle(cached.style, userStyle) }
+  }
+  const normalized = normalizeClassName(className)
+  if (normalized.length === 0) {
+    const empty: ResolvedCss = { style: EMPTY }
+    resolvedCache.set(key, empty)
+    return userStyle === undefined || userStyle === null ? empty : { style: [userStyle] }
+  }
+  // Molecules are static pre-merges; anything carrying `active:`/`focus:`
+  // is never registered as one, so the atom path handles interactive state.
+  const tokens = normalized.split(' ')
+  const molecule = interactState ? undefined : molecules[state.scheme]?.[normalized] ?? molecules[COMMON_SCHEME]?.[normalized]
+  // Feature-only tokens (gradient / haptic / truncate) carry no style — keep
+  // them out of the atom lookup so they don't warn as "unknown class".
+  const style =
+    molecule === undefined ? lookupCss(tokens.filter((token) => !isFeatureOnlyToken(token)).join(' '), state, undefined, interactState) : molecule
+  const base = attachFeatures({ style }, tokens)
+  resolvedCache.set(key, base)
+  return userStyle === undefined || userStyle === null ? base : { ...base, style: withUserStyle(base.style, userStyle) }
+}
+
+/** Local mutable view for building the frozen-shaped result. */
+type Mutable<T> = { -readonly [K in keyof T]: T[K] }
+
+/** Test-only — clear the molecule / gradient / haptic registries + cache. */
+export function __resetResolveState(): void {
+  molecules = Object.create(null)
+  gradients = Object.create(null)
+  haptics = Object.create(null)
+  resolvedCache.clear()
+  registryVersion += 1
+  cachedFor = -1
+}
+
+export {normalizeClassName} from '../core/normalize-classname'

package/src/runtime/wrap.tsx

@@ -0,0 +1,267 @@
+import { createElement, useEffect, useRef, type ComponentType, type ReactElement } from 'react'
+import { chainFocus, chainPress } from './chain-handlers'
+import { useInteract } from './hooks/use-interact'
+import { useRnwind } from './components/rnwind-provider'
+import type { RnwindState } from './components/rnwind-provider'
+import { resolve, type ResolvedCss } from './resolve'
+import type { OnHaptics } from '../core/parser/haptics'
+
+/** Matches a leading `active:` / `focus:` variant token (`\b` excludes `inactive:`). */
+const INTERACTIVE_VARIANT = /\b(?:active|focus):/
+
+/** One-shot guard so the missing-`onHaptics` warning logs once per session. */
+let warnedMissingOnHaptics = false
+
+/**
+ * Dev-only warning when a className carries a haptic utility but no
+ * `onHaptics` dispatcher is wired on the nearest `<RnwindProvider>` — the
+ * haptic would silently drop otherwise. Fires once per session.
+ * @param onHaptics The dispatcher from context (or undefined).
+ * @param haptics The resolved haptic requests (or undefined).
+ */
+function warnIfHapticsUnwired(onHaptics: OnHaptics | undefined, haptics: ResolvedCss['haptics']): void {
+  if (onHaptics || !haptics || haptics.length === 0) return
+  const isDevelopment = typeof __DEV__ === 'undefined' || __DEV__
+  if (!isDevelopment || warnedMissingOnHaptics) return
+  warnedMissingOnHaptics = true
+  // eslint-disable-next-line no-console
+  console.warn(
+    'rnwind: a `haptic-*` utility resolved but no `onHaptics` callback is wired on <RnwindProvider>. ' +
+      'Pass `onHaptics` on the provider to forward the request to expo-haptics (or any library).',
+  )
+}
+
+/**
+ * Whether a className needs press/focus state tracking.
+ * @param className Raw className string.
+ * @returns True when an `active:` / `focus:` variant is present.
+ */
+function hasInteractiveVariant(className: string): boolean {
+  return INTERACTIVE_VARIANT.test(className)
+}
+
+/**
+ * Best-effort display name for the wrapped component.
+ * @param component Component being wrapped.
+ * @returns Its `displayName`, `name`, or `'Component'`.
+ */
+function displayNameOf(component: unknown): string {
+  const named = component as { displayName?: string; name?: string }
+  return named.displayName ?? named.name ?? 'Component'
+}
+
+/**
+ * Fire the `mount`-trigger haptics once, after the element mounts. Snaps
+ * the resolved requests + dispatcher at mount via a `useRef` initializer
+ * (evaluated only on the first render), so an unstable inline `onHaptics`
+ * doesn't re-fire them and no ref is written during render.
+ * @param resolved The resolved className (carries any haptic requests).
+ * @param onHaptics The dispatcher from context (or undefined).
+ */
+function useMountHaptics(resolved: ResolvedCss, onHaptics: OnHaptics | undefined): void {
+  const mount = useRef({ resolved, onHaptics })
+  useEffect(() => {
+    const { resolved: current, onHaptics: dispatch } = mount.current
+    if (!dispatch || !current.haptics) return
+    for (const entry of current.haptics) if (entry.trigger === 'mount') dispatch(entry.request, 'mount')
+  }, [])
+}
+
+/** Suffix marking a secondary class-prop (`contentContainerClassName`, …). */
+const CLASSNAME_SUFFIX = 'ClassName'
+
+/**
+ * Resolve every secondary `<prefix>ClassName` prop (e.g.
+ * `contentContainerClassName` on a ScrollView / FlatList) into its
+ * matching `<prefix>Style`, in place. Any existing `<prefix>Style` is
+ * appended last (caller wins). The original `*ClassName` prop is deleted
+ * so RN never sees an unknown attribute. The primary `className` is
+ * handled separately by the leaf and never reaches here.
+ * @param props Mutable prop object being assembled for the host.
+ * @param state Rnwind context for resolution.
+ */
+function applyContainerClassNames(props: Record<string, unknown>, state: RnwindState): void {
+  for (const key of Object.keys(props)) {
+    if (!key.endsWith(CLASSNAME_SUFFIX)) continue
+    const value = props[key]
+    if (typeof value !== 'string') continue
+    const styleKey = `${key.slice(0, -CLASSNAME_SUFFIX.length)}Style`
+    props[styleKey] = resolve(value, state, props[styleKey]).style
+    delete props[key]
+  }
+}
+
+/**
+ * Build the props for the wrapped host: resolved `style`, gradient
+ * (`colors`/`start`/`end`), truncate (`numberOfLines`/`ellipsizeMode`),
+ * secondary `<prefix>ClassName` → `<prefix>Style`, and a chained
+ * `onPressIn` that fires press-trigger haptics. Unknown props on a host
+ * are simply ignored by RN, so this stays generic.
+ * @param rest Forwarded props (incl. `ref`).
+ * @param resolved Resolved className result.
+ * @param state Rnwind context — used to resolve secondary class props.
+ * @param onHaptics Dispatcher from context.
+ * @param userOnPressIn Caller-supplied onPressIn to chain after the haptic.
+ * @returns The merged prop object for `createElement`.
+ */
+function buildProps(
+  rest: Record<string, unknown>,
+  resolved: ResolvedCss,
+  state: RnwindState,
+  onHaptics: OnHaptics | undefined,
+  userOnPressIn?: unknown,
+): Record<string, unknown> {
+  warnIfHapticsUnwired(onHaptics, resolved.haptics)
+  const props: Record<string, unknown> = { ...rest, style: resolved.style }
+  applyContainerClassNames(props, state)
+  if (resolved.colors) {
+    props.colors = resolved.colors
+    props.start = resolved.start
+    props.end = resolved.end
+  }
+  if (resolved.numberOfLines !== undefined) {
+    props.numberOfLines = resolved.numberOfLines
+    if (resolved.ellipsizeMode !== undefined) props.ellipsizeMode = resolved.ellipsizeMode
+  }
+  const pressHaptics = onHaptics && resolved.haptics?.filter((entry) => entry.trigger === 'pressIn')
+  if (pressHaptics && pressHaptics.length > 0) {
+    const previous = userOnPressIn as ((event: unknown) => void) | undefined
+    props.onPressIn = (event: unknown): void => {
+      for (const entry of pressHaptics) onHaptics(entry.request, 'pressIn')
+      previous?.(event)
+    }
+  } else if (userOnPressIn !== undefined) {
+    props.onPressIn = userOnPressIn
+  }
+  return props
+}
+
+/** Props a leaf receives — the wrapped `as` tag plus forwarded props. */
+interface LeafProps {
+  readonly as: ComponentType<Record<string, unknown>>
+  readonly className?: string
+  readonly style?: unknown
+  readonly [key: string]: unknown
+}
+
+/**
+ * Non-interactive leaf: resolve className → style (+ features) and
+ * forward. One context read, one molecule/atom resolve.
+ * @param props Leaf props.
+ * @param props.as
+ * @param props.className
+ * @param props.style
+ * @param props.onPressIn
+ * @returns The rendered `as` element.
+ */
+function PlainLeaf({ as: As, className, style, onPressIn, ...rest }: LeafProps): ReactElement {
+  const state = useRnwind()
+  const resolved = resolve(className, state, style)
+  useMountHaptics(resolved, state.onHaptics)
+  return createElement(As, buildProps(rest, resolved, state, state.onHaptics, onPressIn))
+}
+
+/**
+ * Interactive leaf: tracks press/focus via `useInteract()`, feeds it into
+ * `resolve` so `active:`/`focus:` atoms apply, and chains the
+ * press/focus handlers.
+ * @param props Leaf props.
+ * @param props.as
+ * @param props.className
+ * @param props.style
+ * @param props.onPressIn
+ * @param props.onPressOut
+ * @param props.onFocus
+ * @param props.onBlur
+ * @returns The rendered `as` element with interactive wiring.
+ */
+function InteractiveLeaf({ as: As, className, style, onPressIn, onPressOut, onFocus, onBlur, ...rest }: LeafProps): ReactElement {
+  const state = useRnwind()
+  const interact = useInteract()
+  const resolved = resolve(className, state, style, interact.state)
+  useMountHaptics(resolved, state.onHaptics)
+  const props = buildProps(rest, resolved, state, state.onHaptics, onPressIn)
+  props.onPressIn = chainPress(props.onPressIn as Parameters<typeof chainPress>[0], interact.onPressIn)
+  props.onPressOut = chainPress(onPressOut as Parameters<typeof chainPress>[0], interact.onPressOut)
+  props.onFocus = chainFocus(onFocus as Parameters<typeof chainFocus>[0], interact.onFocus)
+  props.onBlur = chainFocus(onBlur as Parameters<typeof chainFocus>[0], interact.onBlur)
+  return createElement(As, props)
+}
+
+/**
+ * Wrap a component so its `className` prop resolves to RN `style` (plus
+ * gradient / truncate props and haptic dispatch) at render — no matter
+ * how className arrived: written directly, spread through `{...rest}`, or
+ * forwarded down custom wrappers. The returned component is hook-free; it
+ * dispatches to a plain or interactive leaf so non-interactive elements
+ * never pay for press/focus state. `ref` (a normal prop in React 19) and
+ * all other props forward untouched.
+ * @example
+ * ```tsx
+ * const Pressable = wrap(RNPressable)
+ * <Pressable className="active:bg-sky-700 px-4 haptic-light" onPress={fn} />
+ * ```
+ * @param Component Any component accepting a `style` prop.
+ * @returns A component accepting `className`.
+ */
+export function wrap<P>(Component: ComponentType<P>): ComponentType<P & { className?: string }> {
+  const as = Component as unknown as ComponentType<Record<string, unknown>>
+  /**
+   * The wrapped component — hook-free dispatcher to a leaf.
+   * @param props Forwarded props with `className` intercepted.
+   * @param props.className
+   * @returns The rendered leaf.
+   */
+  function RnwindWrapped({ className, ...rest }: { className?: string; [key: string]: unknown }): ReactElement {
+    if (className !== undefined && hasInteractiveVariant(className)) {
+      return createElement(InteractiveLeaf, { as, className, ...rest })
+    }
+    return createElement(PlainLeaf, { as, className, ...rest })
+  }
+  RnwindWrapped.displayName = `wrap(${displayNameOf(Component)})`
+  return RnwindWrapped as unknown as ComponentType<P & { className?: string }>
+}
+
+/**
+ * Whether a namespace member name denotes a component to wrap —
+ * PascalCase and not a React context (`*Context`). Lowercase utilities /
+ * hooks (`createAnimatedComponent`, `spring`) pass through untouched.
+ * @param name Member key.
+ * @returns True when the member should be `wrap()`-ed.
+ */
+function isComponentMember(name: string): boolean {
+  return /^[A-Z]/.test(name) && !name.endsWith('Context')
+}
+
+/**
+ * Wrap a component NAMESPACE (a default/namespace import like reanimated's
+ * `Animated`) so member access — `Animated.View`, `Animated.ScrollView` —
+ * returns a `wrap()`-ed component whose `className` resolves at render.
+ * Returns a Proxy: component members are wrapped lazily and memoised so
+ * each access yields the SAME wrapped component (stable identity — React
+ * would remount otherwise). Non-component members (`createAnimatedComponent`,
+ * config objects) pass straight through.
+ * @example
+ * ```tsx
+ * const Animated = wrapNamespace(RNReanimated)
+ * <Animated.View className="enter-fade" />
+ * ```
+ * @param namespace The imported namespace object.
+ * @returns A Proxy that wraps component members on access.
+ */
+export function wrapNamespace<T extends object>(namespace: T): T {
+  const cache = new Map<string, unknown>()
+  return new Proxy(namespace, {
+    get(target, key, receiver): unknown {
+      const value = Reflect.get(target, key, receiver)
+      if (typeof key !== 'string' || !isComponentMember(key)) return value
+      if (!value || (typeof value !== 'function' && typeof value !== 'object')) return value
+      let wrapped = cache.get(key)
+      if (wrapped === undefined) {
+        wrapped = wrap(value as ComponentType<unknown>)
+        cache.set(key, wrapped)
+      }
+      return wrapped
+    },
+  })
+}