@openviking/react 0.1.2 → 0.1.3

package/dist/modules/file-browser/tree-info-copy.d.ts

@@ -0,0 +1,15 @@
+import type { FileTreeLabels } from '../../components/file-tree/index.js';
+/**
+ * 按语言解析目录树的文案。组件内置的是英文，模块这一层必须整份给中文——只
+ * 覆盖其中几项会让同一张卡片里中英文混排，比全英文更难读。
+ *
+ * 宿主的 `info` 逐键叠在内置值之上：整份替换会丢掉宿主没提到的键。
+ *
+ * Resolves the tree copy for a language. The component ships English, so the module
+ * supplies Chinese as a whole set — a partial override would mix languages inside
+ * one card, which reads worse than English alone.
+ *
+ * A host `info` layers key by key over the built-in values: replacing it wholesale
+ * would drop the keys the host did not mention.
+ */
+export declare function resolveTreeLabels(locale: 'en-US' | 'zh-CN' | undefined, hostLabels: FileTreeLabels | undefined): FileTreeLabels | undefined;

package/dist/modules/file-browser/tree-info-copy.zh-CN.d.ts

@@ -0,0 +1,15 @@
+import type { FileTreeInfoLabels } from '../../components/file-tree/index.js';
+/**
+ * 目录说明与浮层字段名的中文文案。
+ *
+ * 组件内置的是英文，模块这一层必须按当前语言整份传下去——只覆盖其中几项会让
+ * 同一张卡片里中英文混排，比全英文更难读。
+ *
+ * Chinese copy for the directory descriptions and the field names inside the
+ * popover.
+ *
+ * The component ships English; the module passes a whole set per language. A
+ * partial override would mix Chinese and English inside one card, which reads worse
+ * than English alone.
+ */
+export declare const TREE_INFO_LABELS_ZH_CN: FileTreeInfoLabels;

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

@@ -1,49 +1,75 @@
+import type { FilePreviewLabels, FilePreviewTab } from '../../components/file-preview/index.js';
+import type { FileTreeEntryRow, FileTreeLabels, FileTreeRow } from '../../components/file-tree/index.js';
 import type { OvRequestOptions } from '../../client/index.js';
 import type { HTMLAttributes, ReactNode } from 'react';
