@hydranium/core 1.0.0-next.298 → 1.0.0-next.299

package/README.md

@@ -49,6 +49,13 @@ needs it.
 3. Start other heads on the same shared services, with `startSocketServer` and
    `publishPortOnLspConnection` beside the LSP head, or `startStdioServer`
    alone.
+4. In a web worker, answer the page's bootstrap with `hostHeadsInWorker` from
+   `./browser`: it awaits what you prepared, such as `persistentFileSystem`,
+   then calls your `start`, which starts the LSP head on its port with
+   `startLanguageServerInWorker` and the other heads with their own starters.
+   It posts the ready message once every head is up, runs the validating
+   build and reports a failed start, build or rejection to the page;
+   `reportWorkerError` reports a failure of your own.
 
 See *Compose a server by hand* and *Add a validation check* in
 [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
@@ -59,7 +66,7 @@ See *Compose a server by hand* and *Add a validation check* in
 | ---------------------- | ---------------------------------------------------------------------------- | --------------- |
 | `.`                    | Composing services and extending the language's semantics                    | browser-neutral |
 | `./lsp`                | The LSP head and its modules                                                 | browser-neutral |
-| `./browser`            | The IndexedDB store behind a persistent filesystem in a web worker           | browser-only    |
+| `./browser`            | Hosting the heads in a web worker, and the IndexedDB store behind them       | browser-only    |
 | `./node`               | The Node filesystem, the stdio and socket launchers, the headless tools      | Node-only       |
 | `./messages`           | Validation messages with stable codes, and the codes this package raises     | browser-neutral |
 | `./testing`            | Parsing and service doubles for unit tests                                   | browser-neutral |

package/lib/browser/host-heads-in-worker.d.ts

@@ -0,0 +1,58 @@
+/********************************************************************************
+ * 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 HeadPorts } from '@hydranium/protocol';
+import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
+/**
+ * Report a failure to the page on the worker global, the channel no head is
+ * allowed to bind, which is what keeps it free for this. A report under
+ * {@link WORKER_BOOTSTRAP_PHASE} ends the page's heads; any other phase is
+ * shown there and the heads stay. The stack goes with it: a worker has no log
+ * anyone reads, so the page is the one place the stack can be seen.
+ */
+export declare function reportWorkerError(phase: string, error: unknown): void;
+/** What the host's `start` hands back: the shared tier, and the readiness of any head that reports it later. */
+export interface StartedHeads {
+    readonly shared: ServerSharedServicesMinimal;
+    /**
+     * The `started` promise of every head that reports a failed start through
+     * one rather than by throwing, such as the GLSP head's. The ready message
+     * waits for them, and a rejection is a failed bootstrap.
+     */
+    readonly started?: ReadonlyArray<Promise<unknown>>;
+}
+/**
+ * Answer the page's bootstrap by starting the heads on its ports, once per
+ * worker, and tell the page when they are up and when something fails.
+ *
+ * `start` is synchronous by type, and that is the ordering contract: every
+ * head's transport starts its port as it is built but drops what arrives
+ * before the head listens, so an `await` between building a head and
+ * listening loses the page's first request with no error. Everything
+ * asynchronous, the filesystem's restore above all, is `prepared`, which is
+ * awaited before `start` is called. It may be a plain value where nothing has
+ * to be awaited.
+ *
+ * Once `start` has returned and every `started` it handed back has resolved,
+ * the ready message goes out, so a page never hears of heads that failed to
+ * come up, and an uncaught error from then on is a report rather than the end
+ * of the heads. Then every document is built with validation once the
+ * workspace has initialised: Langium's initial build validates nothing, so a
+ * page that only opens its ports would see a server that indexed the
+ * workspace and says nothing. An initial build that a write during startup
+ * cancelled is built the same, since every document exists by then.
+ *
+ * Call it once: a second call answers the same bootstrap with a second set of
+ * heads on the same ports and reports every rejection twice. The worker's
+ * `unhandledrejection` listener is this function's; it drops Langium's
+ * `OperationCancelled` marker, which a build preempted by a write rejects
+ * with, as the Node host does. An uncaught throw needs no listener, since it
+ * reaches the page as the `Worker`'s own `error` event.
+ */
+export declare function hostHeadsInWorker<TPrepared>(prepared: TPrepared | PromiseLike<TPrepared>, start: (ports: HeadPorts, prepared: TPrepared) => ServerSharedServicesMinimal | StartedHeads): void;
+//# sourceMappingURL=host-heads-in-worker.d.ts.map

package/lib/browser/host-heads-in-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-heads-in-worker.d.ts","sourceRoot":"","sources":["../../src/browser/host-heads-in-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAMJ,KAAK,SAAS,EAGhB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAGjF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAGrE;AAED,gHAAgH;AAChH,MAAM,WAAW,YAAY;IAC1B,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;CACrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EACxC,QAAQ,EAAE,SAAS,GAAG,WAAW,CAAC,SAAS,CAAC,EAC5C,KAAK,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,KAAK,2BAA2B,GAAG,YAAY,GAC5F,IAAI,CAiDN"}

package/lib/browser/host-heads-in-worker.js

@@ -0,0 +1,113 @@
+/********************************************************************************
+ * 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 { describeErrorWithStack, isWorkerBootstrapMessage, WORKER_BOOTSTRAP_PHASE, WORKER_ERROR_MESSAGE_TYPE, WORKER_READY_MESSAGE_TYPE } from '@hydranium/protocol';
+import { isOperationCancelled } from '@hydranium/langium';
+import { isConnectionGoneError } from '../util/connection-liveness.js';
+/**
+ * Report a failure to the page on the worker global, the channel no head is
+ * allowed to bind, which is what keeps it free for this. A report under
+ * {@link WORKER_BOOTSTRAP_PHASE} ends the page's heads; any other phase is
+ * shown there and the heads stay. The stack goes with it: a worker has no log
+ * anyone reads, so the page is the one place the stack can be seen.
+ */
+export function reportWorkerError(phase, error) {
+    const report = { type: WORKER_ERROR_MESSAGE_TYPE, phase, message: describeErrorWithStack(error) };
+    postMessage(report);
+}
+/**
+ * Answer the page's bootstrap by starting the heads on its ports, once per
+ * worker, and tell the page when they are up and when something fails.
+ *
+ * `start` is synchronous by type, and that is the ordering contract: every
+ * head's transport starts its port as it is built but drops what arrives
+ * before the head listens, so an `await` between building a head and
+ * listening loses the page's first request with no error. Everything
+ * asynchronous, the filesystem's restore above all, is `prepared`, which is
+ * awaited before `start` is called. It may be a plain value where nothing has
+ * to be awaited.
+ *
+ * Once `start` has returned and every `started` it handed back has resolved,
+ * the ready message goes out, so a page never hears of heads that failed to
+ * come up, and an uncaught error from then on is a report rather than the end
+ * of the heads. Then every document is built with validation once the
+ * workspace has initialised: Langium's initial build validates nothing, so a
+ * page that only opens its ports would see a server that indexed the
+ * workspace and says nothing. An initial build that a write during startup
+ * cancelled is built the same, since every document exists by then.
+ *
+ * Call it once: a second call answers the same bootstrap with a second set of
+ * heads on the same ports and reports every rejection twice. The worker's
+ * `unhandledrejection` listener is this function's; it drops Langium's
+ * `OperationCancelled` marker, which a build preempted by a write rejects
+ * with, as the Node host does. An uncaught throw needs no listener, since it
+ * reaches the page as the `Worker`'s own `error` event.
+ */
+export function hostHeadsInWorker(prepared, start) {
+    const preparation = Promise.resolve(prepared);
+    // Handled here, so a restore that fails before the bootstrap arrives reaches
+    // the page once, under the bootstrap phase, and not first as an unhandled
+    // rejection.
+    preparation.catch(() => undefined);
+    // Rejections only, and not the ones the framework's own handlers already
+    // settle: a rejected LSP handler is caught by the connection, and a failed
+    // workspace walk rejects `workspaceInitialized`, which is reported below.
+    addEventListener('unhandledrejection', event => {
+        if (isOperationCancelled(event.reason)) {
+            // Dropped from the console too, as a Node listener's presence drops
+            // it there; a reported rejection keeps its console entry, the one
+            // place its stack stays navigable.
+            event.preventDefault();
+        }
+        else {
+            reportWorkerError('unhandled rejection', event.reason);
+        }
+    });
+    // One bootstrap per worker: the heads are composed against a single shared
+    // Langium tree, so a second would build a second tree over the same seed and
+    // hand out sessions that silently disagree about the workspace.
+    let bootstrapped = false;
+    // The bare global rather than `self.addEventListener`: only the former is
+    // typed against the dedicated worker's event map, where `message` carries a
+    // `MessageEvent`.
+    addEventListener('message', event => {
+        if (bootstrapped || !isWorkerBootstrapMessage(event.data)) {
+            return;
+        }
+        bootstrapped = true;
+        // `.catch` rather than try/catch: a rejected restore, a `start` that
+        // throws and a head whose `started` rejects arrive by the same route, and
+        // all have to reach the page.
+        onBootstrap(event.data.ports).catch((error) => reportWorkerError(WORKER_BOOTSTRAP_PHASE, error));
+    });
+    async function onBootstrap(ports) {
+        const value = await preparation;
+        const result = start(ports, value);
+        const { shared, started } = 'shared' in result ? result : { shared: result, started: undefined };
+        // Safe to await now: every head listens already, so nothing is lost.
+        await Promise.all(started ?? []);
+        const ready = { type: WORKER_READY_MESSAGE_TYPE };
+        postMessage(ready);
+        validateWorkspace(shared).catch((error) => reportWorkerError('workspace validation', error));
+    }
+}
+/**
+ * The trailing validating build, after `workspaceInitialized`: building before
+ * it would validate a partial document set. A cancelled or connection-gone
+ * initial build is routine, so it is built through; any other failure is the
+ * caller's to report.
+ */
+async function validateWorkspace(shared) {
+    await shared.workspace.WorkspaceManager.workspaceInitialized.catch((error) => {
+        if (!isOperationCancelled(error) && !isConnectionGoneError(error)) {
+            throw error;
+        }
+    });
+    await shared.workspace.DocumentBuilder.build(shared.workspace.LangiumDocuments.all.toArray(), { validation: true });
+}
+//# sourceMappingURL=host-heads-in-worker.js.map

package/lib/browser/host-heads-in-worker.js.map

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

package/lib/browser/index.d.ts

@@ -6,5 +6,7 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
+export * from './host-heads-in-worker.js';
 export * from './indexeddb-file-system-store.js';
+export * from './start-language-server-in-worker.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAMlF,cAAc,kCAAkC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAOlF,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kCAAkC,CAAC;AACjD,cAAc,sCAAsC,CAAC"}

package/lib/browser/index.js

@@ -7,8 +7,11 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 // Worker-only entry (`@hydranium/core/browser`). Compiled as its own project
-// against `lib.webworker`, so a worker global such as `indexedDB` resolves here
-// and nowhere else in the package: the portable `.` barrel must stay free of
-// DOM and worker globals, since it also loads in a plain Node consumer.
+// against `lib.webworker`, so a worker global such as `indexedDB` or
+// `postMessage` resolves here and nowhere else in the package: the portable
+// `.` barrel must stay free of DOM and worker globals, since it also loads in a
+// plain Node consumer.
+export * from './host-heads-in-worker.js';
 export * from './indexeddb-file-system-store.js';
+export * from './start-language-server-in-worker.js';
 //# sourceMappingURL=index.js.map

package/lib/browser/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,6EAA6E;AAC7E,gFAAgF;AAChF,6EAA6E;AAC7E,wEAAwE;AACxE,cAAc,kCAAkC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,6EAA6E;AAC7E,qEAAqE;AACrE,4EAA4E;AAC5E,gFAAgF;AAChF,uBAAuB;AACvB,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kCAAkC,CAAC;AACjD,cAAc,sCAAsC,CAAC"}

package/lib/browser/start-language-server-in-worker.d.ts

@@ -0,0 +1,29 @@
+/********************************************************************************
+ * 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 LatencyCollector, type TransferredMessagePort } from '@hydranium/protocol';
+import { type Connection } from 'vscode-languageserver/browser';
+import type { ServerSharedServices } from '../langium/module.js';
+export interface WorkerLanguageServerOptions {
+    /** Records every request the head answers. One collector serves every head, so a report covers them all. */
+    readonly latency?: LatencyCollector;
+}
+/**
+ * Start the LSP head on the port the page transferred for it, and return the
+ * shared tier `compose` built around its connection.
+ *
+ * `compose` is the adopter's services factory, called with the connection
+ * exactly as a Node entry calls it with a stdio one; the filesystem it spreads
+ * in must already be restored, since every read the head makes is synchronous
+ * and the transport drops a message that arrives before `startLanguageServer`
+ * listens. The page's end of the port closing ends only this head's
+ * connection, not the worker the other heads share, so the language client's
+ * documents are closed here, each reverting as its last close does.
+ */
+export declare function startLanguageServerInWorker<TShared extends ServerSharedServices>(port: TransferredMessagePort, compose: (connection: Connection) => TShared, options?: WorkerLanguageServerOptions): TShared;
+//# sourceMappingURL=start-language-server-in-worker.d.ts.map

