@webview-native-ui/engine 1.0.1 → 1.0.2

package/src/dom/geometry.ts

@@ -0,0 +1,24 @@
+export function* projectionAncestors(element: HTMLElement): Generator<HTMLElement> {
+  let current: HTMLElement | null = element;
+  while (current) {
+    const root = current.getRootNode();
+    current = current.assignedSlot ?? current.parentElement ?? (root instanceof ShadowRoot ? (root.host as HTMLElement) : null);
+    if (current) yield current;
+  }
+}
+
+export const fitsClip = (element: HTMLElement): boolean => {
+  const rect = element.getBoundingClientRect();
+  for (const ancestor of projectionAncestors(element)) {
+    const style = getComputedStyle(ancestor);
+    if (style.transform !== 'none' && !new DOMMatrixReadOnly(style.transform).isIdentity) return false;
+    const bounds = ancestor.getBoundingClientRect();
+    const left = bounds.left + ancestor.clientLeft;
+    const top = bounds.top + ancestor.clientTop;
+    if (/^(hidden|clip|scroll|auto)$/.test(style.overflowX) && (rect.left < left - 1 || rect.right > left + ancestor.clientWidth + 1))
+      return false;
+    if (/^(hidden|clip|scroll|auto)$/.test(style.overflowY) && (rect.top < top - 1 || rect.bottom > top + ancestor.clientHeight + 1))
+      return false;
+  }
+  return true;
+};

package/src/dom/overlays.ts

