@hydranium/cli 1.0.0-next.31 → 1.0.0-next.312

package/lib/commands/init-templates.js

@@ -21,6 +21,9 @@
  *   `bin` key, the DI module filename, and the data-server port command.
  * - `__CONFIG_ROOT_CONST__` — SCREAMING_SNAKE project id, naming the
  *   `lsp.configurationRoot` constant a multi-grammar project binds.
+ * - `__PROTOCOL_PACKAGE__` — the protocol member's package name, scope
+ *   included, which the server and every client import ids and wire types
+ *   from.
  *
  * GRAMMAR tokens, substituted once per grammar:
  *
@@ -28,6 +31,8 @@
  *   Drives the PER-LANGUAGE generated symbols (`<grammar>GeneratedModule`,
  *   `<grammar>LanguageMetaData`).
  * - `__GRAMMAR_ID__` — kebab grammar id: the `.langium` filename.
+ * - `__GRAMMAR_ID_CONST__` — SCREAMING_SNAKE grammar id, prefixing the
+ *   diagram's type-id constants.
  * - `__LANGUAGE_ID__` — kebab routing key: the `langium-config` entry id and
  *   its TextMate output.
  * - `__EXTENSION__` — the grammar's FIRST file extension, without the dot.
@@ -48,10 +53,19 @@
  * generator emits `interface <projectName>Element` as the base type every rule
  * extends, which a rule of that name would collide with.
  *
- * Kept as in-source strings (not on-disk assets) so no build-time copy step
- * is needed and the substitution is unit-testable. The `.ts` / `.langium` / JSON
- * templates are derived from the in-repo reference example so the generated project
- * compiles against the real `@hydranium/*` API once `langium generate` has run.
+ * The project is two packages and a starter workspace, each in its own
+ * directory: `server/` (the grammar, the language and its heads), `protocol/`
+ * (what the server and its clients both import, so a client never installs
+ * Langium), and `workspace/` (starter model files every host and the CLI
+ * open). A standalone project adds a root manifest naming them as npm
+ * workspaces; a workspace member joins the surrounding root instead.
+ *
+ * A file that is fixed text with tokens lives in the `templates/` tree the
+ * package ships beside `lib`, at the path it is emitted at, tokens included
+ * (each ignore file without its dot); one computed from the composition is
+ * built here. The tree is read synchronously, so `runInit` stays synchronous,
+ * and it is neither formatted with the repo's settings nor given a license
+ * header, since either would change what `init` emits.
  *
  * Two conventions the templates follow deliberately:
  *
@@ -70,16 +84,8 @@
  *   is what the detection cannot fix. A very long `--name` can still push a line
  *   over; the adopter's own formatter settles it.
  */
+import { readFileSync } from 'node:fs';
 import { readCliVersion } from '../cli-version.js';
