@symbiote-native/navigation 1.0.0

package/src/core/navigator-props.ts

@@ -0,0 +1,323 @@
+// Navigator prop types. Per CLAUDE.md <prop_types_split_agnostic_vs_per_adapter>: screen
+// options (title, header styling, transition/presentation) are entirely scalar/color-typed, so
+// they live here as the shared agnostic base every adapter re-exports. The Stack/Screen PUBLIC
+// component props are NOT here - they carry framework children (the screen content) and a
+// framework ref (the navigator handle), so each adapter declares its own flavored type over
+// this base, same split as IPressableProps.
+
+import type { IColorValue, ISymbioteEvent } from '@symbiote-native/engine';
+import type { IImageSourceProp } from '@symbiote-native/components';
+
+export type IStackAnimation =
+  | 'default'
+  | 'flip'
+  | 'simple_push'
+  | 'none'
+  | 'fade'
+  | 'slide_from_right'
+  | 'slide_from_left'
+  | 'slide_from_bottom'
+  | 'fade_from_bottom'
+  | 'ios_from_right'
+  | 'ios_from_left';
+
+export type IStackPresentation =
+  | 'push'
+  | 'modal'
+  | 'transparentModal'
+  | 'fullScreenModal'
+  | 'formSheet'
+  | 'pageSheet'
+  | 'containedModal'
+  | 'containedTransparentModal';
+
+export type IHeaderBackButtonDisplayMode = 'minimal' | 'default' | 'generic';
+
+// react-native-screens' native chrome (the nav bar's blur/vibrancy, and - critically - an
+// embedded headerSearchBarOptions search field's own backdrop) follows this OS-level trait
+// rather than our individual color props; left 'unspecified', it inherits the SYSTEM appearance
+// regardless of app theme, which is why a search bar on an otherwise all-dark screen still shows
+// a stray light backdrop even with every color prop set. 'dark'/'light' force the whole header
+// (and any embedded search bar) into that appearance outright.
+export type IHeaderUserInterfaceStyle = 'unspecified' | 'light' | 'dark';
+
+// A 3-state native boolean (RNSSearchBar's `obscureBackground`/`hideNavigationBar`): the legacy
+// (Paper) architecture can't diff a `WithDefault<boolean>` against "unset" the way Fabric can, so
+// react-native-screens' own codegen spec models these two props as this string enum instead of a
+// plain optional boolean.
+export type IOptionalBooleanNativeProp = 'undefined' | 'false' | 'true';
+
+// RNSScreen's real sheet-detent surface (`formSheet`/`pageSheet` presentation). The compat union
+// mirrors react-native-screens' own ScreenProps['sheetAllowedDetents'] - a plain fraction array,
+// sorted ascending, or one of RNS's named presets; the fold to the native `sheetAllowedDetents:
+// number[]` array happens in screen-options.ts, replicating RNS's own resolveSheetAllowedDetents.
+export type ISheetAllowedDetents = number[] | 'fitToContents' | 'large' | 'medium' | 'all';
+export type ISheetLargestUndimmedDetent = number | 'last' | 'none' | 'all' | 'large' | 'medium';
+export type ISheetInitialDetent = number | 'last';
+
+// A bar-button item's icon: SF Symbol / iOS asset-catalog name, or an image asset. Mirrors RNS's
+// PlatformIconIOS union - the only icon shape RNSScreenStackHeaderConfig's bar-button items
+// accept; there is no Android equivalent in the codegen spec (header bar-button items are iOS-only
+// native surface).
+export type IHeaderBarButtonIcon =
+  | { type: 'sfSymbol'; name: string }
+  | { type: 'xcasset'; name: string }
+  | { type: 'imageSource'; imageSource: IImageSourceProp }
+  | { type: 'templateSource'; templateSource: IImageSourceProp };
+
+export type IHeaderBarButtonItemBadge = {
+  value: string;
+  style?: {
+    color?: IColorValue;
+    backgroundColor?: IColorValue;
+    fontFamily?: string;
+    fontSize?: number;
+    fontWeight?: string;
+  };
+};
+
+type ISharedHeaderBarButtonItem = {
+  index?: number;
+  title?: string;
+  titleStyle?: {
+    fontFamily?: string;
+    fontSize?: number;
+    fontWeight?: string;
+    color?: IColorValue;
+  };
+  icon?: IHeaderBarButtonIcon;
+  variant?: 'plain' | 'done' | 'prominent';
+  tintColor?: IColorValue;
+  disabled?: boolean;
+  width?: number;
+  hidesSharedBackground?: boolean;
+  sharesBackground?: boolean;
+  identifier?: string;
+  badge?: IHeaderBarButtonItemBadge;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+};
+
+export type IHeaderBarButtonItemAction = ISharedHeaderBarButtonItem & {
+  type: 'button';
+  onPress: () => void;
+  selected?: boolean;
+};
+
+export type IHeaderBarButtonMenuAction = {
+  type: 'action';
+  title?: string;
+  subtitle?: string;
+  onPress: () => void;
+  icon?: IHeaderBarButtonIcon;
+  state?: 'on' | 'off' | 'mixed';
+  disabled?: boolean;
+  destructive?: boolean;
+  hidden?: boolean;
+  keepsMenuPresented?: boolean;
+  discoverabilityLabel?: string;
+};
+
+export type IHeaderBarButtonSubmenu = {
+  type: 'submenu';
+  title?: string;
+  icon?: IHeaderBarButtonIcon;
+  items: (IHeaderBarButtonMenuAction | IHeaderBarButtonSubmenu)[];
+  displayInline?: boolean;
+  destructive?: boolean;
+  singleSelection?: boolean;
+  displayAsPalette?: boolean;
+};
+
+export type IHeaderBarButtonItemMenu = ISharedHeaderBarButtonItem & {
+  type: 'menu';
+  menu: {
+    title?: string;
+    items: (IHeaderBarButtonMenuAction | IHeaderBarButtonSubmenu)[];
+    singleSelection?: boolean;
+    displayAsPalette?: boolean;
+  };
+  changesSelectionAsPrimaryAction?: boolean;
+};
+
+export type IHeaderBarButtonItemSpacing = { type: 'spacing'; spacing: number };
+
+export type IHeaderBarButtonItem =
+  IHeaderBarButtonItemAction | IHeaderBarButtonItemMenu | IHeaderBarButtonItemSpacing;
+
+export type ISearchBarAutoCapitalize =
+  'systemDefault' | 'none' | 'words' | 'sentences' | 'characters';
+
+export type ISearchBarPlacement =
+  'automatic' | 'inline' | 'stacked' | 'integrated' | 'integratedButton' | 'integratedCentered';
+
+// RNSSearchBar's full static config surface plus every event callback react-native-screens'
+// own SearchBarProps exposes (types.tsx): onChangeText/onSearchButtonPress carry the current
+// text, the rest are plain notifications. onClose/onOpen are Android-only upstream. The
+// imperative ref (focus/blur/clearText/setText/cancelSearch/toggleCancelButton) is NOT here -
+// it carries a framework ref type, so it is per-adapter (see react/screen.ts's
+// IReactSearchBarOptions), same split as IPressableProps' children/ref fields.
+export type ISearchBarOptions = {
+  placeholder?: string;
+  autoCapitalize?: ISearchBarAutoCapitalize;
+  placement?: ISearchBarPlacement;
+  hideWhenScrolling?: boolean;
+  allowToolbarIntegration?: boolean;
+  obscureBackground?: boolean;
+  hideNavigationBar?: boolean;
+  cancelButtonText?: string;
+  barTintColor?: IColorValue;
+  tintColor?: IColorValue;
+  textColor?: IColorValue;
+  autoFocus?: boolean;
+  disableBackButtonOverride?: boolean;
+  inputType?: string;
+  hintTextColor?: IColorValue;
+  headerIconColor?: IColorValue;
+  shouldShowHintSearchIcon?: boolean;
+  onChangeText?: (text: string) => void;
+  onFocus?: () => void;
+  onBlur?: () => void;
+  onCancelButtonPress?: () => void;
+  onSearchButtonPress?: (text: string) => void;
+  // Android only, per react-native-screens' own SearchBarProps comment.
+  onClose?: () => void;
+  onOpen?: () => void;
+};
+
+export type IScreenOrientation =
+  | 'default'
+  | 'all'
+  | 'portrait'
+  | 'portrait_up'
+  | 'portrait_down'
+  | 'landscape'
+  | 'landscape_left'
+  | 'landscape_right';
+
+// The agnostic per-screen options surface: header title/appearance, transition tuning, sheet
+// detents (formSheet/pageSheet), header bar-button items, the search bar, and the
+// translucent/status-bar family. The gamma-line stack host remains deferred - see packages/
+// navigation's README for the explicit split. `headerSearchBarOptions` folds through
+// resolveSearchBarView/resolveSearchBarProps into a SEPARATE RNSSearchBar leaf, not into this
+// record's own native view - see render-stack.ts.
+export interface IScreenOptions {
+  title?: string;
+  headerShown?: boolean;
+  headerTitleColor?: IColorValue;
+  headerStyle?: { backgroundColor?: IColorValue };
+  headerTintColor?: IColorValue;
+  headerBackTitle?: string;
+  headerBackButtonDisplayMode?: IHeaderBackButtonDisplayMode;
+  headerLargeTitle?: boolean;
+  // react-native-screens tracks the large-title (scroll-edge) appearance SEPARATELY from the
+  // compact/collapsed one - headerStyle.backgroundColor only colors the latter. Left unset with
+  // headerLargeTitle: true, the expanded state falls back to the system default (white), which
+  // reads as a stray white band against a dark theme. Naming mirrors @react-navigation/
+  // native-stack's own headerLargeStyle for the same prop.
+  headerLargeStyle?: { backgroundColor?: IColorValue };
+  headerUserInterfaceStyle?: IHeaderUserInterfaceStyle;
+  headerTranslucent?: boolean;
+  headerLeftBarButtonItems?: IHeaderBarButtonItem[];
+  headerRightBarButtonItems?: IHeaderBarButtonItem[];
+  headerSearchBarOptions?: ISearchBarOptions;
+  gestureEnabled?: boolean;
+  stackAnimation?: IStackAnimation;
+  stackPresentation?: IStackPresentation;
+  transitionDuration?: number;
+  sheetAllowedDetents?: ISheetAllowedDetents;
+  sheetLargestUndimmedDetentIndex?: ISheetLargestUndimmedDetent;
+  sheetInitialDetentIndex?: ISheetInitialDetent;
+  sheetGrabberVisible?: boolean;
+  sheetCornerRadius?: number;
+  sheetExpandsWhenScrolledToEdge?: boolean;
+  sheetElevation?: number;
+  sheetShouldOverflowTopInset?: boolean;
+  sheetDefaultResizeAnimationEnabled?: boolean;
+  statusBarStyle?: 'inverted' | 'auto' | 'light' | 'dark';
+  statusBarHidden?: boolean;
+  statusBarAnimation?: 'none' | 'fade' | 'slide';
+  screenOrientation?: IScreenOrientation;
+}
+
+// The per-platform piece the render needs, matching ISliderPlatform's shape: a default header
+// tint the host platform normally applies natively, kept explicit here so the render stays
+// platform-invariant (no Platform.OS read in core).
+export type INavigatorPlatform = {
+  defaultHeaderBackTitleVisible: boolean;
+};
+
+// Pre-resolved inputs the RNSScreen native render paints from. Only fields the fold actually
+// computes are explicit (screenId, activityState, the resolved options); everything else - the
+// native lifecycle/back-button event handlers - rides in `passthrough`, same convention as
+// ISliderViewProps.
+export type IScreenViewProps = {
+  screenId: string;
+  activityState: number;
+  gestureEnabled?: boolean;
+  stackAnimation?: IStackAnimation;
+  stackPresentation?: IStackPresentation;
+  transitionDuration?: number;
+  sheetAllowedDetents?: number[];
+  sheetLargestUndimmedDetent?: number;
+  sheetInitialDetent?: number;
+  sheetGrabberVisible?: boolean;
+  sheetCornerRadius?: number;
+  sheetExpandsWhenScrolledToEdge?: boolean;
+  sheetElevation?: number;
+  sheetShouldOverflowTopInset?: boolean;
+  sheetDefaultResizeAnimationEnabled?: boolean;
+  statusBarStyle?: 'inverted' | 'auto' | 'light' | 'dark';
+  statusBarHidden?: boolean;
+  statusBarAnimation?: 'none' | 'fade' | 'slide';
+  screenOrientation?: IScreenOrientation;
+  passthrough: Record<string, unknown>;
+};
+
+export type IHeaderConfigViewProps = {
+  title?: string;
+  hidden: boolean;
+  backTitle?: string;
+  backTitleVisible: boolean;
+  backButtonDisplayMode?: IHeaderBackButtonDisplayMode;
+  largeTitle?: boolean;
+  translucent?: boolean;
+  color?: IColorValue;
+  titleColor?: IColorValue;
+  backgroundColor?: IColorValue;
+  largeTitleBackgroundColor?: IColorValue;
+  userInterfaceStyle?: IHeaderUserInterfaceStyle;
+  // Already native-shaped (buttonId/menuId-tagged, colors run through processColor) - the fold
+  // that builds these lives in header-bar-buttons.ts, mirroring RNS's own prepareHeaderBarButtonItems.
+  headerLeftBarButtonItems?: unknown[];
+  headerRightBarButtonItems?: unknown[];
+  onPressHeaderBarButtonItem?: (event: ISymbioteEvent) => void;
+  onPressHeaderBarButtonMenuItem?: (event: ISymbioteEvent) => void;
+  passthrough: Record<string, unknown>;
+};
+
+export type IStackViewProps = {
+  passthrough: Record<string, unknown>;
+};
+
+// Pre-resolved inputs the RNSSearchBar native leaf paints from, mirroring IScreenViewProps'
+// shape: derived from ISearchBarOptions since every static config field is identical - only the
+// two boolean fields the native prop processor needs to see resolved (obscureBackground/
+// hideNavigationBar) and the event callbacks (which ride in `passthrough`, adapter-supplied,
+// instead of being called directly here) differ.
+export type ISearchBarViewProps = Omit<
+  ISearchBarOptions,
+  | 'obscureBackground'
+  | 'hideNavigationBar'
+  | 'onChangeText'
+  | 'onFocus'
+  | 'onBlur'
+  | 'onCancelButtonPress'
+  | 'onSearchButtonPress'
+  | 'onClose'
+  | 'onOpen'
+> & {
+  obscureBackground?: IOptionalBooleanNativeProp;
+  hideNavigationBar?: IOptionalBooleanNativeProp;
+  passthrough: Record<string, unknown>;
+};

