@symbiote-native/components 0.3.0 → 0.5.0

package/build/state/virtualized-list.js

@@ -56,8 +56,6 @@ function readNumber(source, key) {
 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)
@@ -67,7 +65,19 @@ export function readScrollOffset(event, horizontal) {
         return undefined;
     return readNumber(offset, horizontal ? 'x' : 'y');
 }
-// onLayout -> the cross-section length of the box along the scroll axis.
+// The cell's own position inside the scroll content, as the host reported it. Paired with
+// readLayoutLength at the same onLayout: this is the value buildOffsets stores VERBATIM, and it is
+// what lets the table describe where the content actually is rather than where a sum of heights
+// says it should be.
+export function readLayoutOffset(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 ? 'x' : 'y');
+}
 export function readLayoutLength(event, horizontal) {
     const native = asRecord(event.nativeEvent);
     if (native === undefined)
@@ -80,23 +90,53 @@ export function readLayoutLength(event, horizontal) {
 // 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) {
+//
+// THE COORDINATE SPACE IS THE HOST'S, NOT A MODEL'S. `measuredOffsets` holds each cell's raw y (x
+// when horizontal) exactly as onLayout reported it — content-container relative, so it carries the
+// container's padding, the list header, and whatever spacer stood above the cell at the time. A
+// measured cell is placed at that value VERBATIM. It is never re-derived from a neighbour, never
+// rebased onto a running sum. This is react-native's ListMetricsAggregator: `getCellMetricsApprox`
+// returns a laid-out cell's real frame untouched and approximates only what has never been seen.
+//
+// That "verbatim" is the whole safety property, and it is not a stylistic preference — it is the
+// fix for the canary going blank mid-scroll (diagnosed on device 2026-08-19). The table is not
+// merely an output: buildListPlan sizes the leading spacer from it, the host lays the window's
+// cells out below that spacer, and their measured y — spacer included — comes straight back in
+// here. It is a closed loop. Combining two measurements arithmetically inside that loop feeds the
+// model's own error back to itself: with a Yoga `gap` on the content container (the canary's .grid
+// has one) a spacer is an extra flex child, so its presence shifts the layout by one more gap than
+// any pure-arithmetic model predicts, and differencing two cells measured either side of that
+// change banks the difference. Measured, at one gap per recompute, unbounded — onScroll fires per
+// frame, so the spacer walks thousands of pixels away from reality within a second of dragging and
+// the window lands nowhere near the viewport. Regression test:
+// core/components/src/state/virtualized-list-feedback.test.ts.
+//
+// Unmeasured cells are the only place an estimate lives, and they advance by the average STRIDE
+// (measured cell-origin to cell-origin) rather than by the average LENGTH. A height is not the
+// distance to the next cell: separators, section gaps and container `gap` all live in between, and
+// sizing an unmeasured region by heights alone leaves it short by exactly that chrome.
+//
+// A fixed getItemLayout skips all of it — authoritative by contract, and its offsets are exact.
+export function buildOffsets(count, measured, measuredOffsets, fixedLayout, averageLength, averageStride) {
     const offsets = new Array(count);
     const lengths = new Array(count);
-    let running = EMPTY_OFFSET;
+    // What the average stride has left over once the average cell is accounted for: the chrome drawn
+    // BETWEEN two cells. Estimating with this rather than the stride itself keeps a cell whose own
+    // length IS known from being overwritten by an average — the stride is only ever used for the
+    // part nobody measured.
+    const interCellChrome = Math.max(EMPTY_OFFSET, averageStride - averageLength);
+    // Where the next cell goes when its own position has never been reported.
+    let cursor = 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;
+        const layout = fixedLayout?.(index);
+        const known = layout?.offset ?? measuredOffsets.get(index);
+        offsets[index] = known ?? cursor;
+        lengths[index] = layout?.length ?? measured.get(index) ?? averageLength;
+        cursor = offsets[index] + lengths[index] + interCellChrome;
     }
-    return { offsets, lengths, total: running };
+    const last = count - 1;
+    const total = count > FIRST_INDEX ? offsets[last] + lengths[last] : EMPTY_OFFSET;
+    return { offsets, lengths, total };
 }
 // Pick the resident window: every index whose box overlaps
 // [offset - buffer, offset + viewport + buffer]. The buffer is (windowSize - 1) / 2
@@ -106,7 +146,10 @@ export function computeWindow(count, offsets, lengths, scrollOffset, viewportLen
         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 };
+        return {
+            first: FIRST_INDEX,
+            last: Math.min(count, initialNumToRender) - 1,
+        };
     }
     const overscan = ((windowSize - 1) / 2) * viewportLength;
     const windowTop = scrollOffset - overscan;
