From efb87b6aa7d338cd02bebe3634c0443d2312f374 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=97=B0=EC=9A=B0?= <yeonu@eunyeon.com>
Date: Sun, 8 Nov 2026 01:39:24 +0900
Subject: [PATCH 1/4] =?UTF-8?q?feat:=20=EC=98=A4=EB=B2=84=EB=A0=88?=
 =?UTF-8?q?=EC=9D=B4=20=EC=8A=A4=ED=81=AC=EB=A1=A4=20=EB=A7=89=EB=8C=80=20?=
 =?UTF-8?q?=EC=BB=B4=ED=8F=AC=EB=84=8C=ED=8A=B8=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../overlayScrollbar/OverlayScrollbar.tsx     |  67 +++
 .../overlayScrollbarController.test.ts        | 356 ++++++++++++
 .../overlayScrollbarController.ts             | 519 ++++++++++++++++++
 .../overlayScrollbarModel.test.ts             | 241 ++++++++
 .../overlayScrollbar/overlayScrollbarModel.ts | 131 +++++
 src/renderer/hooks/useLenis.ts                |  54 ++
 6 files changed, 1368 insertions(+)
 create mode 100644 src/renderer/components/main/common/overlayScrollbar/OverlayScrollbar.tsx
 create mode 100644 src/renderer/components/main/common/overlayScrollbar/overlayScrollbarController.test.ts
 create mode 100644 src/renderer/components/main/common/overlayScrollbar/overlayScrollbarController.ts
 create mode 100644 src/renderer/components/main/common/overlayScrollbar/overlayScrollbarModel.test.ts
 create mode 100644 src/renderer/components/main/common/overlayScrollbar/overlayScrollbarModel.ts

