@webview-native-ui/engine 0.0.0-stage → 0.0.2

package/dist/native/session.js

@@ -0,0 +1,520 @@
+import { projectionPlacement } from '../projection/placement.js';
+import { getOverlayCoordinator } from '../dom/overlays.js';
+import { readScrollPlacement } from '../dom/scroll-placement.js';
+import { projectionAncestors } from '../dom/geometry.js';
+import { createWebProjection } from '../projection/web.js';
+import { createWebProjectionScope } from '../projection/scope.js';
+import { bindProjectionEvents } from '../projection/events.js';
+/** Native startup calls this; application code does not initialize or wrap the plugin. */
+export const startNativeSession = async (config, nativeBridge, plugin = {
+    addListener: async (name, listener) => {
+        const capacitor = globalThis.Capacitor;
+        return capacitor.addListener(config.plugin, name, listener);
+    },
+}) => {
+    const sourceID = 'view';
+    const listeners = config.receiveListeners;
+    let stopped = false;
+    let ready = false;
+    let requestedDestination = 'native';
+    let destination = 'native';
+    const overlays = getOverlayCoordinator(document);
+    const effectiveDestination = () => requestedDestination === 'native' && target && overlays.isCovered(target) ? 'web' : requestedDestination;
+    let automaticMotion = false;
+    let placementPending = false;
+    let nativeScroll = false;
+    let scrollOwner;
+    let scrollTimer;
+    let manager;
+    let startingProjection = false;
+    const beginProjection = () => {
+        const previous = startingProjection;
+        startingProjection = true;
+        try {
+            manager?.begin();
+        }
+        finally {
+            startingProjection = previous;
+        }
+    };
+    let target;
+    const placementOwner = {};
+    let coveredToken;
+    let placementEpoch = 0;
+    const clearPlacement = () => {
+        placementEpoch++;
+        coveredToken = undefined;
+        const binding = projectionPlacement(target);
+        if (binding?.owner === placementOwner) {
+            binding.projected = false;
+            binding.owner = undefined;
+        }
+    };
+    const bridge = {
+        listen: (listener) => nativeBridge.listen(listener),
+        send: (request) => {
+            if (!config.placementHandoff)
+                return nativeBridge.send(request);
+            const binding = projectionPlacement(target);
+            if (request.action === 'cover') {
+                const epoch = ++placementEpoch;
+                coveredToken = request.token;
+                if (binding) {
+                    binding.owner = placementOwner;
+                    binding.projected = false;
+                }
+                return nativeBridge
+                    .send(request)
+                    .then((result) => {
+                    if (epoch === placementEpoch && binding === projectionPlacement(target) && binding?.owner === placementOwner)
+                        binding.projected = result?.shown === true;
+                    return result;
+                })
+                    .catch((error) => {
+                    if (epoch === placementEpoch && binding?.owner === placementOwner) {
+                        clearPlacement();
+                        binding.invalidate();
+                    }
+                    throw error;
+                });
+            }
+            const releasing = request.action === 'release' && request.token === coveredToken;
+            const revealing = coveredToken &&
+                (request.action === 'restore' || releasing || request.action === 'reset' || (request.action === 'visibility' && request.visible));
+            if (revealing)
+                placementEpoch++;
+            const epoch = placementEpoch;
+            const failed = () => {
+                if (epoch !== placementEpoch || binding?.owner !== placementOwner)
+                    return;
+                clearPlacement();
+                binding.invalidate();
+            };
+            // Measure synchronously and use the existing ordered reveal/draw acknowledgement.
+            try {
+                const payload = revealing && binding?.owner === placementOwner
+                    ? { ...request, token: ('token' in request ? request.token : coveredToken), placement: binding.measure() }
+                    : request;
+                return nativeBridge
+                    .send(payload)
+                    .then((result) => {
+                    if (epoch === placementEpoch &&
+                        (request.action === 'resume' || releasing || request.action === 'reset' || request.action === 'visibility'))
+                        clearPlacement();
+                    return result;
+                })
+                    .catch((error) => {
+                    failed();
+                    throw error;
+                });
+            }
+            catch (error) {
+                failed();
+                return Promise.reject(error);
+            }
+        },
+    };
+    let revision = 0;
+    let contentRevision = 0;
+    let generation = 0;
+    let restoring = false;
+    let initializing = false;
+    let scheduled = false;
+    let reconciling = false;
+    const style = document.createElement('style');
+    const marker = `data-native-ui-session-${config.id.replace(/[^a-zA-Z0-9-]/g, '')}`;
+    style.textContent = `[${marker}="native"], [${marker}="native"] *, [${marker}="none"], [${marker}="none"] * {visibility:hidden!important}`;
+    document.documentElement.append(style);
+    const findTarget = () => {
+        const matches = document.querySelectorAll(config.projectionSelector);
+        return matches.length === 1 && matches[0] instanceof HTMLElement ? matches[0] : undefined;
+    };
+    const setVisibility = () => {
+        if (!target)
+            return;
+        if (destination === 'web' || (destination === 'native' && placementPending))
+            target.removeAttribute(marker);
+        else
+            target.setAttribute(marker, destination);
+    };
+    const sources = () => {
+        if (!target?.isConnected)
+            return [];
+        const r = target.getBoundingClientRect();
+        const frame = { x: r.x, y: r.y, width: r.width, height: r.height };
+        const scroll = scrollOwner && readScrollPlacement(target, scrollOwner, () => config.id);
+        return [
+            {
+                element: target,
+                scrollElement: scrollOwner,
+                control: { id: sourceID, ...frame, ...(scroll ? { scroll } : {}) },
+            },
+        ];
+    };
+    const recoverFailedProjection = async () => {
+        if (stopped)
+            return;
+        const version = generation;
+        const native = config.failedFallback === 'native' && effectiveDestination() === 'native' && !!target?.isConnected;
+        await bridge.send({ action: 'visibility', visible: native }).catch(() => { });
+        if (stopped || version !== generation)
+            return;
+        if (native || destination === 'none')
+            setVisibility();
+        else
+            target?.removeAttribute(marker);
+    };
+    const applyFailedFallback = () => {
+        if (!automaticMotion || destination !== 'native' || !target?.isConnected || manager?.token || manager?.restoring)
+            return;
+        const native = config.failedFallback === 'native';
+        void bridge.send({ action: 'visibility', visible: native }).catch(() => { });
+        if (native)
+            setVisibility();
+        else
+            target.removeAttribute(marker);
+    };
+    const wake = () => {
+        // begin() can synchronously retire a previous return before installing its next
+        // image. That intermediate state is not a failed projection or a new reveal.
+        if (stopped || startingProjection)
+            return;
+        applyFailedFallback();
+        if (destination === 'web' && manager && !manager.token && !manager.restoring) {
+            void bridge.send({ action: 'visibility', visible: false }).catch(() => { });
+            target?.removeAttribute(marker);
+            return;
+        }
+        if (restoring || !manager?.restoring || destination !== 'native')
+            return;
+        restoring = true;
+        const version = generation;
+        const current = manager;
+        // The native library acknowledges after the live views have entered a draw pass.
+        void bridge
+            .send({ action: 'resume' })
+            .then(() => {
+            if (stopped || version !== generation || current !== manager)
+                return;
+            placementPending = false;
+            current.updated(undefined, [sourceID], ++revision);
+            setVisibility();
+            schedule();
+        })
+            .catch(() => {
+            if (version !== generation || stopped)
+                return;
+            current.invalidate();
+            void recoverFailedProjection();
+        })
+            .finally(() => {
+            restoring = false;
+            wake();
+        });
+    };
+    const reconcile = async () => {
+        if (stopped || initializing || automaticMotion)
+            return;
+        if (manager?.restoring) {
+            wake();
+            return;
+        }
+        const found = findTarget();
+        if (found !== target) {
+            generation++;
+            clearPlacement();
+            target?.removeAttribute(marker);
+            await manager?.destroy();
+            manager = undefined;
+            if (stopped)
+                return;
+            target = found;
+            placementPending = false;
+            sizeObserver.disconnect();
+            if (target)
+                sizeObserver.observe(target);
+        }
+        refreshScrollListeners();
+        destination = effectiveDestination();
+        if (!target) {
+            await bridge.send({ action: 'visibility', visible: false });
+            return;
+        }
+        if (!manager) {
+            initializing = true;
+            const version = generation;
+            try {
+                const created = await createWebProjection(createWebProjectionScope(target, config.id), bridge, {
+                    wake,
+                    captureDelayMs: config.captureDelayMs,
+                    blocked: () => destination !== 'native' || automaticMotion || (placementPending && !manager?.token),
+                    revision: () => revision,
+                    captureRevision: config.captureMode === 'view' ? () => contentRevision : undefined,
+                    transient: true,
+                    opaqueUnderlay: config.captureMode === 'view',
+                });
+                if (stopped || version !== generation) {
+                    await created.destroy();
+                    return;
+                }
+                manager = created;
+            }
+            finally {
+                initializing = false;
+            }
+        }
+        if (stopped)
+            return;
+        if (destination === 'native' && placementPending) {
+            await bridge.send({ action: 'visibility', visible: false });
+            setVisibility();
+            return;
+        }
+        if (destination === 'native') {
+            const version = generation;
+            await bridge.send({ action: 'visibility', visible: true });
+            if (stopped || version !== generation || destination !== 'native')
+                return;
+            setVisibility();
+            scrollOwner = [...projectionAncestors(target)].find((element) => {
+                const style = getComputedStyle(element);
+                return (/auto|scroll/.test(style.overflowX + style.overflowY) &&
+                    (element.scrollHeight > element.clientHeight || element.scrollWidth > element.clientWidth));
+            });
+            const scroll = scrollOwner && readScrollPlacement(target, scrollOwner, () => config.id);
+            const tracking = await bridge.send({ action: 'track', viewportWidth: innerWidth, ...(scroll ? { scroll } : {}) });
+            if (stopped || version !== generation)
+                return;
+            nativeScroll = tracking?.tracked === true;
+            manager.consider(config.captureMode === 'view' ? contentRevision : ++revision, sources());
+        }
+        else {
+            await bridge.send({ action: 'visibility', visible: false });
+            setVisibility();
+        }
+    };
+    const schedule = () => {
+        if (stopped)
+            return;
+        scheduled = true;
+        if (!ready || reconciling)
+            return;
+        reconciling = true;
+        void Promise.resolve().then(async () => {
+            try {
+                while (scheduled && !stopped) {
+                    scheduled = false;
+                    await reconcile();
+                }
+            }
+            catch {
+                // Preserve the selected recovery policy without overriding a newer destination.
+                await recoverFailedProjection();
+            }
+            finally {
+                reconciling = false;
+                if (scheduled)
+                    schedule();
+            }
+        });
+    };
+    const resized = () => {
+        manager?.invalidate();
+        schedule();
+    };
+    const sizeObserver = new ResizeObserver(resized);
+    window.addEventListener('resize', resized);
+    const scrollAncestors = new Set();
+    const handledScrolls = new WeakSet();
+    const onScroll = (event) => {
+        const owner = event.composedPath()[0] ?? event.target;
+        if (stopped ||
+            destination !== 'native' ||
+            !target ||
+            handledScrolls.has(event) ||
+            (owner !== document && ![...projectionAncestors(target)].includes(owner)))
+            return;
+        handledScrolls.add(event);
+        if (nativeScroll && owner === scrollOwner) {
+            manager?.changed(owner);
+            return;
+        }
+        if (!automaticMotion) {
+            // A fresh gesture supersedes the preceding presentation's pending draw ACK.
+            // begin() retires that return image and starts another presentation on the same manager.
+            if (restoring || manager?.restoring)
+                generation++;
+            automaticMotion = true;
+            beginProjection();
+            placementPending = config.failedFallback !== 'native';
+            if (manager?.token)
+                target.removeAttribute(marker);
+            else
+                applyFailedFallback();
+        }
+        else if (config.captureMode === 'view')
+            manager?.moved();
+        else
+            manager?.changed();
+        clearTimeout(scrollTimer);
+        scrollTimer = setTimeout(() => {
+            automaticMotion = false;
+            if (stopped || destination !== 'native')
+                return;
+            manager?.end();
+            if (!manager?.restoring)
+                schedule();
+        }, 100);
+    };
+    // Listen on composed-tree ancestors themselves: non-composed scroll events inside
+    // Ionic's shadow tree never reach document, and Node.contains excludes slotted children.
+    const refreshScrollListeners = () => {
+        const next = new Set(target ? projectionAncestors(target) : []);
+        const changed = next.size !== scrollAncestors.size || [...next].some((element) => !scrollAncestors.has(element));
+        for (const element of scrollAncestors)
+            if (!next.has(element)) {
+                element.removeEventListener('scroll', onScroll);
+                element.removeEventListener('slotchange', slotChanged);
+                scrollAncestors.delete(element);
+            }
+        for (const element of next)
+            if (!scrollAncestors.has(element)) {
+                element.addEventListener('scroll', onScroll, { passive: true });
+                element.addEventListener('slotchange', slotChanged);
+                scrollAncestors.add(element);
+            }
+        if (changed) {
+            nativeScroll = false;
+            scrollOwner = undefined;
+            manager?.invalidate();
+            schedule();
+        }
+    };
+    const slotChanged = () => {
+        refreshScrollListeners();
+        schedule();
+    };
+    document.addEventListener('scroll', onScroll, true);
+    const observer = new MutationObserver((records) => {
+        refreshScrollListeners();
+        if (findTarget() !== target)
+            schedule();
+        // Moving the same host into or out of an overlay changes coverage, not registration.
+        else if (target && records.some((record) => record.type === 'childList'))
+            applyDestination(effectiveDestination());
+    });
+    observer.observe(document.documentElement, { childList: true, attributes: true, subtree: true });
+    const applyDestination = (next, force = false) => {
+        if (stopped || (!force && next === destination))
+            return;
+        automaticMotion = false;
+        clearTimeout(scrollTimer);
+        destination = next;
+        generation++;
+        const version = generation;
+        if (destination === 'none') {
+            // Retire native visibility before releasing images; release must not resurrect hidden views.
+            void bridge
+                .send({ action: 'visibility', visible: false })
+                .then(() => {
+                if (destination !== 'none' || version !== generation || stopped)
+                    return;
+                manager?.invalidate();
+                setVisibility();
+            })
+                .catch(() => {
+                if (destination !== 'none' || version !== generation || stopped)
+                    return;
+                manager?.invalidate();
+                setVisibility();
+            });
+        }
+        else if (destination === 'web') {
+            beginProjection();
+            if (!manager?.token)
+                void bridge.send({ action: 'visibility', visible: false }).catch(() => { });
+            setVisibility();
+        }
+        else if (destination === 'native') {
+            manager?.end();
+            if (!manager?.restoring)
+                schedule();
+        }
+    };
+    // Let a renderer claim a native child window during the same Ionic event dispatch.
+    const stopOverlays = overlays.subscribe(() => queueMicrotask(() => applyDestination(effectiveDestination())));
+    let events;
+    const destroy = async () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearPlacement();
+        generation++;
+        stopOverlays();
+        observer.disconnect();
+        sizeObserver.disconnect();
+        window.removeEventListener('resize', resized);
+        document.removeEventListener('scroll', onScroll, true);
+        for (const element of scrollAncestors) {
+            element.removeEventListener('scroll', onScroll);
+            element.removeEventListener('slotchange', slotChanged);
+        }
+        scrollAncestors.clear();
+        clearTimeout(scrollTimer);
+        target?.removeAttribute(marker);
+        style.remove();
+        await Promise.allSettled([Promise.resolve(events?.remove()), manager?.destroy()]);
+    };
+    try {
+        const initialGeneration = generation;
+        events = await bindProjectionEvents({
+            addListener: (name, listener) => plugin.addListener(name, listener),
+            update: listeners?.update,
+            projection: listeners?.projection,
+            accepts: (event) => !listeners?.match ||
+                Object.entries(listeners?.match).every(([key, value]) => typeof event === 'object' && event !== null && event[key] === value),
+        }, (next, updated) => {
+            if (stopped)
+                return;
+            if (next) {
+                if (next === 'native')
+                    placementPending = false;
+                requestedDestination = next;
+                void bridge.send({ action: 'destination', destination: next }).catch(() => { });
+                applyDestination(effectiveDestination(), true);
+            }
+            if (updated) {
+                contentRevision++;
+                manager?.changed();
+                if (destination === 'native')
+                    schedule();
+            }
+        });
+        const initial = await bridge.send({ action: 'connect' });
+        if (generation === initialGeneration && ['native', 'web', 'none'].includes(initial?.destination))
+            requestedDestination = initial.destination;
+        destination = effectiveDestination();
+        ready = true;
+        schedule();
+        return {
+            destroy,
+            show: () => {
+                placementPending = false;
+                requestedDestination = 'native';
+                applyDestination(effectiveDestination(), true);
+            },
+            hide: () => {
+                requestedDestination = destination = 'none';
+                generation++;
+                automaticMotion = false;
+                clearTimeout(scrollTimer);
+                manager?.invalidate();
+                setVisibility();
+            },
+        };
+    }
+    catch (error) {
+        await destroy();
+        throw error;
+    }
+};

