Repository navigation
Description
What this issue is
The Settings window is drawn three times, once per platform, in hand-written AppKit, Win32 and GTK. This issue replaces all three with one webview built on the Chat surface's existing CSS tokens.
The spike that asked whether to do this is finished and the answer was yes. ADR-0029 records the decision, and both it and the prototype are on main under docs/adr/0029-settings-window-is-a-webview.md and spike/settings-webview/, landed by #725.
The work runs to nine steps, listed in the plan comment below. Six are done; Step 7 is in progress.
- Step 1 extracted the controller to
settings/controller.rsand put the macOS renderer on it (refactor(settings): Move what a Settings gesture means into one testable module #731). - Step 2 added the
settings_snapshotcommand and pinned it with committed JSON fixtures (feat(settings): Serialize the form description and pin it with fixtures #729). - Step 3 added
src/settings.html,src/settings.jsandsrc/settings.csswith node tests, not yet reachable from the app (feat(settings): Render the Settings form description in a webview #734). - Step 4 added the
settings_eventcommand over step 1's controller (feat(settings): Add settings_event command for webview gestures #769). - Step 5 added the Settings webview window behind
AI_BUDDY_SETTINGS_WEBVIEW=1, its capability, and the refresh event (feat(settings): Add Settings webview window behind AI_BUDDY_SETTINGS_WEBVIEW flag #773). Native remains the default. - Step 6 landed platform raise (macOS), alt-drag, Escape/Enter, and the focus ring (feat(settings): Add platform integration and keyboard shortcuts (Step 6) #774).
- Step 7 (partial):
scripts/ax-settings.swiftdump (test(macos): Descend into the AXWebArea in the Settings AX dump #779),tab/picksettle (fix(scripts): Gate tab and pick on the webview settle, not just dump #800), webview<select>pick via menu-layer race + type-select (fix(verify): Pick from the webview <select> menu the AX tree never publishes #801 / closes bug(verify): The webview AI source menu draws but ax-settings pick cannot see it #797), androw_liveduplicate-label fix (fix(settings): Publish each row's name once, and look past a repeat of it #820 — pagelabelled()wrap + script skip-repeat). Unmodified native verify still green; webview Settings verify green on macOS for artefact 1 (18 PASS / 2 SKIP). Other Step 7 artefacts remain (2, 4, 6 on verify(settings): Windows and Linux evidence the webview migration cannot get on a Mac #715, 7).
Steps 1 through 8 are each revertable by changing one flag. Step 9 deletes the three renderers and is the point of no return.
Read step 7 in the plan against this correction. Its row lists a screen-reader artefact that ai-buddy never owed, and the section on screen readers below says what replaces it.
Why
The native decision was right when someone made it, because the tree had no JavaScript in it at the time. ADR-0010 later chose a webview for Chat precisely because Settings had already priced the alternative at "1046 and 913 lines of hand-written AppKit and GTK". ADR-0018 supersedes ADR-0010 and does not carry that passage, so the quote is from the superseded text. ADR-0029 restates the reasoning and is the live record for this change.
Those two files are now 2115 and 1572 lines. A third, for Windows, is 2924. Another 1085 lines of verify scripts exist only because node --test cannot assert against a native window.
Numbers, read from main
Renderers total 6611 lines: macOS 2115, Windows 2924, GTK 1572. Of those, 592 lines are tests, split 155 on macOS and 437 on Windows. The GTK renderer has none. Behind them, form.rs is 3279 lines and settings.rs is 4406.
The scripts that drive the native windows are 1085 lines. On macOS, verify-settings-macos.sh and ax-settings.swift are 666 lines and read the accessibility tree. On Windows, verify-settings-win.ps1 is 419 lines and uses raw Win32 calls rather than UI Automation. Linux has no script at all, which is #630.
History shows 44 commits touching the renderers, 13 of them fixes, against 61 touching form.rs and settings.rs, 19 of them fixes.
Seven of the seven classifiable Settings bugs were renderer bugs. None were model bugs. Those are #601, #674, #552, #399, #400 and #642, each in one renderer, plus #625 in all three and fixed once per renderer. #634 closed with no referenced fix and stays unclassified. #629, #630, #631 and #667 are one verification epic per renderer, which is the cost of having three rather than a bug in any of them.
Deleting the renderers, their glue, the scripts and the source-grep test in settings.rs removes roughly 7600 lines. The HTML, JavaScript, CSS, two Tauri commands and node tests add about 1250. Net is around 6300 lines removed, and Settings code behind a platform cfg drops from about 6100 lines to about 15.
What the obvious framing misses
form.rs describes how to draw a row. It does not describe how to commit one.
All three renderers import DirectorDraft, SettingsPatch, SettingsSession and SettingsView, and each carries its own controller: director_draft, do_apply, fill_shortcut, handle_combobox_change and the rest. #534 was a bug in that triplicated copy.
So the job is not "add one interpreter, delete three renderers". It is "add one interpreter, pull the controller into a single Rust settings_event command, then delete three". Most of the new Rust goes into that controller, and pulling it into one place makes it testable for the first time.
The prototype
The AI tab, generated from form.rs, as static HTML and JavaScript on an unchanged chat-ui.css. Its own settings.css reads only var(--chat-*) variables. It covers two states, one where a Model API drives and one where a Harness does, in 155 lines of JavaScript and 244 of CSS, across 6 of the 9 FormRow variants.
Four node --test assertions replicate what verify-settings-macos.sh asks of an AX dump: section order, labels, and frozen HTTP rows. Screenshots came from headless Chrome, which is Blink and not WKWebView, so they show layout rather than the real widget set.
It looked like the Chat surface on the first attempt. <details> gives the disclosure that #642 hand-built, and <select> is the answer to #674. A shared class namespace bit once, when .frozen collided with Chat's.
Arguments against, and what came of each
Some of it stays native. Only raise(), at macos/settings_window.rs:1844. Settings sits at NSStatusWindowLevel, above the overlay's NSFloatingWindowLevel panel, and Tauri's always_on_top is also floating level. About 15 lines of macOS survive.
Screen readers are not affected, because ai-buddy has never claimed to support one. No ADR, no line of docs/SPEC.md and no code mentions VoiceOver, Narrator or Orca.
Row-level verification is not lost. Corrected 2026-09-17, it was. This paragraph previously said step 9 takes away both routes and step 7 owes a replacement for each. What step 9 removes is each script's native reader, not the capability, and the replacement now exists on both legs.
The original reasoning held for the native window. verify-settings-macos.sh parses an AX dump, verify-settings-win.ps1 calls EnumChildWindows and GetClassName to walk the window's Button, Edit and ComboBox children, and a Tauri webview is a single HWND with no Win32 children. The error was concluding from that that a webview cannot be read at all.
macOS reads the webview now. scripts/ax-settings.swift gained webContentSettled in #779: a WKWebView publishes its accessibility subtree only on request, the first pass into the window gets a childless AXGroup, and the real subtree lands about 107 ms after the ask, so sleeping instead of asking never gets it. #800 extended that gating from dump to tab and pick, and #801 taught pick to drive a WebKit <select> that publishes no AXMenu. Measured on this repo: a stock dump of the flag-gated webview Settings window returned 7 lines, the traffic lights and a childless group, and 68 lines with the descent, carrying the tab group, every checkbox and the disclosure triangles.
Windows reads it now too. #768 replaced the COM path with managed UI Automation, and #805 added scripts/ax-settings-win.ps1, which is pure UI Automation with wait, dump, pick-source and expand-disclosure, plus tests/ax-settings-win-finder.test.js. verify-settings-win.ps1 keeps its Win32 walk for the native window, so the two coexist rather than one replacing the other.
What each script can see does change at step 9, and the per-property accounting is still not done. One known asymmetry: #768's own live run reported that the UIA dump did not clearly show frozen HTTP rows, and pushed ES_READONLY into apply_enabled_states unit tests. So UIA is weaker than the Win32 walk for control state even on today's native window.
Keyboard operability is a separate matter and stays a condition below.
Platform integration does not move. TCC, Keychain, opening and wiping Memory, spawning and dismissing are already SettingsSession methods in Rust. None of it moves to JavaScript.
The macOS look changes, and that is accepted. The webview wears Chat's dark theme. It stops following OS light mode and stops matching the System Settings idiom. It matches the product's own window instead of the desktop around it. The owner accepted this trade; it is recorded here so nobody rediscovers it as a surprise.
Conditions
- The controller lives in Rust before the webview reads it, or the webview becomes a fourth copy. Step 1 did the extraction into
settings/controller.rsand moved macOS onto it. Windows and x11 still hold their own copies and stay frozen until step 4'ssettings_eventgives the module a caller on every platform. - The scripts are deleted only after node tests cover every tab in both AI-source states, and after one live open, dump and pick smoke test exists per platform.
- Keyboard-only operation is checked before the flag flips.
- Raising above the overlay is verified live on all three platforms.
- The HTML stays semantic. A
<select>stays a<select>. - No build step and no dependency. ADR-0029 carries that rule forward in its own words: "ADR-0010's stance on the stack holds: no build step, no dependency." TypeScript was settled separately and the answer was no, in spike(shell): Decide whether the webview moves from JS to TypeScript #692.
- The work lands complete behind a Development switch. Native is frozen to bug fixes, then the flag flips, then the renderers and scripts are deleted in one pull request. Keep the window where two implementations coexist short, because feat(settings): Generate the MCP registration for a Harness you run yourself #599 is the kind of form change that currently has to land three times.
Not verified
How WKWebView and WebKitGTK behave in a live window, covering accessibility-tree exposure, the <select> popup, password autofill and z-order. The root cause of #634.
WebView2 is partly answered. The Windows pass on #773 confirmed the webview window opens with the flag on and the native window still opens with it off, and it left two things uncovered: the five-tab HTML detail with one edit round-trip, and the settings-refresh roster push after an Instance spawns. The Linux equivalent was running separately when that was posted.
The platform evidence that cannot be gathered on a Mac is tracked in #715.
Written by the Claude Code agent on @omesser's behalf.
Metadata
Metadata
Assignees
Labels
Projects
- StatusShow more project fieldsDone
Activity
omesser commentedon Sep 15, 2026
Plan: Settings to a webview, in 9 landable steps
The spike's numbers are not re-derived here. This is the execution sequence.
Shape. The webview is built complete but unreachable (Steps 2–4), then reachable and off by default (Steps 5–6), then flipped (8), then the natives are deleted (9). Steps 1–8 are each revertable by a one-line flag change. Step 9 is the point of no return.
Why not one tab behind a flag. The five tabs share one window and one tab bar; a tab cannot be split off. So the unit of increment is reachability, not tab count.
Both pre-step fixes are done
docs/adr/0029-settings-window-is-a-webview.mdonspike/settings-webview-715.The spike report itself has been corrected rather than annotated: the clipboard
finding below is now in it, and the line saving reads as the measured range.
The steps
settings/controller.rs; macOS renderer calls itcargo test,verify-settings-macos.shsettings_snapshot+ serde derives + committed JSON fixturescargo teston 3 OSessrc/settings.html/settings.js/settings.css+ node tests, not reachablenode --teston 3 OSessettings_eventover Step 1's controllercargo teston 3 OSesAI_BUDDY_SETTINGS_WEBVIEW=1; capability; refresh eventAI_BUDDY_SETTINGS_NATIVE=1is the escape hatchmove_drag.rs, the source-grep test, both flags1. Extract the commit controller (macOS only)
Condition 1 of the spike, and the step that makes the triplicated controller testable for the first time.
director_draft,director_staged,do_apply,do_cancel,do_clear_key,fill_shortcut,handle_combobox_change,handle_text_change,rebuild_instances_list,confirm_wipebecome one platform-independent module folding{set_bool | set_text | pick | press}by row id intoSettingsPatchandSettingsSessionoperations. Unit tests for the fix(settings): Stop an untouched Director tab from wiping Base URL and Model #534 case (an untouched Director tab must not wipe Base URL and Model).src-tauri/src/settings/controller.rs(new),src-tauri/src/settings.rs,src-tauri/src/platform/macos/settings_window.rs.cargo test— for the first time against real code, not a source grep — plusscripts/verify-settings-macos.shgreen before and after.cfgto satisfy the macOS renderer. Either means the copies diverged more than the spike priced, and the −6300 estimate is wrong.2.
settings_snapshotand the fixturesSerializeonFormDescription,FormTab,FormSection,FormRow,CompositeControland theSettingsViewslice a tab reads.FormRowgets#[serde(tag = "type")]so the prototype'sswitch (row.type)works unchanged. One command,settings_snapshot, registered ingenerate_handler!.#[test]that serialises all five tabs in both AI-source states and compares against committedsrc-tauri/tests/fixtures/settings-snapshot-{modelApi,harnessDriving}.json. Those fixtures are what the node tests in Step 3 render from — the real description, not the prototype's hand-writtenai-tab.js. Anyform.rschange shows up as a fixture diff in its own PR, which is how feat(settings): Generate the MCP registration for a Harness you run yourself #599/feat(settings): Start a new session from the AI tab without changing Completer #712-shaped work stays honest across the two implementations.src-tauri/src/settings/form.rs,src-tauri/src/settings.rs,src-tauri/src/main.rs, fixtures.form::describe()turns out to carry something unserialisable, or reading live process state (harness::driving(), env) makes the fixture non-deterministic across platforms — the fixture must be byte-stable on all three CI legs or it is worse than no fixture.3. The page, unreachable
src/, extended from 6 of 9FormRowvariants to all 9 (Multiline,Listwith dismiss,InspectPath), plus the five-tab shell and tab switching.emitis a no-op stub.src/settings.html,src/settings.js,src/settings.css,tests/settings.test.js,tests/settings-tabs.test.js..frozenpicked up Chat's Prompt box): every selector insettings.cssis prefixed.set-, andsettings.cssdeclares no literal colour, font or radius — onlyvar(--chat-*). Enforce it by pointing the existingtests/chat-ui-tokens.test.jsrule at the new file rather than writing a second test. That keeps ADR-0019's seam:chat-ui.cssremains the single definition, Settings only consumes it, and a second.chat-ui-*design restyles both.node --test tests/*.test.js— the assertionsverify-settings-macos.shmakes against an AX dump (section order, labels, frozen HTTP rows per AI source), now over the flatcontrols(tab, view)list, for every tab in both states. That is condition 2's first half.4.
settings_eventdescribe()— an unknown id is an error, not a silent no-op, so JS/Rust drift is loud rather than quiet.SettingsSession::enable_consent→consent::enable), Keychain (SecretStore),open_memory,wipe_memory,spawn,dismiss, Harness attach. All are alreadySettingsSessionmethods.invoke→ Keychain and appears in no log line, no error string, and nothing the Development tab may grow. A test asserts the bad-key error path does not contain the key.5. The window, behind a flag
build_settingsmirroringbuild_chat(main.rs:829), labelsettings,WebviewUrl::App("settings.html").show_settings(main.rs:593) branches onmodel::env_switch("AI_BUDDY_SETTINGS_WEBVIEW")— the establishedAI_BUDDY_*pattern, same asAI_BUDDY_OPEN_SETTINGS. Native remains the default.capabilities/settings.json:core:event:allow-listen/allow-unlisten(chat.json's shape) andcore:window:allow-start-dragging.focuslistener, butframe_loop.rs:630also pushesplatform::refresh_settings()when the roster changes while the window is open. Sorefresh_settingsgains a webview arm that emitssettings-refresh, and the page re-invokes the snapshot. Without it, a spawn/dismiss elsewhere leaves Settings stale.cargo clippy -D warnings,cargo test); nothing renders there and nobody has seen it.6. Platform integration and keyboard
cfg(target_os)Settings code that survives:raise()onwindow.ns_window()—NSStatusWindowLevelplusactivateIgnoringOtherApps, because the overlay is anNSPanelatNSFloatingWindowLeveland Tauri'salways_on_topis also floating level, so order among them is not guaranteed.getCurrentWindow().startDragging(), gated on modifier held and!event.target.closest("input,select,button,summary,pre")—move_drag.rs's rule, in the page, with a node test on the gate.:focus-visibleon every control.raise, the flagged window opens behind the overlay.7. The evidence gate
No code lands here except a script change. Nothing is deleted until all six artefacts are posted on this issue.
scripts/ax-settings.swift dumpextended to descendAXWebArea, thenscripts/verify-settings-macos.shgreen with its assertions unchanged, in both AI-source states. The script written for the native window, unmodified in what it asserts, passing against the new one — the single strongest artefact available.<select>opens on Space and picks with arrows;<details>toggles on Enter. Checklist plus one screenshot per tab. (Condition 3.)<select>popup in WKWebView with the overlay up: the AppKit menu draws above it and dismisses on pick. This is macOS Settings Off pick does not leave the Harness popup #634's exact shape and macOS Settings Off pick does not leave the Harness popup #634's root cause is still unknown.verify-settings-win.ps1cannot be adapted — it asserts on Win32 class names throughFindWindow/SendMessage, and a webview has none. There is no Linux script at all (test(linux): Settings e2e + fill GTK renderer gaps #630). So this is a human in a VM or on another machine: window opens, five tabs render, one pick round-trips to disk, z-order holds. No script, no CI, no substitute.8. Flip
show_settingsdefaults to the webview;AI_BUDDY_SETTINGS_NATIVE=1is the way back. Dogfood a week. Abort is one line.9. Delete — point of no return
platform/{macos,windows,x11}/settings_window.rs,settings/move_drag.rs, theplatform.rs/mod.rsglue,verify-settings-macos.sh,ax-settings.swift,verify-settings-win.ps1, theevery_settings_window_is_built_with_the_director_resetsource grep atsettings.rs:2627, and both flags. ADR-0029 lands here. Close #629/#630/#631/#667 as obsolete, #601/#674 as fixed — after checking each is actually gone in the webview rather than assuming it.Everything before this reverts with a flag. After this, reverting means resurrecting 6491 lines from git history and re-learning why they were deleted.
Collisions with what is open right now
feat/679-new-session-from-ai-tab) and feat(settings): Generate the MCP registration for a Harness you run yourself #599 (feat/577-byo-harness-settings) both touch all threesettings_window.rs, plussettings.rsandform.rs. Step 1 conflicts with both in the macOS file. Land both first, then start Step 1. Neither introduces a newFormRowvariant — both reuseComposite/Button/Popup/InspectBlock— so Step 3's row coverage is unaffected. Both will move Step 2's fixtures, which is exactly what the fixtures are for.NSPasteboard,OpenClipboard/SetClipboardData/CF_TEXT,gtk::Clipboard. None of it is inSettingsSession. In the webview it isnavigator.clipboard.writeText()from the click handler, no dependency, no plugin. Two consequences: the spike's "zero platform integration moves to JS" was taken before feat(settings): Generate the MCP registration for a Harness you run yourself #599 and is now wrong, and clipboard write needs a live WKWebView check — hence artefact 7 in Step 7.src/chat-ui.css. Step 3 only reads tokens from it; textual conflict at worst.What two implementations cost while Steps 5–8 run: every form change lands twice. On the evidence of the two PRs open today, that is roughly one change a week. Freeze native to bug fixes and refuse new rows in it. If the window looks like running past ~3 weeks, that is itself the signal to stop and reconsider rather than pay the tax quietly.
Risks and aborts
chat-ui.cssunder ADR-0019's seam, which is a Chat change, not a Settings one.<select>misbehaves in WKWebView above the overlay. Step 7. If the popup draws under the overlay panel, the answer is not a hand-built dropdown; it is lowering the overlay while Settings is key, which is an overlay change and needs its own issue.cargo testred on all three CI legs.Two findings that change the numbers, now folded into the spike
One platform integration does move to JavaScript, and it strengthens the case.
PR #599 added a clipboard write — separately in all three renderers
(
NSPasteboard,SetClipboardData/CF_TEXT,gtk::Clipboard), none of it inSettingsSession. In a webview it is onenavigator.clipboard.writeText().The spike's "zero platform integration moves to JS" was written before #599
landed. It is a fourth renderer triplication, arriving mid-spike, and it is an
argument for the change.
The line saving is 5,500 to 6,300, not 6,300. The three renderers have
diverged more than a line count shows, so some of what looks duplicated is not.
Step 1 closes the range by measuring the real controller.
Two smaller ones, recorded and needing nothing: deleting
settings/move_drag.rssaves nothing worth counting (40 lines, 22 of them tests, already platform-free,
and the drag gate still has to exist in JavaScript); and keeping the window
current needs an event listener plus two capability permissions the spike's
sketch omitted, which is implementation detail, not a risk.
What the verification actually costs
Worth stating plainly, because an earlier draft of this plan framed it as the
largest open risk and that was the wrong shape.
The point of the change is that this cost is paid once. Today every Settings
change needs three renderers built and three verification paths driven — an AX
dump on macOS, Win32 class-name assertions on Windows, and nothing at all on
Linux. That is the recurring tax, and it is why seven of seven classifiable
Settings bugs were renderer bugs.
After the migration there is one renderer, and its tests are
node --testagainst a DOM, on every platform, from any machine. The per-change need for a
Windows box or a Linux session largely goes away, and development moves onto the
JavaScript path the Chat surface already uses.
What remains is one crossing. Step 7 needs Windows and Linux eyes once,
because three renderers cannot be deleted without knowing the replacement works
on three platforms. #715 gathers that, and its phase 1 — rendering the prototype
in WebView2 and WebKitGTK — can run today, before any production code is
written. That is a one-time gate on the way to a permanently smaller surface,
not an ongoing burden.
Still unverified, and honestly so: nothing has run in a live WKWebView, WebView2
or WebKitGTK — not the accessibility tree, the dropdown popup, password autofill,
window z-order, or clipboard write. #634's root cause is also still unknown and
bears directly on the dropdown.
— Claude Code agent, on @omesser's behalf.
omesser commentedon Sep 15, 2026
Filed #715 for the parts of step 7 that cannot be done on a Mac — the owner has Cursor agents with Windows and Linux access.
It splits into two phases, because one of them is available immediately:
index.htmluses an inline<script type="module">and the CSP has nounsafe-inline, so it must move to an externalsrc=the waysrc/chat.html:248does.The macOS artefacts — AX dump, keyboard-only, VoiceOver,
<select>above the overlay — stay here and run on the owner's machine.One gap in the plan I did not resolve, because it should not be settled by whoever happens to run phase 2. Artefact 3 specifies VoiceOver, which is macOS only, but step 9 deletes all three renderers and the native windows expose a real accessibility tree on every platform today — that is how
verify-settings-win.ps1drives Windows at all. So either Narrator and Orca belong in the gate too, or this plan should record why a macOS-only accessibility check is acceptable for a change that removes the accessibility surface on three platforms. Raised in #715 and left open here.— Claude Code agent, on @omesser's behalf.
omesser commentedon Sep 15, 2026
Three corrections to the 9-step plan, from building Step 2
Step 2 is open as #729, green on all three CI legs. Building it turned up three things the plan has wrong. Recording them here so Steps 3 and 9 are not misled by the plan comment above.
1.
describe()is not platform-free dataThe plan's model is that one description is built once and three renderers consume it. That is not what the code does. Two
#[cfg(target_os)]differences live insidedescribe()itself:Capturablecheckbox on Presence is#[cfg(any(macos, windows))].#[cfg(not(linux))], andCONSENT_ACCESSIBILITY_IDandBoolField::UseAccessibilityare gated the same way.This bears directly on Step 9. Deleting three renderers leaves one webview that has to know which platform it is drawing for, or those rows go wrong on Linux. The plan does not account for that anywhere. It is not a blocker for Steps 3 through 8, because the page can derive what it draws from the rows actually present, but it is work nobody has scoped.
2. One byte-stable fixture for three platforms is impossible
Not merely difficult. The plan's stop-and-reconsider condition for Step 2 named
harness::driving()and env vars. Those were the easy half. The one it missed isconsent::pane_intro(&consent::process_listed_as()), which names the responsible parent process. That is machine identity, not platform. A macOS-only fixture would not have been stable either:cargo testfrom a terminal andcargo teston a CI runner produce different strings.What #729 does instead. Three live reads move into a
Livevalue thatdescribe_with(&Live)takes, sodescribe()keeps its signature and every existing caller is untouched. The fixtures hold the full five-tab macOS form. The test pins all five tabs on macOS and Windows, and three on Linux (AI, Character, Development), which is where form churn actually lands per this plan's own #599 and #712 analysis.UNPINNED_TABSin the test is the single place that records the compromise.Nothing is gated behind a test-only
cfg. TheLiveseam is production code.3. The fixture path
The plan says
src-tauri/tests/fixtures/. The fixtures are at repo roottests/fixtures/, becausenode --testin Step 3 has to read the same filescargo testpins. One location, two readers.One thing worth a second opinion before Step 4
settings_snapshotreturnsSettingsView, which carriesbyo_tokenin plaintext. This is parity rather than a regression: the native Settings window already renders that token into a text field, and #599 already copies it to the clipboard. But Step 4's rule is written about the inbound direction, a typed API key travelling JS to Keychain.byo_tokentravels outbound, into the page's JS heap on every snapshot, where a strayconsole.logor an error dump reaches it in a way the native window has no equivalent for.api_key_*is unaffected; it carries only a fingerprint and a bool.Not a blocker for Step 2. Worth deciding explicitly in Step 4 rather than inheriting.
— Claude Code agent, on @omesser's behalf.
omesser commentedon Sep 15, 2026
Two more corrections, from building Step 1
Step 1 is open as #731. 429 lines in
settings/controller.rs, 155 implementation and 274 tests, against the plan's ~600 stop-and-reconsider ceiling. Nocfg(target_os)in it. Both of Step 1's abort gates passed cleanly, so the plan's estimate holds for macOS.settings.rsmoved by two lines, so the rebase against #729 is cheap.4. The plan's function list is a union of three renderers, not a macOS list
The plan says these "live today on the macOS renderer". Five of them do not:
fill_shortcut,handle_combobox_change,handle_text_change,rebuild_instances_listexist only inplatform/windows/settings_window.rs.confirm_wipeexists only inplatform/x11/settings_window.rs.macOS has
shortcut_picked,popup_picked,endpoint_endedandfill_instancesin their place.Step 1's shape is unaffected, since the triplicated part was the glue around
DirectorDraftrather than the names. Step 4 should not expect those names, and anyone sizing Step 9 from that list is counting three renderers' vocabularies as one.5.
verify-settings-macos.shis not green onmain, and cannot beFiled as #732. Two assertions, both
Clear key should be editable, can never pass:row_livematches the AX dump's value column, and a bareAXButtoncarries its text in title, so the match never fires.This bears on Step 7, which calls this script the single strongest artefact available and gates on it passing with its assertions unchanged. Two of them are dead today. Fix #732 before Step 7 runs, or the gate produces a red that has nothing to do with the migration.
#731 left the script alone on purpose. 19 PASS / 2 FAIL / 2 SKIP, identical before and after, check for check. Editing an assertion to make a refactor look green would have destroyed the artefact Step 7 depends on.
— Claude Code agent, on @omesser's behalf.
omesser commentedon Sep 15, 2026
Step 3 is open as #734, and it surfaces the decision Step 4 has to make
All nine
FormRowvariants render, all five tabs, both AI-source states, 21 new node tests. The fixtures on that branch are byte-identical to #729's, verified by hash rather than by eye. Step 3 generated them from the realdescribe_withinstead of transcribing, so the reconciliation between the two PRs is a no-op for the description half.6. The values half does not exist, and the plan does not say where it goes
Step 2 serializes
SettingsViewas its struct. A renderer cannot use that shape. It needs value-by-row-id, and the struct is value-by-field-name.The gap is not cosmetic.
BoolField::LaunchAtLoginwrites to a patch field (settings.rs:1233) andSettingsViewcarries nothing to read it back from. The row has no value source in the snapshot at all. It has not bitten yet only because that checkbox is frozen pending #132.Resolving row id to value in JavaScript means a hand-written table beside
form.rs, drifting in silence. That is the exact failure this migration exists to end.The code already argues for the answer.
SettingsView's own Development rows are keyed by form row id, and the comment atsettings.rs:81gives the reason: "Six switches would be six fields here, six bindings in each window, and a seventh row would need..." The same reasoning covers every row, not just Development.So: flatten to a by-row-id map in Rust, where
writes,endpoint_title,api_key_placeholderandexcluded_textalready live. Roughly forty lines, and it deletes the two hundred lines of AppKit ivar binding rather than porting them.#734 ships
valuesas a separate fixture file rather than a second key, so #729's fixture drops in untouched and a missingvaluesfails loudly instead of a renamed key failing quietly. The reviewer has to decide this, and it is Step 4's call, not Step 3's.7.
form.rsdescribes drawing but not visibilityThe spike found it describes drawing but not committing. One step further out: AppKit hides the BYO token block and its Copy button when
byo_tokenis empty, and that rule lives in the renderer. The webview draws an empty box and a dead Copy button. Porting the rule to JavaScript would re-triplicate it, so #734 leaves it visible and reports it. It belongs inFormRowas data.8. The AI tab has five sections, not four
#599 landed the BYO section between
AI sourceandModel / APIafter the spike was taken.verify-settings-macos.sh's grep is blind to it by construction, so the spike's four-section count is stale.Known gap, stated rather than papered over
No top-level
Popupis frozen in either fixture, so that path is untested. A third fixture withAI_BUDDY_HARNESSexported would close it. #734 did not invent one.Nothing in #734 has run in a live WKWebView. Headless Chrome rendered all five tabs in both states, and Blink is not WKWebView.
— Claude Code agent, on @omesser's behalf.
omesser commentedon Sep 15, 2026
Step 2 landed on main
#729 merged (
a2dab85). On main now:Serializeon the form description types andSettingsViewsettings_snapshotcommand ({ form, view })tests/fixtures/settings-snapshot-{modelApi,harnessDriving}.json, pinned byboth_ai_sources_serialize_to_the_committed_fixturesLive/describe_withso the fixtures stay byte-stable (five tabs on macOS/Windows, three on Linux)Still open on this umbrella: Steps 1 and 3–9. Step 1 is #731; Step 3 is #734. Leaving this issue open.
— Cursor agent (Coder), on @omesser's behalf.
omesser commentedon Sep 15, 2026
Shipped on main via #725 (partial)
PR #725 merged to
mainat68e3fe4. What landed:docs/adr/0029-settings-window-is-a-webview.mdspike/settings-webview/(externalmain.jsfor CSP; serving-from-repo-root note inindex.html)What this does not close: the nine implementation steps. Steps 1–3 are already tracked elsewhere (#731, #729, #734). Linux Phase 1 evidence that rode with the branch was withdrawn (stylesheet 404); re-run and Windows Phase 1 remain on #715.
Leaving this issue open.
— Cursor agent (Coder), on @omesser's behalf.
refactor(settings): Move what a Settings gesture means into one testa…
34 remaining items
omesser commentedon Sep 18, 2026
Step 7 artefact 7 had no ticket of its own. Opened #855.
— Grok Build agent, on @omesser's behalf.
omesser commentedon Sep 18, 2026
#706 Step 7 artefact 7 (clipboard write from a Settings webview Copy click) is in #857 (
Closes #855).— Grok Build agent, on @omesser's behalf.
omesser commentedon Sep 19, 2026
Step 7 artefact 7 (webview clipboard write) landed on
mainvia #857; closes #855.Copy in the Settings webview now puts the BYO registration snippet on the system clipboard. Other Step 7 artefacts (#848 keyboard, #849 select overlay, #850 Windows z-order, and leftovers on #715) stay open. This issue stays open until Steps 7–9 finish.
— Cursor agent (Coder), on @omesser's behalf.
omesser commentedon Sep 21, 2026
Claimed for Step 8 only: default the Settings window to the webview. Native stays behind
AI_BUDDY_SETTINGS_NATIVE=1. Step 9 (delete natives) is not this PR. Issue stays open.— Grok Build agent, on @omesser's behalf.
omesser commentedon Sep 21, 2026
Step 8 is #860 (
652b7110). Default is the webview.AI_BUDDY_SETTINGS_NATIVE=1is the hatch. Issue stays open for Step 9.— Grok Build agent, on @omesser's behalf.
omesser commentedon Sep 21, 2026
Step 8 is up: #864
Settings now opens as the webview by default.
AI_BUDDY_SETTINGS_NATIVE=1is the escape hatch. The oldAI_BUDDY_SETTINGS_WEBVIEWflag is gone.Step 9 is not in that PR. Native renderers,
move_drag.rs, the native verify scripts, and the source-grep test stay until the flip has been dogfooded.Windows prove on this machine: no Settings env var opens class
Tauri WindowtitledSettings;AI_BUDDY_SETTINGS_NATIVE=1opens classAiBuddySettings. Phase 2 smoke CHECK1–3 passed without forcing a webview env; CHECK4 z-order failed (Settings behind overlay HWNDs) and is called out on the PR.— Grok Build agent, on @omesser's behalf.
omesser commentedon Sep 21, 2026
Step 8 landed on main via #860
#860 merged (
7f48e94). On main now:settings_is_webview(); unset → webview).AI_BUDDY_SETTINGS_NATIVE=1keeps the native renderer;AI_BUDDY_SETTINGS_WEBVIEW=1still selects the webview; when both are set, native wins.AI_BUDDY_SETTINGS_NATIVE=1.docs/DEVELOPMENT.mdand ADR-0029 Consequences record the flip. ADR-0029 is not marked Accepted. Native renderers stay until Step 9.Does not close #706. Step 9 still deletes the three native renderers and both flags.
— Cursor agent (Coder), on @omesser's behalf.
omesser commentedon Sep 21, 2026
Step 8 landed as #860 (
7f48e94). Settings is the webview by default.AI_BUDDY_SETTINGS_NATIVE=1is the hatch. This issue stays open for Step 9 (delete the three native renderers).#864 is a second Step 8 PR still open. Same default flip, plus more verify scripts. Land it or close it as overlapping 860.
— Grok Build agent, on @omesser's behalf.
omesser commentedon Sep 21, 2026
Step 8 leftover landed on main via #864
#864 merged (
464fd028). On main now, on top of #860:AI_BUDDY_SETTINGS_WEBVIEW=1; they rely on the default.AI_BUDDY_SETTINGS_NATIVE=1so they still assert AppKit / GTK / Win32 widgets.settings_is_webview().settings_is_webview()from #860 is unchanged. Abort stays one line until Step 9.Does not close #706. Step 9 still deletes the three native renderers,
move_drag.rs, the native verify scripts, the source-grep test, and both Settings env flags.— Cursor agent (Coder), on @omesser's behalf.
omesser commentedon Sep 22, 2026
Step 9 is up: #871
Settings is only the webview. The three native renderers,
move_drag.rs, the native verify scripts,settings_is_webview(),AI_BUDDY_SETTINGS_NATIVE, andAI_BUDDY_SETTINGS_WEBVIEWare gone.raise_settings_windowstays for overlay z-order.Windows live prove on this machine: no Settings env var opens class
Tauri Window, titleSettings.AI_BUDDY_SETTINGS_NATIVE=1still opens that same webview; there is noAiBuddySettingsHWND.macOS / Linux live sittings were not run here.
The PR has
Closes #706. Related native-renderer bugs/epics: #601 and #631 still open and will be closed from this Step; #629, #630, #667, #674 already closed. #634 stays closed and is not reopened — the select-above-overlay root cause is still not claimed.— Grok Build agent, on @omesser's behalf.
omesser commentedon Sep 22, 2026
Step 9 landed on main via #871
#871 merged (
f91f3788). On main now:show_settingsalways builds or raises thesettingswindow.settings/move_drag.rs, the native verify scripts,settings_is_webview(),AI_BUDDY_SETTINGS_NATIVE, andAI_BUDDY_SETTINGS_WEBVIEWare gone.raise_settings_windowstays (macOSNSStatusWindowLevel, X11keep_above+ EWMH, WindowsHWND_TOPMOST) because Taurialways_on_topdoes not beat the overlay band.Related hygiene already done when #871 opened: #601 and #631 closed (Win32 layout / native e2e epic deleted with the renderer). Leftover webview form wiring that the deletion made visible is tracked in #875 (open).
Linux live z-order (
verify-settings-zorder-x11.sh) was not run in #871; Ubuntu CI is the compile evidence for that leg.This closes the #706 migration.
— Cursor agent (Coder), on @omesser's behalf.