fix(web): decide the sidebar's pointer leave by geometry, and tighten the gate

Review findings from the first round:

- ui-settings renders its full-viewport panel as a fixed-position DESCENDANT
  of the sidebar column, so `pointerleave` never fires when the pointer moves
  onto it and the bars stayed drawn after it closed. Leaving is now decided
  against the column's box from a document-level pointermove that exists only
  while the bars are drawn; the element's own leave stays for the pointer that
  leaves the window.
- The rebind gate judges the rule rather than each declaration, so a pair that
  mixes `transparent` with an l2 hover no longer passes, and the elevation
  half compares whole values instead of token shape.
- Hiding no longer exempts a sheet from the elevated-surface rebind check.
- The e2e polls the reveal before reading a colour for the golden, and pins
  that a pointerless scroll draws no thumb.

.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.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/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md
-2026-08-04-pointer-revealed-sidebar-scrollbars.md: fdc68fc0eda0aa68b3ec09d93df4a313f39f6d35
-2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md: 8b11aec961a713fe5e07046dee7473fa34471689
+2026-08-04-pointer-revealed-sidebar-scrollbars.md: eb86f710e44cd8f1fb2cef41db99504af42413bb
+2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md: 598c10dc2373eeb821d05f349a662156b194c71b

.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md

@@ -12,7 +12,9 @@ The sidebar's session list overflows after a handful of sessions, and from that
 
 `SidebarRoot` tracks the pointer over the whole column and carries a `quietBars` class whenever it is outside. The rule that class selects rebinds ui-theme's indirection pair — `--dsh-scrollbar-thumb` and `--dsh-scrollbar-thumb-hover` — to `transparent`, so every scroll region nested under the column draws no thumb. The session list is the only one today; a future one inherits the behavior rather than opting into it.
 
-The tail is `SCROLLBAR_LINGER_MS = 2000`: `pointerleave` starts a timer, `pointerenter` cancels a pending one, and only the timer firing puts the class back. A pointer that crosses the column's edge and returns — travelling around a portalled menu, or overshooting on the way to a row — never sees the thumb blink.
+The tail is `SCROLLBAR_LINGER_MS = 2000`: leaving arms a timer, entering cancels a pending one, and only the timer firing puts the class back. A pointer that crosses the column's edge and returns — travelling around a portalled menu, or overshooting on the way to a row — never sees the thumb blink.
+
+Entering is the column's own `pointerenter`; leaving is decided against the column's box, from a `pointermove` listener that exists only while the bars are drawn. DOM containment cannot decide the leave, because ui-settings renders its full-viewport settings panel as a fixed-position *descendant* of this column: a pointer moved onto that panel — or onto the conversation after it closes — never fires `pointerleave` here, and the bars would stay drawn over a column nobody is pointing at. The element's own leave is kept for the one case geometry cannot see, a pointer that leaves the window and emits no further moves.
 
 The pointer surface is the column, not the list. A pointer heading for the bar crosses the logo row, the New Session capsule, and the search field first, so revealing on the list alone would surface the bar only once the pointer was already among the rows.
 
@@ -20,7 +22,9 @@ The pointer surface is the column, not the list. A pointer heading for the bar c
 
 The indirection pair rather than a rule on the list, because that pair is ui-theme's documented rebinding seam: one declaration reaches both rendering paths (the WebKit pseudo-elements and Firefox's `scrollbar-color`), and custom properties inherit, which is what makes the column — rather than each scroll region in it — the thing that owns the state.
 
-That widens the rebinding contract, so its gate states the new shape rather than accepting it by silence: `ui-theme/tests/scrollbar-styles.spec.ts` now admits exactly two rebind targets, an `-l2` token pair or `transparent`, and rejects everything else — an l1 rebind, which only restates the base-surface default under a name that reads as an elevation, and a literal colour, which leaves the palette.
+That widens the rebinding contract, so its gate states the new shape rather than accepting it by silence: `ui-theme/tests/scrollbar-styles.spec.ts` admits exactly two rebind targets, the l2 pair or `transparent`, and judges the *rule* rather than each declaration — a mixed rule (`thumb: transparent` beside an l2 hover) would repaint the bar the moment the pointer reached it while passing a per-declaration check. The elevation half compares whole values against the pair's canonical spelling, which is also what rejects a crossed pair and a token wrapped in a literal expression; an l1 rebind and a bare colour were already out.
+
+Hiding no longer counts as elevating: only an l2 rebind exempts a sheet from "every sheet that scrolls on an elevated surface rebinds". A sheet that hides its bars and also scrolls on an elevated surface still owes the l2 pair for whatever draws a thumb there.
 
 ## Alternatives considered
 
