@webview-native-ui/engine 1.0.1 → 1.0.2-0

package/dist/controls/shared/bridge.d.ts

@@ -0,0 +1,4 @@
+import type { NativeUIListenerHandle as PluginListenerHandle } from '../transport.js';
+export declare const bounded: <T>(promise: Promise<T>) => Promise<T>;
+/** A timed-out registration still owns a native resource if it eventually succeeds. */
+export declare const boundedListener: (registration: Promise<PluginListenerHandle>) => Promise<PluginListenerHandle>;

package/dist/controls/shared/bridge.js

@@ -0,0 +1,15 @@
+// A failed bridge must not leave the source inaccessible indefinitely.
+export const bounded = (promise) => new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('Native UI bridge timed out')), 5000);
+    promise.then(resolve, reject).finally(() => clearTimeout(timer));
+});
+/** A timed-out registration still owns a native resource if it eventually succeeds. */
+export const boundedListener = async (registration) => {
+    try {
+        return await bounded(registration);
+    }
+    catch (error) {
+        void registration.then((listener) => listener.remove()).catch(() => { });
+        throw error;
+    }
+};

package/dist/controls/shared/candidate.d.ts

@@ -0,0 +1,23 @@
+import type { NativeUIControl, NativeUIItem, NativeUIControlKind, NativeUIComponent, VerticalControlAreaOptions } from '../definitions.js';
+import { type createIconRenderer } from './icons.js';
+export interface Candidate {
+    scrollElement?: HTMLElement;
+    assets?: {
+        signature: string;
+        render(renderer: ReturnType<typeof createIconRenderer>): Promise<void>;
+    };
+    buttonProjection?: 'system' | 'source';
+    buttonDefaultFill?: 'solid' | null;
+    element: HTMLElement;
+    sources?: HTMLElement[];
+    control: NativeUIControl;
+    actions: Map<string, HTMLElement>;
+    icons: {
+        item: NativeUIItem;
+        source: string;
+        field?: 'closeIcon';
+    }[];
+}
+export type Identify = (element: HTMLElement) => string;
+export declare const createCandidate: (element: HTMLElement, kind: NativeUIComponent | NativeUIControlKind, id: Identify, options?: VerticalControlAreaOptions) => Candidate;
+export declare const appendItem: (candidate: Candidate, child: HTMLElement, id: Identify, content?: ParentNode, label?: string) => NativeUIItem | undefined;

package/dist/controls/shared/candidate.js

