@openviking/react 0.1.2 → 0.1.4

package/dist/modules/console/types.d.ts

@@ -1,101 +1,80 @@
-import type { OvRequestOptions } from '../../client/index.js';
+import type { Locale } from '../../shared/locale.js';
 import type { HTMLAttributes, ReactNode } from 'react';
-/**
- * 面板模式。对话与命令共用同一面板，切换时各自保留状态。
- * Panel mode. Conversation and commands share one panel, each keeping its own
- * state when the mode switches.
- */
+import type { OvRequestOptions } from '../../client/types.js';
+import type { TuiCommandDefinition, TuiLabels, TuiRecord } from '../../components/tui/index.js';
+import type { VikingBotLabels, VikingBotProps } from '../../components/viking-bot/index.js';
 export type ConsoleMode = 'conversation' | 'command';
-/** 交互面板模块的插槽。Slots of the console module. */
 export interface ConsoleSlots {
-    /**
-     * 面板顶部工具栏。模式切换由模块渲染，这里放宿主专属入口。
-     * Panel toolbar. The module renders the mode switch; put host-specific
-     * entries here.
-     */
     toolbar?: ReactNode;
-    /**
-     * 对话模式下输入区上方的附加内容，例如当前资源上下文。
-     * Extra content above the composer in conversation mode, for example the
-     * current resource context.
-     */
     conversationContext?: ReactNode;
-    /**
-     * 命令模式下的命令帮助内容。省略时由模块按宿主声明的命令生成。
-     * Command help in command mode. When omitted, the module derives it from the
-     * commands the host declares.
-     */
     commandHelp?: ReactNode;
 }
-/** 交互面板模块的可替换文案。Replaceable copy of the console module. */
 export interface ConsoleLabels {
-    /**
-     * 占位说明。缺省为 `Placeholder. Functionality is not available yet.`。
-     * Placeholder description. Defaults to "Placeholder. Functionality is not
-     * available yet.".
-     */
+    /** Conversation welcome description. */
     description?: string;
-    /** 对话模式名称。Conversation mode label. */
     conversation?: string;
-    /** 命令模式名称。Command mode label. */
     command?: string;
-    /** 会话加载失败提示。Session load failure message. */
-    error?: string;
-    /** 重试按钮文案。Retry button label. */
-    retry?: string;
+    clear?: string;
+    history?: string;
+    emptyHistory?: string;
+    /** 终端空态标题，转交 Tui 的 `emptyTitle`。Terminal empty-state heading, mapped to Tui `emptyTitle`. */
+    commandTitle?: string;
+    /** 终端空态说明，转交 Tui 的 `emptyDescription`。Terminal empty-state description, mapped to Tui `emptyDescription`. */
+    commandDescription?: string;
+    /** 快捷命令引导文案，转交 Tui 的 `quickStart`。Quick-command label, mapped to Tui `quickStart`. */
+    quickStart?: string;
+    mode?: string;
+    tui?: TuiLabels;
+    vikingBot?: VikingBotLabels;
 }
