@symbiote-native/components 0.3.0 → 0.4.0

package/build/scroll-view-commands.js

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

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

@@ -6,6 +6,7 @@ export interface IStickyHeaderState {
     haveReceivedInitialZeroTranslateY: boolean;
     inputRange: number[];
     outputRange: number[];
+    rangesEmitted: boolean;
 }
 export interface IStickyReducerInputs {
     os: string;

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

@@ -30,6 +30,7 @@ export function createInitialStickyState() {
         haveReceivedInitialZeroTranslateY: true,
         inputRange: [...IDENTITY_INPUT_RANGE],
         outputRange: [...IDENTITY_OUTPUT_RANGE],
+        rangesEmitted: false,
     };
 }
 // A cheap signature over the render-relevant state (the ranges + the committed translateY). The
@@ -37,6 +38,11 @@ export function createInitialStickyState() {
 export function stickyEffectSignature(state) {
     return `${state.inputRange.join(',')}|${state.outputRange.join(',')}|${state.translateY}`;
 }
+function arraysEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return a.every((value, index) => value === b[index]);
+}
 // Recompute the derived interpolation ranges off the current state + inputs (wrapping the load-bearing
 // computeStickyInterpolation math), store them, and return them for the rebuild effect.
 function deriveRanges(state, inputs) {
@@ -54,27 +60,87 @@ function deriveRanges(state, inputs) {
 }
 // The single transition every sticky-header adapter shares. The adapter maps a native event / animated
 // tick / timer fire to an action, calls this, stores the returned state, and executes the effects.
+// DIAGNOSTIC-only, gated: identifies which header instance a log line belongs to across a
+// device dump without needing full state dumps at every call — layoutY doubles as a stable
+// per-header id once measured (0 before the first layout).
+function headerTag(state) {
+    return `y=${state.layoutY}`;
+}
 export function reduceSticky(state, action, inputs) {
+    dlog(`STICKY[reducer ${headerTag(state)}] action=${action.kind}` +
+        (action.kind === 'layout' ? ` y=${action.y} height=${action.height}` : '') +
+        (action.kind === 'animated-tick' || action.kind === 'debounce-fired'
+            ? ` value=${action.value}`
+            : '') +
+        ` inputs={inverted=${inputs.inverted} scrollViewHeight=${inputs.scrollViewHeight} nextHeaderLayoutY=${inputs.nextHeaderLayoutY}}`);
     switch (action.kind) {
         case 'layout': {
             // Record own y/height, mark measured, rebuild the interpolation, and (when the reducer owns the
             // cross-talk index) hand the parent this header's y so the PREVIOUS header learns its collision
             // point. Matches RN ScrollViewStickyHeader.js._onLayout.
+            //
+            // Redundant-geometry guard: Yoga legitimately re-fires onLayout with the SAME y/height (relayout
+            // passes triggered by an unrelated sibling, a native-driven prop commit, ...) — every consumer
+            // must tolerate that. React's port gets this guard for FREE: `setLayoutY(sameValue)` is a no-op
+            // (React bails out of re-rendering on an unchanged primitive), so a redundant onLayout never
+            // reaches the rebuild `useEffect`. This reducer has no such implicit bail-out, so it must skip
+            // the rebuild explicitly — device-confirmed (2026-08-13) that omitting this guard lets a
+            // native-driven rebuild (fresh AnimatedProps/AnimatedStyle graph, fresh native connect) commit a
+            // fresh prop identity on every redundant layout, which can itself provoke another relayout pass —
+            // an unbounded same-tick rebuild ping-pong that trips Svelte's effect_update_depth_exceeded guard.
+            const alreadyAtThisGeometry = state.measured && state.layoutY === action.y && state.layoutHeight === action.height;
             state.layoutY = action.y;
             state.layoutHeight = action.height;
             state.measured = true;
-            const { inputRange, outputRange } = deriveRanges(state, inputs);
             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 }],
@@ -87,9 +153,11 @@ export function reduceSticky(state, action, inputs) {
             // 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');
+                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: [
@@ -101,6 +169,7 @@ export function reduceSticky(state, action, inputs) {
         case 'debounce-fired': {
             // The debounce completed: commit the settled translateY. Once a NON-zero value commits, re-arm
             // the swallow gate so the next interpolation rebuild's spurious 0 is dropped (RN).
+            dlog(`STICKY[reducer ${headerTag(state)}] debounce-fired: committing translateY=${action.value}`);
             state.translateY = action.value;
             if (action.value !== 0)
                 state.haveReceivedInitialZeroTranslateY = false;

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

@@ -136,8 +136,10 @@ export interface IListCellPlan {
 }
 export interface IListPlan {
     leadingExtent: number;
+    gapExtent: number;
     trailingExtent: number;
     cells: IListCellPlan[];
+    forcedStickyCell: IListCellPlan | undefined;
     stickyChildPositions: number[];
 }
 export interface IListPlanParams {

package/build/state/virtualized-list.js

@@ -56,8 +56,6 @@ function readNumber(source, key) {
 function asRecord(value) {
     return typeof value === 'object' && value !== null ? { ...value } : undefined;
 }
-// onScroll -> the offset along the scroll axis. Vertical reads contentOffset.y,
-// horizontal reads contentOffset.x.
 export function readScrollOffset(event, horizontal) {
     const native = asRecord(event.nativeEvent);
     if (native === undefined)
@@ -67,7 +65,6 @@ export function readScrollOffset(event, horizontal) {
         return undefined;
     return readNumber(offset, horizontal ? 'x' : 'y');
 }
-// onLayout -> the cross-section length of the box along the scroll axis.
 export function readLayoutLength(event, horizontal) {
     const native = asRecord(event.nativeEvent);
     if (native === undefined)
@@ -279,22 +276,50 @@ export function maxMinimumViewTime(pairs) {
     }
     return max;
 }
-// Compute the windowed child PLAN: the two spacer extents, the in-window cells (index +
-// key), and the sticky child positions. The adapter walks this plan and creates the host
-// elements (createElement / h) plus the framework cell content. This is the shared half of
-// the render; only the element creation and the user's renderItem stay per-adapter.
+// Find the nearest sticky index strictly below `first` — the RN _ensureClosestStickyHeader
+// backward walk. Returns NO_INDEX when none exists (no sticky section applies yet, or the
+// applicable one is already inside the window).
+function findClosestStickyIndexBelow(first, stickyIndices) {
+    for (let index = first - 1; index >= FIRST_INDEX; index -= 1) {
+        if (stickyIndices.has(index))
+            return index;
+    }
+    return NO_INDEX;
+}
+// Compute the windowed child PLAN: the spacer extents, the in-window cells (index + key),
+// the force-mounted sticky cell (if any) ahead of the window, and the sticky child
+// positions. The adapter walks this plan and creates the host elements (createElement / h)
+// plus the framework cell content. This is the shared half of the render; only the element
+// creation and the user's renderItem stay per-adapter.
 export function buildListPlan(params) {
     const cells = [];
-    const leadingExtent = params.first > FIRST_INDEX ? params.offsets[params.first] : EMPTY_OFFSET;
+    const closestStickyIndex = params.stickyIndices !== undefined
+        ? findClosestStickyIndexBelow(params.first, params.stickyIndices)
+        : NO_INDEX;
+    const forcedStickyCell = closestStickyIndex === NO_INDEX
+        ? undefined
+        : { index: closestStickyIndex, key: params.keyFor(closestStickyIndex) };
+    const windowLeadingExtent = params.first > FIRST_INDEX ? params.offsets[params.first] : EMPTY_OFFSET;
+    const leadingExtent = forcedStickyCell === undefined ? windowLeadingExtent : params.offsets[closestStickyIndex];
+    const gapExtent = forcedStickyCell === undefined
+        ? EMPTY_OFFSET
+        : windowLeadingExtent -
+            params.offsets[closestStickyIndex] -
+            params.lengths[closestStickyIndex];
     const renderedExtent = params.last >= params.first
         ? params.offsets[params.last] + params.lengths[params.last] - params.offsets[params.first]
         : EMPTY_OFFSET;
-    const trailingExtent = params.total - leadingExtent - renderedExtent;
+    const trailingExtent = params.total - windowLeadingExtent - renderedExtent;
     const stickyChildPositions = [];
     // The header (when present) is child 0; the leading spacer (when non-empty) is the next
-    // child. Each cell is one child; a separator after it (when ItemSeparatorComponent is set
-    // and this is not the last cell) is another.
+    // child; the forced sticky cell (when present) plus its own gap spacer follow. Each cell
+    // is one child; a separator after it (when ItemSeparatorComponent is set and this is not
+    // the last cell) is another.
     let childPosition = (params.hasHeader ? 1 : 0) + (leadingExtent > EMPTY_OFFSET ? 1 : 0);
+    if (forcedStickyCell !== undefined) {
+        stickyChildPositions.push(childPosition);
+        childPosition += 1 + (gapExtent > EMPTY_OFFSET ? 1 : 0);
+    }
     for (let index = params.first; index <= params.last; index += 1) {
         cells.push({ index, key: params.keyFor(index) });
         if (params.stickyIndices?.has(index) === true)
@@ -303,7 +328,14 @@ export function buildListPlan(params) {
         if (params.hasSeparators && index < params.last)
             childPosition += 1;
     }
-    return { leadingExtent, trailingExtent, cells, stickyChildPositions };
+    return {
+        leadingExtent,
+        gapExtent,
+        trailingExtent,
+        cells,
+        forcedStickyCell,
+        stickyChildPositions,
+    };
 }
 export function computeMvcpAdjustment(params) {
     const { minIndexForVisible, count, keyFor } = params;

package/build/view/render-button.js

@@ -1,7 +1,6 @@
-// Button: the shared render half (framework-agnostic). Rendered in RN's iOS shape (Button.js): a
-// TouchableOpacity wrapping a Text. The pure pieces: the base text style, the role constant, and
-// the color fold (caller color tints the label; disabled greys it) live here so every adapter
-// paints the identical button. The adapter only composes its TouchableOpacity + Text around them.
+// Button: shared render half (framework-agnostic), matching RN's iOS shape (Button.js): a
+// TouchableOpacity wrapping a Text. Each adapter composes its own TouchableOpacity + Text
+// around the pieces below.
 const IOS_BUTTON_BLUE = '#007AFF';
 const IOS_DISABLED_GREY = '#cdcdcd';
 // RN's Button is accessibilityRole="button"; the role string is a native accessibility enum value.

package/package.json

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

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

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

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

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

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

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

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

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