dsh-chat-background 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 本项目遵循 [SemVer](https://semver.org/lang/zh-CN/)；版本号与 `package.json`、`client.js` banner 保持一致。
 
+## [1.1.0] - 2026-11-04
+
+阅读体验版本：对话内容按轮次分区显示，设置页控件在不同屏幕/缩放下保持稳定。
+
+### 新增
+
+- **按轮次绘制的对话遮罩**：每一轮对话（用户消息 + 对应回复）单独一张遮罩卡，卡片宽度 = 阅读列宽 + 两侧各 24px 留白，随阅读列拖拽手柄自动变化；轮次之间露出壁纸，不再整列铺一层遮罩。
+- **舒适轮次间距**：把 DSH 的轮次布局间距从原生 12px 调到 28px（写回宿主的 `--dsh-chat-flow-gap`），配合卡片上边 6px 出血，卡片间保留约 14px 壁纸缝，用户消息气泡完整包在遮罩内。
+
+### 变更
+
+- **主窗口遮罩层**现在控制“每轮对话卡片”的透明度，而不是整块主窗口；0 为无遮罩，100 为不透明卡片。
+- **设置页控件模块化**：所有设置行改为两列 grid，右侧控件组保持自身宽度并右对齐；轮换设置使用固定的 caption/输入/数值槽位；下拉框、按钮、颜色块固定尺寸，不再随语言、字体缩放或 DPI 漂移。
+- **滑块**改用尺寸变量推导 thumb 偏移，替代手调像素值；窄屏（≤640px）控件堆叠到说明下方。
+
+### 修复
+
+- 切换窗口后主窗口/右侧栏偶发变白：通过稳定的槽位标记清除 app 画在布局 frame、主窗口列和右侧栏上的不透明底色，并在标题栏标记变化、窗口重新获得焦点或恢复可见时重新测量。
+- 设置页滑块圆点在部分缩放/DPI 下浮到轨道上方、控件互相挤压错位。
+- 对话遮罩层被宿主的 flow 间距下推 6px，导致用户消息气泡顶部露在遮罩外。
+- npm 安装说明与实际发布状态不一致。
+
+### 安装与兼容
+
+- DSH 桌面端 `>=0.2.1-rc.3`；Node `^22.19.0 || >=24.0.0`。
+- 支持从 GitHub、npm 或手动安装到 profile，详见 [README](README.md#安装)。
+
 ## [1.0.0] - 2026-11-02
 
 首个公开版本。

package/README.en.md

@@ -11,9 +11,10 @@
 
 ## What it does
 
-Pick a few pictures, put them in the background folder, and the chat window gets a wallpaper. Keep one image fixed
-or rotate through a group of favourites; tune the left sidebar, main window and right sidebar scrims separately so
-text stays readable. The plugin also adds a bar under the input, a task progress bar and a total token usage line.
+Pick a few pictures, put them in the background folder (default `~/.dsh/backgrounds/`, created automatically if
+missing), and the chat window gets a wallpaper. Keep one image fixed or rotate through a group of favourites; tune the
+left sidebar, main window and right sidebar scrims separately so text stays readable. The plugin also adds a bar under
+the input, a task progress bar and a total token usage line.
 
 ## Features
 
@@ -44,14 +45,14 @@ dsh plugin --profile desktop add github:LittleLemonJam/dsh-chat-background
 Fully quit and reopen DSH afterwards — the host half loads at boot; refreshing the page is not enough.
 Check **Plugins → Installed** to confirm `dsh-chat-background` is enabled.
 
-### From npm (once published)
-
-> The first release is distributed through GitHub; use the command below after the npm package is published.
+### From npm
 
 ```bash
 dsh plugin --profile desktop add dsh-chat-background
 ```
 
+The npm package tracks the GitHub release (currently `1.1.0`); either channel works.
+
 ### Manual install
 
 1. Copy `package.json`, `index.js`, `host/`, `client.js`, `cordis.patch.yml`, `locale/` and `icon.svg` into
@@ -68,10 +69,11 @@ dsh plugin --profile desktop add dsh-chat-background
 
 4. Restart DSH.
 
-### Add backgrounds
+### Where pictures go
 
-Put images in `~/.dsh/backgrounds/` (or point `DSH_BACKGROUNDS_DIR` elsewhere), then open
-**Settings → Page settings → Background** and press **Rescan**, or **Open folder**.
+Pictures live in `~/.dsh/backgrounds/` (`C:\Users\<you>\.dsh\backgrounds\` on Windows; set `DSH_BACKGROUNDS_DIR` to use
+another folder). **You do not need to create the folder first** — opening the settings page or pressing **Open folder**
+creates it automatically. Drop images in, then press **Rescan** under **Settings → Page settings → Background**.
 
 ## Usage
 

package/README.md

@@ -10,8 +10,8 @@
 
 ## 简介
 
-这是一个本地运行的 DSH 插件。选几张喜欢的图片放进背景文件夹，就能让聊天界面拥有自己的壁纸：
-可以固定一张，也可以按间隔自动轮换；左侧栏、主窗口、右侧栏的遮罩深浅可以分别调，界面文字仍然清楚可读。
+这是一个本地运行的 DSH 插件。选几张喜欢的图片放进背景文件夹（默认 `~/.dsh/backgrounds/`，不存在会自动创建），
+就能让聊天界面拥有自己的壁纸：可以固定一张，也可以按间隔自动轮换；左侧栏、主窗口、右侧栏的遮罩深浅可以分别调，界面文字仍然清楚可读。
 另外还附带输入栏背景条、任务进度条和全会话 Token 用量等小工具。
 
 ## 功能
@@ -43,14 +43,14 @@ dsh plugin --profile desktop add github:LittleLemonJam/dsh-chat-background
 安装后**完全退出并重新打开** DSH 桌面端（宿主半在启动时加载，只刷新页面不够）。
 可以在 **插件 → 已安装** 里确认 `dsh-chat-background` 处于启用状态。
 
-### 从 npm 安装（发布后可用）
-
-> 当前首发渠道是 GitHub；npm 包发布后可使用下面的命令。
+### 从 npm 安装
 
 ```bash
 dsh plugin --profile desktop add dsh-chat-background
 ```
 
+npm 包与 GitHub 发布同步（当前 `1.1.0`），两条安装方式任选其一即可。
+
 ### 手动安装
 
 1. 把仓库（或 `npm pack` 解压后）的 `package.json`、`index.js`、`host/`、`client.js`、`cordis.patch.yml`、
@@ -68,10 +68,11 @@ dsh plugin --profile desktop add dsh-chat-background
 
 4. 重启 DSH。
 
-### 准备背景图
+### 背景图放在哪里
 
-把图片放进 `~/.dsh/backgrounds/`（可用环境变量 `DSH_BACKGROUNDS_DIR` 指向其他目录），
-然后在 **设置 → 页面设置 → 背景** 点「重新扫描」，或点「打开文件夹」直接打开目录。
+图片固定放在 `~/.dsh/backgrounds/`（Windows 为 `C:\Users\<用户名>\.dsh\backgrounds\`；也可以用环境变量
+`DSH_BACKGROUNDS_DIR` 指向其他目录）。**目录不存在不用手动创建**：第一次打开设置页或点「打开文件夹」时插件会自动建好。
+把图片放进去后，在 **设置 → 页面设置 → 背景** 点「重新扫描」即可看到。
 
 ## 使用
 

package/client.js

@@ -1,5 +1,5 @@
 /**
- * dsh-chat-background v1.0.0
+ * dsh-chat-background v1.1.0
  * Chat background image, sidebar veil, composer strip, task progress bar and all-session token total for the DeepSeek Harness (DSH) Web GUI.
  * @author LittleLemonJam
  * @license MIT
@@ -40,6 +40,7 @@
   var RIGHT_COLUMN_ATTRIBUTE = "data-dsh-chat-background-right";
   var RIGHT_PANEL_ATTRIBUTE = "data-dsh-chat-background-right-panel";
   var RIGHT_PANEL_FULL_ATTRIBUTE = "data-dsh-chat-background-right-panel-full";
+  var READ_COLUMN_ATTRIBUTE = "data-dsh-chat-background-read-column";
   var LAYOUT_FRAME_ATTRIBUTE = "data-dsh-chat-background-frame";
   var FRAME_ANIMATING_ATTRIBUTE = "data-dsh-chat-background-frame-animating";
   var RIGHT_FULLSCREEN_ATTRIBUTE = "data-dsh-chat-background-right-fullscreen";
@@ -94,7 +95,7 @@
   }
   function diagnosticsSnapshot() {
     return {
-      version: true ? "1.0.0" : "unknown",
+      version: true ? "1.1.0" : "unknown",
       updatedAt: Date.now(),
       ...state
     };
@@ -762,24 +763,273 @@
     return element;
   }
 
+  // src/lib/turn-masks.js
+  function sidePadding(gap, padding, minGap) {
+    if (!Number.isFinite(gap)) return padding;
+    if (gap <= 0) return 0;
+    return Math.max(0, Math.min(padding, (gap - minGap) / 2));
+  }
+  function computeTurnCards(ranges, options = {}) {
+    const padding = options.padding ?? 10;
+    const minGap = options.minGap ?? 6;
+    return ranges.map((range, index) => {
+      const previous = ranges[index - 1];
+      const next = ranges[index + 1];
+      const gapAbove = previous === void 0 ? Infinity : range.top - previous.bottom;
+      const gapBelow = next === void 0 ? Infinity : next.top - range.bottom;
+      const padTop = sidePadding(gapAbove, padding, minGap);
+      const padBottom = sidePadding(gapBelow, padding, minGap);
+      return {
+        key: range.key,
+        top: range.top - padTop,
+        height: Math.max(0, range.bottom - range.top + padTop + padBottom)
+      };
+    });
+  }
+
+  // src/turn-masks.js
+  var FLOW_SELECTOR = '[data-slot="conversation.chat.flow"]';
+  var ITEM_SELECTOR = "[data-chat-turn]";
+  var LAYER_CLASS = "dshcb-turn-scrims";
+  var SCRIM_CLASS = "dshcb-turn-scrim";
+  var PADDING = 10;
+  var TOP_BLEED = 6;
+  var MIN_GAP = 20;
+  var SIDE_PADDING = 24;
+  var TURN_GAP = 28;
+  var GAP_PROPERTY = "--dsh-chat-flow-gap";
+  var column = null;
+  var layer = null;
+  var resizeObserver = null;
+  var frame = 0;
+  var scrims = /* @__PURE__ */ new Map();
+  var applied = /* @__PURE__ */ new Map();
+  var boundaries = /* @__PURE__ */ new Map();
+  var lastReport = "";
+  function findFlow() {
+    for (const flow of document.querySelectorAll(FLOW_SELECTOR)) {
+      const items = flow.querySelectorAll(ITEM_SELECTOR);
+      if (items.length === 0) continue;
+      if (flow.getClientRects().length === 0 && getComputedStyle(flow).display !== "contents") continue;
+      let visible = false;
+      for (const item of items) {
+        const rect = item.getBoundingClientRect();
+        if (rect.width > 0 && rect.height > 0) {
+          visible = true;
+          break;
+        }
+      }
+      if (!visible) continue;
+      return flow;
+    }
+    return null;
+  }
+  function findColumn(flow) {
+    let element = flow;
+    while (element !== null && element !== document.body) {
+      const style = getComputedStyle(element);
+      if (style.position === "fixed") return null;
+      if (style.display !== "contents" && element.clientWidth > 0 && element.clientHeight > 0) return element;
+      element = element.parentElement;
+    }
+    return null;
+  }
+  function disposeLayer() {
+    resizeObserver?.disconnect();
+    resizeObserver = null;
+    layer?.remove();
+    layer = null;
+    if (column !== null) column.removeAttribute(READ_COLUMN_ATTRIBUTE);
+    column = null;
+    for (const [element] of boundaries) element.style.removeProperty(GAP_PROPERTY);
+    boundaries.clear();
+    scrims.clear();
+    applied.clear();
+  }
+  function ensureLayer(nextColumn) {
+    if (column !== nextColumn) {
+      disposeLayer();
+      column = nextColumn;
+      column.setAttribute(READ_COLUMN_ATTRIBUTE, "");
+    }
+    if (layer === null || !layer.isConnected) {
+      layer = document.createElement("div");
+      layer.className = LAYER_CLASS;
+      layer.setAttribute("aria-hidden", "true");
+      column.appendChild(layer);
+    }
+    if (resizeObserver === null && typeof ResizeObserver !== "undefined" && column !== null) {
+      resizeObserver = new ResizeObserver(() => {
+        scheduleTurnMaskUpdate();
+      });
+      resizeObserver.observe(column);
+    }
+    if (layer.parentElement !== column) column.appendChild(layer);
+    return layer;
+  }
+  function measureTurns(flow, originTop) {
+    const turns = [];
+    const byKey = /* @__PURE__ */ new Map();
+    for (const item of flow.querySelectorAll(ITEM_SELECTOR)) {
+      if (item.closest("[hidden]") !== null) continue;
+      const itemRect = item.getBoundingClientRect();
+      if (itemRect.width <= 0 || itemRect.height <= 0) continue;
+      const turn = item.getAttribute("data-chat-turn") ?? "";
+      if (turn === "") continue;
+      const top = itemRect.top - originTop;
+      const bottom = itemRect.bottom - originTop;
+      const existing = byKey.get(turn);
+      if (existing === void 0) {
+        const group = { key: turn, top, bottom, first: item };
+        byKey.set(turn, group);
+        turns.push(group);
+      } else {
+        if (top < existing.top) existing.top = top;
+        if (bottom > existing.bottom) existing.bottom = bottom;
+      }
+    }
+    turns.sort((left, right) => left.top - right.top);
+    return turns;
+  }
+  function syncTurnGaps(turns) {
+    const desired = /* @__PURE__ */ new Map();
+    for (let index = 1; index < turns.length; index += 1) {
+      const first = turns[index].first;
+      if (first !== null) desired.set(first, TURN_GAP + "px");
+    }
+    let changed = false;
+    for (const [element] of boundaries) {
+      if (element.isConnected && desired.has(element)) continue;
+      element.style.removeProperty(GAP_PROPERTY);
+      boundaries.delete(element);
+      changed = true;
+    }
+    for (const [element, value] of desired) {
+      if (boundaries.get(element) === value) continue;
+      element.style.setProperty(GAP_PROPERTY, value);
+      boundaries.set(element, value);
+      changed = true;
+    }
+    return changed;
+  }
+  function refresh() {
+    frame = 0;
+    if (!document.documentElement.hasAttribute(ACTIVE_ATTRIBUTE)) {
+      disposeLayer();
+      recordTurnMaskDiagnostics({ active: false });
+      return;
+    }
+    const flow = findFlow();
+    const nextColumn = flow === null ? null : findColumn(flow);
+    if (nextColumn === null) {
+      disposeLayer();
+      recordTurnMaskDiagnostics({ active: true, column: false, turns: 0 });
+      return;
+    }
+    const cardLayer = ensureLayer(nextColumn);
+    const style = getComputedStyle(nextColumn);
+    const paddingLeft = Number.parseFloat(style.paddingLeft) || 0;
+    const paddingRight = Number.parseFloat(style.paddingRight) || 0;
+    const borderLeft = Number.parseFloat(style.borderLeftWidth) || 0;
+    const borderTop = Number.parseFloat(style.borderTopWidth) || 0;
+    const rect = nextColumn.getBoundingClientRect();
+    const scrollTop = nextColumn.scrollTop || 0;
+    const scrollLeft = nextColumn.scrollLeft || 0;
+    const originTop = rect.top + borderTop - scrollTop;
+    const originLeft = rect.left + borderLeft - scrollLeft;
+    const contentWidth = Math.max(0, nextColumn.clientWidth - paddingLeft - paddingRight);
+    let turns = measureTurns(flow, originTop);
+    if (syncTurnGaps(turns)) turns = measureTurns(flow, originTop);
+    const cards = computeTurnCards(turns, { padding: PADDING, minGap: MIN_GAP });
+    const cardLeft = paddingLeft - SIDE_PADDING;
+    const cardWidth = contentWidth + SIDE_PADDING * 2;
+    cardLayer.style.left = cardLeft + "px";
+    cardLayer.style.width = cardWidth + "px";
+    const live = /* @__PURE__ */ new Set();
+    for (const card of cards) {
+      const rawTop = Math.round(card.top) - TOP_BLEED;
+      const top = Math.max(0, rawTop);
+      const height = Math.max(0, Math.round(card.height) + TOP_BLEED - (top - rawTop));
+      const key = card.key;
+      live.add(key);
+      let element = scrims.get(key);
+      if (element === void 0) {
+        element = document.createElement("div");
+        element.className = SCRIM_CLASS;
+        element.setAttribute("data-turn", key);
+        cardLayer.appendChild(element);
+        scrims.set(key, element);
+        applied.delete(key);
+      }
+      const previous = applied.get(key);
+      if (previous === void 0 || previous.top !== top || previous.height !== height) {
+        element.style.top = top + "px";
+        element.style.height = height + "px";
+        applied.set(key, { top, height });
+      }
+    }
+    for (const [key, element] of scrims) {
+      if (live.has(key)) continue;
+      element.remove();
+      scrims.delete(key);
+      applied.delete(key);
+    }
+    recordTurnMaskDiagnostics({
+      active: true,
+      column: true,
+      turns: cards.length,
+      width: Math.round(cardWidth),
+      textWidth: Math.round(contentWidth)
+    });
+  }
+  function recordTurnMaskDiagnostics(value) {
+    const next = JSON.stringify(value);
+    if (next === lastReport) return;
+    lastReport = next;
+    recordDiagnostics({ turnMasks: value });
+  }
+  function scheduleTurnMaskUpdate() {
+    if (frame !== 0) return;
+    if (typeof window.requestAnimationFrame !== "function") {
+      refresh();
+      return;
+    }
+    frame = window.requestAnimationFrame(refresh);
+  }
+  function updateTurnMasks() {
+    if (frame !== 0) {
+      window.cancelAnimationFrame(frame);
+      frame = 0;
+    }
+    refresh();
+  }
+  function teardownTurnMasks() {
+    if (frame !== 0) {
+      window.cancelAnimationFrame(frame);
+      frame = 0;
+    }
+    disposeLayer();
+    recordTurnMaskDiagnostics({ active: false });
+  }
+
   // src/background.js
   function ensureBackgroundLayer(name) {
     if (document.body === null || name === null) return null;
-    let layer2 = document.querySelector("[" + BACKGROUND_LAYER_ATTRIBUTE + "]");
-    if (layer2 === null || layer2.tagName !== "IMG") {
-      layer2?.remove();
-      layer2 = document.createElement("img");
-      layer2.className = "dshcb-background-layer";
-      layer2.setAttribute(BACKGROUND_LAYER_ATTRIBUTE, "");
-      layer2.setAttribute("aria-hidden", "true");
-      layer2.setAttribute("alt", "");
-      layer2.setAttribute("decoding", "async");
-      layer2.setAttribute("draggable", "false");
-      document.body.appendChild(layer2);
+    let layer3 = document.querySelector("[" + BACKGROUND_LAYER_ATTRIBUTE + "]");
+    if (layer3 === null || layer3.tagName !== "IMG") {
+      layer3?.remove();
+      layer3 = document.createElement("img");
+      layer3.className = "dshcb-background-layer";
+      layer3.setAttribute(BACKGROUND_LAYER_ATTRIBUTE, "");
+      layer3.setAttribute("aria-hidden", "true");
+      layer3.setAttribute("alt", "");
+      layer3.setAttribute("decoding", "async");
+      layer3.setAttribute("draggable", "false");
+      document.body.appendChild(layer3);
     }
     const src = FILE_URL + encodeURIComponent(name);
-    if (layer2.getAttribute("src") !== src) layer2.setAttribute("src", src);
-    return layer2;
+    if (layer3.getAttribute("src") !== src) layer3.setAttribute("src", src);
+    return layer3;
   }
   function removeBackgroundLayer() {
     for (const element of document.querySelectorAll("[" + BACKGROUND_LAYER_ATTRIBUTE + "]")) element.remove();
@@ -815,7 +1065,7 @@
   function readRightScrim() {
     return readRegionScrim(SCRIM_RIGHT_KEY, VEIL_KEY, VEIL_DEFAULT);
   }
-  function layer(alpha) {
+  function layer2(alpha) {
     const rgb = isDark() ? "9,11,15" : "250,250,250";
     const value = (alpha / 100).toFixed(3);
     return `linear-gradient(rgba(${rgb},${value}), rgba(${rgb},${value}))`;
@@ -860,16 +1110,16 @@
   }
   function markColumn(attribute, slotName) {
     const outlet = document.querySelector(`[data-slot="${slotName}"]`);
-    const column = outlet === null ? null : outlet.parentElement;
-    if (column !== null && !column.hasAttribute(attribute)) column.setAttribute(attribute, "");
+    const column2 = outlet === null ? null : outlet.parentElement;
+    if (column2 !== null && !column2.hasAttribute(attribute)) column2.setAttribute(attribute, "");
   }
   function clearColumn(attribute) {
     for (const element of document.querySelectorAll(`[${attribute}]`)) element.removeAttribute(attribute);
   }
   function markSidebarColumn() {
     const outlet = document.querySelector('[data-slot="sidebar"]');
-    const column = outlet === null ? null : outlet.parentElement;
-    if (column !== null) column.setAttribute(SIDEBAR_COLUMN_ATTRIBUTE, "");
+    const column2 = outlet === null ? null : outlet.parentElement;
+    if (column2 !== null) column2.setAttribute(SIDEBAR_COLUMN_ATTRIBUTE, "");
   }
   function markMainColumn() {
     markColumn(MAIN_COLUMN_ATTRIBUTE, "main");
@@ -936,7 +1186,7 @@
       observedPanel = null;
     }
     const outlet = document.querySelector('[data-slot="rightbar"]');
-    const column = outlet === null ? null : outlet.parentElement;
+    const column2 = outlet === null ? null : outlet.parentElement;
     const panel = outlet === null ? null : outlet.querySelector('[class*="panel"]');
     const root = document.documentElement;
     const labelFull = hasExitFullscreenControl();
@@ -966,12 +1216,12 @@
         element.removeAttribute(RIGHT_PANEL_FULL_ATTRIBUTE);
     };
     setFull(panel);
-    if (column !== null) setFull(column);
+    if (column2 !== null) setFull(column2);
     if (full) {
       const leftOutlet = document.querySelector('[data-slot="sidebar"]');
       const leftColumn = leftOutlet === null ? null : leftOutlet.parentElement;
       const leftWidth = leftColumn === null ? 0 : leftColumn.getBoundingClientRect().width;
-      const columnLeft = column === null ? 0 : column.getBoundingClientRect().left;
+      const columnLeft = column2 === null ? 0 : column2.getBoundingClientRect().left;
       const offset = Math.round(leftWidth - columnLeft);
       const width = Math.round(window.innerWidth - leftWidth);
       root.style.setProperty("--dsh-chat-background-full-left", offset + "px");
@@ -984,15 +1234,15 @@
   }
   function animateLayoutFrame() {
     const outlet = document.querySelector('[data-slot="main"]');
-    const column = outlet === null ? null : outlet.parentElement;
-    const frame = column === null ? null : column.parentElement;
-    if (frame === null) return;
+    const column2 = outlet === null ? null : outlet.parentElement;
+    const frame2 = column2 === null ? null : column2.parentElement;
+    if (frame2 === null) return;
     const reduced = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true;
-    if (!reduced) frame.setAttribute(FRAME_ANIMATING_ATTRIBUTE, "");
+    if (!reduced) frame2.setAttribute(FRAME_ANIMATING_ATTRIBUTE, "");
     if (frameAnimTimer !== 0) window.clearTimeout(frameAnimTimer);
     frameAnimTimer = window.setTimeout(() => {
       frameAnimTimer = 0;
-      frame.removeAttribute(FRAME_ANIMATING_ATTRIBUTE);
+      frame2.removeAttribute(FRAME_ANIMATING_ATTRIBUTE);
     }, 340);
   }
   function installRightbarGestures() {
@@ -1052,9 +1302,9 @@
   }
   function markLayoutFrame() {
     const outlet = document.querySelector('[data-slot="main"]');
-    const column = outlet === null ? null : outlet.parentElement;
-    const frame = column === null ? null : column.parentElement;
-    if (frame !== null && !frame.hasAttribute(LAYOUT_FRAME_ATTRIBUTE)) frame.setAttribute(LAYOUT_FRAME_ATTRIBUTE, "");
+    const column2 = outlet === null ? null : outlet.parentElement;
+    const frame2 = column2 === null ? null : column2.parentElement;
+    if (frame2 !== null && !frame2.hasAttribute(LAYOUT_FRAME_ATTRIBUTE)) frame2.setAttribute(LAYOUT_FRAME_ATTRIBUTE, "");
   }
   function markRegionColumns() {
     markSidebarColumn();
@@ -1112,7 +1362,7 @@
     if (candidates.length > 0) syncDynamicRules([candidates[0]]);
     return candidates;
   }
-  var applied = { selection: void 0, dark: null, scrimLeft: null, scrimMain: null, scrimRight: null };
+  var applied2 = { selection: void 0, dark: null, scrimLeft: null, scrimMain: null, scrimRight: null };
   var markSignature = -1;
   var markContainer = null;
   var flushHandle = 0;
@@ -1128,7 +1378,7 @@
     const container = conversationContainer();
     const painters = markedPainters();
     const needsPaint = signature !== markSignature || container !== markContainer || painters.length === 0;
-    const sameVars = applied.selection === next && applied.dark === dark && applied.scrimLeft === scrimLeft && applied.scrimMain === scrimMain && applied.scrimRight === scrimRight;
+    const sameVars = applied2.selection === next && applied2.dark === dark && applied2.scrimLeft === scrimLeft && applied2.scrimMain === scrimMain && applied2.scrimRight === scrimRight;
     if (next === null) {
       if (sameVars && !root.hasAttribute(ACTIVE_ATTRIBUTE)) return;
       for (const property of INLINE_PROPERTIES) root.style.removeProperty(property);
@@ -1140,8 +1390,9 @@
       clearPainters();
       clearRegionColumns();
       syncDynamicRules([]);
+      teardownTurnMasks();
       nudgeNativeTitlebar(false);
-      applied = { selection: null, dark, scrimLeft, scrimMain, scrimRight };
+      applied2 = { selection: null, dark, scrimLeft, scrimMain, scrimRight };
       markSignature = -1;
       markContainer = null;
       recordDiagnostics({ background: { active: false } });
@@ -1171,13 +1422,14 @@
     });
     if (!sameVars) {
       root.style.setProperty("--dsh-chat-background-image", 'url("' + FILE_URL + encodeURIComponent(next) + '")');
-      root.style.setProperty("--dsh-chat-background-scrim-left", layer(scrimLeft));
-      root.style.setProperty("--dsh-chat-background-scrim-main", layer(scrimMain));
-      root.style.setProperty("--dsh-chat-background-scrim-right", layer(scrimRight));
+      root.style.setProperty("--dsh-chat-background-scrim-left", layer2(scrimLeft));
+      root.style.setProperty("--dsh-chat-background-scrim-main", layer2(scrimMain));
+      root.style.setProperty("--dsh-chat-background-scrim-right", layer2(scrimRight));
       root.setAttribute(ACTIVE_ATTRIBUTE, next);
-      applied = { selection: next, dark, scrimLeft, scrimMain, scrimRight };
+      applied2 = { selection: next, dark, scrimLeft, scrimMain, scrimRight };
       nudgeNativeTitlebar(true);
     }
+    updateTurnMasks();
   }
   function flushBackground() {
     if (flushHandle !== 0) return;
@@ -1186,6 +1438,7 @@
       applyBackground(readSelection());
       renderComposerStrip();
       renderTokenTotal();
+      updateTurnMasks();
     };
     if (typeof window.requestAnimationFrame === "function") {
       flushIsTimeout = false;
@@ -1195,6 +1448,11 @@
       flushHandle = window.setTimeout(run, 16);
     }
   }
+  function invalidatePainters() {
+    markSignature = -1;
+    markContainer = null;
+    flushBackground();
+  }
   function teardownVisuals() {
     if (flushHandle !== 0) {
       if (flushIsTimeout) window.clearTimeout(flushHandle);
@@ -1224,6 +1482,7 @@
     clearPainters();
     clearRegionColumns();
     syncDynamicRules([]);
+    teardownTurnMasks();
     document.querySelector(`style[data-plugin-css=${cssString(DYNAMIC_TAG_ID)}]`)?.remove();
     document.querySelector(`[${STRIP_ATTRIBUTE}]`)?.remove();
     document.querySelector(`[${TOKEN_NODE_ATTRIBUTE}]`)?.remove();
@@ -1231,7 +1490,7 @@
     cachedContainer = null;
     markSignature = -1;
     markContainer = null;
-    applied = { selection: void 0, dark: null, scrimLeft: null, scrimMain: null, scrimRight: null };
+    applied2 = { selection: void 0, dark: null, scrimLeft: null, scrimMain: null, scrimRight: null };
   }
 
   // src/lib/zoom.js
@@ -1463,7 +1722,7 @@
   }
 
   // src/rotation.js
-  var LAYER_CLASS = "dshcb-rotate-layer";
+  var LAYER_CLASS2 = "dshcb-rotate-layer";
   var timer = 0;
   var layerTimers = [];
   var request = null;
@@ -1522,45 +1781,45 @@
     return document.body?.hasAttribute("data-ds-dark-theme") === true ? "rgb(9, 11, 15)" : "rgb(250, 250, 250)";
   }
   function createImageLayer(name) {
-    const layer2 = document.createElement("img");
-    layer2.className = LAYER_CLASS;
-    layer2.setAttribute(ROTATION_LAYER_ATTRIBUTE, "");
-    layer2.setAttribute("aria-hidden", "true");
-    layer2.setAttribute("alt", "");
-    layer2.setAttribute("draggable", "false");
-    layer2.src = FILE_URL + encodeURIComponent(name);
-    document.body.appendChild(layer2);
-    return layer2;
+    const layer3 = document.createElement("img");
+    layer3.className = LAYER_CLASS2;
+    layer3.setAttribute(ROTATION_LAYER_ATTRIBUTE, "");
+    layer3.setAttribute("aria-hidden", "true");
+    layer3.setAttribute("alt", "");
+    layer3.setAttribute("draggable", "false");
+    layer3.src = FILE_URL + encodeURIComponent(name);
+    document.body.appendChild(layer3);
+    return layer3;
   }
   function createColorLayer(color) {
-    const layer2 = document.createElement("div");
-    layer2.className = LAYER_CLASS;
-    layer2.setAttribute(ROTATION_LAYER_ATTRIBUTE, "");
-    layer2.setAttribute("aria-hidden", "true");
-    layer2.style.background = color;
-    document.body.appendChild(layer2);
-    return layer2;
+    const layer3 = document.createElement("div");
+    layer3.className = LAYER_CLASS2;
+    layer3.setAttribute(ROTATION_LAYER_ATTRIBUTE, "");
+    layer3.setAttribute("aria-hidden", "true");
+    layer3.style.background = color;
+    document.body.appendChild(layer3);
+    return layer3;
   }
   function fadeTransition(previous, next, duration) {
-    const layer2 = createImageLayer(previous);
-    layer2.style.opacity = "1";
+    const layer3 = createImageLayer(previous);
+    layer3.style.opacity = "1";
     commit(next);
-    void layer2.offsetWidth;
-    layer2.style.transition = `opacity ${String(duration)}s ease`;
-    layer2.style.opacity = "0";
+    void layer3.offsetWidth;
+    layer3.style.transition = `opacity ${String(duration)}s ease`;
+    layer3.style.opacity = "0";
     scheduleLayer(removeLayer, duration * 1e3 + 80);
   }
   function fadeThroughTransition(previous, next, duration) {
     const half = Math.max(40, duration * 1e3 / 2);
-    const layer2 = createColorLayer(themeBaseColour());
-    layer2.style.opacity = "0";
-    void layer2.offsetWidth;
-    layer2.style.transition = `opacity ${String(half / 1e3)}s ease`;
-    layer2.style.opacity = "1";
+    const layer3 = createColorLayer(themeBaseColour());
+    layer3.style.opacity = "0";
+    void layer3.offsetWidth;
+    layer3.style.transition = `opacity ${String(half / 1e3)}s ease`;
+    layer3.style.opacity = "1";
     scheduleLayer(() => {
       commit(next);
-      layer2.style.transition = `opacity ${String(half / 1e3)}s ease`;
-      layer2.style.opacity = "0";
+      layer3.style.transition = `opacity ${String(half / 1e3)}s ease`;
+      layer3.style.opacity = "0";
       scheduleLayer(removeLayer, half + 80);
     }, half);
     void previous;
@@ -1814,24 +2073,15 @@
       Row,
       { title: copy.modeTitle },
       h(
-        "div",
-        { className: "dshcb-rotation-controls" },
-        h(
-          "label",
-          { className: "dshcb-control-field" },
-          h("span", { className: "dshcb-control-caption" }, copy.modeTitle),
-          h(
-            "select",
-            {
-              className: "dshcb-select",
-              value: mode,
-              "aria-label": copy.modeTitle,
-              onChange: (event) => change(event.target.value)
-            },
-            h("option", { value: "fixed" }, copy.modeFixed),
-            h("option", { value: "rotation" }, copy.modeRotation)
-          )
-        )
+        "select",
+        {
+          className: "dshcb-select",
+          value: mode,
+          "aria-label": copy.modeTitle,
+          onChange: (event) => change(event.target.value)
+        },
+        h("option", { value: "fixed" }, copy.modeFixed),
+        h("option", { value: "rotation" }, copy.modeRotation)
       )
     );
   }
@@ -2359,36 +2609,42 @@ ${active} {
   object-position: center center;
 }
 
-/* Rotation settings block. The mode/effect/group controls stack inside
- * the normal row control column so they line up with every other row. */
+/* Rotation settings block. Each field is its own two-column module so the
+ * captions, inputs and value slots keep the same width on every display,
+ * font scale and window size; the block only decides the module width. */
 .dshcb-rotation-controls {
-  display: flex;
-  flex-direction: column;
+  display: grid;
   gap: 8px;
-  min-width: 260px;
-  max-width: 340px;
+  width: min(340px, 100%);
+  min-width: 0;
 }
 .dshcb-control-field {
-  display: flex;
+  display: grid;
+  grid-template-columns: 84px minmax(0, 1fr) auto;
   align-items: center;
-  gap: 8px;
+  column-gap: 8px;
+  min-width: 0;
   font-size: 12px;
 }
 .dshcb-control-field > .dshcb-control-caption {
-  flex: 0 0 auto;
+  min-width: 0;
   color: var(--dsw-alias-label-secondary);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 .dshcb-control-field > .dshcb-select {
-  flex: 1 1 auto;
+  width: 100%;
+  max-width: none;
   min-width: 0;
 }
 .dshcb-control-field > .dshcb-range {
-  flex: 1 1 auto;
-  min-width: 80px;
+  width: 100%;
+  min-width: 0;
 }
 .dshcb-control-field > .dshcb-value {
-  flex: 0 0 auto;
-  min-width: 42px;
+  min-width: 40px;
+  justify-self: end;
   text-align: end;
 }
 .dshcb-group-list {
@@ -2481,6 +2737,21 @@ ${active} [class*="sidebarCol"] {
   isolation: isolate !important;
 }
 
+/* The app paints the base surface on the frame and on the center/right
+ * columns: the Windows titlebar frame gives the center column an opaque fill
+ * plus a rounded corner, and macOS fills the right column. The measured
+ * painter marks only describe the DOM that was measured, so a rebuilt or
+ * restyled column can come back white while the slots stay the same (the
+ * marker is refreshed on every apply, the measured mark is not). Clearing
+ * through the stable slot-derived markers keeps the image visible across
+ * rebuilds, window restores and titlebar re-themes. */
+${active} [${MAIN_COLUMN_ATTRIBUTE}],
+${active} [${RIGHT_COLUMN_ATTRIBUTE}],
+${active} [${LAYOUT_FRAME_ATTRIBUTE}] {
+  background-color: transparent !important;
+  background-image: none !important;
+}
+
 /* Left sidebar scrim. */
 ${active} [${SIDEBAR_COLUMN_ATTRIBUTE}]::before,
 ${active} [class*="sidebarCol"]::before {
@@ -2492,13 +2763,33 @@ ${active} [class*="sidebarCol"]::before {
   background: var(--dsh-chat-background-scrim-left);
 }
 
-/* Main conversation column scrim. */
-${active} [${MAIN_COLUMN_ATTRIBUTE}]::after {
-  content: "";
+/* The reading-area veil is painted per conversation turn by the turn-mask
+ * layer (src/turn-masks.js), not as one rectangle over the whole centre
+ * column: the wallpaper stays visible between two turns while every turn —
+ * prompt and reply — still reads as one card. The layer lives inside the
+ * reading column so its width follows that column's drag handle. */
+${active} [${READ_COLUMN_ATTRIBUTE}] {
+  position: relative !important;
+  isolation: isolate !important;
+}
+.dshcb-turn-scrims {
   position: absolute;
-  inset: 0;
-  z-index: -1;
+  top: 0;
+  height: 0;
+  overflow: visible;
   pointer-events: none;
+  z-index: -1;
+  /* The host's flow-gap rule targets every direct child of the flow, including
+   * this layer; without the reset the whole layer (and every card in it) sits
+   * one flow gap below the reading column top, leaving prompt bubbles outside
+   * the veil. */
+  margin: 0 !important;
+}
+.dshcb-turn-scrim {
+  position: absolute;
+  left: 0;
+  width: 100%;
+  border-radius: var(--dsw-radius-lg, 12px);
   background: var(--dsh-chat-background-scrim-main);
 }
 
@@ -2594,8 +2885,8 @@ ${active} body > span[style*="dsw-specific-sidebar-fill"] {
     background-image: none !important;
   }
   ${active} [${SIDEBAR_COLUMN_ATTRIBUTE}]::before,
-  ${active} [${MAIN_COLUMN_ATTRIBUTE}]::after,
-  ${active} [${RIGHT_COLUMN_ATTRIBUTE}]::after {
+  ${active} [${RIGHT_COLUMN_ATTRIBUTE}]::after,
+  ${active} .dshcb-turn-scrims {
     display: none;
   }
 }
@@ -2609,8 +2900,8 @@ ${active} body > span[style*="dsw-specific-sidebar-fill"] {
     background-image: none !important;
   }
   ${active} [${SIDEBAR_COLUMN_ATTRIBUTE}]::before,
-  ${active} [${MAIN_COLUMN_ATTRIBUTE}]::after,
-  ${active} [${RIGHT_COLUMN_ATTRIBUTE}]::after {
+  ${active} [${RIGHT_COLUMN_ATTRIBUTE}]::after,
+  ${active} .dshcb-turn-scrims {
     display: none;
   }
 }
@@ -2766,31 +3057,41 @@ ${active} :is([data-slot="settings.section"], [data-slot="settings.header"], [da
 }
 .dshcb-bg-file {
   display: flex;
+  flex-wrap: wrap;
   align-items: center;
   gap: 8px;
 }
 .dshcb-bg-select {
-  flex: 1;
+  flex: 1 1 200px;
   max-width: none;
   min-width: 0;
 }
 .dshcb-bg-file .dshcb-select {
-  flex: 1;
+  flex: 1 1 200px;
   max-width: none;
+  min-width: 0;
+}
+.dshcb-bg-file .dshcb-button {
+  flex: none;
 }
 
+/* Every setting row is a two-column module: the copy takes the free space,
+ * the control block keeps its own intrinsic width and is pinned to the right.
+ * Grid (not flex + space-between) is what stops a wide control from squeezing
+ * the label or shifting it between window sizes, zoom levels and displays. */
 .dshcb-row {
-  display: flex;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
   align-items: center;
-  justify-content: space-between;
-  gap: 24px;
+  column-gap: 24px;
+  row-gap: 8px;
   padding: 16px 0;
   border-bottom: 0.5px solid var(--dsw-alias-border-l2);
 }
 .dshcb-text {
   display: flex;
   flex-direction: column;
-  flex: 1;
+  align-items: stretch;
   gap: 4px;
   min-width: 0;
 }
@@ -2816,14 +3117,20 @@ ${active} :is([data-slot="settings.section"], [data-slot="settings.header"], [da
   font-size: 12px;
   line-height: 18px;
 }
+/* One self-contained module per control group: it keeps its size and stays
+ * right-aligned whatever the label wraps to. */
 .dshcb-control {
-  display: inline-flex;
+  display: flex;
+  flex: none;
   align-items: center;
+  justify-content: flex-end;
   gap: 8px;
+  min-width: 0;
 }
 /* ---- controls ------------------------------------------------------------ */
 
 .dshcb-button {
+  flex: none;
   height: 32px;
   padding: 0 12px;
   border: 0.5px solid var(--dsw-alias-border-l1);
@@ -2833,6 +3140,7 @@ ${active} :is([data-slot="settings.section"], [data-slot="settings.header"], [da
   font: inherit;
   font-size: 13px;
   line-height: 20px;
+  white-space: nowrap;
   cursor: pointer;
 }
 .dshcb-button:hover:not(:disabled) {
@@ -2843,8 +3151,10 @@ ${active} :is([data-slot="settings.section"], [data-slot="settings.header"], [da
   cursor: default;
 }
 .dshcb-select {
-  height: 32px;
+  flex: none;
+  width: 180px;
   max-width: 180px;
+  height: 32px;
   padding: 0 6px;
   border: 0.5px solid var(--dsw-alias-border-l1);
   border-radius: var(--dsw-radius-sm);
@@ -2921,8 +3231,13 @@ ${active} :is([data-slot="settings.section"], [data-slot="settings.header"], [da
   outline-offset: 2px;
 }
 
-/* Range slider. */
+/* Range slider. The track and thumb sizes are variables and the thumb offset
+ * is derived from them; a hand-tuned pixel offset drifts once the app's font
+ * metrics, page zoom or device pixel ratio change (the track's vertical
+ * position depends on the native control's line box, not on this stylesheet). */
 .dshcb-range {
+  --dshcb-range-track-height: 4px;
+  --dshcb-range-thumb-size: 14px;
   appearance: none;
   -webkit-appearance: none;
   flex: none;
@@ -2931,12 +3246,16 @@ ${active} :is([data-slot="settings.section"], [data-slot="settings.header"], [da
   margin: 0;
   background: transparent;
   cursor: pointer;
+  /* Collapse the native line box so the track cannot be pushed off-centre by
+   * the inherited font size. */
+  line-height: 0;
 }
 .dshcb-range:disabled {
   cursor: default;
 }
 .dshcb-range::-webkit-slider-runnable-track {
-  height: 4px;
+  box-sizing: border-box;
+  height: var(--dshcb-range-track-height);
   border: 0.5px solid var(--dsw-alias-border-l1);
   border-radius: 999px;
   background: var(--dsw-alias-bg-module-platform);
@@ -2944,9 +3263,9 @@ ${active} :is([data-slot="settings.section"], [data-slot="settings.header"], [da
 .dshcb-range::-webkit-slider-thumb {
   appearance: none;
   -webkit-appearance: none;
-  width: 14px;
-  height: 14px;
-  margin-top: -50.5px;
+  width: var(--dshcb-range-thumb-size);
+  height: var(--dshcb-range-thumb-size);
+  margin-top: calc((var(--dshcb-range-track-height) - var(--dshcb-range-thumb-size)) / 2);
   border: 0;
   border-radius: 50%;
   background: var(--dsw-alias-brand-primary);
@@ -2955,14 +3274,15 @@ ${active} :is([data-slot="settings.section"], [data-slot="settings.header"], [da
   background: var(--dsw-alias-state-idle-primary, #a2a4a6);
 }
 .dshcb-range::-moz-range-track {
-  height: 4px;
+  box-sizing: border-box;
+  height: var(--dshcb-range-track-height);
   border: 0.5px solid var(--dsw-alias-border-l1);
   border-radius: 999px;
   background: var(--dsw-alias-bg-module-platform);
 }
 .dshcb-range::-moz-range-thumb {
-  width: 14px;
-  height: 14px;
+  width: var(--dshcb-range-thumb-size);
+  height: var(--dshcb-range-thumb-size);
   border: 0;
   border-radius: 50%;
   background: var(--dsw-alias-brand-primary);
@@ -2975,6 +3295,21 @@ ${active} :is([data-slot="settings.section"], [data-slot="settings.header"], [da
   text-align: right;
 }
 
+/* Narrow settings panels: stack the control module under the copy instead of
+ * letting the two columns fight for room. The module keeps its own layout, so
+ * nothing moves between devices — only its position changes. */
+@media (max-width: 640px) {
+  .dshcb-row {
+    grid-template-columns: minmax(0, 1fr);
+  }
+  .dshcb-control {
+    justify-content: flex-start;
+  }
+  .dshcb-rotation-controls {
+    width: 100%;
+  }
+}
+
 /* ---- task progress bar --------------------------------------------------- */
 
 /* Mounted into the composer's input dock (a full-width entry above the composer
@@ -3170,8 +3505,26 @@ ${active} :is([data-slot="settings.section"], [data-slot="settings.header"], [da
           };
           if (document.body === null) document.addEventListener("DOMContentLoaded", observe, { once: true });
           else observe();
+          const rootObserver = new MutationObserver(() => {
+            invalidatePainters();
+          });
+          rootObserver.observe(document.documentElement, {
+            attributes: true,
+            attributeFilter: ["data-windows-titlebar", "data-platform"]
+          });
+          const onFocus = () => {
+            invalidatePainters();
+          };
+          const onVisibility = () => {
+            if (!document.hidden) invalidatePainters();
+          };
+          window.addEventListener("focus", onFocus);
+          document.addEventListener("visibilitychange", onVisibility);
           return () => {
             observer.disconnect();
+            rootObserver.disconnect();
+            window.removeEventListener("focus", onFocus);
+            document.removeEventListener("visibilitychange", onVisibility);
           };
         }, "chat-background: DOM, scheme and switch follow-up");
         ctx.effect(() => ctx.locale.register(LOCALE_NS, { zh, en }), "chat-background: settings dictionaries");

package/docs/ARCHITECTURE.md

@@ -117,14 +117,22 @@ composer 包装层 ResizeObserver（纯样式尺寸） ──┘        ├─ a
 ### 5.0 背景区块、三区遮罩与原生标题栏
 
 - 设置页内部有「背景 / UI」两个 pill 标签页；切换是组件内 `useState`，不产生额外路由。
+- 所有设置行都经 `Row` 组件渲染：两列 grid（说明 / 控件模块）。控件组保持自身宽度并右对齐，所以语言切换、字体缩放、不同 DPI 或窗口变窄时只有位置变化，不会互相挤压或错位；滑块尺寸由变量推导，不写死像素偏移。
 - **背景**标签：大图预览、当前文件名下拉框 + 「打开文件夹」「重新扫描」按钮，下方三个遮罩层滑杆；区块与行之间用默认分隔线。
 - **UI**标签：背景条、进度条、Token 三组设置各用一张 `1px` 细边框 + 大圆角卡片包住，组内两行之间用默认分隔线。
 - 右栏 panel 通过 `markRightPanel()` 打标：普通状态由右栏列的 `::after` 画遮罩（随列宽收缩）；全屏时**左侧栏保持可见**，只隐藏主窗口列，panel 用 offset/width 变量从左侧栏右缘开始覆盖「主窗口 + 原右栏」并绘制统一遮罩；布局 frame 通过 `markLayoutFrame()` 打标，仅在展开/收起点击的 340ms 窗口内启用 300ms `grid-template-columns` 过渡（与 app 内容动画同步），拖动宽度时不启用过渡。
 - 三个遮罩层没有开关，只有 0–100 的不透明度：0 全透明、100 完全不透明；侧栏/右栏的表面始终让位于图片，由遮罩决定遮挡程度。
+- **主窗口遮罩按对话轮次绘制**：不再给整个主窗口列铺一层，而是由 `src/turn-masks.js` 读取 `[data-chat-turn]`，把同一轮的用户消息与回复合成一张绝对定位的卡片，
+  宽度 = 阅读列宽 + 两侧各 24px 留白（正好到阅读列宽度手柄的净空，跟随手柄自动变化），轮次之间保留约 20px 壁纸缝；同时把每轮第一个条目的宿主变量 `--dsh-chat-flow-gap` 写成 28px（原生 12px），把轮次之间的**真实布局间距**调成舒适档，关闭背景图或卸载时还原。卡片本身只写 `top/height`，不影响会话布局；卡片层会把宿主的 flow-gap margin 清零，否则整个层会随 flow 间距下移、用户气泡顶边露在遮罩外。几何计算在
+  `src/lib/turn-masks.js`，有单元测试覆盖；DOM 线程只在布局变化时重算。
 
 - 左侧栏/主窗口/右侧栏由稳定槽位（`[data-slot="sidebar"]`、`[data-slot="main"]`、`[data-slot="rightbar"]`）的父节点打标，
   各自建立 `position: relative` + `isolation: isolate` 的层叠上下文，再用 `::before`/`::after` 在 `z-index: -1` 画独立遮罩；
   因此调暗侧栏不会影响正文，反之亦然。
+- app 会把 base surface 画在布局 frame、主窗口列和右侧栏上：Windows 标题栏模式还会给主窗口列铺不透明底色和 16px 圆角。
+  这些表面通过**槽位标记**（`data-dsh-chat-background-main/right/frame`）清成透明，而不是只依赖一次性测量出的 `lift` 标记，
+  所以列被重建、标题栏重新主题化或窗口从遮挡恢复后都不会重新变白。测量标记丢失、`data-windows-titlebar`/`data-platform`
+  变化、窗口 `focus` 或 `visibilitychange` 变可见时会主动重新测量，见 `src/background.js` 的 `invalidatePainters()`。
 - 窗口控制条：桌面预加载用隐藏 probe 的 `background-color: var(--dsw-specific-sidebar-fill)` 采样原生 titleBarOverlay 颜色；
   插件只在该 probe 上覆盖为透明（不改 token），并通过改写 body 自定义属性触发预加载的 observer 重新发送，见 `src/background.js`。
 

package/docs/CONVENTIONS.md

@@ -109,6 +109,8 @@ export function createSwitch({ key, onChange }) { ... }
 - 选择器按「背景 → 侧栏 → composer → 设置 → 控件 → 进度条 → token 行」分组，组间用 `/* ---- 组名 ---- */` 分隔。
 - 不给宿主元素打标时优先用稳定的 `data-slot` / `data-*` 钩子；确实没有稳定钩子时，才允许用 CSS 模块名后缀选择器（如 `[class*="sidebarCol"]`），并在注释里写明这是升级敏感点。
 - 规则若依赖某个层叠/包含块不变量，必须写注释解释原因。
+- 设置行统一是两列 grid 模块：左侧说明、右侧控件整体成块（`flex: none`、固定槽位、右对齐），控件尺寸不随语言、字体缩放、DPI 或窗口宽度漂移；只有窄屏（≤640px）才把控件堆到说明下方。
+- 原生控件的尺寸不要用手调像素偏移去对齐（如滑块的 `margin-top: -50.5px`），用尺寸变量推导（`calc((track - thumb) / 2)`），否则在别的缩放/DPI 下会漂移。
 
 ## 5. JSON / YAML
 

package/docs/PUBLISHING.md

@@ -6,7 +6,7 @@
 
 ```bash
 npm run verify        # 格式 + 构建一致性 + 静态检查 + 单元测试
-npm run test:e2e      # 9 个端到端套件（需要本机 DSH）
+npm run test:e2e      # 11 个端到端套件（需要本机 DSH）
 npm pack --dry-run    # 确认 tarball 内容
 ```
 
@@ -25,12 +25,12 @@ npm pack --dry-run    # 确认 tarball 内容
 - 删除旧 tag（如 `git tag -d v1.2.0`），只保留要发布的版本；
 - 复查 `git log --oneline` 与 `git ls-files`，确认没有个人文件后再推送。
 
-当前仓库已按此方式重建为单提交的 1.0.0。
+当前仓库已按此方式重建为单提交的 1.0.0 起点，当前发布版本 1.1.0。
 
 ### 2.2 首次创建仓库
 
 1. 在 GitHub 新建公开仓库 `dsh-chat-background`（默认分支 `main`）；
-2. 推送代码与 `v1.0.0` 标签；
+2. 推送代码与 `v1.1.0` 标签；
 3. 仓库 **About** 填写简介：
    - 描述：`给 DeepSeek Harness 桌面端换背景：背景图/轮换分组/三栏遮罩/输入栏背景条/任务进度条/Token 用量`；
    - 网站：留空或填仓库地址；
@@ -49,26 +49,30 @@ npm pack --dry-run    # 确认 tarball 内容
 生成 npm tarball 并创建 GitHub Release。发布后在 Release 中附上主要更新内容即可。
 
 ```bash
-git tag v1.0.0
+git tag v1.1.0
 git push origin main --tags
 ```
 
-## 3. npm 发布（可选）
+## 3. npm 发布
 
-插件可以只通过 GitHub 安装。若希望 `dsh plugin add dsh-chat-background` 直接可用，再发布 npm：
+`1.1.0` 已发布到 npm，`dsh plugin --profile desktop add dsh-chat-background` 可直接安装。
+发新版本时：
 
 ```bash
-npm login
-npm publish --access public
+npm whoami                      # 确认是维护者账号 lemonjam
+npm publish --access public     # 需要带 bypass 2FA 的 granular token
 ```
 
 验证：
 
 ```bash
-npm view dsh-chat-background version
-dsh plugin --profile desktop add dsh-chat-background@1.0.0
+npm view dsh-chat-background version   # 应等于当前版本号
+dsh plugin --profile desktop add dsh-chat-background@1.1.0
 ```
 
+> npm 页面上的 README 是发布时 tarball 的快照，发布后再改 README 不会回写 npm 页面，
+> 下次发版时才会同步；以 GitHub 仓库的 README 为准。
+
 ## 4. 提交 DSH 插件市场
 
 DSH 0.2.x 的插件市场会扫描 GitHub 上的公开 DSH 插件；收录要求：

package/docs/TESTING.md

@@ -59,17 +59,19 @@ npm run test:e2e -- --keep           # 保留临时 DSH_HOME 与产物，便于
 
 ### 2.4 套件一览
 
-| 套件                      | 覆盖                                                                                                                                                                           |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `01-smoke`                | 背景应用、样式表/测量规则安装、背景条覆盖用量行且与输入卡片等宽、进度条空闲隐藏、Token 行位置、设置页标签页、背景区块、UI 分组卡片与控件类型、行 `aria-labelledby/describedby` |
-| `02-controls`             | 3 个开关、3 个滑杆、2 个调色盘、深色主题默认色、语言切换（经设置页语言控件）                                                                                                   |
-| `03-robustness`           | 稳定钩子优先（英文 pill + `display: contents` 包装层）、零布局影响与 fixed 探针、纯样式尺寸变化跟随、移除/重建用量行、连续开关不重复、窗口 resize                              |
-| `04-host-routes`          | `/list`、图片 200/ETag/304、路径穿越 404、`/folder` 的 405/403、token 汇总自洽                                                                                                 |
-| `05-rightbar`             | 右栏收起/展开的临时网格过渡（中间帧宽度）、拖动宽度无过渡、全屏 panel 覆盖窗口/统一遮罩/主窗口隐藏、退出全屏恢复                                                               |
-| `08-security`             | `/health`、目录脱敏、响应头、SVG CSP、真实导航到 SVG 后脚本不执行                                                                                                              |
-| `06-image-zoom`           | 固定层图片滚轮缩放/双击还原；设置弹窗内图片不缩放；右栏图片预览的普通滚轮转换为 Ctrl+滚轮                                                                                      |
-| `07-rotation`             | 轮换分组内切换、过渡层出现、三行设置顺序/控件值/无小字、分组 5 行滚动、仅勾选框选择、缩略图、选择不重排、拖动排序动画、切换固定后停止轮换                                      |
-| `07b-animated-background` | 动图文件被列为背景并由已加载的固定 IMG 层绘制，根元素不再绘制背景图                                                                                                            |
+| 套件                      | 覆盖                                                                                                                                                                                                                                                                                                    |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `01-smoke`                | 背景应用、样式表/测量规则安装、背景条覆盖用量行且与输入卡片等宽、进度条空闲隐藏、Token 行位置、设置页标签页、背景区块、UI 分组卡片与控件类型、行 `aria-labelledby/describedby`                                                                                                                          |
+| `02-controls`             | 3 个开关、3 个滑杆、2 个调色盘、深色主题默认色、语言切换（经设置页语言控件）                                                                                                                                                                                                                            |
+| `03-robustness`           | 稳定钩子优先（英文 pill + `display: contents` 包装层）、零布局影响与 fixed 探针、纯样式尺寸变化跟随、移除/重建用量行、连续开关不重复、窗口 resize                                                                                                                                                       |
+| `04-host-routes`          | `/list`、图片 200/ETag/304、路径穿越 404、`/folder` 的 405/403、token 汇总自洽                                                                                                                                                                                                                          |
+| `05-rightbar`             | 右栏收起/展开的临时网格过渡（中间帧宽度）、拖动宽度无过渡、全屏 panel 覆盖窗口/统一遮罩/主窗口隐藏、退出全屏恢复                                                                                                                                                                                        |
+| `08-security`             | `/health`、目录脱敏、响应头、SVG CSP、真实导航到 SVG 后脚本不执行                                                                                                                                                                                                                                       |
+| `06-image-zoom`           | 固定层图片滚轮缩放/双击还原；设置弹窗内图片不缩放；右栏图片预览的普通滚轮转换为 Ctrl+滚轮                                                                                                                                                                                                               |
+| `07-rotation`             | 轮换分组内切换、过渡层出现、三行设置顺序/控件值/无小字、分组 5 行滚动、仅勾选框选择、缩略图、选择不重排、拖动排序动画、切换固定后停止轮换                                                                                                                                                               |
+| `07b-animated-background` | 动图文件被列为背景并由已加载的固定 IMG 层绘制，根元素不再绘制背景图                                                                                                                                                                                                                                     |
+| `10-turn-masks`           | 每个对话一轮一张遮罩卡（宽度=阅读列宽+两侧留白）、舒适档 28px 轮次布局间距（写回宿主 `--dsh-chat-flow-gap`）、卡片间约 14px 壁纸缝（上边额外 6px 出血，保证用户气泡顶边被盖住；卡片层 margin 清零不受宿主 flow gap 影响）、用户消息与回复同卡、主窗口不再整列铺遮罩、移除会话后卡片/列标记/间距一起还原 |
+| `09-windows-titlebar`     | Windows 标题栏标记给主窗口列铺不透明底色后，靠槽位标记而不是一次性测量结果保持透明；丢失测量标记后仍透明；focus/visibility 重新测量；移除标记后图片仍在                                                                                                                                                 |
 
 ### 2.5 新增断言
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-chat-background",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Chat background image, sidebar veil, composer strip, task progress bar and all-session token total for the DeepSeek Harness (DSH) Web GUI.",
   "meta": {
     "title": "聊天背景",