-/**
- * 交互面板模块的属性。
- *
- * 模块自己通过 Hook 取数，props 里没有会话与命令记录：宿主给配置、受控模式、
- * 插槽与文案。打开资源通过回调交给宿主，与文件浏览模块的联动不依赖对方的私有
- * 状态。
- *
- * Props of the console module.
- *
- * The module loads its own data through a Hook, so no prop carries sessions or
- * command records: the host supplies configuration, the controlled mode, slots
- * and copy. Opening a resource goes back to the host through a callback, and
- * coordination with the file browser never reaches into the other module's
- * private state.
- */
-export interface ConsoleProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect' | 'children'> {
-    /**
-     * 受控的当前模式。传入时由宿主决定模式，模块只上报切换意图。
-     * The controlled mode. When given, the host owns the mode and the module only
-     * reports switch intent.
-     */
+/** Options shared by Console and useConsole. */
+export interface ConsoleOptions {
+    locale?: Locale;
     mode?: ConsoleMode;
-    /**
-     * 非受控时的初始模式，缺省为 `conversation`。
-     * Initial mode when uncontrolled; defaults to `conversation`.
-     */
+    /** Initial uncontrolled mode. Defaults to VikingBot ('conversation'). */
     defaultMode?: ConsoleMode;
-    /**
-     * 模式变化后触发。
-     * Called after the mode changes.
-     */
+    /** Change with the identity when using dynamic credential/identity functions. */
+    scopeKey?: string;
     onModeChange?: (mode: ConsoleMode) => void;
+    requestOptions?: OvRequestOptions;
+}
+export interface ConsoleProps extends ConsoleOptions, Omit<HTMLAttributes<HTMLDivElement>, 'onSelect' | 'children'> {
+    /** 内置中英文文案的语言。Language of the built-in interface copy. */
+    locale: Locale;
     /**
-     * 资源成功打开后触发，参数为资源 URI；失败时不触发。
-     * Called after a resource opens successfully, with its URI; not called on
-     * failure.
+     * 终端空态展示的快捷命令名称，按数组顺序取自命令目录，未命中的名称跳过，
+     * 重复名称只保留首次出现。
+     * 省略时使用默认集合；传空数组不展示内置空态。
+     * Quick command names shown in the terminal empty state, resolved from the
+     * command catalogue in array order with unknown names skipped. Omitted uses
+     * the default set; an empty array shows no built-in empty state.
      */
+    quickCommands?: readonly string[];
+    /** Host-owned conversation state/capabilities. Omit draft callbacks to use Console's local draft. */
+    conversation?: Partial<VikingBotProps>;
+    /** Reports navigation intent; the host opens the resource. */
     onOpenUri?: (uri: string) => void;
-    /**
-     * 插槽，见 {@link ConsoleSlots}。
-     * Slots, see {@link ConsoleSlots}.
-     */
     slots?: ConsoleSlots;
-    /**
-     * 可替换文案，缺省为英文。
-     * Replaceable copy; English by default.
-     */
     labels?: ConsoleLabels;
-    /**
-     * 请求配置覆盖，逐字段覆盖最近的 Provider。
-     * Request configuration override, applied field by field over the nearest
-     * Provider.
-     */
-    requestOptions?: OvRequestOptions;
+}
+/** Local state. Records and drafts are never persisted by the module. */
+export interface ConsoleState {
+    records: readonly TuiRecord[];
+    command: string;
+    conversationDraft: string;
+    isExecuting: boolean;
+    error?: unknown;
+    failedCommand?: string;
+}
+/** Data and operations available independently of Console's view. */
+export interface ConsoleResult extends ConsoleState {
+    mode: ConsoleMode;
+    commands: readonly TuiCommandDefinition[];
+    setMode: (mode: ConsoleMode) => void;
+    setCommand: (command: string) => void;
+    setConversationDraft: (draft: string) => void;
+    execute: (command?: string) => Promise<void>;
+    retry: () => Promise<void>;
+    cancel: () => void;
+    clear: () => void;
 }

package/dist/modules/console/use-console.d.ts

@@ -0,0 +1,3 @@
+import type { ConsoleOptions, ConsoleResult } from './types.js';
+/** Native command execution and draft orchestration, with or without Console. */
+export declare function useConsole({ mode: controlledMode, defaultMode, locale, scopeKey, onModeChange, requestOptions, }?: ConsoleOptions): ConsoleResult;

package/dist/modules/console.js

@@ -1 +1 @@
-export { Console } from "../a~0.js";
+export { Console, useConsole } from "../a~0.js";

package/dist/modules/file-browser/file-browser-detail-icons.d.ts

