@webview-native-ui/engine 0.0.6 → 0.0.7

package/README.md

@@ -29,24 +29,31 @@ WebView Native UI Engine makes that work reusable. It lets applications combine
 
 Use the live native view where it belongs, and a prepared visual projection in the DOM when the Web layer needs to own presentation. Restore the interactive native view when it can take over again. An existing DOM container gives the Web projection its place in the application's layout and layer structure.
 
-The Engine coordinates this handoff; the integrating renderer still creates and positions its views. A projected image preserves appearance, not live interaction or video. Capture availability and layout support determine when a projection can be used, with an explicit fallback when it cannot. See [projection behavior](docs/projection.md) for the detailed contract and limits.
+The Engine coordinates this handoff; the integrating renderer still creates and positions its views. A projected image preserves appearance, not live interaction or video. Capture availability and layout support determine when a projection can be used, with an explicit fallback when it cannot. See [concepts and limits](docs/concepts.md) for the detailed contract and limits.
 
-## Integration
+## Choose your starting point
 
-Applications gain these capabilities through plugins that integrate the Engine. Capacitor and Cordova plugin authors add it as a library dependency while retaining their existing native controls and public APIs. The same Engine supports iOS and Android. Ionic and Angular are not required; Ionic overlay coordination is optional.
+Applications gain these capabilities through plugins that integrate the Engine.
+Plugin authors retain their existing native controls and public APIs; the Engine
+supplies the coordination between native and Web presentation. It supports iOS
+and Android with Capacitor or Cordova. Ionic and Angular are not required.
 
-- [Capacitor plugin guide](docs/capacitor-plugin.md) — install dependencies and add registration, events and teardown to your existing plugin.
-- [Cordova plugin guide](docs/cordova-plugin.md) — integrate the same Engine with Cordova's lifecycle and resource handler, without a Capacitor dependency.
+| Start here                                                     | Purpose                                                                              |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| [Documentation](docs/README.md)                                | Reading order: basic initialization, optional behavior, advanced APIs and reference. |
+| [Concepts and limits](docs/concepts.md)                        | Decide whether projection fits your component.                                       |
+| [Basic initialization](docs/getting-started/initialization.md) | Minimum setup and required inputs, before framework-specific integration.            |
 
-Native registration starts the Web runtime; applications do not need a separate Engine initializer for the base integration. Keep your plugin's normal API and notifications.
+Native registration starts the Web runtime; the base integration needs no separate
+application-side Engine initializer. The API is pre-1.0: pin matching Engine
+versions across npm and native dependencies. Android placement requires API 23+,
+with composited snapshots available from API 26+.
 
-The current API is pre-1.0. Use matching, pinned Engine versions across npm and native dependencies. Android placement requires API 23+, with composited snapshots available from API 26+.
+## Reference and contributing
 
-## Further reading
-
-- [Projection container support](docs/projection-containers.md) — supported HTML and Ionic destinations, sizing conditions and wrapper examples.
-- [Projection behavior and advanced integration](docs/projection.md) — DOM requirements, lifecycle, fallback policies, optional Ionic support and lower-level APIs.
-- [Development and releases](docs/maintenance.md) — repository structure, validation and publishing.
+The [documentation index](docs/README.md) links to configuration, advanced APIs,
+container support and platform contracts. For repository development and publishing,
+see [development and releases](docs/maintenance.md).
 
 ## License
 

package/dist/index.d.ts

@@ -8,3 +8,6 @@ export type { ProjectionEvents, ProjectionDestination } from './projection/event
 export { getOverlayCoordinator, usesOverlayBackdrop, type OverlayChange, type OverlayOptions } from './dom/overlays.js';
 export { getUnprojectedVisibility } from './dom/visibility.js';
 export { bindProjectionPlacement, type ProjectionPlacementBinding } from './projection/placement.js';
+export { createWebProjectionSurfaces } from './projection/surfaces.js';
+export * from './projection/surface.js';
+export { createNativeUpdateQueue, type NativeUpdateSender } from './native/updates.js';

package/dist/index.js

@@ -7,3 +7,6 @@ export * from './dom/scroll-bindings.js';
 export { getOverlayCoordinator, usesOverlayBackdrop } from './dom/overlays.js';
 export { getUnprojectedVisibility } from './dom/visibility.js';
 export { bindProjectionPlacement } from './projection/placement.js';
