@hydranium/glsp-server 1.0.0-next.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# `@hydranium/glsp-server`
+
+The graphical-editing head of [hydranium](../../README.md): a generic
+[GLSP](https://eclipse.dev/glsp/) server, built on `@eclipse-glsp/server`, that
+treats the shared Langium AST as its source of truth. Installed by the server
+process that already composes [`@hydranium/core`](../core); the translation to
+the diagram model is adopter-side, bound per diagram module.
+
+## What it gives you
+
+- **DI composition against the shared workspace.** `HydraniumGlspAppModule` binds
+  the `HydraniumTypes` token registry onto an already-composed
+  `ServerSharedServices` tree and exposes a `configureAdditionalBindings` hook;
+  `AbstractHydraniumGlspDiagramModule` and `bindDiagramLanguage` carry the per-diagram
+  half.
+- **Base model state, so an adopter binds a factory rather than a lifecycle:**
+  `AbstractHydraniumGlspState`, with the ready-made
+  `ReconcilingTransferHydraniumGlspState`, `ReconcilingMultiDocumentGlspState`
+  and `FullTextHydraniumGlspState` specialisations, plus `HydraniumGlspIndex`
+  over the GModel.
+- **Load / save against the live AST.** `HydraniumGlspStorage` loads a document
+  on diagram open and writes user operations back through the shared model
+  coordination layer, with `SaveConflictPolicy` deciding what a concurrent
+  external write means. `HydraniumGlspRecordingCommand` is the operation-handler
+  seam — the framework provides no base handler class.
+- **A submission and dispatch lifecycle that waits for the model.**
+  `HydraniumGlspSubmissionHandler` gates submit on the readiness event,
+  `HydraniumGlspServerActionDispatcher` adds timing and direction to dispatch,
+  and `HydraniumGlspComputedBoundsActionHandler` is handshake-aware.
+- **Diagram diagnostics for free.** `HydraniumGlspModelValidator` and
+  `diagnosticsToMarkers` project the language server's diagnostics onto GLSP
+  markers, so a validation error shows on the diagram and in the text editor from
+  one source.
+- **Two bringups from one composition:** `startGlspServer` over a socket at
+  `./node`, `startGlspServerInWorker` over a transferred `MessagePort` at
+  `./browser`. Both load the same framework overrides and adopter app modules.
+
+## Install
+
+```bash
+npm install @hydranium/glsp-server
+```
+
+Peers: `@eclipse-glsp/server` and `@eclipse-glsp/protocol`, `inversify` and
+`reflect-metadata` (the DI runtime — import `reflect-metadata` once at your entry
+point), `@hydranium/core`, `@hydranium/protocol`, `@hydranium/langium`,
+`vscode-jsonrpc` and `vscode-languageserver-types`. The only bundled runtime
+dependency is `uuid`. You must already have a composed hydranium shared services
+tree, a grammar, and a GModel factory of your own — there is no framework GModel
+factory.
+
+## Exports
+
+| subpath     | holds                                                                                                                                                                   | platform        |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
+| `.`         | Composition and the head itself: app / diagram modules, state, storage, submission, command, dispatcher, computed-bounds, validation, logging, `serviceIdentifier`.       | browser-neutral |
+| `./browser` | `startGlspServerInWorker` and `BrowserGlspServerOptions` — the web-worker bringup on GLSP's `WorkerServerLauncher`.                                                       | browser-only    |
+| `./node`    | `startGlspServer`, `GlspServerOptions`, `StartedGlspServer` — the socket bringup on GLSP's `SocketServerLauncher`.                                                        | Node-only       |
+| `./testing` | `makeGlspHarness`, `makeNoopGlspLogger`, `makeCapturingGlspLogger`.                                                                                                      | browser-neutral |
+
+This is the one head with three platform subpaths
+([why](../../docs/concepts/head-module-maps.md#hydraniumglsp-server--graphical-head)). `.` and
+`./testing` are
+gated as browser-neutral in CI (`scripts/check-neutral-bundles.mjs`), which
+depends on `.` naming only the bare `@eclipse-glsp/server` specifier: a slip back
+to a `/node` subpath in the portable tree fails that gate. `./browser` is
+browser-only rather than neutral — no portability is claimed for it. What the
+gate does and does not promise is [what "gated neutral" does and does not promise](../../docs/concepts/browser-hosting.md#a-note-on-what-gated-neutral-does-and-does-not-promise).
+Each subpath also has a `./lib/…` twin for consumers on
+`moduleResolution: "Node"`.
+
+## Getting oriented
+
+Build the app container, load `HydraniumGlspAppModule` plus your own app modules,
+and hand the result to `startGlspServer` (or `startGlspServerInWorker`, whose
+`context` is a required transferred `MessagePort`). Per diagram open, storage
+loads the document, your GModel factory renders it, and user operations travel
+back into the shared AST through the recording command, after which the GModel is
+re-derived and every listener on that document is notified. The module-by-module
+map is in
+[`docs/concepts/head-module-maps.md`](../../docs/concepts/head-module-maps.md);
+the worker bringup and its two bundler accommodations are in
+[`docs/concepts/browser-hosting.md`](../../docs/concepts/browser-hosting.md); the
+framework/adopter seams are in
+[`docs/concepts/framework-vs-adopter.md`](../../docs/concepts/framework-vs-adopter.md).
+The Theia-side client wiring lives in `@hydranium/glsp-client-theia`.
+
+## Status
+
+Alpha — pre-v0, not yet published. The API is not stable and may change without a
+deprecation cycle. See the [repository README](../../README.md) for the current
+status and known limitations.
+
+## License
+
+`MIT` — see this package's [`LICENSE`](./LICENSE). Third-party notices for the
+repository are recorded in [`NOTICE.md`](../../NOTICE.md).

package/lib/browser/index.d.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * 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 './start-glsp-server-in-worker.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAOlF,cAAc,kCAAkC,CAAC"}

package/lib/browser/index.js

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

package/lib/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,0EAA0E;AAC1E,2DAA2D;AAC3D,4EAA4E;AAC5E,4EAA4E;AAC5E,+DAA+D;AAC/D,cAAc,kCAAkC,CAAC"}

package/lib/browser/start-glsp-server-in-worker.d.ts

@@ -0,0 +1,121 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { type Logger as GlspLogger, type ServerModule } from '@eclipse-glsp/server/browser.js';
+import { type ContainerModule } from 'inversify';
+import type { Logger } from '@hydranium/protocol';
+import type { IntegratedServer } from '@hydranium/core';
+/**
+ * A `MessagePort` the host transferred into the worker, described structurally.
+ *
+ * This package inherits `tsconfig.base.json`'s `lib: ["ES2022"]` and so compiles
+ * without the DOM lib, which is what keeps `document` / `window` compile errors
+ * here — so `MessagePort` has no name either and the contract has to be spelled
+ * out.
+ *
+ * **The member set is chosen to admit a `MessagePort` and REJECT a `Worker` or
+ * the worker global**, both of which the launcher's own reader would otherwise
+ * accept. Only a port needs starting, so `start` is what tells the three apart,
+ * and naming it here turns "never bind a head to the global" from a rule in a
+ * document into a compile error at the call site.
+ *
+ * **That compile error happens at the ADOPTER, not here.** This project resolves
+ * neither `MessagePort` nor `Worker` as a type, so nothing in this package can
+ * demonstrate the rejection; a host compiling its worker against `lib.webworker`
+ * (or a page against `lib.dom`) is where the names resolve and the guard bites.
+ * Measured there: passing the worker global fails with `Property 'start' is
+ * missing in type 'DedicatedWorkerGlobalScope'`.
+ *
+ * `addEventListener` is not a discriminator — `postMessage` plus `start` already
+ * excludes the other two — and nothing in this module calls any of the three
+ * (the reader assigns `onmessage`, which starts a port implicitly). It is listed
+ * because it is part of what the reader uses, so the interface reads as the
+ * contract rather than as a minimal trick.
+ */
+export interface TransferredMessagePort {
+    postMessage(message: unknown): void;
+    addEventListener(type: 'message', listener: (event: unknown) => void, options?: unknown): void;
+    start(): void;
+}
+/**
+ * Options for {@link startGlspServerInWorker}.
+ *
+ * The socket variant's options have no counterpart here and are deliberately
+ * absent rather than ignored: there is no port to bind, none to discover, and
+ * so nothing to publish over an LSP connection.
+ *
+ * @see {@link startGlspServerInWorker} for the lifecycle semantics.
+ */
+export interface BrowserGlspServerOptions {
+    /**
+     * The port the host transferred into the worker for this head.
+     *
+     * **Required, and that is the whole point.** GLSP's
+     * `WorkerServerLauncher.createConnection` falls back to the worker global
+     * when it is omitted, and a head on the global receives every other head's
+     * traffic — `BrowserMessageReader` filters nothing, so this is not a race
+     * under load but every message delivered to the wrong reader. The global is
+     * unusable even for a single head, because the launcher posts its startup
+     * string through the global `postMessage` regardless of the connection it
+     * was given, and no JSON-RPC reader can parse that.
+     */
+    readonly context: TransferredMessagePort;
+    /**
+     * Adopter-supplied logger factory. Called once per Inversify resolution
+     * (with `caller` set to the requesting parent's class name) AND once
+     * per `LoggerFactory` invocation.
+     *
+     * The GLSP log threshold is a property of the logger this returns, and there
+     * is deliberately no launcher-level `logLevel` beside it — see the socket
+     * variant's note on the same member.
+     */
+    readonly createLogger: (caller?: string) => GlspLogger;
+    /**
+     * The GLSP {@link ServerModule} with per-diagram modules pre-configured via
+     * `new ServerModule().configureDiagramModule(...)`.
+     */
+    readonly serverModule: ServerModule;
+    /**
+     * Additional Inversify modules to load on the app container AFTER GLSP's
+     * own app module and the framework overrides. Adopters wire language-services
+     * bindings (e.g. their own shared-services symbol) here.
+     */
+    readonly appModules?: ReadonlyArray<ContainerModule>;
+    /**
+     * Optional framework-lifecycle logger, for the launcher's own bringup and
+     * failure lines. The GLSP container's logger handles application-level logs.
+     */
+    readonly logger?: Logger;
+}
+/**
+ * Start a GLSP head on a transferred `MessagePort` inside a web worker, with no
+ * Node runtime and no backend process.
+ *
+ * The worker counterpart of `startGlspServer`,
+ * and deliberately a separate function rather than a mode of it. The two share
+ * a shape — app module, framework overrides, adopter modules, resolve launcher,
+ * configure the {@link ServerModule}, start — and almost nothing else: a
+ * different launcher, a different upstream `createAppModule` whose options carry
+ * no `fileLog`, and no `'listening'` event to resolve readiness on. Over half of
+ * the socket options are meaningless here, so threading a flag would leave a
+ * function whose contract depends on which branch the caller is in.
+ *
+ * Returns an {@link IntegratedServer} — the socket variant's `port` is the one
+ * member a worker head has no answer for, so it is absent rather than
+ * `undefined`.
+ *
+ * - `started` resolves once the launcher has built its connection and the
+ *   server instance behind it, which is CHECKED rather than assumed — see
+ *   below. There is no transport handshake to wait on: the port arrived live,
+ *   and the launcher's own readiness signal is a string it posts on the worker
+ *   global, which nothing here reads.
+ * - `stopped` resolves when the connection closes, and rejects on a connection
+ *   error.
+ */
+export declare function startGlspServerInWorker(options: BrowserGlspServerOptions): IntegratedServer;
+//# sourceMappingURL=start-glsp-server-in-worker.d.ts.map

package/lib/browser/start-glsp-server-in-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-glsp-server-in-worker.d.ts","sourceRoot":"","sources":["../../src/browser/start-glsp-server-in-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,KAAK,MAAM,IAAI,UAAU,EACzB,KAAK,YAAY,EAInB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAIxD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,sBAAsB;IACpC,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACpC,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/F,KAAK,IAAI,IAAI,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,wBAAwB;IACtC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC;;;;;;;;OAQG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,UAAU,CAAC;IACvD;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACrD;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,gBAAgB,CAsE3F"}

package/lib/browser/start-glsp-server-in-worker.js

@@ -0,0 +1,102 @@
+/********************************************************************************
+ * 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 { WorkerServerLauncher, createAppModule } from '@eclipse-glsp/server/browser.js';
+import { Container } from 'inversify';
+import { createGlspFrameworkOverrides } from '../launcher/glsp-framework-overrides.js';
+import { createGlspServerOverrides } from '../launcher/glsp-server-overrides.js';
+/**
+ * Start a GLSP head on a transferred `MessagePort` inside a web worker, with no
+ * Node runtime and no backend process.
+ *
+ * The worker counterpart of `startGlspServer`,
+ * and deliberately a separate function rather than a mode of it. The two share
+ * a shape — app module, framework overrides, adopter modules, resolve launcher,
+ * configure the {@link ServerModule}, start — and almost nothing else: a
+ * different launcher, a different upstream `createAppModule` whose options carry
+ * no `fileLog`, and no `'listening'` event to resolve readiness on. Over half of
+ * the socket options are meaningless here, so threading a flag would leave a
+ * function whose contract depends on which branch the caller is in.
+ *
+ * Returns an {@link IntegratedServer} — the socket variant's `port` is the one
+ * member a worker head has no answer for, so it is absent rather than
+ * `undefined`.
+ *
+ * - `started` resolves once the launcher has built its connection and the
+ *   server instance behind it, which is CHECKED rather than assumed — see
+ *   below. There is no transport handshake to wait on: the port arrived live,
+ *   and the launcher's own readiness signal is a string it posts on the worker
+ *   global, which nothing here reads.
+ * - `stopped` resolves when the connection closes, and rejects on a connection
+ *   error.
+ */
+export function startGlspServerInWorker(options) {
+    const lifecycle = options.logger;
+    // GLSP's own app module first, as on Node, so the framework tracks the
+    // resolved GLSP version's app bindings instead of re-deriving them. This is
+    // the BROWSER build's `createAppModule`, whose options are `LoggerConfigOptions`
+    // — no `fileLog`, because there is no file to log to. `consoleLog` is forced
+    // off so GLSP binds a throwaway NullLogger; the overrides below replace it
+    // with the adopter's, which is also why no log level is passed here: with
+    // `consoleLog` off, GLSP discards it, and the binding it would have
+    // configured is unbound a line later.
+    const glspAppModule = createAppModule({ consoleLog: false });
+    const appContainer = new Container();
+    appContainer.load(glspAppModule, createGlspFrameworkOverrides(options.createLogger), ...(options.appModules ?? []));
+    const launcher = appContainer.resolve(WorkerServerLauncher);
+    // Additional module rather than an app-container binding, as on Node: the
+    // launcher loads these into the per-connection SERVER container, the only
+    // tier where the adopter's `ServerModule` binding of `GLSPServer` is
+    // rebindable.
+    launcher.configure(options.serverModule, createGlspServerOverrides());
+    try {
+        // Upstream declares `WorkerLaunchOptions.context` as `Worker`, narrower
+        // than the `MessagePort | Worker | DedicatedWorkerGlobalScope` its own
+        // `BrowserMessageReader` accepts — so the value that is CORRECT here is
+        // the one the declaration names as wrong.
+        //
+        // **The cast is currently redundant, and is kept deliberately.** `Worker`
+        // does not resolve under this package's `lib`, so `skipLibCheck` leaves
+        // the option an error type and the assignment compiles without it —
+        // measured, not assumed. Removing it would mean this file type-checks by
+        // the same accident that let upstream's own `?? self` default pass, and
+        // would break the day the name resolves. The cast states the intent
+        // instead, and costs one line to do so.
+        const launchOptions = { context: options.context };
+        // `start` resolves only when the connection closes, so it is the `stopped`
+        // promise. The launcher builds the connection and the server instance
+        // synchronously before returning it, which is what makes "we got here"
+        // equal to "accepting traffic".
+        const stoppedPromise = Promise.resolve(launcher.start(launchOptions));
+        // Attached here and not left to the caller: a worker has no console
+        // anyone is watching, so a connection error on a `stopped` nobody awaits
+        // becomes an unhandled rejection that reaches no one. The handler also
+        // marks the promise handled, which the caller's own `await` still sees.
+        stoppedPromise.catch((error) => lifecycle?.error('[GlspServer] Worker connection error:', error));
+        // The `started`-equals-synchronous-construction assumption above is
+        // upstream's, so it is verified rather than trusted: `run` awaiting
+        // anything before building the connection would leave `started` resolving
+        // on a head that cannot yet answer, and a client's first request would
+        // hang with nothing logged. The field is `protected`, reached by property
+        // indexing as the socket launcher's `netServer` is.
+        const connection = launcher.connection;
+        if (connection === undefined) {
+            const error = new Error('startGlspServerInWorker: the launcher built no connection synchronously — ' +
+                'WorkerServerLauncher.run has become asynchronous and readiness now needs a real signal');
+            lifecycle?.error(`[GlspServer] ${error.message}`);
+            return { started: Promise.reject(error), stopped: stoppedPromise };
+        }
+        lifecycle?.info('[GlspServer] Ready to accept client requests on the transferred port');
+        return { started: Promise.resolve(), stopped: stoppedPromise };
+    }
+    catch (error) {
+        lifecycle?.error('Error in GLSP server worker launcher:', error);
+        return { started: Promise.reject(error), stopped: Promise.resolve() };
+    }
+}
+//# sourceMappingURL=start-glsp-server-in-worker.js.map

package/lib/browser/start-glsp-server-in-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-glsp-server-in-worker.js","sourceRoot":"","sources":["../../src/browser/start-glsp-server-in-worker.ts"],"names":[],"mappings":"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"}

package/lib/command/hydranium-glsp-recording-command.d.ts

@@ -0,0 +1,132 @@
+/********************************************************************************
+ * Copyright (c) 2023-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 AnyObject, type JsonModelState, JsonRecordingCommand, type MaybePromise } from '@eclipse-glsp/server';
+import { type AstNode } from '@hydranium/langium';
+import { type AbstractHydraniumGlspState } from '../state/abstract-hydranium-glsp-state.js';
+/**
+ * Source-model state shape consumed by {@link HydraniumGlspRecordingCommand}.
+ * The intersection ties together GLSP's read-side
+ * {@link JsonModelState.sourceModel} getter with the framework's typed
+ * `logger` and `sourceUri` accessors (used for time-labelled logging) and
+ * the lifted `updateSourceModel` abstract from
+ * {@link AbstractHydraniumGlspState.updateSourceModel}. Adopter states satisfy both
+ * naturally by implementing `JsonModelState<TSourceModel>` on
+ * their framework-state subclass.
+ */
+export type HydraniumGlspRecordingState<TSourceModel extends AnyObject> = AbstractHydraniumGlspState<AstNode, TSourceModel> & JsonModelState<TSourceModel>;
+/**
+ * GLSP {@link JsonRecordingCommand} base shared by all hydranium adopters.
+ * Adds two things on top of GLSP's class:
+ *
+ *  1. A **time-labelled execute wrapper** so log lines record how long a
+ *     user-facing operation takes end-to-end — including the `postChange`
+ *     source-model update that re-parses the document. Otherwise the diff +
+ *     patch + persist work happens silently and is hard to attribute when
+ *     something is slow.
+ *  2. A typed `state` field that exposes `updateSourceModel` for the
+ *     `postChange` bridge AND the framework `logger` for time-labelled
+ *     logging. GLSP's base class only types `modelState: JsonModelState`,
+ *     which lacks the framework's logger surface.
+ *
+ * **Optional undo/redo bridge hooks.** An adopter command can supply
+ * `undoAction` / `redoAction` callbacks invoked alongside the patch apply, to
+ * re-emit a side-effect the patch itself does not carry. Provided as optional
+ * constructor args so adopters get that composition surface without
+ * subclassing. Operation handlers that don't need bridge callbacks omit them.
+ *
+ * **postChange semantics.** GLSP's `JsonRecordingCommand.postChange` calls
+ * `modelState.updateSourceModel(newModel)` with the model only. The
+ * framework lift overrides `postChange` so it also threads the based-on
+ * version captured at command start — letting the downstream
+ * `ModelService.update` opt into the `ConflictError` gate. Undo / redo
+ * postChange calls run with version `undefined` (no gating): the user
+ * authored against the recorded patch, not against a specific server
+ * version, so re-applying it should succeed regardless of intervening
+ * edits. The recorded patch itself encodes the semantic intent.
+ */
+export declare class HydraniumGlspRecordingCommand<TSourceModel extends AnyObject> extends JsonRecordingCommand<TSourceModel> {
+    /** Human-readable label for the operation; appears in the timing-pair log line. */
+    protected readonly label: string;
+    /** Optional bridge invoked alongside undo patch application; for adopters
+     *  that need to re-emit a side-effect the patch does not carry. */
+    protected readonly undoAction?: (() => MaybePromise<void>) | undefined;
+    /** Optional bridge invoked alongside redo patch application. */
+    protected readonly redoAction?: (() => MaybePromise<void>) | undefined;
+    protected modelState: HydraniumGlspRecordingState<TSourceModel>;
+    /**
+     * Based-on version captured at {@link execute} start; threaded into
+     * {@link postChange} so {@link AbstractHydraniumGlspState.updateSourceModel}
+     * sees the version the user authored against. Cleared after `execute`
+     * returns so undo / redo paths fall through to `updateSourceModel`
+     * without a version (no gating).
+     */
+    protected activeVersion?: number;
+    /**
+     * Source-model snapshots captured at {@link execute} — the state the
+     * command left ({@link afterSnapshot}) and the state it started from
+     * ({@link beforeSnapshot}). {@link undo} / {@link redo} reconcile the
+     * recorded transition against the *current* source model via the state's
+     * {@link AbstractHydraniumGlspState.conflictResolver}, so under the default
+     * reconciling policy a concurrent edit to another field survives and a
+     * same-field collision is dropped rather than clobbered.
+     */
+    protected beforeSnapshot?: TSourceModel;
+    protected afterSnapshot?: TSourceModel;
+    constructor(modelState: HydraniumGlspRecordingState<TSourceModel>, 
+    /** Human-readable label for the operation; appears in the timing-pair log line. */
+    label: string, doExecute: () => MaybePromise<void>, 
+    /** Optional bridge invoked alongside undo patch application; for adopters
+     *  that need to re-emit a side-effect the patch does not carry. */
+    undoAction?: (() => MaybePromise<void>) | undefined, 
+    /** Optional bridge invoked alongside redo patch application. */
+    redoAction?: (() => MaybePromise<void>) | undefined);
+    /**
+     * Time-label the full execute path: pre-state snapshot + `doExecute` +
+     * post-state snapshot + patch-derive + `postChange` (which writes back
+     * via {@link AbstractHydraniumGlspState.updateSourceModel}). The label combines
+     * the operation name with the source-uri-stamped logger.
+     *
+     * Captures {@link AbstractHydraniumGlspState.version} at start so {@link postChange}
+     * can thread the based-on version into `updateSourceModel`. The capture
+     * is `try`/`finally`-scoped so undo / redo paths invoked later do not
+     * see a stale captured version.
+     */
+    execute(): Promise<void>;
+    /**
+     * Override of GLSP's {@link JsonRecordingCommand.postChange} so the
+     * call to {@link AbstractHydraniumGlspState.updateSourceModel} threads the
+     * captured based-on version alongside the new model.
+     *
+     * During {@link execute} the version is the snapshot captured at
+     * command start; during {@link undo} / {@link redo} it is `undefined`
+     * — replaying a recorded patch does not author against a specific
+     * server version, so no gate applies.
+     */
+    protected postChange(newModel: TSourceModel): MaybePromise<void>;
+    /**
+     * Reconcile the recorded `after → before` transition against the
+     * *current* source model via the state's
+     * {@link AbstractHydraniumGlspState.conflictResolver}, invoke the optional adopter
+     * `undoAction`, and persist via `postChange`. Under the default reconciling
+     * policy the revert is replayed guarded by `test` ops, so a concurrent edit
+     * to another field is preserved (merged) and a same-field collision is
+     * dropped rather than clobbered; a force policy clobbers (last-writer-wins).
+     * On anything but a clean merge the undo is a logged no-op — the side-effect
+     * bridge and `postChange` only run on a merged result, preserving a
+     * "bridge before commit" order.
+     */
+    undo(): Promise<void>;
+    /**
+     * Reconcile the recorded `before → after` transition against the current
+     * source model, invoke the optional adopter `redoAction`, and persist via
+     * `postChange`. Same guarded merge / drop semantics as {@link undo}.
+     */
+    redo(): Promise<void>;
+}
+//# sourceMappingURL=hydranium-glsp-recording-command.d.ts.map

package/lib/command/hydranium-glsp-recording-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydranium-glsp-recording-command.d.ts","sourceRoot":"","sources":["../../src/command/hydranium-glsp-recording-command.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,oBAAoB,EAAE,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpH,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,0BAA0B,EAAE,MAAM,2CAA2C,CAAC;AAE5F;;;;;;;;;GASG;AACH,MAAM,MAAM,2BAA2B,CAAC,YAAY,SAAS,SAAS,IAAI,0BAA0B,CAAC,OAAO,EAAE,YAAY,CAAC,GACxH,cAAc,CAAC,YAAY,CAAC,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,6BAA6B,CAAC,YAAY,SAAS,SAAS,CAAE,SAAQ,oBAAoB,CAAC,YAAY,CAAC;IA0B/G,mFAAmF;IACnF,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM;IAEhC;uEACmE;IACnE,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAE,MAAM,YAAY,CAAC,IAAI,CAAC;IACxD,gEAAgE;IAChE,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAE,MAAM,YAAY,CAAC,IAAI,CAAC;IAhC3D,UAAkB,UAAU,EAAE,2BAA2B,CAAC,YAAY,CAAC,CAAC;IAExE;;;;;;OAMG;IACH,SAAS,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEjC;;;;;;;;OAQG;IACH,SAAS,CAAC,cAAc,CAAC,EAAE,YAAY,CAAC;IACxC,SAAS,CAAC,aAAa,CAAC,EAAE,YAAY,CAAC;gBAGpC,UAAU,EAAE,2BAA2B,CAAC,YAAY,CAAC;IACrD,mFAAmF;IAChE,KAAK,EAAE,MAAM,EAChC,SAAS,EAAE,MAAM,YAAY,CAAC,IAAI,CAAC;IACnC;uEACmE;IAChD,UAAU,CAAC,GAAE,MAAM,YAAY,CAAC,IAAI,CAAC,aAAA;IACxD,gEAAgE;IAC7C,UAAU,CAAC,GAAE,MAAM,YAAY,CAAC,IAAI,CAAC,aAAA;IAK3D;;;;;;;;;;OAUG;IACY,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAavC;;;;;;;;;OASG;cACgB,UAAU,CAAC,QAAQ,EAAE,YAAY,GAAG,YAAY,CAAC,IAAI,CAAC;IAIzE;;;;;;;;;;;OAWG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBpC;;;;OAIG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAgBtC"}