Settings window layout

[Zihao-Qi]

Summary

This PR improves the Settings window layout and sidebar behavior.

• Replaces the unstable resizable NavigationSplitView sidebar with a fixed-width custom layout.
• Keeps the sidebar visible and non-draggable, so it can no longer collapse, disappear, or become extremely wide.
• Polishes the sidebar visual treatment with a rounded translucent panel, lighter/darker wash for light and dark mode, and adjusted spacing.
• Keeps the detail content constrained so settings rows do not stretch awkwardly across the full window.
• Preserves normal window resizing: an 800-point minimum, the 880-point default, and wider layouts all keep the sidebar stable while the detail column stays readable.
• Reduces unnecessary window appearance refresh work when only the selected pane title changes.

Why

The previous Settings window used SwiftUI NavigationSplitView, but the underlying split divider was still draggable. That caused two bad states:

• dragging left could collapse the sidebar until it disappeared
• dragging right could make the sidebar much wider than intended

Trying to repair this from AppKit was fragile because SwiftUI still owned the split layout. A fixed custom layout better matches the intended behavior: a stable System Settings-style sidebar that is always visible and not user-resizable.

The visual updates make the sidebar feel closer to macOS Settings while keeping the existing app structure and behavior.

Validation

Ran:

• swift test --filter SettingsWindowAppearanceTests
• make check
• git diff --check
• exact release bundle: resized live to 800×572, 880×652, and 1500×900; verified the sidebar remains fixed, the detail column remains capped, and the minimum layout scrolls instead of clipping controls

Screenshots

Before

Issue	Screenshot
Dragging left could collapse the sidebar until it disappeared.
Dragging right could make the sidebar much wider than intended.

after

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 4, 2026, 8:31 PM ET / 00:31 UTC.

Summary
The branch replaces the Settings NavigationSplitView with a custom fixed-width sidebar layout, caps the detail column, preserves window resizing, hides grouped form backgrounds, and updates Settings window tests.

Reproducibility: yes. Current main still uses the resizable NavigationSplitView path, and the PR screenshots show the collapsed and over-wide sidebar states; I did not launch the macOS bundle in this read-only review.

Review metrics: 2 noteworthy metrics.

• Changed surface: 9 files, +177/-96. The diff is focused on Settings layout, appearance, and one focused test file.
• Review continuity: 2 prior no-finding cycles; head unchanged at c979cdd. This pass is a re-review of the same head, so previous no-finding context still applies.

Root-cause cluster
Relationship: canonical
Canonical: #1901
Summary: This PR is the canonical open item for replacing the Settings split view with a fixed sidebar; earlier recovery PRs overlap the collapsed-sidebar symptom but do not fully replace this custom-layout change.

Members:

• partial_overlap: Fix Settings sidebar recovery #1871 - The merged recovery PR repairs collapsed persisted NavigationSplitView frames but leaves the resizable split-view design in place.
• superseded: Fix settings sidebar recovery #1865 - The closed contributor PR proposed collapsed-sidebar recovery and was superseded by the merged owner-authored recovery PR.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster ✨ media proof bonus
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• none.

Mantis proof suggestion
A short native UI proof would materially demonstrate that resizing and attempted divider dragging keep the Settings sidebar fixed. A maintainer can ask Mantis to capture proof by posting this exact PR comment:

@openclaw-mantis visual task: verify CodexBar Settings keeps the sidebar fixed and readable while resizing and attempting to drag the former split divider.

Risk before merge

• [P1] The GitHub status snapshot still had macOS test shards queued, so merge should wait for the normal required checks on c979cdd.

Maintainer options:

1. Decide the mitigation before merge
   Land the PR after required checks and maintainer visual review confirm the fixed, resizable Settings sidebar behavior.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• No repair lane is needed because no concrete patch defect remains; normal maintainer review and required checks can gate this open PR.

Security
Cleared: Security review cleared: the diff is limited to SwiftUI/AppKit Settings layout code and focused tests, with no dependency, workflow, secret, or supply-chain changes.

Review details

Best possible solution:

Land the PR after required checks and maintainer visual review confirm the fixed, resizable Settings sidebar behavior.

