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:
| Type | Why it lives in Hosting |
|---|---|
AppRootAttribute | Declares the root component and all host settings in one place. |
AppRootDefinition | Carries the discovered root factory, merged stylesheet and settings to any host. |
WindowSettings | Platform-neutral window description; the native host applies it. |
RenderPath | Lets settings select direct or indirect rendering without referencing the GL renderer. |
DevToolsDock | Lets settings choose an inspector position without referencing the inspector implementation. |
Host / HostPermissions | The 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.
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.
- The type must derive from
Component. - It must not be abstract.
- 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.
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.
| Group | Fields |
|---|---|
| Geometry | Width, Height, Min/MaxWidth, Min/MaxHeight, Resizable, Frameless, FullScreen, Maximized, CornerRadius |
| Presentation | VSync, TargetFramesPerSecond, ClearColor, Samples, RenderPath, Transparent, TopMost |
| Identity | Title, Icon |
| Scaling | DpiScale; zero derives the ratio from the framebuffer, mobile hosts set display density explicitly |
| Developer tools | EnableDevTools, 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.
}
| Mechanism | Behaviour |
|---|---|
Host.Permissions | Shared HostPermissions instance with camera, microphone, location, notifications, photos, storage, contacts, calendar, Bluetooth, motion and clipboard helpers. |
| Grant cache | A granted result is cached for the host lifetime; a denial is not, so the app can retry after a settings change. |
| In-flight deduplication | Concurrent requests for the same permission share one platform prompt. |
| Cancellation | A cancelled prompt resolves to false rather than throwing. |
| Provider replacement | Host.UsePermissions(service) installs the platform provider and clears cached grants; passing null restores the default. |
| Default provider | Desktop grants and lets the device API enforce access; mobile, browser and unknown platforms return false until their host installs a real provider. |
| Failure policy | Unknown permissions, provider exceptions and cancelled prompts all fail closed. |
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
| Decision | Cost |
|---|---|
| Attribute + reflection discovery | Zero configuration, but trimming or aggressive AOT can remove the root type or its constructor; keep the root type rooted. |
| One root per application | Simple entry points, but multi-window or multi-root apps need their own host layer. |
| Public parameterless constructor | Cacheable construction, but no constructor injection or DI lifetime model. |
| Stylesheet loading during discovery | Avoids per-frame reflection, but scans loaded assemblies and reads resources at startup. |
| Global static permission provider | Easy app API, but process-wide; replacing it affects every consumer at once. |
| Mutable settings struct | Allocation-free composition, but default has surprising sentinel behaviour. |
| Host-agnostic enums in Hosting | Avoids implementation references in settings, at the cost of slightly surprising namespaces. |
| Legacy app contract retained | Keeps older projects compiling, but there are now two discovery paths to understand. |
Code tour
| File | Read it for… |
|---|---|
Hosting/Source/AppRootAttribute.cs | Every root setting and the conversion to WindowSettings. |
Hosting/Source/AppRootLocator.cs | Entry-assembly-first discovery, validation and legacy fallback. |
Hosting/Source/AppRootDefinition.cs | The object every host consumes: type, settings, styles and root factory. |
Hosting/Source/WindowSettings.cs | Native window fields, defaults, sentinels and creation-time semantics. |
Hosting/Source/AppModel.cs | The legacy IDonkehApp/DonkehApp contract. |
Hosting/Source/Host.cs | Platform predicates and permission-provider installation. |
Hosting/Source/HostPermissions.cs | Grant caching, in-flight deduplication and failure policy. |
Hosting/Source/RenderPath.cs / DevToolsDock.cs | The 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.