@eclipse-glsp/protocol 2.7.0-next.24 → 2.7.0-next.25

package/src/action-protocol/model-saving.ts

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2021-2024 STMicroelectronics and others.
+ * Copyright (c) 2021-2026 STMicroelectronics and others.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0 which is available at
@@ -14,7 +14,7 @@
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
 import * as sprotty from 'sprotty-protocol/lib/actions';
-import { hasBooleanProp, hasStringProp } from '../utils/type-util';
+import { ProposalString, hasBooleanProp, hasStringProp } from '../utils/type-util';
 import { Action, RequestAction, ResponseAction } from './base-protocol';
 
 /**
@@ -84,9 +84,12 @@ export namespace SetDirtyStateAction {
 }
 
 /**
- * A `RequestExportSvgAction` is sent by the client (or the server) to initiate the SVG export of the current diagram.
+ * A {@link RequestExportSvgAction} is sent by the client (or the server) to initiate the SVG export of the current diagram.
  * The handler of this action is expected to retrieve the diagram SVG and should send a {@link ExportSvgAction} as response.
  * Typically the {@link ExportSvgAction} is handled directly on client side.
+ *
+ * @deprecated Use the unified {@link RequestExportAction} (with `format: 'svg'`) and
+ * {@link ExportResultAction} pair instead.
  */
 export interface RequestExportSvgAction extends RequestAction<ExportSvgAction>, sprotty.RequestExportSvgAction {
     kind: typeof RequestExportSvgAction.KIND;
@@ -108,18 +111,21 @@ export namespace RequestExportSvgAction {
     }
 }
 
-/** Configuration options for the {@link RequestExportSvgAction */
+/** Configuration options for the {@link RequestExportSvgAction} */
 export interface ExportSvgOptions extends sprotty.ExportSvgOptions {
     // If set to false applied diagram styles will not be copied to the exported SVG
     skipCopyStyles?: boolean;
 }
 
 /**
- * The client sends an `ExportSvgAction` to indicate that the diagram, which represents the current model state,
+ * The client sends an {@link ExportSvgAction} to indicate that the diagram, which represents the current model state,
  * should be exported in SVG format. The action only provides the diagram SVG as plain string. The expected result of executing
- * an `ExportSvgAction` is a new file in SVG-format on the underlying filesystem. However, other details like the target destination,
+ * an {@link ExportSvgAction} is a new file in SVG-format on the underlying filesystem. However, other details like the target destination,
  * concrete file name, file extension etc. are not specified in the protocol. So it is the responsibility of the action handler to
  * process this information accordingly and export the result to the underlying filesystem.
+ *
+ * @deprecated Use {@link ExportResultAction} as the response to a unified
+ * {@link RequestExportAction} instead.
  */
 export interface ExportSvgAction extends ResponseAction, sprotty.ExportSvgAction {
     kind: typeof ExportSvgAction.KIND;
@@ -143,3 +149,161 @@ export namespace ExportSvgAction {
         };
     }
 }
