svelte-adapter-uws 0.5.2 → 0.5.4

package/README.md

@@ -699,12 +699,25 @@ export function open(ws, { platform }) {
   ws.subscribe(`user:${userId}`);
 }
 
-// Called when a message is received
+// Called when a message is received.
 // Note: subscribe/unsubscribe messages from the client store are
-// handled automatically BEFORE this function is called
-export function message(ws, { data, isBinary }) {
-  const msg = JSON.parse(Buffer.from(data).toString());
-  console.log('Got message:', msg);
+// handled automatically BEFORE this function is called.
+//
+// `msg` is the JSON-parsed envelope when the adapter parsed the frame
+// for control-message routing but no control type matched (i.e. it
+// looks like `{"type":"<custom>",...}` from a plugin). The adapter
+// already did `TextDecoder + JSON.parse` once during routing, so this
+// avoids a second parse on the dispatch path. `msg` is `undefined`
+// for binary frames, prefix-miss frames, parse failures, or frames
+// that parse to a non-object.
+export function message(ws, { data, isBinary, msg }) {
+  if (msg) {
+    // Already-parsed JSON object envelope - dispatch by msg.type
+    console.log('Got envelope:', msg);
+    return;
+  }
+  // Binary or non-envelope text frame - decode manually
+  console.log('Got raw frame, byteLength:', data.byteLength);
 }
 
 // Called when a client tries to subscribe to a topic (optional)
@@ -2364,8 +2377,8 @@ import { createPresence } from 'svelte-adapter-uws/plugins/presence';
 
 export const presence = createPresence({
   key: 'id',
-  select: (userData) => ({ id: userData.id, name: userData.name }),
-  heartbeat: 60_000  // optional: needed if clients use maxAge
+  select: (userData) => ({ id: userData.id, name: userData.name })
+  // heartbeat:      30_000 (default) - broadcast every 30s; clients refresh maxAge / re-add aged-out entries
   // maxConnections: 1_000_000 (default) - hard cap on tracked connections
   // maxTopics:      1_000_000 (default) - hard cap on active topic registry
 });
@@ -2437,8 +2450,8 @@ import { createPresence } from 'svelte-adapter-uws/plugins/presence';
 
 const presence = createPresence({
   key: 'id',             // field for multi-tab dedup (default: 'id')
-  select: (userData) => userData,  // extract public fields (default: full userData)
-  heartbeat: 60_000      // broadcast active keys every 60s (default: disabled)
+  select: (userData) => userData,  // extract public fields (default: recursive denylist)
+  heartbeat: 30_000      // broadcast every 30s (default: 30000; pass 0 to disable)
 });
 
 presence.hooks                       // ready-made { subscribe, unsubscribe, close } hooks
@@ -2453,14 +2466,15 @@ presence.clear()                     // reset everything (stops heartbeat timer)
 
 #### Wire format
 
-The plugin emits two frame types on the `__presence:{topic}` channel:
+The plugin emits three frame types on the `__presence:{topic}` channel:
 
 - `{event: 'presence_state', data: {[key]: meta}}` - full snapshot, sent to a single connection on join or sync.
 - `{event: 'presence_diff', data: {joins: {[key]: meta}, leaves: {[key]: meta}}}` - changes, broadcast to all subscribers of the topic.
+- `{event: 'heartbeat', data: {[key]: meta}}` - periodic full-roster refresh, broadcast every `heartbeat` ms (30 s default). Carries a `{userKey: data}` map so a client whose entry aged out of its local `maxAge` sweep can re-add it from the heartbeat alone, without waiting for the next `presence_diff`.
 
 Diffs are buffered in a microtask queue: multiple joins / leaves in the same tick collapse into one diff frame. Within a diff, `leaves` are applied first then `joins`, so an update (same key in both) ends with the user present using the new data. If a key cycles join then leave in the same tick, the diff carries only the latest op (`leave` wins).
 
-`heartbeat` events (when configured) are unchanged: they carry an array of currently-active keys.
+The Redis-backed variant in the [extensions](https://github.com/lanteanio/svelte-adapter-uws-extensions) package emits the same three frame shapes, so the same client bundle works against either backend.
 
 #### Client API
 
@@ -2471,20 +2485,24 @@ const users = presence('room');
 // $users = [{ id: '1', name: 'Alice' }, { id: '2', name: 'Bob' }]
 ```
 
-The `presence()` function accepts an optional second argument with a `maxAge` option (in milliseconds). When set, entries that haven't been refreshed within that window are automatically removed from the store. This makes clients self-healing when the server fails to broadcast a leaving entry in a `presence_diff` frame under load.
+The client store defaults to a 90 s `maxAge` sweep: entries that haven't been refreshed by a heartbeat or `presence_diff` / `presence_state` inside the window are removed from the local map. With the server's 30 s default heartbeat, still-present users are refreshed three times per window and never flicker; ghost entries left over by silent server-side cleanup (cluster mass-disconnect, ungraceful client close) clear within one sweep window.
+
+For admin / audit views that want unbounded retention ("show every user who ever touched this topic"), opt out with `maxAge: 0`:
 
-**Important:** `maxAge` requires the server-side `heartbeat` option. Without heartbeat, no events arrive between the initial `presence_state` snapshot and eventual leave, so maxAge would expire every user - including ones who are still connected. The heartbeat periodically tells clients which keys are still active, resetting their maxAge timers.
+```js
+const everyoneEver = presence('room', { maxAge: 0 });
+```
+
+To customize the window, set `maxAge` and the matching server `heartbeat` together (rule of thumb: heartbeat is one-third of `maxAge` or less, so a still-present user gets at least two refreshes per sweep window):
 
 ```js
 // Server: heartbeat every 60s
 const presence = createPresence({ key: 'id', heartbeat: 60_000 });
 
-// Client: entries expire after 120s without a heartbeat refresh
-const users = presence('room', { maxAge: 120_000 });
+// Client: entries expire after 180s without a heartbeat refresh
+const users = presence('room', { maxAge: 180_000 });
 ```
 
-Rule of thumb: set `heartbeat` to half (or less) of the client's `maxAge`.
-
 #### How multi-tab dedup works
 
 If user "Alice" (key `id: '1'`) has three browser tabs open, `presence.join()` is called three times with the same key. The plugin ref-counts connections per key: Alice appears once in the list. When she closes two tabs, she stays present. Only when the last tab closes does the plugin broadcast a `leave` event.

package/files/handler.js

@@ -3035,17 +3035,30 @@ if (WS_ENABLED) {
 			// The 8192-byte ceiling is generous enough for subscribe-batch with
 			// many topics (N * 256-char names) while keeping the JSON.parse
 			// guard against truly large user messages.
+			// `msg` is hoisted to outer scope so it can be forwarded to the user
+			// handler in the fall-through delegation below. When the prefix
+			// matched and JSON.parse produced an object that did NOT match any
+			// known control type, the parsed value reaches plugin-layer
+			// dispatchers (e.g. svelte-realtime's `onJsonMessage`) directly, so
+			// they don't re-run TextDecoder + JSON.parse on every frame.
+			/** @type {any} */
+			let msg;
 			if (!isBinary && message.byteLength < 8192 &&
 				(new Uint8Array(message))[3] === 0x79 /* 'y' in {"type" */) {
 				/** @type {any} */
-				let msg;
+				let parsed;
 				try {
-					msg = JSON.parse(textDecoder.decode(message));
+					parsed = JSON.parse(textDecoder.decode(message));
 				} catch {
-					// Not valid JSON - fall through to user handler.
-					wsModule.message?.(ws, { data: message, isBinary, platform: ws.getUserData()[WS_PLATFORM] });
+					parsed = undefined;
+				}
+				if (parsed === null || typeof parsed !== 'object') {
+					// Not a JSON object envelope (parse failed, or parsed to
+					// null / primitive / array). Forward raw bytes only.
+					wsModule.message?.(ws, { data: message, isBinary, msg, platform: ws.getUserData()[WS_PLATFORM] });
 					return;
 				}
+				msg = parsed;
 				if (msg.type === 'subscribe' && typeof msg.topic === 'string') {
 					const ref = hasRef(msg.ref) ? msg.ref : null;
 					if (!isValidWireTopic(msg.topic, ALLOW_NON_ASCII_TOPICS)) {
@@ -3230,8 +3243,10 @@ if (WS_ENABLED) {
 					return;
 				}
 			}
-			// Delegate everything else to the user's handler (if provided)
-			wsModule.message?.(ws, { data: message, isBinary, platform: ws.getUserData()[WS_PLATFORM] });
+			// Delegate everything else to the user's handler (if provided).
+			// `msg` is the JSON-parsed envelope when the prefix matched + parsed
+			// to an object + no control type matched; otherwise undefined.
+			wsModule.message?.(ws, { data: message, isBinary, msg, platform: ws.getUserData()[WS_PLATFORM] });
 		},
 
 		drain: (ws) => {

package/index.d.ts

@@ -517,6 +517,26 @@ export interface MessageContext {
 	data: ArrayBuffer;
 	/** Whether the message is binary. */
 	isBinary: boolean;
+	/**
+	 * The JSON-parsed envelope, when the adapter parsed the frame for
+	 * control-message routing (subscribe / unsubscribe / hello / resume /
+	 * reply / subscribe-batch) but no control type matched.
+	 *
+	 * Plugin-layer JSON envelope dispatchers (e.g. svelte-realtime's
+	 * `createMessage({ onJsonMessage })`) consume this directly instead of
+	 * re-running `TextDecoder + JSON.parse` on every frame.
+	 *
+	 * `undefined` when:
+	 * - the frame is binary (`isBinary === true`), or
+	 * - the frame did not start with `{"ty` (byte[3] !== 0x79), or
+	 * - the frame was larger than 8 KiB, or
+	 * - `JSON.parse` threw, or
+	 * - the parsed value was not a plain object (null / array / primitive).
+	 *
+	 * The adapter's `websocket.maxPayloadLength` (default 1 MB) is the
+	 * structural ceiling for frame size; this field adds no separate cap.
+	 */
+	msg?: any;
 	/** The platform API - publish, send, topic helpers, etc. */
 	platform: Platform;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "publishConfig": {
     "tag": "latest"
   },

package/plugins/cursor/server.js

@@ -99,6 +99,13 @@ const EVENTS = Object.freeze({
  *   subscribe so late joiners see existing cursors immediately.
  * @property {() => void} clear -
  *   Clear all cursor tracking state and pending timers.
+ * @property {() => { flushes: number, driftMeanMs: number, driftMaxMs: number, dirtyTopicsCurrent: number, activeTopicsTotal: number }} stats -
+ *   Snapshot of scheduler health. `flushes` is the total tick-driven
+ *   flushes; `driftMeanMs` / `driftMaxMs` measure the gap between the
+ *   target deadline and the actual fire time (`> topicThrottle` indicates
+ *   sustained event-loop saturation); `dirtyTopicsCurrent` is topics with
+ *   pending coalesced entries (should hover near zero); `activeTopicsTotal`
+ *   is topics with at least one local cursor.
  */
 
 /**
@@ -193,14 +200,48 @@ export function createCursor(options = {}) {
 	const topics = new Map();
 
 	/**
-	 * Per-topic aggregate throttle state for `topicThrottle` coalescing.
-	 * Dirty entries are keyed by connection key; latest-wins. When the
-	 * coalesce window elapses, `dirty.size === 1` sends a single `update`
-	 * and any other count sends one `bulk` array.
-	 * @type {Map<string, { lastFlush: number, timer: any, dirty: Map<string, { data: any, platform: any }> }>}
+	 * Per-topic aggregate flush state.
+	 *
+	 * - `dirty`: cursors awaiting coalesced flush. Keyed by connection key;
+	 *   latest-wins. When the coalesce window elapses, `dirty.size === 1`
+	 *   sends a single `update`; any other count sends one `bulk` array.
+	 * - `lastFlush`: target-anchored timestamp of the most recent flush.
+	 *   Advanced by `topicThrottleMs` per cycle (not to actual fire time)
+	 *   so a single late tick does not compound drift on subsequent cycles.
+	 *
+	 * @type {Map<string, { dirty: Map<string, { data: any, platform: any }>, lastFlush: number }>}
 	 */
 	const topicFlush = new Map();
 
+	/**
+	 * Topics with at least one pending dirty entry. Bounded by mover count,
+	 * not active-topic count, so the scheduler walks only dirty topics on
+	 * each tick instead of every active one.
+	 * @type {Set<string>}
+	 */
+	const dirtyTopics = new Set();
+
+	/**
+	 * Single tracker-wide timer. Always points at the next earliest topic
+	 * deadline (or null when idle). Replaces the previous per-topic
+	 * setTimeout pattern: N pending timers -> 1 pending timer regardless
+	 * of topic count. Scheduling cost is O(dirty topics), not O(active
+	 * topics).
+	 * @type {ReturnType<typeof setTimeout> | null}
+	 */
+	let tickTimer = null;
+
+	/**
+	 * Drift accounting for `stats()` observability. Mean (target - actual)
+	 * and max over tick-driven flushes. Leading-edge synchronous flushes
+	 * are NOT counted (they fire on the caller's thread, not via the
+	 * scheduler; their drift is structurally zero).
+	 */
+	let driftSum = 0;
+	let driftCount = 0;
+	let driftMax = 0;
+	let flushCount = 0;
+
 	/**
 	 * Get or create ws state and return the connection key + user data.
 	 * @param {any} ws
@@ -224,14 +265,15 @@ export function createCursor(options = {}) {
 	}
 
 	/**
-	 * Drop the topic's coalesce state (clears any pending timer first).
+	 * Drop the topic's coalesce state. The single tracker-wide tickTimer is
+	 * left alone (it self-cancels on the next tick when `dirtyTopics` is
+	 * empty); we just remove this topic from both the flush map and the
+	 * dirty set so the next tick skips it.
 	 * @param {string} topic
 	 */
 	function clearTopicFlush(topic) {
-		const flushState = topicFlush.get(topic);
-		if (!flushState) return;
-		if (flushState.timer) clearTimeout(flushState.timer);
 		topicFlush.delete(topic);
+		dirtyTopics.delete(topic);
 	}
 
 	/**
@@ -262,6 +304,7 @@ export function createCursor(options = {}) {
 	 */
 	function flushDirty(topic, dirty) {
 		if (dirty.size === 0) return;
+		flushCount++;
 		if (dirty.size === 1) {
 			const [k, v] = dirty.entries().next().value;
 			doBroadcast(topic, k, v.data, v.platform);
@@ -278,9 +321,65 @@ export function createCursor(options = {}) {
 		}
 	}
 
+	/**
+	 * Scheduler tick. Walks `dirtyTopics`, flushes any topic whose deadline
+	 * (`lastFlush + topicThrottleMs`) has passed, and re-arms `tickTimer`
+	 * for the next earliest pending deadline. Topics whose deadline has
+	 * not yet passed stay in `dirtyTopics` for the next tick.
+	 *
+	 * Target-anchored advance: on flush, `lastFlush` is set to the deadline
+	 * (not the actual fire time) so a single late tick does not compound
+	 * drift on subsequent cycles. If we fell behind by more than one cycle
+	 * (event loop saturation > `topicThrottleMs`), `lastFlush` resets to
+	 * `now` to avoid queueing phantom catch-up fires.
+	 */
+	function tick() {
+		tickTimer = null;
+		const now = Date.now();
+		let nextDeadline = Infinity;
+
+		for (const topic of dirtyTopics) {
+			const state = topicFlush.get(topic);
+			if (!state) { dirtyTopics.delete(topic); continue; }
+			if (state.dirty.size === 0) {
+				dirtyTopics.delete(topic);
+				continue;
+			}
+			const deadline = state.lastFlush + topicThrottleMs;
+			if (deadline <= now) {
+				const drift = now - deadline;
+				driftSum += drift;
+				driftCount++;
+				if (drift > driftMax) driftMax = drift;
+
+				flushDirty(topic, state.dirty);  // increments flushCount internally
+				state.dirty.clear();
+				dirtyTopics.delete(topic);
+
+				state.lastFlush = drift < topicThrottleMs ? deadline : now;
+			} else if (deadline < nextDeadline) {
+				nextDeadline = deadline;
+			}
+		}
+
+		if (nextDeadline !== Infinity) {
+			tickTimer = setTimeout(tick, Math.max(0, nextDeadline - Date.now()));
+		}
+		// else: scheduler idle until next `broadcast()` call.
+	}
+
+	function armTick(delay) {
+		if (tickTimer !== null) return;
+		tickTimer = setTimeout(tick, delay);
+	}
+
 	/**
 	 * Route a broadcast through the per-topic coalesce window when
 	 * `topicThrottle` is enabled, or directly publish when disabled.
+	 *
+	 * Leading-edge synchronous flush preserves the contract that the first
+	 * call on an idle topic publishes immediately (no setTimeout(0) detour).
+	 * Trailing-edge fires via the single tracker-wide `tickTimer`.
 	 */
 	function broadcast(topic, key, data, platform) {
 		if (topicThrottleMs <= 0) {
@@ -290,34 +389,22 @@ export function createCursor(options = {}) {
 
 		let state = topicFlush.get(topic);
 		if (!state) {
-			state = { lastFlush: 0, timer: null, dirty: new Map() };
+			state = { dirty: new Map(), lastFlush: 0 };
 			topicFlush.set(topic, state);
 		}
-
 		state.dirty.set(key, { data, platform });
 
 		const now = Date.now();
 		if (now - state.lastFlush >= topicThrottleMs) {
-			if (state.timer) {
-				clearTimeout(state.timer);
-				state.timer = null;
-			}
 			state.lastFlush = now;
 			flushDirty(topic, state.dirty);
 			state.dirty.clear();
+			dirtyTopics.delete(topic);
 			return;
 		}
 
-		if (!state.timer) {
-			state.timer = setTimeout(() => {
-				const s = topicFlush.get(topic);
-				if (!s) return;
-				s.timer = null;
-				s.lastFlush = Date.now();
-				flushDirty(topic, s.dirty);
-				s.dirty.clear();
-			}, topicThrottleMs - (now - state.lastFlush));
-		}
+		dirtyTopics.add(topic);
+		armTick(Math.max(0, topicThrottleMs - (now - state.lastFlush)));
 	}
 
 	/** @type {CursorTracker} */
@@ -460,15 +547,42 @@ export function createCursor(options = {}) {
 					if (entry.timer) clearTimeout(entry.timer);
 				}
 			}
-			for (const [, state] of topicFlush) {
-				if (state.timer) clearTimeout(state.timer);
-			}
+			if (tickTimer !== null) { clearTimeout(tickTimer); tickTimer = null; }
+			dirtyTopics.clear();
 			topics.clear();
 			topicFlush.clear();
 			wsState.clear();
 			connCounter = 0;
 		},
 
+		/**
+		 * Snapshot of scheduler health. Always available, near-zero cost.
+		 *
+		 * - `flushes`: total tick-driven flushes since tracker creation.
+		 * - `driftMeanMs`: mean (target_deadline - actual_fire_time) across
+		 *   all tick-driven flushes. 0 means perfect cadence; values >
+		 *   `topicThrottle` indicate sustained event-loop saturation or
+		 *   CPU contention.
+		 * - `driftMaxMs`: largest single observed late fire. Useful for
+		 *   spotting one-off GC pauses vs. sustained drift.
+		 * - `dirtyTopicsCurrent`: topics with pending coalesced entries
+		 *   right now. Should hover near zero in healthy operation.
+		 * - `activeTopicsTotal`: topics with at least one local cursor.
+		 *
+		 * Leading-edge synchronous flushes (first call on an idle topic)
+		 * are not counted in drift stats - they fire on the call thread,
+		 * not via the scheduler.
+		 */
+		stats() {
+			return {
+				flushes: flushCount,
+				driftMeanMs: driftCount > 0 ? driftSum / driftCount : 0,
+				driftMaxMs: driftMax,
+				dirtyTopicsCurrent: dirtyTopics.size,
+				activeTopicsTotal: topics.size
+			};
+		},
+
 		hooks: {
 			message(ws, { data, platform }) {
 				let parsed;

package/plugins/presence/client.d.ts

@@ -6,10 +6,19 @@ import type { Readable } from 'svelte/store';
  * Returns a readable Svelte store containing an array of user data objects.
  * The array updates automatically when users join or leave.
  *
+ * Defaults to a 90 s `maxAge` sweep: entries that haven't been refreshed
+ * by a heartbeat or presence_diff/state inside the window are removed
+ * from the local map. The server emits `{userKey: data}` heartbeats
+ * every 30 s by default, so still-present users re-appear on the next
+ * heartbeat (no flicker). Pass `maxAge: 0` to opt out of the sweep for
+ * admin / audit views that want unbounded retention.
+ *
  * You must also subscribe to the topic itself (via `on()`, `crud()`, etc.)
  * for the server's `subscribe` hook to fire and register your presence.
  *
  * @param topic - Topic to track presence on
+ * @param options - `maxAge` defaults to 90000 (ms). Pass `0` to disable
+ *   the sweep.
  *
  * @example
  * ```svelte

package/plugins/presence/client.js

@@ -5,17 +5,24 @@
  * a live list of who's connected. The server handles join/leave tracking;
  * this module just keeps the client-side state in sync.
  *
- * When `maxAge` is set, entries that haven't been refreshed (via `list`
- * or `join` events) within that window are automatically removed. This
- * makes clients self-healing when the server fails to broadcast a `leave`
- * event (e.g. mass disconnects overwhelming Redis cleanup).
+ * Defaults to a 90 s `maxAge` sweep: entries that haven't been refreshed
+ * by a heartbeat or presence_diff/state inside the window are removed
+ * from the local map. The in-memory server (and the Redis-backed variant
+ * in svelte-adapter-uws-extensions) emits `{userKey: data}` heartbeats
+ * every 30 s by default, so a still-present user re-appears on the very
+ * next heartbeat - no flicker for live users, and ghost entries from
+ * silent server-side TTL expiry (cluster mass-disconnect, ungraceful
+ * client close) clear within one sweep window.
+ *
+ * Apps that want unbounded retention ("show every user who ever touched
+ * this topic" - admin / audit views) opt out with `maxAge: 0`.
  *
  * @module svelte-adapter-uws/plugins/presence/client
  */
 
 const TOPIC_PREFIX = '__presence:';
 
-import { on } from '../../client.js';
+import { on, connect, status } from '../../client.js';
 import { writable } from 'svelte/store';
 
 /** @type {Map<string, { subscribe: (fn: Function) => (() => void) }>} */
@@ -62,14 +69,19 @@ const presenceStores = new Map();
  * @example
  * ```svelte
  * <script>
- *   // Self-healing: entries expire after 90s without a refresh
- *   const users = presence('room', { maxAge: 90_000 });
+ *   // Opt out of the default 90 s sweep for an admin / audit view.
+ *   const users = presence('room', { maxAge: 0 });
  * </script>
  * ```
  */
 export function presence(topic, options) {
-	const maxAge = options?.maxAge;
-	const cacheKey = maxAge > 0 ? topic + '\0' + maxAge : topic;
+	// Default 90 s sweep matches the extensions Redis presence's default
+	// `ttl: 90` (server-side per-field TTL) and gives the in-memory
+	// server's 30 s default heartbeat a 3x safety margin. Apps that want
+	// "show every user who ever touched this topic" (admin/audit views)
+	// opt out with `maxAge: 0`.
+	const maxAge = options?.maxAge ?? 90000;
+	const cacheKey = topic + '\0' + maxAge;
 
 	const cached = presenceStores.get(cacheKey);
 	if (cached) return cached;
@@ -83,9 +95,11 @@ export function presence(topic, options) {
 	const output = writable(/** @type {any[]} */ ([]));
 
 	let sourceUnsub = /** @type {(() => void) | null} */ (null);
+	let statusUnsub = /** @type {(() => void) | null} */ (null);
 	/** @type {ReturnType<typeof setInterval> | null} */
 	let sweepTimer = null;
 	let refCount = 0;
+	let cancelled = false;
 
 	function flush() {
 		output.set([...userMap.values()]);
@@ -105,6 +119,7 @@ export function presence(topic, options) {
 	}
 
 	function startListening() {
+		cancelled = false;
 		// Fresh on() call each time - the underlying writable in client.js
 		// is cleaned up on full unsubscribe, so a stale reference would
 		// silently stop receiving events.
@@ -150,29 +165,67 @@ export function presence(topic, options) {
 				return;
 			}
 
-			if (event.event === 'heartbeat' && Array.isArray(event.data)) {
-				// Server confirms these keys are still active - refresh their
-				// timestamps so maxAge doesn't expire them. Keys not in the
-				// heartbeat are left alone (maxAge will handle them).
+			if (event.event === 'heartbeat') {
 				const now = Date.now();
-				for (const key of event.data) {
-					if (timestamps.has(key)) {
+				let changed = false;
+				if (event.data && typeof event.data === 'object' && !Array.isArray(event.data)) {
+					// New shape: `{userKey: data}` map. Refresh existing AND
+					// re-add any entry that aged out between heartbeats. The
+					// older "refresh existing only" branch (below) could not
+					// recover entries the local sweep had already removed -
+					// once an entry aged out, the next heartbeat couldn't
+					// bring it back and the user stayed missing until a
+					// presence_diff or presence_state arrived.
+					for (const [key, data] of Object.entries(event.data)) {
 						timestamps.set(key, now);
+						const prev = userMap.get(key);
+						if (prev !== data) {
+							userMap.set(key, data);
+							changed = true;
+						}
+					}
+				} else if (Array.isArray(event.data)) {
+					// Back-compat: keys-only heartbeat (older server). Refresh
+					// existing entries; cannot recover aged-out ones from this
+					// shape. The presence_diff / presence_state reconciliation
+					// path still corrects missing entries on the next event.
+					for (const key of event.data) {
+						if (timestamps.has(key)) {
+							timestamps.set(key, now);
+						}
 					}
 				}
+				if (changed) flush();
+				return;
 			}
 		});
 
 		if (maxAge > 0) {
 			sweepTimer = setInterval(sweep, Math.max(maxAge / 2, 1000));
 		}
+
+		// Request a presence snapshot every time the socket opens (initial
+		// connect AND reconnects). Without this, a reconnecting client
+		// missed any presence_diff frames that fired during the disconnect
+		// window and its in-memory map stayed at whatever it last knew.
+		// Symmetric to the cursor plugin's `cursor-snapshot` send.
+		statusUnsub = status.subscribe((s) => {
+			if (s === 'open' && !cancelled) {
+				connect().send({ type: 'presence-snapshot', topic });
+			}
+		});
 	}
 
 	function stopListening() {
+		cancelled = true;
 		if (sourceUnsub) {
 			sourceUnsub();
 			sourceUnsub = null;
 		}
+		if (statusUnsub) {
+			statusUnsub();
+			statusUnsub = null;
+		}
 		if (sweepTimer) {
 			clearInterval(sweepTimer);
 			sweepTimer = null;

package/plugins/presence/server.d.ts

@@ -47,19 +47,31 @@ export interface PresenceOptions<UserData = unknown, Selected extends Record<str
 	/**
 	 * Interval in milliseconds between heartbeat broadcasts.
 	 *
-	 * When set, the server periodically publishes a `heartbeat` event to all
-	 * presence topics containing the list of active user keys. This resets
-	 * the `maxAge` timer on clients, preventing live users from being expired.
+	 * The server periodically publishes a `heartbeat` event to all presence
+	 * topics carrying a `{userKey: data}` map of every active user. This
+	 * refreshes each entry's `maxAge` timer on the client AND re-adds any
+	 * entry the client swept while the user was still present, so live
+	 * users do not flicker out when a `presence_diff` is missed (transient
+	 * network blip, JS thread saturation).
 	 *
-	 * Set this to a value shorter than the client's `maxAge`.
+	 * Set this to a value shorter than the client's `maxAge`. The 30 s
+	 * default fits the 90 s default client `maxAge` with a 3x safety
+	 * margin. Pass `0` to disable heartbeats entirely (apps that do not
+	 * use the `maxAge` self-healing path).
 	 *
-	 * @default 0 (disabled)
+	 * @default 30000
 	 *
 	 * @example
 	 * ```js
-	 * // Server heartbeat every 60s, client maxAge 120s
+	 * // Slower heartbeat (less wire traffic, larger window for ghost entries)
 	 * const presence = createPresence({ heartbeat: 60_000 });
 	 * ```
+	 *
+	 * @example
+	 * ```js
+	 * // Disable heartbeats; client must rely on presence_diff alone
+	 * const presence = createPresence({ heartbeat: 0 });
+	 * ```
 	 */
 	heartbeat?: number;
 

package/plugins/presence/server.js

@@ -52,11 +52,14 @@ const TOPIC_PREFIX = '__presence:';
  *
  *   Should return JSON-serializable data (plain objects, arrays, strings, numbers,
  *   booleans, null) since the result is sent over WebSocket.
- * @property {number} [heartbeat=0] - Interval in milliseconds between heartbeat broadcasts.
- *   When set, the server periodically publishes a `heartbeat` event to all presence topics
- *   containing the list of active keys. This resets the `maxAge` timer on clients, preventing
- *   live users from being expired. Set this to a value shorter than the client's `maxAge`.
- *   Disabled by default (0 or omitted).
+ * @property {number} [heartbeat=30000] - Interval in milliseconds between heartbeat broadcasts.
+ *   The server periodically publishes a `heartbeat` event to all presence topics carrying a
+ *   `{userKey: data}` map of every active user. This refreshes each entry's `maxAge` timer on
+ *   the client AND re-adds any entry the client swept while the user was still present, so
+ *   live users do not flicker out when a `presence_diff` is missed (e.g. transient network
+ *   blip, JS thread saturation). Set this to a value shorter than the client's `maxAge`
+ *   (default client `maxAge` is 90 s, so 30 s gives a 3x safety margin). Pass `0` to disable
+ *   heartbeats entirely (apps that do not use the `maxAge` self-healing path).
  */
 
 /**
@@ -252,7 +255,15 @@ function defaultPresenceSelect(obj, ancestors) {
 export function createPresence(options = {}) {
 	const keyField = options.key || 'id';
 	const select = options.select || defaultPresenceSelect;
-	const heartbeatMs = options.heartbeat || 0;
+	// Default 30 s heartbeat keeps the client's `maxAge` sweep self-healing:
+	// a still-present user re-appears on the next heartbeat after their
+	// entry ages out of the local map. Apps that want zero heartbeat
+	// traffic (no `maxAge` consumers, or out-of-band liveness) pass
+	// `heartbeat: 0` explicitly to opt out.
+	const heartbeatMs = options.heartbeat ?? 30000;
+	if (typeof heartbeatMs !== 'number' || !Number.isFinite(heartbeatMs) || heartbeatMs < 0) {
+		throw new Error('presence: heartbeat must be a non-negative number');
+	}
 	const maxConnections = options.maxConnections ?? 1_000_000;
 	const maxTopics = options.maxTopics ?? 1_000_000;
 
@@ -373,11 +384,16 @@ export function createPresence(options = {}) {
 		if (heartbeatMs > 0) {
 			heartbeatTimer = setInterval(() => {
 				for (const [topic, users] of topicPresence) {
-					_platform.publish(
-						TOPIC_PREFIX + topic,
-						'heartbeat',
-						[...users.keys()]
-					);
+					// Publish a `{userKey: data}` map (rather than a keys-only
+					// array) so a client whose entry aged out of its local
+					// `maxAge` sweep between heartbeats can re-add it from the
+					// heartbeat alone, without waiting for a presence_diff /
+					// presence_state to reconcile. Matches the Redis-backed
+					// variant in svelte-adapter-uws-extensions.
+					/** @type {Record<string, any>} */
+					const dataMap = {};
+					for (const [userKey, entry] of users) dataMap[userKey] = entry.data;
+					_platform.publish(TOPIC_PREFIX + topic, 'heartbeat', dataMap);
 				}
 			}, heartbeatMs);
 		}

package/testing.js

@@ -568,12 +568,27 @@ export async function createTestServer(options = {}) {
 
 		async message(ws, message, isBinary) {
 			bumpInT(ws, message);
-			// Handle subscribe/unsubscribe from client store
+			// Handle subscribe/unsubscribe from client store.
+			//
+			// `msg` is hoisted to outer scope so it can be forwarded to the
+			// user handler in the fall-through delegation below. When the
+			// prefix matched and JSON.parse produced an object that did NOT
+			// match any known control type, the parsed value reaches plugin-
+			// layer dispatchers (e.g. svelte-realtime's `onJsonMessage`)
+			// directly, so they don't re-run TextDecoder + JSON.parse on
+			// every frame. Mirrors handler.js + vite.js.
+			/** @type {any} */
+			let msg;
 			if (!isBinary && message.byteLength < 8192) {
 				const bytes = new Uint8Array(message);
 				if (bytes[3] === 0x79) {
 					try {
-						const msg = JSON.parse(Buffer.from(message).toString());
+						msg = JSON.parse(Buffer.from(message).toString());
+						// Reject null / primitives / arrays so `msg` only reaches
+						// the user handler as a {type,...} object envelope. Throw
+						// to the catch (which clears `msg`) for a unified fall-
+						// through path with parse failures.
+						if (msg === null || typeof msg !== 'object' || Array.isArray(msg)) throw 0;
 						if (msg.type === 'subscribe' && typeof msg.topic === 'string') {
 							const ref = hasRefT(msg.ref) ? msg.ref : null;
 							if (!isValidWireTopic(msg.topic, ALLOW_NON_ASCII_TOPICS_T)) {
@@ -702,7 +717,13 @@ export async function createTestServer(options = {}) {
 							sendOutboundT(ws, '{"type":"resumed"}');
 							return;
 						}
-					} catch {}
+					} catch {
+						// Not JSON, not an object envelope, or a known control
+						// type that threw inside its handler. Clear `msg` so the
+						// fall-through delegation sees `msg: undefined` (raw
+						// bytes only).
+						msg = undefined;
+					}
 				}
 			}
 
@@ -712,7 +733,9 @@ export async function createTestServer(options = {}) {
 			}
 			messageWaiters = [];
 
-			handler.message?.(ws, { data: message, isBinary, platform: ws.getUserData()[WS_PLATFORM] });
+			// `msg` is the JSON-parsed envelope when the prefix matched + parsed
+			// to an object + no control type matched; otherwise undefined.
+			handler.message?.(ws, { data: message, isBinary, msg, platform: ws.getUserData()[WS_PLATFORM] });
 		},
 
 		close(ws, code, message) {

package/vite.js

@@ -1003,9 +1003,24 @@ export default function uws(options = {}) {
 				// {"topic" have byte[3]='o' - skip JSON.parse for non-control messages.
 				// 8192 bytes matches the production handler ceiling and is large
 				// enough for a subscribe-batch with many topics.
+				//
+				// `msg` is hoisted to outer scope so it can be forwarded to the
+				// user handler in the fall-through delegation below. When the
+				// prefix matched and JSON.parse produced an object that did NOT
+				// match any known control type, the parsed value reaches plugin-
+				// layer dispatchers (e.g. svelte-realtime's `onJsonMessage`)
+				// directly, so they don't re-run TextDecoder + JSON.parse on
+				// every frame.
+					/** @type {any} */
+					let msg;
 					if (!isBinary && buf.byteLength < 8192 && buf[3] === 0x79) {
 						try {
-							const msg = JSON.parse(buf.toString());
+							msg = JSON.parse(buf.toString());
+							// Reject null / primitives / arrays so `msg` only reaches
+							// the user handler as a {type,...} object envelope. Throw
+							// to the catch (which clears `msg`) for a unified fall-
+							// through path with parse failures.
+							if (msg === null || typeof msg !== 'object' || Array.isArray(msg)) throw 0;
 							if (msg.type === 'subscribe' && typeof msg.topic === 'string') {
 								const ref = hasRefValue(msg.ref) ? msg.ref : null;
 								if (!isValidWireTopic(msg.topic, ALLOW_NON_ASCII_TOPICS_V)) {
@@ -1149,14 +1164,20 @@ export default function uws(options = {}) {
 								return;
 							}
 						} catch {
-							// Not JSON - fall through to user handler
+							// Not JSON, not an object envelope, or a known control
+							// type that threw inside its handler. Clear `msg` so the
+							// fall-through delegation sees `msg: undefined` (raw
+							// bytes only).
+							msg = undefined;
 						}
 					}
 
-					// Delegate to user handler
+					// Delegate to user handler. `msg` is the JSON-parsed envelope
+					// when the prefix matched + parsed to an object + no control
+					// type matched; otherwise undefined.
 					await handlerReady;
 					if (userHandlers.message) {
-						userHandlers.message(wrapped, { data: arrayBuffer, isBinary: !!isBinary, platform: wrapped.getUserData()[WS_PLATFORM] });
+						userHandlers.message(wrapped, { data: arrayBuffer, isBinary: !!isBinary, msg, platform: wrapped.getUserData()[WS_PLATFORM] });
 					}
 				});