@hydranium/glsp-client-theia 1.0.0-next.10

package/lib/browser/client-contribution.js

@@ -0,0 +1,111 @@
+"use strict";
+/********************************************************************************
+ * 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);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HydraniumGlspClientContribution = void 0;
+const theia_integration_1 = require("@eclipse-glsp/theia-integration");
+const promise_util_1 = require("@theia/core/lib/common/promise-util");
+const inversify_1 = require("@theia/core/shared/inversify");
+const output_channel_1 = require("@theia/output/lib/browser/output-channel");
+const browser_1 = require("@theia/workspace/lib/browser");
+/**
+ * Theia GLSP client contribution for adopters whose GLSP server runs in a
+ * sideloaded VS Code extension process (or any other deferred-start setup).
+ * The behaviours adopters reliably need are lifted:
+ *
+ *   1. `waitForBackendConnected`: tail the OutputChannel for a server-printed
+ *      ready marker. While a socket connection might open earlier, the GLSP
+ *      server typically does internal initialisation before it can accept
+ *      client connections — we wait for it to say so.
+ *   2. `start`: defer until a workspace is opened. If Theia starts without a
+ *      workspace, this prevents the frontend-backend connection (and its
+ *      "connecting" progress spinner) from firing prematurely.
+ *
+ * A `GLSPClient` override filtering inbound messages by clientId is
+ * deliberately NOT provided: upstream's `BaseJsonrpcGLSPClient.onActionMessage`
+ * already filters by clientId, so the `TheiaJsonrpcGLSPClient` returned by
+ * `BaseGLSPClientContribution.createGLSPClient` is correct as-is.
+ */
+let HydraniumGlspClientContribution = class HydraniumGlspClientContribution extends theia_integration_1.BaseGLSPClientContribution {
+    outputChannelManager;
+    workspaceService;
+    id;
+    channelName;
+    readyMarker;
+    constructor(options) {
+        super();
+        this.id = options.languageContributionId;
+        this.channelName = options.channelName;
+        this.readyMarker = options.readyMarker;
+    }
+    /** Wait for the server to print its ready marker into the OutputChannel.
+     *  Resolves immediately if the marker is already present (server started
+     *  before the client contribution mounted). */
+    async waitForBackendConnected() {
+        const channel = this.outputChannelManager.getChannel(this.channelName);
+        const channelText = channel.resource?.textModel?.getValue() ?? '';
+        if (channelText.includes(this.readyMarker)) {
+            return;
+        }
+        const deferred = new promise_util_1.Deferred();
+        const channelListener = channel.onContentChange(() => {
+            const text = channel.resource?.textModel?.getValue() ?? '';
+            if (text.includes(this.readyMarker)) {
+                channelListener.dispose();
+                deferred.resolve();
+            }
+        });
+        return deferred.promise;
+    }
+    async start(glspClient) {
+        // Defer starting the GLSP client until a workspace is opened. If Theia
+        // starts without a workspace, this prevents creating the frontend-
+        // backend connection (and showing the "connecting" progress) prematurely.
+        const roots = this.workspaceService.tryGetRoots();
+        if (!roots || roots.length === 0) {
+            await new Promise(resolve => {
+                const disposable = this.workspaceService.onWorkspaceChanged(changedRoots => {
+                    if (changedRoots && changedRoots.length > 0) {
+                        disposable.dispose();
+                        resolve();
+                    }
+                });
+            });
+        }
+        await this.waitForBackendConnected();
+        return super.start(glspClient);
+    }
+};
+exports.HydraniumGlspClientContribution = HydraniumGlspClientContribution;
+__decorate([
+    (0, inversify_1.inject)(output_channel_1.OutputChannelManager),
+    __metadata("design:type", output_channel_1.OutputChannelManager)
+], HydraniumGlspClientContribution.prototype, "outputChannelManager", void 0);
+__decorate([
+    (0, inversify_1.inject)(browser_1.WorkspaceService),
+    __metadata("design:type", browser_1.WorkspaceService)
+], HydraniumGlspClientContribution.prototype, "workspaceService", void 0);
+exports.HydraniumGlspClientContribution = HydraniumGlspClientContribution = __decorate([
+    (0, inversify_1.injectable)(),
+    __param(0, (0, inversify_1.unmanaged)()),
+    __metadata("design:paramtypes", [Object])
+], HydraniumGlspClientContribution);
+//# sourceMappingURL=client-contribution.js.map

