@hydranium/cli 1.0.0-next.42 → 1.0.0-next.421

package/templates/host-vscode/test/install-vscode.mts

@@ -0,0 +1,21 @@
+// Downloads the pinned VS Code into `.vscode-test/`, retrying, so the smoke
+// test finds it there and asks the update server nothing.
+
+import { downloadAndUnzipVSCode } from '@vscode/test-electron';
+import { setTimeout } from 'node:timers/promises';
+import { VSCODE_CACHE, VSCODE_VERSION } from './vscode-version.mts';
+
+const ATTEMPTS = 3;
+
+for (let attempt = 1; ; attempt++) {
+   try {
+      await downloadAndUnzipVSCode({ version: VSCODE_VERSION, cachePath: VSCODE_CACHE });
+      break;
+   } catch (error: unknown) {
+      if (attempt === ATTEMPTS) {
+         throw error;
+      }
+      console.warn(`Downloading VS Code ${VSCODE_VERSION} failed, attempt ${attempt} of ${ATTEMPTS}.`, error);
+      await setTimeout(attempt * 5_000);
+   }
+}

package/templates/host-vscode/test/virtual-documents.spec.mts

@@ -0,0 +1,28 @@
+import { test } from '@playwright/test';
+import { runTests } from '@vscode/test-electron';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { VSCODE_CACHE, VSCODE_VERSION } from './vscode-version.mts';
+
+test('serves virtual documents without synchronizing their text', async () => {
+   const scratch = mkdtempSync(join(tmpdir(), 'virtual-host-'));
+   try {
+      await runTests({
+         version: VSCODE_VERSION,
+         cachePath: VSCODE_CACHE,
+         extensionDevelopmentPath: fileURLToPath(new URL('..', import.meta.url)),
+         extensionTestsPath: fileURLToPath(new URL('./virtual-documents.cjs', import.meta.url)),
+         launchArgs: [
+            '--no-sandbox',
+            '--disable-extensions',
+            '--disable-workspace-trust',
+            `--user-data-dir=${join(scratch, 'profile')}`,
+            `--extensions-dir=${join(scratch, 'extensions')}`
+         ]
+      });
+   } finally {
+      rmSync(scratch, { recursive: true, force: true });
+   }
+});

package/templates/host-vscode/test/vscode-version.mts

@@ -0,0 +1,10 @@
+import { fileURLToPath } from 'node:url';
+
+/**
+ * The VS Code build the smoke test downloads and runs. Pinned rather than
+ * `stable`, so a VS Code release cannot fail a run with no change here.
+ */
+export const VSCODE_VERSION = '1.141.0';
+
+/** Where `@vscode/test-electron` keeps the download, below this package. */
+export const VSCODE_CACHE = fileURLToPath(new URL('../.vscode-test', import.meta.url));

package/templates/host-vscode/tsconfig.e2e.json

@@ -0,0 +1,17 @@
+// The smoke tier's half, which runs in Node under Playwright. `test:e2e` passes
+// it with `--tsconfig`, since Playwright otherwise looks for a `tsconfig.json`
+// in the directories above.
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "allowImportingTsExtensions": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["test", "playwright.config.mts"]
+}

package/templates/host-vscode/tsconfig.json

@@ -0,0 +1,19 @@
+// The extension, compiled to CommonJS in `out/`, which the extension host
+// loads. It runs in Node, so it has no DOM; a diagram webview under
+// `src/webview/` is a project of its own, bundled by esbuild.
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "out",
+    "strict": true,
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "types": ["node"]
+  },
+  "include": ["src"],
+  "exclude": ["src/webview"]
+}

package/templates/host-vscode/tsconfig.webview.json

@@ -0,0 +1,17 @@
+// The diagram webviews' half: a browser page, so it has the DOM. esbuild
+// emits, so this only type-checks, and the stylesheet imports are esbuild's to
+// resolve.
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "noUncheckedSideEffectImports": false,
+    "types": []
+  },
+  "include": ["src/webview"]
+}

package/templates/oxlintrc.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "ignorePatterns": ["**/generated", "**/generated-hydranium"]
+}

package/templates/protocol/gitignore

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

package/templates/protocol/src/__GRAMMAR_ID__-diagram-types.ts

