@symbiote-native/solid 3.2.0 → 3.3.0

package/build/components/virtualized-list/shared.jsx

@@ -1,759 +1,60 @@
-// VirtualizedList — real windowing over the `<scroll-view>` tag's own engine-owned scroll host.
-// Only the cells whose computed offset falls inside the visible window (plus a leading/trailing
-// buffer) exist as native views; everything above and below collapses into spacers whose sizes sum
-// to the off-screen extent, so the scroll thumb and total content size stay right without mounting
-// all N rows.
-//
-// The orchestration — window recompute, edge-reached, viewability, batch fill, MVCP, the imperative
-// scrolls — is the framework-agnostic `reduceList` state machine in @symbiote-native/components,
-// shared verbatim with React, Vue, Svelte and Angular. So is every geometry leaf (`buildListPlan`,
-// `computeWindow`, `resolveItemKey`, …) and every scroll-host helper ScrollView also uses
-// (`selectScrollIntrinsics`, `resolveScrollForwarding`, `buildScrollViewHandle`,
-// `attachStickyScroll`, `forwardScrollEvent`). Solid supplies ONLY its lifecycle: it turns native
-// events into ACTIONS, holds ONE plain state cell, runs the returned EFFECTS with Solid primitives,
-// and assembles the host elements. Lists have no Descriptor render fn — the cell content is the
-// user's own subtree (`symbiote-add-component` §0, category 2).
-//
-// THIS FILE NO LONGER BUILDS THE CONTENT NODE ITSELF: `registerScrollViewBehavior()`'s tag-owned
-// `buildStructure` does that, read back off `scroll.childHost` rather than built a second time
-// here. RefreshControl is an ordinary child now; `claimedChildren` decides where it lands.
-//
-// WHY THIS FILE STILL HAND-AUTHORS THE SCROLL TAG VIA `createElement` INSTEAD OF PLAIN JSX
-// (`<scroll-view>{listBody}</scroll-view>`), unlike a component with no dynamic children. Solid's
-// own `insert()` reconciles a parent's children by walking that SAME node's `getFirstChild`/
-// `getNextSibling` — which read `node.children` directly and know nothing about `childHost`
-// redirection. Calling `insert` on the SCROLL node itself would have it diff against the scroll
-// node's own (single) child rather than the content node's list items. So this file keeps an
-// explicit reference to the content node and calls `insert(content, listBody)` on THAT, exactly the
-// node Solid's own diffing needs to see.
-//
-// WHY THE SCROLL CELLS ARE WALKED FOR STICKY HEADERS RATHER THAN LEFT TO THE ENGINE'S GENERIC
-// `stickyHeaderIndices` WALK OF COMMITTED CHILDREN (what a bare `<scroll-view>` gets for free
-// elsewhere): the flagged CELL here needs wrapping ONCE, inside the keyed <For> row that owns it, or
-// every scroll event would tear the wrapper down and rebuild it (losing its measured layout each
-// time) the moment a naive re-render tried to resolve which child is sticky. Same conclusion, same
-// reason, as adapters/svelte's index.svelte. This is independent of the content-node question above
-// — it is about the LIST's own cells, not about how the scroll host itself is built.
-//
-// THREE SOLID FACTS DRIVE THE REST, and none of them is cosmetic (.claude/rules/
-// solid-descriptor-bridge.md):
-//
-// 1. A component body runs ONCE and `insert` REPLACES rather than diffing. So the cells ride a keyed
-//    <For> over the cell KEY strings — <For> matches by value identity, which is what makes a row
-//    MOVE as the window slides instead of being destroyed and rebuilt. <Index> would have been
-//    exactly wrong here: it keys by position, so row 0 would be reused for a different item on every
-//    scroll and its whole `renderItem` subtree would be rebuilt each step.
-// 2. `renderItem` is a render prop, so its info arrives as an ACCESSOR and the call is untracked — a
-//    tracked call would rebuild the cell subtree on every change (trap 4). Same shape
-//    `<For>{(item, index) => …}` and Pressable's child already use.
-// 3. The scroll AXIS picks a different host TAG and Solid cannot swap a tag under a live node — so
-//    the flip is an explicit rebuild boundary (trap 5), with the build untracked so every other prop
-//    re-props the SAME nodes through `spread`.
-import { For, Show, createEffect, createMemo, createSignal, on, onCleanup, splitProps, untrack, } from 'solid-js';
-import { DEFAULT_INITIAL_NUM_TO_RENDER, DEFAULT_MAX_TO_RENDER_PER_BATCH, DEFAULT_UPDATE_CELLS_BATCHING_PERIOD, DEFAULT_WINDOW_SIZE, EMPTY_OFFSET, FIRST_INDEX, NO_INDEX, INVERTED_X_STYLE, INVERTED_Y_STYLE, buildListPlan, buildScrollViewHandle, buildViewabilityPairs, nextStickyHeaderY, isSeparatorGapInRange, listEffectSignature, attachStickyScroll, forwardScrollEvent, resolveAccessibilityProps, resolveScrollForwarding, selectScrollIntrinsics, createInitialListState, readLayoutLength, readLayoutOffset, readLayoutNumber, readScrollOffset, reduceList, resolveItemKey, } from '@symbiote-native/components';
-import { AnimatedValue, dlog, event as animatedEvent, getNativeTag, isNativeAnimatedAvailable, isSymbioteNode, whenCommitted, resolveClassName, } from '@symbiote-native/engine';
-import { createElement, insert, insertNode, spread } from '../../renderer.js';
-import { withStableKeys } from '../../utils/stable-keys.js';
-import { ScrollViewStickyHeader } from './sticky-header.jsx';
-// Consumed by the lifecycle itself; everything LEFT OVER is the accessibility surface, which rides
-// down onto the scroll host exactly as React spreads `...accessibilityRest` onto its ScrollView.
-const HANDLED_PROPS = [
-    'data',
-    'getItem',
-    'getItemCount',
-    'renderItem',
-    'getItemLayout',
-    'initialNumToRender',
-    'windowSize',
-    'ListHeaderComponent',
-    'ListFooterComponent',
-    'ListEmptyComponent',
-    'ItemSeparatorComponent',
-    'ref',
-    'onEndReached',
-    'onEndReachedThreshold',
-    'onStartReached',
-    'onStartReachedThreshold',
-    'keyExtractor',
-    'onViewableItemsChanged',
-    'viewabilityConfig',
-    'viewabilityConfigCallbackPairs',
-    'onScroll',
-    'onScrollBeginDrag',
-    'onScrollEndDrag',
-    'onMomentumScrollBegin',
-    'onMomentumScrollEnd',
-    'scrollEventThrottle',
-    'keyboardShouldPersistTaps',
-    'keyboardDismissMode',
-    'horizontal',
-    'inverted',
-    'style',
-    'contentContainerStyle',
-    'class',
-    'onScrollToIndexFailed',
-    'onRefresh',
-    'refreshing',
-    'progressViewOffset',
-    'stickyHeaderIndices',
-    'maintainVisibleContentPosition',
-    'initialScrollIndex',
-    'maxToRenderPerBatch',
-    'updateCellsBatchingPeriod',
-    'extraData',
-];
-// A ListHeaderComponent occupies child 0 of the content container, which shifts every data index
-// native MVCP anchors against by one (RN VirtualizedList.js does the same bump).
-const HEADER_CHILD_COUNT = 1;
-// No platform parameter any more: the RefreshControl placement per platform (a sibling on iOS, an
-// inverting wrap on Android) is entirely the tag's own engine behavior's concern now
-// (`core/components/src/behaviors/scroll-view/index.{ios,android}.ts`) — this factory used to take
-// an `IScrollViewHostPlatform` only to re-decide the same thing by hand.
+// VirtualizedList over the `<scroll-view>` tag's scroll host, Solid supplies only the lifecycle
+// The body runs ONCE and `insert` replaces rather than diffs, so rows ride a keyed `<For>` and MOVE
+import { splitProps, untrack } from 'solid-js';
+import { FIRST_INDEX, listStyleOf, resolveAccessibilityProps, } from '@symbiote-native/components';
+import { provideVirtualizedListScope } from './nested-scope.js';
+import { buildRow } from './list-rows.jsx';
+import { listBody } from './list-body.jsx';
+import { createListParts } from './list-parts.js';
+import { createScrollTree } from './scroll-tree.jsx';
+import { createSeparators } from './use-separators.js';
+import { HANDLED_PROPS, } from './virtualized-list-props.js';
+// A slot wrapper counter-flips with an inverted list, then takes the slot's own style
+function slotStyleOf(props, slotStyle) {
+    return listStyleOf({
+        inverted: props.inverted === true,
+        horizontal: props.horizontal === true,
+    }, slotStyle);
+}
 export function createVirtualizedList() {
     return function VirtualizedList(props) {
-        // The ONE folded state cell (RN's scattered refs collapsed into IListState). A plain object, never
-        // a signal: nothing reads it reactively.
-        const headerElement = untrack(() => props.ListHeaderComponent);
-        const footerElement = untrack(() => props.ListFooterComponent);
-        const emptyElement = untrack(() => props.ListEmptyComponent);
-        // The scroll host, held by IDENTITY in a plain variable: a store or any proxy wrapper would be a
-        // different key than the one the engine's commit mirror holds, and every imperative command would
-        // silently no-op (symbiote-engine-core §3).
-        let hostNode = null;
-        // A LAZY node getter, not the node captured once: it is null until the tree builds, and every
-        // command re-reads it.
-        const scrollHandle = buildScrollViewHandle(() => hostNode);
+        // Each slot is read once, a JSX prop is a getter that builds the element on read
+        const header = untrack(() => props.ListHeaderComponent);
+        const footer = untrack(() => props.ListFooterComponent);
+        const empty = untrack(() => props.ListEmptyComponent);
         const [, accessibilityRest] = splitProps(props, HANDLED_PROPS);
-        const isHorizontal = () => props.horizontal === true;
-        // Drives every sticky header's translateY (RN's _scrollAnimatedValue). Allocated unconditionally,
-        // exactly like React's unconditional hook, and held by identity.
-        const scrollAnimatedValue = new AnimatedValue(0);
-        // Sticky cross-talk (RN's _headerLayoutYs): a data-index -> measured-y map so each header learns
-        // where the NEXT one starts, its push-off collision point. Mutated imperatively from each
-        // header's onLayout; the version bump is what lets the PREVIOUS header re-read it.
-        const headerLayoutYs = new Map();
-        const [stickyVersion, setStickyVersion] = createSignal(0);
-        const stickySet = createMemo(() => props.stickyHeaderIndices !== undefined
-            ? new Set(props.stickyHeaderIndices)
-            : undefined);
-        const hasStickyHeaders = () => {
-            const indices = props.stickyHeaderIndices;
-            return indices !== undefined && indices.length > FIRST_INDEX;
-        };
-        const nativeStickyAvailable = () => hasStickyHeaders() && isNativeAnimatedAvailable();
-        // RN's FlatList/SectionList expose no invertStickyHeaders of their own (only ScrollView does), so
-        // list headers always pin to the top and the inverted viewport capture is never needed.
-        const forwarding = createMemo(() => resolveScrollForwarding({
-            hasStickyHeaders: hasStickyHeaders(),
-            nativeStickyAvailable: nativeStickyAvailable(),
-            invertStickyHeaders: undefined,
-            scrollEventThrottle: props.scrollEventThrottle,
-            maintainVisibleContentPosition: props.maintainVisibleContentPosition,
-            snapToAlignment: undefined,
-        }));
-        // Inversion flips the scroll container along the scroll axis; each cell re-flips so its own content
-        // stays upright (RN does the same with a scale(-1) transform). The content CONTAINER is left alone
-        // — flipping it too would cancel the outer flip.
-        const invertedStyle = () => {
-            if (props.inverted !== true)
-                return undefined;
-            return isHorizontal() ? INVERTED_X_STYLE : INVERTED_Y_STYLE;
-        };
-        const listState = createInitialListState();
-        // Bumped on every render-relevant transition; that bump is what re-derives `metrics`. listState is
-        // a plain object, so mutating it triggers nothing on its own.
-        const [version, setVersion] = createSignal(0);
-        // Per-gap separator overrides, keyed by the LEADING cell index of the gap. Render state read
-        // directly in the cell walk, not part of the windowing orchestration, so it stays adapter-side.
-        const separatorOverrides = new Map();
-        const [separatorVersion, setSeparatorVersion] = createSignal(0);
-        // The adapter owns the timers; the reducer only asks for a delay.
-        let viewableTimer = null;
-        let batchTimer = null;
-        // The offset we are imperatively driving native to before the host node has a Fabric tag. Rides
-        // down as the scroll host's contentOffset prop; fresh object identity each push.
-        const [commandedOffset, setCommandedOffset] = createSignal(undefined);
-        function inputs() {
-            return {
-                data: props.data,
-                getItem: props.getItem,
-                getItemCount: props.getItemCount,
-                keyExtractor: props.keyExtractor,
-                getItemLayout: props.getItemLayout,
-                horizontal: isHorizontal(),
-                windowSize: props.windowSize ?? DEFAULT_WINDOW_SIZE,
-                initialNumToRender: props.initialNumToRender ?? DEFAULT_INITIAL_NUM_TO_RENDER,
-                maxToRenderPerBatch: props.maxToRenderPerBatch ?? DEFAULT_MAX_TO_RENDER_PER_BATCH,
-                updateCellsBatchingPeriod: props.updateCellsBatchingPeriod ??
-                    DEFAULT_UPDATE_CELLS_BATCHING_PERIOD,
-                onEndReachedThreshold: props.onEndReachedThreshold,
-                onStartReachedThreshold: props.onStartReachedThreshold,
-                maintainVisibleContentPosition: props.maintainVisibleContentPosition,
-                initialScrollIndex: props.initialScrollIndex,
-                onEndReachedActive: props.onEndReached !== undefined,
-                onStartReachedActive: props.onStartReached !== undefined,
-                viewabilityPairs: buildViewabilityPairs(props.onViewableItemsChanged, props.viewabilityConfig, props.viewabilityConfigCallbackPairs),
-            };
-        }
-        function keyFor(index) {
-            return resolveItemKey(props.getItem(props.data, index), index, props.keyExtractor);
-        }
-        // The work the reducer asked for, run with Solid's own primitives. The reducer DESCRIBES an
-        // effect; which timer holds a debounce and how a native scroll is dispatched stay here.
-        function runEffects(effects) {
-            for (const effect of effects) {
-                switch (effect.kind) {
-                    case 'scroll-to': {
-                        const clamped = Math.max(EMPTY_OFFSET, effect.offset);
-                        const target = {
-                            x: isHorizontal() ? clamped : EMPTY_OFFSET,
-                            y: isHorizontal() ? EMPTY_OFFSET : clamped,
-                        };
-                        // A native scrollTo needs the node's COMMITTED Fabric tag; this adapter commits on a
-                        // microtask, so a scroll requested in the same tick as mount has none yet.
-                        // contentOffset is RN's own pre-commit fallback.
-                        const node = hostNode;
-                        if (node !== null && getNativeTag(node) !== undefined) {
-                            dlog(`VirtualizedList scrollTo offset=${clamped} animated=${effect.animated}`);
-                            setCommandedOffset(undefined);
-                            scrollHandle.scrollTo({ ...target, animated: effect.animated });
-                            break;
-                        }
-                        dlog(`VirtualizedList scrollTo offset=${clamped} pending-commit`);
-                        setCommandedOffset(target);
-                        break;
-                    }
-                    case 'fire-end-reached':
-                        props.onEndReached?.({ distanceFromEnd: effect.distanceFromEnd });
-                        break;
-                    case 'fire-start-reached':
-                        props.onStartReached?.({
-                            distanceFromStart: effect.distanceFromStart,
-                        });
-                        break;
-                    case 'fire-viewable': {
-                        const pairs = inputs().viewabilityPairs;
-                        const info = effect.info;
-                        const map = effect.map;
-                        // lastViewable is folded back only when the fire actually LANDS, so a debounce superseded
-                        // mid-flight still diffs against the last committed set.
-                        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;
-                    }
-                    case 'schedule-refill':
-                        // Ask for another render tick so the throttled window keeps growing toward its target.
-                        if (batchTimer !== null)
-                            clearTimeout(batchTimer);
-                        batchTimer = setTimeout(() => {
-                            batchTimer = null;
-                            dispatch({ kind: 'batch-tick' });
-                        }, effect.delay);
-                        break;
-                    case 'fire-scroll-to-index-failed':
-                        props.onScrollToIndexFailed?.({
-                            index: effect.index,
-                            highestMeasuredFrameIndex: effect.highestMeasuredFrameIndex,
-                            averageItemLength: effect.averageItemLength,
-                        });
-                        break;
-                }
-            }
-        }
-        // Untracked by construction: dispatch is reached from native events, timers and the imperative
-        // handle, never from a render position, and reading every prop through inputs() inside a tracked
-        // scope would subscribe that scope to the whole prop surface.
-        function dispatch(action) {
-            untrack(() => {
-                const result = reduceList(listState, action, inputs());
-                runEffects(result.effects);
-                if (result.changed)
-                    setVersion(tick => tick + 1);
-            });
-        }
-        // RN animates every imperative scroll unless the caller passes animated: false; each resolves to an
-        // offset inside the reducer and then rides the native scrollTo command.
-        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();
-            },
-            // Three names for RN-API parity; SymbioteNative has no findNodeHandle / legacy-instance
-            // distinction, so all three route to the same underlying handle (see IScrollRoutingHandle).
-            getNativeScrollRef: () => scrollHandle,
-            getScrollableNode: () => scrollHandle,
-            getScrollResponder: () => scrollHandle,
-            getScrollNode: () => scrollHandle.getScrollNode(),
-            // RN's recordInteraction: flip the interaction flag so waitForInteraction viewability configs
-            // start reporting.
-            recordInteraction: () => {
-                dispatch({ kind: 'record-interaction' });
-            },
-        };
-        // Solid's `ref` is a COMPILE-TIME construct: a `ref={list}` call site has already been rewritten
-        // into a callback by the time this body reads it (utils/host-ref.ts has the full rationale).
+        const { driver, nesting, sticky, listWindow, handlers } = createListParts(props);
+        // Solid's `ref` is a compile-time construct, a `ref={list}` call site is already a callback
         if (typeof props.ref === 'function')
