[Proposal] Add a formal WebView2 bridge for native ↔ SPA communication

[AlexAlves87]

Right now WebChatWindow and CanvasWindow both load gateway content in WebView2, but there's no formal communication channel between the native C# side and the embedded SPA. The two halves run disconnected, which shows up in a few places already:

Surface	Current situation
WebChatWindow	No bridge at all. Native code has no way to signal UI state to the SPA (recording indicator, draft text, activity spinner)
CanvasWindow	One-way native→web channel via ExecuteScriptAsync with 11 heuristic fallbacks. No web→native channel
Voice PR #120 (NichUK)	Works around the gap with DOM scraping (querySelector, MutationObserver, descriptor hacks). The author describes it as fragile
Screen record PR #159	No way to show a recording indicator in the SPA while the app is capturing
QuickSendDialog	Can send messages over WebSocket but can't coordinate UI state with the embedded chat

The fix

WebView2 ships a proper bidirectional bridge that doesn't touch the DOM at all:

Native → SPA

// Inject bootstrap before any page scripts run
await webView.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync(BridgeInitScript);

// Send a message at any point
webView.CoreWebView2.PostWebMessageAsJson(JsonSerializer.Serialize(msg));

SPA → Native

webView.CoreWebView2.WebMessageReceived += (_, e) => {
    var msg = JsonSerializer.Deserialize<BridgeMessage>(e.WebMessageAsJson);
    HandleBridgeMessage(msg);
};

Gateway SPA side

// Receive from native
window.chrome.webview.addEventListener('message', e => {
    const msg = e.data; // { type, payload }
    // dispatch by type
});

// Send to native
window.chrome.webview.postMessage({ type: 'ready' });

Minimal message contract to start

{ "type": "recording-start", "payload": {} }
{ "type": "recording-stop",  "payload": {} }
{ "type": "voice-start",     "payload": {} }
{ "type": "voice-stop",      "payload": {} }
{ "type": "draft-text",      "payload": { "text": "..." } }
{ "type": "ready",           "payload": {} }

Scope

This touches two repos:

1. This repo — wire the bridge in WebChatWindow.xaml.cs and CanvasWindow.xaml.cs
2. Gateway — expose the window.chrome.webview listener in the SPA

The existing WebSocket transport (chat.send) stays as-is — it handles chat messages. The bridge is purely for UI state coordination.

Happy to put together a PR for the Windows side once there's alignment on the gateway contract.

Related

• Add first-pass Windows Voice Mode #120 (NichUK, Voice Mode) — the DOM scraping approach there would be cleanly replaced by this
• feat: add screen recording capability #159 (screen recording) — needs a recording-active indicator in the chat view

[github-actions]

🤖 This is an automated response from Repo Assist.

Great proposal, @AlexAlves87 — the gap you've described is real and the WebView2 PostWebMessageAsJson / WebMessageReceived API is exactly the right fix.

A few notes from looking at the existing code:

Current state

Window	Inbound (SPA→native)	Outbound (native→SPA)
WebChatWindow	❌ none	❌ none
CanvasWindow	❌ none	⚠️ ExecuteScriptAsync with 11 heuristic fallbacks (the fragile pattern you described)

window.chrome.webview is automatically available in any WebView2-hosted page — no bootstrap injection needed on the native side. That keeps the wiring minimal.

Impact on open PRs

• Add first-pass Windows Voice Mode #120 Voice Mode — NichUK's MutationObserver/querySelector hacks would be cleanly replaced by voice-start/voice-stop bridge messages
• feat: add screen recording capability #159 Screen recording — recording indicator in the SPA would land via recording-start/recording-stop

PR

I've opened a draft PR ([#aw_pr191br]) that wires the full bidirectional bridge on the Windows side of WebChatWindow:

• CoreWebView2.WebMessageReceived → fires a BridgeMessageReceived event on the window (SPA→native)
• PostBridgeMessage(string type, object? payload) method (native→SPA via PostWebMessageAsJson)
• WebBridgeMessage record in OpenClaw.Shared with TryParse/ToJson and the well-known type constants from your proposal
• Handler stored and cleaned up in OnWindowClosed — no leak

Callers in App.xaml.cs can subscribe to BridgeMessageReceived and call PostBridgeMessage once the gateway SPA side exposes the listener.

The SPA-side change (adding window.chrome.webview.addEventListener('message', ...) to the gateway) is out of scope for this repo — that's the remaining piece to close the loop.

Generated by 🌈 Repo Assist, see workflow run. Learn more.

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@97143ac59cb3a13ef2a77581f929f06719c7402a