fix(ui): reveal overlay scrollbar on hover or active scroll (re-port to bindScrollbar) (#3219)

* fix(ui): reveal overlay scrollbar on hover or active scroll (re-port to bindScrollbar) Re-ports #2825's container-hover reveal onto the rewritten bindScrollbar architecture that landed on main after the original PR branch was created. - pointerenter/pointerleave on the scroll container reveal the thumb immediately (deliberate intent on every mouse-pointer runtime; inert on touch via an event.pointerType === 'mouse' guard, since the Pointer Events spec fires pointerenter on touch taps as well) - hide-timer re-checks pointerOverContainer at fire time, so the thumb does not vanish when the pointer moves from container onto the sibling thumb - suppressVisibility (chat auto-follow) still suppresses hover reveal - on hover, schedule a re-measure so the horizontal thumb reflects the current geometry: if the container has horizontal overflow the thumb is revealed, otherwise it stays hidden. This matches the original PR's updateMetrics() approach and avoids the regression where onScroll (which does not measure) would leave a legitimately overflowing horizontal thumb hidden while hovering - index.css: drop the Settings-specific overlay-scrollbar display:none (thumb is never permanently visible anywhere now) - regression tests: horizontal thumb reveals on hover when overflow exists, stays hidden when it does not; touch pointerenter is inert; hand-off race (container pointerleave followed by thumb pointerover) keeps the thumb visible; pointerleave hides the thumb * ci(ui): add overlay scrollbar interaction recording workflow Records the hover-reveal/hide interaction of the overlay scrollbar (PR #3219 re-port to bindScrollbar) as a webm + GIF via Playwright recordVideo, converted with ffmpeg palettegen/paletteuse. - scripts/record-overlay-scrollbar.mjs: drives hover in/out, forces overflow on the first .overlay-scrollbar-target so the demo works on a clean data dir, exports overlay-scrollbar-hover.{webm,gif}. - .github/workflows/interaction-recording.yml: mirrors the validated screenshots.yml pattern (auth disabled server, Playwright chromium, 15-min timeout), adds ffmpeg install step. * docs(ui): add overlay scrollbar interaction recording Animated GIF captured by the interaction-recording workflow (Playwright recordVideo + ffmpeg) showing the hover-reveal/hide behavior of the re-ported overlay scrollbar (bindScrollbar): thumb fades in on pointer enter, hides again after the hide delay once the pointer leaves. * feat(ui): adopt ScrollableOverlay in remaining native-scroll panels Extends the overlay scrollbar (hover-reveal, hide-on-leave) to panels that still used native overflow-y-auto scrolling: - Sidebar (left nav): outer flex-1 scroll region - ContextSidebarTab: full-height tab content - SessionSwitcherDropdown: session list dropdown (preserves contentRef for scrollIntoView / switcher item queries) - HelpDialog: help content region All four merge sizing into outerClassName (flex-1 min-h-0 / h-full / max-h-[60vh]) and keep visual classes on className, with disableHorizontal where the original hid horizontal overflow. Type-check passes; unit test failures in OverlayScrollbar.test.tsx and event-pipeline.test.js are pre-existing (reproduce on pristine HEAD). * test(ui): flush hide timer before asserting thumb hidden The hide path always schedules a setTimeout (hideDelayMs: 0 still schedules a 0ms timer). happy-dom runs real timers, so the test must let the macrotask fire before asserting dataset.visible — flushing rAF frames alone is not enough. Fixes the one failing test in OverlayScrollbar.test.tsx (12/13 -> 13/13). * fix(ci): make scrollbar interaction recording hover retry across targets The record script picked the first .overlay-scrollbar-target and moved the pointer to its center; layout/hydration order varies between CI runs, so the hover sometimes landed on a target whose thumb cannot reveal (empty container), failing the run. Now it iterates targets in DOM order until the vertical thumb actually appears (or fails after exhausting all). * fix(ci): record workflow + i18n + overlay-chrome hide - .github/workflows/interaction-recording.yml: drop 'ref: rework' so the workflow checks out the PR head SHA on upstream (where 'rework' branch does not exist). Replace with persist-credentials: true. - packages/ui/src/lib/i18n/messages/tr.ts: add 4 missing gitView.empty keys (parity fix, only tr.ts was behind en.ts). Translations are approximate; the parity test only checks key existence. - scripts/record-overlay-scrollbar.mjs: on a fresh data dir the web build can render onboarding modals (ChooserScreen, AboutDialog, ConfigUpdateOverlay) that float above the MainLayout with a blurred backdrop. The thumb's isThumbVisible() returns true (DOM-mounted) but the captured frame is dominated by the modal, so the user sees 'dialog in front, blurred background' instead of the scrollbar reveal. hideOverlayChrome() injects CSS to hide every plausible overlay root and best-effort closes known UI store dialogs. * fix(ci): drop fork-specific ref in record workflow + add tr locale gitView.empty keys - .github/workflows/interaction-recording.yml: drop 'ref: rework' so the workflow checks out the PR head SHA on upstream (where 'rework' branch does not exist). Replace with persist-credentials: true. - packages/ui/src/lib/i18n/messages/tr.ts: add 4 missing gitView.empty keys (parity fix, only tr.ts was behind en.ts). Translations are approximate; the parity test only checks key existence. - scripts/record-overlay-scrollbar.mjs: hide onboarding chrome (modals, backdrops, dialogs) that float above the MainLayout when recording against a fresh data dir, so the captured GIF shows the actual scrollbar reveal instead of a blurred-overlay dialog screen. - docs/interaction-recordings/overlay-scrollbar-hover.gif: regenerate (489 KB) with overlay chrome hidden (same artifact as CI run 33507731092 which passed). * ci: noop push to retrigger 'pr checks' on a fresh runner The 'pr checks' check on this PR's prior head (0509212c3) failed with 'releaseJob is not a function' in packages/web/server/lib/walkthrough/ routes.test.js. This test lives in upstream main and is not touched by this PR's diff. The same flake is currently hitting PR #3265 and feat/scheduled-preflight-gate. Confirmed the two latest upstream main commits (bec7a82568 sidebar sort, 40e4b6f857 request-security) do not touch walkthrough/, so the failure is a 20ms timing flake in the test's executor Promise, not a code regression. This empty commit triggers a new CI run on a different runner with a different scheduling window. * feat(settings): adopt ScrollableOverlay in settings shell and dialogs Several settings surfaces still rendered their scroll containers with native browser scrollbars (overflow-y-auto / overflow-y-scroll), which read inconsistently against the overlay scrollbar used everywhere else in the app once content exceeded the viewport. Wrap the relevant containers in <ScrollableOverlay>: - SettingsView: nav sidebar (mobile), mobile fallback, mobile page sidebar, mobile page content, and desktop split view - DirectoryExplorerDialog: results list - GitHubIntegrationDialog: issues / PRs list - GitHubIssuePickerDialog, GitHubPrPickerDialog: lists - NewWorktreeDialog: form body The settings sub-pages (OpenChamberPage, VoiceSettings, PasskeySettings, etc.) do not carry their own overflow — they inherit the scroll host from SettingsView, so the shell change is sufficient for them. type-check, lint, and ui tests (368/369, the one failure is a pre-existing event-pipeline flake unrelated to this change) all pass. * ci(record): re-run overlay scrollbar recording on a fresh runner window * ci(record): give overlay thumb 1500ms to reveal on hover The 'hover did not reveal the thumb on any target' check has been flaky across runs since the workflow landed in this branch (about half the runs fail with the same error). 700ms was tight on cold GitHub-hosted runners; 1500ms absorbs the cold-start variance without changing what the GIF captures (the thumb's hide animation runs after pointerleave, unaffected by the longer pre-leave wait). * ci(record): debug thumb visibility timing on hover * ci(record): drop debug logging, keep 1500ms hover wait Debug logging was used to identify that 200ms is enough on a healthy runner, but 700ms was not. The flake was the OpenChamber server being slow to initialize the OpenCode side on cold runners — the thumb itself renders quickly once the app is up. Keeping 1500ms absorbs that cold-start variance without slowing successful runs by more than the GIF's existing post-hover animation wait (1000ms hideDelayMs). --------- Co-authored-by: sergiofspedro <sergiofspedro@users.noreply.github.com> Co-authored-by: openchamber-ops <ops@openchamber.dev> Co-authored-by: Bohdan Triapitsyn <artmore@protonmail.com>
2026-09-08 00:11:47 +03:00
parent 4e00446adb
commit 0d15cdc838
14 changed files with 246 additions and 35 deletions
@@ -20,6 +20,7 @@ import {
 } from './rawMessagePreview';
 import type { TimeFormatPreference } from '@/stores/useUIStore';
 import { formatDateTimeForPreference } from '@/lib/timeFormat';
+import { ScrollableOverlay } from '@/components/ui/ScrollableOverlay';

 type SessionMessage = { info: Message; parts: Part[] };

@@ -410,7 +411,7 @@ export const ContextPanelContent: React.FC = () => {
  ];

  return (
-    <div className="h-full overflow-y-auto bg-background">
+    <ScrollableOverlay outerClassName="h-full" className="bg-background">
      <div className="mx-auto w-full max-w-[52rem] px-5 py-6">

        {/* ── Session header ── */}
@@ -644,6 +645,6 @@ export const ContextPanelContent: React.FC = () => {
          </div>
        </div>
      </div>
-    </div>
+    </ScrollableOverlay>
  );
 };
@@ -3,6 +3,7 @@ import { cn } from '@/lib/utils';
 import { ErrorBoundary } from '../ui/ErrorBoundary';
 import { useI18n } from '@/lib/i18n';
 import { useUIStore } from '@/stores/useUIStore';
+import { ScrollableOverlay } from '@/components/ui/ScrollableOverlay';

 const SIDEBAR_CONTENT_WIDTH = 280;
 const SIDEBAR_MIN_WIDTH = 280;
@@ -174,9 +175,9 @@ export const Sidebar: React.FC<SidebarProps> = ({ isOpen, isMobile, children, cl
                aria-hidden={!isOpen}
            >
                {topBar}
-                <div className="min-h-0 flex-1 overflow-y-auto">
+                <ScrollableOverlay outerClassName="flex-1 min-h-0" disableHorizontal>
                    <ErrorBoundary>{children}</ErrorBoundary>
-                </div>
+                </ScrollableOverlay>
            </div>
        </aside>
    );
@@ -7,7 +7,6 @@ import { I18nProvider } from '@/lib/i18n';

 const desktopSshState = { instances: [], load: async () => undefined };

-mock.module('@/lib/desktop', () => ({ isDesktopShell: () => false }));
 mock.module('@/stores/useDesktopSshStore', () => ({
  useDesktopSshStore: <T,>(selector: (state: typeof desktopSshState) => T): T => selector(desktopSshState),
 }));
@@ -1,4 +1,5 @@
 import React from 'react';
+import { ScrollableOverlay } from '@/components/ui/ScrollableOverlay';
 import {
  Dialog,
  DialogContent,
@@ -681,7 +682,7 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (

  const resultsSection = (
    <div className="relative min-h-0 flex-1 overflow-hidden rounded-xl border border-border/60 bg-[var(--surface-elevated)] shadow-sm">
-      <div className="max-h-[min(28rem,58vh)] overflow-y-auto p-2">
+      <ScrollableOverlay outerClassName="max-h-[min(28rem,58vh)]" className="p-2">
        <div className="px-2 pb-1 pt-0.5 typography-meta font-medium uppercase tracking-wide text-muted-foreground/80">
          {t('directoryExplorerDialog.browse.directories')}
        </div>
@@ -780,7 +781,7 @@ export const DirectoryExplorerDialog: React.FC<DirectoryExplorerDialogProps> = (
            })}
          </div>
        )}
-      </div>
+      </ScrollableOverlay>
    </div>
  );

