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

package/README.md

@@ -1,60 +1,73 @@
-# WebView Native UI Engine
+# Beyond the WebView.
 
-**Bring Web UI above the native layer.**
+**Bring Native UI seamlessly into Web apps.**
 
-_Visually, through seamless native-to-Web projection._
+Build your screens with the flexibility of the Web and the controls and capabilities of native platforms. WebView Native UI Engine helps them work together as one experience, while keeping your Web layouts and navigation.
+
+## Web UI. Native UI. One experience.
+
+A native component should feel like part of the screen around it. For example:
+
+- **Scroll together.** A native ad moves with the surrounding Web content as the reader scrolls through a feed.
+- **Layer together.** A Web alert appears over native navigation controls. Close it, and those controls are ready for native interaction again.
+
+Scrolling and overlays are examples of a broader goal: letting Web UI and Native UI coexist throughout the screen's lifecycle.
 
 ![Conceptual view of a Web overlay above a native surface and WebView content](docs/assets/hero.png)
 
-_Conceptual view. Native appearance is projected into the Web layer during overlay presentation._
+_Conceptual view of overlay presentation. The Engine projects native appearance into the Web layer; it does not reorder the actual native view within the DOM._
+
+https://github.com/user-attachments/assets/2768f014-7325-49c7-b848-25052756c36d
 
-Build WebView apps where native controls and Web content share the same scrolling screens, transitions and overlays.
+native controls beneath a Web alert, followed by a native ad scrolling with Web content. Recorded on iOS Simulator.
 
-## Beyond the WebView boundary
+## Built for plugin developers
 
-WebView apps combine the Web's flexible layouts with access to native platform capabilities. But native UI and the Web page live in separate rendering layers. A native control placed above the WebView does not automatically participate in DOM scrolling, clipping or stacking order. A Web modal cannot simply cover it with a higher `z-index`.
+WebView Native UI Engine is a library for **Capacitor and Cordova plugin developers**. Integrate it into a plugin to bring native components into Web-driven screens, without making each application build its own coordination between rendering layers.
 
-Crossing that boundary takes more than a bridge call. It requires coordinating placement, appearance, input, rendering and restoration across two rendering systems on each platform. Rebuilding that coordination for every component makes otherwise useful designs expensive to deliver and maintain.
+A native view above a WebView does not automatically participate in DOM scrolling, clipping or stacking order. A Web modal cannot simply cover it with a higher `z-index`. The Engine coordinates presentation across that boundary, so you can focus on the controls and native capabilities your plugin provides.
 
-WebView Native UI Engine makes that work reusable. It lets applications combine native UI with Web-driven screens and interactions, while sharing the machinery that moves presentation between the two layers. The goal is to expand what a WebView app can be built to do—and make that practical to ship.
+Use it for toolbars, tab bars, controls and capturable SDK views. Keep your existing plugin API and business logic; applications gain these capabilities through the plugins they use.
 
-## What this makes possible
+## How it works
 
-- **Native UI within Web-designed screens.** Combine native toolbars, tab bars, player controls and eligible SDK views with the application's DOM layout and navigation.
-- **Web overlays that coexist with native content.** Present modals and other overlays over native surfaces, then return to the interactive native UI when they close.
-- **Scrolling and transitions that retain native appearance.** Carry the native surface's captured appearance through Web-layer movement, without recreating its styling in CSS.
-- **Shared infrastructure across components and platforms.** Reuse the same projection and restoration lifecycle on iOS and Android instead of implementing it independently in every integration.
+The plugin supplies a native view and a DOM container that defines its place in the Web layout. The Engine coordinates DOM measurement, supported native scroll tracking and the handoff between native and Web presentation.
 
-## The approach
+When the Web layer needs to own presentation, the Engine displays a prepared image of the native component in that container. When native presentation can resume, it coordinates placement and restoration of the interactive view.
 
