dsh-mega-chat-nav 0.1.1

package/lib/types/config.d.ts

@@ -0,0 +1,44 @@
+/** 风格选项（当前仅「简约」；后续风格在组件层扩展） */
+export declare const StyleOptions: readonly ["minimal"];
+export type NavStyle = typeof StyleOptions[number];
+export declare const DEFAULT_STYLE: NavStyle;
+/** 停靠侧选项与默认值 */
+export declare const AlignOptions: readonly ["left", "right"];
+export type RailAlign = typeof AlignOptions[number];
+export declare const DEFAULT_RAIL_ALIGN: RailAlign;
+/** 节点栏条带高度档位（决定当前可见节点数：≈10/15/20 个） */
+export declare const BandHeightOptions: readonly ["compact", "standard", "tall"];
+export type BandHeight = typeof BandHeightOptions[number];
+export declare const DEFAULT_BAND: BandHeight;
+/** 档位 → 条带最大高度（px）：节点行高 14px × 10/15/20 */
+export declare const BAND_HEIGHT_PX: Record<BandHeight, number>;
+/** 跳转动画方式 */
+export declare const ScrollModeOptions: readonly ["smooth", "instant"];
+export type ScrollMode = typeof ScrollModeOptions[number];
+export declare const DEFAULT_SCROLL_MODE: ScrollMode;
+/** 显示策略：常显 / 悬停浮现 / 隐藏 */
+export declare const ShowModeOptions: readonly ["show", "peek", "hide"];
+export type ShowMode = typeof ShowModeOptions[number];
+export declare const DEFAULT_SHOW: ShowMode;
+/** 悬停级联卡数量（1/3/5 张） */
+export declare const CardCountOptions: readonly [1, 3, 5];
+export type CardCount = typeof CardCountOptions[number];
+export declare const DEFAULT_CARD_COUNT: CardCount;
+/** 风格能力：各风格声明自己的可选能力（组件与设置面据此取舍） */
+export interface StyleCapabilities {
+    /** 悬停悬浮卡片（级联预览）——其他风格可能没有 */
+    hoverCards: boolean;
+}
+/** 风格 → 能力表 */
+export declare const STYLE_CAPABILITIES: Record<NavStyle, StyleCapabilities>;
+/** 设置键名（嵌套 schema 字段名；client 桥写回与 host schema 共用） */
+export declare const STYLE_KEY = "style";
+export declare const ALIGN_KEY = "align";
+export declare const BAND_KEY = "bandHeight";
+export declare const SCROLL_KEY = "scrollBehavior";
+export declare const SHOW_COUNT_KEY = "showCount";
+export declare const SHOW_SEARCH_KEY = "showSearch";
+export declare const SHOW_QUICK_KEY = "showQuickSettings";
+export declare const CARD_COUNT_KEY = "cardCount";
+/** 本插件设置命名空间（拼写而非导入：client bundle 不得依赖宿主包） */
+export declare const MGS_NS = "mega-chat-nav";

package/lib/types/core/active-dot.d.ts

@@ -0,0 +1,15 @@
+/** 一行圆点锚点行的位置测量（滚动口坐标系） */
+export interface DotRowMeasure {
+    /** 圆点 key（回合跳转锚点） */
+    key: string;
+    /** 行顶到滚动口顶的像素差 */
+    top: number;
+}
+/**
+ * 选取标记圆点：阅读线之上（含）的最后一行为当前回合；
+ * 阅读线在所有行之上（开场问答之前）时取第一行兜底；无渲染行返回 null。
+ * 行按圆点顺序输入；扫描保留最后一个满足项，单条乱序测量不回退标记。
+ */
+export declare function nearestReadDot(rows: readonly DotRowMeasure[], readingLine: number): string | null;
+/** 阅读线固定为视口顶部（0） */
+export declare const READING_LINE_TOP = 0;

package/lib/types/core/align.d.ts

