@deepseek-ai/dsh-client-ui-sidebar-files 0.1.6-alpha.2 → 0.1.7-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-sidebar-files/README.md
-README.md: efaf0a584e0e8617d0cb97442f9ebb5fa1fe7b59
-README.zh.md: a0d0abffcd6e9f4e979d9a6548537745d0a74ba6
+README.md: 0340991f16a61b80cd616982c6a6bea6ff60beac
+README.zh.md: 016c74d801a3582785cb600f493eaeb92f7567b9

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-The right Sidebar's navigator tab type: the session's workspace root as a tree, listed one level at a time over the wire, opening files into the Sidebar. It is a page type reached from the guide and claims no address; it opens files by address for the `dsh-resource://file` viewers to claim — nothing in `ui-sidebar-right` knows this package.
+Browse a Session's workspace tree and open files in Sidebar previews. The root and expanded directories refresh automatically from direct-entry watches; manual reload remains available. The tab is reached from the guide and claims no resource address.
 
 ## Table of Contents
 
@@ -25,25 +25,27 @@ The right Sidebar's navigator tab type: the session's workspace root as a tree,
 ## What it registers
 
 - **The type** — `ctx.sidebarRightTabs.register(...)` with kind `files`, id `@deepseek-ai/dsh-client-ui-sidebar-files`, band `builtin`, no patterns, and one guide entry (order 10, its title and description from the `sidebarFiles` namespace, its glyph the shared folder icon) that opens the type.
