@rdlabo/ionic-theme-ios27 0.1.0-beta.pr177.shaea4b7eeec994 → 0.2.1-beta.pr185.sha0793981f6cf4

package/README.md

@@ -1,14 +1,12 @@
 # Ionic Theme iOS27
 
-A CSS/JS theme library that brings the iOS 27 Liquid Glass appearance and navigation animations to Ionic applications while preserving Ionic components and conventions.
+A theme for Ionic apps that brings iOS 27 Liquid Glass and motion to the Web, with an optional way to project existing Ionic controls into native UI.
 
 > [!IMPORTANT]
 > This `main` branch contains the iOS 27 theme under the package name `@rdlabo/ionic-theme-ios27`. For the iOS 26 theme (`@rdlabo/ionic-theme-ios26`), see the [`ios26` branch](https://github.com/rdlabo-dev/ionic-theme-ios27/tree/ios26).
 
 > All versions before 1.0.0 are release candidates (RC). APIs, CSS variables, classes, styling, and behavior may change without backward compatibility, including in minor and patch releases. A stable compatibility commitment starts with 1.0.0.
 
-[Try the iOS 27 demo](https://ionic-theme-ios27.rdlabo.dev/).
-
 <!-- rdlabo-docs-pick -->
 
 <p>
@@ -19,9 +17,27 @@ A CSS/JS theme library that brings the iOS 27 Liquid Glass appearance and naviga
 
 <!-- /rdlabo-docs-pick -->
 
+## Features
+
+### Bring the iOS 27 look to Ionic
+
+Give familiar Ionic screens the iOS 27 visual language: Liquid Glass, styled toolbars and tabs, lists, buttons, search, overlays, page transitions, and coordinated light and dark appearances. See the result in the [Ionic 9 demo](https://ionic-theme-ios27.rdlabo.dev/) and [Ionic 8 demo](https://ionic8-theme-ios27.rdlabo.dev/).
+
+### Project your Ionic UI into Native UI
+
+On Capacitor iOS, the optional, experimental [Native UI Shell](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/native-ui-shell) reads supported fixed controls from your existing Ionic markup. It projects their text, resolved `ion-icon` artwork or supported static SVGs, and selection state into UIKit controls with system Liquid Glass. Changes and native actions flow through the original Ionic components, so the Web and native presentations share one UI definition. Page content and routing stay in the WebView; unsupported layouts keep their Web presentation.
+
+**Tab drag on iOS 27:** The same Library screen with Native UI Shell off (Web) and on (UIKit). Both frames were captured while dragging the selected tab; the lower panels enlarge the glass around the tab bar.
+
+[![Native UI Shell off and on during the same Library tab drag, with enlarged tab bars](./screenshots/native-ui-shell-drag/comparison.png)](./screenshots/native-ui-shell-drag/comparison.png)
+
+### Follow the user's device
+
+Pair the iOS 26 and iOS 27 themes so supported Safari versions can present the design of each generation: the iOS 26 look for iOS 26 users and the iOS 27 look for iOS 27 users. The [adaptive setup](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/ios-adaptive) uses browser feature checks to select the corresponding **styles**; it does not read the iOS version. When both packages are installed, keep the **page transition** on the iOS 27 animation. On even earlier iOS versions, Ionic's default iOS appearance remains when Safari supports neither feature. In a Capacitor iOS app, Native UI Shell's UIKit material follows the installed iOS version.
+
 ## Installation
 
-Capacitor apps can optionally use an experimental [Native UI Shell](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/native-ui-shell): fixed Ionic navigation and action controls rendered by UIKit with system Liquid Glass, while page content, application logic and routing remain in the WebView. The guide covers the idea's origins, the one-time startup call, supported components and fallback behavior.
+The steps below install the iOS 27 theme on its own. To switch between the iOS 26 and iOS 27 themes, follow [Adaptive iOS themes](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/ios-adaptive) instead of using the unconditional stylesheet imports and animation setup below.
 
 Requires `@ionic/core` 8.8.1 or later (Ionic 8 and 9). Install it in an existing Ionic project:
 
@@ -92,6 +108,8 @@ createApp(App)
 })
 ```
 
+To enable Native UI Shell, follow its [setup guide](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/native-ui-shell). Importing the theme's styles alone does not turn on native controls.
+
 The page-transition radius defaults to `0`. Native apps can update it after measuring the web view:
 
 ```ts
@@ -175,13 +193,13 @@ createApp(App)
 
 **Full documentation:** [Ionic Theme iOS27](https://docs.rdlabo.dev/projects/ionic-theme-ios27)
 
-- [Adaptive iOS themes](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/ios-adaptive) — conditionally load iOS 26 or iOS 27 styles.
+- [Adaptive iOS themes](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/ios-adaptive) — select iOS 26 or iOS 27 styles by browser capabilities; keep the iOS 27 page transition when both packages are installed.
 - [Using ion-item-group](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/using-ion-item-group) — required markup for inset lists.
 - [Special markup and classes](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/special-markup) — opt-in markup and utility classes used by the theme.
 - [ESLint](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/eslint) — check list structure with ESLint rules.
 - [Features](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/features) — CSS variables, Liquid Glass, selective imports, and dark mode.
-- [Native UI Shell (Experimental)](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/native-ui-shell) — native controls around Web content, using the included Capacitor plugin.
-- [Animation](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/experimental-animation) — tab bar and searchable effects.
+- [Native UI Shell (Experimental)](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/native-ui-shell) — project supported Ionic controls, text, and icons into UIKit.
+- [Animation](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/experimental-animation) — tab, segment, and searchable effects.
 - [Migration](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/migration) — stylesheet, class, and CSS variable naming changes.
 - [iOS 26 migration history](https://docs.rdlabo.dev/projects/ionic-theme-ios26/docs/migration) — earlier major-version changes for the previous package.
 
@@ -208,7 +226,7 @@ npm start
 
 ### Visual Regression Testing
 
-We use Playwright for visual regression testing to ensure consistent styling across all components. The test suite automatically captures screenshots of all routes in both light and dark modes.
+Playwright compares screenshots of demo routes in light and dark modes against stored baselines to catch unintended visual changes. These regression tests do not measure similarity to iOS 27 reference screens.
 
 #### Running Tests
 

package/dist/native/components/searchable-tabs.d.ts

@@ -6,7 +6,9 @@ export declare const createSearchSupport: (doc: Document, id: (element: Element)
     keepSearchTabsVisible(): void;
     decorate(candidates: Candidate[], blocked: (element: HTMLElement) => boolean): Candidate[];
     projected: (binding: NativeSearchBinding) => boolean;
+    hasActive(): boolean;
     begin(binding: NativeSearchBinding, revision: number): void;
+    setStatus(binding: NativeSearchBinding, active: boolean, focused?: boolean): void;
     release(element: HTMLElement): void;
     reject(ids: string[]): void;
     event(event: ShellSearchEvent): void;

package/dist/native/components/searchable-tabs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"searchable-tabs.d.ts","sourceRoot":"","sources":["../../../src/native/components/searchable-tabs.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAGpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAA0B,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAmB/E,eAAO,MAAM,mBAAmB,GAAI,KAAK,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,EAAE,UAAU,MAAM,IAAI;sBA8FnF,OAAO;;yBAgBJ,SAAS,EAAE,WAAW,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,GAAG,SAAS,EAAE;yBA3GhE,mBAAmB;mBAuO9B,mBAAmB,YAAY,MAAM;qBAInC,WAAW;gBAGhB,MAAM,EAAE;iBAUP,gBAAgB;oBAqCb,mBAAmB;;CAkBtC,CAAC"}
+{"version":3,"file":"searchable-tabs.d.ts","sourceRoot":"","sources":["../../../src/native/components/searchable-tabs.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAGpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAA0B,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAmB/E,eAAO,MAAM,mBAAmB,GAAI,KAAK,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,EAAE,UAAU,MAAM,IAAI;sBA8InF,OAAO;;yBAmBJ,SAAS,EAAE,WAAW,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,GAAG,SAAS,EAAE;yBAlJhE,mBAAmB;;mBAuU9B,mBAAmB,YAAY,MAAM;uBAKjC,mBAAmB,UAAU,OAAO;qBAUtC,WAAW;gBAGhB,MAAM,EAAE;iBASP,gBAAgB;oBAqCb,mBAAmB;;CAoBtC,CAAC"}

package/dist/native/components/searchable-tabs.js

@@ -4,7 +4,52 @@ import { iconSource } from '../shared/icons';
 export const createSearchSupport = (doc, id, schedule) => {
     const states = new Map();
     let keyboardVisible = false;
+    let heldKeyboardResize = null;
+    let keyboardResizeGeneration = 0;
+    const keyboardPlugin = () => doc.defaultView?.Capacitor?.Plugins?.Keyboard;
     const projected = (binding) => binding.footer.hasAttribute(marker);
+    const holdKeyboardResize = () => {
+        const keyboard = keyboardPlugin();
+        if (!keyboard?.setResizeMode || heldKeyboardResize !== null)
+            return;
+        const setResizeMode = keyboard.setResizeMode.bind(keyboard);
+        const generation = ++keyboardResizeGeneration;
+        heldKeyboardResize = 'native';
+        void (async () => {
+            let restoreMode = 'native';
+            try {
+                const current = await keyboard.getResizeMode?.();
+                if (typeof current?.mode === 'string')
+                    restoreMode = current.mode;
+            }
+            catch {
+            }
+            if (generation !== keyboardResizeGeneration)
+                return;
+            heldKeyboardResize = restoreMode;
+            try {
+                await setResizeMode({ mode: 'none' });
+            }
+            catch {
+                if (generation === keyboardResizeGeneration)
+                    heldKeyboardResize = null;
+                return;
+            }
+            if (generation !== keyboardResizeGeneration)
+                void setResizeMode({ mode: restoreMode }).catch(() => undefined);
+        })();
+    };
+    const hasActiveProjection = () => [...states.keys()].some((binding) => binding.active && projected(binding));
+    const releaseKeyboardResize = () => {
+        if (hasActiveProjection())
+            return;
+        keyboardResizeGeneration++;
+        const mode = heldKeyboardResize;
+        heldKeyboardResize = null;
+        if (!mode)
+            return;
+        void keyboardPlugin()?.setResizeMode?.({ mode });
+    };
     const isCurrent = (state) => state.bar.isConnected &&
         state.binding.footer.querySelector('ion-searchbar') === state.bar &&
         state.bar.querySelector('input.searchbar-input') === state.input;
@@ -105,8 +150,10 @@ export const createSearchSupport = (doc, id, schedule) => {
     return {
         keyboard(visible) {
             keyboardVisible = visible;
-            if (!visible)
+            if (!visible) {
                 states.forEach((state) => (state.keyboardHidden = false));
+                releaseKeyboardResize();
+            }
             schedule();
         },
         keepSearchTabsVisible() {
@@ -130,6 +177,11 @@ export const createSearchSupport = (doc, id, schedule) => {
                 }
             }
             const inactive = [];
+            const pageHidden = (element) => !!element.closest('.ion-page-hidden, .ion-page-invisible');
+            const retainInactive = (candidate, state, keepAvailable = false) => {
+                if (state?.last)
+                    inactive.push([candidate, { ...state.last, active: false, available: keepAvailable, focused: false }]);
+            };
             for (const binding of bindings) {
                 const candidate = candidates.find((c) => c.element === binding.tabBar);
                 if (!candidate || candidate.control.search || binding.tabBar.getAttribute('slot') !== 'bottom')
@@ -140,10 +192,36 @@ export const createSearchSupport = (doc, id, schedule) => {
                     continue;
                 if (isShellDisabled(fab) || isShellDisabled(binding.footer))
                     continue;
-                if (blocked(binding.footer) || !visible(binding.trigger) || binding.footer.closest(excluded)) {
-                    const state = states.get(binding);
-                    if (state?.last)
-                        inactive.push([candidate, { ...state.last, active: false, available: false, focused: false }]);
+                const pageUnavailable = blocked(binding.footer) || !!binding.footer.closest(excluded);
+                const existing = states.get(binding);
+                if (pageUnavailable) {
+                    retainInactive(candidate, existing, !!existing?.last?.available && !pageHidden(binding.footer));
+                    if (existing?.last)
+                        continue;
+                }
+                if (binding.active && existing && isCurrent(existing) && existing.last && !pageUnavailable) {
+                    const back = binding.footer.querySelector('ion-buttons[slot=start] ion-button');
+                    if (back && !back.disabled && !back.closest(excluded)) {
+                        candidate.control.search = {
+                            ...existing.last,
+                            active: true,
+                            available: true,
+                            focused: binding.focused,
+                            value: existing.bar.value ?? '',
+                            placeholder: existing.bar.placeholder ?? '',
+                            disabled: existing.bar.disabled,
+                            editSequence: existing.editSequence,
+                            valueVersion: existing.valueVersion,
+                        };
+                        existing.last = candidate.control.search;
+                        candidate.sources = [binding.tabBar, binding.trigger.closest('ion-fab') ?? binding.trigger, binding.footer];
+                        candidate.actions.set(existing.last.trigger.id, binding.trigger);
+                        candidate.actions.set(existing.last.closeId, back);
+                        continue;
+                    }
+                }
+                if (!visible(binding.trigger) && !pageUnavailable) {
+                    retainInactive(candidate, existing);
                     continue;
                 }
                 const bar = binding.footer.querySelector('ion-searchbar');
@@ -155,10 +233,12 @@ export const createSearchSupport = (doc, id, schedule) => {
                     !binding.footer.matches('ion-footer') ||
                     !inFixedToolbar(bar) ||
                     !inFixedToolbar(back) ||
-                    bar.closest(excluded) ||
+                    (!pageUnavailable && bar.closest(excluded)) ||
                     !bar.classList.contains('ios') ||
-                    bar.classList.contains('searchbar-classic'))
+                    bar.classList.contains('searchbar-classic')) {
+                    retainInactive(candidate, existing);
                     continue;
+                }
                 if (bar.color ||
                     back.fill !== 'default' ||
                     back.color ||
@@ -171,14 +251,18 @@ export const createSearchSupport = (doc, id, schedule) => {
                     ![false, 'off', undefined].includes(bar.autocorrect) ||
                     bar.spellcheck ||
                     bar.showClearButton !== 'always' ||
-                    bar.clearIcon)
+                    bar.clearIcon) {
+                    retainInactive(candidate, existing);
                     continue;
-                if (bar.showCancelButton !== 'never' || bar.type !== 'search' || !getComputedStyle(input).backdropFilter.includes('blur'))
+                }
+                if (bar.showCancelButton !== 'never' || bar.type !== 'search' || !getComputedStyle(input).backdropFilter.includes('blur')) {
+                    retainInactive(candidate, existing);
                     continue;
+                }
                 const fabButton = binding.trigger;
                 const nativeTrigger = fabButton.shadowRoot?.querySelector('[part=native]');
-                if (binding.trigger.closest(excluded) ||
-                    back.closest(excluded) ||
+                if ((!pageUnavailable && binding.trigger.closest(excluded)) ||
+                    (!pageUnavailable && back.closest(excluded)) ||
                     back.disabled ||
                     fabButton.disabled ||
                     fabButton.color ||
@@ -186,16 +270,20 @@ export const createSearchSupport = (doc, id, schedule) => {
                     fabButton.href ||
                     !nativeTrigger ||
                     getComputedStyle(fabButton).backgroundColor !== 'rgba(0, 0, 0, 0)' ||
-                    !getComputedStyle(nativeTrigger).backdropFilter.includes('blur'))
+                    !getComputedStyle(nativeTrigger).backdropFilter.includes('blur')) {
+                    retainInactive(candidate, existing);
                     continue;
+                }
+                const state = existing ?? install(binding, bar, input);
                 const trigger = readIcon(binding.trigger, binding.trigger, candidate);
                 const searchIcon = bar.querySelector('.searchbar-search-icon');
                 const field = searchIcon && readIcon(searchIcon, bar, candidate);
-                if (!trigger || !field)
+                if (!trigger || !field) {
+                    retainInactive(candidate, state);
                     continue;
+                }
                 field.label = '';
                 field.accessibilityLabel = bar.getAttribute('aria-label') ?? input.getAttribute('aria-label') ?? 'Search';
-                const state = states.get(binding) ?? install(binding, bar, input);
                 state.layout = JSON.stringify([
                     innerWidth,
                     innerHeight,
@@ -215,16 +303,19 @@ export const createSearchSupport = (doc, id, schedule) => {
                     bar.placeholder,
                     bar.disabled,
                 ]);
-                if (state.rejectedLayout === state.layout)
+                if (state.rejectedLayout === state.layout) {
+                    retainInactive(candidate, state);
                     continue;
+                }
+                const available = !pageUnavailable && visible(binding.trigger);
                 candidate.control.search = {
                     id: id(input),
                     field,
                     trigger,
                     closeId: id(back),
-                    active: binding.active,
-                    available: true,
-                    focused: binding.focused,
+                    active: available && binding.active,
+                    available,
+                    focused: available && binding.focused,
                     value: bar.value ?? '',
                     placeholder: bar.placeholder ?? '',
                     disabled: bar.disabled,
@@ -232,9 +323,11 @@ export const createSearchSupport = (doc, id, schedule) => {
                     valueVersion: state.valueVersion,
                 };
                 state.last = candidate.control.search;
-                candidate.sources = [binding.tabBar, binding.trigger.closest('ion-fab') ?? binding.trigger, binding.footer];
-                candidate.actions.set(id(binding.trigger), binding.trigger);
-                candidate.actions.set(id(back), back);
+                if (available) {
+                    candidate.sources = [binding.tabBar, binding.trigger.closest('ion-fab') ?? binding.trigger, binding.footer];
+                    candidate.actions.set(id(binding.trigger), binding.trigger);
+                    candidate.actions.set(id(back), back);
+                }
             }
             for (const [candidate, configuration] of inactive)
                 (_a = candidate.control).search ?? (_a.search = configuration);
@@ -242,11 +335,26 @@ export const createSearchSupport = (doc, id, schedule) => {
             return candidates.filter((c) => !groups.some((group) => group !== c && group.sources?.some((source) => source.contains(c.element))));
         },
         projected,
+        hasActive() {
+            for (const [binding] of states)
+                if (binding.active && projected(binding))
+                    return true;
+            return false;
+        },
         begin(binding, revision) {
             const state = states.get(binding);
             if (state)
                 state.minimumRevision = revision;
         },
+        setStatus(binding, active, focused = false) {
+            if (!active) {
+                this.retire(binding);
+                return;
+            }
+            binding.active = true;
+            binding.focused = focused;
+            holdKeyboardResize();
+        },
         release(element) {
             for (const binding of states.keys())
                 if (binding.footer === element)
@@ -309,6 +417,7 @@ export const createSearchSupport = (doc, id, schedule) => {
                 state.input.dispatchEvent(new FocusEvent('blur'));
             }
             binding.active = binding.focused = false;
+            releaseKeyboardResize();
         },
         destroy() {
             states.forEach((state) => {
@@ -316,6 +425,7 @@ export const createSearchSupport = (doc, id, schedule) => {
                 state.restore();
             });
             states.clear();
+            releaseKeyboardResize();
         },
     };
 };

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

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

package/dist/native/runtime.js

@@ -137,7 +137,9 @@ export const createRuntime = async (doc, plugin, options = {}) => {
         for (const surface of moving.keys())
             if (!surface.isConnected)
                 moving.delete(surface);
-        if (doc.hidden || overlayOpen() || (win.visualViewport && (win.visualViewport.scale !== 1 || win.visualViewport.offsetTop !== 0)))
+        if (doc.hidden || overlayOpen())
+            return [];
+        if (win.visualViewport && (win.visualViewport.scale !== 1 || win.visualViewport.offsetTop !== 0) && !search.hasActive())
             return [];
         return unprojected(sources.keys(), () => search
             .decorate(Array.from(doc.querySelectorAll(selector))
@@ -230,6 +232,7 @@ export const createRuntime = async (doc, plugin, options = {}) => {
             }
             if (result.rejectedSearches?.length) {
                 search.reject(result.rejectedSearches);
+                lastSnapshot = '';
                 dirty = true;
             }
             for (const candidate of candidates) {
@@ -480,12 +483,16 @@ export const createRuntime = async (doc, plugin, options = {}) => {
             async search(binding, active, focus) {
                 if (!getNativeSearchBindings(doc).includes(binding) || !search.projected(binding))
                     return false;
-                if (active && !binding.active)
-                    search.begin(binding, revision + 1);
-                binding.active = active;
-                binding.focused = focus ?? (active && binding.focused);
-                if (!active)
-                    search.retire(binding);
+                if (!active) {
+                    search.setStatus(binding, false);
+                }
+                else {
+                    const entering = !binding.active;
+                    if (entering)
+                        search.begin(binding, revision + 1);
+                    const nextFocused = focus === true ? true : focus === false ? false : entering ? false : binding.focused;
+                    search.setStatus(binding, true, nextFocused);
+                }
                 await flush();
                 return !stopped && search.projected(binding);
             },

package/docs/ios-adaptive.md

@@ -4,7 +4,7 @@ title: Adaptive iOS themes
 
 # Adaptive iOS themes
 
-Use CSS feature queries to choose a theme while keeping Ionic's default iOS styles on older browsers. Safari 27 adds `:heading` support; see the [WebKit announcement](https://webkit.org/blog/17967/news-from-wwdc26-webkit-in-safari-27-beta/).
+Use CSS feature queries to choose a theme while keeping Ionic's default iOS styles on older browsers. The newer theme branch uses `overflow-anchor` support; see the [MDN `overflow-anchor` documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/overflow-anchor).
 
 These checks detect browser capabilities, not the operating system version. Other browsers may support the same features. Keep Ionic mode and platform-specific animation configuration consistent with your application.
 
@@ -15,7 +15,7 @@ In your global Sass stylesheet, use `meta.load-css` inside the feature query. Un
 ```scss
 @use 'sass:meta';
 
-@supports selector(:heading) {
+@supports (overflow-anchor: auto) {
   @include meta.load-css('@rdlabo/ionic-theme-ios27/src/styles/default-variables');
   @include meta.load-css('@rdlabo/ionic-theme-ios27/src/styles/ionic-theme-ios27');
   @include meta.load-css('@rdlabo/ionic-theme-ios27/src/styles/ionic-theme-ios27-dark-class');
@@ -23,6 +23,8 @@ In your global Sass stylesheet, use `meta.load-css` inside the feature query. Un
 }
 ```
 
+Configure animations from the same package as in the [README](https://docs.rdlabo.dev/projects/ionic-theme-ios27#configure-animations).
+
 ## Use the iOS 26 and iOS 27 themes together
 
 Install both packages:
@@ -36,14 +38,14 @@ Use this global Sass configuration instead of unconditional theme imports:
 ```scss
 @use 'sass:meta';
 
-@supports selector(:heading) {
+@supports (overflow-anchor: auto) {
   @include meta.load-css('@rdlabo/ionic-theme-ios27/src/styles/default-variables');
   @include meta.load-css('@rdlabo/ionic-theme-ios27/src/styles/ionic-theme-ios27');
   @include meta.load-css('@rdlabo/ionic-theme-ios27/src/styles/ionic-theme-ios27-dark-class');
   @include meta.load-css('@rdlabo/ionic-theme-ios27/src/styles/md-remove-ios-class-effect');
 }
 
-@supports (text-wrap: pretty) and (not selector(:heading)) {
+@supports (text-wrap: pretty) and (not (overflow-anchor: auto)) {
   @include meta.load-css('@rdlabo/ionic-theme-ios26/src/styles/default-variables');
   @include meta.load-css('@rdlabo/ionic-theme-ios26/src/styles/ionic-theme-ios26');
   @include meta.load-css('@rdlabo/ionic-theme-ios26/src/styles/ionic-theme-ios26-dark-class');
@@ -51,40 +53,37 @@ Use this global Sass configuration instead of unconditional theme imports:
 }
 ```
 
-The branches are mutually exclusive. Browsers without either feature retain Ionic's default styling. The `text-wrap: pretty` check preserves the earlier theme's capability-based fallback for older Safari versions.
+The branches are mutually exclusive. Browsers without either feature retain Ionic's default styling. The `text-wrap: pretty` check preserves the earlier theme's capability-based fallback when `overflow-anchor` is unavailable.
 
 Both examples use class-based dark mode. Load Ionic's matching dark palette in your application; for system or always-dark mode, replace the `-dark-class` imports with the matching variant. If you also use `md-ion-list-inset`, load the corresponding package's stylesheet inside each branch.
 
-## Select matching JavaScript animations
+### Page transition and overlay animations
 
-Use the same feature checks for dynamic imports before initializing Ionic. Call this loader for the iOS platform; leave other platforms on their existing animation configuration.
+When both packages are installed, keep **page transition** (`navAnimation`) on the iOS 27 animation. Styles still follow the feature queries above; only the transition stays on `@rdlabo/ionic-theme-ios27`. Use the same package for popover enter/leave so overlay motion stays consistent with that transition.
 
 ```ts
-async function loadIOSAnimations() {
+import { iosTransitionAnimation, popoverEnterAnimation, popoverLeaveAnimation } from '@rdlabo/ionic-theme-ios27';
+
+function loadIOSAnimations() {
   if (typeof CSS === 'undefined') {
     return {};
   }
 
-  const theme = CSS.supports('selector(:heading)')
-    ? await import('@rdlabo/ionic-theme-ios27')
-    : CSS.supports('text-wrap: pretty')
-      ? await import('@rdlabo/ionic-theme-ios26')
-      : undefined;
-
-  if (!theme) {
+  // Styles are adaptive; apply iOS theme animations when either generation matches.
+  if (!CSS.supports('overflow-anchor: auto') && !CSS.supports('text-wrap: pretty')) {
     return {};
   }
 
   return {
-    navAnimation: theme.iosTransitionAnimation,
-    popoverEnter: theme.popoverEnterAnimation,
-    popoverLeave: theme.popoverLeaveAnimation,
+    navAnimation: iosTransitionAnimation,
+    popoverEnter: popoverEnterAnimation,
+    popoverLeave: popoverLeaveAnimation,
   };
 }
 
-// In your browser bootstrap, before initializing Ionic:
-const animations = isPlatform('ios') ? await loadIOSAnimations() : {};
+// Resolve synchronously before bootstrapping so Ionic's global config exists before any element upgrades.
+const animations = isPlatform('ios') ? loadIOSAnimations() : {};
 provideIonicAngular({ ...animations });
 ```
 
-Import `isPlatform` and `provideIonicAngular` from your Ionic Angular entry point as shown in the README. Pass the same options to `setupIonicReact` or `IonicVue` when using those frameworks. The imports are selected at runtime; the bundler may still emit chunks for both packages. In server-rendered apps, run the selection during browser initialization.
+Import `isPlatform` and `provideIonicAngular` from your Ionic Angular entry point as shown in the README. Pass the same options to `setupIonicReact` or `IonicVue` when using those frameworks. In server-rendered apps, run the selection during browser initialization.

package/docs/native-ui-shell.md

@@ -46,7 +46,7 @@ Native appearance follows the applied class, system or always-dark theme CSS. Sy
 | `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                          |
-| `ion-tab-bar`                                 | Fixed tabs, icon-only/label-only items, one icon per item, dot/text badges, selection and disabled state                          | `UITabBar` and `UITabBarItem`                                         |
+| `ion-tab-bar`                                 | Fixed tabs, icon-only/label-only items, one icon per item, dot/text badges, selection and disabled state  | `UITabBar` and `UITabBarItem`                                         |
 | `ion-segment`                                 | Fixed toolbar, non-scrollable, text **or** one icon per item                                              | `UISegmentedControl`                                                  |
 | `ion-fab` / `ion-fab-button` / `ion-fab-list` | Glass FAB in an `ion-content` fixed slot; one main button and optional directional lists                  | Persistent glass `UIButton` per button; one FAB synchronization group |
 
@@ -92,7 +92,9 @@ Existing `attachTabBarSearchable(tabBar, fabButton, footer)` registrations autom
 
 Search registration does not bypass placement restrictions. Its searchbar and close button must be in fixed footer toolbars. Its trigger must belong to an `ion-fab[slot="fixed"]` directly inside `ion-content`, or directly on the existing non-scrolling `.ion-page` layout. A wrapper inside scrolling content is not a fixed slot.
 
-Opening search preserves the selected Ionic tab and does not automatically show the keyboard. Tap the search field or call the existing `ion-searchbar.setFocus()`. UIKit owns the search expansion, keyboard placement and return to the ordinary tabs. The trigger's resolved SVG and the search icon are projected from Ionic, including `ion-icon name`. The resting layout is measured against `ion-tab-bar` and both coordinates of the original FAB's center. A layout that cannot preserve those origins uses Web search.
+While a registration is alive, Native UI Shell keeps the searchable controller even when the page is transitioning or temporarily unavailable (`available: false`), instead of demoting back to a separate ordinary control identity. Resting chrome (including Album before search opens) uses the same `UITabBar` + `ShellTabBar.fit` path as ordinary tabs, with the search trigger pinned to the FAB when available; `UISearchTab` is shown only while the search session is active. Flipping availability or entering/leaving search crossfades between those layers. Register before the destination page finishes entering (for example in `ionViewWillEnter`) so the first visit does not paint ordinary tabs and then swap.
+
+Opening search preserves the selected Ionic tab and does not automatically show the keyboard (`automaticallyActivatesSearch` stays off). Tap the field or call `ion-searchbar.setFocus()` for the keyboard. While search is active, Native UI Shell freezes Web layout projection and holds Capacitor Keyboard resize at `none`; UIKit owns tab/search chrome (no Ionic `fit` mid-session). Leave re-fits ordinary tabs to `ion-tab-bar` and search to the FAB. Ordinary native tabs keep an optimistic selection until the Web `selected` state catches up. Input events and application `value` updates continue across the bridge until search closes. The trigger's resolved SVG and the search icon are projected from Ionic, including `ion-icon name`.
 
 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`.
 
@@ -247,5 +249,4 @@ On iOS, [`Components`](../ios/Sources/IonicNativeUIShellPlugin/Components) owns
 
 See the [demo and verification guide](../demo/native-ui-shell.md) for browser tests, Simulator tests and an independent SPM consumer built from the npm package.
 
-
 Search controllers retain their UIKit-managed transition and are excluded from the ordinary control acquisition crossfade.