package/dist/projection/events.d.ts

@@ -0,0 +1,12 @@
+import type { ListenerHandle } from '../types.js';
+export type ProjectionDestination = 'native' | 'web' | 'none';
+/** Notifications from the existing plugin proxy; public plugin methods are never intercepted. */
+export interface ProjectionEvents {
+    addListener(name: string, listener: (event: unknown) => void): Promise<ListenerHandle>;
+    update?: readonly string[];
+    projection?: Partial<Record<ProjectionDestination, readonly string[]>>;
+    /** Required when the plugin emits events for multiple independent surfaces. */
+    accepts?(event: unknown): boolean;
+}
+/** Subscribe once per event, including events that both update and change destination. */
+export declare const bindProjectionEvents: (events: ProjectionEvents, receive: (destination: ProjectionDestination | undefined, updated: boolean) => void) => Promise<ListenerHandle>;

package/dist/projection/events.js

@@ -0,0 +1,44 @@
+import { boundedListener } from '../native/bridge.js';
+/** Subscribe once per event, including events that both update and change destination. */
+export const bindProjectionEvents = async (events, receive) => {
+    const routes = new Map();
+    for (const name of events.update ?? [])
+        routes.set(name, { updated: true });
+    for (const destination of ['native', 'web', 'none']) {
+        for (const name of events.projection?.[destination] ?? []) {
+            const route = routes.get(name) ?? { updated: false };
+            if (route.destination && route.destination !== destination)
+                throw new TypeError(`Projection event "${name}" has conflicting destinations`);
+            routes.set(name, { ...route, destination });
+        }
+    }
+    let stopped = false;
+    const handles = [];
+    const remove = async () => {
+        stopped = true;
+        const results = await Promise.allSettled(handles.splice(0).map((handle) => Promise.resolve().then(() => handle.remove())));
+        const failure = results.find((result) => result.status === 'rejected');
+        if (failure?.status === 'rejected')
+            throw failure.reason;
+    };
+    // Start all registrations immediately, so one slow bridge reply does not delay other subscriptions.
+    const registrations = [...routes].map(async ([name, route]) => {
+        const handle = await boundedListener(Promise.resolve().then(() => events.addListener(name, (event) => {
+            if (!stopped && (!events.accepts || events.accepts(event)))
+                receive(route.destination, route.updated);
+        })));
+        if (stopped)
+            await handle.remove();
+        else
+            handles.push(handle);
+    });
+    try {
+        await Promise.all(registrations);
+        return { remove };
+    }
+    catch (error) {
+        // Disable callbacks immediately. Late successful registrations also remove themselves.
+        await remove().catch(() => { });
+        throw error;
+    }
+};