-/** 文件浏览模块的可替换文案。Replaceable copy of the file browser module. */
+/**
+ * 文件浏览模块的可替换文案。树与预览各有自己的一套，分别透传，模块外壳只提供
+ * 自己渲染的那几条。
+ *
+ * Replaceable copy of the file browser module. The tree and the preview each keep
+ * their own set, passed through as-is; the module shell only carries the strings
+ * it renders itself.
+ */
 export interface FileBrowserLabels {
-    /**
-     * 占位说明。缺省为 `Placeholder. Functionality is not available yet.`。
-     * Placeholder description. Defaults to "Placeholder. Functionality is not
-     * available yet.".
-     */
-    description?: string;
-    /** 区域标题。Area title. */
-    title?: string;
-    /** 搜索框占位文案。Search placeholder. */
-    searchPlaceholder?: string;
-    /** 搜索无结果提示。Message shown when a search returns nothing. */
-    searchEmpty?: string;
-    /** 刷新按钮的无障碍名称。Accessible name of the refresh control. */
-    refresh?: string;
     /** 未选中资源时的提示。Message shown when no resource is selected. */
     empty?: string;
     /** 加载失败提示。Load failure message. */
     error?: string;
     /** 重试按钮文案。Retry button label. */
     retry?: string;
-}
-/**
- * 工具栏按钮的属性。宿主在 `toolbarActions` 里用它组合自己的入口。
- * Props of a toolbar button. The host composes its own entries with it inside
- * `toolbarActions`.
- */
-export interface FileBrowserToolbarButtonProps extends Omit<HTMLAttributes<HTMLButtonElement>, 'children' | 'onClick'> {
-    /** 按钮图标。Button icon. */
-    icon: ReactNode;
-    /** 按钮文案。Button label. */
-    children: ReactNode;
-    /** 是否禁用，缺省为 `false`。Whether the button is disabled; defaults to `false`. */
-    disabled?: boolean;
-    /** 点击后触发。Called on click. */
-    onClick?: () => void;
+    /** 刷新按钮的无障碍名称。Accessible name of the refresh control. */
+    refresh?: string;
+    /** 搜索框占位文案。Search placeholder. */
+    searchPlaceholder?: string;
+    /** 搜索无结果提示。Message shown when a search returns nothing. */
+    searchEmpty?: string;
+    /** 搜索请求失败的结论，原因由服务端返回。Conclusion when the search request fails; the reason comes from the server. */
+    searchFailed?: string;
+    /** 搜索进行中的提示。Message shown while a search runs. */
+    searchLoading?: string;
+    /** 预览读取正文时的提示。Message shown while the preview reads a resource. */
+    loading?: string;
+    /** 分段器里的「预览」。The "preview" segment label. */
+    previewMode?: string;
+    /** 分段器里的「源码」。The "source" segment label. */
+    sourceMode?: string;
+    /** 复制路径按钮的文案。Label of the copy-path button. */
+    copyPath?: string;
+    /** 复制正文按钮的无障碍名称。Accessible name of the copy-content button. */
+    copyContent?: string;
+    /** 下载按钮的无障碍名称。Accessible name of the download button. */
+    download?: string;
+    /** 版本历史按钮的无障碍名称。Accessible name of the version-history button. */
+    history?: string;
+    /** 视图切换分组的无障碍名称。Accessible name of the view-switch group. */
+    viewSwitch?: string;
+    /** 树与详情之间分隔条的无障碍名称。Accessible name of the divider between the tree and the detail. */
+    resizeTree?: string;
+    /** 目录预览的 L0 摘要页签。The L0 summary tab of a directory preview. */
+    l0Summary?: string;
+    /** 目录预览的 L1 总览页签。The L1 overview tab of a directory preview. */
+    l1Overview?: string;
+    /** 目录某一级摘要尚未生成时的提示。Message shown when a summary level is empty. */
+    summaryEmpty?: string;
+    /**
+     * 目录某一级摘要请求失败、且服务端没给消息时的兜底文案。与 `summaryEmpty` 是两
+     * 件事：前者是「取不到」，后者是「还没生成」，处置完全不同。
+     *
+     * Fallback copy when a summary level's request failed without a server message. It
+     * differs from `summaryEmpty`: the former is "could not load", the latter is "not
+     * generated yet", and the two call for different actions.
+     */
+    summaryFailed?: string;
+    /** 目录树文案。Copy of the file tree. */
+    tree?: FileTreeLabels;
+    /** 预览文案。Copy of the file preview. */
+    preview?: FilePreviewLabels;
 }
 /**
  * 文件浏览模块的属性。
  *
  * 模块自己通过 Hook 取数，props 里没有数据字段：宿主给配置、受控的当前资源、
- * 工具栏入口、文案与请求配置。目录、搜索、预览页签与行级状态都在模块内维护，
- * 宿主不需要重复组装。
+ * 工具栏入口、文案与请求配置。目录、搜索、预览页签与行级状态都在模块内维护。
  *
  * 模块只覆盖文件树与文件预览两块。命令面板属于 `console`。
  *
@@ -52,8 +78,7 @@ export interface FileBrowserToolbarButtonProps extends Omit<HTMLAttributes<HTMLB
  * The module loads its own data through a Hook, so no prop carries data: the
  * host supplies configuration, the controlled current resource, the toolbar
  * entries, copy and request configuration. The directory, search, preview tabs
- * and per-row state all live inside the module, so the host does not assemble
- * them again.
+ * and per-row state all live inside the module.
  *
  * The module covers only the file tree and the file preview. The command panel
  * belongs to `console`.
@@ -61,8 +86,18 @@ export interface FileBrowserToolbarButtonProps extends Omit<HTMLAttributes<HTMLB
 export interface FileBrowserProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect' | 'children'> {
     /**
      * 受控的当前资源 URI。传入时由宿主决定当前资源，模块只上报切换意图。
+     *
+     * 用 `uri !== undefined` 判断是否受控，而不是真假值：空字符串也算宿主接管。
+     * 模块不会主动清空选中——点目录行与点面包屑祖先都带具体 URI，没有「取消选中」
+     * 的交互——因此这里不接受 `null`。
+     *
      * The controlled current resource URI. When given, the host owns the current
      * resource and the module only reports switch intent.
+     *
+     * Control is detected with `uri !== undefined` rather than truthiness: even an empty
+     * string counts as the host taking over. The module never clears the selection —
+     * both the row click and the breadcrumb ancestor carry a concrete URI, and there is
+     * no "deselect" interaction — so `null` is not accepted here.
      */
     uri?: string;
     /**
@@ -71,20 +106,52 @@ export interface FileBrowserProps extends Omit<HTMLAttributes<HTMLDivElement>, '
      */
     defaultUri?: string;
     /**
-     * 工具栏左侧的宿主入口，例如连接 Agent、导入资源。用
-     * {@link FileBrowserToolbarButton} 组合，保证与模块内置按钮外观一致。
-     * 搜索与刷新由模块渲染，入口之间的分隔线也由模块处理。
+     * 目录树的根，缺省为 `viking://`。宿主据此把浏览范围收敛到某个子树。
+     * Root of the tree, `viking://` by default. A host narrows the browsed scope
+     * with it.
+     */
+    rootUri?: string;
+    /**
+     * 首次加载后自动展开到的路径，逐级展开并加载。省略时只展开根，其余全部折叠。
+     * 与控制台一致：进去就能看到默认位置，不必逐层点开。
      *
-     * Host entries on the left of the toolbar, for example connecting an agent or
-     * importing resources. Compose them with {@link FileBrowserToolbarButton} so
-     * they match the module's own buttons. Search and refresh are rendered by the
-     * module, and so are the dividers between entries.
+     * Path to expand to after the first load, opening and loading each level. When
+     * omitted only the root is expanded and everything else stays collapsed,
+     * matching the console: the default location is visible right away.
+     */
+    defaultExpandedUri?: string;
+    /**
+     * 透传给预览底座的文案语言。组件自身文案仍由 `labels` 控制。
+     * Language of the preview base's built-in copy. The module's own copy stays
+     * with `labels`.
+     */
+    locale?: 'en-US' | 'zh-CN';
+    /**
+     * 工具栏上方的宿主入口，例如连接 Agent、导入资源。
+     *
+     * 两个固定入口由 `FileBrowserEntries` 提供，外观、图标、分隔线与等分排布都
+     * 在那边，宿主只决定显示哪几个与点击后做什么。搜索与刷新由模块自己渲染。
+     *
+     * Host entries above the toolbar, for example connecting an agent or importing
+     * resources.
+     *
+     * The two fixed entries come from `FileBrowserEntries`, which owns their look,
+     * icons, divider and equal-width layout; the host only decides which appear and
+     * what a click does. Search and refresh are rendered by the module itself.
      */
     toolbarActions?: ReactNode;
     /**
-     * 当前资源变化后触发，参数为新的 URI；清除选中时传入 `null`。
-     * Called after the current resource changes, with the new URI; `null` when
-     * the selection is cleared.
+     * 当前资源变化后触发，参数为新的 URI。
+     *
+     * 签名允许 `null`（上游契约），但本模块目前不会主动上报它：没有「取消选中」的
+     * 交互，模块也不会自己清空选中。宿主不要依赖收到 `null` 来收起详情区。
+     *
+     * Called after the current resource changes, with the new URI.
+     *
+     * The signature allows `null` (the upstream contract), but this module never reports
+     * it today: there is no "deselect" interaction and the module does not clear the
+     * selection itself. A host must not rely on receiving `null` to collapse the detail
+     * pane.
      */
     onUriChange?: (uri: string | null) => void;
     /**
@@ -99,3 +166,81 @@ export interface FileBrowserProps extends Omit<HTMLAttributes<HTMLDivElement>, '
      */
     requestOptions?: OvRequestOptions;
 }