+
+/**
+ * Format identifier for a diagram export. The package ships `'svg'` and `'png'`;
+ * adopters add formats by registering a `DiagramExporter` strategy keyed on any string.
+ */
+export type ExportFormat = ProposalString<'svg' | 'png'>;
+
+/** MIME type returned alongside an export. */
+export type ExportMimeType = ProposalString<'image/svg+xml' | 'image/png'>;
+
+/**
+ * Encoding of the bytes carried in {@link ExportResultAction.data}. The package ships
+ * `'text'` (UTF-8 markup, e.g. SVG) and `'base64'` (binary blobs, e.g. PNG); adopters
+ * registering a strategy with a different runtime declare their own encoding tag.
+ * Receivers must reject encodings they don't understand explicitly; silently treating an
+ * unknown value as one of the shipped ones corrupts payloads.
+ */
+export type ExportEncoding = ProposalString<'text' | 'base64'>;
+
+/**
+ * Options shared by every export strategy that renders through sprotty's SVG export pipeline.
+ * Today honoured by SVG output and the canvas-based PNG rasteriser; future strategies that
+ * also raster from SVG (PDF, PPTX, ...) would extend this interface for the same knob.
+ */
+export interface SvgRenderOptions {
+    /**
+     * Skip the per-element style-copy step. The default copy walk is expensive on large
+     * diagrams; setting this flag skips it at the cost of losing CSS-driven styling in the
+     * exported output.
+     */
+    skipCopyStyles?: boolean;
+}
+
+/**
+ * SVG-specific options carried inside {@link RequestExportAction.formatOptions} for the SVG
+ * export strategy. Mirrors {@link ExportSvgOptions} so callers migrating from the legacy
+ * {@link RequestExportSvgAction} retain feature parity.
+ */
+export interface SvgExportOptions extends SvgRenderOptions {}
+
+/**
+ * PNG-specific options carried inside {@link RequestExportAction.formatOptions} for the PNG
+ * export strategy. All fields optional — strategies fall back to sensible defaults. Inherits
+ * `skipCopyStyles` from {@link SvgRenderOptions} since PNG rasterises from SVG.
+ */
+export interface PngExportOptions extends SvgRenderOptions {
+    /** Output width in px. */
+    width?: number;
+    /** Output height in px. If omitted, height is derived to preserve the rendered aspect ratio. */
+    height?: number;
+    /** CSS colour painted as the canvas background before drawing the SVG. */
+    background?: string;
+}
+
+/**
+ * Generic, format-agnostic export request. Sent client-to-self for UI-driven export
+ * flows, or server-to-client for server-orchestrated flows (e.g. an MCP tool requesting
+ * a PNG snapshot of the active diagram). The expected response is an
+ * {@link ExportResultAction} carrying the rendered bytes.
+ *
+ * `formatOptions` is opaque to the protocol — typed as `unknown` so the format-specific
+ * overloads of {@link RequestExportAction.create} can narrow it to {@link SvgExportOptions},
+ * {@link PngExportOptions}, or an adopter's own shape without an index-signature dance. The
+ * `DiagramExporter` for the given `format` validates the value at the strategy boundary.
+ *
+ * Coexists with the legacy {@link RequestExportSvgAction} under strict separation:
+ * legacy kind (`requestExportSvg`) → legacy action ({@link ExportSvgAction}) only; new kind
+ * (`requestExport`) → new action ({@link ExportResultAction}) only; never crossed.
+ */
+export interface RequestExportAction extends RequestAction<ExportResultAction> {
+    kind: typeof RequestExportAction.KIND;
+    format: ExportFormat;
+    formatOptions?: unknown;
+}
+export namespace RequestExportAction {
+    export const KIND = 'requestExport';
+
+    export function is(object: unknown): object is RequestExportAction {
+        return RequestAction.hasKind(object, KIND) && hasStringProp(object, 'format');
+    }
+
+    /** Typed overload for the shipped `'svg'` format — autocomplete on `formatOptions`. */
+    export function create(format: 'svg', options?: { formatOptions?: SvgExportOptions; requestId?: string }): RequestExportAction;
+    /** Typed overload for the shipped `'png'` format — autocomplete on `formatOptions`. */
+    export function create(format: 'png', options?: { formatOptions?: PngExportOptions; requestId?: string }): RequestExportAction;
+    /** General overload for adopter-registered formats; `formatOptions` is opaque. */
+    export function create(format: ExportFormat, options?: { formatOptions?: unknown; requestId?: string }): RequestExportAction;
+    export function create(format: ExportFormat, options: { formatOptions?: unknown; requestId?: string } = {}): RequestExportAction {
+        return {
+            kind: KIND,
+            format,
+            requestId: '',
+            ...options
+        };
+    }
+}
+
+/**
+ * Response to a {@link RequestExportAction} carrying the rendered diagram. Text-encoded
+ * payloads (e.g. SVG markup) ride in `data` directly; binary payloads (e.g. PNG) are
+ * base64-encoded with `encoding: 'base64'` so the action stays JSON-safe.
+ */
+export interface ExportResultAction extends ResponseAction {
+    kind: typeof ExportResultAction.KIND;
+    /** Echoes the requested format. */
+    format: ExportFormat;
+    mimeType: ExportMimeType;
+    encoding: ExportEncoding;
+    /** SVG markup (`encoding: 'text'`) or base64-encoded bytes (`encoding: 'base64'`). */
+    data: string;
+    /** Echoes the request's `formatOptions` so receivers can correlate result fields back to the request. */
+    formatOptions?: unknown;
+}
+export namespace ExportResultAction {
+    export const KIND = 'exportResult';
+
+    export function is(object: unknown): object is ExportResultAction {
+        return (
+            Action.hasKind(object, KIND) &&
+            hasStringProp(object, 'format') &&
+            hasStringProp(object, 'data') &&
+            hasStringProp(object, 'mimeType') &&
+            hasStringProp(object, 'encoding')
+        );
+    }
+
+    /** Typed overload for the shipped `'svg'` format — typed echoed `formatOptions`. */
+    export function create(
+        format: 'svg',
+        data: string,
+        options: { mimeType: ExportMimeType; encoding: ExportEncoding; responseId?: string; formatOptions?: SvgExportOptions }
+    ): ExportResultAction;
+    /** Typed overload for the shipped `'png'` format — typed echoed `formatOptions`. */
+    export function create(
+        format: 'png',
+        data: string,
+        options: { mimeType: ExportMimeType; encoding: ExportEncoding; responseId?: string; formatOptions?: PngExportOptions }
+    ): ExportResultAction;
+    /** General overload for adopter-registered formats; echoed `formatOptions` is opaque. */
+    export function create(
+        format: ExportFormat,
+        data: string,
+        options: { mimeType: ExportMimeType; encoding: ExportEncoding; responseId?: string; formatOptions?: unknown }
+    ): ExportResultAction;
+    export function create(
+        format: ExportFormat,
+        data: string,
+        options: { mimeType: ExportMimeType; encoding: ExportEncoding; responseId?: string; formatOptions?: unknown }
+    ): ExportResultAction {
+        return {
+            kind: KIND,
+            format,
+            data,
+            responseId: '',
+            ...options
+        };
+    }
+}

