react-native-unistyles 3.5.2 → 3.6.0

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

package/src/unifiber/src/adapters/reanimated.ts

@@ -0,0 +1,204 @@
+// Keeps Reanimated's CSS style copy (`_cssStyle`) in sync with native-only style updates.
+// Private fields are pinned by test/reanimated-contract.test.ts for 4.5 and 4.7.
+import type { Host } from '../host'
+import type { OwnerAdapter, StyleSource } from './registry'
+import * as fiber from '../fiber'
+
+// Bound once: Metro's inline requires
+const { contextReaderFor } = fiber
+const CLASS_COMPONENT = fiber.Tag.ClassComponent
+
+type CSSManagerLike = { update(style: Record<string, unknown>, props?: Record<string, unknown>): void }
+
+type AnimatedComponentLike = {
+    props: Record<string, any>
+    _cssStyle: Record<string, unknown>
+    _CSSManager?: CSSManagerLike
+    // true between componentWillUnmount and componentDidMount: also while frozen, suspended or in a hidden Activity
+    _willUnmount?: boolean
+    _updateStyles(props: Record<string, any>): void
+    shouldComponentUpdate(nextProps: Record<string, any>, ...rest: Array<unknown>): boolean
+}
+
+type AttachedState = {
+    source: StyleSource
+    original: (props: Record<string, any>) => void
+    originalShouldUpdate: AnimatedComponentLike['shouldComponentUpdate']
+    rendering: boolean
+    styleProp: unknown
+    epoch: number
+    contextKeys: Array<unknown>
+    fresh: Record<string, unknown> | undefined
+}
+
+// Symbol.for: two copies of unifiber in one bundle never wrap a component twice
+const STATE = Symbol.for('unifiber.reanimated.css')
+
+// Kept out of AnimatedComponentLike: a unique symbol in a public type breaks consumers' declaration builds (TS4023)
+type Attached = AnimatedComponentLike & { [STATE]?: AttachedState }
+
+const hasCSSConfig = (cssStyle: Record<string, unknown>) => {
+    for (const key in cssStyle) {
+        if (key.startsWith('transition') || key.startsWith('animation')) {
+            return true
+        }
+    }
+
+    return false
+}
+
+// Keyframe animations and pseudo-styles register again on update after componentWillUnmount cleaned them up.
+// React runs no componentWillUnmount for a subtree deleted while hidden, so on a hidden owner they would leak.
+const registersOnUpdate = (cssStyle: Record<string, unknown>) => {
+    for (const key in cssStyle) {
+        if (key.startsWith('animation')) {
+            return true
+        }
+
+        const value = cssStyle[key]
+
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            for (const selector in value) {
+                if (selector === 'default' || selector.startsWith(':')) {
+                    return true
+                }
+
+                break
+            }
+        }
+    }
+
+    return false
+}
+
+// Deepest case: ScrollView with refreshControl on Android, 6-7 fibers
+const MAX_OWNER_DEPTH = 12
+
+// The class whose `_componentRef` is this host's public instance. Lists don't match: their ref isn't a host.
+export const animatedComponentOf = (host: Host | null | undefined): AnimatedComponentLike | null => {
+    const fiber = host as any
+
+    if (fiber?.memoizedProps?.collapsable !== false) {
+        return null
+    }
+
+    const publicInstance = fiber.stateNode?.canonical?.publicInstance
+
+    if (!publicInstance) {
+        return null
+    }
+
+    let current = fiber.return
+
+    for (let depth = 0; current && depth < MAX_OWNER_DEPTH; depth++) {
+        if (current.tag === CLASS_COMPONENT && current.stateNode?._componentRef === publicInstance) {
+            return isAnimatedComponent(current.stateNode) ? current.stateNode : null
+        }
+
+        current = current.return
+    }
+
+    return null
+}
+
+const isAnimatedComponent = (owner: any): owner is AnimatedComponentLike =>
+    typeof owner?._updateStyles === 'function' &&
+    typeof owner.shouldComponentUpdate === 'function' &&
+    owner._cssStyle !== null &&
+    typeof owner._cssStyle === 'object'
+
+function updateStylesThroughSource(this: Attached, props: Record<string, any>) {
+    const state = this[STATE]!
+
+    state.original.call(this, props)
+
+    if (!hasCSSConfig(this._cssStyle)) {
+        return
+    }
+
+    const epoch = state.source.epoch()
+    const read = contextReaderFor(this, state.rendering)
+    const contexts = state.source.contexts ?? []
+    let contextChanged = false
+
+    for (let i = 0; i < contexts.length; i++) {
+        const context = contexts[i]!
+        const value = read(context)
+        const key = state.source.contextKey ? state.source.contextKey(context, value) : value
+
+        if (state.contextKeys[i] !== key) {
+            state.contextKeys[i] = key
+            contextChanged = true
+        }
+    }
+
+    if (contextChanged || state.styleProp !== props.style || state.epoch !== epoch) {
+        state.fresh = state.source.resolve(props, read)
+        state.styleProp = props.style
+        state.epoch = epoch
+    }
+
+    const fresh = state.fresh
+
+    if (!fresh) {
+        return
+    }
+
+    // only the keys Reanimated kept: animated styles were split out of _cssStyle
+    for (const key in this._cssStyle) {
+        if (key in fresh) {
+            this._cssStyle[key] = fresh[key]
+        }
+    }
+}
+
+// Marks the render phase, where context must be read from React's stack
+function shouldUpdateMarkingRender(this: Attached, ...args: [Record<string, any>, ...Array<unknown>]) {
+    const state = this[STATE]!
+
+    state.rendering = true
+
+    try {
+        return state.originalShouldUpdate.apply(this, args)
+    } finally {
+        state.rendering = false
+    }
+}
+
+export const reanimatedCSSAdapter: OwnerAdapter<AnimatedComponentLike> = {
+    name: 'react-native-reanimated/css',
+    gate: (host: Host) => (host as unknown as fiber.RawFiber).memoizedProps?.collapsable === false,
+    claim: animatedComponentOf,
+    attach: (owner: Attached, source) => {
+        if (owner[STATE]) {
+            return
+        }
+
+        owner[STATE] = {
+            source,
+            original: owner._updateStyles,
+            originalShouldUpdate: owner.shouldComponentUpdate,
+            rendering: false,
+            styleProp: undefined,
+            epoch: -1,
+            contextKeys: [],
+            fresh: undefined,
+        }
+        owner._updateStyles = updateStylesThroughSource
+        owner.shouldComponentUpdate = shouldUpdateMarkingRender
+    },
+    refresh: (owner) => {
+        // not mounted yet
+        if (typeof owner._CSSManager?.update !== 'function') {
+            return
+        }
+
+        // Hidden transitions still run, so the reveal shows the new value instead of animating from the old one
+        if (owner._willUnmount === true && registersOnUpdate(owner._cssStyle)) {
+            return
+        }
+
+        owner._updateStyles(owner.props)
+        owner._CSSManager.update(owner._cssStyle, owner.props)
+    },
+}

