@hydranium/cli 1.0.0-next.38 → 1.0.0-next.381

package/templates/server/test/__GRAMMAR_ID__-diagram.test.ts

@@ -0,0 +1,388 @@
+// The starter diagram, run the way a client runs it: an in-process GLSP server
+// opens a document. A create-node operation adds a node, and an undo and a redo
+// take it out and put it back; every step must keep the nodes the document
+// already had, and its comments, since the diagram writes the document from its
+// AST, which carries none. A delete removes a node with the references to it, or
+// an edge's reference. A reference into another document resolves, even
+// when the diagram opened its document before the workspace was up, and draws
+// an edge to an external node standing for its target. Each node is placed a
+// row above its target, and a cycle does not stop the placing. A diagnostic
+// reaches the diagram as a marker on its node.
+
+import 'reflect-metadata';
+import {
+   type Action,
+   CreateNodeOperation,
+   DeleteElementOperation,
+   GEdge,
+   GModelFactory,
+   GNode,
+   ModelValidator,
+   RedoAction,
+   ServerModule,
+   SetDirtyStateAction,
+   UndoAction
+} from '@eclipse-glsp/server';
+import { initializeWorkspaceProgrammatically } from '@hydranium/core';
+import { makeScratchWorkspace, type ScratchWorkspace } from '@hydranium/core/testing/node';
+import { HydraniumGlspAppModule } from '@hydranium/glsp-server';
+import { type GlspHarness, makeGlspHarness } from '@hydranium/glsp-server/testing';
+import { URI } from '@hydranium/langium';
+import { waitFor } from '@hydranium/protocol/testing';
+import {
+   __GRAMMAR_ID_CONST___DIAGRAM_TYPE,
+   __GRAMMAR_ID_CONST___EDGE_TYPE,
+   __GRAMMAR_ID_CONST___EXTERNAL_NODE_TYPE,
+   __GRAMMAR_ID_CONST___NODE_TYPE
+} from '__PROTOCOL_PACKAGE__';
+import { afterEach, describe, expect, it } from 'vitest';
+import { __GRAMMAR__DiagramModule } from '../src/glsp/__GRAMMAR_ID__/diagram-module.js';
+import { __GRAMMAR__GModelFactory } from '../src/glsp/__GRAMMAR_ID__/gmodel-factory.js';
+import type { __GRAMMAR__GlspState } from '../src/glsp/__GRAMMAR_ID__/state.js';
+import { is__ENTRY_RULE__ } from '../src/language-server/ast.js';
+import { createServices } from '../src/node/services.js';
+
+let workspace: ScratchWorkspace | undefined;
+let diagram: GlspHarness<__GRAMMAR__GlspState> | undefined;
+
+afterEach(() => {
+   diagram?.dispose();
+   workspace?.dispose();
+   diagram = undefined;
+   workspace = undefined;
+});
+
+/** Send `action` and wait for the dirty state the server answers it with, which it sends once the edit is written. */
+async function send(harness: GlspHarness<__GRAMMAR__GlspState>, action: Action, reason: string): Promise<void> {
+   const before = harness.actions.length;
+   harness.dispatch(action);
+   await waitFor(() => harness.actions.slice(before).some(sent => SetDirtyStateAction.is(sent) && sent.reason === reason), {
+      message: `no '${reason}' dirty state`
+   });
+}
+
+describe('__GRAMMAR__ diagram', () => {
+   it('creates a node after the existing ones, keeping their comments, and undoes and redoes it', async () => {
+      workspace = makeScratchWorkspace({ prefix: '__GRAMMAR_ID__-diagram-' });
+      const original = '// keep this comment\nnode first -> second\n// about second\nnode second';
+      const file = workspace.write('model.__EXTENSION__', original);
+      const { shared } = createServices();
+      await initializeWorkspaceProgrammatically(shared, workspace.root);
+      diagram = makeGlspHarness<__GRAMMAR__GlspState>({
+         serverModule: new ServerModule().configureDiagramModule(new __GRAMMAR__DiagramModule()),
+         diagramType: __GRAMMAR_ID_CONST___DIAGRAM_TYPE,
+         appModules: [new HydraniumGlspAppModule({ shared })]
+      });
+      await diagram.start();
+      await diagram.openDocument(file);
+      const uri = workspace.uri('model.__EXTENSION__');
+      const text = (): string | undefined => shared.workspace.TextDocuments.get(uri)?.getText();
+
+      await send(diagram, CreateNodeOperation.create(__GRAMMAR_ID_CONST___NODE_TYPE), 'operation');
+      const created = text();
+      await send(diagram, UndoAction.create(), 'undo');
+      const undone = text();
+      await send(diagram, RedoAction.create(), 'redo');
+
+      expect({ created, undone, redone: text() }).toEqual({
+         created: `${original}\nnode Node`,
+         undone: original,
+         redone: `${original}\nnode Node`
+      });
+   });
+
+   it('deletes a node with the references to it, and an edge with its reference, undoably', async () => {
+      workspace = makeScratchWorkspace({ prefix: '__GRAMMAR_ID__-diagram-' });
+      const original = 'node first -> second\nnode second\nnode third -> first';
+      const file = workspace.write('model.__EXTENSION__', original);
+      const { shared } = createServices();
+      await initializeWorkspaceProgrammatically(shared, workspace.root);
+      const harness = makeGlspHarness<__GRAMMAR__GlspState>({
+         serverModule: new ServerModule().configureDiagramModule(new __GRAMMAR__DiagramModule()),
+         diagramType: __GRAMMAR_ID_CONST___DIAGRAM_TYPE,
+         appModules: [new HydraniumGlspAppModule({ shared })]
+      });
+      diagram = harness;
+      await harness.start();
+      await harness.openDocument(file);
+      const uri = workspace.uri('model.__EXTENSION__');
+      const text = (): string | undefined => shared.workspace.TextDocuments.get(uri)?.getText();
+      const idOf = (type: string, index: number): string => harness.state.root.children.filter(child => child.type === type)[index].id;
+
+      await send(harness, DeleteElementOperation.create([idOf(__GRAMMAR_ID_CONST___NODE_TYPE, 1)]), 'operation');
+      const nodeDeleted = text();
+      await send(harness, UndoAction.create(), 'undo');
+      const undone = text();
+      // The edge third -> first.
+      await send(harness, DeleteElementOperation.create([idOf(__GRAMMAR_ID_CONST___EDGE_TYPE, 1)]), 'operation');
+
+      expect({ nodeDeleted, undone, edgeDeleted: text() }).toEqual({
+         nodeDeleted: 'node first\nnode third -> first',
+         undone: original,
+         edgeDeleted: 'node first -> second\nnode second\nnode third'
+      });
+   });
+
+   it('deletes the drawn node of a repeated name, keeping the references the remaining node resolves', async () => {
+      workspace = makeScratchWorkspace({ prefix: '__GRAMMAR_ID__-diagram-' });
+      const file = workspace.write('model.__EXTENSION__', 'node first -> second\nnode first\nnode second -> first');
+      const { shared } = createServices();
+      await initializeWorkspaceProgrammatically(shared, workspace.root);
+      const harness = makeGlspHarness<__GRAMMAR__GlspState>({
+         serverModule: new ServerModule().configureDiagramModule(new __GRAMMAR__DiagramModule()),
+         diagramType: __GRAMMAR_ID_CONST___DIAGRAM_TYPE,
+         appModules: [new HydraniumGlspAppModule({ shared })]
+      });
+      diagram = harness;
+      await harness.start();
+      await harness.openDocument(file);
+
+      await send(harness, DeleteElementOperation.create([harness.state.root.children[0].id]), 'operation');
+
+      expect(shared.workspace.TextDocuments.get(workspace.uri('model.__EXTENSION__'))?.getText()).toBe('node first\nnode second -> first');
+   });
+
+   it('deletes a node, keeping the references another document declares the name for', async () => {
+      workspace = makeScratchWorkspace({ prefix: '__GRAMMAR_ID__-diagram-' });
+      workspace.write('other.__EXTENSION__', 'node second');
+      const file = workspace.write('model.__EXTENSION__', 'node first -> second\nnode second');
+      const { shared } = createServices();
+      await initializeWorkspaceProgrammatically(shared, workspace.root);
+      const harness = makeGlspHarness<__GRAMMAR__GlspState>({
+         serverModule: new ServerModule().configureDiagramModule(new __GRAMMAR__DiagramModule()),
+         diagramType: __GRAMMAR_ID_CONST___DIAGRAM_TYPE,
+         appModules: [new HydraniumGlspAppModule({ shared })]
+      });
+      diagram = harness;
+      await harness.start();
+      await harness.openDocument(file);
+
+      await send(harness, DeleteElementOperation.create([harness.state.root.children[1].id]), 'operation');
+
+      expect(shared.workspace.TextDocuments.get(workspace.uri('model.__EXTENSION__'))?.getText()).toBe('node first -> second');
+   });
+
+   it("draws a repeated name once, as its first node with that node's edge", async () => {
+      workspace = makeScratchWorkspace({ prefix: '__GRAMMAR_ID__-diagram-' });
+      const file = workspace.write('model.__EXTENSION__', 'node a\nnode a -> b\nnode b');
+      const { shared } = createServices();
+      await initializeWorkspaceProgrammatically(shared, workspace.root);
+      diagram = makeGlspHarness<__GRAMMAR__GlspState>({
+         serverModule: new ServerModule().configureDiagramModule(new __GRAMMAR__DiagramModule()),
+         diagramType: __GRAMMAR_ID_CONST___DIAGRAM_TYPE,
+         appModules: [new HydraniumGlspAppModule({ shared })]
+      });
+      await diagram.start();
+      await diagram.openDocument(file);
+
+      // The first `a` references nothing, so no edge, and both nodes share a row.
+      const children = diagram.state.root.children;
+      expect(children.map(child => ({ type: child.type, position: child instanceof GNode ? child.position : undefined }))).toEqual([
+         { type: __GRAMMAR_ID_CONST___NODE_TYPE, position: { x: 0, y: 0 } },
+         { type: __GRAMMAR_ID_CONST___NODE_TYPE, position: { x: 200, y: 0 } }
+      ]);
+   });
+
+   it("draws a node named like another node's label or edge", async () => {
+      workspace = makeScratchWorkspace({ prefix: '__GRAMMAR_ID__-diagram-' });
+      const file = workspace.write('model.__EXTENSION__', 'node a -> b\nnode b\nnode a_name\nnode a_target');
+      const { shared } = createServices();
+      await initializeWorkspaceProgrammatically(shared, workspace.root);
+      diagram = makeGlspHarness<__GRAMMAR__GlspState>({
+         serverModule: new ServerModule().configureDiagramModule(new __GRAMMAR__DiagramModule()),
+         diagramType: __GRAMMAR_ID_CONST___DIAGRAM_TYPE,
+         appModules: [new HydraniumGlspAppModule({ shared })]
+      });
+      await diagram.start();
+      await diagram.openDocument(file);
+
+      expect(diagram.state.root.children.map(child => child.type)).toEqual([
+         __GRAMMAR_ID_CONST___NODE_TYPE,
+         __GRAMMAR_ID_CONST___NODE_TYPE,
+         __GRAMMAR_ID_CONST___NODE_TYPE,
+         __GRAMMAR_ID_CONST___NODE_TYPE,
+         __GRAMMAR_ID_CONST___EDGE_TYPE
+      ]);
+   });
+
+   it('draws a reference into another document as an edge to one external node', async () => {
+      workspace = makeScratchWorkspace({ prefix: '__GRAMMAR_ID__-diagram-' });
+      workspace.write('declaring.__EXTENSION__', 'node second');
+      const file = workspace.write('referencing.__EXTENSION__', 'node first -> second\nnode third -> second');
+      const { shared } = createServices();
+      await initializeWorkspaceProgrammatically(shared, workspace.root);
+      diagram = makeGlspHarness<__GRAMMAR__GlspState>({
+         serverModule: new ServerModule().configureDiagramModule(new __GRAMMAR__DiagramModule()),
+         diagramType: __GRAMMAR_ID_CONST___DIAGRAM_TYPE,
+         appModules: [new HydraniumGlspAppModule({ shared })]
+      });
+      await diagram.start();
+      await diagram.openDocument(file);
+
+      const children = diagram.state.root.children;
+      const external = children.find(child => child.type === __GRAMMAR_ID_CONST___EXTERNAL_NODE_TYPE);
+      expect(children.map(child => child.type)).toEqual([
+         __GRAMMAR_ID_CONST___NODE_TYPE,
+         __GRAMMAR_ID_CONST___NODE_TYPE,
+         __GRAMMAR_ID_CONST___EXTERNAL_NODE_TYPE,
+         __GRAMMAR_ID_CONST___EDGE_TYPE,
+         __GRAMMAR_ID_CONST___EDGE_TYPE
+      ]);
+      expect(external?.children[0]).toMatchObject({ text: 'second (declaring.__EXTENSION__)' });
+      // The two referencing nodes side by side in one row, their target in the next.
+      expect(children.filter(child => child instanceof GNode).map(node => node.position)).toEqual([
+         { x: 0, y: 0 },
+         { x: 200, y: 0 },
+         { x: 0, y: 90 }
+      ]);
+      const targets = children.filter(child => child instanceof GEdge).map(edge => edge.targetId);
+      expect(targets).toEqual([external?.id, external?.id]);
+   });
+
+   it('draws one external node per document when two documents declare the same name', async () => {
+      workspace = makeScratchWorkspace({ prefix: '__GRAMMAR_ID__-diagram-' });
+      workspace.write('one.__EXTENSION__', 'node second');
+      workspace.write('two.__EXTENSION__', 'node second');
+      const file = workspace.write('referencing.__EXTENSION__', 'node first -> second\nnode third -> second');
+      const { shared } = createServices();
+      await initializeWorkspaceProgrammatically(shared, workspace.root);
+      const harness = makeGlspHarness<__GRAMMAR__GlspState>({
+         serverModule: new ServerModule().configureDiagramModule(new __GRAMMAR__DiagramModule()),
+         diagramType: __GRAMMAR_ID_CONST___DIAGRAM_TYPE,
+         appModules: [new HydraniumGlspAppModule({ shared })]
+      });
+      diagram = harness;
+      await harness.start();
+      await harness.openDocument(file);
+      // A name resolves to one node per document, so point each reference at a
+      // different document's node the way a qualified reference would.
+      const [first, third] = harness.state.sourceRoot.nodes;
+      for (const [node, declaring] of [
+         [first, 'one.__EXTENSION__'],
+         [third, 'two.__EXTENSION__']
+      ] as const) {
+         const declared = shared.workspace.LangiumDocuments.getDocument(URI.parse(workspace.uri(declaring)))?.parseResult.value;
+         if (!node.target || !is__ENTRY_RULE__(declared)) {
+            throw new Error(`no reference from ${node.name} or no model in ${declaring}`);
+         }
+         Object.defineProperty(node.target, 'ref', { value: declared.nodes[0] });
+      }
+      harness.sessionContainer.get<GModelFactory>(GModelFactory).createModel();
+
+      const children = harness.state.root.children;
+      const externals = children.filter(child => child.type === __GRAMMAR_ID_CONST___EXTERNAL_NODE_TYPE);
+      expect(externals.map(external => external.children[0])).toMatchObject([
+         { text: 'second (one.__EXTENSION__)' },
+         { text: 'second (two.__EXTENSION__)' }
+      ]);
+      const targets = children.filter(child => child instanceof GEdge).map(edge => edge.targetId);
+      expect(targets).toEqual(externals.map(external => external.id));
+   });
+
+   it('places each node a row above its target, cutting a cycle', async () => {
+      workspace = makeScratchWorkspace({ prefix: '__GRAMMAR_ID__-diagram-' });
+      const file = workspace.write('cycle.__EXTENSION__', 'node a -> b\nnode b -> a\nnode c -> a');
+      const { shared } = createServices();
+      await initializeWorkspaceProgrammatically(shared, workspace.root);
+      diagram = makeGlspHarness<__GRAMMAR__GlspState>({
+         serverModule: new ServerModule().configureDiagramModule(new __GRAMMAR__DiagramModule()),
+         diagramType: __GRAMMAR_ID_CONST___DIAGRAM_TYPE,
+         appModules: [new HydraniumGlspAppModule({ shared })]
+      });
+      await diagram.start();
+      await diagram.openDocument(file);
+
+      // The walk from `a` meets `a` again at `b`, so `b` ranks first; `c` references `a`.
+      const rows = diagram.state.root.children.filter(child => child instanceof GNode).map(node => node.position.y / 90);
+      expect(rows).toEqual([1, 2, 0]);
+   });
+
+   it('ranks a chain longer than the call stack is deep', () => {
+      // The ranking alone, since a document this long takes seconds to parse and link.
+      class Ranking extends __GRAMMAR__GModelFactory {
+         rankChain(targetOf: ReadonlyMap<string, string>, ids: readonly string[]): Map<string, number> {
+            return this.rank(targetOf, ids);
+         }
+      }
+      const ids = Array.from({ length: 100_000 }, (_, i) => `n${i}`);
+      const targetOf = new Map(ids.slice(0, -1).map((id, i) => [id, ids[i + 1]]));
+
+      const ranks = new Ranking().rankChain(targetOf, ids);
+
+      expect({ first: ranks.get(ids[0]), beforeLast: ranks.get(ids[ids.length - 2]) }).toEqual({ first: ids.length - 1, beforeLast: 1 });
+   });
+
+   it('keeps no route the client reports, which it computes before it sizes the nodes', async () => {
+      workspace = makeScratchWorkspace({ prefix: '__GRAMMAR_ID__-diagram-' });
+      const file = workspace.write('loop.__EXTENSION__', 'node a -> a');
+      const { shared } = createServices();
+      await initializeWorkspaceProgrammatically(shared, workspace.root);
+      const harness = makeGlspHarness<__GRAMMAR__GlspState>({
+         serverModule: new ServerModule().configureDiagramModule(new __GRAMMAR__DiagramModule()),
+         diagramType: __GRAMMAR_ID_CONST___DIAGRAM_TYPE,
+         appModules: [new HydraniumGlspAppModule({ shared })]
+      });
+      diagram = harness;
+      await harness.start();
+      await harness.openDocument(file);
+      const edge = (): GEdge | undefined => harness.state.root.children.find(child => child instanceof GEdge);
+      const edgeId = edge()?.id ?? '';
+
+      // A self-reference's loop as the client routes it around a node not yet sized.
+      const corners = [
+         { x: 19, y: -0.75 },
+         { x: 19, y: 19 },
+         { x: -0.75, y: 19 }
+      ];
+      const routes = [{ elementId: edgeId, newRoutingPoints: [{ x: 0, y: 0 }, ...corners, { x: 0, y: 0 }] }];
+      await harness.answerBoundsRequest({ routes });
+
+      expect(edge()?.routingPoints).toEqual([]);
+   });
+
+   it('marks a diagnostic on the node it is about', async () => {
+      workspace = makeScratchWorkspace({ prefix: '__GRAMMAR_ID__-diagram-' });
+      const file = workspace.write('duplicate.__EXTENSION__', 'node first\nnode first');
+      const { shared } = createServices();
+      await initializeWorkspaceProgrammatically(shared, workspace.root);
+      diagram = makeGlspHarness<__GRAMMAR__GlspState>({
+         serverModule: new ServerModule().configureDiagramModule(new __GRAMMAR__DiagramModule()),
+         diagramType: __GRAMMAR_ID_CONST___DIAGRAM_TYPE,
+         appModules: [new HydraniumGlspAppModule({ shared })]
+      });
+      await diagram.start();
+      await diagram.openDocument(file);
+
+      // A workspace brought up programmatically does not validate; an editor's open does.
+      const document = await shared.workspace.LangiumDocuments.getOrCreateDocument(URI.file(file));
+      await shared.workspace.DocumentBuilder.build([document], { validation: true });
+
+      // The repeated name's warning, on the one node the diagram keeps for both.
+      const markers = await diagram.sessionContainer.get<ModelValidator>(ModelValidator).validate([diagram.state.root]);
+      expect(markers.map(marker => ({ elementId: marker.elementId, kind: marker.kind }))).toEqual([
+         { elementId: diagram.state.root.children[0].id, kind: 'warning' }
+      ]);
+   });
+
+   it('resolves a cross-document reference in a document opened before the workspace is up', async () => {
+      workspace = makeScratchWorkspace({ prefix: '__GRAMMAR_ID__-diagram-' });
+      workspace.write('declaring.__EXTENSION__', 'node second');
+      const file = workspace.write('referencing.__EXTENSION__', 'node first -> second');
+      const { shared } = createServices();
+      diagram = makeGlspHarness<__GRAMMAR__GlspState>({
+         serverModule: new ServerModule().configureDiagramModule(new __GRAMMAR__DiagramModule()),
+         diagramType: __GRAMMAR_ID_CONST___DIAGRAM_TYPE,
+         appModules: [new HydraniumGlspAppModule({ shared })]
+      });
+      await diagram.start();
+      // The open waits for the workspace. One that did not would have linked
+      // within this timer against a workspace holding only itself, and the
+      // bring-up does not relink it. Its budget covers the bring-up as well.
+      const opening = diagram.openDocument(file, 10_000);
+      await new Promise(resolve => setTimeout(resolve, 200));
+      await initializeWorkspaceProgrammatically(shared, workspace.root);
+      await opening;
+
+      expect(diagram.state.sourceRoot?.nodes[0].target?.ref?.name).toBe('second');
+   });
+});