package/lib/browser/client-contribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-contribution.js","sourceRoot":"","sources":["../../src/browser/client-contribution.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;AAGlF,uEAA6E;AAC7E,sEAA+D;AAC/D,4DAA6E;AAC7E,6EAAgF;AAChF,0DAAgE;AAYhE;;;;;;;;;;;;;;;;;GAiBG;AAEI,IAAM,+BAA+B,GAArC,MAAM,+BAAgC,SAAQ,8CAA0B;IACpC,oBAAoB,CAAwB;IACvC,gBAAgB,CAAoB;IAExE,EAAE,CAAS;IACD,WAAW,CAAS;IACpB,WAAW,CAAS;IAEvC,YAAyB,OAAkC;QACxD,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC;QACzC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAC1C,CAAC;IAED;;mDAE+C;IACrC,KAAK,CAAC,uBAAuB;QACpC,MAAM,OAAO,GAAG,IAAI,CAAC,oBAAoB,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACvE,MAAM,WAAW,GACb,OAA4E,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QACvH,IAAI,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;YAC1C,OAAO;QACV,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,uBAAQ,EAAQ,CAAC;QACtC,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,GAAG,EAAE;YAClD,MAAM,IAAI,GAAI,OAA4E,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;YACjI,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;gBACnC,eAAe,CAAC,OAAO,EAAE,CAAC;gBAC1B,QAAQ,CAAC,OAAO,EAAE,CAAC;YACtB,CAAC;QACJ,CAAC,CAAC,CAAC;QACH,OAAO,QAAQ,CAAC,OAAO,CAAC;IAC3B,CAAC;IAEkB,KAAK,CAAC,KAAK,CAAC,UAAsB;QAClD,uEAAuE;QACvE,mEAAmE;QACnE,0EAA0E;QAC1E,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC,WAAW,EAAE,CAAC;QAClD,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,OAAO,CAAO,OAAO,CAAC,EAAE;gBAC/B,MAAM,UAAU,GAAG,IAAI,CAAC,gBAAgB,CAAC,kBAAkB,CAAC,YAAY,CAAC,EAAE;oBACxE,IAAI,YAAY,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;wBAC3C,UAAU,CAAC,OAAO,EAAE,CAAC;wBACrB,OAAO,EAAE,CAAC;oBACb,CAAC;gBACJ,CAAC,CAAC,CAAC;YACN,CAAC,CAAC,CAAC;QACN,CAAC;QACD,MAAM,IAAI,CAAC,uBAAuB,EAAE,CAAC;QACrC,OAAO,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAClC,CAAC;CACH,CAAA;AAtDY,0EAA+B;AACD;IAAvC,IAAA,kBAAM,EAAC,qCAAoB,CAAC;8BAAkC,qCAAoB;6EAAC;AACvC;IAA5C,IAAA,kBAAM,EAAC,0BAAgB,CAAC;8BAAuC,0BAAgB;yEAAC;0CAFvE,+BAA+B;IAD3C,IAAA,sBAAU,GAAE;IASG,WAAA,IAAA,qBAAS,GAAE,CAAA;;GARd,+BAA+B,CAsD3C"}

package/lib/browser/diagram-loader.d.ts

