wenay-common2 1.0.73 → 1.0.75

package/doc/wenay-common2.md

@@ -1,396 +1,438 @@
-# wenay-common2 — BRIEF cheat sheet (notation)
-
-> Root import: `import { ... } from "wenay-common2"`.
-> Notation: `name(args: types) -> ret  // note`. Types are shown where they decide a correct call (callback shape,
-> overloads, return). Short names are **canonical**; removed old names are listed in `NAMING_RENAMES.md`.
-> Full surface → **`wenay-common2-rare.md`**. Code style → `CLAUDE.md`. Full RPC guide → `rpc.md`.
-
-## ⭐ events — `listen` / `listenStore`
-```
-import { listen, listenStore, mapListen } from "wenay-common2"
-
-listen<T>(opts?) -> [emit, listen]                   // pure event list: no local value storage, no current replay
-emit(...args: T)                                     // dispatch event only
-listen.on(cb: (...args: T) => void, {key?, cbClose?}) -> off
-listen.once(cb, {key?}) -> off                       // one future event
-listen.onClose(cb: () => void) -> off
-listen.close()                                       // clear listeners + fire close hooks + teardown producer
-listen.count() -> number
-
-listenStore<T>({current, ...opts}) -> [emit, listen]
-  // store wrapper: current() reads external store by reference; the listener does not keep its own value copy
-listen.on(cb, {current: true}) -> off                // current store value first, then future events
-listen.on(cb) -> off                                 // future events only
-listen.once(cb, {current: true}) -> off              // one value from current store, if present; otherwise waits future event
-listen.once(cb) -> off                               // one future event
-listen.on(cb, {current: () => argsOrUndefined}) -> off
-
-opts: { fast? = true, event?(t: 'add'|'remove', count, api), closeOn? }
-```
-```
-mapListen<TIn, TOut>(src, map: (...a: TIn) => TOut | null, opts?) -> [emit, listen]   // map+filter (null skips); lazy subscribe
-joinListens(listens | ports, keyExtractor?) -> { listen, add(port, key?), pending: number, clear(tid?) }   // zip by key
-```
-## ⭐ sleep
-```
-sleepAsync(ms = 0) -> Promise<void>
-```
-
-## ⏱️ async
-```
-createThrottle() -> { throttle(ms: number, fn: () => void) -> void,
-                      debounce(ms: number, fn: () => void) -> Promise<void> }
-  // fn is a ZERO-ARG thunk the scheduler runs itself; NOT a lodash-style wrapper that returns a callable
-  // ONE createThrottle() = ONE shared limiter (shared busy/pending) — use a SEPARATE instance per operation;
-  //   throttle + debounce on the SAME instance contend (a busy throttle silently drops the debounce's trailing run)
-createAsyncQueue(concurrency = 1) -> { add<R>(task: () => Promise<R>) -> Promise<R>, onIdle() -> Promise<void>, size: number }   // p-queue
-createReadyGate() -> { add(fn: () => void), ready() }                  // buffer fns until ready(), then run them in order
-promiseProgress<T>(arr: (Promise<T> | (() => Promise<T>))[]) -> {
-  onOk(cb), onError(cb), all() -> Promise<any[]>, allSettled(), items(), stats() -> { ok: number, error: number, count: number } }
-  // factory entries start on .all()/.allSettled()/items() (once); .all() rejects like Promise.all — read aggregate progress via stats()
-// alias: enhancedWaitRun->createThrottle · createTaskQueue->createReadyGate(.setReady->.ready) · createAsyncQueue.enqueue->add · .getQueueSize->size
-```
-
-## 🧰 core — clone / compare
-```
-clone<T>(v: T) -> T            // deep: cycles + Map/Set/Date, rebinds functions      (alias: deepClone)
-shallowClone<T>(v: T) -> T
-isEqual(a, b) -> boolean       // PLAIN object/array trees ONLY; on Map/Set/Date it returns a vacuous `true` — don't use it on them   (alias: deepEqual)
-shallowEqual(a, b) · arrayShallowEqual(a, b) -> boolean      // strict-by-key vs loose-by-index — both kept on purpose
-toImmutable<T>(o: T) -> T      // deep-frozen clone + Mutable:false marker
-JSON_clone<T>(o: T) -> T       // JSON round-trip; DROPS Map/Set (-> {}) and turns Date -> string. NOT a rich clone — use clone() for those
-```
-
-## 🧰 core — binary search / maps / mutex / memo
-```
-BSearch<T>(arr: ArrayLike<T>, value: T | comparer, match?: 'equal'|'lessOrEqual'|'greatOrEqual', sort?: SortMode) -> number
-  // comparer is (item: T) => number  OR  (a: T, b) => number; without it, T must have valueOf():number
-BSearchNearest<T>(arr: ArrayLike<T>, value: number, getter?: (el: T) => number, maxDelta?: number) -> number
-new MapExt<K,V>() / new WeakMapExt<K,V>():  .getOrSet(k, () => v) -> V          // lazy insert (a plain value is also accepted)
-new Mutex():  .runExclusive<T>(fn: () => T | Promise<T>) -> Promise<T>   |   .lock() -> Promise<release: () => void>   // runExclusive: was dispatch
-MemoFunc<A extends any[], R>(opts?: { timeDelta?: number, maxLimits?: number }) -> { func(...a: A) -> R, cleanAll(), memo }   // TTL + LRU; per-call {timeDelta, reSave}
-```
-
-## 🔢 core — number (frequent)
-```
-round(value: number, digits = 0) -> number                  // round to N decimals          (alias: NormalizeDouble)
-roundSig(value: number, { digitsR?: number /*total significant digits*/, digitsPoint? = 4, type?: 'max'|'min' }) -> number
-  // round to N significant digits — roundSig(1234.5678, {digitsR: 3}) -> 1230     (alias: NormalizeDoubleAnd)
-gcd(a: number, b: number, digits = 8) -> number   |   gcd(values: Iterable<number>, digits = 8) -> number
-  // floats ok; in the ITERABLE overload the 2nd arg is PRECISION digits, not an operand   (alias: MaxCommonDivisor[OnArray])
-formatAuto(value: number, maxDigits = 8) -> string          // shortest decimal string      (alias: DblToStrAuto)
-decimals(value: number, maxDigits = 8, minDigits = 0) -> number   // count of meaningful decimals (alias: GetDblPrecision)
-```
-
-## ⏰ time
-```
-format(date: Date, pattern, { utc? = true }) -> string     // (alias of 11 timeToStr_*/timeLocalToStr_*)
-  pattern: 'HH:mm:ss' | 'HH:mm:ss.SSS' | 'yyyy-MM-dd'
-         | 'yyyy-MM-dd HH:mm' | 'yyyy-MM-dd HH:mm:ss' | 'yyyy-MM-dd HH:mm:ss.SSS'
-         | 'yyyy-MM-dd HH:mm O' | 'yyyy-MM-dd HH:mm:ss O'   // O = GMT offset (local)
-  { utc: false } -> local variants
-formatDuration(ms: number, pattern?: 'H:mm:ss' | 'H:mm:ss.SSS') -> string   // clock; hours unbounded
-durationToStr(ms: number) -> string                        // humanized
-minDate(a: Date | null, b: Date | null) / maxDate(a, b) -> Date | null      // null-tolerant   (alias: MinTime/MaxTime)
-convertDatesToStrings(obj)                                 // Date -> strings, recursively (logs)
-const:  H1_S D1_S W1_S · M1_MS H1_MS D1_MS W1_MS
-```
-
-## 🌐 rpc (brief) — transport is ALWAYS caller-supplied (`{emit,on}`); there is NO url / built-in socket
-```
-// SERVER: `object` is the impl tree, `socket` is a {emit,on} transport adapter
-createRpcServerAuto({ socket: {emit, on}, object, socketKey: string, auth?, limits?, maxPerListen?, throttle?, opt?, replay?, replayOpts? }) -> { api, ... }
-  // replay: false|'auto' (default)|'force' — facade members that are replay lines (replayListen) are exposed
-  //   with BOTH surfaces under the SAME key: legacy plain-Listen path byte-for-byte + line/frameLine/since/keyframe/frame.
-  //   Upgrading listen -> replayListen is a declaration-site-only change; the facade and clients don't move.
-  // replayOpts: {pending?, highWater?, lowWater?, pollMs?} — per-connection lag gate for 'frame'-policy subscribers
-  //   (pending defaults to socket.io writeBuffer; gates close on disconnect automatically). Replay lines are never throttled.
-createRpcServer(opts)        // lower-level core (same { socket, object, socketKey })
-noStrict(obj)                // mark a dynamic subtree (no schema)
-endCallback(fn)              // mark an RPC stream-callback's end   (alias: rpcEndCallback)
-
-// CLIENT hub: takes TWO functions — a socket factory + a schema builder; it is NOT an {url} or an options bag
-createRpcClientHub(
-  createSocket: (token: string | null) => socket,             // YOU build the socket, e.g. socket.io io(url, {auth:{token}})
-  schemaBuilder: (rpc) => ({ key: rpc<Api>('socketKey') }),   // declare each socketKey's typed API
-  hubOpts?: { opt? },
-) -> hub
-hub:     connect(token) -> Promise<clients>  ·  reauth(token)  ·  facade  ·  promise  ·  socket  ·  onConnect/onDisconnect   // connect: was setToken
-         // connect()'s promise resolves on the socket's 'connect' event; for in-proc/loopback (no 'connect') use hub.facade + await hub.promise
-client (on clients[key], NOT on the hub):  func (proxy) · strict (schema-safe) · close() · ready() · init() · subscriptions()
-         // pipe = batch a server chain in one packet · space = fire-and-forget
-
-// minimal wiring (the part no signature can show):
-const [tick, ticks] = listen<[number]>()
-createRpcServerAuto({ socket, object: { math: { add: (a, b) => a + b, ticks } }, socketKey: 'math' })
-const hub = createRpcClientHub((t) => io(url, { auth: { t } }), (rpc) => ({ math: rpc<Api>('math') }))
-const c = await hub.connect(token)               // c = facade of per-socketKey clients
-await c.math.ready();  await c.math.func.add(2, 3)
-const l = c.math.func as unknown as DeepSocketListen<Api>  // typed Listen projection; wrap as webListen(c.math) in app code
-const off = l.ticks.on(v => console.log(v))                // canonical stream subscribe; off is callable and awaitable
-off()                                                     // unsubscribe; .callback/.removeCallback are legacy compat, don't teach them
-l.ticks.once(v => console.log(v))                         // one event, then auto-off
-
-// replay upgrade — ONE WORD at the declaration site, everything below follows automatically:
-// const [tick, ticks] = listen<[number]>()                                       // before
-const [tick, ticks] = replayListen<[number]>({history: 1024, current: 'last'})    // after — same facade, same key
-// legacy subscribers unchanged (byte-for-byte). Replay consumers now also get:
-const sub = replaySubscribe(l.ticks, v => {}, {since: saved, onSeq: s => saved = s})  // catch-up + live, no gaps/dups
-const sub2 = replaySubscribe(c.math.func.ticks, v => {})  // replay members project on func/strict directly — no cast needed
-const routed = replayRouteSubscribe(l.ticks, v => {}, {label: 'relay'})
-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
-
-// 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 (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"`.
-> The happy-path facade over rpc + store + replay + route coordinator. Legacy-friendly by design:
-> the server side is a FRAGMENT spread into your EXISTING `createRpcServerAuto` object, the client
-> side rides your existing connection — old keys keep working untouched.
-```
-// SERVER — next to your legacy object:
-const host = Peer.createPeerHost({authorize?, history?})   // authorize(env) = server-side canExposeEndpoint
-io.on('connection', socket => {
-    const peer = host.connection(accountOf(socket))        // per-account signal port + relay journal
-    createRpcServerAuto({socket, socketKey, object: {...legacyObject, peer: peer.fragment}, disconnectListen})
-    disconnectListen.on(peer.close)
-})
-host: connection(account) · relay(account) · accounts() · revoke(pair, accounts, reason?) · close()
-
-// CLIENT — the whole happy path:
-const me = Peer.createPeerClient<World>({
-    remote: c.app.func.peer,        // deep proxy of the fragment — rest of the connection is yours
-    account: 'a',
-    initial: {...},                 // own store: write me.store.state — others see it
-    rtc?: () => new RTCPeerConnection(cfg),   // omit = relay-only (promoteDirect unavailable)
-})
-const bob = me.peer('b')            // mirror + route control for another account
-await bob.ready                     // keyframe/tail landed
-bob.store.state                     // live mirror — reads survive ANY route change
-await bob.promoteDirect()           // relay -> WebRTC direct; {ok, state, reason?} result, not a throw
-bob.route()                         // 'relay' | 'direct' · bob.reinterposeRelay() · bob.fallback() · bob.block()
-me.onRoute(ev => {})                // route transitions for metrics/UI
-```
-Key property: the relay journal stores the owner's envelopes VERBATIM (owner seq space), so a
-relay <-> direct hand-off is a plain seq resume — no keyframe reset, no gaps, no dups. Late joiners
-get a keyframe folded server-side even while the owner is offline.
-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`.
-
-## 🔁 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.
-```
-// coarse reactive object: subscribe to the fact that a subtree changed, then re-read current state
-Observe.reactive<T extends object>(obj, opts?) -> T
-Observe.onUpdate(node, cb: () => void) -> off
-Observe.onUpdatePaths(node, cb: ({paths}) => void) -> off   // optional dirty paths, relative to node
-Observe.flushReactive(node) -> Promise<void>
-Observe.toRaw(node) -> raw value behind the proxy              // snapshots/serialization without touching lazy nodes
-Observe.listenUpdate(node) -> Listen<void>                  // RPC bridge for coarse change notifications
-Observe.listenUpdatePaths(node) -> Listen<{paths: PropertyKey[][]}>
-opts: { drain?: "immediate"|"micro"|number|((flush)=>void), depth?, eager? }
-
-// path-addressed store facade over reactive()
-Observe.createStore<T extends object>(initial, opts?) -> Store<T>
-store.state                                                   // reactive data object; write normally
-store.node.path.to.leaf.get()/snapshot()/replace(v)           // set(v) is a deprecated alias of replace(v)
-store.node.path.to.leaf.on((value, ctx) => {}, {current?, drain?, key?}) -> off
-store.node.path.to.leaf.once(cb, opts?) -> off
-store.update(mask, opts?) -> selection                         // typed selected snapshot
-selection.get() · selection.on((snap, ctx)=>{}, opts?) -> off · selection.onEach((value, ctx)=>{}, opts?) -> off
-store.each(opts?) -> Listen<[key, value, ctx]>                 // changed TOP-LEVEL keys as a plain Listen — THE per-key feed
-  // one call per CHANGED key per drain window: value = current store.state[key] at flush time; undefined = key deleted;
-  //   two writes to one key in a window = ONE call (last value); deeper dirt (state.a.b = ...) reports 'a' once
-  // root replace (store.replace / mirror keyframe) EXPANDS: one call per key of the new state + (key, undefined)
-  //   per key the replace removed — cold start / reconnect are NOT special cases for per-key consumers
-  // plain Listen shape (on(cb) -> off · once · count); zero cost while it has no subscribers
-  // NOT update(true).onEach: onEach fires per SELECTED path, and mask true selects the root —
-  //   ONE call per window with the whole dict (a dev warn points to each())
-store.count() -> number
-
-// network shape: backend exposes snapshots + changed Listen; frontend mirrors selected masks locally
-Observe.exposeStore(store, opts?) -> { get(mask?), set(path,value), replace(path,value), changed, changedPaths, patches?, changedData? }
-Observe.createStoreMirror(remote, initial, opts?) -> store & { sync(mask, opts?) -> Promise<off>; syncPatches(mask, opts?) -> Promise<off>; syncChangedData(mask, opts?) -> Promise<off> }
-// changedPaths is optional optimization: mirror pulls mask ∩ dirty paths; fallback is changed -> get(mask).
-// Optional push-data mode: exposeStore(store,{push:true}) + syncPatches/syncChangedData; details in rare docs.
-
-// Sequenced sync (replay line): seq-numbered patch stream — keyframe catch-up, reconnect by seq (tail, not snapshot)
-Observe.exposeStoreReplay(store, {history? = 1024}) -> { api /* spread into the RPC server object */, replay, close }
-  // the patch line declares its condensing `frame` itself (last patch per exact path) — reconnect tails and
-  //   lag recovery arrive as a mini-frame (changed paths only), zero config
-Observe.syncStoreReplay(mirror, remote /*{line, since, keyframe, frame?} of api.replay*/, {since?, onSeq?}) -> off
-  // off.ready (catch-up done) · off.seq() (save for reconnect: syncStoreReplay(..., {since: prev.seq()}))
-  // lagging/late client NEVER gets a backlog: evicted seq -> ONE fresh keyframe + live
-  // freshness is an option, not consumer boilerplate: {staleMs, onStale} flags a silent line / stale keyframe (edge-triggered both ways; 🎞️ in rare docs)
-Observe.syncStoreReplayRoute(mirror, remote, {label?}) -> off & {switch(nextRemote, opts), ready, seq(), label(), active()}
-  // 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
-  // opts = all replaySubscribe opts (since/onSeq/policy/staleMs/onStale/onError...) + {drain?, initial?}
-  // off() tears down BOTH the store sub and the wire sub; direct reads via off.store.state.KEY
-  // reconnect: syncStoreReplayEach(remote, cb, {since: prev.seq(), initial: prev.store.snapshot()})
-  //   — the tail lands ON TOP of the previous state (a fresh empty mirror would not converge)
-// Offline persisted mirror (snapshot mode): local cache first, then replay catch-up by seq
-Observe.createOfflineStore({key, remote?, initial, storage, version?, debounceMs?, syncOpts?}) -> Promise<store & {ready, flush(), close(), status(), statusListen, reconnect(remote)}>
-Observe.persistStore(store, {key, storage, seq?, debounceMs?}) -> {flush, forceFlush, close, setSeq, seq, status, statusListen}
-Observe.createMemoryOfflineStorage(initial?) -> OfflineStorage
-  // persists {version, seq, snapshot, savedAt}; seq is the correctness coordinate, timestamps are UX/freshness only
-  // mode:'topLevel' is reserved; first implemented mode is snapshot
-
-// Declarative resource manager above mirror/replay/offline: app chooses what to start, not the store core
-Observe.managedStore.mirror({remote, initial, mask, tags?, priority?, explicitOnly?, large?, sync?})
-Observe.managedStore.replay({remote, initial, tags?, priority?, explicitOnly?, large?, syncOpts?})
-Observe.managedStore.offline({remote?, initial, storage, storageKey?, tags?, priority?, explicitOnly?, large?, syncOpts?})
-Observe.createStoreManager(resources) -> {plan(opts?), start(key, opts?), startPlanned(opts?), stop(key), stopAll(), get(key), touch(key, weight?), usage(), statusListen, handles}
-  // plan excludes explicitOnly/large by default; {includeExplicit, includeLarge} opts opt them in
-// Slow-client conflation: recipe section 🎞️ below. Full generic surface (any event line, history/time-travel) -> Replay namespace, 🎞️ in rare docs.
-// Object add/delete/deep set are paths. Array mutation dirties the whole array branch, not splice internals.
-```
-```
-type Market = {data: {BTC?: number; ETH?: number}; meta: {status?: string}}
-const market = Observe.createStore<Market>({data: {BTC: 1, ETH: 2}, meta: {status: "ok"}})
-
-market.state.data.BTC = 3                                      // plain local mutation
-market.node.data.BTC.on((v, ctx) => {}, {current: true})        // ctx.path = ["data", "BTC"]
-market.node.data.on(data => {}, {current: true, drain: 50})     // branch snapshot, per-sub drain
-market.update({data: {BTC: true, ETH: true}}, {current: true}).on(snap => {})
-
-// backend facade over RPC
-const api = Observe.exposeStore(market)
-
-// frontend mirror: UI subscribes to local mirror, not RPC directly
-const mirror = Observe.createStoreMirror<Market>(api, {data: {}, meta: {}})
-const stop = await mirror.sync({data: {BTC: true}, meta: {status: true}}, {current: true, drain: 250})  // uses changedPaths when available
-mirror.node.data.BTC.on(v => {}, {current: true})
-stop()
-
-// per-key feed — dict store -> grid rows; keyframe / reconnect are just expansion, not special cases
-type Rows = Record<string, {qty: number}>
-const rows = Observe.createStore<Rows>({})
-const offRows = rows.each().on((key, row) => { /* row === undefined ? removeRow(key) : upsertRow(key, row) */ })
-
-// the same per-key contract over the wire — ONE call (mirror store + syncStoreReplay + each)
-const exposed = Observe.exposeStoreReplay(rows, {history: 1024})   // server side: spread exposed.api into the RPC object
-const feed = Observe.syncStoreReplayEach<Rows>(exposed.api.replay, (key, row) => {}, {drain: "micro"})
-await feed.ready                                   // catch-up done: keyframe arrived expanded per key
-feed.store.state                                   // the mirror — direct reads / extra subscriptions
-feed()                                             // tears down the store sub AND the wire sub
-// reconnect later: syncStoreReplayEach(remote, cb, {since: feed.seq(), initial: feed.store.snapshot()})
-// offline persisted mirror — cached snapshot first, then replay catch-up over the same remote
-const offline = await Observe.createOfflineStore<Rows>({
-    key: "rows",
-    remote: exposed.api.replay,
-    initial: {},
-    storage: Observe.createMemoryOfflineStorage(), // use IndexedDB/SQLite adapter in an app
-    debounceMs: 250,
-})
-offline.each().on((key, row) => {})
-await offline.ready
-await offline.flush()
-offline.close()
-
-// configurable app-level resource plan
-const manager = Observe.createStoreManager({
-    market: Observe.managedStore.mirror({remote: api.market, initial: {data: {}, meta: {}}, mask: {data: {BTC: true}}, tags: ['bootstrap'], priority: 10}),
-    rows: Observe.managedStore.offline({remote: exposed.api.replay, initial: {}, storage: Observe.createMemoryOfflineStorage(), tags: ['grid']}),
-    video: Observe.managedStore.replay({remote: videoReplay, initial: {}, explicitOnly: true, large: true}),
-})
-await manager.startPlanned({tags: ['bootstrap']})
-manager.touch('rows', 3)               // usage can raise future plan score
-await manager.start('video', {explicit: true})
-```
-Runnable example: `npx tsx observe/store-mirror.example.ts`.
-Offline oracles: `npx tsx replay/offline-store.test.ts`; real Socket.IO/RPC wire: `npx tsx replay/offline-store-socket.test.ts`.
-
-## 🎞️ Fast ticks vs slow client — replay lines + server-owned lag gate (recipe)
-> The problem: the producer emits faster than a bad link drains. Naive streaming grows an unbounded
-> outgoing queue per slow client. The replay stack solves it with ONE mental model — the FRAME:
-> `frame(sinceSeq, hint?)` on the line returns envelopes bringing a consumer from `sinceSeq` to now,
-> as compact as the line allows (exact tail -> condensed mini-frame -> keyframe fallback). The same
-> method serves reconnect (`since`), client pull (own pace) and lag recovery. The transport sees only
-> `seq`; ALL event semantics live in two lambdas declared on the line: `current` (keyframe = pointer
-> to truth) and `frame` (condenser — may honor a client-supplied `hint`, see below).
-```ts
-import { Observe, Replay } from 'wenay-common2'
-
-// ---- producer: declare what the line HAS (its class follows — no mode flags) ----
-const [emitQuote, quotes] = Replay.replayListen<[string, number]>({
-    history: 4096,
-    frame: (tail, hint) => lastPerSymbol(tail, hint),  // mini-frame; hint = client's pick of the condensation rule
-})   // current+frame = condensable · current only = keyframe recovery · neither = sacred queue (never skipped, loud on eviction)
-// store lines: exposeStoreReplay already declares current + frame (last patch per path) — zero config
-const store = Observe.createStore<World>(initial, { drain: 'micro' })
-const exposed = Observe.exposeStoreReplay(store, { history: 1024 })
-
-// ---- per CONNECTION: the rpc server owns the gate; the facade does NOT change ----
-io.on('connection', socket => {
-    const [disconnect, disconnectListen] = listen<[]>()
-    socket.on('disconnect', () => disconnect())
-    createRpcServerAuto({
-        socket: { emit: (k, d) => socket.emit(k, d), on: (k, cb) => socket.on(k, cb) },
-        socketKey: 'world',
-        object: { ...exposed.api, quotes },       // replay lines auto-exposed: both surfaces, same key
-        disconnectListen,                          // gates close on disconnect automatically
-        replayOpts: { highWater: 64, lowWater: 8 },// arms frameLine; pending defaults to socket.io writeBuffer
-    })
-})
-
-// ---- client: picks its LAG POLICY per subscription; no conflation logic anywhere ----
-const sub = Replay.replaySubscribe(deep.quotes, cb, {since: saved, policy: 'frame'}) // server may skip; drain -> mini-frame
-const sub2 = Replay.replaySubscribe(deep.quotes, cb2, {since: saved})                // 'queue' (default): nothing ever skipped
-// own pace (e.g. 50ms skips + condensation): pull on YOUR timer — hint picks the rule, server condenses:
-//   every(50, async () => { for (const ev of await deep.quotes.frame(mySeq, hint)) apply(ev); })
-// store mirror: Observe.syncStoreReplay(mirror, deep.replay, {since: prev.seq()}) — same contract
-// delivery contract: FIRST delivery = snapshot/tail start (same event type), then strictly-newer,
-// seq-ascending, deduped; reconnect via {since} = mini-frame/tail, not a full snapshot
-```
-Rules that make it correct (violating any of these silently breaks convergence):
-- **The line declares its recovery sources.** `current` (keyframe: SAMPLED from truth, never computed
-  from deltas; `'last'` = last envelope for single-entity lines) and/or `frame` (condenser). A line
-  with neither is a sacred queue: full tails only, evicted journal -> `frame()` THROWS (loud) — a
-  lagging `'frame'`-policy subscriber gets a stream end, never silent loss.
-- **A `frame` result must be state-equivalent to the tail it replaces** (per the line's own semantics).
-  "Can't condense THIS tail" is legal and simple: return the tail as-is. Refuse-loudly is `throw`.
-  Multiple condensation standards live INSIDE the lambda, dispatched by the client-supplied `hint`
-  (opaque to the transport): `frame(tail, hint)`.
-- **Events must be ABSOLUTE per their entity** for last-per-entity condensing (store patches are).
-- Gate drops never hole the journal — it is written BEFORE any gate. Reconnect via `{since}` still
-  gets everything; only an evicted `history` window degrades to keyframe (visible as a seq jump).
-- `pending()` and the watermarks share units (bytes, packets, frames — anything, but the same).
-
-Manual path (pre-rev2, still works, `keyOf` @deprecated): build the gate yourself with
-`Replay.conflateReplay(exposed.replay, {pending, highWater, keyOf})` and spread `gated.api` into the
-facade — details in rare docs. New code should declare `frame` on the line instead.
-
-Wire-level proof/oracles: `npx ts-node replay/rpc-auto.test.ts` (real Socket.IO: auto-exposure, legacy
-parity, frame equivalence, gate lag sim), plus `replay/conflate-socket.test.ts`, `replay/conflate.test.ts`,
-`replay/coalesce.test.ts`. Full generic surface (history/time-travel, archive) → 🎞️ in rare docs.
-
-
-
+# wenay-common2 — BRIEF cheat sheet (notation)
+
+> Root import: `import { ... } from "wenay-common2"`.
+> Notation: `name(args: types) -> ret  // note`. Types are shown where they decide a correct call (callback shape,
+> overloads, return). Short names are **canonical**; removed old names are listed in `NAMING_RENAMES.md`.
+> Full surface → **`wenay-common2-rare.md`**. Code style → `CLAUDE.md`. Full RPC guide → `rpc.md`.
+
+## ⭐ events — `listen` / `listenStore`
+```
+import { listen, listenStore, mapListen } from "wenay-common2"
+
+listen<T>(opts?) -> [emit, listen]                   // pure event list: no local value storage, no current replay
+emit(...args: T)                                     // dispatch event only
+listen.on(cb: (...args: T) => void, {key?, cbClose?}) -> off
+listen.once(cb, {key?}) -> off                       // one future event
+listen.onClose(cb: () => void) -> off
+listen.close()                                       // clear listeners + fire close hooks + teardown producer
+listen.count() -> number
+
+listenStore<T>({current, ...opts}) -> [emit, listen]
+  // store wrapper: current() reads external store by reference; the listener does not keep its own value copy
+listen.on(cb, {current: true}) -> off                // current store value first, then future events
+listen.on(cb) -> off                                 // future events only
+listen.once(cb, {current: true}) -> off              // one value from current store, if present; otherwise waits future event
+listen.once(cb) -> off                               // one future event
+listen.on(cb, {current: () => argsOrUndefined}) -> off
+
+opts: { fast? = true, event?(t: 'add'|'remove', count, api), closeOn? }
+```
+```
+mapListen<TIn, TOut>(src, map: (...a: TIn) => TOut | null, opts?) -> [emit, listen]   // map+filter (null skips); lazy subscribe
+joinListens(listens | ports, keyExtractor?) -> { listen, add(port, key?), pending: number, clear(tid?) }   // zip by key
+```
+## ⭐ sleep
+```
+sleepAsync(ms = 0) -> Promise<void>
+```
+
+## ⏱️ async
+```
+createThrottle() -> { throttle(ms: number, fn: () => void) -> void,
+                      debounce(ms: number, fn: () => void) -> Promise<void> }
+  // fn is a ZERO-ARG thunk the scheduler runs itself; NOT a lodash-style wrapper that returns a callable
+  // ONE createThrottle() = ONE shared limiter (shared busy/pending) — use a SEPARATE instance per operation;
+  //   throttle + debounce on the SAME instance contend (a busy throttle silently drops the debounce's trailing run)
+createAsyncQueue(concurrency = 1) -> { add<R>(task: () => Promise<R>) -> Promise<R>, onIdle() -> Promise<void>, size: number }   // p-queue
+createReadyGate() -> { add(fn: () => void), ready() }                  // buffer fns until ready(), then run them in order
+promiseProgress<T>(arr: (Promise<T> | (() => Promise<T>))[]) -> {
+  onOk(cb), onError(cb), all() -> Promise<any[]>, allSettled(), items(), stats() -> { ok: number, error: number, count: number } }
+  // factory entries start on .all()/.allSettled()/items() (once); .all() rejects like Promise.all — read aggregate progress via stats()
+// alias: enhancedWaitRun->createThrottle · createTaskQueue->createReadyGate(.setReady->.ready) · createAsyncQueue.enqueue->add · .getQueueSize->size
+```
+
+## 🧰 core — clone / compare
+```
+clone<T>(v: T) -> T            // deep: cycles + Map/Set/Date, rebinds functions      (alias: deepClone)
+shallowClone<T>(v: T) -> T
+isEqual(a, b) -> boolean       // PLAIN object/array trees ONLY; on Map/Set/Date it returns a vacuous `true` — don't use it on them   (alias: deepEqual)
+shallowEqual(a, b) · arrayShallowEqual(a, b) -> boolean      // strict-by-key vs loose-by-index — both kept on purpose
+toImmutable<T>(o: T) -> T      // deep-frozen clone + Mutable:false marker
+JSON_clone<T>(o: T) -> T       // JSON round-trip; DROPS Map/Set (-> {}) and turns Date -> string. NOT a rich clone — use clone() for those
+```
+
+## 🧰 core — binary search / maps / mutex / memo
+```
+BSearch<T>(arr: ArrayLike<T>, value: T | comparer, match?: 'equal'|'lessOrEqual'|'greatOrEqual', sort?: SortMode) -> number
+  // comparer is (item: T) => number  OR  (a: T, b) => number; without it, T must have valueOf():number
+BSearchNearest<T>(arr: ArrayLike<T>, value: number, getter?: (el: T) => number, maxDelta?: number) -> number
+new MapExt<K,V>() / new WeakMapExt<K,V>():  .getOrSet(k, () => v) -> V          // lazy insert (a plain value is also accepted)
+new Mutex():  .runExclusive<T>(fn: () => T | Promise<T>) -> Promise<T>   |   .lock() -> Promise<release: () => void>   // runExclusive: was dispatch
+MemoFunc<A extends any[], R>(opts?: { timeDelta?: number, maxLimits?: number }) -> { func(...a: A) -> R, cleanAll(), memo }   // TTL + LRU; per-call {timeDelta, reSave}
+```
+
+## 🔢 core — number (frequent)
+```
+round(value: number, digits = 0) -> number                  // round to N decimals          (alias: NormalizeDouble)
+roundSig(value: number, { digitsR?: number /*total significant digits*/, digitsPoint? = 4, type?: 'max'|'min' }) -> number
+  // round to N significant digits — roundSig(1234.5678, {digitsR: 3}) -> 1230     (alias: NormalizeDoubleAnd)
+gcd(a: number, b: number, digits = 8) -> number   |   gcd(values: Iterable<number>, digits = 8) -> number
+  // floats ok; in the ITERABLE overload the 2nd arg is PRECISION digits, not an operand   (alias: MaxCommonDivisor[OnArray])
+formatAuto(value: number, maxDigits = 8) -> string          // shortest decimal string      (alias: DblToStrAuto)
+decimals(value: number, maxDigits = 8, minDigits = 0) -> number   // count of meaningful decimals (alias: GetDblPrecision)
+```
+
+## ⏰ time
+```
+format(date: Date, pattern, { utc? = true }) -> string     // (alias of 11 timeToStr_*/timeLocalToStr_*)
+  pattern: 'HH:mm:ss' | 'HH:mm:ss.SSS' | 'yyyy-MM-dd'
+         | 'yyyy-MM-dd HH:mm' | 'yyyy-MM-dd HH:mm:ss' | 'yyyy-MM-dd HH:mm:ss.SSS'
+         | 'yyyy-MM-dd HH:mm O' | 'yyyy-MM-dd HH:mm:ss O'   // O = GMT offset (local)
+  { utc: false } -> local variants
+formatDuration(ms: number, pattern?: 'H:mm:ss' | 'H:mm:ss.SSS') -> string   // clock; hours unbounded
+durationToStr(ms: number) -> string                        // humanized
+minDate(a: Date | null, b: Date | null) / maxDate(a, b) -> Date | null      // null-tolerant   (alias: MinTime/MaxTime)
+convertDatesToStrings(obj)                                 // Date -> strings, recursively (logs)
+const:  H1_S D1_S W1_S · M1_MS H1_MS D1_MS W1_MS
+```
+
+## 🌐 rpc (brief) — transport is ALWAYS caller-supplied (`{emit,on}`); there is NO url / built-in socket
+```
+// SERVER: `object` is the impl tree, `socket` is a {emit,on} transport adapter
+createRpcServerAuto({ socket: {emit, on}, object, socketKey: string, auth?, limits?, maxPerListen?, throttle?, opt?, replay?, replayOpts? }) -> { api, ... }
+  // replay: false|'auto' (default)|'force' — facade members that are replay lines (replayListen) are exposed
+  //   with BOTH surfaces under the SAME key: legacy plain-Listen path byte-for-byte + line/frameLine/since/keyframe/frame.
+  //   Upgrading listen -> replayListen is a declaration-site-only change; the facade and clients don't move.
+  // replayOpts: {pending?, highWater?, lowWater?, pollMs?} — per-connection lag gate for 'frame'-policy subscribers
+  //   (pending defaults to socket.io writeBuffer; gates close on disconnect automatically). Replay lines are never throttled.
+createRpcServer(opts)        // lower-level core (same { socket, object, socketKey })
+noStrict(obj)                // mark a dynamic subtree (no schema)
+endCallback(fn)              // mark an RPC stream-callback's end   (alias: rpcEndCallback)
+
+// CLIENT hub: takes TWO functions — a socket factory + a schema builder; it is NOT an {url} or an options bag
+createRpcClientHub(
+  createSocket: (token: string | null) => socket,             // YOU build the socket, e.g. socket.io io(url, {auth:{token}})
+  schemaBuilder: (rpc) => ({ key: rpc<Api>('socketKey') }),   // declare each socketKey's typed API
+  hubOpts?: { opt? },
+) -> hub
+hub:     connect(token) -> Promise<clients>  ·  reauth(token)  ·  facade  ·  promise  ·  socket  ·  onConnect/onDisconnect  ·  connectListen/disconnectListen   // connect: was setToken
+         // connect() resolves after the socket 'connect' event and RPC route/auth handshake; for in-proc/loopback (no 'connect') use hub.facade + await hub.promise
+client (on clients[key], NOT on the hub):  func (proxy) · strict (schema-safe) · close() · ready() · init() · subscriptions()
+         // pipe = batch a server chain in one packet · space = fire-and-forget
+         // func/space/strict paths have stable identity per client+surface: c.func.a.b === c.func.a.b;
+         //   all === func. Identity survives reauth/transient reconnect; connect/setToken creates a new client generation.
+         // onConnect/onDisconnect keep their legacy single-slot contract; connectListen(cb)/disconnectListen(cb) are additive and return individual off functions.
+         // transient reconnect of the SAME Socket.IO object restores active logical Listen subscriptions once the new handshake is ready.
+         // close()/dispose() and connect()/setToken() are terminal for the old generation. Ordinary RPC calls are NEVER retried.
+
+// minimal wiring (the part no signature can show):
+const [tick, ticks] = listen<[number]>()
+createRpcServerAuto({ socket, object: { math: { add: (a, b) => a + b, ticks } }, socketKey: 'math' })
+const hub = createRpcClientHub((t) => io(url, { auth: { t } }), (rpc) => ({ math: rpc<Api>('math') }))
+const c = await hub.connect(token)               // c = facade of per-socketKey clients
+await c.math.ready();  await c.math.func.add(2, 3)
+const l = c.math.func as unknown as DeepSocketListen<Api>  // typed Listen projection; wrap as webListen(c.math) in app code
+const off = l.ticks.on(v => console.log(v))                // canonical stream subscribe; off is callable and awaitable
+off()                                                     // unsubscribe; .callback/.removeCallback are legacy compat, don't teach them
+l.ticks.once(v => console.log(v))                         // one event, then auto-off
+
+// replay upgrade — ONE WORD at the declaration site, everything below follows automatically:
+// const [tick, ticks] = listen<[number]>()                                       // before
+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 uncovered loss/dups (a producer frame/keyframe may jump raw seq)
+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
+
+// 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 (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"`.
+> The happy-path facade over rpc + store + replay + route coordinator. Legacy-friendly by design:
+> the server side is a FRAGMENT spread into your EXISTING `createRpcServerAuto` object, the client
+> side rides your existing connection — old keys keep working untouched.
+```
+// SERVER — next to your legacy object:
+const host = Peer.createPeerHost({authorize?, history?})   // authorize(env) = server-side canExposeEndpoint
+io.on('connection', socket => {
+    const peer = host.connection(accountOf(socket))        // per-account signal port + relay journal
+    createRpcServerAuto({socket, socketKey, object: {...legacyObject, peer: peer.fragment}, disconnectListen})
+    disconnectListen.on(peer.close)
+})
+host: connection(account) · relay(account) · accounts() · revoke(pair, accounts, reason?) · close()
+
+// CLIENT — the whole happy path:
+const me = Peer.createPeerClient<World>({
+    remote: c.app.func.peer,        // deep proxy of the fragment — rest of the connection is yours
+    account: 'a',
+    initial: {...},                 // own store: write me.store.state — others see it
+    rtc?: () => new RTCPeerConnection(cfg),   // omit = relay-only (promoteDirect unavailable)
+})
+const bob = me.peer('b')            // mirror + route control for another account
+await bob.ready                     // keyframe/tail landed
+bob.store.state                     // live mirror — reads survive ANY route change
+await bob.promoteDirect()           // relay -> WebRTC direct; {ok, state, reason?} result, not a throw
+bob.route()                         // 'relay' | 'direct' · bob.reinterposeRelay() · bob.fallback() · bob.block()
+me.onRoute(ev => {})                // route transitions for metrics/UI
+```
+Key property: the relay journal stores the owner's envelopes VERBATIM (owner seq space), so a
+relay <-> direct hand-off is a plain seq resume — no uncovered loss or duplicate delivery. Late joiners
+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`.
+
+### Calls, presence and the media relay (messenger-style, on the same parts)
+```
+// presence rides in the fragment (host >= 1.0.74): subscribe FIRST, then list()
+c.app.func.peer.presence.changes.on(({account, online}) => {})
+await c.app.func.peer.presence.list()                       // ['a', 'b', ...] — connected right now
+
+// SERVER — media relay next to the fragment (per-account named lines, policy-gated watch):
+const media = Peer.createMediaRelay({
+    lines: {cam: 'video', mic: 'audio', screen: 'video'},
+    canWatch?: (watcher, owner, line) => bool,   // ACL, checked on paths + every forwarded frame
+})
+object: {peer: peer.fragment, media: {publish: media.publishOf(account), watch: media.watchOf(account)}}
+media.dropAccount(account)   // retire lines + keyspace (e.g. on presence offline); next publish revives
+
+// CLIENT — calls are envelopes over the SAME signal port; media attach stays app code:
+const calls = Peer.createCallManager({port: Peer.callPortOf(c.app.func.peer), self: 'a'})
+await calls.ready                                           // signal subscription confirmed server-side
+calls.rings.on(call => { call.accept() /* or call.decline() */ })
+const call = calls.call('b', {kinds: ['cam', 'mic']})       // meta rides opaquely
+call.changed.on(state => {})                                // 'active' | 'ended'
+await call.ended                                            // 'declined'|'busy'|'offline'|'timeout'|'hangup'|'canceled'
+call.hangup()
+// while active: publish own frames + attach the peer's lines (Media.attach* viewers)
+media.publish('cam', frame, Date.now());  attachVideoCanvas(c.app.func.media.watch.b.cam, canvas)
+```
+Relay-first is the privacy default (mainstream messengers route calls through their servers too);
+`promoteDirect` stays the policy-gated opt-in for the data path. Ring/accept/decline/hangup ride the
+existing signal hub — the host `authorize` hook sees them too (single server-side policy point), and
+an offline callee fails fast (`'offline'`), no timeout wait. The default incoming gate auto-declines
+with `'busy'` during a live call, which also settles simultaneous cross-calls. `video` relay lines
+are keep-latest (late joiner pulls `keyframe()` instantly), `audio` is a short lossless queue; frames
+ride as `[frame, sentAt]` so viewer latency stats work out of the box. Watch access is an ACL, not a
+convention: `watchOf(account)` views run `canWatch` on every new subscribe/keyframe and every live
+frame. "Media access follows the call" is a few lines of app code (grant on `'active'`, revoke on
+`'ended'`); after revocation an already-open policy view receives no more data. Oracle:
+`replay/peer-call.test.ts`.
+
+## 🔁 Observe — reactive state + store/mirror API
+> `import { Observe } from "wenay-common2"` or `import * as Observe from "wenay-common2/observe"`.
+> This is the documented v2 reactive/store surface.
+```
+// coarse reactive object: subscribe to the fact that a subtree changed, then re-read current state
+Observe.reactive<T extends object>(obj, opts?) -> T
+Observe.onUpdate(node, cb: () => void) -> off
+Observe.onUpdatePaths(node, cb: ({paths}) => void) -> off   // optional dirty paths, relative to node
+Observe.flushReactive(node) -> Promise<void>
+Observe.toRaw(node) -> raw value behind the proxy              // snapshots/serialization without touching lazy nodes
+Observe.listenUpdate(node) -> Listen<void>                  // RPC bridge for coarse change notifications
+Observe.listenUpdatePaths(node) -> Listen<{paths: PropertyKey[][]}>
+opts: { drain?: "immediate"|"micro"|number|((flush)=>void), depth?, eager? }
+
+// path-addressed store facade over reactive()
+Observe.createStore<T extends object>(initial, opts?) -> Store<T>
+store.state                                                   // reactive data object; write normally
+store.node.path.to.leaf.get()/snapshot()/replace(v)           // set(v) is a deprecated alias of replace(v)
+store.node.path.to.leaf.on((value, ctx) => {}, {current?, drain?, key?}) -> off
+store.node.path.to.leaf.once(cb, opts?) -> off
+store.update(mask, opts?) -> selection                         // typed selected snapshot
+selection.get() · selection.on((snap, ctx)=>{}, opts?) -> off · selection.onEach((value, ctx)=>{}, opts?) -> off
+store.each(opts?) -> Listen<[key, value, ctx]>                 // changed TOP-LEVEL keys as a plain Listen — THE per-key feed
+  // one call per CHANGED key per drain window: value = current store.state[key] at flush time; undefined = key deleted;
+  //   two writes to one key in a window = ONE call (last value); deeper dirt (state.a.b = ...) reports 'a' once
+  // root replace (store.replace / mirror keyframe) EXPANDS: one call per key of the new state + (key, undefined)
+  //   per key the replace removed — cold start / reconnect are NOT special cases for per-key consumers
+  // plain Listen shape (on(cb) -> off · once · count); zero cost while it has no subscribers
+  // NOT update(true).onEach: onEach fires per SELECTED path, and mask true selects the root —
+  //   ONE call per window with the whole dict (a dev warn points to each())
+store.count() -> number
+
+// network shape: backend exposes snapshots + changed Listen; frontend mirrors selected masks locally
+Observe.exposeStore(store, opts?) -> { get(mask?), set(path,value), replace(path,value), changed, changedPaths, patches?, changedData? }
+Observe.createStoreMirror(remote, initial, opts?) -> store & { sync(mask, opts?) -> Promise<off>; syncPatches(mask, opts?) -> Promise<off>; syncChangedData(mask, opts?) -> Promise<off> }
+// changedPaths is optional optimization: mirror pulls mask ∩ dirty paths; fallback is changed -> get(mask).
+// Optional push-data mode: exposeStore(store,{push:true}) + syncPatches/syncChangedData; details in rare docs.
+
+// Sequenced sync (replay line): seq-numbered patch stream — keyframe catch-up, reconnect by seq (tail, not snapshot)
+Observe.exposeStoreReplay(store, {history? = 1024}) -> { api /* spread into the RPC server object */, replay, close }
+  // the patch line declares its condensing `frame` itself (last patch per exact path) — reconnect tails and
+  //   lag recovery arrive as a mini-frame (changed paths only), zero config
+Observe.syncStoreReplay(mirror, remote /*{line, since, keyframe, frame?} of api.replay*/, {since?, onSeq?}) -> off
+  // off.ready (catch-up done) · off.seq() (save for reconnect: syncStoreReplay(..., {since: prev.seq()}))
+  // lagging/late client NEVER gets a backlog: evicted seq -> ONE fresh keyframe + live
+  // freshness is an option, not consumer boilerplate: {staleMs, onStale} flags a silent line / stale keyframe (edge-triggered both ways; 🎞️ in rare docs)
+Observe.syncStoreReplayRoute(mirror, remote, {label?}) -> off & {switch(nextRemote, opts), ready, seq(), label(), active()}
+  // 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
+  // opts = all replaySubscribe opts (since/onSeq/policy/staleMs/onStale/onError...) + {drain?, initial?}
+  // off() tears down BOTH the store sub and the wire sub; direct reads via off.store.state.KEY
+  // reconnect: syncStoreReplayEach(remote, cb, {since: prev.seq(), initial: prev.store.snapshot()})
+  //   — the tail lands ON TOP of the previous state (a fresh empty mirror would not converge)
+// Offline persisted mirror (snapshot mode): local cache first, then replay catch-up by seq
+Observe.createOfflineStore({key, remote?, initial, storage, version?, debounceMs?, syncOpts?}) -> Promise<store & {ready, flush(), close(), status(), statusListen, reconnect(remote)}>
+Observe.persistStore(store, {key, storage, seq?, debounceMs?}) -> {flush, forceFlush, close, setSeq, seq, status, statusListen}
+Observe.createMemoryOfflineStorage(initial?) -> OfflineStorage
+  // persists {version, seq, snapshot, savedAt}; seq is the correctness coordinate, timestamps are UX/freshness only
+  // mode:'topLevel' is reserved; first implemented mode is snapshot
+
+// Declarative resource manager above mirror/replay/offline: app chooses what to start, not the store core
+Observe.managedStore.mirror({remote, initial, mask, tags?, priority?, explicitOnly?, large?, sync?})
+Observe.managedStore.replay({remote, initial, tags?, priority?, explicitOnly?, large?, syncOpts?})
+Observe.managedStore.offline({remote?, initial, storage, storageKey?, tags?, priority?, explicitOnly?, large?, syncOpts?})
+Observe.createStoreManager(resources) -> {plan(opts?), start(key, opts?), startPlanned(opts?), stop(key), stopAll(), get(key), touch(key, weight?), usage(), statusListen, handles}
+  // plan excludes explicitOnly/large by default; {includeExplicit, includeLarge} opts opt them in
+// Slow-client conflation: recipe section 🎞️ below. Full generic surface (any event line, history/time-travel) -> Replay namespace, 🎞️ in rare docs.
+// Object add/delete/deep set are paths. Array mutation dirties the whole array branch, not splice internals.
+```
+```
+type Market = {data: {BTC?: number; ETH?: number}; meta: {status?: string}}
+const market = Observe.createStore<Market>({data: {BTC: 1, ETH: 2}, meta: {status: "ok"}})
+
+market.state.data.BTC = 3                                      // plain local mutation
+market.node.data.BTC.on((v, ctx) => {}, {current: true})        // ctx.path = ["data", "BTC"]
+market.node.data.on(data => {}, {current: true, drain: 50})     // branch snapshot, per-sub drain
+market.update({data: {BTC: true, ETH: true}}, {current: true}).on(snap => {})
+
+// backend facade over RPC
+const api = Observe.exposeStore(market)
+
+// frontend mirror: UI subscribes to local mirror, not RPC directly
+const mirror = Observe.createStoreMirror<Market>(api, {data: {}, meta: {}})
+const stop = await mirror.sync({data: {BTC: true}, meta: {status: true}}, {current: true, drain: 250})  // uses changedPaths when available
+mirror.node.data.BTC.on(v => {}, {current: true})
+stop()
+
+// per-key feed — dict store -> grid rows; keyframe / reconnect are just expansion, not special cases
+type Rows = Record<string, {qty: number}>
+const rows = Observe.createStore<Rows>({})
+const offRows = rows.each().on((key, row) => { /* row === undefined ? removeRow(key) : upsertRow(key, row) */ })
+
+// the same per-key contract over the wire — ONE call (mirror store + syncStoreReplay + each)
+const exposed = Observe.exposeStoreReplay(rows, {history: 1024})   // server side: spread exposed.api into the RPC object
+const feed = Observe.syncStoreReplayEach<Rows>(exposed.api.replay, (key, row) => {}, {drain: "micro"})
+await feed.ready                                   // catch-up done: keyframe arrived expanded per key
+feed.store.state                                   // the mirror — direct reads / extra subscriptions
+feed()                                             // tears down the store sub AND the wire sub
+// reconnect later: syncStoreReplayEach(remote, cb, {since: feed.seq(), initial: feed.store.snapshot()})
+// offline persisted mirror — cached snapshot first, then replay catch-up over the same remote
+const offline = await Observe.createOfflineStore<Rows>({
+    key: "rows",
+    remote: exposed.api.replay,
+    initial: {},
+    storage: Observe.createMemoryOfflineStorage(), // use IndexedDB/SQLite adapter in an app
+    debounceMs: 250,
+})
+offline.each().on((key, row) => {})
+await offline.ready
+await offline.flush()
+offline.close()
+
+// configurable app-level resource plan
+const manager = Observe.createStoreManager({
+    market: Observe.managedStore.mirror({remote: api.market, initial: {data: {}, meta: {}}, mask: {data: {BTC: true}}, tags: ['bootstrap'], priority: 10}),
+    rows: Observe.managedStore.offline({remote: exposed.api.replay, initial: {}, storage: Observe.createMemoryOfflineStorage(), tags: ['grid']}),
+    video: Observe.managedStore.replay({remote: videoReplay, initial: {}, explicitOnly: true, large: true}),
+})
+await manager.startPlanned({tags: ['bootstrap']})
+manager.touch('rows', 3)               // usage can raise future plan score
+await manager.start('video', {explicit: true})
+```
+Runnable example: `npx tsx observe/store-mirror.example.ts`.
+Offline oracles: `npx tsx replay/offline-store.test.ts`; real Socket.IO/RPC wire: `npx tsx replay/offline-store-socket.test.ts`.
+
+## 🎞️ Fast ticks vs slow client — replay lines + server-owned lag gate (recipe)
+> The problem: the producer emits faster than a bad link drains. Naive streaming grows an unbounded
+> outgoing queue per slow client. The replay stack solves it with ONE mental model — the FRAME:
+> `frame(sinceSeq, hint?)` on the line returns envelopes bringing a consumer from `sinceSeq` to now,
+> as compact as the line allows (exact tail -> condensed mini-frame -> keyframe fallback). The same
+> method serves reconnect (`since`), client pull (own pace) and lag recovery. The transport sees only
+> `seq`; ALL event semantics live in two lambdas declared on the line: `current` (keyframe = pointer
+> to truth) and `frame` (condenser — may honor a client-supplied `hint`, see below).
+```ts
+import { Observe, Replay } from 'wenay-common2'
+
+// ---- producer: declare what the line HAS (its class follows — no mode flags) ----
+const [emitQuote, quotes] = Replay.replayListen<[string, number]>({
+    history: 4096,
+    frame: (tail, hint) => lastPerSymbol(tail, hint),  // mini-frame; hint = client's pick of the condensation rule
+})   // current+frame = compact + keyframe fallback · current only = exact tail + keyframe · frame only = compact while retained, loud on eviction · neither = sacred exact queue
+// store lines: exposeStoreReplay already declares current + frame (last patch per path) — zero config
+const store = Observe.createStore<World>(initial, { drain: 'micro' })
+const exposed = Observe.exposeStoreReplay(store, { history: 1024 })
+
+// ---- per CONNECTION: the rpc server owns the gate; the facade does NOT change ----
+io.on('connection', socket => {
+    const [disconnect, disconnectListen] = listen<[]>()
+    socket.on('disconnect', () => disconnect())
+    createRpcServerAuto({
+        socket: { emit: (k, d) => socket.emit(k, d), on: (k, cb) => socket.on(k, cb) },
+        socketKey: 'world',
+        object: { ...exposed.api, quotes },       // replay lines auto-exposed: both surfaces, same key
+        disconnectListen,                          // gates close on disconnect automatically
+        replayOpts: { highWater: 64, lowWater: 8 },// arms frameLine; pending defaults to socket.io writeBuffer
+    })
+})
+
+// ---- client: picks its LAG POLICY per subscription; no conflation logic anywhere ----
+const sub = Replay.replaySubscribe(deep.quotes, cb, {since: saved, policy: 'frame'}) // server may skip live envelopes; drain -> state-equivalent mini-frame
+const sub2 = Replay.replaySubscribe(deep.quotes, cb2, {since: saved})                // 'queue' (default): ungated live; catch-up may still use producer frame/keyframe
+// own pace (e.g. 50ms skips + condensation): pull on YOUR timer — hint picks the rule, server condenses:
+//   every(50, async () => { for (const ev of await deep.quotes.frame(mySeq, hint)) apply(ev); })
+// store mirror: Observe.syncStoreReplay(mirror, deep.replay, {since: prev.seq()}) — same contract
+// delivery contract: FIRST delivery = snapshot/tail start (same event type), then strictly-newer,
+// seq-ascending and deduped. Raw seq jumps are legal only when a producer frame/keyframe covers them;
+// a sacred retained tail is exact, while sacred eviction closes with onError instead of continuing past a hole.
+```
+Rules that make it correct (violating any of these silently breaks convergence):
+- **The line declares its recovery sources.** `current` (keyframe: SAMPLED from truth, never computed
+  from deltas; `'last'` = last envelope for single-entity lines) and/or `frame` (condenser). Without
+  `current`, eviction is terminal even when a condenser exists: a true sacred queue (neither source)
+  replays the retained tail exactly, and `frame()` THROWS once that tail is gone. A lagging
+  `'frame'`-policy sacred subscriber gets a stream end, never silent loss.
+- **A `frame` result must be state-equivalent to the tail it replaces** (per the line's own semantics).
+  "Can't condense THIS tail" is legal and simple: return the tail as-is. Refuse-loudly is `throw`.
+  Multiple condensation standards live INSIDE the lambda, dispatched by the client-supplied `hint`
+  (opaque to the transport): `frame(tail, hint)`.
+- **Events must be ABSOLUTE per their entity** for last-per-entity condensing (store patches are).
+- Gate drops never hole the journal — it is written BEFORE any gate. Queue-policy live delivery is
+  ungated; reconnect catch-up may use the producer's state-equivalent mini-frame. An evicted state
+  line falls back to a keyframe (visible raw seq jump); an evicted sacred line fails terminally.
+- `pending()` and the watermarks share units (bytes, packets, frames — anything, but the same).
+
+Manual path (pre-rev2, still works, `keyOf` @deprecated): build the gate yourself with
+`Replay.conflateReplay(exposed.replay, {pending, highWater, keyOf})` and spread `gated.api` into the
+facade — details in rare docs. New code should declare `frame` on the line instead.
+
+Wire-level proof/oracles: `npx ts-node replay/rpc-auto.test.ts` (real Socket.IO: auto-exposure, legacy
+parity, frame equivalence, gate lag sim), plus `replay/conflate-socket.test.ts`, `replay/conflate.test.ts`,
+`replay/coalesce.test.ts`. Full generic surface (history/time-travel, archive) → 🎞️ in rare docs.