-Use the live native view where it belongs, and a prepared visual projection in the DOM when the Web layer needs to own presentation. Restore the interactive native view when it can take over again. An existing DOM container gives the Web projection its place in the application's layout and layer structure.
+The image is a temporary visual projection, not a second interactive control. It does not forward clicks or play live video. Capture eligibility and platform rendering limits still apply, including differences in Liquid Glass highlights. When a suitable image is unavailable, the integration uses its configured Web fallback. See [concepts and limits](docs/concepts.md) and [platform support](docs/reference/platforms.md) before choosing a component.
 
-The Engine coordinates this handoff; the integrating renderer still creates and positions its views. A projected image preserves appearance, not live interaction or video. Capture availability and layout support determine when a projection can be used, with an explicit fallback when it cannot. See [concepts and limits](docs/concepts.md) for the detailed contract and limits.
+## Start building
 
-## Choose your starting point
+The Engine supports **iOS and Android**. Ionic and Angular are optional. Start with a native view and its DOM container, then connect the lifecycle notifications your UI needs. The integration guides cover runtime startup and optional framework support.
 
-Applications gain these capabilities through plugins that integrate the Engine.
-Plugin authors retain their existing native controls and public APIs; the Engine
-supplies the coordination between native and Web presentation. It supports iOS
-and Android with Capacitor or Cordova. Ionic and Angular are not required.
+| Start here                                                     | Why                                                                                   |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| [Basic initialization](docs/getting-started/initialization.md) | Register a native view and its DOM container with the minimum required setup.         |
+| [Capacitor plugin guide](docs/getting-started/capacitor.md)    | Connect the Engine to an existing Capacitor plugin.                                   |
+| [Cordova plugin guide](docs/getting-started/cordova.md)        | Use the same lifecycle through Cordova's native hooks.                                |
+| [Documentation](docs/README.md)                                | Find optional settings, renderer APIs and reference by the problem you need to solve. |
 
-| Start here                                                     | Purpose                                                                              |
-| -------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| [Documentation](docs/README.md)                                | Reading order: basic initialization, optional behavior, advanced APIs and reference. |
-| [Concepts and limits](docs/concepts.md)                        | Decide whether projection fits your component.                                       |
-| [Basic initialization](docs/getting-started/initialization.md) | Minimum setup and required inputs, before framework-specific integration.            |
+Use matching Engine versions across npm and native dependencies, and retain dependency lockfiles for reproducible builds. Android placement requires API 23+, with composited snapshots available from API 26+.
 
-Native registration starts the Web runtime; the base integration needs no separate
-application-side Engine initializer. The API is pre-1.0: pin matching Engine
-versions across npm and native dependencies. Android placement requires API 23+,
-with composited snapshots available from API 26+.
+## Optional Ionic integration
 
-## Reference and contributing
+For Ionic applications using an Engine-enabled plugin, the `@webview-native-ui/engine/ionic` entry point connects Ionic overlay lifecycle events to native projection:
 
-The [documentation index](docs/README.md) links to configuration, advanced APIs,
-container support and platform contracts. For repository development and publishing,
-see [development and releases](docs/maintenance.md).
+```ts
+import { enableSupportIonicOverlays } from '@webview-native-ui/engine/ionic';
+
+enableSupportIonicOverlays();
+```
+
+Call it once during application startup unless your plugin already enables it. Applications importing it directly need `@webview-native-ui/engine` as a direct dependency. This shared framework integration coordinates coverage across plugins; each plugin retains control of its own presentation API. See [Ionic overlay support](docs/configuration/ionic-overlays.md) for setup, supported overlays and renderer helpers.
+
+## Contributing
+
+For repository development, verification and publishing, see [development and releases](docs/maintenance.md).
 
 ## License
 
 [MIT](LICENSE). Commercial use, modification and redistribution are permitted with the license's notice and attribution requirements. The Engine's license does not change the licenses of applications or plugins that depend on it.
+
+For the optional shared control runtime and adapter boundaries, see [shared controls](docs/controls.md).

package/WebViewNativeUIControls.podspec

