@runic-artifex/vite-plugin-runic 0.13.0 → 0.15.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
@@ -27,7 +27,7 @@ or later 24.x, or Node 26.
27
27
  same as omitting the option: the development client is injected while serving,
28
28
  and the Runic dock appears when `DevTools()` is registered. `true` also requires
29
29
  `DevTools()`: serving without it fails with
30
- [`RUNICP007`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.13.0/docs/diagnostics.md#runicp007).
30
+ [`RUNICP007`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.15.0/docs/diagnostics.md#runicp007).
31
31
  `false` turns off both the dock and the development client.
32
32
  `maxTimelineEntries` sets how many timeline entries the dock keeps: 200 by
33
33
  default, rounded down and limited to 1 to 500.
@@ -36,7 +36,7 @@ While serving, the plugin adds `virtual:runic/client`, which loads the
36
36
  development client (`@runic-artifex/vite-plugin-runic/client`), to `index.html`.
37
37
  The client has no exports. It shows the page's connection to its .NET host, as
38
38
  `@runic-artifex/views` reports it (`connecting`, `connected`, `reconnecting`,
39
- `lost`), on the dock's **Connection** card from page load, before a View
39
+ `lost`, and `closed` once the application closed the window), on the dock's **Connection** card from page load, before a View
40
40
  connects (with `@runic-artifex/views` 0.11 or later; earlier releases start it
41
41
  when the first View connects), and forwards
42
42
  `@runic-artifex/views` failures to the timeline: the failed route, the
@@ -47,7 +47,11 @@ dock shows the most recent one. A failure keeps file paths, so that a stack is
47
47
  useful, but is bounded and has credential values redacted. Failures stay in
48
48
  the dock: `/__runic/state` and the copied diagnostic state leave them out, and
49
49
  the other timeline fields stay path-free. An application without a Vite-served `index.html` imports
50
- `virtual:runic/client` itself. `devtools: false` disables the injection.
50
+ the client itself, with `import "@runic-artifex/vite-plugin-runic/client"` (or
51
+ `virtual:runic/client`): `runic()` resolves that import to the same module it
52
+ injects while serving, and to an empty module in the build and on the server,
53
+ so nothing reaches production output. `devtools: false` turns the client off:
54
+ no injection, and an import of it is empty.
51
55
  The plugin adds `@runic-artifex/vite-plugin-runic/client` to
52
56
  `optimizeDeps.include`, because the dependency scanner cannot see the injected
53
57
  client: with a cold `node_modules/.vite` cache, the first page would otherwise
@@ -66,6 +70,117 @@ fields with the text-field binding of your framework package
66
70
  `runic({ staleInputWarning: false })`, or from the page by setting
67
71
  `globalThis[Symbol.for("runic.vite.staleInputWarning")] = false`.
68
72
 
73
+ ### State inspector
74
+
75
+ With `@runic-artifex/views` 0.15 or later the development client also reports
76
+ each open View's state, as the page shows it, and the dock shows it on the
77
+ **Views** card: one card per View with its route, revision and presentation
78
+ epoch, the most recently changed first, and the state as a tree. The client
79
+ sends a View's latest state at most every 250 ms, and the server keeps the 32
80
+ Views that changed last, per page (several windows can share one development
81
+ server), and forgets a View when it closes and a page's Views when the page
82
+ goes away. The state is redacted and bounded like timeline details: a member
83
+ whose name suggests a credential or a path (`password`, `accessToken`,
84
+ `filePath`, …) and a string that looks like a credential or a path read
85
+ `[redacted]`, strings are shortened, long lists end with `… N more`, and deep
86
+ or large states are shown shallower. It is part of `/__runic/state` (`views`)
87
+ and of the copied diagnostic state, which hold no failures.
88
+
89
+ A command that the Bridge answered `superseded` (a
90
+ [command scoped to its page](https://github.com/Runic-Artifex/runic-sdk/blob/v0.15.0/packages/web/vite-plugin-runic/../views/README.md#scoped-commands) called from an earlier page)
91
+ resolves like one that ran, so the page shows nothing. The client reports it
92
+ as a timeline entry (`kind: "command"`, label `<member> superseded`,
93
+ `detail.code: "superseded"` with the route, member, the epoch it was issued for
94
+ and the reply's revision), and the dock lists the latest on the **Superseded
95
+ commands** card. With the Angular CLI, read both from `/__runic/state`.
96
+
97
+ The inspector runs only where the development client does: never in a build.
98
+ `@runic-artifex/views` reports to it only once the client asked for it
99
+ (`runic.views.inspector` in the
100
+ [shared globals](https://github.com/Runic-Artifex/runic-sdk/blob/v0.15.0/specs/application/README.md#shared-globals)).
101
+
102
+ ## SvelteKit and Angular
103
+
104
+ SvelteKit renders its pages itself and warns about every plugin with a
105
+ `transformIndexHtml` hook. Use `runic({ html: false })`: the plugin then has no
106
+ such hook, injects nothing into HTML and leaves host scripts alone, and keeps
107
+ everything else: the timeline, the dock, `/__runic/state` and the dev session.
108
+ The page loads the client from its client hooks:
109
+
110
+ ```ts
111
+ // vite.config.ts
112
+ plugins: [sveltekit({ adapter: runicAdapter() }), runic({ html: false })],
113
+ ```
114
+
115
+ ```ts
116
+ // src/hooks.client.ts
117
+ import "@runic-artifex/vite-plugin-runic/client";
118
+ ```
119
+
120
+ `html: false` cannot be combined with `desktop`, whose bootstrap is a script
121
+ tag in the HTML: `runic({ html: false, desktop: true })` throws.
122
+
123
+ The Angular CLI's development server loads no Vite plugins, only a proxy
124
+ configuration. `runicDevSessionProxy()` returns Vite proxy entries that answer
125
+ locally and never proxy. Spread it into the file that the serve target's
126
+ `proxyConfig` in `angular.json` names:
127
+
128
+ ```js
129
+ // proxy.conf.mjs
130
+ import { runicDevSessionProxy } from "@runic-artifex/vite-plugin-runic";
131
+
132
+ export default { ...runicDevSessionProxy() };
133
+ ```
134
+
135
+ and load the client from `main.ts` in development only:
136
+
137
+ ```ts
138
+ // src/main.ts, before bootstrapApplication
139
+ if (typeof ngDevMode === "undefined" || ngDevMode) await import("@runic-artifex/vite-plugin-runic/client");
140
+ ```
141
+
142
+ A production build (`optimization` on, the default `production`
143
+ configuration) defines `ngDevMode` as `false`, so the import and the client's
144
+ chunk are left out. `isDevMode()` would keep the chunk in the output, because
145
+ the build cannot evaluate a function call.
146
+
147
+ The entries keep the development state in the `ng serve` process and answer:
148
+
149
+ - `/__runic/state` with that state, as `runic()` does: the connection, the
150
+ timeline without failures, and under `dotnet runic dev` the session header
151
+ ([Dev session](#dev-session-and-host-scripts)). The answer is `200` with JSON; without `dotnet runic dev` the
152
+ entry answers too, without the header.
153
+ - `/__runic/diagnostics`, which the client posts its reports to. Each Views
154
+ failure is printed to the `ng serve` terminal with its exception type,
155
+ message and stack:
156
+
157
+ ```text
158
+ [runic] views editorSave failed
159
+ System.InvalidOperationException: Disk full.
160
+ at Notes.Editor.Save() in /src/Notes/Editor.cs:line 12
161
+ ```
162
+
163
+ `runicDevSessionProxy({ maxTimelineEntries, printFailures })` takes the same
164
+ timeline limit as `runic()` and `printFailures: false` to keep the terminal
165
+ quiet. The `stale-input` warning works the same as with `runic()`; turn it off
166
+ from the page with the registered symbol above.
167
+
168
+ ### The client's channel
169
+
170
+ Loaded by `runic()`, the client reports over Vite's HMR connection. Loaded
171
+ otherwise, it posts each report as `{ "event", "data" }` JSON to
172
+ `/__runic/diagnostics` on its own origin, one at a time and in order, and keeps
173
+ at most 100 waiting. `runic()` answers that endpoint too. The endpoint accepts
174
+ only a `POST` with `Content-Type: application/json` and an `Origin` of the
175
+ server itself (a cross-site page would need a CORS preflight, which it never
176
+ grants), rejects a `Sec-Fetch-Site` other than `same-origin` and a body over
177
+ 64 KiB, and sanitizes every entry like any other timeline entry. If the first
178
+ report gets no `204` answer, the page has no Runic development server, and the
179
+ client stops and removes its listeners. Without Vite's HMR context the client
180
+ installs the `stale-input` warning only after that first answer.
181
+
182
+ ## Dev session and host scripts
183
+
69
184
  Under `dotnet runic dev`, the Vite process gets a random value for the session
70
185
  in `RUNIC_APPLICATION_DEV_SESSION`, and `/__runic/state` answers with it in the
71
186
  `X-Runic-Dev-Session` header. Since 0.11, `dev` treats the server as ready
@@ -75,29 +190,11 @@ Pages and other responses do not carry the header. Use the plugin from the same
75
190
  release as `dotnet-runic`, because an older plugin does not answer and `dev`
76
191
  times out with `RAPPDEV1007`.
77
192
 
78
- Two exports answer only the session, for development servers that cannot use
79
- `runic()`. Without `dotnet runic dev` neither changes anything.
80
-
81
- - `runicDevSession()` is a Vite plugin without `runic()`'s HTML hooks, for
82
- SvelteKit, which warns about plugins with a `transformIndexHtml` hook:
83
-
84
- ```ts
85
- plugins: [sveltekit({ adapter: runicAdapter() }), runicDevSession()],
86
- ```
87
-
88
- - `runicDevSessionProxy()` returns Vite proxy entries, for the Angular CLI,
89
- which takes a proxy configuration but no Vite plugins. Spread it into the
90
- file that the serve target's `proxyConfig` in `angular.json` names:
91
-
92
- ```js
93
- // proxy.conf.mjs
94
- import { runicDevSessionProxy } from "@runic-artifex/vite-plugin-runic";
95
-
96
- export default { ...runicDevSessionProxy() };
97
- ```
98
-
99
- `dotnet runic dev` expects the answer from an Angular frontend whose
100
- `package.json` declares this package.
193
+ `runicDevSessionProxy()` answers the session for the Angular CLI (above).
194
+ `dotnet runic dev` expects the answer from an Angular frontend whose
195
+ `package.json` declares this package. `runicDevSession()`, which answered only
196
+ the session, was removed in 0.15: SvelteKit uses `runic({ html: false })`
197
+ (above).
101
198
 
102
199
  The `runic-app` template's SvelteKit and Angular frontends are set up this way.
103
200
 
@@ -0,0 +1,16 @@
1
+ export declare const diagnosticEvent = "runic:diagnostic";
2
+ export declare const connectionEvent = "runic:connection";
3
+ /** The state inspector: a View's state, a closed View, or a page that went away (`DevelopmentTimeline.applyView`). */
4
+ export declare const viewEvent = "runic:view";
5
+ /** The endpoint a client posts `{ "event", "data" }` to, one message per request, answered with 204. */
6
+ export declare const diagnosticsPath = "/__runic/diagnostics";
7
+ /**
8
+ * The largest request body the endpoint accepts. A sanitized diagnostic with a failure is at most about 12,000
9
+ * characters, so this leaves room for JSON escaping and multibyte text.
10
+ */
11
+ export declare const maximumClientMessageBytes = 65536;
12
+ /** `{ channel?: "hot" }` on `globalThis`, set by `virtual:runic/client` before the client evaluates. */
13
+ export declare const clientOptionsKey: unique symbol;
14
+ export interface RunicClientOptions {
15
+ readonly channel?: "hot";
16
+ }
@@ -0,0 +1,21 @@
1
+ // The channel between the development client and the development server, shared by both sides.
2
+ //
3
+ // `runic()` loads the client through `virtual:runic/client`, which sets the client options below to the HMR channel:
4
+ // the client sends with `import.meta.hot.send`, and the plugin listens on `server.ws`. A client that loads otherwise
5
+ // (the Angular CLI's development server, which runs no Vite plugins, or an application import of the package) posts
6
+ // each message to `diagnosticsPath` instead, which `runic()` and `runicDevSessionProxy()` answer.
7
+ //
8
+ // A sanitized View state is at most about 16,000 characters (diagnostics.ts, `sanitizeViewState`).
9
+ export const diagnosticEvent = "runic:diagnostic";
10
+ export const connectionEvent = "runic:connection";
11
+ /** The state inspector: a View's state, a closed View, or a page that went away (`DevelopmentTimeline.applyView`). */
12
+ export const viewEvent = "runic:view";
13
+ /** The endpoint a client posts `{ "event", "data" }` to, one message per request, answered with 204. */
14
+ export const diagnosticsPath = "/__runic/diagnostics";
15
+ /**
16
+ * The largest request body the endpoint accepts. A sanitized diagnostic with a failure is at most about 12,000
17
+ * characters, so this leaves room for JSON escaping and multibyte text.
18
+ */
19
+ export const maximumClientMessageBytes = 65_536;
20
+ /** `{ channel?: "hot" }` on `globalThis`, set by `virtual:runic/client` before the client evaluates. */
21
+ export const clientOptionsKey = Symbol.for("runic.vite.client");
package/dist/client.js CHANGED
@@ -1,16 +1,73 @@
1
- // The development client that the plugin injects into served pages. It forwards the
2
- // diagnostics and connection state of `@runic-artifex/views` to the DevTools dock and warns
3
- // about script that overwrites a focused text field with an older value (`stale-input`). It
4
- // has no exports: applications do not import it.
5
- import { sanitizeDiagnosticSummary } from "./diagnostics.js";
1
+ import { clientOptionsKey, connectionEvent, diagnosticEvent, diagnosticsPath, maximumClientMessageBytes, viewEvent, } from "./channel.js";
2
+ import { sanitizeDiagnosticSummary, sanitizeViewState } from "./diagnostics.js";
6
3
  import { installStaleInputWarning } from "./stale-input.js";
4
+ const host = globalThis;
7
5
  const hot = import.meta.hot;
8
- const diagnosticEvent = "runic:diagnostic";
9
- const connectionEvent = "runic:connection";
6
+ const options = host[clientOptionsKey];
7
+ // The listeners of a previous evaluation (HMR), so this copy replaces them.
8
+ const data = hot?.data ?? {};
9
+ // Messages wait in order, one request at a time, so a later connection state never overtakes an earlier one.
10
+ const maximumPendingMessages = 100;
11
+ const pending = [];
12
+ let posting = false;
13
+ // `open` after the endpoint first answered, `closed` after it did not: then the page has no Runic development server
14
+ // (a build that kept the client, a server without the endpoint), and the client stops.
15
+ let channel = "unknown";
16
+ function post(event, payload) {
17
+ if (channel === "closed")
18
+ return;
19
+ const body = JSON.stringify({ event, data: payload });
20
+ const encoder = host.TextEncoder;
21
+ const size = encoder ? new encoder().encode(body).byteLength : body.length * 3;
22
+ if (size > maximumClientMessageBytes)
23
+ return;
24
+ pending.push(body);
25
+ if (pending.length > maximumPendingMessages)
26
+ pending.shift();
27
+ if (!posting)
28
+ void drain();
29
+ }
30
+ async function drain() {
31
+ const fetch = host.fetch;
32
+ posting = true;
33
+ try {
34
+ while (pending.length > 0 && channel !== "closed") {
35
+ const body = pending.shift();
36
+ let answered = false;
37
+ try {
38
+ const response = await fetch?.(diagnosticsPath, {
39
+ method: "POST",
40
+ headers: { "Content-Type": "application/json" },
41
+ body,
42
+ credentials: "same-origin",
43
+ cache: "no-store",
44
+ });
45
+ answered = response?.status === 204;
46
+ }
47
+ catch { /* answered stays false */ }
48
+ if (!answered) {
49
+ close();
50
+ return;
51
+ }
52
+ if (channel === "unknown") {
53
+ channel = "open";
54
+ // Without Vite's HMR context only the answer shows that a development server serves the page.
55
+ if (!hot)
56
+ installStaleInputWarning(globalThis);
57
+ }
58
+ }
59
+ }
60
+ finally {
61
+ posting = false;
62
+ }
63
+ }
64
+ const send = hot && options?.channel === "hot"
65
+ ? (event, payload) => hot.send(event, payload)
66
+ : post;
10
67
  function sendDiagnostic(candidate) {
11
68
  const summary = sanitizeDiagnosticSummary(candidate);
12
69
  if (summary)
13
- hot?.send(diagnosticEvent, summary);
70
+ send(diagnosticEvent, summary);
14
71
  }
15
72
  // @runic-artifex/views publishes runtime failures on a page-wide listener set
16
73
  // under this registered symbol, so this client needs no dependency on it.
@@ -26,7 +83,7 @@ function fallbackType(code) {
26
83
  return "StaleInputWarning";
27
84
  return "BridgeError";
28
85
  }
29
- /** Forwards a Views runtime diagnostic to the DevTools timeline. */
86
+ /** Forwards a Views runtime diagnostic to the timeline. */
30
87
  function reportViewsDiagnostic(diagnostic) {
31
88
  const route = typeof diagnostic.route === "string" ? diagnostic.route.slice(0, 120) : undefined;
32
89
  const code = typeof diagnostic.code === "string" ? diagnostic.code.slice(0, 32) : "error";
@@ -48,17 +105,18 @@ function reportViewsDiagnostic(diagnostic) {
48
105
  ...(error ? { failure: diagnostic.detail ?? { type: fallbackType(code), message } } : {}),
49
106
  });
50
107
  }
108
+ function viewsDiagnostics() {
109
+ const listeners = host;
110
+ return listeners[viewsDiagnosticsKey] ??= new Set();
111
+ }
51
112
  function connectViewsDiagnostics() {
52
- if (!hot)
53
- return;
54
- const host = globalThis;
55
- const listeners = host[viewsDiagnosticsKey] ??= new Set();
113
+ const listeners = viewsDiagnostics();
56
114
  // HMR re-evaluates this module; replace the listener of the previous copy.
57
- const previous = hot.data[viewsListenerKey];
115
+ const previous = data[viewsListenerKey];
58
116
  if (previous)
59
117
  listeners.delete(previous);
60
118
  listeners.add(reportViewsDiagnostic);
61
- hot.data[viewsListenerKey] = reportViewsDiagnostic;
119
+ data[viewsListenerKey] = reportViewsDiagnostic;
62
120
  }
63
121
  // @runic-artifex/views publishes the page's connection state on this channel once a View
64
122
  // connects, or from page load when this client asks for it with `requested` and `start`
@@ -66,29 +124,120 @@ function connectViewsDiagnostics() {
66
124
  const viewsConnectionKey = Symbol.for("runic.views.connection");
67
125
  const connectionListenerKey = "runic:connection-listener";
68
126
  function reportConnection(state) {
69
- hot?.send(connectionEvent, { state });
127
+ send(connectionEvent, { state });
128
+ }
129
+ function viewsConnection() {
130
+ const channels = host;
131
+ return channels[viewsConnectionKey] ??= { listeners: new Set() };
70
132
  }
71
133
  function connectViewsConnection() {
72
- if (!hot)
73
- return;
74
- const host = globalThis;
75
- const channel = host[viewsConnectionKey] ??= { listeners: new Set() };
76
- const previous = hot.data[connectionListenerKey];
134
+ const connection = viewsConnection();
135
+ const previous = data[connectionListenerKey];
77
136
  if (previous)
78
- channel.listeners.delete(previous);
79
- channel.listeners.add(reportConnection);
80
- hot.data[connectionListenerKey] = reportConnection;
81
- if (typeof channel.state === "string")
82
- reportConnection(channel.state);
137
+ connection.listeners.delete(previous);
138
+ connection.listeners.add(reportConnection);
139
+ data[connectionListenerKey] = reportConnection;
140
+ // The first report also opens the HTTP channel, so it is sent even before a View has a state.
141
+ if (typeof connection.state === "string" || send === post)
142
+ reportConnection(connection.state ?? "unknown");
83
143
  // Observe from page load, not only once a View connects: a copy of @runic-artifex/views that
84
144
  // loads later sees `requested`, and one that already loaded has set `start`.
85
- channel.requested = true;
86
- if (typeof channel.start === "function")
87
- channel.start();
145
+ connection.requested = true;
146
+ if (typeof connection.start === "function")
147
+ connection.start();
148
+ }
149
+ // The state inspector. @runic-artifex/views 0.15 or later reports to this channel once a reader set `requested`
150
+ // (specs/application, "Shared globals"): each route's state as its presentations receive it, a closed route, and a
151
+ // command the producer answered `superseded`. The client sends a route's latest state at most every 250 ms.
152
+ const viewsInspectorKey = Symbol.for("runic.views.inspector");
153
+ const inspectorListenerKey = "runic:inspector-listener";
154
+ const pageHideListenerKey = "runic:page-hide-listener";
155
+ const pageKey = "runic:page";
156
+ const stateInterval = 250;
157
+ // Several windows can share one development server, so the server keeps Views per page.
158
+ const page = typeof data[pageKey] === "string" ? data[pageKey] : (data[pageKey] = randomPage());
159
+ const pendingStates = new Map();
160
+ let stateTimer;
161
+ function randomPage() {
162
+ return `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`.slice(0, 32);
163
+ }
164
+ function sendStates() {
165
+ stateTimer = undefined;
166
+ for (const event of pendingStates.values()) {
167
+ send(viewEvent, {
168
+ page, route: event.route, revision: event.revision, epoch: event.epoch, presentations: event.presentations,
169
+ // Sanitized here too, so that the state leaves the page bounded and redacted.
170
+ state: sanitizeViewState(event.state),
171
+ });
172
+ }
173
+ pendingStates.clear();
174
+ }
175
+ function reportInspector(event) {
176
+ if (typeof event !== "object" || event === null || typeof event.route !== "string")
177
+ return;
178
+ if (event.kind === "state") {
179
+ pendingStates.set(event.route, event);
180
+ stateTimer ??= setTimeout(sendStates, stateInterval);
181
+ }
182
+ else if (event.kind === "closed") {
183
+ pendingStates.delete(event.route);
184
+ send(viewEvent, { page, route: event.route, closed: true });
185
+ }
186
+ else if (event.kind === "superseded") {
187
+ // The call resolved like one that ran, so only the timeline shows that nothing ran.
188
+ sendDiagnostic({
189
+ source: "views",
190
+ kind: "command",
191
+ label: `${String(event.member).slice(0, 80)} superseded`,
192
+ detail: {
193
+ code: "superseded", route: event.route.slice(0, 120), member: String(event.member).slice(0, 80),
194
+ ...(typeof event.epoch === "number" ? { epoch: event.epoch } : {}),
195
+ ...(typeof event.revision === "number" ? { revision: event.revision } : {}),
196
+ },
197
+ });
198
+ }
199
+ }
200
+ function viewsInspector() {
201
+ const channels = host;
202
+ return channels[viewsInspectorKey] ??= { listeners: new Set() };
203
+ }
204
+ function pageHidden() {
205
+ pendingStates.clear();
206
+ send(viewEvent, { page, closed: true });
207
+ }
208
+ function connectViewsInspector() {
209
+ const inspector = viewsInspector();
210
+ const previous = data[inspectorListenerKey];
211
+ if (previous)
212
+ inspector.listeners.delete(previous);
213
+ inspector.listeners.add(reportInspector);
214
+ data[inspectorListenerKey] = reportInspector;
215
+ inspector.requested = true;
216
+ // The page's Views go away with it; the server also keeps only the 32 most recent.
217
+ const previousHide = data[pageHideListenerKey];
218
+ if (previousHide)
219
+ host.removeEventListener?.("pagehide", previousHide);
220
+ host.addEventListener?.("pagehide", pageHidden);
221
+ data[pageHideListenerKey] = pageHidden;
222
+ }
223
+ // Removes this copy's listeners once the HTTP channel has no server to report to.
224
+ function close() {
225
+ channel = "closed";
226
+ pending.length = 0;
227
+ viewsDiagnostics().delete(reportViewsDiagnostic);
228
+ viewsConnection().listeners.delete(reportConnection);
229
+ viewsInspector().listeners.delete(reportInspector);
230
+ host.removeEventListener?.("pagehide", pageHidden);
231
+ if (stateTimer !== undefined)
232
+ clearTimeout(stateTimer);
233
+ stateTimer = undefined;
234
+ pendingStates.clear();
88
235
  }
89
236
  connectViewsDiagnostics();
90
237
  connectViewsConnection();
91
- // Development only: without Vite's HMR context (a production build that imports the client)
92
- // nothing is installed. Installs once per page; HMR re-evaluation leaves it in place.
238
+ connectViewsInspector();
239
+ // Vite's HMR context shows that a development server serves the page: install the warning now. Without it
240
+ // (a production build that kept the client), the HTTP channel installs it once the server answers. Installs once
241
+ // per page; HMR re-evaluation leaves it in place.
93
242
  if (hot)
94
243
  installStaleInputWarning(globalThis);
@@ -1,17 +1,36 @@
1
- import type { Plugin, ProxyOptions } from "vite";
1
+ import type { IncomingMessage, ServerResponse } from "node:http";
2
+ import type { ProxyOptions } from "vite";
3
+ import type { RunicDevelopmentState, RunicTimelineEntry } from "./timeline.js";
2
4
  export declare const devSessionVariable = "RUNIC_APPLICATION_DEV_SESSION";
3
5
  export declare const devSessionHeader = "X-Runic-Dev-Session";
6
+ export declare const statePath = "/__runic/state";
4
7
  /** The session value `dotnet runic dev` set, when it has the shape the tool writes: 32 to 128 hex digits. */
5
8
  export declare function devSessionValue(value: string | undefined): string | undefined;
9
+ /** Answers `/__runic/state` with the path-free state, and with the `dotnet runic dev` session when there is one. */
10
+ export declare function answerState(response: ServerResponse, state: RunicDevelopmentState, session: string | undefined): void;
6
11
  /**
7
- * A Vite plugin that only answers `/__runic/state` with the `dotnet runic dev` session, for a configuration that
8
- * cannot use `runic()`: SvelteKit, which warns about `runic()`'s `transformIndexHtml` hook. `runic()` already
9
- * answers it. Without `dotnet runic dev` the plugin does nothing.
12
+ * Answers a development client's POST to `/__runic/diagnostics`: `{ "event", "data" }` from the same origin, as JSON
13
+ * of at most `maximumClientMessageBytes`. Calls `deliver` with an accepted message and answers 204.
10
14
  */
11
- export declare function runicDevSession(): Plugin;
15
+ export declare function answerClientMessage(request: IncomingMessage, response: ServerResponse, deliver: (event: string, data: unknown) => void): Promise<void>;
16
+ export interface RunicDevSessionProxyOptions {
17
+ /** How many timeline entries `/__runic/state` keeps: 200 by default, rounded down and limited to 1 to 500. */
18
+ readonly maxTimelineEntries?: number;
19
+ /**
20
+ * `false` stops printing the development client's failures (an `error` entry with its exception type, message and
21
+ * stack) to the development server's terminal. Defaults to `true`.
22
+ */
23
+ readonly printFailures?: boolean;
24
+ }
12
25
  /**
13
- * Vite proxy entries that answer `/__runic/state` with the `dotnet runic dev` session, for a development server
14
- * that takes a Vite proxy configuration but no Vite plugins: the Angular CLI's `proxyConfig`. Spread the result
15
- * into the proxy configuration. Without `dotnet runic dev` it is empty and changes nothing.
26
+ * Vite proxy entries for a development server that takes a Vite proxy configuration but no Vite plugins: the
27
+ * Angular CLI's `proxyConfig`. Spread the result into the proxy configuration. The entries never proxy; they answer:
28
+ *
29
+ * - `/__runic/state` with the path-free development state, and under `dotnet runic dev` with its session;
30
+ * - `/__runic/diagnostics`, which the development client (`@runic-artifex/vite-plugin-runic/client`) posts the
31
+ * page's Views diagnostics, connection state and View states to. The timeline is bounded, and failures go to the
32
+ * terminal.
16
33
  */
17
- export declare function runicDevSessionProxy(): Record<string, ProxyOptions>;
34
+ export declare function runicDevSessionProxy(options?: RunicDevSessionProxyOptions): Record<string, ProxyOptions>;
35
+ /** A failure for the terminal: the entry's source and label, then the exception type, message and stack. */
36
+ export declare function formatFailure(entry: RunicTimelineEntry): string;