@doync/query-virtualizer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vitor Buzinaro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,252 @@
+# `@doync/query-virtualizer`
+
+React binding for virtualized infinite lists over doync Subscriptions. Stage factories return a Bound query; the hook keeps three live `useQuery` slots (main page, after page, single-row) filled as you scroll, and renders only the visible window. Built on `@rocicorp/zero-virtual` **`/core` only** — consumers do not declare or import zero-virtual themselves. This package's root export is the stable surface; deeper experimental core symbols stay on `@rocicorp/zero-virtual/core` and may move with that pin.
+
+Use it under a `@doync/react` `<DoyncProvider>` with registered queries that support keyset (or equivalent) pagination.
+
+## Install
+
+```sh
+pnpm add @doync/query-virtualizer
+```
+
+| Package | Role |
+| --- | --- |
+| `@doync/query-virtualizer` | This binding |
+| `@doync/react`, `@doync/core` | Direct dependencies (pulled in transitively — import `DoyncProvider` / hooks from `@doync/react` as usual) |
+| `react` | **Peer** — `>=18` |
+
+`@rocicorp/zero-virtual` is a direct dependency of this package pinned for you; do not add it to the app unless you intentionally opt into `/core` experimental APIs.
+
+## Quick sketch
+
+An overflow-element list. Factories that do not close over props can live at module scope so their identity stays stable across renders (a fresh `estimateSize` / `getRowKey` / factory each render resets paging).
+
+```tsx
+import {
+  rowAttributes,
+  useQueryVirtualizer,
+  type VirtualRow,
+} from '@doync/query-virtualizer'
+import { queries } from './shared/data'
+import { useCallback, useRef } from 'react'
+
+type Task = { id: string; title: string; modified: number }
+type TaskStart = { id: string; modified: number }
+
+const estimateSize = () => 48
+const getRowKey = (row: Task) => row.id
+const toStartRow = (row: Task): TaskStart => ({
+  id: row.id,
+  modified: row.modified,
+})
+const getSingleQuery = ({ id }: { id: string; settled: boolean }) => ({
+  query: queries.taskById(id),
+})
+
+export function TaskList({ ownerId }: { ownerId: string }) {
+  const listRef = useRef<HTMLDivElement>(null)
+  const getScrollElement = useCallback(() => listRef.current, [])
+
+  const getPageQuery = useCallback(
+    ({
+      limit,
+      start,
+      dir,
+    }: {
+      limit: number
+      start: TaskStart | null
+      dir: 'forward' | 'backward'
+      settled: boolean
+    }) => ({
+      // Bound query — registry leaf + args. Optional `options` (ttl, skip, …)
+      // is the per-stage UseQueryOptions bag.
+      query: queries.taskPage({ ownerId, limit, start, dir }),
+    }),
+    [ownerId],
+  )
+
+  const { items, spaceBefore, spaceAfter, status } = useQueryVirtualizer<
+    string,
+    Task,
+    TaskStart
+  >({
+    listContextParams: ownerId, // any stable context; change resets the list
+    getScrollElement,
+    estimateSize,
+    getRowKey,
+    getPageQuery,
+    getSingleQuery,
+    toStartRow,
+  })
+
+  return (
+    <div
+      ref={listRef}
+      style={{ height: 480, overflow: 'auto', position: 'relative' }}
+    >
+      {/* Spacers are sibling elements — not padding on the scroller —
+          so native scroll anchoring can compensate. */}
+      <div style={{ height: spaceBefore }} />
+      {items.map((item) => (
+        <TaskRow key={item.key} item={item} />
+      ))}
+      <div style={{ height: spaceAfter }} />
+      {status.status !== 'complete' ? <div>Loading…</div> : null}
+    </div>
+  )
+}
+
+function TaskRow({ item }: { item: VirtualRow<Task> }) {
+  const { index, key, row } = item
+  if (row === undefined) {
+    return (
+      <div {...rowAttributes(index, key)} style={{ height: 48 }}>
+        …
+      </div>
+    )
+  }
+  return (
+    <div {...rowAttributes(index, key)} style={{ height: 48 }}>
+      {row.title}
+    </div>
+  )
+}
+```
+
+Window-scrolled lists use `useQueryWindowVirtualizer` with the same options: `getScrollElement` then returns the element rows render into (normal page flow); the window is the scroll container.
+
+## Public API
+
+### Hooks
+
+#### `useQueryVirtualizer(options) → QueryVirtualizerResult`
+
+Virtualized, infinitely-paginated list that scrolls inside an overflow element. `getScrollElement` returns that element (also where rows render).
+
+#### `useQueryWindowVirtualizer(options) → QueryVirtualizerResult`
+
+Same contract, window as the scroll container.
+
+Both take `UseQueryVirtualizerOptions<TListContextParams, TRow, TStartRow>`:
+
+| Option | Required | Notes |
+| --- | --- | --- |
+| `listContextParams` | yes | Opaque list context. A value change (by the core's comparison) resets paging / window. |
+| `getScrollElement` | yes | `() => HTMLElement \| null` — overflow scroller, or the rows host for the window variant. |
+| `estimateSize` | yes | `(index) => number` — estimated row height in px. Keep referentially stable. |
+| `getRowKey` | yes | `(row) => RowKey` — stable id per data row. |
+| `getPageQuery` | yes | `GetPageQuery` — see [Stage factories](#stage-factories). |
+| `getSingleQuery` | yes | `GetSingleQuery` — one-row Bound query for permalink / anchor rows. |
+| `toStartRow` | yes | `(row) => TStartRow` — maps a data row to the keyset cursor `getPageQuery` receives as `start`. |
+| `overscan` | no | Extra rows rendered past the viewport (default from zero-virtual core). |
+| `count` | no | Known total row count when the app already has one; otherwise the composition estimates. |
+| `anchoring` | no | `AnchoringMode` — e.g. `'native'` for comment-style natural-height lists. |
+| `minPageSize` | no | Floor on rows requested per page (default 50; lower for tall cards). |
+| `settleTime` | no | Idle ms before the list is considered settled (default 2000). |
+| `onSettled` | no | Fired when the list has been idle for `settleTime`. |
+| `permalinkID` | no | Row id to scroll into view once present. |
+| `scrollState` / `onScrollStateChange` | no | Persist / restore window (`ScrollHistoryState`). Pair with `useRestoreScrollState` or your router. |
+| `observeElementRect` / `observeElementOffset` | no | Override default observers (element vs window defaults are filled in per entry). |
+
+`QueryVirtualizerResult<TRow>` is the zero-virtual binding result without the upstream `complete` boolean, plus aggregated doync `status`:
+
+| Field | Notes |
+| --- | --- |
+| `items` | `VirtualRow<TRow>[]` currently on screen (and overscan). `row` may be `undefined` while a slot is still loading. |
+| `spaceBefore` / `spaceAfter` | Spacer heights in px — render as sibling elements, not scroller padding. |
+| `status` | Aggregated `ViewStatus` from live stages (`unknown` → `complete` / `error`). Replaces upstream `complete`. |
+| `rowsEmpty` | True when the composition has no data rows. |
+| `permalinkNotFound` | True when a `permalinkID` could not be resolved. |
+| `estimatedTotal` / `total` | Size hints from the composition. |
+| `settled` | True after the list has been idle for `settleTime`. |
+| `scrollElement` | Live `HTMLElement \| null` — the resolved scroller (`null` until mounted). |
+| `options` | Bound scroll/observer accessors (used by `usePinToBottom`). |
+| `rowAt` | `(index) => TRow \| undefined` — data row at a virtual index. |
+
+#### `usePinToBottom(virtualizer, options?)`
+
+Chat/log follow: when content grows, keep the viewport pinned to the bottom — only if the user was already parked there. Pass the result of `useQueryVirtualizer` / `useQueryWindowVirtualizer`.
+
+```ts
+import {
+  usePinToBottom,
+  useQueryWindowVirtualizer,
+} from '@doync/query-virtualizer'
+
+const result = useQueryWindowVirtualizer({/* … */})
+usePinToBottom(result)
+// usePinToBottom(result, { enabled: true, slack: 8 })
+```
+
+`PinToBottomOptions`: `{ enabled?: boolean; slack?: number }`.
+
+#### `useRestoreScrollState(key?) → [scrollState, setScrollState]`
+
+Persist virtualizer scroll under a key in `window.history.state` (Navigation API). Pass the tuple to `scrollState` / `onScrollStateChange`. Default key is `"scrollState"`. Requires the Navigation API (Firefox 147+); older browsers should wire a different persist layer (zbugs uses wouter glue).
+
+```ts
+const [scrollState, setScrollState] = useRestoreScrollState<TaskStart>('tasks')
+
+useQueryVirtualizer({
+  /* … */
+  scrollState,
+  onScrollStateChange: setScrollState,
+})
+```
+
+### Stage factories
+
+Each stage returns a `QueryResult` — a Bound query plus optional per-stage `useQuery` options (`ttl`, consumer `skip`, …). Args ride inside the bound value. A null/absent stage from the core is expressed as a falsy query into `useQuery`, not a placeholder swap.
+
+```ts
+import type {
+  GetPageQuery,
+  GetSingleQuery,
+  QueryResult,
+} from '@doync/query-virtualizer'
+
+// GetPageQueryOptions: { limit, start, dir, settled }
+const getPageQuery: GetPageQuery<Task, TaskStart> = ({
+  limit,
+  start,
+  dir,
+}) => ({
+  query: queries.taskPage({ limit, start, dir }),
+  // options: { ttl: 'none' },
+})
+
+// GetSingleQueryOptions: { id, settled }
+const getSingleQuery: GetSingleQuery<Task> = ({ id }) => ({
+  query: queries.taskById(id),
+})
+```
+
+| Type | Shape |
+| --- | --- |
+| `QueryResult<Row, One>` | `{ query: BoundQuery<Row, One>; options?: UseQueryOptions }` |
+| `GetPageQuery<TRow, TStartRow>` | `(GetPageQueryOptions<TStartRow>) => QueryResult<TRow, false>` |
+| `GetSingleQuery<TRow>` | `(GetSingleQueryOptions) => QueryResult<TRow, true>` |
+| `GetPageQueryOptions` / `GetSingleQueryOptions` | Re-exported from `@rocicorp/zero-virtual/core` |
+
+### Helpers and shared types
+
+| Symbol | Role |
+| --- | --- |
+| `rowAttributes(index, key)` | Spread onto each virtual row element so measurement / anchoring can find it. |
+| `VirtualRow<TRow>` | `{ index, key, row?: TRow, … }` — one entry in `items`. |
+| `RowKey` | Stable row identity type (`string \| number`). |
+| `AnchoringMode` | Scroll-anchoring strategy. |
+| `ScrollHistoryState<TStartRow>` | Persisted scroll blob for restore. |
+| `ViewStatus` | Re-export from `@doync/react` — aggregated stage status on the result. |
+
+## Public surface
+
+The main entry (`.`) is governed by semver. Documented public symbols:
+
+- **Runtime**: `useQueryVirtualizer`, `useQueryWindowVirtualizer`, `usePinToBottom`, `useRestoreScrollState`, `rowAttributes`
+- **Types**: `UseQueryVirtualizerOptions`, `QueryVirtualizerResult`, `QueryResult`, `GetPageQuery`, `GetSingleQuery`, `GetPageQueryOptions`, `GetSingleQueryOptions`, `PinToBottomOptions`, `VirtualRow`, `RowKey`, `AnchoringMode`, `ScrollHistoryState`, `ViewStatus`
+
+## Internal (`@doync/query-virtualizer/internal`)
+
+Anything imported from `@doync/query-virtualizer/internal` is **not** part of the semver surface. It may change or disappear in any release, including patches, without notice. Sibling `@doync/*` packages reach internals through that specifier when they must; application code should not. Import the virtualizer hooks from `@doync/query-virtualizer`.

package/dist/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("@rocicorp/zero-virtual/core"),t=require("react"),n=require("@doync/react");const r=Object.freeze({status:`unknown`});function i(e,t){for(let t of e)if(t.status===`error`)return t;return t?{status:`complete`}:r}function a(e){return e!==null&&e.options?.skip!==!0}function o({pageSize:r,anchor:o,settled:s,getPageQuery:c,getSingleQuery:l,toStartRow:u},d=n.useQuery){let f={pageSize:r,anchor:o,settled:s},p=(0,e.buildSingleQuery)(f,l),[m,h]=d(p?.query??!1,p?.options),g=m??void 0,_=h.status===`complete`,v=(0,e.permalinkMissing)(f,g,_),y=g?u(g):null,b=a(p),x=(0,e.buildMainQuery)(f,c,y,v),[S,C]=d(x?.query??!1,x?.options),w=C.status===`complete`,T=a(x),E=(0,e.buildAfterQuery)(f,c,y,v),[D,O]=d(E?.query??!1,E?.options),k=O.status===`complete`,A=a(E);return(0,t.useMemo)(()=>{let t=(0,e.assembleRows)({pageSize:r,anchor:o,settled:s},{singleRow:g,singleComplete:_,mainRows:S,mainComplete:w,afterRows:D,afterComplete:k}),n=[];return b&&n.push(h),T&&n.push(C),A&&n.push(O),{rows:t,status:i(n,t.complete)}},[r,o,s,g,_,h,b,S,w,C,T,D,k,O,A])}function s(n,r){let[,i]=(0,t.useReducer)(()=>({}),{}),[a]=(0,t.useState)(()=>new e.ZeroVirtualizer(n,r));a.setOptions(n);let{pageSize:s,anchor:c,settled:l}=a.getQueryInputs(),{rows:u,status:d}=o({pageSize:s,anchor:c,settled:l,getPageQuery:n.getPageQuery,getSingleQuery:n.getSingleQuery,toStartRow:n.toStartRow});a.setRows(u),(0,t.useLayoutEffect)(()=>{let e=a.subscribe(i);return()=>{e(),a.detach()}},[a]),(0,t.useLayoutEffect)(()=>{a.attach(n.getScrollElement()),a.afterDOMUpdate()});let{getScrollElement:f,observeElementRect:p,observeElementOffset:m}=n,h=(0,t.useMemo)(()=>({getScrollElement:f,observeElementRect:p,observeElementOffset:m}),[f,p,m]),g=a.getSnapshot(),_=d;return(0,t.useMemo)(()=>{let{complete:t,...n}=(0,e.virtualizerResult)(g,h,r);return{...n,status:_}},[g,h,r,_])}function c(t){return s({...t,observeElementRect:t.observeElementRect??e.observeElementRect,observeElementOffset:t.observeElementOffset??e.observeElementOffset},e.resolveElementScrollElement)}function l(t){return s({...t,observeElementRect:t.observeElementRect??e.observeWindowRect,observeElementOffset:t.observeElementOffset??e.observeWindowOffset},e.resolveWindowScrollElement)}function u(n,{enabled:r=!0,slack:i=e.DEFAULT_STICK_SLACK}={}){let a=(0,t.useRef)(null);(0,t.useLayoutEffect)(()=>{if(!r){a.current?.detach();return}(a.current??=(0,e.createStickToBottomCache)()).ensure(n,i)}),(0,t.useLayoutEffect)(()=>()=>{a.current?.detach(),a.current=null},[])}function d(){return[(0,t.useSyncExternalStore)(e.subscribeHistoryState,e.getHistoryStateSnapshot,e.getHistoryStateServerSnapshot),e.updateHistoryState]}function f(n=`scrollState`){let[r,i]=d();return[(0,t.useMemo)(()=>r?r[n]??null:null,[r&&JSON.stringify(r[n]),n]),(0,t.useCallback)(t=>{let r=(0,e.getHistoryStateSnapshot)();i({...r,[n]:t})},[i,n])]}Object.defineProperty(exports,"rowAttributes",{enumerable:!0,get:function(){return e.rowAttributes}}),exports.usePinToBottom=u,exports.useQueryVirtualizer=c,exports.useQueryWindowVirtualizer=l,exports.useRestoreScrollState=f;

package/dist/index.d.cts

@@ -0,0 +1,92 @@
+import { UseQueryOptions, ViewStatus, ViewStatus as ViewStatus$1 } from "@doync/react";
+import { BoundQuery } from "@doync/core";
+import { AnchoringMode, GetPageQueryOptions, GetSingleQueryOptions, RowKey, ScrollHistoryState, ScrollHistoryState as ScrollHistoryState$1, StickOptions, VirtualRow, VirtualizerBindingOptions, VirtualizerResult, rowAttributes } from "@rocicorp/zero-virtual/core";
+
+//#region src/types.d.ts
+/**
+* What a page/single factory returns: a bound query plus optional `useQuery`
+* options (`ttl`, `skip`). Args live on the bound value.
+*/
+type QueryResult<Row extends Record<string, unknown> = Record<string, unknown>, One extends boolean = boolean> = {
+  readonly query: BoundQuery<Row, One>;
+  readonly options?: UseQueryOptions | undefined;
+};
+/**
+* Page-query factory: given `{ limit, start, dir, settled }`, return a
+* multi-row bound query.
+*/
+type GetPageQuery<TRow extends Record<string, unknown>, TStartRow> = (options: GetPageQueryOptions<TStartRow>) => QueryResult<TRow, false>;
+/**
+* Single-row factory: given `{ id, settled }`, return a one-row bound query (``
+* sql.one`…` `` / `findFirst`).
+*/
+type GetSingleQuery<TRow extends Record<string, unknown>> = (options: GetSingleQueryOptions) => QueryResult<TRow, true>;
+/**
+* Options for {@link useQueryVirtualizer} / {@link useQueryWindowVirtualizer}.
+* Provide `getPageQuery` and `getSingleQuery` factories that return bound
+* queries.
+*/
+type UseQueryVirtualizerOptions<TListContextParams, TRow extends Record<string, unknown>, TStartRow> = VirtualizerBindingOptions<TListContextParams, TRow, TStartRow, BoundQuery<TRow, false>, UseQueryOptions, BoundQuery<TRow, true>, UseQueryOptions> & {
+  getPageQuery: GetPageQuery<TRow, TStartRow>;
+  getSingleQuery: GetSingleQuery<TRow>;
+};
+/**
+* Virtualizer result: virtual items, scroll helpers, and aggregated
+* {@link ViewStatus} from the live page stages (replaces core's `complete`
+* boolean).
+*/
+type QueryVirtualizerResult<TRow> = Omit<VirtualizerResult<TRow>, "complete"> & {
+  readonly status: ViewStatus$1;
+};
+//#endregion
+//#region src/use-query-virtualizer.d.ts
+/**
+* Virtualized infinite list inside an overflow element. `getScrollElement`
+* returns that element (also where rows render). Provide page/single query
+* factories via {@link UseQueryVirtualizerOptions}.
+*
+* ```ts
+* const v = useQueryVirtualizer({
+*   getScrollElement: () => listRef.current,
+*   estimateSize: () => 48,
+*   getPageQuery: ({ limit, start, dir }) => ({
+*     query: queries.items.page({ limit, start, dir }),
+*   }),
+*   getSingleQuery: ({ id }) => ({
+*     query: queries.items.byId({ id }),
+*   }),
+*   // …
+* })
+* ```
+*/
+declare function useQueryVirtualizer<TListContextParams, TRow extends Record<string, unknown>, TStartRow>(options: UseQueryVirtualizerOptions<TListContextParams, TRow, TStartRow>): QueryVirtualizerResult<TRow>;
+/**
+* Like {@link useQueryVirtualizer}, but the window is the scroll container.
+* `getScrollElement` returns the element rows render into (normal page flow).
+*/
+declare function useQueryWindowVirtualizer<TListContextParams, TRow extends Record<string, unknown>, TStartRow>(options: UseQueryVirtualizerOptions<TListContextParams, TRow, TStartRow>): QueryVirtualizerResult<TRow>;
+//#endregion
+//#region src/use-pin-to-bottom.d.ts
+/** Options for {@link usePinToBottom}: `enabled` and bottom-edge `slack`. */
+type PinToBottomOptions = StickOptions;
+/**
+* Keep a chat/log list pinned to the bottom when content grows — only while the
+* user is already at the bottom. Pass the result of `useQueryVirtualizer` /
+* `useQueryWindowVirtualizer`.
+*/
+declare function usePinToBottom<TRow>(virtualizer: QueryVirtualizerResult<TRow>, {
+  enabled,
+  slack
+}?: PinToBottomOptions): void;
+//#endregion
+//#region src/use-restore-scroll-state.d.ts
+/**
+* Persist virtualizer scroll under a key in `history.state` (Navigation API).
+* Pass the returned `[scrollState, setScrollState]` into `useQueryVirtualizer`.
+* Default key is `"scrollState"`; use distinct keys for multiple lists.
+* Requires the Navigation API (Firefox 147+).
+*/
+declare function useRestoreScrollState<TStartRow>(key?: string): [ScrollHistoryState$1<TStartRow> | null, (state: ScrollHistoryState$1<TStartRow> | null) => void];
+//#endregion
+export { type AnchoringMode, type GetPageQuery, type GetPageQueryOptions, type GetSingleQuery, type GetSingleQueryOptions, type PinToBottomOptions, type QueryResult, type QueryVirtualizerResult, type RowKey, type ScrollHistoryState, type UseQueryVirtualizerOptions, type ViewStatus, type VirtualRow, rowAttributes, usePinToBottom, useQueryVirtualizer, useQueryWindowVirtualizer, useRestoreScrollState };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/types.ts","../src/use-query-virtualizer.ts","../src/use-pin-to-bottom.ts","../src/use-restore-scroll-state.ts"],"mappings":";;;;;;;AAiBA;;KAAY,WAAA,aACE,MAAA,oBAA0B,MAAA;EAAA,SAG7B,KAAA,EAAO,UAAA,CAAW,GAAA,EAAK,GAAA;EAAA,SACvB,OAAA,GAAU,eAAA;AAAA;;;;;KAOT,YAAA,cAA0B,MAAA,iCACpC,OAAA,EAAS,mBAAA,CAAoB,SAAA,MAC1B,WAAA,CAAY,IAAA;;;;;KAML,cAAA,cAA4B,MAAA,sBACtC,OAAA,EAAS,qBAAA,KACN,WAAA,CAAY,IAAA;AAjBI;AAOrB;;;;AAPqB,KAwBT,0BAAA,kCAEG,MAAA,gCAEX,yBAAA,CACF,kBAAA,EACA,IAAA,EACA,SAAA,EACA,UAAA,CAAW,IAAA,UACX,eAAA,EACA,UAAA,CAAW,IAAA,SACX,eAAA;EAEA,YAAA,EAAc,YAAA,CAAa,IAAA,EAAM,SAAA;EACjC,cAAA,EAAgB,cAAA,CAAe,IAAA;AAAA;;;;;;KAQrB,sBAAA,SAA+B,IAAA,CACzC,iBAAA,CAAsB,IAAA;EAAA,SAGb,MAAA,EAAQ,YAAA;AAAA;;;;;;AAvDnB;;;;;;;;;;;;;;;;iBC8GgB,mBAAA,kCAED,MAAA,8BAGb,OAAA,EAAS,0BAAA,CAA2B,kBAAA,EAAoB,IAAA,EAAM,SAAA,IAC7D,sBAAA,CAAuB,IAAA;;AD/GL;AAOrB;;iBCwHgB,yBAAA,kCAED,MAAA,8BAGb,OAAA,EAAS,0BAAA,CAA2B,kBAAA,EAAoB,IAAA,EAAM,SAAA,IAC7D,sBAAA,CAAuB,IAAA;;;;KChJd,kBAAA,GAAqB,YAAA;;AFMjC;;;;iBECgB,cAAA,OACd,WAAA,EAAa,sBAAA,CAAuB,IAAA;EAClC,OAAA;EAAgB;AAAA,IAA+B,kBAAA;;;;;;;AFHnD;;iBGiBgB,qBAAA,YACd,GAAA,aAEA,oBAAA,CAAmB,SAAA,WAClB,KAAA,EAAO,oBAAA,CAAmB,SAAA"}

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+import { AnchoringMode, GetPageQueryOptions, GetSingleQueryOptions, RowKey, ScrollHistoryState, ScrollHistoryState as ScrollHistoryState$1, StickOptions, VirtualRow, VirtualizerBindingOptions, VirtualizerResult, rowAttributes } from "@rocicorp/zero-virtual/core";
+import { UseQueryOptions, ViewStatus, ViewStatus as ViewStatus$1 } from "@doync/react";
+import { BoundQuery } from "@doync/core";
+
+//#region src/types.d.ts
+/**
+* What a page/single factory returns: a bound query plus optional `useQuery`
+* options (`ttl`, `skip`). Args live on the bound value.
+*/
+type QueryResult<Row extends Record<string, unknown> = Record<string, unknown>, One extends boolean = boolean> = {
+  readonly query: BoundQuery<Row, One>;
+  readonly options?: UseQueryOptions | undefined;
+};
+/**
+* Page-query factory: given `{ limit, start, dir, settled }`, return a
+* multi-row bound query.
+*/
+type GetPageQuery<TRow extends Record<string, unknown>, TStartRow> = (options: GetPageQueryOptions<TStartRow>) => QueryResult<TRow, false>;
+/**
+* Single-row factory: given `{ id, settled }`, return a one-row bound query (``
+* sql.one`…` `` / `findFirst`).
+*/
+type GetSingleQuery<TRow extends Record<string, unknown>> = (options: GetSingleQueryOptions) => QueryResult<TRow, true>;
+/**
+* Options for {@link useQueryVirtualizer} / {@link useQueryWindowVirtualizer}.
+* Provide `getPageQuery` and `getSingleQuery` factories that return bound
+* queries.
+*/
+type UseQueryVirtualizerOptions<TListContextParams, TRow extends Record<string, unknown>, TStartRow> = VirtualizerBindingOptions<TListContextParams, TRow, TStartRow, BoundQuery<TRow, false>, UseQueryOptions, BoundQuery<TRow, true>, UseQueryOptions> & {
+  getPageQuery: GetPageQuery<TRow, TStartRow>;
+  getSingleQuery: GetSingleQuery<TRow>;
+};
+/**
+* Virtualizer result: virtual items, scroll helpers, and aggregated
+* {@link ViewStatus} from the live page stages (replaces core's `complete`
+* boolean).
+*/
+type QueryVirtualizerResult<TRow> = Omit<VirtualizerResult<TRow>, "complete"> & {
+  readonly status: ViewStatus$1;
+};
+//#endregion
+//#region src/use-query-virtualizer.d.ts
+/**
+* Virtualized infinite list inside an overflow element. `getScrollElement`
+* returns that element (also where rows render). Provide page/single query
+* factories via {@link UseQueryVirtualizerOptions}.
+*
+* ```ts
+* const v = useQueryVirtualizer({
+*   getScrollElement: () => listRef.current,
+*   estimateSize: () => 48,
+*   getPageQuery: ({ limit, start, dir }) => ({
+*     query: queries.items.page({ limit, start, dir }),
+*   }),
+*   getSingleQuery: ({ id }) => ({
+*     query: queries.items.byId({ id }),
+*   }),
+*   // …
+* })
+* ```
+*/
+declare function useQueryVirtualizer<TListContextParams, TRow extends Record<string, unknown>, TStartRow>(options: UseQueryVirtualizerOptions<TListContextParams, TRow, TStartRow>): QueryVirtualizerResult<TRow>;
+/**
+* Like {@link useQueryVirtualizer}, but the window is the scroll container.
+* `getScrollElement` returns the element rows render into (normal page flow).
+*/
+declare function useQueryWindowVirtualizer<TListContextParams, TRow extends Record<string, unknown>, TStartRow>(options: UseQueryVirtualizerOptions<TListContextParams, TRow, TStartRow>): QueryVirtualizerResult<TRow>;
+//#endregion
+//#region src/use-pin-to-bottom.d.ts
+/** Options for {@link usePinToBottom}: `enabled` and bottom-edge `slack`. */
+type PinToBottomOptions = StickOptions;
+/**
+* Keep a chat/log list pinned to the bottom when content grows — only while the
+* user is already at the bottom. Pass the result of `useQueryVirtualizer` /
+* `useQueryWindowVirtualizer`.
+*/
+declare function usePinToBottom<TRow>(virtualizer: QueryVirtualizerResult<TRow>, {
+  enabled,
+  slack
+}?: PinToBottomOptions): void;
+//#endregion
+//#region src/use-restore-scroll-state.d.ts
+/**
+* Persist virtualizer scroll under a key in `history.state` (Navigation API).
+* Pass the returned `[scrollState, setScrollState]` into `useQueryVirtualizer`.
+* Default key is `"scrollState"`; use distinct keys for multiple lists.
+* Requires the Navigation API (Firefox 147+).
+*/
+declare function useRestoreScrollState<TStartRow>(key?: string): [ScrollHistoryState$1<TStartRow> | null, (state: ScrollHistoryState$1<TStartRow> | null) => void];
+//#endregion
+export { type AnchoringMode, type GetPageQuery, type GetPageQueryOptions, type GetSingleQuery, type GetSingleQueryOptions, type PinToBottomOptions, type QueryResult, type QueryVirtualizerResult, type RowKey, type ScrollHistoryState, type UseQueryVirtualizerOptions, type ViewStatus, type VirtualRow, rowAttributes, usePinToBottom, useQueryVirtualizer, useQueryWindowVirtualizer, useRestoreScrollState };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/use-query-virtualizer.ts","../src/use-pin-to-bottom.ts","../src/use-restore-scroll-state.ts"],"mappings":";;;;;;;AAiBA;;KAAY,WAAA,aACE,MAAA,oBAA0B,MAAA;EAAA,SAG7B,KAAA,EAAO,UAAA,CAAW,GAAA,EAAK,GAAA;EAAA,SACvB,OAAA,GAAU,eAAA;AAAA;;;;;KAOT,YAAA,cAA0B,MAAA,iCACpC,OAAA,EAAS,mBAAA,CAAoB,SAAA,MAC1B,WAAA,CAAY,IAAA;;;;;KAML,cAAA,cAA4B,MAAA,sBACtC,OAAA,EAAS,qBAAA,KACN,WAAA,CAAY,IAAA;AAjBI;AAOrB;;;;AAPqB,KAwBT,0BAAA,kCAEG,MAAA,gCAEX,yBAAA,CACF,kBAAA,EACA,IAAA,EACA,SAAA,EACA,UAAA,CAAW,IAAA,UACX,eAAA,EACA,UAAA,CAAW,IAAA,SACX,eAAA;EAEA,YAAA,EAAc,YAAA,CAAa,IAAA,EAAM,SAAA;EACjC,cAAA,EAAgB,cAAA,CAAe,IAAA;AAAA;;;;;;KAQrB,sBAAA,SAA+B,IAAA,CACzC,iBAAA,CAAsB,IAAA;EAAA,SAGb,MAAA,EAAQ,YAAA;AAAA;;;;;;AAvDnB;;;;;;;;;;;;;;;;iBC8GgB,mBAAA,kCAED,MAAA,8BAGb,OAAA,EAAS,0BAAA,CAA2B,kBAAA,EAAoB,IAAA,EAAM,SAAA,IAC7D,sBAAA,CAAuB,IAAA;;AD/GL;AAOrB;;iBCwHgB,yBAAA,kCAED,MAAA,8BAGb,OAAA,EAAS,0BAAA,CAA2B,kBAAA,EAAoB,IAAA,EAAM,SAAA,IAC7D,sBAAA,CAAuB,IAAA;;;;KChJd,kBAAA,GAAqB,YAAA;;AFMjC;;;;iBECgB,cAAA,OACd,WAAA,EAAa,sBAAA,CAAuB,IAAA;EAClC,OAAA;EAAgB;AAAA,IAA+B,kBAAA;;;;;;;AFHnD;;iBGiBgB,qBAAA,YACd,GAAA,aAEA,oBAAA,CAAmB,SAAA,WAClB,KAAA,EAAO,oBAAA,CAAmB,SAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+import{DEFAULT_STICK_SLACK as e,ZeroVirtualizer as t,assembleRows as n,buildAfterQuery as r,buildMainQuery as i,buildSingleQuery as a,createStickToBottomCache as o,getHistoryStateServerSnapshot as s,getHistoryStateSnapshot as c,observeElementOffset as l,observeElementRect as u,observeWindowOffset as d,observeWindowRect as f,permalinkMissing as p,resolveElementScrollElement as m,resolveWindowScrollElement as h,rowAttributes as g,subscribeHistoryState as _,updateHistoryState as v,virtualizerResult as y}from"@rocicorp/zero-virtual/core";import{useCallback as b,useLayoutEffect as x,useMemo as S,useReducer as C,useRef as w,useState as T,useSyncExternalStore as E}from"react";import{useQuery as D}from"@doync/react";const O=Object.freeze({status:`unknown`});function k(e,t){for(let t of e)if(t.status===`error`)return t;return t?{status:`complete`}:O}function A(e){return e!==null&&e.options?.skip!==!0}function j({pageSize:e,anchor:t,settled:o,getPageQuery:s,getSingleQuery:c,toStartRow:l},u=D){let d={pageSize:e,anchor:t,settled:o},f=a(d,c),[m,h]=u(f?.query??!1,f?.options),g=m??void 0,_=h.status===`complete`,v=p(d,g,_),y=g?l(g):null,b=A(f),x=i(d,s,y,v),[C,w]=u(x?.query??!1,x?.options),T=w.status===`complete`,E=A(x),O=r(d,s,y,v),[j,M]=u(O?.query??!1,O?.options),N=M.status===`complete`,P=A(O);return S(()=>{let r=n({pageSize:e,anchor:t,settled:o},{singleRow:g,singleComplete:_,mainRows:C,mainComplete:T,afterRows:j,afterComplete:N}),i=[];return b&&i.push(h),E&&i.push(w),P&&i.push(M),{rows:r,status:k(i,r.complete)}},[e,t,o,g,_,h,b,C,T,w,E,j,N,M,P])}function M(e,n){let[,r]=C(()=>({}),{}),[i]=T(()=>new t(e,n));i.setOptions(e);let{pageSize:a,anchor:o,settled:s}=i.getQueryInputs(),{rows:c,status:l}=j({pageSize:a,anchor:o,settled:s,getPageQuery:e.getPageQuery,getSingleQuery:e.getSingleQuery,toStartRow:e.toStartRow});i.setRows(c),x(()=>{let e=i.subscribe(r);return()=>{e(),i.detach()}},[i]),x(()=>{i.attach(e.getScrollElement()),i.afterDOMUpdate()});let{getScrollElement:u,observeElementRect:d,observeElementOffset:f}=e,p=S(()=>({getScrollElement:u,observeElementRect:d,observeElementOffset:f}),[u,d,f]),m=i.getSnapshot(),h=l;return S(()=>{let{complete:e,...t}=y(m,p,n);return{...t,status:h}},[m,p,n,h])}function N(e){return M({...e,observeElementRect:e.observeElementRect??u,observeElementOffset:e.observeElementOffset??l},m)}function P(e){return M({...e,observeElementRect:e.observeElementRect??f,observeElementOffset:e.observeElementOffset??d},h)}function F(t,{enabled:n=!0,slack:r=e}={}){let i=w(null);x(()=>{if(!n){i.current?.detach();return}(i.current??=o()).ensure(t,r)}),x(()=>()=>{i.current?.detach(),i.current=null},[])}function I(){return[E(_,c,s),v]}function L(e=`scrollState`){let[t,n]=I();return[S(()=>t?t[e]??null:null,[t&&JSON.stringify(t[e]),e]),b(t=>{let r=c();n({...r,[e]:t})},[n,e])]}export{g as rowAttributes,F as usePinToBottom,N as useQueryVirtualizer,P as useQueryWindowVirtualizer,L as useRestoreScrollState};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["useQueryDefault","useQuery"],"sources":["../src/use-rows.ts","../src/use-query-virtualizer.ts","../src/use-pin-to-bottom.ts","../src/use-restore-scroll-state.ts"],"sourcesContent":["import type { BoundQuery } from '@doync/core'\n\nimport {\n  useQuery as useQueryDefault,\n  type FalsyQuery,\n  type UseQueryOptions,\n  type ViewStatus,\n} from '@doync/react'\nimport {\n  assembleRows,\n  buildAfterQuery,\n  buildMainQuery,\n  buildSingleQuery,\n  permalinkMissing,\n  type Anchor,\n  type RowsSnapshot,\n} from '@rocicorp/zero-virtual/core'\nimport { useMemo } from 'react'\n\nimport type { GetPageQuery, GetSingleQuery, QueryResult } from './types'\n\n/**\n * Stage payload from core's `build*Query` helpers under doync's `{ query:\n * BoundQuery, options? }` factory contract (closeio/doync#199 / ADR-0027). Core\n * returns `null` for inactive stages; live stages carry a Bound query whose\n * args already ride inside the value.\n */\ntype Stage<\n  TRow extends Record<string, unknown>,\n  One extends boolean,\n> = QueryResult<TRow, One>\n\nconst UNKNOWN: ViewStatus = Object.freeze({ status: 'unknown' })\n\n/**\n * Aggregate live-stage ViewStatuses into the public virtualizer `status`\n * (closeio/doync#178 §F): first live error wins; assembled complete ⇒ complete;\n * else unknown. Skipped stages (core-null / falsy, or consumer `skip: true`)\n * never contribute.\n */\nexport function aggregateStatus(\n  liveStatuses: readonly ViewStatus[],\n  assembledComplete: boolean,\n): ViewStatus {\n  for (const s of liveStatuses) {\n    if (s.status === 'error') return s\n  }\n  if (assembledComplete) return { status: 'complete' }\n  return UNKNOWN\n}\n\n/**\n * Injectable `useQuery` seam (closeio/doync#180 / #199): bound form only —\n * `useQuery(bound | falsy, options?)`. Adapter-first unit tests inject a fake\n * of this shape; the real hook assigns via a bound-form cast (its first public\n * overload rejects falsy).\n */\nexport type UseQueryLike = <\n  Row extends Record<string, unknown> = Record<string, unknown>,\n>(\n  query: BoundQuery<Row, boolean> | FalsyQuery,\n  options?: UseQueryOptions,\n) => [readonly Row[] | Row | undefined, ViewStatus]\n\n/** Core-null or consumer-`skip: true` stages contribute nothing to ViewStatus. */\nfunction isLiveStage(\n  stage: Stage<Record<string, unknown>, boolean> | null,\n): boolean {\n  return stage !== null && stage.options?.skip !== true\n}\n\n/**\n * Internal three-slot adapter: stages Permalink / main / after via core\n * builders, always calls `useQuery` three times (hook-order stable), and passes\n * each stage's Bound query straight through — falsy when the builder returned\n * null (closeio/doync#199 dissolves the placeholder-under-skip workaround from\n * #180). Assembles a `RowsSnapshot` plus public `ViewStatus`.\n *\n * Not package-root-exported. Injectable `useQuery` for adapter-first unit\n * tests.\n */\nexport function useRows<TRow extends Record<string, unknown>, TStartRow>(\n  {\n    pageSize,\n    anchor,\n    settled,\n    getPageQuery,\n    getSingleQuery,\n    toStartRow,\n  }: {\n    pageSize: number\n    anchor: Anchor<TStartRow>\n    settled: boolean\n    getPageQuery: GetPageQuery<TRow, TStartRow>\n    getSingleQuery: GetSingleQuery<TRow>\n    toStartRow: (row: TRow) => TStartRow\n  },\n  // Bound-form cast: real useQuery's non-falsy first overload is not assignable\n  // to the maybe-path UseQueryLike; both sides ARE BoundQuery | falsy (#199).\n  useQuery: UseQueryLike = useQueryDefault as UseQueryLike,\n): { rows: RowsSnapshot<TRow>; status: ViewStatus } {\n  const inputs = { pageSize, anchor, settled }\n\n  // Stage 1: single-item lookup (permalink only). Null stage ⇒ falsy.\n  const stage1 = buildSingleQuery(inputs, getSingleQuery as never) as Stage<\n    TRow,\n    true\n  > | null\n  const [singleRaw, singleStatus] = useQuery(\n    stage1?.query ?? false,\n    stage1?.options,\n  )\n  const typedSingleRow = (singleRaw as TRow | undefined) ?? undefined\n  const singleComplete = singleStatus.status === 'complete'\n  const notFound = permalinkMissing(inputs, typedSingleRow, singleComplete)\n  const singleStart = typedSingleRow ? toStartRow(typedSingleRow) : null\n  const live1 = isLiveStage(stage1)\n\n  // Stage 2: page-before (permalink) or main page. Do not coerce\n  // falsy-skipped multi-row `undefined` to `[]` (ADR-0027 a1; assembleRows\n  // accepts it).\n  const stage2 = buildMainQuery(\n    inputs,\n    getPageQuery as never,\n    singleStart,\n    notFound,\n  ) as Stage<TRow, false> | null\n  const [mainRaw, mainStatus] = useQuery(\n    stage2?.query ?? false,\n    stage2?.options,\n  )\n  const mainComplete = mainStatus.status === 'complete'\n  const live2 = isLiveStage(stage2)\n\n  // Stage 3: page-after (permalink only).\n  const stage3 = buildAfterQuery(\n    inputs,\n    getPageQuery as never,\n    singleStart,\n    notFound,\n  ) as Stage<TRow, false> | null\n  const [afterRaw, afterStatus] = useQuery(\n    stage3?.query ?? false,\n    stage3?.options,\n  )\n  const afterComplete = afterStatus.status === 'complete'\n  const live3 = isLiveStage(stage3)\n\n  return useMemo(() => {\n    const rows = assembleRows(\n      { pageSize, anchor, settled },\n      {\n        singleRow: typedSingleRow,\n        singleComplete,\n        mainRows: mainRaw as readonly TRow[] | undefined as TRow[] | undefined,\n        mainComplete,\n        afterRows: afterRaw as readonly TRow[] | undefined as\n          | TRow[]\n          | undefined,\n        afterComplete,\n      },\n    )\n    const liveStatuses: ViewStatus[] = []\n    if (live1) liveStatuses.push(singleStatus)\n    if (live2) liveStatuses.push(mainStatus)\n    if (live3) liveStatuses.push(afterStatus)\n    return {\n      rows,\n      status: aggregateStatus(liveStatuses, rows.complete),\n    }\n  }, [\n    pageSize,\n    anchor,\n    settled,\n    typedSingleRow,\n    singleComplete,\n    singleStatus,\n    live1,\n    mainRaw,\n    mainComplete,\n    mainStatus,\n    live2,\n    afterRaw,\n    afterComplete,\n    afterStatus,\n    live3,\n  ])\n}\n","import type { ViewStatus } from '@doync/react'\n\nimport {\n  observeElementOffset,\n  observeElementRect,\n  observeWindowOffset,\n  observeWindowRect,\n  resolveElementScrollElement,\n  resolveWindowScrollElement,\n  virtualizerResult,\n  ZeroVirtualizer,\n  type ResolvedScrollOptions,\n  type ResolveScrollElement,\n} from '@rocicorp/zero-virtual/core'\nimport { useLayoutEffect, useMemo, useReducer, useState } from 'react'\n\nimport type {\n  QueryVirtualizerResult,\n  UseQueryVirtualizerOptions,\n} from './types'\n\nimport { useRows } from './use-rows'\n\n/**\n * Thin React binding over framework-agnostic `ZeroVirtualizer`\n * (closeio/doync#180): options and rows push silently every render; DOM work\n * runs from layout effects; re-renders come from the core's subscribe.\n *\n * Public result replaces core's `complete` boolean with aggregated `status:\n * ViewStatus` from live stages.\n */\nfunction useQueryVirtualizerImpl<\n  TListContextParams,\n  TRow extends Record<string, unknown>,\n  TStartRow,\n>(\n  options: UseQueryVirtualizerOptions<TListContextParams, TRow, TStartRow> &\n    ResolvedScrollOptions,\n  resolveScrollElement: ResolveScrollElement,\n): QueryVirtualizerResult<TRow> {\n  const [, rerender] = useReducer(() => ({}), {})\n  // One core instance per hook lifetime. Constructor is pure (no DOM /\n  // listeners / timers), so Strict Mode double-construction is harmless —\n  // and initializing paging from persisted scroll state here avoids Strict\n  // Mode double-mounting the rows.\n  const [core] = useState(\n    () =>\n      new ZeroVirtualizer<TListContextParams, TRow, TStartRow>(\n        options,\n        resolveScrollElement,\n      ),\n  )\n\n  // Silent staging — never notifies during render.\n  core.setOptions(options)\n  const { pageSize, anchor, settled } = core.getQueryInputs()\n  const { rows, status } = useRows<TRow, TStartRow>({\n    pageSize,\n    anchor,\n    settled,\n    getPageQuery: options.getPageQuery,\n    getSingleQuery: options.getSingleQuery,\n    toStartRow: options.toStartRow,\n  })\n  core.setRows(rows)\n\n  // Mount/unmount: re-render subscription + listener teardown. Idempotent\n  // across Strict Mode mount→unmount→mount (state survives detach; the\n  // per-commit effect below re-attaches).\n  useLayoutEffect(() => {\n    const unsubscribe = core.subscribe(rerender)\n    return () => {\n      unsubscribe()\n      core.detach()\n    }\n  }, [core])\n\n  // Every commit, before paint: (re)wire the scroll element and run the\n  // core's post-DOM-update pass (anchoring, restore/permalink, paging,\n  // persistence).\n  useLayoutEffect(() => {\n    core.attach(options.getScrollElement())\n    core.afterDOMUpdate()\n  })\n\n  const { getScrollElement, observeElementRect, observeElementOffset } = options\n  const resultOptions = useMemo(\n    () => ({ getScrollElement, observeElementRect, observeElementOffset }),\n    [getScrollElement, observeElementRect, observeElementOffset],\n  )\n  const snapshot = core.getSnapshot()\n  const statusRef = status\n  return useMemo(() => {\n    const base = virtualizerResult(\n      snapshot,\n      resultOptions,\n      resolveScrollElement,\n    )\n    // Drop core's complete boolean; surface ViewStatus for consumers.\n    const { complete: _complete, ...rest } = base\n    void _complete\n    return {\n      ...rest,\n      status: statusRef,\n    }\n  }, [snapshot, resultOptions, resolveScrollElement, statusRef])\n}\n\n/**\n * Virtualized infinite list inside an overflow element. `getScrollElement`\n * returns that element (also where rows render). Provide page/single query\n * factories via {@link UseQueryVirtualizerOptions}.\n *\n * ```ts\n * const v = useQueryVirtualizer({\n *   getScrollElement: () => listRef.current,\n *   estimateSize: () => 48,\n *   getPageQuery: ({ limit, start, dir }) => ({\n *     query: queries.items.page({ limit, start, dir }),\n *   }),\n *   getSingleQuery: ({ id }) => ({\n *     query: queries.items.byId({ id }),\n *   }),\n *   // …\n * })\n * ```\n */\nexport function useQueryVirtualizer<\n  TListContextParams,\n  TRow extends Record<string, unknown>,\n  TStartRow,\n>(\n  options: UseQueryVirtualizerOptions<TListContextParams, TRow, TStartRow>,\n): QueryVirtualizerResult<TRow> {\n  return useQueryVirtualizerImpl(\n    {\n      ...options,\n      observeElementRect: options.observeElementRect ?? observeElementRect,\n      observeElementOffset:\n        options.observeElementOffset ?? observeElementOffset,\n    },\n    resolveElementScrollElement,\n  )\n}\n\n/**\n * Like {@link useQueryVirtualizer}, but the window is the scroll container.\n * `getScrollElement` returns the element rows render into (normal page flow).\n */\nexport function useQueryWindowVirtualizer<\n  TListContextParams,\n  TRow extends Record<string, unknown>,\n  TStartRow,\n>(\n  options: UseQueryVirtualizerOptions<TListContextParams, TRow, TStartRow>,\n): QueryVirtualizerResult<TRow> {\n  return useQueryVirtualizerImpl(\n    {\n      ...options,\n      observeElementRect: options.observeElementRect ?? observeWindowRect,\n      observeElementOffset: options.observeElementOffset ?? observeWindowOffset,\n    },\n    resolveWindowScrollElement,\n  )\n}\n\n// Re-export for helper modules that type-check against the public result.\nexport type { QueryVirtualizerResult, ViewStatus }\n","import {\n  createStickToBottomCache,\n  DEFAULT_STICK_SLACK,\n  type StickOptions,\n  type StickToBottomCache,\n} from '@rocicorp/zero-virtual/core'\nimport { useLayoutEffect, useRef } from 'react'\n\nimport type { QueryVirtualizerResult } from './types'\n\n/** Options for {@link usePinToBottom}: `enabled` and bottom-edge `slack`. */\nexport type PinToBottomOptions = StickOptions\n\n/**\n * Keep a chat/log list pinned to the bottom when content grows — only while the\n * user is already at the bottom. Pass the result of `useQueryVirtualizer` /\n * `useQueryWindowVirtualizer`.\n */\nexport function usePinToBottom<TRow>(\n  virtualizer: QueryVirtualizerResult<TRow>,\n  { enabled = true, slack = DEFAULT_STICK_SLACK }: PinToBottomOptions = {},\n): void {\n  const ref = useRef<StickToBottomCache | null>(null)\n\n  // Runs per commit, pre-paint, with no deps on purpose: when the scroll\n  // container renders conditionally (or before the first rows) elements can be\n  // null and nothing else would re-run — ensure() retries each tick until they\n  // exist, and is an identity-check no-op after that.\n  useLayoutEffect(() => {\n    if (!enabled) {\n      ref.current?.detach()\n      return\n    }\n    ;(ref.current ??= createStickToBottomCache()).ensure(virtualizer, slack)\n  })\n\n  useLayoutEffect(\n    () => () => {\n      ref.current?.detach()\n      ref.current = null\n    },\n    [],\n  )\n}\n","import {\n  getHistoryStateServerSnapshot,\n  getHistoryStateSnapshot,\n  subscribeHistoryState,\n  updateHistoryState,\n  type ScrollHistoryState,\n} from '@rocicorp/zero-virtual/core'\nimport { useCallback, useMemo, useSyncExternalStore } from 'react'\n\nconst DEFAULT_KEY = 'scrollState'\n\n/**\n * Navigation API current-entry state as a React external store. Shell over pure\n * core history-state helpers — not a re-export of upstream `/react`\n * `useHistoryState` (closeio/doync#180).\n */\nfunction useNavigationHistoryState(): [\n  state: unknown,\n  setState: (state: unknown) => void,\n] {\n  const state = useSyncExternalStore(\n    subscribeHistoryState,\n    getHistoryStateSnapshot,\n    getHistoryStateServerSnapshot,\n  )\n  return [state, updateHistoryState]\n}\n\n/**\n * Persist virtualizer scroll under a key in `history.state` (Navigation API).\n * Pass the returned `[scrollState, setScrollState]` into `useQueryVirtualizer`.\n * Default key is `\"scrollState\"`; use distinct keys for multiple lists.\n * Requires the Navigation API (Firefox 147+).\n */\nexport function useRestoreScrollState<TStartRow>(\n  key: string = DEFAULT_KEY,\n): [\n  ScrollHistoryState<TStartRow> | null,\n  (state: ScrollHistoryState<TStartRow> | null) => void,\n] {\n  const [state, setState] = useNavigationHistoryState()\n\n  // Memoize by serialized content so identity is stable when the nested key\n  // is unchanged — core compares scrollState by reference on restore.\n  const scrollState: ScrollHistoryState<TStartRow> | null = useMemo(() => {\n    if (!state) return null\n    return ((state as Record<string, unknown>)[key] ??\n      null) as ScrollHistoryState<TStartRow> | null\n    // eslint-disable-next-line react-hooks/exhaustive-deps -- content identity\n  }, [state && JSON.stringify((state as Record<string, unknown>)[key]), key])\n\n  const setScrollState = useCallback(\n    (newState: ScrollHistoryState<TStartRow> | null) => {\n      // Re-read the live history state instead of spreading the render-time\n      // snapshot: the virtualizer calls this from a ~100ms persist debounce,\n      // so another virtualizer (under a different key) or the app itself may\n      // have written a sibling key since this closure was created — spreading\n      // the stale snapshot would silently erase that write.\n      const current = getHistoryStateSnapshot()\n      setState({\n        ...(current as Record<string, unknown>),\n        [key]: newState,\n      })\n    },\n    [setState, key],\n  )\n\n  return [scrollState, setScrollState]\n}\n"],"mappings":"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"}

package/dist/internal.d.cts

@@ -0,0 +1 @@
+export { };

package/dist/internal.d.ts

@@ -0,0 +1 @@
+export { };

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@doync/query-virtualizer",
+  "version": "0.1.0",
+  "description": "doync React binding: virtualized infinite lists over Subscriptions via @rocicorp/zero-virtual/core",
+  "keywords": [
+    "doync",
+    "infinite-scroll",
+    "react",
+    "sync-engine",
+    "virtualization"
+  ],
+  "license": "MIT",
+  "author": "Vitor Buzinaro",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/closeio/doync.git",
+    "directory": "packages/query-virtualizer"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./internal": {
+      "import": {
+        "types": "./dist/internal.d.ts",
+        "default": "./dist/internal.js"
+      },
+      "require": {
+        "types": "./dist/internal.d.cts",
+        "default": "./dist/internal.cjs"
+      }
+    }
+  },
+  "dependencies": {
+    "@rocicorp/zero-virtual": "0.6.3",
+    "@doync/core": "0.1.0",
+    "@doync/react": "0.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^24.13.2",
+    "@types/react": "^19.0.0",
+    "jsdom": "^25.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsdown": "^0.22.3",
+    "typescript": "^7.0.2",
+    "vitest": "4.1.9"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+/**
+ * `@doync/query-virtualizer` (closeio/doync#178 / #180 / #199): thin doync
+ * React binding over `@rocicorp/zero-virtual` **`/core` only**. Consumers get
+ * virtualized infinite lists over doync Subscriptions without declaring or
+ * importing zero-virtual themselves. Stage factories return a Bound query
+ * (ADR-0027); core-null stages pass falsy into the three unconditional
+ * `useQuery` slots — no placeholders.
+ *
+ * Deeper / experimental core symbols remain on `@rocicorp/zero-virtual/core`
+ * and may break across experimental-core pin bumps — this package's root export
+ * is the stable surface.
+ */
+
+export {
+  useQueryVirtualizer,
+  useQueryWindowVirtualizer,
+} from './use-query-virtualizer'
+
+export { usePinToBottom, type PinToBottomOptions } from './use-pin-to-bottom'
+
+export { useRestoreScrollState } from './use-restore-scroll-state'
+
+export type {
+  GetPageQuery,
+  GetPageQueryOptions,
+  GetSingleQuery,
+  GetSingleQueryOptions,
+  QueryResult,
+  QueryVirtualizerResult,
+  UseQueryVirtualizerOptions,
+} from './types'
+
+// Core re-exports matching PRD §G
+export {
+  rowAttributes,
+  type AnchoringMode,
+  type RowKey,
+  type ScrollHistoryState,
+  type VirtualRow,
+} from '@rocicorp/zero-virtual/core'
+
+export type { ViewStatus } from '@doync/react'

package/src/internal.ts

@@ -0,0 +1,8 @@
+/**
+ * `@doync/query-virtualizer/internal` (ADR-0033): placeholder entry — the
+ * current public surface stands. Kept so the nine-package `./internal` contract
+ * is uniform. May break in any release. Import virtualizer hooks from
+ * `@doync/query-virtualizer`.
+ */
+
+export {}

package/src/types.ts

@@ -0,0 +1,84 @@
+import type { BoundQuery } from '@doync/core'
+import type { UseQueryOptions, ViewStatus } from '@doync/react'
+import type {
+  AnchoringMode,
+  GetPageQueryOptions,
+  GetSingleQueryOptions,
+  RowKey,
+  ScrollHistoryState,
+  VirtualRow,
+  VirtualizerBindingOptions as CoreVirtualizerBindingOptions,
+  VirtualizerResult as CoreVirtualizerResult,
+} from '@rocicorp/zero-virtual/core'
+
+/**
+ * What a page/single factory returns: a bound query plus optional `useQuery`
+ * options (`ttl`, `skip`). Args live on the bound value.
+ */
+export type QueryResult<
+  Row extends Record<string, unknown> = Record<string, unknown>,
+  One extends boolean = boolean,
+> = {
+  readonly query: BoundQuery<Row, One>
+  readonly options?: UseQueryOptions | undefined
+}
+
+/**
+ * Page-query factory: given `{ limit, start, dir, settled }`, return a
+ * multi-row bound query.
+ */
+export type GetPageQuery<TRow extends Record<string, unknown>, TStartRow> = (
+  options: GetPageQueryOptions<TStartRow>,
+) => QueryResult<TRow, false>
+
+/**
+ * Single-row factory: given `{ id, settled }`, return a one-row bound query (``
+ * sql.one`…` `` / `findFirst`).
+ */
+export type GetSingleQuery<TRow extends Record<string, unknown>> = (
+  options: GetSingleQueryOptions,
+) => QueryResult<TRow, true>
+
+/**
+ * Options for {@link useQueryVirtualizer} / {@link useQueryWindowVirtualizer}.
+ * Provide `getPageQuery` and `getSingleQuery` factories that return bound
+ * queries.
+ */
+export type UseQueryVirtualizerOptions<
+  TListContextParams,
+  TRow extends Record<string, unknown>,
+  TStartRow,
+> = CoreVirtualizerBindingOptions<
+  TListContextParams,
+  TRow,
+  TStartRow,
+  BoundQuery<TRow, false>,
+  UseQueryOptions,
+  BoundQuery<TRow, true>,
+  UseQueryOptions
+> & {
+  getPageQuery: GetPageQuery<TRow, TStartRow>
+  getSingleQuery: GetSingleQuery<TRow>
+}
+
+/**
+ * Virtualizer result: virtual items, scroll helpers, and aggregated
+ * {@link ViewStatus} from the live page stages (replaces core's `complete`
+ * boolean).
+ */
+export type QueryVirtualizerResult<TRow> = Omit<
+  CoreVirtualizerResult<TRow>,
+  'complete'
+> & {
+  readonly status: ViewStatus
+}
+
+export type {
+  AnchoringMode,
+  GetPageQueryOptions,
+  GetSingleQueryOptions,
+  RowKey,
+  ScrollHistoryState,
+  VirtualRow,
+  ViewStatus,
+}

package/src/use-pin-to-bottom.ts

@@ -0,0 +1,44 @@
+import {
+  createStickToBottomCache,
+  DEFAULT_STICK_SLACK,
+  type StickOptions,
+  type StickToBottomCache,
+} from '@rocicorp/zero-virtual/core'
+import { useLayoutEffect, useRef } from 'react'
+
+import type { QueryVirtualizerResult } from './types'
+
+/** Options for {@link usePinToBottom}: `enabled` and bottom-edge `slack`. */
+export type PinToBottomOptions = StickOptions
+
+/**
+ * Keep a chat/log list pinned to the bottom when content grows — only while the
+ * user is already at the bottom. Pass the result of `useQueryVirtualizer` /
+ * `useQueryWindowVirtualizer`.
+ */
+export function usePinToBottom<TRow>(
+  virtualizer: QueryVirtualizerResult<TRow>,
+  { enabled = true, slack = DEFAULT_STICK_SLACK }: PinToBottomOptions = {},
+): void {
+  const ref = useRef<StickToBottomCache | null>(null)
+
+  // Runs per commit, pre-paint, with no deps on purpose: when the scroll
+  // container renders conditionally (or before the first rows) elements can be
+  // null and nothing else would re-run — ensure() retries each tick until they
+  // exist, and is an identity-check no-op after that.
+  useLayoutEffect(() => {
+    if (!enabled) {
+      ref.current?.detach()
+      return
+    }
+    ;(ref.current ??= createStickToBottomCache()).ensure(virtualizer, slack)
+  })
+
+  useLayoutEffect(
+    () => () => {
+      ref.current?.detach()
+      ref.current = null
+    },
+    [],
+  )
+}

package/src/use-query-virtualizer.ts

@@ -0,0 +1,168 @@
+import type { ViewStatus } from '@doync/react'
+
+import {
+  observeElementOffset,
+  observeElementRect,
+  observeWindowOffset,
+  observeWindowRect,
+  resolveElementScrollElement,
+  resolveWindowScrollElement,
+  virtualizerResult,
+  ZeroVirtualizer,
+  type ResolvedScrollOptions,
+  type ResolveScrollElement,
+} from '@rocicorp/zero-virtual/core'
+import { useLayoutEffect, useMemo, useReducer, useState } from 'react'
+
+import type {
+  QueryVirtualizerResult,
+  UseQueryVirtualizerOptions,
+} from './types'
+
+import { useRows } from './use-rows'
+
+/**
+ * Thin React binding over framework-agnostic `ZeroVirtualizer`
+ * (closeio/doync#180): options and rows push silently every render; DOM work
+ * runs from layout effects; re-renders come from the core's subscribe.
+ *
+ * Public result replaces core's `complete` boolean with aggregated `status:
+ * ViewStatus` from live stages.
+ */
+function useQueryVirtualizerImpl<
+  TListContextParams,
+  TRow extends Record<string, unknown>,
+  TStartRow,
+>(
+  options: UseQueryVirtualizerOptions<TListContextParams, TRow, TStartRow> &
+    ResolvedScrollOptions,
+  resolveScrollElement: ResolveScrollElement,
+): QueryVirtualizerResult<TRow> {
+  const [, rerender] = useReducer(() => ({}), {})
+  // One core instance per hook lifetime. Constructor is pure (no DOM /
+  // listeners / timers), so Strict Mode double-construction is harmless —
+  // and initializing paging from persisted scroll state here avoids Strict
+  // Mode double-mounting the rows.
+  const [core] = useState(
+    () =>
+      new ZeroVirtualizer<TListContextParams, TRow, TStartRow>(
+        options,
+        resolveScrollElement,
+      ),
+  )
+
+  // Silent staging — never notifies during render.
+  core.setOptions(options)
+  const { pageSize, anchor, settled } = core.getQueryInputs()
+  const { rows, status } = useRows<TRow, TStartRow>({
+    pageSize,
+    anchor,
+    settled,
+    getPageQuery: options.getPageQuery,
+    getSingleQuery: options.getSingleQuery,
+    toStartRow: options.toStartRow,
+  })
+  core.setRows(rows)
+
+  // Mount/unmount: re-render subscription + listener teardown. Idempotent
+  // across Strict Mode mount→unmount→mount (state survives detach; the
+  // per-commit effect below re-attaches).
+  useLayoutEffect(() => {
+    const unsubscribe = core.subscribe(rerender)
+    return () => {
+      unsubscribe()
+      core.detach()
+    }
+  }, [core])
+
+  // Every commit, before paint: (re)wire the scroll element and run the
+  // core's post-DOM-update pass (anchoring, restore/permalink, paging,
+  // persistence).
+  useLayoutEffect(() => {
+    core.attach(options.getScrollElement())
+    core.afterDOMUpdate()
+  })
+
+  const { getScrollElement, observeElementRect, observeElementOffset } = options
+  const resultOptions = useMemo(
+    () => ({ getScrollElement, observeElementRect, observeElementOffset }),
+    [getScrollElement, observeElementRect, observeElementOffset],
+  )
+  const snapshot = core.getSnapshot()
+  const statusRef = status
+  return useMemo(() => {
+    const base = virtualizerResult(
+      snapshot,
+      resultOptions,
+      resolveScrollElement,
+    )
+    // Drop core's complete boolean; surface ViewStatus for consumers.
+    const { complete: _complete, ...rest } = base
+    void _complete
+    return {
+      ...rest,
+      status: statusRef,
+    }
+  }, [snapshot, resultOptions, resolveScrollElement, statusRef])
+}
+
+/**
+ * Virtualized infinite list inside an overflow element. `getScrollElement`
+ * returns that element (also where rows render). Provide page/single query
+ * factories via {@link UseQueryVirtualizerOptions}.
+ *
+ * ```ts
+ * const v = useQueryVirtualizer({
+ *   getScrollElement: () => listRef.current,
+ *   estimateSize: () => 48,
+ *   getPageQuery: ({ limit, start, dir }) => ({
+ *     query: queries.items.page({ limit, start, dir }),
+ *   }),
+ *   getSingleQuery: ({ id }) => ({
+ *     query: queries.items.byId({ id }),
+ *   }),
+ *   // …
+ * })
+ * ```
+ */
+export function useQueryVirtualizer<
+  TListContextParams,
+  TRow extends Record<string, unknown>,
+  TStartRow,
+>(
+  options: UseQueryVirtualizerOptions<TListContextParams, TRow, TStartRow>,
+): QueryVirtualizerResult<TRow> {
+  return useQueryVirtualizerImpl(
+    {
+      ...options,
+      observeElementRect: options.observeElementRect ?? observeElementRect,
+      observeElementOffset:
+        options.observeElementOffset ?? observeElementOffset,
+    },
+    resolveElementScrollElement,
+  )
+}
+
+/**
+ * Like {@link useQueryVirtualizer}, but the window is the scroll container.
+ * `getScrollElement` returns the element rows render into (normal page flow).
+ */
+export function useQueryWindowVirtualizer<
+  TListContextParams,
+  TRow extends Record<string, unknown>,
+  TStartRow,
+>(
+  options: UseQueryVirtualizerOptions<TListContextParams, TRow, TStartRow>,
+): QueryVirtualizerResult<TRow> {
+  return useQueryVirtualizerImpl(
+    {
+      ...options,
+      observeElementRect: options.observeElementRect ?? observeWindowRect,
+      observeElementOffset: options.observeElementOffset ?? observeWindowOffset,
+    },
+    resolveWindowScrollElement,
+  )
+}
+
+// Re-export for helper modules that type-check against the public result.
+export type { QueryVirtualizerResult, ViewStatus }

package/src/use-restore-scroll-state.ts

@@ -0,0 +1,69 @@
+import {
+  getHistoryStateServerSnapshot,
+  getHistoryStateSnapshot,
+  subscribeHistoryState,
+  updateHistoryState,
+  type ScrollHistoryState,
+} from '@rocicorp/zero-virtual/core'
+import { useCallback, useMemo, useSyncExternalStore } from 'react'
+
+const DEFAULT_KEY = 'scrollState'
+
+/**
+ * Navigation API current-entry state as a React external store. Shell over pure
+ * core history-state helpers — not a re-export of upstream `/react`
+ * `useHistoryState` (closeio/doync#180).
+ */
+function useNavigationHistoryState(): [
+  state: unknown,
+  setState: (state: unknown) => void,
+] {
+  const state = useSyncExternalStore(
+    subscribeHistoryState,
+    getHistoryStateSnapshot,
+    getHistoryStateServerSnapshot,
+  )
+  return [state, updateHistoryState]
+}
+
+/**
+ * Persist virtualizer scroll under a key in `history.state` (Navigation API).
+ * Pass the returned `[scrollState, setScrollState]` into `useQueryVirtualizer`.
+ * Default key is `"scrollState"`; use distinct keys for multiple lists.
+ * Requires the Navigation API (Firefox 147+).
+ */
+export function useRestoreScrollState<TStartRow>(
+  key: string = DEFAULT_KEY,
+): [
+  ScrollHistoryState<TStartRow> | null,
+  (state: ScrollHistoryState<TStartRow> | null) => void,
+] {
+  const [state, setState] = useNavigationHistoryState()
+
+  // Memoize by serialized content so identity is stable when the nested key
+  // is unchanged — core compares scrollState by reference on restore.
+  const scrollState: ScrollHistoryState<TStartRow> | null = useMemo(() => {
+    if (!state) return null
+    return ((state as Record<string, unknown>)[key] ??
+      null) as ScrollHistoryState<TStartRow> | null
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- content identity
+  }, [state && JSON.stringify((state as Record<string, unknown>)[key]), key])
+
+  const setScrollState = useCallback(
+    (newState: ScrollHistoryState<TStartRow> | null) => {
+      // Re-read the live history state instead of spreading the render-time
+      // snapshot: the virtualizer calls this from a ~100ms persist debounce,
+      // so another virtualizer (under a different key) or the app itself may
+      // have written a sibling key since this closure was created — spreading
+      // the stale snapshot would silently erase that write.
+      const current = getHistoryStateSnapshot()
+      setState({
+        ...(current as Record<string, unknown>),
+        [key]: newState,
+      })
+    },
+    [setState, key],
+  )
+
+  return [scrollState, setScrollState]
+}

package/src/use-rows.ts

@@ -0,0 +1,188 @@
+import type { BoundQuery } from '@doync/core'
+
+import {
+  useQuery as useQueryDefault,
+  type FalsyQuery,
+  type UseQueryOptions,
+  type ViewStatus,
+} from '@doync/react'
+import {
+  assembleRows,
+  buildAfterQuery,
+  buildMainQuery,
+  buildSingleQuery,
+  permalinkMissing,
+  type Anchor,
+  type RowsSnapshot,
+} from '@rocicorp/zero-virtual/core'
+import { useMemo } from 'react'
+
+import type { GetPageQuery, GetSingleQuery, QueryResult } from './types'
+
+/**
+ * Stage payload from core's `build*Query` helpers under doync's `{ query:
+ * BoundQuery, options? }` factory contract (closeio/doync#199 / ADR-0027). Core
+ * returns `null` for inactive stages; live stages carry a Bound query whose
+ * args already ride inside the value.
+ */
+type Stage<
+  TRow extends Record<string, unknown>,
+  One extends boolean,
+> = QueryResult<TRow, One>
+
+const UNKNOWN: ViewStatus = Object.freeze({ status: 'unknown' })
+
+/**
+ * Aggregate live-stage ViewStatuses into the public virtualizer `status`
+ * (closeio/doync#178 §F): first live error wins; assembled complete ⇒ complete;
+ * else unknown. Skipped stages (core-null / falsy, or consumer `skip: true`)
+ * never contribute.
+ */
+export function aggregateStatus(
+  liveStatuses: readonly ViewStatus[],
+  assembledComplete: boolean,
+): ViewStatus {
+  for (const s of liveStatuses) {
+    if (s.status === 'error') return s
+  }
+  if (assembledComplete) return { status: 'complete' }
+  return UNKNOWN
+}
+
+/**
+ * Injectable `useQuery` seam (closeio/doync#180 / #199): bound form only —
+ * `useQuery(bound | falsy, options?)`. Adapter-first unit tests inject a fake
+ * of this shape; the real hook assigns via a bound-form cast (its first public
+ * overload rejects falsy).
+ */
+export type UseQueryLike = <
+  Row extends Record<string, unknown> = Record<string, unknown>,
+>(
+  query: BoundQuery<Row, boolean> | FalsyQuery,
+  options?: UseQueryOptions,
+) => [readonly Row[] | Row | undefined, ViewStatus]
+
+/** Core-null or consumer-`skip: true` stages contribute nothing to ViewStatus. */
+function isLiveStage(
+  stage: Stage<Record<string, unknown>, boolean> | null,
+): boolean {
+  return stage !== null && stage.options?.skip !== true
+}
+
+/**
+ * Internal three-slot adapter: stages Permalink / main / after via core
+ * builders, always calls `useQuery` three times (hook-order stable), and passes
+ * each stage's Bound query straight through — falsy when the builder returned
+ * null (closeio/doync#199 dissolves the placeholder-under-skip workaround from
+ * #180). Assembles a `RowsSnapshot` plus public `ViewStatus`.
+ *
+ * Not package-root-exported. Injectable `useQuery` for adapter-first unit
+ * tests.
+ */
+export function useRows<TRow extends Record<string, unknown>, TStartRow>(
+  {
+    pageSize,
+    anchor,
+    settled,
+    getPageQuery,
+    getSingleQuery,
+    toStartRow,
+  }: {
+    pageSize: number
+    anchor: Anchor<TStartRow>
+    settled: boolean
+    getPageQuery: GetPageQuery<TRow, TStartRow>
+    getSingleQuery: GetSingleQuery<TRow>
+    toStartRow: (row: TRow) => TStartRow
+  },
+  // Bound-form cast: real useQuery's non-falsy first overload is not assignable
+  // to the maybe-path UseQueryLike; both sides ARE BoundQuery | falsy (#199).
+  useQuery: UseQueryLike = useQueryDefault as UseQueryLike,
+): { rows: RowsSnapshot<TRow>; status: ViewStatus } {
+  const inputs = { pageSize, anchor, settled }
+
+  // Stage 1: single-item lookup (permalink only). Null stage ⇒ falsy.
+  const stage1 = buildSingleQuery(inputs, getSingleQuery as never) as Stage<
+    TRow,
+    true
+  > | null
+  const [singleRaw, singleStatus] = useQuery(
+    stage1?.query ?? false,
+    stage1?.options,
+  )
+  const typedSingleRow = (singleRaw as TRow | undefined) ?? undefined
+  const singleComplete = singleStatus.status === 'complete'
+  const notFound = permalinkMissing(inputs, typedSingleRow, singleComplete)
+  const singleStart = typedSingleRow ? toStartRow(typedSingleRow) : null
+  const live1 = isLiveStage(stage1)
+
+  // Stage 2: page-before (permalink) or main page. Do not coerce
+  // falsy-skipped multi-row `undefined` to `[]` (ADR-0027 a1; assembleRows
+  // accepts it).
+  const stage2 = buildMainQuery(
+    inputs,
+    getPageQuery as never,
+    singleStart,
+    notFound,
+  ) as Stage<TRow, false> | null
+  const [mainRaw, mainStatus] = useQuery(
+    stage2?.query ?? false,
+    stage2?.options,
+  )
+  const mainComplete = mainStatus.status === 'complete'
+  const live2 = isLiveStage(stage2)
+
+  // Stage 3: page-after (permalink only).
+  const stage3 = buildAfterQuery(
+    inputs,
+    getPageQuery as never,
+    singleStart,
+    notFound,
+  ) as Stage<TRow, false> | null
+  const [afterRaw, afterStatus] = useQuery(
+    stage3?.query ?? false,
+    stage3?.options,
+  )
+  const afterComplete = afterStatus.status === 'complete'
+  const live3 = isLiveStage(stage3)
+
+  return useMemo(() => {
+    const rows = assembleRows(
+      { pageSize, anchor, settled },
+      {
+        singleRow: typedSingleRow,
+        singleComplete,
+        mainRows: mainRaw as readonly TRow[] | undefined as TRow[] | undefined,
+        mainComplete,
+        afterRows: afterRaw as readonly TRow[] | undefined as
+          | TRow[]
+          | undefined,
+        afterComplete,
+      },
+    )
+    const liveStatuses: ViewStatus[] = []
+    if (live1) liveStatuses.push(singleStatus)
+    if (live2) liveStatuses.push(mainStatus)
+    if (live3) liveStatuses.push(afterStatus)
+    return {
+      rows,
+      status: aggregateStatus(liveStatuses, rows.complete),
+    }
+  }, [
+    pageSize,
+    anchor,
+    settled,
+    typedSingleRow,
+    singleComplete,
+    singleStatus,
+    live1,
+    mainRaw,
+    mainComplete,
+    mainStatus,
+    live2,
+    afterRaw,
+    afterComplete,
+    afterStatus,
+    live3,
+  ])
+}