@hydranium/cli 1.0.0-next.406 → 1.0.0-next.411

package/src/commands/init-templates.ts

@@ -596,6 +596,9 @@ __DEPENDENCIES__
   },
   "engines": {
     "node": ">=22.13"
+  },
+  "hydranium": {
+    "services": "./lib/node/services.js"
   }
 }
 `;
@@ -896,8 +899,9 @@ export const __CONFIG_ROOT_CONST___CONFIGURATION_ROOT = '__PROJECT_ID__';
 };`
       : `const __NAME__SharedModule: Module<__NAME__SharedServices, PartialLangiumSharedServices> = {};`;
 
-   const serializerImports = composition.grammars
+   const languageImports = composition.grammars
       .flatMap(grammar => [
+         `import { ${grammar.grammar}SemanticTokenProvider } from './${grammar.grammarId}-semantic-tokens.js';`,
          `import { ${grammar.grammar}Serializer } from './${grammar.grammarId}-serializer.js';`,
          `import { ${grammar.grammar}ValidationContribution } from './${grammar.grammarId}-validation.js';`
       ])
@@ -909,7 +913,12 @@ export const __CONFIG_ROOT_CONST___CONFIGURATION_ROOT = '__PROJECT_ID__';
    // serializer — and that one throws on a `$type` it has no emitter for.
    const languageModules = composition.grammars
       .map(
-         grammar => `const ${grammar.grammar}LanguageModule: Module<__NAME__Services, PartialLangiumServices & DeepPartial<ServerAddedServices>> = {
+         grammar => `const ${grammar.grammar}LanguageModule = (
+   options: __NAME__Options
+): Module<__NAME__Services, PartialLangiumServices & DeepPartial<ServerAddedServices>> => ({
+   lsp: {
+      SemanticTokenProvider: services => new ${grammar.grammar}SemanticTokenProvider(services, options)
+   },
    serializer: {
       Serializer: services => new ${grammar.grammar}Serializer(services)
    },
@@ -918,13 +927,15 @@ export const __CONFIG_ROOT_CONST___CONFIGURATION_ROOT = '__PROJECT_ID__';
          names: () => new ${grammar.grammar}ValidationContribution()
       }
    }
-};`
+});`
       )
       .join('\n\n');
 
    const additionalLanguages = multi
       ? `,\n      additionalLanguages: ${arrayLiteral(
-           additional.map(grammar => `{ generated: ${grammar.grammar}GeneratedModule, adopter: () => ${grammar.grammar}LanguageModule }`),
+           additional.map(
+              grammar => `{ generated: ${grammar.grammar}GeneratedModule, adopter: () => ${grammar.grammar}LanguageModule(options) }`
+           ),
            '      ',
            columns
         )}`
@@ -940,8 +951,8 @@ export const __CONFIG_ROOT_CONST___CONFIGURATION_ROOT = '__PROJECT_ID__';
 // overrides via Langium's \`inject()\` (through the framework's
 // \`createIntegrationServices\`). Each adopter module binds its language's
 // \`Serializer\`, which the framework cannot default because a concrete syntax
-// is grammar knowledge, and its validation checks. Everything else (scope,
-// naming, project management, build pipeline) boots on the framework defaults;
+// is grammar knowledge, its semantic tokens and its validation checks. Scope,
+// naming, project management and the build pipeline use the framework defaults;
 // scope computation and AST extensions go in these same modules.
 //
 // Note which generated symbol comes from which name: the SHARED module is
@@ -965,7 +976,12 @@ export const __CONFIG_ROOT_CONST___CONFIGURATION_ROOT = '__PROJECT_ID__';
    }
 
 ${importList(
-   ['createLspServerLanguageModule', 'createLspServerSharedModule', 'type LspServerAddedServices', 'type LspServerAddedSharedServices'],
+   [
+      'createLspServerLanguageModule',
+      'createLspServerSharedModule',
+      'type HydraniumSemanticTokenProviderOptions',
+      'type LspServerAddedSharedServices'
+   ],
    '@hydranium/core/lsp',
    columns
 )}