@@ -0,0 +1,10 @@
+/** 复制图标。Copy icon. */
+export declare function CopyIcon({ size }: {
+    size?: number;
+}): import("react").JSX.Element;
+/** 历史图标。History icon. */
+export declare function HistoryIcon(): import("react").JSX.Element;
+/** 看板图标。Dashboard icon. */
+export declare function DashboardIcon(): import("react").JSX.Element;
+/** 下载图标。Download icon. */
+export declare function DownloadIcon(): import("react").JSX.Element;

package/dist/modules/file-browser/file-browser-detail.d.ts

@@ -0,0 +1,34 @@
+import type { Locale } from '../../shared/locale.js';
+import { type FilePreviewTab } from '../../components/file-preview/index.js';
+import type { FileBrowserLabels } from './types.js';
+/**
+ * 详情区：页签行与正文。分段器（预览 / 源码）与右侧图标按钮由这里渲染，通过
+ * `slots.actions` 拿到预览的视图状态。
+ *
+ * 目录的摘要层级不在这里——它是 `directory` 页签内部的一层，由组件自己渲染。
+ *
+ * The detail pane: tab row and body. The segmented control (preview / source) and
+ * the icon buttons on the right are rendered here, reading the view state from the
+ * preview through `slots.actions`.
+ *
+ * A directory's summary levels are not here: they are a layer inside the
+ * `directory` tab, rendered by the component itself.
+ */
+export interface FileBrowserDetailProps {
+    tabs: readonly FilePreviewTab[];
+    activeKey: string | null;
+    locale: Locale;
+    labels?: FileBrowserLabels['preview'];
+    footer?: string;
+    /** 分段器与图标按钮的文案。Copy for the segmented control and icon buttons. */
+    viewLabels: {
+        preview: string;
+        source: string;
+        copyPath: string;
+        copyContent: string;
+        download: string;
+        viewSwitch: string;
+    };
+    onActiveKeyChange: (key: string) => void;
+}
+export declare function FileBrowserDetail({ tabs, activeKey, locale, labels, footer, viewLabels, onActiveKeyChange, }: FileBrowserDetailProps): import("react").JSX.Element;

package/dist/modules/file-browser/file-browser-empty.d.ts

@@ -0,0 +1,3 @@
+export declare function FileBrowserEmpty({ label }: {
+    label: string;
+}): import("react").JSX.Element;

package/dist/modules/file-browser/file-browser-failure.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 请求失败时的占位：一句结论、一行原始原因、一个重试按钮。
+ *
+ * 结论用可替换文案，原因原样显示服务端或传输层给的消息——把「403 Forbidden」
+ * 换成「加载失败」会让人分不清是权限、网络还是数据确实不存在，而这三者的处置
+ * 完全不同。
+ *
+ * The placeholder shown when a request fails: a conclusion, the raw reason and a
+ * retry button.
+ *
+ * The conclusion is replaceable copy while the reason is shown as the server or the
+ * transport reported it — replacing "403 Forbidden" with "Failed to load" hides
+ * whether this is a permission problem, a network problem or genuinely missing
+ * data, and the three call for different actions.
+ */
+export interface FileBrowserFailureProps {
+    message: string;
+    detail?: string;
+    retryLabel: string;
+    onRetry: () => void;
+}
+export declare function FileBrowserFailure({ message, detail, retryLabel, onRetry, }: FileBrowserFailureProps): import("react").JSX.Element;

package/dist/modules/file-browser/file-browser-icons.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 工具栏图标：搜索与刷新。
+ *
+ * 路径取自控制台所用的图标集（Arco `IconSearch` / `IconRefresh`），不是手绘近似。
+ * 两者都是 48 网格、`stroke-width: 4`、`fill: none`、`stroke: currentColor`，按
+ * 同一比例缩放到 16px，描边粗细因此与原图标一致。
+ *
+ * Toolbar icons: search and refresh.
+ *
+ * The paths come from the icon set the console uses (Arco `IconSearch` /
+ * `IconRefresh`) rather than a hand-drawn approximation. Both are 48-grid,
+ * `stroke-width: 4`, `fill: none`, `stroke: currentColor`, scaled to 16px at the
+ * same ratio so the stroke weight matches the original.
+ */
+/** 搜索图标。Search icon. */
+export declare function SearchIcon(): import("react").JSX.Element;
+/** 刷新图标。Refresh icon. */
+export declare function RefreshIcon(): import("react").JSX.Element;

