@webview-native-ui/engine 0.0.5 → 0.0.7

package/docs/advanced/web-projection.md

@@ -0,0 +1,88 @@
+# Low-level Web projection
+
+Use the primitives below only if the surface helpers do not fit your renderer's
+existing ownership model. `createWebProjectionSurface` already manages scopes and
+batch handoffs; manually creating another manager for the same fallback would
+introduce competing ownership.
+
+For example, a renderer already owns one fallback container per native panel and
+accepts native updates through its own revision protocol. A projection scope lets
+it retain those ownership decisions while delegating image preparation and return
+coordination. Prefer the surface helpers if page or modal grouping already fits;
+a second manager on the same container would compete for its pixels.
+
+A scope binds one existing Web fallback element for its lifetime. Obtain that element from your plugin's DOM; the engine does not create a replacement host or choose a page, stacking order or z-index. A different fallback element requires a new scope. Its Document is derived from `element.ownerDocument`.
+
+```ts
+import { createWebProjectionScope, createWebProjection } from '@webview-native-ui/engine';
+
+const fallback = container.querySelector<HTMLElement>('[data-web-fallback]');
+if (!fallback) throw new Error('Web fallback is missing');
+const scope = createWebProjectionScope(fallback, 'my-plugin');
+const projection = await createWebProjection(
+  scope,
+  {
+    send: (request) => plugin.snapshot(request),
+    listen: (listener) => plugin.addListener('snapshotInteraction', listener),
+  },
+  {
+    wake: () => schedulePluginUpdate(),
+    blocked: () => overlayIsActive(),
+    revision: () => lastSentRevision,
+  },
+);
+```
+
+The container, bridge and update callbacks above belong to the consuming plugin. No `document`, `target`, `layer`, CSS selector or layer resolver is passed to the projection manager.
+
+1. After an accepted native update, call `projection.consider(revision, sources)`. Sources associate the native IDs and viewport frames with their source DOM; they need not be inside the fallback element. Images are captured and decoded in advance.
+2. Call `projection.changed()` for appearance changes, or `projection.changed(scrollElement)` to invalidate scroll geometry. Layout updates go through `consider`; use `invalidate()` for other geometry changes.
+3. Before covering Native with a Web overlay, call `projection.begin()`. It displays already prepared pixels at the fixed fallback. No new capture or decode starts here. If capture is unavailable, the plugin keeps its ordinary Web fallback.
+4. Exclude `projection.owners` from normal Native updates while the image owns those sources. `visibleOwners` keeps their return pixels while Native is being restored; `preparedOwners` identifies sources with prepared images. These arrays are read-only snapshots.
+5. Call `projection.end()`, send the normal native update, then call `projection.updated(snapshotToken, acceptedIDs, revision)`. A newer acknowledgement containing all captured IDs retires the image.
+6. Call `projection.destroy()` when disposing the surface. It releases only its own images and listener; the plugin owns final Native reset and its DOM.
+
+The engine prepares a noninteractive `img` inside the fallback container (directly inside its open ShadowRoot when present) while Native is visible. It reuses the decoded image and DOM node across handoffs, and releases them when the scope is retired or destroyed. The image is `inert`, hidden from accessibility and excluded from hit testing. The existing fallback and its children are never cloned, replaced, removed or assigned `inert`/`aria-hidden`; their listeners, values and application changes survive projection. Both `::before` and `::after` remain available to the application.
+
+Supply an existing container such as `div`, `button` or a custom element. Replaced/void elements such as `img`, `input` and `video` remain unsupported as scopes; use their existing fallback container. The renderer may move the same container between parents, but must not replace a low-level scope's element or let two managers control it simultaneously. Notify the manager through `moved()` when changing its placement during projection.
+
+The image is absolutely positioned within the fallback, which retains its layout box. Static hosts become positioned while the image is visible. Host and ancestor clipping, transforms and filters still apply. Open ShadowRoot insertion bypasses internal slot wrappers, not the host's own clipping. Closed shadow roots cannot be inspected; provide a fallback container that can render the image.
+
+Engine-owned nodes carry `data-native-ui-projection-node` for their entire pooled lifetime. Renderers that inspect fallback children must exclude these nodes from application content discovery. A renderer that uses a MutationObserver to invalidate captures must also ignore insertion/removal and attribute changes of these nodes, changes inside them, and Engine-owned `data-native-ui-snapshot-*` attributes. Continue observing authored content, dimensions and disabled-state changes; ignoring all mutations on a projection host would hide real updates. Otherwise image preparation can invalidate itself and cause repeated capture/release cycles. The engine removes only its own nodes on disposal. Child insertion can affect structural selectors within the fallback, but does not add items alongside it in flex, grid or virtual lists.
+
+### Notifications from the existing plugin
+
+The low-level manager can subscribe to the existing plugin's events through `options.events`:
+
+```ts
+events: {
+  addListener: (name, listener) => plugin.addListener(name, listener),
+  update: ['setColors', 'setTabs', 'tabSelected'],
+  projection: {
+    native: ['shown'],
+    web: ['transitionStarted'],
+    none: ['hidden'],
+  },
+}
+```
+
+These are **notifications**, not intercepted method names. The plugin emits update events after its native changes succeed. A Web projection event must arrive before movement starts; it uses the previously prepared image. A native event requests restoration, but the image remains until the normal renderer acknowledgement confirms that Native is ready. A hidden event follows the plugin's native hide operation and retires the image; it does not invoke `hide()` or change application-owned fallback DOM. Appearance updates preserve the requested destination, including `none`.
+
+For plugins with several surfaces, provide `accepts(event)` to select this scope's stable surface identity. Events shared by `update` and a destination are subscribed once and processed together. Conflicting destinations for the same event are rejected before subscription. Destroying the manager removes all its subscriptions, including registrations that resolve late after initialization fails. No public plugin methods are wrapped or replayed.
+
+The manager uses the host runtime's resource URL conversion internally (Capacitor or Cordova). Plugin authors do not supply a URL resolver.
+
+This section describes the lower-level manager for renderers that already own batch reconciliation, rather than a single native-view registration. Prefer the native registration in the plugin guides for a new integration; it owns startup, measurements and draw acknowledgements.
+
+### Multiple fallbacks in one Native transaction
+
+For example, a toolbar contains two button groups with separate fallback hosts,
+but the renderer hides and restores them in one native transaction. Independent
+managers could expose one group before the other. A batch uses one handoff token
+for the groups so they can cross the rendering boundary together.
+
+Use `createWebProjectionBatch(transport, options)` when several fallback elements must switch together. It uses the same image engine, one listener and one capture/cover/restore token. Pass `{ scope, element, control, ... }` for each entry to `batch.consider(revision, sources)`. Several native IDs may share one scope, such as a button group.
+
+The batch derives its Document from the first nonempty `consider`; all subsequent scopes and sources must belong to that Document. Before this first update, `begin()` does nothing and `destroy()` is safe. A changed fallback requires a new scope. Scope identity participates in cache invalidation; an active presentation retains its captured scopes until restoration finishes.
+
+`WebProjectionRequest` is an action-discriminated union. `prepare` requires `revision`, `viewportWidth` and `ids`; `cover` requires `token` and includes `viewportWidth` and destination `parts` for transient movement; `restore` requires `token`, `viewportWidth` and destination `parts`; `painted`, `restored` and `release` require `token`; `reset` takes no payload. Empty preparation results and `{ shown: false }` mean the plugin should use its normal Web fallback. Use the plugin's existing ordered bridge; the engine does not retry user actions.

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