wenay-common2 1.0.64 → 1.0.66

package/CLAUDE.md

@@ -51,6 +51,26 @@ Write new code in this style by default — no need to ask.
 ## Comments
 - Section dividers like `// ===...===` with a block heading.
 - Explain "why", not "what". Keep them short.
+
+## Work progress files
+
+- For any task that is more than a tiny/local edit, create a temporary progress file before
+  starting broad changes.
+- Put progress files under `doc/progress/`. This is the working-doc area, separate from public
+  API docs, roadmap docs, and release notes.
+- Name them by task, for example `doc/progress/replay-route-handoff.md`.
+- Keep the file short: goal, current checkpoint list, notable decisions, blockers, and verification
+  already run or still needed.
+- Update the progress file as checkpoints are completed, especially before switching context or
+  making broad edits.
+- When the task is finished, delete the progress file. Preserve only the durable outcome:
+  final response, commit message, and, for publishable changes, the matching `doc/changes/<version>.md`
+  entry.
+- If work is paused or blocked locally, leave the progress file in place and make the next required
+  action explicit. If the paused state must be committed or handed off, promote the useful part into
+  a durable doc (`ROADMAP`, `RECOMMENDATIONS`, `doc/target`, or `doc/changes`) instead of relying on
+  an ignored progress file.
+
 ## Documentation and release notes
 
 - `README.md` is navigation only. Do not put API guides, examples, or long explanations there.

package/doc/REPLAY-PLAN.md

@@ -75,7 +75,11 @@ For seek into the past — not needed for live sync:
 ## Stages
 
 1. `withReplayListen` decorator + seq handover (layer A) — the core, small.
-2. Patch journal in `exposeStore` + `since`-sync in mirror (layer B).
+2. Patch journal in `exposeStore` + `since`-sync in mirror (layer B).
+2.5. **Route hand-off helper** — `replayRouteSubscribe` / `syncStoreReplayRoute`: keep the
+   old route live, catch up the replacement from the last delivered `seq`, then close the old
+   route. This is the replay-level foundation for relay ↔ direct promotion; signaling and
+   direct-transport setup remain outside this layer.
 3. Conflation + snapshot recovery on the wire (first item of D) — this is what turns
    "semi-pro" into pro for fan-out.
 4. C and the rest of D — on demand.

package/doc/ROADMAP.md

