@tinvar/react 0.0.0-stage → 0.4.1

package/src/infinite-scroll.js

@@ -0,0 +1,715 @@
+'use client';
+
+// <InfiniteScroll>'s browser half: when to load the next or the previous
+// page of a Scroll, how, and what the address bar says while the reader
+// scrolls through them (ADR 0020).
+//
+// tinvar-spec.md: "`<InfiniteScroll data="users">` over a `scroll()` field:
+// both directions, URL sync of the page param, `reverse` for chat,
+// `manual`/`manualAfter`, works in any scroll container, `reset` on filter
+// change. Each page streams as server components."
+//
+// Built on what is already there. A page is loaded as a background partial
+// reload of the list's segment at the page's URL, with `preserveUrl`: the
+// server runs the page's whole pipeline -- every check and loader -- and
+// renders the segment, the list's items among it, as server components;
+// <MergeSlot> adds them to those shown. Background, so it never cancels the
+// reader's own navigation, a navigation cancels it, and none starts while
+// one is pending. What starts a load automatically is the deferred
+// boundaries' `visible` trigger, on an edge of the list. A filter that
+// changes the list is a visit with `reset` naming it: the same partial
+// reload, marked to replace.
+//
+// Which pages are loaded is state here, read from each response: the page
+// it carried and the pages either side. A partial reload keeps this
+// component, so the range grows; a reset or a whole page starts it again.
+//
+// A CursorScroll's pages have no numbers (ADR 0120). Each is read at a
+// cursor -- the one before it handed out as `next`, or the one after it as
+// `previous` -- so it is placed by that: after the last page shown, before
+// the first, or, read again at its own cursor, where it already is. The
+// page that arrived whole is place 0, and the places count out from it.
+// One read at a cursor no page shown leads to -- a cursor that expired and
+// was answered with the newest page -- cannot be placed among them, and
+// the list starts again from it. <MergeSlot> asks here where each goes.
+
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { onVisible } from './deferred-triggers.js';
+import { useOptionalRouter } from './link.js';
+import { SegmentContext } from './segment.js';
+
+/**
+ * What a Scroll page says about itself, without its items. A cursor page's
+ * `cursor` is the one it was read at, null for the first; its `previous`
+ * and `next` are cursors, and its `page` is 0 until it is placed.
+ *
+ * @typedef {{
+ *   id: string,
+ *   page: number,
+ *   cursor?: string | null,
+ *   previous: number | string | null,
+ *   next: number | string | null,
+ *   total: number | null,
+ *   perPage: number,
+ *   pageName: string,
+ *   reset: boolean,
+ * }} ScrollMeta
+ *
+ * @typedef {{ page: number, previous: number | string | null, next: number | string | null }} Edge
+ *
+ * @typedef {{
+ *   id: string,
+ *   reverse: boolean,
+ *   loading: 'next' | 'previous' | null,
+ *   manual: boolean,
+ *   hasNext: boolean,
+ *   hasPrevious: boolean,
+ *   first: number,
+ *   last: number,
+ *   total: number | null,
+ *   perPage: number,
+ *   loadNext: () => Promise<boolean>,
+ *   loadPrevious: () => Promise<boolean>,
+ *   epoch: number,
+ *   place: (cursor: string | null) => number | undefined,
+ * }} InfiniteScrollState
+ *
+ * `epoch` counts the times the list started again, and `place` says where
+ * a cursor page read at a cursor goes: what <MergeSlot> reads for a page
+ * with no number.
+ */
+
+export const InfiniteScrollContext = createContext(/** @type {InfiniteScrollState | null} */ (null));
+
+/**
+ * The nearest <InfiniteScroll>'s state and its two loads, for a client
+ * component of the app's -- a "Load more" button, a count of what is shown.
+ *
+ * @returns {InfiniteScrollState}
+ */
+export function useInfiniteScroll() {
+  const state = useContext(InfiniteScrollContext);
+  if (state === null) throw new Error('[tinvar] useInfiniteScroll() needs an <InfiniteScroll> above it.');
+  return state;
+}
+
+/** @param {ScrollMeta} meta @param {number} [page] @returns {Edge} */
+const edgeOf = (meta, page = meta.page) => ({ page, previous: meta.previous, next: meta.next });
+
+/** What a cursor page's place is kept under: its cursor, or '' for the first page's none. */
+const placeKey = (/** @type {string | null | undefined} */ cursor) => cursor ?? '';
+
+/**
+ * Where a cursor page goes among those shown: where it already is, read
+ * again at its own cursor; after the last, read at its `next`; before the
+ * first, read at its `previous`. Undefined for one none of them leads to.
+ *
+ * @param {{ first: Edge, last: Edge, places: ReadonlyMap<string, number> }} range
+ * @param {string | null} cursor
+ * @returns {number | undefined}
+ */
+export function placeOf(range, cursor) {
+  const known = range.places.get(placeKey(cursor));
+  if (known !== undefined) return known;
+  if (cursor === null) return undefined;
+  if (cursor === range.last.next) return range.last.page + 1;
+  if (cursor === range.first.previous) return range.first.page - 1;
+  return undefined;
+}
+
+/**
+ * The range after one more page arrives.
+ *
+ * @param {{ first: Edge, last: Edge }} range
+ * @param {Edge} edge
+ * @returns {{ first: Edge, last: Edge }}
+ */
+export function extendRange(range, edge) {
+  return {
+    first: edge.page <= range.first.page ? edge : range.first,
+    last: edge.page >= range.last.page ? edge : range.last,
+  };
+}
+
+/**
+ * The nearest ancestor that scrolls vertically, or null for the document.
+ *
+ * @param {Element | null} element
+ * @returns {Element | null}
+ */
+export function scrollContainerOf(element) {
+  for (let node = element?.parentElement ?? null; node !== null; node = node.parentElement) {
+    if (node === node.ownerDocument.body || node === node.ownerDocument.documentElement) return null;
+    const overflow = node.ownerDocument.defaultView?.getComputedStyle(node).overflowY;
+    if (overflow === 'auto' || overflow === 'scroll' || overflow === 'overlay') return node;
+  }
+  return null;
+}
+
+/**
+ * How many pages either side of the one the reader was at are loaded again
+ * when they come back to it: as many as were loaded, up to this. A reader
+ * who had scrolled through fifty pages is not made to wait for fifty
+ * requests; those further off load as the edges come into view, as ever.
+ */
+export const RESTORE_PAGES = 5;
+
+/** How long the reader is held at the item they were at while what is above it settles, in milliseconds. */
+const SETTLE_MS = 1000;
+
+/** How many times, and how far apart, a page the reader had is asked for before it is given up on. */
+const RESTORE_TRIES = 20;
+const RESTORE_RETRY_MS = 100;
+
+/** Input that means the reader is moving the list, and holding them should stop. */
+const USER_SCROLL_EVENTS = ['wheel', 'touchstart', 'keydown', 'pointerdown'];
+
+/**
+ * @typedef {{ page: number, element: Element, key: string | null, index: number, cursor: string | null }} Item
+ * @typedef {import('./router.js').ScrollAnchor} ScrollAnchor
+ *
+ * An item's `cursor` is its cursor page's, as the address bar names it: null
+ * for a numbered page's, and for the first cursor page's, read at none.
+ */
+
+/**
+ * The list's items in the DOM, each with its page, in document order: every
+ * element after a page's marker up to the next one. Each with the key it
+ * was rendered under, from the marker, when the page drew one element per
+ * item and the two can be paired.
+ *
+ * @param {Element} root
+ * @param {string} id
+ * @returns {Item[]}
+ */
+export function itemsOf(root, id) {
+  const out = [];
+  for (const marker of root.querySelectorAll('template[data-tinvar-merge]')) {
+    if (marker.getAttribute('data-tinvar-merge') !== id) continue;
+    const page = Number(marker.getAttribute('data-page'));
+    const cursor = marker.getAttribute('data-cursor') || null;
+    const elements = [];
+    for (let node = marker.nextElementSibling; node !== null; node = node.nextElementSibling) {
+      if (node.matches('template[data-tinvar-merge]')) break;
+      elements.push(node);
+    }
+    const keys = keysOf(marker);
+    const paired = keys !== null && keys.length === elements.length;
+    elements.forEach((element, index) =>
+      out.push({ page, element, key: paired ? /** @type {string} */ (keys[index]) : null, index, cursor }),
+    );
+  }
+  return out;
+}
+
+/**
+ * The item keys a page marker lists, or null where it lists none it can be
+ * read for.
+ *
+ * @param {Element} marker
+ * @returns {string[] | null}
+ */
+function keysOf(marker) {
+  try {
+    const keys = JSON.parse(marker.getAttribute('data-keys') ?? 'null');
+    return Array.isArray(keys) && keys.every((key) => typeof key === 'string') ? keys : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The top of what the reader sees of a list: its scroll container's, or the window's. */
+function topOf(/** @type {Element | null} */ container) {
+  return container === null ? 0 : container.getBoundingClientRect().top;
+}
+
+/**
+ * The first item the reader can see -- the page they are reading -- or
+ * null when none is in view.
+ *
+ * @param {Item[]} items
+ * @param {Element | null} container
+ * @returns {(Item & { top: number }) | null}
+ */
+function firstVisible(items, container) {
+  const top = topOf(container);
+  const bottom = container === null ? globalThis.innerHeight : container.getBoundingClientRect().bottom;
+  for (const item of items) {
+    const rect = item.element.getBoundingClientRect();
+    if (rect.bottom > top && rect.top < bottom) return { ...item, top: rect.top };
+  }
+  return null;
+}
+
+/**
+ * Where the reader is in a list: the first item they can see, how far down
+ * the window or the container its top is, and the pages loaded. Null when
+ * no item is in view.
+ *
+ * A cursor list's places count from the page that arrived whole, and that
+ * is the page the address bar names when the reader comes back: so they
+ * are kept counted from it -- `base`, the place of the page the bar names
+ * -- and the page that arrives then is 0 again.
+ *
+ * @param {Element} root
+ * @param {string} id
+ * @param {Element | null} container
+ * @param {{ first: { page: number }, last: { page: number } }} range
+ * @param {((visible: Item) => number) | null} [base] the place the bar's page is at, for a cursor list
+ * @returns {ScrollAnchor | null}
+ */
+export function anchorOf(root, id, container, range, base = null) {
+  const visible = firstVisible(itemsOf(root, id), container);
+  if (visible === null) return null;
+  const from = base === null ? 0 : base(visible);
+  return {
+    page: visible.page - from,
+    key: visible.key,
+    index: visible.index,
+    top: visible.top - topOf(container),
+    first: range.first.page - from,
+    last: range.last.page - from,
+    window: container === null,
+  };
+}
+
+/**
+ * Scrolls the list so the item an anchor names is where it was: found by
+ * its key, or failing that by its place on its page.
+ *
+ * @param {Element} root
+ * @param {string} id
+ * @param {Element | null} container
+ * @param {ScrollAnchor} anchor
+ * @returns {boolean} whether the item is there to scroll to
+ */
+export function scrollToAnchor(root, id, container, anchor) {
+  const items = itemsOf(root, id);
+  const item =
+    (anchor.key === null ? undefined : items.find((one) => one.key === anchor.key)) ??
+    items.find((one) => one.page === anchor.page && one.index === anchor.index);
+  if (item === undefined) return false;
+
+  const moved = item.element.getBoundingClientRect().top - topOf(container) - anchor.top;
+  if (Math.abs(moved) >= 1) {
+    if (container === null) globalThis.scrollBy(0, moved);
+    else container.scrollTop += moved;
+  }
+  return true;
+}
+
+function noop() {}
+
+/**
+ * Puts the reader at an anchor's item, and keeps them there for a moment
+ * while what is above the list settles -- a stream still arriving, a font
+ * -- unless they take over the scroll themselves first.
+ *
+ * @param {Element} root
+ * @param {string} id
+ * @param {Element | null} container
+ * @param {ScrollAnchor} anchor
+ * @returns {() => void} stops holding
+ */
+function holdAt(root, id, container, anchor) {
+  const started = Date.now();
+  let frame = 0;
+  const stop = () => {
+    cancelAnimationFrame(frame);
+    for (const type of USER_SCROLL_EVENTS) globalThis.removeEventListener(type, stop, true);
+  };
+  const hold = () => {
+    if (!scrollToAnchor(root, id, container, anchor) || Date.now() - started > SETTLE_MS) return stop();
+    frame = requestAnimationFrame(hold);
+  };
+  for (const type of USER_SCROLL_EVENTS)
+    globalThis.addEventListener(type, stop, { capture: true, passive: true });
+  hold();
+  return stop;
+}
+
+/**
+ * @param {{
+ *   field: ScrollMeta,
+ *   buffer?: number,
+ *   manual?: boolean,
+ *   manualAfter?: number,
+ *   reverse?: boolean,
+ *   preserveUrl?: boolean,
+ *   previous?: unknown,
+ *   next?: unknown,
+ *   children?: unknown,
+ * }} props
+ */
+export function InfiniteScrollRoot({
+  field,
+  buffer = 0,
+  manual = false,
+  manualAfter = 0,
+  reverse = false,
+  preserveUrl = false,
+  previous = null,
+  next = null,
+  children,
+}) {
+  const router = /** @type {import('./router.js').Router | null} */ (useOptionalRouter());
+  const generation = useContext(SegmentContext)?.generation ?? 0;
+
+  const rootRef = useRef(/** @type {HTMLDivElement | null} */ (null));
+  const startRef = useRef(/** @type {HTMLDivElement | null} */ (null));
+  const endRef = useRef(/** @type {HTMLDivElement | null} */ (null));
+
+  // Pages loaded by scrolling, for `manualAfter`; and every page loaded,
+  // which re-arms the triggers.
+  const [automatic, setAutomatic] = useState(0);
+  const [settled, setSettled] = useState(0);
+
+  // The pages loaded, from what each response said. Derived as it renders,
+  // so the range never commits behind the items <MergeSlot> shows. `epoch`
+  // counts the times it started again -- a reset, a whole page, a cursor
+  // page that cannot be placed -- which also starts the count of automatic
+  // loads again. `places` are where each cursor page went, by its cursor.
+  const byCursor = field.cursor !== undefined;
+  const [range, setRange] = useState(() => ({
+    field,
+    generation,
+    epoch: 0,
+    first: edgeOf(field),
+    last: edgeOf(field),
+    places: /** @type {ReadonlyMap<string, number>} */ (
+      new Map(byCursor ? [[placeKey(field.cursor), 0]] : [])
+    ),
+  }));
+  let current = range;
+  if (range.field !== field || range.generation !== generation) {
+    const placed = byCursor ? placeOf(range, field.cursor ?? null) : field.page;
+    const fresh = field.reset || range.generation !== generation || placed === undefined;
+    if (fresh) {
+      current = {
+        field,
+        generation,
+        epoch: range.epoch + 1,
+        first: edgeOf(field, byCursor ? 0 : field.page),
+        last: edgeOf(field, byCursor ? 0 : field.page),
+        places: new Map(byCursor ? [[placeKey(field.cursor), 0]] : []),
+      };
+    } else {
+      const edge = edgeOf(field, placed);
+      current = {
+        field,
+        generation,
+        epoch: range.epoch,
+        ...extendRange(range, edge),
+        places: byCursor ? new Map(range.places).set(placeKey(field.cursor), placed) : range.places,
+      };
+    }
+    setRange(current);
+    if (fresh && automatic !== 0) setAutomatic(0);
+  }
+
+  const [loading, setLoading] = useState(/** @type {'next' | 'previous' | null} */ (null));
+  const busy = useRef(/** @type {'next' | 'previous' | null} */ (null));
+
+  const switched = manual || (manualAfter > 0 && automatic >= manualAfter);
+
+  // Where the reader was when they left the entry a back, a forward or a
+  // reload has brought them to, while the pages they had are loaded again
+  // and they are put back at the item they were at. Nothing loads on its
+  // own meanwhile, the address bar stays, and nothing is recorded: the list
+  // passes through places the reader never was.
+  const [restoring, setRestoring] = useState(/** @type {ScrollAnchor | null} */ (null));
+  const restoringRef = useRef(/** @type {ScrollAnchor | null} */ (null));
+
+  // The range as last committed, for what runs across several loads.
+  const rangeRef = useRef(current);
+  useLayoutEffect(() => {
+    rangeRef.current = current;
+  });
+
+  /**
+   * Loads one page beyond an edge: a background partial reload of the
+   * list's segment at that page's URL, merged into the page on screen.
+   *
+   * @param {'next' | 'previous'} direction
+   * @param {boolean} [auto]
+   */
+  const load = useCallback(
+    async (direction, auto = false) => {
+      const target = direction === 'next' ? current.last.next : current.first.previous;
+      if (router === null || target === null || busy.current !== null) return false;
+
+      const url = new URL(globalThis.location.href);
+      url.searchParams.set(field.pageName, String(target));
+
+      // What goes in above what the reader sees -- the previous page, or in
+      // a chat the next -- would push it down. The first item in view is
+      // held where it was.
+      const above = reverse ? direction === 'next' : direction === 'previous';
+      const container = scrollContainerOf(rootRef.current);
+      const anchor =
+        above && rootRef.current ? firstVisible(itemsOf(rootRef.current, field.id), container) : null;
+
+      busy.current = direction;
+      setLoading(direction);
+      try {
+        const loaded = await router.visit(url.href, {
+          only: [field.id],
+          background: true,
+          preserveUrl: true,
+          preserveScroll: true,
+        });
+        if (!loaded) return false;
+
+        if (anchor !== null && anchor.element.isConnected) {
+          const moved = anchor.element.getBoundingClientRect().top - anchor.top;
+          if (moved !== 0) (container ?? globalThis).scrollBy(0, moved);
+        }
+        // Only a page that landed re-arms the triggers. One that did not --
+        // a navigation pending, the network down -- is tried again when the
+        // edge next comes into view, or when asked: re-armed at once, it
+        // asked again every frame for as long as the reason lasted.
+        if (auto) setAutomatic((n) => n + 1);
+        setSettled((n) => n + 1);
+        return true;
+      } finally {
+        busy.current = null;
+        setLoading(null);
+      }
+    },
+    [router, current, field.pageName, field.id, reverse],
+  );
+
+  const loadNext = useCallback(() => load('next'), [load]);
+  const loadPrevious = useCallback(() => load('previous'), [load]);
+
+  const loadRef = useRef(load);
+  useLayoutEffect(() => {
+    loadRef.current = load;
+  });
+
+  // Where the reader was, on the entry a back, a forward or a reload
+  // arrived at: taken as the list mounts, or starts again for a whole page,
+  // and the reader put at that item at once if its page is the one the
+  // address bar named -- as it is when the bar followed them. A raw scroll
+  // position cannot do this: the page arrives holding that one page, and
+  // the same offset lands a page or more from where they were. Before the
+  // chat's own start at the bottom, which it replaces.
+  useLayoutEffect(() => {
+    if (router === null || typeof router.takeScrollAnchor !== 'function' || !rootRef.current) return;
+    // With the container it puts the reader back in: should that be a
+    // scroll region, the router leaves its raw position to the list.
+    const container = scrollContainerOf(rootRef.current);
+    const anchor = router.takeScrollAnchor(field.id, container);
+    if (anchor === undefined) return;
+    restoringRef.current = anchor;
+    setRestoring(anchor);
+    scrollToAnchor(rootRef.current, field.id, container, anchor);
+  }, [router, field.id, current.epoch]);
+
+  // Then the pages the reader had loaded, those above first -- each held
+  // in place as it goes in -- up to RESTORE_PAGES either side, and the
+  // reader put back at the item once they are in, and held there while
+  // what is above the list settles.
+  const holding = useRef(noop);
+  useEffect(() => () => holding.current(), []);
+  useEffect(() => {
+    if (restoring === null) return undefined;
+    const epoch = rangeRef.current.epoch;
+    const first = Math.max(restoring.first, restoring.page - RESTORE_PAGES);
+    const last = Math.min(restoring.last, restoring.page + RESTORE_PAGES);
+    let stopped = false;
+    // A filter that starts the list again meanwhile ends it: the pages the
+    // reader had are not this list's.
+    const going = () => !stopped && rangeRef.current.epoch === epoch;
+    holding.current();
+
+    // A page is not loaded while a navigation is pending, and the back that
+    // brought the reader here is one until it has finished mounting this
+    // list: so each is asked for again a moment later, for a while.
+    const step = async (/** @type {'next' | 'previous'} */ direction) => {
+      for (let tries = 0; tries < RESTORE_TRIES && going(); tries++) {
+        if (await loadRef.current(direction)) return true;
+        await new Promise((resolve) => setTimeout(resolve, RESTORE_RETRY_MS));
+      }
+      return false;
+    };
+
+    void (async () => {
+      while (going() && rangeRef.current.first.page > first && rangeRef.current.first.previous !== null) {
+        if (!(await step('previous'))) break;
+      }
+      while (going() && rangeRef.current.last.page < last && rangeRef.current.last.next !== null) {
+        if (!(await step('next'))) break;
+      }
+      if (stopped) return;
+      if (going() && rootRef.current) {
+        holding.current = holdAt(rootRef.current, field.id, scrollContainerOf(rootRef.current), restoring);
+      }
+      restoringRef.current = null;
+      setRestoring(null);
+    })();
+
+    return () => {
+      stopped = true;
+    };
+  }, [restoring, field.id]);
+
+  // The two edges' triggers: `visible`, re-installed after every load, so
+  // an edge still in view once a page lands -- a short page, a tall
+  // screen -- loads the next at once rather than waiting to be scrolled
+  // away from and back to.
+  useEffect(() => {
+    if (router === null || switched || restoring !== null) return undefined;
+    const container = scrollContainerOf(rootRef.current);
+    const options = { buffer, always: true, root: container };
+    const teardowns = [];
+
+    const top = reverse ? 'next' : 'previous';
+    const bottom = reverse ? 'previous' : 'next';
+    const has = (/** @type {'next' | 'previous'} */ direction) =>
+      (direction === 'next' ? current.last.next : current.first.previous) !== null;
+    // A restore taken since this was installed has the list to itself.
+    const auto = (/** @type {'next' | 'previous'} */ direction) => () => {
+      if (restoringRef.current === null) void load(direction, true);
+    };
+
+    if (startRef.current && has(top)) teardowns.push(onVisible(startRef.current, auto(top), options));
+    if (endRef.current && has(bottom)) teardowns.push(onVisible(endRef.current, auto(bottom), options));
+
+    return () => {
+      for (const teardown of teardowns) teardown();
+    };
+  }, [router, switched, restoring, buffer, reverse, current, load, settled]);
+
+  // A chat starts at its newest message, at the bottom, and starts there
+  // again when a filter resets it.
+  useLayoutEffect(() => {
+    if (!reverse || !rootRef.current || restoringRef.current !== null) return;
+    const container = scrollContainerOf(rootRef.current);
+    if (container === null)
+      globalThis.scrollTo(0, rootRef.current.ownerDocument.documentElement.scrollHeight);
+    else container.scrollTop = container.scrollHeight;
+  }, [reverse, current.epoch]);
+
+  // Where the reader is, on the page's history entry, as they scroll and as
+  // pages land: what a back, a forward or a reload puts them back by.
+  useEffect(() => {
+    if (router === null || typeof router.saveScrollAnchor !== 'function' || !rootRef.current) {
+      return undefined;
+    }
+    const root = rootRef.current;
+    const container = scrollContainerOf(root);
+    const target = container ?? globalThis;
+    let frame = 0;
+
+    // A cursor list counts from the page the bar names: the reader's own,
+    // which URL sync puts there, or -- the bar left alone -- the page that
+    // arrived whole.
+    const base = !byCursor
+      ? null
+      : (/** @type {Item} */ visible) =>
+          preserveUrl
+            ? (rangeRef.current.places.get(
+                placeKey(new URL(globalThis.location.href).searchParams.get(field.pageName)),
+              ) ?? 0)
+            : visible.page;
+    const save = () => {
+      frame = 0;
+      if (restoringRef.current !== null) return;
+      const anchor = anchorOf(root, field.id, container, rangeRef.current, base);
+      if (anchor !== null) router.saveScrollAnchor(field.id, anchor);
+    };
+    const onScroll = () => {
+      if (frame === 0) frame = requestAnimationFrame(save);
+    };
+
+    target.addEventListener('scroll', onScroll, { passive: true });
+    onScroll();
+    return () => {
+      target.removeEventListener('scroll', onScroll);
+      if (frame !== 0) cancelAnimationFrame(frame);
+    };
+  }, [router, field.id, field.pageName, byCursor, preserveUrl, settled, restoring]);
+
+  // URL sync: the address bar names the page the reader is in, as they
+  // scroll, without a request or a new entry.
+  useEffect(() => {
+    if (router === null || preserveUrl || !rootRef.current) return undefined;
+    const root = rootRef.current;
+    const container = scrollContainerOf(root);
+    const target = container ?? globalThis;
+    let frame = 0;
+
+    const sync = () => {
+      frame = 0;
+      if (restoringRef.current !== null) return;
+      const visible = firstVisible(itemsOf(root, field.id), container);
+      if (visible === null) return;
+      const url = new URL(globalThis.location.href);
+      const named = url.searchParams.get(field.pageName);
+      // A cursor page is named by the cursor it was read at -- the first by
+      // none -- and a numbered one by its number, the first by none.
+      const wanted = byCursor ? visible.cursor : visible.page === 1 ? null : String(visible.page);
+      if (named === wanted) return;
+      if (wanted === null) url.searchParams.delete(field.pageName);
+      else url.searchParams.set(field.pageName, wanted);
+      router.replaceUrl(url.href);
+    };
+    const onScroll = () => {
+      if (frame === 0) frame = requestAnimationFrame(sync);
+    };
+
+    target.addEventListener('scroll', onScroll, { passive: true });
+    return () => {
+      target.removeEventListener('scroll', onScroll);
+      if (frame !== 0) cancelAnimationFrame(frame);
+    };
+  }, [router, preserveUrl, byCursor, field.id, field.pageName]);
+
+  const state = useMemo(
+    () => ({
+      id: field.id,
+      reverse,
+      loading,
+      manual: switched,
+      hasNext: current.last.next !== null,
+      hasPrevious: current.first.previous !== null,
+      first: current.first.page,
+      last: current.last.page,
+      total: field.total,
+      perPage: field.perPage,
+      loadNext,
+      loadPrevious,
+      epoch: current.epoch,
+      place: (/** @type {string | null} */ cursor) => current.places.get(placeKey(cursor)),
+    }),
+    [field.id, field.total, field.perPage, reverse, loading, switched, current, loadNext, loadPrevious],
+  );
+
+  const sentinel = (/** @type {typeof startRef} */ ref, /** @type {string} */ edge) =>
+    createElement('div', { ref, 'data-tinvar-scroll-edge': edge, 'aria-hidden': true, style: { height: 0 } });
+
+  return createElement(
+    InfiniteScrollContext.Provider,
+    { value: state },
+    createElement(
+      'div',
+      { ref: rootRef, 'data-tinvar-infinite-scroll': field.id },
+      sentinel(startRef, 'start'),
+      reverse ? next : previous,
+      children,
+      reverse ? previous : next,
+      sentinel(endRef, 'end'),
+    ),
+  );
+}