fix(ifr): replay background history and reset list state on hydration fallback (#358)

A structural hydration mismatch tore down the whole IFR tree but applied only
the mismatching background batch. Batches consumed earlier — skipped as
identical, or value-patched — had only ever been painted as the main-thread
render, so everything they described vanished from the page. Buffer the
consumed background batches and replay them onto the clean page before the
mismatching one.

Teardown also left `list-apply`'s registries populated. A native <list> does
not own its rows: they live in those registries and reach native only through
the closures __CreateList captured. After a fallback the ids in the abandoned
stream get reused by a structurally different background render, so a stale
`listElementIds` entry routed a background INSERT into the dead list instead of
the element tree (the child silently never appears), and `update-list-info` was
committed onto whatever element inherited the id. Clearing the state makes the
abandoned list's callbacks inert and lets the replay rebuild each list.

Adds IFR × <list> coverage, which the suite had none of: a hydrated first
screen whose rows native materializes after the background thread has mutated
the list, plus both fallback paths.


Claude-Session: https://claude.ai/code/session_01CuaHSwJh1PvJHUcwrH95pi

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: Huxpro

.changeset/fix-ifr-fallback-list-ownership.md

@@ -0,0 +1,5 @@
+---
+"vue-lynx": patch
+---
+
+Fix the IFR hydration fallback discarding background batches and leaving native `<list>` registries behind. On a structural mismatch the main-thread tree is torn down, but batches the background thread had already sent (skipped as identical, or value-patched) were never re-applied — everything they described disappeared from the page. The fallback now replays the complete background history onto the clean page. Teardown also resets `list-apply`'s state: a native list does not own its rows, so the abandoned render's list registries survived teardown and a later background `INSERT` whose parent id had been a `<list>` in the discarded stream was routed into the dead list instead of the element tree, with `update-list-info` committed onto whatever element reused that id.

packages/testing-library/src/__tests__/ifr-list.test.ts

@@ -0,0 +1,238 @@
+/**
+ * IFR × native `<list>` interaction.
+ *
+ * A native list does not own its rows: `__CreateList` hands native three
+ * main-thread closures, and the rows they hand back live in `list-apply`'s
+ * registries, not in the element tree.  IFR moves a first screen from the main
+ * thread to the background thread, so these tests pin the two places where
+ * that ownership could go wrong:
+ *
+ *   1. Steady state — a hydrated list must keep exactly one native list, and
+ *      the callbacks native holds must see the item order the *background*
+ *      thread maintains after hydration (not the frozen first-screen copy).
+ *   2. Fallback — when hydration hits a structural mismatch, the abandoned
+ *      main-thread stream must not leave list registries behind: a later
+ *      background op addressing a reused element id would otherwise be routed
+ *      into a dead list instead of the element tree.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  h,
+  defineComponent,
+  ref,
+  createApp,
+  onMounted,
+  resetForTesting,
+} from 'vue-lynx';
+import type { Component } from 'vue-lynx';
+import { IFR_MOUNT_APPS_GLOBAL, OP, PAGE_ROOT_ID } from 'vue-lynx/internal/ops';
+import {
+  enableIFR,
+  getIfrPhase,
+  resetIfrForTesting,
+} from '../../../vue-lynx/main-thread/src/ifr.js';
+import { getListItemBgIdsForTest } from '../../../vue-lynx/main-thread/src/list-apply.js';
+import { waitForUpdate } from '../render.js';
+
+const env = () => (globalThis as any).lynxTestingEnv;
+
+/** Phase 1: main-thread first-screen render via renderPage. */
+function mtFirstScreenRender(comp: Component): Document {
+  const e = env();
+  e.switchToMainThread();
+  const doc = e.jsdom.window.document as Document;
+  doc.body.innerHTML = '';
+
+  resetForTesting();
+  resetIfrForTesting();
+  enableIFR();
+
+  createApp(comp).mount();
+  (globalThis as any).renderPage({});
+  return doc;
+}
+
+/** Phase 2: background thread boots, renders the same app, hydrates. */
+function bgHydrate(comp: Component): void {
+  const e = env();
+  delete (globalThis as any).__VUE_LYNX_IFR_MT__;
+  e.switchToBackgroundThread();
+  resetForTesting();
+  createApp(comp).mount();
+}
+
+/**
+ * Ops-level harness: record a synthetic main-thread stream through the IFR
+ * recorder, then feed synthetic background batches to `vuePatchUpdate`.
+ * Component-level tests cannot produce a *multi-batch* first screen with a
+ * mismatch in a later batch, which is exactly where fallback ordering matters.
+ */
+function mtRecordBatches(batches: unknown[][]): Document {
+  const e = env();
+  e.switchToMainThread();
+  const doc = e.jsdom.window.document as Document;
+  doc.body.innerHTML = '';
+
+  resetForTesting();
+  resetIfrForTesting();
+  enableIFR();
+
+  (globalThis as any)[IFR_MOUNT_APPS_GLOBAL] = () => {
+    const apply = (globalThis as any)['__vueLynxIfrApplyOps'] as (
+      ops: unknown[],
+    ) => void;
+    for (const batch of batches) apply(batch);
+  };
+  (globalThis as any).renderPage({});
+  delete (globalThis as any)[IFR_MOUNT_APPS_GLOBAL];
+  return doc;
+}
+
+function bgBatch(ops: unknown[]): void {
+  (globalThis as any).vuePatchUpdate({ data: JSON.stringify(ops) });
+}
+
+/** The BG-side element id the main thread stamped on an element. */
+function bgIdOf(el: Element): number {
+  const attr = Array.from(el.attributes).find((a) =>
+    a.name.startsWith('vue-ref-')
+  );
+  return Number(attr!.name.slice('vue-ref-'.length));
+}
+
+beforeEach(() => {
+  delete (globalThis as any).__VUE_LYNX_IFR_MT__;
+});
+
+describe('IFR + native <list>', () => {
+  it('keeps one native list and lets the background thread own the rows', async () => {
+    const Comp = defineComponent({
+      setup() {
+        const rows = ref(['a', 'b', 'c']);
+        // onMounted only runs on the background thread — this is the
+        // post-hydration mutation native must be able to observe.
+        onMounted(() => {
+          rows.value = [...rows.value, 'd'];
+        });
+        return () =>
+          h(
+            'list',
+            null,
+            rows.value.map((row) =>
+              h('list-item', { key: row, 'item-key': row }, [
+                h('text', null, row),
+              ])
+            ),
+          );
+      },
+    });
+
+    const doc = mtFirstScreenRender(Comp);
+    env().switchToMainThread();
+    // The first screen paints one native list. Rows are not in the tree yet:
+    // native materializes them by calling back into componentAtIndex.
+    expect(doc.querySelectorAll('list').length).toBe(1);
+
+    bgHydrate(Comp);
+    await waitForUpdate();
+
+    env().switchToMainThread();
+    // Hydration skipped the identical structural frame — still one list, and
+    // the background's post-hydration append landed in the *live* registry the
+    // callbacks read.
+    expect(getIfrPhase()).toBe('hydrated');
+    const lists = doc.querySelectorAll('list');
+    expect(lists.length).toBe(1);
+    const listEl = lists[0]! as Element & {
+      componentAtIndex(
+        list: Element,
+        listID: number,
+        cellIndex: number,
+        operationID: number,
+      ): number | undefined;
+    };
+    expect(getListItemBgIdsForTest(bgIdOf(listEl)).length).toBe(4);
+
+    // Native materializes a row that never existed during the IFR render.
+    const sign = listEl.componentAtIndex(listEl, 0, 3, 1);
+    expect(sign).toBeTypeOf('number');
+    const materialized = listEl.lastElementChild!;
+    expect(materialized.tagName.toLowerCase()).toBe('list-item');
+    expect(materialized.textContent).toBe('d');
+  });
+
+  it('does not route background inserts into an abandoned list after fallback', () => {
+    // Main thread renders id 2 as a <list>; the background render diverges and
+    // uses id 2 for a plain <view> with a child. If the abandoned list's
+    // registries survived teardown, the child insert would be swallowed by
+    // `insertListItem` and never reach the element tree.
+    const doc = mtRecordBatches([
+      [
+        OP.CREATE, 2, 'list',
+        OP.INSERT, PAGE_ROOT_ID, 2, -1,
+        OP.CREATE, 3, 'list-item',
+        OP.SET_PROP, 3, 'item-key', 'a',
+        OP.INSERT, 2, 3, -1,
+      ],
+    ]);
+    expect(doc.querySelectorAll('list').length).toBe(1);
+
+    bgBatch([
+      OP.CREATE, 2, 'view',
+      OP.INSERT, PAGE_ROOT_ID, 2, -1,
+      OP.CREATE, 3, 'text',
+      OP.INSERT, 2, 3, -1,
+      OP.SET_TEXT, 3, 'bg',
+    ]);
+
+    expect(getIfrPhase()).toBe('hydrated');
+    expect(doc.querySelectorAll('list').length).toBe(0);
+    const view = doc.querySelector('view')!;
+    expect(view.children.length).toBe(1);
+    expect(view.textContent).toBe('bg');
+  });
+
+  it('replays earlier background batches when a later batch mismatches', () => {
+    // Batch 1 matches and is skipped; batch 2 diverges. The list described by
+    // batch 1 was only ever painted by the main-thread render, so teardown
+    // removes it — the fallback has to replay batch 1 to put it back.
+    const doc = mtRecordBatches([
+      [
+        OP.CREATE, 2, 'list',
+        OP.INSERT, PAGE_ROOT_ID, 2, -1,
+        OP.CREATE, 3, 'list-item',
+        OP.SET_PROP, 3, 'item-key', 'a',
+        OP.INSERT, 2, 3, -1,
+      ],
+      [
+        OP.CREATE, 4, 'text',
+        OP.INSERT, PAGE_ROOT_ID, 4, -1,
+        OP.SET_TEXT, 4, 'main-thread',
+      ],
+    ]);
+
+    bgBatch([
+      OP.CREATE, 2, 'list',
+      OP.INSERT, PAGE_ROOT_ID, 2, -1,
+      OP.CREATE, 3, 'list-item',
+      OP.SET_PROP, 3, 'item-key', 'a',
+      OP.INSERT, 2, 3, -1,
+    ]);
+    expect(getIfrPhase()).toBe('rendered'); // skipped, one batch left
+
+    bgBatch([
+      OP.CREATE, 4, 'image',
+      OP.INSERT, PAGE_ROOT_ID, 4, -1,
+      OP.SET_PROP, 4, 'src', 'x.png',
+    ]);
+
+    expect(getIfrPhase()).toBe('hydrated');
+    // The list from the replayed batch survives, exactly once, with its row.
+    const lists = doc.querySelectorAll('list');
+    expect(lists.length).toBe(1);
+    expect(getListItemBgIdsForTest(bgIdOf(lists[0]!))).toEqual([3]);
+    expect(doc.querySelectorAll('image').length).toBe(1);
+    expect(doc.querySelectorAll('text').length).toBe(0);
+  });
+});

packages/vue-lynx/main-thread/src/ifr.ts

@@ -24,7 +24,8 @@
  *        - identical batch        → skipped (already applied during IFR)
  *        - value-level mismatch   → the background value is patched in place
  *        - structural mismatch    → the IFR tree is torn down and the
- *                                   background batch applied from scratch
+ *                                   complete background history replayed
+ *                                   onto the clean page
  *      Either way the background thread ends up owning the tree, and all
  *      subsequent updates flow through the normal ops pipeline.
  *
@@ -50,6 +51,7 @@ import {
 } from 'vue-lynx/internal/ops';
 
 import { elements } from './element-registry.js';
+import { resetListState } from './list-apply.js';
 import { applyOps } from './ops-apply.js';
 
 // Widened view: op codes read off the wire are plain numbers and may be
@@ -62,6 +64,14 @@ let phase: Phase = 'inactive';
 let recordedBatches: unknown[][] = [];
 let batchCursor = 0;
 
+/**
+ * Background batches consumed by hydration so far (skipped or value-patched).
+ * They are the authoritative description of the background tree, so a
+ * structural mismatch in a *later* batch can replay them onto the clean page
+ * instead of dropping the elements they described.
+ */
+let backgroundHistory: unknown[][] = [];
+
 /**
  * How a mismatch in the *last* argument of an op is handled during
  * hydration.  Ops not listed here are structural: any difference aborts
@@ -182,6 +192,7 @@ export function runIfrRender(): void {
   // start every render from a clean slate.
   recordedBatches = [];
   batchCursor = 0;
+  backgroundHistory = [];
   phase = 'enabled';
 
   const trigger = (globalThis as Record<string, unknown>)[
@@ -236,13 +247,14 @@ export function interceptPatchUpdate(data: string): boolean {
   const patchOps = reconcileBatch(recorded, incoming);
   if (patchOps) {
     if (patchOps.length > 0) applyOps(patchOps);
+    backgroundHistory.push(incoming);
     advanceCursor();
     return true;
   }
 
   // Structural mismatch — the renders diverged (non-deterministic render or
-  // thread-dependent branching).  Remove the IFR tree and apply the
-  // background batch onto the clean page.
+  // thread-dependent branching).  Remove the IFR tree and replay the whole
+  // background render onto the clean page.
   if (__DEV__) {
     console.warn(
       '[vue-lynx] IFR hydration mismatch: the background render differs '
@@ -251,8 +263,14 @@ export function interceptPatchUpdate(data: string): boolean {
         + 'deterministic and thread-agnostic.',
     );
   }
+  // Batches consumed before the mismatch were only ever painted as the
+  // main-thread render — teardown removes those elements, so replaying the
+  // background history is what puts them back. Capture it before teardown
+  // clears the recorded state.
+  const history = backgroundHistory;
   teardownIfrTree();
   phase = 'hydrated';
+  for (const batch of history) applyOps(batch);
   applyOps(incoming);
   return true;
 }
@@ -265,6 +283,7 @@ function advanceCursor(): void {
     // (it pins every type/class/style payload of the first screen otherwise).
     recordedBatches = [];
     batchCursor = 0;
+    backgroundHistory = [];
   }
 }
 
@@ -381,8 +400,20 @@ function teardownIfrTree(): void {
   }
   for (const id of createdIds) elements.delete(id);
 
+  // Native <list> elements are not owned by the element tree: the rows live in
+  // list-apply's registries and reach native only through the callbacks
+  // __CreateList closed over. Removing the list element therefore leaves those
+  // registries pointing at the abandoned main-thread stream — a later
+  // background INSERT whose parent id was a <list> in the discarded render
+  // would be routed into a dead list instead of the element tree, and
+  // update-list-info would be committed onto whatever element reused the id.
+  // Clearing them makes the abandoned list's callbacks inert (they resolve
+  // nothing) and lets the replay rebuild every list from scratch.
+  resetListState();
+
   recordedBatches = [];
   batchCursor = 0;
+  backgroundHistory = [];
 }
 
 // ---------------------------------------------------------------------------
@@ -394,6 +425,7 @@ export function resetIfrForTesting(): void {
   phase = 'inactive';
   recordedBatches = [];
   batchCursor = 0;
+  backgroundHistory = [];
   warnedPostHydrationOps = false;
   const g = globalThis as Record<string, unknown>;
   delete g[IFR_MT_FLAG_GLOBAL];