@@ -0,0 +1,10 @@
+/** 可选停靠侧 */
+export declare const AlignOptions: readonly ["left", "right"];
+/** 停靠侧偏好 */
+export type RailAlign = typeof AlignOptions[number];
+/** 默认停靠侧（设置文档无覆盖时） */
+export declare const DEFAULT_RAIL_ALIGN: RailAlign;
+/** 本插件设置命名空间（此处拼写而非导入：client bundle 不得依赖宿主包） */
+export declare const MGS_NS = "mega-chat-nav";
+/** 设置字段：停靠侧 */
+export declare const ALIGN_KEY = "align";

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

@@ -0,0 +1,44 @@
+/** 风格选项（当前仅「简约」；后续风格在组件层扩展） */
+export declare const StyleOptions: readonly ["minimal"];
+export type NavStyle = typeof StyleOptions[number];
+export declare const DEFAULT_STYLE: NavStyle;
+/** 停靠侧选项与默认值 */
+export declare const AlignOptions: readonly ["left", "right"];
+export type RailAlign = typeof AlignOptions[number];
+export declare const DEFAULT_RAIL_ALIGN: RailAlign;
+/** 节点栏条带高度档位（决定当前可见节点数：≈10/15/20 个） */
+export declare const BandHeightOptions: readonly ["compact", "standard", "tall"];
+export type BandHeight = typeof BandHeightOptions[number];
+export declare const DEFAULT_BAND: BandHeight;
+/** 档位 → 条带最大高度（px）：节点行高 14px × 10/15/20 */
+export declare const BAND_HEIGHT_PX: Record<BandHeight, number>;
+/** 跳转动画方式 */
+export declare const ScrollModeOptions: readonly ["smooth", "instant"];
+export type ScrollMode = typeof ScrollModeOptions[number];
+export declare const DEFAULT_SCROLL_MODE: ScrollMode;
+/** 显示策略：常显 / 悬停浮现 / 隐藏 */
+export declare const ShowModeOptions: readonly ["show", "peek", "hide"];
+export type ShowMode = typeof ShowModeOptions[number];
+export declare const DEFAULT_SHOW: ShowMode;
+/** 悬停级联卡数量（1/3/5 张） */
+export declare const CardCountOptions: readonly [1, 3, 5];
+export type CardCount = typeof CardCountOptions[number];
+export declare const DEFAULT_CARD_COUNT: CardCount;
+/** 风格能力：各风格声明自己的可选能力（组件与设置面据此取舍） */
+export interface StyleCapabilities {
+    /** 悬停悬浮卡片（级联预览）——其他风格可能没有 */
+    hoverCards: boolean;
+}
+/** 风格 → 能力表 */
+export declare const STYLE_CAPABILITIES: Record<NavStyle, StyleCapabilities>;
+/** 设置键名（嵌套 schema 字段名；client 桥写回与 host schema 共用） */
+export declare const STYLE_KEY = "style";
+export declare const ALIGN_KEY = "align";
+export declare const BAND_KEY = "bandHeight";
+export declare const SCROLL_KEY = "scrollBehavior";
+export declare const SHOW_COUNT_KEY = "showCount";
+export declare const SHOW_SEARCH_KEY = "showSearch";
+export declare const SHOW_QUICK_KEY = "showQuickSettings";
+export declare const CARD_COUNT_KEY = "cardCount";
+/** 本插件设置命名空间（拼写而非导入：client bundle 不得依赖宿主包） */
+export declare const MGS_NS = "mega-chat-nav";

package/lib/types/core/focus.d.ts

