svelte-adapter-uws 0.5.3 → 0.5.5

package/README.md

@@ -1274,6 +1274,22 @@ export async function GET({ platform }) {
 
 The returned `Map` is the live module-level instance - read-only, do not mutate. In test mode (`process.env.VITEST` set, or `NODE_ENV === 'test'`) the assert helper additionally throws so test runners surface the failure; in production it logs and counts but does not throw, so a violation inside a uWS callback frame cannot crash the worker.
 
+### `platform.closedWsAborts`
+
+Per-worker count of best-effort uWS operations that aborted because the underlying WebSocket had already closed. Bumped every time `platform.subscribe`, `platform.unsubscribe`, `platform.send`, `platform.sendCoalesced`, `platform.sendTo`, or `platform.request` is called on a `ws` whose native handle has been freed - typically because the caller `await`-ed something (auth, loader, subscribe hook) and the client closed during the wait.
+
+These methods are *closed-WS safe* by contract: they swallow uWS's `Invalid access of closed uWS.WebSocket` exception, return a success-shaped no-op sentinel (`null` for subscribe, `false` for unsubscribe, `2` for send, etc.), and bump this counter. Callers can fire-and-forget without a per-site try/catch.
+
+```js
+export async function GET({ platform }) {
+  return json({ closedWsAborts: platform.closedWsAborts });
+}
+```
+
+A non-zero value is normal under client churn (tab close, network blips, mass reconnect waves). A rapidly-growing value under steady load indicates either pathological client behaviour or that the server's async setup path is too long for its connect rate. In clustered mode, sum across workers for cluster-wide visibility.
+
+Monotonic, per-worker, reset only on process restart.
+
 ### `platform.pressure` and `platform.onPressure(cb)`
 
 Worker-local backpressure signal. The adapter samples once per second (configurable) and reports the most urgent active stress as a single `reason` enum, so user code can degrade with intent instead of generic panic.
@@ -2377,8 +2393,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
 });
@@ -2450,8 +2466,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
@@ -2466,14 +2482,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
 
@@ -2484,20 +2501,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.
 
