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

package/README.md

@@ -2887,6 +2887,160 @@ 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.
+- `typing` / `selections` / `locks` / `reactions` and their send methods, when the matching field surfaces are declared (see [Field surfaces](#field-surfaces-typing-selections-locks-reactions)).
+
+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}
+```
+
+### Field surfaces: typing, selections, locks, reactions
+
+Declare a collaborative field surface on the export and the room view lights up a reactive projection plus a send method for it. Typing, selections, and locks are published onto the same presence roster `room.others` reads, so they cost no extra subscription; reactions ride a dedicated stream.
+
+```js
+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 }),
+  cursors: true,
+  typing: true,
+  selections: 'offset',
+  locks: ['title', 'body'],
+  reactions: true
+});
+```
+
+- **Typing** - `room.typing` is the list of remote collaborators' user keys currently flagged as typing (self excluded). Toggle the local flag with `room.setTyping(true)` / `room.setTyping(false)`. Typing is a transient flag and is never persisted on the roster.
+- **Selections** - `room.selections` is a `{ userKey: range }` map of remote selection ranges (self excluded). Publish the local offset-mode range with `room.setSelection({ start, end, nodePath })`; pass `null` to clear it. A selection is stamped on the caller's roster entry, so a late joiner loads the current selections from the roster snapshot instead of waiting for the next change.
+- **Locks** - `room.locks` is a `{ lockKey: holderUserKey }` map. `room.acquireLock('title')` announces an advisory claim on a key and `room.releaseLock('title')` clears it. A holder disconnecting drops its claims on the next roster push. These are soft, collaborative-awareness locks (they tell collaborators who is editing what), not distributed mutual exclusion - a second caller is not blocked. A held lock is stamped on the caller's roster entry, so a late joiner sees who holds what from the roster snapshot.
+- **Reactions** - `room.reactions` is a bounded ring of recent ephemeral emotes; `room.react('heart', { x, y })` emits one. Reactions are never coalesced, so a burst of taps all arrive, and old entries fall off the ring.
+
+Selections and locks persist on the roster both single-instance and across a cluster (wire `platform.redis`); typing stays ephemeral. Because a field is stamped on a roster entry that only exists once presence is set, declaring `typing`, `selections`, or `locks` requires a `presence` function - the Vite plugin and `live.multiplayer()` both reject a presence field with no presence. `reactions` are exempt: they ride their own ephemeral stream and need no presence.
+
+```svelte
+<script>
+  import { board } from '$live/collab';
+  let { boardId } = $props();
+  const room = board.room(boardId);
+</script>
+
+<input
+  oninput={() => room.setTyping(true)}
+  onblur={() => room.setTyping(false)} />
+
+{#if room.typing.length}
+  <p>{room.typing.length} editing...</p>
+{/if}
+
+<button onclick={() => room.react('heart', { x: 100, y: 40 })}>React</button>
+```
+
+A multiplayer export that declares no field surface is unchanged, and calling a field method on the namespace (rather than a `room(...)` instance) is a safe no-op that points you at `room(...)`.
+
+### 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 +3881,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), field surfaces (typing / selections / advisory locks / reactions), 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,113 @@
+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>;
+	/** Reactions sub-stream (the bounded ring of recent emotes), when enabled. */
+	reactions?: Readable<any[]>;
+	/** Outbound cursor-move send callback. */
+	move?: (...args: any[]) => any;
+	/** Outbound viewport-report send callback. Falls back to `move`. */
+	reportViewport?: (...args: any[]) => any;
+	/** Outbound presence-field send callback for typing toggles. */
+	setTyping?: (...args: any[]) => any;
+	/** Outbound presence-field send callback for selection ranges. */
+	setSelection?: (...args: any[]) => any;
+	/** Outbound presence-field send callback for advisory lock acquisition. */
+	acquireLock?: (...args: any[]) => any;
+	/** Outbound presence-field send callback for advisory lock release. */
+	releaseLock?: (...args: any[]) => any;
+	/** Outbound reaction send callback. */
+	react?: (...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` views are reactive projections of the
+ * presence roster, driven by the field-send methods; `reactions` is the bounded
+ * ring of recent ephemeral emotes.
+ */
+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;
+	/** The user keys of remote collaborators currently flagged as typing. */
+	get typing(): string[];
+	/** Advisory lock holders keyed by lock key: `{ lockKey: holderUserKey }`. */
+	get locks(): Record<string, any>;
+	/** Remote selection ranges keyed by user (self excluded). */
+	get selections(): Record<string, any>;
+	/** The bounded ring of recent reactions. */
+	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;
+	/** Emit an ephemeral reaction (a token at an optional point). */
+	react(token: any, at?: any): any;
+	/** Toggle the local typing flag, published onto the presence roster. */
+	setTyping(on: boolean): any;
+	/** Claim an advisory lock on a key (collaborative awareness, not exclusion). */
+	acquireLock(lockKey: string): any;
+	/** Release an advisory lock on a key. */
+	releaseLock(lockKey: string): any;
+	/** Publish the local selection range; pass `null` to clear it. */
+	setSelection(selection: any): any;
+	/** Unsubscribe from the injected stores. Call when the room unmounts. */
+	destroy(): void;
+}