@@ -0,0 +1,196 @@
+/** Shared by npm consumers and the runtime injected from the native library. */
+export type OverlayPhase = 'willPresent' | 'didPresent' | 'willDismiss' | 'didDismiss' | 'change';
+export interface OverlayChange {
+  element?: HTMLElement;
+  phase: OverlayPhase;
+  event?: Event;
+}
+export interface OverlayDefinition {
+  selector: string;
+  events: Partial<Record<OverlayPhase, string>>;
+}
+export interface OverlayOptions {
+  /** Additional overlay components; Ionic defaults remain enabled. */
+  additional?: readonly OverlayDefinition[];
+  exclude?: string;
+  /** Return undefined to use the normal DOM/backdrop relationship. */
+  covers?: (overlay: HTMLElement, target: HTMLElement) => boolean | undefined;
+}
+export interface OverlayElement extends HTMLElement {
+  presented?: boolean;
+  overlayIndex?: number;
+  showBackdrop?: boolean;
+  initialBreakpoint?: number;
+  backdropBreakpoint?: number;
+}
+
+/** Whether a Web overlay covers the underlying surface, independently of its renderer. */
+export const usesOverlayBackdrop = (element: HTMLElement, breakpoint?: number): boolean => {
+  if (element.matches('ion-toast, ion-menu')) return false;
+  const overlay = element as OverlayElement;
+  if (overlay.showBackdrop === false) return false;
+  if (!element.matches('ion-modal')) return true;
+  const height = breakpoint ?? overlay.initialBreakpoint;
+  return height === undefined || height > (overlay.backdropBreakpoint ?? 0);
+};
+
+const key = Symbol.for('@webview-native-ui/engine/overlays/v1');
+const createCoordinator = (doc: Document) => {
+  const active = new Set<HTMLElement>();
+  const native = new Set<HTMLElement>();
+  const listeners = new Set<(change: OverlayChange) => void>();
+  const breakpoints = new WeakMap<HTMLElement, number>();
+  const dismissed = new WeakSet<HTMLElement>();
+  const registrations = new Map<string, () => void>();
+  let definitions: readonly OverlayDefinition[] = [];
+  let options: OverlayOptions = {};
+  let routes = new Map<string, { phase: OverlayPhase; selector: string }>();
+  let observer: MutationObserver | undefined;
+  const notify = (change: OverlayChange) => {
+    for (const listener of [...listeners]) {
+      try {
+        listener(change);
+      } catch (error) {
+        console.error('Native UI overlay listener failed', error);
+      }
+    }
+  };
+  const accept = (element: HTMLElement, phase: OverlayPhase, event?: Event) => {
+    if (phase === 'willPresent' || phase === 'didPresent') {
+      dismissed.delete(element);
+      active.add(element);
+    } else if (phase === 'didDismiss') {
+      dismissed.add(element);
+      active.delete(element);
+      native.delete(element);
+      breakpoints.delete(element);
+    }
+    const breakpoint = (event as CustomEvent<{ breakpoint?: number }> | undefined)?.detail?.breakpoint;
+    // Zero begins sheet dismissal; retain coverage until DidDismiss retires the surface.
+    if (typeof breakpoint === 'number' && breakpoint > 0) breakpoints.set(element, breakpoint);
+    notify({ element, phase, event });
+  };
+  const refresh = (initial = false) => {
+    let changed = false;
+    for (const element of active)
+      if (!element.isConnected || element.ownerDocument !== doc || !definitions.some(({ selector }) => element.matches(selector))) {
+        active.delete(element);
+        native.delete(element);
+        changed = true;
+      }
+    for (const element of doc.querySelectorAll<OverlayElement>(definitions.map(({ selector }) => selector).join(','))) {
+      if (
+        !active.has(element) &&
+        !dismissed.has(element) &&
+        (initial || !element.matches('ion-popover')) &&
+        (element.presented || element.classList.contains('show-menu'))
+      ) {
+        active.add(element);
+        changed = true;
+      }
+    }
+    if (changed) notify({ phase: 'change' });
+  };
+  return {
+    get active(): ReadonlySet<HTMLElement> {
+      return active;
+    },
+    subscribe(listener: (change: OverlayChange) => void) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    /** Renderer ownership is explicit because a child native window is outside the DOM stack. */
+    setNative(element: HTMLElement, value: boolean) {
+      if (native.has(element) === value) return;
+      if (value) native.add(element);
+      else native.delete(element);
+      notify({ element, phase: 'change' });
+    },
+    isExcluded(element: HTMLElement) {
+      return !!options.exclude && element.matches(options.exclude);
+    },
+    isNative(element: HTMLElement) {
+      return native.has(element);
+    },
+    get stack() {
+      const stack = [...active].filter((element) => element.isConnected && element.ownerDocument === doc);
+      const order = (element: HTMLElement) => {
+        const z = Number.parseFloat(doc.defaultView!.getComputedStyle(element).zIndex);
+        return Number.isFinite(z) ? z : ((element as OverlayElement).overlayIndex ?? 0);
+      };
+      stack.sort((a, b) => order(a) - order(b));
+      return stack;
+    },
+    isCovered(target: HTMLElement) {
+      const stack = this.stack;
+      const owner = stack.reduce((last, element, index) => (element.contains(target) ? index : last), -1);
+      return stack.some((element, index) => {
+        if (native.has(element) || (options.exclude && element.matches(options.exclude))) return false;
+        const override = options.covers?.(element, target);
+        if (override !== undefined) return override;
+        return (
+          index > owner &&
+          !element.contains(target) &&
+          (element.matches('ion-menu') || usesOverlayBackdrop(element, breakpoints.get(element)))
+        );
+      });
+    },
+    enable(defaults: readonly OverlayDefinition[], config?: OverlayOptions) {
+      const nextOptions = { ...options, ...config };
+      const nextDefinitions = [...defaults, ...(nextOptions.additional ?? [])];
+      if (nextOptions.exclude) doc.querySelector(nextOptions.exclude);
+      const nextRoutes = new Map<string, { phase: OverlayPhase; selector: string }>();
+      for (const definition of nextDefinitions) {
+        doc.querySelector(definition.selector);
+        for (const [phase, name] of Object.entries(definition.events)) {
+          const existing = nextRoutes.get(name);
+          if (existing && existing.phase !== phase) throw new TypeError(`Overlay event "${name}" has conflicting phases`);
+          nextRoutes.set(name, {
+            phase: phase as OverlayPhase,
+            selector: existing ? `${existing.selector}, ${definition.selector}` : definition.selector,
+          });
+        }
+      }
+      options = nextOptions;
+      definitions = nextDefinitions;
+      routes = nextRoutes;
+      for (const name of routes.keys()) {
+        if (registrations.has(name)) continue;
+        const listener = (event: Event) => {
+          const route = routes.get(name)!;
+          const element = event
+            .composedPath()
+            .find((node): node is HTMLElement => node instanceof doc.defaultView!.HTMLElement && node.matches(route.selector));
+          if (element) accept(element, route.phase, event);
+        };
+        doc.addEventListener(name, listener, true);
+        registrations.set(name, () => doc.removeEventListener(name, listener, true));
+      }
+      for (const [name, remove] of registrations)
+        if (!routes.has(name)) {
+          remove();
+          registrations.delete(name);
+        }
+      const initial = !observer;
+      if (!observer) {
+        observer = new MutationObserver(() => refresh());
+        observer.observe(doc.documentElement, { childList: true, subtree: true });
+        doc.addEventListener('nativeUIOverlayAdopted', (event) => {
+          const element = (event as CustomEvent<HTMLElement>).detail;
+          if (element?.ownerDocument === doc) accept(element, 'willPresent', event);
+        });
+      }
+      refresh(initial);
+      if (initial || config) notify({ phase: 'change' });
+    },
+  };
+};
+export type OverlayCoordinator = ReturnType<typeof createCoordinator>;
+
+/** Access is inert: only the explicit framework initializer installs DOM listeners. */
+export const getOverlayCoordinator = (doc: Document): OverlayCoordinator => {
+  const shared = doc as unknown as Record<symbol, OverlayCoordinator>;
+  return (shared[key] ??= createCoordinator(doc));
+};

