svelte-realtime 0.5.6 → 0.5.8

package/README.md

@@ -227,6 +227,7 @@ Note: `ctx.user` may contain adapter-injected properties (`__subscriptions`, `re
 
 **Client features**
 - [Batching](#batching)
+- [Volatile RPC (fire-and-forget)](#volatile-rpc-fire-and-forget)
 - [Optimistic updates](#optimistic-updates)
 - [Stream pagination](#stream-pagination)
 - [Undo and redo](#undo-and-redo)
@@ -957,6 +958,8 @@ const [board, column] = await batch(() => [
 
 Each call resolves or rejects independently - one failure does not cancel the others. Batches are limited to 50 calls - enforced both client-side (rejects before sending) and server-side.
 
+A `batch()` containing only one call sends a bare RPC frame (no batch envelope) and the server replies through the normal RPC path - so the defensive "always wrap writes in batch() for symmetry" pattern pays no envelope overhead. Batches of 2+ keep the envelope.
+
 ### Server-side batching
 
 Use `ctx.batch()` inside RPC handlers to publish multiple messages in a single call:
@@ -973,6 +976,59 @@ export const resetBoard = live(async (ctx, boardId) => {
 
 ---
 
+## Volatile RPC (fire-and-forget)
+
+For high-frequency one-way calls where the caller has no reply to await - cursor moves, drag updates, typing indicators, telemetry beacons, heartbeats - use `live.volatile(fn)` server-side + `.fireAndForget(...args)` client-side. The wire frame carries no `id`; the server runs the full handler chain (middleware, guards, rate limits, validation) but does not write a response.
+
+```js
+// src/lib/realtime/cursors.js
+import { live } from 'svelte-realtime';
+
+export const moveCursor = live.volatile(async (ctx, boardId, pos) => {
+  // ctx.publish / ctx.shed / guards all work normally
+  ctx.publish(`board:${boardId}`, 'cursor', pos);
+});
+```
+
+```svelte
+<script>
+  import { moveCursor } from '$live/cursors';
+
+  function onPointerMove(e) {
+    moveCursor.fireAndForget(boardId, { x: e.clientX, y: e.clientY });
+    // returns void synchronously - no Promise, no await
+  }
+</script>
+```
+
+What `.fireAndForget()` skips that a normal RPC does:
+- ID allocation (`_nextId()`)
+- Promise allocation
+- Dedup-Map entry + `queueMicrotask(delete)`
+- Pending-Map entry
+- Timer allocation (per-call 30s timeout)
+- DevTools-pending entry
+
+At 60-120Hz on a single hot path that is 100K+ short-lived heap allocations per second avoided on the client.
+
+**Safety:**
+- **Errors disappear silently from the caller.** A volatile call that fails auth, validation, or throws still runs through metrics (`_recordRpcMetrics`) and server logs - operators see the failure - but the wire carries no reply, so the caller does not. Use `live.volatile()` only when this is the intended contract.
+- **Backpressure drop.** Before send, the client reads `WS.bufferedAmount`; if it exceeds `volatileBackpressureBytes` (default 4 MB, configurable via `configure(...)`), the frame is dropped silently and `__devtools.volatileDropped` ticks. Dev-mode emits a one-shot `console.warn` on first drop per session.
+- **Offline drop.** Volatile calls made while disconnected are silently dropped. They do not enter the offline queue (which is for awaited mutations).
+- **Inside `batch()`.** Throws in dev, no-op in prod. Volatile bypasses batching by design.
+
+**Server-side marker is recommended, not required.** The wire shape (`id` absent) is the actual contract. A `.fireAndForget()` against a plain `live()` handler also works - server processes it, just skips the reply - but dev-mode emits a one-shot warning per such path naming the handler so accidental fire-and-forget surfaces. Mark intentional one-way handlers with `live.volatile()` to silence the warning and document intent. The marker can sit at any depth inside `live.rateLimit` / `live.idempotent` / `live.breaker` / `live.validated` / `live.lock` wrappers (the framework walks `__wrappedFn` to find it).
+
+**When NOT to use `.fireAndForget()`:**
+- The caller needs to know whether the call succeeded -> use the normal awaited RPC.
+- The call needs to be retried on failure -> use `.with({ idempotencyKey })` + normal RPC.
+- The call should survive a disconnect -> use the offline queue via the normal RPC.
+- The call is sometimes one-way, sometimes interesting -> keep the handler `live()` (not `live.volatile()`) and choose at each call site.
+
+**`live.notify` vs `.fireAndForget()`.** Both are fire-and-forget, but they go in opposite directions: `live.notify(target, event, data)` is server -> client (server-initiated push, no client reply expected), while `.fireAndForget(...args)` is client -> server (client-initiated RPC, no server reply emitted). Different surfaces, different use cases.
+
+---
+
 ## Optimistic updates
 
 Apply changes to a stream store instantly, then roll back if the server call fails.
@@ -3663,8 +3719,8 @@ Import from `svelte-realtime/client`.
 |---|---|
 | `RpcError` | Typed error with `code` field |
 | `UploadHandle<T>` | Type for `live.upload` client handles (thenable + events + cancel) |
-| `batch(fn, options?)` | Group RPC calls into one WebSocket frame |
-| `configure(config)` | Connection hooks, offline queue, upload frame size |
+| `batch(fn, options?)` | Group RPC calls into one WebSocket frame (or send bare frame when only one call was collected) |
+| `configure(config)` | Connection hooks, offline queue, upload frame size, `volatileBackpressureBytes` |
 | `combine(...stores, fn)` | Multi-store composition |
 | `onSignal(userId, callback)` | Listen for point-to-point signals |
 | `onDerived` | Re-exported from adapter: reactive derived topic subscription |

package/client.d.ts

@@ -115,6 +115,31 @@ export function __rpc(path: string): ((...args: any[]) => Promise<any>) & {
 				| { event: string; data: any }
 		): (...callArgs: any[]) => Promise<any>;
 	};
+	/**
+	 * Send a fire-and-forget RPC. Returns `void` synchronously - no Promise,
+	 * no pending entry, no timeout, no devtools-pending. The wire frame is
+	 * `{rpc, args}` with no `id` field; the server runs the full handler
+	 * chain but does not write a response. Errors are silently dropped on
+	 * the wire.
+	 *
+	 * Pair with `live.volatile(fn)` server-side. Use for high-frequency
+	 * one-way RPCs - cursor moves, drag updates, typing indicators,
+	 * telemetry beacons, heartbeats.
+	 *
+	 * Safety:
+	 * - Offline: silent no-op (no offline queue).
+	 * - Backpressure: dropped when `conn.bufferedAmount` exceeds the
+	 *   configured `volatileBackpressureBytes` (default 4 MB);
+	 *   `__devtools.volatileDropped` ticks.
+	 * - Inside `batch()`: throws in dev, no-op in prod.
+	 *
+	 * @example
+	 * ```js
+	 * import { moveCursor } from '$live/cursors';
+	 * moveCursor.fireAndForget('board-1', { x, y });
+	 * ```
+	 */
+	fireAndForget: (...args: any[]) => void;
 };
 
 /**
@@ -548,6 +573,16 @@ export function configure(config: {
 	 * @default 60000
 	 */
 	resumeGraceMs?: number;
+	/**
+	 * `WS.bufferedAmount` threshold (in bytes) at which `.fireAndForget()`
+	 * sends are dropped silently and `__devtools.volatileDropped` ticks.
+	 * Sized for 120Hz cursor + drag traffic; raise it if your app
+	 * legitimately bursts above 4 MB of in-flight volatile traffic,
+	 * lower it on mobile-constrained targets where the OS send buffer
+	 * is tighter.
+	 * @default 4_194_304 (4 MB)
+	 */
+	volatileBackpressureBytes?: number;
 	/** Offline mutation queue configuration. */
 	offline?: {
 		/** Enable queuing RPCs when disconnected. */

package/client.js

@@ -15,6 +15,11 @@ export const empty = readable(undefined);
 
 const _textEncoder = new TextEncoder();
 
+/** Dev-mode flag. True when not running under a Vite production build
+ * (and true under vitest, where `import.meta.env.PROD` is undefined).
+ * Gates dev-only warnings and devtools instrumentation. */
+const _IS_DEV = typeof import.meta === 'undefined' || !import.meta.env || !import.meta.env.PROD;
+
 // - Bounded-by-default capacity caps (client side) -------------------------
 // Existing caps not re-declared (already enforced at their sites):
 //   _historyMax           50    FIFO    per-stream undo/redo
@@ -540,6 +545,70 @@ export function __rpc(path) {
 		return _sendRpc(path, args);
 	};
 
+	/**
+	 * Send a fire-and-forget RPC. Returns `void` synchronously - no Promise,
+	 * no pending entry, no timeout, no devtools-pending. The wire frame is
+	 * `{rpc, args}` with no `id` field; the server runs the full handler
+	 * chain (middleware, guards, rate limits, validation) but does not
+	 * write a response. Errors are silently dropped on the wire.
+	 *
+	 * Pair with `live.volatile(fn)` server-side. Use for high-frequency
+	 * one-way RPCs - cursor moves, drag updates, typing indicators,
+	 * telemetry beacons, heartbeats. Skips: `_nextId()`, the Promise
+	 * allocation, the dedup map, the pending Map entry, the timer
+	 * allocation, the devtools-pending entry.
+	 *
+	 * Safety:
+	 * - **Offline:** silent no-op while disconnected. No offline-queue
+	 *   entry. Lossy under disconnect IS the contract.
+	 * - **Backpressure:** if `conn.bufferedAmount` exceeds
+	 *   `volatileBackpressureBytes` (default 4 MB - see `configure(...)`),
+	 *   the send is dropped and the drop counter ticks. Prevents the WS
+	 *   send queue from growing unbounded on a stuck connection.
+	 * - **Inside `batch()`:** dev-mode throws; production no-op. Volatile
+	 *   bypasses batching by design.
+	 *
+	 * @param {...any} args - Arguments forwarded to the handler
+	 * @returns {void}
+	 *
+	 * @example
+	 * ```js
+	 * import { moveCursor } from '$live/cursors';
+	 * moveCursor.fireAndForget('board-1', { x, y });
+	 * ```
+	 */
+	rpcCall.fireAndForget = function fireAndForget(...args) {
+		if (_terminated) return;
+		if (_isOffline) { _volatileDropped++; return; }
+		if (_batchCollector) {
+			if (_IS_DEV) {
+				throw new Error(
+					`[svelte-realtime] '${path}'.fireAndForget() cannot be used inside batch() - volatile RPCs bypass batching.\n  See: https://svti.me/volatile`
+				);
+			}
+			return;
+		}
+		ensureListener();
+		ensureDisconnectListener();
+		const conn = _connect();
+		const cap = _clientConfig.volatileBackpressureBytes || _DEFAULT_VOLATILE_BACKPRESSURE_BYTES;
+		if (typeof conn.bufferedAmount === 'number' && conn.bufferedAmount > cap) {
+			_volatileDropped++;
+			if (__devtools) __devtools.volatileDropped = _volatileDropped;
+			if (_IS_DEV && !_volatileBackpressureWarned) {
+				_volatileBackpressureWarned = true;
+				console.warn(
+					`[svelte-realtime] volatile RPC '${path}' dropped: WS bufferedAmount (${conn.bufferedAmount} bytes) exceeded volatileBackpressureBytes (${cap}). ` +
+					`This warning fires once per session; subsequent drops increment __devtools.volatileDropped silently. ` +
+					`Raise the threshold via configure({ volatileBackpressureBytes }) if your app legitimately bursts above 4 MB of in-flight WS traffic.\n  See: https://svti.me/volatile`
+				);
+			}
+			return;
+		}
+		_devtoolsVolatileSent(path, args);
+		conn.sendQueued({ rpc: path, args });
+	};
+
 	/**
 	 * Attach per-call options. Returns a callable bound to those options.
 	 *
@@ -835,6 +904,23 @@ const _DEFAULT_UPLOAD_HIGH_WATER_MARK = 4 * 1024 * 1024;
 const _DEFAULT_UPLOAD_LOW_WATER_MARK = 1 * 1024 * 1024;
 const _UPLOAD_DRAIN_POLL_MS = 50;
 
+/** Default backpressure threshold for `.fireAndForget()`. When `conn.bufferedAmount`
+ * exceeds this, the volatile send is dropped silently and the drop counter
+ * ticks. Sized for 120Hz cursor + drag traffic (~24 KB/sec per client on
+ * volatile paths): 4 MB gives ~170s of buffer headroom before drops kick
+ * in - healthy demos never trip it; a genuinely dead connection does
+ * before browser OOM. Override via `configure({ volatileBackpressureBytes })`. */
+const _DEFAULT_VOLATILE_BACKPRESSURE_BYTES = 4 * 1024 * 1024;
+
+/** Volatile-send drop counter. Incremented when a `.fireAndForget()` call is
+ * dropped (offline, backpressure, terminated). Exposed to devtools as
+ * `__devtools.volatileDropped`. */
+let _volatileDropped = 0;
+
+/** Dev-warn dedup: one-shot warn when the first volatile backpressure drop
+ * happens, so apps notice in development that they're hitting the cap. */
+let _volatileBackpressureWarned = false;
+
 /** Server-discovered `platform.maxPayloadLength`. Updated whenever an upload
  * response arrives carrying `__cap`. 0 = not yet discovered. */
 let _discoveredUploadMaxFrameSize = 0;
