svelte-adapter-uws 0.5.5 → 0.5.7

package/MIGRATION.md

@@ -145,9 +145,9 @@ These change observable runtime behavior. Most apps are unaffected; a few will n
 
 ### Presence plugin wire format switched to a compact diff protocol
 
-**What changed.** The five-event format (`list` / `join` / `updated` / `leave` / `heartbeat`) collapses to two diff-shaped events plus the existing heartbeat: `presence_state` (full snapshot) and `presence_diff` (joins/leaves). Diffs are microtask-batched. Server and client ship in one bundle, so a single-package upgrade is seamless.
+**What changed.** The five-event format (`list` / `join` / `updated` / `leave` / `heartbeat`) collapses to two diff-shaped events plus the existing heartbeat: `state` (full snapshot) and `diff` (joins/leaves). Diffs are microtask-batched. Server and client ship in one bundle, so a single-package upgrade is seamless.
 
-**How to migrate.** No action needed for users of the bundled `presence()` Svelte store on the client. Hand-rolled clients that consume the wire directly need to switch decoders to handle `presence_state` and `presence_diff` events. Stale browser tabs from a previous deploy will see a blank presence list until refresh.
+**How to migrate.** No action needed for users of the bundled `presence()` Svelte store on the client. Hand-rolled clients that consume the wire directly need to switch decoders to handle `state` and `diff` events. Stale browser tabs from a previous deploy will see a blank presence list until refresh.
 
 ### Wire single-subscribe frames consult `subscribeBatch` when only `subscribeBatch` is exported
 

package/README.md

@@ -2476,7 +2476,7 @@ presence.leave(ws, platform)         // remove from all topics (call from close
 presence.sync(ws, topic, platform)   // send snapshot without joining (for observers)
 presence.list(topic)                 // current user data array
 presence.count(topic)                // unique user count
-presence.flushDiffs()                // drain buffered presence_diff publishes synchronously
+presence.flushDiffs()                // drain buffered diff publishes synchronously
 presence.clear()                     // reset everything (stops heartbeat timer)
 ```
 
@@ -2484,9 +2484,9 @@ presence.clear()                     // reset everything (stops heartbeat timer)
 
 The plugin emits three frame types on the `__presence:{topic}` channel:
 
-- `{event: 'presence_state', data: {[key]: meta}}` - full snapshot, sent to a single connection on join or sync.
-- `{event: 'presence_diff', data: {joins: {[key]: meta}, leaves: {[key]: meta}}}` - changes, broadcast to all subscribers of the topic.
-- `{event: 'heartbeat', data: {[key]: meta}}` - periodic full-roster refresh, broadcast every `heartbeat` ms (30 s default). Carries a `{userKey: data}` map so a client whose entry aged out of its local `maxAge` sweep can re-add it from the heartbeat alone, without waiting for the next `presence_diff`.
+- `{event: 'state', data: {[key]: meta}}` - full snapshot, sent to a single connection on join or sync.
+- `{event: 'diff', data: {joins: {[key]: meta}, leaves: {[key]: meta}}}` - changes, broadcast to all subscribers of the topic.
+- `{event: 'heartbeat', data: {[key]: meta}}` - periodic full-roster refresh, broadcast every `heartbeat` ms (30 s default). Carries a `{userKey: data}` map so a client whose entry aged out of its local `maxAge` sweep can re-add it from the heartbeat alone, without waiting for the next `diff`.
 
 Diffs are buffered in a microtask queue: multiple joins / leaves in the same tick collapse into one diff frame. Within a diff, `leaves` are applied first then `joins`, so an update (same key in both) ends with the user present using the new data. If a key cycles join then leave in the same tick, the diff carries only the latest op (`leave` wins).
 
@@ -2501,7 +2501,7 @@ const users = presence('room');
 // $users = [{ id: '1', name: 'Alice' }, { id: '2', name: 'Bob' }]
 ```
 
