Repository navigation
Runic SDK 0.22.0
Pre-releaseRunic 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 runand 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 inFrontend/srcbind, F5 builds after a frontend-only edit, and
an IDE can stopdotnet 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, anddotnet runic devnames what holds port 9222 (Fixes). - The side panel and the close drain are stable,
and the host-named Views client scriptsrunic-desktop-views.jsand
runic-cswebui.jsare 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.jsandrunic-cswebui.js(D072.11). The host packages
copy their Views client intowww/asrunic-views.jsand, 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. Loadrunic-views.js
instead:<script src="runic-views.js"></script>afterwebui.js. The
templates already do. A project that references more than one host, such as
Runic Desktop and CS-WebUI, setsRunicApplicationHost(desktopor
cswebui), or the build copies norunic-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 torunic-views.js. - Deprecated:
onBridgeDrainingfrom@runic-artifex/views/experimental.
The close drain's flag is a root export of@runic-artifex/viewsfrom 0.22
(the side panel and the close drain are stable).
The old import still works in 0.22:./experimentalre-exports the same
function, marked@deprecated, so editors strike it through. 0.23 removes it;
importonBridgeDrainingfrom@runic-artifex/views. RemoveRUNICDESK104
andRUNICDESK105suppressions too, which no longer do anything. - Runic Translations 0.14.
Runic.Application.Views.Translationsrequires 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: thedotnet-runic-translationstool,Runic.Translationsand
.Build, and@runic-artifex/vite-plugin-runic-translations;dotnet runic doctorchecks 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: keepRunic.Translationsand
Runic.Translations.Buildat 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 (warningRTR0107) 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'scompatibility-setcheck 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 oneswitchper 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'saot-sizefixture 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 callsToolkitCommandInspector.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, inRunicShared.Codecs.Bridge.g.csbeside 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 withusingaliases (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'saot-sizefixture
20.8 KB instead of 25.5 KB. Only the generated C# inobj/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,Cancelregistration and the typedExecuteAsync(T)call for CommunityToolkit, then the await
and the result's encoding. The ToolkitIsRunningsubscription 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'saot-sizefixture 18.2 KB instead of 21.3 KB (25.5 KB in 0.21). ReactiveUI stream commands are
unchanged.ToolkitCommandInspector.DescriptorForkeeps 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 devsource maps name absolute files.runic()makes thesourcesof 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 inFrontend/src; VS Code's
JavaScript debugger, browser developer tools and Runic Inspect read them as before.
vite buildandvite previewoutput 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/buildand@angular/cli
to 22.2.7 and no longer overridevite:@angular/buildnow 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 apnpm-workspace.yaml;--angular-build vite
projects are unchanged. An existing Angular CLI project can remove itsvite
override (inpackage.json, and for pnpm inpnpm-workspace.yaml) after moving
to@angular/build22.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,RunicAssetsDistandAssetArchive.Write*now store one
ZIP entry for it, and the other paths name that entry inrunic-assets.jsonwithcontentPath(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 asrunic.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 throughRunicAssetsEmbeddedArchivein an application that uses an older Runic.Assets,
update that application as well.AssetArchive.Inspectreports 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 managedHttpListener, which
keptSslStream, X.509, OCSP and anHttpClientin 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 thanHttpListener: it answers400to a request whose body framing is
ambiguous (Content-LengthwithTransfer-Encoding, repeated or malformed lengths), to bare CR or LF line ends, to a
dot segment in the path and to repeatedHost,Originor upload headers;501to a transfer coding other than
chunked; and414,431or408to 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.mdlists the limits. -
A RID-specific
dotnet publishof a Runic Desktop application ships only its own
operating system's platform code. This applies todotnet 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.Windowsoutside Windows,Runic.Platform.MacOSoutside
macOS, andRunic.Platform.Linux,.Linux.Portal,.Linux.DBus,.Linux.Gtk4,
.Linux.Polkitwith the Linux-onlyTmds.DBus.Protocoland GirCore GTK 4 bindings
outside Linux. Itsdeps.jsonleaves 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
keepsRunic.Desktop.Gtk4(0.2 MB) on every operating system, because the
application callsDesktopHostOptions.WithGtk4()on each one.Unchanged:
dotnet build,dotnet runand the debugger, a publish without
-r, trimmed (PublishTrimmed) and NativeAOT publishes, and so every
dotnet runic packageoutput (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'sRunic.PlatformAPI from a method that also runs
on this one, even behindOperatingSystem.IsWindows()or a similar check, now
throwsFileNotFoundExceptionin 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-apptemplate 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, fromProperties/launchSettings.json, and keep
<Project>. To stop at breakpoints inFrontend/srcin 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
.vsconfigare 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
InvalidOperationExceptionthat names it. Test
RunicDevelopmentOnly.IsSupportedbefore 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…Executingstate are absent too, and calling or starting it is rejected with reasonunavailable.
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 terminaldotnet runic devopens none.dotnet runic dev --debug-endpoint, for an IDE to pass when it startsdev, asks for a
free port. It prints[dev] Debugging:with it, and lists it in the session
file'sdebugEndpointsas{ "engine": "chromium", "protocol": "cdp", "url": … }
while the window's browser runs.- With
--no-window, the IDE's Window gets port 9225, whichdevlists for
the session. If something holds 9225,devwarns and lists it under
unavailableDebugEndpointsinstead. --no-debug-endpointwins.
- A fixed port is reported only once
/json/versionanswers 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 cswebuihave 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,
CheckSidePaneland theDesktopSidePanel*types in Runic.Desktop;
IRunicWindowPresentation.OpenSidePanelAsyncandSidePanel,
RunicWindowPresentationFeatures.SidePanel,IRunicSidePaneland the
RunicSidePanel*types in Runic.Application.Views; the side panel members of
RunicTestWindowPresentationin Runic.Application.Testing. See the
side panel guide. - Close drain:
RunicCloseDrain,RunicWindowOptions.CloseDrain,
RunicOperationClose,IRunicWindowContext.DrainOnClose,
RunicWindowCloseResult.RemainingDurableWorkand
ReportCloseDrainUnavailable;RunicDesktopHostOptions.CloseDrain;
RunicWindowTestHostOptions.CloseDrainandRunicTestWindow.IsDraining;
DesktopWindowOptions.CloseDrainAsync,DesktopCloseDrainContext,
DesktopCloseReason,DesktopHostOptions.ShutdownDrainTimeoutand
DesktopHost.ShutdownStarting. On npm,onBridgeDrainingis a root export
of@runic-artifex/views;./experimentalkeeps a deprecated re-export
until 0.23. Generated Bridges no longer suppressRUNICDESK105.
What to remove:
RUNICDESK104andRUNICDESK105from<NoWarn>in project files and
Directory.Build.props, and their#pragma warning disable/restorelines.
A leftover suppression is harmless.- Import
onBridgeDrainingfrom@runic-artifex/views. The
@runic-artifex/views/experimentalimport 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
RunicPathWatcherwatches 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
aFailederror, 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 devstill moves Runic's CDP adapter
to a free port, but now names that program when it is yours (anotherdevsession
and its directory, or the command line), and warns when the project's
.vscode/launch.jsonhas a JavaScript attach configuration on 9222, such as the
template'sAttach to the page (JavaScript), which would otherwise debug the other
program's page.--no-window'sRAPPDEV1017names 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,devsays 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 ofRUNIC_DEV_CDP_TRACE, which leaves script sources
out unlessRUNIC_DEV_CDP_TRACE_SOURCES=1. dotnet runic devstarts npm and pnpm on Windows (#1081). Node.js installs them as
batch files (npm.cmd), whichdevcould not start (RAPPDEV1004: Could not start 'npm ci'), so arunic-appproject with its default npm frontend failed there.
dotnet runicnow finds programs throughPATHandPATHEXTas the shell and
doctordo, and starts a batch file throughcmd.exewith its arguments passed
unchanged. Stoppingdevstill stops everything npm started.- Under
dotnet runic devwith 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'spublicDiror one that a Vite
plugin's middleware serves, no longer 404s on the Window's origin (#1085). Runic
Desktop forwards aGETorHEADthat neitherwww/nor the application's
Resourcesanswer 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.jswith 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
Developmentenvironment, with the address thatdev
passes (http://127.0.0.1:<port>/), and not for the embedded frontend archive.
Only same-origin or user-initiatedGETandHEADrequests 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-windowdoes not get
the server's address yet, so it still answers 404 for these paths.
- A trimmed or NativeAOT publish turns the fallback off
dotnet runic doctor'scompatibility-setcheck no longer fails for packages
outside the release train whose ids start withRunic, such as
RunicArtifex.DynamicDataandRunicArtifex.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'spackage-managercheck 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, runnpm 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/openrefused every Windows path that used/, the form Vite uses,
and read/@fs/C:/…asC:\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:OpenWindowAsyncfailed withpresentation-start-failedwhile Edge
showed a 404 page. Runic now removes__COMPAT_LAYERfrom 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 untilConnectionTimeout; if no window connects, opening
fails with the newpresentation-browser-handed-off. Such a window closes when its
page disconnects. - On Windows,
dotnet runic devno longer leavesobj/runic/dev-session.jsonsaying
startingfor 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.devnow retries the replacement for up to about 0.6 seconds.
If it still fails,devprints 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'sDebugger.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 toDebugger.resume, a step,Debugger.pause,
Page.reloadorPage.navigatebefore 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.ViewsandRunic.Navigationno 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, nordotnet runic dev's live
frontend directory and its file watcher. The new
Runic.Application.Views.Desktop.DevelopmentAssetsfeature switch is off in trimmed
and NativeAOT publishes;dotnet runic devand 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
andRunic.Application.Views.Desktop.DevelopmentAssets) are now off only in the
trimmed or NativeAOT publish itself, includingdotnet publish --no-buildand
dotnet runic size. A project that setsPublishAotorPublishTrimmedin its
project file, as the .NET guidance recommends, keeps the development server fallback,
the CS-WebUI DevTools endpoint and the live frontend directory indotnet build,
dotnet run,dotnet runic devand IDE debugging.
- Runic's three development-only feature switches
- Size: a trimmed or NativeAOT Runic Desktop application no longer links the CS-WebUI
Window's Development DevTools Protocol endpoint. The new
Runic.Desktop.WebUiRemoteDebuggingfeature switch is off in trimmed and NativeAOT
publishes, so the trimmer removes the endpoint and the HTTP client of its
/json/versioncheck; such a build opens no endpoint, even inDevelopment.
dotnet runic devand other untrimmed builds keep it, unchanged. Together with the
hosted region's manifest read withoutHttpClient, 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.jsis 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=Nonenow 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 referencesRunic.Desktop.Kestrel(−4.6 MB in that case),
and a window fails withpresentation-server-unavailableinstead of being served by a
referenced Kestrel. The new build warning
RUNICDESK007
reportsNonetogether with a referenced server package; removeRunicDesktopServer
to use that server, or suppress the warning withNoWarn. - The new MSBuild property
RunicDesktopRegionHost(defaulttrue) lets an application
whose pages declare no hosted regions leave the region host out (false).
- Hosted mode (the region guest) is kept only by an application that creates
- 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 ofHttpClient, 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.WebUiRemoteDebuggingfeature switch, this takes about 2.8 MB off a
Runic Desktop executable on Linux. - Size:
Runic.Application.ViewsandRunic.Navigationcompile 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 keptPublishSingleFileand
IncludeNativeLibrariesForSelfExtract, as they keptPublishReadyToRunbefore
0.15. They now reset both, sodotnet 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 devstops. Its fast up-to-date check knew only the C# inputs,
so F5 ran the old page. Afterdevstopped, F5 also kept the development page
thatdevhad written intowww/, 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, withoutnode_modules, the build output
and the generated client. They also give itobj/runic/dev-stopped, which
devtouches when it stops. Only Visual Studio evaluates these items.
Whiledev --no-windowruns, F5 builds nothing unless a C# file changed: a
frontend edit isdev'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 deletedwww/index.htmlalso makes F5 build again.
CI and tests
- The native job's Windows x64 leg runs
dotnet runic devwith 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 inCommandRunner(#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-managerwarning 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'sBridgeCodegenapphost,deps.jsonand
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.Platformprojects, as it
does their packages, with the sameRunicPublishAllPlatformAssemblies
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.Httpand
aot/framework/System.Net.Securityfail when either assembly is back in the
CS-WebUI fixture on linux-x64 (limit 0), andaot/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-bytesis 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.mjsreports the failures of recentci.ymlruns 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-bytesandfdd/desktop/folder-bytesgate every file of the
folder (+2 %) and name the files that grew.fdd/other-os-bytesand
fdd/desktop/other-os-bytesfail on any file of another operating system
(limit 0). - npm archives are reproducible: a package's
gitHeadis 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 agitHeadwhen 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 successfulmainrun at or after that
commit, the rows T, P-tr and P-sdk refuse a barerun, and the train feed reads
the upstream commit fromTrainCommiton the train'sPackageVersion. The gate
refuses a Translations or Command Line candidate whosemainmoved since the
runic-sdk run's train feed served it, unless every package is byte-identical.
eng/train/README.mddescribes the train's choreography step by step.
What's Changed
- Record the 0.21.0 publication; main is 0.22.0 by @ViktorJannicke in #1079
- Runic DevKit: RunicApplication capability, template .vsconfig, new extension ID by @ViktorJannicke in #1080
- CS-WebUI: Development-only CDP port for IDE JavaScript debuggers (SDK-3) by @ViktorJannicke in #1082
- dotnet runic: start npm.cmd and pnpm.cmd on Windows (#1081) by @ViktorJannicke in #1083
- Template: remove the (WebView2 script debugging) launch profile (D070.18) by @ViktorJannicke in #1089
- Views targets: Visual Studio's up-to-date check knows the frontend and dev's stop (WIN-01) by @ViktorJannicke in #1091
- vite-plugin-runic: open frontend files from Windows paths in Runic Inspect (WIN-02, WIN-03, WIN-07, WIN-11) by @ViktorJannicke in #1090
- doctor: check exactly the train's packages; accept the npm 11 of Node 24 and 26 (#1087, #1088) by @ViktorJannicke in #1095
- dotnet runic dev: stop on a request on standard input (WIN-06, SDK half) by @ViktorJannicke in #1092
- WebKit CDP adapter: name what holds 9222, report a page that does not answer (#1065) by @ViktorJannicke in #1098
- Desktop: keep Edge from relaunching itself, survive a browser hand-off (#1097) by @ViktorJannicke in #1099
- vite-plugin-runic: absolute sources in vite dev source maps by @ViktorJannicke in #1084
- File watching: a watch stopped by its directory's deletion is not a failure (#1008) by @ViktorJannicke in #1100
- dotnet runic dev: the Window's origin falls back to the development server (#1085, #1086) by @ViktorJannicke in #1096
- Accessibility probe: move into the side panel and back when the return goes unsaid (#1093) by @ViktorJannicke in #1101
- Bridge codegen: retry a generated-file rename that Windows refuses (WIN-09) by @ViktorJannicke in #1094
- dev: retry the session file and frontend marker replace on Windows (#1102) by @ViktorJannicke in #1103
- Train: select CI runs by commit; choreography and a moved-upstream check (H2, H5) by @ViktorJannicke in #1104
- Reproducible npm archives: gitHead is the commit that last changed the package's inputs (D069.2) by @ViktorJannicke in #1105
- Graduate the side panel and the close drain (RUNICDESK104, RUNICDESK105) by @ViktorJannicke in #1107
- CI: a CI component owns CI-only files; a flake report applies the flake policy (H4, H6) by @ViktorJannicke in #1106
- docs: making a NativeAOT executable smaller (D072.5) by @ViktorJannicke in #1115
- File watching: a delete-pending watched directory is replaced, not failed (#1008) by @ViktorJannicke in #1114
- Runic Desktop: a feature switch for the CS-WebUI remote-debugging endpoint (D072.2, S2) by @ViktorJannicke in #1112
- Hosted regions: read the component manifest without HttpClient (D072.2, S3) by @ViktorJannicke in #1113
- Drop the Angular CLI starter's and Angular examples' vite override (D072.3) by @ViktorJannicke in #1110
- tests: start js-debug window-restart once Vite has stopped reloading the page (#1108) by @ViktorJannicke in #1116
- CS-WebUI: serve blobs and uploads from Runic's own loopback server outside Windows (−2.97 MB AOT) by @ViktorJannicke in #1111
- AOT size budgets: framework sentinels, per-assembly budgets, Desktop fixture (D072.2, SDK-4) by @ViktorJannicke in #1119
- AOT size: Desktop host diet (D072.2, S4) by @ViktorJannicke in #1118
- Document Visual Studio debugging with Runic DevKit (SDK-2, D070) by @ViktorJannicke in #1117
- File watching: releasing one lease keeps another lease of the same sink watching (#1123) by @ViktorJannicke in #1126
- Single-file publish of Views apps (NETSDK1191) and a CI guard (D072.7, FD3) by @ViktorJannicke in #1124
- AOT size: a limit allows the metric's alignment noise, as the growth check does by @ViktorJannicke in #1127
- CI: bound Ubuntu package downloads by progress, rotate mirrors and save the archive cache early (#1129) by @ViktorJannicke in #1130
- Train: adopt Runic Translations 0.14.0 (TrainCommit e4073d71; SDK-5) by @ViktorJannicke in #1128
- AOT size: LINQ and generic diet in Views and Navigation (D072.2, S4/S5) by @ViktorJannicke in #1120
- Store identical assets once in the asset archive (Part of #1109) by @ViktorJannicke in #1122
- dotnet runic dev: fix the CDP adapter's reply ordering and the Window-restart breakpoint race (#1108) by @ViktorJannicke in #1132
- Train: feed exit for Runic Translations 0.14.0 (published) by @ViktorJannicke in #1133
- AOT size: LINQ operator and record diet in Views and Navigation (#1109, D072.2) by @ViktorJannicke in #1135
- Bridge generator: shared codecs per assembly and one getter per property (−13.2 KB per ViewModel) by @ViktorJannicke in #1134
- AOT size: region guest, page scripts and server switch for Desktop apps (part of runic-sdk#1109) by @ViktorJannicke in #1136
- Views targets: F5 in Visual Studio skips the build while dotnet runic dev runs (#1121) by @ViktorJannicke in #1137
- Bridge generator: run async commands through one shared state machine (−10.7 KB per ViewModel) by @ViktorJannicke in #1138
- WebKit CDP adapter: a pause at the just-removed instrumentation breakpoint resumes silently (#1139) by @ViktorJannicke in #1140
- Views: the host-named bootstrap script copy warns that it is deprecated (FD4, D072.11) by @ViktorJannicke in #1143
- Bridge generator: descriptor tables as data (−15.7 KB per ViewModel; 56.3 → 16.7 KB since 0.21) by @ViktorJannicke in #1144
- Framework-dependent publish: only the target OS's Runic platform assemblies (FD1, D072.9) by @ViktorJannicke in #1145
- Development-only views and members ([RunicDevelopmentOnly]) by @ViktorJannicke in #1147
- docs: framework-dependent publishing, per-mode sizes and costs (FD2, FD8) by @ViktorJannicke in #1141
- FD1: Windows and macOS publishes of a GTK 4 app keep Runic.Desktop.Gtk4, now tested (#1150) by @ViktorJannicke in #1154
- Scaling: framework-dependent size budgets (FDD-6) by @ViktorJannicke in #1152
- CI: key the Ubuntu archive cache by resolved package versions (#1131) by @ViktorJannicke in #1153
- tests: the tsserver test stops its Bun child on every path (#1125) by @ViktorJannicke in #1155
- Repository publishes match package consumers: no BridgeCodegen or XML docs, FD1 for project references (FD5, #1151) by @ViktorJannicke in #1156
- Release 0.22.0 by @ViktorJannicke in #1157
Full Changelog: v0.21.0...v0.22.0