@symbiote-native/solid 3.2.0 → 3.3.0

package/build/components/virtualized-list/sticky-binding.d.ts

@@ -0,0 +1,13 @@
+import { type Accessor } from 'solid-js';
+import { type IStickyHeaderProps } from '@symbiote-native/components';
+import { type AnimatedNode, type ISymbioteEvent } from '@symbiote-native/engine';
+export type IStickyBinding = {
+    animatedTranslateY: Accessor<AnimatedNode>;
+    committedStyle: Accessor<{
+        transform: {
+            translateY: number;
+        }[];
+    } | undefined>;
+    onLayout: (event: ISymbioteEvent) => void;
+};
+export declare function createStickyBinding(props: IStickyHeaderProps): IStickyBinding;

package/build/components/virtualized-list/sticky-binding.js

@@ -0,0 +1,111 @@
+// Solid's reactivity around the shared sticky reducer: one state cell, a signal for the
+// interpolation node, a version counter for the committed transform, and the listener wiring
+import { createEffect, createMemo, createSignal, onCleanup, } from 'solid-js';
+import { buildStickyPin, createInitialStickyState, readLayoutNumber, reduceSticky, } from '@symbiote-native/components';
+import { Platform, dlog, } from '@symbiote-native/engine';
+function detachListener(runtime) {
+    const { interpolation, listenerId } = runtime.held;
+    if (interpolation !== undefined && listenerId !== undefined) {
+        interpolation.removeListener(listenerId);
+    }
+    runtime.held.listenerId = undefined;
+}
+function dispatchSticky(runtime, action) {
+    runEffects(runtime, reduceSticky(runtime.state, action, runtime.inputs()).effects);
+}
+function rebuild(runtime, effect) {
+    dlog(`Solid ScrollViewStickyHeader[y=${runtime.state.layoutY}] rebuild ` +
+        `inputRange=${JSON.stringify(effect.inputRange)} outputRange=${JSON.stringify(effect.outputRange)}`);
+    detachListener(runtime);
+    const next = buildStickyPin(runtime.scrollAnimatedValue, effect, effect.hideOffset);
+    // Feeds only the debounced committed transform, the visible pin is the native connection
+    runtime.held.listenerId = next.addListener(({ value }) => {
+        if (typeof value === 'number') {
+            dispatchSticky(runtime, { kind: 'animated-tick', value });
+        }
+    });
+    runtime.held.interpolation = next;
+    runtime.setAnimatedTranslateY(next);
+}
+// The animated value updates several times per frame, hit detection needs the settled one
+function debounce(runtime, value, delay) {
+    const { held } = runtime;
+    if (held.debounceTimer !== undefined)
+        clearTimeout(held.debounceTimer);
+    held.debounceTimer = setTimeout(() => {
+        held.debounceTimer = undefined;
+        dispatchSticky(runtime, { kind: 'debounce-fired', value });
+    }, delay);
+}
+function runEffects(runtime, effects) {
+    for (const effect of effects) {
+        switch (effect.kind) {
+            case 'rebuild-interpolation':
+                rebuild(runtime, effect);
+                break;
+            case 'schedule-debounce':
+                debounce(runtime, effect.value, effect.delay);
+                break;
+            case 'apply-passthrough':
+                dlog(`Solid ScrollViewStickyHeader[y=${runtime.state.layoutY}] passthrough translateY=${effect.translateY}`);
+                runtime.setVersion(tick => tick + 1);
+                break;
+            case 'record-header-y':
+                // `onLayout` of the wrapper records it, the reducer never needs an index here
+                break;
+        }
+    }
+}
+// Every prop that changes over time is read here INSIDE an effect, as a call, so the header
+// tracks it itself and the list's `insert` effect never sees those signals
+export function createStickyBinding(props) {
+    const [version, setVersion] = createSignal(0);
+    // The unmeasured identity stub until the first rebuild replaces it
+    const [animatedTranslateY, setAnimatedTranslateY] = createSignal(props.scrollAnimatedValue.interpolate({
+        inputRange: [-1, 0],
+        outputRange: [0, 0],
+    }));
+    const runtime = {
+        state: createInitialStickyState(),
+        scrollAnimatedValue: props.scrollAnimatedValue,
+        setAnimatedTranslateY,
+        setVersion,
+        inputs: () => ({
+            os: Platform.OS,
+            inverted: props.inverted,
+            hiddenOnScroll: props.hiddenOnScroll,
+            scrollViewHeight: props.scrollViewHeight,
+            nextHeaderLayoutY: props.nextHeaderLayoutY,
+        }),
+        held: {
+            interpolation: undefined,
+            listenerId: undefined,
+            debounceTimer: undefined,
+        },
+    };
+    // Rebuilds on a collision or viewport input change and once on mount
+    createEffect(() => dispatchSticky(runtime, { kind: 'inputs-changed' }));
+    onCleanup(() => {
+        detachListener(runtime);
+        if (runtime.held.debounceTimer !== undefined) {
+            clearTimeout(runtime.held.debounceTimer);
+        }
+    });
+    // RN also re-invokes the `onLayout` of the wrapped child, here that child is committed in its
+    // own right and Fabric fires its listener directly
+    const onLayout = (event) => {
+        const { state } = runtime;
+        dispatchSticky(runtime, {
+            kind: 'layout',
+            y: readLayoutNumber(event, 'y') ?? state.layoutY,
+            height: readLayoutNumber(event, 'height') ?? state.layoutHeight,
+        });
+        props.onLayout(event);
+    };
+    const committedStyle = createMemo(() => {
+        version();
+        const { translateY } = runtime.state;
+        return translateY === null ? undefined : { transform: [{ translateY }] };
+    });
+    return { animatedTranslateY, committedStyle, onLayout };
+}

