@hydranium/client-theia 1.0.0-next.8 → 1.0.0-next.86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/client-theia",
-  "version": "1.0.0-next.8",
+  "version": "1.0.0-next.86",
   "description": "Cross-head Theia client primitives shared by the hydranium protocol heads. Provides the socket-forwarding connection-handler base that the data-server and GLSP Theia integrations subclass, plus the preference-driven Output-channel logger; carries no head-specific dependency.",
   "keywords": [
     "hydranium",
@@ -36,6 +36,14 @@
       "types": "./lib/browser/index.d.ts",
       "default": "./lib/browser/index.js"
     },
+    "./common": {
+      "types": "./lib/common/index.d.ts",
+      "default": "./lib/common/index.js"
+    },
+    "./lib/common": {
+      "types": "./lib/common/index.d.ts",
+      "default": "./lib/common/index.js"
+    },
     "./node": {
       "types": "./lib/node/index.d.ts",
       "default": "./lib/node/index.js"
@@ -70,9 +78,9 @@
     "watch": "tsc -b -w --preserveWatchOutput"
   },
   "devDependencies": {
-    "@hydranium/protocol": "1.0.0-next.8",
-    "@theia/core": "^1.71.0",
-    "@theia/output": "^1.71.0",
+    "@hydranium/protocol": "1.0.0-next.86",
+    "@theia/core": "^1.70.0",
+    "@theia/output": "^1.70.0",
     "@types/node": "^22.0.0",
     "inversify": "6.2.2",
     "reflect-metadata": "0.2.2",
@@ -80,9 +88,9 @@
     "typescript": "^5.8.0"
   },
   "peerDependencies": {
-    "@hydranium/protocol": "1.0.0-next.8",
-    "@theia/core": "^1.71.0",
-    "@theia/output": "^1.71.0",
+    "@hydranium/protocol": "1.0.0-next.86",
+    "@theia/core": "^1.70.0",
+    "@theia/output": "^1.70.0",
     "inversify": "^6.0.0"
   },
   "engines": {
@@ -91,5 +99,6 @@
   "publishConfig": {
     "access": "public"
   },
+  "//peerDependencies": "@theia/core stays at 1.70 here, matching the sibling Theia packages, even though the connection-resilience bindings need 1.71: Theia only began binding `SocketWriteBuffer` then, and before that each connection built one privately, so there is no binding to rebind. Rather than split the package's floor for one feature, `bindConnectionResilience` probes for that binding and warns instead of installing when it is absent — a capability check rather than a version parse, so it answers about the container in front of it. Everything else the feature touches exists at 1.70, and the emitted declarations deliberately name no type that 1.70 lacks, so the package still compiles there. Verified by unpacking 1.70, 1.71 and 1.72, not inferred from a changelog.",
   "//prepack": "The publish guard, and it deliberately is NOT a `prepare`: npm runs a workspace `prepare` BEFORE the root `postinstall` that applies patches/vscode-jsonrpc+9.0.1.patch, so building there fails on a cold clone and npm rolls the entire install back. `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. It FAILS rather than rebuilds, because the rebuild is exactly the part that ordering defeats. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error."
 }

package/src/browser/connection-diagnostics-contribution.ts