@@ -0,0 +1,24 @@
+/** 选中点两侧保持放大的圆点数 */
+export declare const FOCUS_RADIUS = 2;
+/** 悬停放大倍数：仅选中圆点放大（邻居不再有放大特效） */
+export declare const FOCUS_SCALES: readonly [1.5];
+/** 距离 → 聚焦档（窗口内 0..RADIUS，窗口外 null；供级联卡窗口使用） */
+export declare function focusTier(distance: number): number | null;
+/** 距离 → 放大倍数：仅选中点（distance 0）放大，邻居/窗口外均为 1 */
+export declare function focusScale(distance: number): number;
+/** 级联卡呈现参数：选中卡为焦点（最宽/全文本/品牌条），邻居卡窄而截断 */
+export interface CardMetrics {
+    widthPx: number;
+    fontSize: number;
+    maxLines: number;
+}
+export declare function focusCardMetrics(distance: number): CardMetrics | null;
+/** 基础圆点直径与间距（与轨样式一致，翻页步进按整行计） */
+export declare const DOT_SIZE = 8;
+export declare const DOT_GAP = 6;
+/** 一次翻页揭示的整行数 */
+export declare const DOT_PAGE_ROWS = 5;
+/** 一次翻页的滚动步长（px） */
+export declare function pageStep(dotSize?: number, gap?: number, rows?: number): number;
+/** 将目标滚动位置钳制到有效区间 */
+export declare function clampScrollTop(target: number, maxScroll: number): number;

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

@@ -0,0 +1,39 @@
+/** 跳转循环所需的会话快照面 */
+export interface JumpSnapshot {
+    openState: string;
+    hasMore: boolean;
+    loadingOlder: boolean;
+    rows: Iterable<{
+        key: string;
+        anchorSeq: number;
+        visibility?: string;
+    }>;
+}
+/** 外部端口：会话读写、DOM 行查找、滚动与时钟（由浏览器半装配） */
+export interface JumpPorts {
+    snapshot: () => JumpSnapshot | undefined;
+    loadOlder: () => Promise<void>;
+    isViewActive: () => boolean;
+    findRow: (key: string) => HTMLElement | null;
+    scrollIntoView: (row: HTMLElement, mode: 'smooth' | 'instant') => void;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    report?: (code: JumpFailureCode, fallback?: boolean) => void;
+}
+export type JumpFailureCode = 'VIEW_INACTIVE' | 'TARGET_HIDDEN' | 'NOT_FOUND' | 'TIMEOUT';
+export interface JumpResult {
+    ok: boolean;
+    code?: JumpFailureCode;
+    fallback?: boolean;
+}
+export interface JumpOptions {
+    totalTimeoutMs?: number;
+    maxPages?: number;
+    rowWaitMs?: number;
+    pollMs?: number;
+}
+/**
+ * 跳转到 key 对应行：先扩窗（预算内）直至目标入窗，再等待行渲染并滚动；
+ * 目标隐藏/缺失时回退最近可渲染行。各失败点返回结构化结果码。
+ */
+export declare function jumpToTarget(ports: JumpPorts, key: string, options?: JumpOptions, mode?: 'smooth' | 'instant'): Promise<JumpResult>;

package/lib/types/core/logic/active-dot.d.ts

@@ -0,0 +1,15 @@
+/** 一行圆点锚点行的位置测量（滚动口坐标系） */
+export interface DotRowMeasure {
+    /** 圆点 key（回合跳转锚点） */
+    key: string;
+    /** 行顶到滚动口顶的像素差 */
+    top: number;
+}
+/** 阅读线固定为视口顶部（0） */
+export declare const READING_LINE_TOP = 0;
+/**
+ * 选取标记圆点：阅读线之上（含）的最后一行为当前回合；
+ * 阅读线在所有行之上（开场问答之前）时取第一行兜底；无渲染行返回 null。
+ * 实现：自尾向首扫描第一个越过阅读线的行（等价于「最后一个满足项」）。
+ */
+export declare function nearestReadDot(rows: readonly DotRowMeasure[], readingLine: number): string | null;

package/lib/types/core/logic/focus.d.ts

