dsh-plugin-core 0.32.0 → 0.33.1

package/README.md

@@ -1,109 +1,242 @@
 # dsh-plugin-core
 
-DSH（DeepSeek Harness）插件共享底座：把跨插件复用的样式、控件、通用方法、工作区浏览、会话预览收敛到一处，写新插件时按文档 `npm i` 引用，不再一个个仓库抄。
+**English** · [简体中文](https://github.com/cq-guojia/dsh-plugin-core/blob/main/README.zh-CN.md)
 
-服务对象：以后要写的每一个 DSH 插件（不只是现有的几个）。
+The shared UI foundation for **DSH (DeepSeek Harness)** plugins: design tokens, a complete React control set, pure helpers, workspace file browsing, and read-only session preview — in one package, imported subpath by subpath.
 
-## 先看效果：装上预览插件
+It exists so that every plugin does not re-implement the same button, date picker, toast, file preview and conversation playback. Everything here is built on the host's own tokens and theme switch, so a plugin assembled from these parts looks native without any per-plugin skinning.
 
-最快的方式——直接把预览插件装进 DSH 宿主，看真实渲染（明暗、token 全部跟随宿主，**不走任何独立网页**）：
+- **Follows the host, not the OS.** Light and dark come from the host's `body[data-ds-dark-theme]`; the 12 accent colors are the same ones the host uses.
+- **Nothing here fetches data.** Values, options, workspaces and sessions arrive through props or a small injected interface — the components never reach into the host behind your back.
+- **Runs everywhere the code runs.** The `design`, `ui` and `utils` entries carry zero `@deepseek-ai/*` imports, so they import cleanly in Node and in tests, not just inside the host.
 
-```bash
-dsh plugin --profile web add dsh-plugin-core-demo
-```
+## Screenshots
+
+Real rendering inside a DSH host, dark theme:
+
+Design tokens, the theme predicate and the style injector:
+
+![Design tokens and theme predicate](https://cdn.jsdelivr.net/gh/cq-guojia/dsh-plugin-core@main/assets/readme/01-tokens.png)
+
+Buttons — 18 appearance tiers, three heights, icons, automatic loading:
+
+![Button tiers](https://cdn.jsdelivr.net/gh/cq-guojia/dsh-plugin-core@main/assets/readme/02-buttons.png)
+
+Inputs — field hints, switches, checkboxes, segmented controls:
+
+![Inputs](https://cdn.jsdelivr.net/gh/cq-guojia/dsh-plugin-core@main/assets/readme/03-inputs.png)
+
+Workspace browsing — right-docked file browser and preview, not limited to workspaces:
+
+![Workspace explorer](https://cdn.jsdelivr.net/gh/cq-guojia/dsh-plugin-core@main/assets/readme/04-explorer.png)
+
+Session preview — a read-only dialog that mirrors the official conversation page:
 
-装好后：插件列表 → 找到 `dsh-plugin-core-demo` → 进插件详情页就有「组件预览」入口，点开即整页预览；详情页下方还有配置区（侧栏入口开关、查看 demo、访问 GitHub）。
+![Session preview](https://cdn.jsdelivr.net/gh/cq-guojia/dsh-plugin-core@main/assets/readme/05-session.png)
 
-> 预览插件是仓库里的独立包 `packages/demo/`（包名 `dsh-plugin-core-demo`）。它把 core 的构建产物打进自己的 bundle，自包含、不需要 core 先发 npm，预览的永远是当前这份代码。
+All five screenshots are taken from [`dsh-plugin-core-demo`](#see-it-running-the-demo-plugin), the preview plugin shipped from the same repository.
 
-## 用这个包写插件
+## Install
 
 ```bash
 pnpm add dsh-plugin-core
+# or
+npm install dsh-plugin-core
 ```
 
-（npm 也行；推荐 pnpm。）包里带预编译 `dist`——宿主以 git/npm 装插件不跑构建脚本，产物必须随包发布。`react` 是 optional peer：只用 `utils` / `design` 的插件不必装。
+The published package already contains compiled `dist/` output and type declarations — the host never runs build scripts when installing a plugin. `react` / `react-dom` (`>= 18`) are **optional peers**: skip them if you only use `design` or `utils`.
 
-```ts
-import { createStyleKit } from 'dsh-plugin-core/design'
-import { Button, setStyleKit } from 'dsh-plugin-core/ui'
+## Quick start
 
-setStyleKit(createStyleKit({ id: 'dsh-task-reminder-ui' })) // 1) 领本插件专属样式设施（id 按插件唯一）
-const view = <Button variant="primary" onClick={save}>保存</Button> // 2) 直接用控件，样式它自己带
+```tsx
+// your plugin's client entry
+import { createStyleKit } from 'dsh-plugin-core/design'
+import { Button, Input, setStyleKit, showToast } from 'dsh-plugin-core/ui'
+
+const kit = createStyleKit({ id: 'dsh-task-reminder-ui' }) // 1. one kit per plugin
+setStyleKit(kit)
+
+export function TaskEditor(props: { name: string; setName: (v: string) => void }) {
+  return (
+    <div>
+      <Input value={props.name} onChange={props.setName} placeholder="Task name" hint="Shown in the task list" />
+      <Button variant="primary" onClick={async () => { await save(); showToast('Saved', { variant: 'success' }) }}>
+        Save
+      </Button>
+    </div>
+  )
+}
 ```
 
-为什么必须先 `setStyleKit`：样式只能以字符串在运行时注入 `<style>`（客户端产物是 JS 闭包，`.css` 不加载）。固定 style id 在多插件同页时会互相覆盖，所以做成工厂，每个插件领一套自己的；变量前缀统一 `dshpc`，不再按插件区分。
+Three things worth knowing on day one:
 
-**样式是按需的**：每个控件只带自己那份 CSS，首次渲染时自注入（幂等）——用不到的控件，其 CSS 不会被打进你的包（实测：只用 `Button` 时样式文本从 71.7 KB 降到 9.4 KB）。因此请**用具名导入**（`import { Button } from 'dsh-plugin-core/ui'`）：写成 `import * as core from …` 或 CJS `require` 会让打包器无法摇树，这一份收益会静默归零。
+1. **Call `setStyleKit` once.** Styles reach the page as a runtime-injected `<style>` string, because a plugin's client bundle is a CJS closure and the kernel never loads `.css` assets. The `id` must be unique per plugin — several plugins share one page, and the id is what keeps their style tags from overwriting each other.
+2. **Import by name.** Each control registers only its own CSS the first time it renders (idempotent), so an unused control costs nothing in your bundle. That only holds with named imports (`import { Button } from 'dsh-plugin-core/ui'`); `import * as core` or a CJS `require` disables tree-shaking and silently gives the saving back.
+3. **Dialogs are promises.** `await confirmModal({...})` resolves to `true` / `false`, `alertModal({...})` resolves when dismissed. There are no callback-style variants.
 
-## 子包
+## What's inside
 
-| 引入路径 | 装什么 |
-|---|---|
-| `dsh-plugin-core/design` | token 变量表（含深色段）+ `createStyleKit` 注入器工厂 + 主题判据（零 React） |
-| `dsh-plugin-core/ui` | 控件：Button / Input 家族 / Textarea / Checkbox / Segmented / Select / Picker / ModelPicker / DateTimePicker / Modal / toast / 空态 / 错误边界 / Loading … |
-| `dsh-plugin-core/utils` | 纯方法：日期 / 字符串 / 字节 / 时间区间 / HTTP 取数 + 内置中英多语言 |
-| `dsh-plugin-core/explorer` | 工作区浏览：`openFilePreview` / `pickWorkspaceFile` / `FileBrowser` 面板 |
-| `dsh-plugin-core/explorer/preview` | 文件预览体（md / 代码高亮 / HTML / PDF / Office / 图片） |
-| `dsh-plugin-core/session` | 会话预览（承载可换：弹窗 / 侧栏 / 整页） |
+| Import | What you get | React required |
+|---|---|---|
+| `dsh-plugin-core/design` | Token variables (light + dark), `createStyleKit` injector factory, dark-mode predicate | no |
+| `dsh-plugin-core/ui` | The whole control set — actions, inputs, display, feedback, layout, navigation | yes |
+| `dsh-plugin-core/ui/official` | Direct re-exports of the host's official primitives, for the rare case you need one | yes |
+| `dsh-plugin-core/ui/code-viewer` | Code viewer with per-line highlighting (also used by file preview) | yes |
+| `dsh-plugin-core/ui/host` | Bridge to the host's own toast | yes |
+| `dsh-plugin-core/utils` | Pure helpers: date, string, bytes, HTTP, built-in zh/en dictionary | no |
+| `dsh-plugin-core/explorer` | File browser, file picker, docked file preview | yes |
+| `dsh-plugin-core/explorer/preview` | Preview bodies: image, PDF, Markdown, HTML, Office, text/code | yes |
+| `dsh-plugin-core/session` | Read-only session preview dialog + changed-file diff | yes |
+| `dsh-plugin-core/host` | Host-side routes: read-only FS route, model catalog | no |
 
-依赖方向单向：`design` ← `ui` ← `explorer` / `session`，`utils` 谁也不依赖。
+Dependency direction is one-way: `design` ← `ui` ← `explorer` / `session`, while `utils` depends on nothing.
 
-立包判据：有实质内容、会持续长大的功能模块才独立成包；只是一个控件就进 `ui`。
+## Feature tour
 
-## 几条硬规矩
+### design — tokens and style injection
 
-- 不传整个 `ctx`：只传需要的那一小块能力，宿主 breaking 时改的是插件「取出」的一行。
-- 明暗判据是 `body[data-ds-dark-theme]`，不是 `prefers-color-scheme`。
-- 多语言：核心自带中英（`setLocale('zh' | 'en')` 切换），插件自己界面的文案由插件自己管。
-- 数据调用方给：选工作区 / 选文件 / 会话预览的数据要跨 host↔client 边界，组件取不到。
+Zero React, no components: it ships values plus the mechanism that puts them on the page.
 
-## 多语言
+- One token table for both themes, covering surfaces (`--dshpc-surface-1/2/sunken`), text (`--dshpc-fg`, `--dshpc-fg-3`, `--dshpc-fg-4`), borders, and twelve accents: `business`, `success`, `warning`, `danger`, `purple`, `pink`, `cyan`, `teal`, `orange`, `indigo`, `rose`, `slate`.
+- `createStyleKit({ id })` returns a kit with `cssVar(name)`, `registerStyle(domain, css)`, `applyStyle(domain, css)` and `ensureStyles()` — one `<style>` tag per plugin, isolated by id.
+- `DARK_THEME_SELECTOR` is exported as a constant (`body[data-ds-dark-theme]`) so your own CSS never guesses the theme from the OS.
+- Prefixes are fixed across the ecosystem (`--dshpc-*` / `dshpc-*`); there is no per-plugin rename. Plugins built on different core versions are kept apart by the style-tag id, not by prefixing.
 
-```ts
-import { setLocale } from 'dsh-plugin-core/utils'
-setLocale('en') // 默认中文
-```
+Use this subpath alone if you want the palette and the theme switch but write your own components.
+
+### ui — the control set
+
+Everything is built from tokens, takes its data through props, and follows the host's theme. Props are the customization surface — compose them instead of forking a component. See the [control reference](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/help/ui.md) for every prop.
+
+**Actions**
+
+- `Button` — 18 appearance tiers (solid / outline / bare: `primary`, `secondary`, `danger`, `success`, `warning`, `info`, `outline`, `danger-outline`, `ghost`, `link`, plus the eight extended colors), three heights (24 / 28 / 32), leading and trailing icons, fixed / min / max width with marquee overflow, and automatic loading: return a Promise from `onClick` and the button spins, disables and restores itself — including on rejection.
+- `IconButton` — icon-only variant of the same, with the accessible name enforced.
+- `Segmented` — single or multiple selection, optional 1px frame, per-item icon / count / badge, tone-colored selection.
+
+**Inputs**
+
+- `Input`, `PrefixedInput`, `NumberInput`, `Textarea` — one shared field metric (`fieldMetricsOf`) so every control lines up; error state, leading icon slot, search clear button, and a question-mark hint that uses the host's tooltip.
+- `Checkbox`, and the official `Switch` for on/off semantics.
+- `Picker` — single or multiple, search, groups, selection cap, clearable, empty state; keyboard driven (Esc / arrows / Enter). Its logic (`toGroups`, `filterGroups`, `toggleValue`) is exported separately.
+- `WorkspacePicker` / `ModelPicker` — pickers that bring their own data once `connectHost(ctx)` has been called; unwired they show an empty state rather than inventing entries.
+- `DateTimePicker` — one control for a single instant or a range, precision `day` / `hour` / `minute` / `second`, two independent calendars, keyboard support, start floored and end ceiled.
+- `InputGroup` — input with attached actions.
+
+**Display**
+
+- `Surface` — the plain framed container, with tone / border / padding / radius axes.
+- `Card` / `StripCard` — cards with an accent system.
+- `Chip`, `SectionHead`, `MarqueeText`, `FlipText`, `LiveText`.
+- `Table` — grouped (multi-row) headers, banner groups so several sections live in one table, row spanning, selection, density / striped / border switches, per-column alignment and header tone, built-in empty state, loading and loading-more states, optional built-in pagination. Data-driven: it never sorts, fetches or virtualizes.
+- `FieldHint` — the standalone question mark that opens the host's tooltip.
 
-## 文档
+**Feedback**
 
-| 我想… | 看哪 |
+- `Modal`, `SideSheet` — sized dialogs; `SideSheet` slides in from either side; both accept a `busy` lock.
+- `AlertModal`, `ConfirmModal`, `alertModal()`, `confirmModal()` — promise-based dialogs.
+- `showToast`, `notify` — Sonner-backed toasts, one host per screen shared across plugins.
+- `Loader`, `LoaderBar`, `Loading`, `LoadingBlock`, `LoadingToast`, `RunningBlocks`, `showLoading` — spinners, an indeterminate bar, and a single-slot global loading card.
+
+**Layout and navigation**
+
+- `PanelDock` / `DockPanel` / `createPanelDock` — the right-docked column shell: a real layout member that takes width instead of floating over the page, multiple columns with draggable widths, saved widths, collapse to an edge ear.
+- `QuickToolbar` — a toolbar that follows scrolling with back-to-top and visibility rules.
+- `SplitGroup`, `startResizeLayoutWidth`, `Pagination`.
+
+### utils — pure helpers
+
+Zero React, zero DOM, zero dependency on `design`.
+
+- **Date / time**: `formatDateTime`, `formatYmd`, `formatClock`, `formatDurationHms`, `formatRange`, `sameCalendarDay`, `relativePast`, `relativeFuture`, `overlaps`, `pad2`. Local timezone; a parse failure falls back instead of throwing, and never invents a time. `relativePast` and `relativeFuture` are duals — use the latter for future timestamps or "in 3 minutes" collapses into "just now".
+- **Strings / bytes / paths**: `baseNameOf`, `safeTrim`, `truncateBytes` (UTF-8 aware, never splits a character), `formatBytes`, `formatCount`, `joinPath`, `parentOf`, `extOf`, `mimeOf`, `crumbsOf`.
+- **HTTP**: `request`, `requestJson`, `HttpError` — one options object, structured failures.
+- **i18n**: `setLocale('zh' | 'en')`, `getLocale()`, `t()` — the built-in dictionary shipped with the library (field placeholders, empty states, loading copy). Your plugin's own copy stays yours.
+
+### explorer — workspace file browsing
+
+- `openFilePreview({ mount, path })` — opens the right-docked file panel next to your main area. `mount` is the flex row that wraps the main area (element or selector); the dock becomes a layout member and gives the width back when closed.
+- `pickWorkspaceFile({ anchor, filter })` — a Promise-based file picker; resolves to `{ path, isDir }` or `null`.
+- `FileBrowser` — the browse surface on its own, if you would rather host it yourself.
+- `FilePreview` — dispatches by extension to image, PDF, Markdown (rendered or source), HTML (rendered or source), Office (through the host's converter, honest "unavailable" state when it is missing), or text with syntax highlighting and open-at-line.
+- Browsing is **not limited to workspaces**: one tree with workspace nodes plus the real root (`/`, or drive letters on Windows). Wiring takes two lines — `serveFsRoute({ path })` on the host side and `connectFs({ path })` on the client side with the same path constant. Browsing needs no session.
+
+### session — read-only session preview
+
+- `openSessionView(sessions, uiConversation, sessionId, mountId)` builds the data chain and returns a `view`, or `null` when the session cannot be resolved; hand it to `SessionViewModal` and call `view.dispose()` on close.
+- Renders a dialog that mirrors the official conversation page: user and assistant turns, tool cards, reasoning blocks, changed files, permissions.
+- Archive state is live, not a prop: core subscribes to the official workspace snapshot, so the archived badge and the "Continue" button follow changes while the dialog stays open. Archived sessions stay readable.
+- "Continue" never disappears: an active session jumps to the official conversation, an archived one forks a child session first — with a confirmation dialog you can veto.
+- `openSessionReview({ mount, locator })` opens the changed-file diff; a single file exit (`onOpenFile`) covers tool-card paths, inline mentions and delivered cards.
+
+## Compatibility
+
+| Area | Requirement |
 |---|---|
-| 用这个包写插件 | [`docs/help/index.md`](docs/help/index.md) |
-| 从零接入一个插件 | [`docs/help/integration.md`](docs/help/integration.md) |
-| 查为什么这么设计 | [`docs/requirements.md`](docs/requirements.md) |
-| 改这个仓库本身 | `AGENTS.md` → [`docs/README.md`](docs/README.md) |
+| Host | DSH web client. Plugin client bundles are `window.__ModuleLoader__.load({ id, factory })` CJS closures; styles therefore arrive as runtime-injected strings. |
+| Node.js | `>= 22.5` (build and install time only). |
+| React / React DOM | `>= 18`, optional peers. Only `design` and `utils` work without React. |
+| Theme | Follows the host: `body[data-ds-dark-theme]`. Never `prefers-color-scheme`. Tokens fall back to built-in values when the host does not provide them. |
+| Naming | Variables `--dshpc-*`, class names `dshpc-*` — fixed, shared by the whole ecosystem. Nothing touches the host's own `--dsw-*` / `--dsh-*`. |
+| Official primitives | Reachable only through `dsh-plugin-core/ui/official`, and only inside the host. The main entries stay free of `@deepseek-ai/*`, so importing `ui` in Node or in a test does not explode. |
+| Bundling | ESM with `sideEffects: false` and per-control CSS domains — named imports keep unused controls (and their CSS) out of your bundle. |
+| Data | Never fetched by a component. Workspaces, models, files and sessions come from the caller or from an interface you inject once. |
+
+This is a **library, not a plugin**: no `main`, no `dsh` field. Whoever wants to *see* it running installs the demo plugin below.
 
-## 组件预览插件（packages/demo/）
+## See it running: the demo plugin
 
-库本身是纯库：只有六个子路径导出，没有 main、没有 dsh 字段、零运行时依赖。预览用的插件是仓库里的独立 npm 包 `packages/demo/`（包名 `dsh-plugin-core-demo`）。
+`dsh-plugin-core-demo` ("Blue Whale Component Library") is an installable DSH plugin from the same repository. It renders every control and every composed module with real host data — the same code paths your plugin would use, not a static gallery.
 
-本地改了 core 想看效果：
+Install it into your DSH host with the DSH CLI:
 
 ```bash
-pnpm run build        # 先构建库
-pnpm run build:demo   # 构建预览插件 → packages/demo/dist/{index.js,client.js}
-dsh plugin --profile web add dsh-plugin-core-demo   # 本地路径安装即预览当前代码
+dsh plugin --profile web add dsh-plugin-core-demo
 ```
 
-> 旧版「双击 HTML 的独立预览站」（`demo-dist/` + `demo:build` + GitHub Pages）已废弃删除：它不走宿主，与 harness 脱节。`explorer` / `session` 的宿主数据仍是 mock 的（`packages/demo/src/mock.ts`）。
+Or install the npm package itself:
 
-## 发布（打 tag 即发布）
+```bash
+npm install dsh-plugin-core-demo
+```
+
+After installing, open the plugin in DSH: the plugin page carries a **Component preview** entry that opens the full-page preview, and the sidebar entry can be placed first-level, under "More", or turned off entirely in the plugin settings.
+
+What it covers: design foundation (tokens, dark-mode predicate, injection), actions, inputs, display, feedback, layout and scrolling, navigation, workspace browsing, session preview, the utility helpers with live input/output, and every built-in i18n string in both languages.
+
+Its `dist/` is committed to the repository and it bundles core's build output into itself, so it always previews the current code — you do not need to publish core first.
+
+## Documentation
 
-核心与 demo 共用同一个版本号，一个 tag 同时发两个包：
+| I want to… | Read |
+|---|---|
+| Integrate the package into a plugin | [Integration guide](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/help/integration.md) |
+| Look up a control and its props | [Control reference](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/help/ui.md) |
+| Use `createStyleKit`, override tokens, isolate plugins | [design](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/help/design.md) |
+| Use tokens, colors or a custom skin | [Style guide](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/help/style.md) |
+| Handle dates, strings, bytes, HTTP | [utils](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/help/utils.md) — and the shared [method conventions](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/help/methods.md) |
+| Add workspace browsing and file preview | [explorer](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/help/explorer.md) |
+| Render a session as a read-only preview | [session](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/help/session.md) |
+| Understand the architecture | [Architecture](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/design/architecture.md) |
+| See why a decision was made | [Requirements and decisions](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/requirements.md) |
+
+The help documents are bilingual (Chinese prose, English abstract under each section).
+
+## Releasing
+
+Core and the demo share one version number, and one git tag publishes both packages:
 
 ```bash
-# 1. 两个 package.json 的 version 改成同一个号
-# 2. 构建 + 提交（dist/ 必须入库）
+# 1. set the same version in the root package.json and packages/demo/package.json
+# 2. build, commit (dist/ must be committed) and push
 pnpm run build && pnpm run build:demo
-git add -A && git commit -m "发布 0.3.0" && git push
-# 3. 打 tag 即触发 GitHub Actions 自动发布
-git tag v0.3.0 && git push origin v0.3.0
+git add -A && git commit -m "Release X.Y.Z" && git push
+# 3. the tag triggers GitHub Actions, which publishes to npm
+git tag vX.Y.Z && git push origin vX.Y.Z
 ```
 
-| tag | 谁在发 | 发到哪 |
-|---|---|---|
-| `v0.3.0` | `.github/workflows/publish.yml` | `dsh-plugin-core` |
-| 同上 | `.github/workflows/demo-publish.yml` | `dsh-plugin-core-demo` |
+`tag vX.Y.Z` must equal both `version` fields; there is no separate `demo-v*` tag.
+
+## License
 
-硬规则：`tag vX.Y.Z` == 根 `package.json` 的 `version` == `packages/demo/package.json` 的 `version`，三者不一致时 workflow 直接失败。**没有 `demo-v*` 这种独立 tag。** 一次性前置：npm 网页 Settings → Trusted Publisher 勾上 `npm publish`。
+MIT

package/README.zh-CN.md

@@ -0,0 +1,242 @@
+# dsh-plugin-core
+
+[English](https://github.com/cq-guojia/dsh-plugin-core/blob/main/README.md) · **简体中文**
+
+**DSH（DeepSeek Harness）** 插件的共享 UI 底座：设计 token、一整套 React 控件、纯方法、工作区文件浏览、只读会话预览——一个包，按子路径引入。
+
+它存在的意义是：写下一个插件时，不必再把按钮、日期选择器、toast、文件预览、会话回放各抄一遍。这里的东西全部长在宿主自己的 token 与明暗开关上，拼出来的插件天然是宿主的样子，不需要每个插件各调一遍皮肤。
+
+- **跟宿主走，不跟系统走**：明暗判据是宿主写在 body 上的 `body[data-ds-dark-theme]`，12 个强调色也是宿主那套。
+- **组件不取数**：选项、当前值、工作区、会话，一律由调用方经 props 或一次性注入的接口给进来，组件绝不自己伸手去要。
+- **在哪儿都能 import**：`design`、`ui`、`utils` 三个入口零 `@deepseek-ai/*` 依赖，Node 与单测环境里直接 import 不会炸，不是只能在宿主里活。
+
+## 截图
+
+以下都是在 DSH 宿主里暗色主题下的真实渲染：
+
+设计基础——token 色板、明暗判据、样式注入机制：
+
+![设计基础](https://cdn.jsdelivr.net/gh/cq-guojia/dsh-plugin-core@main/assets/readme/01-tokens.png)
+
+按钮——18 档外观、三档高度、图标、自动 loading：
+
+![按钮](https://cdn.jsdelivr.net/gh/cq-guojia/dsh-plugin-core@main/assets/readme/02-buttons.png)
+
+录入——问号提示、Switch、Checkbox、分段选择器：
+
+![录入](https://cdn.jsdelivr.net/gh/cq-guojia/dsh-plugin-core@main/assets/readme/03-inputs.png)
+
+工作区浏览——右侧停靠的文件浏览与预览，且不限工作区：
+
+![工作区浏览](https://cdn.jsdelivr.net/gh/cq-guojia/dsh-plugin-core@main/assets/readme/04-explorer.png)
+
+会话预览——与官方会话页同构的只读弹窗：
+
+![会话预览](https://cdn.jsdelivr.net/gh/cq-guojia/dsh-plugin-core@main/assets/readme/05-session.png)
+
+五张截图都来自 [`dsh-plugin-core-demo`](#装上就能看预览插件)，也就是同仓库发布的预览插件。
+
+## 安装
+
+```bash
+pnpm add dsh-plugin-core
+# 或者
+npm install dsh-plugin-core
+```
+
+发布包里带编译好的 `dist/` 与类型声明——宿主安装插件时不跑构建脚本。`react` / `react-dom`（`>= 18`）是**可选 peer**：只用 `design` 或 `utils` 的插件不必装。
+
+## 快速开始
+
+```tsx
+// 插件 client 入口
+import { createStyleKit } from 'dsh-plugin-core/design'
+import { Button, Input, setStyleKit, showToast } from 'dsh-plugin-core/ui'
+
+const kit = createStyleKit({ id: 'dsh-task-reminder-ui' }) // 1. 一个插件一套
+setStyleKit(kit)
+
+export function TaskEditor(props: { name: string; setName: (v: string) => void }) {
+  return (
+    <div>
+      <Input value={props.name} onChange={props.setName} placeholder="任务名" hint="会显示在任务列表里" />
+      <Button variant="primary" onClick={async () => { await save(); showToast('已保存', { variant: 'success' }) }}>
+        保存
+      </Button>
+    </div>
+  )
+}
+```
+
+第一天就该知道的三件事：
+
+1. **`setStyleKit` 只调一次。** 样式只能以字符串在运行时注入 `<style>`——插件 client 产物是 CJS 闭包，内核不加载 `.css` 资源。`id` 必须插件内唯一：多个插件同页时，靠它让自己的 `<style>` 不被别人覆盖。
+2. **具名引入。** 每个控件在首次渲染时才登记自己那份 CSS（幂等），用不到的控件其 CSS 不进你的包。这条收益只在具名引入时成立（`import { Button } from 'dsh-plugin-core/ui'`）；写成 `import * as core` 或 CJS `require`，打包器无法摇树，收益静默归零。
+3. **弹窗是 Promise 形态。** `await confirmModal({...})` 拿 `true` / `false`，`alertModal({...})` 关闭即 resolve。没有回调式写法。
+
+## 包里有什么
+
+| 引入路径 | 给你什么 | 需要 React |
+|---|---|---|
+| `dsh-plugin-core/design` | token 变量（明 + 暗）、`createStyleKit` 注入器工厂、明暗判据 | 否 |
+| `dsh-plugin-core/ui` | 全套控件：动作、录入、展示、反馈、布局、导航 | 是 |
+| `dsh-plugin-core/ui/official` | 官方 primitives 的直接再导出（少数确实要用官方原件的场景） | 是 |
+| `dsh-plugin-core/ui/code-viewer` | 代码查看器（行级高亮，文件预览源码态用的也是它） | 是 |
+| `dsh-plugin-core/ui/host` | 宿主自带 toast 的桥接 | 是 |
+| `dsh-plugin-core/utils` | 纯方法：日期、字符串、字节、HTTP，外加内置中英字典 | 否 |
+| `dsh-plugin-core/explorer` | 文件浏览、文件选择、右侧停靠的文件预览 | 是 |
+| `dsh-plugin-core/explorer/preview` | 预览体：图片、PDF、Markdown、HTML、Office、文本 / 代码 | 是 |
+| `dsh-plugin-core/session` | 只读会话预览弹窗 + 变更文件 diff | 是 |
+| `dsh-plugin-core/host` | 宿主侧路由：只读 FS 路由、模型目录 | 否 |
+
+依赖方向单向：`design` ← `ui` ← `explorer` / `session`，`utils` 谁也不依赖。
+
+## 功能说明
+
+### design——token 与样式注入
+
+零 React、没有组件，装的是「值 + 把值弄上页面的机制」。
+
+- 一张明暗双份的 token 表：表面（`--dshpc-surface-1/2/sunken`）、文字（`--dshpc-fg`、`--dshpc-fg-3`、`--dshpc-fg-4`）、边框，以及十二个强调色：`business`、`success`、`warning`、`danger`、`purple`、`pink`、`cyan`、`teal`、`orange`、`indigo`、`rose`、`slate`。
+- `createStyleKit({ id })` 返回一套工具：`cssVar(name)`、`registerStyle(domain, css)`、`applyStyle(domain, css)`、`ensureStyles()`——一个插件一个 `<style>` 标签，按 id 隔离。
+- `DARK_THEME_SELECTOR` 常量为 `body[data-ds-dark-theme]`，自己的 CSS 不必再猜系统主题。
+- 变量与类名前缀全生态固定为 `--dshpc-*` / `dshpc-*`，不存在按插件改名；不同 core 版本的插件靠 style 标签 id 隔离，不靠前缀。
+
+只想统一配色与尺寸、但组件自己写：只引这一个子路径就够。
+
+### ui——控件
+
+全部由 token 搭出来，数据走 props，配色跟随宿主主题。props 就是定制面——组合 props，不要 fork 源码。每个参数的完整说明见[控件参考](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/help/ui.md)。
+
+**动作**
+
+- `Button`——18 档外观（实心 / 线框 / 无底：`primary`、`secondary`、`danger`、`success`、`warning`、`info`、`outline`、`danger-outline`、`ghost`、`link`，加扩展八色），三档高度（24 / 28 / 32），前置与后置图标，固定 / 最小 / 最大宽度（超长跑马灯），自动 loading：`onClick` 返回 Promise 就转圈、禁用、settle 后自恢复，reject 同样恢复。
+- `IconButton`——纯图标版本，无障碍名强制给。
+- `Segmented`——单选 / 多选、可选 1px 外框、段内图标 / 计数 / 角标、`tone` 换选中片配色。
+
+**录入**
+
+- `Input`、`PrefixedInput`、`NumberInput`、`Textarea`——共用一套字段尺寸（`fieldMetricsOf`），错误态、左侧图标槽、搜索清空键，问号提示直接走宿主 tooltip。
+- `Checkbox`；开关语义用官方 `Switch`。
+- `Picker`——单选 / 多选、搜索、分组、选择上限、可清空、空态；键盘可全操作（Esc / ↑↓ / Enter）。底层逻辑（`toGroups`、`filterGroups`、`toggleValue`）单独导出。
+- `WorkspacePicker` / `ModelPicker`——自带数据的领域选择器：插件 `apply` 里调一次 `connectHost(ctx)` 即订阅宿主快照，没接线就是空态，不编造。
+- `DateTimePicker`——一个控件覆盖「一个时刻」与「时间段」，精度 `day` / `hour` / `minute` / `second`，左右两块独立月历，键盘可用，起始端归零、结束端拉满。
+- `InputGroup`——带附着动作的输入框。
+
+**展示**
+
+- `Surface`——纯框容器，tone / 边框 / 内距 / 圆角四轴。
+- `Card` / `StripCard`——带强调色的卡片。
+- `Chip`、`SectionHead`、`MarqueeText`、`FlipText`、`LiveText`。
+- `Table`——多行分组表头、通栏分组（一张表装多个板块）、跨行跨列、行选中、密度 / 斑马纹 / 边框开关、列级对齐与表头语义色、内置空态、加载态与加载更多、可选内置分页。数据驱动：不排序、不取数、不虚拟滚动。
+- `FieldHint`——独立的问号提示，浮层用的是宿主官方 tooltip。
+
+**反馈**
+
+- `Modal`、`SideSheet`——定尺寸弹窗与侧边抽屉，都支持 `busy` 锁。
+- `AlertModal`、`ConfirmModal`、`alertModal()`、`confirmModal()`——Promise 形态的确认 / 提示。
+- `showToast`、`notify`——Sonner 底座的 toast，全屏单例、多插件共用。
+- `Loader`、`LoaderBar`、`Loading`、`LoadingBlock`、`LoadingToast`、`RunningBlocks`、`showLoading`——转圈图标、不定进度条、全局单槽加载卡。
+
+**布局与导航**
+
+- `PanelDock` / `DockPanel` / `createPanelDock`——右侧停靠分栏的通用壳：是布局成员而不是浮层，占宽挤窄主区；支持多栏、拖宽、宽度记忆、收起成右侧耳朵。
+- `QuickToolbar`——随滚动出现的工具栏，带回到顶部与可见性规则。
+- `SplitGroup`、`startResizeLayoutWidth`、`Pagination`。
+
+### utils——纯方法
+
+零 React、零 DOM、零 `design` 依赖。
+
+- **日期时间**：`formatDateTime`、`formatYmd`、`formatClock`、`formatDurationHms`、`formatRange`、`sameCalendarDay`、`relativePast`、`relativeFuture`、`overlaps`、`pad2`。一律本机时区；解析失败按兜底返回、不抛错，也不编造时间。`relativePast` 与 `relativeFuture` 是对偶的——未来时间必须用后者，否则「3 分钟后」会显示成「刚刚」。
+- **字符串 / 字节 / 路径**：`baseNameOf`、`safeTrim`、`truncateBytes`（按 UTF-8 字节截断，不切半个字）、`formatBytes`、`formatCount`、`joinPath`、`parentOf`、`extOf`、`mimeOf`、`crumbsOf`。
+- **HTTP**：`request`、`requestJson`、`HttpError`——一个 options 对象，失败有结构。
+- **多语言**：`setLocale('zh' | 'en')`、`getLocale()`、`t()`——管的是库自带的固定文案（占位符、空态、加载文案）。插件自己界面的文案仍归插件自己。
+
+### explorer——工作区文件浏览
+
+- `openFilePreview({ mount, path })`——在主区旁边打开右侧停靠的文件面板。`mount` 是包住主区的那个 flex 行（元素或选择器都行），面板作为布局成员占宽，关闭时还原。
+- `pickWorkspaceFile({ anchor, filter })`——Promise 形态的文件选择器，resolve `{ path, isDir }` 或 `null`。
+- `FileBrowser`——单独使用浏览面板本体。
+- `FilePreview`——按扩展名分派到图片、PDF、Markdown（渲染 / 源码）、HTML（渲染 / 源码）、Office（走宿主转换能力，缺了就如实显示「不可用」）、文本（代码高亮、可定位到行）。
+- 浏览**不限工作区**：一棵树里既有工作区节点也有真实根（POSIX 是 `/`，Windows 是盘符）。接线两行——宿主侧 `serveFsRoute({ path })`，client 侧用同一个路径常量 `connectFs({ path })`。浏览本身不需要会话。
+
+### session——只读会话预览
+
+- `openSessionView(sessions, uiConversation, sessionId, mountId)` 建数据链拿到 `view`（不可解析返回 `null`），交给 `SessionViewModal`，关闭时记得 `view.dispose()`。
+- 渲染与官方会话页同构：用户 / 助手轮次、工具卡、思考块、变更文件、权限卡。
+- 归档态实时跟随、不用调用方传：核心订阅官方工作区快照，弹窗开着期间归档徽标与「继续对话」会跟着变；归档会话同样可读。
+- 「继续对话」始终保留：未归档直跳官方会话区，已归档先开分支并弹确认框（可以取消）。
+- `openSessionReview({ mount, locator })` 打开变更文件的 diff；文件出口只有一个 `onOpenFile`，工具卡路径、行内引用、交付卡都走它。
+
+## 适配范围
+
+| 维度 | 要求 |
+|---|---|
+| 宿主 | DSH web client。插件 client 产物是 `window.__ModuleLoader__.load({ id, factory })` 的 CJS 闭包，所以样式只能运行时注入。 |
+| Node.js | `>= 22.5`（只影响构建与安装阶段）。 |
+| React / React DOM | `>= 18`，可选 peer。只有 `design` 与 `utils` 可以完全不用 React。 |
+| 主题 | 跟随宿主 `body[data-ds-dark-theme]`，绝不使用 `prefers-color-scheme`。宿主没给 token 时回落到内置值。 |
+| 命名 | 变量 `--dshpc-*`、类名 `dshpc-*`，全生态固定；不碰宿主的 `--dsw-*` / `--dsh-*`。 |
+| 官方 primitives | 只从 `dsh-plugin-core/ui/official` 走，且只在宿主内可解析。主入口零 `@deepseek-ai/*`，因此在 Node / 单测里 import `ui` 不会失败。 |
+| 打包 | ESM、`sideEffects: false`、控件各带自己的 CSS 域——具名引入可让用不到的控件连同其 CSS 都不进包。 |
+| 数据 | 组件从不取数。工作区、模型、文件、会话由调用方给，或来自一次性注入的接口。 |
+
+这是一个**库，不是插件**：没有 `main`、没有 `dsh` 字段。想看它跑起来，装下面的预览插件。
+
+## 装上就能看：预览插件
+
+`dsh-plugin-core-demo`（蓝鲸组件库）是同仓库发布的、可安装的 DSH 插件。它用宿主真实数据把每个控件、每个组合模块跑一遍——走的是你的插件将来会走的同一条代码路径，不是静态画廊。
+
+用 DSH 命令装进宿主：
+
+```bash
+dsh plugin --profile web add dsh-plugin-core-demo
+```
+
+或用 npm 装这个包本身：
+
+```bash
+npm install dsh-plugin-core-demo
+```
+
+装好后在 DSH 里打开本插件：插件详情页有「组件预览」入口，点开即整页预览；侧栏入口的位置（第一级 / 收入「更多」/ 关闭）在插件设置里选。
+
+覆盖内容：设计基础（token、明暗判据、注入机制）、动作、录入、展示、反馈、布局与滚动、导航、工作区浏览、会话预览、工具方法的输入输出实测，以及内置中英双语文案。
+
+它的 `dist/` 随仓库入库，并把 core 的构建产物打进自己 bundle，所以预览的永远是当前这份代码——不需要先把 core 发到 npm。
+
+## 文档
+
+| 我想… | 看哪 |
+|---|---|
+| 把包接进插件 | [接入指引](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/help/integration.md) |
+| 查控件与全部 props | [控件参考](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/help/ui.md) |
+| 建 style kit、覆盖 token、多插件隔离 | [design](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/help/design.md) |
+| 用 token、配色或定制皮肤 | [样式说明](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/help/style.md) |
+| 处理日期、字符串、字节、HTTP | [utils](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/help/utils.md)，以及[方法统一口径](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/help/methods.md) |
+| 加工作区文件浏览与预览 | [explorer](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/help/explorer.md) |
+| 把会话渲染成只读预览 | [session](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/help/session.md) |
+| 理解整体架构 | [架构](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/design/architecture.md) |
+| 查某个决定为什么这么定 | [需求与决策](https://github.com/cq-guojia/dsh-plugin-core/blob/main/docs/requirements.md) |
+
+帮助文档为中英双语（正文中文，每节附英文摘要）。
+
+## 发布
+
+核心与预览插件共用同一个版本号，一个 tag 同时发布两个包：
+
+```bash
+# 1. 根 package.json 与 packages/demo/package.json 的 version 改成同一个号
+# 2. 构建、提交（dist/ 必须入库）、推送
+pnpm run build && pnpm run build:demo
+git add -A && git commit -m "发布 X.Y.Z" && git push
+# 3. 打 tag 触发 GitHub Actions 自动发 npm
+git tag vX.Y.Z && git push origin vX.Y.Z
+```
+
+`tag vX.Y.Z` 必须等于两个 `version` 字段；没有 `demo-v*` 这种独立 tag。
+
+## 许可证
+
+MIT

package/dist/adv/explorer/FileBrowser.d.ts

@@ -0,0 +1,58 @@
+import { createElement as h, type CSSProperties } from 'react';
+import { type Translate } from '../../utils/i18n.js';
+import { type OfficeToPdfFace, type PickFilter, type PickedPath, type WorkspaceAnchorItem } from './types.js';
+import type { FsFace } from './fs-face.js';
+export interface FileBrowserProps {
+    /** 只读文件面（绝对路径；列目录 / 读文件都走它）。 */
+    files: FsFace;
+    /** 官方 remote.officeToPdf；未就位传 null ⇒ Office 文件出「不可用」空态。 */
+    officeToPdf?: OfficeToPdfFace | null;
+    /** 相对路径的基准目录（工作区根）；不传 ⇒ 只认绝对路径。 */
+    rootPath?: string;
+    /** 只用来判断「默认落哪个工作区」；浏览本身不需要它。 */
+    sessionId?: string;
+    /** 起始路径：目录 ⇒ 直接列；文件 ⇒ 预览态（dir 取父目录，面包屑保留可返回）。 */
+    path: string;
+    /** 起始文件打开后定位到这一行（1 起）；树里另点别的文件不沿用。 */
+    focusLine?: number;
+    /**
+     * 重开令牌（`openFilePreview` 每次调用递增）：**同一 path 再点一次**也要回到该文件 /
+     * 重读内容，所以初始 effect 依赖它；它只触发重跑，**不重挂组件**（目录树、展开态、滚动位置保留）。
+     */
+    revision?: number;
+    /**
+     * 关闭回调：**只给没有自己关闭钮的容器**（picker 弹窗）用，第一排才补一枚 ✕。
+     * PanelDock 场景不传 —— 面板关闭归壳（用户 2026-11-04 定），内容不承担关闭。
+     */
+    onClose?: () => void;
+    /** 工作区根显示名（picker = 调用方选的工作区名）；不传 = 用缓存根的末段。 */
+    rootName?: string;
+    /**
+     * ▾ 下拉顶部的工作区清单（可选覆盖）；不传 = 用宿主快照里的工作区标题
+     * （picker 与 dock 同一份清单，用户 2026-11-03：两处显示必须一致）。
+     */
+    workspaces?: readonly string[];
+    /**
+     * 宿主工作区清单（带绝对 path，`workspaces` 服务快照的消费子集）——**路径 → 会话解析用**：
+     * props.path 是绝对路径时，按最长前缀匹配工作区，list 换用该工作区名下的会话 id
+     * （官方 list 按 sessionId 解析工作区根，默认 sessionId 的根不含该路径就会被官方判越界）。
+     * **可选覆盖**：不传 = 自动用宿主 workspaces 快照（connectHost 注入的 workspaceList）；
+     * 快照也没数据（未接线 / 宿主没给）⇒ 不匹配，一切 list 回落 props.sessionId。
+     */
+    workspaceAnchors?: readonly WorkspaceAnchorItem[];
+    /** 从 ▾ 下拉选择其他工作区（点当前工作区 = 回其根目录）。 */
+    onSelectWorkspace?: (name: string) => void;
+    /** 工作区根缓存（可注入；不传 = 内部自建，随组件废弃——不用模块级 Map）。 */
+    /** 外部容器样式（嵌入浮层时撑满高度用）。 */
+    style?: CSSProperties;
+    translate?: Translate;
+    /** 选择器态：点文件即 onPick（不进预览）；不传 = 浏览态。 */
+    picker?: boolean;
+    /** 选择器选中回调：path 为**工作区相对**路径，isDir = 选的是整个文件夹。 */
+    onPick?: (picked: PickedPath) => void;
+    /** 选择器过滤（exts = 只要这些扩展名；dirs = 只要文件夹；不传 = 不限）。 */
+    filter?: PickFilter;
+}
+/** 目录浏览器面板。详见 {@link FileBrowserProps}。 */
+export declare function FileBrowser(props: FileBrowserProps): ReturnType<typeof h>;
+//# sourceMappingURL=FileBrowser.d.ts.map

package/dist/adv/explorer/FileBrowser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileBrowser.d.ts","sourceRoot":"","sources":["../../../src/adv/explorer/FileBrowser.ts"],"names":[],"mappings":"AAeA,OAAO,EACL,aAAa,IAAI,CAAC,EASlB,KAAK,aAAa,EAEnB,MAAM,OAAO,CAAA;AASd,OAAO,EAAK,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAEvD,OAAO,EAkBL,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,UAAU,EAEf,KAAK,mBAAmB,EACzB,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAqB1C,MAAM,WAAW,gBAAgB;IAC/B,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,2DAA2D;IAC3D,WAAW,CAAC,EAAE,eAAe,GAAG,IAAI,CAAA;IACpC,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAA;IACZ,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAA;IACjD,qCAAqC;IACrC,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,8CAA8C;IAC9C,0BAA0B;IAC1B,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,SAAS,CAAC,EAAE,SAAS,CAAA;IAGrB,uCAAuC;IACvC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,kDAAkD;IAClD,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAA;IACrC,kDAAkD;IAClD,MAAM,CAAC,EAAE,UAAU,CAAA;CACpB;AAED,2CAA2C;AAC3C,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAwpBzE"}