@runic-artifex/vite-plugin-runic 0.19.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -19,15 +19,25 @@ omit the plugin entirely. A Runic Views frontend needs neither: its page loads
19
19
  `base: "./"` builds one page for Runic Desktop and CS-WebUI. The Views build
20
20
  passes the host it builds for as `RUNIC_APPLICATION_HOST` for a configuration
21
21
  that still differs per host. The optional
22
- `@vitejs/devtools` peer enables the Runic dock; register `DevTools()` in your
23
- Vite configuration when selecting `devtools: true`. The plugin runs on Node 24.18
24
- or later 24.x, or Node 26.
22
+ `@vitejs/devtools` peer enables the Runic panel of the Vite DevTools dock (in
23
+ this README, "the dock"; not the browser's own developer tools, which open with
24
+ F12 or Inspect): register `DevTools()` in your Vite configuration, as the
25
+ `runic-app` template's Vite starters do. The plugin runs on Node 24.18 or later
26
+ 24.x, or Node 26.
27
+
28
+ ```ts
29
+ import { defineConfig } from "vite";
30
+ import { DevTools } from "@vitejs/devtools";
31
+ import { runic } from "@runic-artifex/vite-plugin-runic";
32
+
33
+ export default defineConfig({ plugins: [runic(), DevTools()] });
34
+ ```
25
35
 
26
36
  `devtools` takes `true`, `false` or `"auto"`. `"auto"` is the default and the
27
37
  same as omitting the option: the development client is injected while serving,
28
38
  and the Runic dock appears when `DevTools()` is registered. `true` also requires
29
39
  `DevTools()`: serving without it fails with