@@ -0,0 +1,22 @@
+/** 选中点两侧计入聚焦窗口的圆点数 */
+export declare const FOCUS_RADIUS = 2;
+/** 悬停放大倍数：仅选中圆点放大（邻居不再有放大特效） */
+export declare const FOCUS_SCALES: readonly [1.5];
+/** 级联卡呈现参数：选中卡为焦点（最宽/全文本/品牌条），邻居卡窄而截断 */
+export interface CardMetrics {
+    widthPx: number;
+    fontSize: number;
+    maxLines: number;
+}
+/** 距离 → 聚焦度量（档位 + 放大倍数 + 卡尺寸）；聚焦窗口外返回 null */
+export declare function focusMetrics(distance: number): {
+    tier: number;
+    scale: number;
+    card: CardMetrics;
+} | null;
+/** 距离 → 聚焦档（窗口内 0..RADIUS，窗口外 null；供级联卡窗口使用） */
+export declare function focusTier(distance: number): number | null;
+/** 距离 → 放大倍数：仅选中点（distance 0）放大，邻居/窗口外均为 1 */
+export declare function focusScale(distance: number): number;
+/** 距离 → 卡呈现参数；聚焦窗口外返回 null */
+export declare function focusCardMetrics(distance: number): CardMetrics | null;

package/lib/types/core/logic/jump.d.ts

@@ -0,0 +1,39 @@
+/** 跳转循环所需的会话快照面 */
+export interface JumpSnapshot {
+    openState: string;
+    hasMore: boolean;
+    loadingOlder: boolean;
+    rows: Iterable<{
+        key: string;
+        anchorSeq: number;
+        visibility?: string;
+    }>;
+}
+/** 外部端口：会话读写、DOM 行查找、滚动与时钟（由浏览器半装配） */
+export interface JumpPorts {
+    snapshot: () => JumpSnapshot | undefined;
+    loadOlder: () => Promise<void>;
+    isViewActive: () => boolean;
+    findRow: (key: string) => HTMLElement | null;
+    scrollIntoView: (row: HTMLElement, mode: 'smooth' | 'instant') => void;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    report?: (code: JumpFailureCode, fallback?: boolean) => void;
+}
+export type JumpFailureCode = 'VIEW_INACTIVE' | 'TARGET_HIDDEN' | 'NOT_FOUND' | 'TIMEOUT';
+export interface JumpResult {
+    ok: boolean;
+    code?: JumpFailureCode;
+    fallback?: boolean;
+}
+export interface JumpOptions {
+    totalTimeoutMs?: number;
+    maxPages?: number;
+    rowWaitMs?: number;
+    pollMs?: number;
+}
+/**
+ * 跳转到 key 对应行：状态机驱动（定位 → 等就绪 → 扩窗 → 等渲染 → 回退）；
+ * 各失败点返回结构化结果码。
+ */
+export declare function jumpToTarget(ports: JumpPorts, key: string, options?: JumpOptions, mode?: 'smooth' | 'instant'): Promise<JumpResult>;

package/lib/types/core/logic/nodes.d.ts

@@ -0,0 +1,48 @@
+/** 一条导航展示/跳转单元 */
+export interface NavNode {
+    /** 会话行锚点 key（匹配 [data-chat-anchor-key]） */
+    key: string;
+    /** 单调锚点序号（排序与窗口最小检测） */
+    anchorSeq: number;
+    /** 消息事件 seq */
+    seq: number;
+    /** Unix 毫秒时间戳 */
+    time: number;
+    /** 完整提问文本（悬停卡用，不截断） */
+    text: string;
+}
+/** 会话节点最小结构面（结构型，非 SDK 绑定） */
+export interface ChatRowLike {
+    key: string;
+    anchorSeq: number;
+    visibility?: string;
+    kind?: string;
+    data?: unknown;
+}
+/** 会话行节点的导航提取 / 查找工具 */
+export declare class NavNodes {
+    /** 计入「提问」的节点 kind */
+    static readonly KINDS: readonly ["user", "steering"];
+    /** 判定节点 kind 是否计入提问 */
+    static isKind(kind: string | undefined): boolean;
+    /** 消息首文本块；缺省空串 */
+    static messageText(content: readonly {
+        type?: string;
+        text?: string;
+    }[] | undefined): string;
+    /** 从节点窗口提取提问列表，按 anchorSeq 升序（筛选 → 投影 → 排序 管线） */
+    static extract(rows: Iterable<ChatRowLike>): NavNode[];
+    /** 节点是否实际渲染（隐藏行不可作滚动目标） */
+    static isRenderable(node: ChatRowLike): boolean;
+    /** 窗口内精确查找 key 对应行 */
+    static find(rows: Iterable<ChatRowLike>, key: string): ChatRowLike | null;
+    /** 缺失/隐藏 key 时回退到最近可渲染行（取最新 anchorSeq，贴近用户点击意图） */
+    static nearest(rows: Iterable<{
+        key: string;
+        anchorSeq: number;
+        visibility?: string;
+    }>, excludeKey: string | undefined): {
+        key: string;
+        anchorSeq: number;
+    } | null;
+}

