@symbiote-native/solid 0.0.1 → 1.0.0

package/build/components/touchable/index.jsx

@@ -0,0 +1,247 @@
+// The Touchable* family for Solid, all built on Pressable. Ported against RN's own sources
+// (.vendors/react-native/.../Components/Touchable/*.js), NOT against this repo's React adapter —
+// an audit on 2026-08-19 found the React/Vue/Svelte/Angular ports diverge from RN in ten places.
+// This adapter is the first on the RN-accurate shared API; the other four migrate in phase two,
+// which is why @symbiote-native/components carries both forms for now.
+//
+// Shared (framework-agnostic) half: the press-scheduling machine, the underlay machine, the resting
+// opacity math, the press-handler gate, the extra-style split. Solid owns only the lifecycle —
+// signals, memos, the real timers, and the Animated wiring.
+//
+// NOTHING here destructures `props`. A Solid component body runs ONCE and props are getters, so a
+// destructure would freeze the component at its mount-time config; every read below sits inside an
+// accessor, a memo or an event handler.
+//
+// No conditional picks a branch in any of the three trees. Solid's `insert` REPLACES a subtree
+// rather than diffing it, and a rebuild landing mid-gesture costs the native responder grant
+// (.claude/rules/solid-descriptor-bridge.md §4). Every per-press value here is a prop-bag value,
+// and a prop bag reaches the host through `spread` — a per-key diff on the SAME element.
+import { createEffect, createMemo, createSignal, onCleanup, splitProps, untrack, } from 'solid-js';
+import { createHighlightUnderlayHandlers, createHighlightUnderlayRuntime, createTouchableFeedbackHandlers, createTouchableFeedbackRuntime, hasTouchablePressHandler, resolveHighlightExtraStyles, restingOpacityFromStyle, DEFAULT_ACTIVE_OPACITY, OPACITY_ACTIVE_GRANT_DURATION_MS, OPACITY_INACTIVE_DURATION_MS, TOUCHABLE_MIN_PRESS_DURATION_MS, } from '@symbiote-native/components';
+import { dlog, } from '@symbiote-native/engine';
+import { Animated } from '../../modules/animated/index.js';
+import { TouchablePressable as Pressable, } from '../pressable.jsx';
+// The real timers both shared machines schedule on — core/components carries no timer globals, so
+// scheduling is the adapter's half. Every canceller is retained so unmount cancels what is still in
+// flight: a Solid body runs once, so there is no re-render that would otherwise drop a stale timer,
+// and a fired timer would call back into a disposed scope.
+function createTimeoutScheduler() {
+    const pending = new Set();
+    onCleanup(() => {
+        for (const cancel of [...pending])
+            cancel();
+        pending.clear();
+    });
+    return (callback, ms) => {
+        const id = setTimeout(() => {
+            pending.delete(cancel);
+            callback();
+        }, ms);
+        const cancel = () => {
+            clearTimeout(id);
+            pending.delete(cancel);
+        };
+        pending.add(cancel);
+        return cancel;
+    };
+}
+// `class` is split off with `style`: both describe the FEEDBACK node (the inner Animated.View),
+// not the outer Pressable that owns the responder. Left in `rest` they would land on the wrong one.
+const TOUCHABLE_OPACITY_HANDLED = [
+    'activeOpacity',
+    'style',
+    'class',
+    'children',
+    'onPressIn',
+    'onPressOut',
+    'delayPressIn',
+    'delayPressOut',
+    'minPressDuration',
+];
+export function TouchableOpacity(props) {
+    const [local, rest] = splitProps(props, TOUCHABLE_OPACITY_HANDLED);
+    // RN's _getChildStyleOpacityWithDefault: the fade settles at the opacity the CALLER's style asks
+    // for, not at a hard 1.
+    const restingOpacity = createMemo(() => restingOpacityFromStyle(local.style));
+    // One Animated.Value per mount, held by IDENTITY in a plain variable — a signal or store would
+    // wrap this engine object in a proxy, and the graph's bookkeeping is keyed on the raw instance
+    // (symbiote-engine-core §3). untrack because the body must not subscribe to the initial read.
+    const opacity = new Animated.Value(untrack(restingOpacity));
+    // The shared press-scheduling cell (delayPressIn canceller + activation clock). A setup-scope
+    // object, never reactive: the machine mutates it on every event and nothing reads it reactively.
+    const runtime = createTouchableFeedbackRuntime();
+    const schedule = createTimeoutScheduler();
+    function setOpacityTo(toValue, duration) {
+        dlog(`TouchableOpacity opacity -> ${toValue} over ${duration}ms`);
+        // useNativeDriver: true is RN's own (TouchableOpacity.js:242). opacity is natively drivable and
+        // the fade then survives a busy JS thread, which is the whole point of the feedback.
+        Animated.timing(opacity, {
+            toValue,
+            duration,
+            easing: Animated.Easing.inOut(Animated.Easing.quad),
+            useNativeDriver: true,
+        }).start();
+    }
+    // Rebuilt only when the TIMING config changes — the callbacks read activeOpacity / onPressIn /
+    // onPressOut when they fire, so a re-supplied callback is honored without churning the handler
+    // identities the host node holds. The runtime persists across rebuilds, so an in-flight
+    // delayPressIn timer survives one.
+    const handlers = createMemo(() => createTouchableFeedbackHandlers({
+        delayPressIn: local.delayPressIn ?? 0,
+        delayPressOut: local.delayPressOut ?? 0,
+        // RN's Touchables override Pressability's 130ms floor with 0; the active visual is held by
+        // the fade's own duration instead.
+        minPressDuration: local.minPressDuration ?? TOUCHABLE_MIN_PRESS_DURATION_MS,
+        schedule,
+        now: Date.now,
+    }, runtime, {
+        activate(event) {
+            setOpacityTo(local.activeOpacity ?? DEFAULT_ACTIVE_OPACITY, OPACITY_ACTIVE_GRANT_DURATION_MS);
+            local.onPressIn?.(event);
+        },
+        deactivate(event) {
+            setOpacityTo(restingOpacity(), OPACITY_INACTIVE_DURATION_MS);
+            local.onPressOut?.(event);
+        },
+    }));
+    // RN's componentDidUpdate: a changed `disabled` or a changed style opacity re-settles the view,
+    // so a Touchable disabled mid-press does not stay stuck at its active opacity. Skipped on the
+    // first run — RN does this on UPDATE only, and firing at mount would animate over the initial
+    // value the Animated.Value already holds.
+    createEffect(previous => {
+        const current = { disabled: rest.disabled, resting: restingOpacity() };
+        if (previous !== undefined &&
+            (previous.disabled !== current.disabled ||
+                previous.resting !== current.resting)) {
+            setOpacityTo(current.resting, OPACITY_INACTIVE_DURATION_MS);
+        }
+        return current;
+    }, undefined);
+    // RN's componentWillUnmount: stop the animation and drop the value back, so a teardown mid-fade
+    // leaves no driver running against a node that is gone.
+    onCleanup(() => {
+        opacity.resetAnimation();
+    });
+    // Depends on `style` alone. `opacity` is a stable graph node, so a press changes what the node
+    // HOLDS, never this array — the per-frame path is value.setValue -> AnimatedProps.update ->
+    // setNativeProps, which never re-enters this component.
+    const feedbackStyle = createMemo(() => [local.style, { opacity }]);
+    // A spread followed by explicit props is safe here only because neither override can be
+    // `undefined` — mergeProps takes the first NON-undefined value scanning back-to-front, so an
+    // optional override after a spread would silently lose (.claude/rules/solid-descriptor-bridge.md
+    // §6). handlers() always returns both functions.
+    return (<Pressable {...rest} onPressIn={handlers().handlePressIn} onPressOut={handlers().handlePressOut}>
+      <Animated.View style={feedbackStyle()} class={local.class}>
+        {local.children}
+      </Animated.View>
+    </Pressable>);
+}
+// onPress/onPressIn/onPressOut are INTERCEPTED, not forwarded: RN drives the underlay from those
+// three callbacks and then calls the caller's. onLongPress stays in `rest` (Pressable fires it
+// directly) and is only READ here, for the has-press-handler gate.
+const TOUCHABLE_HIGHLIGHT_HANDLED = [
+    'activeOpacity',
+    'underlayColor',
+    'style',
+    'children',
+    'onPress',
+    'onPressIn',
+    'onPressOut',
+    'onShowUnderlay',
+    'onHideUnderlay',
+    'delayPressOut',
+];
+export function TouchableHighlight(props) {
+    const [local, rest] = splitProps(props, TOUCHABLE_HIGHLIGHT_HANDLED);
+    // `shown` is NOT `pressed`: RN holds the underlay for delayPressOut past the tap so a fast press
+    // still flashes, and the pressed flag is already false by then.
+    const [shown, setShown] = createSignal(false);
+    const runtime = createHighlightUnderlayRuntime();
+    const schedule = createTimeoutScheduler();
+    const hasPressHandler = createMemo(() => hasTouchablePressHandler({
+        onPress: local.onPress,
+        onPressIn: local.onPressIn,
+        onPressOut: local.onPressOut,
+        onLongPress: rest.onLongPress,
+    }));
+    const underlay = createMemo(() => createHighlightUnderlayHandlers({
+        delayPressOut: local.delayPressOut ?? 0,
+        hasPressHandler: hasPressHandler(),
+        schedule,
+    }, runtime, {
+        setShown,
+        onShowUnderlay: () => local.onShowUnderlay?.(),
+        onHideUnderlay: () => local.onHideUnderlay?.(),
+    }));
+    const extraStyles = createMemo(() => resolveHighlightExtraStyles({
+        shown: shown(),
+        hasPressHandler: hasPressHandler(),
+        underlayColor: local.underlayColor,
+        activeOpacity: local.activeOpacity,
+    }));
+    // POINT 7 IS DELIBERATELY NOT FIXED HERE, and this is the whole of the divergence from RN.
+    // RN clones its single child with `extra.child` so the lowered opacity lands on the CHILD while
+    // the container keeps an opaque underlay. Solid has no cloneElement, so the only way to reach the
+    // child is a permanent wrapper view — which inserts a node into the flex chain between this
+    // container and the children, silently re-parenting any `flex` a child declares. The fake Fabric
+    // runs no Yoga, so no headless test can measure that damage, only assert the extra node exists.
+    // Shipping an unmeasurable layout change is worse than the visual approximation, so both styles
+    // stay on the container (the pre-audit behavior) and the child style is folded in last.
+    // resolveHighlightExtraStyles keeps them SEPARATE regardless, so React's cloneElement path and a
+    // future Solid fix are both unblocked. A layout-safe fix needs a real device check, not a test.
+    const containerStyle = createMemo(() => {
+        const extra = extraStyles();
+        if (extra === undefined)
+            return local.style;
+        return [local.style, extra.underlay, extra.child];
+    });
+    // Visual first, then the caller's callback — RN's order in _createPressabilityConfig.
+    const handlePressIn = (event) => {
+        underlay().handlePressIn(event);
+        local.onPressIn?.(event);
+    };
+    const handlePress = (event) => {
+        underlay().handlePress(event);
+        local.onPress?.(event);
+    };
+    const handlePressOut = (event) => {
+        underlay().handlePressOut(event);
+        local.onPressOut?.(event);
+    };
+    return (<Pressable {...rest} style={containerStyle()} onPress={handlePress} onPressIn={handlePressIn} onPressOut={handlePressOut}>
+      {local.children}
+    </Pressable>);
+}
+const TOUCHABLE_WITHOUT_FEEDBACK_HANDLED = [
+    'children',
+    'onPressIn',
+    'onPressOut',
+    'delayPressIn',
+    'delayPressOut',
+    'minPressDuration',
+];
+export function TouchableWithoutFeedback(props) {
+    const [local, rest] = splitProps(props, TOUCHABLE_WITHOUT_FEEDBACK_HANDLED);
+    // RN's TouchableWithoutFeedback builds a FULL Pressability config with delayPressIn /
+    // delayPressOut / minPressDuration: 0 — "without feedback" means no VISUAL, not no timing. The
+    // same shared machine TouchableOpacity uses runs here with the visual half left empty.
+    const runtime = createTouchableFeedbackRuntime();
+    const schedule = createTimeoutScheduler();
+    const handlers = createMemo(() => createTouchableFeedbackHandlers({
+        delayPressIn: local.delayPressIn ?? 0,
+        delayPressOut: local.delayPressOut ?? 0,
+        minPressDuration: local.minPressDuration ?? TOUCHABLE_MIN_PRESS_DURATION_MS,
+        schedule,
+        now: Date.now,
+    }, runtime, {
+        activate(event) {
+            local.onPressIn?.(event);
+        },
+        deactivate(event) {
+            local.onPressOut?.(event);
+        },
+    }));
+    return (<Pressable {...rest} onPressIn={handlers().handlePressIn} onPressOut={handlers().handlePressOut}>
+      {local.children}
+    </Pressable>);
+}

