@rdlabo/capacitor-native-ui 0.0.0-stage → 1.2.1

package/src/native/html.ts

@@ -0,0 +1,193 @@
+import { fitsClip } from './shared/clipping';
+import type { NativeUIRuntimeOptions, NativeUIRuntimeHandle } from './definitions';
+import { appendItem, createCandidate, type Candidate, type Identify } from './shared/candidate';
+import { marker, unprojected, visible } from './shared/dom';
+
+/** Standard HTML sources use standard native renderers, not app-local Swift extensions. */
+export const htmlSelector = '[data-native-ui="button"], [data-native-ui="back-button"]';
+export const htmlRailSource = (element: Element) =>
+  element.matches(htmlSelector) && element.getAttribute('data-native-ui-placement') === 'rail';
+
+export const readHTMLControl = (element: HTMLElement, id: Identify, options: NativeUIRuntimeOptions): Candidate | undefined => {
+  if (
+    !(options.root ?? element.ownerDocument.body).contains(element) ||
+    !element.matches(htmlSelector) ||
+    element.closest('[data-native-ui-proxy]')
+  )
+    return;
+  // Explicit opt-in; custom elements can implement click() and expose role=button.
+  if (!element.matches('button, ion-button, [role="button"]') || !visible(element, htmlRailSource(element))) return;
+  if (element.contains(element.ownerDocument.activeElement)) return;
+  if (!htmlRailSource(element) && !fitsClip(element)) return;
+  if (
+    options.explicitControls === false ||
+    (options.explicitControls === undefined && (options.controls?.toolbar === false || options.controls?.buttons === false))
+  )
+    return;
+  if (htmlRailSource(element) && options.verticalBars?.enabled === false) return;
+  const kind = element.getAttribute('data-native-ui') === 'back-button' ? 'back-button' : 'button';
+  const candidate = createCandidate(element, kind, id, options);
+  const item = appendItem(candidate, element, id);
+  if (!item) return;
+  const labelledBy = element
+    .getAttribute('aria-labelledby')
+    ?.trim()
+    .split(/\s+/)
+    .map((key) => element.ownerDocument.getElementById(key)?.textContent?.trim() ?? '')
+    .filter(Boolean)
+    .join(' ');
+  item.accessibilityLabel = labelledBy || element.getAttribute('aria-label') || item.label;
+  if (!item.accessibilityLabel) return;
+  item.disabled ||= element.matches(':disabled, [disabled]') || !!element.closest('[aria-disabled="true"]');
+  if (htmlRailSource(element)) candidate.control.placement = 'vertical-bars';
+  return candidate;
+};
+
+/** A rail host is supplied and styled by the application, never by the plugin. */
+export const createHTMLWebProjection = (doc: Document, options: NativeUIRuntimeOptions): NativeUIRuntimeHandle => {
+  const host = options.rail?.host;
+  if (!host) {
+    let stopped = false;
+    return {
+      markForCheck: () => {},
+      getStatus: () => ({ state: stopped ? 'stopped' : 'web', projected: 0, updates: 0 }),
+      suspend: async () => ({ resume: async () => {} }),
+      destroy: async () => {
+        stopped = true;
+      },
+    };
+  }
+  const win = doc.defaultView!;
+  const owned = new Map<HTMLElement, { clone: HTMLButtonElement; aria: string | null; signature: string }>();
+  const style = doc.createElement('style');
+  style.textContent = `[data-native-ui-web-source] { visibility: hidden !important; pointer-events: none !important; }`;
+  doc.head.append(style);
+  let frame = 0;
+  let stopped = false;
+  let suspended = 0;
+  let updates = 0;
+  const restore = (source: HTMLElement) => {
+    const state = owned.get(source);
+    if (!state) return;
+    const focused = state.clone.contains(doc.activeElement);
+    state.clone.remove();
+    source.removeAttribute('data-native-ui-web-source');
+    if (focused && source.isConnected && !source.hasAttribute(marker)) source.focus();
+    owned.delete(source);
+  };
+  const measure = <T>(source: HTMLElement, read: () => T): T => {
+    const hidden = source.hasAttribute('data-native-ui-web-source');
+    if (hidden) source.removeAttribute('data-native-ui-web-source');
+    try {
+      return unprojected([source], read);
+    } finally {
+      if (hidden) source.setAttribute('data-native-ui-web-source', '');
+    }
+  };
+  const render = () => {
+    frame = 0;
+    if (stopped) return;
+    observer.disconnect();
+    observer.observe(doc.documentElement, { subtree: true, childList: true, attributes: true, characterData: true });
+    const wanted = new Set<HTMLElement>();
+    if (!suspended && options.verticalBars?.enabled !== false && host?.isConnected && options.root?.isConnected) {
+      const sources = Array.from(options.root.querySelectorAll<HTMLElement>(htmlSelector));
+      let back = false;
+      for (const source of sources) {
+        // An accepted native surface owns its source and descendants. Rejected sources
+        // lose the marker and can return to the Web rail on the next render.
+        if (!htmlRailSource(source) || host.contains(source) || source.closest(`[${marker}]`)) continue;
+        const iconRoot = source.querySelector('ion-icon')?.shadowRoot;
+        if (iconRoot) observer.observe(iconRoot, { subtree: true, childList: true, attributes: true, characterData: true });
+        const candidate = measure(source, () => readHTMLControl(source, () => 'web', options));
+        if (!candidate) continue;
+        if (candidate.control.kind === 'back-button') {
+          if (back) continue;
+          back = true;
+        }
+        wanted.add(source);
+        const item = candidate.control.items[0];
+        const svg = source.querySelector('svg') ?? iconRoot?.querySelector('svg');
+        const signature = JSON.stringify([item, source.innerHTML, svg?.outerHTML]);
+        let state = owned.get(source);
+        if (!state) {
+          const clone = doc.createElement('button');
+          clone.type = 'button';
+          clone.setAttribute('data-native-ui-proxy', candidate.control.kind);
+          state = { clone, aria: source.getAttribute('aria-hidden'), signature: '' };
+          owned.set(source, state);
+          clone.addEventListener('click', () => {
+            const current = !stopped && !suspended && measure(source, () => readHTMLControl(source, () => 'web', options));
+            if (
+              options.verticalBars?.enabled === false ||
+              !current ||
+              !htmlRailSource(source) ||
+              !host.isConnected ||
+              current.control.items[0].disabled ||
+              source.closest(`[${marker}]`)
+            )
+              return;
+            source.click(); // Source owns submission, custom handlers and back navigation.
+            schedule();
+          });
+          host.append(clone);
+        }
+        if (state.signature !== signature) {
+          state.signature = signature;
+          state.clone.replaceChildren();
+          if (svg) {
+            const icon = svg.cloneNode(true) as SVGElement;
+            icon.querySelectorAll('[id]').forEach((node) => node.removeAttribute('id'));
+            icon.removeAttribute('id');
+            for (const node of [icon, ...Array.from(icon.querySelectorAll('*'))])
+              for (const attr of Array.from(node.attributes)) if (attr.name.startsWith('on')) node.removeAttribute(attr.name);
+            state.clone.append(icon);
+          }
+          state.clone.append(doc.createTextNode(item.label));
+          state.clone.setAttribute('aria-label', item.accessibilityLabel);
+          state.clone.disabled = item.disabled;
+          updates++;
+        }
+        if (!source.hasAttribute('data-native-ui-web-source')) source.setAttribute('data-native-ui-web-source', '');
+      }
+    }
+    for (const source of owned.keys()) if (!wanted.has(source)) restore(source);
+    // Ignore our own synchronous DOM writes; later application mutations still schedule a refresh.
+    observer.takeRecords();
+  };
+  const schedule = () => {
+    if (!stopped && !frame) frame = win.requestAnimationFrame(render);
+  };
+  const observer = new MutationObserver(schedule);
+  win.addEventListener('resize', schedule);
+  win.addEventListener('nativeUIRefresh', schedule);
+  render();
+  return {
+    markForCheck: schedule,
+    getStatus: () => ({ state: stopped ? 'stopped' : 'web', projected: owned.size, updates }),
+    async suspend() {
+      suspended++;
+      for (const source of owned.keys()) restore(source);
+      let resumed = false;
+      return {
+        async resume() {
+          if (!resumed) {
+            resumed = true;
+            suspended--;
+            render();
+          }
+        },
+      };
+    },
+    async destroy() {
+      if (stopped) return;
+      stopped = true;
+      observer.disconnect();
+      win.cancelAnimationFrame(frame);
+      win.removeEventListener('resize', schedule);
+      win.removeEventListener('nativeUIRefresh', schedule);
+      for (const source of owned.keys()) restore(source);
+      style.remove();
+    },
+  };
+};

