@webview-native-ui/engine 0.0.2 → 0.0.3

package/docs/maintenance.md

@@ -25,13 +25,13 @@ xcodebuild -scheme WebViewNativeUIEngine -destination 'platform=iOS Simulator,id
 
 Lint combines strict TypeScript checking, the standard ESLint/TypeScript recommended rules, and typed Promise checks for `src`. Scripts and tests receive syntax-level linting; Prettier owns formatting. `npm run format` applies formatting only. Bridge payloads and test doubles may use explicit `any`; production boundary validation remains necessary. An explicit `void` marks background work, but does not handle a rejected Promise. Android uses `lintRelease` with warnings treated as errors in CI; Swift is compiled and tested on an iOS simulator.
 
-The engine is versioned independently of its consumers. Publish order is the native Maven artifact → npm engine; consumers upgrade separately. npm releases verify that the matching POM and AAR exist on Maven Central before publication. No publication is performed by build or test commands. Tests cover plain DOM, fractional/RTL geometry, stale ACKs, image ownership and native WKWebView scroll tracking; consumer tests remain responsible for Ionic/SDK integration.
+The engine is versioned independently of its consumers. Publish order is Maven publication acceptance → npm engine; consumers upgrade separately. npm releases require a successful Maven publication workflow for the exact tagged commit. Maven Central distribution may still be pending: Android consumers must wait until the matching POM and AAR are downloadable, while iOS and Web consumers can upgrade immediately. No publication is performed by build or test commands. Tests cover plain DOM, fractional/RTL geometry, stale ACKs, image ownership and native WKWebView scroll tracking; consumer tests remain responsible for Ionic/SDK integration.
 
 CI-only setup, packaging commands and GitHub outputs are defined in `.github/workflows/`. Scripts retain the runtime build, reusable consumer/package verification, and tested publication logic (Central state handling and npm artifact comparison).
 
 ## Maven publication
 
-The `Native UI Engine Maven Release` workflow is manually dispatched on `main` with the exact engine package version. That commit must first pass `Native UI Engine` CI. It signs an AAR, source archive, generated Kotlin API documentation and Maven metadata, uploads once, and completes when Central reports `PUBLISHING` or `PUBLISHED`. The deployment ID and state changes are recorded in the run summary. `PUBLISHING` means validation passed and Central accepted publication; it does not guarantee that artifacts can already be downloaded. This workflow does not wait for distribution. The npm release still requires the matching POM and AAR to be available on Maven Central. Existing coordinates are never overwritten; if an upload times out, inspect the recorded deployment in Central before taking further action.
+The `Native UI Engine Maven Release` workflow is manually dispatched on `main` with the exact engine package version. That commit must first pass `Native UI Engine` CI. It signs an AAR, source archive, generated Kotlin API documentation and Maven metadata, uploads once, and completes when Central reports `PUBLISHING` or `PUBLISHED`. The deployment ID and state changes are recorded in the run summary. `PUBLISHING` means validation passed and Central accepted publication; it does not guarantee that artifacts can already be downloaded. This workflow does not wait for distribution. The npm release checks that this workflow succeeded for the exact release commit; it does not wait for Maven Central distribution. Existing coordinates are never overwritten; if an upload times out, inspect the recorded deployment in Central before taking further action.
 
 Configure the repository's Actions secrets with `CENTRAL_USERNAME`, `CENTRAL_PASSWORD` (a Central user token), `MAVEN_SIGNING_KEY` (ASCII-armored private key) and `MAVEN_SIGNING_PASSWORD`. The signing public key must be available to Central. GitHub secrets are scoped to this repository.
 
