Repository navigation
Runic SDK 0.23.0
Pre-releaseRunic SDK 0.23.0
Install matching 0.23.0 packages from NuGet and npm;
Runic.Application.Views.CsWebUi is 0.23.0-preview.1 and the new
Runic.Spelling is 0.23.0-preview.1.
Tested with Runic Translations 0.15.1 and Runic Command Line 0.14.0.
0.23.0 is a consolidation release before 1.0. It closes the open work on the C#
side: it removes what 0.22 deprecated, builds the commitments that were still
planned for later, and fixes what a 1.0-readiness sweep found. The host-named
Views client scripts runic-desktop-views.js and runic-cswebui.js, the
./experimental re-export of onBridgeDraining, the error tombstones of types
removed in 0.9 and 0.13, and vite-plugin-runic's reader of the 0.20 source-map
name are gone.
For application code, a bridged Interaction can set its lifetime, including
no deadline for a question a person is still reading (#1146), and an
asynchronous command can take its progress as an IProgress<double> parameter
(#1180). The side panel takes dropped files (#1189), a menu bar item can open
the developer tools, now also WebKit's Web Inspector on Linux (#1188), and an
application supplies one icon from which Runic derives the Windows executable's
icon, the default window icon and the macOS development bundle's icon (#1207).
A trimmed or NativeAOT publish leaves the Bridge blob and upload machinery out
when no Bridge uses it, 365 KB of the size fixture's CS-WebUI application on
linux-x64 (#1193).
dotnet runic dev gives --browser an address of its own for each run, which
admits one browser by a one-time code (#1187), lists a frontend's compile errors
in the IDE's error list (#1160), and no longer leaves the development server
running on Windows after it stops (#1163). JavaScript debugging of the WebKitGTK
Window on Linux is no longer a preview (#1171). The CS-WebUI host (preview) keeps
a guarded window open while its guard decides (#1148), restores window placement
(#1149), drains a closing Window as Runic Desktop does (#1190), now opens the
Development DevTools Protocol endpoint that IDE debuggers attach to (#1221), and
shows its own pages in the application's language. The first release of
Runic.Spelling (preview) checks spelling in the application itself, in the
language each text is written in (#1164). On WebView2, after a screen reader
presses a button in the page, announcements are spoken and typed keys reach the
page (#1181, #1203, #1204).
0.23.0 also hardens the development tools and the new spelling package: dev's
browser address and debugging endpoints, the pages dev leaves in the output,
the CS-WebUI debugging browser's profile, and the files Runic.Spelling
installs. See Fixes and the
security guide.
The 0.23 release train is Runic Command Line 0.14.0, Runic Translations 0.15
and runic-sdk 0.23.0; Runic's editor extensions 0.23.0 follow this release.
runic-sdk 0.23.0 requires Translations 0.15.1, a patch that fixes how external
and overlay packs are loaded (advisory
GHSA-24g5-pcc5-4fg7).
An application that generates ESM translations regenerates it with 0.15.1 to get
the fix. Upgrading from 0.22 lists what an application
changes, and the
migration guide
collects it.
Highlights
- What 0.22 deprecated is gone: the host-named Views client scripts
runic-desktop-views.jsandrunic-cswebui.js, the./experimental
re-export ofonBridgeDraining, the error tombstones of types removed in 0.9
and 0.13, and vite-plugin-runic's reader of the 0.20 source-map name
(Upgrading from 0.22). - For application code:
an Interaction's lifetime, with questions that have no deadline,
operation progress through anIProgress<double>parameter (#1180),
drops onto the side panel,
a menu command that opens the developer tools,
and the application icon from one source. dotnet runic dev:
--browserhas an address of its own for each run, for one browser,
frontend errors appear in the IDE's error list,
and JavaScript debugging of the WebKitGTK Window is no longer a preview.- CS-WebUI (preview) catches up with Runic Desktop:
a guarded Window keeps its WebView window open,
window placement,
the close drain,
its own pages in the application's language
and a working Development DevTools Protocol endpoint (Fixes). Runic.Spelling,
a new preview package, checks spelling in the application itself, with
English bundled and other languages downloaded on request.- A trimmed or NativeAOT publish leaves Bridge blobs and uploads out when no
Bridge uses them (Behaviour and output changes),
and on WebView2 screen reader announcements and keyboard focus work after a
screen reader presses a button in the page (Fixes).
Upgrading from 0.22
Update every Runic NuGet and npm package to 0.23.0 together and rebuild, so that
the generated clients and Bridges are regenerated. Views protocol 4 is
unchanged: a 0.22 page and a 0.23 host still connect, and Bridges that 0.22's
generator wrote keep working with the 0.23 runtime. Rebuild the frontend with
0.23 for questions that last longer than ten minutes
(Interaction lifetime).
Most applications change little. A page that still loads
runic-desktop-views.js or runic-cswebui.js loads runic-views.js, and an
import of onBridgeDraining from @runic-artifex/views/experimental moves to
the root entry; both stopped working in 0.23. An application that uses Runic
Translations moves every Translations package, NuGet and npm, to 0.15.1, and
one that uses Runic Command Line itself moves to 0.14.0. A VS Code launch
configuration that opens http://127.0.0.1:9224/ for dotnet runic dev --browser opens the code page instead. A project that treats warnings as errors
and has no square PNG icon of at least 256 px sees the new RUNICICON warnings
(Behaviour and output changes). Update Runic's
editor extensions to 0.23.0 once they are published.
- Removed: the host-named copy of the Views client script,
runic-desktop-views.jsandrunic-cswebui.js
(D072.11). Deprecated in 0.22, the copy is gone: the host packages copy their Views client intowww/only as
runic-views.js, in builds, publishes andRunicApplicationFrontendDelivery=Embedded. That saves 5 KB (Runic
Desktop) or 21 KB (CS-WebUI) per publish. A page must loadrunic-views.js:
<script src="runic-views.js"></script>afterwebui.js, as the templates do. A page that still loads
runic-desktop-views.jsorrunic-cswebui.jsgets a 404 for it and no Bridge, so its Views never connect; the
build reports warningRUNICBRIDGE019naming the page and the fix. A project that references more than one host
setsRunicApplicationHost(desktoporcswebui), or the build copies norunic-views.js. A copy of the script
that the application keeps under the old name itself is served as before but is not updated by the build; rename it
torunic-views.js. Awww/folder that an earlier build left with the old copy keeps that file until it is
cleaned (dotnet cleanor deletingbin/), and the old copy still logs its deprecation warning there. - Removed:
onBridgeDrainingfrom@runic-artifex/views/experimental(D069.3). Deprecated in 0.22, when the
close drain graduated (RUNICDESK105), the re-export is gone: importonBridgeDrainingfrom
@runic-artifex/views, the same function. An import from./experimentalnow fails to compile or to bundle. See
From 0.22 to 0.23. - Removed: the error tombstones of types removed in 0.9 and 0.13 (D077.1). Since 0.14, nine members of
Runic.Application.Views(RunicBridgeJsonIgnoreAttribute,IAsyncBridgeTransport,IBridgeUtf8Transport,
IBridgeArguments),Runic.Application.Views.ReactiveUIand.Reactive(RunicReactiveSchedulerProviderwith
itsInstallMainThreadScheduler,IRunicReactiveSchedulerProvider),Runic.Application.Testing
(BridgeTestArguments) andRunic.Platform.Runtime(INativePickerOwner) remained as[Obsolete]errors whose
message named the replacement. They are gone, so code that still names one fails withCS0246instead ofCS0619;
the replacements are in Removed types. dotnet runic dev --browserhas an address of its own for each run, and needs the one-time code (#1187). The
address ishttp://<label>.localhost:9224/, with a random label for eachdevrun;http://127.0.0.1:9224/and
http://localhost:9224/answer 403, as does the address without the code. AWindow in Chromelaunch configuration
generated before 0.23 opens"url": "http://127.0.0.1:9224/"; replace that line with
"file": "${workspaceFolder}/obj/runic/dev-browser.html", as the template now does, or open the address that the
[dev] Browser:line prints. A configuration that matches the page by URL (urlFilter) uses
http://*.localhost:9224/*. The session file'sbrowser.urlandbrowser.windows[].urlhave*in place of the
label; an IDE that reads the session file opensbrowser.codeFile. One browser is admitted at a time: opening the
page in another browser ends the first one's admission.- Removed: vite-plugin-runic's reader of the 0.20 source-map name
runic-bridge-sources/1(D077.18). 0.21 renamed
the Bridge generator's development source map (sources.json, which/__runic/sourcesserves) to
runic.views.bridge-sources/1and kept reading the old name for one minor release.@runic-artifex/vite-plugin-runic
now reads only the new name; a map with the old one counts as no map, so Runic Inspect shows no source locations
and/__runic/opencannot open them. Only a 0.20 generator writes the old name: rebuild the application with 0.23.0,
which regenerates the map. - The session file's
browser.urlis a pattern, not an address. Since 0.21 thedotnet runic dev --browser
session file (runic.application.tool.dev-session/1) listed the page's address inbrowser.urland
browser.windows[].url. In 0.23 the address has a secret label for each run (#1187), so these properties hold a
pattern with*for the label,http://*.localhost:9224/, which a browser cannot open. The schema name stays/1,
as no first-party reader uses the property; this is the one change to an existing property within it. A reader that
openedbrowser.urlopens the newbrowser.codeFileinstead, which admits the browser and then opens the address;
the patterns still serve to match the page by URL, such as in a launch configuration'surlFilter. - Runic Translations 0.15 and Runic Command Line 0.14.
Runic.Application.Views.Translationsrequires Runic Translations
[0.15.1, 0.16.0), so an application that uses it moves every Translations
package, NuGet and npm, to 0.15.1. The template pins Translations 0.15.1 three
ways: thedotnet-runic-translationstool,Runic.Translationsand
.Build, and@runic-artifex/vite-plugin-runic-translations;dotnet runic doctorchecks for Translations 0.15.1 and Command Line 0.14.0. Runic's own
catalog is generated by Translations 0.15 for RMF2 runtime ABI 5 (binary
locale data and a deflated message table), so it needs the 0.15 runtime: keep
Runic.TranslationsandRunic.Translations.Buildat the same version. ESM
output stays JSON, so pages are unaffected.
Translations 0.15.1 fixes how external and overlay packs are loaded. Generated
ESM carries its own runtime, so an application with ESM output regenerates it
with 0.15.1 to get the fix: a build with the 0.15.1 Vite plugin or
dotnet-runic-translationstool does that.@runic-artifex/views-translations
0.23.0 is generated with 0.15.1.
dotnet-runic,Runic.Createand theRunic.Assetspacker bundle Runic
Command Line 0.14.0. An application that uses Command Line itself moves to
0.14.0 with Translations 0.15, whoseRunic.Translations.CommandLinerequires
[0.14.0, 0.15.0). Command Line 0.14 retires thefaults.RCLI4001key and
its JSON reader rejects a duplicate member name anywhere in a frame;
Translations 0.15 removes the second override path, so a message in your own
catalog named after a Command Line framework key no longer has an effect
(warningRTR0107). Neither needs a change in Runic SDK. See the
Translations 0.15.0 notes,
the
Translations 0.15.1 notes
and the
Command Line 0.14.0 release.
Behaviour and output changes
-
A trimmed or NativeAOT publish leaves Bridge blobs and uploads out when no Bridge uses them (#1193). The generated
codecs of a member that holds aRunicBlobor takes aRunicUploadnow mark their assembly
([assembly: AssemblyMetadata("Runic.Application.Views.Blobs", "true")]). A trimmed or NativeAOT publish in which
neither the application nor a referenced assembly is marked or namesRunicBloborRunicUploadin its metadata (a
library whose Bridges a generator before 0.23 wrote) turns the new feature switch
Runic.Application.Views.Blobsoff: the producer no longer listsblobs/1in its hello reply or grants uploads, the
CS-WebUI host starts no blob endpoint, and Runic Desktop serves no blob exchange. The trimmer then removes the
Window's blob store, its upload folder and the CS-WebUI loopback blob server. On linux-x64 the scaling suite's
CS-WebUI fixture is 365 KB smaller (7,431,440 instead of 7,796,672 bytes with 9 ViewModels), its Runic Desktop
fixture 163 KB and its Translations fixture 353 KB. Such an application's pages get no upload grant, and
client.uploadrejects withunavailable, which nothing in the application could have read anyway. Builds,
dotnet runand untrimmed publishes keepblobs/1; set<RunicBridgeBlobs>true</RunicBridgeBlobs>to keep it in
every publish, for example when only reflection reaches aRunicBlob.
See Making the executable smaller. -
An application that sets no
ApplicationIcongets one (#1207). Whenicons/icon.png(or the file
RunicPackageIconnames) exists, the build now derives the executable's Windows icon from it, Runic Desktop windows
withoutIconFileshow it on Windows and on macOS outside a bundle, and the macOS development bundle has it as
icon.icns. An application with anApplicationIconkeeps its own.icofor the executable, and its windows now
show that icon instead of the generic one. If the icon is not a square PNG of at least 256 px, the build reports
warningRUNICICON001,RUNICICON002orRUNICICON003and goes on without the derived icon; a project that treats
warnings as errors then fails. Replace the icon, or set
<RunicApplicationIconGenerationEnabled>false</RunicApplicationIconGenerationEnabled>to derive nothing.
An application created from an earlier template can deleteicons/icon.icoand itsApplicationIconline, as the
0.23 template does. -
RunicDevelopmentOnlyViewsandRunicBridgeBlobswarn on a value other thanautoortrue(API-30). Both
takeauto(the default, also when empty) ortrue, compared without case. Until now another value, such as
falseor a typo, silently meantauto; it is now warningRUNICBRIDGE075, and the build still goes on asauto.
Neither has afalse: development-only views and Bridge blobs can't be left out of a build or an untrimmed
publish. MSBuild properties now also says that the runtime feature-switch names the
targets add, such asRunic.Application.Views.Blobs, are not settings: set the MSBuild property instead.
The lifetime of an interaction, and questions without a deadline (#1146)
A bridged ReactiveUI Interaction always gave the page two minutes; after that the handler's signal aborted and
Interaction.Handle threw RunicInteractionTimeoutException in the command that asked, also while a person was still
reading a modal question. Set the lifetime on the property with [RunicInteractionTimeout], in milliseconds up to
24 hours, or Timeout.Infinite for none:
[RunicInteractionTimeout(Timeout.Infinite)]
public Interaction<ConfirmationRequest, bool> ConfirmAction { get; } = new();The Bridge generator passes it to the generated descriptor; the TypeScript and the contract hash do not change.
ViewQuestion<TInput, TOutput>, ReactiveInteractionDescriptor.Create and BridgeInteractionRouter take
Timeout.InfiniteTimeSpan too, and their maximum rises from ten minutes to 24 hours. A question without a deadline
still ends when the command that asked is cancelled, its page unmounts or disconnects, or the Window closes, with
RunicInteractionCancelledException. A value out of range is RUNICBRIDGE073, and the attribute on a view question
RUNICBRIDGE074, both new errors of the generator. See
Interaction lifetime.
On the wire, the new protocol 4 feature open-ended-interactions/1 lets a request without a deadline omit
expiresAt, and the page keeps a deadline beyond ten minutes, however distant, without arming a browser timer longer
than 231 − 1 ms. A page without the feature receives a deadline 24 hours away for such a request. A page
built with @runic-artifex/views before 0.23 still aborts its handler after ten minutes, whatever the lifetime, and
the question then ends with RunicInteractionCancelledException: rebuild the frontend with 0.23. See
Interaction deadlines.
CS-WebUI: a guarded Window keeps its WebView window open (#1148, preview)
Runic.Application.Views.CsWebUi now needs CsWebUi 2.5.0-beta.4.10, whose WebView windows can refuse the user's close.
A Window with GuardClose in a UseWebView window on Windows (WebView2) or Linux (WebKitGTK) stays open while its
CanCloseAsync decides the close button, Alt+F4 or the window manager's close, as it does on Runic Desktop: the window
closes once the guard allows, and stays as it was when it refuses. RequestCloseAsync asks the same guard and joins a
decision the user started.
A browser window, a macOS WebView, a window that RunicCsWebUiHostOptions.ShowWindow shows and serve-only mode still
cannot keep a window open: there a guarded Window opens unguarded and logs WindowCloseGuardUnavailable (event 1053),
which now names the reason. See
Closing a window.
CS-WebUI: window placement (#1149, preview)
A UseWebView window of Runic.Application.Views.CsWebUi on Windows (WebView2) and Linux (WebKitGTK) now reports its
placement, the restored bounds and whether it is maximized, in IRunicWindowPresentation.Placement, also after the user
closed it, and takes one with SetPlacementAsync, MaximizeAsync and RestoreAsync. The new
RunicCsWebUiHostOptions.Placement restores a saved placement as each Window opens, as RunicDesktopHostOptions.Placement
does on Runic Desktop, and keeps it on a monitor that exists now. WebUI raises no event when a window moves, so the host
reads the placement every 500 ms while the window is shown and once more when it closes.
Wayland gives the size and maximized state without a position. A browser window, a macOS WebView and a ShowWindow
window report no placement and take only an initial size and a position within WebUI's limits. See
Window placement.
Frontend errors in the IDE's error list (#1160)
Under dotnet runic dev, a frontend module that Vite cannot compile (a TSX syntax error, an import that does not
resolve) is now also one line per error in MSBuild's form, with the file's absolute path and the 1-based position, from
the Runic Vite plugin:
[vite] /path/to/App/Frontend/src/App.tsx(29,50): error RUNICP008: [vite:oxc] [PARSE_ERROR] Expected corresponding JSX closing tag for 'p'.
VS Code's $msCompile, the runic-app template's .vscode/tasks.json and Visual Studio's Error List read it like a
build error. [vite] [runic] Frontend errors cleared follows once the modules compile again, so an IDE can remove the
rows (see the tool's IDE contract and
RUNICP008). The position comes from Oxc's diagnostic, not from Vite's
File: line, which under Bun names a place in Vite's own code. There is no type check.
Runic.Spelling: an application's own spell checker (#1164, preview)
The new Runic.Spelling package (0.23.0-preview.1, preview, outside the 1.0 promise like
Runic.Application.Views.CsWebUi) checks spelling in the application itself, with Hunspell dictionaries through
WeCantSpell.Hunspell, so each text is checked in the language it is written in. The webview's checker cannot do that:
on WebKitGTK and macOS it belongs to the process, and WebView2 cannot be told the languages at all.
SpellChecker.Check(text, skipRanges)returns the misspelled words as UTF-16 offsets, leaving out the ranges the
application names (MessageFormat 2 placeholders and markup, mentions, comments), addresses, numbers, abbreviations
and single letters;Suggestoffers corrections. Hyphenated compounds are checked per part, and straight and curly
apostrophes are the same. The application's own words and the user's (SpellingUserWords, a word list all Runic
applications share) count as spelled right.- English (
en_US,en_GBfrom SCOWL) ships in the package, and its build targets copy it into the application as
dictionaries/(RunicSpellingBundledDictionaries=falseleaves it out). The computer's Hunspell dictionaries are
used too, including those of a Nix-built application'sspellingDictionaries. - Other languages download when the user asks:
SpellingDictionaries.GetAvailability(tag)says whether a language is
bundled, downloaded, on the system, downloadable (with its size) or unavailable, andDownloadAsyncinstalls a
dictionary of the pinned catalog (wooorm/dictionaries, and LibreOffice's for German) after checking every file's
SHA-256, into a directory all Runic applications of the user share, with its license beside it.
The dictionary for a BCP 47 tag is chosen by the same code as Runic Desktop's platform checkers. See
the spell checking guide and
Runic.Spelling.
JavaScript debugging of the WebKitGTK Window is no longer a preview (#1171)
dotnet runic dev's DevTools Protocol endpoint for the Window's WebKitGTK pages on Linux (since 0.21) is out of
preview: its CI job, VS Code's JavaScript debugger through the endpoint on GTK 3 and GTK 4, ran through 0.22 as D066.39
required. The docs, the runic-app template's README and launch configurations, and dev's [dev] Debugging: line
drop the label.
The docs now say what was checked by hand: the template's Window + WebKitGTK (Linux) in VS Code (a C# breakpoint, then
a Frontend/src breakpoint through the endpoint), C# Dev Kit's "type": "dotnet" configuration on the launch profile,
Visual Studio's F5 on the launch profile with dotnet runic dev --no-window, and Runic DevKit's Debug the Window and
Attach to the Page (since 0.22). Runic does not test Rider or the steps of Visual Studio's own Attach to Process dialog.
The dotnet-runic README shows the C# Dev Kit configuration.
Operation progress through an IProgress<double> parameter (#1180)
An asynchronous command can take its operation's progress as a parameter, the usual .NET pattern, instead of calling
the ambient RunicOperationProgress.Report (API-10, D067.12):
[RelayCommand(IncludeCancelCommand = true)]
private Task ImportAsync(IProgress<double> progress, CancellationToken token) =>
importer.ImportAllAsync(progress, token);The Bridge generator binds the parameter as CommunityToolkit binds the CancellationToken, for a CommunityToolkit
IAsyncRelayCommand<IProgress<double>> and a ReactiveUI ReactiveCommand<IProgress<double>, TResult>. The page sends
no input for it, and the generated client calls import() and startImport() without an argument. Started as an
operation, the command receives a reporter bound to that operation: watching pages receive its reports as progress,
as before, also when a library reports from a worker thread, and reports after the operation ended are ignored.
Through the awaited call, outside an operation, it receives a reporter that does nothing. The new
RunicOperationProgress.Current is that reporter, for .NET code that runs such a command itself or passes the
progress on. The analyzer accepts the parameter as the generator does. See
Operations.
dotnet runic dev --browser: an address of its own for each session, for one browser (#1187)
--browser now serves the Window at http://<label>.localhost:9224/, a proxy to the serve-only Window's pages instead
of a redirect to the Window's own address. The label is random for each dev run and stays the same across its Window
restarts, so a tab keeps its address when dotnet watch restarts the Window. A Runic Desktop page reloads itself onto
the new Window (the stopping Window's close command reaches it as the Bridge's token refusal), and the JavaScript
debugger's breakpoints stop again; reload a CS-WebUI tab. Chromium browsers (Chrome, Edge) and Firefox resolve names
under .localhost to the loopback interface themselves.
- An origin for each session. Pages, service workers, storage and cookies of an earlier session or another project
do not reach a later one. The address answers only its own name:127.0.0.1:9224,localhost:9224and other labels
get 403. - One browser, by a one-time code. The
[dev] Browser:lines carry the address with the current code
(http://<label>.localhost:9224/?code=…), anddevwritesobj/runic/dev-browser.html, a page only you can read
(mode 0600, or an access list of your account alone on Windows), which opens it with the newest code. The session file
names that page asbrowser.codeFileand lists the address with*for the label. The code admits one browser with
dev's host-onlyHttpOnly,SameSite=Strictcookie and is then replaced; a new admission ends the previous
browser's, and closes its open connections. Every other client gets 403. - Bearer secrets. The label, the code and the cookie admit whoever has them. The browser sends the cookie to
<label>.localhoston any port, sodevkeeps the label where it keeps the code: its[dev] Browser:output and the
code page. - The template's
Window in Chromeopens that page ("file": "${workspaceFolder}/obj/runic/dev-browser.html")
instead of a fixed URL, so it also follows a moved port. A configuration that matches the page by URL uses
http://*.localhost:9224/*. - The Window's side.
devsetsRUNIC_APPLICATION_SERVE_ORIGINfor the serve-only Window: Runic Desktop admits
the address as an origin of its pages and connects their Bridge through it, on the page's own host; Runic's CS-WebUI
host admits it at its upload endpoint. Both take only anhttporigin onlocalhostor one label under.localhost.
See Debug the page in Chrome
and Development server security.
A menu command that opens the developer tools (#1188)
DesktopMenuItem.OpenDevToolsCommandId (runic.devtools.open) is the one command id with the reserved runic. prefix
that a menu bar item may name. Runic Desktop runs it itself for the key window, before the window's and the
application's command targets: it opens WebView2's DevTools window on Windows and, new, WebKit's Web Inspector on Linux
(GTK 3 and GTK 4), where DesktopWindow.OpenDevToolsAsync now opens it too. The item is enabled only in Development, in
a window whose developer tools are on; it is disabled on macOS (WKWebView opens its Web Inspector only from Safari), in
an installed browser, on CS-WebUI and in a custom window host, and context menus and status icon menus refuse it.
MenuBar = developing
? [new DesktopMenu("View", [new DesktopMenuItem("Developer Tools", DesktopMenuItem.OpenDevToolsCommandId)])]
: [],The runic-app template declares it as View ▸ Developer Tools in Development, on Windows and Linux. See the
Runic.Desktop README.
Drops onto the side panel (#1189)
The side panel takes drops like the window's page, on every host where it opens: WebView2, WKWebView, and WebKitGTK
on GTK 3 and GTK 4. 0.19 refused them (D062.6); D077.2 builds them before 1.0.
- Files dropped on the panel reach the same API as the page's, in the same queue:
IRunicFileDropTargeton the
Window's root ViewModel andDesktopWindow.FilesDropped. The newRunicFileDrop.InSidePaneland
DesktopFileDropEventArgs.InSidePaneltell the panel's drops apart. The window sets the flag from the view that
received the drop, so unlike thedata-runic-drop-targetlabel it can be trusted. - The rules are the page's: native paths only, the panel page's label and
data-runic-drop-effect, no drops from
frames of another origin, a hosted region's frame in the panel drops to its guest, macOS file promises, and no
navigation to a dropped file. Text and other content reach the panel page's owndropevent. - Drops onto the panel are smoke-tested on GTK 3, GTK 4 and Windows x64. win-arm64 stays unverified like the page's
(#391), and macOS, like the page's, has no drag in CI.
See the side panel guide.
The close drain on CS-WebUI and in serve-only mode (#1190)
A Window with a close drain (RunicWindowOptions.CloseDrain) now drains on two more hosts instead of closing at once
with WindowCloseDrainUnavailable (event 1055):
- CS-WebUI (preview). A
UseWebViewwindow on Windows (WebView2) and Linux (WebKitGTK) stays open after the user's
close, orRequestCloseAsync, was decided, with its page connected and receivingclosingwithdraining: true,
until the Window's operations, awaited commands and drained scopes have ended, as Runic Desktop's embedded window
does. A second user close meanwhile is ignored. The newRunicCsWebUiHostOptions.CloseDrainsets the drain of every
Window. - Serve-only mode (
RUNIC_APPLICATION_SERVE_ONLY=1), on Runic Desktop and CS-WebUI. The end of serving, a line on
standard input, is the Window's close: with a drain the server keeps serving the Window's pages until its work has
ended, and only then doesWaitForCloseAsyncreturn. A browser tab that closes, the last one included, is not a
close, since the server outlives its clients.
An installed browser, and on CS-WebUI a browser window, a macOS WebView and a ShowWindow window, still close at once
with event 1055 (D077.3): a browser closes its window without asking. Runic Desktop's serve-only mode ends the drain at
a termination signal, and the CS-WebUI host handles none. See
Closing after the Window's work has drained.
The application icon from one source (#1207)
An application supplies one icon, the package icon of dotnet runic package (RunicPackageIcon, by default the
512 px icons/icon.png), and Runic derives the rest from it:
- Windows executable. When the project sets no
ApplicationIcon, the build writes
obj/<configuration>/<framework>/runic-icon/application.ico(16, 20, 24, 32, 40, 48 and 64 px as 32-bit bitmaps,
256 px as PNG) and uses it asApplicationIcon, the icon in Explorer and on the taskbar. - Windows. A Runic Desktop window without
IconFileshows the application's icon: from the executable's icon
resource, or from the application's assembly when it runs asdotnet app.dll. On macOS outside a bundle with an
icon, such asdotnet app.dll, the package icon, which the build copies beside the executable, becomes the
application's icon. GTK is unchanged: it takes the icon from the theme by the application ID. - macOS development bundle. The bundle that
dotnet runstarts hasContents/Resources/icon.icnsand
CFBundleIconFile, so the Dock shows the icon during development. - Template.
dotnet new runic-appno longer has a hand-madeicons/icon.icoand anApplicationIconline.
The .ico and .icns are written by managed code in Runic.Platform's build files, without native libraries or tools,
so Linux, Windows, macOS and Nix builds write the same bytes. Any standard PNG works (every colour type and bit depth,
palette transparency, interlacing); the sizes are scaled down with an area filter in premultiplied alpha. An icon that
is not square, smaller than 256 px or not a readable PNG is a warning (RUNICICON001 to RUNICICON003), and
RunicApplicationIconGenerationEnabled=false turns it all off. See
the application icon.
CS-WebUI's own pages and banners in the application's language (cs-webui#32, preview)
CS-WebUI's 404 and 500 pages and the connection banners of WebUI's bridge ("Failed to connect to the backend
application") now take DesktopPlatformTexts.Current, which Runic.Application.Views.Translations keeps in the
application's language, with the window's locale as their language. DesktopPlatformTexts has six new texts for them
(ServerErrorTitle, ServerErrorMessage, ConnectionErrorLabel, ConnectionFailedMessage, ConnectionLostMessage,
WebSocketUnsupportedMessage), and the runic-views catalog has them in English and German. An embedded frontend's
missing file now gets a Resource Not Available page instead of an empty 404. runic-views.js loads the banners'
script from the window's /_runic/cswebui/texts.js, which the window's file handler answers; a window served from a web
root folder now gets that handler too, with WebUI's authentication cookie kept on.
WebUI's own Access Denied page and its 404 page for a file missing from a web root folder stay English (D061.8): WebUI
sends them itself. See
Runic's own text.
Fixes
dotnet runic dev's debugging endpoint for the WebKitGTK Window (Linux) no longer loses a file's breakpoints in VS Code's
JavaScript debugger after a few reloads in quick succession, such as Vite's full reloads while files change. The
endpoint passed WebKit's events on with a delay. In such a reload it could still tell js-debug of the scripts of a
page WebKit had already left, right before telling it that the page was gone. js-debug then kept that page's
original source of a file, bound to a script that no longer existed, and from then on set a breakpoint in that
file only as a guess at its path: on the next page, or after the Window restarted, the debugger did not stop
there. The endpoint now leaves out the scripts of a page that WebKit already replaced. It also no longer hides
one of two scripts whose source maps name their source alike (@vite/clientandvirtual:runic/client), whose
console output had kept js-debug from clearing a page's scripts (#1108).- A NativeAOT application on the native server no longer loads ICU before its first window has its page, as
Packaging describes. Since 0.22.0, the
generated reader of the Bridges' descriptor tables (RunicShared.Tables.Bridge.g.cs) parsed member ids with
int.Parse(…, CultureInfo.InvariantCulture), which initializes the process's cultures and so loads ICU, on the
first window's Bridge: about 5 MiB of memory more at startup on Linux (21.4 instead of 16.6 MiB for the Desktop
example; 21.8 instead of 17.1 MiB for arunic-apptemplate application). It now reads the ids as plain digits.
Rebuilding with 0.23.0 regenerates the reader (#1159). - The
dotnet runic devtasks in therunic-apptemplate's.vscode/tasks.json(--editor vscode) now find the
file of a build error after an edit.devprints the lines of the processes it starts after their label, so a
rebuild's errors read[host] /path/App/File.cs(18,5): error CS1002: …, and the tasks'$msCompiletook
[host] /path/App/File.csfor the file, which VS Code could not open. The tasks now use$msCompile's pattern
after an optional[host],[app]or[vite]label, as the
IDE contract shows. An existing project can copy the
problemMatcherfrom a new one (#1161). - On Windows,
dotnet runic devno longer leaves the Vite development server andrunic-translations serverunning
after it stops. They outlived the package manager (bun or npm) thatdevstarted, anddevended only that
package manager's tree, which no longer reached them once it had exited. An IDE that readdev's output then
waited for pipes those processes still held, and they kept the server's port.devnow runs the frontend's
development server or watcher in a kill-on-close Job object and ends the job at the stop, and Windows ends it when
devitself is killed (#1163). - When
dotnet runic devstops, the development pages it wrote into the output'swww/no longer stay behind. They
loaded their script from the development server's loopback port, which another local process could bind oncedev
had stopped and then serve the application script to a Window started from that output without a build (DEV-SEC-48
of the 2026-11 security review).devnow replaces each such page, unless a build replaced it already, with a page
whose content security policy refuses every script and request; the next build copies the frontend's pages back. A
devkilled by force still leaves its pages until the next build, as Security
says (#1178). - On WebView2, NVDA says a
DesktopWindow.AnnounceAsyncmessage also after a screen reader or another UI Automation
client presses a button in the page. WebView2 activates the window to carry out the press and can leave the keyboard
focus on the window itself while the button stays NVDA's focus; the window then announced the message with a UI
Automation notification, which NVDA speaks only from the application of its focus, WebView2's browser process, so it
said nothing. The page now announces the message in its live region in that case too, as it does while it has the
focus (#1181). - In a WPF window, NVDA says an assertive announcement of
WpfPlatformServices.ForWindowalso right after a screen
reader or another UI Automation client presses a button in aRunicWebView's page. WebView2 activates the WPF window
to carry out the press, and for a moment the keyboard focus is on the WPF window itself or on the control's own child
window while the button stays NVDA's focus; the WPF window then announced with a UI Automation notification, which
NVDA ignored. The page now announces in its live region in that case too, as Runic Desktop's window does (#1181), and
the WPF window still announces while one of its own controls has the focus (#1203). - On WebView2, keys typed after a screen reader or another UI Automation client presses a button in the page reach the
page again. WebView2 activates the window to carry out the press and could leave the keyboard focus on the window
itself, which has no control of its own, while the button stayed the screen reader's focus, so the keys went to the
window. Whenever the window itself receives the focus, as after that press or when the user switches back to it, it
now hands the focus to the page, or to the side panel when that had it last; the page focuses the element it had
before (#1204). - On Windows, a failed WebView2 call (creating the WebView, a DevTools protocol call, installing, listing or removing a
browser extension, a document-start script) reports the error of its own HRESULT as the inner exception. It could
instead report an unrelated, earlier exception that a failed COM call had left on the UI thread (#1208). dotnet runic dev's debugging endpoint for the WebKitGTK Window (Linux) no longer detaches VS Code's JavaScript
debugger when the Window takes long to exit beforedotnet watchrestarts it. The endpoint waited 1.5 seconds after the
page went away and, when the old Window's inspector was still open then, took the page as closed in a running Window
and ended the session, just before the restarted Window came. It now waits while that Window process runs: the
session continues on the restarted Window's page, ends when another page takes the old one's place in a Window that
keeps running, and ends when no restart comes within 3 minutes ordevstops (#1210).- CS-WebUI: the page's DevTools Protocol endpoint opens (#1221). In 0.22 the Development endpoint that
dotnet runic dev --debug-endpoint,--no-windowand the template's(CS-WebUI script debugging)profile ask for
withRUNIC_WEBUI_REMOTE_DEBUGGING_PORTwas built into Runic Desktop's installed-browser windows only, so a
--host cswebuiapplication's Chrome or Edge started without--remote-debugging-port:devprinted no
[dev] Debugging:line, nothing listened on 9225, and Visual Studio's Attach to Process could not reach the page. The
CS-WebUI host now passes the port to the browser WebUI starts, by the same rules (Development, an untrimmed build, a
Chromium-based browser window), confirms the endpoint through/json/versionand prints the
RUNIC_APPLICATION_DEBUG_ENDPOINTlinedevreads.UseWebView,ShowWindowand serve-only windows open none.
WebUI's custom parameters replace its Chromium defaults, so the host passes them itself: a
WebUiWindow.SetCustomParametersinConfigureWindowreplaces the endpoint, andSetProxythere does not apply
while it is on. The process's windows share one browser, so the first window's endpoint serves them all. See
CS-WebUI pages in a JavaScript debugger. - A region's embedder no longer comes from a page that just closed (#1222). For a short time after a page's
connection closed, the surface still reported the origin it had admitted for that page. A region declared in that
time took the closed page's origin as its embedder. The origin now ends when the page's admission ends, before the
connection count drops. - CS-WebUI: the Development DevTools Protocol endpoint runs in a profile of the run's own. When
RUNIC_WEBUI_REMOTE_DEBUGGING_PORTopens the endpoint, the browser no longer uses WebUI's
.WebUI/WebUI<Browser>Profile, which every WebUI application of the user shares and which persists. It runs in a new
runic-cswebui-devtools-*directory in the user's temporary folder (mode 0700 on Linux and macOS), which the Window
deletes when that browser exits. Other applications no longer join the browser that holds the port, and its cookies
and storage do not reach the next run. The process's windows still share one browser: a later window joins it and
reports nothing of its own, instead of asking for a port that its browser never opens. The Window reads a free port
(0) fromDevToolsActivePortin that profile. A fixed port, such as the template's 9225, is reported only when the
browser process WebUI started holds the listener on 127.0.0.1, checked through/procon Linux,
GetExtendedTcpTableon Windows andlsofon macOS. Otherwise the Window warns and prints no
RUNIC_APPLICATION_DEBUG_ENDPOINTline. AWebUiWindow.SetProfileinConfigureWindowreplaces the run's profile.
See
CS-WebUI pages in a JavaScript debugger. dotnet runic devlistens on both loopback addresses.--browser's address and, on Linux, the CDP adapter for
JavaScript debuggers listened on 127.0.0.1 alone, while Chromium connects to a.localhostname on[::1]first, and
a debugger toldlocalhostmay do the same. They now listen on 127.0.0.1 and[::1]on the same port, with the same
Host,Origin, code and cookie rules and, on Linux, the same check of the connecting user on both. A port counts as
free only when it is free on both: when another program holds 9224 on either address,--browser's address moves to
a port free on both and the[dev] Browser:line says so, and the adapter moves off 9222 as before. A system without
IPv6 keeps 127.0.0.1 alone. The template'sAttach to the page (JavaScript)configuration now names
"address": "127.0.0.1"; add it to a configuration generated earlier. See the
security guide.- Runic.Spelling: a downloaded dictionary is used only while its files are the ones it was installed with, and the
user's word list is readable by the user alone. A downloaded dictionary whose.dicor.affno longer has the
size and SHA-256 it was installed with (for example after a crash during the install) no longer counts as installed:
GetAvailabilityoffers it for download again, andSpellChecker.LoadAsyncthrowsInvalidDataException. Each file's
hash is computed once per version of the file in the process (about 1 ms for a dictionary of the median size, 18 ms
for the largest). Downloads are written to the disk before they are moved into place. The personal word list
(SpellingUserWords) is now written as a new file of mode 0600 on Linux and macOS, or with an access list of the
current user alone on Windows, and moved into place in one step; the directories the package creates for it and for
downloads are 0700.
CI and tests
- The startup check that the NativeAOT Desktop example on the native server loads neither ICU nor OpenSSL before its
page is served (S1) runs in the native job's Linux x64 leg instead ofnative-server.yml. That workflow runs only
for the server's own files, so 0.22.0's descriptor tables, a generator change, broke the check unseen. A unit test
also keepsSystem.Globalizationout of the generated table reader (#1159).
Known issues
- No visible close drain on an installed browser or in WPF. A Window in an installed browser closes at once,
withWindowCloseDrainUnavailable(event 1055); its scope still waits for durable work. A WPF window is the
application's own, soRunicViewHostdrains nothing visibly: wait for the work in the window'sClosing
handler, as
Closing after the Window's work has drained
shows. Both stay this way in 1.0. - CS-WebUI (preview) under
dotnet runic dev --browser: an application's own absolute navigation leaves the
session address (#1225). The page's WebUI connection goes to the Window's own port, sodevcannot move a
navigation sent over it. The host sends none, and Views routes in the URL's fragment, but
WebUiWindow.Navigatewith an absolute URL of the Window, or a secondShow, takes the tab to the Window's own
address, outsidedev's admission. PassNavigatea relative path. See
What a window opens. Runic.Desktop.Gtk4is not CI-verified on musl. CI runs Runic Desktop on Alpine with GTK 3 and
WebKitGTK 4.1; the GTK 4 window host is not run there
(Supported platforms).- Screen readers in hosted regions are checked by hand. Automation checks that a guest's controls in a region's
frame are in the accessibility tree; whether NVDA, Narrator and VoiceOver speak them in document order is a manual
check (Hosted regions: Still checked by hand). - With the .NET 11 SDK, a SIGTERM does not stop
dotnet runic devon Linux. The SDK's nativedotnetentry
point exits on SIGTERM without forwarding it to the local tool
(dotnet/sdk#57091), sodevkeeps running without its parent, with
its Window and development server. A process manager or IDE that stops it with SIGTERM leaves it behind. Stop it
with Ctrl+C, send the signal todevitself (the session file'sprocessId), or setDOTNET_CLI_ENABLEAOT=0,
which makes SDK 11 forward the signal as SDK 10 does. Runic DevKit stopsdevthrough its standard input
(RUNIC_DEV_STOP_ON_INPUT), which SDK 11 does not affect. - Side panel on Wayland and on transparent GTK 3 windows. On Wayland the left edge is refused with
PositionUnavailable, and the right edge is not checked in CI, which has no headless compositor. A transparent
GTK 3 window refuses the panel withUnsupported. See
Side panel: Known limits. - WebKit's own
inspector://port is open to other local users. Underdotnet runic devon Linux, WebKitGTK's
remote inspector server, which the debugging adapter and GNOME Web connect to, cannot be filtered: another local
user can connect to it, also while a debugger is attached, and a client that replaces another one can crash the
Window on WebKitGTK 2.54. On a shared machine, rundotnet runic dev --no-debug-endpoint. See
The browser's developer tools per engine. - On Windows on Arm (win-arm64), drag-and-drop and the side panel are not CI-verified. The hosted runner
delivers noSendInputto WebView2, so drops onto and drags out of WebView2 are not checked there
(#391), and its desktop shows GDI nothing, so neither is
the side panel's frame capture or Tab between the views
(Side panel: Known limits). The rest of win-arm64 runs in CI.
What's Changed
- Bridge tables: read ids without a culture, keep ICU off the startup path (#1159) by @ViktorJannicke in #1162
- After 0.22.0: ship the public API, baseline 0.22.0, next 0.23.0 by @ViktorJannicke in #1158
- Runic.Spelling: an application's own spell checker (preview) by @ViktorJannicke in #1164
- Template tasks.json: match dev's rebuild errors past the [host] label by @ViktorJannicke in #1165
- Docs: MSBuild page, Bits UI recheck, 0.23 known issues, smallest NativeAOT recipe by @ViktorJannicke in #1199
- Remove the host-named Views client copies (D072.11) by @ViktorJannicke in #1197
- CS-WebUI blob probe: require the window's own listeners; check the preflight policy (#1185) by @ViktorJannicke in #1198
- Set the lifetime of a bridged interaction, or none (#1146) by @ViktorJannicke in #1196
- dev: end the frontend server's whole tree on Windows with a Job object by @ViktorJannicke in #1201
- NixOS host assumptions L4–L10 (I-118) by @ViktorJannicke in #1202
- Side panel: accept drops (D062.6, D077.2) by @ViktorJannicke in #1206
- dev: print frontend (Vite) errors in MSBuild form for IDE error lists by @ViktorJannicke in #1212
- Windows: announce in the page's live region while the focus is on the host window (#1181) by @ViktorJannicke in #1205
- WebKit CDP adapter: don't tell js-debug of a replaced document's scripts by @ViktorJannicke in #1209
- WebKit CDP adapter: decide a Window restart by connection events, not 1.5 s by @ViktorJannicke in #1215
- Docs: SDK 11 does not forward SIGTERM to dotnet runic dev (dotnet/sdk#57091) by @ViktorJannicke in #1214
- Remove the deprecated onBridgeDraining re-export from ./experimental (#1166) by @ViktorJannicke in #1211
- Commands: take the operation's progress as an IProgress parameter (#1180, API-10) by @ViktorJannicke in #1216
- Application icon from one source: generated .ico, default window icon, macOS development bundle icon (#1207) by @ViktorJannicke in #1213
- dev: replace the development pages in www/ when dev stops (DEV-SEC-48) by @ViktorJannicke in #1217
- CS-WebUI host: guard the user's close in a WebView window, on CS-WebUI 2.5.0-beta.4.10 (#1148) by @ViktorJannicke in #1218
- Menus: the reserved runic.devtools.open command opens the window's developer tools (#1188) by @ViktorJannicke in #1219
- dotnet runic dev --browser: a stable per-session address, admitted by a one-time code (#1187) by @ViktorJannicke in #1220
- CS-WebUI host: report and restore window placement in a WebView window (#1149) by @ViktorJannicke in #1223
- Remove the nine error tombstones of types removed in 0.9 and 0.13 (#1167) by @ViktorJannicke in #1226
- WebKitGTK CDP adapter: out of preview; record the IDE checks (#1171) by @ViktorJannicke in #1227
- CS-WebUI: its own pages and banners in the application's language (cs-webui#32, T4) by @ViktorJannicke in #1228
- CS-WebUI under dev --browser: what keeps the tab on the session address; the app's absolute Navigate is a preview limitation (#1225) by @ViktorJannicke in #1229
- CS-WebUI: open the page's DevTools Protocol endpoint in Development (#1221) by @ViktorJannicke in #1230
- 0.23 train candidate: build against Command Line 0.14.0 and Translations 0.15.0 (T) by @ViktorJannicke in #1231
- Close drain for serve-only and CS-WebUI (#1190) by @ViktorJannicke in #1232
- Conformance: wait for region-detach before checking the page (#1224) by @ViktorJannicke in #1233
- Desktop surface: ConnectionOrigin answers only for an admitted page; no stale region embedder (#1222) by @ViktorJannicke in #1234
- Move specs/platform to docs/design/platform; "Not planned" sections by @ViktorJannicke in #1200
- 1.0 wording checklist: refresh for 0.13 to 0.23 (#1170) by @ViktorJannicke in #1236
- Windows: hand keyboard focus back to the page after a UIA activation (#1204) by @ViktorJannicke in #1235
- 0.23 train step 6: Translations TrainCommit at the frozen 0.15.0 commit, Command Line from nuget.org by @ViktorJannicke in #1237
- WPF RunicWebView: announce in the page while the focus is on the window (#1203) by @ViktorJannicke in #1238
- NativeAOT: leave Bridge blobs out of a publish whose Bridges use none (#1193) by @ViktorJannicke in #1240
- Native smoke: the default browser and mail handler through LaunchUriAsync (#1174) by @ViktorJannicke in #1239
- Docs: the 0.22 graduations of the side panel and the close drain, and the sweep's stale lines (#1168) by @ViktorJannicke in #1241
- Flaky BrowserBridgeTests round trip: the product's Chromium flags and request logging on timeout (#1182) by @ViktorJannicke in #1243
- 0.23 train step 8: back to nuget.org (Command Line 0.14.0, Translations 0.15.0) by @ViktorJannicke in #1244
- Runic.Spelling: Directory and Catalog names (API-31) by @ViktorJannicke in #1245
- Docs: list every RUNIC_* name; record the session file's browser.url change (API-27, API-28) by @ViktorJannicke in #1246
- Test hygiene: Nix template URL wait, CollectionDeltaTests recovery check, hybrid editor Start, WPF + ReactiveUI Bridge fixture (#1184, #1177, #1173) by @ViktorJannicke in #1242
- CS-WebUI Development endpoint: a per-run browser profile, and a fixed port reported only from the browser's own listener by @ViktorJannicke in #1247
- Docs: every CS-WebUI window admits the first local client by @ViktorJannicke in #1248
- RUNICBRIDGE073 and 074 for [RunicInteractionTimeout] (API-29) by @ViktorJannicke in #1249
- GTK 3 drag-out smoke: drop only after the drop target answered (#1183) by @ViktorJannicke in #1251
- dev: listen on both loopback families (DEV-SEC-80) by @ViktorJannicke in #1252
- vite-plugin-runic: stop reading the 0.20 source-map name runic-bridge-sources/1 (API-40) by @ViktorJannicke in #1253
- 0.23 train candidate: build against Translations 0.15.1 (T) by @ViktorJannicke in #1254
- RUNICBRIDGE075 for RunicDevelopmentOnlyViews and RunicBridgeBlobs values; feature-switch names are not settings (API-30) by @ViktorJannicke in #1250
- Runic.Spelling: check installed dictionaries; the word list for its user alone (DEV-SEC-87, DEV-SEC-88) by @ViktorJannicke in #1255
- RunicDevelopmentOnly.Removed: for generated code, kept while the Bridge contract version is (API-39) by @ViktorJannicke in #1256
- 0.15.1 feed exit: Translations 0.15.1 from nuget.org by @ViktorJannicke in #1259
- Release 0.23.0 by @ViktorJannicke in #1260
- Inspector environment smoke: a port outside the ephemeral range, and its listener's owner (#1257) by @ViktorJannicke in #1258
Full Changelog: v0.22.0...v0.23.0