@symbiote-native/components 0.2.6 → 0.4.0

package/build/index.d.ts

@@ -12,12 +12,14 @@ export type { ISwitchProps, ISwitchViewProps, ISwitchPlatform, ISwitchTrackColor
 export type { IResponderProps } from './responder-props';
 export { switchReducer, createInitialSwitchState, shouldSnapBack, valueFromChange, } from './state/switch';
 export type { ISwitchState, ISwitchAction } from './state/switch';
-export { resolveDecelerationRate, selectScrollIntrinsics, readLayoutDimension, didContentSizeChange, SCROLL_VIEW_BASE_HORIZONTAL, SCROLL_VIEW_BASE_VERTICAL, } from './view/render-scroll-view';
-export type { IScrollIntrinsics, IContentSize } from './view/render-scroll-view';
+export { resolveDecelerationRate, selectScrollIntrinsics, readLayoutDimension, didContentSizeChange, resolveScrollForwarding, SCROLL_VIEW_BASE_HORIZONTAL, SCROLL_VIEW_BASE_VERTICAL, } from './view/render-scroll-view';
+export type { IScrollIntrinsics, IContentSize, IScrollForwarding, IScrollForwardingInputs, IScrollForwardMode, } from './view/render-scroll-view';
 export { buildScrollViewHandle, splitLayoutProps, attachStickyScroll, isSymbioteEvent, forwardScrollEvent, } from './scroll-view-commands';
 export type { IScrollViewHandle } from './scroll-view-commands';
 export { computeStickyInterpolation, nextStickyHeaderY, stickyDebounceMs, readLayoutNumber, STICKY_HEADER_Z_INDEX, } from './view/render-scroll-sticky';
 export type { IStickyHeaderProps, IStickyInterpolationParams } from './view/render-scroll-sticky';
+export { reduceSticky, createInitialStickyState, stickyEffectSignature, } from './state/sticky-header-reducer';
+export type { IStickyHeaderState, IStickyReducerInputs, IStickyAction, IStickyEffect, IStickyReduceResult, } from './state/sticky-header-reducer';
 export type { IImageSource, IImageSourceProp, IResizeMode, IImageProps, IImageViewProps, } from './view/render-image';
 export { renderImage } from './view/render-image';
 export type { IImageStatics, IImageSize, IImageCacheStatus } from '@symbiote-native/engine';
@@ -35,8 +37,9 @@ export type { IKeyboardAvoidingBehavior, IMeasuredFrame, IKeyboardFrame, IKeyboa
 export { createPressHandlers, createPressRuntime, normalizeRect, maxEdge, isTouchWithinRegion, readPoint, computeRegion, rippleProps, DEFAULT_DELAY_LONG_PRESS_MS, DEFAULT_PRESS_RECT_OFFSETS, } from './state/pressable';
 export type { IPressState, IPressHandler, IPressHandlers, IPressHost, IPressRuntime, IPressMachineConfig, IFrameCallback, IRectOffset, IEdgeInsets, IResponderRegion, IPressableAndroidRippleConfig, IRippleBackground as IPressableRippleBackground, } from './state/pressable';
 export { buildPressableListeners, resolveDisabledAccessibilityState, noteHoverNoop, shouldSuppressPress, shouldClaimResponder, isTerminationAllowed, } from './view/render-pressable';
-export { computePressOutWait, DEFAULT_ACTIVE_OPACITY, OPACITY_ACTIVE_DURATION_MS, OPACITY_INACTIVE_DURATION_MS, RESTING_OPACITY, DEFAULT_HIGHLIGHT_CHILD_OPACITY, DEFAULT_UNDERLAY_COLOR, DEFAULT_MIN_PRESS_DURATION_MS, } from './state/touchable';
-export type { IPressTimingProps, ITouchableHandler } from './state/touchable';
+export { computePressOutWait, createTouchableFeedbackRuntime, createTouchableFeedbackHandlers, DEFAULT_ACTIVE_OPACITY, OPACITY_ACTIVE_DURATION_MS, OPACITY_INACTIVE_DURATION_MS, RESTING_OPACITY, DEFAULT_HIGHLIGHT_CHILD_OPACITY, DEFAULT_UNDERLAY_COLOR, DEFAULT_MIN_PRESS_DURATION_MS, } from './state/touchable';
+export type { IPressTimingProps, ITouchableHandler, ITouchableFeedbackRuntime, ITouchableFeedbackConfig, ITouchableFeedbackCallbacks, ITouchableFeedbackHandlers, } from './state/touchable';
+export { highlightPressedStyle } from './view/render-touchable-highlight';
 export { backgroundProps, canUseNativeForeground, selectableBackground, selectableBackgroundBorderless, rippleBackground, } from './view/render-touchable-native-feedback';
 export type { INativeFeedbackBackground, IThemeAttrBackground, IRippleBackground, } from './view/render-touchable-native-feedback';
 export { BUTTON_ACCESSIBILITY_ROLE, buttonTextStyle, resolveButtonTextStyle, } from './view/render-button';
@@ -45,8 +48,10 @@ export { resolveTextInputProps, foldText, foldAutoComplete, foldSubmitBehavior,
 export type { ITextInputProps, ITextInputHandle, ITextInputSelection, ITextInputEventHandler, ITextInputFoldInput, IFoldedTextInputProps, IInputMode, IEnterKeyHint, ISubmitBehavior, } from './state/text-input';
 export { renderTextInput } from './view/render-text-input';
 export type { ITextInputViewProps } from './view/render-text-input';
-export { DEFAULT_WINDOW_SIZE, DEFAULT_INITIAL_NUM_TO_RENDER, DEFAULT_END_REACHED_THRESHOLD, DEFAULT_MAX_TO_RENDER_PER_BATCH, DEFAULT_UPDATE_CELLS_BATCHING_PERIOD, DEFAULT_VIEW_AREA_COVERAGE_PERCENT_THRESHOLD, DEFAULT_START_REACHED_THRESHOLD, FIRST_INDEX, EMPTY_OFFSET, NO_INDEX, NO_CONTENT_LENGTH_SENT, INVERTED_Y_STYLE, INVERTED_X_STYLE, readScrollOffset, readLayoutLength, buildOffsets, computeWindow, throttleWindow, visiblePercent, isCellViewable, offsetForIndex, averageMeasuredLength, highestMeasuredIndex, computeEndReached, computeStartReached, buildViewabilityPairs, computeViewableSet, diffViewable, maxMinimumViewTime, buildListPlan, } from './state/virtualized-list';
-export type { ICellLayout, ISeparators, ISeparatorProps, IViewToken, IViewableItemsChangedInfo, IViewabilityConfig, IViewabilityConfigCallbackPair, IVirtualizedListHandle, IViewableSetParams, IListCellPlan, IListPlan, IListPlanParams, } from './state/virtualized-list';
+export { DEFAULT_WINDOW_SIZE, DEFAULT_INITIAL_NUM_TO_RENDER, DEFAULT_END_REACHED_THRESHOLD, DEFAULT_MAX_TO_RENDER_PER_BATCH, DEFAULT_UPDATE_CELLS_BATCHING_PERIOD, DEFAULT_VIEW_AREA_COVERAGE_PERCENT_THRESHOLD, DEFAULT_START_REACHED_THRESHOLD, FIRST_INDEX, EMPTY_OFFSET, NO_INDEX, NO_CONTENT_LENGTH_SENT, INVERTED_Y_STYLE, INVERTED_X_STYLE, readScrollOffset, readLayoutLength, buildOffsets, computeWindow, throttleWindow, visiblePercent, isCellViewable, offsetForIndex, averageMeasuredLength, highestMeasuredIndex, computeEndReached, computeStartReached, buildViewabilityPairs, computeViewableSet, diffViewable, maxMinimumViewTime, buildListPlan, computeMvcpAdjustment, resolveItemKey, indexOfItem, offsetForEnd, isSeparatorGapInRange, decideEdgeReached, resolveStickySectionHeaders, wrapFixedLayout, resolveAverageLength, } from './state/virtualized-list';
+export type { IMvcpAction, IMvcpAdjustmentParams, IMvcpAdjustmentResult, ICellLayout, ISeparators, ISeparatorProps, IViewToken, IViewableItemsChangedInfo, IViewabilityConfig, IViewabilityConfigCallbackPair, IVirtualizedListHandle, IViewableSetParams, IListCellPlan, IListPlan, IListPlanParams, } from './state/virtualized-list';
+export { reduceList, createInitialListState, listEffectSignature, } from './state/virtualized-list-reducer';
+export type { IListState, IListMetrics, IListReducerInputs, IListAction, IListEffect, IListReduceResult, } from './state/virtualized-list-reducer';
 export { SINGLE_COLUMN, chunkIntoRows, rowKeyExtractor, expandRowToken, expandRowViewability, lastItemOfRow, firstItemOfRow, } from './state/flat-list';
 export type { IRow } from './state/flat-list';
 export { flattenSections, unwrapEntryItem, sectionEntryKey, scrollLocationToFlatIndex, } from './state/section-list';

package/build/index.js

@@ -21,9 +21,14 @@ export { switchReducer, createInitialSwitchState, shouldSnapBack, valueFromChang
 // ScrollView: pure render/command helpers (no state machine, no 3-layer split). The adapter
 // owns the refs/effects/element assembly and the sticky-header component; these supply the
 // platform-invariant math and plumbing every adapter shares.
-export { resolveDecelerationRate, selectScrollIntrinsics, readLayoutDimension, didContentSizeChange, SCROLL_VIEW_BASE_HORIZONTAL, SCROLL_VIEW_BASE_VERTICAL, } from './view/render-scroll-view.js';
+export { resolveDecelerationRate, selectScrollIntrinsics, readLayoutDimension, didContentSizeChange, resolveScrollForwarding, SCROLL_VIEW_BASE_HORIZONTAL, SCROLL_VIEW_BASE_VERTICAL, } from './view/render-scroll-view.js';
 export { buildScrollViewHandle, splitLayoutProps, attachStickyScroll, isSymbioteEvent, forwardScrollEvent, } from './scroll-view-commands.js';
 export { computeStickyInterpolation, nextStickyHeaderY, stickyDebounceMs, readLayoutNumber, STICKY_HEADER_Z_INDEX, } from './view/render-scroll-sticky.js';
+// The per-header sticky effect machine: the one pure state machine every sticky-header consumer drives
+// (React/Vue header component, Angular header component, Angular projection wrapper), folding the
+// zero-swallow gate + debounce-delay pick + rebuild-on-input-change decision out of each adapter's
+// reactive glue. The adapter maps events to actions and executes the effects with its own primitives.
+export { reduceSticky, createInitialStickyState, stickyEffectSignature, } from './state/sticky-header-reducer.js';
 export { renderImage } from './view/render-image/index.js';
 export { imageStatics, setImageSourceResolver } from '@symbiote-native/engine';
 // ImageBackground: render-only composition (absolute-fill image behind, children on top).
@@ -43,7 +48,8 @@ export { createPressHandlers, createPressRuntime, normalizeRect, maxEdge, isTouc
 export { buildPressableListeners, resolveDisabledAccessibilityState, noteHoverNoop, shouldSuppressPress, shouldClaimResponder, isTerminationAllowed, } from './view/render-pressable/index.js';
 // Touchable*: shared press-timing constants + the deactivation-floor math (the Animated feedback
 // itself stays per-adapter), and TouchableNativeFeedback's pure static factories + background map.
-export { computePressOutWait, DEFAULT_ACTIVE_OPACITY, OPACITY_ACTIVE_DURATION_MS, OPACITY_INACTIVE_DURATION_MS, RESTING_OPACITY, DEFAULT_HIGHLIGHT_CHILD_OPACITY, DEFAULT_UNDERLAY_COLOR, DEFAULT_MIN_PRESS_DURATION_MS, } from './state/touchable.js';
+export { computePressOutWait, createTouchableFeedbackRuntime, createTouchableFeedbackHandlers, DEFAULT_ACTIVE_OPACITY, OPACITY_ACTIVE_DURATION_MS, OPACITY_INACTIVE_DURATION_MS, RESTING_OPACITY, DEFAULT_HIGHLIGHT_CHILD_OPACITY, DEFAULT_UNDERLAY_COLOR, DEFAULT_MIN_PRESS_DURATION_MS, } from './state/touchable.js';
+export { highlightPressedStyle } from './view/render-touchable-highlight.js';
 export { backgroundProps, canUseNativeForeground, selectableBackground, selectableBackgroundBorderless, rippleBackground, } from './view/render-touchable-native-feedback.js';
 // Button: shared base text style, role constant, and color fold (the adapter composes its own
 // TouchableOpacity + Text).
@@ -59,6 +65,10 @@ export { renderTextInput } from './view/render-text-input.js';
 // have NO view/render-*.ts (the cell content is the framework's own children, so there is
 // no Descriptor render fn) — the shared layer for lists is this STATE/logic, reused
 // verbatim by React and Vue.
-export { DEFAULT_WINDOW_SIZE, DEFAULT_INITIAL_NUM_TO_RENDER, DEFAULT_END_REACHED_THRESHOLD, DEFAULT_MAX_TO_RENDER_PER_BATCH, DEFAULT_UPDATE_CELLS_BATCHING_PERIOD, DEFAULT_VIEW_AREA_COVERAGE_PERCENT_THRESHOLD, DEFAULT_START_REACHED_THRESHOLD, FIRST_INDEX, EMPTY_OFFSET, NO_INDEX, NO_CONTENT_LENGTH_SENT, INVERTED_Y_STYLE, INVERTED_X_STYLE, readScrollOffset, readLayoutLength, buildOffsets, computeWindow, throttleWindow, visiblePercent, isCellViewable, offsetForIndex, averageMeasuredLength, highestMeasuredIndex, computeEndReached, computeStartReached, buildViewabilityPairs, computeViewableSet, diffViewable, maxMinimumViewTime, buildListPlan, } from './state/virtualized-list.js';
+export { DEFAULT_WINDOW_SIZE, DEFAULT_INITIAL_NUM_TO_RENDER, DEFAULT_END_REACHED_THRESHOLD, DEFAULT_MAX_TO_RENDER_PER_BATCH, DEFAULT_UPDATE_CELLS_BATCHING_PERIOD, DEFAULT_VIEW_AREA_COVERAGE_PERCENT_THRESHOLD, DEFAULT_START_REACHED_THRESHOLD, FIRST_INDEX, EMPTY_OFFSET, NO_INDEX, NO_CONTENT_LENGTH_SENT, INVERTED_Y_STYLE, INVERTED_X_STYLE, readScrollOffset, readLayoutLength, buildOffsets, computeWindow, throttleWindow, visiblePercent, isCellViewable, offsetForIndex, averageMeasuredLength, highestMeasuredIndex, computeEndReached, computeStartReached, buildViewabilityPairs, computeViewableSet, diffViewable, maxMinimumViewTime, buildListPlan, computeMvcpAdjustment, resolveItemKey, indexOfItem, offsetForEnd, isSeparatorGapInRange, decideEdgeReached, resolveStickySectionHeaders, wrapFixedLayout, resolveAverageLength, } from './state/virtualized-list.js';
+// The orchestration reducer: the one pure state machine every list adapter drives, folding the
+// after-commit effect skeleton (window recompute -> edge -> viewability -> initial-scroll -> MVCP)
+// out of each adapter's reactive glue. The adapter maps events to actions and runs the effects.
+export { reduceList, createInitialListState, listEffectSignature, } from './state/virtualized-list-reducer.js';
 export { SINGLE_COLUMN, chunkIntoRows, rowKeyExtractor, expandRowToken, expandRowViewability, lastItemOfRow, firstItemOfRow, } from './state/flat-list.js';
 export { flattenSections, unwrapEntryItem, sectionEntryKey, scrollLocationToFlatIndex, } from './state/section-list.js';

package/build/scroll-view-commands.js

@@ -116,5 +116,9 @@ export function attachStickyScroll(node, value) {
     const attachment = attachNativeEvent(node, 'onScroll', [
         { nativeEvent: { contentOffset: { y: value } } },
     ]);
-    return () => attachment.detach();
+    dlog(`STICKY[attach] attachStickyScroll onScroll -> value#${value.__getNativeTag?.() ?? 'js'}`);
+    return () => {
+        dlog('STICKY[attach] attachStickyScroll detached');
+        attachment.detach();
+    };
 }

package/build/state/sticky-header-reducer.d.ts

@@ -0,0 +1,54 @@
+export interface IStickyHeaderState {
+    measured: boolean;
+    layoutY: number;
+    layoutHeight: number;
+    translateY: number | null;
+    haveReceivedInitialZeroTranslateY: boolean;
+    inputRange: number[];
+    outputRange: number[];
+    rangesEmitted: boolean;
+}
+export interface IStickyReducerInputs {
+    os: string;
+    inverted: boolean | undefined;
+    scrollViewHeight: number | undefined;
+    nextHeaderLayoutY: number | undefined;
+    index?: number;
+}
+export type IStickyAction = {
+    kind: 'layout';
+    y: number;
+    height: number;
+} | {
+    kind: 'inputs-changed';
+} | {
+    kind: 'animated-tick';
+    value: number;
+} | {
+    kind: 'debounce-fired';
+    value: number;
+};
+export type IStickyEffect = {
+    kind: 'rebuild-interpolation';
+    inputRange: number[];
+    outputRange: number[];
+} | {
+    kind: 'schedule-debounce';
+    delay: number;
+    value: number;
+} | {
+    kind: 'apply-passthrough';
+    translateY: number;
+} | {
+    kind: 'record-header-y';
+    index: number;
+    y: number;
+};
+export interface IStickyReduceResult {
+    state: IStickyHeaderState;
+    effects: IStickyEffect[];
+    changed: boolean;
+}
+export declare function createInitialStickyState(): IStickyHeaderState;
+export declare function stickyEffectSignature(state: IStickyHeaderState): string;
+export declare function reduceSticky(state: IStickyHeaderState, action: IStickyAction, inputs: IStickyReducerInputs): IStickyReduceResult;

package/build/state/sticky-header-reducer.js

@@ -0,0 +1,183 @@
+// Sticky-header effect machine: the framework-agnostic STATE MACHINE that folds every per-adapter
+// sticky-header effect skeleton into one place. Before this, each adapter (React useState/useEffect,
+// Vue refs/watchEffect, Angular fields/ngOnChanges — and, in Angular, a SECOND copy inside the
+// projection wrapper) re-wrote the same per-header sequence — gate the freshly-rebuilt
+// interpolation's spurious zero, debounce the settled translateY, rebuild the top/inverted ranges on
+// a layout/collision-input change — in its own reactive dialect, so the zero-swallow gate, the
+// debounce-delay pick, and the rebuild decision lived FOUR times and quietly drifted.
+//
+// Here the whole decision half is one pure `reduceSticky(state, action, inputs) -> {state, effects}`,
+// PER sticky header. The adapter keeps only what is genuinely framework-bound: translate a native
+// event / animated tick / timer fire into an ACTION, hold ONE state cell, and EXECUTE the returned
+// EFFECTS with its own primitives (build the interpolation node + wire addListener/removeListener,
+// hold the debounce setTimeout, trigger its own re-render, record the cross-talk y). The math leaf
+// (computeStickyInterpolation) and the debounce-window pick (stickyDebounceMs) still live in
+// ./view/render-scroll-sticky; this module composes them into the ordered transition every adapter
+// shares. Ported from ScrollViewStickyHeader.js's effect.
+import { dlog } from '@symbiote-native/engine';
+import { computeStickyInterpolation, stickyDebounceMs } from '../view/render-scroll-sticky.js';
+// The un-measured identity interpolation (RN: a fresh AnimatedInterpolation before the header has
+// measured its own y/height). Kept as the reset the initial state and every rebuild start from.
+const IDENTITY_INPUT_RANGE = [-1, 0];
+const IDENTITY_OUTPUT_RANGE = [0, 0];
+const NO_TRANSLATE = null;
+export function createInitialStickyState() {
+    return {
+        measured: false,
+        layoutY: 0,
+        layoutHeight: 0,
+        translateY: NO_TRANSLATE,
+        haveReceivedInitialZeroTranslateY: true,
+        inputRange: [...IDENTITY_INPUT_RANGE],
+        outputRange: [...IDENTITY_OUTPUT_RANGE],
+        rangesEmitted: false,
+    };
+}
+// A cheap signature over the render-relevant state (the ranges + the committed translateY). The
+// adapter can skip re-wiring when it is unchanged. Shared so the key CANNOT drift between adapters.
+export function stickyEffectSignature(state) {
+    return `${state.inputRange.join(',')}|${state.outputRange.join(',')}|${state.translateY}`;
+}
+function arraysEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return a.every((value, index) => value === b[index]);
+}
+// Recompute the derived interpolation ranges off the current state + inputs (wrapping the load-bearing
+// computeStickyInterpolation math), store them, and return them for the rebuild effect.
+function deriveRanges(state, inputs) {
+    const { inputRange, outputRange } = computeStickyInterpolation({
+        measured: state.measured,
+        inverted: inputs.inverted,
+        scrollViewHeight: inputs.scrollViewHeight,
+        layoutY: state.layoutY,
+        layoutHeight: state.layoutHeight,
+        nextHeaderLayoutY: inputs.nextHeaderLayoutY,
+    });
+    state.inputRange = inputRange;
+    state.outputRange = outputRange;
+    return { inputRange, outputRange };
+}
+// The single transition every sticky-header adapter shares. The adapter maps a native event / animated
+// tick / timer fire to an action, calls this, stores the returned state, and executes the effects.
+// DIAGNOSTIC-only, gated: identifies which header instance a log line belongs to across a
+// device dump without needing full state dumps at every call — layoutY doubles as a stable
+// per-header id once measured (0 before the first layout).
+function headerTag(state) {
+    return `y=${state.layoutY}`;
+}
+export function reduceSticky(state, action, inputs) {
+    dlog(`STICKY[reducer ${headerTag(state)}] action=${action.kind}` +
+        (action.kind === 'layout' ? ` y=${action.y} height=${action.height}` : '') +
+        (action.kind === 'animated-tick' || action.kind === 'debounce-fired'
+            ? ` value=${action.value}`
+            : '') +
+        ` inputs={inverted=${inputs.inverted} scrollViewHeight=${inputs.scrollViewHeight} nextHeaderLayoutY=${inputs.nextHeaderLayoutY}}`);
+    switch (action.kind) {
+        case 'layout': {
+            // Record own y/height, mark measured, rebuild the interpolation, and (when the reducer owns the
+            // cross-talk index) hand the parent this header's y so the PREVIOUS header learns its collision
+            // point. Matches RN ScrollViewStickyHeader.js._onLayout.
+            //
+            // Redundant-geometry guard: Yoga legitimately re-fires onLayout with the SAME y/height (relayout
+            // passes triggered by an unrelated sibling, a native-driven prop commit, ...) — every consumer
+            // must tolerate that. React's port gets this guard for FREE: `setLayoutY(sameValue)` is a no-op
+            // (React bails out of re-rendering on an unchanged primitive), so a redundant onLayout never
+            // reaches the rebuild `useEffect`. This reducer has no such implicit bail-out, so it must skip
+            // the rebuild explicitly — device-confirmed (2026-08-13) that omitting this guard lets a
+            // native-driven rebuild (fresh AnimatedProps/AnimatedStyle graph, fresh native connect) commit a
+            // fresh prop identity on every redundant layout, which can itself provoke another relayout pass —
+            // an unbounded same-tick rebuild ping-pong that trips Svelte's effect_update_depth_exceeded guard.
+            const alreadyAtThisGeometry = state.measured && state.layoutY === action.y && state.layoutHeight === action.height;
+            state.layoutY = action.y;
+            state.layoutHeight = action.height;
+            state.measured = true;
+            const effects = [];
+            if (inputs.index !== undefined) {
+                effects.push({ kind: 'record-header-y', index: inputs.index, y: action.y });
+            }
+            if (alreadyAtThisGeometry && state.rangesEmitted) {
+                dlog(`STICKY[reducer ${headerTag(state)}] layout: redundant geometry, skipped rebuild`);
+                return { state, effects, changed: effects.length > 0 };
+            }
+            const { inputRange, outputRange } = deriveRanges(state, inputs);
+            state.rangesEmitted = true;
+            dlog(`STICKY[reducer ${headerTag(state)}] layout: measured=true inputRange=${JSON.stringify(inputRange)} ` +
+                `outputRange=${JSON.stringify(outputRange)}`);
+            effects.push({ kind: 'rebuild-interpolation', inputRange, outputRange });
+            return { state, effects, changed: true };
+        }
+        case 'inputs-changed': {
+            // A collision/viewport input changed (RN effect deps: inverted, scrollViewHeight,
+            // nextHeaderLayoutY): recompute the ranges and rebuild.
+            //
+            // Redundant-ranges guard (sibling of 'layout's `alreadyAtThisGeometry` above, same root
+            // cause): the adapter's own mount `$effect` re-dispatches 'inputs-changed' whenever its
+            // `inverted`/`scrollViewHeight`/`nextHeaderLayoutY` derived values re-evaluate — which can
+            // happen on an unrelated parent re-render (e.g. VirtualizedList re-deriving
+            // `nextHeaderLayoutYFor(cell.index)` off its cross-talk Map on every reactive pass) even when
+            // the COMPUTED value is identical. React gets no implicit protection here either (this is a
+            // real `useEffect` with real deps), but RN's own deps array only fires on an ACTUAL primitive
+            // change; a framework-agnostic caller re-dispatching on every derive needs the reducer itself
+            // to compare the RESULT (the ranges), not the raw inputs (which may recompute to the same
+            // ranges via different intermediate values) — device-confirmed (2026-08-13) this is a second,
+            // independent source of the same unbounded same-tick rebuild loop the 'layout' guard fixed.
+            const previousInputRange = state.inputRange;
+            const previousOutputRange = state.outputRange;
+            const hadEmitted = state.rangesEmitted;
+            const { inputRange, outputRange } = deriveRanges(state, inputs);
+            state.rangesEmitted = true;
+            // `hadEmitted` is load-bearing, not defensive: an unmeasured header derives exactly the
+            // identity ranges the initial state already holds, so without it the FIRST dispatch (Angular
+            // sends one from ngOnInit, before any layout) reads as redundant and the header never emits
+            // a rebuild at all — its wrapper then never commits. Regression-covered in
+            // sticky-header-reducer.test.ts.
+            if (hadEmitted &&
+                arraysEqual(previousInputRange, inputRange) &&
+                arraysEqual(previousOutputRange, outputRange)) {
+                dlog(`STICKY[reducer ${headerTag(state)}] inputs-changed: ranges unchanged, skipped rebuild`);
+                return { state, effects: [], changed: false };
+            }
+            dlog(`STICKY[reducer ${headerTag(state)}] inputs-changed: inputRange ${JSON.stringify(previousInputRange)}->` +
+                `${JSON.stringify(inputRange)} outputRange ${JSON.stringify(previousOutputRange)}->` +
+                `${JSON.stringify(outputRange)}`);
+            return {
+                state,
+                effects: [{ kind: 'rebuild-interpolation', inputRange, outputRange }],
+                changed: true,
+            };
+        }
+        case 'animated-tick': {
+            // A freshly-rebuilt interpolation re-emits 0 to its listeners; swallow that first zero once a
+            // real value has committed (RN). Otherwise schedule the host-tuned debounce that pushes the
+            // settled value into the committed transform for hit-testing.
+            if (action.value === 0 && !state.haveReceivedInitialZeroTranslateY) {
+                state.haveReceivedInitialZeroTranslateY = true;
+                dlog(`STICKY[reducer ${headerTag(state)}] animated-tick: swallowed re-emitted zero translateY`);
+                return { state, effects: [], changed: false };
+            }
+            dlog(`STICKY[reducer ${headerTag(state)}] animated-tick: scheduling debounce delay=${stickyDebounceMs(inputs.os)} ` +
+                `value=${action.value}`);
+            return {
+                state,
+                effects: [
+                    { kind: 'schedule-debounce', delay: stickyDebounceMs(inputs.os), value: action.value },
+                ],
+                changed: false,
+            };
+        }
+        case 'debounce-fired': {
+            // The debounce completed: commit the settled translateY. Once a NON-zero value commits, re-arm
+            // the swallow gate so the next interpolation rebuild's spurious 0 is dropped (RN).
+            dlog(`STICKY[reducer ${headerTag(state)}] debounce-fired: committing translateY=${action.value}`);
+            state.translateY = action.value;
+            if (action.value !== 0)
+                state.haveReceivedInitialZeroTranslateY = false;
+            return {
+                state,
+                effects: [{ kind: 'apply-passthrough', translateY: action.value }],
+                changed: true,
+            };
+        }
+    }
+}

package/build/state/touchable.d.ts

@@ -1,4 +1,4 @@
-import type { ISymbioteEvent } from '@symbiote-native/engine';
+import { type ISymbioteEvent } from '@symbiote-native/engine';
 export declare const DEFAULT_ACTIVE_OPACITY = 0.2;
 export declare const OPACITY_ACTIVE_DURATION_MS = 150;
 export declare const OPACITY_INACTIVE_DURATION_MS = 250;
@@ -13,3 +13,24 @@ export interface IPressTimingProps {
     minPressDuration?: number;
 }
 export declare function computePressOutWait(heldFor: number, minPressDuration: number, delayPressOut: number): number;
+export interface ITouchableFeedbackRuntime {
+    pressInTimerCancel: (() => void) | undefined;
+    activatedAt: number | undefined;
+}
+export declare function createTouchableFeedbackRuntime(): ITouchableFeedbackRuntime;
+export interface ITouchableFeedbackCallbacks {
+    activate: (event: ISymbioteEvent) => void;
+    deactivate: (event: ISymbioteEvent) => void;
+}
+export interface ITouchableFeedbackConfig {
+    delayPressIn: number;
+    delayPressOut: number;
+    minPressDuration: number;
+    schedule: (callback: () => void, ms: number) => () => void;
+    now: () => number;
+}
+export interface ITouchableFeedbackHandlers {
+    handlePressIn: ITouchableHandler;
+    handlePressOut: ITouchableHandler;
+}
+export declare function createTouchableFeedbackHandlers(config: ITouchableFeedbackConfig, runtime: ITouchableFeedbackRuntime, callbacks: ITouchableFeedbackCallbacks): ITouchableFeedbackHandlers;

package/build/state/touchable.js

@@ -3,6 +3,7 @@
 // (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.
 export const DEFAULT_ACTIVE_OPACITY = 0.2;
 export const OPACITY_ACTIVE_DURATION_MS = 150;
@@ -20,3 +21,64 @@ export const DEFAULT_MIN_PRESS_DURATION_MS = 130;
 export function computePressOutWait(heldFor, minPressDuration, delayPressOut) {
     return Math.max(minPressDuration - heldFor, delayPressOut);
 }
+export function createTouchableFeedbackRuntime() {
+    return { pressInTimerCancel: undefined, activatedAt: undefined };
+}
+// Build the two press handlers over config + runtime + the adapter's activate/deactivate callbacks.
+// The whole TouchableOpacity press-scheduling dance (delayPressIn defer, flush-on-early-release,
+// activatedAt tracking, the minPressDuration/delayPressOut hold) lives here, shared by every
+// adapter. The adapter rebuilds/holds the callbacks (they capture live config + the Animated Value)
+// while the runtime persists across renders. Twin of Pressable's createPressHandlers.
+export function createTouchableFeedbackHandlers(config, runtime, callbacks) {
+    const { delayPressIn, delayPressOut, minPressDuration, schedule, now } = config;
+    const { activate, deactivate } = callbacks;
+    function clearPressInTimer() {
+        if (runtime.pressInTimerCancel !== undefined) {
+            runtime.pressInTimerCancel();
+            runtime.pressInTimerCancel = undefined;
+        }
+    }
+    // The real activation: stamp the activation clock (for the press-out floor) then run the adapter's
+    // opacity fade + onPressIn. Split out so delayPressIn can defer it behind a timer that an early
+    // release still flushes.
+    function doActivate(event) {
+        runtime.activatedAt = now();
+        activate(event);
+    }
+    function doDeactivate(event) {
+        runtime.activatedAt = undefined;
+        deactivate(event);
+    }
+    return {
+        // RN's _createPressabilityConfig forwards delayPressIn: defer the active visual and onPressIn
+        // behind the delay (a release before it elapses flushes it synchronously).
+        handlePressIn(event) {
+            if (delayPressIn > 0) {
+                dlog(`TouchableOpacity pressIn deferred ${delayPressIn}ms`);
+                runtime.pressInTimerCancel = schedule(() => {
+                    runtime.pressInTimerCancel = undefined;
+                    doActivate(event);
+                }, delayPressIn);
+                return;
+            }
+            doActivate(event);
+        },
+        // delayPressOut + minPressDuration (RN _deactivate): the press-out waits at least
+        // minPressDuration past activation (so a fast tap holds the active visual) and at least
+        // delayPressOut, whichever is longer.
+        handlePressOut(event) {
+            if (runtime.pressInTimerCancel !== undefined) {
+                clearPressInTimer();
+                doActivate(event);
+            }
+            const heldFor = runtime.activatedAt === undefined ? 0 : now() - runtime.activatedAt;
+            const wait = computePressOutWait(heldFor, minPressDuration, delayPressOut);
+            if (wait > 0) {
+                dlog(`TouchableOpacity pressOut deferred ${wait}ms`);
+                schedule(() => doDeactivate(event), wait);
+                return;
+            }
+            doDeactivate(event);
+        },
+    };
+}

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

@@ -0,0 +1,129 @@
+import { type ICellLayout, type IViewToken, type IViewabilityConfigCallbackPair, type IViewableItemsChangedInfo } from './virtualized-list';
+export interface IListMetrics {
+    count: number;
+    offsets: number[];
+    lengths: number[];
+    total: number;
+    first: number;
+    last: number;
+    target: {
+        first: number;
+        last: number;
+    };
+    averageLength: number;
+    fixedLayout: ((index: number) => ICellLayout) | undefined;
+}
+export interface IListState<ItemT> {
+    scrollOffset: number;
+    viewportLength: number;
+    measured: Map<number, number>;
+    committedWindow: {
+        first: number;
+        last: number;
+    };
+    sentEndForContentLength: number;
+    sentStartForContentLength: number;
+    lastViewable: Map<string, IViewToken<ItemT>>;
+    hasInteracted: boolean;
+    firstVisibleKey: string | null;
+    appliedInitialScroll: boolean;
+    metrics: IListMetrics;
+}
+export interface IListReducerInputs<ItemT> {
+    data: unknown;
+    getItem: (data: unknown, index: number) => ItemT;
+    getItemCount: (data: unknown) => number;
+    keyExtractor?: (item: ItemT, index: number) => string;
+    getItemLayout?: (data: unknown, index: number) => {
+        length: number;
+        offset: number;
+        index: number;
+    };
+    horizontal: boolean;
+    windowSize: number;
+    initialNumToRender: number;
+    maxToRenderPerBatch: number;
+    updateCellsBatchingPeriod: number;
+    onEndReachedThreshold: number;
+    onStartReachedThreshold: number;
+    onEndReachedActive: boolean;
+    onStartReachedActive: boolean;
+    viewabilityPairs: IViewabilityConfigCallbackPair<ItemT>[];
+    maintainVisibleContentPosition?: {
+        minIndexForVisible: number;
+        autoscrollToTopThreshold?: number;
+    };
+    initialScrollIndex?: number;
+}
+export type IListAction<ItemT> = {
+    kind: 'scroll';
+    offset: number;
+} | {
+    kind: 'layout';
+    length: number;
+} | {
+    kind: 'measure';
+    index: number;
+    length: number;
+} | {
+    kind: 'refresh-metrics';
+} | {
+    kind: 'batch-tick';
+} | {
+    kind: 'record-interaction';
+} | {
+    kind: 'viewable-fired';
+    map: Map<string, IViewToken<ItemT>>;
+} | {
+    kind: 'commit';
+} | {
+    kind: 'scroll-to-offset';
+    offset: number;
+    animated: boolean;
+} | {
+    kind: 'scroll-to-index';
+    index: number;
+    animated: boolean;
+    viewPosition: number;
+    viewOffset: number;
+} | {
+    kind: 'scroll-to-item';
+    item: unknown;
+    animated: boolean;
+    viewPosition: number;
+} | {
+    kind: 'scroll-to-end';
+    animated: boolean;
+};
+export type IListEffect<ItemT> = {
+    kind: 'scroll-to';
+    offset: number;
+    animated: boolean;
+} | {
+    kind: 'fire-end-reached';
+    distanceFromEnd: number;
+} | {
+    kind: 'fire-start-reached';
+    distanceFromStart: number;
+} | {
+    kind: 'fire-viewable';
+    info: IViewableItemsChangedInfo<ItemT>;
+    delay: number;
+    map: Map<string, IViewToken<ItemT>>;
+} | {
+    kind: 'schedule-refill';
+    delay: number;
+} | {
+    kind: 'fire-scroll-to-index-failed';
+    index: number;
+    highestMeasuredFrameIndex: number;
+    averageItemLength: number;
+};
+export interface IListReduceResult<ItemT> {
+    state: IListState<ItemT>;
+    effects: IListEffect<ItemT>[];
+    changed: boolean;
+}
+export declare function createInitialListState<ItemT>(): IListState<ItemT>;
+export declare function listEffectSignature<ItemT>(state: IListState<ItemT>): string;
+export declare function reduceList<ItemT>(state: IListState<ItemT>, action: IListAction<ItemT>, inputs: IListReducerInputs<ItemT>): IListReduceResult<ItemT>;

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

@@ -0,0 +1,292 @@
+// VirtualizedList orchestration reducer: the framework-agnostic STATE MACHINE that folds every
+// per-adapter effect skeleton into one place. Before this, each adapter (React useEffect, Vue
+// watch, Angular ngAfterViewChecked) re-wrote the same sequence — recompute the window, gate
+// onEndReached on `last === count - 1`, dedup by content length, run viewability, apply MVCP — in
+// its own reactive dialect, and the predicates in that glue (`last === count - 1`, `first === 0`,
+// the batch-fill catch-up test, the viewability guards) lived THREE times and quietly drifted.
+//
+// Here the whole decision half is one pure `reduceList(state, action, inputs) -> {state, effects}`.
+// The adapter keeps only what is genuinely framework-bound: translate a native event into an
+// ACTION, hold ONE state cell, and EXECUTE the returned EFFECTS with its own primitives (a native
+// scrollTo, a callback/emit, a setTimeout, a re-render). The geometry leaves (buildOffsets /
+// computeWindow / computeMvcpAdjustment / …) still live in ./virtualized-list; this module composes
+// them into the ordered transition every adapter shares.
+//
+// Effect EXECUTION stays per-adapter by design: which framework hook fires the commit, how a
+// native scrollTo is dispatched, how a debounce timer is held — an effect-list DESCRIBES the work,
+// it does not run it. State TRANSITIONS (including the derived window metrics) are owned entirely
+// 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';
+export function createInitialListState() {
+    return {
+        scrollOffset: EMPTY_OFFSET,
+        viewportLength: EMPTY_OFFSET,
+        measured: new Map(),
+        committedWindow: { first: FIRST_INDEX, last: NO_INDEX },
+        sentEndForContentLength: NO_CONTENT_LENGTH_SENT,
+        sentStartForContentLength: NO_CONTENT_LENGTH_SENT,
+        lastViewable: new Map(),
+        hasInteracted: false,
+        firstVisibleKey: null,
+        appliedInitialScroll: false,
+        metrics: {
+            count: EMPTY_OFFSET,
+            offsets: [],
+            lengths: [],
+            total: EMPTY_OFFSET,
+            first: FIRST_INDEX,
+            last: NO_INDEX,
+            target: { first: FIRST_INDEX, last: NO_INDEX },
+            averageLength: EMPTY_OFFSET,
+            fixedLayout: undefined,
+        },
+    };
+}
+// A cheap signature over the render-relevant state. The adapter skips the after-commit pass when it
+// is unchanged (the same dedup Angular's lastEffectSignature did), so the batch-fill timer is not
+// thrashed by unrelated re-renders. Shared so the key CANNOT drift between adapters.
+export function listEffectSignature(state) {
+    const m = state.metrics;
+    return `${state.scrollOffset}|${state.viewportLength}|${m.first}|${m.last}|${m.count}|${m.total}`;
+}
+// Recompute the derived window metrics off the current state + inputs. Owns the controlled
+// committedWindow throttle (the side effect React ran during render): committedWindow is plain
+// state, so growing it toward target one batch-step at a time triggers no reactivity loop.
+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 target = computeWindow(count, offsets, lengths, state.scrollOffset, state.viewportLength, inputs.windowSize, inputs.initialNumToRender);
+    const throttled = throttleWindow(target, state.committedWindow, inputs.maxToRenderPerBatch);
+    state.committedWindow = throttled;
+    state.metrics = {
+        count,
+        offsets,
+        lengths,
+        total,
+        first: throttled.first,
+        last: throttled.last,
+        target,
+        averageLength,
+        fixedLayout,
+    };
+    return state;
+}
+function keyForOf(inputs) {
+    return (index) => resolveItemKey(inputs.getItem(inputs.data, index), index, inputs.keyExtractor);
+}
+// The after-render pass: every deferred effect, in the order 2 of 3 adapters already ran them
+// (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.
+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 });
+    }
+    // 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).
+    if (inputs.onEndReachedActive && state.viewportLength > EMPTY_OFFSET) {
+        const { distanceFromEnd, withinThreshold } = computeEndReached(m.total, state.scrollOffset, state.viewportLength, inputs.onEndReachedThreshold);
+        const decision = decideEdgeReached({
+            withinThreshold,
+            edgeCellRendered: m.last === m.count - 1,
+            total: m.total,
+            sentForContentLength: state.sentEndForContentLength,
+        });
+        state.sentEndForContentLength = decision.nextSentForContentLength;
+        if (decision.shouldFire) {
+            dlog(`VirtualizedList onEndReached distanceFromEnd=${distanceFromEnd} ` +
+                `(last=${m.last} of ${m.count}, contentLength=${m.total})`);
+            effects.push({ kind: 'fire-end-reached', distanceFromEnd });
+        }
+    }
+    // onStartReached: the top-edge twin of onEndReached.
+    if (inputs.onStartReachedActive && state.viewportLength > EMPTY_OFFSET) {
+        const { distanceFromStart, withinThreshold } = computeStartReached(state.scrollOffset, state.viewportLength, inputs.onStartReachedThreshold);
+        const decision = decideEdgeReached({
+            withinThreshold,
+            edgeCellRendered: m.first === FIRST_INDEX,
+            total: m.total,
+            sentForContentLength: state.sentStartForContentLength,
+        });
+        state.sentStartForContentLength = decision.nextSentForContentLength;
+        if (decision.shouldFire) {
+            dlog(`VirtualizedList onStartReached distanceFromStart=${distanceFromStart} ` +
+                `(first=${m.first}, contentLength=${m.total})`);
+            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,
+            });
+        }
+    }
+    // initialScrollIndex: once the first viewport is known, jump to that index a single time.
+    if (inputs.initialScrollIndex !== undefined &&
+        !state.appliedInitialScroll &&
+        state.viewportLength > EMPTY_OFFSET &&
+        m.count !== FIRST_INDEX) {
+        state.appliedInitialScroll = true;
+        const offset = offsetForIndex(inputs.initialScrollIndex, FIRST_INDEX, EMPTY_OFFSET, m.count, m.offsets, m.lengths, state.viewportLength);
+        // The initial jump is instant (RN does not animate initialScrollIndex).
+        effects.push({ kind: 'scroll-to', offset, animated: false });
+    }
+    // maintainVisibleContentPosition: shift for the prepended items collapsed into the leading spacer
+    // that native MVCP cannot see (RN getDerivedStateFromProps). computeMvcpAdjustment owns the pure
+    // decision; here it becomes a scroll-to effect.
+    const mvcp = computeMvcpAdjustment({
+        minIndexForVisible: inputs.maintainVisibleContentPosition?.minIndexForVisible,
+        autoscrollToTopThreshold: inputs.maintainVisibleContentPosition?.autoscrollToTopThreshold,
+        count: m.count,
+        committedFirst: state.committedWindow.first,
+        offsets: m.offsets,
+        scrollOffset: state.scrollOffset,
+        prevFirstVisibleKey: state.firstVisibleKey,
+        keyFor: keyForOf(inputs),
+    });
+    if (mvcp.action.kind === 'autoscroll-top') {
+        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 });
+    }
+    state.firstVisibleKey = mvcp.firstVisibleKey;
+    return { state, effects, changed: false };
+}
+// Resolve an imperative scrollToIndex: report the failure when there is no getItemLayout and the
+// 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;
+    const measuredCeiling = highestMeasuredIndex(state.measured);
+    if (inputs.getItemLayout === undefined && action.index > measuredCeiling) {
+        dlog(`VirtualizedList onScrollToIndexFailed index=${action.index} ` +
+            `highestMeasured=${measuredCeiling} (no getItemLayout)`);
+        return {
+            state,
+            effects: [
+                {
+                    kind: 'fire-scroll-to-index-failed',
+                    index: action.index,
+                    highestMeasuredFrameIndex: measuredCeiling,
+                    averageItemLength: m.averageLength,
+                },
+            ],
+            changed: false,
+        };
+    }
+    const offset = offsetForIndex(action.index, action.viewPosition, action.viewOffset, m.count, m.offsets, m.lengths, state.viewportLength);
+    return {
+        state,
+        effects: [{ kind: 'scroll-to', offset, animated: action.animated }],
+        changed: false,
+    };
+}
+// The single transition every adapter shares. The adapter maps a native event / imperative call to
+// an action, calls this, stores the returned state, and executes the returned effects.
+export function reduceList(state, action, inputs) {
+    switch (action.kind) {
+        // Scalar transitions never recompute the window — they set the input and ask for a render; the
+        // metrics derive runs exactly ONCE per render, in the 'refresh-metrics' the adapter fires from
+        // its render body. That single-derive-per-render invariant is what advances the throttled
+        // committedWindow one step per frame (deriving here too would advance it twice).
+        case 'scroll':
+            // First scroll is the interaction that ungates waitForInteraction viewability configs.
+            state.hasInteracted = true;
+            state.scrollOffset = action.offset;
+            return { state, effects: [], changed: true };
+        case 'layout':
+            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.
+            if (inputs.getItemLayout !== undefined)
+                return { state, effects: [], changed: false };
+            if (state.measured.get(action.index) === action.length) {
+                return { state, effects: [], changed: false };
+            }
+            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 };
+        case 'record-interaction':
+            state.hasInteracted = true;
+            return { state, effects: [], changed: false };
+        case 'viewable-fired':
+            state.lastViewable = action.map;
+            return { state, effects: [], changed: false };
+        case 'commit':
+            return commitList(state, inputs);
+        case 'scroll-to-offset':
+            return {
+                state,
+                effects: [{ kind: 'scroll-to', offset: action.offset, animated: action.animated }],
+                changed: false,
+            };
+        case 'scroll-to-index':
+            return resolveScrollToIndex(state, inputs, action);
+        case 'scroll-to-item': {
+            const index = indexOfItem(inputs.data, inputs.getItem, state.metrics.count, action.item);
+            if (index === NO_INDEX) {
+                dlog('VirtualizedList scrollToItem: item not found');
+                return { state, effects: [], changed: false };
+            }
+            const offset = offsetForIndex(index, action.viewPosition, EMPTY_OFFSET, state.metrics.count, state.metrics.offsets, state.metrics.lengths, state.viewportLength);
+            return {
+                state,
+                effects: [{ kind: 'scroll-to', offset, animated: action.animated }],
+                changed: false,
+            };
+        }
+        case 'scroll-to-end':
+            return {
+                state,
+                effects: [
+                    {
+                        kind: 'scroll-to',
+                        offset: offsetForEnd(state.metrics.total, state.viewportLength),
+                        animated: action.animated,
+                    },
+                ],
+                changed: false,
+            };
+    }
+}

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

