@symbiote-native/angular 0.6.2 → 0.8.0

package/src/components/virtualized-list/index.ts

@@ -35,9 +35,12 @@ import {
   Input,
   Output,
   ViewChild,
+  computed,
   inject,
+  signal,
   type AfterViewChecked,
   type DoCheck,
+  type OnChanges,
   type OnDestroy,
 } from '@angular/core';
 import {
@@ -53,10 +56,12 @@ import {
   INVERTED_Y_STYLE,
   buildListPlan,
   buildViewabilityPairs,
+  computeWindow,
   createInitialListState,
   isSeparatorGapInRange,
   listEffectSignature,
   readLayoutLength,
+  readLayoutOffset,
   readScrollOffset,
   reduceList,
   resolveAccessibilityProps,
@@ -84,9 +89,14 @@ import {
   type ISymbioteNode,
   type IViewStyle,
 } from '@symbiote-native/engine';
+import { countAngular } from '../../diagnostics';
 import { ScrollView } from '../scroll-view';
 import { RefreshControl } from '../refresh-control';
-import { anchorHostStyle, ViewHost } from '../../primitives';
+import {
+  anchorHostStyle,
+  SymbioteStyleInputDirective,
+  ViewHost,
+} from '../../primitives';
 import {
   VListEmptyDirective,
   VListFooterDirective,
@@ -123,7 +133,8 @@ export type { IVListItemContext, IVListSeparatorContext } from './directives';
 // element-returning props (renderItem, ListHeader/Footer/Empty Component, ItemSeparatorComponent):
 // those are the per-adapter children/render fields and become `<ng-template>` directives in Angular.
 // Everything agnostic is the SAME surface.
-export interface IVirtualizedListProps<ItemT> extends IAccessibilityProps, IAriaProps {
+export interface IVirtualizedListProps<ItemT>
+  extends IAccessibilityProps, IAriaProps {
   data: unknown;
   getItem: (data: unknown, index: number) => ItemT;
   getItemCount: (data: unknown) => number;
@@ -202,6 +213,9 @@ interface IWindowCell<ItemT> {
 @Component({
   selector: 'VirtualizedList',
   standalone: true,
+  hostDirectives: [
+    { directive: SymbioteStyleInputDirective, inputs: ['style'] },
+  ],
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
   imports: [ScrollView, RefreshControl, VListOutletDirective, ViewHost],
   changeDetection: ChangeDetectionStrategy.OnPush,
@@ -210,30 +224,40 @@ interface IWindowCell<ItemT> {
       [horizontal]="isHorizontal"
       [style]="resolvedStyle"
       [contentContainerStyle]="resolvedContentContainerStyle"
-      [testID]="foldedAccessibility.testID"
-      [nativeID]="foldedAccessibility.nativeID"
-      [accessible]="foldedAccessibility.accessible"
-      [accessibilityLabel]="foldedAccessibility.accessibilityLabel"
-      [accessibilityHint]="foldedAccessibility.accessibilityHint"
-      [accessibilityRole]="foldedAccessibility.accessibilityRole"
-      [accessibilityState]="foldedAccessibility.accessibilityState"
-      [accessibilityValue]="foldedAccessibility.accessibilityValue"
-      [accessibilityActions]="foldedAccessibility.accessibilityActions"
-      [accessibilityLabelledBy]="foldedAccessibility.accessibilityLabelledBy"
-      [importantForAccessibility]="foldedAccessibility.importantForAccessibility"
-      [accessibilityLiveRegion]="foldedAccessibility.accessibilityLiveRegion"
-      [screenReaderFocusable]="foldedAccessibility.screenReaderFocusable"
-      [accessibilityViewIsModal]="foldedAccessibility.accessibilityViewIsModal"
-      [accessibilityElementsHidden]="foldedAccessibility.accessibilityElementsHidden"
-      [accessibilityIgnoresInvertColors]="foldedAccessibility.accessibilityIgnoresInvertColors"
-      [accessibilityLanguage]="foldedAccessibility.accessibilityLanguage"
+      [testID]="foldedAccessibility().testID"
+      [nativeID]="foldedAccessibility().nativeID"
+      [accessible]="foldedAccessibility().accessible"
+      [accessibilityLabel]="foldedAccessibility().accessibilityLabel"
+      [accessibilityHint]="foldedAccessibility().accessibilityHint"
+      [accessibilityRole]="foldedAccessibility().accessibilityRole"
+      [accessibilityState]="foldedAccessibility().accessibilityState"
+      [accessibilityValue]="foldedAccessibility().accessibilityValue"
+      [accessibilityActions]="foldedAccessibility().accessibilityActions"
+      [accessibilityLabelledBy]="foldedAccessibility().accessibilityLabelledBy"
+      [importantForAccessibility]="
+        foldedAccessibility().importantForAccessibility
+      "
+      [accessibilityLiveRegion]="foldedAccessibility().accessibilityLiveRegion"
+      [screenReaderFocusable]="foldedAccessibility().screenReaderFocusable"
+      [accessibilityViewIsModal]="
+        foldedAccessibility().accessibilityViewIsModal
+      "
+      [accessibilityElementsHidden]="
+        foldedAccessibility().accessibilityElementsHidden
+      "
+      [accessibilityIgnoresInvertColors]="
+        foldedAccessibility().accessibilityIgnoresInvertColors
+      "
+      [accessibilityLanguage]="foldedAccessibility().accessibilityLanguage"
       [accessibilityRespondsToUserInteraction]="
-        foldedAccessibility.accessibilityRespondsToUserInteraction
+        foldedAccessibility().accessibilityRespondsToUserInteraction
       "
       [accessibilityShowsLargeContentViewer]="
-        foldedAccessibility.accessibilityShowsLargeContentViewer
+        foldedAccessibility().accessibilityShowsLargeContentViewer
+      "
+      [accessibilityLargeContentTitle]="
+        foldedAccessibility().accessibilityLargeContentTitle
       "
-      [accessibilityLargeContentTitle]="foldedAccessibility.accessibilityLargeContentTitle"
       (accessibilityAction)="accessibilityActionTick($event)"
       (accessibilityTap)="accessibilityTapTick($event)"
       (magicTap)="magicTapTick($event)"
@@ -275,21 +299,43 @@ interface IWindowCell<ItemT> {
         @if (leadingSpacerStyle !== null) {
           <symbiote-view [style]="leadingSpacerStyle"></symbiote-view>
         }
+        @if (forcedStickyCell !== null) {
+          <symbiote-view
+            (layout)="handleCellLayout(forcedStickyCell.measure, $event)"
+            [style]="cellStyle"
+          >
+            <ng-container
+              [vListOutlet]="itemDir?.templateRef"
+              [vListOutletContext]="forcedStickyCell.context"
+            ></ng-container>
+          </symbiote-view>
+        }
+        @if (gapSpacerStyle !== null) {
+          <symbiote-view [style]="gapSpacerStyle"></symbiote-view>
+        }
+        <!-- The separator sits INSIDE the measuring view, as RN's own cell renderer places it
+             (VirtualizedListCellRenderer.js:218-221). As a sibling it is an extra flex child, so
+             the chrome between two cells is gap + separator + gap while a spacer collapsing that
+             region replaces it with a single gap — every cell below the leading spacer then lands
+             short by (separator + gap) and the content jumps by that much whenever the window's
+             first index moves. Measured at exactly 17px on device 2026-08-19; see
+             .claude/rules/list-geometry-feedback-loop.md. -->
         @for (cell of windowCells; track cell.key) {
-          <symbiote-view (layout)="handleCellLayout(cell.measure, $event)" [style]="cellStyle">
+          <symbiote-view
+            (layout)="handleCellLayout(cell.measure, $event)"
+            [style]="cellStyle"
+          >
             <ng-container
               [vListOutlet]="itemDir?.templateRef"
               [vListOutletContext]="cell.context"
             ></ng-container>
-          </symbiote-view>
-          @if (cell.separatorContext !== undefined) {
-            <symbiote-view>
+            @if (cell.separatorContext !== undefined) {
               <ng-container
                 [vListOutlet]="separatorDir?.templateRef"
                 [vListOutletContext]="cell.separatorContext"
               ></ng-container>
-            </symbiote-view>
-          }
+            }
+          </symbiote-view>
         }
         @if (trailingSpacerStyle !== null) {
           <symbiote-view [style]="trailingSpacerStyle"></symbiote-view>
@@ -310,15 +356,22 @@ export class VirtualizedList<ItemT = unknown>
     IVirtualizedListHandle,
     DoCheck,
     AfterViewChecked,
+    OnChanges,
     OnDestroy
 {
   // The list's edge/viewability/failure events as real Angular events: `(endReached)="…"`, not
   // `[onEndReached]="…"`. See handleRefresh/accessibility*Tick below for how the still-callback-
   // shaped ScrollView/RefreshControl @Input()s are fed from these.
-  @Output() readonly endReached = new EventEmitter<{ distanceFromEnd: number }>();
-  @Output() readonly startReached = new EventEmitter<{ distanceFromStart: number }>();
+  @Output() readonly endReached = new EventEmitter<{
+    distanceFromEnd: number;
+  }>();
+  @Output() readonly startReached = new EventEmitter<{
+    distanceFromStart: number;
+  }>();
   @Output() readonly refresh = new EventEmitter<void>();
-  @Output() readonly viewableItemsChanged = new EventEmitter<IViewableItemsChangedInfo<ItemT>>();
+  @Output() readonly viewableItemsChanged = new EventEmitter<
+    IViewableItemsChangedInfo<ItemT>
+  >();
   @Output() readonly scrollToIndexFailed = new EventEmitter<{
     index: number;
     highestMeasuredFrameIndex: number;
@@ -352,7 +405,8 @@ export class VirtualizedList<ItemT = unknown>
   // (no wrapper) falls back to this component's own `.observed`, unchanged from before.
   @Input() refreshRequested?: boolean;
   @Input() viewabilityConfig?: IViewabilityConfig;
-  @Input() viewabilityConfigCallbackPairs?: IViewabilityConfigCallbackPair<ItemT>[];
+  @Input()
+  viewabilityConfigCallbackPairs?: IViewabilityConfigCallbackPair<ItemT>[];
   @Input() initialNumToRender?: number;
   @Input() initialScrollIndex?: number;
   @Input() maxToRenderPerBatch?: number;
@@ -383,8 +437,10 @@ export class VirtualizedList<ItemT = unknown>
   @Input() accessibilityValue?: IAccessibilityProps['accessibilityValue'];
   @Input() accessibilityActions?: IAccessibilityProps['accessibilityActions'];
   @Input() accessibilityLabelledBy?: string | string[];
-  @Input() importantForAccessibility?: IAccessibilityProps['importantForAccessibility'];
-  @Input() accessibilityLiveRegion?: IAccessibilityProps['accessibilityLiveRegion'];
+  @Input()
+  importantForAccessibility?: IAccessibilityProps['importantForAccessibility'];
+  @Input()
+  accessibilityLiveRegion?: IAccessibilityProps['accessibilityLiveRegion'];
   @Input() screenReaderFocusable?: boolean;
   @Input() accessibilityViewIsModal?: boolean;
   @Input() accessibilityElementsHidden?: boolean;
@@ -416,7 +472,8 @@ export class VirtualizedList<ItemT = unknown>
   @ContentChild(VListHeaderDirective) headerDir?: VListHeaderDirective;
   @ContentChild(VListFooterDirective) footerDir?: VListFooterDirective;
   @ContentChild(VListEmptyDirective) emptyDir?: VListEmptyDirective;
-  @ContentChild(VListSeparatorDirective) separatorDir?: VListSeparatorDirective<ItemT>;
+  @ContentChild(VListSeparatorDirective)
+  separatorDir?: VListSeparatorDirective<ItemT>;
 
   // The composed inner scroll view. Its instance IS an IScrollViewHandle (scrollTo / scrollToEnd /
   // flashScrollIndicators / getScrollNode), so the imperative handle delegates straight to it.
@@ -426,7 +483,13 @@ export class VirtualizedList<ItemT = unknown>
   // --- template-bound view state, assembled in ngDoCheck (recomputeView) ---
   itemCount = EMPTY_OFFSET;
   windowCells: IWindowCell<ItemT>[] = [];
+  // The nearest sticky-header cell force-mounted outside [first,last] (plan.forcedStickyCell), the
+  // Angular twin of RN's _ensureClosestStickyHeader. Rendered ahead of windowCells, right after the
+  // leading spacer, with gapSpacerStyle filling the gap to the window's own first cell — see
+  // buildListPlan's doc comment for the exact child order this assumes.
+  forcedStickyCell: IWindowCell<ItemT> | null = null;
   leadingSpacerStyle: IViewStyle | null = null;
+  gapSpacerStyle: IViewStyle | null = null;
   trailingSpacerStyle: IViewStyle | null = null;
   cellStyle: IViewStyle | undefined = undefined;
   renderedStickyIndices: number[] | undefined = undefined;
@@ -437,7 +500,8 @@ export class VirtualizedList<ItemT = unknown>
   resolvedStyle: IViewStyle | undefined = undefined;
   resolvedContentContainerStyle: IStyleProp<IViewStyle> | undefined = undefined;
   resolvedMaintainVisibleContentPosition:
-    { minIndexForVisible: number; autoscrollToTopThreshold?: number } | undefined = undefined;
+    | { minIndexForVisible: number; autoscrollToTopThreshold?: number }
+    | undefined = undefined;
   // The offset we are imperatively driving native to before the scroll handle attaches (rides down
   // as contentOffset). A fresh object identity each push so the commit re-applies a repeated value.
   commandedOffset: { x: number; y: number } | undefined = undefined;
@@ -446,11 +510,35 @@ export class VirtualizedList<ItemT = unknown>
   // measured lengths, committed window, edge/viewability dedup, MVCP anchor — all in IListState,
   // driven by the shared reduceList. `renderVersion` bumps whenever a transition changes render
   // state, so ngDoCheck's recompute-dedup can detect it (listState is a plain object, not tracked).
-  private readonly listState: IListState<ItemT> = createInitialListState<ItemT>();
+  private readonly listState: IListState<ItemT> =
+    createInitialListState<ItemT>();
   private renderVersion = EMPTY_OFFSET;
 
-  private readonly cellMeasures = new Map<number, (event: ISymbioteEvent) => void>();
-  private readonly separatorOverrides = new Map<number, Partial<ISeparatorProps<unknown>>>();
+  private readonly cellMeasures = new Map<
+    number,
+    (event: ISymbioteEvent) => void
+  >();
+  // A cell's context object is the ONLY thing its stamped view reads, and VListOutletDirective
+  // refreshes that view whenever the object's IDENTITY changes. recomputeView runs on every frame
+  // the window moves, so minting a fresh context per cell made a four-row slide cost a refresh of
+  // EVERY cell in the window. MEASURED on PATH B geometry (544 entries, 320px viewport, RN
+  // defaults), per fling frame: 233-cell window, 4 cells genuinely entering, 228 outlet updates —
+  // each one a copyContextFields plus a markForCheck that walks to the root. Solid, same geometry,
+  // same shared reducer, same engine output: 4. Handing back the SAME object for a cell whose item
+  // and index did not move keeps `[vListOutletContext]` reference-equal, so ngOnChanges never fires
+  // for it. The fast adapters get this by construction — Solid's <For> is keyed on the cell KEY
+  // strings precisely so "the plan's freshly-built cell objects" cannot rebuild every row
+  // (adapters/solid/src/components/virtualized-list/shared.tsx, the cellKeys memo).
+  private cellContexts = new Map<string, IVListItemContext<ItemT>>();
+  private nextCellContexts = new Map<string, IVListItemContext<ItemT>>();
+  // Everything a cell's CONTENT can depend on that is not its own item identity. RN's contract for
+  // "re-render the cells, the data object itself did not change" is extraData; without it here an
+  // extraData flip would reuse every context and repaint nothing.
+  private cellContextEpoch: unknown[] | undefined = undefined;
+  private readonly separatorOverrides = new Map<
+    number,
+    Partial<ISeparatorProps<unknown>>
+  >();
   // The adapter-owned debounce (minimumViewTime) and incremental-fill timers; the reducer only
   // hands back a delay.
   private viewableTimer: ReturnType<typeof setTimeout> | null = null;
@@ -476,7 +564,27 @@ export class VirtualizedList<ItemT = unknown>
   // inner `<ScrollView>` one level down (itself its own separate anchor host).
   private readonly elementRef = inject(ElementRef);
 
-  get foldedAccessibility(): IAccessibilityProps & IAriaProps & Record<string, unknown> {
+  // Bridges the non-reactive @Input fields into the reactive graph so the computed below can
+  // memoize a bag derived from them (the same bridge ScrollView's shared.ts uses - read its comment
+  // for why signal inputs are not an option while this package's unit suite runs on JIT).
+  //
+  // ONLY safe for a bag whose every dependency is an @Input. This list's window machinery
+  // (listState, renderVersion, windowCells, the measured metrics) is driven from scroll/layout
+  // callbacks that never touch ngOnChanges, so nothing derived from it may ride this signal - it
+  // would memoize a window that stops re-computing mid-scroll. Make that state its own signal
+  // instead of widening this one.
+  private readonly inputsRevision = signal(0);
+
+  // MEASURED: the template feeds 20 separate <ScrollView> inputs off this one bag, and Angular does
+  // not cache a getter across binding expressions - as a getter it rebuilt the object 20 times per
+  // refresh, and every consumer saw a fresh reference, so all 20 reported "changed" and wrote
+  // through to the ScrollView. A computed evaluates once and hands back the SAME object until an
+  // input actually changes. Every dependency below is an @Input, which is what makes
+  // inputsRevision a complete dependency set here.
+  readonly foldedAccessibility = computed<
+    IAccessibilityProps & IAriaProps & Record<string, unknown>
+  >(() => {
+    this.inputsRevision();
     return resolveAccessibilityProps({
       testID: this.testID,
       nativeID: this.nativeID,
@@ -495,8 +603,10 @@ export class VirtualizedList<ItemT = unknown>
       accessibilityElementsHidden: this.accessibilityElementsHidden,
       accessibilityIgnoresInvertColors: this.accessibilityIgnoresInvertColors,
       accessibilityLanguage: this.accessibilityLanguage,
-      accessibilityRespondsToUserInteraction: this.accessibilityRespondsToUserInteraction,
-      accessibilityShowsLargeContentViewer: this.accessibilityShowsLargeContentViewer,
+      accessibilityRespondsToUserInteraction:
+        this.accessibilityRespondsToUserInteraction,
+      accessibilityShowsLargeContentViewer:
+        this.accessibilityShowsLargeContentViewer,
       accessibilityLargeContentTitle: this.accessibilityLargeContentTitle,
       role: this.role,
       'aria-label': this.ariaLabel,
@@ -514,7 +624,7 @@ export class VirtualizedList<ItemT = unknown>
       'aria-valuenow': this.ariaValueNow,
       'aria-valuetext': this.ariaValueText,
     });
-  }
+  });
 
   get shouldRenderRefreshControl(): boolean {
     return this.refreshRequested ?? this.refresh.observed;
@@ -536,7 +646,9 @@ export class VirtualizedList<ItemT = unknown>
     return this.maxToRenderPerBatch ?? DEFAULT_MAX_TO_RENDER_PER_BATCH;
   }
   private get updateCellsBatchingPeriodValue(): number {
-    return this.updateCellsBatchingPeriod ?? DEFAULT_UPDATE_CELLS_BATCHING_PERIOD;
+    return (
+      this.updateCellsBatchingPeriod ?? DEFAULT_UPDATE_CELLS_BATCHING_PERIOD
+    );
   }
   private get onEndReachedThresholdValue(): number {
     return this.onEndReachedThreshold ?? DEFAULT_END_REACHED_THRESHOLD;
@@ -549,6 +661,7 @@ export class VirtualizedList<ItemT = unknown>
   // flow through it, which an @Output() can't carry), so this is a stable arrow field passed
   // straight to [onScroll]. onLayout is a real @Output() now, bound via (layout)="onLayoutTick($event)".
   onScrollTick = (event: ISymbioteEvent): void => {
+    countAngular('scrollTicks');
     const offset = readScrollOffset(event, this.isHorizontal);
     if (offset === undefined) return;
     dlog(`Angular VirtualizedList onScroll offset=${offset}`);
@@ -615,7 +728,8 @@ export class VirtualizedList<ItemT = unknown>
       onStartReachedActive: this.startReached.observed,
       viewabilityPairs: buildViewabilityPairs(
         this.viewableItemsChanged.observed
-          ? (info: IViewableItemsChangedInfo<ItemT>): void => this.viewableItemsChanged.emit(info)
+          ? (info: IViewableItemsChangedInfo<ItemT>): void =>
+              this.viewableItemsChanged.emit(info)
           : undefined,
         this.viewabilityConfig,
         this.viewabilityConfigCallbackPairs,
@@ -631,13 +745,60 @@ export class VirtualizedList<ItemT = unknown>
     const inputs = this.buildInputs();
     const result = reduceList(this.listState, action, inputs);
     this.runEffects(result.effects, inputs);
-    if (result.changed) {
-      this.renderVersion += 1;
-      this.cdr.markForCheck();
-    }
+    if (!result.changed) return;
+    this.renderVersion += 1;
+    if (this.isWindowSettled(action)) return;
+    countAngular('listMarks');
+    this.cdr.markForCheck();
   }
 
-  private runEffects(effects: IListEffect<ItemT>[], inputs: IListReducerInputs<ItemT>): void {
+  // The reducer reports `changed` for EVERY scroll offset - it has to, since the offset feeds
+  // end-reached distance, viewability and the batch-fill timer, all handled by runEffects. The
+  // TEMPLATE reads none of those; it reads the window. Marking on the offset repainted the whole
+  // ancestor chain 60 times a second on a sticky screen for a window that had not moved.
+  //
+  // So the question here is "would a render leave the window exactly where it is", and it is asked
+  // of the state as it is NOW. It must NOT be answered by comparing the last-rendered window with
+  // the one before it: that window was derived from the PREVIOUS scroll offset, so once two
+  // consecutive derives agree the comparison reads "settled" for every offset that ever follows -
+  // no mark, no CD, no ngDoCheck, no refresh-metrics, so the window can never move again and the
+  // list goes permanently deaf mid-scroll (device: examples/angular Benchmark sticky path B froze
+  // at exactly the window the first viewport asked for, blank below it).
+  //
+  // computeWindow re-run over the CACHED offset table answers it directly. Two scans, no
+  // allocation - buildOffsets, the O(count) allocating half, still runs once per render only. It is
+  // the same function the render will use, so this cannot drift away from the window it predicts.
+  private isWindowSettled(action: IListAction<ItemT>): boolean {
+    // A measurement rewrites the very offset table the prediction reads, so it has no cached
+    // geometry to answer from.
+    if (action.kind === 'measure') return false;
+    const m = this.listState.metrics;
+    // Mid-fill: the committed window is still climbing toward target one batch step per render, and
+    // only a render advances it. Skipping the mark here is what stalls the incremental fill.
+    if (m.first !== m.target.first || m.last !== m.target.last) return false;
+    const next = computeWindow(
+      m.count,
+      m.offsets,
+      m.lengths,
+      this.listState.scrollOffset,
+      this.listState.viewportLength,
+      this.windowSizeValue,
+      this.initialNumToRenderValue,
+    );
+    const isSettled =
+      next.first === m.target.first && next.last === m.target.last;
+    if (!isSettled)
+      dlog(
+        `Angular VirtualizedList window moves [${m.first}, ${m.last}] -> ` +
+          `[${next.first}, ${next.last}] at offset ${this.listState.scrollOffset}`,
+      );
+    return isSettled;
+  }
+
+  private runEffects(
+    effects: IListEffect<ItemT>[],
+    inputs: IListReducerInputs<ItemT>,
+  ): void {
     for (const effect of effects) {
       switch (effect.kind) {
         case 'scroll-to':
@@ -647,7 +808,9 @@ export class VirtualizedList<ItemT = unknown>
           this.endReached.emit({ distanceFromEnd: effect.distanceFromEnd });
           break;
         case 'fire-start-reached':
-          this.startReached.emit({ distanceFromStart: effect.distanceFromStart });
+          this.startReached.emit({
+            distanceFromStart: effect.distanceFromStart,
+          });
           break;
         case 'fire-scroll-to-index-failed':
           this.scrollToIndexFailed.emit({
@@ -690,6 +853,14 @@ export class VirtualizedList<ItemT = unknown>
     }
   }
 
+  // foldedAccessibility reads plain @Input fields, which are NOT reactive on their own - this bump
+  // is what tells that computed an input changed. It must stay in ngOnChanges: that is the single
+  // moment Angular has finished writing every changed input for this pass, and it runs before
+  // ngDoCheck below, so the recompute already sees the current values.
+  ngOnChanges(): void {
+    this.inputsRevision.update(revision => revision + 1);
+  }
+
   // Once-per-CD recompute, BEFORE the template bindings are read (so the freshly computed
   // template-bound fields render this pass — computing them in ngAfterContentChecked instead would
   // trip ExpressionChangedAfterItHasBeenChecked). The dedup guard runs refresh-metrics (which owns
@@ -697,6 +868,7 @@ export class VirtualizedList<ItemT = unknown>
   // grows exactly one step per meaningful CD. The projected templates (ContentChild) are resolved
   // from the second CD on; the first paint (count/viewport still 0) corrects on the layout-driven CD.
   ngDoCheck(): void {
+    countAngular('listChecks');
     const recomputeInputs: unknown[] = [
       this.data,
       this.extraData,
@@ -710,6 +882,10 @@ export class VirtualizedList<ItemT = unknown>
       this.stickyHeaderIndices,
       this.maintainVisibleContentPosition,
       this.style,
+      // `recomputeView` folds this into the committed style, but it arrives through
+      // addClass/removeClass, never as an @Input - so without it here no entry moves on a class
+      // toggle and the gate skips the recompute forever. Reference-stable, so the dedup holds.
+      anchorHostStyle(this.elementRef),
       this.contentContainerStyle,
       // Folds scroll / layout / measure / batch-tick: dispatch bumps renderVersion on any change.
       this.renderVersion,
@@ -728,6 +904,7 @@ export class VirtualizedList<ItemT = unknown>
       return;
     }
     // The single derive-per-CD: recompute the window off the current state before the view reads it.
+    countAngular('listRecomputes');
     reduceList(this.listState, { kind: 'refresh-metrics' }, this.buildInputs());
     this.recomputeView();
   }
@@ -752,7 +929,9 @@ export class VirtualizedList<ItemT = unknown>
     const hasHeader = this.headerDir !== undefined;
     const hasSeparators = this.separatorDir !== undefined;
     const stickySet =
-      this.stickyHeaderIndices !== undefined ? new Set(this.stickyHeaderIndices) : undefined;
+      this.stickyHeaderIndices !== undefined
+        ? new Set(this.stickyHeaderIndices)
+        : undefined;
 
     this.resolvedContentContainerStyle = this.isHorizontal
       ? [this.contentContainerStyle, { width: m.total }]
@@ -774,15 +953,40 @@ export class VirtualizedList<ItemT = unknown>
         : {
             ...this.maintainVisibleContentPosition,
             minIndexForVisible:
-              this.maintainVisibleContentPosition.minIndexForVisible + (hasHeader ? 1 : 0),
+              this.maintainVisibleContentPosition.minIndexForVisible +
+              (hasHeader ? 1 : 0),
           };
 
+    // A change in anything a cell's content reads other than its own item invalidates every cached
+    // context: identity reuse is only sound while the reused object still describes the cell.
+    const epoch: unknown[] = [
+      this.data,
+      this.extraData,
+      this.getItem,
+      this.keyExtractor,
+    ];
+    const previousEpoch = this.cellContextEpoch;
+    this.cellContextEpoch = epoch;
+    if (
+      previousEpoch === undefined ||
+      previousEpoch.length !== epoch.length ||
+      !previousEpoch.every((value, index) => value === epoch[index])
+    ) {
+      this.cellContexts.clear();
+    }
+
     if (m.count === FIRST_INDEX) {
+      this.cellContexts.clear();
+      this.nextCellContexts.clear();
       this.windowCells = [];
+      this.forcedStickyCell = null;
       this.leadingSpacerStyle = null;
+      this.gapSpacerStyle = null;
       this.trailingSpacerStyle = null;
       this.renderedStickyIndices = undefined;
-      dlog(`Angular VirtualizedList empty (viewport=${this.listState.viewportLength})`);
+      dlog(
+        `Angular VirtualizedList empty (viewport=${this.listState.viewportLength})`,
+      );
       return;
     }
 
@@ -796,38 +1000,54 @@ export class VirtualizedList<ItemT = unknown>
       keyFor: this.keyFor,
       stickyIndices: stickySet,
       hasHeader,
-      hasSeparators,
     });
     this.leadingSpacerStyle =
-      plan.leadingExtent > EMPTY_OFFSET ? this.spacerStyle(plan.leadingExtent) : null;
+      plan.leadingExtent > EMPTY_OFFSET
+        ? this.spacerStyle(plan.leadingExtent)
+        : null;
+    this.gapSpacerStyle =
+      plan.gapExtent > EMPTY_OFFSET ? this.spacerStyle(plan.gapExtent) : null;
     this.trailingSpacerStyle =
-      plan.trailingExtent > EMPTY_OFFSET ? this.spacerStyle(plan.trailingExtent) : null;
+      plan.trailingExtent > EMPTY_OFFSET
+        ? this.spacerStyle(plan.trailingExtent)
+        : null;
     this.renderedStickyIndices =
       stickySet !== undefined && plan.stickyChildPositions.length > 0
         ? plan.stickyChildPositions
         : undefined;
+    dlog(
+      `STICKY[list] stickySet=${stickySet === undefined ? 'undefined' : JSON.stringify([...stickySet])} ` +
+        `childPositions=${JSON.stringify(plan.stickyChildPositions)} ` +
+        `forcedStickyCell=${plan.forcedStickyCell === undefined ? 'none' : plan.forcedStickyCell.index} ` +
+        `window=[${m.first},${m.last}] hasHeader=${this.headerDir !== undefined}`,
+    );
+
+    this.forcedStickyCell =
+      plan.forcedStickyCell !== undefined
+        ? this.buildWindowCell(
+            plan.forcedStickyCell.index,
+            plan.forcedStickyCell.key,
+            false,
+          )
+        : null;
 
     const cells: IWindowCell<ItemT>[] = [];
     for (const planned of plan.cells) {
-      const item = this.getItem(this.data, planned.index);
-      const context: IVListItemContext<ItemT> = {
-        $implicit: item,
-        index: planned.index,
-        separators: this.makeSeparators(planned.index),
-      };
-      let separatorContext: IVListSeparatorContext<ItemT> | undefined;
-      if (hasSeparators && planned.index < m.last) {
-        separatorContext = this.buildSeparatorContext(planned.index, item);
-      }
-      cells.push({
-        key: planned.key,
-        index: planned.index,
-        context,
-        measure: this.cellMeasure(planned.index),
-        separatorContext,
-      });
+      // RN gates the separator on the last index of the DATA, not of the WINDOW
+      // (VirtualizedList.js:793 `const end = getItemCount(data) - 1`), and now that the separator
+      // lives INSIDE the measuring wrapper that distinction is load-bearing: gating on the window
+      // would make a cell's own measured height change as the window slides past it. Device-measured
+      // 2026-08-19 as a run of cells all shifting by exactly the divider's 1px.
+      const includeSeparator = hasSeparators && planned.index < m.count - 1;
+      cells.push(
+        this.buildWindowCell(planned.index, planned.key, includeSeparator),
+      );
     }
     this.windowCells = cells;
+    // Swap, don't prune: a cell that left the window is simply absent from the pass that just ran,
+    // so the old map is the garbage and the new one is exactly the live set.
+    this.cellContexts = this.nextCellContexts;
+    this.nextCellContexts = new Map<string, IVListItemContext<ItemT>>();
 
     dlog(
       `Angular VirtualizedList window [${m.first}, ${m.last}] of ${m.count} ` +
@@ -835,7 +1055,53 @@ export class VirtualizedList<ItemT = unknown>
     );
   }
 
-  private buildSeparatorContext(index: number, item: ItemT): IVListSeparatorContext<ItemT> {
+  // Assembles one cell (window or forced-sticky) — the context, measure closure, and optional
+  // separator context — so both plan.cells and plan.forcedStickyCell build identically.
+  private buildWindowCell(
+    index: number,
+    key: string,
+    includeSeparator: boolean,
+  ): IWindowCell<ItemT> {
+    const item = this.getItem(this.data, index);
+    return {
+      key,
+      index,
+      context: this.contextFor(key, index, item),
+      measure: this.cellMeasure(index),
+      separatorContext: includeSeparator
+        ? this.buildSeparatorContext(index, item)
+        : undefined,
+    };
+  }
+
+  // The context for one cell, reused by identity when the cell did not move. See cellContexts.
+  private contextFor(
+    key: string,
+    index: number,
+    item: ItemT,
+  ): IVListItemContext<ItemT> {
+    const cached = this.cellContexts.get(key);
+    if (
+      cached !== undefined &&
+      cached.$implicit === item &&
+      cached.index === index
+    ) {
+      this.nextCellContexts.set(key, cached);
+      return cached;
+    }
+    const context: IVListItemContext<ItemT> = {
+      $implicit: item,
+      index,
+      separators: this.makeSeparators(index),
+    };
+    this.nextCellContexts.set(key, context);
+    return context;
+  }
+
+  private buildSeparatorContext(
+    index: number,
+    item: ItemT,
+  ): IVListSeparatorContext<ItemT> {
     const overrides = this.separatorOverrides.get(index);
     const highlighted = overrides?.highlighted ?? false;
     const context: IVListSeparatorContext<ItemT> = {
@@ -848,7 +1114,12 @@ export class VirtualizedList<ItemT = unknown>
     // arbitrary separator props); the typed fields above stay authoritative.
     if (overrides !== undefined) {
       for (const key of Object.keys(overrides)) {
-        if (key === 'highlighted' || key === 'leadingItem' || key === 'trailingItem') continue;
+        if (
+          key === 'highlighted' ||
+          key === 'leadingItem' ||
+          key === 'trailingItem'
+        )
+          continue;
         context[key] = overrides[key];
       }
     }
@@ -865,10 +1136,13 @@ export class VirtualizedList<ItemT = unknown>
     const measure = (event: ISymbioteEvent): void => {
       const length = readLayoutLength(event, this.isHorizontal);
       if (length === undefined) return;
-      dlog(`Angular VirtualizedList cell ${index} measured length=${length}`);
+      const offset = readLayoutOffset(event, this.isHorizontal);
+      dlog(
+        `Angular VirtualizedList cell ${index} measured length=${length} offset=${offset ?? 'none'}`,
+      );
       // The reducer guards a fixed getItemLayout and a repeated length; a no-op leaves state and the
       // view untouched (dispatch marks for check only when something changed).
-      this.dispatch({ kind: 'measure', index, length });
+      this.dispatch({ kind: 'measure', index, length, offset });
     };
     this.cellMeasures.set(index, measure);
     return measure;
@@ -876,18 +1150,29 @@ export class VirtualizedList<ItemT = unknown>
 
   // Per-cell onLayout rides the engine's structural (layout) event channel — Angular forbids an
   // [onLayout] property binding (NG8002). $event arrives untyped, narrowed before reaching measure.
-  handleCellLayout(measure: (event: ISymbioteEvent) => void, event: unknown): void {
+  handleCellLayout(
+    measure: (event: ISymbioteEvent) => void,
+    event: unknown,
+  ): void {
     if (this.isSymbioteEvent(event)) measure(event);
   }
 
   private isSymbioteEvent(value: unknown): value is ISymbioteEvent {
-    return typeof value === 'object' && value !== null && 'nativeEvent' in value;
+    return (
+      typeof value === 'object' && value !== null && 'nativeEvent' in value
+    );
   }
 
-  private mergeSeparator(gapIndex: number, patch: Partial<ISeparatorProps<unknown>>): void {
+  private mergeSeparator(
+    gapIndex: number,
+    patch: Partial<ISeparatorProps<unknown>>,
+  ): void {
     const count = this.listState.metrics.count;
     if (!isSeparatorGapInRange(gapIndex, count)) return;
-    this.separatorOverrides.set(gapIndex, { ...this.separatorOverrides.get(gapIndex), ...patch });
+    this.separatorOverrides.set(gapIndex, {
+      ...this.separatorOverrides.get(gapIndex),
+      ...patch,
+    });
     this.cdr.markForCheck();
   }
 
@@ -903,7 +1188,10 @@ export class VirtualizedList<ItemT = unknown>
         this.mergeSeparator(index - 1, { highlighted: false });
         this.mergeSeparator(index, { highlighted: false });
       },
-      updateProps: (select: 'leading' | 'trailing', newProps: Record<string, unknown>): void => {
+      updateProps: (
+        select: 'leading' | 'trailing',
+        newProps: Record<string, unknown>,
+      ): void => {
         this.mergeSeparator(select === 'leading' ? index - 1 : index, newProps);
       },
     };
@@ -936,7 +1224,11 @@ export class VirtualizedList<ItemT = unknown>
     });
   }
 
-  scrollToItem(params: { item: unknown; animated?: boolean; viewPosition?: number }): void {
+  scrollToItem(params: {
+    item: unknown;
+    animated?: boolean;
+    viewPosition?: number;
+  }): void {
     this.dispatch({
       kind: 'scroll-to-item',
       item: params.item,
@@ -946,7 +1238,10 @@ export class VirtualizedList<ItemT = unknown>
   }
 
   scrollToEnd(params?: { animated?: boolean }): void {
-    this.dispatch({ kind: 'scroll-to-end', animated: params?.animated ?? true });
+    this.dispatch({
+      kind: 'scroll-to-end',
+      animated: params?.animated ?? true,
+    });
   }
 
   flashScrollIndicators(): void {