@symbiote-native/react 0.1.0

package/build/components/image/index.js

@@ -0,0 +1,28 @@
+import {} from 'react';
+import { imageStatics, renderImage, resolveAccessibilityProps, } from '@symbiote-native/components';
+import { descriptorToReact } from '../../descriptor-to-react';
+// renderImage takes a pre-resolved view + passthrough (the ISwitchViewProps shape), so the
+// adapter folds aria/role and splits the typed transform fields from the forward-only rest.
+// The W3C source aliases (src/srcSet/crossOrigin/referrerPolicy) and width/height become typed
+// view fields (consumed by the source/style fold), so they never leak to Fabric via passthrough.
+const ImageComponent = rawProps => {
+    const { source, defaultSource, loadingIndicatorSource, style, resizeMode, tintColor, src, srcSet, alt, width, height, crossOrigin, referrerPolicy, ...passthrough } = resolveAccessibilityProps(rawProps);
+    return descriptorToReact(renderImage({
+        source,
+        defaultSource,
+        loadingIndicatorSource,
+        style,
+        resizeMode,
+        tintColor,
+        src,
+        srcSet,
+        alt,
+        width,
+        height,
+        crossOrigin,
+        referrerPolicy,
+        passthrough,
+    }));
+};
+export const Image = Object.assign(ImageComponent, imageStatics);
+export { setImageSourceResolver } from '@symbiote-native/components';

package/build/components/image-background/index.d.ts

@@ -0,0 +1,10 @@
+import { type ReactElement, type ReactNode } from 'react';
+import { type IImageProps } from '@symbiote-native/components';
+import type { IStyleProp, IViewStyle } from '../../utils/styles';
+export interface IImageBackgroundProps extends Omit<IImageProps, 'style'> {
+    style?: IStyleProp<IViewStyle>;
+    imageStyle?: IStyleProp<IViewStyle> | string;
+    className?: string;
+    children?: ReactNode;
+}
+export declare function ImageBackground(props: IImageBackgroundProps): ReactElement;

package/build/components/image-background/index.js

@@ -0,0 +1,46 @@
+// ImageBackground: the React lifecycle half. The composition (the absolute-fill Image behind
+// the children, the dimension-proxy + style-merge math) lives framework-agnostic in
+// @symbiote-native/components/renderImageBackground and is shared verbatim with Vue; here React only
+// folds aria/role, splits the typed Image transform fields from the forward-only rest, bridges
+// the Descriptor to elements, and appends the user children ON TOP of the inner image.
+import { createElement } from 'react';
+import { resolveClassName } from '@symbiote-native/engine';
+import { renderImageBackground, resolveAccessibilityProps, } from '@symbiote-native/components';
+import { descriptorToReact } from '../../descriptor-to-react';
+function toChild(child) {
+    return typeof child === 'string' ? child : descriptorToReact(child);
+}
+export function ImageBackground(props) {
+    // className is pulled out here, like style, and applied to the WRAPPER element below — left
+    // in ...imageProps it would fall into `passthrough` and land on the INNER Image instead
+    // (renderImageBackground's `image.passthrough`, not the wrapper's own props).
+    const { children, style, imageStyle, className, ...imageProps } = props;
+    // imageStyle targets the INNER image (renderImageBackground's own field), unlike className
+    // above which lands on the wrapper — resolve the string here, before it flows in below.
+    const resolvedImageStyle = typeof imageStyle === 'string' ? resolveClassName(imageStyle) : imageStyle;
+    // The W3C source aliases (src/srcSet/crossOrigin/referrerPolicy) and width/height become typed
+    // Image view fields (consumed by the source/style fold), so they never leak to Fabric via
+    // passthrough; everything else (events, blurRadius, the folded accessibility*, testID) forwards.
+    const { source, defaultSource, loadingIndicatorSource, resizeMode, tintColor, src, srcSet, alt, width, height, crossOrigin, referrerPolicy, ...passthrough } = resolveAccessibilityProps(imageProps);
+    const wrapper = renderImageBackground({
+        style,
+        imageStyle: resolvedImageStyle,
+        image: {
+            source,
+            defaultSource,
+            loadingIndicatorSource,
+            resizeMode,
+            tintColor,
+            src,
+            srcSet,
+            alt,
+            width,
+            height,
+            crossOrigin,
+            referrerPolicy,
+            passthrough,
+        },
+    });
+    // wrapper = symbiote-view > [imageDescriptor]; the user children paint AFTER the image (on top).
+    return createElement(wrapper.type, { key: wrapper.key, ...wrapper.props, className }, ...wrapper.children.map(toChild), children);
+}

