@webview-native-ui/engine 0.0.6 → 0.0.8

package/docs/concepts.md

@@ -0,0 +1,97 @@
+# Native UI in Web-driven screens
+
+Use the Engine when a native view must coexist with Web scrolling, transitions or
+overlays. A native tab bar, for example, can remain interactive during normal use,
+yet visually sit beneath a Web modal when that modal opens. The application keeps
+its Web navigation and layout instead of recreating the entire screen natively.
+
+## Why a bridge call is not enough
+
+A native view above a WebView is outside the DOM stacking tree. Increasing a Web
+modal's `z-index` cannot cover it. Hiding the native view reveals whatever the Web
+page draws underneath, which may look different; showing it again before layout
+has settled can expose the wrong position.
+
+The Engine handles the visual handoff between those layers. It prepares an image
+while native content is available, presents that image in the application's DOM
+when needed, and keeps it until native restoration is acknowledged. Preparation
+is separate from presentation so opening an overlay does not wait for capture.
+
+## Three presentations, with different purposes
+
+| Presentation     | What the user sees                                    | Why it is used                                                                |
+| ---------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------- |
+| Live native view | The actual interactive control or eligible SDK view   | Normal native interaction and rendering.                                      |
+| Web projection   | A prepared, noninteractive image in a DOM container   | The native appearance can move with Web content or sit beneath a Web overlay. |
+| Web fallback     | The application's own HTML, or its chosen empty state | The integration remains usable when a suitable image cannot be prepared.      |
+
+A projection is not a second live control. It does not forward clicks, animate
+video, or reorder the actual native view beneath individual DOM elements. The
+configured destinations `native`, `web` and `none` express where content should
+belong; the Engine chooses the handoff mechanism. See the
+[projection contract](reference/projection.md#projection-contract) for exact precedence and
+restoration rules.
+
+## Why the integration supplies a DOM container
+
+The container gives the image its place in the application's layout and layer
+structure. A native rectangle alone cannot tell the Engine which modal, clipping
+ancestor or scrolling region should contain the image. The container can already
+hold a Web fallback; its content and listeners survive projection.
+
+For an ad, this might be a `native-ad` element in a scrolling feed. For a tab bar,
+it might be a fallback navigation container below the page's overlay layer.
+Choose a [supported container](reference/containers.md) with the intended layout
+box. The Engine neither creates the application layout nor supplies an ad or tab
+bar implementation.
+
+## Choose the smallest integration that fits
+
+| What you are building                                                                           | Start here                                             | Why this route                                                                                                     |
+| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| A Capacitor plugin exposing a native view, such as a tab bar or a capturable advertisement view | [Capacitor plugin guide](getting-started/capacitor.md) | Native registration owns runtime startup, measurements and handoff acknowledgements; keep the existing plugin API. |
+| A Cordova plugin with the same need                                                             | [Cordova plugin guide](getting-started/cordova.md)     | The same lifecycle uses Cordova's native hooks and resource handler.                                               |
+| A renderer already batching many controls across pages and modals                               | [Renderer guide](advanced/renderer.md)                 | Group controls by lifecycle while retaining the renderer's existing placement and update protocol.                 |
+| An Ionic application using an Engine-enabled plugin                                             | [Ionic overlay guide](configuration/ionic-overlays.md) | One shared monitor connects Ionic overlay lifecycle to projection coverage.                                        |
+
+See [native initialization](getting-started/initialization.md) for the minimal registration
+and a guide to optional settings versus advanced APIs.
+
+A Web modal alone does not require the renderer APIs. Start with native
+`NativeUIProjection` registration unless you already own multi-control
+reconciliation. Applications normally gain Engine support through an integrating
+plugin rather than creating registrations themselves. Other Web frameworks can
+use their own transition notifications; Ionic is optional.
+
+## Where responsibilities meet
+
+| Engine                                                              | Consuming plugin                                                     |
+| ------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| DOM measurement, image geometry and supported native scroll binding | Creating, attaching, positioning and sizing native views             |
+| Startup, event subscriptions and native draw acknowledgements       | Providing the fallback DOM at the correct layer                      |
+| Prepared image cache, decoding, display and retirement              | Reporting appearance changes and the intended projection destination |
+| Native capture and temporary return images                          | Providing native views and SDK capture eligibility                   |
+| Image invalidation, token cleanup and observer teardown             | Owning business actions and the interactive Web fallback             |
+
+A DOM container does not necessarily contain an interactive Web replacement: a button plugin may provide an HTML button as its fallback, while an advertising plugin may leave the container empty when native content is unavailable. Image handoff is explicit and noninteractive. The engine never forwards clicks through an image or replaces SDK click/impression handling.
+
+Native registrations can also [reflect current component values](configuration/values.md)
+into their fallback host. This is independent of [presentation intent](reference/state.md):
+a selected tab is component data, while `native`, `web` and `none` describe where
+it belongs. Application events and framework form integration remain with the
+component adapter.
+
+## Decide whether the limits fit your UI
+
+Images freeze both the control and any captured background. Content that must stay
+live or interactive while covered needs a different presentation policy. SDK
+capture restrictions still apply, and some platform compositor effects, including
+Liquid Glass highlights, can differ from their captured appearance. The Engine
+does not promise pixel-identical capture of every native view.
+
+Validate your actual backgrounds, overlay transitions and restoration on supported
+devices. If capture is unavailable, decide what the user should see in the Web
+fallback before integrating. Read the [capture and platform reference](reference/projection.md)
+for eligibility, timing, storage and failure policies.
+
+[Documentation overview](README.md)

package/docs/configuration/README.md

@@ -0,0 +1,29 @@
+# Configure a native registration
+
+Start with [basic initialization](../getting-started/initialization.md). The settings below belong
+to that same registration; add only those required by your component.
+
+## Optional behavior
+
+Optional means there is a default, not that a changing UI can omit its notifications.
+For example, a tab selection changes appearance even if the tab bar stays at the
+same position: include that successful selection notification in `receiveListeners.update`.
+
+| Input                   | When omitted                                                                                                                                | Case and reason to configure it                                                                                                                                                                                                                                                                             |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `receiveListeners`      | No plugin events are subscribed. Initial intent comes from native view visibility; internal DOM and scroll handling still run.              | A tab selection changes the highlighted item: connect `update` to refresh pixels and bound values, `projection` for presentation changes, and `match` for per-surface routing. See [event wiring](events.md#choose-successful-update-and-presentation-events) and the Cordova guide's `receive` forwarding. |
+| `readValues`            | No native-to-DOM value reads.                                                                                                               | A native toggle changes while its fallback is hidden: read its current state so the fallback does not return with the old value. See [value bindings](values.md).                                                                                                                                           |
+| `values`                | With `readValues`, all returned keys become `data-native-ui-value-*` attributes. Without `readValues`, no reflection occurs.                | A custom element renders from `checked` instead of attributes: map that key to its host property. This does not synthesize application events.                                                                                                                                                              |
+| `captureDelayMs`        | Prepare images after a 50 ms debounce.                                                                                                      | A tab highlight is still animating when its selection event arrives: wait for settled pixels. See [capture timing](capture.md); this does not delay overlay opening.                                                                                                                                        |
+| `canCapture`            | Returns true; Engine geometry and platform checks still apply.                                                                              | An SDK switches from capturable static content to restricted video: prevent an ineligible capture. Return eligibility for the current content.                                                                                                                                                              |
+| `failedFallback`        | Use the ordinary Web fallback when no suitable image is available.                                                                          | An SDK view has no usable Web replacement: keep it native during automatic motion only if the renderer maintains its placement. Explicit Web coverage and `none` still take precedence. See [failure policy](../reference/projection.md#native-surface-requirements).                                       |
+| `allowedOrigins`        | iOS: `capacitor://localhost`, `app://localhost`, `https://localhost`, `http://localhost`. Android: `https://localhost`, `http://localhost`. | An app changes its local hostname: match that exact trusted origin so its channel can connect. On Android use the same origins for `install` and every registration.                                                                                                                                        |
+| `runtime`               | Capacitor.                                                                                                                                  | **Required for Cordova integrations**: select Cordova so notifications and resource URLs use its transport.                                                                                                                                                                                                 |
+| `captureMode` (Android) | `COMPOSITED`, including the visible background.                                                                                             | An opaque card scrolls past adjacent content: `VIEW` captures the card alone instead of surrounding window pixels. Do not use it for translucent content, video or SurfaceView. See [capture eligibility](../reference/platforms.md#android-capture-modes).                                                 |
+
+The Engine exposes [presentation intent](../reference/state.md) separately from
+component values. Neither requires an application-side Engine wrapper. Ionic
+overlay detection is a separate, opt-in [shared initializer](ionic-overlays.md),
+not a registration argument; other frameworks report their lifecycle explicitly.
+
+[Documentation overview](../README.md)

package/docs/configuration/capture.md

@@ -0,0 +1,27 @@
+# Configure capture timing
+
+Use this when a successful state change is reported before its visual animation
+ends. For example, a tab-selection event can arrive while the highlight is still
+enlarged; capturing immediately would preserve that intermediate shape beneath
+the next Web overlay. Delay background preparation until the control settles.
+Keep the default when the measured appearance is already settled; a longer delay
+also keeps the previous image available for longer.
+
+`captureDelayMs` is an optional registration setting shared by Capacitor and Cordova.
+It defaults to **50 milliseconds** on iOS, Android and the lower-level `createWebProjection`
+options. Values must be finite and nonnegative. It uses the existing debounce: a new
+update or interaction restarts preparation after activity settles. It does not add a
+second timer or delay the overlay's presentation.
+
+Until replacement pixels are ready, the last completed image remains available. If
+there is no completed image, normal Web fallback applies. Opening an overlay during
+the debounce does not wait for a new capture. Consequently, increasing the delay also
+increases the period in which the previous appearance may be used after an update.
+
+A starting recommendation for **UITabBar Liquid Glass selection animations is 600 ms**.
+In iOS 27.0 iPhone and iOS 27.1 Duo simulator comparisons, 50 ms captured an enlarged
+selection, 300 ms still retained a small residual change, and 600 ms matched the settled
+appearance observed at 1000 ms. This is a recommendation for that interaction, not an
+Apple timing contract or a universal Liquid Glass duration. Measure your control's
+selection, reselection and successive updates before choosing a value. Continuously
+changing content has no guaranteed settled snapshot.

package/docs/configuration/events.md

@@ -0,0 +1,35 @@
+# Connect plugin notifications
+
+Use `receiveListeners` when native content or presentation changes after initialization.
+These are successful-change notifications, not method interception. The
+[Capacitor](../getting-started/capacitor.md) and [Cordova](../getting-started/cordova.md) guides show where
+to forward them; this page defines the shared event contract.
+
+For example, selecting another native tab changes the highlighted item but not
+the bar's position. Without an update notification, opening a Web sheet can reuse
+an image of the old selection. Emit the plugin's successful selection event and
+include it in `update`. A hide operation is different: route its event to `none`
+so a later appearance update cannot make the hidden bar reappear.
+
+## Startup and routing
+
+Forwarding notifications from the plugin lets the Engine retain the latest matching projection destination before the Web runtime subscribes. No separate state variable or initial-state callback is needed. Keep the plugin's application event delivery unchanged: 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.
+
+## Choose successful update and presentation events
+
+All incoming event declarations belong to `receiveListeners`. Its `update` list refreshes the image and any configured value bindings, 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 and configured values 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.

package/docs/configuration/ionic-overlays.md

@@ -0,0 +1,65 @@
+# Cover native UI with Ionic overlays
+
+Use this adapter when an Ionic modal or another covering Web overlay should appear
+above Engine-managed native content. Native registration handles capture and
+restoration, but it cannot infer Ionic's presentation lifecycle from a native
+view. This shared monitor supplies that coverage decision for all registrations.
+
+Integrate the plugin through the [Capacitor](../getting-started/capacitor.md) or
+[Cordova](../getting-started/cordova.md) guide first. Non-Ionic applications use their own
+lifecycle notifications and do not install this adapter.
+
+For example, opening an Ionic settings modal should cover the background native
+tab bar while leaving the modal's own native close button usable. A blanket hide
+notification cannot express that relationship. The shared monitor evaluates each
+host against the overlay stack, so independent plugins use the same coverage rule.
+
+## Enable once
+
+For an Ionic application, call this once during application startup. When calling it directly from the application, install `@webview-native-ui/engine` as a direct application dependency:
+
+```ts
+import { enableSupportIonicOverlays } from '@webview-native-ui/engine/ionic';
+
+enableSupportIonicOverlays();
+```
+
+Plugin maintainers can include this snippet in their application setup instructions, or call it inside an existing JS initializer. `@rdlabo/capacitor-native-ui` already calls the same initializer internally; its users need no additional call. Non-Ionic applications omit it. Native registration alone does not install Ionic event listeners.
+
+## Coverage and lifetime
+
+One monitor is shared per document, including between the npm module and the runtime injected by Swift/Android. Repeated initialization does not add listeners or erase explicit configuration. Destroying one projection removes only its subscription; it does not stop the monitor used by other plugins. The monitor lives with the document.
+
+The default covers Modal, Popover, Alert, Action Sheet, Loading, Picker, Toast and Menu lifecycle events. It compares each projection's DOM with the active overlay stack: content inside the front modal stays native, while covered content temporarily uses its prepared image. Toasts and inactive sheet backdrops do not cover a surface. Nested overlays keep it covered until the remaining stack permits restoration. Missing images retain the normal Web fallback. This temporary coverage never overwrites a plugin's explicit `web` or `none` destination. Projections registered later read the current state.
+
+A popover displayed in a native window is different from a popover rendered in
+the WebView: its DOM placeholder must not be treated as a covering Web overlay.
+The `@rdlabo/capacitor-native-ui` plugin reports this native presentation ownership
+to the monitor. If its native presentation fails, it releases that ownership and
+the monitor resumes ordinary Web overlay coverage. This exception depends on an
+explicit integration; it is not inferred from the popover's DOM alone.
+
+## Customize unusual layouts
+
+Optional settings are document-wide. Keep the defaults for ordinary Ionic overlays.
+Use `exclude` for an application overlay that should not cover native content, and
+`additional` when the same app also uses a custom dialog with its own lifecycle
+events. Use `covers` only when DOM containment and backdrop state do not describe
+which hosts that custom layout actually covers:
+
+```ts
+enableSupportIonicOverlays({
+  exclude: '[data-nonblocking-overlay]',
+  additional: [
+    {
+      selector: 'app-dialog',
+      events: {
+        willPresent: 'appDialogWillPresent',
+        didDismiss: 'appDialogDidDismiss',
+      },
+    },
+  ],
+});
+```
+
+Use `covers(overlay, target)` only when a registered DOM projection needs a custom coverage rule; return `undefined` for the default, or a boolean to override it. Exclusions and explicit native-window ownership take precedence. The standard relationship uses overlay order, DOM containment and backdrop state, rather than attempting to interpret arbitrary CSS stacking contexts. Configure unusual layouts explicitly.

package/docs/configuration/values.md

@@ -0,0 +1,125 @@
+# Reflect component values into the DOM
+
+A native toggle, tab selection or text control can change while its Web fallback
+is hidden. Reflect its current values so that the fallback and application can
+observe the same selection when they become visible. This is separate from
+[projection state](../reference/state.md): a selected tab is component data, not a
+request to move its rendering between native and Web.
+
+For example, a user turns a native toggle on while its Web fallback is hidden.
+If capture later becomes unavailable, an unchanged fallback would show it off.
+Return the current boolean through `readValues` and map it to the supported host's
+`checked` property. Application form notifications still use the component's
+existing adapter; the Engine only keeps the displayed data aligned.
+
+Configure this connection in the plugin's existing `NativeUIProjection`
+initialization. No application-side wrapper is required. These options work with
+both Capacitor and Cordova registrations. Values are applied to the same element
+matched by `projectionSelector`, not a child control or a separate binding target.
+Choose a [supported projection container](../reference/containers.md): for example,
+an `ion-toggle` or an application custom element exposing `checked` or `value`.
+HTML `input`, `select` and `textarea` are not direct projection containers. When
+using a wrapper around one, its own attribute observer or property setter must
+forward the value to the inner control. The Engine does not discover that control.
+These bindings belong to native registrations; the lower-level renderer APIs keep
+the renderer's existing value synchronization.
+
+## Start with data attributes
+
+Supply `readValues` to enable reflection. It reads the plugin's **current** values,
+including programmatic changes; event payloads are not used as the value store.
+Every returned key defaults to `data-native-ui-value-<key>`. Omit `readValues` to
+keep the existing behavior without value requests.
+
+For example, these arguments in a Swift registration expose the selected tab as
+`data-native-ui-value-selected`:
+
+```swift
+receiveListeners: .init(update: ["updated", "tabSelected"]),
+readValues: { [weak self] in
+    ["selected": self?.selectedTabID ?? ""]
+},
+```
+
+Use lowercase keys starting with a letter, followed by letters, digits or hyphens.
+Return JSON-compatible values. Strings are written literally; numbers, booleans,
+arrays, objects and null use JSON text. Null becomes the attribute text `null`;
+an empty string produces an empty attribute. Neither removes the attribute, and
+an omitted key leaves the previous value unchanged. Use `NSNull()` in Swift or
+`JSONObject.NULL` in Kotlin to return JSON null (`JSONObject.put(key, null)`
+removes the key instead).
+
+The Engine reads values when the matching DOM appears, after page reconnection,
+and on configured `update` events. It ignores replies for a departed
+DOM or superseded request. The callback runs on the native UI thread: read stored
+state rather than performing blocking work.
+
+## Choose a DOM property when the component needs one
+
+A supported Web component host may expose `value`, `checked` or another data
+property instead of reading attributes. Override only those keys with `values`:
+
+```swift
+receiveListeners: .init(update: ["updated", "selectionChanged"]),
+values: ["selected": .init(property: "value")],
+readValues: { [weak self] in
+    ["selected": self?.selectedTabID ?? ""]
+},
+```
+
+The equivalent Kotlin registration arguments are:
+
+```kotlin
+receiveListeners = NativeUIProjection.ReceiveListeners(
+    update = listOf("updated", "selectionChanged")
+),
+values = mapOf(
+    "selected" to NativeUIProjection.ValueBinding(property = "value")
+),
+readValues = { JSONObject().put("selected", selectedTabID) },
+```
+
+Property assignment preserves JSON types: a boolean stays a boolean instead of
+becoming an attribute string. Choose a writable data property supported by the
+component. HTML, style and event-handler properties are not binding destinations.
+A property override replaces attribute reflection for that key. Other returned
+keys still use the default data attributes.
+
+When property bindings target an autonomous custom element (such as `<my-toggle>`)
+that is not defined yet, the
+Engine waits for its definition before reading and assigning values. This keeps
+an early assignment from hiding the component's eventual setter. It rechecks DOM
+ownership and pending updates after the wait. Attribute-only bindings can reflect
+values before the custom element is defined. Define customized built-ins (such as
+`<input is="my-input">`) before enabling property bindings; their custom definition
+name is not reliably available from the DOM.
+
+## Keep application events in the component adapter
+
+The Engine connects native state to the DOM. It does not implement framework
+two-way binding or dispatch `input`, `change`, `ionChange` or other component
+events. Initial reads, user selections and programmatic updates all follow the
+same reflection path. Concurrent reads use the newest response, and responses
+for a departed container are ignored.
+
+Keep application notifications on the plugin's existing event API. The adapter
+for a form control, custom element or framework decides how that native event
+updates the application model. For example, a tab plugin's `tabSelected` event
+can update the application's selected-tab state while the Engine separately
+reflects the current selection into the fallback's `value` property. Do not
+read the DOM from that event handler expecting the asynchronous Engine refresh
+to have completed; use the plugin event's documented payload instead.
+
+A custom element may react to a reflected attribute through its
+`attributeChangedCallback`, or accept a property through its setter. Use that
+hook to render the current value. Setters that emit application events retain
+their own behavior; the Engine neither suppresses those events nor invents a
+universal event shape. Reflecting a property does not by itself connect a
+framework form.
+
+The Engine does not invoke native setters, observe DOM properties to send values
+back to native, or replay actions. Retain the component's existing Web-to-native
+handler and avoid unconditional setter/event loops.
+
+On teardown, reflected values remain available to the Web fallback. The Engine
+removes its projection-state marker, but does not reset component data.

package/docs/cordova.md

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

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).