svelte-realtime 0.5.8 → 0.6.0-next.1

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

@@ -2339,6 +2339,49 @@ Without a leader configured (the default), every worker fires every job. svelte-
 
 ---
 
+## Feature flags
+
+Use `live.flag()` to declare a server-controlled value that every client reads as a readable store. A flag is a thin wrapper over `live.stream`: it declares a `merge: 'set'` topic carrying the value, and `.set(value)` pushes a new value to every subscriber.
+
+```js
+// src/live/flags.js
+import { live } from 'svelte-realtime/server';
+
+export const maintenance = live.flag('flag:maintenance', false);
+```
+
+Flip it from any handler - the `.set(value)` call publishes through the framework-owned platform, so the new value reaches every local subscriber and relays across the cluster when a bus is wired:
+
+```js
+export const toggleMaintenance = live(async (ctx, on) => {
+  maintenance.set(on);
+});
+```
+
+On the client, the flag is a readable store carrying the current value:
+
+```svelte
+<script>
+  import { maintenance } from '$live/flags';
+</script>
+
+{#if $maintenance}
+  <Banner>Down for maintenance</Banner>
+{/if}
+```
+
+`.set(value)` requires that the platform has been captured (`realtime().init`, `setCronPlatform`, or `_activateDerived` from your `hooks.ws.js` `init({ platform })` hook) - the same wiring cron and the top-level `publish()` helper need. Read the current value on the server with `.get()`.
+
+Flags are cluster-consistent by default. A single-entry shared replay buffer is enabled automatically, so a `.set()` on any replica writes the cluster-shared buffer, and a client that connects fresh - to any replica, including one that never set the flag locally - is served the cluster-latest value on connect. Already-subscribed clients stay in sync wherever they connected, because `.set()` relays the update across the cluster. Pass a custom `replay` object (for example `{ replay: { size: 5 } }`) to size the buffer, or `{ replay: false }` to opt out - a single-process app loses nothing by opting out, since the locally cached value is authoritative in one process.
+
+On every running replica an internal watcher keeps the cached value behind `.get()` fresh from boot. The watcher is installed when the registry module loads - the same moment `live.effect` watchers become active - so it does not wait for the flag module's first local import or subscribe: an inbound `set` relayed from any replica updates the cached value within a tick, and synchronous `.get()` reflects the cluster-latest value on any running instance. For a strict read on a replica that booted after the last `set` and has not yet received any inbound `set` - reading a flag the moment a replica comes up, before it has observed any traffic - use the asynchronous `getLatest()`, which reads the shared buffer directly:
+
+```js
+const on = await maintenance.getLatest();
+```
+
+---
+
 ## Derived streams
 
 Server-side computed streams that recompute when any source topic publishes.
@@ -3048,7 +3091,7 @@ With adapter 0.4.0+, the replay end marker sends `{ reqId }` (replay complete) o
 
 Once `platform.replay` is exposed (the standard install pattern is `platform.replay = createReplay(redisClient)` in your hooks), the framework auto-routes every publish to a replay-eligible topic through `platform.replay.publish` regardless of which seam the publisher sits on. `live.stream(topic, loader, { replay: true })` registers the topic at declaration time; static topics are registered up-front and dynamic topics are registered at first-subscribe time when they resolve.
 
