From 63767a3a9784ba9bbda355acd753e60037c156cf Mon Sep 17 00:00:00 2001
From: qwist1233-cpu <qwist1233@gmail.com>
Date: Mon, 19 Oct 2026 11:38:02 +0300
Subject: [PATCH 1/3] fix(settings): give provider model rows their own scroll
 viewport
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A fetched catalog of a few hundred models rendered one page row each, so
the settings page itself became hundreds of rows tall: the model filter
scrolled out of view while browsing, and the advanced request settings
below sat under the whole list.

The rows now scroll inside `min(32rem, 60vh)` of their own, with the
filter, the count and the section buttons left outside. `max-height`
rather than `height`, so a small or filtered-down catalog stands at its
own height; a second `.settingsRows` rather than a bare div, so the rows
keep the `.settingsRows > …` track, hover wash and container query
inside the viewport; `overscroll-behavior` left at `auto`, so a wheel
reaching the end of the list carries on down the page.

Covered by play-function geometry assertions on the 444-model story, a
new 480x800 short-window story, and the two-model story, all of which
fail without this change.

Fixes #6164

Generated-by: Claude Code
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../settings/provider-connection-detail.tsx   |  59 ++++++---
 .../styles/settings/provider-editor.css       |  21 ++++
 .../settings/provider-settings.stories.tsx    | 118 ++++++++++++++++--
 scripts/storybook-visual-smoke.mjs            |   7 ++
 scripts/storybook-visual-smoke.test.mjs       |  17 +++
 5 files changed, 193 insertions(+), 29 deletions(-)

diff --git a/apps/desktop/src/renderer/settings/provider-connection-detail.tsx b/apps/desktop/src/renderer/settings/provider-connection-detail.tsx
index c033a477dcd..3cc79e0b531 100644
--- a/apps/desktop/src/renderer/settings/provider-connection-detail.tsx
+++ b/apps/desktop/src/renderer/settings/provider-connection-detail.tsx
@@ -693,27 +693,46 @@ function ConnectionDetailInner(props: ConnectionDetailProps) {
               label={copy.noModelsMatch}
               end={<Button variant="ghost" size="sm" label={copy.cancel} onClick={() => setModelFilter('')} />}
             />
-          ) : visibleModelRows.map(({ id, entry }) => {
-            const label = entry?.displayName?.trim() || id;
-            const rowLabel = entry?.isDefault ? (
-              <HStack gap={2} vAlign="center">
-                <span>{label}</span>
-                <Badge variant="neutral" label={providerCopy.panel.default} />
-              </HStack>
-            ) : label;
-            return (
-                <SettingsRow key={id} label={rowLabel} end={<>
-                  {/* Astryx tooltips resolve a portal on mount, causing a style recalculation per model row. */}
-                  <span title={copy.declareCapabilities}>
-                    <IconButton variant="ghost" size="sm" icon={<Icon icon="wrench" size="sm" />}
-                      label={copy.declareCapabilitiesAria(label)}
-                      isDisabled={allActionsBusy} onClick={() => openRow({ model: id })} />
-                  </span>
-                  {modelEnableSwitch(id, label)}
-                </>} />
+          ) : (
+            /* The rows get their own viewport so a large catalog stops
+               stretching the page: a provider with hundreds of models used to
+               push the filter above it out of view and bury the advanced
+               request settings below under the whole list. The filter, the
+               model count and the section actions stay outside this element,
+               so they hold still while the rows scroll.
+
+               A second `.settingsRows` rather than a bare div: the row
+               styling in rows.css is written as `.settingsRows > …`, so the
+               rows keep their edge-to-edge track, their hover wash and the
+               460px container query inside the viewport too.
 
-            );
-          })}
+               `max-height` only, so a short or filtered-down list is as tall
+               as its rows instead of reserving an empty box, and no
+               `overscroll-behavior`: a wheel that reaches the end of the list
+               should carry on down the page rather than stop dead. */
+            <div className="settingsRows providerModelRowsViewport">
+              {visibleModelRows.map(({ id, entry }) => {
+                const label = entry?.displayName?.trim() || id;
+                const rowLabel = entry?.isDefault ? (
+                  <HStack gap={2} vAlign="center">
+                    <span>{label}</span>
+                    <Badge variant="neutral" label={providerCopy.panel.default} />
+                  </HStack>
+                ) : label;
+                return (
+                  <SettingsRow key={id} label={rowLabel} end={<>
+                    {/* Astryx tooltips resolve a portal on mount, causing a style recalculation per model row. */}
+                    <span title={copy.declareCapabilities}>
+                      <IconButton variant="ghost" size="sm" icon={<Icon icon="wrench" size="sm" />}
+                        label={copy.declareCapabilitiesAria(label)}
+                        isDisabled={allActionsBusy} onClick={() => openRow({ model: id })} />
+                    </span>
+                    {modelEnableSwitch(id, label)}
+                  </>} />
+                );
+              })}
+            </div>
+          )}
         </SettingsSection>
       )}
       <ModelParametersDialog
