@webview-native-ui/engine 0.0.6 → 0.0.8

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:
@@ -8,7 +13,7 @@ The public entry points are `src/index.ts` and `src/ionic.ts`, with shared contr
 - `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.
+`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 ignored during development and included in release tags so SwiftPM consumers do not need Node.js. Run `npm run build` before building a source checkout with Xcode. 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.
 
@@ -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.
 
@@ -31,7 +40,7 @@ CI-only setup, packaging commands and GitHub outputs are defined in `.github/wor
 
 ## 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.
+The `Native UI Engine Maven Release` workflow is manually dispatched on the release tag with the exact engine package version. The tagged 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.
 
@@ -39,14 +48,35 @@ 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.
 
-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).
+1. Run **Prepare release** (`prepare-release.yml`) on `main` and select `major`, `minor`, `patch` or `revision`. No local build, commit or tag is needed.
+2. The workflow increments the version using npm, builds and verifies the package, and pushes a version-only main commit plus a separate release commit/tag containing the generated resources. It explicitly starts `Native UI Engine` validation on that tag and creates a GitHub Release draft with generated release notes.
+3. Review and edit the release notes. After tag validation passes, dispatch `native-ui-engine-release.yml` on that tag with the exact package version.
+4. Once Maven publication succeeds, publish the GitHub Release draft. Central `PUBLISHING` means upload acceptance, not download readiness; mention any pending Android distribution in the notes. `release.yml` verifies the tag, package version, tag CI and Maven acceptance before publishing to npm (`next` for revisions, `latest` for stable releases).
+
+Version increments follow npm SemVer rules; `revision` maps to `prerelease`:
+
+| Current   | Selection | Next      |
+| --------- | --------- | --------- |
+| `1.2.3`   | major     | `2.0.0`   |
+| `1.2.3`   | minor     | `1.3.0`   |
+| `1.2.3`   | patch     | `1.2.4`   |
+| `1.2.3`   | revision  | `1.2.4-0` |
+| `1.2.4-0` | revision  | `1.2.4-1` |
+| `1.2.4-2` | patch     | `1.2.4`   |
+| `1.3.0-2` | minor     | `1.3.0`   |
+| `2.0.0-2` | major     | `2.0.0`   |
+
+Generated runtime commits never enter main's history. The CI preparation pushes main and the release tag atomically, without force. Publication accepts only a tagged child of main that adds the two generated resources and changes no other files. npm rebuilds and checks the runtime before publication; Maven packages the runtime from the same tested tag.
+
+If preparation fails before pushing, rerun it. If main and the tag were already pushed, do not rerun preparation (that requests another version) or move the tag. Manually run `Native UI Engine` on the existing tag if validation was not started, and create the release draft for that tag if it is missing. This also recovers a failure between the push, validation dispatch and draft creation. Existing tags and published artifacts are never overwritten.
 
 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.
+To rerun release verification for an existing tag, select that tag as both the workflow ref and the `tag` input: `gh workflow run release.yml --ref vX.Y.Z -f tag=vX.Y.Z`. This uses the workflow saved in that release, including for older tags that predate the release-only commit layout. 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.

package/docs/reference/projection.md

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

package/docs/reference/state.md

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