@webview-native-ui/engine 1.0.0 → 1.0.2-0

package/dist/integration/index.js

@@ -0,0 +1,25 @@
+/// <reference lib="es2021.weakref" />
+const searches = new WeakMap();
+export const registerNativeSearch = (tabBar, trigger, footer) => {
+    const binding = { tabBar, trigger, footer, active: false, focused: false };
+    const entries = (searches.get(tabBar.ownerDocument) ?? []).filter((entry) => entry.deref() && entry.deref()?.footer !== footer);
+    entries.push(new WeakRef(binding));
+    searches.set(tabBar.ownerDocument, entries);
+    tabBar.ownerDocument.defaultView?.dispatchEvent(new Event('nativeUIRefresh'));
+    return binding;
+};
+export const getNativeSearchBindings = (doc) => (searches.get(doc) ?? []).flatMap((entry) => entry.deref() ?? []);
+export const requestNativeSearch = async (binding, active, focus) => (await runtimes.get(binding.tabBar.ownerDocument)?.search?.(binding, active, focus)) ?? false;
+const runtimes = new WeakMap();
+export const VERTICAL_BARS_TRANSITION_CANCELED = 'iosThemeVerticalBarsTransitionCanceled';
+export const setNativeUIIntegration = (doc, runtime) => {
+    if (runtime)
+        runtimes.set(doc, runtime);
+    else
+        runtimes.delete(doc);
+};
+export const hasNativeUIIntegration = (doc) => runtimes.has(doc);
+export const isNativeUI = (element) => element.hasAttribute('data-native-ui-projected');
+export const suspendNativeUI = async (scopes, options) => (await runtimes.get(scopes[0]?.ownerDocument)?.suspend(scopes, options)) ?? (() => { });
+/** Shared geometry used by the theme's transition adapter; no theme import in the plugin. */
+export const nativeWebViewMetrics = { radius: 0 };

package/dist/native/bootstrap.js

@@ -16,7 +16,7 @@ const send = (id, request) => new Promise((resolve, reject) => {
     pending.set(key, { resolve, reject, timer });
     const message = JSON.stringify({ key, request });
     const host = globalThis;
-    const channel = host.webkit?.messageHandlers?.[id] ?? host[id] ?? host.nativeUIEngine;
+    const channel = host.webkit?.messageHandlers?.[id] ?? host.nativeUIEngine;
     if (!channel) {
         clearTimeout(timer);
         pending.delete(key);

package/dist/native/session.js

@@ -1,6 +1,6 @@
 import { applyNativeValues } from './values.js';
 import { projectionPlacement } from '../projection/placement.js';
-import { getOverlayCoordinator } from '../dom/overlays.js';
+import { getProjectionPause } from '../projection/pause.js';
 import { readScrollPlacement } from '../dom/scroll-placement.js';
 import { projectionAncestors } from '../dom/geometry.js';
 import { createWebProjection } from '../projection/web.js';
@@ -19,8 +19,8 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
     let ready = false;
     let requestedDestination = 'native';
     let destination = 'native';
-    const overlays = getOverlayCoordinator(document);
-    const effectiveDestination = () => requestedDestination === 'native' && target && overlays.isCovered(target) ? 'web' : requestedDestination;
+    const projectionRequest = getProjectionPause(document);
+    const effectiveDestination = () => requestedDestination === 'native' && projectionRequest.isPaused(target) ? 'web' : requestedDestination;
     let automaticMotion = false;
     let nativeDragging = false;
     let placementPending = false;
@@ -575,7 +575,7 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
             applyDestination(effectiveDestination());
     });
     observer.observe(document.documentElement, { childList: true, attributes: true, subtree: true });
-    const applyDestination = (next, force = false) => {
+    const applyDestination = (next, force) => {
         if (stopped || (!force && next === destination))
             return;
         automaticMotion = false;
@@ -602,6 +602,9 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
             });
         }
         else if (destination === 'web') {
+            // A native show starts a new local request; the screen-wide Web request prevents restoration.
+            if (force === 'native' && projectionRequest.isPaused())
+                manager?.end();
             beginProjection();
             if (!manager?.token)
                 void bridge.send({ action: 'visibility', visible: false }).catch(() => { });
@@ -614,7 +617,10 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
         }
     };
     // Let a renderer claim a native child window during the same Ionic event dispatch.
