NativeWebView.Platform.Android 0.1.0-alpha.1

NativeWebView

Native webview stack for Avalonia that stays on top of platform-native engines instead of bundling Chromium.

NuGet Packages

End-user installs are typically NativeWebView plus the platform package for the target runtime. NativeWebView.Dialog and NativeWebView.Auth are optional facades, while Core and Interop are primarily composition units and transitive dependencies.

Package Layout

Features

• NativeWebView control for embedded native browser surfaces inside Avalonia.
• NativeWebDialog facade for dialog and popup browser workflows.
• WebAuthenticationBroker facade for OAuth and interactive sign-in.
• Platform backends for Windows, macOS, Linux, iOS, Android, and Browser.
• Optional airspace-mitigation modes: Embedded, GpuSurface, and Offscreen.
• Diagnostics, capability reporting, render-frame export, integrity metadata, and smoke-testable sample apps.

Platform Support Matrix

Installation

Install the Avalonia control package and the platform backend that matches the runtime you ship:

dotnet add package NativeWebView
dotnet add package NativeWebView.Platform.Windows

Optional packages:

• dotnet add package NativeWebView.Dialog
• dotnet add package NativeWebView.Auth

Swap NativeWebView.Platform.Windows for NativeWebView.Platform.macOS, NativeWebView.Platform.Linux, NativeWebView.Platform.iOS, NativeWebView.Platform.Android, or NativeWebView.Platform.Browser as needed.

Quick Start

using NativeWebView.Controls;
using NativeWebView.Core;
using NativeWebView.Platform.Windows;

var factory = new NativeWebViewBackendFactory()
    .UseNativeWebViewWindows();

if (!factory.TryCreateNativeWebViewBackend(NativeWebViewPlatform.Windows, out var backend))
{
    throw new InvalidOperationException("Windows backend is not available.");
}

using var webView = new NativeWebView(backend);
await webView.InitializeAsync();
webView.RenderMode = NativeWebViewRenderMode.GpuSurface;
webView.RenderFramesPerSecond = 30;
webView.Navigate("https://example.com");

Rendering Modes

• Embedded keeps the native child view hosted directly for maximum fidelity.
• GpuSurface captures frames into a reusable Avalonia-backed surface.
• Offscreen captures frames offscreen for fully managed composition paths.

Useful runtime APIs:

• webView.SupportsRenderMode(mode)
• webView.IsUsingSyntheticFrameSource
• webView.RenderDiagnosticsMessage
• webView.RenderStatistics and webView.GetRenderStatisticsSnapshot()
• webView.ResetRenderStatistics()
• await webView.CaptureRenderFrameAsync()
• await webView.SaveRenderFrameAsync("artifacts/frame.png")
• await webView.SaveRenderFrameWithMetadataAsync("artifacts/frame.png", "artifacts/frame.json")

Render sidecar metadata includes FrameId, CapturedAtUtc, RenderMode, Origin, PixelDataLength, and PixelDataSha256. Integrity verification requires matching FormatVersion.

Samples

Run the desktop feature explorer:

dotnet run --project samples/NativeWebView.Sample.Desktop/NativeWebView.Sample.Desktop.csproj -c Debug

Run the deterministic smoke matrix used by CI:

dotnet run --project samples/NativeWebView.Sample.Desktop/NativeWebView.Sample.Desktop.csproj -c Debug -- --smoke

Diagnostics and Release Validation

Runtime readiness check:

NativeWebViewRuntime.EnsureCurrentPlatformRegistered();
var diagnostics = NativeWebViewRuntime.GetCurrentPlatformDiagnostics();

if (!diagnostics.IsReady)
{
    throw new InvalidOperationException(
        $"Platform prerequisites are not satisfied for {diagnostics.Platform}.");
}

NativeWebViewDiagnosticsValidator.EnsureReady(diagnostics);

Generate release-facing diagnostics and gate artifacts:

./scripts/run-platform-diagnostics-report.sh --configuration Release --platform all --output artifacts/diagnostics/platform-diagnostics-report.json --markdown-output artifacts/diagnostics/platform-diagnostics-report.md --blocking-baseline ci/baselines/blocking-issues-baseline.txt --comparison-markdown-output artifacts/diagnostics/blocking-regression.md --comparison-json-output artifacts/diagnostics/blocking-regression.json --comparison-evaluation-markdown-output artifacts/diagnostics/gate-evaluation.md --require-baseline-sync --allow-not-ready
./scripts/validate-diagnostics-exit-code-contract.sh --configuration Release --no-build --output-dir artifacts/diagnostics/exit-code-contract --baseline ci/baselines/blocking-issues-baseline.txt --fingerprint-baseline ci/baselines/diagnostics-fingerprint-baseline.txt
./scripts/validate-nuget-packages.sh --package-dir artifacts/packages --markdown-output artifacts/packages/package-validation.md

blocking-regression.json includes deterministic evaluation fingerprints and structured gateFailures metadata for automation and release triage. Package validation verifies every .nupkg and .snupkg, packed README/license files, nuspec metadata, and expected package dependencies.

Documentation

• Hosted docs: wieslawsoltes.github.io/NativeWebVIew
• Getting started: Quickstart
• Control surface: NativeWebView
• Rendering and interop: Render Modes
• Platform notes: Platforms
• Diagnostics and operations: Diagnostics
• API reference: wieslawsoltes.github.io/NativeWebVIew/api

CI and Release

GitHub Actions workflows:

• CI: quality gate, matrix build/test, release pack, diagnostics/report artifacts, and NuGet package validation.
• Release: tag-driven v* pack/publish flow with release notes, diagnostics artifacts, package validation, NuGet push, and GitHub Release publishing.
• Docs: Lunet build and GitHub Pages deployment from site/.lunet/build/www.
• Extended Validation: scheduled/manual Playwright, iOS simulator, and Android emulator validation.

Local release dry run:

dotnet restore NativeWebView.sln
dotnet build NativeWebView.sln -c Release
dotnet test NativeWebView.sln -c Release --no-build
dotnet pack NativeWebView.sln -c Release --no-build -o artifacts/packages
bash ./scripts/validate-nuget-packages.sh --package-dir artifacts/packages --markdown-output artifacts/packages/package-validation.md

Local docs run:

./build-docs.sh
./serve-docs.sh

License

MIT. See LICENSE.