dsh-mega-chat-nav 0.1.1

package/lib/types/client/components/minimal/dot.d.ts

@@ -0,0 +1,14 @@
+export interface DotProps {
+    /** 缩放（聚焦模型输出；跳转中 1.6） */
+    scale: number;
+    className: string;
+    label: string;
+    index: number;
+    keyName: string;
+    focused: boolean;
+    revealed?: {
+        dir: 1 | -1;
+        order: number;
+    };
+}
+export declare const Dot: import("react").NamedExoticComponent<DotProps>;

package/lib/types/client/components/minimal/hint.d.ts

@@ -0,0 +1,11 @@
+import { type ReactNode } from 'react';
+import type { RailAlign } from '../../settings.ts';
+export interface HintProps {
+    text: string;
+    align: RailAlign;
+    /** bottom：显示在对话输入框上方（加载较早记录提示），水平对齐跟随对话区域左右边缘 */
+    position?: 'rail' | 'bottom';
+    /** 加载点动画（仅加载中提示） */
+    loading?: boolean;
+}
+export declare function Hint({ text, align, position, loading }: HintProps): ReactNode;

package/lib/types/client/components/minimal/paging.d.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react';
+export interface PagingButtonProps {
+    dir: 1 | -1;
+    visible: boolean;
+    label: string;
+    onEnter: () => void;
+    onLeave: () => void;
+    onClick: () => void;
+}
+export declare function PagingButton(props: PagingButtonProps): ReactNode;

package/lib/types/client/components/minimal/quick-settings.d.ts

@@ -0,0 +1,8 @@
+import { type ReactNode } from 'react';
+import type { NavInjected, Translate } from '../shared/types.ts';
+export interface QuickSettingsProps {
+    injected: NavInjected;
+    t: Translate;
+    onClose: () => void;
+}
+export declare function QuickSettings(props: QuickSettingsProps): ReactNode;

package/lib/types/client/components/minimal/search.d.ts

@@ -0,0 +1,27 @@
+import { type ReactNode } from 'react';
+import type { Translate } from '../shared/types.ts';
+export interface SearchHit {
+    key: string;
+    seq: number;
+    time: number;
+    role: string;
+    /** 命中消息所在轮次（host 由 turn/start 计数；未定位为 0） */
+    turn: number;
+    /** 命中是否来自更早历史 */
+    historic: boolean;
+    snippet: string;
+    hitStart: number;
+    hitLen: number;
+}
+export interface SearchBoxProps {
+    sessionId?: string;
+    t: Translate;
+    /** 搜索内容范围（多选；host 按此过滤） */
+    scopes: readonly string[];
+    /** 点击命中：key = 完整 DOM 锚点 key（host 按消息 kind 拼好）；seq = 方向判定序号 */
+    onJump: (key: string, seq: number) => void;
+    onClose: () => void;
+    /** 查询为空时显示的内容（如全部轮次列表）；缺省显示空区域 */
+    emptyContent?: ReactNode;
+}
+export declare function SearchBox(props: SearchBoxProps): ReactNode;

package/lib/types/client/components/minimal/useRail.d.ts

