@hydranium/protocol 1.0.0-next.24 → 1.0.0-next.242

package/README.md

@@ -60,15 +60,52 @@ names, a worked example — is in
 @hydranium/protocol               # transfer documents, references, RPC machinery
 @hydranium/protocol/data          # DataServerProtocol / DataClientProtocol
 @hydranium/protocol/client        # the host-neutral client tier
-@hydranium/protocol/testing       # test doubles and waiters
+@hydranium/protocol/messages      # every message it raises, by code
+@hydranium/protocol/node          # process memory and heap-snapshot helpers
+@hydranium/protocol/testing       # test doubles, waiters, catalogue audit
 @hydranium/protocol/testing/node  # the Node-only doubles
 ```
 
 The root barrel re-exports `data` and `client`, so those two subpaths buy a
-narrower surface rather than reach; `testing` is only reachable by its own
-specifier, which is what keeps the doubles out of a production bundle. The RPC
+narrower surface rather than reach; `node` and `testing` are only reachable by
+their own specifiers, which keeps `node:*` imports out of a browser bundle and
+the doubles out of a production bundle. The RPC
 machinery documents itself in [`src/rpc/README.md`](./src/rpc/README.md).
 
+### Auditing a translation catalogue
+
+An adopter with i18n has one failure mode nothing else catches: a catalogue key
+naming no declared code falls back to the English, which is byte-identical to
+the deliberately-partial behaviour every adopter relies on. So a typo is
+invisible at runtime, and `theia nls-extract` reports what the source declares
+rather than whether a catalogue matches it.
+
+`@hydranium/protocol/testing` ships the audit for it — call it from your own
+test, over your own barrels:
+
+<!-- snippet-preamble
+import { flattenCatalogue, findUndeclaredCodes, findSharedCodes } from '@hydranium/protocol/testing';
+import * as protocolMessages from '@hydranium/protocol';
+declare const readFileSync: (path: string, encoding: string) => string;
+declare const expect: (actual: unknown) => { toEqual(expected: unknown): void };
+-->
+
+```ts
+const keys = Object.keys(flattenCatalogue(JSON.parse(readFileSync('nls/de.json', 'utf-8'))));
+
+// Every key names a code some barrel declares. `exemptPrefixes` is for keys no
+// barrel CAN declare — a host mechanism taking its key as an inline literal.
+expect(findUndeclaredCodes(keys, [protocolMessages])).toEqual([]);
+```
+
+`flattenCatalogue` joins nested keys with `/` (the separator a code already
+uses, and what Theia does to a nested catalogue) and drops `_`-prefixed note
+keys, so a flat server-side catalogue and a nested host-side one both go through
+it. `findSharedCodes` covers the other half: exactly one side renders a given
+message, so two catalogues holding one code are two authorities over one
+sentence — assert both key sets non-empty first, since an empty one satisfies
+disjointness while proving nothing.
+
 ## Status
 
 Alpha — pre-v0. The package is being populated incrementally, and its API is

package/lib/abstract-logger.d.ts

@@ -35,6 +35,11 @@ export declare abstract class AbstractLogger implements Logger {
     protected clock(): Clock;
     /** Render the current wall-clock instant as `HH:MM:SS.mmm`, sourced from {@link clock}. */
     protected timestamp(): string;
+    /**
+     * The `[Label - HH:MM:SS.mmm] [component]` prefix every sink starts a line
+     * with. The label is padded to the widest, so timestamps line up across sinks.
+     */
+    protected formatLinePrefix(label: string): string;
     error(message?: string, ...args: unknown[]): this;
     warn(message?: string, ...args: unknown[]): this;
     info(message?: string, ...args: unknown[]): this;

package/lib/abstract-logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"abstract-logger.d.ts","sourceRoot":"","sources":["../src/abstract-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,KAAK,EAAe,MAAM,SAAS,CAAC;AAClD,OAAO,EAAwB,KAAK,QAAQ,EAAE,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAK1F;;;;;;;;;;;;GAYG;AACH,8BAAsB,cAAe,YAAW,MAAM;IACvC,SAAS,CAAC,SAAS,CAAC,EAAE,MAAM;gBAAlB,SAAS,CAAC,EAAE,MAAM,YAAA;IAExC;;;;;;;OAOG;IACH,SAAS,CAAC,KAAK,IAAI,KAAK;IAIxB,2FAA2F;IAC3F,SAAS,CAAC,SAAS,IAAI,MAAM;IAI7B,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAIjD,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAIhD,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAIhD,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAIjD,uFAAuF;IACvF,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAIjD,4EAA4E;IAC5E,GAAG,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAK/C,+EAA+E;IAC/E,KAAK,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAOrD,qDAAqD;IACrD,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI5B,uFAAuF;IACvF,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI5B,kFAAkF;IAClF,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI7B;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI1B,yFAAyF;IACzF,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE,SAAS,OAAO,EAAO,EAAE,KAAK,SAAsB,GAAG,IAAI;IAOnH,gGAAgG;IAChG,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI;IAExG,qFAAqF;IACrF,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CACpD"}
+{"version":3,"file":"abstract-logger.d.ts","sourceRoot":"","sources":["../src/abstract-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,KAAK,EAAe,MAAM,SAAS,CAAC;AAClD,OAAO,EAAwB,KAAK,QAAQ,EAAE,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAK1F;;;;;;;;;;;;GAYG;AACH,8BAAsB,cAAe,YAAW,MAAM;IACvC,SAAS,CAAC,SAAS,CAAC,EAAE,MAAM;IAAxC,YAAsB,SAAS,CAAC,EAAE,MAAM,YAAA,EAAI;IAE5C;;;;;;;OAOG;IACH,SAAS,CAAC,KAAK,IAAI,KAAK,CAEvB;IAED,2FAA2F;IAC3F,SAAS,CAAC,SAAS,IAAI,MAAM,CAE5B;IAED;;;OAGG;IACH,SAAS,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;IAED,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAGhD;IACD,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAG/C;IACD,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAG/C;IACD,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAGhD;IACD,uFAAuF;IACvF,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAGhD;IACD,4EAA4E;IAC5E,GAAG,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAG9C;IAED,+EAA+E;IAC/E,KAAK,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAKpD;IAED,qDAAqD;IACrD,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE3B;IAED,uFAAuF;IACvF,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE3B;IAED,kFAAkF;IAClF,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE5B;IAED;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEzB;IAED,yFAAyF;IACzF,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE,SAAS,OAAO,EAAO,EAAE,KAAK,SAAsB,GAAG,IAAI,CAKlH;IAED,gGAAgG;IAChG,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC;IAEzG,qFAAqF;IACrF,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACrD"}

package/lib/abstract-logger.js

@@ -46,6 +46,13 @@ class AbstractLogger {
     timestamp() {
         return logger_1.Format.timestamp(new Date(this.clock().now()));
     }
+    /**
+     * The `[Label - HH:MM:SS.mmm] [component]` prefix every sink starts a line
+     * with. The label is padded to the widest, so timestamps line up across sinks.
+     */
+    formatLinePrefix(label) {
+        return `[${label.padEnd(5)} - ${this.timestamp()}]${this.component ? ` [${this.component}]` : ''}`;
+    }
     error(message, ...args) {
         this.send('error', message, args);
         return this;

package/lib/abstract-logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"abstract-logger.js","sourceRoot":"","sources":["../src/abstract-logger.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"abstract-logger.js","sourceRoot":"","sources":["../src/abstract-logger.ts"],"names":[],"mappings":"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"}

package/lib/client/data-connection.d.ts

@@ -0,0 +1,245 @@
+/********************************************************************************
+ * 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 { Disposable, Emitter, type Event } from 'vscode-jsonrpc';
+import { type DataClientProtocol, type DataServerProtocol, type DiagnosticOf, type ProjectOf, type TransferDocumentDirtyChangedEvent, type TransferDocumentUpdatedEvent } from '../data';
+import type { Logger } from '../logger';
+import type { TransferElement } from '../transfer-element';
+import { DataEvents } from './data-events';
+import type { DataPort } from './data-port';
+import { DataSession, type DataSessionFactory } from './data-session';
+import { RpcConnection, type RpcConnectionGeneration, type RpcConnectionLifecycle } from './rpc-connection';
+/**
+ * A watch {@link DataConnection.watchDocument} keeps could not be sent again to
+ * a connection that became ready after a drop; the next one sends it again.
+ */
+export declare const DATA_CONNECTION_WATCH_RESTORE_FAILED: import("../messages/primitives").MessageDefinition<"Could not watch {uri} again after reconnecting to the data server: {detail}">;
+/**
+ * A session's restore threw when its connection came back; the connection
+ * went on restoring the others.
+ */
+export declare const DATA_CONNECTION_SESSION_RESTORE_FAILED: import("../messages/primitives").MessageDefinition<"Could not restore a session after reconnecting to the data server: {detail}">;
+/** Options for {@link DataConnection}. */
+export interface DataConnectionOptions<TTransfer extends TransferElement = TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> 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;
+    /** Builds the sessions `createSession` hands out. Defaults to a plain {@link DataSession}. */
+    readonly sessionFactory?: DataSessionFactory<TTransfer, TServer>;
+}
+/** {@link DataConnectionOptions} for a client that does not speak {@link DataClientProtocol}. */
+export interface DataConnectionOptionsWithMethods<TClient extends object, TTransfer extends TransferElement = TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> extends DataConnectionOptions<TTransfer, TServer> {
+    /**
+     * 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, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> = TClient extends DataClientProtocol<TTransfer> ? [options?: DataConnectionOptions<TTransfer, TServer> & Partial<DataConnectionOptionsWithMethods<TClient, TTransfer, TServer>>] : [options: DataConnectionOptionsWithMethods<TClient, TTransfer, TServer>];
+/**
+ * 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 opens and watches per `(uri, clientId)`. Two parties sharing one
+ * identity cannot tell each other's writes from their own echoes.
+ * {@link DataConnection.watchDocument} is the exception: it acts as no
+ * participant, under an id no session holds, and opens or writes nothing.
+ *
+ * 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 declare class DataConnection<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>, TClient extends object = DataClientProtocol<TTransfer>> extends RpcConnection<TServer, TClient> {
+    protected readonly sessions: Set<DataSession<TTransfer, TServer>>;
+    protected readonly sessionFactory: DataSessionFactory<TTransfer, TServer>;
+    protected readonly createSessionEmitter: Emitter<DataSession<TTransfer, TServer>>;
+    /**
+     * Fires with each session {@link createSession} starts, before it returns,
+     * so a listener sees every session a caller can. A session started before
+     * the listener subscribed is in {@link liveSessions}.
+     */
+    readonly onDidCreateSession: Event<DataSession<TTransfer, TServer>>;
+    /**
+     * Per URI, the `dirty` the client was last told, whether a session of this
+     * connection has it open or a watch follows it. A session's open or close
+     * of the URI forgets it; disposing a watch does not, since a watch knows
+     * only the caller's spelling of the URI, not the server's key. A
+     * session's restore and a watch sent again after a reconnect tell the
+     * client their answer where it differs, a forgotten URI included; see
+     * {@link restoreDirty}.
+     */
+    protected readonly dirtyStates: Map<string, boolean>;
+    /** Backs each session's {@link DataSessionHost.onDidChangeDirty}. */
+    protected readonly dirtyChangedEmitter: Emitter<TransferDocumentDirtyChangedEvent>;
+    /** Backs each session's {@link DataSessionHost.onDidUpdateDocument}. */
+    protected readonly documentUpdatedEmitter: Emitter<TransferDocumentUpdatedEvent<TTransfer, DiagnosticOf<TServer>>>;
+    /**
+     * Per id {@link watchDocument} watches under, the URI it watches, which
+     * {@link generationReady} sends again to every later generation until the
+     * watch's handle is disposed.
+     */
+    protected readonly watches: Map<string, string>;
+    /**
+     * Per id, the URI of a watch whose handle was disposed with no ready
+     * generation to unwatch on. {@link generationReady} sends the unwatch to the
+     * next ready one: a generation that failed its readiness check after its
+     * watches were sent leaves them on a connection the port may hand back.
+     */
+    protected readonly pendingUnwatches: Map<string, string>;
+    /** The port's logger, or one that logs nothing. */
+    protected readonly logger: Logger;
+    /** Backs {@link onDidReconnect}. */
+    protected readonly reconnectEmitter: Emitter<void>;
+    /**
+     * Fires on every reconnect: once a connection becomes ready after an
+     * earlier one was, and its watches have been sent. The server sends no
+     * event for a change made while the connection was down, so a watcher reads
+     * its document again on this; a read it sends now reaches the server after
+     * its watch.
+     */
+    readonly onDidReconnect: Event<void>;
+    /** Whether a generation was ready before, which makes the next one a reconnect. */
+    protected readyBefore: boolean;
+    constructor(port: DataPort, client: TClient, ...rest: DataConnectionArgs<TTransfer, TClient, TServer>);
+    /**
+     * The sessions of this connection that have not ended, in the order they
+     * started. A session is listed until its `onDidDispose` fires, or until
+     * {@link dispose} clears the list.
+     */
+    get liveSessions(): readonly DataSession<TTransfer, TServer>[];
+    /**
+     * Start a participant on this connection, registered with the server under a
+     * fresh id, `label` plus `#` plus a random UUID, or under `clientId` when
+     * given. Pass a `label` naming the participant; without one it is
+     * `session`. Synchronous: the registration is sent at once, and the
+     * session's calls wait for it. The server refuses an id live anywhere in
+     * its process, and every call of that session then rejects with an error
+     * `isDuplicateClientIdError` recognises; an id the server reserves beyond
+     * {@link FRAMEWORK_CLIENT_IDS}, such as the integrity author, with one
+     * `isReservedClientIdError` recognises. Only the code crosses the wire, so
+     * test with those guards rather than `instanceof`.
+     *
+     * Throws a {@link ReservedClientIdError} 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 — and a
+     * {@link DuplicateClientIdError} for an id a live session on this
+     * connection already holds.
+     */
+    createSession(label?: string, clientId?: string): DataSession<TTransfer, TServer>;
+    /**
+     * Follow `uri` without opening it: its update events reach this
+     * connection's client once this resolves. An open would hold the document
+     * for as long as the caller follows it. The watch runs under an id of its
+     * own, `label` plus `#` plus a random UUID, and needs no session: a session
+     * closing the document would also end its own watch of it. Every later
+     * connection that becomes ready gets the watch again. Disposing the handle
+     * unwatches.
+     */
+    watchDocument(uri: string, label?: string): Promise<Disposable>;
+    /**
+     * The client, with its `onDocumentDirtyChanged` passing through
+     * {@link deliverDirty} first, so {@link dirtyStates} holds what the server
+     * told it, and every session hears it through {@link dirtyChangedEmitter};
+     * and with its `onDocumentUpdated` heard by every session through
+     * {@link documentUpdatedEmitter} first. Every other bound method forwards
+     * to the client unchanged, and one the client lacks stays absent, so the
+     * binding still refuses it.
+     */
+    protected localTarget(): TClient;
+    /**
+     * Hand a dirty state a restore read to the client, unless it is what
+     * {@link dirtyStates} says the client was last told; a URI it holds
+     * nothing for counts as different.
+     */
+    protected restoreDirty(event: TransferDocumentDirtyChangedEvent): void;
+    /** Record `event` in {@link dirtyStates} and hand it to the client. */
+    protected deliverDirty(event: TransferDocumentDirtyChangedEvent): void;
+    /**
+     * After the transport dropped, reconnect on the next macrotask for the
+     * sessions with documents open, so they re-watch and follow their documents
+     * again without waiting for a call of their own, and connect for what
+     * {@link watchDocument} watches, which {@link generationReady} places
+     * again; a session with nothing open restores on its next call. Nothing is
+     * scheduled once this connection is disposed, which drops its generation
+     * too.
+     */
+    protected dropGeneration(): void;
+    /**
+     * Call `reconnect()` on every session, reporting a throw instead of letting
+     * one session's restore stop the others and the watches after them, and,
+     * inside the readiness gate, fail the whole generation.
+     */
+    protected reconnectSessions(): void;
+    /**
+     * Restore what the server lost with an earlier generation, whichever
+     * request brought this one up: the documents of sessions that have some
+     * open, and every watch {@link watchDocument} keeps.
+     */
+    protected generationReady(generation: RpcConnectionGeneration<TServer>): void;
+    /** Take back the watch of `uri` under `clientId` on `generation`; the server ignores one it does not hold. */
+    protected unwatch(generation: RpcConnectionGeneration<TServer>, clientId: string, uri: string): void;
+    /**
+     * Send the watch of `uri` under `clientId` to `generation`, which has just
+     * passed its readiness gate. Sent at once rather than after a wait, so no
+     * drop can come between choosing the generation and sending. A failure is
+     * reported, since no caller waits on it, only while the watch is kept and
+     * `generation` is still current: otherwise the next generation sends it
+     * again.
+     *
+     * Once the watch is in place, the document's dirty state is read and goes
+     * through {@link restoreDirty}, as a session's restore does: a flip while
+     * the connection was down reached no one.
+     */
+    protected watchAgain(generation: RpcConnectionGeneration<TServer>, clientId: string, uri: string): void;
+    /**
+     * Sessions are detached rather than disposed: the server ends every session
+     * on a connection it sees close, so ending each one first sends requests
+     * over a connection this call is about to dispose.
+     */
+    dispose(): void;
+}
+/**
+ * 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 declare class DataConnectionWithEvents<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> extends DataConnection<TTransfer, TServer, DataEvents<TTransfer, DiagnosticOf<TServer>, ProjectOf<TServer>>> {
+    /** Server pushes, fanned out to as many local listeners as the host has. */
+    readonly events: DataEvents<TTransfer, DiagnosticOf<TServer>, ProjectOf<TServer>>;
+    constructor(port: DataPort, options?: DataConnectionOptions<TTransfer, TServer>);
+    /** Disposes the fan-out it created, which no caller else holds. */
+    dispose(): void;
+}
+//# sourceMappingURL=data-connection.d.ts.map

