@hydranium/core 1.0.0-next.28 → 1.0.0-next.280

package/lib/langium/scope/scope-extension-service.d.ts

@@ -6,9 +6,9 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { type AstNode, type LangiumDocument, type Scope } from '@hydranium/langium';
+import { type AstNode, type LangiumDocument } from '@hydranium/langium';
 import { type Disposable } from 'vscode-languageserver';
-import { type Tracer } from '@hydranium/protocol';
+import { type ProfileRecord, type ProfileSession, type Tracer } from '@hydranium/protocol';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type ServerLanguageServices } from '../language-module.js';
 import { Registry, type RegistryItem } from '../../util/registry.js';
@@ -54,8 +54,7 @@ export interface ScopeDescriptionAcceptor {
      * descriptions are constructed ahead of time, to avoid per-query
      * allocation. The pushed description's `tier` must be `'local'` or
      * `'universal'`; a description of any other tier is silently dropped,
-     * because the per-tier query methods only return descriptions matching
-     * the tier they were asked for.
+     * because {@link ScopeExtensionDescriptions} holds only those two.
      */
     push(description: TieredAstNodeDescription): void;
 }
@@ -78,34 +77,25 @@ export interface ScopeExtension extends RegistryItem {
      */
     addDescriptions(context: AstNode, referenceType: string, document: LangiumDocument, accept: ScopeDescriptionAcceptor): void;
 }
+/** The scope-extension descriptions for one reference, split by tier. */
+export interface ScopeExtensionDescriptions {
+    readonly local: readonly TieredAstNodeDescription[];
+    readonly universal: readonly TieredAstNodeDescription[];
+}
 /**
  * Public contract for the per-language scope-extension service. Extends
  * the {@link ScopeExtensionRegistry} (the imperative `register` surface
- * contributions use) with the per-tier query methods called cross-class
- * from `HydraniumScopeProvider`'s `layerLocalExtension` /
- * `layerUniversalExtension` helpers, which layer scope-extension
- * contributions around the cached project chain.
- *
- * Adopter overrides go through {@link DefaultScopeExtensionService}; the
- * interface keeps the public API stable while internals
- * (`collectExtensionDescriptions` walk) stay `protected` on the default
- * class.
+ * contributions use) with the query `HydraniumScopeProvider` builds its
+ * extension tiers from.
  */
 export interface ScopeExtensionService extends ScopeExtensionRegistry {
     /**
-     * Layer this language's `local`-tier scope-extension descriptions on
-     * top of `outerScope` for the given reference type. Returns
-     * `outerScope` unchanged when no extension contributes a `local`-tier
-     * description for the type (zero-cost common path).
+     * Run every extension registered for `referenceType` once against
+     * `context`, and answer its descriptions by tier. A caller that needs
+     * both tiers takes them from one call: a call per tier runs every
+     * extension twice.
      */
-    getLocalExtensionScope(referenceType: string, context: AstNode, outerScope: Scope): Scope;
-    /**
-     * Layer this language's `universal`-tier scope-extension descriptions
-     * BELOW `outerScope` for the given reference type. Returns `outerScope`
-     * unchanged when no extension contributes a `universal`-tier
-     * description for the type.
-     */
-    getUniversalExtensionScope(referenceType: string, context: AstNode, outerScope: Scope): Scope;
+    getDescriptions(referenceType: string, context: AstNode): ScopeExtensionDescriptions;
 }
 export type ScopeExtensionServiceOptions = LogNameOptions;
 /**
@@ -117,14 +107,20 @@ export type ScopeExtensionServiceOptions = LogNameOptions;
  * separate from the query-time scope-resolution concern (which only reads).
  *
  * Lives in the per-language `references` group alongside `ScopeProvider`,
- * which consumes the per-tier query methods ({@link getLocalExtensionScope}
- * / {@link getUniversalExtensionScope}). Designed as a base class; adopters
+ * which consumes {@link getDescriptions}. Designed as a base class; adopters
  * extend it and call `register` in their constructor.
+ *
+ * At `debug`, each extension's calls and self-time go into one profile
+ * session, reported when a build starts and when it ends. A report thus
+ * covers one build, validation included, or the calls made between two
+ * builds, such as a reference picker's.
  */
 export declare class DefaultScopeExtensionService implements ScopeExtensionService {
     protected readonly services: ServerLanguageServices;
     protected readonly scopeExtensions: Registry<ScopeExtension>;
     protected readonly tracer: Tracer;
+    /** Open from the first profiled call until {@link reportProfile}. */
+    protected profileSession?: ProfileSession;
     constructor(services: ServerLanguageServices, options?: ScopeExtensionServiceOptions);
     /**
      * Register a single scope extension. Doubles as the imperative low-level
@@ -133,17 +129,25 @@ export declare class DefaultScopeExtensionService implements ScopeExtensionServi
      * contributions. Throws on duplicate id.
      */
     register(extension: ScopeExtension): Disposable;
-    getLocalExtensionScope(referenceType: string, context: AstNode, outerScope: Scope): Scope;
-    getUniversalExtensionScope(referenceType: string, context: AstNode, outerScope: Scope): Scope;
     /**
-     * Walk this language's registered scope extensions matching
-     * `referenceType` and collect descriptions of the requested `tier`.
-     * `push`-ed descriptions of other tiers are silently dropped here —
-     * the per-tier query methods only return descriptions matching their
-     * tier. (`local` and `universal` are the only acceptor entry points;
-     * `push` is the escape hatch for pre-built descriptions and is the
-     * only path that could carry other tiers.)
+     * Holds the profile wrap, which an override would have to copy; to change
+     * which extensions run, override {@link extensionsFor}.
+     */
+    getDescriptions(referenceType: string, context: AstNode): ScopeExtensionDescriptions;
+    /** The extensions that run for one reference: by default, those registered for `referenceType`. */
+    protected extensionsFor(referenceType: string, _context: AstNode): ScopeExtension[];
+    /**
+     * Report the profile session, if one is open, and start the next one fresh:
+     * one line per extension, its calls and self-time. Not a share of the
+     * session's time, which runs from the first call to the report and so takes
+     * in whatever happened between the calls.
+     */
+    protected reportProfile(): void;
+    /**
+     * The log line of one extension's {@link reportProfile} entry. It names the
+     * language: each has its own session, and an extension id is unique only
+     * within its language.
      */
-    protected collectExtensionDescriptions(referenceType: string, context: AstNode, tier: 'local' | 'universal'): TieredAstNodeDescription[];
+    protected formatProfileRecord(record: ProfileRecord): string;
 }
 //# sourceMappingURL=scope-extension-service.d.ts.map

