@symbiote-native/solid 0.0.1 → 0.1.0

package/build/components/scroll-view/index.ios.js

@@ -0,0 +1,8 @@
+// ScrollView on iOS. The RefreshControl (PullToRefreshView) is a CHILD of the scroll view, rendered
+// as a childless SIBLING BEFORE the content container — RN ScrollView.js's
+// `{refreshControl}{contentContainer}`, the same fact adapters/react's, adapters/vue's and
+// adapters/svelte's iOS bindings encode. Metro picks this file on an iOS host; no Platform.OS read.
+import { createScrollView } from './shared.jsx';
+export const ScrollView = createScrollView({
+    refreshControlMode: 'sibling',
+});

package/build/components/scroll-view/index.js

@@ -0,0 +1,9 @@
+// Base / default ScrollView: re-exports the iOS build. Metro overrides this with index.ios.ts /
+// index.android.ts on a real host; under vitest / tsc the resolution lands here. Filename is the
+// selector, no Platform.OS read.
+//
+// ScrollViewStickyHeader is exported from here rather than from the platform files: it has no
+// platform branch of its own, and an app may compose it directly around a section instead of going
+// through `stickyHeaderIndices`.
+export * from './index.ios.js';
+export { ScrollViewStickyHeader } from './sticky-header.jsx';

package/build/components/scroll-view/shared.d.ts

@@ -0,0 +1,85 @@
+import { type Ref } from 'solid-js';
+import type { JSX } from '../../jsx-runtime';
+import { type IAccessibilityProps, type IAriaProps, type IScrollViewHandle } from '@symbiote-native/components';
+import { type IClassNameValue, type IStyleProp, type ISymbioteEvent, type IViewStyle } from '@symbiote-native/engine';
+import { type IStickyHeaderComponentType } from './sticky-header';
+export type { IScrollViewHandle } from '@symbiote-native/components';
+export type { IStickyHeaderComponentType, IStickyHeaderComponentProps, } from './sticky-header';
+type IScrollHandler = (event: ISymbioteEvent) => void;
+export type IScrollViewHostPlatform = {
+    refreshControlMode: 'sibling' | 'wrap';
+};
+export interface IScrollViewProps extends IAccessibilityProps, IAriaProps {
+    style?: IStyleProp<IViewStyle>;
+    class?: IClassNameValue;
+    contentContainerStyle?: IStyleProp<IViewStyle> | string;
+    horizontal?: boolean;
+    scrollEnabled?: boolean;
+    showsVerticalScrollIndicator?: boolean;
+    showsHorizontalScrollIndicator?: boolean;
+    pagingEnabled?: boolean;
+    bounces?: boolean;
+    decelerationRate?: 'normal' | 'fast' | number;
+    scrollEventThrottle?: number;
+    contentInset?: {
+        top?: number;
+        left?: number;
+        bottom?: number;
+        right?: number;
+    };
+    contentOffset?: {
+        x: number;
+        y: number;
+    };
+    refreshControl?: JSX.Element;
+    removeClippedSubviews?: boolean;
+    onContentSizeChange?: (width: number, height: number) => void;
+    snapToInterval?: number;
+    snapToOffsets?: number[];
+    snapToAlignment?: 'start' | 'center' | 'end';
+    snapToStart?: boolean;
+    snapToEnd?: boolean;
+    disableIntervalMomentum?: boolean;
+    stickyHeaderIndices?: number[];
+    invertStickyHeaders?: boolean;
+    StickyHeaderComponent?: IStickyHeaderComponentType;
+    keyboardDismissMode?: 'none' | 'on-drag' | 'interactive';
+    keyboardShouldPersistTaps?: boolean | 'always' | 'never' | 'handled';
+    maintainVisibleContentPosition?: {
+        minIndexForVisible: number;
+        autoscrollToTopThreshold?: number;
+    };
+    alwaysBounceHorizontal?: boolean;
+    alwaysBounceVertical?: boolean;
+    centerContent?: boolean;
+    scrollIndicatorInsets?: {
+        top?: number;
+        left?: number;
+        bottom?: number;
+        right?: number;
+    };
+    indicatorStyle?: 'default' | 'black' | 'white';
+    directionalLockEnabled?: boolean;
+    automaticallyAdjustKeyboardInsets?: boolean;
+    contentInsetAdjustmentBehavior?: 'automatic' | 'scrollableAxes' | 'never' | 'always';
+    minimumZoomScale?: number;
+    maximumZoomScale?: number;
+    zoomScale?: number;
+    bouncesZoom?: boolean;
+    pinchGestureEnabled?: boolean;
+    nestedScrollEnabled?: boolean;
+    overScrollMode?: 'auto' | 'always' | 'never';
+    fadingEdgeLength?: number;
+    persistentScrollbar?: boolean;
+    endFillColor?: string;
+    onLayout?: IScrollHandler;
+    onScroll?: IScrollHandler;
+    onScrollBeginDrag?: IScrollHandler;
+    onScrollEndDrag?: IScrollHandler;
+    onMomentumScrollBegin?: IScrollHandler;
+    onMomentumScrollEnd?: IScrollHandler;
+    onScrollToTop?: IScrollHandler;
+    ref?: Ref<IScrollViewHandle>;
+    children?: JSX.Element;
+}
+export declare function createScrollView(platform: IScrollViewHostPlatform): (props: IScrollViewProps) => JSX.Element;