@@ -0,0 +1,47 @@
+// GLSP diagram-type and element-type ids for the __GRAMMAR__ diagram, which the
+// server stamps onto the graph and every client registers.
+//
+// Declared once, here, for both ends. A drift between them fails silently:
+// sprotty's registries are exact-key maps with no prefix fallback, so an id the
+// client does not know yields an element with none of a node's features,
+// rendered by `MissingView` with only a `no registered view for type '…'`
+// console warning. Nothing fails server-side.
+//
+// The ids stay namespaced under the GLSP defaults (`node:` / `edge:`) so a
+// reader can tell a node id from an edge id at a glance.
+
+import { DefaultTypes } from '@eclipse-glsp/protocol';
+import { __GRAMMAR_ID_CONST___LANGUAGE } from './generated-hydranium/languages.js';
+
+/**
+ * The GLSP diagram type — the string GLSP routes every per-diagram-type request
+ * by. A mismatch silently DROPS the request rather than reporting an unknown
+ * diagram type. Read from the language id, so renaming the language renames
+ * the diagram type at the next `generate`.
+ */
+export const __GRAMMAR_ID_CONST___DIAGRAM_TYPE = __GRAMMAR_ID_CONST___LANGUAGE.languageId;
+
+/** A `__NODE_RULE__` — the starter grammar's one named, referenceable node. */
+export const __GRAMMAR_ID_CONST___NODE_TYPE = `${DefaultTypes.NODE}:__GRAMMAR_ID__-node`;
+
+/**
+ * A `__NODE_RULE__` declared in another document, drawn because a node of this
+ * one references it. It belongs to that document, so nothing edits it here.
+ */
+export const __GRAMMAR_ID_CONST___EXTERNAL_NODE_TYPE = `${DefaultTypes.NODE}:__GRAMMAR_ID__-external-node`;
+
+/** A resolved `target` reference, drawn as a connection between two nodes. */
+export const __GRAMMAR_ID_CONST___EDGE_TYPE = `${DefaultTypes.EDGE}:__GRAMMAR_ID__-target`;
+
+/**
+ * Every element type id the server stamps.
+ *
+ * A tuple, so {@link __GRAMMAR__ElementType} is a union of the ids rather than
+ * `string`: a client table keyed by that union does not compile while an id
+ * lacks its registration. Nothing holds the tuple to the constants above, so
+ * an id declared without joining it escapes that check.
+ */
+export const __GRAMMAR_ID_CONST___ELEMENT_TYPES = [__GRAMMAR_ID_CONST___NODE_TYPE, __GRAMMAR_ID_CONST___EXTERNAL_NODE_TYPE, __GRAMMAR_ID_CONST___EDGE_TYPE] as const;
+
+/** One of the element type ids in {@link __GRAMMAR_ID_CONST___ELEMENT_TYPES}. */
+export type __GRAMMAR__ElementType = (typeof __GRAMMAR_ID_CONST___ELEMENT_TYPES)[number];

package/templates/server/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+lib/
+*.tsbuildinfo
+
+# Langium-generated TextMate grammar (rewritten by every `langium generate`).
+syntaxes/

package/templates/server/src/glsp/__GRAMMAR_ID__/create-node-operation-handler.ts

