@hydranium/client-theia 1.0.0-next.50 → 1.0.0-next.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/client-theia",
-  "version": "1.0.0-next.50",
+  "version": "1.0.0-next.52",
   "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,7 +78,7 @@
     "watch": "tsc -b -w --preserveWatchOutput"
   },
   "devDependencies": {
-    "@hydranium/protocol": "1.0.0-next.50",
+    "@hydranium/protocol": "1.0.0-next.52",
     "@theia/core": "^1.70.0",
     "@theia/output": "^1.70.0",
     "@types/node": "^22.0.0",
@@ -80,7 +88,7 @@
     "typescript": "^5.8.0"
   },
   "peerDependencies": {
-    "@hydranium/protocol": "1.0.0-next.50",
+    "@hydranium/protocol": "1.0.0-next.52",
     "@theia/core": "^1.70.0",
     "@theia/output": "^1.70.0",
     "inversify": "^6.0.0"
@@ -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/session-aware-connection-source.ts

@@ -0,0 +1,175 @@
+/********************************************************************************
+ * 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;
+   }
+
+   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;
+}

package/src/common/framed-socket-write-buffer.ts

@@ -0,0 +1,212 @@
+/********************************************************************************
+ * 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 { Emitter, type Event } from '@theia/core/lib/common/event';
+import { SocketWriteBuffer } from '@theia/core/lib/common/messaging/socket-write-buffer';
+
+/**
+ * Prefix on every connection log line, deliberately shared by the browser and the
+ * server so one pattern greps a console and a pod log at once.
+ */
+export const CONNECTION_LOG_PREFIX = '[connection]';
+
+/**
+ * The part of a socket this buffer uses. Narrower than the socket type Theia
+ * declares, which keeps the dependency honest and lets the class be tested
+ * without a connection.
+ */
+export interface MessageSink {
+   send(data: Uint8Array): void;
+}
+
+/**
+ * Reported when the buffer runs out of room. The message that did not fit is
+ * rejected, and so is every further one for as long as the buffer stays full.
+ * Reconnecting drains it and sending resumes, but whatever was rejected
+ * meanwhile is gone, so the two sides no longer agree about the session.
+ */
+export interface ConnectionBufferOverflow {
+   /** Messages held when the limit was reached. */
+   readonly messages: number;
+   /** Bytes held when the limit was reached. */
+   readonly bytes: number;
+   /** The limit in force, so a reader can tell what to raise it to. */
+   readonly maxBytes: number;
+}
+
+/**
+ * Holds messages while the peer is away and re-sends them when it returns.
+ *
+ * Theia copies them into one growing byte array and flushes that with a single
+ * `send`. A websocket delivers whole messages rather than a byte stream, so
+ * Theia's encoding adds no length prefix and every reader assumes one delivery
+ * is one message. The concatenated flush breaks that assumption: the reader
+ * decodes the first message and throws away the bytes behind it.
+ *
+ * Changed here: one entry per message, sent one at a time, so each arrives as
+ * its own delivery. The buffer also decides whether a message may go out
+ * directly — see {@link sendOrQueue} — because a caller that decides for itself
+ * is how messages end up overtaking a backlog.
+ *
+ * Unchanged from Theia: exceeding the limit rejects the message rather than
+ * dropping something silently. The limit is settable, since the right value
+ * depends on how long an outage has to survive.
+ *
+ * Logging goes to `console` rather than through a `Logger`. On the browser side
+ * Theia's preloader builds this before any Output channel exists, so there is
+ * nothing else to write to; the {@link CONNECTION_LOG_PREFIX} keeps the lines
+ * findable on both sides.
+ */
+export class FramedSocketWriteBuffer extends SocketWriteBuffer {
+   /** Theia's fixed limit, kept as the default. */
+   static readonly DEFAULT_MAX_BYTES = 100 * 1024;
+
+   /**
+    * Settable so a deployment can trade memory for longer outages.
+    *
+    * Consulted directly rather than through the base class's `maxBufferSize`,
+    * which does not exist before Theia 1.71 — an `override` of it would not
+    * compile against the oldest release this package supports. Nothing is lost:
+    * `buffer`, `flush` and `drain` are all replaced here, so the base's own
+    * limit is never reached.
+    */
+   maxBytes = FramedSocketWriteBuffer.DEFAULT_MAX_BYTES;
+
+   protected pending: Uint8Array[] = [];
+   protected pendingBytes = 0;
+   protected overflowReported = false;
+   protected readonly onOverflowEmitter = new Emitter<ConnectionBufferOverflow>();
+
+   /** Fires once per outage when the limit is reached. */
+   get onOverflow(): Event<ConnectionBufferOverflow> {
+      return this.onOverflowEmitter.event;
+   }
+
+   /**
+    * Sends `data` now only if nothing is waiting, and queues it otherwise.
+    *
+    * Callers say whether the peer is ready for a message; the buffer decides
+    * whether it may go ahead of one already waiting. Splitting it this way is
+    * the point: a caller that answers both questions from one flag is how a
+    * fresh message ends up overtaking a backlog.
+    */
+   sendOrQueue(socket: MessageSink | undefined, data: Uint8Array): void {
+      if (socket && !this.hasBacklog) {
+         socket.send(data);
+      } else {
+         this.buffer(data);
+      }
+   }
+
+   override buffer(data: Uint8Array): void {
+      if (this.pendingBytes + data.byteLength > this.maxBytes) {
+         this.reportOverflow();
+         throw new Error(`Max disconnected buffer size exceeded by adding ${data.byteLength} bytes`);
+      }
+      // Copied for the same reason the base class copies: the caller owns `data`.
+      this.pending.push(data.slice());
+      this.pendingBytes += data.byteLength;
+      if (this.pending.length === 1) {
+         console.info(`${CONNECTION_LOG_PREFIX} buffering messages, the peer is disconnected`);
+      }
+   }
+
+   override flush(socket: MessageSink): void {
+      if (this.pending.length === 0) {
+         return;
+      }
+      const count = this.pending.length;
+      const bytes = this.pendingBytes;
+      // Drained one by one rather than snapshot-then-send, so `hasBacklog` stays true until the last
+      // message is out and anything produced meanwhile still queues behind it. Each message is
+      // removed only once it has been sent, so a throwing send leaves the backlog intact and in
+      // order rather than swallowing the message it failed on.
+      while (this.pending.length > 0) {
+         const message = this.pending[0];
+         socket.send(message);
+         this.pending.shift();
+         this.pendingBytes -= message.byteLength;
+      }
+      this.overflowReported = false;
+      console.info(`${CONNECTION_LOG_PREFIX} sent ${count} buffered message(s), ${bytes} bytes`);
+   }
+
+   override drain(): void {
+      if (this.pending.length > 0) {
+         console.warn(`${CONNECTION_LOG_PREFIX} discarded ${this.pending.length} buffered message(s), ${this.pendingBytes} bytes`);
+      }
+      this.reset();
+   }
+
+   /** Whether messages are still waiting to go out. */
+   get hasBacklog(): boolean {
+      return this.pending.length > 0;
+   }
+
+   protected reportOverflow(): void {
+      if (this.overflowReported) {
+         return;
+      }
+      this.overflowReported = true;
+      const overflow: ConnectionBufferOverflow = { messages: this.pending.length, bytes: this.pendingBytes, maxBytes: this.maxBytes };
+      console.error(
+         `${CONNECTION_LOG_PREFIX} buffer full at ${overflow.maxBytes} bytes after ${overflow.messages} message(s); ` +
+            'this message is rejected, and so is every further one until the peer returns'
+      );
+      this.onOverflowEmitter.fire(overflow);
+   }
+
+   protected reset(): void {
+      this.pending = [];
+      this.pendingBytes = 0;
+      this.overflowReported = false;
+   }
+}
+
+/** Named in the warning a skipped install emits, so the reader is told what to upgrade to. */
+export const REQUIRED_THEIA_HINT = '@theia/core 1.71 or newer';
+
+/**
+ * Whether this Theia exposes the seam the reconnect hardening replaces.
+ *
+ * Theia only began binding {@link SocketWriteBuffer} in 1.71; before that each
+ * connection built one privately, so there is no binding to rebind and no way
+ * in. Every other API involved has been there throughout, which makes this one
+ * probe the whole compatibility question — and it is a binding check rather
+ * than a version parse, so it answers about the container actually in front of
+ * us instead of a number that may have been overridden or vendored.
+ *
+ * Callers that get `false` must leave Theia's own wiring alone: rebinding half
+ * of it would be worse than not rebinding at all.
+ */
+export function supportsConnectionResilience(isBound: (identifier: typeof SocketWriteBuffer) => boolean): boolean {
+   return isBound(SocketWriteBuffer);
+}
+
+/**
+ * The warning a skipped install emits. Says what is lost rather than only what
+ * is missing: the failures this guards against are silent, so an adopter who
+ * never sees this line has no other way to learn the guard is absent.
+ */
+export function warnConnectionResilienceUnavailable(tier: 'frontend' | 'backend'): void {
+   console.warn(
+      `${CONNECTION_LOG_PREFIX} ${tier} reconnect hardening NOT installed: this Theia does not expose an injectable ` +
+         `socket write buffer (needs ${REQUIRED_THEIA_HINT}). Theia's own behaviour is left in place, which can lose or ` +
+         'reorder messages when a socket drops and reconnects.'
+   );
+}
+
+/** Builds a buffer with the given limit, or Theia's default when none is configured. */
+export function createFramedSocketWriteBuffer(maxBytes?: number): FramedSocketWriteBuffer {
+   const buffer = new FramedSocketWriteBuffer();
+   if (typeof maxBytes === 'number' && maxBytes > 0) {
+      buffer.maxBytes = maxBytes;
+   }
+   return buffer;
+}

package/src/common/index.ts

@@ -0,0 +1,14 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Environment-neutral connection primitives, shared by the browser connection
+// source and the server connection service. Kept out of both tier barrels
+// because each side binds the same buffer for its own half of the socket.
+export * from './framed-socket-write-buffer';
+export * from './connection-resilience-options';

package/src/node/index.ts

@@ -8,3 +8,4 @@
  ********************************************************************************/
 
 export * from './abstract-socket-forwarding-connection-handler';
+export * from './session-bound-frontend-connection-service';