@sigx/lynx-webview 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Andreas Ekdahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+# @sigx/lynx-webview
+
+Native WebView component for sigx-lynx. `WKWebView` on iOS, `android.webkit.WebView` on Android.
+
+Use for: OAuth fallback flows, embedded help / TOS / changelog pages, hybrid screens during an incremental migration to native.
+
+> **Not Lynx's `<webview>`.** ByteDance's Lynx team has confirmed they ship a `<webview>` element internally, but it isn't open-sourced ([lynx-family/lynx#627](https://github.com/lynx-family/lynx/issues/627)). This package registers a sigx-flavored `<sigx-webview>` so apps can ship today.
+
+## Install
+
+```bash
+pnpm add @sigx/lynx-webview
+```
+
+`sigx prebuild` auto-discovers the package and:
+- iOS: emits a `GeneratedComponentRegistry.swift` call to `LynxConfig.registerUI(SigxWebViewUI.self, withName: "sigx-webview")` in `LynxSetupService.initialize`.
+- Android: emits a `GeneratedBehaviors.attachAll(builder)` call alongside the existing `XElementBehaviors().create()` in `MainActivity.kt` and the dev-client path.
+
+No app-side wiring required.
+
+## Usage
+
+```tsx
+import { WebView } from '@sigx/lynx-webview';
+
+<WebView
+    src="https://example.com"
+    onLoad={(e) => console.log('loaded', e.detail.url)}
+    onError={(e) => console.warn('failed', e.detail.message)}
+    onMessage={(e) => console.log('page said', e.detail.data)}
+/>
+```
+
+Inline HTML works too — no network:
+
+```tsx
+<WebView html="<h1>Hello from sigx-lynx</h1>" />
+```
+
+### Page → app messaging
+
+The native side injects `window.sigx.postMessage(payload)` at document start. Any page rendered inside the WebView can call it; the payload arrives in JS as `event.detail.data` (always a string).
+
+```html
+<button onclick="window.sigx.postMessage(JSON.stringify({ click: 'hi' }))">
+  Send
+</button>
+```
+
+```tsx
+<WebView
+    html={pageHtml}
+    onMessage={(e) => {
+        const data = JSON.parse(e.detail.data);
+        // data.click === 'hi'
+    }}
+/>
+```
+
+### Imperative methods (v2)
+
+Two valid call patterns depending on which thread your handler runs on. **There is no one-size-fits-all helper** — `MainThread.Element` only lives on the MT side, and `SelectorQuery` only works from BG.
+
+**Pattern A — from a main-thread tap handler (recommended for toolbar buttons).** Capture a `MainThreadRef`, then call `.invoke()` directly on `ref.current` inside a `'main thread'` handler. Bind the handler to a raw `<view main-thread:bindtap=…>` element — daisyui's `<Button>` only exposes an `onPress` callback (BG-thread) and silently drops `main-thread:bindtap`, so the tap would never reach the handler.
+
+```tsx
+import { useMainThreadRef, type MainThread } from '@sigx/lynx';
+import { WebView } from '@sigx/lynx-webview';
+
+const ref = useMainThreadRef<MainThread.Element | null>(null);
+
+const onBack = () => {
+    'main thread';
+    ref.current?.invoke('goBack', {});
+};
+const onReload = () => {
+    'main thread';
+    ref.current?.invoke('reload', {});
+};
+
+<WebView mtRef={ref} id="my-webview" src="https://example.com" />
+<view main-thread:bindtap={onBack}><Text>‹ Back</Text></view>
+<view main-thread:bindtap={onReload}><Text>↻ Reload</Text></view>
+```
+
+The `'main thread'` directive compiles the handler into a separate main-thread bundle that can't reach cross-package imports — so you must call `.invoke()` directly, not via a JS wrapper from another package.
+
+**Pattern B — from a BG-thread handler (e.g. daisyui `<Button onPress>`).** Use Lynx's `SelectorQuery` to dispatch by element id. Give the WebView an `id` and select by it.
+
+```tsx
+import { Button } from '@sigx/lynx-daisyui';
+
+<WebView id="my-webview" src="https://example.com" />
+<Button onPress={() => {
+    lynx.createSelectorQuery().select('#my-webview').invoke({
+        method: 'reload',
+        params: {},
+        success: () => {},
+        fail: (e) => console.warn(e),
+    }).exec();
+}}>
+    Reload
+</Button>
+```
+
+A typed wrapper that bundles this is exported as `WebViewMethods` for apps that prefer not to write the `SelectorQuery` boilerplate by hand — but note it only works when the relevant `MainThread.Element` is reachable (i.e. inside a `runOnMainThread` block, not from a bare `onPress`).
+
+| Method | Signature | Notes |
+|---|---|---|
+| `goBack` | `(el)` → `void` | No-op when no back history. |
+| `goForward` | `(el)` → `void` | No-op when no forward history. |
+| `reload` | `(el)` → `void` | |
+| `stopLoading` | `(el)` → `void` | |
+| `canGoBack` | `(el)` → `Promise<boolean>` | Resolves `false` when `el` is null. |
+| `canGoForward` | `(el)` → `Promise<boolean>` | Same. |
+| `injectJavaScript` | `(el, code)` → `Promise<string>` | Last-expression value, stringified. Non-string results (numbers, dicts) coerce via `String(result)`. `null` / `undefined` → `""`. |
+| `postMessage` | `(el, data)` → `void` | Delivers to `window.sigx.onmessage(data)` inside the page. Pages that haven't subscribed get a silent no-op. |
+
+Host → page subscription happens in the page itself:
+
+```html
+<script>
+  window.sigx.onmessage = function(data) {
+    console.log('from host', data);
+  };
+</script>
+```
+
+All `WebViewMethods.*` accept `el | null` and no-op when null, so you can pass `ref.current` straight through without an `if` guard.
+
+The same methods are also reachable via Lynx's `SelectorQuery` API for apps that prefer ID-based dispatch:
+
+```ts
+lynx.createSelectorQuery().select('#my-webview').invoke({
+    method: 'reload',
+    params: {},
+    success: () => {},
+    fail: (e) => console.warn(e),
+}).exec();
+```
+
+## Props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `src` | `string` | URL to load. Mutually exclusive with `html`. |
+| `html` | `string` | Inline HTML, no network. Base URL is `null` — relative URLs won't resolve. |
+| `userAgent` | `string` | Override the WebView's User-Agent. |
+| `debug` | `boolean` | iOS 16.4+: Safari Web Inspector via `WKWebView.isInspectable`. Android: `WebView.setWebContentsDebuggingEnabled(true)` — note this is **process-wide** on Android, not per-instance. |
+| `class` / `style` | string / object | Standard Lynx layout. |
+| `onLoad` | `(e) => void` | Main-frame navigation finished. `e.detail.url`. |
+| `onError` | `(e) => void` | Main-frame load failed. `e.detail.{url, message}`. Subresource errors (favicon, image) are suppressed. |
+| `onMessage` | `(e) => void` | Page called `window.sigx.postMessage(payload)`. `e.detail.data` is a string. |
+| `mtRef` | `MainThreadRef<MainThread.Element \| null>` | Captures the underlying native element so you can drive the v2 imperative methods. |
+
+## Gotchas
+
+- **`src` is restricted to `http(s):` and `about:blank`**. `javascript:` URLs are refused (logged + ignored) — they're the headline XSS vector for embedded WebViews. `file:` is refused too; Android also disables `allowFileAccess`/`allowContentAccess` + the legacy file-URL universal-access flags by default. Apps that need richer content should use the `html` prop (rendered with a null base URL → fully sandboxed).
+- **iOS App Transport Security**: HTTPS-only by default in release builds. To load HTTP URLs you'd need to relax ATS in `Info.plist` (and accept the App Store review risk). Dev builds already allow LAN HTTP via the existing `NSAllowsLocalNetworking` flag.
+- **Android `mixed-content`**: defaults block HTTP subresources on HTTPS pages. If you load a mixed-content page, set `webView.settings.mixedContentMode` manually — not currently exposed as a prop.
+- **Cookies**: the WebView uses its own `WKWebsiteDataStore` (iOS) / `CookieManager` (Android). Cookies are **not** shared with the system Safari / Chrome.
+- **No file uploads / downloads in v1**: file `<input type="file">` and `Content-Disposition: attachment` aren't wired through.
+- **`debug` on Android is process-wide**: enabling it on any `<WebView>` instance also flips the flag for every other WebView in the app. Toggling off after enable doesn't detach already-attached `chrome://inspect` sessions.
+
+## Reference app
+
+`examples/showcase/src/screens/TripGuide.tsx` is a real-app integration: each trip's destination ("Lisbon, May 2026" → `Lisbon`) drives a Wikivoyage URL loaded in a WebView, with an `onLoad` loading overlay, an `onError` retry surface, and a bottom toolbar wiring Back / Forward / Reload via `WebViewMethods` so the user can navigate Wikivoyage internal links without leaving the screen. Reachable from `TripDetail` via the `Guide` header button.