package/build/components/input-accessory-view/index.d.ts

@@ -0,0 +1,11 @@
+import { type FC, type ReactNode } from 'react';
+import { type IAccessibilityProps, type IAriaProps } from '@symbiote-native/components';
+import type { IStyleProp, IViewStyle } from '../../utils/styles';
+export interface IInputAccessoryViewProps extends IAccessibilityProps, IAriaProps {
+    nativeID?: string;
+    backgroundColor?: string;
+    style?: IStyleProp<IViewStyle>;
+    className?: string;
+    children?: ReactNode;
+}
+export declare const InputAccessoryView: FC<IInputAccessoryViewProps>;

package/build/components/input-accessory-view/index.js

@@ -0,0 +1,14 @@
+// InputAccessoryView: the React lifecycle half (iOS). The host-node assembly (nativeID /
+// backgroundColor / style / accessibility forwarding) lives framework-agnostic in
+// @symbiote-native/components/renderInputAccessoryView and is shared verbatim with Vue; here React only
+// folds aria/role, bridges the Descriptor, and nests the user children under the host.
+import { createElement } from 'react';
+import { renderInputAccessoryView, resolveAccessibilityProps, } from '@symbiote-native/components';
+export const InputAccessoryView = rawProps => {
+    // Owns its host element (symbiote-input-accessory-view), so it folds aria/role here; the
+    // resolved accessibility* surface rides the node via `...passthrough`.
+    const { nativeID, backgroundColor, style, children, ...passthrough } = resolveAccessibilityProps(rawProps);
+    const host = renderInputAccessoryView({ nativeID, backgroundColor, style, passthrough });
+    // host has no structural children; the user children nest directly under it.
+    return createElement(host.type, { key: host.key, ...host.props }, children);
+};

package/build/components/keyboard-avoiding-view/index.d.ts

@@ -0,0 +1,17 @@
+import { type FC, type ReactNode } from 'react';
+import { type ISymbioteEvent } from '@symbiote-native/engine';
+import { type IKeyboardAvoidingBehavior } from '@symbiote-native/components';
+import type { IAccessibilityProps, IAriaProps } from '@symbiote-native/components';
+import type { IStyleProp, IViewStyle } from '../../utils/styles';
+export type { IKeyboardAvoidingBehavior } from '@symbiote-native/components';
+export interface IKeyboardAvoidingViewProps extends IAccessibilityProps, IAriaProps {
+    behavior?: IKeyboardAvoidingBehavior;
+    enabled?: boolean;
+    keyboardVerticalOffset?: number;
+    contentContainerStyle?: IStyleProp<IViewStyle>;
+    style?: IStyleProp<IViewStyle>;
+    className?: string;
+    children?: ReactNode;
+    onLayout?: (event: ISymbioteEvent) => void;
+}
+export declare const KeyboardAvoidingView: FC<IKeyboardAvoidingViewProps>;

package/build/components/keyboard-avoiding-view/index.js

