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

package/MIGRATION.md

@@ -74,6 +74,19 @@ The fix awaits the predicate before the truthiness check. The matching adapter-s
 
 These won't run cleanly until you make the change.
 
+### `svelte-realtime/test` renamed to `svelte-realtime/testing` (and `/test-client` to `/testing/client`)
+
+**What changed.** The test-authoring entry points moved: import `createTestEnv`, `createTestContext`, and `expectGuardRejects` from `svelte-realtime/testing` (was `svelte-realtime/test`), and `subscribeAt` from `svelte-realtime/testing/client` (was `svelte-realtime/test-client`). The exported names are identical; only the subpath changed, so the framework test helpers no longer collide by name with a test runner global `test`.
+
+**How to migrate.** Update the import specifiers:
+
+```diff
+- import { createTestEnv, expectGuardRejects } from 'svelte-realtime/test';
++ import { createTestEnv, expectGuardRejects } from 'svelte-realtime/testing';
+- import { subscribeAt } from 'svelte-realtime/test-client';
++ import { subscribeAt } from 'svelte-realtime/testing/client';
+```
+
 ### Runtime: Node.js 22+ required (was Node 20+)
 
 **What changed.** `package.json#engines.node` moved from `>=20.0.0` to `>=22.0.0`. Tracks the adapter's bump, which in turn tracks `uWebSockets.js` v20.67.0 dropping Node 20 support upstream.

package/README.md