package/src/unifiber/src/adapters/registry.ts

@@ -0,0 +1,102 @@
+import type { Context } from 'react'
+import type { ContextReader } from '../fiber'
+import type { Host } from '../host'
+
+export interface StyleSource {
+    readonly name: string
+    // bumps on every runtime change (theme, breakpoint, ...)
+    epoch(): number
+    readonly contexts?: ReadonlyArray<Context<any>>
+    // cache key for a context value; default: the value itself. Stable scopes renamed in place need `scope?.name`
+    contextKey?(context: Context<any>, value: unknown): unknown
+    // undefined: none of these styles belong to this source
+    resolve(props: Record<string, any>, read: ContextReader): Record<string, unknown> | undefined
+}
+
+export interface OwnerAdapter<Owner extends object = object> {
+    readonly name: string
+    // runs on every link: keep it to a property read or two
+    gate(host: Host): boolean
+    claim(host: Host): Owner | null
+    attach(owner: Owner, source: StyleSource): void
+    // runs for hidden owners too (frozen, suspended, hidden Activity): skip there what can't run while hidden
+    refresh(owner: Owner, source: StyleSource): void
+}
+
+export type OwnerRegistry = {
+    link(host: Host | null | undefined): void
+    refresh(hosts: ReadonlyArray<Host | null | undefined>): void
+}
+
+// An adapter that throws is disabled for the session and reported once
+export const createOwnerRegistry = (
+    source: StyleSource,
+    adapters: ReadonlyArray<OwnerAdapter<any>>,
+    onAdapterError?: (reason: string) => void,
+): OwnerRegistry => {
+    const disabledAdapters = new Set<OwnerAdapter>()
+    const disable = (adapter: OwnerAdapter, error: unknown) => {
+        disabledAdapters.add(adapter)
+        onAdapterError?.(`adapter ${adapter.name} failed: ${String(error)}`)
+    }
+    // Not inline closures: a closure in link() makes Hermes allocate its environment on every call
+    const attachOwner = (adapter: OwnerAdapter, host: Host) => {
+        try {
+            const owner = adapter.claim(host)
+
+            if (owner) {
+                adapter.attach(owner, source)
+            }
+        } catch (error) {
+            disable(adapter, error)
+        }
+    }
+    const refreshOwner = (adapter: OwnerAdapter, host: Host, seen: Set<object>) => {
+        try {
+            const owner = adapter.claim(host)
+
+            if (owner && !seen.has(owner)) {
+                seen.add(owner)
+                adapter.attach(owner, source)
+                adapter.refresh(owner, source)
+            }
+        } catch (error) {
+            disable(adapter, error)
+        }
+    }
+
+    return {
+        link(host) {
+            if (!host) {
+                return
+            }
+
+            for (let i = 0; i < adapters.length; i++) {
+                const adapter = adapters[i]!
+
+                if (adapter.gate(host) && !disabledAdapters.has(adapter)) {
+                    attachOwner(adapter, host)
+                }
+            }
+        },
+        refresh(hosts) {
+            const seen = new Set<object>()
+
+            for (let h = 0; h < hosts.length; h++) {
+                const host = hosts[h]
+
+                if (!host) {
+                    continue
+                }
+
+                for (let i = 0; i < adapters.length; i++) {
+                    const adapter = adapters[i]!
+
+                    if (adapter.gate(host) && !disabledAdapters.has(adapter)) {
+                        refreshOwner(adapter, host, seen)
+                    }
+                }
+            }
+        },
+    }
+}

