@webview-native-ui/engine 0.0.6 → 0.0.8

package/dist/projection/surfaces.js

@@ -0,0 +1,116 @@
+/** Owns asynchronous projection creation and disposal for DOM-backed surfaces. */
+export const createWebProjectionSurfaces = (options = {}) => {
+    const entries = new Map();
+    let stopped = false;
+    const values = () => [...entries.values()].flatMap((entry) => (entry.surface ? [entry.surface] : []));
+    let doc;
+    let listeners;
+    let motionFrame = 0;
+    const invalidate = () => values().forEach((surface) => surface.invalidate());
+    const changed = (owner) => values().forEach((surface) => surface.changed(owner));
+    const observe = (owner) => {
+        const ownerDocument = owner.nodeType === 9 ? owner : owner.ownerDocument;
+        if (doc && doc !== ownerDocument)
+            throw new TypeError('Projection surfaces must share one Document');
+        if (doc)
+            return;
+        doc = ownerDocument;
+        const win = doc.defaultView;
+        listeners = new win.AbortController();
+        const subscription = { signal: listeners.signal };
+        win.addEventListener('resize', invalidate, subscription);
+        win.addEventListener('orientationchange', invalidate, subscription);
+        doc.addEventListener('visibilitychange', () => {
+            if (doc.hidden)
+                invalidate();
+        }, subscription);
+        const appearance = (event) => {
+            const target = event.target instanceof win.Element ? event.target : undefined;
+            if (target?.closest('style[data-native-ui-snapshot], [data-native-ui-projection-node]') || (target && options.ignoreTarget?.(target)))
+                return;
+            if (target?.hasAttribute('data-native-ui-snapshot') && event.pseudoElement)
+                return;
+            changed();
+        };
+        for (const name of ['load', 'transitionrun', 'transitionend', 'transitioncancel', 'animationstart', 'animationend', 'animationcancel'])
+            doc.addEventListener(name, appearance, { ...subscription, capture: name === 'load' });
+    };
+    const followMotion = (moving, target = (source) => source) => {
+        if (motionFrame || stopped || !moving.size || !doc?.defaultView)
+            return;
+        // Ancestor transforms already carry the image. Only the host's own motion needs rebasing.
+        const surfaces = values().filter((surface) => (surface.token || surface.restoring) && surface.owners.some((owner) => moving.has(target(owner))));
+        if (!surfaces.length)
+            return;
+        motionFrame = doc.defaultView.requestAnimationFrame(() => {
+            motionFrame = 0;
+            surfaces.forEach((surface) => surface.moved());
+            followMotion(moving, target);
+        });
+    };
+    const remove = async (owner) => {
+        const entry = entries.get(owner);
+        if (!entry)
+            return;
+        entries.delete(owner);
+        if (entry.surface)
+            await entry.surface.destroy();
+        // A failed creation has nothing to dispose; ensure() reports that error.
+        else
+            await entry.ready.catch(() => { });
+    };
+    return {
+        get: (owner) => entries.get(owner)?.surface,
+        keys: () => entries.keys(),
+        values,
+        changed,
+        invalidate,
+        followMotion,
+        end: () => values().forEach((surface) => surface.end()),
+        consider: (...args) => values().forEach((surface) => surface.consider(...args)),
+        updated: (...args) => values().forEach((surface) => surface.updated(...args)),
+        get restoring() {
+            return values().some((surface) => surface.restoring);
+        },
+        get handoffPending() {
+            return values().some((surface) => surface.handoffPending);
+        },
+        ensure(owner, create) {
+            if (stopped || !owner.isConnected)
+                return Promise.resolve(undefined);
+            observe(owner);
+            const existing = entries.get(owner);
+            if (existing)
+                return existing.ready;
+            const entry = {
+                ready: Promise.resolve()
+                    .then(create)
+                    .then(async (surface) => {
+                    if (stopped || entries.get(owner) !== entry || !owner.isConnected) {
+                        if (entries.get(owner) === entry)
+                            entries.delete(owner);
+                        await surface.destroy();
+                        return undefined;
+                    }
+                    entry.surface = surface;
+                    return surface;
+                })
+                    .catch((error) => {
+                    if (entries.get(owner) === entry)
+                        entries.delete(owner);
+                    throw error;
+                }),
+            };
+            entries.set(owner, entry);
+            return entry.ready;
+        },
+        delete: remove,
+        async destroy() {
+            stopped = true;
+            listeners?.abort();
+            if (motionFrame)
+                doc?.defaultView?.cancelAnimationFrame(motionFrame);
+            await Promise.all([...entries.keys()].map(remove));
+        },
+    };
+};

