@rdlabo/capacitor-native-ui 0.0.0-stage → 2.0.0-1

package/src/native/definitions.ts

@@ -0,0 +1,274 @@
+import type { NativeUIExtension } from './extensions';
+import type { PluginListenerHandle } from '@capacitor/core';
+
+export type NativeUIComponent =
+  | 'ion-button'
+  | 'ion-buttons'
+  | 'ion-back-button'
+  | 'ion-menu-button'
+  | 'ion-tab-bar'
+  | 'ion-segment'
+  | 'ion-fab';
+
+export interface NativeUIStatus {
+  state: 'web' | 'native' | 'stopped';
+  projected: number;
+  updates: number;
+  reason?: string;
+}
+
+/** Default selection in ordinary (horizontal) or rail (vertical) placement.
+ * Explicit source settings override these defaults. This does not choose placement.
+ */
+export type ControlProjection = boolean | 'horizontalOnly' | 'verticalOnly';
+
+export interface NativeUIControls {
+  /** Group selected ordinary buttons. Does not select children or include back buttons. */
+  buttonGroup?: ControlProjection;
+  /** Select ordinary actions, including menu buttons. */
+  button?: ControlProjection;
+  backButton?: ControlProjection;
+  tabs?: ControlProjection;
+  segment?: ControlProjection;
+  fab?: ControlProjection;
+}
+
+export interface IonicProjectionOptions {
+  /** Discover supported Ionic controls automatically. Explicit sources remain independent. Defaults to true. */
+  auto?: boolean;
+  verticalBars?: {
+    /** Native appearance of vertical Ionic buttons. Local source settings take precedence. Defaults to system. */
+    buttonProjection?: 'system' | 'source';
+    /** Source-style standalone ion-button default; ion-buttons still defaults to clear. Defaults to glass. */
+    buttonDefaultFill?: 'glass' | 'solid';
+    /** Relay Ionic popovers anchored to native rail buttons. Defaults to false. */
+    popover?: boolean;
+  };
+}
+
+export interface NativeUIOptions {
+  /** Connected source subtree. Defaults to document.body. */
+  root?: HTMLElement;
+  /** Default selection and grouping. Scalars apply to every kind; omitted fields default to true. */
+  controls?: ControlProjection | NativeUIControls;
+  verticalBars?: NativeUIVerticalBarsOptions;
+  /** App-local projection definitions, independent of controls.
+   * @experimental API and behavior may change.
+   */
+  extensions?: readonly NativeUIExtension[];
+  ionic?: IonicProjectionOptions;
+  /** Log Web fallback reasons. Defaults to false. */
+  debug?: boolean;
+}
+
+/** Options for the standalone rail entry. */
+export type VerticalControlAreaOptions = NativeUIOptions;
+
+/** @internal Resolved adapter state; not an application configuration API. */
+export interface NativeUIRuntimeOptions extends NativeUIOptions {
+  source?: 'ionic' | 'html' | 'auto' | 'extensions';
+  nativeState?: { edge?: 'left' | 'right' };
+  unavailableExtensions?: ReadonlyMap<string, string>;
+  rail?: { host: HTMLElement; edge: 'left' | 'right' };
+}
+
+/** A running shell. Placement changes preserve all other startup settings. */
+export interface NativeUIHandle extends NativeUIRuntimeHandle {
+  /** Enable rail projection when available, preserving other settings. Rejects after destroy. */
+  enableVerticalControlArea(): Promise<void>;
+  /** Restore rail sources to the Web without stopping ordinary native controls. Rejects after destroy. */
+  disableVerticalControlArea(): Promise<void>;
+}
+
+export interface NativeUIVerticalBarsOptions {
+  /** Defaults to true. Availability is always determined separately. */
+  enabled?: boolean;
+  /** Placement preference, not a declaration of device capability. */
+  placement?: { edge: Exclude<VerticalBarEdge, null>; webHost?: HTMLElement };
+}
+
+export interface NativeUIRuntimeHandle {
+  /** Schedule a source recheck. Calls coalesce; unchanged snapshots are not sent. No-op after destroy or without a runtime. */
+  markForCheck(): void;
+  /** Returns the current Web/native projection state. */
+  getStatus(): NativeUIStatus;
+  /** Restores projected controls to the Web until the returned lease is resumed. */
+  suspend(): Promise<NativeUISuspension>;
+  /** Stops synchronization, restores Web controls and releases native resources. */
+  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;
+  /** Explicit rail width in CSS pixels; omitted to use the stylesheet's safe-area rules. */
+  inset?: number;
+  /** Ignored. Native availability is read from the plugin’s own device metrics.
+   * @deprecated This input no longer reports native availability.
+   */
+  nativeEdge?: VerticalBarEdge;
+}
+
+export interface VerticalControlAreaHandle extends NativeUIHandle {
+  /** Legacy Web CSS adapter. Use the theme setVerticalBarsLayout helper instead.
+   * @deprecated Web layout belongs to the theme or application.
+   */
+  setPlacement(placement: VerticalBarEdge | VerticalBarPlacement, rtl?: boolean): void;
+}
+
+export interface NativeUISuspension {
+  /** Releases this suspension. Native projection resumes after all active suspensions are released. */
+  resume(): Promise<void>;
+}
+
+export interface Frame {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface NativeUIBadge {
+  value: string;
+  color: string;
+  textColor: string;
+}
+
+export interface NativeUIItem extends Frame {
+  id: string;
+  label: string;
+  accessibilityLabel: string;
+  disabled: boolean;
+  selected: boolean;
+  fontSize: number;
+  fontWeight: number;
+  color: string;
+  /** Resolved ion-button fill for vertical projection; clear omits the native glass background. */
+  buttonFill?: 'clear' | 'solid' | 'outline';
+  backgroundColor?: string;
+  borderColor?: string;
+  borderWidth?: number;
+  badge?: NativeUIBadge;
+  icon?: string;
+  iconWidth?: number;
+  iconHeight?: number;
+  iconPosition?: 'leading' | 'trailing' | 'top';
+  imagePadding?: number;
+  contentInsetLeading?: number;
+  contentInsetTrailing?: number;
+  iconTemplate?: boolean;
+  visible?: boolean;
+  closeIcon?: string;
+  closeIconWidth?: number;
+  closeIconHeight?: number;
+  iconTransition?: number;
+}
+
+/** Standard native renderers, independent of the source Web framework. */
+export type NativeUIControlKind =
+  | 'button'
+  | 'button-group'
+  | 'back-button'
+  | 'menu-button'
+  | 'tab-bar'
+  | 'segment'
+  | 'floating-action-button';
+
+export interface NativeUIControl extends Frame {
+  id: string;
+  kind: NativeUIControlKind | 'extension';
+  extension?: { name: string; props: string; actions: Record<string, string>; tabBarId?: string };
+  /** 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: NativeUIItem[];
+  dark: boolean;
+  rtl: boolean;
+  tabBarAnchor?: { x: 0 | 0.5 | 1; y: 0 | 1 };
+  search?: NativeUISearch;
+}
+
+export interface NativeUISearch {
+  id: string;
+  field: NativeUIItem;
+  trigger: NativeUIItem;
+  closeId: string;
+  active: boolean;
+  available: boolean;
+  focused: boolean;
+  value: string;
+  placeholder: string;
+  disabled: boolean;
+  editSequence: number;
+  valueVersion: number;
+}
+
+export interface NativeUISearchEvent extends NativeUIActivation {
+  valueVersion: number;
+  phase: 'input' | 'focus' | 'blur' | 'clear' | 'commit';
+  value: string;
+  composing: boolean;
+}
+
+export interface NativeUISnapshot {
+  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';
+  /** Visible foreground modal bounds; omitted for the full page. */
+  verticalBarFrame?: Frame;
+  controls: NativeUIControl[];
+}
+
+export interface NativeUIActivation {
+  revision: number;
+  id: string;
+  sequence: number;
+  /** Native extension action awaiting a Web dispatch acknowledgement. */
+  requestId?: string;
+}
+
+export interface WebViewMetrics {
+  /** The WebView's effective top-left corner radius in points, or `0` when unavailable. */
+  radius: number;
+  /** Device-reported logical rail edge; null when unavailable. */
+  verticalBarEdge?: VerticalBarEdge;
+}
+
+export interface NativeUIPlugin {
+  configure(options?: { suppressScrollEdgeEffect?: boolean }): Promise<{ supported: boolean; extensions?: string[] }>;
+  completeExtensionAction(options: { requestId: string; accepted: boolean }): Promise<void>;
+  getWebViewMetrics(): Promise<WebViewMetrics>;
+  getVerticalBarsGeometry(options: { viewportWidth: number; ids: string[] }): Promise<{ revision?: number; items: Record<string, Frame> }>;
+  prepareOverlay(options: { id: string }): Promise<void>;
+  presentOverlay(options: { id: string; presentation?: NativeUIPopoverPresentation }): Promise<void>;
+  dismissOverlay(options: { id: string; animated: boolean }): Promise<void>;
+  closeOverlay(options: { id: string }): Promise<void>;
+  stopOverlays(): Promise<void>;
+  update(snapshot: NativeUISnapshot): Promise<{ revision: number; rejectedSearches?: string[]; rejectedControls?: string[] }>;
+  clear(options: { revision: number }): Promise<void>;
+  addListener(name: 'activate', listener: (event: NativeUIActivation) => void): Promise<PluginListenerHandle>;
+  addListener(name: 'search', listener: (event: NativeUISearchEvent) => void): Promise<PluginListenerHandle>;
+  addListener(name: 'webViewMetricsChange', listener: (event: WebViewMetrics) => void): Promise<PluginListenerHandle>;
+  addListener(name: 'overlay', listener: (event: NativeUIOverlayEvent) => void): Promise<PluginListenerHandle>;
+}
+
+export interface NativeUIPopoverPresentation {
+  kind: 'popover';
+  animated: boolean;
+  dark: boolean;
+  anchorId: string;
+  width: number;
+  height: number;
+  backgroundColor: string;
+  backdropDismiss: boolean;
+}
+
+export interface NativeUIOverlayEvent {
+  id: string;
+  action: 'dismiss';
+}

package/src/native/extensions.ts

@@ -0,0 +1,176 @@
+import { fitsClip } from './shared/clipping';
+export { projectionAncestors as extensionAncestors } from './shared/clipping';
+import type { Candidate, Identify } from './shared/candidate';
+import { frame, isDark, visible } from './shared/dom';
+import { iconSource, type createIconRenderer } from './shared/icons';
+
+export type NativeUIValue = string | number | boolean | null | NativeUIValue[] | { [key: string]: NativeUIValue };
+
+/** Opaque image reference. Return it in props; the shell replaces it with NativeUIImage data before transmission. */
+export type NativeUIImageReference = { readonly $nativeUIImage: string };
+type NativeUIImage = { data: string; width: number; height: number; template: boolean };
+
+export interface NativeUIReadContext {
+  /** Capture a local SVG or resolved ion-icon using the standard renderer. Unsupported artwork returns null. */
+  image(element: SVGElement | HTMLElement | null, options?: { template?: boolean }): NativeUIImageReference | null;
+}
+
+/** An app-local DOM projection. Swift or Kotlin registers its native content under the same name.
+ * @experimental API and behavior may change in future releases.
+ */
+export interface NativeUIExtension {
+  readonly name: string;
+  readonly selector: string;
+  /** Defaults to the source element's frame. Unsupported hosts keep the Web source visible. */
+  readonly placement?: 'element' | 'tab-accessory';
+  /** Return null to keep this instance on the Web. Read current source state without side effects. Notify property-only changes with shell.markForCheck(). */
+  readonly read: (
+    element: HTMLElement,
+    context: NativeUIReadContext,
+  ) => {
+    props: { [key: string]: NativeUIValue };
+    /** Click targets must belong to the source element. Null targets are unavailable. */
+    actions?: Record<string, HTMLElement | null>;
+  } | null;
+}
+
+/** Defines a projection locally; it does not start native work or register a Capacitor plugin.
+ * @experimental API and behavior may change in future releases.
+ */
+export const defineNativeUI = <T extends NativeUIExtension>(extension: T): Readonly<T> => Object.freeze({ ...extension });
+
+export const validateExtensions = (extensions: readonly NativeUIExtension[], doc: Document): void => {
+  const names = new Set<string>();
+  for (const extension of extensions) {
+    if (!extension.name.trim() || names.has(extension.name)) throw new Error('Native UI extension names must be nonempty and unique');
+    names.add(extension.name);
+    if (!extension.selector.trim()) throw new Error('Native UI extensions require a selector');
+    doc.querySelector(extension.selector);
+    if (extension.placement && !['element', 'tab-accessory'].includes(extension.placement)) throw new Error('Invalid native UI placement');
+  }
+};
+
+const json = (value: unknown, images: Map<string, NativeUIImage>): string => {
+  if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype)
+    throw new Error('Native UI props must be a JSON object');
+  const result = JSON.stringify(value, (_key, item: unknown) => {
+    if (
+      item === undefined ||
+      typeof item === 'function' ||
+      typeof item === 'symbol' ||
+      (typeof item === 'number' && !Number.isFinite(item)) ||
+      (item !== null && typeof item === 'object' && !Array.isArray(item) && Object.getPrototypeOf(item) !== Object.prototype)
+    )
+      throw new Error('Native UI props must contain only JSON values');
+    if (item && typeof item === 'object' && '$nativeUIImage' in item) {
+      const image = images.get(item.$nativeUIImage as string);
+      if (!image || Object.keys(item).length !== 1) throw new Error('Invalid native image reference');
+      return image;
+    }
+    return item;
+  });
+  if (!result || result.length > 65536) throw new Error('Native UI props exceed 64K characters');
+  return result;
+};
+
+/** Follow slot assignment too: Ionic scroll containers live inside shadow roots. */
+
+export const readExtension = (
+  element: HTMLElement,
+  extensions: readonly NativeUIExtension[],
+  id: Identify,
+  diagnose: (reason: string) => void = () => {},
+): Candidate | undefined => {
+  const skip = (reason: string): undefined => {
+    diagnose(reason);
+    return undefined;
+  };
+  const matches = extensions.filter((extension) => element.matches(extension.selector));
+  if (matches.length !== 1) return skip('overlapping-selectors: exactly one extension must own this source.');
+  if (!visible(element)) return skip('source-hidden: the source must be visible and inside the viewport.');
+  if (element.closest('ion-modal, ion-popover, ion-menu'))
+    return skip('unsupported-overlay: extension sources inside Web overlays stay on the Web.');
+  if (element.contains(element.ownerDocument.activeElement)) return skip('source-focused: keep the focused Web source until focus leaves.');
+  const extension = matches[0];
+  if (extension.placement !== 'tab-accessory' && !fitsClip(element))
+    return skip('source-clipped: the source must fit its clipping ancestors without transformed ancestors.');
+  try {
+    const images: { value: NativeUIImage; source: string }[] = [];
+    const imageValues = new Map<string, NativeUIImage>();
+    let state: ReturnType<NativeUIExtension['read']>;
+    try {
+      state = extension.read(element, {
+        image(owner, options) {
+          if (!owner || !(element.contains(owner) || element.shadowRoot?.contains(owner))) return null;
+          const svg = owner.matches('svg') ? (owner as SVGElement) : owner.shadowRoot?.querySelector<SVGElement>('svg');
+          if (!svg) return null;
+          const source = iconSource(svg);
+          const { width, height } = owner.getBoundingClientRect();
+          if (!source || !Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return null;
+          const value: NativeUIImage = { data: '', width, height, template: options?.template ?? false };
+          const key = String(images.length);
+          images.push({ value, source });
+          imageValues.set(key, value);
+          return { $nativeUIImage: key };
+        },
+      });
+    } catch {
+      return skip('reader-error: the extension reader threw; inspect its implementation.');
+    }
+    if (!state) return skip('reader-opt-out: the reader returned null.');
+    const props = json(state.props, imageValues);
+    const actions = new Map<string, HTMLElement>();
+    const targets: Record<string, string> = {};
+    for (const [name, target] of Object.entries(state.actions ?? {})) {
+      if (!name || (target && !element.contains(target))) return skip('invalid-actions: use named targets inside the source element.');
+      if (
+        !target ||
+        !visible(target) ||
+        (target as HTMLElement & { disabled?: boolean }).disabled ||
+        target.matches(':disabled, [disabled]') ||
+        target.closest('[aria-disabled="true"]') ||
+        getComputedStyle(target).pointerEvents === 'none'
+      )
+        continue;
+      targets[name] = id(target);
+      actions.set(id(target), target);
+    }
+    if (Object.keys(targets).length > 30) return skip('invalid-actions: a source can expose at most 30 actions.');
+    const tabBar =
+      extension.placement === 'tab-accessory'
+        ? Array.from(element.closest('ion-tabs')?.querySelectorAll<HTMLElement>('ion-tab-bar') ?? []).find(
+            (bar) => bar.closest('ion-tabs') === element.closest('ion-tabs'),
+          )
+        : undefined;
+    if (extension.placement === 'tab-accessory' && !tabBar)
+      return skip('missing-tab-owner: a tab accessory needs an owning ion-tabs with ion-tab-bar.');
+    const style = getComputedStyle(element);
+    const control = {
+      id: id(element),
+      kind: 'extension' as const,
+      ...frame(element.getBoundingClientRect()),
+      items: [],
+      dark: isDark(style),
+      rtl: style.direction === 'rtl',
+      extension: { name: extension.name, props, actions: targets, tabBarId: tabBar ? id(tabBar) : undefined },
+    };
+    return {
+      element,
+      actions,
+      icons: [],
+      control,
+      assets: images.length
+        ? {
+            signature: JSON.stringify(images),
+            async render(renderer: ReturnType<typeof createIconRenderer>) {
+              for (const { value, source } of images) value.data = await renderer.render(source, value.width, value.height);
+              control.extension.props = json(state.props, imageValues);
+            },
+          }
+        : undefined,
+    };
+  } catch {
+    // Keep the source usable without exposing props or application exception data.
+    return skip('invalid-props: return a JSON object with finite values, valid image references, and at most 64K characters.');
+  }
+};

package/src/native/foldable/fold-state.ts

@@ -0,0 +1,10 @@
+import type { FoldState } from './types';
+
+/** @deprecated Import applyFoldStateClasses from @rdlabo/ionic-theme-ios27 instead.
+ * Keep posture on ion-app so descendants can follow it through CSS. */
+export function applyFoldStateClasses(root: HTMLElement, fold: FoldState): void {
+  for (const state of ['flat', 'half-opened', 'closed']) {
+    root.classList.toggle(`ios-theme-fold-${state}`, fold.state === state);
+  }
+  root.classList.toggle('ios-theme-fold-expanded', fold.state === 'half-opened' || (fold.state === 'flat' && !!fold.hingeBounds));
+}

package/src/native/foldable/types.ts

@@ -0,0 +1,4 @@
+export interface FoldState {
+  state: 'flat' | 'half-opened' | 'closed';
+  hingeBounds?: { x: number; y: number; width: number; height: number };
+}

package/src/native/html.ts

@@ -0,0 +1,199 @@
+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 (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);
+    const clones = Array.from(wanted, (source) => owned.get(source)!.clone);
+    const order = Array.from(host.children).filter((child): child is HTMLButtonElement => clones.includes(child as HTMLButtonElement));
+    const focused = clones.find((clone) => clone === doc.activeElement);
+    clones.forEach((clone, index) => {
+      if (order[index] === clone) return;
+      host.insertBefore(clone, order[index]);
+      order.splice(order.indexOf(clone), 1);
+      order.splice(index, 0, clone);
+    });
+    // Moving an existing button can blur it; retain keyboard focus across source reordering.
+    if (focused && doc.activeElement !== focused) focused.focus({ preventScroll: true });
+    // 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();
+    },
+  };
+};