D Donkeh docs
GitHub

Image

img is not a normal box. It is replaced content: layout must know the image's intrinsic size before it can place anything, and paint must upload, cache and fit the decoded bitmap. Donkeh treats it as a first-class primitive rather than an empty element with a background.

Why it is special

Pipeline stageWhat the image primitive does
Source resolutionResolves a file path, a data: URI or an embedded asset declared with [Image]. A plain path probes disk first, then packed assets; the packed:, embedded: and asset: prefixes force the embedded lookup.
Intrinsic sizingReads the encoded header, or rasterises an SVG, to get pixel dimensions. Layout uses those dimensions to preserve aspect ratio before CSS constraints apply.
Decoding and uploadDecodes RGBA pixels and uploads one OpenGL texture per source. Encoded bytes, decoded dimensions and textures are cached separately.
PaintingDraws the bitmap through the same instanced renderer as shapes and text, applying object-fit and object-position.
CSS backgroundsbackground-image: url(...) shares the same encoded-byte and texture cache, so an image used both as a layer and as img is decoded once.

Decoding on the layout thread would stall every frame, and letting an img collapse to zero height would break flex and grid layouts. That is why the host owns the cache and reports intrinsic dimensions back to layout.

Declare an embedded image

Add the file as an EmbeddedResource, then declare it with [Image]. The attribute is metadata only; the file still has to be embedded in the same assembly.

<ItemGroup>
  <EmbeddedResource Include="Assets/logo.png" />
</ItemGroup>
using Donkeh.UILab;
using static Donkeh.UILab.HtmlHelper;

[assembly: Image("Assets/logo.png")]

[AppRoot(Width = 1000, Height = 700, Title = "My app")]
public sealed class App : Component
{
    public override Node Render() =>
        Img(new()
        {
            Src = "packed:Assets/logo.png",
            Alt = "Donkeh logo",
            Attributes = new Dictionary<string, string>
            {
                ["width"] = "160",
                ["height"] = "160"
            }
        });
}
Path matching A declaration may be matched by full path, a suffix or its bare file name. Case is ignored, and folder-aware matching prevents Other/logo.png from resolving to Assets/logo.png. When two declarations match, the result is treated as unavailable instead of picking one arbitrarily.

Supported sources

SourceExampleNotes
Relative or absolute fileAssets/logo.pngProbed on disk first. Relative paths resolve against the process working directory at first use.
Embedded assetpacked:Assets/logo.pngUses the [Image] declaration and manifest resource in a loaded assembly.
Data URIdata:image/png;base64,...Decoded directly, with no disk access.
SVGAssets/icon.svgRasterised on first use, whether it comes from disk, a data URI or an embedded resource.

Sizing and fitting

The intrinsic size comes from the decoded pixels, not CSS pixels. If the header cannot be read, the width and height attributes are used. The user-agent sheet gives images max-width: 100%, so a large image shrinks with its container while preserving aspect ratio.

.hero-image {
    width: 100%;
    height: 240px;
    object-fit: cover;
    object-position: center 35%;
    border-radius: 18px;
}

object-fit accepts fill, contain, cover, none and scale-down. cover crops by shrinking the UV rectangle rather than clipping the quad; contain and scale-down centre the image in the box.

Cache behaviour

BehaviourDetail
No evictionEvery successfully used source stays in memory until the window is disposed.
No file watchingReplacing a file on disk does not refresh the image. Restart the window, or use a new source string.
Failures are cachedA missing or corrupt source resolves to a zero texture and is not retried every frame.
Frame-thread uploadTextures are created and deleted on the render thread. Intrinsic-size queries can happen earlier.

Browser host

On WebAssembly the tree is mirrored to a native img, and the browser owns loading, decoding and layout. Use a URL or data: URI there. The packed: and embedded: source forms are for the desktop and Android GL hosts, which implement the packed-asset resolver.

Need the bytes? Use Image.Load("Assets/logo.png") or Image.TryGetBytes(...) when you need the encoded file for an upload, a custom cache or a non-img path. The element pipeline uses the same declarations internally.