-The client store defaults to a 90 s `maxAge` sweep: entries that haven't been refreshed by a heartbeat or `presence_diff` / `presence_state` inside the window are removed from the local map. With the server's 30 s default heartbeat, still-present users are refreshed three times per window and never flicker; ghost entries left over by silent server-side cleanup (cluster mass-disconnect, ungraceful client close) clear within one sweep window.
+The client store defaults to a 90 s `maxAge` sweep: entries that haven't been refreshed by a heartbeat or `diff` / `state` inside the window are removed from the local map. With the server's 30 s default heartbeat, still-present users are refreshed three times per window and never flicker; ghost entries left over by silent server-side cleanup (cluster mass-disconnect, ungraceful client close) clear within one sweep window.
 
 For admin / audit views that want unbounded retention ("show every user who ever touched this topic"), opt out with `maxAge: 0`:
 
@@ -2898,22 +2898,23 @@ const positions = cursor('canvas', { maxAge: 30_000 });
 
 #### How throttle works
 
-The cursor plugin uses two layers of leading-edge + trailing-edge throttle:
+The cursor plugin uses two layers of 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`.
+1. **`throttle`** caps how often a single user broadcasts on a single topic. Leading edge fires the first move immediately; subsequent moves within the window are stored and a trailing timer flushes the latest position at the window boundary.
+2. **`topicThrottle`** caps how often a topic emits a frame at all. Every move appends to the topic's dirty set and shares a single tracker-wide timer that fires once per cadence cycle. Multiple movers in the same window coalesce into one `bulk` array; a single mover in the window emits one `update`. There is no synchronous leading-edge fire: every flush goes through the tick, so movers arriving from different sockets (each a separate JS task in production) batch into the same frame regardless of how many task boundaries separate them.
 
 ```
 throttle: 16, topicThrottle: 16
 
-t=0    A.update({x:0})         --> 'join' A, 'update' {x:0}        (leading edge of both)
+t=0    A.update({x:0})         --> 'join' A (catalog channel)
+                                   position queued in topic dirty set
 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}}]