+/**
+ * 模块 Hook 返回的视图数据与操作。宿主可以只用它自行组装视图，不需要组合
+ * 视图。
+ *
+ * The view data and operations the module Hook returns. A host may assemble its
+ * own view from these without the composite one.
+ */
+export interface FileBrowserApi {
+    /** 按渲染顺序排列的可见行。Visible rows in render order. */
+    rows: readonly FileTreeRow[];
+    /** 当前选中的行 id。Selected row id. */
+    selectedId: string | null;
+    /** 当前资源 URI。Current resource URI. */
+    currentUri: string | null;
+    /** 当前查询词。The current query. */
+    query: string;
+    /** 是否正在展示搜索结果。Whether search results are showing. */
+    searching: boolean;
+    /** 搜索是否进行中。Whether a search is running. */
+    searchLoading: boolean;
+    /** 刷新是否进行中。Whether a refresh is running. */
+    refreshing: boolean;
+    /** 预览底部元信息，例如字符数与更新时间；没有时为 `undefined`。 */
+    previewFooter?: string;
+    /** 首次加载是否已完成。Whether the first load has finished. */
+    isReady: boolean;
+    /** 整体加载失败的原因。Reason the whole tree failed to load. */
+    error: Error | null;
+    /**
+     * 目录列表本身的失败原因。与 {@link error} 的区别是来源单一：宿主据此在树的
+     * 位置渲染失败态并给出重试，而不是把 403 显示成「没有文件」。
+     *
+     * Why the directory listing itself failed. It differs from {@link error} by having
+     * a single source: a host renders a failure state with a retry in the tree's place
+     * instead of showing a 403 as "no files".
+     */
+    treeError: Error | null;
+    /**
+     * 搜索请求本身的失败原因。与「搜索成功但没有结果」不同：前者要显示原因与重试，
+     * 后者才是空态文案。
+     *
+     * Why the search request failed. It differs from "the search succeeded but matched
+     * nothing": the former needs the reason and a retry, only the latter is the empty
+     * copy.
+     */
+    searchError: Error | null;
+    /**
+     * 当前资源预览的失败原因。选中了资源但读不出来时用它区分「读失败」与「什么
+     * 都没选」。
+     *
+     * Why the preview of the current resource failed. It separates "could not read"
+     * from "nothing selected" when a resource is selected.
+     */
+    previewError: Error | null;
+    /** 当前资源的预览页签，没有选中时为 `null`。Preview tabs of the current resource, `null` when nothing is selected. */
+    previewTabs: readonly FilePreviewTab[] | null;
+    /** 当前预览页签 key。Active preview tab key. */
+    previewKey: string | null;
+    /** 树与预览的操作。Operations of the tree and the preview. */
+    actions: FileBrowserActions;
+}
+/** 模块 Hook 暴露的操作。Operations the module Hook exposes. */
+export interface FileBrowserActions {
+    /** 选中条目。Selects an entry. */
+    select: (row: FileTreeEntryRow) => Promise<void>;
+    /** 展开或折叠目录。Expands or collapses a directory. */
+    toggleExpand: (row: FileTreeEntryRow) => Promise<void>;
+    /** 加载下一页子节点。Loads the next page of children. */
+    loadMore: (row: FileTreeRow) => Promise<void>;
+    /** 重新加载失败的子节点。Retries a failed children load. */
+    retry: (row: FileTreeRow) => Promise<void>;
+    /** 重新加载整棵树并保留选中。Reloads the whole tree, keeping the selection. */
+    refresh: () => Promise<void>;
+    /** 切换预览页签。Switches the preview tab. */
+    setPreviewKey: (key: string) => void;
+    /** 更新查询词；空串回到目录树。Updates the query; an empty string returns to the tree. */
+    setQuery: (query: string) => void;
+}

