@rdlabo/ionic-theme-ios27 1.1.0 → 1.2.0-0

package/src/native/components/ion-fab.ts

@@ -1,5 +1,5 @@
 import type { Candidate } from '../shared/candidate';
-import { excluded, isDark, text } from '../shared/dom';
+import { childElements, excluded, isDark, text } from '../shared/dom';
 import { iconSource } from '../shared/icons';
 import type { ShellItem } from '../definitions';
 
@@ -13,12 +13,12 @@ const hasHostMotion = (style: CSSStyleDeclaration): boolean =>
 // and resolved artwork, without inventing layout for display:none descendants.
 export const read = (fab: HTMLElement, id: (element: HTMLElement) => string): Candidate | undefined => {
   if (fab.slot !== 'fixed' || !fab.parentElement?.matches('ion-content') || fab.contains(fab.ownerDocument.activeElement)) return;
-  const children = Array.from(fab.children);
+  const children = childElements(fab);
   const main = children.filter((child) => child.matches('ion-fab-button'));
   const lists = children.filter((child) => child.matches('ion-fab-list'));
   if (main.length !== 1 || main.length + lists.length !== children.length) return;
-  if (lists.some((list) => list.closest(excluded) || Array.from(list.children).some((child) => !child.matches('ion-fab-button')))) return;
-  const buttons = [main[0], ...lists.flatMap((list) => Array.from(list.children))] as HTMLIonFabButtonElement[];
+  if (lists.some((list) => list.closest(excluded) || childElements(list).some((child) => !child.matches('ion-fab-button')))) return;
+  const buttons = [main[0], ...lists.flatMap((list) => childElements(list))] as HTMLIonFabButtonElement[];
   const style = getComputedStyle(fab);
   if (hasHostMotion(style)) return;
   const transform = new DOMMatrixReadOnly(style.transform);

package/src/native/components/ion-menu-button.ts

@@ -1,6 +1,6 @@
 import { createCandidate, appendItem } from '../shared/candidate';
 import type { Candidate, Identify } from '../shared/candidate';
-import { inFixedToolbar } from '../shared/dom';
+import { childElements, inFixedToolbar } from '../shared/dom';
 
 export const tag = 'ion-menu-button';
 // The glass and projection ownership belong to ion-buttons, even for one menu button.
@@ -14,9 +14,10 @@ export const append = (candidate: Candidate, button: HTMLIonMenuButtonElement, i
 };
 
 export const read = (group: HTMLElement, id: Identify): Candidate | undefined => {
-  if (!inFixedToolbar(group) || !group.matches('ion-buttons') || group.children.length !== 1) return;
-  const button = group.firstElementChild;
-  if (!button?.matches(`${tag}.ios`)) return;
+  const children = group.matches('ion-buttons') ? childElements(group) : [];
+  if (!inFixedToolbar(group) || children.length !== 1) return;
+  const button = children[0];
+  if (!button?.matches(`${tag}${group.closest('ion-app.ios-theme-vertical-bars') ? '' : '.ios'}`)) return;
   const candidate = createCandidate(group, tag, id);
   return append(candidate, button as HTMLIonMenuButtonElement, id) ? candidate : undefined;
 };

package/src/native/components/searchable-tabs.ts

@@ -202,7 +202,15 @@ export const createSearchSupport = (doc: Document, id: (element: Element) => str
       };
       for (const binding of bindings) {
         const candidate = candidates.find((c) => c.element === binding.tabBar);
-        if (!candidate || candidate.control.search || binding.tabBar.getAttribute('slot') !== 'bottom') continue;
+        // The vertical rail has no search surface; hiding the FAB/footer there
+        // would leave searchable tabs without any search control.
+        if (
+          !candidate ||
+          candidate.control.search ||
+          candidate.control.placement === 'vertical-bars' ||
+          binding.tabBar.getAttribute('slot') !== 'bottom'
+        )
+          continue;
         const fab = binding.trigger.parentElement;
         // Search also supports the existing page-level fixed FAB, outside scrolling content.
         if (

package/src/native/definitions.ts

@@ -15,6 +15,8 @@ export interface NativeUIShellOptions {
   enabled?: boolean;
   /** Controls eligible for native projection. Omit to enable every control; when present, only `true` controls are enabled. */
   controls?: NativeUIShellControls;
+  /** Internal: limit native projection to the Vertical Control Area. */
+  verticalBarsOnly?: boolean;
 }
 
 export interface NativeUIShellControls {
@@ -37,6 +39,26 @@ export interface NativeUIShellHandle {
   destroy(): Promise<void>;
 }
 
+/** Logical edge in the reading direction, matching UIVerticalBarEdge and capacitor-foldable. */
+export type VerticalBarEdge = 'leading' | 'trailing' | null;
+
+export interface VerticalBarPlacement {
+  edge: VerticalBarEdge;
+  /** UIKit safe-area inset on the vertical-bar edge, in points. */
+  inset: number;
+}
+
+export enum HingeStatus {
+  Closed = 'closed',
+  PartiallyOpen = 'partiallyOpen',
+  FullyOpen = 'fullyOpen',
+}
+
+export interface VerticalControlAreaHandle extends NativeUIShellHandle {
+  /** Applies the application's chosen placement to both Web and native controls. */
+  setPlacement(placement: VerticalBarEdge | VerticalBarPlacement, rtl?: boolean): void;
+}
+
 export interface NativeUIShellSuspension {
   /** Releases this suspension. Native projection resumes after all active suspensions are released. */
   resume(): Promise<void>;
@@ -83,6 +105,10 @@ export interface ShellItem extends Frame {
 export interface ShellControl extends Frame {
   id: string;
   kind: NativeUIShellComponent;
+  /** Lets the native host own adaptive placement instead of mirroring the DOM frame. */
+  placement?: 'vertical-bars';
+  /** Logical Ionic toolbar slot, preserved when projecting to the vertical rail. */
+  toolbarSlot?: 'start' | 'end';
   items: ShellItem[];
   dark: boolean;
   rtl: boolean;
@@ -116,6 +142,8 @@ export interface ShellSnapshot {
   revision: number;
   transitionDuration?: number;
   viewportWidth: number;
+  /** Physical side the native rail is drawn on; the runtime resolves the logical edge through the document direction. */
+  verticalBarEdge?: 'left' | 'right';
   controls: ShellControl[];
 }
 
@@ -130,12 +158,21 @@ export interface WebViewMetrics {
   radius: number;
 }
 
+export interface DeviceLayout {
+  placement: VerticalBarPlacement;
+  /** Fold hinge posture, or `null` when the device reports no hinge. */
+  hingeStatus: HingeStatus | null;
+  webViewMetrics: WebViewMetrics;
+}
+
 export interface NativeUIShellPlugin {
-  configure(): Promise<{ supported: boolean }>;
-  getWebViewMetrics(): Promise<WebViewMetrics>;
+  configure(options?: { verticalBarsOnly?: boolean }): Promise<{ supported: boolean }>;
+  getDeviceLayout(): Promise<DeviceLayout>;
+  startDeviceLayoutMonitoring(): Promise<void>;
+  stopDeviceLayoutMonitoring(): Promise<void>;
   update(snapshot: ShellSnapshot): Promise<{ revision: number; rejectedSearches?: string[]; rejectedControls?: string[] }>;
   clear(options: { revision: number }): Promise<void>;
   addListener(name: 'activate', listener: (event: ShellActivation) => void): Promise<PluginListenerHandle>;
   addListener(name: 'search', listener: (event: ShellSearchEvent) => void): Promise<PluginListenerHandle>;
-  addListener(name: 'webViewMetricsChange', listener: (event: WebViewMetrics) => void): Promise<PluginListenerHandle>;
+  addListener(name: 'deviceLayoutChange', listener: (event: DeviceLayout) => void): Promise<PluginListenerHandle>;
 }

package/src/native/index.ts

@@ -1,8 +1,17 @@
 import { Capacitor, registerPlugin } from '@capacitor/core';
 import { setConfig } from '../transition/ios.transition';
-import type { NativeUIShellHandle, NativeUIShellOptions, NativeUIShellPlugin, WebViewMetrics } from './definitions';
-import { bindMetricsLifecycle } from './lifecycle';
+import type {
+  NativeUIShellHandle,
+  NativeUIShellOptions,
+  NativeUIShellPlugin,
+  VerticalBarEdge,
+  VerticalBarPlacement,
+  VerticalControlAreaHandle,
+  WebViewMetrics,
+} from './definitions';
 import { createRuntime } from './runtime';
+import { createVerticalBarsWebProjection } from './vertical-bars-web';
+import { prehideVerticalBarsToolbarSources } from './prehide';
 export type {
   NativeUIShellComponent,
   NativeUIShellControls,
@@ -10,29 +19,128 @@ export type {
   NativeUIShellOptions,
   NativeUIShellStatus,
   NativeUIShellSuspension,
+  DeviceLayout,
+  VerticalBarEdge,
+  VerticalBarPlacement,
+  VerticalControlAreaHandle,
   WebViewMetrics,
 } from './definitions';
+export { HingeStatus } from './definitions';
 
 const plugin = registerPlugin<NativeUIShellPlugin>('IonicNativeUIShell');
+export const IonicNativeUIShell = plugin;
 let active: Promise<NativeUIShellHandle> | undefined;
+let activeConfiguration: string | undefined;
 const web = (reason: string): NativeUIShellHandle => ({
   getStatus: () => ({ state: 'web', projected: 0, updates: 0, reason }),
   suspend: async () => ({ resume: async () => {} }),
   destroy: async () => {},
 });
 
+const combine = (native: NativeUIShellHandle, fallback: NativeUIShellHandle): NativeUIShellHandle => ({
+  getStatus() {
+    const nativeStatus = native.getStatus();
+    const fallbackStatus = fallback.getStatus();
+    return {
+      ...nativeStatus,
+      state:
+        nativeStatus.state === 'stopped' && fallbackStatus.state === 'stopped' ? 'stopped' : nativeStatus.projected > 0 ? 'native' : 'web',
+      projected: nativeStatus.projected + fallbackStatus.projected,
+      updates: nativeStatus.updates + fallbackStatus.updates,
+    };
+  },
+  async suspend() {
+    const [nativeLease, fallbackLease] = await Promise.all([native.suspend(), fallback.suspend()]);
+    return { resume: async () => void (await Promise.all([nativeLease.resume(), fallbackLease.resume()])) };
+  },
+  async destroy() {
+    await Promise.all([native.destroy(), fallback.destroy()]);
+  },
+});
+
+/** Wraps a runtime handle with the shared enable-lifecycle: reason, suspend hooks and idempotent destroy. */
+const manage = (
+  handle: NativeUIShellHandle,
+  lifecycle: {
+    reason?: string;
+    suspend?: () => (() => void) | undefined;
+    /** Runs after teardown; clears the shared slot only while this activation owns it. */
+    release?: () => void;
+    destroy?: () => void | Promise<void>;
+  } = {},
+): NativeUIShellHandle => {
+  let destroyed = false;
+  return {
+    getStatus: () => (lifecycle.reason ? { ...handle.getStatus(), reason: lifecycle.reason } : handle.getStatus()),
+    async suspend() {
+      const lease = await handle.suspend();
+      const resume = lifecycle.suspend?.();
+      return {
+        async resume() {
+          await lease.resume();
+          resume?.();
+        },
+      };
+    },
+    async destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      try {
+        await handle.destroy();
+      } finally {
+        await lifecycle.destroy?.();
+        lifecycle.release?.();
+      }
+    },
+  };
+};
+
 /** Reads the current native WebView geometry and applies it to page transitions. */
 export const configureNativeTransition = async (): Promise<WebViewMetrics> => {
-  const metrics = typeof document !== 'undefined' && Capacitor.getPlatform() === 'ios' ? await plugin.getWebViewMetrics() : { radius: 0 };
+  const metrics =
+    typeof document !== 'undefined' && Capacitor.getPlatform() === 'ios' ? (await plugin.getDeviceLayout()).webViewMetrics : { radius: 0 };
   setConfig({ radius: metrics.radius });
   return metrics;
 };
 
+/** Resolves a logical vertical-bar edge to the physical side for the given direction. */
+const physicalVerticalBarEdge = (edge: Exclude<VerticalBarEdge, null>, rtl: boolean): 'left' | 'right' =>
+  (edge === 'leading') !== rtl ? 'left' : 'right';
+
+const elementRtl = (element: Element): boolean => element.closest('[dir]')?.getAttribute('dir') === 'rtl';
+
+/**
+ * Applies one placement to the CSS layout and both Web/native projections.
+ * Pass `rtl` when the document direction is known; otherwise the nearest `dir` attribute is used.
+ */
+export const setVerticalControlAreaPlacement = (placement: VerticalBarEdge | VerticalBarPlacement, rtl?: boolean): void => {
+  if (typeof document === 'undefined') return;
+  const app = document.querySelector<HTMLElement>('ion-app');
+  if (!app) throw new Error('Vertical Control Area requires ion-app');
+  const { edge, inset } = placement && typeof placement === 'object' ? placement : { edge: placement, inset: 0 };
+  app.classList.toggle('ios-theme-vertical-bars', edge !== null);
+  app.classList.toggle('ios-theme-vertical-bars-left', edge !== null && physicalVerticalBarEdge(edge, rtl ?? elementRtl(app)) === 'left');
+  if (edge && Number.isFinite(inset) && inset > 0) app.style.setProperty('--ios-theme-vertical-bars-native-inset', `${inset}px`);
+  else app.style.removeProperty('--ios-theme-vertical-bars-native-inset');
+};
+
+/** Call once at application startup. Ionic markup remains the source of truth. */
+export const enableVerticalControlArea = async (): Promise<VerticalControlAreaHandle> => {
+  const handle = await enableNativeUIShell({ controls: { tabs: true, toolbar: true }, verticalBarsOnly: true });
+  return {
+    getStatus: () => handle.getStatus(),
+    suspend: () => handle.suspend(),
+    destroy: () => handle.destroy(),
+    setPlacement: setVerticalControlAreaPlacement,
+  };
+};
+
 /** Call once at application startup. Ionic markup remains the source of truth. */
 export const enableNativeUIShell = (options: NativeUIShellOptions = {}): Promise<NativeUIShellHandle> => {
   if (options.enabled === false) {
     const current = active;
     active = undefined;
+    activeConfiguration = undefined;
     return current
       ? current.then(async (handle) => {
           await handle.destroy();
@@ -40,23 +148,83 @@ export const enableNativeUIShell = (options: NativeUIShellOptions = {}): Promise
         })
       : Promise.resolve(web('Disabled'));
   }
-  if (typeof document === 'undefined' || Capacitor.getPlatform() !== 'ios') return Promise.resolve(web('Requires Capacitor iOS'));
-  return (active ??= (async () => {
-    try {
-      await configureNativeTransition().catch(() => undefined);
-      if (!(await plugin.configure()).supported) {
-        active = undefined;
-        return web('Requires iOS 26 or later');
-      }
-      const runtime = await createRuntime(document, plugin, options);
-      return await bindMetricsLifecycle(
-        runtime,
-        () => plugin.addListener('webViewMetricsChange', (metrics) => setConfig({ radius: metrics.radius })),
-        () => (active = undefined),
-      );
-    } catch (error) {
+  if (typeof document === 'undefined') return Promise.resolve(web('Requires a document'));
+  const controls = options.controls;
+  const configuration = JSON.stringify([
+    options.verticalBarsOnly === true,
+    ...(['tabs', 'toolbar', 'segment', 'fab'] as const).map((component) => !controls || controls[component] === true),
+  ]);
+  if (active && activeConfiguration !== configuration)
+    return Promise.reject(
+      new Error('Native UI Shell is already running with different controls; destroy it before changing configuration.'),
+    );
+  if (active) return active;
+  activeConfiguration = configuration;
+  const prehide =
+    options.controls === undefined || options.controls.toolbar === true ? prehideVerticalBarsToolbarSources(document) : undefined;
+  // A slow destroy of a superseded activation must not release a newer one.
+  let start: Promise<NativeUIShellHandle>;
+  const release = () => {
+    if (active === start) {
       active = undefined;
-      return web(error instanceof Error ? error.message : String(error));
+      activeConfiguration = undefined;
     }
-  })());
+  };
+  const fallback = (reason: string) =>
+    manage(createVerticalBarsWebProjection(document, options), {
+      reason,
+      suspend: () => prehide?.suspend(),
+      destroy: () => prehide?.stop(),
+      release,
+    });
+  return (start = active =
+    (async () => {
+      if (Capacitor.getPlatform() !== 'ios') return fallback('Requires Capacitor iOS');
+      let runtime: NativeUIShellHandle | undefined;
+      let placementListener: Awaited<ReturnType<typeof plugin.addListener>> | undefined;
+      let monitoring = false;
+      try {
+        if (!options.verticalBarsOnly) await configureNativeTransition().catch(() => undefined);
+        const capabilities = await plugin.configure({ verticalBarsOnly: options.verticalBarsOnly === true });
+        if (!capabilities.supported) return fallback('Requires iOS 26 or later');
+        let nativeEdge: VerticalBarEdge = null;
+        const nativeVerticalBars = () => {
+          const root = document.querySelector('ion-app.ios-theme-vertical-bars');
+          if (!root) return false;
+          // The trait stays unspecified when the OS cannot report a rail — for
+          // example an app linked against an SDK older than 27.1 — so the DOM
+          // class is trusted there. When the OS does report an edge, the native
+          // rail only takes over once the app has applied the matching class.
+          const domEdge = root.classList.contains('ios-theme-vertical-bars-left') ? 'left' : 'right';
+          return nativeEdge === null || physicalVerticalBarEdge(nativeEdge, elementRtl(root)) === domEdge;
+        };
+        await plugin.startDeviceLayoutMonitoring();
+        monitoring = true;
+        placementListener = await plugin.addListener('deviceLayoutChange', ({ placement, webViewMetrics }) => {
+          nativeEdge = placement.edge;
+          if (!options.verticalBarsOnly) setConfig({ radius: webViewMetrics.radius });
+          document.defaultView?.dispatchEvent(new Event('nativeUIShellRefresh'));
+        });
+        nativeEdge = (await plugin.getDeviceLayout()).placement.edge;
+        const native = await createRuntime(document, plugin, options, nativeVerticalBars, options.verticalBarsOnly === true);
+        runtime = combine(
+          native,
+          createVerticalBarsWebProjection(document, options, () => !nativeVerticalBars() || native.getStatus().state === 'stopped'),
+        );
+        return manage(runtime, {
+          suspend: () => prehide?.suspend(),
+          release,
+          destroy: async () => {
+            await placementListener?.remove().catch(() => {});
+            if (monitoring) await plugin.stopDeviceLayoutMonitoring().catch(() => {});
+            prehide?.stop();
+          },
+        });
+      } catch (error) {
+        await runtime?.destroy();
+        await placementListener?.remove().catch(() => {});
+        if (monitoring) await plugin.stopDeviceLayoutMonitoring().catch(() => {});
+        return fallback(error instanceof Error ? error.message : String(error));
+      }
+    })());
 };

package/src/native/prehide.ts

@@ -0,0 +1,255 @@
+import { LIFECYCLE_DID_ENTER, LIFECYCLE_DID_LEAVE, LIFECYCLE_WILL_ENTER, LIFECYCLE_WILL_LEAVE } from '@ionic/core';
+import { VERTICAL_BARS_TRANSITION_CANCELED } from '../native-integration';
+import {
+  childElements,
+  clearVerticalBarsPlacement,
+  createVerticalBarsPageState,
+  verticalBarsActionCandidate,
+  verticalBarsBackCandidate,
+  verticalBarsBackWebClass,
+  verticalBarsOwned,
+  isVerticalBarsToolbarActionShape,
+  isPermanentlyExcluded,
+  isShellDisabled,
+  prehiddenClass,
+  prehideRootClass,
+  rejectedClass,
+  setVerticalBarsPlacement,
+} from './shared/dom';
+
+const overlays = 'ion-menu, ion-modal, ion-popover';
+const sourceSelector = 'ion-back-button, ion-menu-button, ion-buttons, ion-button';
+// Realm- and teardown-safe: globals such as Element/HTMLElement may be gone
+// when a queued mutation microtask or a stale listener still runs.
+const isHtmlElement = (node: unknown): node is HTMLElement => !!node && (node as Node).nodeType === 1;
+const asElement = (node: Node | EventTarget | null): HTMLElement | undefined => (isHtmlElement(node) ? node : undefined);
+const backSupported = (element: HTMLElement): boolean => {
+  const back = element as HTMLIonBackButtonElement;
+  return back.icon === undefined && back.color === undefined && !!back.shadowRoot;
+};
+const eligibleBack = verticalBarsBackCandidate;
+const eligible = verticalBarsActionCandidate;
+
+/** Capture toolbar placement once per routed-page epoch, before Ionic paints its transition. */
+export const prehideVerticalBarsToolbarSources = (doc: Document): { suspend: () => () => void; stop: () => void } => {
+  doc.documentElement.classList.add(prehideRootClass);
+  const scopes = new Map<HTMLElement, Set<HTMLElement>>();
+  const owner = new WeakMap<HTMLElement, HTMLElement>();
+  const pendingBacks = new Map<HTMLElement, { scope: HTMLElement; timer: ReturnType<typeof setTimeout> }>();
+  const verticalBarsPages = createVerticalBarsPageState();
+  const listeners = new AbortController();
+  const root = () => doc.querySelector<HTMLElement>('ion-app.ios-theme-vertical-bars');
+  let suspended = 0;
+  let stopped = false;
+  const routedPage = (element: HTMLElement) => element.closest<HTMLElement>('.ion-page:not(ion-app, body)');
+  const release = (scope: HTMLElement) => {
+    for (const [element, pending] of pendingBacks) {
+      if (pending.scope !== scope) continue;
+      clearTimeout(pending.timer);
+      pendingBacks.delete(element);
+    }
+    const owned = scopes.get(scope);
+    if (!owned) return;
+    owned.forEach((element) => {
+      if (owner.get(element) !== scope) return;
+      owner.delete(element);
+      element.classList.remove(prehiddenClass);
+      element.classList.remove(verticalBarsBackWebClass);
+      clearVerticalBarsPlacement(element);
+    });
+    scopes.delete(scope);
+  };
+  const capture = (scope: HTMLElement) => {
+    if (!root()?.contains(scope) || scope.closest(overlays) || verticalBarsPages.isDeparted(scope)) return;
+    const owned = scopes.get(scope) ?? new Set<HTMLElement>();
+    const place = (element: HTMLElement, rail: boolean) => {
+      if (owned.has(element)) return;
+      const previousScope = owner.get(element);
+      if (previousScope) scopes.get(previousScope)?.delete(element);
+      owner.set(element, scope);
+      setVerticalBarsPlacement(element, rail);
+      if (element.matches('ion-back-button')) element.classList.toggle(verticalBarsBackWebClass, !rail);
+      owned.add(element);
+    };
+    const sources = scope.matches('ion-back-button') ? [scope] : Array.from(scope.querySelectorAll<HTMLElement>(sourceSelector));
+    sources.forEach((element) => {
+      if (element.closest(overlays) || (scope.matches('.ion-page') && routedPage(element) !== scope)) return;
+      if (element.matches('ion-buttons')) {
+        const children = childElements(element);
+        const actions = children.filter((child) => eligible(child) && isVerticalBarsToolbarActionShape(child));
+        const group =
+          eligible(element) &&
+          actions.length === children.length &&
+          (actions.length > 1 || (actions.length === 1 && actions[0].matches('ion-menu-button')));
+        const freshGroup = !owned.has(element);
+        place(element, group);
+        children.forEach((child) => {
+          if (!child.matches('ion-back-button')) place(child, freshGroup && actions.includes(child));
+        });
+      } else if (element.matches('ion-back-button') || !element.parentElement?.matches('ion-buttons')) {
+        if (owned.has(element)) return;
+        if (
+          element.matches('ion-back-button') &&
+          eligibleBack(element) &&
+          (element as HTMLIonBackButtonElement).icon === undefined &&
+          (element as HTMLIonBackButtonElement).color === undefined &&
+          !element.shadowRoot &&
+          !element.classList.contains('hydrated')
+        ) {
+          const previousPending = pendingBacks.get(element);
+          if (previousPending && previousPending.scope !== scope) {
+            clearTimeout(previousPending.timer);
+            pendingBacks.delete(element);
+          }
+          if (!pendingBacks.has(element)) {
+            const timer = setTimeout(() => {
+              if (pendingBacks.get(element)?.scope !== scope) return;
+              pendingBacks.delete(element);
+              // A custom element that never hydrates must remain usable on Web.
+              place(element, false);
+              reconcile();
+            }, 1500);
+            pendingBacks.set(element, { scope, timer });
+          }
+          return;
+        }
+        const pending = pendingBacks.get(element);
+        if (pending) {
+          clearTimeout(pending.timer);
+          pendingBacks.delete(element);
+        }
+        place(
+          element,
+          element.matches('ion-back-button')
+            ? eligibleBack(element) && backSupported(element)
+            : eligible(element) && isVerticalBarsToolbarActionShape(element),
+        );
+      }
+    });
+    scopes.set(scope, owned);
+  };
+  const reconcile = () => {
+    const verticalBars = root();
+    if (!verticalBars) {
+      Array.from(scopes.keys()).forEach(release);
+      return;
+    }
+    for (const scope of scopes.keys()) if (!scope.isConnected) release(scope);
+    for (const [element, pending] of pendingBacks) if (element.shadowRoot || element.classList.contains('hydrated')) capture(pending.scope);
+    // Ionic inserts the destination as invisible before WillEnter. Hide its
+    // sources in that same mutation microtask; capture new DOM identities on active pages too.
+    verticalBars.querySelectorAll<HTMLElement>('.ion-page:not(ion-app, body, .ion-page-hidden)').forEach(capture);
+    // Root toolbars can mount after startup; each new DOM identity is captured once.
+    verticalBars.querySelectorAll<HTMLElement>(sourceSelector).forEach((element) => {
+      if (routedPage(element) || element.closest(overlays)) return;
+      const scope = element.closest<HTMLElement>('ion-toolbar') ?? (element.matches('ion-back-button') ? element : null);
+      if (scope) capture(scope);
+    });
+    for (const owned of scopes.values()) {
+      for (const element of owned) {
+        const groupOwnsChildren =
+          element.parentElement?.matches('ion-buttons') &&
+          verticalBarsOwned(element.parentElement) &&
+          childElements(element.parentElement).every((child) => verticalBarsOwned(child));
+        const hide =
+          !suspended &&
+          verticalBarsOwned(element) &&
+          !groupOwnsChildren &&
+          element.isConnected &&
+          !element.closest(`.${rejectedClass}`) &&
+          !isPermanentlyExcluded(element) &&
+          !isShellDisabled(element) &&
+          (!element.matches('ion-back-button') || backSupported(element) || !element.classList.contains('hydrated')) &&
+          (!element.matches('ion-buttons') || childElements(element).every((child) => verticalBarsOwned(child)));
+        element.classList.toggle(prehiddenClass, hide);
+        if (element.matches('ion-back-button')) element.classList.toggle(verticalBarsBackWebClass, !hide);
+      }
+    }
+  };
+  const onWillEnter = (event: Event) => {
+    const page = asElement(event.target);
+    if (page?.matches('.ion-page')) {
+      verticalBarsPages.lifecycle(event);
+      release(page); // Cached pages begin a new placement epoch.
+      capture(page);
+      reconcile();
+    }
+  };
+  const onPageLifecycle: EventListener = (event) => {
+    verticalBarsPages.lifecycle(event);
+    if (event.type !== LIFECYCLE_DID_LEAVE) return;
+    const page = asElement(event.target);
+    if (page) release(page);
+  };
+  // A canceled transition keeps the leaving page active and abandons the entering one.
+  const onTransitionCanceled: EventListener = (event) => {
+    const leaving = asElement(event.target);
+    if (!leaving) return;
+    const entering = (event as CustomEvent<{ entering?: HTMLElement }>).detail?.entering;
+    verticalBarsPages.cancel(entering, leaving);
+    reconcile();
+  };
+  doc.addEventListener(LIFECYCLE_WILL_ENTER, onWillEnter, { capture: true, signal: listeners.signal });
+  for (const name of [LIFECYCLE_WILL_LEAVE, LIFECYCLE_DID_ENTER, LIFECYCLE_DID_LEAVE])
+    doc.addEventListener(name, onPageLifecycle, { capture: true, signal: listeners.signal });
+  doc.addEventListener(VERTICAL_BARS_TRANSITION_CANCELED, onTransitionCanceled, { capture: true, signal: listeners.signal });
+  reconcile();
+  const mutationRelevant = (record: MutationRecord) => {
+    if (record.type === 'childList')
+      return [...Array.from(record.addedNodes), ...Array.from(record.removedNodes)].some(
+        (node) =>
+          isHtmlElement(node) &&
+          (node.matches(`${sourceSelector}, .ion-page, ion-toolbar`) || !!node.querySelector(`${sourceSelector}, .ion-page, ion-toolbar`)),
+      );
+    if (record.attributeName !== 'class') return true;
+    const current = (record.target as Element).className;
+    const previous = record.oldValue ?? '';
+    const withoutOwned = (value: string) =>
+      value
+        .split(/\s+/)
+        .filter((name) => name && ![prehiddenClass, prehideRootClass, verticalBarsBackWebClass].includes(name))
+        .join(' ');
+    return typeof current !== 'string' || withoutOwned(previous) !== withoutOwned(current);
+  };
+  let scheduled = false;
+  const observer = new (doc.defaultView?.MutationObserver ?? MutationObserver)((records) => {
+    if (scheduled || stopped || !records.some(mutationRelevant)) return;
+    scheduled = true;
+    queueMicrotask(() => {
+      scheduled = false;
+      if (!stopped) reconcile();
+    });
+  });
+  observer.observe(doc.documentElement, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+    attributeOldValue: true,
+    attributeFilter: ['class', 'hidden', 'inert', 'icon', 'color'],
+  });
+  return {
+    suspend: () => {
+      if (stopped) return () => {};
+      suspended++;
+      doc.documentElement.classList.remove(prehideRootClass);
+      reconcile();
+      let resumed = false;
+      return () => {
+        if (resumed || stopped) return;
+        resumed = true;
+        if (--suspended === 0) {
+          doc.documentElement.classList.add(prehideRootClass);
+          reconcile();
+        }
+      };
+    },
+    stop: () => {
+      if (stopped) return;
+      stopped = true;
+      observer.disconnect();
+      listeners.abort();
+      doc.documentElement.classList.remove(prehideRootClass);
+      Array.from(scopes.keys()).forEach(release);
+    },
+  };
+};