@hydranium/client-browser 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,102 @@
-# Temporary Holding Version
+# `@hydranium/client-browser`
 
-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 page side of a [Hydranium](https://github.com/eclipse-emfcloud/hydranium)
+host that runs its heads in a web worker, with no backend. Install it when
+your language runs in a plain web page: it hands each head its own
+`MessagePort`, runs the page's LSP handshake, and gives the data head its port.
+
+## What it gives you
+
+- One `MessagePort` per head, transferred to the worker in the framework's
+  bootstrap message, so no head is ever bound to the worker's global scope.
+- The LSP head's connection with the server's own requests answered: the
+  capability registrations and the configuration section it reads while the
+  workspace comes up.
+- A `DataPort` over the data head's port, for the connection and sessions from
+  `@hydranium/protocol`.
+- The GLSP head's connection, for GLSP's own client.
+- Pending requests rejected when the worker fails to start or fails its
+  bootstrap, instead of waiting forever, since a port cannot report a dead
+  peer.
+
+## Install
+
+```bash
+npm install @hydranium/client-browser
+```
+
+| Peer                             | Range         |
+| -------------------------------- | ------------- |
+| `@hydranium/protocol`            | `^1.0.0-next` |
+| `vscode-jsonrpc`                 | `^9.0.0`      |
+| `vscode-languageserver-protocol` | `~3.18.1`     |
+
+## Wiring
+
+Build the `Worker` yourself, from a URL your build gives you, and hand it to
+`connectWorkerHeads`. Run the LSP handshake on the LSP head's connection before
+anything else uses it, and give the data head's port to a data connection:
+
+<!-- snippet-preamble
+import { connectWorkerHeads } from '@hydranium/client-browser';
+// The page's `Worker`, which has no name under this gate's DOM-free lib.
+declare const worker: Parameters<typeof connectWorkerHeads>[0];
+-->
+
+```ts
+import { initializeLanguageClient } from '@hydranium/client-browser';
+import { DataConnectionWithEvents } from '@hydranium/protocol';
+
+const heads = connectWorkerHeads(worker);
+heads.onWorkerError(report => console.error(`worker, ${report.phase}: ${report.message}`));
+const { capabilities } = await initializeLanguageClient(heads.lsp, {
+   rootUri: 'file:///workspace',
+   configuration: { section: 'my-language', settings: () => ({ log: { level: 'info' } }) }
+});
+const data = new DataConnectionWithEvents(heads.data);
+```
+
+In the worker, read the bootstrap with `isWorkerBootstrapMessage` from
+`@hydranium/protocol` and start each head on its port, never on the worker's
+global scope. Post a `WorkerErrorMessage` for a failure you catch there; one
+under `WORKER_BOOTSTRAP_PHASE` ends the page's heads, any other phase only
+reports.
+
+Register the handler for the server's diagnostics in `beforeInitialized`,
+which runs once `initialize` has answered and before `initialized` goes out.
+A second handler for the same notification replaces the first, so fan out
+from one.
+
+The data port reports a data-head failure to the console. A host with a
+surface of its own subclasses `WorkerDataPort` and passes it as
+`createDataPort`.
+
+The default capabilities declare `workspace.applyEdit`, which the handshake
+does not answer: register a `workspace/applyEdit` handler on the connection
+before you open a document, as any LSP client does, or the server's writes
+to that document are lost.
+
+For the whole setup, see *Host in a browser* in
+[Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
+
+## Entry points
+
+| Subpath | Use it for                                                | Runs in    |
+| ------- | --------------------------------------------------------- | ---------- |
+| `.`     | The worker bootstrap, the LSP handshake and the data port | a web page |
+
+The package needs 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/index.d.ts

@@ -0,0 +1,12 @@
+/********************************************************************************
+ * 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 './worker-heads';
+export * from './language-client';
+export * from './worker-data-port';
+//# 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;AAElF,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}

package/lib/index.js

@@ -0,0 +1,28 @@
+"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("./worker-heads"), exports);
+__exportStar(require("./language-client"), exports);
+__exportStar(require("./worker-data-port"), 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,iDAA+B;AAC/B,oDAAkC;AAClC,qDAAmC"}

package/lib/language-client.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 { Locale } from '@hydranium/protocol';
+import type { MessageConnection } from 'vscode-jsonrpc/browser';
+import { type ClientCapabilities, type InitializeResult, type LogMessageParams } from 'vscode-languageserver-protocol';
+/** The one configuration section the server reads, and what it reads there. */
+export interface LanguageClientConfiguration {
+    /** The server's `lsp.configurationRoot`. A mismatch leaves every answer `null`, so the setting reads as unset. */
+    readonly section: string;
+    /** The section's whole subtree. The server replaces its cached section with what it is given, so a partial answer deletes the siblings it omits. */
+    settings(): unknown;
+}
+export interface LanguageClientOptions {
+    /** The workspace root, a URI, which is also the one workspace folder. */
+    readonly rootUri: string;
+    /** The folder's name, the root's last path segment by default. */
+    readonly workspaceName?: string;
+    /** The reading user's language, which only the page knows. Absent means the framework's English. */
+    readonly locale?: Locale;
+    /**
+     * The client's capabilities, `workspace.applyEdit` and
+     * `workspace.configuration` by default. `configuration` gates its request:
+     * absent, the server asks for no section ever. `applyEdit` does not: the
+     * server sends `workspace/applyEdit` to any client with the document open,
+     * and a client with no handler answers it as an unknown method, which loses
+     * the whole inbound direction. Declaring less than the handlers the host
+     * registers is the one safe direction; declaring more produces answers it
+     * cannot render.
+     */
+    readonly capabilities?: ClientCapabilities;
+    /** Answered from the start, since the server reads it while the workspace comes up. */
+    readonly configuration?: LanguageClientConfiguration;
+    /** The server's log, every head of it; a page with no handler loses it. Registered before `listen`, so the first build's lines arrive too. */
+    readonly onLogMessage?: (params: LogMessageParams) => void;
+    /**
+     * Called with the server's answer before `initialized` is sent: the window
+     * in which a handler for the server's first notifications is registered
+     * once the answer it needs is known. The server publishes nothing before
+     * `initialized`, so nothing is missed.
+     */
+    readonly beforeInitialized?: (result: InitializeResult) => void;
+}
+/**
+ * Run the page's end of the LSP handshake on `connection`, which must not be
+ * listening yet, and resolve with the server's answer.
+ *
+ * Registers the answers to the server's own requests before `listen`, because
+ * each is asked while the workspace comes up and an unanswered one is a
+ * failure the page sees as an error and the server as a client with no
+ * settings: capability registrations are acknowledged and kept nowhere, and a
+ * configuration request is answered item by item, since the response is
+ * positional and a dropped item mis-aligns every later answer. These
+ * registrations replace any the host made before the call, since a
+ * connection keeps one handler per method; a host serving more than one
+ * section registers its own configuration handler in `beforeInitialized`.
+ */
+export declare function initializeLanguageClient(connection: MessageConnection, options: LanguageClientOptions): Promise<InitializeResult>;
+//# sourceMappingURL=language-client.d.ts.map

package/lib/language-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language-client.d.ts","sourceRoot":"","sources":["../src/language-client.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAOJ,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACvB,MAAM,gCAAgC,CAAC;AAExC,+EAA+E;AAC/E,MAAM,WAAW,2BAA2B;IACzC,kHAAkH;IAClH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oJAAoJ;IACpJ,QAAQ,IAAI,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB;IACnC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,oGAAoG;IACpG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAC3C,uFAAuF;IACvF,QAAQ,CAAC,aAAa,CAAC,EAAE,2BAA2B,CAAC;IACrD,8IAA8I;IAC9I,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC3D;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAClE;AAKD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,wBAAwB,CAAC,UAAU,EAAE,iBAAiB,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAyBvI"}

package/lib/language-client.js

@@ -0,0 +1,56 @@
+"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.initializeLanguageClient = initializeLanguageClient;
+const vscode_languageserver_protocol_1 = require("vscode-languageserver-protocol");
+/** The capabilities the server's inbound requests rely on, declared unless the host declares its own. */
+const DEFAULT_CAPABILITIES = { workspace: { applyEdit: true, configuration: true } };
+/**
+ * Run the page's end of the LSP handshake on `connection`, which must not be
+ * listening yet, and resolve with the server's answer.
+ *
+ * Registers the answers to the server's own requests before `listen`, because
+ * each is asked while the workspace comes up and an unanswered one is a
+ * failure the page sees as an error and the server as a client with no
+ * settings: capability registrations are acknowledged and kept nowhere, and a
+ * configuration request is answered item by item, since the response is
+ * positional and a dropped item mis-aligns every later answer. These
+ * registrations replace any the host made before the call, since a
+ * connection keeps one handler per method; a host serving more than one
+ * section registers its own configuration handler in `beforeInitialized`.
+ */
+async function initializeLanguageClient(connection, options) {
+    // Before `listen`: a root that is no URI throws here, and a connection left
+    // listening with no `initialize` sent would be one the host cannot reuse.
+    const workspaceName = options.workspaceName ?? workspaceNameOf(options.rootUri);
+    connection.onRequest(vscode_languageserver_protocol_1.RegistrationRequest.type, () => undefined);
+    connection.onRequest(vscode_languageserver_protocol_1.UnregistrationRequest.type, () => undefined);
+    const configuration = options.configuration;
+    connection.onRequest(vscode_languageserver_protocol_1.ConfigurationRequest.type, params => params.items.map(item => (configuration !== undefined && item.section === configuration.section ? configuration.settings() : null)));
+    if (options.onLogMessage) {
+        connection.onNotification(vscode_languageserver_protocol_1.LogMessageNotification.type, options.onLogMessage);
+    }
+    connection.listen();
+    const result = await connection.sendRequest(vscode_languageserver_protocol_1.InitializeRequest.type, {
+        processId: null,
+        rootUri: options.rootUri,
+        locale: options.locale,
+        capabilities: options.capabilities ?? DEFAULT_CAPABILITIES,
+        workspaceFolders: [{ uri: options.rootUri, name: workspaceName }]
+    });
+    options.beforeInitialized?.(result);
+    await connection.sendNotification(vscode_languageserver_protocol_1.InitializedNotification.type, {});
+    return result;
+}
+/** The root's last path segment, decoded, or the root itself for one with no path. */
+function workspaceNameOf(rootUri) {
+    return decodeURIComponent(new URL(rootUri).pathname.replace(/\/+$/, '').split('/').pop() ?? '') || rootUri;
+}
+//# sourceMappingURL=language-client.js.map

package/lib/language-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"language-client.js","sourceRoot":"","sources":["../src/language-client.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAIlF,mFAUwC;AAyCxC,yGAAyG;AACzG,MAAM,oBAAoB,GAAuB,EAAE,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE,CAAC;AAEzG;;;;;;;;;;;;;GAaG;AACI,KAAK,mCAAmC,UAA6B,EAAE,OAA8B;IACzG,4EAA4E;IAC5E,0EAA0E;IAC1E,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,eAAe,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAChF,UAAU,CAAC,SAAS,CAAC,oDAAmB,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAChE,UAAU,CAAC,SAAS,CAAC,sDAAqB,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAClE,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAC5C,UAAU,CAAC,SAAS,CAAC,qDAAoB,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CACtD,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,aAAa,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,KAAK,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CACrI,CAAC;IACF,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACxB,UAAU,CAAC,cAAc,CAAC,uDAAsB,CAAC,IAAI,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAChF,CAAC;IACD,UAAU,CAAC,MAAM,EAAE,CAAC;IAEpB,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,WAAW,CAAC,kDAAiB,CAAC,IAAI,EAAE;QACjE,SAAS,EAAE,IAAI;QACf,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,oBAAoB;QAC1D,gBAAgB,EAAE,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;KACnE,CAAC,CAAC;IACH,OAAO,CAAC,iBAAiB,EAAE,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,UAAU,CAAC,gBAAgB,CAAC,wDAAuB,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACpE,OAAO,MAAM,CAAC;AACjB,CAAC;AAED,sFAAsF;AACtF,SAAS,eAAe,CAAC,OAAe;IACrC,OAAO,kBAAkB,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,IAAI,OAAO,CAAC;AAC9G,CAAC"}

package/lib/worker-data-port.d.ts

@@ -0,0 +1,71 @@
+/********************************************************************************
+ * 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 ResolvedMessage, type TransferredMessagePort } from '@hydranium/protocol';
+import { Emitter, type MessageConnection } from 'vscode-jsonrpc/browser';
+/**
+ * The host half of the data head for a page talking to a worker.
+ *
+ * This is the whole of what a browser host has to supply to reach the data
+ * head; everything above it (the open/watch order, `baseVersion` conflict
+ * handling, echo filtering by `sourceClientId`) is host-invariant and already
+ * in `DataConnection` and `DataSession`.
+ *
+ * `vscode-jsonrpc/browser`, never the package root: version 9's root entry ships
+ * no runtime abstraction layer and throws on the first message rather than at
+ * import, so the mistake surfaces as a dead connection rather than a stack
+ * trace.
+ */
+export declare class WorkerDataPort implements DataPort {
+    /** The page's end of the data head's port, typed as the handshake types it. */
+    protected readonly port: TransferredMessagePort;
+    /** Where the connection logs its protocol faults, and what it does on its own. */
+    readonly logger?: Logger | undefined;
+    protected readonly disposeEmitter: Emitter<void>;
+    readonly onDispose: import("vscode-jsonrpc/browser").Event<void>;
+    protected disposed: boolean;
+    protected connection?: MessageConnection;
+    constructor(
+    /** The page's end of the data head's port, typed as the handshake types it. */
+    port: TransferredMessagePort, 
+    /** Where the connection logs its protocol faults, and what it does on its own. */
+    logger?: Logger | undefined);
+    /**
+     * The transport is the port the worker was already handed at bootstrap, so
+     * there is nothing to open, but the connection must be `listen()`ing before
+     * it is returned, because the RPC proxy queues calls on this promise and
+     * never listens itself.
+     *
+     * Both ends use `createMessagePortTransport`; see it for why.
+     *
+     * Every generation gets the same connection. A fresh one per generation
+     * would leave the one a failed readiness check used still reading the port,
+     * and disposing that one is no way out: disposing any connection over the
+     * port ends the worker's head, and the retry would wait for an answer that
+     * never comes.
+     *
+     * **Rejects once this port is disposed, and a disposed port cannot be
+     * reused.** Its dispose disposes the connection, which signals the close to
+     * the worker, whose end of the port then stays closed: a later connection
+     * over it would send requests nothing answers, and hang.
+     */
+    connect(): Promise<MessageConnection>;
+    /**
+     * To the console: a page has no notification surface of its own, and an
+     * unreported data-head error presents as an empty model, which reads as a
+     * valid document. A host with a surface overrides this.
+     *
+     * No translation map: omitting the argument takes the English. The raw
+     * error goes alongside rather than into the sentence, because `reported`
+     * already carries the detail and only the throw carries a stack.
+     */
+    reportError(error: unknown, reported: ResolvedMessage): void;
+    /** The consumer hears it first; the connection goes even when no generation holds it, as after a failed readiness check. */
+    dispose(): void;
+}
+//# sourceMappingURL=worker-data-port.d.ts.map

package/lib/worker-data-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-data-port.d.ts","sourceRoot":"","sources":["../src/worker-data-port.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAGJ,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC7B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAA2B,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAElG;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAe,YAAW,QAAQ;IAOzC,+EAA+E;IAC/E,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,sBAAsB;IAC/C,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;IAT3B,SAAS,CAAC,QAAQ,CAAC,cAAc,gBAAuB;IACxD,QAAQ,CAAC,SAAS,+CAA6B;IAC/C,SAAS,CAAC,QAAQ,UAAS;IAC3B,SAAS,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAEzC;IACG,+EAA+E;IAC5D,IAAI,EAAE,sBAAsB;IAC/C,kFAAkF;IACzE,MAAM,CAAC,EAAE,MAAM,YAAA,EACvB;IAEJ;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAUpC;IAED;;;;;;;;OAQG;IACH,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAE3D;IAED,4HAA4H;IAC5H,OAAO,IAAI,IAAI,CAKd;CACH"}

package/lib/worker-data-port.js

@@ -0,0 +1,93 @@
+"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.WorkerDataPort = void 0;
+const protocol_1 = require("@hydranium/protocol");
+const browser_1 = require("vscode-jsonrpc/browser");
+/**
+ * The host half of the data head for a page talking to a worker.
+ *
+ * This is the whole of what a browser host has to supply to reach the data
+ * head; everything above it (the open/watch order, `baseVersion` conflict
+ * handling, echo filtering by `sourceClientId`) is host-invariant and already
+ * in `DataConnection` and `DataSession`.
+ *
+ * `vscode-jsonrpc/browser`, never the package root: version 9's root entry ships
+ * no runtime abstraction layer and throws on the first message rather than at
+ * import, so the mistake surfaces as a dead connection rather than a stack
+ * trace.
+ */
+class WorkerDataPort {
+    port;
+    logger;
+    disposeEmitter = new browser_1.Emitter();
+    onDispose = this.disposeEmitter.event;
+    disposed = false;
+    connection;
+    constructor(
+    /** The page's end of the data head's port, typed as the handshake types it. */
+    port, 
+    /** Where the connection logs its protocol faults, and what it does on its own. */
+    logger) {
+        this.port = port;
+        this.logger = logger;
+    }
+    /**
+     * The transport is the port the worker was already handed at bootstrap, so
+     * there is nothing to open, but the connection must be `listen()`ing before
+     * it is returned, because the RPC proxy queues calls on this promise and
+     * never listens itself.
+     *
+     * Both ends use `createMessagePortTransport`; see it for why.
+     *
+     * Every generation gets the same connection. A fresh one per generation
+     * would leave the one a failed readiness check used still reading the port,
+     * and disposing that one is no way out: disposing any connection over the
+     * port ends the worker's head, and the retry would wait for an answer that
+     * never comes.
+     *
+     * **Rejects once this port is disposed, and a disposed port cannot be
+     * reused.** Its dispose disposes the connection, which signals the close to
+     * the worker, whose end of the port then stays closed: a later connection
+     * over it would send requests nothing answers, and hang.
+     */
+    connect() {
+        if (this.disposed) {
+            return Promise.reject(new Error('WorkerDataPort: the port is disposed, and the data head behind it has ended'));
+        }
+        if (!this.connection) {
+            const transport = (0, protocol_1.createMessagePortTransport)(this.port);
+            this.connection = (0, browser_1.createMessageConnection)(transport.reader, transport.writer, this.logger);
+            this.connection.listen();
+        }
+        return Promise.resolve(this.connection);
+    }
+    /**
+     * To the console: a page has no notification surface of its own, and an
+     * unreported data-head error presents as an empty model, which reads as a
+     * valid document. A host with a surface overrides this.
+     *
+     * No translation map: omitting the argument takes the English. The raw
+     * error goes alongside rather than into the sentence, because `reported`
+     * already carries the detail and only the throw carries a stack.
+     */
+    reportError(error, reported) {
+        console.error(`[data head] ${(0, protocol_1.renderFrameworkMessage)(reported)}`, error);
+    }
+    /** The consumer hears it first; the connection goes even when no generation holds it, as after a failed readiness check. */
+    dispose() {
+        this.disposed = true;
+        this.disposeEmitter.fire();
+        this.disposeEmitter.dispose();
+        this.connection?.dispose();
+    }
+}
+exports.WorkerDataPort = WorkerDataPort;
+//# sourceMappingURL=worker-data-port.js.map

package/lib/worker-data-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-data-port.js","sourceRoot":"","sources":["../src/worker-data-port.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF,kDAO6B;AAC7B,oDAAkG;AAElG;;;;;;;;;;;;GAYG;AACH;IAQyB,IAAI;IAEd,MAAM;IATC,cAAc,GAAG,IAAI,iBAAO,EAAQ,CAAC;IAC/C,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC;IACrC,QAAQ,GAAG,KAAK,CAAC;IACjB,UAAU,CAAqB;IAEzC;IACG,+EAA+E;IAC5D,IAA4B;IAC/C,kFAAkF;IACzE,MAAe;oBAFL,IAAI;sBAEd,MAAM;IACf,CAAC;IAEJ;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO;QACJ,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACjB,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,6EAA6E,CAAC,CAAC,CAAC;QACnH,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,MAAM,SAAS,GAAG,IAAA,qCAA0B,EAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACxD,IAAI,CAAC,UAAU,GAAG,IAAA,iCAAuB,EAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YAC3F,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC;QAC5B,CAAC;QACD,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;;;;OAQG;IACH,WAAW,CAAC,KAAc,EAAE,QAAyB;QAClD,OAAO,CAAC,KAAK,CAAC,eAAe,IAAA,iCAAsB,EAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAC3E,CAAC;IAED,4HAA4H;IAC5H,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/worker-heads.d.ts

@@ -0,0 +1,79 @@
+/********************************************************************************
+ * 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 TransferredMessagePort, type WorkerErrorMessage } from '@hydranium/protocol';
+import { type Disposable, type Event, type MessageConnection } from 'vscode-jsonrpc/browser';
+/** The phase a report synthesised from the `Worker`'s `error` event carries. */
+export declare const WORKER_ERROR_EVENT_PHASE = "worker";
+export interface WorkerHeadsOptions {
+    /** Where each head's connection logs its protocol faults, one component per head. Without one they log nothing. */
+    readonly logger?: Logger;
+    /**
+     * Build the data head's port over the page's end of its `MessagePort`, a
+     * {@link WorkerDataPort} by default. A host with a surface of its own for
+     * data-head failures supplies a subclass here.
+     */
+    readonly createDataPort?: (port: TransferredMessagePort, logger?: Logger) => DataPort & Disposable;
+}
+/** The page's end of each head, and what the worker says outside any head. */
+export interface WorkerHeads {
+    /**
+     * The LSP head's connection, not yet listening: register the handlers for
+     * the server's first requests, then `listen()` and send `initialize`. A
+     * message that arrives before `listen` is dropped.
+     */
+    readonly lsp: MessageConnection;
+    /** The data head's port, for a `DataConnection`. */
+    readonly data: DataPort;
+    /**
+     * The GLSP head's connection, not listening: GLSP's client calls `listen()`
+     * when it starts, and a second call throws. Its port is started, so a
+     * message arriving before then is dropped; the GLSP head posts nothing on
+     * its port before the client speaks. Hand it to that client wrapped with
+     * `sendByMethodName`, where the client's own connection type is named:
+     * GLSP's typed messages come from its own copy of `vscode-jsonrpc`, and
+     * this connection's copy rejects them unless they go by method name.
+     */
+    readonly glsp: MessageConnection;
+    /**
+     * Every failure the worker reports on its global, and its `error` event
+     * under {@link WORKER_ERROR_EVENT_PHASE}, before and after the heads have
+     * ended. Whether a report ended them is {@link onDispose}'s to say.
+     */
+    readonly onWorkerError: Event<WorkerErrorMessage>;
+    /**
+     * Fires once when the heads end: on a failed bootstrap, on an `error` event
+     * before the worker has posted on any head's port, or on {@link dispose}.
+     * What the heads had pending is rejected then rather than left waiting. Any
+     * later report, and an `error` event once the worker has posted, ends
+     * nothing: the worker runs on after an uncaught error, and the heads with
+     * it. Subscribe before the first `await`: the end fires once, and a
+     * subscriber after it hears nothing.
+     */
+    readonly onDispose: Event<void>;
+    /** End every head. A head whose connection exists signals its close to the worker, which ends the head there. */
+    dispose(): void;
+}
+/**
+ * Hand each head its own channel into `worker` and build the page's end of
+ * each.
+ *
+ * The worker keeps `port2` of every pair and the page `port1`; neither end is
+ * given the worker global, which carries the bootstrap, the worker's failure
+ * reports and whatever the host adds for itself. See the handshake in
+ * `@hydranium/protocol` for why a head on the global is unusable.
+ *
+ * **A port reports nothing when its peer dies**, so a worker that fails to
+ * load, throws before its bootstrap or fails it would leave every request on
+ * every head waiting forever, which looks exactly like a server still working.
+ * Those signals dispose the heads instead, and disposing a connection is what
+ * rejects its pending requests; a close alone does not. A worker that dies
+ * later still cannot be told from one that is working.
+ */
+export declare function connectWorkerHeads(worker: Worker, options?: WorkerHeadsOptions): WorkerHeads;
+//# sourceMappingURL=worker-heads.d.ts.map

package/lib/worker-heads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-heads.d.ts","sourceRoot":"","sources":["../src/worker-heads.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAMJ,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,sBAAsB,EAE3B,KAAK,kBAAkB,EACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAoC,KAAK,UAAU,EAAE,KAAK,KAAK,EAAE,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAG/H,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,WAAW,CAAC;AAEjD,MAAM,WAAW,kBAAkB;IAChC,mHAAmH;IACnH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,sBAAsB,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,QAAQ,GAAG,UAAU,CAAC;CACrG;AAED,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IACzB;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC;IAChC,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAClD;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAChC,iHAAiH;IACjH,OAAO,IAAI,IAAI,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAwEhG"}

package/lib/worker-heads.js

@@ -0,0 +1,102 @@
+"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.WORKER_ERROR_EVENT_PHASE = void 0;
+exports.connectWorkerHeads = connectWorkerHeads;
+const protocol_1 = require("@hydranium/protocol");
+const browser_1 = require("vscode-jsonrpc/browser");
+const worker_data_port_1 = require("./worker-data-port");
+/** The phase a report synthesised from the `Worker`'s `error` event carries. */
+exports.WORKER_ERROR_EVENT_PHASE = 'worker';
+/**
+ * Hand each head its own channel into `worker` and build the page's end of
+ * each.
+ *
+ * The worker keeps `port2` of every pair and the page `port1`; neither end is
+ * given the worker global, which carries the bootstrap, the worker's failure
+ * reports and whatever the host adds for itself. See the handshake in
+ * `@hydranium/protocol` for why a head on the global is unusable.
+ *
+ * **A port reports nothing when its peer dies**, so a worker that fails to
+ * load, throws before its bootstrap or fails it would leave every request on
+ * every head waiting forever, which looks exactly like a server still working.
+ * Those signals dispose the heads instead, and disposing a connection is what
+ * rejects its pending requests; a close alone does not. A worker that dies
+ * later still cannot be told from one that is working.
+ */
+function connectWorkerHeads(worker, options = {}) {
+    const lsp = new MessageChannel();
+    const data = new MessageChannel();
+    const glsp = new MessageChannel();
+    const bootstrap = {
+        type: protocol_1.WORKER_BOOTSTRAP_MESSAGE_TYPE,
+        ports: { lsp: lsp.port2, data: data.port2, glsp: glsp.port2 }
+    };
+    worker.postMessage(bootstrap, [lsp.port2, data.port2, glsp.port2]);
+    // Both ends use `createMessagePortTransport`; see it for why.
+    const lspTransport = (0, protocol_1.createMessagePortTransport)(lsp.port1);
+    const lspConnection = (0, browser_1.createMessageConnection)(lspTransport.reader, lspTransport.writer, options.logger?.with('LSP head'));
+    const dataLogger = options.logger?.with('data head');
+    const dataPort = options.createDataPort?.(data.port1, dataLogger) ?? new worker_data_port_1.WorkerDataPort(data.port1, dataLogger);
+    const glspTransport = (0, protocol_1.createMessagePortTransport)(glsp.port1);
+    const glspConnection = (0, browser_1.createMessageConnection)(glspTransport.reader, glspTransport.writer, options.logger?.with('GLSP head'));
+    const errorEmitter = new browser_1.Emitter();
+    const disposeEmitter = new browser_1.Emitter();
+    // Whether the worker has posted anything on a head's port, which only a
+    // worker past its bootstrap does. An `error` event before that is a worker
+    // that never started; one after it is an uncaught error the worker survives.
+    let workerPosted = false;
+    for (const port of [lsp.port1, data.port1, glsp.port1]) {
+        port.addEventListener('message', () => (workerPosted = true), { once: true });
+    }
+    let disposed = false;
+    const dispose = () => {
+        if (disposed) {
+            return;
+        }
+        disposed = true;
+        lspConnection.dispose();
+        dataPort.dispose();
+        glspConnection.dispose();
+        disposeEmitter.fire();
+        disposeEmitter.dispose();
+    };
+    // A worker that failed to load raises an event with no message, filename or
+    // line, indistinguishable from a crash on its first statement; the host
+    // adds the URL it tried.
+    worker.addEventListener('error', event => {
+        errorEmitter.fire({
+            type: protocol_1.WORKER_ERROR_MESSAGE_TYPE,
+            phase: exports.WORKER_ERROR_EVENT_PHASE,
+            message: event.message || 'no detail; check that the worker script loaded'
+        });
+        if (!workerPosted) {
+            dispose();
+        }
+    });
+    worker.addEventListener('message', event => {
+        if (!(0, protocol_1.isWorkerErrorMessage)(event.data)) {
+            return;
+        }
+        errorEmitter.fire(event.data);
+        if (event.data.phase === protocol_1.WORKER_BOOTSTRAP_PHASE) {
+            dispose();
+        }
+    });
+    return {
+        lsp: lspConnection,
+        data: dataPort,
+        glsp: glspConnection,
+        onWorkerError: errorEmitter.event,
+        onDispose: disposeEmitter.event,
+        dispose
+    };
+}
+//# sourceMappingURL=worker-heads.js.map

package/lib/worker-heads.js.map

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

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@hydranium/client-browser",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-next",
+  "description": "The page side of a hydranium host that runs its heads in a web worker: the worker bootstrap that hands each head its own MessagePort, the page's LSP handshake, the data head's port, and the rejection of what is pending when the worker dies.",
+  "keywords": [
+    "browser",
+    "hydranium",
+    "langium",
+    "language-server",
+    "lsp",
+    "web-worker"
+  ],
+  "homepage": "https://github.com/eclipse-emfcloud/hydranium/tree/main/packages/client-browser",
+  "bugs": {
+    "url": "https://github.com/eclipse-emfcloud/hydranium/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Hydranium Team"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eclipse-emfcloud/hydranium.git",
+    "directory": "packages/client-browser"
+  },
+  "files": [
+    "lib",
+    "src",
+    "!lib/**/*.tsbuildinfo"
+  ],
+  "sideEffects": false,
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rimraf lib tsconfig.tsbuildinfo",
+    "lint": "oxlint --format stylish --config ../../oxlint.config.cjs src test --max-warnings 0",
+    "prepack": "node -e \"const m=require('./package.json'),fs=require('node:fs');const missing=[m.main,...Object.values(m.bin||{})].filter(entry=>entry&&!fs.existsSync(entry));if(missing.length){console.error('prepack '+m.name+': not built ('+missing.join(', ')+' missing). Run the build before packing: a files entry that matches nothing is skipped silently, so the tarball would ship src only.');process.exit(1);}\"",
+    "test": "npm run typecheck:test && vitest run",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
+    "watch": "tsc -b -w --preserveWatchOutput"
+  },
+  "devDependencies": {
+    "@hydranium/protocol": "1.0.0-next",
+    "@types/node": "^22.0.0",
+    "rimraf": "^5.0.0",
+    "typescript": "^7.0.2",
+    "vscode-jsonrpc": "9.0.0",
+    "vscode-languageserver-protocol": "3.18.1"
+  },
+  "peerDependencies": {
+    "@hydranium/protocol": "^1.0.0-next",
+    "vscode-jsonrpc": "^9.0.0",
+    "vscode-languageserver-protocol": "~3.18.1"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "//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/index.ts

@@ -0,0 +1,12 @@
+/********************************************************************************
+ * 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 './worker-heads';
+export * from './language-client';
+export * from './worker-data-port';

package/src/language-client.ts

@@ -0,0 +1,110 @@
+/********************************************************************************
+ * 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 { Locale } from '@hydranium/protocol';
+import type { MessageConnection } from 'vscode-jsonrpc/browser';
+import {
+   ConfigurationRequest,
+   InitializedNotification,
+   InitializeRequest,
+   LogMessageNotification,
+   RegistrationRequest,
+   UnregistrationRequest,
+   type ClientCapabilities,
+   type InitializeResult,
+   type LogMessageParams
+} from 'vscode-languageserver-protocol';
+
+/** The one configuration section the server reads, and what it reads there. */
+export interface LanguageClientConfiguration {
+   /** The server's `lsp.configurationRoot`. A mismatch leaves every answer `null`, so the setting reads as unset. */
+   readonly section: string;
+   /** The section's whole subtree. The server replaces its cached section with what it is given, so a partial answer deletes the siblings it omits. */
+   settings(): unknown;
+}
+
+export interface LanguageClientOptions {
+   /** The workspace root, a URI, which is also the one workspace folder. */
+   readonly rootUri: string;
+   /** The folder's name, the root's last path segment by default. */
+   readonly workspaceName?: string;
+   /** The reading user's language, which only the page knows. Absent means the framework's English. */
+   readonly locale?: Locale;
+   /**
+    * The client's capabilities, `workspace.applyEdit` and
+    * `workspace.configuration` by default. `configuration` gates its request:
+    * absent, the server asks for no section ever. `applyEdit` does not: the
+    * server sends `workspace/applyEdit` to any client with the document open,
+    * and a client with no handler answers it as an unknown method, which loses
+    * the whole inbound direction. Declaring less than the handlers the host
+    * registers is the one safe direction; declaring more produces answers it
+    * cannot render.
+    */
+   readonly capabilities?: ClientCapabilities;
+   /** Answered from the start, since the server reads it while the workspace comes up. */
+   readonly configuration?: LanguageClientConfiguration;
+   /** The server's log, every head of it; a page with no handler loses it. Registered before `listen`, so the first build's lines arrive too. */
+   readonly onLogMessage?: (params: LogMessageParams) => void;
+   /**
+    * Called with the server's answer before `initialized` is sent: the window
+    * in which a handler for the server's first notifications is registered
+    * once the answer it needs is known. The server publishes nothing before
+    * `initialized`, so nothing is missed.
+    */
+   readonly beforeInitialized?: (result: InitializeResult) => void;
+}
+
+/** The capabilities the server's inbound requests rely on, declared unless the host declares its own. */
+const DEFAULT_CAPABILITIES: ClientCapabilities = { workspace: { applyEdit: true, configuration: true } };
+
+/**
+ * Run the page's end of the LSP handshake on `connection`, which must not be
+ * listening yet, and resolve with the server's answer.
+ *
+ * Registers the answers to the server's own requests before `listen`, because
+ * each is asked while the workspace comes up and an unanswered one is a
+ * failure the page sees as an error and the server as a client with no
+ * settings: capability registrations are acknowledged and kept nowhere, and a
+ * configuration request is answered item by item, since the response is
+ * positional and a dropped item mis-aligns every later answer. These
+ * registrations replace any the host made before the call, since a
+ * connection keeps one handler per method; a host serving more than one
+ * section registers its own configuration handler in `beforeInitialized`.
+ */
+export async function initializeLanguageClient(connection: MessageConnection, options: LanguageClientOptions): Promise<InitializeResult> {
+   // Before `listen`: a root that is no URI throws here, and a connection left
+   // listening with no `initialize` sent would be one the host cannot reuse.
+   const workspaceName = options.workspaceName ?? workspaceNameOf(options.rootUri);
+   connection.onRequest(RegistrationRequest.type, () => undefined);
+   connection.onRequest(UnregistrationRequest.type, () => undefined);
+   const configuration = options.configuration;
+   connection.onRequest(ConfigurationRequest.type, params =>
+      params.items.map(item => (configuration !== undefined && item.section === configuration.section ? configuration.settings() : null))
+   );
+   if (options.onLogMessage) {
+      connection.onNotification(LogMessageNotification.type, options.onLogMessage);
+   }
+   connection.listen();
+
+   const result = await connection.sendRequest(InitializeRequest.type, {
+      processId: null,
+      rootUri: options.rootUri,
+      locale: options.locale,
+      capabilities: options.capabilities ?? DEFAULT_CAPABILITIES,
+      workspaceFolders: [{ uri: options.rootUri, name: workspaceName }]
+   });
+   options.beforeInitialized?.(result);
+   await connection.sendNotification(InitializedNotification.type, {});
+   return result;
+}
+
+/** The root's last path segment, decoded, or the root itself for one with no path. */
+function workspaceNameOf(rootUri: string): string {
+   return decodeURIComponent(new URL(rootUri).pathname.replace(/\/+$/, '').split('/').pop() ?? '') || rootUri;
+}

package/src/worker-data-port.ts

@@ -0,0 +1,97 @@
+/********************************************************************************
+ * 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 {
+   createMessagePortTransport,
+   renderFrameworkMessage,
+   type DataPort,
+   type Logger,
+   type ResolvedMessage,
+   type TransferredMessagePort
+} from '@hydranium/protocol';
+import { createMessageConnection, Emitter, type MessageConnection } from 'vscode-jsonrpc/browser';
+
+/**
+ * The host half of the data head for a page talking to a worker.
+ *
+ * This is the whole of what a browser host has to supply to reach the data
+ * head; everything above it (the open/watch order, `baseVersion` conflict
+ * handling, echo filtering by `sourceClientId`) is host-invariant and already
+ * in `DataConnection` and `DataSession`.
+ *
+ * `vscode-jsonrpc/browser`, never the package root: version 9's root entry ships
+ * no runtime abstraction layer and throws on the first message rather than at
+ * import, so the mistake surfaces as a dead connection rather than a stack
+ * trace.
+ */
+export class WorkerDataPort implements DataPort {
+   protected readonly disposeEmitter = new Emitter<void>();
+   readonly onDispose = this.disposeEmitter.event;
+   protected disposed = false;
+   protected connection?: MessageConnection;
+
+   constructor(
+      /** The page's end of the data head's port, typed as the handshake types it. */
+      protected readonly port: TransferredMessagePort,
+      /** Where the connection logs its protocol faults, and what it does on its own. */
+      readonly logger?: Logger
+   ) {}
+
+   /**
+    * The transport is the port the worker was already handed at bootstrap, so
+    * there is nothing to open, but the connection must be `listen()`ing before
+    * it is returned, because the RPC proxy queues calls on this promise and
+    * never listens itself.
+    *
+    * Both ends use `createMessagePortTransport`; see it for why.
+    *
+    * Every generation gets the same connection. A fresh one per generation
+    * would leave the one a failed readiness check used still reading the port,
+    * and disposing that one is no way out: disposing any connection over the
+    * port ends the worker's head, and the retry would wait for an answer that
+    * never comes.
+    *
+    * **Rejects once this port is disposed, and a disposed port cannot be
+    * reused.** Its dispose disposes the connection, which signals the close to
+    * the worker, whose end of the port then stays closed: a later connection
+    * over it would send requests nothing answers, and hang.
+    */
+   connect(): Promise<MessageConnection> {
+      if (this.disposed) {
+         return Promise.reject(new Error('WorkerDataPort: the port is disposed, and the data head behind it has ended'));
+      }
+      if (!this.connection) {
+         const transport = createMessagePortTransport(this.port);
+         this.connection = createMessageConnection(transport.reader, transport.writer, this.logger);
+         this.connection.listen();
+      }
+      return Promise.resolve(this.connection);
+   }
+
+   /**
+    * To the console: a page has no notification surface of its own, and an
+    * unreported data-head error presents as an empty model, which reads as a
+    * valid document. A host with a surface overrides this.
+    *
+    * No translation map: omitting the argument takes the English. The raw
+    * error goes alongside rather than into the sentence, because `reported`
+    * already carries the detail and only the throw carries a stack.
+    */
+   reportError(error: unknown, reported: ResolvedMessage): void {
+      console.error(`[data head] ${renderFrameworkMessage(reported)}`, error);
+   }
+
+   /** The consumer hears it first; the connection goes even when no generation holds it, as after a failed readiness check. */
+   dispose(): void {
+      this.disposed = true;
+      this.disposeEmitter.fire();
+      this.disposeEmitter.dispose();
+      this.connection?.dispose();
+   }
+}

package/src/worker-heads.ts

@@ -0,0 +1,167 @@
+/********************************************************************************
+ * 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 {
+   createMessagePortTransport,
+   isWorkerErrorMessage,
+   WORKER_BOOTSTRAP_MESSAGE_TYPE,
+   WORKER_BOOTSTRAP_PHASE,
+   WORKER_ERROR_MESSAGE_TYPE,
+   type DataPort,
+   type Logger,
+   type TransferredMessagePort,
+   type WorkerBootstrapMessage,
+   type WorkerErrorMessage
+} from '@hydranium/protocol';
+import { createMessageConnection, Emitter, type Disposable, type Event, type MessageConnection } from 'vscode-jsonrpc/browser';
+import { WorkerDataPort } from './worker-data-port';
+
+/** The phase a report synthesised from the `Worker`'s `error` event carries. */
+export const WORKER_ERROR_EVENT_PHASE = 'worker';
+
+export interface WorkerHeadsOptions {
+   /** Where each head's connection logs its protocol faults, one component per head. Without one they log nothing. */
+   readonly logger?: Logger;
+   /**
+    * Build the data head's port over the page's end of its `MessagePort`, a
+    * {@link WorkerDataPort} by default. A host with a surface of its own for
+    * data-head failures supplies a subclass here.
+    */
+   readonly createDataPort?: (port: TransferredMessagePort, logger?: Logger) => DataPort & Disposable;
+}
+
+/** The page's end of each head, and what the worker says outside any head. */
+export interface WorkerHeads {
+   /**
+    * The LSP head's connection, not yet listening: register the handlers for
+    * the server's first requests, then `listen()` and send `initialize`. A
+    * message that arrives before `listen` is dropped.
+    */
+   readonly lsp: MessageConnection;
+   /** The data head's port, for a `DataConnection`. */
+   readonly data: DataPort;
+   /**
+    * The GLSP head's connection, not listening: GLSP's client calls `listen()`
+    * when it starts, and a second call throws. Its port is started, so a
+    * message arriving before then is dropped; the GLSP head posts nothing on
+    * its port before the client speaks. Hand it to that client wrapped with
+    * `sendByMethodName`, where the client's own connection type is named:
+    * GLSP's typed messages come from its own copy of `vscode-jsonrpc`, and
+    * this connection's copy rejects them unless they go by method name.
+    */
+   readonly glsp: MessageConnection;
+   /**
+    * Every failure the worker reports on its global, and its `error` event
+    * under {@link WORKER_ERROR_EVENT_PHASE}, before and after the heads have
+    * ended. Whether a report ended them is {@link onDispose}'s to say.
+    */
+   readonly onWorkerError: Event<WorkerErrorMessage>;
+   /**
+    * Fires once when the heads end: on a failed bootstrap, on an `error` event
+    * before the worker has posted on any head's port, or on {@link dispose}.
+    * What the heads had pending is rejected then rather than left waiting. Any
+    * later report, and an `error` event once the worker has posted, ends
+    * nothing: the worker runs on after an uncaught error, and the heads with
+    * it. Subscribe before the first `await`: the end fires once, and a
+    * subscriber after it hears nothing.
+    */
+   readonly onDispose: Event<void>;
+   /** End every head. A head whose connection exists signals its close to the worker, which ends the head there. */
+   dispose(): void;
+}
+
+/**
+ * Hand each head its own channel into `worker` and build the page's end of
+ * each.
+ *
+ * The worker keeps `port2` of every pair and the page `port1`; neither end is
+ * given the worker global, which carries the bootstrap, the worker's failure
+ * reports and whatever the host adds for itself. See the handshake in
+ * `@hydranium/protocol` for why a head on the global is unusable.
+ *
+ * **A port reports nothing when its peer dies**, so a worker that fails to
+ * load, throws before its bootstrap or fails it would leave every request on
+ * every head waiting forever, which looks exactly like a server still working.
+ * Those signals dispose the heads instead, and disposing a connection is what
+ * rejects its pending requests; a close alone does not. A worker that dies
+ * later still cannot be told from one that is working.
+ */
+export function connectWorkerHeads(worker: Worker, options: WorkerHeadsOptions = {}): WorkerHeads {
+   const lsp = new MessageChannel();
+   const data = new MessageChannel();
+   const glsp = new MessageChannel();
+   const bootstrap: WorkerBootstrapMessage = {
+      type: WORKER_BOOTSTRAP_MESSAGE_TYPE,
+      ports: { lsp: lsp.port2, data: data.port2, glsp: glsp.port2 }
+   };
+   worker.postMessage(bootstrap, [lsp.port2, data.port2, glsp.port2]);
+
+   // Both ends use `createMessagePortTransport`; see it for why.
+   const lspTransport = createMessagePortTransport(lsp.port1);
+   const lspConnection = createMessageConnection(lspTransport.reader, lspTransport.writer, options.logger?.with('LSP head'));
+   const dataLogger = options.logger?.with('data head');
+   const dataPort = options.createDataPort?.(data.port1, dataLogger) ?? new WorkerDataPort(data.port1, dataLogger);
+   const glspTransport = createMessagePortTransport(glsp.port1);
+   const glspConnection = createMessageConnection(glspTransport.reader, glspTransport.writer, options.logger?.with('GLSP head'));
+   const errorEmitter = new Emitter<WorkerErrorMessage>();
+   const disposeEmitter = new Emitter<void>();
+
+   // Whether the worker has posted anything on a head's port, which only a
+   // worker past its bootstrap does. An `error` event before that is a worker
+   // that never started; one after it is an uncaught error the worker survives.
+   let workerPosted = false;
+   for (const port of [lsp.port1, data.port1, glsp.port1]) {
+      port.addEventListener('message', () => (workerPosted = true), { once: true });
+   }
+
+   let disposed = false;
+   const dispose = (): void => {
+      if (disposed) {
+         return;
+      }
+      disposed = true;
+      lspConnection.dispose();
+      dataPort.dispose();
+      glspConnection.dispose();
+      disposeEmitter.fire();
+      disposeEmitter.dispose();
+   };
+
+   // A worker that failed to load raises an event with no message, filename or
+   // line, indistinguishable from a crash on its first statement; the host
+   // adds the URL it tried.
+   worker.addEventListener('error', event => {
+      errorEmitter.fire({
+         type: WORKER_ERROR_MESSAGE_TYPE,
+         phase: WORKER_ERROR_EVENT_PHASE,
+         message: event.message || 'no detail; check that the worker script loaded'
+      });
+      if (!workerPosted) {
+         dispose();
+      }
+   });
+   worker.addEventListener('message', event => {
+      if (!isWorkerErrorMessage(event.data)) {
+         return;
+      }
+      errorEmitter.fire(event.data);
+      if (event.data.phase === WORKER_BOOTSTRAP_PHASE) {
+         dispose();
+      }
+   });
+
+   return {
+      lsp: lspConnection,
+      data: dataPort,
+      glsp: glspConnection,
+      onWorkerError: errorEmitter.event,
+      onDispose: disposeEmitter.event,
+      dispose
+   };
+}