@@ -0,0 +1,128 @@
+import { frame, isDark, isVerticalBarsSource, text, visible } from './dom.js';
+import { iconSource } from './icons.js';
+export const createCandidate = (element, kind, id, options = {}) => {
+    const rect = element.getBoundingClientRect();
+    const style = getComputedStyle(element);
+    return {
+        element,
+        buttonProjection: options.ionic?.verticalBars?.buttonProjection ?? 'system',
+        buttonDefaultFill: options.ionic?.verticalBars?.buttonDefaultFill === 'solid' ? 'solid' : null,
+        control: {
+            id: id(element),
+            kind: {
+                'ion-button': 'button',
+                'ion-buttons': 'button-group',
+                'ion-back-button': 'back-button',
+                'ion-menu-button': 'menu-button',
+                'ion-tab-bar': 'tab-bar',
+                'ion-segment': 'segment',
+                'ion-fab': 'floating-action-button',
+            }[kind] ?? kind,
+            ...frame(rect),
+            items: [],
+            dark: isDark(style),
+            rtl: style.direction === 'rtl',
+        },
+        actions: new Map(),
+        icons: [],
+    };
+};
+// Shared text, artwork, geometry and action data; component rules stay with their readers.
+export const appendItem = (candidate, child, id, content = child, label = text(child)) => {
+    if (!visible(child, isVerticalBarsSource(candidate.element)) ||
+        child.querySelector('input, button, a, img:not([data-native-ui-projection-node]), canvas, video, ion-spinner, ion-avatar'))
+        return;
+    const icons = Array.from(content.querySelectorAll('ion-icon'));
+    const directSVGs = Array.from(content.querySelectorAll('svg'));
+    if (icons.length + directSVGs.length > 1)
+        return undefined;
+    const svg = directSVGs[0] ?? icons[0]?.shadowRoot?.querySelector('svg');
+    if (icons.length && !svg)
+        return undefined; // ion-icon has not finished loading.
+    const labelElement = content.querySelector('[part="text"], ion-label') ?? child;
+    const native = child.shadowRoot?.querySelector('[part="native"]');
+    const labelStyle = getComputedStyle(labelElement);
+    const badge = child.querySelector('ion-badge');
+    const badgeStyle = badge && visible(badge) ? getComputedStyle(badge) : undefined;
+    const sourceFill = child.fill;
+    const projectionOwner = [child, child.closest('ion-buttons')].find((element) => element?.matches('[data-projection="source"], [data-projection="system"], .ios-theme-projection-source, .ios-theme-projection-system'));
+    const attributeProjection = projectionOwner?.getAttribute('data-projection');
+    const projection = attributeProjection === 'source' || attributeProjection === 'system'
+        ? attributeProjection
+        : projectionOwner
+            ? projectionOwner.classList.contains('ios-theme-projection-system')
+                ? 'system'
+                : 'source'
+            : candidate.buttonProjection;
+    const systemButton = projection !== 'source' && isVerticalBarsSource(child) && child.matches('ion-button, ion-menu-button');
+    // Ionic defaults buttons inside ion-buttons to clear, even when the app defaults to solid.
+    const defaultFill = child.closest('ion-buttons') ? 'clear' : candidate.buttonDefaultFill;
+    const fill = !sourceFill || sourceFill === 'default' ? defaultFill : sourceFill;
+    const buttonFill = !systemButton &&
+        isVerticalBarsSource(child) &&
+        child.matches('ion-button') &&
+        (fill === 'clear' || fill === 'solid' || fill === 'outline')
+        ? fill
+        : undefined;
+    const outline = buttonFill === 'outline' ? getComputedStyle(native ?? child) : undefined;
+    const item = {
+        id: id(child),
+        ...frame(child.getBoundingClientRect(), candidate.element.getBoundingClientRect()),
+        label,
+        accessibilityLabel: child.getAttribute('aria-label') ??
+            native?.getAttribute('aria-label') ??
+            (icons[0]?.getAttribute('aria-hidden') === 'true' ? null : icons[0]?.getAttribute('aria-label')) ??
+            label,
+        disabled: !!child.disabled ||
+            !!candidate.element.disabled ||
+            getComputedStyle(child).pointerEvents === 'none',
+        selected: !!child.selected,
+        fontSize: parseFloat(labelStyle.fontSize),
+        fontWeight: parseInt(labelStyle.fontWeight, 10) || 400,
+        color: systemButton ? 'currentColor' : getComputedStyle(native ?? child).color,
+        iconTemplate: systemButton ? true : undefined,
+        buttonFill,
+        backgroundColor: buttonFill === 'solid' ? getComputedStyle(native ?? child).backgroundColor : undefined,
+        borderColor: outline?.borderTopColor,
+        borderWidth: outline ? parseFloat(outline.borderTopWidth) : undefined,
+        badge: badgeStyle
+            ? { value: badge.textContent?.trim() ?? '', color: badgeStyle.backgroundColor, textColor: badgeStyle.color }
+            : undefined,
+    };
+    if (svg) {
+        const source = iconSource(svg);
+        if (!source)
+            return undefined;
+        const size = (icons[0] ?? svg).getBoundingClientRect();
+        item.iconWidth = size.width;
+        item.iconHeight = size.height;
+        if (!size.width || !size.height)
+            return undefined;
+        item.iconPosition = (icons[0] ?? svg).getAttribute('slot') === 'end' ? 'trailing' : 'leading';
+        candidate.icons.push({ item, source });
+    }
+    if (native && child.matches('ion-button, ion-back-button')) {
+        const style = getComputedStyle(native);
+        const icon = icons[0] ?? svg;
+        const iconStyle = icon && getComputedStyle(icon);
+        const leadingMargin = parseFloat(iconStyle?.marginInlineStart ?? '') || 0;
+        const trailingMargin = parseFloat(iconStyle?.marginInlineEnd ?? '') || 0;
+        const trailing = item.iconPosition === 'trailing';
+        const inner = native.querySelector('.button-inner');
+        const gap = inner ? parseFloat(getComputedStyle(inner).columnGap) || 0 : 0;
+        // UIKit centers the title/image pair using its insets. Include Ionic's
+        // border and negative outer icon margin instead of applying a fixed offset.
+        item.contentInsetLeading =
+            (parseFloat(style.paddingInlineStart) || 0) +
+                (parseFloat(style.borderInlineStartWidth) || 0) +
+                (!trailing || !label ? leadingMargin : 0);
+        item.contentInsetTrailing =
+            (parseFloat(style.paddingInlineEnd) || 0) + (parseFloat(style.borderInlineEndWidth) || 0) + (trailing || !label ? trailingMargin : 0);
+        item.imagePadding = label && icon ? gap + (trailing ? leadingMargin : trailingMargin) : 0;
+    }
+    if (!label && !svg)
+        return undefined;
+    candidate.control.items.push(item);
+    candidate.actions.set(item.id, child);
+    return item;
+};

