@symbiote-native/vue 3.3.0 → 3.5.0

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

@@ -1,369 +1,109 @@
-// VirtualizedList, the Vue lifecycle half. The orchestration — window recompute, batch throttle,
-// viewability, edge-reached, initial-scroll, MVCP, the imperative scrolls — is the framework-agnostic
-// `reduceList` state machine in @symbiote-native/components (state/virtualized-list-reducer), shared verbatim
-// with React and Angular. Here Vue supplies only the reactivity: it turns native events into ACTIONS,
-// holds ONE plain state cell (listState), runs the returned EFFECTS with Vue primitives (a native
-// scrollTo, an emit, a setTimeout, a version bump), and builds the cell/spacer VNodes off the plan.
-// A single `metrics` computed derives the window once per render (refresh-metrics); a single
-// post-flush watcher on the windowing signature runs the after-commit `commit` pass. This is the Vue
-// twin of the React adapter's one-state-cell + dispatch + runEffects. It drives the Vue ScrollView,
-// exactly as the React list drives the React ScrollView.
-//
-// Typed-emits generic component (mirrors FlatList): a GENERIC setup function
-// `<ItemT,>(props: IVirtualizedListProps<ItemT>, ctx: ICtx<IVirtualizedListEmits<ItemT>>)` so the
-// five adapter-synthesized events emit with ItemT-typed payloads (`@viewable-items-changed` carries
-// ItemT, not unknown). For that to infer at the call site, the generic INPUTS (data/getItem/
-// renderItem/…) are read from typed `props`, declared in the runtime `props` array; the raw native
-// scroll events (onScroll/onScrollBeginDrag/…) + any unknown attrs ride through `$attrs` onto the
-// inner ScrollView. RefreshControl + viewability stay GATED on listener presence, so each emit
-// bridge is wired ONLY when the consumer actually listens (read off the instance vnode props),
-// keeping behavior identical to the prop-callback era.
-//
-// Lists have no Descriptor render fn (the cell content is the framework's own children).
-// Cells/spacers are built with h() directly off the plan.
-//
-// Reactivity gotcha: the ScrollView's exposed handle is held in a shallowRef so the engine
-// node it closes over is reached by identity; a deep ref would proxy it and the imperative
-// 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_INITIAL_NUM_TO_RENDER, DEFAULT_MAX_TO_RENDER_PER_BATCH, DEFAULT_UPDATE_CELLS_BATCHING_PERIOD, DEFAULT_WINDOW_SIZE, EMPTY_OFFSET, FIRST_INDEX, INVERTED_X_STYLE, INVERTED_Y_STYLE, buildListPlan, buildScrollViewHandle, buildViewabilityPairs, createInitialListState, isSeparatorGapInRange, listEffectSignature, readLayoutLength, readLayoutOffset, readScrollOffset, reduceList, resolveItemKey, } from '@symbiote-native/components';
-import { dlog, isSymbioteNode, } from '@symbiote-native/engine';
-import { normalizeVueAttrs } from '../../utils/normalize-attrs.js';
-import { componentFromSlot } from '../../utils/slots-to-render-props.js';
-// The typed inputs VirtualizedList reads off `props`; everything else (raw scroll, keyboard*,
-// accessibility, testID, …) falls through $attrs onto the inner ScrollView. Listed for the runtime
-// `props` declaration (keyof can't derive it: the index signature widens keyof to `string`). The
-// five raw-scroll events and the five emit events are deliberately absent.
-const PROP_KEYS = [
-    'data',
-    'getItem',
-    'getItemCount',
-    'keyExtractor',
-    'getItemLayout',
-    'viewabilityConfig',
-    'viewabilityConfigCallbackPairs',
-    'extraData',
-    'horizontal',
-    'inverted',
-    'onEndReachedThreshold',
-    'onStartReachedThreshold',
-    'refreshing',
-    'progressViewOffset',
-    'initialNumToRender',
-    'initialScrollIndex',
-    'maxToRenderPerBatch',
-    'updateCellsBatchingPeriod',
-    'windowSize',
-    'stickyHeaderIndices',
-    'maintainVisibleContentPosition',
-    'style',
-    'contentContainerStyle',
-    'keyboardShouldPersistTaps',
-    'keyboardDismissMode',
-];
-const EMIT_KEYS = [
-    'viewableItemsChanged',
-    'endReached',
-    'startReached',
-    'refresh',
-    'scrollToIndexFailed',
-];
-function isHandler(value) {
-    return typeof value === 'function';
-}
-function isComponent(value) {
-    return (typeof value === 'function' || (typeof value === 'object' && value !== null));
-}
-function asNumber(value, fallback) {
-    return typeof value === 'number' ? value : fallback;
-}
-// The attrs that arrive via $attrs but must NOT be forwarded raw onto the inner ScrollView: VL
-// composes its own onScroll (windowing offset + the user's onScroll) and its own onLayout (viewport
-// measure), so a consumer-passed one is dropped here and re-set explicitly on the scroll props.
-const HANDLED_ATTRS = ['onScroll', 'onLayout'];
-function forwardAttrs(attrs) {
-    const result = {};
-    for (const key of Object.keys(attrs)) {
-        if (!HANDLED_ATTRS.includes(key))
-            result[key] = attrs[key];
-    }
-    return result;
-}
-// A list component element (ListHeaderComponent / ListEmptyComponent / ListFooterComponent) is
-// either a Vue component (invoked via h) or a ready VNode (passed through). RN resolves the same
-// `Component | element` union; we narrow with isVNode before isComponent (a VNode is an object).
-function resolveElement(value) {
-    if (value === undefined || value === null)
-        return undefined;
-    if (isVNode(value))
-        return value;
-    if (isComponent(value))
-        return h(value);
-    return undefined;
-}
-function renderSeparatorElement(component, leadingItem, trailingItem, overrides) {
-    if (component === undefined)
-        return undefined;
-    const props = {
-        highlighted: false,
-        leadingItem,
-        trailingItem,
-        ...overrides,
-    };
-    return h(component, props);
-}
+// VirtualizedList, the Vue lifecycle half over the shared `reduceList` machine
+// A generic setup keeps the five emits typed by `ItemT`, raw native scroll events ride `$attrs`
+// `listState` is a plain object, a `version` ref is bumped when a transition changes render state
+import { computed, defineComponent, getCurrentInstance, h, onBeforeUnmount, ref, shallowRef, watch, } from '@vue/runtime-core';
+import { EMPTY_OFFSET, LIST_ACTION_KIND, buildListHandle, buildListReducerInputs, buildScrollViewHandle, buildSeparatorHandles, buildViewabilityPairs, clearTimers, createInitialListState, createListHandlers, createListNesting, isSeparatorGapInRange, listEffectSignature, listHasMore, reduceList, resolveItemKey, runListEffects, scrollTargetOf, viewPropsOf, } from '@symbiote-native/components';
+import { dlog, isDebug, isSymbioteNode, } from '@symbiote-native/engine';
+import { buildListChildren } from './list-children.js';
+import { buildScrollProps } from './list-scroll-props.js';
+import { narrowProps } from './narrow-props.js';
+import { provideVirtualizedListScope, useVirtualizedListScope, } from './nested-scope.js';
+import { userHandlersOf } from './user-handlers.js';
+import { EMIT_KEYS, PROP_KEYS, } from './virtualized-list-props.js';
 export const VirtualizedList = defineComponent((props, { attrs, expose, emit, slots, }) => {
-    // Bumped when a transition changes render-relevant state, so the `metrics` computed and the
-    // render fn re-run (listState is plain, non-reactive, so mutating it triggers nothing itself).
     const version = ref(EMPTY_OFFSET);
     const separatorVersion = ref(EMPTY_OFFSET);
-    // The offset we are imperatively driving native to. A fresh object identity each push so the
-    // commit path re-applies it even when the numeric value repeats. undefined = none pending.
+    // A fresh object each push so the commit path re-applies a repeated value
     const commandedOffset = ref(undefined);
-    // shallowRef, NOT ref: `<scroll-view>` is a tag now, so its `ref` hands back the raw engine
-    // node directly, reached by identity through the engine's WeakMap mirror. A deep ref would
-    // proxy the object and every imperative scroll (scrollToOffset/Index/…) would miss the node
-    // and silently no-op.
+    // `<scroll-view>` is a tag, so its `ref` hands back the raw engine node, held by identity
     const scrollNodeRef = shallowRef(null);
     const setScrollNodeRef = (el) => {
         scrollNodeRef.value = isSymbioteNode(el) ? el : null;
     };
-    // Built once: `getNode` is lazy, read on every call, so this stays valid across the ref
-    // transitioning from null to the committed node.
     const scrollHandle = buildScrollViewHandle(() => scrollNodeRef.value);
-    // The five 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, so
-    // an emit bridge is wired ONLY when the consumer actually listens (preserving the RefreshControl /
-    // viewability gating of the prop-callback era).
+    // The parent's own vnode props tell whether it listens, Vue strips emits from `$attrs`
     const instance = getCurrentInstance();
     const listens = (onName) => {
         const vnodeProps = instance?.vnode.props;
         return vnodeProps != null && typeof vnodeProps[onName] === 'function';
     };
-    // The one folded state cell (the Vue twin of React's stateRef); plus the per-gap separator
-    // overrides + the adapter-owned debounce/fill timers.
     const listState = createInitialListState();
     const separatorOverrides = new Map();
-    let viewableTimer = null;
-    let batchTimer = null;
-    const narrowed = computed(() => {
-        // extraData has no field of its own; reading it tracks it so a change forces a re-render
-        // (RN's extraData contract).
-        void props.extraData;
-        const folded = normalizeVueAttrs(attrs);
-        return {
-            data: props.data,
-            getItem: props.getItem,
-            getItemCount: props.getItemCount,
-            // Cell + chrome come from scoped slots. #item IS the render fn (a slot fn returning
-            // VNode|VNode[], which the cell wrapper accepts directly). #separator carries scope props
-            // (h(component, props)) so it goes through componentFromSlot; #header/#footer/#empty are
-            // scopeless, so the bare slot fn is handed to resolveElement (its isComponent branch).
-            renderItem: slots.item,
-            keyExtractor: props.keyExtractor,
-            getItemLayout: props.getItemLayout,
-            itemSeparatorComponent: componentFromSlot(slots.separator),
-            listHeaderComponent: slots.header,
-            listFooterComponent: slots.footer,
-            listEmptyComponent: slots.empty,
-            horizontal: props.horizontal === true,
-            inverted: props.inverted === true,
-            onEndReached: listens('onEndReached')
-                ? (info) => emit('endReached', info)
-                : undefined,
-            onEndReachedThreshold: typeof props.onEndReachedThreshold === 'number'
-                ? props.onEndReachedThreshold
-                : undefined,
-            onStartReached: listens('onStartReached')
-                ? (info) => emit('startReached', info)
-                : undefined,
-            onStartReachedThreshold: typeof props.onStartReachedThreshold === 'number'
-                ? props.onStartReachedThreshold
-                : undefined,
-            onRefresh: listens('onRefresh')
-                ? () => emit('refresh')
-                : undefined,
-            refreshing: props.refreshing === true,
-            progressViewOffset: props.progressViewOffset,
-            onViewableItemsChanged: listens('onViewableItemsChanged')
-                ? (info) => emit('viewableItemsChanged', info)
-                : undefined,
-            viewabilityConfig: props.viewabilityConfig,
-            viewabilityConfigCallbackPairs: props.viewabilityConfigCallbackPairs,
-            onScrollToIndexFailed: listens('onScrollToIndexFailed')
-                ? (info) => emit('scrollToIndexFailed', info)
-                : undefined,
-            initialNumToRender: asNumber(props.initialNumToRender, DEFAULT_INITIAL_NUM_TO_RENDER),
-            initialScrollIndex: props.initialScrollIndex,
-            maxToRenderPerBatch: asNumber(props.maxToRenderPerBatch, DEFAULT_MAX_TO_RENDER_PER_BATCH),
-            updateCellsBatchingPeriod: asNumber(props.updateCellsBatchingPeriod, DEFAULT_UPDATE_CELLS_BATCHING_PERIOD),
-            windowSize: asNumber(props.windowSize, DEFAULT_WINDOW_SIZE),
-            stickyHeaderIndices: props.stickyHeaderIndices,
-            maintainVisibleContentPosition: props.maintainVisibleContentPosition,
-            userOnScroll: isHandler(folded.onScroll) ? folded.onScroll : undefined,
-            style: props.style,
-            contentContainerStyle: props.contentContainerStyle,
-            keyboardShouldPersistTaps: props.keyboardShouldPersistTaps,
-            keyboardDismissMode: props.keyboardDismissMode,
-            forwarded: forwardAttrs(folded),
-        };
-    });
-    // The reducer inputs, folded off `narrowed`. Rebuilt per call (cheap); the viewability pairs are
-    // rebuilt here so the reduce and the effect fire against the same set.
-    const buildInputs = () => {
-        const p = narrowed.value;
-        return {
-            data: p.data,
-            getItem: p.getItem,
-            getItemCount: p.getItemCount,
-            keyExtractor: p.keyExtractor,
-            getItemLayout: p.getItemLayout,
-            horizontal: p.horizontal,
-            windowSize: p.windowSize,
-            initialNumToRender: p.initialNumToRender,
-            maxToRenderPerBatch: p.maxToRenderPerBatch,
-            updateCellsBatchingPeriod: p.updateCellsBatchingPeriod,
-            onEndReachedThreshold: p.onEndReachedThreshold,
-            onStartReachedThreshold: p.onStartReachedThreshold,
-            onEndReachedActive: p.onEndReached !== undefined,
-            onStartReachedActive: p.onStartReached !== undefined,
-            viewabilityPairs: buildViewabilityPairs(p.onViewableItemsChanged, p.viewabilityConfig, p.viewabilityConfigCallbackPairs),
-            maintainVisibleContentPosition: p.maintainVisibleContentPosition,
-            initialScrollIndex: p.initialScrollIndex,
-        };
-    };
+    const viewableTimer = { current: null };
+    const batchTimer = { current: null };
+    const narrowed = computed(() => narrowProps({ props, attrs, slots, emit, listens }));
+    const viewabilityPairs = computed(() => buildViewabilityPairs(narrowed.value.onViewableItemsChanged, narrowed.value.viewabilityConfig, narrowed.value.viewabilityConfigCallbackPairs));
+    const buildInputs = () => buildListReducerInputs({
+        ...narrowed.value,
+        findFirstChildWithMore: (first, last) => nesting.findFirstChildWithMore(first, last),
+    }, viewabilityPairs.value);
     const keyFor = (index) => {
         const p = narrowed.value;
         return resolveItemKey(p.getItem(p.data, index), index, p.keyExtractor);
     };
     const scrollToPixel = (offset, animated) => {
-        const p = narrowed.value;
-        const clamped = Math.max(EMPTY_OFFSET, offset);
-        const targetOffset = p.horizontal
-            ? { x: clamped, y: EMPTY_OFFSET }
-            : { x: EMPTY_OFFSET, y: clamped };
-        if (scrollNodeRef.value !== null) {
-            dlog(`Vue VirtualizedList scrollTo offset=${clamped} animated=${animated} (horizontal=${p.horizontal})`);
-            scrollHandle.scrollTo({
-                x: targetOffset.x,
-                y: targetOffset.y,
-                animated,
-            });
+        const target = scrollTargetOf(offset, narrowed.value.horizontal);
+        if (scrollNodeRef.value === null) {
+            dlog(`Vue VirtualizedList scrollTo offset=${offset} pending-ref`);
+            commandedOffset.value = target;
             return;
         }
-        dlog(`Vue VirtualizedList scrollTo offset=${clamped} pending-ref`);
-        commandedOffset.value = targetOffset;
+        dlog(`Vue VirtualizedList scrollTo offset=${offset} animated=${animated}`);
+        scrollHandle.scrollTo({ x: target.x, y: target.y, animated });
     };
-    // Execute the reducer's effects with Vue primitives. `inputs` is threaded through so a
-    // fire-viewable fires against the same pairs the reduce used.
-    const runEffects = (effects, inputs) => {
-        const p = narrowed.value;
-        for (const effect of effects) {
-            switch (effect.kind) {
-                case 'scroll-to':
-                    scrollToPixel(effect.offset, effect.animated);
-                    break;
-                case 'fire-end-reached':
-                    p.onEndReached?.({ distanceFromEnd: effect.distanceFromEnd });
-                    break;
-                case 'fire-start-reached':
-                    p.onStartReached?.({ distanceFromStart: effect.distanceFromStart });
-                    break;
-                case 'fire-scroll-to-index-failed':
-                    p.onScrollToIndexFailed?.({
-                        index: effect.index,
-                        highestMeasuredFrameIndex: effect.highestMeasuredFrameIndex,
-                        averageItemLength: effect.averageItemLength,
-                    });
-                    break;
-                case 'schedule-refill': {
-                    if (batchTimer !== null)
-                        clearTimeout(batchTimer);
-                    batchTimer = setTimeout(() => {
-                        batchTimer = null;
-                        dispatch({ kind: 'batch-tick' });
-                    }, effect.delay);
-                    break;
-                }
-                case 'fire-viewable': {
-                    const pairs = inputs.viewabilityPairs;
-                    const info = effect.info;
-                    const map = effect.map;
-                    const fire = () => {
-                        for (const pair of pairs) {
-                            pair.onViewableItemsChanged({
-                                ...info,
-                                viewabilityConfig: pair.viewabilityConfig,
-                            });
-                        }
-                        dispatch({ kind: 'viewable-fired', map });
-                    };
-                    if (viewableTimer !== null) {
-                        clearTimeout(viewableTimer);
-                        viewableTimer = null;
-                    }
-                    if (effect.delay > EMPTY_OFFSET) {
-                        viewableTimer = setTimeout(() => {
-                            viewableTimer = null;
-                            fire();
-                        }, effect.delay);
-                    }
-                    else {
-                        fire();
-                    }
-                    break;
-                }
-            }
-        }
+    const effectHost = {
+        callbacks: () => ({
+            onEndReached: narrowed.value.onEndReached,
+            onStartReached: narrowed.value.onStartReached,
+            onScrollToIndexFailed: narrowed.value.onScrollToIndexFailed,
+            viewabilityPairs: viewabilityPairs.value,
+        }),
+        scrollToPixel,
+        dispatch: () => dispatch,
+        viewableTimer,
+        batchTimer,
     };
     const dispatch = (action) => {
-        const inputs = buildInputs();
-        const result = reduceList(listState, action, inputs);
-        runEffects(result.effects, inputs);
+        const result = reduceList(listState, action, buildInputs());
+        runListEffects(result.effects, effectHost);
         if (result.changed)
             version.value += 1;
     };
-    // The single derive-per-render: the window is recomputed once here (refresh-metrics) and cached
-    // by the computed until `version` or the narrowed props change, so the render fn and the commit
-    // signature both read it without re-deriving (which would double-advance the throttle).
+    // The one window recompute, cached so the render and the commit signature both read it
+    // without re-deriving (which would double-advance the throttle)
     const metrics = computed(() => {
         void version.value;
-        reduceList(listState, { kind: 'refresh-metrics' }, buildInputs());
+        reduceList(listState, { kind: LIST_ACTION_KIND.refreshMetrics }, buildInputs());
         return listState.metrics;
     });
     const commitSignature = computed(() => {
         void metrics.value;
         return listEffectSignature(listState);
     });
-    const onScroll = (event) => {
-        const p = narrowed.value;
-        const offset = readScrollOffset(event, p.horizontal);
-        if (offset === undefined)
-            return;
-        dlog(`Vue VirtualizedList onScroll offset=${offset}`);
-        // A real native scroll supersedes any pending commanded offset.
-        commandedOffset.value = undefined;
-        dispatch({ kind: 'scroll', offset });
-        // Compose, don't clobber: internal windowing ran first, now the user's onScroll.
-        if (p.userOnScroll !== undefined)
-            p.userOnScroll(event);
-    };
-    const onViewportLayout = (event) => {
-        const length = readLayoutLength(event, narrowed.value.horizontal);
-        if (length === undefined)
-            return;
-        dlog(`Vue VirtualizedList onLayout viewport=${length}`);
-        dispatch({ kind: 'layout', length });
-    };
-    const makeCellMeasure = (index) => (event) => {
-        const length = readLayoutLength(event, narrowed.value.horizontal);
-        if (length === undefined)
-            return;
-        const offset = readLayoutOffset(event, narrowed.value.horizontal);
-        dlog(`Vue VirtualizedList cell ${index} measured length=${length} offset=${offset ?? 'none'}`);
-        dispatch({ kind: 'measure', index, length, offset });
-    };
+    // The list above hands its scope down, this list hands its own to the lists in its cells
+    const nesting = createListNesting({
+        parent: useVirtualizedListScope(),
+        horizontal: narrowed.value.horizontal,
+        getState: () => listState,
+        dispatch,
+        getContainerNode: () => scrollNodeRef.value,
+        getHasMore: () => listHasMore(listState),
+        keyFor,
+        handlers: () => handlers,
+    });
+    provideVirtualizedListScope(nesting.scope);
+    const handlers = createListHandlers({
+        isHorizontal: () => narrowed.value.horizontal,
+        user: () => userHandlersOf(narrowed.value),
+        nesting: () => nesting,
+        dispatch,
+        clearCommandedOffset: () => {
+            commandedOffset.value = undefined;
+        },
+        getNode: () => scrollNodeRef.value,
+        keyFor,
+    });
+    const makeCellFocus = (index) => () => dispatch({ kind: LIST_ACTION_KIND.cellFocused, index });
     const mergeSeparator = (gapIndex, patch) => {
         if (!isSeparatorGapInRange(gapIndex, listState.metrics.count))
             return;
@@ -373,246 +113,78 @@ export const VirtualizedList = defineComponent((props, { attrs, expose, emit, sl
         });
         separatorVersion.value += 1;
     };
-    const makeSeparators = (index) => ({
-        highlight: () => {
-            dlog(`Vue VirtualizedList separator highlight cell=${index}`);
-            mergeSeparator(index - 1, { highlighted: true });
-            mergeSeparator(index, { highlighted: true });
-        },
-        unhighlight: () => {
-            dlog(`Vue VirtualizedList separator unhighlight cell=${index}`);
-            mergeSeparator(index - 1, { highlighted: false });
-            mergeSeparator(index, { highlighted: false });
-        },
-        updateProps: (select, newProps) => {
-            mergeSeparator(select === 'leading' ? index - 1 : index, newProps);
-        },
-    });
-    // ---- imperative handle (the shared IVirtualizedListHandle surface) ------
-    const handle = {
-        scrollToOffset: (params) => {
-            dispatch({
-                kind: 'scroll-to-offset',
-                offset: params.offset,
-                animated: params.animated ?? true,
-            });
-        },
-        scrollToIndex: (params) => {
-            dispatch({
-                kind: 'scroll-to-index',
-                index: params.index,
-                animated: params.animated ?? true,
-                viewPosition: params.viewPosition ?? FIRST_INDEX,
-                viewOffset: params.viewOffset ?? EMPTY_OFFSET,
-            });
-        },
-        scrollToItem: (params) => {
-            dispatch({
-                kind: 'scroll-to-item',
-                item: params.item,
-                animated: params.animated ?? true,
-                viewPosition: params.viewPosition ?? FIRST_INDEX,
-            });
-        },
-        scrollToEnd: (params) => {
-            dispatch({ kind: 'scroll-to-end', animated: params?.animated ?? true });
-        },
-        flashScrollIndicators: () => {
-            scrollHandle.flashScrollIndicators();
-        },
-        getNativeScrollRef: () => scrollNodeRef.value !== null ? scrollHandle : null,
-        getScrollableNode: () => scrollNodeRef.value !== null ? scrollHandle : null,
-        getScrollResponder: () => scrollNodeRef.value !== null ? scrollHandle : null,
-        getScrollNode: () => scrollNodeRef.value,
-        recordInteraction: () => {
-            dispatch({ kind: 'record-interaction' });
-        },
-    };
-    expose(handle);
-    // ---- after-commit pass (one post-flush watcher, the Vue twin of the layout effect) ----
-    // Runs the deferred effects (batch fill, edge-reached, viewability, initial-scroll, MVCP)
-    // whenever the windowing signature changes — the same dedup key every adapter shares.
+    const makeSeparators = (index) => buildSeparatorHandles(index, mergeSeparator);
+    expose(buildListHandle({
+        dispatch,
+        scrollHandle,
+        getNode: () => scrollNodeRef.value,
+    }));
+    // The after-commit pass, a post-flush watcher on the windowing signature
     watch(commitSignature, () => {
-        const inputs = buildInputs();
-        const result = reduceList(listState, { kind: 'commit' }, inputs);
-        runEffects(result.effects, inputs);
+        const result = reduceList(listState, { kind: LIST_ACTION_KIND.commit }, buildInputs());
+        runListEffects(result.effects, effectHost);
     }, { flush: 'post' });
     onBeforeUnmount(() => {
-        if (viewableTimer !== null)
-            clearTimeout(viewableTimer);
-        if (batchTimer !== null)
-            clearTimeout(batchTimer);
+        clearTimers([viewableTimer, batchTimer]);
+        nesting.detach();
     });
     return () => {
         const p = narrowed.value;
         const m = metrics.value;
-        // Read the version refs so a separator/measurement bump re-renders.
+        // Reading the version makes a separator bump re-render
         void separatorVersion.value;
-        if (p.renderItem === undefined)
-            dlog('Vue VirtualizedList: no #item slot provided — cells render empty');
-        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 header = resolveElement(p.listHeaderComponent);
-        if (header !== undefined) {
-            children.push(h('view', { key: 'list-header' }, [header]));
-        }
-        if (m.count === FIRST_INDEX) {
-            const empty = resolveElement(p.listEmptyComponent);
-            if (empty !== undefined) {
-                children.push(h('view', { key: 'list-empty' }, [empty]));
-            }
-        }
-        else {
-            const plan = buildListPlan({
-                count: m.count,
-                first: m.first,
-                last: m.last,
-                offsets: m.offsets,
-                lengths: m.lengths,
-                total: m.total,
-                keyFor,
-                stickyIndices: stickySet,
-                hasHeader: header !== undefined,
-            });
-            // `plan.stickyChildPositions` is deliberately NOT read — it was the input to the index form.
-            if (plan.leadingExtent > EMPTY_OFFSET) {
-                children.push(h('view', {
-                    key: 'spacer-leading',
-                    style: p.horizontal
-                        ? { width: plan.leadingExtent }
-                        : { height: plan.leadingExtent },
-                }));
-            }
-            const cellInverted = p.inverted
-                ? p.horizontal
-                    ? INVERTED_X_STYLE
-                    : INVERTED_Y_STYLE
-                : undefined;
-            // The separator lives INSIDE the cell's own measuring wrapper, not as a sibling: a sibling
-            // is an extra flex child, so a leading-spacer collapse would land every cell below it
-            // short by (separator + 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 = 
-                // Gated on the last index of the DATA, not the WINDOW: since the separator lives
-                // inside the measuring wrapper, gating on the window would make a cell's own
-                // measured height change as the window slides past it.
-                cell.index < m.count - 1
-                    ? renderSeparatorElement(p.itemSeparatorComponent, item, p.getItem(p.data, cell.index + 1), separatorOverrides.get(cell.index))
-                    : undefined;
-                children.push(h(
-                // A cell the app flagged sticky IS the `sticky-header` tag — same position, same key,
-                // same `onLayout` (the behavior forwards it rather than replacing it). The collision
-                // point then comes from the owner's DOCUMENT order, which is the one form that
-                // survives windowing; `stickyHeaderIndices` numbers paint children and does not.
-                stickySet?.has(cell.index) === true ? 'sticky-header' : 'view', {
-                    key: `cell-${cell.key}`,
-                    onLayout: makeCellMeasure(cell.index),
-                    style: cellInverted,
-                }, 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('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('view', {
-                    key: 'spacer-trailing',
-                    style: p.horizontal
-                        ? { width: plan.trailingExtent }
-                        : { height: plan.trailingExtent },
-                }));
-            }
-        }
-        const footer = resolveElement(p.listFooterComponent);
-        if (footer !== undefined) {
-            children.push(h('view', { key: 'list-footer' }, [footer]));
+        if (p.renderItem === undefined && p.listItemComponent === undefined) {
+            dlog('Vue VirtualizedList: no #item slot provided, cells render empty');
         }
-        const resolvedContentContainerStyle = p.horizontal
-            ? [p.contentContainerStyle, { width: m.total }]
-            : p.contentContainerStyle;
-        // VirtualizedList.js: `[inversionStyle, style]` — the app's style can override the flip.
-        const resolvedStyle = p.inverted
-            ? [p.horizontal ? INVERTED_X_STYLE : INVERTED_Y_STYLE, p.style]
-            : p.style;
-        // `horizontal` is NOT in the bag: the axis is the TAG (`horizontal-scroll-view`), so passing
-        // it would be redundant at best and a contradiction the behavior has to warn about at worst.
-        const scrollProps = {
-            ...p.forwarded,
-            style: resolvedStyle,
-            contentContainerStyle: resolvedContentContainerStyle,
-            onScroll,
-            onLayout: onViewportLayout,
-            ref: setScrollNodeRef,
-        };
-        // The raw scroll-lifecycle callbacks (onScrollBeginDrag/…) and scrollEventThrottle are NOT in
-        // PROP_KEYS, so they already ride through via ...p.forwarded. The keyboard props come from
-        // typed props (PROP_KEYS), so re-set them explicitly here (only when provided).
-        // VirtualizedList.js:1111 — Android moves the scrollbar back after the `scale: -1` flip.
-        if (p.inverted)
-            scrollProps.isInvertedVirtualizedList = true;
-        if (p.keyboardShouldPersistTaps !== undefined) {
-            scrollProps.keyboardShouldPersistTaps = p.keyboardShouldPersistTaps;
+        if (isDebug()) {
+            dlog(`Vue VirtualizedList window [${m.first}, ${m.last}] of ${m.count} ` +
+                `(offset=${listState.scrollOffset}, viewport=${listState.viewportLength})`);
         }
-        if (p.keyboardDismissMode !== undefined) {
-            scrollProps.keyboardDismissMode = p.keyboardDismissMode;
-        }
-        // A pending imperative/initial scroll rides down as contentOffset (fallback for the
-        // pre-mount window before the handle attaches).
-        if (commandedOffset.value !== undefined)
-            scrollProps.contentOffset = commandedOffset.value;
-        // `stickyHeaderIndices` is deliberately NOT forwarded — see `pushCell`. It numbers the scroll
-        // view's PAINT children, and a windowed list paints a header, a spacer and a slice, so the
-        // positions move every time the window slides and the behavior re-wraps a different child
-        // each pass. The cells carry the tag instead.
-        // Forward maintainVisibleContentPosition to the ScrollView so it anchors the in-window cells.
-        // minIndexForVisible is bumped by 1 when a ListHeaderComponent occupies child 0.
-        if (p.maintainVisibleContentPosition !== undefined) {
-            scrollProps.maintainVisibleContentPosition = {
-                ...p.maintainVisibleContentPosition,
-                minIndexForVisible: p.maintainVisibleContentPosition.minIndexForVisible +
-                    (header !== undefined ? 1 : 0),
-            };
-        }
-        // Pull-to-refresh: when a @refresh listener is present, the RefreshControl is an ordinary
-        // FIRST CHILD on both platforms rather than a prop — the scroll behavior CLAIMS it, so the
-        // engine keeps it beside the content view on iOS and inverts the tree on Android. The
-        // onRefresh bridge is gated on the listener, so an unlistened list builds no control.
-        let refreshControl;
-        if (p.onRefresh !== undefined) {
-            dlog('Vue VirtualizedList wiring RefreshControl (@refresh listened)');
-            refreshControl = h('refresh-control', {
-                refreshing: p.refreshing,
-                onRefresh: p.onRefresh,
-                progressViewOffset: p.progressViewOffset,
-            });
+        const { children, hasHeader } = buildListChildren({
+            props: p,
+            metrics: m,
+            keyFor,
+            separatorOverrides,
+            makeSeparators,
+            makeCellMeasure: handlers.makeCellMeasure,
+            makeCellFocus,
+        });
+        const scrollProps = buildScrollProps({
+            props: p,
+            total: m.total,
+            hasHeader,
+            onScroll: handlers.onScroll,
+            onScrollBeginDrag: handlers.onScrollBeginDrag,
+            onScrollEndDrag: handlers.onScrollEndDrag,
+            onMomentumScrollBegin: handlers.onMomentumScrollBegin,
+            onMomentumScrollEnd: handlers.onMomentumScrollEnd,
+            onContentSizeChange: handlers.onContentSizeChange,
+            onLayout: handlers.onViewportLayout,
+            setRef: setScrollNodeRef,
+            commandedOffset: commandedOffset.value,
+        });
+        // The list above scrolls, so RN renders a `View` with no content container
+        if (nesting.isNested) {
+            return h('view', {
+                ...viewPropsOf(p.forwarded),
+                style: p.style,
+                onLayout: handlers.onViewportLayout,
+                ref: setScrollNodeRef,
+            }, children);
         }
-        // The scroll TAG, not a wrapper: the engine builds the content node, carries
-        // `contentContainerStyle` onto it and places the refresh control. `ref` hands back the
-        // engine node, which is what `buildScrollViewHandle` drives for the imperative scrolls.
-        return h(p.horizontal ? 'horizontal-scroll-view' : 'scroll-view', scrollProps, refreshControl === undefined ? children : [refreshControl, ...children]);
+        // With a `@refresh` listener the RefreshControl is an ordinary first child, the scroll
+        // behavior claims it and places it per platform
+        const refreshControl = p.onRefresh === undefined
+            ? []
+            : [
+                h('refresh-control', {
+                    refreshing: p.refreshing,
+                    onRefresh: p.onRefresh,
+                    progressViewOffset: p.progressViewOffset,
+                }),
+            ];
+        // The scroll TAG, not a wrapper: the engine builds the content node and places the control
+        return h(p.horizontal ? 'horizontal-scroll-view' : 'scroll-view', scrollProps, [...refreshControl, ...children]);
     };
 }, {
     name: 'VirtualizedList',