@webview-native-ui/engine 0.0.3 → 0.0.5

package/README.md

@@ -44,6 +44,7 @@ The current API is pre-1.0. Use matching, pinned Engine versions across npm and
 
 ## 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.
 

package/dist/dom/visibility.js

@@ -13,6 +13,7 @@ export const getUnprojectedVisibility = (element) => {
         for (const attribute of Array.from(node.attributes)) {
             if (attribute.name === 'data-native-ui-snapshot-source' ||
                 attribute.name === 'data-native-ui-snapshot-prepared' ||
+                attribute.name === 'data-native-ui-snapshot-content' ||
                 attribute.name.startsWith('data-native-ui-session-'))
                 markers.push({ node, name: attribute.name, value: attribute.value });
         }

package/dist/native/session.d.ts

@@ -1,5 +1,5 @@
 import { type ProjectionDestination } from '../projection/events.js';
-import type { ScrollPlacement, ListenerHandle, WebProjectionRequest } from '../types.js';
+import type { Frame, ScrollPlacement, ListenerHandle, WebProjectionRequest } from '../types.js';
 /** Serialized by the native library. One registration owns one fixed fallback container. */
 export interface NativeSessionConfiguration {
     id: string;
@@ -12,6 +12,8 @@ export interface NativeSessionConfiguration {
     captureMode?: 'composited' | 'view';
     /** Native registration accepts a final placement in its reveal request. */
     placementHandoff?: boolean;
+    /** Android can cover prepared pixels before a Web scroll event arrives. */
+    nativeDragHandoff?: boolean;
     receiveListeners?: {
         update?: string[];
         projection?: Partial<Record<ProjectionDestination, string[]>>;
@@ -29,6 +31,13 @@ export interface NativeSessionBridge {
         action: 'track';
         viewportWidth: number;
         scroll?: ScrollPlacement;
+        gesture?: {
+            viewport: Frame;
+            offsetX: number;
+            offsetY: number;
+            rangeX: number;
+            rangeY: number;
+        };
     } | {
         action: 'connect';
     } | {
@@ -37,6 +46,7 @@ export interface NativeSessionBridge {
     }): Promise<any>;
     listen(listener: (event: {
         active: boolean;
+        precovered?: string;
     }) => void): Promise<ListenerHandle>;
 }
 /** Native startup calls this; application code does not initialize or wrap the plugin. */

package/dist/native/session.js

@@ -21,6 +21,7 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
     const overlays = getOverlayCoordinator(document);
     const effectiveDestination = () => requestedDestination === 'native' && target && overlays.isCovered(target) ? 'web' : requestedDestination;
     let automaticMotion = false;
+    let nativeDragging = false;
     let placementPending = false;
     let nativeScroll = false;
     let scrollOwner;
@@ -51,17 +52,26 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
         }
     };
     const bridge = {
-        listen: (listener) => nativeBridge.listen(listener),
+        listen: (listener) => nativeBridge.listen((event) => {
+            listener(event);
+            if (!event.active && nativeDragging) {
+                nativeDragging = false;
+                endAutomaticMotionLater();
+            }
+            if (event.precovered)
+                adoptNativeCover(event.precovered);
+        }),
         send: (request) => {
             if (!config.placementHandoff)
                 return nativeBridge.send(request);
             const binding = projectionPlacement(target);
             if (request.action === 'cover') {
+                const alreadyCovered = coveredToken === request.token && binding?.owner === placementOwner && binding.projected;
                 const epoch = ++placementEpoch;
                 coveredToken = request.token;
                 if (binding) {
                     binding.owner = placementOwner;
-                    binding.projected = false;
+                    binding.projected = !!alreadyCovered;
                 }
                 return nativeBridge
                     .send(request)
@@ -97,7 +107,18 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
                     : request;
                 return nativeBridge
                     .send(payload)
-                    .then((result) => {
+                    .then(async (result) => {
+                    // A native drag can race retirement before its notification reaches JS.
+                    // Keep the prepared underlay until native has applied a fresh return placement.
+                    if (request.action === 'release' && result?.requiresPlacement) {
+                        if (binding && (!binding.owner || binding.owner === placementOwner)) {
+                            result = await nativeBridge.send({ ...request, placement: binding.measure() });
+                        }
+                        else {
+                            await nativeBridge.send({ action: 'visibility', visible: false });
+                            result = await nativeBridge.send(request);
+                        }
+                    }
                     if (epoch === placementEpoch &&
                         (request.action === 'resume' || releasing || request.action === 'reset' || request.action === 'visibility'))
                         clearPlacement();
@@ -247,6 +268,7 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
                 const created = await createWebProjection(createWebProjectionScope(target, config.id), bridge, {
                     wake,
                     captureDelayMs: config.captureDelayMs,
+                    retainPreparedUntilRelease: config.nativeDragHandoff,
                     blocked: () => destination !== 'native' || automaticMotion || (placementPending && !manager?.token),
                     revision: () => revision,
                     captureRevision: config.captureMode === 'view' ? () => contentRevision : undefined,
@@ -282,7 +304,23 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
                     (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 } : {}) });
+            // Gesture gating needs a hit region, not native compositor scroll eligibility.
+            // Rounded/clipped Ionic hosts can reject readScrollPlacement while still scrolling in Web.
+            const gesture = config.nativeDragHandoff && config.captureMode === 'view' && scrollOwner
+                ? {
+                    viewport: scrollOwner.getBoundingClientRect(),
+                    offsetX: scrollOwner.scrollLeft,
+                    offsetY: scrollOwner.scrollTop,
+                    rangeX: Math.max(0, scrollOwner.scrollWidth - scrollOwner.clientWidth),
+                    rangeY: Math.max(0, scrollOwner.scrollHeight - scrollOwner.clientHeight),
+                }
+                : undefined;
+            const tracking = await bridge.send({
+                action: 'track',
+                viewportWidth: innerWidth,
+                ...(scroll ? { scroll } : {}),
+                ...(gesture ? { gesture } : {}),
+            });
             if (stopped || version !== generation)
                 return;
             nativeScroll = tracking?.tracked === true;
@@ -356,8 +394,13 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
             manager?.moved();
         else
             manager?.changed();
+        endAutomaticMotionLater();
+    };
+    function endAutomaticMotionLater() {
         clearTimeout(scrollTimer);
         scrollTimer = setTimeout(() => {
+            if (nativeDragging)
+                return;
             automaticMotion = false;
             if (stopped || destination !== 'native')
                 return;
@@ -365,7 +408,31 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
             if (!manager?.restoring)
                 schedule();
         }, 100);
-    };
+    }
+    function adoptNativeCover(token) {
+        if (stopped || destination !== 'native' || !target?.isConnected || !manager)
+            return;
+        nativeDragging = true;
+        // A scroll handler may have adopted the same native cover before its notification arrives.
+        if (manager.token)
+            return;
+        if (restoring || manager.restoring)
+            generation++;
+        coveredToken = token;
+        const binding = projectionPlacement(target);
+        if (binding) {
+            binding.owner = placementOwner;
+            binding.projected = true;
+        }
+        automaticMotion = true;
+        beginProjection();
+        if (!manager.token) {
+            automaticMotion = false;
+            void recoverFailedProjection();
+            return;
+        }
+        endAutomaticMotionLater();
+    }
     // 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 = () => {
@@ -408,6 +475,7 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
         if (stopped || (!force && next === destination))
             return;
         automaticMotion = false;
+        nativeDragging = false;
         clearTimeout(scrollTimer);
         destination = next;
         generation++;
@@ -419,13 +487,13 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
                 .then(() => {
                 if (destination !== 'none' || version !== generation || stopped)
                     return;
-                manager?.invalidate();
+                manager?.invalidate(true);
                 setVisibility();
             })
                 .catch(() => {
                 if (destination !== 'none' || version !== generation || stopped)
                     return;
-                manager?.invalidate();
+                manager?.invalidate(true);
                 setVisibility();
             });
         }
@@ -507,8 +575,9 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
                 requestedDestination = destination = 'none';
                 generation++;
                 automaticMotion = false;
+                nativeDragging = false;
                 clearTimeout(scrollTimer);
-                manager?.invalidate();
+                manager?.invalidate(true);
                 setVisibility();
             },
         };

package/dist/projection/scope.js

@@ -3,6 +3,6 @@ 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');
+        throw new TypeError('A Web projection fallback must be a container element; use the existing fallback container');
     return Object.freeze({ element, namespace });
 };

package/dist/projection/styles.d.ts

@@ -1,2 +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";
+export declare const snapshotStyles = "\n@layer native-ui-projection {\n:is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content]), :is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content]) *, :is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content])::part(native) { visibility: hidden !important; }\n:is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content])::before, :is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content])::after,\n:is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content]) *::before, :is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content]) *::after {\n  visibility: hidden !important;\n}\n}\n[data-native-ui-snapshot-visible] { opacity:1!important;overflow:visible!important; }\n[data-native-ui-snapshot-visible][data-native-ui-snapshot-positioned] { position:relative!important; }\n";
+export declare const snapshotShadowStyles = "\n@layer native-ui-projection {\n:host([data-native-ui-snapshot-content]),\n:host([data-native-ui-snapshot-content])::before,\n:host([data-native-ui-snapshot-content])::after,\n:host([data-native-ui-snapshot-content]) *,\n:host([data-native-ui-snapshot-content]) *::before,\n:host([data-native-ui-snapshot-content]) *::after {\n  visibility: hidden !important;\n}\n}\n";

package/dist/projection/styles.js

@@ -1,14 +1,25 @@
 /** Image presentation only; Native/Web ownership styling stays with the renderer. */
+const hidden = ':is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content])';
 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;
+@layer native-ui-projection {
+${hidden}, ${hidden} *, ${hidden}::part(native) { visibility: hidden !important; }
+${hidden}::before, ${hidden}::after,
+${hidden} *::before, ${hidden} *::after {
+  visibility: hidden !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; }
+[data-native-ui-snapshot-visible][data-native-ui-snapshot-positioned] { position:relative!important; }
+`;
+export const snapshotShadowStyles = `
+@layer native-ui-projection {
+:host([data-native-ui-snapshot-content]),
+:host([data-native-ui-snapshot-content])::before,
+:host([data-native-ui-snapshot-content])::after,
+:host([data-native-ui-snapshot-content]) *,
+:host([data-native-ui-snapshot-content]) *::before,
+:host([data-native-ui-snapshot-content]) *::after {
+  visibility: hidden !important;
+}
+}
 `;

package/dist/projection/web.d.ts

@@ -6,6 +6,8 @@ export interface WebProjectionOptions {
     events?: ProjectionEvents;
     /** Debounce before preparing replacement pixels, in milliseconds. Defaults to 50; never delays handoff. */
     captureDelayMs?: number;
+    /** Preserve an idle underlay while native disarms a possible early drag cover. */
+    retainPreparedUntilRelease?: boolean;
     wake(): void;
     blocked(): boolean;
     revision?(): number;
@@ -35,7 +37,7 @@ declare const createProjectionEngine: (scope: WebProjectionScope, transport: Web
     retireRestoration: () => void;
     end: () => void;
     updated: (token: string | undefined, restoredIDs?: string[], revision?: number) => void;
-    invalidate: () => void;
+    invalidate: (nativeHidden?: boolean) => void;
     destroy(): Promise<void>;
 }>;
 type Engine = Awaited<ReturnType<typeof createProjectionEngine>>;