package/android/com/sigx/webview/SigxWebViewBehavior.kt

@@ -0,0 +1,19 @@
+package com.sigx.webview
+
+import com.lynx.tasm.behavior.Behavior
+import com.lynx.tasm.behavior.LynxContext
+import com.lynx.tasm.behavior.ui.LynxUI
+
+/**
+ * Registers the `<sigx-webview>` JSX tag with Lynx's UI registry.
+ *
+ * Discovered by the autolinker via `signalx-module.json`'s `android.behaviors`
+ * field; the generated `GeneratedBehaviors.attachAll(builder)` calls
+ * `builder.addBehavior(SigxWebViewBehavior())` for every `LynxViewBuilder`
+ * in the app (production + dev-client path).
+ */
+class SigxWebViewBehavior : Behavior("sigx-webview") {
+    override fun createUI(context: LynxContext): LynxUI<*> {
+        return SigxWebViewUI(context)
+    }
+}

package/android/com/sigx/webview/SigxWebViewJavascriptInterface.kt

@@ -0,0 +1,24 @@
+package com.sigx.webview
+
+import android.os.Handler
+import android.os.Looper
+import android.webkit.JavascriptInterface
+
+/**
+ * JS bridge exposed to the embedded page as `window.sigxBridge`. Calls into
+ * [postMessage] arrive on the WebView's background JS thread; we hop to the
+ * main thread before firing the `bindmessage` event so [SigxWebViewUI.fireEvent]
+ * runs on the same thread Lynx expects.
+ */
+class SigxWebViewJavascriptInterface(private val owner: SigxWebViewUI) {
+
+    private val mainHandler = Handler(Looper.getMainLooper())
+
+    @JavascriptInterface
+    fun postMessage(payload: String?) {
+        val data = payload ?: ""
+        mainHandler.post {
+            owner.fireEvent("message", mapOf("data" to data))
+        }
+    }
+}

package/android/com/sigx/webview/SigxWebViewUI.kt