@@ -0,0 +1,85 @@
+// KeyboardAvoidingView: composes the host View and shifts it out of the keyboard's way as
+// the keyboard shows/hides. It subscribes to the Keyboard module (native->JS events) and
+// recomputes a bottom inset from the keyboard frame and the view's own measured frame.
+// Mirrors RN's Libraries/Components/Keyboard/KeyboardAvoidingView.js, as a function component.
+//
+// The inset math + the behavior → style/structure decision are framework-agnostic and live in
+// @symbiote-native/components (render-keyboard-avoiding-view), shared verbatim with the Vue adapter.
+// React supplies only the lifecycle: useState for the inset, useRef for the measured frame, a
+// useEffect subscription, and the descriptor-free element assembly around its children.
+import { createElement, useEffect, useRef, useState, } from 'react';
+import { dlog } from '@symbiote-native/engine';
+import { computeInset, readKeyboardFrame, readLayoutFrame, resolveKeyboardAvoidingLayout, DEFAULT_VERTICAL_OFFSET, } from '@symbiote-native/components';
+import { View } from '../../components';
+import { Keyboard, KEYBOARD_EVENT } from '../../modules/keyboard';
+export const KeyboardAvoidingView = props => {
+    const { behavior, enabled = true, keyboardVerticalOffset = DEFAULT_VERTICAL_OFFSET, contentContainerStyle, style, children, onLayout, 
+    // The wrapper is the View FC, which runs resolveAccessibilityProps itself, so
+    // the raw aria/role + accessibility* props pass through untouched here and fold
+    // there once.
+    ...accessibilityRest } = props;
+    const [inset, setInset] = useState(0);
+    // Mutable, not state: changing the frame alone shouldn't re-render; it feeds the
+    // next keyboard event's inset math.
+    const frameRef = useRef(undefined);
+    const initialHeightRef = useRef(undefined);
+    useEffect(() => {
+        const onShow = (payload) => {
+            const keyboard = readKeyboardFrame(payload);
+            const next = computeInset(frameRef.current, keyboard, keyboardVerticalOffset);
+            dlog(`KeyboardAvoidingView show -> inset ${next}`);
+            setInset(next);
+        };
+        const onHide = () => {
+            dlog('KeyboardAvoidingView hide -> inset 0');
+            setInset(0);
+        };
+        const subscriptions = [
+            Keyboard.addListener(KEYBOARD_EVENT.didShow, onShow),
+            Keyboard.addListener(KEYBOARD_EVENT.didChangeFrame, onShow),
+            Keyboard.addListener(KEYBOARD_EVENT.didHide, onHide),
+        ];
+        return () => {
+            for (const subscription of subscriptions)
+                subscription.remove();
+        };
+    }, [keyboardVerticalOffset]);
+    const handleLayout = (event) => {
+        const frame = readLayoutFrame(event.nativeEvent.layout);
+        if (frame !== undefined) {
+            frameRef.current = frame;
+            if (initialHeightRef.current === undefined)
+                initialHeightRef.current = frame.height;
+        }
+        onLayout?.(event);
+    };
+    // When disabled the inset is forced to 0, so every behavior mode renders the view
+    // untouched (RN gates each bottomHeight/height computation on `enabled ?? true`).
+    const effectiveInset = enabled ? inset : 0;
+    const layout = resolveKeyboardAvoidingLayout({
+        behavior,
+        effectiveInset,
+        initialHeight: initialHeightRef.current,
+        style,
+        contentContainerStyle,
+    });
+    // 'nested' ('position') pushes the content in an inner View by `bottom: inset`; the wrapper
+    // modes adjust the single wrapper directly.
+    if (layout.kind === 'nested') {
+        return renderWrapper(layout.wrapperStyle, createElement(View, { style: layout.innerStyle }, children));
+    }
+    return renderWrapper(layout.wrapperStyle, children);
+    // The wrapper carries onLayout. The View FC's public props don't surface it, but
+    // `symbiote-view` routes the base layout event at runtime; widen the props through
+    // a typed variable (no inline-literal excess-property check, no `as`) so the
+    // onLayout reaches the host without editing View's public type.
+    function renderWrapper(wrapStyle, content) {
+        const wrapperProps = {
+            ...accessibilityRest,
+            style: wrapStyle,
+            onLayout: handleLayout,
+            children: content,
+        };
+        return createElement(View, wrapperProps);
+    }
+};

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

@@ -0,0 +1,24 @@
+import { type FC, type ReactNode } from 'react';
+import { type IAccessibilityProps, type IAriaProps, type IModalAnimationType, type IModalOrientation, type IModalOrientationChangeEvent, type IModalPresentationStyle } from '@symbiote-native/components';
+import type { IStyleProp, IViewStyle } from '../../utils/styles';
+export type { IModalAnimationType, IModalPresentationStyle, IModalOrientation, IModalOrientationChangeEvent, } from '@symbiote-native/components';
+export interface IModalProps extends IAccessibilityProps, IAriaProps {
+    visible?: boolean;
+    transparent?: boolean;
+    backdropColor?: string;
+    animationType?: IModalAnimationType;
+    presentationStyle?: IModalPresentationStyle;
+    supportedOrientations?: ReadonlyArray<IModalOrientation>;
+    hardwareAccelerated?: boolean;
+    statusBarTranslucent?: boolean;
+    navigationBarTranslucent?: boolean;
+    allowSwipeDismissal?: boolean;
+    onShow?: () => void;
+    onDismiss?: () => void;
+    onRequestClose?: () => void;
+    onOrientationChange?: (event: IModalOrientationChangeEvent) => void;
+    style?: IStyleProp<IViewStyle>;
+    className?: string;
+    children?: ReactNode;
+}
+export declare const Modal: FC<IModalProps>;

