@hydranium/data-client-theia 1.0.0-next.28 → 1.0.0-next.281

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/data-client-theia",
-  "version": "1.0.0-next.28",
+  "version": "1.0.0-next.281",
   "description": "Theia-coupled client primitives for the hydranium data-server protocol head; companion of @hydranium/data-server. Bridges framework typed errors (e.g. ConflictError) across Theia's RPC boundary so their code + data survive the wire.",
   "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/data-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",
@@ -39,64 +46,43 @@
     "./node": {
       "types": "./lib/node/index.d.ts",
       "default": "./lib/node/index.js"
-    },
-    "./lib/common": {
-      "types": "./lib/common/index.d.ts",
-      "default": "./lib/common/index.js"
-    },
-    "./lib/browser": {
-      "types": "./lib/browser/index.d.ts",
-      "default": "./lib/browser/index.js"
-    },
-    "./lib/node": {
-      "types": "./lib/node/index.d.ts",
-      "default": "./lib/node/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/client-theia": "1.0.0-next.28",
-    "@hydranium/core": "1.0.0-next.28",
-    "@hydranium/protocol": "1.0.0-next.28",
+    "@hydranium/client-theia": "1.0.0-next.281",
+    "@hydranium/protocol": "1.0.0-next.281",
     "@theia/core": "^1.70.0",
     "@theia/workspace": "^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",
-    "vscode-jsonrpc": "9.0.1"
+    "typescript": "^7.0.2",
+    "vscode-jsonrpc": "9.0.0"
   },
   "peerDependencies": {
-    "@hydranium/client-theia": "1.0.0-next.28",
-    "@hydranium/core": "1.0.0-next.28",
-    "@hydranium/protocol": "1.0.0-next.28",
+    "@hydranium/client-theia": "1.0.0-next.281",
+    "@hydranium/protocol": "1.0.0-next.281",
     "@theia/core": "^1.70.0",
     "@theia/workspace": "^1.70.0",
     "inversify": "^6.0.0",
-    "vscode-jsonrpc": "9.0.1"
+    "vscode-jsonrpc": "^9.0.0"
   },
   "engines": {
     "node": ">=22.13"
   },
-  "publishConfig": {
-    "access": "public"
-  },
-  "//peerDependencies": "`vscode-jsonrpc` is EXACT rather than a range, because it is one link of an atomic chain with no independently movable link: `vscode-languageserver-protocol` depends on it at exactly 9.0.1, so any other value an adopter supplies is a SECOND physical copy rather than an upgrade. This wire stack breaks on copy identity rather than on structure — `ParameterStructures.auto` is a singleton compared by `===` in connection.js, so a request type built by one copy and sent over a connection owned by the other throws `Unknown parameter structure auto`. A caret or union range was rejected because npm then resolves a `vscode-jsonrpc@8.2.0` tree SILENTLY, with no diagnostic at all, and the failure surfaces only later at server init. Exact does not fail the install either — npm downgrades an unsatisfiable peer to a warning — but it is a NAMED ERESOLVE warning printing the required version beside the found one, and a hard error for anyone installing with `--strict-peer-deps`. It does NOT prevent a NESTED copy — `@eclipse-glsp/*` carries its own exact `vscode-jsonrpc@8.2.0` dependency and root `overrides` do not ship — so a consumer of the GLSP head must pin the chain in its own manifest.",
-  "//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": "`vscode-jsonrpc` takes a caret, so the framework shares the transport the LSP connection resolves, which an `init` scaffold pins: each `vscode-languageserver-protocol` release pins its transport exactly, so an exact peer would name a copy a fresh install rarely holds. The caret excludes 8.x, so a tree whose top holds GLSP's copy fails the peer with a named ERESOLVE warning, an error under `--strict-peer-deps`, rather than resolving silently. No peer reaches a NESTED copy, such as GLSP's or one the LSP packages nest. The wire compares message types and `ResponseError`s by copy identity, so the framework sends typed messages by method name and recognises errors with `isResponseError` rather than `instanceof`.",
+  "//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-connection.ts

