svelte-adapter-uws 0.6.0-next.21 → 0.6.0-next.23

package/README.md

@@ -3065,13 +3065,78 @@ The `cursor()` function accepts an optional second argument with a `maxAge` opti
 const positions = cursor('canvas', { maxAge: 30_000 });
 ```
 
+#### Canvas rendering (worker offload)
+
+At high cursor density the DOM `{#each}` above stops being the bottleneck you can fix: every frame still lands on the main thread, gets parsed there, and re-renders through reactivity. Hand `cursor()` a canvas instead and the entire ingest-decode-merge-paint pipeline moves into a dedicated worker that owns its own WebSocket (subscribed only to the cursor topic) and the canvas's transferred drawing surface. The main thread reads nothing from the cursor stream - at any density.
+
+```svelte
+<script>
+  import { cursor, move } from 'svelte-adapter-uws/plugins/cursor/client';
+  let canvas = $state();
+  $effect(() => cursor('board:42', { canvas }).mount());
+</script>
+
+<canvas bind:this={canvas} class="cursor-layer"></canvas>
+<div onpointermove={(e) => move('board:42', { x: e.clientX, y: e.clientY })}> ... </div>
+```
+
+That is the whole zero-config path. `mount()` returns its teardown, so the `$effect` one-liner is the complete lifecycle; unmounting pauses the pipeline (socket closed, state cleared) and a remount on the same canvas resumes it, same or different topic. `move()` is unchanged - sending stays on the main thread (pointer events only exist there); only receiving and rendering move off it. On a browser without the worker pipeline (no `OffscreenCanvas`, an old Safari) the identical call renders on the main thread through the same renderer backends: same visuals, lower ceiling, no API difference, no thrown error.
+
+What the worker does for you:
+
+- **Decodes off the main thread.** Binary cursor frames decode 15-18x faster than `JSON.parse`, and even that cost now happens where it cannot drop an app frame.
+- **Renders through a density-aware backend.** Canvas2D below 500 in-view cursors (zero GPU setup for quiet boards), automatic promotion to an instanced WebGL2 renderer at the threshold - one draw call per frame at any count. Crossing back down never thrashes backends.
+- **Culls and reports the viewport.** The worker tracks your `viewport` source (or the canvas element itself), paints only the in-view subset, and reports the rect on its own socket so [server-side culling](#cutting-cursor-volume-opt-in-reducers) also shrinks the wire.
+- **Reconnects independently.** The cursor socket has its own backoff and liveness check; a cursor-stream hiccup never disturbs your main connection, and vice versa.
+
+Options, all opt-in:
+
+```js
+const handle = cursor('board:42', {
+  canvas,
+  rendering: 'auto',          // 'auto' | 'main' (forces main thread, adds handle.store) | 'worker' (throws if unsupported)
+  gpu: 'auto',                // 'auto' | 'canvas2d' | 'webgl2' | 'webgpu' (reserved; throws until it ships)
+  gpuThreshold: 500,          // in-view count where 'auto' promotes to the GPU backend
+  smooth: true,               // render-in-the-past interpolation for remote cursors (see below)
+  mainThreadFeed: { rate: 10 }, // opt-in thinned position feed back to the main thread
+  maxAge: 30_000,             // same self-healing sweep as the store
+  viewport: () => board       // same sources as the store path; defaults to the canvas element
+});
+```
+
+#### Smooth remote cursors (`smooth`)
+
+Without smoothing, remote cursors paint exactly where the last wire frame put them - at typical coalesced rates that is visibly steppy, and one dropped frame freezes a cursor until the next one lands. `smooth: true` switches remote rendering to buffered playback: each cursor keeps a short history of server-stamped samples, and every render frame paints the position interpolated between the two samples that straddle a render time held a small, self-tuning delay behind the newest data. A single dropped frame becomes invisible (there is still a real pair of samples around the render time), and motion between wire frames is filled in at full display rate.
+
+The trade is stated once and plainly: **remote cursors render `interpolationMs` behind their newest known position - a larger delay survives more dropped frames but trails further behind.** The `'auto'` default tracks twice the measured update interval, so a stream already arriving at display rate collapses toward the 32ms floor and pays almost nothing, while a coarse stream widens itself just enough. Your own pointer is unaffected (it is drawn by the OS, not the canvas), and the `mainThreadFeed` keeps shipping raw wire positions - smoothing changes pixels, never data.
+
+```js
+cursor('board:42', { canvas, smooth: true });                  // tuned defaults
+cursor('board:42', {
+  canvas,
+  smooth: {
+    interpolationMs: 'auto', // or a fixed ms: the render-in-the-past delay
+    extrapolateMs: 250,      // dead-reckoning cap when the buffer runs dry
+    snapGapMs: 500           // sample gap snapped (a view re-entry, an idle resume), not smeared
+  }
+});
+```
+
+Under the hood this negotiates one extra capability (`cursor.protocol:4`): the server stamps each position frame with its wall clock (one byte per frame steady-state, delta-coded), the snapshot reply leads with a `time` event that seeds a per-socket server-clock estimator, and the worker (or the main-thread fallback - same code, same visuals) samples each cursor's ring at the estimated server time minus the delay. Old servers and old clients keep working: without the capability the interpolator runs on arrival times, which still smooths but breathes with network jitter.
+
+`handle.feed` (present only with `mainThreadFeed`) is a `Readable<Map<key, { user, data, colorRGBA }>>` sampled at the feed rate in board coordinates - for the leader badge, the minimap, the "3 people here" pill - not a second rendering path: at 500 in-view cursors a feed tick costs the main thread ~30 microseconds. Apps that genuinely need full reactive cursor data alongside their own canvas use `rendering: 'main'` and read `handle.store`.
+
+`handle.configure({ colorOf, hide })` sets display config: the callbacks run on the main thread against the live roster (and re-run as users join), and only the resolved per-key results cross to the worker. `colorOf(user)` returns a hex string or packed RGBA integer; anything else keeps the deterministic default palette. A user hidden by `hide` disappears from the canvas and the feed.
+
+One canvas renders one topic at a time, and a canvas whose surface was transferred belongs to its worker for the element's lifetime - `handle.destroy()` is terminal (leaving the board for good); for component lifecycles rely on the `mount()` teardown. The worker identifies its socket with the `svelte-realtime-cursor` subprotocol, so deployments running the admission gate's cursor lane shed cursor sockets before main connections under load.
+
 #### Server API
 
 | Method | Description |
 |---|---|
 | `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.snapshot(ws, topic, platform)` | Send current positions to one connection as `time` + `catalog` + `bulk` (initial sync; `time` seeds the smoothing clock) |
 | `cursors.list(topic)` | Current positions (for SSR) |
 | `cursors.viewport(ws, topic, rect)` | Record a subscriber's viewport rect (called for you by `hooks.message` on a `cursor-viewport` frame) |
 | `cursors.viewportFor(ws, topic)` | The subscriber's last reported rect, or `null` if it never reported one |

package/client-runtime.js

@@ -82,6 +82,45 @@ export const clearIntervalTimer = (h) => current.timers.clearInterval(h);
 export const microtask = (cb) => current.timers.queueMicrotask(cb);
 export const effectiveTimeZone = () => current.tz;
 
+/**
+ * Compute the next reconnect delay using exponential backoff with
+ * proportional jitter.
+ *
+ * The capped delay is `min(base * 2.2^attempt, maxDelay)`. A random factor
+ * in `[0.75, 1.25]` is then applied multiplicatively, so the final delay
+ * spans +/- 25% of the capped value. Multiplicative jitter keeps spread
+ * meaningful at high attempt counts: with 10K clients all reconnecting
+ * after a server restart, additive +/- 500ms jitter clusters reconnects
+ * inside a 1 second window; proportional jitter spreads them across
+ * a window proportional to the current backoff.
+ *
+ * The 2.2 exponent with a 5 minute cap is aggressive enough to back off
+ * fast under sustained server pain (the default 3 second base hits the
+ * cap by attempt 6) and gentle enough that a brief restart resolves
+ * before the user notices.
+ *
+ * Pure given an explicit `randFactor`: no I/O, no globals. Pass a fixed
+ * value for reproducible assertions in tests.
+ *
+ * Lives here (not client.js) because every socket owner shares one curve -
+ * the main connection and any dedicated secondary socket - and this module
+ * is the only client module such a socket owner can import without dragging
+ * the whole connection surface (and Svelte) into its bundle. The default
+ * `randFactor` is the runtime float source: backoff jitter spreads retries
+ * across a fleet, never crosses a trust boundary, and routing it through
+ * the runtime lets a seeded harness reproduce the reconnect schedule.
+ *
+ * @param {number} base       base interval in ms (e.g. 3000)
+ * @param {number} maxDelay   cap in ms (e.g. 300000)
+ * @param {number} attempt    zero-based attempt counter
+ * @param {number} [randFactor]  random factor in [0, 1); defaults to randomFloat()
+ * @returns {number}
+ */
+export function nextReconnectDelay(base, maxDelay, attempt, randFactor = randomFloat()) {
+	const capped = Math.min(base * Math.pow(2.2, attempt), maxDelay);
+	return capped * (0.75 + randFactor * 0.5);
+}
+
 // Install a virtual environment (the simulator/test harness only). Refuses under
 // a node production build unless explicitly forced, so a stray call can never
 // swap the clock under a live deployment; in a real browser there is no process

package/client.js

@@ -1,6 +1,6 @@
 import { writable, derived } from 'svelte/store';
 import { parseBinaryFrame, requestNFrame } from './files/wire.js';
-import { now, randomFloat, setTimer, setIntervalTimer, clearTimer, clearIntervalTimer, microtask } from './client-runtime.js';
+import { now, setTimer, setIntervalTimer, clearTimer, clearIntervalTimer, microtask, nextReconnectDelay } from './client-runtime.js';
 
 /** @type {ReturnType<typeof createConnection> | null} */
 let singleton = null;
@@ -700,43 +700,10 @@ export function classifyCloseCode(code) {
 	return 'RETRY';
 }
 
-/**
- * Compute the next reconnect delay using exponential backoff with
- * proportional jitter.
- *
- * The capped delay is `min(base * 2.2^attempt, maxDelay)`. A random factor
- * in `[0.75, 1.25]` is then applied multiplicatively, so the final delay
- * spans +/- 25% of the capped value. Multiplicative jitter keeps spread
- * meaningful at high attempt counts: with 10K clients all reconnecting
- * after a server restart, additive +/- 500ms jitter clusters reconnects
- * inside a 1 second window; proportional jitter spreads them across
- * a window proportional to the current backoff.
- *
- * The 2.2 exponent with a 5 minute cap is aggressive enough to back off
- * fast under sustained server pain (the default 3 second base hits the
- * cap by attempt 6) and gentle enough that a brief restart resolves
- * before the user notices.
- *
- * Pure given an explicit `randFactor`: no I/O, no globals. Pass a fixed
- * value for reproducible assertions in tests.
- *
- * The default `randFactor` is the runtime float source: this value is
- * reconnect-backoff jitter, used to spread retries across a fleet so a
- * server restart does not hit a thundering-herd. Not security-relevant -
- * the randFactor never crosses a trust boundary - so the runtime source is
- * the right primitive; routing it through the runtime also lets a seeded
- * harness reproduce the reconnect schedule exactly.
- *
- * @param {number} base       base interval in ms (e.g. 3000)
- * @param {number} maxDelay   cap in ms (e.g. 300000)
- * @param {number} attempt    zero-based attempt counter
- * @param {number} [randFactor]  random factor in [0, 1); defaults to randomFloat()
- * @returns {number}
- */
-export function nextReconnectDelay(base, maxDelay, attempt, randFactor = randomFloat()) {
-	const capped = Math.min(base * Math.pow(2.2, attempt), maxDelay);
-	return capped * (0.75 + randFactor * 0.5);
-}
+// Reconnect backoff curve. Defined in client-runtime.js (the worker-safe
+// module every socket owner can import); re-exported here so the public
+// surface of this module is unchanged.
+export { nextReconnectDelay };
 
 /**
  * @param {import('./client.js').ConnectOptions} options
@@ -1343,6 +1310,10 @@ function createConnection(options) {
 							if (decoded && !match.codec.sink) {
 								const out = { topic, event: decoded.event, data: decoded.data };
 								if (parsed.seq > 0) out.seq = parsed.seq;
+								// Additive codec metadata (e.g. the cursor wire's server
+								// stamp): rides the dispatched event for consumers that
+								// want it; the store merge ignores it.
+								if (decoded.t !== undefined) out.t = decoded.t;
 								dispatchEvent(out);
 							}
 						} else if (debug) {
@@ -1916,6 +1887,12 @@ function createConnection(options) {
 		get bufferedAmount() { return ws?.bufferedAmount ?? 0; },
 		onRequest,
 		_resendHello: resendHello,
+		// Internal: the resolved WebSocket URL this connection dials. A plugin
+		// that opens its own dedicated socket (the cursor render worker) must
+		// reach the same endpoint the main connection negotiated - including a
+		// custom `url` / `path` option - so the derivation is exposed here
+		// rather than re-derived from window.location in the plugin.
+		_url: getUrl,
 		// Internal-only subscription to the connection's flow-control health.
 		// A boolean (degraded yes/no) is the only thing that crosses this
 		// accessor - no window count, deadline, or any internal accounting

package/files/utils.js

@@ -668,6 +668,51 @@ export function computeTopPublishers(stats, intervalSec, thresholds) {
 // alternative was a silent cluster-routing break in production.
 
 export const WS_SUBSCRIPTIONS = Symbol.for('adapter-uws.ws.subscriptions');
+
+/**
+ * Subscribe a socket the way the wire-level subscribe path does: the uWS
+ * native call PLUS the connection's subscription registry. The registry is
+ * what `platform.publishWire`'s per-subscriber walk delivers by (native
+ * membership is not enumerable from JS), so a plugin that subscribes a
+ * socket natively but skips the registry silently excludes that socket from
+ * every stateful-codec binary publish on the topic. Plugins establishing
+ * server-side membership (a snapshot handshake, a presence join) must use
+ * this instead of raw `ws.subscribe`.
+ *
+ * Returns false when the socket is already closed (uWS throws on access).
+ *
+ * @param {any} ws
+ * @param {string} topic
+ * @returns {boolean}
+ */
+export function trackedSubscribe(ws, topic) {
+	try { ws.subscribe(topic); } catch { return false; }
+	try {
+		const subs = ws.getUserData()[WS_SUBSCRIPTIONS];
+		if (subs) subs.add(topic);
+	} catch { /* socket died between the calls; close cleanup owns the registry */ }
+	return true;
+}
+
+/**
+ * Unsubscribe counterpart of {@link trackedSubscribe}: native unsubscribe
+ * plus registry removal, so the per-subscriber binary walk stops delivering
+ * the moment native membership ends.
+ *
+ * @param {any} ws
+ * @param {string} topic
+ * @returns {boolean} false when the socket was already closed
+ */
+export function trackedUnsubscribe(ws, topic) {
+	let ok = true;
+	try { ws.unsubscribe(topic); } catch { ok = false; }
+	try {
+		const subs = ws.getUserData()[WS_SUBSCRIPTIONS];
+		if (subs) subs.delete(topic);
+	} catch { /* socket died; close cleanup owns the registry */ }
+	return ok;
+}
+
 export const WS_COALESCED = Symbol.for('adapter-uws.ws.coalesced');
 export const WS_SESSION_ID = Symbol.for('adapter-uws.ws.session-id');
 export const WS_PENDING_REQUESTS = Symbol.for('adapter-uws.ws.pending-requests');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws",
-  "version": "0.6.0-next.21",
+  "version": "0.6.0-next.23",
   "publishConfig": {
     "tag": "next"
   },

package/plugins/cursor/client.d.ts

@@ -1,95 +1,239 @@
-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.
- *
- * Pass a `viewport` source to opt this subscriber into server-side culling: the
- * store reports the visible region automatically (on scroll, resize, zoom, and
- * late mount) while subscribed, so you write no `reportViewport` wiring yourself.
- *
- * @example
- * ```svelte
- * <script>
- *   import { cursor, move } from 'svelte-adapter-uws/plugins/cursor/client';
- *
- *   let board;
- *   // Auto-reports board's visible region; omit `viewport` to see all cursors.
- *   const cursors = cursor('canvas', { viewport: () => board });
- * </script>
- *
- * <div bind:this={board}
- *      onpointermove={(e) => move('canvas', { x: e.clientX + board.scrollLeft, y: e.clientY + board.scrollTop })}>
- *   {#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?: {
-		/** Drop a cursor that has not updated within this many ms. */
-		maxAge?: number;
-		/**
-		 * Opt into server-side viewport culling. Pass a scroll-container element,
-		 * an explicit `{ x, y, w, h, zoom? }` rect, or a getter returning either
-		 * (a getter handles a late-bound `bind:this` element). While subscribed,
-		 * the store reports the resolved region whenever it changes - covering
-		 * scroll, resize, zoom, and mount with no manual wiring. The reported rect
-		 * and your `move()` coordinates must share one coordinate space (the
-		 * board's). Omit it and the subscriber sees all cursors (never culled).
-		 */
-		viewport?:
-			| Element
-			| { x: number; y: number; w: number; h: number; zoom?: number }
-			| (() => Element | { x: number; y: number; w: number; h: number; zoom?: number } | null | undefined);
-	}
-): 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;
-
-/**
- * Report this subscriber's viewport on a topic so the server can cull cursors
- * outside the visible region (once viewport culling is enabled server-side).
- * Reporting is per-subscriber and opt-in: a subscriber that never reports a
- * viewport is treated as whole-board and is never culled. Frames are coalesced
- * via `requestAnimationFrame` (one send per repaint); multi-topic callers do
- * not clobber each other.
- *
- * No-op in non-browser environments and for an unresolvable source.
- *
- * @param topic
- * @param source a scroll-container element (the visible content region is read
- *   from `scrollLeft` / `scrollTop` / `clientWidth` / `clientHeight`), an
- *   explicit `{ x, y, w, h, zoom? }` rect (for a virtualized canvas with its
- *   own transform), or a getter returning either.
- */
-export function reportViewport(
-	topic: string,
-	source:
-		| Element
-		| { x: number; y: number; w: number; h: number; zoom?: number }
-		| (() => Element | { x: number; y: number; w: number; h: number; zoom?: number } | null | undefined)
-): void;
+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;
+}
+
+/** A viewport source: a scroll-container element, an explicit rect in board
+ * coordinates, or a getter returning either (a getter handles a late-bound
+ * `bind:this` element). */
+export type ViewportSource =
+	| Element
+	| { x: number; y: number; w: number; h: number; zoom?: number }
+	| (() => Element | { x: number; y: number; w: number; h: number; zoom?: number } | null | undefined);
+
+/** One entry of the thinned main-thread feed: the classic store's
+ * `{ user, data }` join plus the resolved display color. */
+export interface CursorFeedEntry<UserInfo = unknown> {
+	user: UserInfo;
+	data: { x: number; y: number };
+	/** Packed 0xRRGGBBAA, after display-config resolution. */
+	colorRGBA: number;
+}
+
+/**
+ * The handle returned by `cursor(topic, { canvas })`. Rendering starts on
+ * `mount()` and the returned teardown stops it, so the natural Svelte 5
+ * binding is one line: `$effect(() => cursor(topic, { canvas }).mount())`.
+ */
+export interface CursorHandle<UserInfo = unknown> {
+	/**
+	 * Start rendering into the canvas. Idempotent across components: two
+	 * mounts of the same topic+canvas share one pipeline. Returns the
+	 * teardown; after the last teardown the pipeline pauses (the worker and
+	 * the canvas surface are kept, so a later mount on the same element
+	 * resumes - including on a different topic).
+	 *
+	 * Throws when `rendering: 'worker'` is set and the browser cannot
+	 * provide a worker pipeline, and when the canvas is currently rendering
+	 * a different topic.
+	 */
+	mount(): () => void;
+	/**
+	 * Replace the tracked viewport source. Rarely needed - the plugin
+	 * auto-tracks the `viewport` option (or the canvas element itself) every
+	 * frame; use this for a transform only you can compute, passing the same
+	 * shapes the `viewport` option accepts.
+	 */
+	viewport(source: ViewportSource): void;
+	/**
+	 * Display config. The callbacks run on the main thread against the
+	 * current roster and re-run automatically as users join and leave; only
+	 * the resolved per-key results are shipped to the renderer. `colorOf`
+	 * returns a hex string ('#rgb', '#rrggbb', '#rrggbbaa') or a packed
+	 * 32-bit RGBA integer; any other value keeps the deterministic default
+	 * palette. A user hidden by `hide` is excluded from the canvas AND from
+	 * the main-thread feed. Throwing callbacks are contained per user.
+	 */
+	configure(config: {
+		colorOf?: (user: UserInfo) => string | number | null | undefined;
+		hide?: (user: UserInfo) => boolean;
+	}): void;
+	/**
+	 * Terminal teardown: stops the pipeline and disposes the worker. The
+	 * canvas element cannot render cursors again afterwards (its drawing
+	 * surface was transferred to the disposed worker - a once-per-element
+	 * operation), so prefer the `mount()` teardown for component lifecycles
+	 * and reserve `destroy()` for leaving the board entirely.
+	 */
+	destroy(): void;
+	/**
+	 * Present only when `mainThreadFeed` is enabled: the thinned, rate-capped
+	 * position feed (board coordinates, in-view and non-hidden cursors only),
+	 * updated at the feed rate rather than the wire rate.
+	 */
+	feed?: Readable<Map<string, CursorFeedEntry<UserInfo>>>;
+	/**
+	 * Present only with `rendering: 'main'`: the classic reactive store, for
+	 * apps that draw on their own canvas AND need cursor data reactively.
+	 */
+	store?: Readable<Map<string, CursorPosition<UserInfo>>>;
+}
+
+/** Options shared by both `cursor()` forms. */
+export interface CursorStoreOptions {
+	/** Drop a cursor that has not updated within this many ms. */
+	maxAge?: number;
+	/**
+	 * Opt into server-side viewport culling. While subscribed/mounted, the
+	 * resolved region is reported whenever it changes - covering scroll,
+	 * resize, zoom, and late mount with no manual wiring. The reported rect
+	 * and your `move()` coordinates must share one coordinate space (the
+	 * board's). Omit it and this subscriber sees all cursors (never culled).
+	 * In canvas mode it additionally drives the render transform and
+	 * client-side culling; omitting it there tracks the canvas element.
+	 */
+	viewport?: ViewportSource;
+}
+
+/** Options accepted when a `canvas` is supplied. */
+export interface CursorCanvasOptions extends CursorStoreOptions {
+	/** Render target. Its drawing surface is transferred to a dedicated
+	 * worker when the browser supports it. */
+	canvas: HTMLCanvasElement;
+	/**
+	 * Which thread renders. `'auto'` (default) uses a worker when
+	 * `Worker` + `OffscreenCanvas` + `transferControlToOffscreen` exist and
+	 * silently renders on the main thread otherwise (same call, same visual
+	 * result, lower ceiling). `'worker'` requires the worker pipeline and
+	 * throws at `mount()` without it - for deployments that refuse to ship
+	 * an untested fallback. `'main'` forces main-thread rendering and
+	 * additionally exposes `handle.store` for reactive reads.
+	 */
+	rendering?: 'auto' | 'main' | 'worker';
+	/**
+	 * Which backend draws. `'auto'` (default) starts on Canvas2D and
+	 * promotes to WebGL2 when the in-view count first reaches
+	 * `gpuThreshold`; forced values name a backend and fail loudly when it
+	 * is unavailable.
+	 */
+	gpu?: 'auto' | 'canvas2d' | 'webgl2' | 'webgpu';
+	/** In-view cursor count at which `gpu: 'auto'` promotes to a GPU
+	 * backend (default 500). Crossing back down never downgrades. */
+	gpuThreshold?: number;
+	/**
+	 * Opt-in thinned position feed back to the main thread, for the
+	 * incidental reactive needs of worker mode (a leader badge, a minimap).
+	 * `true` samples at 10 Hz; `{ rate }` picks the frequency. Off by
+	 * default: the point of worker mode is that the main thread reads
+	 * nothing from the cursor stream. The feed always ships raw wire
+	 * positions - smoothing changes pixels, never the data surface.
+	 */
+	mainThreadFeed?: boolean | { rate?: number };
+	/**
+	 * Render-in-the-past interpolation for remote cursors. `true` selects
+	 * the tuned defaults; the object form exposes the knobs. Remote cursors
+	 * render `interpolationMs` behind their newest known position, so a
+	 * dropped or late frame is invisible (there is almost always a real
+	 * pair of samples around the render time) at the cost of that small
+	 * trailing delay. `'auto'` (default) tracks twice the measured update
+	 * interval and collapses toward a 32ms floor when updates arrive at
+	 * display rate. `extrapolateMs` caps dead-reckoning when the buffer
+	 * runs dry (default 250); `snapGapMs` is the sample gap treated as a
+	 * discontinuity and snapped rather than smeared (default 500). Requires
+	 * a canvas (the plain store has no render loop). Off by default.
+	 */
+	smooth?: boolean | {
+		interpolationMs?: 'auto' | number;
+		extrapolateMs?: number;
+		snapGapMs?: number;
+	};
+}
+
+/**
+ * Reactive cursor data for 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';
+ *
+ *   let board;
+ *   // Auto-reports board's visible region; omit `viewport` to see all cursors.
+ *   const cursors = cursor('canvas', { viewport: () => board });
+ * </script>
+ *
+ * <div bind:this={board}
+ *      onpointermove={(e) => move('canvas', { x: e.clientX + board.scrollLeft, y: e.clientY + board.scrollTop })}>
+ *   {#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: CursorCanvasOptions
+): CursorHandle<UserInfo>;
+
+/**
+ * Rendered cursors for a topic: hand `cursor()` a canvas and the whole
+ * ingest-decode-merge-paint pipeline moves into a dedicated worker that owns
+ * its own WebSocket and the canvas's transferred drawing surface - the main
+ * thread reads nothing from the cursor stream at any density. On a browser
+ * without the worker pipeline the identical call renders on the main thread
+ * instead (no API difference, no thrown error in `'auto'` mode).
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { cursor, move } from 'svelte-adapter-uws/plugins/cursor/client';
+ *   let canvas = $state();
+ *   $effect(() => cursor('board:42', { canvas }).mount());
+ * </script>
+ *
+ * <canvas bind:this={canvas} class="cursor-layer"></canvas>
+ * <div onpointermove={(e) => move('board:42', { x: e.clientX, y: e.clientY })}> ... </div>
+ * ```
+ */
+export function cursor<UserInfo = unknown, Data = unknown>(
+	topic: string,
+	options?: CursorStoreOptions
+): 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;
+
+/**
+ * Report this subscriber's viewport on a topic so the server can cull cursors
+ * outside the visible region (once viewport culling is enabled server-side).
+ * Reporting is per-subscriber and opt-in: a subscriber that never reports a
+ * viewport is treated as whole-board and is never culled. Frames are coalesced
+ * via `requestAnimationFrame` (one send per repaint); multi-topic callers do
+ * not clobber each other.
+ *
+ * No-op in non-browser environments and for an unresolvable source.
+ *
+ * @param topic
+ * @param source a scroll-container element (the visible content region is read
+ *   from `scrollLeft` / `scrollTop` / `clientWidth` / `clientHeight`), an
+ *   explicit `{ x, y, w, h, zoom? }` rect (for a virtualized canvas with its
+ *   own transform), or a getter returning either.
+ */
+export function reportViewport(topic: string, source: ViewportSource): void;