Skip to content

Runic SDK 0.23.0

Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 20 Nov 14:26
f2e7d20

Runic 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

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.js and runic-cswebui.js
    (D072.11).
    Deprecated in 0.22, the copy is gone: the host packages copy their Views client into www/ only as
    runic-views.js, in builds, publishes and RunicApplicationFrontendDelivery=Embedded. That saves 5 KB (Runic
    Desktop) or 21 KB (CS-WebUI) per publish. A page must load runic-views.js:
    <script src="runic-views.js"></script> after webui.js, as the templates do. A page that still loads
    runic-desktop-views.js or runic-cswebui.js gets a 404 for it and no Bridge, so its Views never connect; the
    build reports warning RUNICBRIDGE019 naming the page and the fix. A project that references more than one host
    sets RunicApplicationHost (desktop or cswebui), or the build copies no runic-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
    to runic-views.js. A www/ folder that an earlier build left with the old copy keeps that file until it is
    cleaned (dotnet clean or deleting bin/), and the old copy still logs its deprecation warning there.
  • Removed: onBridgeDraining from @runic-artifex/views/experimental (D069.3). Deprecated in 0.22, when the
    close drain graduated (RUNICDESK105), the re-export is gone: import onBridgeDraining from
    @runic-artifex/views, the same function. An import from ./experimental now 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.ReactiveUI and .Reactive (RunicReactiveSchedulerProvider with
    its InstallMainThreadScheduler, IRunicReactiveSchedulerProvider), Runic.Application.Testing
    (BridgeTestArguments) and Runic.Platform.Runtime (INativePickerOwner) remained as [Obsolete] errors whose
    message named the replacement. They are gone, so code that still names one fails with CS0246 instead of CS0619;
    the replacements are in Removed types.
  • dotnet runic dev --browser has an address of its own for each run, and needs the one-time code (#1187). The
    address is http://<label>.localhost:9224/, with a random label for each dev run; http://127.0.0.1:9224/ and
    http://localhost:9224/ answer 403, as does the address without the code. A Window in Chrome launch 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's browser.url and browser.windows[].url have * in place of the
    label; an IDE that reads the session file opens browser.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/sources serves) to
    runic.views.bridge-sources/1 and 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/open cannot 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.url is a pattern, not an address. Since 0.21 the dotnet runic dev --browser
    session file (runic.application.tool.dev-session/1) listed the page's address in browser.url and
    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
    opened browser.url opens the new browser.codeFile instead, 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's urlFilter.
  • Runic Translations 0.15 and Runic Command Line 0.14.
    Runic.Application.Views.Translations requires 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: the dotnet-runic-translations tool, Runic.Translations and
    .Build, and @runic-artifex/vite-plugin-runic-translations; dotnet runic doctor checks 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.Translations and Runic.Translations.Build at 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-translations tool does that. @runic-artifex/views-translations
    0.23.0 is generated with 0.15.1.
    dotnet-runic, Runic.Create and the Runic.Assets packer bundle Runic
    Command Line 0.14.0. An application that uses Command Line itself moves to
    0.14.0 with Translations 0.15, whose Runic.Translations.CommandLine requires
    [0.14.0, 0.15.0). Command Line 0.14 retires the faults.RCLI4001 key 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
    (warning RTR0107). 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 a RunicBlob or takes a RunicUpload now 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 names RunicBlob or RunicUpload in its metadata (a
    library whose Bridges a generator before 0.23 wrote) turns the new feature switch
    Runic.Application.Views.Blobs off: the producer no longer lists blobs/1 in 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.upload rejects with unavailable, which nothing in the application could have read anyway. Builds,
    dotnet run and untrimmed publishes keep blobs/1; set <RunicBridgeBlobs>true</RunicBridgeBlobs> to keep it in
    every publish, for example when only reflection reaches a RunicBlob.
    See Making the executable smaller.

  • An application that sets no ApplicationIcon gets one (#1207). When icons/icon.png (or the file
    RunicPackageIcon names) exists, the build now derives the executable's Windows icon from it, Runic Desktop windows
    without IconFile show it on Windows and on macOS outside a bundle, and the macOS development bundle has it as
    icon.icns. An application with an ApplicationIcon keeps its own .ico for 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
    warning RUNICICON001, RUNICICON002 or RUNICICON003 and 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 delete icons/icon.ico and its ApplicationIcon line, as the
    0.23 template does.

  • RunicDevelopmentOnlyViews and RunicBridgeBlobs warn on a value other than auto or true (API-30). Both
    take auto (the default, also when empty) or true, compared without case. Until now another value, such as
    false or a typo, silently meant auto; it is now warning RUNICBRIDGE075, and the build still goes on as auto.
    Neither has a false: 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 as Runic.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; Suggest offers 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_GB from SCOWL) ships in the package, and its build targets copy it into the application as
    dictionaries/ (RunicSpellingBundledDictionaries=false leaves it out). The computer's Hunspell dictionaries are
    used too, including those of a Nix-built application's spellingDictionaries.
  • 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, and DownloadAsync installs 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:9224 and 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=…), and dev writes obj/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 as browser.codeFile and lists the address with * for the label. The code admits one browser with
    dev's host-only HttpOnly, SameSite=Strict cookie 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>.localhost on any port, so dev keeps the label where it keeps the code: its [dev] Browser: output and the
    code page.
  • The template's Window in Chrome opens 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. dev sets RUNIC_APPLICATION_SERVE_ORIGIN for 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 an http origin on localhost or 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: IRunicFileDropTarget on the
    Window's root ViewModel and DesktopWindow.FilesDropped. The new RunicFileDrop.InSidePanel and
    DesktopFileDropEventArgs.InSidePanel tell the panel's drops apart. The window sets the flag from the view that
    received the drop, so unlike the data-runic-drop-target label 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 own drop event.
  • 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 UseWebView window on Windows (WebView2) and Linux (WebKitGTK) stays open after the user's
    close, or RequestCloseAsync, was decided, with its page connected and receiving closing with draining: 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 new RunicCsWebUiHostOptions.CloseDrain sets 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 does WaitForCloseAsync return. 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 as ApplicationIcon, the icon in Explorer and on the taskbar.
  • Windows. A Runic Desktop window without IconFile shows the application's icon: from the executable's icon
    resource, or from the application's assembly when it runs as dotnet app.dll. On macOS outside a bundle with an
    icon, such as dotnet 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 run starts has Contents/Resources/icon.icns and
    CFBundleIconFile, so the Dock shows the icon during development.
  • Template. dotnet new runic-app no longer has a hand-made icons/icon.ico and an ApplicationIcon line.

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/client and virtual: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 a runic-app template application). It now reads the ids as plain digits.
    Rebuilding with 0.23.0 regenerates the reader (#1159).
  • The dotnet runic dev tasks in the runic-app template's .vscode/tasks.json (--editor vscode) now find the
    file of a build error after an edit. dev prints 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' $msCompile took
    [host] /path/App/File.cs for 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
    problemMatcher from a new one (#1161).
  • On Windows, dotnet runic dev no longer leaves the Vite development server and runic-translations serve running
    after it stops. They outlived the package manager (bun or npm) that dev started, and dev ended only that
    package manager's tree, which no longer reached them once it had exited. An IDE that read dev's output then
    waited for pipes those processes still held, and they kept the server's port. dev now 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
    dev itself is killed (#1163).
  • When dotnet runic dev stops, the development pages it wrote into the output's www/ no longer stay behind. They
    loaded their script from the development server's loopback port, which another local process could bind once dev
    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). dev now 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
    dev killed by force still leaves its pages until the next build, as Security
    says (#1178).
  • On WebView2, NVDA says a DesktopWindow.AnnounceAsync message 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.ForWindow also right after a screen
    reader or another UI Automation client presses a button in a RunicWebView'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 before dotnet watch restarts 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 or dev stops (#1210).
  • CS-WebUI: the page's DevTools Protocol endpoint opens (#1221). In 0.22 the Development endpoint that
    dotnet runic dev --debug-endpoint, --no-window and the template's (CS-WebUI script debugging) profile ask for
    with RUNIC_WEBUI_REMOTE_DEBUGGING_PORT was built into Runic Desktop's installed-browser windows only, so a
    --host cswebui application's Chrome or Edge started without --remote-debugging-port: dev printed 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/version and prints the
    RUNIC_APPLICATION_DEBUG_ENDPOINT line dev reads. UseWebView, ShowWindow and serve-only windows open none.
    WebUI's custom parameters replace its Chromium defaults, so the host passes them itself: a
    WebUiWindow.SetCustomParameters in ConfigureWindow replaces the endpoint, and SetProxy there 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_PORT opens 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) from DevToolsActivePort in 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 /proc on Linux,
    GetExtendedTcpTable on Windows and lsof on macOS. Otherwise the Window warns and prints no
    RUNIC_APPLICATION_DEBUG_ENDPOINT line. A WebUiWindow.SetProfile in ConfigureWindow replaces the run's profile.
    See
    CS-WebUI pages in a JavaScript debugger.
  • dotnet runic dev listens 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 .localhost name on [::1] first, and
    a debugger told localhost may 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's Attach 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 .dic or .aff no longer has the
    size and SHA-256 it was installed with (for example after a crash during the install) no longer counts as installed:
    GetAvailability offers it for download again, and SpellChecker.LoadAsync throws InvalidDataException. 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 of native-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 keeps System.Globalization out 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,
    with WindowCloseDrainUnavailable (event 1055); its scope still waits for durable work. A WPF window is the
    application's own, so RunicViewHost drains nothing visibly: wait for the work in the window's Closing
    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, so dev cannot move a
    navigation sent over it. The host sends none, and Views routes in the URL's fragment, but
    WebUiWindow.Navigate with an absolute URL of the Window, or a second Show, takes the tab to the Window's own
    address, outside dev's admission. Pass Navigate a relative path. See
    What a window opens.
  • Runic.Desktop.Gtk4 is 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 dev on Linux. The SDK's native dotnet entry
    point exits on SIGTERM without forwarding it to the local tool
    (dotnet/sdk#57091), so dev keeps 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 to dev itself (the session file's processId), or set DOTNET_CLI_ENABLEAOT=0,
    which makes SDK 11 forward the signal as SDK 10 does. Runic DevKit stops dev through 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 with Unsupported. See
    Side panel: Known limits.
  • WebKit's own inspector:// port is open to other local users. Under dotnet runic dev on 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, run dotnet 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 no SendInput to 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

Full Changelog: v0.22.0...v0.23.0