makersclaw 0.5.2 → 0.7.0

package/templates/next/files/lib/door.js

@@ -0,0 +1,680 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { claw } from "./claw";
+import { surfaceOfPath } from "./platform";
+
+// The app's own tables through the data door, from the browser (claw
+// docs/brain/STATIC-SPEC.md §3; the door's routes are CONTRACTS §8, "The
+// own-tables half").
+//
+// A browser app has no server of its own. It reads and writes its tables
+// through _claw/data, which the Makersclaw gateway answers under the
+// app's path: the grant cookie says who is asking, the work runs on the
+// app's own database role in one transaction that knows the member, and
+// the door writes the activity line. This file is the door's client,
+// with the names and shapes of the server data layer (lib/data.js's
+// reads, lib/actions.js's writes), so a surface reads the same in both
+// modes. A browser app's lib/data.js and lib/actions.js re-export it under
+// those names; in a server app a "use client" component may take its
+// hooks from here.
+//
+// The rules it keeps:
+//   - Every function resolves and never throws. A read that fails keeps
+//     its empty values ({ rows: [], error, code }, and unavailable: true
+//     when no door answers: an older Makersclaw, or the app on its own).
+//     A write that fails is { ok: false, error, code }, never undefined:
+//     a block reads undefined as success.
+//   - A filter goes to the door as it is: the one grammar lib/data.js's
+//     whereClause reads in a server app. orderBy goes as `order`.
+//   - The door's JSON is handed on as it came. A date is its day, a
+//     numeric or a bigint is text, as the server layer gives them.
+//   - Writes go one at a time, in the order they were called, as Next ran
+//     a client's Server Actions: a slow older save never lands after a
+//     newer one.
+//   - Every write that answers ok calls dataChanged(). Every mounted hook
+//     reads again, and whenLanded() resolves once they have all handed
+//     out their new rows, in one pass.
+//   - Nothing here logs activity: the door writes the line. `data` on
+//     updateRow is taken and never sent (a value never goes in a line).
+
+/** What a call needs and was not given; its words follow the name. */
+class Refused extends Error {}
+
+/** One path segment, encoded, so "a/b" stays one. */
+function segment(value, what) {
+  if (value === undefined || value === null || value === "") throw new Refused(`needs ${what}`);
+  return encodeURIComponent(String(value));
+}
+
+/** "?a=1&b=2", leaving out what was not given. */
+function query(params) {
+  const q = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null || value === "") continue;
+    q.set(key, String(value));
+  }
+  const text = q.toString();
+  return text ? `?${text}` : "";
+}
+
+/** A filter as the door reads it: JSON in the query. One that names
+ *  nothing (every condition undefined, as JSON drops them) is none. */
+function whereOf(filter) {
+  if (filter === undefined || filter === null) return undefined;
+  const text = JSON.stringify(filter);
+  return text === "{}" ? undefined : text;
+}
+
+/** id_column, sent only when it is not the door's default, id. */
+function idColumnOf(idColumn) {
+  return idColumn && idColumn !== "id" ? String(idColumn) : undefined;
+}
+
+/** A whole number from 1 to `most`, `fallback` for anything else, as
+ *  the server's loadRows reads its limit. */
+function clamp(value, fallback, most) {
+  return Math.max(1, Math.min(most, Math.floor(Number(value)) || fallback));
+}
+
+/** A positive whole number, or none. */
+function skip(value) {
+  const n = Math.floor(Number(value));
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+/** The surface the page is on, for the door's activity line: the <key>
+ *  of /s/<key> in its path. */
+function pageSurface() {
+  return typeof location === "undefined" ? undefined : surfaceOfPath(location.pathname) || undefined;
+}
+
+/** A write's surface: the caller's key (a string, or the page's
+ *  `surface` object), else the page's. null sends none. */
+function surfaceOf(explicit) {
+  if (explicit === null) return undefined;
+  if (typeof explicit === "string" && explicit) return explicit;
+  if (explicit && typeof explicit === "object" && typeof explicit.key === "string" && explicit.key) return explicit.key;
+  return pageSurface();
+}
+
+/** The keys of an object whose values are given. */
+function given(values) {
+  return values && typeof values === "object" && !Array.isArray(values) ? Object.keys(values).filter((k) => values[k] !== undefined) : [];
+}
+
+/** A claw() answer → { data }, the door's JSON, or { fail }, why not:
+ *  { error, code } always, unavailable or aborted when so. */
+function readAnswer(answer) {
+  const data = answer?.data;
+  const json = Boolean(data) && typeof data === "object" && !Array.isArray(data);
+  if (answer?.ok && json && data.ok !== false) return { data };
+  if (answer?.ok) {
+    // A 2xx that is not the door's success: its refusal, or not its JSON.
+    if (!json) return { fail: { error: "the door answered something that is not its JSON", code: "failed" } };
+    return { fail: { error: String(data.error || "the door refused"), code: typeof data.code === "string" && data.code ? data.code : "failed" } };
+  }
+  const fail = { error: String(answer?.error || "the door refused") };
+  fail.code = answer?.code || (answer?.aborted ? "aborted" : answer?.unavailable ? "unavailable" : "failed");
+  if (answer?.unavailable) fail.unavailable = true;
+  if (answer?.aborted) fail.aborted = true;
+  return { fail };
+}
+
+/** A call refused here, before anything was sent, said as the door would. */
+function refusedHere(name, error, empty = {}) {
+  const words = error instanceof Refused ? `${name} ${error.message}` : `${name}: ${error?.message ?? error}`;
+  return { ...empty, error: words, code: "bad_request" };
+}
+
+// ---------------------------------------------------------------------------
+// Reads. They resolve and never throw: lib/data.js's names and shapes.
+
+/**
+ * The reads, each as: `empty()` (what a failure keeps, fresh each
+ * time), `path(args)` (under _claw/data; null asks nothing and answers
+ * the empty values), `pick(json)` (the answer's values) and, for loadRow,
+ * `absent(code)` (a refusal that means "no such row", which the server
+ * reads as row: null).
+ */
+const READS = {
+  loadRows: {
+    empty: () => ({ rows: [], next: null }),
+    path: ({ source, idColumn, orderBy, limit = 500, filter, offset, cursor }) =>
+      `tables/${segment(source, "a source")}/rows` +
+      query({ where: whereOf(filter), order: orderBy, limit: clamp(limit, 500, 5000), offset: skip(offset), cursor, id_column: idColumnOf(idColumn) }),
+    pick: (json) => ({ rows: listOf(json.rows), next: json.next ?? null }),
+  },
+  loadRow: {
+    empty: () => ({ row: null }),
+    path: ({ source, idColumn, id }) => {
+      const table = segment(source, "a source");
+      if (id === undefined || id === null || id === "") return null;
+      return `tables/${table}/rows/${segment(id, "an id")}` + query({ id_column: idColumnOf(idColumn) });
+    },
+    pick: (json) => ({ row: json.row ?? null }),
+    absent: (code) => code === "not_found",
+  },
+  countRows: {
+    empty: () => ({ count: 0 }),
+    path: ({ source, filter }) => `tables/${segment(source, "a source")}/counts` + query({ where: whereOf(filter) }),
+    pick: (json) => ({ count: json.count ?? 0 }),
+  },
+  countBy: {
+    empty: () => ({ counts: {} }),
+    path: ({ source, column, filter }) => {
+      const table = segment(source, "a source");
+      if (!column) throw new Refused("needs a column");
+      return `tables/${table}/counts` + query({ by: column, where: whereOf(filter) });
+    },
+    pick: (json) => ({ counts: json.by && typeof json.by === "object" && !Array.isArray(json.by) ? json.by : {} }),
+  },
+  loadActivity: {
+    empty: () => ({ rows: [] }),
+    path: ({ limit = 100, surface, since } = {}) =>
+      "activity" + query({ surface, since: since instanceof Date ? since.toISOString() : since, limit: clamp(limit, 100, 1000) }),
+    pick: (json) => ({ rows: listOf(json.rows) }),
+  },
+};
+
+class NotItsJson extends Error {}
+
+function listOf(value) {
+  if (!Array.isArray(value)) throw new NotItsJson();
+  return value;
+}
+
+/** Run one of READS. Never throws. */
+async function read(name, args) {
+  const { empty, path, pick, absent } = READS[name];
+  let sub;
+  try {
+    sub = path(args ?? {});
+  } catch (error) {
+    return refusedHere(name, error, empty());
+  }
+  if (sub === null) return { ...empty(), error: null };
+  let answer;
+  try {
+    answer = await claw(`data/${sub}`, { signal: args?.signal });
+  } catch (error) {
+    answer = { ok: false, error: String(error?.message ?? error) };
+  }
+  const { data, fail } = readAnswer(answer);
+  if (fail) return absent?.(fail.code) ? { ...empty(), error: null } : { ...empty(), ...fail };
+  try {
+    return { ...pick(data), error: null };
+  } catch {
+    return { ...empty(), error: "the door answered something that is not its JSON", code: "failed" };
+  }
+}
+
+/** GET _claw/data/tables/<source>/rows: rows of one of the app's own
+ *  tables or views. `filter` is { column: condition } in the door's
+ *  grammar (lib/data.js's whereClause), `orderBy` "updated_at desc"
+ *  (default: idColumn desc), `limit` 500 (at most 5,000), `offset` at
+ *  most 10,000; `cursor` the last answer's `next`, which the door gives
+ *  only when orderBy names one column. → { rows, error, next } */
+export function loadRows(args) {
+  return read("loadRows", args);
+}
+
+/** GET _claw/data/tables/<source>/rows/<id>: one row. `row` is null when
+ *  there is none, and when no id is given (nothing is asked).
+ *  → { row, error } */
+export function loadRow(args) {
+  return read("loadRow", args);
+}
+
+/** GET _claw/data/tables/<source>/counts: how many rows match `filter`.
+ *  → { count, error } */
+export function countRows(args) {
+  return read("countRows", args);
+}
+
+/** GET _claw/data/tables/<source>/counts?by=<column>: rows per value of
+ *  `column`, "null" for none. → { counts: { [value]: n }, error } */
+export function countBy(args) {
+  return read("countBy", args);
+}
+
+/** GET _claw/data/activity: this app's activity lines, newest first.
+ *  `surface` narrows to one surface key, `since` (ISO or a Date) to
+ *  lines after it, `limit` 100 (at most 1,000). Rows: { id, at, action,
+ *  surface, row_ref, detail, data, by }. → { rows, error } */
+export function loadActivity(args) {
+  return read("loadActivity", args);
+}
+
+// ---------------------------------------------------------------------------
+// Writes. lib/actions.js's names and shapes, and runAction.
+
+// One write at a time, in the order called. Next ran a client's Server
+// Actions so; plain fetches overlap, and a whole-document save that
+// answered slowly would land over the newer one after it.
+let turn = Promise.resolve();
+
+/** Run `work` once every write called before it has answered. The
+ *  brain's writes (lib/brain.js) take their turn here too. */
+export function inTurn(work) {
+  const run = turn.then(work, work);
+  turn = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  return run;
+}
+
+/** One write: `build(args)` → { path, method, body }. Refused here with
+ *  nothing sent when an argument is missing; else sent in its turn. A
+ *  success is the door's JSON as it came, and calls dataChanged(). */
+async function write(name, args, build) {
+  let req;
+  try {
+    req = build(args ?? {});
+    // claw() would read a body that cannot be JSON as "not reachable".
+    JSON.stringify(req.body);
+  } catch (error) {
+    return { ok: false, ...refusedHere(name, error) };
+  }
+  return inTurn(async () => {
+    let answer;
+    try {
+      answer = await claw(`data/${req.path}`, { method: req.method ?? "POST", body: req.body });
+    } catch (error) {
+      answer = { ok: false, error: String(error?.message ?? error) };
+    }
+    const { data, fail } = readAnswer(answer);
+    if (fail) return { ok: false, ...fail };
+    dataChanged();
+    return data;
+  });
+}
+
+/** The row's path: tables/<source>/rows/<id>. */
+function rowPath(source, id) {
+  const table = segment(source, "a source");
+  return `tables/${table}/rows/${segment(id, "an id")}`;
+}
+
+/** A patch: the given columns, or refused. */
+function patchOf(patch) {
+  const cols = given(patch);
+  if (!cols.length) throw new Refused("has nothing to change");
+  return Object.fromEntries(cols.map((c) => [c, patch[c]]));
+}
+
+/** Add a row: POST _claw/data/tables/<source>/rows. `values` is
+ *  { column: value }; the door answers the new row's id (idColumn).
+ *  `action` defaults to "added" at the door. → { ok, id } */
+export function insertRow(args) {
+  return write("insertRow", args, ({ source, idColumn, values, surface, action, detail }) => {
+    const table = segment(source, "a source");
+    const cols = given(values);
+    if (!cols.length) throw new Refused("has nothing to add");
+    return {
+      path: `tables/${table}/rows`,
+      body: {
+        values: Object.fromEntries(cols.map((c) => [c, values[c]])),
+        id_column: idColumnOf(idColumn),
+        action,
+        surface: surfaceOf(surface),
+        detail,
+      },
+    };
+  });
+}
+
+/** Change columns of one row: PATCH _claw/data/tables/<source>/rows/<id>.
+ *  The door stamps updated_at as the server's updateRow does. `log:
+ *  false` writes no activity line (a save that is typing, not a
+ *  decision). `data` is taken and not sent. → { ok } */
+export function updateRow(args) {
+  return write("updateRow", args, ({ source, idColumn, id, patch, surface, action, detail, log }) => ({
+    method: "PATCH",
+    path: rowPath(source, id),
+    body: {
+      patch: patchOf(patch),
+      id_column: idColumnOf(idColumn),
+      action,
+      surface: surfaceOf(surface),
+      detail,
+      log: log === false ? false : undefined,
+    },
+  }));
+}
+
+/** Move a row to another state (a board column, a stage): updateRow of
+ *  `stateColumn`, its line "moved", "to <to>". → { ok } */
+export function moveRow(args) {
+  return write("moveRow", args, ({ source, idColumn, id, stateColumn, to, surface }) => {
+    const path = rowPath(source, id);
+    if (!stateColumn) throw new Refused("needs a stateColumn");
+    if (to === undefined) throw new Refused("needs `to`, the state to move to");
+    return {
+      method: "PATCH",
+      path,
+      body: { patch: { [stateColumn]: to }, id_column: idColumnOf(idColumn), action: "moved", surface: surfaceOf(surface), detail: `to ${to}` },
+    };
+  });
+}
+
+/** Remove a row: POST _claw/data/tables/<source>/rows/<id>/delete.
+ *  → { ok } */
+export function deleteRow(args) {
+  return write("deleteRow", args, ({ source, idColumn, id, surface, detail }) => ({
+    path: `${rowPath(source, id)}/delete`,
+    body: { id_column: idColumnOf(idColumn), surface: surfaceOf(surface), detail },
+  }));
+}
+
+/**
+ * Settings, one key: POST _claw/data/tables/<source>/setting. Table mode
+ * updates the (keyColumn, valueColumn) row and inserts one when there is
+ * none; json mode sets `key` inside the jsonb `column` of the row `id`.
+ * The door does either in one transaction. → { ok }
+ */
+export function saveSetting(args) {
+  return write("saveSetting", args, ({ mode = "table", source, keyColumn = "key", valueColumn = "value", column, idColumn, id, key, value, surface }) => {
+    const table = segment(source, "a source");
+    if (mode !== "table" && mode !== "json") throw new Refused(`takes mode "table" or "json", not ${JSON.stringify(mode)}`);
+    if (!key) throw new Refused("needs a key");
+    const body = { mode, key, value: value === undefined ? null : value, surface: surfaceOf(surface) };
+    if (mode === "json") {
+      if (!column) throw new Refused("needs the jsonb column, in json mode");
+      if (id === undefined || id === null || id === "") throw new Refused("needs the row's id, in json mode");
+      Object.assign(body, { column, id, id_column: idColumnOf(idColumn) });
+    } else {
+      Object.assign(body, { key_column: keyColumn !== "key" ? keyColumn : undefined, value_column: valueColumn !== "value" ? valueColumn : undefined });
+    }
+    return { path: `tables/${table}/setting`, body };
+  });
+}
+
+/**
+ * Run an action: POST _claw/data/actions/<name>, which calls the app's
+ * function `<name>(args jsonb) returns jsonb` in one transaction, as the
+ * member. `args` defaults to {}. The door logs the call: `action`
+ * defaults to the name, `row_ref` is `rowRef` or the result's id; `log:
+ * false` writes no line. A function's own `raise exception` comes back as
+ * its sentence, code action_refused. → { ok, result }
+ */
+export function runAction(args) {
+  return write("runAction", args, ({ name, args: input, surface, action, detail, rowRef, log }) => ({
+    path: `actions/${segment(name, "a name")}`,
+    body: {
+      args: input === undefined ? {} : input,
+      action,
+      row_ref: rowRef,
+      surface: surfaceOf(surface),
+      detail,
+      log: log === false ? false : undefined,
+    },
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// The refresh. Every mounted hook is a reader. dataChanged() starts one
+// landing: every reader reads again, and when all have answered, their
+// new values are handed out in one pass, so the page moves at once. A
+// change while a landing is out starts one more after it: an answer read
+// before the change must not be the last one shown.
+
+/** How long a landing waits for its slowest read before it hands out
+ *  what has come; a late answer is then handed out when it comes. */
+const LANDING_WAIT_MS = 10_000;
+
+const readers = new Set();
+let landing = null;
+let again = false;
+let waiting = [];
+
+/** Something changed: every hook on the page reads again. Every write
+ *  here that answers ok calls it, and so does a browser app's
+ *  auto-refresh when the door says the tables or the brain moved. */
+export function dataChanged() {
+  if (landing) {
+    again = true;
+    return;
+  }
+  startLanding();
+}
+
+/** Resolves when every read the last dataChanged() started has answered
+ *  and its hook has handed out its rows. Nothing out: at once. */
+export function whenLanded() {
+  if (!landing && !again) return Promise.resolve();
+  return new Promise((resolve) => waiting.push(resolve));
+}
+
+function startLanding() {
+  again = false;
+  const run = { open: true, pending: new Set(), handOut: [], timer: null };
+  landing = run;
+  for (const reader of [...readers]) {
+    try {
+      reader.reread(run);
+    } catch {
+      /* a reader that cannot read waits for nothing */
+    }
+  }
+  if (!run.pending.size) {
+    closeLanding(run);
+    return;
+  }
+  run.timer = setTimeout(() => closeLanding(run), LANDING_WAIT_MS);
+}
+
+/** A read of this landing answered; `handOut` sets its hook's state, or
+ *  is null (aborted, unmounted). The last one closes the landing. */
+function landed(run, flight, handOut) {
+  if (!run.open) {
+    handOut?.();
+    return;
+  }
+  run.pending.delete(flight);
+  if (handOut) run.handOut.push(handOut);
+  if (!run.pending.size) closeLanding(run);
+}
+
+function closeLanding(run) {
+  if (!run.open) return;
+  run.open = false;
+  clearTimeout(run.timer);
+  // Every hook's new values in one synchronous pass: React renders them
+  // together.
+  for (const handOut of run.handOut.splice(0)) {
+    try {
+      handOut();
+    } catch {
+      /* one hook's failure is not the others' */
+    }
+  }
+  if (landing === run) landing = null;
+  if (again) {
+    startLanding();
+    return;
+  }
+  for (const resolve of waiting.splice(0)) resolve();
+}
+
+// A hook's options are compared by value on every render: a new object
+// with the same values reads nothing. A time is the exception. A server
+// component read once per request, so a bound worked out as it ran
+// (`since: new Date(Date.now() - 7 * 864e5)`) cost one read. A hook runs
+// on every render, and the answer is itself a render: compared to the
+// millisecond, that bound was new options on each one, and the hook
+// blanked and read again forever (a 30 ms round trip made 36 reads a
+// second, over the door's rate limit, with loading true throughout). So
+// a time in a bound (`filter`, the brain's `where`, `since`) is compared
+// to the minute, and when only a time moved the hook keeps what it shows
+// while it reads again. The read always sends the time it was given.
+
+/** The options that hold bounds, where a time may be worked out on each
+ *  render. Only these: an `id` that looks like a time is still an id. */
+const BOUNDS = new Set(["filter", "where", "since"]);
+
+/** A time as text: a day and a time of day ("2026-09-30T08:15:00Z"). A
+ *  day alone does not move between renders, and is compared as it is. */
+const TIME_TEXT = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/;
+const MINUTE_MS = 60_000;
+
+/** `value` with each time in it (a Date, or a time as text) replaced by
+ *  `as(ms)`, through lists and conditions. */
+function withTimes(value, as) {
+  if (value instanceof Date) return as(value.getTime());
+  if (typeof value === "string") {
+    const ms = TIME_TEXT.test(value) ? Date.parse(value) : NaN;
+    return Number.isFinite(ms) ? as(ms) : value;
+  }
+  if (Array.isArray(value)) return value.map((v) => withTimes(v, as));
+  // An object JSON would read through its own toJSON is left to it.
+  if (value && typeof value === "object" && typeof value.toJSON !== "function") {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, withTimes(v, as)]));
+  }
+  return value;
+}
+
+const toMinute = (ms) => `\u0000minute ${Math.floor(ms / MINUTE_MS)}`;
+const anyTime = () => "\u0000time";
+
+/** A hook's options as text, each time in a bound replaced by `as(ms)`.
+ *  The top-level `signal` is the hook's own. */
+function optionsText(opts, as) {
+  try {
+    if (!opts || typeof opts !== "object" || Array.isArray(opts)) return JSON.stringify(opts ?? null);
+    const plain = {};
+    for (const [name, value] of Object.entries(opts)) {
+      if (name !== "signal") plain[name] = BOUNDS.has(name) ? withTimes(value, as) : value;
+    }
+    return JSON.stringify(plain);
+  } catch {
+    return "unreadable";
+  }
+}
+
+/** The key: a change of any value reads again, a time's to the minute. */
+const keyOf = (opts) => optionsText(opts, toMinute);
+
+/** The question without its times: the same shape and a new key means
+ *  only a time moved, and what is shown stays until the new answer. */
+const shapeOf = (opts) => optionsText(opts, anyTime);
+
+/** A read's answer into a hook's state. A failure keeps what is shown
+ *  for these options, or for these options at an earlier time, with the
+ *  error; with nothing shown yet, the empty values. */
+function settle(state, key, shape, answer, empty) {
+  if (answer && answer.error === null) {
+    const { aborted, ...values } = answer;
+    return { ...values, key, shape, loading: false };
+  }
+  const why = { error: String(answer?.error ?? "the read failed") };
+  if (answer?.code) why.code = answer.code;
+  if (answer?.unavailable) why.unavailable = true;
+  if ((state.key === key || state.shape === shape) && !state.loading) {
+    const { code, unavailable, ...shown } = state;
+    return { ...shown, ...why, key };
+  }
+  return { key, shape, ...empty(), ...why, loading: false };
+}
+
+/**
+ * The hooks' one machine, for lib/data's five and lib/brain.js's four:
+ * `read(args)` is one of the reads above (it resolves, never throws, and
+ * takes a `signal`), `empty()` the values before the first answer, and
+ * `idle(opts)` true when there is nothing to ask (useRow with no id).
+ *
+ *   - `loading` is true until the first answer for these options, and
+ *     again when they change. A re-read keeps the last values, and
+ *     loading false, until the new ones land.
+ *   - Options are compared by value; a time in a bound to the minute.
+ *     When only such a time moved, the hook reads again as a re-read
+ *     does: the last values stay, loading false (above, keyOf).
+ *   - Every answer is a new array (a new object), even when the rows
+ *     are equal: the blocks' optimistic overrides wait for one.
+ *   - A read no longer needed is aborted: on unmount, when the options
+ *     change, when a newer read of the same hook starts.
+ *   - A failed re-read keeps the last values and sets `error`.
+ *   → { ...the read's values, error, loading, reload }
+ */
+export function useDoorRead(read, opts, { empty = () => ({}), idle } = {}) {
+  const key = keyOf(opts);
+  const shape = shapeOf(opts);
+  const still = Boolean(idle?.(opts ?? {}));
+  const blank = useMemo(() => ({ key, shape, ...empty(), error: null, loading: !still }), [key, shape, still]);
+  const [state, setState] = useState(blank);
+  const latest = useRef({ read, opts, empty });
+  latest.current = { read, opts, empty };
+  const own = useRef(null);
+
+  useEffect(() => {
+    if (still) return undefined;
+    let alive = true;
+    let flight = null;
+    const reader = (run) => {
+      // An answer still out may predate what changed: this read replaces it.
+      flight?.controller.abort();
+      const mine = { controller: new AbortController() };
+      flight = mine;
+      if (run) run.pending.add(mine);
+      const { read: readNow, opts: now, empty: emptyNow } = latest.current;
+      return Promise.resolve()
+        .then(() => readNow({ ...(now && typeof now === "object" ? now : {}), signal: mine.controller.signal }))
+        .catch((error) => ({ ...emptyNow(), error: String(error?.message ?? error), code: "failed" }))
+        .then((answer) => {
+          if (flight === mine) flight = null;
+          const wanted = alive && !mine.controller.signal.aborted && !answer?.aborted;
+          const handOut = wanted ? () => setState((s) => settle(s, key, shape, answer, emptyNow)) : null;
+          if (run) landed(run, mine, handOut);
+          else handOut?.();
+        });
+    };
+    const entry = { reread: reader };
+    readers.add(entry);
+    own.current = reader;
+    reader(null);
+    return () => {
+      alive = false;
+      readers.delete(entry);
+      if (own.current === reader) own.current = null;
+      flight?.controller.abort();
+    };
+  }, [key, shape, still]);
+
+  const reload = useCallback(() => (own.current ? own.current(null) : Promise.resolve()), []);
+  // New options show the empty values, loading, until they answer: useRow
+  // with a new id must never show the old record. Only a time that moved
+  // keeps what is shown, while the effect above reads again.
+  const current = state.key === key || (!still && state.shape === shape) ? state : blank;
+  const { key: _key, shape: _shape, ...shown } = current;
+  return { ...shown, reload };
+}
+
+const readOf = (name) => (args) => read(name, args);
+const idOf = (opts) => opts?.id === undefined || opts?.id === null || opts?.id === "";
+
+/** loadRows as a hook. → { rows, next, error, loading, reload } */
+export function useRows(opts) {
+  return useDoorRead(readOf("loadRows"), opts, { empty: READS.loadRows.empty });
+}
+
+/** loadRow as a hook; no id asks nothing and answers row: null.
+ *  → { row, error, loading, reload } */
+export function useRow(opts) {
+  return useDoorRead(readOf("loadRow"), opts, { empty: READS.loadRow.empty, idle: idOf });
+}
+
+/** countRows as a hook. → { count, error, loading, reload } */
+export function useCount(opts) {
+  return useDoorRead(readOf("countRows"), opts, { empty: READS.countRows.empty });
+}
+
+/** countBy as a hook. → { counts, error, loading, reload } */
+export function useCountBy(opts) {
+  return useDoorRead(readOf("countBy"), opts, { empty: READS.countBy.empty });
+}
+
+/** loadActivity as a hook. → { rows, error, loading, reload } */
+export function useActivity(opts) {
+  return useDoorRead(readOf("loadActivity"), opts, { empty: READS.loadActivity.empty });
+}