dsh-mega-chat-nav 0.1.1

package/lib/types/client/components/shared/types.d.ts

@@ -0,0 +1,101 @@
+import type { BandHeight, CardCount, CardItem, MarkTone, NavStyle, RailAlign, ScrollMode, SearchScope, ShowMode } from '../../settings.ts';
+/** 会话投影 face 最小面 */
+export interface ObservableFace {
+    getSnapshot: () => unknown;
+    subscribe: (listener: () => void) => () => void;
+}
+/** 回合标记：某回合的提问组（或一条未入投影的活提问） */
+export interface RailMarker {
+    /** 归属回合；活提问（投影未收）为 null */
+    readonly turn: number | null;
+    /** 跳转锚点：组内首问的聊天 key */
+    readonly key: string;
+    /** 首问锚点序号 */
+    readonly seq: number;
+    /** 首问时间 */
+    readonly time: number;
+    /** 组内全部提问文本（按序） */
+    readonly texts: readonly string[];
+    /** 组内全部聊天 key（活合并去重用） */
+    readonly members: readonly string[];
+    /** 该轮性能指标（投影附带；缺数据时省略） */
+    readonly metrics?: {
+        durationMs: number;
+        firstTokenMs: number;
+        tokensPerSec: number;
+    };
+}
+/** 注册注入面（client/index.ts 装配；各风格经此拿数据与动作） */
+export interface NavInjected {
+    readQuestions: (sessionId: string) => {
+        key: string;
+        anchorSeq: number;
+        seq: number;
+        time: number;
+        text: string;
+    }[];
+    subscribeList: (cb: () => void) => () => void;
+    subscribeContent: (sessionId: string, cb: () => void) => () => void;
+    questionProjection: (sessionId: string) => ObservableFace | undefined;
+    /** seq：目标轮序号（方向判定）；currentSeq：当前阅读位置序号（可选，下方判定优先用） */
+    jump: (sessionId: string, key: string, seq?: number, currentSeq?: number) => void;
+    style: () => NavStyle;
+    setStyle: (style: NavStyle) => void;
+    align: () => RailAlign;
+    subscribeSettings: (cb: () => void) => () => void;
+    setAlign: (align: RailAlign) => void;
+    bandHeight: () => BandHeight;
+    setBandHeight: (band: BandHeight) => void;
+    scrollBehavior: () => ScrollMode;
+    setScrollMode: (mode: ScrollMode) => void;
+    showCount: () => ShowMode;
+    setShowCount: (mode: ShowMode) => void;
+    showSearch: () => ShowMode;
+    setShowSearch: (mode: ShowMode) => void;
+    showQuickSettings: () => ShowMode;
+    setShowQuickSettings: (mode: ShowMode) => void;
+    showFavorites: () => ShowMode;
+    setShowFavorites: (mode: ShowMode) => void;
+    showPaging: () => ShowMode;
+    setShowPaging: (mode: ShowMode) => void;
+    searchScopes: () => SearchScope[];
+    setSearchScopes: (scopes: SearchScope[]) => void;
+    railOffset: () => number;
+    setRailOffset: (offset: number) => void;
+    cardCount: () => CardCount;
+    setCardCount: (count: CardCount) => void;
+    cardItems: () => CardItem[];
+    setCardItems: (items: CardItem[]) => void;
+    markTone: () => MarkTone;
+    setMarkTone: (tone: MarkTone) => void;
+}
+/** 悬停聚焦窗口项 */
+export interface FocusWindowItem {
+    dot: RailMarker;
+    distance: number;
+}
+/** 聚焦状态：卡片呈现所需几何 */
+export interface FocusState {
+    key: string;
+    items: FocusWindowItem[];
+    centerY: number;
+    left?: number;
+    right?: number;
+}
+/** 会话列表最小面（useSessions selector） */
+export interface SessionListLike {
+    current?: unknown;
+    byId?: Record<string, {
+        blank?: boolean;
+    }>;
+}
+/** 翻译函数面 */
+export type Translate = (key: string, vars?: Record<string, string | number>) => string;
+/** 会话选择器面（useSessions 最小面，宿主按风格组件注入） */
+export type SessionSelector = <S>(selector: (s: SessionListLike) => S) => S;
+/** 风格组件统一 props 面（各风格自治实现，但入参一致） */
+export interface RailProps {
+    injected: NavInjected | undefined;
+    useSessions?: SessionSelector;
+    t: Translate;
+}