package/src/native/index.ts

@@ -0,0 +1,41 @@
+// Compatibility Ionic entrypoint. Standard HTML consumers can import /core without Ionic.
+import { startNativeUI as activate } from './startup';
+import type { NativeUIOptions, VerticalControlAreaOptions, VerticalControlAreaHandle } from './definitions';
+import { setVerticalControlAreaPlacement } from './legacy-layout';
+export { setVerticalControlAreaPlacement } from './legacy-layout';
+export { configureNativeTransition, NativeUI } from './activation';
+export { defineNativeUI } from './extensions';
+export type { NativeUIExtension, NativeUIValue, NativeUIReadContext, NativeUIImageReference } from './extensions';
+export type {
+  NativeUIVerticalBarsOptions,
+  NativeUIComponent,
+  NativeUIControls,
+  AutoIonicControls,
+  IonicProjectionOptions,
+  NativeUIHandle,
+  NativeUIOptions,
+  NativeUIStatus,
+  NativeUISuspension,
+  VerticalBarEdge,
+  VerticalBarPlacement,
+  VerticalControlAreaHandle,
+  ToolbarProjectionOptions,
+  VerticalControlAreaOptions,
+  WebViewMetrics,
+} from './definitions';
+
+export const enableNativeUI = (options: NativeUIOptions = {}) =>
+  activate(options, async (...args) => (await import('./overlays/controller')).createOverlayController(...args));
+
+export const enableVerticalControlArea = async (options: VerticalControlAreaOptions = {}): Promise<VerticalControlAreaHandle> => {
+  const handle = await enableNativeUI({
+    extensions: options.extensions,
+    horizontal: options.horizontal,
+    vertical: options.vertical,
+    buttonProjection: options.buttonProjection,
+    buttonDefaultFill: options.buttonDefaultFill,
+    controls: { tabs: true, toolbar: true, popover: options.controls?.popover === true },
+    verticalBarsOnly: true,
+  });
+  return { ...handle, setPlacement: setVerticalControlAreaPlacement };
+};