diff --git a/apps/desktop/src/renderer/styles/settings/provider-editor.css b/apps/desktop/src/renderer/styles/settings/provider-editor.css
index 5ce447e9a7e..7dd3f48c3fb 100644
--- a/apps/desktop/src/renderer/styles/settings/provider-editor.css
+++ b/apps/desktop/src/renderer/styles/settings/provider-editor.css
@@ -44,6 +44,27 @@
   color: var(--muted-foreground);
 }
 
+/* The model rows of a provider connection, in their own scroll viewport.
+ * Settings → 模型 → a connection expands every chat-capable model into the
+ * page, so a large catalog made the page itself hundreds of rows tall: the
+ * filter scrolled away while browsing, and the advanced request settings
+ * below sat under the whole list.
+ *
+ * `max-height`, not `height`: a small catalog, a filtered-down list and the
+ * empty-result row are as tall as their content, with no blank box reserved
+ * under them. The bound tracks the window — 60vh keeps the surrounding
+ * section visible in a short window, and the 32rem cap stops the list from
+ * eating a tall one.
+ *
+ * `overscroll-behavior` is deliberately left at `auto`: once the list is
+ * scrolled to its end the wheel carries on down the settings page, so the
+ * viewport cannot swallow the gesture of a user heading for the sections
+ * below it. */
+.providerModelRowsViewport {
+  max-height: min(32rem, 60vh);
+  overflow-y: auto;
+}
+
 .providerEndpointField {
   display: grid;
   gap: 6px;
diff --git a/apps/desktop/stories/settings/provider-settings.stories.tsx b/apps/desktop/stories/settings/provider-settings.stories.tsx
index b16e0985181..2186418b90c 100644
--- a/apps/desktop/stories/settings/provider-settings.stories.tsx
+++ b/apps/desktop/stories/settings/provider-settings.stories.tsx
@@ -816,6 +816,21 @@ export const ConnectionDetailPage: Story = {
       autoOpen="detail"
     />
   ),
+  // The same viewport with a two-model catalog, the common case: the bound is a
+  // maximum, so the rows stand at their own height with no scrollbar and no
+  // empty box under them, and the filter stays absent below its threshold.
+  play: async ({ canvasElement }) => {
+    const viewport = await waitFor(() => {
+      const found = canvasElement.querySelector<HTMLElement>('.providerModelRowsViewport');
+      expect(found).not.toBeNull();
+      expect(found!.childElementCount).toBe(2);
+      return found!;
+    });
+    expect(viewport.scrollHeight).toBe(viewport.clientHeight);
+    expect(viewport.clientHeight).toBeLessThan(modelRowsHeightBound());
+    expect(within(canvasElement).queryByPlaceholderText(detailCopy.filterModels)).toBeNull();
+    expect(within(canvasElement).getByText('GLM 4.7')).toBeTruthy();
+  },
 };
 
 // Real path: after upgrading, open the retained OpenCode Free connection in Settings.
@@ -837,6 +852,64 @@ export const RetiredFreeConnection: Story = {
   },
 };
 