@@ -0,0 +1,90 @@
+import { type RefObject } from 'react';
+import type { FocusState, NavInjected, RailMarker, SessionListLike, Translate } from '../shared/types.ts';
+import { type BandHeight, type CardCount, type CardItem, type NavStyle, type RailAlign, type ScrollMode, type SearchScope, type ShowMode } from '../../settings.ts';
+/** 圆点数据：会话可见性 + 标记装配（订阅集中管理，共用一条刷新管线） */
+export declare function useMarkerData(injected: NavInjected | undefined, useSessions?: <S>(selector: (s: SessionListLike) => S) => S): {
+    sessionId: string | undefined;
+    visible: boolean;
+    markers: RailMarker[];
+};
+/** 布局钉位：期望几何 → 比对 → 写入（rAF 循环，连续 3 帧稳定停车；resize/尺寸变化唤醒） */
+export declare function usePinning(panelRef: RefObject<HTMLDivElement>, visible: boolean, align: RailAlign, offset?: number, sessionId?: string): void;
+/** 阅读间谍：滚动/尺寸变化按 rAF 采样行位置，标记当前所在回合。
+ *  返回 [currentKey, forceKey]——forceKey 用于点击跳转瞬间强制激活目标，
+ *  滚动稳定后由采样判据接管。 */
+export declare function useReadingSpy(visible: boolean, markers: readonly RailMarker[]): [string | null, (key: string) => void];
+/** 条带翻页：▲/▼ 步进（固定 5 行/页）+ 溢出检测 + 入场错峰动画 */
+export declare function useBandPaging(listRef: RefObject<HTMLDivElement>, markers: readonly RailMarker[]): {
+    scrollable: boolean;
+    revealed: ReadonlyMap<string, {
+        dir: 1 | -1;
+        order: number;
+    }> | null;
+    syncScroll: () => void;
+    pageBy: (dir: 1 | -1) => void;
+    canPageUp: boolean;
+    canPageDown: boolean;
+};
+export interface CardMetrics {
+    widthPx: number;
+    fontSize: number;
+    maxLines: number;
+}
+/** 距离 → 卡片呈现参数；聚焦窗口外返回 null */
+export declare function cardMetrics(distance: number): CardMetrics | null;
+/** 距离 → 聚焦档（窗口内 0..2，窗口外 null；圆点缩放层级用） */
+export declare function markerTier(distance: number): number | null;
+/** 距离 → 放大倍数：仅选中点放大，邻居/窗口外均为 1 */
+export declare function markerScale(distance: number): number;
+/**
+ * 卡片预览：悬停标记弹出级联卡（minimal 能力，enabled=false 时整组失效——
+ * 其他风格可无卡片）。
+ */
+export declare function useCardPreview(markers: readonly RailMarker[], align: RailAlign, radius: number, enabled: boolean): {
+    focus: FocusState | null;
+    openCards: (marker: RailMarker, target: HTMLElement) => void;
+    cancelClear: () => void;
+    scheduleClear: () => void;
+};
+/** 跳转失败提示：监听 mega-chat-nav:jump-failed 事件，1.8s 后自动消退 */
+export declare function useFailureNotice(t: Translate): string | null;
+/** 监听跳转编排的扩窗加载状态，显示「正在加载较早记录以定位…（第 N 页）」 */
+export declare function useLoadingNotice(t: Translate): string | null;
+/** 设置订阅：全部配置项跟随（align/bandHeight/cardCount/显示模式/动画方式） */
+export declare function useNavSettings(injected: NavInjected | undefined): {
+    style: NavStyle;
+    align: RailAlign;
+    bandHeight: BandHeight;
+    cardCount: CardCount;
+    cardItems: CardItem[];
+    scrollBehavior: ScrollMode;
+    showCount: ShowMode;
+    showSearch: ShowMode;
+    showQuickSettings: ShowMode;
+    showFavorites: ShowMode;
+    searchScopes: SearchScope[];
+    railOffset: number;
+};
+/** 相对时间：同日 HH:MM / 同年 MM-DD HH:MM / 跨年 YYYY-MM-DD HH:MM；非法输入返回空串 */
+export declare function clockText(time: number, now: number): string;
+/** 收藏状态：localStorage 持久化 + 切换动作（跨刷新保留） */
+export declare function useFavorites(sessionId: string | undefined): {
+    favorites: Set<string>;
+    toggle: (key: string) => void;
+};
+/** 毫秒 → 人类可读时长（1分21秒 / 10秒） */
+export declare function durationText(ms: number): string;
+/** 完整指标行：本轮用时 1分21秒 · 首 token 10秒 · 188 tok/s */
+export declare function metricsLine(metrics: {
+    durationMs: number;
+    firstTokenMs: number;
+    tokensPerSec: number;
+}): string;
+/** 手机模式：页面宽度小于 breakpoint（默认 1024px），resize 实时跟随 */
+export declare function useMobileMode(breakpoint?: number): boolean;
+/**
+ * 手机模式：向对话滚动容器 [data-conversation-scroll] 头部插入零高 wrapper
+ * （width:100%; height:0; sticky top:0; overflow:visible），按钮 absolute 相对
+ * wrapper 定位——sticky 粘在滚动视口顶部，按钮不随内容滚走、不占布局空间。
+ */
+export declare function useMobileSearchButton(onClick: () => void, enabled: boolean, align: RailAlign, label: string): void;

