@symbiote-native/components 0.1.0

package/build/state/virtualized-list.js

@@ -0,0 +1,306 @@
+// VirtualizedList logic: the framework-agnostic windowing engine. Every adapter
+// (React hooks, Vue reactivity) drives the SAME math from here, so a windowing /
+// viewability / edge-reached bug is fixed once for all adapters
+// (<adapters_reach_full_feature_parity>). The adapter supplies only its lifecycle
+// (refs/state/effects), the imperative handle wiring, and the per-cell element
+// creation (createElement / h) — never the geometry.
+//
+// What lives here:
+//   - the RN-matching defaults + sentinels,
+//   - the nativeEvent payload readers (scroll offset / layout length),
+//   - offset table + window computation + batch throttling,
+//   - viewability classification, the viewable-set diff, and the minimumViewTime fold,
+//   - the edge-reached (onEndReached / onStartReached) distance + threshold compute,
+//   - the assembled child PLAN (spacer extents, in-window cell keys, sticky child
+//     positions) the adapter maps onto its host elements,
+//   - the shared data + imperative-handle types.
+//
+// What stays in the adapter (genuinely framework-bound): the cell CONTENT is the
+// framework's own children (renderItem -> ReactNode / VNode), so there is no
+// Descriptor render fn for a list — the shared layer for lists is this STATE/logic
+// module, not a view/render-*.ts. See core/components/.docs-note-lists.md.
+// Defaults match RN. windowSize is measured in viewport-lengths (21 => ten screens
+// of buffer on each side of the visible region). onEndReachedThreshold is a multiple
+// of the visible length (RN's onEndReachedThresholdOrDefault returns `?? 2`).
+// initialNumToRender bounds the first paint before any layout is measured.
+// maxToRenderPerBatch / batching period mirror RN's incremental fill defaults.
+export const DEFAULT_WINDOW_SIZE = 21;
+export const DEFAULT_INITIAL_NUM_TO_RENDER = 10;
+export const DEFAULT_END_REACHED_THRESHOLD = 2;
+export const DEFAULT_MAX_TO_RENDER_PER_BATCH = 10;
+export const DEFAULT_UPDATE_CELLS_BATCHING_PERIOD = 50;
+export const DEFAULT_VIEW_AREA_COVERAGE_PERCENT_THRESHOLD = 0;
+// onStartReachedThreshold default, mirroring RN's onStartReachedThresholdOrDefault.
+export const DEFAULT_START_REACHED_THRESHOLD = 2;
+export const FIRST_INDEX = 0;
+export const EMPTY_OFFSET = 0;
+export const NO_INDEX = -1;
+export const FULLY_VISIBLE_PERCENT = 100;
+// RN floors sub-pixel end distances to 0 so a debounced scroll that stops a fraction
+// of a pixel from the bottom still counts as "reached the end" (RN VirtualizedList.js).
+export const ON_EDGE_REACHED_EPSILON = 0.001;
+// Sentinel for "onEndReached / onStartReached has not fired for any content length
+// yet". Real content lengths are >= 0, so -1 can never collide with one.
+export const NO_CONTENT_LENGTH_SENT = -1;
+// Inversion flips the content container along the scroll axis; each cell re-flips so
+// its own content stays upright (RN does the same with a scale(-1) transform).
+export const INVERTED_Y_STYLE = { transform: [{ scaleY: -1 }] };
+export const INVERTED_X_STYLE = { transform: [{ scaleX: -1 }] };
+// nativeEvent payload guards. The payloads arrive as `unknown` off the wire, so they
+// are narrowed with runtime checks rather than cast.
+function readNumber(source, key) {
+    const value = source[key];
+    return typeof value === 'number' ? value : undefined;
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? { ...value } : undefined;
+}
+// onScroll -> the offset along the scroll axis. Vertical reads contentOffset.y,
+// horizontal reads contentOffset.x.
+export function readScrollOffset(event, horizontal) {
+    const native = asRecord(event.nativeEvent);
+    if (native === undefined)
+        return undefined;
+    const offset = asRecord(native.contentOffset);
+    if (offset === undefined)
+        return undefined;
+    return readNumber(offset, horizontal ? 'x' : 'y');
+}
+// onLayout -> the cross-section length of the box along the scroll axis.
+export function readLayoutLength(event, horizontal) {
+    const native = asRecord(event.nativeEvent);
+    if (native === undefined)
+        return undefined;
+    const layout = asRecord(native.layout);
+    if (layout === undefined)
+        return undefined;
+    return readNumber(layout, horizontal ? 'width' : 'height');
+}
+// Resolve every cell offset/length from the cache (or getItemLayout), filling gaps with
+// the running average so an unmeasured tail still has a plausible total. Returns the
+// per-index offset table plus the grand total extent.
+export function buildOffsets(count, measured, fixedLayout, averageLength) {
+    const offsets = new Array(count);
+    const lengths = new Array(count);
+    let running = EMPTY_OFFSET;
+    for (let index = FIRST_INDEX; index < count; index += 1) {
+        offsets[index] = running;
+        let length;
+        if (fixedLayout !== undefined) {
+            length = fixedLayout(index).length;
+        }
+        else {
+            length = measured.get(index) ?? averageLength;
+        }
+        lengths[index] = length;
+        running += length;
+    }
+    return { offsets, lengths, total: running };
+}
+// Pick the resident window: every index whose box overlaps
+// [offset - buffer, offset + viewport + buffer]. The buffer is (windowSize - 1) / 2
+// viewport-lengths on each side, matching RN's symmetric leading/trailing overscan.
+export function computeWindow(count, offsets, lengths, scrollOffset, viewportLength, windowSize, initialNumToRender) {
+    if (count === FIRST_INDEX)
+        return { first: FIRST_INDEX, last: NO_INDEX };
+    // Before the viewport is known, paint a bounded prefix.
+    if (viewportLength <= EMPTY_OFFSET) {
+        return { first: FIRST_INDEX, last: Math.min(count, initialNumToRender) - 1 };
+    }
+    const overscan = ((windowSize - 1) / 2) * viewportLength;
+    const windowTop = scrollOffset - overscan;
+    const windowBottom = scrollOffset + viewportLength + overscan;
+    let first = FIRST_INDEX;
+    while (first < count - 1 && offsets[first] + lengths[first] <= windowTop) {
+        first += 1;
+    }
+    let last = first;
+    while (last < count - 1 && offsets[last] + lengths[last] < windowBottom) {
+        last += 1;
+    }
+    return { first, last };
+}
+// Clamp a freshly computed window against the previously-committed one so at most
+// maxToRenderPerBatch new cells are added on each side per tick (RN's incremental fill).
+// The window grows toward the target over successive batch ticks rather than snapping in
+// one render: cheaper first paint on a big jump.
+export function throttleWindow(target, previous, maxToRenderPerBatch) {
+    if (previous.last < previous.first)
+        return target;
+    const first = Math.max(target.first, previous.first - maxToRenderPerBatch);
+    const last = Math.min(target.last, previous.last + maxToRenderPerBatch);
+    // Never present an empty window when the target is non-empty.
+    if (last < first)
+        return target;
+    return { first, last };
+}
+// Fraction (0..100) of a cell's box that lies inside the viewport.
+export function visiblePercent(cellOffset, cellLength, scrollOffset, viewportLength) {
+    if (cellLength <= EMPTY_OFFSET)
+        return EMPTY_OFFSET;
+    const top = Math.max(cellOffset, scrollOffset);
+    const bottom = Math.min(cellOffset + cellLength, scrollOffset + viewportLength);
+    const visible = Math.max(EMPTY_OFFSET, bottom - top);
+    return (visible / cellLength) * FULLY_VISIBLE_PERCENT;
+}
+// A cell is viewable when its visible fraction clears the configured threshold.
+// itemVisiblePercentThreshold compares against the cell's own size;
+// viewAreaCoveragePercentThreshold compares against the viewport. The former wins when
+// set, else the latter, matching RN's precedence.
+export function isCellViewable(percent, config) {
+    const itemThreshold = config.itemVisiblePercentThreshold;
+    if (itemThreshold !== undefined)
+        return percent >= itemThreshold;
+    const areaThreshold = config.viewAreaCoveragePercentThreshold ?? DEFAULT_VIEW_AREA_COVERAGE_PERCENT_THRESHOLD;
+    return percent > areaThreshold || percent >= FULLY_VISIBLE_PERCENT;
+}
+// Resolve an index to a pixel offset, optionally biasing where in the viewport the item
+// lands (viewPosition 0=top, 1=bottom, 0.5=center) and an absolute viewOffset nudge,
+// mirroring RN's scrollToIndex options.
+export function offsetForIndex(index, viewPosition, viewOffset, count, offsets, lengths, viewportLength) {
+    const clamped = Math.max(FIRST_INDEX, Math.min(index, count - 1));
+    const cellOffset = offsets[clamped] ?? EMPTY_OFFSET;
+    const cellLength = lengths[clamped] ?? EMPTY_OFFSET;
+    const positioned = cellOffset - viewPosition * (viewportLength - cellLength);
+    return Math.max(EMPTY_OFFSET, positioned - viewOffset);
+}
+// Running average of known cell lengths, used to size not-yet-measured cells and the
+// trailing spacer so the total is plausible before full measurement.
+export function averageMeasuredLength(measured) {
+    if (measured.size === EMPTY_OFFSET)
+        return EMPTY_OFFSET;
+    let sum = EMPTY_OFFSET;
+    for (const length of measured.values())
+        sum += length;
+    return sum / measured.size;
+}
+// The largest index whose length has actually been measured (RN
+// ListMetricsAggregator.getHighestMeasuredCellIndex). NO_INDEX when nothing is measured.
+export function highestMeasuredIndex(measured) {
+    let highest = NO_INDEX;
+    for (const index of measured.keys()) {
+        if (index > highest)
+            highest = index;
+    }
+    return highest;
+}
+// onEndReached distance + threshold test (RN _maybeCallOnEdgeReached). The adapter still
+// gates on "the last cell is actually rendered" and dedups by content length via its own
+// ref; this returns only the pure geometry.
+export function computeEndReached(total, scrollOffset, viewportLength, thresholdMultiplier) {
+    let distanceFromEnd = total - (scrollOffset + viewportLength);
+    if (distanceFromEnd < ON_EDGE_REACHED_EPSILON)
+        distanceFromEnd = EMPTY_OFFSET;
+    const threshold = thresholdMultiplier * viewportLength;
+    return { distanceFromEnd, withinThreshold: distanceFromEnd <= threshold };
+}
+// onStartReached twin of computeEndReached. distanceFromStart is just the scroll offset.
+export function computeStartReached(scrollOffset, viewportLength, thresholdMultiplier) {
+    let distanceFromStart = scrollOffset;
+    if (distanceFromStart < ON_EDGE_REACHED_EPSILON)
+        distanceFromStart = EMPTY_OFFSET;
+    const threshold = thresholdMultiplier * viewportLength;
+    return { distanceFromStart, withinThreshold: distanceFromStart <= threshold };
+}
+// Fold the single-config and pairs forms into one list (RN supports either, not both).
+export function buildViewabilityPairs(onViewableItemsChanged, viewabilityConfig, pairs) {
+    const result = [];
+    if (onViewableItemsChanged !== undefined) {
+        result.push({ viewabilityConfig: viewabilityConfig ?? {}, onViewableItemsChanged });
+    }
+    if (pairs !== undefined)
+        result.push(...pairs);
+    return result;
+}
+// Classify every rendered cell against the viewability configs. A cell counts as
+// viewable if ANY config says so (RN's broadest classification); a config with
+// waitForInteraction classifies nothing until the first scroll has happened.
+export function computeViewableSet(params) {
+    const tokens = [];
+    const map = new Map();
+    for (let index = params.first; index <= params.last && index < params.count; index += 1) {
+        const percent = visiblePercent(params.offsets[index], params.lengths[index], params.scrollOffset, params.viewportLength);
+        const item = params.getItem(params.data, index);
+        const key = params.keyExtractor ? params.keyExtractor(item, index) : String(index);
+        let anyViewable = false;
+        for (const pair of params.pairs) {
+            if (pair.viewabilityConfig.waitForInteraction === true && !params.hasInteracted) {
+                continue;
+            }
+            if (isCellViewable(percent, pair.viewabilityConfig)) {
+                anyViewable = true;
+                break;
+            }
+        }
+        if (anyViewable) {
+            const token = { item, key, index, isViewable: true };
+            map.set(key, token);
+            tokens.push(token);
+        }
+    }
+    return { tokens, map };
+}
+// The `changed` delta between two viewable sets: newly viewable (true) and newly hidden
+// (false). hasChanged is false when the viewable KEY set is identical, so the adapter can
+// skip firing (RN dedups the same way). Hidden tokens come straight from the previous map,
+// so no rescan of all N items.
+export function diffViewable(previous, current, currentTokens) {
+    let hasChanged = previous.size !== current.size;
+    if (!hasChanged) {
+        for (const key of current.keys()) {
+            if (!previous.has(key)) {
+                hasChanged = true;
+                break;
+            }
+        }
+    }
+    if (!hasChanged)
+        return { changed: [], hasChanged: false };
+    const changed = [];
+    for (const token of currentTokens) {
+        if (!previous.has(token.key))
+            changed.push(token);
+    }
+    for (const [key, token] of previous) {
+        if (!current.has(key))
+            changed.push({ ...token, isViewable: false });
+    }
+    return { changed, hasChanged: true };
+}
+// The largest configured minimumViewTime across all pairs (RN gates the unified pass on
+// the largest value, since we fold all pairs into one classification).
+export function maxMinimumViewTime(pairs) {
+    let max = EMPTY_OFFSET;
+    for (const pair of pairs) {
+        const configured = pair.viewabilityConfig.minimumViewTime;
+        if (configured !== undefined && configured > max)
+            max = configured;
+    }
+    return max;
+}
+// Compute the windowed child PLAN: the two spacer extents, the in-window cells (index +
+// key), and the sticky child positions. The adapter walks this plan and creates the host
+// elements (createElement / h) plus the framework cell content. This is the shared half of
+// the render; only the element creation and the user's renderItem stay per-adapter.
+export function buildListPlan(params) {
+    const cells = [];
+    const leadingExtent = params.first > FIRST_INDEX ? params.offsets[params.first] : EMPTY_OFFSET;
+    const renderedExtent = params.last >= params.first
+        ? params.offsets[params.last] + params.lengths[params.last] - params.offsets[params.first]
+        : EMPTY_OFFSET;
+    const trailingExtent = params.total - leadingExtent - renderedExtent;
+    const stickyChildPositions = [];
+    // The header (when present) is child 0; the leading spacer (when non-empty) is the next
+    // child. Each cell is one child; a separator after it (when ItemSeparatorComponent is set
+    // and this is not the last cell) is another.
+    let childPosition = (params.hasHeader ? 1 : 0) + (leadingExtent > EMPTY_OFFSET ? 1 : 0);
+    for (let index = params.first; index <= params.last; index += 1) {
+        cells.push({ index, key: params.keyFor(index) });
+        if (params.stickyIndices?.has(index) === true)
+            stickyChildPositions.push(childPosition);
+        childPosition += 1;
+        if (params.hasSeparators && index < params.last)
+            childPosition += 1;
+    }
+    return { leadingExtent, trailingExtent, cells, stickyChildPositions };
+}

