fix(react): preserve scroll authority across anchored rebuilds (#543)

* fix(react): preserve controller scroll authority

* fix(react): synchronize anchored scroll authority

Author: blove

.changeset/scroll-authority.md

@@ -0,0 +1,8 @@
+---
+"@pretable/react": patch
+---
+
+Preserve row-layout scroll anchoring across controller rebuilds. Grid/DOM
+viewport changes now enter the layout controller as explicit inputs, while
+anchor-adjusted controller publications flow back through grid state to the
+real scroll element without re-feeding the stale pre-anchor offset.

packages/react/src/__tests__/page-key-navigation.test.tsx

@@ -438,6 +438,14 @@ describe("a page key while the cursor's row is evicted", () => {
     expect(
       view.container.querySelector('[data-pretable-row-id="row-30"]'),
     ).not.toBeNull();
+    const viewport = view.container.querySelector<HTMLElement>(
+      "[data-pretable-scroll-viewport]",
+    );
+    if (viewport === null) throw new Error("no scroll viewport");
+    // The controller anchored the replacement window in global coordinates;
+    // its output must reach the real scroller before the DOM can publish
+    // another input. This is the integration half of the #524 authority seam.
+    expect(viewport.scrollTop).toBeGreaterThan(0);
 
     return { view, changes, seen, cursor };
   }
@@ -448,6 +456,16 @@ describe("a page key while the cursor's row is evicted", () => {
     seen: PretableSelectionState[],
     cursor: string,
   ) {
+    // Window 30 was reached by an anchored controller publication, which now
+    // correctly moves the real viewport to that window's global offset. A
+    // server-window consumer only loads window 0 again after the user scrolls
+    // back there, so model that input explicitly instead of relying on the old
+    // stale-DOM re-feed to reset the controller as a side effect.
+    const viewport = view.container.querySelector<HTMLElement>(
+      "[data-pretable-scroll-viewport]",
+    );
+    if (viewport === null) throw new Error("no scroll viewport");
+    fireEvent.scroll(viewport, { target: { scrollTop: 0 } });
     view.rerender(
       <WindowedGrid
         windowStart={0}

packages/react/src/__tests__/scroll-authority.test.tsx

@@ -0,0 +1,92 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+import { createColumnHelper, createLocalRowModel } from "@pretable/core";
+import type { RowLayoutController } from "@pretable-internal/renderer-dom";
+
+type Row = { id: number; label: string };
+
+const column = createColumnHelper<Row>();
+const columns = [
+  column.accessor("label", { type: "text", wrap: true, widthPx: 180 }),
+] as const;
+
+type Controller = RowLayoutController<Row, number, typeof columns>;
+
+const controllerRecords: Array<{
+  readonly controller: Controller;
+  readonly setViewport: ReturnType<typeof vi.fn<Controller["setViewport"]>>;
+}> = [];
+
+vi.mock("@pretable-internal/renderer-dom", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("@pretable-internal/renderer-dom")>();
+  const createRowLayoutController: typeof actual.createRowLayoutController = (
+    options,
+  ) => {
+    const controller = actual.createRowLayoutController(options);
+    const setViewport = vi.fn(controller.setViewport);
+    const wrapped = { ...controller, setViewport };
+    controllerRecords.push({
+      controller: wrapped as unknown as Controller,
+      setViewport: setViewport as unknown as ReturnType<
+        typeof vi.fn<Controller["setViewport"]>
+      >,
+    });
+    return wrapped;
+  };
+  return { ...actual, createRowLayoutController };
+});
+
+const { usePretable } = await import("../use-pretable");
+
+afterEach(() => {
+  cleanup();
+  controllerRecords.length = 0;
+  vi.clearAllMocks();
+});
+
+describe("scroll authority", () => {
+  test("a controller rebuild does not re-feed an unchanged grid viewport", async () => {
+    const rows = Array.from({ length: 2_000 }, (_, id): Row => ({
+      id,
+      label: `row ${id}`,
+    }));
+    const model = createLocalRowModel({ rows, columns });
+    const view = renderHook(() =>
+      usePretable({ model, overscan: 0, viewportHeight: 120 }),
+    );
+
+    expect(controllerRecords).toHaveLength(1);
+    const { controller, setViewport } = controllerRecords[0]!;
+    await expect.poll(() => controller.getState().status.kind).toBe("ready");
+
+    act(() => {
+      view.result.current.grid.setViewport({
+        scrollTop: 800,
+        scrollLeft: 0,
+        height: 120,
+        width: 600,
+      });
+    });
+    await expect.poll(() => controller.getState().scrollTop).toBe(800);
+    setViewport.mockClear();
+
+    await act(async () => {
+      model.setRows(
+        rows.map((_, offset): Row => ({
+          id: rows.length + offset,
+          label: `replacement ${offset}`,
+        })),
+      );
+      expect(controller.getState().status.kind).toBe("rebuilding");
+      await expect.poll(() => controller.getState().status.kind).toBe("ready");
+    });
+
+    expect(setViewport).not.toHaveBeenCalled();
+
+    view.unmount();
+    model.dispose();
+  });
+});

packages/react/src/pretable-model.ts

@@ -3,6 +3,7 @@ import {
   createRowLayoutController,
   type DomLayoutColumn,
 } from "@pretable-internal/renderer-dom";
+import { ɵqueriesSemanticallyEqual } from "@pretable-internal/row-model/query-equality";
 import {
   ɵcreateGridUiCore as createGridUiCore,
   type PretableGridUiState,
@@ -1038,21 +1039,93 @@ export function usePretableModelInternal<
     previousPresentationColumns.current = columns;
   }, [columns, stores.autoWidths, stores.gridCore]);
 
+  const viewportAuthorityRef = useRef<{
+    readonly gridScrollTop: number;
+    readonly controllerScrollTop: number;
+    readonly viewportHeight: number;
+    readonly overscan: number;
+    readonly observedQuery: typeof observedQuery;
+    readonly renderColumns: typeof renderColumns;
+  } | null>(null);
+  const controllerScrollTop = renderControllerSnapshot.scrollTop;
+  const viewportOverscan = options.overscan ?? 6;
   useLayoutEffect(() => {
-    if (renderControllerSnapshot.status.kind === "disposed") return;
-    stores.controller.setColumns(renderColumns);
-    stores.controller.setViewport({
-      scrollTop: gridSnapshot.viewport.scrollTop,
+    if (stores.controller.getState().status.kind === "disposed") return;
+
+    const previous = viewportAuthorityRef.current;
+    const gridChanged =
+      previous === null ||
+      previous.gridScrollTop !== gridSnapshot.viewport.scrollTop;
+    const viewportShapeChanged =
+      previous === null ||
+      previous.viewportHeight !== gridSnapshot.viewport.height ||
+      previous.overscan !== viewportOverscan;
+    const queryChanged =
+      previous !== null &&
+      !ɵqueriesSemanticallyEqual(previous.observedQuery, observedQuery);
+    const columnsChanged =
+      previous === null || previous.renderColumns !== renderColumns;
+    const controllerChanged =
+      previous !== null && previous.controllerScrollTop !== controllerScrollTop;
+
+    // Record the committed pair before publishing either side. A synchronous
+    // external-store notification can render immediately, and that render
+    // must classify the publication as the echo of this decision rather than
+    // as a second source of authority.
+    viewportAuthorityRef.current = {
+      gridScrollTop: gridSnapshot.viewport.scrollTop,
+      controllerScrollTop,
       viewportHeight: gridSnapshot.viewport.height,
-      overscan: options.overscan ?? 6,
-    });
+      overscan: viewportOverscan,
+      observedQuery,
+      renderColumns,
+    };
+
+    if (columnsChanged) {
+      stores.controller.setColumns(renderColumns);
+    }
+
+    if (gridChanged || viewportShapeChanged || queryChanged) {
+      // A real grid/DOM change is an input. When it races an anchored
+      // controller publication, the newer external input deliberately wins.
+      // A semantic query change also starts from the grid's position: sort,
+      // filter and grouping transitions keep the user's DOM offset rather
+      // than following an old row to its new dataset rank.
+      stores.controller.setViewport({
+        scrollTop: gridSnapshot.viewport.scrollTop,
+        viewportHeight: gridSnapshot.viewport.height,
+        overscan: viewportOverscan,
+      });
+      return;
+    }
+
+    if (
+      controllerChanged &&
+      controllerScrollTop !== gridSnapshot.viewport.scrollTop
+    ) {
+      // Anchor restoration is a controller output, not permission to re-feed
+      // the grid's previous offset. Publish it outward so the grid and DOM
+      // converge on the controller before another viewport input is possible.
+      const viewport = stores.gridCore.getState().viewport;
+      viewportAuthorityRef.current = {
+        ...viewportAuthorityRef.current,
+        gridScrollTop: controllerScrollTop,
+        controllerScrollTop,
+      };
+      stores.gridCore.setViewport({
+        ...viewport,
+        scrollTop: controllerScrollTop,
+      });
+    }
   }, [
+    controllerScrollTop,
     gridSnapshot.viewport.height,
     gridSnapshot.viewport.scrollTop,
-    options.overscan,
+    observedQuery,
     renderColumns,
-    renderControllerSnapshot.status.kind,
     stores.controller,
+    stores.gridCore,
+    viewportOverscan,
   ]);
 
   const observedRevision = renderControllerSnapshot.observedRevision;

packages/react/src/pretable-surface.tsx

@@ -2825,6 +2825,22 @@ export function PretableSurface<
     };
   }, [indexedSnapshot, rowModelSnapshot]);
 