-This applies to every framework publish surface — `ctx.publish` from RPC handlers, cron auto-publish (`live.cron('* * * * * *', topic, async (ctx) => result)` where `result !== undefined`), and `ctx.publish` from inside cron handlers — without the user wiring anything beyond `replay: true`. Pre-fix, the user was responsible for wrapping the platform with a `wrapWithReplay` proxy at every seam (the docs showed it on `createMessage` only; cron was a separate `setCronPlatform(platform)` capture, and cron-published events silently bypassed the buffer because the wrap was missing there). The auto-routing makes that asymmetry impossible by construction.
+This applies to every framework publish surface - `ctx.publish` from RPC handlers, cron auto-publish (`live.cron('* * * * * *', topic, async (ctx) => result)` where `result !== undefined`), and `ctx.publish` from inside cron handlers - without the user wiring anything beyond `replay: true`. Pre-fix, the user was responsible for wrapping the platform with a `wrapWithReplay` proxy at every seam (the docs showed it on `createMessage` only; cron was a separate `setCronPlatform(platform)` capture, and cron-published events silently bypassed the buffer because the wrap was missing there). The auto-routing makes that asymmetry impossible by construction.
 
 If you need to keep your own platform-wrapping proxy (custom topic patterns, additional intercepts), set `[WRAPPED_FOR_REPLAY] = true` on the proxy:
 
