wenay-common2 1.0.69 → 1.0.70

package/observe/listen-core.test.ts

@@ -0,0 +1,66 @@
+import {createListen, createListenCore, listenStore} from '../src/Common/events/Listen'
+
+let fails = 0
+const ok = (c: any, m: string) => { if (!c) { fails++; console.log('  FAIL', m) } else console.log('  OK  ', m) }
+
+async function main() {
+    console.log('\n[slim-listen] core on/off/once')
+    {
+        const listen = createListenCore<[number]>()
+        const seen: number[] = []
+        const off = listen.on(v => seen.push(v))
+        listen.emit(1)
+        off()
+        listen.emit(2)
+        listen.once(v => seen.push(v * 10))
+        listen.emit(3)
+        listen.emit(4)
+        ok(JSON.stringify(seen) == '[1,30]', 'core delivers on, removes by off, and once fires once')
+        ok(listen.count() == 0, 'core once removes itself')
+    }
+
+    console.log('\n[slim-listen] core key replacement')
+    {
+        const listen = createListenCore<[number]>()
+        const seen: string[] = []
+        listen.on(v => seen.push('a' + v), {key: 'slot'})
+        listen.on(v => seen.push('b' + v), {key: 'slot'})
+        listen.emit(5)
+        ok(JSON.stringify(seen) == '["b5"]', 'same key replaces previous callback')
+        ok(listen.count() == 1, 'key replacement keeps one live subscriber')
+    }
+
+    console.log('\n[slim-listen] full lifecycle and close hooks')
+    {
+        let producerClosed = 0
+        let cbClosed = 0
+        let streamClosed = 0
+        const listen = createListen<[number]>(() => () => { producerClosed++ })
+        listen.run()
+        const off = listen.on(() => {}, {cbClose: () => { cbClosed++ }})
+        off()
+        listen.on(() => {}, {cbClose: () => { cbClosed++ }})
+        listen.onClose(() => { streamClosed++ })
+        listen.close()
+        ok(cbClosed == 1, 'cbClose fires on full close for live subscribers only')
+        ok(producerClosed == 1, 'producer cleanup fires on close')
+        ok(streamClosed == 1, 'onClose fires on close')
+        ok(listen.count() == 0, 'full close clears listeners')
+    }
+
+    console.log('\n[slim-listen] store once(current) waits when current is absent')
+    {
+        const [emit, listen] = listenStore<[number]>({current: () => undefined})
+        const seen: number[] = []
+        listen.once(v => seen.push(v), {current: true})
+        emit(8)
+        emit(9)
+        ok(JSON.stringify(seen) == '[8]', 'once(current) falls back to one future event when store has no value')
+    }
+
+    console.log(`\n${fails == 0 ? 'ALL GREEN' : fails + ' FAILURE(S)'}`)
+    process.exit(fails == 0 ? 0 : 1)
+}
+
+main().catch(e => { console.error(e); process.exit(1) })
+

package/observe/listen-store.test.ts

@@ -0,0 +1,56 @@
+import {listen as createListenPair, listenStore} from '../src/Common/events/Listen'
+
+let fails = 0
+const ok = (c: any, m: string) => { if (!c) { fails++; console.log('  FAIL', m) } else console.log('  OK  ', m) }
+
+async function main() {
+    console.log('\n[listen-store] base listen is a pure event list')
+    {
+        const [emit, listen] = createListenPair<[number]>()
+        emit(1)
+        let got = 0
+        ;(listen.on as any)((v: number) => { got = v }, {current: true})
+        ok(got == 0, 'base listen ignores current and stores no value')
+    }
+
+    console.log('\n[listen-store] listenStore reads external store reference')
+    {
+        const box = {value: 1}
+        const [emit, listen] = listenStore<[number]>({current: () => [box.value]})
+        emit(99)
+        let got = 0
+        listen.on(v => { got = v }, {current: true})
+        ok(got == 1, 'current:true reads store provider, not emitted args')
+        box.value = 9
+        got = 0
+        listen.once(v => { got = v }, {current: true})
+        ok(got == 9, 'once(current) reads changed external value')
+    }
+
+    console.log('\n[listen-store] per-subscription getter overrides wrapper provider')
+    {
+        const box = {value: 1}
+        const [emit, listen] = listenStore<[number]>({current: () => [box.value]})
+        emit(7)
+        let got = 0
+        listen.on(v => { got = v }, {current: () => [42]})
+        ok(got == 42, 'per-call current getter is used for that subscriber')
+    }
+
+    console.log('\n[listen-store] normal events still flow through the wrapper')
+    {
+        const box = {value: 1}
+        const [emit, listen] = listenStore<[number]>({current: () => [box.value]})
+        const seen: number[] = []
+        const off = listen.on(v => seen.push(v))
+        emit(5)
+        off()
+        emit(6)
+        ok(JSON.stringify(seen) == '[5]', 'wrapper delegates event delivery and off() to base listen')
+    }
+
+    console.log(`\n${fails == 0 ? 'ALL GREEN' : fails + ' FAILURE(S)'}`)
+    process.exit(fails == 0 ? 0 : 1)
+}
+
+main().catch(e => { console.error(e); process.exit(1) })

