@hydranium/client-theia 1.0.0-next.9 → 1.0.0-next.90

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 {

package/src/browser/session-aware-connection-source.ts

@@ -0,0 +1,179 @@
+/********************************************************************************
+ * 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 { WebSocketConnectionSource } from '@theia/core/lib/browser/messaging/ws-connection-source';
+import { Disposable, DisposableCollection } from '@theia/core/lib/common/disposable';
+import { type Event } from '@theia/core/lib/common/event';
+import { type AbstractChannel, ForwardingChannel } from '@theia/core/lib/common/message-rpc/channel';
+import { Uint8ArrayReadBuffer, Uint8ArrayWriteBuffer } from '@theia/core/lib/common/message-rpc/uint8-array-message-buffer';
+import { ConnectionManagementMessages } from '@theia/core/lib/common/messaging/connection-management';
+import { injectable, type interfaces } from '@theia/core/shared/inversify';
+import { SocketWriteBuffer } from '@theia/core/lib/common/messaging/socket-write-buffer';
+import { type ConnectionResilienceOptions } from '../common/connection-resilience-options';
+import {
+   type ConnectionBufferOverflow,
+   createFramedSocketWriteBuffer,
+   FramedSocketWriteBuffer,
+   supportsConnectionResilience,
+   warnConnectionResilienceUnavailable
+} from '../common/framed-socket-write-buffer';
+
+/**
+ * Sends a message only once the server has confirmed the session, and only
+ * behind anything already queued.
+ *
+ * Theia sends straight away when `socket.connected` is true and buffers
+ * otherwise. The gap is that reconnecting sets that flag immediately, while the
+ * session is only confirmed a round trip later. A message produced in that
+ * window either jumps ahead of older messages still waiting in the buffer, or,
+ * if nothing was waiting, goes out on a socket whose channel the server has not
+ * attached yet and is discarded by a peer with no listener for it.
+ *
+ * Losing one or reordering them is equally unrecoverable for anything that
+ * applies messages by position. Theia's plugin host keeps a line-indexed copy of
+ * every open document, so a single late or missing edit leaves that copy wrong
+ * for good, and the next edit past its end fails.
+ *
+ * The server side needs no equivalent: it adopts its socket and flushes in one
+ * synchronous step, so it has no window of this kind.
+ */
+@injectable()
+export class SessionAwareConnectionSource extends WebSocketConnectionSource {
+   /**
+    * Whether the server has confirmed, on the socket in use right now, that it
+    * still holds this frontend's session. A connected socket is not enough:
+    * until the handshake is answered the server has not attached its channel to
+    * this socket, and a message sent meanwhile reaches a peer with no listener
+    * for it and is discarded without a trace.
+    */
+   protected sessionResumed = false;
+   protected sessionListenersAttached = false;
+
+   /**
+    * Every connect starts a socket the server has not confirmed yet, including
+    * the reconnects socket.io performs on its own. Resetting here rather than on
+    * disconnect also covers a connect that follows no clean disconnect event.
+    */
+   protected override handleSocketConnected(): void {
+      this.trackSessionState();
+      this.sessionResumed = false;
+      super.handleSocketConnected();
+   }
+
+   /**
+    * Watches the connection handshake for its outcome.
+    *
+    * Attached once, to the socket socket.io reuses across reconnects, and before
+    * the base class adds its own per-negotiation listeners — so this has already
+    * recorded the outcome by the time the base class reacts to it by flushing.
+    */
+   protected trackSessionState(): void {
+      if (this.sessionListenersAttached) {
+         return;
+      }
+      this.sessionListenersAttached = true;
+      this.socket.on(ConnectionManagementMessages.INITIAL_CONNECT, () => {
+         this.sessionResumed = true;
+      });
+      this.socket.on(ConnectionManagementMessages.RECONNECT, (hasConnection: boolean) => {
+         this.sessionResumed = hasConnection;
+      });
+   }
+
+   /** Whether a message may go out now, as opposed to waiting in the buffer. */
+   protected get canSend(): boolean {
+      return this.socket.connected && this.sessionResumed;
+   }
+
+   /**
+    * Copied from Theia apart from the `onCommit` body, because the base builds that callback inline
+    * and exposes no narrower seam. Re-diff when the supported range moves.
+    */
+   protected override createChannel(): AbstractChannel {
+      const toDispose = new DisposableCollection();
+      const messageHandler = (data: ArrayBuffer | Uint8Array): void => {
+         this.onIncomingMessageActivityEmitter.fire();
+         if (this.currentChannel) {
+            // socket.io hands binary over as ArrayBuffer in the browser.
+            const buffer = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+            this.currentChannel.onMessageEmitter.fire(() => new Uint8ArrayReadBuffer(buffer));
+         }
+      };
+      this.socket.on('message', messageHandler);
+      toDispose.push(Disposable.create(() => this.socket.off('message', messageHandler)));
+
+      return new ForwardingChannel(
+         'any',
+         () => toDispose.dispose(),
+         () => {
+            const result = new Uint8ArrayWriteBuffer();
+            // Says only whether the session can carry a message; the buffer decides whether it may
+            // go ahead of anything already waiting.
+            result.onCommit(buffer => this.framedBuffer.sendOrQueue(this.canSend ? this.socket : undefined, buffer));
+            return result;
+         }
+      );
+   }
+
+   /** Fires when the buffer runs out of room, so an adopter can say so rather than just stopping. */
+   get onBufferOverflow(): Event<ConnectionBufferOverflow> {
+      return this.framedBuffer.onOverflow;
+   }
+
+   /**
+    * The write buffer Theia injected into the base class.
+    *
+    * Reached through a structural view rather than as `this.writeBuffer`,
+    * because that member is `private` in Theia 1.70 and only became `protected`
+    * in 1.71 — and this package compiles against the whole range. The view
+    * asserts nothing the versions disagree about: the field is there in both,
+    * holding whatever `SocketWriteBuffer` is bound, and the check below is what
+    * establishes it is ours.
+    */
+   protected get framedBuffer(): FramedSocketWriteBuffer {
+      const buffer = (this as unknown as { readonly writeBuffer: SocketWriteBuffer }).writeBuffer;
+      if (!(buffer instanceof FramedSocketWriteBuffer)) {
+         throw new Error('SessionAwareConnectionSource requires FramedSocketWriteBuffer to be bound');
+      }
+      return buffer;
+   }
+}
+
+/**
+ * Replaces the frontend pieces that decide how outgoing messages survive a
+ * reconnect. Every one of them rebinds something Theia's
+ * `messagingFrontendModule` already bound, so this belongs in a module loaded
+ * into the same container.
+ *
+ * It must be a `frontendPreload` module rather than a normal frontend module:
+ * Theia's preloader resolves `WebSocketConnectionSource` (and with it the write
+ * buffer) while loading i18n and OS settings, which happens before any frontend
+ * module is loaded. A rebind there would come too late — the instances would
+ * already exist. All `frontendPreload` modules, by contrast, are loaded before
+ * the preloader constructs anything.
+ *
+ * Does nothing but warn on a Theia too old to expose the buffer binding, so the
+ * package keeps one supported range rather than splitting its floor for this
+ * feature. Returns whether the hardening was installed, for an adopter that
+ * wants to branch on it.
+ */
+export function bindConnectionResilience(
+   isBound: interfaces.IsBound,
+   rebind: interfaces.Rebind,
+   options: ConnectionResilienceOptions = {}
+): boolean {
+   if (!supportsConnectionResilience(isBound)) {
+      warnConnectionResilienceUnavailable('frontend');
+      return false;
+   }
+   // Scopes are kept as Theia declares them: one buffer per connection source, one shared socket owner.
+   rebind(SocketWriteBuffer).toDynamicValue(() => createFramedSocketWriteBuffer(options.bufferBytes));
+   rebind(WebSocketConnectionSource).to(SessionAwareConnectionSource).inSingletonScope();
+   return true;
+}

package/src/common/connection-resilience-options.ts

@@ -0,0 +1,24 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Options for the `bindConnectionResilience` helper each tier exports.
+ *
+ * Lives in `common` rather than beside either helper so the server entry can
+ * name the type without importing the browser module, and the other way round.
+ */
+export interface ConnectionResilienceOptions {
+   /**
+    * Size of the buffer holding messages while the socket is down, in bytes.
+    * Defaults to Theia's own limit. It decides how long an outage can last
+    * before changes start being rejected, so a deployment on a poor network
+    * trades memory for tolerance here.
+    */
+   readonly bufferBytes?: number;
+}