@hydranium/glsp-server 1.0.0-next.31 → 1.0.0-next.315

package/src/state/reconciling-transfer-hydranium-glsp-state.ts

@@ -10,7 +10,8 @@
 import { type JsonModelState } from '@eclipse-glsp/server';
 import { injectable } from 'inversify';
 import { type AstNode } from '@hydranium/langium';
-import { type TransferElement } from '@hydranium/protocol';
+import { type BaseVersion, type TransferElement, type VersionedModel } from '@hydranium/protocol';
+import { type OperationTransition } from '../command/hydranium-glsp-operation-command.js';
 import { AbstractHydraniumGlspState } from './abstract-hydranium-glsp-state.js';
 import { reconcileSourceModelWrite } from './reconcile-source-model-write.js';
 
@@ -27,16 +28,16 @@ import { reconcileSourceModelWrite } from './reconcile-source-model-write.js';
  *   field-level shape is what lets `fast-json-patch` diff per field, so undo /
  *   redo and forward-write reconcile act per field instead of clobbering the
  *   whole document.
- * - {@link baseline} — the last in-sync projection, captured on every
- *   {@link setSourceRoot}. A forward-write conflict reconciles the user's
- *   intent (baseline → attempted) against the fresh server root.
+ * - {@link base} — the last in-sync projection, taken on every capture of
+ *   the built root. A forward-write conflict reconciles the user's
+ *   intent (base → ours) against the server's current root (theirs).
  * - {@link updateSourceModel} — the concrete reconcile template: persist,
  *   and on a `ConflictError` consult the injected `conflictResolver` and act
- *   on the merged / no-op / conflict / unavailable outcome.
+ *   on its outcome.
  * - {@link persist} / {@link refetch} — the only I/O seams. Defaults route
- *   through `ModelService.update` / `.validated` (reachable from the base via
- *   `sharedServices.model`); adopters whose document round-trip differs
- *   override these without touching the orchestration.
+ *   through the diagram session's `update` and `ModelService.validated`;
+ *   adopters whose document round-trip differs override these without
+ *   touching the orchestration.
  *
  * Adopters whose source model is whole-document text (a bare `{ text }`
  * source model) or that are read-only do NOT extend this class — they extend
