@hydranium/protocol 1.0.0-next.7 → 1.0.0-next.70

package/src/client/data-connection.ts

@@ -0,0 +1,160 @@
+/********************************************************************************
+ * 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 { FRAMEWORK_CLIENT_IDS } from '../client-ids';
+import { DATA_CLIENT_PROTOCOL_METHODS, DATA_SERVER_WIRE_PREFIX, type DataClientProtocol, type DataServerProtocol } from '../data';
+import type { TransferElement } from '../transfer-element';
+import { DataEvents } from './data-events';
+import type { DataPort } from './data-port';
+import { DataSession } from './data-session';
+import { RpcConnection, type RpcConnectionLifecycle } from './rpc-connection';
+
+/** Options for {@link DataConnection}. */
+export interface DataConnectionOptions extends RpcConnectionLifecycle {
+   /**
+    * Wire namespace the server is addressed under. Defaults to the
+    * framework's {@link DATA_SERVER_WIRE_PREFIX}, which is what an unmodified
+    * `DataServer` binds. Override only alongside the server's own
+    * `methodNamespace` option — a mismatch turns every request into
+    * "Unhandled method" rather than failing at wire-up.
+    */
+   readonly methodNamespace?: string;
+}
+
+/** {@link DataConnectionOptions} for a client that does not speak {@link DataClientProtocol}. */
+export interface DataConnectionOptionsWithMethods<TClient extends object> extends DataConnectionOptions {
+   /**
+    * Method names of the client to bind as inbound handlers. Declare it
+    * `as const satisfies ReadonlyArray<keyof YourClient & string>` so the list
+    * cannot drift from the interface.
+    */
+   readonly clientMethods: readonly (keyof TClient & string)[];
+}
+
+/**
+ * Trailing constructor arguments, required only when the client cannot take
+ * the framework's default method list.
+ *
+ * `bindRpcMethods` throws for a name the target does not implement, so a
+ * request/response-only client binding the default list fails at wire-up. The
+ * conditional turns that into a compile error.
+ */
+export type DataConnectionArgs<TTransfer extends TransferElement, TClient extends object> =
+   TClient extends DataClientProtocol<TTransfer>
+      ? [options?: DataConnectionOptions & Partial<DataConnectionOptionsWithMethods<TClient>>]
+      : [options: DataConnectionOptionsWithMethods<TClient>];
+
+/**
+ * A {@link RpcConnection} to the data head, carrying as many participants as
+ * the host has interested parties.
+ *
+ * Document operations live on the participants rather than here: they carry a
+ * `clientId`, which identifies a participant rather than a wire, and the server
+ * keys its holds and watches per `(uri, clientId)`. Two parties sharing one
+ * identity cannot tell each other's writes from their own echoes.
+ *
+ * Generic over the transfer root so this file names no grammar. An adopter
+ * binds the concrete root (or the union of them, for a multi-grammar head) at
+ * its own edge.
+ */
+export class DataConnection<
+   TTransfer extends TransferElement,
+   TServer extends DataServerProtocol<TTransfer> = DataServerProtocol<TTransfer>,
+   TClient extends object = DataClientProtocol<TTransfer>
+> extends RpcConnection<TServer, TClient> {
+   protected readonly sessions = new Set<DataSession<TTransfer, TServer>>();
+
+   constructor(port: DataPort, client: TClient, ...rest: DataConnectionArgs<TTransfer, TClient>) {
+      const [options = {}] = rest as [(DataConnectionOptions & Partial<DataConnectionOptionsWithMethods<TClient>>)?];
+      super(port, client, {
+         methodNamespace: options.methodNamespace ?? DATA_SERVER_WIRE_PREFIX,
+         // The default is reachable only where `TClient` satisfies
+         // `DataClientProtocol`, which the constructor's conditional enforces;
+         // the compiler cannot carry that through to the generic parameter.
+         clientMethods: options.clientMethods ?? (DATA_CLIENT_PROTOCOL_METHODS as unknown as readonly (keyof TClient & string)[]),
+         lifecycle: options
+      });
+   }
+
+   /**
+    * Mint a participant on this connection under `clientId`.
+    *
+    * `clientId` must be distinct per participant and stable for its lifetime:
+    * it keys the server's per-`(uri, clientId)` hold and watch, and it is the
+    * echo key an inbound `onDocumentUpdated` is matched against.
+    *
+    * Throws for an id in {@link FRAMEWORK_CLIENT_IDS} — those are authors the
+    * SERVER emits rather than participants, so a session holding one would read
+    * the framework's own broadcasts as its own echoes and drop them. Nothing
+    * about that fails on its own: the document simply stops following, which
+    * looks like a dead connection.
+    */
+   createSession(clientId: string): DataSession<TTransfer, TServer> {
+      this.assertLive();
+      if (FRAMEWORK_CLIENT_IDS.includes(clientId)) {
+         throw new Error(`clientId '${clientId}' is reserved by the framework and cannot identify a participant`);
+      }
+      const session = new DataSession<TTransfer, TServer>(clientId, {
+         connected: () => this.connected(),
+         releaseSession: released => this.sessions.delete(released)
+      });
+      this.sessions.add(session);
+      return session;
+   }
+
+   /**
+    * Sessions are detached rather than disposed: the server releases every hold
+    * on a connection it sees close, so closing each document first sends
+    * requests over a connection this call is about to dispose.
+    */
+   override dispose(): void {
+      for (const session of [...this.sessions]) {
+         session.detach();
+      }
+      this.sessions.clear();
+      super.dispose();
+   }
+}
+
+/**
+ * A {@link DataConnection} that brings its own {@link DataEvents}, so a host
+ * with several interested parties does not have to supply one.
+ *
+ * **The client slot holds exactly one object, and that is why this exists.**
+ * `createRpcProxy` binds a single `localTarget`, and underneath a method name
+ * maps to one handler — a second registration replaces the first silently. So a
+ * properties panel and a tree cannot both be the client; one fan-out sits in the
+ * slot and both subscribe to it.
+ *
+ * Use {@link DataConnection} directly instead when the client is yours: an
+ * adopter service that implements the protocol plus its own methods, a single
+ * consumer that IS the client, or a request/response-only client that binds
+ * nothing.
+ */
+export class DataConnectionWithEvents<
+   TTransfer extends TransferElement,
+   TServer extends DataServerProtocol<TTransfer> = DataServerProtocol<TTransfer>
+> extends DataConnection<TTransfer, TServer, DataEvents<TTransfer>> {
+   /** Server pushes, fanned out to as many local listeners as the host has. */
+   readonly events: DataEvents<TTransfer>;
+
+   constructor(port: DataPort, options?: DataConnectionOptions) {
+      // Built as a local because `this` is unavailable before `super`, then
+      // read back onto the field.
+      const events = new DataEvents<TTransfer>();
+      super(port, events, options);
+      this.events = events;
+   }
+
+   /** Disposes the fan-out it created, which no caller else holds. */
+   override dispose(): void {
+      super.dispose();
+      this.events.dispose();
+   }
+}

