@webview-native-ui/engine 0.0.5 → 0.0.7

package/docs/reference/projection.md

@@ -0,0 +1,134 @@
+# Projection reference
+
+Use this reference to check integration contracts and platform limits. Start with
+[concepts and integration choices](../concepts.md) to decide whether the Engine fits
+your UI. Use [native initialization](../getting-started/initialization.md) to distinguish required
+inputs, optional settings and advanced APIs, then follow the [Capacitor](../getting-started/capacitor.md),
+[Cordova](../getting-started/cordova.md) or [renderer](../advanced/renderer.md) guide.
+
+This page covers DOM lifetime, destination precedence, host requirements and native
+eligibility. See [platform limits](platforms.md) for capture details, [projection state](state.md)
+for the intent attribute, and [container support](containers.md) for HTML/Ionic hosts.
+
+Use this contract when deciding what must survive a transition. For example, a
+modal closes while a native restore reply is still in flight, and the framework
+replaces the page DOM. The old reply must not reveal the departed page's controls;
+the lifetime and destination rules below define that boundary.
+
+## DOM and page lifetime
+
+Native registration is independent of the JavaScript framework. Its selector identifies
+one fallback container in the current document; it may appear after registration.
+When a framework removes or replaces that container, the Engine retires the old
+projection and binds the current matching element. A pending drag or native draw
+acknowledgement from the departed container must not hold up its replacement.
+Moving the same element between parents refreshes its scroll bindings without
+requiring the plugin to register it again.
+
+A full HTML navigation creates a new document and runtime session. The native
+registration installs the runtime in the new document and retains the plugin's
+explicit projection destination; images and replies belong to their original
+document. Keep registrations for the native renderer's lifetime, rather than
+recreating them for each framework page event.
+
+These rules apply to selector-based native registration. A lower-level
+`createWebProjectionScope(element)` intentionally binds that particular element;
+its renderer remains responsible for replacing the scope when it changes elements.
+
+The Engine cannot infer every framework's transition or modal semantics from DOM
+mutations. Use the existing projection notifications for those transitions, and an
+explicit overlay integration when needed. Ionic support is opt-in; it is not required
+for ordinary DOM lifetime handling. Framework-specific events are not installed
+automatically. Native view creation, layout constraints and SDK
+lifecycle remain owned by the plugin.
+
+## Projection contract
+
+A notification specifies **where the surface belongs**, not how to capture it. The Engine chooses the platform-specific handoff without requiring the plugin to keep another copy of projection state.
+
+| Intended destination | Required behavior                                                                                                                      |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `native`             | Show the interactive native view at confirmed geometry. During motion, use supported native tracking or a prepared image.              |
+| `web`                | Keep native content below the covering Web layer by removing its native projection; use a prepared image or the plugin's Web fallback. |
+| `none`               | Retire native content, projected images and fallback content. Later update/capture callbacks must not show it again.                   |
+
+Overlay coverage can temporarily turn `native` into `web`; it never overrides `none`. A capture failure does not change the intended destination. `failedFallback: native` is only valid for consumers that maintain native placement themselves, and never overrides explicit `web`, `none`, or overlay coverage.
+
+The Engine owns image readiness and restoration acknowledgement. It must not hide native pixels before replacement pixels are ready, nor retire replacement pixels before native restoration succeeds. Position-only motion reuses prepared content; appearance, size and renderer identity changes invalidate it. A missing image uses the declared fallback immediately rather than waiting to capture during a transition.
+
+Registration and notification forwarding retain the latest intent across startup and reconnection; they do not replay business events. Destruction retires the registration and its cached images. Notifications are intent, not completion promises: an API that promises completed hiding must await the explicit retirement acknowledgement described under DOM and native surface requirements.
+
+An existing renderer that checks CSS visibility can call `getUnprojectedVisibility(element)` from the npm package. It reads current authored/inherited visibility without the Engine's hiding rules, and restores projection ownership before returning. Do not use Engine marker attributes to infer projection ownership or mutate them in a consuming plugin. See [renderer DOM integration](../advanced/web-projection.md) for excluding Engine-owned mutations from renderer invalidation. This helper performs a style read and can trigger attribute observers; it does not eliminate measurement or transport costs.
+
+## DOM and native surface requirements
+
+`projectionSelector` is required and must resolve to **one existing container when projection starts**, using a valid CSS selector. ID, class, attribute and descendant selectors are supported; zero or multiple matches leave Native hidden. The engine does not create the fallback container or choose its size, placement, layer or z-index. Keep the container's normal layout and any interactive Web controls; an empty zero-size placeholder is not a usable fallback. It is a fixed scope, not a discovery root.
+
+The container does not have to exist at registration time. A missing DOM waits without showing native content; replacing it creates a new binding and retires old images. The engine preserves the container's children, listeners and values. Pass the native view itself through `view`; a group of controls can use their common native container. The engine manages the internal identifier, so no ID list or view dictionary is required. Independent surfaces use separate registrations.
+
+A Web Component host can be the destination, for example `projectionSelector: 'native-ad[placement="home"]'`. Give the host a layout box (`display: block` with the intended dimensions); the engine observes insertion, removal and selector attribute changes. The selector runs in the document and does not search inside shadow roots. The engine suppresses fallback content and pseudo-elements in the light DOM and open shadow roots during projection. Closed shadow content cannot be inspected and must inherit the host's `visibility`; provide a container whose shadow/slot structure can display the inserted image.
+
+See [Projection container support](containers.md) for the HTML and complete Ionic element tables, sizing conditions and a wrapper example.
+
+### Native surface requirements
+
+When a plugin displays several independently moving native views—for example,
+several advertisements in a scrolling feed—create a separate registration for
+each view and give each one a selector matching its own DOM container. This lets
+one view move, hide or be replaced without changing another view's projection.
+
+If those registrations share plugin notifications, use `receiveListeners.match`
+to route each notification to its intended registration. The matching fields are
+chosen by your plugin, not reserved Engine identifiers. For example, include
+`viewKey` to identify the displayed item and `instanceId` to distinguish successive
+loaded instances for that item:
+
+```swift
+match: ["viewKey": viewKey, "instanceId": instanceId]
+```
+
+```kotlin
+match = mapOf("viewKey" to viewKey, "instanceId" to instanceId)
+```
+
+Include the same fields in the notification payload. Dispose the old registration
+when replacing its loaded content, even if the native container is reused, so
+notifications for the previous instance cannot affect the replacement.
+
+For third-party SDK views, keep loading and interaction handling in your plugin.
+Use `canCapture` to report whether the current content may be captured under the
+SDK's rules and your integration's supported capture conditions. For example, an
+advertising SDK may require different handling for video and static content.
+The Engine does not grant permission to capture SDK content or replace its
+click and impression handling.
+
+For SDK consumers without an equivalent Web fallback, set `failedFallback: .native`
+on iOS or `failedFallback = NativeUIProjection.FailedFallback.NATIVE` on Android.
+The default is `.web` / `WEB`, preserving existing consumers. If automatic motion
+cannot use a prepared image (not ready, unsupported capture, or rejected handoff),
+`native` preserves the live native view and keeps fallback DOM hidden. The consumer
+must continue positioning that view; this option does not create native scroll
+tracking on Android. Explicit `web`, `none`, and overlay coverage take precedence:
+this option never raises a native view above an intentionally covering Web layer.
+
+On Android, consumers whose asynchronous hide method promises that all pixels have
+disappeared must call `projection.hide { completed -> ... }` and resolve only when
+`completed` is true. Native handoff copies disappear immediately; completion waits
+for synchronous Web-proxy retirement. A timeout reports failure, not success.
+Call `projection.show()` when presenting again, in addition to normal plugin events;
+this also preserves presentation intent if event subscription is still starting.
+
+Scroll observation follows composed-tree ancestors, including assigned slots.
+Non-composed scroll events inside an Ionic shadow tree are observed at their source;
+applications do not add an extra listener or dispatch synthetic document events.
+Listeners follow host reparenting and slot reassignment and are removed on teardown.
+
+Scrolling is internal: iOS uses a uniquely matched native scroll binding when available; otherwise, including Android, scrolling temporarily uses the prepared image and restores native content after motion settles. Automatic scroll handling never overrides explicit `web` or `none`. Unsupported capture or geometry keeps the normal DOM fallback; it does not wait for a new capture on the transition path. The latest explicit destination survives WebView reload, and old-document replies cannot complete a new document's requests.
+
+By default, the internal channel is limited to the main frame on Capacitor's localhost origins. Pass the application's exact `allowedOrigins` for a different configured origin. Android requires WebView's `WEB_MESSAGE_LISTENER` and `DOCUMENT_START_SCRIPT` features; registration fails explicitly on unsupported WebView implementations. Do not use wildcard origins for remotely navigable WebViews.
+
+For capture modes, translucent surfaces, image color and private storage, see
+[capture and platform limits](platforms.md). Custom renderer bridge and scroll
+bindings are documented under [native handoff](../advanced/native-handoff.md).
+
+[Documentation overview](../README.md)