@@ -3363,6 +3449,35 @@ export function batch(fn, options) {
 		return Promise.reject(new RpcError('INVALID_REQUEST', 'Batch exceeds maximum of 50 calls'));
 	}
 
+	const conn = _connect();
+	const effectiveTimeout = _getTimeout();
+
+	// Batch-of-1: send the bare RPC frame instead of wrapping in a batch
+	// envelope. Defensive callers (single writes wrapped in batch() for API
+	// symmetry) should not pay envelope cost or the round-trip of a batch
+	// response. The collected entry's pending entry was created with
+	// timer: null inside the call's __rpc path; attach a per-call timer
+	// here so the single call still times out cleanly.
+	if (collected.length === 1) {
+		const call = collected[0];
+		const _startTime = Date.now();
+		const sleepThreshold = Math.max(effectiveTimeout * 3, 90000);
+		const timer = setTimeout(() => {
+			const entry = pending.get(call.id);
+			if (!entry) return;
+			pending.delete(call.id);
+			if (Date.now() - _startTime > sleepThreshold) {
+				entry.reject(new RpcError('DISCONNECTED', 'Connection interrupted (device sleep)'));
+			} else {
+				entry.reject(new RpcError('TIMEOUT', `RPC '${call.rpc}' timed out after ${Math.round(effectiveTimeout / 1000)}s`));
+			}
+		}, effectiveTimeout);
+		const existing = pending.get(call.id);
+		if (existing) existing.timer = timer;
+		conn.sendQueued(call);
+		return Promise.all(promises);
+	}
+
 	// Set a batch-level timeout (sleep-aware)
 	const _batchStartTime = Date.now();
 	const batchTimer = setTimeout(() => {
@@ -3383,10 +3498,9 @@ export function batch(fn, options) {
 				entry.reject(new RpcError('TIMEOUT', `Batch timed out after 30s`));
 			}
 		}
-	}, _getTimeout());
+	}, effectiveTimeout);
 
 	// Send all calls as one frame
