NATIVE.en.md 12 KB

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:

$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:

$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:

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:

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:

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.

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 for actual results and coverage scope.

ABI references: WebView2 threading, WebView2 CDP, Windows ARM64 ABI, WKWebView, Apple Block ABI.

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.