@@ -0,0 +1,142 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { MessageService, nls } from '@theia/core';
+import { FrontendApplicationContribution } from '@theia/core/lib/browser/frontend-application-contribution';
+import { ConnectionStatus, ConnectionStatusService } from '@theia/core/lib/browser/connection-status-service';
+import { WebSocketConnectionSource } from '@theia/core/lib/browser/messaging/ws-connection-source';
+import { inject, injectable, type interfaces } from '@theia/core/shared/inversify';
+import { type ConnectionBufferOverflow } from '../common/framed-socket-write-buffer';
+import { ChannelLogger } from './channel-logger';
+import { SessionAwareConnectionSource } from './session-aware-connection-source';
+
+/**
+ * Records the browser side of the websocket lifecycle into the adopter's Output
+ * channel, and tells the user the one thing they cannot recover from on their
+ * own.
+ *
+ * Theia reports an outage only as an "Offline" status-bar item, which cannot
+ * distinguish a plain network drop from the server having stopped answering on a
+ * socket that is still up. The latter is what a connection defect looks like
+ * from here, so the two are logged differently — that distinction is what says
+ * whether reopening an editor helps or only a reload does.
+ *
+ * Purely observational apart from the overflow message: nothing here changes how
+ * the connection behaves.
+ */
+@injectable()
+export class ConnectionDiagnosticsContribution implements FrontendApplicationContribution {
+   @inject(WebSocketConnectionSource) protected readonly connectionSource: WebSocketConnectionSource;
+   @inject(ConnectionStatusService) protected readonly connectionStatus: ConnectionStatusService;
+   @inject(ChannelLogger) protected readonly logger: ChannelLogger;
+   @inject(MessageService) protected readonly messageService: MessageService;
+
+   /** Main channels created so far; more than one means the server did not recognise this frontend. */
+   protected channelCount = 0;
+   protected socketClosedAt?: number;
+   protected offlineAt?: number;
+
+   initialize(): void {
+      this.connectionSource.onSocketDidOpen(() => this.handleSocketOpen());
+      this.connectionSource.onSocketDidClose(() => this.handleSocketClose());
+      this.connectionSource.onConnectionDidOpen(() => this.handleChannelOpen());
+      this.connectionStatus.onStatusChange(status => this.handleStatusChange(status));
+      if (this.connectionSource instanceof SessionAwareConnectionSource) {
+         this.connectionSource.onBufferOverflow(overflow => this.handleBufferOverflow(overflow));
+      }
+      // The socket is opened by the preloader, before this contribution exists, so the first
+      // `onSocketDidOpen` has already fired; state the current situation instead.
+      this.logger.info(`diagnostics active; socket ${this.socketId()}, backend ${this.statusName(this.connectionStatus.currentStatus)}`);
+   }
+
+   protected handleSocketOpen(): void {
+      const downFor = this.socketClosedAt === undefined ? '' : ` after ${Date.now() - this.socketClosedAt} ms down`;
+      this.socketClosedAt = undefined;
+      this.logger.info(`websocket connected: socket ${this.socketId()}${downFor}`);
+   }
+
+   protected handleSocketClose(): void {
+      this.socketClosedAt = Date.now();
+      this.logger.info(`websocket disconnected: socket ${this.socketId()}; outgoing messages are buffered until it returns`);
+   }
+
+   /**
+    * A second channel means the reconnect was refused and the session discarded.
+    * Only reachable with `reloadOnReconnect` off — with it on, Theia reloads the
+    * page instead of opening another channel.
+    */
+   protected handleChannelOpen(): void {
+      this.channelCount++;
+      if (this.channelCount === 1) {
+         this.logger.info(`initial channel opened on socket ${this.socketId()}`);
+         return;
+      }
+      this.logger.warn(
+         `new channel #${this.channelCount} on socket ${this.socketId()}: the backend did not recognise this frontend, ` +
+            'so its session was discarded and every pending request rejected'
+      );
+   }
+
+   protected handleStatusChange(status: ConnectionStatus): void {
+      if (status === ConnectionStatus.ONLINE) {
+         const offlineFor = this.offlineAt === undefined ? '' : ` after ${Date.now() - this.offlineAt} ms`;
+         this.offlineAt = undefined;
+         this.logger.info(`backend reachable again${offlineFor}`);
+         return;
+      }
+      this.offlineAt = Date.now();
+      const socket = this.connectionSource.socket;
+      if (socket?.connected) {
+         this.logger.warn(
+            `backend stopped answering while socket ${socket.id} is still connected: nothing this session sends will ` +
+               'arrive, and socket.io will not reconnect on its own. Reload the page to recover.'
+         );
+         return;
+      }
+      this.logger.info(`backend unreachable; websocket is disconnected (socket ${this.socketId()})`);
+   }
+
+   /**
+    * The outage outlasted what the buffer can hold, so changes made from here on
+    * are being thrown away rather than queued. Reconnecting resumes sending but
+    * cannot bring those back, which leaves the editor disagreeing with the
+    * server — and without a message the user would see nothing but an editor
+    * that has quietly stopped saving, so say it plainly.
+    */
+   protected handleBufferOverflow(overflow: ConnectionBufferOverflow): void {
+      this.logger.error(`buffer full at ${overflow.maxBytes} bytes holding ${overflow.messages} message(s)`);
+      this.messageService.error(
+         nls.localize(
+            'hydranium/connection/offlineLimitReached',
+            'Disconnected for too long: recent changes were not sent. Reload the page before continuing.'
+         )
+      );
+   }
+
+   protected socketId(): string {
+      return this.connectionSource.socket?.id ?? WebSocketConnectionSource.NO_CONNECTION;
+   }
+
+   protected statusName(status: ConnectionStatus): string {
+      return status === ConnectionStatus.ONLINE ? 'online' : 'offline';
+   }
+}
+
+/**
+ * Bind {@link ConnectionDiagnosticsContribution} as a `FrontendApplicationContribution`.
+ *
+ * Needs a {@link ChannelLogger} binding, so call it from a module that has also
+ * called `bindChannelLogger`. Unlike `bindConnectionResilience` this belongs in a
+ * normal frontend module: it only observes, so it has no reason to run during
+ * preload, and `MessageService` is not available that early.
+ */
+export function bindConnectionDiagnostics(bind: interfaces.Bind): void {
+   bind(ConnectionDiagnosticsContribution).toSelf().inSingletonScope();
+   bind(FrontendApplicationContribution).toService(ConnectionDiagnosticsContribution);
+}

