@ultimat3/realtime 30.3.0 → 30.5.0

package/README.md

@@ -86,7 +86,7 @@ class — stay on `.`.
 | wire | `.` | `PROTOCOL_VERSION` (3), `encode`, `decode`, `Frame` |
 | the node | `./server` | `syncNode` / `listenSyncNode` (`sync` role) |
 | a socket's identity | `./server` | `SyncAuthenticator`, `SyncGrant`, `GrantBook`, `sweepGrants`, `DEFAULT_REAUTH_INTERVAL_MS` |
-| hooks | `.` | `useQuery` (and `pollEvery` for its `poll`), `useRecord`, `useRecords` (by key, or a whole type: `RecordSelection`), `useRecordChanges`, `useMutation`, `useMutationQueue`, `useOutbox`, `useConnection`, `useChannel`, `usePresence`, `hasPageSocket`, `installRealtime` |
+| hooks | `.` | `useQuery` (and `pollEvery` for its `poll`), `useRecord`, `useRecords` (by key, or a whole type: `RecordSelection`), `useRecordChanges`, `useMutation`, `useMutationQueue`, `useOutbox`, `useConnection`, `useChannel`, `usePresence`, `hasPageSocket`, `installRealtime`, `resetPageRealtime` (tests) |
 | channel records, no replicator | `./server` | `recordPublisher` — an app's committed rows as channel `records`, sequenced per producer ([below](#channel-records-with-no-replicator)) |
 | channels | `.` | `channel`, `channelRef`, `ChannelHandle`, `topic`, `readPresence`, the channel frame types |
 | first paint | `.` | `holdFirstPaint`, `FIRST_PAINT_HOLD_MS` (1 s) — what the island bootstrap awaits before `mount`, for an island that reads the store or the outbox: the boot's restore and the open outbox, capped (#506). An island taking only `useChannel` / `usePresence` / `useConnection` never awaits it and is never hidden, nor is one taking `useQuery` / `useRecord` in an app that declares no `persist: true` entity |
@@ -304,6 +304,11 @@ state; a `useMutation` call refuses with `X_LIVE_SERVER_RENDER`. With a DOM and
 hook is `X_REALTIME_UNINSTALLED`. `hasPageSocket()` is the guard a component with a static fallback
 asks.
 
+**Between island tests**, `resetPageRealtime()` (`.`) is the one reset: it closes the page socket —
+whichever bundle's copy built it, through the page object — and drops the page object, the outbox
+and the boot's promise. A mounted chunk carries its own copy of this package, so a test never reaches
+into `Symbol.for('ultimate.realtime')` itself. Tests only; a page's state ends with its tab.
+
 ## Who a socket is
 
 `syncNode({ authenticate })` is the one place a websocket gets an identity. It runs on the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "30.3.0",
+  "version": "30.5.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "keywords": [
     "ultimate",
@@ -50,10 +50,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "30.3.0",
-    "@ultimat3/entity": "30.3.0",
-    "@ultimat3/policy": "30.3.0",
-    "@ultimat3/query": "30.3.0",
+    "@ultimat3/core": "30.5.0",
+    "@ultimat3/entity": "30.5.0",
+    "@ultimat3/policy": "30.5.0",
+    "@ultimat3/query": "30.5.0",
     "nats": "2.29.3"
   }
 }

package/src/index.ts

@@ -135,6 +135,7 @@ export {
   type PageOutbox,
   pageOutbox,
 } from './page-outbox';
+export { resetPageRealtime } from './page-reset';
 export { hasPageSocket, type SyncTarget } from './page-store';
 export { pollEvery, type QueryPoll } from './query-poll';
 export { installRealtime, type RealtimeInstall } from './reactivity';

package/src/page-reset.ts

@@ -0,0 +1,28 @@
+// The one test reset of a page's realtime state, for an app's island tests. An island test mounts
+// the BUILT chunk, which carries its own copy of this package: module state the test's copy cannot
+// see. So this acts on what every copy shares — the page object and the page globals on `globalThis`.
+
+import { pageClient } from '@ultimat3/core/page';
+import { OUTBOX_KEY } from './outbox-slot';
+import { closePageSockets } from './page-socket';
+import { BOOT_KEY, BOOT_RELEASE_KEY, PAGE_KEY, peekPageRealtime } from './page-store';
+import { uninstallRealtime } from './reactivity';
+
+/** Every page global the realtime client keeps: the page object, the outbox, the boot's promise. */
+const PAGE_KEYS: readonly symbol[] = [PAGE_KEY, OUTBOX_KEY, BOOT_KEY, BOOT_RELEASE_KEY];
+
+/**
+ * For tests: the page as no island has touched it. Closes the page socket — whichever bundle's
+ * copy built it — drops the page object, the outbox and the boot's promise, and unseats the store
+ * and socket from core's page client, so the next case or file starts with no page. Never call it
+ * in a browser: a page's state ends with the tab. A host a test handed `resetPageSocket` stays.
+ */
+export function resetPageRealtime(): void {
+  peekPageRealtime()?.closeSocket?.();
+  closePageSockets();
+  uninstallRealtime();
+  for (const key of PAGE_KEYS) Reflect.deleteProperty(globalThis, key);
+  const handle = pageClient();
+  handle.store = undefined;
+  handle.socket = undefined;
+}

