D Donkeh docs
GitHub

Browser

Donkeh.Windowing.Browser is a DOM host, not a renderer. It mounts the same UILab application, then mirrors the reconciled virtual tree into real browser elements. CSS layout, focus, carets, selection, scrolling, form controls and pseudo-classes stay with the browser; the host only keeps the DOM in sync and forwards events to the same delegates a desktop host would invoke.

Bootstrap

DonkehBrowser.RunAsync creates a default Blazor WebAssembly host, registers DomHost as a singleton and starts it. Blazor is used only for its WebAssembly runtime and JavaScript interop. No Blazor components are rendered; UILab owns the UI tree.

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.Services.AddSingleton<DomHost>();

var host = builder.Build();
await host.Services.GetRequiredService<DomHost>().StartAsync();
await host.RunAsync();

DomHost.StartAsync discovers the [AppRoot], imports an embedded JavaScript module, initializes it against the container element, installs the browser permission provider, applies the merged stylesheet and title, subscribes to Renderer.AfterUpdate, mounts the component tree and performs the first sync.

The bridge is an embedded ES module The JavaScript lives in the framework assembly and is imported as a data:text/javascript;base64,... URL. Apps do not need a wwwroot folder, static web asset manifest or _content path. The bridge is a framework concern, not an app packaging detail.

Stable ids and snapshots

Every virtual node gets a stable integer id the first time it is synced. The browser stores the same id on its DOM node, and the C# host keeps both directions:

StatePurpose
Node → intStable identity for patching, even across keyed reorders.
int → NodeResolves the handler and target for an incoming browser event.
NodeSnapshotLast applied tag, text, attribute map, event list, child order and folded text content.
Root child idsTracks the flattened top-level order, with fragments removed from the DOM shape.

A sync walks the live tree, compares each node with its snapshot and emits only changed patches. Fragments have no DOM counterpart, so their children occupy the fragment’s slot in the parent. Nodes that disappear from the walk are removed from the maps and get a remove patch. The DOM node is never recreated just because its position changed.

Renderer.AfterUpdate └── RequestSync (coalesced) └── SyncAsync ├── walk live tree, assign ids on first sight ├── diff text / attrs / events / children / folded text ├── collect removals └── serialize DomPatchBatch → JS apply()

The patch protocol

The patch vocabulary is deliberately small. The browser owns the real DOM; the host only describes how it differs from the last applied snapshot.

PatchEffect
createCreate an element or text node with a stable id.
removeRemove a node and forget its id.
childrenSet the exact child order, inserting and moving existing nodes instead of rebuilding.
textReplace a text node’s value.
contentSet folded element text, or clear it when real children return.
attrsReplace the full attribute map; the bridge preserves its own data-donkeh-* bookkeeping.
eventsReplace the event-name list stored on the element for delegation.

Patches are serialized with a source-generated JsonSerializerContext, which keeps the bridge trim-safe in published WebAssembly builds. The JS side applies them in order and maintains a Map<number, Node>. It also handles the cases where the DOM’s live state must win:

Event delegation

The bridge installs one delegated listener per event family on the container, not one listener per element. Each element carries its event-name list in a data attribute. When a browser event fires, the bridge walks from the physical target up to the nearest element that declares a handler for that event, then calls back into .NET with:

ArgumentMeaning
handlerIdThe nearest virtual element that owns the handler.
targetIdThe deepest virtual node under the physical event target.
eventNameNormalized name such as click, pointerdown, input or change.
x, yElement-local coordinates, scroll deltas or media time, depending on the event.
text, valueKey name, pasted text or control value.

DomHost.HandleEventAsync resolves both ids, updates control state for input/change/Enter and invokes the same delegate shapes as the desktop host: typed event-class handlers, parameterless actions, string handlers and two-float pointer handlers. Each callback builds the matching Event subclass, so a browser handler sees the same ClickEvent, KeyDownEvent or ScrollEvent as a native one. Browser key names are mapped to the desktop names: Space, Left, Right, Up, Down, Escape and single letters. A throwing handler is contained, as it is on desktop.

Scroll and media tracking are opt-in per element. When an element declares scroll, the bridge records its previous offsets and reports the delta. Declaring media events attaches play, pause, ended and timeupdate tracking. Both use passive listeners where possible.

What the browser owns

The browser path intentionally does not run LayoutLab or the OpenGL renderer. It delegates far more to the platform than the desktop host:

ConcernOwner
CSS layout, cascade and pseudo-classesThe browser.
Focus, caret, selection and IMEThe browser’s native form controls.
Scrolling and scrollbarsThe browser; the host consumes scroll deltas.
img, video, audioNative browser elements and media APIs.
canvasThe element exists, but no C# draw callback is wired.
InspectorNot part of the browser host; devtools are desktop-only.

Browser permissions

BrowserPermissionService forwards the supported capabilities to the embedded module, which uses the corresponding browser API:

PermissionBrowser mechanism
CameragetUserMedia({ video: true }); the temporary stream is stopped immediately.
MicrophonegetUserMedia({ audio: true }); same stop-after-check policy.
Locationnavigator.geolocation.getCurrentPosition with a 15-second timeout.
NotificationsNotification.requestPermission(), with existing grant/deny states short-circuited.
Storagenavigator.storage.persist().
MotionDeviceMotionEvent.requestPermission() where available; otherwise true.
ClipboardA clipboard read, which requires a user gesture in most browsers.
Photos, contacts, calendar, BluetoothUnsupported; returns false.
User gesture required Browsers gate camera, microphone, clipboard and some notification prompts on a user gesture. Calling Host.Permissions.Camera() from a button click works; calling it during startup may be rejected even though the same API succeeds later. Failures resolve false rather than throwing.

Why the bridge stays small

Trade-offs and sharp edges

DecisionCost
DOM is authoritativeNative form behaviour is excellent, but the host must reconcile browser-driven value changes back into virtual node state.
No layout engineBrowser CSS and layout do the real work, so desktop-specific layout behaviour and the inspector are unavailable.
Data-URL moduleNo app packaging requirements, but the bridge is loaded as a generated module rather than a cacheable static asset.
Full attribute replacementSimple and correct, but every attribute map crosses the interop boundary when any attribute changes.
Delegated eventsOne listener setup, but every event walks ancestors to find a handler.
No canvas drawingNative canvas exists, but C# callbacks are not bridged; there is no WebGL interop yet.
Permission gesture rulesApps must trigger prompts from interaction; startup checks can fail for reasons the host cannot control.
WASM startup and trimmingThe Blazor runtime is large compared with a native host; source-generated JSON and rooting keep the bridge safe under trimming.

Code tour

FileRead it for…
DonkehBrowser.csThe Blazor WebAssembly bootstrap and singleton host registration.
DomHost.csApp mount, id maps, snapshots, patch generation, event dispatch and control-state reconciliation.
DomPatch.csThe small patch vocabulary and source-generated JSON contract.
wwwroot/donkeh.jsDOM creation/patching, delegated listeners, scroll/media tracking and browser permission APIs.
BrowserPermissionService.csThe Donkeh-to-browser permission mapping and failure policy.

The mental model: desktop paints a tree; the browser mirrors it. UILab remains the source of truth for structure, but the browser is the source of truth for layout, focus, form state and native interaction.