Do we have a high-confidence way to reproduce the issue?

Yes. Current main still uses the resizable NavigationSplitView path, and the PR screenshots show the collapsed and over-wide sidebar states; I did not launch the macOS bundle in this read-only review.

Is this the best way to solve the issue?

Yes. Replacing the split view with a fixed custom sidebar directly removes the draggable divider, and the latest maintainer commits address the detail-width and resizing follow-ups.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against e677087a1b1e.

Label changes

Label justifications:

• P3: This is a low-blast-radius Settings window layout and ergonomics fix with sufficient screenshot proof and no blocking correctness finding.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (screenshot): The PR body includes before screenshots of the bad sidebar states and an after screenshot showing the fixed Settings layout, which is sufficient visual proof for this UI layout change.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes before screenshots of the bad sidebar states and an after screenshot showing the fixed Settings layout, which is sufficient visual proof for this UI layout change.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The PR body includes before screenshots of the bad sidebar states and an after screenshot showing the fixed Settings layout, which is sufficient visual proof for this UI layout change.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully and its Settings/testing guidance was applied; no matching maintainer notes directory was present. (AGENTS.md:1, e677087a1b1e)
• Current main baseline: Current main still builds Settings with NavigationSplitView and fixed column-width hints, so the non-draggable custom sidebar is not already on main. (Sources/CodexBar/PreferencesView.swift:69, e677087a1b1e)
• PR head implementation: The PR head replaces NavigationSplitView with an HStack containing a fixed 260-point sidebar and a capped detail width. (Sources/CodexBar/PreferencesView.swift:68, c979cdd8d41d)
• Resizable-window follow-up: The latest head explicitly preserves the resizable style mask and adds focused coverage that the Settings window remains resizable. (Tests/CodexBarTests/SettingsWindowAppearanceTests.swift:123, c979cdd8d41d)
• Real behavior proof: I downloaded and inspected the PR's before/after screenshots; the before images show collapsed and over-wide sidebar states, and the after image shows a fixed visible sidebar with readable detail content. (c979cdd8d41d)
• Related recovery work: Merged PR Fix Settings sidebar recovery #1871 repaired persisted collapsed NavigationSplitView frames, but it kept the split-view design that this PR replaces. (Sources/CodexBar/PreferencesView.swift:69, b37e29971698)

Likely related people:

• steipete: GitHub PR history and git log show steipete authored the System Settings-style redesign, the merged sidebar recovery, and the latest fixups on this PR head. (role: current Settings surface introducer and recent area contributor; confidence: high; commits: 9b13a7bae72f, b37e29971698, 950b4a0d8efc; files: Sources/CodexBar/PreferencesView.swift, Sources/CodexBar/CodexbarApp.swift, Tests/CodexBarTests/SettingsWindowAppearanceTests.swift)
• ProspectOre: The closed predecessor PR covered the same collapsed-sidebar failure mode and was credited in the merged owner replacement recovery work. (role: prior collapsed-sidebar recovery contributor; confidence: medium; commits: 70f76a408e76, b37e29971698; files: Sources/CodexBar/PreferencesView.swift, Tests/CodexBarTests/SettingsWindowAppearanceTests.swift)
• hhh2210: PR and git history show hhh2210 previously touched the Settings appearance bridge and tests around toolbar/dark-mode synchronization. (role: adjacent Settings appearance contributor; confidence: medium; commits: 1d39e0ca9ec4; files: Sources/CodexBar/PreferencesView.swift, Tests/CodexBarTests/SettingsWindowAppearanceTests.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (2 earlier review cycles)

• reviewed 2026-07-05T00:08:27.980Z sha d27e3a7 :: needs maintainer review before merge. :: none
• reviewed 2026-07-05T00:17:40.197Z sha c979cdd :: needs maintainer review before merge. :: none

[steipete]

Landed in 17347d8 from exact head c979cdd after 10/10 checks passed. Focused Settings appearance tests and make check passed; the release bundle was verified at 800×572, 880×652, and 1500×900 with a fixed visible sidebar, capped readable detail content, and scrolling rather than clipping at the minimum size. Changelog follow-up: 68f5f91. Thanks @Zihao-Qi!