diff --git a/src/renderer/components/main/common/overlayScrollbar/OverlayScrollbar.tsx b/src/renderer/components/main/common/overlayScrollbar/OverlayScrollbar.tsx
new file mode 100644
index 000000000..7356fd733
--- /dev/null
+++ b/src/renderer/components/main/common/overlayScrollbar/OverlayScrollbar.tsx
@@ -0,0 +1,67 @@
+import { useEffect, useRef } from 'react';
+
+import { usePanelHost } from '@contexts/PanelHostContext';
+
+import {
+  createOverlayScrollbarController,
+  type OverlayScrollbarController,
+  type OverlayScrollbarPlacement,
+} from './overlayScrollbarController';
+
+interface OverlayScrollbarProps {
+  /** 끌어 정렬처럼 뷰포트 위 히트 판정이 필요한 동안 막대 입력을 끈다 */
+  inert?: boolean;
+  /** 레일 왼쪽 위치(뷰포트 기준 px). edge 배치에서만 쓴다 */
+  railLeft?: number;
+  /** edge는 뷰포트 오른쪽 끝 안쪽, outside는 부모 상자 바깥 오른쪽 여백 */
+  placement?: OverlayScrollbarPlacement;
+  className?: string;
+}
+
+/**
+ * 오버레이 스크롤 막대. 스크롤 뷰포트와 같은 부모(위치 지정 요소) 안 마지막 자식으로 둔다.
+ * 네이티브 막대는 전역에서 숨긴 채, 스크롤할 때와 가장자리에 포인터가 닿을 때만 드러난다.
+ * 레일 자리(오른쪽 띠)에는 버튼이 없어야 한다 - 쓰는 쪽 레이아웃이 그 띠를 비워 둔다
+ */
+const OverlayScrollbar = ({
+  inert = false,
+  railLeft,
+  placement = 'edge',
+  className,
+}: OverlayScrollbarProps) => {
+  // 분리 패널로 옮겨지면 그 창 기준으로 관찰자를 다시 만든다
+  const { window: ownerWindow } = usePanelHost();
+  const railRef = useRef<HTMLDivElement>(null);
+  const thumbRef = useRef<HTMLDivElement>(null);
+  const controllerRef = useRef<OverlayScrollbarController | null>(null);
+
+  useEffect(() => {
+    const rail = railRef.current;
+    const thumb = thumbRef.current;
+    if (!rail || !thumb) return undefined;
+    const view = (rail.ownerDocument.defaultView ?? ownerWindow) as Window &
+      typeof globalThis;
+    const controller = createOverlayScrollbarController(rail, thumb, view);
+    controllerRef.current = controller;
+    return () => {
+      controller.destroy();
+      controllerRef.current = null;
+    };
+  }, [ownerWindow]);
+
+  useEffect(() => {
+    controllerRef.current?.setOptions({ inert, railLeft, placement });
+  }, [inert, railLeft, placement, ownerWindow]);
+
+  return (
+    <div
+      ref={railRef}
+      aria-hidden="true"
+      className={className ? `dmn-scrollbar ${className}` : 'dmn-scrollbar'}
+    >
+      <div ref={thumbRef} className="dmn-scrollbar-thumb" />
+    </div>
+  );
+};
+
+export default OverlayScrollbar;
diff --git a/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarController.test.ts b/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarController.test.ts
new file mode 100644
index 000000000..f0714ff87
--- /dev/null
+++ b/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarController.test.ts
@@ -0,0 +1,356 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createOverlayScrollbarController } from './overlayScrollbarController';
+
+const lenisMocks = vi.hoisted(() => ({
+  scrollLenisTo: vi.fn(),
+  getWrapperLenis: vi.fn(() => undefined),
+  forwardWheelToLenis: vi.fn(() => true),
+}));
+
+vi.mock('@hooks/useLenis', () => lenisMocks);
+vi.mock('@utils/core/platform', () => ({ isMac: () => false }));
+
+// jsdom에는 레이아웃이 없어 박스 값을 직접 심는다
+const setBox = (element: HTMLElement, box: Record<string, unknown>) => {
+  Object.entries(box).forEach(([key, value]) => {
+    Object.defineProperty(element, key, { configurable: true, value });
+  });
+};
+
+const pointer = (type: string, init: Record<string, unknown> = {}) => {
+  const event = new MouseEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    button: 0,
+    ...init,
+  });
+  Object.defineProperties(event, {
+    pointerId: { value: 1 },
+    pointerType: { value: 'mouse' },
+  });
+  return event;
+};
+
+class ResizeObserverStub {
+  static instances: ResizeObserverStub[] = [];
+  constructor(public callback: () => void) {
+    ResizeObserverStub.instances.push(this);
+  }
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+describe('createOverlayScrollbarController', () => {
+  let host: HTMLDivElement;
+  let rail: HTMLDivElement;
+  let thumb: HTMLDivElement;
+  let view: Window & typeof globalThis;
+
+  const addViewport = (box: Record<string, unknown>) => {
+    const viewport = document.createElement('div');
+    viewport.style.overflowY = 'auto';
+    viewport.append(document.createElement('div'));
+    setBox(viewport, {
+      clientWidth: 240,
+      clientTop: 0,
+      clientLeft: 0,
+      offsetTop: 0,
+      offsetLeft: 0,
+      offsetParent: host,
+      ...box,
+    });
+    host.insertBefore(viewport, rail);
+    return viewport;
+  };
+
+  const create = () => createOverlayScrollbarController(rail, thumb, view);
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    Object.values(lenisMocks).forEach((mock) => mock.mockClear());
+    // 실패한 테스트가 바꾼 반환값이 다음 테스트로 새지 않게
+    lenisMocks.getWrapperLenis.mockReturnValue(undefined);
+    lenisMocks.forwardWheelToLenis.mockReturnValue(true);
+    ResizeObserverStub.instances = [];
+    view = Object.assign(Object.create(window), {
+      ResizeObserver: ResizeObserverStub,
+      MutationObserver: window.MutationObserver,
+      getComputedStyle: window.getComputedStyle.bind(window),
+      setTimeout: window.setTimeout.bind(window),
+      clearTimeout: window.clearTimeout.bind(window),
+    });
+    host = document.createElement('div');
+    host.style.position = 'relative';
+    rail = document.createElement('div');
+    thumb = document.createElement('div');
+    rail.append(thumb);
+    host.append(rail);
+    document.body.append(host);
+    setBox(rail, { offsetWidth: 10, offsetHeight: 400 });
+    rail.getBoundingClientRect = () =>
+      ({
+        top: 0,
+        bottom: 400,
+        left: 230,
+        right: 240,
+        height: 400,
+        width: 10,
+      } as DOMRect);
+    const captured = new Set<number>();
+    HTMLElement.prototype.setPointerCapture = (id: number) => {
+      captured.add(id);
+    };
+    HTMLElement.prototype.releasePointerCapture = (id: number) => {
+      captured.delete(id);
+    };
+    HTMLElement.prototype.hasPointerCapture = (id: number) => captured.has(id);
+  });
+
+  afterEach(() => {
+    host.remove();
+    vi.useRealTimers();
+  });
+
+  it('열릴 때는 숨은 채로 두고, 스크롤하면 얇게 드러났다가 대기 시간 뒤 숨는다', () => {
+    const viewport = addViewport({ clientHeight: 400, scrollHeight: 1600 });
+    const controller = create();
+    expect(rail.dataset.state).toBe('hidden');
+    viewport.scrollTop = 40;
+    viewport.dispatchEvent(new Event('scroll'));
+    expect(rail.dataset.state).toBe('thin');
+    vi.advanceTimersByTime(899);
+    expect(rail.dataset.state).toBe('thin');
+    vi.advanceTimersByTime(1);
+    expect(rail.dataset.state).toBe('hidden');
+    controller.destroy();
+  });
+
+  it('넘치지 않으면 none', () => {
+    addViewport({ clientHeight: 400, scrollHeight: 400 });
+    const controller = create();
+    expect(rail.dataset.state).toBe('none');
+    controller.destroy();
+  });
+
+  it('숨은 keepalive 뷰포트는 건너뛰고 보이는 쪽에 맞춘다', () => {
+    addViewport({ clientHeight: 0, scrollHeight: 0 });
+    addViewport({ clientHeight: 400, scrollHeight: 1600, offsetTop: 20 });
+    const controller = create();
+    // 트랙 392(400 - 여백 4×2) × 보이는 비율 1/4
+    expect(thumb.style.height).toBe('98px');
+    expect(rail.style.top).toBe('20px');
+    expect(rail.style.left).toBe('230px');
+    expect(rail.style.height).toBe('400px');
+    controller.destroy();
+  });
+
+  it('railLeft를 주면 뷰포트 기준 그 위치에 레일을 둔다', () => {
+    addViewport({ clientHeight: 400, scrollHeight: 1600, offsetLeft: 8 });
+    const controller = create();
+    controller.setOptions({ inert: false, railLeft: 100, placement: 'edge' });
+    expect(rail.style.left).toBe('108px');
+    controller.destroy();
+  });
+
+  it('스크롤하면 썸이 따라가고 다시 드러난다', () => {
+    const viewport = addViewport({ clientHeight: 400, scrollHeight: 1600 });
+    const controller = create();
+    vi.advanceTimersByTime(900);
+    expect(rail.dataset.state).toBe('hidden');
+
+    viewport.scrollTop = 600;
+    viewport.dispatchEvent(new Event('scroll'));
+    // 여백 4 + 진행 1/2 × 이동 거리 294
+    expect(thumb.style.transform).toBe('translate3d(0, 151px, 0)');
+    expect(rail.dataset.state).toBe('thin');
+    controller.destroy();
+  });
+
+  it('가장자리 띠에 포인터가 닿으면 숨어 있어도 굵게 드러나고, 떠나면 얇게 남았다가 숨는다', () => {
+    addViewport({ clientHeight: 400, scrollHeight: 1600 });
+    const controller = create();
+    expect(rail.dataset.state).toBe('hidden');
+    rail.dispatchEvent(pointer('pointerenter'));
+    expect(rail.dataset.state).toBe('expanded');
+    vi.advanceTimersByTime(2000);
+    expect(rail.dataset.state).toBe('expanded');
+    rail.dispatchEvent(pointer('pointerleave'));
+    expect(rail.dataset.state).toBe('thin');
+    vi.advanceTimersByTime(900);
+    expect(rail.dataset.state).toBe('hidden');
+    controller.destroy();
+  });
+
+  it('outside 배치는 부모 상자 바깥 오른쪽에 부모 높이만큼 붙는다', () => {
+    addViewport({
+      clientHeight: 392,
+      scrollHeight: 1568,
+      offsetTop: 4,
+      offsetLeft: 4,
+    });
+    setBox(host, { clientWidth: 216, clientHeight: 400 });
+    const controller = create();
+    controller.setOptions({
+      inert: false,
+      railLeft: undefined,
+      placement: 'outside',
+    });
+    expect(rail.style.left).toBe('216px');
+    expect(rail.style.top).toBe('0px');
+    expect(rail.style.height).toBe('400px');
+    // 트랙은 부모 높이에서 여백 4×2를 뺀 392, 보이는 비율 1/4
+    expect(thumb.style.height).toBe('98px');
+    controller.destroy();
+  });
+
+  it('깊은 자손만 커졌으면 휠을 Lenis보다 먼저 받아 한도를 다시 재게 한다', () => {
+    const viewport = addViewport({ clientHeight: 400, scrollHeight: 400 });
+    // 실제 Lenis처럼 resize()가 구독자에게 'scroll'을 동기로 낸다
+    let onLenisScroll: (() => void) | undefined;
+    const order: string[] = [];
+    const lenis = {
+      on: vi.fn((_event: string, callback: () => void) => {
+        onLenisScroll = callback;
+        return () => {};
+      }),
+      resize: vi.fn(() => {
+        order.push('resize');
+        onLenisScroll?.();
+      }),
+    };
+    lenisMocks.getWrapperLenis.mockReturnValue(lenis as never);
+    const controller = create();
+    expect(lenis.on).toHaveBeenCalledWith('scroll', expect.any(Function));
+    viewport.addEventListener('wheel', () => order.push('lenis-wheel'));
+
+    setBox(viewport, { scrollHeight: 800 });
+    viewport.dispatchEvent(
+      new WheelEvent('wheel', { deltaY: 40, bubbles: true }),
+    );
+    expect(order).toEqual(['resize', 'lenis-wheel']);
+    // 크기만 다시 잰다. 드러내는 건 이어지는 실제 스크롤이 맡는다
+    expect(rail.dataset.state).toBe('hidden');
+    expect(thumb.style.height).toBe('196px');
+    controller.destroy();
+  });
+
+  it('직계 자식 박스는 그대로이고 깊은 자손만 커져도 스크롤 때 다시 잰다', () => {
+    const viewport = addViewport({ clientHeight: 400, scrollHeight: 1600 });
+    const controller = create();
+    expect(thumb.style.height).toBe('98px');
+    setBox(viewport, { scrollHeight: 3200 });
+    viewport.scrollTop = 10;
+    viewport.dispatchEvent(new Event('scroll'));
+    expect(thumb.style.height).toBe('49px');
+    controller.destroy();
+  });
+
+  it('처음엔 넘치지 않다가 깊은 자손이 커지면 스크롤 때 막대가 생긴다', () => {
+    const viewport = addViewport({ clientHeight: 400, scrollHeight: 400 });
+    const controller = create();
+    expect(rail.dataset.state).toBe('none');
+    setBox(viewport, { scrollHeight: 800 });
+    viewport.scrollTop = 20;
+    viewport.dispatchEvent(new Event('scroll'));
+    expect(rail.dataset.state).toBe('thin');
+    expect(thumb.style.height).toBe('196px');
+    controller.destroy();
+  });
+
+  it('썸을 끌면 이동량을 콘텐츠 거리로 바꿔 즉시 스크롤한다', () => {
+    const viewport = addViewport({ clientHeight: 400, scrollHeight: 1600 });
+    const controller = create();
+    thumb.dispatchEvent(pointer('pointerdown', { clientY: 50 }));
+    expect(rail.dataset.state).toBe('dragging');
+    thumb.dispatchEvent(pointer('pointermove', { clientY: 99 }));
+    // 49px × 범위 1200 / 이동 거리 294
+    expect(lenisMocks.scrollLenisTo).toHaveBeenLastCalledWith(viewport, 200, {
+      immediate: true,
+    });
+    thumb.dispatchEvent(pointer('pointerup', { clientX: 500, clientY: 99 }));
+    expect(rail.dataset.state).toBe('thin');
+    controller.destroy();
+  });
+
+  it('트랙을 누르면 한 화면 넘기고 감속을 탄다', () => {
+    const viewport = addViewport({ clientHeight: 400, scrollHeight: 1600 });
+    const controller = create();
+    rail.dispatchEvent(pointer('pointerdown', { clientY: 380 }));
+    expect(lenisMocks.scrollLenisTo).toHaveBeenCalledWith(viewport, 360, {
+      immediate: false,
+    });
+    controller.destroy();
+  });
+
+  it('Shift로 누르면 그 자리로 바로 가고 놓기 전까지 끌 수 있다', () => {
+    const viewport = addViewport({ clientHeight: 400, scrollHeight: 1600 });
+    const controller = create();
+    rail.dispatchEvent(
+      pointer('pointerdown', { clientY: 4 + 294 / 2 + 49, shiftKey: true }),
+    );
+    expect(lenisMocks.scrollLenisTo).toHaveBeenCalledWith(viewport, 600, {
+      immediate: true,
+    });
+    expect(rail.dataset.state).toBe('dragging');
+    controller.destroy();
+  });
+
+  it('inert면 포인터에 반응하지 않는다', () => {
+    addViewport({ clientHeight: 400, scrollHeight: 1600 });
+    const controller = create();
+    controller.setOptions({
+      inert: true,
+      railLeft: undefined,
+      placement: 'edge',
+    });
+    expect(rail.hasAttribute('data-inert')).toBe(true);
+    rail.dispatchEvent(pointer('pointerenter'));
+    expect(rail.dataset.state).toBe('hidden');
+    thumb.dispatchEvent(pointer('pointerdown', { clientY: 50 }));
+    expect(rail.dataset.state).toBe('hidden');
+    controller.destroy();
+  });
+
+  it('레일에 떨어진 휠은 스크롤 영역으로 넘기고 부모로 올리지 않는다', () => {
+    const viewport = addViewport({ clientHeight: 400, scrollHeight: 1600 });
+    const controller = create();
+    const parentWheel = vi.fn();
+    document.body.addEventListener('wheel', parentWheel);
+    const wheel = new WheelEvent('wheel', {
+      deltaY: 40,
+      bubbles: true,
+      cancelable: true,
+    });
+    rail.dispatchEvent(wheel);
+    expect(lenisMocks.forwardWheelToLenis).toHaveBeenCalledWith(
+      viewport,
+      wheel,
+    );
+    expect(wheel.defaultPrevented).toBe(true);
+    expect(parentWheel).not.toHaveBeenCalled();
+    document.body.removeEventListener('wheel', parentWheel);
+    controller.destroy();
+  });
+
+  it('보이는 뷰포트가 바뀌면 그쪽으로 옮겨 붙되 깜빡이지 않는다', () => {
+    const first = addViewport({ clientHeight: 400, scrollHeight: 1600 });
+    const second = addViewport({ clientHeight: 0, scrollHeight: 0 });
+    const controller = create();
+    expect(rail.dataset.state).toBe('hidden');
+
+    setBox(first, { clientHeight: 0 });
+    setBox(second, { clientHeight: 400, scrollHeight: 800 });
+    ResizeObserverStub.instances[0].callback();
+    expect(thumb.style.height).toBe('196px');
+    expect(rail.dataset.state).toBe('hidden');
+
+    second.scrollTop = 400;
+    second.dispatchEvent(new Event('scroll'));
+    expect(thumb.style.transform).toBe('translate3d(0, 200px, 0)');
+    expect(rail.dataset.state).toBe('thin');
+    controller.destroy();
+  });
+});
diff --git a/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarController.ts b/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarController.ts
new file mode 100644
index 000000000..11996887d
--- /dev/null
+++ b/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarController.ts
@@ -0,0 +1,519 @@
+import {
+  forwardWheelToLenis,
+  getWrapperLenis,
+  scrollLenisTo,
+} from '@hooks/useLenis';
+import { isMac } from '@utils/core/platform';
+
+import {
+  computeThumbGeometry,
+  resolveOverlayScrollbarState,
+  resolveTrackPressTarget,
+  scrollOffsetForThumbDrag,
+  wheelDeltaToPixels,
+  type OverlayScrollbarState,
+  type ThumbGeometry,
+} from './overlayScrollbarModel';
+
+/**
+ * 레일 자리. edge는 뷰포트 오른쪽 끝 안쪽, outside는 부모 바깥 오른쪽에 붙어 부모 높이만큼.
+ * 어느 쪽이든 그 자리는 막대 전용이어야 한다 - 버튼을 두지 않는다
+ */
+export type OverlayScrollbarPlacement = 'edge' | 'outside';
+
+export interface OverlayScrollbarOptions {
+  /** 끌어 정렬처럼 뷰포트 위 히트 판정이 필요한 동안 막대 입력을 끈다 */
+  inert: boolean;
+  /** 레일 왼쪽 위치(뷰포트 기준 px). edge 배치에서만 쓴다 */
+  railLeft: number | undefined;
+  placement: OverlayScrollbarPlacement;
+}
+
+export interface OverlayScrollbarController {
+  setOptions: (options: OverlayScrollbarOptions) => void;
+  destroy: () => void;
+}
+
+interface DragSession {
+  pointerId: number;
+  startY: number;
+  startScroll: number;
+  scale: number;
+}
+
+const DEFAULT_PAD = 4;
+const DEFAULT_MIN_THUMB = 28;
+const DEFAULT_HIDE_DELAY_MS = 900;
+
+// 분리 패널은 다른 창 문서라 instanceof HTMLElement가 거짓이 된다
+const isElement = (node: Element): node is HTMLElement => node.nodeType === 1;
+
+const readPx = (style: CSSStyleDeclaration, name: string, fallback: number) => {
+  const value = parseFloat(style.getPropertyValue(name));
+  return Number.isFinite(value) ? value : fallback;
+};
+
+const readMs = (style: CSSStyleDeclaration, name: string, fallback: number) => {
+  const raw = style.getPropertyValue(name).trim();
+  const value = parseFloat(raw);
+  if (!Number.isFinite(value)) return fallback;
+  if (raw.endsWith('ms')) return value;
+  return raw.endsWith('s') ? value * 1000 : value;
+};
+
+/**
+ * 레일의 부모(위치 지정된 래퍼) 안에서 보이는 스크롤 뷰포트를 찾아 썸을 맞춘다.
+ * keepalive 탭처럼 뷰포트가 여럿이면 보이는 쪽을 따라간다.
+ * 위치 갱신은 transform만 쓰고, 크기는 ResizeObserver 콜백에서만 잰다.
+ * 레일 자리는 레이아웃이 비워 둔 막대 전용 띠라, 넘치는 동안 레일이 포인터를 받는다
+ */
+export const createOverlayScrollbarController = (
+  rail: HTMLElement,
+  thumb: HTMLElement,
+  // 분리 패널 창이면 그 창 - 관찰자·타이머가 메인 창 렌더 주기에 묶이지 않게
+  view: Window & typeof globalThis,
+): OverlayScrollbarController => {
+  const host = rail.parentElement;
+  const doc = rail.ownerDocument;
+
+  let options: OverlayScrollbarOptions = {
+    inert: false,
+    railLeft: undefined,
+    placement: 'edge',
+  };
+  let viewport: HTMLElement | null = null;
+  let viewportVisible = false;
+  let geometry: ThumbGeometry | null = null;
+  let viewportSize = 0;
+  let contentSize = 0;
+  let trackSize = 0;
+  let pad = DEFAULT_PAD;
+  let minThumb = DEFAULT_MIN_THUMB;
+  let hideDelay = DEFAULT_HIDE_DELAY_MS;
+  let hovering = false;
+  let revealed = false;
+  let drag: DragSession | null = null;
+  let hideTimer: number | undefined;
+  let state: OverlayScrollbarState | null = null;
+  let lenis: ReturnType<typeof getWrapperLenis>;
+  let unsubscribeLenis: (() => void) | null = null;
+  let destroyed = false;
+  let syncingContentSize = false;
+  const observed = new Set<Element>();
+
+  const applyState = () => {
+    const next = resolveOverlayScrollbarState({
+      overflow: viewportVisible && !!geometry?.overflow,
+      dragging: drag !== null,
+      hovering: hovering && !options.inert,
+      revealed,
+    });
+    if (next === state) return;
+    state = next;
+    rail.dataset.state = next;
+  };
+
+  const reveal = () => {
+    revealed = true;
+    if (hideTimer !== undefined) view.clearTimeout(hideTimer);
+    hideTimer = view.setTimeout(() => {
+      hideTimer = undefined;
+      revealed = false;
+      applyState();
+    }, hideDelay);
+    applyState();
+  };
+
+  const placeThumb = () => {
+    if (!geometry) return;
+    thumb.style.transform = `translate3d(0, ${pad + geometry.offset}px, 0)`;
+  };
+
+  const updateOffset = () => {
+    if (!viewport || !geometry?.overflow) return;
+    geometry = computeThumbGeometry({
+      viewportSize,
+      contentSize,
+      scrollOffset: viewport.scrollTop,
+      trackSize,
+      minThumbSize: minThumb,
+    });
+    placeThumb();
+  };
+
+  const measure = () => {
+    if (!viewport || viewport.clientHeight === 0) {
+      viewportVisible = false;
+      geometry = null;
+      return;
+    }
+    const style = view.getComputedStyle(rail);
+    pad = readPx(style, '--ui-scrollbar-pad', DEFAULT_PAD);
+    minThumb = readPx(style, '--ui-scrollbar-min', DEFAULT_MIN_THUMB);
+    hideDelay = readMs(
+      style,
+      '--ui-scrollbar-hide-delay',
+      DEFAULT_HIDE_DELAY_MS,
+    );
+
+    viewportVisible = true;
+    viewportSize = viewport.clientHeight;
+    contentSize = viewport.scrollHeight;
+
+    let top = 0;
+    let left: number;
+    let height: number;
+    if (options.placement === 'outside' && host) {
+      // 부모 상자 바깥 여백에 붙인다 - 상자 안 행·버튼과 자리를 나누지 않게
+      left = host.clientWidth;
+      height = host.clientHeight;
+    } else {
+      // 부모가 위치 지정 요소가 아니면 오프셋 기준이 달라 부모 전체를 덮는 배치로 둔다
+      const aligned = viewport.offsetParent === host;
+      top = aligned ? viewport.offsetTop + viewport.clientTop : 0;
+      left =
+        (aligned ? viewport.offsetLeft + viewport.clientLeft : 0) +
+        (options.railLeft ?? viewport.clientWidth - rail.offsetWidth);
+      height = viewportSize;
+    }
+    rail.style.top = `${top}px`;
+    rail.style.left = `${left}px`;
+    rail.style.height = `${height}px`;
+
+    trackSize = Math.max(0, height - pad * 2);
+    geometry = computeThumbGeometry({
+      viewportSize,
+      contentSize,
+      scrollOffset: viewport.scrollTop,
+      trackSize,
+      minThumbSize: minThumb,
+    });
+    thumb.style.height = `${geometry.size}px`;
+    placeThumb();
+  };
+
+  // 관찰 대상(뷰포트 직계 자식)의 박스는 그대로인데 깊은 자손만 커져 scrollHeight가
+  // 바뀐 경우를 휠·스크롤·호버 시점에 바로잡는다. 같은 이유로 Lenis 한도도 낡았을 수 있어
+  // 함께 다시 잰다 - 안 그러면 휠이 이전 한도에 묶여 새 영역으로 못 간다. 바뀌었으면 true
+  const syncContentSize = (): boolean => {
+    if (!viewport || syncingContentSize) return false;
+    if (
+      viewport.scrollHeight === contentSize &&
+      viewport.clientHeight === viewportSize
+    ) {
+      return false;
+    }
+    syncingContentSize = true;
+    try {
+      // 캐시를 먼저 갱신한다 - Lenis resize()는 'scroll'을 동기로 내서 여기로 다시 들어온다
+      measure();
+      getWrapperLenis(viewport)?.resize();
+      applyState();
+    } finally {
+      syncingContentSize = false;
+    }
+    return true;
+  };
+
+  const onLenisScroll = () => {
+    if (!syncContentSize()) updateOffset();
+  };
+
+  // Lenis는 rAF 안에서 scrollTop을 바꾸고 바로 'scroll'을 낸다. 네이티브 이벤트만 들으면
+  // 썸이 콘텐츠보다 한 프레임 늦게 따라온다. 인스턴스는 부모 이펙트에서 늦게 생기므로 지연 구독
+  const syncLenis = () => {
+    const next = viewport ? getWrapperLenis(viewport) : undefined;
+    if (next === lenis) return;
+    unsubscribeLenis?.();
+    unsubscribeLenis = null;
+    lenis = next;
+    if (next) unsubscribeLenis = next.on('scroll', onLenisScroll);
+  };
+
+  const onScroll = () => {
+    syncLenis();
+    if (!syncContentSize()) updateOffset();
+    if (geometry?.overflow) reveal();
+  };
+
+  // Lenis보다 먼저 받아야 바뀐 한도로 이번 휠을 처리한다 (캡처 단계)
+  const onHostWheelCapture = () => {
+    syncContentSize();
+  };
+
+  const pickViewport = (): HTMLElement | null => {
+    if (!host) return null;
+    for (const child of Array.from(host.children)) {
+      if (child === rail || !isElement(child)) continue;
+      // keepalive 탭의 숨은 뷰포트(display: none)는 건너뛴다
+      if (child.clientHeight === 0) continue;
+      const { overflowY } = view.getComputedStyle(child);
+      if (overflowY === 'auto' || overflowY === 'scroll') return child;
+    }
+    return null;
+  };
+
+  // 관찰자가 없는 환경(jsdom 등)에서는 마운트·자식 변경 때만 잰다
+  const resizeObserver =
+    typeof view.ResizeObserver === 'function'
+      ? new view.ResizeObserver(() => refresh())
+      : null;
+  const mutationObserver =
+    typeof view.MutationObserver === 'function'
+      ? new view.MutationObserver(() => refresh())
+      : null;
+
+  // 관찰 대상이 바뀐 것만 반영 - 다시 observe하면 초기 콜백이 또 와서 루프가 된다
+  const syncObservation = () => {
+    if (!resizeObserver) return;
+    const targets = new Set<Element>();
+    if (host) {
+      targets.add(host);
+      Array.from(host.children).forEach((child) => {
+        if (child !== rail) targets.add(child);
+      });
+    }
+    if (viewport) {
+      Array.from(viewport.children).forEach((child) => targets.add(child));
+    }
+    observed.forEach((target) => {
+      if (targets.has(target)) return;
+      resizeObserver.unobserve(target);
+      observed.delete(target);
+    });
+    targets.forEach((target) => {
+      if (observed.has(target)) return;
+      resizeObserver.observe(target);
+      observed.add(target);
+    });
+  };
+
+  const observeMutations = () => {
+    if (!mutationObserver) return;
+    mutationObserver.disconnect();
+    if (host) mutationObserver.observe(host, { childList: true });
+    if (viewport) mutationObserver.observe(viewport, { childList: true });
+  };
+
+  const releaseDrag = () => {
+    if (!drag) return;
+    const { pointerId } = drag;
+    drag = null;
+    try {
+      if (rail.hasPointerCapture(pointerId))
+        rail.releasePointerCapture(pointerId);
+      if (thumb.hasPointerCapture(pointerId)) {
+        thumb.releasePointerCapture(pointerId);
+      }
+    } catch {
+      // 이미 해제된 포인터
+    }
+  };
+
+  const refresh = () => {
+    if (destroyed) return;
+    const next = pickViewport();
+    const changed = next !== viewport;
+    if (changed) {
+      viewport?.removeEventListener('scroll', onScroll);
+      releaseDrag();
+      viewport = next;
+      viewport?.addEventListener('scroll', onScroll, { passive: true });
+      syncLenis();
+      observeMutations();
+    }
+    syncObservation();
+    // 열림·탭 전환에는 드러내지 않는다 - 선택마다 패널이 다시 그려져 깜빡임이 소음이 된다.
+    // 막대는 스크롤할 때와 가장자리에 포인터가 닿을 때만 나타난다
+    measure();
+    applyState();
+  };
+
+  const railScale = () => {
+    const rect = rail.getBoundingClientRect();
+    return rail.offsetHeight > 0 && rect.height > 0
+      ? rect.height / rail.offsetHeight
+      : 1;
+  };
+
+  const startDrag = (
+    event: PointerEvent,
+    target: HTMLElement,
+    startScroll: number,
+  ) => {
+    drag = {
+      pointerId: event.pointerId,
+      startY: event.clientY,
+      startScroll,
+      scale: railScale(),
+    };
+    try {
+      target.setPointerCapture(event.pointerId);
+    } catch {
+      // 캡처를 못 잡아도 레일 위에서는 계속 끌린다
+    }
+    applyState();
+  };
+
+  const canInteract = () =>
+    !options.inert && viewport !== null && !!geometry?.overflow;
+
+  const onThumbPointerDown = (event: PointerEvent) => {
+    if (event.button !== 0 || !canInteract() || !viewport) return;
+    event.preventDefault();
+    event.stopPropagation();
+    startDrag(event, thumb, viewport.scrollTop);
+  };
+
+  const onTrackPointerDown = (event: PointerEvent) => {
+    if (event.target !== rail || event.button !== 0) return;
+    if (!canInteract() || !viewport || !geometry) return;
+    event.preventDefault();
+    const rect = rail.getBoundingClientRect();
+    const scale = railScale();
+    const pointer = (event.clientY - rect.top) / scale - pad;
+    // macOS는 ⌥, Windows는 Shift - 각 OS의 "누른 자리로 이동" 관례
+    const jumpToSpot = isMac() ? event.altKey : event.shiftKey;
+    const target = resolveTrackPressTarget({
+      pointer,
+      geometry,
+      scrollOffset: viewport.scrollTop,
+      viewportSize,
+      jumpToSpot,
+    });
+    if (target === null) return;
+    if (jumpToSpot) {
+      // 썸이 포인터 아래로 오고, 놓기 전까지 그대로 끌 수 있다
+      scrollLenisTo(viewport, target, { immediate: true });
+      startDrag(event, rail, target);
+      return;
+    }
+    const reducedMotion = doc.documentElement.hasAttribute(
+      'data-dmn-reduced-motion',
+    );
+    scrollLenisTo(viewport, target, { immediate: reducedMotion });
+  };
+
+  const onPointerMove = (event: PointerEvent) => {
+    if (!drag || event.pointerId !== drag.pointerId || !viewport || !geometry) {
+      return;
+    }
+    const target = scrollOffsetForThumbDrag({
+      startScroll: drag.startScroll,
+      pointerDelta: (event.clientY - drag.startY) / drag.scale,
+      range: geometry.range,
+      travel: geometry.travel,
+    });
+    scrollLenisTo(viewport, target, { immediate: true });
+  };
+
+  const onPointerEnter = (event: PointerEvent) => {
+    if (event.pointerType === 'touch') return;
+    syncContentSize();
+    hovering = true;
+    applyState();
+  };
+
+  const onPointerLeave = () => {
+    hovering = false;
+    if (drag) {
+      applyState();
+      return;
+    }
+    // 띠를 떠나면 바로 숨지 않고 대기 시간만큼 얇게 남는다
+    if (geometry?.overflow) reveal();
+    else applyState();
+  };
+
+  const onPointerEnd = (event: PointerEvent) => {
+    if (!drag || event.pointerId !== drag.pointerId) return;
+    releaseDrag();
+    const rect = rail.getBoundingClientRect();
+    hovering =
+      event.pointerType !== 'touch' &&
+      event.clientX >= rect.left &&
+      event.clientX <= rect.right &&
+      event.clientY >= rect.top &&
+      event.clientY <= rect.bottom;
+    reveal();
+  };
+
+  // 막대는 포커스를 가져가지 않는다 - 편집 중인 입력의 blur 커밋을 일으키지 않게
+  const onMouseDown = (event: MouseEvent) => event.preventDefault();
+
+  const onWheel = (event: WheelEvent) => {
+    if (!viewport || event.ctrlKey) return;
+    event.preventDefault();
+    event.stopPropagation();
+    if (forwardWheelToLenis(viewport, event)) return;
+    viewport.scrollBy({
+      left: wheelDeltaToPixels(
+        event.deltaX,
+        event.deltaMode,
+        viewport.clientWidth,
+      ),
+      top: wheelDeltaToPixels(
+        event.deltaY,
+        event.deltaMode,
+        viewport.clientHeight,
+      ),
+    });
+  };
+
+  thumb.addEventListener('pointerdown', onThumbPointerDown);
+  rail.addEventListener('pointerdown', onTrackPointerDown);
+  rail.addEventListener('pointermove', onPointerMove);
+  rail.addEventListener('pointerup', onPointerEnd);
+  rail.addEventListener('pointercancel', onPointerEnd);
+  rail.addEventListener('lostpointercapture', onPointerEnd);
+  rail.addEventListener('pointerenter', onPointerEnter);
+  rail.addEventListener('pointerleave', onPointerLeave);
+  rail.addEventListener('mousedown', onMouseDown);
+  rail.addEventListener('wheel', onWheel, { passive: false });
+  host?.addEventListener('wheel', onHostWheelCapture, {
+    capture: true,
+    passive: true,
+  });
+
+  refresh();
+
+  return {
+    setOptions: (next) => {
+      if (
+        next.inert === options.inert &&
+        next.railLeft === options.railLeft &&
+        next.placement === options.placement
+      ) {
+        return;
+      }
+      options = next;
+      rail.toggleAttribute('data-inert', next.inert);
+      if (next.inert) {
+        hovering = false;
+        releaseDrag();
+      }
+      measure();
+      applyState();
+    },
+    destroy: () => {
+      destroyed = true;
+      if (hideTimer !== undefined) view.clearTimeout(hideTimer);
+      releaseDrag();
+      resizeObserver?.disconnect();
+      mutationObserver?.disconnect();
+      unsubscribeLenis?.();
+      viewport?.removeEventListener('scroll', onScroll);
+      thumb.removeEventListener('pointerdown', onThumbPointerDown);
+      rail.removeEventListener('pointerdown', onTrackPointerDown);
+      rail.removeEventListener('pointermove', onPointerMove);
+      rail.removeEventListener('pointerup', onPointerEnd);
+      rail.removeEventListener('pointercancel', onPointerEnd);
+      rail.removeEventListener('lostpointercapture', onPointerEnd);
+      rail.removeEventListener('pointerenter', onPointerEnter);
+      rail.removeEventListener('pointerleave', onPointerLeave);
+      rail.removeEventListener('mousedown', onMouseDown);
+      rail.removeEventListener('wheel', onWheel);
+      host?.removeEventListener('wheel', onHostWheelCapture, { capture: true });
+    },
+  };
+};
diff --git a/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarModel.test.ts b/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarModel.test.ts
new file mode 100644
index 000000000..e7eff75d0
--- /dev/null
+++ b/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarModel.test.ts
@@ -0,0 +1,241 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  computeThumbGeometry,
+  resolveOverlayScrollbarState,
+  resolveTrackPressTarget,
+  scrollOffsetForThumbDrag,
+  wheelDeltaToPixels,
+} from './overlayScrollbarModel';
+
+describe('computeThumbGeometry', () => {
+  it('넘치지 않으면 썸이 트랙을 채우고 범위는 0', () => {
+    const g = computeThumbGeometry({
+      viewportSize: 400,
+      contentSize: 400,
+      scrollOffset: 0,
+      trackSize: 392,
+      minThumbSize: 28,
+    });
+    expect(g.range).toBe(0);
+    expect(g.overflow).toBe(false);
+    expect(g.size).toBe(392);
+    expect(g.offset).toBe(0);
+  });
+
+  it('1px 이하 차이는 서브픽셀 반올림으로 보고 넘침으로 치지 않음', () => {
+    const g = computeThumbGeometry({
+      viewportSize: 400,
+      contentSize: 401,
+      scrollOffset: 0,
+      trackSize: 392,
+      minThumbSize: 28,
+    });
+    expect(g.overflow).toBe(false);
+  });
+
+  it('썸 길이는 보이는 비율, 위치는 스크롤 비율을 따름', () => {
+    const g = computeThumbGeometry({
+      viewportSize: 400,
+      contentSize: 1600,
+      scrollOffset: 600,
+      trackSize: 400,
+      minThumbSize: 28,
+    });
+    expect(g.overflow).toBe(true);
+    expect(g.range).toBe(1200);
+    expect(g.size).toBe(100);
+    expect(g.travel).toBe(300);
+    expect(g.offset).toBe(150);
+  });
+
+  it('콘텐츠가 아주 길어도 최소 길이 아래로 줄지 않음', () => {
+    const g = computeThumbGeometry({
+      viewportSize: 300,
+      contentSize: 30000,
+      scrollOffset: 29700,
+      trackSize: 292,
+      minThumbSize: 28,
+    });
+    expect(g.size).toBe(28);
+    expect(g.offset).toBe(264);
+  });
+
+  it('트랙이 최소 길이보다 짧으면 트랙 길이에서 멈춤', () => {
+    const g = computeThumbGeometry({
+      viewportSize: 20,
+      contentSize: 200,
+      scrollOffset: 0,
+      trackSize: 12,
+      minThumbSize: 28,
+    });
+    expect(g.size).toBe(12);
+    expect(g.travel).toBe(0);
+  });
+
+  it('오버스크롤 값은 트랙 안으로 묶음', () => {
+    const base = {
+      viewportSize: 400,
+      contentSize: 1600,
+      trackSize: 400,
+      minThumbSize: 28,
+    };
+    expect(computeThumbGeometry({ ...base, scrollOffset: -40 }).offset).toBe(0);
+    expect(computeThumbGeometry({ ...base, scrollOffset: 1300 }).offset).toBe(
+      300,
+    );
+  });
+});
+
+describe('scrollOffsetForThumbDrag', () => {
+  it('썸 이동량을 콘텐츠 이동량으로 환산', () => {
+    expect(
+      scrollOffsetForThumbDrag({
+        startScroll: 600,
+        pointerDelta: 30,
+        range: 1200,
+        travel: 300,
+      }),
+    ).toBe(720);
+  });
+
+  it('범위 밖으로 끌면 양 끝에서 멈춤', () => {
+    const base = { startScroll: 600, range: 1200, travel: 300 };
+    expect(scrollOffsetForThumbDrag({ ...base, pointerDelta: -999 })).toBe(0);
+    expect(scrollOffsetForThumbDrag({ ...base, pointerDelta: 999 })).toBe(1200);
+  });
+
+  it('썸이 움직일 공간이 없으면 시작 위치 유지', () => {
+    expect(
+      scrollOffsetForThumbDrag({
+        startScroll: 40,
+        pointerDelta: 50,
+        range: 100,
+        travel: 0,
+      }),
+    ).toBe(40);
+  });
+});
+
+describe('resolveTrackPressTarget', () => {
+  const geometry = computeThumbGeometry({
+    viewportSize: 400,
+    contentSize: 1600,
+    scrollOffset: 600,
+    trackSize: 400,
+    minThumbSize: 28,
+  });
+
+  it('썸 위를 누르면 한 화면 위로', () => {
+    expect(
+      resolveTrackPressTarget({
+        pointer: 40,
+        geometry,
+        scrollOffset: 600,
+        viewportSize: 400,
+        jumpToSpot: false,
+      }),
+    ).toBe(240);
+  });
+
+  it('썸 아래를 누르면 한 화면 아래로', () => {
+    expect(
+      resolveTrackPressTarget({
+        pointer: 380,
+        geometry,
+        scrollOffset: 600,
+        viewportSize: 400,
+        jumpToSpot: false,
+      }),
+    ).toBe(960);
+  });
+
+  it('한 화면 이동도 범위 끝에서 멈춤', () => {
+    expect(
+      resolveTrackPressTarget({
+        pointer: 380,
+        geometry,
+        scrollOffset: 1100,
+        viewportSize: 400,
+        jumpToSpot: false,
+      }),
+    ).toBe(1200);
+  });
+
+  it('보조키를 누르면 썸 가운데가 누른 자리에 오도록 이동', () => {
+    expect(
+      resolveTrackPressTarget({
+        pointer: 350,
+        geometry,
+        scrollOffset: 600,
+        viewportSize: 400,
+        jumpToSpot: true,
+      }),
+    ).toBe(1200);
+    expect(
+      resolveTrackPressTarget({
+        pointer: 200,
+        geometry,
+        scrollOffset: 600,
+        viewportSize: 400,
+        jumpToSpot: true,
+      }),
+    ).toBe(600);
+  });
+
+  it('썸 위를 눌렀으면 이동하지 않음', () => {
+    expect(
+      resolveTrackPressTarget({
+        pointer: 200,
+        geometry,
+        scrollOffset: 600,
+        viewportSize: 400,
+        jumpToSpot: false,
+      }),
+    ).toBeNull();
+  });
+});
+
+describe('resolveOverlayScrollbarState', () => {
+  const base = {
+    overflow: true,
+    dragging: false,
+    hovering: false,
+    revealed: false,
+  };
+
+  it('넘치지 않으면 다른 입력과 무관하게 none', () => {
+    expect(
+      resolveOverlayScrollbarState({
+        ...base,
+        overflow: false,
+        dragging: true,
+        hovering: true,
+      }),
+    ).toBe('none');
+  });
+
+  it('끄는 중이 호버보다 우선', () => {
+    expect(
+      resolveOverlayScrollbarState({ ...base, dragging: true, hovering: true }),
+    ).toBe('dragging');
+  });
+
+  it('호버는 굵게, 스크롤 직후는 얇게, 그 밖은 숨김', () => {
+    expect(resolveOverlayScrollbarState({ ...base, hovering: true })).toBe(
+      'expanded',
+    );
+    expect(resolveOverlayScrollbarState({ ...base, revealed: true })).toBe(
+      'thin',
+    );
+    expect(resolveOverlayScrollbarState(base)).toBe('hidden');
+  });
+});
+
+describe('wheelDeltaToPixels', () => {
+  it('픽셀·줄·페이지 단위를 픽셀로', () => {
+    expect(wheelDeltaToPixels(12, 0, 300)).toBe(12);
+    expect(wheelDeltaToPixels(3, 1, 300)).toBe(48);
+    expect(wheelDeltaToPixels(1, 2, 300)).toBe(300);
+  });
+});
diff --git a/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarModel.ts b/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarModel.ts
new file mode 100644
index 000000000..324c5e4df
--- /dev/null
+++ b/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarModel.ts
@@ -0,0 +1,131 @@
+// 오버레이 스크롤 막대의 순수 계산 - DOM 없이 썸 크기·위치, 끌기·트랙 누름 환산, 표시 상태를 정한다
+
+export type OverlayScrollbarState =
+  | 'none'
+  | 'hidden'
+  | 'thin'
+  | 'expanded'
+  | 'dragging';
+
+// scrollHeight는 정수로 반올림돼 clientHeight보다 1px 크게 나오는 경우가 있다
+const OVERFLOW_EPSILON = 1;
+
+// 트랙 누름 한 번에 넘기는 양. 한 줄 남짓 겹쳐 이어 읽을 자리를 남긴다
+const PAGE_RATIO = 0.9;
+
+const LINE_HEIGHT_PX = 16;
+
+const clamp = (value: number, min: number, max: number) =>
+  Math.min(max, Math.max(min, value));
+
+export interface ThumbGeometryInput {
+  viewportSize: number;
+  contentSize: number;
+  scrollOffset: number;
+  /** 썸이 움직이는 트랙 길이 (레일 위아래 여백 제외) */
+  trackSize: number;
+  minThumbSize: number;
+}
+
+export interface ThumbGeometry {
+  overflow: boolean;
+  /** 스크롤할 수 있는 거리 */
+  range: number;
+  size: number;
+  /** 썸이 움직일 수 있는 거리 */
+  travel: number;
+  /** 트랙 시작점 기준 썸 위치 */
+  offset: number;
+}
+
+export const computeThumbGeometry = ({
+  viewportSize,
+  contentSize,
+  scrollOffset,
+  trackSize,
+  minThumbSize,
+}: ThumbGeometryInput): ThumbGeometry => {
+  const track = Math.max(0, trackSize);
+  const rawRange = Math.max(0, contentSize - viewportSize);
+  if (rawRange <= OVERFLOW_EPSILON || contentSize <= 0) {
+    return { overflow: false, range: 0, size: track, travel: 0, offset: 0 };
+  }
+  const proportional = (track * viewportSize) / contentSize;
+  const size = clamp(proportional, Math.min(minThumbSize, track), track);
+  const travel = Math.max(0, track - size);
+  const offset = clamp(scrollOffset / rawRange, 0, 1) * travel;
+  return { overflow: true, range: rawRange, size, travel, offset };
+};
+
+export const scrollOffsetForThumbDrag = ({
+  startScroll,
+  pointerDelta,
+  range,
+  travel,
+}: {
+  startScroll: number;
+  pointerDelta: number;
+  range: number;
+  travel: number;
+}): number => {
+  if (travel <= 0) return startScroll;
+  return clamp(startScroll + (pointerDelta * range) / travel, 0, range);
+};
+
+/**
+ * 트랙(썸 바깥)을 눌렀을 때 갈 스크롤 위치. 기본은 한 화면 이동,
+ * jumpToSpot이면 썸 가운데가 누른 자리에 오도록 바로 이동한다.
+ * pointer는 트랙 시작점 기준 좌표. 썸 위를 눌렀으면 null
+ */
+export const resolveTrackPressTarget = ({
+  pointer,
+  geometry,
+  scrollOffset,
+  viewportSize,
+  jumpToSpot,
+}: {
+  pointer: number;
+  geometry: ThumbGeometry;
+  scrollOffset: number;
+  viewportSize: number;
+  jumpToSpot: boolean;
+}): number | null => {
+  const { range, size, travel, offset } = geometry;
+  if (range <= 0) return null;
+  if (jumpToSpot) {
+    if (travel <= 0) return null;
+    return clamp((pointer - size / 2) / travel, 0, 1) * range;
+  }
+  if (pointer >= offset && pointer <= offset + size) return null;
+  const direction = pointer < offset ? -1 : 1;
+  return clamp(scrollOffset + direction * viewportSize * PAGE_RATIO, 0, range);
+};
+
+export const resolveOverlayScrollbarState = ({
+  overflow,
+  dragging,
+  hovering,
+  revealed,
+}: {
+  overflow: boolean;
+  dragging: boolean;
+  hovering: boolean;
+  revealed: boolean;
+}): OverlayScrollbarState => {
+  if (!overflow) return 'none';
+  if (dragging) return 'dragging';
+  if (hovering) return 'expanded';
+  if (revealed) return 'thin';
+  return 'hidden';
+};
+
+// WheelEvent.deltaMode 단위(0 픽셀, 1 줄, 2 페이지)를 픽셀로
+export const wheelDeltaToPixels = (
+  delta: number,
+  deltaMode: number,
+  pageSize: number,
+): number => {
+  if (deltaMode === 1) return delta * LINE_HEIGHT_PX;
+  if (deltaMode === 2) return delta * pageSize;
+  return delta;
+};
diff --git a/src/renderer/hooks/useLenis.ts b/src/renderer/hooks/useLenis.ts
index de66f89c6..5e5400a10 100644
--- a/src/renderer/hooks/useLenis.ts
+++ b/src/renderer/hooks/useLenis.ts
@@ -80,6 +80,60 @@ export const scrollLenisBy = (wrapper: HTMLElement, delta: number) => {
   });
 };
 
