@webview-native-ui/engine 0.0.1 → 0.0.3

package/WebViewNativeUIEngine.podspec

@@ -5,8 +5,8 @@ Pod::Spec.new do |s|
  s.version = package['version']
  s.summary = 'Native UI infrastructure for Capacitor and Cordova plugin maintainers.'
  s.homepage = 'https://github.com/webview-native-ui/engine'
- s.license = { :type => 'Zlib', :file => 'LICENSE' }
- s.preserve_paths = 'LICENSE', 'NOTICE'
+ s.license = { :type => 'MIT', :file => 'LICENSE' }
+ s.preserve_paths = 'LICENSE'
  s.author = { 'rdlabo' => 'sakakibara@rdlabo.jp' }
  s.source = { :git => 'https://github.com/webview-native-ui/engine.git', :tag => "v#{s.version}" }
  s.resource_bundles = { 'WebViewNativeUIEngine' => ['ios/Sources/WebViewNativeUIEngine/Resources/*.js'] }

package/dist/{scroll-bindings.d.ts → dom/scroll-bindings.d.ts}

@@ -1,4 +1,4 @@
-import type { WebProjectionSource } from './types.js';
+import type { WebProjectionSource } from '../types.js';
 /** Coordinate ownership, independent of any plugin's update transport or rendering. */
 export declare const createScrollBindings: () => {
     reuse: (candidate: WebProjectionSource, width: number) => boolean;

package/dist/{scroll-placement.d.ts → dom/scroll-placement.d.ts}

@@ -1,4 +1,4 @@
-import type { ScrollPlacement as NativeUIScrollPlacement } from './types.js';
+import type { ScrollPlacement as NativeUIScrollPlacement } from '../types.js';
 type Identify = (element: HTMLElement) => string;
 /** Layout-only measurement. Native owns subsequent scroll offsets. No private Ionic APIs. */
 export declare const readScrollPlacement: (element: HTMLElement, owner: HTMLElement, id: Identify) => NativeUIScrollPlacement | undefined;

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 export * from './types.js';
-export * from './geometry.js';
-export * from './scroll-placement.js';
-export { createWebProjectionScope, type WebProjectionScope } from './web-projection-scope.js';
-export * from './web-projection.js';
-export * from './scroll-bindings.js';
-export type { ProjectionEvents, ProjectionDestination } from './projection-events.js';
-export { getOverlayCoordinator, usesOverlayBackdrop, type OverlayChange, type OverlayOptions } from './overlays.js';
-export { getUnprojectedVisibility } from './visibility.js';
-export { bindProjectionPlacement, type ProjectionPlacementBinding } from './projection-placement.js';
+export * from './dom/geometry.js';
+export * from './dom/scroll-placement.js';
+export { createWebProjectionScope, type WebProjectionScope } from './projection/scope.js';
+export * from './projection/web.js';
+export * from './dom/scroll-bindings.js';
+export type { ProjectionEvents, ProjectionDestination } from './projection/events.js';
+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';

package/dist/index.js

@@ -1,9 +1,9 @@
 export * from './types.js';
-export * from './geometry.js';
-export * from './scroll-placement.js';
-export { createWebProjectionScope } from './web-projection-scope.js';
-export * from './web-projection.js';
-export * from './scroll-bindings.js';
-export { getOverlayCoordinator, usesOverlayBackdrop } from './overlays.js';
-export { getUnprojectedVisibility } from './visibility.js';
-export { bindProjectionPlacement } from './projection-placement.js';
+export * from './dom/geometry.js';
+export * from './dom/scroll-placement.js';
+export { createWebProjectionScope } from './projection/scope.js';
+export * from './projection/web.js';
+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';

package/dist/ionic.d.ts

@@ -1,9 +1,9 @@
-import { type OverlayDefinition, type OverlayOptions } from './overlays.js';
-export type { OverlayOptions as IonicOverlayOptions } from './overlays.js';
+import { type OverlayDefinition, type OverlayOptions } from './dom/overlays.js';
+export type { OverlayOptions as IonicOverlayOptions } from './dom/overlays.js';
 /** Call once at app startup. Repeated default calls share the existing configuration and monitor. */
 export declare const enableSupportIonicOverlays: (options?: OverlayOptions, doc?: Document | undefined) => {
     readonly active: ReadonlySet<HTMLElement>;
-    subscribe(listener: (change: import("./overlays.js").OverlayChange) => void): () => void;
+    subscribe(listener: (change: import("./dom/overlays.js").OverlayChange) => void): () => void;
     setNative(element: HTMLElement, value: boolean): void;
     isExcluded(element: HTMLElement): boolean;
     isNative(element: HTMLElement): boolean;

package/dist/ionic.js

@@ -1,4 +1,4 @@
-import { getOverlayCoordinator } from './overlays.js';
+import { getOverlayCoordinator } from './dom/overlays.js';
 const defaults = [
     ...['Modal', 'Popover', 'Alert', 'ActionSheet', 'Loading', 'Picker', 'Toast'].map((name) => ({
         selector: `ion-${name.replace(/[A-Z]/g, (letter, index) => (index ? '-' : '') + letter.toLowerCase())}`,

package/dist/{native-bootstrap.d.ts → native/bootstrap.d.ts}

@@ -1,4 +1,4 @@
-import { type NativeSessionConfiguration } from './native-session.js';
+import { type NativeSessionConfiguration } from './session.js';
 /** Cordova plugins forward their existing notifications through NativeUIProjection.receive. */
 export declare const notify: (id: string, name: string, data: unknown) => void | undefined;
 export declare const receive: (id: string, key: string | null, value: any, error?: string) => void;

package/dist/{native-bootstrap.js → native/bootstrap.js}

@@ -1,4 +1,4 @@
-import { startNativeSession } from './native-session.js';
+import { startNativeSession } from './session.js';
 const sessions = new Map();
 const pending = new Map();
 const interactions = new Map();

package/dist/{bridge.d.ts → native/bridge.d.ts}

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

package/dist/{native-session.d.ts → native/session.d.ts}

@@ -1,11 +1,12 @@
-import { type ProjectionDestination } from './projection-events.js';
-import type { ScrollPlacement, ListenerHandle, WebProjectionRequest } from './types.js';
+import { type ProjectionDestination } from '../projection/events.js';
+import type { ScrollPlacement, ListenerHandle, WebProjectionRequest } from '../types.js';
 /** Serialized by the native library. One registration owns one fixed fallback container. */
 export interface NativeSessionConfiguration {
     id: string;
     plugin: string;
     runtime?: 'capacitor' | 'cordova';
     projectionSelector: string;
+    captureDelayMs?: number;
     /** Recovery while native is requested. Explicit web/none destinations take precedence. */
     failedFallback?: 'web' | 'native';
     captureMode?: 'composited' | 'view';

package/dist/{native-session.js → native/session.js}

@@ -1,10 +1,10 @@
-import { projectionPlacement } from './projection-placement.js';
-import { getOverlayCoordinator } from './overlays.js';
-import { readScrollPlacement } from './scroll-placement.js';
-import { projectionAncestors } from './geometry.js';
-import { createWebProjection } from './web-projection.js';
-import { createWebProjectionScope } from './web-projection-scope.js';
-import { bindProjectionEvents } from './projection-events.js';
+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) => {
@@ -246,6 +246,7 @@ export const startNativeSession = async (config, nativeBridge, plugin = {
             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,

package/dist/{projection-events.d.ts → projection/events.d.ts}

@@ -1,4 +1,4 @@
-import type { ListenerHandle } from './types.js';
+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 {

package/dist/{projection-events.js → projection/events.js}

@@ -1,4 +1,4 @@
-import { boundedListener } from './bridge.js';
+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();

package/dist/{web-projection.d.ts → projection/web.d.ts}

@@ -1,9 +1,11 @@
-import type { WebProjectionSource, ScopedWebProjectionSource as Candidate, WebProjectionTransport } from './types.js';
-import type { WebProjectionScope } from './web-projection-scope.js';
-import { type ProjectionEvents } from './projection-events.js';
+import type { WebProjectionSource, ScopedWebProjectionSource as Candidate, WebProjectionTransport } from '../types.js';
+import type { WebProjectionScope } from './scope.js';
+import { type ProjectionEvents } from './events.js';
 export interface WebProjectionOptions {
     /** Existing plugin notifications, scoped to this presentation surface. */
     events?: ProjectionEvents;
+    /** Debounce before preparing replacement pixels, in milliseconds. Defaults to 50; never delays handoff. */
+    captureDelayMs?: number;
     wake(): void;
     blocked(): boolean;
     revision?(): number;

package/dist/{web-projection.js → projection/web.js}

@@ -1,8 +1,8 @@
-import { projectionURL } from './runtime.js';
-import { bounded, boundedListener } from './bridge.js';
-import { bindProjectionEvents } from './projection-events.js';
-import { projectionAncestors } from './geometry.js';
-import { snapshotStyles } from './snapshot-styles.js';
+import { projectionURL } from '../native/resource-url.js';
+import { bounded, boundedListener } from '../native/bridge.js';
+import { bindProjectionEvents } from './events.js';
+import { projectionAncestors } from '../dom/geometry.js';
+import { snapshotStyles } from './styles.js';
 const layout = (candidates, positionIndependent = false) => JSON.stringify(candidates.map(({ control: c }) => [
     c.id,
     c.kind,
@@ -51,6 +51,9 @@ const coordinateSpace = (target, win, style = win.getComputedStyle(target)) => {
 };
 /** Images are prepared after accepted native updates, never on the overlay's critical path. */
 const createProjectionEngine = async (scope, transport, callbacks) => {
+    const captureDelayMs = callbacks.captureDelayMs ?? 50;
+    if (!Number.isFinite(captureDelayMs) || captureDelayMs < 0 || captureDelayMs > 2147483647)
+        throw new RangeError('captureDelayMs must be a finite, nonnegative timer interval');
     let destination = 'native';
     const doc = scope.element.ownerDocument;
     const win = doc.defaultView;
@@ -265,7 +268,7 @@ const createProjectionEngine = async (scope, transport, callbacks) => {
     const schedule = () => {
         win.clearTimeout(timer);
         if (!stopped && destination === 'native' && !active && !touching && !callbacks.blocked())
-            timer = win.setTimeout(() => void prepare(), 50);
+            timer = win.setTimeout(() => void prepare(), captureDelayMs);
     };
     let consideredLayout;
     const consider = (revision, candidates) => {

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { WebProjectionScope } from './web-projection-scope.js';
+import type { WebProjectionScope } from './projection/scope.js';
 /** All wire coordinates are CSS pixels, relative to the Web viewport. */
 export interface Frame {
     x: number;

package/docs/capacitor-plugin.md

@@ -0,0 +1,279 @@
+# Capacitor plugin integration
+
+Add Web projection and restoration to an existing Capacitor plugin without changing its public `registerPlugin()` export. The plugin keeps its native renderer and application API; the Engine coordinates its native view with a DOM fallback.
+
+This guide covers dependencies, registration, notifications and teardown. See [projection behavior](projection.md) for shared DOM requirements, capture policies and advanced integration.
+
+## Requirements
+
+This package declares support for Capacitor 8 (`>=8.0.0 <9`). The Engine library requires iOS 15+ and Android API 23+; the consuming Capacitor version or SDK may require a higher minimum. Composited Android capture requires API 26+ and the WebView features described in the [projection reference](projection.md#dom-and-native-surface-requirements).
+
+## Install inside a plugin
+
+```sh
+npm install --save-exact @webview-native-ui/engine@0.0.1
+```
+
+The npm archive contains TypeScript declarations, ESM, Swift sources and a podspec. Native dependencies must also be declared by the consuming plugin; an npm dependency alone links neither the Swift library nor the Android AAR.
+
+The primary native distribution is Swift Package Manager. Depend on the repository-root library from your plugin:
+
+```swift
+.package(url: "https://github.com/webview-native-ui/engine.git", exact: "0.0.1")
+// In the plugin target's dependencies:
+.product(name: "WebViewNativeUIEngine", package: "engine")
+```
+
+The new coordinates start at `0.0.1`. While the API is pre-1.0, pin the same Engine release across npm, SwiftPM, Gradle and CocoaPods, and upgrade deliberately. Applications should retain their dependency lockfiles for reproducible builds.
+
+SwiftPM resolves this repository's version tags such as `v0.0.1`. For unreleased integration tests, use a local checkout or an explicit tested commit.
+
+`import WebViewNativeUIEngine` requires no Capacitor registration. The npm companion supplies DOM measurement and Web image handoff; SwiftPM resolves the native dependency independently of npm hoisting.
+
+### Android: add the Maven dependency
+
+In the consuming plugin's `android/build.gradle`, add the Engine version matching its npm dependency:
+
+```groovy
+dependencies {
+    implementation 'io.github.webview-native-ui:engine:0.0.1'
+}
+```
+
+Ensure `google()` and `mavenCentral()` are present in the consuming build's dependency repositories. For a build using centralized repositories, merge them into `android/settings.gradle`:
+
+```groovy
+dependencyResolutionManagement {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+```
+
+If the build uses project-level repositories instead, add them to its existing `repositories` block. Installing the npm package does not add this Gradle dependency. Use a version whose POM and AAR are available from Central; `PUBLISHING` only confirms acceptance and does not yet guarantee downloads.
+
+### CocoaPods compatibility through npm
+
+CocoaPods uses the Swift sources and podspec shipped in npm; no CocoaPods Trunk publication is required. The plugin maintainer declares the matching dependency in the plugin's podspec:
+
+```ruby
+s.dependency 'WebViewNativeUIEngine', '0.0.1'
+```
+
+The maintainer must also document this one-time application setup. Install the matching engine version as a direct npm dependency, then add the local pod **inside the application's target, outside `def capacitor_pods`**, which Capacitor regenerates:
+
+```sh
+npm install --save-exact @webview-native-ui/engine@0.0.1
+```
+
+```ruby
+# ios/App/Podfile; adjust the path for a different native project layout.
+target 'App' do
+  capacitor_pods
+  pod 'WebViewNativeUIEngine', :path => '../../node_modules/@webview-native-ui/engine'
+end
+```
+
+Run `npx cap sync ios` and rebuild. Keep the direct engine version aligned with the consuming plugin's dependency when upgrading. With a nonstandard node_modules layout, point `:path` at the installed engine package directory. An npm dependency alone does not register a Pod, and a podspec dependency cannot specify this local path. The engine intentionally has no Capacitor plugin registration or Podfile rewriting hook. SwiftPM consumers do not need this CocoaPods setup.
+
+## Register from the native plugin
+
+Keep the plugin's normal `registerPlugin()` export and public methods unchanged. Create and retain a registration after creating the native renderer. The engine ships its Web runtime with the Swift/Android library, starts it in the current document and future documents, finds the existing fallback DOM, and subscribes to the plugin's notifications. Applications do not call a separate JS initializer.
+
+The integration has three responsibilities:
+
+1. The consumer provides an existing, laid-out Web fallback container in the correct layer. Pass this projection destination as the required `projectionSelector: string`; there is no `null` / automatic DOM creation mode.
+2. The plugin registers its native views and notification names once on each platform.
+3. The plugin emits notifications after its updates and releases the registration at teardown.
+
+### iOS: add the registration to your `CAPPlugin` class
+
+In `ios/Sources/ExamplePlugin/ExamplePlugin.swift`, retain the registration as a property and initialize it in `load()`, **after your existing renderer creates and attaches its view**.
+
+In this diff, `nativeView` is the `UIView` your plugin already owns; its existing rendering code is represented by comments.
+
+Use the existing **`jsName`**, not `identifier`: Capacitor uses `jsName` for JS plugin calls and event subscriptions. Do not repeat the plugin name in the Engine configuration.
+
+```diff
+ import Capacitor
+ import UIKit
++import WebViewNativeUIEngine
+
+ @objc(ExamplePlugin)
+ public class ExamplePlugin: CAPPlugin, CAPBridgedPlugin {
+     public let identifier = "ExamplePlugin"
+     public let jsName = "Example"
+     public let pluginMethods: [CAPPluginMethod] = [
+         CAPPluginMethod(name: "setColors", returnType: CAPPluginReturnPromise)
+     ]
+     private var nativeView: UIView?
++    private var projection: NativeUIProjection?
+
+     public override func load() {
+         // Existing code creates and attaches nativeView here.
++        do {
++            projection = try NativeUIProjection(
++                webView: bridge?.webView,
++                plugin: jsName,
++                projectionSelector: "#native-ui-fallback",
++                receiveListeners: .init(
++                    update: ["appearanceChanged"],
++                    projection: .init(
++                        native: ["shown"],
++                        web: ["transitionStarted"],
++                        none: ["hidden"]
++                    )
++                ),
++                view: { [weak self] in
++                    self?.nativeView
++                }
++            )
++        } catch {
++            CAPLog.print("Native UI projection unavailable: \(error)")
++        }
+     }
+
+     @objc func setColors(_ call: CAPPluginCall) {
+         DispatchQueue.main.async {
+             // Existing code applies the requested colors to nativeView.
++            self.notifyListeners("appearanceChanged", data: [:])
+             call.resolve()
+         }
+     }
++
++    public override func notifyListeners(_ eventName: String, data: [String: Any]?, retainUntilConsumed: Bool) {
++        projection?.receive(eventName, data: data)
++        super.notifyListeners(eventName, data: data, retainUntilConsumed: retainUntilConsumed)
++    }
++
++    deinit {
++        projection?.destroy()
++    }
+ }
+```
+
+Pass `bridge?.webView` directly. If the WebView is unavailable, the Engine throws an initialization error into the same `catch`; a separate guard or force unwrap is unnecessary.
+
+If the view is created later in an existing `initialize` / `show` method, put the registration there after view creation instead of in `load()`. Retain one registration for that renderer's lifetime; do not create another on every update. When replacing a renderer, destroy its old registration before registering the replacement.
+
+### Android: add the registration to your `Plugin` class
+
+Make the corresponding changes in `android/src/main/java/<your-package>/ExamplePlugin.kt`. **`pluginHandle.id`** is Capacitor's registered plugin name, derived from `@CapacitorPlugin`; no second name string is needed.
+
+```diff
+ import android.view.View
+ import com.getcapacitor.Plugin
+ import com.getcapacitor.PluginCall
+ import com.getcapacitor.PluginMethod
+ import com.getcapacitor.annotation.CapacitorPlugin
++import android.util.Log
++import com.getcapacitor.JSObject
++import io.github.webview_native_ui.engine.NativeUIProjection
++import io.github.webview_native_ui.engine.NativeUIProjection.ReceiveListeners
+
+ @CapacitorPlugin(name = "Example")
+ class ExamplePlugin : Plugin() {
+     private var nativeView: View? = null
++    private var projection: NativeUIProjection? = null
+
+     override fun load() {
+         // Existing code creates and attaches nativeView here.
++        projection = runCatching {
++            NativeUIProjection.install(bridge.webView)
++            NativeUIProjection(
++                window = activity.window,
++                webView = bridge.webView,
++                plugin = pluginHandle.id,
++                projectionSelector = "#native-ui-fallback",
++                receiveListeners = ReceiveListeners(
++                    update = listOf("appearanceChanged"),
++                    projection = ReceiveListeners.Projection(
++                        native = listOf("shown"),
++                        web = listOf("transitionStarted"),
++                        none = listOf("hidden")
++                    )
++                ),
++                view = { nativeView }
++            )
++        }.onFailure {
++            Log.e(javaClass.simpleName, "Native UI projection unavailable", it)
++        }.getOrNull()
+     }
+
+     @PluginMethod
+     fun setColors(call: PluginCall) {
+         activity.runOnUiThread {
+             // Existing code applies the requested colors to nativeView.
++            notifyListeners("appearanceChanged", JSObject())
+             call.resolve()
+         }
+     }
++
++    override fun notifyListeners(eventName: String, data: JSObject, retainUntilConsumed: Boolean) {
++        projection?.receive(eventName, data)
++        super.notifyListeners(eventName, data, retainUntilConsumed)
++    }
++
++    override fun handleOnDestroy() {
++        projection?.close()
++        projection = null
++        super.handleOnDestroy()
++    }
+ }
+```
+
+On Android, call `NativeUIProjection.install(bridge.webView)` in plugin `load()`,
+before the first navigation, even when SDK views arrive later. Include installation
+in the same error boundary as registration; if it fails, keep the existing Web
+fallback and do not retry installation after navigation. Registrations then
+share that main-frame, origin-restricted channel; they do not install new message
+listeners into a loaded WebView. This avoids a WebView native crash reproduced when
+registering an asynchronously loaded AdMob view. The registration constructor can
+install the channel only on an un-navigated WebView; late installation fails with
+an actionable error instead of attempting unsafe injection. All registrations on
+the same WebView must use the same allowed origins. Closing a registration removes
+only its owner from the channel, so other slots continue working. The shared channel
+remains installed for the WebView lifetime; registrations must still be retained
+and closed by their consuming plugin.
+
+Both diffs add a private property, native registration, a notification override, an update notification and teardown. They add no Engine methods to `pluginMethods`, no public JS wrapper, and no application-side Engine initializer.
+
+Keep your plugin's existing `registerPlugin()` export. Use the same event names in the registration and `notifyListeners`; if the plugin already emits a suitable event (such as `tabSelected`), list that event instead of emitting it twice.
+
+### Notifications during startup
+
+The notification override above lets the Engine retain the latest matching projection destination before the Web runtime subscribes. No separate state variable or initial-state callback is needed. Forward every notification to `super` as usual: the Engine records state without replaying notifications, updates, or user actions. Without a destination notification, it infers the initial destination from native view visibility. Registration must exist before the notifications it should observe.
+
+If your plugin owns multiple registrations, pass the notification to each registration; `receiveListeners.match` selects the owning surface. Appearance updates do not change the destination. The renderer still owns native placement and visibility before connection.
+
+With the default Web fallback, scrolling without a prepared image or native scroll binding keeps the Web fallback visible until the renderer confirms current native placement with its native-destination notification. An appearance update alone is not that confirmation. Consumers choosing native failure recovery must keep their own native geometry current.
+
+### Which events to emit
+
+All incoming event declarations belong to `receiveListeners`. Its `update` list refreshes the image, its `projection` lists select the destination, and its optional `match` filters notifications for the owning surface.
+
+| Notification                            | Where to emit it in the existing plugin                                               |
+| --------------------------------------- | ------------------------------------------------------------------------------------- |
+| `appearanceChanged` (an `update` event) | After a successful native appearance update, such as `setColors`                      |
+| `transitionStarted` (`web`)             | Before the fallback DOM starts moving or a Web layer covers the native view           |
+| `shown` (`native`)                      | After the plugin's existing show operation, or when returning from the Web projection |
+| `hidden` (`none`)                       | After the plugin's existing hide operation                                            |
+
+The names in the examples are conventions you choose, not reserved Engine methods. An `update` event refreshes the prepared image without changing the requested destination. It does not call `setColors` again.
+
+Emit `transitionStarted` before the DOM starts moving, `shown` when native projection is requested again, and `hidden` after the plugin's own hide operation. Native capture, URL conversion, image preparation, draw acknowledgement, image retirement and listener cleanup stay inside the engine. The engine never invokes the plugin's `show`, `hide`, selection or ad-loading methods. End the registration with `projection.destroy()` on iOS or `projection.close()` on Android when the renderer is destroyed. Retain the registration for its full lifetime and call native APIs on the UI thread.
+
+## DOM, scrolling and overlays
+
+Provide one laid-out DOM container for each registration, in the layer where its Web projection belongs. It may be inserted after registration. The plugin still owns native view placement and sizing; the Engine does not create or size either view for you.
+
+Read the [DOM and native surface requirements](projection.md#dom-and-native-surface-requirements) before integrating custom elements, SDK content or multiple surfaces. Scroll tracking and image handoff are internal to the registration. For Ionic applications, optionally enable [Ionic overlay support](projection.md#ionic-overlay-support-optional) once during application startup. Other frameworks emit the configured projection notifications from their own transition and overlay lifecycle.
+
+## Animated native controls
+
+Native appearance updates prepare replacement images after a 50 ms debounce by default.
+If your control continues animating after its update notification, set `captureDelayMs`
+on the native registration (Swift: `captureDelayMs: 600`; Kotlin: `captureDelayMs = 600`).
+This changes background image preparation, not overlay presentation timing.
+See [capture timing](projection.md#capture-timing) for the cache behavior and measured guidance.