From db2a71b12f7d5a389f60aa0fc05f1ff56c72de54 Mon Sep 17 00:00:00 2001
From: Mateusz Choma <chomamateusz@gmail.com>
Date: Sat, 31 Oct 2026 19:11:06 +0100
Subject: [PATCH 1/2] feat(web): add a setting to disable history swipe
 navigation

Horizontal mouse wheels can accidentally navigate desktop thread history.
Electron input events do not distinguish a trackpad swipe from a mouse wheel.

Add a default-enabled client setting with desktop Settings search and reset
support. Unmount the gesture handler when disabled, and cover disabling,
mid-swipe cleanup, and re-enabling with focused regression tests.

Model: gpt-6.1-sol via Codex CLI, orchestrated by Claude Code.
---
 .../AppSidebarLayout.browser.test.tsx         | 67 +++++++++++++++++++
 apps/web/src/components/AppSidebarLayout.tsx  |  5 +-
 .../src/components/HistorySwipeNavigation.tsx |  1 +
 .../components/settings/SettingsPanels.tsx    | 35 ++++++++++
 .../settings/settingsSearch.test.ts           |  2 +
 .../src/components/settings/settingsSearch.ts |  7 ++
 packages/contracts/src/settings.test.ts       | 13 ++++
 packages/contracts/src/settings.ts            |  2 +
 8 files changed, 130 insertions(+), 2 deletions(-)
 create mode 100644 apps/web/src/components/AppSidebarLayout.browser.test.tsx

diff --git a/apps/web/src/components/AppSidebarLayout.browser.test.tsx b/apps/web/src/components/AppSidebarLayout.browser.test.tsx
new file mode 100644
index 0000000000000..c1e087ff9e93a
--- /dev/null
+++ b/apps/web/src/components/AppSidebarLayout.browser.test.tsx
@@ -0,0 +1,67 @@
+import { DEFAULT_CLIENT_SETTINGS } from "@t3tools/contracts/settings";
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import { act, render } from "../../test/render";
+import {
+  __resetClientSettingsPersistenceForTests,
+  __setClientSettingsForTests,
+  updateClientSettings,
+} from "../hooks/useSettings";
+import { AppSidebarLayout } from "./AppSidebarLayout";
+
+vi.mock("../env", () => ({ isElectron: true }));
+vi.mock("./Sidebar", () => ({ default: () => null }));
+vi.mock("./BackgroundThreadAnnouncer", () => ({ BackgroundThreadAnnouncer: () => null }));
+vi.mock("./sidebar/SidebarChrome", () => ({ SidebarBrandWidthProbe: () => null }));
+vi.mock("../localApi", () => ({
+  ensureLocalApi: () => ({
+    persistence: { setClientSettings: async () => undefined },
+  }),
+}));
+
+function setup(historySwipeNavigation: boolean) {
+  __resetClientSettingsPersistenceForTests();
+  __setClientSettingsForTests({ ...DEFAULT_CLIENT_SETTINGS, historySwipeNavigation });
+}
+
+function wheel(deltaX: number) {
+  window.dispatchEvent(new WheelEvent("wheel", { deltaX, clientY: 200 }));
+}
+
+describe("desktop history swipe navigation", () => {
+  it.each(["back", "forward"] as const)(
+    "disables %s swipes and can re-enable them without reloading",
+    async (direction) => {
+      setup(false);
+      using _available = vi
+        .spyOn(window.navigation, direction === "back" ? "canGoBack" : "canGoForward", "get")
+        .mockReturnValue(true);
+      await using screen = await render(<AppSidebarLayout>Thread</AppSidebarLayout>);
+      using navigate = vi.spyOn(window.history, direction).mockImplementation(() => undefined);
+      const deltaX = direction === "back" ? -140 : 140;
+
+      await act(() => {
+        wheel(deltaX);
+        wheel(0);
+      });
+      expect(navigate).not.toHaveBeenCalled();
+      await expect.element(screen.getByTestId("history-swipe-indicator")).not.toBeInTheDocument();
+
+      await act(() => updateClientSettings({ historySwipeNavigation: true }));
+      await act(() => wheel(deltaX));
+      await expect.element(screen.getByTestId("history-swipe-indicator")).toBeInTheDocument();
+
+      await act(() => updateClientSettings({ historySwipeNavigation: false }));
+      await expect.element(screen.getByTestId("history-swipe-indicator")).not.toBeInTheDocument();
+      await act(() => wheel(0));
+      expect(navigate).not.toHaveBeenCalled();
+
+      await act(() => updateClientSettings({ historySwipeNavigation: true }));
+      await act(() => {
+        wheel(deltaX);
+        wheel(0);
+      });
+      expect(navigate).toHaveBeenCalledOnce();
+    },
+  );
+});
diff --git a/apps/web/src/components/AppSidebarLayout.tsx b/apps/web/src/components/AppSidebarLayout.tsx
index 91df5616f7f50..6140b77d49230 100644
--- a/apps/web/src/components/AppSidebarLayout.tsx
+++ b/apps/web/src/components/AppSidebarLayout.tsx
@@ -31,7 +31,7 @@ import { selectActiveRightPanel, useRightPanelStore } from "../rightPanelStore";
 import { selectThreadTerminalUiState, useTerminalUiStateStore } from "../terminalUiStateStore";
 import { cn, isMacPlatform } from "../lib/utils";
 import { primaryServerKeybindingsAtom } from "../state/server";
