@ultimat3/realtime 20.2.1 → 21.0.0

package/src/sync-protocol.ts

@@ -1,14 +1,15 @@
-// The wire. One protocol for all three tiers: a channel subscribe, a live-query subscribe, and an
-// offline mutation drain are frames in the same union — so moving a route from tier 2 to tier 3
-// needs no new protocol, and THAT is the half this file enforces.
-// It is not a `persist: true` config flag: this header said so until 2026-09 and `query()` has
-// never accepted the key (`local-store.ts` records the same). Tier 3 is reached by passing a
-// `LocalStore` to the live client, which is a client-side wiring decision this file cannot see —
-// claiming to enforce it here is the declared-and-never-wired shape the repo keeps re-shipping.
-
-import { renderThrowable, stringField } from '@ultimat3/core';
-import { CURSOR_ID_LIMIT, type LiveCursor } from './cursor';
-import { ProtocolVersionError } from './errors';
+// The wire, READ-ONLY for the client: channel and live-query subscriptions go up, snapshots,
+// patches, presence and refusals come down. A client write is HTTP (`useMutation`), never a frame —
+// so there is one write path, with the action's authz, idempotency store and contract behind it.
+
+import { renderThrowable, stringField } from '@ultimat3/core/page';
+import type {
+  ChannelEventsFrame,
+  ChannelRecordsFrame,
+  ChannelSubscribeTarget,
+  ReplayGapFrame,
+} from './channel-wire';
+import type { LiveCursor } from './cursor';
 import {
   isJsonObject,
   isRow,
@@ -17,41 +18,19 @@ import {
   type Row,
   type RowPatch,
 } from './json';
-
-/**
- * **2 since 2026-08-24**, when `cursor.digest` and `cursor.count` were deleted. The version guards
- * incompatibility, never novelty — an additive optional field (`snapshot.entity`) and a removed
- * field read through `list()` (`hello.resume`) both stayed at 1, because `decode` is a whitelist
- * and `list()` answers `[]` for an absent field. `cursor()` is the other kind of reader: it reads
- * through `str`/`num`, which THROW on an absent field, so a cursor without those two is a frame a
- * node or a client one deploy behind cannot read — in BOTH directions, since a cursor rides the
- * client's `subscribe` and the node's `snapshot`. That is exactly what this number refuses, with
- * one instruction instead of a per-frame "field \"digest\" must be a string".
- */
-export const PROTOCOL_VERSION = 2;
-
-/**
- * What one frame may contain. Hard ceilings a caller cannot widen — the shape
- * `packages/mcp/src/query-limits.ts` uses — because every one of them is read off a socket the
- * node has already paid for: an unbounded `cursor.ids` was consumed raw into a `Set`, and an
- * `input` of arbitrary depth reached `canonicalJson`, which recurses.
- *
- * Every number clears what this node itself produces, or the decoder refuses its own frames on
- * the next reconnect: `cursorIds` is `CURSOR_ID_LIMIT`, `patches` clears
- * `defaultReconnectBudget.maxPatches`.
- */
-export const FRAME_LIMITS = Object.freeze({
-  cursorIds: CURSOR_ID_LIMIT,
-  patches: 4_096,
-  rows: 10_000,
-  members: 4_096,
-  /** Nesting one `input` may reach. 32 is far past any query's real argument shape. */
-  inputDepth: 32,
-  /** Values one `input` may hold in total, so a flat-but-enormous object is refused too. */
-  inputNodes: 10_000,
-});
-
-export type ConflictStrategyName = 'server-wins' | 'last-write-wins' | 'custom';
+import { ProtocolVersionError } from './page-errors';
+import { channelTarget, events, records, replayGap } from './wire-channel';
+import { bounded, fail, list, nullableStr, num, object, pick, str } from './wire-read';
+import { FRAME_LIMITS, PROTOCOL_VERSION } from './wire-version';
+
+export type {
+  ChannelEventsFrame,
+  ChannelRecordsFrame,
+  ChannelSubscribeTarget,
+  ReplayGapFrame,
+} from './channel-wire';
+/** The version and the ceilings live below this file so the readers can share them without a cycle. */
+export { FRAME_LIMITS, PROTOCOL_VERSION } from './wire-version';
 
 export interface WireError {
   readonly code: string;
@@ -69,7 +48,8 @@ export interface PresenceMember {
 }
 
 export type SubscribeTarget =
-  | { readonly kind: 'topic'; readonly topic: string }
+  /** A declared `channel()`: its NAME and params, never a topic string the client spelled. */
+  | ChannelSubscribeTarget
   | {
       /**
        * Client -> server, `qid` carries the *query name*; the server derives the real qid from
@@ -124,6 +104,12 @@ export interface SnapshotFrame {
    * skews are safe in both directions, which is why it carries no `PROTOCOL_VERSION` bump.
    */
   readonly entity?: string;
+  /**
+   * Each row's RECORD key, parallel to `rows`, sent only when some key is not its row's `id` (a
+   * composite primary key). The server renders it with the entity's projection; the browser never
+   * derives a key.
+   */
+  readonly keys?: readonly string[];
 }
 
 export interface PatchFrame {
@@ -134,51 +120,18 @@ export interface PatchFrame {
   readonly lsn: string;
 }
 
-export interface MutateFrame {
-  readonly type: 'mutate';
-  readonly v: number;
-  /** Idempotency key. The server collapses repeats; the client never renumbers. */
-  readonly key: string;
-  readonly seq: number;
-  readonly name: string;
-  readonly input: JsonValue;
-}
-
 export interface AckFrame {
   readonly type: 'ack';
   readonly v: number;
-  /** Mutation key or subscription id being acknowledged. */
+  /**
+   * What a refusal refers to: the sid of a subscription the node refused, or the socket id for a
+   * frame it could not read at all. The socket carries no writes, so an ack is never a receipt.
+   */
   readonly ref: string;
   readonly lsn: string | null;
   readonly error: WireError | null;
 }
 
-export interface RebaseFrame {
-  readonly type: 'rebase';
-  readonly v: number;
-  readonly key: string;
-  readonly entity: string;
-  readonly strategy: ConflictStrategyName;
-  /** Server truth for the row the mutation touched; `null` when the server deleted it. */
-  readonly row: Row | null;
-}
-
-export interface PresenceFrame {
-  readonly type: 'presence';
-  readonly v: number;
-  readonly topic: string;
-  readonly op: 'join' | 'leave' | 'update' | 'sync';
-  readonly members: readonly PresenceMember[];
-  /**
-   * Members in the whole set behind a `sync` frame, which is capped: a 5,000-avatar row is not a UI
-   * anyone renders, and the count is what lets a client say "and 4,744 others" without holding
-   * them. Optional and **additive**, exactly like `snapshot.entity`: an old node omits it and a new
-   * one reads its absence as "this frame is the whole set", so neither skew is unreadable and
-   * `PROTOCOL_VERSION` does not move. Never set on a `join`/`leave`/`update` — those are deltas.
-   */
-  readonly total?: number;
-}
-
 export interface ReconnectFrame {
   readonly type: 'reconnect';
   readonly v: number;
@@ -198,12 +151,12 @@ export type Frame =
   | SubscribeFrame
   | SnapshotFrame
   | PatchFrame
-  | MutateFrame
   | AckFrame
-  | RebaseFrame
-  | PresenceFrame
   | ReconnectFrame
-  | UpdateAvailableFrame;
+  | UpdateAvailableFrame
+  | ChannelRecordsFrame
+  | ChannelEventsFrame
+  | ReplayGapFrame;
 
 export type FrameKind = Frame['type'];
 
@@ -212,12 +165,12 @@ export const FRAME_KINDS: readonly FrameKind[] = [
   'subscribe',
   'snapshot',
   'patch',
-  'mutate',
   'ack',
-  'rebase',
-  'presence',
   'reconnect',
   'update-available',
+  'records',
+  'events',
+  'replay-gap',
 ];
 
 export function encode(frame: Frame): string {
@@ -265,7 +218,14 @@ export function decode(raw: string | Uint8Array): Frame {
         cursor: cursor(parsed['cursor']),
       } as const;
       const entity = nullableStr(parsed, 'entity');
-      return entity === null ? base : { ...base, entity };
+      const scoped = entity === null ? base : { ...base, entity };
+      if (parsed['keys'] === undefined) return scoped;
+      const keys = list(parsed, 'keys', FRAME_LIMITS.rows).map((key) => {
+        if (typeof key !== 'string') throw fail('snapshot.keys must hold strings');
+        return key;
+      });
+      if (keys.length !== base.rows.length) throw fail('snapshot.keys must pair with rows');
+      return { ...scoped, keys };
     }
     case 'patch':
       return {
@@ -275,15 +235,6 @@ export function decode(raw: string | Uint8Array): Frame {
         patches: list(parsed, 'patches', FRAME_LIMITS.patches).map(patch),
         lsn: str(parsed, 'lsn'),
       };
-    case 'mutate':
-      return {
-        type: 'mutate',
-        v: PROTOCOL_VERSION,
-        key: str(parsed, 'key'),
-        seq: num(parsed, 'seq'),
-        name: str(parsed, 'name'),
-        input: bounded(parsed['input'] ?? null, 'input'),
-      };
     case 'ack':
       return {
         type: 'ack',
@@ -292,25 +243,6 @@ export function decode(raw: string | Uint8Array): Frame {
         lsn: nullableStr(parsed, 'lsn'),
         error: wireError(parsed['error']),
       };
-    case 'rebase':
-      return {
-        type: 'rebase',
-        v: PROTOCOL_VERSION,
-        key: str(parsed, 'key'),
-        entity: str(parsed, 'entity'),
-        strategy: pick(parsed, 'strategy', ['server-wins', 'last-write-wins', 'custom'] as const),
-        row: parsed['row'] === null ? null : row(parsed['row']),
-      };
-    case 'presence': {
-      const base = {
-        type: 'presence',
-        v: PROTOCOL_VERSION,
-        topic: str(parsed, 'topic'),
-        op: pick(parsed, 'op', ['join', 'leave', 'update', 'sync'] as const),
-        members: list(parsed, 'members', FRAME_LIMITS.members).map(member),
-      } as const;
-      return parsed['total'] === undefined ? base : { ...base, total: num(parsed, 'total') };
-    }
     case 'reconnect':
       return {
         type: 'reconnect',
@@ -320,6 +252,12 @@ export function decode(raw: string | Uint8Array): Frame {
       };
     case 'update-available':
       return { type: 'update-available', v: PROTOCOL_VERSION, buildId: str(parsed, 'buildId') };
+    case 'records':
+      return records(parsed);
+    case 'events':
+      return events(parsed);
+    case 'replay-gap':
+      return replayGap(parsed);
     default:
       throw fail(`unknown frame type ${JSON.stringify(kind)}`);
   }
@@ -340,80 +278,6 @@ export function toWireError(error: unknown): WireError {
   return docs === undefined ? { code, cause, fix } : { code, cause, fix, docs };
 }
 
-function fail(detail: string): ProtocolVersionError {
-  return new ProtocolVersionError({ got: detail, expected: PROTOCOL_VERSION, detail });
-}
-
-function str(obj: JsonObject, key: string): string {
-  const value = obj[key];
-  if (typeof value !== 'string') throw fail(`field "${key}" must be a string`);
-  return value;
-}
-
-function nullableStr(obj: JsonObject, key: string): string | null {
-  const value = obj[key];
-  if (value === null || value === undefined) return null;
-  if (typeof value !== 'string') throw fail(`field "${key}" must be a string or null`);
-  return value;
-}
-
-function num(obj: JsonObject, key: string): number {
-  const value = obj[key];
-  if (typeof value !== 'number' || !Number.isFinite(value)) {
-    throw fail(`field "${key}" must be a finite number`);
-  }
-  return value;
-}
-
-function pick<T extends string>(obj: JsonObject, key: string, allowed: readonly T[]): T {
-  const value = str(obj, key);
-  const found = allowed.find((candidate) => candidate === value);
-  if (found === undefined) throw fail(`field "${key}" must be one of ${allowed.join('|')}`);
-  return found;
-}
-
-/**
- * An array field, with the ceiling the caller had to choose. `max` is required rather than
- * defaulted: a new list field on a new frame is a new thing an authenticated socket can make
- * arbitrarily large, and a default would let one ship without anyone deciding its size.
- */
-function list(obj: JsonObject, key: string, max: number, label = key): JsonValue[] {
-  const value = obj[key];
-  if (value === undefined || value === null) return [];
-  if (!Array.isArray(value)) throw fail(`field "${label}" must be an array`);
-  if (value.length > max) {
-    throw fail(`field "${label}" carries ${value.length} entries, over the limit of ${max}`);
-  }
-  return value;
-}
-
-/**
- * A client-supplied value, walked ITERATIVELY to its limits. Iteratively because the thing being
- * refused is a stack overflow: `queryHash` -> `canonicalJson` recurses over exactly this value, so a
- * depth check that recursed would be the same crash one frame earlier.
- */
-function bounded(value: JsonValue, label: string): JsonValue {
-  const stack: { node: JsonValue; depth: number }[] = [{ node: value, depth: 1 }];
-  let seen = 0;
-  while (stack.length > 0) {
-    // `pop` cannot answer undefined here — the loop guard is the length — and the check is what
-    // makes that readable to the compiler without a cast.
-    const next = stack.pop();
-    if (next === undefined) break;
-    seen += 1;
-    if (seen > FRAME_LIMITS.inputNodes) {
-      throw fail(`field "${label}" holds more than ${FRAME_LIMITS.inputNodes} values`);
-    }
-    if (next.depth > FRAME_LIMITS.inputDepth) {
-      throw fail(`field "${label}" is nested deeper than ${FRAME_LIMITS.inputDepth}`);
-    }
-    if (next.node === null || typeof next.node !== 'object') continue;
-    const children = Array.isArray(next.node) ? next.node : Object.values(next.node);
-    for (const child of children) stack.push({ node: child, depth: next.depth + 1 });
-  }
-  return value;
-}
-
 function row(value: unknown): Row {
   if (!isRow(value)) throw fail('row must be an object with a string "id"');
   return value;
@@ -440,23 +304,15 @@ function patch(value: unknown): RowPatch {
     row: value['row'] === null || value['row'] === undefined ? null : object(value['row']),
     lsn: str(value, 'lsn'),
   };
-  return value['index'] === undefined ? base : { ...base, index: num(value, 'index') };
-}
-
-function member(value: unknown): PresenceMember {
-  if (!isJsonObject(value)) throw fail('presence member must be an object');
-  return {
-    id: str(value, 'id'),
-    actorId: nullableStr(value, 'actorId'),
-    meta: object(value['meta'] ?? {}),
-    updatedAt: num(value, 'updatedAt'),
-  };
+  const indexed = value['index'] === undefined ? base : { ...base, index: num(value, 'index') };
+  const key = nullableStr(value, 'key');
+  return key === null ? indexed : { ...indexed, key };
 }
 
 function target(value: unknown): SubscribeTarget {
   if (!isJsonObject(value)) throw fail('subscribe.target must be an object');
-  const kind = pick(value, 'kind', ['topic', 'query'] as const);
-  if (kind === 'topic') return { kind, topic: str(value, 'topic') };
+  const kind = pick(value, 'kind', ['query', 'channel'] as const);
+  if (kind === 'channel') return channelTarget(value);
   return {
     kind,
     qid: str(value, 'qid'),
@@ -466,11 +322,6 @@ function target(value: unknown): SubscribeTarget {
   };
 }
 
-function object(value: unknown): JsonObject {
-  if (!isJsonObject(value)) throw fail('expected a JSON object');
-  return value;
-}
-
 function wireError(value: unknown): WireError | null {
   if (value === null || value === undefined) return null;
   if (!isJsonObject(value)) throw fail('ack.error must be an object or null');

package/src/sync-worker.ts

@@ -0,0 +1,12 @@
+// The SharedWorker entry (plan 101, slice 11): every tab of this origin and principal connects a
+// port, and the one engine behind them holds the one socket. `x build` bundles this file as a
+// classic script at `/_x/sync-worker/<hash>.js`. No other code lives here.
+
+import { browserSocket, dialUrl } from './browser-socket';
+import { messagePort, SocketEngine } from './socket-engine';
+
+const engine = new SocketEngine({ dial: (target) => browserSocket(dialUrl(target)) });
+
+(globalThis as { onconnect?: (event: MessageEvent) => void }).onconnect = (event) => {
+  for (const port of event.ports) engine.attach(messagePort(port));
+};

package/src/thundering-herd.ts

@@ -13,7 +13,7 @@ import {
   type JitterMode,
   type Random,
   systemClock,
-} from '@ultimat3/core';
+} from '@ultimat3/core/page';
 import { type Frame, PROTOCOL_VERSION } from './sync-protocol';
 
 /** Injected so tests are deterministic and `local` mutators stay replayable. */
@@ -40,6 +40,24 @@ export const defaultBackoff: BackoffPolicy = {
   jitter: 'full',
 };
 
+/** The longest a browser waits between two dials, whatever the attempt. */
+export const BROWSER_RECONNECT_MAX_MS = 4_000;
+
+/**
+ * A browser's redial: the same curve, capped at seconds rather than `defaultBackoff`'s thirty.
+ * Measured after a deploy — six dials in ~3s, then a full-jitter roll under a 30s cap left the
+ * node that came back (and the `update-available` it had for the tab) unreached for 27s. `equal`
+ * jitter, because at the cap it keeps a floor: a SIGKILLed node's herd redials inside a 2-4s
+ * window rather than at once, and the `AcceptBudget` sheds the excess before any query runs. A
+ * PLANNED restart never reaches this: the drain's `reconnect` frame assigns each socket its slot.
+ */
+export const browserBackoff: BackoffPolicy = {
+  baseMs: 500,
+  maxMs: BROWSER_RECONNECT_MAX_MS,
+  factor: 2,
+  jitter: 'equal',
+};
+
 /**
  * Attempt is 0-BASED. Result is always in `[0, maxMs]`.
  *

package/src/type-pins.ts

@@ -1,83 +1,52 @@
-// Compile-time pins for the typed query hook. Source, not a `.test.ts`, on purpose:
-// `tsconfig.json` excludes `src/**/*.test.ts`, so `tsc -b` never reads a test file and a
-// type-level assertion written there can never fail. This module emits nothing and exports
-// nothing anybody imports — a regression is a build error, the only enforcement that counts
-// (axiom 3). What it protects is the whole reason `liveHookFor` exists: `useLiveFeed({ orgId })`
-// carrying the query's own input and row types. Lose that and the hook still runs — it just
-// stops catching the typo that makes a subscription match nothing.
+// Compile-time pins for the hook surface. Source, not a `.test.ts`, on purpose: `tsconfig.json`
+// excludes `src/**/*.test.ts`, so `tsc -b` never reads a test file and a type-level assertion
+// written there can never fail. This module emits nothing anybody imports — a regression is a
+// build error, the only enforcement that counts (axiom 3).
 
-import type { Query } from '@ultimat3/query';
-import type { LiveClient, LiveClientLike, LiveHandle, Unsubscribe } from './client';
-import type { LiveRows } from './hooks';
-import type { LiveQueryHook, LiveQuerySource } from './query-hook';
+import type { AsyncState, Row } from '@ultimat3/core';
+import type { LiveHandle, Unsubscribe } from './client-contract';
+import type { QueryAccessor, QueryRef } from './use-query';
+import type { RecordAccessor } from './use-record';
 
 /** Fails to compile when `T` is anything but `true`. The whole mechanism. */
 type Assert<T extends true> = T;
 
 type Equals<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
 
-/** The input type a `Query` accepts, read off its call signature rather than its schema. */
-type InputOf<Q> = Q extends (input: infer I, options?: never) => unknown ? I : never;
-
-interface FeedInput {
-  readonly orgId: string;
-}
-
 interface FeedRow {
   readonly id: string;
   readonly title: string;
 }
 
-type FeedHook = LiveQueryHook<FeedInput, FeedRow>;
-
-/** The hook takes the query's own input, as a value or as the thunk `useLive` reads once. */
-export type _HookInputIsTheQueryInput = Assert<
-  Equals<Parameters<FeedHook>[0], FeedInput | (() => FeedInput)>
->;
-
-/** …and answers in the query's own row type, not the wire's `Row`. */
-export type _HookRowsAreTheQueryRows = Assert<
-  Equals<ReturnType<ReturnType<FeedHook>>, readonly FeedRow[]>
->;
-
 /**
- * A wrong key is refused. Written as a negative because that is the failure being pinned: a hook
- * whose input widened to `JsonValue` would still compile everywhere and silently accept `orgIdd`.
+ * `useQuery` answers core's `AsyncState` over the caller's own row type — the value `@ultimat3/ui`
+ * takes as `state`, with no adapter between them (plan 101, decision 10).
  */
-export type _WrongInputKeyIsRefused = Assert<
-  [{ readonly orgIdd: string }] extends [Parameters<FeedHook>[0]] ? false : true
+export type _QueryAnswersAsyncState = Assert<
+  Equals<ReturnType<QueryAccessor<FeedRow>>, AsyncState<readonly FeedRow[]>>
 >;
 
-/**
- * The seam itself: a declared `@ultimat3/query` `Query` assigns to the structural shape
- * `liveHookFor` binds. Named structurally rather than imported as a value, so this stays the one
- * place a change to `Query` — losing `isLive`, ceasing to be callable — fails, instead of every
- * component call site in every app.
- */
-export type _DeclaredQueryBindsToTheHook = Assert<
-  [Query] extends [LiveQuerySource<InputOf<Query>, Record<string, unknown>>] ? true : false
+/** …and `useRecord` the same vocabulary, with `undefined` for a record the server removed. */
+export type _RecordAnswersAsyncState = Assert<
+  Equals<ReturnType<RecordAccessor<FeedRow>>, AsyncState<FeedRow | undefined>>
 >;
 
 /**
- * The handle `LiveClient.useLive()` returns must stay `Disposable`, or `using sub =
- * client.useLive(...)` silently degrades to "never unsubscribes" the moment someone drops the
- * `[Symbol.dispose]` member while refactoring `unsubscribe`.
+ * A query ref carries no server field: a `Query` VALUE in an island drags its whole read path into
+ * the bundle, so the ref is a name and two declared facts. A `sql` key is refused.
  */
-export type _LiveHandleIsDisposable = Assert<[LiveHandle] extends [Disposable] ? true : false>;
-
-/** Same pin, one layer up: the hook's callable result set must stay `Disposable` too. */
-export type _LiveRowsIsDisposable = Assert<[LiveRows] extends [Disposable] ? true : false>;
-
-/** `channel.subscribe()`'s return must stay both callable and `Disposable`. */
-export type _UnsubscribeIsDisposable = Assert<[Unsubscribe] extends [Disposable] ? true : false>;
+export type _QueryRefHasNoServerHalf = Assert<
+  [{ readonly name: string; readonly sql: () => unknown }] extends [Required<QueryRef>]
+    ? false
+    : true
+>;
 
-/**
- * The hook seam takes `LiveClientLike`, not `LiveClient` — a structural shape, so the server
- * render's client can satisfy it without dragging the connection lifecycle into every island that
- * calls `useLive` (measured: 8,368 B → 26,571 B). This is what keeps the two in step: a member
- * `hooks.ts` needs and `LiveClient` stops providing fails HERE, at the build, rather than at the
- * one app that registered a real client.
- */
-export type _LiveClientSatisfiesTheHookSeam = Assert<
-  [LiveClient] extends [LiveClientLike] ? true : false
+/** Every handle a caller gets back stays `Disposable`, so `using` releases it on scope exit. */
+export type _LiveHandleIsDisposable = Assert<[LiveHandle] extends [Disposable] ? true : false>;
+export type _QueryAccessorIsDisposable = Assert<
+  [QueryAccessor] extends [Disposable] ? true : false
 >;
+export type _RecordAccessorIsDisposable = Assert<
+  [RecordAccessor<Row>] extends [Disposable] ? true : false
+>;
+export type _UnsubscribeIsDisposable = Assert<[Unsubscribe] extends [Disposable] ? true : false>;

package/src/use-channel.ts

@@ -0,0 +1,88 @@
+// A declared channel, held by a component. Every holder of one topic on the page shares ONE
+// membership on the page socket; its `records` land in the store (read them with `useRecord` /
+// `useQuery`), and only `events` and presence reach the handlers given here.
+
+import type { ChannelHandlers, ChannelRef, ChannelState } from './client-channels';
+import { pageSocket } from './page-socket';
+import { isServerRender, signalFor } from './reactivity';
+import type { PresenceMember } from './sync-protocol';
+
+/** The membership's state, callable, plus its release (Solid: `onCleanup`). */
+export type ChannelAccessor = (() => ChannelState) & {
+  release(): void;
+  [Symbol.dispose](): void;
+};
+
+const nothing = (): void => undefined;
+
+/**
+ * Takes the `channel()` DECLARATION (any `ChannelRef` — a declaration is one), never a topic
+ * string: the declaration is the only thing that may spell a topic (`bun run channel-literals`
+ * holds it), so both halves spell it one way.
+ */
+export function useChannel<K extends string>(
+  declared: ChannelRef<K>,
+  params: Readonly<Record<K, string>>,
+  handlers?: ChannelHandlers,
+): ChannelAccessor {
+  const signal = signalFor('useChannel');
+  if (isServerRender()) {
+    return Object.assign((): ChannelState => 'joining', {
+      release: nothing,
+      [Symbol.dispose]: nothing,
+    });
+  }
+  const membership = pageSocket('useChannel').holdChannel(declared, params, handlers);
+  const [version, setVersion] = signal(0);
+  const off = membership.onChange(() => setVersion(version() + 1));
+  const read = (): ChannelState => {
+    version();
+    return membership.state();
+  };
+  const release = (): void => {
+    off();
+    membership.release();
+  };
+  return Object.assign(read, { release, [Symbol.dispose]: release });
+}
+
+/** Who is in a channel's room, as the node's presence set says — one entry per member id. */
+export type PresenceAccessor = (() => readonly PresenceMember[]) & {
+  release(): void;
+  [Symbol.dispose](): void;
+};
+
+/**
+ * The roster of a channel declared with `events: true`: a `sync` replaces it, `join` / `update`
+ * upsert a member, `leave` removes one. It is a membership of the channel like any other — the
+ * same one `useChannel` holds, shared on the page — so holding both costs one subscribe.
+ */
+export function usePresence<K extends string>(
+  declared: ChannelRef<K>,
+  params: Readonly<Record<K, string>>,
+): PresenceAccessor {
+  const signal = signalFor('usePresence');
+  if (isServerRender()) {
+    return Object.assign((): readonly PresenceMember[] => [], {
+      release: nothing,
+      [Symbol.dispose]: nothing,
+    });
+  }
+  const [version, setVersion] = signal(0);
+  let members = new Map<string, PresenceMember>();
+  const membership = pageSocket('usePresence').holdChannel(declared, params, {
+    onPresence: (event) => {
+      if (event.presence === 'sync') members = new Map();
+      for (const member of event.members) {
+        if (event.presence === 'leave') members.delete(member.id);
+        else members.set(member.id, member);
+      }
+      setVersion(version() + 1);
+    },
+  });
+  const read = (): readonly PresenceMember[] => {
+    version();
+    return [...members.values()];
+  };
+  return Object.assign(read, { release: membership.release, [Symbol.dispose]: membership.release });
+}