package/lib/browser/start-language-server-in-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-language-server-in-worker.d.ts","sourceRoot":"","sources":["../../src/browser/start-language-server-in-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAA8B,KAAK,gBAAgB,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACrH,OAAO,EAAsC,KAAK,UAAU,EAAE,MAAM,+BAA+B,CAAC;AACpG,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAKjE,MAAM,WAAW,2BAA2B;IACzC,4GAA4G;IAC5G,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CACtC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,SAAS,oBAAoB,EAC7E,IAAI,EAAE,sBAAsB,EAC5B,OAAO,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,OAAO,EAC5C,OAAO,GAAE,2BAAgC,GACzC,OAAO,CAaT"}

package/lib/browser/start-language-server-in-worker.js

@@ -0,0 +1,35 @@
+/********************************************************************************
+ * 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 } from '@hydranium/protocol';
+import { createConnection, ProposedFeatures } from 'vscode-languageserver/browser';
+import { withHydraniumLspFeatures } from '../lsp/connection-features.js';
+import { lspLatencyOptions } from '../lsp/lsp-latency.js';
+import { startLanguageServer } from '../lsp/start-language-server.js';
+/**
+ * Start the LSP head on the port the page transferred for it, and return the
+ * shared tier `compose` built around its connection.
+ *
+ * `compose` is the adopter's services factory, called with the connection
+ * exactly as a Node entry calls it with a stdio one; the filesystem it spreads
+ * in must already be restored, since every read the head makes is synchronous
+ * and the transport drops a message that arrives before `startLanguageServer`
+ * listens. The page's end of the port closing ends only this head's
+ * connection, not the worker the other heads share, so the language client's
+ * documents are closed here, each reverting as its last close does.
+ */
+export function startLanguageServerInWorker(port, compose, options = {}) {
+    // Both ends use `createMessagePortTransport`; see it for why.
+    const transport = createMessagePortTransport(port);
+    const connection = createConnection(withHydraniumLspFeatures(ProposedFeatures.all), transport.reader, transport.writer, lspLatencyOptions(options.latency));
+    const shared = compose(connection);
+    startLanguageServer(shared);
+    transport.reader.onClose(() => void shared.workspace.TextDocuments.closeLanguageClientDocuments());
+    return shared;
+}
+//# sourceMappingURL=start-language-server-in-worker.js.map

