test(web): assert the timestamp occlusion the sidebar gutter fixes

The e2e measured the reserved band but never the symptom the change is
named for. Headless chromium defaults to an overlay scrollbar, which is
the configuration where a bar can cover row content at all, so the
scenario already ran in the right mode: against clean master the band is
0 and the bar covers 7px of the relative time.

Adds timeCoveredBy, the overlap between the relative time's right edge
and the range the bar occupies, taking the bar's width from the sheet
where it applies and from the UA's overlay width otherwise. Assuming 0
there would report no occlusion in precisely the state that has it.

Keeps the band assertion rather than replacing it: the two catch
different regressions. Removing only scrollbar-gutter leaves
timeCoveredBy at 0, because the bar is then 8px and the row's right
padding is also 8px, so it abuts the timestamp without covering it.
Removing the pseudo-element width as well is what produces the overlap.
Each was mutation-checked with the other assertions in its test silenced.

Records in the note that the gutter and the ::-webkit-scrollbar width are
jointly necessary against an overlay bar, measured by deleting each from
the live cascade with the other in force: either alone drops the band
from 8 to 0.

.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md
-2026-07-28-themed-scrollbars-and-reserved-gutter.md: 71d2e5b5156d3bc54968552aa2eef82fab2ff443
-2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: fcae03440ff621d949f8158990e2d871590b7daa
+2026-07-28-themed-scrollbars-and-reserved-gutter.md: c52440bb057c5202ee90bcf53518fe62ba1379b7
+2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: e234106c47eeaf418aac4a09ced0dd6c854a439c

.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md

@@ -26,6 +26,8 @@ The track and the corner stay transparent, so the thumb reads against whatever s
 
 `.list` declares `scrollbar-gutter: stable`, which keeps the bar beside the rows instead of on top of them. `stable` rather than `auto` because `auto` reserves the gutter only while the list actually overflows: expanding a workspace group would then shift every row horizontally at the moment it starts scrolling. The reservation is unconditional and the rows never move.
 
+The gutter and the sheet's `::-webkit-scrollbar` width are jointly necessary against an overlay scrollbar, which is the configuration where the symptom exists at all. Measured on the running app by deleting each from the live cascade with the other left in force: either deletion alone takes the list's band from 8 to 0. The gutter states that space be reserved, and the pseudo-element width is what makes chromium treat the bar as occupying layout space rather than floating over the content. Neither half of this change is therefore optional for the reported bug, which is a second reason the two halves ship together.
+
 ## Alternatives considered
 
 **Per-module `::-webkit-scrollbar` rules in each scrolling component sheet.** Rejected: the client has thirteen scrolling containers across nine packages, every one would carry the same block, and the fourteenth would ship unthemed with nothing failing. A skin driven by design tokens belongs in the package that owns the tokens.
@@ -65,6 +67,8 @@ Two chromium measurement limits shape what the e2e can assert. The gate makes ch
 
 The gate itself has a negative control at the level it operates on: removing the `@supports` wrapper from the sheet, rebuilding `build:web`, and rerunning the e2e turns the `scrollbar-width: auto` assertion red with `thin`, which is the suppression the gate exists to prevent.
 
