wenay-react2 1.0.33 → 1.0.35

package/lib/common/src/hooks/useReorderBoard.d.ts

@@ -0,0 +1,61 @@
+import { tReorderItem } from './useReorder';
+/** useReorderBoard - the columns extension of useReorder: keyed blocks live in
+ *  VERTICAL columns (plain consumer divs), one block drags between/within them,
+ *  ONE commit on drop. Column "gravity" is pure consumer CSS (justify-content:
+ *  flex-start packs up, flex-end packs down) - the hook never knows it, it
+ *  measures the real layout. Columns can appear/disappear between drags (the
+ *  ref callback registry is live); the set is frozen for the duration of one
+ *  drag. Children of a column div must be exactly its items, 1:1, in order.
+ *  Same non-goals as useReorder: no nesting, no spans/collision packing, no
+ *  autoscroll - that day is a ready-made dnd library. */
+export type tBoardPos = {
+    col: string;
+    index: number;
+};
+export type tBoardColumn = {
+    key: string;
+    items: string[];
+};
+export type tReorderBoardOptions = {
+    /** columns in board order; each column's div children must render items 1:1 */
+    columns: tBoardColumn[];
+    /** ONE commit on drop; skipped when nothing moved */
+    commit: (next: tBoardColumn[]) => void;
+    /** false = this key cannot start a drag (default: all can) */
+    canDrag?: (key: string) => boolean;
+    /** hold before the drag starts; default 0 */
+    holdMs?: number;
+    /** the block was grabbed */
+    onDragStart?: (e: {
+        key: string;
+        from: tBoardPos;
+    }) => void;
+    /** every pointer move while dragging; position = pointer delta in local px */
+    onDragMove?: (e: {
+        key: string;
+        over: tBoardPos;
+        position: {
+            x: number;
+            y: number;
+        };
+    }) => void;
+    /** the target slot changed (compare prev.col != over.col for column crossings) */
+    onOverChange?: (e: {
+        key: string;
+        over: tBoardPos;
+        prev: tBoardPos | null;
+    }) => void;
+    /** drop; committed=false when nothing moved (plain click) */
+    onDragEnd?: (e: {
+        key: string;
+        from: tBoardPos;
+        over: tBoardPos;
+        committed: boolean;
+    }) => void;
+};
+export declare function useReorderBoard(o: tReorderBoardOptions): {
+    columnRef: (col: string) => (el: HTMLElement | null) => void;
+    item: (key: string) => tReorderItem;
+    dragKey: string | null;
+    over: tBoardPos | null;
+};

package/lib/common/src/hooks/useReorderBoard.js

