@symbiote-native/solid 0.0.1 → 1.0.0

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

@@ -0,0 +1,118 @@
+// FlatList — the convenience surface over VirtualizedList. It takes a plain `data` array and
+// derives the getItem/getItemCount access protocol itself, so a caller never writes them, and
+// `numColumns` packs that many items into each row so the virtualized stream is ROWS rather than
+// items (RN's FlatList). Everything else — windowing, spacers, viewability, batching, sticky
+// headers, pull-to-refresh, the imperative scrolls — is inherited from VirtualizedList; the data
+// shaping and the row/viewability/separator transforms come from @symbiote-native/components and
+// are shared verbatim with React, Vue, Svelte and Angular. This file adds Solid's lifecycle and
+// nothing else.
+//
+// TWO SOLID FACTS SHAPE IT (.claude/rules/solid-descriptor-bridge.md):
+//
+// 1. `renderItem` takes an ACCESSOR, matching this adapter's VirtualizedList and diverging from
+//    React's snapshot signature. Solid has no reconciler under the render prop, so a value would
+//    freeze the row at its mount-time item.
+// 2. The columns inside a packed row ride an <Index>, not a <For>. That is the exact MIRROR of
+//    VirtualizedList's choice and for the same reason read the other way round: a cell key moves
+//    between rows as the window slides, so the CELLS are keyed by value; a column is a fixed
+//    positional slot inside its row — column 1 of row 3 is always column 1 of row 3 — so keying it
+//    by value would destroy and rebuild the whole column subtree every time the data array is
+//    replaced with fresh item objects. <Index> keys by position and hands the item down as an
+//    accessor, so only the leaf that reads it re-runs.
+//
+// The imperative handle needs no delegation layer here, unlike Vue's and Svelte's. `ref` is an
+// ordinary prop in the passthrough tail, so it lands on the inner VirtualizedList directly and the
+// caller receives that list's own handle — FlatList's handle IS VirtualizedList's (RN says the
+// same).
+import { Index, Show, createMemo, splitProps, untrack, } from 'solid-js';
+import { SINGLE_COLUMN, chunkIntoRows, expandRowViewability, firstItemOfRow, lastItemOfRow, rowKeyExtractor, } from '@symbiote-native/components';
+import { dlog, resolveClassName, } from '@symbiote-native/engine';
+import { VirtualizedList, } from '../virtualized-list';
+// What FlatList itself consumes or re-shapes. Everything NOT listed here is passthrough and rides
+// down onto the inner list untouched — `ref` among it, which is why no delegate handle is needed.
+const OWN_PROPS = [
+    'data',
+    'numColumns',
+    'columnWrapperStyle',
+    'renderItem',
+    'keyExtractor',
+    'ItemSeparatorComponent',
+    'onViewableItemsChanged',
+    'viewabilityConfigCallbackPairs',
+];
+const ROW_STYLE = { flexDirection: 'row' };
+// Equal weight per column, so `numColumns` columns split the row evenly (RN's own multi-column
+// FlatList). A cell that sized itself would leave ragged columns.
+const COLUMN_STYLE = { flex: 1 };
+export function FlatList(props) {
+    const [, passthrough] = splitProps(props, OWN_PROPS);
+    const columnCount = () => props.numColumns ?? SINGLE_COLUMN;
+    // RN treats anything at or below one column as an ordinary single-column list rather than an
+    // error, and so does adapters/react.
+    const isMultiColumn = () => columnCount() > SINGLE_COLUMN;
+    const rows = createMemo(() => {
+        const columns = columnCount();
+        // Logged from inside the memo, not from the body: a Solid body runs ONCE, so a line emitted
+        // there would report the mount-time shape forever and be actively misleading on a data change.
+        dlog(`Solid FlatList over ${props.data.length} items, ${columns} column(s)`);
+        return columns > SINGLE_COLUMN ? chunkIntoRows(props.data, columns) : [];
+    });
+    // A bare string is a registered class name and has to be resolved here — the row view's style
+    // prop takes objects/arrays, so an unresolved string would silently paint nothing.
+    const rowStyle = createMemo(() => [
+        ROW_STYLE,
+        typeof props.columnWrapperStyle === 'string'
+            ? resolveClassName(props.columnWrapperStyle)
+            : props.columnWrapperStyle,
+    ]);
+    function renderRow(info) {
+        return (<symbiote-view style={rowStyle()}>
+        <Index each={info().item.items}>
+          {(item, column) => {
+                // Called ONCE and untracked, the shape VirtualizedList's own cell build uses: a
+                // tracked call would put every signal renderItem reads into this column's insert
+                // effect and rebuild the subtree instead of updating its leaf.
+                const content = untrack(() => props.renderItem(() => ({
+                    item: item(),
+                    index: info().item.startIndex + column,
+                    // The row IS the virtualized cell, so every column in it shares the row's
+                    // separators handle — the divider sits between rows, not between columns.
+                    separators: info().separators,
+                })));
+                return (<symbiote-view style={COLUMN_STYLE}>{content}</symbiote-view>);
+            }}
+        </Index>
+      </symbiote-view>);
+    }
+    // The divider between rows shows real items (last of the row above, first of the row below), so
+    // the caller's separator, typed on ItemT, never sees the IRow wrapper.
+    const rowSeparatorComponent = createMemo(() => {
+        const Separator = props.ItemSeparatorComponent;
+        if (Separator === undefined)
+            return undefined;
+        return (rowProps) => (<Separator {...rowProps} leadingItem={lastItemOfRow(rowProps.leadingItem)} trailingItem={firstItemOfRow(rowProps.trailingItem)}/>);
+    });
+    // Viewability over rows expands back to per-item tokens, so the caller sees item-level
+    // visibility rather than row-level (shared expandRowViewability).
+    const rowViewability = createMemo(() => {
+        const onChanged = props.onViewableItemsChanged;
+        if (onChanged === undefined)
+            return undefined;
+        return (rowInfo) => onChanged(expandRowViewability(rowInfo, props.keyExtractor));
+    });
+    const rowViewabilityPairs = createMemo(() => props.viewabilityConfigCallbackPairs?.map(pair => ({
+        viewabilityConfig: pair.viewabilityConfig,
+        onViewableItemsChanged: (rowInfo) => {
+            pair.onViewableItemsChanged(expandRowViewability(rowInfo, props.keyExtractor));
+        },
+    })));
+    // The two paths instantiate VirtualizedList over DIFFERENT item types — ItemT vs IRow<ItemT> —
+    // so they are two elements, not one with switching props: a single instantiation would have to
+    // union the two and narrow ItemT | IRow<ItemT> back apart at runtime, which nothing can do
+    // soundly for an arbitrary ItemT. <Show> memoizes on the flip alone, so a numColumns change
+    // rebuilds (RN documents changing it live as unsupported — "change the key prop" — which is the
+    // same fresh start) while every other prop change re-props the live list.
+    return (<Show when={isMultiColumn()} fallback={<VirtualizedList {...passthrough} data={props.data} getItem={(_source, index) => props.data[index]} getItemCount={() => props.data.length} renderItem={props.renderItem} keyExtractor={props.keyExtractor} ItemSeparatorComponent={props.ItemSeparatorComponent} onViewableItemsChanged={props.onViewableItemsChanged} viewabilityConfigCallbackPairs={props.viewabilityConfigCallbackPairs}/>}>
+      <VirtualizedList {...passthrough} data={rows()} getItem={(_source, index) => rows()[index]} getItemCount={() => rows().length} renderItem={renderRow} keyExtractor={rowKeyExtractor} ItemSeparatorComponent={rowSeparatorComponent()} onViewableItemsChanged={rowViewability()} viewabilityConfigCallbackPairs={rowViewabilityPairs()}/>
+    </Show>);
+}

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