@@ -0,0 +1,17 @@
+require 'json'
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+Pod::Spec.new do |s|
+ s.name = 'WebViewNativeUIControls'
+ s.version = package['version']
+ s.summary = 'Native UI infrastructure for Capacitor and Cordova plugin maintainers.'
+ s.homepage = 'https://github.com/webview-native-ui/engine'
+ s.license = { :type => 'MIT', :file => 'LICENSE' }
+ s.preserve_paths = 'LICENSE'
+ s.author = { 'rdlabo' => 'sakakibara@rdlabo.jp' }
+ s.source = { :git => 'https://github.com/webview-native-ui/engine.git', :tag => "v#{s.version}" }
+ s.source_files = 'ios/Sources/WebViewNativeUIControls/**/*.swift'
+ s.ios.deployment_target = '15.0'
+ s.swift_version = '5.9'
+ s.frameworks = 'UIKit', 'WebKit', 'SwiftUI'
+ s.dependency 'WebViewNativeUIEngine', s.version.to_s
+end

package/dist/controls/activation.d.ts

@@ -0,0 +1,15 @@
+import type { NativeUITransport } from './transport.js';
+import type { NativeUIRuntimeHandle, NativeUIRuntimeOptions, NativeUIPlugin, WebViewMetrics } from './definitions.js';
+import { type NativeUIConnection } from './shared/connection.js';
+export interface OverlayController {
+    suspend(): Promise<() => void>;
+    destroy(): Promise<void>;
+}
+type OverlayFactory = (doc: Document, plugin: NativeUIPlugin, options: NativeUIRuntimeOptions, retain: (deferActivation?: (id: string) => boolean) => () => void, nativeRail: () => boolean, connection?: NativeUIConnection) => Promise<OverlayController>;
+export { defineNativeUI } from './extensions.js';
+export type { NativeUIExtension, NativeUIValue } from './extensions.js';
+export type { NativeUIComponent, NativeUIControls, NativeUIRuntimeHandle, NativeUIRuntimeOptions, NativeUIStatus, NativeUISuspension, VerticalBarEdge, WebViewMetrics, } from './definitions.js';
+export declare const createNativeUIActivation: (transport: NativeUITransport) => {
+    enableNativeUI: (options?: NativeUIRuntimeOptions, overlayFactory?: OverlayFactory) => Promise<NativeUIRuntimeHandle>;
+    configureNativeTransition: () => Promise<WebViewMetrics>;
+};

package/dist/controls/activation.js

