Inspector
Donkeh.Inspector is the in-app devtools panel. It is not a
separate viewer and it does not clone the application tree: it renders a
normal UILab component over the live mounted nodes, uses the same compiled
stylesheet and the same layout result, and queues every edit back to the
frame thread that owns the app.
Three pieces
| Piece | Role |
|---|---|
DevToolsState | Shared mutable state: visibility, dock, tabs, selection, hover, expanded nodes, stylesheet table, layout result, performance samples and the deploy service. |
InspectorPanel | A normal Component that renders the toolbar, tree, styles, animations, performance and deploy tabs from that state. |
DeployState / DownloadServer | Project discovery, build targets, process execution, logs and the local HTTP download endpoint. |
The window owns one DevToolsState and gives the panel its own
Renderer, LayoutEngine, renderer context and
display list. A docked panel reserves space from the app viewport; a
standalone panel runs in its own native window on a separate thread and
queues edits back to the frame thread.
Shared state and refresh
The host updates DevToolsState from the frame loop and bumps a
single version counter. InspectorPanel.Tick() polls that version
and schedules a render only when it changed, so an idle inspector costs
almost nothing. Selection, hover and expansion use node identity
(ReferenceEqualityComparer), because nodes do not define value
equality.
Stylesheet and DOM mutations never run directly from the panel. They are
queued through QueueEdit and drained by the host before layout.
That is essential in window mode: the panel thread and the render thread are
different, and the table and box tree are not thread-safe.
Elements tab
The tree is the logical tree, not just the live DOM shape. It includes component and provider rows with their rendered output nested underneath, so a developer can see why an element exists. Fragment nodes are followed through; on first open the tree expands down to the first branching point, at most eight levels.
| Feature | Behaviour |
|---|---|
| Selection / hover | Node identity, with a highlight overlay drawn by the host over the selected box. |
| Inspect mode | Pointer clicks pick the app element under the cursor instead of interacting with the app. |
| Expansion | A set of expanded nodes pruned every render when nodes unmount; selection can scroll itself into view. |
| Component rows | Show the component type and its current output kind without pretending to be an element. |
| Text rows | Show the text content and its node identity. |
The Styles pane matches rules with the same DataTable and
RendererContext the app used, groups them by origin and selector,
and reverses the list so the strongest group is first. Rule ranges recorded
at stylesheet rebuild time label each match as user-agent,
author #N or devtools.
Computed values come from the real LayoutResult, not from a
second style pass. If the element has no box, the pane says so instead of
inventing values. The grouping is cached by element identity, element
revision, state version and table instance, because matching, selector text
and declaration interning are the expensive parts of the pane.
Editing
Declarations are edited in place. Property changes commit on Enter or focus loss; value changes commit live when the text looks complete and again on change. Pasting into the add row parses one or more declarations, or a whole rule block, and applies them to the same group. Edits are queued as table mutations, so the next app layout sees them through the normal cascade.
The inspector can also create an element-level style rule for the selected
node and add declarations to it. It does not restructure the application
tree. Its own highlight and selection markers are private
data-* attributes on the live elements, not a second app tree.
Colour picker
ColorPreview converts between CSS colour text and the engine’s
packed 0xAARRGGBB. It understands #rgb,
#rgba, #rrggbb, #rrggbbaa,
comma/space/slash rgb()/rgba() and a small named
set. Unsupported syntax never throws; it simply does not get a swatch.
The picker is a modal popup with a 110 px hue/saturation wheel, a live hex field and preset swatches. Pointer angle selects hue, distance selects saturation, and value stays at full brightness. Every move queues a rule value edit, but identical interned values are skipped. Preset rows are laid out eight per row because the engine has no inline styles.
Performance tab
The host samples frame, layout, render and UILab update timings, frame count, instruction count, box count, node count, CPU, managed/working/private memory, thread count and GC generations. Sampling is throttled: the window updates roughly four times per second, and the panel refreshes about once per second while this tab is active.
| Surface | Content |
|---|---|
| Cards | FPS, CPU, managed/working set, GC counts, layout, render, update and total frames. |
| Graphs | Frame history at a 33 ms scale, layout and render history at 16 ms scales. |
| Bars | Quantised to 120 height classes; no inline styles or canvas drawing. |
| History | Fixed-size ring buffers; the panel reads spans, it does not sample on the UI thread. |
Animations tab
Keyframes are read directly from the DataTable. Frames are
grouped by animation name in first-seen order, then stops are grouped by
selector text such as from, 50% or to.
Declarations are displayed from interned property and value ids. The selected
animation is part of DevToolsState; unknown selections fall back
to the first group.
Deploy tab
DeployState discovers the application project, derives targets
from its target frameworks and provides build buttons plus logs. Discovery
starts beside the entry assembly, then the base and current directories, and
walks upward. A project whose name matches the entry assembly wins when a
folder contains several projects.
| Target | Command / output |
|---|---|
| Desktop | dotnet build -c Release -f <tfm> -o builds/desktop |
| Android | dotnet build with APK packaging, then copy the signed APK to builds/android. |
| WebAssembly | dotnet publish -f net10.0-browser -o builds/wasm, then verify index.html. |
| Custom | A DeployTarget delegate receives project paths, output directory, configuration and a log sink. |
Builds run on a worker and are sequential, because concurrent
dotnet build processes share intermediate directories. A busy
flag rejects overlapping starts; every target reports its own state, error,
duration, timestamp and trimmed log. Build output notifications are
throttled to a 200 ms window so a noisy build cannot monopolise the frame
loop.
Download server
The Deploy tab can expose the build directory over a tiny HTTP server. It
uses a raw TcpListener instead of HttpListener, so
no Windows URL reservation or administrator rights are needed. It binds all
IPv4 interfaces, supports GET, HEAD and a
POST /upload endpoint, lists the build directory, streams large
files, rejects path traversal and closes each connection after one request.
Uploads accept raw image bodies up to 32 MB, restrict the extension to known
image types and write into {project}/debug; the generated index
page exposes the drop area and posts one file per request.
debug folder. Stop it when not deploying;
changing the root stops a running server.
Host integration
The host compiles the inspector stylesheet after the user agent and author
sheets, so its rules win source-order ties. Dock sizes are generated as
dt-dockh-N and dt-dockw-N classes rather than
inline styles. DevToolsDock.Window opens a separate native
window on an STA thread and shares the same state; edits are queued and
drained on the app frame thread.
Hiding the inspector exits inspect mode, closes the colour picker and removes the docked viewport reservation. Disabling devtools removes its shortcut and skips its stylesheet, layout engine and overlay submission entirely.
Trade-offs and sharp edges
| Decision | Cost |
|---|---|
| Live tree, no clone | Edits and selection reflect the real app immediately, but the inspector must respect node lifetimes and thread ownership. |
| Panel is a UILab component | Dogfoods the engine and reuses all layout/paint code, but every inspector layout costs a second engine pass. |
| Generated utility classes | Works without inline styles, but dock sizes and graph heights require a finite class table. |
| Heuristic project discovery | Zero configuration for normal apps; a published app with no project files simply shows an empty Deploy tab. |
| Sequential builds | Avoids MSBuild directory races, at the cost of build-all latency. |
| Raw TCP download server | No elevation or URL reservations, but no TLS, authentication or HTTP/1.1 keep-alive. |
| Throttled sampling | Keeps the inspector cheap, but the graphs are a coarse diagnostic view, not a profiler trace. |
| Desktop-oriented | Window, docking and local build/deploy features assume the native host; the browser host does not include this inspector. |
Code tour
| File | Read it for… |
|---|---|
DevToolsState.cs | Shared state, tabs, selection, expansion, stylesheet ranges, edit queue, versioning and performance stats. |
InspectorPanel.cs | Toolbar, tree, styles grouping and editing, colour picker, animations, performance dashboard and deploy UI. |
InspectorStyles.cs | Panel CSS, dock sizes and generated height/width utility classes. |
ColorPreview.cs | CSS colour parsing/formatting and HSV helpers. |
DeployState.cs | Project discovery, target construction, dotnet builds, logs, throttled notifications and download-server wiring. |
DownloadServer.cs | Raw TCP HTTP server, directory listing, file streaming and traversal rejection. |
The mental model: the inspector is a second UILab application that observes the first one through shared state. It can read the live tree, compiled table and layout result cheaply, but it never owns them; edits go back through the host’s queue so the real application remains the source of truth.