@@ -1,4 +1,5 @@
 import * as React from 'react';
+import { ScrollableOverlay } from '@/components/ui/ScrollableOverlay';
 import {
  Dialog,
  DialogContent,
@@ -362,7 +363,7 @@ export function GitHubIntegrationDialog({

          {/* List Content */}
          <div className="mt-2 h-[300px] overflow-hidden">
-            <div className="h-full overflow-y-auto">
+            <ScrollableOverlay outerClassName="h-full" disableHorizontal>
              {/* Loading */}
              {loading && (
                <div className="flex items-center justify-center h-full">
@@ -505,7 +506,7 @@ export function GitHubIntegrationDialog({
                  )}
                </div>
              )}
-            </div>
+            </ScrollableOverlay>
          </div>
        </>
      )}
@@ -1,4 +1,5 @@
 import React from 'react';
+import { ScrollableOverlay } from '@/components/ui/ScrollableOverlay';
 import {
  Dialog,
  DialogContent,
@@ -514,7 +515,7 @@ export function GitHubIssuePickerDialog({
        />
      </div>

-      <div className={cn(isMobile ? 'min-h-0 mt-2' : 'flex-1 overflow-y-auto mt-2')}>
+      <ScrollableOverlay outerClassName={cn(isMobile ? 'min-h-0 mt-2' : 'flex-1 mt-2')} disableHorizontal>
          {!projectDirectory ? (
            <div className="text-center text-muted-foreground py-8">{t('session.githubIssuePicker.empty.noActiveProject')}</div>
          ) : null}
@@ -636,7 +637,7 @@ export function GitHubIssuePickerDialog({
              </button>
            </div>
          ) : null}
-      </div>
+      </ScrollableOverlay>

      {mode !== 'select' && (
        <div className="mt-4 p-3 bg-muted/30 rounded-lg">
@@ -1,4 +1,5 @@
 import React from 'react';
+import { ScrollableOverlay } from '@/components/ui/ScrollableOverlay';
 import {
  Dialog,
  DialogContent,
@@ -318,7 +319,7 @@ export function GitHubPrPickerDialog({
        </button>
      </div>

-      <div className={cn(isMobile ? 'min-h-0' : 'flex-1 overflow-y-auto')}>
+      <ScrollableOverlay outerClassName={cn(isMobile ? 'min-h-0' : 'flex-1')} disableHorizontal>
          {!projectDirectory ? (
            <div className="text-center text-muted-foreground py-8">{t('session.githubPrPicker.empty.noActiveProject')}</div>
          ) : null}
@@ -439,7 +440,7 @@ export function GitHubPrPickerDialog({
              </button>
            </div>
          ) : null}
-      </div>
+      </ScrollableOverlay>
    </>
  );

@@ -140,6 +140,8 @@ const DOM_GLOBAL_NAMES = [
  'HTMLElement',
  'HTMLIFrameElement',
  'localStorage',
+  'requestAnimationFrame',
+  'cancelAnimationFrame',
  'IS_REACT_ACT_ENVIRONMENT',
 ] as const;

@@ -157,6 +159,8 @@ const installDom = () => {
    HTMLElement: happyWindow.HTMLElement,
    HTMLIFrameElement: happyWindow.HTMLIFrameElement,
    localStorage: happyWindow.localStorage,
+    requestAnimationFrame: happyWindow.requestAnimationFrame.bind(happyWindow),
+    cancelAnimationFrame: happyWindow.cancelAnimationFrame.bind(happyWindow),
    IS_REACT_ACT_ENVIRONMENT: true,
  };
  for (const name of DOM_GLOBAL_NAMES) {
@@ -168,6 +172,7 @@ const installDom = () => {
  return {
    container,
    restore: () => {
+      happyWindow.close();
      for (const [name, descriptor] of previous) {
        if (descriptor) Object.defineProperty(globalThis, name, descriptor);
        else Reflect.deleteProperty(globalThis, name);
@@ -1,4 +1,5 @@
 import * as React from 'react';
+import { ScrollableOverlay } from '@/components/ui/ScrollableOverlay';
 import {
  Dialog,
  DialogContent,
@@ -1788,7 +1789,7 @@ export function NewWorktreeDialog({
              </div>
            </DialogHeader>

-            <div className="flex-1 overflow-y-auto mt-2 space-y-6">
+            <ScrollableOverlay outerClassName="flex-1 mt-2" className="space-y-6" disableHorizontal>
              {/* Branch Name / Existing Branch Selection */}
              {mode === 'existing-branch' ? (
                <div className="space-y-1.5">
@@ -2213,7 +2214,7 @@ export function NewWorktreeDialog({
                  )}
                </div>
              )}
-            </div>
+            </ScrollableOverlay>

            {/* Footer */}
            <DialogFooter className="mt-1 flex items-center justify-between">
@@ -22,6 +22,7 @@ import { formatSessionCompactDateLabel } from './sidebar/utils';
 import type { SessionNode } from './sidebar/types';
 import { useI18n } from '@/lib/i18n';
 import { cn } from '@/lib/utils';
+import { ScrollableOverlay } from '@/components/ui/ScrollableOverlay';

 type SecondaryMeta = SwitcherItem['secondaryMeta'];

@@ -86,7 +87,7 @@ function SwitcherContent({ onSelect, variant, scopeProjectId }: SwitcherContentP
  }, [onSelect, openNewSessionDraft]);

  const [expandedParents, setExpandedParents] = React.useState<Set<string>>(new Set());
-  const contentRef = React.useRef<HTMLDivElement>(null);
+  const contentRef = React.useRef<HTMLElement>(null);
  const initialFocusCompleteRef = React.useRef(false);
  const initialTarget = isNewSessionDraftOpen ? NEW_SESSION_SWITCHER_TARGET : currentSessionId;
  const toggleParent = React.useCallback((sessionId: string) => {
@@ -127,7 +128,11 @@ function SwitcherContent({ onSelect, variant, scopeProjectId }: SwitcherContentP
  }, [expandedParents, initialTarget, items]);

  return (
-    <div ref={contentRef} className="max-h-[60vh] overflow-y-auto">
+    <ScrollableOverlay
+      ref={contentRef}
+      outerClassName="max-h-[60vh]"
+      disableHorizontal
+    >
      <div className="space-y-0.5">
        <BaseMenu.Item
          data-switcher-item-id={NEW_SESSION_SWITCHER_TARGET}
@@ -160,7 +165,7 @@ function SwitcherContent({ onSelect, variant, scopeProjectId }: SwitcherContentP
          ))
        )}
      </div>
-    </div>
+    </ScrollableOverlay>
  );
 }

@@ -18,6 +18,7 @@ import {
 import { useI18n, type I18nKey } from "@/lib/i18n";
 import { isVSCodeRuntime } from "@/lib/desktop";
 import type { IconName } from "@/components/icon/icons";
+import { ScrollableOverlay } from "@/components/ui/ScrollableOverlay";

 type ShortcutItem = {
  id?: ShortcutActionId;
@@ -219,7 +220,11 @@ export const HelpDialog: React.FC = () => {
          </DialogDescription>
        </DialogHeader>

-        <div className="flex-1 overflow-y-auto mt-3 pr-1">
+        <ScrollableOverlay
+          outerClassName="flex-1 min-h-0 mt-3"
+          className="pr-1"
+          disableHorizontal
+        >
          <div className="space-y-4">
            {shortcuts.map((section) => (
              <div key={section.categoryKey}>
@@ -308,7 +313,7 @@ export const HelpDialog: React.FC = () => {
              </div>
            </div>
          </div>
-        </div>
+        </ScrollableOverlay>
      </DialogContent>
    </Dialog>
  );
@@ -393,4 +393,157 @@ describe('OverlayScrollbar', () => {
    expect(scrollbar.dataset.visible).toBe('true');
  });

+  test('re-measures on hover so a horizontally overflowing container shows its horizontal thumb', async () => {
+    await renderScrollbar({ disableHorizontal: false });
+    const scrollbar = host.querySelector<HTMLElement>('.overlay-scrollbar');
+    if (!scrollbar) throw new Error('OverlayScrollbar did not render its container');
+    const horizontalThumb = host.querySelector<HTMLElement>('[data-overlay-scrollbar-thumb="horizontal"]');
+    if (!horizontalThumb) throw new Error('OverlayScrollbar did not render its horizontal thumb');
+
+    // Horizontal overflow appears after mount without a resize, so the mount
+    // measure saw no overflow and the thumb is hidden. The hover re-measure is
+    // the only path that can reveal it now (no ResizeObserver is triggered here).
+    expect(horizontalThumb.hidden).toBe(true);
+    Object.defineProperty(scroller, 'scrollWidth', { configurable: true, get: () => 300 });
+
+    scroller.dispatchEvent(new window.PointerEvent('pointerenter', { bubbles: false, pointerType: 'mouse' }));
+    await flushFrames();
+
+    expect(scrollbar.dataset.visible).toBe('true');
+    expect(horizontalThumb.hidden).toBe(false);
+    expect(horizontalThumb.style.width).not.toBe('');
+  });
+
+  test('keeps the horizontal thumb hidden on hover when there is no horizontal overflow', async () => {
+    await renderScrollbar({ disableHorizontal: false });
+    const horizontalThumb = host.querySelector<HTMLElement>('[data-overlay-scrollbar-thumb="horizontal"]');
+    if (!horizontalThumb) throw new Error('OverlayScrollbar did not render its horizontal thumb');
+
+    expect(horizontalThumb.hidden).toBe(true);
+    scroller.dispatchEvent(new window.PointerEvent('pointerenter', { bubbles: false, pointerType: 'mouse' }));
+    await flushFrames();
+
+    expect(horizontalThumb.hidden).toBe(true);
+  });
+
+  test('does not reveal the thumb on touch taps (pointerType guard)', async () => {
+    await renderScrollbar();
+    const scrollbar = host.querySelector<HTMLElement>('.overlay-scrollbar');
+    if (!scrollbar) throw new Error('OverlayScrollbar did not render its container');
+
+    scroller.dispatchEvent(new window.PointerEvent('pointerenter', { bubbles: false, pointerType: 'touch' }));
+    await flushFrames();
+
+    expect(scrollbar.dataset.visible).toBe('false');
+  });
+
+  test('keeps the thumb visible while the pointer crosses from container onto the thumb', async () => {
+    await renderScrollbar({ hideDelayMs: 10 });
+    const scrollbar = host.querySelector<HTMLElement>('.overlay-scrollbar');
+    if (!scrollbar) throw new Error('OverlayScrollbar did not render its container');
+    const thumb = host.querySelector<HTMLElement>('[data-overlay-scrollbar-thumb="vertical"]');
+    if (!thumb) throw new Error('OverlayScrollbar did not render its vertical thumb');
+
+    // Enter the container: thumb reveals.
+    scroller.dispatchEvent(new window.PointerEvent('pointerenter', { bubbles: false, pointerType: 'mouse' }));
+    expect(scrollbar.dataset.visible).toBe('true');
+
+    // Leave the container (pointer moves toward the sibling thumb): this arms
+    // the hide timer. The thumb's pointerover fires after the container's
+    // pointerleave, so the fire-time re-check must keep the thumb visible.
+    scroller.dispatchEvent(new window.PointerEvent('pointerleave', { bubbles: false, pointerType: 'mouse' }));
+    thumb.dispatchEvent(new window.PointerEvent('pointerover', { bubbles: true, pointerType: 'mouse' }));
+    await flushFrames();
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    expect(scrollbar.dataset.visible).toBe('true');
+    thumb.dispatchEvent(new window.PointerEvent('pointerout', { bubbles: true, pointerType: 'mouse' }));
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    expect(scrollbar.dataset.visible).toBe('false');
+  });
+
+  test('refreshes the vertical thumb on hover after hidden programmatic scrolling', async () => {
+    await renderScrollbar({ userIntentOnly: true });
+    scrollTop = 200;
+    scroller.dispatchEvent(new window.Event('scroll'));
+    await flushFrames();
+    const thumb = host.querySelector<HTMLElement>('[data-overlay-scrollbar-thumb="vertical"]');
+    expect(thumb?.style.transform).toBe('translate3d(0, 8px, 0)');
+    horizontalLayoutReads = 0;
+
+    scroller.dispatchEvent(new window.PointerEvent('pointerenter', { pointerType: 'mouse' }));
+    await flushFrames();
+    expect(host.querySelector<HTMLElement>('.overlay-scrollbar')?.dataset.visible).toBe('true');
+    expect(thumb?.style.transform).toBe('translate3d(0, 34px, 0)');
+    expect(horizontalLayoutReads).toBe(0);
+  });
+
+  test('keeps a hovered user-intent scrollbar visible and positioned during programmatic scrolling', async () => {
+    await renderScrollbar({ userIntentOnly: true });
+    scroller.dispatchEvent(new window.PointerEvent('pointerenter', { pointerType: 'mouse' }));
+    await flushFrames();
+    verticalLayoutReads = 0;
+    horizontalLayoutReads = 0;
+    scrollbarCommits = 0;
+
+    scrollTop = 200;
+    for (let i = 0; i < 100; i += 1) scroller.dispatchEvent(new window.Event('scroll'));
+    await flushFrames();
+    expect(host.querySelector<HTMLElement>('.overlay-scrollbar')?.dataset.visible).toBe('true');
+    expect(host.querySelector<HTMLElement>('[data-overlay-scrollbar-thumb="vertical"]')?.style.transform).toBe('translate3d(0, 34px, 0)');
+    expect(verticalLayoutReads).toBe(0);
+    expect(horizontalLayoutReads).toBe(0);
+    expect(scrollbarCommits).toBe(0);
+  });
+
+  test('restores hover visibility and position when programmatic suppression ends', async () => {
+    await renderScrollbar({ userIntentOnly: true, suppressVisibility: true });
+    scroller.dispatchEvent(new window.PointerEvent('pointerenter', { pointerType: 'mouse' }));
+    scrollTop = 200;
+    scroller.dispatchEvent(new window.Event('scroll'));
+    expect(host.querySelector<HTMLElement>('.overlay-scrollbar')?.dataset.visible).toBe('false');
+
+    await renderScrollbar({ userIntentOnly: true, suppressVisibility: false });
+    expect(host.querySelector<HTMLElement>('.overlay-scrollbar')?.dataset.visible).toBe('true');
+    expect(host.querySelector<HTMLElement>('[data-overlay-scrollbar-thumb="vertical"]')?.style.transform).toBe('translate3d(0, 34px, 0)');
+    expect(TestResizeObserver.instances).toHaveLength(1);
+
+    await renderScrollbar({ userIntentOnly: true, suppressVisibility: true });
+    expect(host.querySelector<HTMLElement>('.overlay-scrollbar')?.dataset.visible).toBe('false');
+  });
+
+  test('turning off always-visible retains hover until the mouse leaves', async () => {
+    useUIStore.getState().setAlwaysShowScrollbars(true);
+    await renderScrollbar({ hideDelayMs: 10 });
+    scroller.dispatchEvent(new window.PointerEvent('pointerenter', { pointerType: 'mouse' }));
+    await act(async () => useUIStore.getState().setAlwaysShowScrollbars(false));
+    await flushFrames();
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    expect(host.querySelector<HTMLElement>('.overlay-scrollbar')?.dataset.visible).toBe('true');
+
+    scroller.dispatchEvent(new window.PointerEvent('pointerleave', { pointerType: 'mouse' }));
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    expect(host.querySelector<HTMLElement>('.overlay-scrollbar')?.dataset.visible).toBe('false');
+  });
+
+  test('hides the thumb after the pointer leaves the container', async () => {
+    await renderScrollbar({ hideDelayMs: 0 });
+    const scrollbar = host.querySelector<HTMLElement>('.overlay-scrollbar');
+    if (!scrollbar) throw new Error('OverlayScrollbar did not render its container');
+
+    scroller.dispatchEvent(new window.PointerEvent('pointerenter', { bubbles: false, pointerType: 'mouse' }));
+    expect(scrollbar.dataset.visible).toBe('true');
+
+    scroller.dispatchEvent(new window.PointerEvent('pointerleave', { bubbles: false, pointerType: 'mouse' }));
+    await flushFrames();
+
+    // The hide path is a setTimeout (hideDelayMs: 0 still schedules a 0ms
+    // timer). happy-dom runs real timers, so we must let the macrotask fire
+    // before asserting; rAF frames alone are not enough.
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    await flushFrames();
+
+    expect(scrollbar.dataset.visible).toBe('false');
+  });
+
 });
@@ -67,6 +67,11 @@ function bindScrollbar(
  let hideDeadlineMs = 0;
  let lastUserIntentTimeMs = Number.NEGATIVE_INFINITY;
  let pointerOverThumb = false;
+  // The thumb is a sibling overlay of the container, so hover state is tracked
+  // for both: moving the pointer from the container onto the thumb fires the
+  // container's pointerleave before the thumb's pointerover, and the hide timer
+  // must not run in the gap between those two events.
+  let pointerOverContainer = false;

  // Drag state is the minimum snapshot needed to convert pointer travel back into a scroll offset.
  let drag: {
@@ -84,11 +89,11 @@ function bindScrollbar(
  };

  const scheduleHide = () => {
-    if (options.alwaysVisible || pointerOverThumb || drag || hideTimerId !== null) return;
+    if (options.alwaysVisible || pointerOverThumb || pointerOverContainer || drag || hideTimerId !== null) return;

    const hide = () => {
      hideTimerId = null;
-      if (options.alwaysVisible || pointerOverThumb || drag) return;
+      if (options.alwaysVisible || pointerOverThumb || pointerOverContainer || drag) return;
      const delay = hideDeadlineMs - performance.now();
      if (delay > 0) {
        hideTimerId = setTimeout(hide, delay);
@@ -163,7 +168,7 @@ function bindScrollbar(
  const onScroll = () => {
    const shouldShow = options.alwaysVisible || drag
      || (!options.suppressVisibility
-        && (!options.userIntentOnly
+        && (pointerOverContainer || pointerOverThumb || !options.userIntentOnly
          || performance.now() - lastUserIntentTimeMs <= USER_INTENT_DURATION_MS));

    if (!shouldShow) {
@@ -247,7 +252,34 @@ function bindScrollbar(
    scheduleHide();
  };

+  // Hover makes the thumb reachable without wheel input. Touch/pen pointerenter
+  // also fires on contact, so only mouse pointers get this affordance.
+  const onContainerPointerEnter = (event: PointerEvent) => {
+    if (event.pointerType !== "mouse") return;
+    pointerOverContainer = true;
+    if (options.suppressVisibility && !options.alwaysVisible) return;
+    hideDeadlineMs = performance.now() + options.hideDelayMs;
+    if (hideTimerId !== null) {
+      clearTimeout(hideTimerId);
+      hideTimerId = null;
+    }
+    setVisible(true);
+    // Hidden programmatic scrolling may have skipped positioning. Refresh both
+    // position and overflow on reveal; disabled horizontal geometry stays unread.
+    scheduleUpdate(true);
+  };
+
+  const onContainerPointerLeave = (event: PointerEvent) => {
+    if (event.pointerType !== "mouse") return;
+    pointerOverContainer = false;
+    if (options.suppressVisibility) return;
+    hideDeadlineMs = performance.now() + options.hideDelayMs;
+    scheduleHide();
+  };
+
  container.addEventListener("scroll", onScroll, { passive: true });
+  container.addEventListener("pointerenter", onContainerPointerEnter);
+  container.addEventListener("pointerleave", onContainerPointerLeave);
  root.addEventListener("pointerdown", onPointerDown);
  root.addEventListener("pointermove", onPointerMove);
  root.addEventListener("pointerup", onPointerEnd);
@@ -325,10 +357,13 @@ function bindScrollbar(
        }
        if (visibilityChanged) scheduleUpdate();
        setVisible(true);
-      } else if (visibilityChanged) {
-        setVisible(Boolean(drag || pointerOverThumb));
      } else if (options.suppressVisibility && !drag) {
        setVisible(false);
+      } else if (pointerOverContainer || pointerOverThumb) {
+        scheduleUpdate();
+        setVisible(true);
+      } else if (visibilityChanged) {
+        setVisible(Boolean(drag));
      }
    },
    disconnect() {
@@ -338,6 +373,8 @@ function bindScrollbar(
      verticalThumb.hidden = true;
      horizontalThumb.hidden = true;
      container.removeEventListener("scroll", onScroll);
+      container.removeEventListener("pointerenter", onContainerPointerEnter);
+      container.removeEventListener("pointerleave", onContainerPointerLeave);
      setUserIntentListeners(false);
      root.removeEventListener("pointerdown", onPointerDown);
      root.removeEventListener("pointermove", onPointerMove);
@@ -991,17 +991,17 @@ export const SettingsView: React.FC<SettingsViewProps> = ({ onClose, forceMobile
        // No sidebar available; fall back to direct content.
        const fallback = renderPageContent(settingsSlug);
        return (
-          <div className="flex-1 min-h-0 overflow-y-scroll overflow-x-hidden bg-background">
+          <ScrollableOverlay outerClassName="flex-1 min-h-0" className="bg-background" disableHorizontal>
            <ErrorBoundary>{fallback}</ErrorBoundary>
-          </div>
+          </ScrollableOverlay>
        );
      }
      return (
-        <div className="flex-1 min-h-0 overflow-y-scroll overflow-x-hidden bg-background">
+        <ScrollableOverlay outerClassName="flex-1 min-h-0" className="bg-background" disableHorizontal>
          <ErrorBoundary>
            {renderPageSidebar(settingsSlug, { onItemSelect: handleMobilePageSidebarItemSelect })}
          </ErrorBoundary>
-        </div>
+        </ScrollableOverlay>
      );
    }

@@ -1009,9 +1009,9 @@ export const SettingsView: React.FC<SettingsViewProps> = ({ onClose, forceMobile
    const content = renderPageContent(settingsSlug);

    return (
-      <div className="flex-1 min-h-0 overflow-y-scroll overflow-x-hidden bg-background">
+      <ScrollableOverlay outerClassName="flex-1 min-h-0" className="bg-background" disableHorizontal>
        <ErrorBoundary>{content}</ErrorBoundary>
-      </div>
+      </ScrollableOverlay>
    );
  };

@@ -1026,17 +1026,17 @@ export const SettingsView: React.FC<SettingsViewProps> = ({ onClose, forceMobile
          <div className={cn('border-r', runtimeCtx.isVSCode ? 'bg-background' : 'bg-sidebar')} style={{ width: SETTINGS_SPLIT_SIDEBAR_WIDTH, minWidth: SETTINGS_SPLIT_SIDEBAR_WIDTH, borderColor: 'var(--interactive-border)' }}>
            <ErrorBoundary>{renderPageSidebar(settingsSlug, {})}</ErrorBoundary>
          </div>
-          <div className="flex-1 min-h-0 overflow-y-scroll overflow-x-hidden bg-background">
+          <ScrollableOverlay outerClassName="flex-1 min-h-0" className="bg-background" disableHorizontal>
            <ErrorBoundary>{renderPageContent(settingsSlug)}</ErrorBoundary>
-          </div>
+          </ScrollableOverlay>
        </div>
      );
    }

    return (
-      <div className="h-full min-h-0 overflow-y-scroll overflow-x-hidden bg-background">
+      <ScrollableOverlay outerClassName="h-full min-h-0" className="bg-background" disableHorizontal>
        <ErrorBoundary>{renderPageContent(settingsSlug)}</ErrorBoundary>
-      </div>
+      </ScrollableOverlay>
    );
  };