wenay-common2 1.0.70 → 1.0.73

package/README.md

@@ -13,7 +13,8 @@
 ## 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.
+  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

package/demo/client.ts

@@ -1,9 +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.
 import {io} from 'socket.io-client'
 import {createRpcClientHub} from '../src/Common/rcp/rpc-clientHub'
 import {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,7 +30,7 @@ async function main() {
     el('who').textContent = `me: ${me}  ·  watching: ${other}`
 
     const hub = createRpcClientHub(
-        () => io({transports: ['websocket'], auth: {account: me}}),
+        () => io({transports: ['websocket'], auth: {account: me, watch: other}}),
         r => ({app: r<any>('app')}) as const,
     )
     const clients = await hub.setToken(null)
@@ -95,6 +98,125 @@ async function main() {
         const res = await peer.reinterposeRelay('manual')
         log(res.ok ? 'back on relay' : `re-interpose failed: ${String(res.reason)}`)
     })
+
+    setupMedia(clients.app.func.media)
+}
+
+// ============== media: capture own cam/mic/screen, watch the peer's ==============
+type tMediaKind = 'cam' | 'mic' | 'screen'
+
+function setupMedia(media: any) {
+    // -------- publish own frames through the demo 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')
+
+    // -------- 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')
+        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
+    audioBtn.addEventListener('click', function togglePeerAudio() {
+        if (player.enabled) {
+            player.disable()
+            audioBtn.textContent = '🔊 peer audio'
+        } else {
+            player.enable()
+            audioBtn.textContent = '🔊 peer audio ⏹'
+        }
+    })
+
+    // -------- 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
+        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 (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)
 }
 
 main().catch(e => { console.error(e); log('FATAL: ' + e) })

package/demo/index.html

@@ -11,6 +11,13 @@
     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>
@@ -22,6 +29,29 @@
     <span id="route"></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,21 +5,66 @@ 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 {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'
+
+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}),
+        }
+    }
+    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)
+        }
+        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]}
+        },
+    }
+}
+
 const host = createPeerHost()
+const mediaHub = createDemoMediaHub()
 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')
+    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() })
@@ -30,10 +75,15 @@ 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: mediaHub.publishOf(account),
+                // the watched account's live lines, declared at connect time (auth.watch)
+                peer: mediaHub.watchOf(watch),
+            },
         },
         disconnectListen,
     })