-**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.
+For admin / audit views that want unbounded retention ("show every user who ever touched this topic"), opt out with `maxAge: 0`:
+
+```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.
@@ -3328,6 +3349,8 @@ Per-worker limitations (acceptable for most apps):
 - `platform.connections`  - returns the count for the local worker only
 - `platform.subscribers(topic)`  - returns the count for the local worker only
 - `platform.sendTo(filter, ...)`  - iterates the local worker's connections only, no cross-worker relay
+- `platform.closedWsAborts`  - per-worker counter; sum across workers for cluster total
+- `platform.assertions`  - per-worker counter Map
 
 ### Docker / multi-process deployments (Linux)
 

package/files/handler.js

@@ -421,7 +421,8 @@ const closeHookRegistered = WS_ENABLED && !!wsModule.close;
  */
 function bumpIn(ws, message) {
 	if (!closeHookRegistered) return;
-	const stats = ws.getUserData()[WS_STATS];
+	let stats;
+	try { stats = ws.getUserData()[WS_STATS]; } catch { return; }
 	if (!stats) return;
 	stats.messagesIn++;
 	stats.bytesIn += typeof message === 'string' ? message.length : message.byteLength;
@@ -439,7 +440,8 @@ function bumpIn(ws, message) {
  */
 function bumpOut(ws, payload) {
 	if (!closeHookRegistered) return;
-	const stats = ws.getUserData()[WS_STATS];
+	let stats;
+	try { stats = ws.getUserData()[WS_STATS]; } catch { return; }
 	if (!stats) return;
 	stats.messagesOut++;
 	stats.bytesOut += payload.length;
@@ -489,6 +491,16 @@ function maybeWarnTopicRegistry() {
 
 let publishCountWindow = 0;
 let totalSubscriptions = 0;
+// Count of best-effort operations that aborted because the underlying
+// uWS WebSocket had already closed. The platform contract is that
+// ws-targeted public methods (subscribe / unsubscribe / send /
+// sendCoalesced / request) and internal helpers that may run after an
+// `await` never propagate uWS's "Invalid access of closed
+// uWS.WebSocket" exception to user code - they swallow it, return a
+// no-op sentinel, and bump this counter. Operators can read
+// `platform.closedWsAborts` to detect when mass-connect kernel /
+// backpressure churn is closing sockets mid-async-setup at scale.
+let closedWsAborts = 0;
 
 /**
  * Per-topic publish counters for runaway-publisher detection. Single
@@ -824,7 +836,7 @@ async function runUserSubscribeGate(ws, topic) {
 function sendSubscribed(ws, topic, ref) {
 	if (ref === null) return;
 	const payload = JSON.stringify({ type: 'subscribed', topic, ref });
-	ws.send(payload, false, false);
+	try { ws.send(payload, false, false); } catch { closedWsAborts++; return; }
 	bumpOut(ws, payload);
 }
 
@@ -840,7 +852,7 @@ function sendSubscribed(ws, topic, ref) {
 function sendSubscribeDenied(ws, topic, ref, reason) {
 	if (ref === null) return;
 	const payload = JSON.stringify({ type: 'subscribe-denied', topic, ref, reason });
-	ws.send(payload, false, false);
+	try { ws.send(payload, false, false); } catch { closedWsAborts++; return; }
 	bumpOut(ws, payload);
 }
 
@@ -852,15 +864,29 @@ function sendSubscribeDenied(ws, topic, ref, reason) {
  * @param {import('uWebSockets.js').WebSocket<any>} ws
  */
 function flushCoalescedFor(ws) {
-	const userData = ws.getUserData();
+	let userData;
+	try { userData = ws.getUserData(); }
+	catch { closedWsAborts++; return; }
 	const pending = userData[WS_COALESCED];
 	if (!pending || pending.size === 0) return;
 	assert(pending instanceof Map, 'coalesce.pending-type', null);
+	let aborted = false;
 	drainCoalesced(pending, (msg) => {
+		if (aborted) return 2;
 		assert(typeof msg.topic === 'string', 'coalesce.entry-topic-type', null);
 		assert(typeof msg.event === 'string', 'coalesce.entry-event-type', null);
 		const payload = envelopePrefix(msg.topic, msg.event) + JSON.stringify(msg.data ?? null) + '}';
-		const result = ws.send(payload, false, false);
+		let result;
+		try { result = ws.send(payload, false, false); }
+		catch {
+			// Socket closed mid-drain. There will be no further `drain`
+			// event to retry on, so dropping the rest of the buffer is
+			// the only correct outcome - returning 1 (BACKPRESSURE) lets
+			// drainCoalesced clear the current entry and stop iterating.
+			closedWsAborts++;
+			aborted = true;
+			return 1;
+		}
 		// `result` MUST propagate to drainCoalesced. 0=SUCCESS removes the
 		// entry; 1=BACKPRESSURE removes it and halts the loop; 2=DROPPED
 		// retains the entry for retry on next drain. Don't refactor away
@@ -869,6 +895,7 @@ function flushCoalescedFor(ws) {
 		if (result !== 2) bumpOut(ws, payload);
 		return result;
 	});
+	if (aborted) pending.clear();
 }
 
 /** @type {import('./index.js').Platform} */
@@ -927,7 +954,13 @@ const platform = {
 	send(ws, topic, event, data) {
 		const payload = envelopePrefix(topic, event) + JSON.stringify(data ?? null) + '}';
 		assert(payload.length > 0, 'envelope.send-empty', { topic, event });
-		const result = ws.send(payload, false, false);
+		// `ws.send` throws on a freed native handle (callers may reach
+		// here after an `await` that outlasted the socket). Return 2
+		// (DROPPED, the uWS sentinel) so callers can pattern-match
+		// without distinguishing closed from backpressure-dropped.
+		let result;
+		try { result = ws.send(payload, false, false); }
+		catch { closedWsAborts++; return 2; }
 		bumpOut(ws, payload);
 		return result;
 	},
@@ -954,7 +987,9 @@ const platform = {
 	 * on the next drain.
 	 */
 	sendCoalesced(ws, { key, topic, event, data }) {
-		const userData = ws.getUserData();
+		let userData;
+		try { userData = ws.getUserData(); }
+		catch { closedWsAborts++; return; }
 		let pending = userData[WS_COALESCED];
 		if (!pending) {
 			pending = new Map();
@@ -990,7 +1025,15 @@ const platform = {
 		const envelope = envelopePrefix(topic, event) + JSON.stringify(data ?? null) + '}';
 		let count = 0;
 		for (const ws of wsConnections) {
-			const decision = filter(ws.getUserData());
+			// uWS's close event fires synchronously and removes from
+			// wsConnections before any user code runs, so under normal
+			// flow every entry here is open. Defensive try/catch covers
+			// pathological cases (e.g. user filter triggers a close via
+			// side effect, or another worker raced through cleanup).
+			let userData;
+			try { userData = ws.getUserData(); }
+			catch { closedWsAborts++; continue; }
+			const decision = filter(userData);
 			if (decision && typeof decision.then === 'function') {
 				if (!sendToAsyncWarned) {
 					sendToAsyncWarned = true;
@@ -1005,7 +1048,8 @@ const platform = {
 				continue;
 			}
 			if (decision) {
-				ws.send(envelope, false, false);
+				try { ws.send(envelope, false, false); }
+				catch { closedWsAborts++; continue; }
 				bumpOut(ws, envelope);
 				count++;
 			}
@@ -1040,6 +1084,30 @@ const platform = {
 		return readAssertionCounts();
 	},
 
+	/**
+	 * Per-worker count of best-effort uWS operations that aborted
+	 * because the underlying WebSocket had already closed.
+	 *
+	 * Ws-targeted platform methods (`subscribe`, `unsubscribe`, `send`,
+	 * `sendCoalesced`, `sendTo`, `request`) and the wire-level
+	 * subscribe / subscribe-batch handlers all swallow uWS's "Invalid
+	 * access of closed uWS.WebSocket" exception so callers never need
+	 * a per-site try/catch. Each swallow bumps this counter.
+	 *
+	 * A non-zero value is normal under churn (clients close mid-async-
+	 * setup all the time). A rapidly-growing value under steady load
+	 * indicates either pathological client behaviour or that the
+	 * server's async setup path is too long for its connect rate -
+	 * worth investigating but not, by itself, a bug.
+	 *
+	 * Monotonic, per-worker, reset only on process restart.
+	 *
+	 * @returns {number}
+	 */
+	get closedWsAborts() {
+		return closedWsAborts;
+	},
+
 	/**
 	 * Number of clients subscribed to a specific topic.
 	 */
@@ -1138,7 +1206,13 @@ const platform = {
 		// non-ASCII topic names (`__signal:Jose`, presence rooms with
 		// localized labels) must not be blocked at the platform layer.
 		if (!isValidWireTopic(topic, true)) return 'INVALID_TOPIC';
-		const subs = ws.getUserData()[WS_SUBSCRIPTIONS];
+		// `ws.getUserData()` throws on a freed native handle. RPC and
+		// plugin code paths routinely `await` something else before
+		// reaching here, so the WS may already be closed by the time
+		// this runs. Treat as a silent no-op.
+		let subs;
+		try { subs = ws.getUserData()[WS_SUBSCRIPTIONS]; }
+		catch { closedWsAborts++; return null; }
 		assert(subs instanceof Set, 'subs.shape', null);
 		if (subs.has(topic)) return null;
 		if (subs.size >= MAX_SUBSCRIPTIONS_PER_CONNECTION) return 'RATE_LIMITED';
@@ -1150,7 +1224,13 @@ const platform = {
 		// counter bump in that case.
 		if (subs.has(topic)) return null;
 		if (subs.size >= MAX_SUBSCRIPTIONS_PER_CONNECTION) return 'RATE_LIMITED';
-		ws.subscribe(topic);
+		// `ws.subscribe()` throws if the socket closed during the await
+		// above. Under mass-connect / backpressure churn this is the
+		// dominant abort mode (10-15% of connections close mid-setup).
+		// Swallow, count, and return success-shaped null so callers can
+		// fire-and-forget without per-site try/catch.
+		try { ws.subscribe(topic); }
+		catch { closedWsAborts++; return null; }
 		subs.add(topic);
 		totalSubscriptions++;
 		return null;
@@ -1227,10 +1307,17 @@ const platform = {
 	 * @returns {boolean} `true` if a subscription was removed
 	 */
 	unsubscribe(ws, topic) {
-		const subs = ws.getUserData()[WS_SUBSCRIPTIONS];
+		// Closed sockets get an early-out: there is no subscription
+		// state to remove, no uWS bookkeeping to drop, no informational
+		// hook to fire. The platform contract is "best effort; no throw
+		// on closed WS" - mirrors subscribe / send.
+		let subs;
+		try { subs = ws.getUserData()[WS_SUBSCRIPTIONS]; }
+		catch { closedWsAborts++; return false; }
 		assert(subs instanceof Set, 'subs.shape-unsubscribe', null);
 		if (!subs.has(topic)) return false;
-		ws.unsubscribe(topic);
+		try { ws.unsubscribe(topic); }
+		catch { closedWsAborts++; return false; }
 		subs.delete(topic);
 		totalSubscriptions--;
 		assert(totalSubscriptions >= 0, 'subs.total-negative', { totalSubscriptions });
@@ -1493,7 +1580,12 @@ const platform = {
 	 * so cleanup is automatic on close - no module-level leak risk.
 	 */
 	request(ws, event, data, options) {
-		const userData = ws.getUserData();
+		let userData;
+		try { userData = ws.getUserData(); }
+		catch {
+			closedWsAborts++;
+			return Promise.reject(new Error('connection closed'));
+		}
 		let pending = userData[WS_PENDING_REQUESTS];
 		if (!pending) {
 			pending = new Map();
@@ -1514,7 +1606,14 @@ const platform = {
 			}, timeoutMs);
 			pending.set(ref, { resolve, reject, timer });
 			const payload = JSON.stringify({ type: 'request', ref, event, data: data ?? null });
-			ws.send(payload, false, false);
+			try { ws.send(payload, false, false); }
+			catch {
+				closedWsAborts++;
+				clearTimeout(timer);
+				pending.delete(ref);
+				reject(new Error('connection closed'));
+				return;
+			}
 			bumpOut(ws, payload);
 		});
 	},
@@ -3093,7 +3192,8 @@ if (WS_ENABLED) {
 						sendSubscribeDenied(ws, msg.topic, ref, 'RATE_LIMITED');
 						return;
 					}
-					try { ws.subscribe(msg.topic); } catch { return; }
+					try { ws.subscribe(msg.topic); }
+					catch { closedWsAborts++; return; }
 					subs.add(msg.topic);
 					totalSubscriptions++;
 					if (wsDebug) console.log('[ws] subscribe topic=%s', msg.topic);
@@ -3171,7 +3271,8 @@ if (WS_ENABLED) {
 							sendSubscribeDenied(ws, topic, ref, 'RATE_LIMITED');
 							continue;
 						}
-						try { ws.subscribe(topic); } catch { continue; }
+						try { ws.subscribe(topic); }
+						catch { closedWsAborts++; continue; }
 						subs.add(topic);
 						totalSubscriptions++;
 						subscribed++;

package/index.d.ts

@@ -1202,6 +1202,14 @@ export interface Platform {
 	 * Send a message to a single WebSocket connection.
 	 * Wraps in the same `{ topic, event, data }` envelope as `publish()`.
 	 *
+	 * Returns the uWS send result: `0` = SUCCESS, `1` = BACKPRESSURE
+	 * (queued, will flush on drain), `2` = DROPPED (frame discarded
+	 * because the socket has closed or its queue is over the limit).
+	 *
+	 * Closed-WS safe: if the socket has already closed, returns `2`
+	 * (DROPPED) and bumps `platform.closedWsAborts` rather than
+	 * propagating uWS's "Invalid access" exception.
+	 *
 	 * @example
 	 * ```js
 	 * // In hooks.ws.js - reply to sender:
