@hydranium/client-theia 1.0.0-next.22 → 1.0.0-next.220

package/lib/node/socket-channel-forwarder.js

@@ -0,0 +1,95 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocketChannelForwarder = void 0;
+const protocol_1 = require("@hydranium/protocol");
+const core_1 = require("@theia/core");
+const node_1 = require("vscode-jsonrpc/node");
+/**
+ * Relays JSON-RPC messages between a Theia browser-frontend {@link Channel} and
+ * a server's TCP socket — the backend half of a head's transport. The server
+ * speaks vscode-jsonrpc (Content-Length framed) on the socket; the frontend
+ * speaks the same protocol over the channel. This forwarder decodes each side
+ * and re-emits on the other.
+ *
+ * Behaves as `@eclipse-glsp/theia-integration`'s `SocketConnectionForwarder`
+ * does, and both heads use it, except that when the channel closes, the writes
+ * still queued go out before the socket ends. A page going away sends its last
+ * messages and closes its channel in the same tick, and the writer takes
+ * several turns per message, so destroying the socket on the close loses them.
+ */
+class SocketChannelForwarder {
+    channel;
+    socket;
+    clock;
+    toDispose = new core_1.DisposableCollection();
+    /** The last write to the socket; the writer runs its writes one at a time, so this settles last. */
+    lastWrite = Promise.resolve();
+    /**
+     * How long {@link endSocket} waits for the queued writes before it destroys
+     * the socket anyway. Without a bound, a server that stops reading holds the
+     * socket open for good, and with it the server's end of the connection.
+     */
+    flushTimeoutMs = 10_000;
+    constructor(channel, socket, 
+    /** Times {@link flushTimeoutMs}. */
+    clock = new protocol_1.SystemClock()) {
+        this.channel = channel;
+        this.socket = socket;
+        this.clock = clock;
+        const reader = new node_1.SocketMessageReader(socket);
+        const writer = new node_1.SocketMessageWriter(socket);
+        // Never listens, so it handles no message and has nothing to log.
+        // ast-grep-ignore: connection-without-logger
+        const connection = (0, node_1.createMessageConnection)(reader, writer);
+        // Nothing here destroys the socket directly. `SocketMessageWriter.dispose()`
+        // destroys it itself, which covers both `dispose` and `endSocket`; and
+        // `connection.onClose` fires only from the reader's or writer's own close,
+        // which for a socket means the socket has already gone — so a destroy
+        // handler there is downstream of the effect it would be trying to cause.
+        this.toDispose.pushAll([
+            reader.listen(message => this.writeToChannel(message)),
+            channel.onMessage(provider => {
+                // A failed write means the socket is gone, which its own close reports.
+                this.lastWrite = writer.write(this.decodeChannelMessage(provider)).catch(() => undefined);
+            }),
+            channel.onClose(() => void this.endSocket(connection)),
+            connection.onClose(() => channel.close()),
+            core_1.Disposable.create(() => {
+                channel.close();
+                connection.dispose();
+            })
+        ]);
+    }
+    /**
+     * Dispose `connection`, which destroys the socket, once the writes queued
+     * before the channel closed are out, or {@link flushTimeoutMs} has passed. A
+     * write has settled once the socket handed its bytes to the OS, and
+     * destroying the socket then loses nothing.
+     */
+    async endSocket(connection) {
+        await this.clock.raceTimer(this.lastWrite, this.flushTimeoutMs);
+        connection.dispose();
+    }
+    decodeChannelMessage(provider) {
+        const buffer = provider().readBytes();
+        return JSON.parse(new TextDecoder().decode(buffer));
+    }
+    writeToChannel(message) {
+        const writeBuffer = this.channel.getWriteBuffer();
+        writeBuffer.writeBytes(new TextEncoder().encode(JSON.stringify(message)));
+        writeBuffer.commit();
+    }
+    dispose() {
+        this.toDispose.dispose();
+    }
+}
+exports.SocketChannelForwarder = SocketChannelForwarder;
+//# sourceMappingURL=socket-channel-forwarder.js.map