package/build/components/scroll-view/shared.jsx

@@ -0,0 +1,334 @@
+// ScrollView — the Solid lifecycle half. The Fabric tree is nested: a scroll view wraps a content
+// view that holds the children (RN's own ScrollView.js shape). Everything platform- and
+// framework-invariant already exists in @symbiote-native/components and is CALLED, never re-derived:
+// `selectScrollIntrinsics` (per-axis tags + base styles), `resolveDecelerationRate`,
+// `resolveScrollForwarding` (which onScroll path, the 1/16 throttle defaults, the inverted viewport
+// capture, collapsableChildren), `didContentSizeChange`, `buildScrollViewHandle`,
+// `splitLayoutProps`, `attachStickyScroll`, `forwardScrollEvent`, `resolveAccessibilityProps`.
+// Solid supplies signals, effects and the element assembly.
+//
+// THREE THINGS ARE SOLID-SPECIFIC AND NONE OF THEM IS COSMETIC.
+//
+// 1. There is no reconciler between what this file returns and the host nodes. React diffs fibers,
+//    Vue diffs vnodes, Svelte patches in place; Solid's `insert` REPLACES. So the tree is built ONCE
+//    and every prop rides a `spread` render effect on the SAME node — the identity
+//    dispatchViewCommand, the commit mirror and native-owned scroll offset all key on. The only
+//    rebuild is when the host TAG itself has to change (see `treeShape` below).
+// 2. A JSX element prop is a GETTER that CREATES the element on read, so `refreshControl` is read
+//    exactly once. A second read would build a second refresh-control node.
+// 3. The commit is microtask-coalesced (`requestCommit`), so at mount time the scroll node has no
+//    Fabric tag. Anything native wired then — here, the sticky scroll attach — goes through
+//    `whenCommitted` or it silently no-ops with no retry. The imperative handle is safe without it
+//    for a different reason: `buildScrollViewHandle` takes a LAZY node getter and every command
+//    re-reads it, so a handle handed out at setup keeps working once the node commits.
+//
+// NOTHING here destructures `props`. Solid props are getters and a component body runs ONCE;
+// `splitProps` is the idiomatic split that keeps the rest reactive, and every read below sits inside
+// an accessor, a memo, or an event handler.
+import { children, createEffect, createMemo, createRenderEffect, createSignal, on, onCleanup, splitProps, untrack, } from 'solid-js';
+import { attachStickyScroll, buildScrollViewHandle, didContentSizeChange, forwardScrollEvent, nextStickyHeaderY, readLayoutDimension, resolveAccessibilityProps, resolveDecelerationRate, resolveScrollForwarding, selectScrollIntrinsics, splitLayoutProps, } from '@symbiote-native/components';
+import { AnimatedValue, dlog, event as animatedEvent, isNativeAnimatedAvailable, isSymbioteNode, resolveClassName, whenCommitted, } from '@symbiote-native/engine';
+import { createElement, insert, insertNode, setProp, spread, } from '../../renderer.js';
+import { withStableKeys } from '../../utils/stable-keys.js';
+import { wrapStickyHeaders, } from './sticky-header.jsx';
+// Consumed by the lifecycle itself; everything else forwards onto the scroll-view host node.
+// onContentSizeChange is synthesized from the content view's onLayout and must never reach Fabric —
+// a function prop crashes Android's folly::dynamic serializer. Same for the sticky props, which
+// native ignores, and `refreshControl`, which is an element.
+const HANDLED_PROPS = [
+    'style',
+    'class',
+    'contentContainerStyle',
+    'horizontal',
+    'decelerationRate',
+    'refreshControl',
+    'stickyHeaderIndices',
+    'invertStickyHeaders',
+    'StickyHeaderComponent',
+    'onContentSizeChange',
+    'onLayout',
+    'onScroll',
+    'scrollEventThrottle',
+    'children',
+    'ref',
+];
+// `maintainVisibleContentPosition`, `snapToAlignment` and `nestedScrollEnabled` are deliberately NOT
+// in that list: the lifecycle READS them (for resolveScrollForwarding and RN's nested-scroll
+// default) while native also needs them, so they forward through `rest` untouched.
+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(`ScrollView: ${tag} did not create a host node`);
+    return node;
+}
+export function createScrollView(platform) {
+    return function ScrollView(props) {
+        const [local, rest] = splitProps(props, HANDLED_PROPS);
+        // The scroll-view host node, held by IDENTITY in a plain variable. A store or any proxy wrapper
+        // would become 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 scrollNode = null;
+        // A LAZY getter, not the node captured once: it is null until buildTree runs, and null again
+        // under it if the tree is ever rebuilt.
+        const handle = buildScrollViewHandle(() => scrollNode);
+        // Read ONCE and untracked — see the module header, point 2. Nothing reactive is lost: a
+        // RefreshControl's live state is `refreshing`, which is a prop of the element itself.
+        const refreshControlElement = untrack(() => local.refreshControl);
+        const refreshControlNode = isSymbioteNode(refreshControlElement)
+            ? refreshControlElement
+            : undefined;
+        const isWrappingRefreshControl = platform.refreshControlMode === 'wrap' &&
+            refreshControlNode !== undefined;
+        // 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);
+        // Inverted sticky headers stick to the BOTTOM, so they need the viewport height (RN
+        // _handleLayout). Captured off the scroll view's own onLayout.
+        const [viewportHeight, setViewportHeight] = createSignal(undefined);
+        // Sticky-header cross-talk (RN's _headerLayoutYs): a child-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 [headerLayoutVersion, setHeaderLayoutVersion] = createSignal(0);
+        // RN fires the content onLayout on every layout pass; only a real size change emits.
+        let lastContentSize = null;
+        const isHorizontal = () => local.horizontal === true;
+        const stickyHeaderIndices = createMemo(() => local.stickyHeaderIndices);
+        const hasStickyHeaders = () => {
+            const indices = stickyHeaderIndices();
+            return indices !== undefined && indices.length > 0;
+        };
+        const nativeStickyAvailable = () => hasStickyHeaders() && isNativeAnimatedAvailable();
+        // A class-name string resolves through the shared registry before it reaches the intrinsic
+        // selector, which only understands style objects/arrays.
+        const resolvedContentContainerStyle = () => {
+            const style = local.contentContainerStyle;
+            return typeof style === 'string' ? resolveClassName(style) : style;
+        };
+        const intrinsics = createMemo(() => selectScrollIntrinsics(isHorizontal(), resolvedContentContainerStyle()));
+        // `class` is normally forwarded raw and resolved per-node at commit time, but the Android
+        // RefreshControl wrap has to splitLayoutProps() BEFORE that, so a class-only layout prop
+        // (flex, height, gap, …) would otherwise never reach the wrapper and it would collapse to
+        // nothing.
+        const layoutSplitStyle = () => [
+            resolveClassName(local.class),
+            local.style,
+        ];
+        const splitStyles = createMemo(() => splitLayoutProps(layoutSplitStyle()));
+        const forwarding = createMemo(() => resolveScrollForwarding({
+            hasStickyHeaders: hasStickyHeaders(),
+            nativeStickyAvailable: nativeStickyAvailable(),
+            invertStickyHeaders: local.invertStickyHeaders,
+            scrollEventThrottle: local.scrollEventThrottle,
+            maintainVisibleContentPosition: props.maintainVisibleContentPosition,
+            snapToAlignment: props.snapToAlignment,
+        }));
+        // onScroll: the JS-fallback path wraps the user's handler in Animated.event so the offset drives
+        // the AnimatedValue each frame (RN's _scrollAnimatedValueAttachment); the native and plain paths
+        // forward it as-is, because the native driver attaches the value on the UI thread instead.
+        const scrollHandler = createMemo(() => {
+            const userOnScroll = local.onScroll;
+            if (forwarding().mode !== 'sticky-js')
+                return userOnScroll;
+            return animatedEvent([{ nativeEvent: { contentOffset: { y: scrollAnimatedValue } } }], userOnScroll === undefined
+                ? undefined
+                : {
+                    listener: (...args) => forwardScrollEvent(userOnScroll, args),
+                });
+        });
+        // onLayout on the scroll-view node: capture the viewport height for inverted sticky headers
+        // (RN _handleLayout), then call the user's handler. Passed through unchanged otherwise, so a
+        // ScrollView with neither never raises the onLayout flag prop and native never measures it.
+        const scrollLayoutHandler = createMemo(() => {
+            const userOnLayout = local.onLayout;
+            if (!forwarding().capturesViewportHeight)
+                return userOnLayout;
+            return (event) => {
+                const height = readLayoutDimension(event, 'height');
+                if (height !== undefined)
+                    setViewportHeight(height);
+                userOnLayout?.(event);
+            };
+        });
+        const handleContentLayout = (event) => {
+            const width = readLayoutDimension(event, 'width');
+            const height = readLayoutDimension(event, 'height');
+            if (width === undefined || height === undefined)
+                return;
+            if (!didContentSizeChange(lastContentSize, { width, height }))
+                return;
+            lastContentSize = { width, height };
+            dlog(`Solid ScrollView contentSizeChange ${width}x${height}`);
+            local.onContentSizeChange?.(width, height);
+        };
+        const onHeaderLayoutY = (index, y) => {
+            if (headerLayoutYs.get(index) === y)
+                return;
+            headerLayoutYs.set(index, y);
+            dlog(`Solid ScrollView sticky-header layoutY index=${index} y=${y}`);
+            setHeaderLayoutVersion(tick => tick + 1);
+        };
+        const readNextHeaderLayoutY = (indexOfIndex) => {
+            // 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".
+            headerLayoutVersion();
+            const indices = stickyHeaderIndices();
+            if (indices === undefined)
+                return undefined;
+            return nextStickyHeaderY(indices, indexOfIndex, headerLayoutYs);
+        };
+        // withStableKeys on BOTH bags: resolveAccessibilityProps has two branches with different key
+        // sets, and several keys below are conditional. Solid's `spread` walks only the CURRENT keys and
+        // has no removal pass, so a vanished key would keep its last value on the native view forever
+        // (.claude/rules/solid-descriptor-bridge.md §1).
+        const outerBag = withStableKeys(() => {
+            const bag = {
+                ...resolveAccessibilityProps(rest),
+            };
+            // RN defaults nested scrolling ON (ScrollView.js `nestedScrollEnabled ?? true`): Android needs
+            // it for a scrollable nested inside another to scroll independently; iOS handles nesting
+            // natively. The Android RefreshControl wrap forces it, so the inner scroll view takes the
+            // gesture before the refresh parent.
+            bag.nestedScrollEnabled = isWrappingRefreshControl
+                ? true
+                : (props.nestedScrollEnabled ?? true);
+            // Load-bearing on iOS (it flips RCTScrollView's axis), ignored by Android's dedicated
+            // horizontal manager — so forward it whenever it is defined.
+            if (local.horizontal !== undefined)
+                bag.horizontal = local.horizontal;
+            const rate = local.decelerationRate;
+            if (rate !== undefined)
+                bag.decelerationRate = resolveDecelerationRate(rate);
+            // Base style UNDER the user style, so an explicit height / flexDirection still wins. Under the
+            // Android wrap only the VISUAL half stays here; the LAYOUT half moved to the wrapper.
+            bag.style = [
+                intrinsics().scrollViewBaseStyle,
+                isWrappingRefreshControl ? splitStyles().inner : local.style,
+            ];
+            // Stripped under the wrap: layoutSplitStyle already folded the resolved class into
+            // outer/inner, so forwarding it raw too would re-apply its LAYOUT half a second time.
+            if (!isWrappingRefreshControl)
+                bag.class = local.class;
+            bag.onScroll = scrollHandler();
+            bag.onLayout = scrollLayoutHandler();
+            bag.scrollEventThrottle = forwarding().scrollEventThrottle;
+            return bag;
+        });
+        // `collapsable: false` is load-bearing on Android: the content container is a layout-only view
+        // that Fabric would otherwise flatten away, hoisting the cells up as DIRECT children of the
+        // scroll view — which hosts exactly one ("addViewAt" crash). iOS never flattens.
+        const contentBag = withStableKeys(() => {
+            const bag = {
+                style: intrinsics().contentStyle,
+                collapsable: false,
+            };
+            // maintainVisibleContentPosition (and Android snapToAlignment) anchor against the metrics of
+            // MOUNTED cell views, so RN keeps them un-flattened too (ScrollView.js preserveChildren).
+            if (forwarding().collapsableChildren)
+                bag.collapsableChildren = false;
+            if (local.onContentSizeChange !== undefined)
+                bag.onLayout = handleContentLayout;
+            return bag;
+        });
+        function mountChildren(content) {
+            if (!hasStickyHeaders()) {
+                // The plain path hands `insert` the raw children accessor, so its own nested-effect
+                // machinery keeps updates fine-grained — a <For> inside re-runs only its own insert.
+                insert(content, () => local.children);
+                return;
+            }
+            // Sticky wrapping needs an INDEXABLE list, which is what solid's `children()` helper resolves
+            // to. It costs a coarser update (any child change re-runs the whole wrap), which is why it is
+            // created ONLY here and not for every ScrollView — and it must not coexist with the accessor
+            // above, since reading `local.children` twice would build the subtree twice.
+            const resolved = children(() => local.children);
+            insert(content, () => wrapStickyHeaders(resolved.toArray(), {
+                stickyHeaderIndices: stickyHeaderIndices() ?? [],
+                scrollAnimatedValue,
+                readInverted: () => local.invertStickyHeaders,
+                readScrollViewHeight: viewportHeight,
+                readNextHeaderLayoutY,
+                StickyHeaderComponent: local.StickyHeaderComponent,
+                onHeaderLayoutY,
+            }));
+        }
+        function buildTree() {
+            const { scrollViewIntrinsic, contentIntrinsic } = intrinsics();
+            dlog(`Solid ScrollView -> ${scrollViewIntrinsic} (horizontal=${String(isHorizontal())} sticky=${String(hasStickyHeaders())})`);
+            const content = hostElement(contentIntrinsic);
+            spread(content, contentBag, true);
+            mountChildren(content);
+            const scroll = hostElement(scrollViewIntrinsic);
+            scrollNode = scroll;
+            spread(scroll, outerBag, true);
+            // iOS: the RefreshControl is a childless SIBLING placed BEFORE the content container (RN
+            // ScrollView.js: {refreshControl}{contentContainer}).
+            if (refreshControlNode !== undefined && !isWrappingRefreshControl) {
+                insertNode(scroll, refreshControlNode);
+            }
+            insertNode(scroll, content);
+            if (refreshControlNode === undefined || !isWrappingRefreshControl)
+                return scroll;
+            // Android: the RefreshControl WRAPS the scroll view. React does this with cloneElement and Vue
+            // by re-invoking the VNode's type; Solid has neither, because the element arrived already
+            // built — so the scroll view is nested into the existing node and the outer style is written
+            // onto it. A render effect, not a one-shot set, so a later style/class change still moves.
+            //
+            // This OVERRIDES a `style` the app put on the RefreshControl itself, exactly as React's
+            // cloneElement({style}) does. Unlike React's, the two writers are independent render effects,
+            // so an app that styles BOTH boxes on Android has no defined winner — pass the ScrollView's
+            // layout through `style`/`class` there and leave the control's own `style` alone.
+            createRenderEffect(() => {
+                setProp(refreshControlNode, 'style', splitStyles().outer);
+            });
+            insertNode(refreshControlNode, scroll);
+            return refreshControlNode;
+        }
+        // The scroll AXIS picks a different host TAG (horizontal is a separate ViewManager on Android)
+        // and sticky headers pick a different children pipeline. Solid cannot swap a tag under a live
+        // node, so either flip REBUILDS — which is exactly what React does when an element type changes.
+        // `on()` runs buildTree untracked, so every other read inside it (style, class, handlers,
+        // contentContainerStyle) re-props the SAME nodes through `spread` instead of rebuilding them.
+        const treeShape = createMemo(() => `${String(isHorizontal())}:${String(hasStickyHeaders())}`);
+        const tree = createMemo(on(treeShape, () => buildTree()));
+        // Solid's `ref` is a COMPILE-TIME construct: by the time a component body reads `props.ref`, a
+        // `ref={scroller}` call site has already been rewritten into a callback. The full rationale (and
+        // why the declared type still has to be the `Ref<T>` union) is in utils/host-ref.ts, whose
+        // helper is typed for a host node — this hands back the imperative handle instead.
+        //
+        // Called AFTER `tree` has built at least once, not right after `handle` is constructed.
+        // `createAnimatedComponent`'s captureRef (resolveHostNode) reads handle.getScrollNode()
+        // EAGERLY, once, at ref-call time - it never re-reads the lazy getter later. React's
+        // useImperativeHandle and Vue's expose() fire only after the child's own mount work, so they
+        // never saw a null handle; Solid's `ref` is called by the component itself and has to be
+        // sequenced by hand. Calling it before `buildTree()` gave captureRef a permanently-null node,
+        // so Animated.ScrollView's onScroll never native-attached - a scroll-linked header fade froze
+        // at its initial value on this adapter only.
+        if (typeof local.ref === 'function')
+            local.ref(handle);
+        // Drive the sticky scroll value on the native UI thread (RN's attachNativeEvent /
+        // _updateAnimatedNodeAttachment), so the header interpolations ride scroll natively with no JS
+        // jitter. `tree()` is read for its dependency: a rebuild means a NEW scroll node to attach to.
+        createEffect(() => {
+            tree();
+            if (!nativeStickyAvailable())
+                return;
+            const node = scrollNode;
+            if (node === null)
+                return;
+            let detach;
+            // The engine commits on a microtask, so this node has no Fabric tag yet on the first run and
+            // the attach would no-op with no retry. whenCommitted is that retry.
+            const cancel = whenCommitted(node, () => {
+                detach = attachStickyScroll(node, scrollAnimatedValue);
+            });
+            onCleanup(() => {
+                cancel();
+                detach?.();
+            });
+        });
+        return tree;
+    };
+}