@@ -0,0 +1,370 @@
+import { controlDefault } from './shared/control-options.js';
+import { toolbarOptions } from './shared/toolbar-options.js';
+import { createDiagnostics } from './shared/diagnostics.js';
+import { createHTMLWebProjection } from './html.js';
+import { validateExtensions } from './extensions.js';
+import { nativeWebViewMetrics } from '../integration/index.js';
+import { createRuntime } from './runtime.js';
+import { bounded, boundedListener } from './shared/bridge.js';
+import { createNativeConnection } from './shared/connection.js';
+import { createVerticalBarsWebProjection } from './vertical-bars-web.js';
+import { prehideVerticalBarsToolbarSources } from './prehide.js';
+import { observeVerticalBarsModals, topModal, modalPreparing, modalPresentation } from './shared/modal.js';
+export { defineNativeUI } from './extensions.js';
+export const createNativeUIActivation = (transport) => {
+    const plugin = transport.plugin;
+    let active;
+    let activeFailed = false;
+    let activeRoot;
+    let activeRailHost;
+    let activeConfiguration;
+    let activeExtensions = [];
+    let stopping;
+    // Every stop entry point releases the activation immediately but reserves the
+    // shared native/DOM resources until its teardown has settled.
+    const stopActivation = (owner, destruction) => {
+        if (active !== owner)
+            return;
+        active = undefined;
+        activeFailed = false;
+        activeConfiguration = undefined;
+        activeRoot = undefined;
+        activeRailHost = undefined;
+        activeExtensions = [];
+        stopping = destruction;
+        const release = () => {
+            if (stopping === destruction)
+                stopping = undefined;
+        };
+        void destruction.then(release, release);
+    };
+    const web = (reason) => ({
+        markForCheck: () => { },
+        getStatus: () => ({ state: 'web', projected: 0, updates: 0, reason }),
+        suspend: async () => ({ resume: async () => { } }),
+        destroy: async () => { },
+    });
+    const combine = (native, fallback) => ({
+        markForCheck() {
+            native.markForCheck();
+            fallback.markForCheck();
+        },
+        getStatus() {
+            const nativeStatus = native.getStatus();
+            const fallbackStatus = fallback.getStatus();
+            return {
+                ...nativeStatus,
+                state: nativeStatus.state === 'stopped' && fallbackStatus.state === 'stopped'
+                    ? 'stopped'
+                    : nativeStatus.projected > 0
+                        ? 'native'
+                        : 'web',
+                projected: nativeStatus.projected + fallbackStatus.projected,
+                updates: nativeStatus.updates + fallbackStatus.updates,
+            };
+        },
+        async suspend(options) {
+            const [nativeLease, fallbackLease] = await Promise.all([native.suspend(options), fallback.suspend(options)]);
+            return { resume: async () => void (await Promise.all([nativeLease.resume(), fallbackLease.resume()])) };
+        },
+        async destroy() {
+            await Promise.all([native.destroy(), fallback.destroy()]);
+        },
+    });
+    /** Wraps a runtime handle with the shared enable-lifecycle: reason, suspend hooks and idempotent destroy. */
+    const manage = (handle, lifecycle = {}) => {
+        let destruction;
+        return {
+            markForCheck: () => {
+                if (!destruction)
+                    handle.markForCheck();
+            },
+            getStatus: () => (lifecycle.reason ? { ...handle.getStatus(), reason: lifecycle.reason } : handle.getStatus()),
+            async suspend(options) {
+                const lease = await handle.suspend(options);
+                const resume = await lifecycle.suspend?.();
+                return {
+                    async resume() {
+                        await lease.resume();
+                        resume?.();
+                    },
+                };
+            },
+            destroy() {
+                if (!destruction) {
+                    destruction = Promise.resolve().then(async () => {
+                        try {
+                            await handle.destroy();
+                        }
+                        finally {
+                            await lifecycle.destroy?.();
+                        }
+                    });
+                    lifecycle.stopping?.(destruction);
+                }
+                return destruction;
+            },
+        };
+    };
+    /** Reads the current native WebView geometry and applies it to page transitions. */
+    const configureNativeTransition = async () => {
+        const metrics = typeof document !== 'undefined' && transport.getPlatform() === 'ios' && transport.isAvailable()
+            ? await bounded(plugin.getWebViewMetrics())
+            : { radius: 0 };
+        nativeWebViewMetrics.radius = metrics.radius;
+        return metrics;
+    };
+    /** Resolves a logical vertical-bar edge to the physical side for the given direction. */
+    const physicalVerticalBarEdge = (edge, rtl) => (edge === 'leading') !== rtl ? 'left' : 'right';
+    const elementRtl = (element) => element.closest('[dir]')?.getAttribute('dir') === 'rtl';
+    const webProjection = (doc, options, enabled = () => true) => {
+        const ionic = () => createVerticalBarsWebProjection(doc, options, () => options.verticalBars?.enabled !== false && enabled());
+        if (options.source === 'html')
+            return createHTMLWebProjection(doc, options);
+        if (options.source === 'auto')
+            return combine(ionic(), createHTMLWebProjection(doc, options));
+        return ionic();
+    };
+    /** Call once at application startup. Ionic markup remains the source of truth. */
+    const enableNativeUI = (options = {}, overlayFactory) => {
+        if (typeof document === 'undefined')
+            return Promise.resolve(web('Requires a document'));
+        const extensions = [...(options.extensions ?? [])];
+        const nativeState = (options.nativeState = {});
+        try {
+            validateExtensions(extensions, document);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const configuration = JSON.stringify([
+            options.source ?? 'ionic',
+            options.debug === true,
+            options.ionic?.auto !== false,
+            options.verticalBars?.enabled !== false,
+            options.verticalBars?.placement?.edge,
+            options.rail?.edge,
+            toolbarOptions(options, false),
+            toolbarOptions(options, true),
+            options.ionic?.verticalBars?.buttonProjection ?? 'system',
+            // Local source overrides can use this even when the startup projection is system.
+            options.ionic?.verticalBars?.buttonDefaultFill ?? 'glass',
+            ...['tabs', 'segment', 'fab'].flatMap((kind) => [
+                controlDefault(options, kind, false),
+                controlDefault(options, kind, true),
+            ]),
+            options.ionic?.verticalBars?.popover === true,
+        ]);
+        if (active && activeFailed) {
+            const previous = active;
+            stopActivation(previous, previous.then((handle) => handle.destroy()));
+        }
+        if (active &&
+            (activeConfiguration !== configuration ||
+                activeRoot !== options.root ||
+                activeRailHost !== options.rail?.host ||
+                extensions.length !== activeExtensions.length ||
+                extensions.some((extension, index) => extension !== activeExtensions[index])))
+            return Promise.reject(new Error('Native UI is already running with different controls or extensions; destroy it before changing configuration.'));
+        if (active)
+            return active;
+        activeConfiguration = configuration;
+        activeRoot = options.root;
+        activeRailHost = options.rail?.host;
+        activeExtensions = extensions;
+        const previousStop = stopping;
+        let start;
+        const stop = (destruction) => stopActivation(start, destruction);
+        let releaseNative = async () => { };
+        let retired = false;
+        const pagehide = () => runtimeStopped('pagehide');
+        const runtimeStopped = (cause) => {
+            if (cause === 'failure') {
+                // Keep the Web rail usable, but replace this degraded activation on the next enable.
+                if (active === start)
+                    activeFailed = true;
+                void start
+                    .then(async () => {
+                    if (!retired)
+                        document.defaultView?.addEventListener('pagehide', pagehide, { once: true });
+                    await releaseNative();
+                })
+                    .catch(() => { });
+                return;
+            }
+            const destruction = start.then((handle) => handle.destroy());
+            stop(destruction);
+            void destruction.catch(() => { });
+        };
+        return (start = active =
+            (async () => {
+                // Native controls and DOM ownership are shared. A replacement activation
+                // must wait until the old handle has finished clearing both surfaces.
+                if (previousStop)
+                    await previousStop.catch(() => { });
+                const platform = transport.getPlatform();
+                const diagnose = createDiagnostics(options.debug);
+                let nativeModalAnimations = () => false;
+                const stopModals = options.source === 'html' ? () => { } : observeVerticalBarsModals(document, () => nativeModalAnimations());
+                const prehide = platform !== 'android' && options.source !== 'html' && options.ionic?.auto !== false
+                    ? prehideVerticalBarsToolbarSources(document, () => options.verticalBars?.enabled !== false, options.root, options)
+                    : undefined;
+                const fallback = (reason) => {
+                    diagnose(`web-fallback: ${reason}`);
+                    return manage(webProjection(document, options), {
+                        reason,
+                        suspend: () => prehide?.suspend(),
+                        destroy: () => {
+                            retired = true;
+                            document.defaultView?.removeEventListener('pagehide', pagehide);
+                            prehide?.stop();
+                            stopModals();
+                        },
+                        stopping: stop,
+                    });
+                };
+                if (platform !== 'ios' && platform !== 'android')
+                    return fallback('Requires an iOS or Android native host');
+                if (!transport.isAvailable())
+                    return fallback('Native UI plugin is not registered');
+                let runtime;
+                let overlays;
+                let connection;
+                let metricsListener;
+                let nativeRelease;
+                releaseNative = () => (nativeRelease ??= (async () => {
+                    try {
+                        connection?.stop();
+                        await overlays?.destroy();
+                    }
+                    finally {
+                        if (metricsListener)
+                            await bounded(metricsListener.remove()).catch(() => { });
+                    }
+                })());
+                const cleanup = async () => {
+                    retired = true;
+                    try {
+                        await releaseNative();
+                    }
+                    finally {
+                        document.defaultView?.removeEventListener('pagehide', pagehide);
+                        prehide?.stop();
+                        stopModals();
+                    }
+                };
+                try {
+                    const ordinaryControls = ['button', 'backButton', 'tabs', 'segment', 'fab'].some((kind) => controlDefault(options, kind, false));
+                    const capabilities = await bounded(plugin.configure({ suppressScrollEdgeEffect: ordinaryControls }));
+                    if (!capabilities.supported)
+                        return fallback('Native UI is unavailable on this device');
+                    if (capabilities.connectionState)
+                        connection = createNativeConnection(document, plugin);
+                    const listen = connection?.listen ?? plugin.addListener.bind(plugin);
+                    const unavailableExtensions = new Map();
+                    for (const extension of extensions) {
+                        if (platform === 'android' && extension.placement === 'tab-accessory')
+                            unavailableExtensions.set(extension.name, 'unsupported-placement: tab-accessory requires a supported iOS tab host.');
+                        else if (!capabilities.extensions?.includes(extension.name))
+                            unavailableExtensions.set(extension.name, 'unregistered-extension: register this name in the native app before enabling the shell, then rebuild.');
+                    }
+                    if (platform === 'android') {
+                        runtime = await createRuntime(document, plugin, {
+                            ...options,
+                            source: 'extensions',
+                            coveredSnapshots: capabilities.coveredSnapshots === true,
+                            extensions,
+                            unavailableExtensions,
+                        }, () => false, runtimeStopped, connection);
+                        runtime = combine(runtime, webProjection(document, options));
+                        metricsListener = await boundedListener(listen('webViewMetricsChange', () => {
+                            document.defaultView?.dispatchEvent(new Event('nativeUIRefresh'));
+                        }));
+                        connection?.start();
+                        return manage(runtime, {
+                            stopping: stop,
+                            destroy: cleanup,
+                        });
+                    }
+                    let deviceEdge = null;
+                    const ionicRoot = () => {
+                        if (options.source === 'html')
+                            return null;
+                        const root = options.root ?? document.body;
+                        return root.closest('ion-app') ?? root.querySelector('ion-app');
+                    };
+                    const updateNativeEdge = () => {
+                        const requested = options.verticalBars?.placement?.edge;
+                        const root = ionicRoot() ?? options.root ?? document.body;
+                        nativeState.edge =
+                            deviceEdge && (!requested || requested === deviceEdge) ? physicalVerticalBarEdge(deviceEdge, elementRtl(root)) : undefined;
+                    };
+                    // Ionic layout is read-only input; device metrics determine native availability.
+                    const nativeVerticalBars = () => {
+                        updateNativeEdge();
+                        if (options.verticalBars?.enabled === false)
+                            return false;
+                        const app = ionicRoot();
+                        if (!app?.classList.contains('ios-theme-vertical-bars'))
+                            return !!nativeState.edge;
+                        const physicalEdge = app.classList.contains('ios-theme-vertical-bars-left') ? 'left' : 'right';
+                        return physicalEdge === nativeState.edge;
+                    };
+                    nativeModalAnimations = () => capabilities.modalAnimation === true && nativeVerticalBars();
+                    const applyMetrics = (metrics) => {
+                        if (ordinaryControls)
+                            nativeWebViewMetrics.radius = metrics.radius;
+                        deviceEdge = metrics.verticalBarEdge ?? null;
+                        updateNativeEdge();
+                        document.defaultView?.dispatchEvent(new Event('nativeUIRefresh'));
+                    };
+                    metricsListener = await boundedListener(listen('webViewMetricsChange', applyMetrics));
+                    await bounded(Promise.resolve().then(() => plugin.getWebViewMetrics()))
+                        .then(applyMetrics)
+                        .catch(() => undefined);
+                    connection?.observe(async (_, restored) => {
+                        if (restored)
+                            await bounded(plugin.getWebViewMetrics())
+                                .then(applyMetrics)
+                                .catch(() => undefined);
+                    });
+                    const native = await createRuntime(document, plugin, {
+                        ...options,
+                        extensions,
+                        unavailableExtensions,
+                        coveredSnapshots: capabilities.coveredSnapshots === true,
+                        nativeScroll: capabilities.nativeScroll === true,
+                    }, nativeVerticalBars, runtimeStopped, connection);
+                    runtime = combine(native, webProjection(document, options, () => {
+                        const modal = topModal(document);
+                        return (!(modal && (modalPreparing(modal) || modalPresentation(modal))) &&
+                            (!nativeVerticalBars() || native.getStatus().projected === 0));
+                    }));
+                    if (options.ionic?.verticalBars?.popover === true && overlayFactory)
+                        overlays = await overlayFactory(document, plugin, options, native.retain, nativeVerticalBars, connection);
+                    connection?.start();
+                    return manage(runtime, {
+                        suspend: async () => {
+                            const restorePrehide = prehide?.suspend();
+                            const resumeOverlays = await overlays?.suspend();
+                            return () => {
+                                restorePrehide?.();
+                                resumeOverlays?.();
+                            };
+                        },
+                        stopping: stop,
+                        destroy: cleanup,
+                    });
+                }
+                catch (error) {
+                    connection?.stop();
+                    await overlays?.destroy().catch(() => { });
+                    await runtime?.destroy().catch(() => { });
+                    if (metricsListener)
+                        await bounded(metricsListener.remove()).catch(() => { });
+                    return fallback(error instanceof Error ? error.message : String(error));
+                }
+            })());
+    };
+    return { enableNativeUI, configureNativeTransition };
+};

package/dist/controls/components/index.d.ts

@@ -0,0 +1,16 @@
+import type { VerticalControlAreaOptions } from '../definitions.js';
+import * as button from './ion-button.js';
+import * as buttons from './ion-buttons.js';
+import * as backButton from './ion-back-button.js';
+import * as menuButton from './ion-menu-button.js';
+import * as tabBar from './ion-tab-bar.js';
+import * as segment from './ion-segment.js';
+import * as fab from './ion-fab.js';
+import type { Candidate, Identify } from '../shared/candidate.js';
+export declare const components: readonly [typeof button, typeof buttons, typeof backButton, typeof menuButton, typeof tabBar, typeof segment, typeof fab];
+export type NativeUIComponent = (typeof components)[number]['tag'];
+export declare const selector: string;
+export declare const shadowSelector: string;
+export declare const motionSelector: string;
+export declare const isVerticalBarsCandidate: (element: HTMLElement) => boolean;
+export declare const readCandidate: (element: HTMLElement, id: Identify, options?: VerticalControlAreaOptions) => Candidate | undefined;

package/dist/controls/components/index.js

@@ -0,0 +1,38 @@
+import * as button from './ion-button.js';
+import * as buttons from './ion-buttons.js';
+import * as backButton from './ion-back-button.js';
+import * as menuButton from './ion-menu-button.js';
+import * as tabBar from './ion-tab-bar.js';
+import * as segment from './ion-segment.js';
+import * as fab from './ion-fab.js';
+import { isVerticalBarsSource, visible, withoutPrehide } from '../shared/dom.js';
+// Static composition only. Each component declares its own tag, discovery and reader.
+export const components = [button, buttons, backButton, menuButton, tabBar, segment, fab];
+export const selector = components
+    .map((component) => ('selector' in component ? component.selector : component.tag))
+    .filter(Boolean)
+    .join(', ');
+export const shadowSelector = [
+    'ion-icon',
+    ...components.flatMap((component) => ('shadowSelector' in component ? [component.shadowSelector] : [])),
+].join(', ');
+export const motionSelector = [
+    '.ion-page',
+    'ion-header',
+    'ion-footer',
+    'ion-toolbar',
+    ...components.filter((component) => 'tracksMotion' in component && component.tracksMotion).map((component) => component.tag),
+].join(', ');
+export const isVerticalBarsCandidate = isVerticalBarsSource;
+export const readCandidate = (element, id, options = {}) => {
+    const verticalBars = isVerticalBarsCandidate(element);
+    if ((!element.classList.contains('ios') && !verticalBars) ||
+        !visible(element, verticalBars) ||
+        element.closest('ion-popover') ||
+        (element.closest('ion-modal') && !verticalBars))
+        return;
+    if (element.contains(element.ownerDocument.activeElement))
+        return;
+    // Read icon and control geometry before restoring prehide, which can collapse the toolbar.
+    return withoutPrehide(element, () => components.find((component) => component.tag === element.localName)?.read(element, id, options));
+};

package/dist/controls/components/ion-back-button.d.ts

@@ -0,0 +1,4 @@
+import type { VerticalControlAreaOptions } from '../definitions.js';
+import type { Candidate, Identify } from '../shared/candidate.js';
+export declare const tag = "ion-back-button";
+export declare const read: (element: HTMLElement, id: Identify, options?: VerticalControlAreaOptions) => Candidate | undefined;

package/dist/controls/components/ion-back-button.js

@@ -0,0 +1,16 @@
+import { horizontalSelected, inVerticalToolbarLayout } from '../shared/toolbar-options.js';
+import { createCandidate, appendItem } from '../shared/candidate.js';
+import { inFixedToolbar, isVerticalBarsSource } from '../shared/dom.js';
+export const tag = 'ion-back-button';
+export const read = (element, id, options = {}) => {
+    const button = element;
+    if ((inVerticalToolbarLayout(element) ? !isVerticalBarsSource(element) : !horizontalSelected(element, options)) ||
+        !button.shadowRoot ||
+        button.icon !== undefined ||
+        button.color !== undefined ||
+        (!isVerticalBarsSource(element) && !inFixedToolbar(element)))
+        return;
+    const candidate = createCandidate(element, tag, id);
+    const label = button.shadowRoot.querySelector('[part="text"]')?.textContent?.trim() ?? '';
+    return appendItem(candidate, element, id, button.shadowRoot, label) ? candidate : undefined;
+};

package/dist/controls/components/ion-button.d.ts

@@ -0,0 +1,4 @@
+import type { VerticalControlAreaOptions } from '../definitions.js';
+import type { Candidate, Identify } from '../shared/candidate.js';
+export declare const tag = "ion-button";
+export declare const read: (element: HTMLElement, id: Identify, options?: VerticalControlAreaOptions) => Candidate | undefined;

package/dist/controls/components/ion-button.js

@@ -0,0 +1,26 @@
+import { horizontalSelected, horizontalToolbarGroup, inVerticalToolbarLayout } from '../shared/toolbar-options.js';
+import { createCandidate, appendItem } from '../shared/candidate.js';
+import { inFixedToolbar, isVerticalBarsToolbarAction, isVerticalBarsToolbarGroup } from '../shared/dom.js';
+export const tag = 'ion-button';
+export const read = (element, id, options = {}) => {
+    const button = element;
+    const verticalBars = inVerticalToolbarLayout(element);
+    if (verticalBars && element.parentElement && isVerticalBarsToolbarGroup(element.parentElement))
+        return;
+    const fill = button.fill ?? 'default';
+    const group = element.parentElement?.matches('ion-buttons') ? element.parentElement : undefined;
+    if (!verticalBars && (!horizontalSelected(element, options) || (group && horizontalToolbarGroup(group, options))))
+        return;
+    if (!inFixedToolbar(element) ||
+        (verticalBars && !isVerticalBarsToolbarAction(element)) ||
+        (!verticalBars && fill !== 'default' && !(group && fill === 'clear')) ||
+        (!verticalBars && button.classList.contains('ion-color')))
+        return;
+    const candidate = createCandidate(element, tag, id, options);
+    const item = appendItem(candidate, element, id);
+    if (!item)
+        return;
+    if (!verticalBars && (fill === 'clear' || (group && button.fill === undefined)))
+        item.buttonFill = 'clear';
+    return candidate;
+};