@@ -0,0 +1,190 @@
+# wenay-common2 — Roadmap (open / deferred)
+
+> Forward-looking backlog of distributed-state / transport features that are **not fully built**.
+> Everything here sits on top of the existing seams — `{emit,on}` transport, `exposeStore` /
+> `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.
+
+## 0. Distributed Runtime Model
+
+The strategic direction is not "RPC plus store helpers"; it is a small distributed-state runtime:
+application code keeps a stable typed API while lower layers can choose the transport, route, replay
+source, and authority model.
+
+Four concerns must stay explicit:
+
+- **Transport** - how two endpoints exchange `{emit,on}` messages: socket.io, in-process loopback,
+  relay, WebRTC/direct channel, or a future adapter. Transport is replaceable infrastructure.
+- **Routing** - where a logical call or stream goes: server, peer through relay, peer directly, or a
+  promoted relay <-> direct path. Routing must be allowed to change without changing the facade API.
+- **Authority** - who is allowed to write truth: one server, partitioned peer-owned slices, server
+  authority with client prediction, or true multi-writer conflict resolution. This is a semantic
+  decision, not a transport decision.
+- **Replay** - how live state survives reconnect, lag, transport swap, and history playback:
+  `seq` + keyframe/frame + deltas. Replay is the continuity layer that makes route changes boring.
+
+Design rule: direct peer links and relay hand-offs are optimizations of transport/routing. They must
+not silently change auth, ownership, validation, or conflict semantics. If a method is exposed as
+`api.hit(playerId)`, it may travel through the server or a direct channel, but the authority rules
+behind that method must remain the same.
+
+This implies a useful split:
+
+- **API surface** remains facade-shaped and typed.
+- **Transport/routing layer** may substitute sockets and promote paths.
+- **Replay layer** resumes streams and mirrors from the last known `seq`.
+- **Authority layer** decides whether an incoming write is accepted, predicted, reconciled, or merged.
+
+Critical ordering rule: do **not** start with WebRTC/NAT plumbing or CRDTs. The next useful layer is a
+small route/account/policy coordinator with a fake/in-process transport adapter. Direct transport and
+multi-writer merge are expensive adapters; they only become safe after the coordinator state machine is
+boring and well-tested.
+
+### 0.1 Account route coordinator ("wrapper over wrappers") 🔴
+
+Some deployments need separate client/account identities to communicate directly when policy and
+network conditions allow it, while still allowing the server/relay to step back into the path later.
+This is not just a socket trick; it is an account-aware routing shell above the existing facade,
+mirror, and replay primitives.
+
+- **Account model:** every participant has its own account/session identity and a scoped facade/store
+  set. Runtime-account maps are a dynamic keyspace, so they should look like `noStrict(accountMap)`
+  rather than a fixed schema. Access checks stay in the facade/policy layer; `noStrict` is not an ACL.
+- **Wrapper over wrappers:** an app-level coordinator owns the set of per-account clients, exposed
+  facades, mirrors, replay subscriptions, and route state. "State of other accounts" is represented as
+  selected `Observe` mirrors/replay/offline resources, ideally started and stopped through
+  `createStoreManager`, not as a new global store core.
+- **Route states:** a pair of accounts may be `relay`, `direct`, `direct+shadowRelay` (audit/observe
+  copy), `blocked`, or `fallback`. Direct links are optional optimizations, useful for latency or
+  traffic cost, not a semantic change.
+- **Re-interposition:** if NDA/privacy policy, audit, moderation, throttling, reauth, direct-link
+  failure, or group topology changes require it, the relay must be able to re-enter the data path.
+  This is the reverse of direct promotion: open the replacement route, resume from the last `seq`,
+  switch consumers after catch-up, then close or demote the old route.
+- **Privacy rule:** direct account links are opt-in and policy-gated. Peers only receive the endpoint
+  and session material needed for that specific relationship; no implicit broad account discovery.
+
+Concrete next API shape, not final names:
+
+```ts
+createRouteCoordinator({
+  policy,
+  routes,
+  resources,
+}) -> {
+  pair(a, b),
+  state(pair),
+  promoteDirect(pair, opts?),
+  reinterposeRelay(pair, reason?),
+  block(pair, reason?),
+  fallback(pair, reason?),
+  onRoute(cb),
+}
+```
+
+Policy must run **before** transport promotion:
+
+- `canDirect(pair, ctx)` - may these accounts attempt direct at all?
+- `mustRelay(pair, ctx)` - force relay path because of NDA/audit/moderation/reauth.
+- `mustShadowRelay(pair, ctx)` - allow direct payload path, but keep audit/observe copy.
+- `canExposeEndpoint(pair, ctx)` - whether signaling may reveal endpoint/session material.
+- `canReinterpose(pair, ctx)` - whether/when relay is allowed or required to step back in.
+
+Minimum state machine:
+
+- `relay` -> `direct:connecting` -> `direct` -> `relay:reinterposing` -> `relay`
+- `relay` -> `direct:connecting` -> `fallback` -> `relay`
+- `direct` -> `direct+shadowRelay`
+- any state -> `blocked`
+
+Required failure modes:
+
+- direct setup never completes: keep relay active and mark fallback;
+- replacement route catches up too slowly: keep old route active and fail the switch;
+- policy changes mid-stream: re-interpose relay through replay hand-off;
+- account reauth changes facade/ACL: rebuild route policy before accepting new writes;
+- endpoint/session material is revoked: close direct and resume relay from `seq`;
+- audit/shadow route lags: decide whether to throttle, fallback, or block by policy.
+
+Acceptance tests for 0.1:
+
+- policy denial: direct is never attempted;
+- direct promotion: old relay stays live until replacement catches up;
+- failed direct: old relay continues with no data gap;
+- re-interposition: direct -> relay resumes from `seq`;
+- `direct+shadowRelay`: direct path is active while relay/audit mirror observes;
+- revocation: direct closes and relay resumes without changing facade API;
+- account map uses `noStrict`, but all access checks live in policy/facade code;
+- `createStoreManager` starts/stops selected per-account mirrors without store-core changes.
+
+Open questions: exact policy object shape; signaling envelope; whether the relay sees payloads or only
+coordinates encrypted direct streams; app-facing route-state events; backpressure across multi-hop and
+direct paths; group topology beyond a pair of accounts.
+
+Status: 🔴 not started. This belongs to project-0 architecture: no store-core change, but it defines
+the account/routing shell that later direct-connection work plugs into. This is the next important
+roadmap item; WebRTC and CRDT work should wait until this state machine is proven with fake transports.
+
+## 1. Connection hand-off — relay ↔ direct promotion ("port forwarding") 🟡
+
+A relay/intermediary bootstraps a connection between two parties, then — on a signal — **steps out
+of the middle**: both ends open a second, direct socket and migrate the live stream onto it,
+bypassing the relay. The same mechanism must work in reverse: the relay can deliberately
+**re-interpose** and become the middleman again. Under the hood the socket substitutes itself; data
+starts flowing on the new path.
+
+- Family: NAT hole-punching / WebRTC TURN→direct promotion, expressed over the existing `{emit,on}`
+  abstraction rather than a specific transport.
+- **Design lead (reuse what exists):** the socket swap is a *stream resume*, which the replay layer
+  already solves. Migrate with `replaySubscribe(..., {since: prev.seq()})` /
+  `syncStoreReplay(..., {since})` on the new socket — the consumer fold is gap-free by contract, so a
+  mid-stream transport change is not a special case. The transport carries only `seq`; the semantics
+  never learn the socket changed.
+- **Implemented foundation (2026-07-08):** `Replay.replayRouteSubscribe(...)` and
+  `Observe.syncStoreReplayRoute(...)` keep the old route alive, subscribe the replacement route,
+  catch it up from the last delivered `seq`, then close the old route. This covers relay → direct
+  promotion and direct → relay re-interposition for any ordered `ReplayRemote`; overlap is deduped by
+  `seq`, and a failed replacement leaves the old route active.
+- Open questions: signaling channel that negotiates the direct endpoint; fallback if the direct path
+  never establishes (stay on relay); auth continuity across the swap; per-socketKey vs whole-connection
+  hand-off; policy trigger and catch-up boundary for direct → relay re-interposition.
+- Status: 🟡 partial. Route hand-off/resume helper is implemented and covered by `replay/route-handoff.test.ts`; signaling, direct endpoint negotiation, NAT/WebRTC adapter, auth-continuity policy, and trigger rules remain open.
+
+## 2. Coordinated fan-out send to a large group 🧊
+
+Synchronized/batched send to a very large audience "at once", as opposed to the current model where
+**each connection is paced independently** (per-connection lag gate + `frame` policy).
+
+- Current reality: pacing is per-recipient by design — every client's link is unique. Even in video
+  fan-out no two receivers drain at the same rate, so the per-connection gate is usually the *correct*
+  answer. That is why this is shelved.
+- When it would matter: true lockstep broadcast (all-or-nothing / same-instant delivery) — rare.
+- Status: 🧊 deliberately shelved. Revisit only against a concrete lockstep requirement.
+
+## 3. Multi-authority stores — two truths, one reconciliation (games) 🔴
+
+Two stores, each **dynamically filled by its own authority ("truth")**, that must agree on a shared
+source of truth. Decompose by write topology:
+
+- **Partitioned authority — fits today.** Each peer authoritative over its own slice → two
+  `exposeStore` / `createStoreMirror` pairs crossed over one duplex `{emit,on}`. No new primitive.
+  "Confirmation" = the per-direction `seq` ack.
+- **Authoritative server + client prediction — small layer on top.** Server store is the truth; the
+  client applies optimistically, then reconciles when the authoritative patch arrives. Build a
+  `predictedStore` = confirmed mirror + a pending-input list, rebased on each `mirror.each()` /
+  `changed` tick. Helper factory, not a core change.
+- **Symmetric co-write of the same path — needs a different model.** LWW-per-path converges but can
+  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.
+
+## 4. Data-transfer optimization backlog (ongoing) 🟡
+
+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.

package/doc/changes/1.0.65.md

@@ -0,0 +1,8 @@
+# 1.0.65
+
+- Add `Replay.replayRouteSubscribe` for transport-agnostic replay route hand-off: keep the old route live, catch up the replacement route by `seq`, then close the old route.
+- Add `Observe.syncStoreReplayRoute` for store mirrors that can switch relay/direct routes without gaps or duplicate patch delivery.
+- Add `replay/route-handoff.test.ts` covering relay -> direct promotion, direct -> relay re-interposition, failed replacement fallback, and store mirror convergence.
+- Update roadmap/replay docs to mark connection hand-off as partially implemented and keep signaling/WebRTC/policy triggers explicitly open.
+- Normalize package metadata for `wenay-common2@1.0.65`.
+- Add `doc/progress/` working-checkpoint rules for non-trivial tasks and keep task progress files out of package output.

package/doc/changes/1.0.66.md

@@ -0,0 +1,8 @@
+# 1.0.66
+
+- Add `Media.createAudioSource` and `Media.createVideoSource` browser capture helpers that expose media as ordinary binary `Listen` sources.
+- Add fixed-header media frame helpers: `Media.encodeMediaFrame` and `Media.decodeMediaFrame` (`Uint8Array` header + raw payload, no JSON envelope).
+- Add optional `replay:true` media source mode so `createRpcServerAuto` can expose media listeners with legacy + replay surfaces under the same key.
+- Add `wenay-common2/media` package export and root `Media` namespace export.
+- Add `replay/media-socket.test.ts` covering media binary frame headers, no-device typed state, replay media source shape, and real Socket.IO/RPC binary delivery.
+- Document media-over-socket backpressure defaults and reserve WebRTC as a future explicit SFU/signaling opt-in, not the default transport.

package/doc/wenay-common2-rare.md

@@ -205,6 +205,50 @@ Contract:
 - Static dotted keys are also supported: `api["a.b"].c` is distinct from `api.a.b.c`. Internal route/listen/cache identity must stay lossless; dotted strings are only a debug display form.
 - If a branch is a fixed public API, keep it strict. If a branch is a personal/dynamic keyspace, wrap that branch in `noStrict` instead of trying to publish all current keys as schema.
 
+## 🎙️ Media over socket — browser capture as binary Listen
+> `import { Media } from "wenay-common2"` or `import * as Media from "wenay-common2/media"`.
+> The hot path event is ONE `Uint8Array`: fixed 40-byte common2 media header + raw payload. No JSON envelope.
+```
+Media.createAudioSource(opts?) -> [emit, listen] & control
+Media.createVideoSource(opts?) -> [emit, listen] & control
+Media.encodeMediaFrame(meta, payload) -> Uint8Array
+Media.decodeMediaFrame(frame) -> {kind, codec, seq, tMono, payload, sampleRate?, channels?, nSamples?, width?, height?}
+
+control: start() -> Promise<MediaSourceState> · stop() · getStats() · setDevice(id) · listDevices()
+state: 'idle'|'requesting'|'live'|'denied'|'no-device'|'error'
+```
+Audio source:
+- default `mode:'pcm'`, `format:'int16'`, raw PCM payload; uses `AudioWorklet` when available and falls back to `ScriptProcessor` only when the browser cannot run a worklet.
+- `mode:'record'` uses `MediaRecorder` chunks (`webm-opus`) for record/upload flows, not live STT.
+- `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.
+- 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.
+
+Replay/RPC wiring:
+```ts
+const audio = Media.createAudioSource({sourceId: 'mic'})                 // plain lossless queue Listen
+const video = Media.createVideoSource({sourceId: 'cam', fps: 2, replay: true})
+
+createRpcServerAuto({
+    socket, socketKey: 'media',
+    object: {audio: audio[1], video: video[1]},
+    replayOpts: {highWater: 64, lowWater: 8},
+})
+```
+`replay:true` makes the returned listen a `Replay.replayListen` surface before capture emits into it, so `createRpcServerAuto` brand-detects it and exposes legacy + replay under the same key. Defaults differ by media kind: audio replay is a sacred queue (`history:1024`, no keyframe/frame, do not drop samples); video replay is keep-latest (`history:256`, `current:'last'`, `frame` returns the newest covered frame). Pass `replay:{...}` for custom history/current/frame.
+
+Backpressure rule: audio consumers should use the default queue policy unless the app explicitly accepts loss. Video consumers can use `Replay.replaySubscribe(remote.video, cb, {policy:'frame'})`; a slow socket drains to the latest frame instead of accumulating stale images. The binary frame itself is RPC-safe because `rpc-walk` passes `TypedArray`/`ArrayBuffer` leaves through natively and applies `maxBinaryLen`.
+
+WebRTC future contract:
+- `transport:'socket'` is the implemented default today.
+- `transport:'webrtc'` is reserved and currently reports `state:'error'` on `start()`; it is not a hidden second transport.
+- Future WebRTC support must be explicit opt-in for sub-200ms human duplex. Signaling belongs on the existing socket/RPC control channel (offer/answer/ICE), and backend/AI access requires an SFU that re-emits media bytes into the same `Media` Listen/replay surface. Downstream RPC/replay/store consumers must not change.
+
+Oracle: `npx ts-node replay/media-socket.test.ts` checks header decode, plain Listen shape, `replay:true`, typed no-device state in Node, and real Socket.IO binary delivery.
+
 ## 📈 exchange — params (`CParams`)
 ```
 class CParams / CParamsReadonly implements IParams
@@ -420,7 +464,9 @@ exposeReplay(replay)  <->  replaySubscribe(remote, cb, {since?, onSeq?, staleMs?
   //   on the line (RPC_STOP — e.g. the gate's loud sacred failure) surfaces via onError + off, never silence.
   //   hint reaches the frame lambda on catch-up and on every explicit frame(seq, hint) call (pull); the push-gate's
   //   drain recovery uses the line's DEFAULT condensation — client-specific rules/pace = the pull path.
-  // off.ready (catch-up done) · off.seq() (reconnect point) · off.isStale()/off.lastTs(); reconnect = call again with {since: prev.seq()}
+  // off.ready (catch-up done) · off.seq() (reconnect point) · off.isStale()/off.lastTs(); reconnect = call again with {since: prev.seq()}
+replayRouteSubscribe(remote, cb, {label?, since?, onSeq?, onError?, onRoute?}) -> off & {ready, switch(nextRemote, {label?, since?, reset?, policy?, hint?}), seq(), label(), active()}
+  // transport hand-off helper: old route remains live, replacement subscribes+catches up from seq, then old closes; overlap is seq-deduped. Use for relay -> direct and direct -> relay over any ordered ReplayRemote.
   // DELIVERY CONTRACT (guaranteed, not best-effort): the subscriber's cb sees ONE uniform stream —
   //   first delivery = the snapshot (keyframe as an event of the SAME type; store: root patch),
   //   then only strictly-newer events, seq-ascending, no gaps, no dups. Live events racing ahead of the
@@ -439,7 +485,8 @@ exposeReplay(replay)  <->  replaySubscribe(remote, cb, {since?, onSeq?, staleMs?
   //   of clock skew) + ENVELOPE-TS AGE checked at delivery (producer clock — a stale keyframe reports stale
   //   IMMEDIATELY; clock-skew caveat: producer/client clocks may disagree, skewMs tolerance absorbs it, default 0).
   //   A since-tail's historical ts never flaps mid-catch-up (one assessment after handover); off() disarms the timer.
-exposeStoreReplay(store, opts?)  <->  syncStoreReplay(mirror, remote, opts?)            // layer B: patch line; keyframe = root patch ({path: [], value: snapshot})
+exposeStoreReplay(store, opts?)  <->  syncStoreReplay(mirror, remote, opts?)            // layer B: patch line; keyframe = root patch ({path: [], value: snapshot})
+syncStoreReplayRoute(mirror, remote, opts?) -> off & {ready, switch(nextRemote, opts), seq(), label(), active()}   // same patch fold, but route-replaceable for relay/direct promotion
 syncStoreReplayEach<T>(remote, cb, opts?) -> off & {store, ready, seq(), isStale(), lastTs()}   // one-call per-key fold over the patch line (mirror + syncStoreReplay + store.each()); most-used surface — full contract + example in wenay-common2.md
 createOfflineStore({key, remote?, initial, storage, version?, debounceMs?, syncOpts?}) -> Promise<OfflineStore<T>>
   // snapshot-mode persisted mirror: read local {version,seq,snapshot,savedAt}, create a normal Store immediately,

package/doc/wenay-common2.md

@@ -136,11 +136,24 @@ 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 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
 ```
 