package/build/components/modal/index.js

@@ -0,0 +1,56 @@
+// Modal: the React lifecycle half. RCTModalHostView is an ordinary Fabric host node committing
+// through the same childSet as the rest of the tree (no second JS surface). The style math (the
+// backdrop override, the container/host styles, the presentationStyle default), the visible gate,
+// and the iOS keep-alive reducer all live framework-agnostic in @symbiote-native/components and are
+// shared verbatim with Vue; here React supplies only the lifecycle: useReducer over the keep-alive
+// state machine + a post-render effect to drive the visible→hidden transition, and the Descriptor
+// bridge, nesting the user children UNDER the container View.
+//
+// Deferred vs RN: RN's native exit-animation timing (the modalDismissed emitter on old-renderer
+// iOS) is not reproduced; onDismiss is delivered as the native topDismiss DirectEvent via the
+// host's onDismiss prop (it rides `...passthrough`), and the keep-alive holds the node mounted
+// through the exit transition. The native exit-animation timing is what's deferred, not the
+// callback contract.
+import { createElement, useEffect, useReducer } from 'react';
+import { dlog } from '@symbiote-native/engine';
+import { createInitialModalState, modalReducer, renderModal, resolveAccessibilityProps, shouldRenderModal, } from '@symbiote-native/components';
+export const Modal = rawProps => {
+    // Modal owns its host element (symbiote-modal), so it folds aria/role here; the resolved fields
+    // ride the host node via `...passthrough`. The events (onShow/onDismiss/onRequestClose/
+    // onOrientationChange) are real ViewConfig DirectEvents, so they too ride passthrough raw.
+    // className is pulled out here, like style, and applied to the CONTAINER element below — left in
+    // ...passthrough it would land on the outer symbiote-modal host instead (renderModal composes
+    // `style` into the container's style, not the host's).
+    const { visible, transparent, backdropColor, animationType, presentationStyle, supportedOrientations, hardwareAccelerated, statusBarTranslucent, navigationBarTranslucent, allowSwipeDismissal, style, className, children, ...passthrough } = resolveAccessibilityProps(rawProps);
+    // The iOS keep-alive: the effect runs AFTER this render, so a visible→hidden transition keeps the
+    // node mounted for one frame (state.isRendered still true here) before the next render unmounts it,
+    // the same shape as RN's componentDidUpdate setState (see state/modal.ts).
+    const [state, dispatch] = useReducer(modalReducer, visible === true, createInitialModalState);
+    useEffect(() => {
+        dispatch(visible === true ? { type: 'show' } : { type: 'hide' });
+    }, [visible]);
+    if (!shouldRenderModal(visible === true, state)) {
+        dlog('Modal hidden -> no node committed');
+        return null;
+    }
+    const root = renderModal({
+        visible,
+        transparent,
+        backdropColor,
+        animationType,
+        presentationStyle,
+        supportedOrientations,
+        hardwareAccelerated,
+        statusBarTranslucent,
+        navigationBarTranslucent,
+        allowSwipeDismissal,
+        style,
+        passthrough,
+    });
+    // root = symbiote-modal > [container]; the user children nest UNDER the container View, never as
+    // a direct sibling of the host (RN's modal content layout).
+    const [container] = root.children;
+    if (typeof container === 'string')
+        return null;
+    return createElement(root.type, { key: root.key, ...root.props }, createElement(container.type, { key: container.key, ...container.props, className }, children));
+};

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