@@ -0,0 +1,62 @@
+// The starter operation handler for the __GRAMMAR__ diagram: the tool-palette
+// entry that creates a `__NODE_RULE__`.
+//
+// **Deleting this file, `delete-operation-handler.ts` and their
+// `configureOperationHandlers` registrations in `diagram-module.ts`, and setting
+// `deletable` back to `false` in `diagram-configuration.ts`, gives a read-only
+// viewer** — creation is offered through the palette rather than through a type
+// hint. The scaffold emits the editable direction because that asymmetry runs one
+// way: editable → read-only is a deletion the compiler checks, while read-only →
+// editable is authoring against a seam you have not used yet.
+//
+// **It edits the operation's copy.** A handler runs inside an operation, where
+// `sourceRoot` is a copy of the built root: the recording command's runnable
+// appends to the copy, and the operation writes the copy's text through the
+// grammar's `Serializer` once, gated on the version the copy was made at, with
+// undo and redo applying that one change. A command that writes the document
+// itself instead reads no text off the copy, which has no `$document`, and the
+// operation's own write then overwrites it.
+//
+// **The drop location is discarded.** `needsClientLayout` is `true` and the
+// starter grammar persists no bounds, so there is nowhere to put a coordinate: the
+// node is appended at the end of the document and the client places it.
+//
+// Like protocol's `__GRAMMAR_ID__-diagram-types.ts`, `gmodel-factory.ts`,
+// `delete-operation-handler.ts` and `diagram-configuration.ts`, this file knows
+// the starter grammar's shape — the `nodes` list and the `__NODE_RULE__` it
+// holds. Replacing the grammar means replacing them together.
+
+import { type Command, type CreateNodeOperation, JsonCreateNodeOperationHandler, type MaybePromise } from '@eclipse-glsp/server';
+import { appendChild } from '@hydranium/core';
+import { HydraniumGlspRecordingCommand } from '@hydranium/glsp-server';
+import { findNextUnique } from '@hydranium/protocol';
+import { __GRAMMAR_ID_CONST___NODE_TYPE } from '__PROTOCOL_PACKAGE__';
+import { injectable } from 'inversify';
+import type { __NODE_RULE__ } from '../../language-server/ast.js';
+import type { __GRAMMAR__GlspState } from './state.js';
+
+/** Proposed name for a new node, uniquified against the ones the document already has. */
+const NODE_NAME_STEM = 'Node';
+
+@injectable()
+export class __GRAMMAR__CreateNodeOperationHandler extends JsonCreateNodeOperationHandler {
+   declare protected modelState: __GRAMMAR__GlspState;
+
+   /** The palette's word for the thing it creates, so a noun rather than an action. */
+   override readonly label = '__NODE_RULE__';
+   elementTypeIds = [__GRAMMAR_ID_CONST___NODE_TYPE];
+
+   override createCommand(operation: CreateNodeOperation): MaybePromise<Command | undefined> {
+      if (!this.elementTypeIds.includes(operation.elementTypeId)) {
+         return undefined;
+      }
+      return new HydraniumGlspRecordingCommand(this.modelState, this.label, () => {
+         const root = this.modelState.sourceRoot;
+         const name = findNextUnique(
+            NODE_NAME_STEM,
+            root.nodes.map(node => node.name)
+         );
+         appendChild(root, 'nodes', root.nodes, { $type: '__NODE_RULE__', name } as __NODE_RULE__);
+      });
+   }
+}

package/templates/server/src/glsp/__GRAMMAR_ID__/delete-operation-handler.ts

@@ -0,0 +1,63 @@
+// The starter delete handler for the __GRAMMAR__ diagram: removes a
+// `__NODE_RULE__`, or the reference an edge draws.
+//
+// Deleting a node also clears every reference to it in this document, so
+// `node A -> B` becomes `node A` rather than keeping a reference that no longer
+// resolves. A reference stays when the name still resolves: to another node of
+// it here, or to one another document declares. A reference from another
+// document is not this operation's to edit: it is left, and reported there as a
+// link error. A node drawn for another document's target is not deletable, and
+// its id finds no node here.
+//
+// Like the create handler, it edits the operation's copy, which the operation
+// writes once, with undo and redo applying that one change.
+
+import { type Command, DeleteElementOperation, GEdge, JsonOperationHandler, type MaybePromise } from '@eclipse-glsp/server';
+import { removeChildren } from '@hydranium/core';
+import { HydraniumGlspRecordingCommand } from '@hydranium/glsp-server';
+import { UriUtils } from '@hydranium/langium';
+import type { Mutable } from '@hydranium/protocol';
+import { injectable } from 'inversify';
+import type { __NODE_RULE__ } from '../../language-server/ast.js';
+import type { __GRAMMAR__GlspState } from './state.js';
+
+@injectable()
+export class __GRAMMAR__DeleteOperationHandler extends JsonOperationHandler {
+   readonly operationType = DeleteElementOperation.KIND;
+
+   declare protected modelState: __GRAMMAR__GlspState;
+
+   override createCommand(operation: DeleteElementOperation): MaybePromise<Command | undefined> {
+      return new HydraniumGlspRecordingCommand(this.modelState, 'Delete', () => {
+         const index = this.modelState.index;
+         const root = this.modelState.sourceRoot;
+         // The first node with the id, which is the one the diagram draws for a repeated name.
+         const nodeOf = (id: string): __NODE_RULE__ | undefined => root.nodes.find(node => index.findId(node) === id);
+         const deleted = new Set<__NODE_RULE__>();
+         // The nodes whose reference a deleted edge drew.
+         const unlinked = new Set<__NODE_RULE__>();
+         for (const elementId of operation.elementIds) {
+            const element = index.find(elementId);
+            const node = nodeOf(element instanceof GEdge ? element.sourceId : elementId);
+            if (node !== undefined) {
+               (element instanceof GEdge ? unlinked : deleted).add(node);
+            }
+         }
+         const remaining = new Set(root.nodes.filter(node => !deleted.has(node)).map(node => node.name));
+         const indexManager = index.languageServicesFor(root)?.shared.workspace.IndexManager;
+         const stillResolves = (target: __NODE_RULE__): boolean =>
+            remaining.has(target.name) ||
+            (indexManager
+               ?.allElements(target.$type)
+               .some(element => element.name === target.name && !UriUtils.equals(element.documentUri, this.modelState.sourceUri)) ??
+               false);
+         for (const node of root.nodes) {
+            const target = node.target?.ref;
+            if (unlinked.has(node) || (target !== undefined && deleted.has(target) && !stillResolves(target))) {
+               (node as Mutable<__NODE_RULE__>).target = undefined;
+            }
+         }
+         removeChildren(root.nodes, deleted);
+      });
+   }
+}