@@ -0,0 +1,123 @@
+/********************************************************************************
+ * 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 { DiagramLoader, type DiagramLoadingOptions } from '@eclipse-glsp/client';
+import { ChannelLogger } from '@hydranium/client-theia/lib/browser';
+import { Deferred } from '@hydranium/protocol';
+/**
+ * How a diagram load ended. A discriminated union rather than a boolean or a
+ * string: a consumer showing a pending indicator has to distinguish "not settled
+ * yet" (`undefined`) from either terminal state, and the failed arm has to carry
+ * enough for that consumer to decide whether *it* is now the only thing that can
+ * report the failure — see {@link DiagramLoadFailure.surfaced}.
+ */
+export type DiagramLoadOutcome = DiagramLoadSuccess | DiagramLoadFailure;
+export interface DiagramLoadSuccess {
+    readonly status: 'loaded';
+}
+export interface DiagramLoadFailure {
+    readonly status: 'failed';
+    /** The thrown value, verbatim. `unknown` because a rejection can be anything. */
+    readonly error: unknown;
+    /**
+     * Whether the `severity: 'ERROR'` {@link StatusAction} reached the action
+     * dispatcher — i.e. whether GLSP's `StatusOverlay` is now displaying this
+     * failure.
+     *
+     * `false` means the report itself failed, which happens when the action
+     * dispatcher is the thing that could not initialize. A consumer that covers
+     * the canvas must then render the failure itself: it is the only surface
+     * left, and removing its overlay would leave a blank diagram whose only
+     * explanation is a line in the Output channel — the exact failure mode this
+     * loader exists to prevent.
+     */
+    readonly surfaced: boolean;
+}
+/**
+ * Diagram loader that never lets a load failure vanish.
+ *
+ * `DiagramLoader.load()` orchestrates the full diagram-init path — action
+ * dispatcher init, GLSP-client connect + server `initialize`, the first
+ * `RequestModelAction`, and the model-initialization constraint. Of these only
+ * the `IDiagramStartup` hooks are wrapped by the base loader (it logs them to
+ * `console.error`); the dispatcher-init / connection / request-model steps are
+ * not. The widget that drives loading
+ * (`@eclipse-glsp/theia-integration`'s `GLSPDiagramWidget.onAfterAttach`)
+ * calls `load()` *without awaiting or catching it*, so any rejection becomes an
+ * uncaught promise rejection visible only in the browser devtools console —
+ * nothing reaches the e2e output, the server log, or a Theia log sink, and the
+ * diagram just stays blank.
+ *
+ * This subclass closes that gap: it catches every load failure, routes it to
+ * the framework Output channel (the same {@link ChannelLogger} sink the server
+ * log and action traffic share, so it is discoverable where a developer already
+ * looks), and surfaces a persistent error to the user via a `severity: 'ERROR'`
+ * {@link StatusAction} on the diagram's status overlay. It deliberately does
+ * **not** rethrow — the caller drops the promise, so rethrowing would only
+ * reproduce the uncaught rejection this exists to prevent.
+ *
+ * It also publishes the load's terminal state ({@link loadOutcome} /
+ * {@link onceLoadSettled}) so a pending indicator has one authority to key on.
+ * `HydraniumGlspDiagramWidget` uses it to cover the canvas while loading; see
+ * {@link settle} for why the signal cannot be derived from the error
+ * `StatusAction` instead.
+ *
+ * Bound by `createGlspClientTheiaModule` via `rebind(DiagramLoader)`.
+ */
+export declare class HydraniumDiagramLoader extends DiagramLoader {
+    protected readonly channel: ChannelLogger;
+    protected readonly settled: Deferred<DiagramLoadOutcome>;
+    protected outcome?: DiagramLoadOutcome;
+    /** Terminal state of the load, or `undefined` while it is still in flight.
+     *  The synchronous companion of {@link onceLoadSettled}, for a consumer that
+     *  must decide something in the same tick (e.g. whether to show an indicator
+     *  at all when re-attaching an already-loaded diagram). */
+    get loadOutcome(): DiagramLoadOutcome | undefined;
+    /** Resolves once the load reaches a terminal state — on success **and** on
+     *  failure, so a caller awaiting it cannot hang. Never rejects. */
+    onceLoadSettled(): Promise<DiagramLoadOutcome>;
+    load(options?: DiagramLoadingOptions): Promise<void>;
+    /**
+     * Record the terminal state and release {@link onceLoadSettled}. Idempotent —
+     * the first outcome wins, so a reload cannot flip a settled indicator.
+     *
+     * This runs unconditionally after {@link reportLoadFailure}, *including* when
+     * the status dispatch inside it threw. That is the load-bearing property: when
+     * the action dispatcher is itself the thing that failed to initialize — the
+     * exact failure this class exists for — no `StatusAction` ever lands, so a
+     * consumer observing actions would wait forever. Settling here means a pending
+     * indicator always comes down, and `surfaced: false` tells that consumer it is
+     * now the only thing that can report the failure.
+     */
+    protected settle(outcome: DiagramLoadOutcome): void;
+    /**
+     * Route a diagram-load failure to the Output channel and the status overlay.
+     * The status dispatch is itself guarded: when the action dispatcher is the
+     * thing that failed to initialize, dispatching may throw too, and a failure
+     * to *report* the failure must not re-escape as an uncaught rejection.
+     *
+     * @returns whether the `StatusAction` reached the dispatcher — i.e. whether the
+     * user can see this failure on the diagram. The channel line always happens, so
+     * the return value is specifically about the *user-visible* report; a `false`
+     * makes {@link DiagramLoadFailure.surfaced} false and hands the job to whoever
+     * is covering the canvas.
+     */
+    protected reportLoadFailure(err: unknown): Promise<boolean>;
+    /**
+     * The sentence a failed load is reported with, on every surface that reports
+     * it, and the only seam an adopter rewords or localizes it at. Public
+     * because the canvas overlay is one of those surfaces and lives in another
+     * class: it renders this failure exactly when the `StatusAction` did not
+     * land, so a second copy of the sentence there could only ever drift unseen.
+     */
+    loadFailureLabel(err: unknown): string;
+    /** Render a thrown value as a message. Shared so the channel line, the status
+     *  overlay and any consumer rendering {@link DiagramLoadFailure.error} agree. */
+    protected formatError(err: unknown): string;
+}
+//# sourceMappingURL=diagram-loader.d.ts.map