package/dist/modules/file-browser/use-container-width.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 订阅元素的内容宽度，返回 ref 与当前宽度（四舍五入到整数像素）。
+ *
+ * 宽度要用来算拖拽上限，不能只在窗口 `resize` 时更新：宿主侧栏展开、字体变化
+ * 都会让容器变宽或变窄，而窗口尺寸不变。
+ *
+ * Subscribes to an element's content width, returning the ref and the current
+ * width rounded to whole pixels.
+ *
+ * The width feeds the drag limit, so a window `resize` listener is not enough: a
+ * host sidebar opening or a font change resizes the container while the window
+ * stays the same.
+ */
+export declare function useContainerWidth<T extends HTMLElement>(): {
+    ref: import("react").RefObject<T | null>;
+    width: number;
+};

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

@@ -0,0 +1,49 @@
+import type { OvRequestOptions } from '../../client/types.js';
+import type { FileBrowserApi } from './types.js';
+export interface UseFileBrowserOptions {
+    rootUri: string;
+    /**
+     * 宿主是否受控地持有当前资源。受控时 `currentUri` 就是唯一事实；非受控时
+     * `currentUri` 只是初始值，之后的选中由模块自己记在 `pendingUri` 里。
+     *
+     * 两者的区别只在「谁拥有选中」：非受控模块在初始没有选中时 `currentUri` 也是
+     * `null`，因此不能靠值来区分，必须显式声明。
+     *
+     * Whether the host owns the current resource. While controlled, `currentUri` is the
+     * single source of truth; while uncontrolled it is only the initial value and later
+     * selections live in the module's own `pendingUri`.
+     *
+     * The distinction is only about who owns the selection: an uncontrolled module also
+     * has a `null` `currentUri` when nothing is selected initially, so the value itself
+     * cannot tell the two apart and the mode has to be declared.
+     */
+    controlled?: boolean;
+    /**
+     * 目录两级摘要的标题与失败兜底文案。两级摘要各自可能请求失败，失败且服务端没给
+     * 消息时用 `failure` 显示——它必须可替换，否则宿主无法本地化。
+     *
+     * Titles of the two summary levels and the fallback copy for a failure. Either level
+     * can fail; when it fails without a server message, `failure` is shown — it has to be
+     * replaceable, or a host cannot localise it.
+     */
+    summaryLabels?: {
+        l0: string;
+        l1: string;
+        failure: string;
+    };
+    /** 首次加载后自动展开到的路径。Path to expand to after the first load. */
+    defaultExpandedUri?: string;
+    currentUri: string | null;
+    requestOptions?: OvRequestOptions;
+    onUriChange: (uri: string | null) => void;
+}
+/**
+ * 文件浏览模块的取数与联动：把目录树、搜索与预览组合成一份视图数据。三者各自
+ * 取数，这里只负责把它们接起来——目录行展开树，文件行与搜索结果打开预览。
+ *
+ * Data loading and coordination of the file browser module: the tree, the search
+ * and the preview each load their own data, and this only wires them together —
+ * a directory row expands the tree, while a file row or a search result opens
+ * the preview.
+ */
+export declare function useFileBrowser({ rootUri, controlled, summaryLabels, defaultExpandedUri, currentUri, requestOptions, onUriChange, }: UseFileBrowserOptions): FileBrowserApi;