package/dist/modules/file-browser/file-browser-labels.d.ts

@@ -0,0 +1,27 @@
+import { type Locale } from '../../shared/locale.js';
+import type { FilePreviewLabels } from '../../components/file-preview/index.js';
+import type { FileTreeLabels } from '../../components/file-tree/index.js';
+import type { FileBrowserLabels } from './types.js';
+/** 模块外壳自己渲染的文案，其余透传给树与预览。 */
+export type ShellLabels = Omit<FileBrowserLabels, 'tree' | 'preview' | 'entries'>;
+/**
+ * 模块外壳的内置文案。树与预览的默认值留在各自组件里，模块不重复一份。
+ * Built-in copy of the module shell. The tree and the preview keep their own
+ * defaults, so the module does not duplicate them.
+ */
+/** 解析后的外壳文案，外加透传给两个组件的文案。 */
+export interface ResolvedLabels extends Required<ShellLabels> {
+    tree: FileTreeLabels | undefined;
+    previewLabels: FileBrowserLabels['preview'];
+}
+/** 逐项合并默认文案；树与预览的文案原样透传，缺省由组件自己兜底。 */
+export declare function resolveLabels(labels: FileBrowserLabels | undefined, locale: Locale): ResolvedLabels;
+/** Shared shell labels followed by explicit preview overrides. */
+export declare function resolvePreviewLabels(text: ResolvedLabels): FilePreviewLabels;
+export declare const DEFAULT_LABELS: Required<ShellLabels>;
+/** Summary titles are derived from the module resource, including host overrides. */
+export declare function resolveSummaryLabels(locale: Locale, labels?: FileBrowserLabels): {
+    l0: string;
+    l1: string;
+    failure: string;
+};

package/dist/modules/file-browser/file-browser-layout.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 文件浏览的栏宽约束。
+ *
+ * 树默认 352px（与设计稿一致）；窄于 200px 就只剩图标可辨。上限除了 520px 的
+ * 绝对值，还要给右侧详情留出可读宽度——容器被宿主压窄时，树不能继续占着
+ * 520px 把详情挤没。
+ *
+ * Column-width limits of the file browser.
+ *
+ * The tree starts at 352px, matching the design; below 200px only icons stay
+ * legible. Above the 520px absolute cap the detail pane must still have room, so a
+ * container the host squeezed narrows the tree rather than letting it keep 520px
+ * and crush the detail.
+ */
+export declare const TREE_DEFAULT_WIDTH = 352;
+export declare const TREE_MIN_WIDTH = 200;
+/**
+ * 按容器宽度算出树的最大宽度。
+ *
+ * 容器宽度还没测出来（首帧）时用绝对值上限，避免把树压到最小。
+ *
+ * Resolves the tree's maximum width from the container width.
+ *
+ * Before the container is measured (the first frame) the absolute cap applies, so
+ * the tree is never squeezed to its minimum.
+ */
+export declare function resolveTreeMaxWidth(containerWidth: number): number;

package/dist/modules/file-browser/file-browser-toolbar.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 搜索行：搜索框与刷新按钮。内置的连接与导入入口位于上一行。
+ *
+ * The search row: the search box and refresh button. Built-in connection and import
+ * entries occupy the row above.
+ */
+export interface FileBrowserToolbarProps {
+    searchId: string;
+    query: string;
+    refreshing: boolean;
+    canRefresh: boolean;
+    placeholder: string;
+    refreshLabel: string;
+    onQueryChange: (value: string) => void;
+    onRefresh: () => void;
+}
+export declare function FileBrowserToolbar({ searchId, query, refreshing, canRefresh, placeholder, refreshLabel, onQueryChange, onRefresh, }: FileBrowserToolbarProps): import("react").JSX.Element;

