@tinvar/react 0.0.0-stage → 0.4.0

package/src/merge-slot.d.ts

@@ -0,0 +1,41 @@
+import type { ReactNode } from 'react';
+
+export type MergeMode = 'append' | 'prepend' | 'page';
+
+export interface Chunk {
+  order: number;
+  seq: number;
+  items: readonly unknown[];
+  keys: readonly (string | null)[];
+  /** A cursor page's: the cursor it was read at, null for the first (ADR 0120). */
+  cursor?: string | null;
+}
+
+export declare function mergeChunks(
+  chunks: readonly Chunk[],
+  incoming: {
+    items: readonly unknown[];
+    keys: readonly (string | null)[];
+    order: number;
+    seq: number;
+    cursor?: string | null;
+  },
+  mode: MergeMode,
+): Chunk[];
+
+export declare function arrange(
+  chunks: readonly Chunk[],
+  reverse: boolean,
+): { order: number; cursor?: string | null; entries: { key: string; node: unknown }[] }[];
+
+/** Where a merged list's items go; rendered by <Merged>, not by hand. */
+export declare function MergeSlot(props: {
+  id: string;
+  mode?: MergeMode;
+  order?: number;
+  /** A cursor page's cursor, which the <InfiniteScroll> around it places it by in place of `order`. */
+  cursor?: string | null;
+  reset?: boolean;
+  items?: readonly ReactNode[];
+  keys?: readonly (string | null)[];
+}): ReactNode;

package/src/merge-slot.js

