svelte-adapter-uws 0.5.1 → 0.5.2

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.
 
@@ -2755,14 +2755,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 +2819,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.
 
-**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.
+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.
 
-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:
+**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 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 +2856,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/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;

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.2",
   "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;

package/plugins/cursor/client.js

@@ -5,10 +5,23 @@
  * a live Map of cursor positions. The server handles throttling and
  * cleanup; this module keeps the client-side state in sync.
  *
- * When `maxAge` is 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 a `remove` event
- * (e.g. mass disconnects overwhelming Redis cleanup).
+ * Wire shape (catalog / positions split):
+ *   - `catalog`  [{key, user}]  - roster sent on snapshot to a fresh
+ *                                  subscriber. Replaces local user map.
+ *   - `join`     {key, user}    - new user announced on the topic.
+ *   - `update`   {key, data}    - single-mover position frame.
+ *   - `bulk`     [{key, data}]  - multi-mover coalesced position frame.
+ *   - `remove`   {key}          - user gone (catalog + positions cleared).
+ *
+ * User metadata lives on the catalog channel (catalog + join), positions
+ * live on the update/bulk channel. The merge happens here: the public
+ * Readable yields `Map<key, {user, data}>`, skipping any position whose
+ * user has not yet been seen via catalog/join.
+ *
+ * When `maxAge` is 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 a `remove`
+ * event (e.g. mass disconnects overwhelming Redis cleanup).
  *
  * @module svelte-adapter-uws/plugins/cursor/client
  */
@@ -26,7 +39,7 @@ const cursorStores = new Map();
  *
  * Returns a readable Svelte store containing a Map of connection keys
  * to `{ user, data }` objects. The Map updates automatically when
- * cursors move or disconnect.
+ * cursors move, join, or disconnect.
  *
  * @template UserInfo, Data
  * @param {string} topic - Topic to track cursors on
@@ -36,22 +49,28 @@ const cursorStores = new Map();
  * @example
  * ```svelte
  * <script>
- *   import { cursor } from 'svelte-adapter-uws/plugins/cursor/client';
+ *   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>
  *
- * {#each [...$cursors] as [key, { user, data }] (key)}
- *   <div style="left: {data.x}px; top: {data.y}px" class="cursor">
- *     {user.name}
- *   </div>
- * {/each}
+ * <div on:mousemove={onmousemove}>
+ *   {#each [...$cursors] as [key, { user, data }] (key)}
+ *     <div style="left: {data.x}px; top: {data.y}px" class="cursor">
+ *       {user.name}
+ *     </div>
+ *   {/each}
+ * </div>
  * ```
  *
  * @example
  * ```svelte
  * <script>
- *   // Self-healing: cursors expire after 30s without movement
+ *   // Self-healing: cursors expire after 30s without a position update.
  *   const cursors = cursor('canvas', { maxAge: 30_000 });
  * </script>
  * ```
