@hydranium/protocol 1.0.0-next.123 → 1.0.0-next.127

package/src/data/data-server-protocol.ts

@@ -16,6 +16,7 @@ import type { ReferenceCandidate, ReferenceTarget } from '../model-service/refer
 import type {
    ProjectsChangedEvent,
    TransferDocumentDeletedEvent,
+   TransferDocumentDirtyChangedEvent,
    TransferDocumentSavedEvent,
    TransferDocumentsBuiltEvent,
    TransferDocumentUpdatedEvent
@@ -329,6 +330,17 @@ export interface DocumentClientProtocol<TTransfer extends TransferElement, TDiag
     */
    onDocumentSaved(event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>): void;
 
+   /**
+    * Delivered when a subscribed document's text starts or stops differing
+    * from its file, as the server last knew it. Gated like
+    * {@link onDocumentSaved}; the answer at any one moment is the `dirty` of
+    * the documents the server sends. After a reconnect, a `DataSession`
+    * delivers here the answer of each document it restored, when that differs
+    * from the last this client was told: the flips while the connection was
+    * down reached no one.
+    */
+   onDocumentDirtyChanged(event: TransferDocumentDirtyChangedEvent): void;
+
    /**
     * Delivered when a document's backing file was removed. Separate from
     * {@link onDocumentUpdated} for the same reason as {@link onDocumentSaved},

package/src/data/events.ts

@@ -95,6 +95,22 @@ export type TransferDocumentSavedListener<
    TDiagnostic extends TransferDiagnostic = TransferDiagnostic
 > = (event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>) => void;
 
+/**
+ * Delivered on the data-server when a watched document's text starts or stops
+ * differing from its file, as the server last knew the file. The current
+ * answer rides on every transfer document the server sends as `dirty`; this
+ * carries only its changes, so a client that follows it needs no rebuild to
+ * learn of a save.
+ */
+export interface TransferDocumentDirtyChangedEvent {
+   /** Canonical URI, keyed as the subscription is. */
+   readonly uri: string;
+   readonly dirty: boolean;
+}
+
+/** Callback shape for `DataClientProtocol.onDocumentDirtyChanged`. */
+export type TransferDocumentDirtyChangedListener = (event: TransferDocumentDirtyChangedEvent) => void;
+
 /**
  * Delivered on the data-server when a document's backing file was removed.
  * Carries no document, and cannot: the state a

package/src/errors.ts

@@ -124,18 +124,33 @@ export const DOCUMENT_NOT_OPEN_ERROR_CODE = 1005;
 /** JSON-RPC code for {@link DuplicateClientIdError}. */
 export const DUPLICATE_CLIENT_ID_ERROR_CODE = 1006;
 
+/**
+ * The catalogue declaration behind {@link SessionClosedError}'s default
+ * sentence. It names no client id: the sentence can reach an end user, and the
+ * id stays in {@link SessionClosedErrorData.clientId} for whoever needs it.
+ */
+export const SESSION_CLOSED = defineMessage('hydranium/protocol/session-closed', 'The editing session has ended.');
+
+/** Structured payload carried in {@link SessionClosedError.data}. */
+export interface SessionClosedErrorData extends HydraniumMessageData {
+   readonly clientId: string;
+}
+
 /**
  * Thrown by every call on a client session after it ended, and by an open that
- * was still in flight when its session ended.
- *
- * The message names the client id, so it is addressed to whoever composes the
- * system rather than to an end user, and carries no message identity. A client
- * recognises it after an RPC with {@link isSessionClosedError}.
+ * was still in flight when its session ended: by the server for its sessions,
+ * and by a client-side `DataSession` once disposed, so a caller handles both
+ * the same way. A caller recognises it with {@link isSessionClosedError}, never
+ * by its sentence.
  */
-export class SessionClosedError extends ResponseError<{ readonly clientId: string }> {
-   /** `message` replaces the default sentence, for a caller that knows more than that the session is gone. */
-   constructor(clientId: string, message = `Client session ${clientId} is closed`) {
-      super(SESSION_CLOSED_ERROR_CODE, message, { clientId });
+export class SessionClosedError extends ResponseError<SessionClosedErrorData> {
+   /**
+    * `message` replaces the default English, for a caller that knows more than
+    * that the session is gone. The identity stays {@link SESSION_CLOSED}'s, so a
+    * translating renderer renders the catalogue sentence in its place.
+    */
+   constructor(clientId: string, message = SESSION_CLOSED.format()) {
+      super(SESSION_CLOSED_ERROR_CODE, message, { clientId, ...messageData(SESSION_CLOSED) });
       this.name = 'SessionClosedError';
       // `ResponseError` resets the prototype to its own; see `ConflictError`.
       Object.setPrototypeOf(this, SessionClosedError.prototype);

package/src/glsp-save-model-actions.ts

@@ -0,0 +1,59 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Declared field by field rather than extending GLSP's action types: this
+// package carries no GLSP dependency, and both GLSP heads already depend on it.
+// The fields are GLSP's own, so both actions are assignable to GLSP's
+// `RequestAction` and `ResponseAction`.
+
+/**
+ * A save of a diagram's model that the server answers, with a
+ * {@link ModelSavedAction} once the save has finished or a GLSP
+ * `RejectAction` when it fails.
+ *
+ * It carries what GLSP's `SaveModelAction` carries, and the server saves it the
+ * same way. GLSP's `SaveModelAction` is not answered: the server's only
+ * reply is a dirty-state change, which the client drops when the dirty flag
+ * does not change, so a client cannot tell which save an answer belongs to or
+ * whether a save failed.
+ */
+export interface RequestSaveModelAction {
+   kind: typeof RequestSaveModelAction.KIND;
+   /** The id the response echoes as its `responseId`. Empty until the dispatcher assigns one. */
+   requestId: string;
+   /** How long the receiver waits for its own handler, in milliseconds. */
+   timeout?: number;
+   /** The file to save to, as in GLSP's `SaveModelAction`; absent saves to the diagram's source. */
+   fileUri?: string;
+   /** GLSP's typing marker for the response. Never set. */
+   readonly _?: ModelSavedAction;
+}
+
+export namespace RequestSaveModelAction {
+   export const KIND = 'hydraniumRequestSaveModel';
+
+   export function create(options: { fileUri?: string; requestId?: string } = {}): RequestSaveModelAction {
+      return { kind: KIND, requestId: '', ...options };
+   }
+}
+
+/** The server's answer to a {@link RequestSaveModelAction} that saved. */
+export interface ModelSavedAction {
+   kind: typeof ModelSavedAction.KIND;
+   /** The `requestId` of the save this answers. The server's dispatcher sets it. */
+   responseId: string;
+}
+
+export namespace ModelSavedAction {
+   export const KIND = 'hydraniumModelSaved';
+
+   export function create(options: { responseId?: string } = {}): ModelSavedAction {
+      return { kind: KIND, responseId: '', ...options };
+   }
+}

package/src/index.ts

@@ -21,6 +21,7 @@ export * from './clock';
 export * from './data';
 export * from './browser-runtime';
 export * from './debouncer';
+export * from './glsp-save-model-actions';
 export * from './errors';
 export * from './host-diagnostics';
 export * from './logger';

package/src/messages/index.ts

@@ -25,7 +25,7 @@
 
 export * from './primitives';
 
-export { STALE_BASED_UPDATE } from '../errors';
+export { SESSION_CLOSED, STALE_BASED_UPDATE } from '../errors';
 export { DATA_SERVER_CONNECT_FAILED, DATA_SERVER_NOT_READY } from '../client/rpc-connection';
 export { DATA_SESSION_RESTORE_FAILED, DATA_SESSION_UNSAVED_LOST } from '../client/data-session';
 export {

package/src/testing/data-doubles.ts

@@ -37,6 +37,7 @@ import type { DataClientProtocol } from '../data/data-server-protocol';
 import type {
    ProjectsChangedEvent,
    TransferDocumentDeletedEvent,
+   TransferDocumentDirtyChangedEvent,
    TransferDocumentSavedEvent,
    TransferDocumentsBuiltEvent,
    TransferDocumentUpdatedEvent
@@ -132,6 +133,8 @@ export interface CapturingDataClient<
    readonly updates: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>[];
    /** Every `onDocumentSaved` event, in arrival order. */
    readonly saves: TransferDocumentSavedEvent<TTransfer, TDiagnostic>[];
+   /** Every `onDocumentDirtyChanged` event, in arrival order. */
+   readonly dirtyChanges: TransferDocumentDirtyChangedEvent[];
    /** Every `onDocumentDeleted` event, in arrival order. */
    readonly deletions: TransferDocumentDeletedEvent[];
    /** Every `onDocumentsBuilt` event, in arrival order. */
@@ -160,6 +163,7 @@ export function makeCapturingDataClient<
 >(overrides: Partial<DataClientProtocol<TTransfer, TDiagnostic, TProject>> = {}): CapturingDataClient<TTransfer, TDiagnostic, TProject> {
    const updates: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>[] = [];
    const saves: TransferDocumentSavedEvent<TTransfer, TDiagnostic>[] = [];
+   const dirtyChanges: TransferDocumentDirtyChangedEvent[] = [];
    const deletions: TransferDocumentDeletedEvent[] = [];
    const builds: TransferDocumentsBuiltEvent[] = [];
    const projectsChanges: ProjectsChangedEvent<TProject>[] = [];
@@ -174,6 +178,11 @@ export function makeCapturingDataClient<
          (event => {
             saves.push(event);
          }),
+      onDocumentDirtyChanged:
+         overrides.onDocumentDirtyChanged ??
+         (event => {
+            dirtyChanges.push(event);
+         }),
       onDocumentDeleted:
          overrides.onDocumentDeleted ??
          (event => {
@@ -190,5 +199,5 @@ export function makeCapturingDataClient<
             projectsChanges.push(event);
          })
    };
-   return { client, updates, saves, deletions, builds, projectsChanges };
+   return { client, updates, saves, dirtyChanges, deletions, builds, projectsChanges };
 }

package/src/testing/fake-clock.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type Clock, type Stopwatch, type Timed } from '../clock';
+import { type Clock, type Stopwatch, SystemClock } from '../clock';
 import { Disposable } from '../util';
 
 /** A {@link Clock} whose time only moves when the test calls {@link FakeClock.advance}. */
@@ -17,9 +17,13 @@ export interface FakeClock extends Clock {
     * whose deadline falls within the window — in chronological order, each at
     * its own deadline (so `now()` inside a callback reads the fire instant, not
     * the advance target). Timers scheduled by a callback fire too if they fall
-    * within the same window.
+    * within the same window. A {@link Clock.raceTimer} over a promise that
+    * settles through a chain still pending loses to the timer, so let that
+    * chain settle before advancing.
     */
    advance(ms: number): void;
+   /** How many {@link Clock.setTimer} timers have neither fired nor been disposed. */
+   pendingTimers(): number;
 }
 
 interface FakeTimer {
@@ -39,68 +43,79 @@ interface FakeTimer {
  *
  * Server-free and DI-free — lives in `@hydranium/protocol/testing` so every
  * head can bind it without pulling in a server package.
+ *
+ * The clock is a `SystemClock` with its time replaced, so its methods live on
+ * its prototype and a spread of it carries none of them. Replace one by
+ * assigning it onto the clock, or layer over the clock with `Object.create`.
  */
 export function makeFakeClock(options: { now?: number } = {}): FakeClock {
-   let current = options.now ?? 0;
-   const timers: FakeTimer[] = [];
+   return new VirtualClock(options.now ?? 0);
+}
+
+/**
+ * A `SystemClock` whose time, stopwatches and timers read one virtual axis, so
+ * the `measure` and `raceTimer` it inherits run on that axis too.
+ */
+class VirtualClock extends SystemClock implements FakeClock {
+   protected readonly timers: FakeTimer[] = [];
 
-   const makeStopwatch = (): Stopwatch => {
-      const start = current;
-      let lastLap = current;
+   constructor(protected current: number) {
+      super();
+   }
+
+   override now(): number {
+      return this.current;
+   }
+
+   override setTimer(callback: () => void, ms: number): Disposable {
+      const timer: FakeTimer = { at: this.current + ms, callback, disposed: false, fired: false };
+      this.timers.push(timer);
+      return Disposable.create(() => {
+         timer.disposed = true;
+      });
+   }
+
+   override stopwatch(): Stopwatch {
+      const read = (): number => this.current;
+      const start = read();
+      let lastLap = start;
       let stopped: number | undefined;
       return {
          get elapsedMs(): number {
-            return (stopped ?? current) - start;
+            return (stopped ?? read()) - start;
          },
          lap(): number {
-            const at = stopped ?? current;
+            const at = stopped ?? read();
             const split = at - lastLap;
             lastLap = at;
             return split;
          },
          stop(): number {
-            if (stopped === undefined) {
-               stopped = current;
-            }
+            stopped ??= read();
             return stopped - start;
          }
       };
-   };
+   }
 
-   return {
-      now: () => current,
-      setTimer(callback: () => void, ms: number): Disposable {
-         const timer: FakeTimer = { at: current + ms, callback, disposed: false, fired: false };
-         timers.push(timer);
-         return Disposable.create(() => {
-            timer.disposed = true;
-         });
-      },
-      stopwatch: makeStopwatch,
-      measure: (<T>(callback: () => T | Promise<T>): Timed<T> | Promise<Timed<T>> => {
-         const stopwatch = makeStopwatch();
-         const result = callback();
-         if (result instanceof Promise) {
-            return (result as Promise<T>).then(value => ({ result: value, elapsedMs: stopwatch.elapsedMs }));
-         }
-         return { result: result as T, elapsedMs: stopwatch.elapsedMs };
-      }) as Clock['measure'],
-      advance(ms: number): void {
-         const target = current + ms;
-         // Fire due timers one at a time, re-scanning after each so a callback
-         // that schedules a nearer timer still fires within this window.
-         for (;;) {
-            const next = timers
-               .filter(timer => !timer.disposed && !timer.fired && timer.at <= target)
-               .sort((left, right) => left.at - right.at)[0];
-            if (!next) {
-               break;
-            }
-            current = next.at;
-            next.fired = true;
-            next.callback();
+   pendingTimers(): number {
+      return this.timers.filter(timer => !timer.disposed && !timer.fired).length;
+   }
+
+   advance(ms: number): void {
+      const target = this.current + ms;
+      // Fire due timers one at a time, re-scanning after each so a callback
+      // that schedules a nearer timer still fires within this window.
+      for (;;) {
+         const next = this.timers
+            .filter(timer => !timer.disposed && !timer.fired && timer.at <= target)
+            .sort((left, right) => left.at - right.at)[0];
+         if (!next) {
+            break;
          }
-         current = target;
+         this.current = next.at;
+         next.fired = true;
+         next.callback();
       }
-   };
+      this.current = target;
+   }
 }

package/src/testing/node/index.ts

@@ -8,8 +8,7 @@
  ********************************************************************************/
 
 // Subpath barrel for `@hydranium/protocol/testing/node` — the test transports
-// that need a Node runtime: a crossed `PassThrough` pair and the in-process
-// `MessageConnection` bridge over it.
+// that need a Node runtime.
 //
 // Separate from `./testing` because a `PassThrough` is in `DuplexStreamPair`'s
 // exported type and `StreamMessageReader` comes from `vscode-jsonrpc/node`, so
@@ -20,3 +19,4 @@
 
 export * from './duplex-connection';
 export * from './duplex-stream';
+export * from './message-port-pair';

package/src/testing/node/message-port-pair.ts

@@ -0,0 +1,40 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { MessageChannel } from 'node:worker_threads';
+import type { TransferredMessagePort } from '../../client/post-message-transport';
+
+/**
+ * The two ends of a `worker_threads` `MessageChannel`, typed as the transferred
+ * browser ports `createMessagePortTransport` takes. Node's port clones and keeps
+ * order as a browser's does, which is what lets a headless test stand in for a
+ * worker.
+ *
+ * `dispose` closes both ports. Node reports that as a close and a browser port
+ * reports nothing, so a test that asserts on a close does so before teardown.
+ */
+export interface MessagePortPair {
+   readonly port1: TransferredMessagePort;
+   readonly port2: TransferredMessagePort;
+   dispose(): void;
+}
+
+export function makeMessagePortPair(): MessagePortPair {
+   const channel = new MessageChannel();
+   return {
+      // Node's port satisfies the structural type at runtime; the cast records
+      // one platform's port standing in for the other's.
+      port1: channel.port1 as unknown as TransferredMessagePort,
+      port2: channel.port2 as unknown as TransferredMessagePort,
+      dispose(): void {
+         channel.port1.close();
+         channel.port2.close();
+      }
+   };
+}

package/src/transfer-document.ts

@@ -43,6 +43,14 @@ export interface TransferDocument<TTransfer extends TransferElement, TDiagnostic
     */
    root?: TTransfer;
    diagnostics: TDiagnostic[];
+   /**
+    * Whether the server holds text for this document that its file does not,
+    * as the server last knew the file: set on every document a data server
+    * answers or sends that the server holds, and absent otherwise. A change
+    * after this snapshot arrives as `onDocumentDirtyChanged` to a client
+    * watching the document.
+    */
+   dirty?: boolean;
 }
 
 /**