package/lib/browser/diagram-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagram-loader.d.ts","sourceRoot":"","sources":["../../src/browser/diagram-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,aAAa,EAAE,KAAK,qBAAqB,EAAgB,MAAM,sBAAsB,CAAC;AAC/F,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAEzE,MAAM,WAAW,kBAAkB;IAChC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IAChC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBACa,sBAAuB,SAAQ,aAAa;IAC/B,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAG,aAAa,CAAC;IAElE,SAAS,CAAC,QAAQ,CAAC,OAAO,+BAAsC;IAChE,SAAS,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAEvC;;;+DAG2D;IAC3D,IAAI,WAAW,IAAI,kBAAkB,GAAG,SAAS,CAEhD;IAED;uEACmE;IACnE,eAAe,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAI/B,IAAI,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAcnE;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAQnD;;;;;;;;;;;OAWG;cACa,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAYjE;;;;;;OAMG;IACH,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM;IAItC;qFACiF;IACjF,SAAS,CAAC,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM;CAG7C"}

package/lib/browser/diagram-loader.js

@@ -0,0 +1,153 @@
+"use strict";
+/********************************************************************************
+ * 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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HydraniumDiagramLoader = void 0;
+const client_1 = require("@eclipse-glsp/client");
+const browser_1 = require("@hydranium/client-theia/lib/browser");
+const protocol_1 = require("@hydranium/protocol");
+const inversify_1 = require("@theia/core/shared/inversify");
+/**
+ * Diagram loader that never lets a load failure vanish.
+ *
+ * `DiagramLoader.load()` orchestrates the full diagram-init path — action
+ * dispatcher init, GLSP-client connect + server `initialize`, the first
+ * `RequestModelAction`, and the model-initialization constraint. Of these only
+ * the `IDiagramStartup` hooks are wrapped by the base loader (it logs them to
+ * `console.error`); the dispatcher-init / connection / request-model steps are
+ * not. The widget that drives loading
+ * (`@eclipse-glsp/theia-integration`'s `GLSPDiagramWidget.onAfterAttach`)
+ * calls `load()` *without awaiting or catching it*, so any rejection becomes an
+ * uncaught promise rejection visible only in the browser devtools console —
+ * nothing reaches the e2e output, the server log, or a Theia log sink, and the
+ * diagram just stays blank.
+ *
+ * This subclass closes that gap: it catches every load failure, routes it to
+ * the framework Output channel (the same {@link ChannelLogger} sink the server
+ * log and action traffic share, so it is discoverable where a developer already
+ * looks), and surfaces a persistent error to the user via a `severity: 'ERROR'`
+ * {@link StatusAction} on the diagram's status overlay. It deliberately does
+ * **not** rethrow — the caller drops the promise, so rethrowing would only
+ * reproduce the uncaught rejection this exists to prevent.
+ *
+ * It also publishes the load's terminal state ({@link loadOutcome} /
+ * {@link onceLoadSettled}) so a pending indicator has one authority to key on.
+ * `HydraniumGlspDiagramWidget` uses it to cover the canvas while loading; see
+ * {@link settle} for why the signal cannot be derived from the error
+ * `StatusAction` instead.
+ *
+ * Bound by `createGlspClientTheiaModule` via `rebind(DiagramLoader)`.
+ */
+let HydraniumDiagramLoader = class HydraniumDiagramLoader extends client_1.DiagramLoader {
+    channel;
+    settled = new protocol_1.Deferred();
+    outcome;
+    /** Terminal state of the load, or `undefined` while it is still in flight.
+     *  The synchronous companion of {@link onceLoadSettled}, for a consumer that
+     *  must decide something in the same tick (e.g. whether to show an indicator
+     *  at all when re-attaching an already-loaded diagram). */
+    get loadOutcome() {
+        return this.outcome;
+    }
+    /** Resolves once the load reaches a terminal state — on success **and** on
+     *  failure, so a caller awaiting it cannot hang. Never rejects. */
+    onceLoadSettled() {
+        return this.settled.promise;
+    }
+    async load(options) {
+        try {
+            await super.load(options);
+            this.settle({ status: 'loaded' });
+        }
+        catch (err) {
+            // Report first, settle second, and carry whether the report landed: a
+            // consumer that uncovers the canvas on settle then finds the error
+            // already on the status overlay — or learns that it has to render the
+            // failure itself because nothing else can.
+            const surfaced = await this.reportLoadFailure(err);
+            this.settle({ status: 'failed', error: err, surfaced });
+        }
+    }
+    /**
+     * Record the terminal state and release {@link onceLoadSettled}. Idempotent —
+     * the first outcome wins, so a reload cannot flip a settled indicator.
+     *
+     * This runs unconditionally after {@link reportLoadFailure}, *including* when
+     * the status dispatch inside it threw. That is the load-bearing property: when
+     * the action dispatcher is itself the thing that failed to initialize — the
+     * exact failure this class exists for — no `StatusAction` ever lands, so a
+     * consumer observing actions would wait forever. Settling here means a pending
+     * indicator always comes down, and `surfaced: false` tells that consumer it is
+     * now the only thing that can report the failure.
+     */
+    settle(outcome) {
+        if (this.outcome !== undefined) {
+            return;
+        }
+        this.outcome = outcome;
+        this.settled.resolve(outcome);
+    }
+    /**
+     * Route a diagram-load failure to the Output channel and the status overlay.
+     * The status dispatch is itself guarded: when the action dispatcher is the
+     * thing that failed to initialize, dispatching may throw too, and a failure
+     * to *report* the failure must not re-escape as an uncaught rejection.
+     *
+     * @returns whether the `StatusAction` reached the dispatcher — i.e. whether the
+     * user can see this failure on the diagram. The channel line always happens, so
+     * the return value is specifically about the *user-visible* report; a `false`
+     * makes {@link DiagramLoadFailure.surfaced} false and hands the job to whoever
+     * is covering the canvas.
+     */
+    async reportLoadFailure(err) {
+        const label = this.loadFailureLabel(err);
+        this.channel.error(label, err);
+        try {
+            await this.actionDispatcher.dispatch(client_1.StatusAction.create(label, { severity: 'ERROR' }));
+            return true;
+        }
+        catch (statusErr) {
+            this.channel.error('Failed to surface the diagram-load failure on the status overlay', statusErr);
+            return false;
+        }
+    }
+    /**
+     * The sentence a failed load is reported with, on every surface that reports
+     * it, and the only seam an adopter rewords or localizes it at. Public
+     * because the canvas overlay is one of those surfaces and lives in another
+     * class: it renders this failure exactly when the `StatusAction` did not
+     * land, so a second copy of the sentence there could only ever drift unseen.
+     */
+    loadFailureLabel(err) {
+        return `Diagram failed to load: ${this.formatError(err)}`;
+    }
+    /** Render a thrown value as a message. Shared so the channel line, the status
+     *  overlay and any consumer rendering {@link DiagramLoadFailure.error} agree. */
+    formatError(err) {
+        return err instanceof Error ? err.message : String(err);
+    }
+};
+exports.HydraniumDiagramLoader = HydraniumDiagramLoader;
+__decorate([
+    (0, inversify_1.inject)(browser_1.ChannelLogger),
+    __metadata("design:type", browser_1.ChannelLogger)
+], HydraniumDiagramLoader.prototype, "channel", void 0);
+exports.HydraniumDiagramLoader = HydraniumDiagramLoader = __decorate([
+    (0, inversify_1.injectable)()
+], HydraniumDiagramLoader);
+//# sourceMappingURL=diagram-loader.js.map

