@symbiote-native/components 0.2.5 → 0.3.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,10 +21,15 @@ 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';
-export { renderImage } from './view/render-image.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).
 export { renderImageBackground } from './view/render-image-background.js';
@@ -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/state/sticky-header-reducer.d.ts

@@ -0,0 +1,53 @@
+export interface IStickyHeaderState {
+    measured: boolean;
+    layoutY: number;
+    layoutHeight: number;
+    translateY: number | null;
+    haveReceivedInitialZeroTranslateY: boolean;
+    inputRange: number[];
+    outputRange: number[];
+}
+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,114 @@
+// 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],
+    };
+}
+// 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}`;
+}
+// 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.
+export function reduceSticky(state, action, inputs) {
+    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.
+            state.layoutY = action.y;
+            state.layoutHeight = action.height;
+            state.measured = true;
+            const { inputRange, outputRange } = deriveRanges(state, inputs);
+            const effects = [];
+            if (inputs.index !== undefined) {
+                effects.push({ kind: 'record-header-y', index: inputs.index, y: action.y });
+            }
+            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.
+            const { inputRange, outputRange } = deriveRanges(state, inputs);
+            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-header swallowed re-emitted zero translateY');
+                return { state, effects: [], changed: false };
+            }
+            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).
+            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

@@ -153,3 +153,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`).
@@ -304,3 +305,111 @@ export function buildListPlan(params) {
     }
     return { leadingExtent, trailingExtent, cells, 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-image-background.js

@@ -10,7 +10,7 @@
 // the box. `imageStyle` wins last.
 import { dlog, flattenStyle, } from '@symbiote-native/engine';
 import { el } from '../descriptor.js';
-import { renderImage } from './render-image.js';
+import { renderImage } from './render-image/index.js';
 // The inner Image's positioning: absolute-fill behind the wrapper's children.
 const IMAGE_BACKGROUND_ABSOLUTE_FILL = {
     position: 'absolute',

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,7 +1,8 @@
 {
   "name": "@symbiote-native/components",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Framework-agnostic component logic (state machines + render functions) for SymbioteNative — written once, inherited by every adapter (React, Vue, Angular, ...).",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/OneEyed1366/symbiote-native.git",
@@ -33,12 +34,12 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@symbiote-native/engine": ">=0.1.6",
+    "@symbiote-native/engine": ">=0.1.7",
     "react-native": ">=0.86"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",
-    "@symbiote-native/engine": "0.1.6"
+    "@symbiote-native/engine": "0.1.7"
   },
   "scripts": {
     "typecheck": "tsc --build",

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

@@ -1,56 +0,0 @@
-import { type IImageSource, type IImageSourceProp, type IStyleProp, type ISymbioteEvent, type IViewStyle } from '@symbiote-native/engine';
-import type { IAccessibilityProps, IAriaProps } from '../accessibility-props';
-import { type IDescriptor } from '../descriptor';
-export type { IImageSource, IImageSourceProp };
-type IImageEventHandler = (event: ISymbioteEvent) => void;
-export type IResizeMode = 'cover' | 'contain' | 'stretch' | 'repeat' | 'center';
-export type IImageCapInsets = {
-    top: number;
-    left: number;
-    bottom: number;
-    right: number;
-};
-export type IResizeMethod = 'auto' | 'resize' | 'scale' | 'none';
-export type IImageProps = IAccessibilityProps & IAriaProps & {
-    source?: IImageSourceProp;
-    defaultSource?: IImageSourceProp;
-    loadingIndicatorSource?: IImageSourceProp;
-    style?: IStyleProp<IViewStyle>;
-    resizeMode?: IResizeMode;
-    resizeMethod?: IResizeMethod;
-    tintColor?: string;
-    blurRadius?: number;
-    capInsets?: IImageCapInsets;
-    fadeDuration?: number;
-    progressiveRenderingEnabled?: boolean;
-    src?: string;
-    srcSet?: string;
-    alt?: string;
-    width?: number;
-    height?: number;
-    crossOrigin?: 'anonymous' | 'use-credentials';
-    referrerPolicy?: string;
-    onLoadStart?: IImageEventHandler;
-    onLoad?: IImageEventHandler;
-    onLoadEnd?: IImageEventHandler;
-    onError?: IImageEventHandler;
-    onProgress?: IImageEventHandler;
-    onPartialLoad?: IImageEventHandler;
-};
-export type IImageViewProps = {
-    source?: IImageSourceProp;
-    defaultSource?: IImageSourceProp;
-    loadingIndicatorSource?: IImageSourceProp;
-    style?: IStyleProp<IViewStyle>;
-    resizeMode?: IResizeMode;
-    tintColor?: string;
-    src?: string;
-    srcSet?: string;
-    alt?: string;
-    width?: number;
-    height?: number;
-    crossOrigin?: 'anonymous' | 'use-credentials';
-    referrerPolicy?: string;
-    passthrough: Record<string, unknown>;
-};
-export declare function renderImage(view: IImageViewProps): IDescriptor;

package/build/view/render-image.js

@@ -1,133 +0,0 @@
-import { dlog, flattenStyle, resolveImageSource, } from '@symbiote-native/engine';
-import { el } from '../descriptor.js';
-// Resolve the source, then normalize to the array shape native expects. A single
-// object/number becomes a one-element array; an already-array source passes through.
-function normalizeSource(source) {
-    const resolved = resolveImageSource(source);
-    const sources = Array.isArray(resolved) ? resolved : [resolved];
-    dlog(`Image source resolved to ${JSON.stringify(sources)}`);
-    return sources;
-}
-// The HTTP headers the W3C aliases (crossOrigin / referrerPolicy) contribute to
-// every folded source, mirroring ImageSourceUtils.js getImageSourcesFromImageProps:
-// 'use-credentials' adds the credentials header; referrerPolicy adds Referrer-Policy.
-function headersFromAliases(view) {
-    const headers = {};
-    if (view.crossOrigin === 'use-credentials') {
-        headers['Access-Control-Allow-Credentials'] = 'true';
-    }
-    if (view.referrerPolicy !== undefined) {
-        headers['Referrer-Policy'] = view.referrerPolicy;
-    }
-    return headers;
-}
-// Expand a `srcSet` descriptor list into scaled sources, falling back to `src` for
-// the 1x slot when srcSet omits it. Direct port of getImageSourcesFromImageProps'
-// srcSet branch (ImageSourceUtils.js:48). Invalid scale tokens are skipped, matching
-// RN's parse-and-warn behavior.
-function expandSrcSet(srcSet, view, headers) {
-    const sources = [];
-    let useSrcForDefaultScale = true;
-    for (const entry of srcSet.split(', ')) {
-        const [uri, xScale = '1x'] = entry.split(' ');
-        if (!xScale.endsWith('x')) {
-            dlog(`Image srcSet: unsupported scale token "${xScale}", skipping`);
-            continue;
-        }
-        const scale = parseInt(xScale.slice(0, -1), 10);
-        if (Number.isNaN(scale))
-            continue;
-        if (scale === 1)
-            useSrcForDefaultScale = false;
-        sources.push({ uri, scale, width: view.width, height: view.height, ...{ headers } });
-    }
-    if (useSrcForDefaultScale && view.src !== undefined) {
-        sources.push({
-            uri: view.src,
-            scale: 1,
-            width: view.width,
-            height: view.height,
-            ...{ headers },
-        });
-    }
-    if (sources.length === 0)
-        dlog('Image srcSet: produced no valid sources');
-    return sources;
-}
-// Resolve the native `source` array from whichever of source / src / srcSet the
-// caller provided. Mirrors ImageSourceUtils.js getImageSourcesFromImageProps:
-// srcSet wins, then src, then a header-decorated source, then the plain source.
-// Always returns the array shape native expects (the same contract normalizeSource
-// guarantees), so the component never sends a bare object.
-function resolveSourceArray(view) {
-    const headers = headersFromAliases(view);
-    if (view.srcSet !== undefined) {
-        return expandSrcSet(view.srcSet, view, headers);
-    }
-    if (view.src !== undefined) {
-        return [{ uri: view.src, width: view.width, height: view.height, ...{ headers } }];
-    }
-    if (view.source === undefined) {
-        dlog('Image: no source / src / srcSet provided');
-        return [];
-    }
-    const sources = normalizeSource(view.source);
-    // A header-decorated single object source gets the headers merged in, per RN's
-    // `source.uri && headers` branch; the array/number shapes pass through untouched.
-    if (Object.keys(headers).length > 0 && sources.length === 1) {
-        const [only] = sources;
-        if (typeof only === 'object' && only !== null && typeof Reflect.get(only, 'uri') === 'string') {
-            return [{ ...only, headers }];
-        }
-    }
-    return sources;
-}
-function readStyleString(style, key) {
-    if (style === undefined)
-        return undefined;
-    // style is a StyleProp (possibly a nested array), so flatten before reading a key.
-    const flat = flattenStyle(style);
-    const value = Object.hasOwn(flat, key) ? flat[key] : undefined;
-    return typeof value === 'string' ? value : undefined;
-}
-// Resolve an asset source and read its single uri. RN forwards the Android
-// loading indicator as a bare uri string (`loadingIndicatorSrc`), not the
-// array shape the main source uses, so we resolve and pluck the uri.
-function readSourceUri(source) {
-    const [resolved] = normalizeSource(source);
-    if (typeof resolved === 'object' && resolved !== null) {
-        const uri = Reflect.get(resolved, 'uri');
-        if (typeof uri === 'string')
-            return uri;
-    }
-    return undefined;
-}
-export function renderImage(view) {
-    // `width` / `height` aliases fold into style (ImageProps.js:195,202); explicit
-    // style keys win, matching RN's `{width, height}, ...style` ordering.
-    const foldedStyle = view.width === undefined && view.height === undefined
-        ? view.style
-        : [{ width: view.width, height: view.height }, view.style];
-    const mapped = {
-        ...view.passthrough,
-        style: foldedStyle,
-        source: resolveSourceArray(view),
-        resizeMode: view.resizeMode ?? readStyleString(view.style, 'resizeMode'),
-        tintColor: view.tintColor ?? readStyleString(view.style, 'tintColor'),
-    };
-    // `alt` is the accessibility text: it sets accessibilityLabel and marks the image
-    // accessible (Image.ios.js / Image.android.js: alt -> accessibilityLabel + accessible).
-    // An explicit accessibilityLabel (already folded into passthrough) still wins.
-    if (view.alt !== undefined) {
-        if (mapped.accessibilityLabel === undefined)
-            mapped.accessibilityLabel = view.alt;
-        mapped.accessible = true;
-    }
-    if (view.defaultSource !== undefined)
-        mapped.defaultSource = normalizeSource(view.defaultSource);
-    if (view.loadingIndicatorSource !== undefined) {
-        mapped.loadingIndicatorSrc = readSourceUri(view.loadingIndicatorSource);
-    }
-    dlog('Image -> RCTImageView');
-    return el('symbiote-image', mapped);
-}