package/src/client/data-events.ts

@@ -8,7 +8,14 @@
  ********************************************************************************/
 
 import { Emitter, type Event } from 'vscode-jsonrpc';
-import type { DataClientProtocol, ProjectsChangedEvent, TransferDocumentSavedEvent, TransferDocumentUpdatedEvent } from '../data';
+import type {
+   DataClientProtocol,
+   ProjectsChangedEvent,
+   TransferDocumentDeletedEvent,
+   TransferDocumentSavedEvent,
+   TransferDocumentsBuiltEvent,
+   TransferDocumentUpdatedEvent
+} from '../data';
 import type { Project } from '../project';
 import type { TransferDiagnostic } from '../transfer-diagnostic';
 import type { TransferElement } from '../transfer-element';
@@ -40,12 +47,18 @@ export class DataEvents<
 > implements DataClientProtocol<TTransfer, TDiagnostic, TProject> {
    protected readonly documentUpdatedEmitter = new Emitter<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>>();
    protected readonly documentSavedEmitter = new Emitter<TransferDocumentSavedEvent<TTransfer, TDiagnostic>>();
+   protected readonly documentDeletedEmitter = new Emitter<TransferDocumentDeletedEvent>();
+   protected readonly documentsBuiltEmitter = new Emitter<TransferDocumentsBuiltEvent>();
    protected readonly projectsChangedEmitter = new Emitter<ProjectsChangedEvent<TProject>>();
 
    /** A build-phase event for a watched document. Carries the originating `sourceClientId`. */
    readonly onDidUpdateDocument: Event<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>> = this.documentUpdatedEmitter.event;
    /** A watched document was persisted to disk. */
    readonly onDidSaveDocument: Event<TransferDocumentSavedEvent<TTransfer, TDiagnostic>> = this.documentSavedEmitter.event;
+   /** A document's backing file was removed, watched or not. Any watch survives. */
+   readonly onDidDeleteDocument: Event<TransferDocumentDeletedEvent> = this.documentDeletedEmitter.event;
+   /** Documents built that nobody watches — re-read anything derived from them. */
+   readonly onDidBuildDocuments: Event<TransferDocumentsBuiltEvent> = this.documentsBuiltEmitter.event;
    /** The project set changed. */
    readonly onDidChangeProjects: Event<ProjectsChangedEvent<TProject>> = this.projectsChangedEmitter.event;
 
@@ -59,6 +72,14 @@ export class DataEvents<
       this.documentSavedEmitter.fire(event);
    }
 
