dsh-conversation-aurora 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 conversation-aurora contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# dsh-conversation-aurora
 
-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.
+给 DSH 对话区加一层**整屏动效背景**：把整块画布当背景，用 Canvas 画星空、代码雨、电路、小猫、小女生、赛车、飘雪、肥皂泡；正文列用一层按列宽计算的纱罩住，保证可读。
+
+- 包名：`dsh-conversation-aurora`
+- 插件目录：`conversation-aurora/`
+- patch 行 id：`dsh-conversation-aurora`
+- Client 工厂 id：`dsh-conversation-aurora`（必须与包名一致）
+- 宿主半区：`index.js`，空的（只需要一行可加载）
+
+---
+
+## 安装
+
+**从 npm 安装（推荐）**
+
+插件页 → **添加插件** → 输入包名 `dsh-conversation-aurora` → 安装源选 **npm 官方** → 安装 → **立即启用**。
+
+> 国内镜像（`registry.npmmirror.com`）同步有延迟；刚发布时请先用官方源。
+
+**从本地目录安装（开发用）**
+
+插件页 → 添加插件 → 填本目录的绝对路径 → 安装 → 立即启用。
+
+**卸载**：插件页 → 卸载。效果随插件 context 一起回收，页面恢复原样。
+
+---
+
+## 用它
+
+| 快捷键 | 作用 |
+| --- | --- |
+| `Alt+T` | 换下一个背景（8 个循环，选择会记住） |
+| `Alt+D` | 浅色 / 深色主题互换（走宿主 `theme.setTheme`，与「设置 → 外观」同步） |
+
+**它只在"你干活"的时候出现**：任何工具在跑、或回合进行中，背景才播放；空闲、切会话、窗口隐藏时立刻停掉 `requestAnimationFrame` 并淡出，两侧恢复普通白纸。
+
+**每个会话自动分配不同主题**（按 `data-conversation-session` 哈希）。按过 `Alt+T` 之后会变成全局固定主题；想恢复"每会话自动"，删掉 `localStorage` 里的 `dsh.conversation-aurora.theme` 即可。
+
+---
+
+## 8 个背景
+
+| 主题 | 内容 |
+| --- | --- |
+| 星空跃迁 | 星点从中心向外飞出，长条纹 |
+| 代码雨 | 竖列字符下落，带拖尾 |
+| 电路脉冲 | 直角走线 + 沿线跑的光点 |
+| 小猫散步 | 矢量剪影小猫走路、尾巴摆动、留下爪印 |
+| 小女生 | 连衣裙剪影 + 马尾 + 牵着气球，一路小跑掉小心心 |
+| 赛车 | 横向速度线 + 小车剪影 |
+| 飘雪 | 雪花慢落 + 摇摆 |
+| 肥皂泡 | 径向渐变薄膜 + 高光，缓缓升起 |
+
+**加一种新背景**：在 `client.js` 里写一个 `themeXxx(g)`，返回 `{ resize(), step(dt) }`，再往 `STAGE_THEMES` 数组加一行 `{ id, name, create }`。`g` 提供 `{ ctx, w, h, pal }`。
+
+---
+
+## 可读性怎么保证
+
+- `.dsh-stage__veil` 是一条**按 `--dsh-chat-content-width` 计算**的横向纱：正文列内 84% 遮盖，列外 110px 内快速放开，两侧完全透明。
+- 浅色主题用 **`multiply`（正片叠底）+ 墨色**（靛蓝 / 紫 / 青），像印在白纸上；深色主题用 **`lighter`（加色）+ 亮色**，才有发光感。见 `stagePalette()`。
+- 背景层是 `z-index:-1`，永远在正文之下，`pointer-events:none`，不挡任何交互。
+
+---
+
+## 调参
+
+视觉参数集中在 `client.js` 顶部：
+
+| 位置 | 含义 |
+| --- | --- |
+| `TUNE.holdIdleMs` | 工具停下后多久淡出（默认 420ms，防抖） |
+| `TUNE.switchQuietMs` | 切会话后的静默期（默认 600ms） |
+| `stagePalette()` | 浅色/深色两套墨色 + 混合模式 |
+| `THEMES` 里各主题的常量 | 数量、速度、尺寸 |
+| `.dsh-stage__veil` 的 `.84` | 文字列遮盖强度，调高更护眼、调低更炫 |
+
+改完 `client.js` 后**刷新页面**即可（`Ctrl+R`）。
+
+---
+
+## 已知限制
+
+1. **依赖宿主的 DOM 语义属性**：`[data-conversation-content]` / `[data-tool][data-state]` / `[data-chat-running]` / `[data-streaming]` / `[data-conversation-session]`。DSH 大版本升级后如果这些改名，插件会安静地什么都不做（不会报错、不会挡交互）。
+2. **没有"背景层"插槽**：DSH 目前没有这个扩展点，所以背景层是挂在对话画布元素内部的（`z-index:-1`）。这是刻意偏离「只能注册进 slot」的地方，随插件停用一起消失。
+3. **切会话会静默 600ms**：避免把上一轮残留的工具行当成"正在工作"，看到几秒特效。
+4. **减少动态效果**：系统开启后只画一帧静止画面，不跑 `requestAnimationFrame`。
+5. **性能**：只有一张 canvas；每帧只做绘制，无 `filter`/`backdrop-filter`；空闲时 rAF 归零。
+6. **不做设置项**：没有「设置」里的面板，调参靠改常量。
+
+---
+
+## 开发
+
+```powershell
+node --check client.js                 # 语法
+node tools/rename.mjs <新包名>          # 三处 id 一起改（发布前用）
+npm pack --dry-run                     # 看会发出去哪些文件
+```
+
+发布：`npm version patch` → `npm publish`（需要 2FA 验证码）。
+
+## 文件
+
+```text
+conversation-aurora/
+├─ package.json        dsh.bundle.patch + dsh.client
+├─ cordis.patch.yml    插入一行
+├─ index.js            Host 半区（空）
+├─ client.js           Client 半区：状态机 + 8 个背景主题
+├─ locale/zh.json      插件页标题与描述
+├─ locale/en.json
+├─ icon.svg
+├─ preview.html        离线预览（直接加载 client.js）
+├─ tools/rename.mjs    发布前改名脚本
+├─ LICENSE
+└─ README.md
+```