30
- [`RUNICP007`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.19.0/docs/diagnostics.md#runicp007).
40
+ [`RUNICP007`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/docs/diagnostics.md#runicp007).
31
41
  `false` turns off both the dock and the development client.
32
42
  `maxTimelineEntries` sets how many timeline entries the dock keeps: 200 by
33
43
  default, rounded down and limited to 1 to 500.
@@ -87,7 +97,7 @@ or large states are shown shallower. It is part of `/__runic/state` (`views`)
87
97
  and of the copied diagnostic state, which hold no failures.
88
98
 
89
99
  A command that the Bridge answered `superseded` (a
90
- [command scoped to its page](https://github.com/Runic-Artifex/runic-sdk/blob/v0.19.0/packages/web/vite-plugin-runic/../views/README.md#scoped-commands) called from an earlier page)
100
+ [command scoped to its page](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/vite-plugin-runic/../views/README.md#scoped-commands) called from an earlier page)
91
101
  resolves like one that ran, so the page shows nothing. The client reports it
92
102
  as a timeline entry (`kind: "command"`, label `<member> superseded`,
93
103
  `detail.code: "superseded"` with the route, member, the epoch it was issued for
@@ -97,7 +107,490 @@ commands** card. With the Angular CLI, read both from `/__runic/state`.
97
107
  The inspector runs only where the development client does: never in a build.
98
108
  `@runic-artifex/views` reports to it only once the client asked for it
99
109
  (`runic.views.inspector` in the
100
- [shared globals](https://github.com/Runic-Artifex/runic-sdk/blob/v0.19.0/specs/application/README.md#shared-globals)).
110
+ [shared globals](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/specs/application/README.md#shared-globals)).
111
+
112
+ ### Bridge calls in the Performance panel
113
+
114
+ With `@runic-artifex/views` 0.20 or later the development client also listens
115
+ to the Bridge-call channel (`runic.views.calls`). It draws each settled call
116
+ on a **Bridge calls** track in a **Runic** track group of a Chromium engine's
117
+ Performance recording (turn on "Show custom tracks"), and its listening turns
118
+ on the async stack segments that lead from a reply back to the click that made
119
+ the call. See
120
+ [Bridge calls in the browser's developer tools](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/vite-plugin-runic/../views/README.md#bridge-calls-in-the-browsers-developer-tools).
121
+ The dock lists the same calls with their C# handlers (next section).
122
+ Only the
123
+ [development build](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/vite-plugin-runic/../views/README.md#development-build) of
124
+ `@runic-artifex/views` reports calls, which `vite dev` resolves; `vite build`
125
+ bundles the production build, which has no reporting code. A .NET host in Development names each call's C#
126
+ handler and its duration, which the client lists on the call's entry and draws
127
+ on a **C# handlers** track below it.
128
+
129
+ ### OTLP export of the page's spans
130
+
131
+ While serving, the plugin exports a span per Bridge call to an OTLP/HTTP
132
+ endpoint, so the page's call, the .NET `runic.bridge.*` span and the
133
+ ViewModel's own spans form one trace. It is on when `OTEL_EXPORTER_OTLP_ENDPOINT`
134
+ or `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` is set in the development server's
135
+ environment (and off with `OTEL_SDK_DISABLED=true` or `OTEL_TRACES_EXPORTER=none`):
136
+ the development client then gives each call a W3C trace context, which its
137
+ requests carry to .NET, and sends the settled call to the development server,
138
+ which posts it as OTLP/JSON. The page loads no OpenTelemetry code and posts
139
+ nothing cross-origin; a production build contains none of it.
140
+
141
+ ```ts
142
+ runic({ otlp: false }); // never
143
+ runic({ otlp: { url: "http://localhost:4318/v1/traces", serviceName: "notes-page" } });
144
+ ```
145
+
146
+ `url` is the full traces URL; `headers` defaults to `OTEL_EXPORTER_OTLP_HEADERS`,
147
+ and `serviceName` to `OTEL_SERVICE_NAME`, or else the root's package name, with
148
+ `-page` appended. [Tracing Bridge calls](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/vite-plugin-runic/../../../docs/tracing.md) sets it up
149
+ with the Aspire dashboard.
150
+
151
+ ### Bridge call timeline in the dock
152
+
153
+ The client also sends each settled call to the development server, and the
154
+ dock's **Bridge calls** card shows the latest 20, the newest first:
155
+
156
+ ```text
157
+ command EditorViewModel.save → SaveAsync() 23 ms
158
+ C# 21 ms · revision 4 · EditorViewModel.cs:42 · 2026-11-15T10:12:03.120Z
159
+ [Open SaveAsync()]
160
+ ```
161
+
162
+ - **The call.** Its kind (`command`, `set`, `write`, `can`, `region`,
163
+ `operation`, `query`), the C# ViewModel and the member, and how long the page
164
+ waited from the call to its settled reply. A call that did not end `ok` adds
165
+ its outcome and reason, such as `· cancelled (superseded)` or
166
+ `· error (domain-failed)`.
167
+ - **The C# handler.** The plugin looks the call up in the
168
+ [source map](#source-map-and-open-in-editor): `SaveAsync()` for a command's
169
+ `[RelayCommand]` method, `Title.set` for a setter. The button opens it in the
170
+ editor (see [the dock's open action](#the-docks-open-action)). Without a map (no build yet, or
171
+ `sourceMap: false`) the row has no handler.
172
+ - **The handler's own duration.** When the reply carries .NET's timing of the
173
+ handler (a .NET host in Development that measures it), the second line
174
+ starts with `C# <n> ms`, and the call's `handlerDuration` holds it; without it
175
+ the row shows the page's duration only.
176
+ - **Failures.** A failed call shows .NET's exception (the development detail of
177
+ the error reply) and a button for each stack frame in a file of the source
178
+ map, which opens that line, such as `EditorViewModel.SaveAsync() ·
179
+ EditorViewModel.cs:12`. Other frames stay text on the **Last failure** card,
180
+ which links the same frames.
181
+ - **Bounds and privacy.** The server keeps as many calls as timeline entries
182
+ (`maxTimelineEntries`, 200 by default). What the page sends is checked like a
183
+ timeline entry: names and routes of a fixed shape, finite durations, and the
184
+ failure under the failure rules (bounded, credential values redacted). The
185
+ handler comes from the server's own map, and an entry names it by the map's
186
+ member id and the file's name, never a path. `/__runic/state` has the calls
187
+ (`calls`, typed `RunicBridgeCall`) without failures, like the timeline.
188
+
189
+ Under `dotnet runic dev` the window's document is the .NET host's page, which
190
+ loads Vite's modules from Vite's origin, so the dock's own loader (a script
191
+ that loads `/__devtools/embedded.js` relative to the document) finds nothing.
192
+ The development client is one of Vite's modules, so it loads the dock from
193
+ Vite's origin whenever the document's scripts did not; with `html: false`
194
+ (SvelteKit) it always does, and `runic()` removes the dock's HTML hook, which
195
+ SvelteKit would warn about. The first time a page opens the dock, the dock asks
196
+ for the one-time code that Vite DevTools prints in the development server's
197
+ output (shown by `dotnet runic dev`); keep that check on, as it is what keeps
198
+ other pages of this machine out of the dock.
199
+
200
+ ## Source map and open in editor
201
+
202
+ The Bridge generator writes a development source map beside its generated C#
203
+ in `obj` (`obj/<Configuration>/<TargetFramework>/runic-bridge/sources.json`).
204
+ It lists every ViewModel with a generated Bridge and every member its client
205
+ and the Bridge frames name, with the C# that runs for it and where it is.
206
+ `vite dev` serves it at `/__runic/sources`, and `/__runic/open` opens one of
207
+ its locations in your editor. The map never enters the generated TypeScript,
208
+ a `vite build` or a package: production output is the same with and without
209
+ it.
210
+
211
+ ```jsonc
212
+ // GET /__runic/sources
213
+ {
214
+ "format": "runic-bridge-sources/1",
215
+ "viewModels": [{
216
+ "id": "Demo.CounterViewModel", "name": "Counter", "route": "counter",
217
+ "contract": "Demo.CounterViewModel:EE06…", "pageKinds": ["counter"],
218
+ "symbol": "Demo.CounterViewModel",
219
+ "location": { "file": "/src/Demo/CounterViewModel.cs", "line": 6, "column": 29 }
220
+ }],
221
+ "members": [{
222
+ "id": "Demo.CounterViewModel/command/increment", "viewModel": "Demo.CounterViewModel",
223
+ "member": "increment", "kind": "command",
224
+ "symbol": "Demo.CounterViewModel.Increment()", "property": "Demo.CounterViewModel.IncrementCommand",
225
+ "location": { "file": "/src/Demo/CounterViewModel.cs", "line": 18, "column": 18 }
226
+ }]
227
+ }
228
+ ```
229
+
230
+ - **Lookup.** A ViewModel's `id` is the part of a generated client's contract
231
+ before the colon, and `route` is the route `connect<Name>()` connects. A
232
+ member's `id` is `{viewModel}/{kind}/{member}`, where `member` is the name the
233
+ client and the Bridge frames use (`count`, `increment`), and `kind` is one of
234
+ `state` (read through the getter), `setter` (`set…` and `write…`, through the
235
+ setter), `command` (located at its handler: the `[RelayCommand]` method, a
236
+ method group the command is created from, such as
237
+ `ReactiveCommand.CreateFromTask(SaveAsync)`, or else the line that creates
238
+ it), `commandState` (`canSave` and other state a command adds), `interaction`
239
+ and `request`. The TypeScript types are exported as `RunicSourceMap`,
240
+ `RunicSourceMember` and `RunicSourceLocation`.
241
+ - **Locations.** A location is `{ file, line, column }`: the absolute path of a
242
+ local source file and a 1-based line and column, as in a compiler
243
+ diagnostic. They come from the application assembly's portable PDB (the
244
+ default), then from the source of members a source generator writes, such as
245
+ a CommunityToolkit `[ObservableProperty]`. A method is located at its name and
246
+ an accessor at its `get` or `set`, not at the first statement the PDB
247
+ records, so a Debug and a Release build give the same map. Without a PDB or source file an
248
+ entry has no `location`; the build does not fail. A map is as current as the
249
+ last build: `dotnet watch`, and so `dotnet runic dev`, rebuilds it after a C#
250
+ edit, and the plugin reads it again when the file changes.
251
+ - **Where the plugin finds it.** `dotnet runic dev` passes the map's path in
252
+ `RUNIC_APPLICATION_DEV_SOURCE_MAP`. Otherwise, or when that file does not
253
+ exist, the plugin takes the newest `runic-bridge/sources.json` under `obj` of
254
+ the project `dotnet runic dev` runs, else of the Vite root or its parent (the
255
+ project of a `Frontend/` directory). `runic({ sourceMap:
256
+ "../obj/Debug/net10.0/runic-bridge/sources.json" })` names the file, or a
257
+ directory to search, relative to the Vite root. `sourceMap: false` reads no
258
+ map: `/__runic/sources` is gone, and `/__runic/open` opens only frontend
259
+ files. Without a map `/__runic/sources` answers 404.
260
+ - **Opening.** `POST /__runic/open` with `{ "id": "<entry id>" }`, or with
261
+ `{ "file", "line", "column" }` in a file of an entry (`column` defaults to 1;
262
+ a .NET stack frame's line) or in a frontend file Vite serves to the page
263
+ (`server.fs.allow`, without `server.fs.deny`; an absolute, normalized path,
264
+ such as a component that [Runic Inspect](#runic-inspect) links to), opens that
265
+ location with [launch-editor](https://github.com/vitejs/launch-editor), the
266
+ package behind Vite's own editor launcher (`LAUNCH_EDITOR`, else a running
267
+ editor such as VS Code or a JetBrains IDE like Rider, else
268
+ `VISUAL`/`EDITOR`), and answers 200. It is meant for the page and
269
+ other development tools:
270
+
271
+ ```ts
272
+ await fetch("/__runic/open", {
273
+ method: "POST",
274
+ headers: { "Content-Type": "application/json" },
275
+ body: JSON.stringify({ id: "Demo.CounterViewModel/command/increment" }),
276
+ });
277
+ ```
278
+
279
+ - **What it refuses.** Vite's `/__open-in-editor` opens any path; the Runic
280
+ action opens only a file the map lists or a frontend file Vite serves (with
281
+ `server.fs.strict: false`, any file, as Vite then serves any), at a positive
282
+ line and column, and only while the file exists, so a page cannot open
283
+ anything else. It answers a POST of JSON (415 otherwise)
284
+ from a page of the development server's own origin (`Origin` and
285
+ `Sec-Fetch-Site`; a cross-origin page cannot send JSON without a CORS
286
+ preflight, which it never grants) and from this machine (a loopback client
287
+ address), else 403; an id or file the map does not list, an entry
288
+ without a location, and a file that no longer exists answer 404. The map
289
+ itself answers only same-origin requests from this machine too, unless
290
+ other machines are allowed ([Runic Inspect from another machine](#runic-inspect-from-another-machine));
291
+ the open action stays loopback-only, as it launches the editor on this
292
+ machine.
293
+ - **Only development servers.** Both endpoints exist only on the development
294
+ server (`vite dev`, and `ng serve` through `runicDevSessionProxy()`), not in
295
+ `vite build` or `vite preview`.
296
+
297
+ ### The dock's open action
298
+
299
+ The dock's open buttons call the `runic:open-in-editor` Vite DevTools action
300
+ with `{ id }` or a stack frame's `{ file, line }`. It decides what may open
301
+ exactly as `/__runic/open` does (`resolveOpenLocation`: a location in a file
302
+ the current map lists, while the file exists) and refuses everything else,
303
+ launching nothing. Then it opens the location with
304
+ [launch-editor](https://github.com/vitejs/launch-editor) 2.14.2 itself, the
305
+ package behind Vite's `/__open-in-editor`, so the editor is chosen the same
306
+ way (`LAUNCH_EDITOR`, a running editor, `VISUAL`/`EDITOR`). The action makes
307
+ no HTTP request: only clients that Vite DevTools trusts (its one-time code)
308
+ can call an action, which takes the place of the endpoint's origin checks.
309
+ With `sourceMap: false` it opens nothing. It does not open frontend files:
310
+ the dock links only what the map lists.
311
+
312
+ ## Runic Inspect
313
+
314
+ **Runic Inspect** is a select mode of the development client: press
315
+ **Alt+Shift+X** in the page (or call `toggle()`, below), hover an element to
316
+ outline it, and click it to see how it is connected. The selecting click
317
+ reaches no handler of the page: while the mode is on, a transparent layer of
318
+ the overlay takes every pointer event, and the window's capture phase stops
319
+ them. **Esc** or Alt+Shift+X turns it off. The overview shows:
320
+
321
+ - **Component**: the element's framework component and the components around
322
+ it, from each framework's own development metadata, with an editor link:
323
+
324
+ | Framework | What it shows |
325
+ | --- | --- |
326
+ | React 19 | The component and its owners from the element's fiber, and the file:line of the element's JSX: the fiber's `_debugStack` frame resolved through the served module's source map. |
327
+ | Svelte 5 | The component and the file:line:column of the element (`__svelte_meta`). |
328
+ | Vue 3 | The component (`__vueParentComponent`) and its file (`__file`, from the SFC compiler), without a line. |
329
+ | Angular 17.1+ | The component class (`ng.getComponent`/`ng.getOwningComponent`) and, with the compiler's debug info, its file:line (`ɵcmp.debugInfo`). |
330
+
331
+ - **Commands**: the commands the element calls, each with its C# handler (such
332
+ as the `[RelayCommand]` method) and file:line from the
333
+ [source map](#source-map-and-open-in-editor), how often the element called
334
+ it, and its availability state (`canSave`) when the ViewModel has one.
335
+ - **ViewModel members**: the members the element sets (`set…`/`write…`, with
336
+ the C# setter), and state members whose value is the element's text or a
337
+ form control's value, each with its current value and C# member. A value
338
+ match is marked as such: it is a match, not proof.
339
+ - **ViewModels** the element is connected to, with the C# class.
340
+ - **Recent Bridge calls** the element made: kind, member, duration, outcome and
341
+ the reply's revision.
342
+ - **Texts from the ViewModel**: text references (`TextReference` members) the
343
+ element shows, with their catalog, key, locale and arguments.
344
+ - **Messages**: the messages of generated `m.*()` calls the element shows, in
345
+ its text or in an attribute (`title`, `aria-label`, `placeholder`, `alt`, an
346
+ input's value), each with its catalog, key, locale, its text as authored and
347
+ the `.rmf2`/`.mf2` file:line that defines it, and **Edit**, which edits its
348
+ text in every locale in place. See
349
+ [Messages of `m.*()` calls](#messages-of-m-calls) and
350
+ [Edit a translation on the page](#edit-a-translation-on-the-page).
351
+
352
+ C# locations and frontend files open in your editor through
353
+ [`/__runic/open`](#source-map-and-open-in-editor): a C# location by its source
354
+ map id, a frontend file by its path, which the endpoint opens only when Vite
355
+ serves that file to the page. Runic Inspect does not use Vite's
356
+ `/__open-in-editor`, which opens any path for any page.
357
+
358
+ **Under `dotnet runic dev`** the window's document is the .NET host's page,
359
+ which loads Vite's modules from Vite's origin, so a relative URL such as
360
+ `/__runic/sources` names the host. Runic Inspect therefore asks the Vite server
361
+ over the development client's HMR connection instead of HTTP: a
362
+ `runic:request` event (`{ id, kind }` with `kind` `sources`, `handlers` with a
363
+ `file`, `message` with a `target` `{ catalog, key }`, or `open` with a
364
+ `target`), answered by `runic:response` with the same id. The server answers
365
+ as `/__runic/sources`, `/__runic/handlers`, the Translations message API and
366
+ `/__runic/open` do, with the same decision of what opens and the same access
367
+ rules, judged per request from the connection's address (Vite reports it):
368
+ `sources`, `handlers` and `message` for this machine and the hosts and
369
+ networks `allow` and `RUNIC_DEV_ALLOW` admit, `open` for this machine only
370
+ (403 otherwise). Vite admits that connection only with the token in its own client
371
+ module, which only the page's origins Vite's CORS allows can read (by default
372
+ `localhost`, `127.0.0.1` and `[::1]`, the .NET host's page among them), so it
373
+ needs no CORS rule of its own. Without an HMR connection (the Angular CLI, or
374
+ a page that loads the client without Vite's HMR) Inspect uses the HTTP
375
+ endpoints, which also serve tools such as `curl`.
376
+
377
+ **Before the first click.** The development server reads the element's
378
+ component file and finds which of its event handlers reach which client call:
379
+ directly (`client.save()`, `client.command("save")`), through Runic's helpers
380
+ (`useCommand`, `useOperation`, `injectCommand`, `injectOperation`), or through
381
+ other declarations of the same file (a function, a variable, a destructured
382
+ `run`, a class method, `this.x`). The overview lists the calls that are
383
+ commands of a ViewModel in the [source map](#source-map-and-open-in-editor),
384
+ with the C# handler, "from the source, not called yet", and a link to the
385
+ line that calls the client:
386
+
387
+ ```tsx
388
+ const increment = useCommand(() => client?.increment()); // ← found here
389
+ return <button onClick={() => void increment.run()}>Increment</button>;
390
+ ```
391
+
392
+ | Framework | Handlers read | How the element is found |
393
+ | --- | --- | --- |
394
+ | React (JSX/TSX) | `onClick={…}` and every other `on…` prop, of elements and components | The element's JSX line (`_debugStack`); for a `<button onClick={props.onClick}>`, the `<Button onClick={…}>` around it |
395
+ | Vue 3 (SFC) | `@click`/`v-on:click` in the template, with `<script setup>` and the Options API (`methods`, `setup()`) | The element's compiled listeners (`$setup.increment()`), else its component's only binding of the event |
396
+ | Svelte 5 | `onclick={…}` and `on:click={…}`, of elements and components | The element's file, line and column (`__svelte_meta`), then the component tags around it |
397
+ | Angular 17.1+ | `(click)="…"` in `template` and `templateUrl` files, with the class's fields and methods | The component file (`ɵcmp.debugInfo`) and `ng.getListeners`: the template's binding of the event and tag, by its order when there are several |
398
+
399
+ Svelte and Vue files are read with the application's own `svelte/compiler`
400
+ and `vue/compiler-sfc`, scripts with Vite's parser. Served modules are not
401
+ changed: the analysis answers `GET /__runic/handlers?file=…` for pages of this
402
+ machine, for frontend source files below the Vite root (not `node_modules`).
403
+
404
+ What it does not see, so the command is learned on first click:
405
+
406
+ - calls in other files: a store, a service, a custom hook or a function
407
+ imported from another module. The overview names the import
408
+ (`saveAll from ./store`);
409
+ - handlers that come from outside the component: a prop passed down several
410
+ components, a context, an event bus;
411
+ - elements that a template repeats with different handlers where the
412
+ framework does not say which one it is: an Angular `@for` with listeners that
413
+ differ per item, a Vue listener whose compiled code is the method itself
414
+ (`@click="save"`) when the component has several such bindings;
415
+ - render functions (`h("button", { onClick })`) and Vue JSX.
416
+
417
+ **On first click.** The development client also listens to the Bridge-call
418
+ channel (`runic.views.calls`), whose `start` report arrives in the stack of
419
+ the code that made the call. The DOM event being dispatched names the element
420
+ (its `target`, so React's delegation to the root does not matter), and the
421
+ nearest button, link or form field is recorded as calling that member. A
422
+ command found this way is marked with its call count; it covers what the
423
+ source analysis does not see. Use the element once with the mode off, then
424
+ inspect it. A call that does not run during the event, such as a write a
425
+ field controller sends after its previous one finished, is not attributed.
426
+
427
+ **For agents and tests**, the development client puts an API on the page at
428
+ `globalThis[Symbol.for("runic.vite.inspect")]`:
429
+
430
+ ```ts
431
+ const inspect = (globalThis as any)[Symbol.for("runic.vite.inspect")];
432
+ inspect.toggle(true); // select mode on, which marks m.*() text; returns whether it is on
433
+ const overview = await inspect.describe(document.querySelector("#save"));
434
+ // { element, component, viewModels, members, commands, calls, texts, messages, notes }
435
+ await inspect.select(document.querySelector("#save")); // shows the overview card
436
+ await inspect.open(overview.commands[0].location); // opens it in the editor
437
+ ```
438
+
439
+ `describe(element)` resolves to JSON-safe data (the type is exported as
440
+ `RunicInspectDescription`); values are shortened, and `notes` says what the
441
+ overview cannot tell, such as a missing source map. `messages` is filled only
442
+ while select mode is on: call `toggle(true)` and let the page render once
443
+ before `describe`. With `chrome-devtools-mcp` or Playwright, evaluate it in
444
+ the page.
445
+
446
+ Runic Inspect is plain DOM in a shadow root, so it works in every engine
447
+ `dotnet runic dev` runs: an installed browser, WebView2, WKWebView and
448
+ WebKitGTK. It is part of the development client, which a build replaces with
449
+ an empty module: `vite build` output is byte-identical with and without it.
450
+ `runic({ inspect: false })` leaves it out of the client (with the translation
451
+ editor) and turns off `/__runic/handlers`. Under the Angular CLI, `runicDevSessionProxy()` answers
452
+ `/__runic/sources`, `/__runic/open` and `/__runic/handlers` too
453
+ ([SvelteKit and Angular](#sveltekit-and-angular)), so the overview has the C#
454
+ handlers and the commands before the first click there as well.
455
+
456
+ ### Messages of `m.*()` calls
457
+
458
+ A generated message function returns a plain string, so nothing in the page
459
+ says which message a text came from. Runic Inspect asks Runic Translations to
460
+ mark it, **only while select mode is on**:
461
+
462
+ - Turning select mode on calls `markers.set(true)` on the Translations
463
+ text-change channel (`globalThis[Symbol.for("runic.translations.text")]`).
464
+ The page renders its messages again, as on a language switch, and every
465
+ `m.*()` call puts an invisible marker in front of its text that names the
466
+ message. Turning select mode off renders the plain text again. Outside
467
+ select mode the page's text, `textContent`, copied text and tests see no
468
+ markers.
469
+ - The markers are invisible format characters that take no width, so the
470
+ layout does not change. While select mode is on they are also in attribute
471
+ values and anything else the text went into; the overview strips them from
472
+ the element's text.
473
+ - For each message it finds, the overview asks the Translations dev server
474
+ for its source (`GET /__runic-translations/message`, or over Vite's
475
+ connection as above, where the server asks it), and its link opens it
476
+ through `/__runic/open` with `{ "message": { catalog, key, locale } }`. The
477
+ open action never takes a path for a message: it asks the same API and
478
+ opens only the `.rmf2`/`.mf2` source it names.
479
+
480
+ It needs `@runic-artifex/vite-plugin-runic-translations` 0.12 or later under
481
+ `vite dev` (the markers, and in project mode with in-page editing on, the
482
+ source locations), and text helpers that render again on the text-change
483
+ channel: `useTextLocale` in React and Vue, Svelte's `useTextLocale` or
484
+ `useMessageLocale`, Angular's `textLocaleSignal`, as for a language switch. A
485
+ component that does not render again, or a value computed once (such as
486
+ `document.title`), keeps its text unmarked. Text formatted from a ViewModel's
487
+ text reference is listed under **Texts from the ViewModel** instead. With an
488
+ earlier plugin, the overview has no messages and its notes say why.
489
+
490
+ ### Edit a translation on the page
491
+
492
+ Select a text in Runic Inspect and press **Edit** next to its message. The
493
+ panel below the overview reads the message from Runic Translations' in-page
494
+ editing API (`GET /__runic-translations/message`) and shows:
495
+
496
+ - a **locale** list, base locale first, starting with the locale the page
497
+ shows; a locale without text of its own is marked `(missing)`, and saving it
498
+ adds the message beside the base locale's;
499
+ - where the locale's text is defined (`translations/de.rmf2:4`), and for a
500
+ library's text, the application override a save writes instead;
501
+ - its **structure**: the inputs (`$count :integer`), what it selects on
502
+ (`$count (plural): one · *`), the locale's plural categories, with the ones
503
+ that have no variant, and the markup it uses (`{#strong}`);
504
+ - the **MF2 source** of that locale, exactly as authored: declarations,
505
+ `.match` and its variants, placeholders and markup. Plural, selector, markup
506
+ and document messages are edited as their whole source.
507
+
508
+ **Save** (or Ctrl+Enter, ⌘+Enter) posts the text with the hash of the file it
509
+ was read from. Runic Translations compiles it with the rest of the catalog and
510
+ writes it with the Translations Editor's source-preserving writer: only that
511
+ entry changes, and the file keeps its comments, formatting and order. The dev
512
+ server then updates the page **in place**, as for a save in an editor: no
513
+ reload, the page keeps its state, and the card keeps its selection and
514
+ describes the element again with the new text. Each locale keeps its own
515
+ unsaved text while you switch between them. There is no separate preview: the
516
+ page itself shows the saved text.
517
+
518
+ - **The text does not compile** (422): the panel lists the RTR diagnostics
519
+ with their lines, keeps your text, and nothing is written.
520
+ - **The file changed since it was read** (409), for example saved in an
521
+ editor: the panel shows the text in the file now. **Reapply my text** keeps
522
+ your text and saves it over the current file; **Use the file's text** drops
523
+ your edit. When the page's text changes and you have not edited the locale,
524
+ the panel reads the message again on its own.
525
+ - **Not allowed** (403): the panel says how to allow this machine (below).
526
+
527
+ The panel is plain DOM in the overlay's shadow root, so it works in every
528
+ engine `dotnet runic dev` runs. Tab moves through the locale list, the text,
529
+ Save and Revert; **Esc** in the panel closes it and returns to its Edit button.
530
+ Typing in it does not reach the page's own key handlers. Selecting another
531
+ element closes the panel unless it has unsaved text.
532
+
533
+ It needs `@runic-artifex/vite-plugin-runic-translations` 0.12 or later in
534
+ project mode (the `project` option), with `inPageEditing` on, which is the
535
+ default under `vite dev`. Without it, the overview lists messages without
536
+ **Edit**.
537
+
538
+ ### Runic Inspect from another machine
539
+
540
+ The development server can serve a page to another machine: a laptop on the
541
+ same [Tailscale](https://tailscale.com/kb/1015/100.x-addresses) network, or
542
+ the browser of a laptop that shows a page of a dev server an agent runs on a
543
+ local server. Start Vite on a reachable address (`server.host`, `vite --host`)
544
+ and name the machines that may use Runic Inspect's data there:
545
+
546
+ ```sh
547
+ RUNIC_DEV_ALLOW="100.64.0.0/10, fd7a:115c:a1e0::/48" vite dev --host
548
+ ```
549
+
550
+ ```ts
551
+ runic({ allow: ["100.64.0.0/10", "192.168.1.20", "laptop.tailnet.ts.net"] })
552
+ ```
553
+
554
+ Entries are IPv4 or IPv6 addresses, CIDR networks, or host names (resolved
555
+ when a request arrives, and cached for 30 seconds); the environment variable
556
+ takes the same entries separated by commas or spaces and adds to the option.
557
+ An invalid entry stops the dev server with its name, and a non-empty list is
558
+ logged at start. `RUNIC_DEV_ALLOW` is one setting for both plugins: Runic
559
+ Translations' in-page editing API reads it too (its older
560
+ `RUNIC_TRANSLATIONS_EDIT_ALLOW` and `inPageEditing: { allow }` still work), so
561
+ the same variable lets that machine read the source map and handler analysis
562
+ and edit translations.
563
+
564
+ | Endpoint | Loopback | An allowed machine | Any other machine |
565
+ | --- | --- | --- | --- |
566
+ | `/__runic/sources`, `/__runic/handlers` | yes | yes | 403 |
567
+ | `/__runic-translations/message` (Runic Translations) | yes | yes | 403 |
568
+ | `/__runic/open` | yes | 403 | 403 |
569
+
570
+ `/__runic/open` launches an editor **on the development machine**, so it stays
571
+ loopback-only. A page opened from another machine (its address is not
572
+ `localhost`) shows file:line locations without links, and its notes say why.
573
+ When a machine is refused, the overview's notes name what was refused and the
574
+ setting that allows it.
575
+
576
+ **Security.**
577
+
578
+ - **Loopback by default.** Without a list, every endpoint answers only the
579
+ machine the dev server runs on (`127.0.0.0/8`, `::1`), judged by the TCP
580
+ connection's address; `X-Forwarded-For` and similar headers are ignored. A
581
+ reverse proxy on the same machine makes every client look like loopback.
582
+ - **Same origin.** A request must come from a page of the dev server itself
583
+ (`Sec-Fetch-Site`, `Origin`), so another site, or another dev server on a
584
+ different port, cannot read the data or write a translation. Vite's host check
585
+ (`server.allowedHosts`) runs first and refuses DNS-rebinding hosts; allow the
586
+ host names your other machines use there (IP addresses are allowed by
587
+ default).
588
+ - **Allow only machines you trust with your sources.** An allowed machine can
589
+ read the source map and the analysis of frontend files, and change the
590
+ catalog's translation sources.
591
+ - **Development only.** Nothing of it is in `vite build` or `vite preview`
592
+ output: the build is byte-identical with and without Runic Inspect, the
593
+ editor and the allow list.
101
594
 
102
595
  ## Component build target
103
596
 
@@ -114,7 +607,12 @@ export default defineConfig({
114
607
  ```
115
608
 
116
609
  The entry's default export is the mount function of
117
- [`@runic-artifex/views/component`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.19.0/packages/web/vite-plugin-runic/../views/README.md#components). `vite build`
610
+ [`@runic-artifex/views/component`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/vite-plugin-runic/../views/README.md#components). With Angular,
611
+ the Analog plugin (`angular()`) compiles the component's code ahead of time as
612
+ it does the page's, and `runicComponentMount` of `@runic-artifex/angular/experimental`
613
+ is the mount function; it keeps Angular's component styles, which Angular adds
614
+ to the document at run time rather than to the build's CSS, in the shadow root
615
+ ([Angular components](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/vite-plugin-runic/../angular/README.md#components-experimental)). `vite build`
118
616
  then builds every environment, as `vite build --app` does, and after them the
119
617
  `runic_component` environment into `_runic_component/` of the build output:
120
618
 
@@ -158,6 +656,12 @@ a component's.
158
656
 
159
657
  ## SvelteKit and Angular
160
658
 
659
+ Angular built with Vite, through the Analog Angular plugin
660
+ (`plugins: [angular({ liveReload: true }), runic()]`), uses `runic()` as the other
661
+ frameworks do (`dotnet new runic-app --frontend angular --angular-build vite`);
662
+ see the [Angular package](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/vite-plugin-runic/../angular/README.md#building-with-the-angular-cli-or-vite).
663
+ What follows covers SvelteKit and the Angular CLI.
664
+
161
665
  SvelteKit renders its pages itself and warns about every plugin with a
162
666
  `transformIndexHtml` hook. Use `runic({ html: false })`: the plugin then has no
163
667
  such hook, injects nothing into HTML and leaves host scripts alone, and keeps
@@ -166,7 +670,7 @@ The page loads the client from its client hooks:
166
670
 
167
671
  ```ts
168
672
  // vite.config.ts
169
- plugins: [sveltekit({ adapter: runicAdapter() }), runic({ html: false })],
673
+ plugins: [sveltekit({ adapter: runicAdapter() }), runic({ html: false }), DevTools()],
170
674
  ```
171
675
 
172
676
  ```ts
@@ -174,6 +678,10 @@ plugins: [sveltekit({ adapter: runicAdapter() }), runic({ html: false })],
174
678
  import "@runic-artifex/vite-plugin-runic/client";
175
679
  ```
176
680
 
681
+ With `DevTools()` registered the client loads the dock as well, and `runic()`
682
+ removes the dock's own HTML hook, which SvelteKit would warn about and never
683
+ run.
684
+
177
685
  `html: false` cannot be combined with `desktop`, whose bootstrap is a script
178
686
  tag in the HTML: `runic({ html: false, desktop: true })` throws.
179
687
 
@@ -204,7 +712,8 @@ the build cannot evaluate a function call.
204
712
  The entries keep the development state in the `ng serve` process and answer:
205
713
 
206
714
  - `/__runic/state` with that state, as `runic()` does: the connection, the
207
- timeline without failures, and under `dotnet runic dev` the session header
715
+ timeline and the Bridge calls (without C# handlers: the Angular CLI's server
716
+ reads no source map) without failures, and under `dotnet runic dev` the session header
208
717
  ([Dev session](#dev-session-and-host-scripts)). The answer is `200` with JSON; without `dotnet runic dev` the
209
718
  entry answers too, without the header.
210
719
  - `/__runic/diagnostics`, which the client posts its reports to. Each Views
@@ -217,9 +726,20 @@ The entries keep the development state in the `ng serve` process and answer:
217
726
  at Notes.Editor.Save() in /src/Notes/Editor.cs:line 12
218
727
  ```
219
728
 
220
- `runicDevSessionProxy({ maxTimelineEntries, printFailures })` takes the same
221
- timeline limit as `runic()` and `printFailures: false` to keep the terminal
222
- quiet. The `stale-input` warning works the same as with `runic()`; turn it off
729
+ For [Runic Inspect](#runic-inspect), the entries also answer
730
+ `/__runic/sources` (the development source map, found as `runic()` finds it,
731
+ relative to the `ng serve` working directory), `/__runic/open` (a C# location,
732
+ opened through the Angular development server's `/__open-in-editor`) and
733
+ `/__runic/handlers` (the handler analysis of a component and its
734
+ `templateUrl`), each for pages of this machine only, unless `allow` or
735
+ `RUNIC_DEV_ALLOW` admits other machines to `/__runic/sources` and
736
+ `/__runic/handlers` ([Runic Inspect from another machine](#runic-inspect-from-another-machine)).
737
+
738
+ `runicDevSessionProxy({ maxTimelineEntries, printFailures, sourceMap, inspect, allow })`
739
+ takes the same timeline limit as `runic()`, `printFailures: false` to keep the
740
+ terminal quiet, `sourceMap` as `runic({ sourceMap })` takes it (`false` turns
741
+ off `/__runic/sources` and `/__runic/open`), `inspect: false` to turn off
742
+ `/__runic/handlers`, and `allow` as `runic({ allow })` takes it. The `stale-input` warning works the same as with `runic()`; turn it off
223
743
  from the page with the registered symbol above.
224
744
 
225
745
  ### The client's channel
@@ -0,0 +1,46 @@
1
+ import type { IncomingMessage } from "node:http";
2
+ /** Hosts and networks, besides loopback, that may read the development data: comma- or space-separated. */
3
+ export declare const allowVariable = "RUNIC_DEV_ALLOW";
4
+ /** One entry of the allow list, validated. */
5
+ export type AccessRule = {
6
+ readonly kind: "address";
7
+ readonly text: string;
8
+ readonly address: string;
9
+ readonly family: "ipv4" | "ipv6";
10
+ } | {
11
+ readonly kind: "network";
12
+ readonly text: string;
13
+ readonly address: string;
14
+ readonly prefix: number;
15
+ readonly family: "ipv4" | "ipv6";
16
+ } | {
17
+ readonly kind: "host";
18
+ readonly text: string;
19
+ readonly name: string;
20
+ };
21
+ /** Validates allow-list entries; throws a TypeError naming the entry and `source` for an invalid one. */
22
+ export declare function parseAllowList(entries: unknown, source: string): AccessRule[];
23
+ /** The entries of the environment variable: separated by commas or whitespace. */
24
+ export declare function allowListFromEnvironment(value: string | undefined): string[];
25
+ /** An IPv4-mapped IPv6 address (`::ffff:192.0.2.1`) as its IPv4 address; any other address unchanged, without a zone. */
26
+ export declare function normalizeAddress(address: string): string;
27
+ /** Whether a client address is loopback: 127.0.0.0/8 or ::1 (also IPv4-mapped). */
28
+ export declare function isLoopbackAddress(address: string | undefined): boolean;
29
+ /** Decides whether a client address may read the development data: loopback, or one of the rules. */
30
+ export declare class AccessList {
31
+ #private;
32
+ readonly rules: readonly AccessRule[];
33
+ constructor(rules?: readonly AccessRule[], lookup?: (name: string) => Promise<readonly string[]>);
34
+ /** Whether the list admits more than loopback. */
35
+ get remote(): boolean;
36
+ allows(address: string | undefined): Promise<boolean>;
37
+ /** Whether the request's client (its connection's address) is admitted. */
38
+ allowsRequest(request: IncomingMessage): Promise<boolean>;
39
+ }
40
+ /** Loopback only: what the endpoints accept without configuration. */
41
+ export declare const loopbackOnly: AccessList;
42
+ /**
43
+ * The access list of a development server: the option's entries (validated when the plugin is created), then
44
+ * `RUNIC_DEV_ALLOW`'s, each validated under its own name.
45
+ */
46
+ export declare function resolveAccessList(option: readonly AccessRule[], environment?: Readonly<Record<string, string | undefined>>): AccessList;