@@ -1310,6 +1318,36 @@ export interface Platform {
 	 */
 	readonly connections: number;
 
+	/**
+	 * Per-worker count of best-effort uWS operations that aborted
+	 * because the underlying WebSocket had already closed.
+	 *
+	 * Ws-targeted platform methods (`subscribe`, `unsubscribe`, `send`,
+	 * `sendCoalesced`, `sendTo`, `request`) and the wire-level
+	 * subscribe / subscribe-batch handlers swallow uWS's "Invalid
+	 * access of closed uWS.WebSocket" exception so callers never need
+	 * a per-site try/catch when a socket closes mid-async-setup.
+	 * Each swallow bumps this counter.
+	 *
+	 * A non-zero value is normal under client churn (browser tab close,
+	 * network blips, mass-reconnect waves). A rapidly-growing value
+	 * under steady load indicates either pathological client behaviour
+	 * or that the server's async setup path is too long for its
+	 * connect rate - worth investigating but not, on its own, a bug.
+	 *
+	 * Monotonic, per-worker, reset only on process restart. In
+	 * clustered mode, sum across workers to get the cluster total.
+	 *
+	 * @example
+	 * ```js
+	 * // periodic ops log
+	 * setInterval(() => {
+	 *   console.log('closed-ws aborts:', platform.closedWsAborts);
+	 * }, 60_000);
+	 * ```
+	 */
+	readonly closedWsAborts: number;
+
 	/**
 	 * Number of clients subscribed to a specific topic.
 	 *
@@ -1387,6 +1425,13 @@ export interface Platform {
 	 * hook may be async (the framework awaits the hook before inspecting
 	 * its return). Callers must `await` the result.
 	 *
+	 * Closed-WS safe: if the socket closes during the awaited hook (or
+	 * before the call, e.g. caller `await`-ed something else first) the
+	 * method silently returns `null` rather than propagating uWS's
+	 * "Invalid access of closed uWS.WebSocket" exception. Each abort
+	 * increments `platform.closedWsAborts`. Callers can fire-and-forget
+	 * without a per-site try/catch.
+	 *
 	 * @example
 	 * ```js
 	 * // In an RPC handler that needs to subscribe the connection
@@ -1456,6 +1501,9 @@ export interface Platform {
 	 * otherwise removes the subscription, decrements `totalSubscriptions`,
 	 * fires `hooks.ws.unsubscribe` (informational, not a gate - mirrors
 	 * the wire-level unsubscribe path), and returns `true`.
+	 *
+	 * Closed-WS safe: returns `false` and bumps `platform.closedWsAborts`
+	 * if the socket has already closed.
 	 */
 	unsubscribe(ws: WebSocket<unknown>, topic: string): boolean;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "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
@@ -213,9 +254,17 @@ export function createCursor(options = {}) {
 				const oldest = wsState.keys().next().value;
 				if (oldest !== undefined) wsState.delete(oldest);
 			}
+			let userData = {};
+			if (typeof ws.getUserData === 'function') {
+				// Closed-WS race: caller may reach here after an `await`
+				// that outlasted the socket; getUserData throws on a
+				// freed handle. Fall back to an empty userData rather
+				// than crashing the worker.
+				try { userData = ws.getUserData(); } catch { userData = {}; }
+			}
 			state = {
 				key: String(++connCounter),
-				user: select(typeof ws.getUserData === 'function' ? ws.getUserData() : {}),
+				user: select(userData),
 				topics: new Set()
 			};
 			wsState.set(ws, state);
@@ -224,14 +273,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 +312,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 +329,77 @@ 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 claims the cadence slot synchronously (lastFlush =
+	 * now) but defers the actual flush by one microtask so co-arriving
+	 * broadcasts in the same JS pass batch into a single bulk frame.
+	 * Without the microtask defer, an event-loop pause > topicThrottleMs
+	 * caused the post-pause first cursor to fire alone (single-cursor
+	 * UPDATE) while every other cursor in the same burst queued to the
+	 * trailing tick: under sustained pressure (30K RPCs/sec/worker) this
+	 * fragmented 86% of cursor frames into single-cursor UPDATEs.
+	 * Microtasks run after the current synchronous code completes but
+	 * before the next I/O / setTimeout / event-loop tick, so any
+	 * subsequent broadcast() in the same handler batch adds itself to
+	 * `dirty` before the flush runs.
+	 *
+	 * Trailing-edge fires via the single tracker-wide `tickTimer` for
+	 * broadcasts that land mid-window.
 	 */
 	function broadcast(topic, key, data, platform) {
 		if (topicThrottleMs <= 0) {
@@ -290,34 +409,31 @@ 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, pendingMicroflush: false };
 			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);
+			// Schedule once per cycle slot; subsequent broadcasts inside
+			// the same microtask boundary just append to `state.dirty`.
+			if (!state.pendingMicroflush) {
+				state.pendingMicroflush = true;
+				queueMicrotask(() => {
+					state.pendingMicroflush = false;
+					if (state.dirty.size === 0) return;
+					flushDirty(topic, state.dirty);
+					state.dirty.clear();
+				});
+			}
 			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 +576,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/groups/server.js

@@ -168,7 +168,15 @@ export function createGroup(name, options = {}) {
 			// Publish join BEFORE subscribing so joiner doesn't see own join
 			platform.publish(internalTopic, 'join', { role, count: members.size });
 
-			ws.subscribe(internalTopic);
+			// Callers reach `join` after their own async auth chain; the
+			// socket may have closed in the meantime. Roll back the
+			// member entry instead of letting uWS's "Invalid access"
+			// crash the worker.
+			try { ws.subscribe(internalTopic); }
+			catch {
+				members.delete(ws);
+				return false;
+			}
 
 			// Send current member list to the joiner
 			platform.send(ws, internalTopic, 'members', membersList());

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,10 +5,17 @@
  * 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
  */
@@ -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;

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);
 		}
