@ultimat3/realtime 20.2.1 → 21.0.0

package/src/errors.ts

@@ -18,12 +18,19 @@ export const REALTIME_OWNED_ERROR_CODES = [
   'X_REPLICATION_PROTOCOL',
   'X_REPLICATION_FAILED',
   'X_REPLICATOR_SLOT_HELD',
+  // Retired in 21.0.0 and never thrown since — kept registered, because a shipped code is
+  // forever: a log line from an older build still resolves through `x errors explain`.
   'X_LIVE_CLIENT_MISSING',
+  'X_QUERY_NOT_SUBSCRIBABLE',
+  'X_REALTIME_UNINSTALLED',
+  'X_SYNC_UNCONFIGURED',
+  'X_RECORD_REJECTED',
+  'X_CHANNEL_DECLARATION_INVALID',
+  'X_LOCAL_STORE_UNAVAILABLE',
   'X_LIVE_SERVER_RENDER',
   'X_LIVE_ROW_UNIDENTIFIED',
   'X_LIVE_QUERY_UNKNOWN',
   'X_LIVE_REPLICA_IDENTITY',
-  'X_QUERY_NOT_SUBSCRIBABLE',
   'X_SOCKET_UNAUTHENTICATED',
   'X_SOCKET_AUTH_UNAVAILABLE',
 ] as const;
@@ -118,12 +125,19 @@ export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, stri
   X_REPLICATION_PROTOCOL: 'the WAL stream cannot be decoded',
   X_REPLICATION_FAILED: 'the replication connection was refused',
   X_REPLICATOR_SLOT_HELD: 'another replicator already owns this database',
-  X_LIVE_CLIENT_MISSING: 'a realtime hook ran in a browser with no LiveClient registered',
+  X_LIVE_CLIENT_MISSING:
+    'retired in 21.0.0 (no LiveClient to register; see X_REALTIME_UNINSTALLED): a realtime hook ran in a browser with no LiveClient registered',
+  X_QUERY_NOT_SUBSCRIBABLE:
+    'retired in 21.0.0 (liveHookFor was deleted; useQuery reads any query): a hook was bound to a query that is not declared live',
+  X_REALTIME_UNINSTALLED: 'a realtime hook ran in an island bundle that never installed realtime',
+  X_SYNC_UNCONFIGURED: 'a live hook needed the page socket and no sync target was configured',
+  X_RECORD_REJECTED: 'a row reached the record store in a shape it cannot hold',
+  X_CHANNEL_DECLARATION_INVALID: 'a channel() declaration cannot route its rows',
+  X_LOCAL_STORE_UNAVAILABLE: "the page's durable store could not open",
   X_LIVE_SERVER_RENDER: 'a browser-only live operation ran during a server render',
   X_LIVE_ROW_UNIDENTIFIED: 'a live query returned a row with no id',
   X_LIVE_QUERY_UNKNOWN: 'no live query is registered under the name a subscribe frame asked for',
   X_LIVE_REPLICA_IDENTITY: 'a replicated table sends a key-only row on delete',
-  X_QUERY_NOT_SUBSCRIBABLE: 'a hook was bound to a query that is not declared live',
   X_SOCKET_UNAUTHENTICATED: 'the sync upgrade carried no credential this app accepts',
   X_SOCKET_AUTH_UNAVAILABLE: 'the sync node could not decide who a connecting socket is',
 };
@@ -136,10 +150,21 @@ registerErrorCodes(
   ),
 );
 