@@ -0,0 +1,30 @@
+import { type FC, type ReactNode } from 'react';
+import { type IPressState, type IPressHandler, type IRectOffset, type IPressableAndroidRippleConfig } from '@symbiote-native/components';
+import type { IAccessibilityProps, IAriaProps } from '@symbiote-native/components';
+import type { IStyleProp, IViewStyle } from '../../utils/styles';
+export type { IPressState, IPressableAndroidRippleConfig } from '@symbiote-native/components';
+type IPressableStyle = IStyleProp<IViewStyle> | ((state: IPressState) => IStyleProp<IViewStyle>);
+type IChildrenProp = ReactNode | ((state: IPressState) => ReactNode);
+export interface IPressableProps extends IAccessibilityProps, IAriaProps {
+    onPress?: IPressHandler;
+    onPressIn?: IPressHandler;
+    onPressOut?: IPressHandler;
+    onPressMove?: IPressHandler;
+    onLongPress?: IPressHandler;
+    delayLongPress?: number;
+    disabled?: boolean;
+    cancelable?: boolean;
+    hitSlop?: IRectOffset;
+    pressRetentionOffset?: IRectOffset;
+    unstable_pressDelay?: number;
+    android_ripple?: IPressableAndroidRippleConfig;
+    android_disableSound?: boolean;
+    onHoverIn?: IPressHandler;
+    onHoverOut?: IPressHandler;
+    delayHoverIn?: number;
+    delayHoverOut?: number;
+    style?: IPressableStyle;
+    className?: string;
+    children?: IChildrenProp;
+}
+export declare const Pressable: FC<IPressableProps>;

package/build/components/pressable/index.js

@@ -0,0 +1,100 @@
+// Pressable: the React lifecycle half. The press lifecycle (the long-press timer, unstable_press-
+// Delay deferral, the pressRetentionOffset drift test, the suppression flags) lives in
+// @symbiote-native/components/state as a pure machine over a runtime + host; the render decisions (the
+// responder listeners, the disabled→accessibilityState fold, the ripple prop) in
+// @symbiote-native/components/view. Here React owns only the lifecycle: useState for `pressed`, a ref for
+// the runtime, a ref for the View instance (the measure handle), and a useMemo that rebuilds the
+// handlers when the config changes. This is the React twin of the Vue adapter's setup-scope
+// runtime + setPressed ref.
+//
+// Three RN interaction props that change real app feel ride on top of the shared synthesis,
+// entirely in JS: android_ripple (an Android native-feedback prop on a dedicated inner View, inert
+// on iOS), unstable_pressDelay, and pressRetentionOffset (the drift region), all handled by the
+// shared machine; here we only wire its host + render the View.
+import { createElement, useMemo, useRef, useState } from 'react';
+import { createPressHandlers, createPressRuntime, rippleProps, buildPressableListeners, resolveDisabledAccessibilityState, noteHoverNoop, DEFAULT_DELAY_LONG_PRESS_MS, } from '@symbiote-native/components';
+import { View } from '../../components';
+function resolveStyle(style, state) {
+    if (typeof style === 'function')
+        return style(state);
+    return style;
+}
+function resolveChildren(children, state) {
+    if (typeof children === 'function')
+        return children(state);
+    return children;
+}
+export const Pressable = props => {
+    const { onPress, onPressIn, onPressOut, onPressMove, onLongPress, delayLongPress = DEFAULT_DELAY_LONG_PRESS_MS, disabled, cancelable, hitSlop, pressRetentionOffset, unstable_pressDelay = 0, android_ripple, android_disableSound, onHoverIn, onHoverOut, delayHoverIn, delayHoverOut, accessibilityState, testID, style, children, 
+    // The remaining accessibility / aria props forward to View untouched; View runs
+    // resolveAccessibilityProps, so aria/role fold there, once.
+    ...accessibilityRest } = props;
+    const [pressed, setPressed] = useState(false);
+    // The mutable press runtime (timers, suppression flags, measured region), a ref so mutating it
+    // never triggers a re-render; only setPressed does.
+    const runtime = useRef(createPressRuntime()).current;
+    // The View instance, so the machine can measure its on-screen rect on responder grant.
+    const viewRef = useRef(null);
+    // The lifecycle seam the machine fills: flip pressed-state, and expose the View's raw measure.
+    const host = useMemo(() => ({
+        setPressed,
+        getMeasureFn: () => {
+            const view = viewRef.current;
+            if (view === null)
+                return undefined;
+            return callback => view.measure(callback);
+        },
+        schedule: (callback, ms) => {
+            const id = setTimeout(callback, ms);
+            return () => clearTimeout(id);
+        },
+    }), []);
+    const handlers = useMemo(() => createPressHandlers({
+        onPress,
+        onPressIn,
+        onPressOut,
+        onPressMove,
+        onLongPress,
+        delayLongPress,
+        unstable_pressDelay,
+        hitSlop,
+        pressRetentionOffset,
+    }, runtime, host), [
+        onPress,
+        onPressIn,
+        onPressOut,
+        onPressMove,
+        onLongPress,
+        delayLongPress,
+        unstable_pressDelay,
+        hitSlop,
+        pressRetentionOffset,
+        runtime,
+        host,
+    ]);
+    noteHoverNoop(onHoverIn, onHoverOut);
+    void delayHoverIn;
+    void delayHoverOut;
+    const state = { pressed };
+    const resolvedAccessibilityState = resolveDisabledAccessibilityState(accessibilityState, disabled);
+    const viewProps = {
+        ...accessibilityRest,
+        // The ref is the handle the retention measure reaches through (measure on grant).
+        ref: viewRef,
+        style: resolveStyle(style, state),
+        hitSlop,
+        accessibilityState: resolvedAccessibilityState,
+        testID,
+    };
+    // Forward the Android tap-sound suppressor under RN's own key; inert on iOS.
+    if (android_disableSound !== undefined)
+        viewProps.android_disableSound = android_disableSound;
+    Object.assign(viewProps, buildPressableListeners(handlers, { disabled, cancelable }));
+    // android_ripple rides a dedicated inner View (the Pressable's own View only forwards a fixed
+    // prop set), mirroring touchable-native-feedback. On iOS the ripple prop is undefined, so the
+    // child renders unwrapped, no extra node.
+    const ripple = android_ripple !== undefined ? rippleProps(android_ripple) : undefined;
+    const content = resolveChildren(children, state);
+    const inner = ripple !== undefined ? createElement(View, ripple, content) : content;
+    return createElement(View, viewProps, inner);
+};