package/dist/modules/file-browser/use-fs-preview.d.ts

@@ -0,0 +1,51 @@
+import type { FilePreviewTab } from '../../components/file-preview/index.js';
+import type { OvClient, OvRequestOptions } from '../../client/types.js';
+export interface PreviewState {
+    tabs: readonly FilePreviewTab[] | null;
+    activeKey: string | null;
+    error: Error | null;
+    /** 底部元信息，例如字符数。Footer metadata such as the character count. */
+    footer?: string;
+    setActiveKey: (key: string) => void;
+}
+export interface UseFsPreviewOptions {
+    client: OvClient | null;
+    uri: string | null;
+    /**
+     * 当前资源的类型。目录读 L0/L1 摘要，文件读正文，`unknown` 先查一次 `fs/stat`
+     * 再决定。
+     *
+     * 传三态而不是「目录集合」：集合每次加载都会换新引用，作为 effect 依赖会让预览
+     * 反复重取。三态是稳定的字符串，换引用的问题不存在。
+     *
+     * The type of the current resource. A directory reads its L0/L1 summary, a file reads
+     * its content, and `unknown` resolves with one `fs/stat` call first.
+     *
+     * A three-state value rather than the directory set: the set gets a new identity on
+     * every load, and as an effect dependency it would make the preview reload
+     * repeatedly. The three-state value is a stable string, so that cannot happen.
+     */
+    resourceType?: 'directory' | 'file' | 'unknown';
+    /** 目录两级摘要的标题。Titles of the two summary levels. */
+    labels?: {
+        l0: string;
+        l1: string;
+        failure: string;
+    };
+    /**
+     * 打开路径上的某一级祖先。面包屑与目录页签共用它。
+     * Opens one ancestor level; the breadcrumb and a directory tab share it.
+     */
+    openParent?: (uri: string) => Promise<void>;
+    /**
+     * 重新取数的代次。宿主调用刷新时递增，让同一资源的正文重新请求——内容在服务
+     * 端变了而 URI 没变，只靠依赖是看不出来的。
+     *
+     * Reload generation. A host increments it on refresh so the same resource is read
+     * again: the content changed on the server while the URI did not, which
+     * dependencies alone cannot express.
+     */
+    generation?: number;
+    requestOptions?: OvRequestOptions;
+}
+export declare function useFsPreview({ client, uri, resourceType, labels, openParent, generation, requestOptions, }: UseFsPreviewOptions): PreviewState;