+/** The model rows' own scroll viewport, once the fixture catalog has rendered. */
+async function reachModelRowsViewport(canvasElement: HTMLElement, rows: number): Promise<HTMLElement> {
+  await waitFor(() => {
+    expect(canvasElement.querySelectorAll('button[aria-label*="Fixture model"]').length).toBe(rows);
+  }, { timeout: 20_000 });
+  const viewport = canvasElement.querySelector<HTMLElement>('.providerModelRowsViewport');
+  expect(viewport).not.toBeNull();
+  return viewport!;
+}
+
+/** The bound the viewport's CSS asks for, in this window. Read rather than
+ *  hard-coded at 512: the cap is in rem, so a user's text size moves it. */
+function modelRowsHeightBound(): number {
+  const rem = Number.parseFloat(getComputedStyle(document.documentElement).fontSize);
+  return Math.min(32 * rem, window.innerHeight * 0.6);
+}
+
+/** What the model rows are measured against: the settings pane is the page's
+ *  scroll owner (nav-sidebar.css), and the list used to stretch it. */
+function settingsPane(canvasElement: HTMLElement): HTMLElement {
+  const pane = canvasElement.querySelector<HTMLElement>('.settingsMainPane');
+  expect(pane).not.toBeNull();
+  return pane!;
+}
+
+/** The rows scroll inside their viewport, nothing is clipped at its edges, and
+ *  the controls around the list stay out of it. Shared by the standard and the
+ *  short-window runs, which differ only in how much height the bound leaves. */
+function expectBoundedModelRows(canvasElement: HTMLElement, viewport: HTMLElement) {
+  // Bounded, and bounded against the window: in a short window 60vh wins over
+  // the 32rem cap, so the sections around the list stay on screen.
+  expect(viewport.clientHeight).toBeLessThanOrEqual(Math.ceil(modelRowsHeightBound()) + 1);
+  // The list owns its overflow instead of handing it to the page.
+  expect(viewport.scrollHeight).toBeGreaterThan(viewport.clientHeight);
+  expect(settingsPane(canvasElement).scrollHeight).toBeLessThan(viewport.scrollHeight);
+
+  // Nothing pokes out sideways, at any window width.
+  expect(viewport.scrollWidth).toBeLessThanOrEqual(viewport.clientWidth + 1);
+
+  // The search box and the section's own buttons are not carried along by the
+  // rows — they are siblings of the viewport, not children of it.
+  expect(viewport.contains(within(canvasElement).getByPlaceholderText(detailCopy.filterModels))).toBe(false);
+  expect(viewport.contains(within(canvasElement).getByRole('button', { name: detailCopy.addModel }))).toBe(false);
+
+  // The last row is reachable and whole: scrolled to the end, its bottom edge
+  // sits inside the viewport rather than under its lower border.
+  viewport.scrollTop = viewport.scrollHeight;
+  expect(viewport.scrollTop).toBeGreaterThan(0);
+  const lastRow = viewport.lastElementChild as HTMLElement | null;
+  expect(lastRow).not.toBeNull();
+  expect(lastRow!.getBoundingClientRect().bottom)
+    .toBeLessThanOrEqual(viewport.getBoundingClientRect().bottom + 1);
+
+  // The settings below the list are a short scroll away rather than 444 rows
+  // away: the whole page is now shorter than the catalog it contains.
+  expect(within(canvasElement).getByText(detailCopy.advancedRequest)).toBeTruthy();
+}
+
 // Real path: 设置 → 模型 → an OpenRouter connection after fetching hundreds of models.
 // The fetched snapshot is local; browsing it never needs an API key.
 export const LargeConnectionDetail: Story = {
@@ -847,9 +920,9 @@ export const LargeConnectionDetail: Story = {
     />
   ),
   play: async ({ canvasElement }) => {
-    await waitFor(() => {
-      expect(canvasElement.querySelectorAll('button[aria-label*="Fixture model"]').length).toBe(444);
-    }, { timeout: 20_000 });
+    const viewport = await reachModelRowsViewport(canvasElement, 444);
+    expectBoundedModelRows(canvasElement, viewport);
+
     const canvas = within(canvasElement);
     const second = canvas.getByRole('switch', { name: /Fixture model 002$/ });
     const third = canvas.getByRole('switch', { name: /Fixture model 003$/ });
@@ -860,19 +933,46 @@ export const LargeConnectionDetail: Story = {
     const bar = canvasElement.querySelector<HTMLElement>('.providerModelsSaveBar')!;
     const save = within(bar).getByRole('button', { name: /^(保存|儲存|Save)$/ });
     expect(save).toBeEnabled();
-    const pane = canvasElement.querySelector<HTMLElement>('.settingsMainPane')!;
-    // The production pane is the sole scroll owner. Save stays on screen at
-    // the top, middle and end of a hundreds-of-models catalog.
+    const pane = settingsPane(canvasElement);
+    // Save stays on screen at the top, middle and end of the page. With the
+    // rows in their own viewport the page is short enough that there is little
+    // left to scroll, which is the point: the bar was being pushed away by the
+    // list, not by the page.
     for (const top of [0, pane.scrollHeight / 2, pane.scrollHeight]) {
       pane.scrollTop = top;
       await waitFor(() => {
         const rect = bar.getBoundingClientRect();
-        const viewport = pane.getBoundingClientRect();
-        expect(rect.top).toBeGreaterThanOrEqual(viewport.top);
-        expect(rect.bottom).toBeLessThanOrEqual(viewport.bottom + 1);
+        const paneRect = pane.getBoundingClientRect();
+        expect(rect.top).toBeGreaterThanOrEqual(paneRect.top);
+        expect(rect.bottom).toBeLessThanOrEqual(paneRect.bottom + 1);
         expect(rect.height).toBeGreaterThan(0);
       });
     }
+
+    // Filtering down to a handful of models leaves no empty box below them:
+    // the bound is a maximum, so a short list is as tall as its own rows.
+    const filter = canvas.getByPlaceholderText(detailCopy.filterModels);
+    filter.focus();
+    await userEvent.paste('model-04');
+    await waitFor(() => {
+      expect(canvasElement.querySelectorAll('button[aria-label*="Fixture model"]').length).toBe(10);
+    }, { timeout: 10_000 });
+    expect(viewport.scrollHeight).toBe(viewport.clientHeight);
+    expect(viewport.clientHeight).toBeLessThan(modelRowsHeightBound());
+  },
+};
+
+// The same catalog in a short, narrow window — the case the bound exists for.
+// The smoke run gives this story a 480 × 800 viewport (storybook-visual-smoke).
+export const LargeConnectionDetailShortWindow: Story = {
+  render: () => (
+    <ProviderStory
+      bridge={createBridge({ connections: [largeConnection], defaultSlug: 'openrouter-large' })}
+      autoOpen="detail-large"
+    />
+  ),
+  play: async ({ canvasElement }) => {
+    expectBoundedModelRows(canvasElement, await reachModelRowsViewport(canvasElement, 444));
   },
 };
 
diff --git a/scripts/storybook-visual-smoke.mjs b/scripts/storybook-visual-smoke.mjs
index b678020eeda..15fa9a6ac03 100644
--- a/scripts/storybook-visual-smoke.mjs
+++ b/scripts/storybook-visual-smoke.mjs
@@ -240,6 +240,13 @@ export function storyViewport(storyId) {
   // The progress card also uses viewport-relative picker sizing inside its
   // native 360px WebContents; a narrow wrapper alone does not reproduce that.
   if (storyId === 'product-workhub--progress-model-picker') return { width: 360, height: 900 };
+  // A short, narrow window is the case the model-row viewport's 60vh bound
+  // exists for: at 900px tall the 32rem cap wins instead, and the story would
+  // never exercise the branch that keeps the settings around the list on
+  // screen. Narrow as well, so the rows' container query runs here too.
+  if (storyId === 'product-settings-providers--large-connection-detail-short-window') {
+    return { width: 480, height: 800 };
+  }
   return storyId.includes('narrow') ? NARROW_RENDER_VIEWPORT : RENDER_VIEWPORT;
 }
 
diff --git a/scripts/storybook-visual-smoke.test.mjs b/scripts/storybook-visual-smoke.test.mjs
index 07dc07183dd..fa484e8b9cf 100644
--- a/scripts/storybook-visual-smoke.test.mjs
+++ b/scripts/storybook-visual-smoke.test.mjs
@@ -27,6 +27,7 @@ import {
   jobLabel,
   rescuedRenderSummary,
   storyUrl,
+  storyViewport,
 } from './storybook-visual-smoke.mjs';
 
 const REFERENCE_STORY_ID = 'product-shell-official-appshell--native-conversation';
@@ -278,3 +279,19 @@ test('WorkHub suggestion geometry runs at both widths in both themes', () => {
     ],
   );
 });