@@ -136,8 +136,10 @@ export interface IListCellPlan {
 }
 export interface IListPlan {
     leadingExtent: number;
+    gapExtent: number;
     trailingExtent: number;
     cells: IListCellPlan[];
+    forcedStickyCell: IListCellPlan | undefined;
     stickyChildPositions: number[];
 }
 export interface IListPlanParams {
@@ -153,3 +155,46 @@ export interface IListPlanParams {
     hasSeparators: boolean;
 }
 export declare function buildListPlan(params: IListPlanParams): IListPlan;
+export type IMvcpAction = {
+    kind: 'none';
+} | {
+    kind: 'autoscroll-top';
+} | {
+    kind: 'shift';
+    offset: number;
+};
+export interface IMvcpAdjustmentParams {
+    minIndexForVisible: number | undefined;
+    autoscrollToTopThreshold: number | undefined;
+    count: number;
+    committedFirst: number;
+    offsets: number[];
+    scrollOffset: number;
+    prevFirstVisibleKey: string | null;
+    keyFor: (index: number) => string;
+}
+export interface IMvcpAdjustmentResult {
+    firstVisibleKey: string | null;
+    action: IMvcpAction;
+}
+export declare function computeMvcpAdjustment(params: IMvcpAdjustmentParams): IMvcpAdjustmentResult;
+export declare function resolveItemKey<ItemT>(item: ItemT, index: number, keyExtractor: ((item: ItemT, index: number) => string) | undefined): string;
+export declare function indexOfItem(data: unknown, getItem: (data: unknown, index: number) => unknown, count: number, item: unknown): number;
+export declare function offsetForEnd(total: number, viewportLength: number): number;
+export declare function isSeparatorGapInRange(gapIndex: number, count: number): boolean;
+export declare function decideEdgeReached(params: {
+    withinThreshold: boolean;
+    edgeCellRendered: boolean;
+    total: number;
+    sentForContentLength: number;
+}): {
+    shouldFire: boolean;
+    nextSentForContentLength: number;
+};
+export declare function resolveStickySectionHeaders(enabled: boolean | undefined, headerIndices: number[], platformOS: string): number[] | undefined;
+export declare function wrapFixedLayout(data: unknown, getItemLayout: ((data: unknown, index: number) => {
+    length: number;
+    offset: number;
+    index: number;
+}) | undefined): ((index: number) => ICellLayout) | undefined;
+export declare function resolveAverageLength(fixedLayout: ((index: number) => ICellLayout) | undefined, count: number, measured: Map<number, number>): number;

package/build/state/virtualized-list.js

@@ -19,6 +19,7 @@
 // framework's own children (renderItem -> ReactNode / VNode), so there is no
 // Descriptor render fn for a list - the shared layer for lists is this STATE/logic
 // module, not a view/render-*.ts.
+import { dlog } from '@symbiote-native/engine';
 // Defaults match RN. windowSize is measured in viewport-lengths (21 => ten screens
 // of buffer on each side of the visible region). onEndReachedThreshold is a multiple
 // of the visible length (RN's onEndReachedThresholdOrDefault returns `?? 2`).
@@ -55,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)
@@ -66,7 +65,6 @@ 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.
 export function readLayoutLength(event, horizontal) {
     const native = asRecord(event.nativeEvent);
     if (native === undefined)
@@ -278,22 +276,50 @@ 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 closestStickyIndex = params.stickyIndices !== undefined
+        ? findClosestStickyIndexBelow(params.first, params.stickyIndices)
+        : NO_INDEX;
+    const forcedStickyCell = closestStickyIndex === NO_INDEX
+        ? undefined
+        : { index: closestStickyIndex, key: params.keyFor(closestStickyIndex) };
+    const windowLeadingExtent = params.first > FIRST_INDEX ? params.offsets[params.first] : EMPTY_OFFSET;
+    const leadingExtent = forcedStickyCell === undefined ? windowLeadingExtent : params.offsets[closestStickyIndex];
+    const gapExtent = forcedStickyCell === undefined
+        ? EMPTY_OFFSET
+        : windowLeadingExtent -
+            params.offsets[closestStickyIndex] -
+            params.lengths[closestStickyIndex];
     const renderedExtent = params.last >= params.first
         ? params.offsets[params.last] + params.lengths[params.last] - params.offsets[params.first]
         : EMPTY_OFFSET;
-    const trailingExtent = params.total - leadingExtent - renderedExtent;
+    const trailingExtent = params.total - windowLeadingExtent - 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 one child; a separator after it (when ItemSeparatorComponent is set and this is not
+    // the last cell) is another.
     let childPosition = (params.hasHeader ? 1 : 0) + (leadingExtent > EMPTY_OFFSET ? 1 : 0);
+    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)
@@ -302,5 +328,120 @@ export function buildListPlan(params) {
         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;
+    if (minIndexForVisible === undefined || count === FIRST_INDEX) {
+        return { firstVisibleKey: null, action: { kind: 'none' } };
+    }
+    const newFirstVisibleKey = count > minIndexForVisible ? keyFor(minIndexForVisible) : null;
+    const prevKey = params.prevFirstVisibleKey;
+    const settled = {
+        firstVisibleKey: newFirstVisibleKey,
+        action: { kind: 'none' },
+    };
+    if (prevKey === null || newFirstVisibleKey === null || prevKey === newFirstVisibleKey) {
+        return settled;
+    }
+    let anchorIndex = NO_INDEX;
+    for (let index = minIndexForVisible; index < count; index += 1) {
+        if (keyFor(index) === prevKey) {
+            anchorIndex = index;
+            break;
+        }
+    }
+    if (anchorIndex <= minIndexForVisible)
+        return settled;
+    // Native MVCP shifts in-window cells itself; the JS shift covers ONLY the inserted items in the
+    // leading SPACER (above the first rendered index). Counting the full inserted extent would
+    // double-correct.
+    const spacerEnd = Math.min(anchorIndex, params.committedFirst);
+    const insertedExtent = spacerEnd > minIndexForVisible
+        ? params.offsets[spacerEnd] - params.offsets[minIndexForVisible]
+        : EMPTY_OFFSET;
+    if (insertedExtent <= EMPTY_OFFSET)
+        return settled;
+    const autoThreshold = params.autoscrollToTopThreshold;
+    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' } };
+    }
+    dlog(`VirtualizedList MVCP adjust +${insertedExtent}px ` +
+        `(anchor "${prevKey}" moved ${minIndexForVisible}->${anchorIndex})`);
+    return {
+        firstVisibleKey: newFirstVisibleKey,
+        action: { kind: 'shift', offset: params.scrollOffset + insertedExtent },
+    };
+}
+// The default key extractor: the caller's keyExtractor when set, else the index as a string (RN's
+// default). Centralized so every adapter's keyForIndex resolves keys identically.
+export function resolveItemKey(item, index, keyExtractor) {
+    return keyExtractor ? keyExtractor(item, index) : String(index);
+}
+// Linear item -> index lookup for scrollToItem (RN scans by reference identity). NO_INDEX when the
+// item is not in data.
+export function indexOfItem(data, getItem, count, item) {
+    for (let index = FIRST_INDEX; index < count; index += 1) {
+        if (getItem(data, index) === item)
+            return index;
+    }
+    return NO_INDEX;
+}
+// The pixel offset that scrolls the last content to the bottom edge (scrollToEnd). Never negative
+// when the content is shorter than the viewport.
+export function offsetForEnd(total, viewportLength) {
+    return Math.max(EMPTY_OFFSET, total - viewportLength);
+}
+// A gap index addresses a real separator only inside [0, count-2]; outside it there is no gap and
+// the write is a no-op (RN bails on the same bounds).
+export function isSeparatorGapInRange(gapIndex, count) {
+    return gapIndex >= FIRST_INDEX && gapIndex <= count - 2;
+}
+// onEndReached / onStartReached fire decision + content-length dedup (RN _maybeCallOnEdgeReached).
+// The geometry (withinThreshold) comes from computeEndReached/computeStartReached; this folds in the
+// "edge cell actually rendered" gate, the dedup against the last-fired content length, and the
+// re-arm once scrolled away from the edge. Returns whether to fire plus the next dedup sentinel.
+export function decideEdgeReached(params) {
+    const { withinThreshold, edgeCellRendered, total, sentForContentLength } = params;
+    if (withinThreshold && edgeCellRendered && sentForContentLength !== total) {
+        return { shouldFire: true, nextSentForContentLength: total };
+    }
+    // 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: sentForContentLength };
+}
+// Section headers stick by default only on iOS (RN); the explicit prop overrides. Returns the
+// header indices to stick, or undefined when sticking is off.
+export function resolveStickySectionHeaders(enabled, headerIndices, platformOS) {
+    const stickyEnabled = enabled ?? platformOS === 'ios';
+    return stickyEnabled ? headerIndices : undefined;
+}
+// Wrap the user's getItemLayout into an (index) => ICellLayout resolver (dropping the `index` field
+// RN's getItemLayout returns), or undefined when there is no getItemLayout.
+export function wrapFixedLayout(data, getItemLayout) {
+    if (getItemLayout === undefined)
+        return undefined;
+    return (index) => {
+        const layout = getItemLayout(data, index);
+        return { length: layout.length, offset: layout.offset };
+    };
+}
+// The average cell length that sizes unmeasured cells and the trailing spacer: the fixed layout's
+// first cell length when getItemLayout is set (guarded against an empty list so it never calls
+// fixedLayout on a non-existent cell), else the running average of the measured cells.
+export function resolveAverageLength(fixedLayout, count, measured) {
+    if (fixedLayout === undefined)
+        return averageMeasuredLength(measured);
+    return count > FIRST_INDEX ? fixedLayout(FIRST_INDEX).length : EMPTY_OFFSET;
 }

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-scroll-view.d.ts