package/lib/client/data-connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-connection.d.ts","sourceRoot":"","sources":["../../src/client/data-connection.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEjE,OAAO,EAGJ,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,iCAAiC,EACtC,KAAK,4BAA4B,EACnC,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAIxC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,KAAK,uBAAuB,EAAE,KAAK,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE5G;;;GAGG;AACH,eAAO,MAAM,oCAAoC,mIAGhD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,sCAAsC,mIAGlD,CAAC;AAEF,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB,CACnC,SAAS,SAAS,eAAe,GAAG,eAAe,EACnD,OAAO,SAAS,kBAAkB,CAAC,SAAS,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,GAAG,kBAAkB,CAAC,SAAS,CAAC,CACrG,SAAQ,sBAAsB;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,8FAA8F;IAC9F,QAAQ,CAAC,cAAc,CAAC,EAAE,kBAAkB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;CACnE;AAED,iGAAiG;AACjG,MAAM,WAAW,gCAAgC,CAC9C,OAAO,SAAS,MAAM,EACtB,SAAS,SAAS,eAAe,GAAG,eAAe,EACnD,OAAO,SAAS,kBAAkB,CAAC,SAAS,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,GAAG,kBAAkB,CAAC,SAAS,CAAC,CACrG,SAAQ,qBAAqB,CAAC,SAAS,EAAE,OAAO,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,EAAE,CAAC;CAC9D;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,CAC3B,SAAS,SAAS,eAAe,EACjC,OAAO,SAAS,MAAM,EACtB,OAAO,SAAS,kBAAkB,CAAC,SAAS,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,GAAG,kBAAkB,CAAC,SAAS,CAAC,IAEpG,OAAO,SAAS,kBAAkB,CAAC,SAAS,CAAC,GACxC,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,gCAAgC,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,GAC9H,CAAC,OAAO,EAAE,gCAAgC,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;AAEjF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAc,CACxB,SAAS,SAAS,eAAe,EACjC,OAAO,SAAS,kBAAkB,CAAC,SAAS,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,GAAG,kBAAkB,CAAC,SAAS,CAAC,EACpG,OAAO,SAAS,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,CACvD,SAAQ,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC;IACtC,SAAS,CAAC,QAAQ,CAAC,QAAQ,uCAA8C;IACzE,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,kBAAkB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC1E,SAAS,CAAC,QAAQ,CAAC,oBAAoB,2CAAkD;IACzF;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,EAAE,KAAK,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAmC;IACtG;;;;;;;;OAQG;IACH,SAAS,CAAC,QAAQ,CAAC,WAAW,uBAA8B;IAC5D,qEAAqE;IACrE,SAAS,CAAC,QAAQ,CAAC,mBAAmB,6CAAoD;IAC1F,wEAAwE;IACxE,SAAS,CAAC,QAAQ,CAAC,sBAAsB,0EAAiF;IAC1H;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,sBAA6B;IACvD;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,gBAAgB,sBAA6B;IAChE,mDAAmD;IACnD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAClC,oCAAoC;IACpC,SAAS,CAAC,QAAQ,CAAC,gBAAgB,gBAAuB;IAC1D;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,KAAK,CAAC,IAAI,CAAC,CAA+B;IACnE,mFAAmF;IACnF,SAAS,CAAC,WAAW,UAAS;IAE9B,YAAY,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,kBAAkB,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,EAepG;IAED;;;;OAIG;IACH,IAAI,YAAY,IAAI,SAAS,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,CAE7D;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,KAAK,SAAY,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,CA8BnF;IAED;;;;;;;;OAQG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,SAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAmCrE;IAED;;;;;;;;OAQG;IACH,UAAmB,WAAW,IAAI,OAAO,CA4BxC;IAED;;;;OAIG;IACH,SAAS,CAAC,YAAY,CAAC,KAAK,EAAE,iCAAiC,GAAG,IAAI,CAIrE;IAED,uEAAuE;IACvE,SAAS,CAAC,YAAY,CAAC,KAAK,EAAE,iCAAiC,GAAG,IAAI,CAIrE;IAED;;;;;;;;OAQG;IACH,UAAmB,cAAc,IAAI,IAAI,CAiBxC;IAED;;;;OAIG;IACH,SAAS,CAAC,iBAAiB,IAAI,IAAI,CAWlC;IAED;;;;OAIG;IACH,UAAmB,eAAe,CAAC,UAAU,EAAE,uBAAuB,CAAC,OAAO,CAAC,GAAG,IAAI,CAUrF;IAED,8GAA8G;IAC9G,SAAS,CAAC,OAAO,CAAC,UAAU,EAAE,uBAAuB,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAGnG;IAED;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,UAAU,CAAC,UAAU,EAAE,uBAAuB,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CA+BtG;IAED;;;;OAIG;IACM,OAAO,IAAI,IAAI,CAavB;CACH;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,wBAAwB,CAClC,SAAS,SAAS,eAAe,EACjC,OAAO,SAAS,kBAAkB,CAAC,SAAS,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,GAAG,kBAAkB,CAAC,SAAS,CAAC,CACrG,SAAQ,cAAc,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,CAAC,SAAS,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3G,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,SAAS,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IAElF,YAAY,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,qBAAqB,CAAC,SAAS,EAAE,OAAO,CAAC,EAM9E;IAED,mEAAmE;IAC1D,OAAO,IAAI,IAAI,CAGvB;CACH"}