package/lib/types/core/model/nav-item.d.ts

@@ -0,0 +1,12 @@
+export interface NavItem {
+    /** 归属回合号（turn/start 之后的第一个提问） */
+    turn: number;
+    /** 消息稳定 id（跳转锚点推导源） */
+    id: string;
+    /** 事件 seq（排序与锚点序号） */
+    seq: number;
+    /** Unix 毫秒时间戳 */
+    time: number;
+    /** 首文本块（悬停/级联卡正文） */
+    text: string;
+}

package/lib/types/core/model/turns.d.ts

@@ -0,0 +1,30 @@
+import type { NavItem } from './nav-item.ts';
+import type { NavNode } from '../logic/nodes.ts';
+/**
+ * 消息稳定聊天 key 格式：镜像 conversationContextKey(kind, id) 公式，
+ * 即 '<kind长度>:<kind><id>'；kind 段固定为用户消息的 'input-message'
+ * ——必须与 dsh 聊天行的 [data-chat-anchor-key] 对齐（外部契约，勿改）。
+ */
+/** 一个圆点：某回合的提问组（或一条未入投影的活提问） */
+export interface NavDot {
+    /** 归属回合；活提问（投影未收）为 null */
+    readonly turn: number | null;
+    /** 跳转锚点：组内首问的聊天 key */
+    readonly key: string;
+    /** 首问锚点序号 */
+    readonly anchorSeq: number;
+    /** 首问时间 */
+    readonly time: number;
+    /** 组内全部提问文本（按序） */
+    readonly texts: readonly string[];
+    /** 组内全部聊天 key（活合并去重用） */
+    readonly memberKeys: readonly string[];
+}
+/** 投影提问列表 → 每回合一个圆点；同回合连续条目合并（锚点取首问） */
+export declare function groupByTurn(entries: readonly NavItem[]): NavDot[];
+/**
+ * 合并活窗口提问（投影推送帧到达前的短暂窗口）：
+ * 已并入圆点的 key 丢弃（投影副本优先）；其余作为单问圆点（turn:null）
+ * 按 anchorSeq 有序插入。无新增时返回原数组引用（调用方可 bail out）。
+ */
+export declare function mergeLiveEntries(dots: readonly NavDot[], live: readonly NavNode[]): NavDot[];

package/lib/types/core/nav-item.d.ts

@@ -0,0 +1,12 @@
+export interface NavItem {
+    /** 归属回合（turn/start 之后的第一个提问） */
+    turn: number;
+    /** 消息稳定 id（跳转锚点推导源） */
+    id: string;
+    /** 事件 seq（排序与跳转锚点） */
+    seq: number;
+    /** Unix 毫秒时间戳 */
+    time: number;
+    /** 首文本块（悬停/卡片正文） */
+    text: string;
+}

package/lib/types/core/nodes.d.ts