package/templates/server/src/glsp/__GRAMMAR_ID__/gmodel-factory.ts

@@ -0,0 +1,144 @@
+// AST → GModel for the __GRAMMAR__ diagram: one node per `__NODE_RULE__`, one
+// edge per resolved `target` reference.
+//
+// Ids come from the index rather than being composed here, so the id strategy
+// stays in one place. An id derived from a node's, for its label, its edge or an
+// external node, appends a suffix starting with `-`, which the grammar's `ID`
+// does not allow, so it never clashes with a node's own. Nodes are emitted
+// before edges, because a GLSP edge pointing at an id that does not exist fails
+// client-side with a far less obvious error than a missing edge. An unresolved
+// reference is SKIPPED rather than treated as an error: a dangling reference is
+// ordinary editing state, and the language already reports it as a diagnostic.
+//
+// A reference into another document is drawn to an external node standing for
+// its target, once however many nodes reference it, so the diagram shows what
+// the editor resolves. The target's own diagnostics stay with its document.
+//
+// The starter grammar persists no positions, so the nodes are placed in a grid:
+// each one row above its target, and side by side in document order within a
+// row. Without a cycle every edge spans one row; a cycle is cut where the walk
+// meets a node it is still ranking, and its closing edge spans the cycle.
+
+import { DefaultTypes, GEdge, GGraph, GLabel, type GModelFactory, GNode, ModelState } from '@eclipse-glsp/server';
+import { AstUtils, UriUtils } from '@hydranium/langium';
+import { __GRAMMAR_ID_CONST___EDGE_TYPE, __GRAMMAR_ID_CONST___EXTERNAL_NODE_TYPE, __GRAMMAR_ID_CONST___NODE_TYPE } from '__PROTOCOL_PACKAGE__';
+import { inject, injectable } from 'inversify';
+import type { __ENTRY_RULE__, __NODE_RULE__ } from '../../language-server/ast.js';
+import type { __GRAMMAR__GlspState } from './state.js';
+
+/** The size of one cell of the grid the nodes are placed in, a column wide and a row high. */
+const CELL = { width: 200, height: 90 };
+
+@injectable()
+export class __GRAMMAR__GModelFactory implements GModelFactory {
+   @inject(ModelState) protected readonly modelState!: __GRAMMAR__GlspState;
+
+   createModel(): void {
+      const root = this.modelState.sourceRoot;
+      const graph = GGraph.builder().id(this.modelState.sourceUri).build();
+      if (root) {
+         this.buildGraph(root, graph);
+      }
+      this.modelState.updateRoot(graph);
+   }
+
+   protected buildGraph(root: __ENTRY_RULE__, graph: GGraph): void {
+      const index = this.modelState.index;
+      // A repeated name repeats the id: only its first node is drawn, with that node's edge.
+      const drawn = new Map<string, __NODE_RULE__>();
+      for (const node of root.nodes) {
+         const id = index.createId(node);
+         if (!drawn.has(id)) {
+            drawn.set(id, node);
+         }
+      }
+      const nodes = [...drawn].map(([id, node]) => ({ id, builder: this.createNode(id, __GRAMMAR_ID_CONST___NODE_TYPE, node.name) }));
+      const edges: GEdge[] = [];
+      const targetOf = new Map<string, string>();
+      // By document and id: same-named targets of two documents get separate
+      // nodes, the second with a counter, not a uri in a client-visible id.
+      const externalIds = new Map<string, string>();
+      const externalCounts = new Map<string, number>();
+      for (const [sourceId, node] of drawn) {
+         const target = node.target?.ref;
+         if (!target) {
+            continue;
+         }
+         let targetId = index.createId(target);
+         if (AstUtils.findRootNode(target) !== root) {
+            const uri = AstUtils.getDocument(target).uri;
+            const key = `${uri.toString()} ${targetId}`;
+            const known = externalIds.get(key);
+            if (known !== undefined) {
+               targetId = known;
+            } else {
+               const count = (externalCounts.get(targetId) ?? 0) + 1;
+               externalCounts.set(targetId, count);
+               targetId = count === 1 ? `${targetId}-external` : `${targetId}-external-${count}`;
+               externalIds.set(key, targetId);
+               const file = UriUtils.basename(uri);
+               const external = this.createNode(targetId, __GRAMMAR_ID_CONST___EXTERNAL_NODE_TYPE, `${target.name} (${file})`);
+               nodes.push({ id: targetId, builder: external.addCssClass('external') });
+            }
+         }
+         targetOf.set(sourceId, targetId);
+         edges.push(GEdge.builder().id(`${sourceId}-target`).type(__GRAMMAR_ID_CONST___EDGE_TYPE).sourceId(sourceId).targetId(targetId).build());
+      }
+      const ids = nodes.map(node => node.id);
+      const ranks = this.rank(targetOf, ids);
+      // Loops rather than spread arguments, which overflow the stack on a large diagram.
+      let lastRow = 0;
+      for (const rank of ranks.values()) {
+         lastRow = Math.max(lastRow, rank);
+      }
+      const columns = new Map<number, number>();
+      const placed = nodes.map(({ id, builder }) => {
+         const row = lastRow - (ranks.get(id) ?? 0);
+         const column = columns.get(row) ?? 0;
+         columns.set(row, column + 1);
+         return builder.position(column * CELL.width, row * CELL.height).build();
+      });
+      for (const child of [...placed, ...edges]) {
+         graph.children.push(child);
+      }
+   }
+
+   /**
+    * Each node's row counted up from the bottom: one more than its target's,
+    * and 0, left out of the map, for a node that references nothing here. A
+    * cycle is cut where the walk meets itself.
+    */
+   protected rank(targetOf: ReadonlyMap<string, string>, ids: readonly string[]): Map<string, number> {
+      const ranks = new Map<string, number>();
+      for (const start of ids) {
+         // Walked in a loop, not recursively, so a long chain does not overflow the stack.
+         const walk = new Set<string>();
+         let id = start;
+         let target = targetOf.get(id);
+         while (target !== undefined && !walk.has(id) && !ranks.has(id)) {
+            walk.add(id);
+            id = target;
+            target = targetOf.get(id);
+         }
+         let rank = ranks.get(id) ?? 0;
+         for (const walked of [...walk].reverse()) {
+            rank += 1;
+            ranks.set(walked, rank);
+         }
+      }
+      return ranks;
+   }
+
+   /** A node labelled `text`, placed and built by the caller. */
+   protected createNode(id: string, type: string, text: string) {
+      return (
+         GNode.builder()
+            .id(id)
+            .type(type)
+            // Sized by the client around its label, which it lays out.
+            .layout('vbox')
+            .addLayoutOptions({ paddingLeft: 12, paddingRight: 12, paddingTop: 8, paddingBottom: 8 })
+            .add(GLabel.builder().id(`${id}-name`).text(text).type(DefaultTypes.LABEL).build())
+      );
+   }
+}

