@symbiote-native/react 0.1.0

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

@@ -0,0 +1,98 @@
+import { type ReactElement, type ReactNode, type RefObject } from 'react';
+import { AnimatedValue, type ISymbioteEvent, type ISymbioteNode } from '@symbiote-native/engine';
+import { type ISymbioteIntrinsic } from '@symbiote-native/components';
+import { type IAccessibilityProps, type IAriaProps } from '@symbiote-native/components';
+import type { IStyleProp, IViewStyle } from '../../utils/styles';
+import { type IStickyHeaderComponentType } from './sticky-header';
+export type { IScrollViewHandle } from '@symbiote-native/components';
+type IScrollHandler = (event: ISymbioteEvent) => void;
+type ILayoutHandler = (event: ISymbioteEvent) => void;
+export interface IScrollViewProps extends IAccessibilityProps, IAriaProps {
+    style?: IStyleProp<IViewStyle>;
+    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?: ReactElement<IClonableRefreshControl>;
+    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?: ILayoutHandler;
+    onScroll?: IScrollHandler;
+    onScrollBeginDrag?: IScrollHandler;
+    onScrollEndDrag?: IScrollHandler;
+    onMomentumScrollBegin?: IScrollHandler;
+    onMomentumScrollEnd?: IScrollHandler;
+    onScrollToTop?: IScrollHandler;
+    children?: ReactNode;
+    className?: string;
+}
+export interface IClonableRefreshControl {
+    style?: IStyleProp<IViewStyle>;
+    children?: ReactNode;
+}
+export interface IPreparedScrollView {
+    scrollViewIntrinsic: ISymbioteIntrinsic;
+    scrollViewBaseStyle: IStyleProp<IViewStyle> | undefined;
+    outerProps: Record<string, unknown>;
+    style: IStyleProp<IViewStyle> | undefined;
+    layoutSplitStyle: IStyleProp<IViewStyle>;
+    content: ReactElement;
+    refreshControl: ReactElement<IClonableRefreshControl> | undefined;
+    scrollAnimatedValue: AnimatedValue;
+    nativeStickyAvailable: boolean;
+}
+export declare function usePreparedScrollView(rawProps: IScrollViewProps): IPreparedScrollView;
+export declare function useNativeStickyScrollAttach(scrollNodeRef: RefObject<ISymbioteNode | null>, scrollAnimatedValue: AnimatedValue, enabled: boolean): void;

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