+
+test('the provider model-row viewport story runs in a short window', () => {
+  const shortWindow = storyViewport(
+    'product-settings-providers--large-connection-detail-short-window',
+  );
+  assert.deepEqual(shortWindow, { width: 480, height: 800 });
+  // The height is what the story is for: the rows are capped at
+  // min(32rem, 60vh), and only under ~853px tall does 60vh become the
+  // smaller of the two. At the default 900px the cap would win and the
+  // story would assert the same thing twice.
+  assert.ok(shortWindow.height * 0.6 < 32 * 16);
+  assert.deepEqual(storyViewport('product-settings-providers--large-connection-detail'), {
+    width: 1280,
+    height: 900,
+  });
+});

From edc83c70051f53bdfcef2099e4a5855d189eab83 Mon Sep 17 00:00:00 2001
From: qwist1233-cpu <qwist1233@gmail.com>
Date: Wed, 21 Oct 2026 11:24:45 +0300
Subject: [PATCH 2/3] fix(settings): keep model row focus inside the viewport
 and clear of the Save bar

The rows viewport clipped the trailing switch's focus ring, and the sticky
Save bar could cover a row the keyboard had just focused. The viewport now
bleeds its own padding back out so the ring has room inside the clip, and the
settings pane reserves the bar's measured height as scroll padding.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../settings/provider-connection-detail.tsx   | 35 ++++++++-
 .../styles/settings/provider-editor.css       | 21 ++++++
 .../settings/provider-settings.stories.tsx    | 72 ++++++++++++++++++-
 3 files changed, 123 insertions(+), 5 deletions(-)

diff --git a/apps/desktop/src/renderer/settings/provider-connection-detail.tsx b/apps/desktop/src/renderer/settings/provider-connection-detail.tsx
index 3cc79e0b531..9dd4a5d587c 100644
--- a/apps/desktop/src/renderer/settings/provider-connection-detail.tsx
+++ b/apps/desktop/src/renderer/settings/provider-connection-detail.tsx
@@ -17,7 +17,7 @@
  * under the License.
  */
 
