Architecture

Vidra runs a standard web application inside one OS-native WebView. A .NET MAUI host owns the window, native capabilities, and the bridge between JavaScript and C#.

flowchart TB
    subgraph web["WebView (JavaScript)"]
        app["Web application"]
        sdk["Generated TypeScript APIs"]
        transport["Native message transport"]
        app --> sdk --> transport
    end

    subgraph native[".NET MAUI host (C#)"]
        host["Vidra host"]
        bridge["Generated C# contracts"]
        modules["Native modules"]
        host --> bridge --> modules
    end

    os["Operating system APIs"]
    transport <-->|"Typed bridge"| host
    modules --> os

Host model

The same host and bridge run in development and production:

• Development: the WebView loads the Vite development server. vidra dev starts Vite and the native host together with hot reload.
• Production: the WebView loads static assets packaged with the app, or a compatible downloaded web bundle when updates are enabled.

The bridge supports three generated contract directions:

• Native contracts: JavaScript calls methods implemented in C#.
• JavaScript contracts: C# calls handlers implemented in JavaScript.
• Event contracts: C# pushes typed events to JavaScript subscribers.

Start with Call C# from JavaScript and Call JavaScript from C#.

Transport

Vidra prefers the platform’s native WebView message channel:

• WKWebView script messages on Apple platforms.
• WebView2 web messages on Windows.
• AndroidX WebViewCompat web message listeners on Android.

A custom vidra:// scheme is available as a fallback on desktop. On Android, packaged assets are served by WebViewAssetLoader from https://vidra.invalid instead, and the custom scheme is not used. The generated APIs are independent of the selected transport. See Bridge protocol for envelopes, startup negotiation, and errors.

Type safety & code generation

C# declarations are the source of truth for native methods, JavaScript methods, events, and their payload types. The build generates matching C# and TypeScript APIs plus deterministic contract manifests. The host compares manifest fingerprints at startup so incompatible web and native code fail before bridge traffic begins.

Read Code generation for the full pipeline, supported type mapping, generated-file workflow, and diagnostics.

Native access policy

Contract generation describes what the host implements. vidra.config.ts separately declares which native methods and events the WebView may use. Unlisted access is denied, registered capabilities are filtered before being advertised, and filesystem methods also require a symbolic root scope.

The CLI compiles this configuration into an immutable native resource. Its fingerprint joins the two contract fingerprints in startup and web-update compatibility checks. See Control bridge access.

Versioning

All Vidra npm and NuGet packages share one version. Applications have their own version in package.json; vidra build uses it for artifact names and native application metadata.

During the 0.x alpha period, APIs can change between releases. Keep Vidra packages on the same version and rebuild the host whenever generated contracts change.