+t=16   [tick timer fires]      --> 'bulk' [{key:A, data:{x:5}}, {key:B, data:{x:0}}]
 ```
 
-The trailing edges ensure you always see where each cursor stopped, even when the user stops moving mid-window.
+Latency cost vs. the alternate "fire-the-first-mover-synchronously" design: the first mover on an idle topic waits up to `topicThrottleMs` before its frame leaves. At the default 16 ms (~60 Hz) that's one frame-budget; well below the perceptual floor for cursor. The cost buys cross-socket coalescing - without it, the first mover from each socket fragments out as its own single-cursor `update` because uWS dispatches each WS message as its own JS task and microtasks drain between dispatches.
 
 #### Limitations
 

package/package.json

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

package/plugins/cursor/server.js

@@ -383,23 +383,30 @@ export function createCursor(options = {}) {
 
 	/**
 	 * Route a broadcast through the per-topic coalesce window when
-	 * `topicThrottle` is enabled, or directly publish when disabled.
+	 * `topicThrottle` is enabled, or publish immediately when disabled.
 	 *
-	 * Leading-edge claims the cadence slot synchronously (lastFlush =
-	 * now) but defers the actual flush by one microtask so co-arriving
-	 * broadcasts in the same JS pass batch into a single bulk frame.
-	 * Without the microtask defer, an event-loop pause > topicThrottleMs
-	 * caused the post-pause first cursor to fire alone (single-cursor
-	 * UPDATE) while every other cursor in the same burst queued to the
-	 * trailing tick: under sustained pressure (30K RPCs/sec/worker) this
-	 * fragmented 86% of cursor frames into single-cursor UPDATEs.
-	 * Microtasks run after the current synchronous code completes but
-	 * before the next I/O / setTimeout / event-loop tick, so any
-	 * subsequent broadcast() in the same handler batch adds itself to
-	 * `dirty` before the flush runs.
+	 * Every broadcast appends to `dirty` and arms (or shares) the
+	 * tracker-wide tick timer. When the cadence window has already
+	 * elapsed since the last flush, the tick is armed at delay 0 so it
+	 * fires on the next event-loop iteration; otherwise it is armed at
+	 * the remaining window time. Either way, the actual fanout happens
+	 * inside `tick()`, never synchronously.
 	 *
-	 * Trailing-edge fires via the single tracker-wide `tickTimer` for
-	 * broadcasts that land mid-window.
+	 * Why no synchronous leading-edge fire: uWS dispatches each WS
+	 * message as its own JS task. Microtasks drain at the C++ <-> JS
+	 * boundary between tasks, so a `queueMicrotask`-deferred flush
+	 * (previous design) runs BEFORE the next socket's message handler -
+	 * cross-socket coalescing window is zero, and every "first message
+	 * of a new cadence slot" from any socket fires alone as a single-
+	 * cursor UPDATE. Going through the tick timer instead schedules a
+	 * macrotask, which is dequeued only after the poll phase processes
+	 * every ready message on every socket. All messages dispatched in
+	 * the same loop iteration end up in one flush.
+	 *
+	 * Latency cost: the first cursor on an idle topic waits up to
+	 * `topicThrottleMs` (one cycle) before its frame leaves. At the
+	 * default 16 ms / 60 Hz this is one frame-budget; at 8 ms / 125 Hz
+	 * it is half a frame. Below the perceptual floor for cursor.
 	 */
 	function broadcast(topic, key, data, platform) {
 		if (topicThrottleMs <= 0) {
@@ -409,31 +416,19 @@ export function createCursor(options = {}) {
 
 		let state = topicFlush.get(topic);
 		if (!state) {
-			state = { dirty: new Map(), lastFlush: 0, pendingMicroflush: false };
+			// Anchor lastFlush one full cycle in the past so the first
+			// broadcast on a fresh topic is treated as "cycle ready" and
+			// schedules the tick at delay 0 with zero drift, rather than
+			// inflating drift stats by Date.now() worth of "lateness".
+			state = { dirty: new Map(), lastFlush: Date.now() - topicThrottleMs };
 			topicFlush.set(topic, state);
 		}
 		state.dirty.set(key, { data, platform });
-
-		const now = Date.now();
-		if (now - state.lastFlush >= topicThrottleMs) {
-			state.lastFlush = now;
-			dirtyTopics.delete(topic);
-			// Schedule once per cycle slot; subsequent broadcasts inside
-			// the same microtask boundary just append to `state.dirty`.
-			if (!state.pendingMicroflush) {
-				state.pendingMicroflush = true;
-				queueMicrotask(() => {
-					state.pendingMicroflush = false;
-					if (state.dirty.size === 0) return;
-					flushDirty(topic, state.dirty);
-					state.dirty.clear();
-				});
-			}
-			return;
-		}
-
 		dirtyTopics.add(topic);
-		armTick(Math.max(0, topicThrottleMs - (now - state.lastFlush)));
+
+		const elapsed = Date.now() - state.lastFlush;
+		const delay = elapsed >= topicThrottleMs ? 0 : topicThrottleMs - elapsed;
+		armTick(delay);
 	}
 
 	/** @type {CursorTracker} */

package/plugins/presence/client.d.ts

@@ -7,7 +7,7 @@ import type { Readable } from 'svelte/store';
  * The array updates automatically when users join or leave.
  *
  * Defaults to a 90 s `maxAge` sweep: entries that haven't been refreshed
- * by a heartbeat or presence_diff/state inside the window are removed
+ * by a heartbeat or diff/state inside the window are removed
  * from the local map. The server emits `{userKey: data}` heartbeats
  * every 30 s by default, so still-present users re-appear on the next
  * heartbeat (no flicker). Pass `maxAge: 0` to opt out of the sweep for

package/plugins/presence/client.js

@@ -6,7 +6,7 @@
  * this module just keeps the client-side state in sync.
  *
  * Defaults to a 90 s `maxAge` sweep: entries that haven't been refreshed
- * by a heartbeat or presence_diff/state inside the window are removed
+ * by a heartbeat or diff/state inside the window are removed
  * from the local map. The in-memory server (and the Redis-backed variant
  * in svelte-adapter-uws-extensions) emits `{userKey: data}` heartbeats
  * every 30 s by default, so a still-present user re-appears on the very
@@ -127,7 +127,7 @@ export function presence(topic, options) {
 		sourceUnsub = source.subscribe((event) => {
 			if (event === null) return;
 
-			if (event.event === 'presence_state' && event.data && typeof event.data === 'object') {
+			if (event.event === 'state' && event.data && typeof event.data === 'object') {
 				userMap = new Map();
 				timestamps.clear();
 				const now = Date.now();
@@ -139,7 +139,7 @@ export function presence(topic, options) {
 				return;
 			}
 
-			if (event.event === 'presence_diff' && event.data && typeof event.data === 'object') {
+			if (event.event === 'diff' && event.data && typeof event.data === 'object') {
 				const { joins, leaves } = event.data;
 				const now = Date.now();
 				let changed = false;
@@ -175,7 +175,7 @@ export function presence(topic, options) {
 					// recover entries the local sweep had already removed -
 					// once an entry aged out, the next heartbeat couldn't
 					// bring it back and the user stayed missing until a
-					// presence_diff or presence_state arrived.
+					// diff or state arrived.
 					for (const [key, data] of Object.entries(event.data)) {
 						timestamps.set(key, now);
 						const prev = userMap.get(key);
@@ -187,7 +187,7 @@ export function presence(topic, options) {
 				} else if (Array.isArray(event.data)) {
 					// Back-compat: keys-only heartbeat (older server). Refresh
 					// existing entries; cannot recover aged-out ones from this
-					// shape. The presence_diff / presence_state reconciliation
+					// shape. The diff / state reconciliation
 					// path still corrects missing entries on the next event.
 					for (const key of event.data) {
 						if (timestamps.has(key)) {
@@ -206,7 +206,7 @@ export function presence(topic, options) {
 
 		// Request a presence snapshot every time the socket opens (initial
 		// connect AND reconnects). Without this, a reconnecting client
-		// missed any presence_diff frames that fired during the disconnect
+		// missed any diff frames that fired during the disconnect
 		// window and its in-memory map stayed at whatever it last knew.
 		// Symmetric to the cursor plugin's `cursor-snapshot` send.
 		statusUnsub = status.subscribe((s) => {

package/plugins/presence/server.d.ts

@@ -51,7 +51,7 @@ export interface PresenceOptions<UserData = unknown, Selected extends Record<str
 	 * topics carrying a `{userKey: data}` map of every active user. This
 	 * refreshes each entry's `maxAge` timer on the client AND re-adds any
 	 * entry the client swept while the user was still present, so live
-	 * users do not flicker out when a `presence_diff` is missed (transient
+	 * users do not flicker out when a `diff` is missed (transient
 	 * network blip, JS thread saturation).
 	 *
 	 * Set this to a value shorter than the client's `maxAge`. The 30 s
@@ -69,7 +69,7 @@ export interface PresenceOptions<UserData = unknown, Selected extends Record<str
 	 *
 	 * @example
 	 * ```js