-import { useEffect, useState } from 'react';
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
 import {
   Badge,
   Banner,
@@ -154,6 +154,36 @@ type EditingRow =
   | 'add-model'
   | null;
 
+/** Publishes the sticky Save bar's height to the settings pane, which spends
+ *  it as `scroll-padding-block-end` (provider-editor.css).
+ *
+ *  The bar hangs over the bottom of the pane, and the model rows scroll in a
+ *  viewport of their own: tabbing from one row's control to the next scrolls
+ *  that viewport, and no amount of scrolling inside it can move a row out from
+ *  under a bar stuck to the pane. With the padding in place the pane itself
+ *  scrolls the focused control clear of the bar. Measured rather than tokenized
+ *  because the bar wraps at narrow widths, the same way the composer dock's
+ *  clearance is measured in `use-focused-preview.ts`. */
+function useSaveBarScrollClearance(enabled: boolean) {
+  const barRef = useRef<HTMLDivElement>(null);
+  useLayoutEffect(() => {
+    const bar = barRef.current;
+    const pane = bar?.closest<HTMLElement>('.settingsMainPane');
+    if (!bar || !pane) return;
+    const measure = () => {
+      pane.style.setProperty('--provider-models-save-bar-space', `${Math.ceil(bar.getBoundingClientRect().height)}px`);
+    };
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(bar);
+    return () => {
+      observer.disconnect();
+      pane.style.removeProperty('--provider-models-save-bar-space');
+    };
+  }, [enabled]);
+  return barRef;
+}
+
 function ConnectionDetailInner(props: ConnectionDetailProps) {
   const reportHostError = useRuntimeHostSettingsErrorReporter();
   const locale = useUiLocale();
@@ -208,6 +238,7 @@ function ConnectionDetailInner(props: ConnectionDetailProps) {
     remove,
     refreshAfterRelogin,
   } = useConnectionDetail(props);
+  const saveBarRef = useSaveBarScrollClearance(retired);
   const entryById = new Map(modelChoices.map((entry) => [entry.id, entry]));
   // One row is a form at a time, the way the settings-sidebar template does it.
   // Opening a row discards the other's draft: leaving an abandoned draft in
@@ -871,7 +902,7 @@ function ConnectionDetailInner(props: ConnectionDetailProps) {
         </SettingsActions>
       </SettingsSection>
       {!retired && (
-        <div className="providerModelsSaveBar" role="group" aria-label={copy.modelSelection}>
+        <div ref={saveBarRef} className="providerModelsSaveBar" role="group" aria-label={copy.modelSelection}>
           <span role="status">{hasEnabledModelChanges ? copy.modelsUnsaved : copy.modelsSaved}</span>
           <HStack gap={2}>
             <Button variant="secondary" label={copy.cancel} isDisabled={!hasEnabledModelChanges || allActionsBusy}
diff --git a/apps/desktop/src/renderer/styles/settings/provider-editor.css b/apps/desktop/src/renderer/styles/settings/provider-editor.css
index 7dd3f48c3fb..378528a7546 100644
--- a/apps/desktop/src/renderer/styles/settings/provider-editor.css
+++ b/apps/desktop/src/renderer/styles/settings/provider-editor.css
@@ -63,6 +63,16 @@
 .providerModelRowsViewport {
   max-height: min(32rem, 60vh);
   overflow-y: auto;
+  /* A scroll container clips at its padding edge, and model rows run flush
+   * with it: `rows.css` takes their inline padding away so the row track
+   * reaches the section's edges. Anything a row paints outside its own box —
+   * the keyboard focus ring of the trailing Switch (`--focus-ring-offset` out,
+   * `--focus-ring-width` wide), the hover wash a clickable row steps out by —
+   * would be cut by the new boundary. The viewport steps out by that same
+   * `--space-2` and takes it straight back as padding, so the rows keep the
+   * edges they had and everything painted around them stays inside the clip. */
+  margin: calc(-1 * var(--space-2));
+  padding: var(--space-2);
 }
 
 .providerEndpointField {
@@ -110,6 +120,17 @@
   accent-color: var(--primary);
 }
 
+/* The pane spends the Save bar's measured height as scroll padding, so a
+   control the keyboard reaches is scrolled clear of the bar instead of under
+   it. Needed since the model rows scroll in a viewport of their own: focus
+   moving down the list scrolls that viewport, which cannot move a row out from
+   beneath a bar stuck to the pane. The height is published by
+   `provider-connection-detail.tsx`; without it the padding is nothing, so the
+   other settings pages are untouched. */
+.settingsMainPane {
+  scroll-padding-block-end: var(--provider-models-save-bar-space, 0px);
+}
+
 /* The settings pane remains the only scroll owner. Sticky bottom keeps Save
    reachable even when the model catalog extends far below the viewport. */
 .providerModelsSaveBar {
diff --git a/apps/desktop/stories/settings/provider-settings.stories.tsx b/apps/desktop/stories/settings/provider-settings.stories.tsx
index 2186418b90c..f3cec5ec3b4 100644
--- a/apps/desktop/stories/settings/provider-settings.stories.tsx
+++ b/apps/desktop/stories/settings/provider-settings.stories.tsx
@@ -877,10 +877,74 @@ function settingsPane(canvasElement: HTMLElement): HTMLElement {
   return pane!;
 }
 
+/** How far a focus ring is painted outside the control it belongs to: the ring
+ *  recipe is two tokens (maka-tokens.css), read from the element rather than
+ *  hard-coded so a retune of the recipe moves this bound with it. */
+function focusRingBleed(element: HTMLElement): number {
+  const style = getComputedStyle(element);
+  const token = (name: string, fallback: number) => {
+    const value = Number.parseFloat(style.getPropertyValue(name));
+    return Number.isFinite(value) ? value : fallback;
+  };
+  return token('--focus-ring-width', 2) + token('--focus-ring-offset', 2);
+}
+
+/** The keyboard's view of the list, which the viewport could have broken in two
+ *  ways: a scroll container clips at its padding edge, and the Save bar is
+ *  stuck over the bottom of the pane. Both are about a control the keyboard
+ *  reaches, so neither is covered by the scroll-width and row-bottom geometry
+ *  above (#6164 review). */
+async function expectLastRowControlFullyVisible(canvasElement: HTMLElement, viewport: HTMLElement) {
+  viewport.scrollTop = viewport.scrollHeight;
+  const switches = viewport.querySelectorAll<HTMLElement>('[role="switch"]');
+  const last = switches[switches.length - 1];
+  expect(last).toBeTruthy();
+
+  // 1. The ring of the trailing control fits inside the clipping boundary:
+  // the rows run flush with the viewport's edges, so without room reserved for
+  // it the outward ring is cut off on the right.
+  const bleed = focusRingBleed(last);
+  expect(bleed).toBeGreaterThan(0);
+  const clip = viewport.getBoundingClientRect();
+  const control = last.getBoundingClientRect();
+  expect(control.right + bleed).toBeLessThanOrEqual(clip.right + 0.5);
+  expect(control.left - bleed).toBeGreaterThanOrEqual(clip.left - 0.5);
+  expect(control.bottom + bleed).toBeLessThanOrEqual(clip.bottom + 0.5);
+
+  // 2. Focus lands clear of the sticky Save bar, wherever the page itself is
+  // scrolled. The bar hangs over the bottom of the pane, and no amount of
+  // scrolling inside the viewport can move a row out from under it, so the
+  // pane holds the bar's height as scroll padding and scrolls itself.
+  const bar = canvasElement.querySelector<HTMLElement>('.providerModelsSaveBar');
+  expect(bar).not.toBeNull();
+  const pane = settingsPane(canvasElement);
+  const paneRange = pane.scrollHeight - pane.clientHeight;
+  for (let step = 0; step <= 10; step += 1) {
+    pane.scrollTop = (paneRange * step) / 10;
+    viewport.scrollTop = viewport.scrollHeight;
+    const trailing = viewport.querySelectorAll<HTMLElement>('[role="switch"]');
+    const control = trailing[trailing.length - 1];
+    // Refocusing the already-focused control would scroll nothing, so the
+    // focus has to leave the list between positions.
+    (document.activeElement as HTMLElement | null)?.blur();
+    control.focus();
+    await waitFor(() => {
+      const focused = control.getBoundingClientRect();
+      const covered = bar!.getBoundingClientRect();
+      expect(focused.bottom <= covered.top + 1 || focused.top >= covered.bottom - 1).toBe(true);
+      const hit = document.elementFromPoint(
+        Math.round(focused.left + focused.width / 2),
+        Math.round(focused.top + focused.height / 2),
+      );
+      expect(hit !== null && bar!.contains(hit)).toBe(false);
+    });
+  }
+}
+
 /** The rows scroll inside their viewport, nothing is clipped at its edges, and
  *  the controls around the list stay out of it. Shared by the standard and the
  *  short-window runs, which differ only in how much height the bound leaves. */
-function expectBoundedModelRows(canvasElement: HTMLElement, viewport: HTMLElement) {
+async function expectBoundedModelRows(canvasElement: HTMLElement, viewport: HTMLElement) {
   // Bounded, and bounded against the window: in a short window 60vh wins over
   // the 32rem cap, so the sections around the list stay on screen.
   expect(viewport.clientHeight).toBeLessThanOrEqual(Math.ceil(modelRowsHeightBound()) + 1);
@@ -908,6 +972,8 @@ function expectBoundedModelRows(canvasElement: HTMLElement, viewport: HTMLElemen
   // The settings below the list are a short scroll away rather than 444 rows
   // away: the whole page is now shorter than the catalog it contains.
   expect(within(canvasElement).getByText(detailCopy.advancedRequest)).toBeTruthy();
+
+  await expectLastRowControlFullyVisible(canvasElement, viewport);
 }
 
 // Real path: 设置 → 模型 → an OpenRouter connection after fetching hundreds of models.
@@ -921,7 +987,7 @@ export const LargeConnectionDetail: Story = {
   ),
   play: async ({ canvasElement }) => {
     const viewport = await reachModelRowsViewport(canvasElement, 444);
-    expectBoundedModelRows(canvasElement, viewport);
+    await expectBoundedModelRows(canvasElement, viewport);
 
     const canvas = within(canvasElement);
     const second = canvas.getByRole('switch', { name: /Fixture model 002$/ });
@@ -972,7 +1038,7 @@ export const LargeConnectionDetailShortWindow: Story = {
     />
   ),
   play: async ({ canvasElement }) => {
-    expectBoundedModelRows(canvasElement, await reachModelRowsViewport(canvasElement, 444));
+    await expectBoundedModelRows(canvasElement, await reachModelRowsViewport(canvasElement, 444));
   },
 };
 

From f593196304259241e46bcc872ce13861eb35fd80 Mon Sep 17 00:00:00 2001
From: qwist1233-cpu <qwist1233@gmail.com>
Date: Thu, 22 Oct 2026 11:20:52 +0300
Subject: [PATCH 3/3] fix(settings): move the Save bar measurement out of
 recorded renderer debt

The clearance was published from a `useLayoutEffect` inside the connection
detail view, which is recorded AppShell-closure debt: its hook calls and
environment capabilities are frozen, so `check:architecture` failed on the
added `useLayoutEffect`, `useRef` and `ResizeObserver`.

The measurement is a `connection-settings` concern, not the view's, so it
moves there as a ref callback. The view gains no hook call and no capability
of its own, and the feature's public entry is already a sanctioned dependency
for it, so the ledger is unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../features/connection-settings/index.ts     |  2 +
 .../models-save-bar-clearance.ts              | 54 +++++++++++++++++++
 .../settings/provider-connection-detail.tsx   | 37 ++-----------
 .../styles/settings/provider-editor.css       |  4 +-
 4 files changed, 61 insertions(+), 36 deletions(-)
 create mode 100644 apps/desktop/src/renderer/features/connection-settings/models-save-bar-clearance.ts

diff --git a/apps/desktop/src/renderer/features/connection-settings/index.ts b/apps/desktop/src/renderer/features/connection-settings/index.ts
index 40377bfbd09..8e53af75d72 100644
--- a/apps/desktop/src/renderer/features/connection-settings/index.ts
+++ b/apps/desktop/src/renderer/features/connection-settings/index.ts
@@ -51,3 +51,5 @@ export { AddModelDialog, ModelParametersDialog } from './provider-add-model-dial
 export { ProviderEndpointField } from './provider-endpoint-field.js';
 
 export { ConnectionDefaultAction } from './connection-default-action.js';
+
+export { attachModelsSaveBarClearance } from './models-save-bar-clearance.js';
diff --git a/apps/desktop/src/renderer/features/connection-settings/models-save-bar-clearance.ts b/apps/desktop/src/renderer/features/connection-settings/models-save-bar-clearance.ts
new file mode 100644
index 00000000000..d06ef0b3b63
--- /dev/null
+++ b/apps/desktop/src/renderer/features/connection-settings/models-save-bar-clearance.ts
@@ -0,0 +1,54 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+
+/** The settings pane spends this as `scroll-padding-block-end`, so a control
+ *  the keyboard reaches is scrolled clear of the sticky Save bar instead of
+ *  under it (`styles/settings/provider-editor.css`). */
+const CLEARANCE_PROPERTY = '--provider-models-save-bar-space';
+const PANE_SELECTOR = '.settingsMainPane';
+
+/** Ref callback for the model Save bar: publishes the bar's height to the
+ *  settings pane it is stuck to.
+ *
+ *  The bar hangs over the bottom of the pane, and the model rows scroll in a
+ *  viewport of their own: tabbing from one row's control to the next scrolls
+ *  that viewport, and no amount of scrolling inside it can move a row out from
+ *  under a bar stuck to the pane. With the clearance published the pane itself
+ *  scrolls the focused control above the bar. The height is measured rather
+ *  than tokenized because the bar wraps at narrow widths, the way the
+ *  composer dock's clearance is measured in `use-focused-preview.ts`.
+ *
+ *  A ref callback rather than a hook: the detail view that renders the bar is
+ *  recorded renderer debt whose hook and capability budgets are frozen, so the
+ *  measurement belongs to this feature instead. */
+export function attachModelsSaveBarClearance(bar: HTMLElement | null) {
+  const pane = bar?.closest<HTMLElement>(PANE_SELECTOR);
+  if (!bar || !pane) return;
+  const measure = () => {
+    pane.style.setProperty(CLEARANCE_PROPERTY, `${Math.ceil(bar.getBoundingClientRect().height)}px`);
+  };
+  measure();
+  const observer = new ResizeObserver(measure);
+  observer.observe(bar);
+  return () => {
+    observer.disconnect();
+    pane.style.removeProperty(CLEARANCE_PROPERTY);
+  };
+}
diff --git a/apps/desktop/src/renderer/settings/provider-connection-detail.tsx b/apps/desktop/src/renderer/settings/provider-connection-detail.tsx
index 9dd4a5d587c..d529bdc4030 100644
--- a/apps/desktop/src/renderer/settings/provider-connection-detail.tsx
+++ b/apps/desktop/src/renderer/settings/provider-connection-detail.tsx
@@ -17,7 +17,7 @@
  * under the License.
  */
 
-import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { useEffect, useState } from 'react';
 import {
   Badge,
   Banner,
@@ -49,7 +49,7 @@ import { PasswordInput } from './password-input';
 import { SettingsExpandableRow } from './settings-expandable-row';
 import { SettingsActions, SettingsRow, SettingsSection } from './settings-section';
 import { providerDisplay } from './provider-display';
-import { CapabilityEditor, AddModelDialog, ModelParametersDialog } from '../features/connection-settings';
+import { CapabilityEditor, AddModelDialog, ModelParametersDialog, attachModelsSaveBarClearance } from '../features/connection-settings';
 import {
   RuntimeHostSettingsGenerationBoundary,
   useRuntimeHostSettingsErrorReporter,
@@ -154,36 +154,6 @@ type EditingRow =
   | 'add-model'
   | null;
 
-/** Publishes the sticky Save bar's height to the settings pane, which spends
- *  it as `scroll-padding-block-end` (provider-editor.css).
- *
- *  The bar hangs over the bottom of the pane, and the model rows scroll in a
- *  viewport of their own: tabbing from one row's control to the next scrolls
- *  that viewport, and no amount of scrolling inside it can move a row out from
- *  under a bar stuck to the pane. With the padding in place the pane itself
- *  scrolls the focused control clear of the bar. Measured rather than tokenized
- *  because the bar wraps at narrow widths, the same way the composer dock's
- *  clearance is measured in `use-focused-preview.ts`. */
-function useSaveBarScrollClearance(enabled: boolean) {
-  const barRef = useRef<HTMLDivElement>(null);
-  useLayoutEffect(() => {
-    const bar = barRef.current;
-    const pane = bar?.closest<HTMLElement>('.settingsMainPane');
-    if (!bar || !pane) return;
-    const measure = () => {
-      pane.style.setProperty('--provider-models-save-bar-space', `${Math.ceil(bar.getBoundingClientRect().height)}px`);
-    };
-    measure();
-    const observer = new ResizeObserver(measure);
-    observer.observe(bar);
-    return () => {
-      observer.disconnect();
-      pane.style.removeProperty('--provider-models-save-bar-space');
-    };
-  }, [enabled]);
-  return barRef;
-}
-
 function ConnectionDetailInner(props: ConnectionDetailProps) {
   const reportHostError = useRuntimeHostSettingsErrorReporter();
   const locale = useUiLocale();
@@ -238,7 +208,6 @@ function ConnectionDetailInner(props: ConnectionDetailProps) {
     remove,
     refreshAfterRelogin,
   } = useConnectionDetail(props);
-  const saveBarRef = useSaveBarScrollClearance(retired);
   const entryById = new Map(modelChoices.map((entry) => [entry.id, entry]));
   // One row is a form at a time, the way the settings-sidebar template does it.
   // Opening a row discards the other's draft: leaving an abandoned draft in
@@ -902,7 +871,7 @@ function ConnectionDetailInner(props: ConnectionDetailProps) {
         </SettingsActions>
       </SettingsSection>
       {!retired && (
-        <div ref={saveBarRef} className="providerModelsSaveBar" role="group" aria-label={copy.modelSelection}>
+        <div ref={attachModelsSaveBarClearance} className="providerModelsSaveBar" role="group" aria-label={copy.modelSelection}>
           <span role="status">{hasEnabledModelChanges ? copy.modelsUnsaved : copy.modelsSaved}</span>
           <HStack gap={2}>
             <Button variant="secondary" label={copy.cancel} isDisabled={!hasEnabledModelChanges || allActionsBusy}
diff --git a/apps/desktop/src/renderer/styles/settings/provider-editor.css b/apps/desktop/src/renderer/styles/settings/provider-editor.css
index 378528a7546..68051cf2147 100644
--- a/apps/desktop/src/renderer/styles/settings/provider-editor.css
+++ b/apps/desktop/src/renderer/styles/settings/provider-editor.css
@@ -125,8 +125,8 @@
    it. Needed since the model rows scroll in a viewport of their own: focus
    moving down the list scrolls that viewport, which cannot move a row out from
    beneath a bar stuck to the pane. The height is published by
-   `provider-connection-detail.tsx`; without it the padding is nothing, so the
-   other settings pages are untouched. */
+   `features/connection-settings/models-save-bar-clearance.ts`; where it is absent
+   the padding is nothing, so the other settings pages are untouched. */
 .settingsMainPane {
   scroll-padding-block-end: var(--provider-models-save-bar-space, 0px);
 }