@@ -0,0 +1,232 @@
+import { useEffect, useRef, useState } from 'react';
+import { useDraggableApi } from './useDraggable';
+export function useReorderBoard(o) {
+    const oRef = useRef(o);
+    oRef.current = o;
+    const colEls = useRef(new Map());
+    const refCbs = useRef(new Map());
+    const [dragKey, setDragKey] = useState(null);
+    const geom = useRef(null);
+    const measureCache = useRef(null);
+    /** stable callback ref for a column div; columns can be added at runtime */
+    function columnRef(col) {
+        let cb = refCbs.current.get(col);
+        if (!cb) {
+            cb = el => { el ? colEls.current.set(col, el) : colEls.current.delete(col); };
+            refCbs.current.set(col, cb);
+        }
+        return cb;
+    }
+    const local = (v) => v / (geom.current?.scale ?? 1);
+    /** Nearest column by clamped distance to its rect, then the insertion index
+     *  = how many of that column's items (start centers, excluding the dragged
+     *  one) sit above the dragged center. Targeting always runs against the
+     *  geometry measured at drag START (anti-oscillation, same as useReorder). */
+    function dragTarget(dx, dy) {
+        const g = geom.current;
+        if (!g)
+            return { col: '', index: 0 };
+        const cx = g.draggedCenter.x + dx, cy = g.draggedCenter.y + dy;
+        let best = null, bestD = Infinity;
+        for (const [col, r] of g.colRect) {
+            const px = Math.max(r.x, Math.min(r.x + r.w, cx));
+            const py = Math.max(r.y, Math.min(r.y + r.h, cy));
+            const d = (px - cx) ** 2 + (py - cy) ** 2;
+            if (d < bestD) {
+                bestD = d;
+                best = col;
+            }
+        }
+        if (best == null)
+            return g.from;
+        let index = 0;
+        for (const c of geom.current.centers.get(best) ?? [])
+            if (c.key != dragKey && c.y < cy)
+                index++;
+        return { col: best, index };
+    }
+    /** Simulated commit: the dragged key removed from its column and inserted at
+     *  over - preview and drop share this, so they agree by construction. */
+    function movedColumns(key, over) {
+        return oRef.current.columns.map(c => {
+            let items = c.items.filter(k => k != key);
+            if (c.key == over.col) {
+                const i = Math.max(0, Math.min(items.length, over.index));
+                items = items.slice(0, i).concat(key, items.slice(i));
+            }
+            return { key: c.key, items };
+        });
+    }
+    /** FLIP across columns, all offset-based (transform/transition-immune, see
+     *  useReorder): the dragged block leaves flow via display:none, survivors get
+     *  their preview CSS `order`, and the landing slot becomes a real margin gap
+     *  (draggedHeight + row-gap) on the neighbour - so the column's own CSS
+     *  gravity decides who moves aside (flex-end pushes the blocks ABOVE up).
+     *  One synchronous apply-read-revert, cached per target slot. */
+    function measured(key, over) {
+        const cacheKey = over.col + '#' + over.index;
+        if (measureCache.current?.key == cacheKey)
+            return measureCache.current.pos;
+        const g = geom.current;
+        const keyToEl = new Map();
+        for (const c of oRef.current.columns) {
+            const el = colEls.current.get(c.key);
+            if (!el)
+                continue;
+            const kids = el.children;
+            c.items.forEach((k, i) => { const kid = kids[i]; if (kid)
+                keyToEl.set(k, kid); });
+        }
+        const preview = movedColumns(key, over);
+        const saved = [];
+        const save = (el) => saved.push({ el, order: el.style.order, display: el.style.display, mt: el.style.marginTop, mb: el.style.marginBottom });
+        for (const pc of preview) {
+            pc.items.forEach((k, i) => {
+                const el = keyToEl.get(k);
+                if (!el)
+                    return;
+                save(el);
+                if (k == key)
+                    el.style.display = 'none';
+                else
+                    el.style.order = String(i);
+            });
+        }
+        const target = preview.find(c => c.key == over.col);
+        if (target) {
+            const gap = g.draggedSize.h + (g.rowGap.get(over.col) ?? 0);
+            const afterEl = keyToEl.get(target.items[over.index + 1] ?? '');
+            const beforeEl = keyToEl.get(target.items[over.index - 1] ?? '');
+            if (afterEl)
+                afterEl.style.marginTop = gap + 'px';
+            else if (beforeEl)
+                beforeEl.style.marginBottom = gap + 'px';
+        }
+        const pos = new Map();
+        for (const c of oRef.current.columns)
+            for (const k of c.items) {
+                if (k == key)
+                    continue;
+                const el = keyToEl.get(k);
+                if (el)
+                    pos.set(k, { x: el.offsetLeft, y: el.offsetTop });
+            }
+        saved.reverse().forEach(s => { s.el.style.order = s.order; s.el.style.display = s.display; s.el.style.marginTop = s.mt; s.el.style.marginBottom = s.mb; });
+        measureCache.current = { key: cacheKey, pos };
+        return pos;
+    }
+    const drag = useDraggableApi({ holdMs: o.holdMs ?? 0, onDragEnd: function commitBoard(final) {
+            const key = dragKey;
+            setDragKey(null);
+            measureCache.current = null;
+            const g = geom.current;
+            geom.current = null;
+            if (key == null || !g)
+                return;
+            geom.current = g; // dragTarget/local need it for this last computation
+            const over = dragTarget(local(final.x), local(final.y));
+            const next = movedColumns(key, over);
+            const cur = oRef.current.columns;
+            const committed = next.some((c, i) => c.items.length != cur[i].items.length || c.items.some((k, j) => k != cur[i].items[j]));
+            geom.current = null;
+            if (committed)
+                oRef.current.commit(next);
+            oRef.current.onDragEnd?.({ key, from: g.from, over, committed });
+        } });
+    function beginDrag(key, e) {
+        if (oRef.current.canDrag && !oRef.current.canDrag(key))
+            return false;
+        if (e.target.closest('input, button, select, textarea, a'))
+            return false;
+        const cols = oRef.current.columns;
+        let from = null;
+        for (const c of cols) {
+            const i = c.items.indexOf(key);
+            if (i != -1) {
+                from = { col: c.key, index: i };
+                break;
+            }
+        }
+        const fromEl = from && colEls.current.get(from.col);
+        if (!from || !fromEl)
+            return false;
+        const scale = fromEl.offsetWidth ? fromEl.getBoundingClientRect().width / fromEl.offsetWidth : 1;
+        const g = { scale, from, colRect: new Map(), centers: new Map(), startOffset: new Map(), rowGap: new Map(), draggedCenter: { x: 0, y: 0 }, draggedSize: { w: 0, h: 0 } };
+        for (const c of cols) {
+            const el = colEls.current.get(c.key);
+            if (!el)
+                continue;
+            const r = el.getBoundingClientRect();
+            g.colRect.set(c.key, { x: r.x / scale, y: r.y / scale, w: r.width / scale, h: r.height / scale });
+            g.rowGap.set(c.key, parseFloat(getComputedStyle(el).rowGap) || 0);
+            const kids = el.children;
+            const cs = [];
+            c.items.forEach((k, i) => {
+                const kid = kids[i];
+                if (!kid)
+                    return;
+                const kr = kid.getBoundingClientRect();
+                cs.push({ key: k, y: (kr.y + kr.height / 2) / scale });
+                g.startOffset.set(k, { x: kid.offsetLeft, y: kid.offsetTop });
+                if (k == key) {
+                    g.draggedCenter = { x: (kr.x + kr.width / 2) / scale, y: (kr.y + kr.height / 2) / scale };
+                    g.draggedSize = { w: kid.offsetWidth, h: kid.offsetHeight };
+                }
+            });
+            g.centers.set(c.key, cs);
+        }
+        geom.current = g;
+        measureCache.current = null;
+        setDragKey(key);
+        oRef.current.onDragStart?.({ key, from });
+        return true;
+    }
+    const over = dragKey != null && geom.current
+        ? dragTarget(local(drag.position.x), local(drag.position.y)) : null;
+    // callbacks ride effects (post-render), reading fresh options via oRef
+    const prevOverRef = useRef(null);
+    useEffect(() => {
+        if (dragKey == null || !over) {
+            prevOverRef.current = null;
+            return;
+        }
+        const prev = prevOverRef.current;
+        if (!prev || prev.col != over.col || prev.index != over.index) {
+            oRef.current.onOverChange?.({ key: dragKey, over, prev });
+            prevOverRef.current = { ...over };
+        }
+    });
+    const px = dragKey != null ? drag.position.x : 0, py = dragKey != null ? drag.position.y : 0;
+    useEffect(() => {
+        if (dragKey != null && over)
+            oRef.current.onDragMove?.({ key: dragKey, over, position: { x: px, y: py } });
+    }, [dragKey, px, py]); // eslint-disable-line react-hooks/exhaustive-deps
+    function item(key) {
+        const active = dragKey != null;
+        const dragging = key == dragKey;
+        let style;
+        if (active && geom.current && over) {
+            if (dragging) {
+                style = { transform: `translate(${local(drag.position.x)}px, ${local(drag.position.y)}px)` };
+            }
+            else {
+                const pos = measured(dragKey, over);
+                const a = geom.current.startOffset.get(key), b = pos.get(key);
+                if (a && b && (a.x != b.x || a.y != b.y))
+                    style = { transform: `translate(${b.x - a.x}px, ${b.y - a.y}px)` };
+            }
+        }
+        return {
+            props: {
+                onMouseDown(e) { if (e.button == 0 && beginDrag(key, e))
+                    drag.props.onMouseDown(e); },
+                onTouchStart(e) { if (beginDrag(key, e))
+                    drag.props.onTouchStart(e); },
+            },
+            style,
+            dragging,
+            active,
+        };
+    }
+    return { columnRef, item, dragKey, over };
+}