package/templates/server/test/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.test.json",
+  "include": ["../src", ".", "../src/**/*.json"]
+}

package/templates/server/tsconfig.test.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "noEmit": true,
+    "isolatedModules": true,
+    "types": ["node"]
+  },
+  "include": ["src", "test", "src/**/*.json"]
+}

package/templates/server/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config';
+
+// Vitest transforms TypeScript itself and resolves `.js` specifiers to their
+// `.ts` source, so tests import from `../src/` with the same specifiers the
+// compiled output uses. `include` is scoped to `test/` so `lib/` is never
+// scanned; `npm test` runs `typecheck:test` first, because vitest's
+// transform strips types without checking them.
+
+export default defineConfig({
+   test: {
+      environment: 'node',
+      include: ['test/**/*.{test,spec}.ts']
+   }
+});

package/templates/theia/gitignore

@@ -0,0 +1,3 @@
+node_modules/
+lib/
+*.tsbuildinfo

package/templates/theia/src/browser/__GRAMMAR_ID__-diagram-frontend-module.ts

@@ -0,0 +1,65 @@
+// The __GRAMMAR__ diagram in Theia: the client package's diagram, opened from
+// the language's files by a diagram manager. Its GLSP client is the one the
+// extension's frontend module binds for every diagram.
+
+import type { ContainerConfiguration } from '@eclipse-glsp/client';
+import type { GLSPDiagramLanguage } from '@eclipse-glsp/theia-integration/lib/common';
+import {
+   AbstractHydraniumGlspDiagramConfiguration,
+   AbstractHydraniumGlspDiagramManager,
+   AbstractHydraniumGlspTheiaFrontendModule,
+   createGlspClientTheiaModule,
+   SkipClientContribution
+} from '@hydranium/glsp-client-theia/browser';
+import { type Container, ContainerModule, injectable } from '@theia/core/shared/inversify';
+import { initialize__GRAMMAR__DiagramContainer } from '__CLIENT_PACKAGE__';
+import { __GRAMMAR_ID_CONST___DIAGRAM_TYPE, __GRAMMAR_ID_CONST___LANGUAGE } from '__PROTOCOL_PACKAGE__';
+import { __CONFIG_ROOT_CONST___GLSP_CONTRIBUTION_ID } from '../common/__PROJECT_ID__-glsp-contribution.js';
+import '../../style/diagram.css';
+
+export const __GRAMMAR__DiagramLanguage: GLSPDiagramLanguage = {
+   contributionId: __CONFIG_ROOT_CONST___GLSP_CONTRIBUTION_ID,
+   label: '__GRAMMAR__ Diagram',
+   diagramType: __GRAMMAR_ID_CONST___DIAGRAM_TYPE,
+   fileExtensions: [...__GRAMMAR_ID_CONST___LANGUAGE.fileExtensions]
+};
+
+// Theia's host bindings, logging to the language client's Output channel. Passed
+// after GLSP's Theia modules, whose bindings it replaces; a rebind made earlier
+// is overwritten without an error.
+const theiaModule = new ContainerModule((bind, unbind, isBound, rebind) => {
+   createGlspClientTheiaModule({ bind, unbind, isBound, rebind }, { channelLogger: { channelName: '__NAME__' } });
+});
+
+@injectable()
+export class __GRAMMAR__DiagramConfiguration extends AbstractHydraniumGlspDiagramConfiguration {
+   diagramType = __GRAMMAR_ID_CONST___DIAGRAM_TYPE;
+   // The LSP head already reports these problems.
+   protected override propagateMarkersToProblemsView = false;
+
+   configureContainer(container: Container, ...containerConfiguration: ContainerConfiguration): Container {
+      return initialize__GRAMMAR__DiagramContainer(container, ...containerConfiguration, theiaModule);
+   }
+}
+
+@injectable()
+export class __GRAMMAR__DiagramManager extends AbstractHydraniumGlspDiagramManager {
+   protected readonly diagramLanguage = __GRAMMAR__DiagramLanguage;
+   protected readonly managerLabel = '__GRAMMAR__ Diagram Editor';
+
+   override get id(): string {
+      return '__GRAMMAR_ID__-diagram-manager';
+   }
+}
+
+export class __GRAMMAR__DiagramModule extends AbstractHydraniumGlspTheiaFrontendModule {
+   readonly diagramLanguage = __GRAMMAR__DiagramLanguage;
+   protected readonly diagramConfiguration = __GRAMMAR__DiagramConfiguration;
+   protected readonly diagramManager = __GRAMMAR__DiagramManager;
+
+   protected override bindClientContribution(): SkipClientContribution {
+      return SkipClientContribution;
+   }
+}
+
+export default new __GRAMMAR__DiagramModule();