@@ -0,0 +1,195 @@
+// ScrollView: shared core. The Fabric tree is nested: the scroll view wraps a content
+// view that holds the children (RN's own ScrollView.js shape). Building that content
+// node, resolving decelerationRate, and the prop plumbing are platform-invariant and
+// live here. What diverges (ADR 0020) is how a RefreshControl integrates: on iOS it is a
+// CHILD of the scroll view (sibling of the content), on Android it WRAPS the scroll view
+// (AndroidSwipeRefreshLayout is the parent, ScrollView nested inside). So the .ios/.android
+// files assemble the final element; the filename selects, no Platform.OS read.
+//
+// The framework-agnostic pieces (decelerationRate, the per-axis intrinsics/base style, the
+// content-size dedupe, the imperative handle, splitLayoutProps, the sticky math, the native
+// scroll-attach) live in @symbiote-native/components (ADR 0024); this file holds only the React
+// lifecycle (refs/state/effects) and the element assembly that consumes them.
+import { createElement, useEffect, useRef, useState, } from 'react';
+import { AnimatedValue, dlog, event as animatedEvent, isClassNameValue, isNativeAnimatedAvailable, resolveClassName, } from '@symbiote-native/engine';
+import { attachStickyScroll, didContentSizeChange, forwardScrollEvent, readLayoutDimension, resolveDecelerationRate, selectScrollIntrinsics, } from '@symbiote-native/components';
+import { resolveAccessibilityProps, } from '@symbiote-native/components';
+import { wrapStickyHeaders } from './sticky-header';
+export function usePreparedScrollView(rawProps) {
+    // ScrollView forwards its outer props straight to the native scroll view (not a View
+    // wrapper), so it folds aria/role into accessibility* here before forwarding.
+    const props = resolveAccessibilityProps(rawProps);
+    const { style, className, contentContainerStyle, horizontal, decelerationRate, refreshControl, children, onContentSizeChange, stickyHeaderIndices, invertStickyHeaders, StickyHeaderComponent, onLayout, onScroll, scrollEventThrottle, ...outer } = props;
+    const isHorizontal = horizontal === true;
+    const hasStickyHeaders = stickyHeaderIndices !== undefined && stickyHeaderIndices.length > 0;
+    // A single AnimatedValue tracks the scroll offset and drives every sticky header's
+    // translateY (RN's _scrollAnimatedValue). Stable across renders via a ref so the headers'
+    // bindings survive re-renders. Allocated even when no sticky headers are present (hooks
+    // run unconditionally: usePreparedScrollView is always called at the top of the render body).
+    const scrollAnimatedValueRef = useRef(null);
+    if (scrollAnimatedValueRef.current === null)
+        scrollAnimatedValueRef.current = new AnimatedValue(0);
+    const scrollAnimatedValue = scrollAnimatedValueRef.current;
+    // Inverted sticky headers stick to the BOTTOM, so they need the viewport height (RN reads
+    // it in _handleLayout). Tracked here and fed back into the wrapped headers.
+    const [viewportHeight, setViewportHeight] = useState(undefined);
+    // Sticky-header cross-talk (RN ScrollView.js _headerLayoutYs, line 754): a child-index→measured-y
+    // map the parent keeps so each header can learn where the NEXT sticky header starts (its push-off
+    // collision point). The map lives in a ref (mutated imperatively from each header's onLayout, like
+    // RN's _onStickyHeaderLayout), and a state bump forces the re-render that feeds the freshly-recorded
+    // y forward into the previous header's nextHeaderLayoutY prop.
+    const headerLayoutYsRef = useRef(null);
+    if (headerLayoutYsRef.current === null)
+        headerLayoutYsRef.current = new Map();
+    const headerLayoutYs = headerLayoutYsRef.current;
+    const [, bumpHeaderLayout] = useState(0);
+    const onHeaderLayoutY = (index, y) => {
+        if (headerLayoutYs.get(index) === y)
+            return;
+        headerLayoutYs.set(index, y);
+        dlog(`ScrollView sticky-header layoutY index=${index} y=${y}`);
+        bumpHeaderLayout(tick => tick + 1);
+    };
+    // A class-name string resolves through the shared registry before it reaches the
+    // framework-agnostic selector below, which only understands style objects/arrays.
+    const resolvedContentContainerStyle = typeof contentContainerStyle === 'string'
+        ? resolveClassName(contentContainerStyle)
+        : contentContainerStyle;
+    // The per-axis intrinsics, base style, and content style come from the shared selector
+    // (@symbiote-native/components): on Android horizontal resolves to its own ViewManager, on iOS both
+    // map back to RCTScrollView; here we only pass the axis.
+    const { scrollViewIntrinsic, contentIntrinsic, scrollViewBaseStyle, contentStyle } = selectScrollIntrinsics(isHorizontal, resolvedContentContainerStyle);
+    const outerProps = { ...outer };
+    // className is pulled out above (unlike the rest of `...outer`) so `layoutSplitStyle` below can
+    // resolve it eagerly; re-added here so the simple single-node paths (iOS, Android with no
+    // refreshControl) keep forwarding it raw, exactly as it did when it flowed through `...outer`.
+    if (className !== undefined)
+        outerProps.className = className;
+    // RN defaults nested scrolling ON (ScrollView.js:1862 `nestedScrollEnabled ?? true`).
+    // Android needs the flag to scroll a scrollable nested inside another scroll view
+    // independently; without it the inner one stays put. iOS handles nesting natively, so
+    // it is a no-op there. Default to true so nested lists scroll out of the box, like RN.
+    outerProps.nestedScrollEnabled = props.nestedScrollEnabled ?? true;
+    // iOS needs `horizontal` to flip RCTScrollView's axis; Android's dedicated horizontal
+    // manager ignores it. Harmless on Android, load-bearing on iOS, so always forward it.
+    if (horizontal !== undefined)
+        outerProps.horizontal = horizontal;
+    if (decelerationRate !== undefined) {
+        outerProps.decelerationRate = resolveDecelerationRate(decelerationRate);
+    }
+    // onScroll: when sticky headers are active, the offset must reach the AnimatedValue, so
+    // we wrap the user's handler with Animated.event (it fires the listener passthrough). RN
+    // does the same with _scrollAnimatedValueAttachment. Without sticky headers, forward as-is.
+    const nativeStickyAvailable = hasStickyHeaders && isNativeAnimatedAvailable();
+    if (hasStickyHeaders) {
+        if (nativeStickyAvailable) {
+            // Native path (RN attachNativeEvent): the scroll value is driven on the UI thread by the
+            // imperative attach in the platform component's effect (useNativeStickyScrollAttach), so
+            // onScroll only forwards to the user, zero JS per frame. RN uses throttle 1 when sticky
+            // (ScrollView.js:1798); the native driver can afford it.
+            if (onScroll !== undefined)
+                outerProps.onScroll = onScroll;
+            outerProps.scrollEventThrottle = scrollEventThrottle ?? 1;
+        }
+        else {
+            // JS fallback (no native module): Animated.event drives the value each frame and forwards
+            // the user's handler as the listener passthrough. Correct, but lags a frame under fast
+            // scroll (the jitter), which the native path above removes on a real host.
+            outerProps.onScroll = animatedEvent([{ nativeEvent: { contentOffset: { y: scrollAnimatedValue } } }], onScroll === undefined
+                ? undefined
+                : { listener: (...args) => forwardScrollEvent(onScroll, args) });
+            outerProps.scrollEventThrottle = scrollEventThrottle ?? 16;
+        }
+    }
+    else {
+        if (onScroll !== undefined)
+            outerProps.onScroll = onScroll;
+        if (scrollEventThrottle !== undefined)
+            outerProps.scrollEventThrottle = scrollEventThrottle;
+    }
+    // onLayout on the scroll-view node: capture the viewport height for inverted sticky headers
+    // (RN _handleLayout), then call the user's handler. Pass through unchanged otherwise.
+    if (hasStickyHeaders && invertStickyHeaders === true) {
+        outerProps.onLayout = (layoutEvent) => {
+            const height = readLayoutDimension(layoutEvent, 'height');
+            if (height !== undefined)
+                setViewportHeight(height);
+            onLayout?.(layoutEvent);
+        };
+    }
+    else if (onLayout !== undefined) {
+        outerProps.onLayout = onLayout;
+    }
+    dlog(`ScrollView -> ${scrollViewIntrinsic} (horizontal=${isHorizontal} sticky=${hasStickyHeaders})`);
+    // onContentSizeChange is synthesized from the content view's own onLayout (RN
+    // _handleContentOnLayout): read width/height off nativeEvent.layout and fire only when the
+    // size actually changed (dedupe via a ref, like RN). Composed with any content onLayout.
+    const lastContentSizeRef = useRef(null);
+    const contentProps = { style: contentStyle, collapsable: false };
+    // maintainVisibleContentPosition (and Android snapToAlignment) anchor against the metrics
+    // of MOUNTED cell views. Android Fabric view-flattens layout-only cells away, so the native
+    // MaintainVisibleScrollPositionHelper has nothing to anchor to and the list jumps on prepend.
+    // RN keeps the cells as real views via collapsableChildren={false} on the content container
+    // (ScrollView.js:1731-1748 `preserveChildren`). iOS never flattens, so it is a no-op there.
+    if (props.maintainVisibleContentPosition !== undefined || props.snapToAlignment !== undefined) {
+        contentProps.collapsableChildren = false;
+    }
+    if (onContentSizeChange !== undefined) {
+        contentProps.onLayout = (layoutEvent) => {
+            const width = readLayoutDimension(layoutEvent, 'width');
+            const height = readLayoutDimension(layoutEvent, 'height');
+            if (width === undefined || height === undefined)
+                return;
+            const last = lastContentSizeRef.current;
+            if (!didContentSizeChange(last, { width, height }))
+                return;
+            lastContentSizeRef.current = { width, height };
+            dlog(`ScrollView onContentSizeChange ${width}x${height}`);
+            onContentSizeChange(width, height);
+        };
+    }
+    // Sticky headers are a pure-JS layer (the native scroll view ignores stickyHeaderIndices);
+    // wrap the flagged children so they pin to the scroll offset. No-op when none are flagged.
+    const contentChildren = hasStickyHeaders
+        ? wrapStickyHeaders(children, stickyHeaderIndices, scrollAnimatedValue, invertStickyHeaders, viewportHeight, StickyHeaderComponent, headerLayoutYs, onHeaderLayoutY)
+        : children;
+    // `collapsable: false` is load-bearing on Android. The content container is a
+    // layout-only View, which Android Fabric view-flattens away, hoisting the cells
+    // up as DIRECT children of the scroll view, which strictly hosts exactly one
+    // child ("ScrollView can host only one direct child" → addViewAt crash). RN pins
+    // its own NativeScrollContentView the same way (ScrollView.js, collapsable={false};
+    // ReactScrollView.java: "the 'content' View … non-collapsable so it will never be
+    // View-flattened away"). iOS doesn't flatten, so this is a no-op there.
+    const content = createElement(contentIntrinsic, contentProps, contentChildren);
+    // resolveClassName(undefined) is a cheap {} no-op, so this is safe with no className too.
+    const resolvedClassName = isClassNameValue(className) ? className : undefined;
+    const layoutSplitStyle = [resolveClassName(resolvedClassName), style];
+    return {
+        scrollViewIntrinsic,
+        scrollViewBaseStyle,
+        outerProps,
+        style,
+        layoutSplitStyle,
+        content,
+        refreshControl,
+        scrollAnimatedValue,
+        nativeStickyAvailable,
+    };
+}
+// Attach the scroll event to the scroll-offset value on the NATIVE driver, RN's
+// _updateAnimatedNodeAttachment / AnimatedImplementation.attachNativeEvent (ScrollView.js:1087).
+// Called by each platform ScrollView with its committed scroll-node ref; the value then tracks
+// scroll on the UI thread and the sticky-header interpolations ride it natively (no JS jitter).
+// No-op when native sticky is unavailable or the node hasn't committed. Detaches on unmount.
+// The attach/detach itself lives in @symbiote-native/components (attachStickyScroll); this is the React
+// effect that drives it.
+export function useNativeStickyScrollAttach(scrollNodeRef, scrollAnimatedValue, enabled) {
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const node = scrollNodeRef.current;
+        if (node === null)
+            return;
+        return attachStickyScroll(node, scrollAnimatedValue);
+    }, [scrollNodeRef, scrollAnimatedValue, enabled]);
+}

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