-            props.ref(handle);
-        function onViewportLayout(event) {
-            const length = readLayoutLength(event, isHorizontal());
-            if (length === undefined)
-                return;
-            dlog(`VirtualizedList onLayout viewport=${length}`);
-            dispatch({ kind: 'layout', length });
-        }
-        // Without getItemLayout the list learns its cell sizes from each cell's own onLayout, which is
-        // what fills the offset table the window and the spacers are computed from.
-        function makeCellMeasure(index) {
-            return (event) => {
-                const length = readLayoutLength(event, isHorizontal());
-                if (length === undefined)
-                    return;
-                const offset = readLayoutOffset(event, isHorizontal());
-                dlog(`VirtualizedList cell ${index()} measured length=${length} offset=${offset ?? 'none'}`);
-                dispatch({ kind: 'measure', index: index(), length, offset });
-            };
-        }
-        function handleScroll(event) {
-            const offset = readScrollOffset(event, isHorizontal());
-            if (offset === undefined)
-                return;
-            dlog(`VirtualizedList onScroll offset=${offset}`);
-            // A real user/native scroll supersedes any pending commanded offset.
-            setCommandedOffset(undefined);
-            dispatch({ kind: 'scroll', offset });
-            // Compose, don't clobber: internal windowing ran first, now the user's onScroll.
-            props.onScroll?.(event);
-        }
-        // Without the native animated module the sticky value has to be driven off the JS thread, so the
-        // handler is wrapped in Animated.event; the native and plain paths forward it untouched.
-        const scrollHandler = createMemo(() => {
-            if (forwarding().mode !== 'sticky-js')
-                return handleScroll;
-            return animatedEvent([{ nativeEvent: { contentOffset: { y: scrollAnimatedValue } } }], {
-                listener: (...args) => forwardScrollEvent(handleScroll, args),
-            });
-        });
-        // The single derive-per-render: the reducer recomputes the window exactly once per render pass
-        // (deriving twice would advance its throttled window two batch steps per frame).
-        const metrics = createMemo(() => {
-            version();
-            reduceList(listState, { kind: 'refresh-metrics' }, inputs());
-            return listState.metrics;
-        });
-        // The shared plan: the spacer extents plus the in-window cell keys. Every geometry decision in it
-        // is core's, so a windowing bug is fixed once for all adapters.
-        const plan = createMemo(() => {
-            const m = metrics();
-            if (m.count === FIRST_INDEX)
-                return null;
-            return buildListPlan({
-                count: m.count,
-                first: m.first,
-                last: m.last,
-                offsets: m.offsets,
-                lengths: m.lengths,
-                total: m.total,
-                keyFor,
-                stickyIndices: stickySet(),
-                hasHeader: headerElement !== undefined,
-            });
-        });
-        // forcedStickyCell is prepended to the window cells so BOTH walk through the SAME keyed <For>.
-        // Two separate template positions would give a header toggling between "forced ahead of the
-        // window" and "inside the window" no shared identity, so it would be destroyed and rebuilt
-        // (losing its measured layout, back to its default translateY) on every crossing.
-        const cells = createMemo(() => {
-            const current = plan();
-            if (current === null)
-                return [];
-            return current.forcedStickyCell !== undefined
-                ? [current.forcedStickyCell, ...current.cells]
-                : current.cells;
-        });
-        // <For> matches by VALUE identity, so the KEYS — not the plan's freshly-built cell objects — are
-        // what it walks. A key that survives a window slide keeps its row's nodes and simply moves; over
-        // the objects every row would be rebuilt on every recompute.
-        const cellKeys = createMemo(() => cells().map(cell => cell.key));
-        const cellIndexByKey = createMemo(() => new Map(cells().map((cell) => [cell.key, cell.index])));
-        // The after-commit pass, in the order every adapter runs it: batch fill, edge-reached, viewability,
-        // initial scroll, MVCP. Each is guarded by its own dedup state inside the reducer, so running it on
-        // every windowing change is safe. `on()` runs the body untracked, so this depends on the windowing
-        // SIGNATURE alone — the same dedup key every adapter shares — and not on every prop the reducer
-        // inputs touch.
-        const commitSignature = createMemo(() => {
-            metrics();
-            return listEffectSignature(listState);
-        });
-        createEffect(on(commitSignature, () => {
-            const result = reduceList(listState, { kind: 'commit' }, inputs());
-            runEffects(result.effects);
-        }));
-        // RN's ViewabilityHelper.dispose: a pending dwell timer must not outlive the list.
-        onCleanup(() => {
-            if (viewableTimer !== null)
-                clearTimeout(viewableTimer);
-            if (batchTimer !== null)
-                clearTimeout(batchTimer);
-        });
-        const isEmpty = () => metrics().count === FIRST_INDEX;
-        const leadingExtent = () => plan()?.leadingExtent ?? EMPTY_OFFSET;
-        const trailingExtent = () => plan()?.trailingExtent ?? EMPTY_OFFSET;
-        const spacerStyle = (extent) => isHorizontal() ? { width: extent } : { height: extent };
-        // Merge an override onto the separator at a given gap. A gap index outside [0, count-2] addresses
-        // no separator, so the write is a no-op (RN bails on the same bounds).
-        function mergeSeparator(gapIndex, patch) {
-            if (!isSeparatorGapInRange(gapIndex, listState.metrics.count))
-                return;
-            separatorOverrides.set(gapIndex, {
-                ...separatorOverrides.get(gapIndex),
-                ...patch,
-            });
-            setSeparatorVersion(tick => tick + 1);
-        }
-        // The ISeparators handle for the cell at `index` (RN CellRenderer._separators): highlight touches
-        // the gap before AND after this cell, so a pressed row draws a full-bleed divider on both sides.
-        function makeSeparators(index) {
-            return {
-                highlight: () => {
-                    mergeSeparator(index - 1, { highlighted: true });
-                    mergeSeparator(index, { highlighted: true });
-                },
-                unhighlight: () => {
-                    mergeSeparator(index - 1, { highlighted: false });
-                    mergeSeparator(index, { highlighted: false });
-                },
-                updateProps: (select, newProps) => {
-                    mergeSeparator(select === 'leading' ? index - 1 : index, newProps);
-                },
-            };
-        }
-        // Reads separatorVersion so a highlight()/unhighlight()/updateProps() call reactively refreshes
-        // this gap's props — separatorOverrides is a plain Map and tracks nothing on its own.
-        function separatorPropsFor(index) {
-            separatorVersion();
-            const overrides = separatorOverrides.get(index);
-            return {
-                highlighted: overrides?.highlighted === true,
-                leadingItem: props.getItem(props.data, index),
-                trailingItem: props.getItem(props.data, index + 1),
-                ...overrides,
-            };
-        }
-        function separatorElement(index) {
-            const Separator = props.ItemSeparatorComponent;
-            if (Separator === undefined)
-                return undefined;
-            // A spread of a CALL compiles to mergeProps(() => …), so the separator's props stay live.
-            return <Separator {...separatorPropsFor(index)}/>;
-        }
-        // RN renders a separator in the gap AFTER a cell, only while there is a following rendered
-        // cell — never after the window's last one, and never after the force-mounted sticky cell,
-        // which is not adjacent to the window.
-        // RN gates the separator on the last index of the DATA, not of the WINDOW
-        // (VirtualizedList.js:793): the separator lives INSIDE the measuring wrapper, so gating on the
-        // window would make a cell's own measured height change as the window slides past it.
-        const hasSeparatorAfter = (index) => props.ItemSeparatorComponent !== undefined && index < metrics().count - 1;
-        // Records a sticky header's measured y (RN's _headerLayoutYs) so the header AHEAD of it can
-        // compute its collision point; without it every header would stick indefinitely.
-        function makeStickyCellLayout(index) {
-            const measure = makeCellMeasure(index);
-            return (event) => {
-                measure(event);
-                const y = readLayoutNumber(event, 'y');
-                if (y === undefined || headerLayoutYs.get(index()) === y)
-                    return;
-                dlog(`VirtualizedList sticky header index=${index()} y=${y}`);
-                headerLayoutYs.set(index(), y);
-                setStickyVersion(tick => tick + 1);
-            };
-        }
-        // Only a header MOUNTED RIGHT NOW can collide with this one — the same restriction React gets by
-        // handing its ScrollView the RENDERED sticky positions rather than the full index list. Feeding
-        // the full list instead lets a header collide against a stale y from one that already scrolled
-        // out, freezing it in place. The map itself is deliberately NOT pruned (React does not either): a
-        // measured y stays valid for when that header scrolls back in.
-        function nextStickyHeaderYFor(index) {
-            // Read the bump FIRST so this stays a dependency of whichever header calls it — that is what
-            // turns "a later header measured" into "the previous header rebuilds its collision range".
-            stickyVersion();
-            const indices = props.stickyHeaderIndices;
-            if (indices === undefined)
-                return undefined;
-            const mounted = new Set(cells().map(cell => cell.index));
-            const rendered = indices.filter(sticky => mounted.has(sticky));
-            return nextStickyHeaderY(rendered, rendered.indexOf(index), headerLayoutYs);
-        }
-        function buildCell(index, sticky) {
-            // Called ONCE and untracked, the shape Solid core uses for its own render props: a tracked call
-            // would put the item signals in the cell's `insert` effect and rebuild this whole subtree on
-            // every window step (.claude/rules/solid-descriptor-bridge.md §4).
-            const content = untrack(() => props.renderItem(() => ({
-                item: props.getItem(props.data, index()),
-                index: index(),
-                separators: makeSeparators(index()),
-            })));
-            // The separator rides INSIDE the measuring wrapper (VirtualizedListCellRenderer.js:218-221).
-            // As a SIBLING it would be an extra flex child, landing every cell below the leading spacer
-            // short by (separator + gap) — see `list-geometry-feedback-loop.md`.
-            const separator = (<Show when={hasSeparatorAfter(index())}>
-          <view>{separatorElement(index())}</view>
-        </Show>);
-            if (!sticky) {
-                return (<view onLayout={makeCellMeasure(index)} style={invertedStyle()}>
-            {content}
-            {separator}
-          </view>);
-            }
-            // The sticky wrapper measures the cell itself, so it REPLACES the plain measuring view rather
-            // than nesting inside it. Every reactive input is written as a CALL, which makes the compiler
-            // emit a getter the header reads inside its OWN effect — a resolved value here would join the
-            // enclosing insert effect and rebuild every header on every layout.
-            return (<ScrollViewStickyHeader onLayout={makeStickyCellLayout(index)} nextHeaderLayoutY={nextStickyHeaderYFor(index())} scrollAnimatedValue={scrollAnimatedValue} inverted={undefined} scrollViewHeight={undefined}>
-          {content}
-          {separator}
-        </ScrollViewStickyHeader>);
-        }
-        function buildRow(key) {
-            // The row is keyed by its cell key, so its data INDEX moves under it as the window slides. The
-            // previous value is the fallback for the tick between a key leaving the plan and <For>
-            // disposing its row.
-            const index = createMemo((previous) => cellIndexByKey().get(key) ?? previous, NO_INDEX);
-            const isSticky = createMemo(() => stickySet()?.has(index()) === true);
-            // A sticky cell is a different host subtree, not a different prop, and Solid has no reconciler
-            // to swap one for the other — so the flip is an explicit rebuild boundary keyed on the
-            // DISCRIMINATOR alone, with the build untracked by `on()`.
-            const cell = createMemo(on(isSticky, sticky => buildCell(index, sticky)));
-            const forcedStickyIndex = () => plan()?.forcedStickyCell?.index;
-            const gapExtent = () => plan()?.gapExtent ?? EMPTY_OFFSET;
-            return [
-                cell,
-                // The gap between the force-mounted sticky cell and the window's first cell.
-                <Show when={forcedStickyIndex() === index() && gapExtent() > EMPTY_OFFSET}>
-          <view style={spacerStyle(gapExtent())}/>
-        </Show>,
-            ];
-        }
-        // The scroll host's own intrinsics. A horizontal list resolves DIFFERENT host tags (on Android
-        // horizontal scrolling is a separate ViewManager entirely) and lays its content out in a row.
-        // A class-name string resolves through the shared registry before it reaches the intrinsic
-        // selector, which only understands style objects/arrays.
-        const contentContainerStyleInput = () => {
-            const style = props.contentContainerStyle;
-            return typeof style === 'string' ? resolveClassName(style) : style;
+            props.ref(driver.handle);
+        const rowDeps = {
+            props,
+            listWindow,
+            metrics: driver.metrics,
+            separators: createSeparators(props, driver.currentCount),
+            sticky,
+            measureCell: handlers.measureCell,
+            focusCell: handlers.focusCell,
         };
-        const intrinsics = createMemo(() => selectScrollIntrinsics(isHorizontal(), contentContainerStyleInput()));
-        // The composed content style RN's ScrollView carries: the app's contentContainerStyle plus the
-        // one thing only THIS list knows — the total content extent along the scroll axis, which pins
-        // the content to its measured width so a horizontal row has something to scroll (RN's own
-        // ScrollView never needs this; it never virtualizes). The behavior's own `contentFold` appends
-        // the row-direction style on top of whatever this resolves to (`core/components/src/behaviors/
-        // scroll-view/shared.ts`), same composition `intrinsics().contentStyle` used to build by hand.
-        const contentContainerStyleForContent = () => isHorizontal()
-            ? [contentContainerStyleInput(), { width: metrics().total }]
-            : contentContainerStyleInput();
-        // withStableKeys because several keys below are conditional and Solid's `spread` walks only the
-        // CURRENT key set with no removal pass — a key that vanished would keep its last value on the
-        // native view forever (.claude/rules/solid-descriptor-bridge.md §1).
-        //
-        // No `wrapsRefreshControl`/`splitStyles`/base-style composition here any more: the tag's own
-        // engine behavior owns the content node, the base-style-under-the-app's-style composition, the
-        // Android-wrap style split (`splitScrollViewStyle`, read off exactly the `style` written below),
-        // `nestedScrollEnabled`'s default and the `horizontal` axis fold — this file only supplies what
-        // the behavior cannot know (the windowing metrics).
-        const outerBag = withStableKeys(() => {
-            const bag = {
-                ...resolveAccessibilityProps(accessibilityRest),
-                // VirtualizedList.js: `[inversionStyle, style]` — the app's style can override the flip.
-                style: [invertedStyle(), props.style],
-                class: props.class,
-                contentContainerStyle: contentContainerStyleForContent(),
-                onLayout: onViewportLayout,
-                onScroll: scrollHandler(),
-            };
-            // VirtualizedList.js:1111 — Android moves the scrollbar back after the `scale: -1` flip.
-            if (props.inverted === true)
-                bag.isInvertedVirtualizedList = true;
-            // forwarding's throttle, not the raw prop: it folds in the sticky-mode default (1 native / 16
-            // JS-fallback), without which a header rebuilt off too-sparse scroll events pins late.
-            if (forwarding().scrollEventThrottle !== undefined)
-                bag.scrollEventThrottle = forwarding().scrollEventThrottle;
-            if (props.onScrollBeginDrag !== undefined)
-                bag.onScrollBeginDrag = props.onScrollBeginDrag;
-            if (props.onScrollEndDrag !== undefined)
-                bag.onScrollEndDrag = props.onScrollEndDrag;
-            if (props.onMomentumScrollBegin !== undefined)
-                bag.onMomentumScrollBegin = props.onMomentumScrollBegin;
-            if (props.onMomentumScrollEnd !== undefined)
-                bag.onMomentumScrollEnd = props.onMomentumScrollEnd;
-            if (props.keyboardShouldPersistTaps !== undefined)
-                bag.keyboardShouldPersistTaps = props.keyboardShouldPersistTaps;
-            if (props.keyboardDismissMode !== undefined)
-                bag.keyboardDismissMode = props.keyboardDismissMode;
-            // Forwarded so native anchors the cells it CAN see; the JS half (the prepended items collapsed
-            // into the leading spacer) is the reducer's. minIndexForVisible counts CHILDREN, so it is
-            // bumped by one when a ListHeaderComponent occupies child 0.
-            const commanded = commandedOffset();
-            if (commanded !== undefined)
-                bag.contentOffset = commanded;
-            const mvcp = props.maintainVisibleContentPosition;
-            if (mvcp !== undefined) {
-                bag.maintainVisibleContentPosition = {
-                    ...mvcp,
-                    minIndexForVisible: mvcp.minIndexForVisible +
-                        (headerElement !== undefined ? HEADER_CHILD_COUNT : FIRST_INDEX),
-                };
-            }
-            return bag;
-        });
-        // Every reactive read below sits inside a <Show>/<For> prop getter, so this accessor itself has no
-        // dependencies and the content view's `insert` effect runs exactly ONCE. Moving one of those
-        // conditions into a plain helper called from here would put it in that effect's dependency set and
-        // rebuild the whole list on the next scroll (.claude/rules/solid-descriptor-bridge.md §4).
-        function listBody() {
-            return [
-                <Show when={headerElement !== undefined}>
-          <view>{headerElement}</view>
-        </Show>,
-                <Show when={isEmpty()} fallback={<>
-              <Show when={leadingExtent() > EMPTY_OFFSET}>
-                <view style={spacerStyle(leadingExtent())}/>
-              </Show>
-              <For each={cellKeys()}>{buildRow}</For>
-              <Show when={trailingExtent() > EMPTY_OFFSET}>
-                <view style={spacerStyle(trailingExtent())}/>
-              </Show>
-            </>}>
-          <Show when={emptyElement !== undefined}>
-            <view>{emptyElement}</view>
-          </Show>
-        </Show>,
-                <Show when={footerElement !== undefined}>
-          <view>{footerElement}</view>
-        </Show>,
-            ];
-        }
-        function hostElement(tag) {
-            const node = createElement(tag);
-            // Narrowing, not defensive: the renderer types createElement over its IHostNode union (which
-            // includes the surface), while everything below needs a real host node.
-            if (!isSymbioteNode(node))
-                throw new Error(`VirtualizedList: ${tag} did not create a host node`);
-            return node;
-        }
-        // Built ONCE per tree: `refreshing` is written as a CALL, so the compiler emits a getter and the
-        // controlled state keeps reaching this same node.
-        function buildRefreshControl() {
-            const onRefresh = props.onRefresh;
-            if (onRefresh === undefined)
-                return undefined;
-            dlog('VirtualizedList wiring RefreshControl (onRefresh provided)');
-            const element = (<refresh-control refreshing={props.refreshing ?? false} onRefresh={onRefresh} progressViewOffset={props.progressViewOffset}/>);
-            return isSymbioteNode(element) ? element : undefined;
-        }
-        // The scroll host, wired to the ENGINE-OWNED content node rather than a hand-built one. Once
-        // `registerScrollViewBehavior()` is live, `createElement(scrollViewIntrinsic)` already ran the
-        // behavior's `buildStructure` and appended its own content child as `childHost` — building a
-        // second one here would nest `RCTScrollContentView > RCTScrollContentView`
-        // (`core/components/src/behaviors/scroll-view/shared.ts`'s own header names this precondition).
-        function buildTree() {
-            const { scrollViewIntrinsic } = intrinsics();
-            dlog(`VirtualizedList -> ${scrollViewIntrinsic}`);
-            const scroll = hostElement(scrollViewIntrinsic);
-            hostNode = scroll;
-            spread(scroll, outerBag, true);
-            const content = scroll.childHost;
-            if (content === undefined)
-                throw new Error(`VirtualizedList: ${scrollViewIntrinsic} built no content node — is ` +
-                    'registerScrollViewBehavior() wired?');
-            insert(content, listBody);
-            // An ordinary child on both platforms now, not a hand-branched sibling/wrap: the behavior's
-            // own `claimedChildren` places it (a sibling of the content view on iOS, an inverting wrap on
-            // Android) and puts it BEFORE the content view regardless of insertion order.
-            const refresh = buildRefreshControl();
-            if (refresh !== undefined)
-                insertNode(scroll, refresh);
-            // A wrap claim re-parents `scroll` under the RefreshControl and records it as `scroll.wrapper`
-            // (`core/engine/src/node.ts`'s `placedNode`) — the wrapper, not `scroll`, is what actually
-            // occupies this subtree's place once claimed, so returning `scroll` on Android would hand back
-            // a node that is no longer the tree's root.
-            return scroll.wrapper ?? scroll;
-        }
-        // Drive the sticky scroll value on the native UI thread (RN's attachNativeEvent) so the header
-        // interpolations ride scroll natively with no JS per frame. `tree()` is read for its dependency:
-        // a rebuild means a NEW scroll node to attach to. The engine commits on a microtask, so the node
-        // has no Fabric tag on the first run and the attach would no-op with no retry — whenCommitted is
-        // that retry.
-        function attachSticky() {
-            createEffect(() => {
-                tree();
-                if (!nativeStickyAvailable())
-                    return;
-                const node = hostNode;
-                if (node === null)
-                    return;
-                let detach;
-                const cancel = whenCommitted(node, () => {
-                    detach = attachStickyScroll(node, scrollAnimatedValue);
-                });
-                onCleanup(() => {
-                    cancel();
-                    detach?.();
-                });
-            });
-        }
-        // The scroll AXIS picks a different host TAG and Solid cannot swap a tag under a live node, so the
-        // flip REBUILDS — which is exactly what React does when an element type changes. `on()` runs
-        // buildTree untracked, so every other read inside it re-props the SAME nodes through `spread`
-        // instead of rebuilding them.
-        const treeShape = createMemo(() => String(isHorizontal()));
-        const tree = createMemo(on(treeShape, () => buildTree()));
-        attachSticky();
-        return tree;
+        return provideVirtualizedListScope(nesting.scope, () => createScrollTree({
+            props,
+            accessibility: () => resolveAccessibilityProps(accessibilityRest),
+            driver,
+            sticky,
+            handlers,
+            nesting,
+            hasHeader: header !== undefined,
+            body: () => listBody({
+                header,
+                footer,
+                empty,
+                headerStyle: () => slotStyleOf(props, props.ListHeaderComponentStyle),
+                footerStyle: () => slotStyleOf(props, props.ListFooterComponentStyle),
+                emptyStyle: () => slotStyleOf(props, undefined),
+                isEmpty: () => driver.metrics().count === FIRST_INDEX,
+                rowKeys: listWindow.rowKeys,
+                renderRow: rowKey => buildRow(rowDeps, rowKey),
+            }),
+        }));
     };
 }