+## 🎙️ Media over socket — binary Listen frames
+```
+import { Media } from "wenay-common2"        // or: import * as Media from "wenay-common2/media"
+
+Media.createAudioSource({format?: 'int16'|'float32', mode?: 'pcm'|'record', replay?}) -> [emit, listen] & control
+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
+```
+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.
+
 ## 🔁 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.
@@ -186,7 +199,9 @@ 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)
+  // 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
   //   top-level key; first delivery = keyframe EXPANDED per key; (key, undefined) = key deleted

package/lib/Common/Observe/store-replay.d.ts

@@ -1,6 +1,7 @@
 import { Store, StorePatch, StoreDrain, StoreEachCtx } from './store';
 import { ReplayListenOptions, ReplayEvent } from '../events/replay-listen';
 import { ReplayRemote, ReplaySubscribeOpts } from '../events/replay-wire';
+import { ReplayRouteSubscribeOpts } from '../events/replay-route';
 import { ReplayStorage } from '../events/replay-history';
 export type StoreReplayOpts = Pick<ReplayListenOptions<[StorePatch]>, 'history' | 'getSince' | 'onJournal' | 'now'>;
 export declare function storePatchKey(patch: StorePatch): string | null;
@@ -48,6 +49,13 @@ export declare function syncStoreReplay<T extends object>(store: Store<T>, remot
     isStale: () => boolean;
     lastTs: () => number;
 };