package/src/page-runtime-wait.ts

@@ -3,7 +3,8 @@
 // classic script); every other document — a static export, an anonymous page, an app with no sync
 // node — gets it from the runtime chunk the island loads itself. Never both, never twice.
 
-import { deferredScriptsPending, peekPageRealtime } from './page-store';
+import type { TransportRequest } from '@ultimat3/core/page';
+import { deferredScriptsPending, installedPage, peekPageRealtime } from './page-store';
 
 export interface AwaitPageRuntimeOptions {
   /**
@@ -70,3 +71,13 @@ function firstOf(boot: Listenable): Promise<void> {
     if (typeof addEventListener === 'function') addEventListener('load', done, { once: true });
   });
 }
+
+/**
+ * Core's `clientTransport`, as the page runtime installed it. What a realtime island's bundle sends
+ * through instead of carrying its own copy (`packages/cli/src/island-realtime.ts`): the island
+ * awaited the runtime before its module body ran, so the transport is already on the page.
+ * `X_REALTIME_UNINSTALLED` on a page with no runtime, never a silent second transport.
+ */
+export function runtimeSend(req: TransportRequest): Promise<unknown> {
+  return installedPage('clientTransport').services.send(req);
+}

package/src/page-socket.ts

@@ -77,7 +77,9 @@ export function pageSocket(hook: string): LiveClient {
     addEventListener('online', wake);
     if (typeof document !== 'undefined') document.addEventListener('visibilitychange', wake);
   }
-  teardowns.add(() => {
+  const teardown = (): void => {
+    teardowns.delete(teardown);
+    if (page.closeSocket === teardown) page.closeSocket = undefined;
     offRescope();
     if (listens) {
       removeEventListener('pagehide', bye);
@@ -89,14 +91,17 @@ export function pageSocket(hook: string): LiveClient {
     host.bye();
     if (page.socket === client) page.socket = undefined;
     if (pageClient().socket === client) pageClient().socket = undefined;
-  });
+  };
+  teardowns.add(teardown);
+  page.closeSocket = teardown;
   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.
+ * `resetPageSocket`. Not on the barrel: an app's test calls `resetPageRealtime` (`page-reset.ts`),
+ * which reaches the socket through the page object, whichever bundle's copy built it.
  */
 const teardowns = new Set<() => void>();
 
@@ -112,11 +117,16 @@ let hosts: (options: SocketHostOptions) => SocketHost = openHost;
 export function resetPageSocket(
   options: { readonly openHost?: (options: SocketHostOptions) => SocketHost } = {},
 ): void {
-  for (const teardown of teardowns) teardown();
-  teardowns.clear();
+  closePageSockets();
   hosts = options.openHost ?? openHost;
 }
 
+/** Unsubscribe, close and unseat every page socket THIS copy built; the host override stays. */
+export function closePageSockets(): void {
+  for (const teardown of [...teardowns]) teardown();
+  teardowns.clear();
+}
+
 /** Where `hasPageSocket` lives, re-exported for the callers that reach it from here. */
 export { hasPageSocket } from './page-store';
 

package/src/page-store.ts

@@ -39,6 +39,11 @@ export interface PageRealtime {
   readonly booted: Promise<void>;
   /** What a hook calls instead of bundling it — installed with the store, by the page runtime. */
   services: PageServices | undefined;
+  /**
+   * Closes the page socket and unhooks its listeners — set by whichever bundle's copy built it, so
+   * a test reset in ANOTHER copy (`resetPageRealtime`, from an app's island test) can reach it.
+   */
+  closeSocket: (() => void) | undefined;
 }
 
 /**
@@ -68,7 +73,7 @@ export interface PageWrites {
   readonly listeners: Set<() => void>;
 }
 
-const KEY: unique symbol = Symbol.for('ultimate.realtime');
+export const PAGE_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
@@ -149,7 +154,7 @@ function bootComing(): boolean {
   return document.querySelector(`meta[name="${CLIENT_SCOPE_META}"]`) !== null;
 }
 
-type Host = { [KEY]?: PageRealtime };
+type Host = { [PAGE_KEY]?: PageRealtime };
 
 /**
  * Get-or-create the page object — never its runtime: an island that asks before the runtime is
@@ -157,7 +162,7 @@ type Host = { [KEY]?: PageRealtime };
  */
 export function pageRealtime(): PageRealtime {
   const host = globalThis as Host;
-  const existing = host[KEY];
+  const existing = host[PAGE_KEY];
   if (existing !== undefined) return existing;
   const created: PageRealtime = {
     store: undefined,
@@ -168,14 +173,15 @@ export function pageRealtime(): PageRealtime {
       return bootedPromise();
     },
     services: undefined,
+    closeSocket: undefined,
   };
-  Object.defineProperty(host, KEY, { value: created, configurable: true });
+  Object.defineProperty(host, PAGE_KEY, { value: created, configurable: true });
   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];
+  return (globalThis as Host)[PAGE_KEY];
 }
 
 /**