package/build/view/render-activity-indicator.d.ts

@@ -0,0 +1,25 @@
+import type { IStyleProp, IViewStyle, ISymbioteEvent } from '@symbiote-native/engine';
+import type { IDescriptor } from '../descriptor';
+import type { IAccessibilityProps, IAriaProps } from '../accessibility-props';
+export type IActivityIndicatorSize = 'small' | 'large' | number;
+export interface IActivityIndicatorProps extends IAccessibilityProps, IAriaProps {
+    animating?: boolean;
+    color?: string;
+    size?: IActivityIndicatorSize;
+    hidesWhenStopped?: boolean;
+    style?: IStyleProp<IViewStyle>;
+    onLayout?: (event: ISymbioteEvent) => void;
+}
+export type IActivityIndicatorViewProps = {
+    animating: boolean;
+    hidesWhenStopped: boolean;
+    size: IActivityIndicatorSize;
+    color?: string;
+    style?: IStyleProp<IViewStyle>;
+    passthrough: Record<string, unknown>;
+};
+export type IActivityIndicatorPlatform = {
+    defaultColor: string | null;
+    nativeExtras: Readonly<Record<string, unknown>>;
+};
+export declare function renderActivityIndicator(view: IActivityIndicatorViewProps, platform: IActivityIndicatorPlatform): IDescriptor;