package/src/core/navigator-state/index.ts

@@ -0,0 +1,112 @@
+// Navigator: the logic half (framework-agnostic, zero render). A pure reducer over a route
+// stack - push/pop/popToTop/popTo/replace - mirroring what @react-navigation/native-stack keeps
+// in its router, minus the React-specific action-creator/linking machinery. Route identity
+// (`key`) is generated by the CALLER (the adapter, via React's useId or an equivalent) - the
+// reducer never invents identity itself, so it stays a pure (state, action) => state function.
+
+import { SCREEN_ACTIVITY_STATE_FOCUSED, SCREEN_ACTIVITY_STATE_INACTIVE } from '../constants';
+import { mergeParams } from '../guards';
+
+export type IRoute<TParams = undefined> = Readonly<{
+  key: string;
+  name: string;
+  params: TParams;
+}>;
+
+type IRouteEntry = IRoute<unknown>;
+
+export type INavigatorState = Readonly<{
+  routes: readonly IRouteEntry[];
+}>;
+
+export type INavigatorAction =
+  | { type: 'push'; route: IRouteEntry }
+  | { type: 'pop'; count?: number }
+  | { type: 'popToTop' }
+  | { type: 'popTo'; key: string }
+  | { type: 'replace'; route: IRouteEntry }
+  | { type: 'setParams'; key?: string; params: unknown }
+  | { type: 'reset'; state: INavigatorState };
+
+export function createInitialNavigatorState(initialRoute: IRouteEntry): INavigatorState {
+  return { routes: [initialRoute] };
+}
+
+// The stack never pops its last route - mirrors the library refusing to pop the initial screen;
+// the caller (e.g. a hardware back handler) decides what a pop-at-root means for the host app.
+export function navigatorReducer(
+  state: INavigatorState,
+  action: INavigatorAction,
+): INavigatorState {
+  switch (action.type) {
+    case 'push':
+      return { routes: [...state.routes, action.route] };
+
+    case 'pop': {
+      if (state.routes.length <= 1) return state;
+      const count = action.count ?? 1;
+      const nextLength = Math.max(1, state.routes.length - count);
+      return { routes: state.routes.slice(0, nextLength) };
+    }
+
+    case 'popToTop':
+      return state.routes.length <= 1 ? state : { routes: state.routes.slice(0, 1) };
+
+    case 'popTo': {
+      const index = state.routes.findIndex(route => route.key === action.key);
+      if (index === -1) return state;
+      return { routes: state.routes.slice(0, index + 1) };
+    }
+
+    case 'replace': {
+      if (state.routes.length === 0) return { routes: [action.route] };
+      return { routes: [...state.routes.slice(0, -1), action.route] };
+    }
+
+    // Mirrors @react-navigation's CommonActions.setParams: merges onto the route matched by
+    // `key`, defaulting to the focused (top-of-stack) route when omitted - same shape as its
+    // `source`-defaults-to-focused-route behavior, minus the cross-navigator target routing this
+    // single-navigator reducer has no need for.
+    case 'setParams': {
+      const targetKey = action.key ?? state.routes[state.routes.length - 1]?.key;
+      if (targetKey === undefined) return state;
+      const index = state.routes.findIndex(route => route.key === targetKey);
+      if (index === -1) return state;
+      const target = state.routes[index];
+      const nextRoute: IRouteEntry = {
+        ...target,
+        params: mergeParams(target.params, action.params),
+      };
+      return {
+        routes: [...state.routes.slice(0, index), nextRoute, ...state.routes.slice(index + 1)],
+      };
+    }
+
+    // Mirrors @react-navigation's CommonActions.reset / BaseRouter's RESET handler: the payload
+    // state replaces the current one verbatim, no merge - full rehydration (e.g. restoring a
+    // persisted stack) is just a reset with the deserialized state as the payload.
+    case 'reset':
+      return action.state;
+
+    default:
+      return state;
+  }
+}
+
+// Mirrors @react-navigation/native-stack's actual algorithm (NativeStackView.native.tsx:
+// `activityState={isInactive ? 0 : 2}`, where isInactive = index > state.index) - NOT a
+// three-way top/one-below/rest split. A route index beyond the focused one only exists for a
+// preloaded-but-not-yet-navigated-to screen, a feature this reducer doesn't implement, so the
+// focused index is always routesLength - 1 (the last route) and every currently-mounted route is
+// FOCUSED. This is required, not just simpler: react-native-screens' native RNSScreen.mm asserts
+// an already-mounted NativeStack screen's activityState can never decrease via a plain prop
+// update ("activityState can only progress in NativeStack") - since no mounted route's index ever
+// exceeds routesLength - 1, this formula never produces a decrease across a push or pop.
+export function computeActivityState(index: number, routesLength: number): number {
+  const focusedIndex = routesLength - 1;
+  return index > focusedIndex ? SCREEN_ACTIVITY_STATE_INACTIVE : SCREEN_ACTIVITY_STATE_FOCUSED;
+}
+
+export function isTopRoute(index: number, routesLength: number): boolean {
+  return index === routesLength - 1;
+}

