wenay-common2 1.0.73 → 1.0.74

package/README.md

@@ -12,10 +12,11 @@
 
 ## Living examples (shipped in the npm package)
 
-- [`demo/`](demo/) — runnable stand (`npm run demo`): shared cursors in two browser tabs over the
+- [`demo/`](demo/) — runnable from a repository checkout (`npm run demo`): shared cursors in two browser tabs over the
   Peer SDK, relay ⇄ WebRTC direct hand-off next to a legacy rpc key; plus live media — camera,
   microphone and screen share captured with the `Media` sources and streamed to the watching tab.
 - [`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
+- The package ships readable example sources, not installed CLI scripts. Examples import from the
+  repo's `src/`; in application code the same API comes from
   `wenay-common2` / `wenay-common2/peer` / `wenay-common2/replay` / `wenay-common2/observe`.

package/demo/client.ts

@@ -1,11 +1,12 @@
 // 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.
-// Plus live media: camera / mic / screen share captured with the Media sources and
-// streamed to the watching tab through the demo server's media relay.
+// Plus messenger-style calls: presence shows who is online, the call button rings
+// the peer over the SAME signal hub, and media (camera / mic / screen) attaches
+// only while the call is active — the server's watch ACL follows the call.
 import {io} from 'socket.io-client'
 import {createRpcClientHub} from '../src/Common/rcp/rpc-clientHub'
-import {createPeerClient} from '../src/Common/peer/peer-index'
+import {callPortOf, createCallManager, createPeerClient} from '../src/Common/peer/peer-index'
 import {attachAudioPlayer, attachVideoCanvas, createAudioSource, createVideoSource, pipeMediaPublish} from '../src/Common/media/media-index'
 
 type World = {cursor: {x: number, y: number}, color: string, name: string}
@@ -27,23 +28,40 @@ function log(line: string) {
 
 async function main() {
     document.title = `peer ${me}`
-    el('who').textContent = `me: ${me}  ·  watching: ${other}`
+    el('who').textContent = `me: ${me}  ·  peer: ${other}`
 
     const hub = createRpcClientHub(
-        () => io({transports: ['websocket'], auth: {account: me, watch: other}}),
+        () => 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
+    // debug tap: every signaling envelope this account receives (webrtc AND call types)
     ;(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)}` : ''))
     })
 
+    // ============== presence: is the peer online? ==============
+    const onlineEl = el('online')
+    const onlineSet = new Set<string>()
+    function renderPresence() {
+        const up = onlineSet.has(other)
+        onlineEl.textContent = up ? `● ${other} online` : `○ ${other} offline`
+        onlineEl.style.color = up ? '#2e7d32' : '#999'
+    }
+    // subscribe FIRST, then list() — the changes feed is a plain edge Listen
+    ;(clients.app.func.peer.presence.changes as any).on((ch: any) => {
+        if (ch.online) onlineSet.add(ch.account); else onlineSet.delete(ch.account)
+        if (ch.account != me) log(`presence: ${ch.account} ${ch.online ? 'online' : 'offline'}`)
+        renderPresence()
+    })
+    for (const account of await clients.app.func.peer.presence.list()) onlineSet.add(account)
+    renderPresence()
+
     const client = createPeerClient<World>({
         remote: clients.app.func.peer,
         account: me,
@@ -99,14 +117,65 @@ async function main() {
         log(res.ok ? 'back on relay' : `re-interpose failed: ${String(res.reason)}`)
     })
 
-    setupMedia(clients.app.func.media)
+    // ============== calls: ring/accept/decline over the same signal hub ==============
+    const media = setupMedia(clients.app.func.media)
+    const calls = createCallManager({port: callPortOf(clients.app.func.peer), self: me})
+    calls.ready.then(() => log('call signaling ready'))
+
+    const callBtn = el('call') as HTMLButtonElement
+    const acceptBtn = el('accept') as HTMLButtonElement
+    const declineBtn = el('decline') as HTMLButtonElement
+    const callStateEl = el('callState')
+    let call: any = null
+
+    function renderCallUi() {
+        const state = call?.state()
+        const incoming = call?.direction == 'in' && state == 'ringing'
+        callBtn.hidden = incoming
+        acceptBtn.hidden = !incoming
+        declineBtn.hidden = !incoming
+        callBtn.textContent = state == 'active' ? '📞 hang up'
+            : state == 'ringing' ? '📞 cancel…'
+            : `📞 call ${other}`
+        callStateEl.textContent = !call ? ''
+            : state == 'ringing' ? (incoming ? `${call.peer} is calling…` : `ringing ${call.peer}…`)
+            : state == 'active' ? `in call with ${call.peer}`
+            : ''
+    }
+
+    function bindCall(next: any) {
+        call = next
+        call.changed.on(function onCallState(state: string) {
+            log(`call ${state}${call?.reason() ? ` (${call.reason()})` : ''}`)
+            if (state == 'active') media.attachPeer()
+            if (state == 'ended') {
+                media.detachPeer()
+                call = null
+            }
+            renderCallUi()
+        })
+        renderCallUi()
+    }
+
+    callBtn.addEventListener('click', function onCallButton() {
+        if (call) { call.hangup(); return }
+        log(`calling ${other}...`)
+        bindCall(calls.call(other, {kinds: ['cam', 'mic', 'screen']}))
+    })
+    acceptBtn.addEventListener('click', () => call?.accept())
+    declineBtn.addEventListener('click', () => call?.decline())
+    calls.rings.on(function onIncomingRing(incoming: any) {
+        log(`incoming call from ${incoming.peer}`)
+        bindCall(incoming)
+    })
+    renderCallUi()
 }
 
