@webview-native-ui/engine 1.0.1 → 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/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

@@ -45,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(() => {

package/dist/projection/web.js

@@ -2,6 +2,7 @@ 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';
+import { getProjectionPause } from './pause.js';
 const layout = ({ control: c }, positionIndependent = false) => [
     c.id,
     c.kind,
@@ -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('-');
@@ -324,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.
@@ -618,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) ||
@@ -685,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);
                 });
@@ -697,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.
@@ -796,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)
@@ -807,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;
                 }
@@ -814,6 +844,8 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
                     begin();
                 if (next === 'native') {
                     end();
+                    if (projectionRequest.isPaused())
+                        present(true);
                     schedule();
                 }
                 if (updated)
@@ -826,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];
@@ -855,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

@@ -49,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/configuration/README.md

@@ -24,6 +24,8 @@ same position: include that successful selection notification in `receiveListene
 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)

package/docs/configuration/ionic-overlays.md

@@ -5,10 +5,17 @@ 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
+Applications use this adapter with an Engine-enabled plugin. Plugin authors first
+integrate through the [Capacitor](../getting-started/capacitor.md) or
+[Cordova](../getting-started/cordova.md) guide. Non-Ionic applications use their own
 lifecycle notifications and do not install this adapter.
 
+The `/ionic` entry point provides shared framework integration. It observes Ionic
+overlays and determines which registered surfaces they cover. A plugin's explicit
+presentation controls remain part of that plugin's API, connected through
+[projection notifications](events.md) or its existing
+[renderer API](../advanced/renderer.md).
+
 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
@@ -32,6 +39,10 @@ One monitor is shared per document, including between the npm module and the run
 
 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.
 
+Here, Alert means Ionic's `ion-alert`. This adapter does not intercept
+`window.alert()`, detect HTML `<dialog>` automatically, or observe native dialogs.
+Custom Web overlays can supply lifecycle events through `additional`, below.
+
 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
@@ -42,6 +53,8 @@ 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.
+`IonicOverlayOptions`, exported from the same `/ionic` entry point, is the TypeScript
+type for these settings; it is not another initialization function.
 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
@@ -63,3 +76,24 @@ enableSupportIonicOverlays({
 ```
 
 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.
+
+## When a plugin needs to know which modal is behind another
+
+For ordinary application setup, use `enableSupportIonicOverlays()` as shown above.
+The Engine then handles Ionic overlay coverage without additional calls.
+
+A plugin that places native controls inside Ionic modals may also need to know
+which modal lies behind the one being opened. Two helpers from the same `/ionic`
+entry point let the plugin read the modal order already tracked by the Engine.
+
+For example, open modal A, then modal B above it:
+
+- `ionicModalStack(document)` returns `[A, B]`, from back to front.
+- `coveredIonicSurface(B)` returns A, the modal beneath B.
+- If a popover opens above B, `coveredIonicSurface(popover)` returns B.
+- `coveredIonicSurface(A)` returns `undefined`: the page behind A is not a modal.
+
+A and B here are the actual `ion-modal` DOM elements. These helpers only read the
+tracked modal order; they do not open or close overlays, switch projection, or
+start monitoring. Call them after `enableSupportIonicOverlays()` has enabled the
+monitor and the relevant overlay has entered its presentation lifecycle.

package/docs/configuration/pause-resume.md

@@ -0,0 +1,51 @@
+# Cover native UI with a custom Web overlay
+
+Use `pause()` before presenting a custom modal or `div` over native UI and
+`resume()` when it closes. For Ionic overlays, use the automatic
+[Ionic integration](ionic-overlays.md), which shares this coordination but only
+covers surfaces behind the overlay.
+
+## Plugin authors: re-export the Engine functions
+
+```ts
+export { pause, resume } from '@webview-native-ui/engine';
+```
+
+The functions share one pause count across Engine-enabled plugins and bundles in
+the same document. No wrapper or native plugin method is needed.
+
+## Application authors: pair each pause with a resume
+
+```ts
+import { pause, resume } from 'your-plugin';
+
+pause();
+try {
+  await showCustomModal();
+} finally {
+  resume();
+}
+```
+
+`showCustomModal()` must resolve when the modal closes. With event-driven modals,
+call `resume()` on dismissal, cancellation or failure. Use one pair per overlay,
+even with multiple plugins; nested overlays each need their own pair.
+
+A pause replaces visible native surfaces with prepared Web images or their normal
+Web fallback. Hidden surfaces stay hidden. The final `resume()` releases
+the request, preserving each plugin's presentation intent and remaining Ionic
+overlay coverage.
+
+The counter does not track callers or pair individual calls. An extra `resume()`
+while paused can release another overlay's request; only a `resume()` at zero has
+no effect. Each owner must release exactly once for each pause it requested.
+
+Both functions return immediately, without waiting for native acknowledgments or
+painting. Returning from `pause()` does not mean native UI has already moved
+behind the Web overlay; it may remain in front until the handoff completes.
+The final `resume()` defers native restoration until the second animation frame,
+allowing overlay removal to paint without guaranteeing compositor completion.
+Call it after removing the overlay or completing
+its dismissal animation. A new `pause()` cancels a pending restoration.
+Calling `pause()` just before a blocking `window.alert()` therefore does
+not guarantee a completed handoff. They do not detect custom overlays automatically.