@@ -38,17 +42,22 @@ That widens the rebinding contract, so its gate states the new shape rather than
 
 ## Consequences
 
-- A list scrolled by keyboard or by a touch drag shows no thumb once the linger passes, since neither leaves a pointer over the column.
+- A list scrolled by keyboard or by a touch drag shows no thumb once the linger passes, since neither leaves a pointer over the column. The e2e pins this rather than only describing it.
+- Dragging the thumb itself out of the column does not hide it mid-drag: the scrollbar takes the pointer capture, so the page receives no `pointermove` while the button is held. Measured in Chromium — the bar stays drawn and keeps scrolling with the pointer 900px to its right, past the linger window.
 - The column starts quiet on a cold load and stays so until the pointer first moves over it. A pointer already parked there when the page loads fires nothing until it moves, which is the browser's rule rather than this shell's.
-- An elevated surface nested in the column that rebinds the pair to l2 for its own elevation overrides the quiet state and keeps its bar drawn. Nothing in the sidebar does this today; the settings panel portals out of the column entirely.
+- An elevated surface nested in the column that rebinds the pair to l2 for its own elevation overrides the quiet state and keeps its bar drawn. Nothing in the sidebar does this today.
 - The shell's DOM now carries a state class, so ui-sidebar's shell snapshots pin `quietBars` and a regression in the default state is a snapshot diff rather than something someone has to notice in a screenshot.
 
 ## Testing
 
-`packages/client/ui-sidebar/tests/pointer-scrollbars.spec.tsx` drives the class through the transitions with fake timers: revealed on entry, still revealed one millisecond before the linger closes, quiet one millisecond after, and cancelled by a return within the window. It also unmounts mid-linger and asserts no timer survives — a pending hide firing into a dead component is the failure this shape is prone to. The events are `pointerover`/`pointerout` carrying a `relatedTarget`, because React synthesizes enter and leave from those and ignores the raw ones.
+`packages/client/ui-sidebar/tests/pointer-scrollbars.spec.tsx` drives the class through the transitions with fake timers: revealed on entry, still revealed one millisecond before the linger closes, quiet one millisecond after, and cancelled by a return within the window. Two more cover the geometric leave: a `pointermove` landing outside the column's box hides the bars without any DOM leave (the settings-panel shape), and one landing back inside cancels a pending hide. It also unmounts mid-linger and asserts no timer survives — a pending hide firing into a dead component is the failure this shape is prone to. The events are `pointerover`/`pointerout` carrying a `relatedTarget`, because React synthesizes enter and leave from those and ignores the raw ones.
 
 `packages/client/ui-sidebar/tests/scrollbar-quiet-styles.spec.ts` reads the sheet: the rule states both halves of the pair — rebinding the resting thumb alone would leave the hover colour painting the moment the pointer reached the bar — and states no `scrollbar-gutter`, which belongs to the scrolling region.
 
-`apps/web/tests/sidebar-scrollbar.e2e.ts` is where the two halves meet a real engine. It parks the pointer over the list before every colour reading, since a scenario that never moves the mouse would measure the quiet state throughout and read as vacuous green. Its own test then moves the pointer away, asserts the thumb is still drawn on the leave itself, polls until it resolves to `rgba(0, 0, 0, 0)`, and re-measures the geometry there to prove the reservation held while the bar was hidden. The committed golden records the thumb at both pointer positions in both palettes.
+`apps/web/tests/sidebar-scrollbar.e2e.ts` is where the two halves meet a real engine. It parks the pointer over the list before every colour reading, since a scenario that never moves the mouse would measure the quiet state throughout and read as vacuous green. Its own test then moves the pointer away, asserts the thumb is still drawn on the leave itself, polls until it resolves to `rgba(0, 0, 0, 0)`, re-measures the geometry there to prove the reservation held while the bar was hidden, and scrolls the list programmatically — what a keyboard or a touch drag does — to pin that a pointerless scroll draws nothing. The committed golden records the thumb at both pointer positions in both palettes.
 
 The e2e's control is a mutation, and it needs the plugin's own bundle: dropping `quietBars` from the shell, rebuilding `@deepseek-ai/dsh-client-ui-sidebar` and only then `build:web`, turns that test red on the thumb resolving to `rgb(229, 229, 229)` where it expects `rgba(0, 0, 0, 0)`. Rerunning `build:web` alone exercises a stale bundle and passes with the change removed, which is the trap [the gutter note](../bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md) documented.
