svelte-adapter-uws 0.5.7 → 0.6.0-next.1

package/README.md

@@ -2815,6 +2815,16 @@ Positions live on the `update` / `bulk` channel; user metadata lives on the `cat
 
 The cluster-aware [extensions](https://github.com/lanteanio/svelte-adapter-uws-extensions) Redis-backed cursor speaks the same wire format, so the same client bundle works against either backend.
 
+#### Binary wire mode
+
+Cursor frames ride a compact **binary wire** by default. The events above are the same; on the wire they are encoded as a binary `0x03` frame instead of a JSON envelope whenever the client supports it. A 221-cursor coalesced `bulk` is **~83% smaller** than the JSON equivalent and decodes ~4-5x faster (no `JSON.parse` on the cursor receive path). This is fully transparent: `cursor()` / `move()` are unchanged, the store still yields `Map<key, { user, data }>`, and the decode happens in the framework before your code sees the event.
+
+- **Capability-gated, never breaking.** The client advertises `cursor.protocol:2` in its `hello` frame; a client that does not (an older build, or one that opted out) receives the JSON frames unchanged. Old client <-> new server and new client <-> old server both keep working.
+- **`binary: false` to disable.** `createCursor({ binary: false })` forces JSON for every client (e.g. to keep DevTools' WS inspector readable). The wire format is the server's decision - the library reads no URL parameter and a client cannot force its own connection back to JSON, so it can't be used to inflate egress.
+- **Positions are `float32`, keys are length-prefixed strings.** Fractional positions (e.g. `clientX - getBoundingClientRect().left`) are carried losslessly enough for cursors (sub-0.01 px at screen scale). Cursor `data` that is not exactly `{ x, y }` numeric - extra fields, non-numeric values - transparently falls back to JSON for that frame, so richer cursor payloads keep working.
+
+Writing your own high-throughput plugin? The same mechanism is available via `platform.publishWire(topic, event, data, wire)` / `platform.sendWire(...)` on the server (where `wire = { capability, schemaVersion, encode(event, data) }` and `encode` returns a `Uint8Array` payload or `null` to fall back to JSON), plus `registerWireCodec(prefix, { capability, decode })` from `svelte-adapter-uws/client` on the client. JSON-only deployments pay nothing - `publishWire` takes the same single broadcast as `publish` when no connected client wants binary.
+
 #### Server usage
 
 Use the `hooks` helper for zero-config cursor handling. The `message` hook handles `cursor` and `cursor-snapshot` messages automatically, and `close` calls `remove()`. The hooks verify that the sender is subscribed to the `__cursor:{topic}` channel before processing - clients that haven't passed the `subscribe` hook for that topic are silently rejected.

package/client.d.ts

@@ -640,3 +640,25 @@ export interface WSConnection {
  * ```
  */
 export function connect(options?: ConnectOptions): WSConnection;
+
+/**
+ * Register a client-side binary wire codec for a topic-name prefix. This is a
+ * plugin-author surface, not an app-author one - a plugin (e.g. the cursor
+ * client) calls it at import time. The connection then advertises
+ * `codec.capability` in its `hello` frame and routes inbound binary `0x03`
+ * frames whose resolved topic starts with `prefix` to `codec.decode`, which
+ * must return the same `{ event, data }` the JSON path would have dispatched
+ * (or `null` to drop a malformed frame). Idempotent per prefix. A client
+ * always advertises what it can decode; whether a topic is actually sent as
+ * binary is the server's decision (the plugin's codec, or `binary: false`).
+ *
+ * @param prefix - topic-name prefix the codec owns (e.g. `'__cursor:'`)
+ * @param codec - `{ capability, decode }`
+ */
+export function registerWireCodec(
+	prefix: string,
+	codec: {
+		capability: string;
+		decode: (payload: Uint8Array) => { event: string; data: unknown } | null;
+	}
+): void;

package/client.js

@@ -1,4 +1,5 @@
 import { writable, derived } from 'svelte/store';
