svelte-adapter-uws 0.5.8 → 0.6.0-next.2

package/README.md

@@ -2815,6 +2815,21 @@ 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. 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.
+
+There are two binary wire forms, negotiated per connection by capability:
+
+- **Full-string keys (`cursor.protocol:2`, schema 1).** Every frame carries each cursor's key string. A 221-cursor coalesced `bulk` is **~83% smaller** than JSON and decodes ~4-5x faster.
+- **Short-id dictionary (`cursor.protocol:3`, schema 2), the default for capable clients.** Each cursor key is announced once, then referenced by a 1-2 byte per-connection id, so the key bytes leave the wire after the first frame and the decoder resolves the id from a cached map - **no per-entry string decode**. For realistic clustered keys this lands a warm `bulk` at **~88-89% smaller than JSON** and decodes **~16-18x faster than `JSON.parse` (~4.4x faster than the full-string wire)**. No `JSON.parse` on the cursor receive path at all.
+
+- **Capability-gated, never breaking.** The client advertises both `cursor.protocol:2` and `cursor.protocol:3` in its `hello` frame; the server sends the dictionary form to clients that advertised it and the full-string form to older binary clients, and a client with neither receives JSON unchanged. The frame's 1-byte schema version tells the decoder which form it is. Old client <-> new server and new client <-> old server both keep working.
+- **`binary: false` to disable, `dictionary: false` to keep the full-string wire.** `createCursor({ binary: false })` forces JSON for every client (e.g. to keep DevTools' WS inspector readable). `createCursor({ dictionary: false })` keeps binary but uses the full-string form for everyone, encoded once and fanned out to all subscribers. The dictionary is per-connection stateful, so each capable subscriber's frame is encoded independently; a warm dictionary encode is much cheaper than a full-string encode, so the default is a net win (cheaper CPU and smaller frames) for typical per-process fan-out - reach for `dictionary: false` only on a single process serving very high per-topic subscriber counts (hundreds-plus on one worker), where the per-subscriber encode would cost more CPU than the bandwidth saving is worth. 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.
+- **Positions are `float32`, keys are 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, state?), state? }` and `encode` returns a `Uint8Array` payload or `null` to fall back to JSON), plus `registerWireCodec(prefix, { capability, capabilities?, state?, decode })` from `svelte-adapter-uws/client` on the client. The optional `wire.state` slot gives the codec one object per connection (`onAttach(ws)` / `onDetach(ws, state)`) for a stateful wire like the cursor dictionary; the per-connection `state` is reset on reconnect. 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,44 @@ 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`).
+ *
+ * A codec may advertise more than one capability via `capabilities` (e.g. a
+ * cursor client that decodes both the full-string and the short-id dictionary
+ * wire advertises both tokens, negotiating the best the server offers while an
+ * older server still sends the form it knows). A codec may also declare a
+ * per-connection `state` factory (`state.onAttach` / `state.onDetach`) for a
+ * stateful wire (the cursor short-id dictionary); `decode` then receives that
+ * per-connection state and the frame's `schemaVersion` so it can resolve
+ * references and dispatch between schema revisions. The state is reset on every
+ * (re)connect, in lock-step with the server's matching encoder state.
+ *
+ * @param prefix - topic-name prefix the codec owns (e.g. `'__cursor:'`)
+ * @param codec - `{ capability, capabilities?, state?, decode }`
+ */
+export function registerWireCodec(
+	prefix: string,
+	codec: {
+		capability: string;
+		capabilities?: string[];
+		state?: {
+			onAttach?: () => unknown;
+			onDetach?: (state: unknown) => void;
+		};
+		decode: (
+			payload: Uint8Array,
+			state?: unknown,
+			schemaVersion?: number
+		) => { 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,76 @@ 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.
+ *
+ * A codec may advertise more than one capability (`capabilities`) - e.g. a
+ * cursor client that can decode both the full-string and the short-id wire
+ * advertises both tokens so it negotiates the best the server offers while an
+ * older server still sends it the form it knows. A codec may also declare a
+ * per-connection `state` factory (`state.onAttach` / `state.onDetach`) for a
+ * stateful wire (the cursor short-id dictionary, or a future apply-in-place
+ * CRDT codec); the decoder then receives that state plus the frame's
+ * `schemaVersion` so it can dispatch between schema revisions.
+ * @type {Map<string, { capability: string, capabilities?: string[], state?: { onAttach?: () => any, onDetach?: (state: any) => void }, decode: (payload: Uint8Array, state?: any, schemaVersion?: number) => ({ 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, capabilities?: string[], state?: { onAttach?: () => any, onDetach?: (state: any) => void }, decode: (payload: Uint8Array, state?: any, schemaVersion?: number) => ({ 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 capability every
+ * registered codec can decode. 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()) {
+		const tokens = codec.capabilities || [codec.capability];
+		for (let i = 0; i < tokens.length; i++) caps.push(tokens[i]);
+	}
+	return caps;
+}
+
+/**
+ * Resolve a topic name to its registered wire codec (and its prefix, for
+ * per-connection state keying) by longest matching prefix.
+ * @param {string} topic
+ * @returns {{ prefix: string, codec: { capability: string, capabilities?: string[], state?: { onAttach?: () => any, onDetach?: (state: any) => void }, decode: (payload: Uint8Array, state?: any, schemaVersion?: number) => ({ 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 = { prefix, codec };
+			bestLen = prefix.length;
+		}
+	}
+	return best;
+}
+
 /**
  * Ensure the singleton connection exists.
  * @param {import('./client.js').ConnectOptions} [options]
@@ -707,6 +778,47 @@ 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();
+
+	// Per-connection decoder state for stateful wire codecs (e.g. the cursor
+	// short-id dictionary), keyed by codec prefix. Created lazily on the first
+	// `0x03` frame for a prefix via the codec's `state.onAttach()`, and cleared
+	// (with `state.onDetach()`) on each (re)connect alongside `wireIdMap` since
+	// the server resets its matching encoder state on a fresh connection.
+	/** @type {Map<string, any>} */
+	const wireDecoderStates = new Map();
+
+	// Resolve (lazily creating) the per-connection decoder state for a codec.
+	/** @param {string} prefix @param {{ state?: { onAttach?: () => any } }} codec @returns {any} */
+	function ensureDecoderState(prefix, codec) {
+		if (!codec.state || typeof codec.state.onAttach !== 'function') return null;
+		let st = wireDecoderStates.get(prefix);
+		if (st === undefined) {
+			try { st = codec.state.onAttach(); } catch { st = null; }
+			wireDecoderStates.set(prefix, st);
+		}
+		return st;
+	}
+
+	// Dispose every per-connection decoder state, then clear. Called on each
+	// (re)connect so a reconnect starts from an empty dictionary in lock-step
+	// with the server's reset encoder state.
+	function resetWireDecoderStates() {
+		for (const [prefix, st] of wireDecoderStates) {
+			const codec = wireCodecs.get(prefix);
+			if (codec && codec.state && typeof codec.state.onDetach === 'function') {
+				try { codec.state.onDetach(st); } catch {}
+			}
+		}
+		wireDecoderStates.clear();
+	}
+
 	// 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 +1095,18 @@ 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.
+		// The stateful codec dictionaries reset in lock-step: the server starts a
+		// fresh encoder dictionary on the new connection, so a stale client
+		// dictionary would resolve ids to the wrong keys.
+		wireIdMap.clear();
+		resetWireDecoderStates();
 
 		ws.onopen = () => {
 			attempt = 0;
@@ -992,10 +1116,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 +1183,38 @@ 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 match = wireCodecForTopic(topic);
+							const decoded = match
+								? match.codec.decode(parsed.payload, ensureDecoderState(match.prefix, match.codec), parsed.schemaVersion)
+								: 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 +1251,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 +1729,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 +1761,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, WS_WIRE_STATE, 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,97 @@ 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;
+}
+
+/**
+ * Resolve (allocating on first use) the per-connection state object for a
+ * stateful wire codec, stored under the codec's capability in the
+ * `WS_WIRE_STATE` slot. The codec's `wire.state.onAttach(ws)` factory runs once
+ * per (connection, capability) - the decision it makes (e.g. which schema
+ * version this connection negotiated, read from its `WS_CAPS`) is then fixed for
+ * the life of the connection. A factory that throws or returns null degrades
+ * that connection to JSON for the frame rather than crashing the publish.
+ * Returns null for a stateless codec (no `wire.state`) or on attach failure.
+ * @param {import('uWebSockets.js').WebSocket<any>} ws
+ * @param {any} ud - ws.getUserData()
+ * @param {{ capability: string, state?: { onAttach: (ws: any) => any, onDetach?: (ws: any, state: any) => void } }} wire
+ * @returns {any}
+ */
+function ensureWireState(ws, ud, wire) {
+	if (!wire.state) return null;
+	let m = ud[WS_WIRE_STATE];
+	if (!m) {
+		m = new Map();
+		ud[WS_WIRE_STATE] = m;
+	}
+	let entry = m.get(wire.capability);
+	if (entry === undefined) {
+		let state = null;
+		try {
+			state = wire.state.onAttach(ws);
+		} catch (err) {
+			if (wsDebug) console.error('[ws] wire.state.onAttach threw for', wire.capability, err);
+			state = null;
+		}
+		entry = { state, detach: wire.state.onDetach };
+		m.set(wire.capability, entry);
+	}
+	return entry.state;
+}
+
+/**
+ * Dispose every per-connection wire-codec state on close. Mirrors the
+ * `capCounts.adjust(..., null)` release: a codec that holds resources (or just
+ * wants its dictionary freed promptly) gets its `onDetach(ws, state)` called
+ * exactly once. Safe to call when no stateful codec ever ran.
+ * @param {import('uWebSockets.js').WebSocket<any>} ws
+ * @param {any} ud - ws.getUserData()
+ */
+function detachWireStates(ws, ud) {
+	const m = ud[WS_WIRE_STATE];
+	if (!m) return;
+	for (const entry of m.values()) {
+		if (entry && typeof entry.detach === 'function') {
+			try { entry.detach(ws, entry.state); } catch (err) {
+				if (wsDebug) console.error('[ws] wire.state.onDetach threw', err);
+			}
+		}
+	}
+	m.clear();
+}
+
 /** @type {import('./index.js').Platform} */
 const platform = {
 	/**
@@ -979,6 +1071,190 @@ 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;
+
+		const relayed = !!(parentPort && (!options || options.relay !== false));
+
+		// JSON fast path: no live connection wants binary for this codec. Byte-
+		// and instruction-identical to platform.publish - a JSON-only deployment
+		// never enters the per-subscriber walk or touches the codec at all.
+		if (!capCounts.has(wire.capability)) {
+			const result = app.publish(topic, envelope, false, false);
+			if (relayed) batchRelay(topic, envelope);
+			return result || relayed;
+		}
+
+		const seqOnWire = seq == null ? 0 : seq;
+
+		// Stateful codec (per-connection dictionary / apply-state): the encoded
+		// payload depends on the recipient's state, so encode-once-send-many no
+		// longer holds for the binary recipients - each capable connection is
+		// encoded against its own state. Connections whose onAttach returned null
+		// (e.g. an older client that negotiated the stateless schema) share one
+		// encode at `wire.schemaVersion`, memoized by topic-id, so a mixed room
+		// keeps the single-encode fan-out for those clients.
+		if (wire.state) {
+			let sharedPayload;
+			let sharedEncoded = false;
+			/** @type {Map<number, Uint8Array>} */
+			const sharedFrameById = 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)) {
+					try { ws.send(envelope, false, false); } catch { closedWsAborts++; }
+					continue;
+				}
+				const state = ensureWireState(ws, ud, wire);
+				if (state == null) {
+					// Shared encode-once at the codec's baseline schema version.
+					if (!sharedEncoded) { sharedPayload = wire.encode(event, data, null); sharedEncoded = true; }
+					if (sharedPayload == null) { try { ws.send(envelope, false, false); } catch { closedWsAborts++; } continue; }
+					const id = ensureWireId(ws, ud, topic);
+					let frame = sharedFrameById.get(id);
+					if (!frame) { frame = buildBinaryFrame(wire.schemaVersion, id, seqOnWire, sharedPayload); sharedFrameById.set(id, frame); }
+					try { ws.send(frame, true, false); } catch { closedWsAborts++; }
+				} else {
+					// Per-connection encode against this connection's state, stamped
+					// with the schema version that state negotiated.
+					const payload = wire.encode(event, data, state);
+					if (payload == null) { try { ws.send(envelope, false, false); } catch { closedWsAborts++; } continue; }
+					const sv = typeof state.schemaVersion === 'number' ? state.schemaVersion : wire.schemaVersion;
+					const frame = buildBinaryFrame(sv, ensureWireId(ws, ud, topic), seqOnWire, payload);
+					try { ws.send(frame, true, false); } catch { closedWsAborts++; }
+				}
+			}
+			if (relayed) batchRelay(topic, envelope);
+			return true;
+		}
+
+		// Stateless codec: encode once, send many. A null payload (the codec
+		// declined this frame) falls through to the single C++ app.publish
+		// fan-out, instruction-identical to platform.publish. 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 payload = wire.encode(event, data);
+		if (payload == null) {
+			const result = app.publish(topic, envelope, false, false);
+			if (relayed) batchRelay(topic, envelope);
+			return result || relayed;
+		}
+		/** @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];
+		let payload = null;
+		let schemaVersion = wire.schemaVersion;
+		if (caps && caps.has(wire.capability)) {
+			if (wire.state) {
+				// Share the connection's codec state with publishWire so a
+				// snapshot CATALOG interns ids the following BULK (and every
+				// later broadcast) references against the same dictionary.
+				const state = ensureWireState(ws, ud, wire);
+				payload = wire.encode(event, data, state);
+				if (state != null && typeof state.schemaVersion === 'number') schemaVersion = state.schemaVersion;
+			} else {
+				payload = wire.encode(event, data);
+			}
+		}
+		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(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 +3597,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 +3693,12 @@ 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);
+				// Dispose any per-connection wire-codec state (e.g. the cursor
+				// short-id dictionary) so a long-lived server frees it promptly.
+				detachWireStates(ws, userData);
 				wsConnections.delete(ws);
 				if (wsDebug) console.log('[ws] close code=%d connections=%d', code, wsConnections.size);
 			}

package/files/utils.js

@@ -404,6 +404,31 @@ 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');
+
+/**
+ * Per-connection per-codec wire state for stateful binary codecs:
+ * `Map<capability, { state, detach }>`. A codec that declares a `wire.state`
+ * factory (e.g. the cursor short-id dictionary, or a future apply-in-place
+ * CRDT codec) gets one `state` object per connection, created lazily by
+ * `wire.state.onAttach(ws)` on the first binary frame to that connection and
+ * disposed by `wire.state.onDetach(ws, state)` on close. JSON-only and
+ * stateless-codec connections never allocate this slot. The decision a codec
+ * makes in `onAttach` (e.g. which schema version this connection negotiated)
+ * is fixed for the life of the connection - reset on reconnect, not re-hello.
+ */
+export const WS_WIRE_STATE = Symbol.for('adapter-uws.ws.wire-state');
+
 // - 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