@@ -0,0 +1,10 @@
+import type { JSX } from '../jsx-runtime';
+import { type IImageProps } from '@symbiote-native/components';
+import { type IClassNameValue, type IStyleProp, type IViewStyle } from '@symbiote-native/engine';
+export interface IImageBackgroundProps extends Omit<IImageProps, 'style'> {
+    style?: IStyleProp<IViewStyle>;
+    imageStyle?: IStyleProp<IViewStyle> | string;
+    class?: IClassNameValue;
+    children?: JSX.Element;
+}
+export declare function ImageBackground(props: IImageBackgroundProps): JSX.Element;

package/build/components/image-background.jsx

@@ -0,0 +1,74 @@
+// ImageBackground — the Solid lifecycle half. The composition (the absolute-fill Image behind the
+// children, the wrapper-dimension proxy onto that Image, the imageStyle-last merge) lives
+// framework-agnostic in @symbiote-native/components' renderImageBackground and is shared verbatim
+// with React, Vue and Svelte. Solid supplies only the reactivity, the class-name resolution and
+// the child order.
+//
+// SPLIT DOWN THE MIDDLE, and the seam is the children rule. The wrapper hosts a live Solid subtree
+// (the overlay content), which only the reconciler can reduce, so it stays a literal
+// `symbiote-view` carrying the shared fn's own props — the same shape View and SafeAreaView use,
+// and the same one Svelte's ImageBackground lands on. The inner image is a leaf built entirely
+// from VALUES, so it goes through descriptorToSolid, which builds it once and re-props it in place
+// (replacing it would restart the download and drop the decoded bitmap).
+//
+// FLAT FILE, no folder: there are no platform or shared variants to group
+// (`symbiote-file-layout` — only genuine groups get a folder).
+//
+// NOTHING here destructures `props` at setup. Solid props are getters and a component body runs
+// ONCE; splitProps keeps every bucket reactive, and each read happens inside an accessor.
+import { createMemo, splitProps } from 'solid-js';
+import { createDescriptorShapeGuard, renderImageBackground, resolveAccessibilityProps, } from '@symbiote-native/components';
+import { resolveClassName, } from '@symbiote-native/engine';
+import { descriptorToSolid } from '../descriptor-to-solid.js';
+// renderImage's typed view fields — the props it CONSUMES rather than forwards. Split off so they
+// never also ride through `passthrough`: the W3C aliases in particular must not reach Fabric raw,
+// since native sees only the resolved `source` array they fold into. `style` is absent on purpose
+// — the inner image's style is computed by renderImageBackground, never taken from the caller.
+const IMAGE_VIEW_PROPS = [
+    'source',
+    'defaultSource',
+    'loadingIndicatorSource',
+    'resizeMode',
+    'tintColor',
+    'src',
+    'srcSet',
+    'alt',
+    'width',
+    'height',
+    'crossOrigin',
+    'referrerPolicy',
+];
+const shape = createDescriptorShapeGuard('ImageBackground');
+export function ImageBackground(props) {
+    const [local, view, rest] = splitProps(props, ['children', 'style', 'imageStyle', 'class'], IMAGE_VIEW_PROPS);
+    // One memo, so the wrapper bag and the inner image derive from a SINGLE call per change.
+    const wrapper = createMemo(() => renderImageBackground({
+        style: local.style,
+        // A bare string is a registered class name and has to become a style object here, before
+        // it reaches the shared fn — which merges it, and knows nothing about the registry.
+        imageStyle: typeof local.imageStyle === 'string'
+            ? resolveClassName(local.imageStyle)
+            : local.imageStyle,
+        image: {
+            ...view,
+            // The wrapper is a raw host, not the View component, so the aria/role fold is this
+            // component's own job; the resolved surface rides the IMAGE, matching every other adapter.
+            passthrough: { ...resolveAccessibilityProps(rest) },
+        },
+    }));
+    const backgroundImage = descriptorToSolid(() => shape.asElement(wrapper().children[0]));
+    // ONE object literal rather than a spread-then-override on the tag: `class` is legitimately
+    // undefined, and Solid's mergeProps (which the compiler uses for a spread followed by an
+    // explicit prop) would discard that undefined instead of applying it
+    // (.claude/rules/solid-descriptor-bridge.md §6). No withStableKeys — renderImageBackground's
+    // wrapper props are `{ style }` unconditionally, so no key can vanish between runs.
+    const wrapperBag = () => ({
+        ...wrapper().props,
+        class: local.class,
+    });
+    // The user children come AFTER the image in child order, which is what makes them paint on top.
+    return (<symbiote-view {...wrapperBag()}>
+      {backgroundImage}
+      {local.children}
+    </symbiote-view>);
+}