@@ -0,0 +1,43 @@
+/** 一条导航展示/跳转单元 */
+export interface NavNode {
+    /** 会话行锚点 key（匹配 [data-chat-anchor-key]） */
+    key: string;
+    /** 单调锚点序号（排序与窗口最小检测） */
+    anchorSeq: number;
+    /** 消息事件 seq */
+    seq: number;
+    /** Unix 毫秒时间戳 */
+    time: number;
+    /** 完整提问文本（悬停卡用，不截断） */
+    text: string;
+}
+/** 会话节点最小结构面（结构型，非 SDK 绑定） */
+export interface ChatRowLike {
+    key: string;
+    anchorSeq: number;
+    visibility?: string;
+    kind?: string;
+    data?: unknown;
+}
+/** 计入「提问」的节点 kind */
+export declare const NAV_KINDS: readonly ["user", "steering"];
+/** 消息首文本块；缺省空串 */
+export declare function messageText(content: readonly {
+    type?: string;
+    text?: string;
+}[] | undefined): string;
+/** 从节点窗口提取提问列表，按 anchorSeq 升序 */
+export declare function extractNavNodes(nodes: Iterable<ChatRowLike>): NavNode[];
+/** 节点是否实际渲染（隐藏行不可作滚动目标） */
+export declare function isRenderable(node: ChatRowLike): boolean;
+/** 窗口内精确查找 key 对应行 */
+export declare function findNavRow(nodes: Iterable<ChatRowLike>, key: string): ChatRowLike | null;
+/** 缺失/隐藏 key 时回退到最近可渲染行（取最新 anchorSeq，贴近用户点击意图） */
+export declare function nearestRenderable(nodes: Iterable<{
+    key: string;
+    anchorSeq: number;
+    visibility?: string;
+}>, excludeKey: string | undefined): {
+    key: string;
+    anchorSeq: number;
+} | null;

package/lib/types/core/page-size.d.ts

@@ -0,0 +1,8 @@
+/** 可选翻页数量 */
+export declare const PageSizeOptions: readonly [3, 5, 8, 10];
+/** 一次翻页揭示的圆点数 */
+export type PageSize = typeof PageSizeOptions[number];
+/** 默认翻页数量 */
+export declare const DEFAULT_PAGE: PageSize;
+/** 设置字段：翻页数量 */
+export declare const PAGE_SIZE_KEY = "pageSize";

package/lib/types/core/question-entry.d.ts

@@ -0,0 +1,12 @@
+export interface NavEntry {
+    /** 归属回合（turn/start 之后的第一个提问） */
+    turn: number;
+    /** 消息稳定 id（跳转锚点推导源） */
+    id: string;
+    /** 事件 seq（排序与跳转锚点） */
+    seq: number;
+    /** Unix 毫秒时间戳 */
+    time: number;
+    /** 首文本块（悬停/卡片正文） */
+    text: string;
+}

package/lib/types/core/time.d.ts

@@ -0,0 +1,4 @@
+/** 是否同一自然日 */
+export declare function sameDay(time: number, now: number): boolean;
+/** 智能时间：同日 HH:MM / 同年 MM-DD HH:MM / 其他 YYYY-MM-DD HH:MM；非法时间返回空串 */
+export declare function formatNavTime(time: number, now: number): string;

package/lib/types/core/turn-dots.d.ts

@@ -0,0 +1,29 @@
+import type { NavItem } from './nav-item.ts';
+import type { NavNode } from './nodes.ts';
+/** 用户提问节点的定义 kind（锚点 key 推导用） */
+export declare const MESSAGE_KIND = "input-message";
+/** 消息稳定聊天 key：镜像 conversationContextKey(kind, id) 公式 */
+export declare function navKeyOf(id: unknown): string;
+/** 一个圆点：某回合的提问组（或一条未入投影的活提问） */
+export interface NavDot {
+    /** 归属回合；活提问（投影未收）为 null */
+    readonly turn: number | null;
+    /** 跳转锚点：组内首问的聊天 key */
+    readonly key: string;
+    /** 首问锚点序号 */
+    readonly anchorSeq: number;
+    /** 首问时间 */
+    readonly time: number;
+    /** 组内全部提问文本（按序） */
+    readonly texts: readonly string[];
+    /** 组内全部聊天 key（活合并去重用） */
+    readonly memberKeys: readonly string[];
+}
+/** 投影提问列表 → 每回合一个圆点；同回合连续条目合并（锚点取首问） */
+export declare function groupByTurn(entries: readonly NavItem[]): NavDot[];
+/**
+ * 合并活窗口提问（投影推送帧到达前的短暂窗口）：
+ * 已并入圆点的 key 丢弃（投影副本优先）；其余作为单问圆点（turn:null）
+ * 按 anchorSeq 有序插入。无新增时返回原数组引用（调用方可 bail out）。
+ */
+export declare function mergeLiveEntries(dots: readonly NavDot[], live: readonly NavNode[]): NavDot[];