package/build/view/render-activity-indicator.js

@@ -0,0 +1,54 @@
+// ActivityIndicator: the render half (framework-agnostic). RN wraps the native spinner
+// in a centering View and translates `size` in JS: 'small'/'large' map to a native size
+// enum AND a fixed box style; a numeric size never reaches native (it sizes the spinner
+// via style only). That translation is platform-invariant and lives here.
+//
+// What IS platform-specific (ADR 0020, prop-level): Android's AndroidProgressBar needs
+// `styleAttr` (which triggers its setStyle(), without it the view throws "setStyle() not
+// called") plus `indeterminate: true`, and its default color is the theme (null), whereas
+// iOS's ActivityIndicatorView takes neither and defaults to GRAY. The adapter's per-host
+// file supplies those bits via `platform`.
+import { dlog } from '@symbiote-native/engine';
+import { el } from '../descriptor';
+// Fixed pixel boxes RN gives the two named sizes (styles.sizeSmall/sizeLarge).
+const SIZE_SMALL_PX = 20;
+const SIZE_LARGE_PX = 36;
+// Centering wrapper RN puts around the spinner (styles.container).
+const CONTAINER_STYLE = {
+    alignItems: 'center',
+    justifyContent: 'center',
+};
+function resolveSize(size) {
+    if (size === 'small') {
+        return { sizeStyle: { width: SIZE_SMALL_PX, height: SIZE_SMALL_PX }, sizeProp: 'small' };
+    }
+    if (size === 'large') {
+        return { sizeStyle: { width: SIZE_LARGE_PX, height: SIZE_LARGE_PX }, sizeProp: 'large' };
+    }
+    return { sizeStyle: { width: size, height: size } };
+}
+export function renderActivityIndicator(view, platform) {
+    const { sizeStyle, sizeProp } = resolveSize(view.size);
+    dlog(sizeProp !== undefined
+        ? `ActivityIndicator size '${sizeProp}' -> native size enum '${sizeProp}'`
+        : `ActivityIndicator size ${String(view.size)} -> style only, native size not set`);
+    const nativeProps = {
+        animating: view.animating,
+        hidesWhenStopped: view.hidesWhenStopped,
+        style: sizeStyle,
+        ...platform.nativeExtras,
+    };
+    // Omit color entirely when neither given nor defaulted (Android's theme default is
+    // null); a null color prop would be rejected by Fabric's color parser.
+    const resolvedColor = view.color ?? platform.defaultColor;
+    if (resolvedColor !== null)
+        nativeProps.color = resolvedColor;
+    if (sizeProp !== undefined)
+        nativeProps.size = sizeProp;
+    dlog('ActivityIndicator -> RCTView(spinner)');
+    const wrapperProps = {
+        ...view.passthrough,
+        style: [CONTAINER_STYLE, view.style],
+    };
+    return el('symbiote-view', wrapperProps, [el('symbiote-activity-indicator', nativeProps)]);
+}

