feat(webview): Windows vtable fix + full verification stack + 3-OS CI e2e

The Windows 'COM apartment' blocker was a misdiagnosis. get_CoreWebView2
lives at vtable slot 25, not 3 — slot 3 on the controller is
get_IsVisible, which writes a BOOL into the out-pointer; reading that
back as ICoreWebView2* yields 1+garbage, crashing on any vtable access.
All vtable indices now verified against the official WebView2 SDK header
(Microsoft.Web.WebView2 nupkg):

- Windows backend: corrected indices; controller+CoreWebView2 AddRef'd
  and retained (post-open navigate works); title/url via
  get_DocumentTitle/get_Source; capture! via PrintWindow -> DIB -> BMP ->
  PowerShell PNG; put_Bounds sizes the webview to the client area;
  WM_CLOSE wired to on-close; HRESULT checks + stderr diagnostics
  throughout.
- Linux backend: capture! via gdk_pixbuf (get_from_window + savev png).
- open-window/open-webview #:devtools? (macOS setInspectable:, Windows
  OpenDevToolsWindow, Linux accepted-but-ignored).
- scripts/webview-e2e.rkt: cross-platform real-window e2e (open, title
  commit, capture, navigate, close, on-close) with exit codes; ALL PASS
  locally on macOS.
- CI: webview-e2e job on ubuntu (Xvfb + WebKitGTK + DMABUF workaround),
  windows, macOS.
- Docs: status matrices updated (honest 'pending CI verification' for
  Windows/Linux), CHANGELOG, AGENTS.md with the misdiagnosis story.

Author: turinglambdaai

.github/workflows/ci.yml

@@ -38,6 +38,48 @@ jobs:
         run: raco fmt --check glaze-lib/ glaze-cli/ glaze-test/
         continue-on-error: true
 
