svelte-realtime 0.6.0-next.2 → 0.6.0-next.3

package/README.md

@@ -2887,6 +2887,118 @@ export const { message, close, unsubscribe } = board.hooks;
 
 ---
 
+## Multiplayer
+
+`live.multiplayer()` bundles the collaborative surfaces - live cursors and presence - into a single declaration. It reuses the same data, presence, and cursor machinery a room uses, so the data stream, presence auto-join, and scoped actions behave exactly like `live.room()`. The difference is on the client: the generated export carries a connection-aware surface alongside the sub-streams - a `status` connection store, the `move` / `reportViewport` cursor methods, `identify(key)`, and a `room(...)` factory that returns the aggregated roster view.
+
+```js
+// src/live/collab.js
+import { live } from 'svelte-realtime/server';
+
+export const board = live.multiplayer({
+  topic: (ctx, boardId) => 'board:' + boardId,
+  topicArgs: 1,
+  init: async (ctx, boardId) => db.cards.forBoard(boardId),
+  presence: (ctx) => ({ name: ctx.user.name, avatar: ctx.user.avatar }),
+  cursors: true,
+  actions: {
+    addCard: async (ctx, boardId, title) => {
+      const card = await db.cards.insert({ boardId, title });
+      ctx.publish('created', card);
+      return card;
+    }
+  }
+});
+```
+
+### The roster view
+
+`board.room(...)` aggregates the raw presence and cursor streams into the reactive surface an app renders. It is the recommended way to consume a multiplayer export:
+
+- `others` - the presence roster, deduped by user key (latest wins), each entry stamped with a deterministic color, and with the local user excluded once it is known.
+- `cursors` - deduped by user key and colored. The local user is kept so you can render your own cursor.
+- `me` - the local user's key, or `null` until you name it.
+- `status` - the connection-status passthrough.
+- `move(...)` / `reportViewport(...)` - forward to the cursor send path.
+
+Name the current user once with `board.identify(key)` - the same identity you already supply for presence, available from the SvelteKit page load. Calling `identify(key)` after `board.room(...)` still lights up `me` and self-exclusion. If you never call it the surface degrades gracefully: `others` is the full deduped roster and `me` reads `null`, never a crash.
+
+```svelte
+<script>
+  import { board } from '$live/collab';
+
+  let { data, boardId } = $props();   // data.userId from the SvelteKit load
+  board.identify(data.userId);        // names self; me + self-exclusion light up
+
+  const room = board.room(boardId);
+
+  function onPointerMove(e) {
+    // move() is volatile (fire-and-forget) - lossy under disconnect is the contract.
+    room.move(boardId, { x: e.clientX, y: e.clientY });
+  }
+</script>
+
+<div onpointermove={onPointerMove}>
+  <ul class="roster">
+    {#each room.others as person (person.key)}
+      <li style:color={person.color}>{person.name}</li>
+    {/each}
+  </ul>
+
+  {#each room.cursors as c (c.key)}
+    <Cursor x={c.x} y={c.y} color={c.color} />
+  {/each}
+
+  {#if room.me == null}
+    <p>Pass a user key to <code>board.identify(...)</code> to highlight yourself.</p>
+  {/if}
+</div>
+
+<button onclick={() => board.addCard(boardId, 'New card')}>Add</button>
+```
+
+The aggregated view ships from the `svelte-realtime/multiplayer` subpath and is reactive: `others` and `cursors` refresh whenever the underlying presence or cursor stream pushes. Reactivity uses Svelte 5 runes, so `board.room(...)` requires Svelte 5.
+
+### Raw sub-streams
+
+The raw `data` / `presence` / `cursors` factory stores stay on the export for back-compat and lower-level use; `board.room(...)` composes them for you.
+
+```svelte
+<script>
+  import { board } from '$live/collab';
+  let { boardId } = $props();
+
+  const data = board.data(boardId);       // main data stream
+  const cursors = board.cursors(boardId); // raw cursor stream (uncolored, undeduped)
+  const status = board.status;            // connection status store
+</script>
+
+{#each $data as card (card.id)}
+  <Card {card} />
+{/each}
+```
+
+### Reserved surfaces
+
+The `typing`, `locks`, `selections`, and `reactions` views and their methods (`setTyping`, `acquireLock`, `releaseLock`, `setSelection`, `react`) are present on the export so the API shape is stable, but they are inert for now: the views read empty and the methods are no-ops that emit a single dev-mode note. They activate once the client-to-server field send path lands; declaring `typing: true`, `locks: ['cell']`, `reactions: true`, or `selections: 'offset'` reserves the surface without changing today's behavior.
+
+### Deterministic user colors
+
+`colorForKey(key)` and `hueForKey(key)` derive a stable color from a user key with a 32-bit FNV-1a hash, so a server render and the first client paint compute the identical color with no hydration mismatch.
+
+The hue is the folded hash; saturation and lightness are each drawn from a legible band using high bits of the same hash, so the palette spans 4320 distinct swatches (360 hues x 3 saturation bands x 4 lightness bands) instead of hue alone. Two keys are far less likely to share a swatch, and every swatch keeps a legible contrast for foreground text. `hueForKey(key)` is unchanged and still returns the raw hue, so a caller building its own color expression from the hue is unaffected.
+
+```js
+import { colorForKey } from 'svelte-realtime/client';
+
+const fill = colorForKey(user.id);
+// saturation and lightness vary per key, e.g.
+// colorForKey('alice') -> 'hsl(239, 70%, 45%)'
+// colorForKey('carol') -> 'hsl(2, 85%, 55%)'
+```
+
+---
+
 ## Webhooks
 
 Bridge external HTTP webhooks into your pub/sub topics.
@@ -3727,6 +3839,7 @@ Import from `svelte-realtime/server`.
 | `live.effect(sources, fn, options?)` | Server-side reactive side effect |
 | `live.aggregate(source, reducers, options)` | Real-time incremental aggregation |
 | `live.room(config)` | Collaborative room (data + presence + cursors + actions) |
+| `live.multiplayer(config)` | Collaborative surface: room sub-streams plus an aggregated roster view (`room(...)` -> `others` / `cursors` / `me`, colored and deduped), live cursors (move / reportViewport), connection status, and `identify(key)` |
 | `live.webhook(topic, config)` | HTTP webhook-to-stream bridge |
 | `live.gate(predicate, fn)` | Conditional stream activation |
 | `live.rateLimit(config, fn)` | Per-function sliding window rate limiter |

package/client-multiplayer.d.ts

