┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Avalonia      │    │  Blazor Server   │    │     Photino     │
│   (Desktop      │◄──►│  (Web UI &       │◄──►│   (WebView      │
│    Framework)   │    │   Components)    │    │    Hosting)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
        ▲                        ▲                        ▲
        │                        │                        │
        ▼                        ▼                        ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Native OS     │    │    MudBlazor     │    │   File System   │
│   Integration   │    │   (Material UI)  │    │     Access      │
└─────────────────┘    └──────────────────┘    └─────────────────┘

In .NET 10, blazor.web.js ships in the Microsoft.AspNetCore.App.Internal.Assets NuGet package. Its MSBuild targets register it as a static web asset — but only for OutputType=Exe projects using Microsoft.NET.Sdk.Web. Desktop apps use OutputType=WinExe, so the framework skips them entirely regardless of SDK choice.

CheapAvaloniaBlazor supplies the file itself, in three layers. Each one covers a case the layer above it cannot reach, and the app only needs one of them to succeed.

1. Build and publish (PackageReference consumers). Build/CheapAvaloniaBlazor.targets adds the script as Content targeting wwwroot/_framework/blazor.web.js, sourced from the restored Microsoft.AspNetCore.App.Internal.Assets package. Because it is Content and not a copy into the output folder, it survives dotnet publish and travels to machines with no SDK and no package cache. This is the normal path.

2. NuGet cache extraction (developer machines, ProjectReference). BlazorFrameworkExtractor runs at startup, picks the cached version matching the running runtime, and copies it into wwwroot/_framework/. MSBuild props and targets from a package are not imported through a ProjectReference, so the samples in this repo rely on this layer.

3. Embedded copy (everything else). A copy of the script is baked into CheapAvaloniaBlazor.dll at build time. When layers 1 and 2 both come up empty the extractor writes it out to wwwroot/_framework/, and if the install directory is read-only a middleware serves it straight from the assembly at /_framework/blazor.web.js. The DLL always ships with the app, so this layer cannot be missing.

UseStaticFiles() serves whatever landed on disk; the embedded middleware sits directly behind it and only answers when nothing else did.

The embedded copy is frozen at the version CheapAvaloniaBlazor was packed against, so on layer 3 an app running a newer 10.0.x runtime gets a slightly older bootstrapper. That is fine: blazor.web.js negotiates over a protocol that is stable across a major version. Layers 1 and 2 always match the app's own package graph, and layer 3 only runs when neither could supply anything at all.

Before 3.4.1 only layer 2 existed. A published app on a clean machine has no NuGet cache, so the script 404'd and the window rendered blank white with no error — the app was running and serving its HTML the whole time.

The JS bridge that carries every desktop interop call is a static web asset of this library, served at _content/CheapAvaloniaBlazor/cheap-blazor-interop.js. dotnet publish copies it into the app's wwwroot/_content/, which is the normal path and works.

It is also embedded in CheapAvaloniaBlazor.dll and served from there when the file is not on disk, for the same reason blazor.web.js is. The static web asset chain has more failure modes than it appears: a manifest recording absolute paths into a machine that no longer exists, a consumer excluding assets, an install where wwwroot did not survive. When it breaks, MapStaticAssets throws FileNotFoundException and returns 500, or answers 200 with a zero-length body — never a 404 anything downstream could recover from.

Third-party _content assets such as MudBlazor's CSS and JS have no equivalent safety net. This library has no copy of them to serve, so they must be on disk.

Every deployment failure in this area looks identical from the outside: a blank white window, no controls, no error dialog, nothing in a network trace that reads as broken. To stop that being a guessing game, the host fetches its own root document once at startup, follows every local _framework/ and _content/ reference in it, and logs an error naming any that come back failing or empty. External URLs (Google Fonts and the like) are skipped — an offline machine is not a broken app.

If the log names an asset, the deployment is the thing to look at:

A manifest pointing at paths that do not exist used to kill the process at startup with no window and no message. It is now caught and logged, and the app runs on whatever is reachable.

Minimize to Tray uses Windows user32.dll P/Invoke to fully hide the window. On Linux/macOS, the window falls back to a regular minimize (taskbar icon stays visible). System Tray behavior on Linux depends on the desktop environment's support for Avalonia's TrayIcon API.

MyDesktopApp/
├── Program.cs                 # Application entry point
├── Components/
│   ├── App.razor             # HTML document root (loads scripts, CSS, renders Routes)
│   ├── Routes.razor          # Blazor router configuration
│   └── MainLayout.razor      # Main application layout
├── Pages/
│   ├── Index.razor           # Home page
│   └── Files.razor           # File management page
├── wwwroot/                  # Static web assets
│   └── css/
└── Services/                 # Your business logic
    └── IMyService.cs