svelte-realtime 0.5.5 → 0.5.7

package/README.md

@@ -2239,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)
@@ -3014,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)
+
+`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 const message = createMessage({ platform: (p) => bus.wrap(p) });
+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.
 
@@ -3051,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)
@@ -3072,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
@@ -3586,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-realtime",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "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,71 @@ 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;
 
+/**
+ * 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
@@ -5109,43 +5157,73 @@ export function __registerDerived(path, fn) {
  * triggered externally when the platform fires publish.
  * @param {import('svelte-adapter-uws').Platform} platform
  */
-/** @type {WeakSet<object>} Guard against double-wrapping platform.publish during HMR */
+/**
+ * Tracks platforms whose `publish` has been swapped to `derivedPublish`
+ * by `_wrapPlatformPublish`. WeakSet so per-connection platform clones
+ * inherit the mutation via prototype chain without forcing the base
+ * platform to live longer than the adapter intends - entries clear
+ * naturally when the platform itself becomes GC-eligible. The WeakSet
+ * is the single source of truth for "is this platform's publish path
+ * framework-owned?" - consulted by `_ensureWrap` (the universal idempotent
+ * installer), referenced indirectly by every publish surface (RPC, cron,
+ * reactive, top-level `publish()`).
+ *
+ * @type {WeakSet<object>}
+ */
 const _activatedPlatforms = new WeakSet();
 
-export function _activateDerived(platform) {
-	_derivedPlatform = platform;
-	_activateDerivedCalled = true;
-
-	// Only wrap platform.publish if there are actual reactive registrations,
-	// OR a lazy push has signaled "registrations are coming." Without the
-	// `_hasLazyReactive` clause, calling `_activateDerived` from
-	// `init({ platform })` (the README's recommended call site) would
-	// early-return on a still-empty registry and leave the wrap uninstalled
-	// - so a cron-driven publish that fires before the lazy queue resolves
-	// (or before the first WS connection) silently bypasses every watcher.
-	if (
-		_derivedBySource.size === 0
-		&& _effectBySource.size === 0
-		&& _aggregateBySource.size === 0
-		&& !_hasDynamicDerived
-		&& !_hasLazyReactive
-	) {
-		return;
-	}
-
+/**
+ * Universal install point for the framework's publish wrap. Idempotent
+ * against `_activatedPlatforms`, safe under HMR, called from every site
+ * that captures or first sees a platform reference:
+ * - `setCronPlatform(platform)` - call from `realtime().init` or
+ *   directly from `hooks.ws.js`'s `init({ platform })`.
+ * - `_activateDerived(platform)` - same call site, alternative entry.
+ * - The default `message` hook + `createMessage` returned hook - first
+ *   message per platform installs the wrap, so apps that wire only
+ *   `setBus(bus)` and re-export `message` (no init hook, no
+ *   `_activateDerived` call) still get cluster routing on first RPC.
+ *
+ * Single install site eliminates the entire class of "outer wrap stacks
+ * on inner wrap" bugs: there is only ONE `bus.wrap(...)` call in the
+ * whole framework (inside `_wrapPlatformPublish`'s `_refreshBusCache`)
+ * and it's composed with everything else (reactive watchers, batched
+ * fast path, replay routing) at publish time via the mutated
+ * `derivedPublish` / `derivedPublishBatched`.
+ *
+ * @param {any} platform
+ */
+function _ensureWrap(platform) {
+	if (!platform) return;
 	// svelte-adapter-uws hands hooks a per-connection platform created via
-	// Object.create(basePlatform). Wrapping that per-connection object leaves
-	// every other connection's inherited publish / publishBatched untouched,
-	// because their lookups walk the prototype chain to the original base.
-	// Resolve to the base prototype so the wrap is visible to all connections
-	// that share it. Test mocks pass plain objects whose proto is
-	// Object.prototype - in that case wrap the object itself.
+	// Object.create(basePlatform). Wrapping that per-connection object would
+	// leave every other connection's inherited publish / publishBatched
+	// untouched, because their lookups walk the prototype chain to the
+	// original base. Resolve to the base prototype so the wrap is visible
+	// to all connections that share it. Test mocks pass plain objects whose
+	// proto is Object.prototype - in that case wrap the object itself.
 	const target = _resolveWrapTarget(platform);
 	if (_activatedPlatforms.has(target)) return;
 	_activatedPlatforms.add(target);
 	_wrapPlatformPublish(target);
 }
 
+export function _activateDerived(platform) {
+	_derivedPlatform = platform;
+	_activateDerivedCalled = true;
+	// Install the framework's publish wrap unconditionally. Pre-0.5.7 this
+	// was gated on "any reactive primitives registered?" to avoid wrap
+	// overhead on apps that didn't use derived/effect/aggregate. With the
+	// wrap now also responsible for bus routing (every publish surface
+	// consults `_getBus()` via `derivedPublish`), gating would create a
+	// window where a publish escapes routing - the late-activation race
+	// from the 0.5.6 audit. The per-publish overhead of an empty wrap is
+	// one function call plus a `Map.has` check on an empty Map (`O(1)`,
+	// branch-predicted to false); the install cost is one closure scope
+	// per platform, paid once at init.
+	_ensureWrap(platform);
+}
+
 /**
  * Install the publish wrap retroactively if `_activateDerived(platform)`
  * was called against an empty registry and a registration has now landed
@@ -5164,10 +5242,7 @@ export function _activateDerived(platform) {
  */
 function _maybeLateActivate() {
 	if (!_derivedPlatform) return;
-	const target = _resolveWrapTarget(_derivedPlatform);
-	if (_activatedPlatforms.has(target)) return;
-	_activatedPlatforms.add(target);
-	_wrapPlatformPublish(target);
+	_ensureWrap(_derivedPlatform);
 }
 
 /**
@@ -5192,6 +5267,45 @@ 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);
+		_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 +5411,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 +5452,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);
 		};
 	}
 }
@@ -5526,6 +5662,12 @@ export function setCronPlatform(platform) {
 	// Re-arm the dedup so a subsequent platform-loss (defensive only --
 	// platform never goes null in practice) gets one fresh warning.
 	_cronPlatformWarnFired = false;
+	// Install the framework's publish wrap here too: pure-cron apps that
+	// never call `_activateDerived` (no reactive primitives wired) still
+	// need cluster routing when a bus is configured. The wrap is idempotent
+	// via `_activatedPlatforms`, so when `realtime().init` calls both
+	// `setCronPlatform` and `_activateDerived` the second call is a no-op.
+	if (platform) _ensureWrap(platform);
 }
 
 /**
@@ -5589,7 +5731,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 +5750,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
@@ -5991,17 +6135,15 @@ export async function _tickCron() {
 					}
 					return;
 				}
-				// Cluster fan-out: when a bus is wired via
-				// `configureCron({ bus })`, route the cron fire's
-				// publishes through `bus.wrap(platform)` so other cluster
-				// instances see them too. Without a bus, leader-only ticks
-				// only reach subscribers on the leader worker. Fresh wrap
-				// per fire is cheap (object literal allocation) and
-				// avoids any caching staleness around platform / bus
-				// mutation. Falls through to the raw platform when no bus
-				// is configured (single-instance dev, the canonical
-				// happy path).
-				const cronPub = _cronBus ? _cronBus.wrap(_cronPlatform) : _cronPlatform;
+				// Cluster fan-out is the framework's publish wrap's job
+				// now (one wrap site for the whole framework, installed
+				// by `_ensureWrap` from `setCronPlatform`). The cron tick
+				// uses the captured `_cronPlatform` directly - its
+				// `publish` is `derivedPublish`, which consults the
+				// process-wide bus at publish time. No outer `bus.wrap(...)`
+				// here, which eliminates the 0.5.6 double-relay class of
+				// bugs by construction.
+				const cronPub = _cronPlatform;
 				const _h = _getCtxHelpers(cronPub);
 				const ctx = _buildCtx(null, null, cronPub, _h, null);
 				const result = await entry.fn(ctx);
@@ -8057,7 +8199,43 @@ export function close(ws, { platform, subscriptions }) {
 }
 
 /**
- * Ready-made message hook. Re-export from hooks.ws.js for zero-config RPC routing.
+ * One-shot dev-mode flag for the "createMessage({ platform: callback })
+ * is redundant" warning. A user-supplied `platform` callback in
+ * `createMessage` was the pre-0.5.6 way to wire bus.wrap into the RPC
+ * hook. With 0.5.7+ the framework installs a single publish wrap on the
+ * adapter platform (via `_ensureWrap`, called from
+ * `setCronPlatform` / `_activateDerived` / first message), and that
+ * wrap is the sole `bus.wrap(...)` site. A manual callback that wraps
+ * with `bus.wrap` stacks an outer relay on top of the inner one and
+ * double-delivers every RPC publish to other replicas. We can't detect
+ * the manual-wrap case from the callback's output (user-built wraps
+ * don't carry our sentinel), but the input platform is the activated
+ * adapter platform, so we warn at receive time when both conditions
+ * hold. Module-level so a user creating multiple message hooks sees
+ * one warning total.
+ */
+let _manualPlatformCallbackWarnFired = false;
+
+/**
+ * Reset the one-shot dev-warn flag for tests. Production deployments
+ * don't need this - the warning is meant to fire once per process and
+ * the flag never needs resetting outside test isolation.
+ */
+export function _resetManualPlatformCallbackWarn() {
+	_manualPlatformCallbackWarnFired = false;
+}
+
+/**
+ * Ready-made message hook. Re-export from hooks.ws.js for zero-config
+ * RPC routing.
+ *
+ * First call per platform installs the framework's publish wrap via
+ * `_ensureWrap` (idempotent), so apps that wire `setBus(bus)` and
+ * re-export `message` but never call `_activateDerived` /
+ * `setCronPlatform` themselves still get cluster routing on first
+ * RPC. Subsequent calls are no-ops on the wrap path. Without a bus,
+ * the wrap's per-publish overhead is one function call plus a
+ * `Map.has` check on an empty Map - well below noise.
  *
  * Signature matches the adapter's message hook exactly.
  *
@@ -8065,6 +8243,7 @@ export function close(ws, { platform, subscriptions }) {
  * @param {{ data: ArrayBuffer, platform: import('svelte-adapter-uws').Platform }} ctx
  */
 export function message(ws, { data, platform }) {
+	_ensureWrap(platform);
 	handleRpc(ws, data, platform);
 }
 
@@ -8086,10 +8265,232 @@ export function createMessage(options) {
 	const hasRpcOpts = beforeExecute || onError;
 
 	return function customMessage(ws, { data, platform }) {
-		const p = transformPlatform ? transformPlatform(platform) : platform;
+		// Install the framework's publish wrap on the platform (idempotent
+		// per platform). After this returns, `platform.publish` is
+		// `derivedPublish`, which is the single bus-routing site for the
+		// whole framework. Done BEFORE any transform callback so the
+		// callback sees the wrapped publish path (correct ordering for
+		// non-bus transforms like metrics instrumentation; double-wrap
+		// detected and warned for legacy bus.wrap callbacks).
+		_ensureWrap(platform);
+		let p;
+		if (transformPlatform) {
+			// Dev-only nudge: a `platform` callback against an
+			// already-activated platform with a process-wide bus wired
+			// almost always means a legacy `(p) => bus.wrap(p)` callback
+			// is layered on top of `derivedPublish`'s inner bus.wrap,
+			// which double-relays every RPC publish. Warn once per
+			// process; users with a non-bus transform (e.g. metrics
+			// instrumentation) can ignore.
+			if (_IS_DEV
+				&& !_manualPlatformCallbackWarnFired
+				&& _getBus()
+			) {
+				_manualPlatformCallbackWarnFired = true;
+				console.warn(
+					"[svelte-realtime] createMessage({ platform: callback }) is redundant when `setBus(...)` is wired: " +
+					"the framework already routes ctx.publish through the bus, so a manual `bus.wrap(p)` callback double-relays every RPC publish to other replicas. " +
+					"Drop the `platform` option to fix. If your callback does a non-bus transform (e.g. metrics) you can ignore this warning.\n" +
+					"  See: https://svti.me/cluster-relay"
+				);
+			}
+			p = transformPlatform(platform);
+		} else {
+			p = 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;
+}