package/docs/reference/state.md

@@ -0,0 +1,39 @@
+# Observe projection state
+
+Projection state answers **where the component should be presented**. It is
+independent of its value, such as a toggle's checked state or a selected tab.
+See [value bindings](../configuration/values.md) for that connection.
+
+For example, a tab bar unexpectedly remains hidden after dismissing a modal.
+Inspect this attribute to distinguish a remaining `web` request from a `native`
+request whose restoration is still pending. It helps diagnose the ownership
+choice; it is not permission to reveal the bar or discard its image early.
+
+A selector-based `NativeUIProjection` registration writes the read-only
+`data-native-ui-destination` attribute on its current DOM container:
+
+| Value    | Meaning                                                                                         |
+| -------- | ----------------------------------------------------------------------------------------------- |
+| `native` | Native presentation is requested.                                                               |
+| `web`    | Web presentation is requested, explicitly or because a registered overlay covers the container. |
+| `none`   | No presentation is requested.                                                                   |
+
+Without a prior destination notification, startup derives the initial intent from
+native view visibility; a hidden or absent view starts as `none`. The plugin's
+projection events then select `native`, `web` or `none`. Overlay coverage
+changes an otherwise native request to Web; it does not override an explicit
+`none`. The Engine updates the attribute as it reconciles presentation and removes
+it when the container is replaced or the registration is destroyed. Reserve this
+attribute for the Engine rather than setting it from application code.
+
+This is presentation **intent**, not an acknowledgement that a native frame or
+image has finished drawing. Web presentation may use a cached native image or the
+existing interactive fallback according to availability and the integration's
+policy. Do not hide the fallback solely because this attribute says `native`:
+the Engine's handoff keeps the previous representation until the next one is ready.
+
+Use this attribute for diagnostics and application state that does not take over
+visibility. Continue using the documented projection events to request a change.
+See the [projection contract](projection.md#projection-contract) for ownership,
+fallback and interaction rules. Internal snapshot attributes are not additional
+public state APIs.

package/ios/Sources/WebViewNativeUIEngine/ClippedView.swift

@@ -1,16 +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 }
- }
+    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