package/build/components/refresh-control/index.d.ts

@@ -0,0 +1,17 @@
+import { type FC, type ReactNode } from 'react';
+import { type IAccessibilityProps, type IAriaProps } from '@symbiote-native/components';
+export interface IRefreshControlProps extends IAccessibilityProps, IAriaProps {
+    refreshing: boolean;
+    onRefresh?: () => void | Promise<void>;
+    tintColor?: string;
+    title?: string;
+    titleColor?: string;
+    progressViewOffset?: number;
+    colors?: readonly string[];
+    progressBackgroundColor?: string;
+    size?: 'default' | 'large';
+    enabled?: boolean;
+    children?: ReactNode;
+    className?: string;
+}
+export declare const RefreshControl: FC<IRefreshControlProps>;

package/build/components/refresh-control/index.js

@@ -0,0 +1,21 @@
+// RefreshControl primitive. On iOS this is the PullToRefreshView Fabric node that
+// lives INSIDE a ScrollView (a sibling of the content container), giving the
+// pull-to-refresh gesture. `refreshing` is a controlled prop: the parent owns it
+// and pushes it down each commit; native reports the gesture via the direct
+// `topRefresh` event, which shared routes to the `refresh` listener (onRefresh).
+import { createElement } from 'react';
+import { dlog } from '@symbiote-native/engine';
+import { resolveAccessibilityProps, } from '@symbiote-native/components';
+export const RefreshControl = rawProps => {
+    // Owns its host element (symbiote-refresh-control), so it folds aria/role here;
+    // the resolved accessibility* fields ride down via `...nativeProps`.
+    const props = resolveAccessibilityProps(rawProps);
+    const { children, ...nativeProps } = props;
+    dlog('RefreshControl -> PullToRefreshView');
+    dlog(`RefreshControl refreshing=${String(props.refreshing)}`);
+    if (props.enabled !== undefined)
+        dlog(`RefreshControl enabled=${String(props.enabled)} (Android-only)`);
+    if (props.onRefresh !== undefined)
+        dlog('RefreshControl onRefresh listener wired');
+    return createElement('symbiote-refresh-control', { ...nativeProps }, children);
+};

package/build/components/safe-area-view/index.d.ts

@@ -0,0 +1,11 @@
+import { type FC, type ReactNode } from 'react';
+import { type ISymbioteEvent } from '@symbiote-native/engine';
+import { type IAccessibilityProps, type IAriaProps } from '@symbiote-native/components';
+import type { IStyleProp, IViewStyle } from '../../utils/styles';
+export interface ISafeAreaViewProps extends IAccessibilityProps, IAriaProps {
+    style?: IStyleProp<IViewStyle>;
+    className?: string;
+    children?: ReactNode;
+    onLayout?: (event: ISymbioteEvent) => void;
+}
+export declare const SafeAreaView: FC<ISafeAreaViewProps>;