package/lib/browser/diagram-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagram-loader.js","sourceRoot":"","sources":["../../src/browser/diagram-loader.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;AAElF,iDAA+F;AAC/F,iEAAoE;AACpE,kDAA+C;AAC/C,4DAAkE;AAkClE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEI,IAAM,sBAAsB,GAA5B,MAAM,sBAAuB,SAAQ,sBAAa;IACZ,OAAO,CAAiB;IAE/C,OAAO,GAAG,IAAI,mBAAQ,EAAsB,CAAC;IACtD,OAAO,CAAsB;IAEvC;;;+DAG2D;IAC3D,IAAI,WAAW;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC;IACvB,CAAC;IAED;uEACmE;IACnE,eAAe;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;IAC/B,CAAC;IAEQ,KAAK,CAAC,IAAI,CAAC,OAA+B;QAChD,IAAI,CAAC;YACF,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC1B,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACZ,sEAAsE;YACtE,mEAAmE;YACnE,sEAAsE;YACtE,2CAA2C;YAC3C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;YACnD,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC3D,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;OAWG;IACO,MAAM,CAAC,OAA2B;QACzC,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC9B,OAAO;QACV,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;;;;;;OAWG;IACO,KAAK,CAAC,iBAAiB,CAAC,GAAY;QAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;QACzC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC;YACF,MAAM,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,qBAAY,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;YACxF,OAAO,IAAI,CAAC;QACf,CAAC;QAAC,OAAO,SAAS,EAAE,CAAC;YAClB,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,kEAAkE,EAAE,SAAS,CAAC,CAAC;YAClG,OAAO,KAAK,CAAC;QAChB,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,gBAAgB,CAAC,GAAY;QAC1B,OAAO,2BAA2B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;IAC7D,CAAC;IAED;qFACiF;IACvE,WAAW,CAAC,GAAY;QAC/B,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3D,CAAC;CACH,CAAA;AA9FY,wDAAsB;AACU;IAAzC,IAAA,kBAAM,EAAC,uBAAa,CAAC;8BAA8B,uBAAa;uDAAC;iCADxD,sBAAsB;IADlC,IAAA,sBAAU,GAAE;GACA,sBAAsB,CA8FlC"}