package/src/core/navigator-state/navigator-state.test.ts

@@ -0,0 +1,80 @@
+// Co-located unit test (ADR 0025) for the pure route-stack reducer, covering setParams and reset
+// (the react-navigation StackRouter parity pieces) alongside the existing action shapes they sit
+// next to. Push/pop/popToTop/popTo/replace are exercised end-to-end through the React lifecycle
+// in stack.test.tsx already - this file targets navigatorReducer directly, framework-free.
+
+import { describe, expect, it } from 'vitest';
+import { navigatorReducer } from './index';
+import type { INavigatorState } from './index';
+
+const HOME = { key: 'home-1', name: 'Home', params: { tab: 'feed' } };
+const DETAILS = { key: 'details-1', name: 'Details', params: { id: 1 } };
+
+function twoRouteState(): INavigatorState {
+  return { routes: [HOME, DETAILS] };
+}
+
+describe('navigatorReducer — setParams', () => {
+  it('merges params onto the focused (top) route when no key is given', () => {
+    const next = navigatorReducer(twoRouteState(), { type: 'setParams', params: { id: 2 } });
+    expect(next.routes).toEqual([HOME, { ...DETAILS, params: { id: 2 } }]);
+  });
+
+  it('merges params onto the route matched by key, not the top route', () => {
+    const next = navigatorReducer(twoRouteState(), {
+      type: 'setParams',
+      key: 'home-1',
+      params: { tab: 'search' },
+    });
+    expect(next.routes).toEqual([{ ...HOME, params: { tab: 'search' } }, DETAILS]);
+  });
+
+  it('shallow-merges, keeping sibling fields the new params omit', () => {
+    const state: INavigatorState = {
+      routes: [{ key: 'r1', name: 'Home', params: { a: 1, b: 2 } }],
+    };
+    const next = navigatorReducer(state, { type: 'setParams', params: { b: 3 } });
+    expect(next.routes[0].params).toEqual({ a: 1, b: 3 });
+  });
+
+  it('replaces params outright when the existing params are not an object', () => {
+    const state: INavigatorState = { routes: [{ key: 'r1', name: 'Home', params: undefined }] };
+    const next = navigatorReducer(state, { type: 'setParams', params: { a: 1 } });
+    expect(next.routes[0].params).toEqual({ a: 1 });
+  });
+
+  it('leaves state untouched when no route matches the given key', () => {
+    const state = twoRouteState();
+    const next = navigatorReducer(state, { type: 'setParams', key: 'missing', params: { id: 9 } });
+    expect(next).toBe(state);
+  });
+
+  it('does not change route position or identity', () => {
+    const next = navigatorReducer(twoRouteState(), {
+      type: 'setParams',
+      key: 'home-1',
+      params: { tab: 'search' },
+    });
+    expect(next.routes).toHaveLength(2);
+    expect(next.routes[0].key).toBe('home-1');
+    expect(next.routes[1]).toBe(DETAILS);
+  });
+});
+
+describe('navigatorReducer — reset', () => {
+  it('replaces the whole state verbatim, mirroring CommonActions.reset', () => {
+    const nextState: INavigatorState = {
+      routes: [{ key: 'settings-1', name: 'Settings', params: undefined }],
+    };
+    const next = navigatorReducer(twoRouteState(), { type: 'reset', state: nextState });
+    expect(next).toBe(nextState);
+  });
+
+  it('supports rehydrating a persisted multi-route state', () => {
+    const persisted: INavigatorState = {
+      routes: [HOME, DETAILS, { key: 'r3', name: 'Extra', params: undefined }],
+    };
+    const next = navigatorReducer({ routes: [HOME] }, { type: 'reset', state: persisted });
+    expect(next.routes).toHaveLength(3);
+  });
+});