+import { parseBinaryFrame } from './files/wire.js';
 
 /** @type {ReturnType<typeof createConnection> | null} */
 let singleton = null;
@@ -6,6 +7,63 @@ let singleton = null;
 /** @type {'explicit' | 'implicit' | ''} */
 let singletonCreatedBy = '';
 
+/**
+ * Client-side binary wire codecs, keyed by topic-name prefix. A plugin (e.g.
+ * the cursor client) registers its decoder + capability here at import time;
+ * the connection then advertises those capabilities in its `hello` frame and
+ * routes inbound `0x03` frames whose resolved topic matches a prefix to the
+ * matching decoder. The decoder returns the same `{ event, data }` the JSON
+ * path would have dispatched, so the reactive surface is identical.
+ * @type {Map<string, { capability: string, decode: (payload: Uint8Array) => ({ event: string, data: any } | null) }>}
+ */
+const wireCodecs = new Map();
+
+/**
+ * Register a binary wire codec for a topic-name prefix. Idempotent per prefix.
+ * Plugins call this at module load (before connect) so the first `hello`
+ * already advertises the capability; if a connection is already open, its
+ * `hello` is re-sent so a lazily-imported plugin still negotiates binary.
+ *
+ * @param {string} prefix - topic-name prefix the codec owns (e.g. '__cursor:')
+ * @param {{ capability: string, decode: (payload: Uint8Array) => ({ event: string, data: any } | null) }} codec
+ */
+export function registerWireCodec(prefix, codec) {
+	wireCodecs.set(prefix, codec);
+	if (singleton && typeof singleton._resendHello === 'function') singleton._resendHello();
+}
+
+/**
+ * Build the `hello` caps array: `'batch'` plus every registered binary wire
+ * capability. A client always advertises what it can decode; the wire format
+ * is the server's decision (a plugin's codec, or `binary: false` to force
+ * JSON). We deliberately do NOT read any URL query parameter to opt out - the
+ * app owns its URL namespace, and a client-side force-JSON knob would let a
+ * connection inflate its own egress.
+ * @returns {string[]}
+ */
+function buildHelloCaps() {
+	const caps = ['batch'];
+	for (const codec of wireCodecs.values()) caps.push(codec.capability);
+	return caps;
+}
+
+/**
+ * Resolve a topic name to its registered wire codec by longest matching prefix.
+ * @param {string} topic
+ * @returns {{ capability: string, decode: (payload: Uint8Array) => ({ event: string, data: any } | null) } | null}
+ */
+function wireCodecForTopic(topic) {
+	let best = null;
+	let bestLen = -1;
+	for (const [prefix, codec] of wireCodecs) {
+		if (topic.startsWith(prefix) && prefix.length > bestLen) {
+			best = codec;
+			bestLen = prefix.length;
+		}
+	}
+	return best;
+}
+
 /**
  * Ensure the singleton connection exists.
  * @param {import('./client.js').ConnectOptions} [options]
@@ -707,6 +765,14 @@ function createConnection(options) {
 	/** @type {Map<string, number>} */
 	const topicRefCounts = new Map();
 
+	// Inverse of the server's per-connection topic-id map: numeric wireId ->
+	// topic name. Populated from `{type:'wire-id'}` control frames; an inbound
+	// `0x03` binary frame carries only the numeric id, resolved here back to the
+	// topic name the store ladder is keyed on. Per-connection: cleared on each
+	// (re)connect since the server reassigns ids fresh on a new connection.
+	/** @type {Map<number, string>} */
+	const wireIdMap = new Map();
+
 	// Highest seq seen per topic. Sent back to the server on reconnect via
 	// the resume frame so the user's resume hook can replay anything we
 	// missed during the disconnect window. Only topics that the server is
@@ -983,6 +1049,14 @@ function createConnection(options) {
 			scheduleReconnect();
 			return;
 		}