@@ -0,0 +1,100 @@
+import type { Readable } from 'svelte/store';
+
+/** A roster entry: a user key plus the presence payload and a stamped color. */
+export interface RosterEntry {
+	key: string;
+	color: string;
+	[field: string]: any;
+}
+
+/** A cursor entry: a user key, position fields, and a stamped color. */
+export interface CursorEntry {
+	key: string;
+	color: string;
+	[field: string]: any;
+}
+
+/**
+ * A reactive holder for the local user's key. The generated `live.multiplayer()`
+ * namespace owns one; the app sets it once via `namespace.identify(key)` and the
+ * `MultiplayerRoom` reads it through `me`. Until set it reads `null`.
+ */
+export interface LocalKeySource {
+	readonly value: string | null;
+	set(next: string | null | undefined): void;
+}
+
+/**
+ * Create a reactive local-key holder. The generated namespace constructs one
+ * per multiplayer export; an app rarely calls this directly.
+ */
+export function localKeySource(initial?: string | null): LocalKeySource;
+
+/** Dependencies the generated namespace injects when it constructs a room. */
+export interface MultiplayerRoomDeps {
+	/** The local user's key, a reactive holder, or null/undefined when unknown. */
+	me?: string | LocalKeySource | null;
+	/** Presence sub-stream (the per-room factory store). */
+	presence: Readable<any[]>;
+	/** Cursor sub-stream (the per-room factory store). */
+	cursors: Readable<any[]>;
+	/** Connection-status store. */
+	status: Readable<string>;
+	/** Outbound cursor-move send callback. */
+	move?: (...args: any[]) => any;
+	/** Outbound viewport-report send callback. Falls back to `move`. */
+	reportViewport?: (...args: any[]) => any;
+}
+
+/**
+ * Live roster aggregation for a `live.multiplayer()` room. Composes the
+ * generated presence / cursor / status stores into the public surface an app
+ * renders. The aggregated views are reactive: they refresh when the underlying
+ * stores push.
+ *
+ * - `others`: the presence roster, deduped by user key (latest wins), each
+ *   entry stamped with a deterministic color, excluding the local user when
+ *   `me` is known. When `me` is unknown it is the full deduped roster.
+ * - `cursors`: deduped by user key (latest wins) and colored. Self is not
+ *   excluded so the local user can render its own cursor.
+ * - `me`: the local user's key, or `null` when the app never supplied one.
+ * - `status`: the connection-status passthrough.
+ *
+ * The `typing` / `locks` / `selections` / `reactions` field surfaces and their
+ * methods are reserved and inert.
+ */
+export class MultiplayerRoom {
+	constructor(deps: MultiplayerRoomDeps);
+	/** The presence roster: deduped, colored, self-excluded when `me` is known. */
+	get others(): RosterEntry[];
+	/** The cursor roster: deduped and colored (self not excluded). */
+	get cursors(): CursorEntry[];
+	/** The local user's key, or `null` when unknown. */
+	get me(): string | null;
+	/** The connection status. */
+	get status(): string;
+	/** Reserved field surface. Inert. */
+	get typing(): any[];
+	/** Reserved field surface. Inert. */
+	get locks(): Record<string, any>;
+	/** Reserved field surface. Inert. */
+	get selections(): Record<string, any>;
+	/** Reserved field surface. Inert. */
+	get reactions(): any[];
+	/** Forward a cursor move to the injected send callback. */
+	move(...args: any[]): any;
+	/** Forward a viewport report to the injected send callback. */
+	reportViewport(...args: any[]): any;
+	/** Reserved no-op. */
+	react(...args: any[]): void;
+	/** Reserved no-op. */
+	setTyping(...args: any[]): void;
+	/** Reserved no-op. */
+	acquireLock(...args: any[]): void;
+	/** Reserved no-op. */
+	releaseLock(...args: any[]): void;
+	/** Reserved no-op. */
+	setSelection(...args: any[]): void;
+	/** Unsubscribe from the injected stores. Call when the room unmounts. */
+	destroy(): void;
+}

package/client-multiplayer.svelte.js