@@ -0,0 +1,253 @@
+'use client';
+
+// Where a merged list's items go: those every response so far has rendered,
+// together (ADR 0020).
+//
+// The server renders a #[Merge] field or a Scroll page through <Merged>,
+// which draws only the items this response carries and hands them here. A
+// partial reload puts the page segment back at the position it had, so
+// React keeps this component and its state, and the new items are added to
+// those it holds: after them or before them for a #[Merge] field, and by
+// page number for a Scroll page, which goes where its page belongs whatever
+// order the pages arrive in. Each response's items are a chunk; a page
+// fetched again replaces its own chunk.
+//
+// Replaced instead, with only the new items:
+//   - when the response says so -- X-Reset named the field;
+//   - on a whole page, even the same page again, which the page root counts
+//     (`generation`): a navigation, a document, an action's re-render.
+//
+// Items match on their keys -- the matchOn property, or failing one the
+// React key the server rendered each with, unless that is its index (see
+// <Merged>) -- so an item that arrives again replaces the one shown, where
+// it stands, rather than appearing twice. For a #[Merge] field the old copy
+// is let go as the new one takes its place, so what is held is bounded by
+// what is shown however often the list is polled. Unkeyed items are never
+// matched.
+//
+// A cursor page has no number to go by (ADR 0120). The <InfiniteScroll>
+// around it places it by its cursors and says where -- `place()` -- and
+// when the list starts again -- `epoch` -- since a page read at a cursor no
+// page shown leads to cannot be placed among them at all.
+
+import { createElement, Fragment, useContext, useState } from 'react';
+import { InfiniteScrollContext } from './infinite-scroll.js';
+import { SegmentContext } from './segment.js';
+
+/**
+ * One response's items.
+ *
+ * @typedef {{
+ *   order: number,
+ *   seq: number,
+ *   items: readonly unknown[],
+ *   keys: readonly (string | null)[],
+ *   cursor?: string | null,
+ * }} Chunk
+ *
+ * `order` is where the chunk sits: the page number for a Scroll, and for a
+ * #[Merge] field one past the last chunk (append) or one before the first
+ * (prepend). `seq` counts arrivals, so the latest copy of a matched item
+ * wins.
+ *
+ * @typedef {'append' | 'prepend' | 'page'} Mode
+ */
+
+/**
+ * The chunks after one more arrives.
+ *
+ * @param {readonly Chunk[]} chunks in order
+ * @param {{ items: readonly unknown[], keys: readonly (string | null)[], order: number, seq: number, cursor?: string | null }} incoming
+ * @param {Mode} mode
+ * @returns {Chunk[]}
+ */
+export function mergeChunks(chunks, incoming, mode) {
+  if (chunks.length === 0) return [{ ...incoming, order: mode === 'page' ? incoming.order : 0 }];
+
+  if (mode === 'append' || mode === 'prepend') return mergeArrived(chunks, incoming, mode);
+
+  // A page again replaces itself, where it sits; a new one goes where its
+  // number puts it.
+  const others = chunks.filter((chunk) => chunk.order !== incoming.order);
+  return [...others, incoming].sort((a, b) => a.order - b.order);
+}
+
+/**
+ * A #[Merge] field's chunks after one more arrives: each matched item's
+ * latest copy put where the item already stands, only the new ones in the
+ * new chunk, and a chunk left with nothing dropped.
+ *
+ * Kept as arrived, a poll of the same twenty messages added twenty more
+ * held items every time -- three hundred polls, three hundred chunks and six
+ * thousand items, for twenty shown. Held once each, they are bounded by the
+ * items shown. Unkeyed items are never matched, so each arrival is new.
+ *
+ * @param {readonly Chunk[]} chunks in order
+ * @param {{ items: readonly unknown[], keys: readonly (string | null)[], order: number, seq: number }} incoming
+ * @param {'append' | 'prepend'} mode
+ * @returns {Chunk[]}
+ */
+function mergeArrived(chunks, incoming, mode) {
+  /** @type {Map<string, [number, number]>} where each key stands: chunk, item */
+  const standing = new Map();
+  chunks.forEach((chunk, c) =>
+    chunk.keys.forEach((key, i) => {
+      if (key !== null && key !== undefined) standing.set(key, [c, i]);
+    }),
+  );
+
+  /** @type {Chunk[]} */
+  const kept = [...chunks];
+  const copied = new Set();
+  const items = [];
+  const keys = [];
+  /** @type {Map<string, number>} */
+  const own = new Map();
+  incoming.items.forEach((node, i) => {
+    const key = incoming.keys[i] ?? null;
+    const stands = key === null ? undefined : standing.get(key);
+    if (stands !== undefined) {
+      const [c, at] = stands;
+      if (!copied.has(c)) {
+        const chunk = /** @type {Chunk} */ (kept[c]);
+        kept[c] = { ...chunk, items: [...chunk.items] };
+        copied.add(c);
+      }
+      /** @type {unknown[]} */ (/** @type {Chunk} */ (kept[c]).items)[at] = node;
+      return;
+    }
+    const mine = key === null ? undefined : own.get(key);
+    if (mine !== undefined) {
+      items[mine] = node;
+      return;
+    }
+    if (key !== null) own.set(key, items.length);
+    items.push(node);
+    keys.push(key);
+  });
+
+  const fresh = { ...incoming, items, keys };
+  const placed =
+    mode === 'append'
+      ? [...kept, { ...fresh, order: /** @type {Chunk} */ (kept.at(-1)).order + 1 }]
+      : [{ ...fresh, order: /** @type {Chunk} */ (kept[0]).order - 1 }, ...kept];
+  return placed.filter((chunk) => chunk.items.length > 0);
+}
+
+/**
+ * The items to render, in order, each once: a matched item at the place it
+ * first appears, with its latest copy.
+ *
+ * @param {readonly Chunk[]} chunks
+ * @param {boolean} reverse newest last, for a chat: the whole list turned round
+ * @returns {{ order: number, cursor?: string | null, entries: { key: string, node: unknown }[] }[]} by chunk, in display order
+ */
+export function arrange(chunks, reverse) {
+  /** @type {Map<string, { node: unknown, seq: number }>} */
+  const latest = new Map();
+  for (const chunk of chunks) {
+    chunk.items.forEach((node, i) => {
+      const key = chunk.keys[i];
+      if (key === null || key === undefined) return;
+      const seen = latest.get(key);
+      if (seen === undefined || seen.seq <= chunk.seq) latest.set(key, { node, seq: chunk.seq });
+    });
+  }
+
+  const shown = new Set();
+  const ordered = reverse ? [...chunks].reverse() : chunks;
+  return ordered.map((chunk) => {
+    const entries = [];
+    const indices = chunk.items.map((_, i) => i);
+    if (reverse) indices.reverse();
+    for (const i of indices) {
+      const key = chunk.keys[i];
+      if (key === null || key === undefined) {
+        // Positional, by the chunk's place, so it keeps its identity while
+        // its chunk stays.
+        entries.push({ key: `~${chunk.order}:${i}`, node: chunk.items[i] });
+        continue;
+      }
+      if (shown.has(key)) continue;
+      shown.add(key);
+      entries.push({ key: `k:${key}`, node: /** @type {{ node: unknown }} */ (latest.get(key)).node });
+    }
+    return { order: chunk.order, cursor: chunk.cursor, entries };
+  });
+}
+
+/**
+ * @param {{
+ *   id: string,
+ *   mode?: Mode,
+ *   order?: number,
+ *   cursor?: string | null,
+ *   reset?: boolean,
+ *   items?: readonly unknown[],
+ *   keys?: readonly (string | null)[],
+ * }} props `cursor`, for a cursor page: the cursor it was read at, which the
+ *        <InfiniteScroll> around it places it by in place of `order`
+ */
+export function MergeSlot({ id, mode = 'append', order = 0, cursor, reset = false, items = [], keys = [] }) {
+  const generation = useContext(SegmentContext)?.generation ?? 0;
+  const scroll = useContext(InfiniteScrollContext);
+  const own = scroll !== null && scroll.id === id;
+  const reverse = own && scroll.reverse;
+
+  // Where a cursor page goes, and how often its list has started again:
+  // the <InfiniteScroll>'s, worked out as it rendered, just before this.
+  const paged = cursor !== undefined && own && typeof scroll.place === 'function';
+  const at = paged ? (scroll.place(cursor) ?? 0) : order;
+  const epoch = paged ? scroll.epoch : 0;
+
+  const [state, setState] = useState(() => ({
+    items,
+    generation,
+    epoch,
+    seq: 1,
+    chunks: mergeChunks([], { items, keys, order: at, seq: 1, cursor }, mode),
+  }));
+
+  // A new response's items: merged during render, the way React derives
+  // state from a prop that changed, so the list never commits without them.
+  let current = state;
+  if (state.items !== items || state.generation !== generation || state.epoch !== epoch) {
+    const seq = state.seq + 1;
+    const incoming = { items, keys, order: at, seq, cursor };
+    const fresh = reset || state.generation !== generation || state.epoch !== epoch;
+    current = {
+      items,
+      generation,
+      epoch,
+      seq,
+      chunks: fresh ? mergeChunks([], incoming, mode) : mergeChunks(state.chunks, incoming, mode),
+    };
+    setState(current);
+  }
+
+  const out = [];
+  for (const chunk of arrange(current.chunks, reverse)) {
+    // Where each page starts, for <InfiniteScroll> to tell which page the
+    // reader is in. A <template>: allowed in a <tbody>, a <ul> or a <table>
+    // alike, rendered as nothing, and in nobody's accessibility tree. With
+    // the keys of the page's items, in order, so the item the reader was at
+    // is found again by its key after the pages are loaded afresh -- an
+    // order placed meanwhile moves every later one down a place.
+    if (mode === 'page') {
+      out.push(
+        createElement('template', {
+          key: `m:${chunk.order}`,
+          'data-tinvar-merge': id,
+          'data-page': String(chunk.order),
+          // The cursor a cursor page was read at, for the address bar; ''
+          // for the first page, which is read at none.
+          ...(cursor === undefined ? {} : { 'data-cursor': chunk.cursor ?? '' }),
+          'data-keys': JSON.stringify(chunk.entries.map((entry) => entry.key)),
+        }),
+      );
+    }
+    for (const entry of chunk.entries) out.push(createElement(Fragment, { key: entry.key }, entry.node));
+  }
+
+  return out;
+}