package/src/action-protocol/viewport.spec.ts

@@ -15,7 +15,7 @@
  ********************************************************************************/
 
 import { expect } from 'chai';
-import { CenterAction, FitToScreenAction, MoveViewportAction } from './viewport';
+import { CenterAction, FitToScreenAction, MoveViewportAction, OriginViewportAction } from './viewport';
 
 describe('Viewport Actions', () => {
     describe('CenterAction', () => {
@@ -133,4 +133,40 @@ describe('Viewport Actions', () => {
             });
         });
     });
+
+    describe('OriginViewportAction', () => {
+        describe('is', () => {
+            it('should return true for an object having the correct type and a value for all required interface properties', () => {
+                const action: OriginViewportAction = {
+                    kind: 'originViewport',
+                    animate: true
+                };
+                expect(OriginViewportAction.is(action)).to.be.true;
+            });
+            it('should return false for `undefined`', () => {
+                expect(OriginViewportAction.is(undefined)).to.be.false;
+            });
+            it('should return false for an object that does not have all required interface properties', () => {
+                expect(OriginViewportAction.is({ kind: 'notTheRightOne' })).to.be.false;
+            });
+        });
+
+        describe('create', () => {
+            it('should return an object conforming to the interface with default values for the optional arguments', () => {
+                const expected: OriginViewportAction = {
+                    kind: 'originViewport',
+                    animate: true
+                };
+                expect(OriginViewportAction.create()).to.deep.equals(expected);
+            });
+            it('should return an object conforming to the interface with matching properties for the given optional arguments', () => {
+                const expected: OriginViewportAction = {
+                    kind: 'originViewport',
+                    animate: false
+                };
+                const { animate } = expected;
+                expect(OriginViewportAction.create({ animate })).to.deep.equals(expected);
+            });
+        });
+    });
 });

package/src/action-protocol/viewport.ts

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2021-2025 STMicroelectronics and others.
+ * Copyright (c) 2021-2026 STMicroelectronics and others.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0 which is available at
@@ -111,6 +111,38 @@ export namespace FitToScreenAction {
     }
 }
 
