@symbiote-native/components 0.4.0 → 1.0.0

package/build/state/text-input.js

@@ -11,6 +11,7 @@
 // latest count, while `lastNativeText` is bookkeeping the controlled-write effect mutates
 // without a render. So the logic layer is the pure folds/maps + the controlled-write predicate;
 // each adapter holds the two pieces in ITS own primitives (React useState/useRef, Vue ref/let).
+import { Platform } from '@symbiote-native/engine';
 // The acknowledged count starts at 0, native has reported nothing yet, so the first
 // controlled write echoes 0 and lands on eventLag 0.
 export const INITIAL_EVENT_COUNT = 0;
@@ -29,11 +30,25 @@ const inputModeToKeyboardType = {
     email: 'email-address',
     none: 'default',
     numeric: 'number-pad',
-    search: 'default',
     tel: 'phone-pad',
     text: 'default',
     url: 'url',
 };
+// `search` is the ONE inputMode token RN resolves per platform (TextInput.js:815-825):
+//   search: Platform.OS === 'ios' ? 'web-search' : 'default'
+// iOS has a dedicated search keyboard whose return key is a magnifier; every other host falls back
+// to the default one. It is deliberately absent from the map above, so there is one source for it
+// rather than a map entry and an override that can drift apart.
+//
+// The host is an ARGUMENT rather than a `Platform.OS` read inside the body, because the headless
+// Platform module always resolves to iOS (platform/index.ts re-exports index.ios) — a direct read
+// would leave the android branch permanently unprovable. resolveTextInputProps supplies the real
+// value. This costs the callers nothing: the exported fold signature is unchanged.
+export function keyboardTypeForInputMode(inputMode, os) {
+    if (inputMode === 'search')
+        return os === 'ios' ? 'web-search' : 'default';
+    return mapAutoComplete(inputModeToKeyboardType, inputMode);
+}
 // RN's enterKeyHint -> returnKeyType map (TextInput.js:805). Note `enter` -> 'default'.
 const enterKeyHintToReturnKeyType = {
     done: 'done',
@@ -122,7 +137,9 @@ const autoCompleteWebToTextContentType = {
 // if the token has no native equivalent. The caller decides the per-platform fallback. Named
 // for its first user (autoComplete), but it is the one generic safe lookup every map shares.
 export function mapAutoComplete(map, token) {
-    return Object.prototype.hasOwnProperty.call(map, token) ? map[token] : undefined;
+    return Object.prototype.hasOwnProperty.call(map, token)
+        ? map[token]
+        : undefined;
 }
 // RN folds W3C `autoComplete` per platform (TextInput.js:938): Android takes the mapped
 // `autoComplete` token (falling back to the raw token), iOS takes the mapped `textContentType`
@@ -187,7 +204,7 @@ export function resolveTextInputProps(input) {
     const folded = foldAutoComplete(input.autoComplete);
     return {
         keyboardType: input.inputMode !== undefined
-            ? mapAutoComplete(inputModeToKeyboardType, input.inputMode)
+            ? keyboardTypeForInputMode(input.inputMode, Platform.OS)
             : input.keyboardType,
         returnKeyType: input.enterKeyHint !== undefined
             ? mapAutoComplete(enterKeyHintToReturnKeyType, input.enterKeyHint)
@@ -195,11 +212,32 @@ export function resolveTextInputProps(input) {
         editable: input.readOnly !== undefined ? !input.readOnly : input.editable,
         submitBehavior: foldSubmitBehavior(input.submitBehavior, input.blurOnSubmit, input.multiline),
         selectionColor: input.selectionColor,
-        cursorColor: input.cursorColor !== undefined ? input.cursorColor : input.selectionColor,
-        selectionHandleColor: input.selectionHandleColor !== undefined ? input.selectionHandleColor : input.selectionColor,
-        underlineColorAndroid: input.underlineColorAndroid !== undefined ? input.underlineColorAndroid : 'transparent',
+        cursorColor: input.cursorColor !== undefined
+            ? input.cursorColor
+            : input.selectionColor,
+        selectionHandleColor: input.selectionHandleColor !== undefined
+            ? input.selectionHandleColor
+            : input.selectionColor,
+        underlineColorAndroid: input.underlineColorAndroid !== undefined
+            ? input.underlineColorAndroid
+            : 'transparent',
         autoComplete: folded.autoComplete,
-        textContentType: input.textContentType !== undefined ? input.textContentType : folded.textContentType,
-        showSoftInputOnFocus: input.inputMode !== undefined ? input.inputMode !== 'none' : input.showSoftInputOnFocus,
+        textContentType: input.textContentType !== undefined
+            ? input.textContentType
+            : folded.textContentType,
+        showSoftInputOnFocus: input.inputMode !== undefined
+            ? input.inputMode !== 'none'
+            : input.showSoftInputOnFocus,
     };
 }
+const TEXT_INPUT_CALLBACKS = {
+    onValueChange: true,
+    onFocus: true,
+    onBlur: true,
+    onEndEditing: true,
+    onSubmitEditing: true,
+    onKeyPress: true,
+    onSelectionChange: true,
+    onContentSizeChange: true,
+};
+export const TEXT_INPUT_CALLBACK_NAMES = Object.keys(TEXT_INPUT_CALLBACKS);

package/build/state/touchable.d.ts

@@ -1,11 +1,11 @@
 import { type ISymbioteEvent } from '@symbiote-native/engine';
 export declare const DEFAULT_ACTIVE_OPACITY = 0.2;
+export declare const OPACITY_ACTIVE_GRANT_DURATION_MS = 0;
 export declare const OPACITY_ACTIVE_DURATION_MS = 150;
 export declare const OPACITY_INACTIVE_DURATION_MS = 250;
 export declare const RESTING_OPACITY = 1;
 export declare const DEFAULT_HIGHLIGHT_CHILD_OPACITY = 0.85;
 export declare const DEFAULT_UNDERLAY_COLOR = "black";
-export declare const DEFAULT_MIN_PRESS_DURATION_MS = 130;
 export type ITouchableHandler = (event: ISymbioteEvent) => void;
 export interface IPressTimingProps {
     delayPressIn?: number;
@@ -34,3 +34,32 @@ export interface ITouchableFeedbackHandlers {
     handlePressOut: ITouchableHandler;
 }
 export declare function createTouchableFeedbackHandlers(config: ITouchableFeedbackConfig, runtime: ITouchableFeedbackRuntime, callbacks: ITouchableFeedbackCallbacks): ITouchableFeedbackHandlers;
+export declare const TOUCHABLE_MIN_PRESS_DURATION_MS = 0;
+export declare function restingOpacityFromStyle(style: unknown): number;
+export interface ITouchablePressHandlerProps {
+    onPress?: unknown;
+    onPressIn?: unknown;
+    onPressOut?: unknown;
+    onLongPress?: unknown;
+}
+export declare function hasTouchablePressHandler(props: ITouchablePressHandlerProps): boolean;
+export interface IHighlightUnderlayRuntime {
+    hideTimerCancel: (() => void) | undefined;
+}
+export declare function createHighlightUnderlayRuntime(): IHighlightUnderlayRuntime;
+export interface IHighlightUnderlayConfig {
+    delayPressOut: number;
+    hasPressHandler: boolean;
+    schedule: (callback: () => void, ms: number) => () => void;
+}
+export interface IHighlightUnderlayCallbacks {
+    setShown: (shown: boolean) => void;
+    onShowUnderlay?: () => void;
+    onHideUnderlay?: () => void;
+}
+export interface IHighlightUnderlayHandlers {
+    handlePressIn: ITouchableHandler;
+    handlePress: ITouchableHandler;
+    handlePressOut: ITouchableHandler;
+}
+export declare function createHighlightUnderlayHandlers(config: IHighlightUnderlayConfig, runtime: IHighlightUnderlayRuntime, callbacks: IHighlightUnderlayCallbacks): IHighlightUnderlayHandlers;

package/build/state/touchable.js

@@ -3,18 +3,35 @@
 // (delayPressIn/delayPressOut/minPressDuration) and the deactivation floor math. The Animated
 // feedback itself is framework (each adapter's Animated namespace), so it stays in the adapter;
 // only the timing constants + the pure wait computation live here.
-import { dlog } from '@symbiote-native/engine';
-// TouchableOpacity.js: _opacityActive(150)/_opacityInactive(250), activeOpacity 0.2.
+import { dlog, flattenStyle, } from '@symbiote-native/engine';
+// TouchableOpacity.js: _opacityActive(0 | 150)/_opacityInactive(250), activeOpacity 0.2.
 export const DEFAULT_ACTIVE_OPACITY = 0.2;
+// RN picks the press-in fade duration from WHERE the press-in came from
+// (`TouchableOpacity.js:215-220`):
+//
+//   event.dispatchConfig.registrationName === 'onResponderGrant' ? 0 : 150
+//
+// The grant branch is an ordinary tap and it is INSTANT. `Pressability.js:453-468` shows why:
+// `onResponderGrant` calls `_receiveSignal('RESPONDER_GRANT')` and then, when delayPressIn is 0,
+// `_receiveSignal('DELAY', event)` SYNCHRONOUSLY with that same grant event — so the event that
+// reaches onPressIn still carries `onResponderGrant`. The 150 branch is a RE-activation: the
+// finger drifted outside and came back (RESPONDER_INACTIVE_PRESS_OUT -> RESPONDER_ACTIVE_PRESS_IN,
+// driven by onResponderMove).
+//
+// Our engine dispatches pressIn from exactly ONE place — `core/engine/src/events/index.ts:391`,
+// on topTouchStart, ahead of negotiateResponder — and has no drift-back-in re-activation at all.
+// So every pressIn we produce is the grant-equivalent, and 0 is the duration that applies. Using
+// 150 (which all five adapters did until 2026-08-19) makes every tap fade in visibly slower than
+// RN.
+export const OPACITY_ACTIVE_GRANT_DURATION_MS = 0;
+// The re-activation branch. Unreachable today — kept so the constant exists when the press
+// machine grows drift-back-in, and because it is the value RN uses there.
 export const OPACITY_ACTIVE_DURATION_MS = 150;
 export const OPACITY_INACTIVE_DURATION_MS = 250;
 export const RESTING_OPACITY = 1;
 // TouchableHighlight.js: child opacity 0.85, underlay 'black' when unset.
 export const DEFAULT_HIGHLIGHT_CHILD_OPACITY = 0.85;
 export const DEFAULT_UNDERLAY_COLOR = 'black';
-// RN's Pressability DEFAULT_MIN_PRESS_DURATION, the floor a press visual is held, so a very fast
-// tap still flashes the active feedback (Pressability.js).
-export const DEFAULT_MIN_PRESS_DURATION_MS = 130;
 // RN's _deactivate floor: the press-out waits at least minPressDuration past activation (so a fast
 // tap holds the active visual) and at least delayPressOut, whichever is longer. `heldFor` is how
 // long the visual has already been active (0 when it never activated).
@@ -82,3 +99,75 @@ export function createTouchableFeedbackHandlers(config, runtime, callbacks) {
         },
     };
 }
+// ---- RN-audited additions (2026-08-19) --------------------------------------------------------
+//
+// Measured against .vendors/react-native. Everything above predates that audit and is still what
+// the React, Vue, Svelte and Angular adapters call; the names below are the RN-accurate forms and
+// are additive on purpose, so the tree stays green while each adapter migrates.
+// RN's Touchable* family OVERRIDES Pressability's own floor with 0 — TouchableOpacity.js:195,
+// TouchableHighlight.js:203 and TouchableWithoutFeedback.js all pass `minPressDuration: 0`. So
+// Pressability's own default of 130 (Pressability.js:264) reaches a Touchable in RN NEVER: what holds the active visual there is the Animated fade's own duration,
+// not a press-duration floor. Adapters defaulting minPressDuration to 130 delay every press-out by
+// an eighth of a second RN does not.
+export const TOUCHABLE_MIN_PRESS_DURATION_MS = 0;
+// RN's _getChildStyleOpacityWithDefault (TouchableOpacity.js): the fade returns to the opacity the
+// CALLER's style asks for, not to a hard 1 — a Touchable styled `opacity: 0.6` must settle back at
+// 0.6, and its Animated.Value must START there or the first paint jumps to fully opaque. `unknown`
+// in, because a style prop is an arbitrarily nested array the engine's flattenStyle resolves.
+export function restingOpacityFromStyle(style) {
+    const opacity = flattenStyle(style).opacity;
+    return typeof opacity === 'number' ? opacity : RESTING_OPACITY;
+}
+export function hasTouchablePressHandler(props) {
+    return (props.onPress != null ||
+        props.onPressIn != null ||
+        props.onPressOut != null ||
+        props.onLongPress != null);
+}
+export function createHighlightUnderlayRuntime() {
+    return { hideTimerCancel: undefined };
+}
+export function createHighlightUnderlayHandlers(config, runtime, callbacks) {
+    const { delayPressOut, hasPressHandler, schedule } = config;
+    const { setShown, onShowUnderlay, onHideUnderlay } = callbacks;
+    function clearHideTimer() {
+        if (runtime.hideTimerCancel !== undefined) {
+            runtime.hideTimerCancel();
+            runtime.hideTimerCancel = undefined;
+        }
+    }
+    function show() {
+        if (!hasPressHandler)
+            return;
+        setShown(true);
+        onShowUnderlay?.();
+    }
+    function hide() {
+        clearHideTimer();
+        if (!hasPressHandler)
+            return;
+        setShown(false);
+        onHideUnderlay?.();
+    }
+    return {
+        handlePressIn() {
+            clearHideTimer();
+            show();
+        },
+        // RN holds the underlay for delayPressOut past the tap, so a press too fast to see still
+        // flashes. The timer is what onPressOut below reads to know it must not hide yet.
+        handlePress() {
+            clearHideTimer();
+            show();
+            dlog(`TouchableHighlight underlay held ${delayPressOut}ms after press`);
+            runtime.hideTimerCancel = schedule(() => {
+                runtime.hideTimerCancel = undefined;
+                hide();
+            }, delayPressOut);
+        },
+        handlePressOut() {
+            if (runtime.hideTimerCancel === undefined)
+                hide();
+        },
+    };
+}

package/build/state/virtualized-list-diagnostics.d.ts

@@ -0,0 +1,31 @@
+export interface IListDiagnosticFrame {
+    scrollOffset: number;
+    viewportLength: number;
+    first: number;
+    last: number;
+    targetFirst: number;
+    targetLast: number;
+    count: number;
+    measuredCount: number;
+    averageLength: number;
+    averageStride: number;
+    firstOffset: number;
+    firstRaw: number | undefined;
+    total: number;
+    leadingExtent: number;
+    trailingExtent: number;
+}
+export interface IListDiagnosticMove {
+    kind: 'moved' | 'sized';
+    index: number;
+    from: number;
+    to: number;
+}
+interface IListDiagnosticHandlers {
+    onFrame?: (frame: IListDiagnosticFrame) => void;
+    onMove?: (move: IListDiagnosticMove) => void;
+}
+export declare function subscribeListDiagnostics(handlers: IListDiagnosticHandlers): () => void;
+export declare function recordListFrame(build: () => IListDiagnosticFrame): void;
+export declare function recordCellMove(kind: 'moved' | 'sized', index: number, from: number, to: number): void;
+export {};

package/build/state/virtualized-list-diagnostics.js

@@ -0,0 +1,33 @@
+// A diagnostic tap on the list's windowing state, for reading on a DEVICE. The whole class of bugs
+// this exists for — a spacer that disagrees with where the host actually laid the cells out — is
+// invisible to a headless test, because the fake reports back exactly what the model asked for. The
+// residual only exists where a real Yoga does the layout.
+//
+// Off unless something subscribes: `sink` is undefined and every record is one property read, the
+// same cost model as dlog. Nothing here is gated behind DEBUG, because the canary's HUD subscribes
+// explicitly rather than relying on an env flag surviving a Metro cache.
+// A SET, not one slot. Two subscribers overlap for real: swapping between two screens that each
+// mount a readout disposes the outgoing one AFTER the incoming one mounts, so a single slot would
+// leave the survivor unsubscribed and the readout permanently blank.
+const subscribers = new Set();
+export function subscribeListDiagnostics(handlers) {
+    subscribers.add(handlers);
+    return () => {
+        subscribers.delete(handlers);
+    };
+}
+// The frame is built through a callback so nothing is assembled while nobody is listening — the
+// snapshot reads a dozen fields off the state and would otherwise cost that on every recompute.
+export function recordListFrame(build) {
+    if (subscribers.size === 0)
+        return;
+    const frame = build();
+    for (const handlers of subscribers)
+        handlers.onFrame?.(frame);
+}
+export function recordCellMove(kind, index, from, to) {
+    if (subscribers.size === 0)
+        return;
+    for (const handlers of subscribers)
+        handlers.onMove?.({ kind, index, from, to });
+}

package/build/state/virtualized-list-reducer.d.ts

@@ -17,6 +17,19 @@ export interface IListState<ItemT> {
     scrollOffset: number;
     viewportLength: number;
     measured: Map<number, number>;
+    measuredOffsets: Map<number, number>;
+    measureVersion: number;
+    offsetsCache: {
+        count: number;
+        data: unknown;
+        getItemLayout: unknown;
+        averageLength: number;
+        averageStride: number;
+        measureVersion: number;
+        offsets: number[];
+        lengths: number[];
+        total: number;
+    } | null;
     committedWindow: {
         first: number;
         last: number;
@@ -65,6 +78,7 @@ export type IListAction<ItemT> = {
     kind: 'measure';
     index: number;
     length: number;
+    offset?: number;
 } | {
     kind: 'refresh-metrics';
 } | {

package/build/state/virtualized-list-reducer.js

@@ -18,12 +18,16 @@
 // here, so a windowing / edge / viewability / MVCP bug — and the drift between three copies of it —
 // is fixed once for all adapters.
 import { dlog } from '@symbiote-native/engine';
-import { EMPTY_OFFSET, FIRST_INDEX, NO_CONTENT_LENGTH_SENT, NO_INDEX, buildOffsets, computeEndReached, computeMvcpAdjustment, computeStartReached, computeViewableSet, computeWindow, decideEdgeReached, diffViewable, highestMeasuredIndex, indexOfItem, maxMinimumViewTime, offsetForEnd, offsetForIndex, resolveAverageLength, resolveItemKey, throttleWindow, wrapFixedLayout, } from './virtualized-list.js';
+import { EMPTY_OFFSET, FIRST_INDEX, NO_CONTENT_LENGTH_SENT, NO_INDEX, averageMeasuredStride, buildOffsets, computeEndReached, computeMvcpAdjustment, computeStartReached, computeViewableSet, computeWindow, decideEdgeReached, diffViewable, highestMeasuredIndex, indexOfItem, isSettledLayout, maxMinimumViewTime, offsetForEnd, offsetForIndex, resolveAverageLength, resolveItemKey, throttleWindow, wrapFixedLayout, } from './virtualized-list.js';
+import { recordCellMove, recordListFrame, } from './virtualized-list-diagnostics.js';
 export function createInitialListState() {
     return {
         scrollOffset: EMPTY_OFFSET,
         viewportLength: EMPTY_OFFSET,
         measured: new Map(),
+        measuredOffsets: new Map(),
+        measureVersion: 0,
+        offsetsCache: null,
         committedWindow: { first: FIRST_INDEX, last: NO_INDEX },
         sentEndForContentLength: NO_CONTENT_LENGTH_SENT,
         sentStartForContentLength: NO_CONTENT_LENGTH_SENT,
@@ -58,7 +62,34 @@ function deriveMetrics(state, inputs) {
     const count = inputs.getItemCount(inputs.data);
     const fixedLayout = wrapFixedLayout(inputs.data, inputs.getItemLayout);
     const averageLength = resolveAverageLength(fixedLayout, count, state.measured);
-    const { offsets, lengths, total } = buildOffsets(count, state.measured, fixedLayout, averageLength);
+    const averageStride = averageMeasuredStride(state.measuredOffsets, averageLength);
+    // Every input buildOffsets reads, compared before paying for it again. `data` and
+    // `getItemLayout` stand in for `fixedLayout`, which wrapFixedLayout mints fresh on every call
+    // and whose identity therefore means nothing.
+    const cached = state.offsetsCache;
+    const reusable = cached !== null &&
+        cached.count === count &&
+        cached.data === inputs.data &&
+        cached.getItemLayout === inputs.getItemLayout &&
+        cached.averageLength === averageLength &&
+        cached.averageStride === averageStride &&
+        cached.measureVersion === state.measureVersion;
+    const { offsets, lengths, total } = reusable
+        ? cached
+        : buildOffsets(count, state.measured, state.measuredOffsets, fixedLayout, averageLength, averageStride);
+    if (!reusable) {
+        state.offsetsCache = {
+            count,
+            data: inputs.data,
+            getItemLayout: inputs.getItemLayout,
+            averageLength,
+            averageStride,
+            measureVersion: state.measureVersion,
+            offsets,
+            lengths,
+            total,
+        };
+    }
     const target = computeWindow(count, offsets, lengths, state.scrollOffset, state.viewportLength, inputs.windowSize, inputs.initialNumToRender);
     const throttled = throttleWindow(target, state.committedWindow, inputs.maxToRenderPerBatch);
     state.committedWindow = throttled;
@@ -73,6 +104,29 @@ function deriveMetrics(state, inputs) {
         averageLength,
         fixedLayout,
     };
+    recordListFrame(() => ({
+        scrollOffset: state.scrollOffset,
+        viewportLength: state.viewportLength,
+        first: throttled.first,
+        last: throttled.last,
+        targetFirst: target.first,
+        targetLast: target.last,
+        count,
+        measuredCount: state.measured.size,
+        averageLength,
+        averageStride: averageMeasuredStride(state.measuredOffsets, averageLength),
+        firstOffset: offsets[throttled.first] ?? EMPTY_OFFSET,
+        firstRaw: state.measuredOffsets.get(throttled.first),
+        total,
+        leadingExtent: throttled.first > FIRST_INDEX
+            ? offsets[throttled.first - 1] +
+                lengths[throttled.first - 1] -
+                offsets[FIRST_INDEX]
+            : EMPTY_OFFSET,
+        trailingExtent: throttled.last < count - 1
+            ? total - offsets[throttled.last + 1]
+            : EMPTY_OFFSET,
+    }));
     return state;
 }
 function keyForOf(inputs) {
@@ -82,13 +136,61 @@ function keyForOf(inputs) {
 // (batch-fill -> end -> start -> viewability -> initial-scroll -> MVCP). Each is guarded by its own
 // dedup state (sent*ForContentLength, lastViewable, appliedInitialScroll, firstVisibleKey), so
 // running commit on every render is safe — the guards prevent a redundant fire.
+// Reclassify the rendered cells and, if the viewable set changed, hand the adapter an info payload
+// to fire (after minimumViewTime, if any). lastViewable is folded back only when the fire actually
+// lands (the 'viewable-fired' action), so a debounce superseded mid-flight still diffs against the
+// last COMMITTED set.
+//
+// Extracted from commitList because 'record-interaction' needs the same pass: RN's
+// recordInteraction() ungates waitForInteraction and calls _updateViewableItems immediately
+// (VirtualizedList.js ~288-296). Leaving the pass inline meant a list that fits its viewport and is
+// never scrolled reported nothing at all after the interaction — the next commit that would have
+// carried the report never came.
+function viewabilityEffects(state, inputs) {
+    const m = state.metrics;
+    if (inputs.viewabilityPairs.length === EMPTY_OFFSET ||
+        state.viewportLength === EMPTY_OFFSET ||
+        m.count === FIRST_INDEX) {
+        return [];
+    }
+    const { tokens, map } = computeViewableSet({
+        first: m.first,
+        last: m.last,
+        count: m.count,
+        offsets: m.offsets,
+        lengths: m.lengths,
+        scrollOffset: state.scrollOffset,
+        viewportLength: state.viewportLength,
+        data: inputs.data,
+        getItem: inputs.getItem,
+        keyExtractor: inputs.keyExtractor,
+        pairs: inputs.viewabilityPairs,
+        hasInteracted: state.hasInteracted,
+    });
+    const diff = diffViewable(state.lastViewable, map, tokens);
+    if (!diff.hasChanged)
+        return [];
+    dlog(`VirtualizedList viewable=${tokens.length} changed=${diff.changed.length} ` +
+        `(window [${m.first}, ${m.last}])`);
+    return [
+        {
+            kind: 'fire-viewable',
+            info: { viewableItems: tokens, changed: diff.changed },
+            delay: maxMinimumViewTime(inputs.viewabilityPairs),
+            map,
+        },
+    ];
+}
 function commitList(state, inputs) {
     const effects = [];
     const m = state.metrics;
     // Batch fill: when the throttled window has not reached the target, ask for another render tick so
     // it keeps filling toward target (RN's incremental fill).
     if (!(m.first <= m.target.first && m.last >= m.target.last)) {
-        effects.push({ kind: 'schedule-refill', delay: inputs.updateCellsBatchingPeriod });
+        effects.push({
+            kind: 'schedule-refill',
+            delay: inputs.updateCellsBatchingPeriod,
+        });
     }
     // onEndReached: fire only when the actual last cell is rendered AND within threshold; dedup by
     // content length; re-arm on scroll away from the end (RN _maybeCallOnEdgeReached).
@@ -123,39 +225,7 @@ function commitList(state, inputs) {
             effects.push({ kind: 'fire-start-reached', distanceFromStart });
         }
     }
-    // Viewability: reclassify the rendered cells; if the viewable set changed, hand the adapter an
-    // info payload to fire (after minimumViewTime, if any). lastViewable is folded back only when the
-    // fire actually lands (the 'viewable-fired' action), so a debounce that is superseded mid-flight
-    // still diffs against the last COMMITTED set.
-    if (inputs.viewabilityPairs.length > EMPTY_OFFSET &&
-        state.viewportLength > EMPTY_OFFSET &&
-        m.count !== FIRST_INDEX) {
-        const { tokens, map } = computeViewableSet({
-            first: m.first,
-            last: m.last,
-            count: m.count,
-            offsets: m.offsets,
-            lengths: m.lengths,
-            scrollOffset: state.scrollOffset,
-            viewportLength: state.viewportLength,
-            data: inputs.data,
-            getItem: inputs.getItem,
-            keyExtractor: inputs.keyExtractor,
-            pairs: inputs.viewabilityPairs,
-            hasInteracted: state.hasInteracted,
-        });
-        const diff = diffViewable(state.lastViewable, map, tokens);
-        if (diff.hasChanged) {
-            dlog(`VirtualizedList viewable=${tokens.length} changed=${diff.changed.length} ` +
-                `(window [${m.first}, ${m.last}])`);
-            effects.push({
-                kind: 'fire-viewable',
-                info: { viewableItems: tokens, changed: diff.changed },
-                delay: maxMinimumViewTime(inputs.viewabilityPairs),
-                map,
-            });
-        }
-    }
+    effects.push(...viewabilityEffects(state, inputs));
     // initialScrollIndex: once the first viewport is known, jump to that index a single time.
     if (inputs.initialScrollIndex !== undefined &&
         !state.appliedInitialScroll &&
@@ -183,7 +253,11 @@ function commitList(state, inputs) {
         effects.push({ kind: 'scroll-to', offset: EMPTY_OFFSET, animated: true });
     }
     else if (mvcp.action.kind === 'shift') {
-        effects.push({ kind: 'scroll-to', offset: mvcp.action.offset, animated: false });
+        effects.push({
+            kind: 'scroll-to',
+            offset: mvcp.action.offset,
+            animated: false,
+        });
     }
     state.firstVisibleKey = mvcp.firstVisibleKey;
     return { state, effects, changed: false };
@@ -192,6 +266,25 @@ function commitList(state, inputs) {
 // target is past the last measured cell (RN VirtualizedList.js), else scroll to the resolved offset.
 function resolveScrollToIndex(state, inputs, action) {
     const m = state.metrics;
+    // Range check FIRST, mirroring RN VirtualizedList.js (~165-178) invariant-for-invariant. Three
+    // separate messages rather than one, because an empty list and an index past the end are
+    // different diagnoses. It has to precede the onScrollToIndexFailed branch below, or an
+    // out-of-range index on a list without getItemLayout would be reported as a MEASUREMENT problem
+    // and send the reader to inspect cell layout for what is a caller bug.
+    //
+    // Note this is the one place the range is enforced: offsetForIndex() still CLAMPS, and must, since
+    // scrollToEnd and initialScrollIndex resolve through it with indices that are legitimately at or
+    // past the edge.
+    const itemCount = inputs.getItemCount(inputs.data);
+    if (action.index < FIRST_INDEX) {
+        throw new Error(`scrollToIndex out of range: requested index ${action.index} but minimum is 0`);
+    }
+    if (itemCount < 1) {
+        throw new Error(`scrollToIndex out of range: item length ${itemCount} but minimum is 1`);
+    }
+    if (action.index >= itemCount) {
+        throw new Error(`scrollToIndex out of range: requested index ${action.index} is out of 0 to ${itemCount - 1}`);
+    }
     const measuredCeiling = highestMeasuredIndex(state.measured);
     if (inputs.getItemLayout === undefined && action.index > measuredCeiling) {
         dlog(`VirtualizedList onScrollToIndexFailed index=${action.index} ` +
@@ -230,26 +323,61 @@ export function reduceList(state, action, inputs) {
             state.scrollOffset = action.offset;
             return { state, effects: [], changed: true };
         case 'layout':
+            // Same settling rule as a cell measurement: the scroll host re-reports its own size after
+            // every relayout, and a re-derive off noise in its last bits drives the same loop.
+            if (isSettledLayout(state.viewportLength, action.length))
+                return { state, effects: [], changed: false };
             state.viewportLength = action.length;
             return { state, effects: [], changed: true };
-        case 'measure':
-            // A fixed getItemLayout owns cell sizes, so a measured length is ignored; a repeat of a known
-            // length changes nothing. Both guards keep an idle onLayout from forcing a render.
+        case 'measure': {
+            // A fixed getItemLayout owns cell sizes, so a measured length is ignored.
             if (inputs.getItemLayout !== undefined)
                 return { state, effects: [], changed: false };
-            if (state.measured.get(action.index) === action.length) {
+            const knownLength = state.measured.get(action.index);
+            const knownOffset = state.measuredOffsets.get(action.index);
+            const lengthSettled = isSettledLayout(knownLength, action.length);
+            const offsetSettled = action.offset === undefined ||
+                isSettledLayout(knownOffset, action.offset);
+            // Settled means "the same measurement, re-reported" — an idle onLayout, or the float noise a
+            // relayout leaves behind. Bail WITHOUT storing: keeping the settled value byte-identical is
+            // the half that matters, because the spacer derived from it then stops moving too and the
+            // relayout loop has nothing left to feed on (see LAYOUT_EPSILON).
+            if (lengthSettled && offsetSettled)
                 return { state, effects: [], changed: false };
+            // Each half is stored only if IT moved: a cell that slid without resizing must not have its
+            // length rewritten with a noisier reading of the same number.
+            if (!lengthSettled) {
+                if (knownLength !== undefined)
+                    recordCellMove('sized', action.index, knownLength, action.length);
+                state.measured.set(action.index, action.length);
+                state.measureVersion += 1;
+            }
+            if (action.offset !== undefined && !offsetSettled) {
+                if (knownOffset !== undefined)
+                    recordCellMove('moved', action.index, knownOffset, action.offset);
+                state.measuredOffsets.set(action.index, action.offset);
+                state.measureVersion += 1;
             }
-            state.measured.set(action.index, action.length);
             return { state, effects: [], changed: true };
+        }
         case 'batch-tick':
             // The refill timer fired: ask for a render, whose refresh-metrics grows the window one step.
             return { state, effects: [], changed: true };
         case 'refresh-metrics':
-            return { state: deriveMetrics(state, inputs), effects: [], changed: true };
+            return {
+                state: deriveMetrics(state, inputs),
+                effects: [],
+                changed: true,
+            };
         case 'record-interaction':
+            // The flag flip must land BEFORE the pass — computeViewableSet reads hasInteracted to decide
+            // whether a waitForInteraction pair is still gated.
             state.hasInteracted = true;
-            return { state, effects: [], changed: false };
+            return {
+                state,
+                effects: viewabilityEffects(state, inputs),
+                changed: false,
+            };
         case 'viewable-fired':
             state.lastViewable = action.map;
             return { state, effects: [], changed: false };
@@ -258,7 +386,13 @@ export function reduceList(state, action, inputs) {
         case 'scroll-to-offset':
             return {
                 state,
-                effects: [{ kind: 'scroll-to', offset: action.offset, animated: action.animated }],
+                effects: [
+                    {
+                        kind: 'scroll-to',
+                        offset: action.offset,
+                        animated: action.animated,
+                    },
+                ],
                 changed: false,
             };
         case 'scroll-to-index':