package/docs/README.md

@@ -0,0 +1,70 @@
+# Documentation
+
+Start with the smallest integration that meets your component's needs. Basic
+registration is enough for a single native view; optional settings adapt it to
+changing content and application lifecycle. Advanced APIs are a separate route for
+renderers that already own batching or placement.
+
+## Choose by the problem you need to solve
+
+| Case                                                                                     | Start here                                                                                    | Why                                                                                       |
+| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| A Web modal must cover a plugin's native tab bar                                         | [Basic registration](getting-started/initialization.md), then the framework integration guide | Register the view and its DOM host once; the Engine owns capture and restoration.         |
+| A hidden fallback returns with the old toggle selection                                  | [Value bindings](configuration/values.md)                                                     | Reflect current native data on the fallback host, independently of where it is displayed. |
+| Background toolbar buttons and foreground modal buttons need different handoff lifetimes | [Renderer surfaces](advanced/renderer.md)                                                     | Separate owners so closing one surface cannot restore another's controls.                 |
+| An existing renderer overlaps updates or loses a native acknowledgement                  | [Update queue](advanced/update-queue.md)                                                      | Serialize fresh-state passes and reconcile the connection without replaying user actions. |
+
+The full reading order follows. Skip advanced APIs unless your renderer owns the
+work described in their cases.
+
+## 1. Understand the approach
+
+[Concepts and limits](concepts.md) explains what projection makes possible, how it
+differs from live native UI and Web fallback, and which responsibilities stay with
+the plugin.
+
+## 2. Initialize and integrate
+
+Read [basic initialization](getting-started/initialization.md) for the minimum call
+and required inputs. Then choose one platform-framework guide:
+
+- [Capacitor plugin](getting-started/capacitor.md): dependencies, native plugin hooks, event forwarding and teardown.
+- [Cordova plugin](getting-started/cordova.md): the same registration with Cordova startup and resource handling.
+
+Neither route requires a second application-side Engine wrapper or the advanced
+renderer APIs.
+
+## 3. Add optional behavior
+
+[Registration settings](configuration/README.md) lists defaults and the situations
+that require each option. Read only the relevant detail:
+
+- [Notifications](configuration/events.md): tell the Engine when appearance or presentation changes.
+- [Value bindings](configuration/values.md): keep the fallback host's component data aligned with native state.
+- [Capture timing](configuration/capture.md): prepare pixels after native appearance settles.
+- [Ionic overlays](configuration/ionic-overlays.md): connect Ionic coverage with one shared application initializer.
+
+## 4. Use advanced APIs when you own a renderer
+
+[Choose an advanced API](advanced/README.md) before adding one. These guides address
+different existing renderer needs; they are not a sequence of required setup steps.
+
+- [Page and modal surfaces](advanced/renderer.md)
+- [Low-level Web projection and batches](advanced/web-projection.md)
+- [Native handoff and scroll bindings](advanced/native-handoff.md)
+- [Deferred Android placement](advanced/android-placement.md)
+- [Update serialization and recovery](advanced/update-queue.md)
+
+## Reference
+
+Use these to check contracts and supported behavior while implementing either route:
+
+- [Projection contract and lifetime](reference/projection.md)
+- [HTML and Ionic container support](reference/containers.md)
+- [Observable presentation intent](reference/state.md)
+- [Capture and platform limits](reference/platforms.md)
+
+## Contributing
+
+[Development and releases](maintenance.md) covers repository structure, local
+verification, CI and publication. It is not required for consuming the Engine.

package/docs/advanced/README.md