@@ -0,0 +1,326 @@
+package com.sigx.webview
+
+import android.annotation.SuppressLint
+import android.content.Context
+import android.graphics.Bitmap
+import android.os.Handler
+import android.os.Looper
+import android.webkit.WebResourceError
+import android.webkit.WebResourceRequest
+import android.webkit.WebView
+import android.webkit.WebViewClient
+import com.lynx.react.bridge.Callback
+import com.lynx.react.bridge.JavaOnlyMap
+import com.lynx.react.bridge.ReadableMap
+import com.lynx.tasm.behavior.LynxContext
+import com.lynx.tasm.behavior.LynxProp
+import com.lynx.tasm.behavior.LynxUIMethod
+import com.lynx.tasm.behavior.LynxUIMethodConstants
+import com.lynx.tasm.behavior.ui.LynxUI
+import com.lynx.tasm.event.LynxDetailEvent
+import org.json.JSONArray
+
+/**
+ * Native UI for the `<sigx-webview>` JSX element on Android.
+ *
+ * Prop / event surface (v1):
+ *   - `src`           → load a URL
+ *   - `html`          → load inline HTML
+ *   - `user-agent`    → custom UA string
+ *   - `enable-debug`  → `WebView.setWebContentsDebuggingEnabled` (process-wide)
+ *   - `bindload`      → page finished loading
+ *   - `binderror`     → load failed
+ *   - `bindmessage`   → page called `window.sigx.postMessage(payload)`
+ *
+ * Imperative methods (goBack / reload / postMessage from JS / injectJavaScript)
+ * are tracked as a v2 follow-up.
+ */
+class SigxWebViewUI(context: LynxContext) : LynxUI<WebView>(context) {
+
+    companion object {
+        /** JS-side bridge name exposed to the page. Kept in sync with [bridgeUserScript]. */
+        private const val BRIDGE_NAME = "sigxBridge"
+
+        /**
+         * Injected at `WebViewClient.onPageStarted` so it survives navigations.
+         * Aliases `window.sigx.postMessage` to the `addJavascriptInterface`
+         * bridge so authors get the same `window.sigx.postMessage('hi')` shape
+         * as iOS. Also exposes `window.sigxBridge.dispatchMessage` — the host
+         * calls this from `evaluateJavascript` to deliver host → page
+         * messages, which forwards to whatever the page registered as
+         * `window.sigx.onmessage`.
+         */
+        private val bridgeUserScript = """
+            (function() {
+                var bridge = window.${BRIDGE_NAME};
+                if (!bridge) return;
+                window.sigx = window.sigx || {};
+                if (!window.sigx.postMessage) {
+                    window.sigx.postMessage = function(payload) {
+                        try { bridge.postMessage(typeof payload === 'string' ? payload : JSON.stringify(payload)); }
+                        catch (e) { /* swallowed */ }
+                    };
+                }
+                // Host → page delivery slot. No-op until the page subscribes
+                // by setting window.sigx.onmessage; handler exceptions are
+                // swallowed so a bad page can't break the bridge.
+                bridge.dispatchMessage = function(payload) {
+                    try {
+                        var fn = window.sigx && window.sigx.onmessage;
+                        if (typeof fn === 'function') fn(payload);
+                    } catch (e) { /* swallowed */ }
+                };
+            })();
+        """.trimIndent()
+    }
+
+    @SuppressLint("SetJavaScriptEnabled", "AddJavascriptInterface")
+    override fun createView(context: Context): WebView {
+        val webView = WebView(context)
+        webView.settings.apply {
+            javaScriptEnabled = true
+            domStorageEnabled = true
+            // Hardened defaults — the platform's pre-API-30 defaults for the
+            // four flags below were `true`, which lets a malicious page loaded
+            // via `file://` read arbitrary files and cross-origin URLs. Apps
+            // that genuinely need local-file content can override these on a
+            // forked component; we deliberately don't expose them as v1 props.
+            allowFileAccess = false
+            allowContentAccess = false
+            @Suppress("DEPRECATION")
+            allowFileAccessFromFileURLs = false
+            @Suppress("DEPRECATION")
+            allowUniversalAccessFromFileURLs = false
+        }
+        webView.webViewClient = object : WebViewClient() {
+            override fun onPageStarted(view: WebView?, url: String?, favicon: Bitmap?) {
+                super.onPageStarted(view, url, favicon)
+                // Inject the alias at start so the page can call
+                // window.sigx.postMessage from inline / early scripts. The
+                // underlying addJavascriptInterface bridge is always present.
+                view?.evaluateJavascript(bridgeUserScript, null)
+            }
+
+            override fun onPageFinished(view: WebView?, url: String?) {
+                super.onPageFinished(view, url)
+                fireEvent("load", mapOf("url" to (url ?: "")))
+            }
+
+            override fun onReceivedError(
+                view: WebView?,
+                request: WebResourceRequest?,
+                error: WebResourceError?,
+            ) {
+                super.onReceivedError(view, request, error)
+                // Only surface main-frame failures to JS — subresource errors
+                // (a missing favicon, a CDN image 404) shouldn't fire as a
+                // top-level binderror.
+                if (request?.isForMainFrame != true) return
+                fireEvent(
+                    "error",
+                    mapOf(
+                        "url" to (request.url?.toString() ?: ""),
+                        "message" to (error?.description?.toString() ?: "unknown error"),
+                    ),
+                )
+            }
+        }
+        webView.addJavascriptInterface(SigxWebViewJavascriptInterface(this), BRIDGE_NAME)
+        return webView
+    }
+
+    // ── Prop setters ─────────────────────────────────────────────────────
+
+    @LynxProp(name = "src")
+    fun setSrc(value: String?) {
+        if (value.isNullOrEmpty()) return
+        if (!isSchemeAllowed(value)) {
+            android.util.Log.w(
+                "SigxWebView",
+                "Rejected src with unsupported scheme: ${value.take(32)}…",
+            )
+            return
+        }
+        mView.loadUrl(value)
+    }
+
+    @LynxProp(name = "html")
+    fun setHtml(value: String?) {
+        if (value == null) return
+        // baseURL=null intentionally — pages loaded via loadDataWithBaseURL
+        // with a `file://` base could read local files in older Android
+        // versions; a null base keeps the content fully sandboxed.
+        mView.loadDataWithBaseURL(null, value, "text/html", "UTF-8", null)
+    }
+
+    @LynxProp(name = "user-agent")
+    fun setUserAgent(value: String?) {
+        // WebSettings.setUserAgentString(null) restores the platform default
+        // — that's fine when the prop is reset, but we still null-guard for
+        // clarity and to dodge the (rare) NPE Copilot flagged on older
+        // WebView implementations.
+        val ua = value ?: return
+        mView.settings.userAgentString = ua
+    }
+
+    @LynxProp(name = "enable-debug")
+    fun setEnableDebug(value: Boolean) {
+        // Note: setWebContentsDebuggingEnabled is process-wide on Android, not
+        // per-instance. Once enabled by any WebView, chrome://inspect picks it
+        // up. Disabling is a no-op for already-attached debuggers.
+        WebView.setWebContentsDebuggingEnabled(value)
+    }
+
+    // ── Imperative methods ───────────────────────────────────────────────
+    //
+    // Each `@LynxUIMethod` block is discovered by Lynx's annotation processor
+    // (`com.lynx.tasm.behavior.LynxUIMethodsProcessor`) and routed via
+    // `__InvokeUIMethod`. Status codes come from `LynxUIMethodConstants`:
+    // `SUCCESS = 0`, `UNKNOWN = 1`. WebView methods MUST run on the UI
+    // thread — Lynx's invoke dispatch is already main-thread on Android but
+    // we hop explicitly to keep this readable.
+
+    private val mainHandler = Handler(Looper.getMainLooper())
+
+    @LynxUIMethod
+    fun goBack(params: ReadableMap?, callback: Callback?) {
+        mainHandler.post {
+            if (mView.canGoBack()) mView.goBack()
+            callback?.invoke(LynxUIMethodConstants.SUCCESS)
+        }
+    }
+
+    @LynxUIMethod
+    fun goForward(params: ReadableMap?, callback: Callback?) {
+        mainHandler.post {
+            if (mView.canGoForward()) mView.goForward()
+            callback?.invoke(LynxUIMethodConstants.SUCCESS)
+        }
+    }
+
+    @LynxUIMethod
+    fun reload(params: ReadableMap?, callback: Callback?) {
+        mainHandler.post {
+            mView.reload()
+            callback?.invoke(LynxUIMethodConstants.SUCCESS)
+        }
+    }
+
+    @LynxUIMethod
+    fun stopLoading(params: ReadableMap?, callback: Callback?) {
+        mainHandler.post {
+            mView.stopLoading()
+            callback?.invoke(LynxUIMethodConstants.SUCCESS)
+        }
+    }
+
+    @LynxUIMethod
+    fun canGoBack(params: ReadableMap?, callback: Callback?) {
+        mainHandler.post {
+            val result = JavaOnlyMap().apply { putBoolean("value", mView.canGoBack()) }
+            callback?.invoke(LynxUIMethodConstants.SUCCESS, result)
+        }
+    }
+
+    @LynxUIMethod
+    fun canGoForward(params: ReadableMap?, callback: Callback?) {
+        mainHandler.post {
+            val result = JavaOnlyMap().apply { putBoolean("value", mView.canGoForward()) }
+            callback?.invoke(LynxUIMethodConstants.SUCCESS, result)
+        }
+    }
+
+    /**
+     * Evaluate JS in the page; return the last-expression value, stringified.
+     * Non-string results (numbers, dicts, undefined) land as their
+     * `toString()` so the wire shape matches iOS exactly.
+     */
+    @LynxUIMethod
+    fun injectJavaScript(params: ReadableMap?, callback: Callback?) {
+        val code = params?.getString("code").orEmpty()
+        if (code.isEmpty()) {
+            callback?.invoke(LynxUIMethodConstants.UNKNOWN, "injectJavaScript: missing `code` param")
+            return
+        }
+        mainHandler.post {
+            mView.evaluateJavascript(code) { result ->
+                // Android wraps results in JSON-encoded quotes for strings;
+                // strip them for parity with iOS's plain string form.
+                val str = result?.let { stripJsonQuotes(it) } ?: ""
+                val payload = JavaOnlyMap().apply { putString("result", str) }
+                callback?.invoke(LynxUIMethodConstants.SUCCESS, payload)
+            }
+        }
+    }
+
+    /**
+     * Host → page message. The bridge user-script's `dispatchMessage` helper
+     * forwards to whatever handler the page registered as
+     * `window.sigx.onmessage`. JSON-encoding via `JSONArray` puts the
+     * payload through the same escape rules the engine uses, so embedded
+     * quotes / newlines round-trip cleanly into the JS source.
+     */
+    @LynxUIMethod
+    fun postMessage(params: ReadableMap?, callback: Callback?) {
+        val data = params?.getString("data").orEmpty()
+        val arrayLiteral = JSONArray().put(data).toString() // e.g. `["hi"]`
+        val jsLiteral = arrayLiteral.substring(1, arrayLiteral.length - 1)
+        val js = "window.sigxBridge && window.sigxBridge.dispatchMessage && window.sigxBridge.dispatchMessage($jsLiteral);"
+        mainHandler.post {
+            mView.evaluateJavascript(js) { _ ->
+                callback?.invoke(LynxUIMethodConstants.SUCCESS)
+            }
+        }
+    }
+
+    private fun stripJsonQuotes(raw: String): String {
+        // Normalise JS `null` / `undefined` → empty string for parity with
+        // the documented contract + the iOS implementation. Android's
+        // `evaluateJavascript` returns:
+        //   - "null"      for JS `null` AND JS `undefined`
+        //   - the JSON-encoded value otherwise
+        //     (a JS string `"hello"` arrives as the 6-char string `"hello"`).
+        // We strip the JSON quotes for the string case and treat nullish
+        // literals as empty strings — same wire shape as iOS.
+        if (raw == "null" || raw == "undefined" || raw.isEmpty()) return ""
+        if (raw.length >= 2 && raw.startsWith("\"") && raw.endsWith("\"")) {
+            // The simplest safe path — parse as a 1-element JSON array so
+            // escape sequences (`\\n`, `\\u00ff`, etc.) decode properly
+            // instead of leaking into the wire.
+            return try {
+                JSONArray("[$raw]").getString(0)
+            } catch (_: Throwable) {
+                raw.substring(1, raw.length - 1)
+            }
+        }
+        return raw
+    }
+
+    // ── Event firing ─────────────────────────────────────────────────────
+
+    internal fun fireEvent(name: String, params: Map<String, Any?>) {
+        val event = LynxDetailEvent(sign, name)
+        for ((k, v) in params) {
+            event.addDetail(k, v)
+        }
+        lynxContext.eventEmitter.sendCustomEvent(event)
+    }
+
+    /**
+     * Allow only `http(s)` and `about:` for the `src` prop. `javascript:` is
+     * the headline XSS vector — a malicious server could redirect to it and
+     * execute arbitrary JS in the WebView's renderer. `file:` is rejected
+     * because we've disabled file access on the settings anyway, but the
+     * scheme check is defense-in-depth in case a future maintainer flips
+     * one back. Apps that genuinely need other schemes can use the `html`
+     * prop (which is fully sandboxed) instead.
+     */
+    private fun isSchemeAllowed(url: String): Boolean {
+        val trimmed = url.trim()
+        if (trimmed.equals("about:blank", ignoreCase = true)) return true
+        val colon = trimmed.indexOf(':')
+        if (colon <= 0) return false
+        val scheme = trimmed.substring(0, colon).lowercase()
+        return scheme == "http" || scheme == "https"
+    }
+}

