# Native WebView backends: implementation, deployment and tests Native feature increment (2026-11-06), based on `cfbrowser-202611060942.zip`. Windows and macOS now contain actual native adapters, marked experimental. They cross-compile in this delivery, but have not been executed on their target operating systems. Build success and `doctor` output are not runtime acceptance. ## Platforms and capabilities | Platform | Worker engine | Requirements | | --- | --- | --- | | Windows amd64/arm64 | WebView2 Environment/Controller, COM/Win32 | Matching Evergreen WebView2 Runtime and a logged-in desktop session | | macOS amd64/arm64 | System WKWebView through purego/objc | macOS 11+ and a logged-in GUI session | | Linux amd64/arm64 | GTK3/WebKitGTK 4.1 through purego | Correct system ABI and a display; Xvfb is an option for CI | All workers build with `CGO_ENABLED=0`, without a C/Objective-C/Swift compiler, Node or a WebDriver service. Native operating-system runtimes remain dependencies. This does not change Wails' own build requirements. | Feature | Native status | | --- | --- | | goto/back/forward/reload, page creation/closure | Implemented | | Named isolated worlds, JSON evaluation, DOM snapshots and references | Implemented | | Synthetic click/fill/check/uncheck/select/scroll | Implemented; results identify synthetic input | | Text, tables, polling waits and context cancellation | Implemented | | Shared cookies within a session, isolation between sessions | Implemented; must pass target-platform integration tests | | Open Shadow DOM snapshots, references, reads and waits | Implemented across native platforms; closed roots excluded | | Browser-generated click/hover/fill/type/press | Implemented on Windows; macOS/Linux unsupported | | Viewport PNG capture | Implemented on all native platforms; target runtime acceptance required | | Bounded full-page capture | Windows only; maximum 4096 x 4096 pixels and 4 MiB | | Downloads, upload, AX, cross-origin frames, persistent profiles, handoff UI, proxy | Unsupported | | Displayless native operation, strict network isolation | Unsupported; networkPolicy remains degraded | Native windows are hidden by default; `--headed` shows them from startup. A hidden native view is not a displayless browser. WebView2 evaluation uses its native COM CDP channel, without launching full Edge, exposing a debugging port or installing a page-to-Go message bridge. ## Windows runtime acceptance From the repository root in PowerShell: ```powershell $env:CGO_ENABLED = "0" go build -buildvcs=false -mod=vendor -o bin/cfbrowser.exe ./cmd/cfbrowser go build -buildvcs=false -mod=vendor -o bin/cfbrowser-worker.exe ./cmd/cfbrowser-worker .\bin\cfbrowser.exe --engine native --worker "$PWD\bin\cfbrowser-worker.exe" --diagnostics demo .\scripts\test-native.ps1 ``` Do not pass `--browser msedge.exe` for native mode. An installed full Edge browser is not proof that Evergreen WebView2 Runtime is available. Configuration failures return `BROWSER_RUNTIME_UNAVAILABLE`; an early worker exit can instead return `BROWSER_WORKER_EXITED`, with details on stderr. Success contains `"status":"passed"`, session/page IDs and the extracted fixture table. Native mode returns managed viewport screenshot metadata. Add `--headed` before `demo` to inspect the native window; the demo closes quickly. The script builds the worker, executes ABI tests and the demo, then runs native-only integrations. It fails on any failed command, never falls back to CDP and does not disable the sandbox. To run integration tests separately: ```powershell $env:CFBROWSER_INTEGRATION = "1" $env:CFBROWSER_TEST_ENGINE = "native" $env:CFBROWSER_WORKER = "$PWD\bin\cfbrowser-worker.exe" go test -buildvcs=false -mod=vendor ./integration -count=1 -v -timeout=180s ``` ## macOS runtime acceptance Use Terminal in a logged-in graphical session, from the repository root: ```sh CGO_ENABLED=0 go build -buildvcs=false -mod=vendor -o bin/cfbrowser ./cmd/cfbrowser CGO_ENABLED=0 go build -buildvcs=false -mod=vendor -o bin/cfbrowser-worker ./cmd/cfbrowser-worker ./bin/cfbrowser --engine native --worker "$PWD/bin/cfbrowser-worker" --diagnostics demo sh scripts/test-native.sh ``` The platform unit test invokes an actual copied Objective-C block, checks Go callback ABI and exercises `_Block_copy`/`_Block_release` ownership. Integration tests create real WKWebViews. For application distribution, an optional bundle helper is included. Python is only a packaging convenience, never a worker runtime dependency: ```sh python3 scripts/package-macos-worker.py bin/cfbrowser-worker bin/CFBrowserWorker.app ./bin/cfbrowser --engine native --worker "$PWD/bin/CFBrowserWorker.app/Contents/MacOS/cfbrowser-worker" --diagnostics demo ``` Launch `Contents/MacOS/cfbrowser-worker` directly, not through `open`, so private stdin/stdout pipes remain connected. Info.plist declares macOS 11+, LSUIElement and ATS allowances for intentional browser Web content and local HTTP, including SSH tunnels. The packaging helper refuses to overwrite a destination; use a new bundle path or your release process. Sign the nested worker/bundle before the outer application and notarize the final app using ClusterFlow's established Developer ID/entitlement policy. Validate WebKit subprocess startup, networking and shutdown in the real signed installation. Signing, hardened-runtime and notarization acceptance have not been performed here. SSH-only or LaunchDaemon operation without a GUI is outside the current scope. ## Native bridge and lifecycle Windows/macOS share the `internal/nativehost` dispatcher. Protocol goroutines cannot call UI objects directly. The queue holds 32 tasks; each worker admits 16 pages, viewports of 1–4096 pixels per axis and at most 32 native evaluations in flight. The SDK adds its own stricter quotas and per-page sequencing. Scripts/results respect the 512 KiB framed protocol budget. Raw Evaluate remains a trusted-host interface, never an Agent tool. Windows pins its initialization thread, creates a COM STA, owns a hidden HWND per page and pumps Win32 messages. It reuses only the pinned `go-webview2 v1.0.22` Go loader and COM lifetime bridge; narrow local wrappers follow the published ABI. The default Go loader does not need a side-by-side WebView2Loader.dll. Do not add the optional `native_webview2loader` build tag. Pointer arguments use `uintptrescapes`; amd64 passes the 16-byte RECT by address, while arm64 uses two integer registers. Each session owns a private `webview2-profile` and Environment; pages own Controllers. Evaluation follows `Page.getFrameTree`, `Page.createIsolatedWorld`, then `Runtime.evaluate` in `cfbrowser-isolated`. The same world preserves global state and DOM object references. Navigation completion is correlated with navigation IDs. Cleanup removes events, closes Controllers, releases COM references/HWNDs and briefly waits for owned browser PIDs. macOS pins the process main thread in `main.init` and loads Cocoa/WebKit dynamically. Pages share one nonpersistent WKWebsiteDataStore and named WKContentWorld per worker. A no-op WKUserScript retains the world across evaluations. Each page retains NSWindow/WKWebView/delegate objects. NSApplication iterations and a rotating autorelease pool drive callbacks. Evaluation JSON-stringifies results before copying bounded NSString UTF-8 data into Go memory. Completion blocks are allocated in native heap memory and contain integer tokens only. A Go registry retains callback closures while WebKit copies/releases the native blocks. Page closure removes registry entries; late callbacks are ignored. Block descriptors/signatures survive until process exit to avoid freeing metadata before framework-owned blocks. One fixed trampoline serves all evaluations rather than consuming a purego callback slot for every call. Cancellation does not undo already-dispatched JavaScript/navigation. Canceled page creation closes the page in its completion callback. Closing a page immediately completes pending evaluations and releases their quota; late native callbacks cannot complete them twice. After a timeout, observe the page before deciding what to do; do not automatically replay side effects. EOF shuts down the worker; the host waits two seconds before killing that worker. Windows Job Objects, Unix process-group termination and crash recovery are not implemented, and forced host death is not guaranteed to leave no WebView child process. ## ClusterFlow integration Replace only the underlying driver; the eight Agent tools, Owner mapping, grants and cancellation integration remain compatible: ```go manager, err := cfbrowser.New(cfbrowser.Config{ Timeout: 30 * time.Second, }, &native.Driver{WorkerPath: absoluteWorkerPath}) ``` Import `native "clusterflow.dev/cfbrowser/driver/native"`. Resolve the worker from a trusted application installation path, never model arguments. A session owns its worker; external pages do not reuse the Wails frontend WebView or gain access to its bridge. Close runs/workspaces through the existing Manager lifecycle. No Wails migration or frontend UI is required. When the host uses vendor mode, run `go mod tidy` and `go mod vendor` in the actual application module and distribute its matching worker. See [INTEGRATION.en.md](INTEGRATION.en.md). ## Test contract Portable tests cover dispatch, quotas, configuration, cancellation, errors, JSON limits, EOF and pump failure. Windows tests validate COM callbacks/vtables, UTF-16 and Win32 layouts. macOS tests validate copied blocks, callback ABI and ownership. New real-engine tests check isolated globals, world persistence, DOM object identity, script exceptions, navigation state reset and native viewport dimensions. Existing integration tests cover dynamic forms/tables, stale references, cancellation, scope, cookies within/across sessions, history and closure. Native download tests skip explicitly because that capability is unsupported; skips are not successful download validation. A GitHub Actions workflow provides Windows/macOS native execution, but has not been triggered or observed for this delivery. Run the scripts on target machines, inspect all expected tests, then validate the signed application package. See [VALIDATION.en.md](VALIDATION.en.md) for actual results and coverage scope. ABI references: [WebView2 threading](https://learn.microsoft.com/en-us/microsoft-edge/webview2/concepts/threading-model), [WebView2 CDP](https://learn.microsoft.com/en-us/microsoft-edge/webview2/how-to/chromium-devtools-protocol), [Windows ARM64 ABI](https://learn.microsoft.com/en-us/cpp/build/arm64-windows-abi-conventions), [WKWebView](https://developer.apple.com/documentation/webkit/wkwebview), [Apple Block ABI](https://clang.llvm.org/docs/Block-ABI-Apple.html). ## Native feature increment (2026-11-06) Open Shadow DOM traversal and viewport PNG capture are implemented on all three platforms. Windows additionally implements browser-generated click/hover/fill/type/press and bounded full-page capture. macOS/Linux retain synthetic input; select/check/scroll remain synthetic on Windows too. Full-page capture is limited to 4096 x 4096 pixels and 4 MiB; oversized documents fail explicitly. Closed roots, cross-origin frames, AX, native downloads/uploads, persistent profiles, handoff and proxy mapping remain unavailable. Windows/macOS runtime acceptance must run on target machines; compilation is not runtime evidence. The RPC envelope stays v1. New SDKs check `session.features` generation 2 after configuration and reject old workers with `BROWSER_WORKER_OUTDATED`. Rebuild and ship the SDK consumer and worker together. PNG bytes use random private files consumed by the SDK, keeping the 512 KiB RPC bound. Use `CapturePage(..., true)` or optional `fullPage: true` on `cf_browser_capture`.