package/templates/theia/src/browser/__PROJECT_ID__-connection-preload-module.ts

@@ -0,0 +1,15 @@
+// The reconnect hardening, browser side: messages sent while the socket is
+// down are buffered and replayed, rather than the page reloading.
+//
+// A `frontendPreload` entry, not a `frontend` one: Theia builds its connection
+// before any frontend module runs, so a rebind there would do nothing. The
+// buffer size is the application's `theia.frontend.config.connectionBufferBytes`.
+
+import { bindConnectionResilience } from '@hydranium/client-theia/browser';
+import { FrontendApplicationConfigProvider } from '@theia/core/lib/browser/frontend-application-config-provider';
+import { ContainerModule } from '@theia/core/shared/inversify';
+
+export default new ContainerModule((_bind, _unbind, isBound, rebind) => {
+   const bufferBytes = FrontendApplicationConfigProvider.get()['connectionBufferBytes'];
+   bindConnectionResilience(isBound, rebind, { bufferBytes: typeof bufferBytes === 'number' ? bufferBytes : undefined });
+});

package/templates/theia/src/browser/__PROJECT_ID__-data-connection.ts

@@ -0,0 +1,15 @@
+// The page's one connection to the data head. Everything that reads the data
+// head takes a session off it: Theia opens one channel per service path.
+
+import { DataConnectionWithEvents } from '@hydranium/protocol';
+import { inject, injectable } from '@theia/core/shared/inversify';
+import type { __NAME__Element } from '__PROTOCOL_PACKAGE__';
+import { __NAME__DataPort } from './__PROJECT_ID__-data-port.js';
+
+@injectable()
+export class __NAME__DataConnection extends DataConnectionWithEvents<__NAME__Element> {
+   // The constructor, not a field: the port is needed before `super` returns.
+   constructor(@inject(__NAME__DataPort) port: __NAME__DataPort) {
+      super(port);
+   }
+}

