dsh-transparent-ui 0.0.0-stage → 1.3.21

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# Aqua — DSH Transparent UI Plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="icon.svg" width="64" height="64" alt="Aqua glass droplet icon">
+
+English | [中文](<docs/zh.md>)
+
+A customizable glass theme for DeepSeek Harness. The conversation toolbar, sidebar, composer, statistics bar and settings panel use translucent surfaces, with a sidebar fluid backdrop, a particle whale and an interactive mesh behind the application content.
+
+**This repository is a desktop compatibility fork, not the original theme project.**
+
+## Origin and attribution
+
+The original theme, visual design and implementation belong to the original project and its contributors:
+
+- **Original project / maintainer:** [WYH66666666/DSH-Transparent-UI-Plugin](https://github.com/WYH66666666/DSH-Transparent-UI-Plugin) — [WYH66666666](https://github.com/WYH66666666).
+- **Original project contributor:** [imccyu](https://github.com/imccyu).
+- **DSH 0.1.5-rc.2 compatibility adaptation:** [lllong0908/DSH-Transparent-UI-Plugin](https://github.com/lllong0908/DSH-Transparent-UI-Plugin).
+- **This DSH 0.2.0-rc.2 desktop compatibility fork:** [fegnze/dsh-transparent-ui](https://github.com/fegnze/dsh-transparent-ui).
+
+This fork focuses on installation, client API compatibility and desktop rendering/interaction fixes. It does not replace the original authorship. Please retain the original project, contributor and prior adaptation credits when redistributing. See [CONTRIBUTORS.md](<CONTRIBUTORS.md>) and [UPSTREAM_NOTICE.md](<UPSTREAM_NOTICE.md>) for attribution details.
+
+Distributed under [GNU AGPL-3.0](<LICENSE>); package metadata declares `AGPL-3.0-only`.
+
+## Compatibility
+
+| Item | Current target |
+| --- | --- |
+| Plugin package | `dsh-transparent-ui` |
+| Current plugin version | See [`package.json`](package.json) |
+| Target DSH version | Desktop `0.2.0-rc.2` |
+| Desktop profile | `desktop` |
+| Recommended installation | This GitHub repository, branch `main` |
+
+Other DSH versions are not guaranteed. A working legacy Web CLI does not prove compatibility with the desktop Host. Do not use an older `dsh` CLI to modify the desktop profile.
+
+## Install and upgrade
+
+### Install in the current desktop application
+
+1. Open the desktop **Plugin manager** page and choose **Add plugin**.
+2. Enter this repository URL:
+
+   ```text
+   https://github.com/fegnze/dsh-transparent-ui
+   ```
+
+3. Use branch `main` (the default); install and enable the plugin if prompted.
+4. Reload the whole desktop window, then open **Settings → General → Glass theme**.
+
+> [!IMPORTANT]
+> DSH `0.2.0-rc.2` does **not** provide an in-place upgrade or new-version check in its plugin management UI. To upgrade this GitHub installation, **uninstall the old plugin, reinstall the repository above, then reload the whole desktop window**. The list's Refresh action only reloads installed-plugin state; it does not download new commits. Check the installed version after reinstalling.
+
+The theme stores its visual preferences in the current UI origin's localStorage (video media/handles may use IndexedDB). The plugin's teardown does not explicitly erase these preferences. Clearing the application's site data can reset them; a new plugin version does not automatically reset your slider values.
+
+### Do not confuse this fork with the old npm package
+
+The legacy command below addresses a **different, unscoped package**, not this fork:
+
+```sh
+dsh plugin --profile web add dsh-client-ui-aqua
+```
+
+It is not an installation or upgrade procedure for this desktop adaptation. The old unscoped build used removed client runtime APIs. This fork's npm identity is [`dsh-transparent-ui`](https://www.npmjs.com/package/dsh-transparent-ui); use that exact package name when installing from npm. GitHub `main` may contain changes not yet published to npm, so verify the installed version rather than treating the two sources as interchangeable.
+
+The inherited [PowerShell installer](<install.ps1>) targets the older Web setup. It is retained as historical tooling, **not** as the recommended desktop installer.
+
+## Features and usage
+
+The master switch and controls are in **Settings → General**. The master switch remains accessible when the theme is off; the additional controls are hidden while disabled. Changes apply to the current UI as the controls are adjusted.
+
+- **Mica mode:** floating glass panes and themed layout. Toolbar, composer/statistics wrapper and settings panel share the same primary glass material.
+- **Compatibility mode:** retains the host layout as much as possible and applies a more conservative glass treatment. Blur/frost controls are shown in Mica mode.
+- **Sidebar fluid:** the fluid canvas follows the left sidebar's actual width, including resize/collapse. Hue and color depth are adjustable; the fluid no longer fills the chat column.
+- **Image/video wallpaper:** an alternative backdrop with separate media controls. Availability depends on browser storage, file access and media decoding.
+- **Particle whale, small fish and interactive mesh:** independently switchable background decorations. Brightness adjustment sits below the decorations, so brightening the board does not whiten them out. Foreground cards, modal masks and glass blur can still obscure them normally.
+- **Cursor glow and hover press:** glow remains on the toolbar; geometric hover tilt is deliberately excluded from the native conversation toolbar to keep its controls stationary.
+- **Under-toolbar scrolling:** in active Mica conversations, transcript content can scroll behind the toolbar; overlap follows the measured toolbar height.
+- **Theme toggle:** disabling the theme removes its visual overrides and ambient engines without editing DSH application source.
+
+### Material parameters
+
+Blur and frost are different controls: **blur softens background detail**, while **frost changes the translucent surface fill**. Element text and buttons are not faded with an overall opacity.
+
+| Parameter | Range / current behavior |
+| --- | --- |
+| Glass blur | `0–40px`; fresh-install default `20px` |
+| Frost | `0–100`; fresh-install default `7` |
+| Primary light glass | White base fill `42% × min(frost / 50, 1.4)` |
+| Primary dark glass | Neutral cool-gray base fill `50% × min(frost / 50, 1.4)` |
+| Background brightness | `50` unchanged; light mode `50–100` brightens, dark mode `0–50` darkens |
+| Mesh lines / idle nodes | Alpha `0.15 / 0.3`; pointer interaction can locally emphasize nodes |
+
+The toolbar, composer and settings panel share these primary material values. They can still look different because of different backdrop content, modal masks and shadows. The fused composer/statistics bar uses **one outer glass plate**, not two stacked fills. Other small surfaces may retain their own base alpha recipes.
+
+> [!NOTE]
+> With Aqua enabled, the floating conversation toolbar and its descendants are **non-draggable** to avoid Electron window-drag regions consuming clicks. Use other window drag areas. The plugin does not change those other regions.
+
+## What this fork changes
+
+- Migrates removed runtime/settings APIs to the current store and General-settings slot, and fixes scoped bundle identity and icon exports.
+- Keeps independently compiled CSS module identifiers distinct to avoid settings layout collisions.
+- Removes opaque structural fills that concealed ambient canvases in the current desktop layout.
+- Restricts the fluid to the sidebar, fixes mesh node double-alpha multiplication and separates decoration contrast from backdrop brightness.
+- Unifies primary glass surfaces, restores measured under-toolbar scrolling, and overrides the native toolbar drag rule with sufficient specificity.
+
+These are compatibility and behavior changes on top of the original theme. They are not claims of original authorship or universal support for every DSH/plugin combination.
+
+## Development and verification
+
+Use Node.js `22+`. The build requires `esbuild`; the simulated-DOM tests also require `happy-dom`. If the declared DSH development packages are available in your environment:
+
+```sh
+npm install --legacy-peer-deps
+npm run bundle
+npm test
+```
+
+For a standalone checkout without the original DSH monorepo or access to its development packages, install only the build/test tools in an isolated directory (POSIX example, run from the repository root):
+
+```sh
+npm install --prefix .npm-stage/build-tools --no-package-lock esbuild@^0.25.12 happy-dom@^20.0.0
+# Only for a fresh checkout with no existing node_modules directory:
+ln -s .npm-stage/build-tools/node_modules node_modules
+npm run bundle
+npm test
+```
+
+The [build script](<scripts/build.mjs>) creates the Host entry and DSH module-loader client bundle. This repository ships the generated runtime bundle so GitHub installations can run without the original author's monorepo. DSH client peers are provided by the desktop Host; the isolated build tools do not make it a standalone web application.
+
+Optional Chromium interaction regression (supply your own browser executable):
+
+```sh
+DSH_TEST_CHROME='/path/to/chrome' npm run test:browser
+```
+
+The [browser regression](<test/toolbar.browser.mjs>) uses an isolated headless fixture with desktop drag rules, display-contents slot wrappers, under-toolbar scrolling and a high-z body overlay. It checks computed drag exclusions, stable hover geometry and **100 consecutive input clicks**, with hover press enabled/disabled. Temporary fixture/browser profiles stay under ignored `.npm-stage/`.
+
+### Verification boundaries
+
+- `npm test`: simulated DOM lifecycle/settings/material checks and instrumented Canvas draw calls; not a GPU visual test.
+- `npm run test:browser`: real Chromium fixture hit-testing; **not** attachment to the live DSH desktop or a test of Electron's macOS native input routing.
+- Live desktop acceptance is still required for the latest toolbar fix, native window behavior, video/WebGL and combinations with other plugins.
+
+When reporting a problem, include the DSH version, installed plugin version, Mica/Compatibility mode, color scheme, relevant slider values and a screenshot or Console error. Do not paste chat contents, credentials or private file data into a public issue. Report fork-specific issues to [this repository's issue tracker](https://github.com/fegnze/dsh-transparent-ui/issues).
+
+## Upstream visual examples
+
+The images below are retained from the inherited repository and illustrate the original theme. **They are not screenshots of this fork's current desktop acceptance tests**; fluid placement and other details can differ.
+
+![Upstream Aqua example 1](<assets/1.png>)
+![Upstream Aqua example 2](<assets/2.png>)
+![Upstream Aqua example 3](<assets/3.png>)
+![Upstream Aqua example 4](<assets/4.png>)

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# Register the exact package installed by the plugin manager.
+# The host import and browser roster must resolve the same package identity.
+- insert:
+    - id: ui-aqua
+      name: 'dsh-transparent-ui'

package/docs/zh.md

@@ -0,0 +1,153 @@
+# Aqua — DSH 透明玻璃主题插件
+
+<img src="../icon.svg" width="64" height="64" alt="Aqua 玻璃水滴图标">
+
+[English](<../README.md>) | 中文
+
+Aqua 为 DeepSeek Harness 提供可调节的玻璃质感主题：会话顶部操作栏、侧边栏、输入框、统计栏和设置面板使用半透明材质，左侧流体背景、粒子鲸鱼与交互网格位于应用内容下方。
+
+**本仓库是桌面版兼容适配分支，不是原主题项目。**
+
+## 来源与署名
+
+原主题、视觉设计和原始实现归属于原项目及其贡献者：
+
+- **原项目／维护者：**[WYH66666666/DSH-Transparent-UI-Plugin](https://github.com/WYH66666666/DSH-Transparent-UI-Plugin) — [WYH66666666](https://github.com/WYH66666666)。
+- **原项目贡献者：**[imccyu](https://github.com/imccyu)。
+- **DSH 0.1.5-rc.2 兼容适配：**[lllong0908/DSH-Transparent-UI-Plugin](https://github.com/lllong0908/DSH-Transparent-UI-Plugin)。
+- **本 DSH 0.2.0-rc.2 桌面兼容分支：**[fegnze/dsh-transparent-ui](https://github.com/fegnze/dsh-transparent-ui)。
+
+本分支主要修复安装、客户端 API 兼容性、桌面渲染与交互问题，不替代原项目的作者身份。二次分发时请保留原项目、原贡献者及历次适配者的署名。贡献者列表见 [CONTRIBUTORS.md](<../CONTRIBUTORS.md>)，来源说明见 [UPSTREAM_NOTICE.md](<../UPSTREAM_NOTICE.md>)。
+
+沿用 [GNU AGPL-3.0 许可证](<../LICENSE>)；包元数据声明为 `AGPL-3.0-only`。
+
+## 兼容范围
+
+| 项目 | 当前目标 |
+| --- | --- |
+| 插件包名 | `dsh-transparent-ui` |
+| 当前插件版本 | 见 [`package.json`](../package.json) |
+| 目标 DSH 版本 | 桌面版 `0.2.0-rc.2` |
+| 桌面配置 Profile | `desktop` |
+| 推荐安装来源 | 本 GitHub 仓库的 `main` 分支 |
+
+其他 DSH 版本不保证兼容。旧版 Web CLI 可以运行，不代表它与桌面 Host 兼容；不要使用旧版 `dsh` CLI 修改桌面 Profile。
+
+## 安装与更新
+
+### 在当前桌面版安装
+
+1. 打开桌面版的**插件管理器**页面，选择**添加插件**。
+2. 输入本仓库地址：
+
+   ```text
+   https://github.com/fegnze/dsh-transparent-ui
+   ```
+
+3. 使用 `main` 分支（默认）；安装完成后，按提示启用插件。
+4. 刷新整个桌面窗口，再打开**设置 → 通用设置 → 玻璃主题**。
+
+> [!IMPORTANT]
+> DSH `0.2.0-rc.2` 的插件管理界面暂不提供原地升级或新版检查。更新本 GitHub 安装需要**先卸载旧版，再用上述仓库地址重新安装，最后刷新整个桌面窗口**。插件列表的「刷新」只重新读取已安装状态，不会下载新提交。重装后请确认实际安装版本。
+
+主题视觉参数保存在当前界面来源的 localStorage 中，视频媒体／文件句柄可能使用 IndexedDB。插件关闭或清理时不会主动删除这些偏好；清除应用站点数据可能重置它们。安装新版本不会自动重置你已经保存的滑块值。
+
+### 不要混淆旧 npm 包与本分支
+
+下面的旧版命令指向另一个**未带作用域的包**，不是本仓库：
+
+```sh
+dsh plugin --profile web add dsh-client-ui-aqua
+```
+
+它不是本桌面适配版的安装或更新方式。旧的未带作用域构建使用过已移除的客户端 runtime API。本分支的 npm 身份是 [`dsh-transparent-ui`](https://www.npmjs.com/package/dsh-transparent-ui)，从 npm 安装时应使用此完整包名。GitHub `main` 可能包含尚未发布到 npm 的变更，应核对已安装版本，不要把两种来源视为完全相同。
+
+继承保留的 [PowerShell 安装器](<../install.ps1>) 面向旧版 Web 配置，仅作历史工具保留，**不作为推荐的桌面安装入口**。
+
+## 功能与使用
+
+总开关和调节项位于**设置 → 通用设置**。关闭主题后总开关仍可访问，额外调节项会隐藏；调节时参数即时应用于当前界面。
+
+- **云母效果：**使用悬浮玻璃片和主题布局。顶栏、输入框／统计栏外层、设置面板共用主玻璃材质。
+- **兼容模式：**尽量保留宿主排版，采用较保守的玻璃处理。玻璃模糊度和磨砂度调节项在云母模式显示。
+- **侧栏流体：**流体画布随左侧栏实际宽度调整，支持缩放和折叠；可调色调、颜色深浅，不再铺满聊天主区域。
+- **图片／视频壁纸：**作为另一种背景来源，提供独立媒体调节；可用性取决于浏览器存储、文件访问权限和解码能力。
+- **粒子鲸鱼、小鱼、网状交互：**可分别开关的背景装饰。亮度遮罩位于装饰下方，提亮背景不会将装饰一起冲淡；前景卡片、弹窗遮罩和玻璃模糊仍会正常遮盖它们。
+- **鼠标辉光／悬停下压：**顶栏保留辉光，但原生会话顶栏不参与几何倾斜，避免交互控件随鼠标移动。
+- **顶栏背后滚动：**云母模式下的活动会话允许聊天内容从顶栏背后经过，重叠范围根据实际顶栏高度计算。
+- **主题开关：**关闭时移除主题视觉覆盖和装饰引擎，不修改 DSH 应用源码。
+
+### 材质参数
+
+模糊度与磨砂度是两种控制：**模糊度让背景细节变模糊，磨砂度调节玻璃填充的遮盖程度**。不会用元素整体透明度同时淡化文字和按钮。
+
+| 参数 | 范围／当前行为 |
+| --- | --- |
+| 玻璃模糊度 | `0–40px`；无已有偏好时默认 `20px` |
+| 磨砂度 | `0–100`；无已有偏好时默认 `7` |
+| 主玻璃浅色填充 | 白色基础填充 `42% × min(磨砂度 / 50, 1.4)` |
+| 主玻璃深色填充 | 中性冷灰基础填充 `50% × min(磨砂度 / 50, 1.4)` |
+| 背景亮度 | `50` 原样；浅色模式 `50–100` 提亮，深色模式 `0–50` 压暗 |
+| 网格线条／静止节点 | Alpha `0.15 / 0.3`；鼠标交互时可局部突出节点 |
+
+顶栏、输入栏、设置面板共用这些主材质参数；背后的内容、弹窗遮罩与阴影不同，视觉观感仍可能不同。输入框与统计栏融合时只由**一个外层玻璃片**承载材质，不重复叠加填充。其他小型表面可能保留各自的基础透明度配方。
+
+> [!NOTE]
+> 启用 Aqua 后，浮动会话顶栏及其子元素**不作为窗口拖拽区域**，避免 Electron 原生拖拽区域吞掉点击。请使用窗口其他拖拽区域；插件不修改这些其他区域。
+
+## 本分支的适配内容
+
+- 将已移除的 runtime／设置 API 迁移到当前 store 和通用设置插槽，修正带作用域的组合包身份及图标导出。
+- 隔离独立编译的 CSS Module 标识符，避免设置布局发生样式串扰。
+- 清除当前桌面布局中遮住装饰画布的不透明结构底色。
+- 限制流体为左侧栏，修正网格节点透明度重复相乘，并将装饰对比度与背景亮度分层处理。
+- 统一主玻璃材质，恢复按实际高度计算的顶栏背后滚动，并以足够优先级覆盖顶栏原生拖拽规则。
+
+这些是基于原主题的兼容和行为调整，不代表本分支原创整个主题，也不保证全部 DSH／插件组合都能正常工作。
+
+## 开发与验证
+
+使用 Node.js `22+`。构建需要 `esbuild`，模拟 DOM 测试还需要 `happy-dom`。环境可以安装声明的 DSH 开发包时：
+
+```sh
+npm install --legacy-peer-deps
+npm run bundle
+npm test
+```
+
+独立检出、没有原 DSH monorepo 或无法获取其开发包时，可仅在隔离目录安装构建／测试工具（POSIX 示例，在仓库根目录执行）：
+
+```sh
+npm install --prefix .npm-stage/build-tools --no-package-lock esbuild@^0.25.12 happy-dom@^20.0.0
+# 仅适用于尚无 node_modules 目录的新检出：
+ln -s .npm-stage/build-tools/node_modules node_modules
+npm run bundle
+npm test
+```
+
+[构建脚本](<../scripts/build.mjs>) 生成 Host 入口和 DSH Module Loader 客户端包。本仓库随源码提供可运行的构建包，使 GitHub 安装不依赖原作者的 monorepo。DSH 客户端 peer 由桌面 Host 提供；隔离工具安装不会让插件成为独立 Web 应用。
+
+可选的真实 Chromium 交互回归（自行指定浏览器可执行文件）：
+
+```sh
+DSH_TEST_CHROME='/path/to/chrome' npm run test:browser
+```
+
+[浏览器回归脚本](<../test/toolbar.browser.mjs>) 使用独立无头测试页，包含桌面拖拽规则、`display:contents` 插槽包装、顶栏背后滚动和正文高层级遮挡元素。检查实际拖拽排除样式、稳定的悬停位置，并分别在悬停下压开启／关闭时验证**连续 100 次输入点击**。临时测试页／浏览器 Profile 位于已忽略的 `.npm-stage/`。
+
+### 验证边界
+
+- `npm test`：模拟 DOM 的生命周期、设置和材质检查，以及带记录的 Canvas 绘制调用；不是 GPU 视觉测试。
+- `npm run test:browser`：真实 Chromium 测试页的命中检查；**不会连接真实 DSH 桌面，也不能验证 Electron 的 macOS 原生输入路由**。
+- 最新顶栏修复、原生窗口行为、视频／WebGL、与其他插件组合，仍需要真实桌面验收。
+
+反馈问题时请提供 DSH 版本、实际安装的插件版本、云母／兼容模式、深浅色模式、相关滑块值，以及截图或控制台错误。不要向公开 Issue 粘贴聊天正文、凭证或私密文件数据。本分支问题请提交至[本仓库 Issue](https://github.com/fegnze/dsh-transparent-ui/issues)。
+
+## 原项目效果示例
+
+下列图片继承自上游仓库，用于展示原主题。**不是本分支当前桌面验收截图**；流体显示范围及其他细节可能与本分支不同。
+
+![原项目 Aqua 示例 1](<../assets/1.png>)
+![原项目 Aqua 示例 2](<../assets/2.png>)
+![原项目 Aqua 示例 3](<../assets/3.png>)
+![原项目 Aqua 示例 4](<../assets/4.png>)

package/icon.svg

@@ -0,0 +1,35 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64">
+  <title>Aqua glass droplet</title>
+  <defs>
+    <linearGradient id="aqua-body" x1="18" y1="12" x2="46" y2="57" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#97F6FF"/>
+      <stop offset=".42" stop-color="#34CFEA"/>
+      <stop offset="1" stop-color="#4263F4"/>
+    </linearGradient>
+    <linearGradient id="aqua-edge" x1="19" y1="10" x2="45" y2="58" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#D8FCFF"/>
+      <stop offset=".55" stop-color="#72E1FF"/>
+      <stop offset="1" stop-color="#587CFF"/>
+    </linearGradient>
+    <linearGradient id="aqua-wave" x1="12" y1="34" x2="48" y2="51" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#9FFFF3"/>
+      <stop offset="1" stop-color="#25B8DE"/>
+    </linearGradient>
+    <linearGradient id="aqua-gloss" x1="23" y1="19" x2="35" y2="39" gradientUnits="userSpaceOnUse">
+      <stop stop-color="white" stop-opacity=".85"/>
+      <stop offset="1" stop-color="white" stop-opacity=".1"/>
+    </linearGradient>
+    <clipPath id="aqua-clip">
+      <path d="M32 7C28 14 12 29 12 39a20 20 0 0 0 40 0C52 29 36 14 32 7Z"/>
+    </clipPath>
+  </defs>
+  <path d="M32 7C28 14 12 29 12 39a20 20 0 0 0 40 0C52 29 36 14 32 7Z" fill="url(#aqua-body)"/>
+  <g clip-path="url(#aqua-clip)">
+    <path d="M10 38c9-7 16-7 24-2 8 5 13 5 20 1v26H10Z" fill="url(#aqua-wave)" fill-opacity=".8"/>
+    <path d="M10 46c9 5 16 5 24 0s13-5 20-1v18H10Z" fill="#4364F2" fill-opacity=".7"/>
+    <path d="M12 38c8-6 14-6 22-2s13 5 18 2" fill="none" stroke="#D4FFFF" stroke-opacity=".65" stroke-width="1.5"/>
+  </g>
+  <path d="M32 7C28 14 12 29 12 39a20 20 0 0 0 40 0C52 29 36 14 32 7Z" fill="none" stroke="url(#aqua-edge)" stroke-width="1.5" stroke-linejoin="round"/>
+  <path d="M29 19c-5 6-11 13-11 19" fill="none" stroke="url(#aqua-gloss)" stroke-width="4" stroke-linecap="round"/>
+  <path d="m47 11 1.5 4.5L53 17l-4.5 1.5L47 23l-1.5-4.5L41 17l4.5-1.5Z" fill="#AEF9FF"/>
+</svg>