@@ -7,6 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+import { type Clock, type Stopwatch, SystemClock } from '@hydranium/protocol';
 import { type Channel, DisposableCollection, Emitter, type Event, type MessageProvider } from '@theia/core';
 import { type ServiceConnectionProvider } from '@theia/core/lib/browser';
 import { Deferred } from '@theia/core/lib/common/promise-util';
@@ -104,7 +105,7 @@ class ChannelMessageWriter extends AbstractMessageWriter implements MessageWrite
  * Mirrors `@eclipse-glsp/theia-integration`'s `createChannelConnection`, but
  * lives here so the data-server head carries no GLSP dependency.
  */
-export function createChannelConnection(channel: Channel, logger?: Logger): MessageConnection {
+export function createChannelConnection(channel: Channel, logger: Logger): MessageConnection {
    const reader = new ChannelMessageReader(channel);
    const writer = new ChannelMessageWriter(channel);
    return createMessageConnection(reader, writer, logger);
@@ -120,8 +121,10 @@ export interface OpenChannelConnectionOptions {
     * publishes the port) exists.
     */
    whenReady?: Promise<void>;
-   /** Optional `vscode-jsonrpc` logger threaded into the connection. */
-   logger?: Logger;
+   /** Where the connection logs its protocol faults; without one they leave no trace. */
+   logger: Logger;
+   /** Times the escalation reset. Default a `SystemClock`. */
+   clock?: Clock;
    /**
     * Re-establish the connection whenever the live one is lost, by RE-OPENING
     * the channel on `path` — not merely by rebuilding over a channel Theia hands
@@ -199,8 +202,8 @@ export interface ChannelConnectionHandle {
    /**
     * The current connection. Read it per use rather than caching it: after a
     * reconnect this returns a NEW promise, and a cached one resolves to the
-    * dead connection forever. The same reasoning makes
-    * `AbstractDataServiceFrontend` rebuild its proxy rather than hold one.
+    * dead connection forever. The same reasoning makes `RpcConnection` rebuild
+    * its proxy per generation rather than hold one.
     */
    readonly current: Promise<MessageConnection>;
 
@@ -213,10 +216,10 @@ export interface ChannelConnectionHandle {
     *
     * **This is the event a consumer wants, not {@link onDidReconnect}.** Anything
     * derived from a connection — an `createRpcProxy`, a readiness gate, a
-    * `DataSession` generation — is dead from this moment, and a consumer that
+    * `DataConnection` generation — is dead from this moment, and a consumer that
     * waits for the replacement to be live instead keeps sending into the dead one
     * for the whole gap. A `DataPort` implementation translates this into the
-    * port's own `onDispose`, which is what makes `DataSession` drop its
+    * port's own `onDispose`, which is what makes `DataConnection` drop its
     * generation.
     *
     * Never fires when {@link OpenChannelConnectionOptions.reconnect} is off.
@@ -269,7 +272,7 @@ export interface ChannelConnectionHandle {
 export function openChannelConnection(
    connectionProvider: ServiceConnectionProvider,
    path: string,
-   options: OpenChannelConnectionOptions = {}
+   options: OpenChannelConnectionOptions
 ): ChannelConnectionHandle {
    const reconnect = options.reconnect ?? true;
    const reconnectDelays = options.reconnectDelays ?? DEFAULT_RECONNECT_DELAYS;
@@ -283,8 +286,9 @@ export function openChannelConnection(
    let awaitingReplacement = false;
    /** Consecutive losses, indexing `reconnectDelays`. */
    let losses = 0;
-   /** When the live connection was built, for the escalation reset. `0` before the first. */
-   let liveSince = 0;
+   const clock = options.clock ?? new SystemClock();
+   /** Running since the live connection was built, for the escalation reset. */
+   let sinceLive: Stopwatch | undefined;
    let reopenTimer: ReturnType<typeof setTimeout> | undefined;
    // Own synchronous flag, deliberately NOT `deferred.state`. Theia's
    // `Deferred` sets `state` inside a `.then()` on its own promise, so it is
@@ -298,7 +302,7 @@ export function openChannelConnection(
    let built = false;
 
    const scheduleReopen = (): void => {
-      if (liveSince > 0 && Date.now() - liveSince >= RECONNECT_ESCALATION_RESET_MS) {
+      if (sinceLive !== undefined && sinceLive.elapsedMs >= RECONNECT_ESCALATION_RESET_MS) {
          losses = 0;
       }
       const delay = reconnectDelays[Math.min(losses, reconnectDelays.length - 1)];
@@ -355,7 +359,7 @@ export function openChannelConnection(
       built = true;
       awaitingReplacement = false;
       generation++;
-      liveSince = Date.now();
+      sinceLive = clock.stopwatch();
       if (reconnect) {
          // Registered AFTER `createChannelConnection`, so the connection's own
          // reader and writer see the close first and `connection.onClose` still

package/src/browser/channel-data-port.ts

@@ -0,0 +1,189 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 { ChannelLogger, ConnectionReporter, type ConnectionAttempt, type ConnectionTarget } from '@hydranium/client-theia/browser';
+import { Clock } from '@hydranium/client-theia/common';
+import {
+   DATA_SERVER_CONNECT_FAILED,
+   DATA_SERVER_NOT_READY,
+   renderFrameworkMessage,
+   SystemClock,
+   type DataPort,
+   type ResolvedMessage,
+   type RpcConnectionLifecycle
+} from '@hydranium/protocol';
+import { Emitter, MessageService, nls, type Event } from '@theia/core';
+import { type ServiceConnectionProvider } from '@theia/core/lib/browser';
+import { RemoteConnectionProvider } from '@theia/core/lib/browser/messaging/service-connection-provider';
+import { inject, injectable, optional } from '@theia/core/shared/inversify';
+import { WorkspaceService } from '@theia/workspace/lib/browser';
+import type { MessageConnection } from 'vscode-jsonrpc';
+import { type ChannelConnectionHandle, openChannelConnection } from './channel-connection';
+import { whenWorkspaceOpen } from './workspace-gate';
+
+/**
+ * A {@link DataPort} over a Theia frontend channel.
+ *
+ * Subclasses supply {@link servicePath}; everything above the port —
+ * `DataConnection`, its sessions, and whatever model a widget drives — is
+ * host-neutral and shared with the VS Code and browser shells.
+ *
+ * Bind one per service path and in singleton scope. Theia keys a frontend
+ * channel by its path and refuses a second on a path already open, and the
+ * throw escapes the `openChannelConnection` the loser is awaiting, leaving that
+ * promise unsettled rather than rejected.
+ */
+@injectable()
+export abstract class ChannelDataPort implements DataPort {
+   @inject(RemoteConnectionProvider) protected readonly connectionProvider!: ServiceConnectionProvider;
+   @inject(WorkspaceService) protected readonly workspaceService!: WorkspaceService;
+   @inject(MessageService) protected readonly messageService!: MessageService;
+   @inject(ConnectionReporter) protected readonly connectionReporter!: ConnectionReporter;
+   @inject(ChannelLogger) readonly logger!: ChannelLogger;
+   /** Times the channel's reconnect escalation: the container's {@link Clock}, or a `SystemClock`. */
+   @inject(Clock) @optional() protected readonly clock: Clock = new SystemClock();
+
+   /** Frontend service path the backend forwarder for this head is registered under. */
+   protected abstract readonly servicePath: string;
+
+   /**
+    * Re-open the channel when the current connection is lost. Default `true` —
+    * re-opening is the only thing that recovers a restarted language server,
+    * which binds new ephemeral ports. Turn it off for a frontend that tears
+    * itself down on transport loss instead.
+    */
+   protected readonly reconnectOnConnectionLoss: boolean = true;
+
+   protected readonly disposeEmitter = new Emitter<void>();
+   readonly onDispose: Event<void> = this.disposeEmitter.event;
+
+   protected handle?: ChannelConnectionHandle;
+   /** Set by {@link dispose}, after which {@link connect} rejects. */
+   protected disposed = false;
+
+   /** How long a connection may take before it is reported as failed; it keeps trying after. */
+   protected readonly connectFailureNoticeMs: number = 30_000;
+   protected attempt?: ConnectionAttempt;
+   protected attemptTimer?: ReturnType<typeof setTimeout>;
+   /** Set once {@link connectionLifecycle} reports, which then owns the connection failures. */
+   protected reportsConnections = false;
+
+   /** Reports each connection generation through the {@link ConnectionReporter}. */
+   readonly connectionLifecycle: RpcConnectionLifecycle = {
+      onConnecting: () => {
+         this.reportsConnections = true;
+         this.settleAttempt();
+         const attempt = this.connectionReporter.connecting(this.connectionTarget);
+         this.attempt = attempt;
+         this.attemptTimer = setTimeout(() => {
+            attempt.failed(this.connectTimeoutMessage());
+            // The generation keeps waiting; a follow-up attempt reports it connecting.
+            this.attempt = this.connectionReporter.connecting(this.connectionTarget);
+         }, this.connectFailureNoticeMs);
+      },
+      onReady: () => this.settleAttempt(attempt => attempt.connected()),
+      onFailed: () => this.settleAttempt(attempt => attempt.failed(this.unreachableMessage()))
+   };
+
+   /**
+    * Open the workspace-gated channel and hand back its listening connection.
+    *
+    * Gated because the backend forwarder discovers the head's port by executing
+    * a command the language server answers, and the language server only
+    * launches once there is a workspace to launch it for. Asking earlier polls
+    * a command nobody has registered.
+    *
+    * Rejects once the port is disposed: the consumer reconnects when the
+    * dispose fires {@link onDispose}, and a channel opened then is closed by
+    * nothing.
+    */
+   connect(): Promise<MessageConnection> {
+      if (this.disposed) {
+         return Promise.reject(new Error(`${this.constructor.name}: the port is disposed`));
+      }
+      // Read per call rather than cached: `current` is repointed at a fresh
+      // promise every time the channel is re-opened, so reading through the
+      // handle is what makes a later generation reach the live server.
+      if (!this.handle) {
+         this.handle = openChannelConnection(this.connectionProvider, this.servicePath, {
+            whenReady: whenWorkspaceOpen(this.workspaceService),
+            logger: this.logger,
+            clock: this.clock,
+            reconnect: this.reconnectOnConnectionLoss
+         });
+         // A relaunched server binds new ephemeral ports; the handle re-opens
+         // and the forwarder rediscovers, but `DataConnection` caches its
+         // generation and would go on addressing the dead one. Its signal to
+         // drop that generation is this event.
+         this.handle.onDidLoseConnection(() => this.disposeEmitter.fire(undefined));
+      }
+      return this.handle.current;
+   }
+
+   /**
+    * Surface a transport or write failure as a Theia notification.
+    *
+    * Swallowing it is the failure this exists to prevent: a dead connection and
+    * an empty document are indistinguishable in a widget.
+    *
+    * `reported` is already a complete sentence with the detail interpolated, so
+    * wrapping it in a sentence of the host's own would nest one owner's clause
+    * inside another's and leave no translator in control of the whole.
+    */
+   reportError(_error: unknown, reported: ResolvedMessage): void {
+      const connectionFailure = reported.code === DATA_SERVER_CONNECT_FAILED.code || reported.code === DATA_SERVER_NOT_READY.code;
+      const message = renderFrameworkMessage(reported, nls.localization?.translations);
+      if (connectionFailure && this.reportsConnections) {
+         // The reporter shows the failure without its detail, so it is kept here.
+         this.logger.warn(message);
+         return;
+      }
+      this.messageService.error(message);
+   }
+
+   /** End the current attempt through `settle`, or cancel it. */
+   protected settleAttempt(settle: (attempt: ConnectionAttempt) => void = attempt => attempt.cancelled()): void {
+      clearTimeout(this.attemptTimer);
+      const attempt = this.attempt;
+      this.attempt = undefined;
+      if (attempt) {
+         settle(attempt);
+      }
+   }
+
+   protected get connectionTarget(): ConnectionTarget {
+      return (this.cachedConnectionTarget ??= {
+         connectingMessage: nls.localize('hydranium/data-client-theia/data-server-connecting', 'Connecting to the data server…'),
+         connectedMessage: nls.localize('hydranium/data-client-theia/data-server-connected', 'Connected to the data server.')
+      });
+   }
+   /** One object per port: the reporter keys what it has shown on it. */
+   protected cachedConnectionTarget?: ConnectionTarget;
+
+   protected unreachableMessage(): string {
+      return nls.localize('hydranium/data-client-theia/data-server-unreachable', 'Could not connect to the data server.');
+   }
+
+   protected connectTimeoutMessage(): string {
+      return nls.localize(
+         'hydranium/data-client-theia/data-server-timeout',
+         'The data server did not answer within {0} seconds.',
+         String(Math.round(this.connectFailureNoticeMs / 1000))
+      );
+   }
+
+   dispose(): void {
+      this.disposed = true;
+      this.settleAttempt();
+      this.handle?.dispose();
+      this.handle = undefined;
+      this.disposeEmitter.fire(undefined);
+      this.disposeEmitter.dispose();
+   }
+}

package/src/browser/data-session-stop-contribution.ts

@@ -0,0 +1,151 @@
+/********************************************************************************
+ * 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 { bindConnectionReporter } from '@hydranium/client-theia/browser';
+import type { DataConnection, DataServerProtocol, DataSession, DiagnosticOf, TransferElement } from '@hydranium/protocol';
+// Not the `@theia/core/lib/browser` barrel: it touches DOM globals at module
+// load, which the node-environment unit tests cannot provide.
+import { FrontendApplicationContribution, type OnWillStopAction } from '@theia/core/lib/browser/frontend-application-contribution';
+import { injectable, type interfaces } from '@theia/core/shared/inversify';
+
+/**
+ * Ends a Theia frontend's data sessions with its page, and holds the page
+ * while one of them is still saving. {@link bindDataConnection} binds it and
+ * has it {@link track} each data connection bound through it.
+ *
+ * **Stop.** {@link onStop} disposes every tracked session, which sends its
+ * `closeSession`, so the server ends it as closed: each document it was the
+ * last to hold is released at once. Otherwise the server learns of the page only
+ * when its connection goes, which Theia may hold open for its reconnect
+ * timeout, and then ends the sessions as lost, so their documents wait out the
+ * release grace. The close is best effort: under load the page's last frames
+ * can be lost on the way, and the server then ends the sessions as lost. A
+ * session with calls still in flight at the stop closes after them, which is
+ * too late for a page going away, and is left to the server's connection-close
+ * cleanup. A call a session makes in the same tick as the stop is refused and
+ * never sent.
+ *
+ * **Veto.** While a tracked session has a save in flight, {@link onWillStop}
+ * vetoes, including a session disposed meanwhile. In Electron, Theia awaits
+ * the veto's action, which waits for the saves to answer, a save started during
+ * the wait included, up to {@link maxSettlePasses} times. The browser runs no
+ * action before unload, so there the veto shows the leave-page prompt and
+ * nothing more. Theia ignores every veto under
+ * `application.confirmExit: 'never'`, so there a save in flight at the stop
+ * may be cut off.
+ */
+@injectable()
+export class DataSessionStopContribution implements FrontendApplicationContribution {
+   /** The sessions to end at the stop, and to wait for while they save. */
+   protected readonly sessions = new Set<DataSession<TransferElement>>();
+   /**
+    * How many times the veto's action waits for the saves in flight before it
+    * lets the stop go. Each wait ends by the session's own bound, so a save
+    * that never answers holds the stop for a few bounds, not for good.
+    */
+   protected readonly maxSettlePasses: number = 3;
+
+   /**
+    * Take every session of `connection` into the stop: the ones it has
+    * started already, and each one it starts from now on. Generic, so a
+    * connection of any transfer root, server and client fits.
+    */
+   track<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>>, TClient extends object>(
+      connection: DataConnection<TTransfer, TServer, TClient>
+   ): void {
+      connection.liveSessions.forEach(session => this.trackSession(session));
+      connection.onDidCreateSession(session => this.trackSession(session));
+   }
+
+   /**
+    * Take `session` into the stop. It leaves once it has ended and its saves
+    * have answered, so a session disposed with a save in flight still holds
+    * the page.
+    */
+   protected trackSession(session: DataSession<TransferElement>): void {
+      this.sessions.add(session);
+      // A save can outlast the wait's bound, so the session stays until none
+      // is left in flight.
+      const release = (): void =>
+         void session.whenSavesSettled().then(() => (session.hasSavesInFlight ? release() : this.sessions.delete(session)));
+      // An ended session has fired its event already, and never fires it again.
+      if (session.isDisposed) {
+         release();
+      } else {
+         session.onDidDispose(release);
+      }
+   }
+
+   onWillStop(): OnWillStopAction | undefined {
+      if (this.savingSessions().length === 0) {
+         return undefined;
+      }
+      return {
+         // Theia logs the reason and shows it nowhere, so it is not translated.
+         reason: 'Data sessions are saving',
+         action: async () => {
+            // The page stays usable while Theia awaits this, so a save can
+            // start during a wait; each pass waits for the saves then in flight.
+            for (let pass = 0; pass < this.maxSettlePasses; pass++) {
+               const saving = this.savingSessions();
+               if (saving.length === 0) {
+                  break;
+               }
+               await Promise.all(saving.map(session => session.whenSavesSettled()));
+            }
+            return true;
+         }
+      };
+   }
+
+   /** The tracked sessions with a save in flight. */
+   protected savingSessions(): DataSession<TransferElement>[] {
+      return [...this.sessions].filter(session => session.hasSavesInFlight);
+   }
+
+   onStop(): void {
+      for (const session of this.sessions) {
+         session.dispose();
+      }
+   }
+}
+
+/**
+ * Bind `connectionClass` in singleton scope, its sessions tracked by the
+ * {@link DataSessionStopContribution}, and bind that contribution and the
+ * `ConnectionReporter` the connection's port injects unless they are bound
+ * already. The binding's `onActivation` is taken; a frontend's own hook on the
+ * connection goes on the container's `onActivation`, which runs after it. A
+ * subclass of the contribution is rebound after this call: one bound before it
+ * is never registered as a frontend contribution, so its stop never runs.
+ * Call it once per connection class: a second call makes the class's lookup
+ * ambiguous.
+ */
+export function bindDataConnection<
+   TTransfer extends TransferElement,
+   TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>>,
+   TClient extends object
+>(
+   bind: interfaces.Bind,
+   isBound: interfaces.IsBound,
+   connectionClass: interfaces.Newable<DataConnection<TTransfer, TServer, TClient>>
+): void {
+   bind(connectionClass)
+      .toSelf()
+      .inSingletonScope()
+      .onActivation((context, connection) => {
+         context.container.get(DataSessionStopContribution).track(connection);
+         return connection;
+      });
+   if (!isBound(DataSessionStopContribution)) {
+      bind(DataSessionStopContribution).toSelf().inSingletonScope();
+      bind(FrontendApplicationContribution).toService(DataSessionStopContribution);
+   }
+   bindConnectionReporter(bind, isBound);
+}

package/src/browser/host-diagnostics-frontend.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { HostMemoryDiagnosticsService } from '@hydranium/client-theia/lib/browser';
+import { HostMemoryDiagnosticsService } from '@hydranium/client-theia/browser';
 import { HOST_DIAGNOSTICS_PATH, type HostDiagnosticsProtocol } from '@hydranium/protocol';
 import { RemoteConnectionProvider, type ServiceConnectionProvider } from '@theia/core/lib/browser/messaging/service-connection-provider';
 import { type interfaces } from '@theia/core/shared/inversify';

package/src/browser/index.ts

@@ -8,8 +8,7 @@
  ********************************************************************************/
 
 export * from './channel-connection';
-export * from './data-service-frontend';
-export * from './diagnostics-data-service-frontend';
+export * from './channel-data-port';
+export * from './data-session-stop-contribution';
 export * from './host-diagnostics-frontend';
-export * from './references-data-service-frontend';
 export * from './workspace-gate';

package/src/common/emitter-data-client.ts

@@ -12,7 +12,10 @@ import type {
    Project,
    ProjectsChangedEvent,
    TransferDiagnostic,
+   TransferDocumentDeletedEvent,
+   TransferDocumentDirtyChangedEvent,
    TransferDocumentSavedEvent,
+   TransferDocumentsBuiltEvent,
    TransferDocumentUpdatedEvent,
    TransferElement
 } from '@hydranium/protocol';
@@ -46,6 +49,18 @@ export class EmitterDataClient<
    /** Fires for each inbound {@link onDocumentSaved} notification. */
    readonly onDidSaveDocument: Event<TransferDocumentSavedEvent<TTransfer, TDiagnostic>> = this.onDocumentSavedEmitter.event;
 
+   protected readonly onDocumentDirtyChangedEmitter = new Emitter<TransferDocumentDirtyChangedEvent>();
+   /** Fires for each inbound {@link onDocumentDirtyChanged} notification. */
+   readonly onDidChangeDocumentDirty: Event<TransferDocumentDirtyChangedEvent> = this.onDocumentDirtyChangedEmitter.event;
+
+   protected readonly onDocumentDeletedEmitter = new Emitter<TransferDocumentDeletedEvent>();
+   /** Fires for each inbound {@link onDocumentDeleted} notification. */
+   readonly onDidDeleteDocument: Event<TransferDocumentDeletedEvent> = this.onDocumentDeletedEmitter.event;
+
+   protected readonly onDocumentsBuiltEmitter = new Emitter<TransferDocumentsBuiltEvent>();
+   /** Fires for each inbound {@link onDocumentsBuilt} notification. */
+   readonly onDidBuildDocuments: Event<TransferDocumentsBuiltEvent> = this.onDocumentsBuiltEmitter.event;
+
    protected readonly onProjectsChangedEmitter = new Emitter<ProjectsChangedEvent<TProject>>();
    /** Fires for each inbound {@link onProjectsChanged} notification. */
    readonly onDidChangeProjects: Event<ProjectsChangedEvent<TProject>> = this.onProjectsChangedEmitter.event;
@@ -58,6 +73,18 @@ export class EmitterDataClient<
       this.onDocumentSavedEmitter.fire(event);
    }
 
+   onDocumentDirtyChanged(event: TransferDocumentDirtyChangedEvent): void {
+      this.onDocumentDirtyChangedEmitter.fire(event);
+   }
+
+   onDocumentDeleted(event: TransferDocumentDeletedEvent): void {
+      this.onDocumentDeletedEmitter.fire(event);
+   }
+
+   onDocumentsBuilt(event: TransferDocumentsBuiltEvent): void {
+      this.onDocumentsBuiltEmitter.fire(event);
+   }
+
    onProjectsChanged(event: ProjectsChangedEvent<TProject>): void {
       this.onProjectsChangedEmitter.fire(event);
    }

package/src/node/connection-container-module.ts

@@ -27,11 +27,12 @@ import { ContainerModule, type interfaces } from '@theia/core/shared/inversify';
  *
  * **More than one handler is the normal case, not an exotic one.** Theia keys a
  * frontend channel by its service path and refuses a second channel on a path
- * already open, so every frontend abstraction reaching the data head needs its
- * own path and therefore its own handler — a host-neutral `DataPort` beside a
- * Theia `AbstractDataServiceFrontend` is exactly that shape. They still forward
+ * already open, so every frontend abstraction reaching the data head on its own
+ * channel needs its own path and therefore its own handler. They still forward
  * to the SAME data server: the path distinguishes the channel, the shared
- * `portCommand` names the one process behind it.
+ * `portCommand` names the one process behind it. Several participants over ONE
+ * channel need no second handler — that is what `DataConnection`'s sessions are
+ * for, and it is the cheaper arrangement.
  */
 export function createDataServerConnectionContainerModule(...handlerClasses: interfaces.Newable<ConnectionHandler>[]): ContainerModule {
    const frontendScopedConnectionModule = ConnectionContainerModule.create(({ bind }) => {