dsh-single-terminal 0.1.0 → 0.1.4

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,30 +17,51 @@ 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
-  icon button in the session header's utilities row toggles
-  the drawer. Hovering shows a bubble tooltip (the host `Tooltip` component)
-  with the shortcut; `Alt+C` toggles from anywhere except while typing inside
-  the terminal (there `Alt+C` is passed to the shell as `ESC c`).
+- **Drawer-handle entry** (rendered inside the drawer in `shell.overlay`): a
+  `>_` prompt tab stuck to the drawer's top-right outer edge — the terminal's
+  entry button. It rides the drawer's own slide animation: expanded it sticks
+  to the terminal's top-right corner like a drawer handle; minimized it settles
+  at the page's bottom-right corner. Clicking toggles the drawer; `Alt+C`
+  toggles from anywhere except while typing inside the terminal (there `Alt+C`
+  is passed to the shell as `ESC c`).
+- **Invisible session bridge** (`conversation.session.header.utilities`): a
+  `null`-rendering component that only syncs the current session's workspace
+  root into the controller (so new terminals start there); the header shows no
+  visible UI for this plugin.
 - **Drawer** (`shell.overlay`): a frame-level bottom drawer with
   - a tab strip — one PTY session per tab, independent shells, close button
     per tab (terminates the whole process tree; the pid is verified gone),
-  - a `＋` button (new tab with the default shell) and a `▸` menu
-    (all shells found on this machine; unavailable ones are not listed),
+  - one `＋` button whose dropdown lists all shells found on this machine
+    (unavailable ones are not listed), the default shell pinned first and
+    marked,
   - a mode switch (*Docked* / *Overlay*), a connection status dot and a
-    collapse button,
+    minimize (`−`) button,
   - a drag handle on the top edge (pointer-capture drag, min 140px).
 - **Docked mode** pushes the app frame up with `padding-bottom` on the frame
   root element (no host hook exists for bottom docks); when the anchor cannot
@@ -65,10 +90,13 @@ profile `cordis.patch.yml`:
             args: []
 ```
 
-- `defaultShell` — shell used by the `＋` button; when unavailable it falls
+- `defaultShell` — shell preselected in the `＋` dropdown (pinned first and
+  marked "Default"); 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 +120,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 +163,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 (drawer + entry handle), term.tsx, controller.ts, ws.ts, styles.ts, theme.ts, scope.tsx (session bridge), 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 +205,19 @@ 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`).
+  existing slots (`shell.overlay` for the drawer and its entry handle,
+  `conversation.session.header.utilities` for the invisible session bridge).

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,26 +13,39 @@ 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`）：会话头部
-  utilities 区的「底部面板」(panel-bottom) 图标按钮，点击开合抽屉；悬停显示
-  宿主 `Tooltip`
-  气泡（含快捷键提示）。`Alt+C` 全局开合抽屉；焦点在终端输入区内时放行
-  （`Alt+C` 作为 `ESC c` 发给 shell）。
+- **抽屉把手入口**（渲染在 `shell.overlay` 的抽屉内部）：`>_` 提示符小标签
+  吸附在抽屉右上角外沿——即终端入口按钮。它随抽屉自身的滑动动画移动：
+  展开时像抽屉把手一样吸附在终端右上角；最小化后落在页面右下角。点击开合
+  抽屉；`Alt+C` 全局开合，焦点在终端输入区内时放行（`Alt+C` 作为 `ESC c`
+  发给 shell）。
+- **隐形会话桥**（`conversation.session.header.utilities`）：渲染 null 的
+  组件，只负责把当前会话的工作区根目录同步给 controller（新建终端落在该
+  目录）；会话头部不显示本插件任何可见 UI。
 - **抽屉**（`shell.overlay`）：frame 级底部抽屉，包含
   - 标签条 —— 每标签一条独立 PTY 会话，可独立选择 shell；每标签有关闭按钮
     （终止整棵进程树，已实测 pid 消失）；
-  - `＋` 按钮（默认 shell 新建标签）与 `▸` 菜单（列出本机探测到的全部 shell，
-    不可用的不显示）；
-  - 模式切换（占高度 / 浮层）、连接状态点、收起按钮；
+  - 单一 `＋` 按钮 —— 下拉列出本机探测到的全部 shell（不可用的不显示），
+    默认 shell 置顶并标记；
+  - 模式切换（占高度 / 浮层）、连接状态点、最小化（`−`）按钮；
   - 顶边拖拽条（pointer capture 拖拽，最小 140px）。
 - **占高度模式** 通过对框架根元素设 `padding-bottom` 把内容顶起（宿主没有底部
   停靠钩子）；找不到锚点元素时静默降级为浮层。
@@ -56,10 +73,11 @@ Schemastery `Config`（宿主 Plugins 设置页自动渲染），和 / 或 profi
             args: []
 ```
 
-- `defaultShell` —— `＋` 按钮使用的 shell；不可用时自动回退（Windows 回退
-  `powershell`，POSIX 回退 `$SHELL`/`bash`）。
-- `defaultCwd` —— `home`（默认）从用户主目录启动；`workspace` 预留（当前等同
-  home）；绝对路径必须存在。
+- `defaultShell` —— `＋` 下拉菜单中预选的 shell（置顶并标记「默认」）；不可用
+  时自动回退（Windows 回退 `powershell`，POSIX 回退 `$SHELL`/`bash`）。
+- `defaultCwd` —— 无工作区上下文时的启动目录：`home`（默认）从用户主目录启动；
+  `workspace` 预留（当前等同 home）；绝对路径必须存在。当前会话归属工作区时
+  优先使用工作区根目录（见上）。
 - `customShells` —— 额外启动器；`command` 可为绝对路径或从 `PATH` 解析的名称
   （Windows 上叠加 `PATHEXT`）。
 
@@ -82,6 +100,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 +138,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、scope.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 +176,15 @@ 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`）。
+  （抽屉与其入口把手在 `shell.overlay`，隐形会话桥在
+  `conversation.session.header.utilities`）。