package/build/view/render-button.d.ts

@@ -0,0 +1,19 @@
+import type { ITextStyle, ISymbioteEvent } from '@symbiote-native/engine';
+import type { IAccessibilityProps, IAriaProps } from '../accessibility-props';
+export interface IButtonProps extends IAccessibilityProps, IAriaProps {
+    title: string;
+    onPress?: (event: ISymbioteEvent) => void;
+    color?: string;
+    disabled?: boolean;
+    touchSoundDisabled?: boolean;
+    testID?: string;
+    hasTVPreferredFocus?: boolean;
+    nextFocusDown?: number;
+    nextFocusForward?: number;
+    nextFocusLeft?: number;
+    nextFocusRight?: number;
+    nextFocusUp?: number;
+}
+export declare const BUTTON_ACCESSIBILITY_ROLE = "button";
+export declare const buttonTextStyle: ITextStyle;
+export declare function resolveButtonTextStyle(color: string | undefined, disabled: boolean | undefined): ITextStyle;

package/build/view/render-button.js

@@ -0,0 +1,24 @@
+// Button: the shared render half (framework-agnostic). Rendered in RN's iOS shape (Button.js): a
+// TouchableOpacity wrapping a Text. The pure pieces: the base text style, the role constant, and
+// the color fold (caller color tints the label; disabled greys it) live here so every adapter
+// paints the identical button. The adapter only composes its TouchableOpacity + Text around them.
+const IOS_BUTTON_BLUE = '#007AFF';
+const IOS_DISABLED_GREY = '#cdcdcd';
+// RN's Button is accessibilityRole="button"; the role string is a native accessibility enum value.
+export const BUTTON_ACCESSIBILITY_ROLE = 'button';
+export const buttonTextStyle = {
+    color: IOS_BUTTON_BLUE,
+    textAlign: 'center',
+    padding: 8,
+    fontSize: 18,
+};
+// The label text style with the color folded in: an explicit `color` tints the label (iOS), and
+// `disabled` greys it out (disabled wins over color, matching RN's Button.js).
+export function resolveButtonTextStyle(color, disabled) {
+    const style = { ...buttonTextStyle };
+    if (color !== undefined)
+        style.color = color;
+    if (disabled === true)
+        style.color = IOS_DISABLED_GREY;
+    return style;
+}