-	const conn = _connect();
 	const payload = { batch: collected };
 	if (options?.sequential) payload.sequential = true;
 	conn.sendQueued(payload);
@@ -3416,7 +3530,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, 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 } }} */
+/** @type {{ url?: string, auth?: boolean | string, onConnect?: () => void, onDisconnect?: () => void, timeout?: number, resumeGraceMs?: number, volatileBackpressureBytes?: 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} */
@@ -3440,7 +3554,14 @@ let _replayingQueue = false;
  * 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, 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
+ * `volatileBackpressureBytes` (default 4 MB) is the `WS.bufferedAmount`
+ * threshold at which `.fireAndForget()` sends are dropped silently and
+ * `__devtools.volatileDropped` increments. Sized for 120Hz cursor + drag
+ * traffic; raise it if your app legitimately bursts above 4 MB of in-flight
+ * volatile traffic, lower it on mobile-constrained targets where the OS
+ * send buffer is tighter.
+ *
+ * @param {{ url?: string, auth?: boolean | string, onConnect?: () => void, onDisconnect?: () => void, timeout?: number, resumeGraceMs?: number, volatileBackpressureBytes?: 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;
@@ -3743,11 +3864,15 @@ const _DEFAULT_REDACT_KEYS = new Set([
 
 const _MAX_STREAM_EVENTS = 20;
 
+const _DEVTOOLS_VOLATILE_MAX = 100;
+
 /**
  * @type {{
  *   history: any[],
  *   streams: Map<string, any>,
  *   pending: Map<string, any>,
+ *   volatile: any[],
+ *   volatileDropped: number,
  *   redactKeys: Set<string>,
  *   paused: boolean
  * } | null}
@@ -3757,11 +3882,37 @@ export const __devtools = (typeof import.meta !== 'undefined' && !import.meta.en
 		history: new Array(50).fill(null),
 		streams: new Map(),
 		pending: new Map(),
+		volatile: new Array(_DEVTOOLS_VOLATILE_MAX).fill(null),
+		volatileDropped: 0,
 		redactKeys: new Set(_DEFAULT_REDACT_KEYS),
 		paused: false
 	}
 	: null;
 
+/** Ring buffer index for the devtools volatile send track. */
+let _devtoolsVolatileIdx = 0;
+let _devtoolsVolatileSeq = 0;
+
+/**
+ * Record a fire-and-forget RPC send for devtools. Send-only - there is no
+ * matching completion event because the wire shape carries no `id` and the
+ * server never replies. Ring buffer is bounded (`_DEVTOOLS_VOLATILE_MAX`,
+ * drop-oldest) so a high-frequency 60-120Hz mover can't anchor unbounded
+ * dev-mode memory.
+ * @param {string} path
+ * @param {any[]} args
+ */
+function _devtoolsVolatileSent(path, args) {
+	if (!__devtools) return;
+	__devtools.volatile[_devtoolsVolatileIdx] = {
+		path,
+		args,
+		time: Date.now(),
+		seq: ++_devtoolsVolatileSeq
+	};
+	_devtoolsVolatileIdx = (_devtoolsVolatileIdx + 1) % _DEVTOOLS_VOLATILE_MAX;
+}
+
 /**
  * Walk a value, replacing matched keys with `'[REDACTED]'`. Caps recursion
  * depth at 5 and array length at 50 so dev-only capture doesn't pin large

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-realtime",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "publishConfig": {
     "tag": "latest"
   },
@@ -89,12 +89,12 @@
   "peerDependencies": {
     "@sveltejs/kit": "^2.0.0",
     "svelte": "^4.0.0 || ^5.0.0",
-    "svelte-adapter-uws": "^0.5.1"
+    "svelte-adapter-uws": "^0.5.2"
   },
   "devDependencies": {
     "@playwright/test": "^1.59.1",
     "fast-check": "^4.7.0",
-    "svelte-adapter-uws-extensions": "^0.5.1",
+    "svelte-adapter-uws-extensions": "^0.5.2",
     "vitest": "^4.0.18"
   },
   "keywords": [

package/server.d.ts

@@ -958,6 +958,35 @@ export namespace live {
 	 */
 	function middleware(fn: (ctx: LiveContext<any>, next: () => Promise<any>) => Promise<any>): void;
 
+	/**
+	 * Mark a handler as fire-and-forget (volatile). The server still runs
+	 * the full middleware / guard / rate-limit / validation chain, but does
+	 * NOT write a response frame back. The matching client surface is
+	 * `rpc.fireAndForget(...args)`, which sends a no-id wire frame and
+	 * returns void synchronously.
+	 *
+	 * Use for high-frequency one-way RPCs where the caller has no reply
+	 * to await: cursor moves, drag updates, typing indicators, telemetry
+	 * beacons, heartbeats.
+	 *
+	 * Errors on a volatile call still run through the handler's error
+	 * path (metrics, server logs) but are not transmitted - per the
+	 * fire-and-forget contract.
+	 *
+	 * @param fn - Handler function (ctx, ...args)
+	 *
+	 * @example
+	 * ```js
+	 * export const moveCursor = live.volatile(async (ctx, boardId, pos) => {
+	 *   cursor.update(ctx.ws, `board:${boardId}`, pos, ctx.platform);
+	 * });
+	 *
+	 * // Client:
+	 * moveCursor.fireAndForget('board-1', { x: 100, y: 200 });
+	 * ```
+	 */
+	function volatile<T extends (ctx: LiveContext<any>, ...args: any[]) => any>(fn: T): T;
+
 	/**
 	 * Wrap a stream with a server-side gate predicate.
 	 * If the predicate returns false (or a `Promise` resolving to false),

package/server.js

@@ -2067,6 +2067,62 @@ live.public = function publicMarker(fn) {
 	return fn;
 };
 
+/**
+ * Mark a handler as fire-and-forget (volatile). The server still runs the
+ * full middleware / guard / rate-limit / validation chain, but does NOT
+ * write a response frame back. The client calls the handler via
+ * `.fireAndForget(...args)`, which sends a no-id wire frame and returns
+ * void synchronously.
+ *
+ * Use for high-frequency one-way RPCs where the caller has no reply to
+ * await: cursor moves, drag updates, typing indicators, telemetry beacons,
+ * heartbeats. The handler-level marker is intent + documentation; the wire
+ * shape (no `id` field) is the actual contract, so calling
+ * `.fireAndForget()` on a non-volatile handler also works (server processes
+ * it, just skips the reply). The marker exists so reviewers can see at a
+ * glance that a handler is intentionally one-way and that errors will not
+ * surface to the caller.
+ *
+ * Errors on a volatile call still run through the handler's error path
+ * (metrics, server logs) but are not transmitted - per the fire-and-forget
+ * contract. Pair with `live.rateLimit` + `ctx.shed` for admission control;
+ * shed volatile calls naturally have no caller to inform.
+ *
+ * @param {Function} fn - Handler function (ctx, ...args)
+ * @returns {Function}
+ *
+ * @example
+ * ```js
+ * // src/lib/realtime/cursors.js
+ * import { live } from 'svelte-realtime';
+ *
+ * export const moveCursor = live.volatile(async (ctx, boardId, pos) => {
+ *   cursor.update(ctx.ws, `board:${boardId}`, pos, ctx.platform);
+ * });
+ *
+ * // Client:
+ * import { moveCursor } from '$live/cursors';
+ * moveCursor.fireAndForget('board-1', { x: 100, y: 200 });  // no await, no reply
+ * ```
+ */
+live.volatile = function volatileMarker(fn) {
+	if (typeof fn !== 'function') {
+		throw new Error('[svelte-realtime] live.volatile(fn) requires a handler function');
+	}
+	/** @type {any} */ (fn).__isLive = true;
+	/** @type {any} */ (fn).__volatileRpc = true;
+	return fn;
+};
+
+/**
+ * Dev-mode warn dedup for fire-and-forget calls against non-volatile
+ * handlers. Bounded so a script-driven barrage doesn't anchor unbounded
+ * memory; first 256 distinct paths warn once each, then quiet.
+ * @type {Set<string>}
+ */
+const _volatileWarnSet = new Set();
+const _VOLATILE_WARN_CAP = 256;
+
 /**
  * Wraps a live() function with a sliding window rate limiter.
  *
@@ -3461,15 +3517,6 @@ let _bus = null;
  */
 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
@@ -5166,43 +5213,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
@@ -5221,10 +5298,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);
 }
 
 /**
@@ -5282,10 +5356,6 @@ function _wrapPlatformPublish(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)
@@ -5648,6 +5718,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);
 }
 
 /**
@@ -6115,17 +6191,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);
@@ -6516,7 +6590,20 @@ export function handleRpc(ws, data, platform, options) {
 		return true;
 	}
 
-	if (typeof msg.rpc !== 'string' || typeof msg.id !== 'string') return false;
+	if (typeof msg.rpc !== 'string') return false;
+
+	// Volatile (fire-and-forget) RPC: frames with no `id` field signal
+	// "no reply expected". Server runs the full handler chain but skips
+	// the response emit. The wire shape (id absent) is the contract; the
+	// matching client surface is `rpc.fireAndForget(...)` plus the
+	// `live.volatile()` server-side marker.
+	if (msg.id === undefined) {
+		if (msg.rpc.length === 0) return false;
+		_executeVolatileRpc(ws, msg, platform, options);
+		return true;
+	}
+
+	if (typeof msg.id !== 'string') return false;
 
 	// envelope.shape invariant: rpc and id must be non-empty for routing
 	assert(msg.rpc.length > 0 && msg.id.length > 0, 'realtime/handleRpc.envelope.non-empty', { rpcLen: msg.rpc.length, idLen: msg.id.length });
@@ -6537,6 +6624,58 @@ async function _executeRpc(ws, msg, platform, options) {
 	_respond(ws, platform, msg.id, result);
 }
 
+/**
+ * Execute a fire-and-forget RPC. Runs the full handler chain (middleware,
+ * guards, rate limits, validation) but does NOT write a response frame.
+ * `msg.id` is absent on the wire; an internal correlation id is synthesized
+ * so metrics, devtools, and `_executeSingleRpc`'s response shape stay
+ * uniform without leaking onto the wire.
+ *
+ * Dev-mode warns once per non-volatile handler that receives a fire-and-forget
+ * call (bounded by `_VOLATILE_WARN_CAP` distinct paths) so accidental
+ * `.fireAndForget()` calls against handlers that have a meaningful return
+ * value surface in the server log.
+ *
+ * @param {any} ws
+ * @param {{ rpc: string, args?: any[] }} msg
+ * @param {import('svelte-adapter-uws').Platform} platform
+ * @param {{ beforeExecute?: (ws: any, rpcPath: string, args: any[]) => Promise<void> | void, onError?: (path: string, error: unknown, ctx: any) => void }} [options]
+ */
+async function _executeVolatileRpc(ws, msg, platform, options) {
+	if (_IS_DEV) {
+		const path = msg.rpc;
+		const fn = await _resolveRegistryEntry(path);
+		if (fn && !_hasVolatileMarker(fn) && !_volatileWarnSet.has(path)) {
+			if (_volatileWarnSet.size < _VOLATILE_WARN_CAP) _volatileWarnSet.add(path);
+			console.warn(
+				`[svelte-realtime] handler '${path}' received a fire-and-forget call but is not marked live.volatile(). ` +
+				"Errors will be silently dropped (no reply is sent). Wrap the handler with live.volatile() to make this intent explicit.\n  See: https://svti.me/volatile"
+			);
+		}
+	}
+	/** @type {any} */ (msg).id = '__volatile';
+	await _executeSingleRpc(ws, /** @type {any} */ (msg), platform, options);
+	// No _respond - fire-and-forget contract.
+}
+
+/**
+ * Walk the `__wrappedFn` chain produced by `live.rateLimit` / `live.idempotent`
+ * / `live.breaker` / `live.validated` / `live.lock` to find an inner
+ * `__volatileRpc` marker. Lets users wrap a `live.volatile(handler)` core
+ * with any combination of the other markers in any order without tripping
+ * the dev-mode "not marked volatile" warning. Bounded walk (depth 8) so a
+ * pathological cycle cannot loop forever.
+ * @param {any} fn
+ */
+function _hasVolatileMarker(fn) {
+	let cur = fn;
+	for (let i = 0; cur && i < 8; i++) {
+		if (cur.__volatileRpc) return true;
+		cur = cur.__wrappedFn;
+	}
+	return false;
+}
+
 /**
  * Execute a batch of RPC calls. Supports parallel (default) and sequential modes.
  *
@@ -8181,50 +8320,43 @@ 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 }>}
+ * 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.
  */
-const _rpcBusWrapCache = new WeakMap();
+let _manualPlatformCallbackWarnFired = false;
 
 /**
- * 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}
+ * 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.
  */
-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;
+export function _resetManualPlatformCallbackWarn() {
+	_manualPlatformCallbackWarnFired = false;
 }
 
 /**
- * Ready-made message hook. Re-export from hooks.ws.js for zero-config RPC routing.
+ * 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.
+ * 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.
  *
@@ -8232,7 +8364,8 @@ function _autoBusWrap(platform) {
  * @param {{ data: ArrayBuffer, platform: import('svelte-adapter-uws').Platform }} ctx
  */
 export function message(ws, { data, platform }) {
-	handleRpc(ws, data, _autoBusWrap(platform));
+	_ensureWrap(platform);
+	handleRpc(ws, data, platform);
 }
 
 /**
@@ -8253,12 +8386,39 @@ export function createMessage(options) {
 	const hasRpcOpts = beforeExecute || onError;
 
 	return function customMessage(ws, { data, 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);
+		// 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);

package/vite.js

@@ -41,6 +41,11 @@ const PUBLIC_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.public\s*\(/g;
 // module are intentionally public.
 const PUBLIC_COMMENT_RE = /(?:\/\/|\/\*)\s*realtime-allow-public\b/;
 const IDEMPOTENT_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.idempotent\s*\(/g;
+// `live.volatile(...)` is the fire-and-forget RPC marker. From the client's
+// perspective the export is a normal RPC stub - the `.fireAndForget()` method
+// is attached by the `__rpc()` factory itself - so the codegen emits the same
+// `__rpc(...)` line as a plain `live()` export.
+const VOLATILE_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.volatile\s*\(/g;
 
 const _validSegmentReVite = /^[a-zA-Z0-9_]+$/;
 
@@ -1097,7 +1102,7 @@ function _generateClientStubs(filePath, modulePath, dir) {
 	const hasPublicComment = PUBLIC_COMMENT_RE.test(source);
 	// live() and the wrappers that pass through unchanged on the client
 	// (validated/lock/idempotent/rateLimit/public) all emit the same __rpc line.
-	for (const re of [LIVE_EXPORT_RE, VALIDATED_EXPORT_RE, LOCK_EXPORT_RE, IDEMPOTENT_EXPORT_RE, RATE_LIMIT_EXPORT_RE, PUBLIC_EXPORT_RE]) {
+	for (const re of [LIVE_EXPORT_RE, VALIDATED_EXPORT_RE, LOCK_EXPORT_RE, IDEMPOTENT_EXPORT_RE, RATE_LIMIT_EXPORT_RE, PUBLIC_EXPORT_RE, VOLATILE_EXPORT_RE]) {
 		re.lastIndex = 0;
 		while ((match = re.exec(source)) !== null) {
 			const name = match[1];
@@ -1886,8 +1891,8 @@ function _generateRegistry(liveDir, dir, topicsRegistry) {
 		const registered = new Set();
 		let match;
 		// live() and the wrappers that share the plain __register line
-		// (validated/lock/idempotent/rateLimit).
-		for (const re of [LIVE_EXPORT_RE, VALIDATED_EXPORT_RE, LOCK_EXPORT_RE, IDEMPOTENT_EXPORT_RE, RATE_LIMIT_EXPORT_RE]) {
+		// (validated/lock/idempotent/rateLimit/volatile).
+		for (const re of [LIVE_EXPORT_RE, VALIDATED_EXPORT_RE, LOCK_EXPORT_RE, IDEMPOTENT_EXPORT_RE, RATE_LIMIT_EXPORT_RE, VOLATILE_EXPORT_RE]) {
 			re.lastIndex = 0;
 			while ((match = re.exec(source)) !== null) {
 				const name = match[1];
@@ -2381,6 +2386,24 @@ function _generateTypeDeclarations(liveDir, dir) {
 			}
 		}
 
+		// Detect live.volatile() exports - inner handler at arg index 0
+		// (same shape as plain live()). The .fireAndForget(...) method is
+		// attached by the __rpc(...) factory itself, so the generated stub
+		// types as the plain RPC signature; users get the method at runtime.
+		VOLATILE_EXPORT_RE.lastIndex = 0;
+		while ((match = VOLATILE_EXPORT_RE.exec(source)) !== null) {
+			const name = match[1];
+			handledNames.add(name);
+			if (!exports.some(e => e.includes(`export const ${name}:`))) {
+				if (isTS) {
+					const sig = _extractFunctionSignatureFor(source, name, 'live\\.volatile', 0);
+					exports.push(`  export const ${name}: ${sig};`);
+				} else {
+					exports.push(`  export const ${name}: (...args: any[]) => Promise<any>;`);
+				}
+			}
+		}
+
 		// Detect live.room() exports
 		ROOM_EXPORT_RE.lastIndex = 0;
 		while ((match = ROOM_EXPORT_RE.exec(source)) !== null) {