@@ -256,6 +256,8 @@ Note: `ctx.user` may contain adapter-injected properties (`__subscriptions`, `re
 - [Pipes](#pipes)
 - [Binary RPC](#binary-rpc)
 - [Rooms](#rooms)
+- [Multiplayer](#multiplayer)
+- [Smoothed entities](#smoothed-entities)
 - [Webhooks](#webhooks)
 - [Signals](#signals)
 - [Schema evolution](#schema-evolution)
@@ -2125,12 +2127,14 @@ The six-line shim adapts realtime's options-object call shape to the extensions
 - **In production**, a violation increments an in-memory per-category counter, fires the Prometheus counter `svelte_realtime_assertion_violations_total{category}` (when `live.metrics(...)` is wired), and logs a single `[realtime/assert] {...}` line at `console.error`. The assert does NOT throw - a thrown exception inside a publish hot-path microtask or a subscribe callback could leave a half-applied bookkeeping update or a corrupted index. Counter + log give observability without the corruption risk.
 - **In test mode** (`process.env.VITEST` or `NODE_ENV === 'test'`) the assert THROWS so vitest surfaces the failure as a normal test error.
 
+There is also a **hard tier**, `fatal(cond, category, context)`, for genuinely unrecoverable server state where continuing risks silent misdelivery. It records the same per-category counter and Prometheus series as `assert` (the severity rides the log as `[realtime/fatal] {..., "severity":"fatal"}`), but in production it schedules a deferred worker termination with exit code 78 once the current callback frame unwinds, so the supervisor restarts the worker from clean state rather than letting it mis-route publishes; in test mode it throws. On the client it degrades to the log + counter only (there is no worker to terminate).
+
 Categories are stable strings prefixed `realtime/<module>.<invariant>` (so the Prometheus label cardinality is bounded and won't collide with the adapter's `extensions_assertion_violations_total`). Today's categories:
 
 | Category                                              | Where                                       |
 | ----------------------------------------------------- | ------------------------------------------- |
 | `realtime/handleRpc.envelope.non-empty`               | RPC frame has non-empty `rpc` and `id`      |
-| `realtime/subscription.bookkeeping.ws-was-tracked`    | Unsubscribe path: ws was in the topic set   |
+| `realtime/subscription.bookkeeping.ws-was-tracked`    | Subscribe rollback: forward/reverse subscription indexes agree (**hard tier**: terminates the worker) |
 | `realtime/push-registry.entry-tracked`                | Close hook: registry entry exists for userId |
 | `realtime/lock.waiter.shape`                          | Dequeued lock waiter has resolve+reject     |
 | `realtime/optimistic.queue.serverValue-iff-nonempty`  | Server-merge path: `_serverValue` set when queue non-empty |
@@ -2885,6 +2889,381 @@ import { board } from './live/collab.js';
 export const { message, close, unsubscribe } = board.hooks;
 ```
 
+### Lag compensation
+
+For real-time games, the moment a player acts and the moment the server evaluates that action are separated by network latency - by the time a shot arrives, the target has moved on the server. A room can opt into a bounded history of state snapshots and evaluate actions against the state *as it was when the player acted*: declare `history` with a `capture` function (your snapshot of your own authoritative state - the framework never guesses at state shape), and call `ctx.compensate()` inside an action with the client-stamped command time, passed as an ordinary action argument:
+
+```js
+export const game = live.room({
+  topic: (ctx, gameId) => 'game:' + gameId,
+  init: async (ctx, gameId) => loadWorld(gameId),
+  topicArgs: 1,
+  history: {
+    capture: (gameId) => snapshotPlayers(gameId)  // plain data, recorded after every action
+  },
+  actions: {
+    move: async (ctx, gameId, dir) => applyMove(gameId, ctx.user.id, dir),
+    shoot: async (ctx, gameId, targetId, firedAt) => {
+      const result = await ctx.compensate(firedAt, (state, meta) => {
+        const target = state.players[targetId];
+        const hit = target && hitscan(state.players[ctx.user.id].pos, target.pos);
+        return { hit, rewoundMs: meta.age };
+      });
+      if (result.hit) ctx.publish('hit', { by: ctx.user.id, target: targetId });
+      return result;
+    }
+  }
+});
+```
+
+```js
+// Client: stamp the moment the player fired with the local clock.
+game.shoot(gameId, targetId, Date.now());
+```
+
+How it behaves:
+
+- **Recording.** After every successful action, `capture` runs and the snapshot joins a per-room-topic ring (`maxEntries`, default 300; `maxAgeMs` rewind window, default 2000ms; topics LRU-capped via `maxTopics`, default 100). A failed action records nothing. Snapshots are frozen - return plain data from `capture`, not live references. Worst-case retention is `maxTopics * maxEntries` snapshots per room export (a quiet topic keeps its ring until it is touched again or LRU-evicted), so size your `capture` output with that envelope in mind.
+- **Capture is room-global by design.** It receives only the room-identifying arguments, never the acting user's `ctx`: a snapshot recorded during one player's action is served to *every* room member's later evaluations, so an API that cannot see the acting user cannot accidentally record one user's private view into state another user will read.
+- **Trust model.** The client stamps when it acted; the server only honors stamps inside the window it recorded itself. A stamp older than the history window, an empty ring, or a nested `compensate` call all fail safe to *current* state - never the oldest marker - and report `meta.fallback: true`. Production game servers run windows of 500-2000ms; longer windows widen the peek advantage a high-latency client gets, so tune `maxAgeMs` to your tolerance. The ring's topic cap is per room export: if your action guard lets a user act on arbitrarily many room ids, that user can cycle honest rooms' history out of the cap - the guard is the mitigation.
+- **Clock skew matters.** The stamp is compared against the *server's* wall clock. A client clock running ahead makes every stamp look fresh (no rewind, reported as `fallback: false`); one running behind by more than the window gets permanent `fallback: true`. Both degrade safely but silently - so derive the stamp from a server-synced clock instead of raw `Date.now()`. A [smoothed-entity view](#smoothed-entities) maintains exactly that clock: stamp with `view.now()` and the compensation window and the prediction loop share one time axis.
+- **Publishes during evaluation** are ordinary room publishes, delivered immediately - the same semantics as a publish anywhere else in an action (a publish followed by a throw is delivered there too). The recommended pattern is evaluate first, publish from the result, as in the example above.
+- **Cost.** Without `history`, actions are unchanged. With it, recording adds roughly the cost of your `capture` (a 32-player snapshot measures ~2-4us per action with `NODE_ENV=production node bench/compensate.mjs`; plain dev mode reads several times that because dev deep-freezes each snapshot to catch mutations), and a ring-hit rewind is a clock read plus a binary search - the cheapest compensate path, since it reuses an already-frozen snapshot.
+- **With client prediction.** If clients predict and reconcile, capture every field the reconciliation compares (position-only snapshots suffice for hitscan, not for replaying movement), and stamp commands with the same clock the prediction loop uses - `view.now()` on a [smoothed-entity view](#smoothed-entities).
+
+`tolerance` (per call: `ctx.compensate(t, fn, { tolerance: 20 })`) skips the rewind when the stamp is within that many milliseconds of now - the low-latency common case.
+
+---
+
+## 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, scoped actions, and the `history` / `ctx.compensate()` lag-compensation surface 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%)'
+```
+
+---
+
+## Smoothed entities
+
+`live.smooth()` is the responsiveness primitive for entities a user drives continuously - a dragged shape, an avatar, a game character. The local entity responds to input on the same frame it happens; remote entities animate smoothly between server updates; and the server remains the only authority on truth - a client can only ever send commands, never state.
+
+The whole contract is one pure function the app writes once, in a plain module both sides import:
+
+```js
+// src/live/board.shared.js - no framework imports, pure (state, command) -> state.
+export function apply(state, command) {
+  return { x: state.x + command.dx, y: state.y + command.dy };
+}
+```
+
+The server declares the topic with it:
+
+```js
+// src/live/board.js
+import { live } from 'svelte-realtime';
+import { apply } from './board.shared.js';
+
+export const shape = live.smooth({
+  topic: (ctx, boardId) => 'shape:' + boardId,
+  apply,
+  initial: { x: 0, y: 0 }
+});
+```
+
+And the component constructs the view with the same `apply` - the generated module can only carry paths and literals, so the shared function travels through the app's own import, which is exactly what makes client and server provably identical:
+
+```svelte
+<script>
+  import { shape } from '$live/board';
+  import { apply } from '$live/board.shared.js';
+
+  let { boardId } = $props();
+  const view = shape.smooth(boardId, { apply, initial: { x: 0, y: 0 } });
+  $effect(() => () => view.destroy());
+
+  function onpointermove(e) {
+    view.command({ dx: e.movementX, dy: e.movementY });
+  }
+</script>
+
+<Box x={view.local.x} y={view.local.y} />
+{#each [...view.remote] as [key, s] (key)}
+  <Box x={s.x} y={s.y} ghost />
+{/each}
+```
+
+How it behaves:
+
+- **The local entity is predicted.** `view.command(cmd)` applies your function immediately, so `view.local` moves this frame, and transmits the command (frame-batched, fire-and-forget - loss is recovered by reconciliation, never retransmission). The server applies the same commands through the same function on its authoritative tick and acknowledges each owner with the resulting state. When the acknowledged state disagrees with the prediction, the simulation adopts the server's answer immediately and the *rendered* position eases over a short window (`smoothTimeMs`, default 100) - unless the divergence is below `errorThreshold` (default 1), where easing would smear precision for nothing and the correction snaps silently.
+- **Remote entities render slightly in the past.** Their positions interpolate between server updates on a server-synced clock, so a dropped or late frame is invisible. `interpolationMs: 'auto'` (the default) tracks twice the measured update interval and collapses toward its floor when updates arrive at display rate. State fields beyond `x`/`y` are latest-value.
+- **Echo suppression is on by default** (`noEcho`): broadcasts of an owner's own commanded updates skip that owner - the acknowledgement already carries the authoritative copy, so the echo would be wasted bytes that fight the prediction. `onMissing` motion produces no acknowledgement and broadcasts to the owner too.
+- **One entity per identity per topic**, keyed like presence rosters (`identify`-style user keys, or per-connection guest keys). A second tab takes ownership by constructing a view (its sync re-binds the entity); it never races commands against the first. Ownership is last-sync-wins: a dispossessed view's commands are silently ignored until its un-acked window overflows, and the overflow recovery resync re-takes ownership - so exactly one view per identity should be commanding at a time.
+- **Side effects in `apply` must guard on `ctx.firstTime`** - reconciliation replays commands, and the flag is true only on a command's first application. Randomness inside `apply` must come from `ctx.rng` (reseeded per command id, identical on prediction, replay, and the server); `Math.random()` there is the documented mistake that turns every random command into a misprediction.
+- **Discrete one-shot events ride the channel, not state.** A muzzle flash, a hit, a pickup is a fire-once effect, not a position. Call `ctx.emitEvent(type, data, opts?)` inside `apply` and subscribe with `const off = view.onEvent((e) => { if (e.type === 'shot') flash(e.data); })`. The owner draws it the instant its command is read (`origin:'local'`, suppressed on every reconciliation replay by the same `ctx.firstTime` gate), and the authority broadcasts it author-excluded so other clients see it (`origin:'server'`) while the owner never double-draws its own. The optimistic and authoritative copies of one event share a `<commandId>:<ordinal>` key, so a handler that receives both can correlate them. Two escape hatches on `opts`: `{ toAuthor: true }` (the owner must also receive the authoritative copy - a hit it took) and `{ global: true }` (the author needs the broadcast too). `view.onEvent` returns an unsubscribe; events are not buffered, so subscribe before the first command.
+- **`onMissing(state, lastCommand)`** runs on the server for entities with no commands that tick - the hook for genuinely simulated entities that keep moving between inputs. Omitted, an idle entity simply holds position and costs nothing.
+- **Recovery is explicit.** If the server stops acknowledging long enough that the un-acked command window overflows (`windowCap` 256 commands or `windowMaxAgeMs` 3000ms), prediction is killed rather than allowed to run away: the entity renders the last authoritative state, `view.overflowed` reads true, the shared `health` store reads `'degraded'`, and the view resyncs; the next acknowledgement re-engages prediction.
+- **`view.now()`** is the estimated server wall-clock time, maintained from the server's frame stamps and the acknowledgement round trips. It is the right stamp for lag-compensated action arguments (see below).
+- **The wire is negotiated.** Binary frames engage per connection (`smooth.protocol:1`); everything degrades to JSON additively - old clients ignore the new events, and a server without the smooth plugin fails the first sync or command with an actionable version message, never a resolution crash.
+
+Knobs (all optional, on the server declaration: `tickMs` 50, `noEcho` true, `queueCap` 1024, `guard`, `onMissing`, `snapshot` false, `snapshotDebounceMs` 1000; on the client factory: `interpolationMs` 'auto', `extrapolateMs` 250, `snapGapMs` 500, `smoothTimeMs` 100, `errorThreshold` 1, `computeError`, `cmdRate` 60, `windowCap` 256, `windowMaxAgeMs` 3000). The tradeoff to know: larger `interpolationMs` survives more dropped frames but renders remote entities further in the past.
+
+Requires Svelte 5 (the view is a rune class) and svelte-adapter-uws 0.6.0-next.26 or newer (`view.onEvent` needs the adapter's client-side event delivery; the prediction/reconciliation surface alone needs only next.24).
+
+**Cluster-aware:** wire `platform.smooth = createSmoothCluster(redisClient)` from `svelte-adapter-uws-extensions/redis/smooth` and the smoothed-entity layer detects it and routes through it automatically. Because the authority's `apply` is order-dependent (unlike a document merge, it cannot run on every instance), the model is single-owner-per-topic: one instance holds a per-topic Redis lease and ticks that topic; the others forward their clients' commands to it and re-broadcast its updates, acknowledgements, and events to their own subscribers, so a load balancer can spread one topic's players across instances and cross-instance events still fire exactly once. On owner death the lease expires, another instance takes over with a fresh authority, and clients re-sync. Without it, `live.smooth()` runs single-instance (correct on one process, divergent across a load-balanced cluster - so wire the coordinator for any multi-instance deployment). **Warm handoff:** pass `snapshot: true` to recover gracefully from an owner crash - the owner persists a debounced state snapshot and the instance that takes over resumes each entity from its last state instead of resetting it to `initial` (snapping a player back to spawn). Off by default; tune the write cadence with `snapshotDebounceMs`. Needs `svelte-adapter-uws-extensions >= 0.6.0-next.20`.
+
+**Area of interest** (an uncapped lobby): a smoothed topic broadcasts every entity's motion to every subscriber, which is right for a small room and ruinous for a lobby of thousands where each client only sees its own neighbourhood. Opt into `interest` and the tick delivers each subscriber only the entities inside its area of interest:
+
+```js
+export const arena = live.smooth({
+  topic: (ctx, arenaId) => `arena:${arenaId}`,
+  apply,
+  initial: (key) => spawn(key),
+  interest: {
+    radius: 1200,                              // cull radius, in your position units
+    position: (s) => ({ x: s.x, y: s.y }),     // where an entity is; null = always-visible (a flag, an objective)
+    lod: [                                      // optional level-of-detail bands (the outer edge is the radius)
+      { within: 400, rate: 1 },                // near: every tick
+      { within: 800, rate: 3 },                // mid: every 3rd tick
+      { within: 1200, rate: 8 }                // fringe: every 8th tick
+    ]
+  }
+});
+```
+
+The area-of-interest centre is the subscriber's own entity by default, so a player-centric game needs no extra wiring. A spectator or free-cam whose view is not its own entity calls `view.reportCenter(x, y)` to point culling at where the camera looks (and `view.clearCenter()` to revert); the report rides a volatile send, an unchanged centre is dropped, and it takes effect even on a still board, so panning across a paused scene reveals what is there. `lod` bands let distant motion fade at a throttled, id-staggered cadence instead of consuming the same bandwidth as a nearby duel; a small hysteresis margin on the band edges stops an entity hovering on a ring from flickering, and an entity entering range (or crossing into a nearer band) is always delivered at once. Relevancy is a delivery preference, never authorization - the `guard` stays the separate auth layer - and the polarity is to over-deliver: a subscriber with no resolvable centre is delivered the whole board. **Off by default**, gated end to end on `interest != null`, so a topic without it is byte-identical to the broadcast-all path (the gate overhead benchmarks within noise, well under 1%). Culling re-sends an entity only when it actually moved since a subscriber last saw it, which relies on `apply` returning a NEW state object on a change rather than mutating in place - the same contract the broadcast itself already depends on (an in-place mutation makes the authority think nothing changed). At arena scale the cull delivers roughly 90% less per client, and the saving grows with the population. It works single-instance and across the cluster (a topic's owner culls its own local subscribers against the full cluster-wide catalog). _A subscriber on a non-owning cluster instance is over-delivered relayed updates - never under-delivered - until the cross-instance fine cull lands._
+
+---
+
+## Shared documents
+
+`live.doc()` / `live.map()` / `live.array()` are the merge primitives for state several people edit at once - a kanban board, a shared form, a todo list, collaborative text. A `live.stream` publish replaces; a document write **merges**: every client holds a local replica, every local edit applies immediately (no pending state, no rollback), and concurrent edits from any number of peers converge to the same value on every replica without a server round trip deciding a winner.
+
+The server declares a document like any other live export:
+
+```js
+// src/live/board.js
+import { live } from 'svelte-realtime';
+
+export const board = live.map({
+  topic: (ctx, boardId) => 'board:' + boardId,
+  guard({ user }) {
+    const role = roleFor(user);
+    return { read: role !== null, write: role === 'editor' || role === 'owner' };
+  },
+  persist: {
+    load: (topic) => db.loadSnapshot(topic),          // bytes or null for a new doc
+    store: (topic, bytes) => db.saveSnapshot(topic, bytes)
+  }
+});
+```
+
+And the component mutates the store directly - no transaction objects, no flush, no await:
+
+```svelte
+<script>
+  import { board } from '$live/board';
+
+  let { boardId, selected } = $props();
+  const cards = board.map(boardId);
+  $effect(() => () => cards.destroy());
+
+  function rename(id, title) {
+    cards.set(id, { ...cards.get(id), title });   // applies locally now, merges everywhere
+  }
+</script>
+
+<input value={cards.get(selected)?.title ?? ''} disabled={cards.readOnly}
+       oninput={(e) => rename(selected, e.target.value)} />
+
+{#each [...cards.entries()] as [id, card] (id)}
+  <Card {...card} />
+{/each}
+```
+
+The three declarations differ only in what the component-side factory returns. `live.map` gives the keyed container directly (`get` / `set` / `delete` / `entries` / `keys` / `size`); `live.array` gives the ordered container (`at` / `push` / `insert` / `delete` / `length` - positions are stable under concurrent insert/delete because every element carries its own identity); `live.doc` gives the root handle for documents that mix shapes:
+
+```js
+const doc = board.doc(boardId);
+const layers = doc.array('layers');   // ordered
+const meta   = doc.map('meta');       // keyed
+const title  = doc.text('title');     // collaborative text (concurrent character edits)
+doc.transact(() => { meta.set('a', 1); meta.set('b', 2); });  // one atomic wire update
+```
+
+All named containers share the topic's single update stream. Reads are rune-backed and granular - a write to one map key re-renders only readers of that key - and multiple components mounting the same document share one replica through a reference-counted cache, so `destroy()` is safe to call per component.
+
+How it behaves:
+
+- **Local-first by construction.** Reads never await the network (the page renders offline); a write returns synchronously and the template re-renders against the just-written value in the same tick. The update travels as opaque merge data, never as a request that could fail and need unwinding.
+- **Reconnect and offline are one mechanism.** On every connection open the store runs one idempotent exchange: it tells the server what it has (a compact state vector), receives exactly the missing changes, and uploads exactly what the server lacks. The local replica IS the offline queue - two minutes or two hours offline reconciles in one bounded round trip, and replaying overlapping data is free because the merge is idempotent. Any lost frame in between (backpressure, anything) is detected as a dependency gap and self-heals through the same exchange.
+- **The guard returns an access record.** `{read, write, comment}` per connection per document: a boolean widens to all three rights (`guard: () => user != null` never learns the record shape), a partial record defaults missing rights to false (`{read: true}` is a viewer). The record is cached at sync time and every inbound update is checked against it server-side; a role change applies at the next sync. Read-only mounts surface `readOnly` so the UI disables inputs up front - their mutators throw rather than silently fork the local view with edits the server will reject. The `comment` right is carried in full for the coming rich-text marks surface; granting it changes nothing yet. No guard means everyone connected can read and write (a one-time production warning says so).
+- **Persistence is two hooks on a framework schedule.** `load` runs once per cold document (simultaneous joiners coalesce onto one call); `store` receives the compacted full state - debounced 2s after the last edit, forced at least every 10s under sustained editing, compacted every 200 updates, and flushed once when the last subscriber leaves, so an edit-then-disconnect is never lost. Knobs: `debounceWait`, `debounceMaxWait`, `snapshotEvery`, `persistOnEmpty`, `onError`. Omit `persist` entirely for an in-memory document.
+- **Status is on the store**: `synced` (this connection completed its exchange), `degraded` (the exchange is failing and retrying - also folded into the shared `health` store), `access`, `readOnly`. Documents survive dev-server hot reloads with their unsaved edits intact.
+- **The wire is negotiated.** Document frames ride the binary wire per connection (`crdt.protocol:1`) and degrade transparently to JSON envelopes; updates ride a reliable no-reply send (never the volatile drop tier - a dropped edit would desync the document, a buffered one merely arrives late).
+
+Values are plain JSON values with replace-on-write semantics (`m.set(k, { ...m.get(k), title })`); nested collaborative structures are sibling named containers on the same document, not nested values. Presence (who is here, where their cursor is) stays a sibling concern - pair a document with `live.multiplayer()` / the cursor plugin; ephemeral state never belongs in the document.
+
+### Running across a cluster
+
+On a single process, documents are correct out of the box. Behind a load balancer, two people editing one document land on different instances - so clustered deployments must wire the CRDT coordinator from the extensions package, or the instances will not converge and each will overwrite the others' persisted snapshot:
+
+```js
+// hooks.server.js (or wherever you wire the Redis bus)
+import { createCrdtCluster } from 'svelte-adapter-uws-extensions/redis/crdt';
+
+platform.crdt = createCrdtCluster(redisClient);   // alongside platform.redis / platform.presence
+```
+
+That is the whole wiring. The document layer detects `platform.crdt` and routes through it automatically: every instance keeps its own replica and serves its own subscribers (no extra hop), every edit relays so all replicas converge, snapshots persist single-writer per topic (no clobber), and a cold-joining instance pulls the latest from a live peer. Without it the document family still works - it just runs single-instance, which is correct on one process and divergent across a cluster.
+
+Requires Svelte 5 (the stores are rune classes) and svelte-adapter-uws 0.6.0-next.25 or newer.
+
 ---
 
 ## Webhooks
@@ -2922,6 +3301,69 @@ export async function POST({ request, platform }) {
 }
 ```
 
+The flat `live.webhook(...)` above is an alias for `live.webhooks.inbound(...)`; both keep working.
+
+---
+
+## Outbound webhooks
+
+The mirror of inbound: `live.webhooks.outbound(sources, config)` fires an HTTP POST to an external endpoint whenever one of the `sources` topics publishes. Use it to forward your events to other systems - Slack, a partner's API, an internal pipeline.
+
+```js
+// src/live/integrations.js
+export const slackAlerts = live.webhooks.outbound(['alerts'], {
+  url: 'https://hooks.slack.example/services/T000/B000/xxxx',
+  secret: process.env.WEBHOOK_SECRET,         // optional HMAC-SHA256 signing
+  transform: (event, data) => ({ text: `[${event}] ${data.message}` })
+});
+```
+
+That's the whole wiring - no `+server.js`, no client code. It fires on every `platform.publish('alerts', ...)` (local or cluster-relayed). The body defaults to `{ event, data }`; return `null` from `transform` to skip an event.
+
+#### Cluster delivery: at-least-once, leader-gated
+
+In a single process every publish fires the webhook once. In a cluster every replica receives the published event, so to fire it **once** wire a leader (the same one cron uses):
+
+```js
+import { createLeader } from 'svelte-adapter-uws-extensions/redis/leader';
+configureCron({ leader: createLeader(redis).isLeader });
+```
+
+With a leader configured, only the leader replica POSTs; without one, every worker fires (correct for single-process, the same footgun cron has). Delivery is **at-least-once**, not exactly-once - strict exactly-once over HTTP is unachievable (a dropped *response* is indistinguishable from a dropped *request*, so the only safe action, retry, is also what can duplicate). Every POST therefore carries an `idempotency-key` header (stable across retries **and** across a leadership-transition double-fire), so **make your receiver idempotent** and it is effectively-once. When you set a `secret` the default key is **keyed** with it (an outsider who can trigger the same publish still cannot precompute the key to replay or suppress a delivery); without a secret it is a plain content hash (predictable - set a secret or supply your own `idempotencyKey: (event, data) => yourId`).
+
+#### SSRF protection
+
+Outbound delivery is a classic server-side request forgery (SSRF) surface, so the guard is **on by default and covers the whole request**, not just the configured URL:
+
+- **Private/loopback/metadata ranges are blocked** (strict by default) at definition time for a static `url` and at fire time for a dynamic `url: (event, data) => ...`.
+- **DNS rebinding is closed.** A DNS-name target is resolved, **every** resolved address is range-checked, and the connection is **pinned** to the validated address - a public-looking name that resolves to `169.254.169.254` or a private host is rejected, and it cannot rebind between the check and the connection. The `Host` header and TLS certificate validation still use the original hostname.
+- **Redirects are re-checked on every hop** (up to `maxRedirects`, default 5): a `3xx` to a private host, a non-http(s) scheme, or an https->http downgrade is refused, and redirect loops are detected. (A plain `fetch` would silently follow such a redirect - this does not.)
+- A blocked URL throws at definition or calls `onFailure` at fire time; it never reaches the network.
+
+To reach an internal endpoint on purpose, set `urlMode: 'allowlist'` + `allow: [...]` for a **public** host, or - for a **private** host - `urlMode: 'off'` (the explicit range opt-out; the http(s) scheme gate still applies) paired with a `validateUrl` that allows exactly that host. `validateUrl` is an **additional** restriction (logical AND): it can only narrow the allowed set, never re-open a blocked host, and it may be `async`. Supply a custom `resolve(hostname)` to use a hardened resolver.
+
+#### Delivery
+
+Delivery runs over `node:http`/`node:https` (no extra dependency). Each POST is retried with **jittered** exponential backoff (default 3 attempts, 100ms - 5s) on a 5xx / 429 / network error / timeout; a 4xx (other than 429) is a permanent client error and is not retried. When `secret` is set the body is signed as `x-webhook-signature: sha256=<hex>`. The per-attempt `timeoutMs` covers DNS, connect, TTFB and body; user callbacks are bounded by `callbackTimeoutMs`. Exhausted retries (and blocked URLs / bad payloads / blocked redirects) call `onFailure(err, event, data, attempts)` - the error never contains the `secret`, the signature, or URL credentials.
+
+#### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `url` | (required) | Destination URL, or `(event, data) => string \| Promise<string>` for a per-event URL. SSRF-checked. |
+| `transform` | `{ event, data }` | Build the POST body. Return `null` to skip the event. |
+| `secret` | - | HMAC-SHA256 signing secret; adds `x-webhook-signature` and keys the default idempotency key. |
+| `idempotencyKey` | keyed/content hash | Override the `idempotency-key` header value. |
+| `retry` | `{ attempts: 3, initialDelayMs: 100, maxDelayMs: 5000, backoffMultiplier: 2 }` | Retry policy (jittered). |
+| `timeoutMs` | `10000` | Per-attempt timeout (DNS + connect + TTFB + body). |
+| `callbackTimeoutMs` | `10000` | Timeout for each user callback (`transform` / `url` / `validateUrl` / `resolve` / `idempotencyKey`). |
+| `maxRedirects` | `5` | Redirect hops to follow; every hop is re-gated. `0` refuses all redirects. |
+| `urlMode` | `'strict'` | SSRF posture: `strict` (range-check + DNS pin), `allowlist` (+ host in `allow`), or `off` (no range check / no pin; scheme gate stays on). |
+| `allow` | - | Allowlisted hostnames for `urlMode: 'allowlist'`. |
+| `validateUrl` | - | Additional restriction `(url) => boolean \| Promise<boolean>`, ANDed with the built-in guard on every hop. Narrows only. |
+| `resolve` | `node:dns` | Custom DNS resolver `(hostname) => address \| address[] \| Promise<...>` for the pin. |
+| `onFailure` | - | Called on delivery failure after retries (or on a blocked URL / payload / redirect). |
+
 ---
 
 ## Signals
@@ -2982,12 +3424,12 @@ The Vite plugin includes the stream version in the client stub. On reconnect, th
 
 The migration codepath only fires across a real deploy boundary - a v1 server is replaced with a v2 server, a previously-connected v1 client reconnects, the cached `_schemaVersion` rides up. There's no path in a fresh tab to observe the migrate chain end-to-end, which makes demos and e2e tests awkward.
 
-`subscribeAt(stream, { schemaVersion })` from `svelte-realtime/test-client` creates a parallel store that subscribes pretending to be a stale client at the chosen version. The wire envelope carries `schemaVersion: N`, the server runs the registered migrate chain forward, and the parallel store renders the migrated payload. Use it for side-by-side demo panels and for e2e assertions on the migrate chain output.
+`subscribeAt(stream, { schemaVersion })` from `svelte-realtime/testing/client` creates a parallel store that subscribes pretending to be a stale client at the chosen version. The wire envelope carries `schemaVersion: N`, the server runs the registered migrate chain forward, and the parallel store renders the migrated payload. Use it for side-by-side demo panels and for e2e assertions on the migrate chain output.
 
 ```svelte
 <script>
   import { todos } from '$live/todos';
-  import { subscribeAt } from 'svelte-realtime/test-client';
+  import { subscribeAt } from 'svelte-realtime/testing/client';
 
   // Production store at the current server version (no migration on its responses).
   // Parallel stores pretending to be stale clients - each triggers the migrate
@@ -3007,7 +3449,7 @@ For dynamic streams, call the factory first and pass the cached store:
 
 ```js
 import { messages } from '$live/chat';
-import { subscribeAt } from 'svelte-realtime/test-client';
+import { subscribeAt } from 'svelte-realtime/testing/client';
 
 const v1Messages = subscribeAt(messages('room-1'), { schemaVersion: 1 });
 ```
@@ -3570,11 +4012,11 @@ realtime({ devtools: false })
 
 ## Testing
 
-Use `createTestEnv()` from `svelte-realtime/test` to test your live functions without a real WebSocket server.
+Use `createTestEnv()` from `svelte-realtime/testing` to test your live functions without a real WebSocket server.
 
 ```js
 import { describe, it, expect, afterEach } from 'vitest';
-import { createTestEnv } from 'svelte-realtime/test';
+import { createTestEnv } from 'svelte-realtime/testing';
 import * as chat from '../src/live/chat.js';
 
 describe('chat module', () => {
@@ -3637,7 +4079,7 @@ describe('chat module', () => {
 `createTestEnv({ chaos: { dropRate, seed } })` enables fault injection on `platform.publish` so tests can verify resilience to message drops without spinning a real cluster.
 
 ```js
-import { createTestEnv } from 'svelte-realtime/test';
+import { createTestEnv } from 'svelte-realtime/testing';
 
 // 50% drop rate, deterministic via seed
 const env = createTestEnv({
@@ -3672,7 +4114,7 @@ Currently models the `drop-outbound` scenario only - `platform.publish` events t
 `createTestContext({ user })` builds a `ctx`-shaped object suitable for direct unit tests of guards and predicates - helper methods are no-ops, the user / cursor / requestId can be overridden. Use this when the function under test takes `ctx` and synchronously returns a value; reach for `createTestEnv()` only when you need full publish/subscribe round-trips.
 
 ```js
-import { createTestContext } from 'svelte-realtime/test';
+import { createTestContext } from 'svelte-realtime/testing';
 
 const adminOnly = (ctx) => ctx.user?.role === 'admin';
 
@@ -3688,7 +4130,7 @@ The returned shape mirrors the production `_buildCtx`: `user`, `ws`, `platform`,
 `expectGuardRejects(promise, expectedCode?)` is a small ergonomic wrapper for the common "this call should be denied" pattern. It awaits the promise, asserts it rejected with a `LiveError` of the expected code (default `'FORBIDDEN'`), and returns the error so further assertions can run on it.
 
 ```js
-import { createTestEnv, expectGuardRejects } from 'svelte-realtime/test';
+import { createTestEnv, expectGuardRejects } from 'svelte-realtime/testing';
 
 const env = createTestEnv();
 env.register('admin', adminModule);
@@ -3727,6 +4169,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 |
@@ -3817,7 +4260,7 @@ The benchmark suite measures the full-stack overhead added by svelte-realtime on
 Run with:
 
 ```bash
-node bench/rpc.js
+node bench/rpc.mjs
 ```
 
 What gets measured:
@@ -3835,7 +4278,7 @@ With high-frequency streams (e.g. 1000 cursors at 20 updates/sec), this reduces
 
 In Node/SSR (tests, `__directCall`, etc.), events apply synchronously - no batching overhead.
 
-See [bench/rpc.js](bench/rpc.js) for the full source.
+See [bench/rpc.mjs](bench/rpc.mjs) for the full source.
 
 ---