@rdlabo/ionic-theme-ios27 1.2.0-0 → 1.2.0-beta.pr225.sha520dc52f7232

package/README.md

@@ -123,9 +123,9 @@ Use this markup to preview the inset grouped list look. For the list structure t
 
 ### Support iPhone Duo without the iOS 27 theme (experimental)
 
-iPhone Duo support is experimental. It is planned for release alongside Native UI Shell. Its APIs and supported behavior may change.
+Keep your existing Ionic theme and move tabs and supported toolbar actions into a vertical side area. **Start in Chrome** with one stylesheet, an app class, and `enableVerticalControlArea()`; then connect the layout to iPhone Duo device events for the system rail and hinge posture.
 
-Import only `@rdlabo/ionic-theme-ios27/dist/css/vertical-bars.css`, add `ios-theme-vertical-bars` to `ion-app`, and call `enableVerticalControlArea()` from `@rdlabo/ionic-theme-ios27/vertical-bars` at startup. This uses Ionic's standard appearance outside the Vertical Control Area; on supported iOS, only controls moved into that area are projected natively. To read only the hinge posture — for example to adapt an `ion-split-pane` — subscribe to the plugin's `deviceLayoutChange` event without starting any runtime. iOS enables the real system rail only for apps built with Xcode 27.1 or later; older toolchains run in compatibility mode and keep the DOM-driven rail instead. See [iPhone Duo support](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo) for the complete setup.
+Follow [iPhone Duo with your existing theme](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-theme) for the browser preview and iOS setup. For shared layout rules and APIs, see [iPhone Duo support](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo). Available in `1.2.0-0` as an experimental feature; APIs and supported behavior may change.
 
 ### Use only the iOS 27 theme
 