package/build/view/render-drawer-layout-android.d.ts

@@ -0,0 +1,23 @@
+import type { IStyleProp, IViewStyle } from '@symbiote/engine';
+import { type IDrawerLockMode, type IDrawerPosition, type IKeyboardDismissMode } from '../state/drawer-layout-android';
+export declare const DRAWER_HOST_STYLE: Readonly<IViewStyle>;
+export declare const DRAWER_MAIN_SUBVIEW_STYLE: Readonly<IViewStyle>;
+export interface IDrawerLayoutResolveInput {
+    drawerWidth?: number;
+    drawerPosition?: IDrawerPosition;
+    drawerLockMode?: IDrawerLockMode;
+    keyboardDismissMode?: IKeyboardDismissMode;
+    drawerBackgroundColor?: string;
+    statusBarBackgroundColor?: string;
+    drawerOpened: boolean;
+    style?: IStyleProp<IViewStyle>;
+    passthrough: Record<string, unknown>;
+}
+export interface IDrawerLayoutResolved {
+    viewName: string;
+    hostProps: Record<string, unknown>;
+    contentWrapperStyle: Readonly<IViewStyle>;
+    navigationWrapperStyle: IViewStyle;
+    navigationPointerEvents: 'auto' | 'none';
+}
+export declare function resolveDrawerLayout(input: IDrawerLayoutResolveInput): IDrawerLayoutResolved;