package/lib/types/client/components/rail/cards.d.ts

@@ -0,0 +1,19 @@
+import type { ReactNode } from 'react';
+import type { RailAlign, CardItem } from '../../settings.ts';
+import type { FocusState, RailMarker } from '../shared/types.ts';
+export interface CardsProps {
+    focus: FocusState;
+    align: RailAlign;
+    /** 显示哪些内容块（多选配置） */
+    cardItems: readonly CardItem[];
+    /** 收藏集合 */
+    favorites: ReadonlySet<string>;
+    /** 切换收藏（按该轮首问锚点 key） */
+    onToggleFavorite: (key: string) => void;
+    onJump: (dot: RailMarker) => void;
+    /** 卡片 hover 保活（取消 rail 的清焦定时） */
+    onEnter: () => void;
+    /** 离开卡片后重新排程清焦 */
+    onLeave: () => void;
+}
+export declare function Cards(props: CardsProps): ReactNode;

package/lib/types/client/components/rail/hint.d.ts

@@ -0,0 +1,11 @@
+import { type ReactNode } from 'react';
+import type { RailAlign } from '../../settings.ts';
+export interface HintProps {
+    text: string;
+    align: RailAlign;
+    /** bottom：显示在对话输入框上方（加载较早记录提示），水平对齐跟随对话区域左右边缘 */
+    position?: 'rail' | 'bottom';
+    /** 加载点动画（仅加载中提示） */
+    loading?: boolean;
+}
+export declare function Hint({ text, align, position, loading }: HintProps): ReactNode;

package/lib/types/client/components/rail/paging.d.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react';
+export interface PagingButtonProps {
+    dir: 1 | -1;
+    visible: boolean;
+    label: string;
+    onEnter: () => void;
+    onLeave: () => void;
+    onClick: () => void;
+}
+export declare function PagingButton(props: PagingButtonProps): ReactNode;

package/lib/types/client/components/rail/quick-settings.d.ts

@@ -0,0 +1,8 @@
+import { type ReactNode } from 'react';
+import type { NavInjected, Translate } from '../shared/types.ts';
+export interface QuickSettingsProps {
+    injected: NavInjected;
+    t: Translate;
+    onClose: () => void;
+}
+export declare function QuickSettings(props: QuickSettingsProps): ReactNode;

package/lib/types/client/components/rail/search.d.ts

@@ -0,0 +1,34 @@
+import { type ReactNode } from 'react';
+import type { Translate } from '../shared/types.ts';
+export interface SearchHit {
+    key: string;
+    seq: number;
+    time: number;
+    role: string;
+    /** 命中消息所在轮次（host 由 turn/start 计数；未定位为 0） */
+    turn: number;
+    /** 命中是否来自更早历史 */
+    historic: boolean;
+    snippet: string;
+    hitStart: number;
+    hitLen: number;
+}
+export interface SearchBoxProps {
+    sessionId?: string;
+    t: Translate;
+    /** 搜索内容范围（多选；host 按此过滤） */
+    scopes: readonly string[];
+    /** 点击命中：key = 完整 DOM 锚点 key（host 按消息 kind 拼好）；seq = 方向判定序号 */
+    onJump: (key: string, seq: number) => void;
+    onClose: () => void;
+    /** 查询为空时显示的内容（如全部轮次列表）；缺省显示空区域 */
+    emptyContent?: ReactNode;
+}
+/** 检索：携带 AbortController 的 host 请求（scopes 过滤由 host 执行） */
+/**
+ * 检索 + 统一排序：host 按日志顺序返回，此处统一按轮次倒序（最新轮在上；
+ * 同轮按 seq 倒序——最新消息在前）。minimal/codex 浮层、deepseek 面板与移动抽屉共用，
+ * 保证三种风格与搜索抽屉的命中顺序一致。
+ */
+export declare function fetchHits(sessionId: string | undefined, query: string, scopes: readonly string[], signal: AbortSignal): Promise<SearchHit[]>;
+export declare function SearchBox(props: SearchBoxProps): ReactNode;

package/lib/types/client/components/rail/useRail.d.ts

