svelte-adapter-uws 0.5.1 → 0.5.3

package/MIGRATION.md

@@ -104,7 +104,7 @@ These change observable runtime behavior. Most apps are unaffected; a few will n
 
 ### Default `maxPayloadLength` raised from 16 KB to 1 MB
 
-**What changed.** The default cap on a single inbound WebSocket frame moved from 16 KB to 1 MB. uWS itself defaults to 16 MB; 16 KB was excessively conservative and forced chunked-upload frameworks to use ~12 KB chunks (~9000 chunks for a 100 MB file after typical 90% headroom). Apps that were chunking large payloads to fit under 16 KB will now accept them in fewer chunks (or in a single frame).
+**What changed.** The default cap on a single inbound WebSocket frame moved from 16 KB to 1 MB. The adapter previously matched uWS's own 16 KB default, which was excessively conservative for typical app payloads - it forced chunked-upload frameworks to use ~12 KB chunks (~9000 chunks for a 100 MB file after typical 90% headroom). Apps that were chunking large payloads to fit under 16 KB will now accept them in fewer chunks (or in a single frame).
 
 **How to migrate.** No action needed for most apps. To pin the previous cap, set `websocket.maxPayloadLength: 16 * 1024` in `svelte.config.js`. To pin any other value, set the option to that byte count. DoS protection remains layered: `upgradeAdmission.maxConcurrent` caps connection count, `maxBackpressure` caps per-connection outbound queue size.
 

package/README.md