-Headless chromium draws overlay scrollbars, so a reserved gutter there does not shrink `clientWidth`. The reservation shows up as a non-zero `offsetWidth - clientWidth` band on the list; client-area geometry alone does not demonstrate it, and an assertion comparing the time element's right edge against the client-area edge holds with and without the reservation, so it would pass or fail on the platform's scrollbar style rather than on the declaration under test.
+Headless chromium draws overlay scrollbars, and that is the configuration in which the reported symptom exists, so the e2e reproduces the bug rather than approximating it: against clean master the list's band is 0 and the bar covers 7px of the relative time. A reserved gutter there does not shrink `clientWidth`, so an assertion comparing the time element's right edge against the client-area edge holds with and without the reservation and would pass or fail on the platform's scrollbar style rather than on the declaration under test. The two signals that do separate the states are the `offsetWidth - clientWidth` band and `timeCoveredBy`, the overlap measured against the bar's own width.
+
+Both are asserted because each catches a different regression, established by mutating one declaration at a time with the other assertions in that test silenced. Removing only the gutter leaves `timeCoveredBy` at 0 — the bar is then 8px and the row's right padding is also 8px, so it abuts the timestamp without covering it — and the band assertion is what fails. Removing the pseudo-element width as well, which is the actual master state, produces the overlap, and `timeCoveredBy` fails at 7. A headed run under xvfb cannot show the symptom in either state, because chromium paints a classic space-consuming bar there and `clientWidth` already excludes it.
 
 Verifying browser-visible plugin CSS needs a rebuild `pnpm run build:web` does not perform. `WorkspaceBrowser.module.css` never reaches `apps/web/dist`: ui-workspace loads as a runtime plugin and its CSS is inlined into `packages/client/ui-workspace/lib/client.js`, built by that package's own `bundle` script. A negative control that reruns only `build:web` therefore exercises a stale bundle and passes with the declaration removed, which reads as a vacuous test rather than as an invalid control. Rebuild with `pnpm --filter @deepseek-ai/dsh-client-ui-workspace run bundle`, confirm the artifact by grepping `lib/client.js` for the declaration, then `build:web`. No script in the web lane does this: `test:web` runs `build:web` alone, so every scroll-region or plugin-CSS change hits the same trap.

.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md

@@ -26,6 +26,8 @@ Status: implemented
 
 `.list` 声明 `scrollbar-gutter: stable`，使滚动条位于行的旁边而非行的上方。取 `stable` 而非 `auto`，因为 `auto` 只在列表确实溢出时才预留空位：那样展开一个工作区分组时，所有行会在列表开始滚动的那一刻发生水平位移。`stable` 的预留是无条件的，行不会移动。
 
+面对覆盖式滚动条——也就是这个症状唯一存在的那种形态——空位声明与样式表里的 `::-webkit-scrollbar` 宽度是共同必要的。在运行中的应用上实测：保留其中一条、从活的层叠中删掉另一条，任意一次单独删除都会让列表的条带从 8 降到 0。空位声明表述的是「要预留空间」，而伪元素宽度才是让 chromium 把滚动条视为占据布局空间、而不是浮在内容之上的原因。因此对这个 bug 而言，本次变更的两半都不是可选项，这也是两半必须一起交付的第二个理由。
+
 ## 曾考虑的替代方案
 
 **在每个滚动组件的样式表里各写一份 `::-webkit-scrollbar` 规则。** 之所以否决：客户端共有分布在九个包中的十三个滚动容器，每一个都要带上同一段规则，而第十四个会在没有任何门禁报错的情况下漏掉主题。由设计 token 驱动的皮肤应当归属于拥有这些 token 的包。
@@ -65,6 +67,8 @@ chromium 上有两处测量限制决定了 e2e 能断言什么。门禁使 chrom
 
 门禁本身在它起作用的层面有反向对照：把样式表中的 `@supports` 包裹去掉、重新 `build:web`、再跑 e2e，`scrollbar-width: auto` 那条断言会以 `thin` 变红，而这正是门禁存在所要阻止的那种静音。
 
