@symbiote-native/react 0.2.8 → 0.4.0

package/README.md

@@ -6,7 +6,7 @@ in **mutation mode** (`appendChild` / `insertBefore` / `removeChild` → the eng
 mutation API); `@symbiote-native/engine` does the clone-on-write commit into Fabric.
 
 This is the **reference adapter**: the known-good driver used to validate the native pipe and the
-commit engine before any other framework lands, so a break in Vue/Svelte/Solid isolates to *that*
+commit engine before any other framework lands, so a break in Vue/Svelte/Solid isolates to _that_
 adapter, not the core.
 
 <div align="center">
@@ -16,7 +16,7 @@ adapter, not the core.
 </div>
 
 > New to SymbioteNative? The [root README](../../README.md) has the architecture and the one fact it
-> rests on — React is just *one client* of `nativeFabricUIManager`.
+> rests on — React is just _one client_ of `nativeFabricUIManager`.
 
 ---
 
@@ -46,7 +46,7 @@ export default function App() {
   return (
     <View style={{ padding: 24 }}>
       <Text>Taps: {count}</Text>
-      <Pressable onPress={() => setCount((c) => c + 1)}>
+      <Pressable onPress={() => setCount(c => c + 1)}>
         <Text>Tap me</Text>
       </Pressable>
     </View>
@@ -54,7 +54,7 @@ export default function App() {
 }
 ```
 
-The native entry registers a low-level *runnable* instead of a React component: RN's Fabric host
+The native entry registers a low-level _runnable_ instead of a React component: RN's Fabric host
 calls it with the surface's `rootTag`, and the renderer takes over from there — `nativeFabric-
 UIManager` is driven directly, RN's own renderer never runs.
 
@@ -94,7 +94,7 @@ path:
   `Appearance` · `PixelRatio` · `AppState`, plus imperative `Alert` · `ActionSheetIOS` · `Share` ·
   `Linking` · `Vibration` · `Keyboard` · `StatusBar` — each reaching its real native module on the
   bridgeless host.
-- **`Animated`, both drivers** — JS *and* native driver side by side (`timing` · `spring` · `loop` ·
+- **`Animated`, both drivers** — JS _and_ native driver side by side (`timing` · `spring` · `loop` ·
   `interpolate` · `ValueXY` · tracking · `diffClamp`). Native offload is proven by jamming the JS
   thread 1.5 s: the native-driven animations keep moving, the JS-driven one stalls.
 - **Third-party native views** — `@react-native-community/slider` used straight from the package

package/build/bootstrap.js

@@ -1,11 +1,10 @@
-// Zero-config app entry: wires the four RN-backed host seams (via @symbiote-native/components'
+// Zero-config app entry: wires the four RN-backed host seams (via @symbiote-native/components's
 // bootstrapHost) plus this adapter's own AppRegistry host-registrar bridge, then registers the
-// root component — collapsing the canary's manual sequence into one call. Lives OUTSIDE the
-// package's main barrel (see package.json's "./bootstrap" export): it imports react-native
-// directly, which Vitest's Flow-unaware transform can't parse (see
-// @symbiote-native/components/bootstrap for the full reason).
+// root component in one call. Lives OUTSIDE the package's main barrel (package.json's
+// "./bootstrap" export) because it imports react-native directly, which Vitest's Flow-unaware
+// transform can't parse (see @symbiote-native/components/bootstrap for the full reason).
 import { AppRegistry as RNAppRegistry } from 'react-native';
-import { bootstrapHost } from '@symbiote-native/components/bootstrap';
+import { bootstrapHost, } from '@symbiote-native/components/bootstrap';
 import { AppRegistry, setHostRegistrar } from './modules/app-registry/index.js';
 // Mirrors bare RN's own `AppRegistry.registerComponent(appName, () => App)` idiom, minus the
 // manual host wiring in front of it.

package/build/components/activity-indicator/index.android.js

@@ -1,10 +1,8 @@
-// ActivityIndicator on Android: AndroidProgressBar needs `styleAttr` (it drives the
-// ProgressBar's setStyle(); without it the view throws "setStyle() not called") and
-// `indeterminate: true`, and its default color is the theme (null), per RN's
-// ActivityIndicator.js android branch ({styleAttr:'Normal', indeterminate:true}). Metro
-// picks this on an Android host; no Platform.OS read.
-// device-verify-pending: prop names mirror RN's AndroidProgressBar, proven on a real
-// host by the absence of the "setStyle() not called" red box.
+// AndroidProgressBar needs `styleAttr` (drives ProgressBar.setStyle(); missing it throws
+// "setStyle() not called") and `indeterminate: true`; default color is the theme (null) —
+// mirrors RN's ActivityIndicator.js android branch. Metro selects this file on an Android
+// host, no Platform.OS read needed.
+// device-verify-pending: confirmed by the absence of the setStyle() red box on a real host.
 import { descriptorToReact } from '../../descriptor-to-react/index.js';
 import { useActivityIndicatorLogic } from './shared.js';
 const PLATFORM = {

package/build/components/activity-indicator/shared.js

@@ -11,7 +11,7 @@
 // index.ios.ts / index.android.ts each declare their OWN top-level `ActivityIndicator`
 // function that calls this hook, rather than exporting whatever a factory here returns (same
 // shape as switch/shared.ts's useSwitchLogic).
-import { renderActivityIndicator, resolveAccessibilityProps } from '@symbiote-native/components';
+import { renderActivityIndicator, resolveAccessibilityProps, } from '@symbiote-native/components';
 export function useActivityIndicatorLogic(rawProps, platform) {
     // The wrapper is a raw symbiote-view, not the View FC, so it never runs
     // resolveAccessibilityProps itself, so fold aria/role here, then forward the resolved

package/build/components/button.js

@@ -5,7 +5,7 @@
 import { createElement } from 'react';
 import { Text } from '../components.js';
 import { TouchableOpacity } from './touchable/index.js';
-import { BUTTON_ACCESSIBILITY_ROLE, resolveButtonTextStyle } from '@symbiote-native/components';
+import { BUTTON_ACCESSIBILITY_ROLE, resolveButtonTextStyle, } from '@symbiote-native/components';
 export const Button = props => {
     const { title, onPress, color, disabled, touchSoundDisabled, testID, hasTVPreferredFocus, nextFocusDown, nextFocusForward, nextFocusLeft, nextFocusRight, nextFocusUp, ...accessibilityRest } = props;
     const textStyle = resolveButtonTextStyle(color, disabled);

package/build/components/flat-list/index.js

@@ -6,7 +6,7 @@
 // transforms are shared from @symbiote-native/components. This file only adapts to React's lifecycle
 // (element creation + ref threading).
 import { createElement, } from 'react';
-import { dlog, resolveClassName } from '@symbiote-native/engine';
+import { dlog, resolveClassName, } from '@symbiote-native/engine';
 import { SINGLE_COLUMN, chunkIntoRows, expandRowViewability, firstItemOfRow, lastItemOfRow, rowKeyExtractor, } from '@symbiote-native/components';
 import { VirtualizedList, } from '../virtualized-list/index.js';
 export function FlatList(props) {
@@ -38,7 +38,10 @@ export function FlatList(props) {
     const resolvedColumnWrapperStyle = typeof columnWrapperStyle === 'string'
         ? resolveClassName(columnWrapperStyle)
         : columnWrapperStyle;
-    const rowStyle = [{ flexDirection: 'row' }, resolvedColumnWrapperStyle];
+    const rowStyle = [
+        { flexDirection: 'row' },
+        resolvedColumnWrapperStyle,
+    ];
     const renderRow = (info) => {
         const cells = info.item.items.map((item, column) => {
             const index = info.item.startIndex + column;

package/build/components/input-accessory-view/index.js

@@ -8,7 +8,12 @@ export const InputAccessoryView = rawProps => {
     // Owns its host element (symbiote-input-accessory-view), so it folds aria/role here; the
     // resolved accessibility* surface rides the node via `...passthrough`.
     const { nativeID, backgroundColor, style, children, ...passthrough } = resolveAccessibilityProps(rawProps);
-    const host = renderInputAccessoryView({ nativeID, backgroundColor, style, passthrough });
+    const host = renderInputAccessoryView({
+        nativeID,
+        backgroundColor,
+        style,
+        passthrough,
+    });
     // host has no structural children; the user children nest directly under it.
     return createElement(host.type, { key: host.key, ...host.props }, children);
 };

package/build/components/keyboard-avoiding-view/index.js

@@ -5,13 +5,17 @@
 //
 // The inset math + the behavior → style/structure decision are framework-agnostic and live in
 // @symbiote-native/components (render-keyboard-avoiding-view), shared verbatim with the Vue adapter.
-// React supplies only the lifecycle: useState for the inset, useRef for the measured frame, a
-// useEffect subscription, and the descriptor-free element assembly around its children.
+// React supplies only the lifecycle: useState for the inset, useRef for the measured frame and
+// the cross-fade setting, the useEffect subscriptions, and the descriptor-free element assembly
+// around its children.
 import { createElement, useEffect, useRef, useState, } from 'react';
-import { dlog } from '@symbiote-native/engine';
-import { computeInset, readKeyboardFrame, readLayoutFrame, resolveKeyboardAvoidingLayout, DEFAULT_VERTICAL_OFFSET, } from '@symbiote-native/components';
+import { dlog, Keyboard, Platform, } from '@symbiote-native/engine';
+import { computeInset, keyboardAvoidingEventNamesFor, readKeyboardFrame, readLayoutFrame, readPrefersCrossFadeTransitions, resolveKeyboardAvoidingLayout, DEFAULT_VERTICAL_OFFSET, } from '@symbiote-native/components';
 import { View } from '../../components.js';
-import { Keyboard, KEYBOARD_EVENT } from '../../modules/keyboard.js';
+// The two notifications to subscribe to, per host (iOS takes the `will` pair so the view rides
+// up with the keyboard animation; Android has no will-notifications). Resolved ONCE at module
+// scope: Platform.OS is fixed for the process, so recomputing it per render buys nothing.
+const KEYBOARD_EVENTS = keyboardAvoidingEventNamesFor(Platform.OS);
 export const KeyboardAvoidingView = props => {
     const { behavior, enabled = true, keyboardVerticalOffset = DEFAULT_VERTICAL_OFFSET, contentContainerStyle, style, children, onLayout, 
     // The wrapper is the View FC, which runs resolveAccessibilityProps itself, so
@@ -23,27 +27,43 @@ export const KeyboardAvoidingView = props => {
     // next keyboard event's inset math.
     const frameRef = useRef(undefined);
     const initialHeightRef = useRef(undefined);
+    // A device accessibility setting, not component state: it cannot change mid-session, and
+    // learning it must not re-render. Read once per mount, then fed to every computeInset call.
+    const prefersCrossFadeRef = useRef(false);
+    useEffect(() => {
+        void readPrefersCrossFadeTransitions().then(prefers => {
+            prefersCrossFadeRef.current = prefers;
+        });
+    }, []);
     useEffect(() => {
         const onShow = (payload) => {
             const keyboard = readKeyboardFrame(payload);
-            const next = computeInset(frameRef.current, keyboard, keyboardVerticalOffset);
-            dlog(`KeyboardAvoidingView show -> inset ${next}`);
-            setInset(next);
+            // Functional update, not a read of `inset`: this handler is built inside the effect, so a
+            // direct read would freeze the value from the render that created it — and 'height' mode
+            // feeds the LIVE inset back in to cancel the wrapper's own shrink.
+            setInset(previousInset => {
+                const next = computeInset(frameRef.current, keyboard, keyboardVerticalOffset, {
+                    behavior,
+                    previousInset,
+                    prefersCrossFadeTransitions: prefersCrossFadeRef.current,
+                });
+                dlog(`KeyboardAvoidingView show -> inset ${next}`);
+                return next;
+            });
         };
         const onHide = () => {
             dlog('KeyboardAvoidingView hide -> inset 0');
             setInset(0);
         };
         const subscriptions = [
-            Keyboard.addListener(KEYBOARD_EVENT.didShow, onShow),
-            Keyboard.addListener(KEYBOARD_EVENT.didChangeFrame, onShow),
-            Keyboard.addListener(KEYBOARD_EVENT.didHide, onHide),
+            Keyboard.addListener(KEYBOARD_EVENTS.show, onShow),
+            Keyboard.addListener(KEYBOARD_EVENTS.hide, onHide),
         ];
         return () => {
             for (const subscription of subscriptions)
                 subscription.remove();
         };
-    }, [keyboardVerticalOffset]);
+    }, [behavior, keyboardVerticalOffset]);
     const handleLayout = (event) => {
         const frame = readLayoutFrame(event.nativeEvent.layout);
         if (frame !== undefined) {

package/build/components/modal/index.d.ts

@@ -1,5 +1,6 @@
 import { type FC, type ReactNode } from 'react';
-import { type IAccessibilityProps, type IAriaProps, type IModalAnimationType, type IModalOrientation, type IModalOrientationChangeEvent, type IModalPresentationStyle } from '@symbiote-native/components';
+import { type ISymbioteEvent } from '@symbiote-native/engine';
+import { type IAccessibilityProps, type IAriaProps, type IModalAnimationType, type IModalOrientation, type IModalPresentationStyle } from '@symbiote-native/components';
 import type { IStyleProp, IViewStyle } from '../../utils/styles';
 export type { IModalAnimationType, IModalPresentationStyle, IModalOrientation, IModalOrientationChangeEvent, } from '@symbiote-native/components';
 export interface IModalProps extends IAccessibilityProps, IAriaProps {
@@ -16,7 +17,7 @@ export interface IModalProps extends IAccessibilityProps, IAriaProps {
     onShow?: () => void;
     onDismiss?: () => void;
     onRequestClose?: () => void;
-    onOrientationChange?: (event: IModalOrientationChangeEvent) => void;
+    onOrientationChange?: (event: ISymbioteEvent) => void;
     style?: IStyleProp<IViewStyle>;
     className?: string;
     children?: ReactNode;

package/build/components/modal/index.js

@@ -11,7 +11,7 @@
 // host's onDismiss prop (it rides `...passthrough`), and the keep-alive holds the node mounted
 // through the exit transition. The native exit-animation timing is what's deferred, not the
 // callback contract.
-import { createElement, useEffect, useReducer } from 'react';
+import { createElement, useEffect, useReducer, } from 'react';
 import { dlog } from '@symbiote-native/engine';
 import { createInitialModalState, modalReducer, renderModal, resolveAccessibilityProps, shouldRenderModal, } from '@symbiote-native/components';
 export const Modal = rawProps => {

package/build/components/pressable/index.d.ts

@@ -2,7 +2,7 @@ import { type FC, type ReactNode } from 'react';
 import { type IPressState, type IPressHandler, type IRectOffset, type IPressableAndroidRippleConfig } from '@symbiote-native/components';
 import type { IAccessibilityProps, IAriaProps } from '@symbiote-native/components';
 import type { IStyleProp, IViewStyle } from '../../utils/styles';
-export type { IPressState, IPressableAndroidRippleConfig } from '@symbiote-native/components';
+export type { IPressState, IPressableAndroidRippleConfig, } from '@symbiote-native/components';
 type IPressableStyle = IStyleProp<IViewStyle> | ((state: IPressState) => IStyleProp<IViewStyle>);
 type IChildrenProp = ReactNode | ((state: IPressState) => ReactNode);
 export interface IPressableProps extends IAccessibilityProps, IAriaProps {

package/build/components/pressable/index.js

@@ -11,7 +11,7 @@
 // entirely in JS: android_ripple (an Android native-feedback prop on a dedicated inner View, inert
 // on iOS), unstable_pressDelay, and pressRetentionOffset (the drift region), all handled by the
 // shared machine; here we only wire its host + render the View.
-import { createElement, useMemo, useRef, useState } from 'react';
+import { createElement, useMemo, useRef, useState, } from 'react';
 import { createPressHandlers, createPressRuntime, rippleProps, buildPressableListeners, resolveDisabledAccessibilityState, noteHoverNoop, DEFAULT_DELAY_LONG_PRESS_MS, } from '@symbiote-native/components';
 import { View } from '../../components.js';
 function resolveStyle(style, state) {

package/build/components/scroll-view/index.android.js

@@ -6,11 +6,9 @@
 // android branch (cloneElement(refreshControl, {style}, <ScrollView nestedScrollEnabled
 // style={flex:1}>{content}</ScrollView>)). Metro picks this on an Android host; no
 // Platform.OS read.
-// device-verify-pending: the wrap shape mirrors RN, proven on a real host by the absence
-// of the "addViewAt: failed to insert" crash.
-import { cloneElement, createElement, forwardRef, useImperativeHandle, useRef } from 'react';
+import { cloneElement, createElement, forwardRef, useImperativeHandle, useRef, } from 'react';
 import { dlog } from '@symbiote-native/engine';
-import { buildScrollViewHandle, splitLayoutProps } from '@symbiote-native/components';
+import { buildScrollViewHandle, splitLayoutProps, } from '@symbiote-native/components';
 import { usePreparedScrollView, useNativeStickyScrollAttach, } from './shared.js';
 export const ScrollView = forwardRef((props, forwardedRef) => {
     const { scrollViewIntrinsic, scrollViewBaseStyle, outerProps, style, layoutSplitStyle, content, refreshControl, scrollAnimatedValue, nativeStickyAvailable, } = usePreparedScrollView(props);
@@ -23,11 +21,14 @@ export const ScrollView = forwardRef((props, forwardedRef) => {
     // Drive the sticky scroll value on the native UI thread (RN attachNativeEvent). No-op on a
     // host without the native animated module. The JS sticky path stays in effect.
     useNativeStickyScrollAttach(ref, scrollAnimatedValue, nativeStickyAvailable);
-    dlog('ScrollView.ANDROID refreshControl=' + (refreshControl === undefined ? 'NONE(1child)' : 'WRAP'));
+    dlog('ScrollView.ANDROID refreshControl=' +
+        (refreshControl === undefined ? 'NONE(1child)' : 'WRAP'));
     if (refreshControl === undefined) {
         // Base style (flexDirection: row for horizontal) under user style; undefined base
         // (vertical) passes the user style through unchanged.
-        const scrollStyle = scrollViewBaseStyle ? [scrollViewBaseStyle, style] : style;
+        const scrollStyle = scrollViewBaseStyle
+            ? [scrollViewBaseStyle, style]
+            : style;
         return createElement(scrollViewIntrinsic, { ...outerProps, style: scrollStyle, ref }, content);
     }
     // RN splits the flattened style across the two boxes (ScrollView.js android branch):
@@ -42,12 +43,19 @@ export const ScrollView = forwardRef((props, forwardedRef) => {
     // starves the wrapper of its layout style and it collapses to nothing. layoutSplitStyle is
     // `style` merged with the resolved className style (see usePreparedScrollView).
     const { outer: outerStyle, inner: innerStyle } = splitLayoutProps(layoutSplitStyle);
-    const scrollStyle = scrollViewBaseStyle ? [scrollViewBaseStyle, innerStyle] : innerStyle;
+    const scrollStyle = scrollViewBaseStyle
+        ? [scrollViewBaseStyle, innerStyle]
+        : innerStyle;
     // className is stripped from the spread here: layoutSplitStyle already folded its resolved
     // value into `outer`/`inner` above, so forwarding the raw prop too would re-apply its LAYOUT
     // half onto the inner scroll view a second time (on top of the outer wrapper).
     const { className: _classNameAppliedViaSplit, ...innerOuterProps } = outerProps;
-    const scrollView = createElement(scrollViewIntrinsic, { ...innerOuterProps, style: scrollStyle, nestedScrollEnabled: true, ref }, content);
+    const scrollView = createElement(scrollViewIntrinsic, {
+        ...innerOuterProps,
+        style: scrollStyle,
+        nestedScrollEnabled: true,
+        ref,
+    }, content);
     return cloneElement(refreshControl, { style: outerStyle }, scrollView);
 });
 ScrollView.displayName = 'ScrollView';

package/build/components/scroll-view/index.ios.js

@@ -1,23 +1,25 @@
-// ScrollView on iOS: the RefreshControl is a CHILD of the scroll view, rendered as a
-// sibling BEFORE the content container (RN ScrollView.js: {refreshControl}{contentContainer}).
-// Also the base (scroll-view.ts re-exports it) for headless / web.
+// ScrollView (iOS): RefreshControl renders as a sibling BEFORE the content container, matching
+// RN's ScrollView.js ({refreshControl}{contentContainer}). Also the base export
+// (scroll-view.ts re-exports it) for headless / web.
 import { createElement, forwardRef, useImperativeHandle, useRef } from 'react';
 import { buildScrollViewHandle } from '@symbiote-native/components';
 import { usePreparedScrollView, useNativeStickyScrollAttach, } from './shared.js';
 export const ScrollView = forwardRef((props, forwardedRef) => {
     const { scrollViewIntrinsic, scrollViewBaseStyle, outerProps, style, content, refreshControl, scrollAnimatedValue, nativeStickyAvailable, } = usePreparedScrollView(props);
-    // The node ref backs the imperative handle; it attaches to the scroll-view element below
-    // (passing `ref` through createElement props binds it to the SymbioteNode, as TextInput does).
+    // Backs the imperative handle; passing `ref` through createElement props binds it to the
+    // SymbioteNode below, as TextInput does.
     const ref = useRef(null);
-    // Lazy getter, not the ref itself: the node is null until the element commits, so the handle
-    // must read ref.current on each command, an eager capture would freeze null.
+    // Lazy getter: the node is null until commit, so the handle reads ref.current per call
+    // instead of capturing eagerly, which would freeze null.
     useImperativeHandle(forwardedRef, () => buildScrollViewHandle(() => ref.current), []);
-    // Drive the sticky scroll value on the native UI thread (RN attachNativeEvent). No-op on a
-    // host without the native animated module. The JS sticky path stays in effect.
+    // Drives sticky scroll on the native UI thread (RN attachNativeEvent); no-ops without the
+    // native animated module, falling back to the JS sticky path.
     useNativeStickyScrollAttach(ref, scrollAnimatedValue, nativeStickyAvailable);
-    // Base style under user style so an explicit user value wins; undefined base (vertical)
+    // Base style stays under user style so an explicit value wins; undefined base (vertical)
     // passes the user style through unchanged.
-    const scrollStyle = scrollViewBaseStyle ? [scrollViewBaseStyle, style] : style;
+    const scrollStyle = scrollViewBaseStyle
+        ? [scrollViewBaseStyle, style]
+        : style;
     const scrollProps = { ...outerProps, style: scrollStyle, ref };
     if (refreshControl === undefined) {
         return createElement(scrollViewIntrinsic, scrollProps, content);

package/build/components/scroll-view/shared.js

@@ -14,7 +14,7 @@ import { createElement, useEffect, useRef, useState, } from 'react';
 import { AnimatedValue, dlog, event as animatedEvent, isClassNameValue, isNativeAnimatedAvailable, resolveClassName, } from '@symbiote-native/engine';
 import { attachStickyScroll, didContentSizeChange, forwardScrollEvent, readLayoutDimension, resolveDecelerationRate, resolveScrollForwarding, selectScrollIntrinsics, } from '@symbiote-native/components';
 import { resolveAccessibilityProps, } from '@symbiote-native/components';
-import { wrapStickyHeaders } from './sticky-header.js';
+import { wrapStickyHeaders, } from './sticky-header.js';
 export function usePreparedScrollView(rawProps) {
     // ScrollView forwards its outer props straight to the native scroll view (not a View
     // wrapper), so it folds aria/role into accessibility* here before forwarding.
@@ -42,13 +42,56 @@ export function usePreparedScrollView(rawProps) {
     if (headerLayoutYsRef.current === null)
         headerLayoutYsRef.current = new Map();
     const headerLayoutYs = headerLayoutYsRef.current;
-    const [, bumpHeaderLayout] = useState(0);
+    // The mounted headers by child index (RN's _stickyHeaderRefs, ScrollView.js:750), so a fresh
+    // measurement reaches its predecessor directly.
+    const stickyHeaderRefsRef = useRef(null);
+    if (stickyHeaderRefsRef.current === null)
+        stickyHeaderRefsRef.current = new Map();
+    const stickyHeaderRefs = stickyHeaderRefsRef.current;
+    const onHeaderRef = (index, handle) => {
+        if (handle === null)
+            stickyHeaderRefs.delete(index);
+        else
+            stickyHeaderRefs.set(index, handle);
+    };
+    // Measurements waiting to be handed to their predecessors, flushed together (see below).
+    const pendingHeaderYsRef = useRef(null);
+    if (pendingHeaderYsRef.current === null)
+        pendingHeaderYsRef.current = new Map();
+    const pendingHeaderYs = pendingHeaderYsRef.current;
+    const flushScheduledRef = useRef(false);
+    const flushHeaderYs = () => {
+        flushScheduledRef.current = false;
+        if (stickyHeaderIndices === undefined)
+            return;
+        for (const [index, y] of pendingHeaderYs) {
+            const previousIndex = stickyHeaderIndices[stickyHeaderIndices.indexOf(index) - 1];
+            if (previousIndex === undefined)
+                continue;
+            stickyHeaderRefs.get(previousIndex)?.setNextHeaderY(y);
+        }
+        pendingHeaderYs.clear();
+    };
+    // RN _onStickyHeaderLayout (ScrollView.js:1136): record this header's y, then hand it to the
+    // PREVIOUS sticky header as its push-off collision point.
+    //
+    // The handoff is COALESCED rather than immediate, and that is the point. Cross-talk runs BACKWARDS
+    // (a header learns its collision point from the one after it), so a mount measures every header
+    // and walks the chain end to start. Pushing each value the moment it arrives makes every link its
+    // own update generation - a setState on the predecessor, whose effect setStates again - and React
+    // caps nested updates at 50: three headers go unnoticed, two hundred abort the app with "Maximum
+    // update depth exceeded", which reads like an infinite loop but is really depth. Draining on a
+    // microtask puts one burst of layouts into ONE render pass, so depth stops tracking header count.
     const onHeaderLayoutY = (index, y) => {
         if (headerLayoutYs.get(index) === y)
             return;
         headerLayoutYs.set(index, y);
         dlog(`ScrollView sticky-header layoutY index=${index} y=${y}`);
-        bumpHeaderLayout(tick => tick + 1);
+        pendingHeaderYs.set(index, y);
+        if (flushScheduledRef.current)
+            return;
+        flushScheduledRef.current = true;
+        void Promise.resolve().then(flushHeaderYs);
     };
     // A class-name string resolves through the shared registry before it reaches the
     // framework-agnostic selector below, which only understands style objects/arrays.
@@ -58,7 +101,7 @@ export function usePreparedScrollView(rawProps) {
     // The per-axis intrinsics, base style, and content style come from the shared selector
     // (@symbiote-native/components): on Android horizontal resolves to its own ViewManager, on iOS both
     // map back to RCTScrollView; here we only pass the axis.
-    const { scrollViewIntrinsic, contentIntrinsic, scrollViewBaseStyle, contentStyle } = selectScrollIntrinsics(isHorizontal, resolvedContentContainerStyle);
+    const { scrollViewIntrinsic, contentIntrinsic, scrollViewBaseStyle, contentStyle, } = selectScrollIntrinsics(isHorizontal, resolvedContentContainerStyle);
     const outerProps = { ...outer };
     // className is pulled out above (unlike the rest of `...outer`) so `layoutSplitStyle` below can
     // resolve it eagerly; re-added here so the simple single-node paths (iOS, Android with no
@@ -121,7 +164,10 @@ export function usePreparedScrollView(rawProps) {
     // _handleContentOnLayout): read width/height off nativeEvent.layout and fire only when the
     // size actually changed (dedupe via a ref, like RN). Composed with any content onLayout.
     const lastContentSizeRef = useRef(null);
-    const contentProps = { style: contentStyle, collapsable: false };
+    const contentProps = {
+        style: contentStyle,
+        collapsable: false,
+    };
     // maintainVisibleContentPosition (and Android snapToAlignment) anchor against the metrics
     // of MOUNTED cell views. Android Fabric view-flattens layout-only cells away, so the native
     // MaintainVisibleScrollPositionHelper has nothing to anchor to and the list jumps on prepend.
@@ -144,10 +190,10 @@ export function usePreparedScrollView(rawProps) {
             onContentSizeChange(width, height);
         };
     }
-    // Sticky headers are a pure-JS layer (the native scroll view ignores stickyHeaderIndices);
-    // wrap the flagged children so they pin to the scroll offset. No-op when none are flagged.
+    // Wrap the flagged children so they pin to the scroll offset (see the sticky-headers note
+    // above); no-op when none are flagged.
     const contentChildren = hasStickyHeaders
-        ? wrapStickyHeaders(children, stickyHeaderIndices, scrollAnimatedValue, invertStickyHeaders, viewportHeight, StickyHeaderComponent, headerLayoutYs, onHeaderLayoutY)
+        ? wrapStickyHeaders(children, stickyHeaderIndices, scrollAnimatedValue, invertStickyHeaders, viewportHeight, StickyHeaderComponent, { headerLayoutYs, onHeaderLayoutY, onHeaderRef })
         : children;
     // `collapsable: false` is load-bearing on Android. The content container is a
     // layout-only View, which Android Fabric view-flattens away, hoisting the cells
@@ -159,7 +205,10 @@ export function usePreparedScrollView(rawProps) {
     const content = createElement(contentIntrinsic, contentProps, contentChildren);
     // resolveClassName(undefined) is a cheap {} no-op, so this is safe with no className too.
     const resolvedClassName = isClassNameValue(className) ? className : undefined;
-    const layoutSplitStyle = [resolveClassName(resolvedClassName), style];
+    const layoutSplitStyle = [
+        resolveClassName(resolvedClassName),
+        style,
+    ];
     return {
         scrollViewIntrinsic,
         scrollViewBaseStyle,

package/build/components/scroll-view/sticky-header.d.ts

@@ -1,9 +1,18 @@
-import { type ComponentType, type ReactNode } from 'react';
+import { type ComponentType, type ReactNode, type Ref } from 'react';
 import { AnimatedValue } from '@symbiote-native/engine';
 import { type IStickyHeaderProps } from '@symbiote-native/components';
+export type IStickyHeaderHandle = {
+    setNextHeaderY: (y: number) => void;
+};
+export type IStickyCrossTalk = {
+    headerLayoutYs: ReadonlyMap<number, number>;
+    onHeaderLayoutY: (index: number, y: number) => void;
+    onHeaderRef: (index: number, handle: IStickyHeaderHandle | null) => void;
+};
 export type IStickyHeaderComponentProps = IStickyHeaderProps & {
     children?: ReactNode;
+    ref?: Ref<IStickyHeaderHandle>;
 };
 export type IStickyHeaderComponentType = ComponentType<IStickyHeaderComponentProps>;
 export declare const ScrollViewStickyHeader: IStickyHeaderComponentType;
-export declare function wrapStickyHeaders(children: ReactNode, stickyHeaderIndices: number[] | undefined, scrollAnimatedValue: AnimatedValue, invertStickyHeaders: boolean | undefined, scrollViewHeight: number | undefined, StickyHeaderComponent: IStickyHeaderComponentType | undefined, headerLayoutYs: ReadonlyMap<number, number>, onHeaderLayoutY: (index: number, y: number) => void): ReactNode;
+export declare function wrapStickyHeaders(children: ReactNode, stickyHeaderIndices: number[] | undefined, scrollAnimatedValue: AnimatedValue, invertStickyHeaders: boolean | undefined, scrollViewHeight: number | undefined, StickyHeaderComponent: IStickyHeaderComponentType | undefined, crossTalk: IStickyCrossTalk): ReactNode;