@openviking/react 0.1.1 → 0.1.3

package/dist/modules/console/style.css

@@ -1,6 +1,88 @@
+.ov-agent-connect, .ov-divider, .ov-file-browser, .ov-file-browser-entries, .ov-file-preview, .ov-file-tree, .ov-module-placeholder, .ov-popover, .ov-scope-switcher, .ov-tooltip, .ov-tui, .ov-viking-bot, .ov-viking-bot__interaction {
+  --ov-ui-primary-default: #5252ff;
+  --ov-ui-primary-hover-default: #7075ff;
+  --ov-ui-primary-active-default: #3833d2;
+  --ov-ui-primary-light-default: #f5f7ff;
+  --ov-ui-connect-glow-warm-default: #ff952b0a;
+  --ov-ui-connect-glow-pink-default: #fb4fbc0f;
+  --ov-ui-connect-glow-pink-soft-default: #fb4fbc0a;
+  --ov-ui-on-primary-default: #fff;
+  --ov-ui-text-1-default: #0b0b0f;
+  --ov-ui-text-2-default: #3f3f51;
+  --ov-ui-text-3-default: #6e718c;
+  --ov-ui-text-description-default: #0006;
+  --ov-ui-text-disabled-default: #a5a7bb;
+  --ov-ui-border-1-default: #f0f2fa;
+  --ov-ui-border-2-default: #e1e4f2;
+  --ov-ui-border-3-default: #d7daea;
+  --ov-ui-bg-1-default: #fff;
+  --ov-ui-bg-3-default: #f7f8fd;
+  --ov-ui-bg-4-default: #f6f7fa;
+  --ov-ui-bg-5-default: #f1f2f9;
+  --ov-ui-status-success-default: #1f9d55;
+  --ov-ui-shadow-default: #0f172a;
+  --ov-ui-focus-default: #5252ff;
+  --ov-ui-fill-hover-default: #f1f2f9;
+  --ov-ui-status-error-default: #c43838;
+  --ov-ui-warning-default: #b26a00;
+  --ov-ui-warning-light-default: #fff0b3;
+  --ov-ui-tooltip-bg-default: #1f2329;
+  --ov-ui-tooltip-text-default: #fff;
+}
+
+.dark .ov-agent-connect, .dark .ov-divider, .dark .ov-file-browser, .dark .ov-file-browser-entries, .dark .ov-file-preview, .dark .ov-file-tree, .dark .ov-module-placeholder, .dark .ov-popover, .dark .ov-scope-switcher, .dark .ov-tooltip, .dark .ov-tui, .dark .ov-viking-bot, .dark .ov-viking-bot__interaction {
+  --ov-ui-primary-default: #5f5fff;
+  --ov-ui-primary-hover-default: #7075ff;
+  --ov-ui-primary-active-default: #4242ba;
+  --ov-ui-primary-light-default: #1a1632;
+  --ov-ui-connect-glow-warm-default: #ff952b05;
+  --ov-ui-connect-glow-pink-default: #fb4fbc08;
+  --ov-ui-connect-glow-pink-soft-default: #fb4fbc05;
+  --ov-ui-text-1-default: #c7ccd6;
+  --ov-ui-text-2-default: #9da3af;
+  --ov-ui-text-3-default: #737a87;
+  --ov-ui-text-description-default: #fff6;
+  --ov-ui-text-disabled-default: #42464e;
+  --ov-ui-border-1-default: #23252a;
+  --ov-ui-border-2-default: #2e3138;
+  --ov-ui-border-3-default: #3a3d45;
+  --ov-ui-bg-1-default: #131416;
+  --ov-ui-bg-3-default: #1b1d21;
+  --ov-ui-bg-4-default: #202227;
+  --ov-ui-bg-5-default: #23252a;
+  --ov-ui-focus-default: #5f5fff;
+  --ov-ui-fill-hover-default: #23252a;
+  --ov-ui-status-error-default: #ff9595;
+  --ov-ui-warning-default: #e0a04a;
+  --ov-ui-warning-light-default: #3a2f14;
+  --ov-ui-tooltip-bg-default: #2a2d33;
+  --ov-ui-tooltip-text-default: #f0f1f3;
+}
+
+.ov-agent-connect {
+  --ov-ui-connect-card-default: #fbfbfc;
+  --ov-ui-connect-tabs-default: #f7f7f9;
+  --ov-ui-connect-selected-default: #f3f4f7;
+  --ov-ui-connect-border-default: #edeef2;
+  --ov-ui-connect-outline-default: #e1e3ea;
+  --ov-ui-connect-muted-default: #787c91;
+  --ov-ui-connect-notice-default: #2e2984;
+}
+
+.dark .ov-agent-connect {
+  --ov-ui-connect-card-default: var(--ov-ui-bg-3-default);
+  --ov-ui-connect-tabs-default: var(--ov-ui-bg-3-default);
+  --ov-ui-connect-selected-default: var(--ov-ui-bg-4-default);
+  --ov-ui-connect-border-default: var(--ov-ui-border-1-default);
+  --ov-ui-connect-outline-default: var(--ov-ui-border-2-default);
+  --ov-ui-connect-muted-default: var(--ov-ui-text-3-default);
+  --ov-ui-connect-notice-default: var(--ov-ui-text-2-default);
+}
+
 .ov-module-placeholder {
   box-sizing: border-box;
-  border: 1px dashed var(--ov-ui-border, currentColor);
+  border: 1px dashed
+    var(--ov-ui-color-border-2, var(--ov-ui-border-2-default, currentColor));
   border-radius: var(--ov-ui-radius, 6px);
   min-width: 0;
   min-height: 160px;

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,33 @@
+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?: 'en-US' | 'zh-CN';
+    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,28 @@
+import type { FilePreviewLabels } from '../../components/file-preview/index.js';
+import type { FileTreeLabels } from '../../components/file-tree/index.js';
+import type { FileBrowserLabels } from './types.js';
+/** 模块外壳自己渲染的文案，其余透传给树与预览。 */
+type ShellLabels = Omit<FileBrowserLabels, 'tree' | 'preview'>;
+/**
+ * 模块外壳的内置文案。树与预览的默认值留在各自组件里，模块不重复一份。
+ * Built-in copy of the module shell. The tree and the preview keep their own
+ * defaults, so the module does not duplicate them.
+ */
+export declare const DEFAULT_LABELS: Required<ShellLabels>;
+/** 解析后的外壳文案，外加透传给两个组件的文案。 */
+export interface ResolvedLabels extends Required<ShellLabels> {
+    tree: FileTreeLabels | undefined;
+    previewLabels: FileBrowserLabels['preview'];
+}
+/** 逐项合并默认文案；树与预览的文案原样透传，缺省由组件自己兜底。 */
+export declare function resolveLabels(labels: FileBrowserLabels | undefined): ResolvedLabels;
+/**
+ * 预览组件的文案：模块自己的那几项叠在宿主透传的之上。组件那份英文默认值只在
+ * 宿主完全不传时才会用到，模块不能让它在中文界面里漏出来。
+ *
+ * The preview component's copy: the module's own fields layered over what the host
+ * passed through. The component's English defaults only apply when a host passes
+ * nothing, and must not leak into a Chinese interface.
+ */
+export declare function resolvePreviewLabels(text: ResolvedLabels): FilePreviewLabels;
+export {};

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,18 @@
+/**
+ * 搜索行：搜索框与刷新按钮。两者都是模块自己的，宿主入口在上一行的
+ * `toolbarActions` 里。
+ *
+ * The search row: the search box and the refresh button. Both belong to the module;
+ * host entries live in `toolbarActions` on 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,30 @@
+import type { ReactNode } from 'react';
+import type { FileTreeLabels } from '../../components/file-tree/index.js';
+import type { FileBrowserApi } from './types.js';
+/**
+ * 左栏：宿主入口条、搜索行与目录树。
+ *
+ * 宽度由外层的可拖拽分隔条决定，因此这里只铺满自己的盒子，不设宽度；树内容
+ * 比栏宽时横向滚动，而不是把名称截成省略号。
+ *
+ * The left column: the host's 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 {
+    toolbarActions?: ReactNode;
+    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({ toolbarActions, 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, toolbarActions, onUriChange, 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[];

package/dist/modules/file-browser/fs-read-directory.d.ts

@@ -0,0 +1,20 @@
+import type { OvClient, OvRequestOptions } from '../../client/types.js';
+import type { FilePreviewDirectoryTab } from '../../components/file-preview/index.js';
+/**
+ * 读目录的两级摘要，各自成一个页签：L0 是摘要，L1 是总览。
+ *
+ * 两个接口分别请求，一个失败不影响另一个；两个都为空时仍给出两个空页签，
+ * 让使用者知道目录存在但没有生成内容，而不是看到一片空白。
+ *
+ * Reads a directory's two summary levels, one tab each: L0 is the abstract and L1
+ * the overview.
+ *
+ * The two endpoints are requested separately so one failing does not hide the
+ * other; when both are empty the tabs still appear, so the user sees that the
+ * directory exists but has no generated content instead of blank space.
+ */
+export declare function readDirectory(client: OvClient, uri: string, options: OvRequestOptions, labels: {
+    l0: string;
+    l1: string;
+    failure: string;
+}, openParent?: (uri: string) => Promise<void>): Promise<FilePreviewDirectoryTab>;

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

@@ -0,0 +1,22 @@
+import type { OvClient, OvRequestOptions } from '../../client/types.js';
+/**
+ * 一次请求的**有效作用域**：客户端实例加上逐请求覆盖的身份字段。
+ *
+ * 只按客户端实例判定是不够的——宿主可以在同一个 Provider 下把
+ * `requestOptions.accountId` 从 A 换成 B，客户端对象不变，但数据空间已经换了；
+ * 上一个账号在途的响应同样不能落到新账号的树上。
+ *
+ * The **effective scope** of one request: the client instance plus the per-request
+ * identity overrides.
+ *
+ * The client instance alone is not enough — a host can switch
+ * `requestOptions.accountId` from A to B under the same Provider, leaving the client
+ * object unchanged while the data space has changed; a response still in flight for
+ * the previous account must not land on the new account's tree either.
+ */
+export declare function scopeKeyOf(client: OvClient | null, options: OvRequestOptions | undefined, rootUri?: string): string;
+/** 一次请求所属的作用域：键与它的控制器。One request's scope: its key and controller. */
+export interface RequestScope {
+    key: string;
+    controller: AbortController;
+}

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

@@ -0,0 +1,25 @@
+import type { OvClient, OvRequestOptions } from '../../client/types.js';
+/**
+ * 问服务端一个 URI 是不是目录。
+ *
+ * 只在类型未知时调用：树只认识已加载的层，宿主直接传一个尚未展开过的目录 URI 时
+ * 它不在已知集合里，仅凭这一点按文件处理会让目录丢掉 L0/L1 摘要、改去读正文。
+ *
+ * 查不到（404、无权限）时按文件处理：调用方本来就要读这个资源，让那次读取去报
+ * 真正的失败比在这里拦下来更直接。
+ *
+ * Asks the server whether a URI is a directory.
+ *
+ * Only called when the type is unknown: the tree only knows the levels it has loaded,
+ * so a directory URI the host passes directly, before it was ever expanded, is absent
+ * from the known set — and treating that as a file would make the directory lose its
+ * L0/L1 summary and read content instead.
+ *
+ * A lookup failure (404, no permission) falls back to "file": the caller is about to
+ * read the resource anyway, and letting that read report the real failure is more
+ * direct than stopping here.
+ */
+export declare function resolveIsDirectory(client: OvClient, uri: string, options: OvRequestOptions): Promise<boolean>;
+/** 一个带 `AbortError` 名字的错误，交给既有的取消分支处理。 */
+/** An error named `AbortError`, for the existing cancellation branch. */
+export declare function abortError(): Error;

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

@@ -1 +1,3 @@
-export * from './file-browser.js';
+export { FileBrowser } from './file-browser.js';
+export { useFileBrowser } from './use-file-browser.js';
+export type { FileBrowserActions, FileBrowserApi, FileBrowserLabels, FileBrowserProps, } from './types.js';