@@ -0,0 +1,132 @@
+import { type RefObject } from 'react';
+import type { FocusState, NavInjected, RailMarker, SessionListLike, Translate } from '../shared/types.ts';
+import { type BandHeight, type CardCount, type CardItem, type MarkTone, type NavStyle, type RailAlign, type ScrollMode, type SearchScope, type ShowMode } from '../../settings.ts';
+/** 圆点数据：会话可见性 + 标记装配（订阅集中管理，共用一条刷新管线） */
+export declare function useMarkerData(injected: NavInjected | undefined, useSessions?: <S>(selector: (s: SessionListLike) => S) => S): {
+    sessionId: string | undefined;
+    visible: boolean;
+    markers: RailMarker[];
+};
+/** 布局钉位：期望几何 → 比对 → 写入（rAF 循环，连续 3 帧稳定停车；resize/尺寸变化唤醒） */
+/**
+ * 布局钉位：校准状态机（鲁棒 + 长会话低成本）。
+ *
+ * 会话/工作区切换时对话区可能整体重建、或复用同一容器异步填充——校准必须
+ * 覆盖这些路径，同时**行级消息增删绝不唤醒校准**（那会让长会话的 rAF 校准
+ * 循环停不下来，每帧 reflow 拖慢一切交互——与对话几何无关）。
+ *
+ * 状态机：
+ *  - running：切换/尺寸事件后启动，每帧 calibrate 一次；
+ *      changed → 重置稳定帧；stable → 连续 3 帧停车（parked）；
+ *      missing（对话区未出现/高度为 0）→ 不停车，继续等待重建完成。
+ *  - parked：静默。唤醒条件：
+ *      1) ResizeObserver（frame / 对话区根元素尺寸变化）
+ *      2) window resize
+ *      3) MutationObserver 发现对话区根元素被移除或替换（会话/工作区切换）
+ *      4) effect 依赖变化重启（sessionId / visible / align / offset）
+ *
+ * 行级变化（追加消息、装载历史、其他插件改 body 子树）只做一次 O(1) 的
+ * isConnected 检查，不唤醒校准。
+ */
+export declare function usePinning(panelRef: RefObject<HTMLDivElement>, visible: boolean, align: RailAlign, offset?: number, sessionId?: string): void;
+/** 阅读间谍：滚动/尺寸变化按 rAF 采样行位置，标记当前所在回合。
+ *  返回 [currentKey, forceKey]——forceKey 用于点击跳转瞬间强制激活目标，
+ *  滚动稳定后由采样判据接管。 */
+export declare function useReadingSpy(visible: boolean, markers: readonly RailMarker[]): [string | null, (key: string) => void];
+/** 行内节点几何：节点 8px + 行距 6px = 行高 14px（minimal 圆点与 codex 刻度槽一致；
+ *  与样式 .mgcn-dots gap 6px / 节点 8px、codex 槽高 14px 对齐） */
+export declare const NODE_SIZE = 8;
+export declare const ROW_GAP = 6;
+export declare const ROW_HEIGHT: number;
+export declare const ROWS_PER_PAGE = 5;
+/** 条带翻页：▲/▼ 步进（固定 5 行/页）+ 溢出检测 + 入场错峰动画 */
+export declare function useBandPaging(listRef: RefObject<HTMLDivElement>, markers: readonly RailMarker[]): {
+    scrollable: boolean;
+    revealed: ReadonlyMap<string, {
+        dir: 1 | -1;
+        order: number;
+    }> | null;
+    syncScroll: () => void;
+    pageBy: (dir: 1 | -1) => void;
+    canPageUp: boolean;
+    canPageDown: boolean;
+};
+/**
+ * 浮现态（minimal/codex 共用）：进入 rail 立即显示；移出后至少停留 1s 再隐藏。
+ * peekCls 供 show=peek 模式使用（open 态不隐藏）。
+ */
+export declare function usePeekState(): {
+    peekVisible: boolean;
+    showPeek: () => void;
+    hidePeek: () => void;
+    peekCls: (mode: string, open: boolean) => string;
+};
+/**
+ * 点击浮层之外（非 .mgcn-gear-wrap）→ 关闭 config/search 浮层（minimal/codex 共用）。
+ */
+export declare function useClosePopoversOnOutside(configOpen: boolean, searchOpen: boolean, close: () => void): void;
+export interface CardMetrics {
+    widthPx: number;
+    fontSize: number;
+    maxLines: number;
+}
+/** 距离 → 卡片呈现参数；聚焦窗口外返回 null */
+export declare function cardMetrics(distance: number): CardMetrics | null;
+/** 距离 → 聚焦档（窗口内 0..2，窗口外 null；圆点缩放层级用） */
+export declare function markerTier(distance: number): number | null;
+/** 距离 → 放大倍数：仅选中点放大，邻居/窗口外均为 1 */
+export declare function markerScale(distance: number): number;
+/**
+ * 卡片预览：悬停标记弹出级联卡（minimal 能力，enabled=false 时整组失效——
+ * 其他风格可无卡片）。
+ */
+export declare function useCardPreview(markers: readonly RailMarker[], align: RailAlign, radius: number, enabled: boolean): {
+    focus: FocusState | null;
+    openCards: (marker: RailMarker, target: HTMLElement) => void;
+    cancelClear: () => void;
+    scheduleClear: () => void;
+};
+/** 跳转失败提示：监听 mega-chat-nav:jump-failed 事件，1.8s 后自动消退 */
+export declare function useFailureNotice(t: Translate): string | null;
+/** 监听跳转编排的扩窗加载状态，显示「正在加载较早记录以定位…（第 N 页）」 */
+export declare function useLoadingNotice(t: Translate): string | null;
+/** 设置订阅：全部配置项跟随（align/bandHeight/cardCount/markTone/显示模式/动画方式） */
+export declare function useNavSettings(injected: NavInjected | undefined): {
+    style: NavStyle;
+    align: RailAlign;
+    bandHeight: BandHeight;
+    cardCount: CardCount;
+    cardItems: CardItem[];
+    markTone: MarkTone;
+    scrollBehavior: ScrollMode;
+    showCount: ShowMode;
+    showSearch: ShowMode;
+    showQuickSettings: ShowMode;
+    showFavorites: ShowMode;
+    showPaging: ShowMode;
+    searchScopes: SearchScope[];
+    railOffset: number;
+};
+/** 相对时间：同日 HH:MM / 同年 MM-DD HH:MM / 跨年 YYYY-MM-DD HH:MM；非法输入返回空串 */
+export declare function clockText(time: number, now: number): string;
+/** 收藏状态：localStorage 持久化 + 切换动作（跨刷新保留） */
+export declare function useFavorites(sessionId: string | undefined): {
+    favorites: Set<string>;
+    toggle: (key: string) => void;
+};
+/** 毫秒 → 人类可读时长（1分21秒 / 10秒） */
+export declare function durationText(ms: number): string;
+/** 完整指标行：本轮用时 1分21秒 · 首 token 10秒 · 188 tok/s */
+export declare function metricsLine(metrics: {
+    durationMs: number;
+    firstTokenMs: number;
+    tokensPerSec: number;
+}): string;
+/** 手机模式：页面宽度小于 breakpoint（默认 1024px），resize 实时跟随 */
+export declare function useMobileMode(breakpoint?: number): boolean;
+/**
+ * 手机模式：向对话滚动容器 [data-conversation-scroll] 头部插入零高 wrapper
+ * （width:100%; height:0; sticky top:0; overflow:visible），按钮 absolute 相对
+ * wrapper 定位——sticky 粘在滚动视口顶部，按钮不随内容滚走、不占布局空间。
+ */
+export declare function useMobileSearchButton(onClick: () => void, enabled: boolean, align: RailAlign, label: string): void;

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

