svelte-realtime 0.5.4 → 0.5.6

package/README.md

@@ -1271,6 +1271,27 @@ Call `configure()` once at app startup. The hooks fire on state transitions only
 | `onConnect()` | Called when the WebSocket connection opens after a reconnect |
 | `onDisconnect()` | Called when the WebSocket connection closes |
 | `beforeReconnect()` | Called before each reconnection attempt (can be async) |
+| `timeout` | Default RPC timeout in ms (default `30000`). Per-call `.with({ timeout })` overrides. |
+| `resumeGraceMs` | Stream resume-grace window in ms (default `60000`). See [Pause and resume without re-rehydrating](#pause-and-resume-without-re-rehydrating) below. Set to `0` to disable. |
+
+### Pause and resume without re-rehydrating
+
+When the last subscriber of a stream unsubs, the stream releases its WebSocket subscription immediately (giving the server back its slot, dropping the in-flight counter) but keeps the in-memory data model -- `currentValue`, the last seen `seq` / `version`, the pagination `cursor`, and any history -- for `resumeGraceMs` (default 60 seconds). If a new `subscribe()` lands inside that window, the stream re-attaches its listeners and sends the retained cursor on the resume envelope, so the server can fill the gap from its bounded replay buffer (or `delta.fromSeq`, or a truncated-cache fall-through to a full rehydrate) instead of cold-starting.
+
+This is the default for two reasons:
+
+1. **Pause/resume UIs work for free.** A `{#if active} <SubscribedComponent /> {/if}` toggle, or an `$effect` whose subscribe-arm flips on user action, can pause and resume the subscription without re-loading from scratch. The events that arrived during the pause stream in via the replay buffer.
+2. **Browser back/forward feels instant.** Navigating away and back within the grace window restores the previous data immediately, and any events the user missed are gap-filled by the server.
+
+If the grace expires without a new subscriber, the data model resets and the next subscribe is a true cold start. Apps that prefer aggressive memory reclamation can shorten or disable the grace:
+
+```js
+configure({ resumeGraceMs: 0 });        // every unsub is a full reset (pre-grace behavior)
+configure({ resumeGraceMs: 5_000 });    // 5s grace covers brief toggles
+configure({ resumeGraceMs: 300_000 });  // 5min grace for navigation-heavy apps
+```
+
+The grace only affects local data retention. The server's replay buffer and `delta.fromSeq` window are independent and govern how far back the gap-fill can reach.
 
 ### Cross-origin and native app usage
 
@@ -2218,7 +2239,7 @@ On older adapters (`open(ws, platform)` is the only available hand-off point), c
 
 Each worker process runs its own cron tick. In a single-process deployment that's exactly what you want. In a clustered deployment - whether `CLUSTER_MODE=reuseport` on Linux (N kernel workers per replica), acceptor mode on Windows / macOS (N internal workers per process), or N Docker replicas, or any combination - every worker fires every job in parallel by default. For "send the daily summary at 9am" jobs, that's almost certainly wrong.
 
-Wire a cluster-wide leader gate via `configureCron({ leader, bus })`. The canonical leader implementation lives in `svelte-adapter-uws-extensions/redis/leader` (Redis SETNX lease) and the canonical bus is `svelte-adapter-uws-extensions/redis/pubsub`:
+Wire a cluster-wide leader gate via `configureCron({ leader, bus })` (or via the higher-level `realtime({ bus, leader })` factory described in [Redis multi-instance](#redis-multi-instance) - same outcome, one fewer wiring step). The canonical leader implementation lives in `svelte-adapter-uws-extensions/redis/leader` (Redis SETNX lease) and the canonical bus is `svelte-adapter-uws-extensions/redis/pubsub`:
 
 ```js
 // src/hooks.ws.js (clustered, with extensions)
@@ -2993,28 +3014,70 @@ If `replay: true` is declared but `platform.replay` is never set, dev-mode logs
 
 ## Redis multi-instance
 
-Use `createMessage` with the Redis pub/sub bus for multi-instance deployments. `ctx.publish` automatically goes through Redis when the platform is wrapped.
+One declaration of cluster intent reaches every framework publish surface. `realtime({ bus, leader })` (added in 0.5.6) wires `ctx.publish` for RPC, the cron tick, the reactive watcher path (`live.effect`, `live.derived`, `live.aggregate`, `live.webhook`), and the top-level `publish()` helper in one call. Handler code (`src/live/*.js`) is byte-identical between single-replica and cluster - you opt in by passing `bus` and `leader` at the top of `hooks.ws.js`, nothing else changes.
 
 ```js
 // src/hooks.ws.js
-import { createMessage } from 'svelte-realtime/server';
-import { createRedis, createPubSubBus } from 'svelte-adapter-uws-extensions/redis';
+import { realtime } from 'svelte-realtime/server';
+import { createRedis, createPubSubBus, createLeader } from 'svelte-adapter-uws-extensions/redis';
 
 const redis = createRedis();
 const bus = createPubSubBus(redis);
+const leader = createLeader(redis);
 
-export function open(ws, { platform }) {
-  bus.activate(platform);
+export const { open, close, message, init } = realtime({
+  bus,
+  leader: leader.isLeader,
+});
+
+export function upgrade({ cookies }) {
+  return validateSession(cookies.session_id) || false;
 }
+```
+
+Single-replica is the same file with no config:
 
+```js
+// src/hooks.ws.js (single-replica)
+import { realtime } from 'svelte-realtime/server';
+export const { open, close, message, init } = realtime();
 export function upgrade({ cookies }) {
   return validateSession(cookies.session_id) || false;
 }
+```
+
+### Layer 1: manual wiring (experts)
 
-export const message = createMessage({ platform: (p) => bus.wrap(p) });
+`realtime()` is sugar over the existing primitives. If you want fine control - per-route bus, custom hook composition, conditional cluster wiring - drop down to the building blocks. The pre-0.5.6 pattern still works unchanged, and as of 0.5.6 it routes through the same compose-at-publish-time pipeline, so reactive handlers (`live.effect`, `live.derived`, `live.aggregate`) pick up cluster relay automatically once a bus is wired:
+
+```js
+// src/hooks.ws.js (manual primitives)
+import { setBus, setCronPlatform, _activateDerived, configureCron, pushHooks, message } from 'svelte-realtime/server';
+import { createRedis, createPubSubBus, createLeader } from 'svelte-adapter-uws-extensions/redis';
+
+const redis = createRedis();
+const bus = createPubSubBus(redis);
+const leader = createLeader(redis);
+
+setBus(bus);                          // process-wide bus; reactive seam + RPC auto-wrap + publish() helper all use it
+configureCron({ leader: leader.isLeader });
+
+export { message };
+export const open = pushHooks.open;
+export const close = pushHooks.close;
+export function init({ platform }) {
+  setCronPlatform(platform);
+  _activateDerived(platform);
+}
+
+export function upgrade({ cookies }) {
+  return validateSession(cookies.session_id) || false;
+}
 ```
 
-No changes needed in your live modules. `ctx.publish` delegates to whatever platform was passed in, so Redis wrapping is transparent.
+`setBus(bus)` and `configureCron({ bus })` write the same backing state; pick whichever reads better at the call site. `getBus()`, `getPlatform()`, and `publish(topic, event, data)` are exported for diagnostics and for publishing from outside a framework handler (e.g. a `+server.js` HTTP endpoint).
+
+No changes needed in your live modules either way. `ctx.publish` delegates to whatever composed platform reached the handler, so cluster relay is transparent to user code.
 
 If you already run Postgres and don't need Redis, you can use the [LISTEN/NOTIFY bridge](#postgres-notify) instead for cross-instance pub/sub.
 
@@ -3030,19 +3093,23 @@ When you add the Redis extensions from [svelte-adapter-uws-extensions](https://g
 
 ### Combined: Redis + rate limiting
 
+`realtime()` returns the standard hook set; for the cross-cutting `beforeExecute` rate-limit gate, swap `realtime()`'s `message` for a `createMessage` you composed yourself. The bus is still wired once via `setBus`, so the reactive seam and cron tick stay cluster-correct without a per-hook bus callback:
+
 ```js
-import { createMessage, LiveError } from 'svelte-realtime/server';
-import { createRedis, createPubSubBus, createRateLimit } from 'svelte-adapter-uws-extensions/redis';
+import { realtime, createMessage, setBus, LiveError } from 'svelte-realtime/server';
+import { createRedis, createPubSubBus, createLeader, createRateLimit } from 'svelte-adapter-uws-extensions/redis';
 
 const redis = createRedis();
 const bus = createPubSubBus(redis);
+const leader = createLeader(redis);
 const limiter = createRateLimit(redis, { points: 30, interval: 10000 });
 
-export function open(ws, { platform }) { bus.activate(platform); }
+setBus(bus);
+
+export const { open, close, init } = realtime({ leader: leader.isLeader });
 export function upgrade({ cookies }) { return validateSession(cookies.session_id) || false; }
 
 export const message = createMessage({
-  platform: (p) => bus.wrap(p),
   async beforeExecute(ws, rpcPath) {
     const { allowed, resetMs } = await limiter.consume(ws);
     if (!allowed)
@@ -3051,6 +3118,8 @@ export const message = createMessage({
 });
 ```
 
+Without a `platform` callback, `createMessage` auto-wraps with whatever `setBus(...)` wired - one source of truth, no double-wrap.
+
 ---
 
 ## Postgres NOTIFY
@@ -3565,13 +3634,18 @@ Import from `svelte-realtime/server`.
 | `guard(...fns)` | Per-module auth middleware |
 | `LiveError(code, message?)` | Typed error (propagates to client) |
 | `handleRpc(ws, data, platform, options?)` | Low-level RPC handler |
-| `message` | Ready-made message hook |
-| `createMessage(options?)` | Custom message hook factory |
+| `message` | Ready-made message hook (auto bus-wraps when `setBus` is wired) |
+| `createMessage(options?)` | Custom message hook factory (auto bus-wraps unless `options.platform` is provided) |
+| `realtime(config?)` | One-call setup returning `{ open, close, message, init, upgrade? }` - wires bus + leader + platform from a single declaration of cluster intent |
+| `setBus(bus)` | Configure the process-wide bus consulted by every framework publish surface (alias for `configureCron({ bus })`) |
+| `getBus()` | Read the process-wide bus, or `null` |
+| `getPlatform()` | Read the framework-owned composed platform after `init` has captured it |
+| `publish(topic, event, data, options?)` | Top-level publish helper (routes through the composed platform; relays via bus when wired) |
 | `pipe(stream, ...transforms)` | Composable stream transforms |
 | `close` | Ready-made close hook (fires onUnsubscribe for remaining topics) |
 | `unsubscribe` | Ready-made unsubscribe hook (fires onUnsubscribe in real time) |
 | `setCronPlatform(platform)` | Capture platform for cron jobs (call from `init({ platform })`) |
-| `configureCron({ leader })` | Cluster-mode leader gate for cron (default: every worker fires) |
+| `configureCron({ leader, bus })` | Cluster-mode leader gate for cron (default: every worker fires); `bus` also wires the process-wide bus |
 | `onError(handler)` | Global error handler for cron, effects, and derived |
 | `onCronError(handler)` | Deprecated alias for `onError` |
 | `enableSignals(ws)` | Enable point-to-point signal delivery |

package/client.d.ts

@@ -534,6 +534,20 @@ export function configure(config: {
 	onConnect?(): void;
 	/** Called when the WebSocket connection closes. */
 	onDisconnect?(): void;
+	/** Default RPC timeout in ms; per-call `.with({ timeout })` overrides. @default 30000 */
+	timeout?: number;
+	/**
+	 * Stream resume-grace window in ms. When the last subscriber of a stream
+	 * unsubs, the WS subscription is released immediately but the data model
+	 * (currentValue, seq, version, cursor) is kept for this long. A new
+	 * subscribe within the window resumes from the retained cursor so the
+	 * server can fill the gap from its replay buffer (or fromSeq, or
+	 * truncated -> full rehydrate) instead of cold-rehydrating. Covers
+	 * pause/resume UIs and browser back/forward navigation. Set to 0 to
+	 * disable the grace window.
+	 * @default 60000
+	 */
+	resumeGraceMs?: number;
 	/** Offline mutation queue configuration. */
 	offline?: {
 		/** Enable queuing RPCs when disconnected. */

package/client.js

@@ -314,6 +314,25 @@ function _getTimeout() {
 	return _clientConfig.timeout || _DEFAULT_TIMEOUT;
 }
 
+const _DEFAULT_RESUME_GRACE_MS = 60000;
+
+/**
+ * Stream resume-grace window in ms. When the last subscriber unsubs, the
+ * stream releases its WS subscription immediately but keeps the in-memory
+ * data model (currentValue, _lastSeq, _lastVersion, _cursor) for this
+ * long. A new subscribe() within the window resumes from the retained
+ * cursor so the server can fill the gap from its replay buffer instead
+ * of cold-rehydrating. Set to 0 to disable the grace window (every
+ * cleanup is a full reset).
+ *
+ * @returns {number}
+ */
+function _getResumeGraceMs() {
+	const v = _clientConfig.resumeGraceMs;
+	if (typeof v === 'number' && v >= 0) return v;
+	return _DEFAULT_RESUME_GRACE_MS;
+}
+
 /** @type {boolean} Whether the connection is permanently dead (terminal close code, exhausted retries, or explicit close) */
 let _terminated = false;
 
@@ -2509,9 +2528,16 @@ function _createStream(path, options, dynamicArgs, initialSchemaVersion) {
 	}
 
 	/**
-	 * Clean up subscriptions.
+	 * Tear down WS-level subscription handles, transient flags, and any
+	 * in-flight subscribe request. Leaves the in-memory data model
+	 * (currentValue, _index, _history, _lastSeq, _lastVersion, _cursor,
+	 * _hasMore, _schemaVersion, topic) intact so that a subscribe() call
+	 * landing during the resume-grace window can reattach listeners,
+	 * call fetchAndSubscribe() with the retained seq/version/cursor, and
+	 * let the server fill the gap from its replay buffer (or fromSeq, or
+	 * a truncated -> full rehydrate fallback) instead of cold-starting.
 	 */
-	function cleanup() {
+	function _releaseSubscription() {
 		if (pendingId) {
 			const entry = pending.get(pendingId);
 			if (entry) {
@@ -2547,10 +2573,19 @@ function _createStream(path, options, dynamicArgs, initialSchemaVersion) {
 		_bufA.length = 0;
 		_bufB.length = 0;
 		_activeBuf = _bufA;
+		fetching = false;
+	}
+
+	/**
+	 * Reset the in-memory data model and error state. Runs when the
+	 * resume-grace window expires with no new subscriber, or immediately
+	 * on cleanup when resumeGraceMs is 0. After this runs, the next
+	 * subscribe() is a true cold start.
+	 */
+	function _resetSession() {
 		if (topic) _unregisterTopicErrorSetter(topic, _setError);
 		topic = null;
 		initialLoaded = false;
-		fetching = false;
 		buffer = [];
 		currentValue = undefined;
 		store.set(undefined);
@@ -2562,17 +2597,6 @@ function _createStream(path, options, dynamicArgs, initialSchemaVersion) {
 		_history = [];
 		_historyIndex = -1;
 		_reconnectAttempts = 0;
-		// Reset session-resume cursors. Cleanup means the stream is being
-		// abandoned (last subscriber gone, deferred-cleanup microtask fired);
-		// the next subscribe must start fresh, not falsely resume from
-		// whatever seq / version / cursor the prior session left behind.
-		// Without these resets, an unmount/remount cycle (e.g. browser back
-		// then forward) sends a stale `seq` to the server, the server
-		// responds with a since-seq delta (often empty), and the client's
-		// reset `currentValue = undefined` never gets repopulated -- the
-		// store stays undefined and any `{#if $store === undefined}` spinner
-		// hangs forever. In-session WS reconnects do NOT go through cleanup,
-		// so the replay-buffer gap-fill optimization is preserved for those.
 		_lastSeq = null;
 		_lastVersion = undefined;
 		_schemaVersion = initialSchemaVersion;
@@ -2582,8 +2606,95 @@ function _createStream(path, options, dynamicArgs, initialSchemaVersion) {
 		_devtoolsStream(path, null, 0, merge);
 	}
 
-	/** @type {boolean} Whether a deferred cleanup is pending (prevents thrashing on rapid unsub+resub) */
+	/**
+	 * Full cleanup: release WS handles AND reset session state. Equivalent
+	 * to the pre-grace cleanup; used when resumeGraceMs is 0 (opt-out) or
+	 * when grace expires.
+	 */
+	function cleanup() {
+		_releaseSubscription();
+		_resetSession();
+	}
+
+	/** @type {boolean} Whether a microtask-deferred cleanup is pending (handles rapid sync unsub+resub) */
 	let _pendingCleanup = false;
+	/** @type {ReturnType<typeof setTimeout> | null} Resume-grace expiry timer; non-null while state is being retained for a possible resume */
+	let _resumeGraceTimer = null;
+	/** @type {boolean} Whether the stream is in the resume-grace window (released WS, retained data) */
+	let _inGracePeriod = false;
+
+	/**
+	 * Wire up the per-subscribe lifecycle listeners: quiescence tracking
+	 * (registers the stream with the global in-flight counter) and the
+	 * reconnect-on-open watcher. Shared between first-subscribe and
+	 * resume-from-grace so both paths get the same listener setup.
+	 */
+	function _attachLifecycleListeners() {
+		_quiescenceUnsub = _statusStore.subscribe((s) => {
+			const inFlight = s === 'loading' || s === 'reconnecting';
+			if (inFlight && !_countedInFlight) {
+				_countedInFlight = true;
+				_addInFlight();
+			} else if (!inFlight && _countedInFlight) {
+				_countedInFlight = false;
+				_removeInFlight();
+			}
+		});
+
+		// `status.subscribe` fires synchronously with the current value, which
+		// for a stream subscribing during page hydration is usually 'connecting'
+		// (since `_connect()` is lazy on the first subscriber). Filter on 'open'
+		// first and track whether we've ever seen one, so the FIRST 'open' is
+		// the lifetime baseline rather than treating it as a reconnect bounce.
+		let hasOpenedOnce = false;
+		statusUnsub = status.subscribe((s) => {
+			if (s !== 'open') return;
+			if (!hasOpenedOnce) {
+				hasOpenedOnce = true;
+				return;
+			}
+			if (subCount > 0) {
+				_status = 'reconnecting';
+				_statusStore.set('reconnecting');
+				if (_reconnectTimer) clearTimeout(_reconnectTimer);
+				let delay;
+				// Reconnect jitter: spread a fleet's reconnect attempts across the
+				// window so a server restart does not get a thundering-herd retry
+				// spike. Math.random is the right primitive here - jitter does not
+				// need crypto-quality entropy. Not security-relevant.
+				if (_reconnectAttempts < 2) {
+					delay = 20 + Math.floor(Math.random() * 80);
+				} else {
+					const base = Math.min(1000 * Math.pow(2.2, _reconnectAttempts - 2), 300000);
+					delay = Math.floor(base * (0.75 + Math.random() * 0.5));
+				}
+				_reconnectAttempts++;
+				_reconnectTimer = setTimeout(() => {
+					_reconnectTimer = null;
+					if (topicUnsub) {
+						topicUnsub();
+						topicUnsub = null;
+					}
+					initialLoaded = false;
+					fetching = false;
+					buffer = [];
+					fetchAndSubscribe();
+				}, delay);
+			}
+		});
+
+		// Surface terminal close as an error on the stream (adapter 0.4.0)
+		try {
+			const conn = _connect();
+			if (conn && typeof conn.ready === 'function') {
+				conn.ready().catch((/** @type {any} */ err) => {
+					if (subCount > 0) {
+						_setError(new RpcError(err?.code || 'CONNECTION_CLOSED', err?.message || 'Connection permanently closed'));
+					}
+				});
+			}
+		} catch {}
+	}
 
 	return {
 		// Stamped metadata so test-affordances like `subscribeAt`
@@ -2598,83 +2709,35 @@ function _createStream(path, options, dynamicArgs, initialSchemaVersion) {
 		subscribe(fn) {
 			if (subCount++ === 0) {
 				if (_pendingCleanup) {
-					// Rapid resub - cancel the pending cleanup, subscription is still alive
+					// Rapid sync resub (same microtask) - cancel the pending cleanup,
+					// WS subscription is still attached.
 					_pendingCleanup = false;
-				} else {
-				// First subscriber - start the stream
-				fetchAndSubscribe();
-				_devtoolsStream(path, topic, subCount, merge);
-
-				// Quiescence tracking: register this stream's contribution to
-				// the global in-flight counter. Subscriber fires synchronously
-				// with the current status so initial 'loading' is captured.
-				_quiescenceUnsub = _statusStore.subscribe((s) => {
-					const inFlight = s === 'loading' || s === 'reconnecting';
-					if (inFlight && !_countedInFlight) {
-						_countedInFlight = true;
-						_addInFlight();
-					} else if (!inFlight && _countedInFlight) {
-						_countedInFlight = false;
-						_removeInFlight();
-					}
-				});
-
-				// Listen for reconnects to refetch (debounced to avoid thundering herd).
-				// `status.subscribe` fires synchronously with the current value, which
-				// for a stream subscribing during page hydration is usually 'connecting'
-				// (since `_connect()` is lazy on the first subscriber). Filter on 'open'
-				// first and track whether we've ever seen one, so the FIRST 'open' is
-				// the lifetime baseline rather than treating it as a reconnect bounce.
-				let hasOpenedOnce = false;
-				statusUnsub = status.subscribe((s) => {
-					if (s !== 'open') return;
-					if (!hasOpenedOnce) {
-						hasOpenedOnce = true;
-						return;
+				} else if (_inGracePeriod) {
+					// Resume during the grace window: WS handles were released but
+					// session state (currentValue, _lastSeq, _lastVersion, _cursor)
+					// is intact. Re-attach lifecycle listeners and call
+					// fetchAndSubscribe(); the retained cursors ride along on the
+					// subscribe envelope so the server can fill the gap from its
+					// replay buffer (or fromSeq, or truncated -> full rehydrate).
+					if (_resumeGraceTimer) {
+						clearTimeout(_resumeGraceTimer);
+						_resumeGraceTimer = null;
 					}
-					if (subCount > 0) {
-						_status = 'reconnecting';
-						_statusStore.set('reconnecting');
-						if (_reconnectTimer) clearTimeout(_reconnectTimer);
-						let delay;
-						// Reconnect jitter: spread a fleet's reconnect attempts across the
-						// window so a server restart does not get a thundering-herd retry
-						// spike. Math.random is the right primitive here - jitter does not
-						// need crypto-quality entropy. Not security-relevant.
-						if (_reconnectAttempts < 2) {
-							delay = 20 + Math.floor(Math.random() * 80);
-						} else {
-							const base = Math.min(1000 * Math.pow(2.2, _reconnectAttempts - 2), 300000);
-							delay = Math.floor(base * (0.75 + Math.random() * 0.5));
-						}
-						_reconnectAttempts++;
-						_reconnectTimer = setTimeout(() => {
-							_reconnectTimer = null;
-							if (topicUnsub) {
-								topicUnsub();
-								topicUnsub = null;
-							}
-							initialLoaded = false;
-							fetching = false;
-							buffer = [];
-							fetchAndSubscribe();
-						}, delay);
-					}
-				});
-
-				// Surface terminal close as an error on the stream (adapter 0.4.0)
-				try {
-					const conn = _connect();
-					if (conn && typeof conn.ready === 'function') {
-						conn.ready().catch((/** @type {any} */ err) => {
-							if (subCount > 0) {
-								_setError(new RpcError(err?.code || 'CONNECTION_CLOSED', err?.message || 'Connection permanently closed'));
-							}
-						});
-					}
-				} catch {}
-
-			} // end else (not _pendingCleanup)
+					_inGracePeriod = false;
+					// Flip status back to 'loading' so the newly-attached quiescence
+					// subscriber sees us as in-flight while the resume envelope is
+					// outstanding (it fires synchronously with the current value).
+					_status = 'loading';
+					_statusStore.set('loading');
+					_attachLifecycleListeners();
+					fetchAndSubscribe();
+					_devtoolsStream(path, topic, subCount, merge);
+				} else {
+					// First subscriber - start the stream
+					fetchAndSubscribe();
+					_devtoolsStream(path, topic, subCount, merge);
+					_attachLifecycleListeners();
+				}
 			}
 
 			const unsub = store.subscribe(fn);
@@ -2686,7 +2749,24 @@ function _createStream(path, options, dynamicArgs, initialSchemaVersion) {
 					queueMicrotask(() => {
 						if (_pendingCleanup && subCount === 0) {
 							_pendingCleanup = false;
-							cleanup();
+							const graceMs = _getResumeGraceMs();
+							if (graceMs > 0) {
+								// Release WS handles immediately (give server back the
+								// subscription, stop counting toward quiescence) but
+								// retain session state for graceMs to support pause/resume
+								// and back/forward navigation patterns. If a new
+								// subscribe() lands before the timer fires, it resumes
+								// from the retained seq via fetchAndSubscribe.
+								_releaseSubscription();
+								_inGracePeriod = true;
+								_resumeGraceTimer = setTimeout(() => {
+									_resumeGraceTimer = null;
+									_inGracePeriod = false;
+									_resetSession();
+								}, graceMs);
+							} else {
+								cleanup();
+							}
 						}
 					});
 				}
@@ -3336,7 +3416,7 @@ function _checkArgs(path, args) {
  * @typedef {{ path: string, args: any[], queuedAt: number, resolve: Function, reject: Function, idempotencyKey?: string, timeout?: number }} OfflineEntry
  */
 
-/** @type {{ url?: string, auth?: boolean | string, onConnect?: () => void, onDisconnect?: () => void, timeout?: number, upload?: { frameSize?: number, chunkSize?: number, highWaterMark?: number, lowWaterMark?: number }, offline?: { queue?: boolean, maxQueue?: number, maxAge?: number, replay?: 'sequential' | 'batch' | ((queue: OfflineEntry[]) => OfflineEntry[]), beforeReplay?: (call: { path: string, args: any[], queuedAt: number }) => boolean, onReplayError?: (call: { path: string, args: any[], queuedAt: number }, error: any) => void } }} */
+/** @type {{ url?: string, auth?: boolean | string, onConnect?: () => void, onDisconnect?: () => void, timeout?: number, resumeGraceMs?: number, upload?: { frameSize?: number, chunkSize?: number, highWaterMark?: number, lowWaterMark?: number }, offline?: { queue?: boolean, maxQueue?: number, maxAge?: number, replay?: 'sequential' | 'batch' | ((queue: OfflineEntry[]) => OfflineEntry[]), beforeReplay?: (call: { path: string, args: any[], queuedAt: number }) => boolean, onReplayError?: (call: { path: string, args: any[], queuedAt: number }, error: any) => void } }} */
 let _clientConfig = {};
 
 /** @type {boolean} */
@@ -3352,9 +3432,15 @@ let _isOffline = false;
 let _replayingQueue = false;
 
 /**
- * Configure client-side connection hooks and offline queue.
+ * Configure client-side connection hooks, RPC timeout, stream resume
+ * grace window, and offline queue.
+ *
+ * `resumeGraceMs` (default 60000) controls how long a stream retains its
+ * data model after the last subscriber unsubs. A new subscribe within the
+ * window resumes from the retained seq/version/cursor so the server can
+ * gap-fill instead of cold-rehydrating. Set to 0 to disable.
  *
- * @param {{ url?: string, auth?: boolean | string, onConnect?: () => void, onDisconnect?: () => void, offline?: { queue?: boolean, maxQueue?: number, maxAge?: number, replay?: 'sequential' | 'batch' | ((queue: OfflineEntry[]) => OfflineEntry[]), beforeReplay?: (call: { path: string, args: any[], queuedAt: number }) => boolean, onReplayError?: (call: { path: string, args: any[], queuedAt: number }, error: any) => void } }} config
+ * @param {{ url?: string, auth?: boolean | string, onConnect?: () => void, onDisconnect?: () => void, timeout?: number, resumeGraceMs?: number, offline?: { queue?: boolean, maxQueue?: number, maxAge?: number, replay?: 'sequential' | 'batch' | ((queue: OfflineEntry[]) => OfflineEntry[]), beforeReplay?: (call: { path: string, args: any[], queuedAt: number }) => boolean, onReplayError?: (call: { path: string, args: any[], queuedAt: number }, error: any) => void } }} config
  */
 export function configure(config) {
 	_clientConfig = config;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-realtime",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "publishConfig": {
     "tag": "latest"
   },

package/server.d.ts

@@ -2445,3 +2445,123 @@ export function close(
 	ws: WebSocket<any>,
 	ctx: { platform: Platform; subscriptions?: Set<string> | string[] }
 ): void;
+
+// ---------------------------------------------------------------------------
+// Cluster wiring + realtime() convenience factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Cluster bus contract. Any object exposing `wrap(platform)` matches.
+ * The canonical implementation is `redisBus()` from
+ * `svelte-adapter-uws-extensions/redis/pubsub`; sharded-pubsub and
+ * test buses conform to the same shape.
+ */
+export interface ClusterBus {
+	wrap(platform: Platform): Platform;
+}
+
+/**
+ * Configure the process-wide cluster bus. One declaration of cluster
+ * intent reaches every framework publish surface in lockstep: RPC
+ * `ctx.publish` (auto-wrapped by `message` / `createMessage`), cron
+ * tick publishes, the reactive watcher publish wrap (`live.effect`,
+ * `live.derived`, `live.aggregate`, `live.webhook`), and the top-level
+ * `publish()` helper.
+ *
+ * Pass `null` to clear and revert to single-replica behaviour.
+ *
+ * `configureCron({ bus })` is equivalent for the bus field - they
+ * write the same backing state. Most apps reach for
+ * `realtime({ bus, leader })` instead and never call this directly.
+ */
+export function setBus(bus: ClusterBus | null): void;
+
+/** Read the process-wide bus, or `null` when none is configured. */
+export function getBus(): ClusterBus | null;
+
+/**
+ * Read the framework-owned composed platform - the same reference
+ * handed to every reactive handler. Returns `null` before the adapter's
+ * `init({ platform })` hook has captured it on this worker.
+ */
+export function getPlatform(): Platform | null;
+
+/**
+ * Publish from outside a framework handler (e.g. a `+server.js` HTTP
+ * handler). Routes through the composed platform so the publish reaches
+ * every local subscriber, fires every reactive watcher, and relays to
+ * other cluster instances when a bus is wired. Throws when called
+ * before the platform has been captured.
+ */
+export function publish(topic: string, event: string, data?: unknown, options?: unknown): void;
+
+/**
+ * Configuration accepted by `realtime()`.
+ */
+export interface RealtimeConfig {
+	/**
+	 * Cluster bus. Pass `redisBus()` or any object exposing
+	 * `wrap(platform)` to enable cluster fan-out. Omit (or pass `null`)
+	 * for single-replica.
+	 */
+	bus?: ClusterBus | null;
+	/**
+	 * Cluster leader gate for cron's "exactly once across the cluster"
+	 * semantics. Pass `redisLeader().isLeader` (or any function returning
+	 * the current leader status). Omit for single-replica or for the
+	 * "every worker fires" default.
+	 */
+	leader?: (() => boolean) | null;
+	/**
+	 * Optional `upgrade` hook handed straight back out as part of the
+	 * returned hook set. Lets you write a single one-import-one-
+	 * destructure `hooks.ws.js`. Omit and export your own `upgrade`
+	 * separately if you prefer.
+	 */
+	upgrade?: (...args: any[]) => any;
+	/**
+	 * Optional error handler for cron / effect / derived failures.
+	 * Equivalent to calling `onError(handler)`.
+	 */
+	onError?: (path: string, error: unknown) => void;
+}
+
+/**
+ * Shape returned by `realtime()`. Spread into `hooks.ws.js` exports.
+ * `upgrade` is present only when the caller passed one in the config.
+ */
+export interface RealtimeHooks {
+	open(ws: any, ctx: { platform: Platform }): void;
+	close(ws: any, ctx: { platform: Platform; subscriptions?: Set<string> | string[] }): void;
+	message(ws: any, ctx: { data: ArrayBuffer; platform: Platform }): void;
+	init(ctx: { platform: Platform }): void;
+	upgrade?: (...args: any[]) => any;
+}
+
+/**
+ * One-call setup that wires every framework seam from a single
+ * declaration of cluster intent. Returns the standard adapter hook
+ * set so `hooks.ws.js` is a one-import-one-destructure file.
+ *
+ * Single-replica:
+ * ```js
+ * import { realtime } from 'svelte-realtime/server';
+ * export const { open, close, message, init } = realtime();
+ * export function upgrade({ cookies }) { ... }
+ * ```
+ *
+ * Cluster:
+ * ```js
+ * import { realtime } from 'svelte-realtime/server';
+ * import { redisBus, redisLeader } from 'svelte-adapter-uws-extensions/redis';
+ * export const { open, close, message, init } = realtime({
+ *   bus: redisBus(),
+ *   leader: redisLeader().isLeader,
+ * });
+ * export function upgrade({ cookies }) { ... }
+ * ```
+ *
+ * Handler-level code is byte-identical between the two modes; the only
+ * difference is whether `bus` and `leader` are passed at the top.
+ */
+export function realtime(config?: RealtimeConfig): RealtimeHooks;

package/server.js

@@ -3426,23 +3426,80 @@ let _cronPlatform = null;
 let _cronLeader = null;
 
 /**
- * Optional cluster bus for cron fan-out. When set, every cron fire
- * publishes through `_cronBus.wrap(_cronPlatform)` instead of through
- * the raw platform, so leader-only ticks reach subscribers on
- * non-leader instances via the bus's relay channel.
- *
- * Why this is cron-specific (not derived/effect/aggregate): derived /
- * aggregate watchers re-publish through the realtime-wrapped
- * `platform.publish` captured at activation time. Every instance sees
- * the source-topic firehose via its own bus subscriber and computes
- * its own derived locally; bus-relaying derived publishes would cause
- * double delivery. Cron is different - only the leader fires it, so
- * the leader's publish must relay or remote subscribers see nothing.
+ * Process-wide cluster bus. Single source of truth consulted by every
+ * publish surface in the framework (RPC `ctx.publish`, cron tick,
+ * reactive watchers' publish wrap, top-level `publish()` helper). When
+ * set, outbound publishes relay to other cluster instances via
+ * `bus.wrap(platform).publish`; inbound relays from other instances
+ * arrive through the bus's own subscriber and are broadcast on this
+ * instance via the wrapped surrogate's `publish`.
+ *
+ * Written by `setBus(bus)`, `configureCron({ bus })`, and the
+ * `realtime({ bus })` factory. Read via `getBus()` and consulted at
+ * publish-time by every framework seam so a single declaration of
+ * deployment intent covers all of them. Without a bus, every seam
+ * publishes locally (the single-replica default).
+ *
+ * Composition discipline: `bus.wrap(...)` is applied at publish time
+ * over a snapshot of the raw adapter publish (the "surrogate"). The
+ * reactive seam mutates `platform.publish` to a `derivedPublish` that
+ * routes through the wrapped surrogate when a bus is configured, so
+ * the same publish call fires reactive watchers AND relays to the
+ * cluster in one step. Inbound relays from other instances arrive via
+ * the wrapped surrogate's publish (which runs the local broadcast + the
+ * watcher fan-out without re-relaying), so derived / effect /
+ * aggregate handlers on receiving instances see the cross-cluster
+ * stream the same way they see local publishes.
  *
  * @type {{ wrap: (platform: any) => any } | null}
  */
+let _bus = null;
+/**
+ * Legacy alias retained so the existing `_cronBus` references in the
+ * cron tick read the canonical bus without surgery. Always equal to
+ * `_bus` (the setter writes both in lockstep). Treat as read-only.
+ */
 let _cronBus = null;
 
+/**
+ * Sentinel attached to platforms that have been wrapped with the
+ * process-wide bus. Lets the framework detect already-wrapped inputs
+ * and skip re-wrapping, so a user who passes a manually `bus.wrap`-ed
+ * platform via `createMessage({ platform })` is not double-wrapped by
+ * the auto-wrap path.
+ */
+const _BUS_WRAPPED = Symbol.for('svelte-realtime.busWrapped');
+
+/**
+ * Write the process-wide bus. Validated like `configureCron({ bus })`
+ * - must expose `.wrap(platform)` or be `null`. Mirrored into the
+ * legacy `_cronBus` alias so the existing cron tick keeps reading the
+ * canonical value without surgery. Bumps `_busEpoch` so memoized
+ * `bus.wrap(...)` caches (per-platform, computed lazily by the
+ * reactive wrap and the RPC message hooks) invalidate on swap.
+ * @param {{ wrap: (platform: any) => any } | null} bus
+ */
+function _setBus(bus) {
+	if (bus !== null && (typeof bus !== 'object' || typeof bus.wrap !== 'function')) {
+		throw new Error('[svelte-realtime] setBus: bus must expose a .wrap(platform) method or be null');
+	}
+	_bus = bus;
+	_cronBus = bus;
+	_busEpoch++;
+}
+
+/** Read the process-wide bus (or null when no cluster intent is wired). */
+function _getBus() {
+	return _bus;
+}
+
+/**
+ * Monotonic counter bumped on every bus swap. Used by per-platform
+ * `bus.wrap(...)` caches to detect "the bus changed under me, re-wrap"
+ * without holding a strong reference to the old bus.
+ */
+let _busEpoch = 0;
+
 /**
  * One-shot flag for the "configureCron leader without bus" warning.
  * Setting `leader` declares cluster intent; not also wiring a bus
@@ -5192,6 +5249,49 @@ function _wrapPlatformPublish(platform) {
 		? /** @type {any} */ (platform).publishBatched.bind(platform)
 		: null;
 
+	// Memoized bus-wrapped surrogate. Recomputed when the process-wide
+	// bus changes (detected via `_busEpoch`). The surrogate's `publish`
+	// is `derivedPublishLocal` (local broadcast + watcher fan-out, no
+	// re-relay), so inbound bus deliveries fire watchers on the
+	// receiving instance without bouncing the message back out onto the
+	// bus. The wrapped surrogate's `publish` (set up by the extension's
+	// `bus.wrap`) does relay + delegate-to-surrogate; outbound publishes
+	// from user code go through `derivedPublish` below, which routes via
+	// this cache when a bus is configured.
+	let _cachedBusEpoch = -1;
+	/** @type {((topic: string, event: string, data: any, opts?: any) => any) | null} */
+	let _busPublish = null;
+	/** @type {((batch: any) => any) | null} */
+	let _busPublishBatched = null;
+	function _refreshBusCache() {
+		if (_cachedBusEpoch === _busEpoch) return;
+		_cachedBusEpoch = _busEpoch;
+		const bus = _getBus();
+		if (!bus) {
+			_busPublish = null;
+			_busPublishBatched = null;
+			return;
+		}
+		// Surrogate holds derivedPublishLocal as its publish so inbound
+		// cluster relays still fire reactive watchers on this instance
+		// but do not bounce back out. Spread carries the rest of the
+		// platform surface (subscribe, send, redis, replay, ...) so the
+		// extensions's bus.wrap sees a complete platform shape.
+		/** @type {any} */
+		const surrogate = Object.assign(Object.create(Object.getPrototypeOf(platform)), platform);
+		surrogate.publish = derivedPublishLocal;
+		if (originalPublishBatched) surrogate.publishBatched = derivedPublishBatchedLocal;
+		const wrapped = bus.wrap(surrogate);
+		// Tag so a downstream auto-wrap pass (e.g. message hook) can
+		// detect "already wrapped by us" and skip re-wrapping. The tag
+		// records the bus identity so a later swap re-wraps cleanly.
+		/** @type {any} */ (wrapped)[_BUS_WRAPPED] = bus;
+		_busPublish = typeof wrapped.publish === 'function' ? wrapped.publish.bind(wrapped) : null;
+		_busPublishBatched = typeof /** @type {any} */ (wrapped).publishBatched === 'function'
+			? /** @type {any} */ (wrapped).publishBatched.bind(wrapped)
+			: null;
+	}
+
 	let _publishDepth = 0;
 
 	function fireWatchers(topic, event, data) {
@@ -5297,10 +5397,37 @@ function _wrapPlatformPublish(platform) {
 		_publishDepth--;
 	}
 
-	platform.publish = function derivedPublish(topic, event, data, opts) {
+	// Inner publish used by the bus-wrap surrogate. Does the local
+	// broadcast + watcher fan-out but NEVER relays - relay is the
+	// outer `derivedPublish`'s job (via the wrapped surrogate). This
+	// is also what runs when an inbound message arrives from another
+	// instance, so cluster-relayed events fire derived / effect /
+	// aggregate watchers on the receiving instance.
+	function derivedPublishLocal(topic, event, data, opts) {
 		const result = originalPublish(topic, event, data, opts);
 		fireWatchers(topic, event, data);
 		return result;
+	}
+
+	function derivedPublishBatchedLocal(batch) {
+		const result = originalPublishBatched ? originalPublishBatched(batch) : undefined;
+		if (Array.isArray(batch) && _watchedTopics.size > 0) {
+			for (const item of batch) {
+				if (!item || typeof item.topic !== 'string') continue;
+				fireWatchers(item.topic, item.event, item.data);
+			}
+		}
+		return result;
+	}
+
+	// Outbound user-facing publish. When a bus is configured, routes
+	// through the wrapped surrogate so the publish both broadcasts
+	// locally (with watchers) and relays to the cluster in one step.
+	// Without a bus, identical to the legacy local-only path.
+	platform.publish = function derivedPublish(topic, event, data, opts) {
+		_refreshBusCache();
+		if (_busPublish) return _busPublish(topic, event, data, opts);
+		return derivedPublishLocal(topic, event, data, opts);
 	};
 
 	if (originalPublishBatched) {
@@ -5311,14 +5438,9 @@ function _wrapPlatformPublish(platform) {
 		// publishes from the batched path - they only fire from the unbatched
 		// platform.publish path that some test mocks happen to use.
 		/** @type {any} */ (platform).publishBatched = function derivedPublishBatched(batch) {
-			const result = originalPublishBatched(batch);
-			if (Array.isArray(batch) && _watchedTopics.size > 0) {
-				for (const item of batch) {
-					if (!item || typeof item.topic !== 'string') continue;
-					fireWatchers(item.topic, item.event, item.data);
-				}
-			}
-			return result;
+			_refreshBusCache();
+			if (_busPublishBatched) return _busPublishBatched(batch);
+			return derivedPublishBatchedLocal(batch);
 		};
 	}
 }
@@ -5589,7 +5711,7 @@ export function setCronPlatform(platform) {
 export function configureCron(config) {
 	if (config === null) {
 		_cronLeader = null;
-		_cronBus = null;
+		_setBus(null);
 		return;
 	}
 	if (typeof config !== 'object') {
@@ -5608,13 +5730,15 @@ export function configureCron(config) {
 		}
 	}
 	if (config.bus !== undefined) {
-		if (config.bus === null) {
-			_cronBus = null;
-		} else if (typeof config.bus !== 'object' || typeof config.bus.wrap !== 'function') {
+		// Routes through `_setBus` so the canonical `_bus` (consulted by
+		// the reactive wrap, the RPC auto-wrap, and the top-level
+		// `publish()` helper) stays in lockstep with the legacy
+		// `_cronBus` alias - one declaration of cluster intent covers
+		// every framework seam, not just cron.
+		if (config.bus !== null && (typeof config.bus !== 'object' || typeof config.bus.wrap !== 'function')) {
 			throw new Error('[svelte-realtime] configureCron: bus must expose a .wrap(platform) method or be null');
-		} else {
-			_cronBus = config.bus;
 		}
+		_setBus(config.bus);
 	}
 	// Diagnostic: cluster intent (leader) without cluster fan-out (bus)
 	// is almost always a misconfig. Leader-only cron ticks publish on the
@@ -8056,16 +8180,59 @@ export function close(ws, { platform, subscriptions }) {
 	}
 }
 
+/**
+ * Per-platform cache of the bus-wrapped surrogate used by the RPC hook
+ * (`message` / `createMessage`). Keyed on the raw adapter platform, with
+ * the bus identity stored alongside so a `setBus(differentBus)` swap is
+ * detected and re-wrapped without holding a strong reference to the old
+ * bus. WeakMap so the entry clears when the platform is GC-eligible.
+ * @type {WeakMap<object, { bus: any, wrapped: any, epoch: number }>}
+ */
+const _rpcBusWrapCache = new WeakMap();
+
+/**
+ * Resolve the platform handed to `handleRpc` from the WS message path.
+ * When a process-wide bus is configured (via `setBus`,
+ * `configureCron({ bus })`, or `realtime({ bus })`), the raw adapter
+ * platform is wrapped on first use and memoized for subsequent
+ * messages on the same platform. When the user manually pre-wraps via
+ * `createMessage({ platform })`, this is bypassed (their callback
+ * runs first) so we never double-wrap.
+ *
+ * @param {import('svelte-adapter-uws').Platform} platform
+ * @returns {import('svelte-adapter-uws').Platform}
+ */
+function _autoBusWrap(platform) {
+	const bus = _getBus();
+	if (!bus) return platform;
+	// Idempotence: if the input has already been wrapped by this
+	// framework against the current bus, return it untouched.
+	if (/** @type {any} */ (platform)[_BUS_WRAPPED] === bus) return platform;
+	const entry = _rpcBusWrapCache.get(/** @type {any} */ (platform));
+	if (entry && entry.bus === bus && entry.epoch === _busEpoch) return entry.wrapped;
+	const wrapped = bus.wrap(platform);
+	/** @type {any} */ (wrapped)[_BUS_WRAPPED] = bus;
+	_rpcBusWrapCache.set(/** @type {any} */ (platform), { bus, wrapped, epoch: _busEpoch });
+	return wrapped;
+}
+
 /**
  * Ready-made message hook. Re-export from hooks.ws.js for zero-config RPC routing.
  *
+ * When a process-wide bus is configured (via `setBus`,
+ * `configureCron({ bus })`, or `realtime({ bus })`), this hook auto-
+ * wraps the adapter platform so RPC `ctx.publish` relays to other
+ * cluster instances without any per-hook wiring. Without a bus,
+ * publishes stay local - the single-replica default with zero
+ * overhead.
+ *
  * Signature matches the adapter's message hook exactly.
  *
  * @param {any} ws
  * @param {{ data: ArrayBuffer, platform: import('svelte-adapter-uws').Platform }} ctx
  */
 export function message(ws, { data, platform }) {
-	handleRpc(ws, data, platform);
+	handleRpc(ws, data, _autoBusWrap(platform));
 }
 
 /**
@@ -8086,10 +8253,205 @@ export function createMessage(options) {
 	const hasRpcOpts = beforeExecute || onError;
 
 	return function customMessage(ws, { data, platform }) {
-		const p = transformPlatform ? transformPlatform(platform) : platform;
+		// User-supplied `platform` callback signals "I am wiring the
+		// transform myself"; we run it as-is and skip the auto bus
+		// wrap so we never double-wrap. Without the callback, we
+		// route through `_autoBusWrap` so the process-wide bus
+		// reaches RPC handlers with zero per-hook config.
+		const p = transformPlatform ? transformPlatform(platform) : _autoBusWrap(platform);
 		const handled = handleRpc(ws, data, p, hasRpcOpts ? rpcOpts : undefined);
 		if (!handled && onUnhandled) {
 			onUnhandled(ws, data, p);
 		}
 	};
 }
+
+// ---------------------------------------------------------------------------
+// Cluster wiring: process-wide bus + composed-platform accessors
+// ---------------------------------------------------------------------------
+
+/**
+ * Configure the process-wide cluster bus. Consumed by every framework
+ * publish surface in lockstep: RPC `ctx.publish` (via the `message` /
+ * `createMessage` auto-wrap), cron tick publishes, reactive watchers'
+ * publish wrap (`live.effect`, `live.derived`, `live.aggregate`,
+ * `live.webhook`), and the top-level `publish()` helper. One
+ * declaration of cluster intent covers all of them.
+ *
+ * Pass a bus exposing `.wrap(platform)` (e.g. `redisBus()` from
+ * `svelte-adapter-uws-extensions/redis/pubsub`) to enable cluster
+ * fan-out. Pass `null` to clear and revert to single-replica behaviour.
+ *
+ * `configureCron({ bus })` is equivalent to `setBus(bus)` for the bus
+ * field - they write the same backing state. Pick whichever reads more
+ * naturally at the call site; the typical app uses
+ * `realtime({ bus, leader })` instead and never calls either directly.
+ *
+ * @param {{ wrap: (platform: any) => any } | null} bus
+ *
+ * @example
+ * ```js
+ * // hooks.ws.js (Layer 1 / expert wiring)
+ * import { setBus, setCronPlatform, _activateDerived, configureCron, message } from 'svelte-realtime/server';
+ * import { redisBus, redisLeader } from 'svelte-adapter-uws-extensions/redis';
+ *
+ * const bus = redisBus();
+ * setBus(bus);
+ * configureCron({ leader: redisLeader() });
+ *
+ * export { message };
+ * export function init({ platform }) {
+ *   setCronPlatform(platform);
+ *   _activateDerived(platform);
+ * }
+ * ```
+ */
+export function setBus(bus) {
+	_setBus(bus);
+}
+
+/**
+ * Read the process-wide bus, or `null` when none is configured. Useful
+ * for diagnostics, conditional cluster-only wiring, and tests.
+ *
+ * @returns {{ wrap: (platform: any) => any } | null}
+ */
+export function getBus() {
+	return _getBus();
+}
+
+/**
+ * Read the framework-owned composed platform - the same reference handed
+ * to every `live.effect` / `live.derived` / `live.aggregate` handler and
+ * threaded through `ctx.platform` in RPC / cron / webhook contexts.
+ *
+ * Returns `null` before `setCronPlatform(platform)` /
+ * `_activateDerived(platform)` / `realtime().init({ platform })` has
+ * captured the adapter platform on this worker.
+ *
+ * Use for publish from outside a framework handler (e.g. a `+server.js`
+ * HTTP handler) when you want the same cluster semantics. Most callers
+ * should reach for the top-level `publish()` helper instead.
+ *
+ * @returns {import('svelte-adapter-uws').Platform | null}
+ */
+export function getPlatform() {
+	return _derivedPlatform || _cronPlatform || null;
+}
+
+/**
+ * Publish from outside a framework handler. Routes through the
+ * framework-owned composed platform, so the same publish reaches every
+ * local subscriber, fires every reactive watcher (`live.effect`,
+ * `live.derived`, `live.aggregate`), and relays to other cluster
+ * instances when a bus is wired - identical semantics to a publish
+ * inside an RPC, cron, or effect handler.
+ *
+ * Throws when the platform has not yet been captured (called before
+ * the adapter's `init({ platform })` hook fires, or in a process where
+ * no svelte-realtime wiring ran). For the rare case where you genuinely
+ * want a no-op when the platform is absent (e.g. a shared utility
+ * that may run in non-realtime contexts), guard with `getPlatform()`.
+ *
+ * @param {string} topic
+ * @param {string} event
+ * @param {unknown} data
+ * @param {unknown} [options]
+ *
+ * @example
+ * ```js
+ * // src/routes/webhooks/+server.js
+ * import { publish } from 'svelte-realtime/server';
+ *
+ * export async function POST({ request }) {
+ *   const payload = await request.json();
+ *   publish('audit', 'webhook', payload);
+ *   return new Response();
+ * }
+ * ```
+ */
+export function publish(topic, event, data, options) {
+	const platform = getPlatform();
+	if (!platform) {
+		throw new Error('[svelte-realtime] publish: platform has not been captured yet. Wire `realtime({ ... }).init` (or `setCronPlatform` + `_activateDerived`) from your hooks.ws.js init({ platform }) hook before calling publish() at module scope.');
+	}
+	return platform.publish(topic, event, data, options);
+}
+
+// ---------------------------------------------------------------------------
+// realtime() - Layer 2 convenience factory
+// ---------------------------------------------------------------------------
+
+/**
+ * One-call setup that wires every framework seam from a single
+ * declaration of cluster intent. Returns the standard adapter hook
+ * set (`open`, `close`, `message`, `init`) plus optional `upgrade`,
+ * so `hooks.ws.js` is a one-import-one-destructure file:
+ *
+ * ```js
+ * // src/hooks.ws.js (single-replica)
+ * import { realtime } from 'svelte-realtime/server';
+ * export const { upgrade, open, close, message, init } = realtime({
+ *   upgrade: ({ cookies }) => validate(cookies),
+ * });
+ * ```
+ *
+ * ```js
+ * // src/hooks.ws.js (cluster)
+ * import { realtime } from 'svelte-realtime/server';
+ * import { redisBus, redisLeader } from 'svelte-adapter-uws-extensions/redis';
+ *
+ * export const { upgrade, open, close, message, init } = realtime({
+ *   bus: redisBus(),
+ *   leader: redisLeader().isLeader,
+ *   upgrade: ({ cookies }) => validate(cookies),
+ * });
+ * ```
+ *
+ * Handler-level code (`live.rpc`, `live.effect`, `live.derived`,
+ * `live.aggregate`, `live.cron`, `live.webhook`, ...) is byte-identical
+ * between the two modes - the only difference between single-replica
+ * and cluster is whether `bus` and `leader` are passed at the top.
+ *
+ * `realtime()` is sugar over the existing primitives. Internally it
+ * calls `setBus(bus)`, `configureCron({ leader })`,
+ * `setCronPlatform(platform)`, and `_activateDerived(platform)` in the
+ * right order when the adapter's `init` hook fires. Mixing `realtime()`
+ * with direct calls to those primitives is supported - the primitives
+ * remain first-class and write the same backing state.
+ *
+ * @param {{
+ *   bus?: { wrap: (platform: any) => any } | null,
+ *   leader?: (() => boolean) | null,
+ *   upgrade?: (...args: any[]) => any,
+ *   onError?: (path: string, error: unknown) => void,
+ * }} [config]
+ */
+export function realtime(config) {
+	const cfg = config || {};
+	const { bus, leader, upgrade: upgradeFn, onError } = cfg;
+
+	if (bus !== undefined) _setBus(bus);
+	if (leader !== undefined) configureCron({ leader });
+	if (typeof onError === 'function') {
+		// Routes through the existing module-level setter so the
+		// behaviour matches a direct `onError(handler)` call - one
+		// source of truth for the cron / effect / derived error path.
+		_serverErrorHandler = onError;
+	}
+
+	const hooks = {
+		open: pushHooks.open,
+		close: pushHooks.close,
+		message,
+		init(ctx) {
+			if (!ctx || !ctx.platform) {
+				throw new Error('[svelte-realtime] realtime().init: missing platform on hook context (expected adapter init({ platform }) signature)');
+			}
+			setCronPlatform(ctx.platform);
+			_activateDerived(ctx.platform);
+		},
+	};
+	if (typeof upgradeFn === 'function') /** @type {any} */ (hooks).upgrade = upgradeFn;
+	return hooks;
+}