svelte-adapter-uws 0.4.3 → 0.4.5

package/README.md

@@ -2008,26 +2008,12 @@ 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:
+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:
 
 ```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.3",
+  "version": "0.4.5",
   "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

@@ -1,43 +1,34 @@
-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;
-		/**
-		 * 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>>>;
+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>>>;

package/plugins/cursor/client.js

@@ -1,255 +1,196 @@
-/**
- * Client-side cursor helper for svelte-adapter-uws.
- *
- * Subscribes to the internal `__cursor:{topic}` channel and maintains
- * 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).
- *
- * @module svelte-adapter-uws/plugins/cursor/client
- */
-
-import { on, connect, status } from '../../client.js';
-import { writable } from 'svelte/store';
-
-/** @type {Map<string, ReturnType<typeof cursor>>} */
-const cursorStores = new Map();
-
-/**
- * Get a reactive store of cursor positions on a topic.
- *
- * Returns a readable Svelte store containing a Map of connection keys
- * to `{ user, data }` objects. The Map updates automatically when
- * cursors move or disconnect.
- *
- * @template UserInfo, Data
- * @param {string} topic - Topic to track cursors on
- * @param {{ maxAge?: number, interpolate?: boolean }} [options] - Options
- * @returns {import('svelte/store').Readable<Map<string, { user: UserInfo, data: Data }>>}
- *
- * @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" class="cursor">
- *     {user.name}
- *   </div>
- * {/each}
- * ```
- *
- * @example
- * ```svelte
- * <script>
- *   // Self-healing: cursors expire after 30s without movement
- *   const cursors = cursor('canvas', { maxAge: 30_000 });
- * </script>
- * ```
- */
-export function cursor(topic, options) {
-	const maxAge = options?.maxAge;
-	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;
-
-	const cursorTopic = '__cursor:' + topic;
-
-	/** @type {Map<string, { user: any, data: any }>} */
-	let cursorMap = new Map();
-	/** @type {Map<string, number>} */
-	const timestamps = new Map();
-	const output = writable(/** @type {Map<string, any>} */ (new Map()));
-
-	let sourceUnsub = /** @type {(() => void) | null} */ (null);
-	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;
-		let changed = false;
-		for (const [key, ts] of timestamps) {
-			if (ts < cutoff) {
-				timestamps.delete(key);
-				if (cursorMap.delete(key)) changed = true;
-			}
-		}
-		if (changed) output.set(new Map(cursorMap));
-	}
-
-	function startListening() {
-		cancelled = false;
-		const source = on(cursorTopic);
-		sourceUnsub = source.subscribe((event) => {
-			if (event === null) return;
-
-			if (event.event === 'update' && event.data != null) {
-				const { key, user, data } = event.data;
-				timestamps.set(key, Date.now());
-				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;
-					cursorMap.set(key, { user, data });
-					timestamps.set(key, now);
-				}
-				output.set(new Map(cursorMap));
-				return;
-			}
-
-			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;
-					cursorMap.set(key, { user, data });
-					timestamps.set(key, now);
-				}
-				output.set(new Map(cursorMap));
-				return;
-			}
-
-			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));
-				}
-			}
-		});
-
-		if (maxAge > 0) {
-			sweepTimer = setInterval(sweep, Math.max(maxAge / 2, 1000));
-		}
-
-		// Request a snapshot of existing cursor positions every time the socket
-		// opens (initial connect and reconnects). Without this, the store would
-		// miss cursors that appeared while the client was offline.
-		statusUnsub = status.subscribe((s) => {
-			if (s === 'open' && !cancelled) {
-				connect().send({ type: 'cursor-snapshot', topic });
-			}
-		});
-	}
-
-	function stopListening() {
-		cancelled = true;
-		if (sourceUnsub) {
-			sourceUnsub();
-			sourceUnsub = null;
-		}
-		if (statusUnsub) {
-			statusUnsub();
-			statusUnsub = null;
-		}
-		if (sweepTimer) {
-			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
-		// not see ghost cursors from the previous subscription cycle.
-		output.set(new Map());
-	}
-
-	const store = {
-		subscribe(fn) {
-			if (refCount++ === 0) startListening();
-			const unsub = output.subscribe(fn);
-			return () => {
-				unsub();
-				if (--refCount === 0) {
-					stopListening();
-					cursorStores.delete(cacheKey);
-				}
-			};
-		}
-	};
-
-	cursorStores.set(cacheKey, store);
-
-	// If nothing subscribes before the next microtask, remove the cache entry.
-	queueMicrotask(() => {
-		if (refCount === 0) cursorStores.delete(cacheKey);
-	});
-
-	return store;
-}
+/**
+ * Client-side cursor helper for svelte-adapter-uws.
+ *
+ * Subscribes to the internal `__cursor:{topic}` channel and maintains
+ * 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).
+ *
+ * @module svelte-adapter-uws/plugins/cursor/client
+ */
+
+import { on, connect, status } from '../../client.js';
+import { writable } from 'svelte/store';
+
+/** @type {Map<string, ReturnType<typeof cursor>>} */
+const cursorStores = new Map();
+
+/**
+ * Get a reactive store of cursor positions on a topic.
+ *
+ * Returns a readable Svelte store containing a Map of connection keys
+ * to `{ user, data }` objects. The Map updates automatically when
+ * cursors move or disconnect.
+ *
+ * @template UserInfo, Data
+ * @param {string} topic - Topic to track cursors on
+ * @param {{ maxAge?: number }} [options] - Options
+ * @returns {import('svelte/store').Readable<Map<string, { user: UserInfo, data: Data }>>}
+ *
+ * @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" class="cursor">
+ *     {user.name}
+ *   </div>
+ * {/each}
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   // Self-healing: cursors expire after 30s without movement
+ *   const cursors = cursor('canvas', { maxAge: 30_000 });
+ * </script>
+ * ```
+ */
+export function cursor(topic, options) {
+	const maxAge = options?.maxAge;
+	const cacheKey = maxAge > 0 ? topic + '\0' + maxAge : topic;
+
+	const cached = cursorStores.get(cacheKey);
+	if (cached) return cached;
+
+	const cursorTopic = '__cursor:' + topic;
+
+	/** @type {Map<string, { user: any, data: any }>} */
+	let cursorMap = new Map();
+	/** @type {Map<string, number>} */
+	const timestamps = new Map();
+	const output = writable(/** @type {Map<string, any>} */ (new Map()));
+
+	let sourceUnsub = /** @type {(() => void) | null} */ (null);
+	let statusUnsub = /** @type {(() => void) | null} */ (null);
+	/** @type {ReturnType<typeof setInterval> | null} */
+	let sweepTimer = null;
+	let refCount = 0;
+	let cancelled = false;
+
+	function sweep() {
+		if (!maxAge || maxAge <= 0) return;
+		const cutoff = Date.now() - maxAge;
+		let changed = false;
+		for (const [key, ts] of timestamps) {
+			if (ts < cutoff) {
+				timestamps.delete(key);
+				if (cursorMap.delete(key)) changed = true;
+			}
+		}
+		if (changed) output.set(new Map(cursorMap));
+	}
+
+	function startListening() {
+		cancelled = false;
+		const source = on(cursorTopic);
+		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));
+				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);
+				}
+				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);
+				}
+				output.set(new Map(cursorMap));
+				return;
+			}
+
+			if (event.event === 'remove' && event.data != null) {
+				const { key } = event.data;
+				timestamps.delete(key);
+				if (cursorMap.delete(key)) {
+					output.set(new Map(cursorMap));
+				}
+			}
+		});
+
+		if (maxAge > 0) {
+			sweepTimer = setInterval(sweep, Math.max(maxAge / 2, 1000));
+		}
+
+		// Request a snapshot of existing cursor positions every time the socket
+		// opens (initial connect and reconnects). Without this, the store would
+		// miss cursors that appeared while the client was offline.
+		statusUnsub = status.subscribe((s) => {
+			if (s === 'open' && !cancelled) {
+				connect().send({ type: 'cursor-snapshot', topic });
+			}
+		});
+	}
+
+	function stopListening() {
+		cancelled = true;
+		if (sourceUnsub) {
+			sourceUnsub();
+			sourceUnsub = null;
+		}
+		if (statusUnsub) {
+			statusUnsub();
+			statusUnsub = null;
+		}
+		if (sweepTimer) {
+			clearInterval(sweepTimer);
+			sweepTimer = null;
+		}
+		cursorMap = 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.
+		output.set(new Map());
+	}
+
+	const store = {
+		subscribe(fn) {
+			if (refCount++ === 0) startListening();
+			const unsub = output.subscribe(fn);
+			return () => {
+				unsub();
+				if (--refCount === 0) {
+					stopListening();
+					cursorStores.delete(cacheKey);
+				}
+			};
+		}
+	};
+
+	cursorStores.set(cacheKey, store);
+
+	// If nothing subscribes before the next microtask, remove the cache entry.
+	queueMicrotask(() => {
+		if (refCount === 0) cursorStores.delete(cacheKey);
+	});
+
+	return store;
+}

