dsh-mega-chat-nav 0.1.1

package/lib/search.js

@@ -0,0 +1,285 @@
+function eventText(ev) {
+    if (ev.type === 'tool/call') {
+        // 工具调用：name + 参数 JSON 前段（可被搜索命中）
+        const d = ev.data;
+        const name = typeof d?.name === 'string' ? d.name : '';
+        const args = typeof d?.arguments === 'string' ? d.arguments : '';
+        return name.length === 0 && args.length === 0 ? '' : name + ' ' + args.slice(0, 200);
+    }
+    if (ev.type !== 'user/message' && ev.type !== 'assistant/message')
+        return '';
+    const msg = ev.type === 'user/message' ? ev.data : ev.data?.message;
+    const content = msg?.content;
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        const parts = [];
+        for (const b of content) {
+            if (b && typeof b === 'object' && b.type === 'text') {
+                const txt = b.text;
+                if (typeof txt === 'string')
+                    parts.push(txt);
+            }
+        }
+        return parts.join(' ');
+    }
+    return '';
+}
+function roleOf(ev) {
+    if (ev.type === 'user/message') {
+        const kind = ev.data?.source?.kind;
+        return kind === 'steering' ? 'steering' : 'user';
+    }
+    if (ev.type === 'tool/call')
+        return 'tool';
+    return 'assistant';
+}
+function keyOf(ev) {
+    const id = ev.type === 'user/message' ? ev.data?.id : ev.data?.message?.id;
+    return typeof id === 'string' && id.length > 0 ? id : 'seq:' + (ev.seq ?? 0);
+}
+function snippetAround(text, q, radius = 40) {
+    const idx = text.toLowerCase().indexOf(q.toLowerCase());
+    if (idx < 0)
+        return null;
+    const start = Math.max(0, idx - radius);
+    const end = Math.min(text.length, idx + q.length + radius);
+    const pre = start > 0 ? '…' : '';
+    const post = end < text.length ? '…' : '';
+    return { snippet: pre + text.slice(start, end) + post, hitStart: idx - start + (start > 0 ? 1 : 0), hitLen: q.length };
+}
+function makeLru(capacity = 32) {
+    const map = new Map();
+    return {
+        get(k) {
+            const v = map.get(k);
+            if (v !== undefined) {
+                map.delete(k);
+                map.set(k, v);
+            }
+            return v;
+        },
+        set(k, v) {
+            map.delete(k);
+            map.set(k, v);
+            if (map.size > capacity) {
+                const first = map.keys().next().value;
+                if (first !== undefined)
+                    map.delete(first);
+            }
+        },
+    };
+}
+const searchCache = makeLru();
+/** 访问可选服务：未注入的 cordis 服务在属性读取时抛错，捕获后按缺失处理 */
+function tryGet(getter) {
+    try {
+        return getter();
+    }
+    catch {
+        return undefined;
+    }
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const r = req;
+        const chunks = [];
+        r.on?.('data', (chunk) => {
+            if (typeof chunk === 'string')
+                chunks.push(Buffer.from(chunk));
+            else if (chunk instanceof Uint8Array)
+                chunks.push(Buffer.from(chunk));
+        });
+        r.on?.('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        r.on?.('error', reject);
+    });
+}
+/**
+ * 读取会话事件：合并「已加载窗口」（live）与「更早历史」（持久化日志 →
+ * sessionQuery 兜底），按 seq 去重（历史中与 live 重复的丢弃），整体按 seq 排序。
+ */
+function readEventSources(sessionId, sessions, persistence, query) {
+    const live = (sessions?.get(sessionId)?.events ?? []);
+    const liveSeqs = new Set();
+    for (const ev of live) {
+        if (typeof ev?.seq === 'number')
+            liveSeqs.add(ev.seq);
+    }
+    let historic = [];
+    try {
+        const raw = persistence?.readRaw(sessionId);
+        if (Array.isArray(raw))
+            historic = raw;
+    }
+    catch { /* 下一级 */ }
+    if (historic.length === 0) {
+        const q = query?.readSession(sessionId);
+        if (q && Array.isArray(q.events))
+            historic = q.events;
+    }
+    const out = live.map((ev) => ({ ev, historic: false }));
+    for (const ev of historic) {
+        if (typeof ev?.seq === 'number' && liveSeqs.has(ev.seq))
+            continue;
+        out.push({ ev, historic: true });
+    }
+    return out.sort((a, b) => (a.ev.seq ?? 0) - (b.ev.seq ?? 0));
+}
+/**
+ * 命中锚点：直接按消息 kind 拼出完整 DOM 锚点 key（对齐 conversationContextKey 公式）：
+ *   - 用户/steering 消息 → '13:input-message' + id
+ *   - assistant 消息 → '14:assistant-step' + turn + ':' + step（assistant-step 定义见
+ *     dsh-client-ui-conversation；id 为 turn:step 组合）
+ * AI 命中的方向判定 seq 取所属轮用户消息序号（AI 行紧跟其用户提问，位置近似）。
+ */
+/** 事件 → 搜索内容范围 */
+function scopeOf(ev) {
+    if (ev.type === 'tool/call')
+        return 'tool';
+    if (ev.type === 'assistant/message')
+        return 'assistant';
+    return 'user';
+}
+export function searchEvents(events, q, limit, scopes = ['user', 'assistant', 'tool']) {
+    const hits = [];
+    const needle = q.toLowerCase();
+    let turn = 0;
+    let lastUserSeq = 0;
+    for (const { ev, historic } of events) {
+        if (ev.type === 'turn/start') {
+            const t = ev.data?.turn;
+            if (typeof t === 'number')
+                turn = t;
+            continue;
+        }
+        if (ev.type === 'user/message')
+            lastUserSeq = ev.seq ?? 0;
+        const text = eventText(ev);
+        if (!text || !text.toLowerCase().includes(needle))
+            continue;
+        if (!scopes.includes(scopeOf(ev)))
+            continue;
+        const role = roleOf(ev);
+        const isAssistant = role === 'assistant';
+        const isTool = ev.type === 'tool/call';
+        const anchorKey = isTool
+            ? '9:tool-call' + String(ev.data?.callId ?? '')
+            : isAssistant
+                ? '14:assistant-step' + turn + ':' + ev.data?.step
+                : '13:input-message' + keyOf(ev);
+        const anchorSeq = isAssistant || isTool ? lastUserSeq : ev.seq ?? 0;
+        const snip = snippetAround(text, q);
+        hits.push({
+            key: anchorKey,
+            seq: anchorSeq,
+            time: ev.time ?? 0,
+            role,
+            turn,
+            historic,
+            snippet: snip ? snip.snippet : text.slice(0, 60),
+            hitStart: snip ? snip.hitStart : -1,
+            hitLen: snip ? snip.hitLen : 0,
+        });
+        if (limit > 0 && hits.length >= limit)
+            break;
+    }
+    return { hits, truncated: limit > 0 && hits.length >= limit };
+}
+export function registerSearchRoute(ctx) {
+    ctx.inject(['webServer', 'sessions'], (scoped) => {
+        const webServer = scoped.webServer;
+        const sessions = scoped.sessions;
+        if (!webServer || !sessions)
+            return;
+        ctx.inject(['settings'], (settingsCtx) => {
+            const settingsService = settingsCtx.settings;
+            if (!settingsService)
+                return;
+            ctx.effect(() => {
+                const dispose = webServer.register({
+                    kind: 'prefix',
+                    path: '/mega-chat-nav',
+                    handler: async (req, res) => {
+                        const httpRes = res;
+                        const httpReq = req;
+                        const write = (code, body) => {
+                            httpRes.statusCode = code;
+                            httpRes.setHeader?.('Content-Type', 'application/json; charset=utf-8');
+                            httpRes.end(JSON.stringify(body));
+                        };
+                        try {
+                            const url = new URL(httpReq.url ?? '/', 'http://localhost');
+                            // 嵌套配置写回：scope.set 仅支持 section 内标量，嵌套 section 必须走 host 桥
+                            if (url.pathname === '/mega-chat-nav/settings') {
+                                if ((httpReq.method ?? 'GET') !== 'POST') {
+                                    write(405, { ok: false, error: 'POST required' });
+                                    return;
+                                }
+                                const raw = await readBody(req);
+                                let patch;
+                                let revision;
+                                try {
+                                    const body = JSON.parse(raw);
+                                    patch = body.patch;
+                                    revision = body.revision;
+                                }
+                                catch {
+                                    write(400, { ok: false, error: 'bad json' });
+                                    return;
+                                }
+                                if (typeof patch !== 'object' || patch === null || Array.isArray(patch)) {
+                                    write(400, { ok: false, error: 'patch must be an object' });
+                                    return;
+                                }
+                                try {
+                                    await settingsService.update('mega-chat-nav', patch, typeof revision === 'number' ? revision : undefined);
+                                }
+                                catch (e) {
+                                    write(409, { ok: false, error: 'settings conflict: ' + String(e) });
+                                    return;
+                                }
+                                write(200, { ok: true });
+                                return;
+                            }
+                            if (url.pathname !== '/mega-chat-nav/search') {
+                                write(404, { ok: false, error: 'not found' });
+                                return;
+                            }
+                            const sessionId = url.searchParams.get('session') ?? '';
+                            const q = (url.searchParams.get('q') ?? '').trim();
+                            // limit<=0（含未传）→ 不限条数，返回全部命中
+                            const rawLimit = url.searchParams.get('limit');
+                            const limit = rawLimit === null || rawLimit === ''
+                                ? 0
+                                : Math.max(0, Math.min(Number(rawLimit) || 0, 500));
+                            if (!sessionId || q.length < 1) {
+                                write(400, { ok: false, error: 'session & q required' });
+                                return;
+                            }
+                            // 搜索内容范围（多选）；缺省全选；user 必选强制保留
+                            const rawScopes = (url.searchParams.get('scopes') ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+                            const scopes = rawScopes.length > 0
+                                ? [...new Set(['user', ...rawScopes])].filter((s) => s === 'user' || s === 'assistant' || s === 'tool')
+                                : ['user', 'assistant', 'tool'];
+                            const cacheKey = sessionId + '|' + q + '|' + limit;
+                            const cached = searchCache.get(cacheKey);
+                            if (cached) {
+                                write(200, { ok: true, ...cached });
+                                return;
+                            }
+                            const persistence = tryGet(() => scoped.sessionPersistence);
+                            const query = tryGet(() => scoped.sessionQuery);
+                            const result = searchEvents(readEventSources(sessionId, sessions, persistence, query), q, limit, scopes);
+                            searchCache.set(cacheKey, result);
+                            write(200, { ok: true, ...result });
+                        }
+                        catch (e) {
+                            write(500, { ok: false, error: String(e) });
+                        }
+                    },
+                });
+                return dispose;
+            });
+        });
+    });
+}

package/lib/settings.js

@@ -0,0 +1,89 @@
+/**
+ * Host-side durable settings for the mega-chat-nav plugin.
+ * 配置选项为本插件自有定义：host 半持有此处；client 半在
+ * src/client/settings.ts 持有同值副本（client bundle 不得依赖宿主包）。
+ *
+ * @module dsh-mega-chat-nav/settings
+ */
+import z from '@deepseek-ai/schemastery';
+/** 风格选项：简约 / codex（时间线刻度）/ deepseek（用户消息面板，常态短横折叠） */
+export const STYLE_OPTIONS = ['minimal', 'codex', 'deepseek'];
+/** 停靠侧选项 */
+export const ALIGN_OPTIONS = ['left', 'right'];
+/** 节点栏条带高度档位 */
+export const BAND_OPTIONS = ['compact', 'standard', 'tall'];
+/** 跳转动画方式 */
+export const SCROLL_OPTIONS = ['smooth', 'instant'];
+/** 显示策略：常显 / 悬停浮现 / 隐藏 */
+export const SHOW_OPTIONS = ['show', 'peek', 'hide'];
+/** 翻页标记默认显示模式（按风格独立）：minimal 常显（历史行为）/ codex 隐藏 */
+export const DEFAULT_PAGING = {
+    minimal: 'show',
+    codex: 'hide',
+    deepseek: 'peek',
+};
+/** 搜索内容范围（多选；用户必选） */
+export const SEARCH_SCOPE_OPTIONS = ['user', 'assistant', 'tool'];
+export const DEFAULT_SEARCH_SCOPES = ['user', 'assistant', 'tool'];
+/** 悬停卡片数量 */
+export const CARD_OPTIONS = [1, 3, 5];
+/** 悬浮卡默认数量（按风格独立）：minimal 3 张 / codex 1 张 / deepseek 1 张（无悬浮卡能力，占位） */
+export const DEFAULT_CARD_COUNT = {
+    minimal: 3,
+    codex: 1,
+    deepseek: 1,
+};
+/** 悬浮卡内容块（多选） */
+export const CARD_ITEM_OPTIONS = ['turn', 'duration', 'favorite'];
+export const DEFAULT_CARD_ITEMS = ['turn', 'duration', 'favorite'];
+/** 刻度色调：柔和（低对比）/ 深邃（高对比、清晰） */
+export const MARK_TONE_OPTIONS = ['soft', 'deep'];
+export const DEFAULT_MARK_TONE = 'deep';
+export const DEFAULT_STYLE = 'minimal';
+export const DEFAULT_ALIGN = 'left';
+export const DEFAULT_BAND = 'standard';
+export const DEFAULT_SCROLL = 'smooth';
+export const DEFAULT_SHOW = 'show';
+// 显示模式兼容旧布尔（true → show / false → hide）：旧 user 段里的布尔值
+// 不能导致 register 的 schema 校验失败，否则 namespace 注册失败、设置无法持久化
+const ShowModeSchema = z.union([z.boolean(), ...SHOW_OPTIONS]).default(DEFAULT_SHOW);
+const GeneralSchema = z.object({
+    style: z.union([...STYLE_OPTIONS]).default(DEFAULT_STYLE),
+    align: z.union([...ALIGN_OPTIONS]).default(DEFAULT_ALIGN),
+    scrollBehavior: z.union([...SCROLL_OPTIONS]).default(DEFAULT_SCROLL),
+    showCount: ShowModeSchema,
+    showSearch: ShowModeSchema,
+    showQuickSettings: ShowModeSchema,
+    showFavorites: ShowModeSchema,
+    /* 旧版 general.showPaging 残留兼容（0.9.x 曾置于此处）；新主源已迁移 styles.<style> */
+    showPaging: ShowModeSchema,
+    searchScopes: z.array(z.union([...SEARCH_SCOPE_OPTIONS])).default([...DEFAULT_SEARCH_SCOPES]),
+    railOffset: z.natural().max(32).default(8),
+});
+/** 风格公共字段（两风格默认一致的配置） */
+const StyleFields = {
+    bandHeight: z.union([...BAND_OPTIONS]).default(DEFAULT_BAND),
+    cardItems: z.array(z.union([...CARD_ITEM_OPTIONS])).default([...DEFAULT_CARD_ITEMS]),
+    markTone: z.union([...MARK_TONE_OPTIONS]).default(DEFAULT_MARK_TONE),
+};
+/** 每风格独立默认字段：悬浮卡数与翻页标记（minimal 常显 / codex 隐藏 / deepseek 浮现） */
+const StyleDefaults = {
+    minimal: { cardCount: DEFAULT_CARD_COUNT.minimal, showPaging: DEFAULT_PAGING.minimal },
+    codex: { cardCount: DEFAULT_CARD_COUNT.codex, showPaging: DEFAULT_PAGING.codex },
+    deepseek: { cardCount: DEFAULT_CARD_COUNT.deepseek, showPaging: DEFAULT_PAGING.deepseek },
+};
+const styleSchemaFields = (style) => ({
+    cardCount: z.union([...CARD_OPTIONS]).default(StyleDefaults[style].cardCount),
+    showPaging: z.union([...SHOW_OPTIONS]).default(StyleDefaults[style].showPaging),
+});
+/** 持久化设置 schema；也是浏览器 scope 校验的 wire 信封 */
+export const NavSettingsSchema = z.object({
+    general: GeneralSchema,
+    styles: z.object({
+        minimal: z.object({ ...StyleFields, ...styleSchemaFields('minimal') }),
+        codex: z.object({ ...StyleFields, ...styleSchemaFields('codex') }),
+        deepseek: z.object({ ...StyleFields, ...styleSchemaFields('deepseek') }),
+    }),
+});
+/** 本插件设置命名空间 */
+export const megaChatNavSettingsNamespace = 'mega-chat-nav';

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

@@ -0,0 +1,18 @@
+import { type ReactNode } from 'react';
+import type { NavConfig } from '../schema.ts';
+interface ScopeLike {
+    getSnapshot(): {
+        value?: NavConfig;
+    };
+    subscribe(fn: () => void): () => void;
+}
+interface OverlayProps {
+    scope?: ScopeLike;
+    renderSlot?: (name: string) => ReactNode;
+    SessionProvider?: (props: {
+        children?: ReactNode;
+    }) => ReactNode;
+}
+export declare function useScope(scope?: ScopeLike): NavConfig | undefined;
+export declare function NavOverlay(props: OverlayProps): ReactNode;
+export {};

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

@@ -0,0 +1,7 @@
+import { type ReactNode } from 'react';
+interface RailProps {
+    useProjection?: (key: string) => unknown;
+    t?: (key: string, vars?: Record<string, string | number>) => string;
+}
+export declare function NavRail(props: RailProps): ReactNode;
+export {};

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

@@ -0,0 +1,16 @@
+/**
+ * The plugin's settings page inside the shell's Plugins section
+ * (`settings.plugins.tab`): two segmented controls — which edge of the
+ * conversation column the dot rail anchors to, and how many hidden dots one
+ * ▲/▼ paging-button click reveals. The choices are written to the
+ * `mega-chat-nav` settings namespace (registered by the host half); the strip
+ * re-anchors and re-steps live when the snapshot changes.
+ *
+ * @module dsh-mega-chat-nav/client/settings-tab
+ */
+import type { QuestionNavInjected } from './QuestionNavStrip.tsx';
+interface ComponentProps extends QuestionNavInjected {
+    t(key: string, vars?: Record<string, string | number>): string;
+}
+export declare function QuestionNavSettingsTab(props: ComponentProps): React.JSX.Element | null;
+export {};

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

@@ -0,0 +1,48 @@
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client';
+import type { QuestionNode } from '../core/nodes.ts';
+import type { AlignPreference } from '../core/align.ts';
+import type { PageSize } from '../core/page-size.ts';
+/** Minimal observable shape of a session projection face. */
+export interface ObservableFace {
+    /** Current projection value (unknown — validated structurally at read). */
+    getSnapshot: () => unknown;
+    /** Subscribe to value changes; returns an unsubscribe. */
+    subscribe: (listener: () => void) => () => void;
+}
+/** Values the registrant inject face supplies (wired in src/client/index.ts). */
+export interface QuestionNavInjected {
+    /** Extract the user questions of a session's currently loaded window. */
+    readQuestions: (sessionId: SessionId) => QuestionNode[];
+    /** Subscribe to the session list; returns an unsubscribe. */
+    subscribeList: (cb: () => void) => () => void;
+    /** Subscribe to a session's content; returns an unsubscribe. */
+    subscribeContent: (sessionId: SessionId, cb: () => void) => () => void;
+    /** The session's `msgNavMessages` projection face, when the host unit is registered. */
+    questionProjection: (sessionId: SessionId) => ObservableFace | undefined;
+    /** Jump the chat to a question row (pages the window on demand). */
+    jump: (sessionId: SessionId, key: string) => void;
+    /** Current rail anchor edge (defaults to 'left' before the settings section is ready). */
+    align: () => AlignPreference;
+    /** Observe plugin-settings changes (align, page size); returns an unsubscribe. */
+    subscribeSettings: (cb: () => void) => () => void;
+    /** Persist a new anchor edge. */
+    setAlign: (align: AlignPreference) => void;
+    /** Current ▲/▼ page size (defaults to DEFAULT_PAGE_SIZE before the settings section is ready). */
+    pageSize: () => PageSize;
+    /** Persist a new page size. */
+    setPageSize: (pageSize: PageSize) => void;
+}
+/** 宽松 props 面（原 PropsRuntime/PropsLocale 来自虚拟包，此处本地化） */
+interface ComponentProps extends QuestionNavInjected {
+    useSessions?: <S>(selector: (s: SessionListLike) => S) => S;
+    t(key: string, vars?: Record<string, string | number>): string;
+}
+/** 会话列表最小面（供 useSessions selector） */
+interface SessionListLike {
+    current?: unknown;
+    byId?: Record<string, {
+        blank?: boolean;
+    }>;
+}
+export declare function QuestionNavStrip(props: ComponentProps): React.JSX.Element | null;
+export {};

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

@@ -0,0 +1,14 @@
+import { type ReactNode } from 'react';
+import type { NavConfig } from '../../schema.ts';
+import type { ScopeLike } from '../config.ts';
+export interface ConfigPanelProps {
+    scope: ScopeLike | undefined;
+    t(key: string, vars?: Record<string, string | number>): string;
+    onClose(): void;
+}
+export declare function ConfigPanel(props: ConfigPanelProps): ReactNode;
+export declare function Switch({ checked, onChange }: {
+    checked: boolean;
+    onChange(v: boolean): void;
+}): ReactNode;
+export type { NavConfig };

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

@@ -0,0 +1,15 @@
+import { type ReactNode } from 'react';
+import type { MsgNavItem } from '../../projection.ts';
+import type { NavConfig } from '../../schema.ts';
+import type { RailPos } from './NavOverlay.tsx';
+export interface DotRailProps {
+    items: readonly MsgNavItem[];
+    align: 'left' | 'right';
+    cfg: NavConfig;
+    t(key: string, vars?: Record<string, string | number>): string;
+    activeKey: string | null;
+    failed: boolean;
+    onJump(key: string): void;
+    pos: RailPos | null;
+}
+export declare function DotRail(props: DotRailProps): ReactNode;

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

@@ -0,0 +1,30 @@
+import { type ReactNode } from 'react';
+import type { ScopeLike } from '../config.ts';
+import { type SessionLike } from '../engines/useJump.ts';
+export interface SessionsLike {
+    binding?(sessionId: string): {
+        session?: SessionLike & {
+            projections?: ProjectionsLike;
+        };
+    } | undefined;
+}
+interface ProjectionsLike {
+    faceOf?(key: string): {
+        getSnapshot(): unknown;
+        subscribe(fn: () => void): () => void;
+    };
+}
+export interface NavOverlayProps {
+    scope?: ScopeLike;
+    sessions?: SessionsLike;
+    useSessions?: <S>(selector: (s: unknown) => S) => S;
+    t?: (key: string, vars?: Record<string, string | number>) => string;
+}
+export interface RailPos {
+    top: number;
+    height: number;
+    left?: number;
+    right?: number;
+}
+export declare function NavOverlay(props: NavOverlayProps): ReactNode;
+export {};

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

@@ -0,0 +1,16 @@
+import { type ReactNode } from 'react';
+import type { ScopeLike } from '../config.ts';
+import { type SessionLike } from '../engines/useJump.ts';
+export interface SessionsLike {
+    binding?(sessionId: string): {
+        session?: SessionLike;
+    } | undefined;
+}
+export interface NavRailProps {
+    scope?: ScopeLike;
+    useProjection?: (key: string) => unknown;
+    sessionId?: string;
+    sessions?: SessionsLike;
+    t?: (key: string, vars?: Record<string, string | number>) => string;
+}
+export declare function NavRail(props: NavRailProps): ReactNode;

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

@@ -0,0 +1,8 @@
+import { type ReactNode } from 'react';
+import type { NavInjected, SessionSelector, Translate } from './shared/types.ts';
+export interface RailDispatchProps {
+    injected: NavInjected | undefined;
+    useSessions?: SessionSelector;
+    t: Translate;
+}
+export declare function RailDispatch(props: RailDispatchProps): ReactNode;

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

@@ -0,0 +1,27 @@
+import { type ReactNode } from 'react';
+import type { MsgNavItem } from '../../projection.ts';
+import type { NavConfig } from '../../schema.ts';
+import type { ScopeLike } from '../config.ts';
+import { type SessionLike } from '../engines/useJump.ts';
+export interface SessionsLike {
+    binding?(sessionId: string): {
+        session?: SessionLike;
+    } | undefined;
+}
+export interface RailHostProps {
+    scope?: ScopeLike;
+    useProjection?: (key: string) => unknown;
+    sessionId?: string;
+    sessions?: SessionsLike;
+    t?: (key: string, vars?: Record<string, string | number>) => string;
+}
+export declare function RailHost(props: RailHostProps): ReactNode;
+export interface StyleCommon {
+    items: readonly MsgNavItem[];
+    align: 'left' | 'right';
+    collapsed: boolean;
+    setCollapsed(v: boolean): void;
+    t(key: string, vars?: Record<string, string | number>): string;
+    general: NavConfig['general'];
+    jump(key: string): void;
+}

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

@@ -0,0 +1,9 @@
+import { type ReactNode } from 'react';
+export interface SearchBoxProps {
+    sessionId?: string;
+    debounceMs: number;
+    t(key: string, vars?: Record<string, string | number>): string;
+    onJump(key: string): void;
+    onClose(): void;
+}
+export declare function SearchBox(props: SearchBoxProps): ReactNode;

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

@@ -0,0 +1,9 @@
+import { type ReactNode } from 'react';
+import type { ScopeLike } from '../config.ts';
+export interface SettingsPageProps {
+    scope?: ScopeLike;
+    t(key: string, vars?: Record<string, string | number>): string;
+    /** mega-settings 已收纳时由宿主传入提示（自足页内检测） */
+    hosted?: boolean;
+}
+export declare function SettingsPage(props: SettingsPageProps): ReactNode;

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

@@ -0,0 +1,13 @@
+import { type ReactNode } from 'react';
+import type { ScopeLike } from '../config.ts';
+interface SlotsLike {
+    entries?(key: string): readonly unknown[];
+    subscribe?(key: string, fn: () => void): () => void;
+}
+export interface StandaloneSettingsProps {
+    scope?: ScopeLike;
+    slots?: SlotsLike;
+    t?(key: string, vars?: Record<string, string | number>): string;
+}
+export declare function StandaloneSettings(props: StandaloneSettingsProps): ReactNode;
+export {};

package/lib/types/client/components/codex/CodexRail.d.ts

@@ -0,0 +1,3 @@
+import type { ReactNode } from 'react';
+import type { RailProps } from '../shared/types.ts';
+export declare function CodexRail(props: RailProps): ReactNode;

package/lib/types/client/components/deepseek/DeepseekRail.d.ts

@@ -0,0 +1,3 @@
+import type { ReactNode } from 'react';
+import type { RailProps } from '../shared/types.ts';
+export declare function DeepseekRail(props: RailProps): ReactNode;

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

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+import type { NavInjected, SessionListLike, Translate } from '../shared/types.ts';
+export interface MinimalRailProps {
+    injected: NavInjected | undefined;
+    useSessions?: <S>(selector: (s: SessionListLike) => S) => S;
+    t: Translate;
+}
+export declare function MinimalRail(props: MinimalRailProps): ReactNode;

package/lib/types/client/components/minimal/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;