package/dist/controls/shared/clipping.d.ts

@@ -0,0 +1 @@
+export { projectionAncestors, fitsClip } from '../../index.js';

package/dist/controls/shared/clipping.js

@@ -0,0 +1 @@
+export { projectionAncestors, fitsClip } from '../../index.js';

package/dist/controls/shared/connection.d.ts

@@ -0,0 +1,21 @@
+import type { NativeUIListenerHandle as PluginListenerHandle } from '../transport.js';
+import type { NativeUIConnectionState, NativeUIPlugin } from '../definitions.js';
+type Check = (state: NativeUIConnectionState, restored: boolean, requestedAt: number) => void | Promise<void>;
+type Failure = (error: unknown) => void | Promise<void>;
+/** One connection check for the shell, independent of projection retention. */
+export declare const createNativeConnection: (doc: Document, plugin: NativeUIPlugin) => {
+    listen: {
+        (name: "snapshotInteraction", listener: (event: {
+            active: boolean;
+        }) => void): Promise<PluginListenerHandle>;
+        (name: "activate", listener: (event: import("../definitions.js").NativeUIActivation) => void): Promise<PluginListenerHandle>;
+        (name: "search", listener: (event: import("../definitions.js").NativeUISearchEvent) => void): Promise<PluginListenerHandle>;
+        (name: "webViewMetricsChange", listener: (event: import("../definitions.js").WebViewMetrics) => void): Promise<PluginListenerHandle>;
+        (name: "overlay", listener: (event: import("../definitions.js").NativeUIOverlayEvent) => void): Promise<PluginListenerHandle>;
+    };
+    observe(callback: Check, failure?: Failure): () => void;
+    start(): void;
+    stop(): void;
+};
+export type NativeUIConnection = ReturnType<typeof createNativeConnection>;
+export {};

package/dist/controls/shared/connection.js