package/observe/listen.test.ts

@@ -0,0 +1,92 @@
+import {createListen, createListenCore, getListenByOn, isListenOn, listenStore} from '../src/Common/events/Listen'
+
+let fails = 0
+const ok = (condition: any, message: string) => {
+    if (!condition) { fails++; console.log('  FAIL', message) }
+    else console.log('  OK  ', message)
+}
+
+async function main() {
+    console.log('\n[listen] core compatibility')
+    {
+        const listen = createListenCore<[number]>()
+        const seen: number[] = []
+        const off = listen.on(v => seen.push(v))
+        listen.emit(1)
+        off()
+        listen.emit(2)
+        listen.once(v => seen.push(v * 10))
+        listen.emit(3)
+        listen.emit(4)
+        ok(seen.join(',') == '1,30', 'core exposes on/off/once behavior')
+        ok(listen.count() == 0, 'core once removes itself')
+        ok(isListenOn(listen.on) && getListenByOn(listen.on) === listen, 'core on is registered for Listen identity checks')
+    }
+    {
+        const listen = createListenCore<[number]>()
+        const seen: number[] = []
+        const cb = (v: number) => seen.push(v)
+        const off = listen.on(cb)
+        listen.emit(1)
+        off()
+        listen.emit(2)
+        listen.on(cb)
+        listen.on(cb)
+        listen.on(v => seen.push(v * 10))
+        listen.off(cb)
+        listen.emit(3)
+        ok(seen.join(',') == '1,30', 'off(cb) removes matching callbacks')
+        ok(listen.count() == 1, 'off(cb) leaves unrelated subscribers')
+    }
+
+    console.log('\n[listen] store once(current) fallback')
+    {
+        let reads = 0
+        const [emit, listen] = listenStore<[number]>({current: () => ++reads == 1 ? undefined : [7]})
+        const seen: number[] = []
+        listen.once(v => seen.push(v), {current: true})
+        emit(8)
+        emit(9)
+        ok(seen.join(',') == '8', 'once(current) without current waits for one future event')
+        ok(reads == 1, 'fallback does not ask current provider twice')
+    }
+    {
+        const [_emit, listen] = listenStore<[number]>({current: () => [5]})
+        const seen: number[] = []
+        const off = listen.once(v => seen.push(v), {current: true})
+        off()
+        ok(seen.join(',') == '5' && listen.count() == 0, 'once(current) with current does not subscribe')
+    }
+
+    console.log('\n[listen] close hook parity')
+    {
+        const listen = createListen<[number]>(() => {})
+        const order: string[] = []
+        listen.onClose(() => order.push('stream1'))
+        listen.on(() => {}, {cbClose: () => order.push('sub')})
+        listen.onClose(() => order.push('stream2'))
+        listen.close()
+        ok(order.join(',') == 'stream1,sub,stream2', 'close hooks fire in insertion order like Listen.ts')
+    }
+    {
+        const listen = createListen<[number]>(() => {})
+        let closed = 0
+        const off = listen.on(() => {}, {cbClose: () => closed++})
+        off()
+        listen.close()
+        ok(closed == 0, 'off removes per-sub cbClose before close')
+    }
+    {
+        const listen = createListen<[number]>(() => {})
+        let closed = 0
+        listen.on(() => {}, {key: 'slot', cbClose: () => closed++})
+        listen.on(() => {}, {key: 'slot', cbClose: () => closed += 10})
+        listen.close()
+        ok(closed == 10, 'key replacement removes previous cbClose')
+    }
+
+    console.log(`\n${fails == 0 ? 'ALL GREEN' : fails + ' FAILURE(S)'}`)
+    process.exit(fails == 0 ? 0 : 1)
+}
+
+main().catch(e => { console.error(e); process.exit(1) })

