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.

A custom vidra:// scheme is available as a fallback. 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.

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.