-    const stopOverlays = overlays.subscribe(() => queueMicrotask(() => applyDestination(effectiveDestination())));
+    const stopPause = projectionRequest.subscribe(() => queueMicrotask(() => {
+        if (ready)
+            applyDestination(effectiveDestination());
+    }));
     let events;
     const destroy = async () => {
         if (stopped)
@@ -624,7 +630,7 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
         retireValueRead();
         clearPlacement();
         generation++;
-        stopOverlays();
+        stopPause();
         observer.disconnect();
         sizeObserver.disconnect();
         window.removeEventListener('resize', resized);
@@ -656,7 +662,7 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
                     placementPending = false;
                 requestedDestination = next;
                 void bridge.send({ action: 'destination', destination: next }).catch(() => { });
-                applyDestination(effectiveDestination(), true);
+                applyDestination(effectiveDestination(), next);
             }
             if (updated) {
                 void refreshValues();
@@ -677,7 +683,7 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
             show: () => {
                 placementPending = false;
                 requestedDestination = 'native';
-                applyDestination(effectiveDestination(), true);
+                applyDestination(effectiveDestination(), 'native');
             },
             hide: () => {
                 requestedDestination = destination = 'none';

package/dist/projection/pause.d.ts

@@ -0,0 +1,10 @@
+export declare const getProjectionPause: (doc: Document) => {
+    isPaused: (target?: HTMLElement) => boolean;
+    subscribe(listener: () => void): () => void;
+    pause: () => void;
+    resume: () => void;
+};
+/** Request temporary Web projection across this document. Pair each call with resume(). */
+export declare const pause: () => void;
+/** Release one shared pause, regardless of caller; resume exactly once per pause(). */
+export declare const resume: () => void;

package/dist/projection/pause.js

@@ -0,0 +1,58 @@
+import { getOverlayCoordinator } from '../dom/overlays.js';
+const key = Symbol.for('@webview-native-ui/engine/projection-pause/v1');
+const createPause = (doc) => {
+    const overlays = getOverlayCoordinator(doc);
+    const listeners = new Set();
+    let depth = 0;
+    let releaseFrame = 0;
+    const paused = () => depth > 0 || releaseFrame !== 0;
+    const notify = () => {
+        for (const listener of listeners)
+            listener();
+    };
+    const change = (delta) => {
+        if (delta < 0 && depth === 0)
+            return;
+        const wasPaused = paused();
+        depth += delta;
+        const win = doc.defaultView;
+        if (releaseFrame && win) {
+            win.cancelAnimationFrame(releaseFrame);
+            releaseFrame = 0;
+        }
+        if (depth === 0 && win) {
+            // Give DOM dismissal a paint opportunity before requesting Native return.
+            // Keep all consumers paused meanwhile, including Ionic change callbacks.
+            releaseFrame = win.requestAnimationFrame(() => {
+                releaseFrame = win.requestAnimationFrame(() => {
+                    releaseFrame = 0;
+                    notify();
+                });
+            });
+        }
+        else if (wasPaused !== paused())
+            notify();
+    };
+    return {
+        // Without a target, only the document-wide request applies; renderers own local coverage.
+        isPaused: (target) => paused() || (!!target && overlays.isCovered(target)),
+        subscribe(listener) {
+            listeners.add(listener);
+            const stopOverlays = overlays.subscribe(listener);
+            return () => {
+                listeners.delete(listener);
+                stopOverlays();
+            };
+        },
+        pause: () => change(1),
+        resume: () => change(-1),
+    };
+};
+export const getProjectionPause = (doc) => {
+    const shared = doc;
+    return (shared[key] ??= createPause(doc));
+};
+/** Request temporary Web projection across this document. Pair each call with resume(). */
+export const pause = () => getProjectionPause(document).pause();
+/** Release one shared pause, regardless of caller; resume exactly once per pause(). */
+export const resume = () => getProjectionPause(document).resume();

package/dist/projection/styles.d.ts

@@ -1,2 +1,2 @@
-export declare const snapshotStyles = "\n@layer native-ui-projection {\n:is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content]), :is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content]) *, :is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content])::part(native) { visibility: hidden !important; }\n:is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content])::before, :is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content])::after,\n:is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content]) *::before, :is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content]) *::after {\n  visibility: hidden !important;\n}\n}\n[data-native-ui-snapshot-visible] { opacity:1!important;overflow:visible!important; }\n[data-native-ui-snapshot-visible][data-native-ui-snapshot-positioned] { position:relative!important; }\n";
+export declare const snapshotStyles = "\n@layer native-ui-projection {\n:is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content]), :is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content]) *, :is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content])::part(native) { visibility: hidden !important; }\n:is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content])::before, :is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content])::after,\n:is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content]) *::before, :is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content]) *::after {\n  visibility: hidden !important;\n}\n}\n[data-native-ui-snapshot-visible][data-native-ui-snapshot-positioned] { position:relative!important; }\n";
 export declare const snapshotShadowStyles = "\n@layer native-ui-projection {\n:host([data-native-ui-snapshot-content]),\n:host([data-native-ui-snapshot-content])::before,\n:host([data-native-ui-snapshot-content])::after,\n:host([data-native-ui-snapshot-content]) *,\n:host([data-native-ui-snapshot-content]) *::before,\n:host([data-native-ui-snapshot-content]) *::after {\n  visibility: hidden !important;\n}\n}\n";

package/dist/projection/styles.js

@@ -8,7 +8,6 @@ ${hidden} *::before, ${hidden} *::after {
   visibility: hidden !important;
 }
 }
-[data-native-ui-snapshot-visible] { opacity:1!important;overflow:visible!important; }
 [data-native-ui-snapshot-visible][data-native-ui-snapshot-positioned] { position:relative!important; }
 `;
 export const snapshotShadowStyles = `

package/dist/projection/surfaces.js

@@ -1,6 +1,12 @@
 /** Owns asynchronous projection creation and disposal for DOM-backed surfaces. */
 export const createWebProjectionSurfaces = (options = {}) => {
     const entries = new Map();
+    const retiring = new Set();
+    const retire = (disposal) => {
+        const pending = disposal.finally(() => retiring.delete(pending));
+        retiring.add(pending);
+        return pending;
+    };
     let stopped = false;
     const values = () => [...entries.values()].flatMap((entry) => (entry.surface ? [entry.surface] : []));
     let doc;
@@ -39,7 +45,8 @@ export const createWebProjectionSurfaces = (options = {}) => {
         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))));