package/lib/node/socket-channel-forwarder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-channel-forwarder.js","sourceRoot":"","sources":["../../src/node/socket-channel-forwarder.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF,kDAA8D;AAC9D,sCAAmG;AAEnG,8CAM6B;AAE7B;;;;;;;;;;;;GAYG;AACH;IAYyB,OAAO;IACP,MAAM;IAEN,KAAK;IAdR,SAAS,GAAG,IAAI,2BAAoB,EAAE,CAAC;IAC1D,oGAAoG;IAC1F,SAAS,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IACvD;;;;OAIG;IACgB,cAAc,GAAW,MAAM,CAAC;IAEnD,YACsB,OAAgB,EAChB,MAAkB;IACrC,oCAAoC;IACjB,KAAK,GAAU,IAAI,sBAAW,EAAE;uBAHhC,OAAO;sBACP,MAAM;qBAEN,KAAK;QAExB,MAAM,MAAM,GAAG,IAAI,0BAAmB,CAAC,MAAM,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,IAAI,0BAAmB,CAAC,MAAM,CAAC,CAAC;QAC/C,kEAAkE;QAClE,6CAA6C;QAC7C,MAAM,UAAU,GAAG,IAAA,8BAAuB,EAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC3D,6EAA6E;QAC7E,uEAAuE;QACvE,2EAA2E;QAC3E,sEAAsE;QACtE,yEAAyE;QACzE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;YACtD,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE;gBAC1B,wEAAwE;gBACxE,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAC7F,CAAC,CAAC;YACF,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;YACtD,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACzC,iBAAU,CAAC,MAAM,CAAC,GAAG,EAAE;gBACpB,OAAO,CAAC,KAAK,EAAE,CAAC;gBAChB,UAAU,CAAC,OAAO,EAAE,CAAC;YACxB,CAAC,CAAC;SACJ,CAAC,CAAC;IACN,CAAC;IAED;;;;;OAKG;IACO,KAAK,CAAC,SAAS,CAAC,UAA6B;QACpD,MAAM,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;QAChE,UAAU,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;IAES,oBAAoB,CAAC,QAAyB;QACrD,MAAM,MAAM,GAAG,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAY,CAAC;IAClE,CAAC;IAES,cAAc,CAAC,OAAgB;QACtC,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;QAClD,WAAW,CAAC,UAAU,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAC1E,WAAW,CAAC,MAAM,EAAE,CAAC;IACxB,CAAC;IAED,OAAO;QACJ,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;CACH"}

