D Donkeh docs
GitHub

Hosting

Donkeh.Hosting is the small, platform-neutral contract every host shares. It does not open windows or render anything. It discovers the application root, carries the settings that native hosts need, and exposes the platform flags and awaitable permission surface that app code can use without referencing a specific host implementation.

What belongs here

The package deliberately has no dependency on Silk.NET, OpenGL, LibVLC or a native window. That is what lets the same app assembly compile for desktop, Android and the browser. A few types live here even though their namespaces belong to other packages, precisely so settings can describe a platform feature without pulling the implementation into every consumer:

TypeWhy it lives in Hosting
AppRootAttributeDeclares the root component and all host settings in one place.
AppRootDefinitionCarries the discovered root factory, merged stylesheet and settings to any host.
WindowSettingsPlatform-neutral window description; the native host applies it.
RenderPathLets settings select direct or indirect rendering without referencing the GL renderer.
DevToolsDockLets settings choose an inspector position without referencing the inspector implementation.
Host / HostPermissionsThe app-facing platform and permission API.

The attributed app root

An application declares one component:

using Donkeh.Hosting;
using Donkeh.UILab;
using static Donkeh.UILab.HtmlHelper;

[AppRoot(
    Width = 1180,
    Height = 760,
    Title = "My app",
    EnableDevTools = true,
    Frameless = true,
    CornerRadius = 9f)]
public sealed class App : Component
{
    public override Node Render() =>
        Div(new() { ClassName = "app" });
}

The attribute is the whole application contract. It carries window size, title, frame style, VSync, frame cap, clear colour, MSAA samples, render path, DPI override, resizability, min/max size, icon, topmost and transparency flags, inspector settings, and an optional native corner radius. ToWindowSettings() converts those constants into the mutable struct a native host consumes.

Attribute arguments are constants C# attributes cannot take object initializers, so settings are named properties. CornerRadius uses float.NaN to mean “derive the window shape from CSS”; zero means a square frameless window. Zero is also a sentinel for several native settings, so prefer WindowSettings.Default over default when building settings in code.

Discovery

AppRootLocator.Find() is the single discovery point used by every platform entry point. It checks the entry assembly first, then every loaded assembly. The first type with [AppRoot] wins.

  1. The type must derive from Component.
  2. It must not be abstract.
  3. It must expose a public parameterless constructor.

Failures are explicit: a missing root, a non-component type, or a missing constructor throws an InvalidOperationException with a message that names the type. The attribute is not inherited, so a derived component does not accidentally become a second root.

For migration, the locator falls back to the legacy [DonkehApp]/IDonkehApp contract when no [AppRoot] is present. New applications should use the attribute; the legacy path exists so older projects keep compiling.

The app definition

Discovery produces an AppRootDefinition: the component type, the converted WindowSettings, the merged author stylesheet and a factory that creates the root component node. The stylesheet is loaded during definition construction through Stylesheet.Load(), so reflection and embedded-resource reads happen once at startup rather than per frame.

AppRootLocator.Find() └── AppRootDefinition ├── ComponentType [AppRoot] type, or null for legacy ├── Settings WindowSettings copy ├── Styles merged embedded CSS └── CreateRoot() _.C(componentType)

Hosts consume the definition differently but share the same object. The desktop/browser entry point mounts CreateRoot() into a Renderer and passes Settings to the window. The Android activity discovers the same definitions and applies its own surface, density and lifecycle rules.

Window settings

WindowSettings is a mutable struct so it can be composed with an object initializer and copied into the native window without a heap allocation. Defaults are desktop-oriented: 1280 × 800, resizable, not VSync, 144 FPS cap, opaque white clear colour, 4× MSAA, inspector enabled at the bottom.

GroupFields
GeometryWidth, Height, Min/MaxWidth, Min/MaxHeight, Resizable, Frameless, FullScreen, Maximized, CornerRadius
PresentationVSync, TargetFramesPerSecond, ClearColor, Samples, RenderPath, Transparent, TopMost
IdentityTitle, Icon
ScalingDpiScale; zero derives the ratio from the framebuffer, mobile hosts set display density explicitly
Developer toolsEnableDevTools, DevToolsPosition