package/build/view/render-drawer-layout-android.js

@@ -0,0 +1,56 @@
+// DrawerLayoutAndroid: the framework-agnostic view (style/prop) math. AndroidDrawerLayout is an
+// ordinary Fabric host node committing through the same childSet as the rest of the tree (like
+// Modal / Switch): a content wrapper FIRST and a navigation wrapper SECOND, mirroring RN's android
+// render order {childrenWrapper}{drawerViewWrapper}. This builds the host prop bag + the two wrapper
+// styles from the resolved props; the adapter overlays its ref + the wrapped event handlers and
+// supplies the framework children / navigation elements. The logic half (event normalization,
+// imperative handle, constants, types) lives in state/drawer-layout-android.ts.
+import { DEFAULT_DRAWER_BACKGROUND_COLOR, DEFAULT_DRAWER_POSITION, DRAWER_VIEW_NAME, } from '../state/drawer-layout-android';
+// RN styles.base on the host: flex:1 plus the Android drop-shadow that floats the drawer over
+// content (android styles.base { flex:1, elevation:16 }).
+export const DRAWER_HOST_STYLE = {
+    flex: 1,
+    elevation: 16,
+};
+// RN styles.mainSubview: the content wrapper fills the host (absolute, all edges 0).
+export const DRAWER_MAIN_SUBVIEW_STYLE = {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+};
+// RN styles.drawerSubview: the navigation wrapper is absolute and full-height; its width comes from
+// drawerWidth and its background from drawerBackgroundColor (both folded in by resolveDrawerLayout).
+const DRAWER_SUBVIEW_STYLE = {
+    position: 'absolute',
+    top: 0,
+    bottom: 0,
+};
+// Build the AndroidDrawerLayout host prop bag + the two wrapper styles from the resolved props. The
+// adapter overlays its ref + the four wrapped event handlers (onDrawerOpen / Close / Slide /
+// StateChanged) and nests [contentWrapper, navigationWrapper] under the host IN THAT ORDER.
+export function resolveDrawerLayout(input) {
+    const drawerBackgroundColor = input.drawerBackgroundColor ?? DEFAULT_DRAWER_BACKGROUND_COLOR;
+    const hostProps = {
+        ...input.passthrough,
+        drawerWidth: input.drawerWidth,
+        drawerPosition: input.drawerPosition ?? DEFAULT_DRAWER_POSITION,
+        drawerLockMode: input.drawerLockMode,
+        keyboardDismissMode: input.keyboardDismissMode,
+        drawerBackgroundColor,
+        statusBarBackgroundColor: input.statusBarBackgroundColor,
+        style: [DRAWER_HOST_STYLE, input.style],
+    };
+    return {
+        viewName: DRAWER_VIEW_NAME,
+        hostProps,
+        contentWrapperStyle: DRAWER_MAIN_SUBVIEW_STYLE,
+        navigationWrapperStyle: {
+            ...DRAWER_SUBVIEW_STYLE,
+            width: input.drawerWidth,
+            backgroundColor: drawerBackgroundColor,
+        },
+        navigationPointerEvents: input.drawerOpened ? 'auto' : 'none',
+    };
+}