package/templates/server/src/glsp/__GRAMMAR_ID__/state.ts

@@ -0,0 +1,18 @@
+// GLSP state for the __GRAMMAR__ diagram.
+//
+// `FullTextHydraniumGlspState` is the simplest of the framework source-model
+// strategies (the others project a structured transfer model, over one document
+// or several): the source model is the whole document text, serialised through
+// the per-URI `Serializer` and round-tripped by re-parsing. Both seams resolve
+// through shared services, so narrowing the root type is all an adopter adds.
+//
+// It cannot field-merge — every concurrent edit on a whole-document model is a
+// same-document collision, so undo / redo degrade to drop-on-divergence. Move to
+// `ReconcilingTransferHydraniumGlspState` when you need field-level undo.
+
+import { FullTextHydraniumGlspState } from '@hydranium/glsp-server';
+import { injectable } from 'inversify';
+import type { __ENTRY_RULE__ } from '../../language-server/ast.js';
+
+@injectable()
+export class __GRAMMAR__GlspState extends FullTextHydraniumGlspState<__ENTRY_RULE__> {}

package/templates/server/src/glsp/__GRAMMAR_ID__/storage.ts

@@ -0,0 +1,16 @@
+// Source-model storage for the __GRAMMAR__ diagram, inheriting both framework
+// defaults: `loadSourceModel` (open + settle + `setSourceRoot`) and
+// `saveSourceModel` (flush the store's text for the primary and every tracked
+// secondary through the diagram's client session).
+//
+// No serializer runs on the save path — a save persists what the diagram's
+// operations already wrote to the store.
+//
+// The subclass exists so a bespoke load or save has a stable place to land.
+
+import { type FullTextSourceModel, HydraniumGlspStorage } from '@hydranium/glsp-server';
+import { injectable } from 'inversify';
+import type { __ENTRY_RULE__ } from '../../language-server/ast.js';
+
+@injectable()
+export class __GRAMMAR__GlspStorage extends HydraniumGlspStorage<__ENTRY_RULE__, FullTextSourceModel> {}