package/src/browser/index.ts

@@ -12,3 +12,5 @@ export * from './channel-logger';
 export * from './log-level-preference';
 export * from './browser-capture';
 export * from './memory-diagnostics-contribution';
+export * from './session-aware-connection-source';
+export * from './connection-diagnostics-contribution';

package/src/browser/log-level-preference.ts

@@ -108,7 +108,18 @@ export class LogLevelPreferenceContribution implements FrontendApplicationContri
    protected applyLevel(): void {
       const level = parseLogLevel(this.preferences.get<string>(this.preferenceName));
       if (level) {
+         const previous = Logger.getLevel();
          Logger.setLevel(level);
+         if (previous !== level) {
+            // Through Theia's `ILogger`, which has a threshold of its own and so
+            // is not silenced by the value just applied — the framework logger
+            // this preference governs would drop the line on a switch to `error`.
+            //
+            // Frontend and server announce separately: this preference reaches
+            // the server only if a client delivers it as configuration, so one
+            // line without the other says it did not.
+            this.logger.info(`Log level ${previous} → ${level} (preference '${this.preferenceName}')`);
+         }
       }
    }
 }

package/src/browser/memory-diagnostics-contribution.ts

@@ -14,7 +14,7 @@ import {
    type StartProfilingArgs
 } from '@hydranium/protocol';
 import { captureBrowserRuntime, formatBrowserRuntime } from './browser-capture';
-import { CommandContribution, MessageService, type Command, type CommandRegistry } from '@theia/core';
+import { CommandContribution, MessageService, nls, type Command, type CommandRegistry } from '@theia/core';
 import { inject, injectable, optional, type interfaces } from '@theia/core/shared/inversify';
 import { OutputChannelManager, type OutputChannel } from '@theia/output/lib/browser/output-channel';
 
@@ -54,6 +54,17 @@ export const MemoryDiagnosticsService = Symbol('MemoryDiagnosticsService');
 export type HostMemoryDiagnosticsService = HostDiagnosticsProtocol;
 export const HostMemoryDiagnosticsService = Symbol('HostMemoryDiagnosticsService');
 
+/**
+ * What a `report` call captured, as a code rather than a prose fragment. The
+ * sentences it appears in are authored once per code, because a fragment
+ * substituted into a sentence is itself translatable text and a translator
+ * given the sentence alone cannot inflect around a hole.
+ */
+export type DiagnosticsSubject = 'server-state' | 'pod-memory' | 'latency' | 'backend-state' | 'profile';
+
+/** Which process a heap snapshot is taken of; a code, for the reason {@link DiagnosticsSubject} is one. */
+export type HeapSnapshotTarget = 'server' | 'backend';
+
 /**
  * Memory-diagnostics commands, one per layer reachable from the frontend. Full
  * multi-line snapshots are appended to the configured output channel; a one-line
@@ -88,76 +99,162 @@ export class MemoryDiagnosticsContribution implements CommandContribution {
     * localized apart, leaving a button or an instruction that names a command
     * the user cannot find.
     */