package/dist/modules/file-browser/file-browser-tree-pane.d.ts

@@ -0,0 +1,32 @@
+import type { Locale } from '../../shared/locale.js';
+import type { FileBrowserEntriesProps } from '../../components/file-browser-entries/index.js';
+import type { FileTreeLabels } from '../../components/file-tree/index.js';
+import type { FileBrowserApi } from './types.js';
+/**
+ * 左栏：内置入口条、搜索行与目录树。
+ *
+ * 宽度由外层的可拖拽分隔条决定，因此这里只铺满自己的盒子，不设宽度；树内容
+ * 比栏宽时横向滚动，而不是把名称截成省略号。
+ *
+ * The left column: the built-in entries, the search row and the tree.
+ *
+ * The width comes from the draggable divider outside, so this only fills its own
+ * box. When the tree is wider than the column it scrolls sideways rather than
+ * truncating names into ellipses.
+ */
+export interface FileBrowserTreePaneProps {
+    entries: Pick<FileBrowserEntriesProps, 'agentConnect' | 'onImportResources' | 'renderImportResources' | 'labels'>;
+    locale: Locale;
+    searchId: string;
+    browser: FileBrowserApi;
+    treeLabels: FileTreeLabels | undefined;
+    searchPlaceholder: string;
+    refreshLabel: string;
+    searchLoading: string;
+    searchEmpty: string;
+    /** 搜索失败时的结论文案。Conclusion shown when the search request fails. */
+    searchErrorLabel: string;
+    /** 失败态里的重试按钮。Retry button of the failure state. */
+    retryLabel: string;
+}
+export declare function FileBrowserTreePane({ entries, locale, searchId, browser, treeLabels, searchPlaceholder, refreshLabel, searchLoading, searchEmpty, searchErrorLabel, retryLabel, }: FileBrowserTreePaneProps): import("react").JSX.Element;

package/dist/modules/file-browser/file-browser.d.ts

@@ -1,6 +1,15 @@
-import { FileBrowserToolbarButton } from './file-browser-toolbar-button.js';
 import type { FileBrowserProps } from './types.js';
-export { FileBrowserToolbarButton };
-export type { FileBrowserLabels, FileBrowserProps, FileBrowserToolbarButtonProps, } from './types.js';
-/** 占位组件：渲染一个带模块名的空容器，真实实现随模块 Hook 与组合视图迁入。 */
-export declare function FileBrowser({ className, style, labels }: FileBrowserProps): import("react").JSX.Element;
+export type { FileBrowserActions, FileBrowserApi, FileBrowserLabels, FileBrowserProps, } from './types.js';
+/**
+ * 文件浏览模块的组合视图，对齐控制台设计稿：左侧目录树（入口条、搜索行、树），
+ * 右侧详情区（面包屑、标题行、正文、底部元信息）。两栏之间有一条可拖拽的
+ * 分隔条，拖动改树宽；取数与联动都在 {@link useFileBrowser} 里，这里只组装
+ * 视图。
+ *
+ * The file browser module's composite view, matching the console design: the tree
+ * on the left (entry row, search row, tree) and the detail pane on the right
+ * (breadcrumb, header, body, footer). A draggable divider between them resizes the
+ * tree; loading and coordination live in {@link useFileBrowser}, and this only
+ * assembles the view.
+ */
+export declare function FileBrowser({ uri, defaultUri, rootUri, defaultExpandedUri, locale, agentConnect, onUriChange, onImportResources, renderImportResources, labels, requestOptions, className, style, ...rest }: FileBrowserProps): import("react").JSX.Element;

package/dist/modules/file-browser/find-result.d.ts