+  webview-e2e:
+    # Real-window WebView end-to-end on each OS: open -> load (title
+    # commits) -> capture -> navigate -> close -> on-close. Windows needs
+    # nothing extra (WebView2 runtime is preinstalled); Linux runs under
+    # Xvfb with the WebKitGTK packages.
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macOS-latest]
+        racket-version: ['8.12']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Racket
+        uses: Bogdanp/setup-racket@v1.11
+        with:
+          version: ${{ matrix.racket-version }}
+
+      - name: Install Glaze packages
+        run: |
+          raco pkg install --no-docs --link ./glaze-lib
+          raco pkg install --link ./glaze
+
+      - name: Install webview deps (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev xvfb
+
+      - name: Run webview e2e
+        env:
+          WEBKIT_DISABLE_DMABUF_RENDERER: '1'
+        shell: bash
+        run: |
+          if [ "$RUNNER_OS" = "Linux" ]; then
+            xvfb-run -a racket scripts/webview-e2e.rkt
+          else
+            racket scripts/webview-e2e.rkt
+          fi
+
   package:
     # Build a sample app with `raco glaze build --installer` on each platform
     # and upload the resulting distribution + installer as artifacts.

AGENTS.md

@@ -19,9 +19,9 @@ Glaze 是 "Tauri-like framework for Racket"——Racket 写后端，Web 技术
 
 | 平台 | 状态 | 说明 |
 |------|------|------|
-| macOS | ✅ 端到端可用 | NSWindow + WKWebView（objc FFI），含验证 API |
-| Windows | ⚠️ experimental | COM 初始化链已通，`Navigate` 卡在 STA 生命周期问题，见 `webview-windows.rkt` 头注释 |
-| Linux | 🔲 骨架 | GtkWindow + WebKitGTK 绑定未接线，见 `webview-linux.rkt` |
+| macOS | ✅ 端到端可用 | NSWindow + WKWebView（objc FFI），含验证 API + devtools |
+| Windows | 🔄 修复待 CI 验证 | 历史上卡在"COM apartment"——真相是 `get_CoreWebView2` vtable 索引错（25 被写成 3，实际调了 `get_IsVisible`）。vtable 顺序已对官方 SDK 头文件逐一核对，详见 `webview-windows.rkt` 头注释 |
+| Linux | 🔄 待 CI 验证 | 泵结构 + destroy 回调 + title/url/capture 已接线，Xvfb CI e2e |
 
 ## 快速命令
 

CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [0.3.0] - Unreleased
 
+### Fixed (Phase 3, in progress)
+- **Windows WebView2 root cause found and fixed**: the long-standing
+  "COM apartment" diagnosis was wrong — `get_CoreWebView2` was being called
+  at vtable slot 3 (actually `get_IsVisible`, which writes a BOOL into the
+  out-pointer), yielding a garbage pointer that crashed on any vtable
+  access. All vtable indices are now verified against the official
+  Microsoft.Web.WebView2 SDK header. The backend additionally: AddRefs and
+  retains the controller/CoreWebView2 for post-open navigate, implements
+  title/url (get_DocumentTitle / get_Source) and capture! (PrintWindow +
+  PowerShell BMP->PNG), sizes the WebView to the client area, and wires
+  WM_CLOSE to on-close. Runtime verification pending the new CI e2e job.
+- Linux backend: capture! via gdk_pixbuf; CI e2e job added (Xvfb +
+  WebKitGTK) alongside macOS/Windows real-window e2e.
+- `open-window`/`open-webview` accept `#:devtools?` (macOS:
+  setInspectable:; Windows: OpenDevToolsWindow; Linux: not yet).
+
 ### Added (Phase 3, in progress)
 - **JavaScript bridge** (`glaze/api`): real JSON routing over the frontend
   server — `GET`/`POST`/`PUT`/`DELETE` route values with `:param` capture,

README.md

@@ -28,7 +28,7 @@ You get:
 | Agent-friendly UI verification (`title`/`url`/screenshot) | **built-in** | via WebDriver | via CDP | limited |
 | WebView backends | WebView2 / WKWebView / WebKitGTK | same | bundled Chromium | WebView2/WKWebView |
 
-The honest gaps today: Windows webview is experimental (see status below), no devtools wiring, no typed IPC layer — plain JSON.
+The honest gaps today: Windows/Linux webview runtime verification is pending CI (see status below); no typed IPC layer — plain JSON.
 
 ## Platform status
 
@@ -37,9 +37,10 @@ The honest gaps today: Windows webview is experimental (see status below), no de
 | HTTP server + browser | ✅ | ✅ | ✅ |
 | System tray | ✅ | ✅ | ✅ (CI-verified) |
 | JSON API bridge | ✅ | ✅ | ✅ |
-| Native webview window | ✅ verified end-to-end | ⚠️ experimental (WebView2 init works; `Navigate` pending a COM fix) | 🔲 structural, not runtime-verified |
-| `webview-title` / `webview-url` | ✅ | partial (url) | partial (url) |
-| `webview-capture!` (screenshot) | ✅ | 🔲 | 🔲 |
+| Native webview window | ✅ verified end-to-end | 🔄 fixed against official SDK header; CI e2e pending | 🔄 structural; CI e2e (Xvfb) pending |
+| `webview-title` / `webview-url` | ✅ | 🔄 implemented (`get_DocumentTitle`/`get_Source`); CI pending | 🔄 implemented; CI pending |
+| `webview-capture!` (screenshot) | ✅ | 🔄 implemented (PrintWindow + PowerShell PNG); CI pending | 🔄 implemented (gdk_pixbuf); CI pending |
+| `#:devtools?` | ✅ (inspectable, macOS 13+) | ✅ (`OpenDevToolsWindow`) | 🔲 |
 
 Without a native backend, `run-app` / `open-window` automatically fall back to the system browser — the app still works everywhere.
 

README.zh-CN.md

@@ -28,7 +28,7 @@ Racket 自带的 `racket/gui` 可以用，但很难做出现代化的产品级 U
 | Agent 友好的 UI 验证（title/url/截图） | **内置** | 需 WebDriver | 需 CDP | 有限 |
 | WebView 后端 | WebView2 / WKWebView / WebKitGTK | 相同 | 自带 Chromium | WebView2/WKWebView |
 
-当前的诚实差距：Windows WebView 尚在实验阶段（见下表状态）、未接 devtools、IPC 为纯 JSON 无类型层。
+当前的诚实差距：Windows/Linux WebView 的真机验证待 CI 跑通（见下表状态）、IPC 为纯 JSON 无类型层。
 
 ## 平台支持状态
 
@@ -37,9 +37,10 @@ Racket 自带的 `racket/gui` 可以用，但很难做出现代化的产品级 U
 | HTTP 服务器 + 浏览器 | ✅ | ✅ | ✅ |
 | 系统托盘 | ✅ | ✅ | ✅（CI 验证） |
 | JSON API 桥接 | ✅ | ✅ | ✅ |
-| 原生 WebView 窗口 | ✅ 端到端验证 | ⚠️ 实验性（WebView2 初始化已通；`Navigate` 待修 COM 问题） | 🔲 结构完整，未真机验证 |
-| `webview-title` / `webview-url` | ✅ | 部分（url） | 部分（url） |
-| `webview-capture!`（截图） | ✅ | 🔲 | 🔲 |
+| 原生 WebView 窗口 | ✅ 端到端验证 | 🔄 已按官方 SDK 头文件修正，待 CI 验证 | 🔄 结构完整，待 CI（Xvfb）验证 |
+| `webview-title` / `webview-url` | ✅ | 🔄 已实现（`get_DocumentTitle`/`get_Source`），待 CI | 🔄 已实现，待 CI |
+| `webview-capture!`（截图） | ✅ | 🔄 已实现（PrintWindow + PowerShell 转 PNG），待 CI | 🔄 已实现（gdk_pixbuf），待 CI |
+| `#:devtools?` | ✅（inspectable，macOS 13+） | ✅（`OpenDevToolsWindow`） | 🔲 |
 
 原生后端不可用时，`run-app` / `open-window` 自动回退系统浏览器 —— 应用在所有平台都能跑。
 

glaze-lib/webview/main.rkt

@@ -66,19 +66,22 @@
                      #:title [title "Glaze"]
                      #:width [width 1024]
                      #:height [height 768]
+                     #:devtools? [devtools? #f]
                      #:on-close [on-close (lambda () (void))]
                      #:fallback-browser? [fallback? #f])
   (open-webview url
                 #:title title
                 #:width width
                 #:height height
+                #:devtools? devtools?
                 #:on-close on-close
                 #:fallback-browser? fallback?))
 
 (define (open-webview url
                       #:title [title "Glaze"]
                       #:width [width 1024]
                       #:height [height 768]
+                      #:devtools? [devtools? #f]
                       #:on-close [on-close (lambda () (void))]
                       #:fallback-browser? [fallback? #f])
   (define h
@@ -88,7 +91,12 @@
                                           (exn-message e))
                                  (displayln "use open-browser as fallback." (current-error-port))
                                  #f)])
-      ((ref 'open-webview) url #:title title #:width width #:height height #:on-close on-close)))
+      ((ref 'open-webview) url
+        #:title title
+        #:width width
+        #:height height
+        #:devtools? devtools?
+        #:on-close on-close)))
   (cond
     [h (webview (detected-backend) h)]
     [fallback? (open-browser url) #f]

glaze-lib/webview/webview-linux.rkt

@@ -25,6 +25,7 @@
 ;;     and kept alive forever (GTK stores the raw pointer).
 
 (require ffi/unsafe
+         racket/file
          racket/path
          racket/string)
 
@@ -128,6 +129,7 @@
                       #:title [title "Glaze"]
                       #:width [width 1024]
                       #:height [height 768]
+                      #:devtools? [devtools? #f]
                       #:on-close [on-close (lambda () (void))])
   (unless (supported?)
     (error 'open-webview "Linux WebView backend not available"))
@@ -167,5 +169,45 @@
     (define u (webkit_web_view_get_uri (lin:webview-webview wv)))
     (and (non-empty-string? u) u)))
 
+;; Window capture via GDK: gdk_pixbuf_get_from_window on the window's
+;; GdkWindow, then gdk_pixbuf_savev to PNG ("png" handler ships with GTK).
+(define gdk-pixbuf-lib
+  (with-handlers ([exn:fail? (lambda (e) #f)])
+    (ffi-lib "gdk_pixbuf-2.0" '("0" #f))))
+(define gtk_widget_get_window
+  (maybe-bind gtk-lib "gtk_widget_get_window" (_fun _pointer -> _pointer)))
+(define gdk_pixbuf_get_from_window
+  (and gdk-pixbuf-lib
+       (get-ffi-obj "gdk_pixbuf_get_from_window"
+                    gdk-pixbuf-lib
+                    (_fun _pointer _int _int _int _int -> _pointer)
+                    (lambda () #f))))
+(define gdk_pixbuf_savev
+  (and gdk-pixbuf-lib
+       (get-ffi-obj "gdk_pixbuf_savev"
+                    gdk-pixbuf-lib
+                    (_fun _pointer _string _string _pointer _pointer _pointer -> _bool)
+                    (lambda () #f))))
+
 (define (capture! wv [dest #f])
-  #f)
+  (and (not (unbox (lin:webview-closed?-box wv)))
+       gtk_widget_get_window
+       gdk_pixbuf_get_from_window
+       gdk_pixbuf_savev
+       (let ()
+         (define gdkwin (gtk_widget_get_window (lin:webview-window wv)))
+         (and gdkwin
+              (let ()
+                (define pixbuf (gdk_pixbuf_get_from_window gdkwin 0 0 -1 -1))
+                (and pixbuf
+                     (let ()
+                       (define path
+                         (if dest
+                             (if (string? dest) (string->path dest) dest)
+                             (make-temporary-file "glaze-capture-~a.png")))
+                       (define ok?
+                         (gdk_pixbuf_savev pixbuf
+                                           (path->string path)
+                                           "png"
+                                           #f #f #f))
+                       (and ok? path))))))))

glaze-lib/webview/webview-macos.rkt

@@ -200,6 +200,7 @@
                       #:title [title "Glaze"]
                       #:width [width 1024]
                       #:height [height 768]
+                      #:devtools? [devtools? #f]
                       #:on-close [on-close (lambda () (void))])
   (unless (supported?)
     (error 'open-webview "macOS WebView backend unavailable (WebKit failed to load)"))
@@ -240,6 +241,11 @@
          #:type _uint
          (bitwise-ior NSViewWidthSizable NSViewHeightSizable))
   (tellv window setContentView: #:type _id webview)
+  ;; #:devtools? makes WKWebView inspectable (macOS 13+); on older systems
+  ;; web inspectors need a bundle-local override — ignored here.
+  (when (and devtools?
+             (tell webview respondsToSelector: #:type _SEL (selector setInspectable:)))
+    (tellv webview setInspectable: #:type _bool #t))
 
   ;; Delegate forwards windowWillClose: to the on-close thunk and flags the
   ;; closed?-box so the pump loop exits. Registry key: the window's pointer.

glaze-lib/webview/webview-stub.rkt

@@ -19,6 +19,7 @@
                       #:title [title "Glaze"]
                       #:width [width 1024]
                       #:height [height 768]
+                      #:devtools? [devtools? #f]
                       #:on-close [on-close (lambda () (void))])
   #f)