dsh-mega-chat-nav 0.1.1

package/lib/client/components/minimal/useRail.js

@@ -0,0 +1,716 @@
+// 简约风格：轨道逻辑层（数据装配 / 布局钉位 / 阅读间谍 / 条带翻页 / 卡片预览 / 失败提示）
+// 全部为本风格自研实现：数据形态（RailMarker）、几何常量与算法均为插件自身设计
+import { useEffect, useRef, useState } from 'react';
+import { DEFAULT_ALIGN, DEFAULT_BAND, DEFAULT_CARD_COUNT, DEFAULT_CARD_ITEMS, DEFAULT_SCROLL, DEFAULT_SEARCH_SCOPES, DEFAULT_SHOW, DEFAULT_STYLE } from "../../settings.js";
+/* ================= 数据装配 ================= */
+/** 锚点 key：镜像聊天行锚点公式 '<kind长度>:<kind><id>'，kind 段固定 'input-message'（DOM 契约） */
+function anchorKey(id) {
+    return '13:input-message' + String(id);
+}
+/** 投影值 → 条目（结构守卫：缺 id/seq/turn 的脏数据丢弃） */
+function projectedEntries(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');
+}
+/** 结构相等：members 全等即内容一致（React bail out 用） */
+function sameMarkers(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i].key !== b[i].key || a[i].members.length !== b[i].members.length)
+            return false;
+        for (let j = 0; j < a[i].members.length; j++) {
+            if (a[i].members[j] !== b[i].members[j])
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * 回合标记装配：投影条目（全量）+ 活窗口行（投影未收录才补）统一排序后按回合分组。
+ * 同回合连续条目合并为同一标记（锚点取首问）。
+ */
+function buildMarkers(projected, live) {
+    const seen = new Set();
+    const merged = [];
+    for (const p of projected) {
+        const key = anchorKey(p.id);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        merged.push({ turn: p.turn, seq: p.seq, key, time: p.time, text: p.text, metrics: p.metrics });
+    }
+    for (const l of live) {
+        if (seen.has(l.key))
+            continue;
+        seen.add(l.key);
+        merged.push({ turn: null, seq: l.anchorSeq, key: l.key, time: l.time, text: l.text });
+    }
+    merged.sort((a, b) => a.seq - b.seq);
+    const markers = [];
+    for (const m of merged) {
+        const tail = markers[markers.length - 1];
+        if (tail !== undefined && tail.turn !== null && tail.turn === m.turn) {
+            markers[markers.length - 1] = { ...tail, texts: [...tail.texts, m.text], members: [...tail.members, m.key] };
+        }
+        else {
+            markers.push({ turn: m.turn, key: m.key, seq: m.seq, time: m.time, texts: [m.text], members: [m.key], metrics: m.metrics });
+        }
+    }
+    return markers;
+}
+/** 圆点数据：会话可见性 + 标记装配（订阅集中管理，共用一条刷新管线） */
+export function useMarkerData(injected, useSessions) {
+    const current = useSessions?.((s) => s.current);
+    const summary = useSessions?.((s) => (current === undefined ? undefined : s.byId?.[String(current)]));
+    // 仅对话视图显示（[data-chat-flow] 只在对话消息流渲染；Trajectory 视图与会话未加载时不存在）
+    const [viewOk, setViewOk] = useState(() => document.querySelector('[data-chat-flow]') !== null);
+    useEffect(() => {
+        const check = () => setViewOk(document.querySelector('[data-chat-flow]') !== null);
+        check();
+        const observer = typeof MutationObserver === 'undefined' ? null : new MutationObserver(check);
+        observer?.observe(document.body, { childList: true, subtree: true });
+        return () => { observer?.disconnect(); };
+    }, []);
+    const visible = current !== undefined && summary !== undefined && summary.blank !== true && viewOk;
+    const [markers, setMarkers] = useState([]);
+    const cacheRef = useRef([]);
+    useEffect(() => {
+        if (!visible || current === undefined || injected === undefined) {
+            cacheRef.current = [];
+            setMarkers([]);
+            return;
+        }
+        const face = injected.questionProjection(current);
+        const refresh = () => {
+            const next = buildMarkers(projectedEntries(face), injected.readQuestions(current));
+            if (sameMarkers(next, cacheRef.current)) {
+                setMarkers(cacheRef.current);
+                return;
+            }
+            cacheRef.current = next;
+            setMarkers(next);
+        };
+        refresh();
+        const offProjection = face?.subscribe(refresh) ?? (() => { });
+        const offContent = injected.subscribeContent(current, refresh);
+        return () => {
+            offProjection();
+            offContent();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [injected, current, visible]);
+    return { sessionId: current, visible, markers };
+}
+/* ================= 布局钉位 ================= */
+/** 对话列根元素（桌面 rail 钉位基准——保持历史稳定实现） */
+function conversationRoot() {
+    return document.querySelector('[data-slot="conversation"] > div[data-phase]');
+}
+/** 手机搜索按钮宿主：对话滚动容器 [data-conversation-scroll]（sticky 粘附基准） */
+function mobileSearchHost() {
+    return document.querySelector('[data-conversation-scroll]');
+}
+/** 期望几何：rail 钉到对话列（对齐侧决定 edge 归属）；offset 为 rail 与对话列边缘的距离 */
+function desiredGeometry(panel, align, offset) {
+    const frame = panel.closest('[data-shell-overlay]')?.parentElement ?? null;
+    const root = conversationRoot();
+    if (frame === null || root === null)
+        return null;
+    const fr = frame.getBoundingClientRect();
+    const rr = root.getBoundingClientRect();
+    if (rr.height <= 0 || rr.width <= 0)
+        return null;
+    // 取整到整数像素：getBoundingClientRect 的浮点噪声（如 3.05e-05px）
+    // 会让字符串比较永远 dirty，布局循环停不下来
+    const top = Math.round(rr.top - fr.top);
+    const height = Math.round(rr.height);
+    return align === 'right'
+        ? { top: top + 'px', height: height + 'px', edge: Math.round(fr.right - rr.right + offset) + 'px', side: 'right' }
+        : { top: top + 'px', height: height + 'px', edge: Math.round(rr.left - fr.left + offset) + 'px', side: 'left' };
+}
+/** 布局钉位：期望几何 → 比对 → 写入（rAF 循环，连续 3 帧稳定停车；resize/尺寸变化唤醒） */
+export function usePinning(panelRef, visible, align, offset = 0, sessionId) {
+    useEffect(() => {
+        if (!visible)
+            return;
+        let raf = 0;
+        let idle = 0;
+        let alive = true;
+        let observer = null;
+        let domObserver = null;
+        // 三态：missing=目标（对话区）尚未出现（会话/工作区切换重建中——不停车，持续等）；
+        // changed=刚写入（重置稳定计数）；stable=目标在且无变化（计入稳定帧）
+        const paint = () => {
+            const panel = panelRef.current;
+            if (panel === null)
+                return 'missing';
+            const want = desiredGeometry(panel, align, offset);
+            if (want === null)
+                return 'missing';
+            const other = want.side === 'right' ? 'left' : 'right';
+            const dirty = panel.style.top !== want.top
+                || panel.style.height !== want.height
+                || panel.style[want.side] !== want.edge
+                || panel.style[other] !== '';
+            if (!dirty)
+                return 'stable';
+            panel.style.top = want.top;
+            panel.style.height = want.height;
+            panel.style[want.side] = want.edge;
+            panel.style[other] = '';
+            return 'changed';
+        };
+        const loop = () => {
+            if (!alive)
+                return;
+            raf = 0;
+            const result = paint();
+            if (result === 'changed')
+                idle = 0;
+            else if (result === 'stable')
+                idle += 1;
+            else
+                idle = 0; // missing：对话区重建中，持续校准不停车
+            if (idle < 3)
+                raf = requestAnimationFrame(loop);
+        };
+        const nudge = () => {
+            if (!alive)
+                return;
+            idle = 0;
+            if (raf === 0)
+                raf = requestAnimationFrame(loop);
+        };
+        observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(nudge);
+        if (observer !== null) {
+            const panel = panelRef.current;
+            const frame = panel?.closest('[data-shell-overlay]')?.parentElement ?? null;
+            const root = conversationRoot();
+            if (frame !== null)
+                observer.observe(frame, { box: 'border-box' });
+            if (root !== null)
+                observer.observe(root, { box: 'border-box' });
+        }
+        // 对话区 DOM 重建（会话/工作区切换）会替换观察目标——ResizeObserver 感知不到，
+        // 用 MutationObserver 监听 body 子树变化唤醒校准（nudge 有 rAF 合并，开销可控）
+        if (typeof MutationObserver !== 'undefined') {
+            domObserver = new MutationObserver(nudge);
+            domObserver.observe(document.body, { childList: true, subtree: true });
+        }
+        nudge();
+        window.addEventListener('resize', nudge);
+        return () => {
+            alive = false;
+            if (raf !== 0)
+                cancelAnimationFrame(raf);
+            observer?.disconnect();
+            domObserver?.disconnect();
+            window.removeEventListener('resize', nudge);
+        };
+    }, [panelRef, visible, align, offset, sessionId]);
+}
+/** 采样已渲染行：为每个标记取组内首个已渲染成员 */
+function probeRows(flow, portTop, markers) {
+    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 probes = [];
+    for (const marker of markers) {
+        for (const member of marker.members) {
+            const row = rendered.get(member);
+            if (row !== undefined) {
+                probes.push({ key: marker.key, top: row.getBoundingClientRect().top - portTop });
+                break;
+            }
+        }
+    }
+    return probes;
+}
+/**
+ * 阅读位置判定：视口内（top >= 阅读线）的**第一条**标记 = 正在阅读的标记。
+ * 判据贴近「视口顶部正在看哪一条」——点击跳转后目标行贴顶（top≈0）即选中，
+ * 避免旧判据（线上方最后一行）因 scrollIntoView 的像素偏移误选中上一行。
+ * 全部行已滚过视口时取最后一行（最靠近视口底）。
+ */
+function readingTurnAt(rows, line) {
+    if (rows.length === 0)
+        return null;
+    for (const row of rows) {
+        if (row.top >= line)
+            return row.key;
+    }
+    return rows[rows.length - 1].key;
+}
+/** 阅读间谍：滚动/尺寸变化按 rAF 采样行位置，标记当前所在回合。
+ *  返回 [currentKey, forceKey]——forceKey 用于点击跳转瞬间强制激活目标，
+ *  滚动稳定后由采样判据接管。 */
+export function useReadingSpy(visible, markers) {
+    const [currentKey, setCurrentKey] = useState(null);
+    const forceKey = (key) => setCurrentKey(key);
+    useEffect(() => {
+        if (!visible || markers.length === 0) {
+            setCurrentKey(null);
+            return;
+        }
+        let raf = 0;
+        let disposed = false;
+        let observer = null;
+        let trackedFlow = null;
+        const sample = () => {
+            raf = 0;
+            const scrollport = document.querySelector('[data-conversation-scroll]');
+            const flow = document.querySelector('[data-chat-flow]');
+            if (scrollport === null || flow === null) {
+                setCurrentKey(null);
+                return;
+            }
+            if (observer !== null && trackedFlow !== flow) {
+                observer.disconnect();
+                observer.observe(flow);
+                trackedFlow = flow;
+            }
+            const portRect = scrollport.getBoundingClientRect();
+            if (portRect.height <= 0)
+                return;
+            const next = readingTurnAt(probeRows(flow, portRect.top, markers), 0);
+            setCurrentKey((prev) => (prev === next ? prev : next));
+        };
+        const schedule = () => {
+            if (!disposed && raf === 0)
+                raf = requestAnimationFrame(sample);
+        };
+        observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(schedule);
+        sample();
+        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, markers]);
+    return [currentKey, forceKey];
+}
+/* ================= 条带翻页 ================= */
+/** 圆点几何（与样式一致） */
+const DOT_DIAMETER = 8;
+const DOT_SPACING = 6;
+const ROWS_PER_PAGE = 5;
+/** 一次翻页的滚动距离 */
+function pageDistance() {
+    return ROWS_PER_PAGE * (DOT_DIAMETER + DOT_SPACING);
+}
+/** 滚动位置钳制到 [0, max] */
+function clampScroll(pos, max) {
+    const ceiling = Math.max(0, max);
+    if (pos < 0)
+        return 0;
+    if (pos > ceiling)
+        return ceiling;
+    return pos;
+}
+/** 可见性快照：元素是否与条带相交 */
+function bandVisibility(list, els) {
+    const band = list.getBoundingClientRect();
+    return els.map((el) => {
+        const r = el.getBoundingClientRect();
+        return r.bottom > band.top && r.top < band.bottom;
+    });
+}
+/** 入场批次：滚动后新进入条带的元素 key（dir=向下时逆序排列，配合错峰动画） */
+function enteringBatch(list, els, before, dir) {
+    const band = list.getBoundingClientRect();
+    const fresh = [];
+    els.forEach((el, i) => {
+        if (before[i])
+            return;
+        const r = el.getBoundingClientRect();
+        const key = el.dataset.megaChatNavKey;
+        if (key !== undefined && r.bottom > band.top && r.top < band.bottom)
+            fresh.push(key);
+    });
+    if (dir === 1)
+        fresh.reverse();
+    const batch = new Map();
+    fresh.forEach((key, order) => batch.set(key, { dir, order }));
+    return batch;
+}
+/** 条带翻页：▲/▼ 步进（固定 5 行/页）+ 溢出检测 + 入场错峰动画 */
+export function useBandPaging(listRef, markers) {
+    const [scrollable, setScrollable] = useState(false);
+    const [, bumpScroll] = useState(0); // 滚动位置变化仅作重渲染触发
+    const [revealed, setRevealed] = useState(null);
+    const revealTimer = useRef(null);
+    const readBand = () => {
+        const list = listRef.current;
+        if (list === null)
+            return { top: 0, max: 0 };
+        return { top: list.scrollTop, max: Math.max(0, list.scrollHeight - list.clientHeight) };
+    };
+    const syncScroll = () => {
+        bumpScroll((n) => n + 1);
+    };
+    const pageBy = (dir) => {
+        const list = listRef.current;
+        if (list === null)
+            return;
+        const { max } = readBand();
+        const target = clampScroll(list.scrollTop + dir * pageDistance(), max);
+        if (target === list.scrollTop)
+            return;
+        const els = Array.from(list.querySelectorAll('[data-mega-chat-nav-key]'));
+        const before = bandVisibility(list, els);
+        list.scrollTop = target;
+        syncScroll();
+        const batch = enteringBatch(list, els, before, dir);
+        if (batch.size === 0)
+            return;
+        setRevealed(batch);
+        if (revealTimer.current !== null)
+            window.clearTimeout(revealTimer.current);
+        revealTimer.current = window.setTimeout(() => setRevealed(null), 320 + batch.size * 35 + 120);
+    };
+    // 溢出检测：标记或布局变化时重测
+    useEffect(() => {
+        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();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [markers]);
+    useEffect(() => () => {
+        if (revealTimer.current !== null)
+            window.clearTimeout(revealTimer.current);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const { top, max } = readBand();
+    return {
+        scrollable,
+        revealed,
+        syncScroll,
+        pageBy,
+        canPageUp: scrollable && top > 0,
+        canPageDown: scrollable && top < max - 1, // 1px 容差：滚动到底不再显示 ▼
+    };
+}
+/* ================= 卡片预览（风格能力：hoverCards） ================= */
+/** 卡片尺寸档位（档 0 选中卡最宽全文本 / 档 1 / 档 2 最窄） */
+const CARD_SIZES = [
+    { widthPx: 380, fontSize: 13, maxLines: 6 },
+    { widthPx: 300, fontSize: 12.5, maxLines: 2 },
+    { widthPx: 240, fontSize: 12, maxLines: 1 },
+];
+/** 距离 → 卡片呈现参数；聚焦窗口外返回 null */
+export function cardMetrics(distance) {
+    const magnitude = distance < 0 ? -distance : distance;
+    if (magnitude > CARD_SIZES.length - 1)
+        return null;
+    return CARD_SIZES[magnitude] ?? CARD_SIZES[CARD_SIZES.length - 1];
+}
+/** 距离 → 聚焦档（窗口内 0..2，窗口外 null；圆点缩放层级用） */
+export function markerTier(distance) {
+    const magnitude = distance < 0 ? -distance : distance;
+    return magnitude > CARD_SIZES.length - 1 ? null : magnitude;
+}
+/** 距离 → 放大倍数：仅选中点放大，邻居/窗口外均为 1 */
+export function markerScale(distance) {
+    return distance === 0 ? 1.5 : 1;
+}
+/** 卡片窗口：选中标记 ± radius 内的成员 */
+function cardSpan(markers, index, radius) {
+    const lo = Math.max(0, index - radius);
+    const hi = Math.min(markers.length - 1, index + radius);
+    const out = [];
+    for (let i = lo; i <= hi; i++) {
+        out.push({ dot: markers[i], distance: Math.abs(i - index) });
+    }
+    return out;
+}
+/**
+ * 卡片预览：悬停标记弹出级联卡（minimal 能力，enabled=false 时整组失效——
+ * 其他风格可无卡片）。
+ */
+export function useCardPreview(markers, align, radius, enabled) {
+    const [focus, setFocus] = useState(null);
+    const clearTimer = useRef(null);
+    const cancelClear = () => {
+        if (clearTimer.current !== null) {
+            window.clearTimeout(clearTimer.current);
+            clearTimer.current = null;
+        }
+    };
+    const scheduleClear = () => {
+        cancelClear();
+        clearTimer.current = window.setTimeout(() => setFocus(null), 240);
+    };
+    const openCards = (marker, target) => {
+        if (!enabled)
+            return;
+        const index = markers.findIndex((m) => m.key === marker.key);
+        if (index < 0)
+            return;
+        cancelClear();
+        const r = target.getBoundingClientRect();
+        const horizontal = align === 'right'
+            ? { right: window.innerWidth - r.left + 10 }
+            : { left: r.right + 10 };
+        setFocus({ key: marker.key, items: cardSpan(markers, index, radius), centerY: r.top + r.height / 2, ...horizontal });
+    };
+    // 半径（卡片数）变化时重算已打开的预览窗口
+    useEffect(() => {
+        if (focus === null || !enabled)
+            return;
+        const index = markers.findIndex((m) => m.key === focus.key);
+        if (index < 0)
+            return;
+        setFocus((prev) => (prev !== null && prev.key === focus.key ? { ...prev, items: cardSpan(markers, index, radius) } : prev));
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [radius, markers, enabled]);
+    useEffect(() => () => {
+        if (clearTimer.current !== null)
+            window.clearTimeout(clearTimer.current);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return { focus, openCards, cancelClear, scheduleClear };
+}
+/* ================= 失败提示 ================= */
+/** 跳转失败提示：监听 mega-chat-nav:jump-failed 事件，1.8s 后自动消退 */
+export function useFailureNotice(t) {
+    const [notice, setNotice] = useState(null);
+    const timer = useRef(null);
+    useEffect(() => {
+        const onFail = (event) => {
+            const code = event.detail ?? 'TIMEOUT';
+            const known = ['jump.inactive', 'jump.hidden', 'jump.notfound', 'jump.timeout'];
+            setNotice(t(known.includes(code) ? code : 'jump.timeout'));
+            if (timer.current !== null)
+                window.clearTimeout(timer.current);
+            timer.current = window.setTimeout(() => setNotice(null), 1800);
+        };
+        window.addEventListener('mega-chat-nav:jump-failed', onFail);
+        return () => {
+            window.removeEventListener('mega-chat-nav:jump-failed', onFail);
+            if (timer.current !== null)
+                window.clearTimeout(timer.current);
+        };
+    }, [t]);
+    return notice;
+}
+/* ================= 加载较早记录提示 ================= */
+/** 监听跳转编排的扩窗加载状态，显示「正在加载较早记录以定位…（第 N 页）」 */
+export function useLoadingNotice(t) {
+    const [state, setState] = useState({ loading: false, pages: 0 });
+    const timer = useRef(null);
+    useEffect(() => {
+        const onLoading = (event) => {
+            const detail = event.detail;
+            const on = detail?.loading === true;
+            setState({ loading: on, pages: detail?.pages ?? 0 });
+            if (on) {
+                if (timer.current !== null)
+                    window.clearTimeout(timer.current);
+                timer.current = window.setTimeout(() => setState({ loading: false, pages: 0 }), 10_000); // 兜底：最长 10s
+            }
+        };
+        window.addEventListener('mega-chat-nav:jump-loading', onLoading);
+        return () => {
+            window.removeEventListener('mega-chat-nav:jump-loading', onLoading);
+            if (timer.current !== null)
+                window.clearTimeout(timer.current);
+        };
+    }, []);
+    return state.loading ? t('jump.loading', { n: state.pages }) : null;
+}
+/* ================= 设置订阅 ================= */
+/** 设置订阅：全部配置项跟随（align/bandHeight/cardCount/显示模式/动画方式） */
+export function useNavSettings(injected) {
+    const [style, setStyle] = useState(() => injected?.style() ?? DEFAULT_STYLE);
+    const [align, setAlign] = useState(() => injected?.align() ?? DEFAULT_ALIGN);
+    const [bandHeight, setBandHeight] = useState(() => injected?.bandHeight() ?? DEFAULT_BAND);
+    const [cardCount, setCardCount] = useState(() => injected?.cardCount() ?? DEFAULT_CARD_COUNT);
+    const [cardItems, setCardItems] = useState(() => injected?.cardItems() ?? [...DEFAULT_CARD_ITEMS]);
+    const [scrollBehavior, setScrollBehavior] = useState(() => injected?.scrollBehavior() ?? DEFAULT_SCROLL);
+    const [showCount, setShowCount] = useState(() => injected?.showCount() ?? DEFAULT_SHOW);
+    const [showSearch, setShowSearch] = useState(() => injected?.showSearch() ?? DEFAULT_SHOW);
+    const [showQuickSettings, setShowQuickSettings] = useState(() => injected?.showQuickSettings() ?? DEFAULT_SHOW);
+    const [showFavorites, setShowFavorites] = useState(() => injected?.showFavorites() ?? DEFAULT_SHOW);
+    const [searchScopes, setSearchScopes] = useState(() => injected?.searchScopes() ?? [...DEFAULT_SEARCH_SCOPES]);
+    const [railOffset, setRailOffset] = useState(() => injected?.railOffset() ?? 8);
+    useEffect(() => {
+        if (injected === undefined)
+            return;
+        return injected.subscribeSettings(() => {
+            setStyle(injected.style());
+            setAlign(injected.align());
+            setBandHeight(injected.bandHeight());
+            setCardCount(injected.cardCount());
+            setCardItems(injected.cardItems());
+            setScrollBehavior(injected.scrollBehavior());
+            setShowCount(injected.showCount());
+            setShowSearch(injected.showSearch());
+            setShowQuickSettings(injected.showQuickSettings());
+            setShowFavorites(injected.showFavorites());
+            setSearchScopes(injected.searchScopes());
+            setRailOffset(injected.railOffset());
+        });
+    }, [injected]);
+    return { style, align, bandHeight, cardCount, cardItems, scrollBehavior, showCount, showSearch, showQuickSettings, showFavorites, searchScopes, railOffset };
+}
+/* ================= 时间工具（卡片/搜索结果相对时间） ================= */
+/** 相对时间：同日 HH:MM / 同年 MM-DD HH:MM / 跨年 YYYY-MM-DD HH:MM；非法输入返回空串 */
+export function clockText(time, now) {
+    if (!(time > 0) || !Number.isFinite(time))
+        return '';
+    const stamp = new Date(time);
+    const pad = (n) => String(n).padStart(2, '0');
+    const hm = pad(stamp.getHours()) + ':' + pad(stamp.getMinutes());
+    const ref = new Date(now);
+    const sameDay = stamp.getFullYear() === ref.getFullYear()
+        && stamp.getMonth() === ref.getMonth()
+        && stamp.getDate() === ref.getDate();
+    if (sameDay)
+        return hm;
+    const md = pad(stamp.getMonth() + 1) + '-' + pad(stamp.getDate());
+    if (stamp.getFullYear() === ref.getFullYear())
+        return md + ' ' + hm;
+    return stamp.getFullYear() + '-' + md + ' ' + hm;
+}
+/* ================= 收藏 ================= */
+const FAV_STORAGE_PREFIX = 'mega-chat-nav:favorites:';
+function readFavorites(sessionId) {
+    if (sessionId === undefined)
+        return new Set();
+    try {
+        const raw = window.localStorage.getItem(FAV_STORAGE_PREFIX + sessionId);
+        if (raw === null)
+            return new Set();
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return new Set();
+        return new Set(parsed.filter((k) => typeof k === 'string'));
+    }
+    catch {
+        return new Set();
+    }
+}
+function writeFavorites(sessionId, keys) {
+    try {
+        window.localStorage.setItem(FAV_STORAGE_PREFIX + sessionId, JSON.stringify([...keys]));
+    }
+    catch { /* 存储不可用时收藏仅内存态 */ }
+}
+/** 收藏状态：localStorage 持久化 + 切换动作（跨刷新保留） */
+export function useFavorites(sessionId) {
+    const [favorites, setFavorites] = useState(() => readFavorites(sessionId));
+    useEffect(() => {
+        setFavorites(readFavorites(sessionId));
+    }, [sessionId]);
+    const toggle = (key) => {
+        setFavorites((prev) => {
+            const next = new Set(prev);
+            if (next.has(key))
+                next.delete(key);
+            else
+                next.add(key);
+            if (sessionId !== undefined)
+                writeFavorites(sessionId, next);
+            return next;
+        });
+    };
+    return { favorites, toggle };
+}
+/* ================= 性能指标格式化 ================= */
+/** 毫秒 → 人类可读时长（1分21秒 / 10秒） */
+export function durationText(ms) {
+    const total = Math.max(0, Math.round(ms / 1000));
+    if (total >= 60) {
+        const m = Math.floor(total / 60);
+        const s = total % 60;
+        return m + '分' + s + '秒';
+    }
+    return total + '秒';
+}
+/** 完整指标行：本轮用时 1分21秒 · 首 token 10秒 · 188 tok/s */
+export function metricsLine(metrics) {
+    const parts = [];
+    parts.push('本轮用时 ' + durationText(metrics.durationMs));
+    if (metrics.firstTokenMs > 0)
+        parts.push('首 token ' + durationText(metrics.firstTokenMs));
+    if (metrics.tokensPerSec > 0)
+        parts.push(metrics.tokensPerSec + ' tok/s');
+    return parts.join(' · ');
+}
+/* ================= 手机模式 ================= */
+/** 手机模式：页面宽度小于 breakpoint（默认 1024px），resize 实时跟随 */
+export function useMobileMode(breakpoint = 1024) {
+    const [mobile, setMobile] = useState(() => window.innerWidth < breakpoint);
+    useEffect(() => {
+        const onResize = () => setMobile(window.innerWidth < breakpoint);
+        window.addEventListener('resize', onResize);
+        return () => window.removeEventListener('resize', onResize);
+    }, [breakpoint]);
+    return mobile;
+}
+/* ================= 手机模式搜索按钮（零高 sticky wrapper + absolute 按钮） ================= */
+/**
+ * 手机模式：向对话滚动容器 [data-conversation-scroll] 头部插入零高 wrapper
+ * （width:100%; height:0; sticky top:0; overflow:visible），按钮 absolute 相对
+ * wrapper 定位——sticky 粘在滚动视口顶部，按钮不随内容滚走、不占布局空间。
+ */
+export function useMobileSearchButton(onClick, enabled, align, label) {
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const host = mobileSearchHost();
+        if (host === null)
+            return;
+        // 零高 wrapper：sticky 粘在滚动容器顶部、不占空间；按钮 absolute 相对 wrapper 定位
+        const wrap = document.createElement('div');
+        wrap.style.width = '100%';
+        wrap.style.height = '0';
+        wrap.style.margin = '0';
+        wrap.style.position = 'sticky';
+        wrap.style.top = '0';
+        wrap.style.overflow = 'visible';
+        wrap.style.zIndex = '60';
+        wrap.style.pointerEvents = 'none'; // wrapper 不拦截，按钮自身可点
+        const btn = document.createElement('button');
+        btn.type = 'button';
+        btn.className = 'mgs-config-gear mgs-mobileSearch';
+        btn.setAttribute('aria-label', label);
+        btn.style.position = 'absolute';
+        btn.style.top = '8px';
+        btn.style[align === 'right' ? 'right' : 'left'] = '8px';
+        btn.style.zIndex = '60';
+        btn.style.pointerEvents = 'auto';
+        btn.innerHTML = '<svg class="mgs-btn-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"><circle cx="7" cy="7" r="4.5" fill="none" stroke="currentColor" stroke-width="1.6"/><line x1="10.4" y1="10.4" x2="14" y2="14" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg>';
+        btn.addEventListener('click', onClick);
+        wrap.appendChild(btn);
+        // 保证 wrapper 是父级第一个元素（sticky 相对滚动容器视口顶部）
+        host.insertBefore(wrap, host.firstChild);
+        return () => {
+            wrap.remove();
+        };
+    }, [enabled, onClick, align, label]);
+}