wenay-react2 1.0.32 → 1.0.34

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

@@ -2,6 +2,7 @@ import { ObserveAll2, Replay } from "wenay-common2";
 type StorePatch = ObserveAll2.StorePatch;
 type ReplayEvent<Z extends any[]> = Replay.ReplayEvent<Z>;
 type ReplayRemote<Z extends any[]> = Replay.ReplayRemote<Z>;
+type StaleInfo = Replay.StaleInfo;
 export type UseReplaySubscribeOptions = {
     /** Start position for the first subscription: journal tail after this seq; omit = keyframe. */
     since?: number;
@@ -11,13 +12,44 @@ export type UseReplaySubscribeOptions = {
     enabled?: boolean;
     onSeq?: (seq: number) => void;
     onError?: (e: unknown) => void;
+    /**
+     * Producer-freshness watchdog (detection lives in wenay-common2): no event with a fresh
+     * producer ts for staleMs -> `stale` flips true, flips back on resume. Omitted = zero cost
+     * (no watchdog, no extra state updates). Changing staleMs resubscribes (reconnects by tail
+     * under keepSeq, so it is cheap).
+     */
+    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. */
     readonly ready: boolean;
     readonly error: unknown;
+    /**
+     * Line is stale by the staleMs watchdog. React state, but it updates ONLY on fresh<->stale
+     * transitions — a high-frequency line causes zero extra renders while fresh.
+     * Always false without staleMs.
+     */
+    readonly stale: boolean;
     /** Last seen seq (reconnect point). Getter — reading it does not re-render. */
     seq(): number;
+    /** Producer ts of the last delivered event (0 before the first delivery). Getter — reading it does not re-render. */
+    lastTs(): number;
     /** Drop and re-create the subscription. since omitted = continue by keepSeq rules; a number = explicit position. */
     restart(since?: number): void;
 };
@@ -46,6 +78,55 @@ 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 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

@@ -11,10 +11,16 @@ import { ObserveAll2, Replay } from "wenay-common2";
  *   (ref/store/canvas). If the consumer state resets on resubscribe, pass {keepSeq: false};
  * - a FULL unmount loses the hook's refs: to reconnect by tail after a remount, keep the position
  *   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).
+ * - 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;
+ * - 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);
@@ -28,14 +34,16 @@ 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 } = options;
+    const { since, keepSeq = true, enabled = true, onSeq, onError, staleMs, onStale, policy, hint } = options;
     const cbRef = useLatestRef(cb);
-    const hooksRef = useLatestRef({ onSeq, onError });
+    const hooksRef = useLatestRef({ onSeq, onError, onStale });
+    const hintRef = useLatestRef(hint);
     const seqRef = useRef(since);
     const subRef = useRef(null);
     const lastRemoteRef = useRef(undefined);
     const [ready, setReady] = useState(false);
     const [error, setError] = useState(null);
+    const [stale, setStale] = useState(false);
     const [epoch, setEpoch] = useState(0);
     useEffect(() => {
         if (!remote || !enabled)
@@ -46,8 +54,14 @@ export function useReplaySubscribe(remote, cb, options = {}) {
         let alive = true;
         setReady(false);
         setError(null);
+        // stale is NOT reset here: it re-syncs from common2 after the first delivery (a stale
+        // keyframe must show stale from the start, not flicker through false on resubscribe)
+        if (staleMs === undefined)
+            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);
@@ -57,10 +71,23 @@ export function useReplaySubscribe(remote, cb, options = {}) {
                     setError(e);
                 hooksRef.current.onError?.(e);
             },
+            ...(staleMs !== undefined ? {
+                staleMs,
+                onStale: (info) => {
+                    if (alive)
+                        setStale(info.stale);
+                    hooksRef.current.onStale?.(info);
+                },
+            } : null),
         });
         subRef.current = off;
-        off.ready.then(() => { if (alive)
-            setReady(true); }, e => { if (alive)
+        off.ready.then(() => {
+            if (!alive)
+                return;
+            setReady(true);
+            if (staleMs !== undefined)
+                setStale(off.isStale()); // fresh line after a stale one: no edge from common2, sync by hand
+        }, e => { if (alive)
             setError(e); });
         return () => {
             alive = false;
@@ -69,16 +96,19 @@ export function useReplaySubscribe(remote, cb, options = {}) {
             if (!keepSeq)
                 seqRef.current = since;
         };
-        // keepSeq/since are start-position config, not subscription identity — no resubscribe on change
+        // keepSeq/since are start-position config, not subscription identity — no resubscribe on change;
+        // 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]);
+    }, [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) => {
         if (at !== undefined)
             seqRef.current = at;
         setEpoch(v => v + 1);
     }, []);
-    return useMemo(() => ({ ready, error, seq, restart }), [ready, error, seq, restart]);
+    return useMemo(() => ({ ready, error, stale, seq, lastTs, restart }), [ready, error, stale, seq, lastTs, restart]);
 }
 /**
  * Sync an existing mirror store from a store replay line (`ObserveAll2.exposeStoreReplay(...).api.replay`).
@@ -87,13 +117,15 @@ export function useReplaySubscribe(remote, cb, options = {}) {
  * (useStoreNode/useStoreSelect).
  */
 export function useStoreReplaySync(store, remote, options = {}) {
-    const { since, keepSeq = true, enabled = true, onSeq, onError } = options;
-    const hooksRef = useLatestRef({ onSeq, onError });
+    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);
     const [ready, setReady] = useState(false);
     const [error, setError] = useState(null);
+    const [stale, setStale] = useState(false);
     const [epoch, setEpoch] = useState(0);
     useEffect(() => {
         if (!store || !remote || !enabled)
@@ -104,8 +136,12 @@ export function useStoreReplaySync(store, remote, options = {}) {
         let alive = true;
         setReady(false);
         setError(null);
+        if (staleMs === undefined)
+            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);
@@ -115,10 +151,23 @@ export function useStoreReplaySync(store, remote, options = {}) {
                     setError(e);
                 hooksRef.current.onError?.(e);
             },
+            ...(staleMs !== undefined ? {
+                staleMs,
+                onStale: (info) => {
+                    if (alive)
+                        setStale(info.stale);
+                    hooksRef.current.onStale?.(info);
+                },
+            } : null),
         });
         subRef.current = off;
-        off.ready.then(() => { if (alive)
-            setReady(true); }, e => { if (alive)
+        off.ready.then(() => {
+            if (!alive)
+                return;
+            setReady(true);
+            if (staleMs !== undefined)
+                setStale(off.isStale());
+        }, e => { if (alive)
             setError(e); });
         return () => {
             alive = false;
@@ -128,14 +177,15 @@ export function useStoreReplaySync(store, remote, options = {}) {
                 seqRef.current = since;
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [store, remote, enabled, epoch]);
+    }, [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) => {
         if (at !== undefined)
             seqRef.current = at;
         setEpoch(v => v + 1);
     }, []);
-    return useMemo(() => ({ ready, error, seq, restart }), [ready, error, seq, restart]);
+    return useMemo(() => ({ ready, error, stale, seq, lastTs, restart }), [ready, error, stale, seq, lastTs, restart]);
 }
 /**
  * Convenience: create a local mirror store and keep it synced from a store replay line.
@@ -151,6 +201,115 @@ export function useStoreReplayMirror(remote, initial, options = {}) {
     const sync = useStoreReplaySync(store, remote, options);
     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";

package/lib/common/src/styles/tokens.js

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