+        const surfaces = values().filter((surface) => (surface.token || surface.restoring) &&
+            (surface.restoring ? surface.visibleOwners : surface.owners).some((owner) => moving.has(target(owner))));
         if (!surfaces.length)
             return;
         motionFrame = doc.defaultView.requestAnimationFrame(() => {
@@ -53,11 +60,7 @@ export const createWebProjectionSurfaces = (options = {}) => {
         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(() => { });
+        await retire(entry.surface ? entry.surface.destroy() : entry.ready.catch(() => { }));
     };
     return {
         get: (owner) => entries.get(owner)?.surface,
@@ -89,7 +92,7 @@ export const createWebProjectionSurfaces = (options = {}) => {
                     if (stopped || entries.get(owner) !== entry || !owner.isConnected) {
                         if (entries.get(owner) === entry)
                             entries.delete(owner);
-                        await surface.destroy();
+                        await retire(surface.destroy());
                         return undefined;
                     }
                     entry.surface = surface;
@@ -110,7 +113,7 @@ export const createWebProjectionSurfaces = (options = {}) => {
             listeners?.abort();
             if (motionFrame)
                 doc?.defaultView?.cancelAnimationFrame(motionFrame);
-            await Promise.all([...entries.keys()].map(remove));
+            await Promise.all([...retiring, ...[...entries.keys()].map(remove)]);
         },
     };
 };

package/dist/projection/web.js

@@ -2,7 +2,8 @@ import { projectionURL } from '../native/resource-url.js';
 import { bounded, boundedListener } from '../native/bridge.js';
 import { bindProjectionEvents } from './events.js';
 import { snapshotStyles, snapshotShadowStyles } from './styles.js';
-const layout = (candidates, positionIndependent = false) => JSON.stringify(candidates.map(({ control: c }) => [
+import { getProjectionPause } from './pause.js';
+const layout = ({ control: c }, positionIndependent = false) => [
     c.id,
     c.kind,
     c.placement,
@@ -12,7 +13,7 @@ const layout = (candidates, positionIndependent = false) => JSON.stringify(candi
     c.height,
     c.dark,
     c.rtl,
-]));
+];
 /** Images are prepared after accepted native updates, never on the overlay's critical path. */
 const createProjectionEngine = async (scope, transport, callbacks) => {
     const captureDelayMs = callbacks.captureDelayMs ?? 50;
@@ -20,6 +21,8 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
         throw new RangeError('captureDelayMs must be a finite, nonnegative timer interval');
     let destination = 'native';
     const doc = scope.element.ownerDocument;
+    const projectionRequest = getProjectionPause(doc);
+    let locallyRequested = false;
     const win = doc.defaultView;
     // Native tokens are local to a transport; never use them as global CSS identities.
     const imageIdentity = Array.from(win.crypto.getRandomValues(new Uint32Array(4)), (value) => value.toString(16)).join('-');
@@ -48,7 +51,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
         const relative = origin
             ? { ...candidate, control: { ...candidate.control, x: candidate.control.x - origin.x, y: candidate.control.y - origin.y } }
             : candidate;
-        return [scopeIDs.get(candidate.scope), layout([relative], !!callbacks.opaqueUnderlay)];
+        return [scopeIDs.get(candidate.scope), layout(relative, !!callbacks.opaqueUnderlay)];
     }));
     const sheets = new Map();
     const rootFor = (element) => {
@@ -249,8 +252,9 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
             // One crop may cover a button group, but must have one fixed fallback destination.
             if (result.parts.some((part) => new Set(part.ids.map((id) => selected.find((candidate) => candidate.control.id === id).scope)).size !== 1))
                 return;
-            await bounded(Promise.all(result.parts.map(async (part) => {
-                const target = selected.find((candidate) => part.ids.includes(candidate.control.id)).scope.element;
+            const partSources = result.parts.map((part) => selected.find((candidate) => part.ids.includes(candidate.control.id)));
+            await bounded(Promise.all(result.parts.map(async (part, index) => {
+                const target = partSources[index].scope.element;
                 let pool = imagePool.get(target);
                 if (!pool) {
                     pool = [];
@@ -283,9 +287,9 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
                 data: result,
                 images,
                 sources: Array.from(new Set(selected.flatMap((item) => [item.element, ...(item.sources ?? [])]))),
-                targets: result.parts.map((part) => selected.find((candidate) => part.ids.includes(candidate.control.id)).element),
-                scopes: result.parts.map((part) => selected.find((candidate) => part.ids.includes(candidate.control.id)).scope),
-                parents: result.parts.map((part) => selected.find((candidate) => part.ids.includes(candidate.control.id)).scope.element.parentNode),
+                targets: partSources.map((source) => source.element),
+                scopes: partSources.map((source) => source.scope),
+                parents: partSources.map((source) => source.scope.element.parentNode),
                 frames: [],
                 viewport: size,
                 revision,
@@ -323,6 +327,8 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
             preparedVisualRevision = visual;
             adopted = true;
             dispose(previous);
+            if (projectionRequest.isPaused())
+                present();
         }
         catch {
             // Preparing a visual is optional. Preserve the previous image or the Web fallback.
@@ -617,11 +623,11 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
         const rect = element.getBoundingClientRect();
         return { ...image.data.parts[index], x: rect.x, y: rect.y, width: rect.width, height: rect.height };
     });
-    const begin = () => {
+    const present = (force = false) => {
         retireRestoration();
-        if (stopped || destination === 'none' || active)
+        if (stopped || destination === 'none' || (active && !force))
             return;
-        const image = cached;
+        const image = active ?? cached;
         if (!image ||
             image.viewport !== viewport() ||
             !image.sources.every(validSource) ||
@@ -684,7 +690,12 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
                 paintFrame = 0;
                 if (!isCurrent())
                     return;
-                void call({ action: 'painted', token: image.data.token }).catch(() => {
+                void call({ action: 'painted', token: image.data.token })
+                    .then((result) => {
+                    if (isCurrent() && result?.shown === false)
+                        abandon(image, false);
+                })
+                    .catch(() => {
                     if (isCurrent())
                         abandon(image, false);
                 });
@@ -696,7 +707,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
                 abandon(image, false);
         });
     };
-    const end = () => {
+    const restore = () => {
         if (!active || stopped || ending)
             return;
         // A return belongs to the captured surface, never to the modal exposed beneath it.
@@ -795,6 +806,25 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
             win.dispatchEvent(new Event(sourcesChangedEvent));
         }
     };
+    const begin = () => {
+        const starting = !locallyRequested;
+        locallyRequested = true;
+        present(starting && projectionRequest.isPaused());
+    };
+    const end = () => {
+        locallyRequested = false;
+        if (!projectionRequest.isPaused())
+            restore();
+    };
+    const projectionChanged = () => queueMicrotask(() => {
+        if (stopped)
+            return;
+        if (projectionRequest.isPaused())
+            present();
+        else if (!locallyRequested)
+            restore();
+        callbacks.wake();
+    });
     let eventListener;
     try {
         if (callbacks.events)
@@ -806,6 +836,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
                 // Native hide has already happened. Retire images and invalidate pending captures,
                 // without calling the plugin's public hide method or disturbing its fallback DOM.
                 if (destination === 'none') {
+                    locallyRequested = false;
                     invalidate();
                     return;
                 }
@@ -813,6 +844,8 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
                     begin();
                 if (next === 'native') {
                     end();
+                    if (projectionRequest.isPaused())
+                        present(true);
                     schedule();
                 }
                 if (updated)
@@ -825,6 +858,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
         await bounded(Promise.resolve(listener.remove())).catch(() => { });
         throw error;
     }
+    const stopPause = projectionRequest.subscribe(projectionChanged);
     return {
         get owners() {
             return [...owners];
@@ -854,6 +888,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
         invalidate,
         async destroy() {
             stopped = true;
+            stopPause();
             invalidate();
             imagePool.forEach((pool) => pool.forEach((image) => image.remove()));
             imagePool.clear();

package/dist/types.d.ts

@@ -79,7 +79,11 @@ export type WebProjectionResult<Request extends WebProjectionRequest> = Request
     action: 'cover' | 'restore';
 } ? {
     shown: boolean;
-} : void;
+} : Request extends {
+    action: 'painted';
+} ? {
+    shown: boolean;
+} | void : void;
 export interface ListenerHandle {
     remove(): Promise<void> | void;
 }

package/docs/README.md

@@ -1,18 +1,24 @@
 # 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.
+Build Web-driven screens with native controls and capabilities. These guides
+explain how to integrate the Engine into a plugin so Web UI and Native UI can
+coexist. Start with [the shared model](concepts.md): how a native component belongs in a Web layout,
+which layer presents it, and how interaction returns to the live view. Scrolling
+and overlays are examples of that coordination, not separate integration models.
+
+Then choose the smallest integration that fits your ownership model. Register a
+native view and its DOM container, connect the lifecycle notifications your UI
+needs, and add advanced APIs only if you already own a renderer's 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. |
+| Case                                                                                     | Start here                                                                                            | Why                                                                                                                 |
+| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| An eligible native SDK view belongs in a scrolling Web feed                              | [Basic registration](getting-started/initialization.md) and [platform limits](reference/platforms.md) | Bind it to its DOM container; native tracking or temporary image presentation depends on the platform and layout.   |
+| 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, then connect overlay lifecycle; the Engine coordinates handoff 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.
@@ -43,6 +49,7 @@ that require each option. Read only the relevant detail:
 - [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.
+- [Custom Web overlays](configuration/pause-resume.md): re-export pause/resume from a plugin so applications can bracket their own overlays.
 
 ## 4. Use advanced APIs when you own a renderer
 

package/docs/concepts.md

@@ -1,21 +1,46 @@
 # 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.
+The goal is to combine the flexibility of Web layouts and navigation with native
+controls and capabilities in one screen. Applications keep their Web-driven UI;
+plugins supply native components. The Engine coordinates presentation between
+them so each component can coexist with the surrounding screen throughout layout
+changes, interaction and navigation.
 
 ## 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.
+Creating a native view does not give it a place in the DOM. A view above the
+WebView does not automatically follow a scrolling container or participate in
+its clipping and stacking order. A higher Web `z-index` cannot cover it. Simply
+hiding and showing it can reveal a different appearance or restore it at an
+outdated 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.
+The shared integration model is a native view paired with a DOM container. The
+container identifies where the component belongs in the Web screen. The plugin
+provides native content and reports changes; the Engine coordinates measurement,
+prepared appearance and the handoff between presentation layers.
+
+## What coexistence looks like
+
+These situations share the same presentation model. Each integration connects the lifecycle and value notifications it needs:
+
+| Situation                                                | Desired experience                                                                 | How the shared model helps                                                                                           |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| An eligible native advertisement sits in a Web feed      | It stays aligned with the content as the reader scrolls.                           | The DOM container supplies geometry; supported native tracking or temporary Web projection follows the movement.     |
+| A Web alert opens over native navigation controls        | The alert covers their appearance, then native interaction returns when it closes. | Lifecycle notifications or the Ionic adapter request coverage; the Engine coordinates image handoff and restoration. |
+| A page or modal changes layout                           | Its native controls return at the current location rather than an old rectangle.   | Geometry and restoration are coordinated with the owning container's lifetime.                                       |
+| A native toggle changes while its Web fallback is hidden | Returning to HTML does not reveal the old value.                                   | Optional value bindings reflect component data independently of presentation.                                        |
+
+Scrolling does not always mean moving a live native view. Supported iOS overflow
+layouts can use native scroll bindings; Android uses temporary image presentation,
+and unsupported layouts follow the configured fallback policy. Images do not
+provide live SDK interaction. See [platform limits](reference/platforms.md) and
+[scroll binding constraints](advanced/native-handoff.md#native-scroll-tracking).
+
+The Engine prepares images while native content is available and retains them
+through the handoff until native restoration is acknowledged. Preparation is
+separate from presentation so opening an overlay does not wait for capture.
+Application-specific lifecycle decisions still need notifications; registering a
+view does not automatically detect every framework's overlays.
 
 ## Three presentations, with different purposes
 
@@ -91,7 +116,7 @@ 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.
+fallback before integrating. Read the [capture and platform reference](reference/platforms.md)
+and [projection contract](reference/projection.md) for eligibility and failure policies.
 
 [Documentation overview](README.md)

package/docs/configuration/README.md

@@ -17,13 +17,15 @@ same position: include that successful selection notification in `receiveListene
 | `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.                                                                                                                                        |
+| `allowedOrigins`        | Capacitor: bundled `server.url` or local hostname/scheme; localhost defaults when no app server config exists. Cordova: localhost defaults. | Override for programmatic configuration or a narrower trusted origin. On Android set `install` before navigation; registrations inherit it. See [origin matching](../reference/projection.md).                                                                                                              |
 | `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.
+not a registration argument. For application-owned overlays, plugins can
+[re-export pause/resume](pause-resume.md) so applications explicitly bracket their
+overlays.
 
 [Documentation overview](../README.md)