@@ -0,0 +1,24 @@
+import type { FsEntry } from './fs-model.js';
+/** 语义搜索返回的分组结果。Grouped results of a semantic search. */
+export interface FindResult {
+    memories?: Array<{
+        uri?: string;
+        abstract?: string;
+    }>;
+    resources?: Array<{
+        uri?: string;
+        abstract?: string;
+    }>;
+    skills?: Array<{
+        uri?: string;
+        abstract?: string;
+    }>;
+}
+/**
+ * 把分组结果合并成一个按 URI 去重的列表。搜索视图只需要「跳到哪个资源」，类别
+ * 分组对使用者没有意义。
+ *
+ * Merges the grouped result into one list deduplicated by URI: the search view
+ * only needs "which resource to jump to", so the category split adds nothing.
+ */
+export declare function mergeFindResult(result: FindResult | null | undefined): FsEntry[];

package/dist/modules/file-browser/fs-directories.d.ts

@@ -0,0 +1,33 @@
+import type { DirState } from './fs-model.js';
+/**
+ * 树已知的目录 URI 集合：根目录，加上每一层已加载条目里标记为目录的那些。
+ *
+ * 它与「当前可见的行」无关——根目录从不出现在展平列表里，祖先折叠后其后代也会
+ * 消失，但它们的类型不会因此改变。预览据此决定读 L0/L1 摘要还是读正文。
+ *
+ * The set of directory URIs the tree knows about: the root plus every loaded entry
+ * marked as a directory.
+ *
+ * It is independent of the rows currently visible — the root never appears in the
+ * flattened list, and a descendant disappears when its ancestor collapses, yet
+ * neither changes type. The preview decides between an L0/L1 summary and content
+ * from this set.
+ */
+export declare function knownDirectories(rootUri: string, dirs: Record<string, DirState>): ReadonlySet<string>;
+/**
+ * 树里出现过的文件 URI。与 {@link knownDirectories} 一起构成「类型已知」的判定：
+ * 两者都不包含，说明这个 URI 还没被加载过，类型未知——此时不能假定它是文件。
+ *
+ * The file URIs the tree has seen. Together with {@link knownDirectories} this decides
+ * "type known": in neither means the URI was never loaded, so its type is unknown —
+ * and it must not be assumed to be a file.
+ */
+export declare function knownFiles(dirs: Record<string, DirState>): ReadonlySet<string>;
+/**
+ * 「这个 URI 是树里见过的文件」的判定函数。引用跟着文件集合走，因此同一份加载
+ * 结果下它是稳定的，可以作为依赖。
+ *
+ * The predicate "this URI is a file the tree has seen". Its identity follows the file
+ * set, so it stays stable for one load result and can be used as a dependency.
+ */
+export declare function useKnownFile(dirs: Record<string, DirState>): (uri: string) => boolean;

package/dist/modules/file-browser/fs-file-kind.d.ts

@@ -0,0 +1,19 @@
+import type { FilePreviewFileTab } from '../../components/file-preview/index.js';
+import type { ReactNode } from 'react';
+/**
+ * 该文件是否应按二进制读取。没有扩展名或扩展名未知时按文本处理——绝大多数
+ * 无扩展名的资源都是文本，例如 `Dockerfile`、`Makefile`。
+ *
+ * Whether the file should be read as binary. A file with no extension, or an
+ * unknown one, is treated as text — most extensionless resources are text, such as
+ * `Dockerfile` and `Makefile`.
+ */
+export declare function isBinaryFile(name: string): boolean;
+/** 该文件名对应的 MIME 类型。The MIME type for this file name. */
+export declare function mimeTypeOf(name: string): string;
+/**
+ * 一个二进制文件的预览页签。字节直接交给底座，按 `fileName` 的扩展名选 Adapter。
+ * A preview tab for a binary file. The bytes go to the base, which picks an adapter
+ * from the `fileName` extension.
+ */
+export declare function toBinaryTab(uri: string, name: string, file: Blob, icon?: ReactNode, openParent?: (uri: string) => Promise<void>): FilePreviewFileTab;