package/src/native/legacy-layout.ts

@@ -0,0 +1,21 @@
+import type { VerticalBarEdge, VerticalBarPlacement } from './definitions';
+const physicalVerticalBarEdge = (edge: Exclude<VerticalBarEdge, null>, rtl: boolean) => ((edge === 'leading') !== rtl ? 'left' : 'right');
+const elementRtl = (element: Element): boolean => element.closest('[dir]')?.getAttribute('dir') === 'rtl';
+
+/**
+ * @deprecated Use the theme setVerticalBarsLayout helper. nativeEdge is ignored; device metrics determine availability.
+ * Legacy Web layout adapter; does not report native availability.
+ * 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 = 0 } = placement && typeof placement === 'object' ? placement : { edge: placement, inset: 0 };
+  app.removeAttribute('data-native-ui-vertical-bars-suspended');
+  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');
+  document.defaultView?.dispatchEvent(new Event('nativeUIRefresh'));
+};

package/src/native/overlays/content.ts

@@ -0,0 +1,51 @@
+import { sheetText } from './styles';
+
+/** Constructed stylesheets cannot cross documents with their nodes. */
+export const moveContent = (content: HTMLElement[], destination: HTMLElement): (() => void) => {
+  const home = content.map((element) => ({ element, parent: element.parentNode!, next: element.nextSibling }));
+  const roots: { root: ShadowRoot; css: string; sheets: CSSStyleSheet[] }[] = [];
+  const collect = (node: Element) => {
+    if (node.shadowRoot) {
+      roots.push({
+        root: node.shadowRoot,
+        css: sheetText(node.shadowRoot.adoptedStyleSheets),
+        sheets: [...node.shadowRoot.adoptedStyleSheets],
+      });
+      for (const child of Array.from(node.shadowRoot.children)) collect(child);
+    }
+    for (const child of Array.from(node.children)) collect(child);
+  };
+  content.forEach(collect);
+  for (const element of content) destination.append(destination.ownerDocument.adoptNode(element));
+  const styles = roots
+    .filter(({ css }) => css)
+    .map(({ root, css }) => {
+      const style = destination.ownerDocument.createElement('style');
+      style.textContent = css;
+      root.append(style);
+      return style;
+    });
+  return () => {
+    styles.forEach((style) => style.remove());
+    for (const { element, parent, next } of home) {
+      const connected = element.isConnected;
+      parent.ownerDocument!.adoptNode(element);
+      // Ionic may already have destroyed the Angular component on dismiss.
+      if (connected) parent.insertBefore(element, next?.parentNode === parent ? next : null);
+    }
+    for (const { root, css, sheets } of roots) {
+      // WebKit re-associates adopted sheets with the new document across
+      // adoptNode, so they may no longer match this root; fall back to the
+      // inline copy instead of aborting the remaining restore.
+      try {
+        root.adoptedStyleSheets = sheets;
+      } catch {
+        if (css) {
+          const style = root.ownerDocument.createElement('style');
+          style.textContent = css;
+          root.append(style);
+        }
+      }
+    }
+  };
+};

