dsh-mega-chat-nav 0.1.1

package/lib/client/QuestionNavStrip.js

@@ -0,0 +1,555 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Question-nav minimap. Renders a vertical column of small round dots overlaid
+ * on the LEFT edge of the conversation column (via the frame-wide
+ * `shell.overlay` floating layer): one dot per turn that claimed at least one
+ * user question — strictly aligned with the Trajectory view's turn numbering
+ * (turns without a question produce no dot). The dot column is vertically
+ * centered and clamped to at most 60% of the conversation height, scrolling
+ * within that band when the session has more dots than fit.
+ *
+ * Hovering a dot "selects" it: the selected dot plus its two immediate
+ * neighbors on each side magnify (progressively smaller with distance), and a
+ * vertical cascade of question cards opens — the selected (center) card is the
+ * focus (brand accent, elevated, full question text), the four neighbors are
+ * narrower context cards clamped to fewer lines. Every card is clickable and
+ * jumps to its question, exactly like clicking the dot. Hovering never scrolls
+ * the band — the dot column stays put while you browse.
+ *
+ * Overflow is paged, not auto-scrolled: two small triangle buttons in the dot
+ * style sit above and below the dot queue (▲ / ▼), each click revealing one
+ * page of hidden dots (the page size is configurable in the plugin settings,
+ * default 5) with a staggered pop-in animation as click feedback. The native
+ * scrollbar stays hidden; the triangles themselves are the overflow cue (each
+ * appears only while its direction has more to reveal) — no hover auto-scroll
+ * of any kind.
+ *
+ * A scroll-spy marks the reader's position: the dot of the turn at the
+ * reading line (35% down the scrollport) carries a ring marker that follows
+ * the conversation as it scrolls, streams, or pages its window. The marker
+ * never scrolls the band — it is purely a position indicator.
+ *
+ * Data source: the host-folded `msgNavMessages` session projection (whole
+ * history, persisted host-side, pushed live through session/projection
+ * frames) read through the injected `questionProjection` face, plus the live
+ * chat window's questions merged on top for the brief window before a
+ * just-sent question lands in the projection. No render-window expansion, no
+ * client-side history paging.
+ *
+ * Data arrives through the props shares: the framework `useSessions` hook
+ * (current session), the registrant inject face (read/subscribe/project/
+ * jump), and the bound locale translator.
+ */
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { groupQuestionsByTurn, mergeLiveQuestions } from "../core/turn-dots.js";
+import { DOT_GAP, DOT_SIZE, FOCUS_RADIUS, clampScrollTop, focusCardMetrics, focusScale, focusTier, pageStep } from "../core/focus.js";
+import { pickActiveDot, readingLineOffset } from "../core/active-dot.js";
+import { formatQuestionTime } from "../core/time.js";
+const FAILURE_HINTS = {
+    VIEW_INACTIVE: 'jump.inactive',
+    TARGET_HIDDEN: 'jump.hidden',
+    NOT_FOUND: 'jump.notfound',
+    TIMEOUT: 'jump.timeout',
+};
+/** Read the projection face value as a question-entry list (structural guard). */
+function projectionEntries(face) {
+    const value = face?.getSnapshot();
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === 'object' && item !== null
+        && typeof item.id === 'string'
+        && typeof item.seq === 'number'
+        && typeof item.turn === 'number');
+}
+function findConvRoot() {
+    return document.querySelector('[data-slot="conversation"] > div[data-phase]');
+}
+/** Structural equality of two dot lists (member keys fully capture a dot's
+ *  folded questions, so identical key sequences mean identical content).
+ *  Lets the strip skip a re-render when a refresh produced no change. */
+function sameDots(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        const da = a[i];
+        const db = b[i];
+        if (da.key !== db.key || da.memberKeys.length !== db.memberKeys.length)
+            return false;
+        for (let j = 0; j < da.memberKeys.length; j++) {
+            if (da.memberKeys[j] !== db.memberKeys[j])
+                return false;
+        }
+    }
+    return true;
+}
+export function QuestionNavStrip(props) {
+    const current = props.useSessions?.((s) => s.current);
+    const summary = props.useSessions?.((s) => (current === undefined ? undefined : s.byId?.[String(current)]));
+    const visible = current !== undefined && summary !== undefined && summary.blank !== true;
+    const [dots, setDots] = useState([]);
+    const [jumpingKey, setJumpingKey] = useState(null);
+    const [hint, setHint] = useState(null);
+    const [focus, setFocus] = useState(null);
+    // Scroll-spy: the dot marking the reader's current turn (null outside chat).
+    const [currentKey, setCurrentKey] = useState(null);
+    const [align, setAlign] = useState(() => props.align());
+    // Dots revealed per ▲/▼ click (settings scope; drives pageBy's step).
+    const [pageSize, setPageSize] = useState(() => props.pageSize());
+    const panelRef = useRef(null);
+    const listRef = useRef(null);
+    const hintTimerRef = useRef(null);
+    // Pending focus-clear timer: lets the mouse move from the rail onto a
+    // cascade card without dropping the cascade mid-flight.
+    const clearFocusTimerRef = useRef(null);
+    // Last rendered dot list, for the change-detection bail-out below.
+    const lastDotsRef = useRef([]);
+    // Whether the dot band overflows its 60% clamp (drives the ▲/▼ paging
+    // buttons).
+    const [scrollable, setScrollable] = useState(false);
+    // Scroll offset of the band + its max offset: drives the ▲/▼ visibility
+    // (each direction hides once there is nothing more to reveal).
+    const [scrollPos, setScrollPos] = useState({ top: 0, max: 0 });
+    // Dots revealed by the latest ▲/▼ click: key → stagger order + travel
+    // direction. Drives a short staggered pop-in animation so the click has a
+    // visible effect; cleared by a timer once the animation has played out.
+    const [revealed, setRevealed] = useState(null);
+    const revealTimerRef = useRef(null);
+    const syncScroll = () => {
+        const list = listRef.current;
+        if (list === null)
+            return;
+        const max = Math.max(0, list.scrollHeight - list.clientHeight);
+        setScrollPos({ top: list.scrollTop, max });
+    };
+    // Page the band by one DOT_PAGE_ROWS click in the given direction, then mark
+    // the dots the page just brought into view so they play a staggered pop-in
+    // animation in the direction of travel (▼ → rise from below, ▲ → drop from
+    // above) — the visual confirmation that the click revealed new dots.
+    const pageBy = (dir) => {
+        const list = listRef.current;
+        if (list === null)
+            return;
+        const max = Math.max(0, list.scrollHeight - list.clientHeight);
+        const target = clampScrollTop(list.scrollTop + dir * pageStep(DOT_SIZE, DOT_GAP, pageSize), max);
+        if (target === list.scrollTop)
+            return;
+        // Snapshot which dots are geometrically inside the band before the jump
+        // (the container rect does not move when its content scrolls).
+        const band = list.getBoundingClientRect();
+        const els = Array.from(list.querySelectorAll('[data-mega-chat-nav-key]'));
+        const wasVisible = els.map((el) => {
+            const r = el.getBoundingClientRect();
+            return r.bottom > band.top && r.top < band.bottom;
+        });
+        list.scrollTop = target;
+        syncScroll();
+        const next = new Map();
+        const fresh = [];
+        els.forEach((el, i) => {
+            if (wasVisible[i])
+                return;
+            const r = el.getBoundingClientRect();
+            const key = el.dataset.questionNavKey;
+            if (key !== undefined && r.bottom > band.top && r.top < band.bottom) {
+                fresh.push(key);
+            }
+        });
+        // Stagger radiates from the clicked triangle: paging down (▼) starts at
+        // the bottom of the fresh batch, paging up (▲) at the top.
+        if (dir === 1)
+            fresh.reverse();
+        fresh.forEach((key, order) => next.set(key, { dir, order }));
+        if (next.size === 0)
+            return;
+        setRevealed(next);
+        if (revealTimerRef.current !== null)
+            window.clearTimeout(revealTimerRef.current);
+        // Animation (320ms) + per-dot stagger (35ms each) + slack.
+        revealTimerRef.current = window.setTimeout(() => setRevealed(null), 320 + next.size * 35 + 120);
+    };
+    const canPageUp = scrollable && scrollPos.top > 0;
+    const canPageDown = scrollable && scrollPos.top < scrollPos.max;
+    // Focus persists briefly after leaving the rail, so the mouse can reach the
+    // clickable cascade cards; entering a card cancels the clear, leaving
+    // everything re-arms it.
+    const cancelClearFocus = () => {
+        if (clearFocusTimerRef.current !== null) {
+            window.clearTimeout(clearFocusTimerRef.current);
+            clearFocusTimerRef.current = null;
+        }
+    };
+    const scheduleClearFocus = () => {
+        cancelClearFocus();
+        clearFocusTimerRef.current = window.setTimeout(() => setFocus(null), 240);
+    };
+    // Follow the plugin settings from the settings scope (an align change
+    // re-anchors the rail through the layout effect below; a page-size change
+    // steps the ▲/▼ paging).
+    useEffect(() => props.subscribeSettings(() => {
+        setAlign(props.align());
+        setPageSize(props.pageSize());
+    }), [props]);
+    const showHint = (message) => {
+        setHint(message);
+        if (hintTimerRef.current !== null)
+            window.clearTimeout(hintTimerRef.current);
+        hintTimerRef.current = window.setTimeout(() => setHint(null), 1800);
+    };
+    // Recompute the dot list from the projection + live window. Subscribed to
+    // the projection push frames and the session's content only — session
+    // switches are covered by `current` below (the effect re-runs on change),
+    // so the session-list feed is not subscribed: it would re-run the full
+    // recompute for unrelated list churn.
+    useEffect(() => {
+        if (!visible || current === undefined) {
+            setDots([]);
+            lastDotsRef.current = [];
+            return;
+        }
+        const sessionId = current;
+        const face = props.questionProjection(sessionId);
+        const refresh = () => {
+            const grouped = groupQuestionsByTurn(projectionEntries(face));
+            const next = mergeLiveQuestions(grouped, props.readQuestions(sessionId));
+            // Identical content (a streaming update that added no question): re-use
+            // the previous array reference so React bails out of re-rendering the
+            // strip — the common case during assistant streaming.
+            if (sameDots(next, lastDotsRef.current)) {
+                setDots(lastDotsRef.current);
+                return;
+            }
+            lastDotsRef.current = next;
+            setDots(next);
+        };
+        refresh();
+        const unsubProjection = face?.subscribe(refresh) ?? (() => { });
+        const unsubContent = props.subscribeContent(sessionId, refresh);
+        return () => {
+            unsubProjection();
+            unsubContent();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [visible, current, props]);
+    // Listen for jump-failure events and surface the hint.
+    useEffect(() => {
+        const onJumpFailed = (event) => {
+            const code = event.detail;
+            showHint(props.t(FAILURE_HINTS[code] ?? 'jump.timeout'));
+        };
+        window.addEventListener('mega-chat-nav:jump-failed', onJumpFailed);
+        return () => window.removeEventListener('mega-chat-nav:jump-failed', onJumpFailed);
+    }, [props]);
+    // Anchor the minimap to the conversation column: position it at the left
+    // edge of the conversation root and reserve a thin rail with padding-left.
+    //
+    // A layout-correction loop keeps the rail pinned to the conversation even
+    // when an outside panel (e.g. a browser-extension sidebar like Doubao) moves
+    // or resizes the frame without resizing the browser window: `window resize`
+    // never fires for in-page panels, and a ResizeObserver on the conversation
+    // root alone misses remounts and the tail of the frame's grid-column
+    // transition, which used to leave the rail drifting into the session list.
+    // The loop runs while the layout is still moving, then parks itself after a
+    // few stable frames; observers re-wake it on the next change.
+    useLayoutEffect(() => {
+        if (!visible)
+            return;
+        let raf = 0;
+        let idle = 0;
+        let stopped = false;
+        let observer = null;
+        const observed = { frame: null, convRoot: null };
+        const applyLayout = () => {
+            const panel = panelRef.current;
+            if (panel === null)
+                return false;
+            const frame = panel.closest('[data-shell-overlay]')?.parentElement ?? null;
+            const convRoot = findConvRoot();
+            // Keep looping while the anchors are not both present (conversation not
+            // mounted yet / mid-reflow), so a late mount still aligns.
+            if (frame === null || convRoot === null)
+                return true;
+            // Keep observing the live nodes: the conversation root may remount
+            // (e.g. after a panel-triggered reflow), which silently detaches an
+            // earlier ResizeObserver target.
+            if (observer !== null) {
+                if (observed.frame !== frame) {
+                    observer.observe(frame, { box: 'border-box' });
+                    observed.frame = frame;
+                }
+                if (observed.convRoot !== convRoot) {
+                    observer.observe(convRoot, { box: 'border-box' });
+                    observed.convRoot = convRoot;
+                }
+            }
+            const frameRect = frame.getBoundingClientRect();
+            const convRect = convRoot.getBoundingClientRect();
+            // Never snap onto a transient box: keep correcting until the
+            // conversation has a real footprint again.
+            if (convRect.height <= 0 || convRect.width <= 0)
+                return true;
+            const top = `${convRect.top - frameRect.top}px`;
+            const height = `${convRect.height}px`;
+            // Anchor to the configured edge: keep the other edge's inline style
+            // cleared so the CSS class (left: auto on .railRight) owns it.
+            if (align === 'right') {
+                // Give back the conversation scrollbar's layout width so the 44px
+                // rail never covers the bar: the WebKit path consumes 8px at the
+                // column's right edge, which the rail would otherwise render on top
+                // of, making the bar unclickable. ui-theme mirrors that width as
+                // --dsh-scrollbar-width (the overlay composer seat offsets `right`
+                // by the same variable); 8px fallback covers engines where the
+                // variable is absent.
+                const right = `calc(${frameRect.right - convRect.right}px + var(--dsh-scrollbar-width, 8px))`;
+                if (panel.style.top === top && panel.style.height === height
+                    && panel.style.right === right && panel.style.left === '') {
+                    return false;
+                }
+                panel.style.top = top;
+                panel.style.height = height;
+                panel.style.right = right;
+                panel.style.left = '';
+                return true;
+            }
+            const left = `${convRect.left - frameRect.left}px`;
+            if (panel.style.top === top && panel.style.height === height
+                && panel.style.left === left && panel.style.right === '') {
+                return false;
+            }
+            panel.style.top = top;
+            panel.style.height = height;
+            panel.style.left = left;
+            panel.style.right = '';
+            return true;
+        };
+        const loop = () => {
+            if (stopped)
+                return;
+            raf = 0;
+            idle = applyLayout() ? 0 : idle + 1;
+            if (idle < 3)
+                raf = requestAnimationFrame(loop);
+        };
+        const wake = () => {
+            if (stopped)
+                return;
+            idle = 0;
+            if (raf === 0)
+                raf = requestAnimationFrame(loop);
+        };
+        observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(wake);
+        if (observer !== null) {
+            const panel = panelRef.current;
+            const frame = panel?.closest('[data-shell-overlay]')?.parentElement ?? null;
+            const convRoot = findConvRoot();
+            if (frame !== null) {
+                observer.observe(frame, { box: 'border-box' });
+                observed.frame = frame;
+            }
+            if (convRoot !== null) {
+                observer.observe(convRoot, { box: 'border-box' });
+                observed.convRoot = convRoot;
+            }
+        }
+        // Initial alignment; the loop keeps correcting through layout transitions.
+        wake();
+        window.addEventListener('resize', wake);
+        return () => {
+            stopped = true;
+            if (raf !== 0)
+                cancelAnimationFrame(raf);
+            observer?.disconnect();
+            window.removeEventListener('resize', wake);
+        };
+    }, [visible, align]);
+    // Detect band overflow: drives the ▲/▼ paging buttons. Re-checked when the
+    // dots change and whenever the band itself resizes (the layout loop above
+    // clamps it to the conversation height).
+    useLayoutEffect(() => {
+        const list = listRef.current;
+        if (list === null)
+            return;
+        const check = () => {
+            setScrollable(list.scrollHeight > list.clientHeight + 1);
+            syncScroll();
+        };
+        check();
+        if (typeof ResizeObserver === 'undefined')
+            return;
+        const observer = new ResizeObserver(check);
+        observer.observe(list);
+        return () => observer.disconnect();
+    }, [dots, align]);
+    // Scroll-spy: mark the dot whose turn sits at the reader's position and
+    // follow the conversation as it scrolls. The reading line is 35% down the
+    // scrollport (see core/active-dot.ts), so the marker reads as "the question
+    // I am looking at". Only rendered rows participate: a paged-out window
+    // unmounts older questions, and the marker tracks what is on screen.
+    useEffect(() => {
+        if (!visible || dots.length === 0) {
+            setCurrentKey(null);
+            return;
+        }
+        let raf = 0;
+        let disposed = false;
+        let observedFlow = null;
+        const compute = () => {
+            raf = 0;
+            const scrollport = document.querySelector('[data-conversation-scroll]');
+            const flow = document.querySelector('[data-chat-flow]');
+            // Trajectory view / chat not mounted: no marker.
+            if (scrollport === null || flow === null) {
+                setCurrentKey(null);
+                return;
+            }
+            // Content growth (streaming, paging) shifts row tops without a scroll
+            // event; re-observe the flow element across remounts.
+            if (observer !== null && observedFlow !== flow) {
+                observer.disconnect();
+                observer.observe(flow);
+                observedFlow = flow;
+            }
+            const portRect = scrollport.getBoundingClientRect();
+            if (portRect.height <= 0)
+                return;
+            // Key lookup without interpolating a selector (chat keys contain ':').
+            const rendered = new Map();
+            for (const row of flow.querySelectorAll('[data-chat-anchor-key]')) {
+                const key = row.dataset.chatAnchorKey;
+                if (key !== undefined && !rendered.has(key))
+                    rendered.set(key, row);
+            }
+            const rows = [];
+            for (const dot of dots) {
+                // The turn's first rendered question row anchors the dot (memberKeys
+                // are in seq order, so the first hit is the turn's topmost row).
+                for (const memberKey of dot.memberKeys) {
+                    const row = rendered.get(memberKey);
+                    if (row !== undefined) {
+                        rows.push({ key: dot.key, top: row.getBoundingClientRect().top - portRect.top });
+                        break;
+                    }
+                }
+            }
+            const next = pickActiveDot(rows, readingLineOffset(portRect.height));
+            setCurrentKey((prev) => (prev === next ? prev : next));
+        };
+        const schedule = () => {
+            if (!disposed && raf === 0)
+                raf = requestAnimationFrame(compute);
+        };
+        const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(schedule);
+        compute();
+        // Scroll events do not bubble; capturing at the document reaches the
+        // conversation scrollport today and after any remount without tracking
+        // the node. rAF-throttled, so hot scroll streams coalesce into one
+        // measurement per frame.
+        document.addEventListener('scroll', schedule, true);
+        window.addEventListener('resize', schedule);
+        return () => {
+            disposed = true;
+            if (raf !== 0)
+                cancelAnimationFrame(raf);
+            observer?.disconnect();
+            document.removeEventListener('scroll', schedule, true);
+            window.removeEventListener('resize', schedule);
+        };
+    }, [visible, dots]);
+    // Clear any pending timers on unmount.
+    useEffect(() => () => {
+        if (hintTimerRef.current !== null)
+            window.clearTimeout(hintTimerRef.current);
+        if (clearFocusTimerRef.current !== null)
+            window.clearTimeout(clearFocusTimerRef.current);
+        if (revealTimerRef.current !== null)
+            window.clearTimeout(revealTimerRef.current);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    if (!visible)
+        return null;
+    const onJump = (dot) => {
+        if (current === undefined)
+            return;
+        setJumpingKey(dot.key);
+        props.jump(current, dot.key);
+        window.setTimeout(() => setJumpingKey((k) => (k === dot.key ? null : k)), 600);
+    };
+    const openFocus = (dot, target) => {
+        const index = dots.findIndex((d) => d.key === dot.key);
+        if (index < 0)
+            return;
+        cancelClearFocus();
+        const r = target.getBoundingClientRect();
+        // The cascade opens away from the rail: to the right of the dots on a
+        // left-anchored rail, to the left on a right-anchored one. The column is
+        // vertically centered on the selected dot (top: centerY + translateY(-50%)).
+        const horizontal = align === 'right'
+            ? { right: window.innerWidth - r.left + 10 }
+            : { left: r.right + 10 };
+        const lo = Math.max(0, index - FOCUS_RADIUS);
+        const hi = Math.min(dots.length - 1, index + FOCUS_RADIUS);
+        const items = [];
+        for (let i = lo; i <= hi; i++) {
+            items.push({ dot: dots[i], distance: Math.abs(i - index) });
+        }
+        setFocus({ key: dot.key, items, centerY: r.top + r.height / 2, ...horizontal });
+    };
+    const t = props.t;
+    const selectedIndex = focus === null ? -1 : dots.findIndex((d) => d.key === focus.key);
+    return (_jsxs("div", { ref: panelRef, className: align === 'right' ? `${'mgs-rail'} ${'mgs-railRight'}` : 'mgs-rail', "data-mega-chat-nav": "rail", children: [_jsx("div", { className: 'mgs-queue', children: dots.length === 0 ? (_jsx("div", { className: 'mgs-empty', children: t('strip.empty') })) : (_jsxs(_Fragment, { children: [_jsx("span", { className: 'mgs-count', children: dots.length }), scrollable ? (_jsx("button", { type: "button", className: `${'mgs-navBtn'} ${'mgs-navUp'}`, "aria-label": t('strip.up'), style: { visibility: canPageUp ? 'visible' : 'hidden' }, onMouseEnter: cancelClearFocus, onMouseLeave: scheduleClearFocus, onClick: () => pageBy(-1) })) : null, _jsx("div", { ref: listRef, className: 'mgs-list', onScroll: syncScroll, onMouseLeave: scheduleClearFocus, children: _jsx("div", { className: 'mgs-dots', children: dots.map((dot, index) => {
+                                    const isFocused = focus !== null && focus.key === dot.key;
+                                    // Progressive magnification: selected largest, ±1 smaller, ±2
+                                    // smaller still, the rest base scale.
+                                    const tier = selectedIndex < 0 ? null : focusTier(index - selectedIndex);
+                                    const scale = jumpingKey === dot.key ? 1.6 : tier !== null ? focusScale(tier) : 1;
+                                    // Click-paging feedback: dots just paged into view play a
+                                    // staggered pop-in, traveling in the paging direction.
+                                    const reveal = revealed?.get(dot.key);
+                                    const cls = ['mgs-dot'];
+                                    if (isFocused)
+                                        cls.push('mgs-focused');
+                                    if (jumpingKey === dot.key)
+                                        cls.push('mgs-active');
+                                    if (currentKey === dot.key)
+                                        cls.push('mgs-current');
+                                    if (reveal !== undefined) {
+                                        cls.push(reveal.dir === 1 ? 'mgs-dotEnterFromBottom' : 'mgs-dotEnterFromTop');
+                                    }
+                                    return (_jsx("button", { className: cls.join(' '), style: {
+                                            transform: `scale(${scale})`,
+                                            ...(reveal !== undefined ? { animationDelay: `${reveal.order * 35}ms` } : {}),
+                                        }, "data-mega-chat-nav-focused": isFocused ? 'true' : undefined, "data-mega-chat-nav-index": index, "data-mega-chat-nav-key": dot.key, "aria-label": dot.texts[0] ?? '', onMouseEnter: (e) => openFocus(dot, e.currentTarget), onClick: () => onJump(dot) }, dot.key));
+                                }) }) }), scrollable ? (_jsx("button", { type: "button", className: `${'mgs-navBtn'} ${'mgs-navDown'}`, "aria-label": t('strip.down'), style: { visibility: canPageDown ? 'visible' : 'hidden' }, onMouseEnter: cancelClearFocus, onMouseLeave: scheduleClearFocus, onClick: () => pageBy(1) })) : null] })) }), hint !== null
+                ? createPortal(_jsx("div", { className: 'mgs-hint', style: align === 'right' ? { right: 60, top: 20 } : { left: 60, top: 20 }, children: hint }), document.body)
+                : null, focus !== null
+                ? createPortal(
+                /* The vertical cascade: one crisp card per window dot, stacked
+                   non-overlapping, vertically centered on the selected dot.
+                   Hovering the cascade keeps it alive (the rail only re-arms its
+                   clear once the mouse leaves both). */
+                _jsx("div", { className: align === 'right' ? `${'mgs-cascade'} ${'mgs-cascadeRight'}` : 'mgs-cascade', style: {
+                        ...(focus.left !== undefined ? { left: focus.left } : {}),
+                        ...(focus.right !== undefined ? { right: focus.right } : {}),
+                        top: focus.centerY,
+                        transform: 'translateY(-50%)',
+                    }, onMouseEnter: cancelClearFocus, onMouseLeave: scheduleClearFocus, children: focus.items.map((item) => {
+                        const metrics = focusCardMetrics(item.distance);
+                        if (metrics === null)
+                            return null;
+                        const isSelected = item.distance === 0;
+                        // Cascade cards join their dot's texts into one clamped line;
+                        // the selected card keeps every line. Every card shows the
+                        // question's sent time, and clicking any card jumps to its
+                        // question exactly like clicking the dot.
+                        const text = item.dot.texts.join(' · ');
+                        const cls = isSelected
+                            ? `${'mgs-card'} ${'mgs-cardSelected'}${align === 'right' ? ` ${'mgs-cardSelectedRight'}` : ''}`
+                            : 'mgs-card';
+                        return (_jsxs("div", { className: cls, role: "button", tabIndex: -1, style: { width: metrics.widthPx }, onClick: () => onJump(item.dot), children: [isSelected && item.dot.turn !== null ? (_jsxs("div", { className: 'mgs-cardTitle', children: ["Turn ", item.dot.turn] })) : null, _jsx("div", { className: isSelected ? 'mgs-cardBody' : 'mgs-cardClamp', style: isSelected
+                                        ? undefined
+                                        : { WebkitLineClamp: metrics.maxLines, fontSize: metrics.fontSize }, children: isSelected
+                                        ? item.dot.texts.map((line, lineIndex) => (_jsx("div", { className: 'mgs-cardLine', children: line }, lineIndex)))
+                                        : text }), _jsx("div", { className: 'mgs-cardTime', children: formatQuestionTime(item.dot.time, Date.now()) })] }, item.dot.key));
+                    }) }), document.body)
+                : null] }));
+}

package/lib/client/components/ConfigPanel.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { readConfig, setGeneral } from "../config.js";
+const STYLES = ['minimal', 'deepseek', 'codex'];
+export function ConfigPanel(props) {
+    const cfg = readConfig(props.scope);
+    if (!cfg || !props.scope)
+        return null;
+    const g = cfg.general;
+    const set = (patch) => void setGeneral(props.scope, patch);
+    return (_jsxs("div", { className: "mgs-panel mgs-config", role: "dialog", "aria-label": props.t('settings.entry'), children: [_jsxs("div", { className: "mgs-panel__head", children: [_jsx("span", { className: "mgs-panel__title", children: props.t('settings.entry') }), _jsx("button", { type: "button", className: "mgs-rail__toggle", onClick: props.onClose, "aria-label": "close", children: "\u2715" })] }), _jsxs("div", { className: "mgs-row", children: [_jsx("span", { className: "mgs-row__label", children: props.t('config.style') }), _jsx("div", { className: "mgs-seg", children: STYLES.map((s) => (_jsx("button", { type: "button", className: 'mgs-seg__item' + (g.style === s ? ' mgs-seg__item--active' : ''), onClick: () => set({ style: s }), children: props.t('config.style.' + s) }, s))) })] }), _jsxs("div", { className: "mgs-row", children: [_jsx("span", { className: "mgs-row__label", children: props.t('config.align') }), _jsx("div", { className: "mgs-seg", children: ['left', 'right'].map((a) => (_jsx("button", { type: "button", className: 'mgs-seg__item' + (g.align === a ? ' mgs-seg__item--active' : ''), onClick: () => set({ align: a }), children: props.t('config.align.' + a) }, a))) })] }), _jsxs("div", { className: "mgs-row", children: [_jsx("span", { className: "mgs-row__label", children: props.t('config.panelWidth') }), _jsx("input", { className: "mgs-input mgs-input--num", type: "number", min: 200, max: 400, value: g.panelWidth, onChange: (e) => set({ panelWidth: Math.min(400, Math.max(200, Number(e.target.value) || 280)) }) })] }), _jsxs("div", { className: "mgs-row", children: [_jsx("span", { className: "mgs-row__label", children: props.t('config.collapsed') }), _jsx(Switch, { checked: g.collapsed, onChange: (v) => set({ collapsed: v }) })] }), _jsxs("div", { className: "mgs-row", children: [_jsx("span", { className: "mgs-row__label", children: props.t('config.showSearch') }), _jsx(Switch, { checked: g.showSearch, onChange: (v) => set({ showSearch: v }) })] }), _jsxs("div", { className: "mgs-row", children: [_jsx("span", { className: "mgs-row__label", children: props.t('config.themeMode') }), _jsx("div", { className: "mgs-seg", children: ['follow', 'custom'].map((m) => (_jsx("button", { type: "button", className: 'mgs-seg__item' + (g.themeMode === m ? ' mgs-seg__item--active' : ''), onClick: () => set({ themeMode: m }), children: props.t('config.themeMode.' + m) }, m))) })] })] }));
+}
+export function Switch({ checked, onChange }) {
+    return (_jsxs("label", { className: "mgs-switch", children: [_jsx("input", { type: "checkbox", checked: checked, onChange: (e) => onChange(e.target.checked) }), _jsx("span", { className: "mgs-switch__track", children: _jsx("span", { className: "mgs-switch__thumb" }) })] }));
+}

package/lib/client/components/DotRail.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// 圆点轨（纯渲染）：question-nav 形态 —— 8px 圆点 / 波纹放大 / 悬停预览卡
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { VirtualList } from "../virtual/VirtualList.js";
+import { formatTime, truncate } from "../pure.js";
+const DOT_STEP = 14;
+const RIPPLE = [2.0, 1.55, 1.25];
+function rippleScale(dist) {
+    if (dist < RIPPLE.length)
+        return RIPPLE[dist];
+    return 1;
+}
+function userItems(items) {
+    return items.filter((it) => it.role === 'user' || it.role === 'steering');
+}
+export function DotRail(props) {
+    const { items, align, cfg, t, activeKey, failed, onJump, pos } = props;
+    const entries = useMemo(() => userItems(items), [items]);
+    const [scrollTop, setScrollTop] = useState(0);
+    const [viewportH, setViewportH] = useState(360);
+    const [hoverKey, setHoverKey] = useState(null);
+    const [hoverIdx, setHoverIdx] = useState(-1);
+    const trackRef = useRef(null);
+    const keys = entries.map((it) => it.key);
+    const hovered = hoverIdx >= 0 ? entries[hoverIdx] : undefined;
+    const pinned = useMemo(() => {
+        const s = new Set();
+        if (activeKey)
+            s.add(activeKey);
+        if (hoverKey)
+            s.add(hoverKey);
+        return s.size > 0 ? s : undefined;
+    }, [activeKey, hoverKey]);
+    // 视口高度跟随轨道容器
+    useEffect(() => {
+        const el = trackRef.current;
+        if (!el)
+            return;
+        const ro = new ResizeObserver(() => {
+            const h = el.clientHeight;
+            setViewportH((prev) => (Math.abs(prev - h) > 1 ? h : prev));
+        });
+        ro.observe(el);
+        setViewportH(el.clientHeight || 360);
+        return () => ro.disconnect();
+    }, []);
+    const style = {
+        position: 'fixed',
+        top: pos?.top ?? '50%',
+        height: pos?.height ?? undefined,
+        left: pos?.left,
+        right: pos?.right,
+    };
+    if (!pos)
+        style.transform = 'translateY(-50%)';
+    return (_jsxs("div", { className: 'mgs-dots mgs-dots--' + align, style: style, role: "navigation", "aria-label": t('a11y.list'), children: [_jsx("div", { className: "mgs-dots__track", ref: trackRef, children: entries.length === 0 ? (_jsx("div", { className: "mgs-dots__empty", children: t('empty') })) : (_jsx(VirtualList, { items: entries, itemHeight: DOT_STEP, viewportHeight: viewportH, scrollTop: scrollTop, onScrollTopChange: setScrollTop, keyOf: (it) => it.key, pinned: pinned, renderItem: (it, i) => {
+                        const dist = hoverIdx >= 0 ? Math.abs(i - hoverIdx) : 99;
+                        return (_jsx("button", { type: "button", className: 'mgs-dot' +
+                                (it.key === activeKey ? ' mgs-dot--active' : '') +
+                                (it.key === hoverKey ? ' mgs-dot--hover' : ''), style: { transform: 'scale(' + rippleScale(dist) + ')' }, "aria-label": truncate(it.text, 40), "aria-current": it.key === activeKey ? 'step' : undefined, onClick: () => onJump(it.key), onMouseEnter: () => { setHoverKey(it.key); setHoverIdx(i); }, onMouseLeave: () => { setHoverKey((k) => (k === it.key ? null : k)); setHoverIdx(-1); } }));
+                    } })) }), hovered && (_jsxs("div", { className: 'mgs-dots__tip mgs-dots__tip--' + align, children: [_jsx("div", { className: "mgs-dots__tip-text", children: truncate(hovered.text, 80) || t('empty') }), _jsx("div", { className: "mgs-dots__tip-time", children: formatTime(hovered.time) })] })), failed && _jsx("div", { className: "mgs-dots__hint", children: t('jump.failed') })] }));
+}