package/src/dom/scroll-bindings.ts

@@ -0,0 +1,66 @@
+import type { WebProjectionSource } from '../types.js';
+
+/** Coordinate ownership, independent of any plugin's update transport or rendering. */
+export const createScrollBindings = () => {
+  let acknowledged: WebProjectionSource[] = [];
+  let viewportWidth = 0;
+  const motion = new WeakMap<HTMLElement, { version: number; moving: boolean }>();
+  const reuse = (candidate: WebProjectionSource, width: number) => {
+    const next = candidate.control.scroll;
+    if (!candidate.scrollElement || !next || viewportWidth !== width) return false;
+    return acknowledged.some((previous) => {
+      const current = previous.control.scroll;
+      return (
+        previous.scrollElement === candidate.scrollElement &&
+        current?.id === next.id &&
+        current.contentWidth === next.contentWidth &&
+        current.contentHeight === next.contentHeight &&
+        (['viewport', 'clip'] as const).every((key) =>
+          (['x', 'y', 'width', 'height'] as const).every((axis) => current[key][axis] === next[key][axis]),
+        )
+      );
+    });
+  };
+  return {
+    reuse,
+    acknowledge(sources: WebProjectionSource[], width: number) {
+      acknowledged = sources;
+      viewportWidth = width;
+    },
+    changed(owner: HTMLElement) {
+      motion.set(owner, { version: (motion.get(owner)?.version ?? 0) + 1, moving: true });
+    },
+    settled(owner: HTMLElement) {
+      const state = motion.get(owner);
+      if (state) state.moving = false;
+    },
+    eligible(candidate: WebProjectionSource, width: number) {
+      return !candidate.scrollElement || !motion.get(candidate.scrollElement)?.moving || reuse(candidate, width);
+    },
+    acquiring(sources: WebProjectionSource[], width: number) {
+      return new Map(
+        sources.flatMap((source) =>
+          source.scrollElement && !reuse(source, width)
+            ? [[source.scrollElement, motion.get(source.scrollElement)?.version ?? 0] as const]
+            : [],
+        ),
+      );
+    },
+    unconfirmed(sources: WebProjectionSource[], acquiring: Map<HTMLElement, number>) {
+      return new Set(
+        sources.flatMap((source) => {
+          const owner = source.scrollElement,
+            sample = source.control.scroll;
+          return owner &&
+            sample &&
+            acquiring.has(owner) &&
+            (acquiring.get(owner) !== (motion.get(owner)?.version ?? 0) ||
+              owner.scrollLeft !== sample.offsetX ||
+              owner.scrollTop !== sample.offsetY)
+            ? [owner]
+            : [];
+        }),
+      );
+    },
+  };
+};

package/src/dom/scroll-placement.ts