@@ -65,8 +84,10 @@ export function cursor(topic, options) {
 
 	const cursorTopic = TOPIC_PREFIX + topic;
 
-	/** @type {Map<string, { user: any, data: any }>} */
-	let cursorMap = new Map();
+	/** @type {Map<string, any>} */
+	let positionMap = new Map();
+	/** @type {Map<string, any>} */
+	let userMap = new Map();
 	/** @type {Map<string, number>} */
 	const timestamps = new Map();
 	const output = writable(/** @type {Map<string, any>} */ (new Map()));
@@ -78,6 +99,16 @@ export function cursor(topic, options) {
 	let refCount = 0;
 	let cancelled = false;
 
+	function emitOutput() {
+		const merged = new Map();
+		for (const [key, data] of positionMap) {
+			const user = userMap.get(key);
+			if (user === undefined) continue;
+			merged.set(key, { user, data });
+		}
+		output.set(merged);
+	}
+
 	function sweep() {
 		if (!maxAge || maxAge <= 0) return;
 		const cutoff = Date.now() - maxAge;
@@ -85,10 +116,11 @@ export function cursor(topic, options) {
 		for (const [key, ts] of timestamps) {
 			if (ts < cutoff) {
 				timestamps.delete(key);
-				if (cursorMap.delete(key)) changed = true;
+				if (positionMap.delete(key)) changed = true;
+				userMap.delete(key);
 			}
 		}
-		if (changed) output.set(new Map(cursorMap));
+		if (changed) emitOutput();
 	}
 
 	function startListening() {
@@ -97,44 +129,55 @@ export function cursor(topic, options) {
 		sourceUnsub = source.subscribe((event) => {
 			if (event === null) return;
 
-			if (event.event === 'update' && event.data != null) {
-				const { key, user, data } = event.data;
-				cursorMap.set(key, { user, data });
-				timestamps.set(key, Date.now());
-				output.set(new Map(cursorMap));
+			if (event.event === 'catalog' && Array.isArray(event.data)) {
+				userMap = new Map();
+				for (const entry of event.data) {
+					if (entry && typeof entry.key === 'string') {
+						userMap.set(entry.key, entry.user);
+					}
+				}
+				emitOutput();
 				return;
 			}
 
-			if (event.event === 'snapshot' && Array.isArray(event.data)) {
-				cursorMap = new Map();
-				timestamps.clear();
-				const now = Date.now();
-				for (const entry of event.data) {
-					const { key, user, data } = entry;
-					cursorMap.set(key, { user, data });
-					timestamps.set(key, now);
+			if (event.event === 'join' && event.data != null) {
+				const { key, user } = event.data;
+				if (typeof key === 'string') {
+					userMap.set(key, user);
+					emitOutput();
+				}
+				return;
+			}
+
+			if (event.event === 'update' && event.data != null) {
+				const { key, data } = event.data;
+				if (typeof key === 'string') {
+					positionMap.set(key, data);
+					timestamps.set(key, Date.now());
+					emitOutput();
 				}
-				output.set(new Map(cursorMap));
 				return;
 			}
 
 			if (event.event === 'bulk' && Array.isArray(event.data)) {
 				const now = Date.now();
 				for (const entry of event.data) {
-					const { key, user, data } = entry;
-					cursorMap.set(key, { user, data });
-					timestamps.set(key, now);
+					if (entry && typeof entry.key === 'string') {
+						positionMap.set(entry.key, entry.data);
+						timestamps.set(entry.key, now);
+					}
 				}
-				output.set(new Map(cursorMap));
+				emitOutput();
 				return;
 			}
 
 			if (event.event === 'remove' && event.data != null) {
 				const { key } = event.data;
+				if (typeof key !== 'string') return;
 				timestamps.delete(key);
-				if (cursorMap.delete(key)) {
-					output.set(new Map(cursorMap));
-				}
+				const hadPosition = positionMap.delete(key);
+				const hadUser = userMap.delete(key);
+				if (hadPosition || hadUser) emitOutput();
 			}
 		});
 
@@ -166,7 +209,8 @@ export function cursor(topic, options) {
 			clearInterval(sweepTimer);
 			sweepTimer = null;
 		}
-		cursorMap = new Map();
+		positionMap = new Map();
+		userMap = new Map();
 		timestamps.clear();
 		// Push the cleared state to the output store so a new subscriber does
 		// not see ghost cursors from the previous subscription cycle.
@@ -196,3 +240,58 @@ export function cursor(topic, options) {
 
 	return store;
 }
+
+/**
+ * Internal coalesce buffer for `move()`. One entry per topic; latest-
+ * wins inside a single animation frame. Flushed on the next rAF tick.
+ * @type {Map<string, any>}
+ */
+const movePending = new Map();
+let moveScheduled = false;
+
+// Resolve `requestAnimationFrame` at call time so a polyfill installed
+// after this module imports (or a test harness substitution) is honored.
+function scheduleFrame(cb) {
+	if (typeof requestAnimationFrame !== 'undefined') return requestAnimationFrame(cb);
+	return setTimeout(cb, 16);
+}
+
+/**
+ * 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.
+ *
+ * @param {string} topic
+ * @param {any} data
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { move } from 'svelte-adapter-uws/plugins/cursor/client';
+ *
+ *   function onmousemove(e) {
+ *     move('canvas', { x: e.clientX, y: e.clientY });
+ *   }
+ * </script>
+ *
+ * <div on:mousemove={onmousemove}> ... </div>
+ * ```
+ */
+export function move(topic, data) {
+	if (typeof window === 'undefined') return;
+	movePending.set(topic, data);
+	if (moveScheduled) return;
+	moveScheduled = true;
+	scheduleFrame(() => {
+		moveScheduled = false;
+		const conn = connect();
+		for (const [t, d] of movePending) {
+			conn.send({ type: 'cursor', topic: t, data: d });
+		}
+		movePending.clear();
+	});
+}

package/plugins/cursor/server.d.ts

@@ -6,14 +6,33 @@ export interface CursorOptions<UserData = unknown, UserInfo = unknown> {
 	 * Minimum milliseconds between broadcasts per user per topic.
 	 * A trailing-edge timer ensures the final position is always sent.
 	 *
-	 * @default 50
+	 * Lower for high-refresh demos (8 = 120 Hz), higher to conserve
+	 * bandwidth (33 = 30 Hz). Set to 0 to disable.
+	 *
+	 * @default 16 (~60 Hz)
 	 */
 	throttle?: number;
 
+	/**
+	 * Per-topic aggregate coalesce window in ms. Each topic emits at
+	 * most one frame per window, carrying the latest position for every
+	 * cursor that moved (a single `update` when one mover is dirty, a
+	 * `bulk` array otherwise). Bandwidth per peer scales with active-
+	 * mover count, not with mover-count times per-mover rate.
+	 *
+	 * Raise (e.g. 33 = 30 Hz) for high-density rooms where wire bytes
+	 * dominate. Lower (e.g. 8 = 120 Hz) for high-refresh demos. 0
+	 * disables coalescing; per-cursor `throttle` then governs broadcast
+	 * rate.
+	 *
+	 * @default 16 (~60 Hz)
+	 */
+	topicThrottle?: number;
+
 	/**
 	 * Extract user-identifying data from a connection's userData.
-	 * This is broadcast alongside the cursor data so other clients
-	 * know who the cursor belongs to.
+	 * This is announced on the `catalog` / `join` channel when a user
+	 * first appears on a topic, not on every position frame.
 	 *
 	 * Defaults to the full userData object.
 	 *
@@ -41,8 +60,8 @@ export interface CursorOptions<UserData = unknown, UserInfo = unknown> {
 	/**
 	 * Hard cap on the active topic registry. When the cap is reached,
 	 * the oldest insertion-order topic is dropped on the next `update()`
-	 * for a new topic; any pending throttle timers on the dropped topic
-	 * are cleared first.
+	 * for a new topic; any pending throttle and coalesce timers on the
+	 * dropped topic are cleared first.
 	 *
 	 * @default 1_000_000
 	 */
@@ -83,7 +102,12 @@ export interface CursorEntry<UserInfo = unknown, Data = unknown> {
 
 export interface CursorTracker<UserInfo = unknown> {
 	/**
-	 * Broadcast a cursor position update. Throttled per user per topic.
+	 * Broadcast a cursor position update. Throttled per user per topic
+	 * and optionally coalesced per topic via `topicThrottle`.
+	 *
+	 * The first call for a (ws, topic) pair also emits a `join` event
+	 * carrying the user's catalog entry; subsequent calls emit only
+	 * positions (`update` or `bulk`).
 	 *
 	 * Call this from your `message` hook when you receive cursor data.
 	 *
@@ -112,14 +136,16 @@ export interface CursorTracker<UserInfo = unknown> {
 	list(topic: string): CursorEntry<UserInfo>[];
 
 	/**
-	 * Send current cursor positions for a topic to a single connection.
+	 * Send current cursor positions for a topic to a single connection
+	 * as a `catalog` + `bulk` pair (roster, then positions).
 	 *
 	 * Call this from your `message` handler when the client sends a
 	 * `{ type: 'cursor-snapshot', topic }` request. The `cursor()` client
 	 * store sends this automatically on subscribe, so late joiners see
 	 * existing cursors immediately without waiting for the next move event.
 	 *
-	 * Does nothing if the topic has no active cursors.
+	 * Sends an empty `catalog` and `bulk` when the topic has no active
+	 * cursors.
 	 *
 	 * @example
 	 * ```js
@@ -169,7 +195,8 @@ export interface CursorTracker<UserInfo = unknown> {
  * import { createCursor } from 'svelte-adapter-uws/plugins/cursor';
  *
  * export const cursors = createCursor({
- *   throttle: 50,
+ *   throttle: 16,        // 60 Hz per-cursor rate (default)
+ *   topicThrottle: 16,   // 60 Hz per-topic coalescing (default)
  *   select: (userData) => ({ id: userData.id, name: userData.name })
  * });
  * ```

package/plugins/cursor/server.js

@@ -9,6 +9,24 @@
  * Zero impact on the adapter core - this is a standalone module that
  * uses platform.publish() and platform.send().
  *
+ * Wire shape (channel `__cursor:{topic}`):
+ *   - `catalog`  [{key, user}, ...]  - sent on snapshot() to a single
+ *                                      newly-attaching subscriber.
+ *   - `join`     {key, user}         - emitted once per (ws, topic) the
+ *                                      first time that ws updates on the
+ *                                      topic. Broadcast to all subscribers.
+ *   - `update`   {key, data}         - single-mover position update.
+ *   - `bulk`     [{key, data}, ...]  - per-topic coalesced positions when
+ *                                      `topicThrottle` is enabled and >1
+ *                                      mover is pending in the window.
+ *   - `remove`   {key}               - user is gone from the topic.
+ *
+ * User metadata (the `select()`ed userData) lives on the catalog channel
+ * (catalog + join), not on every position frame. This matches the
+ * cluster-aware Redis-backed variant in the extensions package so a
+ * single browser bundle (`plugins/cursor/client`) works against either
+ * backend.
+ *
  * MULTI-TENANT NOTE
  * Cursor state is keyed by the topic name verbatim. Apps running
  * multiple tenants in one process must namespace topic names with
@@ -20,16 +38,37 @@
 
 const TOPIC_PREFIX = '__cursor:';
 
+/** Wire-protocol event names. */
+const EVENTS = Object.freeze({
+	CATALOG: 'catalog',
+	JOIN: 'join',
+	UPDATE: 'update',
+	BULK: 'bulk',
+	REMOVE: 'remove'
+});
+
 /**
  * @typedef {Object} CursorOptions
- * @property {number} [throttle=50] - Minimum milliseconds between broadcasts per
- *   user per topic. A trailing-edge timer fires to ensure the final position is
- *   always sent even if the user stops moving.
- * @property {(userData: any) => any} [select] - Extract user-identifying data from
- *   the connection's userData. This is broadcast alongside the cursor data so other
- *   clients know who the cursor belongs to. Defaults to the full userData.
- *   Should return JSON-serializable data (plain objects, arrays, strings, numbers,
- *   booleans, null). The same applies to the `data` argument passed to `update()`.
+ * @property {number} [throttle=16] - Minimum milliseconds between broadcasts
+ *   per user per topic. A trailing-edge timer fires to ensure the final
+ *   position is always sent. Default 16 (~60 Hz) suits collaborative
+ *   apps; lower (e.g. 8 for 120 Hz) for high-refresh demos, higher to
+ *   conserve bandwidth.
+ * @property {number} [topicThrottle=16] - World-state tick rate, in ms.
+ *   Per-topic aggregate cap on broadcasts: each topic emits at most one
+ *   frame per window, carrying the latest position for every cursor that
+ *   moved (a single `update` when one mover is dirty, a `bulk` array
+ *   otherwise). Bandwidth per peer scales with active-mover count, not
+ *   with mover-count times per-mover rate. Default 16 (~60 Hz) suits
+ *   small-to-medium rooms; raise to 33 (~30 Hz) for high-density rooms
+ *   where wire bytes dominate. 0 disables the tick; per-cursor `throttle`
+ *   then governs broadcast rate.
+ * @property {(userData: any) => any} [select] - Extract user-identifying data
+ *   from the connection's userData. This is announced on the `catalog` /
+ *   `join` channel when a user first appears on a topic. Defaults to the
+ *   full userData. Should return JSON-serializable data (plain objects,
+ *   arrays, strings, numbers, booleans, null). The same applies to the
+ *   `data` argument passed to `update()`.
  */
 
 /**
@@ -42,8 +81,9 @@ const TOPIC_PREFIX = '__cursor:';
 /**
  * @typedef {Object} CursorTracker
  * @property {(ws: any, topic: string, data: any, platform: import('../../index.js').Platform) => void} update -
- *   Broadcast a cursor position update. Throttled per user per topic.
- *   Call this from your `message` hook when you receive cursor data.
+ *   Broadcast a cursor position update. Throttled per user per topic and
+ *   optionally coalesced per topic. Call this from your `message` hook
+ *   when you receive cursor data.
  * @property {(ws: any, platform: import('../../index.js').Platform) => void} remove -
  *   Remove a connection's cursor state from all topics and broadcast removal.
  *   Call this from your `close` hook.
@@ -51,6 +91,12 @@ const TOPIC_PREFIX = '__cursor:';
  *   Get current cursor positions for a topic. Use in load() functions for SSR.
  *   Returns deep copies (via structuredClone) when data is JSON-serializable.
  *   Falls back to shared references for non-cloneable data.
+ * @property {(ws: any, topic: string, platform: import('../../index.js').Platform) => void} snapshot -
+ *   Send current cursor positions for a topic to a single connection as
+ *   a `catalog` + `bulk` pair (roster, then positions). Call from your
+ *   `message` handler when the client sends `{type: 'cursor-snapshot',
+ *   topic}`. The `cursor()` client store sends this automatically on
+ *   subscribe so late joiners see existing cursors immediately.
  * @property {() => void} clear -
  *   Clear all cursor tracking state and pending timers.
  */
@@ -67,13 +113,20 @@ const TOPIC_PREFIX = '__cursor:';
  * import { createCursor } from 'svelte-adapter-uws/plugins/cursor';
  *
  * export const cursors = createCursor({
- *   throttle: 50,
+ *   throttle: 16,        // 60 Hz per-cursor rate (default)
+ *   topicThrottle: 16,   // 60 Hz per-topic coalescing (default)
  *   select: (userData) => ({ id: userData.id, name: userData.name, color: userData.color })
  * });
  * ```
  *
  * @example
  * ```js
+ * // 120 Hz demo: halve both intervals
+ * createCursor({ throttle: 8, topicThrottle: 8 });
+ * ```
+ *
+ * @example
+ * ```js
  * // src/hooks.ws.js - using hooks helper
  * import { cursors } from '$lib/server/cursors';
  *
@@ -86,7 +139,8 @@ const TOPIC_PREFIX = '__cursor:';
  * ```
  */
 export function createCursor(options = {}) {
-	const throttleMs = options.throttle ?? 50;
+	const throttleMs = options.throttle ?? 16;
+	const topicThrottleMs = options.topicThrottle ?? 16;
 	const select = options.select || ((userData) => userData);
 	const maxConnections = options.maxConnections ?? 1_000_000;
 	const maxTopics = options.maxTopics ?? 1_000_000;
@@ -96,6 +150,9 @@ export function createCursor(options = {}) {
 	if (typeof throttleMs !== 'number' || !Number.isFinite(throttleMs) || throttleMs < 0) {
 		throw new Error('cursor: throttle must be a non-negative number');
 	}
+	if (typeof topicThrottleMs !== 'number' || !Number.isFinite(topicThrottleMs) || topicThrottleMs < 0) {
+		throw new Error('cursor: topicThrottle must be a non-negative number');
+	}
 	if (typeof select !== 'function') {
 		throw new Error('cursor: select must be a function');
 	}
@@ -116,7 +173,9 @@ export function createCursor(options = {}) {
 	let connCounter = 0;
 
 	/**
-	 * Per-ws state: their key and which topics they have cursor state on.
+	 * Per-ws state: connection key, selected user data, and which topics
+	 * this ws has already announced (the `topics` set doubles as the
+	 * already-joined set - presence in the set means a `join` has fired).
 	 * Capped at `maxConnections` - oldest insertion-order entry evicted
 	 * on new insert at cap. Eviction is rare in practice because user
 	 * code is expected to call `remove(ws)` on disconnect.
@@ -125,14 +184,23 @@ export function createCursor(options = {}) {
 	const wsState = new Map();
 
 	/**
-	 * Per-topic cursor positions. Capped at `maxTopics` - oldest
+	 * Per-topic local cursor state. Drives the per-(ws, topic) throttle
+	 * and the post-disconnect cleanup. Capped at `maxTopics` - oldest
 	 * insertion-order topic evicted on new insert at cap. Each evicted
-	 * topic's pending timers are cleared first so no callback fires on
-	 * a deleted entry.
+	 * topic's pending throttle and coalesce timers are cleared first.
 	 * @type {Map<string, Map<string, { user: any, data: any, lastBroadcast: number, timer: any }>>}
 	 */
 	const topics = new Map();
 
+	/**
+	 * Per-topic aggregate throttle state for `topicThrottle` coalescing.
+	 * Dirty entries are keyed by connection key; latest-wins. When the
+	 * coalesce window elapses, `dirty.size === 1` sends a single `update`
+	 * and any other count sends one `bulk` array.
+	 * @type {Map<string, { lastFlush: number, timer: any, dirty: Map<string, { data: any, platform: any }> }>}
+	 */
+	const topicFlush = new Map();
+
 	/**
 	 * Get or create ws state and return the connection key + user data.
 	 * @param {any} ws
@@ -156,15 +224,100 @@ export function createCursor(options = {}) {
 	}
 
 	/**
-	 * Broadcast a cursor update for a specific entry.
+	 * Drop the topic's coalesce state (clears any pending timer first).
+	 * @param {string} topic
+	 */
+	function clearTopicFlush(topic) {
+		const flushState = topicFlush.get(topic);
+		if (!flushState) return;
+		if (flushState.timer) clearTimeout(flushState.timer);
+		topicFlush.delete(topic);
+	}
+
+	/**
+	 * 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 });
+	}
+
+	/**
+	 * Publish a single-mover position update.
 	 * @param {string} topic
 	 * @param {string} key
-	 * @param {any} user
 	 * @param {any} data
 	 * @param {import('../../index.js').Platform} platform
 	 */
-	function broadcast(topic, key, user, data, platform) {
-		platform.publish(TOPIC_PREFIX + topic, 'update', { key, user, data });
+	function doBroadcast(topic, key, data, platform) {
+		platform.publish(TOPIC_PREFIX + topic, EVENTS.UPDATE, { key, data });
+	}
+
+	/**
+	 * Flush all coalesced entries for a topic. One entry -> `update`,
+	 * many entries -> single `bulk` array.
+	 * @param {string} topic
+	 * @param {Map<string, { data: any, platform: any }>} dirty
+	 */
+	function flushDirty(topic, dirty) {
+		if (dirty.size === 0) return;
+		if (dirty.size === 1) {
+			const [k, v] = dirty.entries().next().value;
+			doBroadcast(topic, k, v.data, v.platform);
+			return;
+		}
+		const entries = [];
+		let flushPlatform = null;
+		for (const [k, v] of dirty) {
+			entries.push({ key: k, data: v.data });
+			flushPlatform = v.platform;
+		}
+		if (flushPlatform) {
+			flushPlatform.publish(TOPIC_PREFIX + topic, EVENTS.BULK, entries);
+		}
+	}
+
+	/**
+	 * Route a broadcast through the per-topic coalesce window when
+	 * `topicThrottle` is enabled, or directly publish when disabled.
+	 */
+	function broadcast(topic, key, data, platform) {
+		if (topicThrottleMs <= 0) {
+			doBroadcast(topic, key, data, platform);
+			return;
+		}
+
+		let state = topicFlush.get(topic);
+		if (!state) {
+			state = { lastFlush: 0, timer: null, dirty: new Map() };
+			topicFlush.set(topic, state);
+		}
+
+		state.dirty.set(key, { data, platform });
+
+		const now = Date.now();
+		if (now - state.lastFlush >= topicThrottleMs) {
+			if (state.timer) {
+				clearTimeout(state.timer);
+				state.timer = null;
+			}
+			state.lastFlush = now;
+			flushDirty(topic, state.dirty);
+			state.dirty.clear();
+			return;
+		}
+
+		if (!state.timer) {
+			state.timer = setTimeout(() => {
+				const s = topicFlush.get(topic);
+				if (!s) return;
+				s.timer = null;
+				s.lastFlush = Date.now();
+				flushDirty(topic, s.dirty);
+				s.dirty.clear();
+			}, topicThrottleMs - (now - state.lastFlush));
+		}
 	}
 
 	/** @type {CursorTracker} */
@@ -187,6 +340,7 @@ export function createCursor(options = {}) {
 				if (dataBytes > maxDataBytes) return;
 			}
 			const state = getWsState(ws);
+			const isFirstOnTopic = !state.topics.has(topic);
 			state.topics.add(topic);
 
 			let topicMap = topics.get(topic);
@@ -201,12 +355,17 @@ export function createCursor(options = {}) {
 							}
 						}
 						topics.delete(oldest);
+						clearTopicFlush(oldest);
 					}
 				}
 				topicMap = new Map();
 				topics.set(topic, topicMap);
 			}
 
+			if (isFirstOnTopic) {
+				emitJoin(topic, state.key, state.user, platform);
+			}
+
 			let entry = topicMap.get(state.key);
 			const now = Date.now();
 
@@ -226,20 +385,19 @@ export function createCursor(options = {}) {
 					entry.timer = null;
 				}
 				entry.lastBroadcast = now;
-				broadcast(topic, state.key, state.user, data, platform);
+				broadcast(topic, state.key, data, platform);
 				return;
 			}
 
 			// Trailing edge: schedule a broadcast for the end of the window
 			if (!entry.timer) {
 				const key = state.key;
-				const user = state.user;
 				entry.timer = setTimeout(() => {
 					const e = topicMap.get(key);
 					if (e) {
 						e.lastBroadcast = Date.now();
 						e.timer = null;
-						broadcast(topic, key, user, e.data, platform);
+						broadcast(topic, key, e.data, platform);
 					}
 				}, throttleMs - (now - entry.lastBroadcast));
 			}
@@ -259,8 +417,12 @@ export function createCursor(options = {}) {
 					topicMap.delete(state.key);
 					if (topicMap.size === 0) {
 						topics.delete(topic);
+						clearTopicFlush(topic);
+					} else {
+						const flushState = topicFlush.get(topic);
+						if (flushState) flushState.dirty.delete(state.key);
 					}
-					platform.publish(TOPIC_PREFIX + topic, 'remove', { key: state.key });
+					platform.publish(TOPIC_PREFIX + topic, EVENTS.REMOVE, { key: state.key });
 				}
 			}
 
@@ -273,30 +435,36 @@ export function createCursor(options = {}) {
 			const result = [];
 			for (const [key, entry] of topicMap) {
 				const item = { key, user: entry.user, data: entry.data };
-			try { result.push(structuredClone(item)); } catch { result.push(item); }
+				try { result.push(structuredClone(item)); } catch { result.push(item); }
 			}
 			return result;
 		},
 
 		snapshot(ws, topic, platform) {
 			const topicMap = topics.get(topic);
-			const entries = [];
+			const catalog = [];
+			const positions = [];
 			if (topicMap) {
 				for (const [key, entry] of topicMap) {
-					entries.push({ key, user: entry.user, data: entry.data });
+					catalog.push({ key, user: entry.user });
+					positions.push({ key, data: entry.data });
 				}
 			}
-			platform.send(ws, TOPIC_PREFIX + topic, 'snapshot', entries);
+			platform.send(ws, TOPIC_PREFIX + topic, EVENTS.CATALOG, catalog);
+			platform.send(ws, TOPIC_PREFIX + topic, EVENTS.BULK, positions);
 		},
 
 		clear() {
-			// Clear all timers
 			for (const [, topicMap] of topics) {
 				for (const [, entry] of topicMap) {
 					if (entry.timer) clearTimeout(entry.timer);
 				}
 			}
+			for (const [, state] of topicFlush) {
+				if (state.timer) clearTimeout(state.timer);
+			}
 			topics.clear();
+			topicFlush.clear();
 			wsState.clear();
 			connCounter = 0;
 		},