svelte-realtime 0.5.8 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-realtime",
-  "version": "0.5.8",
+  "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.2"
+    "svelte-adapter-uws": "^0.5.3"
   },
   "devDependencies": {
     "@playwright/test": "^1.59.1",
     "fast-check": "^4.7.0",
-    "svelte-adapter-uws-extensions": "^0.5.2",
+    "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;

package/server.js

@@ -823,12 +823,22 @@ function _applyInitTransform(transform, data) {
 	return transform(data);
 }
 
-/** @type {WeakMap<any, { publish: Function, throttle: Function, debounce: Function, signal: Function, batch: Function, shed: Function }>} */
+/** @type {WeakMap<any, { publish: Function, publishThrottled: Function, publishDebounced: Function, throttle: Function, debounce: Function, signal: Function, batch: Function, shed: Function, skip: Function }>} */
 const _ctxHelpersCache = new WeakMap();
 
 /** @type {boolean} */
 const _IS_DEV = typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production';
 
+/** Dev-warn dedup: one-time "ctx.throttle is deprecated" warning. */
+let _throttleDeprecatedWarned = false;
+/** Dev-warn dedup: one-time "ctx.debounce is deprecated" warning. */
+let _debounceDeprecatedWarned = false;
+/** Dev-warn dedup: per-helper bad-args warning. Keys: 'publishThrottled', 'publishDebounced', 'throttle', 'debounce'. */
+/** @type {Record<string, boolean>} */
+const _publishHelperBadArgsWarned = Object.create(null);
+/** Dev-warn dedup: one-time "ctx.skip gate map at capacity" warning. */
+let _skipGateCapWarned = false;
+
 /**
  * Topics declared with `live.stream(..., { replay: true })`. Populated at
  * declaration time for static topics and at first-subscribe time for
@@ -1254,15 +1264,50 @@ function _getCtxHelpers(platform) {
 		};
 		helpers = {
 			publish,
-			throttle: (topic, event, data, ms) => _throttlePublish(platform, topic, event, data, ms),
-			debounce: (topic, event, data, ms) => _debouncePublish(platform, topic, event, data, ms),
+			publishThrottled: (...args) => {
+				_checkPublishHelperArgs('publishThrottled', args);
+				return _throttlePublish(platform, /** @type {string} */ (args[0]), /** @type {string} */ (args[1]), args[2], /** @type {number} */ (args[3]));
+			},
+			publishDebounced: (...args) => {
+				_checkPublishHelperArgs('publishDebounced', args);
+				return _debouncePublish(platform, /** @type {string} */ (args[0]), /** @type {string} */ (args[1]), args[2], /** @type {number} */ (args[3]));
+			},
+			throttle: (...args) => {
+				if (_IS_DEV && !_throttleDeprecatedWarned) {
+					_throttleDeprecatedWarned = true;
+					console.warn(
+						'[svelte-realtime] ctx.throttle is deprecated -- rename to ctx.publishThrottled. ' +
+						'The old name reads like a handler gate, but it is a 4-arg publish helper. ' +
+						'For per-key handler gating use ctx.skip(key, ms); the publish-helper behaviour ' +
+						'is unchanged. This warning fires once per process.\n' +
+						'  See: https://svti.me/publish-throttled'
+					);
+				}
+				_checkPublishHelperArgs('throttle', args);
+				return _throttlePublish(platform, /** @type {string} */ (args[0]), /** @type {string} */ (args[1]), args[2], /** @type {number} */ (args[3]));
+			},
+			debounce: (...args) => {
+				if (_IS_DEV && !_debounceDeprecatedWarned) {
+					_debounceDeprecatedWarned = true;
+					console.warn(
+						'[svelte-realtime] ctx.debounce is deprecated -- rename to ctx.publishDebounced. ' +
+						'The old name reads like a handler gate, but it is a 4-arg publish helper. ' +
+						'For per-key handler gating use ctx.skip(key, ms); the publish-helper behaviour ' +
+						'is unchanged. This warning fires once per process.\n' +
+						'  See: https://svti.me/publish-debounced'
+					);
+				}
+				_checkPublishHelperArgs('debounce', args);
+				return _debouncePublish(platform, /** @type {string} */ (args[0]), /** @type {string} */ (args[1]), args[2], /** @type {number} */ (args[3]));
+			},
 			signal: (userId, event, data) => {
 				const reason = _validUserIdReason(userId);
 				if (reason !== null) throw new LiveError('INVALID_USER_ID', 'ctx.signal: ' + reason);
 				return platform.publish('__signal:' + userId, event, data);
 			},
 			batch: (messages) => platform.batch ? platform.batch(messages) : messages.forEach((m) => publish(m.topic, m.event, m.data, m.options)),