@@ -214,6 +214,7 @@ For Ionic 9 Angular, import `isPlatform` and `provideIonicAngular` from `@ionic/
 - [Features](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/features) — CSS variables, Liquid Glass, selective imports, and dark mode.
 - [Native UI Shell (Experimental)](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/native-ui-shell) — project supported Ionic controls, text, and icons into UIKit.
 - [iPhone Duo support (experimental)](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo) — vertical system rail, hinge posture, and split-pane layout; usable without the theme or the shell.
+- [iPhone Duo with your existing theme (experimental)](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-theme) — standalone setup that keeps your existing Web theme.
 - [Animation](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/animation) — tab, segment, and searchable effects.
 - [Migration from iOS 26](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/migration) — upgrade an existing app, including stylesheet, class, and CSS variable changes.
 - [iOS 26 migration history](https://docs.rdlabo.dev/projects/ionic-theme-ios26/docs/migration) — earlier major-version changes for the previous package.

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { iosPopoverEnterAnimation as popoverEnterAnimation, iosPopoverLeaveAnima
 export * from './tab-bar-searchable';
 export * from './searchbar';
 export * from './transition/ios.transition';
+export { withNativeUIShellTransition } from './native-integration/transition';
 export { registerSegmentEffect } from './segment';
 export declare const registerTabBarEffect: (targetElement: HTMLElement) => registeredEffect | undefined;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAEhE,cAAc,8BAA8B,CAAC;AAC7C,OAAO,EACL,wBAAwB,IAAI,qBAAqB,EACjD,wBAAwB,IAAI,qBAAqB,GAClD,MAAM,2BAA2B,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC;AAC5B,cAAc,6BAA6B,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAElD,eAAO,MAAM,oBAAoB,GAAI,eAAe,WAAW,KAAG,gBAAgB,GAAG,SAgCpF,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAEhE,cAAc,8BAA8B,CAAC;AAC7C,OAAO,EACL,wBAAwB,IAAI,qBAAqB,EACjD,wBAAwB,IAAI,qBAAqB,GAClD,MAAM,2BAA2B,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC;AAC5B,cAAc,6BAA6B,CAAC;AAC5C,OAAO,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAElD,eAAO,MAAM,oBAAoB,GAAI,eAAe,WAAW,KAAG,gBAAgB,GAAG,SAgCpF,CAAC"}

package/dist/index.js

@@ -4,6 +4,7 @@ export { iosPopoverEnterAnimation as popoverEnterAnimation, iosPopoverLeaveAnima
 export * from './tab-bar-searchable';
 export * from './searchbar';
 export * from './transition/ios.transition';
+export { withNativeUIShellTransition } from './native-integration/transition';
 export { registerSegmentEffect } from './segment';
 export const registerTabBarEffect = (targetElement) => {
     const win = targetElement.ownerDocument.defaultView;

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/native-integration/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,CAAC,QAAQ,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC,CAAC;IACtE,MAAM,CAAC,CAAC,OAAO,EAAE,mBAAmB,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3F;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;IACrB,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB;AAID,eAAO,MAAM,oBAAoB,GAAI,QAAQ,WAAW,EAAE,SAAS,WAAW,EAAE,QAAQ,WAAW,KAAG,mBAOrG,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAI,KAAK,QAAQ,KAAG,mBAAmB,EACR,CAAC;AAEpE,eAAO,MAAM,mBAAmB,GAAU,SAAS,mBAAmB,EAAE,QAAQ,OAAO,EAAE,QAAQ,OAAO,KAAG,OAAO,CAAC,OAAO,CAC3B,CAAC;AAGhG,eAAO,MAAM,iCAAiC,2CAA2C,CAAC;AAE1F,eAAO,MAAM,2BAA2B,GAAI,KAAK,QAAQ,EAAE,UAAU,wBAAwB,SAG5F,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,SAAS,WAAW,YAAiD,CAAC;AAEtG,eAAO,MAAM,oBAAoB,GAAU,QAAQ,WAAW,EAAE,KAAG,OAAO,CAAC,CAAC,QAAQ,CAAC,EAAE,OAAO,KAAK,IAAI,CACxB,CAAC;AAGhF,eAAO,MAAM,8BAA8B,GAAI,WAAW,SAAS,EAAE,UAAU,WAAW,EAAE,UAAU,WAAW,SAkEhH,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/native-integration/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,CAAC,QAAQ,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC,CAAC;IACtE,MAAM,CAAC,CAAC,OAAO,EAAE,mBAAmB,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3F;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;IACrB,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB;AAID,eAAO,MAAM,oBAAoB,GAAI,QAAQ,WAAW,EAAE,SAAS,WAAW,EAAE,QAAQ,WAAW,KAAG,mBAOrG,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAI,KAAK,QAAQ,KAAG,mBAAmB,EACR,CAAC;AAEpE,eAAO,MAAM,mBAAmB,GAAU,SAAS,mBAAmB,EAAE,QAAQ,OAAO,EAAE,QAAQ,OAAO,KAAG,OAAO,CAAC,OAAO,CAC3B,CAAC;AAGhG,eAAO,MAAM,iCAAiC,2CAA2C,CAAC;AAE1F,eAAO,MAAM,2BAA2B,GAAI,KAAK,QAAQ,EAAE,UAAU,wBAAwB,SAG5F,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,SAAS,WAAW,YAAiD,CAAC;AAEtG,eAAO,MAAM,oBAAoB,GAAU,QAAQ,WAAW,EAAE,KAAG,OAAO,CAAC,CAAC,QAAQ,CAAC,EAAE,OAAO,KAAK,IAAI,CACxB,CAAC;AAMhF,eAAO,MAAM,8BAA8B,GAAI,WAAW,SAAS,EAAE,UAAU,WAAW,EAAE,UAAU,WAAW,SAqEhH,CAAC"}

package/dist/native-integration/index.js

@@ -19,14 +19,19 @@ export const setNativeUIShellIntegration = (doc, runtime) => {
 };
 export const isNativeUIShell = (element) => element.hasAttribute('data-native-ui-shell');
 export const suspendNativeUIShell = async (scopes) => (await runtimes.get(scopes[0]?.ownerDocument)?.suspend(scopes)) ?? (() => { });
+const connectedTransitions = new WeakSet();
+const cancellationTransitions = new WeakSet();
 export const connectNativeUIShellTransition = (animation, entering, leaving) => {
-    if (leaving)
+    if (leaving && !cancellationTransitions.has(animation)) {
+        cancellationTransitions.add(animation);
         animation.onFinish((step) => {
             if (step === 0)
                 leaving.dispatchEvent(new CustomEvent(VERTICAL_BARS_TRANSITION_CANCELED, { bubbles: true, detail: { entering } }));
         });
-    if (!runtimes.has(entering.ownerDocument))
+    }
+    if (connectedTransitions.has(animation) || !runtimes.has(entering.ownerDocument))
         return;
+    connectedTransitions.add(animation);
     const scopes = leaving ? [entering, leaving] : [entering];
     const play = animation.play.bind(animation);
     const progressStart = animation.progressStart.bind(animation);

package/dist/native-integration/transition.d.ts

@@ -0,0 +1,3 @@
+import type { AnimationBuilder } from '@ionic/core';
+export declare const withNativeUIShellTransition: (builder: AnimationBuilder) => AnimationBuilder;
+//# sourceMappingURL=transition.d.ts.map

package/dist/native-integration/transition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition.d.ts","sourceRoot":"","sources":["../../src/native-integration/transition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAQpD,eAAO,MAAM,2BAA2B,GACrC,SAAS,gBAAgB,KAAG,gBAK5B,CAAC"}

package/dist/native-integration/transition.js

@@ -0,0 +1,7 @@
+import { connectNativeUIShellTransition } from './index';
+export const withNativeUIShellTransition = (builder) => (baseEl, opts) => {
+    const animation = builder(baseEl, opts);
+    if (opts?.enteringEl)
+        connectNativeUIShellTransition(animation, opts.enteringEl, opts.leavingEl);
+    return animation;
+};

package/dist/transition/ios.transition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ios.transition.d.ts","sourceRoot":"","sources":["../../src/transition/ios.transition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgC,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAIjD,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;CAChB;AAUD,eAAO,MAAM,SAAS,GAAI,QAAQ,OAAO,CAAC,mBAAmB,CAAC,KAAG,IAEhE,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,iBAAiB,KAAK,SACnB,CAAC"}
+{"version":3,"file":"ios.transition.d.ts","sourceRoot":"","sources":["../../src/transition/ios.transition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgC,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAIjD,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;CAChB;AASD,eAAO,MAAM,SAAS,GAAI,QAAQ,OAAO,CAAC,mBAAmB,CAAC,KAAG,IAEhE,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,iBAAiB,KAAK,SAErF,CAAC"}

package/dist/transition/ios.transition.js

@@ -1,15 +1,14 @@
 import { createIosTransitionAnimation, shadow } from '@rdlabo/ionic-theme-utils';
 import { getIonPageElement } from './index';
-import { connectNativeUIShellTransition } from '../native-integration';
+import { withNativeUIShellTransition } from '../native-integration/transition';
 export { shadow };
 const transitionConfig = {
     offLeftPercent: 30,
     getIonPageElement,
-    connectNativeUIShellTransition,
     shouldAnimateFixedBackButton: (navEl) => !navEl.closest('ion-app.ios-theme-vertical-bars'),
     radius: 0,
 };
 export const setConfig = (config) => {
     Object.assign(transitionConfig, config);
 };
-export const iosTransitionAnimation = createIosTransitionAnimation(transitionConfig);
+export const iosTransitionAnimation = withNativeUIShellTransition(createIosTransitionAnimation(transitionConfig));

package/dist/vertical-bars.d.ts

@@ -1,4 +1,5 @@
 export { enableVerticalControlArea, setVerticalControlAreaPlacement, IonicNativeUIShell } from './native';
 export { HingeStatus } from './native';
+export { withNativeUIShellTransition } from './native-integration/transition';
 export type { DeviceLayout, NativeUIShellStatus, NativeUIShellSuspension, VerticalBarEdge, VerticalControlAreaHandle } from './native';
 //# sourceMappingURL=vertical-bars.d.ts.map

package/dist/vertical-bars.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vertical-bars.d.ts","sourceRoot":"","sources":["../src/vertical-bars.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,+BAA+B,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC1G,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"vertical-bars.d.ts","sourceRoot":"","sources":["../src/vertical-bars.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,+BAA+B,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC1G,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC;AAC9E,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC"}

package/dist/vertical-bars.js

@@ -1,2 +1,3 @@
 export { enableVerticalControlArea, setVerticalControlAreaPlacement, IonicNativeUIShell } from './native';
 export { HingeStatus } from './native';
+export { withNativeUIShellTransition } from './native-integration/transition';

package/docs/iphone-duo-with-original-theme.md

@@ -0,0 +1,149 @@
+---
+title: iPhone Duo with your existing theme (experimental)
+---
+
+# iPhone Duo with your existing theme (experimental)
+
+Add a vertical navigation area to your Ionic app while keeping its existing theme. Tabs and supported toolbar actions move to the side of the screen; your content and horizontal controls keep their current appearance. Both Ionic `ios` and `md` modes are supported.
+
+**Try it in Chrome first.** You can preview the layout with Web controls before setting up an iPhone Duo or an iOS build. On supported Capacitor iOS, the same Ionic markup supplies native SwiftUI controls in the system rail.
+
+Available in `1.2.0-0` as an **experimental** feature. APIs and supported behavior may change.
+
+## Try it in your existing Ionic app
+
+### 1. Install and load the standalone stylesheet
+
+This guide assumes an existing Ionic app with Ionic `>=8.8.1 <10` and Capacitor Core `>=8 <9`. Keep your existing Capacitor 8 installation. If your app uses another Capacitor major, migrate its Core, CLI, and platform packages together before following this guide. For a Web-only app without Capacitor, also install `@capacitor/core@^8`; the JavaScript entry point needs it even in Chrome.
+
+```bash
+npm install @rdlabo/ionic-theme-ios27@1.2.0-0
+```
+
+Keep your existing theme imports. Add this to your global Sass file:
+
+```scss
+@use '@rdlabo/ionic-theme-ios27/dist/css/vertical-bars.css';
+```
+
+The standalone JavaScript entry point needs `@capacitor/core` even in Chrome. The iOS 27 theme stylesheets are not required.
+
+### 2. Opt your app into the side layout
+
+Add the class to your existing app root and keep the content inside it:
+
+```html
+<ion-app class="ios-theme-vertical-bars">
+  <!-- Keep your existing pages, tabs, and toolbar controls here. -->
+</ion-app>
+```
+
+The preview reserves `80px` on the physical right. To preview the left side, also add `ios-theme-vertical-bars-left`.
+
+### 3. Connect your navigation animation
+
+Configure `navAnimation` before Ionic initializes. Starting the rail runtime does not register this option. The adapter waits for native control retirement and coordinates swipe progress and cancellation while keeping your existing animation.
+
+#### Keep Ionic's default animation
+
+If you have not configured `navAnimation`, wrap Ionic's standard builders. Select the builder from Ionic's transition `mode` so both `ios` and `md` keep their usual animation:
+
+```ts
+import { iosTransitionAnimation, mdTransitionAnimation, type AnimationBuilder } from '@ionic/core';
+import { withNativeUIShellTransition } from '@rdlabo/ionic-theme-ios27/vertical-bars';
+
+const defaultTransition: AnimationBuilder = (baseEl, opts) =>
+  (opts.mode === 'ios' ? iosTransitionAnimation : mdTransitionAnimation)(baseEl, opts);
+
+const ionicConfig = {
+  navAnimation: withNativeUIShellTransition(defaultTransition),
+};
+```
+
+Merge this option into your existing Ionic configuration before initialization: pass it to Angular's `provideIonicAngular()`, React's `setupIonicReact()`, or Vue's `IonicVue` plugin options. Keep your existing theme stylesheet imports. No iOS 27 theme stylesheet is required.
+
+#### Keep your custom animation
+
+If your app already configures `navAnimation`, wrap that builder instead:
+
+```ts
+import type { AnimationBuilder } from '@ionic/core';
+import { withNativeUIShellTransition } from '@rdlabo/ionic-theme-ios27/vertical-bars';
+
+// Pass the animation builder your app already uses.
+const configureNavigation = (existingTransition: AnimationBuilder) => ({
+  navAnimation: withNativeUIShellTransition(existingTransition),
+});
+```
+
+The adapter returns the original `Animation`, preserving its effects, duration, and easing. Use it only for navigation, not modal or popover animations. The builder must return a fresh `Animation` for each navigation; Ionic destroys it after the transition. Keep lifecycle events for control registration and transitions without animation.
+
+The adapter keeps the builder's animation targets, including any horizontal back-button effect. If you need the iOS 27 transition with that effect excluded in vertical layouts, use `iosTransitionAnimation` from `@rdlabo/ionic-theme-ios27` as your `navAnimation` instead. It already includes the adapter, so no wrapper is needed.
+
+The adapter is available after `1.2.0-0`. With `1.2.0-0`, use the package's `iosTransitionAnimation` for iOS mode and keep your existing MD configuration.
+
+### 4. Start the controls after the app root is mounted
+
+Call this once from your application startup after `ion-app` exists in the DOM:
+
+```ts
+import { enableVerticalControlArea } from '@rdlabo/ionic-theme-ios27/vertical-bars';
+
+const rail = await enableVerticalControlArea();
+```
+
+**What you should see:** your existing tab bar moves to the side, and supported icon-based fixed-toolbar actions appear there too. Content keeps its existing theme and leaves room for the controls. The Web tab rail displays icons; pressing and dragging reveals tab labels.
+
+Use your existing Ionic click handlers and routing. Text-only toolbar actions remain horizontal. Add `.ios-theme-horizontal-only` to an `ion-buttons` group or individual `ion-button` to keep an action in the horizontal toolbar.
+
+When the application owner is disposed, call `await rail.destroy()` to restore the original controls and release the runtime. If you already use `enableNativeUIShell()`, keep that runtime and follow the [shared placement guide](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo#project-controls-into-the-rail).
+
+### If the preview does not appear
+
+| What you see | What to check |
+| --- | --- |
+| No space at the side | Load `vertical-bars.css` and put the class on `ion-app`. |
+| Space appears, but controls stay horizontal | Start `enableVerticalControlArea()` after mounting the app root. Use existing tabs or supported icon-based actions in a fixed toolbar. |
+| One action stays horizontal | Text-only actions, custom fills, and explicitly excluded controls keep their original presentation. See [control requirements](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo#project-controls-into-the-rail). |
+
+## Connect an iPhone Duo
+
+For Capacitor iOS, run `npx cap sync ios`. Build with Xcode 27.1 or newer and link against the iOS 27.1 SDK or later to receive the actual rail edge, safe-area inset, and hinge posture. The plugin uses Swift Package Manager; existing CocoaPods apps can follow [Native UI Shell setup](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/native-ui-shell#enable-the-shell).
+
+Replace the browser-only startup above with this after `ion-app` is mounted:
+
+```ts
+import { Capacitor, type PluginListenerHandle } from '@capacitor/core';
+import { enableVerticalControlArea, IonicNativeUIShell } from '@rdlabo/ionic-theme-ios27/vertical-bars';
+
+const rail = await enableVerticalControlArea();
+let layoutListener: PluginListenerHandle | undefined;
+
+if (Capacitor.getPlatform() === 'ios') {
+  // The runtime already monitors device layout; only subscribe.
+  layoutListener = await IonicNativeUIShell.addListener('deviceLayoutChange', ({ placement }) =>
+    rail.setPlacement(placement),
+  );
+  rail.setPlacement((await IonicNativeUIShell.getDeviceLayout()).placement);
+}
+
+// Call when the application owner is disposed.
+const stopVerticalArea = async () => {
+  await layoutListener?.remove();
+  await rail.destroy();
+};
+```
+
+`setPlacement()` applies the measured inset and resolves the logical edge through the document direction. A `null` edge restores the ordinary layout. Devices without a rail and apps built with older SDKs report `null`, so this example restores the ordinary layout there. To deliberately preview a DOM rail on such an iOS build, have your application choose a fixed edge with `rail.setPlacement('trailing')` instead of applying that null placement. This simulates the layout; it does not provide a real system rail or hinge measurements.
+
+On supported iOS, controls in the rail use the system SwiftUI appearance; your custom Web styling still applies to ordinary content and horizontal controls. Web and Android use Web clones.
+
+## Use hinge posture without projecting controls
+
+If your existing theme needs only a posture-driven split pane or a layout switch, do not start a projection runtime or add `.ios-theme-vertical-bars`. Use `getDeviceLayout()` and `deviceLayoutChange` directly, pairing `startDeviceLayoutMonitoring()` with `stopDeviceLayoutMonitoring()` and removing the listener when finished.
+
+See [Read the device layout](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo#read-the-device-layout) for the subscription example, null values, and monitoring lifetime. See [Adapt the split pane](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo#adapt-the-split-pane) for the opt-in width rules and half-open state.
+
+## Shared layout rules and API
+
+Safe-area handling, overlays, RTL, control eligibility, Web simulation, and the handle API are documented in [iPhone Duo support](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo). Those rules apply to this standalone setup too.

package/docs/iphone-duo.md

@@ -4,9 +4,11 @@ title: iPhone Duo support (experimental)
 
 # iPhone Duo support (experimental)
 
-iPhone Duo support is experimental, including the Vertical Control Area, device-layout reporting, and posture-driven split-pane layout. It is planned for release alongside [Native UI Shell](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/native-ui-shell). Its APIs and supported behavior may change.
+Adapt your Ionic app to iPhone Duo: place navigation and actions in its vertical system rail, and adjust your split pane as the device opens and closes. Existing Ionic markup remains the source of labels, icons, routing, and click handlers.
 
-iPhone Duo folds along a hinge and reserves a physical system rail on one side of the display. On iOS 27.1 and later, the system reports both facts to the app: the rail's edge with its safe-area inset, and the hinge posture while the device opens and closes.
+**New here?** Start with [iPhone Duo with your existing theme](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-theme) to preview the side layout in Chrome. This page explains device events, placement, split panes, and the API.
+
+Available in `1.2.0-0` as an **experimental** feature alongside [Native UI Shell](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/native-ui-shell). APIs and supported behavior may change. The real system rail and hinge reporting require iOS 27.1 or later and an app built with Xcode 27.1 or newer.
 
 This package provides three independent pieces for that hardware. Each works **without the iOS 27 theme stylesheets** and **without the full Native UI Shell**:
 
@@ -18,9 +20,12 @@ The pieces map to distinct responsibilities. The plugin reports **device facts**
 
 ## Choose what to adopt
 
+To keep your existing theme and add only the standalone support, follow [iPhone Duo with your existing theme](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-theme). This page covers the shared device-layout rules and API.
+
 | Goal                                             | Stylesheet          | Runtime                                                            |
 | ------------------------------------------------ | ------------------- | ------------------------------------------------------------------ |
-| Hinge posture only (split pane, layout switches) | `vertical-bars.css` | none — subscribe to the plugin directly                            |
+| Hinge posture only (layout switches) | none | none — subscribe to the plugin directly |
+| Posture-driven split-pane width | `vertical-bars.css` | none — subscribe to the plugin directly |
 | Vertical rail for tabs and toolbar actions       | `vertical-bars.css` | `enableVerticalControlArea()`                                      |
 | Native shell plus the rail                       | `vertical-bars.css` | `enableNativeUIShell()` — already includes rail and posture support |
 
@@ -91,17 +96,24 @@ The mode is component-mode independent: an app can keep Ionic `mode: 'md'` on iO
 Start the standalone runtime once at application startup:
 
 ```ts