@@ -0,0 +1,92 @@
+import type { ScrollPlacement as NativeUIScrollPlacement } from '../types.js';
+type Identify = (element: HTMLElement) => string;
+import { projectionAncestors } from './geometry.js';
+const frame = ({ x, y, width, height }: DOMRect) => ({ x, y, width, height });
+
+const viewportFrame = (element: HTMLElement) => {
+  const bounds = element.getBoundingClientRect();
+  const style = getComputedStyle(element);
+  const left = parseFloat(style.borderLeftWidth) || 0;
+  const top = parseFloat(style.borderTopWidth) || 0;
+  return {
+    x: bounds.left + left,
+    y: bounds.top + top,
+    width: bounds.width - left - (parseFloat(style.borderRightWidth) || 0),
+    height: bounds.height - top - (parseFloat(style.borderBottomWidth) || 0),
+  };
+};
+
+/** Layout-only measurement. Native owns subsequent scroll offsets. No private Ionic APIs. */
+export const readScrollPlacement = (element: HTMLElement, owner: HTMLElement, id: Identify): NativeUIScrollPlacement | undefined => {
+  const ancestors = [element, ...projectionAncestors(element)];
+  const index = ancestors.indexOf(owner);
+  if (index <= 0 || owner === element.ownerDocument.scrollingElement) return;
+  const win = element.ownerDocument.defaultView!;
+  if (win.visualViewport && (win.visualViewport.scale !== 1 || win.visualViewport.offsetLeft || win.visualViewport.offsetTop)) return;
+  let left = 0,
+    top = 0,
+    right = win.innerWidth,
+    bottom = win.innerHeight;
+  for (const [i, ancestor] of ancestors.entries()) {
+    const style = getComputedStyle(ancestor);
+    if (
+      (style.transform !== 'none' && !new DOMMatrixReadOnly(style.transform).isIdentity) ||
+      (style.zoom && style.zoom !== 'normal' && Number(style.zoom) !== 1) ||
+      [style.translate, style.rotate, style.scale, style.perspective].some((value) => value && value !== 'none') ||
+      (style.writingMode && style.writingMode !== 'horizontal-tb') ||
+      (i < index && /^(fixed|sticky)$/.test(style.position))
+    )
+      return;
+    if (i === 0) continue;
+    if (style.scrollbarGutter && style.scrollbarGutter !== 'auto') return;
+    const clipsX = /^(auto|scroll|hidden|clip)$/.test(style.overflowX);
+    const clipsY = /^(auto|scroll|hidden|clip)$/.test(style.overflowY);
+    // Nested moving/clipping coordinates require a separate binding; do not guess.
+    if (i < index && (clipsX || clipsY)) return;
+    const documentScroll = ancestor === element.ownerDocument.scrollingElement;
+    if (
+      i > index &&
+      (((clipsX || documentScroll) && ancestor.scrollWidth > ancestor.clientWidth) ||
+        ((clipsY || documentScroll) && ancestor.scrollHeight > ancestor.clientHeight))
+    )
+      return;
+    if (
+      (clipsX || clipsY) &&
+      [style.borderTopLeftRadius, style.borderTopRightRadius, style.borderBottomLeftRadius, style.borderBottomRightRadius].some(
+        (radius) => parseFloat(radius) > 0,
+      )
+    )
+      return;
+    if ((style.clipPath && style.clipPath !== 'none') || (style.maskImage && style.maskImage !== 'none')) return;
+    if (i >= index) {
+      const rect = viewportFrame(ancestor);
+      if (clipsX) {
+        left = Math.max(left, rect.x);
+        right = Math.min(right, rect.x + rect.width);
+      }
+      if (clipsY) {
+        top = Math.max(top, rect.y);
+        bottom = Math.min(bottom, rect.y + rect.height);
+      }
+    }
+  }
+  const style = getComputedStyle(owner);
+  if (!/^(auto|scroll)$/.test(style.overflowX) && !/^(auto|scroll)$/.test(style.overflowY)) return;
+  const viewport = viewportFrame(owner);
+  if (right <= left || bottom <= top || !viewport.width || !viewport.height) return;
+  const source = frame(element.getBoundingClientRect());
+  return {
+    id: id(owner),
+    offsetX: owner.scrollLeft,
+    offsetY: owner.scrollTop,
+    viewport,
+    clip: { x: left, y: top, width: right - left, height: bottom - top },
+    contentWidth: owner.scrollWidth,
+    contentHeight: owner.scrollHeight,
+    frame: {
+      ...source,
+      x: source.x - viewport.x + owner.scrollLeft,
+      y: source.y - viewport.y + owner.scrollTop,
+    },
+  };
+};

