@tinvar/react 0.0.0-stage → 0.4.0

package/src/live.js

@@ -0,0 +1,977 @@
+// Live updates: the page on screen and its <Deferred> boundaries, fetched
+// again when something they read changes -- in another tab, for someone else.
+//
+// tinvar-spec.md, "Deferred components": "When an action revalidates a tag,
+// the client re-fetches any mounted fragment that read it, not the whole
+// page." The client that ran the action learns it from the action's
+// response (X-Invalidated-Tags). Every other client learns it here.
+//
+// What a render read comes with it as a live token (Tinvar\Live): signed by
+// the server, bound to the session, and naming the hub topics of the tags it
+// read -- a page's at the end of its document, in X-Live-Token, or beside
+// an action's re-render of it; a fragment's in X-Live-Token. This module
+// trades the tokens it holds at /_live/subscribe for the hub's access to
+// their topics, which the server puts in a cookie script cannot read, and
+// opens one stream on the hub for them. An update names a topic and a tag.
+// Whatever read the topic is fetched again:
+//
+//   - a <Deferred> boundary quietly, as refreshDeferred() fetches one -- no
+//     `reloading`, nothing dims, the content swapped when the new is ready,
+//     paced by the boundary's own backoff;
+//   - the page as a background reload, partial when only some segments'
+//     loaders read the tag, and re-rendering its #[Once] fields -- paced by
+//     the same floor and backoff a boundary has.
+//
+// Updates are gathered for a moment first, so a burst of writes is one
+// refetch. The stream reconnects with backoff, stops while the tab is hidden
+// -- and fetches everything once on return, since it heard nothing meanwhile
+// -- and is renewed before the hub's grant runs out, the session checked
+// again each time. A token the trade answers with null after running out
+// -- a tab hidden past its lifetime -- has what held it fetched again for a
+// new one, a channel's subscription asked for again. A 401 from the trade
+// ends the session on this client, with a full page load, as any 401 does
+// -- unless a document load has begun already, which it leaves to arrive
+// (document-load.js); so does any change of session the router sees, short
+// of the load.
+//
+// No React: the boundaries register through subscribeLive(), and the page
+// through the router's events.
+//
+// Channels (ADR 0069) ride the same stream. A subscription's token, which
+// /_channel/{name} hands out once the server has run the channel's checks,
+// registers through subscribeChannel() and is traded with the rest -- the
+// hub reads one cookie, so one trade grants every topic held -- and an
+// update naming a channel is a message for whoever subscribed to that
+// topic: delivered at once, never gathered, and never read as an
+// invalidation.
+
+import { bindingOf, revokeSession } from './router.js';
+import { csrfHeaders } from './csrf.js';
+import { reloadUnlessLoading } from './document-load.js';
+import { MAX_FAILURES, MIN_INTERVAL_MS } from './fragment-client.js';
+
+export const SUBSCRIBE_PATH = '/_live/subscribe';
+
+/** The id of the data block a document carries its live token in, at its end. */
+export const LIVE_BLOCK_ID = 'tinvar-live';
+
+/** How long updates are gathered before anything is fetched again. */
+export const DEBOUNCE_MS = 150;
+
+/** The longest a stream of updates can put a refetch off. */
+export const MAX_WAIT_MS = 1000;
+
+/** Backoff between reconnects: from this, doubling, to MAX_RECONNECT_MS. */
+export const RECONNECT_MS = 1000;
+export const MAX_RECONNECT_MS = 30000;
+
+/** A stream that stayed up this long was working: the backoff starts over. */
+export const STABLE_MS = 10000;
+
+/** How long before the hub's grant runs out the next one is asked for. */
+export const RENEW_BEFORE_MS = 30000;
+
+/** How long a trade is waited for before it is given up and tried again. */
+export const TRADE_TIMEOUT_MS = 15000;
+
+/** The server's cap on tokens in one trade. */
+export const MAX_TOKENS = 32;
+
+/** Page tokens kept across partial reloads, each naming what its segments read. */
+const MAX_PAGE_TOKENS = 8;
+
+/** The shape a token the server issued always has. */
+const TOKEN_SHAPE = /^v1\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+
+/** A topic, as the server names them. */
+const TOPIC_SHAPE = /^tinvar:[A-Za-z0-9_-]{22}$/;
+
+/** The page as a whole, as a segment: no partial reload will do. */
+const WHOLE = '*';
+
+/** A token's longest life from its first issue, and the least grant a trade hands out (TokenClaims, SubscribeEndpoint). */
+const MAX_LIFETIME_S = 86400;
+const MIN_GRANT_S = 30;
+
+/**
+ * How long a token is held before running out can be what its null means:
+ * one answered with null sooner -- its expiry past by a clock ahead of the
+ * server's, a renewal that brought a spent one -- is let go, so no page is
+ * fetched again and again for tokens the server will not answer.
+ */
+const MIN_HELD_MS = 60000;
+
+// ------------------------------------------------------------------ boundaries
+
+/**
+ * The boundaries listening, by what each holds: its live token, and how to
+ * fetch it again. Module-level, so a <Deferred> registers without a handle
+ * on the live instance -- there is one per page, made by the app's entry.
+ *
+ * @typedef {{ tokens: string[], refresh: () => void }} Entry
+ * @type {Set<Entry>}
+ */
+const boundaries = new Set();
+
+/**
+ * The channel subscriptions listening, each with its token and what to call
+ * with each message -- and, after a gap in the stream, what to tell it that
+ * messages may have been missed.
+ *
+ * @typedef {{
+ *   tokens: string[],
+ *   message: (message: unknown) => void,
+ *   gap?: () => void,
+ *   renew?: () => Promise<string | null>,
+ * }} ChannelEntry
+ * @type {Set<ChannelEntry>}
+ */
+const channels = new Set();
+
+/** @type {Set<() => void>} */
+const watchers = new Set();
+
+function changed() {
+  for (const watcher of watchers) watcher();
+}
+
+/**
+ * Listens for changes to what a boundary's render read: `refresh` is called
+ * when the server says one of its tags was invalidated. Returns the
+ * unsubscribe.
+ *
+ * @param {string | null | undefined} token the live token its load came with
+ * @param {() => void} refresh
+ * @returns {() => void}
+ */
+export function subscribeLive(token, refresh) {
+  if (typeof token !== 'string' || !TOKEN_SHAPE.test(token)) return () => {};
+  /** @type {Entry} */
+  const entry = { tokens: [token], refresh };
+  boundaries.add(entry);
+  changed();
+  return () => {
+    if (boundaries.delete(entry)) changed();
+  };
+}
+
+/**
+ * Listens to a channel with the token its subscription was answered with:
+ * `message` is called with each message published to it, and `gap` -- if
+ * given -- after the stream was down, when messages may have been missed;
+ * the hub keeps none to replay. `renew` -- if given -- asks for the
+ * subscription again when its token ran out unrenewed, as it does in a tab
+ * hidden past its lifetime, and answers with the new token or null; `gap`
+ * follows once the new one is listened to. Returns the unsubscribe.
+ *
+ * @param {string | null | undefined} token
+ * @param {(message: unknown) => void} message
+ * @param {() => void} [gap]
+ * @param {() => Promise<string | null>} [renew]
+ * @returns {() => void}
+ */
+export function subscribeChannel(token, message, gap, renew) {
+  if (typeof token !== 'string' || !TOKEN_SHAPE.test(token)) return () => {};
+  /** @type {ChannelEntry} */
+  const entry = { tokens: [token], message, gap, renew };
+  channels.add(entry);
+  changed();
+  return () => {
+    if (channels.delete(entry)) changed();
+  };
+}
+
+// ---------------------------------------------------------------------- tokens
+
+/**
+ * The live token a document carries: the LAST block with the id, which the
+ * server writes after everything the page rendered, so no block in page
+ * content can stand in for it. Null when there is none, or it says none.
+ *
+ * @param {Document} [doc]
+ * @returns {string | null}
+ */
+export function readLiveToken(doc = globalThis.document) {
+  if (typeof doc?.querySelectorAll !== 'function') return null;
+  const blocks = doc.querySelectorAll(`script[type="application/json"]#${LIVE_BLOCK_ID}`);
+  const element = blocks[blocks.length - 1];
+  if (!element) return null;
+  try {
+    const token = JSON.parse(element.textContent ?? '')?.token;
+    return typeof token === 'string' && TOKEN_SHAPE.test(token) ? token : null;
+  } catch {
+    return null;
+  }
+}
+
+/** @type {Map<string, Map<string, string[]>>} */
+const decoded = new Map();
+
+/**
+ * The topics a live token names, each with the segments that read it. Read
+ * without verifying -- the payload is plain base64url JSON, and nothing here
+ * trusts it: it says which updates concern what this client holds, while the
+ * server decides what the client may hear.
+ *
+ * @param {string} token
+ * @returns {Map<string, string[]>}
+ */
+export function topicsOf(token) {
+  const known = decoded.get(token);
+  if (known) return known;
+
+  /** @type {Map<string, string[]>} */
+  const topics = new Map();
+  try {
+    const body = token.split('.')[1] ?? '';
+    const claims = JSON.parse(atob(body.replace(/-/g, '+').replace(/_/g, '/')));
+    // A channel token names its one topic under `c`.
+    if (typeof claims?.c === 'string' && TOPIC_SHAPE.test(claims.c)) topics.set(claims.c, []);
+    for (const [topic, segments] of Object.entries(claims?.t ?? {})) {
+      if (!TOPIC_SHAPE.test(topic) || !Array.isArray(segments)) continue;
+      topics.set(
+        topic,
+        segments.filter((s) => typeof s === 'string'),
+      );
+    }
+  } catch {
+    // Not a shape this understands: it names nothing.
+  }
+
+  // Bounded: tokens are refreshed every few minutes, each a new string.
+  if (decoded.size >= 256) decoded.delete(decoded.keys().next().value);
+  decoded.set(token, topics);
+  return topics;
+}
+
+/**
+ * Whether a token the server answered with null had run out of time -- its
+ * expiry passed, or its lifetime from first issue all but spent -- rather
+ * than been refused: what held it is fetched again, for a token that will
+ * be answered. Read unverified, as topicsOf() reads; one refused for any
+ * other reason is let go, since fetching it again would be refused again.
+ *
+ * @param {string} token
+ * @param {number} nowMs
+ */
+function outOfTime(token, nowMs) {
+  try {
+    const body = token.split('.')[1] ?? '';
+    const claims = JSON.parse(atob(body.replace(/-/g, '+').replace(/_/g, '/')));
+    const at = nowMs / 1000;
+    if (typeof claims?.e !== 'number') return false;
+    return claims.e <= at || (typeof claims.i === 'number' && claims.i + MAX_LIFETIME_S - MIN_GRANT_S <= at);
+  } catch {
+    return false;
+  }
+}
+
+// ------------------------------------------------------------------------ live
+
+/**
+ * Starts listening for the page's router: the first page's token from the
+ * document, each later page's from the router's `success` events, and every
+ * boundary's as it registers.
+ *
+ * @param {{
+ *   router: Pick<import('./router.js').Router, 'on' | 'reload' | 'routeTokens' | 'flushByCacheTags' | 'revoke'>,
+ *   fetch?: typeof fetch,
+ *   document?: Document,
+ *   hardNavigate?: (url: string) => void,
+ *   now?: () => number,
+ *   random?: () => number,
+ *   initialToken?: string | null,
+ * }} options
+ */
+export function createLive({
+  router,
+  fetch: fetchImpl = globalThis.fetch?.bind(globalThis),
+  document: doc = globalThis.document,
+  hardNavigate,
+  now = () => Date.now(),
+  random = Math.random,
+  initialToken,
+}) {
+  let running = false;
+  let paused = false;
+
+  /** The page's tokens: its render's, and its partial reloads'. */
+  let page = /** @type {string[]} */ ([]);
+
+  /** Whose session the tokens are for, as the router's route token says. */
+  let binding = /** @type {string | null} */ (null);
+
+  /**
+   * A stream on the hub, and -- until it is answered -- the one it replaces,
+   * still listened to so a renewal leaves no gap. Whatever ends the new one
+   * ends that one too: a stream nothing tracks would deliver beside the next.
+   *
+   * @typedef {{ controller: AbortController, key: string, startedAt: number, previous: Connection | null }} Connection
+   */
+  /** @type {Connection | null} */
+  let conn = null;
+  let trading = false;
+  /** The trade in flight: given up at its deadline, or when live stops. */
+  let tradeController = /** @type {AbortController | null} */ (null);
+  let tradeAgain = false;
+  /** Trade at the next sync even for the topics already granted: the binding moved. */
+  let rebound = false;
+  let attempts = 0;
+  /** A stretch without a stream: whatever happened in it was not heard. */
+  let missed = false;
+  /**
+   * Fetched again already, for a token that ran out, since the last stream
+   * opened: the catch-up after the gap leaves them be.
+   */
+  let refetched = { page: false, entries: /** @type {Set<Entry>} */ (new Set()) };
+  /** When each token was first held, by this client's clock. */
+  const firstHeld = /** @type {Map<string, number>} */ (new Map());
+  /** Channels renewed after a token ran out, told of the gap once the next stream opens. */
+  const gapOwed = /** @type {Set<ChannelEntry>} */ (new Set());
+
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let syncTimer = null;
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let retryTimer = null;
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let renewTimer = null;
+  /**
+   * Forgets the reload an ended session waits to make while a document load
+   * begun is under way (ended()). Not called by stop(): the session has
+   * ended whatever stops listening after it.
+   */
+  let stopReload = () => {};
+
+  /** Updates heard and not yet acted on. */
+  let pending = {
+    tags: /** @type {Set<string>} */ (new Set()),
+    segments: /** @type {Set<string>} */ (new Set()),
+    entries: /** @type {Set<Entry>} */ (new Set()),
+  };
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let flushTimer = null;
+  let firstHeard = 0;
+
+  /** The page's own refetches, paced as a boundary's are. */
+  const pageRefresh = {
+    inFlight: false,
+    /** @type {Set<string> | null} */
+    wanted: null,
+    failures: 0,
+    notBefore: 0,
+    /** @type {ReturnType<typeof setTimeout> | null} */
+    timer: null,
+  };
+
+  const offs = /** @type {(() => void)[]} */ ([]);
+
+  const hidden = () => doc?.visibilityState === 'hidden';
+
+  /** Every token held, each with whoever holds it -- a group's members share one. */
+  function held() {
+    /** @type {Map<string, { holders: Array<{ list: string[], index: number }> }>} */
+    const tokens = new Map();
+    const add = (/** @type {string[]} */ list) =>
+      list.forEach((token, index) => {
+        const known = tokens.get(token) ?? { holders: [] };
+        known.holders.push({ list, index });
+        tokens.set(token, known);
+      });
+    add(page);
+    for (const entry of boundaries) add(entry.tokens);
+    for (const entry of channels) add(entry.tokens);
+    const at = now();
+    for (const [token] of tokens) {
+      if (firstHeld.has(token)) continue;
+      // Bounded: tokens are refreshed every few minutes, each a new string.
+      if (firstHeld.size >= 256) firstHeld.delete(firstHeld.keys().next().value);
+      firstHeld.set(token, at);
+    }
+    // Within the server's cap: the page's first, which it was given first.
+    return [...tokens].slice(0, MAX_TOKENS);
+  }
+
+  /** @param {Iterable<string>} topics */
+  function keyOf(topics) {
+    return [...topics].sort().join(' ');
+  }
+
+  function wantedKey() {
+    const topics = new Set();
+    for (const [token] of held()) for (const topic of topicsOf(token).keys()) topics.add(topic);
+    return keyOf(topics);
+  }
+
+  function sync(delay = 50) {
+    if (!running || paused) return;
+    if (syncTimer !== null) clearTimeout(syncTimer);
+    syncTimer = setTimeout(() => {
+      syncTimer = null;
+      if (!running || paused) return;
+      const key = wantedKey();
+      if (key === '' || binding === null) return close();
+      if (conn !== null && conn.key === key && !rebound) return;
+      void trade();
+    }, delay);
+  }
+
+  /**
+   * Trades the tokens held for the hub's access to their topics, takes each
+   * one back refreshed, and opens a stream for what was granted.
+   */
+  async function trade() {
+    if (trading) {
+      tradeAgain = true;
+      return;
+    }
+    trading = true;
+    rebound = false;
+    if (retryTimer !== null) clearTimeout(retryTimer);
+    retryTimer = null;
+
+    try {
+      const tokens = held();
+      if (tokens.length === 0 || !fetchImpl) return close();
+
+      let response;
+      let text;
+      const controller = new AbortController();
+      tradeController = controller;
+      const deadline = setTimeout(() => controller.abort(), TRADE_TIMEOUT_MS);
+      try {
+        response = await fetchImpl(SUBSCRIBE_PATH, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', accept: 'application/json', ...csrfHeaders(doc) },
+          body: JSON.stringify({ tokens: tokens.map(([token]) => token) }),
+          credentials: 'same-origin',
+          mode: 'same-origin',
+          redirect: 'error',
+          cache: 'no-store',
+          signal: controller.signal,
+        });
+        // Read whole within the deadline too: an answer that stops halfway
+        // holds the trade as one that never came does.
+        text = await response.text();
+      } catch {
+        if (running) retry();
+        return;
+      } finally {
+        clearTimeout(deadline);
+        if (tradeController === controller) tradeController = null;
+      }
+      if (!running || paused) return;
+
+      // "Session revocation, which the server signals with a 401" -- a
+      // sign-out in another tab, a role change: this page belongs to a
+      // session that has ended.
+      if (response.status === 401) return ended();
+      if (!response.ok) return retry();
+
+      let body;
+      try {
+        body = JSON.parse(text);
+      } catch {
+        return retry();
+      }
+
+      // Refreshed in place, so the next trade sends the newest; a token
+      // answered with null is spent -- out of lifetime, or of a build no
+      // longer answered for -- and what held it listens no longer.
+      const refreshed = Array.isArray(body?.tokens) ? body.tokens : [];
+      const valid = (/** @type {unknown} */ t) => typeof t === 'string' && TOKEN_SHAPE.test(t);
+      // A token that ran out -- a tab hidden past its lifetime, a backoff
+      // that long -- is no refusal: what held it is fetched again, as the
+      // catch-up after a gap would, and that brings a token the next trade
+      // is answered for.
+      const stale = new Set(
+        tokens
+          .filter(
+            ([token], i) =>
+              !valid(refreshed[i]) &&
+              outOfTime(token, now()) &&
+              now() - (firstHeld.get(token) ?? now()) >= MIN_HELD_MS,
+          )
+          .map(([token]) => token),
+      );
+      const pageStale = page.some((token) => stale.has(token));
+      const entriesStale = [...boundaries].filter((entry) => entry.tokens.some((token) => stale.has(token)));
+      const channelsStale = [...channels].filter((entry) => entry.tokens.some((token) => stale.has(token)));
+      tokens.forEach(([, { holders }], i) => {
+        const next = refreshed[i];
+        for (const { list, index } of holders) {
+          list[index] = typeof next === 'string' && TOKEN_SHAPE.test(next) ? next : '';
+        }
+      });
+      page = page.filter((token) => token !== '');
+      for (const entry of boundaries) entry.tokens = entry.tokens.filter((token) => token !== '');
+      for (const entry of channels) entry.tokens = entry.tokens.filter((token) => token !== '');
+
+      if (pageStale && page.length === 0) {
+        refetched.page = true;
+        refreshPage([WHOLE]);
+      }
+      for (const entry of entriesStale) {
+        if (entry.tokens.length > 0) continue;
+        refetched.entries.add(entry);
+        entry.refresh();
+      }
+      for (const entry of channelsStale) if (entry.tokens.length === 0) renewChannel(entry);
+
+      const topics = Array.isArray(body?.topics) ? body.topics.filter((t) => typeof t === 'string') : [];
+      const url = typeof body?.url === 'string' ? body.url : null;
+      // Same-origin and a path: the stream is opened with this session's
+      // cookies, so never somewhere the answer merely names.
+      if (topics.length === 0 || url === null || !/^\/(?!\/)/.test(url)) return close();
+
+      open(url, keyOf(topics), typeof body.expiresAt === 'number' ? body.expiresAt : null);
+    } finally {
+      trading = false;
+      if (tradeAgain) {
+        tradeAgain = false;
+        sync(0);
+      }
+    }
+  }
+
+  /**
+   * Asks for a channel's subscription again, its token run out: the new
+   * token is traded at the next sync, and the subscriber told of the gap
+   * once a stream carries it.
+   *
+   * @param {ChannelEntry} entry
+   */
+  function renewChannel(entry) {
+    if (!entry.renew) return;
+    entry.renew().then(
+      (token) => {
+        if (!running || !channels.has(entry) || typeof token !== 'string' || !TOKEN_SHAPE.test(token)) return;
+        entry.tokens = [token];
+        gapOwed.add(entry);
+        changed();
+      },
+      () => {},
+    );
+  }
+
+  /**
+   * Opens a stream on the hub. One already open is closed only once this
+   * one is answered, so a renewal leaves no gap for an update to fall in.
+   *
+   * @param {string} url
+   * @param {string} key
+   * @param {number | null} expiresAt the grant's end, in seconds
+   */
+  function open(url, key, expiresAt) {
+    // The stream still delivering: the current one, or -- while that is
+    // unanswered, and so superseded unheard -- the one it was replacing.
+    let previous = conn;
+    if (conn !== null && conn.previous !== null) {
+      previous = conn.previous;
+      conn.previous = null;
+      conn.controller.abort();
+    }
+    /** @type {Connection} */
+    const next = { controller: new AbortController(), key, startedAt: now(), previous };
+    conn = next;
+
+    if (renewTimer !== null) clearTimeout(renewTimer);
+    renewTimer = null;
+    if (expiresAt !== null) {
+      const due = expiresAt * 1000 - RENEW_BEFORE_MS - now();
+      renewTimer = setTimeout(
+        () => {
+          renewTimer = null;
+          if (running && !paused) void trade();
+        },
+        Math.max(MIN_INTERVAL_MS, due),
+      );
+    }
+
+    void read(next, url);
+  }
+
+  /**
+   * @param {Connection} c
+   * @param {string} url
+   */
+  async function read(c, url) {
+    const { signal } = c.controller;
+    let response;
+    try {
+      response = await fetchImpl(url, {
+        method: 'GET',
+        headers: { accept: 'text/event-stream' },
+        credentials: 'same-origin',
+        mode: 'same-origin',
+        redirect: 'error',
+        cache: 'no-store',
+        signal,
+      });
+    } catch {
+      if (!signal.aborted) lost(c);
+      return;
+    }
+
+    if (signal.aborted || c !== conn) {
+      void response.body?.cancel().catch(() => {});
+      return;
+    }
+
+    // The hub refused the grant -- run out, or a cookie that never landed.
+    // Traded again, after the backoff.
+    if (!response.ok || !response.body) {
+      void response.body?.cancel().catch(() => {});
+      return lost(c);
+    }
+
+    if (c.previous !== null) {
+      c.previous.controller.abort();
+      c.previous = null;
+    }
+
+    // Nothing was heard while there was no stream: whatever this client
+    // holds may have changed meanwhile, so all of it is fetched again, once.
+    if (missed) {
+      missed = false;
+      catchUp();
+    }
+    refetched = { page: false, entries: new Set() };
+    for (const entry of gapOwed) {
+      if (!channels.has(entry)) gapOwed.delete(entry);
+      else if (entry.tokens.length > 0) {
+        gapOwed.delete(entry);
+        entry.gap?.();
+      }
+    }
+
+    const reader = response.body.getReader();
+    const text = new TextDecoder();
+    let buffer = '';
+    try {
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += text.decode(value, { stream: true });
+        let end;
+        while ((end = buffer.search(/\r?\n\r?\n/)) !== -1) {
+          const event = buffer.slice(0, end);
+          buffer = buffer.slice(end).replace(/^\r?\n\r?\n/, '');
+          const data = event
+            .split(/\r?\n/)
+            .filter((line) => line.startsWith('data:'))
+            .map((line) => line.slice(5).replace(/^ /, ''))
+            .join('\n');
+          // Only while it is the stream listened to: one superseded, or
+          // left over from a stop(), delivers nothing.
+          if (data !== '' && running && (c === conn || c === conn?.previous)) heard(data);
+        }
+      }
+    } catch {
+      // Torn down -- aborted, or the connection dropped.
+    }
+
+    if (signal.aborted || c !== conn) return;
+
+    // The hub closed it: the grant ran out before a renewal opened another,
+    // or the hub restarted. A stream that was up for a while was working,
+    // so the backoff starts over.
+    if (now() - c.startedAt >= STABLE_MS) attempts = 0;
+    lost(c);
+  }
+
+  /** @param {Connection} c */
+  function lost(c) {
+    if (c !== conn) return;
+    // The stream it was replacing goes with it: the retry opens one afresh,
+    // and catches up on the gap.
+    c.previous?.controller.abort();
+    c.previous = null;
+    conn = null;
+    missed = true;
+    retry();
+  }
+
+  /** The next trade, after a backoff with jitter: a hub that restarted is not met by every tab at once. */
+  function retry() {
+    if (!running || paused) return;
+    attempts++;
+    const ceiling = Math.min(MAX_RECONNECT_MS, RECONNECT_MS * 2 ** (attempts - 1));
+    const delay = ceiling / 2 + (random() * ceiling) / 2;
+    if (retryTimer !== null) clearTimeout(retryTimer);
+    retryTimer = setTimeout(() => {
+      retryTimer = null;
+      if (running && !paused) void trade();
+    }, delay);
+  }
+
+  /** Stops listening, and keeps what is held. */
+  function close() {
+    if (renewTimer !== null) clearTimeout(renewTimer);
+    if (retryTimer !== null) clearTimeout(retryTimer);
+    renewTimer = null;
+    retryTimer = null;
+    conn?.previous?.controller.abort();
+    conn?.controller.abort();
+    conn = null;
+  }
+
+  /** @param {string} data */
+  function heard(data) {
+    let update;
+    try {
+      update = JSON.parse(data);
+    } catch {
+      return;
+    }
+    const topic = update?.topic;
+    if (typeof topic !== 'string') return;
+
+    // A channel's message, for its subscribers alone, as it came: what the
+    // server encoded, from a Data object, to a topic only a trade that ran
+    // the channel's checks granted.
+    if (typeof update.channel === 'string') {
+      for (const entry of channels) {
+        if (!entry.tokens.some((token) => topicsOf(token).has(topic))) continue;
+        try {
+          entry.message(update.message);
+        } catch (error) {
+          // One subscriber's failure is not the stream's.
+          globalThis.reportError?.(error);
+        }
+      }
+      return;
+    }
+
+    let concerned = false;
+    for (const token of page) {
+      const segments = topicsOf(token).get(topic);
+      if (!segments) continue;
+      concerned = true;
+      for (const segment of segments) pending.segments.add(segment);
+    }
+    for (const entry of boundaries) {
+      if (entry.tokens.some((token) => topicsOf(token).has(topic))) {
+        concerned = true;
+        pending.entries.add(entry);
+      }
+    }
+    if (!concerned) return;
+    if (typeof update.tag === 'string' && update.tag !== '') pending.tags.add(update.tag);
+
+    // Gathered: a burst of writes is one refetch, put off no longer than
+    // MAX_WAIT_MS however long the burst.
+    const at = now();
+    if (flushTimer === null) firstHeard = at;
+    else clearTimeout(flushTimer);
+    flushTimer = setTimeout(flush, Math.max(0, Math.min(DEBOUNCE_MS, firstHeard + MAX_WAIT_MS - at)));
+  }
+
+  function flush() {
+    flushTimer = null;
+    const { tags, segments, entries } = pending;
+    pending = { tags: new Set(), segments: new Set(), entries: new Set() };
+    if (!running) return;
+
+    // What the client keeps under the tags goes, as it would on reading
+    // X-Invalidated-Tags: prefetched pages, and #[Once] content no longer
+    // claimed.
+    if (tags.size > 0) router.flushByCacheTags([...tags]);
+    for (const entry of entries) if (boundaries.has(entry)) entry.refresh();
+    if (segments.size > 0) refreshPage(segments);
+  }
+
+  /** Everything held, fetched again: what a gap in the stream may have hidden. */
+  function catchUp() {
+    if (page.length > 0 && !refetched.page) refreshPage([WHOLE]);
+    for (const entry of boundaries)
+      if (entry.tokens.length > 0 && !refetched.entries.has(entry)) entry.refresh();
+    for (const entry of channels) {
+      if (entry.tokens.length === 0) continue;
+      gapOwed.delete(entry);
+      entry.gap?.();
+    }
+  }
+
+  /** @param {Iterable<string>} segments */
+  function refreshPage(segments) {
+    const wanted = (pageRefresh.wanted ??= new Set());
+    for (const segment of segments) wanted.add(segment);
+    pumpPage();
+  }
+
+  function pumpPage() {
+    const s = pageRefresh;
+    if (!running || s.inFlight || s.timer !== null || s.wanted === null) return;
+    const wait = s.notBefore - now();
+    if (wait <= 0) void runPageRefresh();
+    else s.timer = setTimeout(runPageRefresh, wait);
+  }
+
+  async function runPageRefresh() {
+    const s = pageRefresh;
+    s.timer = null;
+    if (!running || s.wanted === null) return;
+    const segments = s.wanted;
+    s.wanted = null;
+    s.inFlight = true;
+
+    /** @type {import('./router.js').VisitOptions} */
+    const options = { background: true, refreshOnce: true };
+    // Only the segments whose loaders read it, when that is all that did;
+    // a server not answering partial reloads renders the page whole.
+    if (!segments.has(WHOLE)) options.only = [...segments];
+
+    let mounted = false;
+    try {
+      mounted = (await router.reload(options)) === true;
+    } catch {
+      mounted = false;
+    }
+    s.inFlight = false;
+
+    if (mounted) {
+      s.failures = 0;
+      s.notBefore = now() + MIN_INTERVAL_MS;
+    } else {
+      // Not mounted: failed, or not sent while a visit was under way. Asked
+      // again with the boundaries' backoff, until it has failed as often
+      // as a boundary may.
+      s.failures++;
+      s.notBefore = now() + MIN_INTERVAL_MS * 2 ** s.failures;
+      if (s.failures < MAX_FAILURES) refreshPage(segments);
+      else s.failures = 0;
+    }
+    pumpPage();
+  }
+
+  /** The session ended: what is held goes, and the page is loaded again. */
+  function ended() {
+    // Every token held goes -- the page's, each boundary's and channel's --
+    // here rather than through the router's 'revoke', whose listener the
+    // stop below takes away.
+    purge();
+    // This client's own stop: a bare stop() here is the window's, which
+    // aborts the document's navigation and every fetch it has under way.
+    halt();
+    // Wiped first, as a fragment's 401 does: the reload alone left
+    // remembered drafts in the tab's storage for the next page to read.
+    revokeSession(router);
+    // Loaded again -- unless a document load has begun, which is the page
+    // being replaced already: an action that replaced the session and sent
+    // the browser on. It is left to arrive (document-load.js).
+    stopReload();
+    stopReload = reloadUnlessLoading(hardNavigate ?? ((u) => globalThis.location.assign(u)));
+  }
+
+  /** Everything held for the session, gone: client-held data. */
+  function purge() {
+    close();
+    page = [];
+    for (const entry of boundaries) entry.tokens = [];
+    for (const entry of channels) entry.tokens = [];
+    pending = { tags: new Set(), segments: new Set(), entries: new Set() };
+    if (flushTimer !== null) clearTimeout(flushTimer);
+    flushTimer = null;
+    missed = false;
+    refetched = { page: false, entries: new Set() };
+    gapOwed.clear();
+  }
+
+  function onVisibility() {
+    if (!running) return;
+    if (hidden()) {
+      // Paused: no stream held open for a tab nobody is looking at.
+      paused = true;
+      close();
+      return;
+    }
+    if (!paused) return;
+    paused = false;
+    // It heard nothing while away.
+    missed = wantedKey() !== '';
+    attempts = 0;
+    sync(0);
+  }
+
+  /** @param {CustomEvent} event */
+  function onSuccess(event) {
+    const detail = event?.detail ?? {};
+    // A page mounted with nothing said of its live token -- an action's
+    // re-render from a server that minted none -- says nothing about what
+    // the page reads; the tokens held stand.
+    if (!('liveToken' in detail)) return;
+
+    const current = bindingOf(router.routeTokens()[0] ?? null);
+    if (current !== binding) {
+      // Another session's page: what was held for the last one goes.
+      purge();
+      binding = current;
+    }
+
+    const token =
+      typeof detail.liveToken === 'string' && TOKEN_SHAPE.test(detail.liveToken) ? detail.liveToken : null;
+
+    // Drawn under another binding than the tokens held, with the route
+    // token kept: an action moved the user's auth epoch -- a role change --
+    // and re-rendered the page in place. The grant open is for the session
+    // as it was, so it is traded again at once, whether or not the topics
+    // differ: the server refuses with a 401 any token held from before the
+    // change, which ends the session here as any binding change does, and
+    // otherwise grants the new token's topics under the binding as it is.
+    if (token !== null && page.length > 0 && bindingOf(token) !== bindingOf(page[0])) rebound = true;
+
+    if (detail.partial) {
+      if (token !== null && !page.includes(token)) page = [...page, token].slice(-MAX_PAGE_TOKENS);
+    } else {
+      page = token === null ? [] : [token];
+    }
+    sync();
+  }
+
+  /** Stops listening: the stream closed, nothing more traded, the router's events let go of. */
+  function halt() {
+    if (!running) return;
+    running = false;
+    tradeController?.abort();
+    close();
+    for (const off of offs.splice(0)) off();
+    for (const timer of [syncTimer, flushTimer, pageRefresh.timer]) if (timer !== null) clearTimeout(timer);
+    syncTimer = null;
+    flushTimer = null;
+    pageRefresh.timer = null;
+  }
+
+  return {
+    start() {
+      if (running) return;
+      running = true;
+      paused = hidden();
+      binding = bindingOf(router.routeTokens()[0] ?? null);
+      const first = initialToken === undefined ? readLiveToken(doc) : initialToken;
+      page = typeof first === 'string' && TOKEN_SHAPE.test(first) ? [first] : [];
+      offs.push(router.on('success', onSuccess));
+      offs.push(router.on('revoke', purge));
+      offs.push(router.on('clearHistory', purge));
+      const watcher = () => sync();
+      watchers.add(watcher);
+      offs.push(() => watchers.delete(watcher));
+      doc?.addEventListener?.('visibilitychange', onVisibility);
+      offs.push(() => doc?.removeEventListener?.('visibilitychange', onVisibility));
+      sync(0);
+    },
+
+    stop: halt,
+
+    purge,
+
+    /** Whether a stream is open on the hub. */
+    get connected() {
+      return conn !== null;
+    },
+
+    /** The topics the open stream was granted, space-separated. */
+    get listening() {
+      return conn?.key ?? '';
+    },
+  };
+}