@@ -0,0 +1,9 @@
+import { type ComponentType, type ReactNode } from 'react';
+import { AnimatedValue } from '@symbiote-native/engine';
+import { type IStickyHeaderProps } from '@symbiote-native/components';
+export type IStickyHeaderComponentProps = IStickyHeaderProps & {
+    children?: ReactNode;
+};
+export type IStickyHeaderComponentType = ComponentType<IStickyHeaderComponentProps>;
+export declare const ScrollViewStickyHeader: IStickyHeaderComponentType;
+export declare function wrapStickyHeaders(children: ReactNode, stickyHeaderIndices: number[] | undefined, scrollAnimatedValue: AnimatedValue, invertStickyHeaders: boolean | undefined, scrollViewHeight: number | undefined, StickyHeaderComponent: IStickyHeaderComponentType | undefined, headerLayoutYs: ReadonlyMap<number, number>, onHeaderLayoutY: (index: number, y: number) => void): ReactNode;

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

@@ -0,0 +1,161 @@
+// Sticky headers: the JS layer RN implements in ScrollView.js / ScrollViewStickyHeader.js.
+//
+// VERDICT (source-based): RN does stickiness PURELY IN JS. ScrollView.js (render, ~line
+// 1690) wraps each child whose index is in `stickyHeaderIndices` in a ScrollViewStickyHeader,
+// fed by a single `_scrollAnimatedValue` an Animated.event drives from `onScroll`
+// (ScrollView.js ~line 1095). The native Fabric scroll view does NOT honor the index array on
+// its own. Forwarding `stickyHeaderIndices` to native is a silent no-op. So we replicate the
+// JS layer: subscribe each flagged child to the scroll offset and translate it to stay pinned.
+// The interpolation mirrors ScrollViewStickyHeader.js (non-inverted + inverted branches) and now
+// lives, framework-agnostic, in @symbiote-native/components (computeStickyInterpolation, ADR 0024); this
+// file holds the React component shell, the layout state, and the child-wrapping.
+import { Children, createElement, isValidElement, useCallback, useEffect, useRef, useState, } from 'react';
+import { AnimatedInterpolation, AnimatedValue, Platform, dlog, } from '@symbiote-native/engine';
+import { computeStickyInterpolation, nextStickyHeaderY, readLayoutNumber, stickyDebounceMs, STICKY_HEADER_Z_INDEX, } from '@symbiote-native/components';
+import { Animated } from '../../modules/animated';
+function readChildOnLayout(child) {
+    const childProps = child.props;
+    if (typeof childProps !== 'object' || childProps === null)
+        return undefined;
+    const handler = Reflect.get(childProps, 'onLayout');
+    return typeof handler === 'function' ? handler : undefined;
+}
+function firstChild(children) {
+    const first = Children.toArray(children)[0];
+    return isValidElement(first) ? first : undefined;
+}
+// One sticky header. Measures its own y/height via onLayout, interpolates the shared scroll
+// offset into a translateY that keeps it pinned to the top (or 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 (no JS jitter). Ported from
+// ScrollViewStickyHeader.js, including the Fabric ShadowTree debounce path.
+export const ScrollViewStickyHeader = props => {
+    const { inverted, scrollViewHeight, scrollAnimatedValue, nextHeaderLayoutY, children } = props;
+    const [measured, setMeasured] = useState(false);
+    const [layoutY, setLayoutY] = useState(0);
+    const [layoutHeight, setLayoutHeight] = useState(0);
+    // The animated node that drives the transform (RN's animatedTranslateY). When the scroll value
+    // is native (attachNativeEvent), this interpolation runs on the UI thread: the smooth pin.
+    const [animatedTranslateY, setAnimatedTranslateY] = useState(() => scrollAnimatedValue.interpolate({ inputRange: [-1, 0], outputRange: [0, 0] }));
+    // The debounced EXPLICIT translateY pushed to the committed transform via
+    // passthroughAnimatedPropExplicitValues, so the Fabric ShadowTree (hit-testing) knows the pinned
+    // position while the native driver animates. null until the listener first fires.
+    const [translateY, setTranslateY] = useState(null);
+    const haveReceivedInitialZeroTranslateY = useRef(true);
+    const debounceTimer = useRef(null);
+    useEffect(() => {
+        if (translateY !== 0 && translateY !== null)
+            haveReceivedInitialZeroTranslateY.current = false;
+    }, [translateY]);
+    // The animated value updates several times per frame during scroll; debounce it and push the
+    // settled value into the committed transform so hit detection stays current (RN: a Fabric-only
+    // issue, symbiote is always Fabric, and worse on Android).
+    const animatedValueListener = useCallback(({ value }) => {
+        if (typeof value !== 'number')
+            return;
+        const timeout = stickyDebounceMs(Platform.OS);
+        // A freshly-rebuilt interpolation re-emits 0 to its listeners; swallow that first zero (RN).
+        if (value === 0 && !haveReceivedInitialZeroTranslateY.current) {
+            haveReceivedInitialZeroTranslateY.current = true;
+            return;
+        }
+        if (debounceTimer.current !== null)
+            clearTimeout(debounceTimer.current);
+        debounceTimer.current = setTimeout(() => setTranslateY(value), timeout);
+    }, []);
+    useEffect(() => {
+        const { inputRange, outputRange } = computeStickyInterpolation({
+            measured,
+            inverted,
+            scrollViewHeight,
+            layoutY,
+            layoutHeight,
+            nextHeaderLayoutY,
+        });
+        const newAnimatedTranslateY = scrollAnimatedValue.interpolate({ inputRange, outputRange });
+        // symbiote is always Fabric: listen to the settled value to keep the ShadowTree transform
+        // current for hit-testing (RN attaches this listener only under Fabric).
+        const listenerId = newAnimatedTranslateY.addListener(animatedValueListener);
+        setAnimatedTranslateY(newAnimatedTranslateY);
+        return () => {
+            newAnimatedTranslateY.removeListener(listenerId);
+            if (debounceTimer.current !== null)
+                clearTimeout(debounceTimer.current);
+        };
+    }, [
+        measured,
+        layoutY,
+        layoutHeight,
+        scrollViewHeight,
+        nextHeaderLayoutY,
+        inverted,
+        scrollAnimatedValue,
+        animatedValueListener,
+    ]);
+    const onLayout = (event) => {
+        const y = readLayoutNumber(event, 'y');
+        const height = readLayoutNumber(event, 'height');
+        if (y !== undefined)
+            setLayoutY(y);
+        if (height !== undefined)
+            setLayoutHeight(height);
+        setMeasured(true);
+        props.onLayout(event);
+        const child = firstChild(children);
+        const childOnLayout = child === undefined ? undefined : readChildOnLayout(child);
+        childOnLayout?.(event);
+    };
+    // The EXPLICIT debounced translateY overrides the committed transform for hit-testing, while
+    // `animatedTranslateY` does the smooth (native-driven) pin, per RN ScrollViewStickyHeader.js.
+    const passthroughAnimatedPropExplicitValues = translateY !== null ? { style: { transform: [{ translateY }] } } : null;
+    // collapsable:false keeps the wrapper a real Yoga node; zIndex makes the pinned header paint
+    // OVER the rows scrolling under it. `style` is `unknown` on Animated.View, so the interpolation
+    // transform passes with no cast.
+    return createElement(Animated.View, {
+        style: { transform: [{ translateY: animatedTranslateY }], zIndex: STICKY_HEADER_Z_INDEX },
+        onLayout,
+        collapsable: false,
+        passthroughAnimatedPropExplicitValues,
+    }, children);
+};
+ScrollViewStickyHeader.displayName = 'ScrollViewStickyHeader';
+// Wrap each child flagged by `stickyHeaderIndices` in the sticky header component, fed by the
+// shared scroll AnimatedValue. Mirrors ScrollView.js's render-time children.map (~line 1690).
+// Returns the children unchanged when no indices are flagged.
+//
+// Cross-talk plumbing (RN's _headerLayoutYs + _onStickyHeaderLayout, ScrollView.js:1115-1143):
+// `headerLayoutYs` is a child-index→measured-y map the parent keeps; each header reports its own
+// y through `onHeaderLayoutY` as it measures, and we feed every header the y of the NEXT flagged
+// header (the collision point past which it scrolls off) by looking up its successor's index in
+// `stickyHeaderIndices`. The LAST flagged header has no successor, so its `nextHeaderLayoutY`
+// stays undefined and it sticks indefinitely (correct).
+export function wrapStickyHeaders(children, stickyHeaderIndices, scrollAnimatedValue, invertStickyHeaders, scrollViewHeight, StickyHeaderComponent, headerLayoutYs, onHeaderLayoutY) {
+    if (stickyHeaderIndices === undefined || stickyHeaderIndices.length === 0)
+        return children;
+    const Wrapper = StickyHeaderComponent ?? ScrollViewStickyHeader;
+    return Children.toArray(children).map((child, index) => {
+        const indexOfIndex = stickyHeaderIndices.indexOf(index);
+        if (indexOfIndex === -1 || !isValidElement(child))
+            return child;
+        // The next flagged header's measured y, by index order in stickyHeaderIndices (RN
+        // ScrollView.js:1695 nextIndex). undefined until that header has measured (or for the last).
+        const nextIndex = stickyHeaderIndices[indexOfIndex + 1];
+        const nextHeaderLayoutY = nextStickyHeaderY(stickyHeaderIndices, indexOfIndex, headerLayoutYs);
+        dlog(`ScrollView sticky-header wrap index=${index} next=${nextIndex} nextY=${nextHeaderLayoutY}`);
+        return createElement(Wrapper, {
+            key: child.key ?? `sticky-${index}`,
+            nextHeaderLayoutY,
+            // RN _onStickyHeaderLayout: record this header's own y, then push it to the previous
+            // header as its nextHeaderLayoutY. We record into the parent map; the lookup above feeds
+            // it forward on the resulting re-render.
+            onLayout: (event) => {
+                const y = readLayoutNumber(event, 'y');
+                if (y !== undefined)
+                    onHeaderLayoutY(index, y);
+            },
+            scrollAnimatedValue,
+            inverted: invertStickyHeaders,
+            scrollViewHeight,
+        }, child);
+    });
+}

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