+		// Read inbound binary frames as ArrayBuffer (default is Blob, which is
+		// async to read). Cannot regress the realtime upload layer: that layer
+		// only EMITS binary (0x01/0x02) and receives upload results as JSON on
+		// the '__upload' topic - it never reads an inbound binary frame.
+		ws.binaryType = 'arraybuffer';
+		// Topic-ids are per-connection; the server reassigns them on a fresh
+		// connection, so drop any stale id -> name mappings from a prior socket.
+		wireIdMap.clear();
 
 		ws.onopen = () => {
 			attempt = 0;
@@ -992,10 +1066,12 @@ function createConnection(options) {
 			if (debug) console.log('[ws] connected');
 
 			// Advertise client capabilities. Server stores these on the
-			// connection's userData and uses them to gate opt-in wire
-			// features (currently: 'batch' for platform.publishBatched
-			// frames). Old servers ignore the unknown frame type.
-			ws?.send('{"type":"hello","caps":["batch"]}');
+			// connection's userData and uses them to gate opt-in wire features:
+			// 'batch' for publishBatched frames, plus any registered binary wire
+			// codec capabilities (e.g. 'cursor.protocol:2'). A client always
+			// advertises what it can decode; the wire format is the server's
+			// call. Old servers ignore the unknown frame type.
+			ws?.send(JSON.stringify({ type: 'hello', caps: buildHelloCaps() }));
 
 			// If we have a previous session id and any tracked seqs, ask the
 			// server to fill the gap before we resubscribe. The server's
@@ -1057,6 +1133,36 @@ function createConnection(options) {
 		ws.onmessage = (rawEvent) => {
 			lastServerMessage = Date.now();
 			try {
+				// Inbound binary demux, ahead of the JSON path. A 0x03 frame is
+				// a binary topic PAYLOAD: resolve its numeric topic-id to a name,
+				// decode via the registered codec, and feed the SAME
+				// dispatchEvent the JSON path uses so the reactive surface is
+				// byte-for-byte identical (zero JSON.parse on this hot path).
+				// Any other binary frame (the realtime layer's outbound-only
+				// 0x01/0x02, or a malformed frame) is dropped. Binary frames
+				// never fall through to JSON.parse.
+				if (rawEvent.data instanceof ArrayBuffer) {
+					if (rawEvent.data.byteLength > 1048576) {
+						if (debug) console.warn('[ws] binary frame too large, dropped:', rawEvent.data.byteLength, 'bytes');
+						return;
+					}
+					const parsed = parseBinaryFrame(new Uint8Array(rawEvent.data));
+					if (parsed) {
+						const topic = wireIdMap.get(parsed.topicId);
+						if (topic !== undefined) {
+							const codec = wireCodecForTopic(topic);
+							const decoded = codec ? codec.decode(parsed.payload) : null;
+							if (decoded) {
+								const out = { topic, event: decoded.event, data: decoded.data };
+								if (parsed.seq > 0) out.seq = parsed.seq;
+								dispatchEvent(out);
+							}
+						} else if (debug) {
+							console.warn('[ws] 0x03 frame for unknown topicId', parsed.topicId);
+						}
+					}
+					return;
+				}
 				// Reject oversized messages to prevent main-thread blocking
 				if (typeof rawEvent.data === 'string' && rawEvent.data.length > 1048576) {
 					if (debug) console.warn('[ws] message too large, dropped:', rawEvent.data.length, 'bytes');
@@ -1093,6 +1199,15 @@ function createConnection(options) {
 					if (debug) console.log('[ws] subscribed topic=%s ref=%s', msg.topic, msg.ref);
 					return;
 				}
+				if (msg.type === 'wire-id' && typeof msg.topic === 'string' && typeof msg.id === 'number') {
+					// Server announced a binary topic-id assignment. Record the
+					// inverse mapping so a subsequent 0x03 frame's numeric id
+					// resolves to this topic name. Arrives before the first
+					// binary frame for the topic (same socket, ordered).
+					wireIdMap.set(msg.id, msg.topic);
+					if (debug) console.log('[ws] wire-id topic=%s id=%d', msg.topic, msg.id);
+					return;
+				}
 				if (msg.type === 'subscribe-denied' && typeof msg.topic === 'string' && typeof msg.reason === 'string') {
 					console.warn('[ws] subscribe denied topic=%s reason=%s\n  See: https://svti.me/subscribe-denied', msg.topic, msg.reason);
 					denialsStore.set({ topic: msg.topic, reason: msg.reason, ref: msg.ref });
@@ -1562,6 +1677,16 @@ function createConnection(options) {
 		return () => { if (requestHandler === handler) requestHandler = null; };
 	}
 
+	// Re-advertise capabilities on an already-open socket. Called by
+	// registerWireCodec when a binary plugin is imported after connect so its
+	// capability still reaches the server (the common case - import before
+	// connect - is covered by buildHelloCaps() reading the registry at open).
+	function resendHello() {
+		if (ws && ws.readyState === WebSocket.OPEN) {
+			ws.send(JSON.stringify({ type: 'hello', caps: buildHelloCaps() }));
+		}
+	}
+
 	return {
 		events: { subscribe: eventsStore.subscribe },
 		status: { subscribe: statusStore.subscribe },
@@ -1584,6 +1709,7 @@ function createConnection(options) {
 		// mark and back off until it drops below a low-water mark.
 		get bufferedAmount() { return ws?.bufferedAmount ?? 0; },
 		onRequest,
+		_resendHello: resendHello,
 		close
 	};
 }

package/files/handler.js

@@ -22,7 +22,8 @@ import { env } from 'ENV';
 import { server } from './_init.js';
 import * as wsModule from 'WS_HANDLER';
 import { parseCookies, createCookies } from './cookies.js';
-import { mimeLookup, parse_as_bytes, parse_origin, writeChunkWithBackpressure, drainCoalesced, computePressureReason, computeTopPublishers, nextTopicSeq, completeEnvelope, wrapBatchEnvelope, collapseByCoalesceKey, esc, isValidWireTopic, createScopedTopic, isOriginAllowed, isAuthOriginAccepted, describeUnsafeSameOriginConfig, createUpgradeAdmission, resolveRequestId, assert, readAssertionCounts, WS_SUBSCRIPTIONS, WS_COALESCED, WS_SESSION_ID, WS_PENDING_REQUESTS, WS_STATS, WS_PLATFORM, WS_REQUEST_ID_KEY, WS_CAPS, MAX_SUBSCRIPTIONS_PER_CONNECTION, MAX_PENDING_REQUESTS_PER_CONNECTION, MAX_COALESCED_KEYS_PER_CONNECTION, TOPIC_SEQS_WARN_THRESHOLD, PUBLISH_WARN_DEDUP_MAX } from './utils.js';
+import { mimeLookup, parse_as_bytes, parse_origin, writeChunkWithBackpressure, drainCoalesced, computePressureReason, computeTopPublishers, nextTopicSeq, completeEnvelope, wrapBatchEnvelope, collapseByCoalesceKey, esc, isValidWireTopic, createScopedTopic, isOriginAllowed, isAuthOriginAccepted, describeUnsafeSameOriginConfig, createUpgradeAdmission, resolveRequestId, assert, readAssertionCounts, WS_SUBSCRIPTIONS, WS_COALESCED, WS_SESSION_ID, WS_PENDING_REQUESTS, WS_STATS, WS_PLATFORM, WS_REQUEST_ID_KEY, WS_CAPS, WS_TOPIC_IDS, MAX_SUBSCRIPTIONS_PER_CONNECTION, MAX_PENDING_REQUESTS_PER_CONNECTION, MAX_COALESCED_KEYS_PER_CONNECTION, TOPIC_SEQS_WARN_THRESHOLD, PUBLISH_WARN_DEDUP_MAX } from './utils.js';
+import { buildBinaryFrame, allocWireId, wireIdAnnounce, createCapCounts } from './wire.js';
 
 /* global ENV_PREFIX */
 /* global PRECOMPRESS */
@@ -366,12 +367,24 @@ const app = is_tls
 	: uWS.App();
 
 // - Cross-worker pub/sub relay (batched) ------------------------------------
-// Batch postMessage calls within a single microtask. A SvelteKit action that
-// publishes N events sends one structured-clone across the thread boundary
-// instead of N. No-op in single-process mode (parentPort is null).
+// Batch postMessage calls within a single event-loop iteration. A SvelteKit
+// action that publishes N events sends one structured-clone across the thread
+// boundary instead of N. No-op in single-process mode (parentPort is null).
+//
+// Why `setTimeout(0)` and not `queueMicrotask`: uWS dispatches each WS message
+// as its own JS task, and N-API drains microtasks at the C++/JS boundary
+// between tasks. A microtask-deferred flush fires BEFORE the next socket's
+// handler runs, so cross-socket coalescing is impossible at the microtask
+// level - N publishes from N socket handlers in the same iteration produce N
+// postMessage structured-clones instead of one batched. `setTimeout(0)` lands
+// in libuv's timers phase, which fires only after the poll phase has
+// dispatched every ready socket message in the current iteration. Same
+// structural choice the 0.5.6 cursor always-tick rewrite locked in.
 
 /** @type {Array<{topic: string, envelope: string}> | null} */
 let relayBatch = null;
+/** @type {ReturnType<typeof setTimeout> | null} */
+let relayTimer = null;
 
 /**
  * @param {string} topic
@@ -380,12 +393,14 @@ let relayBatch = null;
 function batchRelay(topic, envelope) {
 	if (!relayBatch) {
 		relayBatch = [];
-		queueMicrotask(() => {
+		relayTimer = setTimeout(() => {
+			relayTimer = null;
 			if (relayBatch) {
 				parentPort.postMessage({ type: 'publish-batch', messages: relayBatch });
 			}
 			relayBatch = null;
-		});
+		}, 0);
+		if (relayTimer.unref) relayTimer.unref();
 	}
 	relayBatch.push({ topic, envelope });
 }
@@ -898,6 +913,40 @@ function flushCoalescedFor(ws) {
 	if (aborted) pending.clear();
 }
 
+// - Binary wire (0x03) capability accounting + topic-id assignment ----------
+// A connection opts into a binary plugin codec by advertising the codec's
+// capability token in its `hello` frame (stored in WS_CAPS). capCounts tracks
+// how many live connections advertised each token, so platform.publishWire
+// takes a zero-cost JSON fast path when no connected client wants binary for a
+// codec - a JSON-only deployment never enters the per-subscriber walk. The
+// id-allocation, announce-frame, and cap-counting primitives are shared with
+// the test / dev platforms via ./wire.js so the id space is identical.
+const capCounts = createCapCounts();
+
+/**
+ * Resolve (allocating on first use) the per-connection binary topic-id for a
+ * topic. On a fresh assignment, announce the `name -> id` mapping to the
+ * client in a `{type:'wire-id'}` control frame so an inbound `0x03` frame's
+ * numeric id resolves back to the topic name. The announce rides the same
+ * socket immediately before the first binary frame for the topic, so ordering
+ * guarantees the client records the mapping first - no ack/frame race.
+ * Per-connection and reset on reconnect (a reconnect is a new connection with
+ * fresh userData).
+ * @param {import('uWebSockets.js').WebSocket<any>} ws
+ * @param {any} ud - ws.getUserData()
+ * @param {string} topic
+ * @returns {number}
+ */
+function ensureWireId(ws, ud, topic) {
+	const { id, isNew } = allocWireId(ud, WS_TOPIC_IDS, topic);
+	if (isNew) {
+		const announce = wireIdAnnounce(topic, id);
+		try { ws.send(announce, false, false); } catch { closedWsAborts++; return id; }
+		bumpOut(ws, announce);
+	}
+	return id;
+}
+
 /** @type {import('./index.js').Platform} */
 const platform = {
 	/**
@@ -965,6 +1014,126 @@ const platform = {
 		return result;
 	},
 
+	/**
+	 * Publish via a plugin-declared binary wire codec. Binary-capable
+	 * subscribers (those that advertised `wire.capability`) receive a `0x03`
+	 * frame; everyone else receives the identical JSON envelope `publish()`
+	 * would have sent. When no connected client advertises the capability - or
+	 * the codec declines this frame (`encode` returns null) - this takes the
+	 * exact single `app.publish` JSON fan-out with no per-subscriber walk, so a
+	 * JSON-only deployment pays nothing for the binary machinery.
+	 *
+	 * The framework owns the `0x03 | schemaVersion | topicId | seq | payload`
+	 * envelope; the plugin's `encode` produces only the payload. seq is stamped
+	 * once and carried in both the JSON and binary forms so resume keeps working.
+	 *
+	 * @param {string} topic
+	 * @param {string} event
+	 * @param {any} data
+	 * @param {{ capability: string, schemaVersion: number, encode: (event: string, data: any) => (Uint8Array | null) }} wire
+	 * @param {{ seq?: boolean, relay?: boolean }} [options]
+	 * @returns {boolean}
+	 */
+	publishWire(topic, event, data, wire, options) {
+		publishCountWindow++;
+		const seq = (options && options.seq === false)
+			? null
+			: nextTopicSeq(topicSeqs, topic);
+		const envelope = completeEnvelope(envelopePrefix(topic, event), data, seq);
+		assert(envelope.length > 0, 'envelope.empty', { topic, event });
+		let s = topicPublishStats.get(topic);
+		if (!s) {
+			s = { m: 0, b: 0 };
+			topicPublishStats.set(topic, s);
+			maybeWarnTopicRegistry();
+		} else {
+			assert(typeof s.m === 'number' && typeof s.b === 'number', 'topic.stats-shape', { topic });
+		}
+		s.m++;
+		s.b += envelope.length;
+
+		// Encode once - but only when at least one live connection wants binary
+		// for this codec. A null payload (no capable client, or the codec
+		// declined this frame) falls through to the single C++ app.publish
+		// fan-out, byte- and instruction-identical to platform.publish.
+		const payload = capCounts.has(wire.capability) ? wire.encode(event, data) : null;
+		const relayed = !!(parentPort && (!options || options.relay !== false));
+		if (payload == null) {
+			const result = app.publish(topic, envelope, false, false);
+			if (relayed) batchRelay(topic, envelope);
+			return result || relayed;
+		}
+
+		// Mixed-capability fan-out: app.publish cannot vary payload per
+		// recipient, so walk the topic's subscribers and send each the form it
+		// negotiated. The codec payload is shared across recipients; only the
+		// tiny per-connection frame header (topic-id + seq) differs, memoized
+		// per distinct id so the common all-same-id case builds one frame and
+		// reuses it for every binary send.
+		const seqOnWire = seq == null ? 0 : seq;
+		/** @type {Map<number, Uint8Array>} */
+		const frameById = new Map();
+		for (const ws of wsConnections) {
+			let ud;
+			try { ud = ws.getUserData(); } catch { continue; }
+			const subs = ud[WS_SUBSCRIPTIONS];
+			if (!subs || !subs.has(topic)) continue;
+			const caps = ud[WS_CAPS];
+			if (caps && caps.has(wire.capability)) {
+				const id = ensureWireId(ws, ud, topic);
+				let frame = frameById.get(id);
+				if (!frame) {
+					frame = buildBinaryFrame(wire.schemaVersion, id, seqOnWire, payload);
+					frameById.set(id, frame);
+				}
+				try { ws.send(frame, true, false); } catch { closedWsAborts++; }
+			} else {
+				try { ws.send(envelope, false, false); } catch { closedWsAborts++; }
+			}
+		}
+		// Cross-worker subscribers receive the JSON envelope (binary is
+		// same-worker only); their worker re-publishes it to them as JSON.
+		if (relayed) batchRelay(topic, envelope);
+		if (wsDebug) {
+			console.log('[ws] publishWire topic=%s event=%s payloadBytes=%d', topic, event, payload.length);
+		}
+		return true;
+	},
+
+	/**
+	 * Single-target send via a plugin-declared binary wire codec. The target
+	 * receives a `0x03` frame when it advertised `wire.capability` and the
+	 * codec can encode this frame; otherwise it receives the JSON envelope
+	 * `send()` would have sent. No seq is stamped (matches `send()`); the
+	 * binary frame carries seq 0 ("no seq"). Used for snapshot/catalog frames.
+	 *
+	 * @param {import('uWebSockets.js').WebSocket<any>} ws
+	 * @param {string} topic
+	 * @param {string} event
+	 * @param {any} data
+	 * @param {{ capability: string, schemaVersion: number, encode: (event: string, data: any) => (Uint8Array | null) }} wire
+	 * @returns {number} uWS send status (0/1/2), or 2 on a freed handle
+	 */
+	sendWire(ws, topic, event, data, wire) {
+		let ud;
+		try { ud = ws.getUserData(); } catch { closedWsAborts++; return 2; }
+		const caps = ud[WS_CAPS];
+		const payload = (caps && caps.has(wire.capability)) ? wire.encode(event, data) : null;
+		if (payload == null) {
+			const json = envelopePrefix(topic, event) + JSON.stringify(data ?? null) + '}';
+			let result;
+			try { result = ws.send(json, false, false); } catch { closedWsAborts++; return 2; }
+			bumpOut(ws, json);
+			return result;
+		}
+		const id = ensureWireId(ws, ud, topic);
+		const frame = buildBinaryFrame(wire.schemaVersion, id, 0, payload);
+		let result;
+		try { result = ws.send(frame, true, false); } catch { closedWsAborts++; return 2; }
+		bumpOut(ws, frame);
+		return result;
+	},
+
 	/**
 	 * Send a message to a single connection with coalesce-by-key semantics.
 	 *
@@ -3307,7 +3476,12 @@ if (WS_ENABLED) {
 					for (let i = 0; i < msg.caps.length; i++) {
 						if (typeof msg.caps[i] === 'string') caps.add(msg.caps[i]);
 					}
-					ws.getUserData()[WS_CAPS] = caps;
+					const ud = ws.getUserData();
+					// Maintain the live per-capability connection counts so the
+					// binary publish fast path knows whether any client wants
+					// binary. A re-sent hello replaces the prior set; diff it.
+					capCounts.adjust(ud[WS_CAPS], caps);
+					ud[WS_CAPS] = caps;
 					if (wsDebug) console.log('[ws] hello caps=%o', [...caps]);
 					return;
 				}
@@ -3398,6 +3572,9 @@ if (WS_ENABLED) {
 			} finally {
 				totalSubscriptions -= subscriptions.size;
 				assert(totalSubscriptions >= 0, 'subs.total-negative', { totalSubscriptions });
+				// Release this connection's advertised capabilities from the
+				// live counts so the binary publish fast path stays accurate.
+				capCounts.adjust(userData[WS_CAPS], null);
 				wsConnections.delete(ws);
 				if (wsDebug) console.log('[ws] close code=%d connections=%d', code, wsConnections.size);
 			}

package/files/utils.js

@@ -404,6 +404,18 @@ export const WS_PLATFORM = Symbol.for('adapter-uws.ws.platform');
  */
 export const WS_CAPS = Symbol.for('adapter-uws.ws.caps');
 
+/**
+ * Per-connection binary wire-id allocation for `0x03` topic frames:
+ * `{ byName: Map<topicName, number>, next: number }`. Allocated lazily on the
+ * first binary publish to a connection (never for JSON-only connections, so
+ * the common case pays nothing). The id replaces the topic string on the wire;
+ * the server announces each `name -> id` assignment to the client in a
+ * `{type:'wire-id'}` control frame the first time it emits a binary frame for
+ * that topic. Per-connection and reset on reconnect - no cross-reconnect id
+ * stability and no server-side schema registry.
+ */
+export const WS_TOPIC_IDS = Symbol.for('adapter-uws.ws.topic-ids');
+
 // - Bounded-by-default capacity caps ---------------------------------------
 // Single source of truth for the per-connection and module-level Map / Set
 // caps that handler.js, vite.js, and testing.js all enforce. The numbers