package/build/components/safe-area-view/index.js

@@ -0,0 +1,18 @@
+// SafeAreaView primitive. A plain view whose native side insets its children to
+// the safe area (notch, rounded corners, system bars). There is no JS-side
+// translation; RN just renders the native RCTSafeAreaView and lets the host do
+// the inset math, so this maps style + children straight onto the intrinsic.
+import { createElement } from 'react';
+import { dlog } from '@symbiote-native/engine';
+import { resolveAccessibilityProps, } from '@symbiote-native/components';
+export const SafeAreaView = rawProps => {
+    // Owns its host element (symbiote-safe-area-view), so it folds aria/role here;
+    // the resolved accessibility* surface rides the node via `...accessibilityRest`.
+    const props = resolveAccessibilityProps(rawProps);
+    const { style, children, onLayout, ...accessibilityRest } = props;
+    dlog('SafeAreaView -> SafeAreaView');
+    const nodeProps = { ...accessibilityRest, style };
+    if (onLayout !== undefined)
+        nodeProps.onLayout = onLayout;
+    return createElement('symbiote-safe-area-view', nodeProps, children);
+};

package/build/components/scroll-view/index.android.d.ts

@@ -0,0 +1,3 @@
+import { type IScrollViewHandle, type IScrollViewProps } from './shared';
+export type { IScrollViewProps, IScrollViewHandle } from './shared';
+export declare const ScrollView: import("react").ForwardRefExoticComponent<IScrollViewProps & import("react").RefAttributes<IScrollViewHandle>>;

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

@@ -0,0 +1,53 @@
+// ScrollView on Android: an Android ScrollView accepts only ONE child, so a RefreshControl
+// can't be a sibling of the content the way iOS allows ("addViewAt: failed to insert view
+// ... at index 1"). Instead the RefreshControl (AndroidSwipeRefreshLayout) WRAPS the
+// scroll view, with the scroll view nested inside and nestedScrollEnabled so the inner
+// scroll handles the gesture before the refresh parent, which mirrors RN's ScrollView.js
+// android branch (cloneElement(refreshControl, {style}, <ScrollView nestedScrollEnabled
+// style={flex:1}>{content}</ScrollView>)). Metro picks this on an Android host; no
+// Platform.OS read. See ADR 0020.
+// device-verify-pending: the wrap shape mirrors RN, proven on a real host by the absence
+// of the "addViewAt: failed to insert" crash.
+import { cloneElement, createElement, forwardRef, useImperativeHandle, useRef } from 'react';
+import { dlog } from '@symbiote-native/engine';
+import { buildScrollViewHandle, splitLayoutProps } from '@symbiote-native/components';
+import { usePreparedScrollView, useNativeStickyScrollAttach, } from './shared';
+export const ScrollView = forwardRef((props, forwardedRef) => {
+    const { scrollViewIntrinsic, scrollViewBaseStyle, outerProps, style, layoutSplitStyle, content, refreshControl, scrollAnimatedValue, nativeStickyAvailable, } = usePreparedScrollView(props);
+    // The node ref backs the imperative handle; it attaches to the inner scroll-view element
+    // (the wrap shape leaves the scroll view as the command target, not the RefreshControl).
+    const ref = useRef(null);
+    // Lazy getter, not the ref itself: the node is null until the element commits, so the handle
+    // must read ref.current on each command (ADR 0024 §3), an eager capture would freeze null.
+    useImperativeHandle(forwardedRef, () => buildScrollViewHandle(() => ref.current), []);
+    // Drive the sticky scroll value on the native UI thread (RN attachNativeEvent). No-op on a
+    // host without the native animated module. The JS sticky path stays in effect.
+    useNativeStickyScrollAttach(ref, scrollAnimatedValue, nativeStickyAvailable);
+    dlog('ScrollView.ANDROID refreshControl=' + (refreshControl === undefined ? 'NONE(1child)' : 'WRAP'));
+    if (refreshControl === undefined) {
+        // Base style (flexDirection: row for horizontal) under user style; undefined base
+        // (vertical) passes the user style through unchanged.
+        const scrollStyle = scrollViewBaseStyle ? [scrollViewBaseStyle, style] : style;
+        return createElement(scrollViewIntrinsic, { ...outerProps, style: scrollStyle, ref }, content);
+    }
+    // RN splits the flattened style across the two boxes (ScrollView.js android branch):
+    // LAYOUT props (margin/flex/size/position/transform/gap/…) drive the outer
+    // AndroidSwipeRefreshLayout frame; VISUAL props (background/padding/border/opacity/…) paint
+    // the inner scroll view. So the wrapper carries `outer`, and the inner scroll view its base
+    // (flexDirection/overflow) plus the visual `inner` composed over it, NOT a hardcoded flex:1
+    // that would override an explicit user height/width.
+    //
+    // layoutSplitStyle (not style): a class-only layout prop (flex/height/gap/…) is invisible to
+    // `style` (it never carries the resolved `className` value), so splitting on `style` alone
+    // starves the wrapper of its layout style and it collapses to nothing. layoutSplitStyle is
+    // `style` merged with the resolved className style (see usePreparedScrollView).
+    const { outer: outerStyle, inner: innerStyle } = splitLayoutProps(layoutSplitStyle);
+    const scrollStyle = scrollViewBaseStyle ? [scrollViewBaseStyle, innerStyle] : innerStyle;
+    // className is stripped from the spread here: layoutSplitStyle already folded its resolved
+    // value into `outer`/`inner` above, so forwarding the raw prop too would re-apply its LAYOUT
+    // half onto the inner scroll view a second time (on top of the outer wrapper).
+    const { className: _classNameAppliedViaSplit, ...innerOuterProps } = outerProps;
+    const scrollView = createElement(scrollViewIntrinsic, { ...innerOuterProps, style: scrollStyle, nestedScrollEnabled: true, ref }, content);
+    return cloneElement(refreshControl, { style: outerStyle }, scrollView);
+});
+ScrollView.displayName = 'ScrollView';

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

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