package/build/components/touchable-native-feedback/index.d.ts

@@ -0,0 +1,16 @@
+import type { JSX } from '../../jsx-runtime';
+import { canUseNativeForeground, rippleBackground, selectableBackground, selectableBackgroundBorderless, type INativeFeedbackBackground } from '@symbiote-native/components';
+import { type IPressableProps } from '../pressable';
+export type { INativeFeedbackBackground, IThemeAttrBackground, IRippleBackground, } from '@symbiote-native/components';
+export interface ITouchableNativeFeedbackProps extends Omit<IPressableProps, 'style' | 'children'> {
+    background?: INativeFeedbackBackground;
+    useForeground?: boolean;
+    children?: JSX.Element;
+}
+declare function TouchableNativeFeedbackImpl(props: ITouchableNativeFeedbackProps): JSX.Element;
+export declare const TouchableNativeFeedback: typeof TouchableNativeFeedbackImpl & {
+    SelectableBackground: typeof selectableBackground;
+    SelectableBackgroundBorderless: typeof selectableBackgroundBorderless;
+    Ripple: typeof rippleBackground;
+    canUseNativeForeground: typeof canUseNativeForeground;
+};

package/build/components/touchable-native-feedback/index.jsx

@@ -0,0 +1,68 @@
+// TouchableNativeFeedback — Android's ripple / state-drawable touchable, built on Pressable like
+// the rest of the family. RN clones its child into an RCTView carrying the native ripple props;
+// we nest the child under a feedback view that carries them, inside a Pressable that owns the
+// press wiring. `nativeBackgroundAndroid` / `nativeForegroundAndroid` are read by Android's
+// ReactViewManager; on iOS they are inert props, so the component still renders its child with
+// working press wiring — exactly what React's and Vue's do.
+//
+// EVERYTHING NON-LIFECYCLE IS SHARED. The static factories (selectableBackground,
+// selectableBackgroundBorderless, rippleBackground), the platform gate (canUseNativeForeground)
+// and the background→native-prop mapping (backgroundProps) all live in
+// @symbiote-native/components; this file only attaches them to the component value and nests the
+// feedback view. Press timing is Pressable's, which is the shared state machine.
+//
+// The feedback carrier is a raw `symbiote-view`, not the `View` component — the same choice
+// Pressable already makes for its android_ripple wrapper. It carries native props and nothing
+// else: no accessibility surface, no class, no ref, so View's aria fold and nativeID resolution
+// would be pure overhead. The committed node is `RCTView` either way.
+//
+// NOTHING here destructures `props`. A Solid component body runs ONCE, so a destructure would
+// freeze the background at its mount-time value; every read below sits inside an accessor.
+import { splitProps } from 'solid-js';
+import { backgroundProps, canUseNativeForeground, rippleBackground, selectableBackground, selectableBackgroundBorderless, } from '@symbiote-native/components';
+import { dlog } from '@symbiote-native/engine';
+import { withStableKeys } from '../../utils/stable-keys.js';
+import { TouchablePressable as Pressable, } from '../pressable.jsx';
+function TouchableNativeFeedbackImpl(props) {
+    const [local, rest] = splitProps(props, [
+        'background',
+        'useForeground',
+        'children',
+    ]);
+    // ONE bag, and it goes through withStableKeys. backgroundProps returns a DIFFERENT single key
+    // per branch (nativeForegroundAndroid vs nativeBackgroundAndroid), and Solid's `spread` walks
+    // only the current key set with no removal pass — so flipping `useForeground` on an Android
+    // host would leave the abandoned key painting its old drawable forever. Widening restores what
+    // React and Vue get from their reconcilers: the vanished key arrives as `undefined`, which
+    // routeProp treats as a delete, and `spread` still does the actual diffing
+    // (.claude/rules/solid-descriptor-bridge.md §1).
+    const feedbackProps = withStableKeys(() => {
+        // RN never leaves a TouchableNativeFeedback without feedback: a missing background defaults
+        // to SelectableBackground().
+        const resolved = local.background ?? selectableBackground();
+        const useForeground = local.useForeground === true;
+        dlog(`TouchableNativeFeedback render ${resolved.type} useForeground ${useForeground}`);
+        // The no-op seam: RN silently routes a requested foreground back to the background slot off
+        // Android / below API 23, and a missing ripple on device looks like a broken component.
+        if (useForeground && !canUseNativeForeground()) {
+            dlog('TouchableNativeFeedback useForeground ignored: no native foreground here');
+        }
+        return backgroundProps(resolved, useForeground);
+    });
+    // Two single spreads, never spread-then-override: `mergeProps` (which the compiler uses for a
+    // spread followed by an explicit prop) keeps the FIRST non-undefined value, so an explicit
+    // `undefined` after a spread silently loses — the opposite of React's JSX spread
+    // (.claude/rules/solid-descriptor-bridge.md §6). `rest` and `feedbackProps()` are each the sole
+    // source for their element, so there is nothing to merge.
+    return (<Pressable {...rest}>
+      <symbiote-view {...feedbackProps()}>{local.children}</symbiote-view>
+    </Pressable>);
+}
+// The statics ride on the component value so callers reach TouchableNativeFeedback.Ripple(…)
+// exactly like RN. They are the shared functions themselves, not wrappers.
+export const TouchableNativeFeedback = Object.assign(TouchableNativeFeedbackImpl, {
+    SelectableBackground: selectableBackground,
+    SelectableBackgroundBorderless: selectableBackgroundBorderless,
+    Ripple: rippleBackground,
+    canUseNativeForeground,
+});

