@uniflowed/hooks 0.0.0-alpha.11 → 0.0.0-alpha.13

package/browser.js

@@ -13,17 +13,52 @@
 // # What belongs in this module
 //
 // A reading of the one browser the page is in: its size, its scroll offset,
-// its connection, its visibility, its position on the earth, the preferences
-// the reader set, the permissions the reader granted. There is exactly one
-// answer at a time, nobody has to pass anything in to ask, and a server has no
-// answer at all — which is why every hook here either takes a server value
-// from the caller or states an honest default.
+// its connection, its visibility, its position on the earth, the fragment in
+// its address bar, the preferences the reader set, the permissions the reader
+// granted. There is exactly one answer at a time, nobody has to pass anything
+// in to ask, and a server has no answer at all — which is why every hook here
+// either takes a server value from the caller or states an honest default.
 //
 // Not here: anything about a specific element, which needs a ref and lives in
 // `dom.js`. `useDocumentVisible` is the closest call in the package and stays
 // here, because the document is the environment rather than a node a caller
 // chose.
 //
+// The path and the query are not here either, and that one is a boundary rather
+// than a filing decision: they are on the request, so `@uniflowed/router` has
+// already resolved them and `useRoute` is where a page reads them. What is here
+// is the fragment, which the browser strips before the request goes out and
+// which therefore nothing on the server has ever seen. See `useHash`.
+//
+// # What the first render produces
+//
+// Every hook below answers twice with the same value — once during the
+// prerender, once during the client's hydrating render — and only then with
+// what the browser actually says. That second column is not a detail: it is the
+// value React compares the two trees at, so a hook whose first client render
+// disagreed with the server's would report a mismatch on a page that did
+// nothing wrong.
+//
+// | Hook | Prerender, and the first client render | Afterwards |
+// | --- | --- | --- |
+// | `useSupported` | `false` | what `probe` says |
+// | `useMediaQuery` | `serverValue`, default `false` | whether it matches |
+// | `usePreferredColorScheme` | `serverValue`, default `"light"` | the reader's setting |
+// | `usePrefersReducedMotion` | `serverValue`, default `false` | the reader's setting |
+// | `useOnline` | `serverValue`, default `true` | `navigator.onLine` |
+// | `useDocumentVisible` | `serverValue`, default `true` | the visibility state |
+// | `useHash` | `""`, and no way to say otherwise | the fragment |
+// | `useWindowSize` | `serverValue`, default `0x0` | the viewport |
+// | `useWindowScroll` | `serverValue`, default `0,0` | the offset |
+// | `useNetwork` | `{ online: serverValue, measured: null }` | what Chromium measured |
+// | `useGeolocation` | `"unsupported"` | `"pending"`, then a fix or a failure |
+// | `usePermission` | `"unknown"` | what the browser answers |
+// | `useScrollLock` | nothing at all — effects do not run in a prerender | the page is held |
+//
+// `tests/library/hooks-ssr.test.js` renders every one of them in a process with
+// no document and asserts the markup, so a row of this table that stopped being
+// true would fail there rather than in somebody's browser.
+//
 // # The one that writes
 //
 // `useScrollLock` is the exception to "reading", and it is here rather than in
@@ -41,6 +76,12 @@
 // subscriptions whose *first* value only arrives asynchronously, so there is
 // nothing for a snapshot to return until it does, and `useScrollLock` writes.
 // Each says so where it is defined.
+//
+// `useHash` is a store whose event the browser only half provides —
+// `hashchange` and `popstate` cover what a reader does, and a `pushState` fires
+// neither — so it keeps a registry of its own subscribers and announces its own
+// writes, the way `useStorage` does. That is a store with a gap named in it,
+// not a fourth kind of hook.
 
 import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from "@uniflowed/react";
 
@@ -76,6 +117,35 @@ export type BrowserNavigator = {
   ...
 };
 
