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

package/dist/types.d.ts

@@ -0,0 +1,88 @@
+import type { WebProjectionScope } from './projection/scope.js';
+/** All wire coordinates are CSS pixels, relative to the Web viewport. */
+export interface Frame {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ScrollPlacement {
+    id: string;
+    reuse?: boolean;
+    offsetX: number;
+    offsetY: number;
+    viewport: Frame;
+    clip: Frame;
+    contentWidth: number;
+    contentHeight: number;
+    frame: Frame;
+}
+/** A source and its native rendering. Kind/placement are opaque layout identity keys. */
+export interface WebProjectionSource {
+    element: HTMLElement;
+    sources?: HTMLElement[];
+    scrollElement?: HTMLElement;
+    control: Frame & {
+        id: string;
+        kind?: string;
+        placement?: string;
+        dark?: boolean;
+        rtl?: boolean;
+        scroll?: ScrollPlacement;
+    };
+}
+/** Multiple fixed fallback elements sharing one Native capture/cover/restore transaction. */
+export interface ScopedWebProjectionSource extends WebProjectionSource {
+    scope: WebProjectionScope;
+}
+export interface PreparedWebProjection {
+    token: string;
+    parts: (Frame & {
+        ids: string[];
+        url: string;
+    })[];
+}
+/** Each action carries only the fields required by that phase of handoff. */
+export type WebProjectionRequest = {
+    action: 'prepare';
+    revision: number;
+    viewportWidth: number;
+    ids: string[];
+} | {
+    action: 'cover';
+    token: string;
+    transient?: boolean;
+} | {
+    action: 'restore';
+    token: string;
+    viewportWidth: number;
+    parts: (Frame & {
+        ids: string[];
+    })[];
+} | {
+    action: 'prepared' | 'painted' | 'restored' | 'release';
+    token: string;
+} | {
+    action: 'reset';
+};
+/** Empty prepare results mean capture is unavailable; a partial capture is never valid. */
+export type WebProjectionResult<Request extends WebProjectionRequest> = Request extends {
+    action: 'prepare';
+} ? PreparedWebProjection | {
+    token?: never;
+    parts?: never;
+} : Request extends {
+    action: 'cover' | 'restore';
+} ? {
+    shown: boolean;
+} : void;
+export interface ListenerHandle {
+    remove(): Promise<void> | void;
+}
+/** Implement with the owning plugin's existing ordered transport. No engine plugin registration. */
+export interface WebProjectionTransport {
+    send<Request extends WebProjectionRequest>(request: Request): Promise<WebProjectionResult<Request>>;
+    listen(listener: (event: {
+        active: boolean;
+    }) => void): Promise<ListenerHandle>;
+}

package/dist/types.js

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

package/docs/capacitor-plugin.md

@@ -0,0 +1,279 @@
+# Capacitor plugin integration
+
+Add Web projection and restoration to an existing Capacitor plugin without changing its public `registerPlugin()` export. The plugin keeps its native renderer and application API; the Engine coordinates its native view with a DOM fallback.
+
+This guide covers dependencies, registration, notifications and teardown. See [projection behavior](projection.md) for shared DOM requirements, capture policies and advanced integration.
+
+## Requirements
+
+This package declares support for Capacitor 8 (`>=8.0.0 <9`). The Engine library requires iOS 15+ and Android API 23+; the consuming Capacitor version or SDK may require a higher minimum. Composited Android capture requires API 26+ and the WebView features described in the [projection reference](projection.md#dom-and-native-surface-requirements).
+
+## Install inside a plugin
+
+```sh
+npm install --save-exact @webview-native-ui/engine@0.0.1
+```
+
+The npm archive contains TypeScript declarations, ESM, Swift sources and a podspec. Native dependencies must also be declared by the consuming plugin; an npm dependency alone links neither the Swift library nor the Android AAR.
+
+The primary native distribution is Swift Package Manager. Depend on the repository-root library from your plugin:
+
+```swift
+.package(url: "https://github.com/webview-native-ui/engine.git", exact: "0.0.1")
+// In the plugin target's dependencies:
+.product(name: "WebViewNativeUIEngine", package: "engine")
+```
+
+The new coordinates start at `0.0.1`. While the API is pre-1.0, pin the same Engine release across npm, SwiftPM, Gradle and CocoaPods, and upgrade deliberately. Applications should retain their dependency lockfiles for reproducible builds.
+
+SwiftPM resolves this repository's version tags such as `v0.0.1`. For unreleased integration tests, use a local checkout or an explicit tested commit.
+
+`import WebViewNativeUIEngine` requires no Capacitor registration. The npm companion supplies DOM measurement and Web image handoff; SwiftPM resolves the native dependency independently of npm hoisting.
+
+### Android: add the Maven dependency
+
+In the consuming plugin's `android/build.gradle`, add the Engine version matching its npm dependency:
+
+```groovy
+dependencies {
+    implementation 'io.github.webview-native-ui:engine:0.0.1'
+}
+```
+
+Ensure `google()` and `mavenCentral()` are present in the consuming build's dependency repositories. For a build using centralized repositories, merge them into `android/settings.gradle`:
+
+```groovy
+dependencyResolutionManagement {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+```
+
+If the build uses project-level repositories instead, add them to its existing `repositories` block. Installing the npm package does not add this Gradle dependency. Use a version whose POM and AAR are available from Central; `PUBLISHING` only confirms acceptance and does not yet guarantee downloads.
+
+### CocoaPods compatibility through npm
+
+CocoaPods uses the Swift sources and podspec shipped in npm; no CocoaPods Trunk publication is required. The plugin maintainer declares the matching dependency in the plugin's podspec:
+
+```ruby
+s.dependency 'WebViewNativeUIEngine', '0.0.1'
+```
+
+The maintainer must also document this one-time application setup. Install the matching engine version as a direct npm dependency, then add the local pod **inside the application's target, outside `def capacitor_pods`**, which Capacitor regenerates:
+
+```sh
+npm install --save-exact @webview-native-ui/engine@0.0.1
+```
+
+```ruby
+# ios/App/Podfile; adjust the path for a different native project layout.
+target 'App' do
+  capacitor_pods
+  pod 'WebViewNativeUIEngine', :path => '../../node_modules/@webview-native-ui/engine'
+end
+```
+
+Run `npx cap sync ios` and rebuild. Keep the direct engine version aligned with the consuming plugin's dependency when upgrading. With a nonstandard node_modules layout, point `:path` at the installed engine package directory. An npm dependency alone does not register a Pod, and a podspec dependency cannot specify this local path. The engine intentionally has no Capacitor plugin registration or Podfile rewriting hook. SwiftPM consumers do not need this CocoaPods setup.
+
+## Register from the native plugin
+
+Keep the plugin's normal `registerPlugin()` export and public methods unchanged. Create and retain a registration after creating the native renderer. The engine ships its Web runtime with the Swift/Android library, starts it in the current document and future documents, finds the existing fallback DOM, and subscribes to the plugin's notifications. Applications do not call a separate JS initializer.
+
+The integration has three responsibilities:
+
+1. The consumer provides an existing, laid-out Web fallback container in the correct layer. Pass this projection destination as the required `projectionSelector: string`; there is no `null` / automatic DOM creation mode.
+2. The plugin registers its native views and notification names once on each platform.
+3. The plugin emits notifications after its updates and releases the registration at teardown.
+
+### iOS: add the registration to your `CAPPlugin` class
+
+In `ios/Sources/ExamplePlugin/ExamplePlugin.swift`, retain the registration as a property and initialize it in `load()`, **after your existing renderer creates and attaches its view**.
+
+In this diff, `nativeView` is the `UIView` your plugin already owns; its existing rendering code is represented by comments.
+
+Use the existing **`jsName`**, not `identifier`: Capacitor uses `jsName` for JS plugin calls and event subscriptions. Do not repeat the plugin name in the Engine configuration.
+
+```diff
+ import Capacitor
+ import UIKit
++import WebViewNativeUIEngine
+
+ @objc(ExamplePlugin)
+ public class ExamplePlugin: CAPPlugin, CAPBridgedPlugin {
+     public let identifier = "ExamplePlugin"
+     public let jsName = "Example"
+     public let pluginMethods: [CAPPluginMethod] = [
+         CAPPluginMethod(name: "setColors", returnType: CAPPluginReturnPromise)
+     ]
+     private var nativeView: UIView?
++    private var projection: NativeUIProjection?
+
+     public override func load() {
+         // Existing code creates and attaches nativeView here.
++        do {
++            projection = try NativeUIProjection(
++                webView: bridge?.webView,
++                plugin: jsName,
++                projectionSelector: "#native-ui-fallback",
++                receiveListeners: .init(
++                    update: ["appearanceChanged"],
++                    projection: .init(
++                        native: ["shown"],
++                        web: ["transitionStarted"],
++                        none: ["hidden"]
++                    )
++                ),
++                view: { [weak self] in
++                    self?.nativeView
++                }
++            )
++        } catch {
++            CAPLog.print("Native UI projection unavailable: \(error)")
++        }
+     }
+
+     @objc func setColors(_ call: CAPPluginCall) {
+         DispatchQueue.main.async {
+             // Existing code applies the requested colors to nativeView.
++            self.notifyListeners("appearanceChanged", data: [:])
+             call.resolve()
+         }
+     }
++
++    public override func notifyListeners(_ eventName: String, data: [String: Any]?, retainUntilConsumed: Bool) {
++        projection?.receive(eventName, data: data)
++        super.notifyListeners(eventName, data: data, retainUntilConsumed: retainUntilConsumed)
++    }
++
++    deinit {
++        projection?.destroy()
++    }
+ }
+```
+
+Pass `bridge?.webView` directly. If the WebView is unavailable, the Engine throws an initialization error into the same `catch`; a separate guard or force unwrap is unnecessary.
+
+If the view is created later in an existing `initialize` / `show` method, put the registration there after view creation instead of in `load()`. Retain one registration for that renderer's lifetime; do not create another on every update. When replacing a renderer, destroy its old registration before registering the replacement.
+
+### Android: add the registration to your `Plugin` class
+
+Make the corresponding changes in `android/src/main/java/<your-package>/ExamplePlugin.kt`. **`pluginHandle.id`** is Capacitor's registered plugin name, derived from `@CapacitorPlugin`; no second name string is needed.
+
+```diff
+ import android.view.View
+ import com.getcapacitor.Plugin
+ import com.getcapacitor.PluginCall
+ import com.getcapacitor.PluginMethod
+ import com.getcapacitor.annotation.CapacitorPlugin
++import android.util.Log
++import com.getcapacitor.JSObject
++import io.github.webview_native_ui.engine.NativeUIProjection
++import io.github.webview_native_ui.engine.NativeUIProjection.ReceiveListeners
+
+ @CapacitorPlugin(name = "Example")
+ class ExamplePlugin : Plugin() {
+     private var nativeView: View? = null
++    private var projection: NativeUIProjection? = null
+
+     override fun load() {
+         // Existing code creates and attaches nativeView here.
++        projection = runCatching {
++            NativeUIProjection.install(bridge.webView)
++            NativeUIProjection(
++                window = activity.window,
++                webView = bridge.webView,
++                plugin = pluginHandle.id,
++                projectionSelector = "#native-ui-fallback",
++                receiveListeners = ReceiveListeners(
++                    update = listOf("appearanceChanged"),
++                    projection = ReceiveListeners.Projection(
++                        native = listOf("shown"),
++                        web = listOf("transitionStarted"),
++                        none = listOf("hidden")
++                    )
++                ),
++                view = { nativeView }
++            )
++        }.onFailure {
++            Log.e(javaClass.simpleName, "Native UI projection unavailable", it)
++        }.getOrNull()
+     }
+
+     @PluginMethod
+     fun setColors(call: PluginCall) {
+         activity.runOnUiThread {
+             // Existing code applies the requested colors to nativeView.
++            notifyListeners("appearanceChanged", JSObject())
+             call.resolve()
+         }
+     }
++
++    override fun notifyListeners(eventName: String, data: JSObject, retainUntilConsumed: Boolean) {
++        projection?.receive(eventName, data)
++        super.notifyListeners(eventName, data, retainUntilConsumed)
++    }
++
++    override fun handleOnDestroy() {
++        projection?.close()
++        projection = null
++        super.handleOnDestroy()
++    }
+ }
+```
+
+On Android, call `NativeUIProjection.install(bridge.webView)` in plugin `load()`,
+before the first navigation, even when SDK views arrive later. Include installation
+in the same error boundary as registration; if it fails, keep the existing Web
+fallback and do not retry installation after navigation. Registrations then
+share that main-frame, origin-restricted channel; they do not install new message
+listeners into a loaded WebView. This avoids a WebView native crash reproduced when
+registering an asynchronously loaded AdMob view. The registration constructor can
+install the channel only on an un-navigated WebView; late installation fails with
+an actionable error instead of attempting unsafe injection. All registrations on
+the same WebView must use the same allowed origins. Closing a registration removes
+only its owner from the channel, so other slots continue working. The shared channel
+remains installed for the WebView lifetime; registrations must still be retained
+and closed by their consuming plugin.
+
+Both diffs add a private property, native registration, a notification override, an update notification and teardown. They add no Engine methods to `pluginMethods`, no public JS wrapper, and no application-side Engine initializer.
+
+Keep your plugin's existing `registerPlugin()` export. Use the same event names in the registration and `notifyListeners`; if the plugin already emits a suitable event (such as `tabSelected`), list that event instead of emitting it twice.
+
+### Notifications during startup
+
+The notification override above lets the Engine retain the latest matching projection destination before the Web runtime subscribes. No separate state variable or initial-state callback is needed. Forward every notification to `super` as usual: the Engine records state without replaying notifications, updates, or user actions. Without a destination notification, it infers the initial destination from native view visibility. Registration must exist before the notifications it should observe.
+
+If your plugin owns multiple registrations, pass the notification to each registration; `receiveListeners.match` selects the owning surface. Appearance updates do not change the destination. The renderer still owns native placement and visibility before connection.
+
+With the default Web fallback, scrolling without a prepared image or native scroll binding keeps the Web fallback visible until the renderer confirms current native placement with its native-destination notification. An appearance update alone is not that confirmation. Consumers choosing native failure recovery must keep their own native geometry current.
+
+### Which events to emit
+
+All incoming event declarations belong to `receiveListeners`. Its `update` list refreshes the image, its `projection` lists select the destination, and its optional `match` filters notifications for the owning surface.
+
+| Notification                            | Where to emit it in the existing plugin                                               |
+| --------------------------------------- | ------------------------------------------------------------------------------------- |
+| `appearanceChanged` (an `update` event) | After a successful native appearance update, such as `setColors`                      |
+| `transitionStarted` (`web`)             | Before the fallback DOM starts moving or a Web layer covers the native view           |
+| `shown` (`native`)                      | After the plugin's existing show operation, or when returning from the Web projection |
+| `hidden` (`none`)                       | After the plugin's existing hide operation                                            |
+
+The names in the examples are conventions you choose, not reserved Engine methods. An `update` event refreshes the prepared image without changing the requested destination. It does not call `setColors` again.
+
+Emit `transitionStarted` before the DOM starts moving, `shown` when native projection is requested again, and `hidden` after the plugin's own hide operation. Native capture, URL conversion, image preparation, draw acknowledgement, image retirement and listener cleanup stay inside the engine. The engine never invokes the plugin's `show`, `hide`, selection or ad-loading methods. End the registration with `projection.destroy()` on iOS or `projection.close()` on Android when the renderer is destroyed. Retain the registration for its full lifetime and call native APIs on the UI thread.
+
+## DOM, scrolling and overlays
+
+Provide one laid-out DOM container for each registration, in the layer where its Web projection belongs. It may be inserted after registration. The plugin still owns native view placement and sizing; the Engine does not create or size either view for you.
+
+Read the [DOM and native surface requirements](projection.md#dom-and-native-surface-requirements) before integrating custom elements, SDK content or multiple surfaces. Scroll tracking and image handoff are internal to the registration. For Ionic applications, optionally enable [Ionic overlay support](projection.md#ionic-overlay-support-optional) once during application startup. Other frameworks emit the configured projection notifications from their own transition and overlay lifecycle.
+
+## Animated native controls
+
+Native appearance updates prepare replacement images after a 50 ms debounce by default.
+If your control continues animating after its update notification, set `captureDelayMs`
+on the native registration (Swift: `captureDelayMs: 600`; Kotlin: `captureDelayMs = 600`).
+This changes background image preparation, not overlay presentation timing.
+See [capture timing](projection.md#capture-timing) for the cache behavior and measured guidance.

package/docs/cordova-plugin.md

@@ -0,0 +1,198 @@
+# 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.
+
+## Requirements
+
+The integration is verified with cordova-ios 8.1.1 and cordova-android 15.1.0 using their standard WebViews. The Engine itself requires iOS 15+ and Android API 23+; the Cordova host or SDK may require a higher minimum. Composited Android capture requires API 26+.
+
+## Dependencies
+
+Use the same Engine release for the Web package and native libraries. The API is pre-1.0; pin versions and retain dependency lockfiles.
+
+```sh
+npm install --save-exact @webview-native-ui/engine@0.0.1
+```
+
+Declare the native dependencies in the consuming plugin as well. npm installation alone does not link either native library.
+
+For Swift Package Manager:
+
+```swift
+.package(url: "https://github.com/webview-native-ui/engine.git", exact: "0.0.1")
+// In the plugin target's dependencies:
+.product(name: "WebViewNativeUIEngine", package: "engine")
+```
+
+For the plugin's Android Gradle configuration:
+
+```groovy
+dependencies {
+    implementation 'io.github.webview-native-ui:engine:0.0.1'
+}
+```
+
+Keep `google()` and `mavenCentral()` in the consuming build's dependency repositories.
+
+## iOS
+
+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. Keep the plugin's existing SwiftPM product and source-file declarations.
+
+In the iOS platform section of `plugin.xml`, register the plugin for startup if its renderer should appear before the first application call:
+
+```xml
+<platform name="ios" package="swift">
+    <config-file target="config.xml" parent="/*">
+        <feature name="ExamplePlugin">
+            <param name="ios-package" value="ExamplePlugin" />
+            <param name="onload" value="true" />
+        </feature>
+    </config-file>
+    <!-- Keep the plugin's existing source-file declarations. -->
+</platform>
+```
+
+Merge these entries into the existing platform sections rather than adding duplicate sections. The [integration fixture](https://github.com/webview-native-ui/engine/tree/main/tests/cordova/plugin) includes complete plugin.xml, SwiftPM and Gradle wiring.
+
+The examples extend an existing renderer: `nativeView` is its attached, positioned view, not a view created by the Engine.
+
+```swift
+import Cordova
+import WebKit
+import WebViewNativeUIEngine
+
+@objc(ExamplePlugin)
+class ExamplePlugin: CDVPlugin {
+    private var projection: NativeUIProjection?
+    private var nativeView: UIView?
+
+    override func pluginInitialize() {
+        // Existing renderer creates, attaches and positions nativeView here.
+        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()
+    }
+}
+```
+
+If the iOS renderer loads later, create the registration after its view is attached, and destroy the old registration before replacing the renderer.
+
+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. In the Android platform section of the plugin's `plugin.xml`, merge this registration so initialization runs before the first WebView navigation:
+
+```xml
+<platform name="android">
+    <config-file target="res/xml/config.xml" parent="/*">
+        <feature name="ExamplePlugin">
+            <param name="android-package" value="com.example.ExamplePlugin" />
+            <param name="onload" value="true" />
+        </feature>
+    </config-file>
+    <!-- Keep existing source-file and Gradle framework declarations. -->
+</platform>
+```
+
+```kotlin
+import android.view.View
+import android.webkit.WebView
+import io.github.webview_native_ui.engine.NativeUIProjection
+import org.apache.cordova.CordovaPlugin
+import org.apache.cordova.CordovaPluginPathHandler
+
+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)
+            // Existing renderer creates, attaches and positions nativeView here.
+            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. If the renderer loads asynchronously, keep `install(web)` in `pluginInitialize()` and create the registration after the view is ready. Close the old registration before replacing that renderer.
+
+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. See the shared [DOM and native surface requirements](projection.md#dom-and-native-surface-requirements) for selector, layout and capture rules. [Ionic overlay support](projection.md#ionic-overlay-support-optional) remains optional; 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.
+
+## Animated native controls
+
+Native appearance updates prepare replacement images after a 50 ms debounce by default.
+If your control continues animating after its update notification, set `captureDelayMs`
+on the native registration (Swift: `captureDelayMs: 600`; Kotlin: `captureDelayMs = 600`).
+This changes background image preparation, not overlay presentation timing.
+See [capture timing](projection.md#capture-timing) for the cache behavior and measured guidance.

package/docs/cordova.md

@@ -0,0 +1,3 @@
+# Cordova plugin integration
+
+This guide has moved to [Cordova plugin integration](cordova-plugin.md).

package/docs/maintenance.md

@@ -0,0 +1,52 @@
+# Development and releases
+
+## Development
+
+The public entry points are `src/index.ts` and `src/ionic.ts`, with shared contracts in `src/types.ts`. Implementation is grouped by responsibility:
+
+- `src/native/`: bridge transport, native sessions, startup and resource URLs.
+- `src/projection/`: image handoff, projection ownership, events and styles.
+- `src/dom/`: geometry, scrolling, visibility and overlay coordination.
+
+`npm run build` bundles `src/native/bootstrap.ts` into `runtime/native-ui-engine.js`, the shared WebView runtime. Android packages this file directly as an asset. The build also copies it into `ios/Sources/WebViewNativeUIEngine/Resources` because SwiftPM requires resources inside the target directory. Both generated files are committed so native consumers do not need Node.js. Edit the TypeScript source, not either generated file; CI checks regeneration and verifies the runtime included in npm and Maven archives.
+
+Browser tests mirror these groups under `tests/`. `tests/cordova/` contains the real native consumer fixture.
+
+Use Node.js 24, matching CI. From this repository:
+
+```sh
+npm ci
+npm run build
+npm run lint
+npx playwright install chromium
+npm test
+xcodebuild -scheme WebViewNativeUIEngine -destination 'platform=iOS Simulator,id=<booted simulator UUID>' test
+```
+
+Lint combines strict TypeScript checking, the standard ESLint/TypeScript recommended rules, and typed Promise checks for `src`. Scripts and tests receive syntax-level linting; Prettier owns formatting. `npm run format` applies formatting only. Bridge payloads and test doubles may use explicit `any`; production boundary validation remains necessary. An explicit `void` marks background work, but does not handle a rejected Promise. Android uses `lintRelease` with warnings treated as errors in CI; Swift is compiled and tested on an iOS simulator.
+
+The engine is versioned independently of its consumers. Publish order is the native Maven artifact → npm engine; consumers upgrade separately. npm releases verify that the matching POM and AAR exist on Maven Central before publication. No publication is performed by build or test commands. Tests cover plain DOM, fractional/RTL geometry, stale ACKs, image ownership and native WKWebView scroll tracking; consumer tests remain responsible for Ionic/SDK integration.
+
+CI-only setup, packaging commands and GitHub outputs are defined in `.github/workflows/`. Scripts retain the runtime build, reusable consumer/package verification, and tested publication logic (Central state handling and npm artifact comparison).
+
+## Maven publication
+
+The `Native UI Engine Maven Release` workflow is manually dispatched on `main` with the exact engine package version. That commit must first pass `Native UI Engine` CI. It signs an AAR, source archive, generated Kotlin API documentation and Maven metadata, uploads once, and completes when Central reports `PUBLISHING` or `PUBLISHED`. The deployment ID and state changes are recorded in the run summary. `PUBLISHING` means validation passed and Central accepted publication; it does not guarantee that artifacts can already be downloaded. This workflow does not wait for distribution. The npm release still requires the matching POM and AAR to be available on Maven Central. Existing coordinates are never overwritten; if an upload times out, inspect the recorded deployment in Central before taking further action.
+
+Configure the repository's Actions secrets with `CENTRAL_USERNAME`, `CENTRAL_PASSWORD` (a Central user token), `MAVEN_SIGNING_KEY` (ASCII-armored private key) and `MAVEN_SIGNING_PASSWORD`. The signing public key must be available to Central. GitHub secrets are scoped to this repository.
+
+For local packaging verification, run `python3 scripts/native-ui-engine-release/verify.py` with JDK 21, Android SDK 36 and GnuPG. It creates a disposable key, validates signatures and checksums, and deletes its test ZIP without uploading. Publication always rebuilds from clean outputs with the real signing key. Publish its Maven artifact before the corresponding npm release, including prereleases.
+
+## Maintainer release setup
+
+This repository starts from the merged Engine implementation at [ionic-theme-ios27 `b218d8b`](https://github.com/rdlabo-dev/ionic-theme-ios27/commit/b218d8bfe0c87c02addc668fee9c7aa333489486). Extraction preserves the merged implementation; Cordova host support is developed in this repository. The renamed package starts at version `0.0.1`. Publish the same version for npm, SwiftPM and Maven; do not reuse the old package coordinates.
+
+The npm organization `webview-native-ui` and Maven Central namespace `io.github.webview-native-ui` are registered. Maintain npm trusted publishing for `webview-native-ui/engine`, workflow `release.yml`, and provision the Maven secrets above in this repository. Credentials are not copied by moving source files.
+
+1. Prepare the next version and release notes on `main`; use `npm run release` to create a standard `vX.Y.Z` tag/GitHub release. Keep the GitHub release as a draft until Maven is downloadable.
+2. After that main commit passes CI, dispatch `native-ui-engine-release.yml` with the exact package version.
+3. Central `PUBLISHING` is an accepted upload, not download readiness. Once the POM and AAR are available, publish the prepared GitHub release. `release.yml` verifies the tag, package version, CI and Maven artifacts before npm publication (`next` for prereleases, `latest` otherwise).
+
+No build or test command publishes a package. Existing npm/Maven versions are never overwritten.
+
+To rerun release verification for an existing tag, dispatch `release.yml` with that tag. It checks the original tagged commit and skips npm publication only when the existing package contents match. Keep the tag unchanged. Release tooling uses the Node.js 24 bundled npm, matching CI.