@@ -11,6 +11,22 @@ export type IScrollIntrinsics = {
     contentStyle: IStyleProp<IViewStyle>;
 };
 export declare function selectScrollIntrinsics(isHorizontal: boolean, contentContainerStyle: IStyleProp<IViewStyle> | undefined): IScrollIntrinsics;
+export type IScrollForwardMode = 'plain' | 'sticky-native' | 'sticky-js';
+export interface IScrollForwardingInputs {
+    hasStickyHeaders: boolean;
+    nativeStickyAvailable: boolean;
+    invertStickyHeaders: boolean | undefined;
+    scrollEventThrottle: number | undefined;
+    maintainVisibleContentPosition: unknown;
+    snapToAlignment: unknown;
+}
+export interface IScrollForwarding {
+    mode: IScrollForwardMode;
+    scrollEventThrottle: number | undefined;
+    capturesViewportHeight: boolean;
+    collapsableChildren: boolean;
+}
+export declare function resolveScrollForwarding(inputs: IScrollForwardingInputs): IScrollForwarding;
 export type IContentSize = {
     width: number;
     height: number;

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

@@ -71,6 +71,41 @@ export function selectScrollIntrinsics(isHorizontal, contentContainerStyle) {
         : contentContainerStyle;
     return { scrollViewIntrinsic, contentIntrinsic, scrollViewBaseStyle, contentStyle };
 }
+// When sticky headers are active the scroll offset must reach the AnimatedValue; RN raises the scroll
+// event rate for it (ScrollView.js:1798): throttle 1 on the native driver (it can afford every frame),
+// 16 on the JS fallback (Animated.event drives the value in JS). Without sticky headers the user's
+// throttle passes through untouched. These two magic numbers were copied into all three adapters.
+const STICKY_NATIVE_SCROLL_THROTTLE = 1;
+const STICKY_JS_SCROLL_THROTTLE = 16;
+export function resolveScrollForwarding(inputs) {
+    // maintainVisibleContentPosition (and Android snapToAlignment) anchor against MOUNTED cell views;
+    // Android Fabric view-flattens layout-only cells away, so RN keeps them as real views with
+    // collapsableChildren={false} on the content container (ScrollView.js preserveChildren). No-op on iOS.
+    const collapsableChildren = inputs.maintainVisibleContentPosition !== undefined || inputs.snapToAlignment !== undefined;
+    if (!inputs.hasStickyHeaders) {
+        return {
+            mode: 'plain',
+            scrollEventThrottle: inputs.scrollEventThrottle,
+            capturesViewportHeight: false,
+            collapsableChildren,
+        };
+    }
+    const capturesViewportHeight = inputs.invertStickyHeaders === true;
+    if (inputs.nativeStickyAvailable) {
+        return {
+            mode: 'sticky-native',
+            scrollEventThrottle: inputs.scrollEventThrottle ?? STICKY_NATIVE_SCROLL_THROTTLE,
+            capturesViewportHeight,
+            collapsableChildren,
+        };
+    }
+    return {
+        mode: 'sticky-js',
+        scrollEventThrottle: inputs.scrollEventThrottle ?? STICKY_JS_SCROLL_THROTTLE,
+        capturesViewportHeight,
+        collapsableChildren,
+    };
+}
 // Did the content view's measured size actually change since the last fire? RN synthesizes
 // onContentSizeChange from the inner content view's onLayout, but that fires on every layout
 // pass; RN dedupes so the user handler only sees real size changes (ScrollView.js). First

package/build/view/render-touchable-highlight.d.ts

@@ -0,0 +1,2 @@
+import type { IViewStyle } from '@symbiote-native/engine';
+export declare function highlightPressedStyle<TStyle>(pressed: boolean, style: TStyle, underlayColor: string, activeOpacity: number): TStyle | [TStyle, IViewStyle];

package/build/view/render-touchable-highlight.js

@@ -0,0 +1,12 @@
+// TouchableHighlight underlay: the shared render decision (framework-agnostic). RN drives the
+// highlight with setState (not Animated) — while pressed it paints underlayColor + lowers the child
+// opacity, at rest it is the bare style (TouchableHighlight.js). This 3-line gating was triplicated
+// verbatim across adapters; it lives here once, prop-driven. Each adapter passes its own resolved
+// style base (React the raw style, Angular the anchor+style array, Vue the untyped attrs style) plus
+// the live `pressed`, so the base is generic — the overlay is layered on top when pressed.
+export function highlightPressedStyle(pressed, style, underlayColor, activeOpacity) {
+    if (!pressed)
+        return style;
+    const overlay = { backgroundColor: underlayColor, opacity: activeOpacity };
+    return [style, overlay];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/components",
-  "version": "0.2.6",
+  "version": "0.4.0",
   "description": "Framework-agnostic component logic (state machines + render functions) for SymbioteNative — written once, inherited by every adapter (React, Vue, Angular, ...).",
   "license": "MIT",
   "repository": {
@@ -39,7 +39,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.0.0",
-    "@symbiote-native/engine": "0.1.7"
+    "@symbiote-native/engine": "0.2.0"
   },
   "scripts": {
     "typecheck": "tsc --build",

package/build/state/scroll-routing-handle/index.d.ts

@@ -1,10 +0,0 @@
-import type { ISymbioteNode } from '@symbiote-native/engine';
-import type { IScrollViewHandle } from '../../scroll-view-commands';
-export interface IScrollRoutingHandle {
-    flashScrollIndicators(): void;
-    getNativeScrollRef(): IScrollViewHandle | null;
-    getScrollableNode(): IScrollViewHandle | null;
-    getScrollResponder(): IScrollViewHandle | null;
-    getScrollNode(): ISymbioteNode | null;
-    recordInteraction(): void;
-}

package/build/state/scroll-routing-handle/index.js

@@ -1,6 +0,0 @@
-// The inner-scroll routing tail every windowed-list imperative handle exposes
-// (VirtualizedList, VirtualizedSectionList, and via those FlatList/SectionList). Each
-// method forwards straight to the underlying ScrollView's own handle/node; neither list
-// adds behavior of its own, so the 6 members live here once and both list handle types
-// extend this instead of hand-duplicating (and risking drift in) the signatures.
-export {};

package/build/view/layout-event/index.d.ts

@@ -1,2 +0,0 @@
-import type { ISymbioteEvent } from '@symbiote-native/engine';
-export declare function readLayoutField(event: ISymbioteEvent, key: 'width' | 'height' | 'y'): number | undefined;

package/build/view/layout-event/index.js

@@ -1,12 +0,0 @@
-// Shared across render-scroll-view's content/frame dimension read (width/height) and
-// render-scroll-sticky's header position read (y/height): both pull a single numeric field out of
-// an onLayout event's nativeEvent.layout. SymbioteEvent.nativeEvent is Record<string, unknown>, so
-// the layout box and the requested field are narrowed at runtime, no cast. A malformed event
-// yields undefined (no-op).
-export function readLayoutField(event, key) {
-    const layout = event.nativeEvent.layout;
-    if (typeof layout !== 'object' || layout === null)
-        return undefined;
-    const value = Reflect.get(layout, key);
-    return typeof value === 'number' ? value : undefined;
-}