package/build/view/render-image-background.d.ts

@@ -0,0 +1,9 @@
+import { type IStyleProp, type IViewStyle } from '@symbiote-native/engine';
+import { type IDescriptor } from '../descriptor';
+import { type IImageViewProps } from './render-image';
+export type IImageBackgroundViewProps = {
+    style?: IStyleProp<IViewStyle>;
+    imageStyle?: IStyleProp<IViewStyle>;
+    image: IImageViewProps;
+};
+export declare function renderImageBackground(view: IImageBackgroundViewProps): IDescriptor;

package/build/view/render-image-background.js

@@ -0,0 +1,48 @@
+// ImageBackground: the render half (framework-agnostic). Pure JS composition, no native
+// component of its own (mirrors react-native/Libraries/Image/ImageBackground.js): an outer
+// View receives the wrapper `style`; an absolutely-filled Image sits behind it; the user's
+// `children` paint on top (as siblings AFTER the image in the wrapper's child order, injected
+// by the adapter). Shared verbatim across adapters: React and Vue both bridge this Descriptor.
+//
+// The inner Image is positioned absolute-fill and has the wrapper's width/height reapplied:
+// RN's Image overwrites its own width/height from the source's intrinsic size, which would
+// fight the wrapper's explicit dimensions, so we proxy them back onto the Image so it fills
+// the box. `imageStyle` wins last.
+import { dlog, flattenStyle, } from '@symbiote-native/engine';
+import { el } from '../descriptor';
+import { renderImage } from './render-image';
+// The inner Image's positioning: absolute-fill behind the wrapper's children.
+const IMAGE_BACKGROUND_ABSOLUTE_FILL = {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    top: 0,
+    bottom: 0,
+};
+// Read one explicit dimension off the (already-flattened) wrapper style. A dp number or a
+// percentage string is a valid IDimensionValue; anything else (auto / undefined) yields undefined.
+function readDimension(style, key) {
+    const value = Object.hasOwn(style, key) ? Reflect.get(style, key) : undefined;
+    if (typeof value === 'number' || typeof value === 'string')
+        return value;
+    return undefined;
+}
+export function renderImageBackground(view) {
+    // Flatten only to read the wrapper's explicit dimensions; RN copies these onto the Image so
+    // it fills the box rather than collapsing to the source's intrinsic size. `imageStyle` last.
+    const flattenedWrapper = flattenStyle(view.style);
+    const imageMergedStyle = [
+        IMAGE_BACKGROUND_ABSOLUTE_FILL,
+        {
+            width: readDimension(flattenedWrapper, 'width'),
+            height: readDimension(flattenedWrapper, 'height'),
+        },
+        view.imageStyle,
+    ];
+    dlog('ImageBackground -> View(RCTView) > Image(RCTImageView absolute-fill) + children');
+    // The wrapper View holds the inner Image as its only structural child; the adapter appends
+    // the user children after it (so they paint on top).
+    return el('symbiote-view', { style: view.style }, [
+        renderImage({ ...view.image, style: imageMergedStyle }),
+    ]);
+}