package/src/native/overlays/controller.ts

@@ -0,0 +1,349 @@
+import type { NativeUIOptions, NativeUIPlugin } from '../definitions';
+import { bounded, boundedListener } from '../shared/bridge';
+import { isExcluded, isPermanentlyExcluded, isNativeUIDisabled } from '../shared/dom';
+import { activeElement, trapFocus } from './focus';
+import { relayPopover, popoverPresentation, verticalBarsPopoverAnchor } from './popover';
+import { nativeDialogAnimation } from './dialog-animation';
+import { relayLayoutSupported, relayStyles } from './styles';
+import { moveContent } from './content';
+import { validVerticalBarFrame } from '../shared/vertical-bars-geometry';
+
+type Presentation = { kind: 'popover'; animated: boolean };
+type Overlay = HTMLIonPopoverElement;
+const lifecycle = (overlay: Overlay, phase: string) =>
+  `ion${overlay.localName.slice(4, 5).toUpperCase()}${overlay.localName.slice(5)}${phase}`;
+
+interface Connection {
+  id: string;
+  overlay: Overlay;
+  dismissed: boolean;
+  win?: Window;
+  focus: Element | null;
+  stopStyles?: () => void;
+  releaseProjection?: () => void;
+  stopContent?: () => void;
+  stopFocus?: () => void;
+  stopEvents?: () => void;
+  stopChildEvents?: () => void;
+  stopExclusions?: () => void;
+  closing?: Promise<void>;
+  nativeClosing?: Promise<void>;
+  stopAnimation?: () => void;
+  hideAnimation?: () => void;
+  stopLifecycle?: () => void;
+}
+
+/** Ionic owns lifecycle and dismissal; only one overlay is relayed at a time. */
+export const createOverlayController = async (
+  doc: Document,
+  plugin: NativeUIPlugin,
+  options: NativeUIOptions,
+  retainProjection: (deferActivation?: (id: string) => boolean) => () => void,
+  nativeVerticalBars: () => boolean,
+) => {
+  let current: Connection | undefined;
+  let opening = Promise.resolve();
+  let sequence = 0;
+  let stopped = false;
+  const suspensions = new Set<symbol>();
+  const events = ['Modal', 'Popover', 'Alert', 'ActionSheet', 'Loading', 'Picker', 'Toast'].map((name) => `ion${name}WillPresent`);
+  const cleanup = async (connection: Connection) => {
+    // Every teardown step is isolated and bounded: a throwing or hanging step
+    // must not strand the retained page projections or the child window.
+    const stage = async (label: string, run?: () => void | Promise<void>) => {
+      try {
+        await bounded(Promise.resolve(run?.()));
+      } catch (error) {
+        console.error(`Native overlay teardown failed at ${label}; continuing cleanup anyway.`, error);
+      }
+    };
+    try {
+      await stage('events', connection.stopEvents);
+      await stage('lifecycle', connection.stopLifecycle);
+      await stage('childEvents', connection.stopChildEvents);
+      await stage('exclusions', connection.stopExclusions);
+      await stage('focus', connection.stopFocus);
+      // A timed-out dismissal must not strand the relayed content in the child window.
+      await connection.nativeClosing?.catch((error) => {
+        console.error('Native overlay dismissal did not complete; restoring the Web content anyway.', error);
+      });
+      await stage('content', connection.stopContent);
+      await stage('animation', connection.stopAnimation);
+      await stage('styles', connection.stopStyles);
+      await stage('close', () => bounded(plugin.closeOverlay({ id: connection.id })));
+    } finally {
+      // The page projections must be released even if teardown throws above.
+      connection.releaseProjection?.();
+      connection.releaseProjection = undefined;
+      try {
+        connection.win?.close();
+      } catch (error) {
+        console.error('Native overlay window was already gone.', error);
+      }
+      if (current === connection) current = undefined;
+      const focus = connection.focus as HTMLElement | null;
+      if (focus?.isConnected && focus.tabIndex >= 0) focus.focus({ preventScroll: true });
+    }
+  };
+  const release = (connection: Connection): Promise<void> => (connection.closing ??= cleanup(connection));
+  const restoreWeb = async () => {
+    if (current) await release(current);
+  };
+  const excluded = (overlay: HTMLElement) => isPermanentlyExcluded(overlay) || isExcluded(overlay) || isNativeUIDisabled(overlay);
+  const connect = async (connection: Connection, ready: Promise<void>, presentation: Presentation) => {
+    const { overlay } = connection;
+    const gone = () =>
+      current !== connection ||
+      stopped ||
+      suspensions.size ||
+      connection.dismissed ||
+      !overlay.isConnected ||
+      !nativeVerticalBars() ||
+      excluded(overlay);
+    // Keep the source invisible while the native toolbar prepares its popover.
+    connection.hideAnimation?.();
+    try {
+      // Prepare the child window concurrently with Ionic's content initialization.
+      const staging = (async () => {
+        await bounded(
+          plugin.prepareOverlay({
+            id: connection.id,
+          }),
+        );
+        if (gone()) return undefined;
+        const win = doc.defaultView!.open(`about:blank#${connection.id}`, '_blank');
+        if (!win) throw new Error('Native overlay window unavailable');
+        connection.win = win;
+        // The requested blank page replaces the initial document created by window.open.
+        // WebKit percent-encodes the '#' marker in the popup URL; compare decoded.
+        // Adopt nodes only after that navigation; otherwise WebKit discards the relay.
+        if (decodeURIComponent(win.document.URL) !== `about:blank#${connection.id}` || win.document.readyState !== 'complete')
+          await bounded(new Promise<void>((resolve) => win.addEventListener('load', () => resolve(), { once: true })));
+        if (gone()) return undefined;
+        // about:blank is a quirks-mode document in WebKit. Initialize standards
+        // mode before adopting live content: otherwise percentage button heights
+        // can resolve against the entire popover viewport.
+        win.document.open();
+        win.document.write('<!doctype html><html><head></head><body></body></html>');
+        win.document.close();
+        connection.stopChildEvents = observe(win.document);
+        const environment = relayStyles(doc, win.document, overlay, () => {
+          if (connection.stopContent) void release(connection).catch(console.error);
+        });
+        connection.stopStyles = environment.stop;
+        await bounded(environment.ready);
+        if (gone()) return undefined;
+        return { destination: environment.destination, win };
+      })();
+      // The staging join is awaited below; settle early rejections quietly.
+      staging.catch(() => {});
+      // Ionic initializes its gestures after didPresent. Let that turn finish before adopting their content.
+      // A stalled presentation must not park the opening queue forever.
+      await bounded(ready);
+      // Placement is captured after Ionic has laid out the overlay.
+      await bounded(new Promise<void>((resolve) => doc.defaultView!.requestAnimationFrame(() => resolve())));
+      const staged = await staging;
+      if (gone() || !staged) {
+        await release(connection);
+        return;
+      }
+      const focused = activeElement(doc) as HTMLElement | null;
+      const nativePresentation = popoverPresentation(overlay);
+      const content = relayPopover(overlay, staged.destination);
+      connection.stopContent = content.stop;
+      if (!relayLayoutSupported(overlay) || !content.matchesSourceAppearance()) {
+        await release(connection);
+        return;
+      }
+      connection.hideAnimation?.();
+      // Ionic does not dismiss a presented overlay when its page is hidden or
+      // destroyed; without this a popover could retain the page projections
+      // forever and freeze every later control update.
+      const exclusions = new MutationObserver(() => {
+        if (!overlay.isConnected || !nativeVerticalBars() || excluded(overlay) || isNativeUIDisabled(content.root))
+          void release(connection).catch(console.error);
+      });
+      const attributes = { attributes: true, attributeFilter: ['class', 'data-native-ui', 'hidden', 'inert'] };
+      for (let node: HTMLElement | null = overlay; node; node = node.parentElement) {
+        exclusions.observe(node, attributes);
+        exclusions.observe(node, { childList: true });
+      }
+      exclusions.observe(content.root, { ...attributes, subtree: true });
+      connection.stopExclusions = () => exclusions.disconnect();
+      connection.stopFocus = trapFocus(
+        content.root,
+        () =>
+          !connection.dismissed &&
+          (!('focusTrap' in overlay) || overlay.focusTrap !== false) &&
+          !overlay.classList.contains('ion-disable-focus-trap'),
+      );
+      const close = () => {
+        void release(connection).catch(console.error);
+      };
+      const escape = (event: KeyboardEvent) => {
+        if (event.key === 'Escape' && overlay.backdropDismiss) void overlay.dismiss(undefined, 'backdrop');
+      };
+      staged.win.document.addEventListener('keydown', escape);
+      overlay.addEventListener(lifecycle(overlay, 'DidDismiss'), close, { once: true });
+      connection.stopEvents = () => {
+        staged.win.document.removeEventListener('keydown', escape);
+        overlay.removeEventListener(lifecycle(overlay, 'DidDismiss'), close);
+      };
+      // SwiftUI owns the only visible presentation animation.
+      await bounded(
+        plugin.presentOverlay({
+          id: connection.id,
+          presentation: { ...nativePresentation, animated: presentation.animated },
+        }),
+      );
+      (focused?.isConnected && focused.ownerDocument === staged.win.document ? focused : content.root).focus({ preventScroll: true });
+    } catch (error) {
+      await release(connection);
+      console.error('Native overlay projection failed; keeping Ionic content in the source WebView.', error);
+    }
+  };
+  const present = (event: Event) => {
+    const overlay = event.target as Overlay;
+    if (current) {
+      const connection = current;
+      const fromChild = overlay.ownerDocument === connection.win?.document;
+      if (fromChild) {
+        // A child-document overlay may be a sibling of the relayed content.
+        // Move it before cleanup closes that document; keep the live node,
+        // component handlers and adopted shadow styles in the source WebView.
+        moveContent([overlay], doc.querySelector<HTMLElement>('ion-app') ?? doc.body);
+      }
+      current = undefined;
+      opening = opening.then(() => release(connection)).catch(console.error);
+      // The original event path still belongs to the child document. Let the
+      // source runtime observe presentation before releasing retained controls.
+      if (fromChild) doc.dispatchEvent(new CustomEvent('nativeUIOverlayAdopted', { detail: overlay }));
+      if (!connection.dismissed) return;
+      // A didDismiss handler may immediately open the next popover while SwiftUI is still closing this one.
+      connection.stopAnimation?.();
+      connection.stopAnimation = undefined;
+    }
+    const enabled =
+      overlay.localName === 'ion-popover' &&
+      overlay.mode !== 'md' &&
+      !overlay.classList.contains('md') &&
+      options.controls?.popover === true &&
+      nativeVerticalBars() &&
+      verticalBarsPopoverAnchor(overlay) !== undefined;
+    if (stopped || suspensions.size || !enabled || excluded(overlay)) {
+      opening = opening.then(restoreWeb).catch(console.error);
+      return;
+    }
+    const connection: Connection = { id: `ios-theme-overlay-${++sequence}`, overlay, dismissed: false, focus: activeElement(doc) };
+    const presentation: Presentation = { kind: 'popover', animated: overlay.animated };
+    current = connection;
+    // Retain synchronously, before the scheduled projection update can retire the rail.
+    const anchorId = verticalBarsPopoverAnchor(overlay);
+    connection.releaseProjection = retainProjection(
+      (id) =>
+        id === anchorId &&
+        current === connection &&
+        !!connection.nativeClosing &&
+        !stopped &&
+        !suspensions.size &&
+        nativeVerticalBars() &&
+        !excluded(overlay),
+    );
+    const closed = () => {
+      connection.dismissed = true;
+    };
+    overlay.addEventListener(lifecycle(overlay, 'DidDismiss'), closed, { once: true });
+    let resolveReady!: () => void;
+    const readyPromise = new Promise<void>((resolve) => {
+      resolveReady = resolve;
+    });
+    const ready = () => {
+      resolveReady();
+    };
+    const closeNative = () =>
+      (connection.nativeClosing ??= bounded(plugin.dismissOverlay({ id: connection.id, animated: presentation.animated })));
+    const viewport = `${win.innerWidth}:${win.innerHeight}`;
+    const anchor = bounded(plugin.getVerticalBarsGeometry({ viewportWidth: win.innerWidth, ids: [anchorId!] }))
+      .then(({ items }) => {
+        const frame = items[anchorId!];
+        return frame && validVerticalBarFrame(frame) && viewport === `${win.innerWidth}:${win.innerHeight}` ? frame : undefined;
+      })
+      .catch(() => undefined);
+    const animation = nativeDialogAnimation(overlay, closeNative, anchor);
+    connection.stopAnimation = animation.stop;
+    connection.hideAnimation = animation.hide;
+    animation.hide();
+    overlay.addEventListener(lifecycle(overlay, 'DidPresent'), ready, { once: true });
+    connection.stopLifecycle = () => overlay.removeEventListener(lifecycle(overlay, 'DidDismiss'), closed);
+    opening = opening
+      .then(() => connect(connection, readyPromise, presentation))
+      .catch(console.error)
+      .finally(() => {
+        overlay.removeEventListener(lifecycle(overlay, 'DidPresent'), ready);
+      });
+  };
+  const menuOpen = (event: Event) => {
+    if (!event.composedPath().some((node): node is HTMLElement => node instanceof HTMLElement && node.matches('ion-menu'))) return;
+    // Menus render in the source document below the native overlay; release the relay.
+    const connection = current;
+    current = undefined;
+    if (connection) opening = opening.then(() => release(connection)).catch(console.error);
+  };
+  const observe = (target: Document) => {
+    for (const name of events) target.addEventListener(name, present);
+    target.addEventListener('ionWillOpen', menuOpen);
+    return () => {
+      for (const name of events) target.removeEventListener(name, present);
+      target.removeEventListener('ionWillOpen', menuOpen);
+    };
+  };
+  const invalidate = () => {
+    const connection = current;
+    current = undefined;
+    if (connection) opening = opening.then(() => release(connection)).catch(console.error);
+  };
+  // Retention must not freeze an obsolete layout or a departed page.
+  const win = doc.defaultView!;
+  const visibility = () => {
+    if (doc.hidden) invalidate();
+  };
+  const listener = await boundedListener(
+    plugin.addListener('overlay', (event) => {
+      if (event.id !== current?.id) return;
+      if (event.action === 'dismiss' && current.overlay.backdropDismiss)
+        void current.overlay.dismiss(undefined, 'backdrop').catch(console.error);
+    }),
+  );
+  win.addEventListener('resize', invalidate);
+  doc.addEventListener('ionViewWillLeave', invalidate);
+  doc.addEventListener('visibilitychange', visibility);
+  const stopEvents = observe(doc);
+  return {
+    async suspend() {
+      const lease = Symbol();
+      suspensions.add(lease);
+      await opening;
+      await restoreWeb();
+      return () => {
+        suspensions.delete(lease);
+      };
+    },
+    async destroy() {
+      stopped = true;
+      stopEvents();
+      win.removeEventListener('resize', invalidate);
+      doc.removeEventListener('ionViewWillLeave', invalidate);
+      doc.removeEventListener('visibilitychange', visibility);
+      try {
+        await opening;
+        await restoreWeb();
+      } finally {
+        try {
+          await bounded(plugin.stopOverlays());
+        } finally {
+          await bounded(listener.remove());
+        }
+      }
+    },
+  };
+};