@hydranium/glsp-server 1.0.0-next.10

package/lib/validation/hydranium-glsp-model-validator.d.ts

@@ -0,0 +1,51 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { type Marker } from '@eclipse-glsp/protocol';
+import { type GModelElement, type ModelValidator } from '@eclipse-glsp/server';
+import { type AstNode } from '@hydranium/langium';
+import { type ServerSharedServices } from '@hydranium/core';
+import { type AbstractHydraniumGlspState } from '../state/abstract-hydranium-glsp-state.js';
+/**
+ * Framework {@link ModelValidator} that surfaces the model server's LSP
+ * diagnostics as GLSP diagram markers. Bound per diagram via
+ * `DiagramModule.bindModelValidator()`; the framework submission handler also
+ * pushes its output as a `SetMarkersAction` after every model submit so
+ * markers refresh live (the GLSP client otherwise only re-requests markers on
+ * the tool-palette validate command).
+ *
+ * The translation itself ({@link diagnosticsToMarkers}) is pure; this class
+ * supplies its model-shaped lookups from the live services: the per-language
+ * `AstNodeLocator` resolves a diagnostic's `element` path back to its AST node,
+ * and the GModel index assigns the node's diagram id and reports whether that
+ * id is currently drawn.
+ *
+ * **Cross-document.** A diagram routinely renders elements defined in *other*
+ * documents, and their validation errors are published on those documents, not
+ * on the diagram's own. The validator therefore scans the diagnostics of every
+ * document the index reports as contributing a rendered element (the index's
+ * `renderedDocumentUris`: the diagram's own document plus those reached via
+ * reference projections) and lets the index's rendered-check keep only those
+ * that map to an element drawn on this diagram; the rest fall away. The
+ * `elements` argument of {@link validate} is ignored — the diagnostic set is
+ * the source of truth, and the default `RequestMarkersAction` requests the
+ * whole diagram anyway.
+ */
+export declare class HydraniumGlspModelValidator<TRoot extends AstNode = AstNode> implements ModelValidator {
+    protected readonly sharedServices: ServerSharedServices;
+    protected readonly modelState: AbstractHydraniumGlspState<TRoot>;
+    validate(_elements: GModelElement[], _reason?: string): Marker[];
+    /**
+     * Markers for everything drawn on this diagram, gathered from the
+     * diagnostics of every document the index reports as contributing a
+     * rendered element. Empty before the source model is loaded, and for any
+     * diagnostic whose element is not rendered here.
+     */
+    markers(): Marker[];
+}
+//# sourceMappingURL=hydranium-glsp-model-validator.d.ts.map

package/lib/validation/hydranium-glsp-model-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydranium-glsp-model-validator.d.ts","sourceRoot":"","sources":["../../src/validation/hydranium-glsp-model-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,KAAK,aAAa,EAAc,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3F,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,KAAK,oBAAoB,EAA8B,MAAM,iBAAiB,CAAC;AACxF,OAAO,EAAE,KAAK,0BAA0B,EAAE,MAAM,2CAA2C,CAAC;AAI5F;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBACa,2BAA2B,CAAC,KAAK,SAAS,OAAO,GAAG,OAAO,CAAE,YAAW,cAAc;IACrD,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAG,oBAAoB,CAAC;IAChF,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAG,0BAA0B,CAAC,KAAK,CAAC,CAAC;IAEtF,QAAQ,CAAC,SAAS,EAAE,aAAa,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE;IAIhE;;;;;OAKG;IACH,OAAO,IAAI,MAAM,EAAE;CA6CrB"}

package/lib/validation/hydranium-glsp-model-validator.js