package/src/merge.d.ts

@@ -0,0 +1,111 @@
+import type { ReactNode } from 'react';
+
+/** The key a #[Merge] field is sent under, holding its dot path. */
+export declare const MERGE_KEY: '$merge';
+/** The key a Scroll page is sent under, holding its dot path. */
+export declare const SCROLL_KEY: '$scroll';
+
+/**
+ * What the encoder sends for a #[Merge] field: this response's items, and
+ * how the browser puts them with those it shows. Rendered through <Merged>.
+ * A field merged into a path -- `#[Merge(append: 'data')]` -- is its object
+ * with this under that property.
+ */
+export interface MergeField<T> {
+  /** The list's dot path, `'page.messages'` or `'page.feed.data'`: what X-Reset names it by. */
+  $merge: string;
+  mode: 'append' | 'prepend';
+  /** X-Reset named it: replace what is shown instead of adding to it. */
+  reset: boolean;
+  matchOn: string | null;
+  items: T[];
+}
+
+/**
+ * What the encoder sends for a Scroll: one page's items, and where they sit
+ * among the pages. Rendered through <InfiniteScroll> and <Merged>.
+ */
+export interface ScrollField<T> {
+  /** The field's dot path, `'page.orders'`: what X-Reset and X-Only name it by. */
+  $scroll: string;
+  reset: boolean;
+  page: number;
+  previous: number | null;
+  next: number | null;
+  total: number | null;
+  perPage: number;
+  /** The query parameter the page number is read from and written to. */
+  pageName: string;
+  matchOn: string | null;
+  items: T[];
+}
+
+/**
+ * What the encoder sends for a CursorScroll: one page of a list read by
+ * cursor, and the cursors of the pages either side -- sealed and bound to
+ * the reader by the server, opaque here (ADR 0120). A page has no number:
+ * the browser places it by its cursors. Rendered as a ScrollField is.
+ */
+export interface CursorScrollField<T> {
+  /** The field's dot path, `'page.orders'`: what X-Reset and X-Only name it by. */
+  $scroll: string;
+  reset: boolean;
+  /** The cursor this page was read at; null for the first page. */
+  cursor: string | null;
+  previous: string | null;
+  next: string | null;
+  total: null;
+  perPage: number;
+  /** The query parameter the cursor is read from and written to. */
+  pageName: string;
+  matchOn: string | null;
+  items: T[];
+}
+
+export declare function isScrollField(
+  field: unknown,
+): field is ScrollField<unknown> | CursorScrollField<unknown>;
+
+/**
+ * Renders this response's items of a merged field -- each keyed, by its own
+ * React key or the field's matchOn -- for the browser to put with those it
+ * shows. A server component.
+ */
+export declare function Merged<T>(props: {
+  field: MergeField<T> | ScrollField<T> | CursorScrollField<T>;
+  children: (item: T, index: number) => ReactNode;
+}): ReactNode;
+
+export interface InfiniteScrollProps<T> {
+  data: ScrollField<T> | CursorScrollField<T>;
+  /**
+   * The items, as a function of one; or elements holding a <Merged> for the
+   * same field -- inside a table's body, say.
+   */
+  children: ((item: T, index: number) => ReactNode) | ReactNode;
+  /** Pixels short of an edge at which the next page starts loading. 0 unless given. */
+  buffer?: number;
+  /** Load only when asked -- useInfiniteScroll().loadNext() -- never on scroll. */
+  manual?: boolean;
+  /** Load on scroll this many times, then only when asked. */
+  manualAfter?: number;
+  /**
+   * For a chat: the list turned round, newest at the bottom, starting
+   * scrolled there; scrolling up loads the next (older) page.
+   */
+  reverse?: boolean;
+  /** Leave the address bar alone as the reader scrolls from page to page. */
+  preserveUrl?: boolean;
+  /** Shown before the items (after them, reversed): a client component using useInfiniteScroll(). */
+  previous?: ReactNode;
+  /** Shown after the items (before them, reversed). */
+  next?: ReactNode;
+}
+
+/**
+ * A Scroll that loads its other pages as the reader nears either end:
+ * background partial reloads of its segment, merged in. Keeps the address
+ * bar on the page being read, and works in any scroll container. A server
+ * component.
+ */
+export declare function InfiniteScroll<T>(props: InfiniteScrollProps<T>): ReactNode;