package/build/components/image.d.ts

@@ -0,0 +1,9 @@
+import type { JSX } from '../jsx-runtime';
+import { type IImageProps as IImageBaseProps, type IImageStatics } from '@symbiote-native/components';
+import type { IClassNameValue } from '@symbiote-native/engine';
+export type { IImageStatics } from '@symbiote-native/components';
+export type IImageProps = IImageBaseProps & {
+    class?: IClassNameValue;
+};
+export type IImageWithStatics = ((props: IImageProps) => JSX.Element) & IImageStatics;
+export declare const Image: IImageWithStatics;

package/build/components/image.js

@@ -0,0 +1,75 @@
+// Image — the Solid lifecycle half. Everything that turns props into a native prop bag (the
+// source / src / srcSet resolution, the width+height fold into style, resizeMode and tintColor
+// read back off the style, alt -> accessibilityLabel, the array shape native expects) lives
+// framework-agnostic in @symbiote-native/components' renderImage, shared verbatim with React, Vue
+// and Svelte. Solid supplies only the reactivity and the Descriptor bridge.
+//
+// PLAIN .ts, NOT .tsx, unlike ./view.tsx and ./text.tsx — and the difference is the children rule,
+// not a style choice. View and Text take a live subtree of the user's components, which only the
+// framework's own reconciler can reduce, so they emit real JSX. An image is a leaf built entirely
+// from VALUES, so it goes through renderImage + descriptorToSolid exactly like Switch does
+// (.claude/rules/component-render-fn-boundary.md).
+//
+// NOTHING here destructures `props`. Solid props are getters and a component body runs ONCE;
+// splitProps is the idiomatic split that keeps both halves reactive, and every read below happens
+// inside the descriptor accessor descriptorToSolid re-runs.
+//
+// ASSET RESOLUTION IS LAZY BY CONSTRUCTION, and that is what lets an app drop the hand-rolled
+// resolveImageSource() call it needed while this component did not exist. renderImage calls
+// resolveImageSource at RENDER time, and the resolver behind it is installed by bootstrapHost,
+// which createApp().mount() runs before AppRegistry ever renders a root. So a `require('./x.png')`
+// asset id handed to `source` is resolved by RN's own resolveAssetSource on the way to Fabric,
+// with no ordering hazard: a module-scope resolve would run one step too early, an accessor-time
+// one cannot.
+import { splitProps } from 'solid-js';
+import { imageStatics, renderImage, resolveAccessibilityProps, } from '@symbiote-native/components';
+import { descriptorToSolid } from '../descriptor-to-solid.js';
+// renderImage's typed view fields — the props it CONSUMES rather than forwards. Split off here so
+// they never also ride through `passthrough`: the W3C aliases in particular must not reach Fabric
+// raw, since native sees only the resolved `source` array they fold into. Everything else (the
+// load events, blurRadius, capInsets, resizeMethod, fadeDuration, testID, `class`, a caller's own
+// `ref`, the accessibility props) stays in `rest` and lands on the host image untouched.
+const VIEW_PROPS = [
+    'source',
+    'defaultSource',
+    'loadingIndicatorSource',
+    'style',
+    'resizeMode',
+    'tintColor',
+    'src',
+    'srcSet',
+    'alt',
+    'width',
+    'height',
+    'crossOrigin',
+    'referrerPolicy',
+];
+function ImageComponent(props) {
+    const [view, rest] = splitProps(props, VIEW_PROPS);
+    // The node is created once and kept by identity — descriptorToSolid wires every prop through a
+    // render effect on that same node, so a later source/style/alt change re-commits the existing
+    // image rather than replacing it (which would restart the download and drop the decoded bitmap).
+    return descriptorToSolid(() => renderImage({
+        source: view.source,
+        defaultSource: view.defaultSource,
+        loadingIndicatorSource: view.loadingIndicatorSource,
+        style: view.style,
+        resizeMode: view.resizeMode,
+        tintColor: view.tintColor,
+        src: view.src,
+        srcSet: view.srcSet,
+        alt: view.alt,
+        width: view.width,
+        height: view.height,
+        crossOrigin: view.crossOrigin,
+        referrerPolicy: view.referrerPolicy,
+        // Image owns its host element rather than rendering through a symbiote View, so folding
+        // aria/role into the canonical accessibility* props is its own job, like Switch's.
+        // renderImage's own `alt` fold then defers to an explicit accessibilityLabel found here.
+        passthrough: { ...resolveAccessibilityProps(rest) },
+    }));
+}
+// Statics attached like RN's own `Image.getSize` / `prefetch` / `queryCache` / `abortPrefetch` /
+// `getSizeWithHeaders` / `resolveAssetSource`, by identity off the same @symbiote-native/engine
+// module React, Vue and Svelte attach — never a Solid-side reimplementation.
+export const Image = Object.assign(ImageComponent, imageStatics);

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

