@webview-native-ui/engine 0.0.0-stage → 0.0.1

package/docs/cordova.md

@@ -0,0 +1,125 @@
+# Cordova plugin integration
+
+The same npm package, Swift library and Android AAR support Capacitor and Cordova. Engine is a library used by plugin maintainers, not a separately registered Cordova plugin. A Cordova application does not need `@capacitor/core` or a Capacitor native SDK.
+
+The consuming plugin still owns its native view and the corresponding DOM, including placement, size and stacking order. Supply an existing selector such as `native-ad` or `#player`. The DOM may be added after initialization. Image preparation, scroll handling, overlays and restoration use the common Engine implementation.
+
+## iOS
+
+Use the same SwiftPM dependency described in the main README. In a Cordova SwiftPM plugin, declare both Cordova and Engine as dependencies of the plugin target; neither framework becomes a dependency of the Engine target.
+
+```swift
+import Cordova
+import WebKit
+import WebViewNativeUIEngine
+
+@objc(ExamplePlugin)
+class ExamplePlugin: CDVPlugin {
+    private var projection: NativeUIProjection?
+    private var nativeView: UIView?
+
+    override func pluginInitialize() {
+        do {
+            projection = try NativeUIProjection(
+                webView: webView as? WKWebView,
+                plugin: "ExamplePlugin",
+                projectionSelector: "#player",
+                receiveListeners: .init(
+                    update: ["contentChanged"],
+                    projection: .init(native: ["shown"], web: ["covered"], none: ["hidden"])
+                ),
+                runtime: .cordova,
+                view: { [weak self] in self?.nativeView }
+            )
+        } catch {
+            // Keep the existing Web fallback when registration is unavailable.
+            NSLog("Native UI projection unavailable: %@", String(describing: error))
+        }
+    }
+
+    override func dispose() {
+        projection?.destroy()
+        projection = nil
+        super.dispose()
+    }
+}
+```
+
+Forward the plugin's existing presentation/content notifications with `projection?.receive("shown")`, `receive("hidden")` or `receive("contentChanged")`. Put this alongside the existing callback/event delivery, or in the plugin's shared notification method. `receive` updates the Engine session only: it does not deliver a second application callback. A matching destination emitted before JS startup is retained for the initial connection.
+
+Cordova iOS's built-in `WkWebView.convertFilePath` serves the prepared PNGs. Engine resolves this internally. No file plugin, additional permission or author-provided URL converter is required. The default allowed origins include `app://localhost`; pass the actual trusted origin if the app changes its scheme or hostname.
+
+## Android
+
+Declare the Maven dependency in the existing Cordova plugin Gradle configuration. Also declare `implementation 'androidx.webkit:webkit:1.14.0'` when using the `CordovaPluginPathHandler` signature; Cordova's internal WebKit dependency is not exposed on the plugin compile classpath. The plugin's `plugin.xml` must initialize it before the first WebView navigation:
+
+```xml
+<feature name="ExamplePlugin">
+    <param name="android-package" value="com.example.ExamplePlugin" />
+    <param name="onload" value="true" />
+</feature>
+```
+
+```kotlin
+class ExamplePlugin : CordovaPlugin() {
+    private var projection: NativeUIProjection? = null
+    private var nativeView: View? = null
+
+    override fun pluginInitialize() {
+        val web = webView.view as WebView
+        projection = runCatching {
+            // One origin-restricted channel per WebView, shared with later registrations.
+            NativeUIProjection.install(web)
+            NativeUIProjection(
+                window = cordova.activity.window,
+                webView = web,
+                plugin = serviceName,
+                projectionSelector = "#player",
+                receiveListeners = NativeUIProjection.ReceiveListeners(
+                    update = listOf("contentChanged"),
+                    projection = NativeUIProjection.ReceiveListeners.Projection(
+                        native = listOf("shown"), web = listOf("covered"), none = listOf("hidden")
+                    )
+                ),
+                runtime = NativeUIProjection.Runtime.CORDOVA,
+                view = { nativeView }
+            )
+        }.onFailure {
+            android.util.Log.e(javaClass.simpleName, "Native UI projection unavailable", it)
+        }.getOrNull()
+    }
+
+    override fun getPathHandler() = CordovaPluginPathHandler { path ->
+        projection?.handleResource(path)
+    }
+
+    override fun onDestroy() {
+        projection?.close()
+        projection = null
+        super.onDestroy()
+    }
+}
+```
+
+Use `projection?.receive(eventName, data)` at the existing notification point, as on iOS. Native view creation and placement remain on the UI thread.
+
+The `PathHandler` delegates same-origin image requests to Engine. It serves only the registration's PNG files in app-private cache storage; unrelated paths return `null`. If the plugin already has a handler, combine them with `projection?.handleResource(path) ?: existingHandler.handle(path)`. For multiple registrations, delegate to the matching owner. Keep the handler installed for the WebView lifetime. No WebViewClient replacement or storage permission is needed.
+
+The defaults support Cordova's `https://localhost` and `http://localhost`. If the hostname changes, pass the same explicit origin set to `install` and each registration. Wildcard origins and `file://` app origins are not supported by this integration.
+
+## Lifetime and verification
+
+Keep the registration for the WebView lifetime. Engine reconnects after a document reload and clears the old document's image state. If the plugin destroys its native UI in `onReset`, update its view provider and emit the appropriate destination; do not leave a registration pointing at a destroyed view. Dispose registrations when the plugin/WebView is destroyed.
+
+Capacitor registrations retain their existing default. The Cordova integration requires the standard Cordova WebView resource handler. Running a Cordova plugin inside a Capacitor app is not covered by this integration; the host must use the Capacitor integration instead. Ionic overlay observation remains optional and shared through `enableSupportIonicOverlays`; plain Cordova apps need not enable it.
+
+The integration fixture uses Cordova CLI 13, cordova-ios 8.1.1 and cordova-android 15.1.0 with their standard WebViews. It checks actual PNG handoff, native restoration and hidden-state retention across document reload, not merely JS bridge mocks. Older Cordova releases and custom WebView engines require separate verification.
+
+Run the real consumer checks with an already booted simulator/emulator:
+
+```sh
+npm run test:cordova -- ios SIMULATOR_UDID
+npm run test:cordova -- android emulator-5554
+```
+
+The script creates a disposable app, uses local SwiftPM/Maven Engine artifacts, and records the application result in the printed temporary directory. It never publishes to npm or Maven. Android requires JDK 21+, SDK 36 and `ANDROID_HOME`; iOS requires Xcode.