package/lib/browser/diagram-only-marker-manager.d.ts

@@ -0,0 +1,28 @@
+/********************************************************************************
+ * 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 { ExternalMarkerManager, type Marker } from '@eclipse-glsp/client';
+/**
+ * {@link ExternalMarkerManager} that drops all marker propagation into Theia's
+ * Problems view. GLSP's `SetMarkersActionHandler` still applies the in-diagram
+ * decoration through the separate `ValidationFeedbackEmitter` path; only the
+ * forward into the `ProblemManager` is suppressed, so the LSP head stays the
+ * single source of Problems-view diagnostics.
+ *
+ * Bound per diagram by `AbstractHydraniumGlspDiagramConfiguration` when its
+ * `propagateMarkersToProblemsView` flag is `false`; see that flag for when a
+ * head should choose it.
+ *
+ * Kept in its own module — importing only `@eclipse-glsp/client`, not
+ * `@eclipse-glsp/theia-integration` — so it stays unit-testable without pulling
+ * the Theia integration into the test graph.
+ */
+export declare class NoOpExternalMarkerManager extends ExternalMarkerManager {
+    setMarkers(_markers: Marker[], _reason?: string, _sourceUri?: string): void;
+}
+//# sourceMappingURL=diagram-only-marker-manager.d.ts.map

package/lib/browser/diagram-only-marker-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagram-only-marker-manager.d.ts","sourceRoot":"","sources":["../../src/browser/diagram-only-marker-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,qBAAqB,EAAE,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAG1E;;;;;;;;;;;;;;GAcG;AACH,qBACa,yBAA0B,SAAQ,qBAAqB;IACjE,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;CAG7E"}

package/lib/browser/diagram-only-marker-manager.js