-/**
- * The version every framework package carries before the first release.
- *
- * A scaffold made by a CLI still at this version pins a range the registry
- * cannot serve, so the emitted README keeps its yalc note and `init` keeps its
- * install warning while — and only while — it holds: from a published CLI the
- * derived pins resolve and either note would be false as printed.
- */
-export const UNPUBLISHED_FRAMEWORK_VERSION = '0.0.0';
 /**
  * The version `init` pins every `@hydranium/*` dependency at: the scaffolding
  * CLI's own.
@@ -107,12 +113,47 @@ function frameworkPin(composition) {
 function screamingSnake(projectId) {
     return projectId.replace(/-/g, '_').toUpperCase();
 }
+/**
+ * A member's package name: `<id>-<member>`, under the scope when there is one.
+ *
+ * Suffixed even for the server, because a project of several packages has no
+ * member entitled to the bare id, and a later client or host would otherwise
+ * read as a part of the server.
+ */
+export function memberPackageName(composition, member) {
+    const { scope } = composition.packaging;
+    const name = `${composition.projectId}-${member}`;
+    return scope === undefined ? name : `${scope}/${name}`;
+}
+/**
+ * The composition as one member sees it: inside a workspace, its placement
+ * sits one directory below the project's, so its `extends` and its lint
+ * config path reach one level further up.
+ */
+function forMember(composition, member) {
+    const workspace = composition.packaging.workspace;
+    if (workspace === undefined) {
+        return composition;
+    }
+    return {
+        ...composition,
+        packaging: {
+            ...composition.packaging,
+            workspace: {
+                ...workspace,
+                targetPath: `${workspace.targetPath}/${member}`,
+                baseTsconfig: workspace.baseTsconfig === undefined ? undefined : `../${workspace.baseTsconfig}`
+            }
+        }
+    };
+}
 /** Substitute the project-tier tokens. */
 function project(text, composition) {
     return text
         .replace(/__NAME__/g, composition.name)
         .replace(/__PROJECT_ID__/g, composition.projectId)
-        .replace(/__CONFIG_ROOT_CONST__/g, screamingSnake(composition.projectId));
+        .replace(/__CONFIG_ROOT_CONST__/g, screamingSnake(composition.projectId))
+        .replace(/__PROTOCOL_PACKAGE__/g, memberPackageName(composition, 'protocol'));
 }
 /**
  * Substitute the grammar-tier tokens for ONE grammar.
@@ -124,6 +165,7 @@ function project(text, composition) {
  */
 function grammarTier(text, grammar) {
     return text
+        .replace(/__GRAMMAR_ID_CONST__/g, screamingSnake(grammar.grammarId))
         .replace(/__GRAMMAR_ID__/g, grammar.grammarId)
         .replace(/__GRAMMAR__/g, grammar.grammar)
         .replace(/__LANGUAGE_ID__/g, grammar.languageId)
@@ -135,6 +177,25 @@ function grammarTier(text, grammar) {
 function render(text, composition, grammar) {
     return grammarTier(project(text, composition), grammar);
 }
+/** The template tree, the same two levels up from `src/commands` and `lib/commands`. */
+const TEMPLATES = new URL('../../templates/', import.meta.url);
+/** One template file's text. */
+function template(path) {
+    return readFileSync(new URL(path, TEMPLATES), 'utf-8');
+}
+/** A template emitted once per project at its own path, rendered with the project tokens. */
+function projectTemplate(path, composition) {
+    return { path, content: project(template(path), composition) };
+}
+/** A template emitted once per grammar, its path rendered like its content. */
+function grammarTemplate(path, composition, grammar) {
+    return { path: render(path, composition, grammar), content: render(template(path), composition, grammar) };
+}
+/** An ignore file, stored without its dot because `npm pack` drops a nested `.gitignore` and applies it as an ignore file. */
+function ignoreFile(directory) {
+    const prefix = directory === '' ? '' : `${directory}/`;
+    return { path: `${prefix}.gitignore`, content: template(`${prefix}gitignore`) };
+}
 /** A comma-separated list of single-quoted TypeScript/JS string literals. */
 function quotedList(values) {
     return values.map(value => `'${value}'`).join(', ');
@@ -156,7 +217,7 @@ function columnsFor(composition) {
 }
 /**
  * A named import on one line while it fits the column budget, else one symbol
- * per line. Emitted files are supposed to pass a prettier check as-is, and the
+ * per line. Emitted files are supposed to pass a format check as-is, and the
  * generated-module import grows by one symbol per grammar.
  */
 function importList(symbols, from, columns, typeOnly = false) {
@@ -175,9 +236,13 @@ function arrayLiteral(elements, indent, columns) {
  * The FRAMEWORK packages each head adds, carrying no version: every
  * `@hydranium/*` pin is derived at scaffold time from {@link frameworkPin}, so
  * none of them can name a version its siblings were not published at.
+ *
+ * `base` is every head set's: the services every head serves from are composed
+ * the same with or without an LSP head.
  */
 const HEAD_FRAMEWORK_DEPENDENCIES = {
-    lsp: ['@hydranium/core', '@hydranium/langium', '@hydranium/protocol'],
+    base: ['@hydranium/core', '@hydranium/langium', '@hydranium/protocol'],
+    lsp: [],
     data: ['@hydranium/data-server'],
     glsp: ['@hydranium/glsp-server']
 };
@@ -197,15 +262,22 @@ const HEAD_FRAMEWORK_DEPENDENCIES = {
  * `overrides` block exists to prevent — so a repo gate holds each entry here
  * against the manifest that declares it.
  *
- * `langium` is required by `lsp` even though hand-written code goes through the
+ * `langium` is required even though hand-written code goes through the
  * `@hydranium/langium` chokepoint, because `langium-cli` emits direct imports
- * into the generated files and regenerates them on every build.
+ * into the generated files and regenerates them on every build. The `vscode-*`
+ * packages are required peers of `@hydranium/core`, so they are `base` too.
  */
 const HEAD_THIRD_PARTY_DEPENDENCIES = {
-    lsp: {
+    base: {
         langium: '4.3.1',
-        'vscode-languageserver': '~10.0.1'
+        // Exact, as are the protocol and transport it pins, so Langium and the
+        // framework share their copies; across copies, an error a handler throws
+        // or returns loses its code, and a later patch can pin another protocol.
+        'vscode-languageserver': '10.0.1',
+        'vscode-jsonrpc': '9.0.0',
+        'vscode-languageserver-protocol': '3.18.1'
     },
+    lsp: {},
     data: {},
     glsp: {
         '@eclipse-glsp/graph': '2.7.0',
@@ -216,25 +288,79 @@ const HEAD_THIRD_PARTY_DEPENDENCIES = {
         'reflect-metadata': '~0.2.2'
     }
 };
-/** The dependency block for a head set, merged and sorted as npm writes it. */
+/**
+ * What each head adds to the protocol member, which carries only what a
+ * client may install. Keyed by head because the `glsp` head implies a diagram,
+ * whose element ids extend GLSP's default type names.
+ */
+const PROTOCOL_THIRD_PARTY_DEPENDENCIES = {
+    lsp: {},
+    data: {},
+    glsp: { '@eclipse-glsp/protocol': '2.7.0' }
+};
+/**
+ * The exact pins of `heads`, for a workspace root to declare too. npm installs a
+ * root's own dependencies at the top of the tree, so another member's version of
+ * one nests beneath that member instead of taking the place of the copy this
+ * package shares with the framework.
+ */
+export function workspaceRootPins(heads) {
+    return [
+        ...Object.entries(HEAD_THIRD_PARTY_DEPENDENCIES.base),
+        ...heads.flatMap(head => [
+            ...Object.entries(HEAD_THIRD_PARTY_DEPENDENCIES[head]),
+            ...Object.entries(PROTOCOL_THIRD_PARTY_DEPENDENCIES[head])
+        ])
+    ]
+        .filter(([, version]) => /^\d+\.\d+\.\d+$/.test(version))
+        .sort(([left], [right]) => left.localeCompare(right));
+}
+/** Whether an npm version is 11.6.0 or later, the first that installs `vitest` 4.1's peer set; `11.6.0-rc.1` is earlier. */
+function installsVitest41(npmVersion) {
+    const [release, prerelease] = (npmVersion ?? '0.0.0').split('-', 2);
+    const [major, minor, patch] = release.split('.').map(Number);
+    return major > 11 || (major === 11 && (minor > 6 || (minor === 6 && (patch > 0 || prerelease === undefined))));
+}
+/**
+ * Whether the scaffold holds `vitest` below 4.1, whose peer set crashes npm
+ * before 11.6 (every npm a Node 22 release bundles) on the first install. Only a
+ * workspace root declaring a newer npm lifts it, and only when `init` runs under
+ * an npm known to be newer: npm does not enforce `packageManager`.
+ */
+function pinsVitest(composition) {
+    const workspace = composition.packaging.workspace;
+    return !(installsVitest41(workspace?.packageManagerNpm) && installsVitest41(workspace?.npmVersion));
+}
+/**
+ * The version a member pins a sibling member at: exact, at the version every
+ * member starts with. npm links a sibling only when the range admits its local
+ * version, and otherwise looks for it in the registry, where it was never
+ * published.
+ */
+const MEMBER_PIN = '0.0.0';
+/** A dependency block, sorted as npm writes it. */
+function sortedBlock(dependencies, indent) {
+    return Object.keys(dependencies)
+        .sort()
+        .map(name => `${indent}"${name}": "${dependencies[name]}"`)
+        .join(',\n');
+}
+/** The server's dependency block: the base and head set's packages and the protocol member. */
 function dependencyBlock(composition, indent) {
-    const merged = {};
-    for (const head of composition.heads) {
+    const merged = { [memberPackageName(composition, 'protocol')]: MEMBER_PIN };
+    for (const head of ['base', ...composition.heads]) {
         Object.assign(merged, HEAD_THIRD_PARTY_DEPENDENCIES[head]);
         for (const framework of HEAD_FRAMEWORK_DEPENDENCIES[head]) {
             merged[framework] = frameworkPin(composition);
         }
     }
-    return Object.keys(merged)
-        .sort()
-        .map(name => `${indent}"${name}": "${merged[name]}"`)
-        .join(',\n');
+    return sortedBlock(merged, indent);
 }
 // JSON at two-space indent, not the three the `.ts` templates use: that is the
 // npm convention, and `npm install` rewrites `package.json` at two spaces
 // regardless — so three would not survive the adopter's first install.
 //
-// The KEY ORDER is `prettier-plugin-packagejson`'s canonical one, `private`
+// The KEY ORDER is the one Oxfmt's `sortPackageJson` canonicalises to, `private`
 // before `license` included. Any other order is rewritten by the scaffolded
 // project's own first `format` run — a diff on a file the adopter never touched
 // — and it makes a byte-compare against a formatted copy of this emission
@@ -254,6 +380,11 @@ function dependencyBlock(composition, indent) {
 // from this package's own grammar and can reach a consumer from nowhere else; a
 // listed path that does not exist yet is inert.
 //
+// `exports` puts `createServices`, the one module reading the real filesystem,
+// behind `./node`, so the root loads in a browser worker that has no `node:fs`.
+// `./lib/*` and `./package.json` stay reachable for a host that resolves
+// `<server>/lib/main.js` to spawn the server.
+//
 // `repository` is deliberately NOT emitted while `author` is emitted empty. An
 // empty `author` is the form `npm init` itself writes and asserts nothing, but
 // `repository` is CONSUMED — the registry page, `npm repo` and publish
@@ -265,16 +396,9 @@ const PACKAGE_JSON = `{
   "version": "0.0.0",
 __PRIVATE__  "description": "__NAME__ language server, built with the Hydranium framework.",
   "keywords": [
-    "hydranium",
-    "langium",
-    "language-server",
-    "__PROJECT_ID__"
-  ],
+__KEYWORDS__  ],
   "license": "UNLICENSED",
   "author": "",
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
   "bin": {
 __BIN__  },
   "files": [
@@ -282,17 +406,32 @@ __BIN__  },
     "src",
     "syntaxes"
   ],
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./node": {
+      "types": "./lib/node/services.d.ts",
+      "default": "./lib/node/services.js"
+    },
+    "./lib/*": "./lib/*",
+    "./package.json": "./package.json"
+  },
   "scripts": {
-    "build": "npm run generate && tsc",
+    "build": "npm run generate && tsc -b",
     "clean": "rimraf lib syntaxes src/language-server/generated src/language-server/generated-hydranium tsconfig.tsbuildinfo",
     "generate": "npm run langium:generate && npm run generate:transfer-model",
-    "generate:transfer-model": "hydranium-cli generate-transfer-model --ast-file src/language-server/generated/ast.ts --augmentation-file src/language-server/ast.ts --out-file src/language-server/generated-hydranium/transfer-model.ts --ast-builder-file src/language-server/generated-hydranium/ast-builder.ts --element-type-name __NAME__Element --terminals-name __NAME__Terminals --regen-command \\"Run: __NPM_RUN__ generate:transfer-model\\"",
+    "generate:transfer-model": "hydranium-cli generate-transfer-model --ast-file src/language-server/generated/ast.ts --augmentation-file src/language-server/ast.ts --out-file ../protocol/src/generated-hydranium/transfer-model.ts --ast-builder-file src/language-server/generated-hydranium/ast-builder.ts --languages-file ../protocol/src/generated-hydranium/languages.ts --element-type-name __NAME__Element --terminals-name __NAME__Terminals --regen-command \\"Run: __NPM_RUN__ generate:transfer-model\\"",
     "langium:generate": "langium generate",
     "langium:watch": "langium generate --watch",
-__LINT__    "start": "node lib/main.js --stdio",
+__LINT__    "start": "node lib/main.js__START_ARGS__",
     "test": "npm run typecheck:test && vitest run",
     "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
-    "watch": "tsc --watch"
+    "watch": "tsc -b --watch"
   },
   "dependencies": {
 __DEPENDENCIES__
@@ -302,8 +441,8 @@ __DEPENDENCIES__
     "@types/node": "^22.0.0",
     "langium-cli": "4.3.0",
     "rimraf": "^5.0.0",
-    "typescript": "^5.8.0",
-    "vitest": "^4.0.0"
+    "typescript": "^7.0.2",
+    "vitest": "__VITEST__"
   },
   "engines": {
     "node": ">=22.13"
@@ -311,16 +450,17 @@ __DEPENDENCIES__
 }
 `;
 /**
- * How the scaffold names `npm run` when talking about itself.
+ * How the scaffold names `npm run` for one member's script.
  *
- * A workspace member's scripts are routinely invoked from the repo root, where
- * a bare `npm run` reaches the ROOT manifest and fails — so the regen hint a
- * generated file prints has to name the package, or it sends every reader who
- * follows it to the wrong place.
+ * Always with `--prefix`, from the directory commands are run in: the
+ * workspace root for a member, the project root for a standalone project. A
+ * bare `npm run` there reaches the ROOT manifest and fails, and the regen hint
+ * a generated file prints is read in `protocol/` as well, where the script it
+ * names does not exist.
  */
-function npmRun(composition) {
+function npmRun(composition, member) {
     const workspace = composition.packaging.workspace;
-    return workspace === undefined ? 'npm run' : `npm --prefix ${workspace.targetPath} run`;
+    return `npm --prefix ${workspace === undefined ? member : `${workspace.targetPath}/${member}`} run`;
 }
 /**
  * The `bin` targets, one per executable entry the head set emits.
@@ -331,7 +471,7 @@ function npmRun(composition) {
  * name. Without the second key a scaffolded project has no command line that
  * reaches its own data head at all.
  *
- * Alphabetical, because `prettier-plugin-packagejson` sorts `bin` and any other
+ * Alphabetical, because Oxfmt's `sortPackageJson` sorts `bin` and any other
  * order is rewritten by the scaffolded project's first `format` run.
  */
 function binBlock(composition) {
@@ -341,21 +481,37 @@ function binBlock(composition) {
     }
     return entries.map(([name, target]) => `    "${name}": "${target}"`).join(',\n') + '\n';
 }
-/** `package.json` with the name, the private flag and the dependency block all derived. */
+/**
+ * A member's `lint` script line, over `directories`, or nothing.
+ *
+ * Emitted only where a root lint config says the repo lints. The absence is
+ * the dangerous direction: a task runner runs a script only where one is
+ * declared, so a package with no `lint` is SKIPPED rather than reported, and
+ * that reads as a clean lint. A wrong invocation is one visible line to edit.
+ */
+function lintScript(member, directories) {
+    const workspace = member.packaging.workspace;
+    if (workspace?.oxlintConfig !== undefined) {
+        const config = `${'../'.repeat(workspace.targetPath.split('/').length)}${workspace.oxlintConfig}`;
+        return `    "lint": "oxlint --report-unused-disable-directives --format stylish --config ${config} ${directories} --max-warnings 0",\n`;
+    }
+    return workspace?.eslintConfig !== undefined ? `    "lint": "eslint ${directories} --max-warnings 0",\n` : '';
+}
+/** The server's `package.json`, with the name, the private flag and the dependency block all derived. */
 function packageJson(composition) {
-    const { scope } = composition.packaging;
-    const packageName = scope === undefined ? composition.projectId : `${scope}/${composition.projectId}`;
-    // Emitted only where a root eslint config says the repo lints. The absence is
-    // the dangerous direction: a task runner runs a script only where one is
-    // declared, so a package with no `lint` is SKIPPED rather than reported, and
-    // that reads as a clean lint. A wrong invocation is one visible line to edit.
-    const lint = composition.packaging.workspace?.eslintConfig === undefined ? '' : '    "lint": "eslint src test --max-warnings 0",\n';
+    const keywords = ['hydranium', 'langium', 'language-server', composition.projectId]
+        .sort()
+        .map(keyword => `    ${JSON.stringify(keyword)}`)
+        .join(',\n') + '\n';
     return project(PACKAGE_JSON, composition)
-        .replace('__PACKAGE_NAME__', packageName)
+        .replace('__PACKAGE_NAME__', memberPackageName(composition, 'server'))
+        .replace('__KEYWORDS__', keywords)
         .replace('__BIN__', binBlock(composition))
-        .replace('__LINT__', lint)
+        .replace('__LINT__', lintScript(forMember(composition, 'server'), 'src test'))
+        .replace('__START_ARGS__', composition.heads.includes('lsp') ? ' --stdio' : ' ../workspace')
+        .replace('__VITEST__', pinsVitest(composition) ? '~4.0.18' : '^4.0.0')
         .replace('__PRIVATE__', composition.packaging.private ? '  "private": true,\n' : '')
-        .replace('__NPM_RUN__', npmRun(composition))
+        .replace('__NPM_RUN__', npmRun(composition, 'server'))
         .replace('__FRAMEWORK_PIN__', frameworkPin(composition))
         .replace('__DEPENDENCIES__', dependencyBlock(composition, '    '));
 }
@@ -406,6 +562,11 @@ const TSCONFIG_COMPILER_OPTIONS = [
     ['outDir', 'lib'],
     ['strict', true],
     ['esModuleInterop', true],
+    // A server that renders its own user-facing messages loads a catalogue, and
+    // a catalogue is JSON. Without this the import does not resolve at all, and
+    // without the `include` glob below a composite project rejects it with
+    // TS6307 naming neither cause.
+    ['resolveJsonModule', true],
     ['skipLibCheck', true],
     ['declaration', true],
     ['experimentalDecorators', true],
@@ -413,6 +574,23 @@ const TSCONFIG_COMPILER_OPTIONS = [
     ['forceConsistentCasingInFileNames', true],
     ['types', ['node']]
 ];
+/** The protocol member's compiler options, pruned against a workspace base like the server's. */
+const PROTOCOL_COMPILER_OPTIONS = [
+    ['target', 'ES2022'],
+    ['lib', ['ES2022']],
+    ['module', 'NodeNext'],
+    ['moduleResolution', 'NodeNext'],
+    ['rootDir', 'src'],
+    ['outDir', 'lib'],
+    ['strict', true],
+    ['skipLibCheck', true],
+    ['declaration', true],
+    // The server's `tsc -b` builds this project through a reference, which
+    // `tsc` refuses unless the referenced project is composite.
+    ['composite', true],
+    // No ambient Node types: a browser client compiles against this package.
+    ['types', []]
+];
 /**
  * The options that describe where THIS package's own files live. Never pruned,
  * and emitted first in the workspace case: a base config that supplied them
@@ -420,9 +598,19 @@ const TSCONFIG_COMPILER_OPTIONS = [
  * base is wrong rather than that the member is redundant.
  */
 const PACKAGE_LOCAL_OPTIONS = ['rootDir', 'outDir'];
-/** Compare two JSON option values. Sound here because compiler options are scalars and flat arrays. */
-function jsonEquals(left, right) {
-    return JSON.stringify(left) === JSON.stringify(right);
+/**
+ * The enum-valued options of {@link TSCONFIG_COMPILER_OPTIONS}, whose values
+ * `tsc` reads case-insensitively, so `nodenext` and `NodeNext` are one value.
+ * An enum-valued option added there belongs here too.
+ */
+const CASE_INSENSITIVE_OPTIONS = ['target', 'lib', 'module', 'moduleResolution'];
+/** Compare two option values. Sound here because compiler options are scalars and flat arrays. */
+function optionEquals(key, left, right) {
+    const normalise = (value) => {
+        const text = JSON.stringify(value);
+        return CASE_INSENSITIVE_OPTIONS.includes(key) ? text?.toLowerCase() : text;
+    };
+    return normalise(left) === normalise(right);
 }
 /**
  * `tsconfig.json`, extending the workspace's base config when there is one.
@@ -431,104 +619,41 @@ function jsonEquals(left, right) {
  * the same key: inheriting `"module": "CommonJS"` where the scaffold needs
  * `NodeNext` would break every emitted import, so a differing base value is a
  * reason to keep the override rather than to trust the parent.
+ *
+ * `member` is the composition as that member sees it, so `extends` reaches the
+ * workspace base from the member's own directory.
  */
-function tsconfigJson(composition) {
-    const workspace = composition.packaging.workspace;
+function tsconfigJson(member, compilerOptions, include, references = '') {
+    const workspace = member.packaging.workspace;
     const base = workspace?.baseTsconfig === undefined ? undefined : (workspace.baseCompilerOptions ?? {});
     const options = base === undefined
-        ? TSCONFIG_COMPILER_OPTIONS
+        ? compilerOptions
         : [
-            ...TSCONFIG_COMPILER_OPTIONS.filter(([key]) => PACKAGE_LOCAL_OPTIONS.includes(key)),
-            ...TSCONFIG_COMPILER_OPTIONS.filter(([key, value]) => !PACKAGE_LOCAL_OPTIONS.includes(key) && !jsonEquals(base[key], value))
+            ...compilerOptions.filter(([key]) => PACKAGE_LOCAL_OPTIONS.includes(key)),
+            ...compilerOptions.filter(([key, value]) => !PACKAGE_LOCAL_OPTIONS.includes(key) && !optionEquals(key, base[key], value))
         ];
     const extendsLine = workspace?.baseTsconfig === undefined ? '' : `  "extends": "${workspace.baseTsconfig}",\n`;
     const body = options.map(([key, value]) => `    "${key}": ${JSON.stringify(value)}`).join(',\n');
-    return `{\n${extendsLine}  "compilerOptions": {\n${body}\n  },\n  "include": ["src"]\n}\n`;
-}
-// `isolatedModules` is what makes this check agree with the transform that
-// actually runs the tests. `npm test` is `typecheck:test && vitest run`, and
-// vitest compiles through esbuild — a per-file transform with no type
-// information, which cannot tell a re-exported TYPE from a re-exported value.
-// Without the flag `tsc` accepts `export { SomeType } from './x'` that esbuild
-// then emits as a real import of a symbol that does not exist at runtime, so
-// the typecheck passes and the suite fails with a confusing missing-export.
-const TSCONFIG_TEST = `{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "rootDir": ".",
-    "noEmit": true,
-    "isolatedModules": true,
-    "types": ["node"]
-  },
-  "include": ["src", "test"]
+    const referencesLine = references === '' ? '' : `,\n  "references": ${references}`;
+    return `{\n${extendsLine}  "compilerOptions": {\n${body}\n  },\n  "include": ${include}${referencesLine}\n}\n`;
 }
-`;
-const VITEST_CONFIG = `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 the esbuild
-// transform strips types without checking them.
-
-export default defineConfig({
-   test: {
-      environment: 'node',
-      include: ['test/**/*.{test,spec}.ts']
-   }
-});
-`;
-const GITIGNORE = `node_modules/
-lib/
-*.tsbuildinfo
-
-# Langium-generated TextMate grammar (rewritten by every \`langium generate\`).
-syntaxes/
-`;
 /**
- * The workspace-member `.gitignore` — one entry, and the one entry a root
- * cannot be assumed to have.
- *
- * A member inherits the root's rules, and `node_modules/`, `lib/` and
- * `*.tsbuildinfo` are in every monorepo root already, so repeating them here
- * would be three lines to keep in step for no coverage. `syntaxes/` is not like
- * them: it is a Langium artefact, so a root that has never held a Langium
- * package has no rule for it, and the first `langium generate` then offers
- * generated output up for commit with nothing to warn the adopter. Dropping the
- * whole file rather than this subset is the mistake this template exists to
- * undo.
+ * The server's `tsconfig.json`. It references the protocol member, so `tsc -b`
+ * compiles protocol first, after `generate` has written its generated modules.
  */
-const GITIGNORE_WORKSPACE_MEMBER = `# The workspace root already covers \`node_modules/\`, \`lib/\` and \`*.tsbuildinfo\`.
-# It has no reason to know about this one: the TextMate grammar is a Langium
-# artefact, rewritten by every \`langium generate\`, so a root that has never held
-# a Langium package ignores nothing here and the generated file is offered for
-# commit.
-syntaxes/
-`;
-/** The terminals every grammar needs, shared verbatim by the fragment and the lone-grammar case. */
-const TERMINALS = `hidden terminal WS: /\\s+/;
-terminal ID: /[_a-zA-Z][\\w_]*/;
-hidden terminal SL_COMMENT: /\\/\\/[^\\n\\r]*/;
-hidden terminal ML_COMMENT: /\\/\\*[\\s\\S]*?\\*\\//;
-`;
+function serverTsconfigJson(composition) {
+    return tsconfigJson(forMember(composition, 'server'), TSCONFIG_COMPILER_OPTIONS, '["src", "src/**/*.json"]', '[{ "path": "../protocol" }]');
+}
 /**
- * The shared lexical fragment, emitted only for a multi-grammar project.
- *
- * The alternative — every grammar declaring its own `WS` / `ID` — lets the token
- * sets drift apart.
+ * The terminals every grammar needs: the shared fragment's text after its
+ * leading comment run, so a lone grammar declares the same set.
  */
-const COMMON_GRAMMAR = `// 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.
-
-${TERMINALS}`;
+function terminals() {
+    return template('server/src/grammar/common.langium').replace(/^(\/\/.*\n)*\n/, '');
+}
 /** One starter grammar. `shared` decides whether it imports the fragment or declares its own terminals. */
 function grammarFile(shared) {
-    const lexis = shared ? "import './common'\n" : `\n${TERMINALS}`;
+    const lexis = shared ? "import './common'\n" : `\n${terminals()}`;
     return `grammar __GRAMMAR__
 ${shared ? '\n' + lexis : ''}
 // A minimal starter grammar — replace with your own language. \`__NODE_RULE__\` is
@@ -696,179 +821,89 @@ ${returnType}
 `;
     return project(text, composition);
 }
-const SERVICES = `// Zero-arg service factory for the headless \`hydranium-cli\` tooling: the
-// \`reflect\` / \`lint-grammar\` / \`validate\` subcommands import this via
-// \`--services ./lib/services.js\`. The head wires its own filesystem here.
-//
-// The contract is language-count-agnostic — a second grammar needs no edit here.
-
-import { NodeFileSystem } from '@hydranium/core/node';
-import { create__NAME__Services } from './language-server/__PROJECT_ID__-module.js';
-
-export function createServices(): ReturnType<typeof create__NAME__Services> {
-   return create__NAME__Services({ ...NodeFileSystem });
-}
-`;
-const AST = `// The language's AST entry point: a re-export of what \`langium generate\`
-// emits, plus anywhere you augment those types.
-//
-// Import the AST from HERE rather than from \`./generated/ast.js\`, so any
-// augmentation below travels with every import. One \`langium-cli\` run over N
-// grammars emits ONE combined AST module sharing one reflection, so a further
-// grammar needs no change here.
-//
-// \`generate:transfer-model\` reads this file as its \`--augmentation-file\`: the
-// generated wire types are derived from the AST *as augmented*, not from the
-// raw generated module. Augment a type here and the transfer model follows.
-//
-// A \`@derived\` property is computed at build time rather than parsed, so it is
-// declared here and populated by an AST-extension contribution:
-//
-// declare module './generated/ast.js' {
-//    interface __ENTRY_RULE__ {
-//       /** @derived Populated by an \`ast.extensions.computedProperties\` contribution. */
-//       readonly _summary?: string;
-//    }
-// }
-
-export * from './generated/ast.js';
-`;
 /**
- * The starter serializer — the concrete-syntax emitter for ONE grammar.
+ * How a host finds each socket head's port, in emission order: an LSP request
+ * when the LSP head publishes the ports, else the environment variable
+ * `main.ts` reads a port from.
  *
- * Emitted per grammar, not per project, because `services.serializer.Serializer`
- * is a per-language slot and a serializer is grammar-shaped by definition. That
- * is also why the framework refuses to default it: its `UnboundSerializer`
- * throws, naming the binding to add, rather than guessing a syntax.
- */
-const SERIALIZER = `// 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. \`ModelService.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}\`;
-   }
-}
-`;
-/**
- * The exported constant names for the head set, in emission order. Both are
- * keyed by the PROJECT rather than by a language: one server of each kind per
+ * Keyed by the PROJECT rather than by a language: one server of each kind per
  * process serves every registered grammar, so a language-derived name would tie
  * a project-level endpoint to whichever grammar was scaffolded first.
  */
-function portCommandNames(composition) {
+function headPortConstants(composition) {
     const upper = screamingSnake(composition.projectId);
-    return [
-        ...(composition.heads.includes('data') ? [`${upper}_DATA_SERVER_PORT_COMMAND`] : []),
-        ...(composition.heads.includes('glsp') ? [`${upper}_GLSP_PORT_COMMAND`] : [])
+    const lsp = composition.heads.includes('lsp');
+    const heads = [
+        ...(composition.heads.includes('data') ? [{ key: 'DATA_SERVER', path: 'data-server', label: 'data-server' }] : []),
+        ...(composition.heads.includes('glsp') ? [{ key: 'GLSP_SERVER', path: 'glsp-server', label: 'GLSP' }] : [])
     ];
+    return heads.map(head => lsp
+        ? {
+            name: `${upper}_${head.key}_PORT_COMMAND`,
+            value: `${composition.projectId}/${head.path}/port`,
+            doc: `LSP request the host queries to discover the ${head.label} socket port.`
+        }
+        : {
+            name: `${upper}_${head.key}_PORT_ENV`,
+            value: `${upper}_${head.key}_PORT`,
+            doc: `Environment variable naming the ${head.label} socket port when no \`--${head.path}-port\` flag does.`
+        });
 }
 /**
- * The socket heads' discovery commands, as an importable module.
+ * The socket heads' port commands or variables, in the protocol member.
  *
- * Deliberately NOT declared in `main.ts`. A host shell has to name the same
- * string to reach the head, and `main.ts` opens a connection at module scope,
- * so importing a constant from it would start a server. A host that retypes the
- * literal instead gets no error when it drifts: the framework's port poll
- * defaults to `findPortAttempts = -1`, so a wrong command retries forever
- * rather than failing.
+ * A host shell has to name the same string the server reads, and reaches it
+ * here without depending on the server. A host that retypes the literal
+ * instead gets no error when it drifts: the framework's port poll defaults to
+ * `findPortAttempts = -1`, so a wrong command retries forever rather than
+ * failing, and a wrong variable is never read.
  */
 function headPortsFile(composition) {
-    const upper = screamingSnake(composition.projectId);
-    const data = composition.heads.includes('data');
-    const glsp = composition.heads.includes('glsp');
-    const blocks = [
-        ...(data
-            ? [
-                `/** LSP request the host queries to discover the data-server socket port. */\nexport const ${upper}_DATA_SERVER_PORT_COMMAND = '${composition.projectId}/data-server/port';`
-            ]
-            : []),
-        ...(glsp
-            ? [
-                `/** LSP request the host queries to discover the GLSP socket port. */\nexport const ${upper}_GLSP_PORT_COMMAND = '${composition.projectId}/glsp/port';`
-            ]
-            : [])
-    ];
-    return `// The LSP requests a host queries to discover this server's socket head${blocks.length > 1 ? 's' : ''}.
+    const constants = headPortConstants(composition);
+    const blocks = constants.map(constant => `/** ${constant.doc} */\nexport const ${constant.name} = '${constant.value}';`);
+    const heads = `socket head${blocks.length > 1 ? 's' : ''}`;
+    const opening = composition.heads.includes('lsp')
+        ? `// The LSP requests a host queries to discover this server's ${heads}.`
+        : `// The environment variables that name the ports of this server's ${heads}.`;
+    const usage = composition.heads.includes('lsp')
+        ? `// The server publishes them and a host shell has to name the same string to
+// reach the head; both import them from here. A shell that retypes the literal
+// gets no error when it drifts: the framework's port poll retries indefinitely
+// by default.`
+        : `// The server reads them and a process that starts it sets them; both import
+// them from here. A variable retyped with a typo is never read, and the head
+// then listens on whichever port is free.`;
+    return `${opening}
 //
-// Both are keyed by the PROJECT, not the language: one server of each kind per
+// ${blocks.length > 1 ? 'Both are' : 'It is'} keyed by the PROJECT, not the language: one server of each kind per
 // process serves every registered grammar, so a language-derived name would tie
 // a project-level endpoint to whichever grammar was scaffolded first.
 //
-// They live here rather than in \`main.ts\` because a host shell has to name the
-// same string to reach the head, and \`main.ts\` is an executable entry — nothing
-// can import from it. A shell that retypes the literal gets no error when it
-// drifts: the framework's port poll retries indefinitely by default. Import
-// these instead, and assert any host-side copy against them.
+${usage}
 
 ${blocks.join('\n\n')}
 `;
 }
-const INDEX = `// Public surface of the __NAME__ language server: the DI factory, the generated
-// AST, and the headless \`createServices\` entry.
+/**
+ * The server's root entry: the DI factory, the generated AST and each diagram
+ * module, all loadable in a browser worker.
+ */
+function indexFile(composition) {
+    const diagrams = composition.grammars.filter(grammar => grammar.diagram);
+    const diagramPhrase = diagrams.length === 0 ? '' : diagrams.length === 1 ? ', plus the diagram module' : ', plus the diagram modules';
+    const text = `// Public surface of the __NAME__ language server: the DI factory and the
+// generated AST${diagramPhrase}.
 //
-// The entry points under \`src/\` are deliberately NOT re-exported. Each opens a
-// transport at module scope, so importing one starts a server as a side effect
-// — which is why they are \`bin\` targets and this file is \`main\`.
+// Everything here loads in a browser worker as well as in Node, so a host can
+// compose the language wherever it runs it. \`createServices\`, which reads the
+// real filesystem, is the package's \`./node\` entry instead. The entry points
+// under \`src/\` are not re-exported either: each opens a transport at module
+// scope, so importing one starts a server, which is why they are \`bin\` targets.
 
 export * from './language-server/__PROJECT_ID__-module.js';
 export * from './language-server/ast.js';
-export { createServices } from './services.js';
-`;
-/**
- * The public surface, plus the head-port commands when there is a socket head.
- *
- * The commands belong here rather than only in `head-ports.ts` so a host shell
- * reaches them from the package root, the same way it reaches `createServices`.
- */
-function indexFile(composition) {
-    const base = project(INDEX, composition);
-    return portCommandNames(composition).length ? `${base}export * from './head-ports.js';\n` : base;
+${diagrams.map(grammar => `export * from './glsp/${grammar.grammarId}/diagram-module.js';\n`).join('')}`;
+    return project(text, composition);
 }
 /**
  * The `#!` line every emitted `bin` target carries.
@@ -896,10 +931,12 @@ function mainFile(composition) {
     const columns = columnsFor(composition);
     const roots = [...composition.grammars.map(grammar => grammar.entryRule)].sort();
     const upper = screamingSnake(composition.projectId);
+    const lsp = composition.heads.includes('lsp');
     const data = composition.heads.includes('data');
     const glsp = composition.heads.includes('glsp');
     const diagrams = composition.grammars.filter(grammar => grammar.diagram);
     const plural = roots.length > 1 ? 's' : '';
+    const portFlags = [...(data ? ['--data-server-port'] : []), ...(glsp ? ['--glsp-server-port'] : [])];
     const headNames = composition.heads.map(head => head === 'lsp' ? 'the Langium LSP head' : head === 'data' ? 'a socket data-server (model server) head' : 'a GLSP head');
     // Comma-joined but for the last, which takes `and`: a bare `, ` join reads as
     // a truncated list, and the emitted comment is the first thing an adopter
@@ -908,7 +945,7 @@ function mainFile(composition) {
     // `reflect-metadata` must be imported before anything that reads a
     // decorator's emitted metadata, which inversify does at module scope.
     const reflectImport = glsp ? "import 'reflect-metadata';\n" : '';
-    const coreNodeSymbols = ['NodeFileSystem', ...(data ? ['publishPortOnLspConnection', 'startSocketServer'] : [])];
+    const coreNodeSymbols = ['NodeFileSystem', ...(data ? [...(lsp ? ['publishPortOnLspConnection'] : []), 'startSocketServer'] : [])];
     const glspImports = glsp
         ? `import { ServerModule } from '@eclipse-glsp/server/node.js';
 import { GlspClientLogger, HydraniumGlspAppModule } from '@hydranium/glsp-server';
@@ -925,44 +962,57 @@ import { startGlspServer } from '@hydranium/glsp-server/node';
 // \`TransferElement\` structurally, so naming the AST type here compiles fine and
 // silently tells every typed client that a reference is a resolvable object
 // rather than a name.
-${importList(roots, './language-server/generated-hydranium/transfer-model.js', columns, true)}
+${importList(roots, memberPackageName(composition, 'protocol'), columns, true)}
 `
         : '';
-    // The commands live in `head-ports.ts`, not here: a host shell has to name
-    // the same string to reach the head, and this file is an executable entry, so
-    // nothing can import from it.
-    const portCommands = portCommandNames(composition).length
-        ? importList(portCommandNames(composition), './head-ports.js', columns) + '\n'
-        : '';
-    const dataBlock = data
-        ? `
+    // The names live in the protocol member, not here: a host shell has to name
+    // the same string to reach the head, and this file is an executable entry,
+    // so nothing can import from it.
+    const portNames = headPortConstants(composition).map(constant => constant.name);
+    const portImports = portNames.length ? importList(portNames, memberPackageName(composition, 'protocol'), columns) + '\n' : '';
+    const dataBlock = !data
+        ? ''
+        : !lsp
+            ? `
+// Data-server head: each accepted client gets its own DataServer.
+const dataServer = startSocketServer(
+   { shared, workspace, port: portFrom('data-server-port', ${upper}_DATA_SERVER_PORT_ENV), logTag: 'ModelServer', logger: shared.Logger },
+   dataConnection => {
+      new DataServer<${roots.join(' | ')}>(dataConnection, shared);
+      return { dispose: () => undefined };
+   }
+);
+`
+            : `
 // Data-server head alongside LSP: binds an ephemeral port, published over the LSP
 // connection for the host to discover. Each accepted client gets its own DataServer.
 //
 // Neither the bind nor the publish may be swallowed: either failure leaves the LSP
 // head serving text edits while every data client waits on a port command that was
 // never registered, and the launcher reports a bind failure only if given a logger.
-const dataServer = startSocketServer({ port: 0, logTag: 'ModelServer', logger: shared.Logger }, dataConnection => {
+const dataServer = startSocketServer({ shared, port: 0, logTag: 'ModelServer', logger: shared.Logger }, dataConnection => {
    new DataServer<${roots.join(' | ')}>(dataConnection, shared);
    return { dispose: () => undefined };
 });
 dataServer.started
-   .then(() => {
-      const { port } = dataServer;
-      if (port === undefined) {
-         // \`started\` resolves only once the address is resolved, so this is
-         // unreachable; a non-null assertion in its place would publish
-         // \`undefined\`, which the host cannot tell from an unreachable port.
-         throw new Error('the data head started without a resolved port');
-      }
-      publishPortOnLspConnection(shared.lsp.Connection, ${upper}_DATA_SERVER_PORT_COMMAND, port);
-   })
+   .then(
+      () => {
+         const { port } = dataServer;
+         if (port === undefined) {
+            // \`started\` resolves only once the address is resolved, so this is
+            // unreachable; a non-null assertion in its place would publish
+            // \`undefined\`, which the host cannot tell from an unreachable port.
+            throw new Error('the data head started without a resolved port');
+         }
+         publishPortOnLspConnection(shared.lsp.Connection, ${upper}_DATA_SERVER_PORT_COMMAND, port);
+      },
+      // The launcher logged its own bind failure; the rejection is control flow.
+      () => undefined
+   )
    .catch((error: unknown) => {
-      const reason = error instanceof Error ? error.message : String(error);
-      shared.Logger.error(\`[ModelServer] Could not publish the data-server port: \${reason}\`);
+      shared.Logger.error(\`[ModelServer] Could not publish the data-server port: \${describeErrorWithStack(error)}\`);
    });
-`
-        : '';
+`;
     const glspBlock = glsp
         ? `
 // GLSP head on the same shared workspace. \`HydraniumGlspAppModule\` is used
@@ -970,59 +1020,118 @@ dataServer.started
 // grammar a request concerns, so nothing per-language belongs there — each
 // diagram module declares its own language instead.
 //
-// GLSP framework logs route through the LSP connection rather than stdout, which
-// IS the LSP transport in stdio mode; writing there corrupts the protocol stream.
+${lsp
+            ? `// GLSP framework logs route through the LSP connection rather than stdout, which
+// IS the LSP transport in stdio mode; writing there corrupts the protocol stream.`
+            : `// GLSP framework logs route through the framework's logger to stderr. GLSP's
+// own startup line goes to stdout, beside the ports line below.`}
 const glspServer = startGlspServer({
    // The GLSP log threshold lives on the logger, not beside it: the framework
    // replaces GLSP's own \`Logger\` binding, so a launcher-level \`logLevel\` would
    // be discarded. The logger tracks the framework's process-wide threshold, so
-   // \`HYDRANIUM_LOG_LEVEL\` and the LSP log-level setting govern GLSP output too;
+   // \`HYDRANIUM_LOG_LEVEL\` ${lsp ? 'and the LSP log-level setting govern' : 'governs'} GLSP output too;
    // pass \`logLevel\` only to make GLSP quieter than the rest of the server.
    createLogger: caller => new GlspClientLogger(shared, { component: caller }),
    serverModule: new ServerModule()${diagrams.map(grammar => `.configureDiagramModule(new ${grammar.grammar}DiagramModule())`).join('')},
    appModules: [new HydraniumGlspAppModule({ shared })],
-   lspConnection: shared.lsp.Connection,
-   portCommand: ${upper}_GLSP_PORT_COMMAND
+${lsp
+            ? `   lspConnection: shared.lsp.Connection,
+   portCommand: ${upper}_GLSP_SERVER_PORT_COMMAND`
+            : `   workspace,
+   port: portFrom('glsp-server-port', ${upper}_GLSP_SERVER_PORT_ENV),
+   logger: shared.Logger`}
 });
-void glspServer;
-`
+${lsp ? 'void glspServer;\n' : ''}`
         : '';
+    const lspImports = `// The framework's entry point, NOT Langium's \`@hydranium/langium/lsp\` one. It is
+// signature-compatible and delegates straight through; what it adds first is
+// \`assertLspHeadComposed\`, which fails the start if the LSP head's SHARED module
+// was never composed. Reaching for Langium's is the natural mistake and it is
+// silent: the server boots, links and completes, while echo suppression, the
+// didChangeContent debounce and the last-client-close rebuild are all inert.
+import { startLanguageServer, withHydraniumLspFeatures } from '@hydranium/core/lsp';
+import { ProposedFeatures, createConnection } from 'vscode-languageserver/node';
+`;
+    const lspStart = `
+const connection = createConnection(withHydraniumLspFeatures(ProposedFeatures.all));
+const { shared } = create__NAME__Services({ connection, ...NodeFileSystem });
+startLanguageServer(shared);
+`;
+    // No LSP client names the workspace or asks for the ports here, so the
+    // command line does, and the ports go to stdout once every head listens.
+    const servers = [...(data ? ['dataServer'] : []), ...(glsp ? ['glspServer'] : [])];
+    const socketStart = `
+const { values, positionals } = parseArgs({
+   options: { ${portFlags.map(flag => `'${flag.slice(2)}': { type: 'string' }`).join(', ')} },
+   allowPositionals: true
+});
+// The workspace root: the first argument, else the process cwd.
+const workspace = positionals[0] ?? process.cwd();
+
+/** A head's port: its flag, else its environment variable, else 0 for any free port. */
+function portFrom(flag: keyof typeof values, variable: string): number {
+   const text = values[flag] ?? process.env[variable] ?? '0';
+   const port = Number(text);
+   // Decimal digits only: \`Number\` also reads '' as 0 and takes '1e3' or '0x10'.
+   if (!/^\\d+$/.test(text) || port > 65_535) {
+      throw new Error(\`--\${flag} or \${variable} is '\${text}', not a port\`);
+   }
+   return port;
+}
+
+const { shared } = create__NAME__Services({ ...NodeFileSystem });
+`;
+    const portsLine = `
+// One JSON line on stdout once every head listens, for the process that started
+// this one to read the ports from: the one line that starts with \`{\`. Each
+// head brings the workspace up before it listens; a head that fails to start
+// has logged why and ends the process, which would otherwise serve without it.
+Promise.all([${servers.map(server => `${server}.started`).join(', ')}]).then(
+   () => process.stdout.write(\`\${JSON.stringify({ ${servers.map(server => `${server}: ${server}.port`).join(', ')} })}\\n\`),
+   () => process.exit(1)
+);
+`;
+    const invocation = lsp
+        ? `// Invocation: \`node lib/main.js --stdio\`, or the package's \`__PROJECT_ID__\` bin
+// script.`
+        : `// Invocation: \`node lib/main.js [<workspace-path>] ${portFlags.map(flag => `[${flag} <port>]`).join(' ')}\`,
+// or the package's \`__PROJECT_ID__\` bin script. Each port falls back to its
+// environment variable, then to any free port.`;
+    const dataNote = !data
+        ? ''
+        : lsp
+            ? `
+//
+// NOT the entry the data-server subcommands of \`hydranium-cli\` speak to: stdio
+// here carries LSP, and the data head is a socket whose port is published over
+// the LSP connection. Those subcommands spawn \`data-server-main.js\`.`
+            : `
+//
+// NOT the entry the data-server subcommands of \`hydranium-cli\` speak to: they
+// drive the data protocol over a child's stdio, and the data head here is a
+// socket. Those subcommands spawn \`data-server-main.js\`.`;
     const text = `${SHEBANG}// Standalone entry point: starts ${headSummary} in the same
 // process, so every head shares one model store.
-// Invocation: \`node lib/main.js --stdio\`, or the package's \`__PROJECT_ID__\` bin
-// script.${data
-        ? `
-//
-// NOT the entry \`hydranium-cli query\` / \`save\` / \`projects\` / \`watch\` speak to:
-// stdio here carries LSP, and the data head is a socket whose port is published
-// over the LSP connection. Those subcommands spawn \`data-server-main.js\`.`
-        : ''}
+${invocation}${dataNote}
 //
 // Everything here runs at module scope, so this file is an executable rather
 // than a library entry — import \`./index.js\` instead to compose the language.
 
 ${reflectImport}${glspImports}${importList(coreNodeSymbols, '@hydranium/core/node', columns)}
-${data ? "import { DataServer } from '@hydranium/data-server';\n" : ''}import { startLanguageServer } from '@hydranium/langium/lsp';
-import { ProposedFeatures, createConnection } from 'vscode-languageserver/node';
-${diagramImports}${transferImports}import { create__NAME__Services } from './language-server/__PROJECT_ID__-module.js';
-${portCommands === '' ? '' : '\n' + portCommands}
-const connection = createConnection(ProposedFeatures.all);
-const { shared } = create__NAME__Services({ connection, ...NodeFileSystem });
-startLanguageServer(shared);
-${dataBlock}${glspBlock}`;
+${data ? "import { DataServer } from '@hydranium/data-server';\n" : ''}${data && lsp ? "import { describeErrorWithStack } from '@hydranium/protocol';\n" : ''}${lsp ? lspImports : "import { parseArgs } from 'node:util';\n"}${diagramImports}${transferImports}import { create__NAME__Services } from './language-server/__PROJECT_ID__-module.js';
+${portImports === '' ? '' : '\n' + portImports}${lsp ? lspStart : socketStart}${dataBlock}${glspBlock}${lsp ? '' : portsLine}`;
     return project(text, composition);
 }
 /**
  * The second executable entry: the data head alone, on stdio.
  *
  * Emitted with the `data` head because it is the ONLY command line that reaches
- * that head from outside the editor. `main.ts` gives stdio to LSP and publishes
- * the data head's socket port over the LSP connection, so a client that is not
- * an LSP client cannot discover it — which is every one of `hydranium-cli`'s
- * `query` / `save` / `projects` / `watch`, all of which drive the data protocol
- * over a spawned child's stdin/stdout. Without this file a scaffolded project
- * has no `--server` value, and the closest guess — the LSP entry — fails as an
- * unrecognised method rather than as a missing head.
+ * that head from outside the editor. `main.ts` serves the data head on a
+ * socket, so a client driving the data protocol over a spawned child's
+ * stdin/stdout cannot reach it — which is every data-server subcommand of
+ * `hydranium-cli`. Without this file a scaffolded project has no `--server`
+ * value, and the closest guess, `main.ts`, fails as an unrecognised method or
+ * an unknown flag rather than as a missing head.
  *
  * A separate process rather than a flag on `main.ts`: only one protocol can own
  * stdio, so the two entries are mutually exclusive by construction.
@@ -1032,21 +1141,25 @@ function dataServerMainFile(composition) {
     const roots = [...composition.grammars.map(grammar => grammar.entryRule)].sort();
     const plural = roots.length > 1 ? 's' : '';
     const text = `${SHEBANG}// Standalone entry point: a data-server head on **stdio**, with no LSP head in
-// the process. This is the transport \`hydranium-cli\` speaks — \`query\`, \`save\`,
-// \`projects\` and \`watch\` all spawn a server command and drive JSON-RPC over its
-// stdin/stdout — so it is what makes those subcommands usable against this
-// language.
+// the process. This is the transport \`hydranium-cli\` speaks — its data-server
+// subcommands spawn a server command and drive JSON-RPC over its stdin/stdout —
+// so it is what makes those subcommands usable against this language.
 //
 // Invocation: \`node lib/data-server-main.js [<workspace-path>]\`, or the
 // package's \`__PROJECT_ID__-data-server\` bin script. The workspace path defaults to
 // the process cwd, which is what the CLI's \`--cwd\` sets on the child.
 //
-// Contrast with \`main.ts\`, the editor entry: there the LSP head owns stdio and
+${composition.heads.includes('lsp')
+        ? `// Contrast with \`main.ts\`, the editor entry: there the LSP head owns stdio and
 // the data head is a socket published over the LSP connection. Here there is no
 // LSP connection at all, so the workspace initialization an
 // \`initialize\`/\`initialized\` pair would otherwise drive has to happen here —
 // which is why this entry uses \`startStdioServer\` rather than wiring a
-// connection directly.
+// connection directly.`
+        : `// Contrast with \`main.ts\`, where the data head is a socket whose port it
+// prints. Here it owns stdio, and as there, no LSP connection drives the
+// workspace initialization, so \`startStdioServer\` brings the workspace up
+// before it listens.`}
 //
 // Everything here runs at module scope, so this file is an executable rather
 // than a library entry — import \`./index.js\` instead to compose the language.
@@ -1054,7 +1167,7 @@ function dataServerMainFile(composition) {
 ${importList(['NodeFileSystem', 'startStdioServer'], '@hydranium/core/node', columns)}
 import { DataServer } from '@hydranium/data-server';
 // The TRANSFER root${plural}, not the AST one${plural} — same reasoning as \`main.ts\`.
-${importList(roots, './language-server/generated-hydranium/transfer-model.js', columns, true)}
+${importList(roots, memberPackageName(composition, 'protocol'), columns, true)}
 import { create__NAME__Services } from './language-server/__PROJECT_ID__-module.js';
 
 const { shared } = create__NAME__Services({ ...NodeFileSystem });
@@ -1102,7 +1215,7 @@ function servicesTest(composition) {
 // is missing from the composition.
 
 import { describe, expect, it } from 'vitest';
-import { createServices } from '../src/services.js';
+import { createServices } from '../src/node/services.js';
 
 describe('__NAME__ services', () => {
    it('composes the DI tree and registers ${title}', () => {
@@ -1170,8 +1283,8 @@ function serializationTest(composition) {
     const transferTypes = composition.grammars.map(grammar => `${grammar.entryRule} as Transfer${grammar.entryRule}`);
     const text = `// Round-trips each grammar through its serializer: parse the source, serialize
 // the model, compare the text. The serializer is the parser's inverse, so this
-// is the assertion that keeps \`ModelService.update\` / \`save\` writing files the
-// language server can read back.
+// is the assertion that keeps a client session's \`update\` / \`save\` writing
+// files the language server can read back.
 //
 // The transfer case is the one that catches the mistake worth catching.
 // \`ModelService.modelToText\` short-circuits only a RAW STRING, so a typed model
@@ -1181,8 +1294,8 @@ function serializationTest(composition) {
 import { parseHelper } from '@hydranium/core/testing';
 import { describe, expect, it } from 'vitest';
 ${importList(astTypes, '../src/language-server/ast.js', columns, true)}
-${importList(transferTypes, '../src/language-server/generated-hydranium/transfer-model.js', columns, true)}
-import { createServices } from '../src/services.js';
+${importList(transferTypes, memberPackageName(composition, 'protocol'), columns, true)}
+import { createServices } from '../src/node/services.js';
 
 ${composition.grammars.map(grammar => render(SERIALIZATION_SUITE, composition, grammar)).join('\n\n')}
 `;
@@ -1305,7 +1418,7 @@ function grammarTest(composition, header, imports, suite) {
 import { parseHelper } from '@hydranium/core/testing';
 import { describe, expect, it } from 'vitest';
 ${imports.join('\n')}${imports.length ? '\n' : ''}${importList(astTypes, '../src/language-server/ast.js', columns, true)}
-import { createServices } from '../src/services.js';
+import { createServices } from '../src/node/services.js';
 
 ${composition.grammars.map(grammar => render(suite, composition, grammar)).join('\n\n')}
 `;
@@ -1332,6 +1445,7 @@ function readme(composition) {
     const multi = composition.grammars.length > 1;
     const data = composition.heads.includes('data');
     const primaryExtension = composition.grammars[0].extensions[0];
+    const diagramCount = composition.grammars.filter(grammar => grammar.diagram).length;
     const grammarBullets = composition.grammars.map(grammar => `- \`src/grammar/${grammar.grammarId}.langium\` — the \`${grammar.grammar}\` grammar (.${grammar.extensions.join(', .')})`);
     const lines = [
         '# __NAME__',
@@ -1340,20 +1454,6 @@ function readme(composition) {
         '',
         '## Getting started',
         '',
-        // Conditional on the pin this scaffold actually carries — see
-        // `UNPUBLISHED_FRAMEWORK_VERSION`.
-        ...(composition.frameworkVersion === UNPUBLISHED_FRAMEWORK_VERSION
-            ? [
-                '> **Pre-publish note.** `@hydranium/*` is not on npm yet, so the `0.0.0`',
-                '> pins below are placeholders and `npm install` will fail with a 404 until',
-                '> the framework is released. Until then, supply the packages from a local',
-                '> framework checkout with [yalc](https://github.com/wclr/yalc) — a plain',
-                '> `file:` path or `npm link` is not enough, because the framework packages',
-                '> depend on each other by version and npm would try to fetch those from the',
-                '> registry too.',
-                ''
-            ]
-            : []),
         '```bash',
         'npm install',
         'npm run langium:generate   # generate the AST from the grammar',
@@ -1368,25 +1468,26 @@ function readme(composition) {
         // nowhere else.
         '```bash',
         '# Grammar / AST reflection',
-        'npx hydranium-cli reflect --services ./lib/services.js',
+        'npx hydranium-cli reflect --services ./lib/node/services.js',
         '',
         '# Grammar-convention lint (CI gate)',
-        'npx hydranium-cli lint-grammar --services ./lib/services.js',
+        'npx hydranium-cli lint-grammar --services ./lib/node/services.js',
         '',
         '# Validate a workspace of model files (non-zero exit on errors)',
-        'npx hydranium-cli validate --services ./lib/services.js <workspace-dir>',
+        'npx hydranium-cli validate --services ./lib/node/services.js ../workspace',
         ...(data
             ? [
                 '',
                 '# Data-head operations. `--server` is a command line the CLI spawns and then',
                 "# drives the data protocol over the child's stdin/stdout, so it has to name",
-                '# `data-server-main.js` — `main.js` gives stdio to LSP and answers these',
-                '# methods with "Unhandled method".',
+                ...(composition.heads.includes('lsp')
+                    ? ['# `data-server-main.js` — `main.js` gives stdio to LSP and answers these', '# methods with "Unhandled method".']
+                    : ['# `data-server-main.js` — `main.js` serves the data head on a socket.']),
                 '#',
                 '# The workspace goes to the ENTRY, not to `--cwd`: `--cwd` re-roots the child,',
                 '# so a relative entry path is refused by name (an absolute one is fine).',
-                'npx hydranium-cli projects --server "node ./lib/data-server-main.js <workspace-dir>"',
-                `npx hydranium-cli query --server "node ./lib/data-server-main.js <workspace-dir>" --uri <file:// URI of a .${primaryExtension} file>`
+                'npx hydranium-cli projects --server "node ./lib/data-server-main.js ../workspace"',
+                `npx hydranium-cli query --server "node ./lib/data-server-main.js ../workspace" --uri <file:// URI of ../workspace/nodes.${primaryExtension}>`
             ]
             : []),
         '```',
@@ -1397,8 +1498,8 @@ function readme(composition) {
         ...(multi ? ['- `src/grammar/common.langium` — shared terminals, imported by each grammar (not a language)'] : []),
         '- `src/language-server/__PROJECT_ID__-module.ts` — `create__NAME__Services` DI wiring',
         ...composition.grammars.map(grammar => `- \`src/language-server/${grammar.grammarId}-serializer.ts\` — emits \`${grammar.grammar}\` back to text (the framework defaults this to a throw)`),
-        '- `src/services.ts` — zero-arg `createServices()` for the headless CLI',
-        '- `src/index.ts` — the package entry (`main`): DI factory + generated AST',
+        "- `src/node/services.ts` — zero-arg `createServices()` for the headless CLI, the package's `./node` entry",
+        `- \`src/index.ts\` — the package root, loadable in a browser worker: DI factory + generated AST${diagramCount === 0 ? '' : diagramCount === 1 ? ' + diagram module' : ' + diagram modules'}`,
         `- \`src/main.ts\` — starts ${composition.heads.join(' + ')}, the \`__PROJECT_ID__\` bin entry`,
         ...(data
             ? [
@@ -1408,7 +1509,8 @@ function readme(composition) {
             : []),
         ...composition.grammars
             .filter(grammar => grammar.diagram)
-            .map(grammar => `- \`src/glsp/${grammar.grammarId}/\` — the \`${grammar.grammar}\` diagram: type ids, state, storage, submission handler, GModel factory, configuration, create-node handler, DI module`),
+            .map(grammar => `- \`src/glsp/${grammar.grammarId}/\` — the \`${grammar.grammar}\` diagram: state, storage, submission handler, GModel factory, configuration, create-node handler, DI module`),
+        `- \`../protocol/\` — the \`${memberPackageName(composition, 'protocol')}\` package: what this server and its clients both import (language ids, ${headPortConstants(composition).length === 0 ? '' : composition.heads.includes('lsp') ? 'port commands, ' : 'port variables, '}${composition.grammars.some(grammar => grammar.diagram) ? 'diagram ids, ' : ''}the transfer model), written partly by \`npm run generate\``,
         '- `test/services.test.ts` — the DI tree composes; grows as your language does',
         '- `test/parsing.test.ts` / `linking.test.ts` / `validating.test.ts` — the three tiers a new language breaks first',
         '- `test/serialization.test.ts` — each grammar round-trips through its serializer',
@@ -1461,6 +1563,24 @@ function readme(composition) {
         'atomic set and depends on a single physical copy, so a floating range can',
         'silently resolve a second one.',
         '',
+        '`vscode-languageserver` is pinned to `10.0.1`, and',
+        '`vscode-languageserver-protocol` and `vscode-jsonrpc` to the `3.18.1` and',
+        '`9.0.0` it pins, so Langium, the LSP connection and the framework share one',
+        'copy of each. With two, an error a Langium handler returns, such as a request',
+        'for a document the server does not have, reaches the client as a result, and a',
+        'framework error your own LSP handler throws loses its code. The Langium 4.4',
+        'upgrade',
+        '([eclipse-emfcloud/hydranium#142](https://github.com/eclipse-emfcloud/hydranium/issues/142))',
+        'replaces these pins.',
+        '',
+        ...(pinsVitest(composition)
+            ? [
+                '`vitest` is held below 4.1, whose peer set crashes the npm every Node 22',
+                'release bundles. Raise it once every npm that installs this project is',
+                '11.6 or later.',
+                ''
+            ]
+            : []),
         '## If your repo gates license headers',
         '',
         'The emitted `.ts` files carry no copyright header — the scaffold cannot know',
@@ -1479,10 +1599,9 @@ function readme(composition) {
 /**
  * The GLSP files for ONE grammar's diagram.
  *
- * Per grammar rather than per project because a diagram type has exactly one
- * grammar — `AbstractHydraniumGlspDiagramModule.declareLanguage()` returns that
- * grammar's `LanguageMetaData`, and it is bound on the SESSION container so a
- * grammar with no diagram can sit on the same server.
+ * Per grammar rather than per project because the state, storage and GModel
+ * factory are typed over that grammar's model, and a grammar with no diagram
+ * can sit on the same server.
  *
  * The index and the computed-bounds handler are framework classes used
  * unmodified; storage and the submission handler are thin typed subclasses,
@@ -1496,152 +1615,11 @@ function readme(composition) {
  */
 function glspFiles(composition, grammar) {
     const columns = columnsFor(composition);
-    const upper = screamingSnake(grammar.grammarId);
-    const dir = `src/glsp/${grammar.grammarId}`;
-    const render = (text) => grammarTier(project(text, composition), grammar);
-    const types = `// GLSP diagram-type and element-type ids for the __GRAMMAR__ diagram.
-//
-// **Authoritative half of a client/server contract.** Every id here has to be
-// registered on the client too: 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/server';
-
-/**
- * The GLSP diagram type — the string GLSP routes every per-diagram-type request
- * by. Mirrored by the client; a mismatch silently DROPS the request rather than
- * reporting an unknown diagram type. Same value as the language id, so the two
- * cannot drift apart as a diagram gains element types.
- */
-export const ${upper}_DIAGRAM_TYPE = '__LANGUAGE_ID__';
-
-/** A \`__NODE_RULE__\` — the starter grammar's one named, referenceable node. */
-export const ${upper}_NODE_TYPE = \`\${DefaultTypes.NODE}:__GRAMMAR_ID__-node\`;
-
-/** A resolved \`target\` reference, drawn as a connection between two nodes. */
-export const ${upper}_EDGE_TYPE = \`\${DefaultTypes.EDGE}:__GRAMMAR_ID__-target\`;
-`;
-    const state = `// 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__> {}
-`;
-    const storage = `// Source-model storage for the __GRAMMAR__ diagram, inheriting both framework
-// defaults: \`loadSourceModel\` (open + settle + \`setSourceRoot\`) and
-// \`saveSourceModel\` (through \`ModelService.save\` → the per-URI \`Serializer\` →
-// the multi-client text store → \`WritableFileSystemProvider\`).
-//
-// 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> {}
-`;
-    const submission = `// 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';
-   }
-}
-`;
-    const factory = `// 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. 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 LSP head already reports it as a diagnostic.
-
-import { DefaultTypes, GEdge, GGraph, GLabel, type GModelFactory, GNode, ModelState } from '@eclipse-glsp/server';
-import { inject, injectable } from 'inversify';
-import type { __ENTRY_RULE__ } from '../../language-server/ast.js';
-import { ${upper}_EDGE_TYPE, ${upper}_NODE_TYPE } from './types.js';
-import type { __GRAMMAR__GlspState } from './state.js';
-
-@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 {
-      for (const node of root.nodes) {
-         const id = this.modelState.index.createId(node);
-         graph.children.push(
-            GNode.builder()
-               .id(id)
-               .type(${upper}_NODE_TYPE)
-               .add(GLabel.builder().id(\`\${id}_name\`).text(node.name).type(DefaultTypes.LABEL).build())
-               .build()
-         );
-      }
-      for (const node of root.nodes) {
-         const target = node.target?.ref;
-         if (!target) {
-            continue;
-         }
-         const sourceId = this.modelState.index.createId(node);
-         graph.children.push(
-            GEdge.builder()
-               .id(\`\${sourceId}_target\`)
-               .type(${upper}_EDGE_TYPE)
-               .sourceId(sourceId)
-               .targetId(this.modelState.index.createId(target))
-               .build()
-         );
-      }
-   }
-}
-`;
+    const fixed = (file) => grammarTemplate(`server/src/glsp/__GRAMMAR_ID__/${file}`, composition, grammar);
+    const computed = (file, text) => ({
+        path: `server/src/glsp/${grammar.grammarId}/${file}`,
+        content: render(text, composition, grammar)
+    });
     const configuration = `// Diagram configuration for the __GRAMMAR__ diagram.
 //
 // **Every hint is \`false\`, and that is not the same as read-only.** The starter
@@ -1661,7 +1639,7 @@ export class __GRAMMAR__GModelFactory implements GModelFactory {
 import { type GModelElementConstructor } from '@eclipse-glsp/graph';
 ${importList(['type DiagramConfiguration', 'type EdgeTypeHint', 'ServerLayoutKind', 'type ShapeTypeHint', 'getDefaultMapping'], '@eclipse-glsp/server', columns)}
 import { injectable } from 'inversify';
-import { ${upper}_EDGE_TYPE, ${upper}_NODE_TYPE } from './types.js';
+import { __GRAMMAR_ID_CONST___EDGE_TYPE, __GRAMMAR_ID_CONST___NODE_TYPE } from '__PROTOCOL_PACKAGE__';
 
 @injectable()
 export class __GRAMMAR__DiagramConfiguration implements DiagramConfiguration {
@@ -1673,7 +1651,7 @@ export class __GRAMMAR__DiagramConfiguration implements DiagramConfiguration {
 
    readonly shapeTypeHints: ShapeTypeHint[] = [
       {
-         elementTypeId: ${upper}_NODE_TYPE,
+         elementTypeId: __GRAMMAR_ID_CONST___NODE_TYPE,
          deletable: false,
          reparentable: false,
          repositionable: false,
@@ -1683,105 +1661,18 @@ export class __GRAMMAR__DiagramConfiguration implements DiagramConfiguration {
 
    readonly edgeTypeHints: EdgeTypeHint[] = [
       {
-         elementTypeId: ${upper}_EDGE_TYPE,
+         elementTypeId: __GRAMMAR_ID_CONST___EDGE_TYPE,
          deletable: false,
          repositionable: false,
          routable: false,
-         sourceElementTypeIds: [${upper}_NODE_TYPE],
-         targetElementTypeIds: [${upper}_NODE_TYPE]
+         sourceElementTypeIds: [__GRAMMAR_ID_CONST___NODE_TYPE],
+         targetElementTypeIds: [__GRAMMAR_ID_CONST___NODE_TYPE]
       }
    ];
 }
-`;
-    const createHandler = `// The starter operation handler for the __GRAMMAR__ diagram: the tool-palette
-// entry that creates a \`__NODE_RULE__\`.
-//
-// **Deleting this file and its \`configureOperationHandlers\` registration in
-// \`diagram-module.ts\` gives a read-only viewer**, and nothing else has to change
-// — creation is offered through the palette rather than through a type hint, so
-// every hint in \`diagram-configuration.ts\` is already \`false\`. 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 composes TEXT rather than mutating the AST.** The source model of
-// \`FullTextHydraniumGlspState\` is the document text, and reading it back through
-// \`state.sourceModel\` serialises the AST through the per-URI \`Serializer\`, which
-// this scaffold does not bind — so that getter throws until you do. Appending a
-// declaration to the text the parser last read needs no serializer, which is what
-// makes a scaffolded diagram editable on day one. Bind a \`Serializer\` at
-// \`services.serializer.Serializer\` and this becomes a
-// \`HydraniumGlspRecordingCommand\` over \`state.sourceModel\` instead — the same
-// binding the diagram's own save action needs.
-//
-// **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 \`types.ts\`, \`gmodel-factory.ts\` and \`diagram-configuration.ts\`, this file
-// knows the starter grammar's concrete syntax — the \`node\` keyword below is that
-// grammar's. Replacing the grammar means replacing these four together.
-
-import { type Command, type CreateNodeOperation, JsonCreateNodeOperationHandler, type MaybePromise } from '@eclipse-glsp/server';
-import { findNextUnique } from '@hydranium/protocol';
-import { injectable } from 'inversify';
-import { ${upper}_NODE_TYPE } from './types.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 = [${upper}_NODE_TYPE];
-
-   override createCommand(operation: CreateNodeOperation): MaybePromise<Command | undefined> {
-      if (!this.elementTypeIds.includes(operation.elementTypeId)) {
-         return undefined;
-      }
-      const state = this.modelState;
-      const before = this.documentText();
-      const after = this.withNode(
-         before,
-         findNextUnique(
-            NODE_NAME_STEM,
-            state.sourceRoot.nodes.map(node => node.name)
-         )
-      );
-      // Whole-document undo, which is all a full-text source model can offer: it
-      // has exactly one field, so there is nothing to merge a concurrent edit into.
-      return {
-         execute: () => state.updateSourceModel({ text: after }),
-         undo: () => state.updateSourceModel({ text: before }),
-         redo: () => state.updateSourceModel({ text: after })
-      };
-   }
-
-   /** The text the captured source root was parsed from — the baseline an edit appends to. */
-   protected documentText(): string {
-      return this.modelState.sourceRoot.$document?.textDocument.getText() ?? '';
-   }
-
-   /** \`text\` with one more node declaration, under exactly one trailing newline. */
-   protected withNode(text: string, name: string): string {
-      const body = text.trimEnd();
-      const declaration = \`node \${name}\`;
-      return body.length === 0 ? \`\${declaration}\\n\` : \`\${body}\\n\${declaration}\\n\`;
-   }
-}
 `;
     const module = `// GLSP diagram module for __GRAMMAR__ — the DI wiring of one diagram type.
 //
-// \`declareLanguage\` is the multi-grammar seam: it binds the grammar this diagram
-// edits on the SESSION container, so \`modelState.diagramLanguage\` and the
-// per-language lookups resolve to __LANGUAGE_ID__. That is what stops one
-// diagram type from fighting over a process-wide binding when a project holds
-// several grammars — a grammar with no diagram is registered on the same server.
-//
 // \`configureActionHandlers\` REBINDS rather than adds: GLSP's own
 // \`DiagramModule\` already registers \`ComputedBoundsActionHandler\`, and two
 // handlers for one action would both run.
@@ -1803,23 +1694,17 @@ ${importList([
         'SourceModelStorage'
     ], '@eclipse-glsp/server', columns, true)}
 import { ComputedBoundsActionHandler } from '@eclipse-glsp/server';
-import type { LanguageMetaData } from '@hydranium/langium';
 ${importList(['HydraniumGlspComputedBoundsActionHandler', 'AbstractHydraniumGlspDiagramModule', 'HydraniumGlspIndex'], '@hydranium/glsp-server', columns)}
-import { __GRAMMAR__LanguageMetaData } from '../../language-server/generated/module.js';
 import { __GRAMMAR__CreateNodeOperationHandler } from './create-node-operation-handler.js';
 import { __GRAMMAR__DiagramConfiguration } from './diagram-configuration.js';
 import { __GRAMMAR__GModelFactory } from './gmodel-factory.js';
 import { __GRAMMAR__GlspState } from './state.js';
 import { __GRAMMAR__GlspStorage } from './storage.js';
 import { __GRAMMAR__SubmissionHandler } from './submission-handler.js';
-import { ${upper}_DIAGRAM_TYPE } from './types.js';
+import { __GRAMMAR_ID_CONST___DIAGRAM_TYPE } from '__PROTOCOL_PACKAGE__';
 
 export class __GRAMMAR__DiagramModule extends AbstractHydraniumGlspDiagramModule {
-   readonly diagramType = ${upper}_DIAGRAM_TYPE;
-
-   protected override declareLanguage(): LanguageMetaData {
-      return __GRAMMAR__LanguageMetaData;
-   }
+   readonly diagramType = __GRAMMAR_ID_CONST___DIAGRAM_TYPE;
 
    protected override bindModelState(): BindingTarget<ModelState> {
       return { service: __GRAMMAR__GlspState };
@@ -1858,68 +1743,238 @@ export class __GRAMMAR__DiagramModule extends AbstractHydraniumGlspDiagramModule
 }
 `;
     return [
-        { path: `${dir}/types.ts`, content: render(types) },
-        { path: `${dir}/state.ts`, content: render(state) },
-        { path: `${dir}/storage.ts`, content: render(storage) },
-        { path: `${dir}/submission-handler.ts`, content: render(submission) },
-        { path: `${dir}/gmodel-factory.ts`, content: render(factory) },
-        { path: `${dir}/diagram-configuration.ts`, content: render(configuration) },
-        { path: `${dir}/create-node-operation-handler.ts`, content: render(createHandler) },
-        { path: `${dir}/diagram-module.ts`, content: render(module) }
+        fixed('state.ts'),
+        fixed('storage.ts'),
+        fixed('submission-handler.ts'),
+        fixed('gmodel-factory.ts'),
+        computed('diagram-configuration.ts', configuration),
+        fixed('create-node-operation-handler.ts'),
+        computed('diagram-module.ts', module),
+        grammarTemplate('server/test/__GRAMMAR_ID__-diagram.test.ts', composition, grammar)
     ];
 }
 /**
- * Every file the scaffold emits, fully rendered.
+ * The server member: the grammar, the language and its heads.
  *
  * Grammar-count-dependent emissions live here rather than in a template string:
  * one `.langium` file per grammar, and the shared `common.langium` fragment only
  * when there is more than one grammar to share it.
  */
-export function buildInitTemplates(composition) {
+function serverFiles(composition) {
     const multi = composition.grammars.length > 1;
     const grammarFiles = composition.grammars.map(grammar => ({
-        path: `src/grammar/${grammar.grammarId}.langium`,
+        path: `server/src/grammar/${grammar.grammarId}.langium`,
         content: render(grammarFile(multi), composition, grammar)
     }));
+    // The shared lexical fragment, only for several grammars: each declaring its
+    // own `WS` / `ID` lets the token sets drift apart.
     if (multi) {
-        grammarFiles.unshift({ path: 'src/grammar/common.langium', content: COMMON_GRAMMAR });
+        grammarFiles.unshift(projectTemplate('server/src/grammar/common.langium', composition));
     }
     const diagramFiles = composition.grammars.filter(grammar => grammar.diagram).flatMap(grammar => glspFiles(composition, grammar));
     return [
-        { path: 'package.json', content: packageJson(composition) },
-        { path: 'langium-config.json', content: langiumConfig(composition) },
-        { path: 'tsconfig.json', content: tsconfigJson(composition) },
-        { path: 'tsconfig.test.json', content: TSCONFIG_TEST },
-        { path: 'vitest.config.ts', content: VITEST_CONFIG },
-        {
-            path: '.gitignore',
-            content: composition.packaging.workspace === undefined ? GITIGNORE : GITIGNORE_WORKSPACE_MEMBER
-        },
-        { path: 'README.md', content: readme(composition) },
+        { path: 'server/package.json', content: packageJson(composition) },
+        { path: 'server/langium-config.json', content: langiumConfig(composition) },
+        { path: 'server/tsconfig.json', content: serverTsconfigJson(composition) },
+        // `isolatedModules` is what makes this check agree with the transform that
+        // actually runs the tests. `npm test` is `typecheck:test && vitest run`, and
+        // vitest compiles each file on its own — a transform with no type
+        // information, which cannot tell a re-exported TYPE from a re-exported value.
+        // Without the flag `tsc` accepts `export { SomeType } from './x'` that the
+        // transform then emits as a real import of a symbol that does not exist at
+        // runtime, so the typecheck passes and the suite fails with a confusing
+        // missing-export.
+        projectTemplate('server/tsconfig.test.json', composition),
+        // Found by name, unlike `tsconfig.test.json`. Under vite 8, vitest's transform
+        // applies a tsconfig only to the files its own `include` lists, so without this
+        // a test declaring a decorated class fails to load.
+        projectTemplate('server/test/tsconfig.json', composition),
+        projectTemplate('server/vitest.config.ts', composition),
+        // Written for a workspace member too: its root may not ignore `lib/` (a `yo
+        // langium` root ignores `out/`), and a rule the root repeats costs nothing.
+        ignoreFile('server'),
+        { path: 'server/README.md', content: readme(composition) },
         ...grammarFiles,
-        { path: `src/language-server/${composition.projectId}-module.ts`, content: moduleFile(composition) },
-        { path: 'src/language-server/ast.ts', content: render(AST, composition, composition.grammars[0]) },
-        ...composition.grammars.map(grammar => ({
-            path: `src/language-server/${grammar.grammarId}-serializer.ts`,
-            content: render(SERIALIZER, composition, grammar)
-        })),
-        { path: 'src/index.ts', content: indexFile(composition) },
-        { path: 'src/services.ts', content: project(SERVICES, composition) },
-        { path: 'src/main.ts', content: mainFile(composition) },
-        ...(composition.heads.includes('data') ? [{ path: 'src/data-server-main.ts', content: dataServerMainFile(composition) }] : []),
-        ...(portCommandNames(composition).length ? [{ path: 'src/head-ports.ts', content: headPortsFile(composition) }] : []),
+        { path: `server/src/language-server/${composition.projectId}-module.ts`, content: moduleFile(composition) },
+        grammarTemplate('server/src/language-server/ast.ts', composition, composition.grammars[0]),
+        // Per grammar, because `services.serializer.Serializer` is a per-language slot
+        // and a serializer is grammar-shaped by definition. That is also why the
+        // framework refuses to default it: its `UnboundSerializer` throws, naming the
+        // binding to add, rather than guessing a syntax.
+        ...composition.grammars.map(grammar => grammarTemplate('server/src/language-server/__GRAMMAR_ID__-serializer.ts', composition, grammar)),
+        { path: 'server/src/index.ts', content: indexFile(composition) },
+        projectTemplate('server/src/node/services.ts', composition),
+        { path: 'server/src/main.ts', content: mainFile(composition) },
+        ...(composition.heads.includes('data') ? [{ path: 'server/src/data-server-main.ts', content: dataServerMainFile(composition) }] : []),
         ...diagramFiles,
-        { path: 'test/services.test.ts', content: servicesTest(composition) },
-        { path: 'test/parsing.test.ts', content: grammarTest(composition, PARSING_HEADER, [], PARSING_SUITE) },
+        { path: 'server/test/services.test.ts', content: servicesTest(composition) },
+        { path: 'server/test/parsing.test.ts', content: grammarTest(composition, PARSING_HEADER, [], PARSING_SUITE) },
         {
-            path: 'test/linking.test.ts',
+            path: 'server/test/linking.test.ts',
             content: grammarTest(composition, LINKING_HEADER, ["import { AstUtils } from '@hydranium/langium';"], LINKING_SUITE)
         },
         {
-            path: 'test/validating.test.ts',
+            path: 'server/test/validating.test.ts',
             content: grammarTest(composition, VALIDATING_HEADER, ["import { DiagnosticSeverity } from 'vscode-languageserver';"], VALIDATING_SUITE)
         },
-        { path: 'test/serialization.test.ts', content: serializationTest(composition) }
+        { path: 'server/test/serialization.test.ts', content: serializationTest(composition) }
+    ];
+}
+/**
+ * The protocol member's `package.json`.
+ *
+ * Its `build` runs the server's `generate` first, because the server writes
+ * this package's `generated-hydranium/` modules from the grammar: a runner that
+ * builds in dependency order reaches this package before the server, and would
+ * otherwise compile modules that do not exist yet. A full build therefore
+ * generates twice; the second pass rewrites nothing.
+ */
+function protocolPackageJson(composition) {
+    const member = forMember(composition, 'protocol');
+    const dependencies = {};
+    for (const head of composition.heads) {
+        Object.assign(dependencies, PROTOCOL_THIRD_PARTY_DEPENDENCIES[head]);
+    }
+    const dependencyLines = Object.keys(dependencies).length === 0 ? '' : `  "dependencies": {\n${sortedBlock(dependencies, '    ')}\n  },\n`;
+    return `{
+  "name": "${memberPackageName(composition, 'protocol')}",
+  "version": "0.0.0",
+${composition.packaging.private ? '  "private": true,\n' : ''}  "description": "What the ${composition.name} language server and its clients share: language ids, wire types and diagram ids.",
+  "license": "UNLICENSED",
+  "author": "",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "npm --prefix ../server run generate && tsc -b",
+    "clean": "rimraf lib tsconfig.tsbuildinfo",
+${lintScript(member, 'src')}    "watch": "tsc -b --watch"
+  },
+${dependencyLines}  "devDependencies": {
+    "rimraf": "^5.0.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=22.13"
+  }
+}
+`;
+}
+/** The protocol member's root entry, one re-export per module. */
+function protocolIndexFile(composition) {
+    const modules = [
+        './generated-hydranium/languages.js',
+        './generated-hydranium/transfer-model.js',
+        ...(headPortConstants(composition).length ? ['./head-ports.js'] : []),
+        ...composition.grammars.filter(grammar => grammar.diagram).map(grammar => `./${grammar.grammarId}-diagram-types.js`)
+    ];
+    const text = `// What the __NAME__ server and its clients both import. A client depends on
+// this package instead of the server, so it never installs Langium to reach a
+// constant or a wire type.
+//
+// The server's \`generate\` writes \`generated-hydranium/\` from the grammar;
+// commit those modules with the grammar change that produced them.
+
+${modules.map(module => `export * from '${module}';`).join('\n')}
+`;
+    return project(text, composition);
+}
+/** The protocol member's README. */
+function protocolReadme(composition) {
+    const lines = [
+        `# ${memberPackageName(composition, 'protocol')}`,
+        '',
+        'What the __NAME__ language server and its clients both import, so a client',
+        'never depends on the server or installs Langium.',
+        '',
+        '- `src/generated-hydranium/languages.ts` — each language id and its file extensions',
+        '- `src/generated-hydranium/transfer-model.ts` — the wire types of the model, references as plain strings',
+        ...(headPortConstants(composition).length === 0
+            ? []
+            : composition.heads.includes('lsp')
+                ? ['- `src/head-ports.ts` — the LSP requests a host sends to find the socket heads']
+                : ["- `src/head-ports.ts` — the environment variables naming the socket heads' ports"]),
+        ...composition.grammars
+            .filter(grammar => grammar.diagram)
+            .map(grammar => `- \`src/${grammar.grammarId}-diagram-types.ts\` — the \`${grammar.grammar}\` diagram's type ids`),
+        '',
+        "The server's `npm run generate` writes `src/generated-hydranium/` from the",
+        'grammar, and `npm run build` here runs it first. Commit the generated',
+        'modules with the grammar change that produced them.',
+        ''
+    ];
+    return project(lines.join('\n'), composition);
+}
+/** The protocol member: everything the server and its clients both import. */
+function protocolFiles(composition) {
+    return [
+        { path: 'protocol/package.json', content: protocolPackageJson(composition) },
+        { path: 'protocol/tsconfig.json', content: tsconfigJson(forMember(composition, 'protocol'), PROTOCOL_COMPILER_OPTIONS, '["src"]') },
+        ignoreFile('protocol'),
+        { path: 'protocol/README.md', content: protocolReadme(composition) },
+        { path: 'protocol/src/index.ts', content: protocolIndexFile(composition) },
+        ...(headPortConstants(composition).length ? [{ path: 'protocol/src/head-ports.ts', content: headPortsFile(composition) }] : []),
+        ...composition.grammars
+            .filter(grammar => grammar.diagram)
+            .map(grammar => grammarTemplate('protocol/src/__GRAMMAR_ID__-diagram-types.ts', composition, grammar))
+    ];
+}
+/**
+ * The starter model files every host and the CLI open, two per language: one
+ * declaring nodes, one referencing a node in the other file.
+ *
+ * Named by extension alone, since `init` refuses two grammars sharing one.
+ */
+function workspaceFiles(composition) {
+    return composition.grammars.flatMap(grammar => [
+        grammarTemplate('workspace/nodes.__EXTENSION__', composition, grammar),
+        grammarTemplate('workspace/references.__EXTENSION__', composition, grammar)
+    ]);
+}
+/**
+ * A standalone project's root: the members as npm workspaces.
+ *
+ * Always private: it is never published, whatever `--public` makes of the
+ * members. npm runs a script across the members in the order listed here, not
+ * by their dependencies; listing protocol first is safe because its `build`
+ * runs the server's `generate` before compiling.
+ */
+function rootFiles(composition) {
+    const content = `{
+  "name": "${composition.projectId}-root",
+  "version": "0.0.0",
+  "private": true,
+  "workspaces": [
+    "protocol",
+    "server"
+  ],
+  "scripts": {
+    "build": "npm run build --workspaces",
+    "clean": "npm run clean --workspaces --if-present",
+    "test": "npm test --workspaces --if-present"
+  },
+  "engines": {
+    "node": ">=22.13"
+  }
+}
+`;
+    return [{ path: 'package.json', content }, ignoreFile('')];
+}
+/**
+ * Every file the scaffold emits, fully rendered, at its path in the project
+ * directory. A workspace member's project gets no root of its own: it joins the
+ * surrounding workspace, whose manifest `init` prints the changes for.
+ */
+export function buildInitTemplates(composition) {
+    return [
+        ...(composition.packaging.workspace === undefined ? rootFiles(composition) : []),
+        ...protocolFiles(composition),
+        ...serverFiles(composition),
+        ...workspaceFiles(composition)
     ];
 }
 //# sourceMappingURL=init-templates.js.map