wenay-common2 1.0.70 → 1.0.74

package/README.md

@@ -12,9 +12,11 @@
 
 ## 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.
+- [`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,9 +1,13 @@
 // 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 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}
 
@@ -24,7 +28,7 @@ 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}}),
@@ -34,13 +38,30 @@ async function main() {
     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,
@@ -95,6 +116,212 @@ async function main() {
         const res = await peer.reinterposeRelay('manual')
         log(res.ok ? 'back on relay' : `re-interpose failed: ${String(res.reason)}`)
     })
+
+    // ============== 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 WHILE IN CALL ==============
+type tMediaKind = 'cam' | 'mic' | 'screen'
+
+function setupMedia(media: any) {
+    // -------- 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}`),
+        })
+        return src
+    }
+
+    const camResEl = el('camRes') as HTMLSelectElement
+    function makeCam() {
+        // library fps default (3) targets machine vision; a live stand wants motion
+        return pipePublish('cam', createVideoSource({sourceId: 'cam', fps: 60, width: Number(camResEl.value) || 640, codec: 'jpeg'}))
+    }
+
+    const sources = {
+        cam: makeCam(),
+        screen: pipePublish('screen', createVideoSource({
+            sourceId: 'screen',
+            fps: 10,
+            codec: 'jpeg',
+            quality: 0.5,            // full-screen JPEGs get large fast; favor latency
+            // the documented `stream` injection point: skip getUserMedia, bring getDisplayMedia
+            stream: () => (navigator.mediaDevices as any).getDisplayMedia({video: true}),
+        })),
+        // big buffers on purpose: the worklet's 128-sample chunks would be ~375 socket
+        // messages per second and drown the shared connection (lag for everything)
+        mic: pipePublish('mic', createAudioSource({sourceId: 'mic', worklet: false, bufferSize: 4096})),
+    }
+
+    // resolution stress test: swap the camera source on the fly, keep it live if it was
+    camResEl.addEventListener('change', async function onCamResChange() {
+        const wasLive = sources.cam.state == 'live'
+        sources.cam.stop()
+        sources.cam = makeCam()
+        if (wasLive) {
+            const state = await sources.cam.start()
+            log(`cam @${camResEl.value}p: ${state}`)
+        }
+    })
+
+    // -------- capture toggles --------
+    function bindToggle(id: string, kind: tMediaKind, label: string) {
+        const btn = el(id) as HTMLButtonElement
+        btn.addEventListener('click', async function toggleCapture() {
+            const src = sources[kind]
+            if (src.state == 'live') {
+                src.stop()
+                btn.textContent = label
+                log(`${kind}: stopped`)
+                return
+            }
+            btn.textContent = `${label} …`
+            const state = await src.start()
+            btn.textContent = state == 'live' ? `${label} ⏹` : label
+            log(`${kind}: ${state}${state != 'live' && src.getStats().error ? ' — ' + src.getStats().error : ''}`)
+        })
+    }
+    bindToggle('cam', 'cam', '📷 camera')
+    bindToggle('mic', 'mic', '🎙 mic')
+    bindToggle('screen', 'screen', '🖥 screen')
+
+    // -------- 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 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 (!views) return
+        if (views.player.enabled) {
+            views.player.disable()
+            audioBtn.textContent = '🔊 peer audio'
+        } else {
+            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}
+    setInterval(function renderMediaStats() {
+        const parts: string[] = []
+        const nextTx = {cam: 0, mic: 0, screen: 0}
+        for (const kind of ['cam', 'mic', 'screen'] as const) {
+            const s = sources[kind].getStats()
+            nextTx[kind] = s.frames
+            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
+        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`)
+        }
+        statsEl.textContent = parts.join('  ·  ')
+    }, 1000)
+
+    return {attachPeer, detachPeer}
 }
 
 main().catch(e => { console.error(e); log('FATAL: ' + e) })

package/demo/index.html

@@ -11,17 +11,54 @@
     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; }
+    #mediaView { display: flex; gap: 12px; margin-top: 8px; flex-wrap: wrap; }
+    #mediaView figure { margin: 0; }
+    #mediaView figcaption { font-size: 12px; color: #777; margin-bottom: 4px; }
+    #peerCam, #peerScreen { border: 1px solid #bbb; border-radius: 6px; background: #111; max-width: 480px; height: auto; cursor: zoom-in; }
+    #peerCam:fullscreen, #peerScreen:fullscreen { width: 100vw; height: 100vh; object-fit: contain; background: #000; border: none; }
+    select { padding: 6px 8px; border-radius: 6px; border: 1px solid #888; background: #fff; }
+    #mediaStats { font-family: monospace; font-size: 12px; color: #777; }
 </style>
 </head>
 <body>
 <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>
+    <select id="camRes" title="camera capture width">
+        <option value="320">320p</option>
+        <option value="640" selected>640p</option>
+        <option value="1280">1280p</option>
+        <option value="1920">1920p</option>
+    </select>
+    <button id="mic">🎙 mic</button>
+    <button id="screen">🖥 screen</button>
+    <button id="audio">🔊 peer audio</button>
+    <span id="mediaStats"></span>
+</div>
+<div id="mediaView">
+    <figure>
+        <figcaption id="peerCamCap">peer camera · click = fullscreen</figcaption>
+        <canvas id="peerCam" width="320" height="240"></canvas>
+    </figure>
+    <figure>
+        <figcaption id="peerScreenCap">peer screen · click = fullscreen</figcaption>
+        <canvas id="peerScreen" width="480" height="270"></canvas>
+    </figure>
+</div>
 <div id="log"></div>
 <script src="client.js"></script>
 </body>

package/demo/server.ts

@@ -5,18 +5,100 @@ 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 {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)
 
-const host = createPeerHost()
+// ============== 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 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
+    }
+
+    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 {
+        authorize,
+        canWatch: (watcher: string, owner: string) => grants.has(watcher + '|' + owner),
+        dropAccount,
+    }
+}
+
+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')))
 
 const httpServer = createServer(app)
-const ioServer = new SocketIOServer(httpServer)
+// screen-share JPEG frames can exceed the 1MB Socket.IO default
+const ioServer = new SocketIOServer(httpServer, {maxHttpBufferSize: 1e8})
 
 ioServer.on('connection', function onDemoConnection(socket) {
     const account = String(socket.handshake.auth?.account ?? 'anon')
@@ -30,6 +112,11 @@ ioServer.on('connection', function onDemoConnection(socket) {
             // legacy key on the SAME connection — the SDK does not displace old code
             serverTime: () => new Date().toISOString(),
             peer: peer.fragment,
+            media: {
+                publish: media.publishOf(account),
+                // policy-gated view: THIS connection's account is what canWatch receives
+                watch: media.watchOf(account),
+            },
         },
         disconnectListen,
     })
@@ -37,7 +124,7 @@ ioServer.on('connection', function onDemoConnection(socket) {
 })
 
 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

@@ -0,0 +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 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/`.