svelte-adapter-uws 0.4.1 → 0.4.3

package/README.md

@@ -2008,12 +2008,26 @@ The client store is a `Readable<Map<string, { user, data }>>`. The Map updates w
 
 **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 `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:
 
 ```js
 const positions = cursor('canvas', { maxAge: 30_000 });
 ```
 
+`maxAge` (milliseconds) -- cursor entries that haven't received an update within that window are automatically removed. Makes clients self-healing when the server fails to broadcast `remove` events under load.
+
+`interpolate` -- enables smooth cursor rendering via `requestAnimationFrame`. Incoming `update` events set a lerp target and the displayed position moves toward it at 30% of the remaining distance per frame, eliminating visual jitter from network timing. The first update for each cursor snaps immediately (no lerp from 0,0). `snapshot`, `bulk`, and `remove` events always snap. Only applies to cursor data with numeric `x` and `y` fields -- non-numeric data falls back to direct assignment.
+
+```js
+const positions = cursor('canvas', { interpolate: true });
+```
+
+Options can be combined:
+
+```js
+const positions = cursor('canvas', { maxAge: 30_000, interpolate: true });
+```
+
 #### Server API
 
 | Method | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "SvelteKit adapter for uWebSockets.js - high-performance C++ HTTP server with built-in WebSocket support",
   "author": "Kevin Radziszewski",
   "license": "MIT",

package/plugins/cursor/client.d.ts

@@ -30,5 +30,14 @@ export interface CursorPosition<UserInfo = unknown, Data = unknown> {
  */
 export function cursor<UserInfo = unknown, Data = unknown>(
 	topic: string,
-	options?: { maxAge?: number }
+	options?: {
+		maxAge?: number;
+		/**
+		 * Enable smooth lerp interpolation for cursor movement.
+		 * When enabled, `update` events with numeric `x` and `y` fields
+		 * are interpolated via requestAnimationFrame instead of snapping.
+		 * `snapshot`, `bulk`, and `remove` events always snap immediately.
+		 */
+		interpolate?: boolean;
+	}
 ): Readable<Map<string, CursorPosition<UserInfo, Data>>>;

package/plugins/cursor/client.js

@@ -28,7 +28,7 @@ const cursorStores = new Map();
  *
  * @template UserInfo, Data
  * @param {string} topic - Topic to track cursors on
- * @param {{ maxAge?: number }} [options] - Options
+ * @param {{ maxAge?: number, interpolate?: boolean }} [options] - Options
  * @returns {import('svelte/store').Readable<Map<string, { user: UserInfo, data: Data }>>}
  *
  * @example
@@ -56,7 +56,10 @@ const cursorStores = new Map();
  */
 export function cursor(topic, options) {
 	const maxAge = options?.maxAge;
-	const cacheKey = maxAge > 0 ? topic + '\0' + maxAge : topic;
+	const interpolate = options?.interpolate === true;
+	let cacheKey = topic;
+	if (maxAge > 0) cacheKey += '\0' + maxAge;
+	if (interpolate) cacheKey += '\0lerp';
 
 	const cached = cursorStores.get(cacheKey);
 	if (cached) return cached;
@@ -73,9 +76,38 @@ export function cursor(topic, options) {
 	let statusUnsub = /** @type {(() => void) | null} */ (null);
 	/** @type {ReturnType<typeof setInterval> | null} */
 	let sweepTimer = null;
+	/** @type {Map<string, { x: number, y: number }>} */
+	const targets = new Map();
+	let rafId = /** @type {number | null} */ (null);
 	let refCount = 0;
 	let cancelled = false;
 
+	function tick() {
+		let changed = false;
+		for (const [key, target] of targets) {
+			const entry = cursorMap.get(key);
+			if (!entry) { targets.delete(key); continue; }
+			const dx = target.x - entry.data.x;
+			const dy = target.y - entry.data.y;
+			if (Math.abs(dx) < 0.5 && Math.abs(dy) < 0.5) {
+				if (entry.data.x !== target.x || entry.data.y !== target.y) {
+					entry.data = { ...entry.data, x: target.x, y: target.y };
+					changed = true;
+				}
+				targets.delete(key);
+				continue;
+			}
+			entry.data = { ...entry.data, x: entry.data.x + dx * 0.5, y: entry.data.y + dy * 0.5 };
+			changed = true;
+		}
+		if (changed) output.set(new Map(cursorMap));
+		if (targets.size > 0) {
+			rafId = requestAnimationFrame(tick);
+		} else {
+			rafId = null;
+		}
+	}
+
 	function sweep() {
 		if (!maxAge || maxAge <= 0) return;
 		const cutoff = Date.now() - maxAge;
@@ -97,15 +129,35 @@ export function cursor(topic, options) {
 
 			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 (interpolate && typeof data?.x === 'number' && typeof data?.y === 'number') {
+					const existing = cursorMap.get(key);
+					if (!existing) {
+						cursorMap.set(key, { user, data });
+					} else {
+						const dx = data.x - existing.data.x;
+						const dy = data.y - existing.data.y;
+						existing.user = user;
+						existing.data = {
+							...existing.data,
+							x: existing.data.x + dx * 0.5,
+							y: existing.data.y + dy * 0.5
+						};
+					}
+					targets.set(key, { x: data.x, y: data.y });
+					output.set(new Map(cursorMap));
+					if (rafId === null) rafId = requestAnimationFrame(tick);
+				} else {
+					cursorMap.set(key, { user, data });
+					output.set(new Map(cursorMap));
+				}
 				return;
 			}
 
 			if (event.event === 'snapshot' && Array.isArray(event.data)) {
 				cursorMap = new Map();
 				timestamps.clear();
+				targets.clear();
 				const now = Date.now();
 				for (const entry of event.data) {
 					const { key, user, data } = entry;
@@ -117,6 +169,7 @@ export function cursor(topic, options) {
 			}
 
 			if (event.event === 'bulk' && Array.isArray(event.data)) {
+				targets.clear();
 				const now = Date.now();
 				for (const entry of event.data) {
 					const { key, user, data } = entry;
@@ -130,6 +183,7 @@ export function cursor(topic, options) {
 			if (event.event === 'remove' && event.data != null) {
 				const { key } = event.data;
 				timestamps.delete(key);
+				targets.delete(key);
 				if (cursorMap.delete(key)) {
 					output.set(new Map(cursorMap));
 				}
@@ -164,6 +218,11 @@ export function cursor(topic, options) {
 			clearInterval(sweepTimer);
 			sweepTimer = null;
 		}
+		if (rafId !== null) {
+			cancelAnimationFrame(rafId);
+			rafId = null;
+		}
+		targets.clear();
 		cursorMap = new Map();
 		timestamps.clear();
 		// Push the cleared state to the output store so a new subscriber does