WebView

WebView embeds a real browser engine inside the native widget tree — WKWebView on Apple platforms, WebView2 on Windows, WebKitGTK 6.0 on Linux, android.webkit.WebView on Android, and a sandboxed <iframe> on the web target. Use it for OAuth / payment flows, embedded admin pages, help / docs viewers, or any “show this URL as part of my app” surface. (Tracked under issue #658.)

import {
    WebView,
    webviewLoadUrl,
    webviewReload,
    webviewGoBack,
    webviewGoForward,
    webviewCanGoBack,
    webviewEvaluateJs,
    webviewClearCookies,
} from "perry/ui"

Scope. This is a “browser tab embedded in your native widget tree” primitive — explicit non-goals: a Tauri / Electron-style native↔JS RPC bridge, custom protocol / scheme handlers, DevTools, file downloads, WebGL / camera / mic / clipboard permission negotiation, service workers, WebRTC. If you need any of those, reach for Tauri or Electron; the rest of perry/ui still applies.

Basic Usage

const wv = WebView({
    url: "https://example.com",
    width: 800,
    height: 600,
})

App({
    title: "WebView Demo",
    width: 820,
    height: 640,
    body: wv,
})

WebView({...}) returns a Widget you can drop into any layout container. The widget tree’s layout engine controls final size — width and height are hints for the initial bounds.

OAuth / Callback Interception

The load-bearing use case. onShouldNavigate is a synchronous intercept invoked before each navigation; return false to cancel the load. Every backend’s should-load hook is itself sync on the main thread (decidePolicyForNavigationAction, NavigationStarting, shouldOverrideUrlLoading, decide-policy), so the contract is the same everywhere.

const authCode = State("")

const auth = WebView({
    url: "https://accounts.google.com/o/oauth2/auth?client_id=...&redirect_uri=https://myapp.com/oauth/callback&response_type=code&scope=email",
    // Hard host-level allowlist — blocked at the native delegate
    // without round-tripping into TS. Exact match or subdomain match
    // (so "google.com" allows "accounts.google.com").
    allowedDomains: ["accounts.google.com", "google.com", "myapp.com"],
    onShouldNavigate: (url) => {
        if (url.startsWith("https://myapp.com/oauth/callback?")) {
            const code = new URL(url).searchParams.get("code") ?? ""
            authCode.set(code)
            return false  // cancel — we already have what we need
        }
        return true
    },
    onLoaded: (url) => {
        // Fires after every successful page load.
    },
    onError: (code, message) => {
        // DNS / TLS / HTTP / cancellation all flow here.
    },
})

The allowedDomains allowlist is enforced at the native delegate layer — disallowed hosts never reach your onShouldNavigate. Treat it as defense-in-depth against a hijacked OAuth page redirecting the embedded session somewhere unexpected.

Imperative Navigation

Drive the WebView from outside (toolbar buttons, deep links, app-state changes):

// Navigate the WebView from outside (e.g. from a toolbar button).
webviewLoadUrl(wv, "https://perryts.com")
webviewReload(wv)
webviewGoBack(wv)
webviewGoForward(wv)
const hasHistory = webviewCanGoBack(wv)  // 1 or 0

Reading Page State

webviewEvaluateJs(handle, js, callback) runs a one-shot JS expression in the WebView’s content process and delivers the stringified result. Use this for “after the redirect lands, read document.cookie / localStorage.getItem(...)” — not as a general native↔JS RPC channel.

// Read state out of the loaded page after `onLoaded` fires. The
// callback gets the stringified return value (empty string on null /
// undefined / error). Plain string returns are JSON-unwrapped for
// ergonomic `document.cookie` reads.
const reader = WebView({
    url: "https://example.com/auth/callback",
    onLoaded: (_url) => {
        webviewEvaluateJs(reader, "document.cookie", (cookies) => {
            // parseCookies(cookies)
        })
    },
})

The callback receives an empty string on null / undefined / error. Plain string returns are JSON-unwrapped (so document.cookie reads clean, without surrounding quotes).

Cookie Isolation

ephemeral: true is the default — auth flows that silently reuse a user’s logged-in browser session are usually a footgun. Each backend maps this to its native equivalent at construction time:

To opt out:

// Opt out of ephemeral cookies so the user's session survives app
// restarts (like a regular browser profile).
const browser = WebView({
    url: "https://news.ycombinator.com",
    ephemeral: false,
    userAgent: "MyApp/1.0",
})

webviewClearCookies(handle) wipes the data store on demand — useful at logout, or between accounts:

// Wipe the WebView's cookies / localStorage / IndexedDB. Useful at
// logout, or between user accounts in a multi-tenant flow. No-op when
// `ephemeral: true` (the default), since there's nothing persisted to
// clear.
webviewClearCookies(wv)

API

Options

Platform Notes

Cross-Origin Messaging (Web Target)

On the web target, the embedded iframe can window.parent.postMessage out, and the host can window.addEventListener("message", ...) to receive. This is a browser-only pattern — native targets don’t expose postMessage (that’s the Tauri / Electron path Perry’s WebView deliberately avoids).

The portable contract that works on every target:

• Push state in with webviewEvaluateJs(wv, "window.someHook(...)").
• Pull state out by intercepting a known callback URL in onShouldNavigate.

Common Pitfalls

• Don’t reuse one WebView for unrelated sessions. Cookie isolation is per-WebView, not per-call. If you need to log a different user in, call webviewClearCookies(handle) first or destroy and recreate the widget.
• onShouldNavigate runs on the main thread. Keep it cheap — it blocks the navigation until you return. Heavy work belongs in onLoaded or off-thread via spawn.
• WebView2 runtime requirement on older Windows. WebView2 is preinstalled on Windows 10 1803+ and Windows Server 2019+. On older builds the runtime needs to be installed separately (Microsoft ships an evergreen bootstrapper).
• No bidirectional RPC. If you find yourself round-tripping structured data through webviewEvaluateJs callbacks, you’re past the design scope — pick Tauri / Electron instead, or move the logic out of the embedded page.

Next Steps

• Widgets — All available widgets
• State Management — React to onLoaded / onError from the rest of the UI
• Multi-Window — Pop a fresh window with a WebView for isolated sessions