+export declare function syncStoreReplayRoute<T extends object>(store: Store<T>, remote: ReplayRemote<[StorePatch]>, opts?: ReplayRouteSubscribeOpts): (() => void) & {
+    ready: Promise<void>;
+    switch: (nextRemote: ReplayRemote<[StorePatch]>, nextOpts?: import("../events/replay-route").ReplayRouteSwitchOpts) => Promise<void>;
+    seq: () => number;
+    label: () => string | undefined;
+    active: () => boolean;
+};
 export declare function syncStoreReplayEach<T extends object>(remote: ReplayRemote<[StorePatch]>, cb: (key: string, value: T[keyof T] | undefined, ctx: StoreEachCtx) => void, opts?: ReplaySubscribeOpts & {
     drain?: StoreDrain;
     initial?: T;

package/lib/Common/Observe/store-replay.js

@@ -3,11 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.storePatchKey = storePatchKey;
 exports.exposeStoreReplay = exposeStoreReplay;
 exports.syncStoreReplay = syncStoreReplay;
+exports.syncStoreReplayRoute = syncStoreReplayRoute;
 exports.syncStoreReplayEach = syncStoreReplayEach;
 exports.storeReplayAt = storeReplayAt;
 const store_1 = require("./store");
 const replay_listen_1 = require("../events/replay-listen");
 const replay_wire_1 = require("../events/replay-wire");
+const replay_route_1 = require("../events/replay-route");
 const replay_history_1 = require("../events/replay-history");
 function makeStorePatch(store, path) {
     let node = store.node;
@@ -55,6 +57,9 @@ function exposeStoreReplay(store, opts = {}) {
 function syncStoreReplay(store, remote, opts = {}) {
     return (0, replay_wire_1.replaySubscribe)(remote, function applyLine(patch) { (0, store_1.applyStorePatch)(store, patch); }, opts);
 }
+function syncStoreReplayRoute(store, remote, opts = {}) {
+    return (0, replay_route_1.replayRouteSubscribe)(remote, function applyRoutePatch(patch) { (0, store_1.applyStorePatch)(store, patch); }, opts);
+}
 function syncStoreReplayEach(remote, cb, opts = {}) {
     const { drain, initial, ...wireOpts } = opts;
     const store = (0, store_1.createStore)((initial ?? {}), drain !== undefined ? { drain } : {});

package/lib/Common/events/replay-index.d.ts

@@ -2,3 +2,4 @@ export * from './replay-listen';
 export * from './replay-wire';
 export * from './replay-conflate';
 export * from './replay-history';
+export * from './replay-route';

package/lib/Common/events/replay-index.js

@@ -18,3 +18,4 @@ __exportStar(require("./replay-listen"), exports);
 __exportStar(require("./replay-wire"), exports);
 __exportStar(require("./replay-conflate"), exports);
 __exportStar(require("./replay-history"), exports);
+__exportStar(require("./replay-route"), exports);

package/lib/Common/events/replay-route.d.ts

@@ -0,0 +1,25 @@
+import { Listener } from './Listen';
+import { ReplayRemote, ReplaySubscribeOpts } from './replay-wire';
+export type ReplayRoutePhase = 'switching' | 'ready' | 'error' | 'closed';
+export type ReplayRouteEvent = {
+    phase: ReplayRoutePhase;
+    seq: number;
+    from?: string;
+    to?: string;
+    error?: unknown;
+};
+export type ReplayRouteSwitchOpts = Pick<ReplaySubscribeOpts, 'policy' | 'hint'> & {
+    label?: string;
+    since?: number;
+    reset?: boolean;
+};
+export type ReplayRouteSubscribeOpts = ReplayRouteSwitchOpts & Pick<ReplaySubscribeOpts, 'onSeq' | 'onError'> & {
+    onRoute?: (ev: ReplayRouteEvent) => void;
+};
+export declare function replayRouteSubscribe<Z extends any[]>(remote: ReplayRemote<Z>, cb: Listener<Z>, opts?: ReplayRouteSubscribeOpts): (() => void) & {
+    ready: Promise<void>;
+    switch: (nextRemote: ReplayRemote<Z>, nextOpts?: ReplayRouteSwitchOpts) => Promise<void>;
+    seq: () => number;
+    label: () => string | undefined;
+    active: () => boolean;
+};

package/lib/Common/events/replay-route.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.replayRouteSubscribe = replayRouteSubscribe;
+function unsubscribeHandle(handle) {
+    if (typeof handle == 'function') {
+        handle();
+        return;
+    }
+    if (typeof handle?.off == 'function')
+        handle.off();
+    else if (typeof handle?.unsubscribe == 'function')
+        handle.unsubscribe();
+}
+function replayRouteSubscribe(remote, cb, opts = {}) {
+    const { onSeq, onError, onRoute } = opts;
+    let lastDelivered = opts.since ?? -1;
+    let closed = false;
+    let active = null;
+    let currentLabel = opts.label;
+    let switchChain = Promise.resolve();
+    const slots = new Set();
+    function emitRoute(ev) {
+        if (!onRoute)
+            return;
+        try {
+            onRoute(ev);
+        }
+        catch (e) {
+            setTimeout(function rethrowRouteEvent() { throw e; }, 0);
+        }
+    }
+    function deliver(ev) {
+        if (closed || ev.seq <= lastDelivered)
+            return;
+        lastDelivered = ev.seq;
+        cb(...ev.event);
+        onSeq?.(ev.seq);
+    }
+    function deliverMany(envs, allowReset) {
+        if (allowReset && envs.length && envs[0].seq <= lastDelivered) {
+            lastDelivered = envs[0].seq - 1;
+        }
+        for (const ev of envs)
+            deliver(ev);
+    }
+    function attach(nextRemote, since, nextOpts, allowReset) {
+        const { policy = 'queue', hint, label } = nextOpts;
+        let slot;
+        let slotClosed = false;
+        let replaying = true;
+        let lineError;
+        const queue = [];
+        const liveLine = policy == 'frame' && nextRemote.frameLine ? nextRemote.frameLine : nextRemote.line;
+        const handle = liveLine.on(function liveTap(ev) {
+            if (slotClosed)
+                return;
+            if (ev == null || typeof ev.seq != 'number') {
+                lineError = new Error('replayRouteSubscribe: line ended by route (' + String(ev) + ')');
+                slot.close();
+                if (!replaying)
+                    onError?.(lineError);
+                return;
+            }
+            if (replaying)
+                queue.push(ev);
+            else
+                deliver(ev);
+        });
+        function closeSlot() {
+            if (slotClosed)
+                return;
+            slotClosed = true;
+            unsubscribeHandle(handle);
+            slots.delete(slot);
+        }
+        async function catchUp() {
+            try {
+                let done = false;
+                if (since >= 0 && nextRemote.frame) {
+                    const envs = await nextRemote.frame(since, hint);
+                    if (slotClosed)
+                        return;
+                    if (envs) {
+                        deliverMany(envs, allowReset);
+                        done = true;
+                    }
+                }
+                if (!done) {
+                    const tail = since >= 0 ? await nextRemote.since(since) : null;
+                    if (slotClosed)
+                        return;
+                    if (tail) {
+                        deliverMany(tail, false);
+                    }
+                    else {
+                        const kf = await nextRemote.keyframe();
+                        if (slotClosed)
+                            return;
+                        if (kf)
+                            deliverMany([kf], allowReset);
+                    }
+                }
+                if (lineError)
+                    throw lineError;
+                while (queue.length)
+                    deliver(queue.shift());
+                replaying = false;
+            }
+            catch (e) {
+                closeSlot();
+                throw e;
+            }
+        }
+        slot = {
+            label,
+            ready: catchUp(),
+            close: closeSlot,
+            closed: () => slotClosed,
+        };
+        slots.add(slot);
+        return slot;
+    }
+    async function doSwitch(nextRemote, nextOpts = {}, initial = false) {
+        if (closed)
+            throw new Error('replayRouteSubscribe: closed');
+        const from = active;
+        const fromLabel = from?.label ?? currentLabel;
+        const toLabel = nextOpts.label;
+        const since = nextOpts.since ?? lastDelivered;
+        const allowReset = nextOpts.reset ?? (initial || !from);
+        const slot = attach(nextRemote, since, nextOpts, allowReset);
+        emitRoute({ phase: 'switching', from: fromLabel, to: toLabel, seq: lastDelivered });
+        try {
+            await slot.ready;
+            if (closed || slot.closed())
+                return;
+            active = slot;
+            currentLabel = slot.label;
+            if (from && from !== slot)
+                from.close();
+            emitRoute({ phase: 'ready', from: fromLabel, to: toLabel, seq: lastDelivered });
+        }
+        catch (e) {
+            slot.close();
+            emitRoute({ phase: 'error', from: fromLabel, to: toLabel, seq: lastDelivered, error: e });
+            onError?.(e);
+            throw e;
+        }
+    }
+    const ready = doSwitch(remote, opts, true);
+    switchChain = ready.catch(() => { });
+    function switchRoute(nextRemote, nextOpts = {}) {
+        const run = () => doSwitch(nextRemote, nextOpts, false);
+        const p = switchChain.then(run, run);
+        switchChain = p.catch(() => { });
+        return p;
+    }
+    function off() {
+        if (closed)
+            return;
+        closed = true;
+        for (const slot of Array.from(slots))
+            slot.close();
+        active = null;
+        emitRoute({ phase: 'closed', seq: lastDelivered, to: currentLabel });
+    }
+    return Object.assign(off, {
+        ready,
+        switch: switchRoute,
+        seq: () => lastDelivered,
+        label: () => currentLabel,
+        active: () => active != null && !active.closed(),
+    });
+}

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

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

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

@@ -0,0 +1,17 @@
+"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("./media-source"), exports);