wenay-common2 1.0.68 → 1.0.70

package/README.md

@@ -1,9 +1,20 @@
 # wenay-common2
 
+[![CI](https://github.com/wenayr/wenay-common2/actions/workflows/ci.yml/badge.svg)](https://github.com/wenayr/wenay-common2/actions/workflows/ci.yml)
+
 ## Documentation
 
 - Brief API cheat sheet: [`doc/wenay-common2.md`](doc/wenay-common2.md)
 - Extended API cheat sheet: [`doc/wenay-common2-rare.md`](doc/wenay-common2-rare.md)
 - Naming migrations: [`doc/NAMING_RENAMES.md`](doc/NAMING_RENAMES.md)
 - Recent changes: [`doc/changes/`](doc/changes/)
-- Project rules for AI/code maintenance: [`CLAUDE.md`](CLAUDE.md)
+- Project rules for AI/code maintenance: [`CLAUDE.md`](CLAUDE.md)
+
+## Living examples (shipped in the npm package)
+
+- [`demo/`](demo/) — runnable stand (`npm run demo`): shared cursors in two browser tabs over the
+  Peer SDK, relay ⇄ WebRTC direct hand-off next to a legacy rpc key.
+- [`replay/`](replay/) · [`observe/`](observe/) · [`oracle/`](oracle/) — the oracle suites CI runs on
+  every push; each file doubles as a worked usage example of one subsystem.
+- Note: examples import from the repo's `src/`; in the installed package the same API comes from
+  `wenay-common2` / `wenay-common2/peer` / `wenay-common2/replay` / `wenay-common2/observe`.

package/demo/client.ts

@@ -0,0 +1,100 @@
+// Demo stand client: shared cursors over the Peer SDK — relay by default,
+// "Go direct" promotes to a real RTCPeerConnection datachannel, "Back to relay"
+// re-interposes. The route hand-off is gap-free by seq; the cursor never jumps.
+import {io} from 'socket.io-client'
+import {createRpcClientHub} from '../src/Common/rcp/rpc-clientHub'
+import {createPeerClient} from '../src/Common/peer/peer-index'
+
+type World = {cursor: {x: number, y: number}, color: string, name: string}
+
+const params = new URLSearchParams(location.search)
+const me = params.get('me') ?? 'a'
+const other = params.get('peer') ?? (me == 'a' ? 'b' : 'a')
+
+const el = (id: string) => document.getElementById(id)!
+const logBox = () => el('log') as HTMLDivElement
+
+function log(line: string) {
+    const box = logBox()
+    const row = document.createElement('div')
+    row.textContent = `${new Date().toLocaleTimeString()}  ${line}`
+    box.prepend(row)
+    while (box.children.length > 30) box.lastChild?.remove()
+}
+
+async function main() {
+    document.title = `peer ${me}`
+    el('who').textContent = `me: ${me}  ·  watching: ${other}`
+
+    const hub = createRpcClientHub(
+        () => io({transports: ['websocket'], auth: {account: me}}),
+        r => ({app: r<any>('app')}) as const,
+    )
+    const clients = await hub.setToken(null)
+    await clients.app.readyStrict()
+    log('rpc connected; legacy serverTime() = ' + await clients.app.func.serverTime())
+
+    // debug tap: every signaling envelope this account receives
+    ;(clients.app.func.peer.signal.signals as any).on((env: any) => {
+        log(`sig<- ${env.type} ${env.from}->${env.to}` +
+            (env.sdp ? ` sdp.len=${String(env.sdp).length}` : '') +
+            (env.candidate ? ` cand=${JSON.stringify(env.candidate).slice(0, 70)}` : ''))
+    })
+
+    const client = createPeerClient<World>({
+        remote: clients.app.func.peer,
+        account: me,
+        initial: {
+            cursor: {x: 160, y: 120},
+            color: me == 'a' ? '#4f8ef7' : '#f7a44f',
+            name: me,
+        },
+        rtc: () => new RTCPeerConnection(),
+        drain: 'micro',
+    })
+    const peer = client.peer(other)
+    client.onRoute(ev => log(`route ${ev.key}: ${ev.from} -> ${ev.to}${ev.reason ? ` (${String(ev.reason)})` : ''}`))
+    peer.ready.then(() => log('peer mirror ready (keyframe landed)')).catch(e => log('mirror error: ' + e))
+
+    // ============== input: own cursor -> own store ==============
+    const canvas = el('canvas') as HTMLCanvasElement
+    canvas.addEventListener('mousemove', function onMove(e) {
+        const r = canvas.getBoundingClientRect()
+        client.store.state.cursor = {x: Math.round(e.clientX - r.left), y: Math.round(e.clientY - r.top)}
+    })
+
+    // ============== render loop: own + mirrored cursor ==============
+    const ctx = canvas.getContext('2d')!
+    function drawCursor(c: {x: number, y: number}, color: string, name: string) {
+        ctx.beginPath()
+        ctx.arc(c.x, c.y, 8, 0, Math.PI * 2)
+        ctx.fillStyle = color
+        ctx.fill()
+        ctx.fillStyle = '#333'
+        ctx.font = '12px sans-serif'
+        ctx.fillText(name, c.x + 12, c.y + 4)
+    }
+    function frame() {
+        ctx.clearRect(0, 0, canvas.width, canvas.height)
+        const mine = client.store.state
+        drawCursor(mine.cursor, mine.color, mine.name + ' (me)')
+        const theirs = peer.store.state
+        if (theirs?.cursor) drawCursor(theirs.cursor, theirs.color ?? '#999', (theirs.name ?? other) + ` [${peer.route()}]`)
+        el('route').textContent = `route: ${peer.route()}  ·  state: ${peer.state()}  ·  seq: ${peer.seq()}`
+        requestAnimationFrame(frame)
+    }
+    frame()
+
+    // ============== route controls ==============
+    el('direct').addEventListener('click', async function goDirect() {
+        log('promoteDirect...')
+        const res = await peer.promoteDirect({timeoutMs: 8000})
+        log(res.ok ? `direct: ok (${res.state})` : `direct failed: ${String(res.reason)}`)
+    })
+    el('relay').addEventListener('click', async function backToRelay() {
+        const res = await peer.reinterposeRelay('manual')
+        log(res.ok ? 'back on relay' : `re-interpose failed: ${String(res.reason)}`)
+    })
+}
+
+main().catch(e => { console.error(e); log('FATAL: ' + e) })

package/demo/index.html

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>wenay-common2 peer stand</title>
+<style>
+    body { font-family: sans-serif; margin: 16px; color: #222; }
+    #canvas { border: 1px solid #bbb; border-radius: 6px; background: #fafafa; display: block; }
+    #bar { display: flex; gap: 12px; align-items: center; margin: 8px 0; flex-wrap: wrap; }
+    #route { font-family: monospace; }
+    button { padding: 6px 14px; border-radius: 6px; border: 1px solid #888; background: #fff; cursor: pointer; }
+    button:hover { background: #f0f0f0; }
+    #log { font-family: monospace; font-size: 12px; margin-top: 8px; max-height: 180px; overflow-y: auto; color: #555; }
+</style>
+</head>
+<body>
+<h3>wenay-common2 — shared cursors (relay ⇄ WebRTC direct)</h3>
+<div id="bar">
+    <span id="who">connecting…</span>
+    <button id="direct">Go direct</button>
+    <button id="relay">Back to relay</button>
+    <span id="route"></span>
+</div>
+<canvas id="canvas" width="640" height="360"></canvas>
+<div id="log"></div>
+<script src="client.js"></script>
+</body>
+</html>

package/demo/server.ts

@@ -0,0 +1,43 @@
+// Demo stand server: the Peer SDK next to a legacy rpc key, static page hosting.
+// Run: npm run demo  ->  open the two printed URLs in two tabs.
+import express from 'express'
+import {createServer} from 'http'
+import path from 'path'
+import {Server as SocketIOServer} from 'socket.io'
+import {listen} from '../src/Common/events/Listen'
+import {createPeerHost} from '../src/Common/peer/peer-index'
+import {createRpcServerAuto} from '../src/Common/rcp/rpc-server-auto'
+
+const PORT = Number(process.env.PORT ?? 8390)
+
+const host = createPeerHost()
+const app = express()
+app.use(express.static(path.resolve(__dirname, 'public')))
+app.get('/', (_req, res) => res.sendFile(path.resolve(__dirname, 'public', 'index.html')))
+
+const httpServer = createServer(app)
+const ioServer = new SocketIOServer(httpServer)
+
+ioServer.on('connection', function onDemoConnection(socket) {
+    const account = String(socket.handshake.auth?.account ?? 'anon')
+    const peer = host.connection(account)
+    const [disconnect, disconnectListen] = listen<[]>()
+    socket.on('disconnect', () => { disconnect(); peer.close() })
+    createRpcServerAuto({
+        socket: {emit: (key, data) => socket.emit(key, data), on: (key, cb) => socket.on(key, cb)},
+        socketKey: 'app',
+        object: {
+            // legacy key on the SAME connection — the SDK does not displace old code
+            serverTime: () => new Date().toISOString(),
+            peer: peer.fragment,
+        },
+        disconnectListen,
+    })
+    console.log(`[demo] ${account} connected`)
+})
+
+httpServer.listen(PORT, function onDemoListen() {
+    console.log('[demo] shared-cursor stand is up:')
+    console.log(`  tab A: http://localhost:${PORT}/?me=a&peer=b`)
+    console.log(`  tab B: http://localhost:${PORT}/?me=b&peer=a`)
+})

package/doc/ROADMAP.md

@@ -5,7 +5,10 @@
 > `createStoreMirror`, and the replay `seq` / `keyframe` / `frame` contract. None of it requires
 > changing the store core; the store stays single-authority (one `seq` sequencer, last-writer-wins
 > per path), and these features are layers or adapters above that.
-> Status: 🔴 not started · 🟡 partial / ongoing · 🧊 deliberately shelved.
+> Status: 🔴 not started · 🟡 partial / ongoing · 🧊 deferred (super-low priority, not forbidden).
+>
+> Current focus is NOT more transport: see `doc/target/library-uplift-tasks.md` (showcase, SDK facade,
+> vertical demo app). Transport items below stay available but rank below everything in that plan.
 
 ## 0. Distributed Runtime Model
 
@@ -195,7 +198,9 @@ source of truth. Decompose by write topology:
   silently drop a concurrent write. This is the one case that genuinely needs CRDT/OT. Design lead:
   wrap a Yjs/Automerge doc as a `RemoteStore`-shaped source and mirror from it — the store↔transport
   decoupling makes this a small adapter, not a rewrite.
-- Status: 🔴 prediction layer + CRDT adapter not started; partitioned-authority already expressible.
+- Status: 🧊 deferred, super-low priority. Prediction layer waits for the demo app to demand and shape
+  it (`doc/target/library-uplift-tasks.md` task 4); CRDT adapter reopens only on a real co-write need.
+  Partitioned-authority already expressible today.
 
 ## 4. Data-transfer optimization backlog (ongoing) 🟡
 
@@ -203,4 +208,5 @@ Open-ended transfer/perf work, especially for backend-heavy models. Never "done"
 
 - Candidates: tighter `frame` condensation per line; delta/patch minimization; binary framing for hot
   paths; batching heuristics beyond the current `pipe` / `space` modes.
-- Status: 🟡 ongoing; pick items as real bottlenecks surface, not speculatively.
+- Status: 🧊 deferred, super-low priority; pick items only as real bottlenecks surface in the SDK/demo
+  consumers, not speculatively.

package/doc/changes/1.0.69.md

@@ -0,0 +1,11 @@
+# 1.0.69
+
+- Fix `createWebRtcConnector` / `acceptWebRtcDirect`: `RTCIceCandidate` now rides the signaling wire as its `toJSON()` init — real browser candidate class instances were mangled by transport serialization, so direct never established (caught by the live demo stand, invisible to fakes).
+- Add the demo stand `demo/` (`npm run demo`): shared cursors in two browser tabs over the Peer SDK next to a legacy rpc key — relay mirroring, "Go direct" (real `RTCPeerConnection`), "Back to relay" re-interposition, signaling/route event log. Verified live in Chrome: seq continues across both hand-offs, no keyframe reset, cursor never jumps.
+
+- Add the `Peer` namespace (`wenay-common2/peer`) — the one-call SDK over rpc + store + replay + route coordinator, legacy-friendly by design: the server side is an object fragment spread into an EXISTING `createRpcServerAuto` object (old keys untouched), the client side rides the existing connection's deep proxy.
+- `Peer.createPeerHost({authorize?, history?})`: per-account signaling ports + relay journals + a `noStrict` dynamic `peers` feed; `authorize` is the server-side `canExposeEndpoint`; `revoke(pair, accounts)` pushes both parties back to relay.
+- `Peer.createPeerClient({remote, account, initial, rtc?, ...})`: own store published as a patch line; `peer(account)` returns a live mirrored store + route control (`promoteDirect/reinterposeRelay/fallback/block`, `route()`, `ready`, `seq()`); mirrors survive any route change; omitting `rtc` gives a relay-only client.
+- `Peer.createPatchRelayJournal({history?})`: server-side journal of OWNER-sequenced envelopes — relay and direct share the owner's seq space, so a relay <-> direct hand-off is a plain seq resume (no keyframe reset); keyframe is folded server-side, late joiners work while the owner is offline.
+- Add GitHub Actions CI (build + publish gate + full oracle suite on windows-latest) and a README badge.
+- Add oracle `replay/peer-sdk.test.ts`: two accounts over a real Socket.IO/RPC wire next to a legacy rpc key — relay mirroring, direct promotion via injected fake WebRTC runtime, same-seq-space hand-off assertion, server revoke fallback, late joiner from the folded keyframe, loud refusal of `promoteDirect` without an `rtc` factory.

package/doc/changes/1.0.70.md

@@ -0,0 +1,4 @@
+# 1.0.70
+
+- Ship the living examples in the npm package: the oracle suites (`replay/`, `observe/`, `oracle/`) and the demo stand (`demo/`, without the generated bundle) — each oracle doubles as a worked usage example of one subsystem, kept honest by CI on every push.
+- README: a "Living examples" section with the src-vs-package import note (examples import the repo's `src/`; installed packages use `wenay-common2` / `wenay-common2/peer` / `wenay-common2/replay` / `wenay-common2/observe`).

package/doc/wenay-common2-rare.md

@@ -529,6 +529,14 @@ acceptWebRtcDirect({port, rtc, self, serve, accept?}) -> close()
   // responder side: on offer, negotiates answer/ICE and serves serve(env) (exposeReplay(...) as is) into
   //   the incoming datachannel; accept(env) validates session material and rejects with a loud revoke
   //   (the initiator fails fast, not by timeout). Repeated offer for a pair recreates the session.
+Peer.createPatchRelayJournal({history?}) -> {push(env), remote, seq(), snapshot(), close()}
+  // server-side mirror of an OWNER-sequenced patch line: push() takes the owner's envelopes VERBATIM
+  //   (dedup by seq; a root patch with a LOWER seq = owner restart, legitimate reset point), keyframe is
+  //   folded server-side (late joiners don't need the owner online), frame condenses last-patch-per-path.
+  //   Owner seq space is the point: relay and direct routes share coordinates -> hand-off is a seq resume.
+  //   remote is ReplayRemote-shaped and rpc-exposable as is (line is a REAL Listen — the rpc layer detects
+  //   listen nodes by registry, a hand-rolled {on: cb => ...} wrapper would not stream).
+  // The full SDK on top (createPeerHost/createPeerClient) is most-used surface -> wenay-common2.md.
 serveReplayChannel(source, channel) <-> channelReplayRemote(channel) -> ReplayRemote
   // replay wire over ANY ordered string channel (datachannel/MessagePort/worker/pipe): tiny JSON
   //   sub/req/res protocol, no RPC core — a direct channel lives OUTSIDE the main rpc connection.

package/doc/wenay-common2.md

@@ -136,8 +136,8 @@ l.ticks.once(v => console.log(v))                         // one event, then aut
 const [tick, ticks] = replayListen<[number]>({history: 1024, current: 'last'})    // after — same facade, same key
 // legacy subscribers unchanged (byte-for-byte). Replay consumers now also get:
 const sub = replaySubscribe(l.ticks, v => {}, {since: saved, onSeq: s => saved = s})  // catch-up + live, no gaps/dups
-const sub2 = replaySubscribe(c.math.func.ticks, v => {})  // replay members project on func/strict directly — no cast needed
-const routed = replayRouteSubscribe(l.ticks, v => {}, {label: 'relay'})
+const sub2 = replaySubscribe(c.math.func.ticks, v => {})  // replay members project on func/strict directly — no cast needed
+const routed = replayRouteSubscribe(l.ticks, v => {}, {label: 'relay'})
 await routed.switch(nextRemoteTicks, {label: 'direct'})  // relay/direct hand-off: old route closes after catch-up
 await l.ticks.frame(mySeq)                                // pull at YOUR pace (50ms timer etc.) — server condenses via the line's frame lambda
 // full guide + examples → rpc.md; frame model / lag policies → 🎞️ recipe below and rare docs
@@ -152,8 +152,44 @@ Media.createVideoSource({fps? = 3, codec? = 'jpeg', quality?, replay?}) -> [emit
 control: start() -> Promise<'idle'|'requesting'|'live'|'denied'|'no-device'|'error'> · stop() · getStats() · setDevice(id) · listDevices() · state
 Media.encodeMediaFrame(meta, payload) / Media.decodeMediaFrame(frame)     // one Uint8Array = 40-byte fixed header + raw payload
 ```
-Audio default is PCM frames from `AudioWorklet` where available (`mode:'record'` uses MediaRecorder chunks). Video default is camera snapshots (`video->canvas`, JPEG, low fps for vision). Put `listen` into `createRpcServerAuto` like any other Listen; with `replay:true`, the returned listen is a replay line, so RPC auto exposes legacy + replay surfaces under the same key. Backpressure policy: audio is lossless queue; video `replay:true` defaults to keep-latest frame recovery. `transport:'webrtc'` is reserved for a future SFU/signaling adapter; socket binary is the default today.
-
+Audio default is PCM frames from `AudioWorklet` where available (`mode:'record'` uses MediaRecorder chunks). Video default is camera snapshots (`video->canvas`, JPEG, low fps for vision). Put `listen` into `createRpcServerAuto` like any other Listen; with `replay:true`, the returned listen is a replay line, so RPC auto exposes legacy + replay surfaces under the same key. Backpressure policy: audio is lossless queue; video `replay:true` defaults to keep-latest frame recovery. `transport:'webrtc'` is reserved for a future SFU/signaling adapter; socket binary is the default today.
+
+## 🤝 Peer — accounts see each other's stores (one-call SDK)
+> `import { Peer } from "wenay-common2"` or `import * as Peer from "wenay-common2/peer"`.
+> The happy-path facade over rpc + store + replay + route coordinator. Legacy-friendly by design:
+> the server side is a FRAGMENT spread into your EXISTING `createRpcServerAuto` object, the client
+> side rides your existing connection — old keys keep working untouched.
+```
+// SERVER — next to your legacy object:
+const host = Peer.createPeerHost({authorize?, history?})   // authorize(env) = server-side canExposeEndpoint
+io.on('connection', socket => {
+    const peer = host.connection(accountOf(socket))        // per-account signal port + relay journal
+    createRpcServerAuto({socket, socketKey, object: {...legacyObject, peer: peer.fragment}, disconnectListen})
+    disconnectListen.on(peer.close)
+})
+host: connection(account) · relay(account) · accounts() · revoke(pair, accounts, reason?) · close()
+
+// CLIENT — the whole happy path:
+const me = Peer.createPeerClient<World>({
+    remote: c.app.func.peer,        // deep proxy of the fragment — rest of the connection is yours
+    account: 'a',
+    initial: {...},                 // own store: write me.store.state — others see it
+    rtc?: () => new RTCPeerConnection(cfg),   // omit = relay-only (promoteDirect unavailable)
+})
+const bob = me.peer('b')            // mirror + route control for another account
+await bob.ready                     // keyframe/tail landed
+bob.store.state                     // live mirror — reads survive ANY route change
+await bob.promoteDirect()           // relay -> WebRTC direct; {ok, state, reason?} result, not a throw
+bob.route()                         // 'relay' | 'direct' · bob.reinterposeRelay() · bob.fallback() · bob.block()
+me.onRoute(ev => {})                // route transitions for metrics/UI
+```
+Key property: the relay journal stores the owner's envelopes VERBATIM (owner seq space), so a
+relay <-> direct hand-off is a plain seq resume — no keyframe reset, no gaps, no dups. Late joiners
+get a keyframe folded server-side even while the owner is offline. Policy/session material:
+`createPeerClient({session, accept, policy})` + host `authorize` — see rare docs for the envelope
+contract and the underlying primitives (`createRouteCoordinator`, `createSignalHub`,
+`createWebRtcConnector`). Oracle: `replay/peer-sdk.test.ts`.
+
 ## 🔁 Observe — reactive state + store/mirror API
 > `import { Observe } from "wenay-common2"` or `import * as Observe from "wenay-common2/observe"`.
 > This is the documented v2 reactive/store surface.
@@ -199,8 +235,8 @@ Observe.exposeStoreReplay(store, {history? = 1024}) -> { api /* spread into the
 Observe.syncStoreReplay(mirror, remote /*{line, since, keyframe, frame?} of api.replay*/, {since?, onSeq?}) -> off
   // off.ready (catch-up done) · off.seq() (save for reconnect: syncStoreReplay(..., {since: prev.seq()}))
   // lagging/late client NEVER gets a backlog: evicted seq -> ONE fresh keyframe + live
-  // freshness is an option, not consumer boilerplate: {staleMs, onStale} flags a silent line / stale keyframe (edge-triggered both ways; 🎞️ in rare docs)
-Observe.syncStoreReplayRoute(mirror, remote, {label?}) -> off & {switch(nextRemote, opts), ready, seq(), label(), active()}
+  // freshness is an option, not consumer boilerplate: {staleMs, onStale} flags a silent line / stale keyframe (edge-triggered both ways; 🎞️ in rare docs)
+Observe.syncStoreReplayRoute(mirror, remote, {label?}) -> off & {switch(nextRemote, opts), ready, seq(), label(), active()}
   // relay/direct promotion and re-interposition: replacement route catches up by seq before the old route closes
 Observe.syncStoreReplayEach<T>(remote, (key, value, ctx) => {}, opts?) -> off & {store, ready, seq(), isStale(), lastTs()}
   // one-call remote fold: mirror store + syncStoreReplay + store.each() — the callback fires per CHANGED

package/lib/Common/events/route-signal-webrtc.js

@@ -130,7 +130,8 @@ function createWebRtcConnector(deps) {
         });
         me.onicecandidate = function onIce(ev) {
             if (ev?.candidate != null) {
-                void port.send({ type: 'ice', pair, from: self, to: peer, candidate: ev.candidate });
+                const c = ev.candidate;
+                void port.send({ type: 'ice', pair, from: self, to: peer, candidate: c?.toJSON ? c.toJSON() : c });
             }
         };
         try {
@@ -202,7 +203,8 @@ function acceptWebRtcDirect(deps) {
         };
         pc.onicecandidate = function onIce(ev) {
             if (ev?.candidate != null) {
-                void port.send({ type: 'ice', pair: env.pair, from: self, to: env.from, candidate: ev.candidate });
+                const c = ev.candidate;
+                void port.send({ type: 'ice', pair: env.pair, from: self, to: env.from, candidate: c?.toJSON ? c.toJSON() : c });
             }
         };
         try {

package/lib/Common/peer/peer-client.d.ts

@@ -0,0 +1,46 @@
+import { StoreDrain, StorePatch } from '../Observe/store';
+import { ReplayRemote } from '../events/replay-wire';
+import { RoutePolicy } from '../events/route-coordinator';
+import { RtcPeerConnection, SignalEnvelope } from '../events/route-signal-webrtc';
+import { PatchEnvelope } from './peer-relay';
+export type PeerRemote = {
+    signal: {
+        send: (env: SignalEnvelope) => Promise<boolean | void>;
+        signals: {
+            on: (cb: (env: SignalEnvelope) => void) => any;
+        };
+    };
+    publish: (env: PatchEnvelope) => Promise<boolean | void> | boolean | void;
+    peers: Record<string, ReplayRemote<[StorePatch]>>;
+};
+export type PeerClientDeps<T extends object> = {
+    remote: PeerRemote;
+    account: string;
+    initial: T;
+    rtc?: () => RtcPeerConnection;
+    session?: unknown;
+    accept?: (env: SignalEnvelope) => boolean | Promise<boolean>;
+    policy?: RoutePolicy;
+    peerInitial?: () => T;
+    history?: number;
+    drain?: StoreDrain;
+};
+export declare function createPeerClient<T extends object>(deps: PeerClientDeps<T>): {
+    store: import("../Observe/store").Store<T>;
+    peer: (other: string) => {
+        account: string;
+        store: import("../Observe/store").Store<T>;
+        ready: Promise<void>;
+        seq: () => number;
+        route: () => string;
+        state: () => import("../events/route-coordinator").tRouteState;
+        promoteDirect: (opts?: import("../events/route-coordinator").PromoteDirectOpts) => Promise<import("../events/route-coordinator").RouteOpResult>;
+        reinterposeRelay: (reason?: unknown) => Promise<import("../events/route-coordinator").RouteOpResult>;
+        fallback: (reason?: unknown) => Promise<import("../events/route-coordinator").RouteOpResult>;
+        block: (reason?: unknown) => Promise<import("../events/route-coordinator").RouteOpResult>;
+        close(): void;
+    };
+    onRoute: (cb: (ev: import("../events/route-coordinator").RouteChangeEvent) => void) => import("../..").ListenOff;
+    close(): void;
+};
+export type PeerClient<T extends object> = ReturnType<typeof createPeerClient<T>>;

package/lib/Common/peer/peer-client.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPeerClient = createPeerClient;
+const store_1 = require("../Observe/store");
+const store_replay_1 = require("../Observe/store-replay");
+const replay_wire_1 = require("../events/replay-wire");
+const route_coordinator_1 = require("../events/route-coordinator");
+const route_signal_webrtc_1 = require("../events/route-signal-webrtc");
+function createPeerClient(deps) {
+    const { remote, account, initial, rtc, session, accept, policy, peerInitial = () => ({}), history, drain, } = deps;
+    const store = (0, store_1.createStore)(initial, drain !== undefined ? { drain } : {});
+    const exposed = (0, store_replay_1.exposeStoreReplay)(store, history !== undefined ? { history } : {});
+    const offPublish = exposed.replay.line.on(function publishEnvelope(env) {
+        void remote.publish(env);
+    });
+    const warmup = exposed.replay.keyframe();
+    if (warmup)
+        void remote.publish(warmup);
+    const port = {
+        send: env => remote.signal.send(env),
+        signals: { on: cb => remote.signal.signals.on(cb) },
+    };
+    const stopAccept = rtc
+        ? (0, route_signal_webrtc_1.acceptWebRtcDirect)({
+            port, rtc, self: account,
+            serve: () => (0, replay_wire_1.exposeReplay)(exposed.replay),
+            ...(accept ? { accept } : {}),
+        })
+        : null;
+    function relayConnector(other) {
+        let state = 'idle';
+        return {
+            info: { label: 'relay', kind: 'relay', ordered: true, reliable: true },
+            open() {
+                const node = remote.peers[other];
+                state = 'open';
+                return {
+                    line: { on: (cb) => node.line.on(cb) },
+                    since: (seq) => node.since(seq),
+                    keyframe: () => node.keyframe(),
+                    frame: (seq, hint) => node.frame(seq, hint),
+                };
+            },
+            close: () => { state = 'closed'; },
+            state: () => state,
+        };
+    }
+    const coord = (0, route_coordinator_1.createRouteCoordinator)({
+        ...(policy ? { policy } : {}),
+        connect(ref, kind) {
+            const other = ref.a == account ? ref.b : ref.a;
+            if (kind == 'relay')
+                return relayConnector(other);
+            if (!rtc)
+                throw new Error('peer client: promoteDirect needs an rtc factory (deps.rtc)');
+            return (0, route_signal_webrtc_1.createWebRtcConnector)({
+                port, rtc, self: account, peer: other, pair: ref.key, session,
+            });
+        },
+    });
+    const views = new Map();
+    function makeView(other) {
+        const link = coord.pair(account, other);
+        const mirror = (0, store_1.createStore)(peerInitial(), drain !== undefined ? { drain } : {});
+        const sub = link.subscribe(function mirrorPatch(patch) {
+            (0, store_1.applyStorePatch)(mirror, patch);
+        });
+        const view = {
+            account: other,
+            store: mirror,
+            ready: sub.ready,
+            seq: sub.seq,
+            route: link.label,
+            state: link.state,
+            promoteDirect: link.promoteDirect,
+            reinterposeRelay: link.reinterposeRelay,
+            fallback: link.fallback,
+            block: link.block,
+            close() {
+                views.delete(other);
+                sub();
+                link.close();
+            },
+        };
+        return view;
+    }
+    function peer(other) {
+        const existing = views.get(other);
+        if (existing)
+            return existing;
+        const view = makeView(other);
+        views.set(other, view);
+        return view;
+    }
+    return {
+        store,
+        peer,
+        onRoute: coord.onRoute,
+        close() {
+            for (const view of Array.from(views.values()))
+                view.close();
+            coord.close();
+            stopAccept?.();
+            offPublish();
+            exposed.close();
+        },
+    };
+}

package/lib/Common/peer/peer-host.d.ts

@@ -0,0 +1,32 @@
+import { StorePatch } from '../Observe/store';
+import { ReplayRemote } from '../events/replay-wire';
+import { SignalEnvelope } from '../events/route-signal-webrtc';
+import { PatchEnvelope } from './peer-relay';
+export type PeerHostDeps = {
+    authorize?: (env: SignalEnvelope) => boolean | Promise<boolean>;
+    history?: number;
+};
+export declare function createPeerHost(deps?: PeerHostDeps): {
+    connection: (account: string) => {
+        fragment: {
+            signal: {
+                send: (env: SignalEnvelope) => Promise<boolean>;
+                signals: import("../..").ListenApi<[SignalEnvelope]>;
+            };
+            publish: (env: PatchEnvelope) => boolean;
+            peers: Record<string, ReplayRemote<[StorePatch]>>;
+        };
+        close: () => void;
+    };
+    relay: (account: string) => {
+        push: (env: PatchEnvelope) => boolean;
+        remote: ReplayRemote<[StorePatch]>;
+        seq: () => number;
+        snapshot: () => any;
+        close: () => void;
+    };
+    accounts: () => string[];
+    revoke: (pair: string, accounts: string[], reason?: string) => void;
+    close(): void;
+};
+export type PeerHost = ReturnType<typeof createPeerHost>;

package/lib/Common/peer/peer-host.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPeerHost = createPeerHost;
+const rpc_dynamic_1 = require("../rcp/rpc-dynamic");
+const route_signal_webrtc_1 = require("../events/route-signal-webrtc");
+const peer_relay_1 = require("./peer-relay");
+function createPeerHost(deps = {}) {
+    const { authorize, history } = deps;
+    const hub = (0, route_signal_webrtc_1.createSignalHub)({ authorize });
+    const relays = new Map();
+    const peersView = (0, rpc_dynamic_1.noStrict)({});
+    function ensureRelay(account) {
+        let relay = relays.get(account);
+        if (!relay) {
+            relay = (0, peer_relay_1.createPatchRelayJournal)({ history });
+            relays.set(account, relay);
+            peersView[account] = relay.remote;
+        }
+        return relay;
+    }
+    function connection(account) {
+        const port = hub.register(account);
+        const mine = ensureRelay(account);
+        return {
+            fragment: {
+                signal: { send: port.send, signals: port.signals },
+                publish: (env) => mine.push(env),
+                peers: peersView,
+            },
+            close: () => port.close(),
+        };
+    }
+    return {
+        connection,
+        relay: ensureRelay,
+        accounts: () => Array.from(relays.keys()),
+        revoke: hub.revoke,
+        close() {
+            hub.close();
+            for (const relay of relays.values())
+                relay.close();
+            relays.clear();
+        },
+    };
+}

package/lib/Common/peer/peer-index.d.ts

@@ -0,0 +1,3 @@
+export * from './peer-relay';
+export * from './peer-host';
+export * from './peer-client';

package/lib/Common/peer/peer-index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./peer-relay"), exports);
+__exportStar(require("./peer-host"), exports);
+__exportStar(require("./peer-client"), exports);

package/lib/Common/peer/peer-relay.d.ts

@@ -0,0 +1,14 @@
+import { ReplayEvent } from '../events/replay-listen';
+import { ReplayRemote } from '../events/replay-wire';
+import { StorePatch } from '../Observe/store';
+export type PatchEnvelope = ReplayEvent<[StorePatch]>;
+export declare function createPatchRelayJournal(opts?: {
+    history?: number;
+}): {
+    push: (env: PatchEnvelope) => boolean;
+    remote: ReplayRemote<[StorePatch]>;
+    seq: () => number;
+    snapshot: () => any;
+    close: () => void;
+};
+export type PatchRelayJournal = ReturnType<typeof createPatchRelayJournal>;