@react-x11/components 0.2.0 → 0.2.1

package/src/internal/scroll.ts

@@ -0,0 +1,288 @@
+// Scrolling a row into view, when neither the row nor the scroll pane is
+// ready to be asked yet.
+//
+// **Shared between `<Tree>` and `<Table>`** — the third piece both
+// virtualizers stand on, beside `./heights.ts` and `./timers.ts`, and here
+// for the same reason: the logic is subtle, it is identical in both, and a
+// second copy of it is a second place for the bug below to come back.
+//
+// Two things a scroll pane does silently, both of them in the gap between a
+// commit and the layout it causes, and both of them enough on their own to
+// leave a virtualized list drawing rows the viewport is no longer looking at:
+//
+//   1. **`scrollTo` clamps against the content height the *last* layout
+//      measured.** A row appended in the commit now being laid out is past
+//      the bottom that clamp knows about, so the request lands short — and
+//      short *for good*, because nothing about it is retried. That is the
+//      live tail: a list that scrolls to its newest row on every update and
+//      settles one update behind, permanently. On mount, where no content
+//      has been laid out at all, the scroll simply never happens.
+//
+//   2. **The pane moves without saying so.** It resolves a queued
+//      `scrollIntoView` during layout, and it re-clamps an offset the
+//      content has outgrown or outshrunk — neither of which fires
+//      `onScroll`. A component that learns the offset only from that event
+//      keeps building its slice from where the pane *was*: the rows are
+//      drawn off-viewport, there is a blank band where they should be, and
+//      nothing puts it right until a scroll of your own re-syncs it by
+//      accident.
+//
+// So a reveal here is not a one-shot: it is a **debt**, kept by row id,
+// attempted at once and re-tried on the layout that makes the rest of the
+// move possible. It is dropped as soon as the row is in view, leaves the
+// list, or the user scrolls somewhere themselves — an owed scroll must never
+// yank the list back out from under a hand on the wheel.
+//
+// The offset is read back from the pane rather than trusted to the event;
+// `useReveal` does not do that itself, because what a component *does* with
+// the offset differs (a slice to rebuild, a header to shift), but it is the
+// other half of the same fix and both components run it on the same tick.
+
+import { useCallback, useEffect, useRef } from 'react';
+import type { DrawnNode, ScrollableNode } from 'react-x11';
+
+import type { RowHeights, RowKey } from './heights.js';
+import { afterLayout, cancelAfterLayout } from './timers.js';
+import type { LayoutTick } from './timers.js';
+
+/** All a reveal needs of a row: `<TreeRow>` and `<TableRow>` are both this. */
+interface Keyed {
+  id: RowKey;
+}
+
+/** A row on screen, and the index it was drawn at — the shape both
+ *  components already keep their mounted rows in. */
+interface Drawn {
+  node: DrawnNode;
+  at: number;
+}
+
+/** What the component lends the reveal: everything it already has, by ref,
+ *  so nothing here goes stale between a render and the tick after layout. */
+export interface RevealSources {
+  /** The scroll pane. `<Table>`'s body; `<Tree>`'s own root. */
+  box: { readonly current: ScrollableNode | null };
+  /** The rows in display order. */
+  rows: { readonly current: readonly Keyed[] };
+  /** The rows on screen, by id. */
+  nodes: { readonly current: ReadonlyMap<RowKey, Drawn> };
+  /** Where the rows that are *not* on screen are — and how tall a row that
+   *  has never been drawn is assumed to be. */
+  heights: RowHeights;
+}
+
+export interface Reveal {
+  /** Owe a scroll to this row, and try to pay it now. */
+  to(id: RowKey): void;
+  /**
+   * Try again: after a layout, or when the content changed size.
+   *
+   * Pass `provisional` on a pass where the height index just moved. The rows
+   * are still laid out at the heights it no longer believes, so a row that
+   * looks in view is not proof of anything yet — a row measured taller than
+   * the guess pushes everything after it down, and the row that was reached a
+   * moment ago ends up under the fold. The debt is kept until a pass that
+   * measured nothing new confirms it, which is exactly when the heights have
+   * converged.
+   */
+  retry(provisional?: boolean): void;
+  /** Scroll the pane, recording that this component is the one that asked. */
+  scrollTo(y: number): void;
+  /** An `onScroll` arrived. One this component did not ask for is the user
+   *  taking over, and it cancels whatever was owed. */
+  heard(scrollY: number): void;
+}
+
+/**
+ * The scroll a component owes a row, and the bookkeeping that pays it.
+ *
+ * Stable across renders — every method reads through the refs it was handed,
+ * so an event handler or a layout tick built in an earlier render still sees
+ * the current rows.
+ */
+export function useReveal(sources: RevealSources): Reveal {
+  const src = useRef(sources);
+  src.current = sources;
+  /** The row still owed a scroll, by id. */
+  const owed = useRef<RowKey | null>(null);
+  /**
+   * The row the last reveal settled on, kept for one reason: a measurement
+   * pass can move the heights that settlement was judged against. A row that
+   * was in view when the debt was paid is not in view any more once the rows
+   * around it turn out taller than the index believed, and the honest answer
+   * to "is that still true?" is to owe it again and look. Measurement
+   * converges, so this stops asking.
+   */
+  const settled = useRef<RowKey | null>(null);
+  /** The offset the last scroll *this component* asked for, so the
+   *  `onScroll` that answers it is not read as the user taking over. */
+  const asked = useRef<number | null>(null);
+  /**
+   * What the pane looked like at the last attempt that could not move.
+   *
+   * An attempt clamped by a content height that is a layout out of date has
+   * to be looked at again — and nothing else will schedule that look: the
+   * scroll that did not happen renders nothing, so the component's own tick
+   * after layout never comes. One is queued here instead, and only while the
+   * pane keeps changing under it: an attempt that finds the same offset and
+   * the same content as the last one has nothing new to try, and stops.
+   */
+  const stuck = useRef<{ y: number; content: number } | null>(null);
+  const look = useRef<LayoutTick>(null);
+  useEffect(() => () => cancelAfterLayout(look.current), []);
+
+  const scrollTo = useCallback((y: number): void => {
+    const box = src.current.box.current;
+    if (!box) return;
+    // Clamped here rather than left to the container, so what comes back on
+    // `onScroll` is the number that was asked for and can be recognised.
+    const to = Math.min(
+      Math.max(0, y),
+      Math.max(0, box.contentHeight - box.abs.height),
+    );
+    if (to === box.scrollY) return;
+    asked.current = to;
+    box.scrollTo({ y: to });
+  }, []);
+
+  const retry = useCallback(
+    (provisional?: boolean): void => {
+      const { box: boxRef, rows: rowsRef, nodes, heights } = src.current;
+      const box = boxRef.current;
+      // The heights just moved, so what the last reveal settled on was settled
+      // against numbers that have changed: owe it again until it can be
+      // confirmed at the new ones.
+      if (provisional && owed.current === null) owed.current = settled.current;
+      const id = owed.current;
+      if (!box || id === null) return;
+      const rows = rowsRef.current;
+      const at = rows.findIndex((r) => r.id === id);
+      if (at < 0) {
+        // the row left the list
+        owed.current = null;
+        settled.current = null;
+        return;
+      }
+      const viewport = box.abs.height;
+      if (viewport <= 0) return; // nothing laid out to scroll inside yet
+
+      // How far the row is outside the pane, in pixels of scrolling. The row's
+      // own rect answers when it is mounted — it knows what it really laid out
+      // at, and the arithmetic stays in screen coordinates, so a pane with
+      // padding on it needs no correction. The height index answers when the
+      // row is not mounted, which while virtualizing is the normal case.
+      const drawn = nodes.current.get(id);
+      const mounted =
+        drawn && drawn.node.abs.height > 0 && rows[drawn.at]?.id === id
+          ? drawn.node
+          : null;
+      const placed = mounted
+        ? {
+            above: box.abs.y - mounted.abs.y,
+            below: mounted.abs.y + mounted.abs.height - (box.abs.y + viewport),
+            height: mounted.abs.height,
+          }
+        : {
+            above: box.scrollY - heights.offsetAt(at),
+            below:
+              heights.offsetAt(at) +
+              heights.heightAt(at) -
+              (box.scrollY + viewport),
+            height: heights.heightAt(at),
+          };
+      /**
+       * Whether this is worth *settling* on, or only worth acting on.
+       *
+       * Two ways a row can look in view and not stay there. Its own placement
+       * may be a guess — the index's answer for a row nothing has measured —
+       * and "in view" judged from a guess is how a tail lands short of a bottom
+       * that has not been measured yet. Or a row *between* the viewport and it
+       * may still be a guess, and every one of those that turns out taller than
+       * the index believed pushes this row down by the difference, out of the
+       * view it had just been brought into.
+       *
+       * Both are settled by the same thing: measurement converges, so the rows
+       * that matter stop being guesses. A component that measures nothing at all
+       * has no guesses to wait on — `hasMeasurements` is how that is told
+       * apart, and it is what keeps a declared-uniform table from owing a debt
+       * for ever.
+       */
+      let certain = mounted !== null || heights.isMeasured(at);
+      if (certain && heights.hasMeasurements()) {
+        const from = Math.min(at, heights.indexAt(box.scrollY));
+        const to = Math.max(at, heights.indexAt(box.scrollY + viewport));
+        for (let i = from; i <= to && certain; i++) {
+          certain = heights.isMeasured(i);
+        }
+      }
+
+      let move = 0;
+      if (placed.height >= viewport) {
+        // A row taller than the pane is never *fully* in view, and asking for
+        // both its edges in turn is a debt that alternates for ever. Its top is
+        // the part worth showing — a wrapped row reads from its first line —
+        // and arriving there settles it.
+        move = -placed.above;
+      } else if (placed.above > 0) move = -placed.above;
+      else if (placed.below > 0) move = placed.below;
+
+      if (move === 0) {
+        // As far in view as it can be — settled, unless what that was judged
+        // against is still moving: a placement that came from a guess, or a
+        // pass that has just changed the heights under it.
+        if (certain && !provisional) {
+          settled.current = id;
+          owed.current = null;
+        }
+        return;
+      }
+      // A move the pane cannot make yet leaves the debt standing: the layout
+      // that admits the rows just appended is the one that will let it finish.
+      const was = box.scrollY;
+      scrollTo(was + move);
+      if (box.scrollY !== was) {
+        stuck.current = null; // it moved; the scroll it caused brings us back
+        return;
+      }
+      const seen = stuck.current;
+      const now = { y: box.scrollY, content: box.contentHeight };
+      stuck.current = now;
+      if (seen && seen.y === now.y && seen.content === now.content) return;
+      cancelAfterLayout(look.current);
+      look.current = afterLayout(() => {
+        look.current = null;
+        retryRef.current?.();
+      });
+    },
+    [scrollTo],
+  );
+
+  /** `retry` referring to itself through a ref, so the queued look calls the
+   *  current one rather than closing over the render that queued it. */
+  const retryRef = useRef<(() => void) | null>(null);
+  retryRef.current = retry;
+
+  const to = useCallback(
+    (id: RowKey): void => {
+      // Recorded before the attempt rather than after it, because the
+      // interesting case is the one that cannot succeed yet.
+      owed.current = id;
+      settled.current = null;
+      stuck.current = null;
+      retry();
+    },
+    [retry],
+  );
+
+  const heard = useCallback((scrollY: number): void => {
+    // A scroll this component did not ask for ends the whole chase, not just
+    // the outstanding half of it.
+    if (scrollY !== asked.current) {
+      owed.current = null;
+      settled.current = null;
+    }
+    asked.current = null;
+  }, []);
+
+  return { to, retry, scrollTo, heard };
+}