@@ -51,13 +52,10 @@ export class ReconcilingTransferHydraniumGlspState<TRoot extends AstNode, TSourc
    implements JsonModelState<TSourceModel>
 {
    /**
-    * Last in-sync source-model projection, captured on every
-    * {@link setSourceRoot} (initial load + post-update). The baseline a
-    * forward-write conflict reconciles against: it stays the pre-command
-    * state because operation handlers mutate `_sourceRoot` in place during
-    * `execute` while `setSourceRoot` only re-runs once the write commits.
+    * The projection a forward-write conflict reconciles the user's intent
+    * from, taken from the built root on every capture.
     */
-   protected baseline?: TSourceModel;
+   protected base!: TSourceModel;
 
    /**
     * Persisted-shape projection of the current source root, consumed by GLSP's
@@ -68,65 +66,89 @@ export class ReconcilingTransferHydraniumGlspState<TRoot extends AstNode, TSourc
     * Synchronous — the encoder walks the in-memory AST without serialising.
     */
    get sourceModel(): TSourceModel {
-      return this.sharedServices.model.TransferEncoder.toTransfer(this._sourceRoot, 'grammar') as unknown as TSourceModel;
+      return this.projectRoot(this.sourceRoot);
    }
 
-   override setSourceRoot(uri: string, root: TRoot): void {
-      super.setSourceRoot(uri, root);
-      this.baseline = this.sourceModel;
+   /**
+    * The source model of `root`. The single projection seam: the source
+    * model, the refetch and {@link normalizeTransition} all project through it.
+    */
+   protected projectRoot(root: AstNode): TSourceModel {
+      return this.sharedServices.model.TransferEncoder.toTransfer(root, 'grammar') as unknown as TSourceModel;
+   }
+
+   /** Both ends serialized for the source document and parsed back, unless they are equal. */
+   override async normalizeTransition(transition: OperationTransition<TSourceModel>): Promise<OperationTransition<TSourceModel>> {
+      if (JSON.stringify(transition.from) === JSON.stringify(transition.to)) {
+         return transition;
+      }
+      return {
+         from: this.projectRoot(await this.roundTrip(this._sourceUri, transition.from)),
+         to: this.projectRoot(await this.roundTrip(this._sourceUri, transition.to))
+      };
+   }
+
+   protected override captureSourceRoot(uri: string, root: TRoot): void {
+      super.captureSourceRoot(uri, root);
+      this.base = this.sourceModel;
    }
 
    /**
     * Persist `model` back to the document store, then capture the resulting
-    * AST root. On a `ConflictError` (the based-on version was superseded),
-    * reconcile the user's intent against the fresh server root via the bound
+    * AST root. On a `ConflictError` (the base version was superseded),
+    * reconcile the user's intent against the server's current root via the bound
     * `conflictResolver` and act on the outcome — one declarative policy
     * (force = last-writer-wins, reconciling = field-level merge) shared with
     * undo / redo.
     */
-   async updateSourceModel(model: TSourceModel, version?: number): Promise<void> {
+   async updateSourceModel(model: TSourceModel, baseVersion: BaseVersion = this.baseVersion): Promise<void> {
       // Orchestration lives in `reconcileSourceModelWrite` so the multi-document
       // state gets the identical conflict handling; this method supplies only
       // the single-document meaning of persist / project.
-      return reconcileSourceModelWrite<TSourceModel>(model, version, {
-         persist: async (candidate, baseVersion) => {
-            const { root } = await this.persist(candidate, baseVersion);
-            this.setSourceRoot(this._sourceUri, root);
+      return reconcileSourceModelWrite<TSourceModel>(model, baseVersion, {
+         persist: async (candidate, candidateBaseVersion) => {
+            const { root } = await this.persist(candidate, candidateBaseVersion);
+            this.captureWrittenRoot(root);
          },
          refetch: () => this.refetch(),
-         baseline: this.baseline,
+         base: this.base,
          conflictResolver: this.conflictResolver,
          logger: this.logger,
-         onConflictDropped: () => this.refreshSourceRoot()
+         onConflictDropped: () => this.writeDropped(),
+         onAlreadyApplied: () => this.captureBuiltRoot(),
+         maxWrites: this.maxSourceModelWrites
       });
    }
 
    /**
     * Persist hook — the only write-side I/O. Default routes the structured
-    * model through `ModelService.update` (serialize → reparse), opting into
-    * the `ConflictError` gate when `version` is given. Adopters whose document
-    * round-trip differs override this; the orchestration in
+    * model through the diagram session's `update` (serialize → reparse),
+    * opting into the `ConflictError` gate unless `baseVersion` is `'any'`,
+    * and throws without a session. Adopters whose document
+    * round-trip differs override this, and {@link normalizeTransition}
+    * alongside so undo compares what this writes; the orchestration in
     * {@link updateSourceModel} is unchanged.
     */
-   protected async persist(model: TSourceModel, baseVersion?: number): Promise<{ root: TRoot }> {
-      const document = await this.sharedServices.model.ModelService.update({
-         uri: this._sourceUri,
-         model,
-         clientId: this.clientId,
-         baseVersion
-      });
+   protected async persist(model: TSourceModel, baseVersion: BaseVersion): Promise<{ root: TRoot }> {
+      const document = await this.requireModelSession().update({ uri: this._sourceUri, model, baseVersion });
       return document as unknown as { root: TRoot };
    }
 
    /**
-    * Refetch hook — reads the current settled server root as a persisted-shape
-    * projection (or `undefined` when unavailable). The `conflictResolver`
-    * replays the user's intent against this fresh state. Default uses
-    * `ModelService.validated` + the framework encoder's `'grammar'` mode;
-    * adopters override alongside {@link persist}.
+    * Refetch hook — the stored text parsed afresh, as a persisted-shape
+    * projection with the version of that text (or `undefined` when
+    * unavailable): theirs, which the `conflictResolver` replays the user's
+    * intent onto. Default uses {@link AbstractHydraniumGlspState.readCurrentRoot}
+    * + the framework encoder's `'grammar'` mode; adopters override alongside
+    * {@link persist}.
     */
-   protected async refetch(): Promise<TSourceModel | undefined> {
-      const fresh = await this.sharedServices.model.ModelService.validated(this._sourceUri).catch(() => undefined);
-      return fresh ? (this.sharedServices.model.TransferEncoder.toTransfer(fresh.root, 'grammar') as unknown as TSourceModel) : undefined;
+   protected async refetch(): Promise<VersionedModel<TSourceModel> | undefined> {
+      const theirs = await this.readCurrentRoot(this._sourceUri);
+      return (
+         theirs && {
+            model: this.projectRoot(theirs.root),
+            baseVersion: theirs.version
+         }
+      );
    }
 }

package/src/status/diagram-status-reporter.ts

@@ -0,0 +1,106 @@
+/********************************************************************************
+ * 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 Action,
+   ActionDispatcher,
+   type ClientSession,
+   type ClientSessionInitializer,
+   type ClientSessionListener,
+   ClientSessionManager,
+   EditMode,
+   ModelState,
+   SetEditModeAction,
+   StatusAction
+} from '@eclipse-glsp/server';
+import { type AstNode } from '@hydranium/langium';
+import { DisposableCollection, describeErrorWithStack } from '@hydranium/protocol';
+import { inject, injectable } from 'inversify';
+import { type AbstractHydraniumGlspState } from '../state/abstract-hydranium-glsp-state.js';
+import { type DiagramStatusEntry } from '../state/diagram-status.js';
+
+/**
+ * Sends the client what {@link AbstractHydraniumGlspState.onStatusChanged}
+ * announces: the current status for its status overlay and the edit mode.
+ *
+ * The only sender of either action. A status or edit mode dispatched from
+ * anywhere else is overwritten by the next change, and the state's account of
+ * why the diagram is read-only no longer matches the client's.
+ */
+export interface DiagramStatusReporter extends ClientSessionInitializer {
+   /**
+    * The client switched itself to `editMode`, as GLSP's client does before it
+    * forwards an edit-mode request. Sends the effective mode back if it differs.
+    */
+   clientEditModeChanged(editMode: EditMode): void;
+}
+export const DiagramStatusReporter = Symbol('DiagramStatusReporter');
+
+@injectable()
+export class DefaultDiagramStatusReporter implements DiagramStatusReporter, ClientSessionListener {
+   @inject(ModelState) protected readonly state!: AbstractHydraniumGlspState<AstNode, unknown>;
+   @inject(ActionDispatcher) protected readonly actionDispatcher!: ActionDispatcher;
+   @inject(ClientSessionManager) protected readonly sessionManager!: ClientSessionManager;
+
+   protected readonly toDispose = new DisposableCollection();
+   /** What the client shows; it starts editable with an empty overlay. */
+   protected sentStatus = statusKey(undefined);
+   protected sentEditMode: string = EditMode.EDITABLE;
+
+   initialize(): void {
+      this.sessionManager.addListener(this, this.state.clientId);
+      this.toDispose.push(this.state.onStatusChanged(() => this.send()));
+   }
+
+   clientEditModeChanged(editMode: EditMode): void {
+      this.sentEditMode = editMode;
+      this.send();
+   }
+
+   protected send(): void {
+      this.actionDispatcher
+         .dispatchAll(this.changedActions())
+         .catch((error: unknown) => this.state.logger.warn(`Could not send the diagram status: ${describeErrorWithStack(error)}`));
+   }
+
+   /** The actions that bring the client up to date, recording them as sent. */
+   protected changedActions(): Action[] {
+      const actions: Action[] = [];
+      const current = this.state.currentStatus;
+      if (statusKey(current) !== this.sentStatus) {
+         this.sentStatus = statusKey(current);
+         actions.push(
+            current?.message === undefined
+               ? // `NONE` is the client's spelling for "clear": an empty message at any
+                 // other severity leaves an empty band with an icon on the canvas.
+                 StatusAction.create('', { severity: 'NONE' })
+               : StatusAction.create(current.message, { severity: current.severity ?? 'INFO' })
+         );
+      }
+      if (this.state.editMode !== this.sentEditMode) {
+         this.sentEditMode = this.state.editMode;
+         actions.push(SetEditModeAction.create(this.state.editMode));
+      }
+      if (actions.length > 0) {
+         this.state.logger.debug(
+            `Sending status ${this.sentStatus} (from ${this.state.currentStatusSource ?? 'none'}); ` +
+               `edit mode ${this.sentEditMode} (held by ${this.state.readonlyStatuses.join(', ') || 'none'})`
+         );
+      }
+      return actions;
+   }
+
+   sessionDisposed(_clientSession: ClientSession): void {
+      this.toDispose.dispose();
+   }
+}
+
+function statusKey(entry: DiagramStatusEntry | undefined): string {
+   return entry?.message === undefined ? 'none' : `${entry.severity ?? 'INFO'} "${entry.message}"`;
+}

package/src/status/hydranium-glsp-request-model-action-handler.ts

@@ -0,0 +1,43 @@
+/********************************************************************************
+ * 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 { ModelState, type ProgressMonitor, RequestModelActionHandler } from '@eclipse-glsp/server';
+import { type AstNode } from '@hydranium/langium';
+import { inject, injectable } from 'inversify';
+import { type AbstractHydraniumGlspState } from '../state/abstract-hydranium-glsp-state.js';
+import { DiagramStatus } from '../state/diagram-status.js';
+
+/**
+ * Reports model loading as {@link DiagramStatus.MODEL_LOAD} rather than
+ * writing the client's status overlay directly, whose closing clear would
+ * erase a status set while the model loaded.
+ *
+ * The status is withdrawn on a failed load as well: GLSP rethrows from
+ * `handleModelLoadingError` before it reports the load finished, which would
+ * leave the loading message standing.
+ */
+@injectable()
+export class HydraniumGlspRequestModelActionHandler extends RequestModelActionHandler {
+   @inject(ModelState) declare protected modelState: AbstractHydraniumGlspState<AstNode, unknown>;
+
+   protected override reportModelLoading(message: string): ProgressMonitor | undefined {
+      this.modelState.setStatus(DiagramStatus.MODEL_LOAD, { message, severity: 'INFO' });
+      return this.progressService.start(message);
+   }
+
+   protected override reportModelLoadingFinished(monitor?: ProgressMonitor): void {
+      this.modelState.setStatus(DiagramStatus.MODEL_LOAD, undefined);
+      monitor?.end();
+   }
+
+   protected override handleModelLoadingError(error: unknown, monitor?: ProgressMonitor): void {
+      this.modelState.setStatus(DiagramStatus.MODEL_LOAD, undefined);
+      super.handleModelLoadingError(error, monitor);
+   }
+}

package/src/status/hydranium-glsp-set-edit-mode-action-handler.ts

@@ -0,0 +1,38 @@
+/********************************************************************************
+ * 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 Action, ClientAction, EditMode, ModelState, type SetEditModeAction, SetEditModeActionHandler } from '@eclipse-glsp/server';
+import { type AstNode } from '@hydranium/langium';
+import { inject, injectable } from 'inversify';
+import { type AbstractHydraniumGlspState } from '../state/abstract-hydranium-glsp-state.js';
+import { DiagramStatus } from '../state/diagram-status.js';
+import { DiagramStatusReporter } from './diagram-status-reporter.js';
+
+/**
+ * Records a client's request for a read-only diagram as
+ * {@link DiagramStatus.CLIENT_REQUEST}, instead of assigning the edit mode
+ * over every other status that holds it.
+ *
+ * Only an action the client sent counts. GLSP also runs this handler for the
+ * edit mode the server itself sends, and recording that as a request would
+ * keep the diagram read-only after its own reason has gone.
+ */
+@injectable()
+export class HydraniumGlspSetEditModeActionHandler extends SetEditModeActionHandler {
+   @inject(ModelState) declare protected modelState: AbstractHydraniumGlspState<AstNode, unknown>;
+   @inject(DiagramStatusReporter) protected readonly reporter!: DiagramStatusReporter;
+
+   override async execute(action: SetEditModeAction): Promise<Action[]> {
+      if (ClientAction.is(action)) {
+         this.modelState.setStatus(DiagramStatus.CLIENT_REQUEST, action.editMode === EditMode.READONLY ? { readonly: true } : undefined);
+         this.reporter.clientEditModeChanged(action.editMode);
+      }
+      return [];
+   }
+}

package/src/status/index.ts

@@ -0,0 +1,12 @@
+/********************************************************************************
+ * 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 './diagram-status-reporter.js';
+export * from './hydranium-glsp-request-model-action-handler.js';
+export * from './hydranium-glsp-set-edit-mode-action-handler.js';

package/src/storage/hydranium-glsp-request-save-model-action-handler.ts

@@ -0,0 +1,40 @@
+/********************************************************************************
+ * 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 Action, SaveModelAction, SaveModelActionHandler } from '@eclipse-glsp/server';
+import { ModelSavedAction, RequestSaveModelAction } from '@hydranium/protocol';
+import { injectable } from 'inversify';
+
+/**
+ * Answers a {@link RequestSaveModelAction}: saves exactly as GLSP's
+ * {@link SaveModelActionHandler} saves a `SaveModelAction` carrying the same
+ * `fileUri`, dirty-state change included, then replies with a
+ * {@link ModelSavedAction}.
+ *
+ * A failed save throws, and the server turns the throw into a `RejectAction`
+ * for the request. The save handler's own `SaveModelAction` stays registered,
+ * so a client that sends it is unaffected.
+ *
+ * `AbstractHydraniumGlspDiagramModule` registers it. A diagram module that does
+ * not extend that base adds it in `configureActionHandlers`. Without it no
+ * handler is advertised for the request, and the Theia client saves as GLSP's
+ * saveable does: a save nothing answers, so a failed one surfaces only as a
+ * timeout, and a window can close over a save still under way.
+ */
+@injectable()
+export class HydraniumGlspRequestSaveModelActionHandler extends SaveModelActionHandler {
+   override actionKinds = [RequestSaveModelAction.KIND];
+
+   // Typed `Action`, the one parameter type both this kind and the base's accept.
+   override async execute(action: Action): Promise<Action[]> {
+      const fileUri = 'fileUri' in action && typeof action.fileUri === 'string' ? action.fileUri : undefined;
+      const actions = await super.execute(SaveModelAction.create({ fileUri }));
+      return [...actions, ModelSavedAction.create()];
+   }
+}