@@ -0,0 +1,20 @@
+# Advanced APIs
+
+The basic registration already owns measurement, capture and handoff acknowledgement.
+Do not add a second projection manager for the same host. Use the following APIs
+when your renderer already owns the corresponding work and needs to coordinate it:
+
+| Need                                                                       | API / guide                                                                                                                                                                                                                                                   |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Apply deferred native placement just before an opaque Android view returns | `beforeNativeReveal`, `updatePlacement`, `isProjecting` and `bindProjectionPlacement`; see [Android placement handoff](android-placement.md#final-placement-when-returning-from-an-opaque-image-android). Both callbacks default to no custom placement work. |
+| Manage independent pages or modals containing multiple native controls     | `createWebProjectionSurface` / `createWebProjectionSurfaces`; see the [renderer guide](renderer.md).                                                                                                                                                          |
+| Coordinate several fallback containers in one native transaction           | `createWebProjectionBatch`; see [batch handoff](web-projection.md#multiple-fallbacks-in-one-native-transaction).                                                                                                                                              |
+| Fit an existing ownership model that surface helpers cannot express        | `createWebProjectionScope` / `createWebProjection`; see [low-level projection](web-projection.md).                                                                                                                                                            |
+| Serialize replaceable state updates and recover a lost acknowledgement     | `createNativeUpdateQueue`; see [update scheduling and recovery](update-queue.md).                                                                                                                                                                             |
+| Implement the native bridge for a custom renderer                          | Snapshot-manager `handle` methods; see [native handoff](native-handoff.md).                                                                                                                                                                                   |
+
+These are integration choices, not additional steps to complete a normal
+`NativeUIProjection` setup. Keep business actions, SDK interaction and application
+notifications in the consuming plugin.
+
+[Documentation overview](../README.md)

package/docs/advanced/android-placement.md

@@ -0,0 +1,48 @@
+# Deferred placement on Android
+
+Use this only when an existing renderer defers native placement while an opaque
+image owns presentation. Basic registrations do not require these callbacks.
+
+For example, an opaque native advertisement moves through a scrolling feed.
+Once its image follows the DOM, repeatedly laying out the hidden native view adds
+work without changing visible pixels. Defer that placement and apply the latest
+position before revealing native content, so it does not jump back to the old
+location. Keep ordinary placement tracking if the view cannot use an opaque image.
+
+Android VIEW consumers can read `isProjecting` on the UI thread after a successful
+cover to defer same-size native placement work. Keep only the latest accepted placement;
+continue validating sequence/generation, and process hide, resize and teardown immediately.
+Supply `beforeNativeReveal` to apply that pending placement synchronously before normal
+restoration, failure recovery, or active-image release reveals native pixels. The engine
+clears `isProjecting` before invoking the callback, so applying placement must not defer
+again. The callback may run without pending work and must be idempotent. Clear consumer
+pending work on hide/destroy and validate the loaded View identity before applying it.
+The callback does not replace content/size invalidation or JavaScript geometry tracking.
+
+### Final placement when returning from an opaque image (Android)
+
+A plugin that normally measures and posts native placement on every scroll can opt
+into a final placement handoff. Pass `updatePlacement: (JSONObject) -> Unit` to its
+Android `NativeUIProjection` registration and bind its Web host with
+`bindProjectionPlacement(element, measure, invalidate)`.
+
+- `binding.projected` becomes true only after native confirms the image handoff.
+  While true, the plugin can reuse that host's last placement in full placement
+  batches and skip measuring it. Other hosts continue their ordinary updates.
+- `measure()` returns a JSON object synchronously. The engine includes it in the
+  existing restore request (or an active-image recovery request). Native validates
+  the active image token and View identity, calls `updatePlacement`, then reveals
+  native and acknowledges its draw. No extra bridge round trip is introduced.
+- The plugin must validate its own identity, generation and per-host sequence in
+  `updatePlacement`. Throw to reject a stale or invalid placement. A final update
+  for one host must not cause updates for another host to be dropped.
+- `invalidate()` is called after a failed handoff request. Clear optimistic
+  placement/deduplication caches and schedule ordinary placement reconciliation.
+- Dispose the binding when detaching a host. Session ownership prevents an old
+  registration's delayed acknowledgement from clearing a new registration's
+  projection state. Pause, author visibility and layout changes must still use
+  the plugin's normal visibility/invalidation paths.
+
+This opt-in does not change registrations without `updatePlacement`. Android rejects
+`updatePlacement` unless `captureMode = CaptureMode.VIEW`; live video and other ineligible captures
+continue native placement tracking under `failedFallback = NATIVE`.

package/docs/advanced/native-handoff.md

@@ -0,0 +1,89 @@
+# Native handoff for custom renderers
+
+An existing renderer should forward its ordered `WebProjectionRequest` messages
+to the native snapshot manager's `handle` method. This keeps request validation,
+CSS-to-native coordinate conversion, cached image handoff and copy retirement in
+the Engine. The bridge remains the plugin's own Capacitor or Cordova method; the
+Engine does not depend on either framework's call object.
+
+For example, a renderer already sends toolbar buttons as one native update and
+knows which views belong to each button group. Forward image handoff messages to
+`handle` instead of reimplementing coordinate conversion and copy retirement for
+each group. Keep the group's capture eligibility and ordinary layout in that
+renderer: the Engine cannot infer which sibling views may safely hide together.
+
+Call view and snapshot lifecycle APIs on the main/UI thread. Supply two renderer
+callbacks: `frames(ids, revision)` returns current eligible bounds, and `views(ids)`
+returns the complete native views that can safely be hidden together. Return empty
+bounds or `nil` / `null` when that operation is unavailable. Bounds use **points
+relative to the WebView on iOS** and **physical pixels relative to the WebView on
+Android**. The Engine checks that measured IDs exactly match the request.
+
+```swift
+snapshots.handle(request, in: webView,
+    frames: { ids, revision in renderer.measure(ids, at: revision) },
+    views: { ids in renderer.viewsAllowedToHide(ids) },
+    complete: reply)
+```
+
+```kotlin
+snapshots.handle(request, activity.window, webView,
+    frames = { ids, revision -> renderer.measure(ids, revision) },
+    views = { ids -> renderer.viewsAllowedToHide(ids) },
+    complete = { result ->
+        result.fold(onSuccess = reply, onFailure = reject)
+    })
+```
+
+`renderer` and `reply` above are the plugin's existing layout code and bridge
+completion callback. On Android, forward a failed `Result` to the bridge's
+rejection callback (`reject` above); Web uses that failure to abandon the image
+and reconcile presentation. Do not acknowledge a failed drawing boundary as
+success. `frames` may run repeatedly while geometry settles; it must
+recheck the requested revision and capture eligibility. It must not mutate layout.
+If multiple controls share a native container, `views` must reject a partial set
+that would hide uncaptured controls. The Engine cannot infer that relationship.
+The renderer also keeps its existing native interaction notifications.
+
+`cover` installs prepared pixels before hiding those views. Destination parts are
+validated against the cached token and used for both cover and restore, so moving
+a prepared surface does not reuse an old position. Invalid or unavailable handoffs
+return `shown: false`. `painted` and `restored` retire only the corresponding copy;
+Android waits for Web drawing readiness. `release` and `reset` retire owned
+resources. No capture starts in the cover or restore path.
+
+The renderer still performs its ordinary native update between `restore` and the
+accepted update acknowledgement. Before that update, call `restoreControls()` on
+iOS or `restoreViews()` on Android to undo only the Engine's hiding changes. This
+is not a command to lay out or reveal arbitrary plugin content. Keep the normal
+visibility and placement policy in the renderer.
+
+### Direct snapshot primitives
+
+Use these only when your integration owns native placement during handoff. `NativeUIProjection` uses the same operations with registration-specific placement and opaque-view policies. Do not duplicate conversion or copy retirement when forwarding requests to `handle`.
+
+- Convert destination `parts` from CSS pixels using `webView.bounds.width / viewportWidth` on iOS or `webView.width / viewportWidth` on Android. Pass frames to `cover` and `restore`; absent cover parts retain captured placement. Neither operation captures new pixels.
+- `transient: true` separates a moving foreground surface from the background's `coveringToken`. Reuse pixels while source sizes and positions relative to their scope remain unchanged; movement within a fixed scope invalidates the layout.
+- Retire the entry copy after Web drawing readiness: `retireCopy(token)` on iOS, `retireCopyAfterWebDraw` on Android.
+- For return, call `restore`, undo Engine hiding with `restoreControls()` / `restoreViews()`, and apply normal native layout. Retire the return copy after the accepted native update and Web drawing readiness, using `retireCopy` with `entry: false` / `entry = false`. Android can forward `painted` and `restored` to `handle` to reuse readiness and rejection handling.
+- Release tokens with `release(token)`. Use `reset()` only for owner teardown, and Android `close()` to dispose the encoder. Never reset another surface's captures.
+
+Missing captures or placement use the renderer's ordinary fallback. See the [Web request contract](web-projection.md#multiple-fallbacks-in-one-native-transaction) for payloads.
+
+Use `NativeUICoveredSnapshots.observe` to notify the JS listener when interaction starts/ends. On iOS, captures rasterize the visible window with `drawHierarchy(in:afterScreenUpdates:)`, including the background under the clipped native component. Screen snapshot views are display replicas and are not used as bitmap sources. UIKit rasterization can differ from the live compositor for materials such as Liquid Glass; validate the appearance on physical devices with the backgrounds your plugin supports. Cache validity therefore includes layout and the plugin's visual-change notifications. The engine does not capture continuously or guarantee every possible renderer can be captured.
+
+## Native scroll tracking
+
+A native control inside a Web scrolling list would otherwise need new placement
+messages as the list moves. Use these bindings only when the renderer already
+owns scroll reconciliation: a uniquely matched iOS overflow scroll view can
+carry native content with it. Nested or ambiguous scrolling must use the ordinary
+fallback instead of attaching content to the wrong scroll owner.
+
+`readScrollPlacement(element, owner, identify)` measures one untransformed overflow owner. `createScrollBindings()` validates reuse and detects movement while acquisition is awaiting ACK. Keep `reuse` out of layout-deduplication signatures; it describes acknowledgement state, not layout.
+
+On iOS, `NativeUIScrollBindings.replace` groups sources by owner and binds only an unambiguous matching `UIScrollView`. `update()` applies positions and clipping without rebuilding content. `NativeUIClippedView` preserves full content dimensions while restricting visible pixels and hit testing.
+
+An established binding rejected by native loses ownership and may be freshly acquired through the **same** update/ACK path. A failed fresh acquisition stays on the fallback until a relevant layout/scroll-end event. Never add an immediate retry loop or replay user actions. A frame/props change does not recalibrate an established coordinate origin.
+
+This uses WKWebView's internal overflow hierarchy without private class names. Missing/ambiguous views, nested scrolling, document scrolling, unsupported transforms, shaped clipping, or a moving unconfirmed owner cannot be bound. Do not claim support solely because a `UIScrollView` exists. A native view may intercept gestures that begin inside it; routing those gestures and SDK accessibility behavior remain renderer-specific.

package/docs/advanced/renderer.md

@@ -0,0 +1,148 @@
+# Advanced: coordinate pages and modals in an existing renderer
+
+Here, a **renderer** means the part of your plugin that creates native views and
+updates their layout and appearance. Use this guide when it manages multiple native
+controls, batches their updates, and knows which page or modal owns them. The
+Engine takes over image preparation, scope reuse and handoff cleanup so those
+concerns do not need separate implementations for every overlay.
+
+For a single native view, start with [Capacitor](../getting-started/capacitor.md) or
+[Cordova](../getting-started/cordova.md) registration instead. For the shared model and limits,
+read [concepts](../concepts.md). The APIs below are for an existing renderer, not
+additional steps required by those plugin guides. See [native initialization](../getting-started/initialization.md)
+for the basic API and its optional settings before choosing this route.
+
+## Group controls by the lifecycle they share
+
+A **surface** groups controls that must hand off together, such as the buttons on
+a page or modal. It is not necessarily one native view or image.
+`createWebProjectionSurface` manages their prepared images and fallback scopes;
+`createWebProjectionSurfaces` manages the lifetime of multiple such surfaces.
+
+Separate groups matter because covering a background page does not necessarily
+cover the foreground modal's controls. Sharing one lifecycle would make those
+independent presentation decisions interfere with each other.
+
+For example, a plugin rendering toolbar buttons and a tab bar can use separate
+surfaces for a background page and each modal:
+
+| Surface         | Native content              | When a Web image is useful                                                 |
+| --------------- | --------------------------- | -------------------------------------------------------------------------- |
+| Background page | Toolbar buttons and tab bar | A Web modal or popover must cover the page's controls.                     |
+| Modal           | Close and confirm buttons   | The modal moves during a drag, or another Web overlay covers its controls. |
+
+When a modal opens, the background surface can switch to its prepared images while
+the modal's own controls remain Native when appropriate. Closing the modal requests
+restoration of the background controls at their current positions; their images are
+removed after the accepted Native update. Separate surfaces prevent a departing
+modal's images or late replies from taking ownership of the newly exposed page.
+
+## Connect the existing renderer
+
+Connect each phase to the corresponding event in your renderer. These snippets
+show separate lifecycle points, not calls to execute together during initialization.
+The renderer supplies `transport`, source IDs and frames, accepted revisions and
+its existing update scheduler. In this example, `ownerOf(element)` is the
+renderer's existing lookup of the page or modal that owns a control.
+
+### Create a surface when its owner becomes available
+
+Map native control sources to existing fallback containers. The collection reuses
+the surface for repeated updates to the same owner. The owner passed to `ensure`
+is a lifecycle key, not a source filter: `surfaces.consider` broadcasts the batch
+to every surface. Each surface uses `eligible` to select only its own controls;
+two surfaces must not manage the same fallback container:
+
+```ts
+import { createWebProjectionSurface, createWebProjectionSurfaces, type WebProjectionSurface } from '@webview-native-ui/engine';
+
+const surfaces = createWebProjectionSurfaces<HTMLElement, WebProjectionSurface>();
+const projection = await surfaces.ensure(page, () =>
+  createWebProjectionSurface(transport, {
+    namespace: 'my-renderer',
+    target: (source) => source.element,
+    eligible: (source) => ownerOf(source.element) === page,
+    wake: scheduleUpdate,
+    blocked: () => transitionIsActive,
+  }),
+);
+```
+
+### Prepare during normal updates, hand off at presentation boundaries
+
+An accepted native update provides the appearance to prepare. Beginning a handoff
+uses that prepared image; ending one requests restoration rather than immediately
+removing it. While a surface owns the image, exclude its `owners` from ordinary
+native rendering so live controls do not appear above the covering Web layer.
+Use `visibleOwners` for return-image ownership while restoring. Retire the image
+only after the normal native update is acknowledged.
+
+```ts
+// After accepting an ordinary native update:
+surfaces.consider(acceptedRevision, sources);
+
+// When the framework reports coverage or motion for this owner:
+projection?.begin();
+
+// When that coverage or motion ends:
+projection?.end();
+// Send the renderer's normal native update, then on its acknowledgement:
+surfaces.updated(token, restoredIDs, acceptedRevision);
+```
+
+### Retire a page or the renderer
+
+Deleting an owner prevents late creation or restoration from reviving its controls.
+Destroy the collection when the renderer itself is disposed.
+
+```ts
+await surfaces.delete(page); // Page retirement.
+// At renderer teardown:
+await surfaces.destroy();
+```
+
+## Placement and shared monitoring
+
+The renderer supplies Native IDs and frames, source ownership, placement policy and
+accepted update acknowledgements. Framework lifecycle events remain outside the
+Engine; it does not infer modal semantics from arbitrary DOM mutations.
+
+For renderer-owned fallback proxies, `canRelocate(target)` explicitly permits
+`begin(layer)` to place those hosts in a supplied overlay layer. The Engine restores
+their parent and sibling order after restoration, failure or disposal. Application
+DOM is not relocated by default, and an application reparenting a proxy takes
+precedence over restoring its old location.
+
+A collection shares appearance, resize, orientation and document visibility
+listeners across its surfaces, and ignores Engine-owned image events. Renderers can
+exclude their own proxy events with `ignoreTarget`. `followMotion(moving, target)`
+uses the renderer's existing moving-element map to rebase images only while their
+own hosts animate; ancestor transforms already move the images without polling.
+All listeners and scheduled frames are removed at disposal.
+
+Repeated `ensure` calls share pending creation or the existing projection. Deletion,
+DOM disconnection or renderer disposal prevents a late result from becoming active;
+the Engine destroys it instead. A failed creation may be retried. The renderer
+signals page retirement through its existing lifecycle and can inspect `keys()`
+and `values()` during its normal update pass. The collection does not install a
+second DOM mutation observer or a continuous polling loop.
+
+## Verify the handoff in the consuming renderer
+
+Exercise an opening overlay, dismissal, a moving modal and owner removal during
+restoration. The background and foreground must retain their own controls; a late
+acknowledgement must not restore a departed owner. Change position without changing
+appearance to check image reuse, then change content or dimensions to check
+invalidation. Also exercise missing images: the ordinary fallback must remain
+available without delaying overlay startup.
+
+The Engine coordinates ownership, but only the consuming application can verify
+its layer choices and native placement. Implement the native side using the
+[native handoff contract](native-handoff.md), using `NativeUICoveredSnapshots.handle` on iOS and `NativeUISnapshots.handle` on
+Android. Supply eligible native bounds and complete views allowed to hide; Engine
+validates requests and converts destination coordinates. Your renderer still
+applies normal native layout and reports accepted update acknowledgements.
+
+For different ownership needs, see [low-level Web projection](web-projection.md).
+Update scheduling is independent: use the optional [update queue](update-queue.md)
+only when it fits the renderer's reconciliation policy.

package/docs/advanced/update-queue.md

@@ -0,0 +1,58 @@
+# Serialize state updates and recover a lost acknowledgement
+
+Use `createNativeUpdateQueue` when a renderer reads DOM state asynchronously and
+sends native updates. Event bursts should produce one current-state read, and a
+second read must not overlap the previous pass. This helper is optional: it does
+not change native registrations or other projection APIs. Keep an existing scheduler
+if the renderer needs a different cadence or recovery policy. The queue batches requests on
+`requestAnimationFrame`; requests arriving during a pass trigger one later pass.
+
+For example, a resize, a selection update and a DOM mutation arrive in one frame
+while the previous native update is still awaiting acknowledgement. Queue one
+fresh-state pass instead of starting overlapping reads. If the bridge loses an
+acknowledgement, reconcile current state before restoring updates; never use this
+queue to retry a purchase, click or advertisement load.
+
+```ts
+import { createNativeUpdateQueue } from '@webview-native-ui/engine';
+
+const updates = createNativeUpdateQueue(window, {
+  async update(send) {
+    const state = await renderer.readCurrentState();
+    const reply = await send(
+      () => renderer.sendState(state),
+      (reply) => {
+        if (reply.revision !== state.revision) throw new Error('Revision mismatch');
+      },
+    );
+    if (reply) renderer.accept(state, reply);
+  },
+  retry: () => renderer.invalidateLastAcceptedState(),
+  failed: (error) => renderer.stopAndRestoreFallback(error),
+  reconnect: true,
+});
+
+// From existing layout/content notifications:
+updates.request();
+// After the existing connection check has reconciled native session/revision:
+updates.reconnected();
+// At renderer teardown:
+updates.destroy();
+```
+
+`renderer` represents the integration's existing code. `send` is only for
+replaceable state, called sequentially inside an update pass, never clicks,
+selection actions, purchases or SDK requests. A failed send skips the remaining sends in that pass and requests one fresh
+pass, not a replay of its payload. If that also fails, `reconnect: true` waits for
+an external handshake; without it the queue reports terminal failure. An invalid
+acknowledgement waits for reconciliation immediately. After reconciliation, another
+failed retry or invalid acknowledgement is terminal; a fully successful update pass resets the
+recovery budget. The queue does not install a connection poller or subscriptions.
+
+Keep operation timeouts in the transport. A timeout does not cancel an underlying
+native call: the native renderer must reject stale revisions, and the connection
+check must reconcile current state before declaring recovery. Disposal suppresses
+late send results and future passes; it cannot undo a native operation already sent.
+Use `dirty` to reject obsolete DOM measurements, `running` to defer connection
+reconciliation during a pass, and `waiting` to detect a pending recovery. The
+renderer still owns revision assignment, accepted geometry and fallback policy.

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.