live-cursors 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 live-cursors contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# live-cursors
+
+Multiplayer cursors for **any** transport. ~3 KB, zero dependencies, no SaaS.
+
+![Two participants moving cursors across a retro board, relayed over a plain WebSocket](https://raw.githubusercontent.com/qretro/live-cursors/main/docs/demo.gif)
+
+Works over Laravel Echo/Reverb, a raw WebSocket, `BroadcastChannel`, Supabase Realtime — or a channel you already have. Ships vanilla, Vue and React bindings.
+
+```bash
+npm i live-cursors
+```
+
+## Why another cursors package
+
+Existing options ask you to adopt their world: Liveblocks, Velt and Ably Spaces are hosted services, `y-presence` needs Yjs, `cursor-party` needs PartyKit, `nuxt-live-cursors` needs Nitro WebSockets. [`perfect-cursors`](https://github.com/steveruizok/perfect-cursors) stays out of your way but only interpolates positions — everything else is yours to write.
+
+This package is the everything else: throttling, TTL, coordinate spaces, stable colors, rendering, teardown. Bring your own channel.
+
+## Quick start
+
+### Vanilla
+
+```ts
+import { createCursors } from "live-cursors";
+import { broadcastTransport } from "live-cursors/broadcast";
+import { renderCursors } from "live-cursors/dom";
+
+const cursors = createCursors({
+  transport: broadcastTransport({ room: "demo" }),
+  selfId: currentUser.id,
+});
+
+cursors.attach();
+renderCursors({ cursors, label: cursor => names[cursor.id] });
+```
+
+`broadcastTransport` needs no server at all — open two tabs and you have multiplayer cursors.
+
+### Vue
+
+```vue
+<script setup lang="ts">
+import { LiveCursors, useCursors } from "live-cursors/vue";
+import { websocketTransport } from "live-cursors/websocket";
+
+const board = useTemplateRef("board");
+const { cursors } = useCursors({
+  transport: () => websocketTransport({ url: "wss://example.com/cursors", room: "board-1" }),
+  selfId: user.id,
+  container: board,
+});
+</script>
+
+<template>
+  <div ref="board" class="relative overflow-auto">
+    <!-- board content -->
+    <LiveCursors :cursors="cursors" :label="cursor => names[cursor.id]" />
+  </div>
+</template>
+```
+
+The transport is a factory so nothing touches `WebSocket` during SSR.
+
+### React
+
+```tsx
+import { LiveCursors, useCursors } from "live-cursors/react";
+import { websocketTransport } from "live-cursors/websocket";
+
+function Board() {
+  const [board, setBoard] = useState<HTMLDivElement | null>(null);
+  const { cursors } = useCursors({
+    transport: () => websocketTransport({ url: "wss://example.com/cursors" }),
+    selfId: user.id,
+    container: board,
+  });
+
+  return (
+    <div ref={setBoard} style={{ position: "relative", overflow: "auto" }}>
+      <LiveCursors cursors={cursors} label={cursor => names[cursor.id]} />
+    </div>
+  );
+}
+```
+
+### Custom label, built-in arrow
+
+The `label` prop takes a string; for richer content use the `label` slot (Vue) or `renderLabel`
+(React) — the arrow stays, only the pill is yours. The `default` slot / `children` replaces the
+whole cursor instead.
+
+```vue
+<LiveCursors :cursors="cursors">
+  <template #label="{ cursor }">
+    <UAvatar :src="roster[cursor.id].avatar" size="3xs" />
+    <span>{{ roster[cursor.id].name }}</span>
+  </template>
+</LiveCursors>
+```
+
+### Presence: dropping a cursor immediately
+
+`ttlMs` covers clients that vanish silently. When your presence layer reports that someone
+left, drop their cursor at once:
+
+```ts
+channel.leaving(user => cursors.remove(user.id));
+```
+
+### Laravel Echo / Reverb
+
+Cursor updates ride on client events, so the channel has to be private or presence.
+
+```ts
+import { createCursors } from "live-cursors";
+import { echoTransport } from "live-cursors/echo";
+
+const channel = window.Echo.private(`App.Models.Board.${boardId}`);
+
+const cursors = createCursors({
+  transport: echoTransport({ channel }),
+  selfId: user.id,
+});
+```
+
+## Coordinate spaces
+
+Pick the one that matches how participants move through your content:
+
+| Space | Behaviour | Use for |
+|---|---|---|
+| `viewportSpace()` (default) | `x / innerWidth` — a cursor sits at the same screen position for everyone | landing pages, presentations, fixed layouts |
+| `elementSpace(el)` | normalized against the element's scrollable content | boards, canvases, long documents where participants scroll independently |
+| `customSpace({ ... })` | your own mapping | zoomable canvases, virtualized lists |
+
+```ts
+import { createCursors, elementSpace } from "live-cursors";
+
+const cursors = createCursors({
+  transport,
+  selfId: user.id,
+  space: elementSpace(() => boardRef.value),
+});
+```
+
+## Options
+
+| Option | Default | What it does |
+|---|---|---|
+| `transport` | — | where messages go; see below |
+| `selfId` | — | local participant id; incoming messages carrying it are ignored |
+| `space` | `viewportSpace()` | coordinate mapping |
+| `throttleMs` | `40` | ~25 outgoing updates per second, leading + trailing |
+| `ttlMs` | `3000` | a cursor with no update in this window disappears |
+| `maxRemote` | `50` | cap on tracked participants; a flooding client cannot grow the map |
+| `enabled` | `true` | set to `false` to stop broadcasting (a "hide my cursor" toggle) |
+| `meta` | — | tiny extra payload per move; keep personal data out of it |
+
+## Writing a transport
+
+Three methods, no base class:
+
+```ts
+import type { CursorTransport } from "live-cursors";
+
+export function myTransport(): CursorTransport {
+  return {
+    send: message => socket.emit("cursor", message),
+    onMessage: (handler) => {
+      const listener = (payload, senderId) => handler(payload, senderId);
+      socket.on("cursor", listener);
+      return () => socket.off("cursor", listener);
+    },
+  };
+}
+```
+
+If your transport already knows who sent a message, pass its `senderId` as the second argument — it wins over the id inside the payload, so a client cannot claim someone else's identity.
+
+## Notes
+
+- **No personal data on the wire.** A cursor carries an id and two numbers. Names and avatars come from whatever roster your app already has — that keeps payloads small at 25 fps and keeps cursor traffic out of your privacy surface.
+- **Nothing is persisted.** The library holds cursors in memory and forgets them after `ttlMs`.
+- **Touch input is ignored.** There is no hover on touch devices, so nothing is broadcast from them.
+- **Respects `prefers-reduced-motion`** — the interpolating transition is dropped.
+- **Colors and labels stay data.** The tint travels through the `--lc-color` custom property and
+  label text is set as text, so `color` and `label` callbacks cannot introduce markup.
+- **ESM only.** Node 18+, any modern bundler.
+
+## Development
+
+```bash
+pnpm install
+pnpm test          # vitest, happy-dom
+pnpm test:e2e      # playwright: two browser contexts through a websocket relay
+pnpm typecheck
+pnpm lint
+pnpm play          # playground: viewport, element and websocket demos
+pnpm check:pkg     # build + publint + are-the-types-wrong
+pnpm demo:gif      # re-record docs/demo.gif (needs ffmpeg on PATH)
+```
+
+The gif is produced by [`scripts/record-demo.mjs`](scripts/record-demo.mjs): it starts the relay
+and the playground, drives two participants along scripted pointer paths, films a third context
+and encodes the result — so the demo can be regenerated whenever the cursors change shape.
+
+
+## License
+
+MIT

package/dist/broadcast.d.mts

@@ -0,0 +1,13 @@
+import { a as CursorTransport } from "./cursors-CyiNtLCv.mjs";
+//#region src/transports/broadcast.d.ts
+interface BroadcastTransportOptions {
+  /** channel name; participants sharing it see each other */
+  room?: string;
+}
+/**
+ * BroadcastChannel transport — same-origin tabs only, no server at all.
+ * Useful for demos and for developing against cursors without infrastructure.
+ */
+declare function broadcastTransport(options?: BroadcastTransportOptions): CursorTransport;
+//#endregion
+export { BroadcastTransportOptions, broadcastTransport };

package/dist/broadcast.mjs

@@ -0,0 +1,24 @@
+//#region src/transports/broadcast.ts
+/**
+* BroadcastChannel transport — same-origin tabs only, no server at all.
+* Useful for demos and for developing against cursors without infrastructure.
+*/
+function broadcastTransport(options = {}) {
+	const { room = "live-cursors" } = options;
+	const channel = new BroadcastChannel(room);
+	return {
+		send(message) {
+			channel.postMessage(message);
+		},
+		onMessage(handler) {
+			const listener = (event) => handler(event.data);
+			channel.addEventListener("message", listener);
+			return () => channel.removeEventListener("message", listener);
+		},
+		close() {
+			channel.close();
+		}
+	};
+}
+//#endregion
+export { broadcastTransport };

package/dist/color-CN1S_Vq9.mjs

@@ -0,0 +1,27 @@
+//#region src/color.ts
+/**
+* Deterministic hue per id: the same participant keeps the same color across
+* reloads and across clients without any color negotiation.
+*/
+function hashHue(id) {
+	let hash = 0;
+	for (let i = 0; i < id.length; i++) {
+		hash = id.charCodeAt(i) + ((hash << 5) - hash);
+		hash |= 0;
+	}
+	return Math.abs(hash) % 360;
+}
+function cursorColor(id, options = {}) {
+	const { saturation = 70, lightness = 55 } = options;
+	return `hsl(${hashHue(id)}, ${saturation}%, ${lightness}%)`;
+}
+/**
+* Picks from a fixed palette instead of the full hue circle — for brand palettes
+* or when hues have to stay distinguishable for color-blind viewers.
+*/
+function paletteColor(id, palette) {
+	if (palette.length === 0) return cursorColor(id);
+	return palette[hashHue(id) % palette.length];
+}
+//#endregion
+export { hashHue as n, paletteColor as r, cursorColor as t };

package/dist/cursors-BhKZnRWg.mjs

@@ -0,0 +1,348 @@
+//#region src/protocol.ts
+const PROTOCOL_VERSION = 1;
+function clamp01(value) {
+	return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+/**
+* Turns wire data into a message, or null when it is unusable.
+* Coordinates arrive from other clients, so they are clamped rather than trusted.
+*/
+function parseMessage(raw) {
+	if (typeof raw !== "object" || raw === null) return null;
+	const data = raw;
+	if (data.v !== 1) return null;
+	const id = typeof data.id === "string" && data.id !== "" ? data.id : void 0;
+	if (data.t === "l") return id === void 0 ? {
+		v: 1,
+		t: "l"
+	} : {
+		v: 1,
+		t: "l",
+		id
+	};
+	if (data.t !== "m") return null;
+	if (typeof data.x !== "number" || typeof data.y !== "number") return null;
+	if (!Number.isFinite(data.x) || !Number.isFinite(data.y)) return null;
+	const message = {
+		v: 1,
+		t: "m",
+		x: clamp01(data.x),
+		y: clamp01(data.y)
+	};
+	if (id !== void 0) message.id = id;
+	if (typeof data.m === "object" && data.m !== null) message.m = data.m;
+	return message;
+}
+function moveMessage(id, x, y, meta) {
+	const message = {
+		v: 1,
+		t: "m",
+		id,
+		x: clamp01(x),
+		y: clamp01(y)
+	};
+	if (meta !== void 0) message.m = meta;
+	return message;
+}
+function leaveMessage(id) {
+	return {
+		v: 1,
+		t: "l",
+		id
+	};
+}
+//#endregion
+//#region src/space.ts
+function viewportSpace() {
+	return {
+		toNormalized(pointer) {
+			const width = window.innerWidth;
+			const height = window.innerHeight;
+			if (width === 0 || height === 0) return null;
+			return {
+				x: pointer.clientX / width,
+				y: pointer.clientY / height
+			};
+		},
+		fromNormalized(point) {
+			return {
+				x: point.x * window.innerWidth,
+				y: point.y * window.innerHeight
+			};
+		},
+		size() {
+			return {
+				width: window.innerWidth,
+				height: window.innerHeight
+			};
+		},
+		target() {
+			return null;
+		}
+	};
+}
+/**
+* Scroll-aware space: coordinates are relative to the scrollable content of an element,
+* so a cursor stays on the content it points at even when participants scroll differently.
+*/
+function elementSpace(resolve) {
+	const target = () => typeof resolve === "function" ? resolve() : resolve;
+	return {
+		toNormalized(pointer) {
+			const el = target();
+			if (!el) return null;
+			const rect = el.getBoundingClientRect();
+			const width = el.scrollWidth;
+			const height = el.scrollHeight;
+			if (width === 0 || height === 0) return null;
+			const x = (pointer.clientX - rect.left + el.scrollLeft) / width;
+			const y = (pointer.clientY - rect.top + el.scrollTop) / height;
+			if (x < 0 || x > 1 || y < 0 || y > 1) return null;
+			return {
+				x,
+				y
+			};
+		},
+		fromNormalized(point) {
+			const el = target();
+			if (!el) return {
+				x: 0,
+				y: 0
+			};
+			return {
+				x: point.x * el.scrollWidth,
+				y: point.y * el.scrollHeight
+			};
+		},
+		size() {
+			const el = target();
+			if (!el) return {
+				width: 0,
+				height: 0
+			};
+			return {
+				width: el.scrollWidth,
+				height: el.scrollHeight
+			};
+		},
+		target
+	};
+}
+function customSpace(space) {
+	return space;
+}
+//#endregion
+//#region src/throttle.ts
+/**
+* Leading + trailing throttle: the first move goes out immediately and the last
+* one is never dropped, which is what keeps a cursor from freezing mid-screen.
+*/
+function throttle(fn, ms) {
+	let last = 0;
+	let timer = null;
+	let pending = null;
+	const run = (args) => {
+		last = Date.now();
+		pending = null;
+		fn(...args);
+	};
+	const throttled = ((...args) => {
+		const elapsed = Date.now() - last;
+		if (elapsed >= ms) {
+			if (timer) {
+				clearTimeout(timer);
+				timer = null;
+			}
+			run(args);
+			return;
+		}
+		pending = args;
+		if (timer) return;
+		timer = setTimeout(() => {
+			timer = null;
+			if (pending) run(pending);
+		}, ms - elapsed);
+	});
+	throttled.flush = () => {
+		if (timer) {
+			clearTimeout(timer);
+			timer = null;
+		}
+		if (pending) run(pending);
+	};
+	throttled.cancel = () => {
+		if (timer) {
+			clearTimeout(timer);
+			timer = null;
+		}
+		pending = null;
+	};
+	return throttled;
+}
+//#endregion
+//#region src/cursors.ts
+const EMPTY = Object.freeze([]);
+function createCursors(options) {
+	const { transport, selfId, space = viewportSpace(), throttleMs = 40, ttlMs = 3e3, sweepMs = 1e3, maxRemote = 50, meta, onError } = options;
+	const remote = /* @__PURE__ */ new Map();
+	const listeners = /* @__PURE__ */ new Set();
+	let enabled = options.enabled ?? true;
+	let snapshot = EMPTY;
+	let snapshotDirty = false;
+	let sweepTimer = null;
+	let detachPointer = null;
+	let destroyed = false;
+	const fail = (error) => {
+		if (onError) onError(error);
+		else console.error("[live-cursors]", error);
+	};
+	const notify = () => {
+		snapshotDirty = true;
+		for (const listener of listeners) try {
+			listener();
+		} catch (error) {
+			fail(error);
+		}
+	};
+	const getSnapshot = () => {
+		if (snapshotDirty) {
+			snapshot = remote.size === 0 ? EMPTY : Object.freeze([...remote.values()]);
+			snapshotDirty = false;
+		}
+		return snapshot;
+	};
+	const stopSweep = () => {
+		if (sweepTimer) {
+			clearInterval(sweepTimer);
+			sweepTimer = null;
+		}
+	};
+	const sweep = () => {
+		const now = Date.now();
+		let changed = false;
+		for (const [id, cursor] of remote) if (now - cursor.updatedAt >= ttlMs) {
+			remote.delete(id);
+			changed = true;
+		}
+		if (remote.size === 0) stopSweep();
+		if (changed) notify();
+	};
+	const startSweep = () => {
+		if (sweepTimer || ttlMs <= 0) return;
+		sweepTimer = setInterval(sweep, sweepMs);
+		if (typeof sweepTimer === "object" && "unref" in sweepTimer) sweepTimer.unref?.();
+	};
+	const remove = (id) => {
+		if (!remote.delete(id)) return;
+		if (remote.size === 0) stopSweep();
+		notify();
+	};
+	const ingest = (raw, senderId) => {
+		if (destroyed) return;
+		const message = parseMessage(raw);
+		if (!message) return;
+		const id = senderId ?? message.id;
+		if (!id || id === selfId) return;
+		if (message.t === "l") {
+			remove(id);
+			return;
+		}
+		if (!remote.has(id) && remote.size >= maxRemote) return;
+		const cursor = {
+			id,
+			x: message.x,
+			y: message.y,
+			updatedAt: Date.now()
+		};
+		if (message.m !== void 0) cursor.meta = message.m;
+		remote.set(id, cursor);
+		startSweep();
+		notify();
+	};
+	const send = (x, y) => {
+		try {
+			transport.send(moveMessage(selfId, x, y, meta?.()));
+		} catch (error) {
+			fail(error);
+		}
+	};
+	const sendThrottled = throttle(send, throttleMs);
+	const leave = () => {
+		sendThrottled.cancel();
+		try {
+			transport.send(leaveMessage(selfId));
+		} catch (error) {
+			fail(error);
+		}
+	};
+	const unsubscribeTransport = transport.onMessage(ingest);
+	const attach = (element) => {
+		detachPointer?.();
+		if (typeof window === "undefined") return () => {};
+		const host = element ?? space.target() ?? window;
+		const onPointerMove = (event) => {
+			if (!enabled) return;
+			const pointer = event;
+			if (pointer.pointerType && pointer.pointerType !== "mouse") return;
+			const point = space.toNormalized(pointer);
+			if (!point) return;
+			sendThrottled(point.x, point.y);
+		};
+		const onPointerOut = () => {
+			if (enabled) leave();
+		};
+		const onVisibility = () => {
+			if (document.visibilityState === "hidden") onPointerOut();
+		};
+		host.addEventListener("pointermove", onPointerMove, { passive: true });
+		host.addEventListener("pointerleave", onPointerOut, { passive: true });
+		window.addEventListener("blur", onPointerOut, { passive: true });
+		document.addEventListener("visibilitychange", onVisibility, { passive: true });
+		detachPointer = () => {
+			host.removeEventListener("pointermove", onPointerMove);
+			host.removeEventListener("pointerleave", onPointerOut);
+			window.removeEventListener("blur", onPointerOut);
+			document.removeEventListener("visibilitychange", onVisibility);
+			detachPointer = null;
+		};
+		return () => detachPointer?.();
+	};
+	const detach = () => {
+		sendThrottled.cancel();
+		detachPointer?.();
+	};
+	return {
+		attach,
+		detach,
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		getSnapshot,
+		get: (id) => remote.get(id),
+		remove,
+		ingest,
+		setEnabled(next) {
+			if (enabled === next) return;
+			enabled = next;
+			if (!next) leave();
+		},
+		isEnabled: () => enabled,
+		leave,
+		space,
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			detach();
+			stopSweep();
+			leave();
+			unsubscribeTransport?.();
+			transport.close?.();
+			listeners.clear();
+			remote.clear();
+			snapshotDirty = true;
+		}
+	};
+}
+//#endregion
+export { viewportSpace as a, moveMessage as c, elementSpace as i, parseMessage as l, throttle as n, PROTOCOL_VERSION as o, customSpace as r, leaveMessage as s, createCursors as t };