@rdlabo/ionic-theme-ios27 0.1.0-beta.pr175.sha00bf1efcf4b7 → 0.1.0-beta.pr177.shaea4b7eeec994

package/dist/native/definitions.d.ts

@@ -7,10 +7,24 @@ export interface NativeUIShellStatus {
     updates: number;
     reason?: string;
 }
+export interface NativeUIShellOptions {
+    enabled?: boolean;
+    controls?: NativeUIShellControls;
+}
+export interface NativeUIShellControls {
+    tabs?: boolean;
+    toolbar?: boolean;
+    segment?: boolean;
+    fab?: boolean;
+}
 export interface NativeUIShellHandle {
     getStatus(): NativeUIShellStatus;
+    suspend(): Promise<NativeUIShellSuspension>;
     destroy(): Promise<void>;
 }
+export interface NativeUIShellSuspension {
+    resume(): Promise<void>;
+}
 export interface Frame {
     x: number;
     y: number;
@@ -89,10 +103,14 @@ export interface ShellActivation {
     id: string;
     sequence: number;
 }
+export interface WebViewMetrics {
+    radius: number;
+}
 export interface NativeUIShellPlugin {
     configure(): Promise<{
         supported: boolean;
     }>;
+    getWebViewMetrics(): Promise<WebViewMetrics>;
     update(snapshot: ShellSnapshot): Promise<{
         revision: number;
         rejectedSearches?: string[];
@@ -103,5 +121,6 @@ export interface NativeUIShellPlugin {
     }): Promise<void>;
     addListener(name: 'activate', listener: (event: ShellActivation) => void): Promise<PluginListenerHandle>;
     addListener(name: 'search', listener: (event: ShellSearchEvent) => void): Promise<PluginListenerHandle>;
+    addListener(name: 'webViewMetricsChange', listener: (event: WebViewMetrics) => void): Promise<PluginListenerHandle>;
 }
 //# sourceMappingURL=definitions.d.ts.map

package/dist/native/definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/native/definitions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/native/definitions.ts"],"names":[],"mappings":"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"}

package/dist/native/index.d.ts

@@ -1,4 +1,5 @@
-import type { NativeUIShellHandle } from './definitions';
-export type { NativeUIShellComponent, NativeUIShellHandle, NativeUIShellStatus } from './definitions';
-export declare const enableNativeUIShell: () => Promise<NativeUIShellHandle>;
+import type { NativeUIShellHandle, NativeUIShellOptions, WebViewMetrics } from './definitions';
+export type { NativeUIShellComponent, NativeUIShellControls, NativeUIShellHandle, NativeUIShellOptions, NativeUIShellStatus, NativeUIShellSuspension, WebViewMetrics, } from './definitions';
+export declare const configureNativeTransition: () => Promise<WebViewMetrics>;
+export declare const enableNativeUIShell: (options?: NativeUIShellOptions) => Promise<NativeUIShellHandle>;
 //# sourceMappingURL=index.d.ts.map

package/dist/native/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/native/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAuB,MAAM,eAAe,CAAC;AAE9E,YAAY,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAUtG,eAAO,MAAM,mBAAmB,QAAO,OAAO,CAAC,mBAAmB,CAqBjE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/native/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAuB,cAAc,EAAE,MAAM,eAAe,CAAC;AAGpH,YAAY,EACV,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,cAAc,GACf,MAAM,eAAe,CAAC;AAWvB,eAAO,MAAM,yBAAyB,QAAa,OAAO,CAAC,cAAc,CAIxE,CAAC;AAGF,eAAO,MAAM,mBAAmB,GAAI,UAAS,oBAAyB,KAAG,OAAO,CAAC,mBAAmB,CA8BnG,CAAC"}

package/dist/native/index.js

@@ -1,28 +1,41 @@
 import { Capacitor, registerPlugin } from '@capacitor/core';
+import { setConfig } from '../transition/ios.transition';
+import { bindMetricsLifecycle } from './lifecycle';
 import { createRuntime } from './runtime';
 const plugin = registerPlugin('IonicNativeUIShell');
 let active;
 const web = (reason) => ({
     getStatus: () => ({ state: 'web', projected: 0, updates: 0, reason }),
+    suspend: async () => ({ resume: async () => { } }),
     destroy: async () => { },
 });
-export const enableNativeUIShell = () => {
+export const configureNativeTransition = async () => {
+    const metrics = typeof document !== 'undefined' && Capacitor.getPlatform() === 'ios' ? await plugin.getWebViewMetrics() : { radius: 0 };
+    setConfig({ radius: metrics.radius });
+    return metrics;
+};
+export const enableNativeUIShell = (options = {}) => {
+    if (options.enabled === false) {
+        const current = active;
+        active = undefined;
+        return current
+            ? current.then(async (handle) => {
+                await handle.destroy();
+                return web('Disabled');
+            })
+            : Promise.resolve(web('Disabled'));
+    }
     if (typeof document === 'undefined' || Capacitor.getPlatform() !== 'ios')
         return Promise.resolve(web('Requires Capacitor iOS'));
     return (active ?? (active = (async () => {
         try {
+            await configureNativeTransition().catch(() => undefined);
             if (!(await plugin.configure()).supported) {
                 active = undefined;
                 return web('Requires iOS 26 or later');
             }
-            const runtime = await createRuntime(document, plugin);
-            return {
-                getStatus: runtime.getStatus,
-                async destroy() {
-                    await runtime.destroy();
-                    active = undefined;
-                },
-            };
+            const runtime = await createRuntime(document, plugin, options);
+            return await bindMetricsLifecycle(runtime, () => plugin.addListener('webViewMetricsChange', (metrics) => setConfig({ radius: metrics.radius })), () => (active = undefined));
         }
         catch (error) {
             active = undefined;

package/dist/native/lifecycle.d.ts

@@ -0,0 +1,4 @@
+import type { PluginListenerHandle } from '@capacitor/core';
+import type { NativeUIShellHandle } from './definitions';
+export declare const bindMetricsLifecycle: (runtime: NativeUIShellHandle, listen: () => Promise<PluginListenerHandle>, deactivate: () => void) => Promise<NativeUIShellHandle>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/native/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/native/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD,eAAO,MAAM,oBAAoB,GAC/B,SAAS,mBAAmB,EAC5B,QAAQ,MAAM,OAAO,CAAC,oBAAoB,CAAC,EAC3C,YAAY,MAAM,IAAI,KACrB,OAAO,CAAC,mBAAmB,CA8B7B,CAAC"}

package/dist/native/lifecycle.js

@@ -0,0 +1,34 @@
+export const bindMetricsLifecycle = async (runtime, listen, deactivate) => {
+    let listener;
+    try {
+        listener = await listen();
+    }
+    catch (error) {
+        await runtime.destroy();
+        throw error;
+    }
+    let destroying;
+    return {
+        getStatus: runtime.getStatus,
+        suspend: runtime.suspend,
+        destroy() {
+            return (destroying ?? (destroying = (async () => {
+                let removalError;
+                try {
+                    await listener.remove();
+                }
+                catch (error) {
+                    removalError = error;
+                }
+                try {
+                    await runtime.destroy();
+                }
+                finally {
+                    deactivate();
+                }
+                if (removalError)
+                    throw removalError;
+            })()));
+        },
+    };
+};

package/dist/native/runtime.d.ts

@@ -1,3 +1,3 @@
-import type { NativeUIShellHandle, NativeUIShellPlugin } from './definitions';
-export declare const createRuntime: (doc: Document, plugin: NativeUIShellPlugin) => Promise<NativeUIShellHandle>;
+import type { NativeUIShellHandle, NativeUIShellOptions, NativeUIShellPlugin } from './definitions';
+export declare const createRuntime: (doc: Document, plugin: NativeUIShellPlugin, options?: NativeUIShellOptions) => Promise<NativeUIShellHandle>;
 //# sourceMappingURL=runtime.d.ts.map

package/dist/native/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/native/runtime.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAkC,mBAAmB,EAAE,mBAAmB,EAAuB,MAAM,eAAe,CAAC;AAkBnI,eAAO,MAAM,aAAa,GAAU,KAAK,QAAQ,EAAE,QAAQ,mBAAmB,KAAG,OAAO,CAAC,mBAAmB,CA6c3G,CAAC"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/native/runtime.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAGV,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EAEpB,MAAM,eAAe,CAAC;AAkBvB,eAAO,MAAM,aAAa,GACxB,KAAK,QAAQ,EACb,QAAQ,mBAAmB,EAC3B,UAAS,oBAAyB,KACjC,OAAO,CAAC,mBAAmB,CA+e7B,CAAC"}

package/dist/native/runtime.js

@@ -12,7 +12,7 @@ const bounded = (promise) => new Promise((resolve, reject) => {
     const timer = setTimeout(() => reject(new Error('Native UI Shell bridge timed out')), 5000);
     promise.then(resolve, reject).finally(() => clearTimeout(timer));
 });
-export const createRuntime = async (doc, plugin) => {
+export const createRuntime = async (doc, plugin, options = {}) => {
     const win = doc.defaultView;
     const icons = createIconRenderer();
     const crossfade = createCrossfade(win);
@@ -22,6 +22,7 @@ export const createRuntime = async (doc, plugin) => {
     const suspended = new Set();
     const pages = new Set();
     const presented = new Set();
+    const manualSuspensions = new Set();
     const moving = new Map();
     const observed = new Set();
     const listeners = new AbortController();
@@ -44,6 +45,19 @@ export const createRuntime = async (doc, plugin) => {
     let listener;
     let searchListener;
     let waiters = [];
+    const control = (kind) => {
+        if (kind === 'ion-tab-bar')
+            return 'tabs';
+        if (kind === 'ion-segment')
+            return 'segment';
+        if (kind === 'ion-fab')
+            return 'fab';
+        return 'toolbar';
+    };
+    const controlEnabled = (candidate) => {
+        const controls = options.controls;
+        return controls === undefined || controls[control(candidate.control.kind)] === true;
+    };
     const id = (element) => {
         let value = ids.get(element);
         if (!value) {
@@ -87,6 +101,10 @@ export const createRuntime = async (doc, plugin) => {
     };
     const search = createSearchSupport(doc, id, schedule);
     const candidateSources = (candidate) => candidate.sources ?? [candidate.element];
+    const readEnabledCandidate = (element) => {
+        const candidate = readCandidate(element, id);
+        return candidate && controlEnabled(candidate) ? candidate : undefined;
+    };
     const flush = async () => {
         if (stopped)
             return;
@@ -106,7 +124,8 @@ export const createRuntime = async (doc, plugin) => {
         for (const element of presented)
             if (!element.isConnected)
                 presented.delete(element);
-        return (presented.size > 0 ||
+        return (manualSuspensions.size > 0 ||
+            presented.size > 0 ||
             Array.from(doc.querySelectorAll(overlays)).some((element) => element.presented || element.classList.contains('show-menu')));
     };
     const signature = (candidate) => JSON.stringify({ control: candidate.control, icons: candidate.icons.map(({ source }) => source) });
@@ -123,7 +142,7 @@ export const createRuntime = async (doc, plugin) => {
         return unprojected(sources.keys(), () => search
             .decorate(Array.from(doc.querySelectorAll(selector))
             .filter((element) => !blocked(element))
-            .map((element) => readCandidate(element, id))
+            .map(readEnabledCandidate)
             .filter((candidate) => !!candidate), blocked)
             .filter((candidate) => !rejected.has(candidate.element) || rejected.get(candidate.element) !== signature(candidate)));
     };
@@ -366,6 +385,25 @@ export const createRuntime = async (doc, plugin) => {
             updates,
             reason,
         }),
+        async suspend() {
+            const token = Symbol();
+            let resumed = false;
+            if (!stopped) {
+                manualSuspensions.add(token);
+                getNativeSearchBindings(doc).forEach((binding) => search.retire(binding));
+                await flush();
+            }
+            return {
+                async resume() {
+                    if (resumed)
+                        return;
+                    resumed = true;
+                    if (stopped || !manualSuspensions.delete(token))
+                        return;
+                    await flush();
+                },
+            };
+        },
         async destroy() {
             if (stopped)
                 return;
@@ -392,6 +430,7 @@ export const createRuntime = async (doc, plugin) => {
             icons.clear();
             pages.clear();
             presented.clear();
+            manualSuspensions.clear();
             moving.clear();
             suspended.clear();
             await listener?.remove().catch(() => { });
@@ -418,7 +457,7 @@ export const createRuntime = async (doc, plugin) => {
         const owner = Array.from(sources.keys()).find((source) => source === element || source.contains(element));
         if (!owner)
             return;
-        const direct = !blocked(owner) && unprojected(sources.keys(), () => readCandidate(owner, id));
+        const direct = !blocked(owner) && unprojected(sources.keys(), () => readEnabledCandidate(owner));
         const candidate = direct || read().find((candidate) => candidate.actions.has(event.id));
         const item = candidate?.control.items.find((item) => item.id === event.id);
         const searchAction = candidate?.control.search && [candidate.control.search.trigger.id, candidate.control.search.closeId].includes(event.id);

package/docs/native-ui-shell.md

@@ -24,6 +24,14 @@ import { enableNativeUIShell } from '@rdlabo/ionic-theme-ios27/native';
 void enableNativeUIShell();
 ```
 
+`enableNativeUIShell()` also reads the WebView's effective top-left corner radius and applies it to page transitions. To configure only the transition without enabling native controls, call:
+
+```ts
+import { configureNativeTransition } from '@rdlabo/ionic-theme-ios27/native';
+
+await configureNativeTransition();
+```
+
 Keep the existing `navAnimation: iosTransitionAnimation` setting. No per-page registration, component list, native callback, or Swift view controller is required. Run `npx cap sync ios` after installing or updating the package. The native plugin uses Swift Package Manager (SPM). For an existing CocoaPods app, run `npx cap spm-migration-assistant` and link the generated `CapApp-SPM` package to the app target in Xcode. Build with Xcode 26 or later and Capacitor 8; native glass requires iOS 26 or later. Web, Android, SSR and older iOS keep the Web implementation.
 
 This is an opt-in feature. The ordinary package entry point does not import Capacitor, and `@capacitor/core` is an optional peer dependency. Native sources are still detected and built by Capacitor's sync when this package is installed in a Capacitor project, even if the application does not call `enableNativeUIShell()`.
@@ -122,8 +130,113 @@ console.log(shell.getStatus()); // state, projected control count, update count,
 await shell.destroy(); // restore DOM, remove native controls and release listeners/cache
 ```
 
+Projection is globally enabled by default. Limit it to selected Ionic components when an application only wants part of the native shell, or disable it globally while retaining the same configuration path:
+
+```ts
+const shell = await enableNativeUIShell({
+  enabled: true,
+  controls: {
+    tabs: true,
+  },
+});
+
+// Equivalent to leaving Native UI Shell off; all controls remain on the Web.
+const disabledShell = await enableNativeUIShell({ enabled: false });
+```
+
+Omitting `controls` enables every supported control for backward compatibility. When `controls` is present, only entries set to `true` are native-eligible. Available entries are `tabs`, `toolbar`, `segment`, and `fab`.
+
+For a custom modal or overlay that Native UI Shell cannot detect, acquire a suspension before presenting it. The resolved suspension means projected controls have returned to Web rendering. Always release it after dismissal:
+
+```ts
+const suspension = await shell.suspend();
+
+try {
+  await modal.present();
+  await modal.onDidDismiss();
+} finally {
+  await suspension.resume();
+}
+```
+
+Suspensions are nestable and `resume()` is idempotent. Native projection resumes only after every active suspension has been released, using the current DOM rather than a stale snapshot.
+
 The native material and control appearance follow the running iOS version; an iOS 26 device does not acquire iOS 27's appearance merely by installing this theme.
 
+## Native UI Shell API
+
+The generated reference below documents the handle returned by `enableNativeUIShell()`. The underlying Capacitor bridge and its control-snapshot protocol are implementation details.
+
+<docgen-index>
+
+* [`getStatus()`](#getstatus)
+* [`suspend()`](#suspend)
+* [`destroy()`](#destroy)
+* [Interfaces](#interfaces)
+
+</docgen-index>
+
+<docgen-api>
+<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+
+### getStatus()
+
+```typescript
+getStatus() => NativeUIShellStatus
+```
+
+Returns the current Web/native projection state.
+
+**Returns:** <code><a href="#nativeuishellstatus">NativeUIShellStatus</a></code>
+
+--------------------
+
+
+### suspend()
+
+```typescript
+suspend() => Promise<NativeUIShellSuspension>
+```
+
+Restores projected controls to the Web until the returned lease is resumed.
+
+**Returns:** <code>Promise&lt;<a href="#nativeuishellsuspension">NativeUIShellSuspension</a>&gt;</code>
+
+--------------------
+
+
+### destroy()
+
+```typescript
+destroy() => Promise<void>
+```
+
+Stops synchronization, restores Web controls and releases native resources.
+
+--------------------
+
+
+### Interfaces
+
+
+#### NativeUIShellStatus
+
+| Prop            | Type                                        |
+| --------------- | ------------------------------------------- |
+| **`state`**     | <code>'native' \| 'stopped' \| 'web'</code> |
+| **`projected`** | <code>number</code>                         |
+| **`updates`**   | <code>number</code>                         |
+| **`reason`**    | <code>string</code>                         |
+
+
+#### NativeUIShellSuspension
+
+| Method     | Signature                    | Description                                                                                    |
+| ---------- | ---------------------------- | ---------------------------------------------------------------------------------------------- |
+| **resume** | () =&gt; Promise&lt;void&gt; | Releases this suspension. Native projection resumes after all active suspensions are released. |
+
+</docgen-api>
+
 ## Source layout
 
 Each TypeScript module in [`src/native/components`](../src/native/components) declares its Ionic tag and DOM reader. `components/index.ts` combines those exports into discovery selectors and the component type. Shared DOM measurements, item data and SVG rendering live in `src/native/shared`; `runtime.ts` owns synchronization, visibility handoffs and lifecycle events.

package/ios/Sources/IonicNativeUIShellPlugin/IonicNativeUIShellPlugin.swift

@@ -8,6 +8,7 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
     public let jsName = "IonicNativeUIShell"
     public let pluginMethods: [CAPPluginMethod] = [
         CAPPluginMethod(name: "configure", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getWebViewMetrics", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "update", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "clear", returnType: CAPPluginReturnPromise)
     ]
@@ -45,6 +46,7 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
                     }
                 }
                 if keyboard { self.bridge?.triggerWindowJSEvent(eventName: "nativeUIShellRefresh") }
+                else if name == UIDevice.orientationDidChangeNotification { self.notifyWebViewMetricsChange() }
             })
         }
         for name in [UIApplication.didBecomeActiveNotification, UIResponder.keyboardDidHideNotification,
@@ -52,6 +54,7 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
             observers.append(NotificationCenter.default.addObserver(forName: name, object: nil, queue: .main) { [weak self] _ in
                 if name == UIResponder.keyboardDidHideNotification { self?.keyboardVisible = false }
                 self?.bridge?.triggerWindowJSEvent(eventName: "nativeUIShellRefresh", data: name == UIApplication.didBecomeActiveNotification ? "{\"retireSearch\":true}" : "{}")
+                if name == UIApplication.didBecomeActiveNotification { self?.notifyWebViewMetricsChange() }
             })
         }
     }
@@ -60,6 +63,31 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
         observers.forEach(NotificationCenter.default.removeObserver)
     }
 
+    private func webViewMetrics() -> JSObject? {
+        guard #available(iOS 26.0, *), let webView = bridge?.webView else { return nil }
+        webView.layoutIfNeeded()
+        return ["radius": Double(webView.effectiveRadius(corner: .topLeft))]
+    }
+
+    private func notifyWebViewMetricsChange() {
+        guard let metrics = webViewMetrics() else { return }
+        notifyListeners("webViewMetricsChange", data: metrics)
+    }
+
+    @objc func getWebViewMetrics(_ call: CAPPluginCall) {
+        DispatchQueue.main.async { [weak self] in
+            guard #available(iOS 26.0, *) else {
+                call.resolve(["radius": 0])
+                return
+            }
+            guard let metrics = self?.webViewMetrics() else {
+                call.reject("WebView unavailable")
+                return
+            }
+            call.resolve(metrics)
+        }
+    }
+
     @objc func configure(_ call: CAPPluginCall) {
         DispatchQueue.main.async { [weak self] in
             // A new JS context starts revision numbering again (live reload / navigation).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rdlabo/ionic-theme-ios27",
   "private": false,
-  "version": "0.1.0-beta.pr175.sha00bf1efcf4b7",
+  "version": "0.1.0-beta.pr177.shaea4b7eeec994",
   "description": "iOS27 Theme for Ionic Framework",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -27,9 +27,10 @@
     "Package.swift"
   ],
   "scripts": {
-    "build": "npm run build:css && npm run build:ts",
+    "build": "npm run docgen && npm run build:css && npm run build:ts",
     "build:css": "rm -rf dist/css && sass src/styles:dist/css --style=compressed --no-source-map --pkg-importer=node",
     "build:ts": "tsc",
+    "docgen": "docgen --project tsconfig.docgen.json --api NativeUIShellHandle --output-readme docs/native-ui-shell.md",
     "build:demo": "npm run build && cd demo && npm install && npm run build -- --configuration=production",
     "lint": "prettier --check \"./**/*.{scss,ts}\" &&  prettier --parser angular --check \"./**/*.html\"",
     "fmt": "prettier --write \"./**/*.{scss,ts}\" &&  prettier --parser angular --write \"./**/*.html\"",
@@ -59,6 +60,7 @@
   "devDependencies": {
     "@capacitor/core": "^8.5.2",
     "@ionic/angular": "^9.0.0",
+    "@rdlabo/capacitor-docgen": "^0.4.1",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.1",
     "np": "^10.2.0",

package/src/native/definitions.ts

@@ -10,11 +10,38 @@ export interface NativeUIShellStatus {
   reason?: string;
 }
 
+export interface NativeUIShellOptions {
+  /** Enables Native UI Shell globally. Defaults to `true`. */
+  enabled?: boolean;
+  /** Controls eligible for native projection. Omit to enable every control; when present, only `true` controls are enabled. */
+  controls?: NativeUIShellControls;
+}
+
+export interface NativeUIShellControls {
+  /** Projects tab bars and their native search presentation. */
+  tabs?: boolean;
+  /** Projects toolbar buttons, including back and menu buttons. */
+  toolbar?: boolean;
+  /** Projects segments. */
+  segment?: boolean;
+  /** Projects floating action buttons. */
+  fab?: boolean;
+}
+
 export interface NativeUIShellHandle {
+  /** Returns the current Web/native projection state. */
   getStatus(): NativeUIShellStatus;
+  /** Restores projected controls to the Web until the returned lease is resumed. */
+  suspend(): Promise<NativeUIShellSuspension>;
+  /** Stops synchronization, restores Web controls and releases native resources. */
   destroy(): Promise<void>;
 }
 
+export interface NativeUIShellSuspension {
+  /** Releases this suspension. Native projection resumes after all active suspensions are released. */
+  resume(): Promise<void>;
+}
+
 export interface Frame {
   x: number;
   y: number;
@@ -98,10 +125,17 @@ export interface ShellActivation {
   sequence: number;
 }
 
+export interface WebViewMetrics {
+  /** The WebView's effective top-left corner radius in points, or `0` when unavailable. */
+  radius: number;
+}
+
 export interface NativeUIShellPlugin {
   configure(): Promise<{ supported: boolean }>;
+  getWebViewMetrics(): Promise<WebViewMetrics>;
   update(snapshot: ShellSnapshot): Promise<{ revision: number; rejectedSearches?: string[]; rejectedControls?: string[] }>;
   clear(options: { revision: number }): Promise<void>;
   addListener(name: 'activate', listener: (event: ShellActivation) => void): Promise<PluginListenerHandle>;
   addListener(name: 'search', listener: (event: ShellSearchEvent) => void): Promise<PluginListenerHandle>;
+  addListener(name: 'webViewMetricsChange', listener: (event: WebViewMetrics) => void): Promise<PluginListenerHandle>;
 }

package/src/native/index.ts

@@ -1,32 +1,59 @@
 import { Capacitor, registerPlugin } from '@capacitor/core';
-import type { NativeUIShellHandle, NativeUIShellPlugin } from './definitions';
+import { setConfig } from '../transition/ios.transition';
+import type { NativeUIShellHandle, NativeUIShellOptions, NativeUIShellPlugin, WebViewMetrics } from './definitions';
+import { bindMetricsLifecycle } from './lifecycle';
 import { createRuntime } from './runtime';
-export type { NativeUIShellComponent, NativeUIShellHandle, NativeUIShellStatus } from './definitions';
+export type {
+  NativeUIShellComponent,
+  NativeUIShellControls,
+  NativeUIShellHandle,
+  NativeUIShellOptions,
+  NativeUIShellStatus,
+  NativeUIShellSuspension,
+  WebViewMetrics,
+} from './definitions';
 
 const plugin = registerPlugin<NativeUIShellPlugin>('IonicNativeUIShell');
 let active: Promise<NativeUIShellHandle> | undefined;
 const web = (reason: string): NativeUIShellHandle => ({
   getStatus: () => ({ state: 'web', projected: 0, updates: 0, reason }),
+  suspend: async () => ({ resume: async () => {} }),
   destroy: async () => {},
 });
 
+/** Reads the current native WebView geometry and applies it to page transitions. */
+export const configureNativeTransition = async (): Promise<WebViewMetrics> => {
+  const metrics = typeof document !== 'undefined' && Capacitor.getPlatform() === 'ios' ? await plugin.getWebViewMetrics() : { radius: 0 };
+  setConfig({ radius: metrics.radius });
+  return metrics;
+};
+
 /** Call once at application startup. Ionic markup remains the source of truth. */
-export const enableNativeUIShell = (): Promise<NativeUIShellHandle> => {
+export const enableNativeUIShell = (options: NativeUIShellOptions = {}): Promise<NativeUIShellHandle> => {
+  if (options.enabled === false) {
+    const current = active;
+    active = undefined;
+    return current
+      ? current.then(async (handle) => {
+          await handle.destroy();
+          return web('Disabled');
+        })
+      : Promise.resolve(web('Disabled'));
+  }
   if (typeof document === 'undefined' || Capacitor.getPlatform() !== 'ios') return Promise.resolve(web('Requires Capacitor iOS'));
   return (active ??= (async () => {
     try {
+      await configureNativeTransition().catch(() => undefined);
       if (!(await plugin.configure()).supported) {
         active = undefined;
         return web('Requires iOS 26 or later');
       }
-      const runtime = await createRuntime(document, plugin);
-      return {
-        getStatus: runtime.getStatus,
-        async destroy() {
-          await runtime.destroy();
-          active = undefined;
-        },
-      };
+      const runtime = await createRuntime(document, plugin, options);
+      return await bindMetricsLifecycle(
+        runtime,
+        () => plugin.addListener('webViewMetricsChange', (metrics) => setConfig({ radius: metrics.radius })),
+        () => (active = undefined),
+      );
     } catch (error) {
       active = undefined;
       return web(error instanceof Error ? error.message : String(error));

package/src/native/lifecycle.ts

@@ -0,0 +1,38 @@
+import type { PluginListenerHandle } from '@capacitor/core';
+import type { NativeUIShellHandle } from './definitions';
+
+export const bindMetricsLifecycle = async (
+  runtime: NativeUIShellHandle,
+  listen: () => Promise<PluginListenerHandle>,
+  deactivate: () => void,
+): Promise<NativeUIShellHandle> => {
+  let listener: PluginListenerHandle;
+  try {
+    listener = await listen();
+  } catch (error) {
+    await runtime.destroy();
+    throw error;
+  }
+
+  let destroying: Promise<void> | undefined;
+  return {
+    getStatus: runtime.getStatus,
+    suspend: runtime.suspend,
+    destroy() {
+      return (destroying ??= (async () => {
+        let removalError: unknown;
+        try {
+          await listener.remove();
+        } catch (error) {
+          removalError = error;
+        }
+        try {
+          await runtime.destroy();
+        } finally {
+          deactivate();
+        }
+        if (removalError) throw removalError;
+      })());
+    },
+  };
+};

package/src/native/runtime.ts

@@ -2,7 +2,14 @@ import type { PluginListenerHandle } from '@capacitor/core';
 import { LIFECYCLE_WILL_ENTER, LIFECYCLE_WILL_LEAVE, LIFECYCLE_DID_ENTER, LIFECYCLE_DID_LEAVE } from '@ionic/core';
 import { getNativeSearchBindings, setNativeUIShellIntegration } from '../native-integration';
 import { createSearchSupport } from './components/searchable-tabs';
-import type { ShellActivation, ShellSnapshot, NativeUIShellHandle, NativeUIShellPlugin, NativeUIShellStatus } from './definitions';
+import type {
+  ShellActivation,
+  ShellSnapshot,
+  NativeUIShellHandle,
+  NativeUIShellOptions,
+  NativeUIShellPlugin,
+  NativeUIShellStatus,
+} from './definitions';
 import { readCandidate, selector, shadowSelector, motionSelector } from './components';
 import { marker, unprojected } from './shared/dom';
 import { createIconRenderer } from './shared/icons';
@@ -20,7 +27,11 @@ const bounded = <T>(promise: Promise<T>): Promise<T> =>
     promise.then(resolve, reject).finally(() => clearTimeout(timer));
   });
 
-export const createRuntime = async (doc: Document, plugin: NativeUIShellPlugin): Promise<NativeUIShellHandle> => {
+export const createRuntime = async (
+  doc: Document,
+  plugin: NativeUIShellPlugin,
+  options: NativeUIShellOptions = {},
+): Promise<NativeUIShellHandle> => {
   const win = doc.defaultView!;
   const icons = createIconRenderer();
   const crossfade = createCrossfade(win);
@@ -30,6 +41,7 @@ export const createRuntime = async (doc: Document, plugin: NativeUIShellPlugin):
   const suspended = new Set<HTMLElement[]>();
   const pages = new Set<HTMLElement>();
   const presented = new Set<HTMLElement>();
+  const manualSuspensions = new Set<symbol>();
   const moving = new Map<HTMLElement, Set<string>>();
   const observed = new Set<Element | ShadowRoot>();
   const listeners = new AbortController();
@@ -52,6 +64,16 @@ export const createRuntime = async (doc: Document, plugin: NativeUIShellPlugin):
   let listener: PluginListenerHandle | undefined;
   let searchListener: PluginListenerHandle | undefined;
   let waiters: (() => void)[] = [];
+  const control = (kind: Candidate['control']['kind']): keyof NonNullable<NativeUIShellOptions['controls']> => {
+    if (kind === 'ion-tab-bar') return 'tabs';
+    if (kind === 'ion-segment') return 'segment';
+    if (kind === 'ion-fab') return 'fab';
+    return 'toolbar';
+  };
+  const controlEnabled = (candidate: Candidate) => {
+    const controls = options.controls;
+    return controls === undefined || controls[control(candidate.control.kind)] === true;
+  };
   const id = (element: Element) => {
     let value = ids.get(element);
     if (!value) {
@@ -91,6 +113,10 @@ export const createRuntime = async (doc: Document, plugin: NativeUIShellPlugin):
   };
   const search = createSearchSupport(doc, id, schedule);
   const candidateSources = (candidate: Candidate) => candidate.sources ?? [candidate.element];
+  const readEnabledCandidate = (element: HTMLElement): Candidate | undefined => {
+    const candidate = readCandidate(element, id);
+    return candidate && controlEnabled(candidate) ? candidate : undefined;
+  };
   const flush = async () => {
     if (stopped) return;
     schedule();
@@ -108,6 +134,7 @@ export const createRuntime = async (doc: Document, plugin: NativeUIShellPlugin):
   const overlayOpen = () => {
     for (const element of presented) if (!element.isConnected) presented.delete(element);
     return (
+      manualSuspensions.size > 0 ||
       presented.size > 0 ||
       Array.from(doc.querySelectorAll(overlays)).some(
         (element) => (element as Element & { presented?: boolean }).presented || element.classList.contains('show-menu'),
@@ -128,7 +155,7 @@ export const createRuntime = async (doc: Document, plugin: NativeUIShellPlugin):
         .decorate(
           Array.from(doc.querySelectorAll<HTMLElement>(selector))
             .filter((element) => !blocked(element))
-            .map((element) => readCandidate(element, id))
+            .map(readEnabledCandidate)
             .filter((candidate): candidate is Candidate => !!candidate),
           blocked,
         )
@@ -375,6 +402,23 @@ export const createRuntime = async (doc: Document, plugin: NativeUIShellPlugin):
       updates,
       reason,
     }),
+    async suspend() {
+      const token = Symbol();
+      let resumed = false;
+      if (!stopped) {
+        manualSuspensions.add(token);
+        getNativeSearchBindings(doc).forEach((binding) => search.retire(binding));
+        await flush();
+      }
+      return {
+        async resume() {
+          if (resumed) return;
+          resumed = true;
+          if (stopped || !manualSuspensions.delete(token)) return;
+          await flush();
+        },
+      };
+    },
     async destroy() {
       if (stopped) return;
       stopped = true;
@@ -399,6 +443,7 @@ export const createRuntime = async (doc: Document, plugin: NativeUIShellPlugin):
       icons.clear();
       pages.clear();
       presented.clear();
+      manualSuspensions.clear();
       moving.clear();
       suspended.clear();
       await listener?.remove().catch(() => {});
@@ -427,7 +472,7 @@ export const createRuntime = async (doc: Document, plugin: NativeUIShellPlugin):
     if (!element) return;
     const owner = Array.from(sources.keys()).find((source) => source === element || source.contains(element));
     if (!owner) return;
-    const direct = !blocked(owner) && unprojected(sources.keys(), () => readCandidate(owner, id));
+    const direct = !blocked(owner) && unprojected(sources.keys(), () => readEnabledCandidate(owner));
     const candidate = direct || read().find((candidate) => candidate.actions.has(event.id));
     const item = candidate?.control.items.find((item) => item.id === event.id);
     const searchAction =