package/vite.js

@@ -1,4 +1,3 @@
-import { WebSocketServer } from 'ws';
 import path from 'node:path';
 import { existsSync } from 'node:fs';
 import { parseCookies } from './files/cookies.js';
@@ -34,7 +33,7 @@ function esc(s) {
 export default function uws(options = {}) {
 	const wsPath = options.path || '/ws';
 
-	/** @type {WebSocketServer} */
+	/** @type {import('ws').WebSocketServer | undefined} */
 	let wss;
 
 	/** @type {Map<import('ws').WebSocket, Set<string>>} */
@@ -240,7 +239,7 @@ export default function uws(options = {}) {
 				}
 			}
 		},
-		configureServer(server) {
+		async configureServer(server) {
 			// In middleware mode Vite does not own the HTTP server, so WS upgrade cannot be attached.
 			if (!server.httpServer) {
 				server.config.logger.warn(
@@ -251,6 +250,18 @@ export default function uws(options = {}) {
 				return;
 			}
 
+			/** @type {typeof import('ws').WebSocketServer} */
+			let WebSocketServer;
+			try {
+				({ WebSocketServer } = await import('ws'));
+			} catch {
+				server.config.logger.warn(
+					'[svelte-adapter-uws] The "ws" package is not installed. ' +
+					'WebSocket features are disabled in dev. Install with: npm i -D ws'
+				);
+				return;
+			}
+
 			// E7: warn if our WS path collides with the Vite HMR WebSocket path.
 			const hmrConfig = server.config.server?.hmr;
 			if (hmrConfig && typeof hmrConfig === 'object' && hmrConfig.path === wsPath) {