@@ -3062,7 +3105,7 @@ function wrapWithReplay(p) {
 }
 ```
 
-The framework defers entirely when this marker is present (no double-write to Redis). Without the marker, the framework's auto-routing runs alongside the user proxy's routing and will issue duplicate Redis writes — explicit opt-out is required.
+The framework defers entirely when this marker is present (no double-write to Redis). Without the marker, the framework's auto-routing runs alongside the user proxy's routing and will issue duplicate Redis writes - explicit opt-out is required.
 
 If `replay: true` is declared but `platform.replay` is never set, dev-mode logs a one-time `console.warn` per topic on the first publish, with the install pointer for the replay extension. Production runs silently (no per-publish overhead) and the local broadcast still happens.
 
@@ -3401,6 +3444,8 @@ live.publishRateWarning(false);
 
 Production builds constant-fold the activation branch to dead code - zero overhead. The sampler runs once per platform on the first ctx-helpers cache miss; per-publish cost is unchanged. Topics already in `_topicCoalesce` or `_topicVolatile` are skipped (the user has already addressed them).
 
+The client emits the same hint from the receiving side: in development it measures each stream's inbound frame rate and logs one warning per topic when it crosses the threshold, suggesting `coalesceBy` / `volatile` and linking the same guide. Streams declared with `coalesceBy` are suppressed; silence it everywhere with `configure({ publishRateHint: false })`. Production builds strip the client hint entirely (`import.meta.env`-gated), leaving zero residue on the inbound dispatch path.
+
 ### Dev-mode silent-topic warning
 
 In development, the framework arms a one-shot timer when a stream first subscribes to a topic. If no events arrive within `thresholdMs` (default `30000`), it logs a warning naming the topic and the common causes:
@@ -3677,6 +3722,7 @@ Import from `svelte-realtime/server`.
 | `live.upload(fn, options?)` | Streaming upload handler (chunked, abortable async-iterable; `maxSize` 100MB, `maxConcurrentPerSession` 4, `maxBufferedChunks` 64) |
 | `live.validated(schema, fn)` | RPC with [Standard Schema](https://standardschema.dev/) input validation (Zod, ArkType, Valibot, etc.) |
 | `live.cron(schedule, topic, fn)` | Server-side scheduled function |
+| `live.flag(topic, initialValue?, options?)` | Feature flag exposed as a readable stream with a server-side `.set(value)` |
 | `live.derived(sources, fn, options?)` | Server-side computed stream (static or dynamic sources) |
 | `live.effect(sources, fn, options?)` | Server-side reactive side effect |
 | `live.aggregate(source, reducers, options)` | Real-time incremental aggregation |

package/client.d.ts

@@ -583,6 +583,15 @@ export function configure(config: {
 	 * @default 4_194_304 (4 MB)
 	 */
 	volatileBackpressureBytes?: number;
+	/**
+	 * Enable the dev-mode publish-rate hint: a one-shot console warning logged
+	 * when an inbound stream's frame rate crosses the high-frequency threshold,
+	 * suggesting `coalesceBy` / `volatile`. Set `false` to silence it.
+	 * Production builds strip the hint entirely, so this flag only has an effect
+	 * in development.
+	 * @default true
+	 */
+	publishRateHint?: boolean;
 	/** Offline mutation queue configuration. */
 	offline?: {
 		/** Enable queuing RPCs when disconnected. */

package/client.js

@@ -121,6 +121,32 @@ const _dedupMap = new Map();
  */
 const _dedupCoalesceWarned = new Set();
 
+// - Dev-mode publish-rate hint (client half) -------------------------------
+// Mirrors the server-side sampler in `svelte-realtime/server.js`, but the
+// signal source differs. The server reads `platform.pressure.topPublishers`
+// (rates the adapter already computes); the client has no such snapshot, so
+// it measures inbound frame rate directly at the dispatch hook. A per-topic
+// fixed window counts frames; when a window closes over threshold, one warn
+// fires per topic per session with the SAME wording, threshold (200), and
+// `svti.me/highfreq` link as the server. The whole feature is gated by the
+// `import.meta.env`-folded `_IS_DEV` const so a production build strips it to
+// dead code, leaving zero residue on the inbound dispatch hot path.
+
+/** Inbound events/sec at which a topic is considered high-frequency. Matches the server sampler default. */
+const _PUBLISH_RATE_HINT_THRESHOLD = 200;
+
+/** Measurement window for the client frame-rate counter, in ms. Rate = frames-in-window / window-seconds. */
+const _PUBLISH_RATE_HINT_WINDOW_MS = 1000;
+
+/** Max distinct topics tracked in the warned dedup set. FIFO-evict on cap: dropping the oldest entry just lets that topic re-warn on its next over-threshold window. Mirrors the server `PUBLISH_RATE_WARN_DEDUP_MAX` eviction shape. */
+const _PUBLISH_RATE_HINT_DEDUP_MAX = 1_000_000;
+
+/** @type {Map<string, { start: number, count: number }>} Per-topic fixed-window frame counter. */
+const _publishRateWindows = new Map();
+
+/** @type {Set<string>} One-shot warned topics. FIFO-evicted at the dedup cap. */
+const _publishRateHintWarned = new Set();
+
 /**
  * Dev-mode check, mirrored from the `process.env.NODE_ENV` pattern
  * used elsewhere in this file. Cached once at first call so the hot
@@ -494,6 +520,85 @@ function _warnCoalesceOnce(path) {
 	);
 }
 
+/**
+ * Count one inbound frame for a topic and, if its measured rate crosses the
+ * high-frequency threshold, emit a one-shot dev hint. Counterpart to the
+ * server-side sampler: same threshold (200), same `coalesceBy` / `volatile`
+ * suggestions, same `svti.me/highfreq` link. The server reads rates the
+ * adapter pre-computes; the client has none, so it counts frames over a fixed
+ * window and derives the rate locally.
+ *
+ * Suppressed when the stream was declared with `coalesceBy` - that is the user
+ * already choosing the latest-value-wins mitigation, so the hint would be
+ * noise. (There is no client-side `volatile` declaration to read; `volatile`
+ * is a per-call RPC concern, not a stream option, so only `coalesceBy`
+ * suppresses here.) Opt out entirely with `configure({ publishRateHint: false })`.
+ *
+ * The whole function is dead code in production: the only caller is gated by
+ * the `import.meta.env`-folded `_IS_DEV` const, and this body re-checks it so a
+ * direct call from a test still no-ops under a production build.
+ *
+ * @param {string} topic - the stream path (the identity available at dispatch)
+ * @param {any} options - the per-stream options object (read for `coalesceBy`)
+ */
+function _maybeHintPublishRate(topic, options) {
+	if (!_IS_DEV) return;
+	if (_clientConfig.publishRateHint === false) return;
+	if (_publishRateHintWarned.has(topic)) return;
+	// A declared-coalesced stream already picked latest-value-wins, so the hint
+	// would be noise: skip the counting work entirely, mirroring the server which
+	// marks such topics handled up front.
+	if (options && options.coalesceBy) return;
+
+	const now = Date.now();
+	let win = _publishRateWindows.get(topic);
+	if (win === undefined) {
+		_publishRateWindows.set(topic, { start: now, count: 1 });
+		return;
+	}
+	win.count++;
+	const elapsed = now - win.start;
+	if (elapsed < _PUBLISH_RATE_HINT_WINDOW_MS) return;
+
+	// Window closed: derive events/sec and reset for the next window. A short
+	// final window (e.g. the stream unsubscribed mid-window) still scales to a
+	// per-second rate, so a genuine burst is not under-counted.
+	const rate = (win.count * 1000) / elapsed;
+	win.start = now;
+	win.count = 0;
+
+	if (rate < _PUBLISH_RATE_HINT_THRESHOLD) return;
+
+	if (_publishRateHintWarned.size >= _PUBLISH_RATE_HINT_DEDUP_MAX) {
+		const oldest = _publishRateHintWarned.values().next().value;
+		if (oldest !== undefined) _publishRateHintWarned.delete(oldest);
+	}
+	_publishRateHintWarned.add(topic);
+	// The window counter is never re-read once a topic has warned (the warned
+	// set short-circuits at the top), so drop it to keep the window map bounded
+	// by live unwarned topics, mirroring the server sampler's symmetry.
+	_publishRateWindows.delete(topic);
+	console.warn(
+		`[svelte-realtime] Topic '${topic}' is receiving ` +
+		`${Math.round(rate)} events/sec.\n` +
+		`  For high-frequency streams, consider one of:\n` +
+		`    live.stream(topic, loader, { coalesceBy: (data) => data.userId })  // latest-value-wins, queued per subscriber\n` +
+		`    live.stream(topic, loader, { volatile: true })                     // drop on backpressure, best-effort\n` +
+		`  See: https://svti.me/highfreq`
+	);
+}
+
+/**
+ * Reset the dev-mode client publish-rate hint state. Tests only. Clears the
+ * one-shot warned set and the per-topic window counters so a previously seen
+ * topic can warn again.
+ * @internal
+ */
+export function _resetClientPublishRateWarning() {
+	_publishRateHintWarned.clear();
+	_publishRateWindows.clear();
+}
+
 /**
  * Build a dedup key from path and args, avoiding JSON.stringify for common cases.
  * @param {string} path
@@ -2424,6 +2529,7 @@ function _createStream(path, options, dynamicArgs, initialSchemaVersion) {
 		}
 
 		_devtoolsStreamEvent(path, envelope.event, envelope.data);
+		if (_IS_DEV) _maybeHintPublishRate(path, options);
 
 		if (_useRAF) {
 			_activeBuf.push(envelope);
@@ -3530,7 +3636,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, 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 } }} */
+/** @type {{ url?: string, auth?: boolean | string, onConnect?: () => void, onDisconnect?: () => void, timeout?: number, resumeGraceMs?: number, volatileBackpressureBytes?: number, publishRateHint?: boolean, 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} */
@@ -3561,7 +3667,12 @@ let _replayingQueue = false;
  * 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
