Skip to content

Runic SDK 0.20.0

Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 16 Nov 00:48
8288005

Runic SDK 0.20.0

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

0.20.0 is about finding your way from the page to the C# behind it, and back. A
build that generates Bridges writes a development source map from every Bridge
member to its C# (#951), and everything that shows a Bridge call opens that C# in
your editor: the generated clients' Go to Definition (#952), the browser's
Performance panel and async stacks (#953), the Vite DevTools dock's Bridge
calls
card (#954) and Runic Inspect (#955, #976), a select mode in the page
that shows how an element is connected: its component, the commands it calls with
their C# handlers, the state it shows and the messages it displays (#956), which
it can also edit on the page (#957). Under dotnet runic dev a reply names the
C# handler that ran and how long it took, and a call can be one trace from the page
into .NET (#958).

The IDE side is new too. dotnet runic dev has an IDE contract (#959, #1001)
and a --no-window mode that leaves the Window to your IDE's debugger (#960); the
runic-app template has launch profiles and an optional VS Code setup (#961); and
the Bridge analyzers report the generator's errors and warnings while you type,
with code fixes (#962). The
debugging guide
(#964) puts it together. None of it reaches production: @runic-artifex/views now
has a separate development build, and a production bundle has none of the
development code (#975).

The template's Vite frontends compile their messages with the Runic Translations
Vite plugin, so an edited message updates in place (#944), the Angular template can
build with Vite (#946), @runic-artifex/angular is published in the Angular Package
Format (#945), and an Angular guest can be shown in
trusted component mode
(#947, experimental).

0.20.0 moves the release train to Runic Translations 0.12.0; Runic Command Line
stays at 0.13.0. Two changes can fail a build or change a Linux release:
Upgrading from 0.19 lists them, and the
migration guide
collects them.

Highlights

Upgrading from 0.19

Update every Runic NuGet and npm package to 0.20.0 together and rebuild, so that
the generated clients and Bridges are regenerated. The wire protocol is
unchanged; the new Views protocol features (trace-context/1,
handler-timing/1) are negotiated, so a 0.19 page and a 0.20 host connect.

Breaking changes

  • Runic Translations 0.12 (the 0.20 train candidate).
    Runic.Application.Views.Translations requires Runic Translations
    [0.12.0, 0.13.0), so an application that uses it moves every Translations
    package, NuGet and npm, to 0.12.0. The template pins Translations 0.12.0 three
    ways: the dotnet-runic-translations tool, Runic.Translations and
    .Build, and @runic-artifex/vite-plugin-runic-translations. With the plugin
    0.12, an edited message updates in place under dotnet runic dev, and Runic
    Inspect marks the page's messages and edits them; an earlier plugin reloads
    the page and offers no editing. Under vite dev the plugin answers
    /__runic-translations/message, which writes the project's .rmf2 files, to
    the same machine only; inPageEditing: false turns it off. Runic Command Line
    stays at 0.13. See the
    Translations 0.12.0 notes.

Behaviour and output changes

  • The Bridge warnings RUNICBRIDGE013, 028, 031, 032, 034, 039 and 053 fail a build
    that treats warnings as errors
    (#962). They now come from the analyzer as
    compiler warnings, so TreatWarningsAsErrors (or WarningsAsErrors naming
    them) applies to them, as the diagnostics catalog always described; the
    generator's warning did not fail such a build. Fix the declaration, or keep it
    a warning with WarningsNotAsErrors (or hide it with NoWarn).

  • Every Bridge warning fails a build that treats warnings as errors (#962,
    D066.35). The warnings the generator still reports itself (RUNICBRIDGE020,
    and the analyzer's when analyzers are off) and those of
    the Runic.Application.Views build targets (015, 019, 029, 030, 033)
    are MSBuild warnings, which TreatWarningsAsErrors did not reach. With it they
    are now errors too, unless WarningsNotAsErrors or NoWarn names them.

  • WebKit's remote inspector opens only in Development on Linux (#1028,
    D066.38). WebKitGTK opened it whenever WEBKIT_INSPECTOR_SERVER or
    WEBKIT_INSPECTOR_HTTP_SERVER was set, also with developer tools off, so a
    release could be scripted through it. Now, unless DOTNET_ENVIRONMENT (or
    else ASPNETCORE_ENVIRONMENT) is Development, the GTK 3 and GTK 4 hosts
    remove both variables from the process's environment before their first web
    view, also when DevTools is true. Processes the application starts after
    that no longer inherit them either. To inspect a build remotely, run it with
    DOTNET_ENVIRONMENT=Development.

  • Generated clients are two files (#952): <view>.ts and
    <view>.contract.d.ts with a declaration map. Imports and the built
    JavaScript are unchanged; commit the new files of a committed generated
    directory, and a library that emits declarations with tsc copies the
    .contract.d.ts files beside them. See
    Generated clients link to their C# sources.

  • Bun bundles the development build of @runic-artifex/views by default
    (#975). vite build, ng build and bun build --production bundle the
    production build; pass --production to bun build, or set
    NODE_ENV=production for a Bun.build script, when you build a release page.
    The Views MSBuild targets now run the frontend build of an optimized build with
    NODE_ENV=production unless the environment sets it. See
    Development tools cost nothing in production.

  • dotnet runic doctor --format json gives each check a helpUri (#1001).
    The payload type stays runic.application.tool.doctor/1, whose schema now
    lists the member; a validator that holds an earlier copy of that schema, which
    allows no other properties, rejects 0.20's payload. Update the copy.

Experimental features and how to opt in

Nothing changes for an application that does not use them. Each .NET family is
a compile error until the project suppresses its ID
(experimental APIs),
and an npm API is exported only from its package's ./experimental entry. They
may change in 0.21:

ID Feature Opt in
RUNICDESK103 Trusted component mode for Angular guests, part of hosted applications Import runicComponentMount from @runic-artifex/angular/experimental in the guest's component entry; the host already suppresses the ID
RUNICDESK104 The side panel of 0.19, unchanged Suppress the ID where the application calls OpenSidePanelAsync
RUNICDESK105 The close drain of 0.19, unchanged Suppress the ID in the project that sets CloseDrain or declares [RunicOperationClose]; on npm, import onBridgeDraining from @runic-artifex/views/experimental

The development tools of 0.20 (the source map, Runic Inspect, the dock, handler
timing and traces) are development-only, not experimental: they need no opt-in and
are off in production.

Bridge errors and warnings while you type, with code fixes (#962)

Runic.Application.Views ships Roslyn analyzers for the Bridge rules that the
source alone shows. Until now the Bridge generator, a build step that IDEs skip
in their design-time builds, reported them only after a build. Visual Studio,
Rider and VS Code's C# extension now report them while you type, with the
generator's ID, message and help link. Examples are a command named NewCommand
or ThenCommand (RUNICBRIDGE004), a command without the Command suffix or a
plain ICommand without [RunicCommandInput] (RUNICBRIDGE009), and a
ViewRequest<T>, interaction, navigation slot or [RunicCollection] with a
public setter. Code fixes rename the command, or its CommunityToolkit
[RelayCommand] method, make the setter private, or make a Window, View or
ViewModel public. Projects that reference Runic.Application.Views through a
host adapter get the analyzers too. The
diagnostics catalog
lists the rules.

The analyzers also report errors that compare a ViewModel with the rest of the
application: two ViewModels with the same Bridge name, a second View with the
same contract, a slot whose [RunicViewContract] or content no View presents,
and a ReactiveUI member without the Runic ReactiveUI adapter of its flavor
(RUNICBRIDGE004, 006, 008, 025, 070), and the names of the generated
client: two state properties with one wire name, a client member such as
setCount or canReset that two members would generate, a region collection's
select/close method that another member uses (RUNICBRIDGE071), and two
generated files whose names differ only in case. They check a command's
[RunicFailure] type and its [RunicCommandKey] resolver as the generator does
(RUNICBRIDGE012, 027). They build each value's contract from the source as
the generator does, so a value that cannot cross the Bridge (RUNICBRIDGE003,
such as an object, a HashSet<T> or a DTO the page sends without a usable
constructor), a RunicBlob the page would send (065), the rows and key of a
[RunicCollection] or RunicQueryCollection (010, 060) and the row editors
(050–052) are reported while you type. Builds don't change for errors:
the generator still checks every rule and runs before the compiler, so a build
reports each error once.

The warnings RUNICBRIDGE013 (a ViewModel without a View that a slot admits),
028 and 039 ([RunicOperationRetirement] or [RunicOperationClose] that
reaches no operation), 031 (an unrecognized IValidatableViewModel), 032
(an observable collection of DTO rows that is not keyed, with a code fix that
declares [RunicCollection(nameof(Row.Id))]), 034 (a misplaced
[RunicPresentationScoped]) and 053 (an object inside an editable row that
cannot be copied) now
come from the analyzer, while you type and in the build, for the project's own
code. The generator leaves them to it, so each is reported once. As compiler
warnings they now follow .editorconfig severities, #pragma warning disable
and TreatWarningsAsErrors, as the diagnostics catalog always described: a
project that treats warnings as errors and has one of these warnings now fails
to build, where the generator's warning did not fail it. Suppress the warning
with NoWarn or WarningsNotAsErrors, or fix the declaration. Like other
compiler warnings, they are not repeated by a build that finds the project up to
date.

Development source map and open in editor (#951)

Each build that generates Bridges now writes a development source map,
obj/<Configuration>/<TargetFramework>/runic-bridge/sources.json: every
ViewModel and every member its generated client and the Bridge frames name
(state, setters, commands, command state, interactions, View requests), with
the C# that runs for it (a command's [RelayCommand] method or the method its
command is created from) and its {file, line, column}, read from the
assembly's portable PDB. Without a PDB the members are listed without
locations and the build still succeeds.

Under vite dev, @runic-artifex/vite-plugin-runic serves the map at
/__runic/sources and adds POST /__runic/open, which opens a location in
your editor through Vite's own launcher (LAUNCH_EDITOR, VS Code, Rider). Unlike
Vite's /__open-in-editor, it opens only locations the map lists, and only for
a page of the development server's origin on the same machine. dotnet runic dev tells the plugin where the map is; otherwise the plugin finds it under the
project's obj, and runic({ sourceMap }) names it or (false) turns both
endpoints off. The map never enters generated TypeScript, vite build output,
publish output or a package.

Generated clients link to their C# sources (#952)

Each generated client is now two files: <view>.ts with the code, and
<view>.contract.d.ts with its types (state, checked fields, interactions,
View requests, operations, client and page reference interfaces) and a
declaration map, <view>.contract.d.ts.map, into the ViewModel's C#. Go to
Definition or Peek on client.increment(), client.setStep(...) or
state.count in VS Code, Visual Studio or another tsserver-based editor opens
the command's handler, the setter or the getter in the .cs file, with no
extension; Go to Type Definition on a CounterClient or CounterState opens
the ViewModel class. The locations are the development source map's (#951),
and the map's sources are relative to it, so committed clients don't depend
on the checkout. Without a PDB a client gets no map, and the build still
succeeds.

  • Imports keep working. <view>.ts re-exports every contract type with
    export type, so import { connectCounter, type CounterState } from "./generated/counter.js"
    is unchanged. The built JavaScript is unchanged too: the contract holds only
    types.
  • Commit the new files. A committed generated directory gains a
    .contract.d.ts and a .contract.d.ts.map per ViewModel, and the
    interfaces move out of <view>.ts; the example clients changed this way.
  • tsc --declaration into another directory: tsc doesn't copy .d.ts
    inputs, so a library that emits declarations for its generated clients copies
    the .contract.d.ts files beside them.
  • A generated client no longer imports types it doesn't use (a field-path
    client imported FieldBaseline and FieldWriteOptions), so it passes
    noUnusedLocals.

Bridge calls in the browser's developer tools (#953)

During development, each call a generated client makes can now be followed in
the browser. @runic-artifex/views reports every command, setter, checked
write, availability check, region request, operation start and query request
to a development Bridge-call channel (runic.views.calls), with a
client-local id, the route, contract and member, its start and end time, its
outcome (ok, error or cancelled) and the reply's revision. The
development client of @runic-artifex/vite-plugin-runic listens to it, so
under vite dev and dotnet runic dev:

  • a Performance recording in Chrome, Edge or WebView2 has a Runic track
    group with a Bridge calls track, which the development client draws: one
    entry per call, such as EditorViewModel.save #3, coloured by outcome;
  • a breakpoint after a reply, such as in a state subscriber, shows a
    Runic command EditorViewModel.save async stack segment that leads to the
    click handler that made the call (console.createTask).

Other engines get the channel's reports without the two Chromium extras.
Without a reader, a call costs one property read and records nothing. Only the
development build of @runic-artifex/views that vite dev resolves has the
reporting code: a production bundle has none of it (#975). The wire protocol is unchanged: the id stays in the page. See "Bridge
calls in the browser's developer tools" in the Views README for the event
fields.

The dock's Bridge call timeline, and the dock on by default in the template (#954)

The Runic panel of the Vite DevTools dock has a Bridge calls card: each call
a generated client makes, the newest first, with the C# that ran for it from
the development source map (#951) and how long the page waited for it:

command EditorViewModel.save → SaveAsync() 23 ms
  • Its Open button opens the handler (a command's [RelayCommand] method, a
    setter, …) in your editor. It opens only what /__runic/open would, a
    location in a file the source map lists, with the same editor choice
    (launch-editor, the package behind Vite's /__open-in-editor, now a
    dependency of the plugin).
  • A failed call shows .NET's exception, with a button for each stack frame in a
    file of the source map, which opens that line. The Last failure card
    links the same frames. /__runic/open therefore opens any line of a file the
    map lists, not only the map's own locations. It also opens a frontend file
    that Vite serves to the page, for Runic Inspect's component links, which no
    longer use Vite's /__open-in-editor; it opens nothing else, and the dock
    opens only the map's files.
  • When a reply carries .NET's own timing of the handler, the row shows it as
    C# <n> ms next to the page's duration.
  • The history is as long as the timeline (maxTimelineEntries, 200 by
    default) and checked like it. /__runic/state lists the calls (calls)
    without failures and without paths.

The dock now also appears under dotnet runic dev, where the window's document
is the .NET host's page and the dock's own loader looked for its script on the
wrong origin: the development client loads it from Vite's development server.
With runic({ html: false }) (SvelteKit) the client loads it too, and the
dock's HTML hook, which SvelteKit warned about, is removed.

dotnet new runic-app registers the dock (DevTools() from
@vitejs/devtools 0.7.6) in Frontend/vite.config.ts of every frontend that
Vite builds: React, Vue, Svelte, SvelteKit and Angular with
--angular-build vite. The Angular CLI runs no Vite plugins and has no dock.
vite build, and so the application's build, publish and packages, contain no
part of it. To turn it off, delete the DevTools(), line. The first time a page
opens the dock, it asks for the one-time code that Vite DevTools prints in the
dotnet runic dev output.

Applications created from an earlier template: add "@vitejs/devtools": "0.7.6"
to devDependencies, import { DevTools } from "@vitejs/devtools"; and
DevTools() to the Vite plugins.

Runic Inspect: select an element and see how it is connected (#955)

Under vite dev and dotnet runic dev, press Alt+Shift+X in the page to
turn on Runic Inspect, a select mode of the
@runic-artifex/vite-plugin-runic development client. Hover outlines an
element; clicking it shows an overview, without running the page's own
handler for that click:

  • its framework component and the components around it, with a link to the
    source: the element's JSX line in React 19 (from _debugStack through the
    module's source map), the element's line in Svelte 5, the component file in
    Vue 3 and the component class in Angular 17.1+;
  • the commands it calls, with their C# handlers (such as the
    [RelayCommand] method) and file:line from the development source map
    (#951), and their availability (canSave);
  • the ViewModel members it sets, and state members it shows, with their
    current values and C# members;
  • its recent Bridge calls with duration, outcome and revision (#953);
  • the texts its ViewModel sent as text references, with catalog, key and
    locale.

C# locations, Translations messages and frontend files open in the editor
through /__runic/open's decision, which opens a frontend file only when Vite
serves it to the page. Under dotnet runic dev, where the page is the .NET
host's, Inspect asks the Vite server over the development client's connection
to it for the source map, the handler analysis, message sources and opening
(#1012), so its locations and links work in every engine there too. An
element's commands are found in its component's source before any click (#976,
below) and learned from the calls it makes. For agents and tests,
globalThis[Symbol.for("runic.vite.inspect")].describe(element) returns the
overview as data. Runic Inspect is plain DOM, so it works in every engine
dotnet runic dev runs (installed browser, WebView2, WKWebView, WebKitGTK).
It lives in the development client only: vite build output is
byte-identical with and without it, and runic({ inspect: false }) turns it
off.

Runic Inspect: a button's command before its first click (#976)

Runic Inspect now shows the command a button calls, with its C# handler,
before the button was used. The development server reads the element's
component file and follows its event handlers to the client calls they reach:
directly (client.save()), through useCommand, useOperation,
injectCommand and injectOperation, and through functions, variables and
class members of the same file. The overview marks such a command "from the
source, not called yet" and links the line that calls the client. It works
for React (JSX/TSX), Vue single-file components (@click, <script setup>
and the Options API), Svelte 5 (onclick and on:click) and Angular
templates ((click), inline and templateUrl).

Under the Angular CLI, runicDevSessionProxy() now answers /__runic/handlers,
/__runic/sources and /__runic/open as well, so Runic Inspect shows C#
handlers and pre-click commands with ng serve too; dotnet runic dev now
passes the source map's path to the Angular development server as it does to
Vite. The proxy's new options sourceMap and inspect: false turn them off.

Calls made in other files (a store, a service, a custom hook) are still learned
on the element's first click, and the overview names the import the handler
uses. Served modules are unchanged: the analysis answers
GET /__runic/handlers?file=… for pages of this machine and frontend files
below the root, and vite build output is byte-identical with and without it.
runic({ inspect: false }) turns it off.

Runic Inspect for translated text (#956)

Runic Inspect now shows the messages of generated m.*() calls that a
selected element shows: catalog, key, locale, the text as authored, and the
.rmf2 file:line, with an "open in editor" link. describe(element) returns
them as messages.

  • Markers only while selecting. Turning select mode on asks Runic
    Translations (@runic-artifex/vite-plugin-runic-translations 0.12 or later
    under vite dev) to put an invisible marker in front of each message's
    text, and the page renders again, as on a language switch. Turning it off
    renders the plain text again. Outside select mode, and in every build, the
    page's text is exactly as before.
  • Text and attributes. Markers are read from the element's text and from
    title, aria-label, placeholder, alt and an input's value. They take
    no width, so the layout does not change while selecting.
  • Open in editor. The source location comes from the Translations dev
    server's message API. /__runic/open accepts
    { "message": { catalog, key, locale } }, asks the same API, and opens only
    the .rmf2/.mf2 source it names, never a path from the page. The open
    action is now also there with runic({ sourceMap: false }) unless Runic
    Inspect is off.
  • Re-rendering uses the text helpers that follow the text-change channel
    (below): useTextLocale in React and Vue, Svelte's useTextLocale, and
    Angular's textLocaleSignal.

With an earlier Translations plugin the overview has no messages and its notes
say why. vite build output is byte-identical with and without Runic Inspect.

Edit a translation on the page (#957)

Runic Inspect's overview has an Edit action for each message of a selected
text. The panel shows the message's MF2 source in every locale (base locale
first, starting with the one the page shows), its inputs, plural and selector
variants with the locale's plural categories, and its markup.

  • Save writes the source. Save (or Ctrl+Enter) sends the text with the
    file hash it was read from to Runic Translations' in-page editing API
    (@runic-artifex/vite-plugin-runic-translations 0.12 in project mode). Only
    that entry of the .rmf2/.mf2 file changes; comments and formatting stay.
    The page shows the new text in place, without a reload, and the card keeps
    its selection.
  • Refusals in the panel. A text that does not compile shows its RTR
    diagnostics and writes nothing. A file that changed since it was read shows
    its current text, with Reapply my text and Use the file's text.
  • Keyboard. The panel is reachable with Tab, Ctrl+Enter saves, and Esc
    closes it and returns to the message's Edit button. It is plain DOM, so it
    works in every engine dotnet runic dev runs.

From another machine. runic({ allow }) and the RUNIC_DEV_ALLOW
environment variable name hosts and networks (addresses, IPv4/IPv6 CIDR such as
a Tailscale network, host names) whose pages may read /__runic/sources and
/__runic/handlers; runicDevSessionProxy({ allow }) does the same under the
Angular CLI. Runic Translations' editing API reads the same variable, so one
setting covers both. Without it, both stay loopback-only, as before.
/__runic/open always stays loopback-only, because it launches the editor on
the development machine; a page opened from another machine shows locations
without links and says why. Same-origin checks are unchanged.

vite build output is byte-identical with and without Runic Inspect, the
editor and the allow list.

Text helpers follow in-place message updates (runic-translations-sdk#176)

With the Translations Vite plugin 0.12.0 or later, vite dev updates an edited
message in place instead of reloading the page, and the page keeps its
component state, its language and its connection. The plugin signals the change
on a global text-change channel, Symbol.for("runic.translations.text"), and the
text helpers now render again on it as they do on a language switch:

  • configureTranslatedText (@runic-artifex/views) follows the channel and
    notifies text subscribers, so useText, injectText, the runicText pipe,
    texts and syncDocumentLocale update.
  • React: useTextLocale() renders again on a text change that keeps the locale,
    so components that call it, and their children except memoized ones, show the
    new text.
  • Angular: textLocaleSignal() notifies on a text change that keeps the locale,
    so templates that call m.*() through the locale resolver, OnPush ones
    included, show the new text.
  • Effect: textLocales() emits the same locale again on a text change.
  • Vue and Svelte (useTextLocale) needed no change.

In place means a message's text, its plural and selector variants and the text
inside its markup, in any locale. An added, removed or renamed message, changed
inputs or markup, a new locale and a runic.json change still reload the page,
and so does a page that does not call configureTranslatedText. The Angular CLI's
dev server runs no Vite plugins and keeps reloading; in-place updates in Angular
need Angular built with Vite. Only the development build of
@runic-artifex/views follows the channel: a production bundle neither creates
nor reads it, and the helpers behave as before (#975). With an earlier plugin, or with these helpers from
0.19 or earlier, the page reloads as before; only @runic-artifex/views 0.20
with the React or Angular helpers of 0.19 updates the catalog without rendering
again, so install matching versions.

C# handler timing and one trace from the page to .NET (#958)

Under dotnet runic dev, a Bridge reply names the C# handler that ran and how
long it took, such as EditorViewModel.Save in 2.4 ms. The Vite development
client lists it on the call's Bridge calls entry and draws it on a new
C# handlers track below it. A .NET host sends the timing only when
DOTNET_ENVIRONMENT (or else ASPNETCORE_ENVIRONMENT) is Development, which
dotnet runic dev sets, and only to a page whose development tools ask for it.

Bridge calls can also be one trace with the C# they run. When the Vite
development server sees OTEL_EXPORTER_OTLP_ENDPOINT, the page gives each call
a W3C trace context, which the call's request carries to .NET. The
runic.bridge.* span of Runic.Application.Views becomes the child of the
page's span for the call, and the ViewModel's own spans, such as its HTTP and
database calls, follow it. The development server exports the page's spans as
OTLP/JSON, and the application exports its own spans with its usual
OpenTelemetry setup. The page loads no OpenTelemetry code, and dotnet runic dev starts no container. The new
tracing guide
sets it up with the standalone Aspire dashboard.

Both are Views protocol features (trace-context/1 and handler-timing/1):
a page and a .NET host of 0.19 or earlier keep working with 0.20 in either
direction. Outside development nothing changes: only the development build of
@runic-artifex/views implements them, so a production page lists neither
feature and no request carries their members; a host reads a trace context only
while its ActivitySource has a listener, and replies carry no timing.

Development tools cost nothing in production (#975)

@runic-artifex/views now ships a development build next to its production
build, selected by the development export condition. Only the development
build reports Bridge calls, tags them with console.createTask and follows the
Runic Translations text channel. A production bundle contains none of that
code (about 0.6 KB gzip less in the example clients of bun run size), reads
no channel per call and creates no global. Both builds share one set of type
declarations, and everything else, including the state inspector that Runic
Inspect reads, is the same in both.

Vite resolves the development build in vite dev and Vitest, the Angular CLI in
ng serve, and Bun's bundler unless --production or NODE_ENV=production is
set, so the development tools keep working without configuration. vite build,
ng build and bun build --production resolve the production build. A
vite build run with NODE_ENV=development or test bundles the development
build, as it bundles React's. For the Bun runtime, Node.js, esbuild and Rollup,
add the development condition to opt in (bun --conditions development,
node --conditions=development, --conditions=development,
exportConditions); webpack 5 adds it in mode: "development". The framework
packages import @runic-artifex/views by name, so they resolve the same build
as the application, and a page that loads both builds still shares one
runtime. See "Development build" in the Views README.

Bun bundles the development build by default. Pass --production to
bun build, or set NODE_ENV=production for a Bun.build script, when you
build a release page. The Views MSBuild targets now run the frontend build of
an optimized build (dotnet build -c Release, dotnet publish) with
NODE_ENV=production unless the environment sets NODE_ENV, so Bun-built
frontends of Runic applications, such as the examples, get the production
build there and the development build in Debug.

dotnet runic dev: an IDE contract (#959)

dotnet runic dev prints [dev] Window started: process <pid> each time the
Window process starts or dotnet watch restarts it, with the application's own
process ID to attach a .NET debugger to, then [dev] Ready, and
[dev] Window exited: process <pid> when it exits. It writes
obj/runic/dev-session.json (runic.application.tool.dev-session/1): the
development server's URL and port, each page's URL, the Window's process ID,
the web root and the generated clients' directory, and WebView2's debugging
endpoint when WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS enables one. The file is
marked "state": "stopped" when dev ends. A failing dev prints its fault as
one line, <project> : error RAPPDEV1007: <message>, which VS Code's
$msCompile matches like the build's own errors. A background task can wait
for Ready; see
IDE contract.

dotnet runic dev and doctor: fields for IDE tools (#1001)

obj/runic/dev-session.json lists processStartedAt, the dev process's
start time in UTC. A reader checks that a process with the session's
processId runs and started at that time (to within a second), so a process
that reuses the ID of a killed dev no longer reads as a running session. The
file also lists sourceMap, the Bridge source map that dev passes to the
development server for vite-plugin-runic, so IDE tools read the same file as
the page. The schema stays runic.application.tool.dev-session/1: readers
ignore properties they don't know. dotnet runic doctor --format json gives each
check a helpUri, its section of the dotnet-runic README at this release. See
Session file
and Doctor checks.

Debug the Window under your IDE while dev runs the frontend (#960)

dotnet runic dev --no-window runs only the frontend (the Vite or Angular
development server, or the frontend watcher), and your IDE's F5 builds and
starts the Window under its .NET debugger. While dev runs, any build of the
output it serves, such as the IDE's, skips the production frontend build and
keeps dev's development pages in www/, also after a clean; before, an IDE
build replaced them with dist/. Nothing restarts the Window behind the
debugger; use the IDE's Hot Reload. Publish is
unchanged, and RunicApplicationFrontendDevSessionEnabled=false turns the
build behaviour off. --no-window with an option that only describes how dev
starts the Window fails with RAPPDEV1014; a project without a development
server or watcher fails with RAPPDEV1015. The tool's README has the launch
profile and VS Code, Rider and Visual Studio setups; see
Debug the Window in your IDE.

An IDE-ready runic-app template (#961)

Projects from dotnet new runic-app have Properties/launchSettings.json.
Its first profile starts the Window with DOTNET_ENVIRONMENT=Development in
Visual Studio, Rider and plain dotnet run, which uses the first profile, so
dotnet run now has the page's DevTools and detailed Bridge errors on. With
Runic Desktop, a second profile turns on WebView2 script debugging on Windows
(WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9222, and
jsWebView2Debugging for Visual Studio); WebView2 ignores that variable while
the Window runs elevated, so start the IDE without elevation. --editor vscode (default none) adds
.vscode/: tasks for dotnet runic dev and dev --no-window that wait for
[dev] Ready and put RAPPDEV failures and build errors in the Problems panel,
debug configurations for the C# extension (F5 starts the Window under the
debugger while dev --no-window serves the frontend, or attaches to the Window
that dev started), a Windows compound that also attaches VS Code's JavaScript
debugger to WebView2, and the recommended extensions. runic-create asks for
the editor too. Both templates have an ide.host.json and an icon for Visual
Studio's New Project and Add New Item dialogs. See the generated README's "Debug it in
your IDE" section.

A debugging guide (#964)

The new
debugging guide
shows how to debug a Runic application end to end under dotnet runic dev:
the Window under the .NET debugger of Visual Studio, Rider or VS Code (the
template's launch profiles and .vscode/ setup, dev --no-window, the IDE
contract and its session file), the browser's developer tools of each engine
(WebView2 and its DevTools Protocol endpoint, which an elevated Window does not
open; WKWebView with Safari's Web Inspector; WebKitGTK's inspector; an installed
browser) and how dev turns them on, the Runic dock, Runic Inspect, the
Performance panel and traces, and the Bridge analyzers. It names the two kinds
of "DevTools" apart (the browser's developer tools and the Vite DevTools dock),
says what reaches production (nothing), and ends with troubleshooting.

The template's Vite pages compile their catalog with the Translations Vite plugin (#944)

dotnet new runic-app --translations with React, Vue, Svelte or SvelteKit no
longer has the .NET build write the page's ESM and mirror it into
Frontend/.runic/translations. The page compiles the catalog itself with
runicTranslations() from @runic-artifex/vite-plugin-runic-translations
0.12.0 in Frontend/vite.config.ts and imports it as
virtual:runic-translations/app. The plugin runs the
dotnet-runic-translations tool of .config/dotnet-tools.json, the release of
Runic.Translations.Build, so the page and C# (AppText, which the build still
generates) read the same catalog, and nothing else generates the page's copy.

  • Under dotnet runic dev, an edited, added or removed message reaches the page
    without a build: the plugin compiles it again. An edited message updates in
    place and the page keeps its state (runic-translations-sdk#176); an added or
    removed one reloads the page.
  • dotnet build and dotnet publish produce the same page. An edited message
    still rebuilds it, as the catalog is a frontend input.
  • The types of the virtual modules are in Frontend/.runic/translations/virtual.d.ts,
    which Vite writes whenever it runs (the build, the development server, the
    frontend test) and src/translations.ts references, so tsc, vue-tsc and
    svelte-check see the exact messages after the first build, as before.
  • The Angular template built with the Angular CLI keeps the ESM from the .NET
    build: the Angular CLI runs no Vite plugins. The Angular template built with
    Vite (#946) uses the plugin.

Applications created from an earlier template keep working. To move a Vite
page to the plugin: add "@runic-artifex/vite-plugin-runic-translations": "0.12.0"
to devDependencies and runicTranslations() to the Vite plugins; import
virtual:runic-translations/app, /runtime and /transport instead of
../.runic/translations/messages.js, runtime.js and transport.js; add
/// <reference path="../.runic/translations/virtual.d.ts" /> to
src/translations.ts; and remove RunicTranslationsEmitEsm and
RunicApplicationFrontendTranslations from the project file.

The template's tests check each Vite frontend's development loop in Chromium:
an edited message shows on the page without a reload, and an added and a
removed one reach the development server's module, under dotnet runic dev.

The Angular template can build with Vite (#946)

dotnet new runic-app --frontend angular --angular-build vite creates the
Angular frontend built, served and tested by Vite through the Analog Angular
plugin (@analogjs/vite-plugin-angular 2.9.7) instead of the Angular CLI.
--angular-build cli stays the default, and dnx Runic.Create asks for the
choice only for Angular. The components are the same; the Vite frontend adds
what the other frontends have:

  • runic() from @runic-artifex/vite-plugin-runic, so the Runic development
    client and, with @vitejs/devtools, the Runic DevTools dock work as for
    React, Vue and Svelte; dotnet runic dev serves the page with Vite.
  • With --translations, the Translations Vite plugin: an edited, added or
    removed message reaches the page under dotnet runic dev without a build.
  • The component build target of trusted component mode, which the Angular CLI
    cannot build (see Trusted component mode for Angular guests).

vite build checks no types, so the build and typecheck scripts run
ngc --noEmit. The frontend test runs on Vitest with the same plugin. Edited
component templates update in place (liveReload); other edits reload the
page. The template's tests build, type-check and test the new frontend with
every package manager, and open its production page in Chromium.

@runic-artifex/angular in the Angular Package Format (#945)

@runic-artifex/angular is built with ng-packagr and published in the Angular
Package Format: one partially compiled FESM bundle per entry point under
dist/fesm2022/, with its typings under dist/types/, in place of the per-file
ngc output under dist/esm/. Imports don't change: @runic-artifex/angular,
@runic-artifex/angular/forms and @runic-artifex/angular/experimental export
the same API, and the Angular CLI builds and tests an application with them as
before. Bundlers that run the Angular linker only on APF files now link the
package too: a production vite build with @analogjs/vite-plugin-angular
failed in the browser with "JIT compiler unavailable" and now renders the page.

Trusted component mode for Angular guests (#947, experimental)

An Angular guest built with Vite and the Analog plugin can now be shown as a
component (RunicHostedWindowDecision.EmbedComponent, experimental under
RUNICDESK103). runicComponentMount from @runic-artifex/angular/experimental
is the mount function of the component build's entry:

// src/component.ts, runic({ component: { entry: "src/component.ts" } })
import { runicComponentMount } from "@runic-artifex/angular/experimental";
import { Widget } from "./app/widget";

export default runicComponentMount(Widget);
  • Each element starts its own zoneless Angular application, whose
    RUNIC_INSTANCE is the element's Runic instance, and renders the standalone
    component in the element's shadow root.
  • Angular's component styles (styles, styleUrl, Emulated or None
    encapsulation) become constructable stylesheets of that shadow root instead
    of <style> elements in document.head. The host document stays unchanged,
    and the host page's Content-Security-Policy needs no 'unsafe-inline' styles.
  • Removing the element destroys its application and its stylesheets, and the
    last element of a bundle also destroys the bundle's Angular platform.
  • @angular/platform-browser is a new optional peer of @runic-artifex/angular,
    for this entry.

The hosted components example's widget has an Angular frontend
(-p:WidgetFrontend=Angular). Its browser smoke runs the component checks of
the build target: tags, styles in each shadow root, updates from the element's
own ViewModel, an unchanged host document and a clean teardown. CI runs it in
Chromium.

Fixes

  • DesktopWindow.OwnedWindows no longer lists an owned window that has closed
    but whose Closed event has not run yet, for example right after its
    WaitForCloseAsync returned (#965).
  • dotnet runic dev run elevated (as administrator) no longer lists WebView2's
    DevTools Protocol endpoint under debugEndpoints in its session file.
    WebView2 Runtime 150 and later ignores WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS
    in an elevated process, so the endpoint never opened. The session file now
    lists it under unavailableDebugEndpoints with "reason": "elevated", and
    dev prints a [dev] Debugging: hint to run it without elevation (#996).
  • On macOS, DesktopWindow.MoveAsync and SetBoundsAsync with a position
    that would put the title bar behind the menu bar, such as y 0, put it just
    below the menu bar, at the work area's top. AppKit took such a frame and
    moved the window again later on its own terms, which could put it back
    where it had opened (#1000).
  • The Bridge generator's bootstrap pass no longer compiles an application's
    transitive project references again into its own obj/runic-bridge/bootstrap
    directories. They were all compiled into one intermediate directory at once,
    which on Windows could fail the build with CS1504 on the shared
    AssemblyAttributes.cs, and made every build compile them twice (#1003).
  • On Linux under an X11 window manager, a window given a placement while
    maximized now restores to that placement's bounds when RestoreAsync comes
    right after SetPlacementAsync. Before, the GTK 4 window sometimes stayed at
    the bounds the window manager had saved. With GTK 3 and GTK 4, the frame
    Openbox reports on the way to maximized no longer replaces the bounds the
    window restores to (#1004).
  • RunicPathWatcher reports a watched file in a directory that was deleted or
    moved away and created again, even when the new file has the old one's size
    and write time. It now compares the file's identity too. Before, this could
    go unreported, as on Windows when another watcher restarted the shared watch
    of the replaced directory (#1008).
  • DesktopWindow.ActivityChanged is raised once for every change of
    Activity, in order, also when changes arrive faster than the handlers run.
    Before, a change the window undid before the handlers ran, such as hiding
    and showing it again, raised no event at all. The event's Activity is that
    change's activity (#1014).
  • dotnet runic package macos retries creating the disk image for up to a
    minute when hdiutil reports a transient "Resource busy" or "Resource
    temporarily unavailable", which a recently ejected image or Spotlight can
    cause; other hdiutil failures still fail the package (#1018).
  • dotnet runic dev writes its session file before it prints [dev] Ready,
    [dev] Window started: process <pid> and [dev] Window exited: process <pid>.
    It printed each line first, so an IDE task or extension that reacted to
    [dev] Ready and then read obj/runic/dev-session.json could still find
    "state": "starting" (#1026).

CI and tests

  • The NVDA slider checks of the accessibility probe no longer flake: the focus
    moves once NVDA has finished with the previous press and moves away and back
    until NVDA names the control, keys wait until NVDA has been quiet since the
    last focus move, and a step whose key did not reach the slider settles on it
    again first. A failure names where UI Automation has the focus and the
    control's value (#988).
  • DrainsAwaitTheModelTurnAsync no longer fails when the thread pool grows on its
    own. It now counts the threads the waiting drains asked from, which only drains
    that block for their turn can make as many as the routes (#998).
  • The /__runic/open test's recording editor writes its record and renames it,
    so the test no longer reads the file before the editor's arguments are in it
    (#1010).
  • The VoiceOver speech checks wait until VoiceOver has said a control's hint,
    or the time for one has passed, before they act; the list box selection
    check confirms the selection in the accessibility tree, makes it once more
    when VoiceOver did not say it, and names the focus and the selected items
    when it fails (#1015).
  • Disk image steps on macOS retry hdiutil's transient "Resource busy" and
    "Resource temporarily unavailable" failures for up to a minute: the volume
    checks' create, attach and detach, and the packaging check's attach and
    detach (eng/ci/hdiutil.sh). A retried attach first detaches what the failed
    attempt left attached, and the last failure prints hdiutil info (#1018).
  • The continuation tests report a command body as waiting at their gate only once
    it waits there. They had reported it just before, so an early release let that
    body run on ahead of one that already waited (#1024).
  • The scaling suite's notification burst measures the steady state of a unit
    after a pause, so its allocation figure no longer depends on thread
    scheduling (#987).
  • The browser smoke starts Chromium on a blank page and navigates it to the
    requested URL, and fails when a redirect drops a requested query parameter;
    the Notes example's ?mode= scenarios now reach the application (#985).
  • A packed application that gets Runic.Platform only through Runic.Desktop,
    and one that also references it, each report RUNICPLAT001 once, in a build
    and in a design-time build (#972).
  • Windows CI runs the template's WebView2 script debugging profile and checks
    that its DevTools Protocol endpoint opens (D066.25).

Known issues

  • WebKitGTK 2.54.0's HTTP inspector accepts any website's Origin and
    Host
    (WebKit bug 330602,
    fixed upstream on 10 November 2026, in no WebKitGTK release yet). While
    WEBKIT_INSPECTOR_HTTP_SERVER holds a port open, any web page the user visits
    can drive the Window's page and, through it, the Bridge. Outside Development
    0.20 clears the variable (#1028); in Development, under dotnet runic dev, it
    is still honoured, so don't set it on an affected WebKitGTK. Use
    WEBKIT_INSPECTOR_SERVER, which no browser page can speak, instead. See
    the browser's developer tools per engine.
  • WebView2's debugging endpoint is not cleared outside Development. Whoever
    sets a Windows release's environment can open it with
    WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS and script the page and its Bridge. See
    release builds.
  • IDE JavaScript debuggers attach only on Windows. WKWebView and WebKitGTK
    open no DevTools Protocol endpoint, so VS Code, Rider, Visual Studio and
    chrome-devtools-mcp cannot attach to the page on macOS and Linux; use
    Safari's Web Inspector or WebKit's own inspector there. On Windows, WebView2
    ignores the endpoint's variable in an elevated Window (#996): run dev and the
    IDE without elevation.
  • The Angular CLI runs no Vite plugins. An Angular frontend built with the
    Angular CLI has no Vite DevTools dock and reloads the page on an edited
    message; Runic Inspect, its C# handlers and its open links work through
    runicDevSessionProxy(). Build the Angular frontend with Vite
    (--angular-build vite, #946) for in-place message updates and the dock.
  • Go to Type Definition on the result of connect…() (Client & Disposable)
    finds nothing; Go to Definition on its members and Go to Type Definition on the
    client and state types open the C# (#952).
  • CS-WebUI drops the query of a request for /. WebUI answers / with a
    redirect to index.html without the query string, so a page opened at
    /?mode=… loses mode. Request /index.html?… directly. The redirect is in
    upstream WebUI, whose binaries CS-WebUI ships unchanged (cs-webui#33).
  • The known issues of 0.19.0 about the side panel, the close drain on an
    installed browser, serve-only mode and CS-WebUI, assistive technologies in
    hosted regions and a guest's prefers-color-scheme in a region are unchanged;
    see
    0.19.0's known issues.

What's Changed

Full Changelog: v0.19.0...v0.20.0