Skip to content

refactor(settings): Replace the three native Settings renderers with one webview #706

Closed

Description

@omesser

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.

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

  1. 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.rs and moved macOS onto it. Windows and x11 still hold their own copies and stay frozen until step 4's settings_event gives the module a caller on every platform.
  2. 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.
  3. Keyboard-only operation is checked before the flag flips.
  4. Raising above the overlay is verified live on all three platforms.
  5. The HTML stays semantic. A <select> stays a <select>.
  6. 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.
  7. 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.

Activity

  1. added this to the V1 milestone on Sep 14, 2026
  2. added
    p0Drop everything: broken for users, or blocking
    researchDefining or executing a research into an aspect: tech, direction, decision
    on Sep 15, 2026
  3. omesser commented on Sep 15, 2026

    @omesser
    OwnerAuthor

    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

    • ADR renumbered to 0029. 0028 went to the ACP render boundary (docs(adr): ADR-0028 bounds the Chat surface to what ACP sends #710). The draft is now docs/adr/0029-settings-window-is-a-webview.md on spike/settings-webview-715.
    • The prototype's inline script is extracted, so it can load under the app's content security policy. Done on that same branch.

    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

    # What Verified by Blind on Win/Linux?
    1 Commit controller extracted to settings/controller.rs; macOS renderer calls it cargo test, verify-settings-macos.sh no — natives untouched
    2 settings_snapshot + serde derives + committed JSON fixtures cargo test on 3 OSes no
    3 src/settings.html / settings.js / settings.css + node tests, not reachable node --test on 3 OSes no
    4 settings_event over Step 1's controller cargo test on 3 OSes no
    5 Window behind AI_BUDDY_SETTINGS_WEBVIEW=1; capability; refresh event manual macOS; CI compile only elsewhere yes, CI-compiled
    6 macOS raise above the overlay, alt-drag, Escape/Enter, focus ring manual macOS yes, unverified
    7 Evidence gate — AX, keyboard, VoiceOver, z-order, per platform human runs, posted on this issue needs a Windows box and a Linux session
    8 Flip the default; AI_BUDDY_SETTINGS_NATIVE=1 is the escape hatch dogfood yes, until 7 closes
    9 Delete 3 renderers, 3 scripts, move_drag.rs, the source-grep test, both flags CI green POINT OF NO RETURN

    1. Extract the commit controller (macOS only)

    Condition 1 of the spike, and the step that makes the triplicated controller testable for the first time.

    • Changes: director_draft, director_staged, do_apply, do_cancel, do_clear_key, fill_shortcut, handle_combobox_change, handle_text_change, rebuild_instances_list, confirm_wipe become one platform-independent module folding {set_bool | set_text | pick | press} by row id into SettingsPatch and SettingsSession operations. 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).
    • Files: src-tauri/src/settings/controller.rs (new), src-tauri/src/settings.rs, src-tauri/src/platform/macos/settings_window.rs.
    • Verified by: cargo test — for the first time against real code, not a source grep — plus scripts/verify-settings-macos.sh green before and after.
    • Does not: rewire the Windows or x11 renderers. Rewiring two diverged copies blind, on a Mac, for code scheduled for deletion, is risk with no payoff. They keep their copies, frozen. Condition 1 asks that the webview not be a fourth copy; this satisfies that.
    • Stop and reconsider if: the extraction lands over ~600 lines, or needs a cfg to satisfy the macOS renderer. Either means the copies diverged more than the spike priced, and the −6300 estimate is wrong.

    2. settings_snapshot and the fixtures

    • Changes: Serialize on FormDescription, FormTab, FormSection, FormRow, CompositeControl and the SettingsView slice a tab reads. FormRow gets #[serde(tag = "type")] so the prototype's switch (row.type) works unchanged. One command, settings_snapshot, registered in generate_handler!.
    • Plus the load-bearing bit: a #[test] that serialises all five tabs in both AI-source states and compares against committed src-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-written ai-tab.js. Any form.rs change 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.
    • Files: src-tauri/src/settings/form.rs, src-tauri/src/settings.rs, src-tauri/src/main.rs, fixtures.
    • Does not: open a window, render anything, or touch a renderer.
    • Stop and reconsider if: 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

    • Changes: the prototype promoted to src/, extended from 6 of 9 FormRow variants to all 9 (Multiline, List with dismiss, InspectPath), plus the five-tab shell and tab switching. emit is a no-op stub.
    • Files: src/settings.html, src/settings.js, src/settings.css, tests/settings.test.js, tests/settings-tabs.test.js.
    • The namespace collision (.frozen picked up Chat's Prompt box): every selector in settings.css is prefixed .set-, and settings.css declares no literal colour, font or radius — only var(--chat-*). Enforce it by pointing the existing tests/chat-ui-tokens.test.js rule at the new file rather than writing a second test. That keeps ADR-0019's seam: chat-ui.css remains the single definition, Settings only consumes it, and a second .chat-ui-* design restyles both.
    • Verified by: node --test tests/*.test.js — the assertions verify-settings-macos.sh makes against an AX dump (section order, labels, frozen HTTP rows per AI source), now over the flat controls(tab, view) list, for every tab in both states. That is condition 2's first half.
    • Does not: invoke Rust, build a window, or change any product behaviour. This PR is purely additive and cannot break the app.

    4. settings_event

    • Changes: one command over Step 1's controller. Row ids validated against describe() — an unknown id is an error, not a silent no-op, so JS/Rust drift is loud rather than quiet.
    • Stays in Rust, behind this command, none of it reaching JS: TCC/consent (SettingsSession::enable_consent → consent::enable), Keychain (SecretStore), open_memory, wipe_memory, spawn, dismiss, Harness attach. All are already SettingsSession methods.
    • The key: a typed API key travels JS → 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.
    • Stop and reconsider if: any operation needs a window handle to work. That would mean the controller is not as platform-free as Step 1 concluded.

    5. The window, behind a flag

    • Changes: build_settings mirroring build_chat (main.rs:829), label settings, WebviewUrl::App("settings.html"). show_settings (main.rs:593) branches on model::env_switch("AI_BUDDY_SETTINGS_WEBVIEW") — the established AI_BUDDY_* pattern, same as AI_BUDDY_OPEN_SETTINGS. Native remains the default.
    • capabilities/settings.json: core:event:allow-listen / allow-unlisten (chat.json's shape) and core:window:allow-start-dragging.
    • One thing the spike's answer half-covers: become-key refresh is indeed a focus listener, but frame_loop.rs:630 also pushes platform::refresh_settings() when the roster changes while the window is open. So refresh_settings gains a webview arm that emits settings-refresh, and the page re-invokes the snapshot. Without it, a spawn/dismiss elsewhere leaves Settings stale.
    • Verified by: manual macOS run with the flag. Windows and Linux are compile-only in CI (cargo clippy -D warnings, cargo test); nothing renders there and nobody has seen it.
    • This is the judgement point for the look question. First time the webview and the native window can be opened side by side on the platform the owner actually uses. If it loses there, stop before Step 6.

    6. Platform integration and keyboard

    • Stays native, ~15 lines, the only cfg(target_os) Settings code that survives: raise() on window.ns_window() — NSStatusWindowLevel plus activateIgnoringOtherApps, because the overlay is an NSPanel at NSFloatingWindowLevel and Tauri's always_on_top is also floating level, so order among them is not guaranteed.
    • Moves to JS: alt-drag via 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.
    • Escape closes, Enter applies, :focus-visible on every control.
    • Required before Step 7 can even be attempted on macOS: without 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.

    1. macOS AX. scripts/ax-settings.swift dump extended to descend AXWebArea, then scripts/verify-settings-macos.sh green 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.
    2. Keyboard-only. Tab reaches every control in DOM order on all five tabs; focus ring visible on each; Escape closes; Enter applies; <select> opens on Space and picks with arrows; <details> toggles on Enter. Checklist plus one screenshot per tab. (Condition 3.)
    3. VoiceOver. All five tabs, every control announcing role, name and value; frozen rows announcing as read-only.
    4. z-order. Character summoned, Settings opened, Settings above the overlay panel. Screenshot, per platform. (Condition 4.)
    5. <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.
    6. Windows and Linux smoke, by hand. verify-settings-win.ps1 cannot be adapted — it asserts on Win32 class names through FindWindow/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.
    7. Clipboard write from a click handler in WKWebView — added because of feat(settings): Generate the MCP registration for a Harness you run yourself #599, see collisions.

    8. Flip

    show_settings defaults to the webview; AI_BUDDY_SETTINGS_NATIVE=1 is 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, the platform.rs/mod.rs glue, verify-settings-macos.sh, ax-settings.swift, verify-settings-win.ps1, the every_settings_window_is_built_with_the_director_reset source grep at settings.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

    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

    • Step 7 never closes, because there is no Windows box and no Linux desktop session. The most likely way this stalls, and it stalls one step from the payoff. Abort: stop at Step 8 with the flip made per platform — webview on macOS, native on Windows and Linux — and delete only the macOS renderer and its two scripts (−2651). That keeps the multiplier at two, which ADR-0029's Considered Options explicitly rejects, so taking this fallback means amending the ADR, not quietly living outside it.
    • macOS looks worse than the native window. Unresolved, not settled. The webview is Chat's dark theme and stops following OS light mode and the System Settings idiom. Judged at Step 5. If it loses, stop before Step 6; the cheap answer is a light-mode block in chat-ui.css under ADR-0019's seam, which is a Chat change, not a Settings one.
    • Accessibility regresses. Step 7 is both the check and the abort. If VoiceOver cannot reach a control, the fix is in the HTML. If it cannot be fixed in semantic HTML, stop — condition 5 is not negotiable, and a custom widget is not the answer.
    • <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.
    • The fixture goes stale and node tests assert against a description Rust no longer produces. Mitigated by the Rust test comparing rather than writing: a stale fixture turns cargo test red 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 in
    SettingsSession. In a webview it is one navigator.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.rs
    saves 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 --test
    against 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.

  4. omesser commented on Sep 15, 2026

    @omesser
    OwnerAuthor

    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:

    • Phase 1, runnable today: render the existing prototype in WebView2 and WebKitGTK. Nobody has seen it on either platform, and if it looks bad enough there to change the recommendation, that is worth knowing before steps 1-6 get built. One blocker to clear first — the prototype's index.html uses an inline <script type="module"> and the CSP has no unsafe-inline, so it must move to an external src= the way src/chat.html:248 does.
    • Phase 2, blocked on steps 5-6: artefact 6 of the gate above (Windows and Linux smoke by hand) plus the non-macOS half of artefact 4 (z-order above the overlay panel). Nothing to drive until the flag exists.

    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.ps1 drives 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.

  5. omesser commented on Sep 15, 2026

    @omesser
    OwnerAuthor

    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 data

    The 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 inside describe() itself:

    • The Capturable checkbox on Presence is #[cfg(any(macos, windows))].
    • The two consent checkboxes on Privacy are #[cfg(not(linux))], and CONSENT_ACCESSIBILITY_ID and BoolField::UseAccessibility are 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 is consent::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 test from a terminal and cargo test on a CI runner produce different strings.

    What #729 does instead. Three live reads move into a Live value that describe_with(&Live) takes, so describe() 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_TABS in the test is the single place that records the compromise.

    Nothing is gated behind a test-only cfg. The Live seam is production code.

    3. The fixture path

    The plan says src-tauri/tests/fixtures/. The fixtures are at repo root tests/fixtures/, because node --test in Step 3 has to read the same files cargo test pins. One location, two readers.

    One thing worth a second opinion before Step 4

    settings_snapshot returns SettingsView, which carries byo_token in 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_token travels outbound, into the page's JS heap on every snapshot, where a stray console.log or 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.

  6. omesser commented on Sep 15, 2026

    @omesser
    OwnerAuthor

    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. No cfg(target_os) in it. Both of Step 1's abort gates passed cleanly, so the plan's estimate holds for macOS.

    settings.rs moved 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_list exist only in platform/windows/settings_window.rs.
    • confirm_wipe exists only in platform/x11/settings_window.rs.

    macOS has shortcut_picked, popup_picked, endpoint_ended and fill_instances in their place.

    Step 1's shape is unaffected, since the triplicated part was the glue around DirectorDraft rather 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.sh is not green on main, and cannot be

    Filed as #732. Two assertions, both Clear key should be editable, can never pass: row_live matches the AX dump's value column, and a bare AXButton carries 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.

  7. omesser commented on Sep 15, 2026

    @omesser
    OwnerAuthor

    Step 3 is open as #734, and it surfaces the decision Step 4 has to make

    All nine FormRow variants 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 real describe_with instead 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 SettingsView as 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::LaunchAtLogin writes to a patch field (settings.rs:1233) and SettingsView carries 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 at settings.rs:81 gives 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_placeholder and excluded_text already live. Roughly forty lines, and it deletes the two hundred lines of AppKit ivar binding rather than porting them.

    #734 ships values as a separate fixture file rather than a second key, so #729's fixture drops in untouched and a missing values fails 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.rs describes drawing but not visibility

    The spike found it describes drawing but not committing. One step further out: AppKit hides the BYO token block and its Copy button when byo_token is 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 in FormRow as data.

    8. The AI tab has five sections, not four

    #599 landed the BYO section between AI source and Model / API after 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 Popup is frozen in either fixture, so that path is untested. A third fixture with AI_BUDDY_HARNESS exported 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.

  8. omesser commented on Sep 15, 2026

    @omesser
    OwnerAuthor

    Step 2 landed on main

    #729 merged (a2dab85). On main now:

    • Serialize on the form description types and SettingsView
    • settings_snapshot command ({ form, view })
    • committed fixtures at tests/fixtures/settings-snapshot-{modelApi,harnessDriving}.json, pinned by both_ai_sources_serialize_to_the_committed_fixtures
    • Live / describe_with so 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.

  9. omesser commented on Sep 15, 2026

    @omesser
    OwnerAuthor

    Shipped on main via #725 (partial)

    PR #725 merged to main at 68e3fe4. What landed:

    • ADR-0029 — docs/adr/0029-settings-window-is-a-webview.md
    • Spike + static AI-tab prototype — spike/settings-webview/ (external main.js for CSP; serving-from-repo-root note in index.html)
    • No production Settings code — natives untouched; app behaviour unchanged

    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.

  10. 34 remaining items

  11. omesser commented on Sep 18, 2026

    @omesser
    OwnerAuthor

    Step 7 artefact 7 had no ticket of its own. Opened #855.

    — Grok Build agent, on @omesser's behalf.

  12. omesser commented on Sep 18, 2026

    @omesser
    OwnerAuthor

    #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.

  13. omesser commented on Sep 19, 2026

    @omesser
    OwnerAuthor

    Step 7 artefact 7 (webview clipboard write) landed on main via #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.

  14. self-assigned this
    on Sep 21, 2026
  15. omesser commented on Sep 21, 2026

    @omesser
    OwnerAuthor

    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.

  16. moved this from 👷 Todo to 🏗 In Progress in Fidgeton Sep 21, 2026
  17. omesser commented on Sep 21, 2026

    @omesser
    OwnerAuthor

    Step 8 is #860 (652b7110). Default is the webview. AI_BUDDY_SETTINGS_NATIVE=1 is the hatch. Issue stays open for Step 9.

    — Grok Build agent, on @omesser's behalf.

  18. omesser commented on Sep 21, 2026

    @omesser
    OwnerAuthor

    Step 8 is up: #864

    Settings now opens as the webview by default. AI_BUDDY_SETTINGS_NATIVE=1 is the escape hatch. The old AI_BUDDY_SETTINGS_WEBVIEW flag 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 Window titled Settings; AI_BUDDY_SETTINGS_NATIVE=1 opens class AiBuddySettings. 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.

  19. omesser commented on Sep 21, 2026

    @omesser
    OwnerAuthor

    Step 8 landed on main via #860

    #860 merged (7f48e94). On main now:

    • Settings opens as the webview by default on macOS, Windows, and Linux (settings_is_webview(); unset → webview).
    • AI_BUDDY_SETTINGS_NATIVE=1 keeps the native renderer; AI_BUDDY_SETTINGS_WEBVIEW=1 still selects the webview; when both are set, native wins.
    • Native verify scripts export AI_BUDDY_SETTINGS_NATIVE=1. docs/DEVELOPMENT.md and 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.

  20. omesser commented on Sep 21, 2026

    @omesser
    OwnerAuthor

    Step 8 landed as #860 (7f48e94). Settings is the webview by default. AI_BUDDY_SETTINGS_NATIVE=1 is 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.

  21. omesser commented on Sep 21, 2026

    @omesser
    OwnerAuthor

    Step 8 leftover landed on main via #864

    #864 merged (464fd028). On main now, on top of #860:

    • Webview verify scripts no longer force AI_BUDDY_SETTINGS_WEBVIEW=1; they rely on the default.
    • Native verify scripts pin AI_BUDDY_SETTINGS_NATIVE=1 so they still assert AppKit / GTK / Win32 widgets.
    • Surface-flag test pointed at 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.

  22. omesser commented on Sep 22, 2026

    @omesser
    OwnerAuthor

    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, and AI_BUDDY_SETTINGS_WEBVIEW are gone. raise_settings_window stays for overlay z-order.

    Windows live prove on this machine: no Settings env var opens class Tauri Window, title Settings. AI_BUDDY_SETTINGS_NATIVE=1 still opens that same webview; there is no AiBuddySettings HWND.

    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.

  23. moved this from In Progress to Done in Fidgeton Sep 22, 2026
  24. omesser commented on Sep 22, 2026

    @omesser
    OwnerAuthor

    Step 9 landed on main via #871

    #871 merged (f91f3788). On main now:

    • Settings is only the Tauri webview. show_settings always builds or raises the settings window.
    • Native AppKit / Win32 / GTK Settings renderers, settings/move_drag.rs, the native verify scripts, settings_is_webview(), AI_BUDDY_SETTINGS_NATIVE, and AI_BUDDY_SETTINGS_WEBVIEW are gone.
    • raise_settings_window stays (macOS NSStatusWindowLevel, X11 keep_above + EWMH, Windows HWND_TOPMOST) because Tauri always_on_top does not beat the overlay band.
    • ADR-0029 marked Accepted.

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

needs-triageMaintainer needs to evaluate this issuep0Drop everything: broken for users, or blockingrefactoringresearchDefining or executing a research into an aspect: tech, direction, decision

Projects

  • Status
    Done

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions