@symbiote-native/vue 0.3.8 → 0.5.0

package/build/components/touchable.d.ts

@@ -12,6 +12,10 @@ export interface ITouchableHighlightProps extends ITouchableBaseProps {
     underlayColor?: string;
 }
 export type ITouchableWithoutFeedbackProps = ITouchableBaseProps;
+export type ITouchableHighlightEmits = IPressableEmits & {
+    showUnderlay: () => boolean;
+    hideUnderlay: () => boolean;
+};
 export declare const TouchableOpacity: import("vue").DefineSetupFnComponent<ITouchableOpacityProps, IPressableEmits, {}, ITouchableOpacityProps & {
     onPress?: ((event: ISymbioteEvent) => any) | undefined;
     onPressIn?: ((event: ISymbioteEvent) => any) | undefined;
@@ -21,7 +25,7 @@ export declare const TouchableOpacity: import("vue").DefineSetupFnComponent<ITou
     onHoverIn?: ((event: ISymbioteEvent) => any) | undefined;
     onHoverOut?: ((event: ISymbioteEvent) => any) | undefined;
 }, import("vue").PublicProps>;
-export declare const TouchableHighlight: import("vue").DefineSetupFnComponent<ITouchableHighlightProps, IPressableEmits, {}, ITouchableHighlightProps & {
+export declare const TouchableHighlight: import("vue").DefineSetupFnComponent<ITouchableHighlightProps, ITouchableHighlightEmits, {}, ITouchableHighlightProps & {
     onPress?: ((event: ISymbioteEvent) => any) | undefined;
     onPressIn?: ((event: ISymbioteEvent) => any) | undefined;
     onPressOut?: ((event: ISymbioteEvent) => any) | undefined;
@@ -29,6 +33,8 @@ export declare const TouchableHighlight: import("vue").DefineSetupFnComponent<IT
     onLongPress?: ((event: ISymbioteEvent) => any) | undefined;
     onHoverIn?: ((event: ISymbioteEvent) => any) | undefined;
     onHoverOut?: ((event: ISymbioteEvent) => any) | undefined;
+    onShowUnderlay?: (() => any) | undefined;
+    onHideUnderlay?: (() => any) | undefined;
 }, import("vue").PublicProps>;
 export declare const TouchableWithoutFeedback: import("vue").DefineSetupFnComponent<ITouchableBaseProps, IPressableEmits, {}, Omit<IPressableProps, "style"> & IPressTimingProps & {
     style?: IStyleProp<IViewStyle>;

package/build/components/touchable.js

@@ -1,26 +1,35 @@
-// The Touchable* family for Vue, all built on Pressable, the Vue twin of the React adapter. The
-// press-timing constants and the deactivation-floor math are shared with React
-// (@symbiote-native/components/state/touchable); here Vue owns only the Animated wiring + the press
-// scheduling state:
-//   TouchableOpacity: animate an Animated.Value opacity toward activeOpacity on press-in, back
-//     to 1 on press-out, driven from Pressable's onPressIn/onPressOut.
-//   TouchableHighlight: paint underlayColor + lower child opacity while pressed, via Pressable's
-//     style-as-function (the pressed state RN drives with setState).
-//   TouchableWithoutFeedback: no visual change, just the press wiring.
+// The Touchable* family for Vue, 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 shared by the React/Vue/Svelte/Angular ports; Solid migrated first, this is Vue.
+//
+// Shared (framework-agnostic) half: the press-scheduling machine, the underlay machine, the
+// resting-opacity math, the press-handler gate, the extra-style split. Vue owns only the
+// lifecycle — refs, the real timers, the Animated wiring, and the emit bridge:
+//   TouchableOpacity: an Animated.Value fading toward activeOpacity on press-in and back to the
+//     style's own opacity on press-out.
+//   TouchableHighlight: the underlay machine flipping a `shown` ref; underlayColor lands on the
+//     container, the lowered opacity on the cloned child.
+//   TouchableWithoutFeedback: the same press-scheduling machine with the visual half empty.
 //
 // Inputs arrive as attrs (untyped), narrowed with runtime guards. The handlers read attrs LIVE
 // (they fire on events, not render) so a re-supplied callback / timing is always honored.
-import { defineComponent, h } from '@vue/runtime-core';
-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 {} from '@symbiote-native/engine';
+import { cloneVNode, defineComponent, getCurrentInstance, h, onUnmounted, ref, watch, } from '@vue/runtime-core';
+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 { dlog, } from '@symbiote-native/engine';
 import { Pressable, emitPressableEvents, PRESSABLE_EMITS, } from './pressable.js';
 import { Animated } from '../modules/animated/index.js';
 import { normalizeVueAttrs } from '../utils/normalize-attrs.js';
+const TOUCHABLE_HIGHLIGHT_EMITS = {
+    ...PRESSABLE_EMITS,
+    showUnderlay: () => true,
+    hideUnderlay: () => true,
+};
 function numberOr(value, fallback) {
     return typeof value === 'number' ? value : fallback;
 }
-// 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 their deferred activation/deactivation/underlay
+// hide 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);
@@ -44,20 +53,41 @@ const TOUCHABLE_OPACITY_HANDLED = [
     'minPressDuration',
 ];
 export const TouchableOpacity = defineComponent((_props, { slots, attrs: rawAttrs, emit }) => {
-    // One Animated.Value per mount, resting at full opacity. Held by identity in setup scope (an
-    // engine object, never a reactive ref). The Animated.View leaf commits it every frame.
-    const opacity = new Animated.Value(RESTING_OPACITY);
+    // RN's _getChildStyleOpacityWithDefault: the fade settles at the opacity the CALLER's style
+    // asks for, not at a hard 1 — and the Animated.Value is SEEDED there, or the first paint jumps
+    // to fully opaque on a Touchable styled `opacity: 0.6`.
+    const restingOpacity = () => restingOpacityFromStyle(normalizeVueAttrs(rawAttrs).style);
+    // One Animated.Value per mount. Held by identity in setup scope (an engine object, never a
+    // reactive ref — a Proxy would miss the graph's bookkeeping). The Animated.View leaf commits
+    // it every frame.
+    const opacity = new Animated.Value(restingOpacity());
     // The shared press-scheduling cell (delayPressIn timer + activation clock), persisted across
     // renders in setup scope; the handlers are rebuilt each render over live attrs.
     const runtime = createTouchableFeedbackRuntime();
     function setOpacityTo(toValue, duration) {
+        dlog(`TouchableOpacity opacity -> ${toValue} over ${duration}ms`);
+        // useNativeDriver: true is RN's own (TouchableOpacity.js:242). opacity is natively drivable,
+        // so the fade survives a busy JS thread — the whole point of press 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. NO `immediate` —
+    // RN does this on UPDATE only, and firing at mount would animate over the value the
+    // Animated.Value was just seeded with. Two getter sources, not one object: Vue compares an
+    // array source element-wise, so an unrelated attr change does not re-settle the opacity.
+    watch([() => normalizeVueAttrs(rawAttrs).disabled, restingOpacity], ([, resting]) => {
+        setOpacityTo(resting, OPACITY_INACTIVE_DURATION_MS);
+    });
+    // RN's componentWillUnmount: stop the animation and drop the value back, so a teardown
+    // mid-fade leaves no driver running against a node that is gone.
+    onUnmounted(() => {
+        opacity.resetAnimation();
+    });
     return () => {
         const attrs = normalizeVueAttrs(rawAttrs);
         const style = attrs.style;
@@ -66,16 +96,18 @@ export const TouchableOpacity = defineComponent((_props, { slots, attrs: rawAttr
         const { handlePressIn, handlePressOut } = createTouchableFeedbackHandlers({
             delayPressIn: numberOr(attrs.delayPressIn, 0),
             delayPressOut: numberOr(attrs.delayPressOut, 0),
-            minPressDuration: numberOr(attrs.minPressDuration, DEFAULT_MIN_PRESS_DURATION_MS),
+            // RN's Touchables override Pressability's 130ms floor with 0; what holds the active
+            // visual is the fade's own duration, not a press-duration floor.
+            minPressDuration: numberOr(attrs.minPressDuration, TOUCHABLE_MIN_PRESS_DURATION_MS),
             schedule: scheduleTimeout,
             now: Date.now,
         }, runtime, {
             activate(event) {
-                setOpacityTo(numberOr(attrs.activeOpacity, DEFAULT_ACTIVE_OPACITY), OPACITY_ACTIVE_DURATION_MS);
+                setOpacityTo(numberOr(attrs.activeOpacity, DEFAULT_ACTIVE_OPACITY), OPACITY_ACTIVE_GRANT_DURATION_MS);
                 emit('pressIn', event);
             },
             deactivate(event) {
-                setOpacityTo(RESTING_OPACITY, OPACITY_INACTIVE_DURATION_MS);
+                setOpacityTo(restingOpacity(), OPACITY_INACTIVE_DURATION_MS);
                 emit('pressOut', event);
             },
         });
@@ -94,34 +126,150 @@ export const TouchableOpacity = defineComponent((_props, { slots, attrs: rawAttr
     inheritAttrs: false,
     emits: PRESSABLE_EMITS,
 });
-const TOUCHABLE_HIGHLIGHT_HANDLED = ['activeOpacity', 'underlayColor', 'style'];
+// delayPressOut is CONSUMED here (the underlay hold), so it must not also forward to the host.
+// onPress/onPressIn/onPressOut/onShowUnderlay/onHideUnderlay never appear in attrs at all — they
+// are declared emits, which Vue strips from $attrs.
+const TOUCHABLE_HIGHLIGHT_HANDLED = [
+    'activeOpacity',
+    'underlayColor',
+    'style',
+    'delayPressOut',
+];
+// A vnode that can carry a style prop: a host tag (string) or a component (object/function).
+// Fragment / Text / Comment / Static are Symbols and fail all three — cloning one with a style
+// would silently drop it.
+function isStylableVNode(vnode) {
+    const type = vnode.type;
+    return (typeof type === 'string' ||
+        typeof type === 'function' ||
+        (typeof type === 'object' && type !== null));
+}
 export const TouchableHighlight = defineComponent((_props, { slots, attrs: rawAttrs, emit }) => {
+    // `shown` is NOT `pressed`: RN holds the underlay for delayPressOut past the tap so a fast tap
+    // still flashes, and the pressed flag is already false by then.
+    const shown = ref(false);
+    // The mutable underlay cell (the in-flight hide canceller). A plain setup-scope object, never
+    // a ref: the machine mutates it on every event and nothing reads it reactively.
+    const runtime = createHighlightUnderlayRuntime();
+    // The press callbacks are declared emits, so Vue has stripped their onX listeners from $attrs.
+    // RN's _hasPressHandler gate therefore reads what the PARENT actually passed, off the
+    // instance's own vnode props — the same shape FlatList/VirtualizedList use for this.
+    const instance = getCurrentInstance();
+    const listener = (onName) => {
+        const vnodeProps = instance?.vnode.props;
+        return vnodeProps == null ? undefined : vnodeProps[onName];
+    };
     return () => {
         const attrs = normalizeVueAttrs(rawAttrs);
-        const activeOpacity = numberOr(attrs.activeOpacity, DEFAULT_HIGHLIGHT_CHILD_OPACITY);
-        const underlayColor = typeof attrs.underlayColor === 'string' ? attrs.underlayColor : DEFAULT_UNDERLAY_COLOR;
-        const style = attrs.style;
-        function pressedStyle({ pressed }) {
-            return highlightPressedStyle(pressed, style, underlayColor, activeOpacity);
-        }
+        const hasPressHandler = hasTouchablePressHandler({
+            onPress: listener('onPress'),
+            onPressIn: listener('onPressIn'),
+            onPressOut: listener('onPressOut'),
+            onLongPress: listener('onLongPress'),
+        });
+        // Rebuilt each render over live attrs; the runtime persists, so an in-flight hide timer
+        // survives a rebuild.
+        const underlay = createHighlightUnderlayHandlers({
+            delayPressOut: numberOr(attrs.delayPressOut, 0),
+            hasPressHandler,
+            schedule: scheduleTimeout,
+        }, runtime, {
+            setShown: next => {
+                shown.value = next;
+            },
+            onShowUnderlay: () => emit('showUnderlay'),
+            onHideUnderlay: () => emit('hideUnderlay'),
+        });
+        const extra = resolveHighlightExtraStyles({
+            shown: shown.value,
+            hasPressHandler,
+            underlayColor: typeof attrs.underlayColor === 'string'
+                ? attrs.underlayColor
+                : undefined,
+            activeOpacity: typeof attrs.activeOpacity === 'number'
+                ? attrs.activeOpacity
+                : undefined,
+        });
+        const children = slots.default !== undefined ? slots.default() : [];
+        // RN's _createExtraStyles split: the backgroundColor on the CONTAINER, the lowered opacity
+        // on the CHILD (TouchableHighlight.js clones its single child). Vue can reach the child
+        // without a wrapper node — cloneVNode merges the style onto exactly one existing vnode, so
+        // nothing is inserted into the flex chain. It needs RN's own single-element-child shape
+        // though (React.Children.only): a fragment, a raw text node or several roots have no one
+        // child to clone, and there both styles fold onto the container — the pre-audit
+        // approximation, where the opacity fades the very underlay it should reveal.
+        const onlyChild = children.length === 1 && children[0] !== undefined
+            ? children[0]
+            : undefined;
+        const canStyleChild = onlyChild !== undefined && isStylableVNode(onlyChild);
+        const styledChildren = extra !== undefined && canStyleChild && onlyChild !== undefined
+            ? [cloneVNode(onlyChild, { style: extra.child })]
+            : children;
+        const containerStyle = extra === undefined
+            ? attrs.style
+            : canStyleChild
+                ? [attrs.style, extra.underlay]
+                : [attrs.style, extra.underlay, extra.child];
         const pressableProps = {
             ...forwardExcept(attrs, TOUCHABLE_HIGHLIGHT_HANDLED),
             ...emitPressableEvents(emit),
-            style: pressedStyle,
+            style: containerStyle,
+            // Visual first, then the caller's callback — RN's order in _createPressabilityConfig.
+            onPress: (event) => {
+                underlay.handlePress(event);
+                emit('press', event);
+            },
+            onPressIn: (event) => {
+                underlay.handlePressIn(event);
+                emit('pressIn', event);
+            },
+            onPressOut: (event) => {
+                underlay.handlePressOut(event);
+                emit('pressOut', event);
+            },
         };
-        const children = slots.default !== undefined ? slots.default() : [];
-        return h(Pressable, pressableProps, { default: () => children });
+        return h(Pressable, pressableProps, { default: () => styledChildren });
     };
 }, {
     name: 'TouchableHighlight',
     inheritAttrs: false,
-    emits: PRESSABLE_EMITS,
+    emits: TOUCHABLE_HIGHLIGHT_EMITS,
 });
+// RN's TouchableWithoutFeedback builds a FULL Pressability config — "without feedback" means no
+// VISUAL, not no timing — so the delay props are consumed by the shared machine here instead of
+// forwarding to the host as unknown Fabric props.
+const TOUCHABLE_WITHOUT_FEEDBACK_HANDLED = [
+    'delayPressIn',
+    'delayPressOut',
+    'minPressDuration',
+];
 export const TouchableWithoutFeedback = defineComponent((_props, { slots, attrs: rawAttrs, emit }) => {
+    const runtime = createTouchableFeedbackRuntime();
     return () => {
         const attrs = normalizeVueAttrs(rawAttrs);
+        // The same machine TouchableOpacity runs, with the visual half left empty.
+        const { handlePressIn, handlePressOut } = createTouchableFeedbackHandlers({
+            delayPressIn: numberOr(attrs.delayPressIn, 0),
+            delayPressOut: numberOr(attrs.delayPressOut, 0),
+            minPressDuration: numberOr(attrs.minPressDuration, TOUCHABLE_MIN_PRESS_DURATION_MS),
+            schedule: scheduleTimeout,
+            now: Date.now,
+        }, runtime, {
+            activate(event) {
+                emit('pressIn', event);
+            },
+            deactivate(event) {
+                emit('pressOut', event);
+            },
+        });
+        const pressableProps = {
+            ...forwardExcept(attrs, TOUCHABLE_WITHOUT_FEEDBACK_HANDLED),
+            ...emitPressableEvents(emit),
+            onPressIn: handlePressIn,
+            onPressOut: handlePressOut,
+        };
         const children = slots.default !== undefined ? slots.default() : [];
-        return h(Pressable, { ...attrs, ...emitPressableEvents(emit) }, { default: () => children });
+        return h(Pressable, pressableProps, { default: () => children });
     };
 }, {
     name: 'TouchableWithoutFeedback',

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

@@ -27,7 +27,7 @@
 // scroll commands would silently no-op. The folded listState is a PLAIN object (not reactive) —
 // mutating it never triggers Vue; the `version` ref is bumped when a transition changes render state.
 import { computed, defineComponent, getCurrentInstance, h, isVNode, onBeforeUnmount, ref, shallowRef, watch, } from '@vue/runtime-core';
-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 { 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 { dlog, } from '@symbiote-native/engine';
 import { ScrollView } from '../scroll-view';
 import { RefreshControl } from '../refresh-control.js';
@@ -78,7 +78,7 @@ function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 function isComponent(value) {
-    return typeof value === 'function' || (typeof value === 'object' && value !== null);
+    return (typeof value === 'function' || (typeof value === 'object' && value !== null));
 }
 function asNumber(value, fallback) {
     return typeof value === 'number' ? value : fallback;
@@ -181,7 +181,9 @@ export const VirtualizedList = defineComponent((props, { attrs, expose, emit, sl
                 ? (info) => emit('startReached', info)
                 : undefined,
             onStartReachedThreshold: asNumber(props.onStartReachedThreshold, DEFAULT_START_REACHED_THRESHOLD),
-            onRefresh: listens('onRefresh') ? () => emit('refresh') : undefined,
+            onRefresh: listens('onRefresh')
+                ? () => emit('refresh')
+                : undefined,
             refreshing: props.refreshing === true,
             progressViewOffset: props.progressViewOffset,
             onViewableItemsChanged: listens('onViewableItemsChanged')
@@ -351,13 +353,17 @@ export const VirtualizedList = defineComponent((props, { attrs, expose, emit, sl
         const length = readLayoutLength(event, narrowed.value.horizontal);
         if (length === undefined)
             return;
-        dlog(`Vue VirtualizedList cell ${index} measured length=${length}`);
-        dispatch({ kind: 'measure', index, length });
+        const offset = readLayoutOffset(event, narrowed.value.horizontal);
+        dlog(`Vue VirtualizedList cell ${index} measured length=${length} offset=${offset ?? 'none'}`);
+        dispatch({ kind: 'measure', index, length, offset });
     };
     const mergeSeparator = (gapIndex, patch) => {
         if (!isSeparatorGapInRange(gapIndex, listState.metrics.count))
             return;
-        separatorOverrides.set(gapIndex, { ...separatorOverrides.get(gapIndex), ...patch });
+        separatorOverrides.set(gapIndex, {
+            ...separatorOverrides.get(gapIndex),
+            ...patch,
+        });
         separatorVersion.value += 1;
     };
     const makeSeparators = (index) => ({
@@ -440,7 +446,9 @@ export const VirtualizedList = defineComponent((props, { attrs, expose, emit, sl
         dlog(`Vue VirtualizedList window [${m.first}, ${m.last}] of ${m.count} ` +
             `(offset=${listState.scrollOffset}, viewport=${listState.viewportLength}, rendered=${Math.max(0, m.last - m.first + 1)})`);
         const children = [];
-        const stickySet = p.stickyHeaderIndices !== undefined ? new Set(p.stickyHeaderIndices) : undefined;
+        const stickySet = p.stickyHeaderIndices !== undefined
+            ? new Set(p.stickyHeaderIndices)
+            : undefined;
         const header = resolveElement(p.listHeaderComponent);
         if (header !== undefined) {
             children.push(h('symbiote-view', { key: 'list-header' }, [header]));
@@ -463,13 +471,14 @@ export const VirtualizedList = defineComponent((props, { attrs, expose, emit, sl
                 keyFor,
                 stickyIndices: stickySet,
                 hasHeader: header !== undefined,
-                hasSeparators: p.itemSeparatorComponent !== undefined,
             });
             renderedStickyIndices = plan.stickyChildPositions;
             if (plan.leadingExtent > EMPTY_OFFSET) {
                 children.push(h('symbiote-view', {
                     key: 'spacer-leading',
-                    style: p.horizontal ? { width: plan.leadingExtent } : { height: plan.leadingExtent },
+                    style: p.horizontal
+                        ? { width: plan.leadingExtent }
+                        : { height: plan.leadingExtent },
                 }));
             }
             const cellInverted = p.inverted
@@ -477,26 +486,55 @@ export const VirtualizedList = defineComponent((props, { attrs, expose, emit, sl
                     ? INVERTED_X_STYLE
                     : INVERTED_Y_STYLE
                 : undefined;
-            for (let cellPos = 0; cellPos < plan.cells.length; cellPos += 1) {
-                const cell = plan.cells[cellPos];
+            // Wraps one cell identically whether it's the force-mounted sticky cell ahead of the
+            // window or an in-window cell from the loop below — same measuring View, same key shape.
+            // 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.
+            const pushCell = (cell) => {
                 const item = p.getItem(p.data, cell.index);
                 const content = p.renderItem?.({
                     item,
                     index: cell.index,
                     separators: makeSeparators(cell.index),
                 });
+                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.
+                cell.index < m.count - 1
+                    ? renderSeparatorElement(p.itemSeparatorComponent, item, p.getItem(p.data, cell.index + 1), separatorOverrides.get(cell.index))
+                    : undefined;
                 children.push(h('symbiote-view', {
                     key: `cell-${cell.key}`,
                     onLayout: makeCellMeasure(cell.index),
                     style: cellInverted,
-                }, [content]));
-                if (cell.index < m.last) {
-                    const separator = renderSeparatorElement(p.itemSeparatorComponent, item, p.getItem(p.data, cell.index + 1), separatorOverrides.get(cell.index));
-                    if (separator !== undefined) {
-                        children.push(h('symbiote-view', { key: `sep-${cell.key}` }, [separator]));
-                    }
+                }, separator === undefined ? [content] : [content, separator]));
+            };
+            // The nearest sticky section header below the window (RN _ensureClosestStickyHeader):
+            // force-mounted so it never gets destroyed/recreated while pinned off-window. Rendered
+            // ahead of the main window loop, with its own gap spacer to the window's first cell.
+            if (plan.forcedStickyCell !== undefined) {
+                pushCell(plan.forcedStickyCell);
+                if (plan.gapExtent > EMPTY_OFFSET) {
+                    children.push(h('symbiote-view', {
+                        key: 'spacer-gap',
+                        style: p.horizontal
+                            ? { width: plan.gapExtent }
+                            : { height: plan.gapExtent },
+                    }));
                 }
             }
+            for (let cellPos = 0; cellPos < plan.cells.length; cellPos += 1) {
+                pushCell(plan.cells[cellPos]);
+            }
             if (plan.trailingExtent > EMPTY_OFFSET) {
                 children.push(h('symbiote-view', {
                     key: 'spacer-trailing',
@@ -546,7 +584,8 @@ export const VirtualizedList = defineComponent((props, { attrs, expose, emit, sl
         if (p.maintainVisibleContentPosition !== undefined) {
             scrollProps.maintainVisibleContentPosition = {
                 ...p.maintainVisibleContentPosition,
-                minIndexForVisible: p.maintainVisibleContentPosition.minIndexForVisible + (header !== undefined ? 1 : 0),
+                minIndexForVisible: p.maintainVisibleContentPosition.minIndexForVisible +
+                    (header !== undefined ? 1 : 0),
             };
         }
         // Pull-to-refresh: when a @refresh listener is present, build a RefreshControl for the

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

@@ -6,6 +6,11 @@ export type { IVirtualizedSectionListHandle };
 export interface IVirtualizedSectionListProps<ItemT> {
     sections: ReadonlyArray<ISection<ItemT>>;
     keyExtractor?: (item: ItemT, index: number) => string;
+    getItemLayout?: (data: ReadonlyArray<ISection<ItemT>> | null, index: number) => {
+        length: number;
+        offset: number;
+        index: number;
+    };
     stickySectionHeadersEnabled?: boolean;
     extraData?: unknown;
     onEndReachedThreshold?: number;

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

@@ -1,33 +1,34 @@
 // VirtualizedSectionList, the Vue wrapper that flattens sections into one virtualized stream
-// over VirtualizedList. Each section contributes a header row, its item rows, then a footer row
-// (RN counts 2 per section); the flattened tagged sequence is fed to VirtualizedList as one list,
-// so headers/items/footers are all windowed by the same machinery. The flattening, entry keying,
-// separator-item unwrap, and scrollToLocation mapping are shared from @symbiote-native/components; this
-// file wires Vue lifecycle (typed-prop inputs + handle re-expose + the per-entry render dispatch).
-// The Vue twin of the React adapter's VirtualizedSectionList.
+// over VirtualizedList: each section contributes a header row, its item rows, then a footer row
+// (RN counts 2 per section), and the flattened tagged sequence is windowed by the same
+// machinery as one list. Flattening, entry keying, separator-item unwrap, and scrollToLocation
+// mapping are shared from @symbiote-native/components; this file wires Vue lifecycle
+// (typed-prop inputs + handle re-expose + per-entry render dispatch).
 //
-// Typed-emits generic component (mirrors FlatList / VirtualizedList): a GENERIC setup function
-// `<ItemT,>(props: IVirtualizedSectionListProps<ItemT>, ctx: ICtx<IVirtualizedSectionListEmits>)`
-// so the section inputs (sections/renderItem/renderSectionHeader/…) infer ItemT at the call site.
-// For that, those inputs are read from typed `props` (declared in the runtime `props` array); the
-// VirtualizedList passthrough tail (refreshing/style/raw scroll/…) rides through `$attrs` onto the
-// inner list. The three adapter-synthesized events (endReached/startReached/refresh — the exact set
-// React's section list exposes) stay GATED on listener presence: each emit bridge is wired ONLY
-// when the consumer listens (read off the instance vnode props), so the inner VirtualizedList keeps
-// building RefreshControl / computing edge-reached strictly on demand.
+// Typed-emits generic component (mirrors FlatList/VirtualizedList): a GENERIC setup function so
+// section inputs infer ItemT at the call site. Those inputs are read from typed `props`
+// (declared in the runtime `props` array); the VirtualizedList passthrough tail rides through
+// $attrs onto the inner list. The three adapter-synthesized events (endReached/startReached/
+// refresh) stay GATED on listener presence so the inner VirtualizedList keeps building
+// RefreshControl / computing edge-reached strictly on demand.
 import { defineComponent, getCurrentInstance, h, shallowRef, } from '@vue/runtime-core';
 import { flattenSections, resolveStickySectionHeaders, scrollLocationToFlatIndex, sectionEntryKey, unwrapEntryItem, } from '@symbiote-native/components';
 import { Platform, dlog, } from '@symbiote-native/engine';
 import { VirtualizedList } from '../virtualized-list/index.js';
 import { normalizeVueAttrs } from '../../utils/normalize-attrs.js';
-// VirtualizedList is a generic component (generic construct signature), which h()'s overloads can't
-// resolve. Drive it through a loose functional-component handle (generic-component h() limitation).
+// VirtualizedList's generic construct signature can't be resolved by h()'s overloads, so drive
+// it through a loose functional-component handle instead.
 const VirtualizedListHost = VirtualizedList;
-// The typed inputs VSL reads off `props`; everything else (the VirtualizedList passthrough tail and
-// raw scroll) falls through $attrs onto the inner list. Listed for the runtime `props` declaration
-// (keyof can't derive it: the index signature widens keyof to `string`). The three emit events are
-// deliberately absent (declared as emits below).
-const PROP_KEYS = ['sections', 'keyExtractor', 'stickySectionHeadersEnabled'];
+// Listed for the runtime `props` declaration (keyof can't derive it: the index signature widens
+// keyof to `string`). The three emit events are deliberately absent (declared as emits below).
+// getItemLayout is declared here, not left to $attrs: falling through would hand the user's
+// callback the flattened ENTRIES as its `data` argument instead of the sections (see below).
+const PROP_KEYS = [
+    'sections',
+    'keyExtractor',
+    'getItemLayout',
+    'stickySectionHeadersEnabled',
+];
 const EMIT_KEYS = ['endReached', 'startReached', 'refresh'];
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -68,10 +69,8 @@ export const VirtualizedSectionList = defineComponent((props, { attrs, expose, e
     // headerIndices change each render (sections may change); the delegate reads them lazily.
     let headerIndices = [];
     expose(buildSectionDelegate(() => inner.value, () => headerIndices));
-    // The three section-list events are emits, so Vue strips their onX listeners from $attrs. Detect
-    // listener presence off the instance's own vnode props (what the parent passed), exactly like
-    // FlatList/VirtualizedList, so an emit bridge is wired ONLY when the consumer actually listens
-    // (preserving the inner list's RefreshControl / edge-reached gating).
+    // Emits are stripped from $attrs by Vue; detect listener presence off the instance's own
+    // vnode props instead, so an emit bridge is wired ONLY when the consumer actually listens.
     const instance = getCurrentInstance();
     const listens = (onName) => {
         const vnodeProps = instance?.vnode.props;
@@ -95,10 +94,14 @@ export const VirtualizedSectionList = defineComponent((props, { attrs, expose, e
         const renderEntry = (info) => {
             const entry = info.item;
             if (entry.kind === 'header') {
-                return slots.sectionHeader ? slots.sectionHeader({ section: entry.section }) : [];
+                return slots.sectionHeader
+                    ? slots.sectionHeader({ section: entry.section })
+                    : [];
             }
             if (entry.kind === 'footer') {
-                return slots.sectionFooter ? slots.sectionFooter({ section: entry.section }) : [];
+                return slots.sectionFooter
+                    ? slots.sectionFooter({ section: entry.section })
+                    : [];
             }
             if (entry.kind === 'section-separator') {
                 return slots.sectionSeparator ? slots.sectionSeparator() : [];
@@ -122,6 +125,21 @@ export const VirtualizedSectionList = defineComponent((props, { attrs, expose, e
                 trailingItem: unwrapEntryItem(entryProps.trailingItem),
             });
         const entryKeyExtractor = (entry, index) => sectionEntryKey(entry, index, keyExtractor);
+        // Hand the callback `sections`, not the entries: RN's inner VirtualizedList gets
+        // `data={this.props.sections}` (VirtualizedSectionList.js:216) while ours streams the
+        // FLATTENED entries, so the same user code would otherwise see a different argument here
+        // than on RN.
+        //
+        // UPSTREAM-DIVERGENCE(react-native): the flat INDEX matches RN's (two rows per section,
+        // header and footer) only while the #sectionSeparator slot is unset. With it,
+        // flattenSections emits an extra 'section-separator' row per boundary that RN renders inside
+        // the neighbouring cell, so indices shift by one per boundary from the second section on.
+        // Deliberate - that row is how this adapter paints the separator; a caller combining the two
+        // must account for it.
+        const getItemLayout = props.getItemLayout;
+        const entryItemLayout = getItemLayout === undefined
+            ? undefined
+            : (_entries, index) => getItemLayout(sections, index);
         // The three synthesized events become inner-VL handlers ONLY when listened, so the inner list
         // keeps gating (no parasitic RefreshControl / edge-reached work for an unlistened event).
         const endReached = listens('onEndReached')
@@ -130,7 +148,9 @@ export const VirtualizedSectionList = defineComponent((props, { attrs, expose, e
         const startReached = listens('onStartReached')
             ? (eventInfo) => emit('startReached', eventInfo)
             : undefined;
-        const refresh = listens('onRefresh') ? () => emit('refresh') : undefined;
+        const refresh = listens('onRefresh')
+            ? () => emit('refresh')
+            : undefined;
         return h(VirtualizedListHost, {
             ...forwarded,
             ref: setInner,
@@ -138,6 +158,7 @@ export const VirtualizedSectionList = defineComponent((props, { attrs, expose, e
             getItem: (_source, index) => entries[index],
             getItemCount: () => entries.length,
             keyExtractor: entryKeyExtractor,
+            getItemLayout: entryItemLayout,
             stickyHeaderIndices,
             onEndReached: endReached,
             onStartReached: startReached,