package/templates/theia/src/browser/__PROJECT_ID__-data-port.ts

@@ -0,0 +1,11 @@
+// The page's end of the data head: a channel to the backend, which forwards it
+// to the port the servers extension answers.
+
+import { ChannelDataPort } from '@hydranium/data-client-theia/browser';
+import { DATA_SERVER_PATH } from '@hydranium/protocol';
+import { injectable } from '@theia/core/shared/inversify';
+
+@injectable()
+export class __NAME__DataPort extends ChannelDataPort {
+   protected readonly servicePath = DATA_SERVER_PATH;
+}

package/templates/theia/src/browser/__PROJECT_ID__-glsp-client-contribution.ts

@@ -0,0 +1,13 @@
+// The GLSP client every diagram of this extension shares, as they share one
+// server: the frontend module binds it once, and each diagram module skips it.
+
+import { HydraniumGlspClientContribution } from '@hydranium/glsp-client-theia/browser';
+import { injectable } from '@theia/core/shared/inversify';
+import { __CONFIG_ROOT_CONST___GLSP_CONTRIBUTION_ID } from '../common/__PROJECT_ID__-glsp-contribution.js';
+
+@injectable()
+export class __NAME__GlspClientContribution extends HydraniumGlspClientContribution {
+   constructor() {
+      super({ languageContributionId: __CONFIG_ROOT_CONST___GLSP_CONTRIBUTION_ID });
+   }
+}

