@hydranium/glsp-server

The graphical-editing head of hydranium: a generic 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; 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 SaveDeliveryPolicy deciding whether the save action awaits the write. 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

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.

This head needs one line in your own root manifest, and the install works without it right up until the server starts. @eclipse-glsp/* depends on [email protected] exactly, while the Langium chain under hydranium pins the transport at 9.0.1 — the version this package declares as its peer. Two physical copies in one process throw Unknown parameter structure auto during GLSP server init, and no peer declaration can prevent a nested copy. Add an overrides block collapsing the chain and reinstall from scratch; Requirements gives the exact block.

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). . 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. 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; the worker bringup and its two bundler accommodations are in docs/concepts/browser-hosting.md; the framework/adopter seams are in 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 for the current status and known limitations.

License

MIT — see this package's LICENSE. Third-party notices for the repository are recorded in NOTICE.md.