dsh-single-terminal 0.1.0 → 0.1.3

package/README.md

@@ -1,5 +1,9 @@
 # dsh-single-terminal
 
+<p align="center">
+  <img src="assets/preview/1.png" alt="dsh-single-terminal preview" width="800" />
+</p>
+
 **dsh-single-terminal** is a real-terminal drawer plugin for the DeepSeek
 Harness (DSH) host. It docks an interactive PTY terminal (xterm.js) to the
 bottom of the web app — type into it, Ctrl-C it, resize it, open as many tabs
@@ -13,16 +17,30 @@ as you need.
   from config; POSIX: `$SHELL` / bash / zsh / fish
 - **Two drawer modes** — *Docked* pushes the page content up (no occlusion),
   *Overlay* floats above it; drag the top edge to resize, the drawer remembers
-  mode and height
+  mode and height. Both modes share the same frosted-glass style (translucent
+  background + `backdrop-filter` blur) — the mode only decides docking
+  behavior. Open/close slides with the host's
+  easing curve and honors `prefers-reduced-motion`.
+- **Theme following** — the drawer and the terminal palette follow the host's
+  theme (light / dark / custom themes) live; no separate theme config.
 - **Keep-alive sessions** — terminals survive page refreshes and drawer
   close/reopen; on reconnect the recent output is replayed from a ring buffer.
   Opening the drawer with no terminal yet auto-creates one with the default
   shell.
+- **Workspace-aware cwd** — when the current session belongs to a workspace,
+  new terminals (including the auto-created one) start in that workspace root
+  directory, no manual `cd` needed; with no session / no workspace the
+  `defaultCwd` rules apply.
 - **Bilingual UI** — follows the host interface language (中文 / English);
   `Alt+C` toggles the drawer
 
 [中文文档](README.zh.md)
 
+## Preview
+
+Screenshot of the terminal drawer (dark theme following, frosted-glass style):
+see [preview.md](preview.md).
+
 ## Features
 
 - **Header entry** (`conversation.session.header.utilities`): a panel-bottom
@@ -67,8 +85,10 @@ profile `cordis.patch.yml`:
 
 - `defaultShell` — shell used by the `＋` button; when unavailable it falls
   back (`powershell` on Windows, `$SHELL`/`bash` on POSIX).
-- `defaultCwd` — `home` (default) starts in the user home; `workspace` is
-  reserved (currently resolves to home); an absolute path must exist.
+- `defaultCwd` — start directory when there is no workspace context: `home`
+  (default) starts in the user home; `workspace` is reserved (currently
+  resolves to home); an absolute path must exist. When the current session
+  belongs to a workspace the workspace root takes precedence (see above).
 - `customShells` — extra launchers; `command` may be an absolute path or a
   name resolved through `PATH` (with `PATHEXT` on Windows).
 
@@ -92,6 +112,35 @@ dsh --profile web                 # start (restart required for the host half to
 > `pnpm install` to compile it. The browser half inlines xterm.js entirely —
 > no runtime dependency there.
 