@@ -43,9 +43,9 @@ This repository starts from the merged Engine implementation at [ionic-theme-ios
 
 The npm organization `webview-native-ui` and Maven Central namespace `io.github.webview-native-ui` are registered. Maintain npm trusted publishing for `webview-native-ui/engine`, workflow `release.yml`, and provision the Maven secrets above in this repository. Credentials are not copied by moving source files.
 
-1. Prepare the next version and release notes on `main`; use `npm run release` to create a standard `vX.Y.Z` tag/GitHub release. Keep the GitHub release as a draft until Maven is downloadable.
+1. Prepare the next version and release notes on `main`; use `npm run release` to create a standard `vX.Y.Z` tag/GitHub release. Keep the GitHub release as a draft until the Maven publication workflow succeeds.
 2. After that main commit passes CI, dispatch `native-ui-engine-release.yml` with the exact package version.
-3. Central `PUBLISHING` is an accepted upload, not download readiness. Once the POM and AAR are available, publish the prepared GitHub release. `release.yml` verifies the tag, package version, CI and Maven artifacts before npm publication (`next` for prereleases, `latest` otherwise).
+3. Central `PUBLISHING` is an accepted upload, not download readiness. Once the Maven publication workflow succeeds, publish the prepared GitHub release. Note any pending Android artifact distribution in the release notes. `release.yml` verifies the tag, package version, CI and Maven publication acceptance before npm publication (`next` for prereleases, `latest` otherwise).
 
 No build or test command publishes a package. Existing npm/Maven versions are never overwritten.
 

package/docs/projection.md

@@ -244,7 +244,7 @@ The image transport accepts `WebProjectionRequest` and returns prepared token/pa
 | `release`  | Release the named token, files and associated temporary views.                                                                                          |
 | `reset`    | Owner teardown only; release all native capture resources.                                                                                              |
 
-Use `NativeUICoveredSnapshots.observe` to notify the JS listener when interaction starts/ends. Captures use composited pixels so blur/refraction is preserved; they include the background under the clipped native component. Cache validity therefore includes layout and the plugin's visual-change notifications. The engine does not capture continuously or guarantee every possible renderer can be captured.
+Use `NativeUICoveredSnapshots.observe` to notify the JS listener when interaction starts/ends. On iOS, captures rasterize the visible window with `drawHierarchy(in:afterScreenUpdates:)`, including the background under the clipped native component. Screen snapshot views are display replicas and are not used as bitmap sources. UIKit rasterization can differ from the live compositor for materials such as Liquid Glass; validate the appearance on physical devices with the backgrounds your plugin supports. Cache validity therefore includes layout and the plugin's visual-change notifications. The engine does not capture continuously or guarantee every possible renderer can be captured.
 
 ### Temporary storage and application permissions
 

package/ios/Sources/WebViewNativeUIEngine/CoveredSnapshots.swift

@@ -14,13 +14,7 @@ public final class NativeUICoveredSnapshots {
         let webFrame: CGRect
         let parts: [Part]
     }
-    private let snapshotView: (UIWindow) -> UIView
-    public convenience init() {
-        self.init(snapshotView: { $0.screen.snapshotView(afterScreenUpdates: false) })
-    }
-    init(snapshotView: @escaping (UIWindow) -> UIView) {
-        self.snapshotView = snapshotView
-    }
+    public init() {}
     private var captures: [String: Capture] = [:]
     private var restoration: (token: String, views: [UIImageView], entry: Bool)?
     private var hiddenControls: (token: String, restore: [() -> Void])?
@@ -89,15 +83,13 @@ public final class NativeUICoveredSnapshots {
         let format = UIGraphicsImageRendererFormat()
         format.scale = scale
         format.opaque = true
-        // Render the compositor's frozen screen, not UIKit's reconstruction of
-        // the hierarchy: the latter loses Liquid Glass background refraction.
-        // The replica remains detached and never changes visible UI or input.
-        let replica = snapshotView(window)
-        let screenBounds = window.convert(bounds, to: window.screen.coordinateSpace)
+        // Rasterize the visible window directly. A screen snapshot is a display
+        // replica, not a bitmap source; drawing that replica can succeed with
+        // black pixels on physical devices.
         var drawn = false
         let image = UIGraphicsImageRenderer(size: bounds.size, format: format).image { context in
-            context.cgContext.translateBy(x: -screenBounds.minX, y: -screenBounds.minY)
-            drawn = replica.drawHierarchy(in: window.screen.bounds, afterScreenUpdates: true)
+            context.cgContext.translateBy(x: -bounds.minX, y: -bounds.minY)
+            drawn = window.drawHierarchy(in: window.bounds, afterScreenUpdates: true)
         }
         guard drawn, let pixels = image.cgImage else { complete([:]); return }
         let token = UUID().uuidString

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webview-native-ui/engine",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Native UI placement, scroll tracking, and Web projection for Capacitor and Cordova plugin maintainers.",
   "type": "module",
   "license": "MIT",