package/dist/modules/file-browser/fs-icon.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+/**
+ * 文件行的类型图标。同一份图标集里每个键都登记了浅色与暗色两套色值，交给
+ * `color` 由 CSS 跟随宿主的 `.dark`，不在这里判断主题。
+ *
+ * 树行与预览页签共用它，两处的图标因此完全一致——页签不该另画一套。
+ *
+ * The type icon of a file row. Every key in the icon set registers a light and a
+ * dark colour; `color` lets CSS follow the host's `.dark` rather than deciding the
+ * scheme here.
+ *
+ * The tree row and the preview tab share it, so both show the same icon — a tab
+ * has no business drawing its own.
+ */
+export declare function fileTypeIcon(name: string): ReactNode;
+/** 目录的图标，与树上的文件夹图标同源。The directory icon, the tree's folder icon. */
+export declare function directoryIcon(): ReactNode;

package/dist/modules/file-browser/fs-model.d.ts

@@ -0,0 +1,106 @@
+import type { FilePreviewDirectoryTab, FilePreviewFileTab } from '../../components/file-preview/index.js';
+import type { ReactNode } from 'react';
+import type { FileTreeEntryRow, FileTreeRow } from '../../components/file-tree/index.js';
+/**
+ * 目录接口返回的一行。`ls` 的 `output=agent` 不返回 `name`，名称从 URI 末段取。
+ * One row from the directory API. `ls` with `output=agent` returns no `name`, so
+ * the name comes from the last URI segment.
+ */
+export interface FsEntry {
+    uri: string;
+    isDir?: boolean;
+    size?: number;
+    modTime?: string;
+    abstract?: string;
+}
+/** 一个目录已加载的子节点与分页状态。 */
+export interface DirState {
+    entries: FsEntry[];
+    hasMore: boolean;
+    loading: boolean;
+    error: Error | null;
+}
+/** 语义搜索返回的分组结果。Grouped results of a semantic search. */
+/** 空目录状态。An empty directory state. */
+export declare const emptyDir: () => DirState;
+/**
+ * 把新到的一页并入目录状态：`offset` 为 0 是首屏、直接替换，否则追加到已有
+ * 子节点之后。
+ *
+ * 追加而不是替换，是因为分页要保留前几页；替换会让「加载更多」把列表截成最后
+ * 一页。
+ *
+ * Merges an arriving page into a directory's state: `offset` 0 is the first page and
+ * replaces, anything else appends to the children already loaded.
+ *
+ * It appends rather than replaces because paging has to keep the earlier pages;
+ * replacing would truncate the list to its last page on "load more".
+ */
+export declare function mergePage(current: DirState | undefined, page: {
+    entries: FsEntry[];
+    hasMore: boolean;
+}, offset: number): DirState;
+/** 从 URI 取末段名称。最后一段为空时回退到整个 URI。 */
+export declare function nameFromUri(uri: string): string;
+/**
+ * 把接口返回的一行映射成树行。目录未提供子节点信息，按「可以展开」处理。
+ *
+ * `index` 用于搜索结果：同一个 URI 可能出现在两个类别里，行 id 必须唯一，
+ * 否则选中与滚动定位会命中错的行。
+ *
+ * Maps one API entry onto a tree row. A directory carries no child information,
+ * so it is treated as expandable.
+ *
+ * `index` is for search results: one URI can appear in two categories, and row
+ * ids must be unique or selection and scroll targeting hit the wrong row.
+ */
+export declare function toEntryRow(entry: FsEntry, depth: number, expanded: boolean, index?: number, busy?: boolean): FileTreeEntryRow;
+/**
+ * 一个文件的预览页签。行数达到上限时按截断处理——接口不返回总行数，只能由
+ * 「读满了」推断出「可能还有」。
+ *
+ * A preview tab for one file. Reaching the line cap is reported as truncation:
+ * the API returns no total, so "the cap was filled" is the only signal that more
+ * content may exist.
+ */
+export declare function toFileTab(entry: FsEntry, content: string, maxLines: number, icon?: ReactNode, openParent?: (uri: string) => Promise<void>): FilePreviewFileTab;
+/**
+ * 目录的预览页签：两级摘要各自成一级，走 `directory` 页签，而不是文件页签。
+ *
+ * 文件页签只有正文，目录还要在标题行与正文之间多一层同级切换——这正是
+ * `directory` 这一类存在的理由。
+ *
+ * A preview tab for a directory: each summary level is one level of a `directory`
+ * tab rather than a file tab.
+ *
+ * A file tab is just a body; a directory also needs one more level of sibling
+ * switching between its header and body, which is exactly why the `directory` kind
+ * exists.
+ */
+export interface DirectorySummary {
+    /** L0 摘要正文。The L0 abstract body. */
+    abstract: string;
+    /** L1 总览正文。The L1 overview body. */
+    overview: string;
+    /**
+     * 该级摘要的请求失败原因。为 `undefined` 表示请求成功（正文可能是空串，即
+     * 「还没生成」）；有值表示「取不到」，与「没生成」是两件事，必须让用户分得清。
+     *
+     * Why that level's request failed. `undefined` means the request succeeded (the body
+     * may be empty, meaning "not generated yet"); a value means "could not load", which
+     * is a different situation the user has to be able to tell apart.
+     */
+    abstractError?: string;
+    overviewError?: string;
+}
+export declare function toDirectoryTab(uri: string, summary: DirectorySummary, labels: {
+    l0: string;
+    l1: string;
+    failure: string;
+}, openParent?: (uri: string) => Promise<void>, icon?: ReactNode): FilePreviewDirectoryTab;
+/** 把目录状态展开成按渲染顺序排列的行，只展开已打开的分支。 */
+export declare function flattenTree(uri: string, depth: number, dirs: Record<string, DirState>, expanded: ReadonlySet<string>): FileTreeRow[];
+/** 请求被取消时不需要写回状态。A cancelled request has no state to write. */
+export declare function isAbort(error: unknown): boolean;
+/** 把任意抛出物归一成 Error。Normalises a thrown value into an Error. */
+export declare function toError(cause: unknown): Error;