+
+The widened gate has its own controls, each a one-declaration mutation of a real sheet: crossing `transparent` with an l2 hover, and wrapping an l2 token in `color-mix(…)`, each turn the pair assertion red.
+
+The recording that demonstrates this behavior has to be headed. Headless Chromium reserves the band (`offsetWidth - clientWidth` is 8) but paints no thumb into a captured frame — measured by counting thumb-coloured pixels in the band across the reveal, which stays at noise level in headless and jumps from 46 to 1466 in a headed run.

.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md

@@ -12,7 +12,9 @@ Status: implemented
 
 `SidebarRoot` 跟踪整列上的指针，只要指针不在列内就给根元素挂上 `quietBars` 类。该类选中的规则把 ui-theme 的那组间接变量——`--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`——重新绑定为 `transparent`，于是嵌套在这一列下的每个滚动区域都不绘制滑块。今天这样的区域只有会话列表；将来新增的区域会直接继承这一行为，而不需要逐个接入。
 
-拖尾是 `SCROLLBAR_LINGER_MS = 2000`：`pointerleave` 启动一个定时器，`pointerenter` 取消尚未触发的定时器，只有定时器真正触发才会把类加回去。指针越过列边界又折返时——绕过一个 portal 菜单，或是奔向某一行时冲过了头——不会看到滑块闪动。
+拖尾是 `SCROLLBAR_LINGER_MS = 2000`：离开会启动一个定时器，进入会取消尚未触发的定时器，只有定时器真正触发才会把类加回去。指针越过列边界又折返时——绕过一个 portal 菜单，或是奔向某一行时冲过了头——不会看到滑块闪动。
+
+进入用的是列自身的 `pointerenter`；离开则按列的盒子判定，由一个只在滚动条可见期间存在的 `pointermove` 监听完成。DOM 包含关系无法判定离开：ui-settings 把整屏的设置面板渲染为这一列的 fixed 定位**后代**，指针移到该面板上——或在面板关闭后移到对话区——都不会在这里触发 `pointerleave`，滚动条就会继续画在一个没人指向的列上。元素自身的 leave 仍然保留，用于几何判定看不到的那一种情况：指针移出窗口后不再产生任何移动事件。
 
 承载指针的是整列，而不是列表。奔向滚动条的指针会先经过 logo 行、New Session 胶囊和搜索框，所以只在列表上显示，会让滚动条等到指针已经落在行中间时才出现。
 
@@ -20,7 +22,9 @@ Status: implemented
 
 选择这组间接变量而不是给列表加规则，是因为这组变量正是 ui-theme 写明的重新绑定接缝：一次声明同时作用于两条渲染路径（WebKit 伪元素与 Firefox 的 `scrollbar-color`），而自定义属性会继承——这正是让整列、而不是列内每个滚动区域，成为该状态所有者的原因。
 
-这拓宽了重新绑定契约，因此它的门禁把新的形态明写出来，而不是默许通过：`ui-theme/tests/scrollbar-styles.spec.ts` 现在只接受两种重新绑定目标，即一组 `-l2` token 或 `transparent`，其余一律拒绝——绑回 l1 只是用一个听起来像抬升层级的名字重述基础表面的默认值，而字面颜色则脱离了调色板。
+这拓宽了重新绑定契约，因此它的门禁把新的形态明写出来，而不是默许通过：`ui-theme/tests/scrollbar-styles.spec.ts` 只接受两种重新绑定目标，即 l2 那一组或 `transparent`，并且判定的是**整条规则**而不是逐条声明——混合规则（`thumb: transparent` 与 l2 的 hover 并列）会在指针一碰到滚动条时重新上色，却能通过逐条检查。抬升那一半按整个值与这组变量的规范写法比对，这同时也拒绝了交叉绑定和被包在字面表达式里的 token；绑回 l1 与裸颜色本来就在门外。
+
+隐藏不再算作抬升：只有 l2 重绑才能让一张样式表免于「任何既滚动又绘制抬升表面的样式表都必须重新绑定」。既隐藏滚动条又在抬升表面上滚动的样式表，仍然欠着那里真正绘制滑块时所需的 l2。
 
 ## Alternatives considered
 
