From 001a75d44636929067335aab1d06681f3116b705 Mon Sep 17 00:00:00 2001
From: Ernest Badu <55922827+Ernxst@users.noreply.github.com>
Date: Fri, 2 Oct 2026 22:23:12 +0100
Subject: [PATCH 1/2] Report virtual list range after data changes

---
 .changeset/virtual-list-range.md              |   6 +
 README.md                                     |   6 +
 packages/native/src/renderer.rs               | 233 +++++++++++++++++-
 .../src/__tests__/instance-scroll.test.tsx    |  37 +++
 ...virtual-list-focus-window-advance.test.tsx |   7 +-
 .../react/src/__tests__/virtual-list.test.tsx | 229 +++++++++++++++++
 packages/react/src/testing.ts                 |   4 +
 skills/gpuix/references/elements.md           |   2 +-
 8 files changed, 513 insertions(+), 11 deletions(-)
 create mode 100644 .changeset/virtual-list-range.md

diff --git a/.changeset/virtual-list-range.md b/.changeset/virtual-list-range.md
new file mode 100644
index 00000000..ffda5b24
--- /dev/null
+++ b/.changeset/virtual-list-range.md
@@ -0,0 +1,6 @@
+---
+"@gpuix/native": patch
+"@gpuix/react": patch
+---
+
+Report virtual-list visible-range changes after data and layout updates.
diff --git a/README.md b/README.md
index 78299339..a9cd5952 100644
--- a/README.md
+++ b/README.md
@@ -2230,6 +2230,12 @@ function MessageList({ messages }: { messages: Message[] }) {
 }
 ```
 
+`onVisibleRange` runs when the visible logical range changes, including after
+the item count, mounted window, row-height estimate, or viewport size changes.
+It does not run again when an update leaves the range unchanged. For example,
+shrinking a list while scrolled near its end clamps the scroll position and
+reports the new range so a windowed list can mount the rows now in view.
+
 `role` and ARIA props on `<virtual-list>` project an accessibility node exactly
 as they do on a `<div>`. Use `role="list"` on the list and `role="listitem"` on
 its rows to match the react-dom equivalent of `<ul>` and `<li>`.
diff --git a/packages/native/src/renderer.rs b/packages/native/src/renderer.rs
index 14daa15a..f07abf9b 100644
--- a/packages/native/src/renderer.rs
+++ b/packages/native/src/renderer.rs
@@ -10368,6 +10368,8 @@ struct VirtualListEntry {
     /// rather than assuming the list has no id-bearing ancestors.
     accessibility_ancestor_path: Option<Vec<gpui::ElementId>>,
     pending_focus: Option<PendingVirtualFocus>,
+    reported_visible_range: Rc<RefCell<Option<std::ops::Range<usize>>>>,
+    last_visible_range_check: Option<(u64, gpui::Size<gpui::Pixels>, usize, gpui::Pixels)>,
 }
 
 impl VirtualListEntry {
@@ -10403,6 +10405,8 @@ impl VirtualListEntry {
             seen_rows: HashSet::new(),
             accessibility_ancestor_path: None,
             pending_focus: None,
+            reported_visible_range: Rc::new(RefCell::new(None)),
+            last_visible_range_check: None,
         }
     }
 
@@ -10478,6 +10482,8 @@ impl VirtualListEntry {
                 .seen_rows
                 .retain(|id| replacement.child_ids.contains(id));
             replacement.pending_focus = self.pending_focus.take();
+            replacement.reported_visible_range = self.reported_visible_range.clone();
+            replacement.last_visible_range_check = self.last_visible_range_check;
             if !should_follow {
                 replacement.state.scroll_to(scroll_top);
             }
@@ -14456,6 +14462,10 @@ fn build_virtual_list(
             },
         );
     let config = VirtualListConfig::from_element(element);
+    let previous_logical_count = ctx
+        .virtual_lists
+        .get(&element.id)
+        .map(|entry| entry.config.logical_count(entry.child_ids.len()));
     let window_start = if config.item_count.is_some() {
         window_start_from_element(element)
     } else {
@@ -14510,6 +14520,36 @@ fn build_virtual_list(
         }
     };
 
+    let logical_count = ctx
+        .virtual_lists
+        .get(&element.id)
+        .map(|entry| entry.config.logical_count(entry.child_ids.len()))
+        .unwrap_or_default();
+    if previous_logical_count.is_some_and(|previous| previous != logical_count) {
+        if let Some(entry) = ctx.virtual_lists.get(&element.id) {
+            if entry.reported_visible_range.borrow().is_some() {
+                let viewport_height = entry
+                    .last_visible_range_check
+                    .map(|(_, viewport, _, _)| viewport.height)
+                    .filter(|height| f32::from(*height) > 0.0)
+                    .unwrap_or_else(|| entry.state.viewport_bounds().size.height);
+                if let Some(range) = estimated_virtual_list_visible_range_for_height(
+                    &entry.state,
+                    logical_count,
+                    entry.config.estimated_item_height,
+                    viewport_height,
+                ) {
+                    emit_virtual_visible_range(
+                        ctx.event_callback,
+                        element.id,
+                        range,
+                        &entry.reported_visible_range,
+                    );
+                }
+            }
+        }
+    }
+
     if let Some(entry) = ctx.virtual_lists.get_mut(&element.id) {
         entry.accessibility_ancestor_path = ctx
             .gpui_element_path
@@ -14648,12 +14688,20 @@ fn build_virtual_list(
     if element.events.contains("visibleRange") {
         let callback = ctx.event_callback.clone();
         let list_id = element.id;
+        let reported_range = ctx
+            .virtual_lists
+            .get(&list_id)
+            .expect("virtual list entry exists")
+            .reported_visible_range
+            .clone();
         list_state.set_scroll_handler(move |event, _window, _cx| {
             bump_virtual_list_scroll_generation(list_id);
-            emit_event_full(&callback, list_id, "visibleRange", |payload| {
-                payload.start_index = Some(event.visible_range.start as f64);
-                payload.end_index = Some(event.visible_range.end as f64);
-            });
+            emit_virtual_visible_range(
+                &callback,
+                list_id,
+                event.visible_range.clone(),
+                &reported_range,
+            );
         });
     }
 
@@ -14683,12 +14731,65 @@ fn build_virtual_list(
             cx,
         )
     });
-    let list = gpui::list(list_state, render_item)
+    let list = gpui::list(list_state.clone(), render_item)
         .with_sizing_behavior(gpui::ListSizingBehavior::Auto)
         .size_full();
     // `List` doesn't run GPUI's interactivity layout and paint hooks. Let a
     // div own the virtual list's bounds, focus identity, and tab stop while
     // the List keeps its scrolling and row hit testing.
+    let needs_visible_range_check = ctx.virtual_lists.get(&element.id).is_some_and(|entry| {
+        let scroll_top = entry.state.logical_scroll_top();
+        entry.last_visible_range_check
+            != Some((
+                element.subtree_revision,
+                entry.state.viewport_bounds().size,
+                scroll_top.item_ix,
+                scroll_top.offset_in_item,
+            ))
+    });
+    if element.events.contains("visibleRange") && needs_visible_range_check {
+        let list_id = element.id;
+        let subtree_revision = element.subtree_revision;
+        let callback = ctx.event_callback.clone();
+        let view = cx.weak_entity();
+        window.on_next_frame(move |_window, app| {
+            let _ = view.update(app, |view, _cx| {
+                let Some(entry) = view.virtual_lists.get_mut(&list_id) else {
+                    return;
+                };
+                let scroll_top = entry.state.logical_scroll_top();
+                entry.last_visible_range_check = Some((
+                    subtree_revision,
+                    entry.state.viewport_bounds().size,
+                    scroll_top.item_ix,
+                    scroll_top.offset_in_item,
+                ));
+                // A cross-window focus request has already reported the estimated
+                // range needed to mount its target. Reporting the still-current
+                // viewport here could replace that request before React mounts it.
+                if entry.pending_focus.is_some() {
+                    return;
+                }
+                let count = entry.config.logical_count(entry.child_ids.len());
+                if let Some(range) = virtual_list_visible_range(
+                    &entry.state,
+                    count,
+                    entry.config.estimated_item_height,
+                ) {
+                    if entry.reported_visible_range.borrow().is_none() {
+                        *entry.reported_visible_range.borrow_mut() = Some(range);
+                    } else {
+                        emit_virtual_visible_range(
+                            &callback,
+                            list_id,
+                            range,
+                            &entry.reported_visible_range,
+                        );
+                    }
+                }
+            });
+        });
+    }
     let mut surface = gpui::div()
         .id(gpui::ElementId::Integer(element.id))
         .child(list);
@@ -18198,10 +18299,124 @@ fn emit_virtual_window_advance(
             (target_index + viewport_rows).min(logical_count),
         ),
     };
-    emit_event_full(callback, list_id, "visibleRange", |payload| {
-        payload.start_index = Some(start_index as f64);
-        payload.end_index = Some(end_index as f64);
-    });
+    emit_virtual_visible_range(
+        callback,
+        list_id,
+        start_index..end_index,
+        &entry.reported_visible_range,
+    );
+}
+
+fn emit_virtual_visible_range(
+    callback: &Option<EventCallback>,
+    list_id: u64,
+    range: std::ops::Range<usize>,
+    reported_range: &Rc<RefCell<Option<std::ops::Range<usize>>>>,
+) {
+    let changed = {
+        let mut previous = reported_range.borrow_mut();
+        if previous.as_ref() == Some(&range) {
+            false
+        } else {
+            *previous = Some(range.clone());
+            true
+        }
+    };
+    if changed {
+        emit_event_full(callback, list_id, "visibleRange", |payload| {
+            payload.start_index = Some(range.start as f64);
+            payload.end_index = Some(range.end as f64);
+        });
+    }
+}
+
+/// Read the range GPUI laid out after a non-scroll update. The anchor starts
+/// at the first potentially visible row, and GPUI has measured each row as it
+/// enters the viewport, so this walks only the visible rows and the first row
+/// below them. An unknown bound means layout has not measured enough yet; a
+/// later paint will try again.
+fn virtual_list_visible_range(
+    state: &gpui::ListState,
+    logical_count: usize,
+    estimated_item_height: Option<f32>,
+) -> Option<std::ops::Range<usize>> {
+    if logical_count == 0 {
+        return Some(0..0);
+    }
+
+    let scroll_top = state.logical_scroll_top();
+    if scroll_top.item_ix >= logical_count {
+        return estimated_virtual_list_visible_range(
+            state,
+            logical_count,
+            estimated_item_height,
+        );
+    }
+
+    let mut start = scroll_top.item_ix;
+    while start > 0 {
+        match state.item_is_above_viewport(start) {
+            Some(true) => start -= 1,
+            Some(false) => break,
+            None => {
+                return estimated_virtual_list_visible_range(
+                    state,
+                    logical_count,
+                    estimated_item_height,
+                );
+            }
+        }
+    }
+
+    let mut end = start;
+    while end < logical_count {
+        let Some(below) = state.item_is_below_viewport(end) else {
+            return estimated_virtual_list_visible_range(
+                state,
+                logical_count,
+                estimated_item_height,
+            );
+        };
+        end += 1;
+        if below {
+            break;
+        }
+    }
+    Some(start..end)
+}
+
+fn estimated_virtual_list_visible_range(
+    state: &gpui::ListState,
+    logical_count: usize,
+    estimated_item_height: Option<f32>,
+) -> Option<std::ops::Range<usize>> {
+    estimated_virtual_list_visible_range_for_height(
+        state,
+        logical_count,
+        estimated_item_height,
+        state.viewport_bounds().size.height,
+    )
+}
+
+fn estimated_virtual_list_visible_range_for_height(
+    state: &gpui::ListState,
+    logical_count: usize,
+    estimated_item_height: Option<f32>,
+    viewport_height: gpui::Pixels,
+) -> Option<std::ops::Range<usize>> {
+    let height = estimated_item_height.filter(|height| *height > 0.0)?;
+    let scroll_top = state.logical_scroll_top();
+    if scroll_top.item_ix >= logical_count {
+        let viewport_height = f32::from(viewport_height).max(0.0);
+        let rows_in_view = (viewport_height / height).ceil() as usize;
+        return Some(logical_count.saturating_sub(rows_in_view)..logical_count);
+    }
+    let viewport_height = f32::from(viewport_height).max(0.0);
+    let rows_in_view = ((f32::from(scroll_top.offset_in_item).max(0.0) + viewport_height) / height)
+        .floor() as usize
+        + 1;
+    let start = scroll_top.item_ix;
+    Some(start..start.saturating_add(rows_in_view).min(logical_count))
 }
 
 fn window_size(window: &gpui::Window) -> WindowSize {
diff --git a/packages/react/src/__tests__/instance-scroll.test.tsx b/packages/react/src/__tests__/instance-scroll.test.tsx
index 8840052f..2cf8e5b1 100644
--- a/packages/react/src/__tests__/instance-scroll.test.tsx
+++ b/packages/react/src/__tests__/instance-scroll.test.tsx
@@ -93,6 +93,43 @@ describeNative("host instance scroll properties", () => {
     expect(testRoot.renderer.getScrollOffset(scroller.id)).toEqual([0, -40])
   })
 
+  it("reports scroll when a content update clamps the position", async () => {
+    const scrollPositions: number[] = []
+    const scrollerRef = React.createRef<PublicInstance>()
+    let contentHeight = 400
+
+    function ScrollBox() {
+      return (
+        <div
+          ref={scrollerRef}
+          data-testid="clamped-scroller"
+          style={{ width: 200, height: 100, overflowY: "scroll" }}
+          onScroll={(event) => scrollPositions.push(event.currentTarget.scrollTop)}
+        >
+          <div style={{ height: contentHeight, flexShrink: 0 }}>
+            <text>scrollable</text>
+          </div>
+        </div>
+      )
+    }
+
+    testRoot.render(<ScrollBox />)
+    const scroller = scrollerRef.current!
+    testRoot.renderer.scrollTo(scroller.id, 0, -300)
+    testRoot.renderer.flush()
+    testRoot.renderer.dispatchNativeEvents()
+    expect(scroller.scrollTop).toBe(300)
+    expect(scrollPositions).toContain(300)
+
+    contentHeight = 80
+    testRoot.render(<ScrollBox />)
+    await testRoot.waitFor(() => {
+      testRoot.renderer.dispatchNativeEvents()
+      expect(scroller.scrollTop).toBe(0)
+      expect(scrollPositions.at(-1)).toBe(0)
+    }, { timeout: 5_000 })
+  })
+
   it("reports a viewport for an element that cannot scroll", () => {
     const ref = React.createRef<PublicInstance>()
 
diff --git a/packages/react/src/__tests__/virtual-list-focus-window-advance.test.tsx b/packages/react/src/__tests__/virtual-list-focus-window-advance.test.tsx
index f43e5e34..0f289976 100644
--- a/packages/react/src/__tests__/virtual-list-focus-window-advance.test.tsx
+++ b/packages/react/src/__tests__/virtual-list-focus-window-advance.test.tsx
@@ -260,6 +260,7 @@ describeNative("<virtual-list> cross-window focus navigation", () => {
               overflowY: "scroll",
             }}
             onVisibleRange={(event) => {
+              if ((event.endIndex ?? 0) <= end) return
               const next = Math.max(0, Math.floor(event.startIndex ?? 0) - 2)
               release.current = () => setStart((current) => (current === next ? current : next))
             }}
@@ -567,6 +568,7 @@ describeNative("<virtual-list> cross-window focus navigation", () => {
             overflowY: "scroll",
           }}
           onVisibleRange={(event) => {
+            if ((event.endIndex ?? 0) <= end) return
             const next = Math.max(0, (event.endIndex ?? 1) - 1)
             setStart((current) => (current === next ? current : next))
           }}
@@ -783,6 +785,7 @@ describeNative("<virtual-list> cross-window focus navigation", () => {
             overflowY: "scroll",
           }}
           onVisibleRange={(event) => {
+            if ((event.endIndex ?? 0) <= end) return
             const next = Math.max(0, Math.floor(event.startIndex ?? 0) - 2)
             releases.push(() => setStart((current) => (current === next ? current : next)))
           }}
@@ -821,7 +824,9 @@ describeNative("<virtual-list> cross-window focus navigation", () => {
       screen.renderer.focusNext()
       screen.renderer.flush()
       screen.renderer.drawPendingFrame()
-      expect(releases).toHaveLength(1)
+      // A real viewport-range change may also ask the app to widen its
+      // window before the deferred focus request is released.
+      expect(releases.length).toBeGreaterThan(0)
 
       // A real, unrelated wheel scroll happens before the app ever builds
       // Button 20 — this is what supersedes the pending request, regardless
diff --git a/packages/react/src/__tests__/virtual-list.test.tsx b/packages/react/src/__tests__/virtual-list.test.tsx
index cea9c8e4..92a09fdb 100644
--- a/packages/react/src/__tests__/virtual-list.test.tsx
+++ b/packages/react/src/__tests__/virtual-list.test.tsx
@@ -76,6 +76,235 @@ function DynamicFocusableRows({ enabled }: { enabled: boolean }) {
 }
 
 describe("<virtual-list>", () => {
+  it("reports only changed visible ranges when list data and layout change", async () => {
+    const ranges: { startIndex: number | undefined; endIndex: number | undefined }[] = []
+    const onVisibleRange = (event: { startIndex?: number; endIndex?: number }) => {
+      ranges.push({ startIndex: event.startIndex, endIndex: event.endIndex })
+    }
+    const list = (
+      count: number,
+      options: {
+        windowStart?: number
+        windowSize?: number
+        height?: number
+        estimatedItemHeight?: number
+      } = {},
+    ) => {
+      const windowStart = options.windowStart ?? 0
+      const height = options.height ?? 720
+      const estimatedItemHeight = options.estimatedItemHeight ?? 48
+      const childCount = Math.min(
+        Math.max(0, count - windowStart),
+        options.windowSize ?? count,
+      )
+      return (
+        <virtual-list
+          ariaLabel="Bare list"
+          tabIndex={0}
+          style={{ height }}
+          itemCount={count}
+          windowStart={windowStart}
+          estimatedItemHeight={estimatedItemHeight}
+          onVisibleRange={onVisibleRange}
+        >
+          {Array.from({ length: childCount }, (_, offset) => {
+            const index = windowStart + offset
+            return (
+              <div key={index} style={{ height: 48 }}>
+                <text>{`Part ${index + 1}`}</text>
+              </div>
+            )
+          })}
+        </virtual-list>
+      )
+    }
+
+    const screen = createTestRoot()
+    screen.render(list(106))
+    await screen.userEvent.tab()
+    await screen.userEvent.keyboard(screen.getByLabelText("Bare list"), "end")
+
+    expect(ranges.at(-1)).toStrictEqual({ startIndex: 91, endIndex: 106 })
+    const countBeforeShrink = ranges.length
+
+    screen.render(list(12))
+    await screen.waitFor(() => {
+      screen.renderer.dispatchNativeEvents()
+      expect(ranges.at(-1)).toStrictEqual({ startIndex: 0, endIndex: 12 })
+    }, { timeout: 5_000 })
+    expect(screen.getByText("Part 1")).toBeTruthy()
+    expect(ranges).toHaveLength(countBeforeShrink + 1)
+    const listElement = screen.renderer.findByType("virtual-list")[0]
+    expect(screen.renderer.getListScrollTop(listElement!.id)).toEqual([0, 0, 720])
+    expect(screen.renderer.getScrollMetrics(listElement!.id)?.slice(1, 2)).toEqual([0])
+    expect(screen.renderer.getScrollMetrics(listElement!.id)?.[3]).toBe(720)
+    expect(screen.renderer.getScrollMetrics(listElement!.id)?.[5]).toBe(720)
+    screen.render(list(12))
+    await screen.waitFor(() => {
+      screen.renderer.dispatchNativeEvents()
+      expect(screen.renderer.getListScrollTop(listElement!.id)).toEqual([0, 0, 720])
+    }, { timeout: 5_000 })
+    expect(ranges).toHaveLength(countBeforeShrink + 1)
+
+    screen.render(list(96))
+    await screen.waitFor(() => {
+      screen.renderer.dispatchNativeEvents()
+      expect(ranges.at(-1)).toStrictEqual({ startIndex: 0, endIndex: 16 })
+    }, { timeout: 5_000 })
+    screen.render(list(0))
+    await screen.waitFor(() => {
+      screen.renderer.dispatchNativeEvents()
+      expect(ranges.at(-1)).toStrictEqual({ startIndex: 0, endIndex: 0 })
+    }, { timeout: 5_000 })
+    screen.render(list(12))
+    await screen.waitFor(() => {
+      screen.renderer.dispatchNativeEvents()
+      expect(ranges.at(-1)).toStrictEqual({ startIndex: 0, endIndex: 12 })
+    }, { timeout: 5_000 })
+
+    const countAfterReturn = ranges.length
+    screen.render(list(12, { windowStart: 1 }))
+    await screen.waitFor(() => {
+      screen.renderer.dispatchNativeEvents()
+      expect(screen.renderer.getListScrollTop(listElement!.id)).toEqual([0, 0, 720])
+    }, { timeout: 5_000 })
+    expect(ranges).toHaveLength(countAfterReturn)
+
+    screen.render(list(106))
+    await screen.waitFor(() => {
+      screen.renderer.dispatchNativeEvents()
+      expect(ranges.at(-1)).toStrictEqual({ startIndex: 0, endIndex: 16 })
+    }, { timeout: 5_000 })
+    screen.render(list(106, { estimatedItemHeight: 60, windowSize: 5 }))
+    await screen.waitFor(() => {
+      screen.renderer.dispatchNativeEvents()
+      expect(ranges.at(-1)).toStrictEqual({ startIndex: 0, endIndex: 14 })
+    }, { timeout: 5_000 })
+    screen.render(list(106, { estimatedItemHeight: 60, height: 480, windowSize: 5 }))
+    await screen.waitFor(() => {
+      screen.renderer.dispatchNativeEvents()
+      expect(ranges.at(-1)).toStrictEqual({ startIndex: 0, endIndex: 10 })
+    }, { timeout: 5_000 })
+
+    screen.render(list(106))
+    await screen.waitFor(() => {
+      screen.renderer.dispatchNativeEvents()
+      expect(ranges.at(-1)).toStrictEqual({ startIndex: 0, endIndex: 16 })
+    }, { timeout: 5_000 })
+    await screen.userEvent.keyboard(screen.getByLabelText("Bare list"), "end")
+    expect(ranges.at(-1)).toStrictEqual({ startIndex: 91, endIndex: 106 })
+    screen.render(list(96))
+    await screen.waitFor(() => {
+      screen.renderer.dispatchNativeEvents()
+      expect(ranges.at(-1)).toStrictEqual({ startIndex: 81, endIndex: 96 })
+    }, { timeout: 5_000 })
+    expect(screen.renderer.getListScrollTop(listElement!.id)).toEqual([81, 0, 720])
+    expect(screen.renderer.getScrollMetrics(listElement!.id)).toMatchObject([
+      0,
+      3888,
+      expect.any(Number),
+      4608,
+      expect.any(Number),
+      720,
+    ])
+    screen.render(list(96))
+    await screen.waitFor(() => {
+      screen.renderer.dispatchNativeEvents()
+      expect(screen.renderer.getScrollMetrics(listElement!.id)?.[1]).toBe(3888)
+    }, { timeout: 5_000 })
+  }, 30_000)
+
+  it("returns a windowed consumer to the first row when its data shrinks", async () => {
+    function WindowedList({ count }: { count: number }) {
+      const [range, setRange] = React.useState({ startIndex: 0, endIndex: 20 })
+      const startIndex = Math.max(0, Math.min(range.startIndex - 1, count - 1))
+      const endIndex = Math.max(range.endIndex + 1, startIndex + 1)
+
+      return (
+        <virtual-list
+          ariaLabel="Windowed list"
+          tabIndex={0}
+          style={{ height: 720 }}
+          itemCount={count + 1}
+          windowStart={startIndex}
+          estimatedItemHeight={48}
+          onVisibleRange={(event) =>
+            setRange({
+              startIndex: event.startIndex ?? range.startIndex,
+              endIndex: event.endIndex ?? range.endIndex,
+            })
+          }
+        >
+          {Array.from({ length: Math.max(0, Math.min(count, endIndex) - startIndex) }, (_, offset) => (
+            <div key={startIndex + offset} style={{ height: 48 }}>
+              <text>{`Part ${startIndex + offset + 1}`}</text>
+            </div>
+          ))}
+          {count > 0 && endIndex > count ? <div aria-hidden={true} style={{ height: 48 }} /> : null}
+        </virtual-list>
+      )
+    }
+
+    const screen = createTestRoot()
+    screen.render(<WindowedList count={106} />)
+    await screen.userEvent.tab()
+    const list = screen.getByLabelText("Windowed list")
+    await screen.userEvent.keyboard(list, "end")
+    expect(screen.getByText("Part 106")).toBeTruthy()
+
+    screen.render(<WindowedList count={12} />)
+    await screen.waitFor(() => {
+      screen.renderer.dispatchNativeEvents()
+      expect(screen.getByText("Part 1")).toBeTruthy()
+    }, { timeout: 5_000 })
+  }, 15_000)
+
+  it("reports the changed range when a shorter count still contains the viewport", async () => {
+    const ranges: { startIndex: number | undefined; endIndex: number | undefined }[] = []
+    const screen = createTestRoot()
+    const list = (count: number) => (
+      <virtual-list
+        ariaLabel="Positioned list"
+        style={{ height: 720 }}
+        itemCount={count}
+        estimatedItemHeight={48}
+        onVisibleRange={(event) =>
+          ranges.push({ startIndex: event.startIndex, endIndex: event.endIndex })
+        }
+      >
+        {Array.from({ length: count }, (_, index) => (
+          <div key={index} style={{ height: 48 }}>
+            <text>{`Part ${index + 1}`}</text>
+          </div>
+        ))}
+      </virtual-list>
+    )
+
+    screen.render(list(106))
+    const listElement = screen.renderer.findByType("virtual-list")[0]!
+    await screen.userEvent.tab()
+    await screen.userEvent.keyboard(screen.getByLabelText("Positioned list"), "pagedown")
+    await screen.waitFor(() => {
+      screen.renderer.dispatchNativeEvents()
+      expect(ranges.at(-1)?.startIndex).toBeGreaterThan(0)
+      expect(ranges.at(-1)?.endIndex).toBeGreaterThan(ranges.at(-1)!.startIndex!)
+    }, { timeout: 5_000 })
+    const previousRange = ranges.at(-1)
+    const previousRangeCount = ranges.length
+    const previousScrollTop = screen.renderer.getListScrollTop(listElement.id)?.[0]
+    expect(previousScrollTop).toBeGreaterThan(0)
+    expect(previousScrollTop).toBeLessThan(90)
+
+    screen.render(list(90))
+    await screen.waitFor(() => {
+      screen.renderer.dispatchNativeEvents()
+      expect(screen.renderer.getListScrollTop(listElement.id)?.[0]).toBe(previousScrollTop)
+      expect(ranges.length).toBeGreaterThan(previousRangeCount)
+    }, { timeout: 5_000 })
+    expect(ranges.at(-1)).not.toStrictEqual(previousRange)
+    expect(ranges.at(-1)?.startIndex).toBe(previousScrollTop)
+  }, 15_000)
+
   describeNative("accessibility", () => {
     it("projects its declared role and label into the accessibility tree", () => {
       const screen = createTestRoot()
diff --git a/packages/react/src/testing.ts b/packages/react/src/testing.ts
index 4be68fd1..62f8923f 100644
--- a/packages/react/src/testing.ts
+++ b/packages/react/src/testing.ts
@@ -3409,6 +3409,10 @@ export function createTestRoot(options: TestRootOptions = {}): TestRoot {
     actSync(reportRootError, () => root.render(node))
     // Trigger GPUI rendering pipeline after the React commit and its effects.
     renderer.flush()
+    // Native events produced by that render (for example, a virtual list's
+    // visible range after its item count changes) are part of the committed
+    // update. Deliver them before render returns, as the live renderer does.
+    renderer.dispatchNativeEvents()
   }
 
   const unmount = (): void => {
diff --git a/skills/gpuix/references/elements.md b/skills/gpuix/references/elements.md
index 2019f201..4853d0fc 100644
--- a/skills/gpuix/references/elements.md
+++ b/skills/gpuix/references/elements.md
@@ -206,7 +206,7 @@ Their text is selectable and searchable, but test text queries cannot see it; us
 
 A host element, not a component; each immediate child is one row. It needs a bounded height. A populated list that lays out at zero height diagnoses the missing parent height: it throws under `strictStyles` and warns once otherwise. Empty or hidden lists stay quiet.
 
-- Props: `alignment` (`top`/`bottom`), `followTail`, `overdraw` (px, default 512), `estimatedItemHeight` (default 48; `null` opts out), `itemCount` (ignored without a positive estimate), `windowStart` (logical index of the first child; ignored without `itemCount`), `onVisibleRange` (`startIndex`, `endIndex` exclusive), `tabIndex`, `className`, `data-*`, ARIA props.
+- Props: `alignment` (`top`/`bottom`), `followTail`, `overdraw` (px, default 512), `estimatedItemHeight` (default 48; `null` opts out), `itemCount` (ignored without a positive estimate), `windowStart` (logical index of the first child; ignored without `itemCount`), `onVisibleRange` (`startIndex`, `endIndex` exclusive; fires when the visible range changes after scrolling or a list or layout update, and is suppressed when the range is unchanged), `tabIndex`, `className`, `data-*`, ARIA props.
 - Not accepted: mouse/keyboard handlers, `hover`/`active` styles, `transition`. Wrap the list in a `div` for those.
 - Set `tabIndex={0}` to add the list to the Tab order. Its `focus` and `focusVisible` styles work when the list has focus.
 - A single child without `itemCount={1}` throws `VirtualListRowContractError` in strict mode and warns otherwise.

From fc76698bc06b395b19b64550be62aed39d914702 Mon Sep 17 00:00:00 2001
From: Ernest Badu <55922827+Ernxst@users.noreply.github.com>
Date: Fri, 2 Oct 2026 22:54:44 +0100
Subject: [PATCH 2/2] Report virtual list ranges after settled layout

---
 packages/native/src/renderer.rs               | 35 ----------------
 packages/native/src/test_renderer.rs          | 18 +++++++++
 .../react/src/__tests__/virtual-list.test.tsx |  7 ++--
 packages/react/src/testing.ts                 | 40 ++++++++++++++-----
 4 files changed, 51 insertions(+), 49 deletions(-)

diff --git a/packages/native/src/renderer.rs b/packages/native/src/renderer.rs
index f07abf9b..bb7c2144 100644
--- a/packages/native/src/renderer.rs
+++ b/packages/native/src/renderer.rs
@@ -38,7 +38,6 @@ use std::cell::{Cell, RefCell};
 use std::collections::{HashMap, HashSet, VecDeque};
 use std::hash::{Hash as _, Hasher as _};
 use std::path::PathBuf;
-#[cfg(any(target_os = "macos", target_family = "wasm"))]
 use std::rc::Rc;
 use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
 #[cfg(any(target_os = "windows", target_os = "linux", target_os = "freebsd"))]
@@ -14462,10 +14461,6 @@ fn build_virtual_list(
             },
         );
     let config = VirtualListConfig::from_element(element);
-    let previous_logical_count = ctx
-        .virtual_lists
-        .get(&element.id)
-        .map(|entry| entry.config.logical_count(entry.child_ids.len()));
     let window_start = if config.item_count.is_some() {
         window_start_from_element(element)
     } else {
@@ -14520,36 +14515,6 @@ fn build_virtual_list(
         }
     };
 
-    let logical_count = ctx
-        .virtual_lists
-        .get(&element.id)
-        .map(|entry| entry.config.logical_count(entry.child_ids.len()))
-        .unwrap_or_default();
-    if previous_logical_count.is_some_and(|previous| previous != logical_count) {
-        if let Some(entry) = ctx.virtual_lists.get(&element.id) {
-            if entry.reported_visible_range.borrow().is_some() {
-                let viewport_height = entry
-                    .last_visible_range_check
-                    .map(|(_, viewport, _, _)| viewport.height)
-                    .filter(|height| f32::from(*height) > 0.0)
-                    .unwrap_or_else(|| entry.state.viewport_bounds().size.height);
-                if let Some(range) = estimated_virtual_list_visible_range_for_height(
-                    &entry.state,
-                    logical_count,
-                    entry.config.estimated_item_height,
-                    viewport_height,
-                ) {
-                    emit_virtual_visible_range(
-                        ctx.event_callback,
-                        element.id,
-                        range,
-                        &entry.reported_visible_range,
-                    );
-                }
-            }
-        }
-    }
-
     if let Some(entry) = ctx.virtual_lists.get_mut(&element.id) {
         entry.accessibility_ancestor_path = ctx
             .gpui_element_path
diff --git a/packages/native/src/test_renderer.rs b/packages/native/src/test_renderer.rs
index 0562a17e..197c8901 100644
--- a/packages/native/src/test_renderer.rs
+++ b/packages/native/src/test_renderer.rs
@@ -3191,6 +3191,24 @@ impl TestGpuixRenderer {
         events.drain(..).collect()
     }
 
+    /// Return and clear events of one type while leaving other queued events
+    /// available to the test renderer's next full drain.
+    #[napi]
+    pub fn drain_events_of_type(&self, event_type: String) -> Vec<EventPayload> {
+        let mut events = self.events.lock().unwrap();
+        let mut matching = Vec::new();
+        let mut remaining = Vec::with_capacity(events.len());
+        for event in events.drain(..) {
+            if event.event_type == event_type {
+                matching.push(event);
+            } else {
+                remaining.push(event);
+            }
+        }
+        *events = remaining;
+        matching
+    }
+
     /// Return and clear native frame timestamps since the last drain.
     /// Timestamps are collected synchronously — no event loop queuing.
     #[napi]
diff --git a/packages/react/src/__tests__/virtual-list.test.tsx b/packages/react/src/__tests__/virtual-list.test.tsx
index 92a09fdb..d6364ca3 100644
--- a/packages/react/src/__tests__/virtual-list.test.tsx
+++ b/packages/react/src/__tests__/virtual-list.test.tsx
@@ -290,16 +290,17 @@ describe("<virtual-list>", () => {
       expect(ranges.at(-1)?.endIndex).toBeGreaterThan(ranges.at(-1)!.startIndex!)
     }, { timeout: 5_000 })
     const previousRange = ranges.at(-1)
-    const previousRangeCount = ranges.length
     const previousScrollTop = screen.renderer.getListScrollTop(listElement.id)?.[0]
     expect(previousScrollTop).toBeGreaterThan(0)
     expect(previousScrollTop).toBeLessThan(90)
+    const shortenedCount = previousRange!.endIndex! - 1
+    expect(shortenedCount).toBeGreaterThan(previousScrollTop)
 
-    screen.render(list(90))
+    screen.render(list(shortenedCount))
     await screen.waitFor(() => {
       screen.renderer.dispatchNativeEvents()
       expect(screen.renderer.getListScrollTop(listElement.id)?.[0]).toBe(previousScrollTop)
-      expect(ranges.length).toBeGreaterThan(previousRangeCount)
+      expect(ranges.at(-1)?.endIndex).toBe(shortenedCount)
     }, { timeout: 5_000 })
     expect(ranges.at(-1)).not.toStrictEqual(previousRange)
     expect(ranges.at(-1)?.startIndex).toBe(previousScrollTop)
diff --git a/packages/react/src/testing.ts b/packages/react/src/testing.ts
index 62f8923f..cef7febf 100644
--- a/packages/react/src/testing.ts
+++ b/packages/react/src/testing.ts
@@ -198,6 +198,7 @@ interface NativeTestRendererApi extends Omit<NativeRenderer, "requestFrame"> {
   getIntrinsicProbeLayoutCount(): number
   getStyleTransitionFrameRequestCount(): number
   drainEvents(): EventPayload[]
+  drainEventsOfType(eventType: string): EventPayload[]
   drainFrameTimestamps(): number[]
   setMenus(menus: MenuSpec[]): void
   simulateMenuAction(id: string): void
@@ -1222,22 +1223,36 @@ export class TestRenderer implements NativeRenderer {
    *  surface a further frame's worth of events — in a loop until nothing is
    *  left. */
   dispatchNativeEvents(): boolean {
+    return this.dispatchNativeEventsMatching()
+  }
+
+  /** Deliver visible-range updates produced by a committed render without
+   *  advancing unrelated native events queued for the test's next interaction. */
+  dispatchVisibleRangeEvents(): boolean {
+    return this.dispatchNativeEventsMatching("visibleRange")
+  }
+
+  private dispatchNativeEventsMatching(eventType?: EventPayload["eventType"]): boolean {
     const endResizeObserverDeliveryTurn = beginResizeObserverDeliveryTurn()
     try {
     const report = (error: unknown): void => reportUncaughtErrorToRenderer(this, error)
     let delivered = false
-    let hadPendingResizeObservations = false
-    actSync(report, () => {
-      hadPendingResizeObservations = flushPendingResizeObservations(this)
-    })
-    if (hadPendingResizeObservations) {
-      delivered = true
+    if (eventType === undefined) {
+      let hadPendingResizeObservations = false
+      actSync(report, () => {
+        hadPendingResizeObservations = flushPendingResizeObservations(this)
+      })
+      if (hadPendingResizeObservations) {
+        delivered = true
+      }
     }
     for (;;) {
-      const events = this.native.drainEvents()
-      if (events.length === 0) break
+      const matchingEvents = eventType === undefined
+        ? this.native.drainEvents()
+        : this.native.drainEventsOfType(eventType)
+      if (matchingEvents.length === 0) break
       delivered = true
-      const resizeEvents = events.filter(
+      const resizeEvents = matchingEvents.filter(
         (event): event is EventPayload & { entries: NonNullable<EventPayload["entries"]> } =>
           event.eventType === "resizeObservation" && Array.isArray(event.entries)
       )
@@ -1246,7 +1261,7 @@ export class TestRenderer implements NativeRenderer {
         for (const entry of event.entries) resizeEntries.set(entry.elementId, entry)
       }
       let resizeBatchDelivered = false
-      for (const event of events) {
+      for (const event of matchingEvents) {
         if (event.eventType === "resizeObservation") {
           if (!resizeBatchDelivered && resizeEvents[0]) {
             resizeBatchDelivered = true
@@ -3409,10 +3424,13 @@ export function createTestRoot(options: TestRootOptions = {}): TestRoot {
     actSync(reportRootError, () => root.render(node))
     // Trigger GPUI rendering pipeline after the React commit and its effects.
     renderer.flush()
+    // Deliver the next-frame range check after list layout and scroll
+    // anchoring have settled.
+    renderer.drawPendingFrame()
     // Native events produced by that render (for example, a virtual list's
     // visible range after its item count changes) are part of the committed
     // update. Deliver them before render returns, as the live renderer does.
-    renderer.dispatchNativeEvents()
+    renderer.dispatchVisibleRangeEvents()
   }
 
   const unmount = (): void => {