package/build/components/view.d.ts

@@ -0,0 +1,32 @@
+import { type Ref } from 'solid-js';
+import type { JSX } from '../jsx-runtime';
+import { type IAccessibilityProps, type IAriaProps, type IResponderProps } from '@symbiote-native/components';
+import type { IClassNameValue, IStyleProp, ISymbioteEvent, IViewStyle } from '@symbiote-native/engine';
+import type { IHostInstance } from '../host-instance';
+export interface IViewProps extends IAccessibilityProps, IAriaProps, IResponderProps {
+    style?: IStyleProp<IViewStyle>;
+    class?: IClassNameValue;
+    onPress?: (event: ISymbioteEvent) => void;
+    onPressIn?: (event: ISymbioteEvent) => void;
+    onPressOut?: (event: ISymbioteEvent) => void;
+    onLayout?: (event: ISymbioteEvent) => void;
+    onFocus?: (event: ISymbioteEvent) => void;
+    onBlur?: (event: ISymbioteEvent) => void;
+    pointerEvents?: 'auto' | 'none' | 'box-none' | 'box-only';
+    hitSlop?: number | {
+        top?: number;
+        left?: number;
+        bottom?: number;
+        right?: number;
+    };
+    id?: string;
+    focusable?: boolean;
+    collapsable?: boolean;
+    removeClippedSubviews?: boolean;
+    renderToHardwareTextureAndroid?: boolean;
+    shouldRasterizeIOS?: boolean;
+    needsOffscreenAlphaCompositing?: boolean;
+    ref?: Ref<IHostInstance>;
+    children?: JSX.Element;
+}
+export declare function View(props: IViewProps): JSX.Element;