-headless chromium 绘制的是覆盖式滚动条，因此其中预留空位不会缩小 `clientWidth`。该预留表现为列表上非零的 `offsetWidth - clientWidth` 条带；仅凭内容区几何无法证明它，而把时间元素右边缘与内容区右边缘做比较的断言，在有无预留的两种状态下都成立，因此它的通过或失败取决于平台的滚动条样式，而不是取决于被测的那条声明。
+headless chromium 绘制的是覆盖式滚动条，而这恰好就是被报告症状存在的那种形态，因此这个 e2e 复现的是这个 bug 本身，而不是它的近似：在干净的 master 上，列表条带为 0，滚动条盖住相对时间 7px。其中预留空位不会缩小 `clientWidth`，因此把时间元素右边缘与内容区右边缘做比较的断言在有无预留的两种状态下都成立，它的通过或失败取决于平台的滚动条样式，而不是取决于被测的那条声明。真正能区分两种状态的两个量是 `offsetWidth - clientWidth` 条带，以及以滚动条自身宽度为基准量出的重叠量 `timeCoveredBy`。
+
+两者都要断言，因为各自捕捉的是不同的回归；这一点通过每次只改动一条声明、并把同一个测试里的其余断言静音来确定。只删掉空位声明时 `timeCoveredBy` 仍为 0——此时滚动条是 8px，而行的右内边距也是 8px，于是它紧贴时间戳但并未盖住——失败的是条带那条断言。再把伪元素宽度也删掉（这才是 master 的真实状态）才会产生重叠，此时 `timeCoveredBy` 以 7 变红。在 xvfb 下的有头运行无论哪种状态都看不到这个症状，因为 chromium 在那里画的是经典占位滚动条，`clientWidth` 本来就已经把它排除了。
 
 验证浏览器可见的插件 CSS 需要一次 `pnpm run build:web` 并不执行的重建。`WorkspaceBrowser.module.css` 从不进入 `apps/web/dist`：ui-workspace 以运行时插件方式加载，其 CSS 内联进 `packages/client/ui-workspace/lib/client.js`，由该包自己的 `bundle` 脚本构建。因此只重跑 `build:web` 的反向对照实际测的是旧产物，去掉声明后仍会通过，看起来像测试无效，实际是对照无效。正确做法是先 `pnpm --filter @deepseek-ai/dsh-client-ui-workspace run bundle`，用 grep 在 `lib/client.js` 中确认该声明确实存在或消失，然后再 `build:web`。web 通道中没有任何脚本会做这一步：`test:web` 只运行 `build:web`，因此任何滚动区域或插件 CSS 的改动都会碰到同一个陷阱。

apps/web/tests/sidebar-scrollbar.e2e.ts

@@ -14,11 +14,35 @@
 //
 // Headless-chromium caveats, load-bearing for what is asserted below.
 //
-// Chromium paints an OVERLAY scrollbar that consumes no layout width, so
-// comparing the time element's right edge against the list's client-area right
-// edge holds with and without the reservation and proves nothing; the reserved
-// band width is the only layout signal that distinguishes the two states. See
-// the assertions for which one is the control.
+// Headless chromium defaults to an OVERLAY scrollbar: one drawn on top of the
+// content, consuming no layout width unless something reserves space. That is
+// the mode in which the reported symptom exists at all, so this environment
+// reproduces it rather than merely approximating it — measured against clean
+// master, where the list's band is 0 and the bar covers 7px of the relative
+// time. (Under a classic space-consuming bar, `clientWidth` already excludes
+// the bar and nothing can be covered; a headed run under xvfb behaves that way
+// and cannot show the symptom.)
+//
+// The consequence for assertions: comparing the time element's right edge
+// against the list's CLIENT-area right edge holds in both states and proves
+// nothing, because with an overlay bar the client edge is the border edge. The
+// two signals that do separate the states are the reserved band width and
+// `timeCoveredBy`, which measures the overlap against the bar's own width.
+//
+// Both the `scrollbar-gutter: stable` reservation and the sheet's
+// `::-webkit-scrollbar` width are needed for that band, and neither suffices:
+// measured on the running app, deleting either one takes the band from 8 to 0
+// while the other stays in force. The gutter states that space be reserved; the
+// pseudo-element width is what makes chromium treat the bar as occupying layout
+// space in the first place.
+//
+// That conjunction is why `band` and `timeCoveredBy` are both asserted and
+// neither replaces the other. Removing only the gutter leaves `timeCoveredBy` at
+// 0, because the bar is then 8px wide and the row's right padding is also 8px,
+// so it abuts the timestamp without covering it; `band` catches that case.
+// Removing both — the actual master state — is what produces the reported
+// overlap, and `timeCoveredBy` measures it at 7. Each was mutation-checked with
+// the other assertions in its test silenced.
 //
 // Chromium also takes the `::-webkit-scrollbar*` path, not the standard
 // properties: scrollbar.css gates `scrollbar-width`/`scrollbar-color` behind
