+
{scroll.initialized && (
{
- if (this.state.followingTail && !scroll.movedByReader) {
+ if ((!scroll.movedByReader && this.state.followingTail)
+ || (scroll.movedByReader && scroll.metrics.top >= scroll.metrics.floor)) {
this.followTail()
- this.sampled?.({ position: null, movedByReader: false, followingTail: true })
+ this.sampled?.({ position: null, movedByReader: scroll.movedByReader, followingTail: true })
return
}
this.sampleTimer ??= window.setTimeout(this.flushSample, SCROLL_SAMPLE_INTERVAL_MS)
diff --git a/packages/client/ui-chat/tests/chat-view.client.spec.tsx b/packages/client/ui-chat/tests/chat-view.client.spec.tsx
index 2e0bf9545b..2c71fa1092 100644
--- a/packages/client/ui-chat/tests/chat-view.client.spec.tsx
+++ b/packages/client/ui-chat/tests/chat-view.client.spec.tsx
@@ -2430,6 +2430,7 @@ describe('ChatView', () => {
readerScroll(scroller, 100) // far from bottom
const backButton = view.getByLabelText('回到底部')
expect(backButton).toBeTruthy()
+ expect(view.container.querySelector('[data-chat-following-tail]')).toBeNull()
// Streaming growth must NOT drag a scrolled-away reader down.
act(() => {
h.setChat({ partial: { turn: 1, step: 1, blocks: [{ kind: 'text', text: 'grow' }] } })
@@ -2437,6 +2438,7 @@ describe('ChatView', () => {
expect(scroller.scrollTop).toBe(100)
fireEvent.click(backButton)
expect(scroller.scrollTop).toBe(700)
+ expect(view.container.querySelector('[data-chat-following-tail]')).not.toBeNull()
// At the bottom again: follow re-arms and the button unmounts.
expect(view.queryByLabelText('回到底部')).toBeNull()
})
@@ -2555,6 +2557,25 @@ describe('ChatView', () => {
expect(scroller.scrollTop).toBe(680)
})
+ it('keeps following when reader input reaches the floor before growth and scrollend', () => {
+ const h = makeHarness({ nodes: [user(1, 'q'), assistant(2, 'a')] })
+ const view = render(` for `{ kind: 'bytes', data }`. The Host's `maxFileBytes` cap rejects oversized files rather than truncating them. PDF copies retained bytes before worker transfer, keeping the Preview buffer usable. Bytes stay in transient view state, never persisted layouts or Session JSONL. Loading-mode changes retire previous results.
-- **Reload** — only the current Preview tab rereads through its Remote callbacks, preserving its scroll preference and retiring older requests. Its change notice compares the read version and the observation captured at read start with later `resource.value.version`; an already observed version does not become a new change after refresh. Reads neither refresh shared metadata nor clear another tab's notice.
+- **Reload** — manual reload rereads only the current Preview tab through its Remote callbacks, preserving its scroll preference and retiring older requests. Automatic refresh uses the same callbacks after a ResourceGroup member changes. Each member's first metadata establishes a baseline without triggering reload or first-read version reconciliation; later changes received during a read remain pending for another refresh. Reads neither refresh shared metadata nor clear another tab's notice.
-When Developer tools is enabled, HTML fills the body edge to edge in a Blob iframe with exactly `sandbox="allow-scripts"`, without `allow-same-origin`; scripts cannot access the parent application's origin or file reader. The renderer loads directly declared relative `.js` classic scripts and `.css` stylesheets through its ordinary inject callback to `remote.workspaceFiles.readRelated`, with fixed safety limits of 4 MiB per asset, 32 MiB total, and 64 distinct assets. Host code resolves the related path; `rpc.ts` decodes the returned bytes. Inside the renderer, base64 is used only to embed the iframe bootstrap payload in script text. A `![]()
` static-image context, rounded inside a 12px inset. A wider image scales down to the pane's width at its intrinsic aspect ratio, a smaller image centres at its intrinsic CSS-pixel dimensions, and a taller image scrolls vertically. The renderer provides neither zoom nor drag-to-pan. SVG markup never enters the application DOM or an iframe, so its scripts cannot execute or reach the parent page. Replacing or unmounting the image revokes its Blob URL.
diff --git a/packages/client/ui-sidebar-documentpreview/README.zh.md b/packages/client/ui-sidebar-documentpreview/README.zh.md
index 05eefb854b..6e40ceca2f 100644
--- a/packages/client/ui-sidebar-documentpreview/README.zh.md
+++ b/packages/client/ui-sidebar-documentpreview/README.zh.md
@@ -9,7 +9,7 @@ kind: "package-reference"
## 概述
-在右侧 Sidebar 预览文件，并切换已注册的渲染器。Markdown 和代码支持分页文本；PDF、HTML 和常见图片接收完整字节；未知扩展名使用纯文本。Office 文档在本地转换为 PDF。tab 提供文件状态、渲染器选择、换行和重新载入。插件可在头部和不支持预览的空态中添加本地打开控件。
+在右侧 Sidebar 预览文件，并切换已注册的渲染器。Markdown 和代码支持分页文本；PDF、HTML 和常见图片接收完整字节；未知扩展名使用纯文本。Office 文档在本地转换为 PDF。tab 提供文件状态、渲染器选择、换行以及自动或手动重新载入。插件可在头部和不支持预览的空态中添加本地打开控件。
## 目录
@@ -28,12 +28,12 @@ kind: "package-reference"
## 注册了什么
- **类型** —— `ctx.sidebarRightTabs.register(...)`，id 为 `@deepseek-ai/dsh-client-ui-sidebar-documentpreview`（这个实现在 tab 系统中的身份，也是其正文注册所用的键），kind `text`，pattern `dsh-resource://file/**`，档位 `fallback`。`canOpen` 只接受 Session 地址，其中路径可为相对或绝对路径；不认领裸 `absolute` 地址。在 `extension` 或 `builtin` 档以更窄 pattern（比如 `*.png`）注册的类型接走那些地址；其他受支持文件落到这里。整个地址就是内容身份，所以不同目录下同名的两个文件、或同一路径在两个会话之下，是两个 tab；解码后的 basename 是 tab 标题，keyed slot `sidebar.right.pane.tab.title` 会在标题前放置按扩展名选择的 `FileTypeIcon`。
-- **正文** —— keyed slot `sidebar.right.pane.tab`，键为类型的 id。固定头部在可用时显示 Host 的绝对路径，否则显示请求路径；目录使用三级标签色，文件名使用一级标签色，路径过长时保留末段并向开头淡出，提示中仍提供完整值。有多个受支持的渲染器时才显示下拉菜单。仅文本兼容的源文件提供纯文本选项；只有一个渲染器时不显示查看器控件。已知的二进制容器后缀没有注册渲染器时，在路径头部下方显示文件类型图标和不支持预览的说明，并且不会发起读取。两个 Session 作用域的 list 子 slot 在文件元数据报出 Host 路径后把当前文件交给其他插件，owner prop 为 `absolutePath`：`sidebar.right.tab.document.actions` 在每个显示头部的状态里渲染在头部自有控件之后；`sidebar.right.tab.document.unpreviewable` 渲染在不支持预览的空态里，以及可读但本预览无法渲染的文件（`not-text`、`too-large`）的空态里，占据原本放重试的位置；载体或未分类的读取失败仍保留重试，不存在或非普通文件的路径只给说明。两者已发布的占位者都是 [`ui-open-in-app`](../ui-open-in-app/README.zh.md)。仅当所选渲染器声明 `wrap: true` 时显示换行开关；图标表示点击后切换到的模式，该偏好按 tab 保存，初始开启。重新载入仍在此头部，不放入 Sidebar 的 tab 条。正文贴合格的每条边，各渲染器自行提供内容留白，并可拥有内部滚动区。这与 Files tab 右侧预留 2px 滚动条间距的布局有意不同：Preview 使用格的完整宽度，使贴边 HTML 与代码滚动区终止于格的边缘。
-- **共享加载与视图状态**，会话作用域、按 tab id 分桶。store 持有累计页或完整字节、读取与观察版本、加载/失败状态、渲染器选择、滚动位置、换行和已响应的导航 revision。普通 inject face 调用 Remote 读取，并经声明的 store action 写入。重新载入和加载模式变化会淘汰旧请求；tab 的中止信号清理其状态。
+- **正文** —— keyed slot `sidebar.right.pane.tab`，键为类型的 id。固定头部在可用时显示 Host 的绝对路径，否则显示请求路径；目录使用三级标签色，文件名使用一级标签色，路径过长时保留末段并向开头淡出，提示中仍提供完整值。有多个受支持的渲染器时才显示下拉菜单。仅文本兼容的源文件提供纯文本选项；只有一个渲染器时不显示查看器控件。已知的二进制容器后缀没有注册渲染器时，在路径头部下方显示文件类型图标和不支持预览的说明，并且不会发起读取。两个 Session 作用域的 list 子 slot 在文件元数据报出 Host 路径后把当前文件交给其他插件，owner prop 为 `absolutePath`：`sidebar.right.tab.document.actions` 在每个显示头部的状态里渲染在头部自有控件之后；`sidebar.right.tab.document.unpreviewable` 渲染在不支持预览的空态里，以及可读但本预览无法渲染的文件（`not-text`、`too-large`）的空态里，占据原本放重试的位置；载体或未分类的读取失败仍保留重试，不存在或非普通文件的路径只给说明。两者已发布的占位者都是 [`ui-open-in-app`](../ui-open-in-app/README.zh.md)。仅当所选渲染器声明 `wrap: true` 时显示换行开关；图标表示点击后切换到的模式，该偏好按 tab 保存，初始开启。重新载入仍在此头部，不放入 Sidebar 的 tab 条。自动刷新默认开启；独立开关暂时隐藏，状态、文案、样式与切换逻辑保留。正文贴合格的每条边，各渲染器自行提供内容留白，并可拥有内部滚动区。这与 Files tab 右侧预留 2px 滚动条间距的布局有意不同：Preview 使用格的完整宽度，使贴边 HTML 与代码滚动区终止于格的边缘。
+- **共享加载与视图状态**，会话作用域、按 tab id 分桶。store 持有累计页或完整字节、读取与观察版本、待处理 Resource 变化、自动刷新状态、加载/失败状态、渲染器选择、滚动位置、换行和已响应的导航 revision。普通 inject face 调用 Remote 读取，并经声明的 store action 写入。重新载入和加载模式变化会淘汰旧请求；tab 的中止信号清理其状态。
-文档实现在 `ctx.documentPreviews.register({ id, extensions, binaryExtensions?, priority, title, loading, wrap? })` 注册元数据，并以相同 `id` 向 keyed、Session 作用域的子 slot `sidebar.right.tab.document` 注册正文。`binaryExtensions` 列出 `extensions` 中不可按文本阅读的后缀，这些后缀不提供纯文本选项。两处注册都由 effect 持有，通过 `ctx.slots.inject` 等待子 slot。正文接收 `resourceAddress`、`content`、`wrap`、`scrollportRef` 和标准 `useTabInfo`/`useResource` 钩子。内部滚动元素挂载 `scrollportRef`；卸载时恢复共享正文的滚动职责。注册表保留所有匹配备选：`extension`（默认）优先于 `builtin`，随后按更长的后缀、再按注册顺序排列。所选实现仍可用时，下拉选择保持不变。HTML、SVG 和未匹配的扩展名保留纯文本回退，与加载方式无关。
+文档实现在 `ctx.documentPreviews.register({ id, extensions, binaryExtensions?, priority, title, loading, wrap? })` 注册元数据，并以相同 `id` 向 keyed、Session 作用域的子 slot `sidebar.right.tab.document` 注册正文。`binaryExtensions` 列出 `extensions` 中不可按文本阅读的后缀，这些后缀不提供纯文本选项。两处注册都由 effect 持有，通过 `ctx.slots.inject` 等待子 slot。正文接收 `resourceAddress`、`content`、`wrap`、`scrollportRef`、`addResource`、`setResources` 和标准 `useTabInfo`/`useResource` 钩子。依赖成员由 tab 持有的 `ResourceGroup` 管理；替换依赖始终保留根 Resource。内部滚动元素挂载 `scrollportRef`；卸载时恢复共享正文的滚动职责。注册表保留所有匹配备选：`extension`（默认）优先于 `builtin`，随后按更长的后缀、再按注册顺序排列。所选实现仍可用时，下拉选择保持不变。HTML、SVG 和未匹配的扩展名保留纯文本回退，与加载方式无关。
-`loading: 'text-pages'` 和 `'bytes-complete'` 使用共享文件读取器。选择 `'renderer'` 时，所选正文在读取任何字节前挂载，并接收 `content: { kind: 'renderer', revision, loaded, reload }`。其注入回调负责内容加载、错误和取消。`loaded(version)` 为共享变更提示报告已展示的源版本；已被替换的 revision 所发出的报告会被忽略。`reload()` 增加 revision，正文据此取消并替换当前请求。正文也在卸载和 tab 关闭时取消请求，将已完成内容保留在自己声明的 tab store 中，并在 tab 结束时释放。[Office 预览](#office-preview) 使用此模式，转换后的字节和字体元数据不会进入共享文件 store。
+`loading: 'text-pages'` 和 `'bytes-complete'` 使用共享文件读取器。选择 `'renderer'` 时，所选正文在读取任何字节前挂载，并接收 `content: { kind: 'renderer', revision, loaded, failed, reload }`。其注入回调负责内容加载、错误和取消。`loaded(version)` 记录已展示的源版本并结束加载。`failed()` 结束加载但不记录成功版本，使后续文件变化可以重试；已被替换的 revision 所发出的报告会被忽略。`reload()` 增加 revision，正文据此取消并替换当前请求。正文也在卸载和 tab 关闭时取消请求，将已完成内容保留在自己声明的 tab store 中，并在 tab 结束时释放。[Office 预览](#office-preview) 使用此模式，转换后的字节和字体元数据不会进入共享文件 store。
## 地址
@@ -43,16 +43,16 @@ tab 使用 `fileAddressFor` 构造的 Session 地址，携带相对或绝对路
## 怎么读
-Web 和桌面端均通过开发者工具选择 HTML 预览策略。渲染器从插件组装层接收 `interactivePreview`。关闭时，将经 DOMPurify 清理的完整静态文档放入不授予沙箱权限的 iframe：CSP 禁止脚本、外部资源、连接、表单和嵌套框架；所有 `href` 和 `xlink:href` 属性、刷新指令及声明式 Shadow DOM 均在重新解析前被移除。行内样式和 data 图片仍可显示，不读取关联文件。开启时使用下述支持脚本的 Blob 预览。切换模式会卸载之前的框架并中止其待处理关联文件读取。其他文档格式保持各自策略。
+Web 和桌面端均通过开发者工具选择 HTML 预览策略。渲染器从插件组装层接收 `interactivePreview`。关闭时，将经 DOMPurify 清理的完整静态文档放入不授予沙箱权限的 iframe：CSP 禁止脚本、外部资源、连接、表单和嵌套框架；所有 `href` 和 `xlink:href` 属性、刷新指令及声明式 Shadow DOM 均在重新解析前被移除。行内样式和 data 图片仍可显示，不读取关联文件。开启时使用下述支持脚本的 Blob 预览。切换模式会卸载之前的框架并中止其待处理关联文件读取。静态预览释放 CSS/JS 的 Resource 订阅，根文件继续监听。其他文档格式保持各自策略。
正文通过 `useTabInfo().tab` 读取记录、导航和生命周期。`useResource<'file'>(tab.contentId)` 提供元数据，普通 inject 回调提供内容读取：
-- 资源快照仅包含 `status`、`value` 和 `failure`；`value` 是 `WorkspaceFileStat` 元数据。提供方可用后，内容读取无需等待首个元数据帧。观察失败优先于 Preview 的变更提示显示；两者都不会自动替换已加载内容。
+- 资源快照仅包含 `status`、`value` 和 `failure`；`value` 是 `WorkspaceFileStat` 元数据。提供方可用后，内容读取无需等待首个元数据帧。观察失败优先于 Preview 的变更提示显示；元数据不可用时保留已加载内容。
- **文本页** —— 纯文本、Markdown 和代码通过 inject 回调调用 `remote.workspaceFiles.read(sessionId, path, { offset }, signal)`。首次挂载读取第一页；滚动到正文末尾或点击 **加载更多** 会读取下一页，直到 `eof`。owner 以 `{ kind: 'text', text, pages, eof }` 提供累计前缀，包含源码偏移和行数。Markdown 和代码增量渲染此前缀，不把每页当成独立文档。第一页之后到达的更新版本页会使读取从头开始，避免混合版本。尚无内容时，失败会以文件类型图标、说明和该失败对应的出路（重试、unpreviewable 子 slot，或什么都不给）填满正文；较晚的失败保留已有内容并在其下提供重试。
- **完整字节** —— PDF、HTML 和常见图片通过 inject 回调调用 `remote.workspaceFiles.readAll(sessionId, path, signal)`。`rpc.ts` 将线路上的 base64 解码为 `data: Uint8Array`，供 `{ kind: 'bytes', data }` 使用。Host 的 `maxFileBytes` 上限拒绝超大文件，不截断。PDF 在传给 worker 前复制保留的字节，使 Preview 缓冲区仍可使用。字节仅保存在临时视图状态中，绝不进入持久布局或 Session JSONL。加载模式变化会淘汰先前结果。
-- **重新载入** —— 仅当前 Preview tab 通过自己的 Remote 回调重读，保留滚动偏好并淘汰旧请求。变更提示将读取版本及起读时的观察版本与后续 `resource.value.version` 比较；刷新前已观察到的版本不会被当成新变化。读取既不刷新共享元数据，也不清除其它 tab 的提示。
+- **重新载入** —— 手动重新载入仅让当前 Preview tab 通过自己的 Remote 回调重读，保留滚动偏好并淘汰旧请求。ResourceGroup 成员变化后，自动刷新使用相同回调。各成员首次元数据仅建立基线，不触发重新载入或首读版本对账；后续在读取期间收到的变化仍会留待下一次刷新。读取既不刷新共享元数据，也不清除其它 tab 的提示。
-开启开发者工具时，HTML 以贴合正文四边的 Blob iframe 运行，沙箱属性严格为 `sandbox="allow-scripts"`，不含 `allow-same-origin`；脚本无法访问父应用的源或文件读取接口。渲染器通过普通 inject 回调调用 `remote.workspaceFiles.readRelated`，加载直接声明的相对 `.js` 经典脚本和 `.css` 样式表；固定安全上限为单个资源 4 MiB、总计 32 MiB、64 个不同资源。Host 代码解析关联路径，`rpc.ts` 解码返回的字节。在渲染器内部，base64 仅用于把 iframe 引导载荷嵌入脚本文本。`![]()
` 静态图片上下文中渲染，带 12px 内边距和圆角。宽图按固有纵横比缩小到面板宽度，小图按固有 CSS 像素尺寸居中，超高图纵向滚动。渲染器既不提供缩放，也不提供拖拽平移。SVG 标记绝不进入应用 DOM 或 iframe，因此其中的脚本无法执行，也无法访问父页面。替换或卸载图片会撤销其 Blob URL。
diff --git a/packages/client/ui-sidebar-documentpreview/package.json b/packages/client/ui-sidebar-documentpreview/package.json
index 5d5f18604a..2a30d10fac 100644
--- a/packages/client/ui-sidebar-documentpreview/package.json
+++ b/packages/client/ui-sidebar-documentpreview/package.json
@@ -30,6 +30,7 @@
"inject": [
"@deepseek-ai/dsh-api-gateway",
"@deepseek-ai/dsh-api-workspace-files",
+ "@deepseek-ai/dsh-client-resources",
"@deepseek-ai/dsh-client-ui-sidebar-right",
"@deepseek-ai/dsh-client-ui-session",
"@deepseek-ai/dsh-api-remotes",
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/TextPreview.module.css b/packages/client/ui-sidebar-documentpreview/src/client/TextPreview.module.css
index 46757a6287..490ec8e67c 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/TextPreview.module.css
+++ b/packages/client/ui-sidebar-documentpreview/src/client/TextPreview.module.css
@@ -311,6 +311,11 @@
color: var(--dsw-alias-label-primary);
background: var(--dsw-alias-interactive-bg-hover);
}
+
+.tool[data-textpreview-tool='auto-refresh'][aria-pressed='true'] {
+ color: var(--dsw-alias-label-primary);
+ background: var(--dsw-alias-interactive-bg-hover);
+}
.viewerTool {
flex: none;
width: auto;
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/TextPreview.tsx b/packages/client/ui-sidebar-documentpreview/src/client/TextPreview.tsx
index 432da7dd17..34efd79edb 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/TextPreview.tsx
+++ b/packages/client/ui-sidebar-documentpreview/src/client/TextPreview.tsx
@@ -3,9 +3,8 @@
*
* Two sources meet here. The standard `useResource` hook gives the file's
* metadata — its version — and this type's
- * own store holds the content it read through its face. A Host-reported change is
- * announced, not applied: reloading under a reader would lose their place, so
- * the bar waits for a click. A failed metadata frame — the file gone, its
+ * own store holds the content it read through its face. Metadata changes reload
+ * the current preview while automatic refresh is enabled. A failed metadata frame — the file gone, its
* workspace unknown — takes the same bar's place over the pages already loaded,
* with the same reload. The type's controls, viewer choice, wrap and reload, sit at the end of
* the path row; the Sidebar's strip carries none of them.
@@ -16,7 +15,8 @@ import clsx from 'clsx'
import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
import type { InjectFace, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
import {
- FileTypeIcon, IconNowrapFillRegular, IconRefreshOutlineRegular, IconWrapFillRegular, Menu, Tooltip, classifyFileType,
+ FileTypeIcon, IconNowrapFillRegular, IconPauseOutlineRegular, IconPlayOutlineRegular,
+ IconRefreshOutlineRegular, IconWrapFillRegular, Menu, Tooltip, classifyFileType,
} from '@deepseek-ai/dsh-client-ui-primitives'
import { pathPartsOf } from '@deepseek-ai/dsh-util-workspace-path'
import type { TextInjected } from './face.ts'
@@ -96,6 +96,7 @@ export type TextPreviewProps =
export function TextPreview({
useTabInfo, useResource, useStore, actions, loadPage, reloadPages,
loadAll, reloadAll, prepareRenderer, useDocumentPreviews, renderSlot, t,
+ addResource, setResources,
}: TextPreviewProps): ReactNode {
const { tab } = useTabInfo()
const { navigation, signal } = tab
@@ -116,6 +117,15 @@ export function TextPreview({
const mode = selected?.loading
const contentRendererId = mode === 'renderer' ? selected?.id : undefined
const current = (state?.mode ?? 'text-pages') === mode && state?.contentRendererId === contentRendererId ? state : undefined
+ const add = useCallback((address: string) => {
+ addResource(tab.id, address, signal)
+ }, [addResource, tab.id, signal])
+ const set = useCallback((addresses: readonly string[]) => {
+ setResources(tab.id, [tab.contentId, ...addresses], signal)
+ }, [setResources, tab.id, tab.contentId, signal])
+ useEffect(() => {
+ set([])
+ }, [set, selected?.id])
const bodyRef = useRef(null)
const scrollportRef = useRef(null)
const storedScrollTopRef = useRef(0)
@@ -195,11 +205,25 @@ export function TextPreview({
const rendererReload = useCallback((): void => {
if (canRead && selected !== undefined) prepareRenderer(tab.id, signal, selected.id, meta.value?.version, true)
}, [canRead, prepareRenderer, tab.id, signal, selected?.id, meta.value?.version])
+ const observedVersion = meta.value?.version
+ const changed = (current?.version !== undefined && observedVersion !== undefined
+ && observedVersion !== current.version && observedVersion !== current.observedVersion)
+ || state?.resourcesDirty === true
+ const reload = useCallback((): void => {
+ if (!canRead) return
+ if (mode === 'text-pages') reloadPages(tab.id, file, signal, observedVersion)
+ else if (mode === 'bytes-complete') reloadAll(tab.id, file, signal, observedVersion)
+ else rendererReload()
+ }, [canRead, mode, reloadPages, reloadAll, rendererReload, tab.id, file, signal, observedVersion])
+ useEffect(() => {
+ if (state?.autoRefresh && changed && current !== undefined && !current.loading && meta.status === 'live') reload()
+ }, [state?.autoRefresh, changed, current?.loading, meta.status, reload])
const content = useMemo((): DocumentContent | undefined => {
if (mode === 'renderer') {
if (current === undefined) return undefined
const revision = current.loadRevision
return { kind: 'renderer', revision, reload: rendererReload,
+ failed: () => { actions.rendererFailed(tab.id, revision) },
loaded: (version) => { actions.rendered(tab.id, revision, version) } }
}
if (mode === 'bytes-complete') {
@@ -243,19 +267,10 @@ export function TextPreview({
}
const next = loadedThrough + 1
const { name } = pathPartsOf(displayPath)
- const observedVersion = meta.value?.version
- const changed = current?.version !== undefined && observedVersion !== undefined
- && observedVersion !== current.version && observedVersion !== current.observedVersion
const loadNext = (): void => {
if (!canRead || current?.loading || current?.eof) return
loadPage(tab.id, file, next, signal, meta.value?.version)
}
- const reload = (): void => {
- if (!canRead) return
- if (mode === 'text-pages') reloadPages(tab.id, file, signal, meta.value?.version)
- else if (mode === 'bytes-complete') reloadAll(tab.id, file, signal, meta.value?.version)
- else rendererReload()
- }
return (
{
return defineStore({
init: (): TextState => ({ byTab: {} }),
actions: {
+ toggledAutoRefresh: (d, tabId: TabId) => {
+ const state = bucket(d, tabId)
+ state.autoRefresh = !state.autoRefresh
+ },
+ resourceChanged: (d, tabId: TabId) => { bucket(d, tabId).resourcesDirty = true },
/** @param d - draft. @param tabId - owning tab. @param rendererId - manual choice, or automatic selection. */
selected: (d, tabId: TabId, rendererId: string | undefined) => {
if (rendererId === undefined) delete bucket(d, tabId).rendererId
@@ -148,6 +160,12 @@ export function createTextStore(): EngineStoreHandle {
state.version = version
state.loading = false
},
+ /** @param d - draft. @param tabId - owning tab. @param revision - failed content revision. */
+ rendererFailed: (d, tabId: TabId, revision: number) => {
+ const state = d.byTab[tabId]
+ if (state?.mode !== 'renderer' || state.loadRevision !== revision) return
+ state.loading = false
+ },
/** @param d - draft. @param tabId - owning tab. @param file - complete byte result for this view. */
complete: (d, tabId: TabId, file: DocumentFileBytes) => {
const state = bucket(d, tabId)
@@ -191,6 +209,7 @@ export function createTextStore(): EngineStoreHandle {
*/
reset: (d, tabId: TabId) => {
const state = bucket(d, tabId)
+ state.resourcesDirty = false
state.loadRevision++
state.pages = {}
delete state.complete
diff --git a/packages/client/ui-sidebar-documentpreview/tests/apply.client.spec.ts b/packages/client/ui-sidebar-documentpreview/tests/apply.client.spec.ts
index 020666b3da..976da58bbc 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/apply.client.spec.ts
+++ b/packages/client/ui-sidebar-documentpreview/tests/apply.client.spec.ts
@@ -32,7 +32,7 @@ import { en, zh } from '../src/client/locales.ts'
import { RemoteError } from '@deepseek-ai/dsh-client-test-runtime'
import type { textFace } from '../src/client/face.ts'
import type { TextStore } from '../src/client/store.ts'
-import { FILE, SESSION, TAB_ID, page } from './fixtures.client.ts'
+import { FILE, SESSION, TAB_ID, createResources, page } from './fixtures.client.ts'
interface Recorded {
name: string
@@ -45,6 +45,7 @@ interface Recorded {
async function boot() {
const ctx = new Context()
+ ctx.provide('resources', createResources())
ctx.provide('settingsScope', { developerTools: { enabled: createSnapshotStore(true) } } as never)
const tabs = new SidebarRightTabRegistry(ctx)
const registered: Recorded[] = []
@@ -114,7 +115,7 @@ describe('ui-sidebar-documentpreview apply', () => {
expect(dictionaries.size).toBe(0)
})
- it('injects ordinary Remote reads without requiring a Resource service', async () => {
+ it('injects ordinary Remote reads independently of resource metadata', async () => {
const { registered, workspaceFiles } = await boot()
const registration = registered.find(entry => entry.component === TextPreview)
if (registration === undefined) throw new Error('missing preview registration')
diff --git a/packages/client/ui-sidebar-documentpreview/tests/document-seat.client.spec.tsx b/packages/client/ui-sidebar-documentpreview/tests/document-seat.client.spec.tsx
index d225f3cbd5..f938754af5 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/document-seat.client.spec.tsx
+++ b/packages/client/ui-sidebar-documentpreview/tests/document-seat.client.spec.tsx
@@ -102,7 +102,9 @@ describe('document extension seat', () => {
const h = await boot()
act(() => { h.rt.ctx.sidebarRight.openResource(sessionFileAddress('address-session', path)) })
await waitFor(() => { expect(h.view.container.querySelectorAll('[data-textpreview-line]')).toHaveLength(2) })
- expect(h.read).toHaveBeenCalledExactlyOnceWith('address-session', path, { offset: 1 }, expect.any(AbortSignal))
+ expect(h.read.mock.calls).toEqual([
+ ['address-session', path, { offset: 1 }, expect.any(AbortSignal)],
+ ])
expect(h.bytes).not.toHaveBeenCalled()
},
)
@@ -149,7 +151,7 @@ describe('document extension seat', () => {
})
const tab = h.view.container.querySelector('[data-renderer-tab]')?.getAttribute('data-renderer-tab')
expect(h.read).not.toHaveBeenCalled()
- expect(h.bytes).toHaveBeenCalledTimes(1)
+ expect(h.bytes).toHaveBeenCalledOnce()
fireEvent.click(h.view.container.querySelector('[data-document-viewer-menu]')!)
fireEvent.click(screen.getByRole('menuitem', { name: 'builtin-reader' }))
await waitFor(() => { expect(h.view.container.querySelector('[data-renderer="builtin-reader"]')?.textContent).toBe('first\nsecond') })
@@ -171,6 +173,6 @@ describe('document extension seat', () => {
})
await act(async () => { await remove!() })
await waitFor(() => { expect(h.view.container.querySelector('[data-document-markdown]')).not.toBeNull() })
- expect(h.read).toHaveBeenCalledTimes(1)
+ expect(h.read).toHaveBeenCalledOnce()
})
})
diff --git a/packages/client/ui-sidebar-documentpreview/tests/face.client.spec.ts b/packages/client/ui-sidebar-documentpreview/tests/face.client.spec.ts
index 9a728c0844..2a8a85e183 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/face.client.spec.ts
+++ b/packages/client/ui-sidebar-documentpreview/tests/face.client.spec.ts
@@ -14,7 +14,7 @@ import { textFace } from '../src/client/face.ts'
import type { DocumentFileBytes, ReadDocumentBytes, ReadWorkspaceFilePage } from '../src/client/rpc.ts'
import { hostFileOf } from '../src/client/rpc.ts'
import { createTextStore } from '../src/client/store.ts'
-import { ABSOLUTE_PATH, FILE, PATH, SESSION, failure, page } from './fixtures.client.ts'
+import { ABSOLUTE_PATH, FILE, PATH, SESSION, createResources, failure, page } from './fixtures.client.ts'
import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
const TAB_1 = 'tab-1' as TabId
@@ -94,7 +94,8 @@ function bench(sessionId = 'other-session' as SessionId) {
// The store's own `forget`, counted: the record's end must forget a tab exactly once.
const forget = vi.fn(instance.actions.forget)
// Injected for another session on purpose: the address's session must win.
- const face = textFace(read, bytes)(sessionId, { ...instance.actions, forget })
+ const resources = createResources()
+ const face = textFace(read, bytes, resources)(sessionId, { ...instance.actions, forget })
/** Settle the oldest outstanding read, or the oldest one for `offset`. */
const settle = async (result: RemoteResult, offset?: number): Promise => {
const at = offset === undefined ? 0 : pending.findIndex(call => call.offset === offset)
@@ -104,7 +105,7 @@ function bench(sessionId = 'other-session' as SessionId) {
await call.promise
}
return {
- instance, read, face, forget, settle, bytes, controller,
+ instance, read, face, forget, settle, bytes, controller, resources,
settleAll: whole.settle,
outstandingAll: whole.outstanding,
outstanding: () => pending.map(call => call.offset),
@@ -120,6 +121,19 @@ const settlements = [
] as const
describe('textFace', () => {
+ it('subscribes to a dependency once and stops accepting members after the tab ends', () => {
+ const { face, resources, controller, forget } = bench()
+ const source = vi.spyOn(resources, 'source')
+ const address = sessionFileAddress(SESSION, 'style.css')
+ face.addResource(TAB_1, address, controller.signal)
+ face.addResource(TAB_1, address, controller.signal)
+ expect(source).toHaveBeenCalledExactlyOnceWith(address)
+ controller.abort()
+ expect(forget).toHaveBeenCalledExactlyOnceWith(TAB_1)
+ face.addResource(TAB_1, sessionFileAddress(SESSION, 'other.css'), controller.signal)
+ expect(source).toHaveBeenCalledTimes(1)
+ })
+
it('marks the read in flight, then keeps the page', async () => {
const { read, face, settle, tab } = bench()
const controller = new AbortController()
@@ -403,7 +417,7 @@ it.each([new Error('invalid bytes'), 'invalid bytes'])('reports an active comple
const controller = new AbortController()
const read = vi.fn().mockRejectedValue(failure)
try {
- textFace(vi.fn(), read)(SESSION, instance.actions).loadAll(TAB_1, FILE, controller.signal)
+ textFace(vi.fn(), read, createResources())(SESSION, instance.actions).loadAll(TAB_1, FILE, controller.signal)
await Promise.resolve()
expect(instance.getSnapshot().byTab[TAB_1]?.failure).toMatchObject({ code: 'gateway/internal', message: 'invalid bytes' })
} finally { controller.abort() }
@@ -413,7 +427,7 @@ it('ignores a complete-read rejection after renderer-owned loading takes over',
const instance = createTextStore().create()
const controller = new AbortController()
const pending = Promise.withResolvers>>()
- const face = textFace(vi.fn(), () => pending.promise)(SESSION, instance.actions)
+ const face = textFace(vi.fn(), () => pending.promise, createResources())(SESSION, instance.actions)
try {
face.loadAll(TAB_1, FILE, controller.signal)
face.prepareRenderer(TAB_1, controller.signal, 'office')
diff --git a/packages/client/ui-sidebar-documentpreview/tests/fixtures.client.ts b/packages/client/ui-sidebar-documentpreview/tests/fixtures.client.ts
index bbc9c2dea6..d34bd4bc5a 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/fixtures.client.ts
+++ b/packages/client/ui-sidebar-documentpreview/tests/fixtures.client.ts
@@ -8,6 +8,8 @@
* not the slot runtime.
*/
import { onTestFinished, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import { ResourceRegistry } from '../../resources/src/client/resources.ts'
import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
import type { Mock } from 'vitest'
import { act } from '@testing-library/react'
@@ -29,6 +31,12 @@ import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
type BodySlot = PropsRenderSlots<'sidebar.right.tab.document'>['renderSlot']
+export function createResources(): ResourceRegistry {
+ const ctx = new Context()
+ onTestFinished(() => ctx.fiber.dispose())
+ return new ResourceRegistry(ctx)
+}
+
/** Preserve the body-slot callback used by component fixtures. */
export function documentSlots(body: BodySlot): TextPreviewProps['renderSlot'] {
return (name: string, owner: unknown, options?: unknown) => name === 'sidebar.right.tab.document'
@@ -124,7 +132,7 @@ export function harness(script: Record>
const read = vi.fn((_session, _path, offset) =>
Promise.resolve(pages[offset] ?? failure('workspace-file/not-found', { path: PATH })))
const bytes = vi.fn()
- const face = textFace(read, bytes)(SESSION, instance.actions)
+ const face = textFace(read, bytes, createResources())(SESSION, instance.actions)
const current = { version: 'v1' as string | undefined, failure: undefined as RemoteFailure | undefined, snapshot: meta('v1', undefined) }
const refresh = (): void => { current.snapshot = meta(current.version, current.failure) }
const useResource = vi.fn<() => ResourceSnapshot>(() => current.snapshot)
@@ -162,6 +170,7 @@ export function harness(script: Record>
reloadPages: face.reloadPages,
prepareRenderer: face.prepareRenderer, loadAll: face.loadAll,
reloadAll: face.reloadAll,
+ addResource: face.addResource, setResources: face.setResources,
useDocumentPreviews: () => definitions,
renderSlot,
t,
diff --git a/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx b/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx
index d5c36bbb4e..be3a1a7869 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx
+++ b/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx
@@ -1,11 +1,19 @@
// @vitest-environment jsdom
/** HTML iframe ownership follows file identity and bytes, not locale or wrapping changes. */
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { act, cleanup, render, screen } from '@testing-library/react'
+import { act, cleanup, render, screen, waitFor } from '@testing-library/react'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
+import type { Resources, ResourceSnapshot } from '@deepseek-ai/dsh-client-resources/client'
+import type { WorkspaceFileStat } from '@deepseek-ai/dsh-api-workspace-files/types'
import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { TextPreview } from '../src/client/TextPreview.tsx'
+import type { DocumentBodyOwner } from '../src/client/document/contract.ts'
+import { textFace } from '../src/client/face.ts'
import { HtmlBody } from '../src/client/html/HtmlBody.tsx'
import type { HtmlBodyProps } from '../src/client/html/HtmlBody.tsx'
+import { htmlBodyDefinition } from '../src/client/html/index.ts'
import { en } from '../src/client/html/locales.ts'
+import { ADDRESS, ABSOLUTE_PATH, SESSION, TAB_ID, documentSlots, harness } from './fixtures.client.ts'
const translations: ReadonlyMap = new Map(Object.entries(en))
let createDescriptor: PropertyDescriptor | undefined
@@ -41,6 +49,8 @@ function props(text = ' => new TextEncoder().encode(text)
describe('HtmlBody', () => {
+ it.each(['css', 'js'] as const)('reloads the HTML when only its %s resource changes', async (extension) => {
+ const h = harness()
+ const previewProps = h.props()
+ const htmlProps = props()
+ const metadata = (version: string): ResourceSnapshot => ({
+ status: 'live', value: { absolutePath: ABSOLUTE_PATH, version }, failure: undefined,
+ })
+ const root = createSnapshotStore(metadata('root-v1'))
+ const dependency = createSnapshotStore(metadata('asset-v1'))
+ const release = vi.fn()
+ const dependencySource = {
+ getSnapshot: () => dependency.getSnapshot(),
+ subscribe: (listener: () => void) => {
+ const off = dependency.subscribe(listener)
+ return () => { off(); release() }
+ },
+ }
+ const resources: Resources = {
+ source: address => address === ADDRESS ? root : dependencySource,
+ register: () => () => {}, pin: () => {},
+ }
+ const face = textFace(h.read, h.bytes, resources)(SESSION, h.instance.actions)
+ const data = utf8(extension === 'css'
+ ? '().mockResolvedValue({ ok: true, value: {
+ absolutePath: `/workspace/asset.${extension}`, version: 'asset-v1', offset: 0, eof: true,
+ data: btoa(extension === 'css' ? 'body { color: red }' : 'window.loaded = true'),
+ } })
+ const definition = { ...htmlBodyDefinition(() => 'HTML'), extensions: ['md'] }
+ let interactive = true
+ const preview = () => select([definition])}
+ renderSlot={documentSlots((_key, owner) => select(interactive)} readRelated={readRelated} />)} />
+ const view = render(preview())
+ await waitFor(() => {
+ expect(screen.getByTitle(en.frame)).toBeDefined()
+ expect(h.instance.getSnapshot().byTab[TAB_ID]).toMatchObject({ loading: false, resourcesDirty: false })
+ })
+ const previous = screen.getByTitle(en.frame)
+ const reads = h.bytes.mock.calls.length
+ const relatedReads = readRelated.mock.calls.length
+ expect(reads).toBe(1)
+ expect(relatedReads).toBe(1)
+ expect(create).toHaveBeenCalledOnce()
+ readRelated.mockResolvedValueOnce({ ok: true, value: {
+ absolutePath: `/workspace/asset.${extension}`, version: 'asset-v2', offset: 0, eof: true,
+ data: btoa(extension === 'css' ? 'body { color: blue }' : 'window.loaded = false'),
+ } })
+ act(() => { dependency.set(metadata('asset-v2')) })
+ await waitFor(() => { expect(screen.getByTitle(en.frame)).not.toBe(previous) })
+ expect(h.bytes).toHaveBeenCalledTimes(reads + 1)
+ expect(readRelated).toHaveBeenCalledTimes(relatedReads + 1)
+ expect(h.instance.getSnapshot().byTab[TAB_ID]?.version).toBe('root-v1')
+ expect(h.read).not.toHaveBeenCalled()
+ interactive = false
+ view.rerender(preview())
+ const staticFrame = screen.getByTitle(en.frame)
+ expect(staticFrame.getAttribute('sandbox')).toBe('')
+ expect(release).toHaveBeenCalledOnce()
+ act(() => { dependency.set(metadata('asset-v3')) })
+ expect(screen.getByTitle(en.frame)).toBe(staticFrame)
+ expect(h.bytes).toHaveBeenCalledTimes(reads + 1)
+ expect(readRelated).toHaveBeenCalledTimes(relatedReads + 1)
+ act(() => { root.set(metadata('root-v2')) })
+ await waitFor(() => { expect(h.bytes).toHaveBeenCalledTimes(reads + 2) })
+ expect(readRelated).toHaveBeenCalledTimes(relatedReads + 1)
+ view.unmount()
+ })
+
it('renders static HTML without reading related files, running scripts or retaining an advanced frame', async () => {
const initial = props('().mockResolvedValue({ ok: true, value })
const tab = new AbortController()
const loading = new AbortController()
- const read = createReadHtmlRelative(readRelated, ADDRESS, tab.signal)
+ const addResource = vi.fn()
+ const read = createReadHtmlRelative(readRelated, ADDRESS, tab.signal, addResource)
await expect(read('../a%20b.js?v=1#fragment', loading.signal)).resolves.toEqual({ ...value, data: new Uint8Array([120]) })
const signal = readRelated.mock.calls[0]?.[2]
expect(readRelated).toHaveBeenCalledExactlyOnceWith(ADDRESS, '../a b.js', signal)
+ expect(addResource).toHaveBeenCalledExactlyOnceWith(sessionFileAddress('html', value.absolutePath))
expect(signal?.aborted).toBe(false)
tab.abort()
expect(signal?.aborted).toBe(true)
})
+ it('observes the Host-resolved dependency instead of a symlink and parent-segment spelling', async () => {
+ const value = { absolutePath: '/workspace/style.css', data: btoa('x'), version: 'v1', offset: 0, eof: true }
+ const readRelated = vi.fn().mockResolvedValue({ ok: true, value })
+ const addResource = vi.fn()
+ const signal = new AbortController().signal
+ await createReadHtmlRelative(readRelated, ADDRESS, signal, addResource)('linked/../style.css', signal)
+ expect(addResource).toHaveBeenCalledExactlyOnceWith(sessionFileAddress('html', value.absolutePath))
+ })
+
+ it('observes the Host-reported missing path so creation can invalidate the preview', async () => {
+ const path = '/workspace/missing.css'
+ const readRelated = vi.fn().mockResolvedValue({
+ ok: false, error: new RemoteError('workspace-file/not-found', 'Missing dependency', { path }),
+ })
+ const addResource = vi.fn()
+ const signal = new AbortController().signal
+ await expect(createReadHtmlRelative(readRelated, ADDRESS, signal, addResource)('linked/../missing.css', signal))
+ .rejects.toThrow('Missing dependency')
+ expect(addResource).toHaveBeenCalledExactlyOnceWith(sessionFileAddress('html', path))
+ })
+
+ it('does not guess a dependency path when the Host failure contains none', async () => {
+ const readRelated = vi.fn().mockResolvedValue({
+ ok: false, error: new RemoteError('gateway/internal', 'Read failed', {}),
+ })
+ const addResource = vi.fn()
+ const signal = new AbortController().signal
+ await expect(createReadHtmlRelative(readRelated, ADDRESS, signal, addResource)('asset.css', signal)).rejects.toThrow('Read failed')
+ expect(addResource).not.toHaveBeenCalled()
+ })
+
it('refuses non-relative references and preserves Host permission failures', async () => {
const readRelated = vi.fn().mockResolvedValue({
ok: false, error: new RemoteError('workspace-file/outside-workspace', 'outside workspace', { path: '../x.js' }),
})
const signal = new AbortController().signal
- const read = createReadHtmlRelative(readRelated, ADDRESS, signal)
+ const read = createReadHtmlRelative(readRelated, ADDRESS, signal, vi.fn())
for (const path of ['', '/x.js', 'file:///x.js', '%2Fx.js', 'C:/x.js', '..\\x.js', '%00.js', '%ZZ.js']) {
await expect(read(path, signal)).rejects.toThrow()
}
@@ -38,7 +72,7 @@ describe('HTML relative file reader', () => {
const controller = new AbortController()
controller.abort()
const readRelated = vi.fn()
- const read = createReadHtmlRelative(readRelated, ADDRESS, controller.signal)
+ const read = createReadHtmlRelative(readRelated, ADDRESS, controller.signal, vi.fn())
await expect(read('x.js', new AbortController().signal)).rejects.toMatchObject({ name: 'AbortError' })
expect(readRelated).not.toHaveBeenCalled()
})
@@ -47,7 +81,7 @@ describe('HTML relative file reader', () => {
const pending = Promise.withResolvers>>()
const readRelated = vi.fn().mockReturnValue(pending.promise)
const loading = new AbortController()
- const read = createReadHtmlRelative(readRelated, ADDRESS, new AbortController().signal)
+ const read = createReadHtmlRelative(readRelated, ADDRESS, new AbortController().signal, vi.fn())
const result = read('./late.js', loading.signal)
const rejected = expect(result).rejects.toMatchObject({ name: 'AbortError' })
loading.abort()
diff --git a/packages/client/ui-sidebar-documentpreview/tests/markdown-registration.client.spec.tsx b/packages/client/ui-sidebar-documentpreview/tests/markdown-registration.client.spec.tsx
index 4e328a1977..1441718b91 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/markdown-registration.client.spec.tsx
+++ b/packages/client/ui-sidebar-documentpreview/tests/markdown-registration.client.spec.tsx
@@ -61,6 +61,7 @@ describe('Markdown implementation registration', () => {
content: { kind: 'text', text: '# Notes\n\n```ts\nconst value = 1\n```', pages: [], eof: true },
wrap: false,
scrollportRef: vi.fn(),
+ addResource: vi.fn(), setResources: vi.fn(),
}, {
entryKey: MARKDOWN_BODY_ID,
hookContext: useTabInfo,
diff --git a/packages/client/ui-sidebar-documentpreview/tests/renderer-loading.client.spec.tsx b/packages/client/ui-sidebar-documentpreview/tests/renderer-loading.client.spec.tsx
index 660ddc643e..472a8192f2 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/renderer-loading.client.spec.tsx
+++ b/packages/client/ui-sidebar-documentpreview/tests/renderer-loading.client.spec.tsx
@@ -56,6 +56,7 @@ it('lets a non-Office renderer load content, report its version, and reload thro
expect(read).toHaveBeenCalledTimes(1)
expect(await screen.findByText('Custom content v1')).toBeTruthy()
expect(h.instance.getSnapshot().byTab[TAB_ID]?.version).toBe('v1')
+ act(() => { h.instance.actions.toggledAutoRefresh(TAB_ID) })
h.setVersion('v2')
view.rerender(>({ status: 'loading', value: undefined, failure: undefined })
+ const release = vi.fn()
+ const source = {
+ getSnapshot: () => state.getSnapshot(),
+ subscribe: (listener: () => void) => {
+ const off = state.subscribe(listener)
+ return () => { off(); release() }
+ },
+ }
+ const resources: Resources = { source: () => source, register: () => () => {}, pin: () => {} }
+ const changed = vi.fn()
+ const group = new ResourceGroup(resources, changed)
+ onTestFinished(() => { group.close() })
+ const version = (version: string): void => {
+ state.set({ status: 'live', value: { absolutePath: '/style.css', version }, failure: undefined })
+ }
+ return { group, changed, version, release, state }
+}
+
+describe('ResourceGroup', () => {
+ it('uses initial metadata as a baseline and invalidates only on later changes', () => {
+ const h = harness()
+ h.group.add('style.css')
+ h.version('v2')
+ expect(h.changed).not.toHaveBeenCalled()
+ h.version('v3')
+ expect(h.changed).toHaveBeenCalledOnce()
+ h.group.close()
+ })
+
+ it('subscribes to an existing member only once', () => {
+ const h = harness()
+ h.group.add('style.css')
+ h.version('v2')
+ h.group.add('style.css')
+ expect(h.changed).not.toHaveBeenCalled()
+ h.version('v3')
+ expect(h.changed).toHaveBeenCalledOnce()
+ h.group.close()
+ })
+
+ it('ignores repeated metadata and stops observing after close', () => {
+ const h = harness()
+ h.version('v1')
+ h.group.add('style.css')
+ h.version('v1')
+ expect(h.changed).not.toHaveBeenCalled()
+ h.version('v2')
+ expect(h.changed).toHaveBeenCalledOnce()
+ h.group.close()
+ h.version('v3')
+ expect(h.changed).toHaveBeenCalledOnce()
+ })
+
+ it('shares membership and releases members absent from the next document', () => {
+ const h = harness()
+ h.group.add('style.css')
+ h.group.add('style.css')
+ h.group.set(['style.css', 'script.js'])
+ h.group.set(['script.js'])
+ expect(h.release).toHaveBeenCalledOnce()
+ h.group.close()
+ h.group.close()
+ expect(h.release).toHaveBeenCalledTimes(2)
+ })
+
+ it('invalidates on failure and recovery without repeating an unchanged failure', () => {
+ const h = harness()
+ h.group.add('style.css')
+ h.version('v1')
+ const failed = {
+ ...h.state.getSnapshot(), status: 'failed' as const,
+ failure: new RemoteError('workspace-file/not-found', 'File missing', { path: 'style.css' }),
+ }
+ h.state.set(failed)
+ expect(h.changed).toHaveBeenCalledOnce()
+ h.state.set({ ...failed })
+ expect(h.changed).toHaveBeenCalledOnce()
+ h.version('v1')
+ expect(h.changed).toHaveBeenCalledTimes(2)
+ })
+})
diff --git a/packages/client/ui-sidebar-documentpreview/tests/text-preview.client.spec.tsx b/packages/client/ui-sidebar-documentpreview/tests/text-preview.client.spec.tsx
index 81b53f15bb..335b276f90 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/text-preview.client.spec.tsx
+++ b/packages/client/ui-sidebar-documentpreview/tests/text-preview.client.spec.tsx
@@ -326,11 +326,12 @@ describe('TextPreview — pages', () => {
expect(view.container.querySelector('[data-textpreview-failed]')).toBeNull()
})
- it('announces a change and, on request, re-reads the pages keeping the reader\'s place', async () => {
+ it('announces a change while automatic refresh is paused and reloads on request, keeping the reader\'s place', async () => {
const h = harness({ 1: page(1, ['a', 'b'], true) })
const view = render(>()
h.read.mockReturnValueOnce(pending.promise)
const view = render(/`, 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.
## Model Experience
@@ -57,7 +59,7 @@ None; directory listings travel over the Remote and assemble no model request.
## Known Limitations and Deferred Work
-- **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.
@@ -70,4 +72,4 @@ None.
-**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.
diff --git a/packages/client/ui-sidebar-files/README.zh.md b/packages/client/ui-sidebar-files/README.zh.md
index a0d0abffcd..eceffb1c3a 100644
--- a/packages/client/ui-sidebar-files/README.zh.md
+++ b/packages/client/ui-sidebar-files/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 下的一行标题行，然后是树。标题行与文档预览（`ui-sidebar-documentpreview`）的相同：根路径，目录部分灰色、最后一段正色，从不省略号截断（比行宽的路径保留末尾、淡出开头），右端显示重新读取控件。这一行是复制而非共享，因为插件 bundle 只经平台模块共享运行时代码；待 artifact 与各 slot 的形态定下来后，可以在 `ui-primitives` 放一份供每个 pane 标题行使用。
- **标签页标题**：以该 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`（接线）。
## 树
-根是会话的工作目录，读自 `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`，标题行里的拆分由 `@deepseek-ai/dsh-util-workspace-path` 的 `pathPartsOf` 给出。`/` 和 Windows 盘根等文件系统根路径均可作为树的根。每一层以绝对路径为键；子路径是父路径以 `/` 拼上条目名。一层在首次展开时经 `@deepseek-ai/dsh-api-workspace-files` 命名空间的 `remote.workspaceFiles.list(sessionId, absolutePath)` 列出；适配器保留列表的条目与截断标志，丢弃其工作区相对路径。行序为目录优先，其后按自然序、不分大小写的名称排列；dotfiles 与其他条目一样显示。
| 条目类型 | 行 |
|---|---|
-| `directory` | 切换展开与折叠；该层在首次打开时拉取，折叠期间保留。 |
+| `directory` | 切换展开与折叠；再次打开时重新列举，并恢复仍存在的已展开后代。折叠期间保留已显示条目的缓存。 |
| `file` | 经 `useTabInfo().tab.actions.openResource` 打开 `dsh-resource://file/session//`，地址由 `@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 生命周期内持有自己的目标监听；折叠关闭该节点及其不可见后代。祖先恢复期间的展开状态变化会更新存储和待恢复节点，后代恢复时遵循最新展开偏好。自动刷新默认开启；独立开关暂时隐藏，状态、文案、样式与切换逻辑保留。目录读取期间或收尾时收到的变化仍会留待下一次刷新。
## 模型体验
@@ -57,7 +59,7 @@ kind: "package-reference"
## 已知限制与暂缓事项
-- **只有列目录。**没有搜索、产物过滤、拖拽、重命名、右键菜单、当前文件高亮或文件系统监听；一层只会因重新读取而变化。
+- **只有列目录。**没有搜索、产物过滤、拖拽、重命名、右键菜单或当前文件高亮。
- **只有一个根。**树以会话工作目录为根；没有办法浏览到它之上，而 Host 本来也拒绝工作区根之外的路径。
@@ -70,4 +72,4 @@ kind: "package-reference"
-**运行时不变量：** 不发布 companion。树唯一的运行时状态是每 tab 一份的 Slot store，由持有它的正文写入、随 tab 的中止信号忘掉；没有第二个观测源可与之比对。
+**运行时不变量：** 不发布 companion。tab 持有的 face 内部管理目录读取与监听，并通过 Slot store 写入显示状态；tab 取消时释放二者。本包未暴露可用于运行时比对的独立观测源。
diff --git a/packages/client/ui-sidebar-files/package.json b/packages/client/ui-sidebar-files/package.json
index 10768f4300..20d74ac18c 100644
--- a/packages/client/ui-sidebar-files/package.json
+++ b/packages/client/ui-sidebar-files/package.json
@@ -58,6 +58,7 @@
"@deepseek-ai/dsh-client-ui-sidebar-right": "workspace:^",
"@deepseek-ai/dsh-client-ui-slots": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
+ "@deepseek-ai/dsh-typert-protocol": "workspace:^",
"@deepseek-ai/dsh-util-workspace-path": "workspace:^",
"@testing-library/react": "^16.1.0",
"@types/react": "~18.3.1",
diff --git a/packages/client/ui-sidebar-files/src/client/FilesBody.module.css b/packages/client/ui-sidebar-files/src/client/FilesBody.module.css
index a49f6688a3..a069eec6a8 100644
--- a/packages/client/ui-sidebar-files/src/client/FilesBody.module.css
+++ b/packages/client/ui-sidebar-files/src/client/FilesBody.module.css
@@ -201,6 +201,11 @@
background: var(--dsw-alias-interactive-bg-hover);
}
+.tool[aria-pressed='true'] {
+ color: var(--dsw-alias-label-primary);
+ background: var(--dsw-alias-interactive-bg-hover);
+}
+
/* The folder sheet before the chip's text; the chip's title row centres it
on the text's line and spaces it. */
.titleIcon {
diff --git a/packages/client/ui-sidebar-files/src/client/FilesBody.tsx b/packages/client/ui-sidebar-files/src/client/FilesBody.tsx
index 9d3fb42f48..3b707f94a4 100644
--- a/packages/client/ui-sidebar-files/src/client/FilesBody.tsx
+++ b/packages/client/ui-sidebar-files/src/client/FilesBody.tsx
@@ -7,8 +7,7 @@
* 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.
+ * ink, then reload, which refreshes the expanded directories in place.
*/
import { useEffect, useLayoutEffect, useRef } from 'react'
import type { ReactNode, RefObject } from 'react'
@@ -17,6 +16,7 @@ import type { RemoteFailure } from '@deepseek-ai/dsh-api-remotes/client'
import type { PropsLocale, PropsRuntime, PropsStore, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
import {
FileTypeIcon, IconFolderCloseRegular, IconFolderOpenRegular, IconRefreshOutlineRegular, classifyFileType,
+ IconPauseOutlineRegular, IconPlayOutlineRegular,
} from '@deepseek-ai/dsh-client-ui-primitives'
import { fileAddressFor, pathPartsOf } from '@deepseek-ai/dsh-util-workspace-path'
import type { WorkspaceDirectoryEntry } from '@deepseek-ai/dsh-api-workspace-files/types'
@@ -103,7 +103,7 @@ function usePathClipped(
/** What every level shares: the tab's tree and the two gestures. */
interface TreeContext {
readonly state: FilesTabState
- readonly onToggle: (path: string) => void
+ readonly onToggle: (parent: string, path: string) => void
readonly onOpen: (path: string) => void
readonly t: TranslateNS<'sidebarFiles'>
}
@@ -115,7 +115,7 @@ function Entry({ parent, entry, tree }: { parent: string; entry: WorkspaceDirect
const expanded = tree.state.expanded.includes(path)
return (
-
+
+
+
{meta.failure !== undefined && hasContent
@@ -326,6 +341,15 @@ export function TextPreview({
)}
{content !== undefined && renderSlot('sidebar.right.tab.document.action', { content }, { entryKey: selected.id, hookContext: useTabInfo })}
+
+
+
+
+
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/store.ts b/packages/client/ui-sidebar-documentpreview/src/client/store.ts
index f34b7e2dbb..9668b4ea86 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/store.ts
+++ b/packages/client/ui-sidebar-documentpreview/src/client/store.ts
@@ -31,6 +31,8 @@ export interface TextPage {
/** One tab's pages and view. */
export interface TextTabState {
+ autoRefresh: boolean
+ resourcesDirty: boolean
/** Explicit viewer choice for this tab; absence follows automatic matching. */
rendererId?: string
/** Current display-loading mode; absent before the first read. */
@@ -72,6 +74,8 @@ export interface TextState {
*/
export function fresh(): TextTabState {
return {
+ autoRefresh: true,
+ resourcesDirty: false,
loadRevision: 0,
version: undefined,
observedVersion: undefined,
@@ -92,9 +96,12 @@ function bucket(state: TextState, tabId: TabId): TextTabState {
/** The preview store's write set; every action names the tab it writes. */
type TextActions = {
+ toggledAutoRefresh: (draft: TextState, tabId: TabId) => void
+ resourceChanged: (draft: TextState, tabId: TabId) => void
selected: (draft: TextState, tabId: TabId, rendererId: string | undefined) => void
loading: (draft: TextState, tabId: TabId, mode?: DocumentLoadMode, observedVersion?: string, contentRendererId?: string) => void
rendered: (draft: TextState, tabId: TabId, revision: number, version: string) => void
+ rendererFailed: (draft: TextState, tabId: TabId, revision: number) => void
complete: (draft: TextState, tabId: TabId, file: DocumentFileBytes) => void
page: (draft: TextState, tabId: TabId, page: WorkspaceFileText) => void
failed: (draft: TextState, tabId: TabId, failure: RemoteFailure) => void
@@ -116,6 +123,11 @@ export function createTextStore(): EngineStoreHandlehello
'): HtmlBodyProps { sessionId: 'html' as SessionId, useTabInfo: () => ({ tab: { signal } }), readRelated: vi.fn(), + addResource: vi.fn(), + setResources: vi.fn(), useResource: () => ({ value: undefined }), t: key => translations.get(key) ?? key, } as HtmlBodyProps @@ -49,6 +59,78 @@ function props(text = 'hello
'): HtmlBodyProps { const utf8 = (text: string): Uint8ArrayHTML content
' + : 'HTML content
') + h.bytes.mockResolvedValue({ ok: true, value: { absolutePath: ABSOLUTE_PATH, version: 'root-v1', data, offset: 0, eof: true } }) + const readRelated = vi.fnPreview
Static content
') const basic = { ...initial, useInteractivePreview: ((select: (enabled: boolean) => unknown) => select(false)) as HtmlBodyProps['useInteractivePreview'] } diff --git a/packages/client/ui-sidebar-documentpreview/tests/html-read-relative.client.spec.ts b/packages/client/ui-sidebar-documentpreview/tests/html-read-relative.client.spec.ts index a7bd5a70f5..d043a1a579 100644 --- a/packages/client/ui-sidebar-documentpreview/tests/html-read-relative.client.spec.ts +++ b/packages/client/ui-sidebar-documentpreview/tests/html-read-relative.client.spec.ts @@ -1,6 +1,7 @@ /** HTML URL decoding stays local; ordinary Remote reads leave path resolution and authorization to the Host. */ import { describe, expect, it, vi } from 'vitest' import { RemoteError } from '@deepseek-ai/dsh-client-test-runtime' +import { sessionFileAddress } from '@deepseek-ai/dsh-util-workspace-path' import { createReadHtmlRelative } from '../src/client/html/read-relative.ts' import type { ReadHtmlRelated } from '../src/client/html/read-relative.ts' @@ -12,21 +13,54 @@ describe('HTML relative file reader', () => { const readRelated = vi.fn