package/templates/server/src/glsp/__GRAMMAR_ID__/submission-handler.ts

@@ -0,0 +1,24 @@
+// Submission handler for the __GRAMMAR__ diagram.
+//
+// Inherits the framework's `readyEvent = IntegrityService.SettledState`, which
+// is load-bearing rather than incidental: the GModel factory resolves
+// `target.ref`, so it needs a fully-linked AST. Without the gate those reads
+// fire mid-build and warn about resolution before scopes are computed.
+//
+// Only `formatSourceRoot` is overridden, so the submit log names the model and
+// its node count instead of a bare `$type`.
+
+import { ModelState } from '@eclipse-glsp/server';
+import { type FullTextSourceModel, HydraniumGlspSubmissionHandler } from '@hydranium/glsp-server';
+import { inject, injectable } from 'inversify';
+import type { __ENTRY_RULE__ } from '../../language-server/ast.js';
+import type { __GRAMMAR__GlspState } from './state.js';
+
+@injectable()
+export class __GRAMMAR__SubmissionHandler extends HydraniumGlspSubmissionHandler<__ENTRY_RULE__, FullTextSourceModel> {
+   @inject(ModelState) declare protected modelState: __GRAMMAR__GlspState;
+
+   protected override formatSourceRoot(root: __ENTRY_RULE__ | undefined): string {
+      return root ? `__ENTRY_RULE__ nodes=${root.nodes.length}` : 'none';
+   }
+}

package/templates/server/src/grammar/common.langium

@@ -0,0 +1,12 @@
+// Shared lexical basis for this project's grammars. Imported, never registered:
+// it has no entry rule and no `langium-config.json` entry, so it is a fragment
+// rather than a language.
+//
+// Keeping the tokens here rather than in one of the languages means a grammar
+// imports `common` for its TOKENS and another language only when it needs that
+// language's TYPES — separate reasons that are worth keeping separate.
+
+hidden terminal WS: /\s+/;
+terminal ID: /[_a-zA-Z][\w_]*/;
+hidden terminal SL_COMMENT: /\/\/[^\n\r]*/;
+hidden terminal ML_COMMENT: /\/\*[\s\S]*?\*\//;

package/templates/server/src/language-server/__GRAMMAR_ID__-semantic-tokens.ts

@@ -0,0 +1,10 @@
+import { AbstractHydraniumSemanticTokenProvider, type SemanticTokenKind } from '@hydranium/core/lsp';
+import { SemanticTokenTypes } from 'vscode-languageserver';
+import { __NODE_RULE__ } from './ast.js';
+
+/** Declarations and references share the token kind of their target type. */
+export class __GRAMMAR__SemanticTokenProvider extends AbstractHydraniumSemanticTokenProvider {
+   protected override getTokenKind(type: string): SemanticTokenKind | undefined {
+      return type === __NODE_RULE__.$type ? SemanticTokenTypes.class : undefined;
+   }
+}

package/templates/server/src/language-server/__GRAMMAR_ID__-serializer.ts

