@rdlabo/capacitor-native-ui 1.2.1 → 2.0.0-1

package/docs/native-ui-extensions.md

@@ -6,10 +6,10 @@ title: App-local Native UI extensions (experimental)
 
 > **Experimental:** The extension API, native registration interfaces and behavior may change in future releases. This applies to both SwiftUI and Kotlin/Compose extensions, including `element` and `tab-accessory` placement.
 
-> This guide targets the upcoming package split. Until the first native package release, use the [candidate archive installation](../README.md#try-the-unreleased-packages) in place of registry install commands.
-
 An extension projects your existing Web UI into a SwiftUI View on iOS or Jetpack Compose content on Android. Keep both definitions in your application: no npm package, separate library, or Capacitor plugin is required. The Web element remains the source of truth and the fallback UI.
 
+Extensions use the same [projection model](../README.md#how-projection-works) as built-in controls. Define the DOM data and actions to expose, then provide their native presentation.
+
 ## Before you start
 
 Start with an existing Capacitor 8 app and install the plugin if you have not already:
@@ -63,9 +63,18 @@ source.querySelector('button')!.addEventListener('click', () => {
   source.querySelector('[data-count-label]')!.textContent = `Count: ${count}`;
 });
 ```
- The shell observes DOM changes and sends the new props to the native content. State rendered into DOM attributes or text is observed automatically. For properties or external state read by the reader that do not mutate the DOM, call `shell.markForCheck()` after changing them.
 
-The reader is synchronous and read-only. Return `null` when the source should stay on the Web. Props are a JSON object (finite numbers, strings, booleans, null, arrays and objects), limited to 64K characters. Action names map to the source itself or its descendants; missing, hidden and disabled targets cannot be activated. Up to 30 actions are supported per source.
+The shell observes DOM changes and sends the new props to the native content. State rendered into DOM attributes or text is observed automatically. For properties or external state read by the reader that do not mutate the DOM, call `shell.markForCheck()` after changing them.
+
+### Reader contract
+
+| Part           | Requirement                                                                                                    |
+| -------------- | -------------------------------------------------------------------------------------------------------------- |
+| Execution      | Synchronous and read-only.                                                                                     |
+| Web fallback   | Return `null` when the source should stay on the Web.                                                          |
+| `props`        | JSON object containing finite numbers, strings, booleans, null, arrays and objects; limited to 64K characters. |
+| Action targets | The source itself or its descendants. Missing, hidden and disabled targets cannot be activated.                |
+| Action count   | Up to 30 per source.                                                                                           |
 
 ## 2a. Register a SwiftUI View on iOS
 
@@ -221,14 +230,23 @@ For source-specific fallback reasons, temporarily enable [`debug: true`](configu
 
 ## Content and placement are independent
 
-| `placement` | Behavior |
-| --- | --- |
+| `placement`            | Behavior                                                                              |
+| ---------------------- | ------------------------------------------------------------------------------------- |
 | Omitted or `'element'` | Hosts native content in the source element's Web frame on iOS 26+ or Android API 24+. |
-| `'tab-accessory'` | Attaches the View to a projected tab bar's system SwiftUI tab accessory on iOS 26.1+. |
+| `'tab-accessory'`      | Attaches the View to a projected tab bar's system SwiftUI tab accessory on iOS 26.1+. |
+
+Extensions are independent of `controls` and `ionic.auto`, including with `enableVerticalControlArea()`. The application controls their presentation: return `null` from the reader when a source should stay on the Web, then call `markForCheck()` when that condition changes. Accessories still require their supported native tab host.
 
-For `tab-accessory`, place the source inside its owning `ion-tabs`. The shell resolves that tabs element's `ion-tab-bar`; applications do not pass native controller references. Currently only the **Vertical Bars SwiftUI tab host** supports this placement. Ordinary UIKit tab bars, missing native tabs, iOS 26.0, or multiple competing accessories keep the source on the Web. The shell does not approximate a system accessory with a floating overlay. Keep an equivalent Web layout (for example, a fixed footer); the source retains its layout space while hidden.
+### Tab accessory requirements
 
-`enableVerticalControlArea({ extensions: [...] })` also accepts extensions. In this standalone mode only accessories belonging to native Vertical Bars are eligible; ordinary element projections require `enableNativeUI`.
+| Requirement         | Supported configuration                                                                           |
+| ------------------- | ------------------------------------------------------------------------------------------------- |
+| Source location     | Inside its owning `ion-tabs`; the shell resolves that element's `ion-tab-bar`.                    |
+| Native host         | Vertical Bars SwiftUI tab host on iOS 26.1+.                                                      |
+| Accessory count     | A single accessory for the host.                                                                  |
+| Web fallback layout | Keep an equivalent Web layout, such as a fixed footer; the source retains its space while hidden. |
+
+Ordinary UIKit tab bars, missing native tabs, iOS 26.0 or competing accessories keep the source on the Web. Applications do not pass native controller references, and the shell does not approximate a system accessory with a floating overlay.
 
 ## Read source geometry and presentation state
 
@@ -246,16 +264,16 @@ try NativeUI.register("app.counter") {
 
 The existing `(props, actions)` closure remains supported. Both forms use the same registration names and duplicate-name checks.
 
-| Context property | Meaning |
-| --- | --- |
-| `sourceID` | Opaque source identity for its current lifetime; not the HTML `id`. |
-| `sourceFrame` | DOM `getBoundingClientRect()` in CSS pixels relative to the Web viewport, including `x`, `y`, `width`, and `height`. |
-| `sourceFrameInWebView` | The source rectangle converted to UIKit points in the WebView's local coordinate system; not screen coordinates. |
-| `viewportWidth` | CSS viewport width used for that snapshot's coordinate conversion. |
-| `pointsPerCSSPixel` | UIKit points per CSS pixel; not device pixel density. |
-| `placement` | `.element` or `.tabAccessory`. |
-| `colorScheme` | `.light` or `.dark`, also applied to the SwiftUI environment. |
-| `layoutDirection` | `.leftToRight` or `.rightToLeft`, also applied to the SwiftUI environment. |
+| Context property       | Meaning                                                                                                              |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `sourceID`             | Opaque source identity for its current lifetime; not the HTML `id`.                                                  |
+| `sourceFrame`          | DOM `getBoundingClientRect()` in CSS pixels relative to the Web viewport, including `x`, `y`, `width`, and `height`. |
+| `sourceFrameInWebView` | The source rectangle converted to UIKit points in the WebView's local coordinate system; not screen coordinates.     |
+| `viewportWidth`        | CSS viewport width used for that snapshot's coordinate conversion.                                                   |
+| `pointsPerCSSPixel`    | UIKit points per CSS pixel; not device pixel density.                                                                |
+| `placement`            | `.element` or `.tabAccessory`.                                                                                       |
+| `colorScheme`          | `.light` or `.dark`, also applied to the SwiftUI environment.                                                        |
+| `layoutDirection`      | `.leftToRight` or `.rightToLeft`, also applied to the SwiftUI environment.                                           |
 
 The closure receives a fresh context when the shell applies an updated snapshot, including source movement, resizing, and appearance changes. Use the current context rather than caching its geometry in `@State`. Updates cross the Web/native bridge; they are not a synchronous DOM measurement from Swift.
 
@@ -272,16 +290,16 @@ Do not apply `sourceFrame.x` or `y` as another SwiftUI offset: the shell already
 
 ## Use the shared projection capabilities
 
-| Capability | How an extension uses it |
-| --- | --- |
-| Position and size | Automatic host placement plus `NativeUIContext`; actual local bounds through `GeometryReader`. |
-| Dark mode and RTL | `context` or SwiftUI `@Environment(\.colorScheme)` and `@Environment(\.layoutDirection)`. |
-| Reduce Motion and accessibility | SwiftUI environment values such as `@Environment(\.accessibilityReduceMotion)` and native accessibility modifiers. Give custom controls accessible names. |
-| DOM-backed application state | Return JSON `props` from `read(element)`; DOM changes trigger synchronization. For changes without a DOM mutation, call `shell.markForCheck()`. |
-| Enabled/visible action targets | `actions.availableNames` or `actions.isAvailable("increment")`; unavailable DOM targets are omitted. |
-| Invoke the original Web action | `try await actions.activate("increment")`; completion and failure follow the contract below. |
-| Temporary Web fallback and teardown | Managed automatically for unsupported content, overlays, navigation suspension, and source removal. |
-| Application-controlled suspension | Use the shell handle's `suspend()`, the returned token's `resume()`, and `destroy()` from JavaScript. |
+| Capability                          | How an extension uses it                                                                                                                                  |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Position and size                   | Automatic host placement plus `NativeUIContext`; actual local bounds through `GeometryReader`.                                                            |
+| Dark mode and RTL                   | `context` or SwiftUI `@Environment(\.colorScheme)` and `@Environment(\.layoutDirection)`.                                                                 |
+| Reduce Motion and accessibility     | SwiftUI environment values such as `@Environment(\.accessibilityReduceMotion)` and native accessibility modifiers. Give custom controls accessible names. |
+| DOM-backed application state        | Return JSON `props` from `read(element)`; DOM changes trigger synchronization. For changes without a DOM mutation, call `shell.markForCheck()`.           |
+| Enabled/visible action targets      | `actions.availableNames` or `actions.isAvailable("increment")`; unavailable DOM targets are omitted.                                                      |
+| Invoke the original Web action      | `try await actions.activate("increment")`; completion and failure follow the contract below.                                                              |
+| Temporary Web fallback and teardown | Managed automatically for unsupported content, overlays, navigation suspension, and source removal.                                                       |
+| Application-controlled suspension   | Use the shell handle's `suspend()`, the returned token's `resume()`, and `destroy()` from JavaScript.                                                     |
 
 For example, disable a native button when its original action is unavailable:
 
@@ -358,8 +376,19 @@ The shell owns discovery, geometry, state synchronization, native controller con
 
 Element placement requires the source to fit fully inside the viewport and its ancestors' overflow clipping bounds, including Ionic's shadow scroll containers. Partially clipped sources stay on the Web and become eligible again when scrolled fully into view. Tab accessories use the system host's placement instead.
 
-`try await actions.activate(name)` completes after the original Web element receives its click. It does **not** wait for application work launched by the click handler (network requests, navigation or modal presentation). Disabled, removed or stale actions reject; teardown, native task cancellation and bridge timeouts settle pending calls. The bridge acknowledgement is a Capacitor Promise method.
+### Action completion
+
+| Event                                                              | Result of `try await actions.activate(name)` |
+| ------------------------------------------------------------------ | -------------------------------------------- |
+| Original Web element receives its click                            | Completes.                                   |
+| Handler starts a network request, navigation or modal presentation | Does not wait for that application work.     |
+| Action is disabled, removed or stale                               | Rejects.                                     |
+| Teardown, native task cancellation or bridge timeout               | Settles pending calls.                       |
+
+The bridge acknowledgement is a Capacitor Promise method.
 
 The [demo reader](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/demo/src/native-ui/counter.ts) and [demo SwiftUI View](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/demo/ios/App/App/NativeUICounter.swift) show both placements using app-local files. Open the Native UI demo page to compare native projection with its Web fallback.
 
-For a complete application feature, see the [SwiftUI mini-player example](native-mini-player.md): artwork, track metadata, playback controls and swipe-to-open, all defined in the demo application.
+## Example: mini-player
+
+The demo mini-player shows the same pattern with track metadata and playback actions: a [DOM reader and Web fallback](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/demo/src/native-ui/mini-player.ts) paired with an [app-local SwiftUI View](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/demo/ios/App/App/NativeMiniPlayer.swift). The Web app owns playback state and modal presentation; native `open` and `toggle` actions activate its original buttons. This is a UI example, not an audio engine. Adapt the files after completing the extension setup above.

package/docs/native-ui.md

@@ -2,15 +2,13 @@
 title: Native UI (Preview)
 ---
 
-For application-specific SwiftUI or Compose content, see [experimental App-local Native UI extensions](native-ui-extensions.md).
-
 # Native UI (Preview)
 
 Native UI is a **preview**. The earlier Native UI Shell was bundled with theme versions 1.2.0 and 1.2.1; this guide describes the split package and its renamed API. See [migration](migration.md#native-ui-naming-changes). Its API and supported controls may change before stable status. Stable status is planned after the official release of Xcode 27.1.
 
 Native UI gives an Ionic app native navigation and action controls around its Web content. The optional Capacitor iOS plugin renders supported fixed Ionic controls with UIKit or SwiftUI and the system's Liquid Glass material. Page content, scrolling, application state and routing remain in Ionic's WebView.
 
-Use this page as the supported-control and API reference. For first-time installation and a working example, start with [Ionic setup](setup.md) or [HTML setup](framework-independent.md).
+Read [how projection works](../README.md#how-projection-works) for the shared DOM and native presentation model. Use this page as the supported-control and API reference. For first-time installation and a working example, start with [Ionic setup](setup.md) or [HTML setup](framework-independent.md).
 
 ## Enable Native UI
 
@@ -39,54 +37,52 @@ import { configureNativeTransition } from '@rdlabo/capacitor-native-ui';
 await configureNativeTransition();
 ```
 
-If using the theme’s `iosTransitionAnimation`, keep that setting; it already coordinates native transitions. For Ionic default or custom animations, configure the [transition adapter](migration.md#native-ui-transition-adapter). 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 package supplies both Swift Package Manager (SPM) and CocoaPods integration. Keep your existing dependency manager when syncing. If you choose to migrate an existing CocoaPods app to SPM, 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.
+### Navigation and native builds
+
+| Setup                               | Action                                                                                                          |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Theme's `iosTransitionAnimation`    | Keep it; native transitions are already coordinated.                                                            |
+| Ionic default or custom animation   | Configure the [transition adapter](migration.md#native-ui-transition-adapter).                                  |
+| Plugin installed or updated         | Run `npx cap sync ios`, then rebuild the native app.                                                            |
+| SPM or CocoaPods                    | Keep the existing dependency manager; both are supported.                                                       |
+| Optional CocoaPods-to-SPM migration | Run `npx cap spm-migration-assistant`, then link the generated `CapApp-SPM` package to the app target in Xcode. |
+| Ordinary native glass               | Requires Xcode 26+, Capacitor 8 and iOS 26+.                                                                    |
+| Web, Android, SSR or older iOS      | Retain the Web implementation.                                                                                  |
+
+No per-page registration, component list, native callback or Swift view controller is required.
 
 This is an opt-in feature. The ordinary `@rdlabo/ionic-theme-ios27` theme entry point does not import Capacitor. Native runtime entry points require `@capacitor/core`, including in browser builds. Native sources are still detected and built by Capacitor's sync when `@rdlabo/capacitor-native-ui` is a direct dependency of a Capacitor project, even if the application does not call `enableNativeUI()`.
 
-Native appearance follows the applied class, system or always-dark theme CSS. System theme changes are synchronized while the runtime is active.
+Native light/dark appearance is resolved from each source element’s computed style. See [Light and dark appearance](appearance.md) for theme inheritance, priority, live updates and the shared Vertical Bars behavior.
 
 ## Toolbar selection and grouping
 
-Configure ordinary and vertical toolbars independently:
+Use `controls` to choose selection and grouping by placement:
 
 ```ts
 const shell = await enableNativeUI({
-  horizontal: { buttons: false, button: true, backButton: true },
-  vertical: { buttons: true, button: true, backButton: true },
+  controls: {
+    buttonGroup: 'verticalOnly',
+    button: true,
+    backButton: true,
+  },
 });
 ```
 
-Each layout accepts `boolean | ToolbarProjectionOptions`:
-
-| Value | Meaning |
-| --- | --- |
-| `true` or omitted | All three options default to `true`. |
-| `false` | All three options are `false`; local attributes may still opt in. |
-| Object | Set individual options; omitted fields default to `true`. |
-
-For toolbar actions that automatically project only in vertical layout:
-
-```ts
-const shell = await enableNativeUI({ horizontal: false, vertical: true });
-```
+Here, ordinary toolbar actions project individually and eligible rail actions can group. All six control fields accept `true`, `false`, `'horizontalOnly'`, or `'verticalOnly'`; omitted fields are `true`. For all automatic controls only in the rail, use `controls: 'verticalOnly'`. See [selection defaults](configuration.md#selection-defaults) for the complete table.
 
-This selects by active layout, not by the Duo model, and does not disable tabs,
-segments or FABs. These settings refine automatic Ionic toolbar projection;
-`ionic.auto` remains its master switch. Explicit `data-native-ui` sources are independent.
+`button` selects ordinary actions inside or outside a group, including menu buttons. `buttonGroup` only groups already selected actions. With `buttonGroup: true, button: false`, no ordinary action projects without explicit selection. `backButton` independently selects back navigation, including back buttons inside `ion-buttons`; back buttons never join ordinary groups.
 
-`button` selects ordinary actions whether grouped
-in the source or standalone; `buttons` only enables grouping of selected actions.
-With `buttons: true, button: false`, no ordinary action projects unless explicitly
-selected. `backButton` independently controls back navigation, including back
-buttons inside `ion-buttons`.
+`ionic.auto` enables or disables automatic Ionic discovery. Explicit `data-native-ui` sources and extensions remain independent of both `controls` and `ionic.auto`.
 
 Restart the runtime to change these startup options.
 
-Use `data-horizontal-bars="true|false"` for local horizontal overrides, and
-`data-vertical-bars="true|false"` for vertical overrides. Each attribute applies
-only in its corresponding layout. On a button/back button it controls selection;
-on `ion-buttons` it controls grouping only. Neither attribute is inherited.
-Invalid or empty values fall back to the matching startup option.
+| Attribute              | Applies in              | `true`                                                 | `false`                                                   |
+| ---------------------- | ----------------------- | ------------------------------------------------------ | --------------------------------------------------------- |
+| `data-horizontal-bars` | Ordinary placement      | Select the action, or allow grouping on `ion-buttons`. | Exclude the action, or disable grouping on `ion-buttons`. |
+| `data-vertical-bars`   | Vertical rail placement | Select the action, or allow grouping on `ion-buttons`. | Exclude the action, or disable grouping on `ion-buttons`. |
+
+On a button/back button these attributes control selection; on `ion-buttons` they control grouping only. Neither is inherited. Missing, invalid or empty values use the matching `controls` default. Vertical action opt-ins and their eligibility rules are detailed in [Vertical Bars](vertical-bars.md#explicit-action-selection-and-local-grouping).
 
 ```html
 <ion-buttons data-horizontal-bars="false" data-vertical-bars="true">
@@ -100,7 +96,7 @@ The vertical attribute allows grouping but does not select the text-only childre
 add `data-vertical-bars="true"` to each button to select them explicitly.
 
 These settings do not remove CSS or change the source layout. If the app removes
-the source group's glass styling, `horizontal.buttons: false` also prevents a
+the source group's glass styling, `controls: { buttonGroup: 'verticalOnly' }` also prevents a
 shared native group surface. Existing component-mode, fixed-toolbar,
 fill/color and shell opt-out requirements still apply. A horizontal clear button
 inside `ion-buttons` can project individually when grouping is disabled or the
@@ -109,8 +105,7 @@ Horizontal local overrides are re-evaluated live; vertical placement retains its
 per-page-visit rules. `data-projection="source|system"` remains a separate native
 vertical appearance setting.
 
-`enableVerticalControlArea()` remains vertical-only. Use `enableNativeUI()`
-when horizontal projection is needed, and run only one of the two runtimes.
+The standalone `enableVerticalControlArea()` defaults `controls` to `'verticalOnly'`. Explicit sources and extensions remain independent. Use one startup entry per application.
 
 ## Supported markup
 
@@ -118,7 +113,7 @@ The table below describes the ordinary Native UI. Vertical Bars uses the separat
 
 | Ionic component                               | Supported appearance and placement                                                                        | Native rendering                                                      |
 | --------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| `ion-button`                                  | `fill="default"`, or clear inside an ungrouped `ion-buttons`, in a fixed header/footer toolbar                                        | Glass `UIButton`                                                      |
+| `ion-button`                                  | `fill="default"`, or clear inside an ungrouped `ion-buttons`, in a fixed header/footer toolbar            | Glass `UIButton`                                                      |
 | `ion-buttons`                                 | Fixed toolbar, two or more direct clear `ion-button` / `ion-menu-button` children sharing the theme glass | One `UIGlassEffect` surface with independent native buttons           |
 | `ion-back-button`                             | Standard icon and color in a fixed header/footer toolbar                                                  | Glass `UIButton`, using the resolved Ionic label/icon                 |
 | `ion-menu-button`                             | Fixed toolbar, inside the theme glass `ion-buttons`                                                       | Glass `UIButton`; original Ionic menu toggle                          |
@@ -128,6 +123,8 @@ The table below describes the ordinary Native UI. Vertical Bars uses the separat
 
 For the ordinary Native UI, only supported iOS-mode components are eligible. Theme variables are not required; calling `enableNativeUI()` opts into native projection. Explicitly enabled Vertical Bars is mode-independent as described below. `ios-theme-disabled` and the legacy `ios26-disabled` on an element or ancestor always exclude it. A disabled theme on one tab/segment item keeps its whole group on the Web.
 
+### Opt out of native projection
+
 Use `data-native-ui="disabled"` (or the equivalent `native-ui-disabled` class) to disable only the iOS Native UI while keeping the Web theme. It excludes the element and all its descendants. Adding or removing the attribute or class at runtime automatically restores Web rendering or re-evaluates native eligibility.
 
 Only the exact value `disabled` opts out; an empty or unknown value does not opt out. Remove the attribute to restore automatic Ionic projection. For explicitly declared HTML controls, restore the original `data-native-ui="button"` or `data-native-ui="back-button"` value instead. Alternatively, set `data-native-ui="disabled"` on a parent to disable a subtree while preserving its children's declarations. If the `native-ui-disabled` class is also present, remove it as well. This does not disable clicks or change the Web theme. The runtime-owned `data-native-ui-projected` marker is separate; applications should not set it. For the previous opt-out attribute, see [migration](migration.md#native-ui-naming-changes).
@@ -138,13 +135,60 @@ Only the exact value `disabled` opts out; an empty or unknown value does not opt
 </ion-toolbar>
 ```
 
-If a child inside a shared native surface opts out, the entire surface stays on the Web: this includes button groups, tab bars, segments and FAB lists. Opting out of the search FAB or any part of the search footer disables native search integration; the tab bar can still render natively if it remains eligible.
+In ordinary placement, an explicit `data-native-ui="disabled"` or `.native-ui-disabled` opt-out inside a shared surface keeps that surface and its children on the Web, including button groups, tab bars, segments and FAB lists. This is different from disabling grouping with `buttonGroup`. Opting out of the search FAB or any part of the search footer disables native search integration; the tab bar can still render natively if it remains eligible.
+
+### Placement requirements
+
+Glass appearance alone is not enough. Ordinary projection requires fixed controls:
 
-Placement is required even when the appearance is glass. In the ordinary Native UI, buttons, back buttons, menu-button groups and segments need a toolbar directly inside `ion-header` or `ion-footer`, with no `ion-content` ancestor around the control. Buttons directly inside a header/footer, standalone toolbars, and toolbars or headers nested in scrolling content stay on the Web. FABs without `slot="fixed"` also stay on the Web. Moving a projected control to an excluded location restores its Web rendering; moving it back re-evaluates eligibility. When `.ios-theme-vertical-bars` is enabled, a standard `ion-back-button` can instead be projected to the Vertical Control Area from outside a fixed toolbar, including routed content or a persistent app shell. The application chooses where to enable this mode and which Ionic component mode to use; Vertical Bars projection does not require `ios` mode classes. Collapsed headers, opted-out controls and departed pages are excluded. Full-width foreground modals can participate in Vertical Bars as described below; other overlay surfaces keep their own layout.
+| Control or location                                                                                    | Eligibility                                                                                                                         |
+| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Buttons, back buttons, menu-button groups and segments                                                 | Toolbar directly inside `ion-header` or `ion-footer`, with no `ion-content` ancestor around the control.                            |
+| Buttons directly inside a header/footer, standalone toolbars, or toolbars/headers in scrolling content | Stay on the Web.                                                                                                                    |
+| FAB                                                                                                    | Must use the `ion-content` fixed slot.                                                                                              |
+| Back button with `.ios-theme-vertical-bars` enabled                                                    | Can project outside a fixed toolbar, including routed content or a persistent app shell. Vertical Bars does not require `ios` mode. |
+| Collapsed headers, opted-out controls and departed pages                                               | Excluded.                                                                                                                           |
+| Full-width foreground modal                                                                            | Can participate in Vertical Bars; other overlay surfaces keep their own layout.                                                     |
 
-Native tabs accept equal-width items with Ionic's default `layout="icon-top"`. The native bar uses a local compact horizontal and regular vertical size class to preserve the Web's stacked icon/label arrangement on iPad and in landscape. This does not change the app's size class. Label size and weight follow the Web snapshot. Other explicit Ionic layouts (`icon-start`, `icon-end`, `icon-bottom`, `icon-hide`, `label-hide`) and unequal item widths keep the entire tab bar on the Web. Start, center and end placement follow the original `ion-tab-bar`, including RTL. Directional `ion-icon` artwork preserves its rendered RTL flip.
+Moving a projected control to an excluded location restores its Web rendering; moving it back re-evaluates eligibility. The application chooses where to enable Vertical Bars and which Ionic component mode to use.
 
-Outside Vertical Bars, standalone clear, solid and outline buttons are excluded. A glass `ion-buttons` group of two or more clear buttons is projected as one surface; its children retain separate actions. Menu buttons can also share that group. A single menu button uses its parent `ion-buttons` as the glass surface, so no Web glass is left underneath the native button. A menu button outside this theme glass remains on the Web. Mixed fills, unsupported children, or a theme-disabled child keep the group on the Web. Single clear buttons remain on the Web. Custom button colors, custom back icons/colors, collapsing headers, toolbars inside scrolling content, modal content, scrollable/expanded segments and segment-view integration remain on the Web. Complex slots and unsupported SVG features also fall back to Web. The plugin does not translate arbitrary application CSS into UIKit styles.
+### Tab layout
+
+| Source layout                                                        | Result                                                          |
+| -------------------------------------------------------------------- | --------------------------------------------------------------- |
+| Equal-width items with the default `layout="icon-top"`               | Native stacked icon/label layout, including iPad and landscape. |
+| `icon-start`, `icon-end`, `icon-bottom`, `icon-hide` or `label-hide` | Entire tab bar stays on the Web.                                |
+| Unequal item widths                                                  | Entire tab bar stays on the Web.                                |
+| Start, center or end placement                                       | Follows the source bar, including RTL.                          |
+| Directional `ion-icon` artwork                                       | Preserves its rendered RTL flip.                                |
+
+The native bar uses local compact horizontal and regular vertical size classes without changing the app's size class. Label size and weight follow the Web snapshot.
+
+### Ordinary button grouping
+
+These rules apply outside Vertical Bars:
+
+| Source or setting                                            | Result                                                                                                            |
+| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| Clear button inside `ion-buttons`                            | Can project individually.                                                                                         |
+| Standalone clear, solid or outline button                    | Stays on the Web.                                                                                                 |
+| Grouping enabled with two or more eligible clear buttons     | One native surface with separate actions. Menu buttons can join.                                                  |
+| Single menu button                                           | Uses its parent group as the surface.                                                                             |
+| Grouping disabled, mixed fills or unsupported group children | Eligible actions can still project individually. Explicit subtree opt-outs follow the shared-surface rules above. |
+| Back button                                                  | Never joins an ordinary action group.                                                                             |
+
+### Unsupported content
+
+The following remain on the Web; the plugin does not translate arbitrary application CSS into UIKit styles:
+
+| Area       | Unsupported configuration                                                                                                             |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| Buttons    | Custom button colors or custom back icons/colors.                                                                                     |
+| Containers | Collapsing headers, toolbars inside scrolling content, and ordinary modal content. See the separate Vertical Bars modal policy below. |
+| Segments   | Scrollable/expanded segments and segment-view integration.                                                                            |
+| Content    | Complex slots and unsupported SVG features.                                                                                           |
+
+### Backgrounds and fallback handoffs
 
 Native glass samples the Web content actually drawn behind it. Existing toolbar backgrounds and header blur still affect that content. For content to scroll beneath a header, use Ionic's normal translucent-header/fullscreen-content layout; the plugin does not move page content or override an application-owned opaque toolbar background.
 
@@ -154,14 +198,53 @@ When an existing control becomes unsupported, its Web source is painted before i
 
 ## State and events
 
+### Menu actions
+
 Menu buttons use Ionic's resolved default/configured icon or a supported slot icon/label. Native activation clicks the original `ion-menu-button`, preserving `menu` targeting. Non-default menu button types (`submit` / `reset`) remain on the Web. `disabled`, `autoHide`, menu availability and split-pane visibility follow the actual DOM. Opening a menu restores Web controls and retires their native covers; closing it reprojects eligible controls.
 
-The DOM owns labels, SVG content, placement, selected values and application behavior. The placement reference is `ion-tab-bar` itself. The native tab content uses that rectangle as its sizing proposal and placement anchor, accounting for UITabBar's larger outer frame: `tab-bar-position-start`, `tab-bar-position-center`, and `tab-bar-position-end` control the horizontal anchor (including RTL), while `slot="bottom"` retains the bottom edge and `slot="top"` retains the top edge. Class changes are reconciled automatically. UIKit owns internal margins and platter sizing, while the supported stacked layout and label typography follow the Web. UIKit can cap the content width even with fill positioning. On viewports at least 768px wide, the Web theme caps standard two-, three-, four- and five-item bars near the iPad stacked platter measurements (188, 274, 336 and 414pt). Smaller viewports retain the phone sizing. The standard bar is 62pt high, with a 54pt selection and a 4pt inset. Adjacent buttons overlap like UIKit’s controls; icon and label alignment is checked against simulator screenshots. These are default appearance targets, not a guarantee for custom fonts, icons or labels; UIKit still determines its intrinsic width. A different native width or height does not reject projection. Badge and title updates retain native item identities and remeasure the platter at the same placement anchor. The plugin does not stretch icons or modify UIKit's internal controls to force CSS item widths. The plugin measures the view subtree containing the native tab controls without private class names or fixed inset corrections; an unrecognized layout restores Web rendering. The runtime watches structural changes, affected shadow roots, sizing, page lifecycle events and overlays. Ancestor `display: none`, `hidden`, theme classes, component removal and disabled changes are reconciled automatically. Native touch events are checked against the current DOM and revision before clicking the original Ionic element.
+### Tab geometry and state updates
+
+The DOM owns labels, SVG content, placement, selected values and application behavior. `ion-tab-bar` itself is the placement reference; UIKit owns internal margins and platter sizing.
+
+| Source or viewport                                                          | Native behavior                                                                  |
+| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Source bar rectangle                                                        | Sizing proposal and placement anchor, accounting for UIKit's larger outer frame. |
+| `tab-bar-position-start`, `tab-bar-position-center`, `tab-bar-position-end` | Horizontal anchor, including RTL; class changes reconcile automatically.         |
+| `slot="bottom"` / `slot="top"`                                              | Retains the corresponding bottom/top edge.                                       |
+| Supported stacked layout and label typography                               | Follow the Web snapshot. UIKit can cap content width even with fill positioning. |
+| Badge or title updates                                                      | Retain native item identities and remeasure at the same anchor.                  |
+| Different native width or height                                            | Does not reject projection; icons are not stretched to force CSS item widths.    |
+| Unrecognized native layout                                                  | Restores Web rendering.                                                          |
+
+The Web theme's standard appearance targets are:
+
+| Measurement                                      | Target                                                                                           |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| Viewport at least 768px wide, 2 / 3 / 4 / 5 tabs | Platter widths near 188 / 274 / 336 / 414pt respectively. Smaller viewports retain phone sizing. |
+| Bar height                                       | 62pt                                                                                             |
+| Selection height / inset                         | 54pt / 4pt                                                                                       |
+| Adjacent buttons                                 | Overlap like UIKit controls.                                                                     |
+
+These targets do not guarantee identical custom fonts, icons or labels; UIKit determines intrinsic width. Icon and label alignment is checked against simulator screenshots. The plugin measures the native tab subtree without private class names or fixed inset corrections.
+
+The runtime rechecks:
+
+- Structural changes, affected shadow roots and sizing.
+- Page lifecycle events and overlays.
+- Ancestor `display: none`, `hidden`, theme classes, component removal and disabled changes.
+
+Native touch events are checked against the current DOM and revision before clicking the original Ionic element.
+
+### Forms and segment values
 
 For forms, retain `ion-button type="submit"` and the form's existing submit handler. An external form is still passed as `[form]="formRef"`. The plugin does not call `form.submit()`, add a second submit path or change Angular form ownership. Segment values retain their original type because the original `ion-segment-button` is clicked; programmatic value changes do not emit a synthetic `ionChange`.
 
+### Text and artwork
+
 Labels use native text. Local static SVGs and resolved `ion-icon` SVGs (including `name` and changes to `name`) are rasterized at the display scale and cached. Source projection preserves their colors; system projection of vertical toolbar buttons uses template icons tinted by SwiftUI. Tab SVGs that follow text color use native template rendering, so icons and labels change selection color together without waiting for another bridge image. Multicolor tab artwork retains its original colors. External references, `<use>`, animation, embedded HTML/images, SVG text and stylesheets are excluded. Web fonts and arbitrary slot layouts are not reproduced exactly.
 
+### Touch, badges and accessibility
+
 The native host accepts input only within native controls. Tab interaction and accessibility are provided by the standard [UITabBar](https://developer.apple.com/documentation/uikit/uitabbar) control. Empty areas pass touches to the WebView. Ionic iOS hides empty badges by default. An empty visible `ion-badge` becomes a native notification dot; a non-empty badge displays its text. Badge background and text colors come from computed DOM styles, including Ionic `color` palettes. Hidden or removed badges clear the native badge. Tabs use UIKit’s standard tab control for selection, touch behavior, badges and accessibility, retaining item identity across selection updates. UIKit owns the item layout within the measured bar, so arbitrary CSS item placement is not reproduced. Native controls expose names, disabled/selected traits and badges to accessibility; the source is hidden from Web accessibility while projected. This is not a guarantee of identical VoiceOver traversal between Web and UIKit.
 
 ## Searchable tabs
@@ -178,7 +261,16 @@ Opening search preserves the selected Ionic tab and does not automatically show
 
 Native edits pass through Ionic's input handlers, preserving `ionInput` debounce, `ionChange`, `ionFocus`, `ionBlur`, and `ionClear`. Programmatic `value` changes do not emit `ionInput`; synchronous application corrections and stale native input are distinguished. Native editing owns marked text and the caret. Returning through the footer's close action retains the value and does not emit `ionCancel` or `ionClear`.
 
-The first supported search configuration uses iOS-mode glass searchbars with the standard search keyboard, default clear control, no internal cancel button, and default autocorrection/capitalization settings. Custom input modes, return-key hints, min/max length, autocomplete, autocorrection, spellcheck, clear icons and classic searchbars remain on the Web. `disabled`, `placeholder`, `value` and `setFocus()` are synchronized for supported groups. General standalone searchbars are outside this feature.
+### Supported search configuration
+
+| Area                       | Native support                                                      | Remains on the Web                                                                                         |
+| -------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Search group               | Registered searchable tabs with an iOS-mode glass searchbar.        | General standalone searchbars and classic searchbars.                                                      |
+| Keyboard and text settings | Standard search keyboard and default autocorrection/capitalization. | Custom input modes, return-key hints, min/max length, autocomplete, autocorrection or spellcheck settings. |
+| Clear/cancel controls      | Default clear control, no internal cancel button.                   | Custom clear icons or an internal cancel button.                                                           |
+| State and focus            | Synchronizes `disabled`, `placeholder`, `value` and `setFocus()`.   | Unsupported group configurations use Web rendering.                                                        |
+
+### Search lifetime and recovery
 
 Page retirement, overlays, theme exclusion and lost native ownership close the native presentation and preserve the latest synchronized/application value. A later search starts from that closed state. The registration survives cached page transitions; reattaching on every return is not required. Bridge waits are finite. When an opening request loses the bridge, its pending Enter can complete through the existing Web animation. A disconnected bridge cannot recover native characters that were never delivered to JavaScript.
 
@@ -188,15 +280,28 @@ While enabled, Native UI suppresses the WebView’s top scroll-edge effect becau
 
 The native search controller remains visible over its own keyboard. Other projected controls are hidden while a Web input opens the keyboard. UIKit's own accessibility and Reduce Motion behavior apply to the standard controls; full VoiceOver traversal is not a verified parity guarantee.
 
-## Transitions and recovery
+## FAB behavior
 
 FABs retain Ionic's `activated`, per-child `show`, `close()` and original click handlers. Multiple lists, initial expansion, small buttons and `edge` use each button's measured layout. The native side reflects Ionic's staggered visibility without adding another timer or open/close controller. Main-button icon changes crossfade using the resolved `closeIcon`; Reduce Motion disables this crossfade. Native FAB button instances persist across open/close updates. The source FAB stays projected throughout ordinary opening and closing.
 
-FAB support covers the standard circular glass appearance, text and resolved static SVG/`ion-icon` content, including RTL icon mirroring. One unsupported child keeps the whole FAB in Web rendering, including when its list is closed. Colored solid buttons, submit/reset or href FABs, custom host backgrounds/shapes/motion, non-fixed-slot placement and unsupported artwork remain Web. For example, the demo's red-background `floating-action-button-fixed` page retains its existing Web appearance. A fixed-slot FAB must be a direct child of `ion-content`; a `slot="fixed"` attribute on a page sibling is not a content slot.
+### FAB eligibility
+
+One unsupported child keeps the whole FAB on the Web, even when its list is closed.
+
+| Area       | Supported                                                         | Remains on the Web                                              |
+| ---------- | ----------------------------------------------------------------- | --------------------------------------------------------------- |
+| Appearance | Standard circular glass.                                          | Colored solid buttons or custom host backgrounds/shapes/motion. |
+| Content    | Text and resolved static SVG/`ion-icon`, including RTL mirroring. | Unsupported artwork.                                            |
+| Actions    | Original click handlers.                                          | Submit/reset or `href` FABs.                                    |
+| Placement  | `slot="fixed"` on a direct child of `ion-content`.                | Non-fixed placement or `slot="fixed"` on a page sibling.        |
+
+For example, the demo's red-background `floating-action-button-fixed` page retains its Web appearance.
 
 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 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 `withNativeUITransition()`, exported by `@rdlabo/ionic-theme-ios27`. See [Connect your navigation animation](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/iphone-duo-with-original-theme.md#3-connect-your-navigation-animation) for the setup.
+## Transitions and recovery
+
+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 `withNativeUITransition()`, exported by `@rdlabo/ionic-theme-ios27`. See [Connect your navigation animation](ionic-vertical-bars.md#3-connect-your-navigation-animation) for the setup.
 
 Ordinary native/Web handoffs share a 180ms opacity crossfade, including Vertical Bars in both directions. Outgoing visuals cannot receive input or accessibility focus. Reduce Motion and modal presentation use immediate handoffs; search controllers keep their UIKit-managed transition.
 
@@ -204,15 +309,15 @@ Tab switches skip the Web/native crossfade so a retiring UIKit snapshot cannot l
 
 Standard Ionic overlays suspend ordinary native projection until dismissal. Vertical Bars use a separate policy:
 
-| Surface or condition | Vertical Bars behavior |
-| --- | --- |
-| Web toast, ordinary popover or legacy picker overlay | Keep the native rail visible, updated and interactive. |
-| Popover opened from a Vertical Bars button, rendered on Web | Return the rail to Web projection until dismissal, including native rejection or preparation failure. |
-| Alert, action sheet or loading | Restore Web rendering so the overlay and its dimming backdrop cover the controls correctly. |
-| Menu | Keep the existing native rail behavior. |
-| Full-width foreground modal | Project the modal's controls instead of the covered page's controls. |
-| Modal that cannot use Vertical Bars | Restore Web rendering. |
-| Explicit suspension, unavailable native layout, hidden document or unsupported keyboard/viewport geometry | Preserve the existing fallback behavior. |
+| Surface or condition                                                                                      | Vertical Bars behavior                                                                                |
+| --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Web toast, ordinary popover or legacy picker overlay                                                      | Keep the native rail visible, updated and interactive.                                                |
+| Popover opened from a Vertical Bars button, rendered on Web                                               | Return the rail to Web projection until dismissal, including native rejection or preparation failure. |
+| Alert, action sheet or loading                                                                            | Restore Web rendering so the overlay and its dimming backdrop cover the controls correctly.           |
+| Menu                                                                                                      | Keep the existing native rail behavior.                                                               |
+| Full-width foreground modal                                                                               | Project the modal's controls instead of the covered page's controls.                                  |
+| Modal that cannot use Vertical Bars                                                                       | Restore Web rendering.                                                                                |
+| Explicit suspension, unavailable native layout, hidden document or unsupported keyboard/viewport geometry | Preserve the existing fallback behavior.                                                              |
 
 Native projection resumes only after every overlay requiring Web rendering closes. The opt-in native Vertical Bars popover described below keeps its own SwiftUI presentation and input handling. Unsupported searchable-tab configurations use the existing Web animation and share this ownership with Web glass gestures. CSS motion of supported containing surfaces also causes temporary Web rendering.
 
@@ -220,7 +325,7 @@ During retirement, the source is restored and allowed to paint before its native
 
 If a bridge update fails or times out, the runtime stops and restores Web rendering. It does not automatically reconnect. `getStatus()` reports `stopped` and the reason; to retry deliberately, call `destroy()` on that handle and then `enableNativeUI()` again.
 
-Failures or timeouts in required startup bridge calls return a Web fallback handle. Optional WebView metrics may fail without disabling native controls. Both `destroy()` and `enableNativeUI({ enabled: false })` wait for teardown; repeated calls share its completion. A new activation requested while teardown is running waits for it, including when the application calls `destroy()` without awaiting it. Await these promises when the next application operation depends on cleanup, and handle any rejection.
+Failures or timeouts in required startup bridge calls return a Web fallback handle. Optional WebView metrics may fail without disabling native controls. `destroy()` waits for teardown; repeated calls share its completion. A new activation requested while teardown is running waits for it, including when the application calls `destroy()` without awaiting it. Await these promises when the next application operation depends on cleanup, and handle any rejection.
 
 For diagnostics or application teardown:
 
@@ -233,7 +338,7 @@ await shell.destroy(); // restore DOM, remove native controls and release listen
 Projection is enabled by calling the startup API. Partial settings override defaults:
 
 ```ts
-const shell = await enableNativeUI({ ionic: { auto: { tabs: false } } }); // automatic Ionic projection except tabs
+const shell = await enableNativeUI({ controls: { tabs: false } }); // automatic Ionic projection except tabs
 await shell.disableVerticalControlArea(); // retain ordinary native controls
 await shell.enableVerticalControlArea();
 await shell.destroy(); // stop all projection
@@ -243,13 +348,13 @@ See [all configuration options](configuration.md) for defaults, rail-only usage
 
 ### Popovers anchored to Vertical Bars
 
-**Native popover presentation is Vertical Bars only.** It requires an accepted native Vertical Bars `ion-button` anchor; enabling `verticalBars.popover` does not make ordinary toolbar or body popovers native. This feature also works with the standalone Vertical Bars runtime, without enabling the full Native UI.
+**Native popover presentation is Vertical Bars only.** It requires an accepted native Vertical Bars `ion-button` anchor; enabling `ionic.verticalBars.popover` does not make ordinary toolbar or body popovers native. This feature also works with the standalone Vertical Bars runtime, without enabling the full Native UI.
 
-Enable `verticalBars.popover` to present popovers from accepted native Vertical Bars `ion-button` controls. Automatic Ionic button projection is enabled by default; when `ionic.auto` is `false`, mark individual anchors with `data-native-ui="button"`:
+Enable `ionic.verticalBars.popover` to present popovers from accepted native Vertical Bars `ion-button` controls. Automatic Ionic button projection is enabled by default; when `ionic.auto` is `false`, mark individual anchors with `data-native-ui="button"`:
 
 ```ts
 await enableNativeUI({
-  verticalBars: { popover: true },
+  ionic: { verticalBars: { popover: true } },
 });
 ```
 
@@ -263,7 +368,21 @@ Only one popover is relayed at a time. A nested popover or modal created in the
 
 Native presentation owns the arrow, corners and animation; custom Web enter/leave animations do not replace them. The source enter builder runs once with zero duration and delay (including child animations), using the native anchor rectangle for the default `reference="trigger"` layout and visible state for Web fallback. Explicit `reference="event"` retains Ionic’s event-coordinate semantics. An explicit `enterAnimation` is honored; otherwise this package’s iOS popover builder is used. Set `enterAnimation` on the overlay to use a custom builder rather than relying on global `popoverEnter` configuration. Material Design (`md`) popovers keep Ionic’s Web presentation. Initial content dimensions come from Ionic.
 
-The relay copies document and popover shadow styles and preserves the content border spacing. Before native presentation it compares selected computed layout and appearance properties at the source dimensions. Detected differences, unsupported ancestor visual effects or size containers, and content exceeding 1,000 elements restore the live Web popover. Changes to mirrored ancestor attributes or source head styles also restore Web rendering. This is a conservative compatibility check, not a guarantee for arbitrary CSS (including pseudo-elements and dynamic CSSOM changes), document-bound queries, or full VoiceOver/hardware-keyboard parity. Failure to prepare or find the native anchor restores the Web popover. A popover opened from a Vertical Bars button also returns the rail to Web projection for the remainder of that presentation; dismissal restores native projection.
+#### Popover fallback conditions
+
+The relay copies document and popover shadow styles and preserves content border spacing. Before presentation, it compares selected computed layout and appearance properties at the source dimensions.
+
+| Condition                                                 | Result                         |
+| --------------------------------------------------------- | ------------------------------ |
+| Detected style/layout differences                         | Restores the live Web popover. |
+| Unsupported ancestor visual effects or size containers    | Restores the live Web popover. |
+| Content exceeds 1,000 elements                            | Restores the live Web popover. |
+| Mirrored ancestor attributes or source head styles change | Restores Web rendering.        |
+| Preparation fails or the native anchor is unavailable     | Restores the Web popover.      |
+
+A rail-button popover falling back to Web also returns the rail to Web projection until dismissal. This compatibility check does not guarantee arbitrary CSS (including pseudo-elements and dynamic CSSOM changes), document-bound queries, or full VoiceOver/hardware-keyboard parity.
+
+### Custom overlay suspension
 
 For a custom modal or overlay that Native UI cannot detect, acquire a suspension before presenting it. The resolved suspension means projected controls have returned to Web rendering. Always release it after dismissal:
 
@@ -282,19 +401,19 @@ Suspensions are nestable and `resume()` is idempotent. Native projection resumes
 
 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.
 
-## Support iPhone Duo (preview)
+## Support iPhone Duo
 
-iPhone Duo support, including standalone vertical bars without Native UI, is available as a **preview** in `1.2.0` alongside Native UI. Its APIs and supported behavior may change.
+iPhone Duo support, including standalone Vertical Bars, is stable starting with version 2.0.0.
 
-The standalone Vertical Control Area entry point (`@rdlabo/capacitor-native-ui/vertical-bars`) works with application-supplied Web layout. The theme package offers an [optional rail stylesheet](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/vertical-bars-layout.md), `@rdlabo/ionic-theme-ios27/dist/css/vertical-bars.css`, which can be used without loading the full iOS 27 appearance. Call `enableNativeUI({ verticalBars: { only: true } })` for this use case; it projects only controls placed in the vertical area. Apps already calling `enableNativeUI()` should keep that single runtime rather than starting both. See [iPhone Duo support](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/iphone-duo.md) for the complete setup, including hinge posture and the split-pane layout for apps that do not use this shell at all.
+The standalone Vertical Control Area entry point (`@rdlabo/capacitor-native-ui/vertical-bars`) works with application-supplied Web layout. The theme package offers an [optional rail stylesheet](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/vertical-bars-layout.md), `@rdlabo/ionic-theme-ios27/dist/css/vertical-bars.css`, which can be used without loading the full iOS 27 appearance. Call `enableNativeUI({ controls: 'verticalOnly' })` for this use case; its default selection targets controls placed in the vertical area. Apps already calling `enableNativeUI()` should keep that single runtime rather than starting both. See [iPhone Duo support](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/iphone-duo.md) for the complete setup, including hinge posture and the split-pane layout for apps that do not use this shell at all.
 
 Vertical Bars uses a SwiftUI `TabView` and toolbar in the system rail. Ionic remains the source of labels, icons, selected/disabled state and actions. See [Vertical Bars](vertical-bars.md) for rail layout, native fallback and supported overlays.
 
 In Vertical Bars, automatic selection of fixed-toolbar `ion-button` actions requires an `ion-icon` or SVG with `slot="icon-only"`; `data-vertical-bars="true"` can explicitly select other supported buttons. All fills and Ionic colors are eligible; submit buttons follow the same placement rule. Add `.ios-theme-horizontal-only` to a button or its `ion-buttons` group to keep it horizontal. See [Toolbar actions](vertical-bars.md#toolbar-actions) for placement and exclusion rules.
 
-**Native button appearance:** `1.2.0` defaults native vertical buttons to `buttonProjection: 'system'`. Use `source` to project Ionic fill and colors, with `data-projection="source|system"` or the equivalent `ios-theme-projection-source` / `ios-theme-projection-system` classes for local exceptions. These settings affect native vertical `ion-button` and `ion-menu-button` actions only. Horizontal controls and Web clones keep their existing behavior. See [Choose button appearance](vertical-bars.md#choose-button-appearance) for migration, priority and fill rules.
+**Native button appearance:** Native vertical buttons default to `buttonProjection: 'system'`. Use `source` to project Ionic fill and colors, with `data-projection="source|system"` or the equivalent `ios-theme-projection-source` / `ios-theme-projection-system` classes for local exceptions. These settings affect native vertical `ion-button` and `ion-menu-button` actions only. Horizontal controls and Web clones keep their existing behavior. See [Choose button appearance](vertical-bars.md#choose-button-appearance) for priority and fill rules.
 
-For standalone setup while keeping your existing theme, see [iPhone Duo with your existing theme](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/iphone-duo-with-original-theme.md).
+For standalone setup while keeping your existing theme, see [iPhone Duo with your existing theme](ionic-vertical-bars.md).
 
 ## Native UI API