react-native-unistyles 3.5.3 → 3.7.0

package/src/specs/ShadowRegistry/index.ts

@@ -2,10 +2,14 @@ import { NitroModules } from 'react-native-nitro-modules'
 
 import type { Scope } from '../../components/ScopedThemeContext'
 import type { VerifyReport } from '../../diagnostics/types'
+import type { Host } from '../../unifiber/src'
 import type { UnistylesShadowRegistry as UnistylesShadowRegistrySpec } from './ShadowRegistry.nitro'
 import type { ShadowNode, Unistyle, ViewHandle } from './types'
 
+import { Fiber, Reanimated } from '../../unifiber/src'
 import { StyleSheet } from '../StyleSheet'
+import { createUnistylesStyleSource } from './styleSource'
+import { traceSection } from './tracing'
 
 interface ShadowRegistry extends UnistylesShadowRegistrySpec {
     // Babel API
@@ -25,126 +29,71 @@ interface ShadowRegistry extends UnistylesShadowRegistrySpec {
 
 const HybridShadowRegistry = NitroModules.createHybridObject<ShadowRegistry>('UnistylesShadowRegistry')
 
-const HOST_COMPONENT_TAG = 5
-const SUSPENSE_TAG = 13
-const OFFSCREEN_TAG = 22
+const { collectVisibleAncestors, getHostFor, getHostForInstanceHandle, getShadowNode, getShadowNodes, isHidden } = Fiber
 
-const isInsideSuspendedBoundary = (fiber: any): boolean => {
-    let current = fiber?.return
+const { source: styleSource, bumpEpoch } = createUnistylesStyleSource({
+    get: () => HybridShadowRegistry.getScopedTheme(),
+    set: (name) => HybridShadowRegistry.setScopedTheme(name),
+})
+const owners = Fiber.createOwnerRegistry(styleSource, [Reanimated.cssAdapter], (reason) => {
+    console.warn(`Unistyles: ${reason}. CSS transitions won't follow theme changes.`)
+})
 
-    while (current) {
-        if ((current.tag === SUSPENSE_TAG || current.tag === OFFSCREEN_TAG) && current.memoizedState !== null) {
-            return true
-        }
-
-        current = current.return
-    }
-
-    return false
-}
-
-const findFiberForHandle = (handle: ViewHandle) => {
-    return (
-        handle?.__internalInstanceHandle ??
-        handle?.getScrollResponder?.()?.getNativeScrollRef?.()?.__internalInstanceHandle ??
-        handle?.getNativeScrollRef?.()?.__internalInstanceHandle ??
-        handle?._viewRef?.__internalInstanceHandle ??
-        handle?.viewRef?.current?.__internalInstanceHandle ??
-        handle?._nativeRef?.__internalInstanceHandle
-    )
-}
+// A component can point at another native view by the time its ref is cleaned up, eg. FlatList on Android remounts
+// its native ScrollView when `horizontal` changes, so remove unlinks the view it was linked with
+// The host points at its current node, while a stored node would keep its first revision (and children) alive
+// Native views always resolve to their own host, so they skip it
+const linkedHosts = new WeakMap<object, Host>()
 
-const findShadowNodeForHandle = (handle: ViewHandle) => {
-    const node =
-        handle?.__internalInstanceHandle?.stateNode?.node ??
-        handle?.getScrollResponder?.()?.getNativeScrollRef?.()?.__internalInstanceHandle?.stateNode?.node ??
-        handle?.getNativeScrollRef?.()?.__internalInstanceHandle?.stateNode?.node ??
-        handle?._viewRef?.__internalInstanceHandle?.stateNode?.node ??
-        handle?.viewRef?.current?.__internalInstanceHandle?.stateNode?.node ??
-        handle?._nativeRef?.__internalInstanceHandle?.stateNode?.node
-
-    // @ts-ignore we don't know the type of handle
-    if (!node && handle?.props?.horizontal && handle?.constructor?.name === 'FlatList') {
-        throw new Error(
-            'Unistyles: detected an unsupported FlatList with the horizontal prop. This will cause crashes on Android due to a bug in React Native core. Read more: https://github.com/facebook/react-native/issues/51601',
-        )
-    }
+const committedHosts: Array<Host | undefined> = []
+let refreshNodes: Array<ShadowNode> = []
 
-    return node
+const collectShadowNodes = (host: Host) => {
+    getShadowNodes(host, refreshNodes)
 }
 
 // React re-attaches an untouched subtree through its root's node and only follows clones made on the JS thread.
 // Once a node was cloned elsewhere (state updates, Reanimated), React would commit a subtree from before a Unistyles
 // update, so after a Unistyles commit the committed nodes and their host ancestors must point at the committed tree
 const refreshReactNodes = () => {
-    const fibers = HybridShadowRegistry.takeCommittedInstanceHandles()
+    bumpEpoch()
+
+    const handles = HybridShadowRegistry.takeCommittedInstanceHandles()
 
-    if (fibers.length === 0) {
+    if (handles.length === 0) {
         return
     }
 
-    const nodes: Array<ShadowNode> = []
-    const refreshedTags = new Set<number>()
-    const hostFibers: Array<any> = []
-
-    for (const fiber of fibers) {
-        // collected, unmounted since
-        if (!fiber) {
-            continue
+    try {
+        for (let i = 0; i < handles.length; i++) {
+            committedHosts[i] = getHostForInstanceHandle(handles[i])
         }
 
-        let isHidden = false
-
-        hostFibers.length = 0
-
-        for (let current: any = fiber; current; current = current.return) {
-            // hidden by Suspense or a frozen screen
-            if ((current.tag === SUSPENSE_TAG || current.tag === OFFSCREEN_TAG) && current.memoizedState !== null) {
-                isHidden = true
-            }
-
-            if (current.tag !== HOST_COMPONENT_TAG) {
-                continue
-            }
-
-            // its ancestors are visible and already collected
-            if (refreshedTags.has(current.stateNode?.canonical?.nativeTag)) {
-                break
-            }
+        collectVisibleAncestors(committedHosts, collectShadowNodes)
 
-            hostFibers.push(current)
+        if (refreshNodes.length > 0) {
+            HybridShadowRegistry.refreshReactNodes(refreshNodes)
         }
 
-        if (isHidden) {
-            continue
-        }
-
-        for (const hostFiber of hostFibers) {
-            const node = hostFiber.stateNode?.node
-            const alternateNode = hostFiber.alternate?.stateNode?.node
-            const hostTag = hostFiber.stateNode?.canonical?.nativeTag
-
-            if (hostTag !== undefined) {
-                refreshedTags.add(hostTag)
-            }
+        traceSection('refreshOwners', () => owners.refresh(committedHosts))
+    } finally {
+        committedHosts.length = 0
+        refreshNodes = []
+    }
+}
 
-            if (node) {
-                nodes.push(node)
-            }
+StyleSheet.addChangeListener(refreshReactNodes)
 
-            if (alternateNode && alternateNode !== node) {
-                nodes.push(alternateNode)
-            }
-        }
+// a unistyle key holds its secrets object. A unistyle spread into another StyleSheet.create keeps its key,
+// but the parser resolves the (hidden) secrets to undefined, so the key no longer points at a unistyle
+const isUnistyleKey = (style: any, key: string) => {
+    if (!key.startsWith('unistyles_')) {
+        return false
     }
 
-    if (nodes.length > 0) {
-        HybridShadowRegistry.refreshReactNodes(nodes)
-    }
+    return typeof style[key] === 'object' && style[key] !== null
 }
 
-StyleSheet.addChangeListener(refreshReactNodes)
-
 // skips empty styles and splits a style merged from many unistyles (eg. flattened by Animated) into one per unistyle
 // runs for every style on every link, so it reads the keys once and allocates only for the rare merged style
 const collectStyle = (style: any, collected: Array<any>) => {
@@ -156,7 +105,7 @@ const collectStyle = (style: any, collected: Array<any>) => {
     let unistylesCount = 0
 
     for (const key of keys) {
-        if (key.startsWith('unistyles_')) {
+        if (isUnistyleKey(style, key)) {
             unistylesCount++
         }
     }
@@ -170,7 +119,7 @@ const collectStyle = (style: any, collected: Array<any>) => {
     }
 
     for (const key of keys) {
-        if (key.startsWith('unistyles_')) {
+        if (isUnistyleKey(style, key)) {
             collected.push({ [key]: style[key] })
         }
     }
@@ -191,9 +140,10 @@ HybridShadowRegistry.add = (handle, styles, scope) => {
     }
 
     if (filteredStyles.length > 0) {
-        const node = findShadowNodeForHandle(handle)
+        const host = getHostFor(handle)
+        const node = host && getShadowNode(host)
 
-        if (!node) {
+        if (!host || !node) {
             throw new Error(
                 `Unistyles: Could not find shadow node for one of your components of type ${handle?.constructor?.name ?? 'unknown'}`,
             )
@@ -207,6 +157,11 @@ HybridShadowRegistry.add = (handle, styles, scope) => {
         }
 
         HybridShadowRegistry.link(node, filteredStyles)
+        owners.link(host)
+
+        if (!handle.__internalInstanceHandle) {
+            linkedHosts.set(handle, host)
+        }
 
         if (scope) {
             HybridShadowRegistry.setScopedTheme(previousScopedTheme)
@@ -219,12 +174,16 @@ HybridShadowRegistry.remove = (handle) => {
         return
     }
 
-    const maybeNode = findShadowNodeForHandle(handle)
+    const linkedHost = handle.__internalInstanceHandle ? undefined : linkedHosts.get(handle)
+    const host = linkedHost ?? getHostFor(handle)
+    const maybeNode = host && getShadowNode(host)
 
-    if (maybeNode) {
-        const fiber = findFiberForHandle(handle)
+    if (linkedHost) {
+        linkedHosts.delete(handle)
+    }
 
-        if (fiber && isInsideSuspendedBoundary(fiber)) {
+    if (host && maybeNode) {
+        if (isHidden(host)) {
             HybridShadowRegistry.suspend(maybeNode)
         } else {
             HybridShadowRegistry.unlink(maybeNode)

package/src/specs/ShadowRegistry/styleSource.ts

@@ -0,0 +1,78 @@
+import type { Scope } from '../../components/ScopedThemeContext'
+import type { StyleSource } from '../../unifiber/src'
+
+import { ScopedThemeContext } from '../../components/ScopedThemeContext'
+
+type ScopedThemeAccess = {
+    get(): string | undefined
+    set(name: string | undefined): void
+}
+
+export const createUnistylesStyleSource = (scopedTheme: ScopedThemeAccess) => {
+    let epoch = 0
+    let warned = false
+
+    const source: StyleSource = {
+        name: 'unistyles',
+        epoch: () => epoch,
+        contexts: [ScopedThemeContext],
+        contextKey: (_context, scope) => (scope as Scope | null)?.name,
+        resolve: (props, read) => {
+            try {
+                return resolveFresh(props, read(ScopedThemeContext))
+            } catch (error) {
+                if (!warned) {
+                    warned = true
+                    console.warn(`Unistyles: Could not refresh styles for a CSS transition. ${String(error)}`)
+                }
+
+                return undefined
+            }
+        },
+    }
+
+    const resolveFresh = (props: Record<string, any>, scope: Scope | null | undefined) => {
+        const styles = [props.style].flat(Infinity)
+        const fresh: Record<string, unknown> = {}
+        let hasUnistyles = false
+
+        for (const style of styles) {
+            if (!style || typeof style !== 'object') {
+                continue
+            }
+
+            Object.assign(fresh, style)
+
+            for (const key in style) {
+                if (!key.startsWith('unistyles_') || !Object.prototype.hasOwnProperty.call(style, key)) {
+                    continue
+                }
+
+                hasUnistyles = true
+
+                const previousScopedTheme = scope ? scopedTheme.get() : undefined
+
+                if (scope) {
+                    scopedTheme.set(scope.name)
+                }
+
+                try {
+                    Object.assign(fresh, style[key]?.uni__getStyles?.())
+                } finally {
+                    if (scope) {
+                        scopedTheme.set(previousScopedTheme)
+                    }
+                }
+            }
+        }
+
+        return hasUnistyles ? fresh : undefined
+    }
+
+    return {
+        source,
+        bumpEpoch: () => {
+            epoch++
+        },
+    }
+}

package/src/specs/ShadowRegistry/tracing.ts

@@ -0,0 +1,23 @@
+// console.timeStamp(label, start, end, trackName), React Native 0.86+ reports it only while DevTools records and keeps
+// nothing, unlike performance.measure, which adds every entry to an unbounded buffer
+type TracingConsole = {
+    timeStamp?: (label: string, start: number, end: number, trackName: string) => void
+}
+
+const tracingConsole = console as unknown as TracingConsole
+const canTrace = __DEV__ && typeof tracingConsole.timeStamp === 'function'
+
+// Slice on the "Unistyles" track of the React Native DevTools Performance panel, next to the native ones
+export const traceSection = <T>(name: string, fn: () => T): T => {
+    if (!canTrace) {
+        return fn()
+    }
+
+    const start = performance.now()
+
+    try {
+        return fn()
+    } finally {
+        tracingConsole.timeStamp?.(name, start, performance.now(), 'Unistyles')
+    }
+}

package/src/specs/ShadowRegistry/types.ts

@@ -1,48 +1,8 @@
-export type StateNode = {
-    node?: ShadowNode
-    canonical?: {
-        nativeTag?: number
-    }
-}
-
-export type ShadowNode = {
-    __hostObjectShadowNodeWrapper: any
-}
+export type { ShadowNode } from '../../unifiber/src'
 
 export type ViewHandle = {
-    __internalInstanceHandle?: {
-        stateNode?: StateNode
-        elementType?: string
-    }
-    getScrollResponder?: () => {
-        getNativeScrollRef?: () => {
-            __internalInstanceHandle?: {
-                stateNode?: StateNode
-            }
-        }
-    }
-    getNativeScrollRef?: () => {
-        __internalInstanceHandle?: {
-            stateNode?: StateNode
-        }
-    }
-    _viewRef?: {
-        __internalInstanceHandle?: {
-            stateNode?: StateNode
-        }
-    }
-    viewRef?: {
-        current?: {
-            __internalInstanceHandle?: {
-                stateNode?: StateNode
-            }
-        }
-    }
-    _nativeRef?: {
-        __internalInstanceHandle?: {
-            stateNode?: StateNode
-        }
-    }
+    __internalInstanceHandle?: unknown
+    constructor?: { name?: string }
 }
 
 export type Unistyle = {

package/src/unifiber/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacek Pudysz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/unifiber/README.md

@@ -0,0 +1,92 @@
+<div align="center">
+
+# unifiber
+
+**One small, tested place for everything React Native styling libraries read from React's private fiber tree.**
+
+Built for [Unistyles](https://github.com/jpudysz/react-native-unistyles) and Uniwind Pro.
+
+`React 19` · `React Native 0.86 – 0.87` · `iOS + Android` · `Hermes-first` · `MIT`
+
+</div>
+
+---
+
+## Why this exists
+
+Unistyles and Uniwind both do something React Native doesn't officially support: they update the native shadow tree **without a React render**. Theme switches, breakpoints and insets reach native views in a single commit. To do that, both read React's private fiber fields: `__internalInstanceHandle`, `stateNode.node`, `memoizedState`, `return`, `alternate` and more.
+
+Until now, each library kept its own copy of those reads. They drifted apart, and both had bugs that only show up on real apps.
+
+unifiber is the one module that knows what a fiber looks like. It answers questions such as "which native view is this ref?", "is it hidden, and why?" and "what must refresh?". It's tested against **React Native's own components** and **Unistyles' real code**. A daily CI run against React Native nightly catches changes to React's internals before they ship.
+
+## API
+
+`Fiber` and `Reanimated` are plain objects. A **`Host`** is a native view's creation fiber behind an opaque type: free to keep, and stable, so the same view is always the same `Host` (`===` and `WeakMap` keys work).
+
+### ref → Host
+| | |
+|---|---|
+| `getHostFor(ref)` | Native-view refs, RN composites (ScrollView, FlatList / SectionList / VirtualizedList, ImageBackground, KeyboardAvoidingView, RefreshControl), and class components that render their view directly (Button on Android). Any other class component gives the first native view it renders, which may not be the one you styled. Call once per link and keep the result. |
+| `getShadowNodeFor(ref)` | Hot path when you don't keep a Host. |
+| `getHostForInstanceHandle(handle)` | For fibers handed back from C++ (`ShadowNodeFamily::getInstanceHandle`). |
+| `getContentContainerFor(ref)` | ScrollView / list content container, through RN's public `getInnerViewRef()`. |
+
+### Host → native
+| | |
+|---|---|
+| `getShadowNode(host)` | The node in React's `stateNode.node` wrapper. |
+| `getShadowNodes(host, out?)` | Every node React may diff against or re-attach: one after a commit, two while a render is in flight. |
+| `getNativeTag(host)` | `undefined` once the view has unmounted. |
+| `getParentHost(host)` | The nearest native view above (ActivityIndicator's wrapper, on both platforms). |
+| `patchRenderedProps(host, patch)` | Replaces React's diff baseline on both halves. **The only write**, used by Uniwind's baseline. |
+
+### Hidden state
+| | |
+|---|---|
+| `isHidden(host)` | Inside a Suspense fallback, a frozen screen or a hidden `<Activity>`: suspend instead of unlinking. Also right inside a ref cleanup, where React has not switched the committed tree yet. |
+| `isSuspended` · `isFrozen` · `isInHiddenActivity` | Why. Frozen means react-freeze (react-native-screens `freezeOnBlur`, react-navigation). |
+| `collectVisibleAncestors(hosts, visit)` | Batch refresh. Each visible native view from `hosts` up to the root, visited once, in one shared pass. |
+| `collectAncestors(hosts, visit)` | The same walk, with hidden views included. These are the semantics of Uniwind's `collectHostNodes` today. |
+
+### Diagnostics
+| | |
+|---|---|
+| `verify(host, expected)` | Style keys React would re-send, i.e. undo, on this view's next render. |
+| `getOwners(host)` | *Development builds only:* the components that created the view, e.g. `['ProfileCard', 'ProfileScreen']`. |
+| `getCreationStack(host)` | *Development builds only:* where the JSX was written, for Metro to symbolicate. |
+
+### Adapters: when a 3rd-party component owns the view
+Reanimated's `AnimatedComponent` keeps its own copy of a view's style for CSS transitions, so a native-only theme change gets overridden. The adapter keeps that copy in sync, so the theme change **animates** instead.
+
+```ts
+const owners = Fiber.createOwnerRegistry({
+    name: 'unistyles',
+    epoch: () => themeVersion,                     // bump on every runtime change
+    contexts: [ScopedThemeContext],
+    contextKey: (_ctx, scope) => scope?.name,      // stable scopes are renamed in place
+    resolve: (props, read) => freshStyles(props, read(ScopedThemeContext)),
+}, [Reanimated.cssAdapter], warnOnce)
+
+owners.link(host)        // in the link path: ~86 ns for a plain view
+owners.refresh(hosts)    // after a native-only update
+```
+
+Hidden views (a frozen screen, Suspense, a hidden `<Activity>`) are refreshed too, so a transition-only view shows the new value when it's revealed. **Trade-off:** a view that also has a keyframe animation (`animation*` keys) or pseudo-style values isn't refreshed while hidden. After it's revealed, it transitions from the pre-hide value to the new one, then settles correctly. Reanimated registers animations and pseudo-styles again on update, and React runs no `componentWillUnmount` for a subtree deleted while hidden, so refreshing them would leak.
+
+An adapter that throws is switched off for the session and reported once. Private Reanimated fields are pinned by a contract test against the 4.5.1 and 4.7.0 sources.
+
+## Compatibility
+
+| | |
+|---|---|
+| React | 19.2, and 19.3.1 with RN nightly (fiber tags pinned for 19.x) |
+| React Native | 0.87.1, 0.86.3 · iOS, Android · development and production. CI also runs React Native **nightly** (main) every day; 0.89.0-nightly-20261016 passes |
+| Reanimated | 4.5.1, 4.7.0 |
+| Unistyles | 3.5.3 and `main` (its real code runs in the suite) |
+| Uniwind | its lookups copied verbatim into the suite |
+| Engine | Hermes (legacy Hermes benchmarked) |
+
+## License
+
+MIT