-// ============== media: capture own cam/mic/screen, watch the peer's ==============
+// ============== media: capture own cam/mic/screen; watch the peer's WHILE IN CALL ==============
 type tMediaKind = 'cam' | 'mic' | 'screen'
 
 function setupMedia(media: any) {
-    // -------- publish own frames through the demo relay (fire-and-forget) --------
+    // -------- publish own frames through the relay (fire-and-forget) --------
     function pipePublish(kind: tMediaKind, src: any) {
         pipeMediaPublish(src[1], (frame, sentAt) => media.publish(kind, frame, sentAt), {
             onError: e => log(`media publish ${kind} failed: ${e}`),
@@ -167,31 +236,63 @@ function setupMedia(media: any) {
     bindToggle('mic', 'mic', '🎙 mic')
     bindToggle('screen', 'screen', '🖥 screen')
 
-    // -------- watch the peer's lines (one call per channel) --------
-    function watchVideo(line: any, canvasId: string, caption: string) {
-        const canvas = el(canvasId) as HTMLCanvasElement
-        const captionEl = el(canvasId + 'Cap')
+    // -------- peer viewers: attached only while a call is active --------
+    // The server's watch ACL denies media.watch[peer] outside a call, so the viewers
+    // are created on 'active' and torn down on 'ended' (one-time DOM wiring below).
+    for (const id of ['peerCam', 'peerScreen']) {
+        const canvas = el(id) as HTMLCanvasElement
         canvas.addEventListener('click', function goFullscreen() {
             void (document.fullscreenElement == canvas ? document.exitFullscreen() : canvas.requestFullscreen?.())
         })
-        const view = attachVideoCanvas(line, canvas, {onError: e => log('video frame render failed: ' + e)})
-        return {view, captionEl, caption}
     }
-    const peerCam = watchVideo(media.peer.cam, 'peerCam', 'peer camera')
-    const peerScreen = watchVideo(media.peer.screen, 'peerScreen', 'peer screen')
-
-    const player = attachAudioPlayer(media.peer.mic, {onError: e => log('audio frame failed: ' + e)})
     const audioBtn = el('audio') as HTMLButtonElement
+    type PeerViews = {
+        cam: ReturnType<typeof attachVideoCanvas>
+        screen: ReturnType<typeof attachVideoCanvas>
+        player: ReturnType<typeof attachAudioPlayer>
+    }
+    let views: PeerViews | null = null
+
     audioBtn.addEventListener('click', function togglePeerAudio() {
-        if (player.enabled) {
-            player.disable()
+        if (!views) return
+        if (views.player.enabled) {
+            views.player.disable()
             audioBtn.textContent = '🔊 peer audio'
         } else {
-            player.enable()
+            views.player.enable()
             audioBtn.textContent = '🔊 peer audio ⏹'
         }
     })
 
+    function attachPeer() {
+        if (views) return
+        const watch = media.watch[other]
+        views = {
+            cam: attachVideoCanvas(watch.cam, el('peerCam'), {onError: e => log('video frame render failed: ' + e)}),
+            screen: attachVideoCanvas(watch.screen, el('peerScreen'), {onError: e => log('screen frame render failed: ' + e)}),
+            player: attachAudioPlayer(watch.mic, {onError: e => log('audio frame failed: ' + e)}),
+        }
+        audioBtn.disabled = false
+        log(`watching ${other}'s media (call active)`)
+    }
+
+    function detachPeer() {
+        if (!views) return
+        views.cam.off()
+        views.screen.off()
+        views.player.disable()
+        views.player.off()
+        views = null
+        audioBtn.disabled = true
+        audioBtn.textContent = '🔊 peer audio'
+        for (const id of ['peerCam', 'peerScreen']) {
+            const canvas = el(id) as HTMLCanvasElement
+            canvas.getContext('2d')?.clearRect(0, 0, canvas.width, canvas.height)
+        }
+        log('peer media detached (call ended)')
+    }
+    audioBtn.disabled = true
+
     // -------- stats line: own capture + helper-provided rx metrics --------
     const statsEl = el('mediaStats')
     let prevTx = {cam: 0, mic: 0, screen: 0}
@@ -204,19 +305,23 @@ function setupMedia(media: any) {
             if (s.state != 'idle') parts.push(`${kind}: ${s.state} ${s.frames}f ${s.frames - prevTx[kind]}/s${s.rms != null ? ` rms=${s.rms.toFixed(3)}` : ''}`)
         }
         prevTx = nextTx
-        const cam = peerCam.view.stats()
-        const screen = peerScreen.view.stats()
-        const mic = player.stats()
-        for (const v of [peerCam, peerScreen]) {
-            const s = v.view.stats()
-            if (s.width) v.captionEl.textContent = `${v.caption} · ${s.width}×${s.height} · click = fullscreen`
+        if (views) {
+            const cam = views.cam.stats()
+            const screen = views.screen.stats()
+            const mic = views.player.stats()
+            const caps = [['peerCam', 'peer camera', cam], ['peerScreen', 'peer screen', screen]] as const
+            for (const [id, caption, s] of caps) {
+                if (s.width) el(id + 'Cap').textContent = `${caption} · ${s.width}×${s.height} · click = fullscreen`
+            }
+            if (cam.frames || screen.frames || mic.frames) parts.push(
+                `rx: cam ${cam.frames}f/${cam.drawn}d ${cam.perSec}/s ~${cam.ageMs}ms` +
+                ` · screen ${screen.frames}f/${screen.drawn}d ${screen.perSec}/s ~${screen.ageMs}ms` +
+                ` · mic ${mic.frames}f ${mic.perSec}/s ~${mic.ageMs}ms`)
         }
-        if (cam.frames || screen.frames || mic.frames) parts.push(
-            `rx: cam ${cam.frames}f/${cam.drawn}d ${cam.perSec}/s ~${cam.ageMs}ms` +
-            ` · screen ${screen.frames}f/${screen.drawn}d ${screen.perSec}/s ~${screen.ageMs}ms` +
-            ` · mic ${mic.frames}f ${mic.perSec}/s ~${mic.ageMs}ms`)
         statsEl.textContent = parts.join('  ·  ')
     }, 1000)
+
+    return {attachPeer, detachPeer}
 }
 
 main().catch(e => { console.error(e); log('FATAL: ' + e) })

package/demo/index.html

@@ -24,10 +24,17 @@
 <h3>wenay-common2 — shared cursors (relay ⇄ WebRTC direct)</h3>
 <div id="bar">
     <span id="who">connecting…</span>
+    <span id="online"></span>
     <button id="direct">Go direct</button>
     <button id="relay">Back to relay</button>
     <span id="route"></span>
 </div>
+<div id="bar">
+    <button id="call">📞 call</button>
+    <button id="accept" hidden>✅ accept</button>
+    <button id="decline" hidden>⛔ decline</button>
+    <span id="callState"></span>
+</div>
 <canvas id="canvas" width="640" height="360"></canvas>
 <div id="bar">
     <button id="cam">📷 camera</button>

package/demo/server.ts

@@ -5,55 +5,93 @@ import {createServer} from 'http'
 import path from 'path'
 import {Server as SocketIOServer} from 'socket.io'
 import {listen} from '../src/Common/events/Listen'
-import {replayListen} from '../src/Common/events/replay-listen'
-import {createPeerHost} from '../src/Common/peer/peer-index'
+import {SignalEnvelope} from '../src/Common/events/route-signal-webrtc'
+import {createMediaRelay, createPeerHost} from '../src/Common/peer/peer-index'
 import {createRpcServerAuto} from '../src/Common/rcp/rpc-server-auto'
 
 const PORT = Number(process.env.PORT ?? 8390)
 
-// ============== demo media hub: per-account replay lines ==============
-// Browser capture (cam/mic/screen) originates on the CLIENT, so the server side is a
-// tiny relay: publish() feeds the publisher's line, watchers get plain Listen surfaces
-// exposed through createRpcServerAuto like any other Listen. Video lines are keep-latest
-// (a late joiner instantly gets the last frame), audio is a short lossless queue.
-type tMediaKind = 'cam' | 'mic' | 'screen'
+// ============== media relay + call-driven watch ACL ==============
+// The signal hub is the single policy boundary, but authorization still needs a tiny
+// server-owned call lifecycle: an arbitrary forged `accept` must never grant media.
+function createCallWatchPolicy() {
+    type Call = {caller: string, callee: string, state: 'ringing' | 'active', timer: any}
+    const calls = new Map<string, Call>()
+    const grants = new Set<string>()
 
-function createDemoMediaHub() {
-    // [frame, sentAt]: wall-clock publish time rides along so viewers can show real latency
-    function createLines() {
-        return {
-            cam: replayListen<[Uint8Array, number]>({history: 8, current: 'last', frame: tail => tail.length ? [tail[tail.length - 1]] : []}),
-            screen: replayListen<[Uint8Array, number]>({history: 8, current: 'last', frame: tail => tail.length ? [tail[tail.length - 1]] : []}),
-            mic: replayListen<[Uint8Array, number]>({history: 64}),
+    function grant(a: string, b: string, on: boolean) {
+        if (on) { grants.add(a + '|' + b); grants.add(b + '|' + a) }
+        else { grants.delete(a + '|' + b); grants.delete(b + '|' + a) }
+    }
+
+    function finish(pair: string, reason: string) {
+        const call = calls.get(pair)
+        if (!call) return
+        calls.delete(pair)
+        clearTimeout(call.timer)
+        grant(call.caller, call.callee, false)
+        console.log(`[demo] call down: ${call.caller} <-> ${call.callee} (${reason})`)
+    }
+
+    function authorize(env: SignalEnvelope) {
+        if (env.type == 'ring') {
+            if (!env.pair.startsWith('call:') || env.from == env.to || calls.has(env.pair)) return false
+            const timer = setTimeout(function expireServerCall() { finish(env.pair, 'expired') }, 35_000)
+            timer.unref?.()
+            calls.set(env.pair, {caller: env.from, callee: env.to, state: 'ringing', timer})
+            return true
         }
+        if (env.type != 'accept' && env.type != 'decline' && env.type != 'hangup') return true
+        const call = calls.get(env.pair)
+        if (!call) return false
+        const reverse = env.from == call.callee && env.to == call.caller
+        const participant = (env.from == call.caller && env.to == call.callee) || reverse
+        if (env.type == 'accept') {
+            if (call.state != 'ringing' || !reverse) return false
+            call.state = 'active'
+            clearTimeout(call.timer)
+            call.timer = null
+            grant(call.caller, call.callee, true)
+            console.log(`[demo] call up: ${call.caller} <-> ${call.callee} (media granted)`)
+            return true
+        }
+        if (env.type == 'decline' && (!reverse || call.state != 'ringing')) return false
+        if (!participant) return false
+        finish(env.pair, env.type)
+        return true
     }
-    const accounts = new Map<string, ReturnType<typeof createLines>>()
-    function linesOf(account: string) {
-        let lines = accounts.get(account)
-        if (!lines) {
-            lines = createLines()
-            accounts.set(account, lines)
+
+    function dropAccount(account: string) {
+        for (const [pair, call] of calls) {
+            if (call.caller == account || call.callee == account) finish(pair, 'offline')
+        }
+        for (const key of Array.from(grants)) {
+            if (key.startsWith(account + '|') || key.endsWith('|' + account)) grants.delete(key)
         }
-        return lines
     }
+
     return {
-        // what the publishing account calls
-        publishOf(account: string) {
-            return function publish(kind: tMediaKind, frame: Uint8Array, sentAt: number) {
-                const line = linesOf(account)[kind]
-                if (line) line[0](frame, sentAt)
-            }
-        },
-        // what a watcher subscribes to
-        watchOf(account: string) {
-            const lines = linesOf(account)
-            return {cam: lines.cam[1], mic: lines.mic[1], screen: lines.screen[1]}
-        },
+        authorize,
+        canWatch: (watcher: string, owner: string) => grants.has(watcher + '|' + owner),
+        dropAccount,
     }
 }
 
-const host = createPeerHost()
-const mediaHub = createDemoMediaHub()
+const callPolicy = createCallWatchPolicy()
+const media = createMediaRelay({
+    lines: {cam: 'video', mic: 'audio', screen: 'video'},
+    canWatch: callPolicy.canWatch,
+})
+const host = createPeerHost({authorize: callPolicy.authorize})
+
+// Presence cleanup retires media lines and every call/grant involving the account.
+host.presence.changes.on(function onPresenceEdge(ch) {
+    console.log(`[demo] presence: ${ch.account} ${ch.online ? 'online' : 'offline'}`)
+    if (ch.online) return
+    callPolicy.dropAccount(ch.account)
+    media.dropAccount(ch.account)
+})
+
 const app = express()
 app.use(express.static(path.resolve(__dirname, 'public')))
 app.get('/', (_req, res) => res.sendFile(path.resolve(__dirname, 'public', 'index.html')))
@@ -64,7 +102,6 @@ const ioServer = new SocketIOServer(httpServer, {maxHttpBufferSize: 1e8})
 
 ioServer.on('connection', function onDemoConnection(socket) {
     const account = String(socket.handshake.auth?.account ?? 'anon')
-    const watch = String(socket.handshake.auth?.watch ?? (account == 'a' ? 'b' : 'a'))
     const peer = host.connection(account)
     const [disconnect, disconnectListen] = listen<[]>()
     socket.on('disconnect', () => { disconnect(); peer.close() })
@@ -76,18 +113,18 @@ ioServer.on('connection', function onDemoConnection(socket) {
             serverTime: () => new Date().toISOString(),
             peer: peer.fragment,
             media: {
-                publish: mediaHub.publishOf(account),
-                // the watched account's live lines, declared at connect time (auth.watch)
-                peer: mediaHub.watchOf(watch),
+                publish: media.publishOf(account),
+                // policy-gated view: THIS connection's account is what canWatch receives
+                watch: media.watchOf(account),
             },
         },
         disconnectListen,
     })
-    console.log(`[demo] ${account} connected (watching ${watch})`)
+    console.log(`[demo] ${account} connected`)
 })
 
 httpServer.listen(PORT, function onDemoListen() {
-    console.log('[demo] shared-cursor stand is up:')
+    console.log('[demo] shared-cursor + calls 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/INTENT.md

@@ -1,31 +1,31 @@
-# wenay-common2 — project intent
-
-## What this is
-
-A personal, open-source common/transport library, matured over many years. The published `1.x`
-line is really a **second generation** ("version 1" the number, version 2 the design) — the earlier
-generation and its plan/history docs were deliberately removed; the canonical surface today is
-`doc/wenay-common2.md` (brief) + `doc/wenay-common2-rare.md` (full reference).
-
-The current stack is a small distributed-state runtime: a typed RPC core, an `Observe` reactive
-store, a universal replay layer (`seq` + keyframe + deltas), a policy-gated route coordinator
-(relay ⇄ WebRTC direct), a WebRTC signaling adapter, a media-over-socket layer, and a one-call
-`Peer` SDK on top. It is oracle-covered (CI on every push) and shipped with living examples and a
-runnable demo stand in the npm package.
-
-## Intent (2026-07)
-
-- **Open source, not promoted.** The library is public for use and as a portfolio/reference, but the
-  author is **not** going to actively market or grow a community around it. Other side-projects are
-  the current focus.
-- **No pressure to "finish" transport.** The transport/routing/replay lower half is built and good
-  enough; ROADMAP transport items are 🧊 deferred (super-low priority, not forbidden). They reopen
-  only when a real consumer hits a wall — never speculatively.
-- **Value is in being legible and demoable.** The measure of progress is "what can be shown
-  working," not layers added. The demo stand and the oracle examples exist to make the design
-  readable and hireable, not to chase feature completeness.
-- **Direction if picked up again:** the consumption layer (framework adapters — React hooks first),
-  and the showcase (a hero relay→direct demo). Everything else waits for a concrete need.
-
-This file is the durable record of that intent. It is not a worklist; the forward backlog (kept for
-reference, not commitment) lives in `doc/ROADMAP.md` and `doc/target/`.
+# wenay-common2 — project intent
+
+## What this is
+
+A personal, open-source common/transport library, matured over many years. The published `1.x`
+line is really a **second generation** ("version 1" the number, version 2 the design) — the earlier
+generation and its plan/history docs were deliberately removed; the canonical surface today is
+`doc/wenay-common2.md` (brief) + `doc/wenay-common2-rare.md` (full reference).
+
+The current stack is a small distributed-state runtime: a typed RPC core, an `Observe` reactive
+store, a universal replay layer (`seq` + keyframe + deltas), a policy-gated route coordinator
+(relay ⇄ WebRTC direct), a WebRTC signaling adapter, a media-over-socket layer, and a one-call
+`Peer` SDK on top. It is oracle-covered (CI on every push) and shipped with living examples and a
+runnable demo stand in the repository; the npm package carries its readable source.
+
+## Intent (2026-07)
+
+- **Open source, not promoted.** The library is public for use and as a portfolio/reference, but the
+  author is **not** going to actively market or grow a community around it. Other side-projects are
+  the current focus.
+- **No pressure to "finish" transport.** The transport/routing/replay lower half is built and good
+  enough; ROADMAP transport items are 🧊 deferred (super-low priority, not forbidden). They reopen
+  only when a real consumer hits a wall — never speculatively.
+- **Value is in being legible and demoable.** The measure of progress is "what can be shown
+  working," not layers added. The demo stand and the oracle examples exist to make the design
+  readable and hireable, not to chase feature completeness.
+- **Direction if picked up again:** the consumption layer (framework adapters — React hooks first),
+  and the showcase (a hero relay→direct demo). Everything else waits for a concrete need.
+
+This file is the durable record of that intent. It is not a worklist; the forward backlog (kept for
+reference, not commitment) lives in `doc/ROADMAP.md` and `doc/target/`.