package/lib/testing/stub-inversify-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"stub-inversify-context.js","sourceRoot":"","sources":["../../src/testing/stub-inversify-context.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;AAQlF,4DAgBC;AApBD;;;2CAG2C;AAC3C,SAAgB,wBAAwB,CAAC,eAAwB;IAC9D,MAAM,aAAa,GAChB,eAAe,KAAK,SAAS;QAC1B,CAAC,CAAC,IAAI;QACN,CAAC,CAAC;YACG,QAAQ,EAAE;gBACP;oBACG,kBAAkB,EAAE,eAAe,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE;iBAC7E;aACH;SACH,CAAC;IACV,OAAO;QACJ,cAAc,EAAE;YACb,aAAa;SACf;KAC8B,CAAC;AACtC,CAAC"}
+{"version":3,"file":"stub-inversify-context.js","sourceRoot":"","sources":["../../src/testing/stub-inversify-context.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAIlF;;;2CAG2C;AAC3C,kCAAyC,eAAwB;IAC9D,MAAM,aAAa,GAChB,eAAe,KAAK,SAAS;QAC1B,CAAC,CAAC,IAAI;QACN,CAAC,CAAC;YACG,QAAQ,EAAE;gBACP;oBACG,kBAAkB,EAAE,eAAe,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE;iBAC7E;aACH;SACH,CAAC;IACV,OAAO;QACJ,cAAc,EAAE;YACb,aAAa;SACf;KAC8B,CAAC;AACtC,CAAC"}

package/lib/testing/stub-output-channel.js.map

@@ -1 +1 @@
-{"version":3,"file":"stub-output-channel.js","sourceRoot":"","sources":["../../src/testing/stub-output-channel.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;AAmBlF,oEAoBC;AApBD,SAAgB,4BAA4B;IACzC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA6B,CAAC;IACtD,OAAO;QACJ,QAAQ;QACR,UAAU,CAAC,IAAY;YACpB,IAAI,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACjC,IAAI,CAAC,OAAO,EAAE,CAAC;gBACZ,MAAM,KAAK,GAAa,EAAE,CAAC;gBAC3B,OAAO,GAAG;oBACP,IAAI;oBACJ,KAAK;oBACL,UAAU,CAAC,IAAY;wBACpB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACpB,CAAC;iBACH,CAAC;gBACF,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAC/B,CAAC;YACD,OAAO,OAAO,CAAC;QAClB,CAAC;KACH,CAAC;AACL,CAAC"}
+{"version":3,"file":"stub-output-channel.js","sourceRoot":"","sources":["../../src/testing/stub-output-channel.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAmBlF;IACG,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA6B,CAAC;IACtD,OAAO;QACJ,QAAQ;QACR,UAAU,CAAC,IAAY;YACpB,IAAI,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACjC,IAAI,CAAC,OAAO,EAAE,CAAC;gBACZ,MAAM,KAAK,GAAa,EAAE,CAAC;gBAC3B,OAAO,GAAG;oBACP,IAAI;oBACJ,KAAK;oBACL,UAAU,CAAC,IAAY;wBACpB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACpB,CAAC;iBACH,CAAC;gBACF,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAC/B,CAAC;YACD,OAAO,OAAO,CAAC;QAClB,CAAC;KACH,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/client-theia",
-  "version": "1.0.0-next.22",
+  "version": "1.0.0-next.220",
   "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",
@@ -13,16 +13,23 @@
   "bugs": {
     "url": "https://github.com/eclipse-emfcloud/hydranium/issues"
   },
+  "license": "MIT",
+  "author": {
+    "name": "Hydranium Team"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/eclipse-emfcloud/hydranium.git",
     "directory": "packages/client-theia"
   },
-  "license": "MIT",
-  "author": {
-    "name": "Hydranium Team"
-  },
+  "files": [
+    "lib",
+    "src",
+    "!lib/**/*.tsbuildinfo"
+  ],
   "sideEffects": false,
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
@@ -32,64 +39,56 @@
       "types": "./lib/browser/index.d.ts",
       "default": "./lib/browser/index.js"
     },
-    "./lib/browser": {
-      "types": "./lib/browser/index.d.ts",
-      "default": "./lib/browser/index.js"
+    "./common": {
+      "types": "./lib/common/index.d.ts",
+      "default": "./lib/common/index.js"
     },
     "./node": {
       "types": "./lib/node/index.d.ts",
       "default": "./lib/node/index.js"
     },
-    "./lib/node": {
-      "types": "./lib/node/index.d.ts",
-      "default": "./lib/node/index.js"
-    },
     "./testing": {
       "types": "./lib/testing/index.d.ts",
       "default": "./lib/testing/index.js"
-    },
-    "./lib/testing": {
-      "types": "./lib/testing/index.d.ts",
-      "default": "./lib/testing/index.js"
     }
   },
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
-  "files": [
-    "lib",
-    "src",
-    "!lib/**/*.tsbuildinfo"
-  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc -b",
     "clean": "rimraf lib tsconfig.tsbuildinfo",
-    "lint": "eslint src test --max-warnings 0",
+    "lint": "oxlint --format stylish --config ../../oxlint.config.cjs src test --max-warnings 0",
     "prepack": "node -e \"const m=require('./package.json'),fs=require('node:fs');const missing=[m.main,...Object.values(m.bin||{})].filter(entry=>entry&&!fs.existsSync(entry));if(missing.length){console.error('prepack '+m.name+': not built ('+missing.join(', ')+' missing). Run the build before packing: a files entry that matches nothing is skipped silently, so the tarball would ship src only.');process.exit(1);}\"",
     "test": "npm run typecheck:test && vitest run",
     "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
     "watch": "tsc -b -w --preserveWatchOutput"
   },
   "devDependencies": {
-    "@hydranium/protocol": "1.0.0-next.22",
+    "@hydranium/protocol": "1.0.0-next.220",
     "@theia/core": "^1.70.0",
+    "@theia/editor": "^1.70.0",
+    "@theia/filesystem": "^1.70.0",
     "@theia/output": "^1.70.0",
     "@types/node": "^22.0.0",
     "inversify": "6.2.2",
     "reflect-metadata": "0.2.2",
     "rimraf": "^5.0.0",
-    "typescript": "^5.8.0"
+    "typescript": "^7.0.2",
+    "vscode-jsonrpc": "9.0.0"
   },
   "peerDependencies": {
-    "@hydranium/protocol": "1.0.0-next.22",
+    "@hydranium/protocol": "1.0.0-next.220",
     "@theia/core": "^1.70.0",
+    "@theia/editor": "^1.70.0",
+    "@theia/filesystem": "^1.70.0",
     "@theia/output": "^1.70.0",
-    "inversify": "^6.0.0"
+    "inversify": "^6.0.0",
+    "vscode-jsonrpc": "^9.0.0"
   },
   "engines": {
     "node": ">=22.13"
   },
-  "publishConfig": {
-    "access": "public"
-  },
-  "//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."
+  "//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. `vscode-jsonrpc` takes a caret: each `vscode-languageserver-protocol` release pins its transport exactly, so an exact peer would name a copy a fresh install rarely holds, while the caret still excludes the 8.x line.",
+  "//prepack": "The publish guard, a `prepack` rather than a `prepare`: `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. 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/channel-logger.ts

@@ -10,6 +10,7 @@
 import { AbstractLogger, DefaultTracer, type LogLevel, type MemoryReader, SystemClock } from '@hydranium/protocol';
 import { injectable, type interfaces, unmanaged, inject } from '@theia/core/shared/inversify';
 import { type OutputChannel, OutputChannelManager } from '@theia/output/lib/browser/output-channel';
+import { Clock } from '../common/clock';
 
 /**
  * Configuration for a {@link ChannelLogger}, supplied once at bind time via
@@ -65,10 +66,8 @@ export class ChannelLogger extends AbstractLogger {
    }
 
    protected emit(_level: LogLevel, label: string, message: string, args: readonly unknown[]): void {
-      const componentSegment = this.component ? ` [${this.component}]` : '';
       const formattedArgs = args.length > 0 ? ' ' + args.map(stringifyArg).join(' ') : '';
-      // Pad to match the server's 5-char label width so timestamps align across sources.
-      this.channel.appendLine(`[${label.padEnd(5)} - ${this.timestamp()}]${componentSegment} ${message}${formattedArgs}`);
+      this.channel.appendLine(`${this.formatLinePrefix(label)} ${message}${formattedArgs}`);
    }
 
    /**
@@ -94,9 +93,10 @@ const ChannelLoggerBase = Symbol('ChannelLoggerBase');
 
 /**
  * Inversify token for the browser `Tracer` — a {@link DefaultTracer} over
- * the {@link ChannelLogger} (emit sink) + a {@link SystemClock} + a browser
- * heap reader. The browser head has no Langium `services.Tracer` slot, so this
- * is how frontend services that time obtain a tracer: `@inject(ChannelTracer)`.
+ * the {@link ChannelLogger} (emit sink) + the container's {@link Clock}, or a
+ * `SystemClock` when it binds none, + a browser heap reader. The browser head
+ * has no Langium `services.Tracer` slot, so this is how frontend services that
+ * time obtain a tracer: `@inject(ChannelTracer)`.
  * Bound by {@link bindChannelLogger}.
  */
 export const ChannelTracer = Symbol('ChannelTracer');
@@ -134,7 +134,10 @@ export function bindChannelLogger(bind: interfaces.Bind, options: ChannelLoggerO
       return parentName ? base.for(parentName) : base;
    });
    bind(ChannelTracer)
-      .toDynamicValue(ctx => new DefaultTracer(ctx.container.get<ChannelLogger>(ChannelLoggerBase), new SystemClock(), readBrowserMemory))
+      .toDynamicValue(ctx => {
+         const clock = ctx.container.isBound(Clock) ? ctx.container.get<Clock>(Clock) : new SystemClock();
+         return new DefaultTracer(ctx.container.get<ChannelLogger>(ChannelLoggerBase), clock, readBrowserMemory);
+      })
       .inSingletonScope();
 }
 

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/connection-reporter.ts

@@ -0,0 +1,121 @@
+/********************************************************************************
+ * 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, type Progress } from '@theia/core';
+import { inject, injectable, type interfaces } from '@theia/core/shared/inversify';
+
+/** What a head connects to, as the whole sentences reported about it. */
+export interface ConnectionTarget {
+   readonly connectingMessage: string;
+   readonly connectedMessage: string;
+}
+
+/** One connection attempt; it reports exactly one end. */
+export interface ConnectionAttempt {
+   connected(): void;
+   /** Ends the attempt with nothing to report, as when its head is disposed
+    *  or a newer attempt takes over. */
+   cancelled(): void;
+   /**
+    * `message` is the whole sentence to report. `retry`, when given, starts a
+    * fresh attempt at once; a head without one keeps retrying on its own.
+    */
+   failed(message: string, retry?: () => void): void;
+}
+
+/**
+ * How a head's connection attempts reach the user. A head calls
+ * {@link connecting} for every attempt, a reconnect included, and keeps the
+ * attempt's retries and bounds itself; this decides only what is shown. Rebind
+ * the slot to show nothing, or something other than notifications.
+ */
+export interface ConnectionReporter {
+   connecting(target: ConnectionTarget): ConnectionAttempt;
+}
+export const ConnectionReporter = Symbol('ConnectionReporter');
+
+/**
+ * Reports through Theia notifications: an attempt still running after
+ * {@link connectingNoticeDelayMs} shows its progress, and an attempt ends in at
+ * most one notification. A failure is shown once per target until it connects
+ * again, so a head that keeps retrying does not raise one per attempt.
+ */
+@injectable()
+export class DefaultConnectionReporter implements ConnectionReporter {
+   @inject(MessageService) protected readonly messageService!: MessageService;
+
+   protected readonly connectingNoticeDelayMs: number = 3_000;
+   /** Targets whose last reported attempt failed. */
+   protected readonly failing = new Set<ConnectionTarget>();
+
+   connecting(target: ConnectionTarget): ConnectionAttempt {
+      let progress: Promise<Progress> | undefined;
+      const notice = this.failing.has(target)
+         ? undefined
+         : setTimeout(() => (progress = this.showConnecting(target)), this.connectingNoticeDelayMs);
+      let settled = false;
+      const settle = (): boolean => {
+         if (settled) {
+            return false;
+         }
+         settled = true;
+         clearTimeout(notice);
+         void progress?.then(shown => shown.cancel());
+         return true;
+      };
+      return {
+         connected: () => {
+            if (settle() && (this.failing.delete(target) || progress)) {
+               this.showConnected(target);
+            }
+         },
+         cancelled: () => {
+            settle();
+         },
+         failed: (message, retry) => {
+            if (settle() && !this.failing.has(target)) {
+               this.failing.add(target);
+               void this.showFailed(target, message, retry);
+            }
+         }
+      };
+   }
+
+   protected showConnecting(target: ConnectionTarget): Promise<Progress> {
+      return this.messageService.showProgress({ text: target.connectingMessage });
+   }
+
+   protected showConnected(target: ConnectionTarget): void {
+      this.messageService.info(target.connectedMessage);
+   }
+
+   protected async showFailed(target: ConnectionTarget, message: string, retry?: () => void): Promise<void> {
+      if (!retry) {
+         this.messageService.error(message);
+         return;
+      }
+      const label = this.retryLabel();
+      if ((await this.messageService.error(message, label)) === label) {
+         // The retried attempt reports afresh, progress included.
+         this.failing.delete(target);
+         retry();
+      }
+   }
+
+   protected retryLabel(): string {
+      return nls.localize('hydranium/client-theia/connection-retry', 'Retry');
+   }
+}
+
+/** Bind {@link DefaultConnectionReporter} unless the slot is bound already; every head calls this. */
+export function bindConnectionReporter(bind: interfaces.Bind, isBound: interfaces.IsBound): void {
+   if (!isBound(ConnectionReporter)) {
+      bind(ConnectionReporter).to(DefaultConnectionReporter).inSingletonScope();
+   }
+}