@symbiote-native/components 3.1.1 → 3.1.3

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

@@ -1,19 +1,6 @@
-// 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.
+// Sticky-header effect machine: one pure `reduceSticky(state, action, inputs)` shared by every
+// adapter, so the zero-swallow gate, debounce pick, and rebuild decision live once, not once per
+// framework's reactive dialect. Math leaf + debounce window live in ./view/render-scroll-sticky.
 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
@@ -43,8 +30,8 @@ function arraysEqual(a, b) {
         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.
+// Recompute the derived ranges off the current state + inputs, store them, and return them for
+// the rebuild effect.
 function deriveRanges(state, inputs) {
     const { inputRange, outputRange } = computeStickyInterpolation({
         measured: state.measured,
@@ -58,14 +45,99 @@ function deriveRanges(state, inputs) {
     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).
+// Diagnostic-only, gated: identifies which header instance a log line belongs to — layoutY
+// doubles as a stable per-header id once measured (0 before the first layout).
 function headerTag(state) {
     return `y=${state.layoutY}`;
 }
+// Redundant-geometry guard: Yoga re-fires onLayout with the same y/height on an unrelated
+// relayout — without this a fresh prop identity per redundant layout trips an unbounded
+// rebuild loop.
+function handleLayout(state, action, inputs) {
+    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 };
+}
+// Redundant-ranges guard (same cause as layout's): compare the derived result, not raw
+// inputs. `hadEmitted` is load-bearing: an unmeasured header derives the same identity
+// ranges the initial state holds, so without it the first dispatch reads as redundant.
+function handleInputsChanged(state, inputs) {
+    const previousInputRange = state.inputRange;
+    const previousOutputRange = state.outputRange;
+    const hadEmitted = state.rangesEmitted;
+    const { inputRange, outputRange } = deriveRanges(state, inputs);
+    state.rangesEmitted = true;
+    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,
+    };
+}
+// A freshly-rebuilt interpolation re-emits 0 to its listeners; swallow that first zero once a
+// real value has committed. Otherwise schedule the host-tuned debounce.
+function handleAnimatedTick(state, action, inputs) {
+    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,
+    };
+}
+// Already-sitting-at-this-value bails to break a re-arriving settled value's cascade
+// (apply-passthrough -> fresh identity -> reconnect -> another tick).
+function handleDebounceFired(state, action) {
+    if (state.translateY === action.value) {
+        dlog(`STICKY[reducer ${headerTag(state)}] debounce-fired: already at translateY=${action.value}, no-op`);
+        return { state, effects: [], changed: false };
+    }
+    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,
+    };
+}
 export function reduceSticky(state, action, inputs) {
     dlog(`STICKY[reducer ${headerTag(state)}] action=${action.kind}` +
         (action.kind === 'layout'
@@ -76,131 +148,13 @@ export function reduceSticky(state, action, inputs) {
             : '') +
         ` 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': {
-            // Already sitting at this value: emit nothing. Same bail-out the 'layout' case above spells
-            // out, for the same reason - React's own header gets it free from setTranslateY (an unchanged
-            // primitive bails out of the re-render), a reducer has to say it. Device-confirmed 2026-08-18:
-            // without it a re-arriving settled value emits apply-passthrough, the adapter force-renders,
-            // the passthrough prop gets a fresh identity, the animated graph reconnects and re-emits into
-            // another tick -> another debounce -> another passthrough. One header survives it; a screen of
-            // 200 trips React's "Maximum update depth exceeded" and takes the app down.
-            if (state.translateY === action.value) {
-                dlog(`STICKY[reducer ${headerTag(state)}] debounce-fired: already at translateY=${action.value}, no-op`);
-                return { state, effects: [], changed: false };
-            }
-            // 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,
-            };
-        }
+        case 'layout':
+            return handleLayout(state, action, inputs);
+        case 'inputs-changed':
+            return handleInputsChanged(state, inputs);
+        case 'animated-tick':
+            return handleAnimatedTick(state, action, inputs);
+        case 'debounce-fired':
+            return handleDebounceFired(state, action);
     }
 }

package/build/state/touchable.js

@@ -100,11 +100,9 @@ export function createTouchableFeedbackHandlers(config, runtime, callbacks) {
         },
     };
 }
-// ---- RN-audited additions (2026-08-19) --------------------------------------------------------
-//
-// Measured against .vendors/react-native. Everything above predates that audit and is still what
-// the React, Vue, Svelte and Angular adapters call; the names below are the RN-accurate forms and
-// are additive on purpose, so the tree stays green while each adapter migrates.
+// ---- RN-audited additions ----
+// Measured against .vendors/react-native. The names below are the RN-accurate forms, kept
+// additive so the tree stays green while each adapter migrates off the names above.
 // RN's Touchable* family OVERRIDES Pressability's own floor with 0 — TouchableOpacity.js:195,
 // TouchableHighlight.js:203 and TouchableWithoutFeedback.js all pass `minPressDuration: 0`. So
 // Pressability's own default of 130 (Pressability.js:264) reaches a Touchable in RN NEVER: what holds the active visual there is the Animated fade's own duration,

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

@@ -1,22 +1,12 @@
 // 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.
+// per-adapter effect skeleton into one place, so the same predicates no longer live in three
+// reactive dialects and quietly drift.
+// The whole decision half is one pure `reduceList(state, action, inputs) -> {state, effects}`. The
+// adapter keeps only what's genuinely framework-bound: translate a native event into an ACTION,
+// hold ONE state cell, and EXECUTE the returned EFFECTS with its own primitives.
+// Effect EXECUTION stays per-adapter by design — an effect list DESCRIBES the work, it doesn't run
+// it. State TRANSITIONS (including derived window metrics) are owned entirely here, so a
+// windowing/edge/viewability/MVCP bug is fixed once for all adapters.
 import { dlog } from '@symbiote-native/engine';
 import { EMPTY_OFFSET, FIRST_INDEX, NO_CONTENT_LENGTH_SENT, NO_INDEX, averageMeasuredStride, buildOffsets, computeEndReached, computeMvcpAdjustment, computeStartReached, computeViewableSet, computeWindow, decideEdgeReached, diffViewable, highestMeasuredIndex, indexOfItem, isSettledLayout, maxMinimumViewTime, offsetForEnd, offsetForIndex, resolveAverageLength, resolveItemKey, throttleWindow, initialRenderRegion, wrapFixedLayout, } from './virtualized-list.js';
 import { recordCellMove, recordListFrame, } from './virtualized-list-diagnostics.js';
@@ -132,20 +122,12 @@ function deriveMetrics(state, inputs) {
 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.
-// Reclassify the rendered cells and, if the viewable set changed, hand the adapter an info payload
-// to fire (after minimumViewTime, if any). lastViewable is folded back only when the fire actually
-// lands (the 'viewable-fired' action), so a debounce superseded mid-flight still diffs against the
-// last COMMITTED set.
-//
+// Reclassify the rendered cells and, if the viewable set changed, hand the adapter an info
+// payload to fire. lastViewable folds back only when the fire actually lands, so a debounce
+// superseded mid-flight still diffs against the last COMMITTED set.
 // Extracted from commitList because 'record-interaction' needs the same pass: RN's
-// recordInteraction() ungates waitForInteraction and calls _updateViewableItems immediately
-// (VirtualizedList.js ~288-296). Leaving the pass inline meant a list that fits its viewport and is
-// never scrolled reported nothing at all after the interaction — the next commit that would have
-// carried the report never came.
+// recordInteraction() ungates waitForInteraction immediately, and leaving this inline meant a
+// never-scrolled list reported nothing after the interaction.
 function viewabilityEffects(state, inputs) {
     const m = state.metrics;
     if (inputs.viewabilityPairs.length === EMPTY_OFFSET ||
@@ -266,15 +248,10 @@ function commitList(state, inputs) {
 // target is past the last measured cell (RN VirtualizedList.js), else scroll to the resolved offset.
 function resolveScrollToIndex(state, inputs, action) {
     const m = state.metrics;
-    // Range check FIRST, mirroring RN VirtualizedList.js (~165-178) invariant-for-invariant. Three
-    // separate messages rather than one, because an empty list and an index past the end are
-    // different diagnoses. It has to precede the onScrollToIndexFailed branch below, or an
-    // out-of-range index on a list without getItemLayout would be reported as a MEASUREMENT problem
-    // and send the reader to inspect cell layout for what is a caller bug.
-    //
-    // Note this is the one place the range is enforced: offsetForIndex() still CLAMPS, and must, since
-    // scrollToEnd and initialScrollIndex resolve through it with indices that are legitimately at or
-    // past the edge.
+    // Range check FIRST: it must precede the onScrollToIndexFailed branch below, or an out-of-range
+    // index would be reported as a MEASUREMENT problem instead of a caller bug.
+    // The one place the range is enforced: offsetForIndex() still CLAMPS, since scrollToEnd and
+    // initialScrollIndex resolve through it with indices legitimately at or past the edge.
     const itemCount = inputs.getItemCount(inputs.data);
     if (action.index < FIRST_INDEX) {
         throw new Error(`scrollToIndex out of range: requested index ${action.index} but minimum is 0`);
@@ -313,10 +290,8 @@ function resolveScrollToIndex(state, inputs, action) {
 // 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).
+        // Scalar transitions never recompute the window — metrics derive runs exactly ONCE per
+        // render, in 'refresh-metrics', or committedWindow would advance twice per frame.
         case 'scroll':
             // First scroll is the interaction that ungates waitForInteraction viewability configs.
             state.hasInteracted = true;
@@ -338,10 +313,8 @@ export function reduceList(state, action, inputs) {
             const lengthSettled = isSettledLayout(knownLength, action.length);
             const offsetSettled = action.offset === undefined ||
                 isSettledLayout(knownOffset, action.offset);
-            // Settled means "the same measurement, re-reported" — an idle onLayout, or the float noise a
-            // relayout leaves behind. Bail WITHOUT storing: keeping the settled value byte-identical is
-            // the half that matters, because the spacer derived from it then stops moving too and the
-            // relayout loop has nothing left to feed on (see LAYOUT_EPSILON).
+            // Settled means the same measurement, re-reported. Bail WITHOUT storing: keeping the value
+            // byte-identical is what stops the spacer moving and starves the relayout loop.
             if (lengthSettled && offsetSettled)
                 return { state, effects: [], changed: false };
             // Each half is stored only if IT moved: a cell that slid without resizing must not have its