package/build/components/view.jsx

@@ -0,0 +1,49 @@
+// View — the Solid host primitive, and the file that fixes the children/ref idiom every other
+// Solid component will copy.
+//
+// WHY THIS IS REAL JSX AND NOT A HAND-BUILT NODE. `symbiote-view` takes a live subtree of the
+// user's components, and reducing that subtree to primitives IS Solid's reconciler. So the only
+// two moving parts are (a) forwarding a prop bag onto one host element and (b) handing the
+// children accessor to the renderer's `insert` — precisely what compiled JSX emits
+// (`spread(el, mergeProps(bag), true)` + `insert(el, () => props.children)`, verified against
+// babel-preset-solid's output). Writing those calls by hand would be the compiler's job done
+// worse, and this is the file a Solid author reads first.
+//
+// There is NO renderView() in @symbiote-native/components, and there must not be
+// (.claude/rules/component-render-fn-boundary.md). A render fn moves to core only when every
+// input is a framework-agnostic VALUE; `children` is a live framework subtree that flows through
+// the reconciler and is never converted back into a Descriptor. So descriptorToSolid has nothing
+// to do here — View builds its host element directly, exactly as React's and Vue's do.
+//
+// NOTHING here destructures `props` at setup. Solid props are getters and a component body runs
+// ONCE; splitProps is the idiomatic split that keeps the rest reactive, and every read of the
+// remaining props happens inside the bag accessor, which `spread` re-runs as a render effect.
+import { splitProps } from 'solid-js';
+import { resolveAccessibilityProps, } from '@symbiote-native/components';
+import { applyHostRef } from '../utils/host-ref.js';
+import { withStableKeys } from '../utils/stable-keys.js';
+export function View(props) {
+    // `children` and `ref` are pulled out rather than left to ride in the bag. Both are skipped by
+    // spreadExpression's prop loop anyway, but leaving them in would make the bag accessor depend on
+    // the children subtree (recomputing every prop when only a child changed) and would put `ref`
+    // behind spread's own ref effect, which re-runs — and so re-calls the caller's ref — on EVERY
+    // prop change. React calls a ref once per attach; this keeps that contract.
+    const [local, rest] = splitProps(props, ['children', 'ref', 'id']);
+    // RN's modern `id` is a W3C-named alias for `nativeID`: View.js copies it over
+    // (`processedProps.nativeID = id`), so `id` wins when both are set. Folded here, with the raw
+    // `id` key dropped so it never reaches Fabric — every non-function prop otherwise passes
+    // through to the slot untouched. `nativeID` is emitted UNCONDITIONALLY (undefined when neither
+    // is set) rather than conditionally like React's resolveId: a key that appears and disappears
+    // between runs is the exact hazard withStableKeys exists for, and not creating it is cheaper
+    // than widening it back.
+    const bag = withStableKeys(() => ({
+        ...resolveAccessibilityProps(rest),
+        nativeID: local.id ?? rest.nativeID,
+    }));
+    const attachRef = (node) => {
+        applyHostRef(local.ref, node);
+    };
+    return (<symbiote-view ref={attachRef} {...bag()}>
+      {local.children}
+    </symbiote-view>);
+}