package/lib/types/core/utils/measure.d.ts

@@ -0,0 +1,12 @@
+/** 圆点直径（px） */
+export declare const DOT_SIZE = 8;
+/** 相邻圆点间距（px） */
+export declare const DOT_GAP = 6;
+/** 一次翻页揭示的整行数 */
+export declare const DOT_PAGE_ROWS = 5;
+/** 单行占位（直径 + 间距） */
+export declare function rowPitch(dot?: number, gap?: number): number;
+/** 一次翻页的滚动步长（px）：行数 × 单行占位 */
+export declare function pageStep(dot?: number, gap?: number, rows?: number): number;
+/** 将滚动位置钳制到有效区间 [0, maxScroll]；非法上限按 0 处理 */
+export declare function clampScrollTop(target: number, maxScroll: number): number;

package/lib/types/core/utils/time.d.ts

@@ -0,0 +1,4 @@
+/** 是否为同一自然日 */
+export declare function sameDay(time: number, now: number): boolean;
+/** 智能时间：同日 HH:MM / 同年 MM-DD HH:MM / 跨年 YYYY-MM-DD HH:MM；非法输入返回空串 */
+export declare function formatNavTime(time: number, now: number): string;

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis plugin name. */
+export declare const name = "dsh-mega-chat-nav";
+export declare function apply(ctx: Context): void;

package/lib/types/nav-item.d.ts

@@ -0,0 +1,12 @@
+export interface NavItem {
+    /** 归属回合号（turn/start 之后的第一个提问） */
+    turn: number;
+    /** 消息稳定 id（跳转锚点推导源） */
+    id: string;
+    /** 事件 seq（排序与锚点序号） */
+    seq: number;
+    /** Unix 毫秒时间戳 */
+    time: number;
+    /** 首文本块（悬停/级联卡正文） */
+    text: string;
+}

package/lib/types/nodes.d.ts

@@ -0,0 +1,48 @@
+/** 一条导航展示/跳转单元 */
+export interface NavNode {
+    /** 会话行锚点 key（匹配 [data-chat-anchor-key]） */
+    key: string;
+    /** 单调锚点序号（排序与窗口最小检测） */
+    anchorSeq: number;
+    /** 消息事件 seq */
+    seq: number;
+    /** Unix 毫秒时间戳 */
+    time: number;
+    /** 完整提问文本（悬停卡用，不截断） */
+    text: string;
+}
+/** 会话节点最小结构面（结构型，非 SDK 绑定） */
+export interface ChatRowLike {
+    key: string;
+    anchorSeq: number;
+    visibility?: string;
+    kind?: string;
+    data?: unknown;
+}
+/** 会话行节点的导航提取 / 查找工具 */
+export declare class NavNodes {
+    /** 计入「提问」的节点 kind */
+    static readonly KINDS: readonly ["user", "steering"];
+    /** 判定节点 kind 是否计入提问 */
+    static isKind(kind: string | undefined): boolean;
+    /** 消息首文本块；缺省空串 */
+    static messageText(content: readonly {
+        type?: string;
+        text?: string;
+    }[] | undefined): string;
+    /** 从节点窗口提取提问列表，按 anchorSeq 升序（筛选 → 投影 → 排序 管线） */
+    static extract(rows: Iterable<ChatRowLike>): NavNode[];
+    /** 节点是否实际渲染（隐藏行不可作滚动目标） */
+    static isRenderable(node: ChatRowLike): boolean;
+    /** 窗口内精确查找 key 对应行 */
+    static find(rows: Iterable<ChatRowLike>, key: string): ChatRowLike | null;
+    /** 缺失/隐藏 key 时回退到最近可渲染行（取最新 anchorSeq，贴近用户点击意图） */
+    static nearest(rows: Iterable<{
+        key: string;
+        anchorSeq: number;
+        visibility?: string;
+    }>, excludeKey: string | undefined): {
+        key: string;
+        anchorSeq: number;
+    } | null;
+}