package/build/components/scroll-view/sticky-header.d.ts

@@ -0,0 +1,18 @@
+import type { JSX } from '../../jsx-runtime';
+import { type IStickyHeaderProps } from '@symbiote-native/components';
+import { type AnimatedValue } from '@symbiote-native/engine';
+export type IStickyHeaderComponentProps = IStickyHeaderProps & {
+    children?: JSX.Element;
+};
+export type IStickyHeaderComponentType = (props: IStickyHeaderComponentProps) => JSX.Element;
+export declare function ScrollViewStickyHeader(props: IStickyHeaderComponentProps): JSX.Element;
+export interface IStickyWrapInputs {
+    stickyHeaderIndices: number[];
+    scrollAnimatedValue: AnimatedValue;
+    readInverted: () => boolean | undefined;
+    readScrollViewHeight: () => number | undefined;
+    readNextHeaderLayoutY: (indexOfIndex: number) => number | undefined;
+    StickyHeaderComponent: IStickyHeaderComponentType | undefined;
+    onHeaderLayoutY: (index: number, y: number) => void;
+}
+export declare function wrapStickyHeaders(children: readonly JSX.Element[], inputs: IStickyWrapInputs): JSX.Element[];

package/build/components/scroll-view/sticky-header.jsx

@@ -0,0 +1,182 @@
+// Sticky headers — the Solid lifecycle half of the JS layer RN implements in ScrollView.js /
+// ScrollViewStickyHeader.js.
+//
+// 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, isSymbioteNode, } from '@symbiote-native/engine';
+import { Animated } from '../../modules/animated/index.js';
+// 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.
+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.
+    const passthrough = createMemo(() => {
+        // Read the bump so a committed translateY repaints.
+        version();
+        if (state.translateY === null)
+            return null;
+        return { style: { 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.
+    return (<Animated.View style={{
+            transform: [{ translateY: animatedTranslateY() }],
+            zIndex: STICKY_HEADER_Z_INDEX,
+        }} onLayout={onLayout} collapsable={false} passthroughAnimatedPropExplicitValues={passthrough()}>
+      {props.children}
+    </Animated.View>);
+}
+// Wrap each child flagged by `stickyHeaderIndices` in the sticky header component, fed by the shared
+// scroll AnimatedValue (RN ScrollView.js's render-time children.map). Unflagged children pass
+// through untouched.
+//
+// Cross-talk (RN's _headerLayoutYs + _onStickyHeaderLayout): each header reports its own y through
+// `onHeaderLayoutY`, and every header is fed the y of the NEXT flagged one — the point past which it
+// gets pushed off. The LAST flagged header has no successor, so its nextHeaderLayoutY stays
+// undefined and it sticks indefinitely, which is correct.
+export function wrapStickyHeaders(children, inputs) {
+    const Wrapper = inputs.StickyHeaderComponent ?? ScrollViewStickyHeader;
+    return children.map((child, index) => {
+        const indexOfIndex = inputs.stickyHeaderIndices.indexOf(index);
+        // A non-node child (a bare string or number in a scroll view) has no frame to pin and cannot be
+        // wrapped meaningfully, so it passes through like an unflagged one.
+        if (indexOfIndex === -1 || !isSymbioteNode(child))
+            return child;
+        dlog(`Solid ScrollView sticky-header wrap index=${index}`);
+        return (<Wrapper nextHeaderLayoutY={inputs.readNextHeaderLayoutY(indexOfIndex)} onLayout={(event) => {
+                const y = readLayoutNumber(event, 'y');
+                if (y !== undefined)
+                    inputs.onHeaderLayoutY(index, y);
+            }} scrollAnimatedValue={inputs.scrollAnimatedValue} inverted={inputs.readInverted()} scrollViewHeight={inputs.readScrollViewHeight()}>
+        {child}
+      </Wrapper>);
+    });
+}

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

@@ -0,0 +1,6 @@
+import type { JSX } from '../../jsx-runtime';
+import { type IVirtualizedSectionListHandle, type IVirtualizedSectionListProps } from '../virtualized-section-list';
+export type { ISection } from '../virtualized-section-list';
+export type ISectionListProps<ItemT> = IVirtualizedSectionListProps<ItemT>;
+export type ISectionListHandle = IVirtualizedSectionListHandle;
+export declare function SectionList<ItemT>(props: ISectionListProps<ItemT>): JSX.Element;