@@ -74,6 +98,14 @@ interface ListMetrics {
   borderRight: number
   /** Right edge of the first row's relative-time element, the content the unreserved bar covered. */
   timeRight: number
+  /**
+   * Pixels of the relative time the scrollbar paints over: how far its right
+   * edge reaches into the band the bar occupies, `[borderRight - barWidth,
+   * borderRight]`. This is the reported symptom as a number, and it is the one
+   * geometric signal that separates the two states in this environment — see
+   * the file header on why `clientWidth` comparisons cannot.
+   */
+  timeCoveredBy: number
 }
 
 /**
@@ -119,9 +151,11 @@ function measureList(page: Page): Promise<ListMetrics> {
       .filter(rule => rule.selectorText === '::-webkit-scrollbar-thumb:hover')
       .map(rule => rule.style.getPropertyValue('background'))
     const style = getComputedStyle(list)
+    const pseudoWidth = getComputedStyle(list, '::-webkit-scrollbar').width
+    const barWidth = pseudoWidth === 'auto' ? 15 : Number.parseFloat(pseudoWidth)
     return {
       gutter: style.scrollbarGutter,
-      width: getComputedStyle(list, '::-webkit-scrollbar').width,
+      width: pseudoWidth,
       track: getComputedStyle(list, '::-webkit-scrollbar-track').backgroundColor,
       standardWidth: style.scrollbarWidth,
       standardColor: style.scrollbarColor,
@@ -133,6 +167,14 @@ function measureList(page: Page): Promise<ListMetrics> {
       clientRight: list.getBoundingClientRect().left + list.clientWidth,
       borderRight: list.getBoundingClientRect().right,
       timeRight: time.getBoundingClientRect().right,
+      // The bar is drawn in the rightmost `barWidth` of the border box, whether
+      // or not that space was reserved. Its width comes from the sheet where the
+      // sheet applies, and from the UA's own overlay bar otherwise — 15px is
+      // what this chromium paints, measured against master where the rule is
+      // absent. Taking the UA width as the fallback is what keeps the assertion
+      // honest: assuming 0 there would report no occlusion precisely in the
+      // state that has it.
+      timeCoveredBy: Math.max(0, time.getBoundingClientRect().right - (list.getBoundingClientRect().right - barWidth)),
     }
   })
 }
@@ -201,11 +243,19 @@ describe('web e2e: sidebar session list scrollbar (reserved gutter / themed thum
     // drawn over it. Removing the declaration makes it exactly 0. The value
     // itself is not pinned — it tracks `scrollbar-width` and the platform.
     expect(metrics.band).toBeGreaterThan(0)
-    // With the band reserved, the row's relative time — flush against the
-    // row's right padding, the element the unreserved bar covered — ends
-    // inside the content area, clear of the bar. Alone this would be vacuous
-    // under chromium's overlay scrollbar (see the file header); it is
-    // meaningful only conjoined with the band assertion above.
+    // The reported symptom, stated directly: no part of the row's relative time
+    // lies under the bar. Measures 7 on clean master — the `h` of `1h` is the
+    // covered part. Unlike the client-edge comparison below it does not go
+    // vacuous under an overlay scrollbar, because it measures against the bar's
+    // own width rather than against a content edge the overlay bar does not
+    // move. It is not a replacement for the band assertion above; see the file
+    // header for which regression each one catches.
+    expect(metrics.timeCoveredBy).toBe(0)
+    // Corollaries of the reservation, kept because they pin where the band sits
+    // rather than only that it exists: the time ends inside the content area,
+    // and the content area ends before the border box. Each holds in both
+    // states on its own (see the file header) and is meaningful only alongside
+    // the two assertions above.
     expect(metrics.timeRight).toBeLessThanOrEqual(metrics.clientRight)
     expect(metrics.clientRight).toBeLessThan(metrics.borderRight)
     expect(tripwire.pageErrors).toEqual([])