package/build/components/scroll-view/index.ios.d.ts

@@ -0,0 +1,3 @@
+import { type IScrollViewHandle, type IScrollViewProps } from './shared';
+export type { IScrollViewProps, IScrollViewHandle } from './shared';
+export declare const ScrollView: import("react").ForwardRefExoticComponent<IScrollViewProps & import("react").RefAttributes<IScrollViewHandle>>;

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

@@ -0,0 +1,27 @@
+// ScrollView on iOS: the RefreshControl is a CHILD of the scroll view, rendered as a
+// sibling BEFORE the content container (RN ScrollView.js: {refreshControl}{contentContainer}).
+// Also the base (scroll-view.ts re-exports it) for headless / web. See ADR 0020.
+import { createElement, forwardRef, useImperativeHandle, useRef } from 'react';
+import { buildScrollViewHandle } from '@symbiote-native/components';
+import { usePreparedScrollView, useNativeStickyScrollAttach, } from './shared';
+export const ScrollView = forwardRef((props, forwardedRef) => {
+    const { scrollViewIntrinsic, scrollViewBaseStyle, outerProps, style, content, refreshControl, scrollAnimatedValue, nativeStickyAvailable, } = usePreparedScrollView(props);
+    // The node ref backs the imperative handle; it attaches to the scroll-view element below
+    // (passing `ref` through createElement props binds it to the SymbioteNode, as TextInput does).
+    const ref = useRef(null);
+    // Lazy getter, not the ref itself: the node is null until the element commits, so the handle
+    // must read ref.current on each command (ADR 0024 §3), an eager capture would freeze null.
+    useImperativeHandle(forwardedRef, () => buildScrollViewHandle(() => ref.current), []);
+    // Drive the sticky scroll value on the native UI thread (RN attachNativeEvent). No-op on a
+    // host without the native animated module. The JS sticky path stays in effect.
+    useNativeStickyScrollAttach(ref, scrollAnimatedValue, nativeStickyAvailable);
+    // Base style under user style so an explicit user value wins; undefined base (vertical)
+    // passes the user style through unchanged.
+    const scrollStyle = scrollViewBaseStyle ? [scrollViewBaseStyle, style] : style;
+    const scrollProps = { ...outerProps, style: scrollStyle, ref };
+    if (refreshControl === undefined) {
+        return createElement(scrollViewIntrinsic, scrollProps, content);
+    }
+    return createElement(scrollViewIntrinsic, scrollProps, refreshControl, content);
+});
+ScrollView.displayName = 'ScrollView';

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

@@ -0,0 +1,4 @@
+// Base / default ScrollView: re-exports the iOS build. Metro overrides this with
+// scroll-view.ios.ts / .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.
+export * from './index.ios';