@rdlabo/capacitor-native-ui 1.2.1 → 2.0.0-beta.pr304.sha56daf151ad80

package/src/native/definitions.ts

@@ -17,104 +17,61 @@ export interface NativeUIStatus {
   reason?: string;
 }
 
-export interface ToolbarProjectionOptions {
-  /** Group selected actions; never selects children or back buttons. Defaults to true. */
-  buttons?: boolean;
-  /** Automatically select ordinary actions, inside or outside groups. Defaults to true. */
-  button?: boolean;
-  /** Automatically select back navigation independently of groups. Defaults to true. */
-  backButton?: boolean;
+/** 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 VerticalControlAreaOptions {
-  /** App-local DOM readers with matching SwiftUI or Compose registrations.
-   * @experimental API and behavior may change in future releases.
-   */
-  extensions?: readonly NativeUIExtension[];
-  /** Opt-in popovers anchored to native Vertical Bars buttons. */
-  controls?: Pick<NativeUIControls, 'popover'>;
-  /** Ordinary horizontal toolbar selection/grouping. true enables all three options; false disables them.
-   * Object fields default to true. Local data-horizontal-bars overrides still apply.
-   * Only enableNativeUI projects horizontal controls.
-   */
-  horizontal?: boolean | ToolbarProjectionOptions;
-  /** Vertical toolbar selection/grouping. true enables all three options; false disables them.
-   * Object fields default to true. Local data-vertical-bars overrides still apply.
-   * Neither layout setting controls tabs, segments or FABs.
-   */
-  vertical?: boolean | ToolbarProjectionOptions;
-  /** Appearance of native vertical ion-button and ion-menu-button actions.
-   * `system` (default) uses SwiftUI styling and template icons; `source` projects supported Ionic fill and colors.
-   * Local data-projection="source|system" or ios-theme-projection-source / ios-theme-projection-system take precedence:
-   * the button itself, then its nearest ion-buttons, then this option. On the same element, a valid attribute wins;
-   * otherwise system wins if both classes are present. Invalid attribute values are ignored.
-   * Local settings update live; removing them restores inheritance. Actions, disabled state and grouping are preserved.
-   * Does not affect back buttons, tabs, FABs, horizontal controls, source elements or Web clones.
-   */
-  buttonProjection?: 'source' | 'system';
-  /** Default fill for native vertical ion-button actions resolved to `source`, including local overrides.
-   * Use `solid` for Ionic's default design, or `null` (also the omitted default) for the iOS theme's glass design.
-   * Applies when fill is omitted or `default`, outside ion-buttons. Inside ion-buttons the default is clear.
-   * Explicit clear, solid and outline take precedence; clear and outline cannot be configured as defaults.
-   * Source elements and Web clones are unchanged.
-   */
-  buttonDefaultFill?: 'solid' | null;
+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 extends VerticalControlAreaOptions {
-  /** Log Web fallback reasons and their source elements once per reason during this activation. Defaults to false. */
-  debug?: 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;
-  /** Ionic adapter settings. Explicit data-native-ui sources and extensions remain independent. */
+  /** App-local projection definitions, independent of controls.
+   * @experimental API and behavior may change.
+   */
+  extensions?: readonly NativeUIExtension[];
   ionic?: IonicProjectionOptions;
-  /** Source subtree. Defaults to document.body. */
-  root?: HTMLElement;
-  /** @deprecated Call destroy() on the running handle to stop the shell. */
-  enabled?: boolean;
-  /** @deprecated Use ionic.auto for automatic Ionic projection and verticalBars.popover for popovers. */
-  controls?: NativeUIControls;
-  /** @deprecated Use verticalBars.only. */
-  verticalBarsOnly?: boolean;
+  /** 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';
-  /** @internal Preserves legacy controls.buttons behavior for explicit sources. */
-  explicitControls?: boolean;
   nativeState?: { edge?: 'left' | 'right' };
-  /** @internal Keep unavailable definitions discoverable for diagnostics without calling their readers. */
   unavailableExtensions?: ReadonlyMap<string, string>;
   rail?: { host: HTMLElement; edge: 'left' | 'right' };
 }
 
-export interface IonicProjectionOptions {
-  /** Automatic Ionic projection. Defaults to true; partial objects keep omitted kinds enabled. */
-  auto?: boolean | AutoIonicControls;
-}
-
-export interface AutoIonicControls {
-  buttons?: boolean;
-  tabs?: boolean;
-  segment?: boolean;
-  fab?: boolean;
-}
-
-export interface NativeUIControls {
-  /** Toolbar actions and explicitly marked HTML buttons. Defaults to true. */
-  buttons?: boolean;
-  /** Projects tab bars and their native search presentation. */
-  tabs?: boolean;
-  /** @deprecated Use buttons. Projects toolbar buttons, including back and menu buttons. */
-  toolbar?: boolean;
-  /** Projects segments. */
-  segment?: boolean;
-  /** Projects floating action buttons. */
-  fab?: boolean;
-  /** Relays popovers anchored to native Vertical Bars buttons. Defaults to false. */
-  popover?: boolean;
-}
-
 /** 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. */
@@ -126,13 +83,6 @@ export interface NativeUIHandle extends NativeUIRuntimeHandle {
 export interface NativeUIVerticalBarsOptions {
   /** Defaults to true. Availability is always determined separately. */
   enabled?: boolean;
-  /** Project only rail controls; unavailable or disabled rails leave controls on the Web. */
-  only?: boolean;
-  buttonProjection?: 'system' | 'source';
-  /** Source-style standalone buttons with no explicit fill. Defaults to glass. */
-  buttonDefaultFill?: 'glass' | 'solid';
-  /** Ionic popover relay. Defaults to false. */
-  popover?: boolean;
   /** Placement preference, not a declaration of device capability. */
   placement?: { edge: Exclude<VerticalBarEdge, null>; webHost?: HTMLElement };
 }
@@ -290,7 +240,7 @@ export interface WebViewMetrics {
 }
 
 export interface NativeUIPlugin {
-  configure(options?: { verticalBarsOnly?: boolean }): Promise<{ supported: boolean; extensions?: string[] }>;
+  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> }>;

package/src/native/html.ts

@@ -19,11 +19,6 @@ export const readHTMLControl = (element: HTMLElement, id: Identify, options: Nat
   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);

package/src/native/index.ts

@@ -10,7 +10,7 @@ export type {
   NativeUIVerticalBarsOptions,
   NativeUIComponent,
   NativeUIControls,
-  AutoIonicControls,
+  ControlProjection,
   IonicProjectionOptions,
   NativeUIHandle,
   NativeUIOptions,
@@ -19,7 +19,6 @@ export type {
   VerticalBarEdge,
   VerticalBarPlacement,
   VerticalControlAreaHandle,
-  ToolbarProjectionOptions,
   VerticalControlAreaOptions,
   WebViewMetrics,
 } from './definitions';
@@ -28,14 +27,6 @@ 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,
-  });
+  const handle = await enableNativeUI({ ...options, controls: options.controls ?? 'verticalOnly' });
   return { ...handle, setPlacement: setVerticalControlAreaPlacement };
 };