-    console.log(`[demo] ${account} connected`)
+    console.log(`[demo] ${account} connected (watching ${watch})`)
 })
 
 httpServer.listen(PORT, function onDemoListen() {

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 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/`.

package/doc/ROADMAP.md

@@ -141,7 +141,25 @@ and `serveReplayChannel`/`channelReplayRemote` (replay wire over any ordered cha
 path bypasses the RPC core by design). Oracle `replay/route-webrtc.test.ts` drives promotion, endpoint
 denial, session rejection, and server revoke over both an in-proc hub and a real Socket.IO/RPC wire.
 Still open: browser/Node WebRTC glue (step 10 — now a one-line `rtc` factory plus media re-emit) and
-the account-map lifecycle integration (step 7).
+the account-map lifecycle integration (step 7). Media-side candidates (2026-07-10, after the demo
+stand stress test): a real `transport:'webrtc'` media track — SDP over the existing signal hub,
+media bypassing the socket relay for call-grade smoothness; and `MediaStreamTrackProcessor` capture
+for true 30fps (`grabFrame`'s ~50ms serial latency caps snapshot capture at ~15-20fps).
+
+Consumption-layer candidates (2026-07-10, author's ask):
+- **Call system** — one account calls another, messenger-style: presence (the host already knows
+  who is connected), ring / accept / decline envelopes over the existing signal hub, then media
+  over the socket relay (mainstream messengers route calls through their servers too — relay-first
+  is the privacy default, `promoteDirect` stays the opt-in). Builds entirely on shipped parts:
+  peer host + signal hub + media lines + `Media.attach*` viewers.
+- **Store-descriptor media bridge** ("streaming center") — the store carries a small descriptor
+  (`{kind: 'video', sourceId, state}`), a bridge watches the mirror and auto-attaches/detaches
+  `Media.attachVideoCanvas`/`attachAudioPlayer` to the matching binary line. Bytes flow only while
+  subscribed (native Listen-over-RPC semantics). Pairs with the React-hooks direction.
+- 🧊 **Zero-parse patch format** (super-far future) — Cap'n Proto / FlatBuffers-style layout for
+  store patches: fields read directly from the received buffer, no parse stage. Only if a real
+  consumer hits a serialization wall; JSON envelopes are nowhere near the bottleneck today
+  (measured 2-3ms e2e on the stand).
 
 ## 1. Connection hand-off — relay ↔ direct promotion ("port forwarding") 🟡
 

package/doc/changes/1.0.71.md

@@ -0,0 +1,9 @@
+# 1.0.71
+
+- Publish-path reconnect correctness for the Peer SDK: the relay journal never lies after a publisher gap.
+- `Peer.createPatchRelayJournal({gap: 'resume' | 'sacred'})` — the server declares journal semantics: `'resume'` (default) folds a keyframe and takes a ROOT patch as the one legitimate reset point; `'sacred'` never invents (no folded keyframe, no root reset, strict contiguity, `frame()` throws on an evicted tail).
+- `push()` now returns `true | false | {seq}` — a rejected gap carries the relay's last seq, and that coordinate IS the repair request (self-healing protocol, no separate handshake); duplicates are idempotent no-ops; a non-root FIRST envelope is rejected (a partial-state fold would lie to late joiners); rejection never corrupts the fold.
+- `Peer.createPeerClient`: rejection-driven repair — `repair: 'tail'` (missed envelopes verbatim, keyframe fallback on local eviction) or `'keyframe'` (one cheap root reset for ephemeral state); `journal: 'sacred'` narrows `repair` to `'tail'` at the TYPE level (`tPublishRepair<J>`) — incompatible asks are forbidden by typing, not runtime checks, and a lying client just keeps getting rejections, loudly via `onPublishError`.
+- `client.resync()` — call after a transport reconnect: compares the relay's `seq()` (additive on the wire) with the local line and repairs the gap without waiting for the next write.
+- Add oracle `replay/peer-repair.test.ts`: full gap matrix (folding + sacred), both repair modes over a lossy transport, sacred local-eviction fault surfacing, `resync()`.
+- Media sources: `replay` now also accepts custom `ReplayListenUseOptions` (`replay: {history, current, frame}`), not just `true`; defaults stay per-kind (audio — sacred queue `history:1024`, video — keep-latest `history:256`).

package/doc/changes/1.0.72.md

@@ -0,0 +1,6 @@
+# 1.0.72
+
+- Media video sources survive hidden/occluded tabs (Chrome throttling). Three measured stalls, three escape hatches, all on by default (`worker: false` opts out): capture tick moves from `setInterval` (~1/s hidden) to a Blob-worker timer; frames come from `ImageCapture.grabFrame()` (a hidden `<video>` stops painting); JPEG encode moves into a worker with a transferred `ImageBitmap` (main-thread `convertToBlob` is gated to ~1000ms hidden, ~5-10ms in the worker). Measured result: a hidden tab streams a stable ~16fps instead of decaying to 1fps after ~30s.
+- Demo stand: live media — camera, microphone and screen share, captured with the public `Media` sources and streamed between the two tabs. Screen share uses the documented `stream` injection point (`createVideoSource({stream: () => getDisplayMedia(...)})`); the demo server grows a tiny relay of per-account replay lines next to `peer.fragment` (video keep-latest, audio short queue, watched account declared via `auth.watch`, frames ride with a `sentAt` wall-clock stamp).
+- Demo client: capture toggles + per-second tx/rx rates and publish->receive latency in the stats line (`rx: cam Nf/Nd 16/s ~3ms`), peer camera/screen on canvases, peer mic through a sequential-playhead PCM player that drops >350ms backlog (live beats lossless for a call-like demo). Mic capture uses `worker:false, bufferSize:4096` — big PCM chunks instead of ~375 socket messages/s.
+- Docs: screen-share recipe + hidden-tab capture note in the Media section; README demo line mentions the media part.

package/doc/changes/1.0.73.md

@@ -0,0 +1,6 @@
+# 1.0.73
+
+- Media viewer helpers — the consumer side of a media line in one call (`media-view`, additive): `Media.attachVideoCanvas(line, canvas)` (header-driven codec/size, busy-skip keep-latest, `stats()` with frames/drawn/perSec/ageMs), `Media.attachAudioPlayer(line, {maxBacklogSec})` (sequential-playhead PCM, live backlog drop, gesture-gated `enable()`), `Media.pipeMediaPublish(line, publish, {stamp})` (fire-and-forget publish pipe; the `Date.now()` stamp feeds viewer latency stats). DI for tests: `createBitmap` / `audioContext` injection points.
+- Demo stand client rewired onto the helpers — the hand-written viewer plumbing (~90 lines of JPEG decode, PCM playhead, counters) collapses into one call per channel; behavior verified live (cam 30/s ~3ms, mic 12/s ~2ms, zero drops).
+- Route hand-off under media load verified on the live stand: relay -> direct (real ICE/SDP) -> relay while camera + mic stream; zero errors, media rates/latency untouched through both switches (media rides the socket relay; peer-store routes are per-direction by design).
+- Export `Media.toBytes` (binary view normalizer used by the helpers).

package/doc/wenay-common2-rare.md

@@ -223,9 +223,16 @@ Audio source:
 - `getStats().rms` gives a VU-meter signal; permission denied/no device returns typed state, not a thrown public failure.
 
 Video source:
-- default snapshots, not a 30fps video stream: `video->canvas`, JPEG, `fps` default 3, `quality` default 0.82.
+- default snapshots, not a 30fps video stream: JPEG, `fps` default 3, `quality` default 0.82.
 - each frame carries absolute image bytes, so `replay:true` can safely keep the latest frame for lag recovery.
-- `worker` is API-reserved; current implementation stays main-thread. Any future worker path must transfer `ArrayBuffer` payloads, never structured-clone frame objects.
+- capture is hidden-tab-proof by default (Chrome throttles hidden tabs three ways, each stage has its own escape): the tick comes from a Blob-worker timer (in-page `setInterval` drops to ~1/s), the frame comes from `ImageCapture.grabFrame()` when available (a hidden `<video>` stops painting; `<video>->canvas` stays as the fallback), and JPEG encode runs in a worker over a transferred `ImageBitmap`, returning a transferred `ArrayBuffer` — never a structured-cloned frame (main-thread `convertToBlob` is gated to ~1s per call when hidden). `worker: false` opts out of all three into the plain in-page path.
+- one explicit dimension (`width` or `height`) scales the other proportionally from the track resolution, downscale-only; pass both to force an exact size. `grabFrame`'s ~50ms serial latency caps the pipeline around ~15-20fps regardless of `fps`.
+
+Viewer helpers (`media-view`): the consumer side of any media line (local pair or RPC surface).
+- `attachVideoCanvas(line, canvas, {createBitmap?, onError?})` — per-frame codec/size come from the 40-byte header, canvas resizes to follow; decode overload is busy-skipped (keep-latest, `stats().frames` vs `stats().drawn` shows the gap); `createBitmap` injects a custom decoder (tests, OffscreenCanvas pipelines).
+- `attachAudioPlayer(line, {maxBacklogSec? = 0.35, audioContext?, onError?})` — pcm16/float32 through a sequential playhead; a backlog past `maxBacklogSec` is dropped and the playhead rebases near "now" (live beats lossless; `stats().dropped` counts rebases). `enable()` must come from a user gesture (browser autoplay rules); `audioContext` injects a factory for tests/custom routing.
+- `pipeMediaPublish(line, publish, {stamp? = true, onError?})` — fire-and-forget pipe into an RPC call; the default `Date.now()` stamp is what viewer `stats().ageMs` measures against. Both attach helpers also expose `stats().perSec` (rolling 1s rate).
+- Oracle: `replay/media-view.test.ts`.
 
 Replay/RPC wiring:
 ```ts
@@ -529,13 +536,27 @@ 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.
+Peer.createPatchRelayJournal({history?, gap?: 'resume'|'sacred'}) -> {push(env) -> true|false|{seq}, remote, gap, seq(), snapshot(), close()}
+  // server-side mirror of an OWNER-sequenced patch line: push() takes the owner's envelopes VERBATIM.
   //   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).
+  // CORRECTNESS CONTRACT (gap = the SERVER's data-type decision):
+  //   'resume' (default, folding): keyframe folded server-side (late joiners never need the owner online);
+  //     a ROOT patch always resets the journal (owner restart AND keyframe repair share one rule); a
+  //     non-root envelope with a seq gap — and a non-root FIRST envelope (partial-state lie) — is
+  //     REJECTED as {seq: N}: that coordinate IS the repair request, no separate handshake exists.
+  //   'sacred': the journal never invents — no folded keyframe, no root-reset, strict contiguity only;
+  //     frame() on an evicted tail THROWS. For data where an invented snapshot is unacceptable.
+  //   Duplicates (reconnect/repair overlap) are idempotent no-ops. Rejection never corrupts the fold.
+  //   remote is ReplayRemote-shaped (+ additive `seq()` for publisher resync) 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).
+  // Publisher side (createPeerClient): {journal?: 'resume'|'sacred', repair?: 'tail'|'keyframe',
+  //   onPublishError?, resync()}. 'tail' = missed envelopes verbatim (falls back to a root keyframe if
+  //   the local journal evicted them — resume only); 'keyframe' = one cheap root reset (ephemeral state).
+  //   TYPE RULE, not a runtime check: journal:'sacred' narrows repair to 'tail' (tPublishRepair<J>) —
+  //   lie about the journal kind and the relay simply keeps rejecting you (loud via onPublishError).
+  //   resync() = call after transport reconnect: compares relay seq() with the local line, repairs the
+  //   gap without waiting for the next write. Oracle: replay/peer-repair.test.ts (full gap matrix).
   // 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

package/doc/wenay-common2.md

@@ -151,8 +151,13 @@ Media.createAudioSource({format?: 'int16'|'float32', mode?: 'pcm'|'record', repl
 Media.createVideoSource({fps? = 3, codec? = 'jpeg', quality?, replay?}) -> [emit, listen] & control
 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
+
+// viewer/publisher one-liners (the demo stand is built on these):
+Media.attachVideoCanvas(line, canvas, {onError?}) -> {stats(), off}       // decode+render any video line; codec/size come from frame headers
+Media.attachAudioPlayer(line, {maxBacklogSec? = 0.35}) -> {enable(), disable(), enabled, stats(), off}   // live PCM playback, backlog drops
+Media.pipeMediaPublish(line, publish, {stamp? = true, onError?}) -> off   // source -> RPC publish fn; stamp lets viewers measure latency
 ```
-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 (JPEG, low fps for vision) captured hidden-tab-proof: a worker timer ticks (setInterval is throttled to ~1/s in hidden tabs), `ImageCapture.grabFrame()` reads the track (a hidden `<video>` stops painting), and JPEG encode runs in a worker (main-thread `convertToBlob` stalls ~1s hidden) — `worker:false` opts back into the plain in-page path. Screen share is the same video source with an injected stream: `createVideoSource({stream: () => navigator.mediaDevices.getDisplayMedia({video: true})})`. 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. Living example: the demo stand (`npm run demo`) streams camera / mic / screen share between two tabs through a tiny server-side relay of replay lines (`demo/server.ts` + `demo/client.ts`).
 
 ## 🤝 Peer — accounts see each other's stores (one-call SDK)
 > `import { Peer } from "wenay-common2"` or `import * as Peer from "wenay-common2/peer"`.
@@ -185,7 +190,13 @@ 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:
+get a keyframe folded server-side even while the owner is offline.
+Reconnect correctness is self-healing: a publisher gap makes the relay reject the push WITH its last
+seq, and the client repairs from that coordinate automatically (`repair: 'tail'` lossless (default)
+| `'keyframe'` cheap reset for ephemeral state). Server declares journal semantics
+(`createPeerHost({gap: 'resume' | 'sacred'})`); a declared `journal: 'sacred'` TYPE-forbids the cheap
+repair. `me.resync()` after a transport reconnect repairs without waiting for the next write;
+failures surface via `onPublishError`, never silently. 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`.

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

@@ -1 +1,2 @@
 export * from './media-source';
+export * from './media-view';

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

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./media-source"), exports);
+__exportStar(require("./media-view"), exports);

package/lib/Common/media/media-source.d.ts

@@ -14,6 +14,7 @@ export type MediaReplayOpts = true | ReplayListenUseOptions<[Uint8Array]>;
 export type AudioSourceOpts = {
     sourceId?: string;
     deviceId?: string;
+    stream?: any;
     mode?: 'pcm' | 'record';
     format?: 'int16' | 'float32';
     channels?: number;
@@ -28,6 +29,7 @@ export type AudioSourceOpts = {
 export type VideoSourceOpts = {
     sourceId?: string;
     deviceId?: string;
+    stream?: any;
     fps?: number;
     width?: number;
     height?: number;
@@ -88,6 +90,7 @@ export type DecodedMediaFrame = MediaFrameMeta & {
 export declare const MEDIA_FRAME_MAGIC = 1464028466;
 export declare const MEDIA_FRAME_VERSION = 1;
 export declare const MEDIA_FRAME_HEADER_BYTES = 40;
+export declare function toBytes(data: ArrayBuffer | ArrayBufferView): Uint8Array<ArrayBufferLike>;
 export declare function encodeMediaFrame(meta: MediaFrameMeta, payload: ArrayBuffer | ArrayBufferView): Uint8Array<ArrayBuffer>;
 export declare function decodeMediaFrame(frameLike: ArrayBuffer | ArrayBufferView): DecodedMediaFrame;
 export declare function createAudioSource(opts?: AudioSourceOpts): MediaSource;