-import { Capacitor } from '@capacitor/core';
+import { Capacitor, type PluginListenerHandle } from '@capacitor/core';
 import { enableVerticalControlArea, IonicNativeUIShell } from '@rdlabo/ionic-theme-ios27/vertical-bars';
 
 // Start on Chrome too; the Web projection stays idle until the class is present.
 const rail = await enableVerticalControlArea();
+let layoutListener: PluginListenerHandle | undefined;
 
 if (Capacitor.getPlatform() === 'ios') {
   // The runtime already monitors device layout; only subscribe.
-  await IonicNativeUIShell.addListener('deviceLayoutChange', ({ placement }) => rail.setPlacement(placement));
+  layoutListener = await IonicNativeUIShell.addListener('deviceLayoutChange', ({ placement }) => rail.setPlacement(placement));
   rail.setPlacement((await IonicNativeUIShell.getDeviceLayout()).placement);
 }
+
+// Call when the application owner is disposed.
+const stopVerticalArea = async () => {
+  await layoutListener?.remove();
+  await rail.destroy();
+};
 ```
 
 `setPlacement` on the handle and the exported `setVerticalControlAreaPlacement` are the same function; either applies the application's chosen placement to the CSS layout and both projections. It requires a mounted `ion-app` — call it after the app root exists.

package/docs/migration.md

@@ -4,6 +4,29 @@ title: Migration
 
 # Migration
 
+## Native UI Shell transition adapter
+
+Use `withNativeUIShellTransition()` to keep your existing Ionic navigation animation while coordinating Native UI Shell controls.
+
+- If you already use this package's `iosTransitionAnimation`, no configuration change is needed. It now uses the shared adapter internally; do not add another wrapper.
+- If you use Ionic's default animation without a `navAnimation` option, follow [Keep Ionic's default animation](./iphone-duo-with-original-theme.md#keep-ionics-default-animation). The example selects Ionic's standard iOS or MD builder from the transition mode.
+- If you use a custom navigation animation with Native UI Shell or the standalone Vertical Control Area, wrap your existing builder when configuring Ionic:
+
+```diff
++ import { withNativeUIShellTransition } from '@rdlabo/ionic-theme-ios27/vertical-bars';
+
+  const ionicConfig = {
+-   navAnimation: existingTransition,
++   navAnimation: withNativeUIShellTransition(existingTransition),
+  };
+```
+
+Merge this option into your existing Ionic configuration before initialization. The adapter preserves the animation's effects, duration, and easing while coordinating native retirement, swipe progress, and cancellation. Keep your existing theme stylesheet imports and Native UI Shell or Vertical Control Area startup.
+
+Use the adapter only for navigation; leave modal and popover animations unchanged. Your builder must create a fresh `Animation` for each navigation because Ionic destroys it afterward. Keep lifecycle events for control registration and transitions without animation. If the custom builder animates a horizontal back button separately, exclude that effect while `.ios-theme-vertical-bars` is active.
+
+See [Connect your navigation animation](./iphone-duo-with-original-theme.md#3-connect-your-navigation-animation) for the setup and supported scope.
+
 ## From the iOS 26 theme
 
 For an app using `@rdlabo/ionic-theme-ios26`, the recommended migration keeps that package and adds `@rdlabo/ionic-theme-ios27`. The [README setup](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/readme#get-started) selects iOS 27 or iOS 26 styles by browser capability and leaves Ionic's default iOS appearance on older browsers.

package/docs/native-ui-shell.md

@@ -116,7 +116,7 @@ FAB support covers the standard circular glass appearance, text and resolved sta
 
 Custom host animation or transition declarations on the FAB, list or button keep the group on the Web until removed. Button transforms support the standard identity and hidden-child scale(0), not custom scaling. For children inside a `display:none` list, browsers can report a computed transform of `none` even when a custom transform is declared. Such transforms are checked when layout becomes available; the whole FAB then returns to Web if needed. The plugin does not parse application stylesheets or temporarily open lists to predict hidden layout.
 
-The connection in `src/transition/ios.transition.ts` waits for native retirement before starting the Web animation. Interactive progress and completion/cancellation are queued while that retirement is in progress. Stationary shared tabs are retained. First render and transitions without an animation builder are covered by the startup runtime and Ionic lifecycle events.
+The built-in `iosTransitionAnimation` waits for native retirement before starting the Web animation. Interactive progress and completion/cancellation are queued while that retirement is in progress. Stationary shared tabs are retained. First render and transitions without an animation builder are covered by the startup runtime and Ionic lifecycle events. Default Ionic and custom navigation builders can use the same integration through `withNativeUIShellTransition()`, exported from both the package root and `/vertical-bars`. See [Connect your navigation animation](./iphone-duo-with-original-theme.md#3-connect-your-navigation-animation) for the setup.
 
 Tab switches skip the Web/native crossfade so a retiring UIKit snapshot cannot linger over the next tab. Detection uses the router URL versus the still-selected tab on `ionViewWillLeave` (and vanilla `ionTabsWillChange` / `ionTabsDidChange` DOM events). Stack pushes and pops keep the normal 180ms handoff.
 
@@ -169,7 +169,7 @@ The native material and control appearance follow the running iOS version; an iO
 
 ## Support iPhone Duo (experimental)
 
-iPhone Duo support is experimental, including standalone use without Native UI Shell. It is planned for release alongside Native UI Shell. Its APIs and supported behavior may change.
+iPhone Duo support is experimental, including standalone use without Native UI Shell. It is available in the `1.2.0-0` prerelease alongside Native UI Shell. Its APIs and supported behavior may change.
 
 The standalone Vertical Control Area entry point (`@rdlabo/ionic-theme-ios27/vertical-bars`) and `dist/css/vertical-bars.css` work without loading the iOS 27 theme. Call `enableVerticalControlArea()` for this use case; it projects only controls placed in the vertical area. Apps already calling `enableNativeUIShell()` should keep that single runtime rather than starting both. See [iPhone Duo support](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo) for the complete setup, including hinge posture and the split-pane layout for apps that do not use this shell at all.
 
@@ -179,6 +179,8 @@ The SwiftUI surface is clipped and hit-tested to the system rail. Web content re
 
 This mode accepts standard `fill="default"` and `fill="clear"` fixed-toolbar buttons because SwiftUI determines their compact representation. Solid, outline, custom-color, scrolling, and explicitly opted-out controls remain on the Web. Add `.ios-theme-horizontal-only` to an `ion-buttons` group or individual `ion-button` to keep it in the horizontal Web toolbar. On Web, Android, older iOS, or when native projection is unavailable during setup, the Web projection remains the fallback.
 
+For standalone setup while keeping your existing theme, see [iPhone Duo with your existing theme](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-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.

package/docs/special-markup.md

@@ -49,10 +49,12 @@ These classes do not reposition a separate `ion-fab`; leave room for it when cho
 
 ## Support iPhone Duo (experimental)
 
-iPhone Duo support is experimental. It is planned for release alongside Native UI Shell. Its APIs and supported behavior may change.
+iPhone Duo support is experimental. It is available in the `1.2.0-0` prerelease alongside Native UI Shell. Its APIs and supported behavior may change.
 
 iPhone Duo support — the vertical system rail, hinge posture, and the posture-driven split-pane layout — is independent of the iOS 27 theme and the full Native UI Shell. See [iPhone Duo support](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo) for the complete setup, including device-layout monitoring without a projection runtime.
 
+For standalone setup while keeping your existing theme, see [iPhone Duo with your existing theme](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-theme).
+
 ## Two-line inset list items
 
 Place an unslotted `ion-label` immediately alongside an unslotted `ion-note` to render a two-line item. When using the iOS-style inset-list background, wrap the items in `ion-item-group`; keep `ion-list-header` outside the group.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rdlabo/ionic-theme-ios27",
   "private": false,
-  "version": "1.2.0-0",
+  "version": "1.2.0-beta.pr225.sha520dc52f7232",
   "description": "iOS27 Theme for Ionic Framework",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/index.ts

@@ -8,6 +8,7 @@ export {
 export * from './tab-bar-searchable';
 export * from './searchbar';
 export * from './transition/ios.transition';
+export { withNativeUIShellTransition } from './native-integration/transition';
 export { registerSegmentEffect } from './segment';
 
 export const registerTabBarEffect = (targetElement: HTMLElement): registeredEffect | undefined => {

package/src/native-integration/index.ts

@@ -44,13 +44,19 @@ export const isNativeUIShell = (element: HTMLElement) => element.hasAttribute('d
 export const suspendNativeUIShell = async (scopes: HTMLElement[]): Promise<(canceled?: boolean) => void> =>
   (await runtimes.get(scopes[0]?.ownerDocument)?.suspend(scopes)) ?? (() => {});
 
+const connectedTransitions = new WeakSet<Animation>();
+const cancellationTransitions = new WeakSet<Animation>();
+
 /** Ionic write hooks cannot await the bridge. Gate playback, including interactive playback. */
 export const connectNativeUIShellTransition = (animation: Animation, entering: HTMLElement, leaving?: HTMLElement) => {
-  if (leaving)
+  if (leaving && !cancellationTransitions.has(animation)) {
+    cancellationTransitions.add(animation);
     animation.onFinish((step) => {
       if (step === 0) leaving.dispatchEvent(new CustomEvent(VERTICAL_BARS_TRANSITION_CANCELED, { bubbles: true, detail: { entering } }));
     });
-  if (!runtimes.has(entering.ownerDocument)) return;
+  }
+  if (connectedTransitions.has(animation) || !runtimes.has(entering.ownerDocument)) return;
+  connectedTransitions.add(animation);
   const scopes = leaving ? [entering, leaving] : [entering];
   const play = animation.play.bind(animation);
   const progressStart = animation.progressStart.bind(animation);

package/src/native-integration/transition.ts

@@ -0,0 +1,15 @@
+import type { AnimationBuilder } from '@ionic/core';
+import { connectNativeUIShellTransition } from './index';
+
+/**
+ * Keeps an existing Ionic navigation animation and coordinates native control handoff.
+ * Register the returned builder as navAnimation. Do not use it for overlay animations.
+ * The builder must return a fresh Animation for each navigation; Ionic destroys it afterward.
+ */
+export const withNativeUIShellTransition =
+  (builder: AnimationBuilder): AnimationBuilder =>
+  (baseEl, opts) => {
+    const animation = builder(baseEl, opts);
+    if (opts?.enteringEl) connectNativeUIShellTransition(animation, opts.enteringEl, opts.leavingEl);
+    return animation;
+  };

package/src/transition/ios.transition.ts

@@ -2,7 +2,7 @@ import { createIosTransitionAnimation, shadow } from '@rdlabo/ionic-theme-utils'
 import type { Animation } from '@ionic/core';
 import type { TransitionOptions } from './index';
 import { getIonPageElement } from './index';
-import { connectNativeUIShellTransition } from '../native-integration';
+import { withNativeUIShellTransition } from '../native-integration/transition';
 
 export { shadow };
 
@@ -13,7 +13,6 @@ export interface IosTransitionConfig {
 const transitionConfig = {
   offLeftPercent: 30,
   getIonPageElement,
-  connectNativeUIShellTransition,
   shouldAnimateFixedBackButton: (navEl: HTMLElement) => !navEl.closest('ion-app.ios-theme-vertical-bars'),
   radius: 0,
 };
@@ -22,5 +21,6 @@ export const setConfig = (config: Partial<IosTransitionConfig>): void => {
   Object.assign(transitionConfig, config);
 };
 
-export const iosTransitionAnimation: (navEl: HTMLElement, opts: TransitionOptions) => Animation =
-  createIosTransitionAnimation<TransitionOptions>(transitionConfig);
+export const iosTransitionAnimation: (navEl: HTMLElement, opts: TransitionOptions) => Animation = withNativeUIShellTransition(
+  createIosTransitionAnimation<TransitionOptions>(transitionConfig),
+);

package/src/vertical-bars.ts

@@ -1,3 +1,4 @@
 export { enableVerticalControlArea, setVerticalControlAreaPlacement, IonicNativeUIShell } from './native';
 export { HingeStatus } from './native';
+export { withNativeUIShellTransition } from './native-integration/transition';
 export type { DeviceLayout, NativeUIShellStatus, NativeUIShellSuspension, VerticalBarEdge, VerticalControlAreaHandle } from './native';