@@ -0,0 +1,118 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { ModelState } from '@eclipse-glsp/server';
+import { inject, injectable } from 'inversify';
+import { URI } from '@hydranium/langium';
+import { HydraniumTypes } from '../state/hydranium-shared-core-services.js';
+import { diagnosticsToMarkers } from './diagnostic-markers.js';
+/**
+ * Framework {@link ModelValidator} that surfaces the model server's LSP
+ * diagnostics as GLSP diagram markers. Bound per diagram via
+ * `DiagramModule.bindModelValidator()`; the framework submission handler also
+ * pushes its output as a `SetMarkersAction` after every model submit so
+ * markers refresh live (the GLSP client otherwise only re-requests markers on
+ * the tool-palette validate command).
+ *
+ * The translation itself ({@link diagnosticsToMarkers}) is pure; this class
+ * supplies its model-shaped lookups from the live services: the per-language
+ * `AstNodeLocator` resolves a diagnostic's `element` path back to its AST node,
+ * and the GModel index assigns the node's diagram id and reports whether that
+ * id is currently drawn.
+ *
+ * **Cross-document.** A diagram routinely renders elements defined in *other*
+ * documents, and their validation errors are published on those documents, not
+ * on the diagram's own. The validator therefore scans the diagnostics of every
+ * document the index reports as contributing a rendered element (the index's
+ * `renderedDocumentUris`: the diagram's own document plus those reached via
+ * reference projections) and lets the index's rendered-check keep only those
+ * that map to an element drawn on this diagram; the rest fall away. The
+ * `elements` argument of {@link validate} is ignored — the diagnostic set is
+ * the source of truth, and the default `RequestMarkersAction` requests the
+ * whole diagram anyway.
+ */
+let HydraniumGlspModelValidator = class HydraniumGlspModelValidator {
+    sharedServices;
+    modelState;
+    validate(_elements, _reason) {
+        return this.markers();
+    }
+    /**
+     * Markers for everything drawn on this diagram, gathered from the
+     * diagnostics of every document the index reports as contributing a
+     * rendered element. Empty before the source model is loaded, and for any
+     * diagnostic whose element is not rendered here.
+     */
+    markers() {
+        // `sourceUri` is a definite-assignment field — undefined until the
+        // storage load flow calls `setSourceRoot`. Guard so a marker request that
+        // races initial load returns empty rather than scanning an empty index.
+        if (!this.modelState.sourceUri) {
+            return [];
+        }
+        const index = this.modelState.index;
+        const markers = [];
+        // Scan only the documents that contribute rendered elements, not every
+        // loaded document. The rendered-check below still keeps only what is
+        // drawn here.
+        for (const uri of index.renderedDocumentUris()) {
+            const document = this.sharedServices.workspace.LangiumDocuments.getDocument(URI.parse(uri));
+            if (!document) {
+                continue;
+            }
+            // Diagnostics are produced by the framework's `HydraniumDocumentValidator`,
+            // which emits `TransferLspDiagnostic` (LSP `Diagnostic` + `element` path).
+            // Parser/lexer diagnostics carry no `element`; the lookup drops them.
+            const diagnostics = document.diagnostics;
+            if (!diagnostics || diagnostics.length === 0) {
+                continue;
+            }
+            const root = document.parseResult.value;
+            const locator = this.sharedServices.ServiceRegistry.getServices(document.uri).workspace.AstNodeLocator;
+            const lookups = {
+                resolveElement: path => (path ? locator.getAstNode(root, path) : undefined),
+                renderedIdsFor: astNode => {
+                    // A node renders as: every GModel element explicitly registered as
+                    // representing it (reference projections, possibly several), plus its
+                    // own stable id, for an element keyed directly by it. Keep only the
+                    // ids actually drawn on this diagram.
+                    const candidates = new Set(index.findElementIds(astNode));
+                    const stableId = index.findId(astNode);
+                    if (stableId !== undefined) {
+                        candidates.add(stableId);
+                    }
+                    return [...candidates].filter(id => index.find(id) !== undefined);
+                }
+            };
+            markers.push(...diagnosticsToMarkers(diagnostics, lookups));
+        }
+        return markers;
+    }
+};
+__decorate([
+    inject(HydraniumTypes.SharedCoreServices),
+    __metadata("design:type", Object)
+], HydraniumGlspModelValidator.prototype, "sharedServices", void 0);
+__decorate([
+    inject(ModelState),
+    __metadata("design:type", Function)
+], HydraniumGlspModelValidator.prototype, "modelState", void 0);
+HydraniumGlspModelValidator = __decorate([
+    injectable()
+], HydraniumGlspModelValidator);
+export { HydraniumGlspModelValidator };
+//# sourceMappingURL=hydranium-glsp-model-validator.js.map

package/lib/validation/hydranium-glsp-model-validator.js.map

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

package/lib/validation/index.d.ts

@@ -0,0 +1,11 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+export * from './diagnostic-markers.js';
+export * from './hydranium-glsp-model-validator.js';
+//# sourceMappingURL=index.d.ts.map

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

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

package/lib/validation/index.js

@@ -0,0 +1,11 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+export * from './diagnostic-markers.js';
+export * from './hydranium-glsp-model-validator.js';
+//# sourceMappingURL=index.js.map

package/lib/validation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,yBAAyB,CAAC;AACxC,cAAc,qCAAqC,CAAC"}