package/observe/reactive.test.ts

@@ -0,0 +1,270 @@
+// ============================================================
+//  observe/reactive.test.ts — oracle for reactive.ts
+//   npx tsx observe/reactive.test.ts
+// ============================================================
+
+import {reactive, onUpdate, onUpdatePaths, flushReactive, listenUpdate, listenUpdatePaths, toRaw} from './reactive'
+
+type Fn = () => void
+let fails = 0
+const ok = (c: any, m: string) => { if (!c) { fails++; console.log('  FAIL', m) } else console.log('  OK  ', m) }
+const sum = (o: any) => Object.values(o).reduce((a: any, b: any) => a + b, 0) as number
+
+let pending: Fn | null = null
+const manual = {drain: (f: Fn) => { pending = f }}
+const flush = () => { const f = pending; pending = null; if (f) f() }
+const tick = () => new Promise<void>(resolve => setTimeout(resolve, 0))
+
+async function main() {
+    console.log('\n[1] plain + nested read/write')
+    {
+        const s = reactive({price: 0, a: {b: {c: 1}}}, manual)
+        s.price = 100; s.a.b.c = 5
+        ok(s.price == 100 && s.a.b.c == 5, 'reads/writes at any depth, as a normal object')
+    }
+
+    console.log('\n[2] cold = cheap (no subscribers -> set schedules nothing)')
+    {
+        const s = reactive({x: 0}, manual); pending = null
+        s.x = 1; s.x = 2
+        ok(pending == null && s.x == 2, 'set with zero subscribers does not schedule a drain')
+    }
+
+    console.log('\n[3] FACT once per settled batch, on a consistent state')
+    {
+        const s = reactive<{balances: Record<string, number>}>({balances: {BTC: 1, ETH: 10}}, manual)
+        let fires = 0, seen = -1
+        onUpdate(s.balances, () => { fires++; seen = sum(s.balances) })
+        s.balances['BTC'] = 2; s.balances['SOL'] = 3
+        ok(fires == 0, 'nothing fires before the drain')
+        flush()
+        ok(fires == 1, 'one fact for the whole burst: ' + fires)
+        ok(seen == 2 + 10 + 3, 'recomputed on the FINAL consistent state: ' + seen)
+    }
+
+    console.log('\n[4] the $500 case: replace the WHOLE map, sum unchanged -> no false alarm')
+    {
+        const s = reactive<{balances: Record<string, number>}>({balances: {BTC: 100, ETH: 400}}, manual)
+        const alarms: number[] = []
+        onUpdate(s.balances, () => { const t = sum(s.balances); if (t != 500) alarms.push(t) })
+        s.balances = {SOL: 250, DOT: 150, ADA: 100}
+        flush()
+        ok(alarms.length == 0, 'sum stayed 500 across a wholesale replace: ' + JSON.stringify(alarms))
+        ok(sum(s.balances) == 500, 'reads the new consistent collection: ' + sum(s.balances))
+    }
+
+    console.log('\n[5] replace a node in the MIDDLE; subscriber on it survives + deep writes re-bind')
+    {
+        const s = reactive<any>({a: {b: {c: {x: 0}}}}, manual)
+        let onB = 0
+        onUpdate(s.a.b, () => onB++)
+        s.a.b = {c: {x: 1}}
+        flush()
+        ok(onB == 1 && s.a.b.c.x == 1, 'B-subscriber survived wholesale replace: ' + onB)
+        s.a.b.c.x = 2
+        flush()
+        ok(onB == 2 && s.a.b.c.x == 2, 'deep write into replaced sub-tree fires B again: ' + onB)
+    }
+
+    console.log('\n[6] watch root = watch everything; delete fires too')
+    {
+        const s = reactive<any>({a: {b: 1}, list: {k: 1}}, manual)
+        let hits = 0
+        onUpdate(s, () => hits++)
+        s.a.b = 9
+        flush(); const after1 = hits
+        delete s.list.k
+        flush()
+        ok(after1 == 1 && hits == 2, 'root subscriber sees deep set AND delete: ' + hits)
+    }
+
+    console.log('\n[7] unsubscribe before flush suppresses callback')
+    {
+        const s = reactive<any>({a: {x: 1}}, manual)
+        let hits = 0
+        const off = onUpdate(s.a, () => hits++)
+        s.a.x = 2
+        off()
+        flush()
+        ok(hits == 0, 'removed subscriber is not called from an already queued batch')
+    }
+
+    console.log('\n[8] mutation inside callback re-queues into a follow-up drain')
+    {
+        const s = reactive({x: 0}, {drain: 'micro'})
+        let hits = 0
+        onUpdate(s, () => { hits++; if (hits == 1) s.x = 2 })
+        s.x = 1
+        await flushReactive(s)
+        ok(hits == 2 && s.x == 2, 'cascaded update settles without sync recursion: ' + hits)
+    }
+
+    console.log('\n[9] arrays are reactive plain containers')
+    {
+        const s = reactive<any>({arr: [{x: 1}]}, manual)
+        let hits = 0
+        onUpdate(s.arr, () => hits++)
+        s.arr[0].x = 2
+        s.arr.push({x: 3})
+        flush()
+        ok(hits == 1 && s.arr.length == 2 && s.arr[0].x == 2, 'index write + push coalesce on array: ' + hits)
+        ok(Array.isArray(s.arr), 'wrapped array still passes Array.isArray')
+        ok(JSON.stringify(s.arr) == '[{"x":2},{"x":3}]', 'wrapped array JSON stays array-shaped')
+    }
+
+    console.log('\n[9b] captured array proxy follows object rebind without array invariant throws')
+    {
+        const s = reactive<any>({arr: [{x: 1}]}, manual)
+        const a = s.arr
+        s.arr = {x: 1}
+        ok(JSON.stringify(a) == '{"x":1}', 'captured array proxy serializes current object target')
+        ok(JSON.stringify(Object.keys(a)) == '["x"]', 'Object.keys on rebound array proxy returns object keys')
+    }
+
+    console.log('\n[10] Date/Map/class instances are opaque leaves, not proxied')
+    {
+        class Box { constructor(public x: number) {} inc() { this.x++; return this.x } }
+        const d = new Date(1000)
+        const m = new Map<string, number>([['a', 1]])
+        const b = new Box(1)
+        const s = reactive({d, m, b}, manual)
+        ok(s.d === d && s.d.getTime() == 1000, 'Date methods keep their native receiver')
+        ok(s.m === m && s.m.get('a') == 1, 'Map stays raw')
+        ok(s.b === b && s.b.inc() == 2, 'class instance stays raw')
+    }
+
+    console.log('\n[11] depth makes deeper objects opaque')
+    {
+        const s = reactive<any>({a: {b: {x: 1}}}, {...manual, depth: 1})
+        let hits = 0
+        onUpdate(s.a, () => hits++)
+        s.a.b.x = 2
+        flush()
+        ok(hits == 0, 'deep write below depth is intentionally opaque')
+        s.a.b = {x: 3}
+        flush()
+        ok(hits == 1, 'replace at the wrapped level still fires: ' + hits)
+    }
+
+    console.log('\n[12] callback errors do not stop sibling subscribers')
+    {
+        const s = reactive({x: 0}, manual)
+        let sibling = 0
+        let uncaught: any = null
+        process.once('uncaughtException', e => { uncaught = e })
+        onUpdate(s, () => { throw new Error('boom') })
+        onUpdate(s, () => { sibling++ })
+        s.x = 1
+        flush()
+        await tick()
+        ok(sibling == 1, 'sibling subscriber still ran after another subscriber threw')
+        ok(uncaught?.message == 'boom', 'callback error is re-thrown asynchronously')
+    }
+
+    console.log('\n[13] listenUpdate exposes updates as project Listen')
+    {
+        const s = reactive({a: {b: 1}}, manual)
+        pending = null
+        const updates = listenUpdate(s.a)
+        s.a.b = 2
+        ok(pending == null, 'listenUpdate is cold until it has downstream listeners')
+        let hits = 0
+        const off = updates.on(() => hits++)
+        s.a.b = 3
+        flush()
+        ok(hits == 1, 'listenUpdate fired through on')
+        off()
+        pending = null
+        s.a.b = 4
+        ok(pending == null, 'listenUpdate returns cold after last listener leaves')
+        flush()
+        ok(hits == 1, 'listenUpdate off() removed subscriber')
+    }
+
+    console.log('\n[14] descriptor writes go to the reactive target')
+    {
+        const s = reactive<{x: number; y?: number}>({x: 1}, manual)
+        let hits = 0
+        onUpdate(s, () => hits++)
+        Object.defineProperty(s, 'y', {value: 2, enumerable: true, configurable: true, writable: true})
+        flush()
+        ok(s.y == 2 && Object.keys(s).includes('y'), 'defineProperty creates visible reactive property')
+        ok(hits == 1, 'defineProperty notifies subscribers')
+
+        const child = reactive({z: 1}, manual)
+        Object.defineProperty(s, 'box' as any, {value: child, enumerable: true, configurable: true, writable: true})
+        ok((toRaw(s) as any).box === toRaw(child) && (toRaw(s) as any).box !== child, 'defineProperty stores raw values, not reactive proxies')
+    }
+
+    console.log('\n[15] deleted child proxies do not bubble into the live tree')
+    {
+        const s = reactive<{a?: {x: number}}>({a: {x: 1}}, manual)
+        const oldA = s.a!
+        let root = 0, child = 0
+        onUpdate(s, () => root++)
+        onUpdate(oldA, () => child++)
+        delete s.a
+        flush()
+        ok(root == 1 && child == 1 && !('a' in s), 'delete notifies root and deleted child once')
+        oldA.x = 2
+        flush()
+        ok(root == 1 && child == 1, 'mutating captured deleted child is detached')
+    }
+
+    console.log('\n[16] duplicate onUpdate callbacks are independent subscriptions')
+    {
+        const s = reactive({x: 0}, manual)
+        let hits = 0
+        const cb = () => hits++
+        const off1 = onUpdate(s, cb)
+        const off2 = onUpdate(s, cb)
+        off1()
+        s.x = 1
+        flush()
+        ok(hits == 1, 'second duplicate subscription remains after first off')
+        off2()
+        s.x = 2
+        flush()
+        ok(hits == 1, 'second off removes remaining duplicate subscription')
+    }
+
+    console.log('\n[17] optional dirty paths are relative to the subscribed node')
+    {
+        const s = reactive<any>({strategies: {a: {status: false}}, rows: [1]}, manual)
+        const got: string[][] = []
+        onUpdatePaths(s.strategies, change => got.push(change.paths.map(p => p.join('.')).sort()))
+        s.strategies.a.status = true
+        flush()
+        s.strategies.b = {status: false}
+        flush()
+        delete s.strategies.a
+        flush()
+        ok(JSON.stringify(got) == '[["a.status"],["b"],["a"]]', 'object set/add/delete paths: ' + JSON.stringify(got))
+
+        const rootGot: string[][] = []
+        onUpdatePaths(s, change => rootGot.push(change.paths.map(p => p.join('.')).sort()))
+        s.rows.push(2)
+        flush()
+        ok(JSON.stringify(rootGot) == '[["rows"]]', 'array mutation dirties the array branch, not splice internals: ' + JSON.stringify(rootGot))
+    }
+
+    console.log('\n[18] listenUpdatePaths exposes dirty paths as a cold Listen')
+    {
+        const s = reactive({a: {b: 1}}, manual)
+        pending = null
+        const updates = listenUpdatePaths(s.a)
+        s.a.b = 2
+        ok(pending == null, 'listenUpdatePaths is cold until it has downstream listeners')
+        let got = ''
+        const off = updates.on(change => { got = change.paths.map(p => p.join('.')).join(',') })
+        s.a.b = 3
+        flush()
+        ok(got == 'b', 'listenUpdatePaths fired with relative dirty path: ' + got)
+        off()
+    }
+
+    console.log(`\n${fails == 0 ? 'ALL GREEN' : fails + ' FAILURE(S)'}`)
+    process.exit(fails == 0 ? 0 : 1)
+}
+
+main().catch(e => { console.error(e); process.exit(1) })