@@ -0,0 +1,112 @@
+import { bounded, boundedListener } from './bridge.js';
+const failureLimit = 3;
+/** One connection check for the shell, independent of projection retention. */
+export const createNativeConnection = (doc, plugin) => {
+    const registrations = new Set();
+    const checks = new Set();
+    const failures = new Map();
+    let stopped = false;
+    let timer;
+    let session;
+    let failed = false;
+    let consecutiveFailures = 0;
+    const install = async (registration) => {
+        const add = plugin.addListener;
+        const handle = await boundedListener(add.call(plugin, registration.name, registration.callback));
+        if (stopped || !registrations.has(registration))
+            await bounded(handle.remove());
+        else
+            registration.handle = handle;
+    };
+    const listen = (async (name, callback) => {
+        const registration = { name, callback };
+        registrations.add(registration);
+        try {
+            await install(registration);
+        }
+        catch (error) {
+            registrations.delete(registration);
+            throw error;
+        }
+        return {
+            async remove() {
+                registrations.delete(registration);
+                await registration.handle?.remove();
+            },
+        };
+    });
+    const check = async () => {
+        if (stopped)
+            return;
+        if (!doc.hidden) {
+            const requestedAt = doc.defaultView.performance.now();
+            const registered = Array.from(registrations);
+            const observed = Array.from(checks);
+            try {
+                const state = await bounded(plugin.getConnectionState());
+                if (stopped)
+                    return;
+                let restored = failed || (session !== undefined && session !== state.session);
+                session = state.session;
+                for (const registration of registered) {
+                    if (state.listeners.includes(registration.name) || !registrations.has(registration))
+                        continue;
+                    // Remove our previous callback before installing another; never replay events.
+                    await bounded(Promise.resolve(registration.handle?.remove()));
+                    if (stopped || !registrations.has(registration))
+                        continue;
+                    await install(registration);
+                    restored = true;
+                }
+                if (stopped)
+                    return;
+                for (const callback of observed) {
+                    if (checks.has(callback))
+                        await callback(state, restored, requestedAt);
+                    if (stopped)
+                        return;
+                }
+                failed = false;
+                consecutiveFailures = 0;
+            }
+            catch (error) {
+                if (stopped)
+                    return;
+                // A later successful handshake repairs subscriptions and resynchronizes
+                // current state. A timeout ends this logical check, not the underlying request.
+                failed = true;
+                if (++consecutiveFailures >= failureLimit) {
+                    for (const callback of observed) {
+                        if (checks.has(callback))
+                            await failures.get(callback)?.(error);
+                        if (stopped)
+                            return;
+                    }
+                }
+            }
+        }
+        if (!stopped)
+            timer = setTimeout(() => void check(), 1000);
+    };
+    return {
+        listen,
+        observe(callback, failure) {
+            checks.add(callback);
+            if (failure)
+                failures.set(callback, failure);
+            return () => {
+                checks.delete(callback);
+                failures.delete(callback);
+            };
+        },
+        start() {
+            timer = setTimeout(() => void check(), 1000);
+        },
+        stop() {
+            stopped = true;
+            clearTimeout(timer);
+            checks.clear();
+            failures.clear();
+        },
+    };
+};

package/dist/controls/shared/control-options.d.ts

@@ -0,0 +1,4 @@
+import type { NativeUIControls, NativeUIOptions } from '../definitions.js';
+/** Resolve one default without changing discovery, explicit selection, or placement. */
+export declare const controlDefault: (options: NativeUIOptions, kind: keyof NativeUIControls, vertical: boolean) => boolean;
+export declare const controlSelected: (element: HTMLElement, options: NativeUIOptions, kind: keyof NativeUIControls, vertical: boolean) => boolean;

package/dist/controls/shared/control-options.js

@@ -0,0 +1,14 @@
+/** Resolve one default without changing discovery, explicit selection, or placement. */
+export const controlDefault = (options, kind, vertical) => {
+    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, options, kind, vertical) => {
+    const local = element.getAttribute(vertical ? 'data-vertical-bars' : 'data-horizontal-bars');
+    return local === 'true' ? true : local === 'false' ? false : controlDefault(options, kind, vertical);
+};

package/dist/controls/shared/covered-snapshot.d.ts