package/templates/theia/src/browser/__PROJECT_ID__-show-model-command.ts

@@ -0,0 +1,51 @@
+// `__NAME__: Show Model`: the current editor's file, text or diagram, read
+// through the data head, and its root type shown in a notification.
+
+import { Command, type CommandContribution, type CommandRegistry, MessageService, nls } from '@theia/core';
+import { ApplicationShell, NavigatableWidget } from '@theia/core/lib/browser';
+import { inject, injectable } from '@theia/core/shared/inversify';
+import { ALL_LANGUAGES } from '__PROTOCOL_PACKAGE__';
+import { __NAME__DataConnection } from './__PROJECT_ID__-data-connection.js';
+
+export const SHOW_MODEL_COMMAND = Command.toLocalizedCommand(
+   { id: '__PROJECT_ID__.showModel', label: 'Show Model', category: '__NAME__' },
+   '__PROJECT_ID__/showModel',
+   '__PROJECT_ID__/category'
+);
+
+@injectable()
+export class __NAME__ShowModelCommand implements CommandContribution {
+   @inject(__NAME__DataConnection) protected readonly connection: __NAME__DataConnection;
+   @inject(ApplicationShell) protected readonly shell: ApplicationShell;
+   @inject(MessageService) protected readonly messages: MessageService;
+
+   // Opened on the first run and kept: the connection ends it with the page.
+   protected session?: ReturnType<__NAME__DataConnection['createSession']>;
+
+   registerCommands(registry: CommandRegistry): void {
+      registry.registerCommand(SHOW_MODEL_COMMAND, { execute: () => this.showModel() });
+   }
+
+   protected async showModel(): Promise<void> {
+      // The main area's, so focus in a side panel such as the Explorer still finds the editor.
+      const widget = this.shell.getCurrentWidget('main');
+      const uri = NavigatableWidget.is(widget) ? widget.getResourceUri() : undefined;
+      if (
+         uri === undefined ||
+         !ALL_LANGUAGES.some(language => language.fileExtensions.some(extension => uri.path.base.endsWith(extension)))
+      ) {
+         this.messages.info(nls.localize('__PROJECT_ID__/showModel/noFile', 'Open a __NAME__ file first.'));
+         return;
+      }
+      this.session ??= this.connection.createSession('__PROJECT_ID__-show-model');
+      const root = await this.session.withOpenDocument({ uri: uri.toString() }, document => document.model?.root.$type);
+      this.messages.info(
+         nls.localize(
+            '__PROJECT_ID__/showModel/holds',
+            '{0} holds a {1}',
+            uri.path.base,
+            root ?? nls.localize('__PROJECT_ID__/showModel/noModel', 'document with no model')
+         )
+      );
+   }
+}

