@ultimat3/realtime 20.2.0 → 21.0.0

package/src/outbox-slot.ts

@@ -0,0 +1,31 @@
+// The page's outbox as an ISLAND reaches it: read off the page, never built. The page boot
+// (`boot.ts`) is the one module that constructs it — IndexedDB, the queue, the drain listeners —
+// so a writing island ships this reader and none of that (~7.5 kB it would otherwise carry).
+
+import type { JsonValue } from './json';
+
+export interface OutboxEntry {
+  /** The idempotency key the write was first attempted under — the SAME key on every replay. */
+  readonly key: string;
+  /** The mutator's action name; the replay POSTs to `actionPath(name)`. */
+  readonly name: string;
+  readonly input: JsonValue;
+}
+
+/** What a hook asks of the outbox the boot opened: queue a write, list them, replay them. */
+export interface OutboxHandle {
+  enqueue(entry: OutboxEntry): Promise<void>;
+  replay(): Promise<unknown>;
+  pending(): readonly OutboxEntry[];
+  /** Settles once the current principal's queue is open. */
+  readonly ready: Promise<void>;
+}
+
+/** Where the page keeps it: shared by every bundle on the page, as the record store is. */
+export const OUTBOX_KEY: unique symbol = Symbol.for('ultimate.outbox');
+export type OutboxHost = { [OUTBOX_KEY]?: OutboxHandle };
+
+/** The outbox the page boot opened, or `undefined` on a page with no boot (nothing persisted). */
+export function peekOutbox(): OutboxHandle | undefined {
+  return (globalThis as OutboxHost)[OUTBOX_KEY];
+}

package/src/page-errors.ts

@@ -0,0 +1,124 @@
+// The refusals a BROWSER can reach — the page store, the hooks, the socket's wire check, the local
+// store. Apart from `errors.ts` for bytes: that module registers the whole code table at import,
+// and an island that renders one record has no use for sixty titles. The codes stay in `errors.ts`
+// (its `registerErrorCodes()` is what `package.json`'s `sideEffects` names, anchored by the
+// barrel); in a browser that loaded no table a code titles itself from its name, and `code`,
+// `cause` and `fix` — what a reader acts on — are unchanged. This module runs nothing at import.
+
+import { renderFixShellArg } from '@ultimat3/core/page';
+import { RealtimeError } from './realtime-error';
+
+/**
+ * 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 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)",
+    });
+  }
+}
+
+/**
+ * A hook ran IN A BROWSER in an island bundle whose bootstrap never called `installRealtime()`.
+ * Per BUNDLE, not per page: every island carries its own copy of solid-js, so the signal factory a
+ * hook renders through has to be that island's own — the page-wide store cannot hold one.
+ *
+ * A server render is deliberately not this error: no DOM means no reactive runtime to install,
+ * and the hooks answer the honest server-render state instead.
+ */
+export class RealtimeUninstalledError extends RealtimeError {
+  constructor(args: { hook: string }) {
+    super({
+      code: 'X_REALTIME_UNINSTALLED',
+      cause: `${args.hook}() ran in a browser island whose bundle never called installRealtime()`,
+      fix: "x build   # the island bootstrap installs it; a hand-built island calls installRealtime({ signal: createSignal }) from '@ultimat3/realtime' before its first render",
+    });
+  }
+}
+
+/** A live hook needed the page's one socket, and nothing told this page where the sync node is. */
+export class SyncUnconfiguredError extends RealtimeError {
+  constructor(args: { hook: string }) {
+    super({
+      code: 'X_SYNC_UNCONFIGURED',
+      cause: `${args.hook}() needs the page socket, and installRealtime() was given no sync target`,
+      fix: "x build   # the island bootstrap passes it; a hand-built island calls installRealtime({ signal: createSignal, sync: { url, buildId } }) from '@ultimat3/realtime'",
+    });
+  }
+}
+
+/**
+ * A row reached the record store it cannot hold: not an object, or under no key. Dropped and
+ * reported, never partially merged — a keyless row would overwrite another record.
+ */
+export class RecordRejectedError extends RealtimeError {
+  constructor(args: { type: string; reason: string }) {
+    super({
+      code: 'X_RECORD_REJECTED',
+      cause: `a ${args.type === '' ? 'record' : `"${args.type}" record`} was rejected by the page's record store: ${args.reason}`,
+      fix: `x entities describe ${renderFixShellArg(args.type, '<entity>')} --json   # the primary key every row of it must carry; return whole rows from the handler that built this one`,
+    });
+  }
+}
+
+/**
+ * IndexedDB would not open (a private window, storage disabled), so the page keeps records and its
+ * outbox in memory. A WARNING, never thrown: a page must not break because it cannot remember, so
+ * `openLocalStore` hands this to its `warn` once and carries on.
+ */
+export class LocalStoreUnavailableError extends RealtimeError {
+  constructor(args: { reason: string }) {
+    super({
+      code: 'X_LOCAL_STORE_UNAVAILABLE',
+      cause: `the page's durable store could not open (${args.reason}), so records and queued writes live in memory and are lost on reload`,
+      fix: 'nothing to do in the app — allow site storage in the browser (a private window blocks it) and reload',
+    });
+  }
+}
+
+/**
+ * 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: 'move the call into an island: x g island <route-dir> --at <route-dir>, import from its mount(), declare island({ src })',
+    });
+  }
+}
+
+/** 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',
+    });
+  }
+}

package/src/page-outbox.ts

@@ -0,0 +1,242 @@
+/**
+ * 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;
+
+  const open = async (): Promise<void> => {
+    queue = await OfflineQueue.open(queueStore(await options.local, scopeKey(principal())));
+  };
+  let ready = open();
+  let running: Promise<DrainReport> | undefined;
+
+  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();
+    });
+  });
+
+  return {
+    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 a joined trigger would have sent is still queued for the
+      // next one; nothing is dropped.
+      if (running !== undefined) 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 };
+        return queue.drain(deliver);
+      })();
+      const settled = (): void => {
+        if (running === pass) running = undefined;
+      };
+      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;
+    },
+  };
+}
+
+/** 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 },
+    save: (state) => local.saveQueue(scope, state),
+  };
+}
+
+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,108 @@
+// 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 { peekOutbox } from './outbox-slot';
+import { SyncUnconfiguredError } from './page-errors';
+import { pageRealtime } from './page-store';
+import { openHost, 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 = hostFor(pageClient().scope.principal ?? null);
+  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 = hostFor(next.principal ?? null);
+    client.connect();
+  });
+  const bye = (): void => host.bye();
+  const listens = typeof addEventListener === 'function';
+  if (listens) addEventListener('pagehide', bye);
+  teardowns.add(() => {
+    offRescope();
+    if (listens) removeEventListener('pagehide', bye);
+    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): SocketHost {
+  const workerUrl =
+    typeof document === 'undefined' || typeof location === 'undefined'
+      ? undefined
+      : syncWorkerFromMeta(document, location.href);
+  return hosts({ workerUrl, scope });
+}

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;
+}