package/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "@hydranium/glsp-server",
+  "version": "1.0.0-next.10",
+  "description": "GLSP protocol head for the hydranium framework. Peer of @hydranium/core/lsp and @hydranium/data-server; built on @hydranium/core.",
+  "keywords": [
+    "hydranium",
+    "langium",
+    "language-server",
+    "lsp",
+    "glsp",
+    "diagram"
+  ],
+  "homepage": "https://github.com/eclipse-emfcloud/hydranium/tree/main/packages/glsp-server",
+  "bugs": {
+    "url": "https://github.com/eclipse-emfcloud/hydranium/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eclipse-emfcloud/hydranium.git",
+    "directory": "packages/glsp-server"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Hydranium Team"
+  },
+  "sideEffects": [
+    "./lib/testing/glsp-harness.js"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./browser": {
+      "types": "./lib/browser/index.d.ts",
+      "default": "./lib/browser/index.js"
+    },
+    "./lib/browser": {
+      "types": "./lib/browser/index.d.ts",
+      "default": "./lib/browser/index.js"
+    },
+    "./node": {
+      "types": "./lib/node/index.d.ts",
+      "default": "./lib/node/index.js"
+    },
+    "./lib/node": {
+      "types": "./lib/node/index.d.ts",
+      "default": "./lib/node/index.js"
+    },
+    "./testing": {
+      "types": "./lib/testing/index.d.ts",
+      "default": "./lib/testing/index.js"
+    },
+    "./lib/testing": {
+      "types": "./lib/testing/index.d.ts",
+      "default": "./lib/testing/index.js"
+    }
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "src",
+    "!lib/**/*.tsbuildinfo"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rimraf lib tsconfig.tsbuildinfo",
+    "lint": "eslint 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"
+  },
+  "dependencies": {
+    "uuid": "^10.0.0"
+  },
+  "devDependencies": {
+    "@eclipse-glsp/protocol": "2.7.0",
+    "@eclipse-glsp/server": "2.7.0",
+    "@hydranium/core": "1.0.0-next.10",
+    "@hydranium/langium": "1.0.0-next.10",
+    "@hydranium/protocol": "1.0.0-next.10",
+    "inversify": "6.2.2",
+    "reflect-metadata": "0.2.2",
+    "rimraf": "^5.0.0",
+    "typescript": "^5.8.0",
+    "vscode-jsonrpc": "9.0.1",
+    "vscode-languageserver-types": "^3.17.5"
+  },
+  "peerDependencies": {
+    "@eclipse-glsp/protocol": "^2.6.0",
+    "@eclipse-glsp/server": "^2.6.0",
+    "@hydranium/core": "1.0.0-next.10",
+    "@hydranium/langium": "1.0.0-next.10",
+    "@hydranium/protocol": "1.0.0-next.10",
+    "inversify": "^6.0.0",
+    "reflect-metadata": "^0.2.2",
+    "vscode-jsonrpc": "^8.0.0 || ^9.0.0",
+    "vscode-languageserver-types": "^3.17.5"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "//prepack": "The publish guard, and it deliberately is NOT a `prepare`: npm runs a workspace `prepare` BEFORE the root `postinstall` that applies patches/vscode-jsonrpc+9.0.1.patch, so building there fails on a cold clone and npm rolls the entire install back. `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. It FAILS rather than rebuilds, because the rebuild is exactly the part that ordering defeats. 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.",
+  "//sideEffects": "The harness bare-imports `reflect-metadata`, which installs a global `Reflect` polyfill the inversify decorators in this package need before any container is built. That effect is invisible from the module's exports, so a bundler that treats the file as pure may reorder or drop the import and every `@injectable` resolution then fails at runtime. The rest of the package constructs no module-level state beyond frozen constants and DI symbols."
+}

package/src/browser/index.ts

@@ -0,0 +1,15 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+// Browser-only entry (`@hydranium/glsp-server/browser`). Holds the worker
+// launcher, which binds GLSP's `WorkerServerLauncher` from
+// `@eclipse-glsp/server/browser`. The portable `.` entry stays free of that
+// import for the same reason it stays free of the node one: it must resolve
+// under both platforms, and a build that names one has picked.
+export * from './start-glsp-server-in-worker.js';

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