+   onDocumentDeleted(event: TransferDocumentDeletedEvent): void {
+      this.documentDeletedEmitter.fire(event);
+   }
+
+   onDocumentsBuilt(event: TransferDocumentsBuiltEvent): void {
+      this.documentsBuiltEmitter.fire(event);
+   }
+
    onProjectsChanged(event: ProjectsChangedEvent<TProject>): void {
       this.projectsChangedEmitter.fire(event);
    }
@@ -66,6 +87,8 @@ export class DataEvents<
    dispose(): void {
       this.documentUpdatedEmitter.dispose();
       this.documentSavedEmitter.dispose();
+      this.documentDeletedEmitter.dispose();
+      this.documentsBuiltEmitter.dispose();
       this.projectsChangedEmitter.dispose();
    }
 }

package/src/client/data-port.ts

@@ -8,15 +8,19 @@
  ********************************************************************************/
 
 import type { Event, MessageConnection } from 'vscode-jsonrpc';
+import type { ResolvedMessage } from '../messages/primitives';
 
 /**
  * The one thing a host has to supply for the data head: a live JSON-RPC
- * connection to the data server, plus the identity and failure sink that go
- * with it.
+ * connection to the data server, plus the failure sink that goes with it.
  *
- * "Port" in the hexagonal sense — the host implements it, `DataSession`
+ * "Port" in the hexagonal sense — the host implements it, `DataConnection`
  * consumes it, and nothing on either side of the boundary imports the other.
  *
+ * Carries no identity. A `clientId` names a participant, and one transport
+ * serves as many as the host has; binding an identity here is what makes two
+ * of them share one, so it lives on `DataSession` instead.
+ *
  * **This deliberately does NOT wrap the protocol methods.** `createRpcProxy`
  * already takes a promise of a connection and produces the whole typed
  * `DataServerProtocol` surface, so wrapping it would re-derive the framework's
@@ -45,22 +49,6 @@ import type { Event, MessageConnection } from 'vscode-jsonrpc';
  *   calls on the promise but never calls `listen` itself.
  */
 export interface DataPort {
-   /**
-    * Stable identity of this client on the data server, passed as `clientId`
-    * on every document request.
-    *
-    * It has to be stable for the session because it is the echo key: an
-    * inbound `onDocumentUpdated` carries the originating mutation's
-    * `clientId` as `sourceClientId`, and a client that cannot recognise its
-    * own echo treats its own write as a concurrent third-party one. It also
-    * has to be distinct per client, since it keys the server's per-
-    * `(uri, clientId)` watch bucket.
-    *
-    * Avoid the three values the framework itself uses as sentinels —
-    * `'language-client'`, `'unknown'` and `'revert-on-close'`.
-    */
-   readonly clientId: string;
-
    /**
     * Open the transport and hand back a listening `MessageConnection`.
     *
@@ -77,10 +65,16 @@ export interface DataPort {
     *
     * It exists because the alternative is worse in both directions: this tier
     * cannot import a host's UI, and swallowing the error makes a dead
-    * connection look like an empty model. `context` names what was being
-    * attempted, not where in the code it happened.
+    * connection look like an empty model.
+    *
+    * `reported` is a complete sentence plus the identity needed to render it in
+    * another language. It carries a value rather than using a protocol field
+    * because this tier does not know whether a process hop intervenes — in a
+    * webview host the render happens across one — and a `ResolvedMessage` is
+    * structured-clone safe either way. Render it with `renderFrameworkMessage`;
+    * passing no translation map yields the English.
     */
-   reportError(error: unknown, context: string): void;
+   reportError(error: unknown, reported: ResolvedMessage): void;
 
    /**
     * Fires when the host tears the transport down and the current connection

package/src/client/data-session.ts

@@ -7,101 +7,64 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { MessageConnection } from 'vscode-jsonrpc';
-import { DATA_CLIENT_PROTOCOL_METHODS, DATA_SERVER_WIRE_PREFIX, type DataClientProtocol, type DataServerProtocol } from '../data';
-import { type RpcProxy, createRpcProxy } from '../rpc';
+import type { DataServerProtocol, TransferSaveDocumentArgs, TransferUpdateDocumentArgs } from '../data';
+import type { RpcProxy } from '../rpc';
 import type { TransferDocument } from '../transfer-document';
 import type { TransferElement } from '../transfer-element';
-import type { DataPort } from './data-port';
 
-/** Options for {@link DataSession}. */
-export interface DataSessionOptions {
-   /**
-    * Wire namespace the server is addressed under. Defaults to the
-    * framework's {@link DATA_SERVER_WIRE_PREFIX}, which is what an unmodified
-    * `DataServer` binds. Override only alongside the server's own
-    * `methodNamespace` option — a mismatch turns every request into
-    * "Unhandled method" rather than failing at wire-up.
-    */
-   readonly methodNamespace?: string;
-}
+/** Update a document through a session; the session supplies `clientId`. */
+export type DataSessionUpdateArgs<TTransfer> = Omit<TransferUpdateDocumentArgs<TTransfer>, 'clientId'>;
 
-/** One connection generation: its connection, its proxy, and its readiness. */
-interface Generation<TTransfer extends TransferElement> {
-   readonly connection: Promise<MessageConnection>;
-   readonly server: RpcProxy<DataServerProtocol<TTransfer>>;
-   /** Set on first use; the shared readiness gate for this generation. */
-   ready?: Promise<void>;
-}
+/** Persist a document through a session; the session supplies `clientId`. */
+export type DataSessionSaveArgs<TTransfer> = Omit<TransferSaveDocumentArgs<TTransfer>, 'clientId'>;
 
 /**
- * The host-invariant half of talking to the data head: everything above
- * {@link DataPort} that would otherwise be re-derived by every host
- * adapter.
+ * What a {@link DataSession} needs from the connection that minted it.
  *
- * Three jobs, and deliberately no fourth:
+ * Narrower than the connection itself so the dependency points one way:
+ * `DataConnection` constructs sessions, and nothing here imports it back.
+ */
+export interface DataSessionHost<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer>> {
+   connected(): Promise<RpcProxy<TServer>>;
+   releaseSession(session: DataSession<TTransfer, TServer>): void;
+}
+
+/**
+ * One participant on a data connection: a properties panel, a tree, a
+ * form editor.
  *
- * 1. **Build the typed proxy** over the port's connection, with the framework's
- *    wire prefix and its drift-proof client-method allowlist.
- * 2. **Own the readiness gate** — `waitForReady` once per connection, shared
- *    across concurrent callers. A socket client can connect before the
- *    workspace walk finishes, and an early request is then answered correctly
- *    from an empty registry, which reads as a broken project tier rather than
- *    as a race.
- * 3. **Own the reconnect policy**, by dropping its connection generation when
- *    the port disposes and building a fresh one on the next request.
+ * The server keys every hold and watch per `(uri, clientId)`, so the identity
+ * belongs to the participant rather than to the wire — several sessions share
+ * one connection, and two participants forced to share one identity cannot
+ * distinguish each other's writes from their own echoes.
  *
- * It does **not** wrap the protocol methods; callers reach them through
- * {@link connected}. The one exception is {@link openDocument}, which exists
- * because the open/watch *order* is silently wrong the other way round — see
- * its own doc.
+ * Every document operation stamps {@link clientId} itself. A caller that
+ * passed its own could pass another participant's, and the server would
+ * attribute the write and release the hold accordingly.
  *
- * Generic over the transfer root so this file names no grammar. An adopter
- * binds the concrete root (or the union of them, for a multi-grammar head) at
- * its own edge.
+ * Generic over the transfer root so this file names no grammar.
  */
-export class DataSession<TTransfer extends TransferElement> {
-   protected readonly methodNamespace: string;
-   /** The current generation, or `undefined` before the first request / after a teardown. */
-   protected generation?: Generation<TTransfer>;
+export class DataSession<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer> = DataServerProtocol<TTransfer>> {
+   /** URIs this session holds open, so {@link dispose} can release exactly those. */
+   protected readonly openUris = new Set<string>();
    protected disposed = false;
-   protected readonly portDisposeListener: { dispose(): void };
 
    constructor(
-      protected readonly port: DataPort,
-      protected readonly client: DataClientProtocol<TTransfer>,
-      options: DataSessionOptions = {}
-   ) {
-      this.methodNamespace = options.methodNamespace ?? DATA_SERVER_WIRE_PREFIX;
-      this.portDisposeListener = this.port.onDispose(() => this.dropGeneration());
-   }
-
-   /** The identity every request is made under — the port's, not a second one. */
-   get clientId(): string {
-      return this.port.clientId;
-   }
+      readonly clientId: string,
+      protected readonly host: DataSessionHost<TTransfer, TServer>
+   ) {}
 
    /**
-    * The connected, READY server proxy.
-    *
-    * Returns the proxy rather than `void` on purpose. A reconnect replaces the
-    * proxy, so a caller that cached one from an earlier call would go on
-    * addressing a dead connection with no error — handing it back per call
-    * makes the stale reference unrepresentable.
-    *
-    * Concurrent callers share one readiness promise, so `waitForReady` is
-    * awaited once per generation and not once per caller.
+    * The connected, READY server proxy, for protocol methods this session does
+    * not wrap — the ones carrying no `clientId`, so no identity can be got
+    * wrong through them.
     */
-   async connected(): Promise<RpcProxy<DataServerProtocol<TTransfer>>> {
-      if (this.disposed) {
-         throw new Error('DataSession is disposed');
-      }
-      const generation = this.currentGeneration();
-      if (!generation.ready) {
-         generation.ready = this.awaitReady(generation);
-      }
-      await generation.ready;
-      return generation.server;
+   async connected(): Promise<RpcProxy<TServer>> {
+      // `async` so a disposed session REJECTS rather than throwing
+      // synchronously: the connection's own `connected` rejects, and a caller
+      // reaching for `.catch` on one of them would not catch the other.
+      this.assertLive();
+      return this.host.connected();
    }
 
    /**
@@ -126,6 +89,7 @@ export class DataSession<TTransfer extends TransferElement> {
       const server = await this.connected();
       const document = await server.openModelDocument({ uri, clientId: this.clientId });
       await server.watchModelDocument({ uri, clientId: this.clientId });
+      this.openUris.add(uri);
       return document;
    }
 
@@ -135,11 +99,24 @@ export class DataSession<TTransfer extends TransferElement> {
     */
    async closeDocument(uri: string): Promise<void> {
       const server = await this.connected();
+      this.openUris.delete(uri);
       await server.closeModelDocument({ uri, clientId: this.clientId });
    }
 
+   /** Write `args.model` back as this session. */
+   async updateDocument(args: DataSessionUpdateArgs<TTransfer>): Promise<TransferDocument<TTransfer>> {
+      const server = await this.connected();
+      return server.updateModelDocument({ ...args, clientId: this.clientId });
+   }
+
+   /** Persist `args.model` to disk as this session. */
+   async saveDocument(args: DataSessionSaveArgs<TTransfer>): Promise<TransferDocument<TTransfer>> {
+      const server = await this.connected();
+      return server.saveModelDocument({ ...args, clientId: this.clientId });
+   }
+
    /**
-    * Whether `event.sourceClientId` identifies this session's own write.
+    * Whether `sourceClientId` identifies this session's own write.
     *
     * Every watcher needs this and the check is one comparison, so getting it
     * wrong is cheap to do and expensive to find: an unfiltered echo looks
@@ -149,61 +126,46 @@ export class DataSession<TTransfer extends TransferElement> {
       return sourceClientId === this.clientId;
    }
 
-   /** Tear down the current connection and stop tracking the port. Idempotent. */
+   /**
+    * Release this session's holds and detach it from the connection.
+    * Idempotent, and leaves the connection usable by its other sessions.
+    *
+    * The closes are fired without being awaited, because a `Disposable` cannot
+    * be: a host disposing a widget has nowhere to put the promise. A close
+    * that fails is no worse than the leak this exists to prevent, so the
+    * rejection is swallowed rather than surfaced from a teardown.
+    */
    dispose(): void {
       if (this.disposed) {
          return;
       }
       this.disposed = true;
-      this.portDisposeListener.dispose();
-      this.dropGeneration();
-   }
-
-   /** The live generation, building one if there is none. */
-   protected currentGeneration(): Generation<TTransfer> {
-      if (this.generation) {
-         return this.generation;
-      }
-      const connection = this.port.connect();
-      // Rejection is reported here rather than left to float: an unhandled
-      // rejection on a connection promise is the failure mode that reads as
-      // "the model is empty" instead of "the transport never opened".
-      connection.catch((error: unknown) => this.port.reportError(error, 'connecting to the data server'));
-      const server = createRpcProxy<DataServerProtocol<TTransfer>, DataClientProtocol<TTransfer>>(connection, {
-         methodNamespace: this.methodNamespace,
-         localTarget: this.client,
-         localMethods: DATA_CLIENT_PROTOCOL_METHODS
-      });
-      this.generation = { connection, server };
-      return this.generation;
-   }
-
-   /** Await the connection and the server's startup gate for one generation. */
-   protected async awaitReady(generation: Generation<TTransfer>): Promise<void> {
-      try {
-         await generation.connection;
-         await generation.server.waitForReady();
-      } catch (error: unknown) {
-         // Drop the generation so the next request retries rather than
-         // re-awaiting a settled rejection forever.
-         if (this.generation === generation) {
-            this.generation = undefined;
-         }
-         this.port.reportError(error, 'waiting for the data server to become ready');
-         throw error;
+      const uris = [...this.openUris];
+      this.openUris.clear();
+      this.host.releaseSession(this);
+      for (const uri of uris) {
+         void this.host
+            .connected()
+            .then(server => server.closeModelDocument({ uri, clientId: this.clientId }))
+            .catch(() => undefined);
       }
    }
 
    /**
-    * Discard the current generation, disposing its connection if it opened.
-    * The next {@link connected} builds a fresh one.
+    * Come off the connection because it is going away.
+    *
+    * Sends no close, unlike {@link dispose}: the server releases every hold on
+    * a connection it sees close, and the close would travel over the very
+    * connection being disposed.
     */
-   protected dropGeneration(): void {
-      const generation = this.generation;
-      this.generation = undefined;
-      if (!generation) {
-         return;
+   detach(): void {
+      this.disposed = true;
+      this.openUris.clear();
+   }
+
+   protected assertLive(): void {
+      if (this.disposed) {
+         throw new Error('DataSession is disposed');
       }
-      generation.connection.then(connection => connection.dispose()).catch(() => undefined);
    }
 }

package/src/client/index.ts

@@ -13,8 +13,9 @@
  *
  * Where `./data` is the wire *contract* and `./rpc` is the machinery that lowers
  * it onto a connection, this is what a client wraps around both: the seam a host
- * fills in (`DataPort`), the lifecycle above it (`DataSession` —
- * readiness gate, open/watch ordering, echo recognition, reconnect), the inbound
+ * fills in (`DataPort`), the connection above it (`DataConnection` — readiness
+ * gate and reconnect), the participants on that connection (`DataSession` —
+ * identity, open/watch ordering, echo recognition), the inbound
  * fan-out (`DataEvents`), and the two halves of the hop for hosts whose
  * client cannot hold a socket — `createPostMessageTransport` on the client
  * side and `relayToPostMessageChannel` on the side that does hold it.
@@ -26,15 +27,17 @@
  * carries the entries.
  *
  * The Theia-specific mounting of the same contract lives in
- * `@hydranium/data-client-theia`: its `AbstractDataServiceFrontend` solves the
- * same problem against Theia's channel transport, and its `EmitterDataClient`
- * is the Theia-bound counterpart of `DataEvents`. Prefer this tier for
- * anything new, and reach for the Theia package only for what genuinely needs
- * Theia DI.
+ * `@hydranium/data-client-theia`, and is now only the TRANSPORT: its
+ * `ChannelDataPort` fills the `DataPort` seam over a Theia channel, and its
+ * `EmitterDataClient` is the Theia-bound counterpart of `DataEvents`.
+ * Everything above the port is here, so a Theia frontend and a browser page
+ * differ by which port they construct and nothing else.
  */
 
+export * from './data-connection';
 export * from './data-events';
 export * from './data-port';
 export * from './data-session';
 export * from './message-relay';
 export * from './post-message-transport';
+export * from './rpc-connection';