deepseek-harness-background 0.5.5 → 0.6.0

package/README.md

@@ -42,10 +42,10 @@ The look (fixed wallpaper layer + theme-aware scrim + translucent glass panels d
 
 - **Local upload** — pick a JPG / PNG / WebP / GIF from your computer; the plugin stores it under the harness home and serves it over a same-origin route (admitted only when the declared MIME, detected signature and extension all agree).
 - **Paste a URL** — drop an `http(s)` image link and press Enter.
-- **In-panel live preview** — a preview surface at the top of the row renders the image + scrim + a frosted glass bubble; dragging any slider repaints it instantly.
+- **In-panel live preview** — a preview surface at the top of the row renders the image + scrim + a frosted glass bubble; dragging any slider repaints it instantly. The card's box tracks the live window ratio, so the crop it shows is the crop the backdrop paints.
 - **Stepped sliders** — ratio controls snap in **5% steps**, blur radii in 1/2px steps; dragging only repaints, **release commits** (one write per gesture, no jank).
 - **Five controls** — wallpaper opacity, readability scrim, panel opacity, frosted-glass blur, and wallpaper blur.
-- **Fit modes** — `cover` (fill, crop) or `contain` (whole image).
+- **Fit modes & framing** — `cover` (fill, crop) or `contain` (whole image). Under `cover` the preview card is a **pan surface**: it can move the image along the crop's slack axis (up/down when the art fills the width, left/right when it fills the height) with a four-way move cursor — drag, arrow keys (Shift for a coarse step), double-click or the recenter chip. `contain` letterboxes and offers no pan; either way the card keeps tracking the window ratio.
 - **Theme-aware scrim** — the light theme uses a white veil (lifts the art so dark text keeps contrast); the dark theme automatically switches to a black veil (dims the art so light text keeps contrast).
 - **Frosted glass (whitelisted)** — while a background is active, only the surfaces that float as small cards over the wallpaper turn into translucent glass (specular sheen + `backdrop-filter`): the composer card and message bubbles, code blocks / terminal / diff / tool-IO cards / skill & MCP call cards and inline code, the agent task strips and their takeover panels (approval / question / plan review), the chrome buttons (new session, composer plus, scroll-to-bottom), the load-earlier history button, the subagent lineage popover, the sidebar build badge, and the home hero "preview" badge — every glassed surface carries the full recipe (fill + sheen + blur), never translucency without frost. Reading surfaces — dialogs, the settings UI, menus, tooltips, toasts, hover fills and every accent (the send button stays blue) — keep their **official opaque paints** so nothing legible turns washy (the one documented exception: the turn rail's hover preview, which is rail chrome over the art and joins the glass sheet). The blur radius is driven by the glass-blur slider; `panelOpacity` at 100% restores the official paints on the whitelisted list too.
 - **Third-party glass registry** — any plugin can register its own panels into the same frosted-glass system through the published bridge (`window.__DSH_BACKGROUND_GLASS__` global + the `dsh-background-glass:ready` event): *token* mode adds the missing sheen + blur chain when the panel already fills with an overridden `--dsw-*` token, *fill* mode takes the fill over as well; every rule sits under the `data-dsh-bg-glass` gate so it toggles with the glass automatically. Consumers take zero dependencies and degrade gracefully when this plugin is absent; the whole bridge tears down with it. See [docs/GLASS_API.md](docs/GLASS_API.md).
@@ -58,7 +58,9 @@ The look (fixed wallpaper layer + theme-aware scrim + translucent glass panels d
 
 | Plugin release | Supported dsh versions |
 | --- | --- |
-| **0.5.5** | **dsh 0.1.2-rc.1 and 0.1.3-alpha.x (verified on alpha.2), plus 0.1.5-alpha.1/alpha.2/rc.1/rc.2 (verified on rc.2), 0.1.6-alpha.1/alpha.2 and 0.1.7-alpha.1** |
+| **0.6.0** | **dsh 0.1.2-rc.1 and 0.1.3-alpha.x (verified on alpha.2), plus 0.1.5-alpha.1/alpha.2/rc.1/rc.2 (verified on rc.2), 0.1.6-alpha.1/alpha.2, 0.1.7-alpha.1/alpha.2/rc.1/rc.2 (verified on rc.2) and 0.2.0-rc.1 (verified on rc.1)** |
+| 0.5.6 | dsh 0.1.2-rc.1 and 0.1.3-alpha.x, plus 0.1.5-alpha.1/alpha.2/rc.1/rc.2 and 0.1.6-alpha.1/alpha.2, 0.1.7-alpha.1/alpha.2/rc.1/rc.2 |
+| 0.5.5 | dsh 0.1.2-rc.1 and 0.1.3-alpha.x, plus 0.1.5-alpha.1/alpha.2/rc.1/rc.2 and 0.1.6-alpha.1/alpha.2, 0.1.7-alpha.1 |
 | 0.5.3 – 0.5.4 | dsh 0.1.2-rc.1 and 0.1.3-alpha.x, plus 0.1.5-alpha.1/alpha.2/rc.1/rc.2 and 0.1.6-alpha.1/alpha.2 |
 | 0.5.2 | dsh 0.1.1-rc.2 and 0.1.2-alpha.1 ~ alpha.5 |
 
@@ -112,14 +114,14 @@ dsh --profile web
 | 面板不透明度 / Panel opacity | `0..100%` surface transparency (5% steps); at `100%` the official panels stay opaque (no glass). |
 | 毛玻璃模糊 / Glass blur | `0..40px` `backdrop-filter` blur on the translucent surfaces (1px steps). |
 | 壁纸模糊 / Wallpaper blur | `0..60px` blur of the wallpaper image itself (2px steps). |
-| 填充方式 / Fit | `cover` or `contain`. |
+| 填充方式 / Fit | `cover` (fill, crop) or `contain` (whole image); under `cover` the preview drags the image along the crop's slack axis (arrow keys nudge, double-click or the recenter chip recenters). |
 | 会话时间线 / Timeline | on/off switch for the conversation timeline (default on). On dsh ≥ 0.1.2-rc.1 the row is labelled 会话时间线增强 / *enhancement*: the official rail stays and this only improves its behaviour (smooth jumps for loaded turns); turning it off restores stock behaviour. |
 
 5. **清除背景** removes the background and restores the stock look.
 
 ## How it works
 
-- The **settings row** lives in the official General settings section (`settings.general.item` slot), next to the Appearance row. Its chrome uses only `--dsw-alias-*` design tokens (buttons / pills / segmented control / slider track match the official shell); sliders are native `input[type=range]` with 5% / 1–2px steps and release-commit.
+- The **settings row** lives in the official General settings section (`settings.general.item` slot), next to the Appearance row. Its chrome uses only `--dsw-alias-*` design tokens (buttons / pills / segmented control / slider track match the official shell); sliders are native `input[type=range]` with 5% / 1–2px steps and release-commit. The preview card's box is computed from the live window ratio (shrinking and centering as a whole past a height cap), and the wallpaper framing is stored as normalized 0..1 offsets mapped onto `object-position` — so one stored framing holds across every window size and source.
 - The plugin's own host routes (`/api/bg-wallpaper/*`: `settings`, `upload`, `image/<id>`) read/write the section and serve uploads with same-origin + size caps + MIME/signature checks + a path-escape fence. A custom route family is used because the api-proxy settings allowlist does not expose third-party namespaces over the settings RPC.
 - The background is drawn as a fixed `z-index:-2` wallpaper layer plus a `z-index:-1` scrim on `body`, toggled by the `data-dsh-bg` attribute; the scrim switches white/black by `data-ds-dark-theme` in the injected stylesheet. Frosted glass is whitelist-scoped: only the whitelisted surfaces get `--dsw-*` surface-token overrides, while everything else is painted by explicit `data-dsh-bg-glass`-gated rules carrying the FULL recipe (fill + sheen + blur chain): the three chrome buttons, the load-earlier history button, the composer dock family (agent task strips TodoPanel / GoalBar / QueueDock and their takeover panels — approval, question, plan review — whose tokens turn translucent and need the blur added), the subagent lineage popover, the home hero preview badge and the sidebar build badge — every other official token and reading surface (menus, dialogs, tooltips, toasts) stays untouched.
 - The **timeline** is registered into the `conversation.input.dock` slot (per-session lifecycle). Detection is a capability check on the slot props rather than a version compare: the official rail is rendered from the very index `ui-chat` publishes as a session hook (`useChat(s => s.navigation.items())`, dsh >= 0.1.2), so the presence of that hook *is* the presence of the official rail — and it survives pre-releases, forks and deployments that mount a different conversation target. With the hook the plugin renders nothing and intercepts clicks on the official rail's **loaded** marks in the **capture** phase (React 18 dispatches `onClick` from the root container during the bubble phase, so a capture listener on the rail runs first and `stopImmediatePropagation()` keeps the stock handler from ever firing) — resolving the click index against the merged ladder the kernel actually renders (`turnOutline` outline + loaded window, mirroring `mergeTurnRailItems` in ui-chat), with marks outside the loaded window (no anchor key) left to the kernel's own load-through jump — and while one of those kernel jumps is still paging (a mark pulses `aria-busy`) the plugin stands down entirely, because the kernel's loaded branch cancels its own pending jump before landing and an interception would bypass that cancellation. The official hover preview joins the glass sheet under the wallpaper gate (same explicit fill recipe as the composer card), and the tick column carries the DeepSeek-web edge dissolve. Two rail generations are handled by capability, never by version compare: the frame-style rail (dsh 0.1.2-rc.1 … 0.1.6), whose marks are mapped by geometry over the metrics it publishes inline, and the virtualized rail (dsh 0.1.7+), whose rendered marks carry their own ladder index and which mounts only a window of them at a time. Supported baseline: dsh >= `0.1.2-rc.1`; older dsh (0.1.2-alpha.x and 0.1.1-rc.2 or earlier) installs an older plugin release (see Version compatibility).

package/README.zh.md

@@ -42,10 +42,10 @@
 
 - **本地上传** —— 从电脑选择 JPG / PNG / WebP / GIF 图片；插件存入 harness home 目录，经同源路由提供（仅当声明的 MIME、探测到的文件签名与扩展名三者一致才被接受）。
 - **粘贴 URL** —— 输入 `http(s)` 图片链接后回车即可。
-- **面板内实时预览** —— 设置行顶部有预览卡：图片 + 遮罩 + 毛玻璃气泡；拖动任意滑块即时重绘，所见即所存。
+- **面板内实时预览** —— 设置行顶部有预览卡：图片 + 遮罩 + 毛玻璃气泡；拖动任意滑块即时重绘，所见即所存。预览卡比例跟随当前窗口视口，卡片里裁出的就是真实背景裁出的。
 - **阻尼滑块** —— 比例类滑块按 **5% 步进**、模糊类按 1/2px 步进吸附；拖动过程只改画面，**松手才保存**（每次手势一次写入，不再抖动）。
 - **五个调节项** —— 壁纸不透明度、可读性遮罩、面板不透明度、毛玻璃模糊、壁纸模糊。
-- **填充方式** —— `cover`（铺满、裁剪）或 `contain`（完整、留白）。
+- **填充方式与取景** —— `cover`（铺满、裁剪）或 `contain`（完整、留白）。铺满时预览卡是一块**取景面**：可沿图片多出来的那一轴移动图片（左右铺满时上下移、上下铺满时左右移），悬停显示四向移动光标，拖动即可取景，方向键微调（Shift 粗调），双击或「重置位置」回中。`contain` 完整留白、不提供位移；两种方式下预览卡比例都跟随窗口。
 - **主题自适应遮罩** —— 浅色主题用白色纱帘（把图片提亮保持深色文字对比度），深色主题自动换成黑色纱帘（压暗图片保持浅色文字对比度）。
 - **毛玻璃（白名单制）** —— 启用背景后，只有以小卡片/小按钮形态悬浮在壁纸上的表面才会变成半透明玻璃（顶部白色高光渐变 + `backdrop-filter`）：输入框卡片与消息气泡、代码块 / 终端 / diff / 工具 IO 卡 / 技能与 MCP 调用卡与行内代码、agent 任务条及其接管面板（审批 / 提问 / 计划评审）、三个铬件按钮（新会话、输入框加号、回到底部）、「加载更早」历史按钮、标题栏展开的子代理列表面板、侧栏构建徽标，以及首页右上角的「预览版」徽标——每块玻璃面都带完整配方（填充 + 高光 + 模糊），绝无"只透明不磨砂"的残缺面。阅读型表面——对话框、设置界面、菜单、Tooltip、Toast、悬停填充与所有强调色（发送键保持品牌蓝）——一律保留**官方不透明样式**，保证可读性（唯一例外：时间线导航轨的悬浮预览卡，它是画在壁纸上的导航铬件，加入玻璃配方）。模糊半径由「毛玻璃模糊」滑块驱动；「面板不透明度」调至 100% 时白名单表面也恢复官方原样。
 - **第三方毛玻璃接口** —— 内置毛玻璃注册表（`window.__DSH_BACKGROUND_GLASS__` 全局 + `dsh-background-glass:ready` 事件）：任何插件都可把自家面板的选择器注册进来，套上与内置表面完全一致的配方——`token` 模式为已使用被覆盖 `--dsw-*` 填充的面板补齐高光+模糊链，`fill` 模式连填充一并接管；规则统一挂在 `data-dsh-bg-glass` 门控下随玻璃自动开关。消费方零依赖、未安装本插件时优雅降级，本插件卸载时整桥拆除。详见 [docs/GLASS_API.zh.md](docs/GLASS_API.zh.md)。
@@ -57,7 +57,9 @@
 
 | 本插件版本 | 支持的 dsh 版本 |
 | --- | --- |
-| **0.5.5** | **dsh 0.1.2-rc.1 与 0.1.3-alpha.x（已在 alpha.2 验证），另支持 0.1.5-alpha.1 / alpha.2 / rc.1 / rc.2（已在 rc.2 验证）、0.1.6-alpha.1 / alpha.2 与 0.1.7-alpha.1** |
+| **0.6.0** | **dsh 0.1.2-rc.1 与 0.1.3-alpha.x（已在 alpha.2 验证），另支持 0.1.5-alpha.1 / alpha.2 / rc.1 / rc.2（已在 rc.2 验证）、0.1.6-alpha.1 / alpha.2、0.1.7-alpha.1 / alpha.2 / rc.1 / rc.2（已在 rc.2 验证）与 0.2.0-rc.1（已在 rc.1 验证）** |
+| 0.5.6 | dsh 0.1.2-rc.1 与 0.1.3-alpha.x，另支持 0.1.5-alpha.1 / alpha.2 / rc.1 / rc.2 与 0.1.6-alpha.1 / alpha.2、0.1.7-alpha.1 / alpha.2 / rc.1 / rc.2 |
+| 0.5.5 | dsh 0.1.2-rc.1 与 0.1.3-alpha.x，另支持 0.1.5-alpha.1 / alpha.2 / rc.1 / rc.2 与 0.1.6-alpha.1 / alpha.2、0.1.7-alpha.1 |
 | 0.5.3 – 0.5.4 | dsh 0.1.2-rc.1 与 0.1.3-alpha.x，另支持 0.1.5-alpha.1 / alpha.2 / rc.1 / rc.2 与 0.1.6-alpha.1 / alpha.2 |
 | 0.5.2 | dsh 0.1.1-rc.2 与 0.1.2-alpha.1 ~ alpha.5 |
 
@@ -110,14 +112,14 @@ dsh --profile web
 | 面板不透明度 | `0..100%` 表面透明程度（5% 步进）；为 `100%` 时官方面板保持不透明（无玻璃）。 |
 | 毛玻璃模糊 | `0..40px` 半透明表面上的 `backdrop-filter` 模糊（1px 步进）。 |
 | 壁纸模糊 | `0..60px` 壁纸图片本身的模糊（2px 步进）。 |
-| 填充方式 | `cover`（铺满）或 `contain`（完整）。 |
+| 填充方式 | `cover`（铺满）或 `contain`（完整）。铺满时可在预览卡内拖动图片取景；方向键微调，双击或「重置位置」回中。 |
 | 会话时间线 | 会话时间线的开关（默认开启）。dsh ≥ 0.1.2-rc.1 上该项显示为**会话时间线增强**：官方导航轨保留，插件只优化其行为（已加载轮次的平滑跳转），关掉即恢复官方原样。 |
 
 5. 点 **清除背景** 移除背景，恢复默认外观。
 
 ## 原理
 
-- **设置行**位于官方「通用」设置分区的 `settings.general.item` 槽中，紧挨「外观」行。控件样式全部使用 `--dsw-alias-*` 设计 token（按钮 / 胶囊 / 分段控件 / 滑块轨道与官方 chrome 一致），滑块为原生 `input[type=range]` 的 5% / 1–2px 步进 + 松手提交。
+- **设置行**位于官方「通用」设置分区的 `settings.general.item` 槽中，紧挨「外观」行。控件样式全部使用 `--dsw-alias-*` 设计 token（按钮 / 胶囊 / 分段控件 / 滑块轨道与官方 chrome 一致），滑块为原生 `input[type=range]` 的 5% / 1–2px 步进 + 松手提交。预览卡的尺寸按当前窗口视口比例计算（超过高度上限时整体等比缩小并在面板内居中），壁纸的取景位置以归一化 `0..1` 偏移存盘并映射到 `object-position`（percent 语义即"图片 p% 点对齐容器 p% 点"），因此换窗口尺寸或换图片都不需要重新换算。
 - **会话时间线**注册进 `conversation.input.dock` 槽位（绑定每会话生命周期）。判定是对槽位 props 的能力探测，而不是比较版本号： 官方导航轨正是由 `ui-chat` 以会话 hook 形式发布的同一份索引渲染的（`useChat(s => s.navigation.items())`，dsh ≥ 0.1.2）， 所以这个 hook 存在**就是**官方导航轨存在 —— 而且它能扛住预发布版、fork 以及挂载了其它会话目标的部署。 hook 存在时插件什么都不渲染，只在**捕获阶段**拦截官方导航轨**已加载刻度**的点击（React 18 在冒泡阶段由根容器派发 `onClick`， 所以导航轨上的捕获监听先执行，`stopImmediatePropagation()` 让官方处理器根本收不到事件）——点击索引按内核实际渲染的合并阶梯解析（`turnOutline` 大纲 + 已加载窗口，与 `ui-chat` 的 `mergeTurnRailItems` 同构），已加载窗口之外（无锚键）的刻度交给内核自己的穿越加载跳转——且当内核跳转仍在翻页（标记以 `aria-busy` 脉冲）时插件整体让位：内核的已加载分支落点前会先取消自己的在途跳转，拦截会绕过这一取消。 官方导航轨的悬浮预览在壁纸门控下加入毛玻璃配方（与输入卡片同一显式填充配方），刻度列带 DeepSeek 网页版式上下渐隐。 两代导航轨都按能力（而非版本号）识别：**框架式轨道**（dsh 0.1.2-rc.1 … 0.1.6）把内联度量发布在 `<nav>` 上，刻度按几何换算；**虚拟化轨道**（dsh 0.1.7+）不发布任何内联度量，且只挂载可见窗口的刻度，每个刻度自带阶梯下标。 支持基线为 dsh ≥ `0.1.2-rc.1`；更旧的 dsh（0.1.2-alpha.x 与 0.1.1-rc.2 及更早）请安装本插件旧版本（见「版本兼容」）。
 - 插件自有的 host 路由（`/api/bg-wallpaper/*`：`settings`、`upload`、`image/<id>`）负责读写设置与提供上传图片，带同源校验、大小上限、MIME/签名校验与路径穿越防护。使用自定义路由族，是因为 api-proxy 的 settings 白名单不向第三方命名空间开放 settings RPC。
 - 背景以 `body` 上一张固定的 `z-index:-2` 壁纸层 + `z-index:-1` 遮罩绘制，由 `data-dsh-bg` 属性开关；遮罩在注入样式表里按 `data-ds-dark-theme` 切换白/黑纱帘。毛玻璃为白名单制：仅对输入/气泡/代码/任务条等白名单表面覆盖 `--dsw-*` surface token，其余表面通过 `data-dsh-bg-glass` 门控的显式规则补齐整套配方（填充 + 高光 + 模糊滤镜链）：三个 chrome 按钮、「加载更早」历史按钮、composer 坞列家族——agent 任务条（TodoPanel / GoalBar / QueueDock）与接管面板（审批 / 提问 / 计划评审，token 变半透明后由这里补上模糊）、子代理列表弹出层、首页「预览版」徽标、侧栏构建徽章——全部官方 token 与阅读型界面（菜单/对话框/tooltip/toast）保持原样。

package/icon.svg

@@ -0,0 +1,8 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <!-- Fixed palette: the shell hands manifest icons to an <img>, so currentColor
+       cannot inherit the theme; #4D6BFE stays legible on both card materials. -->
+  <title>Custom Background</title>
+  <rect x="2.5" y="6.5" width="31" height="23" rx="5.5" stroke="#4D6BFE" stroke-width="1.5" />
+  <circle cx="25.5" cy="13.5" r="2.25" fill="#4D6BFE" />
+  <path d="M5 25.5L12.5 18.5L16.8 22.8L21.5 18L31 25.5" stroke="#4D6BFE" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" />
+</svg>