svelte-adapter-uws 0.5.8 → 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 */
@@ -912,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 = {
 	/**
@@ -979,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.
 	 *
@@ -3321,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;
 				}
@@ -3412,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

package/files/wire.js

@@ -0,0 +1,270 @@
+/**
+ * Binary wire primitives for the `0x03` topic-PAYLOAD frame.
+ *
+ * The leading-byte demux on a WebSocket connection is:
+ *   - `0x01` upload chunk  (svelte-realtime layer, client -> server, never inbound here)
+ *   - `0x02` upload cancel (svelte-realtime layer, client -> server)
+ *   - `0x03` binary topic frame (this module, server -> client)
+ *
+ * The `0x03` frame envelope, owned by the framework (not the plugin codec):
+ *
+ *   [0x03][schemaVersion:u8][topicId:varint][seq:varint][codec payload...]
+ *
+ * `topicId` is the per-connection short id assigned by the server and
+ * advertised to the client out-of-band (see the `wire-id` control frame).
+ * `seq` is the per-topic monotonic sequence (0 means "no seq", matching the
+ * seq-less single-target send path). The codec payload is opaque to the
+ * framework - a plugin's `wire.encode` produced it and that plugin's
+ * `wire.decode` consumes it.
+ *
+ * Integers use unsigned LEB128 varints. Division/multiplication (not bit
+ * shifts) carry values past 2^31 so a long-lived per-topic `seq` never wraps
+ * or corrupts. Floats use big-endian IEEE-754 single precision, matching the
+ * big-endian convention of the upload frame builders.
+ *
+ * @module svelte-adapter-uws/files/wire
+ */
+
+/** Leading byte of a binary topic-PAYLOAD frame. */
+export const WIRE_BINARY_TAG = 0x03;
+
+const ENC = new TextEncoder();
+const DEC = new TextDecoder();
+
+/**
+ * Growable byte buffer with varint / float32 / length-prefixed-string writers.
+ * Backed by an ArrayBuffer that doubles on demand; `take()` returns an
+ * exact-length copy safe to retain, share, or hand to `ws.send`.
+ */
+export class ByteWriter {
+	constructor(initial = 64) {
+		this._ab = new ArrayBuffer(initial);
+		this._buf = new Uint8Array(this._ab);
+		this._view = new DataView(this._ab);
+		this.len = 0;
+	}
+
+	/** @param {number} need - additional bytes required */
+	_ensure(need) {
+		const want = this.len + need;
+		if (want <= this._buf.length) return;
+		let cap = this._buf.length * 2;
+		while (cap < want) cap *= 2;
+		const ab = new ArrayBuffer(cap);
+		const buf = new Uint8Array(ab);
+		buf.set(this._buf.subarray(0, this.len));
+		this._ab = ab;
+		this._buf = buf;
+		this._view = new DataView(ab);
+	}
+
+	/** Write one byte. @param {number} n */
+	u8(n) {
+		this._ensure(1);
+		this._buf[this.len++] = n & 0xff;
+	}
+
+	/** Write an unsigned LEB128 varint. @param {number} value - non-negative, < 2^53 */
+	varint(value) {
+		// Math (not >>>) so values above 2^31 stay correct - `seq` can exceed
+		// 32 bits on a long-lived high-throughput topic.
+		while (value > 0x7f) {
+			this.u8((value & 0x7f) | 0x80);
+			value = Math.floor(value / 128);
+		}
+		this.u8(value & 0x7f);
+	}
+
+	/** Write a big-endian float32. @param {number} n */
+	f32(n) {
+		this._ensure(4);
+		this._view.setFloat32(this.len, n, false);
+		this.len += 4;
+	}
+
+	/** Write a length-prefixed (varint byte length) UTF-8 string. @param {string} s */
+	str(s) {
+		const bytes = ENC.encode(s);
+		this.varint(bytes.length);
+		this._ensure(bytes.length);
+		this._buf.set(bytes, this.len);
+		this.len += bytes.length;
+	}
+
+	/** Append raw bytes. @param {Uint8Array} bytes */
+	bytes(bytes) {
+		this._ensure(bytes.length);
+		this._buf.set(bytes, this.len);
+		this.len += bytes.length;
+	}
+
+	/** @returns {Uint8Array} exact-length copy of the written bytes */
+	take() {
+		return this._buf.slice(0, this.len);
+	}
+}
+
+/**
+ * Sequential reader over a byte payload (typically a zero-copy subarray of an
+ * inbound frame). Symmetric to {@link ByteWriter}. A read past the end throws
+ * a RangeError, which callers turn into a dropped frame.
+ */
+export class ByteReader {
+	/** @param {Uint8Array} buf */
+	constructor(buf) {
+		this._buf = buf;
+		this._view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+		this.pos = 0;
+	}
+
+	get done() {
+		return this.pos >= this._buf.length;
+	}
+
+	/** @returns {number} */
+	u8() {
+		if (this.pos >= this._buf.length) throw new RangeError('wire: read past end');
+		return this._buf[this.pos++];
+	}
+
+	/** @returns {number} */
+	varint() {
+		// Fast path: single-byte varint (the common case for lengths/counts).
+		const first = this._buf[this.pos];
+		if (first === undefined) throw new RangeError('wire: read past end');
+		if (first < 0x80) { this.pos++; return first; }
+		let result = 0;
+		let mul = 1;
+		let b;
+		do {
+			b = this._buf[this.pos++];
+			if (b === undefined) throw new RangeError('wire: read past end');
+			result += (b & 0x7f) * mul;
+			mul *= 128;
+		} while (b & 0x80);
+		return result;
+	}
+
+	/** @returns {number} big-endian float32 */
+	f32() {
+		if (this.pos + 4 > this._buf.length) throw new RangeError('wire: read past end');
+		const v = this._view.getFloat32(this.pos, false);
+		this.pos += 4;
+		return v;
+	}
+
+	/** @returns {string} length-prefixed UTF-8 string */
+	str() {
+		const len = this.varint();
+		if (this.pos + len > this._buf.length) throw new RangeError('wire: read past end');
+		const s = DEC.decode(this._buf.subarray(this.pos, this.pos + len));
+		this.pos += len;
+		return s;
+	}
+}
+
+/**
+ * Build a complete `0x03` topic-PAYLOAD frame from a codec payload.
+ *
+ * @param {number} schemaVersion - 1-byte plugin codec schema version
+ * @param {number} topicId - per-connection short topic id
+ * @param {number} seq - per-topic monotonic seq, or 0 for "no seq"
+ * @param {Uint8Array} payload - bytes returned by the plugin's `wire.encode`
+ * @returns {Uint8Array}
+ */
+export function buildBinaryFrame(schemaVersion, topicId, seq, payload) {
+	const w = new ByteWriter(8 + payload.length);
+	w.u8(WIRE_BINARY_TAG);
+	w.u8(schemaVersion & 0xff);
+	w.varint(topicId);
+	w.varint(seq);
+	w.bytes(payload);
+	return w.take();
+}
+
+/**
+ * Parse the framework header of a `0x03` frame and return the header fields
+ * plus a zero-copy view of the codec payload.
+ *
+ * @param {Uint8Array} bytes - the full inbound binary frame
+ * @returns {{ schemaVersion: number, topicId: number, seq: number, payload: Uint8Array } | null}
+ *   null when the frame is not a `0x03` frame or is truncated.
+ */
+export function parseBinaryFrame(bytes) {
+	if (bytes.length < 2 || bytes[0] !== WIRE_BINARY_TAG) return null;
+	try {
+		const r = new ByteReader(bytes);
+		r.u8(); // tag, already checked
+		const schemaVersion = r.u8();
+		const topicId = r.varint();
+		const seq = r.varint();
+		return { schemaVersion, topicId, seq, payload: bytes.subarray(r.pos) };
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Allocate (or return the existing) per-connection binary topic-id for a
+ * topic, managing the `WS_TOPIC_IDS` slot `{ byName, next }` on the userData
+ * object. Shared across the prod / test / dev platform implementations so the
+ * id space is identical in all three.
+ *
+ * @param {any} ud - ws.getUserData()
+ * @param {symbol} slotKey - the WS_TOPIC_IDS symbol
+ * @param {string} topic
+ * @returns {{ id: number, isNew: boolean }} isNew is true on first allocation
+ */
+export function allocWireId(ud, slotKey, topic) {
+	let slot = ud[slotKey];
+	if (!slot) {
+		slot = { byName: new Map(), next: 1 };
+		ud[slotKey] = slot;
+	}
+	const existing = slot.byName.get(topic);
+	if (existing !== undefined) return { id: existing, isNew: false };
+	const id = slot.next++;
+	slot.byName.set(topic, id);
+	return { id, isNew: true };
+}
+
+/**
+ * Build the `{type:'wire-id'}` control frame announcing which numeric topic-id
+ * maps to which topic name, so an inbound `0x03` frame resolves to a topic.
+ * @param {string} topic
+ * @param {number} id
+ * @returns {string}
+ */
+export function wireIdAnnounce(topic, id) {
+	return '{"type":"wire-id","topic":' + JSON.stringify(topic) + ',"id":' + id + '}';
+}
+
+/**
+ * Per-entry-point live capability accounting: how many connections have
+ * advertised each capability token. Lets the binary publish path skip the
+ * per-subscriber walk entirely when no connected client wants binary for a
+ * codec (a JSON-only deployment pays nothing).
+ *
+ * @returns {{ has(cap: string): boolean, adjust(prev: Set<string>|null|undefined, next: Set<string>|null|undefined): void }}
+ */
+export function createCapCounts() {
+	/** @type {Map<string, number>} */
+	const counts = new Map();
+	return {
+		has(cap) {
+			return (counts.get(cap) || 0) > 0;
+		},
+		adjust(prev, next) {
+			if (prev) {
+				for (const c of prev) {
+					const n = (counts.get(c) || 0) - 1;
+					if (n > 0) counts.set(c, n);
+					else counts.delete(c);
+				}
+			}
+			if (next) {
+				for (const c of next) counts.set(c, (counts.get(c) || 0) + 1);
+			}
+		}
+	};
+}

package/index.d.ts

@@ -1062,6 +1062,58 @@ export interface Platform {
 	 */
 	publish(topic: string, event: string, data?: unknown, options?: { relay?: boolean; seq?: boolean }): boolean;
 
+	/**
+	 * Publish via a plugin-declared binary wire codec. Subscribers that
+	 * advertised `wire.capability` in their `hello` frame receive a compact
+	 * binary `0x03` frame; everyone else receives the identical JSON envelope
+	 * `publish()` would have sent. App authors never call this - it is the
+	 * plugin-author surface for a high-throughput topic family (the cursor
+	 * plugin is the first beneficiary, gated by `cursor.protocol:2`).
+	 *
+	 * Zero-cost when no connected client wants binary: this takes the same
+	 * single `app.publish` fan-out as `publish()`. The codec's `encode` may
+	 * return `null` for a frame it cannot represent, which transparently falls
+	 * back to JSON for that one frame.
+	 *
+	 * @param topic - Topic string
+	 * @param event - Event name (the codec maps it to an opcode)
+	 * @param data - Payload (passed to `wire.encode`, or JSON-serialized on fallback)
+	 * @param wire - The plugin's wire codec: a negotiated `capability` token, a
+	 *   1-byte `schemaVersion`, and an `encode(event, data)` returning the
+	 *   payload bytes or `null` to fall back to JSON for this frame.
+	 * @param options - Same `relay` / `seq` semantics as `publish()`.
+	 */
+	publishWire(
+		topic: string,
+		event: string,
+		data: unknown,
+		wire: {
+			capability: string;
+			schemaVersion: number;
+			encode: (event: string, data: unknown) => Uint8Array | null;
+		},
+		options?: { relay?: boolean; seq?: boolean }
+	): boolean;
+
+	/**
+	 * Single-target counterpart to `publishWire()`. The connection receives a
+	 * binary `0x03` frame when it advertised `wire.capability` and the codec
+	 * can encode the frame; otherwise the JSON envelope `send()` would have
+	 * sent. No per-topic seq is stamped (matches `send()`). Used for
+	 * snapshot/catalog frames to a single late-joining subscriber.
+	 */
+	sendWire(
+		ws: WebSocket<any>,
+		topic: string,
+		event: string,
+		data: unknown,
+		wire: {
+			capability: string;
+			schemaVersion: number;
+			encode: (event: string, data: unknown) => Uint8Array | null;
+		}
+	): number;
+
 	/**
 	 * Publish multiple messages, returning per-message delivery results.
 	 *

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "svelte-adapter-uws",
-  "version": "0.5.8",
+  "version": "0.6.0-next.1",
   "publishConfig": {
-    "tag": "latest"
+    "tag": "next"
   },
   "description": "SvelteKit adapter for uWebSockets.js - high-performance C++ HTTP server with built-in WebSocket support",
   "author": "Kevin Radziszewski",

package/plugins/cursor/client.js

@@ -28,8 +28,17 @@
 
 const TOPIC_PREFIX = '__cursor:';
 
-import { on, connect, status } from '../../client.js';
+import { on, connect, status, registerWireCodec } from '../../client.js';
 import { writable } from 'svelte/store';
+import { decodeCursor, CURSOR_CAPABILITY } from './codec.js';
+
+// Opt this connection into binary cursor frames: advertise the capability in
+// the `hello` frame and route inbound `0x03` frames on `__cursor:` topics
+// through the cursor decoder, which yields the identical { event, data } the
+// JSON path produced - so the store merge logic below is untouched. Registered
+// at module load so the first `hello` already carries the capability. Fully
+// transparent: nothing in the cursor() store knows whether a frame was binary.
+registerWireCodec(TOPIC_PREFIX, { capability: CURSOR_CAPABILITY, decode: decodeCursor });
 
 /** @type {Map<string, ReturnType<typeof cursor>>} */
 const cursorStores = new Map();

package/plugins/cursor/codec.js

@@ -0,0 +1,199 @@
+/**
+ * Binary wire codec for the cursor plugin.
+ *
+ * Produces / consumes the `codec payload` that rides inside the framework's
+ * `0x03` topic frame (see files/wire.js for the frame envelope). The payload
+ * is `[op:u8][op-specific...]`, one op per cursor wire event:
+ *
+ *   UPDATE  [op][key][x:f32][y:f32]
+ *   BULK    [op][count:varint]({key}{x:f32}{y:f32})*
+ *   REMOVE  [op][key]
+ *   JOIN    [op][key][userJson]
+ *   CATALOG [op][count:varint]({key}{userJson})*
+ *
+ * where `key` and `userJson` are length-prefixed UTF-8 strings.
+ *
+ * Design notes (why the encoding is shaped this way, recorded so the choices
+ * are legible):
+ *
+ *   - The key is a length-prefixed UTF-8 string, NOT 16 raw UUID bytes. Cursor
+ *     keys are server-assigned connection ids - `"42"` in-process,
+ *     `"<instanceId>:42"` in the Redis-backed variant - never UUIDs, and the
+ *     same client decoder serves both backends. A length-prefixed string is
+ *     correct for any key shape.
+ *   - Positions are big-endian float32, NOT i16. Real cursor positions are
+ *     fractional doubles (e.g. `clientX - getBoundingClientRect().left`), so an
+ *     integer-only schema would fall back to JSON for essentially every frame.
+ *     float32 precision (sub-0.01 px at screen scale) is imperceptible for an
+ *     ephemeral cursor.
+ *
+ * The encoder returns `null` for any frame it cannot represent (data that is
+ * not exactly `{x, y}`-numeric, a non-string key, or a `user` that will not
+ * JSON-serialize). A `null` return tells the framework to send JSON for that
+ * one frame, so apps that put richer data on the cursor channel keep working.
+ *
+ * @module svelte-adapter-uws/plugins/cursor/codec
+ */
+
+import { ByteWriter, ByteReader } from '../../files/wire.js';
+
+/** Negotiated capability token. Bumped to `:3` only for an incompatible schema. */
+export const CURSOR_CAPABILITY = 'cursor.protocol:2';
+
+/** 1-byte in-frame schema version (the fine gate within the capability). */
+export const CURSOR_SCHEMA_VERSION = 1;
+
+const OP_UPDATE = 1;
+const OP_BULK = 2;
+const OP_REMOVE = 3;
+const OP_JOIN = 4;
+const OP_CATALOG = 5;
+
+/**
+ * True when `d` is exactly a `{ x, y }` pair of finite numbers and nothing
+ * else - the only shape the binary position encoding is lossless for. Extra
+ * fields or non-numeric coords fall back to JSON so no data is silently lost.
+ * @param {any} d
+ */
+function isXY(d) {
+	if (d === null || typeof d !== 'object') return false;
+	if (typeof d.x !== 'number' || !Number.isFinite(d.x)) return false;
+	if (typeof d.y !== 'number' || !Number.isFinite(d.y)) return false;
+	// Reject anything carrying fields beyond x/y so they are not dropped.
+	for (const k in d) {
+		if (k !== 'x' && k !== 'y') return false;
+	}
+	return true;
+}
+
+/**
+ * Encode a cursor wire event into a codec payload.
+ *
+ * @param {string} event - one of 'update' | 'bulk' | 'remove' | 'join' | 'catalog'
+ * @param {any} data - the same value `platform.publish`/`send` would carry
+ * @returns {Uint8Array | null} payload bytes, or null to fall back to JSON
+ */
+export function encodeCursor(event, data) {
+	try {
+		switch (event) {
+			case 'update': {
+				if (!data || typeof data.key !== 'string' || !isXY(data.data)) return null;
+				const w = new ByteWriter(24);
+				w.u8(OP_UPDATE);
+				w.str(data.key);
+				w.f32(data.data.x);
+				w.f32(data.data.y);
+				return w.take();
+			}
+			case 'bulk': {
+				if (!Array.isArray(data)) return null;
+				for (let i = 0; i < data.length; i++) {
+					const e = data[i];
+					if (!e || typeof e.key !== 'string' || !isXY(e.data)) return null;
+				}
+				const w = new ByteWriter(16 + data.length * 16);
+				w.u8(OP_BULK);
+				w.varint(data.length);
+				for (let i = 0; i < data.length; i++) {
+					const e = data[i];
+					w.str(e.key);
+					w.f32(e.data.x);
+					w.f32(e.data.y);
+				}
+				return w.take();
+			}
+			case 'remove': {
+				if (!data || typeof data.key !== 'string') return null;
+				const w = new ByteWriter(16);
+				w.u8(OP_REMOVE);
+				w.str(data.key);
+				return w.take();
+			}
+			case 'join': {
+				if (!data || typeof data.key !== 'string') return null;
+				const w = new ByteWriter(32);
+				w.u8(OP_JOIN);
+				w.str(data.key);
+				w.str(JSON.stringify(data.user ?? null));
+				return w.take();
+			}
+			case 'catalog': {
+				if (!Array.isArray(data)) return null;
+				const w = new ByteWriter(16 + data.length * 24);
+				w.u8(OP_CATALOG);
+				w.varint(data.length);
+				for (let i = 0; i < data.length; i++) {
+					const e = data[i];
+					if (!e || typeof e.key !== 'string') return null;
+					w.str(e.key);
+					w.str(JSON.stringify(e.user ?? null));
+				}
+				return w.take();
+			}
+			default:
+				return null;
+		}
+	} catch {
+		// Any encode failure (e.g. a `user` value that will not JSON-serialize)
+		// falls back to JSON for this frame rather than throwing into publish.
+		return null;
+	}
+}
+
+/**
+ * Decode a cursor codec payload back into the `{ event, data }` shape the
+ * JSON path would have dispatched. Returns null on an unknown opcode or a
+ * truncated / malformed frame (the frame is then dropped; cursor is
+ * best-effort).
+ *
+ * @param {Uint8Array} payload - codec bytes (frame header already stripped)
+ * @returns {{ event: string, data: any } | null}
+ */
+export function decodeCursor(payload) {
+	try {
+		const r = new ByteReader(payload);
+		const op = r.u8();
+		switch (op) {
+			case OP_UPDATE: {
+				const key = r.str();
+				const x = r.f32();
+				const y = r.f32();
+				return { event: 'update', data: { key, data: { x, y } } };
+			}
+			case OP_BULK: {
+				const count = r.varint();
+				const arr = new Array(count);
+				for (let i = 0; i < count; i++) {
+					const key = r.str();
+					const x = r.f32();
+					const y = r.f32();
+					arr[i] = { key, data: { x, y } };
+				}
+				return { event: 'bulk', data: arr };
+			}
+			case OP_REMOVE: {
+				const key = r.str();
+				return { event: 'remove', data: { key } };
+			}
+			case OP_JOIN: {
+				const key = r.str();
+				const user = JSON.parse(r.str());
+				return { event: 'join', data: { key, user } };
+			}
+			case OP_CATALOG: {
+				const count = r.varint();
+				const arr = new Array(count);
+				for (let i = 0; i < count; i++) {
+					const key = r.str();
+					const user = JSON.parse(r.str());
+					arr[i] = { key, user };
+				}
+				return { event: 'catalog', data: arr };
+			}
+			default:
+				return null;
+		}
+	} catch {
+		return null;
+	}
+}

package/plugins/cursor/server.d.ts

@@ -89,6 +89,23 @@ export interface CursorOptions<UserData = unknown, UserInfo = unknown> {
 	 * @default 8192 (8 KB)
 	 */
 	maxDataBytes?: number;
+
+	/**
+	 * Binary wire transport. When `true` (the default), cursor frames are sent
+	 * as compact binary `0x03` frames to clients that negotiated the
+	 * `cursor.protocol:2` capability, and as JSON to everyone else - fully
+	 * transparent, no app-code change, and a ~65-85% wire-size reduction on the
+	 * position hot path. Set `false` to force JSON for every client (e.g. to
+	 * keep DevTools' WS inspector readable). The wire format is the server's
+	 * decision - clients never opt out via a URL parameter.
+	 *
+	 * Non-`{x, y}`-numeric cursor data (extra fields, non-numeric positions)
+	 * transparently falls back to JSON per frame, so richer cursor payloads
+	 * keep working regardless of this flag.
+	 *
+	 * @default true
+	 */
+	binary?: boolean;
 }
 
 export interface CursorEntry<UserInfo = unknown, Data = unknown> {

package/plugins/cursor/server.js

@@ -36,6 +36,8 @@
  * @module svelte-adapter-uws/plugins/cursor
  */
 
+import { encodeCursor, CURSOR_CAPABILITY, CURSOR_SCHEMA_VERSION } from './codec.js';
+
 const TOPIC_PREFIX = '__cursor:';
 
 /** Wire-protocol event names. */
@@ -154,6 +156,14 @@ export function createCursor(options = {}) {
 	const maxTopicLength = options.maxTopicLength ?? 256;
 	const maxDataBytes = options.maxDataBytes ?? 8192;
 
+	// Binary wire is on by default and fully transparent: binary-capable
+	// clients receive compact `0x03` cursor frames, everyone else (and any
+	// platform without the publishWire/sendWire methods, e.g. the unit-test
+	// mock) receives the identical JSON frames. `binary: false` forces JSON.
+	const wireCodec = options.binary === false
+		? null
+		: { capability: CURSOR_CAPABILITY, schemaVersion: CURSOR_SCHEMA_VERSION, encode: encodeCursor };
+
 	if (typeof throttleMs !== 'number' || !Number.isFinite(throttleMs) || throttleMs < 0) {
 		throw new Error('cursor: throttle must be a non-negative number');
 	}
@@ -284,13 +294,47 @@ export function createCursor(options = {}) {
 		dirtyTopics.delete(topic);
 	}
 
+	/**
+	 * Broadcast a cursor wire event. Routes through the binary `publishWire`
+	 * path when a codec is configured AND the platform supports it (production /
+	 * dev / test-server); otherwise falls back to the JSON `publish` - so the
+	 * unit-test mock platform and `binary: false` both keep the exact JSON shape.
+	 * @param {string} fullTopic - the channel name, already TOPIC_PREFIX-scoped
+	 * @param {string} event
+	 * @param {any} data
+	 * @param {import('../../index.js').Platform} platform
+	 */
+	function emit(fullTopic, event, data, platform) {
+		if (wireCodec && typeof platform.publishWire === 'function') {
+			platform.publishWire(fullTopic, event, data, wireCodec);
+		} else {
+			platform.publish(fullTopic, event, data);
+		}
+	}
+
+	/**
+	 * Single-target variant of {@link emit} (snapshot catalog + positions).
+	 * @param {any} ws
+	 * @param {string} fullTopic
+	 * @param {string} event
+	 * @param {any} data
+	 * @param {import('../../index.js').Platform} platform
+	 */
+	function emitTo(ws, fullTopic, event, data, platform) {
+		if (wireCodec && typeof platform.sendWire === 'function') {
+			platform.sendWire(ws, fullTopic, event, data, wireCodec);
+		} else {
+			platform.send(ws, fullTopic, event, data);
+		}
+	}
+
 	/**
 	 * Emit `join` for a (ws, topic) pair the first time the ws moves on
 	 * the topic. Broadcast (not single-target) so existing subscribers
 	 * pick up the new user before any position frames arrive.
 	 */
 	function emitJoin(topic, key, user, platform) {
-		platform.publish(TOPIC_PREFIX + topic, EVENTS.JOIN, { key, user });
+		emit(TOPIC_PREFIX + topic, EVENTS.JOIN, { key, user }, platform);
 	}
 
 	/**
@@ -301,7 +345,7 @@ export function createCursor(options = {}) {
 	 * @param {import('../../index.js').Platform} platform
 	 */
 	function doBroadcast(topic, key, data, platform) {
-		platform.publish(TOPIC_PREFIX + topic, EVENTS.UPDATE, { key, data });
+		emit(TOPIC_PREFIX + topic, EVENTS.UPDATE, { key, data }, platform);
 	}
 
 	/**
@@ -325,7 +369,7 @@ export function createCursor(options = {}) {
 			flushPlatform = v.platform;
 		}
 		if (flushPlatform) {
-			flushPlatform.publish(TOPIC_PREFIX + topic, EVENTS.BULK, entries);
+			emit(TOPIC_PREFIX + topic, EVENTS.BULK, entries, flushPlatform);
 		}
 	}
 
@@ -533,7 +577,7 @@ export function createCursor(options = {}) {
 						const flushState = topicFlush.get(topic);
 						if (flushState) flushState.dirty.delete(state.key);
 					}
-					platform.publish(TOPIC_PREFIX + topic, EVENTS.REMOVE, { key: state.key });
+					emit(TOPIC_PREFIX + topic, EVENTS.REMOVE, { key: state.key }, platform);
 				}
 			}
 
@@ -561,8 +605,8 @@ export function createCursor(options = {}) {
 					positions.push({ key, data: entry.data });
 				}
 			}
-			platform.send(ws, TOPIC_PREFIX + topic, EVENTS.CATALOG, catalog);
-			platform.send(ws, TOPIC_PREFIX + topic, EVENTS.BULK, positions);
+			emitTo(ws, TOPIC_PREFIX + topic, EVENTS.CATALOG, catalog, platform);
+			emitTo(ws, TOPIC_PREFIX + topic, EVENTS.BULK, positions, platform);
 		},
 
 		clear() {

package/testing.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { parseCookies } from './files/cookies.js';
-import { nextTopicSeq, completeEnvelope, wrapBatchEnvelope, collapseByCoalesceKey, esc, isValidWireTopic, createScopedTopic, resolveRequestId, createChaosState, createUpgradeAdmission, readAssertionCounts, assert, 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 } from './files/utils.js';
+import { nextTopicSeq, completeEnvelope, wrapBatchEnvelope, collapseByCoalesceKey, esc, isValidWireTopic, createScopedTopic, resolveRequestId, createChaosState, createUpgradeAdmission, readAssertionCounts, assert, 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 } from './files/utils.js';
+import { buildBinaryFrame, allocWireId, wireIdAnnounce, createCapCounts } from './files/wire.js';
 
 // Curated re-exports for downstream test code (extensions, app-side
 // integration tests, custom transport bridges that need to assert on
@@ -208,6 +209,50 @@ export async function createTestServer(options = {}) {
 		return result;
 	}
 
+	/**
+	 * Binary-frame variant of sendOutboundT (isBinary=true). Routes through the
+	 * same chaos chokepoint so drop/slow-drain scenarios apply to `0x03` frames.
+	 * @param {import('uWebSockets.js').WebSocket<any>} ws
+	 * @param {Uint8Array} frame
+	 */
+	function sendOutboundBinaryT(ws, frame) {
+		if (chaos.shouldDropOutbound()) return 0;
+		const delay = chaos.getDelayMs();
+		if (delay > 0) {
+			setTimeout(() => {
+				try { ws.send(frame, true, false); }
+				catch { closedWsAbortsT++; return; }
+				bumpOutT(ws, frame);
+			}, delay);
+			return 1;
+		}
+		let result;
+		try { result = ws.send(frame, true, false); }
+		catch { closedWsAbortsT++; return 2; }
+		bumpOutT(ws, frame);
+		return result;
+	}
+
+	// Binary wire (0x03) capability accounting + topic-id assignment, mirroring
+	// production handler.js so the cap-gated binary publish path is exercised
+	// by createTestServer-based suites. Shared primitives live in ./files/wire.js.
+	const capCountsT = createCapCounts();
+
+	/**
+	 * Per-connection topic-id resolution + lazy `wire-id` announce. Binary
+	 * frames and the announce flow through sendOutboundT so chaos scenarios
+	 * apply to them too.
+	 * @param {import('uWebSockets.js').WebSocket<any>} ws
+	 * @param {any} ud
+	 * @param {string} topic
+	 * @returns {number}
+	 */
+	function ensureWireIdT(ws, ud, topic) {
+		const { id, isNew } = allocWireId(ud, WS_TOPIC_IDS, topic);
+		if (isNew) sendOutboundT(ws, wireIdAnnounce(topic, id));
+		return id;
+	}
+
 	const platform = {
 		publish(topic, event, data, options) {
 			const seq = (options && options.seq === false)
@@ -233,6 +278,61 @@ export async function createTestServer(options = {}) {
 			const payload = envelope(topic, event, data);
 			return sendOutboundT(ws, payload);
 		},
+		publishWire(topic, event, data, wire, options) {
+			const seq = (options && options.seq === false)
+				? null
+				: nextTopicSeq(topicSeqs, topic);
+			const env = envelope(topic, event, data, seq);
+			const payload = capCountsT.has(wire.capability) ? wire.encode(event, data) : null;
+			if (payload == null) {
+				// No capable client (or codec declined): single C++ fan-out,
+				// identical to platform.publish's fast path.
+				if (chaos.scenario === null) return app.publish(topic, env, false, false);
+				let delivered = false;
+				for (const ws of wsConnections) {
+					if (!ws.isSubscribed(topic)) continue;
+					sendOutboundT(ws, env);
+					delivered = true;
+				}
+				return delivered;
+			}
+			const seqOnWire = seq == null ? 0 : seq;
+			/** @type {Map<number, Uint8Array>} */
+			const frameById = new Map();
+			let delivered = false;
+			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 = ensureWireIdT(ws, ud, topic);
+					let frame = frameById.get(id);
+					if (!frame) {
+						frame = buildBinaryFrame(wire.schemaVersion, id, seqOnWire, payload);
+						frameById.set(id, frame);
+					}
+					sendOutboundBinaryT(ws, frame);
+				} else {
+					sendOutboundT(ws, env);
+				}
+				delivered = true;
+			}
+			return delivered;
+		},
+		sendWire(ws, topic, event, data, wire) {
+			let ud;
+			try { ud = ws.getUserData(); } catch { closedWsAbortsT++; return 2; }
+			const caps = ud[WS_CAPS];
+			const payload = (caps && caps.has(wire.capability)) ? wire.encode(event, data) : null;
+			if (payload == null) {
+				return sendOutboundT(ws, envelope(topic, event, data));
+			}
+			const id = ensureWireIdT(ws, ud, topic);
+			const frame = buildBinaryFrame(wire.schemaVersion, id, 0, payload);
+			return sendOutboundBinaryT(ws, frame);
+		},
 		sendTo(filter, topic, event, data) {
 			const msg = envelope(topic, event, data);
 			let count = 0;
@@ -681,7 +781,9 @@ export async function createTestServer(options = {}) {
 							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 helloUd = ws.getUserData();
+							capCountsT.adjust(helloUd[WS_CAPS], caps);
+							helloUd[WS_CAPS] = caps;
 							return;
 						}
 						if (msg.type === 'subscribe-batch' && Array.isArray(msg.topics)) {
@@ -809,6 +911,7 @@ export async function createTestServer(options = {}) {
 				}
 				: { code, message, platform: closePlatform, subscriptions: subs };
 			handler.close?.(ws, ctx);
+			capCountsT.adjust(ud[WS_CAPS], null);
 			wsConnections.delete(ws);
 		}
 	});

package/vite.js

@@ -319,6 +319,20 @@ export default function uws(options = {}) {
 	const platform = {
 		publish,
 		publishBatched,
+		// Binary wire (publishWire/sendWire) is a production transport
+		// optimization. Dev mode delegates to the JSON publish/send: a
+		// binary-capable client receives JSON text frames, which its cursor
+		// store consumes identically (the binary path is transparent and
+		// optional). This mirrors dev's existing simpler-than-prod posture
+		// (dev also skips per-topic seq stamping). The full binary `0x03` path
+		// ships and is tested in production (files/handler.js) and the test
+		// server (testing.js).
+		publishWire(topic, event, data, _wire, options) {
+			return publish(topic, event, data, options);
+		},
+		sendWire(ws, topic, event, data, _wire) {
+			return send(ws, topic, event, data);
+		},
 		batch(messages) {
 			const results = [];
 			for (let i = 0; i < messages.length; i++) {