@@ -0,0 +1,9 @@
+import { type ReactNode } from 'react';
+import type { NavInjected, Translate } from '../shared/types.ts';
+export interface SettingsPageProps {
+    injected: NavInjected;
+    t: Translate;
+    /** 已收纳至 mega-settings 时仅显示提示（自足入口让位） */
+    hosted?: boolean;
+}
+export declare function SettingsPage(props: SettingsPageProps): ReactNode;

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

@@ -0,0 +1,6 @@
+import type { NavInjected, Translate } from '../shared/types.ts';
+interface ComponentProps extends NavInjected {
+    t: Translate;
+}
+export declare function SettingsTab(props: ComponentProps): React.JSX.Element | null;
+export {};

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

@@ -0,0 +1,13 @@
+import { type ReactNode } from 'react';
+import type { NavInjected, Translate } from '../shared/types.ts';
+interface SlotsLike {
+    entries?(key: string): readonly unknown[];
+    subscribe?(key: string, fn: () => void): () => void;
+}
+export interface StandaloneSettingsProps {
+    injected: NavInjected;
+    slots?: SlotsLike;
+    t: Translate;
+}
+export declare function StandaloneSettings(props: StandaloneSettingsProps): ReactNode;
+export {};

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

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+import type { RailAlign } from '../../../core/config.ts';
+import type { FocusState } from '../shared/types.ts';
+import type { NavDot } from '../../../core/model/turns.ts';
+export interface CascadeProps {
+    focus: FocusState;
+    align: RailAlign;
+    onJump: (dot: NavDot) => void;
+    /** 级联卡 hover 保活（取消 rail 的清焦定时） */
+    onEnter: () => void;
+    /** 离开级联卡后重新排程清焦 */
+    onLeave: () => void;
+}
+export declare function Cascade(props: CascadeProps): ReactNode;

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