package/build/components/virtualized-list/index.android.d.ts

@@ -0,0 +1,2 @@
+export type { IVirtualizedListProps, IVirtualizedListComponent, IVirtualizedListCellInfo, IVirtualizedListRenderItem, IVirtualizedListHandle, ICellLayout, ISeparators, ISeparatorProps, IViewToken, IViewableItemsChangedInfo, IViewabilityConfig, IViewabilityConfigCallbackPair, } from './shared';
+export declare const VirtualizedList: import("./shared").IVirtualizedListComponent;

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

@@ -0,0 +1,9 @@
+// VirtualizedList on Android. An Android ScrollView accepts only ONE child, so a RefreshControl
+// cannot sit beside the content the way iOS allows ("addViewAt: failed to insert view … at index 1").
+// Instead the RefreshControl (AndroidSwipeRefreshLayout) WRAPS the scroll host, which nests inside it
+// so the inner scroll takes the gesture before the refresh parent — RN's own ScrollView.js android
+// branch. Metro picks this file on an Android host; no Platform.OS read.
+import { createVirtualizedList } from './shared.jsx';
+export const VirtualizedList = createVirtualizedList({
+    refreshControlMode: 'wrap',
+});

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

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

package/build/components/virtualized-list/index.ios.d.ts

@@ -0,0 +1,2 @@
+export type { IVirtualizedListProps, IVirtualizedListComponent, IVirtualizedListCellInfo, IVirtualizedListRenderItem, IVirtualizedListHandle, ICellLayout, ISeparators, ISeparatorProps, IViewToken, IViewableItemsChangedInfo, IViewabilityConfig, IViewabilityConfigCallbackPair, } from './shared';
+export declare const VirtualizedList: import("./shared").IVirtualizedListComponent;

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

