@hydranium/data-client-vscode 0.0.0-stage → 1.0.0-next

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# `@hydranium/data-client-vscode`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The data head's client side in a VS Code extension built on
+[Hydranium](https://github.com/eclipse-emfcloud/hydranium). Install it when a
+webview of your extension reads or writes models through the data head: a
+webview has no sockets, so the extension host relays the data-server's socket
+to it over a `vscode-messenger` hop, and the webview's data port reads it.
+
+## What it gives you
+
+- The extension host's relay from the data-server's socket to one webview,
+  with the port looked up again for every connection, so a restarted server
+  is found.
+- A channel over the messenger for each end of the hop, filtered to the one
+  webview it serves, so the hop can be shared with GLSP's diagram webviews.
+- The webview's `DataPort`, for the connection and sessions from
+  `@hydranium/protocol`, which rejects pending requests when the extension host
+  reports the relay lost.
+
+## Install
+
+```bash
+npm install @hydranium/data-client-vscode
+```
+
+| Peer                       | Range         |
+| -------------------------- | ------------- |
+| `@hydranium/protocol`      | `^1.0.0-next` |
+| `vscode-jsonrpc`           | `^9.0.0`      |
+| `vscode-messenger`         | `^0.4.5`      |
+| `vscode-messenger-common`  | `^0.4.5`      |
+| `vscode-messenger-webview` | `^0.4.5`      |
+
+The `vscode-messenger` packages are optional; only `./testing` loads them.
+Your extension and webview use the copies GLSP's VS Code integration brings,
+or their own.
+
+## Wiring
+
+In the extension host, connect each webview to the data head over a messenger
+constructed with `ignoreHiddenViews: false`, as `GlspVscodeConnector`'s is, or
+a hidden webview misses every answer. Tell the webview when the relay closes,
+since nothing else reaches it:
+
+<!-- snippet-preamble
+import type { MessageParticipant } from 'vscode-messenger-common';
+import type { Messenger } from 'vscode-messenger';
+declare const messenger: Messenger;
+declare const webview: MessageParticipant;
+declare function findDataServerPort(): Promise<number>;
+declare function tellWebviewConnectionLost(): void;
+-->
+
+```ts
+import { connectDataServer } from '@hydranium/data-client-vscode/node';
+
+const relay = connectDataServer({ messenger, webview, findPort: findDataServerPort });
+relay.onClose(() => tellWebviewConnectionLost());
+```
+
+In the webview, build the port over the mirror channel, start the messenger,
+and hand the port to a data connection; call `connectionLost` on the port
+when the extension host says the relay closed:
+
+```ts
+import { createWebviewSideChannel } from '@hydranium/data-client-vscode';
+import { WebviewDataPort } from '@hydranium/data-client-vscode/browser';
+import { DataConnectionWithEvents } from '@hydranium/protocol';
+import { HOST_EXTENSION } from 'vscode-messenger-common';
+import { Messenger, type VsCodeApi } from 'vscode-messenger-webview';
+
+// VS Code injects it into the webview; there is nothing to import.
+declare function acquireVsCodeApi(): VsCodeApi;
+
+const messenger = new Messenger(acquireVsCodeApi());
+const port = new WebviewDataPort(createWebviewSideChannel(messenger, HOST_EXTENSION));
+messenger.start();
+const connection = new DataConnectionWithEvents(port);
+```
+
+To test a webview's data path in Node, `makeMessengerHarness` from `./testing`
+joins the real extension-side and webview-side messengers through a fake
+panel and a fake `window`, so the test runs their real routing.
+
+For the whole setup, see *Host in VS Code* in
+[Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
+
+## Entry points
+
+| Subpath     | Use it for                                    | Runs in                    |
+| ----------- | --------------------------------------------- | -------------------------- |
+| `.`         | The messenger channel both ends build on      | anywhere                   |
+| `./node`    | The relay from the data-server's socket       | the VS Code extension host |
+| `./browser` | The webview's data port                       | a webview                  |
+| `./testing` | The real messenger pair joined in a Node test | a test                     |
+
+The subpaths need a TypeScript `moduleResolution` that reads `exports`
+(`NodeNext` or `Bundler`); see *Requirements* in
+[Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
+
+## Status
+
+Alpha: every release is a prerelease that may break the API, so pin an exact
+version. Guides and known limitations:
+[Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
+
+## License
+
+`MIT` — see this package's [`LICENSE`](./LICENSE), and the repository
+[`NOTICE.md`](https://github.com/eclipse-emfcloud/hydranium/blob/main/NOTICE.md)
+for third-party notices.

package/lib/browser/index.d.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+export * from './webview-data-port';
+//# sourceMappingURL=index.d.ts.map

package/lib/browser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,qBAAqB,CAAC"}

package/lib/browser/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./webview-data-port"), exports);
+//# sourceMappingURL=index.js.map

package/lib/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,sDAAoC"}

package/lib/browser/webview-data-port.d.ts

@@ -0,0 +1,64 @@
+/********************************************************************************
+ * 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 { type DataPort, type Logger, type PostMessageChannel, type ResolvedMessage } from '@hydranium/protocol';
+import { Emitter, type Event, type MessageConnection } from 'vscode-jsonrpc';
+/** Options for {@link WebviewDataPort}. */
+export interface WebviewDataPortOptions {
+    /**
+     * Surface a data-head failure. Without one it goes to the webview's console;
+     * a webview whose extension shows notifications forwards it there instead.
+     */
+    readonly reportError?: (error: unknown, reported: ResolvedMessage) => void;
+    /** Where the connection logs its protocol faults, and what it does on its own. */
+    readonly logger?: Logger;
+}
+/**
+ * The webview's {@link DataPort}: the sandbox side of the data head, over the
+ * extension host's messenger hop.
+ *
+ * `vscode-jsonrpc/browser`, not the package root, which installs no runtime
+ * abstraction layer and throws on the first message rather than at wire-up.
+ */
+export declare class WebviewDataPort implements DataPort {
+    protected readonly channel: PostMessageChannel;
+    protected readonly options: WebviewDataPortOptions;
+    protected readonly disposeEmitter: Emitter<void>;
+    readonly onDispose: Event<void>;
+    readonly logger?: Logger;
+    protected disposed: boolean;
+    /** The connection every generation gets until it is disposed. */
+    protected connection?: MessageConnection;
+    constructor(channel: PostMessageChannel, options?: WebviewDataPortOptions);
+    /**
+     * Hand back a listening connection over the hop: the same one until it is
+     * disposed, and then a fresh transport, so a disposed connection leaves no
+     * second reader on the pipe.
+     *
+     * Every connection reaches the one relay behind the pipe, and each numbers
+     * its requests from zero, so a second live one would take answers meant for
+     * the first. A retry after a failed readiness check therefore gets the
+     * connection the check used.
+     */
+    connect(): Promise<MessageConnection>;
+    reportError(error: unknown, reported: ResolvedMessage): void;
+    /**
+     * The extension host reports the relay's framed side died.
+     *
+     * A `PostMessageChannel` has no `close()`, so the pipe still looks open from
+     * here: firing `onDispose` makes `DataConnection` drop its generation, and
+     * disposing the connection rejects everything in flight, also when no
+     * generation holds it. The connection is forgotten before the event, so a
+     * listener that connects gets a fresh one rather than the one about to be
+     * disposed.
+     */
+    connectionLost(): void;
+    /** Refuses to connect afterwards: the consumer's reconnect would otherwise open a reader nothing releases. */
+    dispose(): void;
+}
+//# sourceMappingURL=webview-data-port.d.ts.map

package/lib/browser/webview-data-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webview-data-port.d.ts","sourceRoot":"","sources":["../../src/browser/webview-data-port.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAGJ,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAG7E,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACpC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,KAAK,IAAI,CAAC;IAC3E,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,YAAW,QAAQ;IAS1C,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,kBAAkB;IAC9C,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,sBAAsB;IATrD,SAAS,CAAC,QAAQ,CAAC,cAAc,gBAAuB;IACxD,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,CAA6B;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,QAAQ,UAAS;IAC3B,iEAAiE;IACjE,SAAS,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAEzC,YACsB,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,sBAA2B,EAGzD;IAED;;;;;;;;;OASG;IACG,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAiB1C;IAED,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAM3D;IAED;;;;;;;;;OASG;IACH,cAAc,IAAI,IAAI,CAKrB;IAED,8GAA8G;IAC9G,OAAO,IAAI,IAAI,CAKd;CACH"}

package/lib/browser/webview-data-port.js

@@ -0,0 +1,97 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebviewDataPort = void 0;
+const protocol_1 = require("@hydranium/protocol");
+const vscode_jsonrpc_1 = require("vscode-jsonrpc");
+const browser_1 = require("vscode-jsonrpc/browser");
+/**
+ * The webview's {@link DataPort}: the sandbox side of the data head, over the
+ * extension host's messenger hop.
+ *
+ * `vscode-jsonrpc/browser`, not the package root, which installs no runtime
+ * abstraction layer and throws on the first message rather than at wire-up.
+ */
+class WebviewDataPort {
+    channel;
+    options;
+    disposeEmitter = new vscode_jsonrpc_1.Emitter();
+    onDispose = this.disposeEmitter.event;
+    logger;
+    disposed = false;
+    /** The connection every generation gets until it is disposed. */
+    connection;
+    constructor(channel, options = {}) {
+        this.channel = channel;
+        this.options = options;
+        this.logger = options.logger;
+    }
+    /**
+     * Hand back a listening connection over the hop: the same one until it is
+     * disposed, and then a fresh transport, so a disposed connection leaves no
+     * second reader on the pipe.
+     *
+     * Every connection reaches the one relay behind the pipe, and each numbers
+     * its requests from zero, so a second live one would take answers meant for
+     * the first. A retry after a failed readiness check therefore gets the
+     * connection the check used.
+     */
+    async connect() {
+        if (this.disposed) {
+            throw new Error('WebviewDataPort: the port is disposed');
+        }
+        if (!this.connection) {
+            const transport = (0, protocol_1.createPostMessageTransport)(this.channel);
+            const connection = (0, browser_1.createMessageConnection)(transport.reader, transport.writer, this.logger);
+            connection.onDispose(() => {
+                transport.dispose();
+                if (this.connection === connection) {
+                    this.connection = undefined;
+                }
+            });
+            connection.listen();
+            this.connection = connection;
+        }
+        return this.connection;
+    }
+    reportError(error, reported) {
+        if (this.options.reportError) {
+            this.options.reportError(error, reported);
+        }
+        else {
+            console.error(`[data head] ${(0, protocol_1.renderFrameworkMessage)(reported)}`, error);
+        }
+    }
+    /**
+     * The extension host reports the relay's framed side died.
+     *
+     * A `PostMessageChannel` has no `close()`, so the pipe still looks open from
+     * here: firing `onDispose` makes `DataConnection` drop its generation, and
+     * disposing the connection rejects everything in flight, also when no
+     * generation holds it. The connection is forgotten before the event, so a
+     * listener that connects gets a fresh one rather than the one about to be
+     * disposed.
+     */
+    connectionLost() {
+        const lost = this.connection;
+        this.connection = undefined;
+        this.disposeEmitter.fire();
+        lost?.dispose();
+    }
+    /** Refuses to connect afterwards: the consumer's reconnect would otherwise open a reader nothing releases. */
+    dispose() {
+        this.disposed = true;
+        this.disposeEmitter.fire();
+        this.disposeEmitter.dispose();
+        this.connection?.dispose();
+    }
+}
+exports.WebviewDataPort = WebviewDataPort;
+//# sourceMappingURL=webview-data-port.js.map

package/lib/browser/webview-data-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webview-data-port.js","sourceRoot":"","sources":["../../src/browser/webview-data-port.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF,kDAO6B;AAC7B,mDAA6E;AAC7E,oDAAiE;AAajE;;;;;;GAMG;AACH;IASyB,OAAO;IACP,OAAO;IATV,cAAc,GAAG,IAAI,wBAAO,EAAQ,CAAC;IAC/C,SAAS,GAAgB,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC;IACnD,MAAM,CAAU;IACf,QAAQ,GAAG,KAAK,CAAC;IAC3B,iEAAiE;IACvD,UAAU,CAAqB;IAEzC,YACsB,OAA2B,EAC3B,OAAO,GAA2B,EAAE;uBADpC,OAAO;uBACP,OAAO;QAE1B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAChC,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO;QACV,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC5D,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,MAAM,SAAS,GAAG,IAAA,qCAA0B,EAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC3D,MAAM,UAAU,GAAG,IAAA,iCAAuB,EAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YAC5F,UAAU,CAAC,SAAS,CAAC,GAAG,EAAE;gBACvB,SAAS,CAAC,OAAO,EAAE,CAAC;gBACpB,IAAI,IAAI,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;oBAClC,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;gBAC/B,CAAC;YACJ,CAAC,CAAC,CAAC;YACH,UAAU,CAAC,MAAM,EAAE,CAAC;YACpB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAChC,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC;IAC1B,CAAC;IAED,WAAW,CAAC,KAAc,EAAE,QAAyB;QAClD,IAAI,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;YAC5B,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAC7C,CAAC;aAAM,CAAC;YACL,OAAO,CAAC,KAAK,CAAC,eAAe,IAAA,iCAAsB,EAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;QAC3E,CAAC;IACJ,CAAC;IAED;;;;;;;;;OASG;IACH,cAAc;QACX,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;QAC3B,IAAI,EAAE,OAAO,EAAE,CAAC;IACnB,CAAC;IAED,8GAA8G;IAC9G,OAAO;QACJ,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;QAC3B,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,CAAC;QAC9B,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC;IAC9B,CAAC;CACH"}

package/lib/index.d.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+export * from './messenger-channel';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAKlF,cAAc,qBAAqB,CAAC"}

package/lib/index.js

@@ -0,0 +1,29 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Neutral: the messenger channel both ends of the hop build on, free of
+// `vscode`, Node and the DOM. The extension host's end is `./node`, the
+// webview's `./browser`.
+__exportStar(require("./messenger-channel"), exports);
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,wEAAwE;AACxE,wEAAwE;AACxE,yBAAyB;AACzB,sDAAoC"}

package/lib/messenger-channel.d.ts

@@ -0,0 +1,155 @@
+/********************************************************************************
+ * 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 type { PostMessageChannel } from '@hydranium/protocol';
+import type { Disposable, Message } from 'vscode-jsonrpc';
+/**
+ * A notification type as `vscode-messenger` defines it: a method name, with the
+ * payload type carried only in the generic parameter.
+ *
+ * Restated rather than imported: `vscode-messenger-common`'s
+ * `NotificationType<P>` is `{ method: string }` with `P` phantom, and the import
+ * would pin the adopter's messenger copy, which GLSP's VS Code integration
+ * chooses.
+ */
+export interface NotificationTypeLike {
+    readonly method: string;
+}
+/**
+ * The one method both ends of the hop share: hand a message to a participant.
+ *
+ * `TParticipant` stays generic because the two ends address different things,
+ * the extension side a registered webview and the webview side
+ * `HOST_EXTENSION`.
+ */
+export interface MessengerSendLike<TParticipant> {
+    sendNotification(type: NotificationTypeLike, receiver: TParticipant, params?: Message): void;
+}
+/**
+ * The two methods the channel needs from the **extension-side** messenger.
+ *
+ * Two methods rather than the class, so any messenger with them fits, GLSP's
+ * included, without pinning a `vscode-messenger` copy.
+ */
+export interface MessengerLike<TParticipant> extends MessengerSendLike<TParticipant> {
+    onNotification(type: NotificationTypeLike, handler: (params: Message, sender: TParticipant) => void, options?: {
+        sender?: TParticipant;
+    }): Disposable;
+}
+/**
+ * The **webview-side** messenger, which differs from the extension side in
+ * every point the channel depends on:
+ *
+ * - **`onNotification` returns the messenger itself**, not a `Disposable`, and
+ *   there is no unregister API, so a registration lasts as long as the webview.
+ *   {@link createMessengerChannel} therefore stops delivering through a flag.
+ * - **There is no `sender` option**: a webview has one peer.
+ * - **`start()` must be called** before anything arrives, since it attaches the
+ *   `window` listener. It is absent here because the channel does not call it;
+ *   the webview's bootstrap does.
+ *
+ * A separate interface rather than a wider {@link MessengerLike}: one shape for
+ * both ends would promise a webview an unregisterable handler and a sender
+ * filter it cannot honour.
+ */
+export interface WebviewMessengerLike<TParticipant> extends MessengerSendLike<TParticipant> {
+    onNotification(type: NotificationTypeLike, handler: (params: Message, sender: TParticipant) => void): unknown;
+}
+/**
+ * The data head's two notification types, one per direction.
+ *
+ * `vscode-messenger` addresses a notification to its receiver, so one method
+ * for both directions would also deliver correctly. Two keep the direction
+ * readable on the wire and in a messenger trace, and keep a delivery that
+ * routes by method alone, such as `BROADCAST`, from reaching the sender's own
+ * handler.
+ */
+export declare const DATA_TO_WEBVIEW: NotificationTypeLike;
+export declare const DATA_TO_EXTENSION: NotificationTypeLike;
+/**
+ * Options for {@link createMessengerChannel}.
+ *
+ * Generic over the registration type as well as the participant, because the two
+ * sides disagree on what `onNotification` hands back: a `Disposable` on the
+ * extension side, the messenger itself on the webview side. The type parameter
+ * keeps {@link releaseRegistration} typed; probing an `unknown` for a `dispose`
+ * method would dispose the whole webview messenger if it ever gained one.
+ */
+export interface MessengerChannelOptions<TParticipant, TRegistration> {
+    readonly messenger: {
+        sendNotification(type: NotificationTypeLike, receiver: TParticipant, params?: Message): void;
+        onNotification(type: NotificationTypeLike, handler: (params: Message, sender: TParticipant) => void, options?: {
+            sender?: TParticipant;
+        }): TRegistration;
+    };
+    /** Where this side's outbound messages are addressed. */
+    readonly receiver: TParticipant;
+    /** The notification type this side SENDS on. */
+    readonly outbound: NotificationTypeLike;
+    /** The notification type this side LISTENS on. */
+    readonly inbound: NotificationTypeLike;
+    /**
+     * Accept inbound notifications only from this participant. Supply it
+     * whenever the messenger is shared, as GLSP's is with every diagram
+     * webview, so a second webview cannot inject traffic into this connection.
+     *
+     * Extension side only: the webview-side messenger ignores it.
+     */
+    readonly sender?: TParticipant;
+    /**
+     * Observe the hop going away, the webview being disposed. Passed through to
+     * {@link PostMessageChannel.onClose}, whose reader and writer use it to fire
+     * their own close.
+     */
+    readonly onClose?: (listener: () => void) => Disposable;
+    /**
+     * Release what `onNotification` returned, where the messenger hands back
+     * something releasable: on the extension side, whose registrations would
+     * otherwise accumulate on a hop that outlives every webview on it.
+     */
+    readonly releaseRegistration?: (registration: TRegistration) => void;
+}
+/**
+ * Present a messenger as a {@link PostMessageChannel}, so the data head's
+ * transport rides a host's existing notification hop.
+ *
+ * `createPostMessageTransport` turns the channel into a reader and writer,
+ * `relayToPostMessageChannel` pumps the extension host's socket onto it from
+ * the other side, and everything above, `createRpcProxy` and `DataSession`
+ * included, is host-invariant. Sharing GLSP's `Messenger` rather than opening a
+ * second hop gives a diagram and a data webview one lifecycle and one dispose.
+ *
+ * **`onMessage`'s `Disposable` means "stop delivering", not necessarily
+ * "unregister".** The webview-side messenger cannot unregister, so a flag keeps
+ * the promise on both sides. Where unregistering is possible,
+ * {@link MessengerChannelOptions.releaseRegistration} does it too, or every
+ * disposed webview would leave a handler on a shared hop.
+ */
+export declare function createMessengerChannel<TParticipant, TRegistration>(options: MessengerChannelOptions<TParticipant, TRegistration>): PostMessageChannel;
+/**
+ * The extension host's end: posts toward the webview, listens for what the
+ * webview sends.
+ */
+export declare function createExtensionSideChannel<TParticipant>(messenger: MessengerLike<TParticipant>, webview: TParticipant, onClose?: (listener: () => void) => Disposable): PostMessageChannel;
+/**
+ * The webview's end: the mirror image, addressed at the extension host.
+ *
+ * Two preconditions the webview's bootstrap owns, both of which present as "no
+ * data ever arrives" when missed:
+ *
+ * - **Read the channel through `WebviewDataPort`**, or build its connection
+ *   with `createMessageConnection` from `vscode-jsonrpc/browser`: the package
+ *   root installs no runtime abstraction layer and throws on the first
+ *   message.
+ * - **Call the messenger's own `start()`**, which attaches the `window`
+ *   listener.
+ *
+ * No `sender` filter: a webview has one peer.
+ */
+export declare function createWebviewSideChannel<TParticipant>(messenger: WebviewMessengerLike<TParticipant>, hostExtension: TParticipant, onClose?: (listener: () => void) => Disposable): PostMessageChannel;
+//# sourceMappingURL=messenger-channel.d.ts.map

package/lib/messenger-channel.d.ts.map

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