@@ -0,0 +1,53 @@
+// Concrete-syntax emitter for __GRAMMAR__ — the parser's inverse, turning a
+// model back into text this grammar accepts. Derived from the starter grammar
+// exactly as `generated/ast.ts` is, so replacing the grammar replaces this too.
+//
+// Without it every structured write fails: the framework's default binding at
+// `services.serializer.Serializer` THROWS, because a concrete syntax is
+// language knowledge no framework can derive. A client session's `update` /
+// `save`, the data head's `saveModelDocument` and a GLSP `SaveModelAction`
+// all reach it.
+//
+// `AbstractSerializer`'s generic property walk lays out FORMAT-structured
+// output — its YAML and JSON subclasses are what it exists for — and cannot
+// produce a keyword-delimited syntax like `node a -> b`. So `serializeNode` is
+// a per-`$type` emitter here and the two array hooks are unreachable.
+
+import { AbstractSerializer } from '@hydranium/core';
+import type { AstNode } from '@hydranium/langium';
+import { type __ENTRY_RULE__, type __NODE_RULE__, is__ENTRY_RULE__, is__NODE_RULE__ } from './ast.js';
+
+export class __GRAMMAR__Serializer extends AbstractSerializer<__ENTRY_RULE__> {
+   protected override serializeNode(node: AstNode | Record<string, unknown>): string {
+      if (is__ENTRY_RULE__(node)) {
+         return node.nodes.map(child => this.emitNode(child)).join('\n');
+      }
+      if (is__NODE_RULE__(node)) {
+         return this.emitNode(node);
+      }
+      // Defensive: a rule added to the grammar with no emitter added here.
+      throw new Error(`__GRAMMAR__Serializer: no emitter for $type ${(node as AstNode).$type}`);
+   }
+
+   /** Unreachable — this grammar's one list is emitted by its `__ENTRY_RULE__` parent. */
+   protected override serializeArray(): string {
+      throw new Error('__GRAMMAR__Serializer: arrays are emitted by the per-$type parent, not the generic dispatch.');
+   }
+
+   /** Unreachable — same reasoning as {@link serializeArray}. */
+   protected override serializeReferenceArray(): string {
+      throw new Error('__GRAMMAR__Serializer: reference arrays are emitted by the per-$type parent, not the generic dispatch.');
+   }
+
+   /**
+    * `serializeReferenceText` rather than `node.target?.$refText`: it is the one
+    * read that spans BOTH input shapes. A transfer model reaching
+    * `serializeTransfer` carries `target` as a plain string rather than a
+    * `Reference`, and a serializer that reaches for `$refText` directly emits
+    * the AST correctly and drops every reference on the transfer path.
+    */
+   private emitNode(node: __NODE_RULE__): string {
+      const target = this.serializeReferenceText(node.target);
+      return target === undefined ? `node ${node.name}` : `node ${node.name} -> ${target}`;
+   }
+}

package/templates/server/src/language-server/__GRAMMAR_ID__-validation.ts

@@ -0,0 +1,30 @@
+// Validation for __GRAMMAR__: a check the parser and linker cannot make.
+//
+// A name is what a reference resolves by and what the diagram keys a node by,
+// so a second node of the same name is unreachable by reference and dropped
+// from the diagram. Each one after the first gets a warning rather than an
+// error, since a half-typed rename passes through this state.
+
+import type { ValidationCheckContribution, ValidationCheckRegistry } from '@hydranium/core';
+import { acceptMessage } from '@hydranium/core/messages';
+import type { ValidationAcceptor } from '@hydranium/langium';
+import { defineMessage } from '@hydranium/protocol';
+import type { __ENTRY_RULE__, __NAME__AstType } from './ast.js';
+
+export const DUPLICATE_NAME = defineMessage('__PROJECT_ID__/__GRAMMAR_ID__/duplicate-name', "A node named '{name}' is already declared.");
+
+export class __GRAMMAR__ValidationContribution implements ValidationCheckContribution {
+   registerValidationChecks(registry: ValidationCheckRegistry): void {
+      registry.register<__NAME__AstType>({ __ENTRY_RULE__: this.checkUniqueNames }, this);
+   }
+
+   protected checkUniqueNames(model: __ENTRY_RULE__, accept: ValidationAcceptor): void {
+      const seen = new Set<string>();
+      for (const node of model.nodes) {
+         if (seen.has(node.name)) {
+            acceptMessage(accept, 'warning', DUPLICATE_NAME, { node, property: 'name' }, { name: node.name });
+         }
+         seen.add(node.name);
+      }
+   }
+}