+/**
+ * Resets the viewport to its origin (zoom 1, scroll 0). This is typically dispatched by the
+ * client (e.g., from the tool palette) but can also be sent by the server to reset the viewport
+ * remotely.
+ * The corresponding namespace declares the action kind as constant and offers helper functions for type guard checks
+ * and creating new `OriginViewportActions`.
+ */
+export interface OriginViewportAction extends Action {
+    kind: typeof OriginViewportAction.KIND;
+
+    /**
+     * Indicate if the modification of the viewport should be realized with or without support of animations.
+     */
+    animate: boolean;
+}
+
+export namespace OriginViewportAction {
+    export const KIND = 'originViewport';
+
+    export function is(object: unknown): object is OriginViewportAction {
+        return Action.hasKind(object, KIND) && hasBooleanProp(object, 'animate');
+    }
+
+    export function create(options: { animate?: boolean } = {}): OriginViewportAction {
+        return {
+            kind: KIND,
+            animate: true,
+            ...options
+        };
+    }
+}
+
 /**
  * Moves the diagram canvas.
  * The corresponding namespace declares the action kind as constant and offers helper functions for type guard checks

package/src/client-server-protocol/base-glsp-client.spec.ts

@@ -220,20 +220,35 @@ describe('Node GLSP Client', () => {
     });
 
     describe('shutdownServer', () => {
-        it('should fail if server is not configured', () => {
+        it('should fail if server is not configured', async () => {
             resetClient(false);
-            expect(() => client.shutdownServer()).to.throw();
+            // `shutdownServer` is now async; guard failures surface as a rejected promise.
+            let rejection: unknown;
+            try {
+                await client.shutdownServer();
+            } catch (err) {
+                rejection = err;
+            }
+            expect(rejection).to.be.instanceOf(Error);
+            expect((rejection as Error).message).to.match(/not in 'Running' state/);
             expect(server.shutdown.called).to.be.false;
         });
-        it('should fail if client is not running', () => {
+        it('should fail if client is not running', async () => {
             resetClient(false);
             client.configureServer(server);
-            expect(() => client.shutdownServer()).to.throw();
+            let rejection: unknown;
+            try {
+                await client.shutdownServer();
+            } catch (err) {
+                rejection = err;
+            }
+            expect(rejection).to.be.instanceOf(Error);
+            expect((rejection as Error).message).to.match(/not in 'Running' state/);
             expect(server.shutdown.called).to.be.false;
         });
-        it('should invoke the corresponding server method', () => {
+        it('should invoke the corresponding server method', async () => {
             resetClient();
-            client.shutdownServer();
+            await client.shutdownServer();
             expect(server.shutdown.calledOnce).to.be.true;
         });
     });

package/src/client-server-protocol/base-glsp-client.ts

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2023-2024 EclipseSource and others.
+ * Copyright (c) 2023-2026 EclipseSource and others.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0 which is available at
@@ -153,7 +153,8 @@ export class BaseGLSPClient implements GLSPClient {
         return this.checkedServer.disposeClientSession(params);
     }
 
-    shutdownServer(): void {
+    async shutdownServer(): Promise<void> {
+        // Fire-and-forget at the proxy boundary; subclasses with a flushable send override.
         this.checkedServer.shutdown();
     }
 

package/src/client-server-protocol/glsp-client.ts

@@ -18,7 +18,7 @@ import { v4 as uuid } from 'uuid';
 import { ActionMessage } from '../action-protocol/base-protocol';
 import { Disposable } from '../utils/disposable';
 import { Event } from '../utils/event';
-import { AnyObject, hasStringProp } from '../utils/type-util';
+import { AnyObject, MaybePromise, hasStringProp } from '../utils/type-util';
 import { DisposeClientSessionParameters, InitializeClientSessionParameters, InitializeParameters, InitializeResult } from './types';
 
 export class ApplicationIdProvider {
@@ -131,9 +131,13 @@ export interface GLSPClient {
     disposeClientSession(params: DisposeClientSessionParameters): Promise<void>;
 
     /**
-     * Send a `shutdown` notification to the server.
+     * Send a `shutdown` notification to the server. The return type is {@link MaybePromise} so
+     * pre-existing synchronous adopter implementations remain valid; new implementations should
+     * return a `Promise<void>` that resolves once the notification has been flushed to the wire,
+     * otherwise callers that dispose the connection immediately afterwards may race the pending
+     * notification and the server never sees the shutdown signal.
      */