@@ -0,0 +1,8 @@
+import { type ReactElement, type Ref } from 'react';
+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> & {
+    ref?: Ref<ISectionListHandle>;
+}): ReactElement;

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

@@ -0,0 +1,12 @@
+// SectionList: the public, high-level list-of-sections component. It is a thin
+// wrapper over VirtualizedSectionList, mirroring RN's layering
+// (SectionList -> VirtualizedSectionList -> VirtualizedList). All the
+// section-flattening / windowing / imperative-scroll logic lives in
+// VirtualizedSectionList; this layer only re-exposes the same surface under the
+// SectionList name so existing consumers and the canary keep importing it from
+// here, threading the imperative ref straight through.
+import { createElement } from 'react';
+import { VirtualizedSectionList, } from '../virtualized-section-list';
+export function SectionList(props) {
+    return createElement((VirtualizedSectionList), props);
+}

package/build/components/switch/index.android.d.ts

@@ -0,0 +1,2 @@
+export type { ISwitchProps, ISwitchTrackColor } from './shared';
+export declare const Switch: import("react").FC<import("./shared").ISwitchProps>;

package/build/components/switch/index.android.js

@@ -0,0 +1,12 @@
+// Switch, Android host binding. AndroidSwitch takes trackColorForTrue / trackColorForFalse
+// plus trackTintColor (the color for the CURRENT value, which RN computes as value ? true :
+// false), and snaps native back via the `setNativeValue` command (Switch.js:221-225).
+import { createSwitch } from './shared';
+export const Switch = createSwitch({
+    snapBackCommand: 'setNativeValue',
+    trackColorProps: (value, trackColor) => ({
+        trackColorForFalse: trackColor?.false,
+        trackColorForTrue: trackColor?.true,
+        trackTintColor: value ? trackColor?.true : trackColor?.false,
+    }),
+});