-- **The body** — the keyed `sidebar.right.pane.tab` seat under that id: a header row under the strip, then the tree. The header row is the document preview's (`ui-sidebar-documentpreview`): the root path, its directories greyed and its last segment in full ink, never ellipsized (a path wider than the row keeps its end and fades its start), with the one control, reload, at its right. The row is copied rather than shared because a plugin bundle shares runtime code only through the platform modules; once the artifact and slot surfaces settle, one copy in `ui-primitives` could serve every pane header.
+- **The body** — the keyed `sidebar.right.pane.tab` seat under that id: a header row under the strip, then the tree. The shared [`PathLabel`](../ui-primitives/README.md#component-catalog) displays the root path with subdued directories and a primary final segment. A clipped path retains its trailing characters with a left-edge fade; hovering reveals the full path. The reload control stays at its right.
 - **The chip title** — the keyed `sidebar.right.pane.tab.title` seat under that id: a shared `FileTypeIcon` folder glyph at 16px before the type's label. The tree's own rows never draw this sheet.
 
-Seven source files under `src/client/`: `definition.tsx` (the type), `store.ts` (what it keeps), `face.ts` (how it lists, Remote binding included), `FilesBody.tsx` (what it draws, with its ordering and failure-line helpers), `FilesTitle.tsx` (the chip title), `locales.ts` (what it says), and `index.ts` (the wiring).
+Source files under `src/client/`: `definition.tsx` (the type), `store.ts` (what it keeps), `face.ts` (Remote reads and watches), `directory-node.ts` (open directories and their lifetimes), `FilesBody.tsx` (what it draws, with its ordering and failure-line helpers), `FilesTitle.tsx` (the chip title), `locales.ts` (what it says), and `index.ts` (the wiring).
 
 <a id="the-tree"></a>
 ## The tree
 
-The root is the session's working directory, read from `useSessions().byId[sessionId].cwd`, and split for the header row by `pathPartsOf` from `@deepseek-ai/dsh-util-workspace-path`. Every level is keyed by absolute path; a child's path is its parent's joined with the entry name by `/`. A level is listed when it is first expanded, through `remote.workspaceFiles.list(sessionId, absolutePath)` on the `@deepseek-ai/dsh-api-workspace-files` namespace; the adapter keeps the listing's entries and truncation flag and drops its workspace-relative path. Rows are ordered directories first, then by natural, case-insensitive name; dotfiles are shown like any other entry.
+The root is the session's working directory, read from `useSessions().byId[sessionId].cwd`. Filesystem roots such as `/` and Windows drive roots are valid tree roots. Every level is keyed by absolute path; a child's path is its parent's joined with the entry name by `/`. A level is listed when it is first expanded, through `remote.workspaceFiles.list(sessionId, absolutePath)` on the `@deepseek-ai/dsh-api-workspace-files` namespace; the adapter keeps the listing's entries and truncation flag and drops its workspace-relative path. Rows are ordered directories first, then by natural, case-insensitive name; dotfiles are shown like any other entry.
 
 | Entry type | Row |
 |---|---|
-| `directory` | Toggles; the level is fetched the first time it opens and kept while collapsed. |
+| `directory` | Toggles; reopening lists again and restores still-present expanded descendants. Displayed entries remain cached while collapsed. |
 | `file` | Opens `dsh-resource://file/session/<sessionId>/<encoded path relative to the root>`, built by `fileAddressFor` from `@deepseek-ai/dsh-util-workspace-path` from the entry's absolute path and the tree's root, through `useTabInfo().tab.actions.openResource`, landing in the tab's own pane. |
 | `other` | Shown greyed and not clickable, so the directory is reported whole. |
 
-A level cut by the endpoint's entry cap ends with a marker; an empty level says so; a level that failed shows one line per code — `workspace-file/not-found`, `outside-workspace`, `not-directory` — and the transport's own message otherwise. Reload drops every listed level and asks again for the expanded ones; collapsed levels are fetched again when they next open. A session without a working directory shows a single line instead of a tree.
+A level cut by the endpoint's entry cap ends with a marker; an empty level says so; a level that failed shows one line per code — `workspace-file/not-found`, `outside-workspace`, `not-directory` — and the transport's own message otherwise. Reload refreshes the root and expanded levels in place, retaining displayed entries during reads instead of resetting the whole tree; collapsed levels are fetched again when they next open. A session without a working directory shows a single line instead of a tree.
 
-State lives in the type's own store, bucketed by tab id: `root`, `levels` (loading / ready / failed per absolute path), `expanded`, and `scrollTop`, which the body tracks locally while scrolling and commits once when it unmounts. Because the store outlives the body, switching to another sidebar tab and back remounts the tree with its levels intact and its scroll offset restored. The owner's `signal` ends a bucket: on abort the tab is forgotten, and neither a listing that settles afterwards nor the unmount's offset commit writes anything.
+State lives in the type's own store, bucketed by tab id: `root`, `levels` (loading / ready / failed per absolute path), `expanded`, `autoRefresh`, and `scrollTop`, which the body tracks locally while scrolling and commits once when it unmounts. Because the store outlives the body, switching to another sidebar tab and back remounts the tree with its levels intact and its scroll offset restored. The owner's `signal` ends a bucket: on abort the tab is forgotten, and neither a listing that settles afterwards nor the unmount's offset commit writes anything.
+
+Each open `DirectoryNode` owns its target watch for the Tab lifetime; collapse closes that node and its hidden descendants. Expansion changes during ancestor restoration update the store and pending nodes, so restored descendants follow the latest expansion preferences. Automatic refresh defaults to enabled; its separate toggle is hidden while state, labels, styles, and toggle logic remain. Changes received during a directory read or its completion remain pending for another refresh.
 
 <a id="model-experience"></a>
 ## Model Experience
@@ -57,7 +59,7 @@ None; directory listings travel over the Remote and assemble no model request.
 ## Known Limitations and Deferred Work
 
 <a id="known-limitations-and-deferred-work"></a>
-- **Listing only.** No search, artifact filter, drag-and-drop, rename, context menu, current-file highlight, or filesystem watching; a level changes only through reload.
+- **Listing only.** No search, artifact filter, drag-and-drop, rename, context menu, or current-file highlight.
 - **One root.** The tree is rooted at the session's working directory; there is no way to browse above it, and the Host refuses paths outside the workspace root anyway.
 
 <a id="dev-note"></a>
@@ -70,4 +72,4 @@ None.
 
 </details>
 
-**Runtime invariant:** No companion is published. The tree's only runtime state is one Slot store per tab, written by the body that owns it and forgotten on the tab's abort signal; there is no second observation of it to compare against.
+**Runtime invariant:** No companion is published. The tab-owned face keeps directory reads and watches private, and writes displayed state through its Slot store; tab cancellation releases both. The package exposes no independent observation for a runtime comparison.

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-右侧 Sidebar 的导航器 tab 类型：把会话的工作区根目录画成一棵树，逐层经线上列出，并把文件打开到 Sidebar 里。它是从引导页进入的页类型，不认领任何地址；它按地址打开文件，交给 `dsh-resource://file` 的查看器认领：`ui-sidebar-right` 里没有任何东西认识本包。
+浏览 Session 的工作区目录树，并在 Sidebar 预览中打开文件。根目录与已展开目录通过直接子项监听自动刷新，手动重新读取仍可用。该 tab 从引导页进入，不认领资源地址。
 
 ## 目录
 
@@ -25,25 +25,27 @@ kind: "package-reference"
 ## 注册了什么
 
 - **类型**：`ctx.sidebarRightTabs.register(...)`，kind 为 `files`，id 为 `@deepseek-ai/dsh-client-ui-sidebar-files`，档位 `builtin`，没有 patterns，另有一个打开该类型的引导页入口（order 10，标题与描述取自 `sidebarFiles` 命名空间，图标是共享的文件夹图标）。
-- **正文**：以该 id 为键的 `sidebar.right.pane.tab` slot：strip 下的一行标题行，然后是树。标题行与文档预览（`ui-sidebar-documentpreview`）的相同：根路径，目录部分灰色、最后一段正色，从不省略号截断（比行宽的路径保留末尾、淡出开头），右端是它唯一的控件、重新读取。这一行是复制而非共享，因为插件 bundle 只经平台模块共享运行时代码；待 artifact 与各 slot 的形态定下来后，可以在 `ui-primitives` 放一份供每个 pane 标题行使用。
+- **正文**：以该 id 为键的 `sidebar.right.pane.tab` slot：strip 下的一行标题行，然后是树。共享的 [`PathLabel`](../ui-primitives/README.zh.md#component-catalog) 显示根路径，目录使用弱化颜色，最后一段使用主色。路径过长时保留尾部字符并在左侧渐隐；悬停显示完整路径。重新读取控件位于右端。
 - **标签页标题**：以该 id 为键的 `sidebar.right.pane.tab.title` slot：类型标签前的一枚 16px 共享 `FileTypeIcon` 文件夹图标。树本身的行不画这枚图标。
 
-`src/client/` 下七个源文件：`definition.tsx`（类型是什么）、`store.ts`（它保存什么）、`face.ts`（它如何列目录，含 Remote 绑定）、`FilesBody.tsx`（它画什么，含排序与失败行两个辅助函数）、`FilesTitle.tsx`（标签页标题）、`locales.ts`（它说什么）、`index.ts`（接线）。
+`src/client/` 下的源文件：`definition.tsx`（类型是什么）、`store.ts`（它保存什么）、`face.ts`（Remote 读取与监听）、`directory-node.ts`（打开的目录及其生命周期）、`FilesBody.tsx`（它画什么，含排序与失败行两个辅助函数）、`FilesTitle.tsx`（标签页标题）、`locales.ts`（它说什么）、`index.ts`（接线）。
 
 <a id="the-tree"></a>
 ## 树
 
-根是会话的工作目录，读自 `useSessions().byId[sessionId].cwd`，标题行里的拆分由 `@deepseek-ai/dsh-util-workspace-path` 的 `pathPartsOf` 给出。每一层以绝对路径为键；子路径是父路径以 `/` 拼上条目名。一层在首次展开时经 `@deepseek-ai/dsh-api-workspace-files` 命名空间的 `remote.workspaceFiles.list(sessionId, absolutePath)` 列出；适配器保留列表的条目与截断标志，丢弃其工作区相对路径。行序为目录优先，其后按自然序、不分大小写的名称排列；dotfiles 与其他条目一样显示。
+根是会话的工作目录，读自 `useSessions().byId[sessionId].cwd`。`/` 和 Windows 盘根等文件系统根路径均可作为树的根。每一层以绝对路径为键；子路径是父路径以 `/` 拼上条目名。一层在首次展开时经 `@deepseek-ai/dsh-api-workspace-files` 命名空间的 `remote.workspaceFiles.list(sessionId, absolutePath)` 列出；适配器保留列表的条目与截断标志，丢弃其工作区相对路径。行序为目录优先，其后按自然序、不分大小写的名称排列；dotfiles 与其他条目一样显示。
 
 | 条目类型 | 行 |
 |---|---|
-| `directory` | 切换展开与折叠；该层在首次打开时拉取，折叠期间保留。 |
+| `directory` | 切换展开与折叠；再次打开时重新列举，并恢复仍存在的已展开后代。折叠期间保留已显示条目的缓存。 |
 | `file` | 经 `useTabInfo().tab.actions.openResource` 打开 `dsh-resource://file/session/<sessionId>/<encoded path relative to the root>`，地址由 `@deepseek-ai/dsh-util-workspace-path` 的 `fileAddressFor` 从条目的绝对路径与树的根生成，落在该 tab 自己的 pane 里。 |
 | `other` | 灰显且不可点击，从而完整呈现目录内容。 |
 
-被端点条目上限截断的层以一条标记收尾；空层如实说明；失败的层按错误码各显示一行（`workspace-file/not-found`、`outside-workspace`、`not-directory`），其他情况显示传输层自己的消息。重新读取丢弃所有已列出的层并只对展开中的层重新请求；折叠的层在下次打开时重新拉取。没有工作目录的会话只显示一行说明，而不是树。
+被端点条目上限截断的层以一条标记收尾；空层如实说明；失败的层按错误码各显示一行（`workspace-file/not-found`、`outside-workspace`、`not-directory`），其他情况显示传输层自己的消息。重新读取就地刷新根与展开中的层，读取期间保留显示条目，不重置整棵树；折叠的层在下次打开时重新拉取。没有工作目录的会话只显示一行说明，而不是树。
 
-状态保存在类型自己的存储里，按 tab id 分桶：`root`、`levels`（每个绝对路径的 loading / ready / failed）、`expanded` 与 `scrollTop`——滚动期间偏移由正文自己记录，卸载时一次性写入。存储比 body 活得久，切到其他侧栏 tab 再切回来时树带着已加载的层重新挂载，滚动位置也随之恢复。owner 的 `signal` 终结一个桶：中止时忘掉该 tab，其后才结算的列表与卸载时的偏移提交都什么也不写。
+状态保存在类型自己的存储里，按 tab id 分桶：`root`、`levels`（每个绝对路径的 loading / ready / failed）、`expanded`、`autoRefresh` 与 `scrollTop`——滚动期间偏移由正文自己记录，卸载时一次性写入。存储比 body 活得久，切到其他侧栏 tab 再切回来时树带着已加载的层重新挂载，滚动位置也随之恢复。owner 的 `signal` 终结一个桶：中止时忘掉该 tab，其后才结算的列表与卸载时的偏移提交都什么也不写。
+
+每个打开的 `DirectoryNode` 在 Tab 生命周期内持有自己的目标监听；折叠关闭该节点及其不可见后代。祖先恢复期间的展开状态变化会更新存储和待恢复节点，后代恢复时遵循最新展开偏好。自动刷新默认开启；独立开关暂时隐藏，状态、文案、样式与切换逻辑保留。目录读取期间或收尾时收到的变化仍会留待下一次刷新。
 
 <a id="model-experience"></a>
 ## 模型体验
@@ -57,7 +59,7 @@ kind: "package-reference"
 ## 已知限制与暂缓事项
 
 <a id="known-limitations-and-deferred-work"></a>
-- **只有列目录。**没有搜索、产物过滤、拖拽、重命名、右键菜单、当前文件高亮或文件系统监听；一层只会因重新读取而变化。
+- **只有列目录。**没有搜索、产物过滤、拖拽、重命名、右键菜单或当前文件高亮。
 - **只有一个根。**树以会话工作目录为根；没有办法浏览到它之上，而 Host 本来也拒绝工作区根之外的路径。
 
 <a id="dev-note"></a>
@@ -70,4 +72,4 @@ kind: "package-reference"
 
 </details>
 
-**运行时不变量：** 不发布 companion。树唯一的运行时状态是每 tab 一份的 Slot store，由持有它的正文写入、随 tab 的中止信号忘掉；没有第二个观测源可与之比对。
+**运行时不变量：** 不发布 companion。tab 持有的 face 内部管理目录读取与监听，并通过 Slot store 写入显示状态；tab 取消时释放二者。本包未暴露可用于运行时比对的独立观测源。

package/lib/client.js

@@ -6,6 +6,7 @@ window.__ModuleLoader__.load({
 		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 		let react_jsx_runtime = require("react/jsx-runtime");
 		let _deepseek_ai_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
+		require("@deepseek-ai/cordis");
 		let react = require("react");
 		let _deepseek_ai_dsh_client_store = require("@deepseek-ai/dsh-client-store");
 		//#region lib/types/client/definition.js
@@ -42,8 +43,215 @@ window.__ModuleLoader__.load({
 			};
 		}
 		//#endregion
+		//#region ../../typert/protocol/src/remote-error.ts
+		/**
+		* One Remote call failure: a real Error carrying its stable code and typed
+		* details. Owners throw it at the failure point; the Host Gateway encodes it
+		* onto the wire unchanged; the Client face rebuilds an instance for the
+		* `RemoteResult` error branch, so `throw result.error` keeps throw semantics.
+		* Discrimination is always by `code`, never by instanceof.
+		*/
+		var RemoteError = class extends Error {
+			code;
+			details;
+			/** Structural marker: cross-realm/bundle identification never uses instanceof. */
+			isDSHRemoteError = true;
+			/**
+			* @param code - stable failure code declared in {@link RemoteErrorDetailsMap}.
+			* @param message - human diagnostic carried across the wire.
+			* @param details - structured payload typed by the code.
+			* @param options - standard Error options (`cause` survives in-process only).
+			*/
+			constructor(code, message, details, options) {
+				super(message, options);
+				this.code = code;
+				this.details = details;
+				this.name = "RemoteError";
+			}
+		};
+		//#endregion
+		//#region ../../typert/protocol/src/index.ts
+		/**
+		* Remote decorators and explicit Gateway bindings backed by versioned
+		* descriptors carried on decorated class prototypes. Strict reflection
+		* remains a Typert compiler responsibility.
+		* @module @deepseek-ai/dsh-typert-protocol
+		*/
+		//#endregion
+		//#region lib/types/client/directory-node.js
+		/** One open directory and its active child nodes; cached view preferences live in the store. */
+		var DirectoryNode = class DirectoryNode {
+			path;
+			load;
+			watch;
+			failed;
+			restore;
+			/** Open direct-child directories, keyed by absolute path. */
+			children = /* @__PURE__ */ new Map();
+			controller = new AbortController();
+			signal;
+			task;
+			reading;
+			dirty = false;
+			initialized = false;
+			automatic = true;
+			constructor(path, load, watch, failed, lifetime, restore = []) {
+				this.path = path;
+				this.load = load;
+				this.watch = watch;
+				this.failed = failed;
+				this.restore = restore;
+				this.signal = AbortSignal.any([lifetime, this.controller.signal]);
+			}
+			/**
+			* Start observation once; readiness triggers the initial listing.
+			* @returns this node.
+			*/
+			open() {
+				this.task ??= this.follow();
+				return this;
+			}
+			/**
+			* Find an active node in this subtree.
+			* @param path - absolute directory path.
+			* @returns the matching node, or undefined when that directory is closed.
+			*/
+			find(path) {
+				if (path === this.path) return this;
+				for (const child of this.children.values()) {
+					const found = child.find(path);
+					if (found !== void 0) return found;
+				}
+			}
+			/**
+			* Update the expansion preferences used by pending directory listings.
+			* @param expanded - latest expansion preferences from the store.
+			*/
+			setExpanded(expanded) {
+				this.restore = expanded;
+				for (const child of this.children.values()) child.setExpanded(expanded);
+			}
+			/**
+			* Open a direct child using this node's lifetime and automatic-refresh setting.
+			* @param path - absolute direct-child directory path.
+			* @param restore - descendant expansion preferences to restore after listing.
+			* @returns the active child, or undefined after cancellation.
+			*/
+			expand(path, restore = []) {
+				if (this.signal.aborted) return void 0;
+				let child = this.children.get(path);
+				if (child === void 0) {
+					child = new DirectoryNode(path, this.load, this.watch, this.failed, this.signal, restore);
+					child.automatic = this.automatic;
+					this.children.set(path, child);
+				}
+				return child.open();
+			}
+			/**
+			* Remove a child and its pending restoration preferences.
+			* @param path - absolute direct-child directory path.
+			* @returns once the child subtree's reads and watches have ended.
+			*/
+			async collapse(path) {
+				this.restore = this.restore.filter((value) => value !== path && !value.startsWith(`${path}/`));
+				const child = this.children.get(path);
+				this.children.delete(path);
+				await child?.close();
+			}
+			/**
+			* Control subtree rereads without ending subscriptions.
+			* @param enabled - refresh dirty nodes automatically.
+			*/
+			setAutomatic(enabled) {
+				this.automatic = enabled;
+				if (enabled && this.dirty) this.refresh();
+				for (const child of this.children.values()) child.setAutomatic(enabled);
+			}
+			/** Queue a reread, coalescing with active work. @returns completion of the active read and its coalesced rereads. */
+			refresh() {
+				this.dirty = true;
+				this.reading ??= this.read();
+				return this.reading;
+			}
+			/** Refresh this node and its open descendants. @returns once their listings settle. */
+			async refreshTree() {
+				await this.refresh();
+				await Promise.all([...this.children.values()].map((child) => child.refreshTree()));
+			}
+			/** Cancel the active subtree. @returns once all owned reads and watches have ended. */
+			async close() {
+				this.controller.abort();
+				await Promise.all([
+					this.task,
+					this.reading,
+					...[...this.children.values()].map((child) => child.close())
+				]);
+				this.children.clear();
+			}
+			async follow() {
+				try {
+					for await (const _event of this.watch(this.path, this.signal)) {
+						this.dirty = true;
+						if (!this.initialized || this.automatic) this.refresh();
+					}
+				} catch (error) {
+					if (!this.signal.aborted) {
+						if (!this.initialized) await this.refresh();
+						if (!(typeof error === "object" && error !== null && "code" in error && error.code === "workspace-file/watch-unsupported")) this.failed(this.path, error);
+					}
+				}
+			}
+			async read() {
+				const readAgain = () => this.dirty && this.automatic && !this.signal.aborted;
+				try {
+					do {
+						this.dirty = false;
+						const level = await this.load(this.path, this.signal);
+						if (this.signal.aborted || level === void 0) return;
+						this.initialized = true;
+						const directories = new Set(level.entries.filter((entry) => entry.type === "directory").map((entry) => `${this.path.replace(/[/\\]+$/, "")}/${entry.name}`));
+						for (const path of this.children.keys()) if (!directories.has(path)) await this.collapse(path);
+						for (const path of directories) if (this.restore.includes(path)) this.expand(path, this.restore);
+						this.restore = [];
+					} while (readAgain());
+				} finally {
+					this.reading = void 0;
+				}
+			}
+		};
+		//#endregion
 		//#region lib/types/client/face.js
 		/**
+		* Bind directory observation to the Remote stream supervisor.
+		* @param remote - Client Remote with workspace file streams.
+		* @returns a watcher that awaits stream disposal when its node ends.
+		*/
+		function createWatch(remote) {
+			return async function* (sessionId, path, signal) {
+				const aborted = () => signal.aborted;
+				if (aborted()) return;
+				const stream = remote.$stream({
+					name: `directory ${path}`,
+					open: (lifetime) => remote.workspaceFiles.changes(sessionId, path, lifetime),
+					ended: () => /* @__PURE__ */ new Error(`Directory watch ended: ${path}`)
+				});
+				const abort = () => {
+					stream.dispose();
+				};
+				signal.addEventListener("abort", abort, { once: true });
+				try {
+					for await (const item of stream) {
+						if (aborted()) return;
+						if (item.value.kind === "ready") item.accept();
+						yield item.value.kind;
+					}
+				} finally {
+					signal.removeEventListener("abort", abort);
+					await stream.dispose();
+				}
+			};
+		}
+		/**
 		* Bind the listing to one Remote face, keeping only what the tree stores.
 		* @param remote - the Client Remote face carrying the `workspaceFiles` namespace.
 		* @returns the listing the tree's face performs.
@@ -76,12 +284,14 @@ window.__ModuleLoader__.load({
 		/**
 		* Bind the tree's face to one directory listing.
 		* @param list - the bound `workspaceFiles.list` call.
+		* @param watch - target-scoped directory observation.
 		* @returns the Slot `inject` factory: session and bound actions in, face out.
 		*/
-		function filesFace(list) {
+		function filesFace(list, watch) {
 			return (sessionId, actions) => {
 				/** Per tab, per absolute path: the listing generation a settlement must match; the latest request wins. */
 				const generations = /* @__PURE__ */ new Map();
+				const roots = /* @__PURE__ */ new Map();
 				const nextGeneration = (tabId, path) => {
 					const byPath = generations.get(tabId) ?? /* @__PURE__ */ new Map();
 					generations.set(tabId, byPath);
@@ -89,29 +299,52 @@ window.__ModuleLoader__.load({
 					byPath.set(path, generation);
 					return generation;
 				};
-				const load = (tabId, path, signal) => {
+				const load = async (tabId, path, signal) => {
 					if (signal.aborted) return;
 					const generation = nextGeneration(tabId, path);
 					actions.loading(tabId, path);
-					list(sessionId, path, signal).then((result) => {
-						if (generations.get(tabId)?.get(path) !== generation) return;
+					return list(sessionId, path, signal).then((result) => {
+						if (signal.aborted || generations.get(tabId)?.get(path) !== generation) return;
 						if (result.ok) actions.loaded(tabId, path, result.value);
 						else actions.failed(tabId, path, result.error);
+						return result.ok ? result.value : void 0;
 					});
 				};
 				return {
+					refresh: (tabId) => {
+						roots.get(tabId)?.refreshTree();
+					},
+					setAutoRefresh: (tabId, enabled) => {
+						actions.autoRefresh(tabId, enabled);
+						roots.get(tabId)?.setAutomatic(enabled);
+					},
 					start(tabId, root, signal) {
 						actions.start(tabId, root);
 						signal.addEventListener("abort", () => {
+							roots.get(tabId)?.close();
+							roots.delete(tabId);
 							generations.delete(tabId);
 							actions.forget(tabId);
 						}, { once: true });
-						load(tabId, root, signal);
+						roots.set(tabId, new DirectoryNode(root, (path, lifetime) => load(tabId, path, lifetime), (path, lifetime) => watch(sessionId, path, lifetime), (path, error) => {
+							if (!signal.aborted) actions.failed(tabId, path, new RemoteError("gateway/internal", error instanceof Error ? error.message : String(error), {}));
+						}, signal).open());
+					},
+					load: (tabId, path, signal) => {
+						load(tabId, path, signal);
 					},
-					load,
-					toggle(tabId, path, loaded, signal) {
+					toggle(tabId, parentPath, path, expanded, signal) {
+						if (signal.aborted) return;
+						const root = roots.get(tabId);
+						if (root === void 0) return;
+						const parent = root.find(parentPath);
+						if (parent === void 0 && !expanded.includes(parentPath)) return;
+						const collapsing = expanded.includes(path);
+						const next = collapsing ? expanded.filter((value) => value !== path) : [...expanded, path];
+						root.setExpanded(next);
+						if (collapsing) parent?.collapse(path);
+						else parent?.expand(path, next);
 						actions.toggled(tabId, path);
-						if (!loaded) load(tabId, path, signal);
 					}
 				};
 			};
@@ -172,27 +405,6 @@ window.__ModuleLoader__.load({
 			return path.startsWith("/") || isWindowsStylePath(path);
 		}
 		/**
-		* Split a path for display: the directories through their last separator, and
-		* the final segment after it. Both `/` and `\` separate, so a Windows path
-		* splits where its own segments end; trailing separators are dropped first, so
-		* a directory path names its own last segment. A path with no separator, or a
-		* separator-only path, is all name.
-		* @param path - file or directory path using POSIX or Windows separators.
-		* @returns the directory prefix (possibly empty) and the final segment.
-		*/
-		function pathPartsOf(path) {
-			const trimmed = path.replace(/[/\\]+$/, "");
-			if (trimmed === "") return {
-				directory: "",
-				name: path
-			};
-			const cut = Math.max(trimmed.lastIndexOf("/"), trimmed.lastIndexOf("\\")) + 1;
-			return {
-				directory: trimmed.slice(0, cut),
-				name: trimmed.slice(cut)
-			};
-		}
-		/**
 		* The address for a path as a caller holds it: a relative path, or an absolute
 		* path inside the Session's workspace, becomes a `session`-scoped address; an
 		* absolute path outside it, or one whose workspace root is unknown, keeps its
@@ -212,7 +424,7 @@ window.__ModuleLoader__.load({
 		}
 		//#endregion
 		//#region \0dsh-css:/home/runner/work/deepseek-harness/deepseek-harness/packages/client/ui-sidebar-files/src/client/FilesBody.module.css.mjs
-		const css = ".k-1LKG_root{height:100%;min-height:0;color:var(--dsw-alias-label-primary);font-size:var(--dsh-content-font-size-secondary,13px);flex-direction:column;flex:auto;line-height:1.5;display:flex}.k-1LKG_header{box-sizing:border-box;border-bottom:.5px solid var(--dsw-alias-border-l3);flex:none;align-items:center;gap:4px;height:38px;padding:0 6px 0 16px;display:flex}.k-1LKG_path{white-space:nowrap;flex:auto;justify-content:flex-end;min-width:0;margin-right:12px;font-size:12px;display:flex;overflow:hidden}.k-1LKG_path[data-files-path-clipped]{mask-image:linear-gradient(90deg,#0000,#000 28px)}.k-1LKG_pathText{flex:none;margin-right:auto}.k-1LKG_pathDirectory{color:var(--dsw-alias-label-tertiary)}.k-1LKG_pathName{color:var(--dsw-alias-label-primary)}.k-1LKG_body{scrollbar-gutter:stable;flex:auto;min-height:0;margin-right:2px;padding:8px 0 8px 8px;overflow:auto}.k-1LKG_body::-webkit-scrollbar-track{margin:2px}.k-1LKG_level{margin:0;padding:0;list-style:none}.k-1LKG_level .k-1LKG_level{padding-left:18px}.k-1LKG_item{margin:0;padding:0}.k-1LKG_row{width:100%;min-width:0;color:inherit;font:inherit;text-align:left;cursor:pointer;background:0 0;border:0;border-radius:10px;align-items:center;gap:6px;padding:5px 10px;display:flex}.k-1LKG_row:hover{background:var(--dsw-alias-interactive-bg-hover)}.k-1LKG_icon{color:var(--dsw-alias-label-tertiary);flex:none}.k-1LKG_fileIcon{flex:none}.k-1LKG_name{white-space:nowrap;text-overflow:ellipsis;min-width:0;overflow:hidden}.k-1LKG_other{color:var(--dsw-alias-label-tertiary);cursor:default}.k-1LKG_other:hover{background:0 0}.k-1LKG_note{color:var(--dsw-alias-label-tertiary);margin:0;padding:3px 10px;font-size:12px}.k-1LKG_status{flex-direction:column;padding:12px 10px;display:flex}.k-1LKG_statusLine{color:var(--dsw-alias-label-secondary);font-size:var(--dsh-content-font-size-secondary,13px);margin:0;line-height:1.6}.k-1LKG_tool{width:28px;height:28px;color:var(--dsw-alias-label-secondary);cursor:pointer;background:0 0;border:none;border-radius:28px;flex:none;justify-content:center;align-items:center;padding:6px;line-height:1;display:inline-flex}.k-1LKG_tool svg{width:15px;height:15px}.k-1LKG_tool:hover{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover)}.k-1LKG_titleIcon{flex:none}";
+		const css = ".k-1LKG_root{height:100%;min-height:0;color:var(--dsw-alias-label-primary);font-size:var(--dsh-content-font-size-secondary,13px);flex-direction:column;flex:auto;line-height:1.5;display:flex}.k-1LKG_header{box-sizing:border-box;border-bottom:.5px solid var(--dsw-alias-border-l3);flex:none;align-items:center;gap:4px;height:38px;padding:0 6px 0 16px;display:flex}.k-1LKG_path{margin-right:12px}.k-1LKG_body{scrollbar-gutter:stable;flex:auto;min-height:0;margin-right:2px;padding:8px 0 8px 8px;overflow:auto}.k-1LKG_body::-webkit-scrollbar-track{margin:2px}.k-1LKG_level{margin:0;padding:0;list-style:none}.k-1LKG_level .k-1LKG_level{padding-left:18px}.k-1LKG_item{margin:0;padding:0}.k-1LKG_row{width:100%;min-width:0;color:inherit;font:inherit;text-align:left;cursor:pointer;background:0 0;border:0;border-radius:10px;align-items:center;gap:6px;padding:5px 10px;display:flex}.k-1LKG_row:hover{background:var(--dsw-alias-interactive-bg-hover)}.k-1LKG_icon{color:var(--dsw-alias-label-tertiary);flex:none}.k-1LKG_fileIcon{flex:none}.k-1LKG_name{white-space:nowrap;text-overflow:ellipsis;min-width:0;overflow:hidden}.k-1LKG_other{color:var(--dsw-alias-label-tertiary);cursor:default}.k-1LKG_other:hover{background:0 0}.k-1LKG_note{color:var(--dsw-alias-label-tertiary);margin:0;padding:3px 10px;font-size:12px}.k-1LKG_status{flex-direction:column;padding:12px 10px;display:flex}.k-1LKG_statusLine{color:var(--dsw-alias-label-secondary);font-size:var(--dsh-content-font-size-secondary,13px);margin:0;line-height:1.6}.k-1LKG_tool{width:28px;height:28px;color:var(--dsw-alias-label-secondary);cursor:pointer;background:0 0;border:none;border-radius:28px;flex:none;justify-content:center;align-items:center;padding:6px;line-height:1;display:inline-flex}.k-1LKG_tool svg{width:15px;height:15px}.k-1LKG_tool:hover,.k-1LKG_tool[aria-pressed=true]{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover)}.k-1LKG_titleIcon{flex:none}";
 		const tagId = "@deepseek-ai/dsh-client-ui-sidebar-files/FilesBody.module.css";
 		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
 			const tag = document.createElement("style");
@@ -232,9 +444,6 @@ window.__ModuleLoader__.load({
 			"note": "k-1LKG_note",
 			"other": "k-1LKG_other",
 			"path": "k-1LKG_path",
-			"pathDirectory": "k-1LKG_pathDirectory",
-			"pathName": "k-1LKG_pathName",
-			"pathText": "k-1LKG_pathText",
 			"root": "k-1LKG_root",
 			"row": "k-1LKG_row",
 			"status": "k-1LKG_status",
@@ -251,10 +460,8 @@ window.__ModuleLoader__.load({
 		* for goes through its injected face. The component itself only decides what to
 		* draw for each absolute path and what a click means: a directory toggles, a
 		* file opens through the owner's `tabActions` for a `file:` viewer to claim, and
-		* anything else is shown but refuses to open. The header row is the text
-		* preview's: the root's path, directories greyed and the last segment in full
-		* ink, then the one control at its end, reload, which drops every listed level
-		* and asks again for the expanded ones.
+		* anything else is shown but refuses to open. The header uses the shared
+		* PathLabel for the root, followed by reload for the expanded directories.
 		*/
 		/** Natural, case-insensitive name order, so `file2` precedes `file10`. */
 		const byName = new Intl.Collator(void 0, {
@@ -288,35 +495,6 @@ window.__ModuleLoader__.load({
 				default: return t("error.unavailable", { message: failure.message });
 			}
 		}
-		/**
-		* Keep the path row's `data-files-path-clipped` current: set while the path's
-		* text is wider than its box, so the stylesheet fades the clipped start. Read
-		* after each commit that can change the path or mount the header, and whenever
-		* either box resizes; written to the DOM directly because it changes only how
-		* the stylesheet fades what is already rendered.
-		*/
-		function usePathClipped(box, text, path) {
-			(0, react.useLayoutEffect)(() => {
-				const outer = box.current;
-				const inner = text.current;
-				if (outer === null || inner === null) return void 0;
-				const apply = () => {
-					if (inner.offsetWidth > outer.clientWidth) outer.dataset.filesPathClipped = "";
-					else delete outer.dataset.filesPathClipped;
-				};
-				apply();
-				const observer = typeof ResizeObserver === "undefined" ? void 0 : new ResizeObserver(apply);
-				observer?.observe(outer);
-				observer?.observe(inner);
-				return () => {
-					observer?.disconnect();
-				};
-			}, [
-				box,
-				text,
-				path
-			]);
-		}
 		/** One entry's row, and its children when it is an expanded directory. */
 		function Entry({ parent, entry, tree }) {
 			const path = childPath(parent, entry.name);
@@ -331,9 +509,9 @@ window.__ModuleLoader__.load({
 						className: FilesBody_module_css_default.row,
 						"aria-expanded": expanded,
 						onClick: () => {
-							tree.onToggle(path);
+							tree.onToggle(parent, path);
 						},
-						children: [expanded ? (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconFolderOpen16, { className: FilesBody_module_css_default.icon }) : (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconFolderClose16, { className: FilesBody_module_css_default.icon }), (0, react_jsx_runtime.jsx)("span", {
+						children: [expanded ? (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconFolderOpenRegular, { className: FilesBody_module_css_default.icon }) : (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconFolderCloseRegular, { className: FilesBody_module_css_default.icon }), (0, react_jsx_runtime.jsx)("span", {
 							className: FilesBody_module_css_default.name,
 							children: entry.name
 						})]
@@ -398,6 +576,11 @@ window.__ModuleLoader__.load({
 			});
 			const entries = orderEntries(level.level.entries);
 			return (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
+				level.failure !== void 0 && (0, react_jsx_runtime.jsx)("li", {
+					className: FilesBody_module_css_default.note,
+					"data-files-row": "failed",
+					children: failureLine(t, level.failure)
+				}),
 				entries.length === 0 && (0, react_jsx_runtime.jsx)("li", {
 					className: FilesBody_module_css_default.note,
 					"data-files-row": "empty",
@@ -416,16 +599,13 @@ window.__ModuleLoader__.load({
 			] });
 		}
 		/** The file tree's body: the workspace root and whatever the reader has opened under it. */
-		function FilesBody({ useTabInfo, sessionId, useSessions, useStore, actions, start, load, toggle, t }) {
+		function FilesBody({ useTabInfo, sessionId, useSessions, useStore, actions, start, refresh, setAutoRefresh, toggle, t }) {
 			const { tab } = useTabInfo();
 			const { signal, actions: tabActions } = tab;
 			const cwd = useSessions((sessions) => sessions.byId[sessionId]?.cwd);
 			const state = useStore((store) => store.byTab[tab.id]);
-			const pathRef = (0, react.useRef)(null);
-			const pathTextRef = (0, react.useRef)(null);
 			const bodyRef = (0, react.useRef)(null);
 			const scrollTopRef = (0, react.useRef)(0);
-			usePathClipped(pathRef, pathTextRef, state?.root);
 			const seeded = state !== void 0;
 			(0, react.useLayoutEffect)(() => {
 				const body = bodyRef.current;
@@ -463,8 +643,8 @@ window.__ModuleLoader__.load({
 			if (state === void 0) return null;
 			const tree = {
 				state,
-				onToggle: (path) => {
-					toggle(tab.id, path, state.levels[path] !== void 0, signal);
+				onToggle: (parent, path) => {
+					toggle(tab.id, parent, path, state.expanded, signal);
 				},
 				onOpen: (path) => {
 					tabActions.openResource(fileAddressFor(sessionId, state.root, path));
@@ -472,41 +652,45 @@ window.__ModuleLoader__.load({
 				t
 			};
 			const reload = () => {
-				actions.reset(tab.id);
-				for (const path of state.expanded) load(tab.id, path, signal);
+				refresh(tab.id);
 			};
-			const { directory, name } = pathPartsOf(state.root);
 			return (0, react_jsx_runtime.jsxs)("div", {
 				className: FilesBody_module_css_default.root,
 				"data-files-state": "tree",
 				"data-files-root": state.root,
 				children: [(0, react_jsx_runtime.jsxs)("div", {
 					className: FilesBody_module_css_default.header,
-					children: [(0, react_jsx_runtime.jsx)("div", {
-						ref: pathRef,
-						className: FilesBody_module_css_default.path,
-						title: state.root,
-						"data-files-path": true,
-						children: (0, react_jsx_runtime.jsxs)("span", {
-							ref: pathTextRef,
-							className: FilesBody_module_css_default.pathText,
-							children: [directory !== "" && (0, react_jsx_runtime.jsx)("span", {
-								className: FilesBody_module_css_default.pathDirectory,
-								children: directory
-							}), (0, react_jsx_runtime.jsx)("span", {
-								className: FilesBody_module_css_default.pathName,
-								children: name
-							})]
+					children: [
+						(0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.PathLabel, {
+							path: state.root,
+							className: FilesBody_module_css_default.path,
+							"data-files-path": true
+						}),
+						(0, react_jsx_runtime.jsx)("span", {
+							hidden: true,
+							children: (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								className: FilesBody_module_css_default.tool,
+								"aria-label": t("autoRefresh"),
+								"aria-pressed": state.autoRefresh,
+								"data-files-auto-refresh": true,
+								title: t(state.autoRefresh ? "autoRefresh.disable" : "autoRefresh.enable"),
+								onClick: () => {
+									setAutoRefresh(tab.id, !state.autoRefresh);
+								},
+								children: state.autoRefresh ? (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconPauseOutlineRegular, {}) : (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconPlayOutlineRegular, {})
+							})
+						}),
+						(0, react_jsx_runtime.jsx)("button", {
+							type: "button",
+							className: FilesBody_module_css_default.tool,
+							"aria-label": t("reload"),
+							title: t("reload"),
+							"data-files-reload": true,
+							onClick: reload,
+							children: (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconRefreshOutlineRegular, {})
 						})
-					}), (0, react_jsx_runtime.jsx)("button", {
-						type: "button",
-						className: FilesBody_module_css_default.tool,
-						"aria-label": t("reload"),
-						title: t("reload"),
-						"data-files-reload": true,
-						onClick: reload,
-						children: (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconRefreshOutline16, {})
-					})]
+					]
 				}), (0, react_jsx_runtime.jsx)("div", {
 					ref: bodyRef,
 					className: FilesBody_module_css_default.body,
@@ -551,6 +735,9 @@ window.__ModuleLoader__.load({
 			truncated: "条目太多，只显示了一部分。",
 			noWorkspace: "这个会话没有工作区目录。",
 			reload: "重新读取",
+			autoRefresh: "自动刷新",
+			"autoRefresh.enable": "开启自动刷新",
+			"autoRefresh.disable": "关闭自动刷新",
 			"entry.other": "这不是文件或目录，没法打开。",
 			"error.notFound": "这个目录不在了。可能已被移动或删除。",
 			"error.outsideWorkspace": "这个目录在工作区之外，侧栏不会读取它。",
@@ -567,6 +754,9 @@ window.__ModuleLoader__.load({
 			truncated: "Too many entries, showing only some of them.",
 			noWorkspace: "This session has no workspace directory.",
 			reload: "Reload",
+			autoRefresh: "Auto refresh",
+			"autoRefresh.enable": "Enable auto refresh",
+			"autoRefresh.disable": "Disable auto refresh",
 			"entry.other": "Not a file or a directory, so it cannot be opened.",
 			"error.notFound": "That directory is gone. It may have been moved or deleted.",
 			"error.outsideWorkspace": "That directory is outside the workspace, so the sidebar will not read it.",
@@ -610,6 +800,9 @@ window.__ModuleLoader__.load({
 			return (0, _deepseek_ai_dsh_client_store.defineStore)({
 				init: () => ({ byTab: {} }),
 				actions: {
+					autoRefresh: (d, tabId, enabled) => {
+						bucket(d, tabId).autoRefresh = enabled;
+					},
 					/**
 					* Seed one tab's tree at its workspace root, with the root expanded.
 					* @param d - draft state.
@@ -621,7 +814,8 @@ window.__ModuleLoader__.load({
 							root,
 							levels: {},
 							expanded: [root],
-							scrollTop: 0
+							scrollTop: 0,
+							autoRefresh: true
 						};
 					},
 					/**
@@ -631,7 +825,8 @@ window.__ModuleLoader__.load({
 					* @param path - absolute directory path.
 					*/
 					loading: (d, tabId, path) => {
-						bucket(d, tabId).levels[path] = { kind: "loading" };
+						const state = bucket(d, tabId);
+						if (state.levels[path]?.kind !== "ready") state.levels[path] = { kind: "loading" };
 					},
 					/**
 					* Record one directory's contents.
@@ -641,7 +836,18 @@ window.__ModuleLoader__.load({
 					* @param level - the listing to show under it.
 					*/
 					loaded: (d, tabId, path, level) => {
-						bucket(d, tabId).levels[path] = {
+						const state = bucket(d, tabId);
+						const previous = state.levels[path];
+						if (previous?.kind === "ready") {
+							const directories = new Set(level.entries.filter((entry) => entry.type === "directory").map((entry) => entry.name));
+							for (const entry of previous.level.entries) {
+								if (entry.type !== "directory" || directories.has(entry.name)) continue;
+								const removed = `${path.replace(/[/\\]+$/, "")}/${entry.name}`;
+								state.expanded = state.expanded.filter((value) => value !== removed && !value.startsWith(`${removed}/`));
+								state.levels = Object.fromEntries(Object.entries(state.levels).filter(([key]) => key !== removed && !key.startsWith(`${removed}/`)));
+							}
+						}
+						state.levels[path] = {
 							kind: "ready",
 							level
 						};
@@ -654,7 +860,11 @@ window.__ModuleLoader__.load({
 					* @param failure - the settled Remote failure.
 					*/
 					failed: (d, tabId, path, failure) => {
-						bucket(d, tabId).levels[path] = {
+						const level = bucket(d, tabId).levels[path];
+						bucket(d, tabId).levels[path] = level?.kind === "ready" ? {
+							...level,
+							failure
+						} : {
 							kind: "failed",
 							failure
 						};
@@ -731,7 +941,7 @@ window.__ModuleLoader__.load({
 				en
 			}), "ui-sidebar-files: dictionaries");
 			const store = createFilesStore();
-			const inject = filesFace(createList(ctx.remote));
+			const inject = filesFace(createList(ctx.remote), createWatch(ctx.remote));
 			ctx.effect(() => ctx.slots.inject("sidebar.right.pane.tab", () => ctx.slots.register({
 				name: "sidebar.right.pane.tab",
 				key: FILES_ID,

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

@@ -22,5 +22,5 @@ export declare function orderEntries(entries: readonly WorkspaceDirectoryEntry[]
  */
 export declare function failureLine(t: TranslateNS<'sidebarFiles'>, failure: RemoteFailure): string;
 /** The file tree's body: the workspace root and whatever the reader has opened under it. */
-export declare function FilesBody({ useTabInfo, sessionId, useSessions, useStore, actions, start, load, toggle, t, }: FilesBodyProps): ReactNode;
+export declare function FilesBody({ useTabInfo, sessionId, useSessions, useStore, actions, start, refresh, setAutoRefresh, toggle, t, }: FilesBodyProps): ReactNode;
 //# sourceMappingURL=FilesBody.d.ts.map

package/lib/types/client/directory-node.d.ts

@@ -0,0 +1,63 @@
+/** Watch and read ownership for the Files panel's expanded directory tree. */
+import type { DirLevel } from './store.ts';
+/** One open directory and its active child nodes; cached view preferences live in the store. */
+export declare class DirectoryNode {
+    readonly path: string;
+    private readonly load;
+    private readonly watch;
+    private readonly failed;
+    private restore;
+    /** Open direct-child directories, keyed by absolute path. */
+    readonly children: Map<string, DirectoryNode>;
+    private readonly controller;
+    private readonly signal;
+    private task;
+    private reading;
+    private dirty;
+    private initialized;
+    private automatic;
+    constructor(path: string, load: (path: string, signal: AbortSignal) => Promise<DirLevel | undefined>, watch: (path: string, signal: AbortSignal) => AsyncIterable<'ready' | 'change'>, failed: (path: string, error: unknown) => void, lifetime: AbortSignal, restore?: readonly string[]);
+    /**
+     * Start observation once; readiness triggers the initial listing.
+     * @returns this node.
+     */
+    open(): this;
+    /**
+     * Find an active node in this subtree.
+     * @param path - absolute directory path.
+     * @returns the matching node, or undefined when that directory is closed.
+     */
+    find(path: string): DirectoryNode | undefined;
+    /**
+     * Update the expansion preferences used by pending directory listings.
+     * @param expanded - latest expansion preferences from the store.
+     */
+    setExpanded(expanded: readonly string[]): void;
+    /**
+     * Open a direct child using this node's lifetime and automatic-refresh setting.
+     * @param path - absolute direct-child directory path.
+     * @param restore - descendant expansion preferences to restore after listing.
+     * @returns the active child, or undefined after cancellation.
+     */
+    expand(path: string, restore?: readonly string[]): DirectoryNode | undefined;
+    /**
+     * Remove a child and its pending restoration preferences.
+     * @param path - absolute direct-child directory path.
+     * @returns once the child subtree's reads and watches have ended.
+     */
+    collapse(path: string): Promise<void>;
+    /**
+     * Control subtree rereads without ending subscriptions.
+     * @param enabled - refresh dirty nodes automatically.
+     */
+    setAutomatic(enabled: boolean): void;
+    /** Queue a reread, coalescing with active work. @returns completion of the active read and its coalesced rereads. */
+    refresh(): Promise<void>;
+    /** Refresh this node and its open descendants. @returns once their listings settle. */
+    refreshTree(): Promise<void>;
+    /** Cancel the active subtree. @returns once all owned reads and watches have ended. */
+    close(): Promise<void>;
+    private follow;
+    private read;
+}
+//# sourceMappingURL=directory-node.d.ts.map

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

@@ -1,7 +1,7 @@
 /**
  * The tree's asynchronous half: listing directories into the store.
  *
- * The component never awaits anything. It calls `start` / `load` / `toggle`, and
+ * The component never awaits anything. It calls `start` / `refresh` / `toggle`, and
  * this face performs the listing and writes the outcome through the store's own
  * actions — the Slot-standard `inject` shape, so the session id is resolved by
  * the framework and the write set stays the store's.
@@ -23,6 +23,20 @@ import type { BoundActions } from '@deepseek-ai/dsh-client-store';
 import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit';
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
 import type { DirLevel, createFilesStore } from './store.ts';
+/**
+ * Observe one directory without recursively watching its descendants.
+ * @param sessionId - Session owning the directory tree.
+ * @param path - absolute directory path.
+ * @param signal - node lifetime.
+ * @returns readiness and invalidation notifications.
+ */
+export type WatchWorkspaceDirectory = (sessionId: SessionId, path: string, signal: AbortSignal) => AsyncIterable<'ready' | 'change'>;
+/**
+ * Bind directory observation to the Remote stream supervisor.
+ * @param remote - Client Remote with workspace file streams.
+ * @returns a watcher that awaits stream disposal when its node ends.
+ */
+export declare function createWatch(remote: ClientRemote): WatchWorkspaceDirectory;
 /**
  * One directory listing, bound to a Remote face.
  *
@@ -56,6 +70,10 @@ export declare function createList(remote: WorkspaceFilesListRemote): ListWorksp
 export declare function childPath(parent: string, name: string): string;
 /** The tree's injected business face, as the body receives it. */
 export interface FilesInjected {
+    /** Refresh the open directory tree. @param tabId - owning tab. */
+    readonly refresh: (tabId: TabId) => void;
+    /** Control automatic rereads without closing watches. @param tabId - owning tab. @param enabled - automatic-refresh setting. */
+    readonly setAutoRefresh: (tabId: TabId, enabled: boolean) => void;
     /**
      * Seed this tab's tree and list its root.
      * @param tabId - the tab being drawn.
@@ -71,18 +89,20 @@ export interface FilesInjected {
      */
     readonly load: (tabId: TabId, path: string, signal: AbortSignal) => void;
     /**
-     * Open or collapse one directory, listing it the first time it opens.
+     * Open or collapse one directory, retaining intent during ancestor restoration.
      * @param tabId - the tab being drawn.
+     * @param parentPath - the listed parent directory's exact tree key.
      * @param path - absolute directory path.
-     * @param loaded - whether this level already has state.
+     * @param expanded - current expansion preferences, including descendants to restore.
      * @param signal - the tab record's lifetime.
      */
-    readonly toggle: (tabId: TabId, path: string, loaded: boolean, signal: AbortSignal) => void;
+    readonly toggle: (tabId: TabId, parentPath: string, path: string, expanded: readonly string[], signal: AbortSignal) => void;
 }
 /**
  * Bind the tree's face to one directory listing.
  * @param list - the bound `workspaceFiles.list` call.
+ * @param watch - target-scoped directory observation.
  * @returns the Slot `inject` factory: session and bound actions in, face out.
  */
-export declare function filesFace(list: ListWorkspaceDirectory): (sessionId: SessionId, actions: BoundActions<ReturnType<typeof createFilesStore>>) => FilesInjected;
+export declare function filesFace(list: ListWorkspaceDirectory, watch: WatchWorkspaceDirectory): (sessionId: SessionId, actions: BoundActions<ReturnType<typeof createFilesStore>>) => FilesInjected;
 //# sourceMappingURL=face.d.ts.map

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

@@ -14,6 +14,9 @@ export declare const zh: {
     truncated: string;
     noWorkspace: string;
     reload: string;
+    autoRefresh: string;
+    'autoRefresh.enable': string;
+    'autoRefresh.disable': string;
     'entry.other': string;
     'error.notFound': string;
     'error.outsideWorkspace': string;
@@ -32,6 +35,9 @@ export declare const en: {
     truncated: string;
     noWorkspace: string;
     reload: string;
+    autoRefresh: string;
+    'autoRefresh.enable': string;
+    'autoRefresh.disable': string;
     'entry.other': string;
     'error.notFound': string;
     'error.outsideWorkspace': string;

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

@@ -32,6 +32,7 @@ export type LevelState = {
 } | {
     readonly kind: 'ready';
     readonly level: DirLevel;
+    readonly failure?: RemoteFailure;
 } | {
     readonly kind: 'failed';
     readonly failure: RemoteFailure;
@@ -43,6 +44,7 @@ export type LevelState = {
  * the Host reports it, and a child is the parent joined with the entry name.
  */
 export interface FilesTabState {
+    autoRefresh: boolean;
     /** Absolute path of the workspace root this tree is rooted at. */
     root: string;
     /** Level state by absolute directory path; a path absent here was never asked for. */
@@ -58,6 +60,7 @@ export interface FilesState {
 }
 /** The tree store's write set; every action names the tab it writes. */
 type FilesActions = {
+    autoRefresh: (draft: FilesState, tabId: TabId, enabled: boolean) => void;
     start: (draft: FilesState, tabId: TabId, root: string) => void;
     loading: (draft: FilesState, tabId: TabId, path: string) => void;
     loaded: (draft: FilesState, tabId: TabId, path: string, level: DirLevel) => void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-sidebar-files",
   "description": "Workspace file tree tab type for the right Sidebar: lazy directory listing over the workspaceFiles Remote namespace, opening files into the Sidebar",
-  "version": "0.1.6-alpha.2",
+  "version": "0.1.7-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -38,7 +38,7 @@
   },
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "~4.0.4"
   },
   "devDependencies": {
     "@testing-library/react": "^16.1.0",
@@ -47,20 +47,21 @@
     "react": "^18.2.0",
     "clsx": "^2.0.0",
     "react-dom": "^18.2.0",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-api-remotes": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-store": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-test-runtime": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-api-workspace-files": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-ui-dockkit": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-locale": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-ui-session": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-ui-sidebar-right": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-util-workspace-path": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.6-alpha.2"
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-api-workspace-files": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-locale": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-store": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-test-runtime": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-ui-dockkit": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-api-remotes": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-ui-session": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-session": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-util-workspace-path": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.1.7-alpha.2"
   },
   "files": [
     "lib/index.js",