package/lib/types/client/config.d.ts

@@ -0,0 +1,9 @@
+import type { NavConfig } from '../schema.ts';
+export interface ScopeLike {
+    getSnapshot(): {
+        value?: NavConfig;
+    };
+    subscribe(fn: () => void): () => void;
+    set(field: string, value: unknown): Promise<void>;
+    unset(field: string): Promise<void>;
+}

package/lib/types/client/engines/jump.d.ts

@@ -0,0 +1,17 @@
+export interface ScrollLike {
+    getBoundingClientRect(): DOMRect;
+    querySelectorAll(selectors: string): NodeListOf<Element>;
+    scrollTo(opts: {
+        top: number;
+        behavior?: ScrollBehavior;
+    }): void;
+}
+export interface JumpTarget {
+    key: string;
+}
+/** 在滚动容器内按锚点 key 定位行元素（持久 id 精确 → 13:input-message 前缀兜底） */
+export declare function findAnchorRow(scrollHost: ParentNode, key: string): Element | null;
+/** 平滑滚动到行（reduced-motion 用瞬时；返回是否成功） */
+export declare function scrollToRow(scrollHost: ScrollLike, row: Element, behavior: ScrollBehavior): boolean;
+/** 原文脉冲高亮：给目标行挂临时 class，pulseMs 后移除 */
+export declare function pulseRow(row: Element, pulseMs: number): () => void;

package/lib/types/client/engines/useAtBottom.d.ts

@@ -0,0 +1 @@
+export declare function useAtBottom(threshold?: number): boolean;

package/lib/types/client/engines/useJump.d.ts

@@ -0,0 +1,16 @@
+export interface SessionLike {
+    loadOlder(): Promise<void>;
+    getSnapshot(): {
+        hasMore: boolean;
+        loadingOlder: boolean;
+    };
+}
+export interface JumpOptions {
+    getSession?(): SessionLike | undefined;
+    maxPages?: number;
+}
+export declare function useJump(scrollBehavior: 'smooth' | 'instant', pulseMs: number, opts?: JumpOptions): {
+    failed: boolean;
+    jumping: boolean;
+    jump: (key: string) => Promise<void>;
+};

package/lib/types/client/engines/useScrollSpy.d.ts

@@ -0,0 +1,12 @@
+import type { AnchorRule } from '../pure.ts';
+/** 行锚点缓存：一次扫描建立 key → 行元素（MutationObserver 失效重扫） */
+export declare function scanAnchors(root: ParentNode): Map<string, Element>;
+export interface ScrollSpyOptions {
+    rule: AnchorRule;
+    /** nav item 候选键（= 投影 items 的 key 列表） */
+    keys: readonly string[];
+    enabled: boolean;
+    /** 触底判定（新消息跟随：仍在底部 → 最新） */
+    atBottom?(): boolean;
+}
+export declare function useScrollSpy(opts: ScrollSpyOptions): string | null;

package/lib/types/client/hooks.d.ts

@@ -0,0 +1,7 @@
+import type { NavConfig } from '../schema.ts';
+export declare function useScope(scope?: {
+    getSnapshot(): {
+        value?: NavConfig;
+    };
+    subscribe(fn: () => void): () => void;
+}): NavConfig | undefined;