package/src/unifiber/src/diagnostics.ts

@@ -0,0 +1,55 @@
+import type { RawFiber } from './fiber'
+import type { Host } from './host'
+import * as host from './host'
+
+// Bound once: Metro's inline requires
+const { committedHalf, fiberOf } = host
+
+const styleDiffers = (a: RawFiber, b: RawFiber) => a.memoizedProps?.style !== b.memoizedProps?.style
+
+const flattenInto = (style: unknown, out: Record<string, unknown>) => {
+    if (Array.isArray(style)) {
+        for (let i = 0; i < style.length; i++) {
+            flattenInto(style[i], out)
+        }
+    } else if (style && typeof style === 'object') {
+        Object.assign(out, style)
+    }
+
+    return out
+}
+
+export type Drift = { key: string; react: unknown; expected: unknown }
+
+// Keys that differ from React's committed props: React re-sends them on the view's next render
+export const verify = (host: Host, expected: Record<string, unknown>): Array<Drift> => {
+    const baseline = committedHalf(fiberOf(host), styleDiffers) ?? fiberOf(host)
+    const react = flattenInto(baseline.memoizedProps?.style, {})
+    const drift: Array<Drift> = []
+
+    for (const key in expected) {
+        if (react[key] !== expected[key]) {
+            drift.push({ key, react: react[key], expected: expected[key] })
+        }
+    }
+
+    return drift
+}
+
+// Development builds only
+export const getOwners = (host: Host, max = 8): Array<string> => {
+    const owners: Array<string> = []
+
+    for (let owner = fiberOf(host)._debugOwner; owner && owners.length < max; owner = owner._debugOwner ?? owner.owner) {
+        const name = owner.name ?? owner.type?.displayName ?? owner.type?.name ?? owner.type?.render?.name
+
+        if (name) {
+            owners.push(name)
+        }
+    }
+
+    return owners
+}
+
+// Development builds only
+export const getCreationStack = (host: Host): string | undefined => fiberOf(host)._debugStack?.stack