@rdlabo/capacitor-native-ui 1.2.1 → 2.0.0-beta.pr304.sha56daf151ad80

package/docs/migration.md

@@ -4,18 +4,14 @@ title: Migration
 
 # Migration
 
-> 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.
+## Upgrading from 1.2.1
 
-## Migrating from Native UI Shell Preview
+This guide is for applications using `@rdlabo/ionic-theme-ios27` **1.2.1**, including its Native UI Shell Preview and standalone Vertical Control Area.
 
-Native UI Shell was already published as **Preview** in `@rdlabo/ionic-theme-ios27` 1.2.0 and 1.2.1. Preview users need the migration below when adopting the split packages; changing the import alone is not sufficient for every configuration. Candidate/beta users should also compare their configuration with these mappings and use JavaScript and native code from the same candidate.
+- **Theme only:** update the theme package. Existing theme imports, CSS/Sass paths and animation imports remain valid; no native startup is needed.
+- **Native UI or Vertical Control Area:** install the native package directly, replace imports and startup settings below, then sync Capacitor and rebuild the native app.
 
-1. Install the matching packages and replace removed imports using [package separation](#native-ui-package-separation).
-2. Apply the [API and native naming changes](#native-ui-naming-changes), then translate startup settings using [shared shell configuration](#shared-shell-configuration-and-html-adapters), especially partial `controls` objects.
-3. Update [Web layout ownership](#web-layout-ownership) and the [transition adapter](#native-ui-transition-adapter) if used.
-4. Rebuild Web assets, sync Capacitor, and rebuild the native app. A Web-only update cannot replace the native plugin.
-
-Native UI remains Preview. App-local SwiftUI / Compose **extensions are experimental**, including their TypeScript definitions, native registration APIs and placement behavior. The `defineNativeUI` and `extensions` names stay unchanged; native registration names change as listed below. Applications using extensions should keep their Web fallback and verify their reader, native renderer and action forwarding together after updates. See the [extension guide](native-ui-extensions.md).
+Native UI remains Preview. Experimental Extensions are documented in the [current extension guide](native-ui-extensions.md); this guide covers the published 1.2.1 controls and setup.
 
 ## Native UI package separation
 
@@ -23,11 +19,11 @@ For a new native integration, follow [Native UI setup](setup.md) or, if you alre
 
 The theme and native controls now live in separate packages. Choose dependencies by the behavior your app uses:
 
-| App behavior | Package to use directly |
-| --- | --- |
-| Theme styles, Ionic Web behavior, and theme animations | `@rdlabo/ionic-theme-ios27` |
-| Native UI or standalone Vertical Control Area | `@rdlabo/capacitor-native-ui` |
-| Theme styling together with native controls | Both packages |
+| App behavior                                           | Package to use directly       |
+| ------------------------------------------------------ | ----------------------------- |
+| Theme styles, Ionic Web behavior, and theme animations | `@rdlabo/ionic-theme-ios27`   |
+| Native UI or standalone Vertical Control Area          | `@rdlabo/capacitor-native-ui` |
+| Theme styling together with native controls            | Both packages                 |
 
 The theme owns the appearance and behavior of Ionic's Web elements. Native UI owns projecting supported controls into native iOS views and coordinating their lifecycle with Web navigation. Native UI can be used without the iOS 27 theme; installing it does not apply theme styles. Standard controls on Android and browsers retain Web presentation; Android can render [app-local Compose extensions](native-ui-extensions.md#2b-register-compose-content-on-android).
 
@@ -35,7 +31,7 @@ The theme uses the native package's shared transition/search integration interna
 
 ### 1. Update application dependencies
 
-These commands apply once the packages containing this migration are published.
+When using both packages, update them together to keep their versions aligned.
 
 For theme-only apps, update the theme package. Keep existing theme imports and CSS/Sass paths; no native startup or plugin setup is needed for theme-only use.
 
@@ -51,22 +47,12 @@ npm install @rdlabo/ionic-theme-ios27 @rdlabo/capacitor-native-ui
 
 For native controls with your existing Web appearance, follow [Native UI only](setup.md). Install the native package directly and keep your existing Web styles. The plugin no longer requires theme variables to select supported controls; Web layout remains the responsibility of your app or theme. Native startup requires Capacitor 8. The Ionic adapter requires Ionic 8.8.1 or later within Ionic 8 or 9; the `/core` entry does not require Ionic.
 
-If you used the intermediate `@ionic-theme/capacitor-native-ui` package name during development, remove it and install `@rdlabo/capacitor-native-ui`. Keep the theme dependency if your app uses its styles or APIs.
-
-```sh
-npm uninstall @ionic-theme/capacitor-native-ui
-npm install @rdlabo/capacitor-native-ui
-```
-
 ### 2. Replace native imports
 
-| Previous import | Replacement |
-| --- | --- |
-| `@rdlabo/ionic-theme-ios27/native` | `@rdlabo/capacitor-native-ui` |
+| Previous import                           | Replacement                                 |
+| ----------------------------------------- | ------------------------------------------- |
+| `@rdlabo/ionic-theme-ios27/native`        | `@rdlabo/capacitor-native-ui`               |
 | `@rdlabo/ionic-theme-ios27/vertical-bars` | `@rdlabo/capacitor-native-ui/vertical-bars` |
-| `@ionic-theme/capacitor-native-ui` | `@rdlabo/capacitor-native-ui` |
-| `@ionic-theme/capacitor-native-ui/vertical-bars` | `@rdlabo/capacitor-native-ui/vertical-bars` |
-| `@ionic-theme/capacitor-native-ui/integration` | `@rdlabo/capacitor-native-ui/integration` |
 
 Update both value and type imports, including lazy imports, test aliases, and bundler configuration. The old theme `/native` and `/vertical-bars` entries have been removed; there are no compatibility aliases.
 
@@ -75,7 +61,7 @@ Update both value and type imports, including lazy imports, test aliases, and bu
 + import { enableNativeUI } from '@rdlabo/capacitor-native-ui';
 ```
 
-Keep existing control markup; review the [startup option changes](#shared-shell-configuration-and-html-adapters), including partial `controls` defaults. The ordinary `@rdlabo/ionic-theme-ios27` entry, theme CSS/Sass paths, and theme animation imports stay unchanged. For custom navigation animations, see the [transition adapter instructions](#native-ui-transition-adapter) below.
+Keep existing control markup; review the [startup option changes](#startup-options), including partial `controls` defaults. The ordinary `@rdlabo/ionic-theme-ios27` entry, theme CSS/Sass paths, and theme animation imports stay unchanged. For custom navigation animations, see the [transition adapter instructions](#native-ui-transition-adapter) below.
 
 ### 3. Sync the native project
 
@@ -87,40 +73,35 @@ npx cap sync ios
 
 The Capacitor plugin is now supplied by the native package. Remove manually linked copies of the old theme Swift package so only the new package supplies the plugin. The Swift package/product and CocoaPods pod are now `RdlaboCapacitorNativeUi`; the Swift module is `NativeUIPlugin`. The Capacitor bridge name is now `NativeUI` on JavaScript, iOS and Android. Run Capacitor sync for each native platform you use and rebuild the native app. An OTA/Web-only update cannot migrate an installed binary containing only the old plugin. Use matching JavaScript and native package versions.
 
-For local Swift package references, the package now lives at `packages/capacitor-native-ui` within this repository; there is no root Swift package. Prefer Capacitor's generated integration for application dependencies.
+Use Capacitor's generated integration for the npm dependency; applications do not need a checkout of this repository or a manually linked Swift package.
 
 ### 4. Verify the migration
 
-- Check `package.json` and the lockfile: native-enabled apps have a direct `@rdlabo/capacitor-native-ui` dependency and no intermediate `@ionic-theme/capacitor-native-ui` dependency.
-- Build the application and confirm there are no imports of the removed theme entries or the intermediate package name.
-- Build and launch the iOS app after sync. Check native controls, navigation/back gestures, and any app-local Swift extensions you use.
+- Check that native-enabled apps declare `@rdlabo/capacitor-native-ui` directly, then build and confirm no imports of the removed theme entries remain.
+- Build and launch the iOS app after sync. Check native controls, navigation/back gestures, and restored Web controls after teardown.
 - Check browser and Android Web presentation where supported by your app, and confirm the theme still looks correct.
 - Check that previously disabled control kinds remain disabled after expanding partial Preview settings. Test toolbar grouping, individually selected actions and back navigation in both horizontal and vertical layouts.
-- For experimental extensions, check native registration, props, click forwarding and restoration of the original Web UI when projection is unavailable. Rebuild and sync Android as well if the app uses Compose extensions.
 
 ## Native UI naming changes
 
-The split package uses Native UI names throughout. These are breaking renames; the old names are not aliases. The historical names below refer to the published theme Preview or pre-release package candidates.
+The split package uses Native UI names throughout. These are breaking renames; the old names are not aliases. The previous names below refer to the published 1.2.1 Preview.
 
-| Previous name | New name |
-| --- | --- |
-| `enableNativeUIShell()` | `enableNativeUI()` |
+| Previous name                                                                                                                                      | New name                                                                                                             |
+| -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `enableNativeUIShell()`                                                                                                                            | `enableNativeUI()`                                                                                                   |
 | `NativeUIShellOptions`, `NativeUIShellHandle`, `NativeUIShellStatus`, `NativeUIShellSuspension`, `NativeUIShellControls`, `NativeUIShellComponent` | `NativeUIOptions`, `NativeUIHandle`, `NativeUIStatus`, `NativeUISuspension`, `NativeUIControls`, `NativeUIComponent` |
-| `IonicNativeUIShell` (plugin export and bridge registration) | `NativeUI` |
-| `withNativeUIShellTransition()` | `withNativeUITransition()` (still exported by the theme package) |
-| `IonicNativeUIShellPlugin` (Swift module/native class) | `NativeUIPlugin` |
-| `IonicThemeCapacitorNativeUi` (SPM package/product and pod) | `RdlaboCapacitorNativeUi` |
-| `NativeUIShell.register()` (Swift / Kotlin extensions) | `NativeUI.register()` |
-| `data-shell="disabled"` | `data-native-ui="disabled"` |
-| `.ios-theme-shell-disabled` | `.native-ui-disabled` |
-
-Replace the `NativeUIShell` part with `NativeUI` in imports from `/integration` as well (for example `suspendNativeUI` and `setNativeUIIntegration`). App-local Swift extensions now use `import NativeUIPlugin`; Kotlin extensions use `import dev.rdlabo.capacitor.nativeui.NativeUI`.
+| `IonicNativeUIShell` (plugin export and bridge registration)                                                                                       | `NativeUI`                                                                                                           |
+| `withNativeUIShellTransition()`                                                                                                                    | `withNativeUITransition()` (still exported by the theme package)                                                     |
+| `IonicNativeUIShellPlugin` (Swift module/native class)                                                                                             | `NativeUIPlugin`                                                                                                     |
+| `RdlaboIonicThemeIos27` (SPM package/product)                                                                                                      | `RdlaboCapacitorNativeUi`                                                                                            |
+| `data-shell="disabled"`                                                                                                                            | `data-native-ui="disabled"`                                                                                          |
+| `.ios-theme-shell-disabled`                                                                                                                        | `.native-ui-disabled`                                                                                                |
 
 Runtime-owned attributes/events are internal, not configuration: `data-native-ui-shell` is now `data-native-ui-projected`, other `data-native-ui-shell-*` attributes use `data-native-ui-*`, `nativeUIShell*` events use `nativeUI*`, and `.ios-theme-native-ui-shell-*` classes use `.native-ui-*`. Update application tests or diagnostics that inspect them. **Keep explicit source declarations such as `data-native-ui="button"` unchanged**; the projected marker is separate and is managed by the runtime.
 
 ## Native UI transition adapter
 
-The Ionic transition adapter now belongs to `@rdlabo/ionic-theme-ios27`. Replace preview imports from the plugin’s `/integration` or `/vertical-bars` entry with the theme root. Native-only applications can use `shell.suspend()` and the returned `resume()` directly.
+The Ionic transition adapter now belongs to `@rdlabo/ionic-theme-ios27`. Replace the 1.2.1 import of `withNativeUIShellTransition` from `@rdlabo/ionic-theme-ios27/vertical-bars` with `withNativeUITransition` from the theme root. Native-only applications can use `shell.suspend()` and the returned `resume()` directly.
 
 Use `withNativeUITransition()` to keep your existing Ionic navigation animation while coordinating Native UI controls.
 
@@ -143,64 +124,61 @@ Use the adapter only for navigation; leave modal and popover animations unchange
 
 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 and supported scope.
 
-## Shared shell configuration and HTML adapters
+## Startup options
 
-Run `npx cap sync ios` after updating: JavaScript now sends framework-independent control kinds to Swift. New Swift code also accepts the previous `ion-*` kinds, but new JavaScript requires the matching native plugin.
+In 1.2.1, providing `controls` enabled **only fields set to `true`**. In the new API, omitted fields default to `true`, even in a partial object. Expand your old selection when migrating.
 
-- `controls.toolbar` becomes `ionic.auto.buttons`.
-- `controls.popover` becomes `verticalBars.popover`.
-- Top-level `buttonProjection` and `buttonDefaultFill` move into `verticalBars`.
-- The new `verticalBars.buttonDefaultFill` uses `'glass'` instead of `null`.
-- `verticalBarsOnly: true` becomes `verticalBars: { only: true }`.
-- Omitted automatic kinds now default to `true`, including partial legacy `controls` objects. Published 1.2.x enabled only fields explicitly set to `true` when `controls` was supplied. Expand partial objects when migrating, even if you keep the legacy option name.
-- The global `enableVerticalControlArea()` remains a legacy startup wrapper. New code starts with `enableNativeUI({ verticalBars: { only: true } })`, then uses the returned handle's `enableVerticalControlArea()` / `disableVerticalControlArea()` methods.
-- Legacy option names and global `enabled: false` remain accepted; use `shell.destroy()` to stop new code. If both old and new settings are supplied, the new nested settings take precedence.
+| 1.2.1                               | New configuration                                                                                                                                         |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No `controls`                       | No `controls`: all supported kinds remain selected by default.                                                                                            |
+| `controls: {}`                      | `controls: false` to disable default selection, or `ionic: { auto: false }` to disable Ionic discovery altogether.                                        |
+| `controls.toolbar`                  | Set `controls.buttonGroup`, `controls.button`, and `controls.backButton` to the old toolbar value.                                                        |
+| `controls.tabs`, `.segment`, `.fab` | Same names, but explicitly use `false` for previously omitted fields.                                                                                     |
+| `buttonProjection`                  | `ionic.verticalBars.buttonProjection`                                                                                                                     |
+| `buttonDefaultFill: null`           | `ionic.verticalBars.buttonDefaultFill: 'glass'` (also the default)                                                                                        |
+| `buttonDefaultFill: 'solid'`        | `ionic.verticalBars.buttonDefaultFill: 'solid'`                                                                                                           |
+| `verticalBarsOnly: true`            | `controls: 'verticalOnly'` for default selection in the rail. For a partial selection, use `'verticalOnly'` on each enabled kind and `false` on the rest. |
+| `enabled: false`                    | Do not start the runtime, or call the active handle's `destroy()`.                                                                                        |
 
-For example, preserve a Preview configuration that projected only tabs:
+The old startup option names are removed, without aliases. The standalone `enableVerticalControlArea()` entry remains available and defaults `controls` to `'verticalOnly'`; its appearance settings also move under `ionic.verticalBars`. Use only one startup entry per app.
+
+### Preserve a tabs-only configuration
 
 ```diff
 - import { enableNativeUIShell } from '@rdlabo/ionic-theme-ios27/native';
 + import { enableNativeUI } from '@rdlabo/capacitor-native-ui';
 
 - const shell = await enableNativeUIShell({
-+ const shell = await enableNativeUI({
 -   controls: { tabs: true },
 -   buttonProjection: 'source',
 -   buttonDefaultFill: null,
-+   ionic: { auto: { tabs: true, buttons: false, segment: false, fab: false } },
-+   verticalBars: { buttonProjection: 'source', buttonDefaultFill: 'glass' },
++ const shell = await enableNativeUI({
++   controls: {
++     buttonGroup: false,
++     button: false,
++     backButton: false,
++     tabs: true,
++     segment: false,
++     fab: false,
++   },
++   ionic: {
++     verticalBars: { buttonProjection: 'source', buttonDefaultFill: 'glass' },
++   },
   });
 ```
 
-Likewise, replace `controls: {}` with `ionic: { auto: false }` to keep automatic Ionic projection off. Explicit `data-native-ui` sources and extensions remain independent. Calling `enableNativeUI()` with no options still enables all supported automatic kinds.
-
-### Toolbar selection and grouping by layout
+### Select controls by placement
 
-`horizontal` and `vertical` are new toolbar settings. Omit them to retain automatic selection and grouping, or configure each layout independently:
+All six control fields accept `boolean | 'horizontalOnly' | 'verticalOnly'`. A scalar `controls` value applies to every field. Horizontal and vertical mean ordinary placement and the rail, not device orientation or model.
 
 ```ts
-const shell = await enableNativeUI({
-  horizontal: false,
-  vertical: { buttons: false, button: false, backButton: true },
-});
+const shell = await enableNativeUI({ controls: 'verticalOnly' });
 ```
 
-This selects only eligible back buttons among vertical toolbar actions and disables automatic horizontal toolbar selection. Tabs, segments and FABs retain their own settings. To enable all eligible toolbar actions only in vertical layout, use `{ horizontal: false, vertical: true }`; this follows layout, not the Duo model.
-
-Do not translate `controls.toolbar` or `ionic.auto.buttons` into `vertical.buttons`: those options govern the entire automatic toolbar category, while `horizontal.buttons` / `vertical.buttons` govern **grouping only**. Within each layout, `button` selects ordinary actions and `backButton` selects back navigation independently. All three fields default to `true`; a layout value of `false` sets all three to `false`.
-
-If you used the short-lived development settings at the top level, move `{ buttons, button, backButton }` into `vertical: { buttons, button, backButton }`. Those fields were not part of the published 1.2.0/1.2.1 API and are not compatibility aliases. Existing `buttonProjection` / `buttonDefaultFill` are separate appearance settings, mapped above.
+These are selection defaults, not a hard projection scope. Explicit `data-native-ui` sources and local `data-horizontal-bars="true"` / `data-vertical-bars="true"` can opt in even when a matching default is `false`. Remove the explicit marker or use `data-native-ui="disabled"` to leave an individual source on the Web. `ionic.auto: false` disables automatic Ionic discovery, including local layout opt-ins, but leaves explicit source declarations enabled.
 
-Local `data-horizontal-bars="true|false"` / `data-vertical-bars="true|false"` can override these layout defaults. On `ion-buttons` they affect grouping only and never select children. A back button ignores its group's grouping setting. `ionic.auto` and structural exclusions still apply. See [toolbar selection and grouping](native-ui.md#toolbar-selection-and-grouping) for eligibility and when changes take effect.
-
-See [all settings and defaults](configuration.md) and [plain HTML setup](framework-independent.md). Standard HTML buttons use the same Swift controls as Ionic; they do not require an application-specific Swift extension.
+`buttonGroup` controls grouping only. It does not select children: `buttonGroup: true, button: false` projects no ordinary action without explicit selection. `backButton` controls back navigation independently, including inside an `ion-buttons` container. See [all settings](configuration.md) for the complete selection matrix and [toolbar grouping](native-ui.md#toolbar-selection-and-grouping) for local overrides.
 
 ## Web layout ownership
 
 Import `setVerticalBarsLayout` and `applyFoldStateClasses` from `@rdlabo/ionic-theme-ios27` for theme CSS. Replace `setVerticalControlAreaPlacement({ edge, nativeEdge, inset })` with `setVerticalBarsLayout({ edge, inset })`. Native UI now reads availability from its own device metrics; `nativeEdge` is ignored by the deprecated compatibility helper. Normal startup, disabled rails and teardown do not remove theme classes or alter reserved Web spacing. An unavailable native rail keeps the application’s Web rail layout; applications wanting a horizontal layout must select it themselves. Native-only applications can continue to use their own layout CSS.
-
-## Automatic Ionic controls
-
-Use `ionic.auto` for new configuration. It accepts `true` (default), `false`, or `{ buttons, tabs, segment, fab }`. Unlike legacy `controls`, it affects only automatic Ionic projection; explicit `data-native-ui` sources and registered extensions remain enabled. `verticalBars` independently controls rail projection. See [selective projection](configuration.md#select-controls-explicitly-in-a-customized-ionic-app) for an existing Ionic app that opts in individual buttons.
-
-The legacy `controls` option is marked `@deprecated` and remains available. When `ionic.auto` is omitted, legacy kind settings are used, but omitted kinds now default to `true`; expand partial Preview configurations as shown above. If both are supplied, `ionic.auto` takes precedence for automatic kinds. Move the legacy `popover` option to `verticalBars.popover`.

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,7 +63,8 @@ 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 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.
 
@@ -221,14 +222,14 @@ 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+. |
 
 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.
 
-`enableVerticalControlArea({ extensions: [...] })` also accepts extensions. In this standalone mode only accessories belonging to native Vertical Bars are eligible; ordinary element projections require `enableNativeUI`.
+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.
 
 ## Read source geometry and presentation state
 
@@ -246,16 +247,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 +273,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:
 
@@ -362,4 +363,6 @@ Element placement requires the source to fit fully inside the viewport and its a
 
 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
 
@@ -47,38 +45,23 @@ Native appearance follows the applied class, system or always-dark theme CSS. Sy
 
 ## 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`. |
+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.
 
-For toolbar actions that automatically project only in vertical layout:
+`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.
 
-```ts
-const shell = await enableNativeUI({ horizontal: false, vertical: true });
-```
-
-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 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.
 
@@ -100,7 +83,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 +92,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 +100,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                          |
@@ -138,13 +120,15 @@ 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 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.
 
 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.
 
-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.
+Outside Vertical Bars, clear buttons can project individually inside `ion-buttons`; standalone clear, solid and outline buttons remain on the Web. With grouping enabled, two or more eligible clear buttons share one native surface while retaining separate actions. Menu buttons can also join that group; a single menu button uses its parent group as the surface. If grouping is disabled or the group contains mixed fills or unsupported children, eligible actions can still project individually. Back buttons never join the group.
+
+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.
 
 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.
 
@@ -204,15 +188,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 +204,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 +217,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 +227,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 } },
 });
 ```
 
@@ -284,15 +268,15 @@ The native material and control appearance follow the running iOS version; an iO
 
 ## Support iPhone Duo (preview)
 
-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 without Native UI, is available as a **preview** alongside Native UI. Its APIs and supported behavior may change.
 
-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).