@@ -0,0 +1,8 @@
+import { type ReactNode } from 'react';
+import type { NavInjected, Translate } from '../shared/types.ts';
+export interface ConfigPanelProps {
+    injected: NavInjected;
+    t: Translate;
+    onClose: () => void;
+}
+export declare function ConfigPanel(props: ConfigPanelProps): ReactNode;

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

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+export interface DotProps {
+    /** 缩放（波纹模型 focusScale 输出；跳转中 1.6） */
+    scale: number;
+    className: string;
+    label: string;
+    index: number;
+    keyName: string;
+    focused: boolean;
+    revealed?: {
+        dir: 1 | -1;
+        order: number;
+    };
+    onEnter: (target: HTMLElement) => void;
+    onClick: () => void;
+}
+export declare function Dot(props: DotProps): ReactNode;

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

@@ -0,0 +1,6 @@
+import type { ReactNode } from 'react';
+import type { RailAlign } from '../../../core/config.ts';
+export declare function Hint({ text, align }: {
+    text: string;
+    align: RailAlign;
+}): ReactNode;

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

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react';
+export interface PagingButtonProps {
+    dir: 1 | -1;
+    visible: boolean;
+    label: string;
+    onEnter: () => void;
+    onLeave: () => void;
+    onClick: () => void;
+}
+export declare function PagingButton(props: PagingButtonProps): ReactNode;

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

@@ -0,0 +1,43 @@
+import { type ReactNode, type RefObject } from 'react';
+import type { NavDot } from '../../../core/model/turns.ts';
+import { useFocus } from './hooks.ts';
+import type { NavInjected, SessionListLike, Translate } from './types.ts';
+export interface RailShellProps {
+    injected: NavInjected | undefined;
+    useSessions?: <S>(selector: (s: SessionListLike) => S) => S;
+    t: Translate;
+    children: (state: RailShellState) => ReactNode;
+}
+export interface RailShellState {
+    injected: NavInjected;
+    sessionId: string | undefined;
+    dots: readonly NavDot[];
+    style: 'minimal';
+    align: 'left' | 'right';
+    bandHeight: 'compact' | 'standard' | 'tall';
+    scrollBehavior: 'smooth' | 'instant';
+    showCount: 'show' | 'peek' | 'hide';
+    showSearch: 'show' | 'peek' | 'hide';
+    showQuickSettings: 'show' | 'peek' | 'hide';
+    cardCount: 1 | 3 | 5;
+    currentKey: string | null;
+    hint: string | null;
+    scrollable: boolean;
+    canPageUp: boolean;
+    canPageDown: boolean;
+    revealed: ReadonlyMap<string, {
+        dir: 1 | -1;
+        order: number;
+    }> | null;
+    jumpingKey: string | null;
+    panelRef: RefObject<HTMLDivElement>;
+    listRef: RefObject<HTMLDivElement>;
+    focus: ReturnType<typeof useFocus>['focus'];
+    openFocus: (dot: NavDot, target: HTMLElement) => void;
+    cancelClearFocus: () => void;
+    scheduleClearFocus: () => void;
+    syncScroll: () => void;
+    pageBy: (dir: 1 | -1) => void;
+    onJump: (dot: NavDot) => void;
+}
+export declare function RailShell(props: RailShellProps): ReactNode;

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