-	 * // Disable heartbeats; client must rely on presence_diff alone
+	 * // Disable heartbeats; client must rely on diff alone
 	 * const presence = createPresence({ heartbeat: 0 });
 	 * ```
 	 */
@@ -105,9 +105,9 @@ export interface PresenceTracker<Selected extends Record<string, any> = Record<s
 	 *
 	 * What happens:
 	 * 1. Adds the user to the topic's presence map
-	 * 2. Buffers a `join` entry into the next presence_diff broadcast (microtask-flushed)
+	 * 2. Buffers a `join` entry into the next diff broadcast (microtask-flushed)
 	 * 3. Subscribes this ws to the presence channel
-	 * 4. Sends the full current snapshot (`presence_state`) to this ws
+	 * 4. Sends the full current snapshot (`state`) to this ws
 	 *
 	 * @example
 	 * ```js
@@ -123,7 +123,7 @@ export interface PresenceTracker<Selected extends Record<string, any> = Record<s
 	 *
 	 * Call this from your `close` hook. Handles multi-tab correctly:
 	 * if the user has other connections still open, they stay present.
-	 * Only buffers a `leave` entry into the next presence_diff when the
+	 * Only buffers a `leave` entry into the next diff when the
 	 * last connection closes.
 	 *
 	 * @example