package/src/dom/visibility.ts

@@ -0,0 +1,29 @@
+import { projectionAncestors } from './geometry.js';
+
+/** Current CSS visibility without the Engine's projection hiding rules.
+ * Use when an existing renderer decides whether its DOM source is authored hidden.
+ * Projection attributes are restored synchronously before returning; this performs
+ * a style read and may notify MutationObservers, so it is not a cached measurement.
+ */
+export const getUnprojectedVisibility = (element: HTMLElement): string => {
+  const win = element.ownerDocument.defaultView;
+  if (!win) return 'hidden';
+  const markers: { node: HTMLElement; name: string; value: string }[] = [];
+  for (const node of [element, ...projectionAncestors(element)]) {
+    for (const attribute of Array.from(node.attributes)) {
+      if (
+        attribute.name === 'data-native-ui-snapshot-source' ||
+        attribute.name === 'data-native-ui-snapshot-prepared' ||
+        attribute.name === 'data-native-ui-snapshot-content' ||
+        attribute.name.startsWith('data-native-ui-session-')
+      )
+        markers.push({ node, name: attribute.name, value: attribute.value });
+    }
+  }
+  try {
+    for (const { node, name } of markers) node.removeAttribute(name);
+    return win.getComputedStyle(element).visibility;
+  } finally {
+    for (const { node, name, value } of markers) node.setAttribute(name, value);
+  }
+};

package/src/index.ts

@@ -0,0 +1,19 @@
+export * from './types.js';
+export * from './dom/geometry.js';
+export * from './dom/scroll-placement.js';
+export { createWebProjectionScope, type WebProjectionScope } from './projection/scope.js';
+export * from './projection/web.js';
+export * from './dom/scroll-bindings.js';
+export type { ProjectionEvents, ProjectionDestination } from './projection/events.js';
+export { getOverlayCoordinator, usesOverlayBackdrop, type OverlayChange, type OverlayOptions } from './dom/overlays.js';
+export { getUnprojectedVisibility } from './dom/visibility.js';
+
+export { bindProjectionPlacement, type ProjectionPlacementBinding } from './projection/placement.js';
+
+export { createWebProjectionSurfaces } from './projection/surfaces.js';
+
+export * from './projection/surface.js';
+
+export { createNativeUpdateQueue, type NativeUpdateSender } from './native/updates.js';
+
+export { pause, resume } from './projection/pause.js';

package/src/integration/index.ts

@@ -0,0 +1,64 @@
+/// <reference lib="es2021.weakref" />
+
+export interface NativeUISuspensionOptions {
+  /** Navigation-only toolbar handoff; omitted for explicit Web ownership requests. */
+  navigation?: boolean;
+  /** A swipe whose navigation result has not yet been committed. */
+  interactive?: boolean;
+  /** Direction supplied by Ionic's navigation animation builder. */
+  direction?: 'forward' | 'back' | 'root';
+}
+
+export type NativeUITransitionRelease = ((canceled?: boolean) => void) & {
+  progress?: (value: number) => void;
+  /** The finger lifted; Web will now settle toward its chosen endpoint. */
+  finishGesture?: (complete: boolean) => void;
+};
+
+export interface NativeUIIntegration {
+  suspend(scopes: HTMLElement[], options?: NativeUISuspensionOptions): Promise<NativeUITransitionRelease>;
+  search?(binding: NativeSearchBinding, active: boolean, focus?: boolean): Promise<boolean>;
+}
+
+export interface NativeSearchBinding {
+  tabBar: HTMLElement;
+  trigger: HTMLElement;
+  footer: HTMLElement;
+  active: boolean;
+  focused: boolean;
+}
+
+const searches = new WeakMap<Document, WeakRef<NativeSearchBinding>[]>();
+
+export const registerNativeSearch = (tabBar: HTMLElement, trigger: HTMLElement, footer: HTMLElement): NativeSearchBinding => {
+  const binding = { tabBar, trigger, footer, active: false, focused: false };
+  const entries = (searches.get(tabBar.ownerDocument) ?? []).filter((entry) => entry.deref() && entry.deref()?.footer !== footer);
+  entries.push(new WeakRef(binding));
+  searches.set(tabBar.ownerDocument, entries);
+  tabBar.ownerDocument.defaultView?.dispatchEvent(new Event('nativeUIRefresh'));
+  return binding;
+};
+
+export const getNativeSearchBindings = (doc: Document): NativeSearchBinding[] =>
+  (searches.get(doc) ?? []).flatMap((entry) => entry.deref() ?? []);
+
+export const requestNativeSearch = async (binding: NativeSearchBinding, active: boolean, focus?: boolean): Promise<boolean> =>
+  (await runtimes.get(binding.tabBar.ownerDocument)?.search?.(binding, active, focus)) ?? false;
+
+const runtimes = new WeakMap<Document, NativeUIIntegration>();
+export const VERTICAL_BARS_TRANSITION_CANCELED = 'iosThemeVerticalBarsTransitionCanceled';
+
+export const setNativeUIIntegration = (doc: Document, runtime?: NativeUIIntegration) => {
+  if (runtime) runtimes.set(doc, runtime);
+  else runtimes.delete(doc);
+};
+
+export const hasNativeUIIntegration = (doc: Document): boolean => runtimes.has(doc);
+
+export const isNativeUI = (element: HTMLElement) => element.hasAttribute('data-native-ui-projected');
+
+export const suspendNativeUI = async (scopes: HTMLElement[], options?: NativeUISuspensionOptions): Promise<NativeUITransitionRelease> =>
+  (await runtimes.get(scopes[0]?.ownerDocument)?.suspend(scopes, options)) ?? (() => {});
+
+/** Shared geometry used by the theme's transition adapter; no theme import in the plugin. */
+export const nativeWebViewMetrics = { radius: 0 };