package/docs/controls.md

@@ -0,0 +1,39 @@
+# Shared controls for native adapters
+
+The existing Engine package also owns the control implementation used by Capacitor Native UI.
+No additional npm package or workspace is required.
+
+- `@webview-native-ui/engine`: generic projection API; unchanged dependency boundary.
+- `@webview-native-ui/engine/controls`: control runtime and transport contract.
+- `@webview-native-ui/engine/controls/ionic`: optional Ionic overlay implementation.
+- `@webview-native-ui/engine/integration`: the single shared transition/search integration state.
+
+An adapter creates one `createNativeUI({ plugin, getPlatform, isAvailable })` instance and keeps it
+for its lifetime. The plugin implements the `NativeUIPlugin` transport interface. The adapter owns
+host registration, method dispatch, listener delivery, and lifecycle hooks; Engine owns rendering,
+DOM ownership, extension acknowledgement, and teardown sequencing. Cordova can supply this same
+transport without importing Capacitor. The Cordova Native UI plugin itself is a subsequent change.
+
+SwiftPM exposes the optional `WebViewNativeUIControls` product, depending on `WebViewNativeUIEngine`.
+CocoaPods exposes `WebViewNativeUIControls` with the same dependency. Android exposes the optional
+`io.github.webview-native-ui:controls` artifact from `android/controls`; it depends on `engine` and
+Compose. Generic Engine consumers keep their existing dependencies and Android minimum SDK 23.
+Controls require Android API 24. Native adapters create `NativeUIController` and forward requests
+and events. iOS receives JSON dictionaries and completion closures; Android receives JSONObjects.
+
+The Ionic theme imports Engine integration directly. The Capacitor compatibility integration export
+re-exports that module. Resolve a single Engine version in the application; do not bundle a private
+copy of integration into the theme or adapter. The `/controls` entry does not load Ionic runtime code;
+load `/controls/ionic` only when opting into Ionic overlays.
+
+## Verification and release order
+
+Run `npm run test:controls` for the migrated control tests and `npm test` for generic projection.
+SwiftPM's `WebViewNativeUIEngine-Package` scheme covers both native targets. Android's
+`:controls:testReleaseUnitTest` covers the migrated snapshot parser. Existing Capacitor transport
+and hosted lifecycle tests remain in its repository, and the theme retains the real demo E2E suite.
+
+Build and verify Engine first, including both signed Maven artifacts in the same Central bundle and
+both npm-distributed podspecs. Release the Engine native artifacts and npm package at the same version
+before refreshing the Capacitor and theme registry lockfiles. Candidate verification uses local npm
+tarballs and a temporary SwiftPM path or local Maven repository; do not commit these temporary paths.

package/ios/Sources/WebViewNativeUIControls/Components/NativeUIButton.swift