package/build/components/switch/index.d.ts

@@ -0,0 +1 @@
+export * from './index.ios';

package/build/components/switch/index.ios.d.ts

@@ -0,0 +1,2 @@
+export type { ISwitchProps, ISwitchTrackColor } from './shared';
+export declare const Switch: import("react").FC<import("./shared").ISwitchProps>;

package/build/components/switch/index.ios.js

@@ -0,0 +1,10 @@
+// Switch, iOS host binding. iOS's native Switch takes onTintColor (ON-track) / tintColor
+// (OFF-track), and snaps native back via the `setValue` command (Switch.js:221-225).
+import { createSwitch } from './shared';
+export const Switch = createSwitch({
+    snapBackCommand: 'setValue',
+    trackColorProps: (_value, trackColor) => ({
+        onTintColor: trackColor?.true,
+        tintColor: trackColor?.false,
+    }),
+});

package/build/components/switch/index.js

@@ -0,0 +1,6 @@
+// Base / default Switch: re-exports the iOS build. Metro overrides this with switch.ios.ts /
+// switch.android.ts on a real host; under tsx / tsc / web the host config resolves here.
+// Filename is the selector, no Platform.OS read. See ADR 0020. The three-layer split (logic
+// in @symbiote-native/components/state, render in @symbiote-native/components/view, hook in switch-shared)
+// replaced the former monolithic Platform.OS-branching component.
+export * from './index.ios';