package/observe/reactive.ts

@@ -0,0 +1 @@
+export * from '../src/Common/Observe/reactive';

package/observe/store-manager.test.ts

@@ -0,0 +1,118 @@
+import {
+    createMemoryOfflineStorage,
+    createStore,
+    createStoreManager,
+    exposeStore,
+    exposeStoreReplay,
+    flushReactive,
+    managedStore,
+} from '../src/Common/Observe'
+
+let fails = 0
+const ok = (condition: any, message: string) => {
+    if (!condition) { fails++; console.log('  FAIL', message) }
+    else console.log('  OK  ', message)
+}
+const tick = () => new Promise<void>(resolve => setTimeout(resolve, 0))
+const settle = async (state: object) => { await flushReactive(state); await tick(); await tick() }
+const json = (v: any) => JSON.stringify(v)
+
+type Market = {
+    data: {BTC?: number; ETH?: number}
+    meta: {status?: string}
+}
+
+type Rows = {
+    rows: Record<string, {qty: number}>
+}
+
+async function main() {
+    console.log('\n[store-manager] plan gates and mirror sync')
+    {
+        const server = createStore<Market>({data: {BTC: 1, ETH: 2}, meta: {status: 'ok'}}, {drain: 'micro'})
+        const remote = exposeStore(server)
+        const manager = createStoreManager({
+            market: managedStore.mirror({
+                remote,
+                initial: {data: {}, meta: {}},
+                mask: {data: {BTC: true}, meta: {status: true}},
+                priority: 10,
+                tags: ['route:main', 'bootstrap'],
+                sync: {opts: {current: true, drain: 'micro'}},
+                storeOpts: {drain: 'micro'},
+            }),
+            heavyHistory: managedStore.mirror({
+                remote,
+                initial: {data: {}, meta: {}},
+                mask: true,
+                priority: 1000,
+                tags: ['history'],
+                explicitOnly: true,
+                large: true,
+            }),
+        })
+
+        const defaultPlan = manager.plan()
+        ok(defaultPlan.length == 1 && defaultPlan[0].key == 'market', 'default plan excludes large explicit-only resources')
+        const fullPlan = manager.plan({includeExplicit: true, includeLarge: true})
+        ok(fullPlan[0].key == 'heavyHistory', 'full plan can include high-priority explicit resource')
+
+        let rejected = false
+        try { await manager.start('heavyHistory') }
+        catch { rejected = true }
+        ok(rejected, 'explicitOnly resource rejects implicit start')
+
+        const mirror = await manager.start('market')
+        ok(mirror.state.data.BTC == 1 && mirror.state.data.ETH === undefined && mirror.state.meta.status == 'ok', 'mirror starts with selected mask only')
+
+        server.state.data.BTC = 5
+        server.state.data.ETH = 9
+        server.state.meta.status = 'warn'
+        await settle(server.state)
+        ok(mirror.state.data.BTC == 5 && mirror.state.data.ETH === undefined && mirror.state.meta.status == 'warn', 'mirror keeps syncing selected paths')
+
+        manager.touch('market', 3)
+        const usage = manager.usage().get('market')
+        ok(usage?.count == 1 && usage.weight == 3, 'touch records usage weight for planning')
+
+        manager.stop('market')
+        ok(manager.handles.market.status().state == 'stopped', 'stop updates handle status')
+    }
+
+    console.log('\n[store-manager] offline replay resource')
+    {
+        const backend = createStore<Rows>({rows: {a: {qty: 1}}}, {drain: 'micro'})
+        const exposed = exposeStoreReplay(backend, {history: 100})
+        const storage = createMemoryOfflineStorage()
+        const manager = createStoreManager({
+            rows: managedStore.offline<Rows>({
+                remote: exposed.api.replay,
+                initial: {rows: {}},
+                storage,
+                debounceMs: 0,
+                storeOpts: {drain: 'micro'},
+                tags: ['route:rows'],
+            }),
+        })
+
+        const store = await manager.start('rows')
+        ok(json(store.state) == json(backend.snapshot()), 'offline resource starts from replay keyframe')
+
+        backend.state.rows.b = {qty: 2}
+        await settle(backend.state)
+        ok(store.state.rows.b.qty == 2, 'offline resource stays connected to replay updates')
+
+        await store.flush()
+        const saved = await storage.read<any>('rows')
+        ok(saved?.seq != null && saved.snapshot.rows.b.qty == 2, 'offline resource persists snapshot and seq')
+
+        manager.stopAll()
+        exposed.close()
+        ok(manager.handles.rows.status().state == 'stopped', 'stopAll closes offline resource')
+    }
+
+    console.log(`\n${fails == 0 ? 'ALL GREEN' : fails + ' FAILURE(S)'}`)
+    process.exit(fails == 0 ? 0 : 1)
+}
+
+main().catch(e => { console.error(e); process.exit(1) })