package/build/view/render-image.d.ts

@@ -0,0 +1,86 @@
+import { type IStyleProp, type ISymbioteEvent, type IViewStyle } from '@symbiote-native/engine';
+import type { IAccessibilityProps, IAriaProps } from '../accessibility-props';
+import { type IDescriptor } from '../descriptor';
+type IImageEventHandler = (event: ISymbioteEvent) => void;
+export type IResizeMode = 'cover' | 'contain' | 'stretch' | 'repeat' | 'center';
+export type IImageSource = {
+    uri?: string;
+    scale?: number;
+    width?: number;
+    height?: number;
+};
+export type IImageSourceProp = IImageSource | IImageSource[] | number;
+export type IImageCapInsets = {
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+};
+export type IResizeMethod = 'auto' | 'resize' | 'scale' | 'none';
+export type IImageProps = IAccessibilityProps & IAriaProps & {
+    source?: IImageSourceProp;
+    defaultSource?: IImageSourceProp;
+    loadingIndicatorSource?: IImageSourceProp;
+    style?: IStyleProp<IViewStyle>;
+    resizeMode?: IResizeMode;
+    resizeMethod?: IResizeMethod;
+    tintColor?: string;
+    blurRadius?: number;
+    capInsets?: IImageCapInsets;
+    fadeDuration?: number;
+    progressiveRenderingEnabled?: boolean;
+    src?: string;
+    srcSet?: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+    crossOrigin?: 'anonymous' | 'use-credentials';
+    referrerPolicy?: string;
+    onLoadStart?: IImageEventHandler;
+    onLoad?: IImageEventHandler;
+    onLoadEnd?: IImageEventHandler;
+    onError?: IImageEventHandler;
+    onProgress?: IImageEventHandler;
+    onPartialLoad?: IImageEventHandler;
+};
+export declare function setImageSourceResolver(resolve: (source: unknown) => unknown): void;
+export type IImageSize = {
+    width: number;
+    height: number;
+};
+export type IImageCacheStatus = 'memory' | 'disk' | 'disk/memory';
+type ISizeSuccess = (width: number, height: number) => void;
+type ISizeFailure = (error: unknown) => void;
+declare function getSize(uri: string, success?: ISizeSuccess, failure?: ISizeFailure): Promise<IImageSize>;
+declare function getSizeWithHeaders(uri: string, headers: Record<string, string>, success?: ISizeSuccess, failure?: ISizeFailure): Promise<IImageSize>;
+declare function prefetch(uri: string, callback?: (requestId: number) => void): Promise<boolean>;
+declare function abortPrefetch(requestId: number): void;
+declare function queryCache(uris: string[]): Promise<Record<string, IImageCacheStatus>>;
+declare function resolveAssetSource(source: IImageSourceProp): unknown;
+export type IImageStatics = {
+    getSize: typeof getSize;
+    getSizeWithHeaders: typeof getSizeWithHeaders;
+    prefetch: typeof prefetch;
+    abortPrefetch: typeof abortPrefetch;
+    queryCache: typeof queryCache;
+    resolveAssetSource: typeof resolveAssetSource;
+};
+export declare const imageStatics: IImageStatics;
+export type IImageViewProps = {
+    source?: IImageSourceProp;
+    defaultSource?: IImageSourceProp;
+    loadingIndicatorSource?: IImageSourceProp;
+    style?: IStyleProp<IViewStyle>;
+    resizeMode?: IResizeMode;
+    tintColor?: string;
+    src?: string;
+    srcSet?: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+    crossOrigin?: 'anonymous' | 'use-credentials';
+    referrerPolicy?: string;
+    passthrough: Record<string, unknown>;
+};
+export declare function renderImage(view: IImageViewProps): IDescriptor;
+export {};