Settings are copied when the native window is constructed. Changing a copy afterwards has no effect on the live window, and some values are only applied at creation. A default(WindowSettings) bypasses the constructor and produces a fixed, non-resizable window with inspector off and an uncapped frame rate — not the documented defaults.

Render path and devtools placement

RenderPath.Auto uses indirect submission when the driver exposes the required extensions and falls back to direct instanced draws otherwise. Indirect bakes geometry into one GPU-resident buffer and submits indirect commands; Direct keeps the same geometry but issues one instanced draw per batch, which is useful for benchmarking or isolating driver problems. Browser hosts ignore the value.

DevToolsDock selects bottom, right or a separate native inspector window. The enum lives in Hosting so settings can reference it without forcing every consumer to reference Donkeh.Inspector.

Platform flags and permissions

Host exposes simple platform predicates: IsAndroid, IsIOS, IsWindows, IsMac, IsLinux, IsWeb, IsDesktop, IsMobile, IsBrowser and a friendly PlatformName. These are safe on every target and require no host setup.

Permission checks are intentionally asynchronous because mobile and browser platforms may need a system prompt:

using Donkeh.Hosting;

if (Host.IsAndroid)
{
    // Android-only setup.
}

if (await Host.Permissions.Camera())
{
    // Open the camera.
}
MechanismBehaviour
Host.PermissionsShared HostPermissions instance with camera, microphone, location, notifications, photos, storage, contacts, calendar, Bluetooth, motion and clipboard helpers.
Grant cacheA granted result is cached for the host lifetime; a denial is not, so the app can retry after a settings change.
In-flight deduplicationConcurrent requests for the same permission share one platform prompt.
CancellationA cancelled prompt resolves to false rather than throwing.
Provider replacementHost.UsePermissions(service) installs the platform provider and clears cached grants; passing null restores the default.
Default providerDesktop grants and lets the device API enforce access; mobile, browser and unknown platforms return false until their host installs a real provider.
Failure policyUnknown permissions, provider exceptions and cancelled prompts all fail closed.
The default is not a security model The desktop default answers “granted” because .NET has no common runtime permission prompt. The actual camera, microphone or filesystem operation can still fail. Mobile and browser hosts are expected to replace the provider during startup; until they do, permission checks return false.

Startup cost and steady state

Hosting is almost entirely startup code. Discovery reflects over loaded assemblies once; the definition loads and merges stylesheets once; window settings are copied once when the native window is created. After that, platform flags are simple runtime checks and permission calls are cached or deduplicated, so the package adds no per-frame work to the render loop.

Trade-offs and sharp edges

DecisionCost
Attribute + reflection discoveryZero configuration, but trimming or aggressive AOT can remove the root type or its constructor; keep the root type rooted.
One root per applicationSimple entry points, but multi-window or multi-root apps need their own host layer.
Public parameterless constructorCacheable construction, but no constructor injection or DI lifetime model.
Stylesheet loading during discoveryAvoids per-frame reflection, but scans loaded assemblies and reads resources at startup.
Global static permission providerEasy app API, but process-wide; replacing it affects every consumer at once.
Mutable settings structAllocation-free composition, but default has surprising sentinel behaviour.
Host-agnostic enums in HostingAvoids implementation references in settings, at the cost of slightly surprising namespaces.
Legacy app contract retainedKeeps older projects compiling, but there are now two discovery paths to understand.

Code tour

FileRead it for…
Hosting/Source/AppRootAttribute.csEvery root setting and the conversion to WindowSettings.
Hosting/Source/AppRootLocator.csEntry-assembly-first discovery, validation and legacy fallback.
Hosting/Source/AppRootDefinition.csThe object every host consumes: type, settings, styles and root factory.
Hosting/Source/WindowSettings.csNative window fields, defaults, sentinels and creation-time semantics.
Hosting/Source/AppModel.csThe legacy IDonkehApp/DonkehApp contract.
Hosting/Source/Host.csPlatform predicates and permission-provider installation.
Hosting/Source/HostPermissions.csGrant caching, in-flight deduplication and failure policy.
Hosting/Source/RenderPath.cs / DevToolsDock.csThe platform-neutral enums settings expose.

The mental model: Hosting is the layer that lets a host and an app agree on what an application is. The app declares a root and settings; Hosting discovers them, loads its styles, and hands a platform-neutral definition to whichever native or browser host is running.