-			shed: (className) => _shouldShed(platform, className)
+			shed: (className) => _shouldShed(platform, className),
+			skip: (key, ms) => _skipGate(key, ms)
 		};
 		_ctxHelpersCache.set(platform, helpers);
 	}
@@ -1400,7 +1445,7 @@ function _rollbackStreamSubscribe(ws, topic, fn, ctx) {
  * @param {any} user
  * @param {any} ws
  * @param {import('svelte-adapter-uws').Platform} platform
- * @param {{ publish: Function, throttle: Function, debounce: Function, signal: Function, batch: Function, shed: Function }} helpers
+ * @param {{ publish: Function, publishThrottled: Function, publishDebounced: Function, throttle: Function, debounce: Function, signal: Function, batch: Function, shed: Function, skip: Function }} helpers
  * @param {any} cursor
  * @param {string | null} [idempotencyKey] Envelope-supplied idempotency key, or null. Internal use only.
  * @returns {any}
@@ -1412,11 +1457,14 @@ function _buildCtx(user, ws, platform, helpers, cursor, idempotencyKey) {
 		platform,
 		publish: helpers.publish,
 		cursor,
+		publishThrottled: helpers.publishThrottled,
+		publishDebounced: helpers.publishDebounced,
 		throttle: helpers.throttle,
 		debounce: helpers.debounce,
 		signal: helpers.signal,
 		batch: helpers.batch,
 		shed: helpers.shed,
+		skip: helpers.skip,
 		requestId: platform.requestId,
 		_idempotencyKey: idempotencyKey || null
 	};
@@ -3045,15 +3093,23 @@ export const pushHooks = {
  * Send a server-initiated request to a connected user and await the reply.
  *
  * Lookup order:
- * 1. **Local registry** - the per-userId Map populated by `pushHooks.open` /
- *    `pushHooks.close`. Resolves directly via `platform.request(ws, ...)` --
- *    no I/O.
- * 2. **Remote registry** - the optional `remoteRegistry` configured via
- *    `live.configurePush({ remoteRegistry })`. When the userId is not
- *    registered on this instance and a registry is configured,
- *    `live.push` falls through to `remoteRegistry.request(userId, ...)`
- *    so a request from any instance reaches the user's owning instance
- *    over the registry's transport.
+ * 1. **Remote registry (when configured)** - the optional `remoteRegistry`
+ *    set via `live.configurePush({ remoteRegistry })` is the cluster-wide
+ *    source of truth for "which instance currently owns this userId" (most-
+ *    recently-opened wins via the registry's last-write-wins userToInstance
+ *    map). `live.push` delegates to `remoteRegistry.request(userId, ...)`
+ *    so the recipient is deterministic regardless of which instance the
+ *    caller runs on. The registry's own self-targeting short-circuit
+ *    (`registry.js: ownerInstanceId === instanceId`) means no extra Redis
+ *    hop when the canonical owner IS this instance -- single-tab
+ *    performance is unchanged.
+ * 2. **Local registry (fallback)** - the per-userId Map populated by
+ *    `pushHooks.open` / `pushHooks.close`. When no `remoteRegistry` is
+ *    configured (single-instance dev), this is the only path. When a
+ *    `remoteRegistry` IS configured, the local entry is used only as a
+ *    best-effort fallback on the brief race window where `pushHooks.open`
+ *    has populated the local map but the cluster pub/sub event has not
+ *    yet propagated to this instance's index.
  *
  * Returns whatever the client's `onPush(event, handler)` returns.
  *
@@ -3141,20 +3197,38 @@ live.push = async function push(target, event, data, options) {
 		throw new LiveError('VALIDATION', '[svelte-realtime] live.push: target.userId must be a non-empty string');
 	}
 
-	const entry = _pushRegistry.get(userId);
-	if (entry) {
-		if (typeof entry.platform.request !== 'function') {
-			throw new Error('[svelte-realtime] live.push: platform.request is not available; requires svelte-adapter-uws >= 0.5.0-next.4');
-		}
+	// Cluster-first when a remoteRegistry is configured: the registry's
+	// userToInstance map is the cluster-wide canonical-owner truth (most-
+	// recent open wins per its last-write-wins applyOpenEvent). The
+	// registry's own self-targeting short-circuit means no extra Redis
+	// hop when the canonical owner is THIS instance -- single-tab perf
+	// is unchanged. Multi-tab same-user across instances now routes
+	// deterministically to the cluster-canonical recipient regardless of
+	// which instance the caller runs on, matching the documented
+	// "cluster-wide most-recent-wins" contract above.
+	//
+	// On a brief registry-offline race (fresh local open whose cluster
+	// pub/sub event has not yet propagated to this instance's index),
+	// fall back to the local entry so the just-opened user does not see
+	// a NOT_FOUND for their own push.
+	const localEntry = _pushRegistry.get(userId);
+	if (_remoteRegistry) {
 		try {
-			return await entry.platform.request(entry.ws, event, data, options || undefined);
+			return await _remoteRegistry.request(userId, event, data, options || undefined);
 		} catch (err) {
-			throw _translatePushError(err);
+			if (localEntry && _isRegistryOfflineError(err)) {
+				// fall through to local fast path below
+			} else {
+				throw _translatePushError(err);
+			}
 		}
 	}
-	if (_remoteRegistry) {
+	if (localEntry) {
+		if (typeof localEntry.platform.request !== 'function') {
+			throw new Error('[svelte-realtime] live.push: platform.request is not available; requires svelte-adapter-uws >= 0.5.0-next.4');
+		}
 		try {
-			return await _remoteRegistry.request(userId, event, data, options || undefined);
+			return await localEntry.platform.request(localEntry.ws, event, data, options || undefined);
 		} catch (err) {
 			throw _translatePushError(err);
 		}
@@ -3195,6 +3269,31 @@ function _translatePushError(err) {
 	return err;
 }
 
+/**
+ * Detect the "cluster has no entry for this userId" rejection from a
+ * configured remoteRegistry. Used by live.push / live.notify to decide
+ * whether to fall back to a (potentially fresher) local registry entry
+ * during the brief propagation race after `pushHooks.open` writes to
+ * Redis + publishes the event but the subscriber index hasn't yet
+ * applied it on the current instance.
+ *
+ * Conservatively substring-matches "offline" -- the extensions
+ * registry's exact wording is `registry.request: target user "..." is
+ * offline`, and the project's existing test fixtures throw bare
+ * `Error('offline')`. Other cluster errors (recipient handler throw,
+ * timeout) are real signals and NOT eligible for local fallback so
+ * caller-defined error shapes propagate intact.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+function _isRegistryOfflineError(err) {
+	const msg = err && typeof (/** @type {any} */ (err).message) === 'string'
+		? /** @type {any} */ (err).message
+		: '';
+	return /offline/i.test(msg);
+}
+
 /**
  * Bounded internal timeout for the wire-level request that backs
  * `live.notify`. The caller doesn't await the reply - this only
@@ -3276,8 +3375,46 @@ live.notify = function notify(target, event, data) {
 		throw new LiveError('VALIDATION', '[svelte-realtime] live.notify: target.userId must be a non-empty string');
 	}
 
-	const entry = _pushRegistry.get(userId);
-	if (entry) {
+	// Cluster-first when a remoteRegistry is configured -- same rationale
+	// as live.push above: the cluster registry's canonical-owner truth
+	// routes deterministically to the most-recently-opened ws regardless
+	// of caller instance. Self-target short-circuit keeps single-tab perf
+	// unchanged. Multi-tab same-user across instances correctly reaches
+	// the cluster-canonical recipient instead of the caller-local one.
+	//
+	// Fire-and-forget contract is preserved: any delivery failure
+	// (offline, timeout, client handler throw, remote registry error)
+	// is silent. The local fallback on registry-offline is a UX-only
+	// optimization for the brief propagation race after a fresh open.
+	const localEntry = _pushRegistry.get(userId);
+	if (_remoteRegistry) {
+		try {
+			const p = _remoteRegistry.request(userId, event, data, { timeoutMs: _NOTIFY_INTERNAL_TIMEOUT_MS });
+			if (localEntry) {
+				// Brief registry-offline race after a fresh local open:
+				// the cluster pub/sub event has not yet propagated, the
+				// cluster rejects with "is offline", but the local
+				// registry already has a valid entry. Fall back so the
+				// user does not silently drop their own first notify.
+				p.catch((err) => {
+					if (_isRegistryOfflineError(err)) _deliverLocalNotify(localEntry);
+				});
+			} else {
+				p.catch(() => { /* silent: fire-and-forget contract */ });
+			}
+		} catch {
+			// Sync throw from registry shape; try local as best-effort.
+			if (localEntry) _deliverLocalNotify(localEntry);
+		}
+		return Promise.resolve();
+	}
+	if (localEntry) _deliverLocalNotify(localEntry);
+	// Offline + no cluster routing: silent no-op. The caller chose
+	// notify; "we couldn't reach the user" isn't an error in this
+	// contract - they'll see the result next time they load.
+	return Promise.resolve();
+
+	function _deliverLocalNotify(entry) {
 		if (typeof entry.platform.request !== 'function') {
 			// Same versioning constraint as live.push - platform.request
 			// requires svelte-adapter-uws >= 0.5.0-next.4. Stay silent in
@@ -3286,7 +3423,7 @@ live.notify = function notify(target, event, data) {
 			if (_IS_DEV) {
 				console.warn('[svelte-realtime] live.notify: platform.request is not available; requires svelte-adapter-uws >= 0.5.0-next.4. Notify dispatch silently no-op.\n  See: https://svti.me/migration');
 			}
-			return Promise.resolve();
+			return;
 		}
 		try {
 			entry.platform.request(entry.ws, event, data, { timeoutMs: _NOTIFY_INTERNAL_TIMEOUT_MS })
@@ -3299,24 +3436,7 @@ live.notify = function notify(target, event, data) {
 			// platform.request can throw synchronously on a torn-down ws.
 			// Same fire-and-forget contract: silent.
 		}
-		return Promise.resolve();
 	}
-	if (_remoteRegistry) {
-		try {
-			_remoteRegistry.request(userId, event, data, { timeoutMs: _NOTIFY_INTERNAL_TIMEOUT_MS })
-				.catch(() => {
-					// Cluster-route error (offline cluster-wide, transport
-					// failure, remote handler throw) - silent.
-				});
-		} catch {
-			// Sync throw from registry shape - silent.
-		}
-		return Promise.resolve();
-	}
-	// Offline + no cluster routing: silent no-op. The caller chose
-	// notify; "we couldn't reach the user" isn't an error in this
-	// contract - they'll see the result next time they load.
-	return Promise.resolve();
 };
 
 /**
@@ -7942,6 +8062,111 @@ function _debouncePublish(platform, topic, event, data, ms) {
 	}, ms));
 }
 
+/**
+ * Per-key gate state. Each entry is a setTimeout handle that self-deletes
+ * the key when its cooldown window elapses. Shape mirrors `_throttles` /
+ * `_debounces` so memory accounting and cap semantics are uniform.
+ *
+ * @type {Map<string, ReturnType<typeof setTimeout>>}
+ */
+const _skipGates = new Map();
+
+/**
+ * Per-key rate gate. Returns `true` to skip the call (key is within its
+ * cooldown window), `false` to run it (no entry, or window elapsed). The
+ * caller pairs this with an early `return` inside an RPC handler:
+ *
+ *     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 });
+ *     });
+ *
+ * Pairs with `ctx.shed` semantically (both return `true` to early-return),
+ * so call sites read uniformly. Different from `ctx.publishThrottled` /
+ * `ctx.publishDebounced` which schedule outbound publishes - `ctx.skip`
+ * gates the inbound handler body.
+ *
+ * **Memory:** capped at `_THROTTLE_DEBOUNCE_MAX` (5000) entries. When the
+ * cap is hit, the gate fails open (returns `false`, does NOT stamp a new
+ * entry) so a runaway dynamic-key generator (e.g. spraying unique keys to
+ * exhaust the map) cannot silently start blocking legitimate calls. The
+ * first cap-hit fires a one-shot dev warning so operators see the issue.
+ *
+ * **Cluster:** state is per-replica. Each replica that received an RPC
+ * call evaluates `ctx.skip` against its local map; the gate is a CPU/DB
+ * shed, not a cluster-wide ratelimit. For cross-replica gating use
+ * `live.rateLimit({ store: 'redis' })` or `redis/ratelimit`.
+ *
+ * @param {string} key
+ * @param {number} ms
+ * @returns {boolean} `true` to skip the call; `false` to run it
+ */
+function _skipGate(key, ms) {
+	if (typeof key !== 'string') {
+		throw new LiveError('INVALID_ARG', 'ctx.skip: key must be a string (got ' + (typeof key) + ')');
+	}
+	if (typeof ms !== 'number' || !(ms > 0) || !Number.isFinite(ms)) {
+		throw new LiveError('INVALID_ARG', 'ctx.skip: ms must be a positive finite number (got ' + String(ms) + ')');
+	}
+	if (_skipGates.has(key)) return true;
+	if (_skipGates.size >= _THROTTLE_DEBOUNCE_MAX) {
+		if (_IS_DEV && !_skipGateCapWarned) {
+			_skipGateCapWarned = true;
+			console.warn(
+				'[svelte-realtime] ctx.skip: gate map at capacity (' + _THROTTLE_DEBOUNCE_MAX + ' entries). ' +
+				'Falling open - calls are no longer being gated. Check for runaway dynamic-key generation ' +
+				'(e.g. unique-per-request keys).\n' +
+				'  See: https://svti.me/skip-gate'
+			);
+		}
+		return false;
+	}
+	_skipGates.set(key, setTimeout(() => { _skipGates.delete(key); }, ms));
+	return false;
+}
+
+/**
+ * Dev-only sanity check for `ctx.publishThrottled` / `ctx.publishDebounced`
+ * (and the deprecated `ctx.throttle` / `ctx.debounce` aliases). Logs a
+ * one-time warning per helper name when args don't match the publish-
+ * helper shape `(topic: string, event: string, data: any, ms: number > 0)`.
+ *
+ * The misuse pattern is calling `ctx.throttle('move:id', 50)` thinking it
+ * gates a handler - it doesn't, it's a 4-arg publish helper. The warning
+ * points at `ctx.skip(key, ms)` as the actual gate primitive.
+ *
+ * Production silently continues (no throw) so existing buggy deployments
+ * don't crash on adapter upgrade; the dev warning surfaces the issue at
+ * code-change time, not at runtime.
+ *
+ * @param {string} name - bare helper name (e.g. `'publishThrottled'`)
+ * @param {ReadonlyArray<unknown>} args - the call's argument list
+ */
+function _checkPublishHelperArgs(name, args) {
+	if (!_IS_DEV) return;
+	if (_publishHelperBadArgsWarned[name]) return;
+	const ok = args.length >= 4
+		&& typeof args[0] === 'string'
+		&& typeof args[1] === 'string'
+		&& typeof args[3] === 'number'
+		&& /** @type {number} */ (args[3]) > 0
+		&& Number.isFinite(/** @type {number} */ (args[3]));
+	if (ok) return;
+	_publishHelperBadArgsWarned[name] = true;
+	console.warn(
+		'[svelte-realtime] ctx.' + name + ' called with bad args -- expected ' +
+		'(topic: string, event: string, data: any, ms: number > 0). Got ' +
+		'argc=' + args.length + ', topic=' + (typeof args[0]) +
+		', event=' + (typeof args[1]) +
+		', ms=' + (typeof args[3] === 'number' ? String(args[3]) : typeof args[3]) + '. ' +
+		'ctx.' + name + ' is a publish helper, not a handler gate. ' +
+		'For per-key handler gating use ctx.skip(key, ms); for handler-wide rate ' +
+		'limiting use live.rateLimit().\n' +
+		'  See: https://svti.me/publish-helper-args'
+	);
+}
+
 /**
  * Send an RPC response to a single client.
  * @param {any} ws
@@ -8371,13 +8596,14 @@ export function message(ws, { data, platform }) {
 /**
  * Create a custom message hook with options baked in.
  *
- * @param {{ platform?: (p: import('svelte-adapter-uws').Platform) => import('svelte-adapter-uws').Platform, beforeExecute?: (ws: any, rpcPath: string, args: any[]) => Promise<void> | void, onError?: (path: string, error: unknown, ctx: any) => void, onUnhandled?: (ws: any, data: ArrayBuffer, platform: import('svelte-adapter-uws').Platform) => void }} [options]
- * @returns {(ws: any, ctx: { data: ArrayBuffer, platform: import('svelte-adapter-uws').Platform }) => void}
+ * @param {{ platform?: (p: import('svelte-adapter-uws').Platform) => import('svelte-adapter-uws').Platform, beforeExecute?: (ws: any, rpcPath: string, args: any[]) => Promise<void> | void, onError?: (path: string, error: unknown, ctx: any) => void, onJsonMessage?: (ws: any, msg: any, platform: import('svelte-adapter-uws').Platform) => void, maxJsonDepth?: number, onUnhandled?: (ws: any, data: ArrayBuffer, platform: import('svelte-adapter-uws').Platform) => void }} [options]
+ * @returns {(ws: any, ctx: { data: ArrayBuffer, msg?: any, platform: import('svelte-adapter-uws').Platform }) => void}
  */
 export function createMessage(options) {
 	if (!options) return message;
 
-	const { platform: transformPlatform, beforeExecute, onError, onUnhandled } = options;
+	const { platform: transformPlatform, beforeExecute, onError, onJsonMessage, onUnhandled } = options;
+	const maxJsonDepth = (options && /** @type {any} */ (options).maxJsonDepth) || _DEFAULT_MAX_ENVELOPE_DEPTH;
 
 	/** @type {any} */
 	const rpcOpts = {};
@@ -8385,7 +8611,13 @@ export function createMessage(options) {
 	if (onError) rpcOpts.onError = onError;
 	const hasRpcOpts = beforeExecute || onError;
 
-	return function customMessage(ws, { data, platform }) {
+	return function customMessage(ws, ctx) {
+		const { data, platform } = ctx;
+		// `msg` is forwarded by svelte-adapter-uws when it JSON-parsed the
+		// frame for control-message routing but no control type matched.
+		// Undefined on older adapter versions / binary / prefix-miss / parse-
+		// fail / non-object. See svelte-adapter-uws MessageContext docs.
+		const forwardedMsg = /** @type {any} */ (ctx).msg;
 		// 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
@@ -8420,7 +8652,52 @@ export function createMessage(options) {
 			p = platform;
 		}
 		const handled = handleRpc(ws, data, p, hasRpcOpts ? rpcOpts : undefined);
-		if (!handled && onUnhandled) {
+		if (handled) return;
+
+		// JSON-envelope dispatch. Plugin-layer frames (cursor `{type:'cursor',...}`,
+		// future presence-snapshot, typing indicators, etc.) reach a single
+		// callback with the parsed value, so user wiring doesn't re-parse on
+		// every frame.
+		//
+		// Two-tier lookup:
+		// 1) Fast path - if the adapter already parsed for control routing,
+		//    use the forwarded `msg` directly (one parse total).
+		// 2) Fallback - if the adapter didn't forward (older adapter version,
+		//    frame > 8 KiB, or first byte not `{"ty`), parse here.
+		//
+		// `exceedsEnvelopeDepth` mirrors `handleRpc`'s defense-in-depth against
+		// host walkers; deeper-than-cap envelopes fall through to `onUnhandled`
+		// with raw bytes so callers can log without crashing.
+		//
+		// The adapter's `maxPayloadLength` (default 1 MB) already bounds the
+		// bytes `JSON.parse` ever sees - no separate size cap needed here.
+		if (onJsonMessage) {
+			/** @type {any} */
+			let dispatchMsg;
+			if (forwardedMsg !== undefined && forwardedMsg !== null && typeof forwardedMsg === 'object') {
+				if (!exceedsEnvelopeDepth(forwardedMsg, maxJsonDepth)) {
+					dispatchMsg = forwardedMsg;
+				}
+				// Adapter forwarded an envelope but depth busted -> skip fallback
+				// (re-parsing the same bytes would produce the same too-deep object).
+			} else if (data instanceof ArrayBuffer && data.byteLength >= 2) {
+				const bytes = new Uint8Array(data);
+				if (bytes[0] === 0x7B /* '{' */) {
+					try {
+						const parsed = JSON.parse(textDecoder.decode(data));
+						if (parsed !== null && typeof parsed === 'object' && !exceedsEnvelopeDepth(parsed, maxJsonDepth)) {
+							dispatchMsg = parsed;
+						}
+					} catch { /* fall through to onUnhandled */ }
+				}
+			}
+			if (dispatchMsg !== undefined) {
+				onJsonMessage(ws, dispatchMsg, p);
+				return;
+			}
+		}
+
+		if (onUnhandled) {
 			onUnhandled(ws, data, p);
 		}
 	};