From 865d3bb4adea4f90380653adbab220dd29fbf3d4 Mon Sep 17 00:00:00 2001
From: Chris233 <h-chris233@outlook.com>
Date: Fri, 10 Jul 2026 21:52:51 +0800
Subject: [PATCH] Disable background scrolling when settings open

Fixes #580: prevent background thin-scroll areas from scrolling/bleeding through when the Settings modal is open. Adds data-ol-settings-open={settingsOpen ? 'true' : undefined} to the main FloatingShell div and corresponding CSS in tokens.css to set overflow:hidden and hide WebKit scrollbars when the attribute is present. Also adds settings-modal-scroll-isolation.test.mjs to assert the attribute placement and CSS selectors.
---
 .../settings-modal-scroll-isolation.test.mjs  | 62 +++++++++++++++++++
 .../app/src/components/FloatingShell.tsx      |  1 +
 openless-all/app/src/styles/tokens.css        |  7 +++
 3 files changed, 70 insertions(+)
 create mode 100644 openless-all/app/scripts/settings-modal-scroll-isolation.test.mjs

diff --git a/openless-all/app/scripts/settings-modal-scroll-isolation.test.mjs b/openless-all/app/scripts/settings-modal-scroll-isolation.test.mjs
new file mode 100644
index 00000000..b7db5568
--- /dev/null
+++ b/openless-all/app/scripts/settings-modal-scroll-isolation.test.mjs
@@ -0,0 +1,62 @@
+import { readFile } from 'node:fs/promises';
+
+function assertEqual(actual, expected, name) {
+  if (actual !== expected) {
+    throw new Error(`${name}：期望 ${expected}，实际 ${actual}`);
+  }
+}
+
+function assertMatch(source, pattern, name) {
+  if (!pattern.test(source)) {
+    throw new Error(`${name}：未找到 ${pattern}`);
+  }
+}
+
+const floatingShellTsx = await readFile(
+  new URL('../src/components/FloatingShell.tsx', import.meta.url),
+  'utf-8',
+);
+const tokensCss = await readFile(
+  new URL('../src/styles/tokens.css', import.meta.url),
+  'utf-8',
+);
+
+const lockAttributeMatches = [
+  ...floatingShellTsx.matchAll(/data-ol-settings-open=\{([^}]*)\}/g),
+];
+
+assertEqual(
+  lockAttributeMatches.length,
+  1,
+  '背景滚动锁标记应只出现一次',
+);
+
+const [lockAttributeMatch] = lockAttributeMatches;
+const lockAttributeExpression = lockAttributeMatch[1];
+const lockAttributeIndex = lockAttributeMatch.index;
+const backgroundScrollerIndex = floatingShellTsx.indexOf('className="ol-thinscroll', lockAttributeIndex);
+const settingsModalIndex = floatingShellTsx.indexOf('<SettingsModal', lockAttributeIndex);
+
+assertMatch(
+  lockAttributeExpression,
+  /\bsettingsOpen\b/,
+  '背景滚动锁标记应由设置弹窗状态控制',
+);
+assertMatch(
+  lockAttributeExpression,
+  /\bundefined\b/,
+  '设置弹窗关闭时应移除背景滚动锁标记',
+);
+if (!(lockAttributeIndex < backgroundScrollerIndex && backgroundScrollerIndex < settingsModalIndex)) {
+  throw new Error('背景滚动锁标记应先于背景滚动区和设置弹窗声明');
+}
+assertMatch(
+  tokensCss,
+  /\[data-ol-settings-open\]\s+\.ol-thinscroll\s*\{[^}]*overflow:\s*hidden\s*!important\s*;?[^}]*\}/s,
+  '背景层内的所有细滚动区应在设置弹窗打开时停止滚动',
+);
+assertMatch(
+  tokensCss,
+  /\[data-ol-settings-open\]\s+\.ol-thinscroll::\-webkit-scrollbar\s*\{[^}]*display:\s*none\s*;?[^}]*\}/s,
+  'WebKitGTK 下应直接隐藏背景细滚动条',
+);
diff --git a/openless-all/app/src/components/FloatingShell.tsx b/openless-all/app/src/components/FloatingShell.tsx
index 96882c48..0f3a744f 100644
--- a/openless-all/app/src/components/FloatingShell.tsx
+++ b/openless-all/app/src/components/FloatingShell.tsx
@@ -175,6 +175,7 @@ function FloatingShellBody({ os, initialTab, initialSettings }: { os: OS; initia
 
       {/* Main shell — flush with the frosted backplate (no separate float). */}
       <div
+        data-ol-settings-open={settingsOpen ? 'true' : undefined}
         style={{
           flex: 1, minHeight: 0,
           display: 'flex',
diff --git a/openless-all/app/src/styles/tokens.css b/openless-all/app/src/styles/tokens.css
index da26024f..b27d01b9 100755
--- a/openless-all/app/src/styles/tokens.css
+++ b/openless-all/app/src/styles/tokens.css
@@ -88,6 +88,13 @@ body {
 .ol-thinscroll::-webkit-scrollbar-thumb:hover { background: rgba(0, 0, 0, 0.28); }
 .ol-thinscroll { scrollbar-width: thin; scrollbar-color: rgba(0, 0, 0, 0.18) transparent; }
 
+/* issue #580：设置弹窗打开时停用背景滚动层，规避 WebKitGTK 滚动条穿透合成。 */
+[data-ol-settings-open] .ol-thinscroll {
+  overflow: hidden !important;
+  scrollbar-width: none;
+}
+[data-ol-settings-open] .ol-thinscroll::-webkit-scrollbar { display: none; }
+
 /* Glass surface */
 .ol-glass {
   background: var(--ol-glass-bg);