package/dist/WebView.d.ts

@@ -0,0 +1,45 @@
+import { type Define, type MainThread, type MainThreadRef } from '@sigx/lynx';
+import './jsx-augment.js';
+import type { WebViewErrorEvent, WebViewLoadEvent, WebViewMessageEvent } from './jsx-augment.js';
+/**
+ * Ref shape consumers pass via `mtRef` to capture the underlying native
+ * element. The current element handle is `ref.current` inside main-thread
+ * event handlers — pass it through `WebViewMethods.*` for typed access to
+ * `goBack`, `reload`, `injectJavaScript`, etc.
+ */
+export type WebViewRef = MainThreadRef<MainThread.Element | null>;
+export type WebViewProps = Define.Prop<'src', string, false> & Define.Prop<'html', string, false> & Define.Prop<'userAgent', string, false> & Define.Prop<'debug', boolean, false> & Define.Prop<'class', string, false> & Define.Prop<'style', string | Record<string, string | number>, false> & Define.Prop<'mtRef', WebViewRef, false> & Define.Prop<'onLoad', (e: WebViewLoadEvent) => void, false> & Define.Prop<'onError', (e: WebViewErrorEvent) => void, false> & Define.Prop<'onMessage', (e: WebViewMessageEvent) => void, false>;
+/**
+ * Native WebView component.
+ *
+ * On iOS this wraps a `WKWebView`; on Android, `android.webkit.WebView`.
+ *
+ * - Page → host: `window.sigx.postMessage(payload)` inside the page surfaces
+ *   on `onMessage` as `event.detail.data` (always a string).
+ * - Host → page: pass `mtRef` and call `WebViewMethods.postMessage(ref.current, data)`
+ *   from a main-thread event handler. The page subscribes by setting
+ *   `window.sigx.onmessage = (data) => { … }`.
+ *
+ * @example
+ * ```tsx
+ * import { useMainThreadRef, type MainThread } from '@sigx/lynx';
+ * import { WebView, WebViewMethods } from '@sigx/lynx-webview';
+ *
+ * const ref = useMainThreadRef<MainThread.Element | null>(null);
+ * const onBack = () => { 'main thread'; WebViewMethods.goBack(ref.current); };
+ *
+ * <WebView mtRef={ref} src="https://example.com" />
+ * <Button onPress={onBack}>Back</Button>
+ * ```
+ */
+export declare const WebView: import("@sigx/runtime-core").ComponentFactory<WebViewProps, void, {}>;
+export declare const WebViewMethods: {
+    readonly goBack: (el: MainThread.Element | null) => void;
+    readonly goForward: (el: MainThread.Element | null) => void;
+    readonly reload: (el: MainThread.Element | null) => void;
+    readonly stopLoading: (el: MainThread.Element | null) => void;
+    readonly canGoBack: (el: MainThread.Element | null) => Promise<boolean>;
+    readonly canGoForward: (el: MainThread.Element | null) => Promise<boolean>;
+    readonly injectJavaScript: (el: MainThread.Element | null, code: string) => Promise<string>;
+    readonly postMessage: (el: MainThread.Element | null, data: string) => void;
+};

package/dist/WebView.js