@@ -0,0 +1,35 @@
+import type { NativeUIPlugin } from '../definitions.js';
+/** Ionic supplies source ownership and proxy placement; Engine owns image handoff. */
+export declare const createCoveredSnapshots: (doc: Document, plugin: NativeUIPlugin, listen: NativeUIPlugin["addListener"], callbacks: {
+    wake: () => void;
+    blocked: () => boolean;
+    modal?: HTMLIonModalElement;
+    revision?: () => number;
+}) => Promise<Omit<{
+    readonly owners: readonly HTMLElement[];
+    readonly visibleOwners: readonly HTMLElement[];
+    readonly preparedOwners: readonly HTMLElement[];
+    consider: (revision: number, candidates: import("../../types.js").ScopedWebProjectionSource[]) => void;
+    changed: (scrollOwner?: EventTarget) => void;
+    moved: () => void;
+    readonly token: string | undefined;
+    begin: () => void;
+    readonly restoring: boolean;
+    readonly handoffPending: boolean;
+    retireRestoration: () => void;
+    end: () => void;
+    updated: (token: string | undefined, restoredIDs?: string[], revision?: number) => void;
+    invalidate: (nativeHidden?: boolean) => void;
+    destroy(): Promise<void>;
+}, "consider"> & {
+    consider(revision: number, sources: import("../../types.js").ScopedWebProjectionSource[]): void;
+} & {
+    consider(revision: number, sources: import("../../types.js").WebProjectionSource[]): void;
+    begin(layer?: HTMLElement): void;
+    updated(token: string | undefined, ids?: string[], revision?: number): void;
+    invalidate(nativeHidden?: boolean): void;
+    destroy(): Promise<void>;
+} & {
+    destroy(): Promise<void>;
+}>;
+export type CoveredSnapshots = Awaited<ReturnType<typeof createCoveredSnapshots>>;

package/dist/controls/shared/covered-snapshot.js

@@ -0,0 +1,41 @@
+import { createWebProjectionSurface } from '../../index.js';
+import { getProjectionState } from './covered-source.js';
+/** Ionic supplies source ownership and proxy placement; Engine owns image handoff. */
+export const createCoveredSnapshots = async (doc, plugin, listen, callbacks) => {
+    const state = getProjectionState(doc);
+    const { modal, wake, blocked, revision } = callbacks;
+    const projection = await createWebProjectionSurface({
+        send: (request) => plugin.coveredSnapshot(request),
+        listen: (listener) => listen('snapshotInteraction', listener),
+    }, {
+        namespace: 'native-ui',
+        target: ({ element: source, control }) => {
+            const proxy = state.getTarget(source);
+            return control.placement === 'vertical-bars' &&
+                (proxy || source.matches('ion-button, ion-buttons, ion-back-button, ion-menu-button'))
+                ? proxy
+                : source;
+        },
+        canRelocate: (target) => target.matches('.ion-cloned-element, [data-native-ui-proxy]'),
+        wake,
+        blocked,
+        revision,
+        transient: !!modal,
+        eligible: (source) => modal
+            ? source.element.closest('ion-modal') === modal && source.control.placement === 'vertical-bars'
+            : !source.element.closest('ion-modal'),
+        current: (sources) => !modal || sources.every((source) => source.closest('ion-modal') === modal),
+    });
+    const unregister = state.register(projection);
+    const destroy = projection.destroy;
+    return Object.assign(projection, {
+        async destroy() {
+            try {
+                await destroy();
+            }
+            finally {
+                unregister();
+            }
+        },
+    });
+};

package/dist/controls/shared/covered-source.d.ts

@@ -0,0 +1,22 @@
+import type { WebProjectionBatch } from '../../index.js';
+declare const createState: () => {
+    imageMarker: string;
+    nativeOwns: (source: HTMLElement) => boolean;
+    registerNativeOwner(owns: (source: HTMLElement) => boolean): () => boolean;
+    readonly snapshotsEnabled: boolean;
+    sourcesChangedEvent: string;
+    targetsChangedEvent: string;
+    register(manager: WebProjectionBatch): () => boolean;
+    readonly owners: readonly HTMLElement[];
+    readonly visibleOwners: readonly HTMLElement[];
+    readonly preparedOwners: readonly HTMLElement[];
+    owns: (element: HTMLElement) => boolean;
+    isVisible: (element: HTMLElement) => boolean;
+    getTarget: (source: HTMLElement) => HTMLElement | undefined;
+    setTarget: (source: HTMLElement, target: HTMLElement) => void;
+    deleteTarget: (source: HTMLElement) => boolean;
+    isProjectionMutation(record: MutationRecord): boolean;
+};
+export type NativeUIProjectionState = ReturnType<typeof createState>;
+export declare const getProjectionState: (doc: Document) => NativeUIProjectionState;
+export {};

