@ultimat3/render 29.4.0 → 30.1.0

package/src/modes.ts

@@ -33,8 +33,6 @@ export interface ModeSpec {
   readonly prerenderable: boolean;
   /** Does the mode need a revalidation trigger (tags or TTL)? */
   readonly needsRevalidate: boolean;
-  /** Does the mode need at least one `<Suspense>` boundary to mean anything? */
-  readonly needsSuspense: boolean;
   readonly description: string;
 }
 
@@ -46,7 +44,6 @@ export const MODE_SPECS = Object.freeze<Record<RenderMode, ModeSpec>>({
     perRequestState: false,
     prerenderable: true,
     needsRevalidate: false,
-    needsSuspense: false,
     description: 'built once, served as a file',
   },
   isr: {
@@ -54,7 +51,6 @@ export const MODE_SPECS = Object.freeze<Record<RenderMode, ModeSpec>>({
     perRequestState: false,
     prerenderable: true,
     needsRevalidate: true,
-    needsSuspense: false,
     description: 'static + background regen on tag/TTL',
   },
   ssr: {
@@ -62,7 +58,6 @@ export const MODE_SPECS = Object.freeze<Record<RenderMode, ModeSpec>>({
     perRequestState: true,
     prerenderable: false,
     needsRevalidate: false,
-    needsSuspense: false,
     description: 'per-request full render',
   },
   stream: {
@@ -70,7 +65,6 @@ export const MODE_SPECS = Object.freeze<Record<RenderMode, ModeSpec>>({
     perRequestState: true,
     prerenderable: false,
     needsRevalidate: false,
-    needsSuspense: true,
     description: 'static shell flushed instantly, holes streamed',
   },
 });
@@ -114,10 +108,10 @@ export function assertModeShape(config: RouteShape): void {
   }
 
   // isr: a CACHED document, so it may not be gated. The symmetry with `static` above is the
-  // point — an ISR route resolves `load` with the request's own `Ctx`, renders that actor's
-  // document, and the cache stores it under the pathname alone. Every later actor who passes the
-  // same policy is then served the first actor's HTML. Keying the cache on more is a trap, not a
-  // fix: the key would have to enumerate everything a policy and a `load` can read.
+  // point — both are rendered as NOBODY (`@ultimat3/http`'s `withAnonymousRequest`: no actor, no
+  // cookie, no `Authorization`), so `load` cannot put one visitor's answer in a stored page, and a
+  // policy would have no one to ask about. Keying the cache on more is a trap, not a fix: the key
+  // would have to enumerate everything a policy and a `load` can read. Per-visitor means `ssr`.
   if (config.render === 'isr' && config.policy !== undefined) {
     throw new RouteModeInvalidError(
       "render: 'isr' caches one document per URL and cannot be gated, but a `policy` was " +
@@ -182,8 +176,6 @@ export interface ModeCheckContext {
   readonly file: string;
   readonly path: string;
   readonly surface: RouteSurface;
-  /** Counted from the route module's JSX by the build. `stream` needs at least one. */
-  readonly suspenseBoundaries: number;
 }
 
 /** Checks that need the surrounding module and surface. Called by `registerRoute`. */
@@ -218,15 +210,6 @@ export function assertModeInvariants(config: RouteShape, ctx: ModeCheckContext):
     );
   }
 
-  if (config.render === 'stream' && ctx.suspenseBoundaries < 1) {
-    throw new RouteModeInvalidError(
-      `${ctx.file} declares render: 'stream' but has no <Suspense> boundary, so there is ` +
-        'nothing to stream — the whole page waits like ssr',
-      `wrap the data-dependent part of ${ctx.file} in <Suspense fallback={…}> ` +
-        "or change render to 'ssr'",
-    );
-  }
-
   if (config.prerender !== undefined && !MODE_SPECS[config.render].prerenderable) {
     throw new RouteModeInvalidError(
       `${ctx.file} declares prerender with render: '${config.render}', which is not prerenderable`,

package/src/module-loader.ts

@@ -205,7 +205,7 @@ export function clearStylesheets(): void {
  * THE ORDER IS A FUNCTION OF THE SHEETS, NEVER OF THEIR ARRIVAL (22.3.5). A sheet registers in Bun's
  * `onLoad`, which runs as the loader fetches a module's dependencies — in parallel — and an island
  * build's too: the arrival order differed on every boot of one image, and so did the joined bytes
- * and the `/styles/<hash>.css` minted from them (notificado.co, 22.3.2–22.3.4: two pods, two URLs,
+ * and the `/styles/<hash>.css` minted from them (one adopter, 22.3.2–22.3.4: two pods, two URLs,
  * each the other's 404). `stylesheetOrder` is the whole rule:
  *
  * | key | first | why |

package/src/navigation-api.ts

@@ -54,7 +54,7 @@ export function refresh(): Promise<void> {
     win.location.reload();
     return Promise.resolve();
   }
-  return win.__xNavigation.refresh();
+  return win.__xNavigation.refresh().then(() => undefined);
 }
 
 /**

package/src/navigation-deadline.ts

@@ -0,0 +1,36 @@
+/**
+ * The bound on a navigation's wait for its answer. A fetch has no timeout of its own, and one that
+ * never settles held the router's `inflight` forever: every later `refresh()` yielded to it.
+ */
+
+/** Longest a navigation waits for its answer — a held prefetch's included — before giving up. */
+export const NAVIGATION_TIMEOUT_MS = 30_000;
+
+/** What the bound reads of the window: its timers, injected by the tests. */
+type Timers = Pick<Window, 'setTimeout' | 'clearTimeout'>;
+
+/**
+ * `ask(signal)`, raced against the deadline. `signal` aborts with `mine` (a newer navigation) or at
+ * the deadline, so the request is dropped either way; only a deadline REJECTS, with the abort's own
+ * reason, and `mine` stays un-aborted — the caller fails it like any network failure, never silently.
+ */
+export function withinDeadline<T>(
+  win: Timers,
+  mine: AbortSignal,
+  ask: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+  const timed = new AbortController();
+  let timer: number | undefined;
+  const expired = new Promise<never>((_, reject) => {
+    timer = win.setTimeout(() => {
+      timed.abort();
+      reject(timed.signal.reason);
+    }, NAVIGATION_TIMEOUT_MS);
+  });
+  // The race, not the signal alone: a held prefetch the click reuses was fetched with no signal.
+  // `ask` runs inside a promise so a synchronous throw rejects through the race, and its `finally`
+  // clears the timer — thrown before it, `expired` would reject later with nobody listening.
+  // (`Promise.try`, once the lib target types it.)
+  const answer = new Promise<T>((resolve) => resolve(ask(AbortSignal.any([mine, timed.signal]))));
+  return Promise.race([answer, expired]).finally(() => win.clearTimeout(timer));
+}

package/src/navigation-dom.ts

@@ -169,6 +169,67 @@ export function focusMain(doc: Document): void {
   target.focus({ preventScroll: true });
 }
 
+/**
+ * Where focus was, said in terms the NEXT document can answer: the control's `id`, else its `name`
+ * in the same form, else its row (`[data-row]`) with its tag and place in that row. `null` when
+ * nothing had focus — the body, or no element at all.
+ */
+export interface FocusMark {
+  readonly id: string;
+  readonly name: string | null;
+  /** The form's `id`, else its place among the document's forms; `null` outside a form. */
+  readonly form: string | number | null;
+  readonly row: string | null;
+  readonly tag: string;
+  readonly nth: number;
+}
+
+export function markFocus(doc: Document): FocusMark | null {
+  const el = doc.activeElement;
+  if (el === null || el === doc.body || el === doc.documentElement) return null;
+  const form = el.closest('form');
+  const rowEl = el.closest('[data-row]');
+  const tag = el.tagName.toLowerCase();
+  return {
+    id: el.id,
+    name: el.getAttribute('name'),
+    form: form === null ? null : form.id || [...doc.querySelectorAll('form')].indexOf(form),
+    row: rowEl?.getAttribute('data-row') ?? null,
+    tag,
+    nth: rowEl === null ? -1 : [...rowEl.querySelectorAll(tag)].indexOf(el),
+  };
+}
+
+/** Focus the control `mark` names in the document now on screen, else `<main>`. No mark: nothing. */
+export function restoreFocus(doc: Document, mark: FocusMark | null): void {
+  if (mark === null) return;
+  const target = markedIn(doc, mark);
+  if (target === null) focusMain(doc);
+  else target.focus({ preventScroll: true });
+}
+
+function markedIn(doc: Document, mark: FocusMark): HTMLElement | null {
+  if (mark.id !== '') return doc.getElementById(mark.id);
+  // Attribute VALUES compared as strings, never spliced into a selector: a name needs no escaping.
+  const by = (scope: ParentNode, attr: string, value: string): HTMLElement | null =>
+    [...scope.querySelectorAll<HTMLElement>(`[${attr}]`)].find(
+      (el) => el.getAttribute(attr) === value,
+    ) ?? null;
+  if (mark.name !== null) {
+    const forms = [...doc.querySelectorAll('form')];
+    const form =
+      mark.form === null
+        ? doc
+        : typeof mark.form === 'number'
+          ? forms[mark.form]
+          : forms.find((f) => f.id === mark.form);
+    return form === undefined ? null : by(form, 'name', mark.name);
+  }
+  if (mark.row === null) return null;
+  const row = by(doc, 'data-row', mark.row);
+  return row?.querySelectorAll<HTMLElement>(mark.tag)[mark.nth] ?? null;
+}
+
 /** A polite live region carried from body to body; styled through the CSSOM, which CSP allows. */
 export function announcer(doc: Document): HTMLElement {
   const region = doc.createElement('div');

package/src/navigation-refresh.ts

@@ -0,0 +1,74 @@
+/**
+ * What makes a `refresh()` a refresh: the same page for the same visitor. Its swap runs without a
+ * view transition, leaves focus on the control the visitor was in and announces nothing; a
+ * navigation already in flight is never cancelled for it. `navigation.ts` asks these at each step.
+ */
+
+import { type FocusMark, focusMain, markFocus, restoreFocus, transition } from './navigation-dom';
+
+/**
+ * One `refresh()` in flight: `held` is asked again at the swap — the visitor may have started
+ * typing or opened a dialog while the page was fetched — and `settled` is what `refresh()` answers:
+ * `true` once it landed OR failed (neither is owed again), `false` when it was skipped.
+ */
+export interface RefreshRun {
+  readonly held: (() => boolean) | undefined;
+  settled: boolean;
+}
+
+/** Held across a refresh's swap: where focus was. `undefined` for an ordinary navigation. */
+export type RefreshHold = { readonly mark: FocusMark | null; readonly run: RefreshRun } | undefined;
+
+/**
+ * Taken at the swap, while the focused control is still in the document. `null`: the refresh is
+ * held NOW, so nothing is swapped and `refresh()` answers `false` for its caller to owe it again.
+ */
+export function holdFor(doc: Document, run: RefreshRun | undefined): RefreshHold | null {
+  if (run === undefined) return undefined;
+  return run.held?.() === true ? null : { mark: markFocus(doc), run };
+}
+
+/**
+ * Whether this navigation is skipped: a refresh while another navigation is in flight. That one
+ * fetches fresh anyway, and aborting it is how a visitor's click was lost.
+ */
+export function refreshYields(refresh: RefreshRun | undefined, inflight: unknown): boolean {
+  return refresh !== undefined && inflight !== undefined;
+}
+
+/** The swap: a view transition for a new place, a plain call for the same page. */
+export function swapIn(
+  win: Window,
+  hold: RefreshHold,
+  apply: () => void,
+  track: Parameters<typeof transition>[2],
+): Promise<void> {
+  if (hold === undefined) return transition(win, apply, track);
+  apply();
+  return Promise.resolve();
+}
+
+/**
+ * Whether a navigation whose answer never came (the network, `NAVIGATION_TIMEOUT_MS`) ends here,
+ * quietly: a refresh is. Reloading a page under a reader is what a refresh exists to prevent, and
+ * the page on screen is still the visitor's; settled, so the scheduler does not owe it again.
+ */
+export function refreshFailsQuietly(run: RefreshRun | undefined): boolean {
+  if (run === undefined) return false;
+  run.settled = true;
+  return true;
+}
+
+/**
+ * After the scripts ran, so an island's mounted control is there to take focus back. A new place:
+ * `<main>` and the title read out. A refresh: the marked control, and the announcer untouched.
+ */
+export function landFocus(doc: Document, live: HTMLElement, hold: RefreshHold): void {
+  if (hold !== undefined) {
+    restoreFocus(doc, hold.mark);
+    hold.run.settled = true;
+    return;
+  }
+  focusMain(doc);
+  live.textContent = doc.title;
+}

package/src/navigation.ts

@@ -16,16 +16,8 @@
  */
 
 import { navigationCache } from './navigation-cache';
-import {
-  anchorOf,
-  announcer,
-  focusMain,
-  handOver,
-  intentUrl,
-  linkFacts,
-  submitFacts,
-  transition,
-} from './navigation-dom';
+import { withinDeadline } from './navigation-deadline';
+import { anchorOf, announcer, handOver, intentUrl, linkFacts, submitFacts } from './navigation-dom';
 import {
   type Answer,
   fetchDocument,
@@ -43,6 +35,14 @@ import {
 import { modalController } from './navigation-modal';
 import { addressOf, modalAddress, modalHistory } from './navigation-modal-rules';
 import { pressTracker } from './navigation-press';
+import type { RefreshRun } from './navigation-refresh';
+import {
+  holdFor,
+  landFocus,
+  refreshFailsQuietly,
+  refreshYields,
+  swapIn,
+} from './navigation-refresh';
 import {
   answerMovesTab,
   formVerdict,
@@ -77,13 +77,19 @@ export interface NavigateOptions {
   readonly hops?: number;
   /** The URL's hash addressed it: a modal, or nothing — never a page (`presentation`). */
   readonly fromHash?: boolean;
+  /** The page on screen again, for the same visitor (`navigation-refresh.ts`). */
+  readonly refresh?: RefreshRun;
 }
 
 export interface NavigationRouter {
   navigate(url: string, options?: NavigateOptions): Promise<void>;
   prefetch(url: string): void;
-  /** The page on screen, fetched again and swapped in where it is scrolled. */
-  refresh(): Promise<void>;
+  /**
+   * The page fetched again and swapped in where it is scrolled, unless `held()` says the visitor
+   * is busy. `true` once SETTLED (`RefreshRun`): landed, or failed quietly (`refreshFailsQuietly`).
+   * `false` when held, yielded to another navigation, or a modal was open.
+   */
+  refresh(held?: () => boolean): Promise<boolean>;
   /** `path` as the modal over this page (`#<path>`); anything but a modal of this tab: nothing. */
   openModal(path: string): Promise<void>;
   /** As Escape: Back through the router's own entry, else the hash dropped in place. */
@@ -158,21 +164,19 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
     else win.location.reload();
   };
 
-  const answerFor = (
-    url: string,
-    method: 'GET' | 'POST',
-    options: NavigateOptions,
-    signal: AbortSignal,
-  ) => {
-    if (method === 'POST') {
-      // Before AND once it settles, landed or not: a guess sent while the write was in flight
-      // may have rendered the old state, and a write that failed here may still have committed.
-      forget();
-      const body = options.body === undefined ? {} : { body: options.body };
-      return request(url, 'soft', { method, ...body, signal }).finally(forget);
-    }
-    return heldOrFetched(cache, url, () => request(url, 'soft', { signal }));
-  };
+  /** Bounded by `NAVIGATION_TIMEOUT_MS`: a hung answer never holds `inflight` for good. */
+  const answerFor = (url: string, options: NavigateOptions, mine: AbortSignal) =>
+    withinDeadline(win, mine, (signal) => {
+      const method = options.method ?? 'GET';
+      if (method === 'POST') {
+        // Before AND once it settles, landed or not: a guess sent while the write was in flight
+        // may have rendered the old state, and a write that failed here may still have committed.
+        forget();
+        const body = options.body === undefined ? {} : { body: options.body };
+        return request(url, 'soft', { method, ...body, signal }).finally(forget);
+      }
+      return heldOrFetched(cache, url, () => request(url, 'soft', { signal }));
+    });
 
   const navigate = async (url: string, options: NavigateOptions = {}): Promise<void> => {
     // The redirect chain's only exit is `hops >= NAVIGATION_MAX_HOPS`, which `NaN` never meets.
@@ -189,6 +193,7 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
       else win.location.assign(url);
       return;
     }
+    if (refreshYields(options.refresh, inflight)) return;
     const detail = { url, method };
     if (!doc.dispatchEvent(new CustomEvent(NAVIGATE_EVENT, { detail, cancelable: true }))) return;
     inflight?.abort();
@@ -207,9 +212,9 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
     try {
       let answer: Answer;
       try {
-        answer = await answerFor(url, method, options, mine.signal);
+        answer = await answerFor(url, options, mine.signal);
       } catch {
-        if (mine.signal.aborted) return;
+        if (mine.signal.aborted || refreshFailsQuietly(options.refresh)) return;
         // A GET that never arrived is the browser's to try; a POST that failed is never re-sent.
         if (method === 'GET') win.location.assign(url);
         else failed(url, method, 'the request failed on the network');
@@ -280,14 +285,17 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
         modal.release();
         modal.dismiss();
         let swapped: ReturnType<typeof swapDocument> | undefined;
-        await transition(
+        const hold = holdFor(doc, options.refresh);
+        if (hold === null) return;
+        await swapIn(
           win,
+          hold,
           () => {
             // A newer navigation started while the sheets loaded: this answer is no longer asked for.
             if (mine.signal.aborted) return;
             swapped = swapDocument(doc, next, owned);
             // Emptied here and filled after the scripts, so a page with the same title still reads out.
-            live.textContent = '';
+            if (hold === undefined) live.textContent = '';
             swapped.body.append(live);
             rendered = withoutFragment(landed);
             if (history !== 'none') {
@@ -314,8 +322,7 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
         await runScripts([...done.body.querySelectorAll('script')], ran, (fresh, inert) =>
           inert.replaceWith(fresh),
         );
-        focusMain(doc);
-        live.textContent = doc.title;
+        landFocus(doc, live, hold);
         doc.dispatchEvent(new CustomEvent(NAVIGATED_EVENT, { detail: { url: landed } }));
         reconcile();
       } catch {
@@ -458,11 +465,15 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
   const router: NavigationRouter = {
     navigate,
     prefetch,
-    refresh() {
-      // A fresh answer for the page on screen, landing where the visitor is scrolled.
+    async refresh(held) {
+      // A fresh answer for the page on screen, landing where the visitor is scrolled. Not under
+      // an open modal: the page beneath is out of reach, and the swap would take the modal with it.
+      if (modal.address !== undefined) return false;
       cache.delete(rendered);
       scroll.save();
-      return navigate(rendered, { history: 'none' });
+      const run: RefreshRun = { held, settled: false };
+      await navigate(rendered, { history: 'none', refresh: run });
+      return run.settled;
     },
     openModal(path) {
       const address = modalAddress(`#${path}`, win.location.href);

package/src/refresh-idle.ts

@@ -0,0 +1,171 @@
+/**
+ * `scheduleRefresh()`: "the server's page changed" said by a channel, paid when the visitor is not
+ * in the middle of something. Coalesced to one running and one owed; held while the tab is hidden,
+ * a dialog or popover is open, a field has focus, text is selected, a navigation runs, or within
+ * `QUIET_MS` of input. State lives on `window` under one `Symbol.for` key: one per page, any chunk.
+ */
+
+import { type Clock, sessionIsLost, systemClock } from '@ultimat3/core/page';
+import type { NavigationRouter } from './navigation';
+
+/** How long after a scroll, wheel, key or press the page counts as being read. */
+export const QUIET_MS = 1_000;
+
+/** A press unreleased this long is a lost `pointerup`, not a visitor still pressing. */
+export const PRESS_HOLD_MS = 10_000;
+
+/**
+ * A refresh not settled by now is given up on, so one hung answer cannot hold `running` forever and
+ * starve every later ask. Long past any answer still worth swapping in under a reader.
+ */
+export const REFRESH_TIMEOUT_MS = 30_000;
+
+const KEY: unique symbol = Symbol.for('ultimate.refresh-idle');
+
+/** What the scheduler reads of the window; injected by the tests. */
+export interface IdleWindow {
+  readonly document: Document;
+  readonly __xNavigation?: Pick<NavigationRouter, 'refresh'> | undefined;
+  addEventListener(type: string, fn: () => void, options?: AddEventListenerOptions): void;
+  getSelection(): { readonly isCollapsed: boolean } | null;
+  setTimeout(fn: () => void, ms: number): number;
+  clearTimeout(id: number | undefined): void;
+}
+
+interface IdleState {
+  running: boolean;
+  owed: boolean;
+  timer: number | undefined;
+  lastInput: number;
+  pressedAt: number | undefined;
+  readonly schedule: () => void;
+}
+
+type StateHost = { [KEY]?: IdleState };
+
+/**
+ * Ask for the page on screen to be re-read once the visitor is idle. Never a reload: without the
+ * client router this does nothing, because reloading a page under a reader is the failure it
+ * exists to prevent. After a lost session (`sessionIsLost()`), nothing, ever.
+ */
+export function scheduleRefresh(): void {
+  const win = (globalThis as { window?: IdleWindow }).window;
+  if (win !== undefined) refreshIdleOn(win, systemClock)();
+}
+
+/** The page's one scheduler over `win`, created on first use. Internal: tests inject `win`/`clock`. */
+export function refreshIdleOn(win: IdleWindow, clock: Pick<Clock, 'monotonic'>): () => void {
+  const host = win as StateHost;
+  const existing = host[KEY];
+  if (existing !== undefined) return existing.schedule;
+  if (win.__xNavigation === undefined) return (): void => {};
+  const doc = win.document;
+  const state: IdleState = {
+    running: false,
+    owed: false,
+    timer: undefined,
+    // Far enough back that a page nobody touched is quiet from the start.
+    lastInput: clock.monotonic() - QUIET_MS,
+    pressedAt: undefined,
+    schedule: (): void => {
+      if (sessionIsLost()) return;
+      state.owed = true;
+      pump();
+    },
+  };
+
+  /** Milliseconds until it is worth asking again; `0` = free now; `Infinity` = wait for an event. */
+  const heldFor = (): number => {
+    if (doc.visibilityState === 'hidden') return Number.POSITIVE_INFINITY;
+    const now = clock.monotonic();
+    if (state.pressedAt !== undefined && now - state.pressedAt < PRESS_HOLD_MS) {
+      return Math.min(QUIET_MS, PRESS_HOLD_MS - (now - state.pressedAt));
+    }
+    const quiet = QUIET_MS - (now - state.lastInput);
+    if (quiet > 0) return quiet;
+    return busy() ? QUIET_MS : 0;
+  };
+
+  const busy = (): boolean => {
+    if (doc.documentElement.hasAttribute('data-x-navigating')) return true;
+    if (doc.querySelector('dialog[open]') !== null || popoverOpen()) return true;
+    const active = doc.activeElement as (Element & { isContentEditable?: boolean }) | null;
+    if (active !== null && active !== doc.body) {
+      if (active.tagName === 'INPUT' || active.tagName === 'TEXTAREA') return true;
+      if (active.isContentEditable === true) return true;
+    }
+    return win.getSelection()?.isCollapsed === false;
+  };
+
+  const popoverOpen = (): boolean => {
+    try {
+      return doc.querySelector('[popover]:popover-open') !== null;
+    } catch {
+      // A browser without the Popover API cannot parse the pseudo-class, and has no open popover.
+      return false;
+    }
+  };
+
+  const pump = (): void => {
+    if (!state.owed || state.running || sessionIsLost()) return;
+    win.clearTimeout(state.timer);
+    state.timer = undefined;
+    const wait = heldFor();
+    if (wait === Number.POSITIVE_INFINITY) return;
+    if (wait > 0) {
+      state.timer = win.setTimeout(pump, wait);
+      return;
+    }
+    state.owed = false;
+    state.running = true;
+    const router = win.__xNavigation;
+    let settled = false;
+    let deadline: number | undefined;
+    const done = (ran: boolean): void => {
+      // Once per run: a hung answer landing after its timeout belongs to no run.
+      if (settled) return;
+      settled = true;
+      win.clearTimeout(deadline);
+      state.running = false;
+      if (ran) {
+        pump();
+        return;
+      }
+      // Skipped — a navigation in flight, an open modal, the visitor busy when the answer landed:
+      // still owed, and asked again after a quiet second rather than spun on at once.
+      state.owed = true;
+      state.timer = win.setTimeout(pump, QUIET_MS);
+    };
+    if (router === undefined) {
+      done(true);
+      return;
+    }
+    // Given up on, a hung refresh counts as run: retrying it would only ask the same stuck router.
+    deadline = win.setTimeout(() => done(true), REFRESH_TIMEOUT_MS);
+    // A failed refresh is not retried here: the router already handed the visitor its own answer.
+    router.refresh(() => heldFor() > 0).then(done, () => done(true));
+  };
+
+  const input = (): void => {
+    state.lastInput = clock.monotonic();
+  };
+  const passive = { passive: true, capture: true };
+  for (const type of ['scroll', 'wheel', 'keydown']) win.addEventListener(type, input, passive);
+  win.addEventListener(
+    'pointerdown',
+    () => {
+      input();
+      state.pressedAt = clock.monotonic();
+    },
+    passive,
+  );
+  const release = (): void => {
+    input();
+    state.pressedAt = undefined;
+  };
+  win.addEventListener('pointerup', release, passive);
+  win.addEventListener('pointercancel', release, passive);
+  doc.addEventListener('visibilitychange', pump);
+  Object.defineProperty(host, KEY, { value: state, configurable: true });
+  return state.schedule;
+}

package/src/registry.ts

@@ -6,7 +6,6 @@
  */
 
 import type { HydrateStrategy, OfflineStrategy, RenderMode } from '@ultimat3/core';
-import { finiteCount } from '@ultimat3/core';
 import { byCodeUnit } from './code-unit-order';
 import {
   RouteDuplicateError,
@@ -50,7 +49,6 @@ export interface RouteEntry<TData = RouteData> {
   readonly path: string;
   readonly surface: RouteSurface;
   readonly config: RouteConfig<TData>;
-  readonly suspenseBoundaries: number;
   readonly islands: readonly string[];
   readonly pattern: CompiledPattern;
   /**
@@ -76,7 +74,7 @@ export interface RouteDescriptor {
   readonly revalidateMaxStale?: string | number | null;
   /**
    * `revalidate.query`, sorted: the only query parameters an `isr` page of this route keys on.
-   * `null` when the route declared none — its pages then key on the WHOLE query string.
+   * `null` when the route declared none — its pages then key on no query at all.
    */
   readonly revalidateQuery?: readonly string[] | null;
   readonly prerenderable: boolean;
@@ -234,8 +232,6 @@ let described: readonly RouteDescriptor[] | undefined;
 export interface RegisterRouteInput<TData = RouteData> {
   readonly file: string;
   readonly config: RouteConfig<TData>;
-  /** Counted from the module's JSX by the build; `stream` requires >= 1. */
-  readonly suspenseBoundaries?: number;
   // No `islands` key: an island is declared by `island()` and reaches the entry through
   // `config.islands`. It was here, undocumented, passed by nothing, and read as
   // `input.islands ?? []` — so the only thing a caller could do with it was un-weigh a
@@ -263,14 +259,6 @@ export function registerRoute<TData = RouteData>(
 
   const derived = routePathFromFile(input.file);
   const path = input.path ?? derived.path;
-  // `ctx.suspenseBoundaries < 1` is the only thing between `render: 'stream'` and a route that
-  // streams nothing, and `NaN < 1` is false — a count that arrived non-finite does not report the
-  // route it counted, it stops reporting any route.
-  const suspenseBoundaries = finiteCount(
-    'registerRoute',
-    'suspenseBoundaries',
-    input.suspenseBoundaries ?? 0,
-  );
   // Explicit `<TData>`: `isRouteConfig` is a guard over the default `RouteData`, so inference off
   // the narrowed argument would resolve the route's own data generic away here.
   const config = withIslandBudget<TData>(input.config, derived.surface);
@@ -279,7 +267,6 @@ export function registerRoute<TData = RouteData>(
     file: input.file,
     path,
     surface: derived.surface,
-    suspenseBoundaries,
   });
 
   assertPurgeableTags(input.file, config.revalidate?.tags);
@@ -301,7 +288,6 @@ export function registerRoute<TData = RouteData>(
     path,
     surface: derived.surface,
     config,
-    suspenseBoundaries,
     // The declaration is the ONLY source. It was `input.islands ?? []`, which nothing ever passed,
     // so the now-deleted `routeJsBytes`'s "what registration declared" half read `[]` on every
     // route in the framework's history — and keeping the input as a fallback would be a second