+/**
+ * 지정 위치로 스크롤. immediate면 한 프레임에 붙고, 아니면 Lenis 감속을 탄다
+ * 스크롤 막대 썸 끌기·트랙 누름처럼 휠 밖에서 오는 이동이 쓰는 경로
+ */
+export const scrollLenisTo = (
+  wrapper: HTMLElement,
+  top: number,
+  { immediate = false }: { immediate?: boolean } = {},
+) => {
+  const instance = lenisByWrapper.get(wrapper);
+  if (!instance) {
+    wrapper.scrollTo({ top, behavior: immediate ? 'auto' : 'smooth' });
+    return;
+  }
+  instance.scrollTo(top, immediate ? { immediate: true, force: true } : {});
+};
+
+// 같은 프레임에 스크롤 값을 받아야 하는 표시용 구독 (네이티브 scroll 이벤트는 한 프레임 늦다)
+export const getWrapperLenis = (wrapper: HTMLElement): Lenis | undefined =>
+  lenisByWrapper.get(wrapper);
+
+/**
+ * 스크롤 영역 바깥 형제 요소(스크롤 막대 레일)에 떨어진 휠을 Lenis로 넘긴다
+ * Lenis는 wrapper의 wheel 리스너로 동작하므로 같은 값의 이벤트를 다시 쏜다.
+ * Lenis가 없는 영역이면 false - 호출 쪽이 네이티브 스크롤로 처리
+ */
+export const forwardWheelToLenis = (
+  wrapper: HTMLElement,
+  event: WheelEvent,
+): boolean => {
+  if (!lenisByWrapper.has(wrapper)) return false;
+  const view = wrapper.ownerDocument.defaultView ?? window;
+  wrapper.dispatchEvent(
+    new view.WheelEvent('wheel', {
+      bubbles: true,
+      cancelable: true,
+      composed: true,
+      deltaX: event.deltaX,
+      deltaY: event.deltaY,
+      deltaZ: event.deltaZ,
+      deltaMode: event.deltaMode,
+      clientX: event.clientX,
+      clientY: event.clientY,
+      screenX: event.screenX,
+      screenY: event.screenY,
+      ctrlKey: event.ctrlKey,
+      shiftKey: event.shiftKey,
+      altKey: event.altKey,
+      metaKey: event.metaKey,
+    }),
+  );
+  return true;
+};
+
 // 문서 간 DOM 이동 뒤 브라우저 스크롤과 Lenis 목표점을 함께 맞춘다
 export const restoreLenisScroll = (wrapper: HTMLElement, top: number) => {
   const instance = lenisByWrapper.get(wrapper);

From 53ecc3ad9627a675aaf4729626a319d5df41598c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=97=B0=EC=9A=B0?= <yeonu@eunyeon.com>
Date: Sun, 8 Nov 2026 01:39:24 +0900
Subject: [PATCH 2/4] =?UTF-8?q?style:=20=EC=8A=A4=ED=81=AC=EB=A1=A4=20?=
 =?UTF-8?q?=EB=A7=89=EB=8C=80=20=ED=86=A0=ED=81=B0=EA=B3=BC=20=ED=91=9C?=
 =?UTF-8?q?=EC=8B=9C=20=EC=8A=A4=ED=83=80=EC=9D=BC=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/renderer/styles/main.css         | 67 ++++++++++++++++++++++++++++
 src/renderer/styles/tokens/base.css  | 10 +++++
 src/renderer/styles/tokens/dark.css  | 11 ++---
 src/renderer/styles/tokens/light.css | 12 ++---
 4 files changed, 90 insertions(+), 10 deletions(-)

diff --git a/src/renderer/styles/main.css b/src/renderer/styles/main.css
index cd18e96e0..c514cd8f2 100644
--- a/src/renderer/styles/main.css
+++ b/src/renderer/styles/main.css
@@ -304,6 +304,73 @@ body.dmn-dragging * {
   display: none !important;
 }
 
+/* 오버레이 스크롤 막대 (OverlayScrollbar) - 네이티브 막대는 위에서 숨긴 채 콘텐츠 위에 띄운다.
+   레이아웃을 차지하지 않고, 스크롤할 때와 가장자리에 포인터가 닿을 때만 드러난다.
+   top·left·height와 썸 transform은 컨트롤러가 인라인으로 맞춘다.
+   레일 띠는 막대 전용 자리다. 쓰는 쪽 레이아웃이 그 띠에 버튼을 두지 않으므로
+   넘치는 동안은 숨어 있어도 포인터를 받아, 가장자리에 닿으면 굵어지며 드러난다.
+   트랙 면은 그리지 않고 굵어지는 썸이 잡을 수 있다는 신호를 맡는다.
+   :where()로 특이도를 0에 둬 사용자 CSS가 항상 이긴다 */
+:where(.dmn-scrollbar) {
+  position: absolute;
+  top: 0;
+  right: 0;
+  width: var(--ui-scrollbar-band);
+  z-index: 1;
+  touch-action: none;
+}
+
+/* 사라질 땐 천천히(280ms), 나타날 땐 빠르게 - 상태별 규칙이 duration만 덮는다 */
+:where(.dmn-scrollbar-thumb) {
+  position: absolute;
+  top: 0;
+  right: var(--ui-scrollbar-edge);
+  width: var(--ui-scrollbar-size);
+  border-radius: 999px;
+  background: var(--ui-scrollbar-thumb);
+  box-shadow: 0 0 0 0.5px var(--ui-scrollbar-outline);
+  opacity: 0;
+  transition: opacity 280ms ease,
+    width var(--ui-duration-base) var(--ui-ease-out),
+    background-color var(--ui-duration-fast) ease;
+  will-change: transform;
+}
+
+:where(.dmn-scrollbar[data-state='thin'] .dmn-scrollbar-thumb) {
+  opacity: 1;
+  transition-duration: var(--ui-duration-fast), var(--ui-duration-base),
+    var(--ui-duration-fast);
+}
+
+:where(.dmn-scrollbar[data-state='expanded'] .dmn-scrollbar-thumb) {
+  opacity: 1;
+  width: var(--ui-scrollbar-size-expanded);
+  background: var(--ui-scrollbar-thumb-hover);
+  transition-duration: var(--ui-duration-fast), var(--ui-duration-base),
+    var(--ui-duration-fast);
+}
+
+:where(.dmn-scrollbar[data-state='dragging'] .dmn-scrollbar-thumb) {
+  opacity: 1;
+  width: var(--ui-scrollbar-size-expanded);
+  background: var(--ui-scrollbar-thumb-active);
+  transition-duration: var(--ui-duration-fast), var(--ui-duration-base), 60ms;
+}
+
+/* 모션 축소 - 굵기 전환 없이 페이드만 */
+:where(:root[data-dmn-reduced-motion] .dmn-scrollbar-thumb) {
+  transition: opacity var(--ui-duration-fast) linear;
+}
+
+/* 넘치지 않을 때·끌어 정렬 중(inert)·다른 드래그 중에는 막대가 입력을 받지 않는다 */
+:where(
+    .dmn-scrollbar[data-state='none'],
+    .dmn-scrollbar[data-inert],
+    html.dmn-drag-cursor .dmn-scrollbar
+  ) {
+  pointer-events: none;
+}
+
 /* PropertiesPanel 오버레이 스크롤바 (레이아웃 수축 방지) */
 .properties-panel-overlay-scroll {
   position: relative;
diff --git a/src/renderer/styles/tokens/base.css b/src/renderer/styles/tokens/base.css
index ab8b707ae..ae6348239 100644
--- a/src/renderer/styles/tokens/base.css
+++ b/src/renderer/styles/tokens/base.css
@@ -48,6 +48,16 @@
   --ui-ease-out: cubic-bezier(0.16, 1, 0.3, 1);
   --ui-ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
 
+  /* 오버레이 스크롤 막대 - 굵기·간격·대기 시간이 다이얼. 색은 테마 파일이 소유
+     band는 포인터를 받는 띠 폭. 굵은 썸 + 가장자리 간격이 이 안에서 끝나야 한다 */
+  --ui-scrollbar-band: 10px;
+  --ui-scrollbar-size: 5px;
+  --ui-scrollbar-size-expanded: 7px;
+  --ui-scrollbar-edge: 3px;
+  --ui-scrollbar-pad: 4px;
+  --ui-scrollbar-min: 28px;
+  --ui-scrollbar-hide-delay: 900ms;
+
   /* 토글 노브 - 끝점을 지나쳤다 돌아온다. 세기는 커브의 y값이 소유한다.
      1.35는 12px 이동에서 0.49px밖에 넘지 않아 눈에 안 띈다. 1.56이면 1.17px로
      인셋 2px 안에서 끝나면서 확실히 읽힌다.
diff --git a/src/renderer/styles/tokens/dark.css b/src/renderer/styles/tokens/dark.css
index cf0f3591c..6d3796358 100644
--- a/src/renderer/styles/tokens/dark.css
+++ b/src/renderer/styles/tokens/dark.css
@@ -114,11 +114,12 @@
   --ui-tab-socket-fill: rgba(255, 255, 255, 0.145);
   --ui-tab-socket-shadow: inset 0 1px 2px rgba(0, 0, 0, 0.28);
 
-  /* 코드 에디터 스크롤바 썸 — 크롬 필보다 진하다. 좁은 4px 막대라
-     같은 알파로는 웰 바닥과 안 갈린다 */
-  --ui-scrollbar-thumb: rgba(255, 255, 255, 0.14);
-  --ui-scrollbar-thumb-hover: rgba(255, 255, 255, 0.2);
-  --ui-scrollbar-thumb-active: rgba(255, 255, 255, 0.26);
+  /* 스크롤 막대 썸 — 콘텐츠 위에 뜨는 얇은 막대라 크롬 필보다 훨씬 진하다.
+     반대 톤 외곽선이 스와치·그라데이션 위에서도 형태를 지킨다 */
+  --ui-scrollbar-thumb: rgba(255, 255, 255, 0.32);
+  --ui-scrollbar-thumb-hover: rgba(255, 255, 255, 0.44);
+  --ui-scrollbar-thumb-active: rgba(255, 255, 255, 0.56);
+  --ui-scrollbar-outline: rgba(0, 0, 0, 0.28);
 
   /* 텍스트 위계 — 애플 실측(1차 L*88.6 / 2차 65.5 / 3차 59.2)에 맞춘 값.
      체감 눈부심에는 표면보다 텍스트가 더 크게 기여한다. 순백에 가까운 본문색을 두고
diff --git a/src/renderer/styles/tokens/light.css b/src/renderer/styles/tokens/light.css
index 4b2517489..92ea63913 100644
--- a/src/renderer/styles/tokens/light.css
+++ b/src/renderer/styles/tokens/light.css
@@ -139,11 +139,13 @@
   --ui-tab-socket-fill: rgba(16, 24, 40, 0.165);
   --ui-tab-socket-shadow: inset 0 1px 2px rgba(16, 24, 40, 0.14);
 
-  /* 코드 에디터 스크롤바 썸 — 좁은 4px 막대라 크롬 필보다 진하게.
-     밝은 웰 위에서는 다크보다 조금 더 밀어야 막대가 형태로 잡힌다 */
-  --ui-scrollbar-thumb: rgba(16, 24, 40, 0.2);
-  --ui-scrollbar-thumb-hover: rgba(16, 24, 40, 0.26);
-  --ui-scrollbar-thumb-active: rgba(16, 24, 40, 0.32);
+  /* 스크롤 막대 썸 — 밝은 면 위 어두운 막대. 외곽선은 반대 톤(밝게)
+     알파는 패널 바닥(#dee3ea) 위 대비비를 다크와 같은 단에 맞춘 값이다.
+     평소 2.9:1 · 굵게 4.3:1 · 끄는 중 6.1:1. 다크와 같은 알파를 쓰면 1.9:1로 흐려진다 */
+  --ui-scrollbar-thumb: rgba(16, 24, 40, 0.46);
+  --ui-scrollbar-thumb-hover: rgba(16, 24, 40, 0.6);
+  --ui-scrollbar-thumb-active: rgba(16, 24, 40, 0.72);
+  --ui-scrollbar-outline: rgba(255, 255, 255, 0.5);
 
   /* 텍스트 위계 — 다크가 순백을 피하듯 여기서도 순흑을 피한다. 배경과 같은
      방향의 쿨 편향을 줘 글자만 무채색으로 떠 보이지 않게 했다.

From 6f4bdfd4ebdfff1eb74a3d4fc51a93ac6537c52a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=97=B0=EC=9A=B0?= <yeonu@eunyeon.com>
Date: Sun, 8 Nov 2026 01:39:24 +0900
Subject: [PATCH 3/4] =?UTF-8?q?feat:=20=EC=86=8D=EC=84=B1=20=ED=8C=A8?=
 =?UTF-8?q?=EB=84=90=C2=B7=EC=84=A4=EC=A0=95=C2=B7=EB=AA=A9=EB=A1=9D?=
 =?UTF-8?q?=EC=97=90=20=EC=8A=A4=ED=81=AC=EB=A1=A4=20=EB=A7=89=EB=8C=80=20?=
 =?UTF-8?q?=EC=A0=81=EC=9A=A9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../panelDomContract.test.tsx.snap            | 738 ++++++++++++++++++
 .../batch/BatchPluginOnlyPanel.tsx            |   2 +
 .../document/DocumentBatchPanel.tsx           |   2 +
 .../document/DocumentElementPanel.tsx         |   2 +
 .../document/legacyKeyLikeBatch.tsx           |   2 +
 .../Grid/PropertiesPanel/layer/LayerRows.tsx  |   5 +-
 .../PropertiesPanel/layer/LayerTabContent.tsx |   2 +
 .../plugin/PluginSettingsPanelView.tsx        |   2 +
 .../single/SingleSelectionPanel.tsx           |   2 +
 .../content/pickers/CommonListPickerPage.tsx  |   8 +-
 src/renderer/components/main/Settings.tsx     |   9 +
 .../main/SettingsPanel/CssPanelContent.tsx    |   2 +
 .../SettingsPanel/PluginsPanelContent.tsx     |   2 +
 .../SettingsPanel/ShortcutsPanelContent.tsx   |   4 +-
 .../main/SettingsPanel/panelChrome.ts         |   2 +-
 15 files changed, 779 insertions(+), 5 deletions(-)

diff --git a/src/renderer/__tests__/panel/__snapshots__/panelDomContract.test.tsx.snap b/src/renderer/__tests__/panel/__snapshots__/panelDomContract.test.tsx.snap
index 328fe8d10..69c81aad0 100644
--- a/src/renderer/__tests__/panel/__snapshots__/panelDomContract.test.tsx.snap
+++ b/src/renderer/__tests__/panel/__snapshots__/panelDomContract.test.tsx.snap
@@ -2041,6 +2041,24 @@ exports[`속성 패널 DOM 약속 > 그래프 여럿 - 그룹 하나 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -4378,6 +4396,24 @@ exports[`속성 패널 DOM 약속 > 그래프 여럿 - 섞인 값 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -6008,6 +6044,24 @@ exports[`속성 패널 DOM 약속 > 그래프 하나 - 기본값 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -7698,6 +7752,24 @@ exports[`속성 패널 DOM 약속 > 그래프 하나 - 이름·고른 값·사
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -10779,6 +10851,24 @@ exports[`속성 패널 DOM 약속 > 그래프와 커서 트래커 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -13064,6 +13154,24 @@ exports[`속성 패널 DOM 약속 > 노브 여럿 - 섞인 값 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -14647,6 +14755,24 @@ exports[`속성 패널 DOM 약속 > 노브 하나 - 기본값 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -16334,6 +16460,24 @@ exports[`속성 패널 DOM 약속 > 노브 하나 - 축·고른 값·사용자 C
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -18851,6 +18995,24 @@ exports[`속성 패널 DOM 약속 > 노브와 그래프 - 카운터 탭 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -21368,6 +21530,24 @@ exports[`속성 패널 DOM 약속 > 노브와 그래프 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -25464,6 +25644,24 @@ exports[`속성 패널 DOM 약속 > 스탯 여럿 - 카운터 탭 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -29560,6 +29758,24 @@ exports[`속성 패널 DOM 약속 > 스탯 여럿 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -33148,6 +33364,24 @@ exports[`속성 패널 DOM 약속 > 스탯 하나 - 기본값 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -36636,6 +36870,24 @@ exports[`속성 패널 DOM 약속 > 스탯 하나 - 이름·누적·카운터 
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -38585,6 +38837,24 @@ exports[`속성 패널 DOM 약속 > 스프라이트 여럿 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -39945,6 +40215,24 @@ exports[`속성 패널 DOM 약속 > 스프라이트 하나 - 기본값 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -41479,6 +41767,24 @@ exports[`속성 패널 DOM 약속 > 스프라이트 하나 - 이미지·자세·
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -44130,6 +44436,24 @@ exports[`속성 패널 DOM 약속 > 스프라이트와 그래프 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -47184,6 +47508,24 @@ exports[`속성 패널 DOM 약속 > 스프라이트와 커서 트래커 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -49806,6 +50148,24 @@ exports[`속성 패널 DOM 약속 > 커서 트래커 여럿 - 섞인 모드 1`]
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -51719,6 +52079,24 @@ exports[`속성 패널 DOM 약속 > 커서 트래커 하나 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -57355,6 +57733,24 @@ exports[`속성 패널 DOM 약속 > 키 여럿 - 그룹 하나 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -62931,6 +63327,24 @@ exports[`속성 패널 DOM 약속 > 키 여럿 - 노트 탭 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -68631,6 +69045,24 @@ exports[`속성 패널 DOM 약속 > 키 여럿 - 섞인 값 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -74207,6 +74639,24 @@ exports[`속성 패널 DOM 약속 > 키 여럿 - 카운터 탭 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -79191,6 +79641,24 @@ exports[`속성 패널 DOM 약속 > 키 하나 - 기본값 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -84175,6 +84643,24 @@ exports[`속성 패널 DOM 약속 > 키 하나 - 노트 탭 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -89171,6 +89657,24 @@ exports[`속성 패널 DOM 약속 > 키 하나 - 이름·고른 값·사용자 C
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -94155,6 +94659,24 @@ exports[`속성 패널 DOM 약속 > 키 하나 - 카운터 탭 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -100297,6 +100819,24 @@ exports[`속성 패널 DOM 약속 > 키·그래프·노브 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -106705,6 +107245,24 @@ exports[`속성 패널 DOM 약속 > 키·스프라이트·그래프 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -112607,6 +113165,24 @@ exports[`속성 패널 DOM 약속 > 키와 그래프 - 카운터 탭 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -118509,6 +119085,24 @@ exports[`속성 패널 DOM 약속 > 키와 그래프 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -124220,6 +124814,24 @@ exports[`속성 패널 DOM 약속 > 키와 노브 - 노트 탭 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -129931,6 +130543,24 @@ exports[`속성 패널 DOM 약속 > 키와 노브 - 카운터 탭 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -135642,6 +136272,24 @@ exports[`속성 패널 DOM 약속 > 키와 노브 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -141331,6 +141979,24 @@ exports[`속성 패널 DOM 약속 > 키와 스탯 - 노트 탭 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -147020,6 +147686,24 @@ exports[`속성 패널 DOM 약속 > 키와 스탯 - 카운터 탭 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -152709,6 +153393,24 @@ exports[`속성 패널 DOM 약속 > 키와 스탯 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -158694,6 +159396,24 @@ exports[`속성 패널 DOM 약속 > 키와 스프라이트 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
@@ -164919,6 +165639,24 @@ exports[`속성 패널 DOM 약속 > 키와 커서 트래커 1`] = `
                   ],
                   "tag": "div",
                 },
+                {
+                  "attrs": {
+                    "aria-hidden": "true",
+                    "data-state": "none",
+                  },
+                  "children": [
+                    {
+                      "class": [
+                        "dmn-scrollbar-thumb",
+                      ],
+                      "tag": "div",
+                    },
+                  ],
+                  "class": [
+                    "dmn-scrollbar",
+                  ],
+                  "tag": "div",
+                },
               ],
               "class": [
                 "flex-1",
diff --git a/src/renderer/components/main/Grid/PropertiesPanel/batch/BatchPluginOnlyPanel.tsx b/src/renderer/components/main/Grid/PropertiesPanel/batch/BatchPluginOnlyPanel.tsx
index 8eb609f27..b6ea4d188 100644
--- a/src/renderer/components/main/Grid/PropertiesPanel/batch/BatchPluginOnlyPanel.tsx
+++ b/src/renderer/components/main/Grid/PropertiesPanel/batch/BatchPluginOnlyPanel.tsx
@@ -7,6 +7,7 @@ import { BatchSizeRow, type BatchGeometry } from './geometry/BatchGeometryRows';
 import EditSessionBoundary from '../selection/EditSessionBoundary';
 import BatchPanelHeader from './BatchPanelHeader';
 import type { MixedValueResult } from './batchPanelShared';
+import OverlayScrollbar from '@components/main/common/overlayScrollbar/OverlayScrollbar';
 
 interface BatchPluginOnlyPanelProps {
   setPanelElement: (el: HTMLDivElement | null) => void;
@@ -119,6 +120,7 @@ const BatchPluginOnlyPanel: React.FC<BatchPluginOnlyPanelProps> = ({
             {pluginSettings}
           </EditSessionBoundary>
         </div>
+        <OverlayScrollbar />
       </div>
     </div>
   );
diff --git a/src/renderer/components/main/Grid/PropertiesPanel/document/DocumentBatchPanel.tsx b/src/renderer/components/main/Grid/PropertiesPanel/document/DocumentBatchPanel.tsx
index ecbab23f7..dceda7a3d 100644
--- a/src/renderer/components/main/Grid/PropertiesPanel/document/DocumentBatchPanel.tsx
+++ b/src/renderer/components/main/Grid/PropertiesPanel/document/DocumentBatchPanel.tsx
@@ -52,6 +52,7 @@ import {
   LegacyKeyLikeBatchBody,
   type LegacyKeyLikeHost,
 } from './legacyKeyLikeBatch';
+import OverlayScrollbar from '@components/main/common/overlayScrollbar/OverlayScrollbar';
 
 // 옛 종류 선택의 일괄 기하 - 속성 패널이 옛 선택 모양(플러그인 요소 포함)에서 만든다
 export type LegacyBatchGeometry = BatchGeometry;
@@ -367,6 +368,7 @@ const DocumentBatchPanel = ({
             {legacyHost?.pluginSettings}
           </EditSessionBoundary>
         </div>
+        <OverlayScrollbar />
       </div>
     </div>
   );
diff --git a/src/renderer/components/main/Grid/PropertiesPanel/document/DocumentElementPanel.tsx b/src/renderer/components/main/Grid/PropertiesPanel/document/DocumentElementPanel.tsx
index 157993709..542d1605c 100644
--- a/src/renderer/components/main/Grid/PropertiesPanel/document/DocumentElementPanel.tsx
+++ b/src/renderer/components/main/Grid/PropertiesPanel/document/DocumentElementPanel.tsx
@@ -45,6 +45,7 @@ import { singlePanelWriterFor } from './documentPanelWriter';
 import { LegacyCustomCssSection, LegacySingleStyle } from './legacyBundleRows';
 import { KeyStatGeometry } from './legacyKeyStatSections';
 import type { PanelTab } from '@src/renderer/elementKinds/defineElementKind';
+import OverlayScrollbar from '@components/main/common/overlayScrollbar/OverlayScrollbar';
 
 interface DocumentElementPanelProps {
   sceneId: string;
@@ -380,6 +381,7 @@ const ElementPanelBody = ({
             {tabBody('style')}
           </div>
         )}
+        <OverlayScrollbar />
       </div>
     </div>
   );
diff --git a/src/renderer/components/main/Grid/PropertiesPanel/document/legacyKeyLikeBatch.tsx b/src/renderer/components/main/Grid/PropertiesPanel/document/legacyKeyLikeBatch.tsx
index 2c1a7c9e4..8c0743944 100644
--- a/src/renderer/components/main/Grid/PropertiesPanel/document/legacyKeyLikeBatch.tsx
+++ b/src/renderer/components/main/Grid/PropertiesPanel/document/legacyKeyLikeBatch.tsx
@@ -70,6 +70,7 @@ import {
 } from './documentPanelModel';
 import { PanelSections, type PanelSectionRenderers } from './documentPanelRows';
 import { canEditBundleField, type UnionSection } from './documentPanelUnion';
+import OverlayScrollbar from '@components/main/common/overlayScrollbar/OverlayScrollbar';
 
 // 속성 패널이 갖는 일괄 피커 상태 - 선택이 바뀌면 속성 패널이 닫는다
 export interface LegacyKeyLikeHost {
@@ -635,6 +636,7 @@ export const LegacyKeyLikeBatchBody = ({
             {tabBody('style')}
           </div>
         )}
+        <OverlayScrollbar />
       </div>
 
       <BatchColorPickerPopup
diff --git a/src/renderer/components/main/Grid/PropertiesPanel/layer/LayerRows.tsx b/src/renderer/components/main/Grid/PropertiesPanel/layer/LayerRows.tsx
index 0b505fea3..9cb93ad2c 100644
--- a/src/renderer/components/main/Grid/PropertiesPanel/layer/LayerRows.tsx
+++ b/src/renderer/components/main/Grid/PropertiesPanel/layer/LayerRows.tsx
@@ -50,13 +50,14 @@ interface LayerRowHandlers {
   onContextMenu: (event: React.MouseEvent) => void;
 }
 
+// 오른쪽 12px는 스크롤 막대 자리 - 숨김 토글 버튼이 그 띠에 걸리지 않게 비워 둔다
 const rowClass = (
   selected: boolean,
   hidden: boolean,
   dragging: boolean,
   dimmed = false,
 ) => `
-  group relative flex items-center gap-[8px] pr-[4px] h-[34px] select-none dmn-row-grabbable
+  group relative flex items-center gap-[8px] pr-[12px] h-[34px] select-none dmn-row-grabbable
   ${dimmed ? 'opacity-30' : hidden ? 'opacity-60' : ''}
   ${
     selected
@@ -200,7 +201,7 @@ export const LayerGroupRow = ({
       style={{ paddingLeft: layerRowIndent(depth) }}
       className={
         dropInto
-          ? 'group relative flex items-center gap-[8px] pr-[4px] h-[34px] select-none bg-fill-hover text-fg-muted'
+          ? 'group relative flex items-center gap-[8px] pr-[12px] h-[34px] select-none bg-fill-hover text-fg-muted'
           : rowClass(selected, hidden, dragging, dimmed)
       }
     >
diff --git a/src/renderer/components/main/Grid/PropertiesPanel/layer/LayerTabContent.tsx b/src/renderer/components/main/Grid/PropertiesPanel/layer/LayerTabContent.tsx
index d159771b7..543d68bdb 100644
--- a/src/renderer/components/main/Grid/PropertiesPanel/layer/LayerTabContent.tsx
+++ b/src/renderer/components/main/Grid/PropertiesPanel/layer/LayerTabContent.tsx
@@ -54,6 +54,7 @@ import {
   type LayerRowRename,
 } from './LayerRows';
 import { useLayerCollapseStore } from '@stores/grid/useLayerCollapseStore';
+import OverlayScrollbar from '@components/main/common/overlayScrollbar/OverlayScrollbar';
 
 // 끌기로 보지 않는 움직임 (화면 px)
 // 예전 레이어 끌기와 같은 시작 거리 (가로·세로 어느 쪽이든)
@@ -771,6 +772,7 @@ const LayerTabContent = ({
           </div>
         )}
       </div>
+      <OverlayScrollbar inert={dragging} />
 
       {contextMenuPresence.mounted &&
         createPortal(
diff --git a/src/renderer/components/main/Grid/PropertiesPanel/plugin/PluginSettingsPanelView.tsx b/src/renderer/components/main/Grid/PropertiesPanel/plugin/PluginSettingsPanelView.tsx
index 359c00772..ba0945dd8 100644
--- a/src/renderer/components/main/Grid/PropertiesPanel/plugin/PluginSettingsPanelView.tsx
+++ b/src/renderer/components/main/Grid/PropertiesPanel/plugin/PluginSettingsPanelView.tsx
@@ -14,6 +14,7 @@ import {
   hasRenderableSettings,
   type SettingsNormalizationErrorKind,
 } from '@plugins/runtime/settingsSections';
+import OverlayScrollbar from '@components/main/common/overlayScrollbar/OverlayScrollbar';
 
 interface PluginSettingsPanelViewProps {
   setPanelElement: (el: HTMLDivElement | null) => void;
@@ -100,6 +101,7 @@ const PluginSettingsPanelView: React.FC<PluginSettingsPanelViewProps> = ({
               )}
             </div>
           </div>
+          <OverlayScrollbar />
         </div>
       ) : (
         <div className="flex-1 flex items-center justify-center px-[24px]">
diff --git a/src/renderer/components/main/Grid/PropertiesPanel/single/SingleSelectionPanel.tsx b/src/renderer/components/main/Grid/PropertiesPanel/single/SingleSelectionPanel.tsx
index 3b89e507e..8b68ddf2d 100644
--- a/src/renderer/components/main/Grid/PropertiesPanel/single/SingleSelectionPanel.tsx
+++ b/src/renderer/components/main/Grid/PropertiesPanel/single/SingleSelectionPanel.tsx
@@ -22,6 +22,7 @@ import {
 } from '../controls/PropertyInputs';
 import { AXIS_FIELD_WIDTH } from '@utils/cardRecipes';
 import EditSessionBoundary from '../selection/EditSessionBoundary';
+import OverlayScrollbar from '@components/main/common/overlayScrollbar/OverlayScrollbar';
 
 // ============================================================================
 // Plugin Selection Panel
@@ -256,6 +257,7 @@ export const PluginSelectionPanel: React.FC<PluginSelectionPanelProps> = ({
               )}
           </EditSessionBoundary>
         </div>
+        <OverlayScrollbar />
       </div>
     </div>
   );
diff --git a/src/renderer/components/main/Modal/content/pickers/CommonListPickerPage.tsx b/src/renderer/components/main/Modal/content/pickers/CommonListPickerPage.tsx
index 28372a763..58c1fc8f5 100644
--- a/src/renderer/components/main/Modal/content/pickers/CommonListPickerPage.tsx
+++ b/src/renderer/components/main/Modal/content/pickers/CommonListPickerPage.tsx
@@ -3,6 +3,7 @@ import { useLenis } from '@hooks/useLenis';
 import Dropdown from '@components/main/common/dropdown/Dropdown';
 import SearchField from '@components/main/common/SearchField';
 import ListAddRow from '@components/main/common/ListAddRow';
+import OverlayScrollbar from '@components/main/common/overlayScrollbar/OverlayScrollbar';
 
 type FilterOption = {
   value: string;
@@ -167,7 +168,7 @@ export default function CommonListPickerPage<T>({
         />
       </div>
       {/* 리스트 컨테이너 — 배경보다 한 단계 밝은 필 테이블. 빈 공간도 테이블의 빈 영역으로 읽힘 */}
-      <div className="mx-[12px] bg-inset rounded-surface p-[4px] flex-1 min-h-0 flex flex-col">
+      <div className="relative mx-[12px] bg-inset rounded-surface p-[4px] flex-1 min-h-0 flex flex-col">
         <div
           ref={setViewportEl}
           className="flex-1 min-h-0 flex flex-col overflow-y-auto modal-content-scroll dmn-scroll-fade dmn-scroll-fade-shallow"
@@ -212,6 +213,11 @@ export default function CommonListPickerPage<T>({
             )}
           </div>
         </div>
+        {/* 행과 ⋮ 버튼이 상자 끝까지 차 있어 막대는 상자 바깥 12px 여백에 둔다 */}
+        <OverlayScrollbar
+          placement="outside"
+          className="[--ui-scrollbar-band:12px]"
+        />
       </div>
       {/* 하단 필터 바 */}
       <div className="p-[12px] shrink-0">
diff --git a/src/renderer/components/main/Settings.tsx b/src/renderer/components/main/Settings.tsx
index 28260b639..e55adc31b 100644
--- a/src/renderer/components/main/Settings.tsx
+++ b/src/renderer/components/main/Settings.tsx
@@ -49,6 +49,7 @@ import { cssApi } from '@api/modules/resources/cssApi';
 import { jsApi } from '@api/modules/plugin/jsApi';
 import { keysApi } from '@api/modules/editor/keysApi';
 import { appApi, windowApi } from '@api/modules/app/appApi';
+import OverlayScrollbar from '@components/main/common/overlayScrollbar/OverlayScrollbar';
 
 interface SettingsProps {
   showAlert: (msg: string, confirmText?: string) => void;
@@ -64,6 +65,10 @@ interface SettingsProps {
   ) => void;
 }
 
+// 스크롤 컨테이너가 창 전체 폭이라 막대를 오른쪽 끝에 두면 프리뷰 옆에 붙는다.
+// 카드 열(패딩 12 + 폭 348)과 프리뷰 페인(left 372) 사이 12px 골에 둔다
+const SETTINGS_RAIL_LEFT = 360;
+
 const Settings = ({
   showAlert,
   showConfirm,
@@ -739,6 +744,10 @@ const Settings = ({
           </div>
         </div>
       </div>
+      <OverlayScrollbar
+        railLeft={SETTINGS_RAIL_LEFT}
+        className="[--ui-scrollbar-band:12px] [--ui-scrollbar-pad:12px]"
+      />
       {/* 우측 고정 콘텐츠 페인 - 기본은 튜토리얼 프리뷰, 선택 시 설정 상세가 같은 표면을 채움 */}
       <div
         className={
diff --git a/src/renderer/components/main/SettingsPanel/CssPanelContent.tsx b/src/renderer/components/main/SettingsPanel/CssPanelContent.tsx
index 6dec0a66b..c1e40e171 100644
--- a/src/renderer/components/main/SettingsPanel/CssPanelContent.tsx
+++ b/src/renderer/components/main/SettingsPanel/CssPanelContent.tsx
@@ -35,6 +35,7 @@ import type {
 } from '@src/types/plugin/api';
 import { cssApi } from '@api/modules/resources/cssApi';
 import { useSingleFlightAction } from '@hooks/useSingleFlightAction';
+import OverlayScrollbar from '@components/main/common/overlayScrollbar/OverlayScrollbar';
 
 const CSS_HISTORY_ERROR_CODES: ReadonlySet<string> = new Set([
   'PATH_NOT_AUTHORIZED',
@@ -334,6 +335,7 @@ const CssPanelContent = ({
             </div>
           )}
         </div>
+        <OverlayScrollbar />
       </div>
 
       {/* 하단 바 - 불러오기(주 액션, 크게) + 닫기 */}
diff --git a/src/renderer/components/main/SettingsPanel/PluginsPanelContent.tsx b/src/renderer/components/main/SettingsPanel/PluginsPanelContent.tsx
index 56769f665..45634c08e 100644
--- a/src/renderer/components/main/SettingsPanel/PluginsPanelContent.tsx
+++ b/src/renderer/components/main/SettingsPanel/PluginsPanelContent.tsx
@@ -25,6 +25,7 @@ import { usePickerItemMenu } from '@hooks/usePickerItemMenu';
 import { usePluginHealthStore } from '@stores/plugin/usePluginHealthStore';
 import { getPluginDisplayName } from '@utils/plugin/components/pluginUtils';
 import type { JsPlugin } from '@src/types/plugin/js';
+import OverlayScrollbar from '@components/main/common/overlayScrollbar/OverlayScrollbar';
 
 interface PluginsPanelContentProps {
   plugins: JsPlugin[];
@@ -146,6 +147,7 @@ const PluginsPanelContent = ({
             </div>
           )}
         </div>
+        <OverlayScrollbar />
       </div>
 
       {/* 하단 바 - 추가(주 액션, 크게) + 닫기 */}
diff --git a/src/renderer/components/main/SettingsPanel/ShortcutsPanelContent.tsx b/src/renderer/components/main/SettingsPanel/ShortcutsPanelContent.tsx
index 20fccf42e..65ab1688a 100644
--- a/src/renderer/components/main/SettingsPanel/ShortcutsPanelContent.tsx
+++ b/src/renderer/components/main/SettingsPanel/ShortcutsPanelContent.tsx
@@ -14,6 +14,7 @@ import type {
 } from '@src/types/settings/shortcuts';
 import { getDefaultShortcuts } from '@src/renderer/defaults';
 import { isHistoryEditorFlushLocked } from '@src/renderer/editor/runtime/lifecycle/historyEditorFlushLock';
+import OverlayScrollbar from '@components/main/common/overlayScrollbar/OverlayScrollbar';
 
 type ShortcutKey = keyof ShortcutsState;
 
@@ -321,7 +322,7 @@ const ShortcutsPanelContent = ({
 
   return (
     <div
-      className="flex flex-col h-full"
+      className="relative flex flex-col h-full"
       onPointerDownCapture={(event) => {
         if (!isListening) return;
         const target = event.target as HTMLElement | null;
@@ -353,6 +354,7 @@ const ShortcutsPanelContent = ({
           ) : null}
         </div>
       </div>
+      <OverlayScrollbar />
 
       {/* 하단 바 - 닫기 */}
       <div className="px-[12px] pb-[12px] shrink-0">
diff --git a/src/renderer/components/main/SettingsPanel/panelChrome.ts b/src/renderer/components/main/SettingsPanel/panelChrome.ts
index 10cfa0a01..950f06317 100644
--- a/src/renderer/components/main/SettingsPanel/panelChrome.ts
+++ b/src/renderer/components/main/SettingsPanel/panelChrome.ts
@@ -39,7 +39,7 @@ export const PANEL_PILL_CLASS =
 
 // 인셋 리스트 웰 + 내부 스크롤 + 빈 상태 + 행 이름
 export const PANEL_LIST_WELL_CLASS =
-  'mx-[12px] mb-[12px] bg-inset rounded-surface flex-1 min-h-0 flex flex-col';
+  'relative mx-[12px] mb-[12px] bg-inset rounded-surface flex-1 min-h-0 flex flex-col';
 // 마스터 스위치가 꺼져도 목록은 가라앉히지 않는다. 그룹 opacity는 켜짐 알약의
 // 면과 항목 이름까지 같이 깎아, 정작 읽어야 할 '무엇이 켜져 있나'를 지운다.
 // 마스터 상태는 바로 위 토글이 이미 말하고 있다

From 26335d1841b50274ef870fadb173b9c9e82cabf0 Mon Sep 17 00:00:00 2001
From: lee-sihun <lee.sihun040223@gmail.com>
Date: Sun, 8 Nov 2026 11:11:13 +0900
Subject: [PATCH 4/4] =?UTF-8?q?fix:=20=EC=8A=A4=ED=81=AC=EB=A1=A4=20?=
 =?UTF-8?q?=EB=A7=89=EB=8C=80=EA=B0=80=20Lenis=20=EB=AA=A9=ED=91=9C=20?=
 =?UTF-8?q?=EC=A7=80=EC=A0=90=EC=9D=84=20=EB=8D=AE=EC=A7=80=20=EC=95=8A?=
 =?UTF-8?q?=EA=B3=A0=20=EA=B4=80=EC=B0=B0=EC=9E=90=EA=B0=80=20=EC=9E=A1?=
 =?UTF-8?q?=EC=9D=80=20=ED=81=AC=EA=B8=B0=20=EB=B3=80=ED=99=94=EB=8F=84=20?=
 =?UTF-8?q?=ED=95=9C=EB=8F=84=EC=97=90=20=EB=B0=98=EC=98=81=ED=95=9C?=
 =?UTF-8?q?=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../overlayScrollbarController.test.ts        | 54 +++++++++++++++++--
 .../overlayScrollbarController.ts             | 20 ++++---
 2 files changed, 58 insertions(+), 16 deletions(-)

diff --git a/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarController.test.ts b/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarController.test.ts
index f0714ff87..4a700be16 100644
--- a/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarController.test.ts
+++ b/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarController.test.ts
@@ -206,11 +206,10 @@ describe('createOverlayScrollbarController', () => {
     controller.destroy();
   });
 
-  it('깊은 자손만 커졌으면 휠을 Lenis보다 먼저 받아 한도를 다시 재게 한다', () => {
-    const viewport = addViewport({ clientHeight: 400, scrollHeight: 400 });
-    // 실제 Lenis처럼 resize()가 구독자에게 'scroll'을 동기로 낸다
+  // 실제 Lenis처럼 resize()는 목표 지점을 현재 위치로 덮고 'scroll'을 동기로 낸다.
+  // 한도만 다시 재는 dimensions.resize()는 이벤트를 내지 않는다
+  const mockLenis = (order: string[] = []) => {
     let onLenisScroll: (() => void) | undefined;
-    const order: string[] = [];
     const lenis = {
       on: vi.fn((_event: string, callback: () => void) => {
         onLenisScroll = callback;
@@ -220,23 +219,68 @@ describe('createOverlayScrollbarController', () => {
         order.push('resize');
         onLenisScroll?.();
       }),
+      dimensions: {
+        resize: vi.fn(() => {
+          order.push('dimensions');
+        }),
+      },
+      emitScroll: () => onLenisScroll?.(),
     };
     lenisMocks.getWrapperLenis.mockReturnValue(lenis as never);
+    return lenis;
+  };
+
+  it('깊은 자손만 커졌으면 휠을 Lenis보다 먼저 받아 한도를 다시 재게 한다', () => {
+    const viewport = addViewport({ clientHeight: 400, scrollHeight: 400 });
+    const order: string[] = [];
+    const lenis = mockLenis(order);
     const controller = create();
     expect(lenis.on).toHaveBeenCalledWith('scroll', expect.any(Function));
     viewport.addEventListener('wheel', () => order.push('lenis-wheel'));
+    order.length = 0;
 
     setBox(viewport, { scrollHeight: 800 });
     viewport.dispatchEvent(
       new WheelEvent('wheel', { deltaY: 40, bubbles: true }),
     );
-    expect(order).toEqual(['resize', 'lenis-wheel']);
+    expect(order).toEqual(['dimensions', 'lenis-wheel']);
     // 크기만 다시 잰다. 드러내는 건 이어지는 실제 스크롤이 맡는다
     expect(rail.dataset.state).toBe('hidden');
     expect(thumb.style.height).toBe('196px');
     controller.destroy();
   });
 
+  it('부드러운 스크롤 중에 높이가 바뀌어도 Lenis 목표 지점을 덮지 않는다', () => {
+    const viewport = addViewport({ clientHeight: 400, scrollHeight: 1600 });
+    const lenis = mockLenis();
+    const controller = create();
+    setBox(viewport, { scrollHeight: 2000 });
+    lenis.emitScroll();
+    expect(lenis.resize).not.toHaveBeenCalled();
+    expect(lenis.dimensions.resize).toHaveBeenCalled();
+    controller.destroy();
+  });
+
+  it('관찰자가 잡은 크기 변화도 Lenis 한도에 반영한다', () => {
+    const viewport = addViewport({ clientHeight: 400, scrollHeight: 400 });
+    const lenis = mockLenis();
+    const controller = create();
+    lenis.dimensions.resize.mockClear();
+
+    setBox(viewport, { scrollHeight: 1600 });
+    ResizeObserverStub.instances.forEach((observer) => observer.callback());
+    expect(lenis.dimensions.resize).toHaveBeenCalledTimes(1);
+    expect(thumb.style.height).toBe('98px');
+
+    // 이미 반영된 크기라 다음 휠에서 다시 재지 않는다
+    viewport.dispatchEvent(
+      new WheelEvent('wheel', { deltaY: 40, bubbles: true }),
+    );
+    expect(lenis.dimensions.resize).toHaveBeenCalledTimes(1);
+    expect(lenis.resize).not.toHaveBeenCalled();
+    controller.destroy();
+  });
+
   it('직계 자식 박스는 그대로이고 깊은 자손만 커져도 스크롤 때 다시 잰다', () => {
     const viewport = addViewport({ clientHeight: 400, scrollHeight: 1600 });
     const controller = create();
diff --git a/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarController.ts b/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarController.ts
index 11996887d..de8165dad 100644
--- a/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarController.ts
+++ b/src/renderer/components/main/common/overlayScrollbar/overlayScrollbarController.ts
@@ -98,7 +98,6 @@ export const createOverlayScrollbarController = (
   let lenis: ReturnType<typeof getWrapperLenis>;
   let unsubscribeLenis: (() => void) | null = null;
   let destroyed = false;
-  let syncingContentSize = false;
   const observed = new Set<Element>();
 
   const applyState = () => {
@@ -157,8 +156,14 @@ export const createOverlayScrollbarController = (
     );
 
     viewportVisible = true;
+    const sizeChanged =
+      viewportSize !== viewport.clientHeight ||
+      contentSize !== viewport.scrollHeight;
     viewportSize = viewport.clientHeight;
     contentSize = viewport.scrollHeight;
+    // 크기가 바뀌면 Lenis 한도도 함께 다시 잰다 - Lenis 관찰자는 깊은 자손 변화를 놓칠 수 있다.
+    // resize()는 진행 중인 부드러운 스크롤 목표를 현재 위치로 덮으므로 dimensions만 다시 잰다
+    if (sizeChanged) getWrapperLenis(viewport)?.dimensions.resize();
 
     let top = 0;
     let left: number;
@@ -196,22 +201,15 @@ export const createOverlayScrollbarController = (
   // 바뀐 경우를 휠·스크롤·호버 시점에 바로잡는다. 같은 이유로 Lenis 한도도 낡았을 수 있어
   // 함께 다시 잰다 - 안 그러면 휠이 이전 한도에 묶여 새 영역으로 못 간다. 바뀌었으면 true
   const syncContentSize = (): boolean => {
-    if (!viewport || syncingContentSize) return false;
+    if (!viewport) return false;
     if (
       viewport.scrollHeight === contentSize &&
       viewport.clientHeight === viewportSize
     ) {
       return false;
     }
-    syncingContentSize = true;
-    try {
-      // 캐시를 먼저 갱신한다 - Lenis resize()는 'scroll'을 동기로 내서 여기로 다시 들어온다
-      measure();
-      getWrapperLenis(viewport)?.resize();
-      applyState();
-    } finally {
-      syncingContentSize = false;
-    }
+    measure();
+    applyState();
     return true;
   };