@@ -0,0 +1,44 @@
+"use strict";
+/********************************************************************************
+ * 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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoOpExternalMarkerManager = void 0;
+const client_1 = require("@eclipse-glsp/client");
+const inversify_1 = require("@theia/core/shared/inversify");
+/**
+ * {@link ExternalMarkerManager} that drops all marker propagation into Theia's
+ * Problems view. GLSP's `SetMarkersActionHandler` still applies the in-diagram
+ * decoration through the separate `ValidationFeedbackEmitter` path; only the
+ * forward into the `ProblemManager` is suppressed, so the LSP head stays the
+ * single source of Problems-view diagnostics.
+ *
+ * Bound per diagram by `AbstractHydraniumGlspDiagramConfiguration` when its
+ * `propagateMarkersToProblemsView` flag is `false`; see that flag for when a
+ * head should choose it.
+ *
+ * Kept in its own module — importing only `@eclipse-glsp/client`, not
+ * `@eclipse-glsp/theia-integration` — so it stays unit-testable without pulling
+ * the Theia integration into the test graph.
+ */
+let NoOpExternalMarkerManager = class NoOpExternalMarkerManager extends client_1.ExternalMarkerManager {
+    setMarkers(_markers, _reason, _sourceUri) {
+        // Intentionally empty — the LSP head owns the Problems view.
+    }
+};
+exports.NoOpExternalMarkerManager = NoOpExternalMarkerManager;
+exports.NoOpExternalMarkerManager = NoOpExternalMarkerManager = __decorate([
+    (0, inversify_1.injectable)()
+], NoOpExternalMarkerManager);
+//# sourceMappingURL=diagram-only-marker-manager.js.map

package/lib/browser/diagram-only-marker-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagram-only-marker-manager.js","sourceRoot":"","sources":["../../src/browser/diagram-only-marker-manager.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;AAElF,iDAA0E;AAC1E,4DAA0D;AAE1D;;;;;;;;;;;;;;GAcG;AAEI,IAAM,yBAAyB,GAA/B,MAAM,yBAA0B,SAAQ,8BAAqB;IACjE,UAAU,CAAC,QAAkB,EAAE,OAAgB,EAAE,UAAmB;QACjE,6DAA6D;IAChE,CAAC;CACH,CAAA;AAJY,8DAAyB;oCAAzB,yBAAyB;IADrC,IAAA,sBAAU,GAAE;GACA,yBAAyB,CAIrC"}

package/lib/browser/diagram-widget.d.ts

