@symbiote-native/react 0.3.0 → 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

@@ -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 {

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,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;

package/build/components/scroll-view/sticky-header.js

@@ -7,7 +7,7 @@
 // layer instead. The interpolation mirrors ScrollViewStickyHeader.js and now lives,
 // framework-agnostic, in @symbiote-native/components (computeStickyInterpolation); this file
 // holds only the React component shell, layout state, and child-wrapping.
-import { Children, createElement, isValidElement, useCallback, useEffect, useReducer, useRef, useState, } from 'react';
+import { Children, createElement, isValidElement, useCallback, useEffect, useImperativeHandle, useReducer, useRef, useState, } from 'react';
 import { AnimatedInterpolation, AnimatedValue, Platform, dlog, } from '@symbiote-native/engine';
 import { createInitialStickyState, nextStickyHeaderY, readLayoutNumber, reduceSticky, STICKY_HEADER_Z_INDEX, } from '@symbiote-native/components';
 import { Animated } from '../../modules/animated/index.js';
@@ -30,7 +30,24 @@ function firstChild(children) {
 // (@symbiote-native/components); this component supplies only the React lifecycle: the ONE folded
 // state cell, the interpolation-node + listener wiring, the debounce setTimeout, and the re-render.
 export const ScrollViewStickyHeader = props => {
-    const { inverted, scrollViewHeight, scrollAnimatedValue, nextHeaderLayoutY, children } = props;
+    const { inverted, scrollViewHeight, scrollAnimatedValue, nextHeaderLayoutY, children, ref, } = props;
+    // The next header's y lives HERE, not in a prop the parent re-renders to update (RN keeps it in
+    // the child too, ScrollViewStickyHeader.js:65). The prop only seeds the first render; afterwards
+    // the ScrollView pushes updates through setNextHeaderY. That keeps the cost linear - a
+    // parent-state round trip re-renders every child on every header's layout, so N headers cost N
+    // re-renders of N children. At N=200 it churned enough native animated nodes to trip Fabric's view
+    // registry ("Attempt to dequeue already registered component") seconds after mount.
+    const [nextHeaderY, setNextHeaderY] = useState(nextHeaderLayoutY);
+    useImperativeHandle(ref, () => ({ setNextHeaderY }), []);
+    // The imperative push is a fast path, not the source of truth. When the parent DOES re-render
+    // with a different value the prop wins, because the successor may be gone: a VirtualizedList
+    // unmounts headers as they scroll out, and a value pushed in earlier would otherwise stick
+    // around as a collision point that no longer exists.
+    const lastNextHeaderProp = useRef(nextHeaderLayoutY);
+    if (lastNextHeaderProp.current !== nextHeaderLayoutY) {
+        lastNextHeaderProp.current = nextHeaderLayoutY;
+        setNextHeaderY(nextHeaderLayoutY);
+    }
     // The one folded state cell (RN's scattered useState/useRef collapsed into IStickyHeaderState),
     // mutated in place by reduceSticky. Lazily created once.
     const stateRef = useRef(null);
@@ -39,7 +56,10 @@ export const ScrollViewStickyHeader = props => {
     // The animated node that drives the transform (RN's animatedTranslateY), rebuilt by the
     // rebuild-interpolation effect. When the scroll value is native, this interpolation runs on the
     // UI thread: the smooth pin.
-    const [animatedTranslateY, setAnimatedTranslateY] = useState(() => scrollAnimatedValue.interpolate({ inputRange: [-1, 0], outputRange: [0, 0] }));
+    const [animatedTranslateY, setAnimatedTranslateY] = useState(() => scrollAnimatedValue.interpolate({
+        inputRange: [-1, 0],
+        outputRange: [0, 0],
+    }));
     const debounceTimer = useRef(null);
     // The current interpolation node + its settled-value listener id, held so the next rebuild can
     // detach the old listener (engine calls the reducer does NOT own) and unmount can clean up.
@@ -49,9 +69,14 @@ export const ScrollViewStickyHeader = props => {
         os: Platform.OS,
         inverted,
         scrollViewHeight,
-        nextHeaderLayoutY,
+        nextHeaderLayoutY: nextHeaderY,
     });
-    inputsRef.current = { os: Platform.OS, inverted, scrollViewHeight, nextHeaderLayoutY };
+    inputsRef.current = {
+        os: Platform.OS,
+        inverted,
+        scrollViewHeight,
+        nextHeaderLayoutY: nextHeaderY,
+    };
     // dispatch reaches through a ref because the effect executors dispatch follow-up actions
     // (the listener -> animated-tick, the debounce timer -> debounce-fired).
     const dispatchRef = useRef(() => { });
@@ -85,7 +110,10 @@ export const ScrollViewStickyHeader = props => {
                         clearTimeout(debounceTimer.current);
                     debounceTimer.current = setTimeout(() => {
                         debounceTimer.current = null;
-                        dispatchRef.current({ kind: 'debounce-fired', value: effect.value });
+                        dispatchRef.current({
+                            kind: 'debounce-fired',
+                            value: effect.value,
+                        });
                     }, effect.delay);
                     break;
                 }
@@ -110,7 +138,7 @@ export const ScrollViewStickyHeader = props => {
     // dispatches 'layout' itself); also does the initial identity build on mount.
     useEffect(() => {
         dispatchRef.current({ kind: 'inputs-changed' });
-    }, [inverted, scrollViewHeight, nextHeaderLayoutY, scrollAnimatedValue]);
+    }, [inverted, scrollViewHeight, nextHeaderY, scrollAnimatedValue]);
     // Detach the listener + clear the debounce on unmount.
     useEffect(() => () => {
         const previous = interpolationRef.current;
@@ -123,7 +151,11 @@ export const ScrollViewStickyHeader = props => {
         const y = readLayoutNumber(event, 'y');
         const height = readLayoutNumber(event, 'height');
         // Keep the previous value when a field is absent (RN sets state only on a defined read).
-        dispatch({ kind: 'layout', y: y ?? state.layoutY, height: height ?? state.layoutHeight });
+        dispatch({
+            kind: 'layout',
+            y: y ?? state.layoutY,
+            height: height ?? state.layoutHeight,
+        });
         props.onLayout(event);
         const child = firstChild(children);
         const childOnLayout = child === undefined ? undefined : readChildOnLayout(child);
@@ -131,12 +163,17 @@ export const ScrollViewStickyHeader = props => {
     };
     // The EXPLICIT debounced translateY overrides the committed transform for hit-testing, while
     // `animatedTranslateY` does the smooth (native-driven) pin, per RN ScrollViewStickyHeader.js.
-    const passthroughAnimatedPropExplicitValues = state.translateY !== null ? { style: { transform: [{ translateY: state.translateY }] } } : null;
+    const passthroughAnimatedPropExplicitValues = state.translateY !== null
+        ? { style: { transform: [{ translateY: state.translateY }] } }
+        : null;
     // collapsable:false keeps the wrapper a real Yoga node; zIndex makes the pinned header paint
     // OVER the rows scrolling under it. `style` is `unknown` on Animated.View, so the interpolation
     // transform passes with no cast.
     return createElement(Animated.View, {
-        style: { transform: [{ translateY: animatedTranslateY }], zIndex: STICKY_HEADER_Z_INDEX },
+        style: {
+            transform: [{ translateY: animatedTranslateY }],
+            zIndex: STICKY_HEADER_Z_INDEX,
+        },
         onLayout,
         collapsable: false,
         passthroughAnimatedPropExplicitValues,
@@ -153,7 +190,8 @@ ScrollViewStickyHeader.displayName = 'ScrollViewStickyHeader';
 // header (the collision point past which it scrolls off) by looking up its successor's index in
 // `stickyHeaderIndices`. The LAST flagged header has no successor, so its `nextHeaderLayoutY`
 // stays undefined and it sticks indefinitely (correct).
-export function wrapStickyHeaders(children, stickyHeaderIndices, scrollAnimatedValue, invertStickyHeaders, scrollViewHeight, StickyHeaderComponent, headerLayoutYs, onHeaderLayoutY) {
+export function wrapStickyHeaders(children, stickyHeaderIndices, scrollAnimatedValue, invertStickyHeaders, scrollViewHeight, StickyHeaderComponent, crossTalk) {
+    const { headerLayoutYs, onHeaderLayoutY, onHeaderRef } = crossTalk;
     if (stickyHeaderIndices === undefined || stickyHeaderIndices.length === 0)
         return children;
     const Wrapper = StickyHeaderComponent ?? ScrollViewStickyHeader;
@@ -168,6 +206,10 @@ export function wrapStickyHeaders(children, stickyHeaderIndices, scrollAnimatedV
         dlog(`ScrollView sticky-header wrap index=${index} next=${nextIndex} nextY=${nextHeaderLayoutY}`);
         return createElement(Wrapper, {
             key: child.key ?? `sticky-${index}`,
+            // Registers this header so the ScrollView can push the NEXT header's y straight in
+            // (RN ScrollView.js:1109). Without it a measurement would have to travel through parent
+            // state, re-rendering every child.
+            ref: (handle) => onHeaderRef(index, handle),
             nextHeaderLayoutY,
             // RN _onStickyHeaderLayout: record this header's own y, then push it to the previous
             // header as its nextHeaderLayoutY. We record into the parent map; the lookup above feeds

package/build/components/text-input/index.js

@@ -10,7 +10,7 @@
 // (setTextAndSelection), never a plain prop re-push. See @symbiote-native/components/state/text-input.
 import { forwardRef, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useRef, useState, } from 'react';
 import { dispatchViewCommand, dlog, } from '@symbiote-native/engine';
-import { blurTextInput, setInputBlurred, setInputFocused } from '@symbiote-native/engine';
+import { blurTextInput, setInputBlurred, setInputFocused, } from '@symbiote-native/engine';
 import { resolveAccessibilityProps, resolveTextInputProps, renderTextInput, foldText, textFromChange, eventCountFromChange, shouldCommandText, INITIAL_EVENT_COUNT, SELECTION_NONE, } from '@symbiote-native/components';
 import { descriptorToReact } from '../../descriptor-to-react/index.js';
 export const TextInput = forwardRef((rawProps, forwardedRef) => {
@@ -132,7 +132,12 @@ export const TextInput = forwardRef((rawProps, forwardedRef) => {
             const node = ref.current;
             if (node === null)
                 return;
-            dispatchViewCommand(node, 'setTextAndSelection', [mostRecentEventCount, '', 0, 0]);
+            dispatchViewCommand(node, 'setTextAndSelection', [
+                mostRecentEventCount,
+                '',
+                0,
+                0,
+            ]);
             lastNativeText.current = '';
         },
         isFocused: () => focused.current,

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

@@ -13,6 +13,8 @@ export declare const TouchableOpacity: FC<ITouchableOpacityProps>;
 export interface ITouchableHighlightProps extends ITouchableBaseProps {
     activeOpacity?: number;
     underlayColor?: string;
+    onShowUnderlay?: () => void;
+    onHideUnderlay?: () => void;
 }
 export declare const TouchableHighlight: FC<ITouchableHighlightProps>;
 export type ITouchableWithoutFeedbackProps = ITouchableBaseProps;