+export { createWebProjectionSurfaces } from './projection/surfaces.js';
+export * from './projection/surface.js';
+export { createNativeUpdateQueue } from './native/updates.js';

package/dist/native/session.d.ts

@@ -1,3 +1,4 @@
+import { type NativeValueBinding } from './values.js';
 import { type ProjectionDestination } from '../projection/events.js';
 import type { Frame, ScrollPlacement, ListenerHandle, WebProjectionRequest } from '../types.js';
 /** Serialized by the native library. One registration owns one fixed fallback container. */
@@ -7,6 +8,8 @@ export interface NativeSessionConfiguration {
     runtime?: 'capacitor' | 'cordova';
     projectionSelector: string;
     captureDelayMs?: number;
+    /** Value reflection is opt-in; native supplies the current values. */
+    values?: Record<string, NativeValueBinding>;
     /** Recovery while native is requested. Explicit web/none destinations take precedence. */
     failedFallback?: 'web' | 'native';
     captureMode?: 'composited' | 'view';
@@ -40,6 +43,8 @@ export interface NativeSessionBridge {
         };
     } | {
         action: 'connect';
+    } | {
+        action: 'values';
     } | {
         action: 'destination';
         destination: ProjectionDestination;

package/dist/native/session.js

@@ -1,3 +1,4 @@
+import { applyNativeValues } from './values.js';
 import { projectionPlacement } from '../projection/placement.js';
 import { getOverlayCoordinator } from '../dom/overlays.js';
 import { readScrollPlacement } from '../dom/scroll-placement.js';
@@ -39,6 +40,46 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
         }
     };
     let target;
+    let valueRequest = 0;
+    let cancelValueWait;
+    const retireValueRead = () => {
+        valueRequest++;
+        cancelValueWait?.();
+        cancelValueWait = undefined;
+    };
+    const refreshValues = async () => {
+        if (!config.values || !target || stopped)
+            return;
+        const element = target;
+        retireValueRead();
+        const request = valueRequest;
+        const current = () => !stopped && request === valueRequest && target === element && findTarget() === element && element.isConnected;
+        // Defining a custom element installs its setters. Earlier assignment would shadow them.
+        if (element.localName.includes('-') &&
+            !element.matches(':defined') &&
+            Object.values(config.values).some((binding) => binding.property)) {
+            await Promise.race([
+                element.ownerDocument.defaultView.customElements.whenDefined(element.localName),
+                new Promise((resolve) => {
+                    cancelValueWait = resolve;
+                }),
+            ]);
+            if (!current())
+                return;
+            cancelValueWait = undefined;
+        }
+        const result = await nativeBridge.send({ action: 'values' }).catch(() => undefined);
+        if (!current())
+            return;
+        if (result?.values && typeof result.values === 'object' && !Array.isArray(result.values)) {
+            try {
+                applyNativeValues(element, result.values, config.values);
+            }
+            catch (error) {
+                console.warn('[Native UI Engine] Cannot reflect values', error);
+            }
+        }
+    };
     const placementOwner = {};
     let coveredToken;
     let placementEpoch = 0;
@@ -138,7 +179,7 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
     let revision = 0;
     let contentRevision = 0;
     let generation = 0;
-    let restoring = false;
+    let restoring;
     let initializing = false;
     let scheduled = false;
     let reconciling = false;
@@ -151,6 +192,9 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
         return matches.length === 1 && matches[0] instanceof HTMLElement ? matches[0] : undefined;
     };
     const setVisibility = () => {
+        const intent = effectiveDestination();
+        if (target && target.getAttribute('data-native-ui-destination') !== intent)
+            target.setAttribute('data-native-ui-destination', intent);
         if (!target)
             return;
         if (destination === 'web' || (destination === 'native' && placementPending))
@@ -206,16 +250,16 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
             target?.removeAttribute(marker);
             return;
         }
-        if (restoring || !manager?.restoring || destination !== 'native')
+        if (!manager?.restoring || restoring === manager || destination !== 'native')
             return;
-        restoring = true;
+        restoring = manager;
         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)
