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

package/dist/projection/web.d.ts

@@ -15,7 +15,7 @@ export interface WebProjectionOptions {
     captureRevision?(): number;
     /** Select this surface's sources, e.g. the underlying page or the active overlay. */
     eligible?(source: Candidate): boolean;
-    /** Reject a cached image when its owning surface has changed. */
+    /** Validate the captured source set, including composite sources, against its owning surface. */
     current?(sources: HTMLElement[]): boolean;
     /** Temporary movement handoff: rebase return pixels to the current display DOM. */
     transient?: boolean;

package/dist/projection/web.js

@@ -23,6 +23,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
     const doc = scope.element.ownerDocument;
     const projectionRequest = getProjectionPause(doc);
     let locallyRequested = false;
+    const imageRequested = () => locallyRequested || projectionRequest.isPaused();
     const win = doc.defaultView;
     // Native tokens are local to a transport; never use them as global CSS identities.
     const imageIdentity = Array.from(win.crypto.getRandomValues(new Uint32Array(4)), (value) => value.toString(16)).join('-');
@@ -41,9 +42,16 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
     const call = transport.send.bind(transport);
     const imageMarker = 'data-native-ui-snapshot';
     const sourcesChangedEvent = `${scope.namespace}:sources-change`;
-    const owners = new Set(), visibleOwners = new Set(), preparedOwners = new Set();
+    const preparedOwners = new Set();
     const scopeIDs = new WeakMap();
     let scopeSerial = 0;
+    const sourceIDs = new WeakMap();
+    let sourceSerial = 0;
+    const sourceIdentity = (source) => {
+        if (!sourceIDs.has(source))
+            sourceIDs.set(source, ++sourceSerial);
+        return sourceIDs.get(source);
+    };
     const signature = (candidates) => JSON.stringify(candidates.map((candidate) => {
         if (!scopeIDs.has(candidate.scope))
             scopeIDs.set(candidate.scope, ++scopeSerial);
@@ -51,7 +59,11 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
         const relative = origin
             ? { ...candidate, control: { ...candidate.control, x: candidate.control.x - origin.x, y: candidate.control.y - origin.y } }
             : candidate;
-        return [scopeIDs.get(candidate.scope), layout(relative, !!callbacks.opaqueUnderlay)];
+        return [
+            scopeIDs.get(candidate.scope),
+            layout(relative, !!callbacks.opaqueUnderlay),
+            (candidate.sources ?? [candidate.element]).map(sourceIdentity),
+        ];
     }));
     const sheets = new Map();
     const rootFor = (element) => {
@@ -104,16 +116,15 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
     };
     const viewport = () => `${win.innerWidth}:${win.innerHeight}:${win.devicePixelRatio}`;
     let handoffPending = false;
-    let presented = false;
     let paintFrame = 0;
     let presentation = 0;
     let cached;
     let retiring;
-    let active;
+    let handoff;
+    const restoring = () => handoff?.phase === 'restoring';
+    const imageVisible = () => !!handoff && (!!callbacks.opaqueUnderlay || handoff.phase === 'image' || (handoff.phase === 'restoring' && handoff.visible));
     let touching = false;
-    let ending = false;
     let restoreTimeout = 0;
-    let restoreRevision = 0;
     let generation = 0;
     let timer = 0;
     let visualRevision = 0;
@@ -125,7 +136,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
         const targets = new Set(latest?.candidates.map((candidate) => candidate.scope.element));
         for (const [target, pool] of imagePool) {
             const reusable = !stopped && target.isConnected && targets.has(target);
-            if (reusable && (active || ending || handoffPending))
+            if (reusable && (handoff || handoffPending))
                 continue;
             const limit = reusable ? 2 * Math.max(1, cached?.scopes.filter((scope) => scope.element === target).length ?? 0) : 0;
             let spare = Math.max(0, limit - pool.filter((image) => leasedImages.has(image)).length);
@@ -142,7 +153,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
         }
         const liveRoots = new Set([
             ...(latest?.candidates.map((candidate) => candidate.scope.element.getRootNode()) ?? []),
-            ...(active?.scopes.map((scope) => scope.element.getRootNode()) ?? []),
+            ...(handoff?.image.scopes.map((scope) => scope.element.getRootNode()) ?? []),
             ...(cached?.scopes.map((scope) => scope.element.getRootNode()) ?? []),
             ...[...leasedImages].map((image) => image.getRootNode()),
             ...[...shadowHosts.values()].flatMap((hosts) => [...hosts].map((host) => host.shadowRoot)),
@@ -174,7 +185,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
         preparedSources.clear();
     };
     const dispose = (item, afterPaint = false) => {
-        if (!item || item === cached || item === active)
+        if (!item || item === cached || item === handoff?.image)
             return;
         item.images.forEach((image) => {
             retireImage(image);
@@ -200,7 +211,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
             destination !== 'native' ||
             flight ||
             touching ||
-            active ||
+            handoff ||
             callbacks.blocked() ||
             !latest ||
             (cached?.revision === latest.revision && preparedVisualRevision === visualRevision))
@@ -275,7 +286,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
             if (stopped ||
                 destination !== 'native' ||
                 touching ||
-                active ||
+                handoff ||
                 callbacks.blocked() ||
                 generation !== stamp ||
                 viewport() !== size ||
@@ -286,7 +297,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
             const prepared = {
                 data: result,
                 images,
-                sources: Array.from(new Set(selected.flatMap((item) => [item.element, ...(item.sources ?? [])]))),
+                sources: Array.from(new Set(selected.flatMap((item) => item.sources ?? [item.element]))),
                 targets: partSources.map((source) => source.element),
                 scopes: partSources.map((source) => source.scope),
                 parents: partSources.map((source) => source.scope.element.parentNode),
@@ -327,7 +338,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
             preparedVisualRevision = visual;
             adopted = true;
             dispose(previous);
-            if (projectionRequest.isPaused())
+            if (imageRequested())
                 present();
         }
         catch {
@@ -349,7 +360,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
     // available while their replacement is being rendered and decoded.
     const schedule = () => {
         win.clearTimeout(timer);
-        if (!stopped && destination === 'native' && !active && !touching && !callbacks.blocked())
+        if (!stopped && destination === 'native' && !handoff && !touching && !callbacks.blocked())
             timer = win.setTimeout(() => void prepare(), captureDelayMs);
     };
     let consideredLayout;
@@ -361,7 +372,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
         // image until the presentation path has chosen whether to use it.
         if (callbacks.blocked())
             return;
-        if (!active && cached && cached.layout !== signature(select(candidates)))
+        if (!handoff && cached && cached.layout !== signature(select(candidates)))
             invalidate();
         const nextLayout = signature(candidates);
         if (consideredLayout !== nextLayout) {
@@ -379,12 +390,13 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
     const changed = (scrollOwner) => {
         // A pre-interaction state image is reusable; an image from another scroll
         // position/clip is not. Invalidate only the surface containing that owner.
-        if (!active &&
+        if (!handoff &&
             cached &&
             scrollOwner &&
-            latest?.candidates.some((candidate) => candidate.scrollElement === scrollOwner && cached.sources.includes(candidate.element)))
+            latest?.candidates.some((candidate) => candidate.scrollElement === scrollOwner &&
+                (candidate.sources ?? [candidate.element]).some((source) => cached.sources.includes(source))))
             invalidate();
-        if (active) {
+        if (handoff) {
             updateOffsets();
         }
         visualRevision++;
@@ -420,12 +432,8 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
         offsets.clear();
         paintFrame = 0;
         handoffPending = false;
-        presented = false;
         clearPrepared();
-        active?.sources.forEach((source) => {
-            owners.delete(source);
-            visibleOwners.delete(source);
-        });
+        handoff = undefined;
         rendered.forEach(clearTarget);
         rendered.clear();
         sheets.forEach((style, root) => {
@@ -435,40 +443,33 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
             }
         });
     };
-    const abandon = (expected = active, afterPaint = ending) => {
-        if (active !== expected)
+    const abandon = (expected = handoff?.image, afterPaint = restoring()) => {
+        if (handoff?.image !== expected)
             return;
-        const previous = new Set([active, cached]);
+        const previous = new Set([handoff?.image, cached]);
         detach();
-        active = undefined;
         cached = undefined;
-        ending = false;
         win.clearTimeout(restoreTimeout);
         previous.forEach((item) => dispose(item, afterPaint));
         callbacks.wake();
     };
     const finishRestoration = () => {
-        if (!active)
+        if (!handoff)
             return;
         // A moved return invalidates the cached coordinates, but keeps the active
         // visual until Native has taken ownership at its destination.
-        if (cached !== active) {
+        if (cached !== handoff?.image) {
             abandon();
             return;
         }
-        const image = active;
+        const image = handoff.image;
         presentation++;
         win.cancelAnimationFrame(paintFrame);
         paintFrame = 0;
-        handoffPending = presented = false;
-        image.sources.forEach((source) => {
-            owners.delete(source);
-            visibleOwners.delete(source);
-        });
+        handoffPending = false;
         rendered.forEach((target) => target.removeAttribute('data-native-ui-snapshot-source'));
         showImages(image, !!callbacks.opaqueUnderlay);
-        active = undefined;
-        ending = false;
+        handoff = undefined;
         win.clearTimeout(restoreTimeout);
         // Retire only the temporary return copy. Keep the pre-interaction image
         // available until a replacement finishes, including rapid overlay reopening.
@@ -483,7 +484,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
         callbacks.wake();
     };
     const retireRestoration = () => {
-        if (ending)
+        if (restoring())
             finishRestoration();
         pendingCleanup.forEach((run) => run());
     };
@@ -531,17 +532,17 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
                     element.style.setProperty(property, next, 'important');
             }
     };
-    const render = (image = active ?? cached) => {
-        if (!image || ending)
+    const render = (image = handoff?.image ?? cached) => {
+        if (!image || restoring())
             return false;
         if (!image.sources.every(validSource) || targetsFor(image).some((target) => !target)) {
             invalidate();
             return false;
         }
         const targets = targetsFor(image);
-        if (active) {
+        if (handoff) {
             if (targets.some((target) => !target?.isConnected || !sheets.has(rootFor(target)))) {
-                abandon(active, false);
+                abandon(handoff.image, false);
                 return false;
             }
             const next = new Set();
@@ -559,7 +560,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
                     clearTarget(target);
             rendered.clear();
             next.forEach((target) => rendered.add(target));
-            showImages(image, presented);
+            showImages(image, imageVisible());
             return true;
         }
         imagePool.forEach((pool) => pool.forEach((element) => {
@@ -625,13 +626,13 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
     });
     const present = (force = false) => {
         retireRestoration();
-        if (stopped || destination === 'none' || (active && !force))
+        if (stopped || destination === 'none' || (handoff && !force))
             return;
-        const image = active ?? cached;
+        const image = handoff?.image ?? cached;
         if (!image ||
             image.viewport !== viewport() ||
             !image.sources.every(validSource) ||
-            (callbacks.current && !callbacks.current(image.targets)) ||
+            (callbacks.current && !callbacks.current(image.sources)) ||
             image.targets.some((source) => !preparedKeys.has(source)) ||
             targetsFor(image).some((target) => !target?.isConnected) ||
             [...rendered].some((target) => !target.isConnected))
@@ -645,16 +646,12 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
         const currentPresentation = ++presentation;
         const isCurrent = () => presentation === currentPresentation;
         handoffPending = true;
-        presented = !!callbacks.opaqueUnderlay;
-        active = image;
+        handoff = { phase: 'covering', image };
         // Reuse decoded pixels; no capture, bridge acknowledgement or animation wait.
         generation++;
         win.clearTimeout(timer);
-        image.sources.forEach((source) => {
-            owners.add(source);
-        });
         rendered.forEach((target) => target.setAttribute('data-native-ui-snapshot-source', ''));
-        showImages(image, presented);
+        showImages(image, imageVisible());
         // Reconciliation may continue after one frame even if the optional bridge reply
         // is delayed. The ordered native transport processes cover before that update.
         paintFrame = win.requestAnimationFrame(() => {
@@ -679,25 +676,28 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
             }
             // Live translucent Native must be hidden before its composited Web image
             // becomes visible. Native's prepared entry copy spans this bridge interval.
-            if (!ending) {
-                presented = true;
-                image.sources.forEach((source) => visibleOwners.add(source));
+            if (!restoring()) {
+                handoff = { phase: 'image', image };
                 render();
                 updateOffsets();
             }
             win.cancelAnimationFrame(paintFrame);
+            // rAF callbacks run before paint. Cross a paint boundary before retiring
+            // Native's entry copy, keeping it over WebKit's compositing interval.
             paintFrame = win.requestAnimationFrame(() => {
-                paintFrame = 0;
-                if (!isCurrent())
-                    return;
-                void call({ action: 'painted', token: image.data.token })
-                    .then((result) => {
-                    if (isCurrent() && result?.shown === false)
-                        abandon(image, false);
-                })
-                    .catch(() => {
-                    if (isCurrent())
-                        abandon(image, false);
+                paintFrame = win.requestAnimationFrame(() => {
+                    paintFrame = 0;
+                    if (!isCurrent())
+                        return;
+                    void call({ action: 'painted', token: image.data.token })
+                        .then((result) => {
+                        if (isCurrent() && result?.shown === false)
+                            abandon(image, false);
+                    })
+                        .catch(() => {
+                        if (isCurrent())
+                            abandon(image, false);
+                    });
                 });
             });
             callbacks.wake();
@@ -708,20 +708,20 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
         });
     };
     const restore = () => {
-        if (!active || stopped || ending)
+        if (!handoff || stopped || restoring())
             return;
         // A return belongs to the captured surface, never to the modal exposed beneath it.
-        if (!active.sources.every(validSource) ||
-            targetsFor(active).some((target) => !target) ||
-            (callbacks.current && !callbacks.current(active.targets))) {
-            abandon(active, false);
+        if (!handoff.image.sources.every(validSource) ||
+            targetsFor(handoff.image).some((target) => !target) ||
+            (callbacks.current && !callbacks.current(handoff.image.sources))) {
+            abandon(handoff.image, false);
             return;
         }
         if (callbacks.blocked())
             return;
         updateOffsets();
         if (callbacks.transient) {
-            const image = active;
+            const image = handoff.image;
             const targets = targetsFor(image);
             if (targets.some((target) => !target?.isConnected)) {
                 abandon(image, false);
@@ -731,28 +731,38 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
             // Translation changes placement, not pixels. Keep the pre-interaction
             // image until its replacement is ready; resizing still invalidates it.
             if (callbacks.opaqueUnderlay ||
-                parts.every((part, index) => part.width === image.data.parts[index].width && part.height === image.data.parts[index].height))
+                parts.every((part, index) => {
+                    const original = image.data.parts[index];
+                    const scale = win.devicePixelRatio || 1;
+                    // Transformed DOMRects can differ by floating-point noise. Reuse pixels
+                    // only when their raster dimensions still match at the display scale.
+                    return (Math.round(part.width * scale) === Math.round(original.width * scale) &&
+                        Math.round(part.height * scale) === Math.round(original.height * scale));
+                }))
                 image.data = { ...image.data, parts };
             else
                 cached = undefined;
             // Both requests use the same ordered bridge. Reprojection need not await this optional copy.
             void call({ action: 'restore', token: image.data.token, viewportWidth: win.innerWidth, parts }).catch(() => { });
         }
-        restoreRevision = callbacks.revision?.() ?? latest?.revision ?? 0;
-        ending = true;
-        active.sources.forEach((source) => owners.delete(source));
+        handoff = {
+            phase: 'restoring',
+            image: handoff.image,
+            visible: handoff.phase === 'image',
+            revision: callbacks.revision?.() ?? latest?.revision ?? 0,
+        };
         restoreTimeout = win.setTimeout(() => {
-            if (ending)
-                abandon(active, false);
+            if (handoff?.phase === 'restoring')
+                abandon(handoff.image, false);
         }, 250);
         callbacks.wake();
     };
     const updated = (token, restoredIDs, revision) => {
-        if (!ending || !active || revision === undefined || revision <= restoreRevision)
+        if (handoff?.phase !== 'restoring' || revision === undefined || revision <= handoff.revision)
             return;
         if (!callbacks.transient && token)
             return;
-        if (!active.data.parts.every((part) => part.ids.every((id) => restoredIDs?.includes(id))))
+        if (!handoff.image.data.parts.every((part) => part.ids.every((id) => restoredIDs?.includes(id))))
             return;
         // Retire the Web image at the native restore acknowledgement, not after
         // another complete reconciliation/paint cycle over live glass.
@@ -767,7 +777,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
         cached = undefined;
         if (nativeHidden || stopped)
             retiring = undefined;
-        if (callbacks.retainPreparedUntilRelease && !active && !nativeHidden && !stopped) {
+        if (callbacks.retainPreparedUntilRelease && !handoff && !nativeHidden && !stopped) {
             if (previous) {
                 const pending = {};
                 retiring = pending;
@@ -780,7 +790,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
                     if (retiring !== pending)
                         return;
                     retiring = undefined;
-                    if (cached || active)
+                    if (cached || handoff)
                         return;
                     // Another session can already own the same host; retire only our own DOM markers.
                     for (const target of rendered) {
@@ -798,8 +808,8 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
                 return;
         }
         dispose(previous);
-        if (active)
-            abandon(active, false);
+        if (handoff)
+            abandon(handoff.image, false);
         else {
             detach();
             preparedKeys.clear();
@@ -813,15 +823,15 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
     };
     const end = () => {
         locallyRequested = false;
-        if (!projectionRequest.isPaused())
+        if (!imageRequested())
             restore();
     };
     const projectionChanged = () => queueMicrotask(() => {
         if (stopped)
             return;
-        if (projectionRequest.isPaused())
+        if (imageRequested())
             present();
-        else if (!locallyRequested)
+        else
             restore();
         callbacks.wake();
     });
@@ -861,10 +871,10 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
     const stopPause = projectionRequest.subscribe(projectionChanged);
     return {
         get owners() {
-            return [...owners];
+            return handoff && handoff.phase !== 'restoring' ? [...handoff.image.sources] : [];
         },
         get visibleOwners() {
-            return [...visibleOwners];
+            return handoff && (handoff.phase === 'image' || (handoff.phase === 'restoring' && handoff.visible)) ? [...handoff.image.sources] : [];
         },
         get preparedOwners() {
             return [...preparedOwners];
@@ -873,11 +883,11 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
         changed,
         moved: updateOffsets,
         get token() {
-            return ending ? undefined : active?.data.token;
+            return restoring() ? undefined : handoff?.image.data.token;
         },
         begin,
         get restoring() {
-            return ending;
+            return restoring();
         },
         get handoffPending() {
             return handoffPending;
@@ -914,6 +924,7 @@ export const createWebProjectionBatch = async (transport, options) => {
     let latest;
     let stopped = false;
     let batchDocument;
+    let pendingRequest = false;
     return {
         get owners() {
             return engine?.owners ?? [];
@@ -956,6 +967,9 @@ export const createWebProjectionBatch = async (transport, options) => {
                     return;
                 }
                 engine = created;
+                if (pendingRequest)
+                    engine.begin();
+                pendingRequest = false;
                 if (latest)
                     engine.consider(latest.revision, latest.sources);
             })
@@ -966,8 +980,16 @@ export const createWebProjectionBatch = async (transport, options) => {
         },
         changed: (owner) => engine?.changed(owner),
         moved: () => engine?.moved(),
-        begin: () => engine?.begin(),
-        end: () => engine?.end(),
+        begin() {
+            if (engine)
+                engine.begin();
+            else
+                pendingRequest = true;
+        },
+        end() {
+            pendingRequest = false;
+            engine?.end();
+        },
         updated: (token, ids, revision) => engine?.updated(token, ids, revision),
         retireRestoration: () => engine?.retireRestoration(),
         invalidate: (nativeHidden) => engine?.invalidate(nativeHidden),

package/dist/types.d.ts

@@ -20,6 +20,7 @@ export interface ScrollPlacement {
 /** A source and its native rendering. Kind/placement are opaque layout identity keys. */
 export interface WebProjectionSource {
     element: HTMLElement;
+    /** Exact DOM sources represented by this control. Replaces the default [element] when supplied. */
     sources?: HTMLElement[];
     scrollElement?: HTMLElement;
     control: Frame & {

package/docs/advanced/web-projection.md

@@ -37,11 +37,24 @@ The container, bridge and update callbacks above belong to the consuming plugin.
 
 1. After an accepted native update, call `projection.consider(revision, sources)`. Sources associate the native IDs and viewport frames with their source DOM; they need not be inside the fallback element. Images are captured and decoded in advance.
 2. Call `projection.changed()` for appearance changes, or `projection.changed(scrollElement)` to invalidate scroll geometry. Layout updates go through `consider`; use `invalidate()` for other geometry changes.
-3. Before covering Native with a Web overlay, call `projection.begin()`. It displays already prepared pixels at the fixed fallback. No new capture or decode starts here. If capture is unavailable, the plugin keeps its ordinary Web fallback.
-4. Exclude `projection.owners` from normal Native updates while the image owns those sources. `visibleOwners` keeps their return pixels while Native is being restored; `preparedOwners` identifies sources with prepared images. These arrays are read-only snapshots.
+3. Before covering Native with a Web overlay, call `projection.begin()`. It displays already prepared pixels at the fixed fallback. No new capture or decode starts here. If no image is ready, no pixel lease is acquired. The plugin retains its existing ownership and chooses how to handle unavailable images.
+4. Exclude `projection.owners` from normal Native updates while their pixels are delegated to the image. `visibleOwners` keeps their return pixels while Native is being restored; `preparedOwners` identifies sources with prepared images. These arrays are read-only snapshots.
 5. Call `projection.end()`, send the normal native update, then call `projection.updated(snapshotToken, acceptedIDs, revision)`. A newer acknowledgement containing all captured IDs retires the image.
 6. Call `projection.destroy()` when disposing the surface. It releases only its own images and listener; the plugin owns final Native reset and its DOM.
 
+Image requests, pixel handoffs, and renderer ownership are separate. `begin()` requests an image; it does not release Native ownership or imply that pixels are ready. The request survives lazy initialization and preparation until `end()` cancels it. A Document pause holds the same request independently.
+
+| Image state                     | `owners`         | `visibleOwners`            | Renderer action                                                                           |
+| ------------------------------- | ---------------- | -------------------------- | ----------------------------------------------------------------------------------------- |
+| Idle / preparing                | Empty            | Empty                      | Keep normal Native rendering. A prepared cache alone does not transfer pixels.            |
+| Cover pending (prepared pixels) | Captured sources | Empty                      | Use the ordered cover transport; Native's entry copy bridges its acknowledgement.         |
+| Image displayed                 | Captured sources | Captured sources           | Temporarily omit these controls from Native updates, retaining renderer source ownership. |
+| Restoring Native                | Empty            | Previously visible sources | Send the Native controls again. Keep the image until a newer, complete acknowledgement.   |
+
+The image state is the single source for these read-only arrays. Motion, cache misses, and the end of an image handoff do not themselves return a renderer's source to Web. The consuming renderer makes that decision for removed/ineligible sources, rejected Native controls, or disposal. The `painted` notification crosses a rendering opportunity before retiring Native's entry copy; it is not a compositor completion API.
+
+For composite controls, `sources` declares the exact DOM elements represented by the image and replaces the default `[element]`. The `element` remains the control/layout anchor; include it explicitly only when the image also represents that whole element. For a partial button group, list only the selected children so unselected siblings retain their own presentation. For searchable tabs, include the represented trigger/footer companions. `options.current(sources)` receives this same captured source set when validating presentation and restoration, so moving a companion to another context invalidates its old image even if the layout anchor remains connected.
+
 The engine prepares a noninteractive `img` inside the fallback container (directly inside its open ShadowRoot when present) while Native is visible. It reuses the decoded image and DOM node across handoffs, and releases them when the scope is retired or destroyed. The image is `inert`, hidden from accessibility and excluded from hit testing. The existing fallback and its children are never cloned, replaced, removed or assigned `inert`/`aria-hidden`; their listeners, values and application changes survive projection. Both `::before` and `::after` remain available to the application.
 
 Supply an existing container such as `div`, `button` or a custom element. Replaced/void elements such as `img`, `input` and `video` remain unsupported as scopes; use their existing fallback container. The renderer may move the same container between parents, but must not replace a low-level scope's element or let two managers control it simultaneously. Notify the manager through `moved()` when changing its placement during projection.

package/ios/Sources/WebViewNativeUIEngine/CoveredSnapshots.swift

@@ -29,6 +29,7 @@ public final class NativeUICoveredSnapshots {
     public private(set) var coveringToken: String?
     /// Dispatch the renderer's existing ordered image-handoff transport on the main thread.
     /// The renderer supplies eligible native bounds and the complete views that may be hidden.
+    /// A nil view selection rejects the handoff; an empty selection means the valid image has no live views to retire.
     public func handle(_ request: [String: Any], in webView: UIView,
                        frames: @escaping (Set<String>, Int) -> [String: CGRect],
                        views: (Set<String>) -> [UIView]?, complete: @escaping ([String: Any]) -> Void) {
@@ -50,7 +51,7 @@ public final class NativeUICoveredSnapshots {
         case "cover":
             let ids = identifiers(for: token)
             let destination = request["parts"] == nil ? nil : projectionFrames(request, in: webView)
-            guard !ids.isEmpty, let selected = views(ids), !selected.isEmpty,
+            guard !ids.isEmpty, let selected = views(ids),
                   request["parts"] == nil || destination != nil else { complete(["shown": false]); return }
             var seen = Set<ObjectIdentifier>()
             complete(["shown": cover(token, in: webView, views: selected.filter { seen.insert(ObjectIdentifier($0)).inserted },