@symbiote-native/react 0.3.0 → 1.0.0

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) => {
@@ -119,6 +119,14 @@ export const TextInput = forwardRef((rawProps, forwardedRef) => {
     // setSelection reuse setTextAndSelection (the same stale-safe path as a controlled write),
     // echoing the acknowledged event count so native applies them.
     useImperativeHandle(forwardedRef, () => ({
+        // Forwarded from the node so a TextInput ref is not poorer than any other host ref. An
+        // `expose`/`useImperativeHandle` that lists only the five TextInput methods CLOSES the
+        // node off, and the lowered path loses the opposite four — two different surfaces an app
+        // crosses between without touching its ref code. `ITextInputHandle` carries the account.
+        measure: (callback) => ref.current?.measure(callback),
+        measureInWindow: (callback) => ref.current?.measureInWindow(callback),
+        measureLayout: (relativeToNativeNode, onSuccess, onFail) => ref.current?.measureLayout(relativeToNativeNode, onSuccess, onFail),
+        setNativeProps: (nativeProps) => ref.current?.setNativeProps(nativeProps),
         focus: () => {
             const node = ref.current;
             if (node !== null)
@@ -132,7 +140,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;

package/build/components/touchable/index.js

@@ -1,18 +1,20 @@
-// The Touchable* family, all built on Pressable. RN realizes their feedback with Animated, and so
-// do we. The press-timing constants and the deactivation-floor math are shared with every adapter
-// (@symbiote-native/components/state/touchable); here React owns only the Animated wiring + the press
-// scheduling refs:
-//   TouchableOpacity:   animate an Animated.Value opacity toward activeOpacity on press-in and
-//     back to 1 on press-out, driven imperatively from onPressIn/onPressOut.
-//   TouchableHighlight: paint underlayColor + lower child opacity while pressed, via Pressable's
-//     pressed-state style (RN drives this with setState, not Animated, faithfully).
-//   TouchableWithoutFeedback: no visual change, just the press wiring.
-import { createElement, useRef } from 'react';
-import { createTouchableFeedbackHandlers, createTouchableFeedbackRuntime, highlightPressedStyle, DEFAULT_ACTIVE_OPACITY, DEFAULT_HIGHLIGHT_CHILD_OPACITY, DEFAULT_MIN_PRESS_DURATION_MS, DEFAULT_UNDERLAY_COLOR, OPACITY_ACTIVE_DURATION_MS, OPACITY_INACTIVE_DURATION_MS, RESTING_OPACITY, } from '@symbiote-native/components';
-import { Pressable } from '../pressable/index.js';
+// The Touchable* family, all built on Pressable. Ported against RN's own sources
+// (.vendors/react-native/.../Components/Touchable/*.js) after the 2026-08-19 audit found ten
+// divergences; the shared halves live in @symbiote-native/components and React owns only the
+// lifecycle — refs, effects, the real timers, the Animated wiring, and the child clone:
+//   TouchableOpacity:   an Animated.Value fades toward activeOpacity on press-in and back to the
+//     style's own resting opacity on press-out, driven from onPressIn/onPressOut.
+//   TouchableHighlight: the underlay machine drives a `shown` flag (NOT `pressed` — RN holds the
+//     underlay for delayPressOut past the tap); the container takes the underlay color and the
+//     child takes the lowered opacity, RN's split.
+//   TouchableWithoutFeedback: the same press-timing machine with the visual half left empty —
+//     "without feedback" means no VISUAL, not no timing.
+import { Children, cloneElement, createElement, isValidElement, useEffect, useRef, useState, } from 'react';
+import { createHighlightUnderlayHandlers, createHighlightUnderlayRuntime, createTouchableFeedbackHandlers, createTouchableFeedbackRuntime, hasTouchablePressHandler, resolveHighlightExtraStyles, restingOpacityFromStyle, DEFAULT_ACTIVE_OPACITY, OPACITY_ACTIVE_GRANT_DURATION_MS, OPACITY_INACTIVE_DURATION_MS, TOUCHABLE_MIN_PRESS_DURATION_MS, } from '@symbiote-native/components';
+import { TouchablePressable as Pressable, } from '../pressable/index.js';
 import { Animated } from '../../modules/animated/index.js';
-// The real setTimeout the shared feedback machine schedules its deferred activation/deactivation on
-// (core/components has no timer globals). Returns a canceller so an early release flushes the timer.
+// The real setTimeout the shared machines schedule on (core/components has no timer globals).
+// Returns a canceller so an early release flushes the timer.
 function scheduleTimeout(callback, ms) {
     const id = setTimeout(callback, ms);
     return () => clearTimeout(id);
@@ -22,42 +24,142 @@ export const TouchableOpacity = props => {
     // className is pulled out here, like style, and applied to the inner Animated.View below —
     // left in ...rest it would land on the outer Pressable instead, which is not where `style`
     // (the opacity-fade node) goes.
-    className, children, onPressIn, onPressOut, delayPressIn = 0, delayPressOut = 0, minPressDuration = DEFAULT_MIN_PRESS_DURATION_MS, ...rest } = props;
-    // One Animated.Value per mount, resting at full opacity. The Animated.View leaf commits its
-    // current value every frame, so timing it animates the real view.
-    const opacity = useRef(new Animated.Value(RESTING_OPACITY)).current;
+    className, children, disabled, onPressIn, onPressOut, delayPressIn = 0, delayPressOut = 0, 
+    // RN's Touchables override Pressability's 130ms floor with 0 (TouchableOpacity.js:195); the
+    // active visual is held by the fade's own duration instead.
+    minPressDuration = TOUCHABLE_MIN_PRESS_DURATION_MS, ...rest } = props;
+    // RN's _getChildStyleOpacityWithDefault: the fade settles at the opacity the CALLER's style
+    // asks for, not at a hard 1 — and must START there, or the first paint jumps to fully opaque.
+    const restingOpacity = restingOpacityFromStyle(style);
+    // One Animated.Value per mount. The Animated.View leaf commits its current value every frame,
+    // so timing it animates the real view.
+    const opacity = useRef(new Animated.Value(restingOpacity)).current;
     // The shared press-scheduling cell (delayPressIn timer + activation clock), held across renders.
     const runtime = useRef(createTouchableFeedbackRuntime()).current;
     function setOpacityTo(toValue, duration) {
+        // useNativeDriver: true is RN's own (TouchableOpacity.js:242). opacity is natively drivable
+        // and the fade then survives a busy JS thread, which is the whole point of the feedback.
         Animated.timing(opacity, {
             toValue,
             duration,
             easing: Animated.Easing.inOut(Animated.Easing.quad),
-            useNativeDriver: false,
+            useNativeDriver: true,
         }).start();
     }
+    // RN's componentDidUpdate: a changed `disabled` or a changed style opacity re-settles the view,
+    // so a Touchable disabled mid-press does not stay stuck at its active opacity.
+    const hasRendered = useRef(false);
+    useEffect(() => {
+        // RN runs this on UPDATE only. Firing at mount would animate over the value the
+        // Animated.Value was just constructed with.
+        if (!hasRendered.current) {
+            hasRendered.current = true;
+            return;
+        }
+        setOpacityTo(restingOpacity, OPACITY_INACTIVE_DURATION_MS);
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- setOpacityTo is re-made per render
+    }, [disabled, restingOpacity]);
+    // RN's componentWillUnmount: stop the fade so a teardown mid-animation leaves no driver running
+    // against a node that is gone.
+    useEffect(() => () => {
+        opacity.resetAnimation();
+    }, [opacity]);
     // The shared machine owns the delayPressIn/minPressDuration scheduling; the adapter supplies only
     // the native seam — the Animated opacity fade + the framework emit — as activate/deactivate.
-    const { handlePressIn, handlePressOut } = createTouchableFeedbackHandlers({ delayPressIn, delayPressOut, minPressDuration, schedule: scheduleTimeout, now: Date.now }, runtime, {
+    const { handlePressIn, handlePressOut } = createTouchableFeedbackHandlers({
+        delayPressIn,
+        delayPressOut,
+        minPressDuration,
+        schedule: scheduleTimeout,
+        now: Date.now,
+    }, runtime, {
         activate(event) {
-            setOpacityTo(activeOpacity, OPACITY_ACTIVE_DURATION_MS);
+            setOpacityTo(activeOpacity, OPACITY_ACTIVE_GRANT_DURATION_MS);
             onPressIn?.(event);
         },
         deactivate(event) {
-            setOpacityTo(RESTING_OPACITY, OPACITY_INACTIVE_DURATION_MS);
+            setOpacityTo(restingOpacity, OPACITY_INACTIVE_DURATION_MS);
             onPressOut?.(event);
         },
     });
-    return createElement(Pressable, { ...rest, onPressIn: handlePressIn, onPressOut: handlePressOut }, createElement(Animated.View, { style: [style, { opacity }], className }, children));
+    return createElement(Pressable, { ...rest, disabled, onPressIn: handlePressIn, onPressOut: handlePressOut }, createElement(Animated.View, { style: [style, { opacity }], className }, children));
 };
+// RN's render: the lowered opacity is cloned onto the CHILD while the container keeps an opaque
+// underlay (TouchableHighlight.js). Fold both onto the container instead and the opacity fades the
+// very underlay it is meant to reveal — `underlayColor: 'black'` paints grey. React is the one
+// adapter that can reach the child without a wrapper view perturbing the flex chain.
+// A non-element child (text, a fragment, nothing at all) has no style prop to compose onto, so it
+// passes through untouched rather than throwing the way RN's Children.only would.
+function withChildStyle(children, extra) {
+    const child = Children.count(children) === 1 ? children : undefined;
+    if (!isValidElement(child))
+        return children;
+    return cloneElement(child, { style: [child.props.style, extra] });
+}
 export const TouchableHighlight = props => {
-    const { activeOpacity = DEFAULT_HIGHLIGHT_CHILD_OPACITY, underlayColor = DEFAULT_UNDERLAY_COLOR, style, children, ...rest } = props;
-    function pressedStyle({ pressed }) {
-        return highlightPressedStyle(pressed, style, underlayColor, activeOpacity);
+    const { activeOpacity, underlayColor, style, children, onPress, onPressIn, onPressOut, onShowUnderlay, onHideUnderlay, delayPressOut = 0, ...rest } = props;
+    // `shown` is NOT `pressed`: RN holds the underlay for delayPressOut past the tap so a press too
+    // fast to see still flashes, and the pressed flag is already false by then.
+    const [shown, setShown] = useState(false);
+    const runtime = useRef(createHighlightUnderlayRuntime()).current;
+    // RN's _hasPressHandler gate: no press handler, no underlay. onLongPress is only READ here —
+    // it stays in `rest` for Pressable to fire directly.
+    const hasPressHandler = hasTouchablePressHandler({
+        onPress,
+        onPressIn,
+        onPressOut,
+        onLongPress: rest.onLongPress,
+    });
+    const underlay = createHighlightUnderlayHandlers({ delayPressOut, hasPressHandler, schedule: scheduleTimeout }, runtime, { setShown, onShowUnderlay, onHideUnderlay });
+    const extraStyles = resolveHighlightExtraStyles({
+        shown,
+        hasPressHandler,
+        underlayColor,
+        activeOpacity,
+    });
+    // Visual first, then the caller's callback — RN's order in _createPressabilityConfig.
+    function handlePressIn(event) {
+        underlay.handlePressIn(event);
+        onPressIn?.(event);
+    }
+    function handlePress(event) {
+        underlay.handlePress(event);
+        onPress?.(event);
     }
-    return createElement(Pressable, { ...rest, style: pressedStyle }, children);
+    function handlePressOut(event) {
+        underlay.handlePressOut(event);
+        onPressOut?.(event);
+    }
+    return createElement(Pressable, {
+        ...rest,
+        style: extraStyles === undefined ? style : [style, extraStyles.underlay],
+        onPress: handlePress,
+        onPressIn: handlePressIn,
+        onPressOut: handlePressOut,
+    }, extraStyles === undefined
+        ? children
+        : withChildStyle(children, extraStyles.child));
 };
 export const TouchableWithoutFeedback = props => {
-    const { children, ...rest } = props;
-    return createElement(Pressable, rest, children);
+    const { children, onPressIn, onPressOut, delayPressIn = 0, delayPressOut = 0, minPressDuration = TOUCHABLE_MIN_PRESS_DURATION_MS, ...rest } = props;
+    // RN's TouchableWithoutFeedback builds a FULL Pressability config with delayPressIn /
+    // delayPressOut / minPressDuration: 0 — the same shared machine TouchableOpacity uses, with the
+    // visual half left empty. Spreading the delay props onto Pressable instead did nothing: it does
+    // not read them, and they leaked to the host as unknown props.
+    const runtime = useRef(createTouchableFeedbackRuntime()).current;
+    const { handlePressIn, handlePressOut } = createTouchableFeedbackHandlers({
+        delayPressIn,
+        delayPressOut,
+        minPressDuration,
+        schedule: scheduleTimeout,
+        now: Date.now,
+    }, runtime, {
+        activate(event) {
+            onPressIn?.(event);
+        },
+        deactivate(event) {
+            onPressOut?.(event);
+        },
+    });
+    return createElement(Pressable, { ...rest, onPressIn: handlePressIn, onPressOut: handlePressOut }, children);
 };

package/build/components/touchable-native-feedback/index.js

@@ -10,7 +10,7 @@ import { createElement } from 'react';
 import { dlog } from '@symbiote-native/engine';
 import { backgroundProps, canUseNativeForeground, rippleBackground, selectableBackground, selectableBackgroundBorderless, } from '@symbiote-native/components';
 import { View } from '../../components.js';
-import { Pressable } from '../pressable/index.js';
+import { TouchablePressable as Pressable, } from '../pressable/index.js';
 const TouchableNativeFeedbackImpl = props => {
     const { background, useForeground = false, children, ...rest } = props;
     // RN defaults a missing background to SelectableBackground() so the touchable always has

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

@@ -18,9 +18,9 @@
 // scrollTo command via its handle ref, animated by default. The `contentOffset` prop is only a
 // fallback for the pre-mount window (handle not yet attached).
 import { createElement, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useReducer, useRef, useState, } from 'react';
-import { dlog } from '@symbiote-native/engine';
-import { DEFAULT_END_REACHED_THRESHOLD, DEFAULT_INITIAL_NUM_TO_RENDER, DEFAULT_MAX_TO_RENDER_PER_BATCH, DEFAULT_START_REACHED_THRESHOLD, DEFAULT_UPDATE_CELLS_BATCHING_PERIOD, DEFAULT_WINDOW_SIZE, EMPTY_OFFSET, FIRST_INDEX, INVERTED_X_STYLE, INVERTED_Y_STYLE, buildListPlan, buildViewabilityPairs, createInitialListState, isSeparatorGapInRange, listEffectSignature, readLayoutLength, readScrollOffset, reduceList, resolveItemKey, } from '@symbiote-native/components';
-import { ScrollView } from '../scroll-view';
+import { dlog, } from '@symbiote-native/engine';
+import { DEFAULT_END_REACHED_THRESHOLD, DEFAULT_INITIAL_NUM_TO_RENDER, DEFAULT_MAX_TO_RENDER_PER_BATCH, DEFAULT_START_REACHED_THRESHOLD, DEFAULT_UPDATE_CELLS_BATCHING_PERIOD, DEFAULT_WINDOW_SIZE, EMPTY_OFFSET, FIRST_INDEX, INVERTED_X_STYLE, INVERTED_Y_STYLE, buildListPlan, buildViewabilityPairs, createInitialListState, isSeparatorGapInRange, listEffectSignature, readLayoutLength, readLayoutOffset, readScrollOffset, reduceList, resolveItemKey, } from '@symbiote-native/components';
+import { ScrollView, } from '../scroll-view';
 import { RefreshControl } from '../refresh-control/index.js';
 function resolveElement(component) {
     if (component === undefined)
@@ -88,7 +88,12 @@ export function VirtualizedList(props) {
         onScrollToIndexFailed,
         viewabilityPairs,
     });
-    handlersRef.current = { onEndReached, onStartReached, onScrollToIndexFailed, viewabilityPairs };
+    handlersRef.current = {
+        onEndReached,
+        onStartReached,
+        onScrollToIndexFailed,
+        viewabilityPairs,
+    };
     // The one folded state cell (RN's scattered refs collapsed into IListState). Lazily created once.
     const stateRef = useRef(null);
     const state = (stateRef.current ??= createInitialListState());
@@ -109,7 +114,9 @@ export function VirtualizedList(props) {
     const scrollToPixel = useCallback((offset, animated) => {
         const clamped = Math.max(EMPTY_OFFSET, offset);
         const isHorizontal = inputsRef.current.horizontal;
-        const target = isHorizontal ? { x: clamped, y: EMPTY_OFFSET } : { x: EMPTY_OFFSET, y: clamped };
+        const target = isHorizontal
+            ? { x: clamped, y: EMPTY_OFFSET }
+            : { x: EMPTY_OFFSET, y: clamped };
         if (scrollViewRef.current !== null) {
             dlog(`VirtualizedList scrollTo offset=${clamped} animated=${animated} (horizontal=${isHorizontal})`);
             scrollViewRef.current.scrollTo({ x: target.x, y: target.y, animated });
@@ -129,10 +136,14 @@ export function VirtualizedList(props) {
                     scrollToPixel(effect.offset, effect.animated);
                     break;
                 case 'fire-end-reached':
-                    handlers.onEndReached?.({ distanceFromEnd: effect.distanceFromEnd });
+                    handlers.onEndReached?.({
+                        distanceFromEnd: effect.distanceFromEnd,
+                    });
                     break;
                 case 'fire-start-reached':
-                    handlers.onStartReached?.({ distanceFromStart: effect.distanceFromStart });
+                    handlers.onStartReached?.({
+                        distanceFromStart: effect.distanceFromStart,
+                    });
                     break;
                 case 'fire-scroll-to-index-failed':
                     handlers.onScrollToIndexFailed?.({
@@ -217,8 +228,9 @@ export function VirtualizedList(props) {
         const length = readLayoutLength(event, horizontal);
         if (length === undefined)
             return;
-        dlog(`VirtualizedList cell ${index} measured length=${length}`);
-        dispatch({ kind: 'measure', index, length });
+        const offset = readLayoutOffset(event, horizontal);
+        dlog(`VirtualizedList cell ${index} measured length=${length} offset=${offset ?? 'none'}`);
+        dispatch({ kind: 'measure', index, length, offset });
     }, [horizontal, dispatch]);
     // Merge an override onto the separator at a given gap and request a re-render. A gap index
     // outside [0, count-2] has no separator, so the write is a no-op (RN bails the same way).
@@ -313,7 +325,9 @@ export function VirtualizedList(props) {
     // extraData) already re-renders and re-runs renderItem. Voided to mark the deliberate no-op.
     void extraData;
     const children = [];
-    const stickySet = stickyHeaderIndices !== undefined ? new Set(stickyHeaderIndices) : undefined;
+    const stickySet = stickyHeaderIndices !== undefined
+        ? new Set(stickyHeaderIndices)
+        : undefined;
     let renderedStickyIndices = [];
     const header = resolveElement(ListHeaderComponent);
     if (header !== undefined) {
@@ -337,13 +351,14 @@ export function VirtualizedList(props) {
             keyFor: keyForIndex,
             stickyIndices: stickySet,
             hasHeader: header !== undefined,
-            hasSeparators: ItemSeparatorComponent !== undefined,
         });
         renderedStickyIndices = plan.stickyChildPositions;
         if (plan.leadingExtent > EMPTY_OFFSET) {
             children.push(createElement('symbiote-view', {
                 key: 'spacer-leading',
-                style: horizontal ? { width: plan.leadingExtent } : { height: plan.leadingExtent },
+                style: horizontal
+                    ? { width: plan.leadingExtent }
+                    : { height: plan.leadingExtent },
             }));
         }
         // The force-mounted sticky cell (RN _ensureClosestStickyHeader): the nearest sticky index
@@ -362,13 +377,19 @@ export function VirtualizedList(props) {
             children.push(createElement('symbiote-view', {
                 key: `cell-${plan.forcedStickyCell.key}`,
                 onLayout: makeCellMeasure(forcedIndex),
-                style: inverted ? (horizontal ? INVERTED_X_STYLE : INVERTED_Y_STYLE) : undefined,
+                style: inverted
+                    ? horizontal
+                        ? INVERTED_X_STYLE
+                        : INVERTED_Y_STYLE
+                    : undefined,
             }, forcedCell));
         }
         if (plan.gapExtent > EMPTY_OFFSET) {
             children.push(createElement('symbiote-view', {
                 key: 'spacer-gap',
-                style: horizontal ? { width: plan.gapExtent } : { height: plan.gapExtent },
+                style: horizontal
+                    ? { width: plan.gapExtent }
+                    : { height: plan.gapExtent },
             }));
         }
         for (const planCell of plan.cells) {
@@ -379,24 +400,42 @@ export function VirtualizedList(props) {
                 index: planCell.index,
                 separators: makeSeparators(planCell.index),
             });
+            // RN renders the separator INSIDE the cell's own measuring wrapper
+            // (VirtualizedListCellRenderer.js:218-221), and that placement is load-bearing rather than
+            // cosmetic. As a SIBLING it is an extra flex child, so the chrome between two cells becomes
+            // gap + separator + gap while a spacer collapsing that region replaces it with one gap — the
+            // leading spacer then lands every cell below it short by (separator + gap), and the content
+            // visibly jumps by that amount each time the window's first index moves. Measured at exactly
+            // 17px on device 2026-08-19 (a 1px divider under a 16px container gap); see
+            // .claude/rules/list-geometry-feedback-loop.md. Inside the wrapper it is part of the cell's
+            // measured length instead, and every cell stays exactly one child.
+            const separator = 
+            // RN gates the separator on the last index of the DATA, not of the WINDOW
+            // (VirtualizedList.js:793 `const end = getItemCount(data) - 1`), and now that the separator
+            // lives INSIDE the measuring wrapper that distinction is load-bearing: gating on the window
+            // would make a cell's own measured height change as the window slides past it. Device-measured
+            // 2026-08-19 as a run of cells all shifting by exactly the divider's 1px.
+            planCell.index < count - 1
+                ? renderSeparatorElement(ItemSeparatorComponent, item, getItem(data, planCell.index + 1), separatorOverridesRef.current.get(planCell.index))
+                : undefined;
             // Wrap each cell in a measuring View. When inverted, each cell carries the counter-flip so
             // its content reads upright inside the flipped content container.
             children.push(createElement('symbiote-view', {
                 key: `cell-${planCell.key}`,
                 onLayout: makeCellMeasure(planCell.index),
-                style: inverted ? (horizontal ? INVERTED_X_STYLE : INVERTED_Y_STYLE) : undefined,
-            }, cell));
-            const separator = planCell.index < last
-                ? renderSeparatorElement(ItemSeparatorComponent, item, getItem(data, planCell.index + 1), separatorOverridesRef.current.get(planCell.index))
-                : undefined;
-            if (separator !== undefined) {
-                children.push(createElement('symbiote-view', { key: `sep-${planCell.key}` }, separator));
-            }
+                style: inverted
+                    ? horizontal
+                        ? INVERTED_X_STYLE
+                        : INVERTED_Y_STYLE
+                    : undefined,
+            }, cell, separator));
         }
         if (plan.trailingExtent > EMPTY_OFFSET) {
             children.push(createElement('symbiote-view', {
                 key: 'spacer-trailing',
-                style: horizontal ? { width: plan.trailingExtent } : { height: plan.trailingExtent },
+                style: horizontal
+                    ? { width: plan.trailingExtent }
+                    : { height: plan.trailingExtent },
             }));
         }
     }
@@ -448,7 +487,8 @@ export function VirtualizedList(props) {
     if (maintainVisibleContentPosition !== undefined) {
         scrollProps.maintainVisibleContentPosition = {
             ...maintainVisibleContentPosition,
-            minIndexForVisible: maintainVisibleContentPosition.minIndexForVisible + (header !== undefined ? 1 : 0),
+            minIndexForVisible: maintainVisibleContentPosition.minIndexForVisible +
+                (header !== undefined ? 1 : 0),
         };
     }
     // Pull-to-refresh: when onRefresh is set, build a RefreshControl for the ScrollView's

package/build/components/virtualized-section-list/index.d.ts

@@ -22,6 +22,11 @@ export interface IVirtualizedSectionListProps<ItemT> extends IAccessibilityProps
     }) => ReactNode;
     SectionSeparatorComponent?: ComponentType<Record<string, never>> | ReactElement;
     keyExtractor?: (item: ItemT, index: number) => string;
+    getItemLayout?: (data: ReadonlyArray<ISection<ItemT>> | null, index: number) => {
+        length: number;
+        offset: number;
+        index: number;
+    };
     stickySectionHeadersEnabled?: boolean;
     extraData?: unknown;
     ItemSeparatorComponent?: ComponentType<ISeparatorProps<ItemT>>;