+            if (stopped || version !== generation || current !== manager || findTarget() !== target)
                 return;
             placementPending = false;
             current.updated(undefined, [sourceID], ++revision);
@@ -229,33 +273,55 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
             void recoverFailedProjection();
         })
             .finally(() => {
-            restoring = false;
+            if (restoring === current)
+                restoring = undefined;
             wake();
         });
     };
     const reconcile = async () => {
-        if (stopped || initializing || automaticMotion)
-            return;
-        if (manager?.restoring) {
-            wake();
+        if (stopped || initializing)
             return;
-        }
         const found = findTarget();
         if (found !== target) {
             generation++;
+            automaticMotion = false;
+            nativeDragging = false;
+            clearTimeout(scrollTimer);
             clearPlacement();
             target?.removeAttribute(marker);
-            await manager?.destroy();
+            target?.removeAttribute('data-native-ui-destination');
+            retireValueRead();
+            // A page/DOM replacement retires its old surface even during a drag or draw ACK.
+            // Hide before releasing its image so retirement cannot reveal the departed view.
+            const previous = manager;
+            const previousTarget = target;
             manager = undefined;
+            target = undefined;
+            sizeObserver.disconnect();
+            refreshScrollListeners();
+            try {
+                if (previousTarget)
+                    await bridge.send({ action: 'visibility', visible: false });
+            }
+            finally {
+                await previous?.destroy();
+            }
             if (stopped)
                 return;
-            target = found;
+            target = findTarget();
             placementPending = false;
-            sizeObserver.disconnect();
-            if (target)
+            if (target) {
                 sizeObserver.observe(target);
+                void refreshValues();
+            }
         }
         refreshScrollListeners();
+        if (automaticMotion)
+            return;
+        if (manager?.restoring) {
+            wake();
+            return;
+        }
         destination = effectiveDestination();
         if (!target) {
             await bridge.send({ action: 'visibility', visible: false });
@@ -516,6 +582,7 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
         if (stopped)
             return;
         stopped = true;
+        retireValueRead();
         clearPlacement();
         generation++;
         stopOverlays();
@@ -530,6 +597,7 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
         scrollAncestors.clear();
         clearTimeout(scrollTimer);
         target?.removeAttribute(marker);
+        target?.removeAttribute('data-native-ui-destination');
         style.remove();
         await Promise.allSettled([Promise.resolve(events?.remove()), manager?.destroy()]);
     };
@@ -552,6 +620,7 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
                 applyDestination(effectiveDestination(), true);
             }
             if (updated) {
+                void refreshValues();
                 contentRevision++;
                 manager?.changed();
                 if (destination === 'native')

package/dist/native/updates.d.ts

@@ -0,0 +1,16 @@
+/** Send only replaceable state from an update pass, never user actions. */
+export type NativeUpdateSender = <T>(request: () => Promise<T>, validate?: (result: T) => void) => Promise<T | undefined>;
+/** Coalesce current-state reads and serialize them across asynchronous native acknowledgements. */
+export declare const createNativeUpdateQueue: (window: Pick<Window, "requestAnimationFrame" | "cancelAnimationFrame">, options: {
+    update(send: NativeUpdateSender): Promise<void>;
+    failed(error: unknown): void | Promise<void>;
+    retry(): void;
+    reconnect?: boolean;
+}) => {
+    request: () => void;
+    readonly dirty: boolean;
+    readonly running: boolean;
+    readonly waiting: boolean;
+    reconnected(): void;
+    destroy(): void;
+};

package/dist/native/updates.js

@@ -0,0 +1,108 @@
+/** Coalesce current-state reads and serialize them across asynchronous native acknowledgements. */
+export const createNativeUpdateQueue = (window, options) => {
+    let frame = 0;
+    let dirty = false;
+    let running = false;
+    let stopped = false;
+    let retrying = false;
+    let waiting = false;
+    let reconciled = false;
+    let passFailed = false;
+    const request = () => {
+        if (stopped)
+            return;
+        dirty = true;
+        if (!running && !waiting && !frame)
+            frame = window.requestAnimationFrame(() => void run());
+    };
+    const waitForConnection = (error) => {
+        if (!options.reconnect || reconciled)
+            throw error;
+        waiting = true;
+        dirty = false;
+    };
+    const send = async (operation, validate) => {
+        if (stopped || waiting || passFailed)
+            return;
+        let result;
+        try {
+            result = await operation();
+        }
+        catch (error) {
+            if (stopped)
+                return;
+            passFailed = true;
+            if (retrying)
+                waitForConnection(error);
+            else {
+                retrying = true;
+                options.retry();
+                request();
+            }
+            return;
+        }
+        if (stopped)
+            return;
+        try {
+            validate?.(result);
+        }
+        catch (error) {
+            passFailed = true;
+            waitForConnection(error);
+            return;
+        }
+        return result;
+    };
+    const run = async () => {
+        frame = 0;
+        if (stopped || waiting)
+            return;
+        dirty = false;
+        running = true;
+        passFailed = false;
+        try {
+            await options.update(send);
+            if (!passFailed)
+                retrying = waiting = reconciled = false;
+        }
+        catch (error) {
+            if (stopped)
+                return;
+            // Retire the queue before reporting terminal failure; no late update can restart it.
+            stopped = true;
+            await options.failed(error);
+        }
+        finally {
+            running = false;
+            if (dirty)
+                request();
+        }
+    };
+    return {
+        request,
+        get dirty() {
+            return dirty;
+        },
+        get running() {
+            return running;
+        },
+        get waiting() {
+            return waiting;
+        },
+        reconnected() {
+            if (stopped)
+                return;
+            if (waiting) {
+                reconciled = true;
+                retrying = waiting = false;
+            }
+            request();
+        },
+        destroy() {
+            stopped = true;
+            dirty = false;
+            window.cancelAnimationFrame(frame);
+            frame = 0;
+        },
+    };
+};

package/dist/native/values.d.ts

@@ -0,0 +1,5 @@
+/** Reflect native state without inventing component-specific input events. */
+export interface NativeValueBinding {
+    property?: string;
+}
+export declare const applyNativeValues: (target: HTMLElement, values: Record<string, unknown>, bindings: Record<string, NativeValueBinding>) => void;

package/dist/native/values.js

@@ -0,0 +1,27 @@
+export const applyNativeValues = (target, values, bindings) => {
+    for (const [key, value] of Object.entries(values)) {
+        if (!/^[a-z][a-z0-9-]*$/.test(key))
+            throw new TypeError('Native value keys must be lowercase attribute names');
+        const binding = Object.hasOwn(bindings, key) ? bindings[key] : undefined;
+        const property = binding?.property;
+        if (property &&
+            (!/^[a-zA-Z][\w]*$/.test(property) ||
+                /^on/i.test(property) ||
+                ['innerHTML', 'outerHTML', 'textContent', 'innerText', 'style', 'constructor', 'prototype'].includes(property)))
+            throw new TypeError('Native value binding requires a data property');
+        const serialized = JSON.stringify(value);
+        if (serialized === undefined)
+            throw new TypeError('Native values must be JSON values');
+        if (property) {
+            const element = target;
+            if (JSON.stringify(element[property]) !== serialized)
+                element[property] = value;
+        }
+        else {
+            const attribute = `data-native-ui-value-${key}`;
+            const text = typeof value === 'string' ? value : serialized;
+            if (target.getAttribute(attribute) !== text)
+                target.setAttribute(attribute, text);
+        }
+    }
+};

package/dist/projection/surface.d.ts

@@ -0,0 +1,35 @@
+import { type WebProjectionOptions } from './web.js';
+import type { WebProjectionSource, WebProjectionTransport } from '../types.js';
+export interface WebProjectionSurfaceOptions extends WebProjectionOptions {
+    namespace: string;
+    target(source: WebProjectionSource): HTMLElement | undefined;
+    /** Only renderer-owned fallback hosts may move into another overlay layer. */
+    canRelocate?(target: HTMLElement): boolean;
+}
+/** A renderer supplies placement policy; the Engine owns the complete image handoff. */
+export declare const createWebProjectionSurface: (transport: WebProjectionTransport, options: WebProjectionSurfaceOptions) => 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: WebProjectionSource[]): void;
+    begin(layer?: HTMLElement): void;
+    updated(token: string | undefined, ids?: string[], revision?: number): void;
+    invalidate(nativeHidden?: boolean): void;
+    destroy(): Promise<void>;
+}>;
+export type WebProjectionSurface = Awaited<ReturnType<typeof createWebProjectionSurface>>;