package/lib/common/src/hooks/useReplay.d.ts

@@ -1,4 +1,6 @@
 import { ObserveAll2, Replay } from "wenay-common2";
+type StoreDrain = ObserveAll2.StoreDrain;
+type StoreEachCtx = ObserveAll2.StoreEachCtx;
 type StorePatch = ObserveAll2.StorePatch;
 type ReplayEvent<Z extends any[]> = Replay.ReplayEvent<Z>;
 type ReplayRemote<Z extends any[]> = Replay.ReplayRemote<Z>;
@@ -21,6 +23,20 @@ export type UseReplaySubscribeOptions = {
     staleMs?: number;
     /** Edge-triggered mirror of common2's onStale (fresh<->stale transitions only). Goes through a ref — a new identity does not resubscribe. */
     onStale?: (info: StaleInfo) => void;
+    /**
+     * Lag policy of the wire subscription (frame model): 'queue' (default) — the socket buffers
+     * everything, nothing is ever skipped; 'frame' — rides the server's frameLine when the remote
+     * has one: on lag the server DROPS events for this client and recovers with a mini-frame.
+     * Without a frameLine (old server, in-proc line) 'frame' degrades to 'queue' in common2.
+     * This picks the wire surface, so changing it resubscribes (reconnects by tail under keepSeq).
+     */
+    policy?: 'queue' | 'frame';
+    /**
+     * Opaque pass-through for the line's `frame` condenser on catch-up (which condensation rule
+     * this client wants). Captured at subscribe time through a ref — a new identity does not
+     * resubscribe; the next (re)subscribe reads the latest value.
+     */
+    hint?: unknown;
 };
 export type ReplaySubscribeController = {
     /** Keyframe/tail catch-up finished, events are live from here. */
@@ -64,6 +80,80 @@ export type StoreReplayMirrorController<T extends object> = StoreReplaySyncContr
  * so reconnect is a journal tail, not a keyframe. A new `remote` recreates the store.
  */
 export declare function useStoreReplayMirror<T extends object>(remote: ReplayRemote<[StorePatch]> | null | undefined, initial: T, options?: UseStoreReplaySyncOptions): StoreReplayMirrorController<T>;
+export type UseStoreReplayEachOptions<T extends object> = UseStoreReplaySyncOptions & {
+    /**
+     * Seed of the internal mirror store. Creation-time only (a later identity change does nothing).
+     * Reconnect after a FULL unmount: pass the saved snapshot together with `since`
+     * ({since: prev.seq(), initial: prev.store.snapshot()}) — the tail lands ON TOP of the previous
+     * state; a fresh empty mirror would not converge.
+     */
+    initial?: T;
+    /** Drain of the internal mirror store — the coalescing window of the per-key feed. Creation-time only. */
+    drain?: StoreDrain;
+};
+/**
+ * Per-key fold over a store replay line — React counterpart of `ObserveAll2.syncStoreReplayEach`
+ * (internal mirror store + syncStoreReplay + store.each()). cb fires once per CHANGED top-level
+ * key per drain window with the current value; the first delivery is the keyframe EXPANDED per
+ * key; (key, undefined) = key deleted — cold start / reconnect are not special cases for per-key
+ * consumers (grid rows, canvas layers, ...). The fold target should live outside React state.
+ *
+ * Unlike the library one-call (a fresh store per call), the mirror here lives in a ref: within
+ * one mounted component every resubscribe (StrictMode double-effect, restart(), enabled toggling,
+ * staleMs/policy change) reconnects by tail ON TOP of the kept state — no snapshot/initial dance.
+ * A new `remote` identity recreates the store (fresh keyframe). Direct reads / extra
+ * subscriptions: controller.store (useStoreNode/useStoreKeys work on it as usual).
+ */
+export declare function useStoreReplayEach<T extends object>(remote: ReplayRemote<[StorePatch]> | null | undefined, cb: (key: string, value: T[keyof T] | undefined, ctx: StoreEachCtx) => void, options?: UseStoreReplayEachOptions<T>): StoreReplayMirrorController<T>;
+export type UseReplayFrameOptions = {
+    /** Pull period, ms. Default 300. */
+    intervalMs?: number;
+    /**
+     * Start position: frame() brings the consumer from here to head. Omit = keyframe start:
+     * keyframe() is polled until the line has one (an empty line is "nothing yet", not an error).
+     * A sacred line (no keyframe) NEEDS an explicit since (0 = full tail) — omitted, it waits forever.
+     */
+    since?: number;
+    /** Keep the last folded seq across remote-identity-stable resubscribes. Default true. */
+    keepSeq?: boolean;
+    /** false = stop pulling (and drop the timer). Default true. */
+    enabled?: boolean;
+    /**
+     * Opaque pass-through for the line's `frame` condenser (which condensation rule this client
+     * wants). Read through a ref on EVERY pull — a new identity neither resubscribes nor is missed.
+     */
+    hint?: unknown;
+    onSeq?: (seq: number) => void;
+    /** frame() failed (network, or a sacred line evicted past our seq — loud by design). Pulling STOPS until restart(). */
+    onError?: (e: unknown) => void;
+};
+export type ReplayFrameController = {
+    /** First successful pull finished (like replaySubscribe's ready — even if the line was still empty). */
+    readonly ready: boolean;
+    /** Last pull error; pulling is stopped while set (restart() clears and re-arms). */
+    readonly error: unknown;
+    /** Last folded seq (reconnect point). Getter — reading it does not re-render. */
+    seq(): number;
+    /** Pull out of schedule now; resolves after folding. hint omitted = the latest options.hint. */
+    pull(hint?: unknown): Promise<void>;
+    /** Re-arm after an error / jump: since omitted = continue from the current seq. */
+    restart(since?: number): void;
+};
+/**
+ * Pull a replay line at YOUR pace (the frame model of common2): a timer around
+ * `remote.frame(seq, hint)` — the server condenses the tail via the line's `frame` lambda
+ * (mini-frame), so a slow consumer never accumulates a backlog and never holds a live socket
+ * subscription. Complements useReplaySubscribe (push): use pull when the consumer wants its own
+ * cadence (e.g. 500ms UI refresh over a fast line) or a client-picked condensation rule (hint).
+ *
+ * Folding contract mirrors the push path: envelopes arrive seq-ascending, already-seen seq are
+ * skipped, a keyframe recovery is just an envelope of the same event type. Fresh start (no since)
+ * = keyframe start like replaySubscribe: keyframe() is polled until the line has one; a sacred
+ * line needs an explicit since. Overlapping pulls are never issued (a slow frame() call skips
+ * timer ticks). A remote without frame() (old server) fails loudly via onError — there is
+ * deliberately no tail fallback here (that is replaySubscribe's job).
+ */
+export declare function useReplayFrame<Z extends any[]>(remote: ReplayRemote<Z> | null | undefined, cb: (...event: Z) => void, options?: UseReplayFrameOptions): ReplayFrameController;
 export type ReplayHistoryLike<Z extends any[]> = {
     at(where?: {
         seq?: number;

package/lib/common/src/hooks/useReplay.js

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { ObserveAll2, Replay } from "wenay-common2";
+import { useStoreEach } from "./useObserveStore";
 /**
  * React bridge over the Replay stack (snapshot + sequenced delta line) of wenay-common2.
  *
@@ -13,10 +14,14 @@ import { ObserveAll2, Replay } from "wenay-common2";
  *   outside via onSeq and pass it back as `since` (see the QA card for the pattern);
  * - a different `remote` identity always starts from scratch (seq from another line is meaningless);
  * - freshness (staleMs/onStale, controller.stale/lastTs()) is detected by wenay-common2;
- *   the hooks only mirror the fresh<->stale edges into React state.
+ *   the hooks only mirror the fresh<->stale edges into React state;
+ * - lag policy is the consumer's pick per subscription (frame model of common2 rev2):
+ *   {policy: 'frame'} rides the server's frameLine when the remote has one (on lag the server
+ *   drops and recovers with a mini-frame; old servers/in-proc lines degrade to 'queue');
+ *   pull-at-own-pace is a separate hook (useReplayFrame) — a timer around remote.frame().
  *
- * Server-side parts of the stack (conflateReplay, archiveReplay) are per-connection/per-process
- * and intentionally have no hooks here.
+ * Server-side parts of the stack (conflateReplay, archiveReplay, createRpcServerAuto replayOpts)
+ * are per-connection/per-process and intentionally have no hooks here.
  */
 function useLatestRef(value) {
     const ref = useRef(value);
@@ -30,9 +35,10 @@ function useLatestRef(value) {
  * cb goes through a ref — a new cb identity does not resubscribe.
  */
 export function useReplaySubscribe(remote, cb, options = {}) {
-    const { since, keepSeq = true, enabled = true, onSeq, onError, staleMs, onStale } = options;
+    const { since, keepSeq = true, enabled = true, onSeq, onError, staleMs, onStale, policy, hint } = options;
     const cbRef = useLatestRef(cb);
     const hooksRef = useLatestRef({ onSeq, onError, onStale });
+    const hintRef = useLatestRef(hint);
     const seqRef = useRef(since);
     const subRef = useRef(null);
     const lastRemoteRef = useRef(undefined);
@@ -55,6 +61,8 @@ export function useReplaySubscribe(remote, cb, options = {}) {
             setStale(false);
         const off = Replay.replaySubscribe(remote, (...event) => cbRef.current(...event), {
             since: seqRef.current,
+            policy,
+            hint: hintRef.current,
             onSeq: seq => {
                 seqRef.current = seq;
                 hooksRef.current.onSeq?.(seq);
@@ -90,9 +98,10 @@ export function useReplaySubscribe(remote, cb, options = {}) {
                 seqRef.current = since;
         };
         // keepSeq/since are start-position config, not subscription identity — no resubscribe on change;
-        // staleMs is subscribe-time config in common2, so changing it resubscribes
+        // staleMs is subscribe-time config in common2, so changing it resubscribes;
+        // policy picks the wire surface (line vs frameLine), so it resubscribes too; hint rides a ref
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [remote, enabled, epoch, staleMs]);
+    }, [remote, enabled, epoch, staleMs, policy]);
     const seq = useCallback(() => subRef.current?.seq() ?? seqRef.current ?? -1, []);
     const lastTs = useCallback(() => subRef.current?.lastTs() ?? 0, []);
     const restart = useCallback((at) => {
@@ -109,8 +118,9 @@ export function useReplaySubscribe(remote, cb, options = {}) {
  * (useStoreNode/useStoreSelect).
  */
 export function useStoreReplaySync(store, remote, options = {}) {
-    const { since, keepSeq = true, enabled = true, onSeq, onError, staleMs, onStale } = options;
+    const { since, keepSeq = true, enabled = true, onSeq, onError, staleMs, onStale, policy, hint } = options;
     const hooksRef = useLatestRef({ onSeq, onError, onStale });
+    const hintRef = useLatestRef(hint);
     const seqRef = useRef(since);
     const subRef = useRef(null);
     const lastRemoteRef = useRef(undefined);
@@ -131,6 +141,8 @@ export function useStoreReplaySync(store, remote, options = {}) {
             setStale(false); // see useReplaySubscribe: stale re-syncs from common2, no reset-to-false flicker
         const off = ObserveAll2.syncStoreReplay(store, remote, {
             since: seqRef.current,
+            policy,
+            hint: hintRef.current,
             onSeq: seq => {
                 seqRef.current = seq;
                 hooksRef.current.onSeq?.(seq);
@@ -166,7 +178,7 @@ export function useStoreReplaySync(store, remote, options = {}) {
                 seqRef.current = since;
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [store, remote, enabled, epoch, staleMs]);
+    }, [store, remote, enabled, epoch, staleMs, policy]);
     const seq = useCallback(() => subRef.current?.seq() ?? seqRef.current ?? -1, []);
     const lastTs = useCallback(() => subRef.current?.lastTs() ?? 0, []);
     const restart = useCallback((at) => {
@@ -190,6 +202,141 @@ export function useStoreReplayMirror(remote, initial, options = {}) {
     const sync = useStoreReplaySync(store, remote, options);
     return useMemo(() => ({ ...sync, store }), [sync, store]);
 }
+/**
+ * Per-key fold over a store replay line — React counterpart of `ObserveAll2.syncStoreReplayEach`
+ * (internal mirror store + syncStoreReplay + store.each()). cb fires once per CHANGED top-level
+ * key per drain window with the current value; the first delivery is the keyframe EXPANDED per
+ * key; (key, undefined) = key deleted — cold start / reconnect are not special cases for per-key
+ * consumers (grid rows, canvas layers, ...). The fold target should live outside React state.
+ *
+ * Unlike the library one-call (a fresh store per call), the mirror here lives in a ref: within
+ * one mounted component every resubscribe (StrictMode double-effect, restart(), enabled toggling,
+ * staleMs/policy change) reconnects by tail ON TOP of the kept state — no snapshot/initial dance.
+ * A new `remote` identity recreates the store (fresh keyframe). Direct reads / extra
+ * subscriptions: controller.store (useStoreNode/useStoreKeys work on it as usual).
+ */
+export function useStoreReplayEach(remote, cb, options = {}) {
+    const { initial, drain, ...syncOptions } = options;
+    const storeRef = useRef(null);
+    if (!storeRef.current || storeRef.current.remote !== remote) {
+        storeRef.current = { remote, store: ObserveAll2.createStore((initial ?? {}), drain !== undefined ? { drain } : undefined) };
+    }
+    const store = storeRef.current.store;
+    // each BEFORE sync: effects run in hook-call order, so the per-key subscriber already exists
+    // when the keyframe applies to the store (the expansion is not missed)
+    useStoreEach(store, cb, { enabled: syncOptions.enabled });
+    const sync = useStoreReplaySync(store, remote, syncOptions);
+    return useMemo(() => ({ ...sync, store }), [sync, store]);
+}
+/**
+ * Pull a replay line at YOUR pace (the frame model of common2): a timer around
+ * `remote.frame(seq, hint)` — the server condenses the tail via the line's `frame` lambda
+ * (mini-frame), so a slow consumer never accumulates a backlog and never holds a live socket
+ * subscription. Complements useReplaySubscribe (push): use pull when the consumer wants its own
+ * cadence (e.g. 500ms UI refresh over a fast line) or a client-picked condensation rule (hint).
+ *
+ * Folding contract mirrors the push path: envelopes arrive seq-ascending, already-seen seq are
+ * skipped, a keyframe recovery is just an envelope of the same event type. Fresh start (no since)
+ * = keyframe start like replaySubscribe: keyframe() is polled until the line has one; a sacred
+ * line needs an explicit since. Overlapping pulls are never issued (a slow frame() call skips
+ * timer ticks). A remote without frame() (old server) fails loudly via onError — there is
+ * deliberately no tail fallback here (that is replaySubscribe's job).
+ */
+export function useReplayFrame(remote, cb, options = {}) {
+    const { intervalMs = 300, since, keepSeq = true, enabled = true, hint, onSeq, onError } = options;
+    const cbRef = useLatestRef(cb);
+    const hooksRef = useLatestRef({ onSeq, onError });
+    const hintRef = useLatestRef(hint);
+    const seqRef = useRef(since ?? -1);
+    const pullRef = useRef(null);
+    const lastRemoteRef = useRef(undefined);
+    const [ready, setReady] = useState(false);
+    const [error, setError] = useState(null);
+    const [epoch, setEpoch] = useState(0);
+    useEffect(() => {
+        if (!remote || !enabled)
+            return;
+        if (lastRemoteRef.current !== undefined && lastRemoteRef.current !== remote)
+            seqRef.current = since ?? -1; // a different line — old seq is meaningless
+        lastRemoteRef.current = remote;
+        let alive = true;
+        let stopped = false;
+        let timer = null;
+        let inflight = null;
+        setReady(false);
+        setError(null);
+        const fail = (e) => {
+            stopped = true;
+            if (timer) {
+                clearInterval(timer);
+                timer = null;
+            }
+            setError(e);
+            hooksRef.current.onError?.(e);
+        };
+        const pull = (hintArg) => {
+            if (inflight)
+                return inflight; // a slow frame() skips ticks, pulls never overlap
+            if (stopped || !alive)
+                return Promise.resolve();
+            const frame = remote.frame;
+            if (!frame) {
+                fail(new Error("useReplayFrame: remote has no frame() (old server) — use useReplaySubscribe"));
+                return Promise.resolve();
+            }
+            inflight = (async () => {
+                try {
+                    // no position yet -> keyframe start, mirroring replaySubscribe's catch-up for since<0:
+                    // frame(-1) has no tail to return and THROWS on a still-empty line, which is not an
+                    // error here — poll keyframe() until the line has one, then switch to frame(seq)
+                    const envs = seqRef.current < 0
+                        ? await Promise.resolve(remote.keyframe()).then(kf => kf ? [kf] : null)
+                        : await frame(seqRef.current, hintArg !== undefined ? hintArg : hintRef.current);
+                    if (!alive)
+                        return;
+                    for (const ev of envs ?? []) {
+                        if (ev.seq <= seqRef.current)
+                            continue;
+                        seqRef.current = ev.seq;
+                        cbRef.current(...ev.event);
+                        hooksRef.current.onSeq?.(ev.seq);
+                    }
+                    setReady(true);
+                }
+                catch (e) {
+                    if (alive)
+                        fail(e);
+                }
+                finally {
+                    inflight = null;
+                }
+            })();
+            return inflight;
+        };
+        pullRef.current = pull;
+        void pull();
+        if (!stopped)
+            timer = setInterval(() => { void pull(); }, intervalMs); // a sync throw in the first pull may already have stopped us
+        return () => {
+            alive = false;
+            pullRef.current = null;
+            if (timer)
+                clearInterval(timer);
+            if (!keepSeq)
+                seqRef.current = since ?? -1;
+        };
+        // since/keepSeq are start-position config, hint rides a ref — only the pace and identity resubscribe
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [remote, enabled, epoch, intervalMs]);
+    const seq = useCallback(() => seqRef.current, []);
+    const pull = useCallback((hintArg) => pullRef.current?.(hintArg) ?? Promise.resolve(), []);
+    const restart = useCallback((at) => {
+        if (at !== undefined)
+            seqRef.current = at;
+        setEpoch(v => v + 1);
+    }, []);
+    return useMemo(() => ({ ready, error, seq, pull, restart }), [ready, error, seq, pull, restart]);
+}
 /**
  * Time machine over `Replay.openHistory(storage, live?)`: scrubber/pause/resume for any replay line.
  * `apply` folds ONE event into the consumer state (draw a frame, apply a store patch, ...) —

package/lib/common/src/styles/tokens.d.ts

@@ -57,6 +57,23 @@ export declare const tokens: {
         readonly navBg: "#17202e";
         readonly navWidth: "168px";
     };
+    /** Toolbar (createToolbar) chrome (--tb-*). Dark defaults; apps re-skin via :root[data-theme]. */
+    readonly tb: {
+        readonly bg: "transparent";
+        readonly border: "none";
+        readonly radius: "6px";
+        readonly gap: "2px";
+        /** var(--color-text-base) in CSS */
+        readonly itemColor: "#c4c4c4";
+        readonly itemHoverBg: "rgba(255, 255, 255, 0.08)";
+        readonly itemRadius: "6px";
+        /** var(--color-bg-dark) in CSS */
+        readonly popBg: "#131821";
+        /** var(--color-border-common) in CSS */
+        readonly popBorder: "1px solid rgb(50, 62, 71)";
+        readonly popRadius: "8px";
+        readonly popShadow: "0 8px 28px rgba(0, 0, 0, 0.5)";
+    };
     readonly font: {
         readonly family: "Roboto";
         readonly sizeBase: "12px";