@@ -0,0 +1,202 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import {
+   type Logger as GlspLogger,
+   type ServerModule,
+   type WorkerLaunchOptions,
+   WorkerServerLauncher,
+   createAppModule
+} from '@eclipse-glsp/server/browser.js';
+import { Container, type ContainerModule } from 'inversify';
+import type { Logger } from '@hydranium/protocol';
+import type { IntegratedServer } from '@hydranium/core';
+import { createGlspFrameworkOverrides } from '../launcher/glsp-framework-overrides.js';
+import { createGlspServerOverrides } from '../launcher/glsp-server-overrides.js';
+
+/**
+ * A `MessagePort` the host transferred into the worker, described structurally.
+ *
+ * This package inherits `tsconfig.base.json`'s `lib: ["ES2022"]` and so compiles
+ * without the DOM lib, which is what keeps `document` / `window` compile errors
+ * here — so `MessagePort` has no name either and the contract has to be spelled
+ * out.
+ *
+ * **The member set is chosen to admit a `MessagePort` and REJECT a `Worker` or
+ * the worker global**, both of which the launcher's own reader would otherwise
+ * accept. Only a port needs starting, so `start` is what tells the three apart,
+ * and naming it here turns "never bind a head to the global" from a rule in a
+ * document into a compile error at the call site.
+ *
+ * **That compile error happens at the ADOPTER, not here.** This project resolves
+ * neither `MessagePort` nor `Worker` as a type, so nothing in this package can
+ * demonstrate the rejection; a host compiling its worker against `lib.webworker`
+ * (or a page against `lib.dom`) is where the names resolve and the guard bites.
+ * Measured there: passing the worker global fails with `Property 'start' is
+ * missing in type 'DedicatedWorkerGlobalScope'`.
+ *
+ * `addEventListener` is not a discriminator — `postMessage` plus `start` already
+ * excludes the other two — and nothing in this module calls any of the three
+ * (the reader assigns `onmessage`, which starts a port implicitly). It is listed
+ * because it is part of what the reader uses, so the interface reads as the
+ * contract rather than as a minimal trick.
+ */
+export interface TransferredMessagePort {
+   postMessage(message: unknown): void;
+   addEventListener(type: 'message', listener: (event: unknown) => void, options?: unknown): void;
+   start(): void;
+}
+
+/**
+ * Options for {@link startGlspServerInWorker}.
+ *
+ * The socket variant's options have no counterpart here and are deliberately
+ * absent rather than ignored: there is no port to bind, none to discover, and
+ * so nothing to publish over an LSP connection.
+ *
+ * @see {@link startGlspServerInWorker} for the lifecycle semantics.
+ */
+export interface BrowserGlspServerOptions {
+   /**
+    * The port the host transferred into the worker for this head.
+    *
+    * **Required, and that is the whole point.** GLSP's
+    * `WorkerServerLauncher.createConnection` falls back to the worker global
+    * when it is omitted, and a head on the global receives every other head's
+    * traffic — `BrowserMessageReader` filters nothing, so this is not a race
+    * under load but every message delivered to the wrong reader. The global is
+    * unusable even for a single head, because the launcher posts its startup
+    * string through the global `postMessage` regardless of the connection it
+    * was given, and no JSON-RPC reader can parse that.
+    */
+   readonly context: TransferredMessagePort;
+   /**
+    * Adopter-supplied logger factory. Called once per Inversify resolution
+    * (with `caller` set to the requesting parent's class name) AND once
+    * per `LoggerFactory` invocation.
+    *
+    * The GLSP log threshold is a property of the logger this returns, and there
+    * is deliberately no launcher-level `logLevel` beside it — see the socket
+    * variant's note on the same member.
+    */
+   readonly createLogger: (caller?: string) => GlspLogger;
+   /**
+    * The GLSP {@link ServerModule} with per-diagram modules pre-configured via
+    * `new ServerModule().configureDiagramModule(...)`.
+    */
+   readonly serverModule: ServerModule;
+   /**
+    * Additional Inversify modules to load on the app container AFTER GLSP's
+    * own app module and the framework overrides. Adopters wire language-services
+    * bindings (e.g. their own shared-services symbol) here.
+    */
+   readonly appModules?: ReadonlyArray<ContainerModule>;
+   /**
+    * Optional framework-lifecycle logger, for the launcher's own bringup and
+    * failure lines. The GLSP container's logger handles application-level logs.
+    */
+   readonly logger?: Logger;
+}
+
+/**
+ * Start a GLSP head on a transferred `MessagePort` inside a web worker, with no
+ * Node runtime and no backend process.
+ *
+ * The worker counterpart of `startGlspServer`,
+ * and deliberately a separate function rather than a mode of it. The two share
+ * a shape — app module, framework overrides, adopter modules, resolve launcher,
+ * configure the {@link ServerModule}, start — and almost nothing else: a
+ * different launcher, a different upstream `createAppModule` whose options carry
+ * no `fileLog`, and no `'listening'` event to resolve readiness on. Over half of
+ * the socket options are meaningless here, so threading a flag would leave a
+ * function whose contract depends on which branch the caller is in.
+ *
+ * Returns an {@link IntegratedServer} — the socket variant's `port` is the one
+ * member a worker head has no answer for, so it is absent rather than
+ * `undefined`.
+ *
+ * - `started` resolves once the launcher has built its connection and the
+ *   server instance behind it, which is CHECKED rather than assumed — see
+ *   below. There is no transport handshake to wait on: the port arrived live,
+ *   and the launcher's own readiness signal is a string it posts on the worker
+ *   global, which nothing here reads.
+ * - `stopped` resolves when the connection closes, and rejects on a connection
+ *   error.
+ */
+export function startGlspServerInWorker(options: BrowserGlspServerOptions): IntegratedServer {
+   const lifecycle = options.logger;
+
+   // GLSP's own app module first, as on Node, so the framework tracks the
+   // resolved GLSP version's app bindings instead of re-deriving them. This is
+   // the BROWSER build's `createAppModule`, whose options are `LoggerConfigOptions`
+   // — no `fileLog`, because there is no file to log to. `consoleLog` is forced
+   // off so GLSP binds a throwaway NullLogger; the overrides below replace it
+   // with the adopter's, which is also why no log level is passed here: with
+   // `consoleLog` off, GLSP discards it, and the binding it would have
+   // configured is unbound a line later.
+   const glspAppModule = createAppModule({ consoleLog: false });
+
+   const appContainer = new Container();
+   appContainer.load(glspAppModule, createGlspFrameworkOverrides(options.createLogger), ...(options.appModules ?? []));
+
+   const launcher = appContainer.resolve<WorkerServerLauncher>(WorkerServerLauncher);
+   // Additional module rather than an app-container binding, as on Node: the
+   // launcher loads these into the per-connection SERVER container, the only
+   // tier where the adopter's `ServerModule` binding of `GLSPServer` is
+   // rebindable.
+   launcher.configure(options.serverModule, createGlspServerOverrides());
+
+   try {
+      // Upstream declares `WorkerLaunchOptions.context` as `Worker`, narrower
+      // than the `MessagePort | Worker | DedicatedWorkerGlobalScope` its own
+      // `BrowserMessageReader` accepts — so the value that is CORRECT here is
+      // the one the declaration names as wrong.
+      //
+      // **The cast is currently redundant, and is kept deliberately.** `Worker`
+      // does not resolve under this package's `lib`, so `skipLibCheck` leaves
+      // the option an error type and the assignment compiles without it —
+      // measured, not assumed. Removing it would mean this file type-checks by
+      // the same accident that let upstream's own `?? self` default pass, and
+      // would break the day the name resolves. The cast states the intent
+      // instead, and costs one line to do so.
+      const launchOptions = { context: options.context } as unknown as WorkerLaunchOptions;
+      // `start` resolves only when the connection closes, so it is the `stopped`
+      // promise. The launcher builds the connection and the server instance
+      // synchronously before returning it, which is what makes "we got here"
+      // equal to "accepting traffic".
+      const stoppedPromise = Promise.resolve(launcher.start(launchOptions));
+      // Attached here and not left to the caller: a worker has no console
+      // anyone is watching, so a connection error on a `stopped` nobody awaits
+      // becomes an unhandled rejection that reaches no one. The handler also
+      // marks the promise handled, which the caller's own `await` still sees.
+      stoppedPromise.catch((error: unknown) => lifecycle?.error('[GlspServer] Worker connection error:', error));
+
+      // The `started`-equals-synchronous-construction assumption above is
+      // upstream's, so it is verified rather than trusted: `run` awaiting
+      // anything before building the connection would leave `started` resolving
+      // on a head that cannot yet answer, and a client's first request would
+      // hang with nothing logged. The field is `protected`, reached by property
+      // indexing as the socket launcher's `netServer` is.
+      const connection = (launcher as unknown as { connection?: unknown }).connection;
+      if (connection === undefined) {
+         const error = new Error(
+            'startGlspServerInWorker: the launcher built no connection synchronously — ' +
+               'WorkerServerLauncher.run has become asynchronous and readiness now needs a real signal'
+         );
+         lifecycle?.error(`[GlspServer] ${error.message}`);
+         return { started: Promise.reject(error), stopped: stoppedPromise };
+      }
+
+      lifecycle?.info('[GlspServer] Ready to accept client requests on the transferred port');
+      return { started: Promise.resolve(), stopped: stoppedPromise };
+   } catch (error) {
+      lifecycle?.error('Error in GLSP server worker launcher:', error);
+      return { started: Promise.reject(error), stopped: Promise.resolve() };
+   }
+}