package/observe/store-mirror.example.ts

@@ -0,0 +1,74 @@
+// Run:
+//   npx tsx observe/store-mirror.example.ts
+
+import {createStore, createStoreMirror, exposeStore} from './store'
+import {flushReactive} from './reactive'
+
+type SymbolRef = {exchange: string; category: string; symbol: string}
+type Strategy = {
+    name: string
+    strategyName: string
+    symbols: SymbolRef[]
+    params: any
+    paramsRun: any
+    status: boolean
+    show: boolean
+}
+type StrategyStore = {strategies: Record<string, Strategy>}
+
+const tick = () => new Promise<void>(resolve => setTimeout(resolve, 0))
+const keys = (store: StrategyStore) => Object.keys(store.strategies).sort().join(',') || '-'
+
+async function settle(state: object) {
+    await flushReactive(state)
+    await tick()
+    await tick()
+}
+
+async function main() {
+    // Backend: ordinary mutable control state.
+    const backend = createStore<StrategyStore>({strategies: {}}, {drain: 'micro'})
+
+    // API shape: get/set/replace + changed + changedPaths.
+    // Over RPC the frontend receives the same shape from the SDK client.
+    const exposed = exposeStore(backend)
+    const api = {
+        ...exposed,
+        get(mask?: any) {
+            console.log('pull', JSON.stringify(mask))
+            return exposed.get(mask)
+        },
+    }
+
+    // Frontend: local mirror. UI subscribes locally, not to the network stream.
+    const mirror = createStoreMirror<StrategyStore>(api, {strategies: {}}, {drain: 'micro'})
+    const stopSync = await mirror.sync({strategies: true}, {current: true, drain: 'micro'})
+    const stopUi = mirror.node.strategies.on(() => {
+        console.log('ui strategies:', keys(mirror.state))
+    }, {current: true, drain: 'micro'})
+
+    backend.state.strategies.alpha = {
+        name: 'alpha',
+        strategyName: 'meanReversion',
+        symbols: [{exchange: 'binance', category: 'spot', symbol: 'BTCUSDT'}],
+        params: {period: 20},
+        paramsRun: {},
+        status: false,
+        show: true,
+    }
+    await settle(backend.state)
+
+    backend.state.strategies.alpha.status = true
+    await settle(backend.state)
+
+    delete backend.state.strategies.alpha
+    await settle(backend.state)
+
+    stopUi()
+    stopSync()
+}
+
+main().catch(e => {
+    console.error(e)
+    process.exit(1)
+})