+/**
+ * The part of `location` this module reads.
+ *
+ * `href` and the fragment, and nothing else. The path and the query are on the
+ * request, so `@uniflowed/router` has already resolved them and a second
+ * reading of them here would be a second answer to a settled question — see
+ * `useHash`.
+ */
+export type BrowserLocation = {
+  readonly href: string,
+  readonly hash: string,
+  ...
+};
+
+/**
+ * The part of `history` this module writes through.
+ *
+ * `state` is read so that a fragment written from here hands back whatever a
+ * router put there, rather than clearing it. The second parameter of both
+ * methods has been ignored by every browser since the API shipped, and is
+ * typed rather than omitted because it is positional.
+ */
+export type BrowserHistory = {
+  readonly state: mixed,
+  readonly pushState: (state: mixed, unused: string, url: string) => void,
+  readonly replaceState: (state: mixed, unused: string, url: string) => void,
+  ...
+};
+
 /** The Network Information object, which only Chromium has. */
 export type NetworkConnection = {
   readonly downlink?: number,
@@ -98,6 +168,8 @@ export type NetworkConnection = {
 export type BrowserWindow = {
   readonly document: Document,
   readonly navigator: BrowserNavigator,
+  readonly location?: ?BrowserLocation,
+  readonly history?: ?BrowserHistory,
   readonly localStorage?: ?Storage,
   readonly sessionStorage?: ?Storage,
   readonly innerWidth: number,
@@ -269,6 +341,132 @@ export hook useDocumentVisible(serverValue: boolean = true): boolean {
   return useSyncExternalStore(subscribe, snapshot, () => serverValue);
 }
 
+/**
+ * Everybody watching the fragment in this tab.
+ *
+ * Module-level, because neither `history.pushState` nor `history.replaceState`
+ * fires anything: a component that writes the fragment has to tell the others
+ * itself, and there is nothing in the platform that will do it. The same
+ * registry shape as `useStorage`'s, and balanced under Strict Mode for the same
+ * reason — `subscribe` adds and the cleanup it returns removes.
+ */
+const fragmentListeners: Set<() => void> = new Set();
+
+/** Listen for every change to the fragment this tab can hear about. */
+function subscribeToFragment(notify: () => void): () => void {
+  const win = browserWindow();
+  fragmentListeners.add(notify);
+  // `hashchange` covers an anchor the reader clicked and an address bar they
+  // edited; `popstate` covers back and forward, which fires only the second of
+  // the two when the entry it lands on differs by more than the fragment.
+  win?.addEventListener("hashchange", notify);
+  win?.addEventListener("popstate", notify);
+  return () => {
+    fragmentListeners.delete(notify);
+    win?.removeEventListener("hashchange", notify);
+    win?.removeEventListener("popstate", notify);
+  };
+}
+
+/** The fragment, without its `#`, decoded where the escapes are valid. */
+function readFragment(): string {
+  const raw = browserWindow()?.location?.hash ?? "";
+  const text = raw.startsWith("#") ? raw.slice(1) : raw;
+  try {
+    return decodeURIComponent(text);
+  } catch {
+    // A fragment is whatever somebody typed into the address bar, and a lone
+    // `%` is not a reason to fail a render. The text as written is closer to
+    // what the reader meant than a throw is. `@uniflowed/web`'s cookie parser
+    // makes the same trade at the same kind of boundary.
+    return text;
+  }
+}
+
+/** What a server render, and the client's hydrating render, both report. */
+function noFragment(): string {
+  return "";
+}
+
+/**
+ * Write the fragment, without moving the page.
+ *
+ * Through `URL` rather than by concatenation, which is the whole safety
+ * argument: the setter percent-escapes what it is handed and can only put it
+ * after the `#`, so a caller who passes `?admin=1`, `//elsewhere.example` or a
+ * whole second URL writes a fragment that says so rather than a query, an
+ * origin or a path. `history.pushState` refuses a cross-origin URL, but that is
+ * the second line of defence and not one worth relying on for a same-origin
+ * path rewrite, which it permits.
+ *
+ * Module-level, so it is the same function on every render and nothing has to
+ * memoize it.
+ */
+function writeFragment(next: string, options?: {| readonly replace?: boolean |}): void {
+  const win = browserWindow();
+  const location = win?.location;
+  const history = win?.history;
+  if (location == null || history == null) {
+    return;
+  }
+  const url = new URL(location.href);
+  url.hash = next;
+  // `history.state` is handed back rather than cleared: a router put it there,
+  // and changing which tab is showing is not a reason to lose it.
+  if (options?.replace === true) {
+    history.replaceState(history.state, "", url.href);
+  } else {
+    history.pushState(history.state, "", url.href);
+  }
+  notifyFragment();
+}
+
+function notifyFragment(): void {
+  for (const listener of fragmentListeners) {
+    listener();
+  }
+}
+
+/**
+ * The fragment in the address bar, and a way to change it.
+ *
+ * The one part of the URL that needs a hook. A request carries the path and the
+ * query, so a server render already knows both and `@uniflowed/router`'s
+ * `useRoute` has resolved them; the fragment is never sent — the browser strips
+ * it before the request goes out — so there is no value for a server to know
+ * and no caller who could supply a better one. That is why this takes no
+ * `serverValue` where `useMediaQuery` and `useOnline` do: `""` is not a default
+ * chosen for want of a better one, it is the only honest answer, and the
+ * client's hydrating render reports it too before re-rendering with the truth.
+ *
+ * Returned without the `#`, and percent-decoded, so it compares directly
+ * against the `id` a section was given.
+ *
+ * Writing does not scroll, and that is deliberate. Moving to a section and
+ * recording which tab is open are two intentions, and the platform couples them
+ * only because assigning `location.hash` is the old way to do both at once — so
+ * a tab strip that writes `billing` would jump the page. Call
+ * `element.scrollIntoView()` where scrolling is what was wanted.
+ *
+ * `replace` overwrites the current history entry instead of adding one, which
+ * is what a tab strip wants: eleven tab clicks should not be eleven presses of
+ * the back button.
+ *
+ * What this cannot see is a fragment some other code changed with
+ * `history.pushState`, because that fires no event of any kind — not
+ * `hashchange`, not `popstate`. Writes made through this hook announce
+ * themselves to every other component using it; a `pushState` made anywhere
+ * else is invisible to every listener the platform offers, and naming that is
+ * more use than pretending otherwise.
+ */
+export hook useHash(): [
+  string,
+  (next: string, options?: {| readonly replace?: boolean |}) => void,
+] {
+  const fragment = useSyncExternalStore(subscribeToFragment, readFragment, noFragment);
+  return [fragment, writeFragment];
+}
+
 /**
  * How far something has been scrolled.
  *
@@ -429,16 +627,35 @@ export hook useScrollLock(locked: boolean): void {
 /** How good the connection is, as the browser grades it. */
 export type EffectiveConnectionType = "slow-2g" | "2g" | "3g" | "4g";
 
-/** What the browser will say about the connection. */
-export type Network = {|
-  readonly online: boolean,
+/**
+ * What Network Information measured, where there is such a thing.
+ *
+ * Its own type rather than three more fields on [`Network`], because the three
+ * of them arrive together or not at all: they come from `navigator.connection`,
+ * which is Chromium's alone. A server, and every other browser, has no object
+ * to read them off.
+ */
+export type NetworkMeasurement = {|
   /** Estimated bandwidth in megabits per second, where the browser reports it. */
   readonly downlink: number | null,
   readonly effectiveType: EffectiveConnectionType | null,
   /** Whether the reader has asked for less data to be used. */
   readonly saveData: boolean,
-  /** Whether anything beyond `online` was actually measured. */
-  readonly supported: boolean,
+|};
+
+/**
+ * What the browser will say about the connection.
+ *
+ * `measured` used to be three flat fields and a `supported` boolean beside
+ * them, which is the shape this package now refuses: a caller had to read one
+ * field to learn whether three others meant anything, and `downlink: null` said
+ * both "this browser does not measure bandwidth" and "it does, and has not
+ * decided yet". A null here says one thing — nothing on this side can answer —
+ * and the fields that would have been guesses are not reachable to be read.
+ */
+export type Network = {|
+  readonly online: boolean,
+  readonly measured: NetworkMeasurement | null,
 |};
 
 const EFFECTIVE_TYPES: $ReadOnlyArray<EffectiveConnectionType> = ["slow-2g", "2g", "3g", "4g"];
@@ -455,10 +672,11 @@ function asEffectiveType(value: string): EffectiveConnectionType | null {
 /**
  * What the browser will say about the connection.
  *
- * Only Chromium implements Network Information, so `supported` is part of the
- * answer rather than something a caller has to find out by seeing nulls. The
- * `online` half is everywhere, and stays true even where the rest is unknown —
- * which is the field almost every caller wants.
+ * Only Chromium implements Network Information, so a browser that does not
+ * reports `measured: null` rather than three fields that are indistinguishable
+ * from a slow connection. `online` stays flat and is answered everywhere — it
+ * is the field almost every caller wants, and burying it behind a narrowing
+ * would have made the common case pay for the rare one.
  *
  * The snapshot is a packed string for the reason `useWindowSize` gives: an
  * object rebuilt on every check never compares equal, and `useSyncExternalStore`
@@ -481,39 +699,49 @@ export hook useNetwork(serverValue: boolean = true): Network {
     };
   }, []);
 
-  const server = useCallback(() => `${serverValue ? "1" : "0"}|||0`, [serverValue]);
+  // Whether there was a connection object to read is its own field, because
+  // "this browser does not measure" and "it measures and reported nothing yet"
+  // pack to the same three empty values and are not the same answer.
+  // `effectiveType` is last so that it is the only field a `|` in browser text
+  // could run into.
+  const server = useCallback(() => `${serverValue ? "1" : "0"}|0|0||`, [serverValue]);
 
   const packed = useSyncExternalStore(
     subscribe,
     useCallback(() => {
       const navigator = browserWindow()?.navigator;
       if (navigator == null) {
-        return `${serverValue ? "1" : "0"}|||0`;
+        return `${serverValue ? "1" : "0"}|0|0||`;
       }
       const connection = navigator.connection;
       const online = navigator.onLine ?? serverValue;
       if (connection == null) {
-        return `${online ? "1" : "0"}|||0`;
+        return `${online ? "1" : "0"}|0|0||`;
       }
       const downlink = connection.downlink;
       return [
         online ? "1" : "0",
+        "1",
+        connection.saveData === true ? "1" : "0",
         downlink == null ? "" : String(downlink),
         connection.effectiveType ?? "",
-        connection.saveData === true ? "1" : "0",
       ].join("|");
     }, [serverValue]),
     server,
   );
 
   return useMemo(() => {
-    const [online, downlink, effectiveType, saveData] = packed.split("|");
+    const [online, measured, saveData, downlink, effectiveType] = packed.split("|");
     return {
       online: online === "1",
-      downlink: downlink === "" ? null : Number(downlink),
-      effectiveType: asEffectiveType(effectiveType),
-      saveData: saveData === "1",
-      supported: downlink !== "" || effectiveType !== "",
+      measured:
+        measured === "1"
+          ? {
+              downlink: downlink === "" ? null : Number(downlink),
+              effectiveType: asEffectiveType(effectiveType),
+              saveData: saveData === "1",
+            }
+          : null,
     };
   }, [packed]);
 }
@@ -527,12 +755,47 @@ export type Geoposition = {|
   readonly timestamp: number,
 |};
 
-/** What `useGeolocation` knows so far. */
-export type GeolocationReading = {|
-  readonly position: Geoposition | null,
-  readonly error: Error | null,
-  readonly supported: boolean,
-|};
+/**
+ * What `useGeolocation` knows so far.
+ *
+ * A union rather than a record of nullable fields, and the difference is the
+ * whole point of the type. The record it replaced —
+ * `{| position: Geoposition | null, error: Error | null, supported: boolean |}`
+ * — could represent eight states, of which four could never happen, and it
+ * asked every caller to work out from three fields which of the four real ones
+ * they were in. `position == null` meant "no browser", "not asked", "asked and
+ * refused" and "waiting for the reader to decide", and a page that wanted to
+ * say something different for each had to reconstruct the distinction the hook
+ * had thrown away.
+ *
+ * Five states, each of which a page does something different about, and Flow
+ * refuses to read a field the state does not have.
+ */
+export type GeolocationReading =
+  /**
+   * Not watching, because the caller passed `enabled: false`. Reported before
+   * `"unsupported"` is even considered, so it is the same on both sides of a
+   * hydration.
+   */
+  | {| readonly status: "idle" |}
+  /** No geolocation object here at all: a server render, or a browser without one. */
+  | {| readonly status: "unsupported" |}
+  /** Watching. The reader has been asked and has not answered yet. */
+  | {| readonly status: "pending" |}
+  /**
+   * A fix. `error` is the failure of a *later* reading, and its presence means
+   * the position beside it is the last good one rather than the current one.
+   */
+  | {| readonly status: "located", readonly position: Geoposition, readonly error: Error | null |}
+  /** Refused, unavailable or timed out, with no earlier fix to fall back on. */
+  | {| readonly status: "failed", readonly error: Error |};
+
+// The three states with nothing in them, allocated once. A hook that returns a
+// fresh object for "nothing has happened" makes every caller's dependency array
+// change on every render.
+const UNSUPPORTED: GeolocationReading = { status: "unsupported" };
+const IDLE: GeolocationReading = { status: "idle" };
+const PENDING: GeolocationReading = { status: "pending" };
 
 /**
  * Watch where the reader is.
@@ -541,8 +804,14 @@ export type GeolocationReading = {|
  * stylistic: there is no snapshot to read. The browser has no "current
  * position" property to ask — the first value arrives in a callback, after a
  * permission prompt the reader may take a minute to answer or never answer at
- * all. So `position` is `null` until one arrives, on a server and in a browser
- * alike, which is also what makes it hydration-safe.
+ * all. So there is nothing but `"unsupported"` to report during a prerender and
+ * in the client's first render, which is also what makes it hydration-safe: the
+ * server writes the markup for a page that does not know where anybody is, and
+ * the hydrating render agrees with it.
+ *
+ * Turning `enabled` off after a fix reports `"idle"` rather than keeping the
+ * position, because a reading nobody is watching is a reading nobody should be
+ * shown. A caller who wants the last one to stay on screen holds it.
  *
  * Mounting this asks the reader for permission. Mount it on the page that
  * needs a position, not at the top of an application.
@@ -591,10 +860,28 @@ export hook useGeolocation(options?: {|
     return () => geolocation.clearWatch(watch);
   }, [enabled, highAccuracy, maximumAge, timeout]);
 
-  return useMemo(
-    () => ({ position: reading.position, error: reading.error, supported }),
-    [reading, supported],
-  );
+  // Derived during the render from what the effect has recorded, rather than
+  // kept as a second copy of it in state: a status that had to be written by
+  // the same `setReading` call would be a second thing to keep in step with
+  // `enabled` and with `supported`, neither of which the effect can see.
+  return useMemo(() => {
+    // `enabled` is asked about before `supported`, because it is the caller's
+    // own decision and is therefore the same on both sides of a hydration: a
+    // watch nobody asked for is idle on a server and idle in a browser, where
+    // "unsupported" would have been true on the server and false a moment
+    // later.
+    if (!enabled) {
+      return IDLE;
+    }
+    if (!supported) {
+      return UNSUPPORTED;
+    }
+    const { position, error } = reading;
+    if (position != null) {
+      return { status: "located", position, error };
+    }
+    return error == null ? PENDING : { status: "failed", error };
+  }, [supported, enabled, reading]);
 }
 
 /** A permission this hook knows how to ask about. */

package/events.js

@@ -0,0 +1,298 @@
+// @flow
+//
+// `@uniflowed/hooks/events`: a stream the server is pushing.
+//
+// One hook, and it is here rather than in `./channels.js` for a reason that
+// module's header states from the other side: what belongs there is a value
+// crossing the page's boundary that is *not* the server, because a request is
+// `@uniflowed/query`'s and `@uniflowed/fetch`'s and comes with caching, retry
+// and revalidation that a broadcast does not want. An event stream is the
+// server and has none of that either — there is no cache entry, nothing to
+// revalidate, and no request to repeat. It is a connection, which is a third
+// thing, so it is a third file.
+//
+// `@uniflowed/server/events` is the other end of it.
+//
+// # What the platform already does, and the one thing it does not
+//
+// `EventSource` reconnects. It backs off, it sends the last `id:` it saw back
+// as `Last-Event-ID`, and it needs no help — for as long as the server keeps
+// answering. There is exactly one case where it gives up permanently: a
+// response that is not a `200` with `content-type: text/event-stream`. Then it
+// fires `error`, moves to `CLOSED`, and never tries again. A deployment
+// restarting behind a load balancer answers `502` for a second or two, and
+// every open stream in every tab is dead until somebody reloads the page.
+//
+// That is the case this hook exists for. When the browser gives up, it opens a
+// new `EventSource` on a doubling delay; when the browser is retrying on its
+// own it stays out of the way, because two reconnection schedules on one
+// connection is worse than either.
+//
+// The other half is that none of the platform's reconnecting is visible. An
+// application that wants to draw "reconnecting…" cannot ask `EventSource`
+// anything but `readyState`, and only from an event handler. [`status`] is that
+// as state.
+//
+// # What a reconnection this hook makes cannot carry
+//
+// `Last-Event-ID`. The browser sends it on its *own* retry and there is no way
+// to set it on a new `EventSource` — the constructor takes a URL and one flag.
+// So [`lastEventId`] is handed back, and a stream that needs to resume puts it
+// in the URL itself:
+//
+//   const stream = useEventSource(`/api/feed?after=${cursor ?? ""}`);
+//
+// Written down rather than worked around: a hook that silently appended a query
+// parameter would be inventing a protocol on the application's behalf.
+//
+// # Before hydration
+//
+// `status` is `"idle"` on the server and on the client's first render, through
+// `useSupported` — see the reason there. Nothing is opened during a render; the
+// connection is made in an effect, so a prerender neither connects nor pretends
+// it did. `"idle"` rather than `"connecting"` because they are different facts
+// and only one of them is true: nothing has been attempted here.
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "@uniflowed/react";
+
+import { useSupported } from "./browser.js";
+import { useStableCallback } from "./lifecycle.js";
+
+/**
+ * The part of `EventSource` this module uses.
+ *
+ * Declared here rather than taken from Flow's library definition, for the
+ * reason `./channels.js` gives about `BroadcastChannel`: the constructor is
+ * looked up at runtime and may be absent, so it has to be a value with a known
+ * constructor signature, and the listener is typed with the two fields that are
+ * read — which removes an `instanceof MessageEvent` whose name is not defined
+ * in every host these tests run in.
+ */
+type StreamEvent = { data?: mixed, lastEventId?: mixed, ... };
+
+declare class Stream {
+  constructor(url: string, options?: { withCredentials?: boolean, ... }): void;
+  readonly readyState: number;
+  close(): void;
+  addEventListener(type: string, listener: (event: StreamEvent) => mixed): void;
+  removeEventListener(type: string, listener: (event: StreamEvent) => mixed): void;
+}
+
+/**
+ * `EventSource`, which is the host's rather than the document's.
+ *
+ * The same split `./channels.js` describes: in a browser the two are one
+ * object, and in a process where a document has been installed onto another
+ * runtime's global they are not — an event stream is a facility of the runtime,
+ * and a hosted `Window` is not required to carry one.
+ */
+declare var EventSource: Class<Stream> | void;
+
+function streamConstructor(): Class<Stream> | null {
+  return typeof EventSource === "undefined" ? null : (EventSource ?? null);
+}
+
+/** `EventSource.CLOSED`, spelled as the number so no global is read for it. */
+const CLOSED = 2;
+
+/** Where the connection is. */
+export type EventStreamStatus =
+  /** Nothing has been attempted: a prerender, no URL, or `enabled: false`. */
+  | "idle"
+  /** Opening, or reopening — by the browser or by this hook. */
+  | "connecting"
+  /** Receiving. */
+  | "open"
+  /** Closed on purpose, by `close()`. It will not reopen on its own. */
+  | "closed";
+
+/** One message, as the three fields the format carries. */
+export type ServerEvent = {|
+  /** The `event:` name, or `message` where the stream sent none. */
+  readonly name: string,
+  /** The `data:` payload, as text. */
+  readonly data: string,
+  /** The `id:`, or `null`. */
+  readonly id: string | null,
+|};
+
+/** How the connection behaves. */
+export type EventSourceOptions = {|
+  /**
+   * Named events to listen for, besides the unnamed `message`.
+   *
+   * A stream that sends `event: progress` delivers nothing to a `message`
+   * listener, which is the single most common way an event stream appears to
+   * be connected and silent.
+   */
+  readonly events?: $ReadOnlyArray<string>,
+  /** Send cookies to another origin. Same-origin streams do not need it. */
+  readonly withCredentials?: boolean,
+  /** `false` closes the connection and opens none; `null` for the URL does too. */
+  readonly enabled?: boolean,
+  /** Called for every event, for a stream whose messages are events. */
+  readonly onEvent?: (event: ServerEvent) => mixed,
+  /** Milliseconds before this hook's first reopen; doubles. Default 1000. */
+  readonly retryDelay?: number,
+  /** The ceiling the doubling stops at. Default 30000. */
+  readonly maxRetryDelay?: number,
+|};
+
+/** What `useEventSource` hands back. */
+export type UseEventSourceReturn = {|
+  readonly status: EventStreamStatus,
+  /**
+   * The most recent event, or `null` before one arrives.
+   *
+   * `./channels.js` deliberately does not hand back the last broadcast, and
+   * the argument there is that a message is an event: a tab that just opened
+   * has never received one and cannot ask. A stream is not that. It is a
+   * connection with a lifetime, and for as long as it is open "the latest
+   * message" is defined — which is what a progress bar, a price and a presence
+   * indicator all are. `onEvent` is there for the streams that really are
+   * events.
+   */
+  readonly last: ServerEvent | null,
+  /**
+   * The last `id:` seen, for a stream that resumes.
+   *
+   * The browser sends this itself when *it* reconnects. It is here for the
+   * reconnection this hook makes, which cannot; see the module header.
+   */
+  readonly lastEventId: string | null,
+  /** Close it. Nothing reopens until `enabled` or the URL changes. */
+  readonly close: () => void,
+  /** Whether this runtime has `EventSource` at all. */
+  readonly supported: boolean,
+|};
+
+const DEFAULT_RETRY = 1_000;
+const DEFAULT_MAX_RETRY = 30_000;
+
+/**
+ * Subscribe to a server-sent event stream.
+ *
+ * `url` is re-read when it changes, and a changed URL is a new connection —
+ * which is what makes the resume in the module header work at all. Pass `null`
+ * to connect to nothing, which is how a stream that depends on something not
+ * loaded yet waits without a second hook.
+ */
+export hook useEventSource(url: string | null, options?: EventSourceOptions): UseEventSourceReturn {
+  const supported = useSupported(() => streamConstructor() != null);
+  const [status, setStatus] = useState<EventStreamStatus>("idle");
+  const [last, setLast] = useState<ServerEvent | null>(null);
+  const [lastEventId, setLastEventId] = useState<string | null>(null);
+  // Bumped to ask for a new connection, which is the only thing that can
+  // reopen one the browser has given up on: `EventSource` in `CLOSED` cannot
+  // be restarted, so the effect has to run again with a new object.
+  const [attempt, setAttempt] = useState(0);
+  const [stopped, setStopped] = useState(false);
+
+  const onEvent = options?.onEvent;
+  const stable = useStableCallback((event: ServerEvent) => {
+    onEvent?.(event);
+  });
+
+  // The names are carried as one string rather than as the array the caller
+  // passed, and rebuilt inside the effect from it. An array literal in a
+  // render is a new array every time, so depending on one would tear the
+  // connection down on every keystroke anywhere in the component — and a ref
+  // written during a render is the other way to get this wrong, which this
+  // package's header rules out.
+  const key = (options?.events ?? []).join(",");
+  const withCredentials = options?.withCredentials === true;
+  const retryDelay = options?.retryDelay ?? DEFAULT_RETRY;
+  const maxRetryDelay = options?.maxRetryDelay ?? DEFAULT_MAX_RETRY;
+  // How many times *this hook* has reopened since the last success. Not
+  // `attempt`, which also moves for a URL change, and not state, because
+  // resetting it on `open` must not be a render.
+  const backoff = useRef(0);
+
+  const enabled = (options?.enabled ?? true) && !stopped;
+
+  useEffect(() => {
+    const Constructor = streamConstructor();
+    if (Constructor == null || url == null || !enabled) {
+      setStatus(stopped ? "closed" : "idle");
+      return;
+    }
+
+    const source = new Constructor(url, { withCredentials });
+    setStatus("connecting");
+    let reopen: TimeoutID | null = null;
+
+    const onOpen = () => {
+      // The delay is reset here rather than on the first message: a stream
+      // that connects and sends nothing for an hour has still connected, and
+      // treating it as a failure would put the next real outage at the top of
+      // the backoff.
+      backoff.current = 0;
+      setStatus("open");
+    };
+
+    const onMessage = (name: string) => (event: StreamEvent) => {
+      const sent = event.lastEventId;
+      const id = typeof sent === "string" && sent !== "" ? sent : null;
+      const received: ServerEvent = { name, data: String(event.data ?? ""), id };
+      setLast(received);
+      if (id != null) {
+        setLastEventId(id);
+      }
+      stable(received);
+    };
+
+    const onError = () => {
+      if (source.readyState !== CLOSED) {
+        // The browser is retrying on its own, with `Last-Event-ID`, which is
+        // strictly better than anything this hook can do. Say so and wait.
+        setStatus("connecting");
+        return;
+      }
+      // It has given up — a non-200, or a body that was not an event stream.
+      // Nothing reopens this object, so a new one is asked for on a delay.
+      setStatus("connecting");
+      const wait = Math.min(retryDelay * 2 ** backoff.current, maxRetryDelay);
+      backoff.current += 1;
+      reopen = setTimeout(() => setAttempt((count) => count + 1), wait);
+    };
+
+    const listeners: Array<[string, (event: StreamEvent) => mixed]> = [
+      ["message", onMessage("message")],
+    ];
+    for (const name of key === "" ? [] : key.split(",")) {
+      listeners.push([name, onMessage(name)]);
+    }
+
+    source.addEventListener("open", onOpen);
+    source.addEventListener("error", onError);
+    for (const [name, listener] of listeners) {
+      source.addEventListener(name, listener);
+    }
+
+    return () => {
+      if (reopen != null) {
+        clearTimeout(reopen);
+      }
+      source.removeEventListener("open", onOpen);
+      source.removeEventListener("error", onError);
+      for (const [name, listener] of listeners) {
+        source.removeEventListener(name, listener);
+      }
+      // Closed as well as unsubscribed: an `EventSource` nobody is listening
+      // to still holds a connection and still reconnects, so leaving it open
+      // is a socket per navigation for the life of the tab.
+      source.close();
+    };
+    // `key` stands in for `options.events`, and `attempt` is what a reopen
+    // moves. `backoff` is a ref, and `stable` never changes identity.
+  }, [url, enabled, stopped, key, attempt, retryDelay, maxRetryDelay, withCredentials, stable]);
+
+  const close = useCallback(() => {
+    setStopped(true);
+  }, []);
+
+  return useMemo(
+    () => ({ status, last, lastEventId, close, supported }),
+    [status, last, lastEventId, close, supported],
+  );
+}

package/index.js

@@ -32,6 +32,12 @@
 // its sidebar under 48rem wants `false` on the server and one that renders a
 // mobile menu wants `true`, and a library cannot know which.
 //
+// Where there is exactly one honest answer, the caller is not asked. `useHash`
+// takes no server value because the browser strips the fragment before the
+// request goes out, so `""` is not a default standing in for something better —
+// it is what the server knows, and offering an override would have invited a
+// caller to state a value that cannot be true.
+//
 // The hooks built on effects rather than stores — everything in `dom.js`, and
 // the three in `browser.js` whose first value only arrives in a callback — do
 // nothing at all before hydration, and report the same starting value on both
@@ -50,7 +56,7 @@
 //
 // # How the package is laid out
 //
-// Eight modules beside this one, split by what a hook's subject is — because
+// Nine modules beside this one, split by what a hook's subject is — because
 // that is the question a reader looking for one actually asks:
 //
 // - `lifecycle.js` — the component itself: mounted, previous, run once.
@@ -58,14 +64,22 @@
 //   toggle, counter, list, set, cycle, undo/redo, storage.
 // - `timing.js` — when something runs: intervals, timeouts, debounce,
 //   throttle, frames, idleness, and the clock behind "3 minutes ago".
+// - `render.js` — what a render has to fix rather than derive: the instant it
+//   was made at, and the seed anything random on the page is drawn from.
 // - `async.js` — one promise: its states, its abort signal, its retries.
 // - `browser.js` — the ambient environment: viewport, scroll, connection,
-//   position, permissions, preferences.
+//   position, permissions, preferences, the fragment in the address bar. Its
+//   header carries the table of what every one of them renders before
+//   hydration.
 // - `dom.js` — one element the caller holds a ref to: listen, measure,
 //   observe, press.
 // - `keyboard.js` — what is being pressed: a chord, and a held key.
 // - `channels.js` — a value that came from outside the page: another tab, the
 //   system clipboard.
+// - `events.js` — a stream the server is pushing, and where its reconnection
+//   is. Not `channels.js`, whose boundary is deliberately everything except
+//   the server, and not `@uniflowed/query`, because there is no cache entry
+//   and nothing to revalidate: a connection is a third thing.
 //
 // The two that are easiest to confuse are `browser.js` and `dom.js`, so each
 // says so in its own header: `browser.js` needs no ref because there is one
@@ -90,11 +104,14 @@
 // **Implemented and tested.** The component's life; the state shapes; every
 // timer, including the adaptive schedule behind `useTimeAgo`; `useAsync` with
 // abort and retry; media queries, colour scheme, reduced motion, online,
-// document visibility, window size and scroll, scroll lock; element size,
+// document visibility, window size and scroll, the address bar's fragment,
+// scroll lock; element size,
 // intersection, mutations, hover, focus-within, click-outside, long press,
 // element scroll, the element as state; key chords and held keys; storage with
 // cross-tab sync;
-// broadcast channels; the clipboard. `tests/library/hooks.test.js` covers
+// broadcast channels; the clipboard; a server-sent event stream, including the
+// one case the platform's own reconnection gives up on; the render anchor and
+// the seeded stream in `render.js`. `tests/library/hooks.test.js` covers
 // behaviour and cleanup, and `tests/library/hooks-ssr.test.js` renders the
 // whole surface in a process that has no DOM at all.
 //
@@ -120,6 +137,8 @@
 
 export type { Async, AsyncOptions } from "./async.js";
 export type {
+  BrowserHistory,
+  BrowserLocation,
   BrowserNavigator,
   BrowserWindow,
   EffectiveConnectionType,
@@ -127,6 +146,7 @@ export type {
   Geoposition,
   Network,
   NetworkConnection,
+  NetworkMeasurement,
   PermissionAnswer,
   PermissionName,
   ScrollOffset,
@@ -134,7 +154,14 @@ export type {
 } from "./browser.js";
 export type { UseBroadcastReturn, UseClipboardReturn } from "./channels.js";
 export type { ListenerOptions, ListenerTarget, MutationOptions, Ref } from "./dom.js";
+export type {
+  EventSourceOptions,
+  EventStreamStatus,
+  ServerEvent,
+  UseEventSourceReturn,
+} from "./events.js";
 export type { KeyComboOptions } from "./keyboard.js";
+export type { RenderEnvelope } from "./render.js";
 export type {
   UseCounterReturn,
   UseCycleReturn,
@@ -169,6 +196,7 @@ export {
   browserWindow,
   useDocumentVisible,
   useGeolocation,
+  useHash,
   useMediaQuery,
   useNetwork,
   useOnline,
@@ -194,7 +222,17 @@ export {
   useScroll,
 } from "./dom.js";
 export { useKeyCombo, useKeyHeld } from "./keyboard.js";
+export {
+  RENDER_ID,
+  RenderProvider,
+  useRandom,
+  useRenderEnvelope,
+  useRenderTimeZone,
+  useRenderedAt,
+  useShuffled,
+} from "./render.js";
 export { useBroadcast, useClipboard } from "./channels.js";
+export { useEventSource } from "./events.js";
 export {
   useCounter,
   useCycle,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/hooks",
-  "version": "0.0.0-alpha.11",
+  "version": "0.0.0-alpha.13",
   "description": "The React hooks an application writes anyway, prerender-safe, part of the Unified Toolchain for Flow.",
   "type": "module",
   "license": "MIT",
@@ -16,8 +16,10 @@
     "./browser": "./browser.js",
     "./channels": "./channels.js",
     "./dom": "./dom.js",
+    "./events": "./events.js",
     "./keyboard": "./keyboard.js",
     "./lifecycle": "./lifecycle.js",
+    "./render": "./render.js",
     "./state": "./state.js",
     "./timing": "./timing.js"
   },
@@ -25,7 +27,8 @@
     "*.js"
   ],
   "dependencies": {
-    "@uniflowed/react": "0.0.0-alpha.11"
+    "@uniflowed/core": "0.0.0-alpha.13",
+    "@uniflowed/react": "0.0.0-alpha.13"
   },
   "peerDependencies": {
     "react": ">=19"

package/render.js

@@ -0,0 +1,274 @@
+// @flow
+//
+// `@uniflowed/hooks/render`: the two things a render must decide once.
+//
+// A page that is prerendered is rendered twice — once on a server, once in the
+// browser that hydrates it — and React compares the two. Anything the second
+// render works out for itself differs from the first, and the two that differ
+// in practice are the clock and the random number generator. `new Date()` is a
+// different instant on the two machines and `Math.random()` is a different
+// number by construction, so a countdown, a greeting that depends on the hour,
+// a shuffled list of featured articles and a randomly chosen placeholder are
+// each a hydration mismatch that the application did nothing to deserve.
+//
+// The usual advice is to render nothing until an effect has run. That works,
+// and it costs the page: the value is invisible to a crawler and to a reader
+// with no JavaScript, and it arrives one frame late and moves the layout when
+// it does.
+//
+// This module is the other answer. The render decides both values once, on
+// whichever side goes first, and the other side reads what was decided instead
+// of deciding again. Both renders then produce the same markup, because they
+// are working from the same two numbers.
+//
+// # Why a provider, and not module state
+//
+// A clock installed in `@uniflowed/core/clock` is the process's. That is right
+// for a test and for a runtime, and wrong for a server: a server renders
+// several requests at once, and two responses that shared one "rendered at"
+// would each be stamped with whenever the other one started. React's context is
+// per-render by construction, which is the granularity this actually needs, so
+// the values travel through the tree rather than beside it.
+//
+// # How the value crosses the network
+//
+// `RenderProvider` writes what it decided into the markup, as an inert
+// `<script type="application/json">`, and reads it back on the client before
+// the first render — the same carrier and the same escaping
+// `@uniflowed/router` uses for loader data, because it is the same problem and
+// a second mechanism would be a second thing to get wrong. `dangerouslySetInnerHTML`
+// rather than a text child, because the HTML parser treats a `<script>` body as
+// raw text and does not decode entities: React's escaping of `&` would survive
+// into `JSON.parse` and fail there.
+//
+// A page nobody prerendered has no script to read, decides both values from the
+// host, and is correct for the reason that there is nothing to disagree with.
+//
+// # What belongs in this module
+//
+// A value that a render has to fix rather than derive. Two so far, and they are
+// the two React itself has an answer for exactly one of: `useId` solves ids by
+// deriving them from the position in the tree, which works for an id and for
+// nothing that has to be shuffled or counted from.
+//
+// Not here: a hook that reads a clock to schedule work. `useInterval`,
+// `useTimeout` and `useNow` are `timing.js`'s, and they read the *current* time
+// — this module is about the one instant that must not move.
+
+import * as React from "@uniflowed/react";
+import { currentClock } from "@uniflowed/core/clock";
+import type { Random } from "@uniflowed/core/random";
+import { hostSeed, seededRandom, shuffled } from "@uniflowed/core/random";
+import type { Instant } from "@uniflowed/core/temporal";
+import { Temporal } from "@uniflowed/core/temporal";
+
+/** What a render fixes, and what travels to the client. */
+export type RenderEnvelope = {
+  /** The instant the render was anchored to, in epoch milliseconds. */
+  readonly at: number,
+  /** The IANA zone the server was in. Not the reader's — see `Time`. */
+  readonly timeZone: string,
+  /** The seed both sides replay the same numbers from. */
+  readonly seed: string,
+};
+
+/** The element the envelope is written into, and read back out of. */
+export const RENDER_ID: string = "__uf_render";
+
+const RenderContext: React.Context<RenderEnvelope | null> = React.createContext(null);
+
+/**
+ * The envelope the server left in the document, if there is one.
+ *
+ * Read from the DOM rather than from a global an inline script assigned,
+ * because an inline script that runs is a script a content-security policy has
+ * to allow, and this value is worth no relaxation of one.
+ */
+function embedded(): RenderEnvelope | null {
+  const document = globalThis.document;
+  if (document == null) {
+    return null;
+  }
+  const element = document.getElementById(RENDER_ID);
+  if (element == null) {
+    return null;
+  }
+  try {
+    const found = JSON.parse(element.textContent ?? "null");
+    if (found == null || typeof found.at !== "number" || typeof found.seed !== "string") {
+      return null;
+    }
+    return { at: found.at, timeZone: String(found.timeZone), seed: found.seed };
+  } catch {
+    // A truncated document — a stream that was cut off — leaves half a JSON
+    // object here. Deciding fresh values is wrong on that page in exactly the
+    // way this module exists to prevent, and it is still better than a render
+    // that throws: the page renders, and hydration reports what it always
+    // would have.
+    return null;
+  }
+}
+
+/** Decide what this render is anchored to, from props, from the markup, or from the host. */
+function envelope(given: { at?: number, timeZone?: string, seed?: string }): RenderEnvelope {
+  const found = embedded();
+  const clock = currentClock();
+  return {
+    at: given.at ?? found?.at ?? clock.now(),
+    timeZone: given.timeZone ?? found?.timeZone ?? clock.timeZone(),
+    seed: given.seed ?? found?.seed ?? hostSeed(),
+  };
+}
+
+/**
+ * `envelope` as the text of a `<script type="application/json">`.
+ *
+ * `<` is escaped so that a zone name or a seed holding `</script>` cannot end
+ * the element early, and the two line separators are escaped because they are
+ * newlines to a JavaScript parser and are not to `JSON.stringify`. The same
+ * three replacements `@uniflowed/router` makes, deliberately duplicated rather
+ * than shared: this package does not depend on the router, and three lines are
+ * not worth an import that would drag one in.
+ */
+function encode(value: RenderEnvelope): string {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+/**
+ * Fix this render's instant, zone and seed, and hand them to the tree.
+ *
+ * Render it once, above everything that reads a clock — a root layout is where
+ * it belongs. Every argument is optional and the defaults are the whole point:
+ * a server decides, the markup carries what it decided, and the browser reads it
+ * back before its first render, so neither side has to be told which one it is.
+ *
+ * `at` and `seed` are there for the two cases that are not that. A test passes
+ * them to get a page that renders the same bytes every time; an application
+ * whose instant comes from somewhere better — a request header, a loader —
+ * passes that instead.
+ *
+ * `security/no-dangerously-set-inner-html` is suppressed on the one line that
+ * needs it, and the argument is narrow enough to state exactly. The rule is
+ * about markup that came from somewhere — a comment, a profile, a response —
+ * and its escape hatch is a `@uniflowed/markdown` sanitizer, which is the right
+ * answer for markup and no answer at all for JSON. What is written here is
+ * three fields this module produced: two of them are typed `number` and
+ * `string` and all three go through `JSON.stringify` and then `encode`, which
+ * removes the only three characters that can end a `<script>` early or split a
+ * line inside one. There is also no other spelling — the HTML parser reads a
+ * `<script>` body as raw text and does not decode entities, so React's escaping
+ * of a text child would survive into `JSON.parse` and fail there.
+ */
+export component RenderProvider(
+  at?: number,
+  timeZone?: string,
+  seed?: string,
+  children: React.Node,
+) {
+  // The initializer runs once per mount, on both sides, which is what makes
+  // this a fixed value rather than a clock: a re-render for any other reason
+  // must not move the instant the page has already been drawn with.
+  const [value] = React.useState(() => envelope({ at, timeZone, seed }));
+
+  return (
+    <RenderContext.Provider value={value}>
+      <script
+        id={RENDER_ID}
+        type="application/json"
+        // uf-lint-disable-next-line security/no-dangerously-set-inner-html
+        dangerouslySetInnerHTML={{ __html: encode(value) }}
+      />
+      {children}
+    </RenderContext.Provider>
+  );
+}
+
+/**
+ * What this render was anchored to, or `null` outside a `RenderProvider`.
+ *
+ * Null rather than a fabricated envelope, because "nobody fixed these values"
+ * is a fact the hooks in `timing.js` act on: without a provider they read the
+ * clock, which is the behaviour they have always had.
+ */
+export hook useRenderEnvelope(): RenderEnvelope | null {
+  return React.useContext(RenderContext);
+}
+
+/**
+ * The instant this page was rendered at, as a `Temporal.Instant`.
+ *
+ * Constant for the life of the render, on both sides, which is what makes it
+ * safe to put in the markup. It is not "now" and does not become "now": a page
+ * left open for an hour still reports the instant it was rendered at, and a
+ * label that has to stay true while the reader looks at it is `useTimeAgo`.
+ *
+ * Falls back to the clock outside a provider, which is right for a page that is
+ * only ever rendered once — and is a hydration mismatch on one that is
+ * prerendered, which is what the provider is for.
+ */
+export hook useRenderedAt(): Instant {
+  const found = useRenderEnvelope();
+  const at = found?.at;
+  // The number, not the instant, in the dependency: `Instant` is a new object
+  // every render and depending on it would rebuild this on every one.
+  const clockAt = at ?? currentClock().now();
+  return React.useMemo(() => Temporal.Instant.fromEpochMilliseconds(clockAt), [clockAt]);
+}
+
+/**
+ * The zone the render was made in.
+ *
+ * The server's, not the reader's, and the distinction is the second half of the
+ * hydration problem rather than a detail: markup formatted in the reader's zone
+ * cannot match markup formatted in the server's, so a component renders this one
+ * and localises after hydration. `@uniflowed/web`'s `Time` is that component.
+ */
+export hook useRenderTimeZone(): string {
+  const found = useRenderEnvelope();
+  return found?.timeZone ?? currentClock().timeZone();
+}
+
+/**
+ * A stream of random numbers that both renders produce identically.
+ *
+ * `label` names the stream, and naming it is what makes it independent of every
+ * other one: two components that ask for `"featured"` and `"sidebar"` get the
+ * same numbers whatever order they render in, and whatever suspends between
+ * them. Sharing one stream would make each component's numbers depend on how
+ * many the components above it happened to draw — stable in a synchronous
+ * render, and not stable once a boundary resolves at a different moment on the
+ * two sides.
+ *
+ * The stream is stateful, so a component that draws from it during render draws
+ * different numbers on a re-render. Draw in a `useMemo` keyed by what the
+ * numbers are for, or in an event, and never in the body of a component React
+ * may render twice.
+ *
+ * Outside a provider the seed is a constant rather than the host's, which looks
+ * like the wrong default and is the right one: two renders with no envelope
+ * between them still have to agree, and a constant is the only seed both of them
+ * can arrive at. What it costs is that every such page shuffles the same way,
+ * which is a reason to render a provider rather than a reason to be
+ * unpredictable here.
+ */
+export hook useRandom(label: string): Random {
+  const found = useRenderEnvelope();
+  const seed = found?.seed;
+  return React.useMemo(() => seededRandom(seed ?? "uf").fork(label), [seed, label]);
+}
+
+/**
+ * `items`, shuffled the same way on both sides of a hydration.
+ *
+ * The shuffle is a `useMemo` over the seed, the label and the items, so it is
+ * one shuffle rather than one per render — which matters for more than speed:
+ * a fresh draw on every render would reorder the list under the reader every
+ * time anything else on the page changed.
+ */
+export hook useShuffled<T>(items: $ReadOnlyArray<T>, label: string): Array<T> {
+  const random = useRandom(label);
+  return React.useMemo(() => shuffled(items, random), [items, random]);
+}

package/timing.js

@@ -32,11 +32,27 @@
 // `@uniflowed/web` to get there, because a hook library that pulled in a
 // component library would be the wrong direction for the one arrow between
 // them.
+//
+// # Where the time comes from
+//
+// Not from `Date.now()`. Every read in this module goes through
+// `@uniflowed/core/clock`, which is a seam a test, a server or a runtime can
+// put its own clock behind — so "3 minutes ago" is a value a test can assert
+// rather than a value it has to wait three minutes for, and a server render is
+// reproducible rather than being stamped with whenever it happened to run.
+//
+// A throttle measured against an installed clock is a throttle that does not
+// elapse while that clock is stopped. That is not a defect to work around: a
+// fixed clock means time is not passing, and a rate limit that fired anyway
+// would be measuring something other than the time the caller said it was.
+// `manualClock` is the one to install when a test wants the window to close.
 
 import { useEffect, useMemo, useRef, useState } from "@uniflowed/react";
+import { currentClock } from "@uniflowed/core/clock";
 
 import { browserWindow } from "./browser.js";
 import { useMounted, useStableCallback } from "./lifecycle.js";
+import { useRenderEnvelope } from "./render.js";
 
 /**
  * Call `body` every `millis`, or not at all when `millis` is null.
@@ -103,7 +119,7 @@ export hook useThrottledCallback<TArgs extends $ReadOnlyArray<mixed>>(
   const last = useRef(0);
 
   return useStableCallback<TArgs, void>((...args: TArgs) => {
-    const now = Date.now();
+    const now = currentClock().now();
     if (now - last.current >= millis) {
       last.current = now;
       stable(...args);
@@ -262,26 +278,39 @@ export hook useIdle(
  * bounded: it happens once, the value is never re-read during a render, and a
  * render React throws away is replaced by another whose clock is just as valid.
  *
- * A prerendered page that puts this on screen needs `serverValue`, because the
- * server's clock and the reader's are not the same number and React compares
- * the text. Given one, the first render on both sides is that value and the
- * real time arrives with the first effect. `useTimeAgo` has already made this
- * choice; prefer it for a label.
+ * On a prerendered page the two renders are at two different instants, so the
+ * first one on each side has to be the *same* instant or React reports a
+ * mismatch. Under a `RenderProvider` that happens by itself — the anchor the
+ * server fixed travels in the markup, both sides start from it, and the real
+ * time arrives with the first effect. `serverValue` is the same choice made by
+ * hand, for a caller who has the instant from somewhere else and for a tree
+ * with no provider above it; it wins over the anchor when both are there,
+ * because an argument at the call site is a decision and a context is a
+ * default.
+ *
+ * A `Date` rather than a `Temporal.Instant`, and deliberately: this value's
+ * consumers subtract it from another one to decide when to run again, which is
+ * millisecond arithmetic on a number. The Temporal-shaped reading of the same
+ * anchor is `useRenderedAt` in `render.js`, and rendering an instant is
+ * `@uniflowed/web`'s `Time`.
  */
 export hook useNow(millis: number | null = 1000, serverValue: Date | null = null): Date {
   // The instant rather than the object: a caller writing `new Date(...)` in
   // the call passes a different object every render, and a dependency on it
   // would re-run the effect forever.
-  const since = serverValue == null ? null : serverValue.getTime();
-  const [now, setNow] = useState<Date>(() => (since == null ? new Date() : new Date(since)));
+  const anchored = useRenderEnvelope()?.at ?? null;
+  const since = serverValue == null ? anchored : serverValue.getTime();
+  const [now, setNow] = useState<Date>(
+    () => new Date(since == null ? currentClock().now() : since),
+  );
 
   useEffect(() => {
     if (since != null) {
-      setNow(new Date());
+      setNow(new Date(currentClock().now()));
     }
   }, [since]);
 
-  useInterval(() => setNow(new Date()), millis);
+  useInterval(() => setNow(new Date(currentClock().now())), millis);
   return now;
 }