package/dist/projection/placement.d.ts

@@ -0,0 +1,14 @@
+/** Placement supplied synchronously before a native view returns from a Web image. */
+export interface ProjectionPlacementBinding {
+    readonly projected: boolean;
+    dispose(): void;
+}
+interface PlacementState {
+    projected: boolean;
+    owner?: object;
+    invalidate(): void;
+    measure(): Record<string, unknown>;
+}
+export declare const bindProjectionPlacement: (element: HTMLElement, measure: () => Record<string, unknown>, invalidate?: () => void) => ProjectionPlacementBinding;
+export declare const projectionPlacement: (element: HTMLElement | undefined) => PlacementState | undefined;
+export {};

package/dist/projection/placement.js

@@ -0,0 +1,18 @@
+// The injected runtime and a plugin's bundled helper share the binding.
+const placementKey = Symbol.for('webview-native-ui-engine.projection-placement');
+export const bindProjectionPlacement = (element, measure, invalidate = () => { }) => {
+    const host = element;
+    const state = { projected: false, measure, invalidate };
+    host[placementKey] = state;
+    return {
+        get projected() {
+            return host[placementKey] === state && state.projected;
+        },
+        dispose() {
+            if (host[placementKey] === state)
+                delete host[placementKey];
+            state.projected = false;
+        },
+    };
+};
+export const projectionPlacement = (element) => element?.[placementKey];