package/src/ionic.ts

@@ -0,0 +1,34 @@
+import { getOverlayCoordinator, type OverlayDefinition, type OverlayOptions } from './dom/overlays.js';
+export type { OverlayOptions as IonicOverlayOptions } from './dom/overlays.js';
+const defaults: readonly OverlayDefinition[] = [
+  ...['Modal', 'Popover', 'Alert', 'ActionSheet', 'Loading', 'Picker', 'Toast'].map((name) => ({
+    selector: `ion-${name.replace(/[A-Z]/g, (letter, index) => (index ? '-' : '') + letter.toLowerCase())}`,
+    events: {
+      willPresent: `ion${name}WillPresent`,
+      didPresent: `ion${name}DidPresent`,
+      willDismiss: `ion${name}WillDismiss`,
+      didDismiss: `ion${name}DidDismiss`,
+    },
+  })),
+  { selector: 'ion-modal', events: { change: 'ionBreakpointDidChange' } },
+  {
+    selector: 'ion-menu',
+    events: { willPresent: 'ionWillOpen', didPresent: 'ionDidOpen', willDismiss: 'ionWillClose', didDismiss: 'ionDidClose' },
+  },
+];
+/** Call once at app startup. Repeated default calls share the existing configuration and monitor. */
+export const enableSupportIonicOverlays = (options?: OverlayOptions, doc: Document | undefined = globalThis.document) => {
+  if (!doc) return;
+  const coordinator = getOverlayCoordinator(doc);
+  coordinator.enable(defaults, options);
+  return coordinator;
+};
+
+/** The background surface shares the same order used for registered DOM projections. */
+export const ionicModalStack = (doc: Document): HTMLElement[] =>
+  getOverlayCoordinator(doc).stack.filter((element) => element.matches('ion-modal'));
+
+export const coveredIonicSurface = (overlay: HTMLElement): HTMLElement | undefined => {
+  const stack = ionicModalStack(overlay.ownerDocument);
+  return overlay.matches('ion-modal') ? stack[stack.indexOf(overlay) - 1] : stack[stack.length - 1];
+};

package/src/native/bootstrap.ts