@@ -152,7 +195,8 @@ 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;
+    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
@@ -165,6 +209,24 @@ export function offsetForIndex(index, viewPosition, viewOffset, count, offsets,
     const positioned = cellOffset - viewPosition * (viewportLength - cellLength);
     return Math.max(EMPTY_OFFSET, positioned - viewOffset);
 }
+// Two layout readings are the SAME measurement unless they differ by more than this.
+//
+// A relayout does not reproduce a float bit-for-bit: the cell positions are derived from a spacer
+// height that is itself a float, so an onLayout that changed nothing observable still comes back a
+// few ulps off. Compared with ===, every one of those counts as a change — the reducer stores it,
+// the spacer derived from it moves in its last bits, Fabric commits the new value, Yoga relays out,
+// and the fresh onLayout starts the next turn. A loop at frame rate, from a difference no screen
+// can show. Device-measured 2026-08-19: 1203 recomputes over one short drag, its log full of
+// `27.33 -> 27.33 (-0.00)`.
+//
+// The smallest change a host can actually express is one device pixel — a third of a point at @3x —
+// so this sits ~30x below any real move and ~1e11 above the noise.
+export const LAYOUT_EPSILON = 0.01;
+// `known` is optional because a first measurement has nothing to settle against, and must count as
+// a change.
+export function isSettledLayout(known, reported) {
+    return known !== undefined && Math.abs(known - reported) < LAYOUT_EPSILON;
+}
 // 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) {
@@ -175,6 +237,27 @@ export function averageMeasuredLength(measured) {
         sum += length;
     return sum / measured.size;
 }