@@ -0,0 +1,18 @@
+import { type ReactNode } from 'react';
+import type { Translate } from './types.ts';
+export interface SearchHit {
+    key: string;
+    seq: number;
+    time: number;
+    role: string;
+    snippet: string;
+    hitStart: number;
+    hitLen: number;
+}
+export interface SearchBoxProps {
+    sessionId?: string;
+    t: Translate;
+    onJump: (key: string) => void;
+    onClose: () => void;
+}
+export declare function SearchBox(props: SearchBoxProps): ReactNode;

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

@@ -0,0 +1,64 @@
+import { type RefObject } from 'react';
+import type { NavDot } from '../../../core/model/turns.ts';
+import { focusCardMetrics, focusScale, focusTier } from '../../../core/logic/focus.ts';
+import { formatNavTime } from '../../../core/utils/time.ts';
+import type { BandHeight, CardCount, NavStyle, RailAlign, ScrollMode, ShowMode } from '../../../core/config.ts';
+import type { FocusState, NavInjected, SessionListLike, Translate } from './types.ts';
+/** 会话可见性守卫：当前会话存在且非空白 */
+export declare function useVisibleSession(useSessions?: <S>(selector: (s: SessionListLike) => S) => S): {
+    sessionId: string | undefined;
+    visible: boolean;
+};
+/** 圆点列表装配：投影（全量）+ 活窗口合并；同内容复用引用（React bail out） */
+export declare function useSessionDots(injected: NavInjected | undefined, sessionId: string | undefined, visible: boolean): NavDot[];
+/** 会话滚动容器（钉位基准） */
+export declare function findConvRoot(): HTMLElement | null;
+/**
+ * 布局钉位：布局校正循环把 rail 钉到对话列（rAF 连续 3 帧稳定停车；
+ * ResizeObserver 观察 frame 与对话根；resize 唤醒）。直接写 panel.style。
+ */
+export declare function useRailLayout(panelRef: RefObject<HTMLDivElement>, visible: boolean, align: RailAlign): void;
+/**
+ * scroll-spy：标记阅读位置所在 turn（35% 视口线，core/active-dot 判据）。
+ * 仅已渲染行参与；rAF 合并 + 捕获式 scroll + ResizeObserver 跟踪 flow 重挂载。
+ */
+export declare function useScrollSpyDot(visible: boolean, dots: readonly NavDot[]): [string | null, (key: string) => void];
+/** 设置订阅：align / bandHeight / scrollBehavior / 显示开关 跟随 */
+export declare function useNavSettings(injected: NavInjected | undefined): {
+    style: NavStyle;
+    align: RailAlign;
+    bandHeight: BandHeight;
+    cardCount: CardCount;
+    scrollBehavior: ScrollMode;
+    showCount: ShowMode;
+    showSearch: ShowMode;
+    showQuickSettings: ShowMode;
+};
+/** 翻页模型：▲/▼ 步进 + 溢出检测 + 错峰弹出动画 */
+export declare function usePaging(listRef: RefObject<HTMLDivElement>, dots: readonly NavDot[], align: RailAlign): {
+    scrollable: boolean;
+    scrollPos: {
+        top: number;
+        max: number;
+    };
+    revealed: ReadonlyMap<string, {
+        dir: 1 | -1;
+        order: number;
+    }> | null;
+    syncScroll: () => void;
+    pageBy: (dir: 1 | -1) => void;
+    canPageUp: boolean;
+    canPageDown: boolean;
+};
+/** 悬停聚焦：选中点 + 邻居窗口 + 级联几何；240ms 清焦延迟（鼠标可移入级联卡） */
+export declare function useFocus(dots: readonly NavDot[], align: RailAlign, radius?: number): {
+    focus: FocusState | null;
+    openFocus: (dot: NavDot, target: HTMLElement) => void;
+    cancelClearFocus: () => void;
+    scheduleClearFocus: () => void;
+};
+/** 跳转失败提示：监听 mega-chat-nav:jump-failed 事件 */
+export declare function useJumpHint(t: Translate): {
+    hint: string | null;
+};
+export { formatNavTime, focusCardMetrics, focusScale, focusTier };