@@ -0,0 +1,109 @@
+import { jsx as _jsx } from "@sigx/lynx/jsx-runtime";
+import { component } from '@sigx/lynx';
+import './jsx-augment.js';
+/**
+ * Native WebView component.
+ *
+ * On iOS this wraps a `WKWebView`; on Android, `android.webkit.WebView`.
+ *
+ * - Page → host: `window.sigx.postMessage(payload)` inside the page surfaces
+ *   on `onMessage` as `event.detail.data` (always a string).
+ * - Host → page: pass `mtRef` and call `WebViewMethods.postMessage(ref.current, data)`
+ *   from a main-thread event handler. The page subscribes by setting
+ *   `window.sigx.onmessage = (data) => { … }`.
+ *
+ * @example
+ * ```tsx
+ * import { useMainThreadRef, type MainThread } from '@sigx/lynx';
+ * import { WebView, WebViewMethods } from '@sigx/lynx-webview';
+ *
+ * const ref = useMainThreadRef<MainThread.Element | null>(null);
+ * const onBack = () => { 'main thread'; WebViewMethods.goBack(ref.current); };
+ *
+ * <WebView mtRef={ref} src="https://example.com" />
+ * <Button onPress={onBack}>Back</Button>
+ * ```
+ */
+export const WebView = component(({ props }) => {
+    return () => (_jsx("sigx-webview", { src: props.src, html: props.html, "user-agent": props.userAgent, "enable-debug": props.debug, class: props.class, style: props.style, "main-thread:ref": props.mtRef, bindload: props.onLoad, binderror: props.onError, bindmessage: props.onMessage }));
+});
+/**
+ * Typed wrappers around `MainThread.Element.invoke(method, params)` for each
+ * v2 imperative method. Lives outside the component so it's directly callable
+ * from any main-thread handler without dragging the component closure in.
+ *
+ * All methods accept `el | null` so call sites can pass `ref.current` directly
+ * without nesting an `if`. When `el` is null the call is a no-op (returns
+ * `void` synchronously or `Promise<void>`/default value asynchronously).
+ *
+ * Method semantics mirror the iOS / Android native implementations:
+ *
+ *   - `goBack` / `goForward` are no-ops when there's no history.
+ *   - `reload` always succeeds even on the current document.
+ *   - `canGoBack` / `canGoForward` resolve with `false` if the element is
+ *     gone.
+ *   - `injectJavaScript` returns the last-expression value stringified.
+ *     `null` / `undefined` results land as `""`.
+ *   - `postMessage` delivers to `window.sigx.onmessage(data)` inside the
+ *     page; pages that haven't subscribed get a silent no-op.
+ */
+// `invoke()` returns a Promise that can reject when the underlying UI method
+// rejects (native error, method missing on a stale element, …). For the
+// fire-and-forget wrappers below, swallow the rejection so callers don't
+// have to wrap every tap handler in try/catch and don't accumulate unhandled
+// rejection warnings. For the async getters, catch + fall back to the
+// documented default value (`false` / `""`) so the failure mode matches
+// the el-is-null mode — callers only have to handle one shape.
+function fireAndForget(p) {
+    p?.catch(() => { });
+}
+export const WebViewMethods = {
+    goBack(el) {
+        fireAndForget(el?.invoke('goBack', {}));
+    },
+    goForward(el) {
+        fireAndForget(el?.invoke('goForward', {}));
+    },
+    reload(el) {
+        fireAndForget(el?.invoke('reload', {}));
+    },
+    stopLoading(el) {
+        fireAndForget(el?.invoke('stopLoading', {}));
+    },
+    async canGoBack(el) {
+        if (!el)
+            return false;
+        try {
+            const r = await el.invoke('canGoBack', {});
+            return r?.value ?? false;
+        }
+        catch {
+            return false;
+        }
+    },
+    async canGoForward(el) {
+        if (!el)
+            return false;
+        try {
+            const r = await el.invoke('canGoForward', {});
+            return r?.value ?? false;
+        }
+        catch {
+            return false;
+        }
+    },
+    async injectJavaScript(el, code) {
+        if (!el)
+            return '';
+        try {
+            const r = await el.invoke('injectJavaScript', { code });
+            return r?.result ?? '';
+        }
+        catch {
+            return '';
+        }
+    },
+    postMessage(el, data) {
+        fireAndForget(el?.invoke('postMessage', { data }));
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import './jsx-augment.js';
+export { WebView, WebViewMethods } from './WebView.js';
+export type { WebViewProps, WebViewRef } from './WebView.js';
+export type { SigxWebViewAttributes, WebViewLoadEvent, WebViewLoadEventDetail, WebViewErrorEvent, WebViewErrorEventDetail, WebViewMessageEvent, WebViewMessageEventDetail, } from './jsx-augment.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+import './jsx-augment.js';
+export { WebView, WebViewMethods } from './WebView.js';

package/dist/jsx-augment.d.ts

@@ -0,0 +1,71 @@
+/**
+ * JSX intrinsic type augmentation for `<sigx-webview>`.
+ *
+ * Importing this module registers `'sigx-webview'` as a valid JSX intrinsic
+ * with the prop + event surface implemented by `SigxWebViewUI` (iOS) and
+ * `SigxWebViewUI.kt` (Android). Pulled in automatically by
+ * `@sigx/lynx-webview`'s entry point so consumers do not need to import it
+ * directly.
+ *
+ * Element availability requires `sigx prebuild` to have run after adding
+ * this package as a dependency — the autolinker emits the `LynxConfig`
+ * registration (iOS) and `Behavior` attachment (Android) that bind the tag
+ * to the native UI class.
+ */
+import type { LynxCommonAttributes, LynxEventHandler } from '@sigx/lynx-runtime';
+export interface WebViewLoadEventDetail {
+    url: string;
+    [k: string]: unknown;
+}
+export interface WebViewLoadEvent {
+    type: 'load';
+    detail: WebViewLoadEventDetail;
+}
+export interface WebViewErrorEventDetail {
+    url: string;
+    message: string;
+    [k: string]: unknown;
+}
+export interface WebViewErrorEvent {
+    type: 'error';
+    detail: WebViewErrorEventDetail;
+}
+export interface WebViewMessageEventDetail {
+    /**
+     * Payload the page sent via `window.sigx.postMessage(payload)`. Always a
+     * string on the wire — apps that send JSON should `JSON.parse` here.
+     */
+    data: string;
+    [k: string]: unknown;
+}
+export interface WebViewMessageEvent {
+    type: 'message';
+    detail: WebViewMessageEventDetail;
+}
+export interface SigxWebViewAttributes extends LynxCommonAttributes {
+    /** URL to load. Setting both `src` and `html` is undefined behavior — pick one. */
+    src?: string;
+    /** Inline HTML to render (no network fetch). */
+    html?: string;
+    /** Override the WebView's User-Agent string. */
+    'user-agent'?: string;
+    /**
+     * Enable platform debugging — Safari Web Inspector on iOS 16.4+,
+     * `chrome://inspect` on Android. Note: Android's flag is **process-wide**.
+     */
+    'enable-debug'?: boolean;
+    /** Fires once the main-frame navigation finishes. */
+    bindload?: LynxEventHandler<WebViewLoadEvent>;
+    /** Fires on main-frame load failure. */
+    binderror?: LynxEventHandler<WebViewErrorEvent>;
+    /** Fires when the page calls `window.sigx.postMessage(payload)`. */
+    bindmessage?: LynxEventHandler<WebViewMessageEvent>;
+}
+declare global {
+    namespace JSX {
+        interface IntrinsicElements {
+            'sigx-webview': SigxWebViewAttributes;
+        }
+    }
+}
+export {};

package/dist/jsx-augment.js

@@ -0,0 +1 @@
+export {};

package/ios/SigxWebViewUI.swift

@@ -0,0 +1,390 @@
+import Foundation
+import UIKit
+import WebKit
+import Lynx
+
+/// Native UI for the `<sigx-webview>` JSX element.
+///
+/// Registered via the autolinker — `signalx-module.json`'s `ios.uiComponents`
+/// produces a `config.registerUI(SigxWebViewUI.self, withName: "sigx-webview")`
+/// call in the generated `GeneratedComponentRegistry.swift`.
+///
+/// Prop / event surface (v1):
+///   - `src`           → load a URL
+///   - `html`          → load inline HTML
+///   - `user-agent`    → custom UA string
+///   - `enable-debug`  → Web Inspector (iOS 16.4+ also flips `isInspectable`)
+///   - `bindload`      → page finished loading
+///   - `binderror`     → load failed
+///   - `bindmessage`   → page called `window.sigx.postMessage(payload)`
+///
+/// Imperative methods (goBack / reload / postMessage from JS / injectJavaScript)
+/// are tracked as a v2 follow-up — they need the Lynx UIMethodInvoker surface.
+// Class is NOT marked `@objc` — Swift forbids that on generic subclasses
+// (`LynxUI<__covariant V>` is an ObjC lightweight generic, so this is one).
+// Member-level `@objc` / `@objc(name)` annotations still bridge because
+// `LynxUI` itself is `@objc`, so the inherited ObjC machinery picks up
+// `__lynx_prop_config__*` and `__lynx_ui_method_config__*` class methods
+// as expected by `LynxPropsProcessor` / `LynxUIMethodProcessor`.
+public class SigxWebViewUI: LynxUI<WKWebView> {
+
+    /// `WKUserContentController` handler name. On the page side this is
+    /// reached via `window.webkit.messageHandlers.sigxBridge.postMessage(...)`
+    /// (WKWebView's standard surface). The user script injected by this
+    /// component then aliases the friendlier `window.sigx.postMessage(...)`
+    /// on top of it so authors get the same API as on Android. Keep in
+    /// sync with `bridgeUserScript`.
+    private static let bridgeName = "sigxBridge"
+
+    private lazy var navigationDelegate = SigxWebViewNavigationDelegate(owner: self)
+    private lazy var scriptMessageHandler = SigxWebViewScriptMessageHandler(owner: self)
+
+    // MARK: - LynxUI overrides
+
+    public override func createView() -> WKWebView? {
+        let config = WKWebViewConfiguration()
+        let controller = WKUserContentController()
+        controller.add(scriptMessageHandler, name: SigxWebViewUI.bridgeName)
+        controller.addUserScript(WKUserScript(
+            source: SigxWebViewUI.bridgeUserScript,
+            injectionTime: .atDocumentStart,
+            forMainFrameOnly: false
+        ))
+        config.userContentController = controller
+
+        // Start with a non-zero placeholder frame so WKWebView's internal
+        // layout engine doesn't sit in a "no size, no render" steady state.
+        // Lynx's `updateFrame` overrides this immediately with the real
+        // layout dims; the placeholder is just to bootstrap WKWebView's
+        // initial render pipeline.
+        let webView = WKWebView(frame: CGRect(x: 0, y: 0, width: 1, height: 1), configuration: config)
+        webView.navigationDelegate = navigationDelegate
+        // Disable the autoresizing-mask translation so when Lynx sets a new
+        // frame, WKWebView re-lays its WKContentView at the new size.
+        // Without this, WKWebView sometimes pins its internal content view
+        // to the initial frame and ignores subsequent frame changes from
+        // outside the iOS auto-layout system.
+        webView.translatesAutoresizingMaskIntoConstraints = true
+        webView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        return webView
+    }
+
+    // Explicit prop-setter registration. The runtime prefers this path
+    // over the per-method `__lynx_prop_config__*` discovery — see
+    // `LynxPropsProcessor.mm:206-211`. Returning a single `NSArray` of
+    // `[propName, fullSelector]` pairs is more robust than relying on
+    // Swift `@objc(name)` class methods being enumerable by
+    // `class_copyMethodList(metaclass)` (which has subtle quirks for
+    // Swift-defined classes that don't carry a class-level `@objc`).
+    @objc public class func propSetterLookUp() -> NSArray {
+        return [
+            ["src", "setSrc:requestReset:"],
+            ["html", "setHtml:requestReset:"],
+            ["user-agent", "setUserAgent:requestReset:"],
+            ["enable-debug", "setEnableDebug:requestReset:"],
+        ] as NSArray
+    }
+
+    // MARK: - Prop setters
+    //
+    // Each `@objc(...)` selector matches the runtime's `__lynx_prop_config__*`
+    // discovery convention from `LynxPropsProcessor.h`. The corresponding
+    // setter follows the macro shape:
+    //     -(void)set<Name>:(type)value requestReset:(BOOL)requestReset
+    // which Swift emits naturally for `@objc func setX(_:requestReset:)`.
+
+    @objc public func setSrc(_ value: NSString?, requestReset: Bool) {
+        guard let raw = value as String?, !raw.isEmpty, let url = URL(string: raw) else { return }
+        guard SigxWebViewUI.isSchemeAllowed(url) else {
+            NSLog("[SigxWebView] Rejected src with unsupported scheme: \(raw.prefix(32))")
+            return
+        }
+        view().load(URLRequest(url: url))
+    }
+
+    @objc(__lynx_prop_config__src)
+    public class func __lynxPropConfigSrc() -> [String] {
+        return ["src", "setSrc", "NSString *"]
+    }
+
+    /// Allow only `http(s)` and `about:blank`. `javascript:` is the headline
+    /// XSS vector — a redirect from a remote page could execute arbitrary JS
+    /// in the WebView's context. `file:` is rejected so the embedded page
+    /// can't read app-bundle resources. Apps that need other schemes can
+    /// use the `html` prop (no base URL → no file access) instead.
+    static func isSchemeAllowed(_ url: URL) -> Bool {
+        if url.absoluteString.caseInsensitiveCompare("about:blank") == .orderedSame {
+            return true
+        }
+        guard let scheme = url.scheme?.lowercased() else { return false }
+        return scheme == "http" || scheme == "https"
+    }
+
+    @objc public func setHtml(_ value: NSString?, requestReset: Bool) {
+        guard let raw = value as String? else { return }
+        view().loadHTMLString(raw, baseURL: nil)
+    }
+
+    @objc(__lynx_prop_config__html)
+    public class func __lynxPropConfigHtml() -> [String] {
+        return ["html", "setHtml", "NSString *"]
+    }
+
+    @objc public func setUserAgent(_ value: NSString?, requestReset: Bool) {
+        // `view()` is lazily built — calling it from a prop setter is safe
+        // because LynxUI has already created the underlying view by the
+        // time the runtime hands us prop values. No "view not built yet"
+        // branch needed.
+        let ua = (value as String?) ?? ""
+        view().customUserAgent = ua.isEmpty ? nil : ua
+    }
+
+    @objc(__lynx_prop_config__user_agent)
+    public class func __lynxPropConfigUserAgent() -> [String] {
+        return ["user-agent", "setUserAgent", "NSString *"]
+    }
+
+    @objc public func setEnableDebug(_ value: Bool, requestReset: Bool) {
+        // iOS 16.4+ exposes `isInspectable` for the Safari Web Inspector. On
+        // older iOS, the WebKit-private `developerExtrasEnabled` preference is
+        // gated behind App-Store-reject risk; we only flip the public flag.
+        if #available(iOS 16.4, *) {
+            view().isInspectable = value
+        }
+    }
+
+    @objc(__lynx_prop_config__enable_debug)
+    public class func __lynxPropConfigEnableDebug() -> [String] {
+        return ["enable-debug", "setEnableDebug", "BOOL"]
+    }
+
+    // MARK: - Imperative methods
+    //
+    // Each method is declared the same way as v1's prop setters: a Swift
+    // instance method matching the macro-generated `<name>:withResult:`
+    // signature plus a `@objc(__lynx_ui_method_config__<name>)` class method
+    // returning the method name as an NSString. Lynx's
+    // `LynxUIMethodProcessor` introspects every class method whose selector
+    // begins with `__lynx_ui_method_config__` to build its dispatch table
+    // (see `Pods/Lynx/.../LynxUIMethodProcessor.h`).
+    //
+    // Status codes: `kUIMethodSuccess = 0`, `kUIMethodUnknown = 1`. Defined
+    // as raw Int32 here so we don't have to import the C enum — the values
+    // are stable across Lynx 3.x.
+
+    private static let kUIMethodSuccess: Int32 = 0
+    private static let kUIMethodUnknown: Int32 = 1
+
+    @objc public func goBack(_ params: NSDictionary?, withResult callback: @escaping LynxUIMethodCallbackBlock) {
+        DispatchQueue.main.async {
+            if self.view().canGoBack { self.view().goBack() }
+            callback(SigxWebViewUI.kUIMethodSuccess, nil)
+        }
+    }
+    @objc(__lynx_ui_method_config__goBack)
+    dynamic public class func __lynxUIMethodConfigGoBack() -> NSString { return "goBack" }
+
+    @objc public func goForward(_ params: NSDictionary?, withResult callback: @escaping LynxUIMethodCallbackBlock) {
+        DispatchQueue.main.async {
+            if self.view().canGoForward { self.view().goForward() }
+            callback(SigxWebViewUI.kUIMethodSuccess, nil)
+        }
+    }
+    @objc(__lynx_ui_method_config__goForward)
+    dynamic public class func __lynxUIMethodConfigGoForward() -> NSString { return "goForward" }
+
+    @objc public func reload(_ params: NSDictionary?, withResult callback: @escaping LynxUIMethodCallbackBlock) {
+        DispatchQueue.main.async {
+            self.view().reload()
+            callback(SigxWebViewUI.kUIMethodSuccess, nil)
+        }
+    }
+    @objc(__lynx_ui_method_config__reload)
+    dynamic public class func __lynxUIMethodConfigReload() -> NSString { return "reload" }
+
+    @objc public func stopLoading(_ params: NSDictionary?, withResult callback: @escaping LynxUIMethodCallbackBlock) {
+        DispatchQueue.main.async {
+            self.view().stopLoading()
+            callback(SigxWebViewUI.kUIMethodSuccess, nil)
+        }
+    }
+    @objc(__lynx_ui_method_config__stopLoading)
+    dynamic public class func __lynxUIMethodConfigStopLoading() -> NSString { return "stopLoading" }
+
+    @objc public func canGoBack(_ params: NSDictionary?, withResult callback: @escaping LynxUIMethodCallbackBlock) {
+        DispatchQueue.main.async {
+            callback(SigxWebViewUI.kUIMethodSuccess, ["value": self.view().canGoBack])
+        }
+    }
+    @objc(__lynx_ui_method_config__canGoBack)
+    dynamic public class func __lynxUIMethodConfigCanGoBack() -> NSString { return "canGoBack" }
+
+    @objc public func canGoForward(_ params: NSDictionary?, withResult callback: @escaping LynxUIMethodCallbackBlock) {
+        DispatchQueue.main.async {
+            callback(SigxWebViewUI.kUIMethodSuccess, ["value": self.view().canGoForward])
+        }
+    }
+    @objc(__lynx_ui_method_config__canGoForward)
+    dynamic public class func __lynxUIMethodConfigCanGoForward() -> NSString { return "canGoForward" }
+
+    /// Evaluate arbitrary JS in the page and return the last-expression
+    /// value. Results are stringified — JS code that returns a non-string
+    /// (number, dict, undefined) lands as its `String(describing:)` form so
+    /// the wire shape stays predictable.
+    @objc public func injectJavaScript(_ params: NSDictionary?, withResult callback: @escaping LynxUIMethodCallbackBlock) {
+        let code = (params?["code"] as? String) ?? ""
+        if code.isEmpty {
+            callback(SigxWebViewUI.kUIMethodUnknown, "injectJavaScript: missing `code` param")
+            return
+        }
+        DispatchQueue.main.async {
+            self.view().evaluateJavaScript(code) { result, error in
+                if let error = error {
+                    callback(SigxWebViewUI.kUIMethodUnknown, error.localizedDescription)
+                    return
+                }
+                // Normalise JS `null` / `undefined` → empty string for
+                // wire-shape parity with Android and the documented
+                // `null/undefined → ""` contract. WKWebView returns:
+                //   - `nil`     for `undefined`
+                //   - `NSNull`  for JS `null`
+                //   - the boxed value otherwise (NSString, NSNumber, …).
+                // The default `String(describing: NSNull())` of "<null>"
+                // would leak into JS otherwise.
+                let str: String
+                if result == nil || result is NSNull {
+                    str = ""
+                } else if let s = result as? String {
+                    str = s
+                } else {
+                    str = "\(result!)"
+                }
+                callback(SigxWebViewUI.kUIMethodSuccess, ["result": str])
+            }
+        }
+    }
+    @objc(__lynx_ui_method_config__injectJavaScript)
+    dynamic public class func __lynxUIMethodConfigInjectJavaScript() -> NSString { return "injectJavaScript" }
+
+    /// Host → page message. The user-script (`bridgeUserScript`) injects a
+    /// `window.sigxBridge.dispatchMessage(data)` helper that no-ops when the
+    /// page hasn't subscribed via `window.sigx.onmessage = …`. We pass the
+    /// payload through `JSON.stringify` on the host side so embedded quotes
+    /// don't break the eval'd JS literal.
+    @objc public func postMessage(_ params: NSDictionary?, withResult callback: @escaping LynxUIMethodCallbackBlock) {
+        let data = (params?["data"] as? String) ?? ""
+        // Encode as JSON string literal so any quotes / newlines in the
+        // payload survive the round-trip into the JS source.
+        guard let payloadData = try? JSONSerialization.data(withJSONObject: [data], options: []),
+              let arrayLiteral = String(data: payloadData, encoding: .utf8),
+              arrayLiteral.count >= 2 else {
+            callback(SigxWebViewUI.kUIMethodUnknown, "postMessage: failed to encode payload")
+            return
+        }
+        // Slice off the array brackets to extract just the quoted-string form.
+        let jsLiteral = String(arrayLiteral.dropFirst().dropLast())
+        let js = "window.sigxBridge && window.sigxBridge.dispatchMessage && window.sigxBridge.dispatchMessage(\(jsLiteral));"
+        DispatchQueue.main.async {
+            self.view().evaluateJavaScript(js) { _, error in
+                if let error = error {
+                    callback(SigxWebViewUI.kUIMethodUnknown, error.localizedDescription)
+                } else {
+                    callback(SigxWebViewUI.kUIMethodSuccess, nil)
+                }
+            }
+        }
+    }
+    @objc(__lynx_ui_method_config__postMessage)
+    dynamic public class func __lynxUIMethodConfigPostMessage() -> NSString { return "postMessage" }
+
+    // MARK: - Event firing
+
+    /// Dispatch a `bind<name>` custom event with the given detail. JS handlers
+    /// see `event.detail` carrying the params.
+    fileprivate func fireEvent(_ name: String, params: [String: Any]) {
+        let event = LynxCustomEvent(name: name, targetSign: sign, params: params)
+        // Swift renames the ObjC `sendCustomEvent:` selector to `send(_:)`
+        // when LynxCustomEvent is the parameter type — both ObjC and Swift
+        // call the same underlying method.
+        context?.eventEmitter?.send(event)
+    }
+
+    /// User-script injected at `documentStart` on every frame. Forwards
+    /// `window.sigx.postMessage(json)` calls to the native script-message
+    /// handler (page → host direction). Also exposes
+    /// `window.sigxBridge.dispatchMessage` — the host calls this via
+    /// `evaluateJavaScript` to deliver host → page messages, which forwards
+    /// to whatever handler the page registered as `window.sigx.onmessage`.
+    private static let bridgeUserScript: String = """
+    (function() {
+        var bridgeNs = window.sigxBridge = window.sigxBridge || {};
+        var raw = window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.sigxBridge;
+        var post = function(payload) {
+            if (!raw) return;
+            try { raw.postMessage(typeof payload === 'string' ? payload : JSON.stringify(payload)); }
+            catch (e) { /* raw.postMessage already serialised the error */ }
+        };
+        // Host → page delivery slot. No-op if the page hasn't subscribed,
+        // and any handler exception is swallowed so a bad page can't break
+        // the bridge.
+        bridgeNs.dispatchMessage = function(payload) {
+            try {
+                var fn = window.sigx && window.sigx.onmessage;
+                if (typeof fn === 'function') fn(payload);
+            } catch (e) { /* swallowed */ }
+        };
+        window.sigx = window.sigx || {};
+        if (!window.sigx.postMessage) window.sigx.postMessage = post;
+    })();
+    """
+}
+
+/// `WKNavigationDelegate` adapter that re-fires lifecycle events back to JS.
+final class SigxWebViewNavigationDelegate: NSObject, WKNavigationDelegate {
+    private weak var owner: SigxWebViewUI?
+
+    init(owner: SigxWebViewUI) { self.owner = owner }
+
+    func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
+        let url = webView.url?.absoluteString ?? ""
+        owner?.fireEvent("load", params: ["url": url])
+    }
+
+    func webView(_ webView: WKWebView, didFail navigation: WKNavigation!, withError error: Error) {
+        owner?.fireEvent("error", params: [
+            "url": webView.url?.absoluteString ?? "",
+            "message": error.localizedDescription,
+        ])
+    }
+
+    func webView(_ webView: WKWebView, didFailProvisionalNavigation navigation: WKNavigation!, withError error: Error) {
+        // Provisional failures (DNS, TLS, unreachable) never hit didFinish;
+        // surface the same shape so JS only has to wire one handler.
+        owner?.fireEvent("error", params: [
+            "url": webView.url?.absoluteString ?? "",
+            "message": error.localizedDescription,
+        ])
+    }
+}
+
+/// `WKScriptMessageHandler` for `window.sigxBridge.postMessage(string)`.
+/// Forwards the payload as the `data` field of a `bindmessage` event so JS
+/// sees `event.detail.data` matching the Android side.
+final class SigxWebViewScriptMessageHandler: NSObject, WKScriptMessageHandler {
+    private weak var owner: SigxWebViewUI?
+
+    init(owner: SigxWebViewUI) { self.owner = owner }
+
+    func userContentController(_ userContentController: WKUserContentController,
+                               didReceive message: WKScriptMessage) {
+        let data: String
+        if let s = message.body as? String {
+            data = s
+        } else {
+            // Non-string bodies (numbers, dicts) — best-effort stringify so
+            // the wire shape is consistent.
+            data = "\(message.body)"
+        }
+        owner?.fireEvent("message", params: ["data": data])
+    }
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@sigx/lynx-webview",
+  "version": "0.4.1",
+  "description": "Native WebView component for sigx-lynx (WKWebView on iOS, android.webkit.WebView on Android).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./signalx-module.json": "./signalx-module.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "ios",
+    "android",
+    "signalx-module.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@sigx/lynx": "^0.4.1"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260521.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7",
+    "@sigx/lynx": "^0.4.1"
+  },
+  "author": "Andreas Ekdahl",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/signalxjs/lynx.git",
+    "directory": "packages/lynx-webview"
+  },
+  "homepage": "https://github.com/signalxjs/lynx/tree/main/packages/lynx-webview",
+  "bugs": {
+    "url": "https://github.com/signalxjs/lynx/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "signalx",
+    "sigx",
+    "lynx",
+    "webview",
+    "wkwebview",
+    "ios",
+    "android"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/clean.mjs dist && tsgo",
+    "dev": "tsgo --watch",
+    "test": "vitest run",
+    "clean": "node ../../scripts/clean.mjs dist .turbo"
+  }
+}

package/signalx-module.json

@@ -0,0 +1,18 @@
+{
+    "name": "WebView",
+    "package": "@sigx/lynx-webview",
+    "description": "Native WebView component (WKWebView / android.webkit.WebView)",
+    "platforms": ["android", "ios"],
+    "ios": {
+        "sourceDir": "ios",
+        "uiComponents": [
+            { "name": "sigx-webview", "uiClass": "SigxWebViewUI" }
+        ]
+    },
+    "android": {
+        "sourceDir": "android",
+        "behaviors": [
+            { "name": "sigx-webview", "behaviorClass": "com.sigx.webview.SigxWebViewBehavior" }
+        ]
+    }
+}