package/dist/projection/scope.d.ts

@@ -0,0 +1,6 @@
+/** A fixed Web fallback element. A replacement element requires a new scope. */
+export declare const createWebProjectionScope: (element: HTMLElement, namespace: string) => Readonly<{
+    element: HTMLElement;
+    namespace: string;
+}>;
+export type WebProjectionScope = ReturnType<typeof createWebProjectionScope>;

package/dist/projection/scope.js

@@ -0,0 +1,8 @@
+/** A fixed Web fallback element. A replacement element requires a new scope. */
+export const createWebProjectionScope = (element, namespace) => {
+    if (element.nodeType !== 1 || element.namespaceURI !== 'http://www.w3.org/1999/xhtml' || !element.ownerDocument || !('style' in element))
+        throw new TypeError('A Web projection scope requires an HTMLElement fallback');
+    if (element.matches('img, input, textarea, select, video, audio, canvas, iframe, embed, object, br, hr, area, base, link, meta, source, track, wbr'))
+        throw new TypeError('A Web projection fallback must support ::before; use its existing container element');
+    return Object.freeze({ element, namespace });
+};

package/dist/projection/styles.d.ts

@@ -0,0 +1,2 @@
+/** Image presentation only; Native/Web ownership styling stays with the renderer. */
+export declare const snapshotStyles = "\n:is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared]),\n:is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared]) *,\n:is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared])::after,\n:is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared])::part(native) { visibility: hidden !important; }\n[data-native-ui-snapshot][data-native-ui-snapshot]::before {\n all:initial!important;content:\"\"!important;display:block!important;position:absolute!important;\n visibility:visible!important;opacity:0!important;will-change:opacity!important;\n pointer-events:none!important;image-rendering:pixelated!important;\n}\n[data-native-ui-snapshot-visible] { opacity:1!important;overflow:visible!important; }\n[data-native-ui-snapshot-visible][data-native-ui-snapshot][data-native-ui-snapshot]::before { opacity:1!important; }\n";

package/dist/projection/styles.js

@@ -0,0 +1,14 @@
+/** Image presentation only; Native/Web ownership styling stays with the renderer. */
+export const snapshotStyles = `
+:is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared]),
+:is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared]) *,
+:is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared])::after,
+:is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared])::part(native) { visibility: hidden !important; }
+[data-native-ui-snapshot][data-native-ui-snapshot]::before {
+ all:initial!important;content:""!important;display:block!important;position:absolute!important;
+ visibility:visible!important;opacity:0!important;will-change:opacity!important;
+ pointer-events:none!important;image-rendering:pixelated!important;
+}
+[data-native-ui-snapshot-visible] { opacity:1!important;overflow:visible!important; }
+[data-native-ui-snapshot-visible][data-native-ui-snapshot][data-native-ui-snapshot]::before { opacity:1!important; }
+`;