Skip to content

feat(settings): Add Settings webview window behind AI_BUDDY_SETTINGS_WEBVIEW flag - #773

Merged
omesser merged 3 commits into
mainfrom
cursor/settings-webview-window-step5-3914
Sep 16, 2026
Merged

omesser merged 3 commits into
mainfrom
cursor/settings-webview-window-step5-3914

Conversation

@omesser

@omesser omesser commented Sep 16, 2026 •

Copy link
Copy Markdown
Owner

Why

Step 5 of the Settings webview migration (#706). Steps 1–4 landed the controller, snapshot command, HTML/JS/CSS page, and settings_event. Step 5 makes the window reachable behind a flag so the webview can be opened and tested, while native remains the default. Step 6 (raise, alt-drag, Escape/Enter, focus ring) follows after this lands.

Without this step, the Settings webview page exists on disk but nothing can open it.

What changed

  • build_settings() mirrors build_chat: label settings, opens settings.html, sized 600×520 with 480×400 minimum
  • show_settings() branches on model::env_switch("AI_BUDDY_SETTINGS_WEBVIEW"): builds or raises the webview window when the flag is explicitly on (1|true|yes|on); native otherwise
  • capabilities/settings.json: grants core:event:allow-listen and allow-unlisten for settings-refresh events (Step 6 adds alt-drag permission)
  • refresh_settings() gains a webview arm: checks flag and webview window existence, emits settings-refresh event when the roster changes while the window is open; otherwise calls native platform refresh
  • settings.js initialization: listens for settings-refresh, calls settings_snapshot on load and refresh, invokes settings_event for row edits; includes visible error states with retry, listener cleanup on beforeunload, and race condition prevention
  • Behavioral tests (tests/settings-webview.test.js): verify snapshot rendering, refresh events, controller response processing, error handling, and race prevention; 224 node tests pass

Native renderers (macOS, Windows, x11) are untouched. Step 6 work (macOS raise, alt-drag gate, Escape/Enter, focus ring) is deliberately excluded.

Review gate applied (060afc2)

Consolidated Standards and Spec gate addressed at tip:

  1. ✅ Outcome::Run uses stable RowOperation::as_str() wire format (not Debug)
  2. ✅ Removed unused batched field from payload
  3. ✅ Visible error states with retry in-page (no silent console.log)
  4. ✅ Removed unused allow-start-dragging permission (Step 6 scope)
  5. ✅ Behavioral tests replace signature-only checks
  6. ✅ Evidence-backed listener cleanup on beforeunload
  7. ✅ Race condition prevention via lastSnapshotPromise
  8. ✅ PR body flag wording corrected

Rebase

Rebased onto origin/main (39fd012), which includes merged PR #767 (Windows Settings auto-open / WM_ACTIVATE). Resolved conflict in src/settings.js (comment block describing initialization), preserving Step 5's implementation comment. Verified both features coexist:

— Cursor agent (Coder), on @omesser's behalf.

Open in Web Open in Cursor 

@cursor

cursor Bot commented Sep 16, 2026

Copy link
Copy Markdown

Rebased onto origin/main (cbe9221, #769). PR is MERGEABLE (no conflicts). Force-with-lease pushed the same branch; tip is now c8f611e.

Conflict: only src/settings.js. Original tip dcab43c sat on 55b6c95, so Step 5’s page init collided with #769’s invokeSettingsEvent / handleEvent. The earlier 2d8c770 rewrite dropped invokeSettingsEvent (so handleEvent could not run) and called handleEvent(response) without awaiting, which would have invoked settings_event twice with the wrong argument.

Resolution (kept the Settings webview window + AI_BUDDY_SETTINGS_WEBVIEW flag; native remains default):

  • Keep feat(settings): Add settings_event command for webview gestures #769’s invokeSettingsEvent and exported handleEvent
  • Step 5 init calls await handleEvent(payload) (no local shadow, no second invoke); a truthy outcome reloads the snapshot
  • Tab clicks still work without Tauri; snapshot + settings-refresh listen only when __TAURI__ is present
  • Linux compile: clone the AppHandle the way open_chat does; import Manager/Emitter in platform.rs

How tested

  • pre-commit run --files on the six touched paths, including cargo fmt and workspace clippy -D warnings
  • node --test tests/*.test.js — 215 pass (including feat(settings): Add settings_event command for webview gestures #769 handleEvent tests and the Step 5 init tests)
  • cargo clippy --workspace --all-targets -- -D warnings — pass
  • cargo test --workspace --all-targets — 485 pass; 4 fail are this VM (no Secret Service / GTK not on the test thread), not this diff

— Cursor agent (Coder), on @omesser's behalf.

@omesser

omesser commented Sep 16, 2026

Copy link
Copy Markdown
Owner Author

DESKTOP-UQIE144 live verify @ c8f611e (Windows)

Branch cursor/settings-webview-window-step5-3914.

Flag ON (AI_BUDDY_SETTINGS_WEBVIEW=1 + AI_BUDDY_OPEN_SETTINGS=1)

  • PASS — Settings opens as a Tauri webview window: Name='Settings', Class=Tauri Window, bounds ~616×559, UIA shows pane ai-buddy Settings - Web content.
  • PASS — No native AiBuddySettings window present.

Flag OFF (AI_BUDDY_SETTINGS_WEBVIEW=0 + open-settings hook)

  • PASS — Native Settings: Name='ai-buddy Settings', Class=AiBuddySettings, bounds 560×720 on secondary.

Not covered on this pass

  • Five-tab HTML detail / one edit round-trip (WebView2 AX tree did not expose tab names; stills are the visual check).
  • Instance spawn → settings-refresh roster push.

Machine freed. Linux twin is running separately in a cloud agent.

— Cursor agent (Coder), on @omesser's behalf.

flag-on-280

flag-off-280

@omesser

omesser commented Sep 16, 2026

Copy link
Copy Markdown
Owner Author

macOS local verification @ c8f611e

MacBook Pro M3 Pro, macOS 25.6, debug build from a clean worktree at the PR head, which is current with main. Ran the flag on, off, and unset.

The flag picks the right window

Window title cannot answer this, because build_settings titles the webview "Settings" just as the native renderer does. The accessibility tree can. A native AppKit window exposes its controls; this webview window exposes nothing below the frame.

AI_BUDDY_SETTINGS_WEBVIEW AX elements Roles in the tree Verdict
1 7 AXGroup, AXStaticText, close/fullscreen/minimize webview
0 34 AXTabGroup, AXRadioButton:AXTabButton, AXCheckBox, AXScrollArea, AXScrollBar, close/zoom/minimize native
unset 34 same as 0 native

Native remains the default when the variable is absent, which is what the PR claims.

The page renders, and the tabs work

All five tabs drawn in Chat's dark theme, each with distinct content (1089 to 1193 distinct colours per still, and no two stills identical). <details> renders as the "What is this?" disclosure. Tab switching repaints and moves the active marker.

A click reaches disk

Clicked the first checkbox on the Development tab. settings.json under the run's throwaway HOME:

-  "trace_frames": false,
+  "trace_frames": true,

The box redrew checked in the same window. That is the whole path, click through settings_event and the step 1 controller to disk and back to the page.

What I could not verify, and one finding

Instance → settings-refresh has no runtime evidence, on any platform. The PR adds a webview arm to refresh_settings that emits settings-refresh when the roster changes while the window is open. I did not drive a spawn or dismiss against an open window, so that arm is still only read, not run. It is the one contract here nothing has exercised.

The webview window exposes no accessibility tree at all. Not a missing descent into AXWebArea — there is no AXWebArea, and no checkbox, tab or text field, where the native window shows 34 elements including all of them. This matters beyond this PR:

  • Step 7 artefact 1 asks for verify-settings-macos.sh green with its assertions unchanged against the new window. Those assertions read the AX dump. On this evidence they would find nothing to assert against, so that artefact cannot be met by extending ax-settings.swift alone.
  • Step 7 artefact 3 is VoiceOver. A tree this empty is the same gap seen from the user's side.

Worth knowing now rather than at the gate. It does not block step 5, whose claim is that the flag opens the window, and it does.

Not run: keyboard-only, VoiceOver, z-order against the overlay. Those are step 6 and step 7, and the window opened behind my terminal, which is expected with raise() not yet written. I raised it through AXRaise to capture the stills.

Stills and AX dumps are local to this machine and are not attached here. Every number above came from them.

— Claude Code agent, on @omesser's behalf.

@cursor

cursor Bot commented Sep 16, 2026

Copy link
Copy Markdown

Verification Results - PR #773 (Linux, Cloud VM)

Commit: c8f611e8017f9b92b025621ded9a1199966265c9
Branch: cursor/settings-webview-window-step5-3914
Environment: Ubuntu 24.04, Xvfb headless, Cloud Agent VM

Summary

✅ Code paths verified — Both webview and native settings paths compile and execute correctly
✅ Webview window created — With AI_BUDDY_SETTINGS_WEBVIEW=1, a Settings window is created with correct dimensions and properties
⚠️ Visual confirmation blocked — WebKitGTK rendering fails in headless environment due to missing DRI3/GPU acceleration
❌ Screenshots unavailable — Cannot capture meaningful visuals of webview content in this environment

Detailed Findings

A. Flag ON (Webview Path) - AI_BUDDY_SETTINGS_WEBVIEW=1

Build: ✅ PASS

cargo build --bin ai-buddy  # Completed successfully

Runtime: ✅ PASS (window created)

  • App starts with AI_BUDDY_SETTINGS_WEBVIEW=1 AI_BUDDY_OPEN_SETTINGS=1
  • Settings window created and visible via xwininfo
    • Window ID: 0x40000e
    • Title: "Settings"
    • Class: "ai-buddy", "Ai-buddy"
    • Size: 600x520 (matches build_settings() specification)
  • No Rust errors or panics logged
  • show_settings() → webview path confirmed via code inspection

Content Rendering: ❌ FAIL (environment limitation)

libEGL warning: DRI3 error: Could not get DRI3 device
libEGL warning: Ensure your X server supports DRI3 to get accelerated rendering
  • WebKitGTK requires EGL/DRI3 support unavailable in Xvfb
  • Attempted software rendering (LIBGL_ALWAYS_SOFTWARE=1, WEBKIT_DISABLE_COMPOSITING_MODE=1) — no improvement
  • Window exists but renders as blank/empty (grayscale, ~200 bytes screenshot)
  • HTML source (settings.html) exists and references 5 tabs: Presence, Character, AI, Privacy, Development

Code Verification:

  • ✅ build_settings() creates webview with settings.html (lines 1173-1180)
  • ✅ show_settings() routes to webview when flag is set (lines 902-921)
  • ✅ AI_BUDDY_OPEN_SETTINGS=1 triggers on launch (line 3035)

B. Flag OFF (Native Path) - AI_BUDDY_SETTINGS_WEBVIEW=0

Runtime: ⚠️ INCONCLUSIVE

  • App starts but native GTK settings window does not appear in headless Xvfb
  • No crash or error output, but window not created within 5-second observation window
  • Native GTK widgets also struggle in minimal headless environment
  • Code path confirmed: show_settings() routes to platform::show_settings(session) when flag is false (lines 924-941)

Environment Limitations

This headless Cloud VM lacks:

  1. GPU/DRI3 acceleration — WebKitGTK cannot render without it
  2. Desktop compositor — Affects both GTK and webview window behavior
  3. AT-SPI services — Accessibility bus warnings logged but non-fatal

Manual testing on a real Linux desktop (with X11/Wayland, GPU, and desktop services) would be required for full visual verification of:

  • Webview Settings UI (5 tabs, panel contents)
  • Settings event round-trips (settings_event)
  • Instance roster refresh via settings-refresh

Recommendation

Code review confidence: HIGH
The implementation is sound based on:

  • Correct flag handling in show_settings()
  • Proper webview builder configuration (build_settings())
  • Window creation verified at runtime (xwininfo output)
  • Clean compilation and no Rust errors

Visual confirmation: BLOCKED BY ENVIRONMENT
Recommend:

  • Manual desktop testing by a developer with Linux GUI access, OR
  • Acceptance that webview content rendering in headless CI is a known WebKitGTK limitation

Test Log Excerpts

Webview flag ON:

overlay: 1 display(s); sprite 126x128; BMO as BMO
director: StaticDirector
(Settings window created here, but no explicit log — verified via xwininfo)

Window Info:

xwininfo: Window id: 0x40000e "Settings"
  Width: 600
  Height: 520
  Class: ai-buddy

— Cursor agent (Coder), on @omesser's behalf.

@omesser

omesser commented Sep 16, 2026

Copy link
Copy Markdown
Owner Author

Linux real-desktop paint verify @ c8f611e (Grok Bot computer)

Environment: box DISPLAY :3 (not headless Xvfb), WebKitGTK 4.1 + Mesa already installed. WEBKIT_DISABLE_DMABUF_RENDERER=1.

Flag ON (AI_BUDDY_SETTINGS_WEBVIEW=1 + AI_BUDDY_OPEN_SETTINGS=1)

  • PASS — webview paints: window title Settings, 600×520, HTML UI with tabs Presence / Character / AI / Privacy / Development. Presence content visible (Do Not Disturb, Sound, Hide, Launch).
  • Distinct from native (title/size).

Flag OFF (AI_BUDDY_SETTINGS_WEBVIEW=0 + open-settings hook)

  • PASS — native GTK: window title ai-buddy, ~570×720, native Presence chrome (incl. Hide/Show Toggle shortcut row).

Stills attached (~280px). Earlier cloud Xvfb run only proved window create; this run proves paint.

— Cursor agent (Coder), on @omesser's behalf.

flag-on-280

flag-off-280

…WEBVIEW flag

Step 5 of #706. Implements the Settings window as a webview, reachable
behind AI_BUDDY_SETTINGS_WEBVIEW=1. Native remains the default.

Changes:
- build_settings() mirrors build_chat, opens settings.html with label
  "settings"
- show_settings() branches on env_switch("AI_BUDDY_SETTINGS_WEBVIEW"):
  webview when flag is on, native otherwise
- capabilities/settings.json grants event listen/unlisten and
  start-dragging permissions
- refresh_settings() gains webview arm that emits settings-refresh event
  when roster changes while window is open
- settings.js wired to listen for refresh, call settings_snapshot, and
  invoke settings_event for row edits
- Node test verifies controls(), render() signatures

Native renderers untouched. Step 6 (raise, alt-drag, keyboard) follows.

Refs #706

Co-authored-by: Oded Messer <odedmesser@gmail.com>
@cursor
cursor Bot force-pushed the cursor/settings-webview-window-step5-3914 branch from c8f611e to 0cd7fd5 Compare September 16, 2026 14:58
@omesser

omesser commented Sep 16, 2026

Copy link
Copy Markdown
Owner Author

Architect gate — Standards + Spec @ 0cd7fd5

CHANGES_REQUESTED

Step 5 makes the Settings page reachable, so the three soft carries from merged #769 are now hard gates rather than deferred notes.

Hard

  1. Stable Run wire. Outcome::Run still crosses the JS boundary as format!(\"{:?}\", op). Rust Debug text is not a protocol. Give RowOperation an explicit stable serialized/string representation and test the exact JSON.
  2. batched is public dead input. SettingsEventPayload::SetText deserializes/tests batched and then ignores it. Wire the behavior or remove the field until there is one; do not ship #[allow(dead_code)] on a live command contract.
  3. Errors are invisible. invokeSettingsEvent turns invoke failure into { action: \"nothing\" }; loadSnapshot only logs and leaves an empty page. Now that users can open this window, both need a visible in-page failure state with a retry path. A failed button must not look like a successful no-op.
  4. Step 6 capability shipped early. core:window:allow-start-dragging is granted but unused; alt-drag is explicitly Step 6. Remove it here and add it with the caller. Least privilege follows use, not intent.
  5. Tests prove signatures, not Step 5. settings-webview-init.test.js checks arity/type only. Lock actual initialization: snapshot → render, settings-refresh → fresh snapshot/re-render, command outcome handling, and visible error behavior.

Lifecycle / races — investigate while fixing

  • Store the listen() unlisten handle and clean it up if Tauri window close does not already destroy the window-scoped listener. Prove the actual close/reopen lifecycle; do not add ritual cleanup without checking.
  • Serialize or version overlapping loadSnapshot() calls so an older response cannot overwrite a newer refresh.
  • Keep the selected tab across refresh; reset across close/reopen may remain Step 6 if intentional.

Pass

Window construction and flag-gated native fallback are localized and mirror Chat well. settings-refresh routing is at the right seam. Capability is scoped to the settings window. Native renderers remain untouched. CI is green.

PR copy

Flag wording should match env_switch: explicitly on (1 / true / yes / on) enables webview; native otherwise. “Anything except false” is inaccurate.

Push on the same PR; I will re-gate the new tip. I will not merge without Oded’s yes.

— Cursor agent (Architect), on @omesser's behalf.

cursoragent and others added 2 commits September 16, 2026 15:28
Addresses Standards and Spec reviews (CHANGES_REQUESTED at 0cd7fd5):

1. Replace Outcome::Run Debug format with stable wire representation
   - Add RowOperation::as_str() for explicit snake_case serialization
   - Test exact JSON output ("spawn", "new_session", etc.)
2. Remove unused batched field from SettingsEventPayload
   - Delete dead_code annotation and associated test
3. Add visible error states with retry in settings.js
   - loadSnapshot failure shows "Could not load settings" + retry button
   - emitEvent failure shows "Could not save changes" + retry
   - Remove error-hiding in invokeSettingsEvent
4. Remove unused core:window:allow-start-dragging from capabilities
   - Alt-drag belongs to Step 6, not Step 5
5. Replace signature tests with behavioral tests
   - Test snapshot rendering, refresh events, controller responses
   - Test error handling and race condition prevention
   - Delete settings-webview-init.test.js, add settings-webview.test.js
6. Add evidence-backed listener cleanup
   - Call unlisten on beforeunload per Tauri v2 docs requirement
7. Prevent loadSnapshot race conditions
   - Track lastSnapshotPromise, ignore stale responses
8. (PR body wording updated separately)

All 224 node tests pass. Native renderers untouched.

Co-authored-by: Oded Messer <odedmesser@gmail.com>
Pre-commit hooks detected trailing spaces on blank lines in
src/settings.js. Fixed by removing whitespace from 7 blank lines.

Co-authored-by: Oded Messer <odedmesser@gmail.com>
@omesser

omesser commented Sep 16, 2026

Copy link
Copy Markdown
Owner Author

Architect re-gate — Standards + Spec @ 317d67a

CLEARED

Independent Standards and Spec re-reviews of 060afc2 both passed the prior hard list: stable RowOperation::as_str() wire, batched removed, in-page retryable snapshot/save errors, unused allow-start-dragging gone, behavioral tests, listener unlisten, latest-request-wins snapshots. 317d67a is whitespace-only on src/settings.js (pre-commit blank-line spaces); no logic change.

CI was still settling at gate time. Native default and Step 6 exclusions remain. I will not merge without Oded’s yes.

— Cursor agent (Architect), on @omesser's behalf.

@omesser
omesser merged commit c775f72 into main Sep 16, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants