Repository navigation
Runic SDK 0.20.0
Pre-releaseRunic 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
- Bridge errors and warnings while you type,
in Visual Studio, Rider and VS Code, with code fixes. - Runic Inspect:
select an element in the page and see its component, its commands with their
C# handlers, its state and its messages, and
edit a translation on the page. - The dock's Bridge call timeline,
on by default in the template, and
C# handler timing and one trace from the page to .NET. - Generated clients link to their C# sources:
Go to Definition onclient.save()opens the command's handler. - An IDE-ready template and
the Window under your IDE's debugger
whiledotnet runic dev --no-windowruns the frontend. - The Angular template can build with Vite.
- Development tools cost nothing in production.
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.Translationsrequires 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: thedotnet-runic-translationstool,Runic.Translationsand
.Build, and@runic-artifex/vite-plugin-runic-translations. With the plugin
0.12, an edited message updates in place underdotnet runic dev, and Runic
Inspect marks the page's messages and edits them; an earlier plugin reloads
the page and offers no editing. Undervite devthe plugin answers
/__runic-translations/message, which writes the project's.rmf2files, to
the same machine only;inPageEditing: falseturns 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,039and053fail a build
that treats warnings as errors (#962). They now come from the analyzer as
compiler warnings, soTreatWarningsAsErrors(orWarningsAsErrorsnaming
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 withWarningsNotAsErrors(or hide it withNoWarn). -
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
theRunic.Application.Viewsbuild targets (015,019,029,030,033)
are MSBuild warnings, whichTreatWarningsAsErrorsdid not reach. With it they
are now errors too, unlessWarningsNotAsErrorsorNoWarnnames them. -
WebKit's remote inspector opens only in Development on Linux (#1028,
D066.38). WebKitGTK opened it wheneverWEBKIT_INSPECTOR_SERVERor
WEBKIT_INSPECTOR_HTTP_SERVERwas set, also with developer tools off, so a
release could be scripted through it. Now, unlessDOTNET_ENVIRONMENT(or
elseASPNETCORE_ENVIRONMENT) isDevelopment, the GTK 3 and GTK 4 hosts
remove both variables from the process's environment before their first web
view, also whenDevToolsistrue. 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>.tsand
<view>.contract.d.tswith 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 withtsccopies the
.contract.d.tsfiles beside them. See
Generated clients link to their C# sources. -
Bun bundles the development build of
@runic-artifex/viewsby default
(#975).vite build,ng buildandbun build --productionbundle the
production build; pass--productiontobun build, or set
NODE_ENV=productionfor aBun.buildscript, when you build a release page.
The Views MSBuild targets now run the frontend build of an optimized build with
NODE_ENV=productionunless the environment sets it. See
Development tools cost nothing in production. -
dotnet runic doctor --format jsongives each check ahelpUri(#1001).
The payload type staysrunic.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>.tsre-exports every contract type with
export type, soimport { 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.tsand a.contract.d.ts.mapper ViewModel, and the
interfaces move out of<view>.ts; the example clients changed this way. tsc --declarationinto another directory:tscdoesn't copy.d.ts
inputs, so a library that emits declarations for its generated clients copies
the.contract.d.tsfiles beside them.- A generated client no longer imports types it doesn't use (a field-path
client importedFieldBaselineandFieldWriteOptions), 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 asEditorViewModel.save #3, coloured by outcome; - a breakpoint after a reply, such as in a state subscriber, shows a
Runic command EditorViewModel.saveasync 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/openwould, 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/opentherefore 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> msnext to the page's duration. - The history is as long as the timeline (
maxTimelineEntries, 200 by
default) and checked like it./__runic/statelists 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_debugStackthrough 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-translations0.12 or later
undervite 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,altand 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/openaccepts
{ "message": { catalog, key, locale } }, asks the same API, and opens only
the.rmf2/.mf2source it names, never a path from the page. The open
action is now also there withrunic({ sourceMap: false })unless Runic
Inspect is off. - Re-rendering uses the text helpers that follow the text-change channel
(below):useTextLocalein React and Vue, Svelte'suseTextLocale, and
Angular'stextLocaleSignal.
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-translations0.12 in project mode). Only
that entry of the.rmf2/.mf2file 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 enginedotnet runic devruns.
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, souseText,injectText, therunicTextpipe,
textsandsyncDocumentLocaleupdate.- 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 callm.*()through the locale resolver,OnPushones
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 buildanddotnet publishproduce 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) andsrc/translations.tsreferences, sotsc,vue-tscand
svelte-checksee 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 devserves the page with Vite.- With
--translations, the Translations Vite plugin: an edited, added or
removed message reaches the page underdotnet runic devwithout 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_INSTANCEis the element's Runic instance, and renders the standalone
component in the element's shadow root. - Angular's component styles (
styles,styleUrl,EmulatedorNone
encapsulation) become constructable stylesheets of that shadow root instead
of<style>elements indocument.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-browseris 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.OwnedWindowsno longer lists an owned window that has closed
but whoseClosedevent has not run yet, for example right after its
WaitForCloseAsyncreturned (#965).dotnet runic devrun elevated (as administrator) no longer lists WebView2's
DevTools Protocol endpoint underdebugEndpointsin its session file.
WebView2 Runtime 150 and later ignoresWEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS
in an elevated process, so the endpoint never opened. The session file now
lists it underunavailableDebugEndpointswith"reason": "elevated", and
devprints a[dev] Debugging:hint to run it without elevation (#996).- On macOS,
DesktopWindow.MoveAsyncandSetBoundsAsyncwith 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 ownobj/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 whenRestoreAsynccomes
right afterSetPlacementAsync. 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). RunicPathWatcherreports 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.ActivityChangedis 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'sActivityis that
change's activity (#1014).dotnet runic package macosretries 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 devwrites 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] Readyand then readobj/runic/dev-session.jsoncould 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). DrainsAwaitTheModelTurnAsyncno 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/opentest'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 printshdiutil 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.Platformonly throughRunic.Desktop,
and one that also references it, each reportRUNICPLAT001once, 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
Originand
Host(WebKit bug 330602,
fixed upstream on 10 November 2026, in no WebKitGTK release yet). While
WEBKIT_INSPECTOR_HTTP_SERVERholds 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, underdotnet 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_ARGUMENTSand 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-mcpcannot 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): rundevand 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 toindex.htmlwithout the query string, so a page opened at
/?mode=…losesmode. 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'sprefers-color-schemein a region are unchanged;
see
0.19.0's known issues.
What's Changed
- Record the 0.19.0 publication by @ViktorJannicke in #942
- Next candidate 0.20.0 on main (D066.13) by @ViktorJannicke in #943
- @runic-artifex/angular in the Angular Package Format (#945) by @ViktorJannicke in #948
- OwnedWindows lists only open windows (#965) by @ViktorJannicke in #966
- Template: frontends use the Translations Vite plugin (#944) by @ViktorJannicke in #949
- Release-note fragments: one file per pull request (D066.33) by @ViktorJannicke in #980
- Text helpers follow in-place message updates (runic-translations-sdk#176) by @ViktorJannicke in #950
- dotnet runic dev: an IDE contract (window process, ready line, session file) (#959) by @ViktorJannicke in #967
- Bridge calls in the browser: a dev call channel, a Performance track and async stacks (#953) by @ViktorJannicke in #968
- Roslyn analyzers for the Bridge rules: errors as you type, with code fixes (#962) by @ViktorJannicke in #971
- Browser smoke: open and find the requested Chromium page reliably (#985) by @ViktorJannicke in #989
- Angular template built with Vite (Analog plugin) (#946) by @ViktorJannicke in #983
- Scaling suite: deterministic allocation measurements (#987) by @ViktorJannicke in #990
- RUNICPLAT001 for apps that get Runic.Platform through another package (#972) by @ViktorJannicke in #984
- Run the Window under the IDE's debugger while dev runs the frontend (#960) by @ViktorJannicke in #970
- NVDA speech scenarios: reliable slider focus and value checks (#988) by @ViktorJannicke in #992
- Dev source map from Bridge members to C#, and a Runic open-in-editor action (#951) by @ViktorJannicke in #969
- Trusted component mode for Angular guests (#947) by @ViktorJannicke in #986
- dotnet runic dev: session file readers check that dev is still running by @ViktorJannicke in #995
- Tests: a deterministic check that drains hold no thread-pool thread (#998) by @ViktorJannicke in #999
- An IDE-ready template: launch profiles, --editor vscode, New Project dialogs (#961) by @ViktorJannicke in #982
- Development tools cost nothing in production: a development build of @runic-artifex/views (#975) by @ViktorJannicke in #997
- Generated clients link to their C# sources (#952) by @ViktorJannicke in #974
- Template: check the WebView2 debugging profile on Windows in CI (D066.25) by @ViktorJannicke in #993
- Bridge generator: one bootstrap build at a time per project (#1003) by @ViktorJannicke in #1005
- GTK: a window restores to the bounds set while it was maximized (#1004) by @ViktorJannicke in #1007
- File watching: a file in a replaced directory is reported even when its size and time match (#1008) by @ViktorJannicke in #1009
- Runic Inspect: select an element and see how it is connected (#955) by @ViktorJannicke in #973
- Tests: the recording editor writes its record atomically (#1010) by @ViktorJannicke in #1011
- macOS: a move to y 0 lands at the screen's top or below the menu bar, deterministically (#1000) by @ViktorJannicke in #1006
- Runic Inspect for translated text (#956) by @ViktorJannicke in #978
- Bridge analyzers, part 2: warnings and the remaining source rules (#962) by @ViktorJannicke in #994
- GTK: every activity change raises ActivityChanged (#1014) by @ViktorJannicke in #1016
- C# handler timing and joined browser and .NET traces (#958) by @ViktorJannicke in #979
- VoiceOver scenarios: reliable list box selection and value checks (#1015) by @ViktorJannicke in #1017
- Runic Inspect: a button's command before its first click (#976) by @ViktorJannicke in #977
- macOS: disk image steps retry transient hdiutil failures (#1018) by @ViktorJannicke in #1019
- Edit a translation on the page (#957) by @ViktorJannicke in #981
- Dock timeline with C# handlers and open-in-editor; the dock on by default in the template (#954) by @ViktorJannicke in #1002
- dotnet runic dev: session file fields for IDE tools, no WebView2 endpoint for an elevated Window (#1001, #996) by @ViktorJannicke in #1020
- Runic Inspect works under dotnet runic dev: sources and open over Vite's connection (#1012) by @ViktorJannicke in #1013
- Bridge analyzers, part 3: the remaining name rules and warnings as errors (#962) by @ViktorJannicke in #1021
- dotnet runic dev: write the session file before [dev] Ready and the Window lines (#1026) by @ViktorJannicke in #1027
- Bridge analyzers, part 4: the value graph and row editors (#962) by @ViktorJannicke in #1022
- Debugging guide: IDEs, the browser's developer tools per engine, the dock, Runic Inspect and traces (#964) by @ViktorJannicke in #1023
- Tests: continuation probes report waiting only once the body waits at its gate (#1024) by @ViktorJannicke in #1025
- WebKitGTK: no remote inspector outside Development (#1028) by @ViktorJannicke in #1032
- 0.20 train candidate: build against Translations 0.12.0 (T) by @ViktorJannicke in #1034
- 0.20.0 notes and migration guide by @ViktorJannicke in #1035
- Leave the 0.20 train feed: nuget.org lock hashes, published Translations Vite plugin in the template locks by @ViktorJannicke in #1037
Full Changelog: v0.19.0...v0.20.0