@@ -0,0 +1,11 @@
+import type { JSX } from '../jsx-runtime';
+import { type IAccessibilityProps, type IAriaProps } from '@symbiote-native/components';
+import type { IClassNameValue, IStyleProp, IViewStyle } from '@symbiote-native/engine';
+export interface IInputAccessoryViewProps extends IAccessibilityProps, IAriaProps {
+    nativeID?: string;
+    backgroundColor?: string;
+    style?: IStyleProp<IViewStyle>;
+    class?: IClassNameValue;
+    children?: JSX.Element;
+}
+export declare function InputAccessoryView(props: IInputAccessoryViewProps): JSX.Element;

package/build/components/input-accessory-view.jsx

@@ -0,0 +1,39 @@
+// InputAccessoryView — the Solid lifecycle half (iOS). The host-node assembly (nativeID /
+// backgroundColor / style / passthrough forwarding onto `symbiote-input-accessory-view`) lives
+// framework-agnostic in @symbiote-native/components' renderInputAccessoryView and is shared
+// verbatim with React, Vue and Svelte; Solid supplies only the reactivity and the children.
+//
+// REAL JSX, NOT descriptorToSolid — the same rule View and SafeAreaView follow. The render fn
+// returns a host with ZERO structural children by contract; the toolbar content is a live Solid
+// subtree only the reconciler can reduce, so the tag stays literal and the shared fn contributes
+// its PROPS. The literal tag is safe because renderInputAccessoryView's `type` is a constant.
+//
+// NOTHING here destructures `props` at setup. Solid props are getters and a component body runs
+// ONCE; splitProps keeps both halves reactive, and every read happens inside the bag accessor
+// that `spread` re-runs as a render effect on the SAME host node.
+import { splitProps } from 'solid-js';
+import { renderInputAccessoryView, resolveAccessibilityProps, } from '@symbiote-native/components';
+import { withStableKeys } from '../utils/stable-keys.js';
+export function InputAccessoryView(props) {
+    const [local, rest] = splitProps(props, [
+        'children',
+        'nativeID',
+        'backgroundColor',
+        'style',
+    ]);
+    // withStableKeys is load-bearing twice over: renderInputAccessoryView emits `nativeID` and
+    // `backgroundColor` CONDITIONALLY, and resolveAccessibilityProps has two branches with
+    // different key sets. Solid's `spread` has no removal pass, so a key that vanishes between
+    // runs would keep its last value on the native view forever (see utils/stable-keys.ts).
+    const bag = withStableKeys(() => renderInputAccessoryView({
+        nativeID: local.nativeID,
+        backgroundColor: local.backgroundColor,
+        style: local.style,
+        // This component owns its host element rather than rendering through a View, so folding
+        // aria/role into the canonical accessibility* props is its own job, like Image's.
+        passthrough: { ...resolveAccessibilityProps(rest) },
+    }).props);
+    return (<symbiote-input-accessory-view {...bag()}>
+      {local.children}
+    </symbiote-input-accessory-view>);
+}

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

