@weft-js/multiplayer 0.0.0-stage → 0.1.1

package/LICENSE

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

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @weft-js/multiplayer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Early release (0.1.1).** APIs will change between minor versions.
+
+Presence, cursors anchored to elements, a typed interaction relay and synced scroll on `channel`. A library, not a plugin.
+
+```bash
+npm install @weft-js/multiplayer
+```

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@weft-js/multiplayer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "@weft-js/multiplayer: presence, cursors anchored to elements, a typed interaction relay and synced scroll on `channel`. A library, not a plugin",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server.ts",
+    "./ui": "./src/Cursors.tsx",
+    "./test": "./src/conformance.ts"
+  },
+  "peerDependencies": {
+    "@weft-js/start": "^0.1.1",
+    "@weft-js/core": "^0.1.1"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "keywords": [
+    "weft"
+  ],
+  "files": [
+    "src",
+    "plugin.mjs",
+    "plugin.d.mts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/Cursors.tsx

@@ -0,0 +1,25 @@
+// The other cursors, drawn over the page: `aria-hidden`, gliding 120 ms, and instant under reduced motion (warp 07 §6.3).
+import { hue, type Cursors as Tracker } from './index'
+
+const CSS = `[data-scope=cursors]{position:fixed;inset:0;pointer-events:none;overflow:hidden;z-index:2147483000}
+[data-scope=cursors] [data-part=cursor]{position:absolute;left:0;top:0;transition:transform 120ms linear,opacity 300ms}
+[data-scope=cursors] [data-part=name]{margin-left:10px;padding:1px 6px;border-radius:6px;font:12px/1.4 system-ui;color:#fff}
+@media (prefers-reduced-motion:reduce){[data-scope=cursors] [data-part=cursor]{transition:none}}`
+
+/** Draws everyone else's cursors from `cursors(room)`, each with its peer's name and colour. */
+export function Cursors<S>(props: { of: Tracker<S> }) {
+  return (
+    <div aria-hidden="true" data-scope="cursors">
+      <style>{CSS}</style>
+      {props.of.list.value.map(c => {
+        const color = `hsl(${hue(c.peer?.user.id ?? c.id)} 80% 45%)`
+        return (
+          <div key={c.id} data-part="cursor" data-peer={c.id} style={`transform:translate(${c.left}px,${c.top}px);opacity:${c.idle ? 0.25 : 1};color:${color}`}>
+            <svg width="16" height="18" viewBox="0 0 16 18"><path fill="currentColor" stroke="#fff" d="M1 1l5 15 2.5-6L15 8z" /></svg>
+            {c.peer?.user.name && <span data-part="name" style={`background:${color}`}>{c.peer.user.name}</span>}
+          </div>
+        )
+      })}
+    </div>
+  )
+}

package/src/conformance.ts

@@ -0,0 +1,68 @@
+// What a transport pack has to do, for `@weft/realtime-*` (research 35 §4). Plain data in, Checks out: it runs in Node
+// against a real relay, or in a page. `make` builds a transport for one named peer.
+
+import { state, type Derived } from '@weft-js/core'
+import type { PeerLink, PeerRoom, PeerTransport } from './index'
+
+/** One requirement of the suite, and how the transport did. */
+export interface Check { name: string; ok: boolean; detail: string }
+type Got = { from: string; text: string }
+
+const settle = async (done: () => boolean, ms = 8000) => {
+  for (const end = Date.now() + ms; !done() && Date.now() < end;) await new Promise(ok => { setTimeout(ok, 10) })
+  return done()
+}
+
+/** What `transportSuite` needs: a way to build the transport for a peer, and that peer's ticket if it takes one. */
+export interface TransportSuiteOptions {
+  make: (peer: string) => PeerTransport | Promise<PeerTransport>
+  /** A credential for `peer`, as `multiplayer({ ticket })` would hand it. It may be a promise. */
+  ticket?: (peer: string) => unknown
+}
+
+function fakeRoom(self: string, ids: Derived<string[]>, ticket: unknown, wires: Map<string, Set<(from: string, data: unknown) => void>>, got: Got[]): PeerRoom {
+  return {
+    self, ticket,
+    peers: { get value() { return ids.value.filter(p => p !== self) } },
+    signal: (to, data) => { for (const f of wires.get(to) ?? []) queueMicrotask(() => f(self, data)) },
+    onSignal(fn) {
+      const set = wires.get(self) ?? new Set()
+      wires.set(self, set)
+      set.add(fn)
+      return () => void set.delete(fn)
+    },
+    receive: (from, text) => void got.push({ from, text }),
+  }
+}
+
+/** One Check per requirement of a peer transport. */
+export async function transportSuite({ make, ticket }: TransportSuiteOptions): Promise<Check[]> {
+  const out: Check[] = []
+  const check = (name: string, ok: boolean, detail = '') => void out.push({ name, ok, detail })
+  const ids = state(['a', 'b'])
+  const wires = new Map<string, Set<(from: string, data: unknown) => void>>()
+  const gotA: Got[] = [], gotB: Got[] = []
+  let a: PeerLink | undefined, b: PeerLink | undefined
+  try {
+    a = (await make('a')).open(fakeRoom('a', ids, await ticket?.('a'), wires, gotA))
+    b = (await make('b')).open(fakeRoom('b', ids, await ticket?.('b'), wires, gotB))
+    check('both links come up', await settle(() => a!.up.value && b!.up.value, 20_000), `${a.up.value} ${b.up.value}`)
+    a.send('{"x":1}')
+    check('a frame reaches the other peer, named by the transport', await settle(() => gotB.length > 0) && gotB[0]!.from === 'a' && gotB[0]!.text === '{"x":1}', JSON.stringify(gotB[0]))
+    await new Promise(ok => { setTimeout(ok, 100) })
+    check('a frame does not come back to its sender', gotA.length === 0, `${gotA.length}`)
+    b.send('{"y":2}')
+    check('frames go both ways', await settle(() => gotA.length > 0) && gotA[0]!.from === 'b', JSON.stringify(gotA[0]))
+    const before = gotB.length
+    a.close()
+    a = undefined
+    await new Promise(ok => { setTimeout(ok, 100) })
+    check('a closed link sends nothing', gotB.length === before, `${gotB.length - before}`)
+  } catch (e) {
+    check('the transport ran', false, String((e as Error | null)?.stack ?? e))
+  } finally {
+    a?.close()
+    b?.close()
+  }
+  return out
+}

package/src/index.ts

@@ -0,0 +1,387 @@
+// Presence, cursors, a typed relay and synced scroll, on a `channel` connection (research 35). A library: nothing here
+// is a plugin, and an app that doesn't import it ships none of it. The server's half is `@weft-js/multiplayer/server`.
+//
+//   const chat = doc.connect(() => ({ id: props.id }))
+//   const room = presence(chat, { state: () => ({ typing: typing.value }) })
+//   room.peers.value                      // Peer[], without this connection
+//   const pointers = cursors(room)        // follows the pointer; <Cursors of={pointers} /> draws the others
+//   const clicks = relay<{ ping: { at: string } }>(chat); clicks.on('ping', e => flash(e.data.at, e.peer))
+
+import { derived, effect, onCleanup, onMount, state, untrack, type Derived, type State } from '@weft-js/core'
+import type { Connection } from '@weft-js/start'
+
+/** Who a peer is, from `user` on the server: never from the client. */
+export interface PeerUser { id: string; name?: string; [key: string]: unknown }
+/** Someone else in the room: their connection's id, who they are, the state they share and when they were last heard. */
+export interface Peer<S = unknown> { id: string; user: PeerUser; state: S; at: number }
+/** A pointer as fractions of `a`, an anchor's id, or of the viewport without one. */
+export interface CursorAt { a?: string; x: number; y: number; style?: string }
+
+// What `presence` needs of a connection: the `mp.*` names are the fragment's, which a `doc.connect()`'s types don't say.
+type Conn = Pick<Connection<unknown, unknown>, 'status' | 'room' | 'onReset'> & {
+  on(name: string, fn: (message: unknown) => void): () => void
+  send(name: string, message: unknown): Promise<void>
+}
+/** One of the fragment's messages, whose shape the server's half decides. */
+const hear = <M,>(conn: Pick<Conn, 'on'>, name: string, fn: (message: M) => void) => conn.on(name, fn as (message: unknown) => void)
+
+/** What a transport pack is handed to carry cursors around the server (`@weft-js/realtime-webrtc`, `-livekit`, `-socketio`). */
+export interface PeerRoom {
+  /** This connection, as the server named it. */
+  readonly self: string
+  /** From `ticket` in `multiplayer()`. */
+  readonly ticket: unknown
+  /** Who else is here, by connection. */
+  readonly peers: Derived<string[]>
+  /** A frame to one peer through the server, stamped with who sent it. For offers and candidates. */
+  signal(to: string, data: unknown): void
+  onSignal(fn: (from: string, data: unknown) => void): () => void
+  /** A frame arrived. `from` has to be one the transport proved, and the frame is checked again here. */
+  receive(from: string, text: string): void
+}
+
+/** An open transport, as `open` returns it. */
+export interface PeerLink {
+  /** True while a `send` reaches every peer. Until then frames go through the server, so nothing waits on it. */
+  readonly up: Derived<boolean>
+  send(text: string): void
+  close(): void
+}
+
+/** A way to carry cursors around the server: what `webrtc()`, `livekit()` and `socketio()` return. */
+export interface PeerTransport {
+  readonly name: string
+  open(room: PeerRoom): PeerLink
+}
+
+/** Options of `presence()`. */
+export interface PresenceOptions<S> {
+  /** This connection's own state. A function is followed. Say what's small: it goes to everyone on every change. */
+  state?: S | (() => S)
+  /** Ms between heartbeats. Default 15000, and peers expire after three missed. */
+  beat?: number
+  /** Carries cursors between peers, with the socket as the fallback. */
+  transport?: PeerTransport
+}
+
+/** What `presence()` returns: who else is in the room, kept current. */
+export interface Presence<S> {
+  /** Everyone else here, oldest first. */
+  readonly peers: Derived<Peer<S>[]>
+  /** This connection, once the server has said. */
+  readonly self: Derived<string | undefined>
+  /** Which way cursors are going: `socket`, or the transport's name. */
+  readonly via: Derived<string>
+  readonly connection: Conn
+  /** @internal */ readonly link: () => PeerLink | undefined
+  /** @internal */ readonly seen: (fn: (id: string, at: CursorAt | null) => void) => void
+}
+
+const STATE_GAP = 50
+
+/** Roster logic with no DOM and no timers of its own, so a test can drive it. */
+export const applyPeer = <S,>(list: Peer<S>[], p: Peer<S>): Peer<S>[] => (list.some(x => x.id === p.id) ? list.map(x => (x.id === p.id ? p : x)) : [...list, p])
+/** The list without peers unheard for `ttl`, or the same list when nobody expired. */
+export const expire = <S,>(list: Peer<S>[], now: number, ttl: number): Peer<S>[] => { const kept = list.filter(p => now - p.at <= ttl); return kept.length === list.length ? list : kept }
+
+const silent = (p: Promise<unknown>) => void p.catch(() => {}) // a volatile message: the next one replaces it
+
+/** Who else is on this connection. Announces this one, follows `state`, and expires peers that stop beating. */
+export function presence<S = undefined>(conn: Conn, options: PresenceOptions<S> = {}): Presence<S> {
+  const { beat = 15_000, transport } = options
+  const ttl = beat * 3
+  const list = state<Peer<S>[]>([])
+  const self = state<string | undefined>(undefined)
+  const ticket = state<unknown>(undefined)
+  const own = () => (typeof options.state === 'function' ? (options.state as () => S)() : options.state) ?? null
+  const hello = () => silent(conn.send('mp.hello', { state: untrack(own) }))
+  const ids = derived(() => list.value.map(p => p.id))
+  const heard = new Set<(id: string, at: CursorAt | null) => void>()
+  const signals = new Set<(from: string, data: unknown) => void>()
+  let link: PeerLink | undefined
+  const linked = state<PeerLink | undefined>(undefined)
+
+  hear(conn, 'mp.you', ({ id, ticket: t }: { id: string; ticket?: unknown }) => {
+    self.value = id
+    ticket.value = t
+  })
+  hear(conn, 'mp.peer', (p: Peer<S>) => {
+    if (p.id === untrack(() => self.value)) return
+    // Stamped by this clock: another machine's would expire it early or never.
+    list.value = applyPeer(untrack(() => list.value), { ...p, at: Date.now() })
+  })
+  hear(conn, 'mp.gone', ({ id }: { id: string }) => {
+    list.value = untrack(() => list.value).filter(p => p.id !== id)
+    for (const f of heard) f(id, null)
+  })
+  hear(conn, 'mp.ask', ({ id }: { id: string }) => silent(conn.send('mp.answer', { to: id, state: untrack(own) })))
+  hear(conn, 'mp.cursor', ({ id, at }: { id: string; at: CursorAt | null }) => { for (const f of heard) f(id, at) })
+  hear(conn, 'mp.signal', ({ from, data }: { from: string; data: unknown }) => { for (const f of signals) f(from, data) })
+  conn.onReset(() => {
+    list.value = []
+    hello()
+  })
+
+  // Open, or moved to another room: everything held is about the last one.
+  effect(() => (conn.status.value === 'open' ? conn.room.value : undefined), (room, was) => {
+    if (room === was) return
+    list.value = []
+    self.value = undefined
+    if (room) hello()
+  })
+
+  let first = true
+  effect(() => own(), () => {
+    if (first) return void (first = false)
+    if (untrack(() => conn.status.value) === 'open') schedule()
+  })
+  let queued: ReturnType<typeof setTimeout> | undefined
+  const schedule = () => {
+    queued ??= setTimeout(() => {
+      queued = undefined
+      silent(conn.send('mp.state', { state: untrack(own) }))
+    }, STATE_GAP)
+  }
+
+  if (typeof setInterval !== 'undefined' && !isServer()) {
+    const timer = setInterval(() => {
+      list.value = expire(untrack(() => list.value), Date.now(), ttl)
+      if (untrack(() => conn.status.value) === 'open') silent(conn.send('mp.state', { state: untrack(own) }))
+    }, beat)
+    onCleanup(() => {
+      clearInterval(timer)
+      clearTimeout(queued)
+    })
+  }
+
+  if (transport) {
+    effect(() => [self.value, ticket.value] as const, ([me, t]) => {
+      link?.close()
+      link = undefined
+      linked.value = undefined
+      if (!me) return
+      link = transport.open({
+        self: me,
+        ticket: t,
+        peers: ids,
+        signal: (to, data) => silent(conn.send('mp.signal', { to, data })),
+        onSignal: fn => { signals.add(fn); return () => void signals.delete(fn) },
+        receive(from, text) {
+          const at = readCursor(text)
+          if (at !== undefined && untrack(() => ids.value).includes(from)) for (const f of heard) f(from, at)
+        },
+      })
+      linked.value = link
+    })
+    onCleanup(() => link?.close())
+  }
+
+  return {
+    peers: list,
+    self,
+    via: derived(() => (linked.value?.up.value ? transport!.name : 'socket')),
+    connection: conn,
+    link: () => { const l = untrack(() => linked.value); return l && untrack(() => l.up.value) ? l : undefined },
+    seen: fn => { heard.add(fn); onCleanup(() => void heard.delete(fn)) },
+  }
+}
+
+const isServer = () => typeof document === 'undefined'
+
+/** A frame off a transport: no server looked at it, so it's read as hostile. Undefined is refused. */
+export function readCursor(text: string): CursorAt | null | undefined {
+  let parsed: unknown
+  try { parsed = JSON.parse(text) } catch { return undefined }
+  if (parsed === null) return null
+  if (typeof parsed !== 'object') return undefined
+  const v = parsed as Record<string, unknown>
+  const unit = (n: unknown): n is number => typeof n === 'number' && n >= -0.5 && n <= 1.5
+  if (!unit(v.x) || !unit(v.y)) return undefined
+  if (v.a !== undefined && (typeof v.a !== 'string' || v.a.length > 128)) return undefined
+  return { x: v.x, y: v.y, ...(typeof v.a === 'string' ? { a: v.a } : {}), ...(typeof v.style === 'string' && v.style.length <= 16 ? { style: v.style } : {}) }
+}
+
+// ---- cursors --------------------------------------------------------------------------------------------------------
+
+/** Options of `cursors()`. */
+export interface CursorOptions {
+  /** What a position is measured from. An element's id, in this attribute, on both sides. Default `data-anchor`. */
+  anchor?: string
+  /** Sends a second. Default 12, which keeps a socket under its default 20 a second with room for everything else. */
+  rate?: number
+  /** Ms before a still cursor fades. Default 5000. */
+  idle?: number
+  /** Where the pointer is followed. Default the document. */
+  root?: () => HTMLElement | Document
+  style?: string
+}
+
+/** One other cursor, placed on this screen. `peer` is missing until their presence arrives. */
+export interface LiveCursor<S = unknown> { id: string; peer?: Peer<S> | undefined; at: CursorAt; left: number; top: number; moved: number; idle: boolean }
+/** What `cursors()` returns, for `<Cursors of={…} />`. */
+export interface Cursors<S = unknown> { readonly list: Derived<LiveCursor<S>[]>; readonly anchor: string }
+
+/** Where a local pointer is, relative to the nearest anchor, or the viewport without one. Pure but for reading layout. */
+export function locate(target: Element | null, x: number, y: number, attr = 'data-anchor', view = { width: innerWidth, height: innerHeight }): CursorAt {
+  const el = target?.closest?.(`[${attr}]`) as HTMLElement | null | undefined
+  if (el) {
+    const r = el.getBoundingClientRect()
+    const w = Math.max(el.scrollWidth, r.width) || 1, h = Math.max(el.scrollHeight, r.height) || 1
+    return { a: el.getAttribute(attr)!, x: (x - r.left + el.scrollLeft) / w, y: (y - r.top + el.scrollTop) / h }
+  }
+  return { x: x / view.width, y: y / view.height }
+}
+
+/** The same spot on this screen. Null when the anchor isn't here: a cursor at (0,0) would be a lie. */
+export function resolve(at: CursorAt, attr = 'data-anchor', view = { width: innerWidth, height: innerHeight }): { left: number; top: number } | null {
+  if (!at.a) return { left: at.x * view.width, top: at.y * view.height }
+  const el = document.querySelector<HTMLElement>(`[${attr}="${CSS.escape(at.a)}"]`)
+  if (!el) return null
+  const r = el.getBoundingClientRect()
+  return { left: r.left + at.x * Math.max(el.scrollWidth, r.width) - el.scrollLeft, top: r.top + at.y * Math.max(el.scrollHeight, r.height) - el.scrollTop }
+}
+
+/** Sends this pointer, latest wins, and tracks everyone else's. Sending and the page's own events stop with the owner. */
+export function cursors<S>(room: Presence<S>, options: CursorOptions = {}): Cursors<S> {
+  const { anchor = 'data-anchor', rate = 12, idle = 5000, root, style } = options
+  const gap = 1000 / rate
+  const raw = state<Record<string, { at: CursorAt; moved: number }>>({})
+  const layout = state(0)
+  const clock = state(0)
+  const send = (at: CursorAt | null) => {
+    const link = room.link()
+    if (link) link.send(JSON.stringify(at))
+    else silent(room.connection.send('mp.cursor', at))
+  }
+  room.seen((id, at) => {
+    const { [id]: _, ...rest } = untrack(() => raw.value)
+    raw.value = at ? { ...rest, [id]: { at, moved: Date.now() } } : rest
+  })
+
+  onMount(() => {
+    if (isServer()) return
+    const host = root?.() ?? document
+    let last = 0, waiting: ReturnType<typeof setTimeout> | undefined, next: CursorAt | null | undefined
+    const flush = () => {
+      waiting = undefined
+      if (next === undefined) return
+      last = performance.now()
+      send(next)
+      next = undefined
+    }
+    const put = (at: CursorAt | null) => {
+      next = at
+      const wait = gap - (performance.now() - last)
+      if (wait <= 0) flush()
+      else waiting ??= setTimeout(flush, wait)
+    }
+    const move = (e: Event) => {
+      const p = e as PointerEvent
+      put({ ...locate(p.target as Element, p.clientX, p.clientY, anchor), ...(style ? { style } : {}) })
+    }
+    const out = () => put(null)
+    let frame = 0
+    const moved = () => { frame ||= requestAnimationFrame(() => { frame = 0; layout.value++ }) }
+    host.addEventListener('pointermove', move, { passive: true })
+    document.documentElement.addEventListener('pointerleave', out)
+    addEventListener('scroll', moved, { passive: true, capture: true })
+    addEventListener('resize', moved)
+    const tick = setInterval(() => { clock.value = Date.now() }, 1000)
+    onCleanup(() => {
+      host.removeEventListener('pointermove', move)
+      document.documentElement.removeEventListener('pointerleave', out)
+      removeEventListener('scroll', moved, { capture: true })
+      removeEventListener('resize', moved)
+      clearInterval(tick)
+      clearTimeout(waiting)
+      cancelAnimationFrame(frame)
+    })
+  })
+
+  const list = derived(() => {
+    void layout.value
+    const now = clock.value || Date.now()
+    const peers = room.peers.value
+    const out: LiveCursor<S>[] = []
+    for (const [id, { at, moved }] of Object.entries(raw.value)) {
+      const spot = resolve(at, anchor)
+      if (spot) out.push({ id, peer: peers.find(p => p.id === id), at, ...spot, moved, idle: now - moved > idle })
+    }
+    return out
+  })
+  return { list, anchor }
+}
+
+/** A peer's colour, the same for them everywhere. */
+export function hue(id: string): number {
+  let h = 0
+  for (let i = 0; i < id.length; i++) h = (h * 31 + id.charCodeAt(i)) | 0
+  return Math.abs(h) % 360
+}
+
+// ---- relay ----------------------------------------------------------------------------------------------------------
+
+/** Something a peer did, named and validated by the server, and which peer did it. */
+export interface RelayEvent<D> { peer: string; kind: string; data: D }
+
+/** Something a peer did, delivered to a callback. Never a synthetic DOM event: the page decides what it means. */
+export function relay<K extends Record<string, unknown>>(conn: Pick<Conn, 'on' | 'send'>) {
+  const handlers = new Map<string, Set<(e: RelayEvent<unknown>) => void>>()
+  hear(conn, 'mp.relay', ({ id, kind, data }: { id: string; kind: string; data: unknown }) => { for (const f of handlers.get(kind) ?? []) f({ peer: id, kind, data }) })
+  return {
+    emit: <N extends keyof K & string>(kind: N, data: K[N]) => conn.send('mp.relay', { kind, data }),
+    on<N extends keyof K & string>(kind: N, fn: (e: RelayEvent<K[N]>) => void) {
+      const set = handlers.get(kind) ?? new Set()
+      handlers.set(kind, set)
+      const handler = fn as (e: RelayEvent<unknown>) => void // the server checked `data` against this kind's schema
+      set.add(handler)
+      const stop = () => void set.delete(handler)
+      onCleanup(stop)
+      return stop
+    },
+  }
+}
+
+// ---- synced scroll and hash: the box, not the DOM ------------------------------------------------------
+
+/** One scroll position in a shared box, as a fraction, so different heights land on the same place. */
+export function syncedScroll(box: State<number>, element: () => HTMLElement | Window = () => window) {
+  onMount(() => {
+    if (isServer()) return
+    const el = element()
+    const page = el === window
+    const max = () => (page ? document.documentElement.scrollHeight - innerHeight : (el as HTMLElement).scrollHeight - (el as HTMLElement).clientHeight)
+    const now = () => (page ? scrollY : (el as HTMLElement).scrollTop)
+    let held = 0, frame = 0
+    const on = () => {
+      if (performance.now() < held) return
+      frame ||= requestAnimationFrame(() => {
+        frame = 0
+        const m = max()
+        if (m > 0) box.value = Math.round((now() / m) * 10_000) / 10_000
+      })
+    }
+    el.addEventListener('scroll', on, { passive: true })
+    onCleanup(() => {
+      el.removeEventListener('scroll', on)
+      cancelAnimationFrame(frame)
+    })
+    effect(() => box.value, f => {
+      const top = f * max()
+      if (Math.abs(top - now()) < 2) return
+      held = performance.now() + 150 // what this write causes isn't the user scrolling
+      el.scrollTo({ top })
+    })
+  })
+}
+
+/** The URL hash in a shared box. */
+export function syncedHash(box: State<string>) {
+  onMount(() => {
+    if (isServer()) return
+    const on = () => { box.value = location.hash }
+    addEventListener('hashchange', on)
+    onCleanup(() => removeEventListener('hashchange', on))
+    effect(() => box.value, h => { if (h && h !== location.hash) location.hash = h })
+  })
+}

package/src/server.ts

@@ -0,0 +1,161 @@
+// The server's half (research 35 §2): messages a `channel` spreads into its own definition, so the compiler still sees a
+// plain `channel({ … })` and `authorize` stays the app's.
+//
+//   const mp = multiplayer({ user: ({ ctx }) => ({ id: ctx.user!.id, name: ctx.user!.name }) })
+//   export const doc = channel({
+//     params, authorize,
+//     client: { ...mp.client, say }, server: { ...mp.server, said }, on: { ...mp.on, say: … }, left: mp.left,
+//   })
+//
+// Who a peer is comes from `user`, never from the client: a connection names only its own state and cursor, and every
+// frame is stamped here with the connection that sent it. There's no roster on the server: each client
+// answers an `ask`, peers expire without a beat, so any bus works and a dead instance's peers just age out.
+
+import { StartError } from '@weft-js/start/data'
+import type { Context, PublishOptions, StandardSchemaV1 } from '@weft-js/start'
+
+/** Who a peer is: what `user` returns. */
+export interface PeerUser { id: string; name?: string; [key: string]: unknown }
+/** A peer as the room hears of it, stamped here with who sent it. */
+export interface Peer<S = unknown> { id: string; user: PeerUser; state: S; at: number }
+/** A pointer as fractions of `a`, an anchor's id, or of the viewport without one. */
+export interface CursorAt { a?: string; x: number; y: number; style?: string }
+
+type Issue = { issues: { message: string }[] }
+/** Whatever a client sent: read as hostile, field by field. */
+type Wire = { [key: string]: unknown } | null | undefined
+const isIssue = (r: unknown): r is Issue => !!(r as Issue | null)?.issues
+const schema = <T,>(validate: (v: Wire) => T | Issue): StandardSchemaV1<T, T> => ({ '~standard': { version: 1, vendor: 'weft', validate: (v: unknown) => { const r = validate(v as Wire); return isIssue(r) ? r : { value: r } } } })
+const no = (message: string): Issue => ({ issues: [{ message }] })
+const within = (v: unknown, bytes: number) => { try { return (JSON.stringify(v) ?? '').length <= bytes } catch { return false } }
+const unit = (n: unknown): n is number => typeof n === 'number' && n >= -0.5 && n <= 1.5
+
+const STATE = 4096, RELAY = 2048, SIGNAL = 16_384
+
+const anything = schema(v => v)
+
+const stateful = (max: number) => schema(v => (v && typeof v === 'object' && within(v.state, max) ? { state: v.state } : no(`\`state\` is JSON up to ${max} bytes`)))
+
+/** What a client may send as a cursor: fractions just past the edges, or null when it leaves. */
+export const cursorSchema = schema<CursorAt | null>(v => {
+  if (v === null) return null
+  if (!v || !unit(v.x) || !unit(v.y)) return no('a cursor is `{ x, y }` in fractions')
+  if (v.a !== undefined && (typeof v.a !== 'string' || v.a.length > 128)) return no('an anchor is up to 128 characters')
+  if (v.style !== undefined && (typeof v.style !== 'string' || v.style.length > 16)) return no('a style is up to 16 characters')
+  return { x: v.x, y: v.y, ...(v.a === undefined ? {} : { a: v.a }), ...(v.style === undefined ? {} : { style: v.style }) }
+})
+
+const answerSchema = schema(v => (v && typeof v.to === 'string' && within(v.state, STATE) ? { to: v.to, state: v.state } : no('an answer names who asked')))
+const signalSchema = schema(v => (v && typeof v.to === 'string' && within(v.data, SIGNAL) ? { to: v.to, data: v.data } : no(`a signal names a peer, with up to ${SIGNAL} bytes`)))
+
+/** What `ticket` gets: the connection, who it is and the room's params. */
+export interface TicketArgs<P> { id: string; user: PeerUser; params: P; ctx: Context }
+
+/** Options of `multiplayer()`. */
+export interface MultiplayerOptions<P> {
+  /** Who this connection is. Required: a peer can't name itself. */
+  user: (args: { ctx: Context; params: P; id: string }) => PeerUser | Promise<PeerUser>
+  /** The relay's event kinds and what each may carry. Nothing else is relayed. */
+  relay?: Record<string, StandardSchemaV1>
+  /** A transport's credential, handed to the client with its id. `livekitTicket`, `socketioTicket`. */
+  ticket?: (args: TicketArgs<P>) => unknown
+  /** Bytes one peer's `state` may be. Default 4096. */
+  state?: number
+}
+
+/** A channel's room as far as the fragment uses it: the app's own messages are none of its business. */
+interface MpRoom { publish(name: string, message: unknown, options?: PublishOptions): Promise<void> }
+
+/** `client`, `server`, `on` and `left` to spread into a `channel`. Every message is `mp.*`, and all but `mp.relay` are volatile. */
+export function multiplayer<P = unknown>(options: MultiplayerOptions<P>) {
+  const { user, relay = {}, ticket, state = STATE } = options
+  type Arrived<M> = { msg: M; id: string; ctx: Context; params: P; room: MpRoom }
+  const people = new Map<string, PeerUser>()
+  const who = async (args: { ctx: Context; params: P; id: string }) => {
+    const known = people.get(args.id)
+    if (known) return known
+    const made = await user(args)
+    if (!made || typeof made.id !== 'string') throw new Error('`user` must return an object with an `id`')
+    people.set(args.id, made)
+    return made
+  }
+  const peer = async (a: { id: string; ctx: Context; params: P }, value: unknown) => ({ id: a.id, user: await who(a), state: value, at: Date.now() })
+  const volatile = { volatile: true }
+  const relaySchema = schema(v => {
+    if (!v || typeof v.kind !== 'string' || !Object.hasOwn(relay, v.kind) || !within(v.data, RELAY)) return no('that relay kind is not declared')
+    return { kind: v.kind, data: v.data }
+  })
+  return {
+    client: {
+      'mp.hello': stateful(state),
+      'mp.state': stateful(state),
+      'mp.answer': answerSchema,
+      'mp.cursor': cursorSchema,
+      'mp.relay': relaySchema,
+      'mp.signal': signalSchema,
+    },
+    server: {
+      'mp.you': anything,
+      'mp.peer': anything,
+      'mp.gone': anything,
+      'mp.ask': anything,
+      'mp.cursor': anything,
+      'mp.relay': anything,
+      'mp.signal': anything,
+    },
+    on: {
+      /** A connection arrives, or comes back: it learns its id and everyone hears it. */
+      'mp.hello': async ({ msg, id, ctx, params, room }: Arrived<{ state: unknown }>) => {
+        const me = await peer({ id, ctx, params }, msg.state)
+        await room.publish('mp.you', { id, ticket: await ticket?.({ id, user: me.user, params, ctx }) }, { to: id, volatile: true })
+        await room.publish('mp.peer', me, { ...volatile, exceptSelf: true })
+        await room.publish('mp.ask', { id }, { ...volatile, exceptSelf: true })
+      },
+      'mp.state': async ({ msg, id, ctx, params, room }: Arrived<{ state: unknown }>) => room.publish('mp.peer', await peer({ id, ctx, params }, msg.state), { ...volatile, exceptSelf: true }),
+      'mp.answer': async ({ msg, id, ctx, params, room }: Arrived<{ to: string; state: unknown }>) => room.publish('mp.peer', await peer({ id, ctx, params }, msg.state), { ...volatile, to: msg.to }),
+      'mp.cursor': ({ msg, id, room }: Pick<Arrived<CursorAt | null>, 'msg' | 'id' | 'room'>) => room.publish('mp.cursor', { id, at: msg }, { ...volatile, exceptSelf: true }),
+      'mp.relay': async ({ msg, id, room }: Pick<Arrived<{ kind: string; data: unknown }>, 'msg' | 'id' | 'room'>) => {
+        const r = await relay[msg.kind]!['~standard'].validate(msg.data) // `relaySchema` refused any kind that isn't declared
+        if (r.issues) throw new StartError('Q002', `\`${msg.kind}\` refused its data`)
+        await room.publish('mp.relay', { id, kind: msg.kind, data: r.value }, { exceptSelf: true })
+      },
+      'mp.signal': ({ msg, id, room }: Pick<Arrived<{ to: string; data: unknown }>, 'msg' | 'id' | 'room'>) => room.publish('mp.signal', { from: id, data: msg.data }, { ...volatile, to: msg.to }),
+    },
+    left: async ({ id, room }: Pick<Arrived<unknown>, 'id' | 'room'>) => {
+      people.delete(id)
+      await room.publish('mp.gone', { id }, volatile)
+    },
+  }
+}
+
+// ---- tickets --------------------------------------------------------------------------------------------------------
+
+const b64 = (bytes: Uint8Array) => btoa(String.fromCharCode(...bytes)).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '')
+const hmac = (secret: string) => crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify'])
+
+/** An HS256 JWT, which is what LiveKit reads and what a relay can check with one shared secret. */
+export async function signTicket(claims: Record<string, unknown>, secret: string): Promise<string> {
+  const text = (v: unknown) => b64(new TextEncoder().encode(JSON.stringify(v)))
+  const body = `${text({ alg: 'HS256', typ: 'JWT' })}.${text(claims)}`
+  return `${body}.${b64(new Uint8Array(await crypto.subtle.sign('HMAC', await hmac(secret), new TextEncoder().encode(body))))}`
+}
+
+/** The claims, or null: a bad signature, another algorithm, or past `exp`. */
+export async function verifyTicket(ticket: unknown, secret: string): Promise<Record<string, unknown> | null> {
+  const [head = '', body = '', sig] = String(ticket).split('.')
+  if (!sig) return null
+  const bytes = (s: string) => Uint8Array.from(atob(s.replaceAll('-', '+').replaceAll('_', '/')), c => c.charCodeAt(0))
+  try {
+    if (JSON.parse(new TextDecoder().decode(bytes(head))).alg !== 'HS256') return null
+    if (!(await crypto.subtle.verify('HMAC', await hmac(secret), bytes(sig), new TextEncoder().encode(`${head}.${body}`)))) return null
+    const claims = JSON.parse(new TextDecoder().decode(bytes(body))) as Record<string, unknown>
+    return typeof claims.exp === 'number' && claims.exp * 1000 > Date.now() ? claims : null
+  } catch {
+    return null
+  }
+}
+
+/** A name for a room a third party can hold: stable, and it says nothing of the params. */
+export async function roomId(params: unknown): Promise<string> {
+  return b64(new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify(params ?? null))))).slice(0, 32)
+}