@@ -0,0 +1,118 @@
+// @ts-check
+import { colorForKey } from './shared/color.js';
+
+/**
+ * A tiny reactive holder for the local user's key. The generated namespace
+ * owns one and the app sets it once with `namespace.identify(key)`; the
+ * `MultiplayerRoom` reads it through `me` so calling `identify(key)` after the
+ * room is created still lights up self-exclusion. Until set it is `null`, which
+ * the room treats as "self unknown" (the full deduped roster, no crash).
+ *
+ * @param {string | null} [initial]
+ */
+export function localKeySource(initial) {
+	let key = $state(initial ?? null);
+	return {
+		get value() { return key; },
+		/** @param {string | null | undefined} next */
+		set(next) { key = next ?? null; }
+	};
+}
+
+/**
+ * Dedupe a roster list by user key, keeping the latest entry per key. Entries
+ * without a key are dropped (they cannot be addressed or colored).
+ *
+ * @param {Array<{ key?: string }> | null | undefined} list
+ * @returns {Array<any>}
+ */
+function dedupeByUser(list) {
+	const seen = new Map();
+	for (const item of list || []) {
+		if (item && item.key != null) seen.set(item.key, item);
+	}
+	return [...seen.values()];
+}
+
+/**
+ * Live roster aggregation for a `live.multiplayer()` room. Composes the
+ * generated presence / cursor / status stores into the public surface an app
+ * renders: `others` (the presence roster, deduped by user key, each entry
+ * stamped with a deterministic color, excluding the local user when known),
+ * `cursors` (deduped + colored), `me` (the local user key, or `null` when the
+ * app never supplied one), and `status` (the connection-status passthrough).
+ *
+ * When `me` is unknown the surface degrades gracefully: `others` is the full
+ * deduped roster (no self-exclusion) and `me` reads `null`, never a crash.
+ *
+ * `me` is supplied either as a plain key or as a reactive holder (the
+ * `localKeySource` the generated namespace owns). Reading it through a getter
+ * means `identify(key)` called after the room is constructed updates self-
+ * exclusion live.
+ *
+ * The views are `$derived` over `$state` snapshots of the injected stores, so a
+ * store push followed by a reactive flush refreshes every view.
+ */
+export class MultiplayerRoom {
+	#meSource;
+	#presence = $state([]);
+	#cursors = $state([]);
+	#status = $state('idle');
+	#move;
+	#reportViewport;
+	#unsubs = [];
+
+	constructor(deps) {
+		this.#meSource = deps.me;
+		this.#move = deps.move;
+		this.#reportViewport = deps.reportViewport || deps.move;
+		this.#unsubs.push(deps.presence.subscribe((v) => { this.#presence = v || []; }));
+		this.#unsubs.push(deps.cursors.subscribe((v) => { this.#cursors = v || []; }));
+		this.#unsubs.push(deps.status.subscribe((v) => { this.#status = v; }));
+	}
+
+	// Reads the reactive holder when one was injected (so identify(key) after
+	// construction lights up self-exclusion), else the plain value, else null.
+	get me() {
+		const m = this.#meSource;
+		const raw = (m && typeof m === 'object' && 'value' in m) ? m.value : m;
+		// The server stamps every presence/cursor key as String(id), so coerce
+		// the local key the same way - a numeric identify(42) still self-excludes
+		// against the stored "42" instead of silently showing the local user.
+		return raw == null ? null : String(raw);
+	}
+	get status() { return this.#status; }
+
+	#othersDerived = $derived(
+		dedupeByUser(this.#presence)
+			.filter((p) => this.me == null || p.key !== this.me)
+			.map((p) => ({ ...p, color: colorForKey(p.key) }))
+	);
+	get others() { return this.#othersDerived; }
+
+	#cursorsDerived = $derived(
+		dedupeByUser(this.#cursors).map((c) => ({ ...c, color: colorForKey(c.key) }))
+	);
+	get cursors() { return this.#cursorsDerived; }
+
+	// Stubbed field surfaces: present so the API shape is stable, inert until
+	// the client-to-server presence-field send path lands.
+	get typing() { return []; }
+	get locks() { return {}; }
+	get selections() { return {}; }
+	get reactions() { return []; }
+
+	move(...args) { return this.#move ? this.#move(...args) : undefined; }
+	reportViewport(...args) { return this.#reportViewport ? this.#reportViewport(...args) : undefined; }
+
+	react() {}
+	setTyping() {}
+	acquireLock() {}
+	releaseLock() {}
+	setSelection() {}
+
+	destroy() {
+		for (const off of this.#unsubs) off();
+		this.#unsubs = [];
+	}
+}

package/client.d.ts

@@ -390,6 +390,18 @@ export function __stream(
 	isDynamic: true
 ): (...args: any[]) => StreamStore;
 
+/**
+ * Build the reserved field-surface members of a generated `live.multiplayer()`
+ * namespace: the empty `typing` / `locks` / `selections` / `reactions` views
+ * and the no-op `setTyping` / `acquireLock` / `releaseLock` / `setSelection` /
+ * `react` methods. The codegen spreads the result into the namespace object and
+ * adds the live `data` / `presence` / `cursors` / `status` / `move` /
+ * `reportViewport` members on top.
+ *
+ * @internal
+ */
+export function __mpFields(): Record<string, any>;
+
 /**
  * Group multiple RPC calls into a single WebSocket frame.
  * All calls are sent together and responses come back in one frame.
@@ -783,6 +795,23 @@ export type FailureClass = 'TERMINAL' | 'EXHAUSTED' | 'THROTTLE' | 'RETRY' | 'AU
  */
 export const failure: Readable<Failure | null>;
 
+/**
+ * Reactive store holding the connection status. Re-exported from
+ * `svelte-adapter-uws/client`. The generated `live.multiplayer()` namespace
+ * exposes this as its `status` view.
+ */
+export const status: Readable<string>;
+
+/**
+ * Deterministic `hsl(...)` color for a stable user key. The same key yields
+ * the same color on the server and on every client, so server-rendered markup
+ * and the first client paint agree without a hydration mismatch. Use it to
+ * stamp a per-user color on a roster or cursor entry.
+ */
+export function colorForKey(key: string): string;
+/** Raw deterministic hue (0..359) for a stable user key. */
+export function hueForKey(key: string): number;
+
 /**
  * Reactive store that emits `true` when every active stream has
  * finished loading (or errored) and `false` while at least one is

package/client.js

@@ -3,6 +3,7 @@ import { connect as _connect, on, status, denials, onRequest as _adapterOnReques
 import { writable, readable } from 'svelte/store';
 import { assert } from './shared/assert.js';
 export { assert, getAssertionCounters, _resetAssertCounters } from './shared/assert.js';
+export { colorForKey, hueForKey } from './shared/color.js';
 import { mergeKeyField, rebuildIndex } from './shared/merge.js';
 import { sanitizeRowData } from './shared/safe-assign.js';
 // Namespace import lets .rune() access fromStore (Svelte 5 only) without
@@ -841,6 +842,45 @@ export function __rpc(path) {
 	return rpcCall;
 }
 
+let _mpStubNoteFired = false;
+
+/**
+ * Build the reserved field-surface members of a generated `live.multiplayer()`
+ * namespace: the `typing` / `locks` / `selections` / `reactions` views (empty)
+ * and the `setTyping` / `acquireLock` / `releaseLock` / `setSelection` / `react`
+ * methods (no-op). These keep the namespace shape stable for the follow-up that
+ * wires the client->server send path; calling a method is a safe no-op and
+ * emits one dev-only note so a render loop does not spam the console.
+ *
+ * Spread into the generated namespace object: the live `data` / `presence` /
+ * `cursors` / `status` / `move` / `reportViewport` members and the room actions
+ * are added by the codegen and override nothing here.
+ *
+ * @returns {Record<string, any>}
+ */
+export function __mpFields() {
+	const note = (method) => {
+		if (_mpStubNoteFired) return;
+		_mpStubNoteFired = true;
+		if (typeof console !== 'undefined' && console.warn) {
+			console.warn(
+				`[svelte-realtime] multiplayer.${method}() is reserved and currently a no-op; the field surface is not yet active.\n  See: https://svti.me/multiplayer`
+			);
+		}
+	};
+	return {
+		typing: [],
+		locks: {},
+		selections: {},
+		reactions: [],
+		setTyping() { note('setTyping'); },
+		acquireLock() { note('acquireLock'); },
+		releaseLock() { note('releaseLock'); },
+		setSelection() { note('setSelection'); },
+		react() { note('react'); }
+	};
+}
+
 /**
  * Internal: send an RPC request over the WebSocket.
  * @param {string} path
@@ -4209,3 +4249,12 @@ export { onDerived } from 'svelte-adapter-uws/client';
  * successful `'open'`. Not set on intentional `close()`.
  */
 export { failure } from 'svelte-adapter-uws/client';
+
+/**
+ * Re-export `status` from the adapter client.
+ * Reactive store holding the connection status: 'loading', 'connected',
+ * 'reconnecting', or 'error'. The generated multiplayer namespace exposes this
+ * as its `status` view so a collaborative surface can react to connectivity
+ * without a separate adapter import.
+ */
+export { status } from 'svelte-adapter-uws/client';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-realtime",
-  "version": "0.6.0-next.2",
+  "version": "0.6.0-next.3",
   "publishConfig": {
     "tag": "next"
   },
@@ -30,6 +30,10 @@
       "types": "./client.d.ts",
       "default": "./client.js"
     },
+    "./multiplayer": {
+      "types": "./client-multiplayer.d.ts",
+      "default": "./client-multiplayer.svelte.js"
+    },
     "./vite": {
       "types": "./vite.d.ts",
       "default": "./vite.js"
@@ -56,6 +60,8 @@
     "server.d.ts",
     "client.js",
     "client.d.ts",
+    "client-multiplayer.svelte.js",
+    "client-multiplayer.d.ts",
     "vite.js",
     "vite.d.ts",
     "test.js",

package/server.d.ts

@@ -722,6 +722,15 @@ export const combineMin: (...buckets: number[]) => number;
 export const combineCounts: (...buckets: Array<Record<string, number> | undefined>) => Record<string, number>;
 export const combineMerge: <T extends object>(...buckets: Array<T | undefined>) => T;
 
+/**
+ * Deterministic `hsl(...)` color for a stable user key. The same key yields
+ * the same color on the server and on every client, so server-rendered markup
+ * and the first client paint agree without a hydration mismatch.
+ */
+export function colorForKey(key: string): string;
+/** Raw deterministic hue (0..359) for a stable user key. */
+export function hueForKey(key: string): number;
+
 /**
  * Maximum number of hop buckets a single sliding window may allocate.
  * Sliding state is `O(bucketCount * per-bucket state)`. Default 1000;
@@ -1885,6 +1894,26 @@ export namespace live {
 	 */
 	function room(config: RoomConfig): RoomExport;
 
+	/**
+	 * Bundle the collaborative surfaces (live cursors and presence) into one
+	 * declaration whose codegen produces a connection-aware client object.
+	 * Reuses the room sub-stream machinery for the `data` / `presence` /
+	 * `cursors` streams, then adds the `status` connection store and the
+	 * `move` / `reportViewport` cursor methods on the client. The cursor
+	 * methods publish a keyed update to the room's cursor sub-topic, so the
+	 * `cursors` stream reflects every connected client's position.
+	 *
+	 * @example
+	 * ```js
+	 * export const board = live.multiplayer({
+	 *   topic: (ctx, id) => 'board:' + id,
+	 *   presence: (ctx) => ({ id: ctx.user.id, name: ctx.user.name }),
+	 *   cursors: true
+	 * });
+	 * ```
+	 */
+	function multiplayer(config: MultiplayerConfig): MultiplayerExport;
+
 	/**
 	 * Create a webhook-to-stream bridge.
 	 * The returned handler can be used in a SvelteKit +server.js POST endpoint.
@@ -2132,6 +2161,56 @@ export interface RoomExport {
 	__actions?: Record<string, any>;
 }
 
+/**
+ * Configuration for `live.multiplayer()`. Mirrors `RoomConfig` and adds the
+ * reserved field-surface declarations.
+ */
+export interface MultiplayerConfig {
+	/** Function that computes the room topic from context and args. */
+	topic: (ctx: LiveContext<any>, ...args: any[]) => string;
+	/** Initial data for the room's data stream. Defaults to an empty list. */
+	init?: (ctx: LiveContext<any>, ...args: any[]) => Promise<any>;
+	/** Presence payload for the connecting user. Drives the roster. */
+	presence?: (ctx: LiveContext<any>) => any;
+	/** Enable cursor tracking. Pass `true` or `{ throttle: ms }`. */
+	cursors?: boolean | { throttle?: number };
+	/** Room-scoped RPC actions on the data stream. */
+	actions?: Record<string, (ctx: LiveContext<any>, ...args: any[]) => any>;
+	/** Guard run before data access and actions. */
+	guard?: (ctx: LiveContext<any>, ...args: any[]) => void | Promise<void>;
+	/** Called when a user joins. */
+	onJoin?: (ctx: LiveContext<any>, ...args: any[]) => void | Promise<void>;
+	/** Called when a user leaves. */
+	onLeave?: (ctx: LiveContext<any>, topic: string) => void | Promise<void>;
+	/** Merge strategy for the data stream. @default 'crud' */
+	merge?: string;
+	/** Key field for the data stream. @default 'id' */
+	key?: string;
+	/** Number of room-identifying args the topic function expects (excluding ctx). */
+	topicArgs?: number;
+	/** Reserve a typing indicator surface. Not yet active. */
+	typing?: boolean;
+	/** Reserve advisory single-holder lock surfaces by key. Not yet active. */
+	locks?: string[];
+	/** Reserve an ephemeral reactions surface. Not yet active. */
+	reactions?: boolean;
+	/** Reserve a remote-selection surface. Not yet active. */
+	selections?: 'offset' | 'crdt';
+}
+
+/**
+ * Return type of `live.multiplayer()`. A superset of `RoomExport`.
+ */
+export interface MultiplayerExport extends RoomExport {
+	__isMultiplayer: true;
+	__fields: {
+		typing: boolean;
+		locks: string[] | null;
+		reactions: boolean;
+		selections: 'offset' | 'crdt' | null;
+	};
+}
+
 /**
  * Webhook configuration for `live.webhook()`.
  */

package/server.js

@@ -2,6 +2,7 @@
 import { assert, wireAssertionMetrics } from './shared/assert.js';
 import { safeAssign as _safeAssignSnapshot } from './shared/safe-assign.js';
 export { assert, getAssertionCounters, _resetAssertCounters } from './shared/assert.js';
+export { colorForKey, hueForKey } from './shared/color.js';
 
 const textDecoder = new TextDecoder();
 const _validPathRe = /^[a-zA-Z0-9_-]+(?:\/[a-zA-Z0-9_-]+)+$/;
@@ -5347,6 +5348,92 @@ live.room = function room(config) {
 	return roomExport;
 };
 
+live.multiplayer = function multiplayer(config) {
+	const topicFn = config && config.topic;
+	if (typeof topicFn !== 'function') {
+		throw new Error(
+			`[svelte-realtime] live.multiplayer() requires a topic function (ctx, ...args) => string\n  See: https://svti.me/multiplayer`
+		);
+	}
+
+	// A multiplayer export is a room export with a marker stamped on top. It
+	// reuses live.room's sub-stream construction verbatim so the data /
+	// presence / cursor streams, the presence-ref auto-join, and the scoped
+	// actions are byte-identical to a room. The codegen and the dev-direct
+	// loader dispatch on __isRoom for the sub-streams; the __isMultiplayer
+	// marker only adds the collaborative client surface.
+	const roomExport = live.room({
+		topic: topicFn,
+		init: config.init ? config.init : async () => [],
+		presence: config.presence,
+		cursors: config.cursors,
+		guard: config.guard,
+		onJoin: config.onJoin,
+		onLeave: config.onLeave,
+		merge: config.merge,
+		key: config.key,
+		actions: config.actions,
+		topicArgs: config.topicArgs
+	});
+
+	/** @type {any} */ (roomExport).__isMultiplayer = true;
+
+	// Cursor send path. The client `move` / `reportViewport` methods are
+	// volatile RPCs (fire-and-forget, lossy under disconnect is the contract)
+	// that publish an `update` frame keyed by the caller's identity onto the
+	// room's `:cursors` sub-topic - the same topic the cursor stream loads and
+	// merges with `merge: 'cursor'`. The leading args identify the room (the
+	// same count the topic function and room actions use); the trailing args
+	// are the cursor payload, normalized to a flat object the cursor merge can
+	// key by `.key`.
+	const _cursorArgCount = config.topicArgs !== undefined
+		? config.topicArgs
+		: Math.max(0, topicFn.length - 1);
+
+	/**
+	 * @param {any} ctx
+	 * @param {any[]} args
+	 * @param {Record<string, any>} extra
+	 */
+	const _publishCursor = (ctx, args, extra) => {
+		const roomArgs = args.slice(0, _cursorArgCount);
+		const payload = args.slice(_cursorArgCount);
+		const cursorTopic = _callTopicFn(topicFn, ctx, roomArgs) + ':cursors';
+		const key = _getIdentityKey(ctx);
+		const frame = { key, ...extra };
+		const cur = payload[0];
+		if (cur && typeof cur === 'object' && !Array.isArray(cur)) {
+			Object.assign(frame, cur);
+		} else if (payload.length > 0) {
+			frame.value = payload.length === 1 ? cur : payload;
+		}
+		ctx.publish(cursorTopic, 'update', frame);
+	};
+
+	const _cursorGuard = config.guard;
+	/** @type {any} */ (roomExport).__cursorMove = live.volatile(async (ctx, ...args) => {
+		if (_cursorGuard) await _cursorGuard(ctx, ...args.slice(0, _cursorArgCount));
+		_publishCursor(ctx, args, {});
+	});
+	/** @type {any} */ (roomExport).__cursorReportViewport = live.volatile(async (ctx, ...args) => {
+		if (_cursorGuard) await _cursorGuard(ctx, ...args.slice(0, _cursorArgCount));
+		_publishCursor(ctx, args, { viewport: true });
+	});
+
+	// Record the declared field surfaces. The typing / locks / selections /
+	// reactions surfaces are reserved here so the returned shape is stable for
+	// the follow-up that wires the client->server send path; they produce no
+	// live sub-stream yet.
+	/** @type {any} */ (roomExport).__fields = {
+		typing: !!config.typing,
+		locks: Array.isArray(config.locks) ? config.locks.slice() : (config.locks ? [] : null),
+		reactions: !!config.reactions,
+		selections: config.selections === 'crdt' ? 'crdt' : (config.selections ? 'offset' : null)
+	};
+
+	return roomExport;
+};
+
 /** @type {{ rpcCount?: any, rpcDuration?: any, rpcErrors?: any, streamGauge?: any, cronCount?: any, cronErrors?: any, assertions?: any } | null} */
 let _metricsInstruments = null;
 

package/shared/color.js

@@ -0,0 +1,79 @@
+// @ts-check
+
+// Deterministic per-user color. Hue is an FNV-1a hash folded to 0..359.
+// Saturation and lightness are each chosen from a small band set using HIGH
+// bits of the same 32-bit hash, drawn from bit windows disjoint from the low
+// bits that `% 360` consumes. The result is 360 hues * 3 sat bands * 4 light
+// bands = 4320 distinct, perceptually separable swatches. The first entry of
+// each band set is the prior single value (70% sat, 55% light), so the palette
+// is a strict superset of the earlier single band. Every operation stays in
+// unsigned 32-bit integer space (`Math.imul` + `>>> 0`), so the value is
+// byte-identical on the server render and the first client paint. No
+// randomness, no Date.
+
+// Band sets. Index 0 of each is the legacy value, so the old single swatch
+// remains reachable and the palette only grows. Bands are spaced far enough
+// apart to read as distinct chips while every combination keeps a legible
+// contrast for foreground text (S in [60, 85], L in [38, 65] - never
+// near-white, never near-black).
+const SAT_BANDS = [70, 60, 85];
+const LIGHT_BANDS = [55, 45, 65, 38];
+
+/**
+ * Deterministic color for a stable per-user key. The same input always yields
+ * the same `hsl(...)` on the server and on every client, so server-rendered
+ * markup and the first client paint agree with no hydration mismatch.
+ *
+ * The hue is an FNV-1a hash of the key folded into 0..359; saturation and
+ * lightness are each drawn from a legible band using high bits of the same
+ * hash, widening the palette to 4320 distinct swatches without sacrificing
+ * foreground contrast. Returns an `hsl(...)` string usable directly as a CSS
+ * color or a custom property.
+ *
+ * @param {string} key - a stable per-user key
+ * @returns {string} an `hsl(h, s%, l%)` color string
+ */
+export function colorForKey(key) {
+	const h = hash32(key);
+	const hue = h % 360;
+	// Band selectors come from high bit windows. `% 360` effectively consumes
+	// the low ~9 bits (360 < 512), so reading from bit 17 and bit 23 keeps the
+	// bands statistically independent of the hue. The two windows (bits 17..
+	// and 23..) and the hue's low region do not overlap, so no selector is a
+	// slave of another.
+	const light = LIGHT_BANDS[(h >>> 17) % LIGHT_BANDS.length];
+	const sat = SAT_BANDS[(h >>> 23) % SAT_BANDS.length];
+	return `hsl(${hue}, ${sat}%, ${light}%)`;
+}
+
+/**
+ * The raw hue (0..359) for a key. Exposed separately so a caller can build a
+ * different color expression (for example a translucent selection fill) from
+ * the same deterministic hue.
+ *
+ * @param {string} key
+ * @returns {number} integer hue in [0, 360)
+ */
+export function hueForKey(key) {
+	return hash32(key) % 360;
+}
+
+/**
+ * FNV-1a, 32-bit. Offset basis 2166136261, prime 16777619. All math is kept in
+ * 32-bit unsigned space via `Math.imul` + `>>> 0` so the result is identical
+ * across engines (server Node and every browser). A naive `h * 16777619`
+ * overflows into float territory and diverges per engine, which would break the
+ * server/client color agreement.
+ *
+ * @param {string} key
+ * @returns {number} unsigned 32-bit hash
+ */
+function hash32(key) {
+	const s = typeof key === 'string' ? key : String(key);
+	let h = 2166136261;
+	for (let i = 0; i < s.length; i++) {
+		h ^= s.charCodeAt(i);
+		h = Math.imul(h, 16777619);
+	}
+	return h >>> 0;
+}

package/vite.js

@@ -15,6 +15,12 @@ const UPLOAD_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.upload\s*\(/g;
 const DERIVED_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.derived\s*\(/g;
 const DYNAMIC_DERIVED_RE = /export\s+const\s+(\w+)\s*=\s*live\.derived\s*\(\s*(?:\([^)]*\)|[a-zA-Z_$][\w$]*)\s*=>/g;
 const ROOM_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.room\s*\(/g;
+// `live.multiplayer(...)` is a room export with a collaborative client surface.
+// At runtime it carries `__isRoom` plus the same __data/__presence/__cursors
+// sub-streams, so its registry registration is identical to a room; the client
+// stub adds the aggregated `status` view and the `move`/`reportViewport`
+// cursor methods on top of the room namespace.
+const MULTIPLAYER_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.multiplayer\s*\(/g;
 const WEBHOOK_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.webhook\s*\(/g;
 const CHANNEL_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.channel\s*\(/g;
 const DYNAMIC_CHANNEL_RE = /export\s+const\s+(\w+)\s*=\s*live\.channel\s*\(\s*(?:\([^)]*\)|[a-zA-Z_$][\w$]*)\s*=>/g;
@@ -989,12 +995,25 @@ function _generateSsrStubs(filePath, modulePath) {
 		rooms.push({ name, info: _extractRoomInfo(source, name) });
 	}
 
+	// Collect live.multiplayer() exports - the SSR stub mirrors the room
+	// namespace (factory-shaped sub-streams, no-op actions) plus the empty
+	// collaborative views and no-op cursor methods, so a page that renders
+	// `board.status` / `board.move(...)` during SSR does not crash.
+	/** @type {Array<{ name: string, info: ReturnType<typeof _extractMultiplayerInfo> }>} */
+	const multiplayers = [];
+	MULTIPLAYER_EXPORT_RE.lastIndex = 0;
+	while ((match = MULTIPLAYER_EXPORT_RE.exec(source)) !== null) {
+		const name = match[1];
+		if (!/^\w+$/.test(name)) continue;
+		multiplayers.push({ name, info: _extractMultiplayerInfo(source, name) });
+	}
+
 	// Escape paths for safe embedding in generated code
 	const safePath = JSON.stringify(normalized);
 	const safeModulePath = (name) => JSON.stringify(modulePath + '/' + name);
 
-	// If no store-like / room / windowed-aggregate exports, simple re-export
-	if (storeNames.length === 0 && rooms.length === 0 && windowedAggregates.length === 0) {
+	// If no store-like / room / multiplayer / windowed-aggregate exports, simple re-export
+	if (storeNames.length === 0 && rooms.length === 0 && multiplayers.length === 0 && windowedAggregates.length === 0) {
 		return `export * from ${safePath};\n`;
 	}
 
@@ -1062,6 +1081,49 @@ function _generateSsrStubs(filePath, modulePath) {
 		lines.push(`export { _${name} as ${name} };`);
 	}
 
+	for (const { name, info } of multiplayers) {
+		// Multiplayer namespace: the same factory-shaped sub-streams a room
+		// uses, plus an empty connection-status readable and no-op cursor
+		// methods. The client factory replaces all of this on hydration.
+		lines.push(`const _${name}_data = (...args) => { const s = readable(undefined); s.hydrate = (d) => readable(d); return s; };`);
+		lines.push(`_${name}_data.load = (platform, options) => __directCall(${JSON.stringify(modulePath + '/' + name + '/__data')}, options?.args || [], platform, options);`);
+		const mpFactories = [`data: _${name}_data`];
+		if (info.hasPresence) {
+			lines.push(`const _${name}_presence = (...args) => readable(undefined);`);
+			mpFactories.push(`presence: _${name}_presence`);
+		}
+		if (info.hasCursors) {
+			lines.push(`const _${name}_cursors = (...args) => readable(undefined);`);
+			mpFactories.push(`cursors: _${name}_cursors`);
+		}
+		mpFactories.push(`status: readable('connecting')`);
+		mpFactories.push(`move: () => {}`);
+		mpFactories.push(`reportViewport: () => {}`);
+		// Reserved field-surface members rendered as their empty SSR state.
+		mpFactories.push(`typing: []`);
+		mpFactories.push(`locks: {}`);
+		mpFactories.push(`selections: {}`);
+		mpFactories.push(`reactions: []`);
+		mpFactories.push(`setTyping: () => {}`);
+		mpFactories.push(`acquireLock: () => {}`);
+		mpFactories.push(`releaseLock: () => {}`);
+		mpFactories.push(`setSelection: () => {}`);
+		mpFactories.push(`react: () => {}`);
+		// identify(...) and room(...) render their empty collaborative state on
+		// the server so a page that names self or reads the aggregated roster
+		// during SSR does not crash before hydration. No rune import on the
+		// server: room() returns a plain object, not a MultiplayerRoom.
+		if (info.hasPresence || info.hasCursors) {
+			mpFactories.push(`identify: () => {}`);
+			mpFactories.push(`room: () => ({ others: [], cursors: [], me: null, status: 'connecting', typing: [], locks: {}, selections: {}, reactions: [], move: () => {}, reportViewport: () => {}, setTyping: () => {}, acquireLock: () => {}, releaseLock: () => {}, setSelection: () => {}, react: () => {}, destroy: () => {} })`);
+		}
+		for (const action of info.actions) {
+			mpFactories.push(`${action}: () => Promise.resolve(undefined)`);
+		}
+		lines.push(`const _${name} = { ${mpFactories.join(', ')} };`);
+		lines.push(`export { _${name} as ${name} };`);
+	}
+
 	return lines.join('\n') + '\n';
 }
 
@@ -1200,6 +1262,79 @@ function _generateClientStubs(filePath, modulePath, dir) {
 		}
 	}
 
+	// Detect live.multiplayer() exports - the room namespace plus the
+	// aggregated connection status and the cursor move / reportViewport
+	// methods. Runs before the room loop and marks the name so the room loop
+	// (which guards on exportedNames) skips it - a single export is never
+	// emitted twice.
+	// Emit the rune-class import at most once per stub even when a module
+	// declares several multiplayer exports, so the generated module never has a
+	// duplicate import declaration.
+	let mpRuntimeImported = false;
+	MULTIPLAYER_EXPORT_RE.lastIndex = 0;
+	while ((match = MULTIPLAYER_EXPORT_RE.exec(source)) !== null) {
+		const name = match[1];
+		if (!/^\w+$/.test(name)) continue;
+		if (!exportedNames.has(name)) {
+			exportedNames.add(name);
+			imports.add('__stream');
+			imports.add('__rpc');
+			imports.add('status');
+			imports.add('__mpFields');
+			const mpInfo = _extractMultiplayerInfo(source, name);
+			// `others` / `cursors` / `me` aggregation needs the rune-class. It
+			// composes the generated presence / cursor / status sub-streams, so
+			// it is only constructed when a roster surface exists (presence or
+			// cursors). The class lives in a separate rune-aware subpath, not in
+			// svelte-realtime/client, so its import is a standalone line.
+			const hasRoster = mpInfo.hasPresence || mpInfo.hasCursors;
+			if (hasRoster) {
+				if (!mpRuntimeImported) {
+					lines.push(`import { MultiplayerRoom, localKeySource } from 'svelte-realtime/multiplayer';`);
+					mpRuntimeImported = true;
+				}
+				lines.push(`const _${name}_me = localKeySource();`);
+			}
+			const mpLines = [];
+			mpLines.push(`export const ${name} = {`);
+			// Reserved field-surface members (typing / locks / selections /
+			// reactions + their no-op methods). The live members below override
+			// nothing here.
+			mpLines.push(`  ...__mpFields(),`);
+			mpLines.push(`  data: __stream(${JSON.stringify(modulePath + '/' + name + '/__data')}, ${JSON.stringify(mpInfo.dataOpts)}, true),`);
+			if (mpInfo.hasPresence) {
+				mpLines.push(`  presence: __stream(${JSON.stringify(modulePath + '/' + name + '/__presence')}, ${JSON.stringify({ merge: 'presence' })}, true),`);
+			}
+			if (mpInfo.hasCursors) {
+				mpLines.push(`  cursors: __stream(${JSON.stringify(modulePath + '/' + name + '/__cursors')}, ${JSON.stringify({ merge: 'cursor' })}, true),`);
+			}
+			mpLines.push(`  status: status,`);
+			mpLines.push(`  move: __rpc(${JSON.stringify(modulePath + '/' + name + '/__cursor/move')}),`);
+			mpLines.push(`  reportViewport: __rpc(${JSON.stringify(modulePath + '/' + name + '/__cursor/reportViewport')}),`);
+			for (const action of mpInfo.actions) {
+				mpLines.push(`  ${action}: __rpc(${JSON.stringify(modulePath + '/' + name + '/__action/' + action)}),`);
+			}
+			if (hasRoster) {
+				// identify(key) names the local user once; me + self-exclusion
+				// light up. room(...args) builds the aggregated reactive view
+				// over the per-room presence / cursor sub-streams and forwards
+				// the room args to each. The object is fully assigned before
+				// room() can be called, so self-referencing ${name} is safe.
+				// A roster surface may declare presence without cursors (or the
+				// reverse); the missing sub-stream falls back to a store that
+				// pushes an empty list once, so the room always has both stores
+				// to compose without a dangling member reference.
+				const emptyStore = `{ subscribe: (fn) => { fn([]); return () => {}; } }`;
+				const presenceArg = mpInfo.hasPresence ? `${name}.presence(...args)` : emptyStore;
+				const cursorsArg = mpInfo.hasCursors ? `${name}.cursors(...args)` : emptyStore;
+				mpLines.push(`  identify(key) { _${name}_me.set(key); },`);
+				mpLines.push(`  room(...args) { return new MultiplayerRoom({ me: _${name}_me, presence: ${presenceArg}, cursors: ${cursorsArg}, status: status, move: (...a) => ${name}.move(...args, ...a), reportViewport: (...a) => ${name}.reportViewport(...args, ...a) }); },`);
+			}
+			mpLines.push(`};`);
+			lines.push(mpLines.join('\n'));
+		}
+	}
+
 	// Detect live.room() exports - generates data stream + presence stream + cursor stream + actions
 	ROOM_EXPORT_RE.lastIndex = 0;
 	while ((match = ROOM_EXPORT_RE.exec(source)) !== null) {
@@ -1890,6 +2025,58 @@ function _extractRoomInfo(source, name) {
 	return info;
 }
 
+/**
+ * Extract multiplayer config for client-stub generation. The config is
+ * room-shaped (topic / init / presence / cursors / actions / merge / key), so
+ * the room extractor supplies the data options and the presence / cursor /
+ * action discriminators; the field-surface keys are read separately so a
+ * future client surface can be told which surfaces were declared.
+ * @param {string} source
+ * @param {string} name
+ * @returns {{ dataOpts: any, hasPresence: boolean, hasCursors: boolean, actions: string[], typing: boolean, hasLocks: boolean, reactions: boolean, selections: string | null }}
+ */
+function _extractMultiplayerInfo(source, name) {
+	const startPattern = new RegExp(
+		`export\\s+const\\s+${name}\\s*=\\s*live\\.multiplayer\\s*\\(`
+	);
+	const startMatch = startPattern.exec(source);
+
+	const info = {
+		dataOpts: { merge: 'crud', key: 'id' },
+		hasPresence: false,
+		hasCursors: false,
+		actions: [],
+		typing: false,
+		hasLocks: false,
+		reactions: false,
+		selections: /** @type {string | null} */ (null)
+	};
+	if (!startMatch) return info;
+
+	const afterOpen = source.slice(startMatch.index + startMatch[0].length);
+	const body = _extractBraceContent(afterOpen);
+	if (!body) return info;
+
+	const configKeys = new Set(_extractTopLevelKeys(body));
+	info.hasPresence = configKeys.has('presence');
+	info.hasCursors = configKeys.has('cursors');
+	info.typing = configKeys.has('typing');
+	info.hasLocks = configKeys.has('locks');
+	info.reactions = configKeys.has('reactions');
+	info.selections = _extractTopLevelStringProp(body, 'selections') || null;
+
+	const mergeVal = _extractTopLevelStringProp(body, 'merge');
+	if (mergeVal) info.dataOpts.merge = mergeVal;
+	const keyVal = _extractTopLevelStringProp(body, 'key');
+	if (keyVal) info.dataOpts.key = keyVal;
+	if (info.dataOpts.merge !== 'crud' && keyVal === undefined) delete info.dataOpts.key;
+
+	const actionsBody = _extractTopLevelBraceProp(body, 'actions');
+	if (actionsBody) info.actions = _extractTopLevelKeys(actionsBody);
+
+	return info;
+}
+
 /**
  * Extract content between matching braces { ... } respecting nesting.
  * Input should start at or before the opening brace.
@@ -2055,6 +2242,27 @@ function _generateRegistry(liveDir, dir, topicsRegistry) {
 			}
 		}
 
+		// Register live.multiplayer() exports - a multiplayer export reuses the
+		// room sub-streams at runtime, so it registers the same
+		// __data/__presence/__cursors paths plus its scoped actions lazily.
+		// Running before the room loop and marking the name means the room loop
+		// (which guards on registered) skips it - never double-registered.
+		MULTIPLAYER_EXPORT_RE.lastIndex = 0;
+		while ((match = MULTIPLAYER_EXPORT_RE.exec(source)) !== null) {
+			const name = match[1];
+			if (!/^\w+$/.test(name)) continue;
+			if (!registered.has(name)) {
+				registered.add(name);
+				const importPath = JSON.stringify(normalizedPath);
+				lines.push(`__register(${JSON.stringify(rel + '/' + name + '/__data')}, __L(() => import(${importPath}).then(m => m.${name}.__dataStream)), ${JSON.stringify(rel)});`);
+				lines.push(`__register(${JSON.stringify(rel + '/' + name + '/__presence')}, __L(() => import(${importPath}).then(m => m.${name}.__presenceStream)), ${JSON.stringify(rel)});`);
+				lines.push(`__register(${JSON.stringify(rel + '/' + name + '/__cursors')}, __L(() => import(${importPath}).then(m => m.${name}.__cursorStream)), ${JSON.stringify(rel)});`);
+				lines.push(`__register(${JSON.stringify(rel + '/' + name + '/__cursor/move')}, __L(() => import(${importPath}).then(m => m.${name}.__cursorMove)), ${JSON.stringify(rel)});`);
+				lines.push(`__register(${JSON.stringify(rel + '/' + name + '/__cursor/reportViewport')}, __L(() => import(${importPath}).then(m => m.${name}.__cursorReportViewport)), ${JSON.stringify(rel)});`);
+				lines.push(`__registerRoomActions(${JSON.stringify(rel + '/' + name)}, ${_lazy(name)});`);
+			}
+		}
+
 		// Register live.room() exports - register sub-streams and actions lazily
 		ROOM_EXPORT_RE.lastIndex = 0;
 		while ((match = ROOM_EXPORT_RE.exec(source)) !== null) {
@@ -2511,6 +2719,23 @@ function _generateTypeDeclarations(liveDir, dir) {
 			}
 		}
 
+		// Detect live.multiplayer() exports - the room namespace plus the
+		// connection-status view and the cursor methods. Runs before the room
+		// branch and claims the name so the room branch skips it.
+		MULTIPLAYER_EXPORT_RE.lastIndex = 0;
+		while ((match = MULTIPLAYER_EXPORT_RE.exec(source)) !== null) {
+			const name = match[1];
+			handledNames.add(name);
+			if (!exports.some(e => e.includes(`export const ${name}:`))) {
+				needsStreamStore = true;
+				const mpInfo = _extractMultiplayerInfo(source, name);
+				const rosterMembers = (mpInfo.hasPresence || mpInfo.hasCursors)
+					? `, identify: (key: string) => void, room: (...args: any[]) => import('svelte-realtime/multiplayer').MultiplayerRoom`
+					: '';
+				exports.push(`  export const ${name}: { data: (...args: any[]) => StreamStore<any>, presence?: (...args: any[]) => StreamStore<any>, cursors?: (...args: any[]) => StreamStore<any>, status: import('svelte/store').Readable<string>, move: (...args: any[]) => void, reportViewport: (...args: any[]) => void${rosterMembers}, [action: string]: any };`);
+			}
+		}
+
 		// Detect live.room() exports
 		ROOM_EXPORT_RE.lastIndex = 0;
 		while ((match = ROOM_EXPORT_RE.exec(source)) !== null) {
@@ -3181,6 +3406,20 @@ async function _loadRegistryDirect(server, liveDir, dir) {
 			for (const [name, fn] of Object.entries(mod)) {
 				if (name === '_guard' && /** @type {any} */ (fn)?.__isGuard) {
 					__registerGuard(rel, fn);
+				} else if (/** @type {any} */ (fn)?.__isMultiplayer) {
+					// A multiplayer export reuses the room sub-streams; register
+					// them, the cursor send handlers, and its scoped actions the
+					// same way a room does.
+					if (fn.__dataStream) __register(rel + '/' + name + '/__data', fn.__dataStream, rel);
+					if (fn.__presenceStream) __register(rel + '/' + name + '/__presence', fn.__presenceStream, rel);
+					if (fn.__cursorStream) __register(rel + '/' + name + '/__cursors', fn.__cursorStream, rel);
+					if (fn.__cursorMove) __register(rel + '/' + name + '/__cursor/move', fn.__cursorMove, rel);
+					if (fn.__cursorReportViewport) __register(rel + '/' + name + '/__cursor/reportViewport', fn.__cursorReportViewport, rel);
+					if (fn.__actions) {
+						for (const [k, v] of Object.entries(fn.__actions)) {
+							__register(rel + '/' + name + '/__action/' + k, v, rel);
+						}
+					}
 				} else if (/** @type {any} */ (fn)?.__isRoom) {
 					if (fn.__dataStream) __register(rel + '/' + name + '/__data', fn.__dataStream, rel);
 					if (fn.__presenceStream) __register(rel + '/' + name + '/__presence', fn.__presenceStream, rel);