+## Publish
+
+The build toolchain is **tsc + tsdown** (no vite): `tsc -b` type-checks and
+emits declarations, while `tsdown` (Rolldown core) bundles the host half
+(`lib/index.js`, ESM) and the browser half (`lib/client.js`, single-file CJS
+`__ModuleLoader__` factory with auto banner wrapping). Dependency management
+uses **pnpm 10** (the `pnpm-lock.yaml` is committed and CI installs with
+`--frozen-lockfile`). Build artifacts are committed to git, so git installs
+need no build:
+
+```sh
+pnpm install     # install per pnpm-lock.yaml
+pnpm run build   # clean lib → tsc -b (declarations) → tsdown (both halves)
+pnpm run verify  # simulate the host module table to check lib/client.js (optional)
+pnpm run release # check + build + verify + npm version patch + push tags (triggers the publish workflow)
+```
+
+### Automated publishing (GitHub Actions)
+
+Pushing a `v*` tag (`pnpm run release` bumps the patch version, rebuilds, and
+tags/pushes automatically) triggers
+[`.github/workflows/publish.yml`](.github/workflows/publish.yml) — a single
+`release` job that: sets up Node 26 → `pnpm install --frozen-lockfile` →
+`pnpm run check` → `pnpm run build` → `pnpm run verify` → `pnpm pack` →
+creates a GitHub Release (auto-generated changelog, tarball attached) →
+publishes to npm via **Trusted Publishing** (OIDC `--provenance`, no
+`NPM_TOKEN` secret; the npm package must have this repository configured as a
+Trusted Publisher).
+
 ## Development
 
 Requirements: **Node ≥ 22.19 (or ≥ 24) + pnpm 10** (the `packageManager` field
@@ -106,14 +155,22 @@ pnpm run verify        # simulate the host seed table to check lib/client.js loa
 ```
 
 ```
-├── src/host/           # Host half: index.ts (entry, ws route + config), hub.ts (session hub + frame protocol), shells.ts (registry + probing), types.ts
-├── src/client/         # Browser half: plugin.tsx (slots), drawer.tsx, term.tsx, controller.ts, ws.ts, styles.ts, i18n.ts ...
-├── lib/index.js        # Host half build artifact (tsdown, ESM)
-├── lib/client.js       # Browser half build artifact (tsdown → __ModuleLoader__ factory, xterm inlined)
-├── scripts/verify-client.mjs    # host-seed simulation check
-├── scripts/gen-xterm-css.mjs    # regenerates src/client/xterm-css.ts from the @xterm/xterm package
+├── src/                # Source
+│   ├── host/           # Host half: index.ts (entry, ws route + config), hub.ts (session hub + frame protocol), shells.ts (registry + probing), types.ts
+│   └── client/         # Browser half: plugin.tsx (slots), drawer.tsx, term.tsx, controller.ts, ws.ts, styles.ts, theme.ts, toggle.tsx, i18n.ts ...
+├── lib/                # Build artifacts (committed: git installs need no build)
+│   ├── index.js        # Host half (tsdown, ESM)
+│   ├── client.js       # Browser half (tsdown → __ModuleLoader__ factory, xterm inlined)
+│   └── types/          # Type declarations (generated by tsc -b)
+├── assets/preview/     # Screenshots referenced by README / preview.md
+├── scripts/            # verify-client.mjs (host-seed simulation check), gen-xterm-css.mjs (regenerates src/client/xterm-css.ts)
+├── tsdown.config.ts    # tsdown build config (node half + client bundle banner wrapper)
+├── tsconfig.json       # solution: references tsconfig.host.json / tsconfig.client.json
 ├── cordis.patch.yml    # Bundle patch: plugin row referenced by package name (no paths)
-└── package.json        # dsh.bundle + dsh.client(web) manifests + peerDependencies
+├── package.json        # dsh.bundle + dsh.client(web) manifests + peerDependencies
+├── README.md           # This file (English)
+├── README.zh.md        # 中文文档
+└── preview.md          # Screenshot preview (references assets/preview/*.png)
 ```
 
 ## Implementation notes
@@ -140,5 +197,18 @@ pnpm run verify        # simulate the host seed table to check lib/client.js loa
   `taskkill /T /F` on the session pid — ConPTY closure alone can leave
   PowerShell (+PSReadLine) alive; POSIX kills the foreground process group
   (`kill(-pid)`).
+- **Theme following**: all plugin CSS consumes the host's semantic alias
+  tokens (`--dsw-alias-*`, defined on `body` and flipped by
+  `body[data-ds-dark-theme]`), so light / dark / custom themes apply without
+  plugin-side logic. The xterm palette is computed at runtime: alias token
+  values are read via a hidden probe element (`getComputedStyle`), the
+  background is re-composed with the frosted alpha, and a `MutationObserver`
+  on the body attribute re-applies the palette — theme switches (including
+  custom themes projected by the host's ThemePresenter) update live.
+- **Renderer strategy**: xterm 5 ships DOM renderer only by default
+  (`allowTransparency` works there, while WebGL canvases are opaque). Both
+  modes share the frosted style, so the plugin stays on the DOM renderer with
+  a translucent terminal background under the frosted blur in every mode —
+  the WebGL addon was removed rather than swapped at runtime.
 - **The official `deepseek-harness` project is not modified**; all UI sits in
   existing slots (`shell.overlay`, `conversation.session.header.utilities`).

package/README.zh.md

@@ -1,5 +1,9 @@
 # dsh-single-terminal
 
+<p align="center">
+  <img src="assets/preview/1.png" alt="dsh-single-terminal 预览" width="800" />
+</p>
+
 **dsh-single-terminal** 是 DeepSeek Harness（DSH）宿主的真实终端抽屉插件。它在
 Web 应用底部挂一条交互式 PTY 终端（xterm.js）——可以正常敲命令、Ctrl-C、拖拽
 改大小、开任意多个标签。
@@ -9,13 +13,23 @@ Web 应用底部挂一条交互式 PTY 终端（xterm.js）——可以正常敲
 - **Shell 选择** —— Windows：PowerShell（默认）/ pwsh 7 / CMD / Git Bash / WSL
   （未安装的自动隐藏）+ config 自定义 shell；POSIX：`$SHELL` / bash / zsh / fish
 - **两种抽屉模式** —— *占高度* 把页面内容顶起（无遮挡），*浮层* 悬浮于内容之上；
-  顶边可拖拽调高度，模式与高度自动记忆
+  顶边可拖拽调高度，模式与高度自动记忆。两种模式共用同一磨砂玻璃样式
+  （半透明背景 + `backdrop-filter` 高斯模糊）——模式只决定停靠行为。开合带
+  滑入滑出动画（沿用宿主缓动曲线，尊重系统减动效设置）。
+- **主题跟随** —— 抽屉与终端配色实时跟随宿主主题（浅色 / 深色 / 自定义主题），
+  无需单独配置。
 - **会话保活** —— 终端在页面刷新、抽屉开合后继续存活；重连后从环形缓冲回放
   近期输出。打开抽屉时若还没有任何终端，会自动用默认 shell 新建一个。
+- **工作区路径感知** —— 当前会话归属某个工作区时，新建终端（含自动新建）直接
+  落在该工作区根目录，无需手动 `cd`；无会话 / 无工作区时回退 `defaultCwd` 规则。
 - **双语 UI** —— 跟随宿主界面语言（中文 / English）；`Alt+C` 开关抽屉
 
 [English](README.md)
 
+## 预览
+
+终端抽屉截图（暗色主题跟随、磨砂玻璃样式）：见 [preview.md](preview.md)。
+
 ## 功能
 
 - **会话头部入口**（`conversation.session.header.utilities`）：会话头部
@@ -58,8 +72,9 @@ Schemastery `Config`（宿主 Plugins 设置页自动渲染），和 / 或 profi
 
 - `defaultShell` —— `＋` 按钮使用的 shell；不可用时自动回退（Windows 回退
   `powershell`，POSIX 回退 `$SHELL`/`bash`）。
-- `defaultCwd` —— `home`（默认）从用户主目录启动；`workspace` 预留（当前等同
-  home）；绝对路径必须存在。
+- `defaultCwd` —— 无工作区上下文时的启动目录：`home`（默认）从用户主目录启动；
+  `workspace` 预留（当前等同 home）；绝对路径必须存在。当前会话归属工作区时
+  优先使用工作区根目录（见上）。
 - `customShells` —— 额外启动器；`command` 可为绝对路径或从 `PATH` 解析的名称
   （Windows 上叠加 `PATHEXT`）。
 
@@ -82,6 +97,31 @@ dsh --profile web                 # 启动（宿主半边需重启后生效）
 > `pnpm install` 时需要 C/C++ 工具链编译。浏览器半边完整内联 xterm.js，
 > 无运行时依赖。
 
+## 发布
+
+构建工具链为 **tsc + tsdown**（无 vite）：`tsc -b` 负责类型检查并产出声明文件，
+`tsdown`（Rolldown 内核）打包宿主半（`lib/index.js`，ESM）与浏览器半
+（`lib/client.js`，单文件 CJS `__ModuleLoader__` 工厂，自动 banner 包裹）。
+依赖管理使用 **pnpm 10**（`pnpm-lock.yaml` 入库，CI 按 `--frozen-lockfile`
+安装）。构建产物随 git 提交，git 安装无需本地构建：
+
+```sh
+pnpm install     # 按 pnpm-lock.yaml 安装
+pnpm run build   # 清空 lib → tsc -b（声明）→ tsdown（双半产物）
+pnpm run verify  # 模拟宿主模块表检查 lib/client.js（可选）
+pnpm run release # check + build + verify + npm version patch + 推送 tag（触发发布工作流）
+```
+
+### 自动发布（GitHub Actions）
+
+推送 `v*` tag（`pnpm run release` 会自动 bump 补丁版本、重建并打 tag 推送）会
+触发 [`.github/workflows/publish.yml`](.github/workflows/publish.yml)——单个
+`release` job：Setup Node 26 → `pnpm install --frozen-lockfile` →
+`pnpm run check` → `pnpm run build` → `pnpm run verify` → `pnpm pack` →
+创建 GitHub Release（自动生成 changelog，附带 tarball）→ 经 **Trusted
+Publishing**（OIDC `--provenance`，无需 `NPM_TOKEN` secret）发布到 npm
+（需先在 npmjs.com 把该包的本仓库配置为 Trusted Publisher）。
+
 ## 开发
 
 环境要求：**Node ≥ 22.19（或 ≥ 24）+ pnpm 10**（`packageManager` 固定 pnpm 版本）。
@@ -95,14 +135,22 @@ pnpm run verify        # 模拟宿主 seed 表检查 lib/client.js 可加载
 ```
 
 ```
-├── src/host/           # 宿主半边：index.ts（入口，ws 路由 + 配置）、hub.ts（会话 Hub + 帧协议）、shells.ts（注册表 + 探测）、types.ts
-├── src/client/         # 浏览器半边：plugin.tsx（slots）、drawer.tsx、term.tsx、controller.ts、ws.ts、styles.ts、i18n.ts ...
-├── lib/index.js        # 宿主半边产物（tsdown，ESM）
-├── lib/client.js       # 浏览器半边产物（tsdown → __ModuleLoader__ 工厂，xterm 已内联）
-├── scripts/verify-client.mjs    # 宿主 seed 表模拟检查
-├── scripts/gen-xterm-css.mjs    # 从 @xterm/xterm 包重新生成 src/client/xterm-css.ts
+├── src/                # 源码
+│   ├── host/           # 宿主半边：index.ts（入口，ws 路由 + 配置）、hub.ts（会话 Hub + 帧协议）、shells.ts（注册表 + 探测）、types.ts
+│   └── client/         # 浏览器半边：plugin.tsx（slots）、drawer.tsx、term.tsx、controller.ts、ws.ts、styles.ts、theme.ts、toggle.tsx、i18n.ts ...
+├── lib/                # 构建产物（入库：git 安装无需本地构建）
+│   ├── index.js        # 宿主半边（tsdown，ESM）
+│   ├── client.js       # 浏览器半边（tsdown → __ModuleLoader__ 工厂，xterm 已内联）
+│   └── types/          # 类型声明（tsc -b 生成）
+├── assets/preview/     # README / preview.md 引用的截图
+├── scripts/            # verify-client.mjs（宿主 seed 表模拟检查）、gen-xterm-css.mjs（重新生成 src/client/xterm-css.ts）
+├── tsdown.config.ts    # tsdown 构建配置（node 半 + client bundle banner 包裹）
+├── tsconfig.json       # solution：引用 tsconfig.host.json / tsconfig.client.json
 ├── cordis.patch.yml    # Bundle patch：按包名引用的插件行（无路径）
-└── package.json        # dsh.bundle + dsh.client(web) manifests + peerDependencies
+├── package.json        # dsh.bundle + dsh.client(web) manifests + peerDependencies
+├── README.md           # 英文文档
+├── README.zh.md        # 本文件（中文）
+└── preview.md          # 截图预览（引用 assets/preview/*.png）
 ```
 
 ## 实现说明
@@ -125,5 +173,14 @@ pnpm run verify        # 模拟宿主 seed 表检查 lib/client.js 可加载
 - **Windows 进程树**：关闭标签执行 `pty.kill()` 后追加 `taskkill /T /F` ——
   仅关 ConPTY 时 PowerShell（+PSReadLine）可能存活；POSIX 杀前台进程组
   （`kill(-pid)`）。
+- **主题跟随**：插件 CSS 全部消费宿主语义 alias token（`--dsw-alias-*`，定义在
+  `body` 上，随 `body[data-ds-dark-theme]` 翻转），浅色 / 深色 / 自定义主题
+  无需插件侧逻辑即可生效。xterm 调色板在运行时现算：经隐藏探针元素读取
+  alias token 的 computed 值，按磨砂 alpha 重组背景色，并用 `MutationObserver`
+  监听 body 属性重新套用——主题切换（含宿主 ThemePresenter 投影的自定义主题）
+  实时生效。
+- **渲染器策略**：xterm 5 默认仅有 DOM 渲染器（`allowTransparency` 在此有效，
+  WebGL canvas 不支持 alpha）。两种模式共用磨砂样式，因此统一保持 DOM 渲染器 +
+  半透明终端背景置于磨砂模糊之上——不做运行时渲染器切换，WebGL 插件已移除。
 - **不修改官方 `deepseek-harness` 项目**；全部 UI 落在既有插槽
   （`shell.overlay`、`conversation.session.header.utilities`）。