@@ -973,22 +989,21 @@ import { createIntegrationServices, type ServerAddedServices, type ServerModuleC
 import { type DeepPartial, EmptyFileSystem, type Module } from '@hydranium/langium';
 import { type LangiumServices, type PartialLangiumServices, type PartialLangiumSharedServices } from '@hydranium/langium/lsp';
 ${importList(generatedImports, './generated/module.js', columns)}
-${serializerImports}
+${languageImports}
 
 export type __NAME__SharedServices = ServerSharedServices & LspServerAddedSharedServices;
 export type __NAME__Services = LangiumServices &
-   ServerAddedServices &
-   LspServerAddedServices & {
+   ServerAddedServices & {
       shared: __NAME__SharedServices;
    };
 
 /** What a host or a test may vary about this composition. */
-export interface __NAME__Options {
+export interface __NAME__Options extends HydraniumSemanticTokenProviderOptions {
    /**
     * Shared modules layered in after the framework's own bindings.
     *
     * The framework constructs most shared services with no options —
-    * \`DocumentBuilder: services => new HydraniumDocumentBuilder(services)\` — so
+    * \`DocumentBuilder: services => new DefaultHydraniumDocumentBuilder(services)\` — so
     * rebinding the slot is the only way to boot one configured differently, and
     * a factory that hard-codes its composition leaves a test nowhere to do it.
     * That is what this is for: pass a module binding \`workspace.DocumentBuilder\`
@@ -1024,7 +1039,7 @@ ${returnType}
       },
       languageModules: {
          generated: ${primary.grammar}GeneratedModule,
-         adopter: () => ${primary.grammar}LanguageModule,
+         adopter: () => ${primary.grammar}LanguageModule(options),
          extra: [createLspServerLanguageModule(fullContext)]
       }${additionalLanguages}
    });
@@ -1783,13 +1798,13 @@ function readme(composition: InitComposition): string {
       // nowhere else.
       '```bash',
       '# Grammar / AST reflection',
-      'npx hydranium-cli reflect --services ./lib/node/services.js',
+      'npx hydranium-cli reflect',
       '',
       '# Grammar-convention lint (CI gate)',
-      'npx hydranium-cli lint-grammar --services ./lib/node/services.js',
+      'npx hydranium-cli lint-grammar',
       '',
       '# Validate a workspace of model files (non-zero exit on errors)',
-      'npx hydranium-cli validate --services ./lib/node/services.js ../workspace',
+      'npx hydranium-cli validate ../workspace',
       ...(data
          ? [
               '',
@@ -1814,6 +1829,7 @@ function readme(composition: InitComposition): string {
       '- `src/language-server/__PROJECT_ID__-module.ts` — `create__NAME__Services` DI wiring',
       ...composition.grammars.flatMap(grammar => [
          `- \`src/language-server/${grammar.grammarId}-serializer.ts\` — emits \`${grammar.grammar}\` back to text (the framework defaults this to a throw)`,
+         `- \`src/language-server/${grammar.grammarId}-semantic-tokens.ts\` — colours declarations and references; the browser enables keywords and comments too`,
          `- \`src/language-server/${grammar.grammarId}-validation.ts\` — the \`${grammar.grammar}\` checks: a warning on a repeated name`
       ]),
       "- `src/node/services.ts` — zero-arg `createServices()` for the headless CLI, the package's `./node` entry",
@@ -2179,6 +2195,8 @@ function serverFiles(composition: InitComposition): InitFile[] {
       // binding to add, rather than guessing a syntax.
       ...composition.grammars.flatMap(grammar => [
          grammarTemplate('server/src/language-server/__GRAMMAR_ID__-serializer.ts', composition, grammar),
+         grammarTemplate('server/src/language-server/__GRAMMAR_ID__-semantic-tokens.ts', composition, grammar),
+         grammarTemplate('server/test/__GRAMMAR_ID__-semantic-tokens.test.ts', composition, grammar),
          grammarTemplate('server/src/language-server/__GRAMMAR_ID__-validation.ts', composition, grammar)
       ]),
       { path: 'server/src/index.ts', content: indexFile(composition) },
@@ -2549,14 +2567,14 @@ function hostWorkerFile(composition: InitComposition): string {
    ];
 
    const services = `const shared = create${composition.name}Services({ ...fileSystem }).shared;`;
-   const lspCall = `startLanguageServerInWorker(ports.lsp, connection => create${composition.name}Services({ connection, ...fileSystem }).shared);`;
+   const lspCall = `startLanguageServerInWorker(ports.lsp, connection => create${composition.name}Services({ connection, ...fileSystem }, { highlightKeywords: true, highlightComments: true }).shared);`;
    const startServices = !lsp
       ? services
       : `      const shared = ${lspCall}`.length <= columns
         ? `const shared = ${lspCall}`
         : `const shared = startLanguageServerInWorker(
          ports.lsp,
-         connection => create${composition.name}Services({ connection, ...fileSystem }).shared
+         connection => create${composition.name}Services({ connection, ...fileSystem }, { highlightKeywords: true, highlightComments: true }).shared
       );`;
    const dataServer = `connection => new DataServer<${roots.join(' | ')}>(connection, shared)`;
    const dataCall = `startDataServerInWorker(ports.data, shared, ${dataServer});`;
@@ -2844,7 +2862,35 @@ ${checks.join('\n')}
 ${edit}
    expect(errors).toEqual([]);
 });
-${guardTest}`;
+${guardTest}${
+      lsp
+         ? `
+test('colours declarations, references, keywords and comments', async ({ page }) => {
+   await page.goto('/');
+   await expect(page.locator('#status')).toHaveText('ready');
+   const editor = page.locator('#editor .view-lines');
+   const second = editor.locator('span').filter({ hasText: /^Second$/ });
+   const keyword = editor
+      .locator('span')
+      .filter({ hasText: /^node$/ })
+      .first();
+   for (const extension of [${composition.grammars.map(grammar => `'${grammar.extensions[0]}'`).join(', ')}]) {
+      await page.locator('#file').selectOption(\`nodes.\${extension}\`);
+      await expect(editor.locator('span').filter({ hasText: /^First$/ })).toHaveCSS('color', 'rgb(36, 122, 147)');
+      await expect(second).toHaveCount(2);
+      for (const target of await second.all()) {
+         await expect(target).toHaveCSS('color', 'rgb(36, 122, 147)');
+      }
+      await expect(keyword).toHaveCSS('color', 'rgb(0, 0, 255)');
+      await expect(editor.locator('.view-line > span > span').filter({ hasText: /A.second.node/ })).toHaveCSS('color', 'rgb(0, 128, 0)');
+      await page.locator('#file').selectOption(\`references.\${extension}\`);
+      await expect(editor.locator('span').filter({ hasText: /^Third$/ })).toHaveCSS('color', 'rgb(36, 122, 147)');
+      await expect(second).toHaveCSS('color', 'rgb(36, 122, 147)');
+   }
+});
+`
+         : ''
+   }`;
 }
 
 /** The browser host's README. */
@@ -4503,6 +4549,9 @@ ${sortedBlock(devDependencies, '    ')}
   },
   "engines": {
     "node": ">=22.13"
+  },
+  "hydranium": {
+    "services": "./server/lib/node/services.js"
   }
 }
 `;

package/src/commands/init.ts

@@ -720,7 +720,11 @@ export function runInit(options: InitCommandOptions): void {
    }
    // `npx`, not a bare invocation: `@hydranium/cli` is a devDependency of the
    // scaffold, so the binary is on PATH inside an npm script and nowhere else.
-   write(`  npx hydranium-cli reflect --services ./${server}/lib/node/services.js\n`);
+   write(
+      detection === undefined
+         ? '  npx hydranium-cli reflect\n'
+         : `  npx hydranium-cli reflect --services ./${server}/lib/node/services.js\n`
+   );
    const hostDir = (host: InitHost): string => (detection === undefined ? `host-${host}` : `${detection.targetPath}/host-${host}`);
    // A standalone root runs a host as `start:<host>`. A surrounding workspace's root is not ours to add to.
    const start = (host: InitHost): string => (detection === undefined ? `npm run start:${host}` : `npm --prefix ${hostDir(host)} start`);

package/src/commands/lint-grammar-args.ts

@@ -38,7 +38,7 @@ export const LINT_GRAMMAR_VALUE_FLAGS: readonly string[] = [...HARNESS_VALUE_FLA
 
 /** The `--help` text, as data, held to {@link LINT_GRAMMAR_FLAGS} by a test. */
 export const LINT_GRAMMAR_HELP: readonly string[] = [
-   'Usage: hydranium-cli lint-grammar --services <module> [--import <specifier>]... [--name-property <p>]... [--strict] [--json] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
+   'Usage: hydranium-cli lint-grammar [--services <module>] [--import <specifier>]... [--name-property <p>]... [--strict] [--json] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    "Check a head's grammar against the framework's conventions — a CI gate: the",
    'process exits non-zero when a violation is found. Read-only: no workspace is',
@@ -49,7 +49,7 @@ export const LINT_GRAMMAR_HELP: readonly string[] = [
    'zero-arg `createServices(): { shared }` thunk. Needs @hydranium/core.',
    '',
    'Options:',
-   '  --services <module>    ESM module exporting `createServices(): { shared }` (required).',
+   '  --services <module>    ESM module exporting `createServices(): { shared }` (required) unless package.json sets hydranium.services.',
    ...importHelpLines(23),
    '  --name-property <p>    Property that satisfies the nameability convention',
    '                         (repeatable). Default: name.',

package/src/commands/measure-memory-args.ts

@@ -49,7 +49,7 @@ export const MEASURE_MEMORY_VALUE_FLAGS: readonly string[] = [...HARNESS_VALUE_F
 
 /** The `--help` text, as data, held to {@link MEASURE_MEMORY_FLAGS} by a test. */
 export const MEASURE_MEMORY_HELP: readonly string[] = [
-   'Usage: hydranium-cli measure-memory --services <module> [--import <specifier>]... <workspace> [options]',
+   'Usage: hydranium-cli measure-memory [--services <module>] [--import <specifier>]... <workspace> [options]',
    '',
    'Measure model-store memory for a workspace. `<module>` is an ESM module that',
    'exports a zero-arg `createServices(): { shared }` thunk (the head wires its own',
@@ -57,7 +57,7 @@ export const MEASURE_MEMORY_HELP: readonly string[] = [
    'baseline / after-build / churn lines print on stdout. Needs @hydranium/core.',
    '',
    'Options:',
-   '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   '  --services <module>   ESM module exporting `createServices(): { shared }` (required) unless package.json sets hydranium.services.',
    ...importHelpLines(22),
    '  <workspace>           Workspace root (path or file URI) to build (required).',
    '  --edits <N>           Rebuild-churn cycles to probe for retention. Default: 0 (skip).',

package/src/commands/message-catalogue-args.ts

@@ -0,0 +1,55 @@
+/********************************************************************************
+ * 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 { assertRequired, exitWithUsage, helpRequested, printHelp, type UsageError } from './harness-args.js';
+import { runMessageCatalogue, type MessageCatalogueCommandOptions } from './message-catalogue.js';
+
+export const MESSAGE_CATALOGUE_FLAGS: readonly string[] = ['--barrel', '--out-file'];
+export const MESSAGE_CATALOGUE_VALUE_FLAGS = MESSAGE_CATALOGUE_FLAGS;
+export const MESSAGE_CATALOGUE_HELP: readonly string[] = [
+   'Usage: hydranium-cli message-catalogue --barrel <module>... [--out-file <file>]',
+   '',
+   'Emit a flat JSON starter catalogue mapping message codes to English defaults.',
+   'Modules are resolved from the current project and must be built first.',
+   'Repeat --barrel for each framework head and your own messages. No server starts.',
+   '',
+   'Options:',
+   '  --barrel <module>    Messages package specifier or ESM file (required). Repeatable.',
+   '  --out-file <file>   Write JSON here instead of stdout, after all imports succeed.'
+];
+
+export function parseMessageCatalogueArgs(args: string[], onError: UsageError = exitWithUsage): MessageCatalogueCommandOptions {
+   const barrels: string[] = [];
+   let outFile: string | undefined;
+   for (let index = 0; index < args.length; index++) {
+      const flag = args[index];
+      if (!MESSAGE_CATALOGUE_FLAGS.includes(flag)) {
+         return onError(`Unexpected argument: ${flag} (hydranium-cli message-catalogue --help)`);
+      }
+      const value = args[++index];
+      if (value === undefined || value.startsWith('--')) {
+         return onError(`Missing value for ${flag}`);
+      }
+      if (flag === '--barrel') {
+         barrels.push(value);
+      } else {
+         outFile = value;
+      }
+   }
+   assertRequired(barrels[0], '--barrel', 'message-catalogue', onError);
+   return { barrels, outFile };
+}
+
+export async function runMessageCatalogueCommand(args: string[]): Promise<void> {
+   if (helpRequested(args, MESSAGE_CATALOGUE_VALUE_FLAGS)) {
+      printHelp(MESSAGE_CATALOGUE_HELP);
+      return;
+   }
+   await runMessageCatalogue(parseMessageCatalogueArgs(args));
+}

package/src/commands/message-catalogue.ts

@@ -0,0 +1,56 @@
+/********************************************************************************
+ * 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 { collectMessages, type MessageCatalogue } from '@hydranium/protocol';
+import { resolve as resolveModule } from 'import-meta-resolve';
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { emitReport } from './headless-harness.js';
+
+/**
+ * Enumerate declarations rather than scanning source. Conflicting defaults
+ * must fail before any output is written, or import order chooses the English.
+ */
+export function createMessageCatalogue(barrels: readonly object[]): MessageCatalogue {
+   const entries = new Map<string, string>();
+   for (const barrel of barrels) {
+      for (const message of collectMessages(barrel)) {
+         const previous = entries.get(message.code);
+         if (previous !== undefined && previous !== message.text) {
+            throw new Error(`Conflicting English defaults for message '${message.code}'.`);
+         }
+         entries.set(message.code, message.text);
+      }
+   }
+   return Object.fromEntries([...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+
+export interface MessageCatalogueCommandOptions {
+   readonly barrels: readonly string[];
+   readonly outFile?: string;
+}
+
+/** Resolve against the caller's project, including when the CLI is installed globally. */
+export async function runMessageCatalogue(options: MessageCatalogueCommandOptions): Promise<void> {
+   const projectUrl = pathToFileURL(resolve('package.json')).href;
+   const barrels: object[] = [];
+   for (const specifier of options.barrels) {
+      const target =
+         specifier.startsWith('.') || isAbsolute(specifier) ? pathToFileURL(resolve(specifier)).href : resolveModule(specifier, projectUrl);
+      const barrel = (await import(target)) as object;
+      if (collectMessages(barrel).length === 0) {
+         throw new Error(`Message barrel '${specifier}' exports no declarations. Pass a built messages module.`);
+      }
+      barrels.push(barrel);
+   }
+   if (barrels.length === 0) {
+      throw new Error('Pass at least one --barrel messages module.');
+   }
+   emitReport(JSON.stringify(createMessageCatalogue(barrels), undefined, 2), options.outFile);
+}

package/src/commands/model-docs-args.ts

@@ -37,7 +37,7 @@ export const MODEL_DOCS_VALUE_FLAGS: readonly string[] = MODEL_DOCS_FLAGS;
 
 /** The `--help` text, as data, held to {@link MODEL_DOCS_FLAGS} by a test. */
 export const MODEL_DOCS_HELP: readonly string[] = [
-   'Usage: hydranium-cli model-docs --services <module> [--import <specifier>]... [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
+   'Usage: hydranium-cli model-docs [--services <module>] [--import <specifier>]... [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    'Generate a navigable Markdown reference of every AST node type — a type index,',
    'cross-linked super/sub types, a reverse "referenced by" index, and a per-language',
@@ -47,7 +47,7 @@ export const MODEL_DOCS_HELP: readonly string[] = [
    'zero-arg `createServices(): { shared }` thunk. Needs @hydranium/core.',
    '',
    'Options:',
-   '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   '  --services <module>   ESM module exporting `createServices(): { shared }` (required) unless package.json sets hydranium.services.',
    ...importHelpLines(22),
    '  --out-file <file>     Write the Markdown to this file instead of stdout. Written',
    '                        only once the report exists, unlike a shell redirection,',

package/src/commands/reflect-args.ts

@@ -38,7 +38,7 @@ export const REFLECT_VALUE_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS, .
 
 /** The `--help` text, as data, held to {@link REFLECT_FLAGS} by a test. */
 export const REFLECT_HELP: readonly string[] = [
-   'Usage: hydranium-cli reflect --services <module> [--import <specifier>]... [--json] [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
+   'Usage: hydranium-cli reflect [--services <module>] [--import <specifier>]... [--json] [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    "Dump a head's grammar/AST reflection — the type hierarchy, each language's",
    'terminals and entry rule, and every cross-reference target. Read-only: no',
@@ -47,7 +47,7 @@ export const REFLECT_HELP: readonly string[] = [
    'exporting a zero-arg `createServices(): { shared }` thunk. Needs @hydranium/core.',
    '',
    'Options:',
-   '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   '  --services <module>   ESM module exporting `createServices(): { shared }` (required) unless package.json sets hydranium.services.',
    ...importHelpLines(22),
    '  --json                Emit the raw JSON reflection instead of the Markdown report.',
    '  --out-file <file>     Write the report to this file instead of stdout. Written',

package/src/commands/validate-args.ts

@@ -38,7 +38,7 @@ export const VALIDATE_VALUE_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS,
 
 /** The `--help` text, as data, held to {@link VALIDATE_FLAGS} by a test. */
 export const VALIDATE_HELP: readonly string[] = [
-   'Usage: hydranium-cli validate --services <module> [--import <specifier>]... <workspace> [--strict] [--json] [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
+   'Usage: hydranium-cli validate [--services <module>] [--import <specifier>]... <workspace> [--strict] [--json] [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    'Build a workspace headlessly and report its validation diagnostics — a CI gate:',
    'the process exits non-zero when any error is found. `<module>` is an ESM module',
@@ -46,7 +46,7 @@ export const VALIDATE_HELP: readonly string[] = [
    'filesystem inside). Needs @hydranium/core.',
    '',
    'Options:',
-   '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   '  --services <module>   ESM module exporting `createServices(): { shared }` (required) unless package.json sets hydranium.services.',
    ...importHelpLines(22),
    '  <workspace>           Workspace root (path or file URI) to validate (required).',
    '  --strict              Also fail (non-zero exit) on warnings, not only errors.',

package/src/index.ts

@@ -17,3 +17,4 @@ export * from './commands/save.js';
 export * from './commands/watch.js';
 export * from './package-name.js';
 export * from './spawn-data-server.js';
+export * from './commands/message-catalogue.js';

package/templates/host-browser/src/editor.ts

@@ -6,6 +6,7 @@ import { initializeLanguageClient, type WorkerHeads } from '@hydranium/client-br
 import { MONACO_CLIENT_CAPABILITIES, MonacoLspClient } from '@hydranium/client-browser/monaco';
 import { describeError } from '@hydranium/protocol';
 import { ALL_LANGUAGES } from '__PROTOCOL_PACKAGE__';
+import * as monaco from 'monaco-editor-core';
 import { PublishDiagnosticsNotification } from 'vscode-languageserver-protocol';
 import { appendLog, setStatus } from './log.js';
 import type { ShownFile } from './shown-file.js';
@@ -18,6 +19,18 @@ declare const __MONACO_WORKER_BUNDLE_URL__: string;
 // bundle emits, and fails on the first edit.
 self.MonacoEnvironment = { getWorker: () => new Worker(__MONACO_WORKER_BUNDLE_URL__) };
 
+// Standalone Monaco has no TextMate scopes to map semantic types to colours.
+monaco.editor.defineTheme('__PROJECT_ID__', {
+   base: 'vs',
+   inherit: true,
+   rules: [
+      { token: 'class', foreground: '247a93' },
+      { token: 'keyword', foreground: '0000ff' },
+      { token: 'comment', foreground: '008000' }
+   ],
+   colors: {}
+});
+
 /** Each language as Monaco registers it, from the ids and extensions the server generates. */
 const LANGUAGES = ALL_LANGUAGES.map(language => ({
    id: language.languageId,
@@ -45,6 +58,7 @@ export async function startEditor(heads: WorkerHeads, shownFile: ShownFile): Pro
    const modelOf = (uri: string) => client.openDocument(uri, shownFile.files.get(uri) as string);
    const editor = client.createEditor(document.getElementById('editor') as HTMLElement, modelOf(shownFile.current()), {
       automaticLayout: true,
+      theme: '__PROJECT_ID__',
       minimap: { enabled: false },
       scrollBeyondLastLine: false,
       wordWrap: 'on'

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/test/__GRAMMAR_ID__-semantic-tokens.test.ts

@@ -0,0 +1,34 @@
+import { parseHelper } from '@hydranium/core/testing';
+import { SemanticTokensDecoder } from '@hydranium/langium/lsp';
+import { describe, expect, it } from 'vitest';
+import { create__NAME__Services } from '../src/language-server/__PROJECT_ID__-module.js';
+
+describe('__GRAMMAR__ semantic tokens', () => {
+   it.each([false, true])('colours declarations and references with lexical highlighting %s', async lexical => {
+      const { __GRAMMAR__ } = create__NAME__Services({}, { highlightKeywords: lexical, highlightComments: lexical });
+      const document = await parseHelper(__GRAMMAR__)('// comment\nnode first -> second\nnode second', {
+         documentUri: 'file:///tokens.__EXTENSION__',
+         validation: true
+      });
+      expect(document.diagnostics).toEqual([]);
+      const provider = __GRAMMAR__.lsp.SemanticTokenProvider!;
+      const tokens = await provider.semanticHighlight(document, { textDocument: { uri: document.uri.toString() } });
+      const decoded = SemanticTokensDecoder.decode(tokens, provider.tokenTypes, document).map(token => ({
+         text: token.text,
+         type: token.tokenType
+      }));
+      expect(decoded).toEqual([
+         ...(lexical
+            ? [
+                 { text: '// comment', type: 'comment' },
+                 { text: 'node', type: 'keyword' }
+              ]
+            : []),
+         { text: 'first', type: 'class' },
+         ...(lexical ? [{ text: '->', type: 'keyword' }] : []),
+         { text: 'second', type: 'class' },
+         ...(lexical ? [{ text: 'node', type: 'keyword' }] : []),
+         { text: 'second', type: 'class' }
+      ]);
+   });
+});