-// Re-exported, never re-declared: `RealtimeError` lives in `realtime-error.ts` and the four
-// replication errors in `replication-errors.ts`, so this file stays the CODE TABLE plus the
-// client-reachable refusals. Every name is still importable from `./errors`, which is what the
-// seventeen `pg-*` modules and the barrel already do.
+export {
+  CursorStaleError,
+  LocalStoreUnavailableError,
+  ProtocolVersionError,
+  RealtimeUninstalledError,
+  RebaseConflictError,
+  RecordRejectedError,
+  ServerRenderLiveError,
+  SyncUnconfiguredError,
+} from './page-errors';
+// Re-exported, never re-declared: `RealtimeError` lives in `realtime-error.ts`, the four
+// replication errors in `replication-errors.ts` and the browser-reachable refusals in
+// `page-errors.ts`, so this file is the CODE TABLE plus the server's refusals. Every name is still
+// importable from `./errors`, which is what the `pg-*` modules and the barrel already do; a
+// browser module imports `./page-errors` so it does not load the table.
 export { RealtimeError } from './realtime-error';
 export {
   ReplicaIdentityError,
@@ -154,7 +179,8 @@ export class TopicForbiddenError extends RealtimeError {
     super({
       code: 'X_TOPIC_FORBIDDEN',
       cause: `actor ${args.actorId ?? '<anonymous>'} may not subscribe to "${args.topic}": ${args.reason}`,
-      fix: `declare a guard for this topic: hub.guard('${args.topic}', ({ actor }) => ...)`,
+      // The topic's first segment is its channel's name; the policy on that declaration decides.
+      fix: 'x policy list --json   # then widen the policy on the channel() declaration this topic belongs to, or subscribe as an actor it allows',
     });
   }
 }
@@ -217,44 +243,6 @@ export class SubscriptionIdTakenError extends RealtimeError {
   }
 }
 