package/lib/browser/start-language-server-in-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-language-server-in-worker.js","sourceRoot":"","sources":["../../src/browser/start-language-server-in-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,0BAA0B,EAAsD,MAAM,qBAAqB,CAAC;AACrH,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAmB,MAAM,+BAA+B,CAAC;AAEpG,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAOtE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,2BAA2B,CACxC,IAA4B,EAC5B,OAA4C,EAC5C,OAAO,GAAgC,EAAE;IAEzC,8DAA8D;IAC9D,MAAM,SAAS,GAAG,0BAA0B,CAAC,IAAI,CAAC,CAAC;IACnD,MAAM,UAAU,GAAG,gBAAgB,CAChC,wBAAwB,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAC9C,SAAS,CAAC,MAAM,EAChB,SAAS,CAAC,MAAM,EAChB,iBAAiB,CAAC,OAAO,CAAC,OAAO,CAAC,CACpC,CAAC;IACF,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACnC,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5B,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC,4BAA4B,EAAE,CAAC,CAAC;IACnG,OAAO,MAAM,CAAC;AACjB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/core",
-  "version": "1.0.0-next.298",
+  "version": "1.0.0-next.299",
   "description": "Foundational runtime of the hydranium framework: AST coordination layer (services, integrity, AST extension, serialization, multi-client documents) plus the LSP textual head at the /lsp subpath. Consumed by protocol-head packages (@hydranium/data-server, @hydranium/glsp-server).",
   "keywords": [
     "ast",
@@ -87,8 +87,8 @@
     "diff": "^5.2.0"
   },
   "devDependencies": {
-    "@hydranium/langium": "1.0.0-next.298",
-    "@hydranium/protocol": "1.0.0-next.298",
+    "@hydranium/langium": "1.0.0-next.299",
+    "@hydranium/protocol": "1.0.0-next.299",
     "@playwright/test": "^1.40.0",
     "@types/diff": "^5.2.0",
     "fake-indexeddb": "^6.2.5",
@@ -101,8 +101,8 @@
     "vscode-languageserver-types": "^3.17.5"
   },
   "peerDependencies": {
-    "@hydranium/langium": "1.0.0-next.298",
-    "@hydranium/protocol": "1.0.0-next.298",
+    "@hydranium/langium": "1.0.0-next.299",
+    "@hydranium/protocol": "1.0.0-next.299",
     "@playwright/test": "^1.40.0",
     "vscode-jsonrpc": "^9.0.0",
     "vscode-languageserver": "~10.0.1",

package/src/browser/host-heads-in-worker.ts

@@ -0,0 +1,142 @@
+/********************************************************************************
+ * 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 {
+   describeErrorWithStack,
+   isWorkerBootstrapMessage,
+   WORKER_BOOTSTRAP_PHASE,
+   WORKER_ERROR_MESSAGE_TYPE,
+   WORKER_READY_MESSAGE_TYPE,
+   type HeadPorts,
+   type WorkerErrorMessage,
+   type WorkerReadyMessage
+} from '@hydranium/protocol';
+import { isOperationCancelled } from '@hydranium/langium';
+import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import { isConnectionGoneError } from '../util/connection-liveness.js';
+
+/**
+ * Report a failure to the page on the worker global, the channel no head is
+ * allowed to bind, which is what keeps it free for this. A report under
+ * {@link WORKER_BOOTSTRAP_PHASE} ends the page's heads; any other phase is
+ * shown there and the heads stay. The stack goes with it: a worker has no log
+ * anyone reads, so the page is the one place the stack can be seen.
+ */
+export function reportWorkerError(phase: string, error: unknown): void {
+   const report: WorkerErrorMessage = { type: WORKER_ERROR_MESSAGE_TYPE, phase, message: describeErrorWithStack(error) };
+   postMessage(report);
+}
+
+/** What the host's `start` hands back: the shared tier, and the readiness of any head that reports it later. */
+export interface StartedHeads {
+   readonly shared: ServerSharedServicesMinimal;
+   /**
+    * The `started` promise of every head that reports a failed start through
+    * one rather than by throwing, such as the GLSP head's. The ready message
+    * waits for them, and a rejection is a failed bootstrap.
+    */
+   readonly started?: ReadonlyArray<Promise<unknown>>;
+}
+
+/**
+ * Answer the page's bootstrap by starting the heads on its ports, once per
+ * worker, and tell the page when they are up and when something fails.
+ *
+ * `start` is synchronous by type, and that is the ordering contract: every
+ * head's transport starts its port as it is built but drops what arrives
+ * before the head listens, so an `await` between building a head and
+ * listening loses the page's first request with no error. Everything
+ * asynchronous, the filesystem's restore above all, is `prepared`, which is
+ * awaited before `start` is called. It may be a plain value where nothing has
+ * to be awaited.
+ *
+ * Once `start` has returned and every `started` it handed back has resolved,
+ * the ready message goes out, so a page never hears of heads that failed to
+ * come up, and an uncaught error from then on is a report rather than the end
+ * of the heads. Then every document is built with validation once the
+ * workspace has initialised: Langium's initial build validates nothing, so a
+ * page that only opens its ports would see a server that indexed the
+ * workspace and says nothing. An initial build that a write during startup
+ * cancelled is built the same, since every document exists by then.
+ *
+ * Call it once: a second call answers the same bootstrap with a second set of
+ * heads on the same ports and reports every rejection twice. The worker's
+ * `unhandledrejection` listener is this function's; it drops Langium's
+ * `OperationCancelled` marker, which a build preempted by a write rejects
+ * with, as the Node host does. An uncaught throw needs no listener, since it
+ * reaches the page as the `Worker`'s own `error` event.
+ */
+export function hostHeadsInWorker<TPrepared>(
+   prepared: TPrepared | PromiseLike<TPrepared>,
+   start: (ports: HeadPorts, prepared: TPrepared) => ServerSharedServicesMinimal | StartedHeads
+): void {
+   const preparation = Promise.resolve(prepared);
+   // Handled here, so a restore that fails before the bootstrap arrives reaches
+   // the page once, under the bootstrap phase, and not first as an unhandled
+   // rejection.
+   preparation.catch(() => undefined);
+
+   // Rejections only, and not the ones the framework's own handlers already
+   // settle: a rejected LSP handler is caught by the connection, and a failed
+   // workspace walk rejects `workspaceInitialized`, which is reported below.
+   addEventListener('unhandledrejection', event => {
+      if (isOperationCancelled(event.reason)) {
+         // Dropped from the console too, as a Node listener's presence drops
+         // it there; a reported rejection keeps its console entry, the one
+         // place its stack stays navigable.
+         event.preventDefault();
+      } else {
+         reportWorkerError('unhandled rejection', event.reason);
+      }
+   });
+
+   // One bootstrap per worker: the heads are composed against a single shared
+   // Langium tree, so a second would build a second tree over the same seed and
+   // hand out sessions that silently disagree about the workspace.
+   let bootstrapped = false;
+   // The bare global rather than `self.addEventListener`: only the former is
+   // typed against the dedicated worker's event map, where `message` carries a
+   // `MessageEvent`.
+   addEventListener('message', event => {
+      if (bootstrapped || !isWorkerBootstrapMessage(event.data)) {
+         return;
+      }
+      bootstrapped = true;
+      // `.catch` rather than try/catch: a rejected restore, a `start` that
+      // throws and a head whose `started` rejects arrive by the same route, and
+      // all have to reach the page.
+      onBootstrap(event.data.ports).catch((error: unknown) => reportWorkerError(WORKER_BOOTSTRAP_PHASE, error));
+   });
+
+   async function onBootstrap(ports: HeadPorts): Promise<void> {
+      const value = await preparation;
+      const result = start(ports, value);
+      const { shared, started } = 'shared' in result ? result : { shared: result, started: undefined };
+      // Safe to await now: every head listens already, so nothing is lost.
+      await Promise.all(started ?? []);
+      const ready: WorkerReadyMessage = { type: WORKER_READY_MESSAGE_TYPE };
+      postMessage(ready);
+      validateWorkspace(shared).catch((error: unknown) => reportWorkerError('workspace validation', error));
+   }
+}
+
+/**
+ * The trailing validating build, after `workspaceInitialized`: building before
+ * it would validate a partial document set. A cancelled or connection-gone
+ * initial build is routine, so it is built through; any other failure is the
+ * caller's to report.
+ */
+async function validateWorkspace(shared: ServerSharedServicesMinimal): Promise<void> {
+   await shared.workspace.WorkspaceManager.workspaceInitialized.catch((error: unknown) => {
+      if (!isOperationCancelled(error) && !isConnectionGoneError(error)) {
+         throw error;
+      }
+   });
+   await shared.workspace.DocumentBuilder.build(shared.workspace.LangiumDocuments.all.toArray(), { validation: true });
+}

package/src/browser/index.ts

@@ -8,7 +8,10 @@
  ********************************************************************************/
 
 // Worker-only entry (`@hydranium/core/browser`). Compiled as its own project
-// against `lib.webworker`, so a worker global such as `indexedDB` resolves here
-// and nowhere else in the package: the portable `.` barrel must stay free of
-// DOM and worker globals, since it also loads in a plain Node consumer.
+// against `lib.webworker`, so a worker global such as `indexedDB` or
+// `postMessage` resolves here and nowhere else in the package: the portable
+// `.` barrel must stay free of DOM and worker globals, since it also loads in a
+// plain Node consumer.
+export * from './host-heads-in-worker.js';
 export * from './indexeddb-file-system-store.js';
+export * from './start-language-server-in-worker.js';

package/src/browser/start-language-server-in-worker.ts

@@ -0,0 +1,51 @@
+/********************************************************************************
+ * 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, type LatencyCollector, type TransferredMessagePort } from '@hydranium/protocol';
+import { createConnection, ProposedFeatures, type Connection } from 'vscode-languageserver/browser';
+import type { ServerSharedServices } from '../langium/module.js';
+import { withHydraniumLspFeatures } from '../lsp/connection-features.js';
+import { lspLatencyOptions } from '../lsp/lsp-latency.js';
+import { startLanguageServer } from '../lsp/start-language-server.js';
+
+export interface WorkerLanguageServerOptions {
+   /** Records every request the head answers. One collector serves every head, so a report covers them all. */
+   readonly latency?: LatencyCollector;
+}
+
+/**
+ * Start the LSP head on the port the page transferred for it, and return the
+ * shared tier `compose` built around its connection.
+ *
+ * `compose` is the adopter's services factory, called with the connection
+ * exactly as a Node entry calls it with a stdio one; the filesystem it spreads
+ * in must already be restored, since every read the head makes is synchronous
+ * and the transport drops a message that arrives before `startLanguageServer`
+ * listens. The page's end of the port closing ends only this head's
+ * connection, not the worker the other heads share, so the language client's
+ * documents are closed here, each reverting as its last close does.
+ */
+export function startLanguageServerInWorker<TShared extends ServerSharedServices>(
+   port: TransferredMessagePort,
+   compose: (connection: Connection) => TShared,
+   options: WorkerLanguageServerOptions = {}
+): TShared {
+   // Both ends use `createMessagePortTransport`; see it for why.
+   const transport = createMessagePortTransport(port);
+   const connection = createConnection(
+      withHydraniumLspFeatures(ProposedFeatures.all),
+      transport.reader,
+      transport.writer,
+      lspLatencyOptions(options.latency)
+   );
+   const shared = compose(connection);
+   startLanguageServer(shared);
+   transport.reader.onClose(() => void shared.workspace.TextDocuments.closeLanguageClientDocuments());
+   return shared;
+}