@symbiote-native/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 A. Prokopenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# @symbiote-native/react
+
+The **React adapter** for [SymbioteJS](../../README.md) — drive real native iOS/Android views from
+React, with React Native's own renderer never in the path. It is a `react-reconciler` host config
+in **mutation mode** (`appendChild` / `insertBefore` / `removeChild` → the engine's four-call
+mutation API); `@symbiote-native/engine` does the clone-on-write commit into Fabric.
+
+This is the **reference adapter**: the known-good driver used to validate the native pipe and the
+commit engine before any other framework lands, so a break in Vue/Svelte/Solid isolates to *that*
+adapter, not the core.
+
+<div align="center">
+
+![React driving real native iOS views through SymbioteJS](../../assets/react-demo.gif)
+
+</div>
+
+> New to SymbioteJS? The [root README](../../README.md) has the architecture and the one fact it
+> rests on — React is just *one client* of `nativeFabricUIManager`.
+
+---
+
+## Use it
+
+The app is ordinary React — it imports primitives from `@symbiote-native/react`, not `react-native`:
+
+```jsx
+import { useState } from 'react';
+import { View, Text, Pressable } from '@symbiote-native/react';
+
+export default function App() {
+  const [count, setCount] = useState(0);
+  return (
+    <View style={{ padding: 24 }}>
+      <Text>Taps: {count}</Text>
+      <Pressable onPress={() => setCount((c) => c + 1)}>
+        <Text>Tap me</Text>
+      </Pressable>
+    </View>
+  );
+}
+```
+
+The native entry registers a low-level *runnable* instead of a React component: RN's Fabric host
+calls it with the surface's `rootTag`, and the renderer takes over from there — `nativeFabric-
+UIManager` is driven directly, RN's own renderer never runs.
+
+```js
+// index.js
+import { AppRegistry, processColor } from 'react-native';
+import { createElement } from 'react';
+import { mount } from '@symbiote-native/react';
+import { setColorProcessor } from '@symbiote-native/engine';
+import App from './App';
+import { name as appName } from './app.json';
+
+// Colors reach Fabric as platform ints; let the engine use RN's own converter.
+setColorProcessor(processColor);
+
+// registerRunnable (not registerComponent): RN stores a raw mount callback and never renders
+// it with its own renderer.
+AppRegistry.registerRunnable(appName, ({ rootTag }) => {
+  mount(rootTag, createElement(App));
+});
+```
+
+The runnable example is [`examples/react`](../../examples/react) — a stock RN 0.86 app whose full
+canary ([`App.tsx`](../../examples/react/App.tsx)) exercises every block of the surface below.
+
+---
+
+## Surface — verified on device, iOS + Android
+
+Every interaction commits through `@symbiote-native/engine` into Fabric, with RN's renderer never in the
+path (R1 + R2 + R3 — decision record 0009):
+
+- **Primitives** — `View` · `Text` · `Image` · `ImageBackground` · `ScrollView` · `TextInput` ·
+  `Pressable` · `Touchable*` · `Button` · `Switch` · `Modal` · `ActivityIndicator` ·
+  `SafeAreaView` · `RefreshControl` · `FlatList` · `SectionList` · `VirtualizedList`.
+- **Runtime modules** — `Platform` · `StyleSheet` (incl. `hairlineWidth`) · `Dimensions` ·
+  `Appearance` · `PixelRatio` · `AppState`, plus imperative `Alert` · `ActionSheetIOS` · `Share` ·
+  `Linking` · `Vibration` · `Keyboard` · `StatusBar` — each reaching its real native module on the
+  bridgeless host.
+- **`Animated`, both drivers** — JS *and* native driver side by side (`timing` · `spring` · `loop` ·
+  `interpolate` · `ValueXY` · tracking · `diffClamp`). Native offload is proven by jamming the JS
+  thread 1.5 s: the native-driven animations keep moving, the JS-driven one stalls (ADR 0016 · 0017).
+- **Third-party native views** — `@react-native-community/slider` used straight from the package
+  with zero SymbioteJS metadata; the engine derives its events and prop processors from the library's
+  own ViewConfig at runtime — the "install the package, use its component" path.
+- **Gestures & events** — the responder lifecycle (grant/move/release/terminate, LCA-scoped
+  re-negotiation), two-phase capture→bubble delivery, `Pressable` press-retention, `Touchable*`
+  delays, and `PanResponder` — all in the engine.
+- **Accessibility** — the `accessibility*` / ARIA prop layer (roles, labels, states, focus,
+  grouping) verified against the platform a11y tree on both platforms.
+- **Modern styling** — RN's JS style processors (`boxShadow` · `filter` · `transform` ·
+  `transformOrigin` · `aspectRatio` · `fontVariant`) and color resolution run in the engine, so
+  CSS-style props commit correctly on **both** platforms — not just iOS tolerating a raw string
+  while Android's strict native converter crashes on it.
+
+### Android
+
+The same canary runs on an Android emulator through the same `@symbiote-native/engine` core. Two signals
+RN ties to a view host SymbioteJS bypasses — or never shipped on Android — are re-supplied by a small
+`@symbiote-native/android` native package (`KeyboardObserver` host shim; `SettingsManager` →
+`SharedPreferences`). `Platform` and the component-name map are Metro-split per OS (`.ios` /
+`.android`), so there is no `Platform.OS` runtime branch. iOS stays the reference surface (more
+real-hardware time, wider prop-edge coverage); `ActionSheetIOS` is iOS-only by design, and
+`Vibration` needs the app to declare the `VIBRATE` permission (RN's standard requirement, owned by
+the future scaffolder).
+
+---
+
+## Run it
+
+[`examples/react`](../../examples/react) is a stock React Native 0.86 app. Requires Node ≥ 22 and
+the [RN environment setup](https://reactnative.dev/docs/set-up-your-environment) (Xcode, CocoaPods):
+
+```bash
+cd examples/react
+npm install
+bundle install                 # first time only — installs CocoaPods itself
+bundle exec pod install        # (cd ios && pod install) — fetch native pods
+
+# terminal 1 — Metro. DEBUG=1 turns on diagnostic logs (Babel inlines it).
+DEBUG=1 npm start --reset-cache
+
+# terminal 2 — build + launch
+npm run ios                    # iOS simulator (the reference surface)
+npm run android                # Android emulator (manual-links @symbiote-native/android)
+```
+
+Press <kbd>R</kbd> in the simulator to reload. Because `DEBUG` is Babel-inlined into the bundle,
+changing it requires restarting Metro with `--reset-cache`.
+
+---
+
+## Test it
+
+```bash
+pnpm test                      # vitest, from the workspace root — headless, fake Fabric slot
+
+cd examples/react
+npm run e2e:build:ios          # build the app for Detox (once per native change)
+npm run e2e:test:ios           # run the canary journeys on the iOS simulator
+# …or the android equivalents: e2e:build:android / e2e:test:android
+```
+
+Why these come for free — a SymbioteJS app is a stock RN app underneath, so RN's whole testing
+ecosystem applies unchanged. See [Testing](../../README.md#testing).

package/build/components/activity-indicator/index.android.d.ts

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

package/build/components/activity-indicator/index.android.js

@@ -0,0 +1,13 @@
+// ActivityIndicator on Android: AndroidProgressBar needs `styleAttr` (it drives the
+// ProgressBar's setStyle(); without it the view throws "setStyle() not called") and
+// `indeterminate: true`, and its default color is the theme (null), per RN's
+// ActivityIndicator.js android branch ({styleAttr:'Normal', indeterminate:true}). Metro
+// picks this on an Android host; no Platform.OS read. See ADR 0020.
+// device-verify-pending: prop names mirror RN's AndroidProgressBar, proven on a real
+// host by the absence of the "setStyle() not called" red box.
+import { createActivityIndicator } from './shared';
+export const ActivityIndicator = createActivityIndicator({
+    // RN: `color = Platform.OS === 'ios' ? GRAY : null`; Android lets the theme color it.
+    defaultColor: null,
+    nativeExtras: { styleAttr: 'Normal', indeterminate: true },
+});

package/build/components/activity-indicator/index.d.ts

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

package/build/components/activity-indicator/index.ios.d.ts

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

package/build/components/activity-indicator/index.ios.js

@@ -0,0 +1,10 @@
+// ActivityIndicator on iOS: RCTActivityIndicatorView takes the size enum + a GRAY
+// default color and no extra native props. Also the base (activity-indicator.ts
+// re-exports it) for headless / web. See ADR 0020.
+import { createActivityIndicator } from './shared';
+// RN's iOS default spinner color (Libraries/.../ActivityIndicator.js GRAY).
+const IOS_DEFAULT_COLOR = '#999999';
+export const ActivityIndicator = createActivityIndicator({
+    defaultColor: IOS_DEFAULT_COLOR,
+    nativeExtras: {},
+});

package/build/components/activity-indicator/index.js

@@ -0,0 +1,4 @@
+// Base / default ActivityIndicator: re-exports the iOS build. Metro overrides this with
+// activity-indicator.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';

package/build/components/activity-indicator/shared.d.ts

@@ -0,0 +1,7 @@
+import type { FC } from 'react';
+import type { IActivityIndicatorPlatform, IActivityIndicatorProps as IActivityIndicatorBaseProps } from '@symbiote-native/components';
+export type { IActivityIndicatorPlatform } from '@symbiote-native/components';
+export type IActivityIndicatorProps = IActivityIndicatorBaseProps & {
+    className?: string;
+};
+export declare function createActivityIndicator(platform: IActivityIndicatorPlatform): FC<IActivityIndicatorProps>;

package/build/components/activity-indicator/shared.js

@@ -0,0 +1,20 @@
+// ActivityIndicator is the React lifecycle half. The render (size translation, wrapper +
+// spinner, color omission) lives framework-agnostic in @symbiote-native/components; here the
+// adapter only resolves props (accessibility, defaults), calls the render fn, and bridges
+// the Descriptor to a React element. No state, no effects: this component is render-only.
+//
+// The per-platform bits (iOS GRAY default + no extras; Android theme/null + styleAttr +
+// indeterminate) are supplied by the .ios/.android files via `IActivityIndicatorPlatform`.
+import { renderActivityIndicator, resolveAccessibilityProps } from '@symbiote-native/components';
+import { descriptorToReact } from '../../descriptor-to-react';
+export function createActivityIndicator(platform) {
+    return rawProps => {
+        // The wrapper is a raw symbiote-view, not the View FC, so it never runs
+        // resolveAccessibilityProps itself, so fold aria/role here, then forward the resolved
+        // accessibility* surface (plus testID / onLayout) onto the wrapper via `passthrough`.
+        const props = resolveAccessibilityProps(rawProps);
+        const { animating = true, color, hidesWhenStopped = true, size = 'small', style, ...passthrough } = props;
+        const descriptor = renderActivityIndicator({ animating, color, hidesWhenStopped, size, style, passthrough }, platform);
+        return descriptorToReact(descriptor);
+    };
+}

package/build/components/button.d.ts

@@ -0,0 +1,6 @@
+import { type FC } from 'react';
+import type { IButtonProps as IButtonBaseProps } from '@symbiote-native/components';
+export type IButtonProps = IButtonBaseProps & {
+    className?: string;
+};
+export declare const Button: FC<IButtonProps>;

package/build/components/button.js

@@ -0,0 +1,42 @@
+// Button is the minimal cross-platform button, rendered in its iOS shape per RN's Button.js: a
+// TouchableOpacity wrapping a Text. The base text style, the role constant, and the color fold
+// (caller color tints the label; disabled greys it) are shared in @symbiote-native/components/view; here
+// React only composes its TouchableOpacity + Text and forwards the native-only props.
+import { createElement } from 'react';
+import { Text } from '../components';
+import { TouchableOpacity } from './touchable';
+import { BUTTON_ACCESSIBILITY_ROLE, resolveButtonTextStyle } from '@symbiote-native/components';
+export const Button = props => {
+    const { title, onPress, color, disabled, touchSoundDisabled, testID, hasTVPreferredFocus, nextFocusDown, nextFocusForward, nextFocusLeft, nextFocusRight, nextFocusUp, ...accessibilityRest } = props;
+    const textStyle = resolveButtonTextStyle(color, disabled);
+    // The pressable / native View props TouchableOpacity does not type but forwards to Fabric
+    // (testID + TV-focus). Carried as a plain record (the pass-through idiom Image uses) so
+    // excess-property typing does not reject the native-only keys. TV-focus is inert on a phone.
+    const nativeForward = { testID };
+    if (hasTVPreferredFocus !== undefined)
+        nativeForward.hasTVPreferredFocus = hasTVPreferredFocus;
+    if (nextFocusDown !== undefined)
+        nativeForward.nextFocusDown = nextFocusDown;
+    if (nextFocusForward !== undefined)
+        nativeForward.nextFocusForward = nextFocusForward;
+    if (nextFocusLeft !== undefined)
+        nativeForward.nextFocusLeft = nextFocusLeft;
+    if (nextFocusRight !== undefined)
+        nativeForward.nextFocusRight = nextFocusRight;
+    if (nextFocusUp !== undefined)
+        nativeForward.nextFocusUp = nextFocusUp;
+    // RN's Button sets role=button, is accessible, and propagates the disabled accessibility state.
+    // The caller's accessibility props pass through, but Button's fixed role / accessible /
+    // disabled-state win, applied after the spread. touchSoundDisabled maps to the pressable's
+    // android_disableSound.
+    return createElement(TouchableOpacity, {
+        ...accessibilityRest,
+        ...nativeForward,
+        onPress,
+        disabled,
+        android_disableSound: touchSoundDisabled,
+        accessibilityRole: BUTTON_ACCESSIBILITY_ROLE,
+        accessible: true,
+        accessibilityState: { disabled },
+    }, createElement(Text, { style: textStyle }, title));
+};

package/build/components/drawer-layout-android/index.android.d.ts

@@ -0,0 +1,3 @@
+import type { IDrawerLayoutAndroidHandle, IDrawerLayoutAndroidProps } from './shared';
+export type { IDrawerPosition, IDrawerLockMode, IKeyboardDismissMode, IDrawerState, IDrawerSlideEvent, IDrawerLayoutAndroidProps, IDrawerLayoutAndroidHandle, } from './shared';
+export declare const DrawerLayoutAndroid: import("react").ForwardRefExoticComponent<IDrawerLayoutAndroidProps & import("react").RefAttributes<IDrawerLayoutAndroidHandle>>;

package/build/components/drawer-layout-android/index.android.js

@@ -0,0 +1,93 @@
+// DrawerLayoutAndroid: the real Android build. AndroidDrawerLayout is an ordinary
+// Fabric host node: it lives in the SAME childSet and commits through the SAME
+// completeRoot as the rest of the tree, exactly like Modal/Switch. There is no
+// per-library glue; shared derives the view's events/processors from its ViewConfig,
+// so we render the RAW Fabric name `AndroidDrawerLayout` (the derive-by-default path:
+// any non-`symbiote-*` createElement type flows through untouched).
+//
+// Behavior mirrors RN's DrawerLayoutAndroid.android.js: the navigation view (from
+// `renderNavigationView()`) and the main content are wrapped in two container Views,
+// and, critically, the child order RN commits is [mainSubview, drawerSubview]: the
+// content wrapper FIRST, the navigation wrapper SECOND (android render:
+// {childrenWrapper}{drawerViewWrapper}). The navigation wrapper is absolutely
+// positioned, drawerWidth-wide, and gated by pointerEvents so it stays untouchable
+// until opened. `openDrawer`/`closeDrawer` are imperative, reached through a ref, and
+// dispatched as the `openDrawer`/`closeDrawer` view commands against the host node,
+// mirroring Switch's dispatchViewCommand path (Commands.openDrawer/closeDrawer in
+// AndroidDrawerLayoutNativeComponent).
+//
+// The platform-invariant math — the host prop bag + the content/navigation wrapper styles, the
+// slide/state event normalization, the imperative open/close handle, and the view/command NAMES —
+// lives in @symbiote/components, shared verbatim with the Vue adapter; here React supplies only the
+// lifecycle: a ref holds the host node, a `drawerOpened` state gates the navigation wrapper's
+// pointerEvents, and useImperativeHandle wires the imperative handle.
+//
+// Metro picks this file on an Android host; off Android the base index.ts
+// renders the fallback. No Platform.OS read; the filename is the selector (ADR 0019).
+// device-verify-pending: the `AndroidDrawerLayout` name + the openDrawer/closeDrawer
+// commands are RN-source-confirmed, not yet exercised on a real Android host.
+import { createElement, forwardRef, useCallback, useImperativeHandle, useRef, useState, } from 'react';
+import { dlog } from '@symbiote/engine';
+import { buildDrawerHandle, DEFAULT_DRAWER_POSITION, offsetFromSlide, resolveAccessibilityProps, resolveDrawerLayout, stateFromChange, } from '@symbiote/components';
+import { View } from '../../components';
+export const DrawerLayoutAndroid = forwardRef((props, ref) => {
+    const { drawerWidth, drawerPosition, drawerLockMode, keyboardDismissMode, drawerBackgroundColor, statusBarBackgroundColor, onDrawerOpen, onDrawerClose, onDrawerSlide, onDrawerStateChanged, renderNavigationView, style, children, ...passthrough } = props;
+    const node = useRef(null);
+    // RN tracks drawerOpened to gate the navigation view's pointerEvents (android
+    // _onDrawerOpen/_onDrawerClose setState). Closed -> 'none' so the off-screen drawer
+    // never intercepts touches; open -> 'auto' (folded in by resolveDrawerLayout).
+    const [drawerOpened, setDrawerOpened] = useState(false);
+    // The imperative handle reads the node through a LAZY getter (() => node.current), not the node
+    // captured once: it is null until the element commits. The React twin of Vue's
+    // expose(buildDrawerHandle(…)).
+    useImperativeHandle(ref, () => buildDrawerHandle(() => node.current), []);
+    const handleDrawerOpen = useCallback(() => {
+        dlog('DrawerLayoutAndroid onDrawerOpen');
+        setDrawerOpened(true);
+        onDrawerOpen?.();
+    }, [onDrawerOpen]);
+    const handleDrawerClose = useCallback(() => {
+        dlog('DrawerLayoutAndroid onDrawerClose');
+        setDrawerOpened(false);
+        onDrawerClose?.();
+    }, [onDrawerClose]);
+    const handleDrawerSlide = useCallback((event) => {
+        onDrawerSlide?.({ offset: offsetFromSlide(event) });
+    }, [onDrawerSlide]);
+    const handleDrawerStateChanged = useCallback((event) => {
+        onDrawerStateChanged?.(stateFromChange(event));
+    }, [onDrawerStateChanged]);
+    const resolved = resolveDrawerLayout({
+        drawerWidth,
+        drawerPosition,
+        drawerLockMode,
+        keyboardDismissMode,
+        drawerBackgroundColor,
+        statusBarBackgroundColor,
+        drawerOpened,
+        style,
+        // The drawer renders a raw host node (not the View FC), so unlike View-backed components nothing
+        // else resolves aria-*/role — fold them into accessibility* here before passing through.
+        passthrough: resolveAccessibilityProps(passthrough),
+    });
+    // RN's mainSubview: content wrapped in an absolute box.
+    const contentWrapper = createElement(View, { style: resolved.contentWrapperStyle }, children);
+    // RN's drawerSubview: the navigation view wrapped, drawerWidth-wide, painted with
+    // drawerBackgroundColor, untouchable until opened.
+    const navigationWrapper = createElement(View, {
+        style: resolved.navigationWrapperStyle,
+        pointerEvents: resolved.navigationPointerEvents,
+    }, renderNavigationView());
+    dlog(`DrawerLayoutAndroid render position=${drawerPosition ?? DEFAULT_DRAWER_POSITION} ` +
+        `width=${String(drawerWidth)} opened=${drawerOpened}`);
+    // Child order matches RN exactly: content FIRST, navigation SECOND
+    // (android render emits {childrenWrapper}{drawerViewWrapper}).
+    return createElement(resolved.viewName, {
+        ...resolved.hostProps,
+        ref: node,
+        onDrawerOpen: handleDrawerOpen,
+        onDrawerClose: handleDrawerClose,
+        onDrawerSlide: handleDrawerSlide,
+        onDrawerStateChanged: handleDrawerStateChanged,
+    }, contentWrapper, navigationWrapper);
+});

package/build/components/drawer-layout-android/index.d.ts

@@ -0,0 +1,3 @@
+import type { IDrawerLayoutAndroidHandle, IDrawerLayoutAndroidProps } from './shared';
+export type { IDrawerPosition, IDrawerLockMode, IKeyboardDismissMode, IDrawerState, IDrawerSlideEvent, IDrawerLayoutAndroidProps, IDrawerLayoutAndroidHandle, } from './shared';
+export declare const DrawerLayoutAndroid: import("react").ForwardRefExoticComponent<IDrawerLayoutAndroidProps & import("react").RefAttributes<IDrawerLayoutAndroidHandle>>;

package/build/components/drawer-layout-android/index.js

@@ -0,0 +1,19 @@
+// DrawerLayoutAndroid: base / off-Android fallback. AndroidDrawerLayout is Android-
+// only, so everywhere except an Android host (where Metro picks
+// drawer-layout-android.android.ts) we render the content in a plain container and drop
+// the navigation view (RN's DrawerLayoutAndroidFallback shape). The imperative
+// open/close are silent no-ops; there is no drawer to drive. The filename is the
+// selector; no Platform.OS read. The barrel imports './drawer-layout-android', which
+// resolves here under tsc/tsx and to the .android file under Metro. See ADR 0019.
+import { createElement, forwardRef, useImperativeHandle } from 'react';
+import { dlog } from '@symbiote/engine';
+import { View } from '../../components';
+export const DrawerLayoutAndroid = forwardRef((props, ref) => {
+    const { style, children } = props;
+    useImperativeHandle(ref, () => ({
+        openDrawer: () => dlog('DrawerLayoutAndroid.openDrawer no-op: off Android'),
+        closeDrawer: () => dlog('DrawerLayoutAndroid.closeDrawer no-op: off Android'),
+    }), []);
+    dlog('DrawerLayoutAndroid fallback: off-Android host, rendering content only');
+    return createElement(View, { style }, children);
+});

package/build/components/drawer-layout-android/shared.d.ts

@@ -0,0 +1,19 @@
+import type { ReactNode } from 'react';
+import type { IAccessibilityProps, IAriaProps, IDrawerLockMode, IDrawerPosition, IDrawerSlideEvent, IDrawerState, IKeyboardDismissMode } from '@symbiote/components';
+import type { IStyleProp, IViewStyle } from '../../utils/styles';
+export type { IDrawerPosition, IDrawerLockMode, IKeyboardDismissMode, IDrawerState, IDrawerSlideEvent, IDrawerLayoutAndroidHandle, } from '@symbiote/components';
+export interface IDrawerLayoutAndroidProps extends IAccessibilityProps, IAriaProps {
+    drawerWidth?: number;
+    drawerPosition?: IDrawerPosition;
+    drawerLockMode?: IDrawerLockMode;
+    keyboardDismissMode?: IKeyboardDismissMode;
+    drawerBackgroundColor?: string;
+    statusBarBackgroundColor?: string;
+    onDrawerOpen?: () => void;
+    onDrawerClose?: () => void;
+    onDrawerSlide?: (event: IDrawerSlideEvent) => void;
+    onDrawerStateChanged?: (state: IDrawerState) => void;
+    renderNavigationView: () => ReactNode;
+    style?: IStyleProp<IViewStyle>;
+    children?: ReactNode;
+}

package/build/components/drawer-layout-android/shared.js

@@ -0,0 +1,7 @@
+// Shared types for the React DrawerLayoutAndroid: the same Props/Handle contract the real Android
+// build (index.android.ts) and the off-Android fallback (index.ts) both implement. The
+// platform-agnostic enums + the imperative handle live in @symbiote/components (the single source of
+// truth, shared verbatim with the Vue adapter); this file adds only the React-facing prop surface and
+// re-exports the agnostic types so the barrel and both builds keep importing them from one local path.
+// Per ADR 0019 the filename selects the build; no Platform.OS read anywhere.
+export {};

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

@@ -0,0 +1,73 @@
+import { type ComponentType, type ReactElement, type ReactNode, type Ref } from 'react';
+import { type ISymbioteEvent } from '@symbiote-native/engine';
+import { type ISeparators, type ISeparatorProps, type IViewabilityConfig, type IViewabilityConfigCallbackPair, type IViewableItemsChangedInfo, type IVirtualizedListHandle } from '../virtualized-list';
+import type { IAccessibilityProps, IAriaProps } from '@symbiote-native/components';
+import type { IStyleProp, IViewStyle } from '../../utils/styles';
+type IRenderItem<ItemT> = (info: {
+    item: ItemT;
+    index: number;
+    separators: ISeparators;
+}) => ReactNode;
+export type IFlatListHandle = IVirtualizedListHandle;
+export interface IFlatListProps<ItemT> extends IAccessibilityProps, IAriaProps {
+    data: readonly ItemT[];
+    renderItem: IRenderItem<ItemT>;
+    keyExtractor?: (item: ItemT, index: number) => string;
+    getItemLayout?: (data: unknown, index: number) => {
+        length: number;
+        offset: number;
+        index: number;
+    };
+    numColumns?: number;
+    columnWrapperStyle?: IStyleProp<IViewStyle> | string;
+    ItemSeparatorComponent?: ComponentType<ISeparatorProps<ItemT>>;
+    ListHeaderComponent?: ComponentType<Record<string, never>> | ReactElement;
+    ListFooterComponent?: ComponentType<Record<string, never>> | ReactElement;
+    ListEmptyComponent?: ComponentType<Record<string, never>> | ReactElement;
+    horizontal?: boolean;
+    inverted?: boolean;
+    extraData?: unknown;
+    onEndReached?: (info: {
+        distanceFromEnd: number;
+    }) => void;
+    onEndReachedThreshold?: number;
+    onStartReached?: (info: {
+        distanceFromStart: number;
+    }) => void;
+    onStartReachedThreshold?: number;
+    onRefresh?: () => void;
+    refreshing?: boolean | null;
+    progressViewOffset?: number;
+    onViewableItemsChanged?: (info: IViewableItemsChangedInfo<ItemT>) => void;
+    viewabilityConfig?: IViewabilityConfig;
+    viewabilityConfigCallbackPairs?: IViewabilityConfigCallbackPair<ItemT>[];
+    onScrollToIndexFailed?: (info: {
+        index: number;
+        highestMeasuredFrameIndex: number;
+        averageItemLength: number;
+    }) => void;
+    initialNumToRender?: number;
+    initialScrollIndex?: number;
+    maxToRenderPerBatch?: number;
+    updateCellsBatchingPeriod?: number;
+    windowSize?: number;
+    maintainVisibleContentPosition?: {
+        minIndexForVisible: number;
+        autoscrollToTopThreshold?: number;
+    };
+    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';
+    style?: IStyleProp<IViewStyle>;
+    contentContainerStyle?: IStyleProp<IViewStyle>;
+    className?: string;
+}
+export declare function FlatList<ItemT>(props: IFlatListProps<ItemT> & {
+    ref?: Ref<IFlatListHandle>;
+}): ReactElement;
+export {};

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

@@ -0,0 +1,86 @@
+// FlatList: the convenience surface over VirtualizedList. It takes a plain `data` array and
+// derives getItem/getItemCount, so callers never touch the VirtualizedList data-access protocol.
+// `numColumns` packs that many items into each row (a horizontal sub-View), so the virtualized
+// stream is rows, not items (RN's FlatList). All windowing, viewability, batching, and imperative
+// scrolling are inherited from VirtualizedList; the data shaping and the row/viewability/separator
+// transforms are shared from @symbiote-native/components. This file only adapts to React's lifecycle
+// (element creation + ref threading).
+import { createElement, } from 'react';
+import { dlog, resolveClassName } from '@symbiote-native/engine';
+import { SINGLE_COLUMN, chunkIntoRows, expandRowViewability, firstItemOfRow, lastItemOfRow, rowKeyExtractor, } from '@symbiote-native/components';
+import { VirtualizedList, } from '../virtualized-list';
+export function FlatList(props) {
+    const { ref, data, renderItem, keyExtractor, numColumns = SINGLE_COLUMN, columnWrapperStyle, 
+    // onViewableItemsChanged/viewability are typed against ItemT here; in the multi-column path
+    // the underlying stream is IRow<ItemT>, so they are dropped from `rest` and pulled out.
+    onViewableItemsChanged, viewabilityConfigCallbackPairs, 
+    // ItemSeparatorComponent is typed on ItemT; the multi-column stream is IRow<ItemT>, so it is
+    // wrapped there to unwrap rows back to items, exactly like viewability above.
+    ItemSeparatorComponent, ...rest } = props;
+    dlog(`FlatList over ${data.length} items, ${numColumns} column(s)`);
+    if (numColumns <= SINGLE_COLUMN) {
+        return createElement((VirtualizedList), {
+            ref,
+            data,
+            getItem: (_source, index) => data[index],
+            getItemCount: () => data.length,
+            renderItem,
+            keyExtractor,
+            onViewableItemsChanged,
+            viewabilityConfigCallbackPairs,
+            ItemSeparatorComponent,
+            ...rest,
+        });
+    }
+    // Multi-column: the virtualized stream is rows. Each cell renders its items side by side in a
+    // flex-row View so windowing accounts for whole rows.
+    const rows = chunkIntoRows(data, numColumns);
+    const resolvedColumnWrapperStyle = typeof columnWrapperStyle === 'string'
+        ? resolveClassName(columnWrapperStyle)
+        : columnWrapperStyle;
+    const rowStyle = [{ flexDirection: 'row' }, resolvedColumnWrapperStyle];
+    const renderRow = (info) => {
+        const cells = info.item.items.map((item, column) => {
+            const index = info.item.startIndex + column;
+            const key = keyExtractor ? keyExtractor(item, index) : String(index);
+            // The row IS the virtualized cell, so every item in it shares the row's separators handle
+            // (the divider sits between rows, not columns), like RN's multi-column FlatList.
+            return createElement('symbiote-view', { key, style: { flex: 1 } }, renderItem({ item, index, separators: info.separators }));
+        });
+        return createElement('symbiote-view', { style: rowStyle }, ...cells);
+    };
+    // Viewability over rows expands back to per-item tokens so the caller sees item-level
+    // visibility, not row-level (shared expandRowViewability).
+    const rowOnViewableItemsChanged = onViewableItemsChanged !== undefined
+        ? (rowInfo) => {
+            onViewableItemsChanged(expandRowViewability(rowInfo, keyExtractor));
+        }
+        : undefined;
+    const rowViewabilityPairs = viewabilityConfigCallbackPairs?.map(pair => ({
+        viewabilityConfig: pair.viewabilityConfig,
+        onViewableItemsChanged: (rowInfo) => {
+            pair.onViewableItemsChanged(expandRowViewability(rowInfo, keyExtractor));
+        },
+    }));
+    // The divider between rows shows real items (last of the row above, first of the row below), so
+    // the user's separator, typed on ItemT, sees items rather than the IRow wrapper.
+    const rowSeparatorComponent = ItemSeparatorComponent === undefined
+        ? undefined
+        : (rowProps) => createElement(ItemSeparatorComponent, {
+            ...rowProps,
+            leadingItem: lastItemOfRow(rowProps.leadingItem),
+            trailingItem: firstItemOfRow(rowProps.trailingItem),
+        });
+    return createElement((VirtualizedList), {
+        ref,
+        data: rows,
+        getItem: (_source, index) => rows[index],
+        getItemCount: () => rows.length,
+        renderItem: renderRow,
+        keyExtractor: rowKeyExtractor,
+        onViewableItemsChanged: rowOnViewableItemsChanged,
+        viewabilityConfigCallbackPairs: rowViewabilityPairs,
+        ItemSeparatorComponent: rowSeparatorComponent,
+        ...rest,
+    });
+}

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

@@ -0,0 +1,9 @@
+import { type FC } from 'react';
+import { type IImageStatics, type IImageProps as IImageBaseProps } from '@symbiote-native/components';
+export type IImageProps = IImageBaseProps & {
+    className?: string;
+};
+export type IImageWithStatics = FC<IImageProps> & IImageStatics;
+export declare const Image: IImageWithStatics;
+export { setImageSourceResolver } from '@symbiote-native/components';
+export type { IImageSource, IImageSourceProp, IResizeMode, IImageSize, IImageCacheStatus, } from '@symbiote-native/components';