package/build/components/virtualized-list/sticky-header.d.ts

@@ -2,5 +2,6 @@ import type { JSX } from '../../jsx-runtime';
 import { type IStickyHeaderProps } from '@symbiote-native/components';
 export type IStickyHeaderComponentProps = IStickyHeaderProps & {
     children?: JSX.Element;
+    onFocus?: () => void;
 };
 export declare function ScrollViewStickyHeader(props: IStickyHeaderComponentProps): JSX.Element;

package/build/components/virtualized-list/sticky-header.jsx

@@ -1,168 +1,20 @@
-// Sticky headers — the Solid lifecycle half of the JS layer RN implements in ScrollView.js /
-// ScrollViewStickyHeader.js.
+// Sticky headers, the Solid lifecycle half of the JS layer RN keeps in `ScrollViewStickyHeader`
 //
-// PRIVATE TO VIRTUALIZED-LIST: `<scroll-view>` honors `stickyHeaderIndices` via the engine's own
-// `sticky-header` intrinsic with no adapter code. VirtualizedList still needs its OWN
-// implementation because it hand-builds its scroll host, so `shared.tsx` wraps the cell directly.
-//
-// RN does stickiness PURELY IN JS: ScrollView wraps each flagged child in a ScrollViewStickyHeader
-// fed by ONE scroll AnimatedValue, and the native scroll view ignores `stickyHeaderIndices`
-// entirely — forwarding that array to Fabric is a silent no-op, so we replicate the JS layer
-// instead. The math (top and inverted input/output ranges) is `computeStickyInterpolation` and the
-// DECISIONS (the zero-swallow gate, the debounce window, when to rebuild) are `reduceSticky`, both
-// in @symbiote-native/components and both shared verbatim with React, Vue and Angular. This file
-// contributes only Solid's reactivity: one signal for the interpolation node, one version counter,
-// the listener/debounce wiring, and the child-wrapping.
-//
-// WHY THE WRAPPER TAKES ITS REACTIVE INPUTS AS PROPS AND NOT AS RESOLVED VALUES. Every prop below
-// that changes over time — `nextHeaderLayoutY` (cross-talk as a later header measures),
-// `scrollViewHeight` (the inverted viewport capture), `inverted` — is written into the JSX as a
-// CALL, so the Solid compiler emits it as a getter and the header reads it inside its OWN effect.
-// That is not a style choice: the wrap runs inside the content view's `insert` render effect, and
-// `insert` REPLACES a subtree rather than diffing one, so a value read there would put those
-// signals in the insert effect's dependency set and every header layout would tear down and rebuild
-// every header. React/Vue/Angular can pass plain values because each has a node-reusing layer
-// underneath; Solid does not (.claude/rules/solid-descriptor-bridge.md §4).
-import { createEffect, createMemo, createSignal, onCleanup } from 'solid-js';
-import { createInitialStickyState, readLayoutNumber, reduceSticky, STICKY_HEADER_Z_INDEX, } from '@symbiote-native/components';
-import { AnimatedInterpolation, Platform, dlog, } from '@symbiote-native/engine';
-// One sticky header. Measures its own y/height through onLayout, interpolates the shared scroll
-// offset into a translateY that pins it to the top (or the bottom, inverted) until the next header
-// collides with it, and drives that translate through the native driver when available so the pin
-// tracks scroll on the UI thread with no JS per frame.
+// Private to VirtualizedList: it hand-builds its scroll host, so `shared.tsx` wraps the cell here
+// The math and the decisions live in `@symbiote-native/components`, the binding in `sticky-binding`
+import { STICKY_HEADER_Z_INDEX, } from '@symbiote-native/components';
+import { createStickyBinding } from './sticky-binding.js';
+// Pins a cell to the top (or the bottom, inverted) until the next header collides with it
+// `collapsable: false` keeps it a real Yoga node, the zIndex paints it over the rows under it
 export function ScrollViewStickyHeader(props) {
-    // The ONE folded state cell (RN's scattered useState/useRef, collapsed into IStickyHeaderState),
-    // mutated in place by reduceSticky. A plain object, never a signal: nothing reads it reactively —
-    // the two signals below are what render depends on.
-    const state = createInitialStickyState();
-    // Bumped on every committed translateY so the passthrough memo re-reads state.translateY (RN's
-    // forceRender()).
-    const [version, setVersion] = createSignal(0);
-    // Read ONCE and held by identity: the value is stable for the header's lifetime by contract (the
-    // parent allocates exactly one per ScrollView).
-    const scrollAnimatedValue = props.scrollAnimatedValue;
-    // The interpolation node currently bound into style.transform — the un-measured identity stub
-    // until the first rebuild-interpolation effect replaces it. A signal, not a plain variable:
-    // render has to repaint when it is swapped.
-    const [animatedTranslateY, setAnimatedTranslateY] = createSignal(scrollAnimatedValue.interpolate({
-        inputRange: [-1, 0],
-        outputRange: [0, 0],
-    }));
-    // Held so the next rebuild can detach the previous settled-value listener (an engine call the
-    // reducer does not own) and cleanup can drop both.
-    let interpolation;
-    let listenerId;
-    let debounceTimer;
-    const inputs = () => ({
-        os: Platform.OS,
-        inverted: props.inverted,
-        scrollViewHeight: props.scrollViewHeight,
-        nextHeaderLayoutY: props.nextHeaderLayoutY,
-    });
-    function runEffects(effects) {
-        for (const effect of effects) {
-            switch (effect.kind) {
-                case 'rebuild-interpolation': {
-                    dlog(`Solid ScrollViewStickyHeader[y=${state.layoutY}] rebuild-interpolation ` +
-                        `inputRange=${JSON.stringify(effect.inputRange)} outputRange=${JSON.stringify(effect.outputRange)}`);
-                    if (interpolation !== undefined && listenerId !== undefined) {
-                        interpolation.removeListener(listenerId);
-                        listenerId = undefined;
-                    }
-                    const next = scrollAnimatedValue.interpolate({
-                        inputRange: effect.inputRange,
-                        outputRange: effect.outputRange,
-                    });
-                    // Feeds ONLY the debounced committed transform below (RN adds this listener solely on
-                    // Fabric, for hit-testing); the visible pin is the native AnimatedProps connection.
-                    listenerId = next.addListener(({ value }) => {
-                        if (typeof value === 'number')
-                            dispatch({ kind: 'animated-tick', value });
-                    });
-                    interpolation = next;
-                    setAnimatedTranslateY(next);
-                    break;
-                }
-                case 'schedule-debounce':
-                    // The animated value updates several times per frame; debounce the settled value into the
-                    // committed transform so hit detection stays current (a Fabric issue, worse on Android).
-                    if (debounceTimer !== undefined)
-                        clearTimeout(debounceTimer);
-                    debounceTimer = setTimeout(() => {
-                        debounceTimer = undefined;
-                        dispatch({ kind: 'debounce-fired', value: effect.value });
-                    }, effect.delay);
-                    break;
-                case 'apply-passthrough':
-                    dlog(`Solid ScrollViewStickyHeader[y=${state.layoutY}] apply-passthrough translateY=${effect.translateY}`);
-                    setVersion(tick => tick + 1);
-                    break;
-                case 'record-header-y':
-                    // Solid records through the wrapper's own onLayout closure (the public
-                    // IStickyHeaderProps.onLayout contract, same as React/Vue), so the reducer never emits an
-                    // index for it.
-                    break;
-            }
-        }
-    }
-    function dispatch(action) {
-        runEffects(reduceSticky(state, action, inputs()).effects);
-    }
-    // Rebuild whenever a collision/viewport input changes (RN's [inverted, scrollViewHeight,
-    // nextHeaderLayoutY] dep array); also does the initial identity build on mount. All three are read
-    // through inputs() INSIDE the effect, which is what makes them dependencies — a guarded or
-    // deferred read would silently drop one.
-    createEffect(() => {
-        runEffects(reduceSticky(state, { kind: 'inputs-changed' }, inputs()).effects);
-    });
-    onCleanup(() => {
-        if (interpolation !== undefined && listenerId !== undefined) {
-            interpolation.removeListener(listenerId);
-        }
-        if (debounceTimer !== undefined)
-            clearTimeout(debounceTimer);
-    });
-    // RN's ScrollViewStickyHeader._onLayout additionally re-invokes the wrapped child's OWN onLayout.
-    // Deliberately not replicated: by the time a Solid component sees `children` they are already
-    // real engine nodes, and a node's listeners live in the engine's event map, not as a readable JS
-    // prop — there is nothing to re-invoke. Nothing is lost, because the child node is committed in
-    // its own right and Fabric fires its onLayout at it directly; React/Vue's forwarding actually
-    // makes a child handler run twice.
-    const onLayout = (event) => {
-        const y = readLayoutNumber(event, 'y');
-        const height = readLayoutNumber(event, 'height');
-        // Keep the previous value when a field is absent (RN sets state only on a defined read).
-        dispatch({
-            kind: 'layout',
-            y: y ?? state.layoutY,
-            height: height ?? state.layoutHeight,
-        });
-        props.onLayout(event);
-    };
-    // The EXPLICIT debounced translateY overrides the committed transform for hit-testing, while
-    // animatedTranslateY does the smooth (native-driven) pin. It rides the style ARRAY now rather
-    // than `passthroughAnimatedPropExplicitValues`: that prop was read by `createAnimatedComponent`,
-    // and the host is a bare tag, where the engine ignores it
-    // (core/engine/src/animated/host-binding.ts calls it a wrapper-ism by name). The wrapper did
-    // exactly this merge — `[reduced.style, passthroughStyle]` — so a later array entry overriding
-    // the transform is the same semantics, one layer down, and the engine still binds the
-    // interpolation it finds in entry 0.
-    const passthrough = createMemo(() => {
-        // Read the bump so a committed translateY repaints.
-        version();
-        if (state.translateY === null)
-            return undefined;
-        return { transform: [{ translateY: state.translateY }] };
-    });
-    // collapsable:false keeps the wrapper a real Yoga node; zIndex makes the pinned header paint OVER
-    // the rows scrolling up under it.
+    const binding = createStickyBinding(props);
     return (<view style={[
             {
-                transform: [{ translateY: animatedTranslateY() }],
+                transform: [{ translateY: binding.animatedTranslateY() }],
                 zIndex: STICKY_HEADER_Z_INDEX,
             },
-            passthrough(),
-        ]} onLayout={onLayout} collapsable={false}>
+            binding.committedStyle(),
+        ]} onLayout={binding.onLayout} onFocus={props.onFocus} collapsable={false}>
       {props.children}
     </view>);
 }