@@ -0,0 +1,15 @@
+import type { JSX } from '../jsx-runtime';
+import { type IAccessibilityProps, type IAriaProps, type IKeyboardAvoidingBehavior } from '@symbiote-native/components';
+import { type IClassNameValue, type IStyleProp, type ISymbioteEvent, type IViewStyle } from '@symbiote-native/engine';
+export type { IKeyboardAvoidingBehavior } from '@symbiote-native/components';
+export interface IKeyboardAvoidingViewProps extends IAccessibilityProps, IAriaProps {
+    behavior?: IKeyboardAvoidingBehavior;
+    enabled?: boolean;
+    keyboardVerticalOffset?: number;
+    contentContainerStyle?: IStyleProp<IViewStyle>;
+    style?: IStyleProp<IViewStyle>;
+    class?: IClassNameValue;
+    onLayout?: (event: ISymbioteEvent) => void;
+    children?: JSX.Element;
+}
+export declare function KeyboardAvoidingView(props: IKeyboardAvoidingViewProps): JSX.Element;

package/build/components/keyboard-avoiding-view.jsx

@@ -0,0 +1,152 @@
+// KeyboardAvoidingView — the Solid lifecycle half. It composes a wrapper View and shifts it out of
+// the keyboard's way as the keyboard shows/hides. The inset math (readKeyboardFrame /
+// readLayoutFrame / computeInset) and the behavior → style/structure decision
+// (resolveKeyboardAvoidingLayout) are framework-agnostic and live in @symbiote-native/components,
+// shared verbatim with React, Vue, Svelte and Angular. Solid supplies only the reactivity: one
+// signal for the inset, three plain variables for the measured frame and the cross-fade setting, a
+// subscribe-at-setup / onCleanup pair over the Keyboard module, and the element assembly around its
+// own children.
+//
+// render-keyboard-avoiding-view.ts deliberately returns a layout DESCRIPTION rather than a
+// Descriptor tree — KAV wraps a live user subtree, which is the case the render-fn boundary rules
+// OUT of core (.claude/rules/component-render-fn-boundary.md). So descriptorToSolid has nothing to
+// do here, exactly as in View and Pressable; the two structural shapes ('nested' vs 'wrapper') are
+// written directly as the two branches at the bottom.
+//
+// NO whenCommitted anywhere: KAV issues no imperative native call. It only reads `onLayout`, and the
+// engine raises the native layout flag itself the moment a listener rides the prop bag — an event
+// cannot arrive before the view exists, so there is no pre-commit window to retry across.
+//
+// NOTHING here destructures `props`. Solid props are getters and a component body runs ONCE; every
+// read below sits inside an accessor, a memo, or an event handler — including
+// `keyboardVerticalOffset`, which is read at EVENT time so a changed offset applies to the next
+// keyboard event without re-subscribing (React re-runs its useEffect for that; here the closure
+// already sees the live value).
+import { createMemo, createSignal, onCleanup, splitProps } from 'solid-js';
+import { computeInset, keyboardAvoidingEventNamesFor, readKeyboardFrame, readLayoutFrame, readPrefersCrossFadeTransitions, resolveKeyboardAvoidingLayout, DEFAULT_VERTICAL_OFFSET, } from '@symbiote-native/components';
+import { Keyboard, Platform, dlog, } from '@symbiote-native/engine';
+import { View } from './view.jsx';
+// Read by KeyboardAvoidingView itself; everything else (the aria/role aliases, accessibility*,
+// testID, class) forwards onto the wrapper View, which folds them once through
+// resolveAccessibilityProps and widens the vanished-key case with withStableKeys.
+const HANDLED_PROPS = [
+    'behavior',
+    'enabled',
+    'keyboardVerticalOffset',
+    'contentContainerStyle',
+    'style',
+    'onLayout',
+    'children',
+];
+export function KeyboardAvoidingView(props) {
+    const [local, rest] = splitProps(props, HANDLED_PROPS);
+    const [inset, setInset] = createSignal(0);
+    // Plain variables, not signals: a re-measure alone must not repaint anything. They only feed the
+    // NEXT keyboard event's math, which is what re-runs the layout memo. Same shape as React's
+    // frameRef/initialHeightRef, Vue's `let frame` and Svelte's non-$state pair.
+    let frame;
+    let initialHeight;
+    // A device accessibility setting, not state: it cannot change mid-session, and nothing should
+    // repaint when the promise lands. So a plain `let` rather than a signal — the same reason `frame`
+    // above is one. It is read at EVENT time, by which point the microtask has long resolved; a
+    // keyboard event that somehow beat it just sees the `false` default, which is the ordinary math.
+    //
+    // Through the shared reader, not AccessibilityInfo directly: the engine's getter REJECTS on a
+    // native error (RN parity), and nothing awaits this call, so a rejection here would surface as an
+    // unhandled promise. readPrefersCrossFadeTransitions owns that fallback once for all five adapters
+    // and answers false, which is also what a missing module and an Android host answer.
+    let prefersCrossFadeTransitions = false;
+    void readPrefersCrossFadeTransitions().then(enabled => {
+        prefersCrossFadeTransitions = enabled;
+    });
+    const onShow = (payload) => {
+        const keyboard = readKeyboardFrame(payload);
+        const offset = local.keyboardVerticalOffset ?? DEFAULT_VERTICAL_OFFSET;
+        const next = computeInset(frame, keyboard, offset, {
+            behavior: local.behavior,
+            // The inset CURRENTLY applied (RN's this.state.bottom). Read from the signal at event time so
+            // it is live: in 'height' mode the wrapper is SHRUNK by it, so the next onLayout reports a
+            // frame shorter by exactly that much and core adds it back to cancel the shrink. Without it
+            // each further keyboard event computes a smaller overlap and the view walks back down under
+            // the keyboard. Core gates the correction on 'height'; the other modes ignore the value.
+            previousInset: inset(),
+            prefersCrossFadeTransitions,
+        });
+        dlog(`KeyboardAvoidingView show -> inset ${next}`);
+        setInset(next);
+    };
+    const onHide = () => {
+        dlog('KeyboardAvoidingView hide -> inset 0');
+        setInset(0);
+    };
+    // TWO listeners, never three, and their names come from the host (RN KeyboardAvoidingView.js):
+    // iOS takes the WILL pair so the view rides up with the keyboard animation instead of snapping
+    // into place after it; Android has no will-notifications and keeps the DID pair. The change-frame
+    // notification is deliberately absent — RN's own comment says an undocked, split or floating iOS
+    // keyboard emits it BEFORE the hide, so listening to it applies a frame captured mid-dismissal.
+    //
+    // Subscribed in the setup body, which runs once per mount — Solid's counterpart to React's
+    // mount-effect and Vue's onMounted. onCleanup runs on dispose (render.ts's teardown disposes the
+    // whole root), so an unmount removes exactly the listeners this mount added; leaking them would
+    // leave a dead closure calling setInset on a disposed signal on every keystroke.
+    const events = keyboardAvoidingEventNamesFor(Platform.OS);
+    const subscriptions = [
+        Keyboard.addListener(events.show, onShow),
+        Keyboard.addListener(events.hide, onHide),
+    ];
+    onCleanup(() => {
+        for (const subscription of subscriptions)
+            subscription.remove();
+    });
+    const handleLayout = (event) => {
+        const measured = readLayoutFrame(event.nativeEvent.layout);
+        if (measured !== undefined) {
+            frame = measured;
+            if (initialHeight === undefined)
+                initialHeight = measured.height;
+        }
+        local.onLayout?.(event);
+    };
+    const layout = createMemo(() => resolveKeyboardAvoidingLayout({
+        behavior: local.behavior,
+        // When disabled the inset is forced to 0, so every behavior mode renders untouched. `inset()`
+        // is not read at all on that branch, so a disabled KAV does not even subscribe to the signal;
+        // re-enabling re-runs this memo through the `local.enabled` getter and picks the value up.
+        effectiveInset: local.enabled === false ? 0 : inset(),
+        initialHeight,
+        style: local.style,
+        contentContainerStyle: local.contentContainerStyle,
+    }));
+    // What keeps the children alive across a keystroke. Solid has no reconciler between this file and
+    // the host nodes — `insert` REPLACES a subtree (.claude/rules/solid-descriptor-bridge.md §4) — and
+    // the branch below runs inside the wrapper's `insert` render effect. `layout()` returns a fresh
+    // object on every keyboard event, so anything that lets it reach that effect tears the wrapped
+    // subtree down and rebuilds it on every show/hide: typically the form the user is typing in, which
+    // loses focus mid-keystroke. createMemo's default `===` equality stops the churn at the BOOLEAN —
+    // it only notifies when the structure actually flips, i.e. when `behavior` moves in or out of
+    // 'position'.
+    //
+    // babel-preset-solid's `wrapConditionals` (on by default) would memoize the condition of the
+    // ternary below on its own, so the inline form happens to be safe too. Naming the memo makes that
+    // guarantee local instead of a compiler flag nobody reads, and it survives the refactor that
+    // actually breaks it — measured: moving the same branch into a plain `renderContent()` helper (the
+    // shape Pressable uses) defeats wrapConditionals and rebuilds the subtree on every keyboard event.
+    const isNested = createMemo(() => layout().kind === 'nested');
+    // The inset reaches the host as a PROP instead: `spread` runs a per-key diff on the SAME element,
+    // so nothing is rebuilt.
+    const innerStyle = () => {
+        const resolved = layout();
+        return resolved.kind === 'nested' ? resolved.innerStyle : undefined;
+    };
+    const wrapperProps = createMemo(() => ({
+        ...rest,
+        style: layout().wrapperStyle,
+        // Last, so KAV's own measure always runs; the caller's handler is invoked from inside it.
+        onLayout: handleLayout,
+    }));
+    // 'nested' ('position') pushes the children in an inner View by `bottom: inset`; the wrapper modes
+    // ('padding' / 'height' / no behavior) adjust the single wrapper directly.
+    return (<View {...wrapperProps()}>
+      {isNested() ? (<View style={innerStyle()}>{local.children}</View>) : (local.children)}
+    </View>);
+}