+// Average origin-to-origin distance between two ADJACENT measured cells — the length plus whatever
+// chrome the list draws in the gap (a separator, a section gap, the content container's Yoga
+// `gap`). Only adjacent pairs qualify: across a hole the distance covers cells nobody measured.
+//
+// This is what an unmeasured cell advances by, and it is deliberately not averageMeasuredLength.
+// Sizing an unmeasured region by heights alone makes the model shorter than the content, so the
+// spacer standing in for that region under-reserves and everything below it slides up — the
+// jump-and-return the canary showed before the offsets became host-absolute. Falls back to the
+// length average while no adjacent pair has been measured yet.
+export function averageMeasuredStride(measuredOffsets, fallback) {
+    let sum = EMPTY_OFFSET;
+    let pairs = EMPTY_OFFSET;
+    for (const [index, offset] of measuredOffsets) {
+        const next = measuredOffsets.get(index + 1);
+        if (next === undefined)
+            continue;
+        sum += next - offset;
+        pairs += 1;
+    }
+    return pairs === EMPTY_OFFSET ? fallback : sum / pairs;
+}
 // The largest index whose length has actually been measured (RN
 // ListMetricsAggregator.getHighestMeasuredCellIndex). NO_INDEX when nothing is measured.
 export function highestMeasuredIndex(measured) {
@@ -207,7 +290,10 @@ export function computeStartReached(scrollOffset, viewportLength, thresholdMulti
 export function buildViewabilityPairs(onViewableItemsChanged, viewabilityConfig, pairs) {
     const result = [];
     if (onViewableItemsChanged !== undefined) {
-        result.push({ viewabilityConfig: viewabilityConfig ?? {}, onViewableItemsChanged });
+        result.push({
+            viewabilityConfig: viewabilityConfig ?? {},
+            onViewableItemsChanged,
+        });
     }
     if (pairs !== undefined)
         result.push(...pairs);
@@ -222,10 +308,13 @@ export function computeViewableSet(params) {
     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);
+        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) {
+            if (pair.viewabilityConfig.waitForInteraction === true &&
+                !params.hasInteracted) {
                 continue;
             }
             if (isCellViewable(percent, pair.viewabilityConfig)) {
@@ -279,31 +368,75 @@ export function maxMinimumViewTime(pairs) {
     }
     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.
+// Find the nearest sticky index strictly below `first` — the RN _ensureClosestStickyHeader
+// backward walk. Returns NO_INDEX when none exists (no sticky section applies yet, or the
+// applicable one is already inside the window).
+function findClosestStickyIndexBelow(first, stickyIndices) {
+    for (let index = first - 1; index >= FIRST_INDEX; index -= 1) {
+        if (stickyIndices.has(index))
+            return index;
+    }
+    return NO_INDEX;
+}
+// Compute the windowed child PLAN: the spacer extents, the in-window cells (index + key),
+// the force-mounted sticky cell (if any) ahead of the window, 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]
+    const closestStickyIndex = params.stickyIndices !== undefined
+        ? findClosestStickyIndexBelow(params.first, params.stickyIndices)
+        : NO_INDEX;
+    const forcedStickyCell = closestStickyIndex === NO_INDEX
+        ? undefined
+        : { index: closestStickyIndex, key: params.keyFor(closestStickyIndex) };
+    // A spacer stands in for a contiguous run of cells, so its extent is the distance from the first
+    // of them to the far edge of the last — a difference between two positions the host itself
+    // reported, never a sum of heights. That is what carries the chrome BETWEEN those cells
+    // (separators, section gaps, the container's Yoga `gap`) without the model having to know it
+    // exists, and it is why the spacer lands the following cell exactly where it already was: the
+    // spacer occupies one child slot, precisely as the region it replaces began and ended on a cell
+    // boundary. Summing heights instead under-reserves by the chrome; rebasing onto a running model
+    // re-introduces the feedback loop buildOffsets exists to avoid.
+    const regionExtent = (from, to) => to < from
+        ? EMPTY_OFFSET
+        : params.offsets[to] + params.lengths[to] - params.offsets[from];
+    const windowLeadingExtent = regionExtent(FIRST_INDEX, params.first - 1);
+    const leadingExtent = forcedStickyCell === undefined
+        ? windowLeadingExtent
+        : regionExtent(FIRST_INDEX, closestStickyIndex - 1);
+    const gapExtent = forcedStickyCell === undefined
+        ? EMPTY_OFFSET
+        : regionExtent(closestStickyIndex + 1, params.first - 1);
+    const trailingExtent = params.last < params.count - 1
+        ? params.total - params.offsets[params.last + 1]
         : 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.
+    // child; the forced sticky cell (when present) plus its own gap spacer follow. Each cell is
+    // EXACTLY one child — an ItemSeparatorComponent rides INSIDE the cell's own measuring wrapper
+    // (RN VirtualizedListCellRenderer.js:218-221), so it neither shifts these positions nor shows
+    // up in the geometry as chrome the spacers would have to account for separately.
     let childPosition = (params.hasHeader ? 1 : 0) + (leadingExtent > EMPTY_OFFSET ? 1 : 0);
+    if (forcedStickyCell !== undefined) {
+        stickyChildPositions.push(childPosition);
+        childPosition += 1 + (gapExtent > 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 };
+    return {
+        leadingExtent,
+        gapExtent,
+        trailingExtent,
+        cells,
+        forcedStickyCell,
+        stickyChildPositions,
+    };
 }
 export function computeMvcpAdjustment(params) {
     const { minIndexForVisible, count, keyFor } = params;
@@ -316,7 +449,9 @@ export function computeMvcpAdjustment(params) {
         firstVisibleKey: newFirstVisibleKey,
         action: { kind: 'none' },
     };
-    if (prevKey === null || newFirstVisibleKey === null || prevKey === newFirstVisibleKey) {
+    if (prevKey === null ||
+        newFirstVisibleKey === null ||
+        prevKey === newFirstVisibleKey) {
         return settled;
     }
     let anchorIndex = NO_INDEX;
@@ -341,7 +476,10 @@ export function computeMvcpAdjustment(params) {
     const anchoredNearTop = autoThreshold !== undefined && params.scrollOffset <= autoThreshold;
     if (anchoredNearTop) {
         dlog(`VirtualizedList MVCP autoscroll-to-top (offset=${params.scrollOffset} <= ${autoThreshold})`);
-        return { firstVisibleKey: newFirstVisibleKey, action: { kind: 'autoscroll-top' } };
+        return {
+            firstVisibleKey: newFirstVisibleKey,
+            action: { kind: 'autoscroll-top' },
+        };
     }
     dlog(`VirtualizedList MVCP adjust +${insertedExtent}px ` +
         `(anchor "${prevKey}" moved ${minIndexForVisible}->${anchorIndex})`);
@@ -385,7 +523,10 @@ export function decideEdgeReached(params) {
     }
     // Re-arm once out of threshold so the next approach can fire again.
     if (!withinThreshold) {
-        return { shouldFire: false, nextSentForContentLength: NO_CONTENT_LENGTH_SENT };
+        return {
+            shouldFire: false,
+            nextSentForContentLength: NO_CONTENT_LENGTH_SENT,
+        };
     }
     return { shouldFire: false, nextSentForContentLength: sentForContentLength };
 }

package/build/text-props.d.ts

@@ -0,0 +1,9 @@
+export type IEllipsizeMode = 'head' | 'middle' | 'tail' | 'clip';
+export interface ITextDefaultableProps {
+    ellipsizeMode?: IEllipsizeMode;
+    allowFontScaling?: boolean;
+}
+export declare function resolveTextProps<T extends ITextDefaultableProps>(props: T): T & {
+    ellipsizeMode: IEllipsizeMode;
+    allowFontScaling: boolean;
+};

package/build/text-props.js

@@ -0,0 +1,24 @@
+// The defaults RN's Text.js applies before handing props to native, folded once for every adapter.
+//
+// RN does this unconditionally on the outer (non-virtual) path, Text.js:288-291:
+//
+//   processedProps.allowFontScaling = allowFontScaling !== false;
+//   processedProps.ellipsizeMode = ellipsizeMode ?? 'tail';
+//
+// We declared both props in all four adapters and applied NEITHER default, so native fell back to
+// its own: `clip` instead of `tail`. Device-observed 2026-08-19 on examples/svelte — a Text with
+// numberOfLines={1} cut mid-word with no ellipsis at all. Nothing failed; the text was simply
+// wrong, which is why four adapters carried it.
+//
+// Both keys are emitted UNCONDITIONALLY, matching RN and — separately — keeping the key set
+// stable. A fold with two branches that emit different key sets is the exact hazard
+// .claude/rules/solid-descriptor-bridge.md §1 exists for, and Svelte's shim diffs the same way.
+export function resolveTextProps(props) {
+    return {
+        ...props,
+        ellipsizeMode: props.ellipsizeMode ?? 'tail',
+        // `!== false`, not `?? true`: RN treats an explicit `undefined` and a missing prop alike, and
+        // only a literal `false` opts out.
+        allowFontScaling: props.allowFontScaling !== false,
+    };
+}

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

@@ -20,10 +20,16 @@ const CONTAINER_STYLE = {
 };
 function resolveSize(size) {
     if (size === 'small') {
-        return { sizeStyle: { width: SIZE_SMALL_PX, height: SIZE_SMALL_PX }, sizeProp: '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_LARGE_PX, height: SIZE_LARGE_PX },
+            sizeProp: 'large',
+        };
     }
     return { sizeStyle: { width: size, height: size } };
 }
@@ -50,5 +56,7 @@ export function renderActivityIndicator(view, platform) {
         ...view.passthrough,
         style: [CONTAINER_STYLE, view.style],
     };
-    return el('symbiote-view', wrapperProps, [el('symbiote-activity-indicator', nativeProps)]);
+    return el('symbiote-view', wrapperProps, [
+        el('symbiote-activity-indicator', nativeProps),
+    ]);
 }

package/build/view/render-button.js

@@ -1,7 +1,6 @@
-// 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.
+// Button: shared render half (framework-agnostic), matching RN's iOS shape (Button.js): a
+// TouchableOpacity wrapping a Text. Each adapter composes its own TouchableOpacity + Text
+// around the pieces below.
 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.

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

@@ -39,7 +39,13 @@ function expandSrcSet(srcSet, view, headers) {
             continue;
         if (scale === 1)
             useSrcForDefaultScale = false;
-        sources.push({ uri, scale, width: view.width, height: view.height, ...{ headers } });
+        sources.push({
+            uri,
+            scale,
+            width: view.width,
+            height: view.height,
+            ...{ headers },
+        });
     }
     if (useSrcForDefaultScale && view.src !== undefined) {
         sources.push({
@@ -65,7 +71,9 @@ function resolveSourceArray(view) {
         return expandSrcSet(view.srcSet, view, headers);
     }
     if (view.src !== undefined) {
-        return [{ uri: view.src, width: view.width, height: view.height, ...{ headers } }];
+        return [
+            { uri: view.src, width: view.width, height: view.height, ...{ headers } },
+        ];
     }
     if (view.source === undefined) {
         dlog('Image: no source / src / srcSet provided');
@@ -76,7 +84,9 @@ function resolveSourceArray(view) {
     // `source.uri && headers` branch; the array/number shapes pass through untouched.
     if (Object.keys(headers).length > 0 && sources.length === 1) {
         const [only] = sources;
-        if (typeof only === 'object' && only !== null && typeof Reflect.get(only, 'uri') === 'string') {
+        if (typeof only === 'object' &&
+            only !== null &&
+            typeof Reflect.get(only, 'uri') === 'string') {
             return [{ ...only, headers }];
         }
     }

package/build/view/render-input-accessory-view.js

@@ -4,10 +4,13 @@
 // the two by id. There is no JS-side translation: style / nativeID / backgroundColor map straight
 // onto the intrinsic and the user children (injected by the adapter) nest under it. Shared
 // verbatim across adapters: React and Vue both bridge this Descriptor.
-import { dlog } from '@symbiote-native/engine';
+import { dlog, } from '@symbiote-native/engine';
 import { el } from '../descriptor.js';
 export function renderInputAccessoryView(view) {
-    const props = { ...view.passthrough, style: view.style };
+    const props = {
+        ...view.passthrough,
+        style: view.style,
+    };
     if (view.nativeID !== undefined)
         props.nativeID = view.nativeID;
     if (view.backgroundColor !== undefined)

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

@@ -1,4 +1,4 @@
-import type { IStyleProp, IViewStyle } from '@symbiote-native/engine';
+import type { IKeyboardEventName, IPlatformOSType, IStyleProp, IViewStyle } from '@symbiote-native/engine';
 export type IKeyboardAvoidingBehavior = 'height' | 'position' | 'padding';
 export declare const DEFAULT_VERTICAL_OFFSET = 0;
 export interface IMeasuredFrame {
@@ -11,7 +11,19 @@ export interface IKeyboardFrame {
 }
 export declare function readKeyboardFrame(payload: unknown): IKeyboardFrame | undefined;
 export declare function readLayoutFrame(layout: unknown): IMeasuredFrame | undefined;
-export declare function computeInset(frame: IMeasuredFrame | undefined, keyboard: IKeyboardFrame | undefined, verticalOffset: number): number;
+export type IKeyboardAvoidingEventNames = {
+    show: IKeyboardEventName;
+    hide: IKeyboardEventName;
+};
+export declare function keyboardAvoidingEventNamesFor(os: IPlatformOSType): IKeyboardAvoidingEventNames;
+export declare function readPrefersCrossFadeTransitions(query?: () => Promise<boolean>): Promise<boolean>;
+export type IComputeInsetOptions = {
+    behavior?: IKeyboardAvoidingBehavior;
+    previousInset?: number;
+    os?: IPlatformOSType;
+    prefersCrossFadeTransitions?: boolean;
+};
+export declare function computeInset(frame: IMeasuredFrame | undefined, keyboard: IKeyboardFrame | undefined, verticalOffset: number, options?: IComputeInsetOptions): number;
 export type IKeyboardAvoidingLayout = {
     kind: 'nested';
     wrapperStyle?: IStyleProp<IViewStyle>;

package/build/view/render-keyboard-avoiding-view.js

@@ -9,7 +9,7 @@
 // carry. Instead we return a layout DESCRIPTION (which styles to apply and whether to nest)
 // and the adapter builds its own element tree with its children. Mirrors RN's
 // Libraries/Components/Keyboard/KeyboardAvoidingView.js inset/behavior logic.
-import { isRecord } from '@symbiote-native/engine';
+import { AccessibilityInfo, dlog, isRecord, KEYBOARD_EVENT, Platform, } from '@symbiote-native/engine';
 // RN's default keyboardVerticalOffset (KeyboardAvoidingView.js).
 export const DEFAULT_VERTICAL_OFFSET = 0;
 // RN rounds nothing here; 'height' mode collapses flex so the shrunk height holds.
@@ -38,13 +38,51 @@ export function readLayoutFrame(layout) {
         return undefined;
     return { y, height };
 }
+export function keyboardAvoidingEventNamesFor(os) {
+    if (os === 'ios')
+        return { show: KEYBOARD_EVENT.willShow, hide: KEYBOARD_EVENT.willHide };
+    return { show: KEYBOARD_EVENT.didShow, hide: KEYBOARD_EVENT.didHide };
+}
+// The iOS "Prefer Cross-Fade Transitions" setting, read once per mount and fed to computeInset.
+//
+// AccessibilityInfo's iOS getters REJECT when the native error callback fires. That is deliberate
+// RN parity and the engine must keep it — but this caller runs at mount and nobody awaits it, so a
+// rejection would surface as an unhandled promise. Five adapters would each need the same `.catch`,
+// which is five chances to forget one, so the fallback lives here instead. A failed read and "the
+// user does not prefer cross-fade" are indistinguishable to every caller, so false is the honest
+// answer, not a swallowed error.
+//
+// The query is injectable purely so both branches are unit-testable without a native-module fake;
+// adapters call it with no arguments.
+export function readPrefersCrossFadeTransitions(query = () => AccessibilityInfo.prefersCrossFadeTransitions()) {
+    return query().catch((error) => {
+        dlog(`KeyboardAvoidingView: prefersCrossFadeTransitions read failed -> false (${String(error)})`);
+        return false;
+    });
+}
 // RN's _relativeKeyboardHeight: how far up the view must move so it no longer overlaps the
 // keyboard. keyboardY is the keyboard's top edge minus the caller's vertical offset; the inset
 // is the overlap of the view's bottom past that edge, clamped at 0.
-export function computeInset(frame, keyboard, verticalOffset) {
+export function computeInset(frame, keyboard, verticalOffset, options = {}) {
     if (frame === undefined || keyboard === undefined)
         return 0;
+    // With the iOS Prefer Cross-Fade Transitions setting on, the keyboard reports screenY as 0
+    // rather than its real top edge (RN:88-96). Run through the ordinary math that makes the overlap
+    // the view's ENTIRE y + height and pushes the content clean off screen, so RN answers 0.
+    const os = options.os ?? Platform.OS;
+    if (os === 'ios' &&
+        keyboard.screenY === 0 &&
+        options.prefersCrossFadeTransitions === true) {
+        return 0;
+    }
     const keyboardY = keyboard.screenY - verticalOffset;
+    // The 'height' fixpoint (RN:100-105). In this mode the wrapper is SHRUNK by the inset, so its
+    // next onLayout reports a frame shorter by exactly that much. Adding the previous inset back
+    // cancels the shrink; without it each subsequent keyboard event computes a smaller overlap and
+    // the view walks back down under the keyboard. A correction, not an accumulation.
+    if (options.behavior === 'height') {
+        return Math.max((options.previousInset ?? 0) + frame.y + frame.height - keyboardY, 0);
+    }
     return Math.max(frame.y + frame.height - keyboardY, 0);
 }
 // Map the behavior + effective inset onto the wrapper/inner styles and the nesting decision:
@@ -52,7 +90,7 @@ export function computeInset(frame, keyboard, verticalOffset) {
 // wrapper directly. 'height' shrinks the wrapper from its initial measured height (only while
 // the keyboard is up, matching RN).
 export function resolveKeyboardAvoidingLayout(params) {
-    const { behavior, effectiveInset, initialHeight, style, contentContainerStyle } = params;
+    const { behavior, effectiveInset, initialHeight, style, contentContainerStyle, } = params;
     if (behavior === 'position') {
         return {
             kind: 'nested',
@@ -61,12 +99,20 @@ export function resolveKeyboardAvoidingLayout(params) {
         };
     }
     if (behavior === 'padding') {
-        return { kind: 'wrapper', wrapperStyle: [style, { paddingBottom: effectiveInset }] };
+        return {
+            kind: 'wrapper',
+            wrapperStyle: [style, { paddingBottom: effectiveInset }],
+        };
     }
-    if (behavior === 'height' && effectiveInset > 0 && initialHeight !== undefined) {
+    if (behavior === 'height' &&
+        effectiveInset > 0 &&
+        initialHeight !== undefined) {
         return {
             kind: 'wrapper',
-            wrapperStyle: [style, { height: initialHeight - effectiveInset, flex: COLLAPSED_FLEX }],
+            wrapperStyle: [
+                style,
+                { height: initialHeight - effectiveInset, flex: COLLAPSED_FLEX },
+            ],
         };
     }
     return { kind: 'wrapper', wrapperStyle: style };

package/build/view/render-modal.js

@@ -5,7 +5,7 @@
 // maps to the `symbiote-modal` intrinsic the host config routes to ModalHostView, wrapping a
 // full-screen container View that holds the user children (injected by the adapter). Shared
 // verbatim: React and Vue both bridge this Descriptor; the keep-alive state lives in state/modal.ts.
-import { dlog } from '@symbiote-native/engine';
+import { dlog, } from '@symbiote-native/engine';
 import { el } from '../descriptor.js';
 // The full-screen box RN anchors the modal content in (Modal.js styles.container: [side]:0,
 // top:0, flex:1, backgroundColor:'white'). It is NOT position:absolute, it is a flex child that
@@ -45,7 +45,9 @@ export function renderModal(view) {
         backdropOverride,
     ];
     const resolvedPresentationStyle = view.presentationStyle ??
-        (view.transparent === true ? PRESENTATION_OVER_FULL_SCREEN : PRESENTATION_FULL_SCREEN);
+        (view.transparent === true
+            ? PRESENTATION_OVER_FULL_SCREEN
+            : PRESENTATION_FULL_SCREEN);
     dlog('Modal visible -> committing ModalHostView(container View)');
     // collapsable:false keeps the container as a real shadow node (RN sets this so the wrapper is
     // never flattened away under the host). Empty structural children: the adapter injects the

package/build/view/render-pressable/index.js

@@ -8,7 +8,9 @@ import { dlog } from '@symbiote-native/engine';
 // disabled state even if the caller passed none (Pressable.js: disabled != null ? {...state,
 // disabled} : state). Untouched when disabled is unset.
 export function resolveDisabledAccessibilityState(accessibilityState, disabled) {
-    return disabled !== undefined ? { ...accessibilityState, disabled } : accessibilityState;
+    return disabled !== undefined
+        ? { ...accessibilityState, disabled }
+        : accessibilityState;
 }
 // The 3 agnostic gating predicates behind the listener bag below. Angular has no bag to spread -
 // it binds these directly onto template event outputs (see adapters/angular/src/components/

package/build/view/render-scroll-sticky.js

@@ -32,7 +32,7 @@ export function readLayoutNumber(event, key) {
 // layoutY and tracks 1:1 until the next header pushes it off, while the inverted branch pins
 // at the viewport bottom (stickStartPoint) and tracks up to the collision point.
 export function computeStickyInterpolation(params) {
-    const { measured, inverted, scrollViewHeight, layoutY, layoutHeight, nextHeaderLayoutY } = params;
+    const { measured, inverted, scrollViewHeight, layoutY, layoutHeight, nextHeaderLayoutY, } = params;
     const inputRange = [-1, 0];
     const outputRange = [0, 0];
     if (measured) {