@webview-native-ui/engine 0.0.1 → 0.0.3

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

@@ -1,125 +1,3 @@
 # 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.
+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 Maven publication acceptance → npm engine; consumers upgrade separately. npm releases require a successful Maven publication workflow for the exact tagged commit. Maven Central distribution may still be pending: Android consumers must wait until the matching POM and AAR are downloadable, while iOS and Web consumers can upgrade immediately. 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 checks that this workflow succeeded for the exact release commit; it does not wait for Maven Central distribution. 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 the Maven publication workflow succeeds.
+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 Maven publication workflow succeeds, publish the prepared GitHub release. Note any pending Android artifact distribution in the release notes. `release.yml` verifies the tag, package version, CI and Maven publication acceptance 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.