@@ -426,7 +426,7 @@ adapter({
 
 These options control how the server handles misbehaving or slow clients at the WebSocket level:
 
-**`maxPayloadLength`** (default: 1 MB) - the maximum size of a single incoming WebSocket message. If a client sends a message larger than this, uWS closes the connection immediately (not just the message - the entire connection is dropped). Set this based on the largest message your application expects to receive. uWS itself defaults to 16 MB; this adapter sets 1 MB as a balanced default that handles typical app payloads in a single frame without forcing chunked-upload frameworks into ~12 KB chunks (which the previous 16 KB default did). For a stricter cap, pin an explicit value (e.g. `16 * 1024` for 16 KB).
+**`maxPayloadLength`** (default: 1 MB) - the maximum size of a single incoming WebSocket message. If a client sends a message larger than this, uWS closes the connection immediately (not just the message - the entire connection is dropped). Set this based on the largest message your application expects to receive. uWS's own default is 16 KB, which the adapter previously matched; the 1 MB default ships now to handle typical app payloads in a single frame without forcing chunked-upload frameworks into ~12 KB chunks (which the previous 16 KB cap did). For a stricter cap, pin an explicit value (e.g. `16 * 1024` for the uWS-matching 16 KB).
 
 **`maxBackpressure`** (default: 1 MB) - the per-connection outbound send buffer, AND the threshold above which `publish` / `send` / `publishBatched` silently skip a subscriber. When a specific subscriber's buffer is over this size, uWS drops that frame *for that subscriber only* while continuing to deliver to every non-backpressured subscriber. This makes `publish` / `send` / `publishBatched` volatile-by-default for slow consumers (the right behavior for cursor positions, typing indicators, presence pings - see "Volatile / fire-and-forget delivery" below). The `drain` hook fires per-connection when the buffer empties again. Lower this if you want subscribers shed sooner; raise it if you prefer to keep the connection queued and absorb temporary slowness. uWS's own default is 64 KB; this adapter sets 1 MB to favor keeping the connection alive under pub/sub spikes.
 
@@ -699,12 +699,25 @@ export function open(ws, { platform }) {
   ws.subscribe(`user:${userId}`);
 }
 
-// Called when a message is received
+// Called when a message is received.
 // Note: subscribe/unsubscribe messages from the client store are
-// handled automatically BEFORE this function is called
-export function message(ws, { data, isBinary }) {
-  const msg = JSON.parse(Buffer.from(data).toString());
-  console.log('Got message:', msg);
+// handled automatically BEFORE this function is called.
+//
+// `msg` is the JSON-parsed envelope when the adapter parsed the frame
+// for control-message routing but no control type matched (i.e. it
+// looks like `{"type":"<custom>",...}` from a plugin). The adapter
+// already did `TextDecoder + JSON.parse` once during routing, so this
+// avoids a second parse on the dispatch path. `msg` is `undefined`
+// for binary frames, prefix-miss frames, parse failures, or frames
+// that parse to a non-object.
+export function message(ws, { data, isBinary, msg }) {
+  if (msg) {
+    // Already-parsed JSON object envelope - dispatch by msg.type
+    console.log('Got envelope:', msg);
+    return;
+  }
+  // Binary or non-envelope text frame - decode manually
+  console.log('Got raw frame, byteLength:', data.byteLength);
 }
 
 // Called when a client tries to subscribe to a topic (optional)
@@ -2755,14 +2768,31 @@ Lightweight fire-and-forget broadcasting for transient state - mouse cursors, te
 import { createCursor } from 'svelte-adapter-uws/plugins/cursor';
 
 export const cursors = createCursor({
-  throttle: 50, // at most one broadcast per 50ms per user per topic
+  throttle: 16,       // per-cursor: at most one broadcast per 16ms (~60 Hz)
+  topicThrottle: 16,  // per-topic: coalesce all movers into one frame per 16ms
   select: (userData) => ({ id: userData.id, name: userData.name, color: userData.color })
   // maxConnections: 1_000_000 (default) - hard cap on tracked connections
   // maxTopics:      1_000_000 (default) - hard cap on active topic registry
 });
 ```
 
-The two cap options bound internal Maps that grow with client behaviour. Eviction at cap drops the oldest insertion-order entry; for `maxTopics` the dropped topic's pending throttle timers are cleared first so no callback fires on a deleted entry. In practice eviction is rare because user code is expected to call `remove(ws)` on disconnect (the `cursors.hooks.close` helper does this automatically).
+Both `throttle` and `topicThrottle` default to 16 ms (~60 Hz). For a 120 Hz demo, halve them to 8. To disable per-topic coalescing entirely (every broadcast goes straight out), pass `topicThrottle: 0`. The two cap options bound internal Maps that grow with client behaviour. Eviction at cap drops the oldest insertion-order entry; for `maxTopics` the dropped topic's pending timers (per-cursor and topic-coalesce) are cleared first.
+
+`topicThrottle` is the bandwidth lever for crowded rooms: rather than fan out one frame per cursor per tick, the server emits one `bulk` array per topic per window carrying every cursor that moved in that window. Bandwidth per peer scales with active-mover count, not with mover-count times per-mover rate.
+
+#### Wire shape
+
+Positions live on the `update` / `bulk` channel; user metadata lives on the `catalog` / `join` channel. The split keeps per-frame wire bytes minimal: a position frame is ~16 bytes per cursor (key + coords), and the user object (name, color, avatar, etc.) flows only when a user first appears.
+
+| Event | Payload | Sent by |
+|---|---|---|
+| `catalog` | `[{key, user}, ...]` | `snapshot()` - initial roster to a single new subscriber |
+| `join` | `{key, user}` | first `update()` on a (ws, topic) pair |
+| `update` | `{key, data}` | single-mover position frame |
+| `bulk` | `[{key, data}, ...]` | multi-mover coalesced position frame |
+| `remove` | `{key}` | `remove()` or `hooks.close` |
+
+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.
 
 #### Server usage
 
@@ -2802,26 +2832,34 @@ export function close(ws, { platform }) {
 
 ```svelte
 <script>
-  import { cursor } from 'svelte-adapter-uws/plugins/cursor/client';
+  import { cursor, move } from 'svelte-adapter-uws/plugins/cursor/client';
 
   const positions = cursor('canvas');
+
+  function onmousemove(e) {
+    move('canvas', { x: e.clientX, y: e.clientY });
+  }
 </script>
 
-{#each [...$positions] as [key, { user, data }] (key)}
-  <div
-    class="cursor-dot"
-    style="left: {data.x}px; top: {data.y}px; background: {user.color}"
-  >
-    {user.name}
-  </div>
-{/each}
+<div on:mousemove={onmousemove}>
+  {#each [...$positions] as [key, { user, data }] (key)}
+    <div
+      class="cursor-dot"
+      style="left: {data.x}px; top: {data.y}px; background: {user.color}"
+    >
+      {user.name}
+    </div>
+  {/each}
+</div>
 ```
 
-The client store is a `Readable<Map<string, { user, data }>>`. The Map updates when cursors move or disconnect. The store handles `update`, `remove`, `snapshot`, and `bulk` events. The `snapshot` event is authoritative - it replaces all client-side state (used for initial sync and reconnect). The `bulk` event merges entries additively (used by the [extensions repo](https://github.com/lanteanio/svelte-adapter-uws-extensions) topicThrottle feature when flushing coalesced updates).
+`move(topic, data)` is the recommended path for sending cursor updates. Calls are coalesced via `requestAnimationFrame` so even a 1000 Hz high-DPI mouse collapses to at most one send per repaint, matching the server-side `topicThrottle` default. Multi-topic callers do not clobber each other. No-op in non-browser environments.
+
+The client store is a `Readable<Map<string, { user, data }>>`. The Map updates when cursors move, join, or disconnect. Internally the store merges the `catalog`/`join` stream (user metadata) with the `update`/`bulk` stream (positions); positions whose user has not yet been seen are withheld until the matching join arrives - they appear on the next render once the catalog catches up.
 
-**Initial sync and reconnect.** The `cursor(topic)` store sends a `{ type: 'cursor-snapshot', topic }` message every time the WebSocket connection opens - both on first connect and on every reconnect. The server calls `cursors.snapshot(ws, topic, platform)` in its `message` handler, which sends a `snapshot` event back with the current cursor state (or an empty array if nobody is active). The client replaces its entire cursor map with the snapshot contents, clearing any stale entries from before the disconnect. Wire `cursors.snapshot()` in your message handler as shown in the server example above.
+**Initial sync and reconnect.** The `cursor(topic)` store sends a `{ type: 'cursor-snapshot', topic }` message every time the WebSocket connection opens - both on first connect and on every reconnect. The server calls `cursors.snapshot(ws, topic, platform)` in its `message` handler, which sends a `catalog` event (roster) followed by a `bulk` event (positions) back to the requesting client. Late joiners see existing cursors immediately. Wire `cursors.snapshot()` in your message handler as shown in the server example above.
 
-The `cursor()` function accepts an optional second argument with a `maxAge` option (in milliseconds). When set, cursor entries that haven't received an update within that window are automatically removed. This makes clients self-healing when the server fails to broadcast `remove` events under load:
+The `cursor()` function accepts an optional second argument with a `maxAge` option (in milliseconds). When set, cursor entries that haven't received a position update within that window are automatically removed. This makes clients self-healing when the server fails to broadcast `remove` events under load:
 
 ```js
 const positions = cursor('canvas', { maxAge: 30_000 });
@@ -2831,28 +2869,34 @@ const positions = cursor('canvas', { maxAge: 30_000 });
 
 | Method | Description |
 |---|---|
-| `cursors.update(ws, topic, data, platform)` | Broadcast position (throttled) |
-| `cursors.remove(ws, platform)` | Remove from all topics, broadcast removal |
-| `cursors.snapshot(ws, topic, platform)` | Send current positions to one connection (initial sync) |
+| `cursors.update(ws, topic, data, platform)` | Broadcast position (per-cursor + per-topic throttled). Emits `join` once per (ws, topic). |
+| `cursors.remove(ws, platform)` | Remove from all topics, broadcast `remove` per topic |
+| `cursors.snapshot(ws, topic, platform)` | Send current positions to one connection as `catalog` + `bulk` (initial sync) |
 | `cursors.list(topic)` | Current positions (for SSR) |
 | `cursors.clear()` | Reset all state and timers |
 
 #### How throttle works
 
-The cursor plugin uses leading edge + trailing edge throttle internally:
+The cursor plugin uses two layers of leading-edge + trailing-edge throttle:
+
+1. **`throttle`** caps how often a single user broadcasts on a single topic.
+2. **`topicThrottle`** caps how often a topic emits a frame at all. Multiple movers in the same window coalesce into one `bulk` array; a single mover in the window emits one `update`.
 
 ```
-t=0    update({x:0})  --> broadcasts immediately (leading edge)
-t=20   update({x:5})  --> stored (within 50ms window)
-t=40   update({x:9})  --> stored (overwrites x:5)
-t=50   [timer fires]  --> broadcasts {x:9} (trailing edge)
+throttle: 16, topicThrottle: 16
+
+t=0    A.update({x:0})         --> 'join' A, 'update' {x:0}        (leading edge of both)
+t=4    B.update({x:0})         --> 'join' B (catalog channel)
+                                   position queued in topic dirty set
+t=8    A.update({x:5})         --> queued (entry-level throttle says wait until t=16)
+t=16   [trailing timer fires]  --> 'bulk' [{key:A, data:{x:5}}, {key:B, data:{x:0}}]
 ```
 
-The trailing edge ensures you always see where the cursor stopped, even if the user stops moving mid-window.
+The trailing edges ensure you always see where each cursor stopped, even when the user stops moving mid-window.
 
 #### Limitations
 
-- **In-memory.** Cursor positions live in the process. In cluster mode, each worker tracks its own connections.
+- **In-memory.** Cursor positions live in the process. In cluster mode, each worker tracks its own connections. For cross-instance cursor sharing use the Redis-backed variant from the [extensions](https://github.com/lanteanio/svelte-adapter-uws-extensions) package.
 - **No persistence.** Positions are lost on restart. This is intentional - cursors are ephemeral.
 
 ### Queue (ordered delivery)

package/files/handler.js

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

package/index.d.ts

@@ -144,8 +144,8 @@ export interface WebSocketOptions {
 	/**
 	 * Max message size in bytes. Connections sending larger messages are closed.
 	 * Default 1 MB is balanced for typical app payloads in a single frame; uWS
-	 * itself defaults to 16 MB. Lower this for stricter caps (e.g. `16 * 1024`
-	 * for 16 KB) when payload-size discipline matters.
+	 * itself defaults to 16 KB. Lower this for stricter caps (e.g. `16 * 1024`
+	 * for the uWS-matching 16 KB) when payload-size discipline matters.
 	 * @default 1048576 (1 MB)
 	 */
 	maxPayloadLength?: number;
@@ -517,6 +517,26 @@ export interface MessageContext {
 	data: ArrayBuffer;
 	/** Whether the message is binary. */
 	isBinary: boolean;
+	/**
+	 * The JSON-parsed envelope, when the adapter parsed the frame for
+	 * control-message routing (subscribe / unsubscribe / hello / resume /
+	 * reply / subscribe-batch) but no control type matched.
+	 *
+	 * Plugin-layer JSON envelope dispatchers (e.g. svelte-realtime's
+	 * `createMessage({ onJsonMessage })`) consume this directly instead of
+	 * re-running `TextDecoder + JSON.parse` on every frame.
+	 *
+	 * `undefined` when:
+	 * - the frame is binary (`isBinary === true`), or
+	 * - the frame did not start with `{"ty` (byte[3] !== 0x79), or
+	 * - the frame was larger than 8 KiB, or
+	 * - `JSON.parse` threw, or
+	 * - the parsed value was not a plain object (null / array / primitive).
+	 *
+	 * The adapter's `websocket.maxPayloadLength` (default 1 MB) is the
+	 * structural ceiling for frame size; this field adds no separate cap.
+	 */
+	msg?: any;
 	/** The platform API - publish, send, topic helpers, etc. */
 	platform: Platform;
 }

package/index.js

@@ -282,16 +282,16 @@ export default function (opts = {}) {
 				);
 			}
 			const wsOpts = {
-				// Default raised from 16 KB to 1 MB in next.19. uWS itself
-				// defaults to 16 MB; 16 KB was excessively conservative and
-				// forced chunked-upload frameworks to use ~12 KB chunks
-				// (~9000 chunks for a 100 MB file). 1 MB handles typical app
+				// Default raised from 16 KB to 1 MB in 0.5. uWS's own
+				// default is also 16 KB, which the adapter previously
+				// matched - that was excessively conservative and forced
+				// chunked-upload frameworks to use ~12 KB chunks (~9000
+				// chunks for a 100 MB file). 1 MB handles typical app
 				// payloads in a single frame without per-app tuning. DoS
-				// exposure is bounded
-				// by `upgradeAdmission.maxConcurrent` (connection count)
-				// and `maxBackpressure` (per-conn outbound queue, also
-				// 1 MB), so per-frame cost stays predictable. Apps that
-				// want a stricter cap can pin via
+				// exposure is bounded by `upgradeAdmission.maxConcurrent`
+				// (connection count) and `maxBackpressure` (per-conn
+				// outbound queue, also 1 MB), so per-frame cost stays
+				// predictable. Apps that want a stricter cap can pin via
 				// `websocket.maxPayloadLength` in svelte.config.js.
 				maxPayloadLength: websocket?.maxPayloadLength ?? 1024 * 1024,
 				idleTimeout: websocket?.idleTimeout ?? 120,

package/package.json

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

package/plugins/cursor/client.d.ts

@@ -1,34 +1,54 @@
-import type { Readable } from 'svelte/store';
-
-export interface CursorPosition<UserInfo = unknown, Data = unknown> {
-	/** User-identifying data from the server's `select` function. */
-	user: UserInfo;
-	/** Latest cursor/position data. */
-	data: Data;
-}
-
-/**
- * Get a reactive store of cursor positions on a topic.
- *
- * Returns a `Readable<Map<string, CursorPosition>>` that updates
- * automatically when cursors move or disconnect.
- *
- * @example
- * ```svelte
- * <script>
- *   import { cursor } from 'svelte-adapter-uws/plugins/cursor/client';
- *
- *   const cursors = cursor('canvas');
- * </script>
- *
- * {#each [...$cursors] as [key, { user, data }] (key)}
- *   <div style="left: {data.x}px; top: {data.y}px">
- *     {user.name}
- *   </div>
- * {/each}
- * ```
- */
-export function cursor<UserInfo = unknown, Data = unknown>(
-	topic: string,
-	options?: { maxAge?: number }
-): Readable<Map<string, CursorPosition<UserInfo, Data>>>;
+import type { Readable } from 'svelte/store';
+
+export interface CursorPosition<UserInfo = unknown, Data = unknown> {
+	/** User-identifying data from the server's `select` function. */
+	user: UserInfo;
+	/** Latest cursor/position data. */
+	data: Data;
+}
+
+/**
+ * Get a reactive store of cursor positions on a topic.
+ *
+ * Returns a `Readable<Map<string, CursorPosition>>` that updates
+ * automatically when cursors move, join, or disconnect. Internally
+ * merges the `catalog` (user metadata) and `update`/`bulk` (positions)
+ * streams; entries are emitted only after both user and position are
+ * known.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { cursor, move } from 'svelte-adapter-uws/plugins/cursor/client';
+ *
+ *   const cursors = cursor('canvas');
+ *
+ *   function onmousemove(e) {
+ *     move('canvas', { x: e.clientX, y: e.clientY });
+ *   }
+ * </script>
+ *
+ * <div on:mousemove={onmousemove}>
+ *   {#each [...$cursors] as [key, { user, data }] (key)}
+ *     <div style="left: {data.x}px; top: {data.y}px">
+ *       {user.name}
+ *     </div>
+ *   {/each}
+ * </div>
+ * ```
+ */
+export function cursor<UserInfo = unknown, Data = unknown>(
+	topic: string,
+	options?: { maxAge?: number }
+): Readable<Map<string, CursorPosition<UserInfo, Data>>>;
+
+/**
+ * Send a cursor move on a topic. Frames are coalesced via
+ * `requestAnimationFrame` so calling `move()` at 1000 Hz (high-DPI
+ * mouse) collapses to at most one send per repaint, matching the
+ * server-side `topicThrottle` default. Multi-topic callers do not
+ * clobber each other.
+ *
+ * No-op in non-browser environments.
+ */
+export function move(topic: string, data: unknown): void;