package/templates/theia/src/common/__PROJECT_ID__-glsp-contribution.ts

@@ -0,0 +1,3 @@
+// The id the page's GLSP client and the backend's forwarder meet under.
+
+export const __CONFIG_ROOT_CONST___GLSP_CONTRIBUTION_ID = '__PROJECT_ID__-glsp';

package/templates/theia/src/node/__PROJECT_ID__-connection-backend-module.ts

@@ -0,0 +1,12 @@
+// The reconnect hardening, backend side: the session outlives a dropped socket
+// for the application's `frontendConnectionTimeout`, and messages for the page
+// wait in a buffer of `theia.backend.config.connectionBufferBytes`.
+
+import { bindConnectionResilience } from '@hydranium/client-theia/node';
+import { BackendApplicationConfigProvider } from '@theia/core/lib/node/backend-application-config-provider';
+import { ContainerModule } from '@theia/core/shared/inversify';
+
+export default new ContainerModule((bind, _unbind, isBound, rebind) => {
+   const bufferBytes = BackendApplicationConfigProvider.get()['connectionBufferBytes'];
+   bindConnectionResilience(bind, isBound, rebind, { bufferBytes: typeof bufferBytes === 'number' ? bufferBytes : undefined });
+});

package/templates/theia/src/node/__PROJECT_ID__-data-backend-module.ts