-import { useEnvironmentIdentificationMode } from "../hooks/useSettings";
+import { useClientSettings, useEnvironmentIdentificationMode } from "../hooks/useSettings";
 import {
   PanelAnimationSuppressionProvider,
   usePanelAnimationSettings,
@@ -402,6 +402,7 @@ function SidebarControl() {
 }
 
 export function AppSidebarLayout({ children }: { children: ReactNode }) {
+  const historySwipeNavigation = useClientSettings((settings) => settings.historySwipeNavigation);
   const sidebarArea = workspaceAreaProps("sidebar", 0, "Threads");
   const [sidebarRouteReveal] = useState<SidebarRouteReveal>(() => ({
     observedKey: null,
@@ -475,7 +476,7 @@ export function AppSidebarLayout({ children }: { children: ReactNode }) {
         {children}
         <BackgroundThreadAnnouncer />
         <SidebarControl />
-        {isElectron ? <HistorySwipeNavigation /> : null}
+        {isElectron && historySwipeNavigation ? <HistorySwipeNavigation /> : null}
       </SidebarProvider>
     </PanelAnimationSuppressionProvider>
   );
diff --git a/apps/web/src/components/HistorySwipeNavigation.tsx b/apps/web/src/components/HistorySwipeNavigation.tsx
index c020878b25363..80b4e2aca3c3e 100644
--- a/apps/web/src/components/HistorySwipeNavigation.tsx
+++ b/apps/web/src/components/HistorySwipeNavigation.tsx
@@ -162,6 +162,7 @@ function SwipeIndicator({ direction, progress, y, bounds, tracking }: SwipeIndic
   return (
     <div
       aria-hidden="true"
+      data-testid="history-swipe-indicator"
       className="pointer-events-none fixed z-100 overflow-hidden"
       style={bounds}
     >
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index dca3eabc868aa..f7222a7acfdeb 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -536,6 +536,9 @@ export function useSettingsRestore(onRestored?: () => void) {
       ? ["Delete confirmation"]
       : []),
     ...(settings.confirmQuit !== DEFAULT_UNIFIED_SETTINGS.confirmQuit ? ["Quit shortcut"] : []),
+    ...(settings.historySwipeNavigation !== DEFAULT_UNIFIED_SETTINGS.historySwipeNavigation
+      ? ["Swipe to go back and forward"]
+      : []),
     ...(isTextGenerationModelDirty ? ["Text generation model"] : []),
     ...(settings.threadTitleInstructions !== DEFAULT_UNIFIED_SETTINGS.threadTitleInstructions
       ? ["Thread title instructions"]
@@ -643,6 +646,7 @@ export function useSettingsRestore(onRestored?: () => void) {
       confirmThreadDelete: DEFAULT_UNIFIED_SETTINGS.confirmThreadDelete,
       confirmThreadUnpin: DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin,
       confirmQuit: DEFAULT_UNIFIED_SETTINGS.confirmQuit,
+      historySwipeNavigation: DEFAULT_UNIFIED_SETTINGS.historySwipeNavigation,
       textGenerationModelSelection: DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection,
       threadTitleInstructions: DEFAULT_UNIFIED_SETTINGS.threadTitleInstructions,
       fontFamilySans: DEFAULT_UNIFIED_SETTINGS.fontFamilySans,
@@ -880,6 +884,37 @@ export function GeneralSettingsPanel() {
         />
       </SettingsSection>
 
+      {isElectron ? (
+        <SettingsSection id="navigation" title="Navigation">
+          <SettingsRow
+            {...searchableSetting("history-swipe-navigation")}
+            description="Two-finger horizontal swipes move through your thread history. Turn off if a mouse with a horizontal wheel switches threads by accident."
+            resetAction={
+              settings.historySwipeNavigation !==
+              DEFAULT_UNIFIED_SETTINGS.historySwipeNavigation ? (
+                <SettingResetButton
+                  label="swipe navigation"
+                  onClick={() =>
+                    updateSettings({
+                      historySwipeNavigation: DEFAULT_UNIFIED_SETTINGS.historySwipeNavigation,
+                    })
+                  }
+                />
+              ) : null
+            }
+            control={
+              <Switch
+                checked={settings.historySwipeNavigation}
+                onCheckedChange={(checked) =>
+                  updateSettings({ historySwipeNavigation: Boolean(checked) })
+                }
+                aria-label="Swipe to go back and forward"
+              />
+            }
+          />
+        </SettingsSection>
+      ) : null}
+
       <SettingsSection id="confirmations" title="Confirmations">
         <SettingsRow
           {...searchableSetting("unpin-confirmation")}
diff --git a/apps/web/src/components/settings/settingsSearch.test.ts b/apps/web/src/components/settings/settingsSearch.test.ts
index 07d1d5dd6c8b9..467de1f6fe01b 100644
--- a/apps/web/src/components/settings/settingsSearch.test.ts
+++ b/apps/web/src/components/settings/settingsSearch.test.ts
@@ -99,6 +99,8 @@ describe("searchSettings", () => {
 
   it("hides desktop-only settings from browser search", () => {
     expect(SETTINGS_SEARCH_ITEMS.some((item) => item.id === "quit-confirmation")).toBe(true);
+    expect(SETTINGS_SEARCH_ITEMS.some((item) => item.id === "history-swipe-navigation")).toBe(true);
+    expect(searchSettings("horizontal wheel")).toEqual([]);
     expect(searchSettings("hold to quit")).toEqual([]);
     expect(searchSettings("wsl")).toEqual([]);
     expect(searchSettings("update track")).toEqual([]);
diff --git a/apps/web/src/components/settings/settingsSearch.ts b/apps/web/src/components/settings/settingsSearch.ts
index aabfd0300eda5..98756caac2fa6 100644
--- a/apps/web/src/components/settings/settingsSearch.ts
+++ b/apps/web/src/components/settings/settingsSearch.ts
@@ -668,6 +668,13 @@ export const SETTINGS_SEARCH_ITEMS = [
     searchTerms: ["confirmation desktop app exit direct hold double click press twice"],
     desktopOnly: true,
   },
+  {
+    id: "history-swipe-navigation",
+    title: "Swipe to go back and forward",
+    to: "/settings/general",
+    searchTerms: ["two-finger horizontal trackpad gesture mouse wheel thread history navigation"],
+    desktopOnly: true,
+  },
   {
     id: "text-generation-model",
     title: "Text generation model",
diff --git a/packages/contracts/src/settings.test.ts b/packages/contracts/src/settings.test.ts
index 859644a54c72f..234811b1c60ba 100644
--- a/packages/contracts/src/settings.test.ts
+++ b/packages/contracts/src/settings.test.ts
@@ -303,6 +303,19 @@ describe("ClientSettings quit confirmation", () => {
   });
 });
 
+describe("ClientSettings history swipe navigation", () => {
+  it.each([undefined, true, false])("decodes and round-trips %s", (historySwipeNavigation) => {
+    const input = historySwipeNavigation === undefined ? {} : { historySwipeNavigation };
+    const settings = decodeClientSettings(input);
+
+    expect(settings.historySwipeNavigation).toBe(historySwipeNavigation ?? true);
+    expect(decodeClientSettings(encodeClientSettings(settings)).historySwipeNavigation).toBe(
+      historySwipeNavigation ?? true,
+    );
+    expect(decodeClientSettingsPatch(input)).toEqual(input);
+  });
+});
+
 describe("provider enabled defaults", () => {
   it("resolves instance enabled state with explicit false winning", () => {
     const grok = ProviderDriverKind.make("grok");
diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts
index fff25149b2e3d..569e9b229acd9 100644
--- a/packages/contracts/src/settings.ts
+++ b/packages/contracts/src/settings.ts
@@ -444,6 +444,7 @@ export const ClientSettingsSchema = Schema.Struct({
   fontFamilyTerminal: FontFamilyPreference.pipe(Schema.withDecodingDefault(Effect.succeed(""))),
 
   fontSmoothing: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
+  historySwipeNavigation: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
   // Older installs also decode to null; onboarding must additionally require an empty workspace.
   onboardingCompletedAt: Schema.NullOr(Schema.String).pipe(
     Schema.withDecodingDefault(Effect.succeed(null)),
@@ -1759,6 +1760,7 @@ export const ClientSettingsPatch = Schema.Struct({
   fontFamilySans: Schema.optionalKey(FontFamilyPreference),
   fontFamilyTerminal: Schema.optionalKey(FontFamilyPreference),
   fontSmoothing: Schema.optionalKey(Schema.Boolean),
+  historySwipeNavigation: Schema.optionalKey(Schema.Boolean),
   persistComposerContextStrip: Schema.optionalKey(Schema.Boolean),
   favorites: Schema.optionalKey(ModelFavorites),
   providerModelPreferences: Schema.optionalKey(ProviderModelPreferences),

From 26f57be94177fc6c18814df74882b9a516ffdeb1 Mon Sep 17 00:00:00 2001
From: chomamateusz-agent <chomamateusz-agent@users.noreply.github.com>
Date: Thu, 12 Nov 2026 22:14:19 +0100
Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=92=AC=20feat(web):=20simpler=20swipe?=
 =?UTF-8?q?=20setting=20wording,=20macOS-only=20row,=20docs=20line?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Name the setting "Swipe to navigate" with a shorter description, and add
back/forward to its search terms. The gesture only runs on macOS now, so
show the row and its search entry only there. Mention the gesture and the
switch next to navigation.back/forward in the keybindings guide.
---
 apps/web/src/components/settings/SettingsPanels.tsx | 11 ++++-------
 apps/web/src/components/settings/settingsSearch.ts  |  7 +++++--
 docs/user/keybindings.md                            |  2 ++
 3 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 4e048b57c3db6..01e410dd9609c 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -579,7 +579,7 @@ export function useSettingsRestore(onRestored?: () => void) {
       : []),
     ...(settings.confirmQuit !== DEFAULT_UNIFIED_SETTINGS.confirmQuit ? ["Quit shortcut"] : []),
     ...(settings.historySwipeNavigation !== DEFAULT_UNIFIED_SETTINGS.historySwipeNavigation
-      ? ["Swipe to go back and forward"]
+      ? ["Swipe to navigate"]
       : []),
     ...(isTextGenerationModelDirty ? ["Text generation model"] : []),
     ...(settings.threadTitleInstructions !== DEFAULT_UNIFIED_SETTINGS.threadTitleInstructions
@@ -919,15 +919,12 @@ export function GeneralSettingsPanel() {
         />
       </SettingsSection>
 
-      {isElectron ? (
+      {isElectron && isMacPlatform(navigator.platform) ? (
         <SettingsSection id="navigation" title={gt("Navigation")}>
           <SettingsRow
             {...setting("history-swipe-navigation")}
             description={
-              <T>
-                Two-finger horizontal swipes move through your thread history. Turn off if a mouse
-                with a horizontal wheel switches threads by accident.
-              </T>
+              <T>Swipe horizontally with two fingers on a trackpad to go back or forward.</T>
             }
             resetAction={
               settings.historySwipeNavigation !==
@@ -948,7 +945,7 @@ export function GeneralSettingsPanel() {
                 onCheckedChange={(checked) =>
                   updateSettings({ historySwipeNavigation: Boolean(checked) })
                 }
-                aria-label={gt("Swipe to go back and forward")}
+                aria-label={gt("Swipe to navigate")}
               />
             }
           />
diff --git a/apps/web/src/components/settings/settingsSearch.ts b/apps/web/src/components/settings/settingsSearch.ts
index 552e487102c9b..d3f5764c5c0e7 100644
--- a/apps/web/src/components/settings/settingsSearch.ts
+++ b/apps/web/src/components/settings/settingsSearch.ts
@@ -848,10 +848,13 @@ export const SETTINGS_SEARCH_ITEMS = [
   },
   {
     id: "history-swipe-navigation",
-    title: "Swipe to go back and forward",
+    title: msg("Swipe to navigate"),
     to: "/settings/general",
-    searchTerms: ["two-finger horizontal trackpad gesture mouse wheel thread history navigation"],
+    searchTerms: [
+      "two-finger horizontal trackpad gesture mouse wheel back forward thread history navigation",
+    ],
     desktopOnly: true,
+    macOnly: true,
   },
   {
     id: "text-generation-model",
diff --git a/docs/user/keybindings.md b/docs/user/keybindings.md
index 0449990ee0b2b..cb07154b59d4f 100644
--- a/docs/user/keybindings.md
+++ b/docs/user/keybindings.md
@@ -184,6 +184,8 @@ field gets its own undo back. Terminals always keep their native shortcut.
 
 `navigation.back` (`mod+[` by default) and `navigation.forward` (`mod+]`) move
 through the pages you have visited, like a browser's back and forward buttons.
+In the desktop app on macOS, a two-finger trackpad swipe does the same. Turn it off
+with **Settings → General → Navigation → Swipe to navigate**.
 
 `chat.new` may ask you to choose a project when there is more than one.
 `chat.newLocal` skips that chooser. Both use your