@@ -136,7 +136,7 @@ export interface PresenceTracker<Selected extends Record<string, any> = Record<s
 	leave(ws: WebSocket<any>, platform: Platform): void;
 
 	/**
-	 * Send the current presence snapshot (`presence_state`) to a connection without joining.
+	 * Send the current presence snapshot (`state`) to a connection without joining.
 	 *
 	 * Use this for observers (admin dashboards, spectators) who want to
 	 * see who's present without being counted as present themselves.
@@ -187,7 +187,7 @@ export interface PresenceTracker<Selected extends Record<string, any> = Record<s
 	clear(): void;
 
 	/**
-	 * Drain any buffered `presence_diff` publishes synchronously.
+	 * Drain any buffered `diff` publishes synchronously.
 	 *
 	 * Diffs are normally microtask-batched: multiple joins / leaves in the
 	 * same tick collapse into one broadcast frame. Tests use this to

package/plugins/presence/server.js

@@ -56,7 +56,7 @@ const TOPIC_PREFIX = '__presence:';
  *   The server periodically publishes a `heartbeat` event to all presence topics carrying a
  *   `{userKey: data}` map of every active user. This refreshes each entry's `maxAge` timer on
  *   the client AND re-adds any entry the client swept while the user was still present, so
- *   live users do not flicker out when a `presence_diff` is missed (e.g. transient network
+ *   live users do not flicker out when a `diff` is missed (e.g. transient network
  *   blip, JS thread saturation). Set this to a value shorter than the client's `maxAge`
  *   (default client `maxAge` is 90 s, so 30 s gives a 3x safety margin). Pass `0` to disable
  *   heartbeats entirely (apps that do not use the `maxAge` self-healing path).
@@ -341,13 +341,13 @@ export function createPresence(options = {}) {
 				if (op === 'join') joins[key] = data;
 				else leaves[key] = data;
 			}
-			platform.publish(TOPIC_PREFIX + topic, 'presence_diff', { joins, leaves });
+			platform.publish(TOPIC_PREFIX + topic, 'diff', { joins, leaves });
 		}
 		pendingDiffs.clear();
 	}
 
 	/**
-	 * Build a presence_state snapshot for a topic: {[key]: data}.
+	 * Build a state snapshot for a topic: {[key]: data}.
 	 * @param {Map<string, { data: Record<string, any>, count: number }> | undefined} users
 	 * @returns {Record<string, Record<string, any>>}
 	 */
@@ -387,8 +387,8 @@ export function createPresence(options = {}) {
 					// Publish a `{userKey: data}` map (rather than a keys-only
 					// array) so a client whose entry aged out of its local
 					// `maxAge` sweep between heartbeats can re-add it from the
-					// heartbeat alone, without waiting for a presence_diff /
-					// presence_state to reconcile. Matches the Redis-backed
+					// heartbeat alone, without waiting for a diff /
+					// state to reconcile. Matches the Redis-backed
 					// variant in svelte-adapter-uws-extensions.
 					/** @type {Record<string, any>} */
 					const dataMap = {};
@@ -484,7 +484,7 @@ export function createPresence(options = {}) {
 			if (existing) {
 				// Same user, additional connection (another tab) - bump count.
 				// A data change (e.g. avatar updated in another session) becomes
-				// a `join` entry in the next presence_diff: client overwrites
+				// a `join` entry in the next diff: client overwrites
 				// the existing key with the new data.
 				existing.count++;
 				if (!deepEqual(existing.data, data)) {
@@ -507,7 +507,7 @@ export function createPresence(options = {}) {
 			// user sees the complete state (including themselves) immediately;
 			// any pending diff fan-out reaches them too but is idempotent on
 			// the client (joins[key] = data is a no-op if already set).
-			platform.send(ws, presenceTopic, 'presence_state', snapshotState(users));
+			platform.send(ws, presenceTopic, 'state', snapshotState(users));
 		},
 
 		leave(ws, platform) {
@@ -527,7 +527,7 @@ export function createPresence(options = {}) {
 			const users = topicPresence.get(topic);
 			const presenceTopic = TOPIC_PREFIX + topic;
 			try { ws.subscribe(presenceTopic); } catch { return; }
-			platform.send(ws, presenceTopic, 'presence_state', snapshotState(users));
+			platform.send(ws, presenceTopic, 'state', snapshotState(users));
 		},
 
 		list(topic) {