package/dist/modules/file-browser/fs-page.d.ts

@@ -0,0 +1,16 @@
+import type { OvClient, OvRequestOptions } from '../../client/types.js';
+import type { FsEntry } from './fs-model.js';
+/** 一次取多少个子节点。One page of children. */
+export declare const PAGE_SIZE = 200;
+/**
+ * 读一页子节点。单独成文件是因为它是纯请求逻辑：没有状态、没有取消管理，调用方
+ * 传入 signal 即可；留在 Hook 里只会让那个文件超出行数上限。
+ *
+ * Reads one page of children. It lives in its own file because it is pure request
+ * logic with no state and no cancellation of its own — the caller supplies the
+ * signal — and keeping it in the Hook would only push that file past the line limit.
+ */
+export declare function loadPage(client: OvClient, uri: string, offset: number, signal: AbortSignal, requestOptions?: OvRequestOptions): Promise<{
+    entries: FsEntry[];
+    hasMore: boolean;
+}>;

package/dist/modules/file-browser/fs-path.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 从根到目标路径之间的目录，按由浅到深排列；目标本身也包含在内——展开一个目录
+ * 才能看到它的子节点。路径不在根之下时返回空数组。
+ *
+ * 拼接时保留根自带的斜杠：`viking://` 去掉末尾斜杠会变成 `viking:`，拼出来就是
+ * `viking:/user` 这种不存在的路径。
+ *
+ * The directories from the root down to the target, shallowest first, including
+ * the target itself: a directory must be open for its children to show. Returns an
+ * empty array when the path is not under the root.
+ *
+ * The root keeps its own slashes when joined: stripping the trailing ones from
+ * `viking://` yields `viking:`, and joining that produces a path like
+ * `viking:/user` that does not exist.
+ */
+export declare function expandChain(rootUri: string, targetUri?: string): string[];