package/lib/types/projection.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The `msgNavMessages` session projection unit: a pure fold of the session
+ * event log into the ordered list of user questions, each tagged with the
+ * turn that claimed it. Registered on `ctx.sessionProjections` by the host
+ * half (src/index.ts); persistence, replay, and client delivery are the
+ * projection seam's (session-projection-cache checkpoints the state, the
+ * api-proxy carriers seed + push the wire view).
+ *
+ * Fold rules mirror the chat messageDefinition classification: an
+ * append-origin `user/message` with a human (`user`) source is a question;
+ * replacement copies (compaction checkpoints) and injected context are not.
+ * Turns come from `turn/start` boundaries, so retry/goal-continuation turns
+ * without a question simply produce no entry — dots may skip turn numbers,
+ * staying exactly aligned with the Trajectory view's turn labels.
+ *
+ * @module dsh-mega-chat-nav/projection
+ */
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection';
+/** 注册本投影单元到框架的合并扩展表（接口声明于 /types 出口，须在声明处合并） */
+declare module '@deepseek-ai/dsh-session-projection/types' {
+    interface SessionProjectionStateMap {
+        msgNavMessages: QuestionIndexState;
+    }
+    interface SessionProjectionMap {
+        msgNavMessages: NavItem[];
+    }
+}
+/** 投影条目：一条 user/message 提问的轻量索引（正文零驻留） */
+export interface NavItem {
+    /** 归属回合号（turn/start 之后的第一个提问） */
+    turn: number;
+    /** 消息稳定 id（跳转锚点推导源） */
+    id: string;
+    /** 事件 seq（排序与锚点序号） */
+    seq: number;
+    /** Unix 毫秒时间戳 */
+    time: number;
+    /** 首文本块（悬停/级联卡正文） */
+    text: string;
+    /** 该轮性能指标（view 附加；缺数据时省略） */
+    metrics?: {
+        durationMs: number;
+        firstTokenMs: number;
+        tokensPerSec: number;
+    };
+}
+/** Fold state: the last opened turn plus every question recorded so far. */
+/** 一轮的性能指标（由 turn/start、assistant/chunk、assistant/message 折叠） */
+interface TurnMetric {
+    /** 轮开始时间（turn/start） */
+    startedAt: number;
+    /** 首个内容增量块时间（assistant/chunk 首 text/reasoning delta）；未流式时为 null */
+    firstTokenAt: number | null;
+    /** 轮结束时间（assistant/message）；未完成时为 null */
+    finishedAt: number | null;
+    /** 累计输出 token（assistant/message 的 usage.outputTokens 求和） */
+    outputTokens: number;
+}
+interface QuestionIndexState {
+    /** Turn of the last `turn/start` (0 before any; turns are 1-based). */
+    turn: number;
+    /** Every recorded question, in event order. */
+    questions: NavItem[];
+    /** 每轮性能指标（turn 号 → 指标） */
+    metrics: Record<number, TurnMetric>;
+}
+/** The `msgNavMessages` unit registered on `ctx.sessionProjections`. */
+export declare const msgNavProjectionDefinition: Omit<ProjectionDefinition<'msgNavMessages', QuestionIndexState>, 'wire'> & {
+    wire: NonNullable<ProjectionDefinition<'msgNavMessages', QuestionIndexState>['wire']>;
+};
+export {};