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

package/README.md

@@ -2920,6 +2920,7 @@ export const board = live.multiplayer({
 - `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.
 
@@ -2978,9 +2979,50 @@ The raw `data` / `presence` / `cursors` factory stores stay on the export for ba
 {/each}
 ```
 
-### Reserved surfaces
+### Field surfaces: typing, selections, locks, reactions
 
-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.
+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
 
@@ -3839,7 +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), connection status, and `identify(key)` |
+| `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

@@ -40,10 +40,22 @@ export interface MultiplayerRoomDeps {
 	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;
 }
 
 /**
@@ -60,8 +72,9 @@ export interface MultiplayerRoomDeps {
  * - `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.
+ * 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);
@@ -73,28 +86,28 @@ export class MultiplayerRoom {
 	get me(): string | null;
 	/** The connection status. */
 	get status(): string;
-	/** Reserved field surface. Inert. */
-	get typing(): any[];
-	/** Reserved field surface. Inert. */
+	/** 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>;
-	/** Reserved field surface. Inert. */
+	/** Remote selection ranges keyed by user (self excluded). */
 	get selections(): Record<string, any>;
-	/** Reserved field surface. Inert. */
+	/** 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;
-	/** 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;
+	/** 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

@@ -50,6 +50,12 @@ function dedupeByUser(list) {
  * 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.
  */
@@ -57,18 +63,32 @@ 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
@@ -95,21 +115,91 @@ export class MultiplayerRoom {
 	);
 	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 []; }
+	// 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; }
 
-	react() {}
-	setTyping() {}
-	acquireLock() {}
-	releaseLock() {}
-	setSelection() {}
+	// 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();

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; }