@symbiote-native/react 0.3.0 → 1.0.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,9 +54,24 @@ export default function App() {
 }
 ```
 
-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.
+The zero-config entry wires the RN-backed host seams (colors, images, device events,
+third-party ViewConfigs) and registers the app in one call — this is what
+[`examples/react`](../../examples/react) actually uses:
+
+```js
+// index.js
+import { registerApp } from '@symbiote-native/react/bootstrap';
+import App from './App';
+import { name as appName } from './app.json';
+
+registerApp(App, { appName });
+```
+
+`registerApp` mirrors bare RN's own `AppRegistry.registerComponent(appName, () => App)` idiom,
+minus the manual host wiring in front of it — RN's own renderer never runs; `nativeFabric-
+UIManager` is driven directly. For anything the defaults don't cover (a custom color processor,
+image resolver, or manual control over the mount callback), drive the lower-level seam directly —
+a raw _runnable_ instead of a registered component:
 
 ```js
 // index.js
@@ -77,8 +92,8 @@ AppRegistry.registerRunnable(appName, ({ rootTag }) => {
 });
 ```
 
-The runnable example is [`examples/react`](../../examples/react) — a stock RN 0.86 app whose full
-canary ([`App.tsx`](../../examples/react/App.tsx)) exercises every block of the surface below.
+Either way, the full canary ([`App.tsx`](../../examples/react/App.tsx)) exercises every block of
+the surface below.
 
 ---
 
@@ -94,7 +109,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

@@ -4,7 +4,7 @@
 // "./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/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 '@symbiote-native/engine';
+// 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.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 {
@@ -28,3 +28,4 @@ export interface IPressableProps extends IAccessibilityProps, IAriaProps {
     children?: IChildrenProp;
 }
 export declare const Pressable: FC<IPressableProps>;
+export declare const TouchablePressable: FC<IPressableProps>;

package/build/components/pressable/index.js

@@ -11,9 +11,10 @@
 // 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 { createPressHandlers, createPressRuntime, rippleProps, buildPressableListeners, resolveDisabledAccessibilityState, noteHoverNoop, DEFAULT_DELAY_LONG_PRESS_MS, } from '@symbiote-native/components';
+import { createElement, useEffect, useMemo, useRef, useState, } from 'react';
+import { createPressHandlers, createPressRuntime, disposePressRuntime, rippleProps, buildPressableListeners, resolveDisabledAccessibilityState, noteHoverNoop, DEFAULT_DELAY_LONG_PRESS_MS, DEFAULT_MIN_PRESS_DURATION_MS, } from '@symbiote-native/components';
 import { View } from '../../components.js';
+import { flushExternalUpdate } from '../../host-config.js';
 function resolveStyle(style, state) {
     if (typeof style === 'function')
         return style(state);
@@ -24,8 +25,8 @@ function resolveChildren(children, state) {
         return children(state);
     return children;
 }
-export const Pressable = props => {
-    const { onPress, onPressIn, onPressOut, onPressMove, onLongPress, delayLongPress = DEFAULT_DELAY_LONG_PRESS_MS, disabled, cancelable, hitSlop, pressRetentionOffset, unstable_pressDelay = 0, android_ripple, android_disableSound, onHoverIn, onHoverOut, delayHoverIn, delayHoverOut, accessibilityState, testID, style, children, 
+const PressableImpl = props => {
+    const { onPress, onPressIn, onPressOut, onPressMove, onLongPress, delayLongPress = DEFAULT_DELAY_LONG_PRESS_MS, disabled, cancelable, hitSlop, pressRetentionOffset, unstable_pressDelay = 0, __minPressDuration = DEFAULT_MIN_PRESS_DURATION_MS, android_ripple, android_disableSound, onHoverIn, onHoverOut, delayHoverIn, delayHoverOut, accessibilityState, testID, style, children, 
     // The remaining accessibility / aria props forward to View untouched; View runs
     // resolveAccessibilityProps, so aria/role fold there, once.
     ...accessibilityRest } = props;
@@ -45,10 +46,16 @@ export const Pressable = props => {
             return callback => view.measure(callback);
         },
         schedule: (callback, ms) => {
-            const id = setTimeout(callback, ms);
+            const id = setTimeout(() => flushExternalUpdate(callback), ms);
             return () => clearTimeout(id);
         },
+        now: Date.now,
     }), []);
+    // This renderer tears insertion effects down during host updates, so use the stable passive
+    // unmount seam to cancel delayed press-in, long-press and press-out callbacks.
+    useEffect(() => () => {
+        disposePressRuntime(runtime);
+    }, [runtime]);
     const handlers = useMemo(() => createPressHandlers({
         onPress,
         onPressIn,
@@ -57,6 +64,7 @@ export const Pressable = props => {
         onLongPress,
         delayLongPress,
         unstable_pressDelay,
+        minPressDuration: __minPressDuration,
         hitSlop,
         pressRetentionOffset,
     }, runtime, host), [
@@ -67,6 +75,7 @@ export const Pressable = props => {
         onLongPress,
         delayLongPress,
         unstable_pressDelay,
+        __minPressDuration,
         hitSlop,
         pressRetentionOffset,
         runtime,
@@ -98,3 +107,6 @@ export const Pressable = props => {
     const inner = ripple !== undefined ? createElement(View, ripple, content) : content;
     return createElement(View, viewProps, inner);
 };
+export const Pressable = PressableImpl;
+// Relative-only composition seam; it is deliberately absent from the adapter barrel.
+export const TouchablePressable = props => createElement(PressableImpl, { ...props, __minPressDuration: 0 });

package/build/components/safe-area-view/index.d.ts

@@ -4,6 +4,7 @@ import { type IAccessibilityProps, type IAriaProps } from '@symbiote-native/comp
 import type { IStyleProp, IViewStyle } from '../../utils/styles';
 export interface ISafeAreaViewProps extends IAccessibilityProps, IAriaProps {
     style?: IStyleProp<IViewStyle>;
+    id?: string;
     className?: string;
     children?: ReactNode;
     onLayout?: (event: ISymbioteEvent) => void;

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

@@ -6,9 +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.
-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);
@@ -21,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):
@@ -40,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

@@ -17,7 +17,9 @@ export const ScrollView = forwardRef((props, forwardedRef) => {
     useNativeStickyScrollAttach(ref, scrollAnimatedValue, nativeStickyAvailable);
     // 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.
@@ -147,7 +193,7 @@ export function usePreparedScrollView(rawProps) {
     // 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;