@@ -38,17 +42,22 @@ Status: implemented
 
 ## Consequences
 
-- 用键盘或触摸拖动滚动的列表，在拖尾结束后不显示滑块，因为这两种方式都不会把指针留在列上。
+- 用键盘或触摸拖动滚动的列表，在拖尾结束后不显示滑块，因为这两种方式都不会把指针留在列上。e2e 会钉住这一点，而不只是把它写下来。
+- 拖动滑块本身移出列不会在拖动中途把它隐藏：滚动条会接管指针捕获，按住按键期间页面收不到 `pointermove`。已在 Chromium 实测——指针拖到列右侧 900px 处、超过拖尾窗口后，滚动条依然绘制并继续滚动。
 - 冷启动时该列处于静默状态，直到指针第一次移到它上面为止。页面加载时就停在那里的指针在移动之前不会触发任何事件，这是浏览器的规则，而非这个外壳的。
-- 嵌套在列内、为自身抬升层级把这组变量重新绑定到 l2 的抬升表面，会覆盖静默状态并继续绘制自己的滚动条。今天侧边栏内没有这样的表面；设置面板整个 portal 到了列之外。
+- 嵌套在列内、为自身抬升层级把这组变量重新绑定到 l2 的抬升表面，会覆盖静默状态并继续绘制自己的滚动条。今天侧边栏内没有这样的表面。
 - 外壳的 DOM 现在带有一个状态类，因此 ui-sidebar 的外壳快照会钉住 `quietBars`，默认状态出现回归时表现为快照 diff，而不是需要有人从截图里看出来的东西。
 
 ## Testing
 
-`packages/client/ui-sidebar/tests/pointer-scrollbars.spec.tsx` 用假定时器把这个类走过各次跃迁：进入时显示，拖尾结束前 1 毫秒仍然显示，结束后 1 毫秒转为静默，以及窗口内折返会取消隐藏。它还在拖尾进行中卸载组件并断言没有定时器存活——待触发的隐藏落到已销毁的组件上，正是这种写法容易犯的错。事件用的是带 `relatedTarget` 的 `pointerover`／`pointerout`，因为 React 由它们合成 enter 与 leave，而会忽略原生的那两个事件。
+`packages/client/ui-sidebar/tests/pointer-scrollbars.spec.tsx` 用假定时器把这个类走过各次跃迁：进入时显示，拖尾结束前 1 毫秒仍然显示，结束后 1 毫秒转为静默，以及窗口内折返会取消隐藏。另有两条覆盖几何判定的离开：落在列盒子之外的 `pointermove` 会在没有任何 DOM leave 的情况下隐藏滚动条（即设置面板那种形态），落回盒子之内的则取消待触发的隐藏。它还在拖尾进行中卸载组件并断言没有定时器存活——待触发的隐藏落到已销毁的组件上，正是这种写法容易犯的错。事件用的是带 `relatedTarget` 的 `pointerover`／`pointerout`，因为 React 由它们合成 enter 与 leave，而会忽略原生的那两个事件。
 
 `packages/client/ui-sidebar/tests/scrollbar-quiet-styles.spec.ts` 直接读样式表：该规则必须写出这组变量的两半——只重新绑定静止态滑块，会让指针一碰到滚动条就露出 hover 颜色——并且不得出现 `scrollbar-gutter`，那属于滚动区域自己。
 