@@ -0,0 +1,98 @@
+import UIKit
+
+enum NativeUIButton {
+    private final class BadgeLabel: UILabel {}
+    private static let activationID = UIAction.Identifier("native-ui-activate")
+
+    /// Reuse an unambiguous presentation slot while keeping action IDs source-specific.
+    @MainActor
+    static func reassociate(_ nodes: [NativeUIControl], controls: inout [String: UIView],
+                            fingerprints: inout [String: NativeUIControl]) -> Set<String> {
+        func identity(_ node: NativeUIControl) -> String? {
+            guard node.placement == nil, kinds.contains(node.kind), node.items.count == 1 else { return nil }
+            return node.items[0].content.transitionId
+        }
+        // swiftlint:disable:next force_unwrapping
+        let old = Dictionary(grouping: fingerprints.values.filter { identity($0) != nil }, by: { identity($0)! })
+        // swiftlint:disable:next force_unwrapping
+        let incoming = Dictionary(grouping: nodes.filter { identity($0) != nil }, by: { identity($0)! })
+        let retained = Set(nodes.map(\.id))
+        var reused = Set<String>()
+        for (key, matches) in incoming {
+            guard matches.count == 1, let node = matches.first, controls[node.id] == nil,
+                  let previous = old[key], previous.count == 1, let source = previous.first,
+                  !retained.contains(source.id), let button = controls[source.id] as? UIButton else { continue }
+            controls.removeValue(forKey: source.id)
+            fingerprints.removeValue(forKey: source.id)
+            controls[node.id] = button
+            reused.insert(node.id)
+        }
+        return reused
+    }
+    // These Ionic components share the same native UIButton presentation.
+    static let kinds: [NativeUIComponent] = [.button, .backButton, .menuButton]
+
+    @available(iOS 26.0, *)
+    static func make(_ node: NativeUIControl, existing: UIButton? = nil, rendering: NativeUIControlRendering, activate: @escaping (String) -> Void) -> UIButton? {
+        guard node.items.count == 1, let item = node.items.first else { return nil }
+        let control = render(item.content, glass: item.content.buttonFill != .clear, existing: existing, rendering: rendering, activate: activate)
+        control.semanticContentAttribute = node.rtl ? .forceRightToLeft : .forceLeftToRight
+        return control
+    }
+
+    @available(iOS 26.0, *)
+    static func render(_ item: NativeUIItemContent, glass: Bool, existing: UIButton? = nil, rendering: NativeUIControlRendering, activate: @escaping (String) -> Void) -> UIButton {
+        var configuration: UIButton.Configuration = glass ? .glass() : .plain()
+        configuration.title = item.label
+        configuration.image = rendering.image(item)
+        configuration.imagePadding = item.imagePadding ?? 4
+        configuration.contentInsets = NSDirectionalEdgeInsets(top: 0, leading: item.contentInsetLeading ?? 4,
+                                                              bottom: 0, trailing: item.contentInsetTrailing ?? 4)
+        configuration.imagePlacement = item.iconPosition == .trailing ? .trailing : .leading
+        configuration.baseForegroundColor = rendering.color(item.color)
+        configuration.titleLineBreakMode = .byTruncatingTail
+        let size = item.fontSize
+        let weight = item.fontWeight
+        configuration.titleTextAttributesTransformer = UIConfigurationTextAttributesTransformer { incoming in
+            var outgoing = incoming
+            outgoing.font = UIFont.systemFont(ofSize: size, weight: weight >= 600 ? .semibold : weight >= 500 ? .medium : .regular)
+            return outgoing
+        }
+        let button = existing ?? UIButton(configuration: configuration)
+        if existing != nil { button.configuration = configuration }
+        button.titleLabel?.numberOfLines = 1
+        // Web and UIKit can differ by a fraction of a point in text measurement.
+        // Absorb that rounding without widening the projected button.
+        button.titleLabel?.adjustsFontSizeToFitWidth = true
+        button.titleLabel?.minimumScaleFactor = 0.99
+        button.isEnabled = !item.disabled
+        button.accessibilityLabel = item.accessibilityLabel
+        button.accessibilityIdentifier = item.id
+        if item.selected { button.accessibilityTraits.insert(.selected) } else { button.accessibilityTraits.remove(.selected) }
+        if item.disabled { button.accessibilityTraits.insert(.notEnabled) } else { button.accessibilityTraits.remove(.notEnabled) }
+        button.subviews.filter { $0 is BadgeLabel }.forEach { $0.removeFromSuperview() }
+        button.accessibilityValue = item.badge?.value
+        if let badge = item.badge {
+            let label = BadgeLabel()
+            label.text = badge.value
+            label.font = .systemFont(ofSize: 11, weight: .semibold)
+            label.textColor = rendering.color(badge.textColor)
+            label.backgroundColor = rendering.color(badge.color)
+            label.textAlignment = .center
+            label.layer.cornerRadius = 8
+            label.clipsToBounds = true
+            label.isAccessibilityElement = false
+            label.translatesAutoresizingMaskIntoConstraints = false
+            button.addSubview(label)
+            NSLayoutConstraint.activate([
+                label.centerXAnchor.constraint(equalTo: button.centerXAnchor, constant: 14),
+                label.topAnchor.constraint(equalTo: button.topAnchor, constant: 1),
+                label.widthAnchor.constraint(greaterThanOrEqualToConstant: max(16, label.intrinsicContentSize.width + 6)),
+                label.heightAnchor.constraint(equalToConstant: 16)
+            ])
+        }
+        button.removeAction(identifiedBy: activationID, for: .touchUpInside)
+        button.addAction(UIAction(identifier: activationID) { _ in activate(item.id) }, for: .touchUpInside)
+        return button
+    }
+}

package/ios/Sources/WebViewNativeUIControls/Components/NativeUIButtons.swift

@@ -0,0 +1,24 @@
+import UIKit
+
+enum NativeUIButtons {
+    static let kind = NativeUIComponent.buttons
+
+    @available(iOS 26.0, *)
+    static func make(_ node: NativeUIControl, scale: CGFloat, rendering: NativeUIControlRendering, activate: @escaping (String) -> Void) -> UIView {
+        let items = node.items
+        let rtl = node.rtl
+        let effect = UIGlassEffect(style: .regular)
+        let control = UIVisualEffectView(effect: effect)
+        control.layer.cornerRadius = node.frame.height * scale / 2
+        control.clipsToBounds = true
+        control.accessibilityIdentifier = node.id
+        for item in items {
+            let button = NativeUIButton.render(item.content, glass: false, rendering: rendering, activate: activate)
+            button.semanticContentAttribute = rtl ? .forceRightToLeft : .forceLeftToRight
+            let rect = item.frame.rect
+            button.frame = CGRect(x: rect.minX * scale, y: rect.minY * scale, width: rect.width * scale, height: rect.height * scale)
+            control.contentView.addSubview(button)
+        }
+        return control
+    }
+}