package/dist/modules/file-browser/use-fs-search.d.ts

@@ -0,0 +1,35 @@
+import type { OvClient, OvRequestOptions } from '../../client/types.js';
+import { type FsEntry } from './fs-model.js';
+export interface SearchState {
+    /** 结果行；未搜索时为 `null`。Result entries, `null` before any search. */
+    results: FsEntry[] | null;
+    /** 搜索是否进行中。Whether a search is running. */
+    loading: boolean;
+    /** 搜索失败的原因。Why the search failed. */
+    error: Error | null;
+}
+export interface UseFsSearchOptions {
+    client: OvClient | null;
+    /** 已去抖的查询词；空串表示没有搜索。The debounced query; empty means no search. */
+    query: string;
+    targetUri: string;
+    /**
+     * 重新取数的代次。宿主调用刷新时递增，让同一查询词重新请求——外部数据变了
+     * 而查询词没变，只靠依赖是看不出来的。
+     *
+     * Reload generation. A host increments it on refresh so the same query is
+     * requested again: the data changed while the query did not, which dependencies
+     * alone cannot express.
+     */
+    generation?: number;
+    requestOptions?: OvRequestOptions;
+}
+/**
+ * 语义搜索。结果按 URI 去重后合并成一个列表——搜索视图只需要「跳到哪个资源」，
+ * 类别分组对使用者没有意义。
+ *
+ * Semantic search. Results merge into one list deduplicated by URI: the search
+ * view only needs "which resource to jump to", so the category split adds
+ * nothing for the user.
+ */
+export declare function useFsSearch({ client, query, targetUri, generation, requestOptions, }: UseFsSearchOptions): SearchState;

package/dist/modules/file-browser/use-fs-tree.d.ts

@@ -0,0 +1,43 @@
+import type { FileTreeEntryRow, FileTreeRow } from '../../components/file-tree/index.js';
+import type { OvClient, OvRequestOptions } from '../../client/types.js';
+export interface FsTreeState {
+    rows: readonly FileTreeRow[];
+    isReady: boolean;
+    error: Error | null;
+    /**
+     * 树已知的目录 URI 集合，与当前是否可见无关。
+     * Directory URIs the tree knows about, whether or not they are visible.
+     */
+    directoryUris: ReadonlySet<string>;
+    /**
+     * 该 URI 是否是树里见过的文件。与 {@link directoryUris} 都不命中即为类型未知。
+     * Whether the URI is a file the tree has seen. Missing from both this and
+     * {@link directoryUris} means the type is unknown.
+     */
+    isKnownFile: (uri: string) => boolean;
+    toggleExpand: (row: FileTreeEntryRow) => Promise<void>;
+    open: (uri: string) => Promise<void>;
+    loadMore: (parentId: string) => Promise<void>;
+    retry: (parentId: string) => Promise<void>;
+    refresh: () => Promise<void>;
+}
+export interface UseFsTreeOptions {
+    client: OvClient | null;
+    rootUri: string;
+    /**
+     * 首次加载后自动展开到的路径，逐级展开并加载子节点。省略时只展开根。
+     * Path to expand to after the first load, opening and loading each level.
+     * Omitting it leaves only the root expanded.
+     */
+    defaultExpandedUri?: string;
+    requestOptions?: OvRequestOptions;
+}
+/**
+ * 目录树的取数、展开与分页。按需展开：根目录先加载，展开某个目录时才取它的
+ * 子节点，每一层各自持有分页与失败状态，一个目录出错不影响其它分支。
+ *
+ * Loading, expansion and paging of the directory tree. It loads on demand: the
+ * root first, then a directory's children when it expands. Each level keeps its
+ * own paging and failure state, so one broken directory does not affect others.
+ */
+export declare function useFsTree({ client, rootUri, defaultExpandedUri, requestOptions, }: UseFsTreeOptions): FsTreeState;