-/**
- * Client and server disagree on the wire format — a version mismatch or a malformed frame.
- * Both are the same class of bug (a peer speaking a shape we do not have), so both get one code.
- */
-export class ProtocolVersionError extends RealtimeError {
-  constructor(args: { got: unknown; expected: number; detail?: string }) {
-    super({
-      code: 'X_PROTOCOL_VERSION',
-      cause:
-        args.detail ??
-        `frame protocol version ${String(args.got)} is not the server version ${args.expected}`,
-      fix: 'x build && redeploy the client; the sync node sends `update-available` before it drains',
-    });
-  }
-}
-
-/** A resume cursor cannot be honoured and no snapshot path was supplied. */
-export class CursorStaleError extends RealtimeError {
-  constructor(args: { qid: string; lsn: string; reason: string }) {
-    super({
-      code: 'X_CURSOR_STALE',
-      cause: `cursor for query ${args.qid} at lsn ${args.lsn} cannot be resumed: ${args.reason}`,
-      fix: 'pass `snapshot` to resumeFrom() so the fallback path can re-snapshot instead of failing',
-    });
-  }
-}
-
-/** A rebase could not be resolved: `custom(merge)` returned nothing, or the base row vanished. */
-export class RebaseConflictError extends RealtimeError {
-  constructor(args: { key: string; entity: string; reason: string }) {
-    super({
-      code: 'X_REBASE_CONFLICT',
-      cause: `mutation ${args.key} on ${args.entity} could not be rebased: ${args.reason}`,
-      fix: "set conflict: 'server-wins' on the mutator, or return a row from custom(merge)",
-    });
-  }
-}
-
 /** The fanout bus is down. `sync` nodes are stateless, so this is always recoverable. */
 export class TransportUnavailableError extends RealtimeError {
   constructor(args: { transport: string; reason: string; fix?: string }) {
@@ -285,44 +273,6 @@ export class TransportProtocolError extends RealtimeError {
   }
 }
 
-/**
- * A hook was called IN A BROWSER before the app entry registered its client. Never a transient
- * fault: the registration is a single call in the entry, so the fix is the call itself rather than
- * a retry.
- *
- * A server render is deliberately not this error, and never was a missing registration: there is
- * no socket to register a client for. It gets `serverRenderLiveClient()` instead — the same rule
- * `@ultimat3/ui`'s `solid()` follows for a missing Solid runtime, one package over.
- */
-export class LiveClientMissingError extends RealtimeError {
-  constructor(args: { hook: string }) {
-    super({
-      code: 'X_LIVE_CLIENT_MISSING',
-      cause: `${args.hook}() ran in a browser before any LiveClient was registered`,
-      fix: 'setLiveClient(new LiveClient({ signal: createSignal, connect, buildId })) in the app entry, above the first render',
-    });
-  }
-}
-
-/**
- * Something that can only mean "talk to the socket" ran on the server client — a mutation, a
- * publish, a topic subscription, a dial. There is no socket during a server render and there never
- * will be one: the document is built and sent, and the browser opens the connection.
- *
- * A refusal rather than a silent no-op, because both alternatives are worse. Queueing it would
- * hold one process-wide queue on behalf of whichever request happened to render, and dropping it
- * would make a write that never happened look like one that did.
- */
-export class ServerRenderLiveError extends RealtimeError {
-  constructor(args: { operation: string }) {
-    super({
-      code: 'X_LIVE_SERVER_RENDER',
-      cause: `${args.operation} ran during a server render, where this app has no live socket`,
-      fix: 'call it from an island mount() instead of from the page — or guard it with hasLiveClient(), which answers false on the server',
-    });
-  }
-}
-
 /**
  * A subscribable read projected a row with no `id`. Patches, cursors and the local store all
  * address a row by `id`, so such a row cannot be delivered — and delivering it anyway produces a
@@ -362,23 +312,6 @@ export class LiveQueryUnknownError extends RealtimeError {
   }
 }
 
-/**
- * `liveHookFor` was handed a read that never patches. Refused where the binding is written rather
- * than at the first render, because a hook over a non-live query has nothing to subscribe to — it
- * would return an empty set forever and look like a policy denial or an empty table.
- */
-export class QueryNotSubscribableError extends RealtimeError {
-  constructor(args: { name: string }) {
-    super({
-      code: 'X_QUERY_NOT_SUBSCRIBABLE',
-      // Empty at module load, when the binding runs and `registerQueries()` has not stamped a
-      // name yet — say so rather than printing `query ""`.
-      cause: `query ${args.name === '' ? '<unregistered>' : `"${args.name}"`} is not declared live: true, so it has no subscription for a hook to read`,
-      fix: 'add live: true to the query declaration, or read it once through query.client({ baseUrl }) — wiki/Queries-And-Live-Queries.md',
-    });
-  }
-}
-
 /**
  * The app's `authenticate` decided this upgrade belongs to nobody. A **decision**, so it is the
  * client's own condition and never pages anyone: the refusal is the whole point of the hook.

package/src/frame-lanes.ts

@@ -1,6 +1,6 @@
 // The order this node applies one socket's inbound frames in. `sync-node.message` dispatches every
 // frame as `void (async () => routeFrame(…))()`, so nothing upstream orders them and a router that
-// awaits a policy, a snapshot read or `onMutate` finishes in whatever order those settle.
+// awaits a policy or a snapshot read finishes in whatever order those settle.
 //
 // **Not one lane per socket.** A global per-socket lane puts every frame behind the slowest one,
 // and the slowest one is a snapshot read — a database round trip that every reconnecting client
@@ -9,9 +9,8 @@
 //
 // | Frames | Lane | Why that is the unit |
 // |---|---|---|
-// | `mutate` | `mutate` (one per socket) | they write the database, and the client numbered them |
 // | `subscribe` on a query | `sub:<sid>` | `add` then `drop` for one sid, or the drop finds nothing and the add strands the subscription it was meant to end |
-// | `subscribe` on a topic | `topic:<name>` | the same add/drop pair, one membership |
+// | `subscribe` on a channel | `channel:<name>:<params>` | the same add/drop pair, one membership |
 // | `hello`, server-authored kinds | none | they read state and write none of it |
 //
 // The caps are NOT this file's job — a lane makes concurrent frames sequential, and N sequential
@@ -52,7 +51,12 @@ export class FrameLanes {
 
 /** The lane a frame belongs in, or `null` for the kinds nothing has to order. */
 export function laneKeyOf(frame: Frame): string | null {
-  if (frame.type === 'mutate') return 'mutate';
   if (frame.type !== 'subscribe') return null;
-  return frame.target.kind === 'topic' ? `topic:${frame.target.topic}` : `sub:${frame.sid}`;
+  const target = frame.target;
+  if (target.kind !== 'channel') return `sub:${frame.sid}`;
+  // The channel's TOPIC, spelled from what fixes it — the declaration name and its params — so an
+  // add and a drop of one topic queue behind each other whatever sids they carry. Sorted, so two
+  // spellings of one params object are one lane. Entry order is sorted, never trusted.
+  const params = Object.entries(target.params).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `channel:${target.channel}:${JSON.stringify(params)}`;
 }

package/src/idb-fake.ts

@@ -0,0 +1,113 @@
+/**
+ * An in-memory IndexedDB with exactly the surface `local-store-idb.ts` uses — open with an
+ * upgrade, one transaction over named stores, `put` / `delete` / `getAll` / `getAllKeys` — and
+ * IndexedDB's own asynchrony: every request answers on a later microtask and a transaction
+ * completes after its last request. Bun ships no IndexedDB, and no dependency is worth a test seam.
+ * Values are structured-cloned in and out, as the real one does.
+ */
+
+import type { IdbDatabaseLike, IdbFactoryLike, IdbRequestLike, IdbStoreLike } from './idb-types';
+
+type Tables = Map<string, Map<string, unknown>>;
+
+export interface FakeIdbOptions {
+  /** `open` fails, as it does in a private window or with storage blocked. */
+  readonly blocked?: boolean;
+}
+
+/** A fresh, empty database server. Share one instance to simulate a reload over the same disk. */
+export function fakeIndexedDb(options: FakeIdbOptions = {}): IdbFactoryLike {
+  const databases = new Map<string, { version: number; tables: Tables }>();
+  return {
+    open(name: string, version: number): IdbRequestLike<IdbDatabaseLike> {
+      const request = pendingRequest<IdbDatabaseLike>();
+      queueMicrotask(() => {
+        if (options.blocked === true) {
+          request.fail(new DOMException('The operation is insecure.', 'SecurityError'));
+          return;
+        }
+        const known = databases.get(name) ?? { version: 0, tables: new Map() };
+        databases.set(name, known);
+        const db = database(known.tables);
+        request.result = db;
+        if (known.version < version) {
+          known.version = version;
+          request.onupgradeneeded?.();
+        }
+        request.onsuccess?.();
+      });
+      return request;
+    },
+  };
+}
+
+function database(tables: Tables): IdbDatabaseLike {
+  return {
+    objectStoreNames: { contains: (name: string): boolean => tables.has(name) },
+    createObjectStore: (name: string): void => {
+      tables.set(name, new Map());
+    },
+    transaction(names: string | readonly string[]) {
+      let open = 0;
+      const failed = false;
+      const tx = {
+        oncomplete: null as (() => void) | null,
+        onerror: null as (() => void) | null,
+        error: null as unknown,
+        objectStore: (name: string): IdbStoreLike => store(name),
+      };
+      const settleLater = (): void => {
+        queueMicrotask(() => {
+          if (open > 0 || failed) return;
+          tx.oncomplete?.();
+        });
+      };
+      const run = <T>(work: () => T): IdbRequestLike<T> => {
+        const request = pendingRequest<T>();
+        open += 1;
+        queueMicrotask(() => {
+          open -= 1;
+          request.result = work();
+          request.onsuccess?.();
+          settleLater();
+        });
+        return request;
+      };
+      const store = (name: string): IdbStoreLike => {
+        const allowed = typeof names === 'string' ? [names] : names;
+        const table = tables.get(name);
+        if (!allowed.includes(name) || table === undefined) {
+          throw new DOMException(`no object store ${name}`, 'NotFoundError');
+        }
+        const sorted = (): [string, unknown][] =>
+          [...table].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return {
+          put: (value, key) => run(() => void table.set(key, structuredClone(value))),
+          delete: (key) => run(() => void table.delete(key)),
+          getAll: () => run(() => sorted().map(([, value]) => structuredClone(value))),
+          getAllKeys: () => run(() => sorted().map(([key]) => key)),
+        };
+      };
+      settleLater();
+      return tx;
+    },
+  };
+}
+
+type PendingRequest<T> = IdbRequestLike<T> & { fail(error: unknown): void };
+
+function pendingRequest<T>(): PendingRequest<T> {
+  const request: PendingRequest<T> = {
+    result: undefined as T,
+    error: null,
+    onsuccess: null,
+    onerror: null,
+    onupgradeneeded: null,
+    onblocked: null,
+    fail(error: unknown): void {
+      request.error = error;
+      request.onerror?.();
+    },
+  };
+  return request;
+}

package/src/idb-types.ts

@@ -0,0 +1,41 @@
+/**
+ * The slice of IndexedDB `local-store-idb.ts` touches, as structural types: the browser's
+ * `indexedDB` satisfies them and so does `idb-fake.ts`, so the store is tested against the same
+ * surface it runs on without a DOM shim.
+ */
+
+export interface IdbRequestLike<T> {
+  result: T;
+  error: unknown;
+  onsuccess: (() => void) | null;
+  onerror: (() => void) | null;
+  onupgradeneeded?: (() => void) | null;
+  onblocked?: (() => void) | null;
+}
+
+export interface IdbStoreLike {
+  put(value: unknown, key: string): IdbRequestLike<unknown>;
+  delete(key: string): IdbRequestLike<unknown>;
+  getAll(): IdbRequestLike<unknown[]>;
+  getAllKeys(): IdbRequestLike<unknown[]>;
+}
+
+export interface IdbTransactionLike {
+  oncomplete: (() => void) | null;
+  onerror: (() => void) | null;
+  error: unknown;
+  objectStore(name: string): IdbStoreLike;
+}
+
+export interface IdbDatabaseLike {
+  readonly objectStoreNames: { contains(name: string): boolean };
+  createObjectStore(name: string): unknown;
+  transaction(
+    names: string | readonly string[],
+    mode?: 'readonly' | 'readwrite',
+  ): IdbTransactionLike;
+}
+
+export interface IdbFactoryLike {
+  open(name: string, version: number): IdbRequestLike<IdbDatabaseLike>;
+}

package/src/index.ts

@@ -1,23 +1,45 @@
 // The CLIENT half of the public API — everything a browser island may bundle. Explicit, tier by
-// tier: the wire, the hooks, the identity map, the offline queue and the reconnect vocabulary.
+// tier: the wire, the hooks, the record store, the offline outbox and the reconnect vocabulary.
 // Nothing here reaches `nats`, a Postgres socket or the sync node; those are `./server`, and
 // `packages/cli/src/realtime-browser-barrel.test.ts` is the build error that keeps them apart.
 
 // ---- the client's one stateless piece, reusable against an app's own store ----------------------
 export { applyPatches, orderAfterPatches } from './apply-patches';
-// ---- server + client halves -------------------------------------------------------------------
+// ---- channels: the declaration is the only way to spell a topic, and the frames it rides --------
 export {
-  type ClientSocket,
-  LiveClient,
-  type LiveClientLike,
-  type LiveClientOptions,
-  type LiveHandle,
-  type LiveQueryRef,
-  type LiveState,
-  type MutatorRef,
-  type SignalFactory,
-  type Unsubscribe,
-} from './client';
+  type Channel,
+  type ChannelEntity,
+  type ChannelInit,
+  type ChannelParams,
+  type ChannelRowLoader,
+  type ChannelServerInit,
+  channel,
+} from './channel-decl';
+// Presence rides a channel's `events`: the payload shape, and the one reader a client needs.
+export { type PresenceEvent, type PresenceOp, readPresence } from './channel-presence';
+// The client half of a channel an island holds — no entity, no policy (`channel-ref.ts`).
+export { type ChannelHandle, channelRef, type Topic, topic } from './channel-ref';
+// The process's channel table: what a hub serves by default. `describeChannels` is `./server`'s.
+export { clearChannels, registeredChannels } from './channel-registry';
+export type {
+  ChannelAdopt,
+  ChannelEventsFrame,
+  ChannelRecordsFrame,
+  ChannelRemove,
+  ChannelSince,
+  ChannelSubscribeTarget,
+  ChannelWireFrame,
+  ReplayGapFrame,
+} from './channel-wire';
+// ---- the hooks: every read and write a component makes -----------------------------------------
+export type { ChannelHandlers, ChannelRef, ChannelState } from './client-channels';
+// ---- the shapes a hook hands back ----------------------------------------------------------------
+export type {
+  LiveHandle,
+  LiveQueryRef,
+  SignalFactory,
+  Unsubscribe,
+} from './client-contract';
 // ---- reconnect ----------------------------------------------------------------------------------
 export {
   advance,
@@ -38,54 +60,29 @@ export {
 export {
   CursorStaleError,
   FrameRateLimitError,
-  LiveClientMissingError,
   LiveQueryUnknownError,
   LiveRowUnidentifiedError,
   NotImplementedError,
   ProtocolVersionError,
-  QueryNotSubscribableError,
   REALTIME_ERROR_CODES,
   REALTIME_ERROR_TITLES,
   RealtimeError,
   type RealtimeErrorCode,
+  RealtimeUninstalledError,
   RebaseConflictError,
+  RecordRejectedError,
   ReplicaIdentityError,
   ReplicationFailedError,
   ReplicationProtocolError,
   ReplicatorSlotHeldError,
   ServerRenderLiveError,
   SubscriptionLimitError,
+  SyncUnconfiguredError,
   TopicForbiddenError,
   TransportProtocolError,
   TransportUnavailableError,
   WindowReadTimeoutError,
 } from './errors';
-// ---- the client hooks --------------------------------------------------------------------------
-export {
-  type ConflictLike,
-  type Connection,
-  clearLiveClient,
-  hasLiveClient,
-  type LiveInput,
-  type LiveRows,
-  type Mutate,
-  type MutationQueue,
-  type MutatorLike,
-  setLiveClient,
-  useConnection,
-  useLive,
-  useMutation,
-  useMutationQueue,
-} from './hooks';
-// ---- the client's single source of truth: one row per (entity, id) ------------------------------
-export {
-  type IdentityListener,
-  IdentityMap,
-  privateScope,
-  type RowKey,
-  type RowScope,
-  rowKey,
-} from './identity-map';
 // ---- shared value domain ---------------------------------------------------------------------
 export {
   changedColumns,
@@ -97,54 +94,48 @@ export {
   type RowOp,
   type RowPatch,
 } from './json';
-export { type Registration, RowWindows } from './live-rows';
-// ---- tier 3: local-first ------------------------------------------------------------------------
+export { type LiveState, type Registration, RowWindows, unnamedType } from './live-rows';
+// ---- offline: the durable store, the persisted records, the one outbox (plan 101 slice 12) ------
 export {
-  createOpfsLocalStore,
   type LocalStore,
-  type LocalTable,
-  type LocalTx,
   MemoryLocalStore,
-  type OpfsLocalStoreOptions,
-  type TableMap,
-} from './local-store';
+  openLocalStore,
+  pageLocalStore,
+  scopeKey,
+} from './local-store-idb';
+// ---- the offline outbox (wired over HTTP in plan 101 slice 12) ----------------------------------
 export {
   type DrainReport,
   MemoryQueueStore,
   type MutationSender,
   type MutationStatus,
-  mutateFrame,
   OfflineQueue,
   type QueuedMutation,
   type QueueState,
   type QueueStore,
 } from './offline-queue';
-/** The typed projection: one query bound to one named hook, `useLiveFeed({ orgId })`. */
 export {
-  type LiveQueryHook,
-  type LiveQuerySource,
-  liveHookFor,
-} from './query-hook';
+  createOutbox,
+  listenForDrain,
+  type OutboxEntry,
+  type PageOutbox,
+  pageOutbox,
+} from './page-outbox';
+// ---- the page: one record store, one socket, installed by the island bootstrap ------------------
+export { hasPageSocket, type SyncTarget } from './page-store';
+export { installRealtime, type RealtimeInstall } from './reactivity';
+export { persistedTypes, type RecordPersister, recordPersister } from './record-persister';
 export {
-  type ConflictStrategy,
-  type CustomMerge,
-  custom,
-  type MergeArgs,
-  type RebaseEntry,
-  RebaseLog,
-  type ReconcileOptions,
-  type ReconcileResult,
-  rebaseFrame,
-  reconcile,
-  type ServerAck,
-  strategyName,
-} from './rebase';
-// ---- what a LiveClient IS on the server: it serves the first render and opens no socket --------
-export { serverRenderLiveClient } from './server-render-client';
+  type RecordKey,
+  type RecordListener,
+  RecordStore,
+  type RecordStoreOptions,
+  recordKey,
+} from './record-store';
+export type { LocalTable, LocalTx, TableMap } from './record-tx';
 // ---- the wire -------------------------------------------------------------------------------------
 export {
   type AckFrame,
-  type ConflictStrategyName,
   decode,
   encode,
   FRAME_KINDS,
@@ -152,12 +143,9 @@ export {
   type Frame,
   type FrameKind,
   type HelloFrame,
-  type MutateFrame,
   type PatchFrame,
   PROTOCOL_VERSION,
-  type PresenceFrame,
   type PresenceMember,
-  type RebaseFrame,
   type ReconnectFrame,
   type SnapshotFrame,
   type SubscribeFrame,
@@ -169,7 +157,9 @@ export {
 // ---- the client's own reconnect: the backoff it computes and the timer it arms -----------------
 export {
   type BackoffPolicy,
+  BROWSER_RECONNECT_MAX_MS,
   backoffDelay,
+  browserBackoff,
   defaultBackoff,
   type JitterMode,
   type ReconnectReason,
@@ -177,3 +167,19 @@ export {
   type Scheduler,
   timeoutScheduler,
 } from './thundering-herd';
+export {
+  type ChannelAccessor,
+  type PresenceAccessor,
+  useChannel,
+  usePresence,
+} from './use-channel';
+export { type Connection, useConnection } from './use-connection';
+export {
+  type Mutate,
+  type MutationQueue,
+  type MutatorLike,
+  useMutation,
+  useMutationQueue,
+} from './use-mutation';
+export { type QueryAccessor, type QueryOptions, type QueryRef, useQuery } from './use-query';
+export { type RecordAccessor, type RecordsAccessor, useRecord, useRecords } from './use-record';

package/src/json.ts

@@ -34,6 +34,11 @@ export interface RowPatch {
   readonly row: JsonObject | null;
   readonly lsn: string;
   readonly index?: number;
+  /**
+   * The row's RECORD key when it is not its `id` — the entity's primary key, rendered by its
+   * projection on the server. Absent means the key is the `id`.
+   */
+  readonly key?: string;
 }
 
 export function isJsonObject(value: unknown): value is JsonObject {

package/src/live-contract.ts

@@ -41,6 +41,11 @@ export interface LiveQueryDefinition<R extends Row = Row> {
    * rows private to that one subscription rather than guessing.
    */
   rowEntity?(input: JsonValue): string | null;
+  /**
+   * The record key each row travels under, resolved with `rowEntity`: the entity's own projection.
+   * `null` (or absent) is a plain table, whose rows are keyed by `id`.
+   */
+  rowKey?(input: JsonValue): ((row: Row) => string) | null;
   /**
    * Resolve whatever this input needs before an entry is built. `matcher` is synchronous by
    * design — a change event must not await anything — so a definition that has to compile a