package/dist/controls/shared/covered-source.js

@@ -0,0 +1,72 @@
+/** Ionic's cross-surface ownership and source/proxy mapping, not a projection DOM scope. */
+const states = new WeakMap();
+const createState = () => {
+    const managers = new Set();
+    const nativeOwners = new Set();
+    const targets = new WeakMap();
+    const imageMarker = 'data-native-ui-snapshot';
+    const collect = (key) => [...new Set([...managers].flatMap((manager) => manager[key]))];
+    return {
+        imageMarker,
+        nativeOwns: (source) => [...nativeOwners].some((owns) => owns(source)),
+        registerNativeOwner(owns) {
+            nativeOwners.add(owns);
+            return () => nativeOwners.delete(owns);
+        },
+        get snapshotsEnabled() {
+            return managers.size > 0;
+        },
+        sourcesChangedEvent: 'native-ui:sources-change',
+        targetsChangedEvent: 'native-ui:targets-change',
+        register(manager) {
+            managers.add(manager);
+            return () => managers.delete(manager);
+        },
+        get owners() {
+            return collect('owners');
+        },
+        get visibleOwners() {
+            return collect('visibleOwners');
+        },
+        get preparedOwners() {
+            return collect('preparedOwners');
+        },
+        owns: (element) => collect('owners').some((owner) => owner === element || owner.contains(element)),
+        isVisible: (element) => collect('visibleOwners').some((owner) => owner === element || owner.contains(element)),
+        getTarget: (source) => targets.get(source),
+        setTarget: (source, target) => {
+            targets.set(source, target);
+        },
+        deleteTarget: (source) => targets.delete(source),
+        isProjectionMutation(record) {
+            const target = record.target instanceof Element ? record.target : record.target.parentElement;
+            if (target?.closest('[data-native-ui-projection-node]'))
+                return true;
+            if (target?.closest('.ion-cloned-element, [data-native-ui-proxy]'))
+                return true;
+            if (record.type === 'attributes' &&
+                [
+                    imageMarker,
+                    'data-native-ui-proxy-prepared',
+                    'data-native-ui-snapshot-prepared',
+                    'data-native-ui-snapshot-source',
+                    'data-native-ui-snapshot-visible',
+                    'data-native-ui-snapshot-content',
+                    'data-native-ui-snapshot-positioned',
+                ].includes(record.attributeName ?? ''))
+                return true;
+            const image = (node) => node instanceof Element &&
+                node.matches(`style[${imageMarker}], style[data-native-ui-snapshot-base], [data-native-ui-proxy-prepared], [data-native-ui-snapshot-prepared], [data-native-ui-projection-node]`);
+            const nodes = [...Array.from(record.addedNodes), ...Array.from(record.removedNodes)];
+            return image(record.target) || (record.type === 'childList' && nodes.length > 0 && nodes.every(image));
+        },
+    };
+};
+export const getProjectionState = (doc) => {
+    let state = states.get(doc);
+    if (!state) {
+        state = createState();
+        states.set(doc, state);
+    }
+    return state;
+};

package/dist/controls/shared/crossfade.d.ts

