@webview-native-ui/engine 0.0.5 → 0.0.7

package/docs/{capacitor-plugin.md → getting-started/capacitor.md}

@@ -2,16 +2,32 @@
 
 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.
+This guide covers dependencies, registration, notifications and teardown. Start with
+[native initialization](initialization.md) for the minimal call, required inputs
+and ownership; the plugin diffs below add event wiring and lifetime handling. Use the [projection reference](../reference/projection.md) for exact contracts and platform limits.
+
+For a Capacitor tab-bar plugin, the application should keep calling the same
+show and selection methods. Add the registration in the native plugin, then
+forward its successful updates so a Web modal can cover the bar without requiring
+every application to implement image handoff.
 
 ## 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).
+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](../reference/projection.md#dom-and-native-surface-requirements).
+
+## Choose the Web destination
+
+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.
+
+Choose a [supported container](../reference/containers.md) before wiring its selector. Read the [DOM and native surface requirements](../reference/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](../configuration/ionic-overlays.md) once during application startup. Other frameworks emit the configured projection notifications from their own transition and overlay lifecycle.
 
 ## Install inside a plugin
 
+Replace `<engine-version>` in every dependency below with the same published
+release. Read that release tag’s documentation so the examples match its APIs.
+
 ```sh
-npm install --save-exact @webview-native-ui/engine@0.0.1
+npm install --save-exact '@webview-native-ui/engine@<engine-version>'
 ```
 
 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.
@@ -19,12 +35,12 @@ The npm archive contains TypeScript declarations, ESM, Swift sources and a podsp
 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")
+.package(url: "https://github.com/webview-native-ui/engine.git", exact: "<engine-version>")
 // 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.
+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.
 
@@ -36,7 +52,7 @@ In the consuming plugin's `android/build.gradle`, add the Engine version matchin
 
 ```groovy
 dependencies {
-    implementation 'io.github.webview-native-ui:engine:0.0.1'
+    implementation 'io.github.webview-native-ui:engine:<engine-version>'
 }
 ```
 
@@ -58,13 +74,13 @@ If the build uses project-level repositories instead, add them to its existing `
 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'
+s.dependency 'WebViewNativeUIEngine', '<engine-version>'
 ```
 
 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
+npm install --save-exact '@webview-native-ui/engine@<engine-version>'
 ```
 
 ```ruby
@@ -81,6 +97,9 @@ Run `npx cap sync ios` and rebuild. Keep the direct engine version aligned with
 
 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 [notification contract](../configuration/events.md) defines which successful
+changes to report and how startup routing works.
+
 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.
@@ -228,12 +247,12 @@ before the first navigation, even when SDK views arrive later. Include installat
 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
+listeners into a loaded WebView. Installing the channel before navigation avoids a WebView native crash when
+registering a view that loads asynchronously. 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
+only its owner from the channel, so other registered views continue working. The shared channel
 remains installed for the WebView lifetime; registrations must still be retained
 and closed by their consuming plugin.
 
@@ -241,43 +260,22 @@ Both diffs add a private property, native registration, a notification override,
 
 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.
+## Verify the integration
 
-## Animated native controls
+Show the control, change its appearance, then open and dismiss a covering Web
+overlay. Check that the prepared appearance belongs to the current control and
+that native interaction returns at the current position. Also check hiding,
+container replacement and plugin teardown: late replies must not reveal retired
+content. Exercise a missing image to verify the chosen Web fallback.
 
-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.
+Use the actual control and backgrounds on supported devices; bridge success alone
+cannot verify visual continuity. For a renderer that already batches controls by
+page, continue with the [renderer guide](../advanced/renderer.md) rather than duplicating
+registration machinery for each handoff.
 
-### Projection DOM
+## Next: choose optional behavior
 
-The engine keeps a reusable image inside the fallback container, using its open ShadowRoot when available. No placement option is needed. If the renderer inspects child elements, exclude nodes marked `data-native-ui-projection-node`. See [DOM requirements](projection.md#dom-and-native-surface-requirements).
+Use the [configuration guide](../configuration/README.md) for notification routing,
+value reflection, capture timing and fallback policy. These shared settings are
+not additional platform setup. For a renderer that already batches controls, see
+[advanced APIs](../advanced/README.md).

package/docs/{cordova-plugin.md → getting-started/cordova.md}

@@ -4,16 +4,38 @@ The same npm package, Swift library and Android AAR support Capacitor and Cordov
 
 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.
 
+See [native initialization](initialization.md) for required inputs and ownership. The platform examples below add Cordova-specific
+startup, notification forwarding and teardown. Set `runtime` to Cordova even
+though it is optional in the constructor.
+
+For a Cordova plugin showing a native advertisement in a feed, the application
+already owns a DOM slot and the plugin owns SDK interaction. This route connects
+that slot to projection without adding a Capacitor dependency or replacing the
+SDK's click handling; capture must still be allowed for the loaded content.
+
 ## 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+.
 
+## Choose the Web destination
+
+Provide a laid-out container such as `native-ad` or `#player` in the layer where
+the projected appearance should live. It may be inserted after registration, but
+must exist when projection starts. The native view's rectangle cannot identify
+its intended place in the DOM stacking tree. Check the
+[container support table](../reference/containers.md) before choosing the selector.
+For Ionic applications, add [overlay support](../configuration/ionic-overlays.md) once; other
+frameworks report their own transition lifecycle through notifications.
+
 ## Dependencies
 
+Replace `<engine-version>` in every dependency below with the same published
+release. Read that release tag’s documentation so the examples match its APIs.
+
 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
+npm install --save-exact '@webview-native-ui/engine@<engine-version>'
 ```
 
 Declare the native dependencies in the consuming plugin as well. npm installation alone does not link either native library.
@@ -21,7 +43,7 @@ Declare the native dependencies in the consuming plugin as well. npm installatio
 For Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/webview-native-ui/engine.git", exact: "0.0.1")
+.package(url: "https://github.com/webview-native-ui/engine.git", exact: "<engine-version>")
 // In the plugin target's dependencies:
 .product(name: "WebViewNativeUIEngine", package: "engine")
 ```
@@ -30,7 +52,7 @@ For the plugin's Android Gradle configuration:
 
 ```groovy
 dependencies {
-    implementation 'io.github.webview-native-ui:engine:0.0.1'
+    implementation 'io.github.webview-native-ui:engine:<engine-version>'
 }
 ```
 
@@ -166,7 +188,7 @@ class ExamplePlugin : CordovaPlugin() {
 }
 ```
 
-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.
+Use `projection?.receive(eventName, data)` at the existing notification point, as on iOS. See the shared [notification contract](../configuration/events.md) for update and destination semantics. 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.
 
@@ -176,7 +198,7 @@ The defaults support Cordova's `https://localhost` and `http://localhost`. If th
 
 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 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](../reference/projection.md#dom-and-native-surface-requirements) for selector, layout and capture rules. [Ionic overlay support](../configuration/ionic-overlays.md) 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.
 
@@ -189,14 +211,9 @@ 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.
-
-### Projection DOM
+## Next: choose optional behavior
 
-The engine keeps a reusable image inside the fallback container, using its open ShadowRoot when available. No placement option is needed. If the renderer inspects child elements, exclude nodes marked `data-native-ui-projection-node`. See [DOM requirements](projection.md#dom-and-native-surface-requirements).
+Use the [configuration guide](../configuration/README.md) for notification routing,
+value reflection, capture timing and fallback policy. These shared settings are
+not additional platform setup. For a renderer that already batches controls, see
+[advanced APIs](../advanced/README.md).

package/docs/getting-started/initialization.md

@@ -0,0 +1,79 @@
+# Initialize a native view registration
+
+Start with `NativeUIProjection` when a plugin owns a native view and a corresponding
+Web container. Registration starts the runtime, binds that container and coordinates
+image handoff and restoration. You do not need the renderer APIs for this route.
+
+Use the [Capacitor](capacitor.md) or [Cordova](cordova.md) guide for
+dependency installation, plugin lifecycle hooks and notification forwarding.
+The examples below show the smallest registration within those hooks, followed by
+required inputs. After initialization, the configuration guide lists optional
+behavior; advanced APIs have their own entry point.
+
+For example, a plugin already draws a native tab bar, but an application opens a
+Web settings sheet above it. Register the bar and its fallback navigation host so
+the Engine can put the captured bar beneath that sheet and restore native input
+when it closes. The plugin keeps its existing tab selection API.
+
+## Minimal initialization
+
+Create and retain one registration after your renderer has attached its native
+view. The selector may match a DOM container added later, but native presentation
+waits until that container exists. Give it a [supported layout box](../reference/containers.md).
+
+In a Capacitor Swift plugin, inside `load()` or the existing renderer initializer:
+
+```swift
+projection = try NativeUIProjection(
+    webView: bridge?.webView,
+    plugin: jsName,
+    projectionSelector: "#native-ui-fallback",
+    view: { [weak self] in self?.nativeView }
+)
+```
+
+In a Capacitor Kotlin plugin, install the shared channel in `load()` **before the
+first WebView navigation**. The registration may be created later when its view is ready:
+
+```kotlin
+NativeUIProjection.install(bridge.webView)
+projection = NativeUIProjection(
+    window = activity.window,
+    webView = bridge.webView,
+    plugin = pluginHandle.id,
+    projectionSelector = "#native-ui-fallback",
+    view = { nativeView }
+)
+```
+
+Both snippets belong inside the integration guide's error boundary; retain the
+existing Web fallback if initialization fails. `projection` and `nativeView` are
+properties of your plugin. Dispose the registration with `destroy()` on iOS or
+`close()` on Android when that renderer is retired. All native lifecycle calls
+run on the UI thread.
+
+Cordova uses the same registration with `runtime: .cordova` / `runtime = Runtime.CORDOVA`
+and its own WebView and plugin identity. Follow the [Cordova guide](cordova.md)
+for those hooks and Android's resource handler.
+
+## Required inputs
+
+| Input                | Platforms     | What it identifies and why                                                                                                                                                                                                                                         |
+| -------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `webView`            | iOS / Android | The application's WebView, which owns the destination document and bridge. Swift accepts an optional reference so a missing WebView throws through the initialization error boundary.                                                                              |
+| `plugin`             | iOS / Android | The existing plugin identity routes notifications to this plugin rather than another Engine consumer. Capacitor: `jsName` on iOS, `pluginHandle.id` on Android. Cordova: the configured service name.                                                              |
+| `projectionSelector` | iOS / Android | A CSS selector matching exactly one existing Web container when presentation begins. It gives the image its correct layout and overlay layer; a native rectangle cannot identify that DOM layer.                                                                   |
+| `view`               | iOS / Android | A callback returning the renderer's current native view, or nil/null when absent. Return the current view within this renderer lifetime. When replacing the renderer, dispose its registration and create a new one; the plugin owns layout and normal visibility. |
+| `window`             | Android       | The window containing the WebView and native surface, needed for composited capture and interaction tracking.                                                                                                                                                      |
+
+These inputs establish ownership. They do not tell the Engine when content
+changes or when an application transition should change presentation.
+
+## Next: configure changing UI
+
+The minimal registration establishes ownership. Continue with [optional settings](../configuration/README.md)
+for event wiring, value reflection, capture and failure policy. Each setting lists
+its default and when it is needed. See [advanced APIs](../advanced/README.md) only when
+your renderer already manages batches, placement or update reconciliation.
+
+[Documentation overview](../README.md)

package/docs/maintenance.md

@@ -1,5 +1,10 @@
 # Development and releases
 
+Use this guide when changing or publishing the Engine itself. A native consumer
+may build without Node.js, so source changes must regenerate the bundled runtime.
+A release may reach npm before Maven artifacts are downloadable, so publication
+acceptance and consumer download readiness are checked separately below.
+
 ## 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:
@@ -23,7 +28,11 @@ 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.
+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.
+
+Native checks run in their platform CI jobs: `npm run lint:swift` uses node-swiftlint with the Capacitor configuration on macOS (`brew install swiftlint`); `npm run lint:android` runs Kotlin formatting checks and Android Lint with warnings treated as errors (JDK 21 and Android SDK 36). Use `npm run format:swift` and `npm run format:kotlin` to apply native formatting. Kotlin uses ktfmt because the Prettier Kotlin plugin cannot parse the existing native test fixture.
+
+These checks include native tests and Cordova fixtures. Swift API documentation uses `///`; implementation notes use `//`. Swift size/complexity heuristics do not force state-machine splits or public API changes; fixture-only force unwraps/casts are permitted, while production retains the checks. Swift is also 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.
 
@@ -39,7 +48,8 @@ For local packaging verification, run `python3 scripts/native-ui-engine-release/
 
 ## 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.
+Publish the same version for npm, SwiftPM and Maven; consumers pin matching
+versions across these distributions.
 
 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.
 
@@ -50,3 +60,5 @@ The npm organization `webview-native-ui` and Maven Central namespace `io.github.
 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.
+
+[Documentation overview](README.md)

package/docs/{projection-containers.md → reference/containers.md}

@@ -10,7 +10,7 @@ Choose the existing DOM element that occupies the native surface's intended loca
 - `projectionSelector` uses document CSS selectors (ID, class, attribute or descendant). It must match exactly one element and does not enter Shadow DOM. A missing element can be created later; zero or multiple matches keep Native hidden.
 - The retained image is inserted in the element's open ShadowRoot, or as a light-DOM child otherwise. Closed shadow content must inherit the host's visibility and expose a slot that can display the image.
 - An overlay, collapsed item or inactive page is eligible only while it has a visible layout box. Do not force hidden configuration elements to render just to use them as destinations.
-- Host/ancestor clipping, opacity, transforms and filters still affect the image. The image is noninteractive and freezes the captured appearance. See [projection behavior](projection.md#dom-and-native-surface-requirements) for lifecycle, mutation-observer exclusions and native capture limits.
+- Host/ancestor clipping, opacity, transforms and filters still affect the image. The image is noninteractive and freezes the captured appearance. See the [projection reference](projection.md#dom-and-native-surface-requirements) for native capture limits and the [renderer guide](../advanced/web-projection.md) for DOM mutation-observer exclusions.
 
 ## HTML containers
 
@@ -184,7 +184,11 @@ Select `#seat-projection`, not the HTML `select`:
 </span>
 ```
 
-The control's DOM, value and event listeners survive handoff. The plugin still owns native behavior and value synchronization; the prepared image does not accept input.
+The control's DOM, value and event listeners survive handoff; the prepared image
+does not accept input. Native behavior and application events remain with the
+plugin. Optional [value bindings](../configuration/values.md) reflect native values on the
+selected host. With the wrapper above, that host is the span, not the inner select;
+the wrapper's component adapter must forward reflected values to its control.
 
 ## Verification scope
 

package/docs/reference/platforms.md

@@ -0,0 +1,137 @@
+# Capture and platform limits
+
+Choose capture and fallback settings for the actual native surface. Start with
+the [projection contract](projection.md) and [configuration guide](../configuration/README.md);
+this reference describes platform behavior and limits, not additional setup steps.
+
+An opaque card in a feed and a translucent player control need different capture
+choices. Drawing the card alone can avoid capturing neighboring content; drawing
+the translucent control alone loses the background it blends with. Use the cases
+below to choose capture behavior, and retain a Web fallback for content that
+cannot be captured. These choices preserve available pixels, not live video or
+all effects of the platform compositor.
+
+## Android capture modes
+
+For opaque, software-renderable Android SDK views, use
+`captureMode = NativeUIProjection.CaptureMode.VIEW` together with an explicit
+`failedFallback` policy (`WEB` unless the consumer maintains native placement). This draws only the View's
+pixels with no surrounding padding, so clipping a partially visible ad cannot bake
+in a toolbar or adjacent content. Video, SurfaceView, translucent views, and content
+requiring Window composition must keep the default `COMPOSITED` mode. The consumer
+must provide a matching, clipped DOM host for the full opaque View; arbitrary native
+outline masks, transforms, and custom clipping are not reproduced.
+
+VIEW pixels are cached by native View identity, dimensions, and content revision.
+Ordinary scrolling retains the decoded Web image and updates placement without
+capture, PNG encoding, or image decode. The image covers the host border box at
+local origin (0, 0), independently of native placement acknowledgment latency.
+Opaque images remain painted beneath the live native View between scrolls.
+Before hiding that View, the engine waits for WebView visual readiness and a draw;
+VIEW creates no native entry or return image copies. Return acknowledgment waits
+across the native draw and the following animation frame. A generation check prevents
+a delayed cover callback from hiding content after restoration or suspension.
+
+The native Bitmap is recycled after PNG encoding in VIEW mode; the PNG and decoded
+Web image remain cached. Plugin update notifications advance the content revision:
+notify an update whenever content changes without replacing the View. Replacing the
+registration, WebView navigation, reset, or close retires the cache. Encoding stays
+off the UI thread; View drawing and cache ownership stay on it, with the existing
+8-million-pixel cap.
+
+COMPOSITED retains native handoff copies for translucent content. Entry copies wait
+for WebView visual readiness and a draw before retirement. If the 500 ms entry
+deadline expires, the native View is restored before the copy is removed, and a late
+paint acknowledgment is rejected.
+
+## Android library
+
+Android uses a Gradle Android library, distributed as an AAR through Maven rather than Capacitor plugin registration. The publication coordinates are `io.github.webview-native-ui:engine:<version>`. Build and verify the local Maven publication with:
+
+```sh
+android/gradlew -p android testDebugUnitTest assembleRelease connectedDebugAndroidTest publishReleasePublicationToVerificationRepository
+```
+
+`NativeUIClippedView` is a low-level helper that applies caller-supplied position and clipping without resetting unchanged dimensions. `NativeUIProjection` manages image handoff and restoration; it does not use this helper to lay out the renderer. The consuming plugin owns normal native placement and size updates. Android does not claim WKWebView-style native overflow binding. High-level registrations share a non-consuming window touch observer: down cancels in-flight capture adoption, up/cancel/focus loss permits preparation again, and teardown removes only that registration. Existing callback dispatch and return values are preserved.
+
+`NativeUISnapshots` prepares composited PixelCopy images and local PNG files, then covers/restores from that cache. Encoding runs off the UI thread; only one preparation runs per owner. Notify it of visual changes and interaction, and release tokens on teardown. All view/lifecycle calls run on the UI thread. The plugin retains revision, eligibility and fallback policy.
+
+After prepared Web pixels are shown or retired, `NativeUIWebReadiness.prepare` checks readiness for a subsequent WebView draw. Its `current` predicate must validate the owning session, source generation and image revision. The temporary native copy covers this asynchronous handoff; overlay startup itself does not wait. Neither bridge acknowledgement nor this callback proves physical display presentation.
+
+An opaque image can remain beneath an opaque native view between handoffs, but
+that policy must not be applied to translucent controls: drawing a translucent
+view over its own captured appearance would composite the content twice. Choose
+capture behavior for the actual view and background, and validate the complete
+integration. Never synthesize clicks through a projected image.
+
+### Translucent Android surfaces
+
+Capture the composited window pixels, including the background, instead of drawing the translucent view onto an empty bitmap. Keep the prepared Web image decoded but hidden. At handoff, `cover(token, window, reference, views)` installs a temporary opaque image copy before hiding those native views in the same UI turn. Reveal the Web image, confirm Web drawing readiness, then retire the entry copy. The overlay starts immediately; image encoding is never on this path.
+
+For return, install the prepared return copy with `restore`, restore the native views underneath it, hide the Web image, and retire the return copy after Web drawing readiness. This avoids compositing live translucent native pixels over their own snapshot. Validate the token and current surface generation at every asynchronous callback. The temporary copy is noninteractive and bounded; teardown releases both copies and cached resources.
+
+This preserves the captured background, not a continuously changing scene behind the image. Background changes must invalidate the cache through the same visual-change notifications as content updates. Video and unsupported capture surfaces retain the consumer's fallback policy.
+
+Consumer integration tests belong to their respective repositories. Engine CI exercises its browser, Swift and Android contracts without requiring a sibling renderer checkout.
+
+## Image color precision on iOS
+
+Prepared window snapshots use an extended Display P3 Float16 bitmap during capture
+and are encoded as 16-bit Display P3 PNGs on a background queue. The Web projection
+displays the prepared image directly, without a Canvas or WebGPU conversion. Native
+entry and return copies also use the decoded PNG, so both sides share the same
+prepared pixels after color conversion. Encoding and decoding
+stay outside the overlay handoff; consumers do not need a new setting or dependency.
+
+This reduces color loss in wide-gamut content but does not guarantee identical Liquid
+Glass appearance: native compositing and conversion to integer PNG can still change
+pixels. Higher precision also increases capture memory and image size. The existing
+fallback policy applies if preparation fails. Android retains its platform capture path.
+
+### Liquid Glass capture differences
+
+A captured Liquid Glass control can look different from the live native control
+when it is projected into the WebView. Reflective edge highlights and background
+refraction or blur are not fully preserved by the capture path. Higher color
+precision alone does not resolve this difference.
+
+![Device screenshots comparing captured and live UIKit tab bars on iPhone and iPad](../assets/ios-native-capture-comparison.png)
+
+Left: **iPhone 15 Pro Max, iOS 27.2**. Right: **iPad mini (6th generation),
+iPadOS 27.2**. Each device screenshot shows the captured **16-bit Display P3 PNG
+in WKWebView above** and the **live UIKit tab bar below**, at the same size within
+that device. The screenshots were placed side by side without rescaling or changing
+their shared color profile. These are physical-device results, not Simulator captures.
+
+The system screenshot preserves the live appearance, but the application-level
+capture does not reproduce it completely. On the tested iPhone, the difference was
+also present when the unencoded captured image was displayed in a native
+`UIImageView`, before PNG encoding or WebView display. Drawing the entire
+`UIWindow` into a full-window bitmap and then cropping it did not improve the
+result compared with the Engine's cropped bitmap.
+
+System screenshots are evidence for this comparison, not an alternative Engine
+capture backend. These screenshots were obtained through developer tooling with
+Developer Mode enabled on the devices. Application screen-capture APIs such as
+ReplayKit require user consent; manually taking a screenshot also requires user
+action. Cropping a system screenshot would preserve its captured pixels, but does
+not remove these acquisition requirements. The Engine therefore does not adopt
+this route for automatic UI handoffs: ordinary projection must not depend on
+Developer Mode, screenshot actions, or a screen-recording permission flow. See
+[Apple's ReplayKit security documentation](https://support.apple.com/guide/security/replaykit-security-seca5fc039dd/web).
+
+We have reported this limitation to Apple and requested a supported way to capture
+the complete appearance without starting a screen-recording session. See the
+[Apple Developer Forums discussion](https://developer.apple.com/forums/thread/853543).
+Apple suggested capturing an ancestor that includes the necessary background;
+the full-window comparison above tests that approach. This remains an observed
+capture limitation, not a confirmed fix or a commitment from Apple. Validate
+translucent controls on physical devices with the backgrounds your plugin supports.
+
+## Temporary storage and application permissions
+
+Prepared images stay in the app's private temporary storage. iOS uses `FileManager.default.temporaryDirectory`. On Android, construct `NativeUISnapshots` with a directory inside `context.cacheDir`; do not use shared or external storage. Neither platform needs a photo-library or storage permission prompt for this path. No Capacitor Filesystem plugin is required. See [Apple's sandbox directories](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html) and [Android's app-specific storage](https://developer.android.com/training/data-storage/app-specific).
+
+`Capacitor.convertFileSrc` maps the returned file URL to the existing WebView local server. It grants no filesystem permission and does not upload the image. If the application sets a Content Security Policy, its `img-src` must allow the local app origin used by that URL; do not enable broad `file:` access or unrelated WebView file-access settings.
+
+`release(token)` and owner teardown remove owned snapshot files. Abrupt process termination can leave temporary images until the operating system clears the cache or the app is uninstalled; immediate deletion after a crash is not guaranteed. Keep this storage private and treat it as disposable, not persistent application data.