package/src/merge.js

@@ -0,0 +1,149 @@
+// <Merged> and <InfiniteScroll>: a merged list, as server components.
+//
+// ADR 0020. Under RSC the browser holds rendered items, not the list they
+// were drawn from, so a #[Merge] field or a Scroll page is merged where its
+// items are: <Merged> renders only the items this response carries, each
+// keyed, and hands them to <MergeSlot>, the client component that holds
+// what earlier responses rendered. <InfiniteScroll> wraps a Scroll with the
+// client component that loads its other pages -- given the page's meta
+// alone, so the items cross once, as rendered elements, and never again as
+// props.
+//
+// No Node and no DOM: this runs in the RSC environment, where <MergeSlot>
+// and <InfiniteScrollRoot> are client references.
+
+import { createElement } from 'react';
+import { InfiniteScrollRoot } from './infinite-scroll.js';
+import { MergeSlot } from './merge-slot.js';
+
+/** The key a #[Merge] field is sent under, holding its dot path. */
+export const MERGE_KEY = '$merge';
+
+/** The key a Scroll page is sent under, holding its dot path. */
+export const SCROLL_KEY = '$scroll';
+
+/**
+ * @param {unknown} field
+ * @returns {boolean}
+ */
+export function isScrollField(field) {
+  return (
+    field !== null &&
+    typeof field === 'object' &&
+    typeof (/** @type {any} */ (field)[SCROLL_KEY]) === 'string'
+  );
+}
+
+/**
+ * Whether a Scroll field is a CursorScroll's: read by cursor, its page
+ * named by the cursor it was read at rather than by a number (ADR 0120).
+ *
+ * @param {unknown} field
+ * @returns {boolean}
+ */
+function isCursorScroll(field) {
+  return isScrollField(field) && 'cursor' in /** @type {object} */ (field);
+}
+
+/**
+ * @param {unknown} field
+ * @returns {boolean}
+ */
+function isMergeField(field) {
+  return (
+    field !== null && typeof field === 'object' && typeof (/** @type {any} */ (field)[MERGE_KEY]) === 'string'
+  );
+}
+
+/**
+ * The keys a response's items are matched by, across every response: each
+ * item's matchOn property where the field names one, else the React key it
+ * was rendered with. Null for neither, and then it is never matched -- kept
+ * by its place on its own page or arrival, so never across them.
+ *
+ * matchOn first: it is what the field says its items are told apart by,
+ * where a React key is only how one component drew them. And a list keyed
+ * by its index -- every key the item's place, 0 to n-1 -- is keyed by
+ * nothing: page 2's 0 is not page 1's 0, and matched, page 2's first item
+ * replaced page 1's.
+ *
+ * @param {readonly unknown[]} nodes
+ * @param {readonly unknown[]} items
+ * @param {string | null} matchOn
+ * @returns {(string | null)[]}
+ */
+function keysOf(nodes, items, matchOn) {
+  const own = nodes.map((node) => {
+    const key = /** @type {{ key?: unknown } | null} */ (node)?.key;
+    return typeof key === 'string' || typeof key === 'number' ? String(key) : null;
+  });
+  const byIndex = own.length > 0 && own.every((key, index) => key === String(index));
+
+  return items.map((item, index) => {
+    if (matchOn !== null && item !== null && typeof item === 'object') {
+      const value = /** @type {Record<string, unknown>} */ (item)[matchOn];
+      if (typeof value === 'string' || typeof value === 'number') return String(value);
+    }
+    return byIndex ? null : (own[index] ?? null);
+  });
+}
+
+/**
+ * Renders the items a merged field carries in this response, for the
+ * browser to put with those it shows.
+ *
+ * @param {{ field: any, children: (item: any, index: number) => unknown }} props
+ */
+export function Merged({ field, children }) {
+  const scroll = isScrollField(field);
+  if (!scroll && !isMergeField(field)) {
+    throw new TypeError('[tinvar] <Merged> renders a #[Merge] field or a Scroll; this is neither.');
+  }
+
+  const items = /** @type {unknown[]} */ (field.items).map((item, index) => children(item, index));
+  const keys = keysOf(items, field.items, field.matchOn ?? null);
+
+  return createElement(MergeSlot, {
+    id: scroll ? field[SCROLL_KEY] : field[MERGE_KEY],
+    mode: scroll ? 'page' : field.mode,
+    // A cursor page has no number: <InfiniteScroll> places it by its cursor.
+    order: scroll && !isCursorScroll(field) ? field.page : 0,
+    ...(isCursorScroll(field) ? { cursor: field.cursor } : {}),
+    reset: field.reset === true,
+    items,
+    keys,
+  });
+}
+
+/**
+ * A Scroll that loads its other pages as the reader nears either end of
+ * what is shown. Given a function as children it renders the items itself;
+ * given elements, they hold a <Merged> for the same field somewhere inside
+ * -- a table's body, say -- and the edges are around them all.
+ *
+ * @param {{ data: any, children: unknown, [option: string]: unknown }} props
+ */
+export function InfiniteScroll({ data, children, ...options }) {
+  if (!isScrollField(data)) {
+    throw new TypeError('[tinvar] <InfiniteScroll> loads a Scroll field; this is not one.');
+  }
+
+  const field = {
+    id: data[SCROLL_KEY],
+    page: isCursorScroll(data) ? 0 : data.page,
+    ...(isCursorScroll(data) ? { cursor: data.cursor } : {}),
+    previous: data.previous,
+    next: data.next,
+    total: data.total,
+    perPage: data.perPage,
+    pageName: data.pageName,
+    reset: data.reset === true,
+  };
+
+  const content =
+    typeof children === 'function'
+      ? createElement(Merged, { field: data, children: /** @type {any} */ (children) })
+      : children;
+
+  return createElement(InfiniteScrollRoot, { ...options, field }, content);
+}