package/lib/types/client/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Browser-half entry for the dsh-mega-chat-nav plugin.
+ *
+ * Registers one surface into the frame-wide floating layer (`shell.overlay`):
+ * a vertical strip on the LEFT edge of the conversation column listing every
+ * user question in the current session as a small button, one dot per turn.
+ * Clicking a button scrolls the chat to that turn's first question.
+ *
+ * The dots are driven by the host-folded `msgNavMessages` session projection
+ * (registered by the plugin's host half): the projection registry folds the
+ * WHOLE event log without touching the chat's paged render window, the
+ * projection cache persists it, and the standard carriers (history tail-page
+ * baseline + session/projection push frames) keep it live. Live-window
+ * questions not yet recorded by the projection are merged on top so a
+ * just-sent question appears immediately.
+ *
+ * Failure policy: nothing here throws at apply time — an external plugin must
+ * never take the GUI down.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+/** Services required by this plugin. */
+export declare const inject: string[];
+/** Single-instance guard: a duplicated client injection must not mount twice. */
+declare global {
+    var __dshMegaChatNavApplied: boolean | undefined;
+}
+/**
+ * Register the mega-chat-nav surface.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/jump.d.ts

@@ -0,0 +1,47 @@
+/** 跳转循环所需的会话快照面 */
+export interface JumpSnapshot {
+    openState: string;
+    hasMore: boolean;
+    loadingOlder: boolean;
+    rows: Iterable<{
+        key: string;
+        anchorSeq: number;
+        visibility?: string;
+    }>;
+}
+/** 外部端口：会话读写、DOM 行查找、滚动与时钟（由浏览器半装配） */
+export interface JumpPorts {
+    snap: () => JumpSnapshot | undefined;
+    loadMore: () => Promise<void>;
+    active: () => boolean;
+    locate: (key: string) => HTMLElement | null;
+    reveal: (row: HTMLElement, mode: 'smooth' | 'instant') => void;
+    /** 会话滚动容器（虚拟渲染按 scrollTop 触发） */
+    scrollport: () => HTMLElement | null;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    report?: (code: JumpFailureCode, fallback?: boolean) => void;
+    /** 扩窗加载进度（loading 状态 + 已加载页数），驱动「正在加载较早记录」提示 */
+    onLoading?: (loading: boolean, pages: number) => void;
+}
+export type JumpFailureCode = 'VIEW_INACTIVE' | 'TARGET_HIDDEN' | 'NOT_FOUND' | 'TIMEOUT';
+interface JumpResult {
+    ok: boolean;
+    code?: JumpFailureCode;
+    fallback?: boolean;
+}
+interface JumpOptions {
+    totalTimeoutMs?: number;
+    maxPages?: number;
+    rowWaitMs?: number;
+    pollMs?: number;
+}
+/**
+ * 跳转到 key 对应行：
+ *   - 目标已在渲染窗口 → 等待 DOM 并滚动；
+ *   - 目标在下方/窗口内（targetSeq ≥ 渲染窗口最小值）→ 向下滚动定位（无需加载）；
+ *   - 目标更早（targetSeq < 渲染窗口最小值 或未知）→ 预算内 loadOlder 补历史，每页后向上滚动定位；
+ *   - 全部失败 → 回退最近可渲染行。
+ */
+export declare function goTo(ports: JumpPorts, key: string, options?: JumpOptions, mode?: 'smooth' | 'instant', targetSeq?: number, currentSeq?: number): Promise<JumpResult>;
+export {};

package/lib/types/client/locales.d.ts

@@ -0,0 +1,142 @@
+/**
+ * mega-chat-nav 词条字典（zh/en）。注册于 `mega-chat-nav` 命名空间；
+ * key 经绑定翻译函数消费。
+ */
+export declare const zh: {
+    readonly 'strip.empty': "本会话还没有提问";
+    readonly 'strip.up': "向上翻出更多提问圆点";
+    readonly 'strip.down': "向下翻出更多提问圆点";
+    readonly 'jump.inactive': "聊天视图未激活";
+    readonly 'jump.hidden': "目标无独立气泡，已定位到邻近内容";
+    readonly 'jump.notfound': "目标未加载或不存在（可能已压缩）";
+    readonly 'jump.timeout': "加载历史超时，可重试";
+    readonly 'jump.loading': "正在加载较早记录以定位（第 {n} 页）";
+    readonly 'search.historic': "另有 {n} 条来自更早历史";
+    readonly 'search.turnTitle': "第 {turn} 轮";
+    readonly 'search.tag.user': "用户";
+    readonly 'search.tag.assistant': "助手";
+    readonly 'search.tag.tool': "工具";
+    readonly 'settings.tab': "提问导航";
+    readonly label: "mega 导航";
+    readonly 'config.align': "对齐方式";
+    readonly 'config.railOffset': "导航栏偏移";
+    readonly 'config.railOffset.desc': "导航条与对话列边缘的距离（0-32px，随左右对齐自适应）。";
+    readonly 'settings.align.desc': "选择圆点导航条锚定在对话栏的哪一侧。";
+    readonly 'settings.align.left': "左侧";
+    readonly 'settings.align.right': "右侧";
+    readonly 'settings.hosted': "配置已收纳至 mega 设置中心";
+    readonly 'config.bandHeight': "节点栏高度";
+    readonly 'config.bandHeight.desc': "节点栏的最大高度。";
+    readonly 'config.bandHeight.compact': "紧凑";
+    readonly 'config.bandHeight.standard': "标准";
+    readonly 'config.bandHeight.tall': "高";
+    readonly 'config.title': "导航条设置";
+    readonly 'config.settings': "设置";
+    readonly 'config.close': "关闭";
+    readonly 'config.scrollBehavior': "跳转动画";
+    readonly 'config.scrollBehavior.desc': "点击跳转时消息滚入的动画方式。";
+    readonly 'config.scrollBehavior.smooth': "平滑";
+    readonly 'config.scrollBehavior.instant': "瞬时";
+    readonly 'config.showCount': "轮次总数";
+    readonly 'config.showPaging': "翻页标记";
+    readonly 'config.showQuickSettings': "设置按钮";
+    readonly 'config.showFavorites': "收藏按钮";
+    readonly 'config.searchScopes': "搜索内容";
+    readonly 'config.searchScopes.desc': "搜索哪些消息类型（多选；用户必选）。";
+    readonly 'config.searchScopes.user': "用户";
+    readonly 'config.searchScopes.assistant': "助手";
+    readonly 'config.searchScopes.tool': "工具";
+    readonly 'config.style': "风格";
+    readonly 'config.style.minimal': "简约";
+    readonly 'config.style.codex': "Codex";
+    readonly 'config.style.deepseek': "Deepseek Chat";
+    readonly 'config.cardCount': "悬停卡片数";
+    readonly 'config.cardCount.desc': "悬停节点时弹出的卡片数量（1/3/5 张）。";
+    readonly 'config.cardItems': "悬浮卡功能";
+    readonly 'config.cardItems.desc': "勾选悬浮卡显示的内容块（多选）。";
+    readonly 'config.cardItems.turn': "轮次";
+    readonly 'config.cardItems.duration': "用时";
+    readonly 'config.cardItems.favorite': "收藏";
+    readonly 'config.markTone': "刻度色调";
+    readonly 'config.markTone.desc': "codex 刻度条的明暗档：柔和低对比 / 深邃高对比（默认）。";
+    readonly 'config.markTone.soft': "柔和";
+    readonly 'config.markTone.deep': "深邃";
+    readonly 'fav.filter': "只看收藏";
+    readonly 'strip.noFavorites': "暂无收藏";
+    readonly 'config.showSearch': "搜索按钮";
+    readonly 'config.showMode.show': "显示";
+    readonly 'config.showMode.peek': "浮现";
+    readonly 'config.showMode.hide': "隐藏";
+    readonly 'search.placeholder': "搜索消息…";
+    readonly 'search.empty': "无匹配结果";
+    readonly 'search.loading': "正在搜索…";
+};
+export declare const en: {
+    readonly 'strip.empty': "No questions in this session yet";
+    readonly 'strip.up': "Reveal more question dots above";
+    readonly 'strip.down': "Reveal more question dots below";
+    readonly 'jump.inactive': "Chat view is not active";
+    readonly 'jump.hidden': "No dedicated bubble; landed on nearby content";
+    readonly 'jump.notfound': "Target not loaded or missing (maybe compacted)";
+    readonly 'jump.timeout': "Timed out loading history; retry";
+    readonly 'jump.loading': "Loading earlier records to locate (page {n})";
+    readonly 'search.historic': "{n} more from earlier history";
+    readonly 'search.turnTitle': "Turn {turn}";
+    readonly 'search.tag.user': "User";
+    readonly 'search.tag.assistant': "Assistant";
+    readonly 'search.tag.tool': "Tool";
+    readonly 'settings.tab': "Question Nav";
+    readonly label: "Mega Nav";
+    readonly 'config.align': "Alignment";
+    readonly 'config.railOffset': "Rail offset";
+    readonly 'config.railOffset.desc': "Distance between the rail and the conversation edge (0-32px, adapts to alignment).";
+    readonly 'settings.align.desc': "Choose which edge of the conversation column the dot rail anchors to.";
+    readonly 'settings.align.left': "Left";
+    readonly 'settings.align.right': "Right";
+    readonly 'settings.hosted': "Config is hosted in the mega settings center";
+    readonly 'config.bandHeight': "Band height";
+    readonly 'config.bandHeight.desc': "Max height of the dot band.";
+    readonly 'config.bandHeight.compact': "Compact";
+    readonly 'config.bandHeight.standard': "Standard";
+    readonly 'config.bandHeight.tall': "Tall";
+    readonly 'config.title': "Nav settings";
+    readonly 'config.settings': "Settings";
+    readonly 'config.close': "Close";
+    readonly 'config.scrollBehavior': "Jump animation";
+    readonly 'config.scrollBehavior.desc': "How the chat scrolls when jumping to a message.";
+    readonly 'config.scrollBehavior.smooth': "Smooth";
+    readonly 'config.scrollBehavior.instant': "Instant";
+    readonly 'config.showCount': "Turn count";
+    readonly 'config.showPaging': "Paging markers";
+    readonly 'config.showQuickSettings': "Settings button";
+    readonly 'config.showFavorites': "Favorite button";
+    readonly 'config.searchScopes': "Search content";
+    readonly 'config.searchScopes.desc': "Message types included in search (multi-select; user is required).";
+    readonly 'config.searchScopes.user': "User";
+    readonly 'config.searchScopes.assistant': "Assistant";
+    readonly 'config.searchScopes.tool': "Tool";
+    readonly 'config.style': "Style";
+    readonly 'config.style.minimal': "Minimal";
+    readonly 'config.style.codex': "Codex";
+    readonly 'config.style.deepseek': "Deepseek Chat";
+    readonly 'config.cardCount': "Card count";
+    readonly 'config.cardCount.desc': "Cascade cards shown on hover (1/3/5).";
+    readonly 'config.cardItems': "Card contents";
+    readonly 'config.cardItems.desc': "Content blocks shown on hover cards (multi-select).";
+    readonly 'config.cardItems.turn': "Turn";
+    readonly 'config.cardItems.duration': "Duration";
+    readonly 'config.cardItems.favorite': "Favorite";
+    readonly 'config.markTone': "Mark tone";
+    readonly 'config.markTone.desc': "Codex tick contrast: soft / deep (default).";
+    readonly 'config.markTone.soft': "Soft";
+    readonly 'config.markTone.deep': "Deep";
+    readonly 'fav.filter': "Favorites only";
+    readonly 'strip.noFavorites': "No favorites yet";
+    readonly 'config.showSearch': "Search button";
+    readonly 'config.showMode.show': "Show";
+    readonly 'config.showMode.peek': "Peek";
+    readonly 'config.showMode.hide': "Hide";
+    readonly 'search.placeholder': "Search messages…";
+    readonly 'search.empty': "No matches";
+    readonly 'search.loading': "Searching…";
+};

package/lib/types/client/pure.d.ts

@@ -0,0 +1,21 @@
+export type AnchorRule = 'line40' | 'top' | 'center' | 'lastInteraction';
+/** TabGate：chat 视图可见（R-10）——滚动容器存在且几何 >0 */
+export declare function isChatViewVisible(doc: Document): boolean;
+/** TabGate：Trajectory（轨迹）视图在场时 nav 停用 */
+export declare function hasTrajectoryView(doc: Document): boolean;
+/** 锚点规则 → 阅读线 Y（视口坐标系） */
+export declare function readingLineY(viewport: {
+    top: number;
+    height: number;
+}, rule: AnchorRule): number;
+/** 距阅读线最近条目索引（40% 线主流判据；无条目返回 -1） */
+export declare function nearestIndex(total: number, line: number, yOf: (i: number) => number): number;
+/** 虚拟滚动窗口（可见 + 前后缓冲；hover/current 由调用方钉住） */
+export declare function virtualWindow(total: number, scrollTop: number, viewportH: number, itemH: number, buffer?: number): {
+    start: number;
+    end: number;
+};
+/** 相对时间（秒/分钟/小时/天） */
+export declare function formatTime(ts: number, now?: number): string;
+/** 截断到 n 字符并加省略号 */
+export declare function truncate(s: string, n: number): string;

package/lib/types/client/settings.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Browser mirror of the `mega-chat-nav` settings namespace: reads the rail
+ * settings from the settings scope (`ctx.settingsScope.bind`) and routes the
+ * user's choices back through the host bridge (POST /mega-chat-nav/settings).
+ *
+ * 配置选项为本插件自有定义：此处为 client 半持有的同值副本（与 host 半
+ * src/settings.ts 一致；client bundle 不得依赖宿主包）。
+ *
+ * The settings surface is optional and may apply after this plugin, so the
+ * controller starts unbound and degrades to the defaults until {@link attach}
+ * binds the scope.
+ *
+ * @module dsh-mega-chat-nav/client/settings
+ */
+import type { SettingsScope, SettingsScopeSpec } from '@deepseek-ai/dsh-client-runtime/client';
+/** 风格选项：简约 / codex（时间线刻度）/ deepseek（用户消息面板，常态短横折叠） */
+export declare const STYLE_OPTIONS: readonly ["minimal", "codex", "deepseek"];
+export type NavStyle = typeof STYLE_OPTIONS[number];
+/** 停靠侧选项 */
+export declare const ALIGN_OPTIONS: readonly ["left", "right"];
+export type RailAlign = typeof ALIGN_OPTIONS[number];
+/** 节点栏条带高度档位 */
+export declare const BAND_OPTIONS: readonly ["compact", "standard", "tall"];
+export type BandHeight = typeof BAND_OPTIONS[number];
+/** 跳转动画方式 */
+export declare const SCROLL_OPTIONS: readonly ["smooth", "instant"];
+export type ScrollMode = typeof SCROLL_OPTIONS[number];
+/** 显示策略：常显 / 悬停浮现 / 隐藏 */
+export declare const SHOW_OPTIONS: readonly ["show", "peek", "hide"];
+export type ShowMode = typeof SHOW_OPTIONS[number];
+/** 翻页标记显示策略（按风格独立默认）：minimal 常显 / codex 隐藏 / deepseek 浮现 */
+export declare const DEFAULT_PAGING: Record<NavStyle, ShowMode>;
+/** 搜索内容范围（多选；用户必选） */
+export declare const SEARCH_SCOPE_OPTIONS: readonly ["user", "assistant", "tool"];
+export type SearchScope = typeof SEARCH_SCOPE_OPTIONS[number];
+export declare const DEFAULT_SEARCH_SCOPES: SearchScope[];
+/** 悬停卡片数量 */
+export declare const CARD_OPTIONS: readonly [1, 3, 5];
+export type CardCount = typeof CARD_OPTIONS[number];
+/** 悬浮卡默认数量（按风格独立）：minimal 3 张 / codex 1 张 / deepseek 1 张（无悬浮卡能力，占位） */
+export declare const DEFAULT_CARD_COUNT: Record<NavStyle, CardCount>;
+/** 悬浮卡内容块（多选） */
+export declare const CARD_ITEM_OPTIONS: readonly ["turn", "duration", "favorite"];
+export type CardItem = typeof CARD_ITEM_OPTIONS[number];
+export declare const DEFAULT_CARD_ITEMS: CardItem[];
+/** 刻度色调：柔和（低对比）/ 深邃（高对比、清晰） */
+export declare const MARK_TONE_OPTIONS: readonly ["soft", "deep"];
+export type MarkTone = typeof MARK_TONE_OPTIONS[number];
+export declare const DEFAULT_MARK_TONE: MarkTone;
+export declare const DEFAULT_STYLE: NavStyle;
+export declare const DEFAULT_ALIGN: RailAlign;
+export declare const DEFAULT_BAND: BandHeight;
+export declare const DEFAULT_SCROLL: ScrollMode;
+export declare const DEFAULT_SHOW: ShowMode;
+/** 条带高度档位 → 像素（minimal/codex 共用基础几何；deepseek 行高 30px 自成一档）
+ *  - minimal / codex：compact 140 / standard 210 / tall 280
+ *  - deepseek：compact 160 / standard 220 / tall 280 */
+export declare const BAND_HEIGHT_PX: Record<NavStyle, Record<BandHeight, number>>;
+/** 风格能力：各风格声明自己的可选能力（组件与设置面据此取舍） */
+export interface StyleCapabilities {
+    /** 悬停悬浮卡片（级联预览）——deepseek 面板自带消息预览，不需要 */
+    hoverCards: boolean;
+    /** ▲/▼ 翻页标志（deepseek 面板内滚动，不需要显式翻页按钮） */
+    paging: boolean;
+}
+/** 风格 → 能力表 */
+export declare const STYLE_CAPABILITIES: Record<NavStyle, StyleCapabilities>;
+/** 本插件设置命名空间 */
+export declare const MGCN_NS = "mega-chat-nav";
+/** 导航栏偏移（px）范围与默认值 */
+export declare const RAIL_OFFSET_MIN = 0;
+export declare const RAIL_OFFSET_MAX = 32;
+export declare const DEFAULT_RAIL_OFFSET = 8;
+/** The minimal face of the settings scope service this controller needs. */
+export interface SettingsScopeBinderLike {
+    bind<T>(spec: SettingsScopeSpec<T>): SettingsScope<T>;
+}
+/** Snapshot consumed by the strip and the settings rows. */
+export interface NavSettingsState {
+    /** Last accepted style. */
+    style: NavStyle;
+    /** Last accepted anchor edge (default while the scope is absent/loading). */
+    align: RailAlign;
+    /** Last accepted band height tier. */
+    bandHeight: BandHeight;
+    /** Last accepted jump scroll mode. */
+    scrollBehavior: ScrollMode;
+    /** Turn-count badge display mode. */
+    showCount: ShowMode;
+    /** Search button display mode. */
+    showSearch: ShowMode;
+    /** Quick settings gear display mode. */
+    showQuickSettings: ShowMode;
+    /** Favorite filter button display mode. */
+    showFavorites: ShowMode;
+    /** 翻页标记显示模式（show=常显 / peek=浮现 / hide=隐藏） */
+    showPaging: ShowMode;
+    /** 搜索内容范围（多选；用户必选） */
+    searchScopes: SearchScope[];
+    /** 导航栏偏移距离（px，随左右对齐自适应） */
+    railOffset: number;
+    /** Hover cascade card count. */
+    cardCount: CardCount;
+    /** 悬浮卡内容块（多选：轮次 / 用时 / 收藏） */
+    cardItems: CardItem[];
+    /** 刻度色调（codex 刻度轨；minimal 忽略） */
+    markTone: MarkTone;
+    /** Whether the user layer overrides the composition default. */
+    overridden: boolean;
+}
+/** Reactive handle over the plugin's durable settings section. */
+export declare class NavSettingsController {
+    private scope;
+    private readonly listeners;
+    private unsubscribe;
+    private state;
+    /**
+     * Bind the namespace scope once the settings surface is present.
+     * A no-op after the first bind.
+     */
+    attach(binder: SettingsScopeBinderLike): void;
+    /** 当前生效风格的 styles.<style> 段（快照内读取，供逐风格独立取值） */
+    private styleSection;
+    private derive;
+    /** Release the scope subscription. */
+    dispose(): void;
+    /** 乐观提交：更新状态并立即通知（UI 即时反映） */
+    private commit;
+    /** 当前 general 段（setter 整段写回用） */
+    private get general();
+    /** 当前风格段的完整值（setter 局部 patch 的基础） */
+    private get styleValues();
+    /** 按当前风格构造 write 的 styles 段（只含当前风格键，绝不染指其他风格段） */
+    private stylePatch;
+    /** @returns the current state (stable reference until the next change). */
+    getSnapshot(): NavSettingsState;
+    /** Observe state replacements; returns the disposer. */
+    subscribe(listener: () => void): () => void;
+    /**
+     * 写回宿主：scope.set 契约只接受 section 内**标量**字段，嵌套 section
+     * （general/styles 对象）无法经它持久化，所以走 host 桥
+     * （POST /mega-chat-nav/settings → settings.update 深层 merge + revision 围栏）。
+     */
+    private write;
+    /** Route the user's anchor-edge choice to the Host document. */
+    setAlign(align: RailAlign): void;
+    /** Route the user's style choice to the Host document（切换后随即载入该风格自己的独立配置） */
+    setStyle(style: NavStyle): void;
+    /** Route the user's band-height choice to the Host document（写入当前风格的独立段） */
+    setBandHeight(band: BandHeight): void;
+    /** Route the user's scroll-mode choice to the Host document. */
+    setScrollMode(mode: ScrollMode): void;
+    /** Route the user's count-badge display mode to the Host document. */
+    setShowCount(mode: ShowMode): void;
+    /** Route the user's search-button display mode to the Host document. */
+    setShowSearch(mode: ShowMode): void;
+    /** Route the user's quick-settings display mode to the Host document. */
+    setShowQuickSettings(mode: ShowMode): void;
+    /** Route the user's favorite-button display mode to the Host document. */
+    setShowFavorites(mode: ShowMode): void;
+    /** Route the user's paging-marker display mode to the Host document（写入当前风格独立段） */
+    setShowPaging(mode: ShowMode): void;
+    /** Route the user's search-scope selection to the Host document（用户必选，强制保留且置于首位） */
+    setSearchScopes(scopes: SearchScope[]): void;
+    /** Route the user's rail-offset choice to the Host document（0-32px 取整钳制） */
+    setRailOffset(offset: number): void;
+    /** Route the user's cascade-card count to the Host document（写入当前风格的独立段） */
+    setCardCount(count: CardCount): void;
+    /** Route the user's card-content selection to the Host document（写入当前风格的独立段） */
+    setCardItems(items: CardItem[]): void;
+    /** Route the user's mark-tone choice to the Host document（codex 刻度色调；写入当前风格段） */
+    setMarkTone(tone: MarkTone): void;
+}

package/lib/types/client/virtual/VirtualList.d.ts

@@ -0,0 +1,15 @@
+import { type ReactNode } from 'react';
+export interface VirtualListProps<T> {
+    items: readonly T[];
+    itemHeight: number;
+    viewportHeight: number;
+    scrollTop: number;
+    onScrollTopChange(top: number): void;
+    renderItem(item: T, index: number): ReactNode;
+    keyOf(item: T, index: number): string;
+    pinned?: ReadonlySet<string>;
+    overscan?: number;
+    listRef?: React.Ref<HTMLDivElement>;
+    onKeyDown?: (e: React.KeyboardEvent) => void;
+}
+export declare function VirtualList<T>(props: VirtualListProps<T>): ReactNode;

package/lib/types/compat.d.ts

@@ -0,0 +1,44 @@
+/**
+ * dsh 版本校验器（纯函数，零依赖：宿主侧 / 单测均可用）。
+ *
+ * 语义（对齐官方 deepseek-harness tag 线，如 dsh-v0.1.1-rc.2）：
+ * - 比较按语义化版本：主/次/修订号数值比较优先；
+ * - 同基线预发布排序：alpha < rc（标识符字典序），数字标识按数值比较；
+ * - 正式版（无预发布）高于同基线任意预发布（0.1.1 > 0.1.1-rc.2）；
+ * - 支持操作符：>  <  =（另附 >=  <=）；
+ * - 通配：仅 '=' 支持，如 '0.1.1-*' 匹配该基线的任意预发布（0.1.1-rc.1 / 0.1.1-rc.2 …）；
+ *   '*' 作为标识段时吞掉其后的全部剩余标识。
+ */
+export type DshCmpOp = '>' | '>=' | '<' | '<=' | '=';
+/** 兼容策略：当前 dsh 版本与目标的比较约束。 */
+export interface DshCompatPolicy {
+    op: DshCmpOp;
+    /**
+     * 目标版本（可含通配，如 0.1.1-*，仅 op='=' 生效）。
+     * 支持数组：命中其中任一版本即通过，如 ['0.1.1-*', '0.1.2-rc.1']。
+     */
+    target: string | readonly string[];
+}
+export interface DshVersionParts {
+    /** [major, minor, patch] */
+    base: [number, number, number];
+    /** 预发布标识数组（rc、alpha、数字…）；无预发布 = null */
+    pre: string[] | null;
+}
+/** 解析 dsh 版本串；非法返回 null（不支持 x.y / 纯数字 etc.）。 */
+export declare function parseDshVersion(v: string): DshVersionParts | null;
+/**
+ * 语义化比较：a < b → -1；相等 → 0；a > b → 1；任一无法解析 → NaN。
+ */
+export declare function compareDshVersions(a: string, b: string): number;
+/** 操作符比较（非法版本一律 false）。 */
+export declare function checkDshVersion(current: string, op: DshCmpOp, target: string): boolean;
+/**
+ * 通配相等（仅配合 op='='）：pattern 形如 0.1.1-*（任意预发布）、0.1.1-rc.*、
+ * 0.1.*（任意小版本）等；'*' 匹配 ≥1 个标识。例：0.1.1-* 命中 0.1.1-rc.1 / 0.1.1-rc.2。
+ */
+export declare function wildcardEqual(version: string, pattern: string): boolean;
+/** 策略校验：target 为数组时命中任一即通过；通配（如 0.1.1-*）仅在 op='=' 时参与。 */
+export declare function checkDshPolicy(current: string, policy: DshCompatPolicy): boolean;
+/** 不兼容时的控制台提示文案（xxx = 检测到的当前 dsh 版本）。 */
+export declare function dshCompatMessage(pluginName: string, currentDshVersion: string): string;