package/build/components/modal.d.ts

@@ -0,0 +1,24 @@
+import type { JSX } from '../jsx-runtime';
+import { type IAccessibilityProps, type IAriaProps, type IModalAnimationType, type IModalOrientation, type IModalPresentationStyle } from '@symbiote-native/components';
+import { type IClassNameValue, type IStyleProp, type ISymbioteEvent, type IViewStyle } from '@symbiote-native/engine';
+export type { IModalAnimationType, IModalPresentationStyle, IModalOrientation, IModalOrientationChangeEvent, } from '@symbiote-native/components';
+export interface IModalProps extends IAccessibilityProps, IAriaProps {
+    visible?: boolean;
+    transparent?: boolean;
+    backdropColor?: string;
+    animationType?: IModalAnimationType;
+    presentationStyle?: IModalPresentationStyle;
+    supportedOrientations?: ReadonlyArray<IModalOrientation>;
+    hardwareAccelerated?: boolean;
+    statusBarTranslucent?: boolean;
+    navigationBarTranslucent?: boolean;
+    allowSwipeDismissal?: boolean;
+    onShow?: () => void;
+    onDismiss?: () => void;
+    onRequestClose?: () => void;
+    onOrientationChange?: (event: ISymbioteEvent) => void;
+    style?: IStyleProp<IViewStyle>;
+    class?: IClassNameValue;
+    children?: JSX.Element;
+}
+export declare function Modal(props: IModalProps): JSX.Element;