+  // The DOM is the source of user scroll INPUT, but it is not the only writer:
+  // row anchoring can legitimately adjust the controller's global offset
+  // after content above the viewport changes. `usePretable` publishes that
+  // adjustment into the grid snapshot; apply it to the actual scroller before
+  // paint so its next scroll event cannot reassert the stale pre-anchor value.
+  useLayoutEffect(() => {
+    const viewport = viewportRef.current;
+    if (viewport === null) return;
+    if (viewport.scrollTop !== snapshot.viewport.scrollTop) {
+      viewport.scrollTop = snapshot.viewport.scrollTop;
+    }
+    if (viewport.scrollLeft !== snapshot.viewport.scrollLeft) {
+      viewport.scrollLeft = snapshot.viewport.scrollLeft;
+    }
+  }, [snapshot.viewport.scrollLeft, snapshot.viewport.scrollTop]);
+
   const surfaceContextRef = useRef({
     snapshot,
     rowModelSnapshot,

packages/react/vitest.config.ts

@@ -38,6 +38,10 @@ export default defineConfig({
         __dirname,
         "../renderer-dom/src/index.ts",
       ),
+      "@pretable-internal/row-model/query-equality": resolve(
+        __dirname,
+        "../row-model/src/query-equality.ts",
+      ),
       "@pretable-internal/row-model": resolve(
         __dirname,
         "../row-model/src/index.ts",

packages/row-model/package.json

@@ -19,6 +19,10 @@
     "./diagnostics": {
       "types": "./dist/diagnostics.d.ts",
       "import": "./dist/diagnostics.js"
+    },
+    "./query-equality": {
+      "types": "./dist/query-equality.d.ts",
+      "import": "./dist/query-equality.js"
     }
   },
   "scripts": {