@@ -0,0 +1,97 @@
+/********************************************************************************
+ * 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 { GLSPDiagramWidget } from '@eclipse-glsp/theia-integration';
+import { type Message } from '@theia/core/lib/browser';
+import { type DiagramLoadOutcome, HydraniumDiagramLoader } from './diagram-loader';
+import '../../style/diagram-loading.css';
+/** Class on the overlay root. Adopters style / override via this contract. */
+export declare const DIAGRAM_LOADING_CLASS = "hydranium-diagram-loading";
+/** Added to the overlay root when it switches from pending to reporting a
+ *  failure, so the spinner can be hidden and the text restyled from CSS alone. */
+export declare const DIAGRAM_LOADING_FAILED_CLASS = "hydranium-diagram-loading-failed";
+/**
+ * `GLSPDiagramWidget` that covers the canvas with a spinner until the diagram
+ * load reaches a terminal state.
+ *
+ * **Why.** GLSP renders nothing until the first model arrives, so opening a
+ * diagram shows a blank tab for the whole round trip — long enough on a large
+ * model to read as a broken editor rather than a slow one.
+ *
+ * **How the pending state is sourced.** From {@link HydraniumDiagramLoader}, not
+ * from `actionDispatcher.onceModelInitialized()`. The loader settles on failure
+ * as well as on success, and it does so even when its own error-reporting
+ * dispatch throws; `onceModelInitialized()` simply never settles on a failed
+ * load. That distinction is not academic here: this overlay is opaque and covers
+ * the widget node, while GLSP's `StatusOverlay` — where the loader reports the
+ * failure — mounts *inside* the diagram's base div. Keyed on model
+ * initialization, a failed load would leave a spinner turning on top of the
+ * error message explaining it. Keyed on the loader, exactly one component decides
+ * whether the canvas is pending and the two mechanisms compose instead of
+ * competing.
+ *
+ * **The one case where this overlay reports the failure itself.** When
+ * `DiagramLoadFailure.surfaced` is `false` the loader could not dispatch its
+ * `StatusAction` — the action dispatcher was what failed — so the status overlay
+ * shows nothing. Uncovering the canvas would then leave a blank diagram whose only
+ * explanation is a line in the Output channel. In that case, and only that case,
+ * the overlay stays up and swaps the spinner for the error text.
+ *
+ * Bound unconditionally by `AbstractHydraniumGlspTheiaFrontendModule`. To opt out,
+ * override {@link showLoadingOverlay} to a no-op; to change what is rendered,
+ * override {@link createLoadingOverlay} or {@link loadingLabel}.
+ */
+export declare class HydraniumGlspDiagramWidget extends GLSPDiagramWidget {
+    protected loadingOverlay?: HTMLElement;
+    protected onAfterAttach(msg: Message): void;
+    dispose(): void;
+    /**
+     * Cover the canvas until the load settles.
+     *
+     * Nothing is created unless there is a signal to take it down again: no
+     * overlay without a framework loader, and none when the load has already
+     * settled — re-attaching a loaded diagram (a tab switch) skips it entirely
+     * rather than creating and immediately removing one, so there is no flash.
+     */
+    protected showLoadingOverlay(): void;
+    /**
+     * Take the overlay down, or keep it as the failure's only reporter.
+     *
+     * The overlay is retained ONLY for a failure the loader could not surface;
+     * anything else uncovers the canvas, so a load that failed *and was reported*
+     * reveals GLSP's status overlay rather than double-reporting on top of it.
+     */
+    protected onLoadSettled(outcome: DiagramLoadOutcome): void;
+    /**
+     * Repurpose the pending overlay in place as a failure report: same node, so
+     * there is no removal-then-insertion flicker, plus a marker class so the
+     * spinner can be hidden from CSS.
+     *
+     * The wording is {@link HydraniumDiagramLoader.loadFailureLabel}'s, so an
+     * adopter rewording a load failure reaches every surface that reports it.
+     * Without the framework loader there is no failure to render, so its absence
+     * is a no-op rather than a fallback wording.
+     */
+    protected showLoadFailure(error: unknown): void;
+    protected hideLoadingOverlay(): void;
+    /** Build the overlay DOM. Override to change the wording or add content; the
+     *  root must carry {@link DIAGRAM_LOADING_CLASS} for the shipped styling, and
+     *  the label element its `-label` class so {@link showLoadFailure} finds it. */
+    protected createLoadingOverlay(): HTMLElement;
+    /** Text shown under the spinner. Override for a domain-specific wording; the
+     *  failure text that replaces it is {@link showLoadFailure}'s. */
+    protected get loadingLabel(): string;
+    /**
+     * The framework loader for this diagram, or `undefined` when the container
+     * binds a plain `DiagramLoader`. Absence degrades to "no overlay" rather than
+     * an error: a head that opted out of the framework loader has no settle signal
+     * to key on, and an overlay that never comes down is worse than none.
+     */
+    protected get hydraniumDiagramLoader(): HydraniumDiagramLoader | undefined;
+}
+//# sourceMappingURL=diagram-widget.d.ts.map

package/lib/browser/diagram-widget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagram-widget.d.ts","sourceRoot":"","sources":["../../src/browser/diagram-widget.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAGlF,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAGpE,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEvD,OAAO,EAAE,KAAK,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAInF,OAAO,iCAAiC,CAAC;AAEzC,8EAA8E;AAC9E,eAAO,MAAM,qBAAqB,8BAA8B,CAAC;AAEjE;kFACkF;AAClF,eAAO,MAAM,4BAA4B,qCAAoC,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBACa,0BAA2B,SAAQ,iBAAiB;IAC9D,SAAS,CAAC,cAAc,CAAC,EAAE,WAAW,CAAC;cAEpB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI;IAO3C,OAAO,IAAI,IAAI;IAKxB;;;;;;;OAOG;IACH,SAAS,CAAC,kBAAkB,IAAI,IAAI;IAmBpC;;;;;;OAMG;IACH,SAAS,CAAC,aAAa,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAQ1D;;;;;;;;;OASG;IACH,SAAS,CAAC,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAa/C,SAAS,CAAC,kBAAkB,IAAI,IAAI;IAKpC;;oFAEgF;IAChF,SAAS,CAAC,oBAAoB,IAAI,WAAW;IAa7C;sEACkE;IAClE,SAAS,KAAK,YAAY,IAAI,MAAM,CAEnC;IAED;;;;;OAKG;IACH,SAAS,KAAK,sBAAsB,IAAI,sBAAsB,GAAG,SAAS,CAGzE;CACH"}