-`apps/web/tests/sidebar-scrollbar.e2e.ts` 是两半在真实引擎里汇合的地方。它在每次读取颜色前先把指针停在列表上，因为一个从不移动鼠标的场景全程测到的都是静默状态，会变成空洞的绿。随后它自己的用例把指针移开，断言在 leave 当下滑块仍在绘制，轮询直到它解析为 `rgba(0, 0, 0, 0)`，并在该状态下重新测量几何，以证明滚动条隐藏期间那份预留依然生效。提交的 golden 记录了两套调色板下、两个指针位置上的滑块颜色。
+`apps/web/tests/sidebar-scrollbar.e2e.ts` 是两半在真实引擎里汇合的地方。它在每次读取颜色前先把指针停在列表上，因为一个从不移动鼠标的场景全程测到的都是静默状态，会变成空洞的绿。随后它自己的用例把指针移开，断言在 leave 当下滑块仍在绘制，轮询直到它解析为 `rgba(0, 0, 0, 0)`，在该状态下重新测量几何以证明滚动条隐藏期间那份预留依然生效，并以编程方式滚动列表——键盘或触摸拖动所做的事——来钉住无指针滚动不绘制任何滑块。提交的 golden 记录了两套调色板下、两个指针位置上的滑块颜色。
 
 这条 e2e 的对照是一次 mutation，而它需要插件自己的产物：把 `quietBars` 从外壳中去掉，先重新构建 `@deepseek-ai/dsh-client-ui-sidebar`、之后再跑 `build:web`，该用例会因为滑块解析为 `rgb(229, 229, 229)`、而期望 `rgba(0, 0, 0, 0)` 而变红。只重跑 `build:web` 用的是过期产物，即使改动已被删除也照样通过，这正是[空槽 Agent Note（agent 决策记录）](../bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)记录过的陷阱。
+
+拓宽后的门禁也有自己的对照，每个都是对真实样式表的一处声明改动：把 `transparent` 与 l2 的 hover 混用，以及把 l2 token 包进 `color-mix(…)`，都会让这条成对断言变红。
+
+演示这一行为的录制必须用有头浏览器。无头 Chromium 会预留那条带（`offsetWidth - clientWidth` 为 8），却不会把滑块画进捕获帧——通过统计带内滑块色像素在显示前后的变化实测：无头一直停在噪声水平，有头则从 46 跳到 1466。

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

@@ -220,6 +220,10 @@ async function measurePalette(page: Page): Promise<PaletteMetrics> {
   await expect.poll(async () => resolveThumb(page), { timeout: 10_000 }).toBe(NO_THUMB)
   const quietThumb = await resolveThumb(page)
   await pointAt(page, 'list')
+  // Poll the reveal too: the reading below is a colour, and taking it in the
+  // same tick as the pointer move would race React's flush and land a
+  // transparent thumb in the golden.
+  await expect.poll(async () => resolveThumb(page), { timeout: 10_000 }).not.toBe(NO_THUMB)
   return { hovered: await measureList(page), quietThumb }
 }
 