@@ -0,0 +1,9 @@
+// VirtualizedList on iOS. The RefreshControl (PullToRefreshView) is a CHILD of the scroll host,
+// rendered as a childless SIBLING BEFORE the content container — RN ScrollView.js's
+// `{refreshControl}{contentContainer}`, the same fact this adapter's ScrollView and 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 { createVirtualizedList } from './shared.jsx';
+export const VirtualizedList = createVirtualizedList({
+    refreshControlMode: 'sibling',
+});

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

@@ -0,0 +1,4 @@
+// Base / default VirtualizedList: 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 — the same shape scroll-view/index.ts has.
+export * from './index.ios.js';

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

@@ -0,0 +1,75 @@
+import { type Accessor, type Ref } from 'solid-js';
+import type { JSX } from '../../jsx-runtime';
+import { type IAccessibilityProps, type IAriaProps, type ICellLayout, type IViewabilityConfig, type IViewabilityConfigCallbackPair, type IViewableItemsChangedInfo, type ISeparatorProps, type ISeparators, type IViewToken, type IVirtualizedListHandle } from '@symbiote-native/components';
+import { type IClassNameValue, type IStyleProp, type ISymbioteEvent, type IViewStyle } from '@symbiote-native/engine';
+import type { IScrollViewHostPlatform } from '../scroll-view/shared';
+export type { IScrollViewHostPlatform };
+export type { ICellLayout, ISeparators, ISeparatorProps, IViewToken, IViewableItemsChangedInfo, IViewabilityConfig, IViewabilityConfigCallbackPair, IVirtualizedListHandle, };
+export interface IVirtualizedListCellInfo<ItemT> {
+    item: ItemT;
+    index: number;
+    separators: ISeparators;
+}
+export type IVirtualizedListRenderItem<ItemT> = (info: Accessor<IVirtualizedListCellInfo<ItemT>>) => JSX.Element;
+export interface IVirtualizedListProps<ItemT> extends IAccessibilityProps, IAriaProps {
+    data: unknown;
+    getItem: (data: unknown, index: number) => ItemT;
+    getItemCount: (data: unknown) => number;
+    renderItem: IVirtualizedListRenderItem<ItemT>;
+    getItemLayout?: (data: unknown, index: number) => {
+        length: number;
+        offset: number;
+        index: number;
+    };
+    initialNumToRender?: number;
+    windowSize?: number;
+    ListHeaderComponent?: JSX.Element;
+    ListFooterComponent?: JSX.Element;
+    ListEmptyComponent?: JSX.Element;
+    ItemSeparatorComponent?: (props: ISeparatorProps<ItemT>) => JSX.Element;
+    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;
+    scrollEventThrottle?: number;
+    keyboardShouldPersistTaps?: boolean | 'always' | 'never' | 'handled';
+    keyboardDismissMode?: 'none' | 'on-drag' | 'interactive';
+    horizontal?: boolean;
+    inverted?: boolean;
+    style?: IStyleProp<IViewStyle>;
+    contentContainerStyle?: IStyleProp<IViewStyle> | string;
+    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 function createVirtualizedList(platform: IScrollViewHostPlatform): IVirtualizedListComponent;