+ * `publishRateHint` (default enabled in dev) controls the one-shot console
+ * hint logged when an inbound stream's frame rate crosses the high-frequency
+ * threshold. Set `false` to silence it. Production builds strip the hint
+ * regardless, so this only matters in development.
+ *
+ * @param {{ url?: string, auth?: boolean | string, onConnect?: () => void, onDisconnect?: () => void, timeout?: number, resumeGraceMs?: number, volatileBackpressureBytes?: number, publishRateHint?: boolean, offline?: { queue?: boolean, maxQueue?: number, maxAge?: number, replay?: 'sequential' | 'batch' | ((queue: OfflineEntry[]) => OfflineEntry[]), beforeReplay?: (call: { path: string, args: any[], queuedAt: number }) => boolean, onReplayError?: (call: { path: string, args: any[], queuedAt: number }, error: any) => void } }} config
  */
 export function configure(config) {
 	_clientConfig = config;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "svelte-realtime",
-  "version": "0.5.8",
+  "version": "0.6.0-next.1",
   "publishConfig": {
-    "tag": "latest"
+    "tag": "next"
   },
   "description": "Realtime RPC and reactive subscriptions for SvelteKit, built on svelte-adapter-uws",
   "author": "Kevin Radziszewski",
@@ -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;
@@ -1549,6 +1659,57 @@ export namespace live {
 		fn: T
 	): T;
 
+	/**
+	 * Declare a server-side feature flag exposed as a readable stream.
+	 *
+	 * A flag is a thin wrapper over `live.stream`: it declares a
+	 * `merge: 'set'` topic carrying the flag value, and any `.set(value)`
+	 * pushes the new value to every subscriber. On the client,
+	 * `$live/<module>` exposes the export as a readable store carrying the
+	 * current value.
+	 *
+	 * Flags are cluster-consistent by default: a single-entry shared replay
+	 * buffer is enabled, so `.set()` writes the cluster-shared buffer and a
+	 * subscriber that connects fresh - to any replica, including one that
+	 * never set the flag locally - is served the cluster-latest value.
+	 * Already-subscribed clients stay in sync across the cluster as `.set()`
+	 * relays the update. Pass a custom `replay` object to size the buffer, or
+	 * `replay: false` to opt out (single-process apps lose nothing, since the
+	 * locally cached value is authoritative in one process).
+	 *
+	 * `.set(value)` publishes through the framework-owned platform (the same
+	 * path as the top-level `publish()` helper), so the new value reaches
+	 * every local subscriber and relays across the cluster when a bus is
+	 * wired. Call it from any server context after the platform has been
+	 * captured. `.get()` reads the current value on the server synchronously;
+	 * an internal watcher - installed when the registry module loads, the same
+	 * lifecycle that activates `live.effect` watchers - keeps it fresh from boot
+	 * within a tick of any inbound `set` on a running replica, without waiting
+	 * for the flag module's first local import. `getLatest()` reads the
+	 * cluster-latest value asynchronously from the shared buffer for the strict
+	 * read on a replica that booted after the last `set` and has not yet
+	 * received any inbound `set`.
+	 *
+	 * @param topic - Topic carrying the flag value
+	 * @param initialValue - Value served to subscribers before the first `.set`
+	 * @param options - Optional `replay` to size the shared buffer, or `replay: false` to opt out
+	 *
+	 * @example
+	 * ```js
+	 * // src/live/flags.js
+	 * export const maintenance = live.flag('flag:maintenance', false);
+	 *
+	 * export const toggleMaintenance = live(async (ctx, on) => {
+	 *   maintenance.set(on);
+	 * });
+	 * ```
+	 */
+	function flag<V = any>(
+		topic: string,
+		initialValue?: V,
+		options?: { replay?: boolean | { size?: number } }
+	): Function & { set(value: V): any; get(): V; getLatest(): Promise<V> };
+
 	/**
 	 * Create a real-time incremental aggregation over a source topic.
 	 *
@@ -2385,6 +2546,15 @@ export function __registerEffect(path: string, fn: Function): void;
  */
 export function __registerAggregate(path: string, fn: Function): void;
 
+/**
+ * Install a flag's refresh watcher eagerly at registry-module load, keyed by
+ * topic, so a server-side `.get()` reflects cluster-latest sets from boot
+ * without waiting for the flag module's first local import. Called by the
+ * Vite-generated registry module.
+ * @internal
+ */
+export function __registerFlag(topic: string, initialValue?: any): void;
+
 /**
  * Register room actions lazily. Called by the Vite-generated registry module.
  * @internal