package/build/components/virtualized-list/sticky-state.d.ts

@@ -0,0 +1,14 @@
+import { type Accessor } from 'solid-js';
+import { resolveScrollForwarding } from '@symbiote-native/components';
+import { AnimatedValue, type ISymbioteEvent } from '@symbiote-native/engine';
+import type { IVirtualizedListProps } from './virtualized-list-props';
+type ICellMeasure = (event: ISymbioteEvent) => void;
+export type IStickyState = {
+    scrollAnimatedValue: AnimatedValue;
+    forwarding: Accessor<ReturnType<typeof resolveScrollForwarding>>;
+    nativeStickyAvailable: () => boolean;
+    makeStickyCellLayout: (index: Accessor<number>, measure: ICellMeasure) => ICellMeasure;
+    nextStickyHeaderYFor: (index: number, mounted: ReadonlySet<number>) => number | undefined;
+};
+export declare function createStickyState<ItemT>(props: IVirtualizedListProps<ItemT>): IStickyState;
+export {};

package/build/components/virtualized-list/sticky-state.js

@@ -0,0 +1,54 @@
+// Sticky header state: the scroll value that drives each header and the cross-talk between them
+import { createMemo, createSignal } from 'solid-js';
+import { FIRST_INDEX, nextStickyHeaderY, readLayoutNumber, resolveScrollForwarding, } from '@symbiote-native/components';
+import { AnimatedValue, dlog, isNativeAnimatedAvailable, } from '@symbiote-native/engine';
+export function createStickyState(props) {
+    // Data index to measured y, so each header learns where the NEXT one starts (its push-off point)
+    // `stickyVersion` lets the previous header re-read the map
+    const headerLayoutYs = new Map();
+    const [stickyVersion, setStickyVersion] = createSignal(0);
+    const hasStickyHeaders = () => {
+        const indices = props.stickyHeaderIndices;
+        return indices !== undefined && indices.length > FIRST_INDEX;
+    };
+    const nativeStickyAvailable = () => hasStickyHeaders() && isNativeAnimatedAvailable();
+    // RN's list has no `invertStickyHeaders`, so headers always pin to the top
+    const forwarding = createMemo(() => resolveScrollForwarding({
+        hasStickyHeaders: hasStickyHeaders(),
+        nativeStickyAvailable: nativeStickyAvailable(),
+        invertStickyHeaders: undefined,
+        scrollEventThrottle: props.scrollEventThrottle,
+        maintainVisibleContentPosition: props.maintainVisibleContentPosition,
+        snapToAlignment: undefined,
+    }));
+    // Without the measured y the header AHEAD of this one has no collision point and sticks forever
+    const makeStickyCellLayout = (index, measure) => {
+        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, a stale y from one that scrolled out freezes it
+    // The map is deliberately not pruned, a measured y stays valid for when it scrolls back in
+    const nextStickyHeaderYFor = (index, mounted) => {
+        // Read the bump first so this stays a dependency of whichever header calls it
+        stickyVersion();
+        const indices = props.stickyHeaderIndices;
+        if (indices === undefined)
+            return undefined;
+        const rendered = indices.filter(sticky => mounted.has(sticky));
+        return nextStickyHeaderY(rendered, rendered.indexOf(index), headerLayoutYs);
+    };
+    return {
+        scrollAnimatedValue: new AnimatedValue(0),
+        forwarding,
+        nativeStickyAvailable,
+        makeStickyCellLayout,
+        nextStickyHeaderYFor,
+    };
+}

package/build/components/virtualized-list/use-list-driver.d.ts

@@ -0,0 +1,22 @@
+import { type Accessor } from 'solid-js';
+import { type IListAction, type IListMetrics, type IListReducerInputs, type IListState, type IVirtualizedListHandle } from '@symbiote-native/components';
+import { type ISymbioteNode } from '@symbiote-native/engine';
+import type { IVirtualizedListProps } from './virtualized-list-props';
+type ICommandedOffset = {
+    x: number;
+    y: number;
+};
+export type IListDriver<ItemT> = {
+    metrics: Accessor<IListMetrics>;
+    dispatch: (action: IListAction<ItemT>) => void;
+    handle: IVirtualizedListHandle;
+    currentCount: () => number;
+    getState: () => IListState<ItemT>;
+    getHostNode: () => ISymbioteNode | null;
+    setHostNode: (node: ISymbioteNode | null) => void;
+    commandedOffset: Accessor<ICommandedOffset | undefined>;
+    clearCommandedOffset: () => void;
+};
+type IFindFirstChildWithMore = IListReducerInputs<unknown>['findFirstChildWithMore'];
+export declare function createListDriver<ItemT>(props: IVirtualizedListProps<ItemT>, findFirstChildWithMore: IFindFirstChildWithMore): IListDriver<ItemT>;
+export {};

package/build/components/virtualized-list/use-list-driver.js

@@ -0,0 +1,128 @@
+// The list's lifecycle: one folded state cell, native events turned into reducer actions, and the
+// returned effects run with Solid primitives
+import { createEffect, createMemo, createSignal, on, onCleanup, untrack, } from 'solid-js';
+import { DEFAULT_INITIAL_NUM_TO_RENDER, DEFAULT_MAX_TO_RENDER_PER_BATCH, DEFAULT_UPDATE_CELLS_BATCHING_PERIOD, DEFAULT_WINDOW_SIZE, LIST_ACTION_KIND, buildListHandle, buildListReducerInputs, buildScrollViewHandle, buildViewabilityPairs, clearTimers, createInitialListState, listEffectSignature, reduceList, runListEffects, scrollTargetOf, } from '@symbiote-native/components';
+import { dlog, getNativeTag, } from '@symbiote-native/engine';
+function viewabilityPairsOf(props) {
+    return buildViewabilityPairs(props.onViewableItemsChanged, props.viewabilityConfig, props.viewabilityConfigCallbackPairs);
+}
+function reducerInputsOf(props, findFirstChildWithMore) {
+    return buildListReducerInputs({
+        findFirstChildWithMore,
+        data: props.data,
+        getItem: props.getItem,
+        getItemCount: props.getItemCount,
+        keyExtractor: props.keyExtractor,
+        getItemLayout: props.getItemLayout,
+        horizontal: props.horizontal === true,
+        windowSize: props.windowSize ?? DEFAULT_WINDOW_SIZE,
+        disableVirtualization: props.disableVirtualization,
+        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,
+        onEndReached: props.onEndReached,
+        onStartReached: props.onStartReached,
+    }, viewabilityPairsOf(props));
+}
+// The host node is held by identity in a plain variable, a store or proxy would be a different key
+// than the engine's commit mirror holds and every imperative command would silently no-op
+function createScrollTarget(props) {
+    let hostNode = null;
+    const scrollHandle = buildScrollViewHandle(() => hostNode);
+    const [commandedOffset, setCommandedOffset] = createSignal(undefined);
+    // A native `scrollTo` needs the committed Fabric tag and this adapter commits on a microtask, so
+    // a scroll requested in the tick of mount rides `contentOffset` instead
+    const scrollToPixel = (offset, animated) => {
+        const target = scrollTargetOf(offset, props.horizontal === true);
+        if (hostNode !== null && getNativeTag(hostNode) !== undefined) {
+            dlog(`VirtualizedList scrollTo offset=${offset} animated=${animated}`);
+            setCommandedOffset(undefined);
+            scrollHandle.scrollTo({ ...target, animated });
+            return;
+        }
+        dlog(`VirtualizedList scrollTo offset=${offset} pending-commit`);
+        setCommandedOffset(target);
+    };
+    return {
+        scrollHandle,
+        scrollToPixel,
+        commandedOffset,
+        clearCommandedOffset: () => setCommandedOffset(undefined),
+        setHostNode: (node) => {
+            hostNode = node;
+        },
+        getHostNode: () => hostNode,
+    };
+}
+// Kept apart so the driver body reads as state, memos and effects, with the host wiring named
+function effectHostOf(props, scrollToPixel, getDispatch, [viewableTimer, batchTimer]) {
+    return {
+        callbacks: () => ({
+            onEndReached: props.onEndReached,
+            onStartReached: props.onStartReached,
+            onScrollToIndexFailed: props.onScrollToIndexFailed,
+            viewabilityPairs: viewabilityPairsOf(props),
+        }),
+        scrollToPixel,
+        dispatch: getDispatch,
+        viewableTimer,
+        batchTimer,
+    };
+}
+export function createListDriver(props, findFirstChildWithMore) {
+    const listState = createInitialListState();
+    // Bumped on every render-relevant transition, `listState` is plain and triggers nothing itself
+    const [version, setVersion] = createSignal(0);
+    const target = createScrollTarget(props);
+    const viewableTimer = { current: null };
+    const batchTimer = { current: null };
+    const host = effectHostOf(props, target.scrollToPixel, () => dispatch, [
+        viewableTimer,
+        batchTimer,
+    ]);
+    // Untracked by construction: it is reached from native events, timers and the imperative handle,
+    // and reading every prop through the inputs in a tracked scope would subscribe it to all of them
+    function dispatch(action) {
+        untrack(() => {
+            const result = reduceList(listState, action, reducerInputsOf(props, findFirstChildWithMore));
+            runListEffects(result.effects, host);
+            if (result.changed)
+                setVersion(tick => tick + 1);
+        });
+    }
+    // The window is recomputed once per pass, deriving twice would advance the throttle twice
+    const metrics = createMemo(() => {
+        version();
+        reduceList(listState, { kind: LIST_ACTION_KIND.refreshMetrics }, reducerInputsOf(props, findFirstChildWithMore));
+        return listState.metrics;
+    });
+    const commitSignature = createMemo(() => {
+        metrics();
+        return listEffectSignature(listState);
+    });
+    // `on()` runs the body untracked, so the commit pass depends on the windowing signature alone
+    createEffect(on(commitSignature, () => {
+        const result = reduceList(listState, { kind: LIST_ACTION_KIND.commit }, reducerInputsOf(props, findFirstChildWithMore));
+        runListEffects(result.effects, host);
+    }));
+    onCleanup(() => clearTimers([viewableTimer, batchTimer]));
+    return {
+        metrics,
+        dispatch,
+        handle: buildListHandle({
+            dispatch,
+            scrollHandle: target.scrollHandle,
+            getNode: target.getHostNode,
+        }),
+        currentCount: () => listState.metrics.count,
+        getState: () => listState,
+        getHostNode: target.getHostNode,
+        setHostNode: target.setHostNode,
+        commandedOffset: target.commandedOffset,
+        clearCommandedOffset: target.clearCommandedOffset,
+    };
+}

package/build/components/virtualized-list/use-separators.d.ts

@@ -0,0 +1,7 @@
+import { type ISeparatorProps, type ISeparators } from '@symbiote-native/components';
+import type { IVirtualizedListProps } from './virtualized-list-props';
+export type IListSeparators<ItemT> = {
+    makeSeparators: (index: number) => ISeparators;
+    separatorPropsFor: (index: number) => ISeparatorProps<ItemT>;
+};
+export declare function createSeparators<ItemT>(props: IVirtualizedListProps<ItemT>, currentCount: () => number): IListSeparators<ItemT>;

package/build/components/virtualized-list/use-separators.js

@@ -0,0 +1,22 @@
+// Per-gap separator overrides, read straight by the cell walk
+import { createSignal } from 'solid-js';
+import { buildSeparatorHandles, buildSeparatorProps, isSeparatorGapInRange, } from '@symbiote-native/components';
+// Keyed by the leading cell index of the gap, a gap outside [0, count - 2] addresses no separator
+export function createSeparators(props, currentCount) {
+    const overrides = new Map();
+    const [version, setVersion] = createSignal(0);
+    const mergeSeparator = (gapIndex, patch) => {
+        if (!isSeparatorGapInRange(gapIndex, currentCount()))
+            return;
+        overrides.set(gapIndex, { ...overrides.get(gapIndex), ...patch });
+        setVersion(tick => tick + 1);
+    };
+    return {
+        makeSeparators: index => buildSeparatorHandles(index, mergeSeparator),
+        // Reads `version` so a highlight call reactively refreshes this gap, the Map tracks nothing
+        separatorPropsFor: index => {
+            version();
+            return buildSeparatorProps(props.getItem(props.data, index), props.getItem(props.data, index + 1), overrides.get(index));
+        },
+    };
+}

package/build/components/virtualized-list/virtualized-list-props.d.ts

@@ -0,0 +1,86 @@
+import type { Accessor, Ref } from 'solid-js';
+import type { JSX } from '../../jsx-runtime';
+import type { IAccessibilityProps, IAriaProps, ICellRendererBaseProps, IInnerViewRef, ISeparatorProps, ISeparators, IViewabilityConfig, IViewabilityConfigCallbackPair, IViewableItemsChangedInfo, IVirtualizedListHandle } from '@symbiote-native/components';
+import type { IClassNameValue, IStyleProp, ISymbioteEvent, IViewStyle } from '@symbiote-native/engine';
+export type ICellRendererProps<ItemT> = ICellRendererBaseProps<ItemT> & {
+    children?: JSX.Element;
+};
+export type ICellRendererComponent<ItemT> = (props: ICellRendererProps<ItemT>) => JSX.Element;
+export type IVirtualizedListCellInfo<ItemT> = {
+    item: ItemT;
+    index: number;
+    separators: ISeparators;
+};
+export type IVirtualizedListRenderItem<ItemT> = (info: Accessor<IVirtualizedListCellInfo<ItemT>>) => JSX.Element;
+export type IVirtualizedListProps<ItemT> = IAccessibilityProps & IAriaProps & {
+    data: unknown;
+    getItem: (data: unknown, index: number) => ItemT;
+    getItemCount: (data: unknown) => number;
+    renderItem?: IVirtualizedListRenderItem<ItemT>;
+    ListItemComponent?: (props: IVirtualizedListCellInfo<ItemT>) => JSX.Element;
+    getItemLayout?: (data: unknown, index: number) => {
+        length: number;
+        offset: number;
+        index: number;
+    };
+    initialNumToRender?: number;
+    windowSize?: number;
+    disableVirtualization?: boolean;
+    ListHeaderComponent?: JSX.Element;
+    ListFooterComponent?: JSX.Element;
+    ListEmptyComponent?: JSX.Element;
+    ItemSeparatorComponent?: (props: ISeparatorProps<ItemT>) => JSX.Element;
+    CellRendererComponent?: ICellRendererComponent<ItemT>;
+    ref?: Ref<IVirtualizedListHandle>;
+    onEndReached?: (info: {
+        distanceFromEnd: number;
+    }) => void;
+    onEndReachedThreshold?: number;
+    onStartReached?: (info: {
+        distanceFromStart: number;
+    }) => void;
+    onStartReachedThreshold?: number;
+    keyExtractor?: (item: ItemT, index: number) => string;
+    onViewableItemsChanged?: (info: IViewableItemsChangedInfo<ItemT>) => void;
+    viewabilityConfig?: IViewabilityConfig;
+    viewabilityConfigCallbackPairs?: IViewabilityConfigCallbackPair<ItemT>[];
+    onScroll?: (event: ISymbioteEvent) => void;
+    onScrollBeginDrag?: (event: ISymbioteEvent) => void;
+    onScrollEndDrag?: (event: ISymbioteEvent) => void;
+    onMomentumScrollBegin?: (event: ISymbioteEvent) => void;
+    onMomentumScrollEnd?: (event: ISymbioteEvent) => void;
+    onContentSizeChange?: (width: number, height: number) => void;
+    scrollEventThrottle?: number;
+    keyboardShouldPersistTaps?: boolean | 'always' | 'never' | 'handled';
+    keyboardDismissMode?: 'none' | 'on-drag' | 'interactive';
+    removeClippedSubviews?: boolean;
+    nestedScrollEnabled?: boolean;
+    stickyHeaderHiddenOnScroll?: boolean;
+    innerViewRef?: IInnerViewRef;
+    horizontal?: boolean;
+    inverted?: boolean;
+    style?: IStyleProp<IViewStyle>;
+    contentContainerStyle?: IStyleProp<IViewStyle> | string;
+    ListHeaderComponentStyle?: IStyleProp<IViewStyle>;
+    ListFooterComponentStyle?: IStyleProp<IViewStyle>;
+    class?: IClassNameValue;
+    onRefresh?: () => void;
+    refreshing?: boolean | null;
+    progressViewOffset?: number;
+    stickyHeaderIndices?: number[];
+    maintainVisibleContentPosition?: {
+        minIndexForVisible: number;
+        autoscrollToTopThreshold?: number;
+    };
+    initialScrollIndex?: number;
+    maxToRenderPerBatch?: number;
+    updateCellsBatchingPeriod?: number;
+    extraData?: unknown;
+    onScrollToIndexFailed?: (info: {
+        index: number;
+        highestMeasuredFrameIndex: number;
+        averageItemLength: number;
+    }) => void;
+};
+export type IVirtualizedListComponent = <ItemT>(props: IVirtualizedListProps<ItemT>) => JSX.Element;
+export declare const HANDLED_PROPS: readonly ["data", "getItem", "getItemCount", "renderItem", "ListItemComponent", "getItemLayout", "initialNumToRender", "windowSize", "disableVirtualization", "ListHeaderComponent", "ListFooterComponent", "ListEmptyComponent", "ItemSeparatorComponent", "CellRendererComponent", "ref", "onEndReached", "onEndReachedThreshold", "onStartReached", "onStartReachedThreshold", "keyExtractor", "onViewableItemsChanged", "viewabilityConfig", "viewabilityConfigCallbackPairs", "onScroll", "onScrollBeginDrag", "onScrollEndDrag", "onMomentumScrollBegin", "onMomentumScrollEnd", "scrollEventThrottle", "keyboardShouldPersistTaps", "keyboardDismissMode", "horizontal", "inverted", "style", "contentContainerStyle", "ListHeaderComponentStyle", "ListFooterComponentStyle", "class", "onScrollToIndexFailed", "onRefresh", "refreshing", "progressViewOffset", "stickyHeaderIndices", "maintainVisibleContentPosition", "initialScrollIndex", "maxToRenderPerBatch", "updateCellsBatchingPeriod", "extraData"];