package/dist/modules/file-browser/use-request-scope.d.ts

@@ -0,0 +1,39 @@
+import type { OvClient, OvRequestOptions } from '../../client/types.js';
+import { type RequestScope } from './fs-scope.js';
+/**
+ * 请求作用域：客户端实例、根目录与逐请求覆盖的身份字段。
+ *
+ * 换 Provider、换 `requestOptions.accountId`、换 `rootUri`，上一个作用域里还没回来
+ * 的请求都必须作废，否则 A 的响应会在 B 的树上落地。
+ *
+ * 中止是**传输副作用**，只在提交之后做，不在渲染里做：React 可以放弃一次渲染
+ * （`startTransition` + Suspense 就会），渲染里中止会把仍在屏幕上的那棵树的在途
+ * 请求杀掉。渲染里只记下「期望的作用域键」，请求回来时用它判断结果是否过期。
+ *
+ * The request scope: the client instance, the root and the per-request identity
+ * overrides.
+ *
+ * Switching the Provider, `requestOptions.accountId` or `rootUri` must invalidate the
+ * requests still in flight, or A's response lands on B's tree.
+ *
+ * Aborting is a **transport side effect** and happens only after commit, never during
+ * render: React may abandon a render (`startTransition` with Suspense does), and
+ * aborting there would kill the in-flight requests of the tree still on screen. Render
+ * only records the *desired* scope key, which a returning request compares against.
+ */
+export interface RequestScopeHandle {
+    /**
+     * 当前**已提交**作用域的键与控制器。
+     *
+     * 它是判断过期的唯一依据，因为只有提交才会改它：渲染期不写任何东西，被放弃的
+     * 渲染因此不会让仍在屏幕上的那棵树的结果作废。
+     *
+     * The key and controller of the **committed** scope.
+     *
+     * It is the only basis for staleness because only a commit changes it: render writes
+     * nothing, so an abandoned render cannot invalidate the results of the tree still on
+     * screen.
+     */
+    current: () => RequestScope;
+}
+export declare function useRequestScope(client: OvClient | null, requestOptions: OvRequestOptions | undefined, rootUri: string): RequestScopeHandle;

package/dist/modules/file-browser.js

@@ -1 +1 @@
-export { FileBrowser, FileBrowserToolbarButton } from "../l~0.js";
+export { FileBrowser, useFileBrowser } from "../l~0.js";

package/dist/modules/scope-cascade/style.css

@@ -1,4 +1,4 @@
-.ov-agent-connect, .ov-file-browser, .ov-file-preview, .ov-file-tree, .ov-module-placeholder, .ov-scope-switcher, .ov-tooltip, .ov-tui, .ov-viking-bot, .ov-viking-bot__interaction {
+.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;
@@ -30,7 +30,7 @@
   --ov-ui-tooltip-text-default: #fff;
 }
 
-.dark .ov-agent-connect, .dark .ov-file-browser, .dark .ov-file-preview, .dark .ov-file-tree, .dark .ov-module-placeholder, .dark .ov-scope-switcher, .dark .ov-tooltip, .dark .ov-tui, .dark .ov-viking-bot, .dark .ov-viking-bot__interaction {
+.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;