@@ -427,7 +443,13 @@ export function createPresence(options = {}) {
 			let connTopics = wsTopics.get(ws);
 			if (connTopics && connTopics.has(topic)) return;
 
-			const data = select(ws.getUserData());
+			// Callers typically reach here after an `await` in their own
+			// join flow (auth, loader, RPC handshake). If the socket
+			// closed mid-await `getUserData()` throws; presence is a
+			// best-effort layer, so silently no-op rather than crash.
+			let userData;
+			try { userData = ws.getUserData(); } catch { return; }
+			const data = select(userData);
 			if (!data || typeof data !== 'object') {
 				throw new TypeError(
 					`presence select() must return a plain object, got ${data === null ? 'null' : typeof data}`
@@ -476,8 +498,10 @@ export function createPresence(options = {}) {
 				bufferDiff(topic, 'join', key, data, platform);
 			}
 
-			// Subscribe this ws to the presence channel (server-side, idempotent)
-			ws.subscribe(presenceTopic);
+			// Subscribe this ws to the presence channel (server-side, idempotent).
+			// `platform.send` is closed-ws-safe on the adapter side; the
+			// direct `ws.subscribe` is not - guard locally.
+			try { ws.subscribe(presenceTopic); } catch { return; }
 
 			// Send the full current snapshot to this connection. The joining
 			// user sees the complete state (including themselves) immediately;
@@ -502,7 +526,7 @@ export function createPresence(options = {}) {
 			capturePlatform(platform);
 			const users = topicPresence.get(topic);
 			const presenceTopic = TOPIC_PREFIX + topic;
-			ws.subscribe(presenceTopic);
+			try { ws.subscribe(presenceTopic); } catch { return; }
 			platform.send(ws, presenceTopic, 'presence_state', snapshotState(users));
 		},
 

package/testing.js

@@ -150,16 +150,25 @@ export async function createTestServer(options = {}) {
 
 	const closeHookRegisteredT = !!handler.close;
 	let sendToAsyncWarnedT = false;
+	// Mirrors prod's `closedWsAborts`. createTestServer uses real uWS,
+	// so a closed-WS race (subscribe gate awaits something, client
+	// closes during the await, post-await ws.subscribe throws) is
+	// exercisable here exactly like in production. Hardening below
+	// catches the uWS exception, bumps this counter, and returns the
+	// platform's success-shaped no-op sentinel.
+	let closedWsAbortsT = 0;
 	function bumpInT(ws, message) {
 		if (!closeHookRegisteredT) return;
-		const stats = ws.getUserData()[WS_STATS];
+		let stats;
+		try { stats = ws.getUserData()[WS_STATS]; } catch { return; }
 		if (!stats) return;
 		stats.messagesIn++;
 		stats.bytesIn += typeof message === 'string' ? message.length : message.byteLength;
 	}
 	function bumpOutT(ws, payload) {
 		if (!closeHookRegisteredT) return;
-		const stats = ws.getUserData()[WS_STATS];
+		let stats;
+		try { stats = ws.getUserData()[WS_STATS]; } catch { return; }
 		if (!stats) return;
 		stats.messagesOut++;
 		stats.bytesOut += payload.length;
@@ -186,12 +195,15 @@ export async function createTestServer(options = {}) {
 		const delay = chaos.getDelayMs();
 		if (delay > 0) {
 			setTimeout(() => {
-				try { ws.send(payload, false, false); } catch {}
+				try { ws.send(payload, false, false); }
+				catch { closedWsAbortsT++; return; }
 				bumpOutT(ws, payload);
 			}, delay);
 			return 1;
 		}
-		const result = ws.send(payload, false, false);
+		let result;
+		try { result = ws.send(payload, false, false); }
+		catch { closedWsAbortsT++; return 2; }
 		bumpOutT(ws, payload);
 		return result;
 	}
@@ -225,7 +237,10 @@ export async function createTestServer(options = {}) {
 			const msg = envelope(topic, event, data);
 			let count = 0;
 			for (const ws of wsConnections) {
-				const decision = filter(ws.getUserData());
+				let userData;
+				try { userData = ws.getUserData(); }
+				catch { closedWsAbortsT++; continue; }
+				const decision = filter(userData);
 				if (decision && typeof decision.then === 'function') {
 					if (!sendToAsyncWarnedT) {
 						sendToAsyncWarnedT = true;
@@ -247,6 +262,7 @@ export async function createTestServer(options = {}) {
 		},
 		get connections() { return wsConnections.size; },
 		get assertions() { return readAssertionCounts(); },
+		get closedWsAborts() { return closedWsAbortsT; },
 		subscribers(topic) { return app.numSubscribers(topic); },
 		// Mirror production: report a numeric cap and a constant-time
 		// bufferedAmount so test code can exercise the same backpressure-
@@ -264,7 +280,9 @@ export async function createTestServer(options = {}) {
 			// user hook so async hooks gate correctly.
 			// Server-side caller: trust non-ASCII topics (matches platform.subscribe in production).
 			if (!isValidWireTopic(topic, true)) return 'INVALID_TOPIC';
-			const subs = ws.getUserData()[WS_SUBSCRIPTIONS];
+			let subs;
+			try { subs = ws.getUserData()[WS_SUBSCRIPTIONS]; }
+			catch { closedWsAbortsT++; return null; }
 			if (!(subs instanceof Set)) return 'INVALID_TOPIC';
 			if (subs.has(topic)) return null;
 			if (subs.size >= MAX_SUBSCRIPTIONS_PER_CONNECTION) return 'RATE_LIMITED';
@@ -272,7 +290,8 @@ export async function createTestServer(options = {}) {
 			if (denial !== null) return denial;
 			if (subs.has(topic)) return null;
 			if (subs.size >= MAX_SUBSCRIPTIONS_PER_CONNECTION) return 'RATE_LIMITED';
-			ws.subscribe(topic);
+			try { ws.subscribe(topic); }
+			catch { closedWsAbortsT++; return null; }
 			subs.add(topic);
 			return null;
 		},
@@ -282,9 +301,12 @@ export async function createTestServer(options = {}) {
 			return await runUserSubscribeGateT(ws, topic);
 		},
 		unsubscribe(ws, topic) {
-			const subs = ws.getUserData()[WS_SUBSCRIPTIONS];
+			let subs;
+			try { subs = ws.getUserData()[WS_SUBSCRIPTIONS]; }
+			catch { closedWsAbortsT++; return false; }
 			if (!(subs instanceof Set) || !subs.has(topic)) return false;
-			ws.unsubscribe(topic);
+			try { ws.unsubscribe(topic); }
+			catch { closedWsAbortsT++; return false; }
 			subs.delete(topic);
 			handler.unsubscribe?.(ws, topic, { platform: ws.getUserData()[WS_PLATFORM] });
 			return true;
@@ -370,7 +392,12 @@ export async function createTestServer(options = {}) {
 			app.publish(fanoutTopic, sharedBatchEnv, false, false);
 		},
 		request(ws, event, data, options) {
-			const userData = ws.getUserData();
+			let userData;
+			try { userData = ws.getUserData(); }
+			catch {
+				closedWsAbortsT++;
+				return Promise.reject(new Error('connection closed'));
+			}
 			let pending = userData[WS_PENDING_REQUESTS];
 			if (!pending) {
 				pending = new Map();
@@ -390,7 +417,21 @@ export async function createTestServer(options = {}) {
 				}, timeoutMs);
 				pending.set(ref, { resolve, reject, timer });
 				const payload = JSON.stringify({ type: 'request', ref, event, data: data ?? null });
-				sendOutboundT(ws, payload);
+				// Direct ws.send so we can distinguish "closed WS"
+				// (throws -> reject now) from "backpressure DROPPED"
+				// (returns 2 -> let it time out, matches production
+				// semantics where uWS will not retry on its own).
+				// sendOutboundT exists for chaos-injection; the request
+				// flow takes the bare path and re-uses bumpOutT.
+				try { ws.send(payload, false, false); }
+				catch {
+					closedWsAbortsT++;
+					clearTimeout(timer);
+					pending.delete(ref);
+					reject(new Error('connection closed'));
+					return;
+				}
+				bumpOutT(ws, payload);
 			});
 		},
 		topic(name) {
@@ -623,7 +664,8 @@ export async function createTestServer(options = {}) {
 								sendDeniedT(ws, msg.topic, ref, 'RATE_LIMITED');
 								return;
 							}
-							ws.subscribe(msg.topic);
+							try { ws.subscribe(msg.topic); }
+							catch { closedWsAbortsT++; return; }
 							subs.add(msg.topic);
 							sendSubscribedT(ws, msg.topic, ref);
 							return;
@@ -680,7 +722,8 @@ export async function createTestServer(options = {}) {
 									sendDeniedT(ws, topic, ref, 'RATE_LIMITED');
 									continue;
 								}
-								ws.subscribe(topic);
+								try { ws.subscribe(topic); }
+								catch { closedWsAbortsT++; continue; }
 								udSubs.add(topic);
 								sendSubscribedT(ws, topic, ref);
 							}

package/vite.js

@@ -398,6 +398,13 @@ export default function uws(options = {}) {
 			// see the documented "no violations" state.
 			return new Map();
 		},
+		get closedWsAborts() {
+			// Dev uses Node's `ws` library, not uWS - sockets do not
+			// throw "Invalid access" when written to after close, so
+			// the closed-WS abort path doesn't exist here. Mirror the
+			// prod surface as a constant zero.
+			return 0;
+		},
 		subscribers(topic) {
 			let count = 0;
 			for (const [, topics] of subscriptions) {