@@ -0,0 +1,11 @@
+export declare const handoffDuration = 180;
+export declare const fadeMarker = "data-native-ui-fading";
+/** Only visual opacity animates; the runtime transfers input/accessibility ownership once. */
+export declare const createCrossfade: (win: Window) => {
+    duration: (instant?: boolean) => 0 | 180;
+    play(element: HTMLElement, toNative: boolean, instant?: boolean): void;
+    retire(element: HTMLElement, instant?: boolean): void;
+    finish: () => void;
+    settled(): Promise<void>;
+    destroy(): void;
+};

package/dist/controls/shared/crossfade.js

@@ -0,0 +1,71 @@
+export const handoffDuration = 180;
+export const fadeMarker = 'data-native-ui-fading';
+/** Only visual opacity animates; the runtime transfers input/accessibility ownership once. */
+export const createCrossfade = (win) => {
+    const active = new Map();
+    const retired = new Set();
+    const reduced = win.matchMedia('(prefers-reduced-motion: reduce)');
+    const finish = (element, animation) => {
+        if (active.get(element) !== animation)
+            return;
+        active.delete(element);
+        element.removeAttribute(fadeMarker);
+        animation.cancel();
+        if (retired.delete(element))
+            element.remove();
+    };
+    const cancelAll = () => {
+        for (const [element, animation] of active)
+            finish(element, animation);
+    };
+    reduced.addEventListener('change', cancelAll);
+    const api = {
+        duration: (instant = false) => (reduced.matches || instant ? 0 : handoffDuration),
+        play(element, toNative, instant = false) {
+            const previous = active.get(element);
+            // Instant handoffs must not force layout before retiring an outgoing tab.
+            if (reduced.matches || instant || !element.isConnected) {
+                if (previous)
+                    finish(element, previous);
+                element.removeAttribute(fadeMarker);
+                return;
+            }
+            const current = Number(win.getComputedStyle(element).opacity);
+            previous?.cancel();
+            active.delete(element);
+            // Measure the Web appearance after lifting ownership concealment.
+            element.setAttribute(fadeMarker, '');
+            const opacity = Number(win.getComputedStyle(element).opacity);
+            const animation = element.animate([{ opacity: previous ? current : toNative ? opacity : 0 }, { opacity: toNative ? 0 : opacity }], {
+                duration: handoffDuration,
+                easing: 'ease-in-out',
+                fill: 'both',
+            });
+            active.set(element, animation);
+            void animation.finished.then(() => finish(element, animation), () => finish(element, animation));
+        },
+        retire(element, instant = false) {
+            element.inert = true;
+            element.setAttribute('aria-hidden', 'true');
+            element.style.setProperty('pointer-events', 'none', 'important');
+            if (!api.duration(instant) || !element.isConnected) {
+                const previous = active.get(element);
+                if (previous)
+                    finish(element, previous);
+                element.remove();
+                return;
+            }
+            retired.add(element);
+            api.play(element, true);
+        },
+        finish: cancelAll,
+        async settled() {
+            await Promise.all(Array.from(active.values(), (animation) => animation.finished.catch(() => { })));
+        },
+        destroy() {
+            reduced.removeEventListener('change', cancelAll);
+            cancelAll();
+        },
+    };
+    return api;
+};

package/dist/controls/shared/diagnostics.d.ts

@@ -0,0 +1,2 @@
+/** Opt-in diagnostics. Never log props, action data, or application exception messages. */
+export declare const createDiagnostics: (enabled?: boolean) => (reason: string, element?: HTMLElement) => void;

package/dist/controls/shared/diagnostics.js

@@ -0,0 +1,16 @@
+/** Opt-in diagnostics. Never log props, action data, or application exception messages. */
+export const createDiagnostics = (enabled = false) => {
+    const elements = new WeakMap();
+    const global = new Set();
+    return (reason, element) => {
+        if (!enabled)
+            return;
+        const seen = element ? (elements.get(element) ?? new Set()) : global;
+        if (seen.has(reason))
+            return;
+        seen.add(reason);
+        if (element)
+            elements.set(element, seen);
+        console.info(`[Native UI] ${reason}`, ...(element ? [element] : []));
+    };
+};