package/dist/projection/surface.js

@@ -0,0 +1,81 @@
+import { createWebProjectionBatch } from './web.js';
+import { createWebProjectionScope } from './scope.js';
+/** A renderer supplies placement policy; the Engine owns the complete image handoff. */
+export const createWebProjectionSurface = async (transport, options) => {
+    const scopes = new WeakMap();
+    const moved = new Map();
+    const restorePlacement = () => {
+        for (const [element, saved] of [...moved].reverse()) {
+            if (element.parentNode === saved.layer && saved.parent.isConnected)
+                saved.parent.insertBefore(element, saved.next?.parentNode === saved.parent ? saved.next : null);
+        }
+        moved.clear();
+    };
+    const projection = await createWebProjectionBatch(transport, {
+        ...options,
+        wake: () => {
+            if (!projection.token && !projection.restoring)
+                restorePlacement();
+            options.wake();
+        },
+    });
+    let latest = [];
+    const { consider, begin, updated, invalidate, destroy } = projection;
+    return Object.assign(projection, {
+        consider(revision, sources) {
+            latest = sources;
+            consider(revision, sources.flatMap((source) => {
+                const target = options.target(source);
+                if (!target?.isConnected || target.ownerDocument !== source.element.ownerDocument)
+                    return [];
+                let scope = scopes.get(target);
+                if (!scope) {
+                    scope = createWebProjectionScope(target, options.namespace);
+                    scopes.set(target, scope);
+                }
+                return [{ ...source, scope }];
+            }));
+        },
+        begin(layer) {
+            if (layer && !layer.isConnected)
+                return;
+            if (layer && !projection.token) {
+                for (const source of latest) {
+                    if (!projection.preparedOwners.includes(source.element))
+                        continue;
+                    const target = options.target(source);
+                    if (!target?.isConnected ||
+                        !target.parentNode ||
+                        target.ownerDocument !== layer.ownerDocument ||
+                        layer.contains(target) ||
+                        target.contains(layer) ||
+                        !options.canRelocate?.(target))
+                        continue;
+                    if (!moved.has(target))
+                        moved.set(target, { parent: target.parentNode, next: target.nextSibling, layer });
+                    layer.append(target);
+                }
+            }
+            begin();
+            if (!projection.token)
+                restorePlacement();
+        },
+        updated(token, ids, revision) {
+            updated(token, ids, revision);
+            if (!projection.restoring && !projection.token)
+                restorePlacement();
+        },
+        invalidate(nativeHidden) {
+            invalidate(nativeHidden);
+            restorePlacement();
+        },
+        async destroy() {
+            try {
+                await destroy();
+            }
+            finally {
+                restorePlacement();
+            }
+        },
+    });
+};

package/dist/projection/surfaces.d.ts

@@ -0,0 +1,20 @@
+import type { WebProjectionSurface } from './surface.js';
+/** Owns asynchronous projection creation and disposal for DOM-backed surfaces. */
+export declare const createWebProjectionSurfaces: <Owner extends Node, Surface extends WebProjectionSurface>(options?: {
+    ignoreTarget?(element: Element): boolean;
+}) => {
+    get: (owner: Owner) => Surface | undefined;
+    keys: () => MapIterator<Owner>;
+    values: () => Surface[];
+    changed: (owner?: EventTarget) => void;
+    invalidate: () => void;
+    followMotion: (moving: ReadonlyMap<HTMLElement, unknown>, target?: (source: HTMLElement) => HTMLElement) => void;
+    end: () => void;
+    consider: (revision: number, sources: import("../types.js").WebProjectionSource[]) => void;
+    updated: (token: string | undefined, restoredIDs?: string[] | undefined, revision?: number | undefined) => void;
+    readonly restoring: boolean;
+    readonly handoffPending: boolean;
+    ensure(owner: Owner, create: () => Promise<Surface>): Promise<Surface | undefined>;
+    delete: (owner: Owner) => Promise<void>;
+    destroy(): Promise<void>;
+};