package/src/core/render-drawer.ts

@@ -0,0 +1,123 @@
+// Drawer: the render half (framework-agnostic). Like render-stack.ts's screen content, both the
+// drawer panel's content (renderDrawerContent) and the wrapped screen content are arbitrary
+// framework subtrees the adapter owns - so, mirroring render-modal.ts's container-slot precedent,
+// renderDrawer hands back one root Descriptor whose structural children are EMPTY placeholder
+// nodes (`content` / `overlay?` / `panel`) that the adapter fills with real framework children.
+// Paint order (and therefore which slot is present) is drawerType-dependent, so `drawerChildOrder`
+// is exported alongside renderDrawer as the single source of truth the adapter zips its own
+// children against - no adapter re-derives the ordering itself.
+//
+// All positioning here is STATIC (position/top/bottom/side/width) - the animated slide transform
+// and overlay opacity are NOT baked into this Descriptor. They are computed once per drawerType
+// via drawer-options.ts's resolveDrawerGeometry() and then driven per-frame by the adapter's own
+// Animated value (Animated.View), because "how to animate a style" is a framework-lifecycle
+// concern (React: Animated.View; a future Vue adapter: a reactive style binding) - see
+// CLAUDE.md <adapters_stay_thin>.
+
+import { el, type IDescriptor } from '@symbiote-native/components';
+import type { IStyleProp, IViewStyle } from '@symbiote-native/engine';
+import {
+  isDrawerOverlayVisible,
+  resolveDrawerPosition,
+  resolveDrawerType,
+  resolveDrawerWidth,
+  type IDrawerOptions,
+} from './drawer-options';
+
+export type IDrawerSlot = 'content' | 'overlay' | 'panel';
+
+// front: content, overlay (dims it), panel (paints on top, last-sibling-on-top).
+// back: panel (stationary, behind), content (slides away to reveal it) - no overlay. Both are
+// absolutely positioned, so sibling order here only decides z-stacking, not screen side.
+// slide: panel, overlay, content (both panel and content animate; content stays visually on top).
+// permanent: NOT absolutely positioned (an ordinary flexDirection:'row' sidebar), so sibling
+// order IS the left-to-right screen position - it must follow drawerPosition.
+export function drawerChildOrder(options: IDrawerOptions): readonly IDrawerSlot[] {
+  const type = resolveDrawerType(options);
+  switch (type) {
+    case 'back':
+      return ['panel', 'content'];
+    case 'slide':
+      return ['panel', 'overlay', 'content'];
+    case 'permanent':
+      return resolveDrawerPosition(options) === 'left'
+        ? ['panel', 'content']
+        : ['content', 'panel'];
+    case 'front':
+    default:
+      return ['content', 'overlay', 'panel'];
+  }
+}
+
+export type IDrawerViewProps = {
+  overlayColor?: string;
+  drawerStyle?: IStyleProp<IViewStyle>;
+  contentPassthrough: Record<string, unknown>;
+  overlayPassthrough: Record<string, unknown>;
+  panelPassthrough: Record<string, unknown>;
+};
+
+const ROOT_STYLE: Readonly<IViewStyle> = { flex: 1 };
+const CONTENT_STYLE: Readonly<IViewStyle> = { flex: 1 };
+// Fabric paints later siblings on top; position:absolute + inset:0 is enough for the overlay
+// (its own sibling order, not zIndex, decides whether it sits above the content).
+const OVERLAY_BASE_STYLE: Readonly<IViewStyle> = {
+  position: 'absolute',
+  top: 0,
+  left: 0,
+  right: 0,
+  bottom: 0,
+};
+
+const DRAWER_PANEL_DEFAULT_BACKGROUND_COLOR = 'white';
+
+function panelBaseStyle(options: IDrawerOptions): IViewStyle {
+  const type = resolveDrawerType(options);
+  const width = resolveDrawerWidth(options);
+  const side = resolveDrawerPosition(options);
+  if (type === 'permanent') {
+    // A sidebar: an ordinary flex child, no absolute positioning, no translate needed.
+    return { width, backgroundColor: DRAWER_PANEL_DEFAULT_BACKGROUND_COLOR };
+  }
+  return {
+    position: 'absolute',
+    top: 0,
+    bottom: 0,
+    width,
+    backgroundColor: DRAWER_PANEL_DEFAULT_BACKGROUND_COLOR,
+    [side]: 0,
+  };
+}
+
+export function renderDrawer(view: IDrawerViewProps, options: IDrawerOptions): IDescriptor {
+  const type = resolveDrawerType(options);
+  const content = el('symbiote-view', { ...view.contentPassthrough, style: CONTENT_STYLE }, []);
+  const panel = el(
+    'symbiote-view',
+    { ...view.panelPassthrough, style: [panelBaseStyle(options), view.drawerStyle] },
+    [],
+  );
+
+  const slots: Partial<Record<IDrawerSlot, IDescriptor>> = { content, panel };
+  if (isDrawerOverlayVisible(options)) {
+    slots.overlay = el(
+      'symbiote-view',
+      {
+        ...view.overlayPassthrough,
+        style: [OVERLAY_BASE_STYLE, { backgroundColor: view.overlayColor }],
+      },
+      [],
+    );
+  }
+
+  const children = drawerChildOrder(options).reduce<IDescriptor[]>((acc, slot) => {
+    const descriptor = slots[slot];
+    if (descriptor !== undefined) acc.push(descriptor);
+    return acc;
+  }, []);
+
+  const rootStyle: IViewStyle =
+    type === 'permanent' ? { ...ROOT_STYLE, flexDirection: 'row' } : ROOT_STYLE;
+
+  return el('symbiote-view', { style: rootStyle }, children);
+}