-    shutdownServer(): void;
+    shutdownServer(): MaybePromise<void>;
 
     /**
      * Stops the client and disposes unknown resources. During the stop procedure the client is in the `Stopping` state and will

package/src/client-server-protocol/glsp-server.ts

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2022-2024 STMicroelectronics and others.
+ * Copyright (c) 2022-2026 STMicroelectronics and others.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0 which is available at
@@ -15,6 +15,7 @@
  ********************************************************************************/
 
 import { ActionMessage } from '../action-protocol/base-protocol';
+import { MaybePromise } from '../utils/type-util';
 import { DisposeClientSessionParameters, InitializeClientSessionParameters, InitializeParameters, InitializeResult } from './types';
 
 /**
@@ -131,6 +132,23 @@ export interface GLSPServerListener {
 }
 export const GLSPServerListener = Symbol('GLSPServerListener');
 
+/**
+ * Contribution interface for extending the server initialization process.
+ * Implementations can modify the {@link InitializeResult} based on the provided {@link InitializeParameters}.
+ */
+export interface GLSPServerInitializer {
+    /**
+     * Handles the server initialization with the given parameters and allows to modify the initialization result.
+     *
+     * @param server The {@link GLSPServer} instance that is being initialized.
+     * @param params The {@link InitializeParameters} provided by the client.
+     * @param result The current {@link InitializeResult} that can be modified by the contribution.
+     * @returns The (possibly modified) {@link InitializeResult}.
+     */
+    initializeServer(server: GLSPServer, params: InitializeParameters, result: InitializeResult): MaybePromise<InitializeResult>;
+}
+export const GLSPServerInitializer = Symbol('GLSPServerInitializer');
+
 /**
  * Communication proxy interface used by the GLSP servers to send action messages to clients.
  * The default `JsonrpcClientProxy` used an underlying jsonrpc message connection for sending the action messages.

package/src/client-server-protocol/jsonrpc/base-jsonrpc-glsp-client.spec.ts

@@ -262,7 +262,16 @@ describe('Base JSON-RPC GLSP Client', () => {
             await resetClient(false);
             const stateChangeHandler = sinon.spy();
             client.onCurrentStateChanged(stateChangeHandler);
-            expect(() => client.shutdownServer()).to.throw();
+            // `shutdownServer` is now async; the connection-state guard rejects the returned
+            // promise rather than throwing synchronously.
+            let rejection: unknown;
+            try {
+                await client.shutdownServer();
+            } catch (err) {
+                rejection = err;
+            }
+            expect(rejection).to.be.instanceOf(Error);
+            expect((rejection as Error).message).to.equal(JsonrpcGLSPClient.ClientNotReadyMsg);
             expect(connection.sendNotification.called).to.be.false;
             expect(stateChangeHandler.called).to.be.false;
         });

package/src/client-server-protocol/jsonrpc/base-jsonrpc-glsp-client.ts

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2019-2024 EclipseSource and others.
+ * Copyright (c) 2019-2026 EclipseSource and others.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0 which is available at
@@ -125,8 +125,9 @@ export class BaseJsonrpcGLSPClient implements GLSPClient {
         this.checkedConnection.sendNotification(JsonrpcGLSPClient.ActionMessageNotification, message);
     }
 
-    shutdownServer(): void {
-        this.checkedConnection.sendNotification(JsonrpcGLSPClient.ShutdownNotification);
+    async shutdownServer(): Promise<void> {
+        // Await the send so callers can dispose the connection without racing the wire flush.
+        await this.checkedConnection.sendNotification(JsonrpcGLSPClient.ShutdownNotification);
     }
 
     stop(): Promise<void> {