@@ -0,0 +1,132 @@
+import { startNativeSession, type NativeSessionConfiguration } from './session.js';
+import type { ListenerHandle } from '../types.js';
+
+const sessions = new Map<string, { destroy(): Promise<void>; hide(): void; show(): void }>();
+const pending = new Map<string, { resolve(value: any): void; reject(error: Error): void; timer: ReturnType<typeof setTimeout> }>();
+const interactions = new Map<string, (event: { active: boolean; precovered?: string }) => void>();
+const documentID = Array.from(crypto.getRandomValues(new Uint32Array(4)), (part) => part.toString(16)).join('-');
+const notifications = new Map<string, Map<string, (event: unknown) => void>>();
+/** Cordova plugins forward their existing notifications through NativeUIProjection.receive. */
+export const notify = (id: string, name: string, data: unknown) => notifications.get(id)?.get(name)?.(data);
+let sequence = 0;
+const send = (id: string, request: unknown): Promise<any> =>
+  new Promise((resolve, reject) => {
+    const key = `${id}:${documentID}:${++sequence}`;
+    const timer = setTimeout(() => {
+      pending.delete(key);
+      reject(new Error('Native UI session timed out'));
+    }, 5000);
+    pending.set(key, { resolve, reject, timer });
+    const message = JSON.stringify({ key, request });
+    const host = globalThis as any;
+    const channel = host.webkit?.messageHandlers?.[id] ?? host.nativeUIEngine;
+    if (!channel) {
+      clearTimeout(timer);
+      pending.delete(key);
+      reject(new Error('Native UI session unavailable'));
+      return;
+    }
+    try {
+      channel.postMessage(message);
+    } catch (error) {
+      clearTimeout(timer);
+      pending.delete(key);
+      reject(error);
+    }
+  });
+export const receive = (id: string, key: string | null, value: any, error?: string) => {
+  if (key === null) {
+    interactions.get(id)?.(value);
+    return;
+  }
+  const item = pending.get(key);
+  if (!item || !key.startsWith(`${id}:`)) return;
+  pending.delete(key);
+  clearTimeout(item.timer);
+  if (error) item.reject(new Error(error));
+  else item.resolve(value);
+};
+export const show = (id: string) => {
+  sessions.get(id)?.show();
+};
+export const hide = (id: string) => {
+  sessions.get(id)?.hide();
+  return true;
+};
+export const stop = async (id: string) => {
+  const session = sessions.get(id);
+  sessions.delete(id);
+  notifications.delete(id);
+  interactions.delete(id);
+  for (const [key, item] of pending) {
+    if (!key.startsWith(`${id}:`)) continue;
+    pending.delete(key);
+    clearTimeout(item.timer);
+    item.reject(new Error('Native UI session closed'));
+  }
+  await session?.destroy();
+};
+export const start = async (config: NativeSessionConfiguration) => {
+  if (sessions.has(config.id)) return;
+  // Reserve before asynchronous initialization, including duplicate Native init callbacks.
+  let actual: Awaited<ReturnType<typeof startNativeSession>> | undefined;
+  let cancelled = false;
+  let pendingDestination: 'none' | 'native' | undefined;
+  const reservation = {
+    show: () => {
+      pendingDestination = 'native';
+      actual?.show();
+    },
+    hide: () => {
+      pendingDestination = 'none';
+      actual?.hide();
+    },
+    destroy: async () => {
+      cancelled = true;
+      await actual?.destroy();
+    },
+  };
+  sessions.set(config.id, reservation);
+  try {
+    if (document.readyState === 'loading')
+      await new Promise<void>((resolve) => document.addEventListener('DOMContentLoaded', () => resolve(), { once: true }));
+    if (cancelled) return;
+    const listeners = new Map<string, (event: unknown) => void>();
+    if (config.runtime === 'cordova') notifications.set(config.id, listeners);
+    actual = await startNativeSession(
+      config,
+      {
+        send: (request) => send(config.id, request),
+        listen: async (listener): Promise<ListenerHandle> => {
+          interactions.set(config.id, listener);
+          return {
+            remove: () => {
+              if (interactions.get(config.id) === listener) interactions.delete(config.id);
+            },
+          };
+        },
+      },
+      config.runtime === 'cordova'
+        ? {
+            addListener: async (name, listener) => {
+              listeners.set(name, listener);
+              return {
+                remove: () => {
+                  listeners.delete(name);
+                },
+              };
+            },
+          }
+        : undefined,
+    );
+    if (pendingDestination === 'none') actual.hide();
+    else if (pendingDestination === 'native') actual.show();
+    if (cancelled) await actual.destroy();
+  } catch (error) {
+    if (sessions.get(config.id) === reservation) {
+      sessions.delete(config.id);
+      notifications.delete(config.id);
+    }
+    throw error;
+  }
+};