package/src/once-slot.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+
+/** Where a once field's rendered content goes; rendered by <Once>, not by hand. */
+export declare function OnceSlot(props: {
+  id: string;
+  held?: boolean;
+  ttl?: number | null;
+  tags?: readonly string[];
+  /** False for content shown but not kept: a rescued failure. */
+  keep?: boolean;
+  /** A once-shared value's signed hold, kept with it to claim it by (ADR 0065). */
+  hold?: string | null;
+  children?: ReactNode;
+}): ReactNode;

package/src/once-slot.js

@@ -0,0 +1,75 @@
+'use client';
+
+// Where a #[Once] field's rendered content goes, and where the browser keeps
+// it from (ADR 0020).
+//
+// The server renders <Once> as this slot: with the content drawn from the
+// field the first time, which the slot hands the router to keep; or -- once
+// a request has listed the key in X-Have-Once -- empty and marked held,
+// when the slot shows what was kept. Server components are rendered away by
+// the time a payload arrives, so the browser has nothing to redraw a field
+// from; what it has is what was drawn, and this is where it is put back.
+//
+// Kept for the page the slot belongs to, taken as it renders: a page being
+// mounted files what it draws under the session its own response came with,
+// never the one on screen it is about to replace.
+
+import { useLayoutEffect, useRef } from 'react';
+import { useOptionalRouter } from './link.js';
+
+/** Keys already reported missing, so a broken page says so once, not per render. */
+const reported = new Set();
+
+/**
+ * @param {{
+ *   id: string,
+ *   held?: boolean,
+ *   ttl?: number | null,
+ *   tags?: readonly string[],
+ *   keep?: boolean,
+ *   hold?: string | null,
+ *   children?: unknown,
+ * }} props
+ *
+ * `keep` false shows the content without keeping it: a rescued failure,
+ * which the next visit must ask for again rather than claim. `hold` is a
+ * once-shared value's signed hold, kept with it and claimed by (ADR 0065).
+ */
+export function OnceSlot({ id, held = false, ttl = null, tags = [], keep = true, hold = null, children }) {
+  const router = /** @type {import('./router.js').Router | null} */ (useOptionalRouter());
+  const scope = router?.rememberScope();
+
+  // What this slot last showed, by key. The browser keeps only so many
+  // fields, and drops the least recently used: one on screen, rendered
+  // again after its entry went, still shows what it showed.
+  const shown = useRef(/** @type {{ id: string, content: unknown } | null} */ (null));
+
+  useLayoutEffect(() => {
+    // On commit, never during render: a render React throws away must not
+    // replace what the next response may be answered from.
+    if (!held && keep && router) router.holdOnce(id, children, ttl, tags, scope, hold);
+  }, [router, scope, held, keep, id, children, ttl, tags, hold]);
+
+  const kept = held ? router?.heldOnce(id, scope) : undefined;
+  useLayoutEffect(() => {
+    if (!held) shown.current = { id, content: children ?? null };
+    else if (kept !== undefined) shown.current = { id, content: kept.content };
+  });
+
+  // The server render that makes the HTML, and every response the browser
+  // did not claim the key for: the content is right here.
+  if (!held) return children ?? null;
+
+  if (kept !== undefined) return kept.content;
+  if (shown.current?.id === id) return shown.current.content;
+
+  // The server left it out because this client said it had it. Nothing
+  // keeps it any more -- a defect, since an entry is only dropped with the
+  // session, or to make room along with every prefetched page that claimed
+  // it -- so the slot is empty, and says why.
+  if (!reported.has(id)) {
+    reported.add(id);
+    console.error(`[tinvar:client] Nothing is kept for the once field '${id}' the server left out.`);
+  }
+  return null;
+}

package/src/once-store.d.ts

@@ -0,0 +1,26 @@
+/** How many rendered fields are kept, at most, before the least recently used go. */
+export declare const MAX_KEPT: number;
+
+/** What the browser keeps of #[Once] fields, by key, bound to a session. */
+export interface OnceStore {
+  /** Most recently used first. */
+  claimable(binding: string | null): string[];
+  /** The once-shared values to claim in X-Have-Shared, each by its signed hold (ADR 0065). */
+  holds(binding: string | null): { key: string; hold: string }[];
+  read(key: string, binding: string | null): { content: unknown } | undefined;
+  /** Returns the keys dropped to make room. */
+  record(
+    key: string,
+    binding: string | null,
+    content: unknown,
+    ttl: number | null,
+    tags: readonly string[],
+    hold?: string | null,
+  ): string[];
+  flushTags(tags: readonly string[]): number;
+  flush(keys?: readonly string[]): void;
+  keepOnly(binding: string | null): void;
+  clear(): void;
+}
+
+export declare function createOnceStore(options?: { now?: () => number; max?: number }): OnceStore;