package/build/components/switch/shared.d.ts

@@ -0,0 +1,10 @@
+import type { FC } from 'react';
+import type { ISwitchPlatform, ISwitchProps as ISwitchBaseProps } from '@symbiote-native/components';
+export type { ISwitchTrackColor } from '@symbiote-native/components';
+export type ISwitchProps = ISwitchBaseProps & {
+    className?: string;
+};
+type ISwitchHostPlatform = ISwitchPlatform & {
+    snapBackCommand: string;
+};
+export declare function createSwitch(platform: ISwitchHostPlatform): FC<ISwitchProps>;

package/build/components/switch/shared.js

@@ -0,0 +1,59 @@
+// Switch is the React lifecycle half. The logic (the lastNativeReport reducer, valueFromChange,
+// the snap-back decision) lives in @symbiote-native/components/state, the render (value fold, track
+// colors, ios_backgroundColor) in @symbiote-native/components/view; here the adapter only owns the
+// hook: useReducer over the shared reducer, a ref for the imperative command, and the
+// useLayoutEffect that snaps native back when the parent rejects a toggle.
+//
+// Switch is controlled exactly like RN's: the parent's onValueChange MUST update `value` for
+// the toggle to stick. If the handler is a no-op, native has already flipped its own grip, so
+// JS commands the old value back down (a plain prop re-push cannot cover the no-op case: the
+// prop never changes, so the retained tree never diverges). The command name is platform-
+// specific (iOS setValue / Android setNativeValue) and arrives via `platform`.
+import { useCallback, useLayoutEffect, useReducer, useRef } from 'react';
+import { renderSwitch, switchReducer, createInitialSwitchState, shouldSnapBack, valueFromChange, } from '@symbiote-native/components';
+import { dispatchViewCommand, dlog, } from '@symbiote-native/engine';
+import { resolveAccessibilityProps } from '@symbiote-native/components';
+import { descriptorToReact } from '../../descriptor-to-react';
+export function createSwitch(platform) {
+    return rawProps => {
+        // Switch owns its host element rather than rendering through a symbiote View, so it folds
+        // aria/role into accessibility* here; the resolved accessibility* fields (plus testID etc.)
+        // ride down to the host node via `passthrough`.
+        const props = resolveAccessibilityProps(rawProps);
+        const { value, onValueChange, disabled, trackColor, thumbColor, ios_backgroundColor, style, ...passthrough } = props;
+        const ref = useRef(null);
+        const [state, dispatch] = useReducer(switchReducer, undefined, createInitialSwitchState);
+        const handleChange = useCallback((event) => {
+            const next = valueFromChange(event);
+            dlog(`Switch onChange value=${String(next)} eventCount=${String(event.nativeEvent.eventCount)}`);
+            if (next === undefined)
+                return;
+            onValueChange?.(next, event);
+            dispatch({ type: 'native-reported', value: next });
+        }, [onValueChange]);
+        // value is a real Fabric prop, folded to a strict boolean: RN sends `value === true`, so
+        // an undefined prop reads as "off" rather than absent.
+        const fabricValue = value === true;
+        useLayoutEffect(() => {
+            const node = ref.current;
+            if (node === null)
+                return;
+            if (!shouldSnapBack(state, fabricValue)) {
+                dlog(`Switch snap-back no-op reported=${String(state.lastNativeReport)} value=${fabricValue}`);
+                return;
+            }
+            dlog(`Switch ${platform.snapBackCommand} snap-back reported=${String(state.lastNativeReport)} value=${fabricValue}`);
+            dispatchViewCommand(node, platform.snapBackCommand, [fabricValue]);
+        }, [fabricValue, state]);
+        const descriptor = renderSwitch({
+            value: fabricValue,
+            disabled,
+            trackColor,
+            thumbColor,
+            ios_backgroundColor,
+            style,
+            passthrough: { ...passthrough, ref, onChange: handleChange },
+        }, platform);
+        return descriptorToReact(descriptor);
+    };
+}