package/lib/langium/scope/scope-extension-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope-extension-service.d.ts","sourceRoot":"","sources":["../../../src/langium/scope/scope-extension-service.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,OAAO,EAAY,KAAK,eAAe,EAAY,KAAK,KAAK,EAAuB,MAAM,oBAAoB,CAAC;AAC7H,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAErE,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAChF,OAAO,EAAE,KAAK,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,wBAAwB;IACtC,KAAK,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,eAAe,CAAA;KAAE,GAAG,IAAI,CAAC;IACjF,SAAS,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,eAAe,CAAA;KAAE,GAAG,IAAI,CAAC;IACrF;;;;;;;OAOG;IACH,IAAI,CAAC,WAAW,EAAE,wBAAwB,GAAG,IAAI,CAAC;CACpD;AAcD;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,YAAY;IACjD,qEAAqE;IACrE,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;IAClC;;;;;;;OAOG;IACH,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,wBAAwB,GAAG,IAAI,CAAC;CAC9H;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAsB,SAAQ,sBAAsB;IAClE;;;;;OAKG;IACH,sBAAsB,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,GAAG,KAAK,CAAC;IAC1F;;;;;OAKG;IACH,0BAA0B,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,GAAG,KAAK,CAAC;CAChG;AAED,MAAM,MAAM,4BAA4B,GAAG,cAAc,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,qBAAa,4BAA6B,YAAW,qBAAqB;IAKpE,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB;IAJtD,SAAS,CAAC,QAAQ,CAAC,eAAe,2BAAkC;IACpE,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGZ,QAAQ,EAAE,sBAAsB,EACnD,OAAO,GAAE,4BAAiC;IAc7C;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,cAAc,GAAG,UAAU;IAI/C,sBAAsB,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,GAAG,KAAK;IAQzF,0BAA0B,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,GAAG,KAAK;IAQ7F;;;;;;;;OAQG;IACH,SAAS,CAAC,4BAA4B,CACnC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,OAAO,GAAG,WAAW,GAC3B,wBAAwB,EAAE;CAa/B"}
+{"version":3,"file":"scope-extension-service.d.ts","sourceRoot":"","sources":["../../../src/langium/scope/scope-extension-service.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,OAAO,EAAY,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAkB,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC3G,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAErE,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAChF,OAAO,EAAE,KAAK,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,wBAAwB;IACtC,KAAK,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,eAAe,CAAA;KAAE,GAAG,IAAI,CAAC;IACjF,SAAS,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,eAAe,CAAA;KAAE,GAAG,IAAI,CAAC;IACrF;;;;;;OAMG;IACH,IAAI,CAAC,WAAW,EAAE,wBAAwB,GAAG,IAAI,CAAC;CACpD;AAcD;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,YAAY;IACjD,qEAAqE;IACrE,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;IAClC;;;;;;;OAOG;IACH,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,wBAAwB,GAAG,IAAI,CAAC;CAC9H;AAED,yEAAyE;AACzE,MAAM,WAAW,0BAA0B;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACpD,QAAQ,CAAC,SAAS,EAAE,SAAS,wBAAwB,EAAE,CAAC;CAC1D;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAsB,SAAQ,sBAAsB;IAClE;;;;;OAKG;IACH,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,0BAA0B,CAAC;CACvF;AAED,MAAM,MAAM,4BAA4B,GAAG,cAAc,CAAC;AAI1D;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,4BAA6B,YAAW,qBAAqB;IAOpE,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB;IANtD,SAAS,CAAC,QAAQ,CAAC,eAAe,2BAAkC;IACpE,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAClC,qEAAqE;IACrE,SAAS,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IAE1C,YACsB,QAAQ,EAAE,sBAAsB,EACnD,OAAO,GAAE,4BAAiC,EAgB5C;IAED;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,cAAc,GAAG,UAAU,CAE9C;IAED;;;OAGG;IACH,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,0BAA0B,CAoBnF;IAED,mGAAmG;IACnG,SAAS,CAAC,aAAa,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,cAAc,EAAE,CAElF;IAED;;;;;OAKG;IACH,SAAS,CAAC,aAAa,IAAI,IAAI,CAM9B;IAED;;;;OAIG;IACH,SAAS,CAAC,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAG3D;CACH"}

package/lib/langium/scope/scope-extension-service.js

@@ -6,7 +6,8 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { AstUtils, MapScope, StreamScope, stream } from '@hydranium/langium';
+import { AstUtils } from '@hydranium/langium';
+import { Format, Logger } from '@hydranium/protocol';
 import { Registry } from '../../util/registry.js';
 /** Build a {@link ScopeDescriptionAcceptor} that synthesises typed descriptions via `descriptions` and accumulates them into `into`. */
 function createScopeDescriptionAcceptor(into, descriptions) {
@@ -16,6 +17,7 @@ function createScopeDescriptionAcceptor(into, descriptions) {
         push: description => into.push(description)
     };
 }
+const NO_DESCRIPTIONS = { local: [], universal: [] };
 /**
  * Default {@link ScopeExtensionService} implementation. Per-language
  * registry for dynamic scope contributions: extra resolvable descriptions
@@ -25,14 +27,20 @@ function createScopeDescriptionAcceptor(into, descriptions) {
  * separate from the query-time scope-resolution concern (which only reads).
  *
  * Lives in the per-language `references` group alongside `ScopeProvider`,
- * which consumes the per-tier query methods ({@link getLocalExtensionScope}
- * / {@link getUniversalExtensionScope}). Designed as a base class; adopters
+ * which consumes {@link getDescriptions}. Designed as a base class; adopters
  * extend it and call `register` in their constructor.
+ *
+ * At `debug`, each extension's calls and self-time go into one profile
+ * session, reported when a build starts and when it ends. A report thus
+ * covers one build, validation included, or the calls made between two
+ * builds, such as a reference picker's.
  */
 export class DefaultScopeExtensionService {
     services;
     scopeExtensions = new Registry();
     tracer;
+    /** Open from the first profiled call until {@link reportProfile}. */
+    profileSession;
     constructor(services, options = {}) {
         this.services = services;
         this.tracer = services.shared.Tracer.for(options.logName ?? 'ScopeExtension').trace('instantiated');
@@ -44,6 +52,10 @@ export class DefaultScopeExtensionService {
         for (const contribution of Object.values(contributions)) {
             contribution.registerScopeExtensions(this);
         }
+        // Optional for the same reason: a stub tree may carry no builder.
+        const builder = services.shared.workspace.DocumentBuilder;
+        builder?.onUpdate(() => this.reportProfile());
+        builder?.onBuildEnded(() => this.reportProfile());
     }
     /**
      * Register a single scope extension. Doubles as the imperative low-level
@@ -54,41 +66,57 @@ export class DefaultScopeExtensionService {
     register(extension) {
         return this.scopeExtensions.register(extension);
     }
-    getLocalExtensionScope(referenceType, context, outerScope) {
-        const local = this.collectExtensionDescriptions(referenceType, context, 'local');
-        if (local.length === 0) {
-            return outerScope;
-        }
-        return new StreamScope(stream(local), outerScope);
-    }
-    getUniversalExtensionScope(referenceType, context, outerScope) {
-        const universal = this.collectExtensionDescriptions(referenceType, context, 'universal');
-        if (universal.length === 0) {
-            return outerScope;
-        }
-        return new StreamScope(outerScope.getAllElements(), new MapScope(universal));
-    }
     /**
-     * Walk this language's registered scope extensions matching
-     * `referenceType` and collect descriptions of the requested `tier`.
-     * `push`-ed descriptions of other tiers are silently dropped here —
-     * the per-tier query methods only return descriptions matching their
-     * tier. (`local` and `universal` are the only acceptor entry points;
-     * `push` is the escape hatch for pre-built descriptions and is the
-     * only path that could carry other tiers.)
+     * Holds the profile wrap, which an override would have to copy; to change
+     * which extensions run, override {@link extensionsFor}.
      */
-    collectExtensionDescriptions(referenceType, context, tier) {
-        const extensionsForType = this.scopeExtensions.all().filter(extension => extension.referenceTypes.includes(referenceType));
+    getDescriptions(referenceType, context) {
+        const extensionsForType = this.extensionsFor(referenceType, context);
         if (extensionsForType.length === 0) {
-            return [];
+            return NO_DESCRIPTIONS;
         }
         const document = AstUtils.getDocument(context);
         const collected = [];
         const accept = createScopeDescriptionAcceptor(collected, this.services.workspace.AstNodeDescriptionProvider);
+        const session = Logger.isLevelEnabled('debug') ? (this.profileSession ??= this.tracer.profile('scope-extension')) : undefined;
         for (const extension of extensionsForType) {
-            extension.addDescriptions(context, referenceType, document, accept);
+            if (session) {
+                session.scope(extension.id, () => extension.addDescriptions(context, referenceType, document, accept));
+            }
+            else {
+                extension.addDescriptions(context, referenceType, document, accept);
+            }
         }
-        return collected.filter(description => description.tier === tier);
+        return {
+            local: collected.filter(description => description.tier === 'local'),
+            universal: collected.filter(description => description.tier === 'universal')
+        };
+    }
+    /** The extensions that run for one reference: by default, those registered for `referenceType`. */
+    extensionsFor(referenceType, _context) {
+        return this.scopeExtensions.all().filter(extension => extension.referenceTypes.includes(referenceType));
+    }
+    /**
+     * Report the profile session, if one is open, and start the next one fresh:
+     * one line per extension, its calls and self-time. Not a share of the
+     * session's time, which runs from the first call to the report and so takes
+     * in whatever happened between the calls.
+     */
+    reportProfile() {
+        const session = this.profileSession;
+        this.profileSession = undefined;
+        for (const record of session?.records() ?? []) {
+            this.tracer.debug(this.formatProfileRecord(record));
+        }
+    }
+    /**
+     * The log line of one extension's {@link reportProfile} entry. It names the
+     * language: each has its own session, and an extension id is unique only
+     * within its language.
+     */
+    formatProfileRecord(record) {
+        const language = this.services.LanguageMetaData.languageId;
+        return `[profile scope-extension ${language}] ${record.id} ×${record.count} ${Format.elapsed(record.selfMs)}`;
     }
 }
 //# sourceMappingURL=scope-extension-service.js.map

package/lib/langium/scope/scope-extension-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"scope-extension-service.js","sourceRoot":"","sources":["../../../src/langium/scope/scope-extension-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scope-extension-service.js","sourceRoot":"","sources":["../../../src/langium/scope/scope-extension-service.ts"],"names":[],"mappings":"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"}

package/lib/langium/scope/scoped-ast-node-description.d.ts

@@ -144,9 +144,7 @@ export declare function isUniversalTier(description: AstNodeDescription): descri
  * URI's project, the public-tier sibling belonging to that
  * same project is redundant (the project-tier sibling under a shorter
  * name is already in scope) and should be hidden from completion /
- * linking. The framework's
- * `HydraniumScopeProvider.bucketFor` uses this
- * predicate to enforce the own-project canonical filter on the typed scope path.
+ * linking.
  *
  * `projectId` accepts `string | undefined` for adopter-call-site
  * ergonomics: when the source has no resolvable project (standalone

package/lib/langium/scope/scoped-ast-node-description.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scoped-ast-node-description.d.ts","sourceRoot":"","sources":["../../../src/langium/scope/scoped-ast-node-description.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE3E;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAyB,SAAQ,kBAAkB;IACjE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,kBAAkB,GAAG,WAAW,IAAI,wBAAwB,CAE5G;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,kBAAkB,GAAG,WAAW,IAAI,wBAAwB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAEjI;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC1B,WAAW,EAAE,kBAAkB,GAC/B,WAAW,IAAI,wBAAwB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAEpG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CACzB,WAAW,EAAE,kBAAkB,GAC/B,WAAW,IAAI,wBAAwB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAEnG;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,kBAAkB,GAAG,WAAW,IAAI,wBAAwB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAEzI;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CACxB,WAAW,EAAE,kBAAkB,EAC/B,SAAS,EAAE,MAAM,GAAG,SAAS,GAC7B,WAAW,IAAI,wBAAwB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAEnG"}
+{"version":3,"file":"scoped-ast-node-description.d.ts","sourceRoot":"","sources":["../../../src/langium/scope/scoped-ast-node-description.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE3E;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAyB,SAAQ,kBAAkB;IACjE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,kBAAkB,GAAG,WAAW,IAAI,wBAAwB,CAE5G;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,kBAAkB,GAAG,WAAW,IAAI,wBAAwB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAEjI;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC1B,WAAW,EAAE,kBAAkB,GAC/B,WAAW,IAAI,wBAAwB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAEpG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CACzB,WAAW,EAAE,kBAAkB,GAC/B,WAAW,IAAI,wBAAwB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAEnG;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,kBAAkB,GAAG,WAAW,IAAI,wBAAwB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAEzI;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CACxB,WAAW,EAAE,kBAAkB,EAC/B,SAAS,EAAE,MAAM,GAAG,SAAS,GAC7B,WAAW,IAAI,wBAAwB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAEnG"}

package/lib/langium/scope/scoped-ast-node-description.js

@@ -83,9 +83,7 @@ export function isUniversalTier(description) {
  * URI's project, the public-tier sibling belonging to that
  * same project is redundant (the project-tier sibling under a shorter
  * name is already in scope) and should be hidden from completion /
- * linking. The framework's
- * `HydraniumScopeProvider.bucketFor` uses this
- * predicate to enforce the own-project canonical filter on the typed scope path.
+ * linking.
  *
  * `projectId` accepts `string | undefined` for adopter-call-site
  * ergonomics: when the source has no resolvable project (standalone

package/lib/langium/scope/scoped-ast-node-description.js.map

@@ -1 +1 @@
-{"version":3,"file":"scoped-ast-node-description.js","sourceRoot":"","sources":["../../../src/langium/scope/scoped-ast-node-description.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAkElF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAA+B;IAChE,OAAO,OAAQ,WAAwC,CAAC,IAAI,KAAK,QAAQ,CAAC;AAC7E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,WAA+B;IACxD,OAAO,mBAAmB,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC,IAAI,KAAK,OAAO,CAAC;AAC3E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC1B,WAA+B;IAE/B,OAAO,mBAAmB,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC,IAAI,KAAK,SAAS,CAAC;AAC7E,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CACzB,WAA+B;IAE/B,OAAO,mBAAmB,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC,IAAI,KAAK,QAAQ,CAAC;AAC5E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,WAA+B;IAC5D,OAAO,mBAAmB,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC,IAAI,KAAK,WAAW,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,WAAW,CACxB,WAA+B,EAC/B,SAA6B;IAE7B,OAAO,SAAS,KAAK,SAAS,IAAI,YAAY,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC,SAAS,KAAK,SAAS,CAAC;AACtG,CAAC"}
+{"version":3,"file":"scoped-ast-node-description.js","sourceRoot":"","sources":["../../../src/langium/scope/scoped-ast-node-description.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAkElF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAA+B;IAChE,OAAO,OAAQ,WAAwC,CAAC,IAAI,KAAK,QAAQ,CAAC;AAC7E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,WAA+B;IACxD,OAAO,mBAAmB,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC,IAAI,KAAK,OAAO,CAAC;AAC3E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC1B,WAA+B;IAE/B,OAAO,mBAAmB,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC,IAAI,KAAK,SAAS,CAAC;AAC7E,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CACzB,WAA+B;IAE/B,OAAO,mBAAmB,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC,IAAI,KAAK,QAAQ,CAAC;AAC5E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,WAA+B;IAC5D,OAAO,mBAAmB,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC,IAAI,KAAK,WAAW,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,WAAW,CACxB,WAA+B,EAC/B,SAA6B;IAE7B,OAAO,SAAS,KAAK,SAAS,IAAI,YAAY,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC,SAAS,KAAK,SAAS,CAAC;AACtG,CAAC"}

package/lib/langium/serialization/abstract-serializer.d.ts

@@ -54,16 +54,6 @@ export interface AbstractSerializerOptions extends LogNameOptions {
      * the extra property carries a value.
      */
     readonly referenceWrapperTypes?: ReadonlyMap<string, string>;
-    /**
-     * Whether {@link AbstractSerializer.serializeAst} trims trailing whitespace
-     * from the final output (leading whitespace is always trimmed). Defaults to
-     * `true` — the conventional "no trailing blank lines" document shape. Set to
-     * `false` for grammars whose values may legitimately END the document with
-     * blank lines that must survive a round-trip — e.g. a multi-line block-scalar
-     * property (see `YamlSerializerOptions.blockScalarProperties`),
-     * where a trailing-trim would silently eat user-typed blank lines.
-     */
-    readonly trimTrailingWhitespace?: boolean;
 }
 /**
  * Abstract base for hand-written grammar-aware AST → text serializers.
@@ -97,8 +87,11 @@ export interface AbstractSerializerOptions extends LogNameOptions {
  * **Extension points** (override in a subclass):
  * - {@link serializeReferenceText} — extract the textual form of a
  *   cross-reference; defaults to the value's `$refText`.
+ * - {@link formatString} — quote a string, as a primitive or a reference, for
+ *   the grammar's string terminal; the one override for a grammar whose
+ *   terminal or value converter differs from Langium's default.
  * - {@link formatReferenceValue} — format a cross-reference value for emission;
- *   defaults to `JSON.stringify`.
+ *   defaults to {@link formatString}.
  * - {@link serializeCustomValue} — type-specific serialization for values
  *   that don't fit the generic paths. Runs after all reference detection, so
  *   references never reach this hook. Returns `undefined` to fall through to
@@ -110,6 +103,14 @@ export interface AbstractSerializerOptions extends LogNameOptions {
 export declare abstract class AbstractSerializer<TAst extends AstNode = AstNode, TTransfer extends TransferElement = TransferElement> implements Serializer<TAst, TTransfer> {
     protected readonly services: HydraniumLanguageServices;
     protected readonly options: AbstractSerializerOptions;
+    /**
+     * The escapes {@link formatString} writes, read through the subclass, so a
+     * grammar adding one overrides this table alone. Langium's
+     * `ValueConverter.convertString` decodes the short escapes here and reads
+     * any other escaped character as itself, which is how `\\` and `\"` read
+     * back, and why a `\u` escape would read back as `u`.
+     */
+    protected static readonly STRING_ESCAPES: ReadonlyMap<string, string>;
     protected readonly reflection: AstReflection;
     protected readonly tracer: Tracer;
     constructor(services: HydraniumLanguageServices, options?: AbstractSerializerOptions);
@@ -117,18 +118,19 @@ export declare abstract class AbstractSerializer<TAst extends AstNode = AstNode,
      * Entry point for AST-shape inputs. Typically the grammar root, but any
      * AST node works — the walker is recursive and shape-agnostic.
      *
-     * Preserves the sync fast path: when every subclass override and every
-     * adopter hook is sync, the return is a bare `string` (no Promise
-     * allocation, no microtask). The async branch fires only if at least one
-     * recursive `serializeNode` call resolved to a Promise.
+     * **Emits the model and nothing else — do not trim here.** Trailing
+     * whitespace belongs to the author, and a write path holding the prior
+     * document restores it from there; trimming at this end deletes it before
+     * that restore sees it. A serializer has no prior document to consult, so it
+     * cannot tell a deliberate blank line from an accidental one.
+     *
+     * **Nothing trims what a subclass emits**, at either end. Emitting leading
+     * whitespace therefore puts it in the file, where no write path removes it.
+     *
+     * Returns whatever `serializeNode` returns, so a fully sync subclass keeps a
+     * bare `string` with no promise allocation.
      */
     serializeAst(model: TAst): MaybePromise<string>;
-    /**
-     * Trim the final serialized output. Leading whitespace is always removed;
-     * trailing whitespace is removed unless {@link AbstractSerializerOptions.trimTrailingWhitespace}
-     * is `false` (which preserves document-ending blank lines, e.g. inside a block scalar).
-     */
-    protected trimSerialized(text: string | undefined): string;
     /**
      * Entry point for transfer-model-shape inputs (cross-references as plain
      * string ids rather than `Reference` objects).
@@ -280,9 +282,10 @@ export declare abstract class AbstractSerializer<TAst extends AstNode = AstNode,
      */
     protected getOrderedPropertyNames(node: AstNode | Record<string, unknown>, type: string): readonly string[];
     /**
-     * Format a cross-reference value for emission. Defaults to `JSON.stringify`.
-     * Override to apply language-specific reference quoting — e.g. an
-     * id-reference formatter that mirrors the grammar's id convention.
+     * Format a cross-reference value for emission. Defaults to
+     * {@link formatString}. Override to apply language-specific reference
+     * quoting — e.g. an id-reference formatter that mirrors the grammar's id
+     * convention.
      *
      * Returns {@link MaybePromise} so adopters with async formatting needs
      * (remote schema lookup, external canonical-id resolution) can return a
@@ -290,15 +293,23 @@ export declare abstract class AbstractSerializer<TAst extends AstNode = AstNode,
      */
     protected formatReferenceValue(value: string): MaybePromise<string>;
     /**
-     * Format a primitive value (string, number, boolean) for emission. Defaults
-     * to `JSON.stringify`, which quotes strings, formats numbers/booleans, and
-     * is valid both as a YAML scalar and a JSON value.
+     * Format a primitive value (string, number, boolean) for emission. A string
+     * goes through {@link formatString}, any other value through
+     * `JSON.stringify`.
      *
      * Returns {@link MaybePromise} so adopters with async formatting needs
      * (e.g. delegating to `prettier.format` for a specific value class) can
      * return a `Promise<string>`.
      */
     protected formatPrimitive(value: unknown): MaybePromise<string>;
+    /**
+     * Quote a string, as a primitive or a reference, for its reader: the
+     * grammar's string terminal and value converter. Defaults to the inverse of
+     * Langium's default `STRING` terminal and converter: double quotes, `\` and
+     * `"` escaped, the converter's short escapes, every other character as it
+     * is. A grammar with another terminal or converter overrides this.
+     */
+    protected formatString(value: string): string;
     /**
      * Hook for type-specific serialization that doesn't fit the generic
      * dispatch table. Runs after all reference detection (steps 2-4 of

package/lib/langium/serialization/abstract-serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"abstract-serializer.d.ts","sourceRoot":"","sources":["../../../src/langium/serialization/abstract-serializer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"abstract-serializer.d.ts","sourceRoot":"","sources":["../../../src/langium/serialization/abstract-serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,MAAM,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3F,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,aAAa,EAAkC,MAAM,oBAAoB,CAAC;AACtG,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAYlD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,yBAA0B,SAAQ,cAAc;IAC9D;;;;;;;;;OASG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;IAChE;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,8BAAsB,kBAAkB,CACrC,IAAI,SAAS,OAAO,GAAG,OAAO,EAC9B,SAAS,SAAS,eAAe,GAAG,eAAe,CACpD,YAAW,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC;IAwBlC,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,yBAAyB;IACtD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,yBAAyB;IAxBxD;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAUlE;IAEH,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IAC7C,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAElC,YACsB,QAAQ,EAAE,yBAAyB,EACnC,OAAO,GAAE,yBAA8B,EAI5D;IAED;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,KAAK,EAAE,IAAI,GAAG,YAAY,CAAC,MAAM,CAAC,CAE9C;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,YAAY,CAAC,MAAM,CAAC,CAExD;IAED;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,QAAQ,CAAC,aAAa,CAC7B,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,gBAAgB,EAAE,MAAM,EACxB,cAAc,CAAC,EAAE,OAAO,GACxB,YAAY,CAAC,MAAM,CAAC,CAAC;IAExB,kEAAkE;IAClE,SAAS,CAAC,QAAQ,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAEnI,oGAAoG;IACpG,SAAS,CAAC,QAAQ,CAAC,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,gBAAgB,EAAE,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAE7G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,SAAS,CAAC,sBAAsB,CAC7B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,gBAAgB,EAAE,MAAM,EACxB,cAAc,UAAQ,GACtB,YAAY,CAAC,MAAM,GAAG,SAAS,CAAC,CAmDlC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,SAAS,CAAC,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAKnE;IAED;;;;;OAKG;IACH,SAAS,CAAC,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAcpF;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,CAAC,2BAA2B,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAkBvE;IAED;;;;;;OAMG;IACH,SAAS,CAAC,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAE1G;IAED;;;;;;;;;OASG;IACH,SAAS,CAAC,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAElE;IAED;;;;;;;;OAQG;IACH,SAAS,CAAC,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,CAE9D;IAED;;;;;;OAMG;IACH,SAAS,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG5C;IAED;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,oBAAoB,CAC3B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,EACf,iBAAiB,EAAE,MAAM,GACzB,YAAY,CAAC,MAAM,GAAG,SAAS,CAAC,CAElC;CACH"}

package/lib/langium/serialization/abstract-serializer.js

@@ -6,7 +6,6 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { isPromiseLike } from '@hydranium/protocol';
 import { isAstNode } from '@hydranium/langium';
 import { isDefaultValue, isReferenceProperty } from './serialization-util.js';
 function isRefTextObject(value) {
@@ -44,8 +43,11 @@ function isRefTextObject(value) {
  * **Extension points** (override in a subclass):
  * - {@link serializeReferenceText} — extract the textual form of a
  *   cross-reference; defaults to the value's `$refText`.
+ * - {@link formatString} — quote a string, as a primitive or a reference, for
+ *   the grammar's string terminal; the one override for a grammar whose
+ *   terminal or value converter differs from Langium's default.
  * - {@link formatReferenceValue} — format a cross-reference value for emission;
- *   defaults to `JSON.stringify`.
+ *   defaults to {@link formatString}.
  * - {@link serializeCustomValue} — type-specific serialization for values
  *   that don't fit the generic paths. Runs after all reference detection, so
  *   references never reach this hook. Returns `undefined` to fall through to
@@ -57,6 +59,24 @@ function isRefTextObject(value) {
 export class AbstractSerializer {
     services;
     options;
+    /**
+     * The escapes {@link formatString} writes, read through the subclass, so a
+     * grammar adding one overrides this table alone. Langium's
+     * `ValueConverter.convertString` decodes the short escapes here and reads
+     * any other escaped character as itself, which is how `\\` and `\"` read
+     * back, and why a `\u` escape would read back as `u`.
+     */
+    static STRING_ESCAPES = new Map([
+        ['\\', '\\\\'],
+        ['"', '\\"'],
+        ['\b', '\\b'],
+        ['\f', '\\f'],
+        ['\n', '\\n'],
+        ['\r', '\\r'],
+        ['\t', '\\t'],
+        ['\v', '\\v'],
+        ['\0', '\\0']
+    ]);
     reflection;
     tracer;
     constructor(services, options = {}) {
@@ -69,28 +89,20 @@ export class AbstractSerializer {
      * Entry point for AST-shape inputs. Typically the grammar root, but any
      * AST node works — the walker is recursive and shape-agnostic.
      *
-     * Preserves the sync fast path: when every subclass override and every
-     * adopter hook is sync, the return is a bare `string` (no Promise
-     * allocation, no microtask). The async branch fires only if at least one
-     * recursive `serializeNode` call resolved to a Promise.
+     * **Emits the model and nothing else — do not trim here.** Trailing
+     * whitespace belongs to the author, and a write path holding the prior
+     * document restores it from there; trimming at this end deletes it before
+     * that restore sees it. A serializer has no prior document to consult, so it
+     * cannot tell a deliberate blank line from an accidental one.
+     *
+     * **Nothing trims what a subclass emits**, at either end. Emitting leading
+     * whitespace therefore puts it in the file, where no write path removes it.
+     *
+     * Returns whatever `serializeNode` returns, so a fully sync subclass keeps a
+     * bare `string` with no promise allocation.
      */
     serializeAst(model) {
-        const result = this.serializeNode(model, 0);
-        if (isPromiseLike(result)) {
-            return result.then(text => this.trimSerialized(text));
-        }
-        return this.trimSerialized(result);
-    }
-    /**
-     * Trim the final serialized output. Leading whitespace is always removed;
-     * trailing whitespace is removed unless {@link AbstractSerializerOptions.trimTrailingWhitespace}
-     * is `false` (which preserves document-ending blank lines, e.g. inside a block scalar).
-     */
-    trimSerialized(text) {
-        if (text === undefined) {
-            return '';
-        }
-        return this.options.trimTrailingWhitespace === false ? text.trimStart() : text.trim();
+        return this.serializeNode(model, 0);
     }
     /**
      * Entry point for transfer-model-shape inputs (cross-references as plain
@@ -309,28 +321,40 @@ export class AbstractSerializer {
         return this.options.propertyOrder?.get(type) ?? Object.keys(node);
     }
     /**
-     * Format a cross-reference value for emission. Defaults to `JSON.stringify`.
-     * Override to apply language-specific reference quoting — e.g. an
-     * id-reference formatter that mirrors the grammar's id convention.
+     * Format a cross-reference value for emission. Defaults to
+     * {@link formatString}. Override to apply language-specific reference
+     * quoting — e.g. an id-reference formatter that mirrors the grammar's id
+     * convention.
      *
      * Returns {@link MaybePromise} so adopters with async formatting needs
      * (remote schema lookup, external canonical-id resolution) can return a
      * `Promise<string>`. Sync overrides remain valid.
      */
     formatReferenceValue(value) {
-        return JSON.stringify(value);
+        return this.formatString(value);
     }
     /**
-     * Format a primitive value (string, number, boolean) for emission. Defaults
-     * to `JSON.stringify`, which quotes strings, formats numbers/booleans, and
-     * is valid both as a YAML scalar and a JSON value.
+     * Format a primitive value (string, number, boolean) for emission. A string
+     * goes through {@link formatString}, any other value through
+     * `JSON.stringify`.
      *
      * Returns {@link MaybePromise} so adopters with async formatting needs
      * (e.g. delegating to `prettier.format` for a specific value class) can
      * return a `Promise<string>`.
      */
     formatPrimitive(value) {
-        return JSON.stringify(value);
+        return typeof value === 'string' ? this.formatString(value) : JSON.stringify(value);
+    }
+    /**
+     * Quote a string, as a primitive or a reference, for its reader: the
+     * grammar's string terminal and value converter. Defaults to the inverse of
+     * Langium's default `STRING` terminal and converter: double quotes, `\` and
+     * `"` escaped, the converter's short escapes, every other character as it
+     * is. A grammar with another terminal or converter overrides this.
+     */
+    formatString(value) {
+        const escapes = this.constructor.STRING_ESCAPES;
+        return `"${Array.from(value, char => escapes.get(char) ?? char).join('')}"`;
     }
     /**
      * Hook for type-specific serialization that doesn't fit the generic