package/ios/Sources/WebViewNativeUIEngine/ClippedView.swift

@@ -0,0 +1,16 @@
+import UIKit
+/// Keeps native content at full size while clipping hit testing and visible pixels.
+public final class NativeUIClippedView: UIView {
+ public let content: UIView
+ public init(content: UIView) { self.content = content; super.init(frame: .zero); addSubview(content) }
+ @available(*, unavailable) required init?(coder: NSCoder) { fatalError() }
+ public func place(_ frame: CGRect, clip: CGRect? = nil) {
+  clipsToBounds = clip != nil
+  let visible = clip.map { frame.intersection($0) } ?? frame
+  isHidden = visible.isNull || visible.isEmpty
+  guard !isHidden else { return }
+  if self.frame != visible { self.frame = visible }
+  let local = CGRect(x: frame.minX - visible.minX, y: frame.minY - visible.minY, width: frame.width, height: frame.height)
+  if content.frame != local { content.frame = local }
+ }
+}

package/ios/Sources/WebViewNativeUIEngine/CoveredSnapshots.swift

@@ -0,0 +1,256 @@
+import UIKit
+
+/// Immutable, locally served images of controls that will be covered by a Web overlay.
+/// Native interaction invalidates in-flight captures before Web receives the activation.
+public final class NativeUICoveredSnapshots {
+    private struct Part {
+        let ids: [String]
+        let frame: CGRect
+        let image: UIImage
+        let file: URL
+    }
+    private struct Capture {
+        let size: CGSize
+        let webFrame: CGRect
+        let parts: [Part]
+    }
+    private let snapshotView: (UIWindow) -> UIView
+    public convenience init() {
+        self.init(snapshotView: { $0.screen.snapshotView(afterScreenUpdates: false) })
+    }
+    init(snapshotView: @escaping (UIWindow) -> UIView) {
+        self.snapshotView = snapshotView
+    }
+    private var captures: [String: Capture] = [:]
+    private var restoration: (token: String, views: [UIImageView], entry: Bool)?
+    private var hiddenControls: (token: String, restore: [() -> Void])?
+    private var generation = 0
+    private var touching = false
+    private weak var window: UIWindow?
+    private var observer: SnapshotTouchObserver?
+    private let directory = FileManager.default.temporaryDirectory.appendingPathComponent("native-ui-snapshots-\(UUID().uuidString)")
+    public private(set) var coveringToken: String?
+    public var covering: Bool { coveringToken != nil }
+
+    public func observe(_ window: UIWindow, changed: @escaping (Bool) -> Void) {
+        guard self.window !== window else { return }
+        if let observer { self.window?.removeGestureRecognizer(observer) }
+        self.window = window
+        let observer = SnapshotTouchObserver { [weak self] active in
+            guard let self else { return }
+            self.touching = active
+            if active { self.generation += 1 }
+            changed(active)
+        }
+        window.addGestureRecognizer(observer)
+        self.observer = observer
+    }
+
+    // Gesture release can keep changing SwiftUI button bounds after touchesEnded.
+    // Wait off the presentation path for unchanged rendered geometry, not a guessed delay.
+    public func prepare(frames: @escaping () -> [String: CGRect], in webView: UIView, viewportWidth: CGFloat,
+                 complete: @escaping ([String: Any]) -> Void) {
+        let stamp = generation
+        let start = CACurrentMediaTime()
+        func sample(_ previous: [String: CGRect], _ stable: Int) {
+            guard generation == stamp, !touching, CACurrentMediaTime() - start < 1 else { complete([:]); return }
+            let current = frames()
+            let count = !current.isEmpty && current == previous ? stable + 1 : 0
+            if count >= 3 {
+                capture(frames: current, in: webView, viewportWidth: viewportWidth, complete: complete)
+            } else {
+                DispatchQueue.main.asyncAfter(deadline: .now() + 1.0 / 60.0) { sample(current, count) }
+            }
+        }
+        sample([:], 0)
+    }
+
+    private func capture(frames: [String: CGRect], in webView: UIView, viewportWidth: CGFloat,
+                 complete: @escaping ([String: Any]) -> Void) {
+        guard !touching, let window = webView.window, !frames.isEmpty,
+              viewportWidth > 0, webView.bounds.width > 0 else { complete([:]); return }
+        let stamp = generation
+        let scale = window.screen.scale
+        let ratio = viewportWidth / webView.bounds.width
+        let size = window.bounds.size
+        let webFrame = webView.convert(webView.bounds, to: window)
+        // Each crop belongs to one source component. Overlapping crops share
+        // the same captured pixels and never combine unrelated components.
+        var regions: [(ids: [String], rect: CGRect)] = []
+        for (id, frame) in frames.sorted(by: { $0.key < $1.key }) {
+            var rect = webView.convert(frame, to: window).insetBy(dx: -12, dy: -12).intersection(window.bounds)
+            guard !rect.isNull, rect.width > 0, rect.height > 0 else { complete([:]); return }
+            rect = CGRect(x: floor(rect.minX * scale) / scale, y: floor(rect.minY * scale) / scale,
+                          width: (ceil(rect.maxX * scale) - floor(rect.minX * scale)) / scale,
+                          height: (ceil(rect.maxY * scale) - floor(rect.minY * scale)) / scale)
+            regions.append(([id], rect))
+        }
+        let bounds = regions.reduce(CGRect.null) { $0.union($1.rect) }
+        let format = UIGraphicsImageRendererFormat()
+        format.scale = scale
+        format.opaque = true
+        // Render the compositor's frozen screen, not UIKit's reconstruction of
+        // the hierarchy: the latter loses Liquid Glass background refraction.
+        // The replica remains detached and never changes visible UI or input.
+        let replica = snapshotView(window)
+        let screenBounds = window.convert(bounds, to: window.screen.coordinateSpace)
+        var drawn = false
+        let image = UIGraphicsImageRenderer(size: bounds.size, format: format).image { context in
+            context.cgContext.translateBy(x: -screenBounds.minX, y: -screenBounds.minY)
+            drawn = replica.drawHierarchy(in: window.screen.bounds, afterScreenUpdates: true)
+        }
+        guard drawn, let pixels = image.cgImage else { complete([:]); return }
+        let token = UUID().uuidString
+        let directory = self.directory
+        let crops = regions.compactMap { region -> (ids: [String], frame: CGRect, image: UIImage)? in
+            let crop = CGRect(x: (region.rect.minX - bounds.minX) * scale, y: (region.rect.minY - bounds.minY) * scale,
+                              width: region.rect.width * scale, height: region.rect.height * scale)
+            guard let part = pixels.cropping(to: crop) else { return nil }
+            return (region.ids, window.convert(region.rect, to: webView), UIImage(cgImage: part, scale: scale, orientation: .up))
+        }
+        guard crops.count == regions.count else { complete([:]); return }
+        DispatchQueue.global(qos: .userInitiated).async { [weak self] in
+            var parts: [Part] = []
+            do {
+                try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+                for (index, crop) in crops.enumerated() {
+                    guard let png = crop.image.pngData() else { throw CocoaError(.fileWriteUnknown) }
+                    let file = directory.appendingPathComponent("\(token)-\(index).png")
+                    try png.write(to: file, options: .atomic)
+                    parts.append(Part(ids: crop.ids, frame: crop.frame, image: crop.image, file: file))
+                }
+            } catch {
+                parts.forEach { try? FileManager.default.removeItem(at: $0.file) }
+                parts = []
+            }
+            DispatchQueue.main.async {
+                guard let self, self.generation == stamp, !self.touching,
+                      window.bounds.size == size, webView.convert(webView.bounds, to: window) == webFrame, parts.count == crops.count else {
+                    parts.forEach { try? FileManager.default.removeItem(at: $0.file) }
+                    complete([:]); return
+                }
+                self.captures[token] = Capture(size: size, webFrame: webFrame, parts: parts)
+                complete(["token": token, "parts": parts.map { part in
+                    ["ids": part.ids, "url": part.file.absoluteString,
+                     "x": part.frame.minX * ratio, "y": part.frame.minY * ratio,
+                     "width": part.frame.width * ratio, "height": part.frame.height * ratio] as [String: Any]
+                }])
+            }
+        }
+    }
+
+    /// Install prepared pixels before hiding live views, within the same main-thread turn.
+    /// A transient (moving) surface does not replace background covering ownership.
+    @discardableResult public func cover(_ token: String, in webView: UIView, views: [UIView], transient: Bool = false) -> Bool {
+        guard restore(in: webView, token: token, entry: true) else { return false }
+        if !transient { coveringToken = token }
+        hide(views, for: token)
+        return true
+    }
+
+    public var hidesNativeControls: Bool { hiddenControls != nil }
+
+    private func hide(_ views: [UIView], for token: String) {
+        generation += 1
+        restoreControls()
+        hiddenControls = (token, views.map { view in
+            let hidden = view.isHidden
+            view.isHidden = true
+            return { [weak view] in view?.isHidden = hidden }
+        })
+    }
+
+    // Undo only the entry handoff's mutation; normal update owns subsequent visibility.
+    public func restoreControls() {
+        hiddenControls?.restore.forEach { $0() }
+        hiddenControls = nil
+    }
+
+    public func identifiers(for token: String) -> Set<String> { Set(captures[token]?.parts.flatMap { $0.ids } ?? []) }
+
+    // Bridge the entry or return with the already prepared pixels until Web retires the copy.
+    // No capture, encoding, or decoding runs here.
+    public func restore(in webView: UIView, token explicitToken: String? = nil, frames: [String: CGRect]? = nil, entry: Bool = false) -> Bool {
+        guard let token = explicitToken ?? coveringToken, let capture = captures[token], let window = webView.window,
+              window.bounds.size == capture.size, webView.convert(webView.bounds, to: window) == capture.webFrame else { return false }
+        if let frames, capture.parts.contains(where: { part in !part.ids.allSatisfy { frames[$0] != nil } }) { return false }
+        clearRestoration()
+        let views = capture.parts.map { part in
+            let view = UIImageView(image: part.image)
+            view.frame = webView.convert(frames?[part.ids[0]] ?? part.frame, to: window)
+            view.isUserInteractionEnabled = false
+            view.isAccessibilityElement = false
+            window.addSubview(view)
+            return view
+        }
+        restoration = (token, views, entry)
+        // A lost cleanup message must never leave an obsolete cover on live UI.
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { [weak self] in
+            guard self?.restoration?.views.first === views.first else { return }
+            self?.clearRestoration()
+        }
+        return true
+    }
+
+    public func retireCopy(_ token: String, entry: Bool = true) {
+        // A late entry acknowledgement cannot remove the copy used on return.
+        guard restoration?.entry == entry, restoration?.token == token else { return }
+        clearRestoration()
+    }
+
+    private func clearRestoration() {
+        restoration?.views.forEach { $0.removeFromSuperview() }
+        restoration = nil
+    }
+
+    public func finishCovering() { coveringToken = nil }
+
+    public func release(_ token: String) {
+        if hiddenControls?.token == token { restoreControls() }
+        if coveringToken == token { coveringToken = nil }
+        if restoration?.token == token { clearRestoration() }
+        captures.removeValue(forKey: token)?.parts.forEach { try? FileManager.default.removeItem(at: $0.file) }
+    }
+
+    public func reset() {
+        restoreControls()
+        if let observer { window?.removeGestureRecognizer(observer) }
+        observer = nil
+        window = nil
+        touching = false
+        generation += 1
+        coveringToken = nil
+        Array(captures.keys).forEach(release)
+    }
+
+    deinit {
+        if let observer { window?.removeGestureRecognizer(observer) }
+        try? FileManager.default.removeItem(at: directory)
+    }
+}
+
+/// Observes the start of interaction without recognizing or delaying the app's gestures.
+private final class SnapshotTouchObserver: UIGestureRecognizer {
+    private let changed: (Bool) -> Void
+    private var touches = Set<UITouch>()
+    init(changed: @escaping (Bool) -> Void) {
+        self.changed = changed
+        super.init(target: nil, action: nil)
+        cancelsTouchesInView = false
+        delaysTouchesBegan = false
+        delaysTouchesEnded = false
+    }
+    override func canPrevent(_ other: UIGestureRecognizer) -> Bool { false }
+    override func canBePrevented(by other: UIGestureRecognizer) -> Bool { false }
+    override func touchesBegan(_ touches: Set<UITouch>, with event: UIEvent) {
+        let first = self.touches.isEmpty
+        self.touches.formUnion(touches)
+        if first { changed(true) }
+    }
+    override func touchesEnded(_ touches: Set<UITouch>, with event: UIEvent) { finish(touches) }
+    override func touchesCancelled(_ touches: Set<UITouch>, with event: UIEvent) { finish(touches) }
+    private func finish(_ touches: Set<UITouch>) {
+        self.touches.subtract(touches)
+        if self.touches.isEmpty { changed(false); state = .failed }
+    }
+}

package/ios/Sources/WebViewNativeUIEngine/Frame.swift

@@ -0,0 +1,15 @@
+import CoreGraphics
+public struct NativeUIFrame: Codable, Equatable {
+ public let x: Double
+ public let y: Double
+ public let width: Double
+ public let height: Double
+ public init(x: Double, y: Double, width: Double, height: Double) { self.x = x; self.y = y; self.width = width; self.height = height }
+ public var rect: CGRect { CGRect(x: x, y: y, width: width, height: height) }
+ public var isValid: Bool { [x, y, width, height].allSatisfy(\.isFinite) && width > 0 && height > 0 }
+}
+public struct NativeUIScrollNode: Decodable {
+ public let id: String
+ public let scroll: NativeUIScrollPlacement?
+ public init(id: String, scroll: NativeUIScrollPlacement?) { self.id = id; self.scroll = scroll }
+}