-   protected readonly stopProfilingLabel: string = 'Stop Profiling (Server)';
+   protected readonly stopProfilingLabel: string = nls.localize(
+      'hydranium/client-theia/command-stop-profiling-server',
+      'Stop Profiling (Server)'
+   );
 
    registerCommands(registry: CommandRegistry): void {
       const { category } = this.options;
-      registry.registerCommand(this.command('dumpServerState', 'Dump Server State', category), {
-         execute: () => this.report('server state', () => this.diagnostics.dumpServerState({ label: new Date().toISOString() }), ['heap'])
-      });
-      registry.registerCommand(this.command('dumpPodMemory', 'Dump Pod Memory', category), {
-         execute: () => this.report('pod memory', () => this.diagnostics.dumpPodMemory(), ['current', 'rss sum'])
-      });
-      registry.registerCommand(this.command('dumpFrontendState', 'Dump Frontend State', category), {
-         execute: () => this.dumpFrontendState()
-      });
-      registry.registerCommand(this.command('writeHeapSnapshot', 'Write Heap Snapshot (Server)', category), {
-         execute: () => this.writeSnapshot('server', label => this.diagnostics.writeHeapSnapshot({ label }))
-      });
+      registry.registerCommand(
+         this.command({
+            id: 'dumpServerState',
+            label: nls.localize('hydranium/client-theia/command-dump-server-state', 'Dump Server State'),
+            category
+         }),
+         {
+            execute: () =>
+               this.report('server-state', () => this.diagnostics.dumpServerState({ label: new Date().toISOString() }), ['heap'])
+         }
+      );
+      registry.registerCommand(
+         this.command({
+            id: 'dumpPodMemory',
+            label: nls.localize('hydranium/client-theia/command-dump-pod-memory', 'Dump Pod Memory'),
+            category
+         }),
+         {
+            execute: () => this.report('pod-memory', () => this.diagnostics.dumpPodMemory(), ['current', 'rss sum'])
+         }
+      );
+      registry.registerCommand(
+         this.command({
+            id: 'dumpFrontendState',
+            label: nls.localize('hydranium/client-theia/command-dump-frontend-state', 'Dump Frontend State'),
+            category
+         }),
+         {
+            execute: () => this.dumpFrontendState()
+         }
+      );
+      registry.registerCommand(
+         this.command({
+            id: 'writeHeapSnapshot',
+            label: nls.localize('hydranium/client-theia/command-write-heap-snapshot-server', 'Write Heap Snapshot (Server)'),
+            category
+         }),
+         {
+            execute: () => this.writeSnapshot('server', label => this.diagnostics.writeHeapSnapshot({ label }))
+         }
+      );
       // Sampled profiling of the server process — sampling does NOT pause it (unlike
       // the heap snapshot). Start/Stop are the manual pair; Record wraps a fixed window.
-      registry.registerCommand(this.command('startProfiling', 'Start Profiling (Server)', category), {
-         execute: () => this.startProfiling()
-      });
-      registry.registerCommand(this.command('stopProfiling', this.stopProfilingLabel, category), {
+      registry.registerCommand(
+         this.command({
+            id: 'startProfiling',
+            label: nls.localize('hydranium/client-theia/command-start-profiling-server', 'Start Profiling (Server)'),
+            category
+         }),
+         {
+            execute: () => this.startProfiling()
+         }
+      );
+      registry.registerCommand(this.command({ id: 'stopProfiling', label: this.stopProfilingLabel, category }), {
          execute: () => this.stopProfiling()
       });
       registry.registerCommand(
-         this.command('recordProfile', `Record Performance Profile (Server, ${Math.round(this.recordDurationMs / 1000)}s)`, category),
+         this.command({
+            id: 'recordProfile',
+            // The window length rides the substitution path rather than a
+            // template literal: an extractor reads the source text, so an
+            // interpolated default is never in the catalogue at all.
+            label: nls.localize(
+               'hydranium/client-theia/command-record-profile',
+               'Record Performance Profile (Server, {0}s)',
+               this.recordDurationSeconds()
+            ),
+            category
+         }),
          {
             execute: () => this.recordProfile()
          }
       );
-      registry.registerCommand(this.command('dumpLatency', 'Dump RPC/LSP Latency (Server)', category), {
-         execute: () => this.report('RPC/LSP latency', async () => formatLatencyReport(await this.diagnostics.getLatency()), ['window'])
-      });
+      registry.registerCommand(
+         this.command({
+            id: 'dumpLatency',
+            label: nls.localize('hydranium/client-theia/command-dump-latency', 'Dump RPC/LSP Latency (Server)'),
+            category
+         }),
+         {
+            execute: () => this.report('latency', async () => formatLatencyReport(await this.diagnostics.getLatency()), ['window'])
+         }
+      );
       // Host (Theia backend) process commands — registered only when the
       // optional host-diagnostics service is bound (see HostMemoryDiagnosticsService).
       const hostDiagnostics = this.hostDiagnostics;
       if (hostDiagnostics) {
-         registry.registerCommand(this.command('dumpBackendState', 'Dump Backend State', category), {
-            execute: () => this.report('backend state', () => hostDiagnostics.dumpHostState({ label: new Date().toISOString() }), ['heap'])
-         });
-         registry.registerCommand(this.command('writeBackendHeapSnapshot', 'Write Heap Snapshot (Backend)', category), {
-            execute: () => this.writeSnapshot('backend', label => hostDiagnostics.writeHostHeapSnapshot({ label }))
-         });
+         registry.registerCommand(
+            this.command({
+               id: 'dumpBackendState',
+               label: nls.localize('hydranium/client-theia/command-dump-backend-state', 'Dump Backend State'),
+               category
+            }),
+            {
+               execute: () =>
+                  this.report('backend-state', () => hostDiagnostics.dumpHostState({ label: new Date().toISOString() }), ['heap'])
+            }
+         );
+         registry.registerCommand(
+            this.command({
+               id: 'writeBackendHeapSnapshot',
+               label: nls.localize('hydranium/client-theia/command-write-heap-snapshot-backend', 'Write Heap Snapshot (Backend)'),
+               category
+            }),
+            {
+               execute: () => this.writeSnapshot('backend', label => hostDiagnostics.writeHostHeapSnapshot({ label }))
+            }
+         );
       }
    }
 
-   protected command(id: string, label: string, category: string): Command {
-      return { id: `${this.options.commandIdPrefix}.${id}`, label, category };
+   /**
+    * Takes an object rather than positional arguments so that `label` — the one
+    * user-facing member — is addressable by name. A lint rule guarding the
+    * localization of labels has only syntax to work with, and a selector for an
+    * argument position would equally catch `id`, which must stay a bare literal.
+    */
+   protected command(spec: { id: string; label: string; category: string }): Command {
+      return { id: `${this.options.commandIdPrefix}.${spec.id}`, label: spec.label, category: spec.category };
+   }
+
+   /** The record window as whole seconds, for the label and the toast that must agree on it. */
+   protected recordDurationSeconds(): number {
+      return Math.round(this.recordDurationMs / 1000);
    }
 
    /** Run a snapshot call, append the full result to the channel, toast the first matching summary line. */
-   protected async report(what: string, produce: () => Promise<string>, summaryKeys: string[]): Promise<void> {
+   protected async report(subject: DiagnosticsSubject, produce: () => Promise<string>, summaryKeys: string[]): Promise<void> {
       try {
          const snapshot = await produce();
          this.channel().appendLine(snapshot);
          this.channel().appendLine('');
-         this.messageService.info(this.summarize(snapshot, what, summaryKeys), { timeout: 5000 });
+         this.messageService.info(this.summarize(snapshot, subject, summaryKeys), { timeout: 5000 });
       } catch (error) {
-         this.messageService.error(`Failed to dump ${what}: ${this.errorMessage(error)}`);
+         this.messageService.error(this.dumpFailedMessage(subject, this.errorMessage(error)));
       }
    }
 
-   protected async writeSnapshot(target: string, produce: (label: string) => Promise<string>): Promise<void> {
+   protected async writeSnapshot(target: HeapSnapshotTarget, produce: (label: string) => Promise<string>): Promise<void> {
       try {
-         this.messageService.info(`Writing ${target} heap snapshot — this briefly pauses that process...`, { timeout: 3000 });
+         this.messageService.info(this.writingSnapshotMessage(target), { timeout: 3000 });
          const filePath = await produce(new Date().toISOString());
-         this.channel().appendLine(`Heap snapshot (${target}) written to ${filePath}`);
-         this.messageService.info(`Heap snapshot (${target}) written to ${filePath}`, { timeout: 8000 });
+         // One sentence, shown in both places: two literals of equal value can be
+         // localized apart, leaving the channel and the toast naming different files.
+         const written = this.wroteSnapshotMessage(target, filePath);
+         this.channel().appendLine(written);
+         this.messageService.info(written, { timeout: 8000 });
       } catch (error) {
-         this.messageService.error(`Failed to write ${target} heap snapshot: ${this.errorMessage(error)}`);
+         this.messageService.error(this.writeSnapshotFailedMessage(target, this.errorMessage(error)));
       }
    }
 
@@ -166,7 +263,7 @@ export class MemoryDiagnosticsContribution implements CommandContribution {
       try {
          await this.diagnostics.startProfiling(this.profileDimensions);
       } catch (error) {
-         this.messageService.error(`Failed to start profiling: ${this.errorMessage(error)}`);
+         this.messageService.error(this.startProfilingFailedMessage(this.errorMessage(error)));
          return;
       }
       // No timeout: the capture runs as long as the user wants it to, and an
@@ -174,7 +271,7 @@ export class MemoryDiagnosticsContribution implements CommandContribution {
       // toast is what keeps the action live, so this resolves only once the
       // user acts on it or dismisses it.
       const chosen = await this.messageService.info(
-         'Server profiling started — sampling does not stop the process.',
+         nls.localize('hydranium/client-theia/profiling-started', 'Server profiling started — sampling does not stop the process.'),
          { timeout: 0 },
          this.stopProfilingLabel
       );
@@ -188,15 +285,27 @@ export class MemoryDiagnosticsContribution implements CommandContribution {
       return this.report('profile', () => this.diagnostics.stopProfiling({ label: new Date().toISOString() }), ['duration']);
    }
 
+   /** One authored sentence for both start paths; identical literals in two places drift apart under translation. */
+   protected startProfilingFailedMessage(detail: string): string {
+      return nls.localize('hydranium/client-theia/error-start-profiling', 'Failed to start profiling: {0}', detail);
+   }
+
    /** Capture a fixed-length window: start, wait, stop, and report the result. */
    protected async recordProfile(): Promise<void> {
       try {
          await this.diagnostics.startProfiling(this.profileDimensions);
       } catch (error) {
-         this.messageService.error(`Failed to start profiling: ${this.errorMessage(error)}`);
+         this.messageService.error(this.startProfilingFailedMessage(this.errorMessage(error)));
          return;
       }
-      this.messageService.info(`Recording a ${Math.round(this.recordDurationMs / 1000)}s server performance profile...`, { timeout: 4000 });
+      this.messageService.info(
+         nls.localize(
+            'hydranium/client-theia/recording-profile',
+            'Recording a {0}s server performance profile...',
+            this.recordDurationSeconds()
+         ),
+         { timeout: 4000 }
+      );
       await this.delay(this.recordDurationMs);
       await this.stopProfiling();
    }
@@ -219,15 +328,129 @@ export class MemoryDiagnosticsContribution implements CommandContribution {
    }
 
    /** Pull the first line starting with one of `keys` for a one-line toast; full text is in the channel. */
-   protected summarize(snapshot: string, what: string, keys: string[]): string {
+   protected summarize(snapshot: string, subject: DiagnosticsSubject, keys: string[]): string {
       const lines = snapshot.split('\n');
       for (const key of keys) {
          const line = lines.find(entry => entry.trim().startsWith(key));
          if (line) {
-            return `Captured ${what} —${line.replace(new RegExp(`^\\s*${key}\\s*`), ` ${key} `)}`;
+            return this.capturedDetailMessage(subject, line.replace(new RegExp(`^\\s*${key}\\s*`), ` ${key} `));
          }
       }
-      return `Captured ${what} (see the ${this.options.channelName} output channel)`;
+      return this.capturedChannelMessage(subject);
+   }
+
+   /**
+    * The captured-with-detail toast. The detail is a machine-formatted figure,
+    * so it is safe as a substitution parameter; the subject is not, hence one
+    * authored sentence per subject.
+    */
+   protected capturedDetailMessage(subject: DiagnosticsSubject, detail: string): string {
+      switch (subject) {
+         case 'server-state':
+            return nls.localize('hydranium/client-theia/captured-server-state-detail', 'Captured server state —{0}', detail);
+         case 'pod-memory':
+            return nls.localize('hydranium/client-theia/captured-pod-memory-detail', 'Captured pod memory —{0}', detail);
+         case 'latency':
+            return nls.localize('hydranium/client-theia/captured-latency-detail', 'Captured RPC/LSP latency —{0}', detail);
+         case 'backend-state':
+            return nls.localize('hydranium/client-theia/captured-backend-state-detail', 'Captured backend state —{0}', detail);
+         case 'profile':
+            return nls.localize('hydranium/client-theia/captured-profile-detail', 'Captured profile —{0}', detail);
+      }
+   }
+
+   /** The captured-without-detail toast; the channel name is adopter branding, not translatable text. */
+   protected capturedChannelMessage(subject: DiagnosticsSubject): string {
+      const channelName = this.options.channelName;
+      switch (subject) {
+         case 'server-state':
+            return nls.localize(
+               'hydranium/client-theia/captured-server-state-channel',
+               'Captured server state (see the {0} output channel)',
+               channelName
+            );
+         case 'pod-memory':
+            return nls.localize(
+               'hydranium/client-theia/captured-pod-memory-channel',
+               'Captured pod memory (see the {0} output channel)',
+               channelName
+            );
+         case 'latency':
+            return nls.localize(
+               'hydranium/client-theia/captured-latency-channel',
+               'Captured RPC/LSP latency (see the {0} output channel)',
+               channelName
+            );
+         case 'backend-state':
+            return nls.localize(
+               'hydranium/client-theia/captured-backend-state-channel',
+               'Captured backend state (see the {0} output channel)',
+               channelName
+            );
+         case 'profile':
+            return nls.localize(
+               'hydranium/client-theia/captured-profile-channel',
+               'Captured profile (see the {0} output channel)',
+               channelName
+            );
+      }
+   }
+
+   /** The failed-to-dump toast; the detail is a technical error string, safe as a parameter. */
+   protected dumpFailedMessage(subject: DiagnosticsSubject, detail: string): string {
+      switch (subject) {
+         case 'server-state':
+            return nls.localize('hydranium/client-theia/error-dump-server-state', 'Failed to dump server state: {0}', detail);
+         case 'pod-memory':
+            return nls.localize('hydranium/client-theia/error-dump-pod-memory', 'Failed to dump pod memory: {0}', detail);
+         case 'latency':
+            return nls.localize('hydranium/client-theia/error-dump-latency', 'Failed to dump RPC/LSP latency: {0}', detail);
+         case 'backend-state':
+            return nls.localize('hydranium/client-theia/error-dump-backend-state', 'Failed to dump backend state: {0}', detail);
+         case 'profile':
+            return nls.localize('hydranium/client-theia/error-dump-profile', 'Failed to dump profile: {0}', detail);
+      }
+   }
+
+   protected writingSnapshotMessage(target: HeapSnapshotTarget): string {
+      switch (target) {
+         case 'server':
+            return nls.localize(
+               'hydranium/client-theia/writing-heap-snapshot-server',
+               'Writing server heap snapshot — this briefly pauses that process...'
+            );
+         case 'backend':
+            return nls.localize(
+               'hydranium/client-theia/writing-heap-snapshot-backend',
+               'Writing backend heap snapshot — this briefly pauses that process...'
+            );
+      }
+   }
+
+   protected wroteSnapshotMessage(target: HeapSnapshotTarget, filePath: string): string {
+      switch (target) {
+         case 'server':
+            return nls.localize('hydranium/client-theia/wrote-heap-snapshot-server', 'Heap snapshot (server) written to {0}', filePath);
+         case 'backend':
+            return nls.localize('hydranium/client-theia/wrote-heap-snapshot-backend', 'Heap snapshot (backend) written to {0}', filePath);
+      }
+   }
+
+   protected writeSnapshotFailedMessage(target: HeapSnapshotTarget, detail: string): string {
+      switch (target) {
+         case 'server':
+            return nls.localize(
+               'hydranium/client-theia/error-write-heap-snapshot-server',
+               'Failed to write server heap snapshot: {0}',
+               detail
+            );
+         case 'backend':
+            return nls.localize(
+               'hydranium/client-theia/error-write-heap-snapshot-backend',
+               'Failed to write backend heap snapshot: {0}',
+               detail
+            );
+      }
    }
 
    protected errorMessage(error: unknown): string {