svelte-realtime 0.5.7 → 0.5.10

package/MIGRATION.md

@@ -287,6 +287,56 @@ Saturation behavior: entries with a pending leave timer are evicted first; if st
 
 Not required. Adopting these gets you the full 0.5 experience.
 
+### `ctx.skip(key, ms)` for per-key handler gating
+
+**What's new.** A per-key gate primitive on `LiveContext`. Returns `true` to skip the call (key is within its cooldown window), `false` to run it. Pairs with `ctx.shed` semantically so call sites read uniformly with an early `return`:
+
+```js
+export const moveNote = live(async (ctx, noteId, x, y) => {
+  if (ctx.shed('background')) return;           // pressure shed
+  if (ctx.skip(`move:${noteId}`, 16)) return;   // per-key handler gate
+  await dbUpdateNote(noteId, x, y);
+  ctx.publish(TOPICS.notes, 'updated', { noteId, x, y });
+});
+```
+
+State is per-replica (CPU/DB shed, not cluster-wide rate limit; for cross-replica gating use `live.rateLimit({ store: 'redis' })` or the `redis/ratelimit` extension). Capped at 5000 active entries with fail-open semantics on overflow (returns `false`, dev-warns once). Throws `LiveError('INVALID_ARG', ...)` on `key` not a string or `ms` not a positive finite number.
+
+This is the primitive developers were reaching for when they wrote `ctx.throttle('move:id', 50)` thinking it gated handler execution. The old `ctx.throttle` / `ctx.debounce` are outbound publish helpers (renamed to `publishThrottled` / `publishDebounced` - see [Cosmetic](#cosmetic)); the new `ctx.skip` is the actual handler gate.
+
+### `createMessage({ onJsonMessage(ws, msg, platform) })` for plugin-layer JSON dispatch
+
+**What's new.** A callback on `createMessage` that receives the parsed envelope when a non-RPC text frame parses as a JSON object. Replaces the manual `TextDecoder + JSON.parse + dispatch` pattern that plugins like `cursor.hooks.message` previously required in user `hooks.ws.js`.
+
+```js
+// Before
+import { createMessage } from 'svelte-realtime/server';
+import { cursor } from '$lib/server/redis';
+
+export const message = createMessage({
+  onUnhandled(ws, data, platform) {
+    if (!(data instanceof ArrayBuffer) || data.byteLength < 2) return;
+    let msg;
+    try { msg = JSON.parse(new TextDecoder().decode(data)); } catch { return; }
+    if (!msg || typeof msg !== 'object') return;
+    if (msg.type === 'cursor') {
+      cursor.hooks.message(ws, { data: msg, platform });
+    }
+  }
+});
+
+// After
+export const message = createMessage({
+  onJsonMessage(ws, msg, platform) {
+    if (msg.type === 'cursor') cursor.hooks.message(ws, { data: msg, platform });
+  }
+});
+```
+
+Two-tier lookup: (1) fast path uses the `msg` field forwarded by `svelte-adapter-uws@^0.5.3` (one parse total); (2) fallback parses locally for frames the adapter didn't fast-path (older adapter, > 8 KiB frame, or non-`{"ty` prefix). Frames that aren't JSON, can't parse, parse to a non-object, or exceed the depth cap (`maxJsonDepth`, default 64) fall through to `onUnhandled` with the original raw bytes. The adapter's `maxPayloadLength` (default 1 MB) is the structural size ceiling.
+
+Both `onJsonMessage` and `onUnhandled` can be set together for mixed JSON / binary frame handling.
+
 ### Move `setCronPlatform` and `live.configurePush({ remoteRegistry })` to `init({ platform })`
 
 **What changed.** Both functions used to be wired from `open(ws, platform)`. The recommended call site is now the adapter's `init({ platform })` lifecycle hook, which fires once per worker after the listen socket is bound and before any upgrade / open / message hook runs. This eliminates the boot-to-first-connect window where cron ticks were no-ops and `live.push` could not reach cross-instance users.
@@ -376,6 +426,26 @@ export const transport = realtimeTransport();
 
 Type-only changes, deprecations, dead code removed. No action required for most apps.
 
+### `ctx.throttle` / `ctx.debounce` renamed to `ctx.publishThrottled` / `ctx.publishDebounced`; old names accepted as soft-deprecated aliases
+
+**What changed.** The names `throttle` / `debounce` in JS-land (lodash, RxJS, Underscore) typically mean "gate a function's execution." The realtime helpers actually scheduled outbound publishes - misreading the name as a gate led to calls like `ctx.throttle('move:noteId', 50)` (developer intent: "gate this handler") which silently published junk frames to a topic nobody subscribed to at the full client rate (`event=50` (number), `data=undefined`, `ms=undefined` -> `setTimeout(_, 0)` -> zero-ms window -> next call publishes again). The new names `publishThrottled` / `publishDebounced` put "publish" central so the misread becomes structurally impossible.
+
+For the gate-handler use case the developer was actually after, `ctx.skip(key, ms)` is the new primitive (see [Recommended new patterns](#recommended-new-patterns)).
+
+**How to migrate.** Optional rename for new code:
+
+```diff
+- ctx.throttle(topic, event, data, ms)
++ ctx.publishThrottled(topic, event, data, ms)
+
+- ctx.debounce(topic, event, data, ms)
++ ctx.publishDebounced(topic, event, data, ms)
+```
+
+The old names keep working as aliases indefinitely. A one-time dev warning per process per name fires on first call to the old name; production behaviour is unchanged. To silence the dev warning, rename. `live.cron()` and `live()` contexts both gained the new names; both keep the old aliases.
+
+If you wrote `ctx.throttle('move:id', 50)` thinking it would gate handler execution, the fix is `if (ctx.skip('move:id', 50)) return` at the top of the handler body. See the `ctx.skip` migration entry in [Recommended new patterns](#recommended-new-patterns).
+
 ### `pushHooks.close` now drains stream-subscription bookkeeping when called with `ctx`
 
 **What changed.** Pre-0.5, `pushHooks.close` was push-only. Apps following the JSDoc-ordained `export const close = pushHooks.close;` left stream-subscription bookkeeping (`_topicWsCounts`, silent-topic watchdogs, `__onUnsubscribe` callbacks) un-drained. A 30s flurry of `silent topic` warnings fired after every page closed.

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.7",
+  "version": "0.5.10",
   "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.3"
   },
   "devDependencies": {
     "@playwright/test": "^1.59.1",
     "fast-check": "^4.7.0",
-    "svelte-adapter-uws-extensions": "^0.5.1",
+    "svelte-adapter-uws-extensions": "^0.5.3",
     "vitest": "^4.0.18"
   },
   "keywords": [

package/server.d.ts

@@ -9,9 +9,32 @@ export interface CronContext {
 	platform: Platform;
 	/** Shorthand for `platform.publish` - delegates to whatever platform was passed in. */
 	publish: Platform['publish'];
-	/** Throttled publish - sends at most once per `ms` milliseconds. */
+	/**
+	 * Publish a value to a topic at most once per `ms` milliseconds.
+	 * The latest value always arrives (trailing edge). Outbound publish
+	 * helper - does NOT gate handler execution. For per-key handler gating
+	 * use `ctx.skip(key, ms)`.
+	 */
+	publishThrottled(topic: string, event: string, data: any, ms: number): void;
+	/**
+	 * Publish a value to a topic after `ms` milliseconds of silence. Outbound
+	 * publish helper - does NOT gate handler execution. For per-key handler
+	 * gating use `ctx.skip(key, ms)`.
+	 */
+	publishDebounced(topic: string, event: string, data: any, ms: number): void;
+	/**
+	 * @deprecated Renamed to `publishThrottled`. The old name reads like a
+	 * handler gate, but it is a publish helper. For per-key handler gating
+	 * use `ctx.skip(key, ms)`. Kept as a soft-deprecated alias indefinitely;
+	 * a one-time dev warning fires on first call.
+	 */
 	throttle(topic: string, event: string, data: any, ms: number): void;
-	/** Debounced publish - sends after `ms` milliseconds of silence. */
+	/**
+	 * @deprecated Renamed to `publishDebounced`. The old name reads like a
+	 * handler gate, but it is a publish helper. For per-key handler gating
+	 * use `ctx.skip(key, ms)`. Kept as a soft-deprecated alias indefinitely;
+	 * a one-time dev warning fires on first call.
+	 */
 	debounce(topic: string, event: string, data: any, ms: number): void;
 	/** Send a point-to-point signal to a specific user. */
 	signal(userId: string, event: string, data: any): void;
@@ -37,12 +60,58 @@ export interface LiveContext<UserData = unknown> {
 	publish: Platform['publish'];
 	/** Cursor value sent by the client for paginated stream requests. `null` if not paginated. */
 	cursor: any;
-	/** Throttled publish - sends at most once per `ms` milliseconds. */
+	/**
+	 * Publish a value to a topic at most once per `ms` milliseconds.
+	 * The latest value always arrives (trailing edge). Outbound publish
+	 * helper - does NOT gate handler execution. For per-key handler gating
+	 * use `ctx.skip(key, ms)`.
+	 */
+	publishThrottled(topic: string, event: string, data: any, ms: number): void;
+	/**
+	 * Publish a value to a topic after `ms` milliseconds of silence. Outbound
+	 * publish helper - does NOT gate handler execution. For per-key handler
+	 * gating use `ctx.skip(key, ms)`.
+	 */
+	publishDebounced(topic: string, event: string, data: any, ms: number): void;
+	/**
+	 * @deprecated Renamed to `publishThrottled`. The old name reads like a
+	 * handler gate, but it is a publish helper. For per-key handler gating
+	 * use `ctx.skip(key, ms)`. Kept as a soft-deprecated alias indefinitely;
+	 * a one-time dev warning fires on first call.
+	 */
 	throttle(topic: string, event: string, data: any, ms: number): void;
-	/** Debounced publish - sends after `ms` milliseconds of silence. */
+	/**
+	 * @deprecated Renamed to `publishDebounced`. The old name reads like a
+	 * handler gate, but it is a publish helper. For per-key handler gating
+	 * use `ctx.skip(key, ms)`. Kept as a soft-deprecated alias indefinitely;
+	 * a one-time dev warning fires on first call.
+	 */
 	debounce(topic: string, event: string, data: any, ms: number): void;
 	/** Send a point-to-point signal to a specific user. */
 	signal(userId: string, event: string, data: any): void;
+	/**
+	 * Per-key handler gate. Returns `true` to skip the call (key is within
+	 * its cooldown window), `false` to run it (no entry, or window elapsed).
+	 * Pair with an early `return` inside the handler body.
+	 *
+	 * State is per-replica - this is a CPU/DB shed, not a cluster-wide rate
+	 * limit. For cross-replica gating use `live.rateLimit({ store: 'redis' })`
+	 * or `redis/ratelimit` from svelte-adapter-uws-extensions.
+	 *
+	 * Throws `LiveError('INVALID_ARG', ...)` if `key` isn't a string or `ms`
+	 * isn't a positive finite number. Capped at 5000 active entries with
+	 * fail-open semantics on overflow (returns `false`, dev-warns once).
+	 *
+	 * @example
+	 * ```js
+	 * export const moveNote = live(async (ctx, noteId, x, y) => {
+	 *   if (ctx.skip(`move:${noteId}`, 16)) return;  // drop calls within 16ms
+	 *   await dbUpdateNote(noteId, x, y);
+	 *   ctx.publish(TOPICS.notes, 'updated', { noteId, x, y });
+	 * });
+	 * ```
+	 */
+	skip(key: string, ms: number): boolean;
 	/**
 	 * Pressure-aware shed check. Returns `true` if a request of the given
 	 * class of service should be shed under current `platform.pressure`.
@@ -500,7 +569,48 @@ export interface CreateMessageOptions {
 	onError?(path: string, error: unknown, ctx: LiveContext<any>): void;
 
 	/**
-	 * Called when a message is not an RPC request.
+	 * Called when a non-RPC text frame parses as a JSON object envelope.
+	 * The framework runs `TextDecoder + JSON.parse` once (or, when the
+	 * adapter already parsed the frame for its own control-message routing,
+	 * uses the adapter-forwarded value directly - one parse total), and
+	 * hands the parsed value to this callback.
+	 *
+	 * Dispatch by `msg.type` inside the callback. Plugin-layer hooks
+	 * (`cursor.hooks.message`, future presence/typing) consume the parsed
+	 * value so user wiring doesn't re-parse on every frame.
+	 *
+	 * Frames that don't look like a JSON object (first byte not `{`),
+	 * fail to parse, or sit at nesting depth greater than `maxJsonDepth`,
+	 * fall through to `onUnhandled` with the original raw bytes.
+	 *
+	 * The adapter's `websocket.maxPayloadLength` already bounds the bytes
+	 * `JSON.parse` ever sees, so there's no separate size cap here.
+	 *
+	 * @example
+	 * ```js
+	 * createMessage({
+	 *   onJsonMessage(ws, msg, platform) {
+	 *     if (msg.type === 'cursor') cursor.hooks.message(ws, { data: msg, platform });
+	 *     else if (msg.type === 'presence-snapshot') presence.hooks.message(ws, { data: msg, platform });
+	 *   }
+	 * })
+	 * ```
+	 */
+	onJsonMessage?(ws: WebSocket<any>, msg: any, platform: Platform): void;
+
+	/**
+	 * Maximum nesting depth allowed in a parsed `onJsonMessage` envelope.
+	 * Frames deeper than this fall through to `onUnhandled` unparsed.
+	 * Mirrors `handleRpc`'s `maxEnvelopeDepth` semantics; same default.
+	 *
+	 * @default 64
+	 */
+	maxJsonDepth?: number;
+
+	/**
+	 * Called when a message is not an RPC request and either no
+	 * `onJsonMessage` is set, or the frame is binary / non-JSON / parses
+	 * to a non-object / exceeds `maxJsonDepth`.
 	 * Use for mixing RPC with custom message handling.
 	 */
 	onUnhandled?(ws: WebSocket<any>, data: ArrayBuffer, platform: Platform): void;
@@ -958,6 +1068,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),