package/src/native/overlays/controller.ts

@@ -227,7 +227,7 @@ export const createOverlayController = async (
       overlay.localName === 'ion-popover' &&
       overlay.mode !== 'md' &&
       !overlay.classList.contains('md') &&
-      options.controls?.popover === true &&
+      options.ionic?.verticalBars?.popover === true &&
       nativeVerticalBars() &&
       verticalBarsPopoverAnchor(overlay) !== undefined;
     if (stopped || suspensions.size || !enabled || excluded(overlay)) {

package/src/native/prehide.ts

@@ -99,7 +99,7 @@ export const prehideVerticalBarsToolbarSources = (
         const children = childElements(element);
         const actions = children.filter((child) => eligible(child) && selectedAction(child, options));
         const group =
-          (localPlacement(element) ?? toolbarOptions(options, true).buttons) &&
+          (localPlacement(element) ?? toolbarOptions(options, true).buttonGroup) &&
           eligible(element) &&
           actions.length === children.length &&
           (actions.length > 1 || (actions.length === 1 && actions[0].matches('ion-menu-button')));

package/src/native/runtime.ts

@@ -1,3 +1,4 @@
+import { controlSelected } from './shared/control-options';
 import { createDiagnostics } from './shared/diagnostics';
 import { htmlSelector, readHTMLControl } from './html';
 import { extensionAncestors, readExtension } from './extensions';
@@ -53,7 +54,6 @@ export const createRuntime = async (
   plugin: NativeUIPlugin,
   options: NativeUIRuntimeOptions = {},
   nativeVerticalBars: () => boolean = () => true,
-  verticalBarsOnly = false,
   onStop?: (cause: 'failure' | 'pagehide') => void,
 ): Promise<NativeUIRuntimeHandle & { retain: (deferActivation?: (id: string) => boolean) => () => void }> => {
   const win = doc.defaultView!;
@@ -118,16 +118,12 @@ export const createRuntime = async (
   let listener: PluginListenerHandle | undefined;
   let searchListener: PluginListenerHandle | undefined;
   let waiters: (() => void)[] = [];
-  const control = (kind: Candidate['control']['kind']): keyof NonNullable<NativeUIRuntimeOptions['controls']> => {
-    if (kind === 'tab-bar') return 'tabs';
-    if (kind === 'segment') return 'segment';
-    if (kind === 'floating-action-button') return 'fab';
-    return 'toolbar';
-  };
   const controlEnabled = (candidate: Candidate) => {
-    if (candidate.control.kind === 'extension') return true;
-    const controls = options.controls;
-    return controls === undefined || controls[control(candidate.control.kind)] === true;
+    const kind = candidate.control.kind;
+    // Button readers apply selection/grouping per child; explicit HTML and extensions
+    // are independent opt-ins. Only other automatic kinds need this final selection.
+    const key = kind === 'tab-bar' ? 'tabs' : kind === 'segment' ? 'segment' : kind === 'floating-action-button' ? 'fab' : undefined;
+    return !key || controlSelected(candidate.element, options, key, candidate.control.placement === 'vertical-bars');
   };
   const id = (element: Element) => {
     let value = ids.get(element);
@@ -200,10 +196,6 @@ export const createRuntime = async (
         return;
       }
       const candidate = readExtension(element, extensions, id, (reason) => diagnose(`${extension.name}: ${reason}`, element));
-      if (verticalBarsOnly && (!candidate?.control.extension?.tabBarId || !nativeVerticalBars())) {
-        if (candidate) diagnose('rail-only: element extensions stay on the Web when verticalBars.only is true.', element);
-        return;
-      }
       return candidate;
     }
     if (options.source === 'extensions') return;
@@ -217,12 +209,11 @@ export const createRuntime = async (
         return;
       }
       const rail = candidate.control.placement === 'vertical-bars';
-      if (verticalBarsOnly && !rail) return;
       if (rail && !nativeVerticalBars()) return;
       return candidate;
     }
     if (element.querySelector(htmlSelector)) return; // A shared automatic surface must not cover explicitly selected descendants.
-    if (verticalBarsOnly && (!isVerticalBarsCandidate(element) || element.closest('[data-native-ui-placement="element"]'))) return;
+    if (options.ionic?.auto === false) return;
     if (options.verticalBars?.enabled === false && isVerticalBarsCandidate(element)) return;
     const pointerPage = isVerticalBarsCandidate(element) ? element.closest<HTMLElement>('.ion-page') : undefined;
     let candidate: Candidate | undefined;

package/src/native/shared/candidate.ts

@@ -4,8 +4,8 @@ import { iconSource, type createIconRenderer } from './icons';
 
 export interface Candidate {
   assets?: { signature: string; render(renderer: ReturnType<typeof createIconRenderer>): Promise<void> };
-  buttonProjection?: VerticalControlAreaOptions['buttonProjection'];
-  buttonDefaultFill?: VerticalControlAreaOptions['buttonDefaultFill'];
+  buttonProjection?: 'system' | 'source';
+  buttonDefaultFill?: 'solid' | null;
   element: HTMLElement;
   sources?: HTMLElement[];
   control: NativeUIControl;
@@ -26,8 +26,8 @@ export const createCandidate = (
   const style = getComputedStyle(element);
   return {
     element,
-    buttonProjection: options.buttonProjection,
-    buttonDefaultFill: options.buttonDefaultFill,
+    buttonProjection: options.ionic?.verticalBars?.buttonProjection ?? 'system',
+    buttonDefaultFill: options.ionic?.verticalBars?.buttonDefaultFill === 'solid' ? 'solid' : null,
     control: {
       id: id(element),
       kind:

package/src/native/shared/control-options.ts

@@ -0,0 +1,20 @@
+import type { NativeUIControls, NativeUIOptions } from '../definitions';
+
+/** Resolve one default without changing discovery, explicit selection, or placement. */
+export const controlDefault = (options: NativeUIOptions, kind: keyof NativeUIControls, vertical: boolean): boolean => {
+  const controls = options.controls;
+  const value = typeof controls === 'object' ? controls[kind] : controls;
+  if (value === undefined || value === true) return true;
+  if (value === false) return false;
+  return value === (vertical ? 'verticalOnly' : 'horizontalOnly');
+};
+
+export const controlSelected = (
+  element: HTMLElement,
+  options: NativeUIOptions,
+  kind: keyof NativeUIControls,
+  vertical: boolean,
+): boolean => {
+  const local = element.getAttribute(vertical ? 'data-vertical-bars' : 'data-horizontal-bars');
+  return local === 'true' ? true : local === 'false' ? false : controlDefault(options, kind, vertical);
+};

package/src/native/shared/toolbar-options.ts

@@ -1,17 +1,13 @@
 import { modalUsesVerticalBars } from './modal';
-import type { ToolbarProjectionOptions, VerticalControlAreaOptions } from '../definitions';
+import type { VerticalControlAreaOptions } from '../definitions';
+import { controlDefault } from './control-options';
 import { childElements, inFixedToolbar, isExcluded, isNativeUIDisabled } from './dom';
 
-export const toolbarOptions = (options: VerticalControlAreaOptions, vertical: boolean): Required<ToolbarProjectionOptions> => {
-  const layout = vertical ? options.vertical : options.horizontal;
-  if (typeof layout === 'boolean') return { buttons: layout, button: layout, backButton: layout };
-  const settings = layout ?? {};
-  return {
-    buttons: settings.buttons ?? true,
-    button: settings.button ?? true,
-    backButton: settings.backButton ?? true,
-  };
-};
+export const toolbarOptions = (options: VerticalControlAreaOptions, vertical: boolean) => ({
+  buttonGroup: controlDefault(options, 'buttonGroup', vertical),
+  button: controlDefault(options, 'button', vertical),
+  backButton: controlDefault(options, 'backButton', vertical),
+});
 
 export const localToolbarOption = (element: HTMLElement, vertical: boolean): boolean | undefined => {
   const value = element.getAttribute(vertical ? 'data-vertical-bars' : 'data-horizontal-bars');
@@ -29,7 +25,7 @@ export const horizontalSelected = (element: HTMLElement, options: VerticalContro
 export const horizontalToolbarGroup = (element: HTMLElement, options: VerticalControlAreaOptions): boolean => {
   if (
     !element.matches('ion-buttons.ios') ||
-    !(localToolbarOption(element, false) ?? toolbarOptions(options, false).buttons) ||
+    !(localToolbarOption(element, false) ?? toolbarOptions(options, false).buttonGroup) ||
     !inFixedToolbar(element) ||
     isExcluded(element) ||
     isNativeUIDisabled(element)

package/src/native/startup.ts

@@ -13,27 +13,11 @@ export const startNativeUI = async (input: NativeUIOptions = {}, overlayFactory?
     throw new Error('Native UI requires a connected root in the current document');
   if (host && (!host.isConnected || host.ownerDocument !== document || root?.contains(host) || host.contains(root!)))
     throw new Error('The Web rail host must be connected in the current document and outside the source root');
-  const legacy = input.controls;
-  const automatic = input.ionic?.auto;
-  const controls = automatic === undefined ? legacy : typeof automatic === 'object' ? automatic : {};
-  const defaultEnabled = automatic !== false;
   const options: NativeUIRuntimeOptions = {
     ...input,
     root,
     source: 'auto',
-    explicitControls: automatic !== undefined || (legacy?.buttons ?? legacy?.toolbar ?? true),
     verticalBars: bars,
-    controls: {
-      ...controls,
-      tabs: controls?.tabs ?? defaultEnabled,
-      segment: controls?.segment ?? defaultEnabled,
-      fab: controls?.fab ?? defaultEnabled,
-      toolbar: controls?.buttons ?? (automatic === undefined ? legacy?.toolbar : undefined) ?? defaultEnabled,
-      popover: bars.popover ?? legacy?.popover ?? false,
-    },
-    verticalBarsOnly: bars.only ?? input.verticalBarsOnly ?? false,
-    buttonProjection: bars.buttonProjection ?? input.buttonProjection ?? 'system',
-    buttonDefaultFill: bars.buttonDefaultFill === 'glass' ? null : (bars.buttonDefaultFill ?? input.buttonDefaultFill ?? null),
     rail: host ? { host, edge: bars.placement?.edge === 'leading' ? 'left' : 'right' } : undefined,
   };
   const runtime = await activate(options, overlayFactory);

package/src/native/vertical-bars-web.ts

@@ -1,3 +1,4 @@
+import { controlSelected } from './shared/control-options';
 import { createCrossfade, fadeMarker } from './shared/crossfade';
 import { alignVerticalBarClone, verticalBarFrame } from './shared/vertical-bars-geometry';
 import { createVerticalBarsWebSearch, searchProjectionClass } from './vertical-bars-web-search';
@@ -50,7 +51,7 @@ export const createVerticalBarsWebProjection = (
   const win = doc.defaultView!;
   const crossfade = createCrossfade(win);
   let incomingInstant: boolean | undefined;
-  const toolbarEnabled = options.controls === undefined || options.controls.toolbar === true;
+  const toolbarEnabled = options.ionic?.auto !== false;
   let root: HTMLElement | undefined;
   let backSource: HTMLIonBackButtonElement | undefined;
   let backProjection: HTMLIonBackButtonElement | undefined;
@@ -79,7 +80,8 @@ export const createVerticalBarsWebProjection = (
   const search = createVerticalBarsWebSearch(
     doc,
     (element) =>
-      (options.controls === undefined || options.controls.tabs === true) &&
+      options.ionic?.auto !== false &&
+      controlSelected(element, options, 'tabs', true) &&
       !!verticalBarsRoot()?.contains(element) &&
       (!options.root || options.root.contains(element)) &&
       !element.closest('[data-native-ui-placement="element"]') &&

package/src/vertical-bars.ts

@@ -5,7 +5,8 @@ export type {
   VerticalBarEdge,
   VerticalControlAreaHandle,
   VerticalControlAreaOptions,
-  ToolbarProjectionOptions,
+  ControlProjection,
+  NativeUIControls,
 } from './native';
 
 export { applyFoldStateClasses } from './native/foldable/fold-state';

package/docs/native-mini-player.md

@@ -1,47 +0,0 @@
----
-title: Native UI Extension: Now Playing
----
-
-# Native UI Extension: Now Playing
-
-This example uses the experimental extension API, which may change in future releases.
-
-Use the [app-local extension API](native-ui-extensions.md) to add a SwiftUI mini-player with a Web fallback. The demo's Index → Native UI Extension page provides a sample you can copy into your application.
-
-- [Web component](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/demo/src/app/mini-player/mini-player.component.ts): owns playback state and the Now Playing modal. Play/pause is separate from opening the player. Tap or swipe up on the track opens the same modal.
-- [Web renderer + DOM reader](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/demo/src/native-ui/mini-player.ts): renders the Web UI from attributes, sends title, artist and playback state to SwiftUI, and maps `open` / `toggle` to the original Web buttons.
-- [SwiftUI View](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/demo/ios/App/App/NativeMiniPlayer.swift): uses `Button`, SF Symbols, `DragGesture`, and a capsule glass background. It awaits `NativeUIActions.activate()` rather than duplicating playback state or presenting its own modal.
-
-The SwiftUI sample uses `NativeUIContext.sourceFrame.width` for compact spacing and `actions.isAvailable(...)` to disable actions whose Web targets are unavailable. See [projection context](native-ui-extensions.md#read-source-geometry-and-presentation-state) for coordinate units and system placement.
-
-Register the View once in the app delegate and pass `miniPlayer` in `enableNativeUI({ extensions: [miniPlayer] })`. Copy these app-local files to adapt the sample to your own playback state and artwork. The original sunset artwork is drawn with SwiftUI shapes, with a matching local SVG for the Web. The compact player shows only artwork, track metadata and playback; elapsed time stays in Now Playing.
-
-The sample uses the default **element projection**: SwiftUI follows the Web element’s position and size on iOS 26+, with ordinary tabs or Vertical Bars. Browsers and unsupported environments retain the Web player. Use the **Native extension** toggle to switch native projection on or off. The player starts in Web mode; disabling the extension restores its Web UI. It is shown only on this demo page; leaving the page hides it without resetting playback state.
-
-The Web fallback reserves its own bottom-slot space and keeps play state across tab changes. Opening Now Playing retires the native player through the shell's existing overlay policy; dismissing it restores the current Web state.
-
-This is a UI example: elapsed time is fixed and no audio engine is started. Applications own playback and reflect current values into the Web DOM. Connect your application's audio engine to the sample's playback events before using it as a player.
-
-## Use the Web + SwiftUI set in your application
-
-The local TypeScript file includes both a renderer for an ordinary DOM element and its native reader. Copy it together with `NativeMiniPlayer.swift`; in your app, replace the demo’s relative `defineNativeUI` import with `@rdlabo/capacitor-native-ui`. The Web renderer works without Angular, Capacitor or an enabled Native UI; SwiftUI replaces it only after native accepts the projection.
-
-```ts
-import { miniPlayer, mountNowPlaying } from './native-ui/mini-player';
-import { enableNativeUI } from '@rdlabo/capacitor-native-ui';
-
-const player = document.querySelector<HTMLElement>('[data-mini-player]')!;
-const destroyWeb = mountNowPlaying(player); // Run on every platform, including the Web.
-player.addEventListener('togglePlayback', () => {
-  player.setAttribute('data-playing', String(player.getAttribute('data-playing') !== 'true'));
-});
-player.addEventListener('openNowPlaying', () => openNowPlaying());
-await enableNativeUI({ extensions: [miniPlayer] });
-// Call destroyWeb() when the application's source element is destroyed.
-```
-
-```html
-<section data-mini-player data-title="Midnight Drive" data-artist="The Coast" data-playing="true"></section>
-```
-
-The sample does not specify `placement`; the default is `'element'`. Applications can opt into `placement: 'tab-accessory'` when they want a system tab accessory; see the [placement options and host requirements](native-ui-extensions.md#content-and-placement-are-independent). Its surrounding Web layout belongs to the application. The same attributes feed the Web view and SwiftUI; both dispatch the same events. The application updates attributes after its playback state changes. Mount into an empty element. The Web renderer owns only its generated children and releases its observer and handlers on teardown. Frameworks own the host's attributes, not those children. Text is rendered as text, never interpreted as HTML.