package/client-multiplayer.svelte.js

@@ -0,0 +1,208 @@
+// @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 collaborative field surfaces - `typing`, `selections`, `locks` - are
+ * projections of the same presence roster: a caller stamps fields onto its own
+ * entry through the injected send callbacks, the presence merge layers them in,
+ * and these views read them back. `reactions` is the bounded ring of recent
+ * ephemeral emotes from the dedicated reactions stream.
+ *
+ * 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([]);
+	#reactions = $state([]);
+	#status = $state('idle');
+	#move;
+	#reportViewport;
+	#setTyping;
+	#setSelection;
+	#acquireLock;
+	#releaseLock;
+	#react;
+	#unsubs = [];
+
+	constructor(deps) {
+		this.#meSource = deps.me;
+		this.#move = deps.move;
+		this.#reportViewport = deps.reportViewport || deps.move;
+		this.#setTyping = deps.setTyping;
+		this.#setSelection = deps.setSelection;
+		this.#acquireLock = deps.acquireLock;
+		this.#releaseLock = deps.releaseLock;
+		this.#react = deps.react;
+		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; }));
+		if (deps.reactions) {
+			this.#unsubs.push(deps.reactions.subscribe((v) => { this.#reactions = 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; }
+
+	// Field surfaces are projections of the same presence roster `others` reads:
+	// a caller stamps fields onto its own roster entry through the send path, the
+	// presence merge layers them onto the entry, and these views read them back.
+	// They add no new store subscription - one derive pass over the roster the
+	// room already aggregates.
+
+	// The keys of remote collaborators currently flagged as typing.
+	#typingDerived = $derived(
+		dedupeByUser(this.#presence)
+			.filter((p) => p.typing === true && (this.me == null || p.key !== this.me))
+			.map((p) => p.key)
+	);
+	get typing() { return this.#typingDerived; }
+
+	// Advisory lock holders, keyed by lock key. A roster entry carries a held key
+	// as `lock:<key>` (truthy while held, cleared on release); the holder is the
+	// entry's own user key. This collapses the roster into a { lockKey: holder }
+	// map. A holder leaving drops its entry, so its locks recompute to absent on
+	// the next push - no stale grant survives.
+	#locksDerived = $derived(this.#deriveLocks(this.#presence));
+	get locks() { return this.#locksDerived; }
+
+	// Remote selections, keyed by user. Self is excluded so an app renders only
+	// collaborators' ranges. Each value is the selection payload the holder sent.
+	#selectionsDerived = $derived(
+		Object.fromEntries(
+			dedupeByUser(this.#presence)
+				.filter((p) => p.selection != null && (this.me == null || p.key !== this.me))
+				.map((p) => [p.key, p.selection])
+		)
+	);
+	get selections() { return this.#selectionsDerived; }
+
+	// The bounded ring of recent reactions. The send stream caps and GCs old
+	// taps, so an app renders the current window and lets entries fall off.
+	get reactions() { return this.#reactions; }
+
+	/** @param {Array<Record<string, any>>} roster */
+	#deriveLocks(roster) {
+		const out = /** @type {Record<string, any>} */ ({});
+		for (const entry of dedupeByUser(roster)) {
+			for (const field in entry) {
+				if (field.startsWith('lock:') && entry[field] != null && entry[field] !== false) {
+					out[field.slice(5)] = entry.key;
+				}
+			}
+		}
+		return out;
+	}
+
+	move(...args) { return this.#move ? this.#move(...args) : undefined; }
+	reportViewport(...args) { return this.#reportViewport ? this.#reportViewport(...args) : undefined; }
+
+	// Toggle the local typing flag. Publishes a `{ typing }` delta onto the
+	// caller's presence entry so every collaborator's `typing` view updates.
+	setTyping(on) {
+		return this.#setTyping ? this.#setTyping({ typing: !!on }) : undefined;
+	}
+
+	// Publish the local selection range. `null` clears it. Offset selections are
+	// a plain `{ start, end, nodePath }` object; the value is sent verbatim.
+	setSelection(selection) {
+		return this.#setSelection ? this.#setSelection({ selection: selection ?? null }) : undefined;
+	}
+
+	// Claim an advisory lock on a key: stamps `lock:<key>` on the caller's
+	// presence entry, which the server keys by the caller's identity. Advisory
+	// only - it announces intent, it does not block another claimant.
+	acquireLock(lockKey) {
+		if (!this.#acquireLock || lockKey == null) return undefined;
+		return this.#acquireLock({ ['lock:' + lockKey]: true });
+	}
+
+	// Release an advisory lock: clears `lock:<key>` on the caller's entry.
+	releaseLock(lockKey) {
+		if (!this.#releaseLock || lockKey == null) return undefined;
+		return this.#releaseLock({ ['lock:' + lockKey]: null });
+	}
+
+	// Emit an ephemeral reaction (an emote token at an optional point). Rides the
+	// dedicated reactions stream, never the roster, so it is a one-off event.
+	react(token, at) {
+		if (!this.#react) return undefined;
+		return at !== undefined ? this.#react(token, at) : this.#react(token);
+	}
+
+	destroy() {
+		for (const off of this.#unsubs) off();
+		this.#unsubs = [];
+	}
+}

package/client-runtime.js

@@ -0,0 +1,138 @@
+// @ts-check
+
+/**
+ * Injectable runtime environment for the clock, RNG, and timers - browser build.
+ *
+ * Browser client code reads time, randomness, and schedules timers exclusively
+ * through the named helpers exported here instead of touching `Date.now`,
+ * `Math.random`, `crypto`, or `setTimeout` directly. The helper names and the
+ * environment shape are kept byte-identical with the node `shared/runtime.js`
+ * copy so the two never drift and callers are interchangeable. The difference is
+ * the binding: this copy is backed entirely by browser globals (no `node:`
+ * imports), so it bundles cleanly for the browser, while a controlled simulation
+ * harness running the same client code under node can still swap in seeded
+ * virtual implementations via `setRuntimeEnv`.
+ *
+ * In production the helpers bind the native globals with zero measurable
+ * overhead: one read over a frozen, never-swapped environment object that V8
+ * keeps monomorphic and inlines straight through to the native calls.
+ *
+ * @module svelte-realtime/client-runtime
+ */
+
+// The browser clock is a direct wall read: the clients never had a 1Hz cache,
+// so reading `Date.now()` per call preserves their existing behavior (and lets a
+// test's fake-timer Date mock propagate directly). `performance.now()` drives
+// monotonic duration math when present, falling back to the wall clock when not.
+const _hasPerf = typeof globalThis.performance !== 'undefined' && typeof globalThis.performance.now === 'function';
+const _processStartEpoch = _hasPerf ? Date.now() - globalThis.performance.now() : 0;
+const _webcrypto = (typeof globalThis.crypto !== 'undefined') ? globalThis.crypto : undefined;
+
+// v4-shaped fallback when Web Crypto randomUUID is unavailable (non-secure
+// context / old browser). Uses the env RNG so a seeded run still reproduces it.
+function _uuidFallback(rngFloat) {
+	let out = '';
+	for (let i = 0; i < 36; i++) {
+		if (i === 8 || i === 13 || i === 18 || i === 23) { out += '-'; continue; }
+		if (i === 14) { out += '4'; continue; }
+		const r = (rngFloat() * 16) | 0;
+		out += (i === 19 ? ((r & 0x3) | 0x8) : r).toString(16);
+	}
+	return out;
+}
+
+// One frozen environment object, one stable hidden class. In production
+// `current === defaultEnv` for the whole page lifetime (no override ever
+// installs), so V8 sees a monomorphic shape and inlines the helpers to the
+// native primitives - zero measurable overhead on the hot path.
+const defaultEnv = Object.freeze({
+	clock: Object.freeze({
+		now: () => Date.now(),                                                  // wall, direct read
+		monotonic: _hasPerf ? () => _processStartEpoch + globalThis.performance.now() : () => Date.now(), // strictly-forward duration math
+		wallEpoch: () => Date.now()                                             // exact wall clock; identity baseline
+	}),
+	rng: Object.freeze({
+		float: () => Math.random(),
+		u32: () => (Math.random() * 0x100000000) >>> 0,
+		uuid: (_webcrypto && typeof _webcrypto.randomUUID === 'function')
+			? () => _webcrypto.randomUUID()
+			: () => _uuidFallback(() => Math.random()),
+		bytes: (_webcrypto && typeof _webcrypto.getRandomValues === 'function')
+			? (n) => _webcrypto.getRandomValues(new Uint8Array(n))
+			: (n) => { const a = new Uint8Array(n); for (let i = 0; i < n; i++) a[i] = (Math.random() * 256) | 0; return a; }
+	}),
+	timers: Object.freeze({
+		set: (cb, ms, ...a) => setTimeout(cb, ms, ...a),
+		setInterval: (cb, ms, ...a) => setInterval(cb, ms, ...a),
+		// No setImmediate in the browser: a zero-delay macrotask is the closest.
+		setImmediate: (cb, ...a) => setTimeout(cb, 0, ...a),
+		clear: (h) => clearTimeout(h),
+		clearInterval: (h) => clearInterval(h),
+		queueMicrotask: (typeof globalThis.queueMicrotask === 'function')
+			? (cb) => globalThis.queueMicrotask(cb)
+			: (cb) => Promise.resolve().then(cb)
+	}),
+	tz: undefined // effective timezone for cron evaluation; undefined = real local TZ
+});
+
+let current = defaultEnv;
+
+// The named helpers are the ONLY thing browser client code imports. Each is a
+// one-line read over `current` - monomorphic in prod, inlined by V8.
+export const now = () => current.clock.now();
+export const monotonicNow = () => current.clock.monotonic();
+export const wallEpoch = () => current.clock.wallEpoch();
+export const randomFloat = () => current.rng.float();
+export const randomU32 = () => current.rng.u32();
+export const randomUuid = () => current.rng.uuid();
+export const randomBytes = (n) => current.rng.bytes(n);
+export const setTimer = (cb, ms, ...a) => current.timers.set(cb, ms, ...a);
+export const setIntervalTimer = (cb, ms, ...a) => current.timers.setInterval(cb, ms, ...a);
+export const setImmediateTimer = (cb, ...a) => current.timers.setImmediate(cb, ...a);
+export const clearTimer = (h) => current.timers.clear(h);
+export const clearIntervalTimer = (h) => current.timers.clearInterval(h);
+export const microtask = (cb) => current.timers.queueMicrotask(cb);
+export const effectiveTimeZone = () => current.tz;
+
+/**
+ * Install a virtual environment (the simulator / test harness only). Refuses in
+ * 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` and nothing calls this anyway. A partial env merges over the native
+ * defaults, so a harness can override just the clock and keep native rng / timers.
+ *
+ * @param {object} [env] - Partial environment. Any of `clock`, `rng`, `timers`
+ *   may carry a subset of their fields; provided fields override the native
+ *   default, omitted fields fall through to native. `tz` overrides only when the
+ *   property is present (including an explicit `undefined`).
+ * @param {object} [opts]
+ * @param {boolean} [opts.force] - Allow the swap even when
+ *   `process.env.NODE_ENV === 'production'`. Use only inside a controlled
+ *   simulation harness.
+ * @returns {object} The newly installed frozen environment.
+ */
+export function setRuntimeEnv(env, opts) {
+	const force = opts && opts.force === true;
+	if (typeof process !== 'undefined' && process.env && process.env.NODE_ENV === 'production' && !force) {
+		throw new Error('client runtime: setRuntimeEnv refused in production (pass { force: true } only inside a controlled simulation harness)');
+	}
+	current = Object.freeze({
+		clock: Object.freeze({ ...defaultEnv.clock, ...(env && env.clock) }),
+		rng: Object.freeze({ ...defaultEnv.rng, ...(env && env.rng) }),
+		timers: Object.freeze({ ...defaultEnv.timers, ...(env && env.timers) }),
+		tz: env && Object.prototype.hasOwnProperty.call(env, 'tz') ? env.tz : defaultEnv.tz
+	});
+	return current;
+}
+
+/**
+ * Restore the native environment. Cheap wholesale reassignment (no per-field
+ * mutation), so the hidden class stays stable.
+ */
+export function resetRuntimeEnv() { current = defaultEnv; }
+
+/**
+ * Read-only accessor for the active environment (test / sim introspection only).
+ * @returns {object} The active frozen environment.
+ */
+export function getRuntimeEnv() { return current; }

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