@@ -27,6 +27,66 @@ public final class NativeUICoveredSnapshots {
     private var observer: SnapshotTouchObserver?
     private let directory = FileManager.default.temporaryDirectory.appendingPathComponent("native-ui-snapshots-\(UUID().uuidString)")
     public private(set) var coveringToken: String?
+    /// Dispatch the renderer's existing ordered image-handoff transport on the main thread.
+    /// The renderer supplies eligible native bounds and the complete views that may be hidden.
+    public func handle(_ request: [String: Any], in webView: UIView,
+                       frames: @escaping (Set<String>, Int) -> [String: CGRect],
+                       views: (Set<String>) -> [UIView]?, complete: @escaping ([String: Any]) -> Void) {
+        let token = request["token"] as? String ?? ""
+        switch request["action"] as? String {
+        case "prepare":
+            guard let ids = request["ids"] as? [String], !ids.isEmpty, !ids.contains(""), Set(ids).count == ids.count,
+                  let revision = request["revision"] as? Int,
+                  let width = request["viewportWidth"] as? Double, width.isFinite, width > 0 else { complete([:]); return }
+            let expected = Set(ids)
+            let firstFrames = frames(expected, revision)
+            guard Set(firstFrames.keys) == expected else { complete([:]); return }
+            var initial: [String: CGRect]? = firstFrames
+            prepare(frames: {
+                let measured = initial ?? frames(expected, revision)
+                initial = nil
+                return Set(measured.keys) == expected ? measured : [:]
+            }, in: webView, viewportWidth: width, complete: complete)
+        case "cover":
+            let ids = identifiers(for: token)
+            let destination = request["parts"] == nil ? nil : projectionFrames(request, in: webView)
+            guard !ids.isEmpty, let selected = views(ids), !selected.isEmpty,
+                  request["parts"] == nil || destination != nil else { complete(["shown": false]); return }
+            var seen = Set<ObjectIdentifier>()
+            complete(["shown": cover(token, in: webView, views: selected.filter { seen.insert(ObjectIdentifier($0)).inserted },
+                                     transient: request["transient"] as? Bool == true, frames: destination)])
+        case "restore":
+            guard let destination = projectionFrames(request, in: webView) else { complete(["shown": false]); return }
+            complete(["shown": restore(in: webView, token: token, frames: destination)])
+        case "painted", "restored":
+            retireCopy(token, entry: request["action"] as? String == "painted")
+            complete([:])
+        case "release": release(token); complete([:])
+        case "reset": reset(); complete([:])
+        default: complete([:])
+        }
+    }
+
+    /// Convert Web viewport CSS pixels to native points, rejecting partial or malformed destinations.
+    func projectionFrames(_ request: [String: Any], in webView: UIView) -> [String: CGRect]? {
+        guard let token = request["token"] as? String,
+              let width = request["viewportWidth"] as? Double, width.isFinite, width > 0,
+              webView.bounds.width > 0, let parts = request["parts"] as? [[String: Any]], !parts.isEmpty else { return nil }
+        let scale = webView.bounds.width / width
+        var result: [String: CGRect] = [:]
+        for part in parts {
+            guard let ids = part["ids"] as? [String], !ids.isEmpty,
+                  let x = part["x"] as? Double, let y = part["y"] as? Double,
+                  let w = part["width"] as? Double, let h = part["height"] as? Double,
+                  [x, y, w, h, x * scale, y * scale, w * scale, h * scale].allSatisfy({ $0.isFinite }), w > 0, h > 0 else { return nil }
+            for id in ids {
+                guard !id.isEmpty, result[id] == nil else { return nil }
+                result[id] = CGRect(x: x * scale, y: y * scale, width: w * scale, height: h * scale)
+            }
+        }
+        return !result.isEmpty && Set(result.keys) == identifiers(for: token) ? result : nil
+    }
+
     public var covering: Bool { coveringToken != nil }
 
     public func observe(_ window: UIWindow, changed: @escaping (Bool) -> Void) {
@@ -46,7 +106,7 @@ public final class NativeUICoveredSnapshots {
     // 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) {
+                        complete: @escaping ([String: Any]) -> Void) {
         let stamp = generation
         let start = CACurrentMediaTime()
         func sample(_ previous: [String: CGRect], _ stable: Int) {
@@ -63,7 +123,7 @@ public final class NativeUICoveredSnapshots {
     }
 
     private func capture(frames: [String: CGRect], in webView: UIView, viewportWidth: CGFloat,
-                 complete: @escaping ([String: Any]) -> Void) {
+                         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
@@ -88,8 +148,9 @@ public final class NativeUICoveredSnapshots {
         guard let space = CGColorSpace(name: CGColorSpace.extendedDisplayP3),
               let outputSpace = CGColorSpace(name: CGColorSpace.displayP3),
               let context = CGContext(data: nil, width: Int(bounds.width * scale), height: Int(bounds.height * scale),
-                bitsPerComponent: 16, bytesPerRow: 0, space: space,
-                bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue | CGBitmapInfo.floatComponents.rawValue | CGBitmapInfo.byteOrder16Little.rawValue)
+                                      bitsPerComponent: 16, bytesPerRow: 0, space: space,
+                                      bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue |
+                                        CGBitmapInfo.floatComponents.rawValue | CGBitmapInfo.byteOrder16Little.rawValue)
         else { complete([:]); return }
         context.translateBy(x: 0, y: bounds.height * scale)
         context.scaleBy(x: scale, y: -scale)
@@ -116,12 +177,12 @@ public final class NativeUICoveredSnapshots {
                 for (index, crop) in crops.enumerated() {
                     guard let pixels = crop.image.cgImage,
                           let png = imageContext.pngRepresentation(of: CIImage(cgImage: pixels), format: .RGBA16,
-                            colorSpace: outputSpace, options: [:]) else { throw CocoaError(.fileWriteUnknown) }
+                                                                   colorSpace: outputSpace, options: [:]) else { throw CocoaError(.fileWriteUnknown) }
                     // Native entry/return copies must use the same encoded pixels as Web,
                     // including gamut clipping performed by integer PNG conversion.
                     guard let source = CGImageSourceCreateWithData(png as CFData, nil),
                           let decoded = CGImageSourceCreateImageAtIndex(source, 0,
-                            [kCGImageSourceShouldCacheImmediately: true] as CFDictionary)
+                                                                        [kCGImageSourceShouldCacheImmediately: true] as CFDictionary)
                     else { throw CocoaError(.fileWriteUnknown) }
                     let image = UIImage(cgImage: decoded, scale: scale, orientation: .up)
                     let file = directory.appendingPathComponent("\(token)-\(index).png")
@@ -150,8 +211,8 @@ public final class NativeUICoveredSnapshots {
 
     /// 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 }
+    @discardableResult public func cover(_ token: String, in webView: UIView, views: [UIView], transient: Bool = false, frames: [String: CGRect]? = nil) -> Bool {
+        guard restore(in: webView, token: token, frames: frames, entry: true) else { return false }
         if !transient { coveringToken = token }
         hide(views, for: token)
         return true
@@ -238,7 +299,7 @@ public final class NativeUICoveredSnapshots {
     }
 }
 
-/// Observes the start of interaction without recognizing or delaying the app's gestures.
+// 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>()

package/ios/Sources/WebViewNativeUIEngine/Frame.swift

@@ -1,15 +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 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 }
+    public let id: String
+    public let scroll: NativeUIScrollPlacement?
+    public init(id: String, scroll: NativeUIScrollPlacement?) { self.id = id; self.scroll = scroll }
 }