@ultimat3/realtime 20.2.1 → 22.0.0

package/src/page-outbox.ts

@@ -0,0 +1,312 @@
+/**
+ * The page's ONE outbox: writes a page could not send are queued in `OfflineQueue`, persisted in
+ * the page's durable store under the current principal, and replayed IN ORDER over HTTP — each to
+ * `actionPath(name)` through core's `clientTransport`, each with its own idempotency key, so a
+ * replay after a lost response is answered from the action's idempotency store and never applied
+ * twice. Replayed on open, on `online`, and on the service worker's `OUTBOX_DRAIN_MESSAGE`.
+ * A principal change wipes the previous principal's queue: its writes are never sent as the next.
+ */
+
+import type { ClientScope } from '@ultimat3/core/page';
+import {
+  actionPath,
+  classifyThrown,
+  clientTransport,
+  OUTBOX_DRAIN_MESSAGE,
+  onRescope,
+  pageClient,
+} from '@ultimat3/core/page';
+import type { LocalStore } from './local-store-idb';
+import { pageLocalStore, scopeKey } from './local-store-idb';
+import type { DrainReport, QueuedMutation, QueueState, QueueStore } from './offline-queue';
+import { MemoryQueueStore, OfflineQueue, toQueueError } from './offline-queue';
+import { OUTBOX_KEY, type OutboxEntry, type OutboxHandle, type OutboxHost } from './outbox-slot';
+import { peekPageRealtime } from './page-store';
+import { carriedBy } from './record-store';
+
+export type { OutboxEntry } from './outbox-slot';
+
+export interface PageOutbox extends OutboxHandle {
+  enqueue(entry: OutboxEntry): Promise<void>;
+  /** Sends everything queued, in order, stopping at the first write the network could not take. */
+  replay(): Promise<DrainReport>;
+  /** Writes not yet taken by the server. `0` until the store has opened. */
+  readonly size: number;
+  /**
+   * Those writes, in queue order — what `useMutation` re-applies as overlays after a reload, so a
+   * queued write is ON SCREEN until its replay settles or refuses it. Empty until `ready`.
+   */
+  pending(): readonly OutboxEntry[];
+  /** Settles once the current principal's queue is open. */
+  readonly ready: Promise<void>;
+}
+
+/** The optimistic twins a replay settles or takes back — the page's record store. */
+export interface OutboxOverlays {
+  settle(key: string, carried?: ReadonlySet<string>): void;
+  drop(key: string): void;
+}
+
+export interface OutboxOptions {
+  readonly local: LocalStore | Promise<LocalStore>;
+  readonly principal?: (() => ClientScope['principal']) | undefined;
+  /**
+   * One write, over HTTP. Default: `clientTransport` POST to `actionPath(entry.name)`, adding every
+   * record the answer carried (`type:key`) to `carried` — what its overlay settles against.
+   */
+  readonly send?: ((entry: OutboxEntry, carried: Set<string>) => Promise<unknown>) | undefined;
+  readonly overlays?: (() => OutboxOverlays | undefined) | undefined;
+  /**
+   * Runs, and is awaited, before a write is queued. The boot hands it the record persister's
+   * `flush`: a queued write is replayed over the rows it touched, so those rows reach the disk no
+   * later than the write does — measured, a reload inside the persister's debounce came back with
+   * the write queued and the post it liked missing, and showed the old count.
+   */
+  readonly beforeEnqueue?: (() => Promise<void>) | undefined;
+}
+
+const EMPTY: DrainReport = { sent: 0, collapsed: 0, remaining: 0, stoppedAt: null };
+
+export function createOutbox(options: OutboxOptions): PageOutbox {
+  const principal =
+    options.principal ?? ((): ClientScope['principal'] => pageClient().scope.principal);
+  const send = options.send ?? sendOverHttp;
+  const overlays =
+    options.overlays ?? ((): OutboxOverlays | undefined => peekPageRealtime()?.store);
+  let queue: OfflineQueue | undefined;
+  /** The scope the open queue belongs to — what the drain lock is named after. */
+  let scope: string | undefined;
+
+  const open = async (): Promise<void> => {
+    scope = scopeKey(principal());
+    queue = await OfflineQueue.open(queueStore(await options.local, scope));
+  };
+  let ready = open();
+  let running: Promise<DrainReport> | undefined;
+  /** A trigger landed while a pass ran: one more pass follows it, never one per trigger. */
+  let again = false;
+
+  const deliver = async (mutation: QueuedMutation): Promise<void> => {
+    const current = queue;
+    const carried = new Set<string>();
+    try {
+      await send({ key: mutation.key, name: mutation.name, input: mutation.input }, carried);
+    } catch (error) {
+      const kind = classifyThrown(error);
+      // The network, or a server asking to be asked again: stays queued, and the pass stops so
+      // nothing behind it overtakes it.
+      if (kind === 'retryable' || kind === 'retry-after') throw error;
+      // Anything else is the server's decision about this write — kept for the UI, never resent.
+      await current?.fail(mutation.key, toQueueError(error));
+      overlays()?.drop(mutation.key);
+      return;
+    }
+    await current?.ack(mutation.key);
+    const store = overlays();
+    try {
+      // Exactly as a live write settles: a row the answer did not carry keeps its overlay until
+      // the server's row for it arrives.
+      store?.settle(mutation.key, carried);
+    } catch {
+      // A custom merge that answered no row: the server's truth stands.
+      store?.drop(mutation.key);
+    }
+  };
+
+  onRescope((_next, prev) => {
+    const gone = scopeKey(prev.principal);
+    ready = ready.then(async () => {
+      if (gone !== undefined) await (await options.local).wipe(gone);
+      await open();
+    });
+  });
+
+  const self: PageOutbox = {
+    enqueue: async (entry) => {
+      // A disk that refused the rows must not also cost the write: the intent still goes on disk.
+      await options.beforeEnqueue?.().catch(() => undefined);
+      await ready;
+      await queue?.enqueue(entry);
+    },
+    replay: () => {
+      // Single flight: a trigger that lands while a replay is running JOINS it. Open, `online`,
+      // the socket's reconnect and the service worker's drain arrive together, and each chaining
+      // a pass of its own sent the head of the queue once per trigger whenever a send failed —
+      // one write, several POSTs. What the running pass could not have seen — a write queued
+      // after it re-read the store — gets exactly ONE follow-up pass, however many triggers
+      // joined: `again` is a flag, never a count.
+      if (running !== undefined) {
+        again = true;
+        return running;
+      }
+      const pass = (async (): Promise<DrainReport> => {
+        await ready;
+        if (queue === undefined) return EMPTY;
+        // Checked when the pass STARTS, whoever asked (the socket's reconnect asks too): an
+        // attempt the browser already knows cannot leave is a failed request on the wire and
+        // nothing more. `online` asks again.
+        if (knownOffline()) return { ...EMPTY, remaining: queue.pending().length };
+        const draining = queue;
+        // One tab drains a principal's outbox at a time, and it drains what EVERY tab queued: the
+        // queue is re-read under the lock, so a write another tab made since this one opened is
+        // sent too, and an `inflight` entry — which only a pass holding this lock could have put
+        // on the wire, and it is over — goes back to `pending`.
+        return await exclusive(`ultimate-outbox:${scope ?? 'memory'}`, async () => {
+          await draining.reload();
+          return await draining.drain(deliver);
+        });
+      })();
+      const settled = (report?: DrainReport): void => {
+        if (running !== pass) return;
+        running = undefined;
+        // Only after a pass that reached the end: one stopped by a failure leaves the rest for
+        // the next trigger, as it always did.
+        if (again && report !== undefined && report.stoppedAt === null) {
+          again = false;
+          void self.replay().catch(() => undefined);
+        }
+        again = false;
+      };
+      running = pass;
+      pass.then(settled, () => settled());
+      return pass;
+    },
+    get size(): number {
+      return queue?.pending().length ?? 0;
+    },
+    pending: () => (queue?.pending() ?? []).map(({ key, name, input }) => ({ key, name, input })),
+    get ready(): Promise<void> {
+      return ready;
+    },
+  };
+  return self;
+}
+
+/** Persisted under the principal; an UNSCOPED page queues in memory only, and loses it on reload. */
+function queueStore(local: LocalStore, scope: string | undefined): QueueStore {
+  if (scope === undefined) return new MemoryQueueStore();
+  return {
+    load: async (): Promise<QueueState> =>
+      (await local.queue(scope)) ?? { mutations: [], nextSeq: 1 },
+    write: (change) => local.writeQueue(scope, change),
+  };
+}
+
+/** The slice of the Web Locks API a drain needs. */
+interface LockManagerLike {
+  request<T>(name: string, callback: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * `work` under the browser's Web Lock named `name`, so two tabs of one user never drain one outbox
+ * at once — they would each send the head of the queue. With no `navigator.locks` the same
+ * exclusion is kept inside this realm, on a chain held on `globalThis` (every island bundle carries
+ * its own copy of this module): tabs cannot be excluded there, but two outboxes in one page can.
+ */
+function exclusive<T>(name: string, work: () => Promise<T>): Promise<T> {
+  const navigator: unknown = Reflect.get(globalThis, 'navigator');
+  const locks: unknown =
+    typeof navigator === 'object' && navigator !== null
+      ? Reflect.get(navigator, 'locks')
+      : undefined;
+  if (
+    typeof locks === 'object' &&
+    locks !== null &&
+    typeof Reflect.get(locks, 'request') === 'function'
+  ) {
+    return (locks as LockManagerLike).request(name, work);
+  }
+  const host = globalThis as LockHost;
+  const chains = host[LOCAL_LOCKS] ?? new Map<string, Promise<unknown>>();
+  if (host[LOCAL_LOCKS] === undefined) {
+    Object.defineProperty(host, LOCAL_LOCKS, { value: chains, configurable: true });
+  }
+  const ahead = chains.get(name) ?? Promise.resolve();
+  const turn = ahead.then(work, work);
+  const tail = turn.then(
+    () => undefined,
+    () => undefined,
+  );
+  chains.set(name, tail);
+  void tail.then(() => {
+    if (chains.get(name) === tail) chains.delete(name);
+  });
+  return turn;
+}
+
+const LOCAL_LOCKS: unique symbol = Symbol.for('ultimate.outbox-locks');
+type LockHost = { [LOCAL_LOCKS]?: Map<string, Promise<unknown>> };
+function sendOverHttp(entry: OutboxEntry, carried: Set<string>): Promise<unknown> {
+  return clientTransport({
+    method: 'POST',
+    url: actionPath(entry.name),
+    body: entry.input,
+    idempotencyKey: entry.key,
+    onEnvelope: (envelope) => carriedBy(envelope, carried),
+  });
+}
+
+/**
+ * The page's outbox, created once per tab. In a browser it replays on open, on `online`, and on the
+ * service worker's drain message; with no `document` it is a memory queue that listens for nothing.
+ */
+export function pageOutbox(options: Pick<OutboxOptions, 'beforeEnqueue'> = {}): PageOutbox {
+  const host = globalThis as OutboxHost;
+  const existing = host[OUTBOX_KEY];
+  // Only this function writes the slot, so what it holds is always a `PageOutbox`.
+  if (existing !== undefined) return existing as PageOutbox;
+  const outbox = createOutbox({ local: pageLocalStore(), beforeEnqueue: options.beforeEnqueue });
+  Object.defineProperty(host, OUTBOX_KEY, { value: outbox, configurable: true });
+  if (Reflect.has(globalThis, 'document')) {
+    listenForDrain(outbox);
+    if (!knownOffline()) void outbox.replay().catch(() => undefined);
+  }
+  return outbox;
+}
+
+/**
+ * The two drain signals a page can receive: the service worker's `sync` (posted to every open tab
+ * as `OUTBOX_DRAIN_MESSAGE`), and the browser coming back `online`. A replay that fails leaves the
+ * queue as it was — the next signal tries again — so its rejection is not the listener's to raise.
+ */
+export function listenForDrain(outbox: Pick<PageOutbox, 'replay'>): () => void {
+  const replay = (): void => {
+    if (!knownOffline()) void outbox.replay().catch(() => undefined);
+  };
+  const worker: EventTarget | undefined = Reflect.get(
+    Reflect.get(globalThis, 'navigator') ?? {},
+    'serviceWorker',
+  );
+  const onMessage = (event: Event): void => {
+    const data: unknown = Reflect.get(event, 'data');
+    if (
+      typeof data === 'object' &&
+      data !== null &&
+      Reflect.get(data, 'type') === OUTBOX_DRAIN_MESSAGE
+    ) {
+      replay();
+    }
+  };
+  worker?.addEventListener('message', onMessage);
+  globalThis.addEventListener('online', replay);
+  return () => {
+    worker?.removeEventListener('message', onMessage);
+    globalThis.removeEventListener('online', replay);
+  };
+}
+
+/**
+ * The browser says it has no network. A replay then is an attempt that can only fail — and a
+ * failed attempt is still a request on the wire: measured, a reload taken offline replayed on open,
+ * that POST failed, and the real one followed on `online`, so one write went out twice. The
+ * `online` event is the replay's own trigger, so nothing is lost by waiting for it. Unknown (no
+ * `navigator`) is not offline.
+ */
+function knownOffline(): boolean {
+  const navigator: unknown = Reflect.get(globalThis, 'navigator');
+  return (
+    typeof navigator === 'object' &&
+    navigator !== null &&
+    Reflect.get(navigator, 'onLine') === false
+  );
+}

package/src/page-socket.ts

@@ -0,0 +1,139 @@
+// The page's ONE socket: built on the first live or channel hook, by whichever island bundle asks
+// first, and shared by every other one through the page state. A form-only island never imports
+// this module, so it ships none of the connection lifecycle.
+
+import { onRescope, pageClient } from '@ultimat3/core/page';
+import { queryClientMethodFor } from '@ultimat3/query/client';
+import { LiveClient } from './client';
+import { DEFAULT_HEARTBEAT_MS } from './client-heartbeat';
+import { peekOutbox } from './outbox-slot';
+import { SyncUnconfiguredError } from './page-errors';
+import { pageRealtime } from './page-store';
+import {
+  openHost,
+  type RehostingHost,
+  rehosting,
+  type SocketHost,
+  type SocketHostOptions,
+} from './socket-host';
+import { pageSyncTarget, syncWorkerFromMeta } from './sync-meta';
+
+/** Get-or-create, and connect on creation. `hook` names the caller in the refusal. */
+export function pageSocket(hook: string): LiveClient {
+  const page = pageRealtime();
+  // Its one writer is below, so the stored value is always this class — from SOME bundle's copy,
+  // which is why it is read structurally and never checked with `instanceof`.
+  if (page.socket !== undefined) return page.socket as LiveClient;
+  // What the bootstrap passed, else what the document shell rendered into `<head>`.
+  const target = page.sync ?? pageSyncTarget();
+  if (target === undefined) throw new SyncUnconfiguredError({ hook });
+  let host = rehostingFor(pageClient().scope.principal ?? null, target.buildId);
+  const client = new LiveClient({
+    connect: () => host.socket(target),
+    buildId: target.buildId,
+    actorId: pageClient().scope.principal ?? null,
+    store: page.store,
+    // The channel's catch-up read is an ordinary query read: core's transport adopts its records.
+    catchUp: (query, params) => queryClientMethodFor(query, { baseUrl: '' })(params),
+  });
+  page.socket = client;
+  pageClient().socket = client;
+  // Every time the socket comes (back) up, the writes the network refused go out, in order, over
+  // HTTP — the outbox's own idempotency keys make a replay after a lost answer harmless.
+  let up = false;
+  client.onStatus(() => {
+    if (client.connected && !up)
+      void peekOutbox()
+        ?.replay()
+        .catch(() => undefined);
+    up = client.connected;
+  });
+  // After the disk restore, so a restored record is shown before the first frame can race it.
+  void page.booted.then(() => client.connect());
+  // A new principal gets its own worker — never the previous principal's socket — and redials.
+  const offRescope = onRescope((next) => {
+    host.bye();
+    host = rehostingFor(next.principal ?? null, target.buildId);
+    client.connect();
+  });
+  // `bye` only for a page that is really going: a `pagehide` into the back/forward cache is a page
+  // that may come back, and one that said bye came back to a port the engine had released.
+  const bye = (event: Event): void => {
+    if (Reflect.get(event, 'persisted') !== true) host.bye();
+  };
+  // ...and a page restored from that cache re-hosts rather than trusting the port it left with.
+  const restored = (event: Event): void => {
+    if (Reflect.get(event, 'persisted') !== true) return;
+    host.rehost();
+    client.connect();
+  };
+  const listens = typeof addEventListener === 'function';
+  if (listens) {
+    addEventListener('pagehide', bye);
+    addEventListener('pageshow', restored);
+  }
+  teardowns.add(() => {
+    offRescope();
+    if (listens) {
+      removeEventListener('pagehide', bye);
+      removeEventListener('pageshow', restored);
+    }
+    client.close();
+    host.bye();
+    if (page.socket === client) page.socket = undefined;
+    if (pageClient().socket === client) pageClient().socket = undefined;
+  });
+  return client;
+}
+
+/**
+ * Every socket this module built, as the undo of building it. A page builds one and never tears it
+ * down — the tab's end is its teardown — so only a test process, which builds one per case, calls
+ * `resetPageSocket`. Not on the barrel: an app has no page to reset.
+ */
+const teardowns = new Set<() => void>();
+
+/** Where a page socket gets its host. `openHost` in production; a test hands in its own. */
+let hosts: (options: SocketHostOptions) => SocketHost = openHost;
+
+/**
+ * For tests: unsubscribe, close and unseat every page socket built so far, so a case starts clean
+ * — and, optionally, build the next ones over `openHost` of the case's own. A case that counts
+ * dials through the real engine counts every engine alive in the process; one that counts HOSTS
+ * counts only what this module asked for, which is the one thing it owns.
+ */
+export function resetPageSocket(
+  options: { readonly openHost?: (options: SocketHostOptions) => SocketHost } = {},
+): void {
+  for (const teardown of teardowns) teardown();
+  teardowns.clear();
+  hosts = options.openHost ?? openHost;
+}
+
+/**
+ * Whether this page holds a socket — `false` on a server render and before any live hook ran.
+ * The guard a component with a static fallback asks (an offline banner, an update prompt).
+ */
+export function hasPageSocket(): boolean {
+  const host = globalThis as { [key: symbol]: unknown };
+  const page = host[Symbol.for('ultimate.realtime')];
+  return (
+    typeof page === 'object' && page !== null && (page as { socket?: unknown }).socket !== undefined
+  );
+}
+
+function hostFor(scope: string | null, buildId: string): SocketHost {
+  const workerUrl =
+    typeof document === 'undefined' || typeof location === 'undefined'
+      ? undefined
+      : syncWorkerFromMeta(document, location.href);
+  return hosts({ workerUrl, scope, buildId });
+}
+
+/**
+ * The host for one principal, re-made when an `open` goes unanswered for two heartbeats — a port
+ * the engine reaped, or a worker that died — rather than leaving the tab dialling a dead port.
+ */
+function rehostingFor(scope: string | null, buildId: string): RehostingHost {
+  return rehosting(() => hostFor(scope, buildId), { openTimeoutMs: 2 * DEFAULT_HEARTBEAT_MS });
+}

package/src/page-store.ts

@@ -0,0 +1,138 @@
+// The page's realtime state: ONE record store and ONE sync target per tab, whichever island bundle
+// asks first. On `globalThis` under a `Symbol.for` key, because every island is its own bundle and
+// a module-scope singleton here is one store PER ISLAND — the bug this file exists to end.
+
+import { CLIENT_SCOPE_META, onRescope, pageClient } from '@ultimat3/core/page';
+import { RecordStore } from './record-store';
+
+/** Where the page's one socket dials. Resolved on the server and handed to the island bootstrap. */
+export interface SyncTarget {
+  /** `wss://…/_x/sync` (or `ws://` in dev) — the sync node's own URL. */
+  readonly url: string;
+  /** This build, so the node can tell a stale tab to reload rather than serve it a patch. */
+  readonly buildId: string;
+}
+
+/** Page-wide and shared by every bundle. Structural on purpose: no `instanceof` across copies. */
+export interface PageRealtime {
+  readonly store: RecordStore;
+  sync: SyncTarget | undefined;
+  /** The socket client, once a live hook opened it. Typed by `page-socket.ts`, its one writer. */
+  socket: unknown;
+  /** Optimistic writes in flight across the page, and the ones the server refused. */
+  readonly writes: PageWrites;
+  /**
+   * Settles once the page's boot script (`@ultimat3/realtime/boot`) has put this principal's
+   * persisted records back. The socket connects after it, so a restored row is on screen before
+   * the first frame can race it. Resolved at once on a page that carries no boot script.
+   */
+  readonly booted: Promise<void>;
+}
+
+/** Every optimistic write on the page, counted per mutator name, and who renders the counts. */
+export interface PageWrites {
+  readonly pending: Map<string, number>;
+  failed: number;
+  readonly listeners: Set<() => void>;
+}
+
+const KEY: unique symbol = Symbol.for('ultimate.realtime');
+
+/**
+ * Where the boot script leaves its promise. The boot is ONE page-level script, not code in every
+ * island: a read-only island carried the disk restore and the outbox (15.5 kB) for a job the page
+ * does once. Read per access, so an island that ran first still waits on a boot that started later.
+ */
+export const BOOT_KEY: unique symbol = Symbol.for('ultimate.page-boot');
+
+/**
+ * Set only while an island is waiting on a boot that has not started yet: the resolver of the
+ * promise already sitting under `BOOT_KEY`. The boot CLAIMS it (deletes it) and resolves it once
+ * the restore is done; a page whose boot never ran has it resolved by `load` instead.
+ */
+export const BOOT_RELEASE_KEY: unique symbol = Symbol.for('ultimate.page-boot.release');
+
+export type BootHost = { [BOOT_KEY]?: Promise<void>; [BOOT_RELEASE_KEY]?: () => void };
+
+/**
+ * The boot's promise, or — when an island asks FIRST on a page whose boot is still coming — a
+ * promise the boot will settle. An island can hydrate before the deferred boot script has run
+ * (the idle callback fires while the parser waits on that script), and answering "already booted"
+ * then meant a reload offline rebuilt no overlay and replayed nothing: the write looked lost.
+ * A boot is coming exactly when the document carries the scope tag (the CLI renders the boot
+ * beside it) and has not finished loading; `load` settles it if the script never ran.
+ */
+export function bootedPromise(): Promise<void> {
+  const host = globalThis as BootHost;
+  const started = host[BOOT_KEY];
+  if (started !== undefined) return started;
+  if (!bootComing()) return Promise.resolve();
+  let release: () => void = () => undefined;
+  const waiting = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  Object.defineProperty(host, BOOT_KEY, { value: waiting, configurable: true });
+  Object.defineProperty(host, BOOT_RELEASE_KEY, { value: release, configurable: true });
+  addEventListener(
+    'load',
+    () => {
+      // Still unclaimed after every deferred script ran: this page's boot is not coming.
+      if (host[BOOT_RELEASE_KEY] !== release) return;
+      Reflect.deleteProperty(host, BOOT_RELEASE_KEY);
+      release();
+    },
+    { once: true },
+  );
+  return waiting;
+}
+
+function bootComing(): boolean {
+  if (typeof document === 'undefined' || typeof addEventListener !== 'function') return false;
+  if (document.readyState === 'complete') return false;
+  // A partial `document` (a component test's stand-in) has no query surface: no tag, no boot.
+  if (typeof document.querySelector !== 'function') return false;
+  return document.querySelector(`meta[name="${CLIENT_SCOPE_META}"]`) !== null;
+}
+
+type Host = { [KEY]?: PageRealtime };
+
+/** Get-or-create. Installs the store as core's `RecordSink`, so HTTP answers adopt into it. */
+export function pageRealtime(): PageRealtime {
+  const host = globalThis as Host;
+  const existing = host[KEY];
+  if (existing !== undefined) return existing;
+  const store = new RecordStore();
+  const created: PageRealtime = {
+    store,
+    sync: undefined,
+    socket: undefined,
+    writes: { pending: new Map(), failed: 0, listeners: new Set() },
+    get booted(): Promise<void> {
+      return bootedPromise();
+    },
+  };
+  Object.defineProperty(host, KEY, { value: created, configurable: true });
+  pageClient().store = store;
+  // A new principal sees nothing of the previous one: every record goes, in memory, at once.
+  onRescope(() => store.clear());
+  return created;
+}
+
+/** The page state when some island already made it — never creates one (a server render must not). */
+export function peekPageRealtime(): PageRealtime | undefined {
+  return (globalThis as Host)[KEY];
+}
+
+/**
+ * Whether this page holds a socket — `false` on a server render and before any live hook ran.
+ * The guard a component with a static fallback asks (an offline banner, an update prompt). Here,
+ * not beside the socket, so asking it costs an island none of the connection lifecycle.
+ */
+export function hasPageSocket(): boolean {
+  return peekPageRealtime()?.socket !== undefined;
+}
+
+/** The page's record store. */
+export function pageStore(): RecordStore {
+  return pageRealtime().store;
+}