@@ -410,6 +414,13 @@ describe('web e2e: sidebar session list scrollbar (reserved gutter / themed thum
     expect(quiet.gutter).toBe('stable')
     expect(quiet.band).toBeGreaterThan(0)
     expect(quiet.timeCoveredBy).toBe(0)
+    // Scrolling without a pointer — what a keyboard or a touch drag does —
+    // leaves the column quiet. This is the change's one deliberate loss, and
+    // it is pinned here rather than only described, so making a scroll
+    // re-reveal the bar has to be a decision rather than a side effect.
+    await page.locator('[role="tree"][aria-label="Sessions"]').evaluate((el) => { el.scrollTop += 200 })
+    await page.waitForTimeout(500)
+    expect(await resolveThumb(page)).toBe(NO_THUMB)
     await pointAt(page, 'list')
     await expect.poll(async () => resolveThumb(page), { timeout: 10_000 }).toBe(revealed)
     expect(tripwire.pageErrors).toEqual([])

packages/client/ui-sidebar/src/client/SidebarRoot.tsx

@@ -73,25 +73,58 @@ export function SidebarRoot({
   // away): drawn while it is inside, and for SCROLLBAR_LINGER_MS after it
   // leaves. A pointer that returns within that window cancels the pending
   // hide rather than restarting from a hidden bar.
+  const column = useRef<HTMLDivElement>(null)
   const [pointerInside, setPointerInside] = useState(false)
   const lingerTimer = useRef<number | undefined>(undefined)
-  useEffect(() => () => { window.clearTimeout(lingerTimer.current) }, [])
+  const armLinger = (): void => {
+    if (lingerTimer.current !== undefined) return
+    lingerTimer.current = window.setTimeout(() => {
+      lingerTimer.current = undefined
+      setPointerInside(false)
+    }, SCROLLBAR_LINGER_MS)
+  }
+  const cancelLinger = (): void => {
+    window.clearTimeout(lingerTimer.current)
+    lingerTimer.current = undefined
+  }
+  // Leaving is decided by the column's BOX, not by DOM containment, and only
+  // while the bars are drawn. ui-settings renders its full-viewport panel as a
+  // fixed-position DESCENDANT of this column, so a pointer moved onto that
+  // panel — or onto the conversation once it closes — fires no `pointerleave`
+  // here, and the bars would stay drawn over a column nobody is pointing at.
+  // The element's own leave stays as the one signal geometry cannot give: a
+  // pointer that leaves the window emits no further moves.
+  useEffect(() => {
+    if (!pointerInside) return
+    const onMove = (event: PointerEvent): void => {
+      const rect = column.current?.getBoundingClientRect()
+      /* v8 ignore next -- the listener only exists while the column is mounted and revealed. */
+      if (rect === undefined) return
+      const inside = event.clientX >= rect.left && event.clientX < rect.right
+        && event.clientY >= rect.top && event.clientY < rect.bottom
+      if (inside) cancelLinger()
+      else armLinger()
+    }
+    document.addEventListener('pointermove', onMove)
+    return () => {
+      document.removeEventListener('pointermove', onMove)
+      cancelLinger()
+    }
+  }, [pointerInside])
 
   return (
     <div
+      ref={column}
       className={clsx(
         css.root, !wide && css.collapsed, !wide && everWide.current && css.railIn,
         collapsed && wide && css.fading, !pointerInside && css.quietBars,
       )}
       style={wide ? { width: collapsed ? lastWideWidth.current : width } : undefined}
       onPointerEnter={() => {
-        window.clearTimeout(lingerTimer.current)
+        cancelLinger()
         setPointerInside(true)
       }}
-      onPointerLeave={() => {
-        window.clearTimeout(lingerTimer.current)
-        lingerTimer.current = window.setTimeout(() => { setPointerInside(false) }, SCROLLBAR_LINGER_MS)
-      }}
+      onPointerLeave={() => { armLinger() }}
     >
       <div className={css.logoRow}>
         {/* Expanded, the wordmark doubles as a New Session shortcut; the

packages/client/ui-sidebar/tests/pointer-scrollbars.spec.tsx

@@ -11,6 +11,10 @@ import type { SidebarRootComponentProps, SidebarSectionOwnerProps } from '../src
 import { SidebarRoot } from '../src/client/SidebarRoot.tsx'
 import { en } from '../src/client/locales.ts'
 
+/** Pinned column box; the shell compares pointer coordinates against it. */
+const COLUMN_WIDTH = 280
+const COLUMN_HEIGHT = 600
+
 const t: SidebarRootComponentProps['t'] = key => (en as Record<string, string>)[key] ?? key
 /** The shell never reads the global hooks; the props share carries them regardless. */
 const neverHook = (() => { throw new Error('shell must not read global hooks') }) as never
@@ -36,6 +40,14 @@ function mountColumn(): { column: HTMLElement; quiet: () => boolean } {
   )
   const column = view.container.firstElementChild
   if (!(column instanceof HTMLElement)) throw new Error('sidebar column not rendered')
+  // jsdom lays nothing out, and the leave decision is geometric: pin the box
+  // the shell reads so a coordinate can be inside or outside it.
+  Object.defineProperty(column, 'getBoundingClientRect', {
+    value: () => ({
+      left: 0, top: 0, right: COLUMN_WIDTH, bottom: COLUMN_HEIGHT,
+      x: 0, y: 0, width: COLUMN_WIDTH, height: COLUMN_HEIGHT, toJSON: () => ({}),
+    }),
+  })
   // CSS-module locals are hashed in this bench, so the state is read as a
   // substring of the class list rather than as an exact local name.
   return { column, quiet: () => [...column.classList].some(name => name.includes('quietBars')) }
@@ -54,6 +66,16 @@ function movePointer(column: HTMLElement, direction: 'in' | 'out'): void {
   else fireEvent.pointerOut(column, { relatedTarget: outside })
 }
 
+/**
+ * Move the pointer over the document, as a pointer crossing a fixed overlay
+ * that is a DOM descendant of the column does.
+ * @param x - client x coordinate.
+ * @param y - client y coordinate.
+ */
+function movePointerOverDocument(x: number, y: number): void {
+  fireEvent.pointerMove(document, { clientX: x, clientY: y })
+}
+
 describe('SidebarRoot pointer-revealed scrollbars', () => {
   it('draws them only while the pointer is inside, and lingers on the way out', () => {
     vi.useFakeTimers()
@@ -83,6 +105,45 @@ describe('SidebarRoot pointer-revealed scrollbars', () => {
     expect(quiet()).toBe(false)
   })
 
+  it('hides when the pointer moves outside the column box without leaving its subtree', () => {
+    // ui-settings renders its full-viewport panel as a fixed-position
+    // DESCENDANT of the column, so DOM containment reports the pointer as
+    // still inside while it is visually somewhere else entirely.
+    vi.useFakeTimers()
+    const { column, quiet } = mountColumn()
+    movePointer(column, 'in')
+    expect(quiet()).toBe(false)
+    movePointerOverDocument(COLUMN_WIDTH + 400, 300)
+    act(() => { vi.advanceTimersByTime(2000) })
+    expect(quiet()).toBe(true)
+  })
+
+  it('does not restart the window when the pointer keeps moving outside', () => {
+    vi.useFakeTimers()
+    const { column, quiet } = mountColumn()
+    movePointer(column, 'in')
+    movePointer(column, 'out')
+    act(() => { vi.advanceTimersByTime(1500) })
+    // A pending hide is left alone rather than re-armed: otherwise a pointer
+    // resting outside the column would keep pushing the bars' disappearance
+    // out, one move at a time.
+    movePointerOverDocument(COLUMN_WIDTH + 400, 300)
+    act(() => { vi.advanceTimersByTime(600) })
+    expect(quiet()).toBe(true)
+  })
+
+  it('keeps them drawn while the pointer moves inside the column box', () => {
+    vi.useFakeTimers()
+    const { column, quiet } = mountColumn()
+    movePointer(column, 'in')
+    movePointer(column, 'out')
+    // A move landing back inside the box cancels the pending hide, the same
+    // way re-entering the element does.
+    movePointerOverDocument(COLUMN_WIDTH - 10, 300)
+    act(() => { vi.advanceTimersByTime(5000) })
+    expect(quiet()).toBe(false)
+  })
+
   it('drops the pending hide when the column unmounts', () => {
     vi.useFakeTimers()
     const { column } = mountColumn()

packages/client/ui-theme/tests/scrollbar-styles.spec.ts

@@ -33,6 +33,11 @@ const TOKEN_PREFIX = '--dsw-alias-scrollbar-'
 const INDIRECTION_PREFIX = '--dsh-scrollbar-'
 /** The one non-token rebind value: a surface that draws no thumb at all. */
 const HIDDEN_THUMB = 'transparent'
+/** The elevation rebind, spelled per property: value-wholeness, not token shape. */
+const ELEVATED_REBIND = new Map([
+  ['--dsh-scrollbar-thumb', '--dsw-alias-scrollbar-bg-l2'],
+  ['--dsh-scrollbar-thumb-hover', '--dsw-alias-scrollbar-hover-l2'],
+].map(([property, token]) => [property!, `var(${token!})`]))
 
 /**
  * Flatten a stylesheet into rules. Whitespace, declaration order, and trailing
@@ -181,8 +186,13 @@ interface SheetSurfaces {
   elevated: Set<string>
   /** True when some rule declares `overflow*: auto|scroll`. */
   scrolls: boolean
-  /** True when some rule rebinds the indirection. */
-  rebinds: boolean
+  /**
+   * True when some rule rebinds the indirection to an ELEVATION. A rule that
+   * only hides the bar (`transparent`) does not count: it states no elevation,
+   * so a sheet that hides its bars and also scrolls on an elevated surface
+   * still owes the l2 pair for whatever draws a thumb there.
+   */
+  rebindsElevation: boolean
 }
 const sheetSurfaces = new Map<string, SheetSurfaces>()
 
@@ -240,12 +250,16 @@ const elevatedSurfaces = elevatedRungs()
 
 for (const file of packageStylesheets()) {
   const rules = parseRules(readFileSync(file, 'utf8'))
-  const surfaces: SheetSurfaces = { elevated: new Set(), scrolls: false, rebinds: false }
+  const surfaces: SheetSurfaces = { elevated: new Set(), scrolls: false, rebindsElevation: false }
   for (const rule of rules) {
     let rebinds = false
+    let rebindsElevation = false
     const ruleSurfaces: string[] = []
     for (const [property, value] of rule.declarations) {
-      if (property.startsWith(INDIRECTION_PREFIX) && file !== fileURLToPath(new URL('scrollbar.css', STYLES))) rebinds = true
+      if (property.startsWith(INDIRECTION_PREFIX) && file !== fileURLToPath(new URL('scrollbar.css', STYLES))) {
+        rebinds = true
+        if (value !== HIDDEN_THUMB) rebindsElevation = true
+      }
       if (OVERFLOW_PROPERTIES.includes(property) && /\b(?:auto|scroll)\b/.test(value)) surfaces.scrolls = true
       if (SURFACE_PROPERTIES.includes(property)) ruleSurfaces.push(...varReferences(value))
       for (const token of varReferences(value)) {
@@ -256,10 +270,8 @@ for (const file of packageStylesheets()) {
     for (const token of ruleSurfaces) {
       if (elevatedSurfaces.has(token)) surfaces.elevated.add(token)
     }
-    if (rebinds) {
-      rebindRules.push({ file, rule })
-      surfaces.rebinds = true
-    }
+    if (rebinds) rebindRules.push({ file, rule })
+    if (rebindsElevation) surfaces.rebindsElevation = true
   }
   sheetSurfaces.set(file, surfaces)
 }
@@ -454,21 +466,25 @@ describe('elevated surface rebinds', () => {
     }
   })
 
-  it('every rebind targets the l2 elevation pair or hides the bar outright', () => {
-    // Two targets, and nothing else. An elevated surface moves the pair to l2;
-    // a surface that draws no bar at all states `transparent` (ui-sidebar's
-    // column, whose scrollbars follow the pointer). What this rejects is a
-    // rebind to l1, which restates the base-surface default under a name that
-    // reads as an elevation, and a literal colour, which leaves the palette.
+  it('rebinds the pair to one target: the l2 elevation pair, or transparent', () => {
+    // The rule as a whole, not each declaration on its own. Per-declaration
+    // checking accepts a MIXED rule — `thumb: transparent` beside
+    // `thumb-hover: var(--dsw-alias-scrollbar-hover-l2)` — which repaints the
+    // bar the moment the pointer reaches it while passing a gate that claims
+    // the two targets are exclusive.
+    //
+    // The elevation half compares the whole value against the pair's canonical
+    // spelling rather than checking that every token it mentions ends in `-l2`.
+    // A shape check admits `color-mix(…, var(--dsw-alias-scrollbar-bg-l2) 85%,
+    // white)` and a crossed pair (the hover token bound to the resting
+    // property); neither is what the contract says.
     for (const { file, rule } of rebindRules) {
-      for (const [property, value] of rule.declarations) {
-        if (!property.startsWith(INDIRECTION_PREFIX)) continue
-        if (value === HIDDEN_THUMB) continue
-        const tokens = varReferences(value)
-        expect(tokens, `${file}: ${property}: ${value}`).not.toEqual([])
-        for (const token of tokens) {
-          expect(token, `${file}: ${property}`).toMatch(/-l2$/)
-        }
+      const rebinds = rule.declarations.filter(([property]) => property.startsWith(INDIRECTION_PREFIX))
+      const where = `${file} ${rule.selectors.join(', ')}`
+      if (rebinds.every(([, value]) => value === HIDDEN_THUMB)) continue
+      expect(rebinds.some(([, value]) => value === HIDDEN_THUMB), `${where}: mixes ${HIDDEN_THUMB} with an elevation`).toBe(false)
+      for (const [property, value] of rebinds) {
+        expect(value, `${where}: ${property}`).toBe(ELEVATED_REBIND.get(property))
       }
     }
   })
@@ -509,7 +525,7 @@ describe('elevated surface rebinds', () => {
     // (ChatView's `.toBottom`, CodeBlock's banner). Geometry cannot make that
     // call — a floating button carries a radius, a shadow, and a fixed size.
     for (const [file, surfaces] of sheetSurfaces) {
-      if (!surfaces.scrolls || surfaces.rebinds) continue
+      if (!surfaces.scrolls || surfaces.rebindsElevation) continue
       expect([...surfaces.elevated], `${file} scrolls on an elevated surface without rebinding`).toEqual([])
     }
   })