@@ -0,0 +1,15 @@
+// Forwards the page's data channel to the port the servers extension answers
+// under its host command.
+
+import { createDataServerConnectionContainerModule, DataServerConnectionHandler } from '@hydranium/data-client-theia/node';
+import { injectable } from '@theia/core/shared/inversify';
+import { __CONFIG_ROOT_CONST___DATA_SERVER_HOST_COMMAND } from '__PROTOCOL_PACKAGE__';
+
+@injectable()
+export class __NAME__DataServerConnectionHandler extends DataServerConnectionHandler {
+   constructor() {
+      super({ portCommand: __CONFIG_ROOT_CONST___DATA_SERVER_HOST_COMMAND });
+   }
+}
+
+export default createDataServerConnectionContainerModule(__NAME__DataServerConnectionHandler);

package/templates/theia/src/node/__PROJECT_ID__-glsp-backend-module.ts

@@ -0,0 +1,16 @@
+// Forwards the page's GLSP channel to the port the servers extension answers
+// under its host command.
+
+import { createGlspConnectionContainerModule, GlspServerConnectionHandler } from '@hydranium/glsp-client-theia/node';
+import { injectable } from '@theia/core/shared/inversify';
+import { __CONFIG_ROOT_CONST___GLSP_SERVER_HOST_COMMAND } from '__PROTOCOL_PACKAGE__';
+import { __CONFIG_ROOT_CONST___GLSP_CONTRIBUTION_ID } from '../common/__PROJECT_ID__-glsp-contribution.js';
+
+@injectable()
+export class __NAME__GlspConnectionHandler extends GlspServerConnectionHandler {
+   constructor() {
+      super({ languageContributionId: __CONFIG_ROOT_CONST___GLSP_CONTRIBUTION_ID, portCommand: __CONFIG_ROOT_CONST___GLSP_SERVER_HOST_COMMAND });
+   }
+}
+
+export default createGlspConnectionContainerModule(__NAME__GlspConnectionHandler);