Skip to content

Runic SDK 0.22.0

Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 18 Nov 20:38
a2a1f8d

Runic SDK 0.22.0

Install matching 0.22.0 packages from NuGet and npm;
Runic.Application.Views.CsWebUi is 0.22.0-preview.1.
Tested with Runic Translations 0.14.0 and Runic Command Line 0.13.0.

0.22.0 makes published applications smaller without taking anything away. A
NativeAOT size pass measured what Runic adds to an executable and cut it on
every host: the size fixture's Runic Desktop host on linux-x64 goes from
14.56 MB to 10.61 MB, and its CS-WebUI application from 10.71 MB to 7.47 MB,
now that the CS-WebUI window serves blobs from Runic's own loopback server
instead of HttpListener. Each bridged ViewModel costs 16.7 KB instead of
0.21's 56.3 KB (#1134, #1138, #1144): generated Bridges share their codecs and
command runners per assembly and describe their members as data. Generated
TypeScript and the wire protocol stay byte for byte the same. Views and members
that only development needs can be marked [RunicDevelopmentOnly], and a
trimmed or NativeAOT publish then leaves them out (#1109).

Framework-dependent publishes get smaller too. A RID-specific publish of a Runic
Desktop application ships only its own operating system's platform assemblies
(1.9 to 3.4 MB less, 4.1 MB with ReadyToRun), with an opt-out for code that
needs the others. Single-file publish of a Views application now works, and
CI's size budgets now gate the framework-dependent publish too. The fixtures
they measure, built inside the repository, now publish exactly what a package
consumer's publish holds (FD5, #1151); applications see no change from that.
The host-named copies of the Views client script, runic-desktop-views.js and
runic-cswebui.js, are deprecated: they log a console warning in 0.22, and 0.23
removes them.

Visual Studio debugs a Runic application end to end through Runic DevKit, the
Runic editor extensions for Visual Studio and VS Code, which share that name
from 0.22. Debug the Window starts the Window under the .NET debugger and
attaches the JavaScript debugger to the page. The development server's source
maps name absolute files, so breakpoints in Frontend/src bind. F5 builds after
a frontend-only edit, and an IDE can stop dotnet runic dev gracefully.
CS-WebUI pages open a Chrome DevTools Protocol port for IDE debuggers in
Development. On Linux, VS Code's js-debug no longer leaves the WebKitGTK page
stopped after a reload or at a breakpoint it never set (#1108, #1139), and
dev names whatever holds port 9222 (#1065). The side panel and the close drain
are stable.

Runic Translations 0.14.0 was published on its own ahead of the train, and
runic-sdk adopts it in 0.22. The 0.22 release train is runic-sdk 0.22.0 and the
Runic editor extensions 0.22.0, with Translations 0.14.0; Runic Command Line
stays at 0.13.0. Upgrading from 0.21 lists what an
application changes, and the
migration guide
collects it.

Highlights

  • Smaller NativeAOT executables: the size fixture's Runic Desktop host on
    linux-x64 goes from 14.56 MB to 10.61 MB and its CS-WebUI application from
    10.71 MB to 7.47 MB, and a bridged ViewModel costs 16.7 KB instead of 56.3 KB.
    Generated TypeScript and the wire protocol are unchanged
    (Behaviour and output changes,
    Fixes).
  • Development-only views and members:
    [RunicDevelopmentOnly] keeps a mock-control or diagnostics view, or single
    properties and commands, out of trimmed and NativeAOT publishes, while builds,
    dotnet run and the debugger keep them.
  • Smaller framework-dependent publishes: a RID-specific publish of a Runic
    Desktop application ships only its own operating system's platform assemblies
    (1.9 to 3.4 MB less), single-file publish of a Views application works, and
    CI gates the framework-dependent size
    (Behaviour and output changes,
    Fixes).
  • Visual Studio debugging through Runic DevKit: Debug the Window starts the
    Window under the .NET debugger with the page in the JavaScript debugger,
    breakpoints in Frontend/src bind, F5 builds after a frontend-only edit, and
    an IDE can stop dotnet runic dev.
    CS-WebUI pages attach to a JavaScript debugger
    too (Runic DevKit).
  • js-debug on Linux: the WebKitGTK page no longer stays stopped after a reload,
    a Window restart or at a breakpoint the debugger never set, and dotnet runic dev names what holds port 9222 (Fixes).
  • The side panel and the close drain are stable,
    and the host-named Views client scripts runic-desktop-views.js and
    runic-cswebui.js are deprecated, for removal in 0.23
    (Upgrading from 0.21).

Upgrading from 0.21

Update every Runic NuGet and npm package to 0.22.0 together and rebuild, so that
the generated clients and Bridges are regenerated. The Views protocol and the
generated TypeScript are unchanged, so a 0.21 page and a 0.22 host still connect,
and Bridges that 0.21's generator wrote keep working with the 0.22 runtime.

Most applications change nothing. A page that loads runic-desktop-views.js or
runic-cswebui.js loads runic-views.js instead, and code that imports
onBridgeDraining from @runic-artifex/views/experimental imports it from the
root entry. Both old forms still work in 0.22 and are removed in 0.23. A Runic
Desktop application whose own code calls another operating system's
Runic.Platform API reads
the RID-specific publish change. An application
that uses Runic Translations moves to 0.14.0. Update Runic's editor extensions to
0.22.0 too: Runic DevKit for Visual Studio debugs the Window, and the VS Code
extension's ID is now runic-artifex.runic-devkit.

  • Deprecated: the host-named copy of the Views client script,
    runic-desktop-views.js and runic-cswebui.js (D072.11).
    The host packages
    copy their Views client into www/ as runic-views.js and, until 0.23, also
    under the host's own name. In 0.22 a page that loads the host-named copy still
    works, but logs one console warning; 0.23 removes the copy, which saves 5 KB
    (Runic Desktop) or 21 KB (CS-WebUI) per publish. Load runic-views.js
    instead: <script src="runic-views.js"></script> after webui.js. The
    templates already do. A project that references more than one host, such as
    Runic Desktop and CS-WebUI, sets RunicApplicationHost (desktop or
    cswebui), or the build copies no runic-views.js (warning
    RUNICBRIDGE019). An application that keeps its own copy of the script under
    the old name gets the same warning; rename that copy to runic-views.js.
  • Deprecated: onBridgeDraining from @runic-artifex/views/experimental.
    The close drain's flag is a root export of @runic-artifex/views from 0.22
    (the side panel and the close drain are stable).
    The old import still works in 0.22: ./experimental re-exports the same
    function, marked @deprecated, so editors strike it through. 0.23 removes it;
    import onBridgeDraining from @runic-artifex/views. Remove RUNICDESK104
    and RUNICDESK105 suppressions too, which no longer do anything.
  • Runic Translations 0.14.
    Runic.Application.Views.Translations requires Runic Translations
    [0.14.0, 0.15.0), so an application that uses it moves every Translations
    package, NuGet and npm, to 0.14.0. The template pins Translations 0.14.0 three
    ways: the dotnet-runic-translations tool, Runic.Translations and
    .Build, and @runic-artifex/vite-plugin-runic-translations; dotnet runic doctor checks for 0.14.0. Its catalog is generated by Translations 0.14 for
    RMF2 runtime ABI 4 (DEFLATE-compressed locale data and one message table), so
    it needs the 0.14 runtime: keep Runic.Translations and
    Runic.Translations.Build at the same version. A NativeAOT CS-WebUI
    application with Runic's own text is about 350 KB smaller on linux-x64
    (aot/views-translations/executable-bytes: 8,898,760 to 8,543,240 bytes).
    Translations 0.14 deprecates overriding Command Line text from your own
    catalog (warning RTR0107) and adds language server protocol 2; neither
    needs a change in Runic SDK. Runic Command Line stays at 0.13. See the
    Translations 0.14.0 notes.

Behaviour and output changes

  • dotnet runic doctor's compatibility-set check warns when a Runic Command
    Line or Runic Translations package is older than the version of the release
    train, which the warning names, or of another minor version; it ignored them
    before (#1087). A later patch of the train's minor version passes.

  • Generated Bridges describe their members as data, so a bridged ViewModel costs about a third of 0.21's. A
    Bridge used to create its descriptors (about 30 objects and 65 delegates for a typical ViewModel) in its constructor,
    for every Bridge instance, with a lambda per member and operation. Now each Bridge holds a table with one record per
    member and answers for its members in one switch per operation. A reader that the generator writes once per
    assembly (RunicShared.Tables.Bridge.g.cs) reads the table on the first Bridge of a ViewModel type and creates the
    same descriptors, which every later Bridge of the type shares. In the research fixture of #1109 a ViewModel costs
    16.7 KB instead of 32.5 KB on linux-x64 (56.3 KB in 0.21); with the shape the scaling suite's aot-size fixture had
    in 0.21, 8.1 KiB instead of 17.3 KiB (25.4 KiB in 0.21), and its Bridge has 19 methods instead of 50 (80 in 0.21).
    The fixture now has every member kind: 14.1 KiB and 34 methods per ViewModel instead of 28.5 KiB and 80, and it
    gates the 34 methods (D072.15). The table reader adds 17 to
    29 KB once per bridged assembly. The first Bridge of a type is created faster (0.74 ms instead of 2.1 ms in a
    JIT benchmark, compilation included), and each further one allocates 15.3 KB instead of 17.8 KB. Descriptor order,
    names and wire names, the generated TypeScript and the wire protocol are unchanged, and Bridges an earlier generator
    wrote keep working. The Runic generator no longer calls ToolkitCommandInspector.DescriptorFor; the method keeps its
    signature and the descriptor it writes still compiles. Part of #1109.

  • Generated Bridges share their codecs and getters, so each bridged ViewModel adds less to a NativeAOT executable.
    The generator now writes each distinct wire codec once per assembly, in RunicShared.Codecs.Bridge.g.cs beside the
    Bridges, instead of one codec class per member, command input or result and interaction value in every Bridge. A
    DTO's codec calls the codecs of its members, so a type used in several places has one codec. Bridges name their
    codecs with using aliases (using TitleValueCodec = …RunicBridgeCodecs.String;). Each property also has one
    getter, shared by its descriptors and its data subscription. In a research fixture with a realistic ViewModel
    shape a ViewModel costs 43.1 KB instead of 56.3 KB on linux-x64 (−23 %); in the scaling suite's aot-size fixture
    20.8 KB instead of 25.5 KB. Only the generated C# in obj/ changes: the generated TypeScript clients, their source
    map and the wire protocol are byte-identical, and code from an earlier generator keeps working with this runtime.
    Part of #1109.

  • Async commands no longer add a state machine each to a NativeAOT executable. A generated Bridge ran each
    CommunityToolkit async command, and each ReactiveUI command with a result or a completion, in an async lambda of its
    own. Bridges now pass a plain lambda to one runner per assembly that the generator writes beside them
    (RunicShared.Toolkit.Bridge.g.cs, RunicShared.Commands.Bridge.g.cs), with the same steps in the same order:
    the token check, Cancel registration and the typed ExecuteAsync(T) call for CommunityToolkit, then the await
    and the result's encoding. The Toolkit IsRunning subscription is shared the same way. In the research fixture of
    #1109 a ViewModel with three async commands costs 32.5 KB instead of 43.2 KB on linux-x64 (56.3 KB in 0.21); in the
    scaling suite's aot-size fixture 18.2 KB instead of 21.3 KB (25.5 KB in 0.21). ReactiveUI stream commands are
    unchanged. ToolkitCommandInspector.DescriptorFor keeps its signature; the descriptor it emits now calls the
    generated runner, which the Runic generator writes whenever a Bridge has a CommunityToolkit async command. Generated
    TypeScript is byte-identical. Part of #1109.

  • vite dev source maps name absolute files. runic() makes the sources of the
    source maps that the development server sends with each module absolute file paths
    (/home/me/App/Frontend/src/App.tsx, C:/Users/me/App/Frontend/src/App.tsx) instead of
    Vite 8's paths relative to the module. Visual Studio's JavaScript debugger, which attaches
    to the page with no web root, then binds breakpoints in Frontend/src; VS Code's
    JavaScript debugger, browser developer tools and Runic Inspect read them as before.
    vite build and vite preview output is unchanged. The Angular CLI's development server
    keeps its own maps. See
    The development server's source maps.

  • Angular CLI starter dependencies. The Angular starter (the Angular CLI
    build) and the Notes Angular examples move @angular/build and @angular/cli
    to 22.2.7 and no longer override vite: @angular/build now depends on Vite
    8.3.5, which has the GHSA-587h-7wmj-h5pm fix. A pnpm project created with the
    Angular CLI build no longer gets a pnpm-workspace.yaml; --angular-build vite
    projects are unchanged. An existing Angular CLI project can remove its vite
    override (in package.json, and for pnpm in pnpm-workspace.yaml) after moving
    to @angular/build 22.2.5 or later.

  • Size: the asset archive stores identical files once. When two paths of a frontend have the same content, such as
    the fonts and stylesheet that two frontend entries share, RunicAssetsDist and AssetArchive.Write* now store one
    ZIP entry for it, and the other paths name that entry in runic-assets.json with contentPath (archive schema
    runic.assets.archive/2). Every path keeps its own media type, entry-point flag and cache mode; lengths, SHA-256
    digests, entity tags and Subresource Integrity tokens are unchanged, and an embedded archive inflates shared content
    once. A fixture with two entries that share three fonts and a stylesheet goes from a 618,913-byte archive to 354,901
    bytes, and its NativeAOT executable on linux-x64 from 3,066,248 to 2,800,008 bytes (−0.25 MiB); reading aliases
    adds about 1.2 KB of code to every NativeAOT application that embeds an archive. An archive without
    duplicate content is still written as runic.assets.archive/1, byte for byte as before, and 0.22 reads archives
    from earlier releases unchanged. Runic.Assets 0.21 and earlier cannot read a schema-2 archive: if you pack an archive
    with 0.22 and embed it through RunicAssetsEmbeddedArchive in an application that uses an older Runic.Assets,
    update that application as well. AssetArchive.Inspect reports the canonical form, so a schema-1 archive that holds
    duplicate content reports schema 2. The packer's RAS1005 warning counts source maps by path, as before.

  • CS-WebUI NativeAOT applications are about 3 MB smaller on Linux and macOS. Each window's blob and upload
    endpoint is now served there by Runic's own loopback HTTP/1.1 server instead of .NET's managed HttpListener, which
    kept SslStream, X.509, OCSP and an HttpClient in every published executable although the endpoint only serves
    http:// on loopback. The CS-WebUI size fixture on linux-x64 goes from 10,710,336 to 7,743,328 bytes (−2.97 MB,
    −28 %). Windows keeps http.sys. The endpoint's URLs, responses and checks (Host, origin, upload token, loopback peers)
    are unchanged. The new server is stricter than HttpListener: it answers 400 to a request whose body framing is
    ambiguous (Content-Length with Transfer-Encoding, repeated or malformed lengths), to bare CR or LF line ends, to a
    dot segment in the path and to repeated Host, Origin or upload headers; 501 to a transfer coding other than
    chunked; and 414, 431 or 408 to a request line over 8 KiB, a head over 32 KiB or 100 fields, or a head that
    takes longer than 10 seconds. A new connection must send its first byte within 5 seconds, and an idle one closes
    after 30 seconds. At its limit of 128 connections, the oldest one without a request in progress is closed to make
    room, and a failed accept is retried (event 2105). The relay that holds the other loopback address now has the same
    bounds: 128 connections, and 2 seconds for a client to close its side after the endpoint closed the connection
    (before, a client that never closed its socket kept two of the process's file descriptors for good).
    docs/security.md lists the limits.

  • A RID-specific dotnet publish of a Runic Desktop application ships only its own
    operating system's platform code.
    This applies to dotnet publish -r <rid> for a
    Windows (win-*), macOS (osx-*) or Linux (linux-*) RuntimeIdentifier,
    framework-dependent (the default) or self-contained without trimming, with or without
    ReadyToRun, and as a single file. Such a publish leaves out the other operating systems' Runic.Platform
    providers: Runic.Platform.Windows outside Windows, Runic.Platform.MacOS outside
    macOS, and Runic.Platform.Linux, .Linux.Portal, .Linux.DBus, .Linux.Gtk4,
    .Linux.Polkit with the Linux-only Tmds.DBus.Protocol and GirCore GTK 4 bindings
    outside Linux. Its deps.json leaves them out too. The Desktop template's
    framework-dependent publish loses 2.4 MB on linux-x64 (13,089,260 to 10,674,346
    bytes), 1.9 MB on win-x64 (13,014,138 to 11,063,439 bytes), 3.4 MB on osx-arm64,
    4.1 MB with ReadyToRun on linux-x64 (26,229,892 to 22,107,458 bytes) and 2.4 MB as a
    single file on linux-x64 (11,621,833 to 9,206,817 bytes); a GTK 4
    application also leaves its 6.8 MB of GirCore bindings out on Windows and macOS. It
    keeps Runic.Desktop.Gtk4 (0.2 MB) on every operating system, because the
    application calls DesktopHostOptions.WithGtk4() on each one.

    Unchanged: dotnet build, dotnet run and the debugger, a publish without
    -r, trimmed (PublishTrimmed) and NativeAOT publishes, and so every
    dotnet runic package output
    (MSIX, the macOS bundle, deb, rpm, AppImage,
    Flatpak and Flathub), which is published with NativeAOT. CS-WebUI applications
    carry no platform providers and are unchanged too.

    Runic calls each provider only on its own operating system. Code of your own that
    calls another operating system's Runic.Platform API from a method that also runs
    on this one, even behind OperatingSystem.IsWindows() or a similar check, now
    throws FileNotFoundException in a RID-specific publish instead of reaching the
    check: .NET loads every assembly a method uses when it compiles the method. Move
    such a call into a method of its own that only that operating system runs (mark it
    [MethodImpl(MethodImplOptions.NoInlining)]), or set
    <RunicPublishAllPlatformAssemblies>true</RunicPublishAllPlatformAssemblies> to
    publish every operating system's assemblies as before.

  • The runic-app template no longer has the <Project> (WebView2 script debugging)
    launch profile
    (Runic Desktop, added in 0.20). It does not work in Visual Studio 2026
    (18.8 and 18.12): F5 hands the profile to Visual Studio's JavaScript adapter
    (jsWebView2Debugging), which starts the Window without the profile's environment
    variables. The Window then runs outside Development, Runic clears
    WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS, and the adapter cannot connect and stops the
    Window after about 20 seconds. In an existing project, delete the profile, the entry
    with "jsWebView2Debugging": true, from Properties/launchSettings.json, and keep
    <Project>. To stop at breakpoints in Frontend/src in Visual Studio, use Debug the
    Window of Runic DevKit for Visual Studio
    (0.22), which starts the Window under the .NET debugger and attaches the JavaScript
    debugger to the page. The VS Code configurations (Window + WebView2 (Windows)) and
    .vsconfig are unchanged. See
    Visual Studio.

Development-only views and members (#1109)

A view that only development needs, such as a mock-control or diagnostics panel, can stay out of the published
executable: mark its ViewModel with [RunicDevelopmentOnly], or mark single state properties and commands (on the
command property or its [RelayCommand] method). Builds, dotnet run, the debugger and untrimmed publishes keep
everything. A trimmed or NativeAOT publish turns the feature switch Runic.Application.Views.DevelopmentOnlyViews off,
so the trimmer removes the marked ViewModel's generated Bridge, about 15 KB per ViewModel in the measurements of
#1109, and the code of marked members:

  • Opening or presenting a marked ViewModel throws an InvalidOperationException that names it. Test
    RunicDevelopmentOnly.IsSupported before presenting it, as your own development-only code can.
  • A marked property is absent from the state and cannot be set or written; a marked command and its can… and
    is…Executing state are absent too, and calling or starting it is rejected with reason unavailable.

The generated TypeScript is the same in every configuration and describes the marked members truthfully: optional
state members, and commands documented as possibly unavailable. Marking a member changes the View's contract;
marking a ViewModel does not. Set the MSBuild property RunicDevelopmentOnlyViews to true to keep the marked code in
every publish (auto, the default, removes it only from trimmed and NativeAOT publishes). [RunicDevelopmentOnly] on
an interaction or view request has no effect and is warning RUNICBRIDGE072. See
Development-only views and members.

CS-WebUI pages in a JavaScript debugger

In Development, a CS-WebUI window in an installed Chrome, Edge or other
Chromium browser can open that browser's Chrome DevTools Protocol endpoint on
127.0.0.1, so an IDE's JavaScript debugger attaches to the page: Visual Studio
with Runic DevKit's Debug the Window or Attach to the Page, or with Attach to
Process ("JavaScript and TypeScript (Chrome DevTools/V8 Inspector)"), and
VS Code with js-debug's attach. Runic.Desktop adds
--remote-debugging-port when RUNIC_WEBUI_REMOTE_DEBUGGING_PORT asks for it,
0 for a free port or a fixed one, beside its Chromium defaults. It adds none
outside Development, when the window's WebContent policy sets
DevTools = false, or when the application's BrowserArguments name the switch
themselves.

  • Any local process can attach to the port, so it opens only when an IDE asks.
    A terminal dotnet runic dev opens none.
    • dotnet runic dev --debug-endpoint, for an IDE to pass when it starts dev, asks for a
      free port. It prints [dev] Debugging: with it, and lists it in the session
      file's debugEndpoints as { "engine": "chromium", "protocol": "cdp", "url": … }
      while the window's browser runs.
    • With --no-window, the IDE's Window gets port 9225, which dev lists for
      the session. If something holds 9225, dev warns and lists it under
      unavailableDebugEndpoints instead.
    • --no-debug-endpoint wins.
  • A fixed port is reported only once /json/version answers on 127.0.0.1 and,
    on Linux, no other user listens there. A taken one becomes a free port, with a
    warning.
  • New CS-WebUI projects from dotnet new runic-app --host cswebui have a
    (CS-WebUI script debugging) launch profile that opens port 9225.

Any local process can attach to the port; on a shared machine, run
dotnet runic dev --no-debug-endpoint. See
CS-WebUI pages in a JavaScript debugger
and the security guide.

dotnet runic dev stops on a request on its standard input

An IDE that can't send Ctrl+C can now stop dotnet runic dev gracefully.
Visual Studio on Windows is one: a process without a console has no Ctrl+C, so
until now it ended the process tree by force. When the IDE sets
RUNIC_DEV_STOP_ON_INPUT=1 and redirects dev's standard input, dev stops
as on Ctrl+C at a line stop or at the end of the input. It stops the frontend
and the Window, marks the session file "stopped", deletes its frontend marker
and development pages, and touches obj/runic/dev-stopped. So a build right
after the stop builds the production frontend again. The processes that dev
starts get an input of their own. Without the variable, dev doesn't read its
input, so a terminal is unaffected. See
IDE contract.

Runic DevKit: the RunicApplication capability and the template's .vsconfig

The Runic Views build targets declare the RunicApplication project
capability in every project that references Runic Views: the window project
and its ViewModel libraries and tests. Visual Studio loads Runic DevKit only
for a solution with such a project (SolutionHasProjectCapability:RunicApplication).

New runic-app projects have a .vsconfig that names the Visual Studio
components that debugging them needs: the .NET desktop development workload
(Microsoft.VisualStudio.Workload.ManagedDesktop) and JavaScript diagnostics
(Microsoft.VisualStudio.Component.JavaScript.Diagnostics), an optional
component of that workload that Visual Studio's JavaScript debugger needs for
the page in WebView2 (Runic DevKit's Debug the Window) and in Chrome or Edge. Visual Studio
offers to install a missing one when it opens the project. To add it to an
existing project, copy the file from a new one into the directory of its solution.

The Runic extension for VS Code is now Runic DevKit, with the ID
runic-artifex.runic-devkit (it was runic-artifex.runic); docs/debugging.md
and the template's .vscode/extensions.json name it.

The side panel and the close drain are stable

The side panel (RUNICDESK104, 0.19) and the close drain (RUNICDESK105, 0.19)
graduate: their [Experimental] attributes are removed and their API is supported
like the rest of its package. Both are unchanged since 0.21, which made the last
API review changes (DesktopSidePanelRefusal.Closed, RunicCloseDrain.KeepWindow).
Their IDs are retired and never name another family.

  • Side panel: DesktopWindow.OpenSidePanelAsync, SidePanel,
    CheckSidePanel and the DesktopSidePanel* types in Runic.Desktop;
    IRunicWindowPresentation.OpenSidePanelAsync and SidePanel,
    RunicWindowPresentationFeatures.SidePanel, IRunicSidePanel and the
    RunicSidePanel* types in Runic.Application.Views; the side panel members of
    RunicTestWindowPresentation in Runic.Application.Testing. See the
    side panel guide.
  • Close drain: RunicCloseDrain, RunicWindowOptions.CloseDrain,
    RunicOperationClose, IRunicWindowContext.DrainOnClose,
    RunicWindowCloseResult.RemainingDurableWork and
    ReportCloseDrainUnavailable; RunicDesktopHostOptions.CloseDrain;
    RunicWindowTestHostOptions.CloseDrain and RunicTestWindow.IsDraining;
    DesktopWindowOptions.CloseDrainAsync, DesktopCloseDrainContext,
    DesktopCloseReason, DesktopHostOptions.ShutdownDrainTimeout and
    DesktopHost.ShutdownStarting. On npm, onBridgeDraining is a root export
    of @runic-artifex/views; ./experimental keeps a deprecated re-export
    until 0.23. Generated Bridges no longer suppress RUNICDESK105.

What to remove:

  • RUNICDESK104 and RUNICDESK105 from <NoWarn> in project files and
    Directory.Build.props, and their #pragma warning disable/restore lines.
    A leftover suppression is harmless.
  • Import onBridgeDraining from @runic-artifex/views. The
    @runic-artifex/views/experimental import still works in 0.22, marked
    @deprecated, and 0.23 removes it (one-minor transition, D069.3).

See graduated and retired IDs.

Making the executable smaller (docs)

The packaging guide has a new section,
Making the executable smaller:
what Runic already does for a trimmed or NativeAOT publish, and four opt-in .NET
settings with their measured savings and what the application gives up
(StackTraceSupport=false, InvariantGlobalization=true,
OptimizationPreference=Size, UseSystemResourceKeys=true), and how to measure
an application with dotnet runic size and an .mstat file. The templates are
unchanged.

Fixes

  • RunicPathWatcher watches a directory that was deleted or replaced again at once.
    On Windows, deleting a watched directory stops its watch with an error, which the
    watcher treated as a failed watch, also when the directory was still being deleted
    or already re-created: until its next poll it skipped the replacement and reported
    a Failed error, and changes in it were found only by polling (#1008).
  • Linux JavaScript debugging (preview) follow-ups from the field test (#1065). When
    another program holds port 9222, dotnet runic dev still moves Runic's CDP adapter
    to a free port, but now names that program when it is yours (another dev session
    and its directory, or the command line), and warns when the project's
    .vscode/launch.json has a JavaScript attach configuration on 9222, such as the
    template's Attach to the page (JavaScript), which would otherwise debug the other
    program's page. --no-window's RAPPDEV1017 names the holder too. When the Window's
    page does not answer the debugger's first command within 5 seconds, as once right
    after WebKit's Web Inspector opened, dev says so, sends an idempotent command once
    more, and then fails it with an error instead of the attach ending in silence. The
    documentation gives the sizes of RUNIC_DEV_CDP_TRACE, which leaves script sources
    out unless RUNIC_DEV_CDP_TRACE_SOURCES=1.
  • dotnet runic dev starts npm and pnpm on Windows (#1081). Node.js installs them as
    batch files (npm.cmd), which dev could not start (RAPPDEV1004: Could not start 'npm ci'), so a runic-app project with its default npm frontend failed there.
    dotnet runic now finds programs through PATH and PATHEXT as the shell and
    doctor do, and starts a batch file through cmd.exe with its arguments passed
    unchanged. Stopping dev still stops everything npm started.
  • Under dotnet runic dev with a Vite or Angular development server, a URL that the
    page builds at run time relative to its document, such as
    <img src="brand/logo.svg">, a file of Vite's publicDir or one that a Vite
    plugin's middleware serves, no longer 404s on the Window's origin (#1085). Runic
    Desktop forwards a GET or HEAD that neither www/ nor the application's
    Resources answer to the development server, and CS-WebUI redirects it there.
    The Vite DevTools dock loads its script, its connection file and its icon from the
    server only, so its button shows its icon again (#1086): the Window answers the
    dock's /__devtools/embedded.js with a module that imports it from the server, and
    redirects the dock's other root paths (/__devtools/, /__devtools-assets/) to the
    same path on the server.
    • A trimmed or NativeAOT publish turns the fallback off
      (Runic.Application.DevelopmentServerForwarding), so the trimmer removes it and its
      HTTP client from published applications.
    • This works only in the Development environment, with the address that dev
      passes (http://127.0.0.1:<port>/), and not for the embedded frontend archive.
      Only same-origin or user-initiated GET and HEAD requests from loopback are
      passed on. Targets keep the server's host, port and base path, and the server's
      own endpoints (/__runic/, /__open-in-editor, /@fs/, any first segment
      starting with __ or @) are not forwarded, except the dock's. The
      security guide
      lists the checks.
    • A Window that an IDE starts under dotnet runic dev --no-window does not get
      the server's address yet, so it still answers 404 for these paths.
  • dotnet runic doctor's compatibility-set check no longer fails for packages
    outside the release train whose ids start with Runic, such as
    RunicArtifex.DynamicData and RunicArtifex.ReactiveUI.Validation (#1087).
    The compatibility set now records the train's packages itself: runic-sdk's own
    packages by id, and the train's Runic Command Line and Runic Translations
    packages with their version. Doctor checks those and ignores every other
    package.
  • dotnet runic doctor's package-manager check accepts the npm 11 that the
    supported Node.js 24 and 26 releases ship, from npm 11.12.1 (the npm of
    Node 26.0.0), with a warning that names the certified npm 12.2.0 (#1088). It
    failed below npm 12.2.0, which no Node release ships; nothing in the starters
    needs npm 12. To use the certified npm that the starters declare in
    packageManager, run npm install --global npm@12.2.0.
  • Runic Inspect's open-in-editor works for frontend files on Windows: Vue,
    Svelte, Angular and React 19 components and handlers, and files outside the
    Vite root served under /@fs/ (monorepo packages, linked libraries).
    /__runic/open refused every Windows path that used /, the form Vite uses,
    and read /@fs/C:/… as C:\C:\…. It still opens only the files that Vite
    would serve to the page, and refuses UNC, device and .. paths
    (#1090).
  • On Windows, a window that falls back to Edge opens when the application was started
    with a compatibility layer (#1097), as Explorer sets for some double-click starts.
    Edge then restarted itself, and Runic took the first process's exit for the window
    closing: OpenWindowAsync failed with presentation-start-failed while Edge
    showed a 404 page. Runic now removes __COMPAT_LAYER from the browser's
    environment and passes Edge --edge-skip-compat-layer-relaunch. A browser whose
    started process still exits before its first request, such as Edge leaving
    elevation, is waited for until ConnectionTimeout; if no window connects, opening
    fails with the new presentation-browser-handed-off. Such a window closes when its
    page disconnects.
  • On Windows, dotnet runic dev no longer leaves obj/runic/dev-session.json saying
    starting for a session that is ready (#1102). The rename that replaces the session
    file or the frontend marker failed with "Access to the path is denied" while another
    process (an IDE's project system, an antivirus scan, an indexer) held the file open
    without delete sharing. dev now retries the replacement for up to about 0.6 seconds.
    If it still fails, dev prints a warning that names the file, keeps the session's
    state, and writes the file again on its next change or its 5-second heartbeat.
  • A JavaScript debugger attached to a WebKitGTK Window through dotnet runic dev's CDP
    adapter (VS Code's js-debug) no longer leaves the page stopped at the start of a module
    after a reload, a Vite page reload or a Window restart (#1108). When the debugger
    continued from one stop and the page stopped again right away, the adapter could pass the
    next stop to the debugger before its reply to the debugger's Debugger.resume. js-debug
    then never continued from the new stop. The page stayed stopped, with no stop shown in
    the editor, until something else resumed it. This happened mostly on a loaded machine.
    The adapter now sends the reply to Debugger.resume, a step, Debugger.pause,
    Page.reload or Page.navigate before the events that follow it, as Chromium does. Its
    emulated pause before each script with a source map continues only after the reply to
    the debugger's own answer, not after the reply to another command, such as an
    evaluation.
    After a Window restart, the debugger's commands now wait until the adapter has set the
    debugger's breakpoints on the restarted Window's page. Before, a click or an evaluation
    could run there before them and not stop.
  • Size: Runic.Application.Views and Runic.Navigation no longer use the LINQ operators
    that make every other LINQ query in a NativeAOT application larger (Skip, OrderBy,
    GroupBy, MaxBy, Concat, SelectMany), and about 30 internal records that never
    compare by value or print themselves are now plain classes. Behaviour is unchanged. This
    takes about 135 KB more off a CS-WebUI executable on Linux and 65 KB off a Runic Desktop
    one (#1109).
  • A JavaScript debugger attached to a WebKitGTK Window through dotnet runic dev's CDP
    adapter (VS Code's js-debug) no longer stops at a breakpoint it never set (#1139). WebKit
    could report a stop at the adapter's own breakpoint for the pause before each script
    with a source map just after the debugger turned that pause off. The adapter passed the
    stop on, and the page stayed stopped until the user continued it. The adapter now lets
    WebKit continue from such a stop.
  • Size: a NativeAOT Runic Desktop application on Linux is about 0.43 MB smaller
    (11.79 → 11.36 MB for the size fixture's Desktop host). A trimmed or NativeAOT publish
    no longer links the macOS backend on Windows or Linux, nor dotnet runic dev's live
    frontend directory and its file watcher. The new
    Runic.Application.Views.Desktop.DevelopmentAssets feature switch is off in trimmed
    and NativeAOT publishes; dotnet runic dev and other untrimmed builds keep the live
    directory, unchanged. Runic Desktop also uses fewer LINQ and collection types over
    enums and value tuples, and stores its file-extension media types as a compact table.
    Behaviour is unchanged.
    • Runic's three development-only feature switches
      (Runic.Application.DevelopmentServerForwarding, Runic.Desktop.WebUiRemoteDebugging
      and Runic.Application.Views.Desktop.DevelopmentAssets) are now off only in the
      trimmed or NativeAOT publish itself, including dotnet publish --no-build and
      dotnet runic size. A project that sets PublishAot or PublishTrimmed in its
      project file, as the .NET guidance recommends, keeps the development server fallback,
      the CS-WebUI DevTools endpoint and the live frontend directory in dotnet build,
      dotnet run, dotnet runic dev and IDE debugging.
  • Size: a trimmed or NativeAOT Runic Desktop application no longer links the CS-WebUI
    Window's Development DevTools Protocol endpoint. The new
    Runic.Desktop.WebUiRemoteDebugging feature switch is off in trimmed and NativeAOT
    publishes, so the trimmer removes the endpoint and the HTTP client of its
    /json/version check; such a build opens no endpoint, even in Development.
    dotnet runic dev and other untrimmed builds keep it, unchanged. Together with the
    hosted region's manifest read without HttpClient, this takes about 2.8 MB off a
    Runic Desktop executable on Linux.
  • Size: a NativeAOT Runic Desktop application keeps less that it does not use
    (runic-sdk#1109; the size fixture's Desktop host on Linux 11.36 → 10.75 MB):
    • Hosted mode (the region guest) is kept only by an application that creates
      RunicGuestOptions; an application that is never a guest no longer carries it (−0.51 MB).
    • The page script of /webui.js is compiled in minified, as UTF-8, and the macOS window
      chrome and WebKitGTK keyboard scripts only in builds whose window code uses them.
    • Behaviour change: RunicDesktopServer=None now turns the presentation server off, as
      documented for an executable that opens no window. A trimmed or NativeAOT build keeps
      neither server, also when it references Runic.Desktop.Kestrel (−4.6 MB in that case),
      and a window fails with presentation-server-unavailable instead of being served by a
      referenced Kestrel. The new build warning
      RUNICDESK007
      reports None together with a referenced server package; remove RunicDesktopServer
      to use that server, or suppress the warning with NoWarn.
    • The new MSBuild property RunicDesktopRegionHost (default true) lets an application
      whose pages declare no hosted regions leave the region host out (false).
  • Size: a hosted Runic Desktop Window in component mode reads its component build's
    manifest (_runic_component/runic-component.json) from its own loopback surface with
    a small HTTP/1.1 GET of its own instead of HttpClient, so a trimmed or NativeAOT
    application no longer links the HTTP client and TLS stack for it. The request, the
    manifest checks and the 64 KiB and ten-second limits are unchanged. Together with the
    Runic.Desktop.WebUiRemoteDebugging feature switch, this takes about 2.8 MB off a
    Runic Desktop executable on Linux.
  • Size: Runic.Application.Views and Runic.Navigation compile less framework code in a
    NativeAOT application. Internal dictionary keys and async results that were value types
    are now classes, so they share the framework's generic code instead of compiling their
    own copies; the two packages share one fallback trace logger; and a few LINQ chains
    over value types are loops. Behaviour is unchanged. This takes about 150 KB off a
    CS-WebUI executable on Linux.
  • On Windows, the Bridge generator no longer fails a build now and then with
    "Access to the path is denied" or "being used by another process". That
    happened when an editor, an antivirus scan or an indexer held a generated
    file open just as the generator replaced it. The generator now retries the
    replacement for up to about 0.6 seconds before it reports the error.
  • Single-file publish of a Views application failed with NETSDK1191 ("A runtime
    identifier for the property 'PublishSingleFile' couldn't be inferred"), for every
    host and also with -r. The Views generator's own build and its bootstrap pass
    clear the runtime identifier but kept PublishSingleFile and
    IncludeNativeLibrariesForSelfExtract, as they kept PublishReadyToRun before
    0.15. They now reset both, so dotnet publish -r <rid> -p:PublishSingleFile=true
    works, framework-dependent or self-contained.
  • Visual Studio's F5 now builds after a frontend-only edit and after
    dotnet runic dev stops. Its fast up-to-date check knew only the C# inputs,
    so F5 ran the old page. After dev stopped, F5 also kept the development page
    that dev had written into www/, which points at the stopped server, so the
    Window stayed blank until an explicit Build. The Runic Views build targets now
    give the check the frontend's files, without node_modules, the build output
    and the generated client. They also give it obj/runic/dev-stopped, which
    dev touches when it stops. Only Visual Studio evaluates these items.
    While dev --no-window runs, F5 builds nothing unless a C# file changed: a
    frontend edit is dev's to serve, so it builds once and then no more, and
    Visual Studio no longer warns that the project stays out of date after a
    build. A deleted www/index.html also makes F5 build again.

CI and tests

  • The native job's Windows x64 leg runs dotnet runic dev with npm
    (dev-npm-smoke.mjs) and tests how the tool starts batch files. The tool's files
    that start programs or choose how plan that leg; its other files still plan no
    Windows leg, and a planner test keeps every process start in CommandRunner (#1081).
  • The Templates lane on Node 26 builds the starters with the npm 11 that
    Node 26 ships instead of the certified npm 12.2.0, and expects doctor's
    package-manager warning for it (#1088).
  • A publish built inside the runic-sdk repository through project references now
    holds what a package consumer's publish holds (FD5, #1151). It no longer
    copies the Views generator's BridgeCodegen apphost, deps.json and
    runtimeconfig.json (which also leave the build output), or the referenced
    projects' XML docs and PDBs; the build output keeps those. A RID-specific
    publish leaves out other operating systems' Runic.Platform projects, as it
    does their packages, with the same RunicPublishAllPlatformAssemblies
    opt-out. The Desktop host fixture's linux-x64 framework-dependent publish
    shrinks from 14,567,820 to 6,987,971 bytes and the CS-WebUI fixture's from
    5,117,976 to 3,692,301 bytes. The size budgets now count the whole folder.
  • The NativeAOT size budgets (tests/scaling/aot-size) name a size regression
    where it happens: aot/framework/System.Net.Http and
    aot/framework/System.Net.Security fail when either assembly is back in the
    CS-WebUI fixture on linux-x64 (limit 0), and aot/assembly/<Runic assembly>
    budgets the mstat bytes of Runic.Application.Views, Runic.Navigation,
    Runic.Application.Views.CsWebUi and Runic.Assets. A Runic Desktop host fixture
    (aot/desktop/*, no presentation server) and the CS-WebUI fixture with
    Translations (aot/views-translations/executable-bytes) are measured in the
    same step. aot/executable-bytes is tightened to the size after 0.22's
    reductions.
  • Every tracked file has a component, or is engineering-only, neutral or a listed
    shared input; a planner test fails on any other. A new CI component owns the
    planner, the gates and the local CI tooling, so a change to them runs only the
    always-run jobs instead of every job and leg, and the CI scripts of platform
    steps plan only their legs.
  • eng/ci/flakes.mjs reports the failures of recent ci.yml runs by signature
    (test or step and first error line), grouped across runs, jobs and legs: those
    seen twice without an issue, known flakes, those that passed on a rerun of the
    same commit, and the merge queue entries to re-queue (the flake policy, D069).
  • The size budgets now also gate the framework-dependent publish
    (-r linux-x64 --self-contained false) of the CS-WebUI and Desktop host
    fixtures, in the same CI step as the NativeAOT budgets.
    fdd/folder-bytes and fdd/desktop/folder-bytes gate every file of the
    folder (+2 %) and name the files that grew. fdd/other-os-bytes and
    fdd/desktop/other-os-bytes fail on any file of another operating system
    (limit 0).
  • npm archives are reproducible: a package's gitHead is now the commit that last
    changed its inputs (its directory, the first-party packages it depends on and the
    shared build files), not the commit the build ran on, so a commit elsewhere leaves
    the archive and its integrity unchanged. npm's provenance still names the release
    commit. The release check accepts such a gitHead when it is an ancestor of the
    release commit with the same inputs (eng/release/README.md, "npm archive source commit").
  • The train gate and the train feed select upstream CI runs by commit, never "the
    newest": run@<commit> takes the newest successful main run at or after that
    commit, the rows T, P-tr and P-sdk refuse a bare run, and the train feed reads
    the upstream commit from TrainCommit on the train's PackageVersion. The gate
    refuses a Translations or Command Line candidate whose main moved since the
    runic-sdk run's train feed served it, unless every package is byte-identical.
    eng/train/README.md describes the train's choreography step by step.

What's Changed

Full Changelog: v0.21.0...v0.22.0