package/src/table/index.ts

@@ -64,6 +64,7 @@ import type { Host } from './hx.js';
 // header of src/internal/heights.ts says why.
 import { RowHeights } from '../internal/heights.js';
 import { afterLayout, cancelAfterLayout } from '../internal/timers.js';
+import { useReveal } from '../internal/scroll.js';
 import {
   MIN_COLUMN,
   columnValue,
@@ -577,6 +578,40 @@ export function Table<Row = any>(props: TableProps<Row>): ReactElement {
     [columns, userWidths, view.width],
   );
 
+  /**
+   * The scroll the table owes a row, and the pane's real offset read back
+   * after every layout — the two halves of `../internal/scroll.ts`, which
+   * says why a reveal cannot be a one-shot and why `onScroll` is not the
+   * whole story.
+   */
+  const reveal = useReveal({
+    box: body,
+    rows: orderedRef,
+    nodes: rowNodes,
+    heights,
+  });
+
+  /**
+   * Re-read the offset the body is *actually* at.
+   *
+   * The pane moves silently — it resolves a queued reveal during layout, and
+   * re-clamps an offset the content outgrew or outshrank — and a slice built
+   * from the offset before those is drawn where the viewport is not: a blank
+   * band where the rows should be, and no way back until a scroll of your own
+   * re-syncs it by accident.
+   */
+  const syncScroll = useCallback((): void => {
+    const box = body.current;
+    if (!box) return;
+    const { scrollX: x, scrollY: y } = box;
+    setScrollX((prev) => (prev === x ? prev : x));
+    // Only a virtualizing table reads the vertical offset — a whole one has
+    // no slice to rebuild, and re-rendering it on a scroll it already drew
+    // would be work for nothing.
+    if (virtualizing)
+      setView((prev) => (prev.top === y ? prev : { ...prev, top: y }));
+  }, [virtualizing]);
+
   /**
    * Read back what the rows on screen actually laid out at.
    *
@@ -587,12 +622,12 @@ export function Table<Row = any>(props: TableProps<Row>): ReactElement {
    * the viewport anchor shift the scroll offset by their delta, or
    * measuring a row already scrolled past yanks the list under the pointer.
    */
-  const measureRows = useCallback((): void => {
-    if (uniform || !virtualizing) return;
+  const measureRows = useCallback((): boolean => {
+    if (uniform || !virtualizing) return false;
     // Before the first `onViewport` the flex columns sit on their floors and
     // every row is laid out against a width that is about to change — there
     // is nothing honest to measure yet.
-    if (viewRef.current.width <= 0) return;
+    if (viewRef.current.width <= 0) return false;
     // A row laid out at a width the columns no longer resolve to is a
     // measurement of the wrong table, and it must not be recorded — a row
     // that scrolls out before the corrected pass would keep a wrong-width
@@ -620,45 +655,49 @@ export function Table<Row = any>(props: TableProps<Row>): ReactElement {
       changed = true;
       if (at < anchor) shift += height - was;
     }
-    if (!changed) return;
+    if (!changed) return false;
     if (shift !== 0 && box) {
-      box.scrollTo({ y: Math.max(0, box.scrollY + shift) });
+      reveal.scrollTo(box.scrollY + shift);
     }
     setMeasured((n) => n + 1);
+    return true;
     // eslint-disable-next-line react-hooks/exhaustive-deps -- `heights` is a
     // stable instance
   }, [uniform, virtualizing]);
 
+  /**
+   * The one tick after layout, and everything that can only be known there:
+   * what the rows measured, whether an owed scroll can go further now that
+   * the new rows are laid out, and where the body actually ended up. In that
+   * order — each step can move the offset the next one reads.
+   *
+   * Scheduled for every render a virtualized table makes, because every one
+   * of them can move the offset its next slice is built from. A whole table
+   * needs none of it: `onViewport` is when its content can have been
+   * re-clamped, and it rebuilds no slice anyway.
+   */
   useEffect(() => {
-    if (uniform || !virtualizing) return undefined;
-    const id = afterLayout(measureRows);
+    if (!virtualizing) return undefined;
+    const id = afterLayout(() => {
+      // `measureRows` first, and its answer handed on: a pass that moved the
+      // heights has not settled anything, and an owed scroll judged against
+      // the layout it is about to invalidate is not owed any less.
+      reveal.retry(measureRows());
+      syncScroll();
+    });
     return () => cancelAfterLayout(id);
   });
 
-  /**
-   * Put a row in view. A mounted row can say where it is, and
-   * `scrollIntoView` then works whatever height it turned out to be; a row
-   * that is not mounted has no geometry to ask, so the height index answers
-   * instead.
-   */
-  const reveal = useCallback((at: number): void => {
-    const box = body.current;
-    const row = orderedRef.current[at];
-    if (!box || !row) return;
-    const drawn = rowNodes.current.get(row.id);
-    if (drawn) {
-      box.scrollIntoView(drawn.node);
-      return;
-    }
-    const top = heights.offsetAt(at);
-    const rowH = heights.heightAt(at);
-    const height = viewRef.current.height;
-    if (top < box.scrollY) box.scrollTo({ y: top });
-    else if (height > 0 && top + rowH > box.scrollY + height) {
-      box.scrollTo({ y: top + rowH - height });
-    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
+  /** Put a row in view, by the index its call site already has. */
+  const revealAt = useCallback(
+    (at: number): void => {
+      const row = orderedRef.current[at];
+      if (row) reveal.to(row.id);
+      // eslint-disable-next-line react-hooks/exhaustive-deps -- `reveal` is a
+      // stable handle
+    },
+    [reveal],
+  );
 
   const commitSingle = useCallback(
     (row: TableRow<Row>): void => {
@@ -690,7 +729,7 @@ export function Table<Row = any>(props: TableProps<Row>): ReactElement {
       if (selectionMode === 'none') return;
       if (selectionMode === 'single') {
         commitSingle(row);
-        reveal(row.index);
+        revealAt(row.index);
         return;
       }
       cursorRef.current = row.id;
@@ -716,9 +755,9 @@ export function Table<Row = any>(props: TableProps<Row>): ReactElement {
         anchorRef.current = row.id;
         commitMulti([row.id], { type: 'replace', id: row.id, row: row.row });
       }
-      reveal(row.index);
+      revealAt(row.index);
     },
-    [selectionMode, commitSingle, commitMulti, reveal],
+    [selectionMode, commitSingle, commitMulti, revealAt],
   );
 
   const activate = useCallback(
@@ -882,13 +921,13 @@ export function Table<Row = any>(props: TableProps<Row>): ReactElement {
       scrollToRow: (id) => {
         const row = orderedRef.current.find((r) => r.id === id);
         if (!row) return false;
-        reveal(row.index);
+        revealAt(row.index);
         return true;
       },
       handleKey,
       rows: () => orderedRef.current,
     }),
-    [tap, handleKey, reveal, selectionMode, selected],
+    [tap, handleKey, revealAt, selectionMode, selected],
   );
 
   // --- rendering -----------------------------------------------------------
@@ -1185,6 +1224,10 @@ export function Table<Row = any>(props: TableProps<Row>): ReactElement {
         ref: body,
         style: s.body,
         onScroll: (ev) => {
+          // A scroll this component did not ask for is the user taking over,
+          // and an owed `scrollToRow` must not yank the list back out from
+          // under them on the next layout.
+          reveal.heard(ev.scrollY);
           setScrollX((prev) => (prev === ev.scrollX ? prev : ev.scrollX));
           if (virtualizing) {
             setView((prev) =>
@@ -1210,6 +1253,14 @@ export function Table<Row = any>(props: TableProps<Row>): ReactElement {
               ? prev
               : { ...prev, height: ev.height, width: ev.width },
           );
+          // The content just changed size, which is both the moment an owed
+          // scroll can reach further than the clamp let it and the moment the
+          // container may have re-clamped the offset without saying so. It is
+          // not a moment anything can be *settled* in while rows are still
+          // being measured: this runs from layout, a tick before the pass that
+          // reads those rows back.
+          reveal.retry(virtualizing && !uniform);
+          syncScroll();
           onViewport?.(ev);
         },
       },

package/src/tree/index.ts

@@ -59,6 +59,7 @@ import type { Host } from './hx.js';
 // header of src/internal/heights.ts says why.
 import { RowHeights } from '../internal/heights.js';
 import { afterLayout, cancelAfterLayout } from '../internal/timers.js';
+import { useReveal } from '../internal/scroll.js';
 import { typeAheadChar, useTypeAhead } from './internal.js';
 import {
   branchEdges,
@@ -571,32 +572,46 @@ export function Tree<T = TreeItem>({
   );
 
   /**
-   * Put a row in view.
+   * The scroll the tree owes a row, and the pane's real offset read back
+   * after every layout — the two halves of `../internal/scroll.ts`, which
+   * says why a reveal cannot be a one-shot and why `onScroll` is not the
+   * whole story. A tree grows and shrinks under its own hands: opening a
+   * branch is a content that got taller between the ask and the layout, in
+   * exactly the way an arriving row is.
+   */
+  const reveal = useReveal({
+    box: scroller,
+    rows: rowsRef,
+    nodes: rowNodes,
+    heights,
+  });
+
+  /** Put a row in view, by the index its call site already has. */
+  const revealAt = useCallback(
+    (at: number): void => {
+      const row = rowsRef.current[at];
+      if (row) reveal.to(row.id);
+      // eslint-disable-next-line react-hooks/exhaustive-deps -- `reveal` is a
+      // stable handle
+    },
+    [reveal],
+  );
+
+  /**
+   * Re-read the offset the pane is *actually* at.
    *
-   * A mounted row can say where it is, and `scrollIntoView` then works
-   * whatever height it turned out to be — which is what a tree that is *not*
-   * virtualizing wants, since nothing has measured its rows. A row that is not
-   * mounted has no geometry to ask about, and while virtualizing that is the
-   * normal case, so the height index answers instead: where the row starts,
-   * and how tall it is or is estimated to be.
+   * It moves silently — a queued reveal resolves during layout, and an offset
+   * the content outgrew or outshrank is re-clamped there — and a slice built
+   * from the offset before those is drawn where the viewport is not: a blank
+   * band where the rows should be, until a scroll of your own re-syncs it by
+   * accident.
    */
-  const reveal = useCallback((at: number): void => {
+  const syncScroll = useCallback((): void => {
     const box = scroller.current;
-    const row = rowsRef.current[at];
-    if (!box || !row) return;
-    const drawn = rowNodes.current.get(row.id);
-    if (drawn) {
-      box.scrollIntoView(drawn.node);
-      return;
-    }
-    const top = heights.offsetAt(at);
-    const rowH = heights.heightAt(at);
-    const height = viewRef.current.height;
-    if (top < box.scrollY) box.scrollTo({ y: top });
-    else if (height > 0 && top + rowH > box.scrollY + height) {
-      box.scrollTo({ y: top + rowH - height });
-    }
-  }, []);
+    if (!box || !virtualizing) return;
+    const y = box.scrollY;
+    setView((prev) => (prev.top === y ? prev : { ...prev, top: y }));
+  }, [virtualizing]);
 
   /**
    * Read back what the rows on screen actually laid out at.
@@ -611,8 +626,8 @@ export function Tree<T = TreeItem>({
    * reports no change, so the second pass over the same rows costs a map walk
    * and re-renders nothing, and measure → render → measure terminates.
    */
-  const measureRows = useCallback((): void => {
-    if (!virtualizing) return;
+  const measureRows = useCallback((): boolean => {
+    if (!virtualizing) return false;
     const box = scroller.current;
     const rows = rowsRef.current;
     const idx = heights;
@@ -631,16 +646,30 @@ export function Tree<T = TreeItem>({
       changed = true;
       if (at < anchor) shift += height - was;
     }
-    if (!changed) return;
+    if (!changed) return false;
     if (shift !== 0 && box) {
-      box.scrollTo({ y: Math.max(0, box.scrollY + shift) });
+      reveal.scrollTo(box.scrollY + shift);
     }
     setMeasured((n) => n + 1);
+    return true;
   }, [virtualizing]);
 
+  /**
+   * The one tick after layout, and everything that can only be known there:
+   * what the rows measured, whether an owed scroll can go further now that
+   * the rows it was waiting for are laid out, and where the pane actually
+   * ended up. In that order — each step can move the offset the next one
+   * reads.
+   */
   useEffect(() => {
     if (!virtualizing) return undefined;
-    const id = afterLayout(measureRows);
+    const id = afterLayout(() => {
+      // `measureRows` first, and its answer handed on: a pass that moved the
+      // heights has not settled anything, and an owed scroll judged against
+      // the layout it is about to invalidate is not owed any less.
+      reveal.retry(measureRows());
+      syncScroll();
+    });
     return () => cancelAfterLayout(id);
   });
 
@@ -650,9 +679,9 @@ export function Tree<T = TreeItem>({
       currentRef.current = row.id;
       if (selected === undefined) setOwnSelected(row.id);
       onSelect?.(row.id, row.item);
-      reveal(row.index);
+      revealAt(row.index);
     },
-    [selected, onSelect, reveal],
+    [selected, onSelect, revealAt],
   );
 
   const activate = useCallback(
@@ -799,13 +828,13 @@ export function Tree<T = TreeItem>({
       scrollToItem: (id) => {
         const row = rowsRef.current.find((r) => r.id === id);
         if (!row) return false;
-        reveal(row.index);
+        revealAt(row.index);
         return true;
       },
       handleKey,
       rows: () => rowsRef.current,
     }),
-    [goTo, toggleId, reveal, handleKey, selected, accessors],
+    [goTo, toggleId, revealAt, handleKey, selected, accessors],
   );
 
   // --- rendering -----------------------------------------------------------
@@ -1071,9 +1100,20 @@ export function Tree<T = TreeItem>({
         setView((prev) =>
           prev.height === ev.height ? prev : { ...prev, height: ev.height },
         );
+        // The content just changed size, which is both the moment an owed
+        // scroll can reach further than the clamp let it and the moment the
+        // pane may have re-clamped its offset without saying so. It is not a
+        // moment anything can be *settled* in: this runs from layout, a tick
+        // before the pass that reads the rows it just drew back.
+        reveal.retry(virtualizing);
+        syncScroll();
         onViewport?.(ev);
       },
       onScroll: (ev) => {
+        // A scroll this component did not ask for is the user taking over,
+        // and an owed reveal must not yank the tree back out from under them
+        // on the next layout.
+        reveal.heard(ev.scrollY);
         if (virtualizing) {
           setView((prev) =>
             prev.top === ev.scrollY ? prev : { ...prev, top: ev.scrollY },